Repository navigation
Conversation
Pin the modern-web-guidance catalog at 1.0.0 in references/tools.md and retrieve guides with DISABLE_TELEMETRY=1 so target-repo runs send no usage data. The install nudge now points at claude-plugins-official. CI retrieves every cited Guidance id at the pin and fails on any that no longer resolve, and check_invariants keeps the docs' commands on the same pin. The package requires Node 22, so the floor moves from 18 to 22 across engines, Doctor, CI (22 + 24) and the target-repo templates. The CI workflow token is now read-only.
| - uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: 20 | ||
| node-version: 22 |
There was a problem hiding this comment.
🟡 (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.
| ids=$( { grep -rhoE '^Guidance: [a-z0-9-]+' skills/browsergnome/references/knowledge | cut -d' ' -f2 | ||
| grep -oE '"guidance": "[a-z0-9-]+"' skills/browsergnome/assets/playbook.seed.json | cut -d'"' -f4; } | sort -u) |
There was a problem hiding this comment.
🟡 (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.
Description
Moves the modern-web-guidance integration to the stable 1.0.0 release.
modern-web-guidance@1.0.0inreferences/tools.md. Runtime retrieval inSKILL.mdandknowledge/INDEX.mdusesDISABLE_TELEMETRY=1 npx --yes modern-web-guidance@1.0.0 retrieve, so no telemetry is sent from target repos and nothing resolves to@latest.claude plugin install modern-web-guidance@claude-plugins-official.Guidance:id at the pin and fails if any doesn't resolve.check_invariants.mjsaddscheckGuidancePin()so the documented commands stay on the same pin.SKILL.mdnotes that guides over ~9.5 KB come back as asaved to <path>pointer.engines, Doctor, the CI matrix (22 + 24),pages.ymland the target-repo templates.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 testpasses on Node 22, including the newcheckGuidancePinself-tests and the real invariants run.QA
N/A
Checklist
Breaking Changeif it applies.package.json.Deploy notes
Dropping Node 18/20 is breaking for plugin users, so the next release should be 0.4.0.