[xavi-999]

Description

Moves the modern-web-guidance integration to the stable 1.0.0 release.

• Pins the catalog at modern-web-guidance@1.0.0 in references/tools.md. Runtime retrieval in SKILL.md and knowledge/INDEX.md uses DISABLE_TELEMETRY=1 npx --yes modern-web-guidance@1.0.0 retrieve, so no telemetry is sent from target repos and nothing resolves to @latest.
• Doctor and the docs now suggest claude plugin install modern-web-guidance@claude-plugins-official.
• CI retrieves every cited Guidance: id at the pin and fails if any doesn't resolve. check_invariants.mjs adds checkGuidancePin() so the documented commands stay on the same pin.
• SKILL.md notes that guides over ~9.5 KB come back as a saved to <path> pointer.
• Breaking: 1.0.0 requires Node ≥ 22, so the floor moves from 18 to 22 across engines, Doctor, the CI matrix (22 + 24), pages.yml and the target-repo templates.
• The CI workflow token is now contents: read, since the new step runs a third-party package.

None of the new 1.0.0 performance guides closely matches an existing knowledge entry, so no citations were added. The six existing ones all resolve at 1.0.0.

Related issues

N/A

Impacted areas

Doctor, the Autoresearch diagnose step, the knowledge base contract, CI, and the templates/ci/ workflows adopted in target repos.

Steps to reproduce or test

Development

• npm test passes on Node 22, including the new checkGuidancePin self-tests and the real invariants run.
• Ran the CI guidance step locally: all 6 ids resolve at 1.0.0, and an unknown id exits 1.

QA

N/A

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Dropping Node 18/20 is breaking for plugin users, so the next release should be 0.4.0.

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

[claude]

🟡 (optional) Adopters whose web repo still builds on Node 20 will have autopilot fail at npm ci or the build, or measure on a toolchain production does not use. The template's hardcoded node-version: 22 sets the Node for the target repo's own install and build, not just for modern-web-guidance. That guidance is optional: SKILL.md/INDEX.md fall back to guidance <id> not installed. Fix: let the target repo's declared Node win (node-version-file, for example .nvmrc or package.json, with 22 only as the default). Add a Setup note saying guidance needs Node ≥ 22. Same change at templates/ci/browsergnome-autopilot-browser.yml:58.

Why this was flagged

templates/ci/browsergnome-autopilot-build.yml:47-52 and browsergnome-autopilot-browser.yml:56-61 run actions/setup-node with a fixed node-version: 22, then - run: npm ci and the agent's build commands on the target repo's code. Repos copy these templates into .github/workflows/. A repo that pins Node 20 (for example "engines": {"node": "20.x"} with engine-strict=true in .npmrc, or a native dependency with no Node 22 prebuild) passes npm ci on the base template, which uses node-version: 20. After this change it fails EBADENGINE or a native build error, so no autopilot PR is opened. A repo that does not fail still gets its bundle and runtime measured on a Node it does not ship. The Node 22 floor exists only for npx modern-web-guidance@ 1.0.0. INDEX.md:64-66 ("Absent") and SKILL.md:253-256 already let a run continue without it. The template Setup comments (lines 6-16) and templates/ci/README.md say nothing about the Node change. Nothing checks the target repo's declared Node version.

Verification: In templates/ci/browsergnome-autopilot-build.yml:47-52, actions/setup-node@ v4 is now set to node-version: 22 (it was 20 at base), and right after it comes - run: npm ci on the checked-out target repo. Nothing in the template reads .nvmrc or node-version-file, so a repo pinned strictly to 20 that copies the new template fails at npm ci. That same repo worked with the base template.

[claude]

🟡 (optional) Maintainers can merge a malformed Guidance: citation that CI silently skips, even though INDEX.md:54 says CI fails if any cited id stops resolving. The extraction keeps only [a-z0-9-]+ values. So "guidance": "perf/optimize-image-priority" or an uppercase or _ id in playbook.seed.json never reaches retrieve. In knowledge/*.md, Guidance: Optimize-… or a line with extra spacing is also dropped. Fix: collect every Guidance: / "guidance" value in full (for example, read the JSON with node). Fail any value that is not a bare ^[a-z0-9-]+$ id, then retrieve the rest.

Why this was flagged

ci.yml:76 uses grep -rhoE '^Guidance: [a-z0-9-]+', and ci.yml:77 uses grep -oE '"guidance": "[a-z0-9-]+"' on skills/browsergnome/assets/playbook.seed.json. The seed is hand-authored (build_playbook.mjs:5), and its contract (INDEX.md:49-51, .claude/CLAUDE.md:130) forbids the category/id form. A JSON value with /, _, . or uppercase fails the regex, because it needs the closing quote right after the id. Compact "guidance":"x" formatting is skipped too. In the md files, a line that starts Guidance: followed by an uppercase letter, or Guidance: with two spaces, matches nothing. The only guard is test -n "$ids" (ci.yml:79), which fails only when no ids at all are found, so one skipped citation passes. On the base branch nothing checked citations. This step is the change's claimed replacement, and INDEX.md:53-54 and tools.md:94-95 now say every cited id is retrieved.

Verification: The step this PR adds to ci.yml only collects ids that match '^Guidance: [a-z0-9-]+' (line 76) and '"guidance": "[a-z0-9-]+"' in assets/playbook.seed.json (line 77). A seed value like "perf/optimize-image-priority" never reaches retrieve, so CI passes in silence. checkGuidancePin in check_invariants.mjs (lines 92-94) only checks version strings. The base had no check at all.