From ddebccdb4fae8558480ebcdc79cc04fb7cfeceaf Mon Sep 17 00:00:00 2001
From: Xavier Costa <xavier.costa@uphold.com>
Date: Wed, 11 Nov 2026 16:56:04 +0000
Subject: [PATCH 1/3] Update modern-web-guidance@1.0.0 and require Node 22

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.
---
 .github/workflows/ci.yml                      | 25 ++++++++++++++-
 .github/workflows/pages.yml                   |  2 +-
 AGENTS.md                                     |  2 +-
 CONTRIBUTING.md                               | 14 ++++----
 README.md                                     |  6 ++--
 package-lock.json                             |  2 +-
 package.json                                  |  2 +-
 skills/browsergnome/SKILL.md                  |  9 +++---
 .../references/knowledge/INDEX.md             | 14 ++++----
 skills/browsergnome/references/tools.md       | 12 +++++++
 .../browsergnome/scripts/check_invariants.mjs | 32 +++++++++++++++++--
 skills/browsergnome/scripts/doctor.mjs        |  4 +--
 .../ci/browsergnome-autopilot-browser.yml     |  2 +-
 templates/ci/browsergnome-autopilot-build.yml |  2 +-
 14 files changed, 96 insertions(+), 32 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a657e5f..cf17345 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -4,6 +4,8 @@
 #     build_perf_map --renders from the render-overlay fixture pair
 #   - JSON validation of all plugin manifests
 #   - official plugin manifest validation (claude plugin validate --strict)
+#   - every `Guidance:` id resolves at the pinned modern-web-guidance (the one networked step:
+#     it downloads the pinned package once)
 #
 # The live path (chrome-devtools-mcp / real browser / MCP runtime) cannot be CI-tested
 # because it requires a running Chrome instance and an active Claude Code session.
@@ -16,13 +18,17 @@ on:
   push:
     branches: [master]
 
+# Read-only token: the guidance step runs a third-party npm package, and checkout persists the token.
+permissions:
+  contents: read
+
 jobs:
   ci:
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x]
+        node-version: [22.x, 24.x]
 
     steps:
       - name: Checkout
@@ -60,6 +66,23 @@ jobs:
           test -s /tmp/perf-map.html    || (echo "perf-map.html is missing or empty"     && exit 1)
           grep -q '"renders":3' /tmp/perf-map.html || (echo "perf-map.html is missing the render overlay" && exit 1)
 
+      - name: Guidance ids resolve at the pinned modern-web-guidance
+        if: matrix.node-version == '22.x'
+        env:
+          DISABLE_TELEMETRY: 1
+        run: |
+          pin=$(grep -oE 'Pinned: `modern-web-guidance@[0-9]+\.[0-9]+\.[0-9]+' skills/browsergnome/references/tools.md | cut -d@ -f2)
+          test -n "$pin" || { echo "::error::no modern-web-guidance pin in references/tools.md"; exit 1; }
+          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)
+          test -n "$ids" || { echo "::error::found no Guidance ids to check"; exit 1; }
+          fail=0
+          for id in $ids; do
+            if npx --yes "modern-web-guidance@$pin" retrieve "$id" > /dev/null 2>&1; then echo "  ok  $id"
+            else echo "::error::Guidance id '$id' does not resolve at modern-web-guidance@$pin"; fail=1; fi
+          done
+          exit $fail
+
       - name: Validate JSON files
         run: |
           node -e "
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 7a266d7..27d3e33 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -48,7 +48,7 @@ jobs:
       - name: Set up Node.js 20
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Install dependencies
         run: npm ci
diff --git a/AGENTS.md b/AGENTS.md
index f0b615e..8e6e7e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,7 +64,7 @@ These have no single source of truth; an edit to one side silently breaks the ot
 - **Knowledge-base status tiers** (`proven` / `documented` / `ungated hypothesis` / `dead end`) in
   `references/knowledge/` require a real measured before/after to upgrade. A citation is not a
   measurement.
-- Node ≥ 18, ESM throughout. The only runtime deps are `@babel/parser` + `@babel/traverse`.
+- Node ≥ 22, ESM throughout. The only runtime deps are `@babel/parser` + `@babel/traverse`.
 
 ## Full detail
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 838a581..799cc5d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,7 +13,7 @@ cd browsergnome
 npm install   # @babel/parser + @babel/traverse, used only by perf_scan.mjs
 ```
 
-No build step. Node ≥ 18, ESM throughout.
+No build step. Node ≥ 22, ESM throughout.
 
 ## Running the tests
 
@@ -25,7 +25,7 @@ npm run invariants       # the invariants check itself (not a self-test — asse
                           #   files agree; see "Cross-file invariants" below)
 ```
 
-`ci.yml` runs this same `npm test` chain on Node 18 and 20 for every PR and push to `master` — the
+`ci.yml` runs this same `npm test` chain on Node 22 and 24 for every PR and push to `master` — the
 per-script `selfTest()`s aren't an untested side-channel, they gate merges.
 
 Each testable script carries its own `selfTest()` behind `--self-test`, with a local pass/fail-tally
@@ -54,11 +54,11 @@ have no other single source of truth and silently drift if only one side of an e
 
 `npm run invariants` (part of `npm test`) mechanically checks the chrome-devtools-mcp pin and its
 `--categoryExperimentalThirdParty` flag, the `react-devtools-cdt-mcp` pin, the stack-catalog filenames,
-the `depPulse`/`depPulseAutoApply`/`pageTools` config keys, and the Perf Map calibration SHA, and fails
-the build on drift. Two invariants stay a manual review responsibility,
-because a script can't meaningfully check them: the "one confident, unhedged voice" rule across
-product docs is editorial, not mechanical; and the `Guidance:` ids resolve against the external
-`modern-web-guidance` catalog, which isn't installed in CI.
+the `depPulse`/`depPulseAutoApply`/`pageTools` config keys, the Perf Map calibration SHA, and the
+`modern-web-guidance` pin, and fails the build on drift. A separate `ci.yml` step retrieves every
+`Guidance:` id at that pin and fails on any that don't resolve. One invariant stays a manual review
+responsibility: the "one confident, unhedged voice" rule across product docs is editorial, not
+mechanical.
 
 ## Proposing a change
 
diff --git a/README.md b/README.md
index 4b84084..c3781d4 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
 [![Forks](https://img.shields.io/github/forks/uphold/browsergnome?color=5b6472)](https://github.com/uphold/browsergnome/network/members)
 [![Issues](https://img.shields.io/github/issues/uphold/browsergnome?color=5b6472)](https://github.com/uphold/browsergnome/issues)
 [![Live demo](https://img.shields.io/badge/demo-live-E45FD8)](https://uphold.github.io/browsergnome/)
-[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-5b6472)](package.json)
+[![Node >=22](https://img.shields.io/badge/node-%3E%3D22-5b6472)](package.json)
 <!-- npm version / downloads: uncomment once published — not on npm yet, see Install.
 [![npm version](https://img.shields.io/npm/v/browsergnome?color=E45FD8)](https://www.npmjs.com/package/browsergnome)
 [![npm downloads](https://img.shields.io/npm/dm/browsergnome?color=5b6472)](https://www.npmjs.com/package/browsergnome)
@@ -68,7 +68,7 @@ capture, plus the live run report.
 /plugin install browsergnome
 ```
 
-**Prerequisites:** Node ≥ 18 · `chrome-devtools-mcp` · clean git tree.
+**Prerequisites:** Node ≥ 22 · `chrome-devtools-mcp` · clean git tree.
 
 **Scripts need `npm install`:** The SessionStart hook does this automatically inside a Claude session. For by-hand or CI use, run `npm install` in the plugin directory first.
 
@@ -208,7 +208,7 @@ trusting the gate on CI hardware.
 
 ## Requirements
 
-- **Node ≥ 18, ESM throughout.**
+- **Node ≥ 22, ESM throughout.**
 - **Measurement is delegated** to [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)
   (pinned in `.mcp.json`, launched with `--categoryExperimentalThirdParty`) — never called via `@latest`.
 - **Page Tools** (React targets) uses the pinned `react-devtools-cdt-mcp` dependency, installed by the
diff --git a/package-lock.json b/package-lock.json
index 491c3aa..3cf9119 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14,7 +14,7 @@
         "react-devtools-cdt-mcp": "0.1.0"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=22"
       }
     },
     "node_modules/@babel/code-frame": {
diff --git a/package.json b/package.json
index 7b645c5..ef6a43b 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,7 @@
   "bugs": "https://github.com/uphold/browsergnome/issues",
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
     "scan": "node skills/browsergnome/scripts/perf_scan.mjs",
diff --git a/skills/browsergnome/SKILL.md b/skills/browsergnome/SKILL.md
index 2d4c82f..e160d7a 100644
--- a/skills/browsergnome/SKILL.md
+++ b/skills/browsergnome/SKILL.md
@@ -207,7 +207,7 @@ check — it **cannot** verify the live tool surface, since that needs an actual
 returns an unexpected shape mid-run, that's the live-drift signal, not this check), git state (via
 `parseGitState` — four states: `usable`/`no-repo`/`no-commits`/`detached`), the three stack axes (framework/bundler/host — unknown on any axis is fine, falls back to
 the generic knowledge base), whether the `modern-web-guidance` plugin is installed (nudges
-`/plugin install modern-web-guidance@googlechrome` if not — see the Knowledge base section above), the
+`claude plugin install modern-web-guidance@claude-plugins-official` if not — see the Knowledge base section above), the
 Page Tools axis (providers detected from the target's `package.json` — `react` when it depends on
 `react-dom` — plus whether the provider package is installed, the target has a `dev` script, and
 `.mcp.json` passes `--categoryExperimentalThirdParty`), and target URL reachability if `--url` is
@@ -251,9 +251,10 @@ loop, condensed:
 3. **Diagnose.** Consult `references/knowledge/lcp.md` (routed by the trace's `LCPBreakdown` insight —
    TTFB-dominated vs render-delay-dominated point at different fixes). Pick the **single dominant**
    candidate fix — never stack fixes in one iteration. If it carries a `Guidance:` id, retrieve that
-   `modern-web-guidance` guide (`npx modern-web-guidance@latest retrieve "<id>"`, or the plugin's
-   equivalent skill call) when installed; otherwise proceed on the local entry and note
-   `guidance <id> not installed` on the finding. See `references/knowledge/INDEX.md`'s "Upstream
+   `modern-web-guidance` guide (`DISABLE_TELEMETRY=1 npx --yes modern-web-guidance@1.0.0 retrieve "<id>"`,
+   or the plugin's equivalent skill call) when installed; otherwise proceed on the local entry and note
+   `guidance <id> not installed` on the finding. A guide over ~9.5 KB prints only a `saved to <path>`
+   pointer — read that file, it is the guide. See `references/knowledge/INDEX.md`'s "Upstream
    guidance" section for the full contract.
 4. **Propose + apply.** One atomic change. Before applying, snapshot each file about to change.
    Check the touched paths against `measurement.md`'s rebuild-fallback list — interleaved (`ABABAB`)
diff --git a/skills/browsergnome/references/knowledge/INDEX.md b/skills/browsergnome/references/knowledge/INDEX.md
index 9c0088f..4b7a9fc 100644
--- a/skills/browsergnome/references/knowledge/INDEX.md
+++ b/skills/browsergnome/references/knowledge/INDEX.md
@@ -49,12 +49,12 @@ Autoresearch may propose anything here regardless of status, but everything stil
 Some entries carry a 5th line, `Guidance: <id>`, naming a `modern-web-guidance`
 guide id (bare id, e.g. `optimize-image-priority` — never `category/id`, since
 upstream category directories churn). `GoogleChrome/modern-web-guidance` ships
-as a Claude Code plugin (`/plugin marketplace add GoogleChrome/modern-web-guidance`
-then `/plugin install modern-web-guidance@googlechrome`); Doctor reports whether
-it's installed.
+as a Claude Code plugin (`claude plugin install modern-web-guidance@claude-plugins-official`);
+Doctor reports whether it's installed. The catalog is pinned in `references/tools.md`, and
+CI fails if any cited id stops resolving at that pin.
 
-- **Present** — retrieve the cited guide with `npx modern-web-guidance@latest
-  retrieve "<id>"` (or the plugin's equivalent skill call) when reasoning about
+- **Present** — retrieve the cited guide with `DISABLE_TELEMETRY=1 npx --yes
+  modern-web-guidance@1.0.0 retrieve "<id>"` (or the plugin's equivalent skill call) when reasoning about
   that entry, and treat its "Fallback strategies"/"Fallback strategy" section
   — a Baseline availability line (`Newly available` / `Widely available` /
   `has limited availability`, with a `Baseline since YYYY-MM-DD` date where
@@ -62,8 +62,8 @@ it's installed.
   `Unsupported in: ...` line — as browser-support fact, independent of the
   gate. Exact wording varies per guide; don't assume a fixed template.
 - **Absent** — proceed on the local entry alone, note `guidance <id> not
-  installed` on the finding, and nudge `/plugin install
-  modern-web-guidance@googlechrome`.
+  installed` on the finding, and nudge `claude plugin install
+  modern-web-guidance@claude-plugins-official`.
 - A citation is not a measurement — it never upgrades an entry's tier. An
   entry cited to `modern-web-guidance` is `documented` at most; the legend
   above already warns against letting "we found a doc for it" become `proven`,
diff --git a/skills/browsergnome/references/tools.md b/skills/browsergnome/references/tools.md
index 491a0b7..02a4cc6 100644
--- a/skills/browsergnome/references/tools.md
+++ b/skills/browsergnome/references/tools.md
@@ -81,3 +81,15 @@ by the `SessionStart` hook. Its `react` group, every tool returning a plain obje
 | `react_get_commit_report` | `traceName`, `commitIndex` | `{committedAt, priority, renderDuration, layoutDuration, passiveDuration, components:[{uid, name, type, actualDuration, selfDuration}]}` sorted by `actualDuration` desc |
 
 Source locations, owner stacks, and profiling data exist only in development builds of React.
+
+## modern-web-guidance — pinned version
+
+**Pinned: `modern-web-guidance@1.0.0`.** The catalog that `Guidance:` ids in `references/knowledge/`
+and `assets/playbook.seed.json` resolve against. Retrieve a guide with
+`DISABLE_TELEMETRY=1 npx --yes modern-web-guidance@1.0.0 retrieve "<id>"` — the package sends
+anonymous usage telemetry by default, and the env var keeps the target repo's runs out of it. It
+requires Node ≥ 22 and reads guides from local files, so it works offline once installed. An unknown
+id exits 1. Output over ~9.5 KB sent to a pipe is written to `$TMPDIR/mwg-guide-*.md` instead, with
+only a `saved to <path>` pointer on stdout. Every `modern-web-guidance@` reference in `SKILL.md` and
+`references/knowledge/INDEX.md` must match this pin (`check_invariants.mjs`), and `ci.yml` retrieves
+every cited id at it.
diff --git a/skills/browsergnome/scripts/check_invariants.mjs b/skills/browsergnome/scripts/check_invariants.mjs
index a900405..a141e00 100644
--- a/skills/browsergnome/scripts/check_invariants.mjs
+++ b/skills/browsergnome/scripts/check_invariants.mjs
@@ -12,8 +12,10 @@
  * Deliberately NOT covered here — see CONTRIBUTING.md:
  *   - "one confident, unhedged voice" across product docs — editorial, not
  *     mechanical.
- *   - `Guidance:` ids resolve against the external modern-web-guidance
- *     catalog, which isn't installed in CI — a check here would be theatre.
+ *   - `Guidance:` ids resolving against the modern-web-guidance catalog —
+ *     that needs the network, so it's a ci.yml step, not part of this
+ *     offline check. This file only keeps the pin those retrievals use
+ *     consistent (checkGuidancePin).
  *
  * Usage:
  *   node check_invariants.mjs       # run the real checks against this repo, exit 0/1
@@ -80,6 +82,20 @@ export function checkPerfMapCalibration(pagesYmlText, perfMapMdText) {
   return { ok: workflowSha != null && docsSha != null && workflowSha.startsWith(docsSha), workflowSha, docsSha };
 }
 
+/**
+ * Every `modern-web-guidance@X` in the docs must match references/tools.md's
+ * **Pinned: `modern-web-guidance@X.Y.Z`.** line — no `@latest`, no stale pin.
+ * @param {string} toolsMdText
+ * @param {string[]} docTexts - SKILL.md, knowledge/INDEX.md
+ * @returns {{ok:boolean, pin:string|null, mismatched:string[]}}
+ */
+export function checkGuidancePin(toolsMdText, docTexts) {
+  const pin = toolsMdText.match(/\*\*Pinned: `modern-web-guidance@(\d+\.\d+\.\d+)`\.\*\*/)?.[1] ?? null;
+  const refs = docTexts.flatMap((t) => [...t.matchAll(/modern-web-guidance@([\w.-]+)/g)].map((m) => m[1]));
+  const mismatched = refs.filter((v) => v !== pin && v !== 'claude-plugins-official');
+  return { ok: pin != null && mismatched.length === 0, pin, mismatched };
+}
+
 // ── Self-test ────────────────────────────────────────────────────────────
 
 function selfTest() {
@@ -103,6 +119,12 @@ function selfTest() {
   check('checkPerfMapCalibration: agreement (short SHA is a prefix)', checkPerfMapCalibration('EXCALIDRAW_SHA: 4872083c044491b6d5c96ae134a75464f96d6831', '`4872083c`, 527 modules').ok, true);
   check('checkPerfMapCalibration: catches drift', checkPerfMapCalibration('EXCALIDRAW_SHA: deadbeef00000000000000000000000000000000', '`4872083c`, 527 modules').ok, false);
 
+  const mwgPin = '**Pinned: `modern-web-guidance@1.0.0`.**';
+  check('checkGuidancePin: agreement (install command ignored)', checkGuidancePin(mwgPin, ['npx modern-web-guidance@1.0.0 retrieve', 'install modern-web-guidance@claude-plugins-official']).ok, true);
+  check('checkGuidancePin: catches @latest', checkGuidancePin(mwgPin, ['npx modern-web-guidance@latest retrieve']).mismatched, ['latest']);
+  check('checkGuidancePin: catches a stale pin', checkGuidancePin(mwgPin, ['modern-web-guidance@0.9.0']).mismatched, ['0.9.0']);
+  check('checkGuidancePin: missing tools.md pin fails', checkGuidancePin('', []).ok, false);
+
   check('checkVersionPin (re-exported from doctor.mjs): still agrees', checkVersionPin('{"mcpServers":{"chrome-devtools":{"args":["chrome-devtools-mcp@1.6.0"]}}}', '**Pinned: `chrome-devtools-mcp@1.6.0`.**').agree, true);
 
   console.log(`\n  ${pass} passed, ${fail} failed`);
@@ -168,6 +190,12 @@ function main() {
   report('Perf Map calibration SHA (pages.yml <-> perf-map.md)', calibration.ok,
     calibration.ok ? calibration.workflowSha.slice(0, 8) : `workflow=${calibration.workflowSha ?? '?'} docs=${calibration.docsSha ?? '?'}`);
 
+  // 4b. modern-web-guidance pin
+  const indexMdText = read(path.join(repoRoot, 'skills/browsergnome/references/knowledge/INDEX.md'));
+  const mwg = checkGuidancePin(toolsMdText, [skillMdText, indexMdText]);
+  report('modern-web-guidance pin (references/tools.md <-> SKILL.md, knowledge/INDEX.md)', mwg.ok,
+    mwg.ok ? `@${mwg.pin}` : `pin=@${mwg.pin ?? '?'} mismatched=[${mwg.mismatched}]`);
+
   // 5. HTML builders escape every `<` in the data they inject into a <script> block
   const HOSTILE = '</script><!--<script>';
   const ESCAPED = HOSTILE.replace(/</g, '\\u003c');
diff --git a/skills/browsergnome/scripts/doctor.mjs b/skills/browsergnome/scripts/doctor.mjs
index 56fd007..f16ba5d 100644
--- a/skills/browsergnome/scripts/doctor.mjs
+++ b/skills/browsergnome/scripts/doctor.mjs
@@ -432,7 +432,7 @@ function main() {
   console.log(`\nbrowsergnome doctor — ${repo}\n`);
 
   const node = process.versions.node;
-  console.log(`  ${ok(parseInt(node, 10) >= 18)} node ${node} (>=18 required)`);
+  console.log(`  ${ok(parseInt(node, 10) >= 22)} node ${node} (>=22 required — modern-web-guidance needs it)`);
 
   // ── chrome-devtools-mcp pin consistency ─────────────────────────────────
   const mcpJsonPath = path.join(pluginRoot, '.mcp.json');
@@ -454,7 +454,7 @@ function main() {
   console.log(`        re-verify against references/tools.md rather than assuming the pin still holds.`);
 
   const mwgInstalled = sh(`find "${os.homedir()}/.claude/plugins" -path "*/modern-web-guidance*" -name "*.md" -maxdepth 6 2>/dev/null | head -1`);
-  console.log(`  ${mwgInstalled ? ok(true) : warn} modern-web-guidance${mwgInstalled ? '' : ' — install: /plugin marketplace add GoogleChrome/modern-web-guidance && /plugin install modern-web-guidance@googlechrome'}`);
+  console.log(`  ${mwgInstalled ? ok(true) : warn} modern-web-guidance${mwgInstalled ? '' : ' — install: claude plugin install modern-web-guidance@claude-plugins-official'}`);
 
   // ── Git state ─────────────────────────────────────────────────────────────
   const gitInsideWorkTree = sh('git rev-parse --is-inside-work-tree') === 'true';
diff --git a/templates/ci/browsergnome-autopilot-browser.yml b/templates/ci/browsergnome-autopilot-browser.yml
index 15cbd95..a72af0d 100644
--- a/templates/ci/browsergnome-autopilot-browser.yml
+++ b/templates/ci/browsergnome-autopilot-browser.yml
@@ -55,7 +55,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
 
       - run: npm ci
diff --git a/templates/ci/browsergnome-autopilot-build.yml b/templates/ci/browsergnome-autopilot-build.yml
index 9ada8b9..017e2a2 100644
--- a/templates/ci/browsergnome-autopilot-build.yml
+++ b/templates/ci/browsergnome-autopilot-build.yml
@@ -46,7 +46,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
 
       - run: npm ci

From c12edf08a7ee5aae711a41803399a1d3d0e8cded Mon Sep 17 00:00:00 2001
From: Xavier Costa <xavier.costa@uphold.com>
Date: Thu, 12 Nov 2026 14:37:56 +0000
Subject: [PATCH 2/3] Sync CLAUDE.md with Node 22 floor and guidance pin checks

---
 .claude/CLAUDE.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 3f2e03d..f5c7ba7 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -48,7 +48,7 @@ gzipped captures in `assets/`; `stats.mjs`/`doctor.mjs`/`build_playbook.mjs` tes
 inline fixtures. Adding a test means extending the relevant `selfTest()`, not adding a file. Keep
 `package.json`'s `test` script in sync when a new `*:test` is added.
 
-CI (`.github/workflows/ci.yml`, Node 18 + 20) runs `npm test` plus two things `npm test` does not:
+CI (`.github/workflows/ci.yml`, Node 22 + 24) runs `npm test` plus two things `npm test` does not:
 
 ```bash
 # offline smoke chain
@@ -128,8 +128,12 @@ These have no single source of truth; an edit to one side silently breaks the ot
   table and `doctor.mjs`'s `DEFAULT_CONFIG`. Same class as the chrome-devtools-mcp pin —
   `check_invariants.mjs`'s `checkConfigKeys()` catches drift.
 - **`Guidance:` ids** in `references/knowledge/*.md` and `assets/playbook.seed.json` name
-  `modern-web-guidance` guide ids. Key on the bare `id` — upstream category directories churn. A
-  citation that stops resolving fails silently; nothing validates it.
+  `modern-web-guidance` guide ids. Key on the bare `id` — upstream category directories churn.
+  `ci.yml` retrieves every cited id at the pinned version and fails on any that don't resolve.
+- **modern-web-guidance pin** — `references/tools.md`'s ``**Pinned: `modern-web-guidance@X.Y.Z`.**``
+  line is the source; every `modern-web-guidance@` in `SKILL.md` and `references/knowledge/INDEX.md`
+  must match it (`checkGuidancePin()`), and `ci.yml` reads it from there. It needs Node ≥ 22, which
+  is why that's the floor.
 
 ## Project rules
 
@@ -146,7 +150,7 @@ These have no single source of truth; an edit to one side silently breaks the ot
 - **Knowledge-base status tiers** (`proven` / `documented` / `ungated hypothesis` / `dead end`) in
   `references/knowledge/` require a real measured before/after to upgrade. A citation is not a
   measurement.
-- Node ≥ 18, ESM throughout. The only runtime deps are `@babel/parser` + `@babel/traverse` (used
+- Node ≥ 22, ESM throughout. The only runtime deps are `@babel/parser` + `@babel/traverse` (used
   solely by `perf_scan.mjs`) and `react-devtools-cdt-mcp` at an exact version (never imported by a
   script — `page_tools.mjs serve` reads its page script from `node_modules` and serves it to the target
   page). The `SessionStart` hook installs them, and its guard checks for both. Keep it that way.

From 7464e537b81017d8212f1e4339f75dc890dd85f4 Mon Sep 17 00:00:00 2001
From: Xavier Costa <xavier.costa@uphold.com>
Date: Thu, 12 Nov 2026 14:40:35 +0000
Subject: [PATCH 3/3] Fail malformed guidance citations and document template
 Node version

---
 .github/workflows/ci.yml                        | 11 ++++++-----
 templates/ci/README.md                          |  4 ++++
 templates/ci/browsergnome-autopilot-browser.yml |  3 +++
 templates/ci/browsergnome-autopilot-build.yml   |  3 +++
 4 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cf17345..510a573 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -73,14 +73,15 @@ jobs:
         run: |
           pin=$(grep -oE 'Pinned: `modern-web-guidance@[0-9]+\.[0-9]+\.[0-9]+' skills/browsergnome/references/tools.md | cut -d@ -f2)
           test -n "$pin" || { echo "::error::no modern-web-guidance pin in references/tools.md"; exit 1; }
-          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)
+          ids=$( { grep -rh '^Guidance:' skills/browsergnome/references/knowledge | sed 's/^Guidance:[[:space:]]*//'
+                   grep -oE '"guidance"[[:space:]]*:[[:space:]]*"[^"]*"' skills/browsergnome/assets/playbook.seed.json | cut -d'"' -f4; } | sort -u)
           test -n "$ids" || { echo "::error::found no Guidance ids to check"; exit 1; }
           fail=0
-          for id in $ids; do
-            if npx --yes "modern-web-guidance@$pin" retrieve "$id" > /dev/null 2>&1; then echo "  ok  $id"
+          while IFS= read -r id; do
+            if ! printf '%s' "$id" | grep -qE '^[a-z0-9-]+$'; then echo "::error::Guidance '$id' is not a bare modern-web-guidance id"; fail=1
+            elif npx --yes "modern-web-guidance@$pin" retrieve "$id" > /dev/null 2>&1; then echo "  ok  $id"
             else echo "::error::Guidance id '$id' does not resolve at modern-web-guidance@$pin"; fail=1; fi
-          done
+          done <<< "$ids"
           exit $fail
 
       - name: Validate JSON files
diff --git a/templates/ci/README.md b/templates/ci/README.md
index d05830b..cb6c306 100644
--- a/templates/ci/README.md
+++ b/templates/ci/README.md
@@ -47,6 +47,10 @@ cp browsergnome-autopilot-build.yml .github/workflows/
 
 A PR will appear on your repo (or a clean exit in the logs if no fix cleared the gate).
 
+Both templates set up Node 22, which `modern-web-guidance` needs. If your repo builds on another
+version, change `node-version` (or use `node-version-file: .nvmrc`); below 22, findings run without
+their guidance citations.
+
 ---
 
 ## Quickstart (browser)
diff --git a/templates/ci/browsergnome-autopilot-browser.yml b/templates/ci/browsergnome-autopilot-browser.yml
index a72af0d..7342358 100644
--- a/templates/ci/browsergnome-autopilot-browser.yml
+++ b/templates/ci/browsergnome-autopilot-browser.yml
@@ -18,6 +18,9 @@ name: browsergnome perf autopilot — browser (weekly)
 #   6. Characterize k/minEffect ON THIS RUNNER before trusting the gate here (see "Runner noise
 #      characterization" below) and commit the result to .bgn/config.json — do not inherit the
 #      laptop-derived defaults in references/measurement.md as-is.
+#   7. Set setup-node's node-version to what your repo builds on (or use node-version-file:
+#      .nvmrc). 22 is the default because modern-web-guidance needs Node >= 22; below that,
+#      findings run without their guidance citations.
 #   7. Tune cron, top_findings, max_iters, preset. Set vars.BROWSERGNOME_GOAL for a fixed goal.
 #
 # See templates/ci/README.md for the full adoption guide.
diff --git a/templates/ci/browsergnome-autopilot-build.yml b/templates/ci/browsergnome-autopilot-build.yml
index 017e2a2..9dd87c7 100644
--- a/templates/ci/browsergnome-autopilot-build.yml
+++ b/templates/ci/browsergnome-autopilot-build.yml
@@ -12,6 +12,9 @@ name: browsergnome perf autopilot (weekly)
 #      Pinning to a tag is recommended: https://github.com/uphold/browsergnome.git@v0.2.0
 #   5. Tune cron, top_findings, max_iters, and optionally set vars.BROWSERGNOME_GOAL for a
 #      fixed custom goal on every scheduled run (blank = weekly top-X default).
+#   6. Set setup-node's node-version to what your repo builds on (or use node-version-file:
+#      .nvmrc). 22 is the default because modern-web-guidance needs Node >= 22; below that,
+#      findings run without their guidance citations.
 #
 # See templates/ci/README.md for the full adoption guide.