@opengsd/gsd-core 1.17.0 → 1.19.0

package/scripts/diagnose-windows-spawn-watcher.cjs

@@ -0,0 +1,317 @@
+'use strict';
+
+/**
+ * #5473 — a job-long watcher for the Windows conformance tier's bounded-child stalls.
+ *
+ * In one Windows run (job 39083981500) three different tests each hit their
+ * bound EXACTLY: the #4784 `sh -c 'printf | sed | head -1'` at 10 s, an
+ * `echo | grep | awk` bash pipeline at 5 s, and `npm ls` through cmd.exe at 30 s.
+ * Measured inside the tier, a bare `bash` starts in ~35 ms, Defender real-time
+ * protection is off, and 2,407 pipeline calls under 6-way concurrency never
+ * stalled past 2 s. So the stall is rare and does not reproduce on demand. This
+ * watcher runs beside the whole test step on the same VM and writes down, with a
+ * UTC wall-clock timestamp, every moment the VM itself stops making progress:
+ *
+ *   - `loop-gap`: this process's own timer fired more than LOOP_GAP_MS late
+ *     (the whole VM, or at least this process, was not scheduled);
+ *   - `probe-slow`: a probe child (the #4784 sh pipeline, or `cmd /c exit`)
+ *     took more than PROBE_SLOW_MS, or hit its bound;
+ *   - `procs`: a snapshot of the live node/sh/bash/cmd/npm/git processes (name,
+ *     parent, age, CPU time so far, and the *.test.cjs names in their
+ *     arguments), taken after either anomaly and every two minutes, so a stall
+ *     can be lined up with what else was running in the chunk. Earlier red
+ *     `next`s (see defaultMaxUnmeasuredPerChunk in scripts/run-tests.cjs) lost
+ *     whole chunks at 600000 ms with zero failing tests; the periodic snapshots
+ *     show which test file a killed chunk was inside and whether it was idle.
+ *
+ * Timestamps are ISO UTC, the same clock as the lines in the job log, so a
+ * failing test's end time minus its duration can be lined up against these
+ * events: a stall that is the VM freezing shows up here at the same instant; a
+ * stall that is only that one child hanging does not.
+ *
+ *   node scripts/diagnose-windows-spawn-watcher.cjs start [dir]   spawn detached, return at once
+ *   node scripts/diagnose-windows-spawn-watcher.cjs report [dir]  stop it, print and summarize the events
+ *
+ * `dir` defaults to RUNNER_TEMP/spawn-watcher. No environment variable or value
+ * is read into the report. TEMPORARY: delete
+ * with scripts/diagnose-validate-commit-*.cjs once #5473 is resolved.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const TICK_MS = 250;
+const LOOP_GAP_MS = 750;
+// The watcher must not become the load it is looking for: a stall that shows up once in
+// thousands of calls is easy to shift with extra spawn churn, so probes are sparse (one
+// sh and one cmd every 5 s, about 480 pairs over a 40 minute job) and the CIM query,
+// the heavy part, runs every 5 minutes plus at most once a minute after an anomaly.
+const PROBE_EVERY_MS = 5000;
+const PROBE_BOUND_MS = 15_000;
+const PROBE_SLOW_MS = 1500;
+const MAX_LIFETIME_MS = 40 * 60_000;
+const PIPELINE = "printf '%s\\n' x | sed -n 's/x/y/p' | head -1";
+
+const REPORT_WAIT_MS = 20_000;
+const EVENTS_FILE = 'events.log';
+const STOP_FILE = 'stop';
+const SUMMARY_FILE = 'summary.json';
+
+/** One event line: `<ISO UTC> <kind> <ms> <detail>`. */
+function formatEvent(at, kind, ms, detail) {
+  return `${new Date(at).toISOString()} ${kind} ${ms} ${detail}`;
+}
+
+const SHELL_NAMES = new Set(['sh', 'bash', 'cmd']);
+const LINGER_AGE_S = 30;
+
+/**
+ * One compact line for a process snapshot. `rows` are `{pid, ppid, name, born, cpuMs, cmd}`
+ * (born = epoch ms, cmd = the command line). Only what identifies the work is kept: the
+ * process name, its age, its CPU time so far, and the `*.test.cjs` file names in its
+ * arguments (the node:test chunk children carry them). Nothing else from a command line
+ * is reported, because the job environment carries tokens and a report is public.
+ */
+function formatProcs(rows, now) {
+  return rows
+    .map((r) => {
+      const tests = [...new Set(String(r.cmd || '').match(/[\w.-]+\.test\.cjs/g) || [])].slice(0, 3);
+      const age = Math.max(0, Math.round((now - r.born) / 1000));
+      const cpu = Math.round(r.cpuMs / 1000);
+      // A shell that outlives every bound the tests set is the signature of a descendant
+      // still holding a spawnSync stdio pipe: node's timer then reports ETIMEDOUT at the
+      // exact bound although the direct child already exited (node src/spawn_sync.cc).
+      const lingering = SHELL_NAMES.has(r.name) && age > LINGER_AGE_S ? ' LINGERING' : '';
+      return `${r.name}#${r.pid}<${r.ppid} age ${age}s cpu ${cpu}s${lingering}${tests.length ? ` [${tests.join(' ')}]` : ''}`;
+    })
+    .join(' | ');
+}
+
+/** Inverse of formatEvent; null for a line that is not an event. */
+function parseEvent(line) {
+  const m = /^(\d{4}-\d{2}-\d{2}T[\d:.]+Z) (loop-gap|probe-slow|probe-error|procs) (\d+) (.*)$/.exec(line);
+  if (!m) return null;
+  return { at: m[1], kind: m[2], ms: Number(m[3]), detail: m[4] };
+}
+
+/** Counts and extremes per kind, over parsed events. */
+function summarizeEvents(events) {
+  const out = {};
+  for (const e of events) {
+    const s = out[e.kind] || (out[e.kind] = { count: 0, maxMs: 0 });
+    s.count += 1;
+    if (e.ms > s.maxMs) s.maxMs = e.ms;
+  }
+  return out;
+}
+
+/** Percentile (0..1) of numbers, nearest-rank on a sorted copy; null when empty. */
+function percentile(values, p) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+}
+
+/**
+ * Run one probe child. `onDone(label, ms, timedOut, started, error)`: `error` is the spawn
+ * error code (or the thrown message) when the probe never ran, else null. A probe that
+ * never ran must not look like a fast success, so callers keep it out of the latencies.
+ */
+function probe(label, bin, args, onDone) {
+  const started = Date.now();
+  let timedOut = false;
+  let settled = false;
+  let timer = null;
+  const finish = (error) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    onDone(label, Date.now() - started, timedOut, started, error || null);
+  };
+  let child;
+  try {
+    child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+  } catch (e) {
+    finish(`threw ${e && e.code ? e.code : 'error'}`);
+    return;
+  }
+  timer = setTimeout(() => { timedOut = true; try { child.kill('SIGKILL'); } catch { /* gone */ } finish(); }, PROBE_BOUND_MS);
+  child.stdout.resume();
+  child.stderr.resume();
+  child.on('error', (e) => finish(`spawn ${e && e.code ? e.code : 'error'}`));
+  child.on('close', () => finish());
+}
+
+const PS_PROCS = "Get-CimInstance Win32_Process | Where-Object { $_.Name -match '^(node|sh|bash|cmd|npm|git)\\.exe$' } | ForEach-Object { [pscustomobject]@{ pid = $_.ProcessId; ppid = $_.ParentProcessId; name = $_.Name -replace '\\.exe$', ''; born = [int64](([datetime]$_.CreationDate).ToUniversalTime() - [datetime]'1970-01-01').TotalMilliseconds; cpuMs = [int64](($_.KernelModeTime + $_.UserModeTime) / 10000); cmd = $_.CommandLine } } | ConvertTo-Json -Compress";
+const SNAPSHOT_EVERY_MS = 300_000;
+const SNAPSHOT_COOLDOWN_MS = 60_000;
+const SNAPSHOT_BOUND_MS = 30_000;
+
+/** Snapshot the live node/sh/bash/cmd/npm/git processes; calls back with the compact line. */
+function snapshotProcs(onDone) {
+  const started = Date.now();
+  let out = '';
+  let err = '';
+  let child;
+  try {
+    child = spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', PS_PROCS], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+  } catch (e) {
+    onDone(Date.now() - started, `snapshot unavailable (threw ${e && e.code ? e.code : 'error'})`);
+    return;
+  }
+  const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, SNAPSHOT_BOUND_MS);
+  child.stdout.on('data', (d) => { out += d; });
+  // PowerShell's own error text carries no command lines; a short head tells a failure from a timeout.
+  child.stderr.on('data', (d) => { if (err.length < 200) err += d; });
+  child.on('error', (e) => { clearTimeout(timer); onDone(Date.now() - started, `snapshot unavailable (spawn ${e && e.code ? e.code : 'error'})`); });
+  child.on('close', (code, signal) => {
+    clearTimeout(timer);
+    let rows = [];
+    try { const parsed = JSON.parse(out); rows = Array.isArray(parsed) ? parsed : [parsed]; } catch { /* no rows */ }
+    // The watcher's own process and its probe/snapshot children are not what we are lining up against.
+    rows = rows.filter((r) => r.pid !== process.pid && r.ppid !== process.pid);
+    const why = signal ? `killed ${signal}` : `exit ${code}`;
+    onDone(
+      Date.now() - started,
+      rows.length ? `${rows.length} procs: ${formatProcs(rows, Date.now())}` : `snapshot unavailable (${why}${err ? `: ${err.replace(/\s+/g, ' ').trim().slice(0, 200)}` : ''})`,
+    );
+  });
+}
+
+function run(dir) {
+  const eventsPath = path.join(dir, EVENTS_FILE);
+  const record = (at, kind, ms, detail) => {
+    try { fs.appendFileSync(eventsPath, `${formatEvent(at, kind, ms, detail)}\n`); } catch { /* dir gone: nothing to do */ }
+  };
+  let lastSnapshotAt = 0;
+  let snapshotting = false;
+  const takeSnapshot = (why) => {
+    const now = Date.now();
+    if (snapshotting || now - lastSnapshotAt < SNAPSHOT_COOLDOWN_MS) return;
+    snapshotting = true;
+    lastSnapshotAt = now;
+    snapshotProcs((ms, detail) => { snapshotting = false; record(Date.now(), 'procs', ms, `${why}: ${detail}`); });
+  };
+  const snapshotTimer = setInterval(() => takeSnapshot('periodic'), SNAPSHOT_EVERY_MS);
+  const lifetimeEnd = Date.now() + MAX_LIFETIME_MS;
+  const probeMs = { sh: [], cmd: [] };
+  let probeCount = 0;
+  let last = Date.now();
+
+  const tick = setInterval(() => {
+    const now = Date.now();
+    const late = now - last - TICK_MS;
+    if (late > LOOP_GAP_MS) { record(now, 'loop-gap', late, `timer fired ${late}ms late`); takeSnapshot('after loop-gap'); }
+    last = now;
+    if (now > lifetimeEnd || fs.existsSync(path.join(dir, STOP_FILE))) finishRun();
+  }, TICK_MS);
+
+  const probeErrors = { sh: 0, cmd: 0 };
+  const onProbe = (label, ms, timedOut, started, error) => {
+    if (error) {
+      probeErrors[label] += 1;
+      record(Date.now(), 'probe-error', ms, `${label} never ran: ${error}`);
+      return;
+    }
+    probeCount += 1;
+    probeMs[label].push(ms);
+    if (ms > PROBE_SLOW_MS || timedOut) {
+      record(Date.now(), 'probe-slow', ms, `${label} started ${new Date(started).toISOString()}${timedOut ? ' hit the bound' : ''}`);
+      takeSnapshot('after probe-slow');
+    }
+  };
+
+  let probing = true;
+  let loopTimer = null;
+  // Run the two probes one after the other, then wait out the rest of the interval.
+  const loop = () => {
+    if (!probing) return;
+    const cycleStart = Date.now();
+    probe('sh', 'sh', ['-c', PIPELINE], (l, ms, to, st, er) => {
+      onProbe(l, ms, to, st, er);
+      probe('cmd', 'cmd', ['/c', 'exit', '0'], (l2, ms2, to2, st2, er2) => {
+        onProbe(l2, ms2, to2, st2, er2);
+        loopTimer = setTimeout(loop, Math.max(0, PROBE_EVERY_MS - (Date.now() - cycleStart)));
+      });
+    });
+  };
+  loop();
+
+  function finishRun() {
+    probing = false;
+    clearInterval(tick);
+    clearInterval(snapshotTimer);
+    clearTimeout(loopTimer);
+    const summary = {
+      probes: probeCount,
+      sh: { n: probeMs.sh.length, errors: probeErrors.sh, median: percentile(probeMs.sh, 0.5), p99: percentile(probeMs.sh, 0.99), max: percentile(probeMs.sh, 1) },
+      cmd: { n: probeMs.cmd.length, errors: probeErrors.cmd, median: percentile(probeMs.cmd, 0.5), p99: percentile(probeMs.cmd, 0.99), max: percentile(probeMs.cmd, 1) },
+    };
+    // Write then rename, so report never sees the file before its content has landed.
+    try {
+      const target = path.join(dir, SUMMARY_FILE);
+      fs.writeFileSync(`${target}.tmp`, JSON.stringify(summary));
+      fs.renameSync(`${target}.tmp`, target);
+    } catch { /* best effort */ }
+    // No process.exit (ADR-3889): every timer is cleared above, so the process ends when the
+    // probe or snapshot child still in flight (each bounded) has exited; report has already
+    // been released by the summary file, so nothing waits on this.
+  }
+}
+
+function start(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  const child = spawn(process.execPath, [__filename, 'run', dir], { detached: true, stdio: 'ignore', windowsHide: true });
+  child.unref();
+}
+
+function report(dir) {
+  try { fs.writeFileSync(path.join(dir, STOP_FILE), ''); } catch { /* start never ran */ }
+  // The stop file is only seen on the watcher's 250ms tick, so a VM stall longer than this
+  // wait (the very case under study) leaves no summary: say so below instead of "crashed".
+  const deadline = Date.now() + REPORT_WAIT_MS;
+  while (!fs.existsSync(path.join(dir, SUMMARY_FILE)) && Date.now() < deadline) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+  }
+  let events = [];
+  try {
+    events = fs.readFileSync(path.join(dir, EVENTS_FILE), 'utf8').split('\n').map(parseEvent).filter(Boolean);
+  } catch { /* no events file: nothing recorded */ }
+  let summary = null;
+  try { summary = JSON.parse(fs.readFileSync(path.join(dir, SUMMARY_FILE), 'utf8')); } catch { /* watcher did not finish */ }
+  const lines = [
+    '### #5473 Windows spawn-stall watcher (whole test step, same VM)',
+    '',
+    summary
+      ? `probes: ${summary.probes} ; sh pipeline median ${summary.sh.median} / p99 ${summary.sh.p99} / max ${summary.sh.max} ms (n=${summary.sh.n}, never ran ${summary.sh.errors}) ; cmd /c exit median ${summary.cmd.median} / p99 ${summary.cmd.p99} / max ${summary.cmd.max} ms (n=${summary.cmd.n}, never ran ${summary.cmd.errors})`
+      : `watcher summary missing after ${REPORT_WAIT_MS / 1000}s: it either crashed or was stalled past the wait (the events below show which: a stall leaves loop-gap/probe-slow lines up to the last tick)`,
+    `events: ${JSON.stringify(summarizeEvents(events))}`,
+    '',
+    ...events.map((e) => `- ${e.at} ${e.kind} ${e.ms}ms ${e.detail}`),
+  ];
+  const text = lines.join('\n');
+  process.stdout.write(`${text}\n`);
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${text}\n`); } catch { /* best effort */ }
+  }
+}
+
+// CONTRIBUTING forbids `${{ }}` inside a workflow `run:` block, so the workflow
+// passes no directory: GitHub sets RUNNER_TEMP itself, and start and report agree on it here.
+function defaultDir() {
+  return path.join(process.env.RUNNER_TEMP || require('node:os').tmpdir(), 'spawn-watcher');
+}
+
+function main() {
+  const [, , mode, dirArg] = process.argv;
+  if (!['start', 'run', 'report'].includes(mode)) {
+    throw new ExitError(2, 'usage: diagnose-windows-spawn-watcher.cjs start|report [dir]');
+  }
+  ({ start, run, report })[mode](path.resolve(dirArg || defaultDir()));
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { formatEvent, formatProcs, parseEvent, summarizeEvents, percentile, LOOP_GAP_MS, PROBE_SLOW_MS };

package/scripts/docs-guard-registry.cjs

@@ -55,7 +55,7 @@
  * narrow subset of guards that read it, instead of always running the
  * entire registry. Each value is a non-empty array of PATTERNS:
  *
- *   - a plain path (e.g. `'docs/AGENTS.md'`) matches that exact file only;
+ *   - a plain path (e.g. `'docs/reference/agents.md'`) matches that exact file only;
  *   - a trailing-slash path (e.g. `'docs/adr/'`) matches any changed path
  *     under that directory prefix — use this for a test that walks or
  *     `readdirSync`s a whole docs/ subdirectory;
@@ -157,6 +157,8 @@ function assertNoSuiteCollision(tests) {
  * unresolvable read is recorded as `'*'`, never a narrowed guess.
  */
 const DOCS_GUARD_TESTS = {
+  'tests/pi-unsupported-skill-docs.test.cjs': ['docs/how-to/start-a-gsd-workflow-from-pi.md'],
+  'tests/pi-parity-matrix.test.cjs': ['docs/reference/pi-parity-matrix.md'],
   'tests/adr-15-progress-converge.test.cjs': [
     'docs/COMMANDS.md',
     'docs/how-to/run-phases-autonomously.md',
@@ -168,11 +170,14 @@ const DOCS_GUARD_TESTS = {
   // Walks docs/features/ as a directory (the fragment corpus) and asserts the
   // committed docs/FEATURES.md equals the generated projection of it (#3840).
   'tests/features-index-gate.test.cjs': ['docs/features/', 'docs/FEATURES.md'],
-  'tests/agent-classification-parity.test.cjs': ['docs/AGENTS.md', 'docs/INVENTORY.md'],
+  'tests/agent-classification-parity.test.cjs': ['docs/reference/agents.md', 'docs/INVENTORY.md'],
   // #3683: pins the learnings feature section's agreement with the canonical
   // artifact registry (reads docs/FEATURES.md around the extract-learnings
   // entry).
   'tests/learnings.test.cjs': ['docs/FEATURES.md'],
+  // #5706: pins the release map statuses / tag states in docs/CONFIGURATION.md
+  // against the milestone-release-map module's exported enums.
+  'tests/milestone-release-map.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/analyze-dependencies.test.cjs': ['docs/COMMANDS.md'],
   'tests/auto-select-attribute.test.cjs': ['docs/reference/plan-md.md'],
   'tests/autonomous-converge.test.cjs': [
@@ -199,6 +204,7 @@ const DOCS_GUARD_TESTS = {
   // files without re-deriving the scan's own file-discovery logic.
   'tests/commit-files-pathspec.test.cjs': ['*'],
   'tests/compact-content-4139.test.cjs': ['docs/CONFIGURATION.md'],
+  'tests/complete-milestone-release-map-routing.test.cjs': ['docs/README.md', 'docs/how-to/tag-a-multi-repo-milestone.md'],
   'tests/config-field-docs.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/config.test.cjs': ['docs/CONFIGURATION.md'],
   // #4974: doc/workflow content-parity checks read docs/CONFIGURATION.md's
@@ -245,7 +251,7 @@ const DOCS_GUARD_TESTS = {
     'docs/ko-KR/reference/state-md.md',
     'docs/pt-BR/reference/state-md.md',
   ],
-  'tests/drift-detection.test.cjs': ['docs/CONFIGURATION.md', 'docs/AGENTS.md'],
+  'tests/drift-detection.test.cjs': ['docs/CONFIGURATION.md', 'docs/reference/agents.md'],
   'tests/edge-probe-docs-fixtures.test.cjs': ['docs/adr/550-spec-phase-probe-contract.md'],
   'tests/edit-phase.test.cjs': [
     'docs/INVENTORY.md',
@@ -313,7 +319,7 @@ const DOCS_GUARD_TESTS = {
   'tests/host-integration-descriptors.test.cjs': [
     'docs/reference/host-integration-capability-matrix.md',
   ],
-  'tests/install.test.cjs': ['docs/AGENTS.md', 'docs/INVENTORY.md', 'docs/INVENTORY-MANIFEST.json'],
+  'tests/install.test.cjs': ['docs/reference/agents.md', 'docs/INVENTORY.md', 'docs/INVENTORY-MANIFEST.json'],
   // SOURCE_DIRS includes 'docs' and walks it recursively for every .md file
   // (intel.test.cjs:1223-1228) — a generic tree walk.
   'tests/intel.test.cjs': ['*'],
@@ -321,6 +327,13 @@ const DOCS_GUARD_TESTS = {
   'tests/inventory-manifest-sync.test.cjs': ['docs/INVENTORY.md', 'docs/INVENTORY-MANIFEST.json'],
   'tests/kilo-upgrades.test.cjs': ['docs/how-to/connect-gsd-mcp-server.md'],
   'tests/live-config-guard.test.cjs': ['docs/TESTING-SUITES.md'],
+  // #5601: localized INVENTORY coverage notes must state no agent counts.
+  'tests/localized-inventory-agent-counts.test.cjs': [
+    'docs/ja-JP/',
+    'docs/ko-KR/',
+    'docs/pt-BR/',
+    'docs/zh-CN/',
+  ],
   // #3726: pins the `milestone complete` synopsis (English + four localized
   // mirrors), the `--confirm` flag row and the guard-override instructions —
   // `type: Fixed` exempts that PR from the docs-required lint, so this is the
@@ -338,13 +351,15 @@ const DOCS_GUARD_TESTS = {
   // (no-pending-3212-markers.test.cjs:37-46), which includes all of docs/ —
   // cannot be resolved to a fixed docs/ path set.
   'tests/no-pending-3212-markers.test.cjs': ['*'],
+  'tests/pause-work-improvements.test.cjs': ['docs/zh-CN/references/git-integration.md'],
   'tests/phase6-capability-docs.test.cjs': ['docs/how-to/develop-a-capability.md', 'docs/README.md'],
   'tests/phase6-review-capabilities.test.cjs': [
     'docs/reference/review-verification-capabilities.md',
     'docs/how-to/develop-a-capability.md',
     'docs/README.md',
   ],
-  'tests/plan-checker-coupling.test.cjs': ['docs/AGENTS.md'],
+  'tests/plan-authoring-verification-gaps.test.cjs': ['docs/reference/plan-md.md'],
+  'tests/plan-checker-coupling.test.cjs': ['docs/reference/agents.md'],
   'tests/plan-phase-drift-guard.test.cjs': [
     'docs/CONFIGURATION.md',
     'docs/COMMANDS.md',
@@ -404,7 +419,7 @@ const DOCS_GUARD_TESTS = {
     'docs/COMMANDS.md',
     'docs/reference/plan-md.md',
     'docs/how-to/plan-a-phase.md',
-    'docs/AGENTS.md',
+    'docs/reference/agents.md',
   ],
   'tests/ui-interaction-capture.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/ui-spec-inventory-provenance.test.cjs': [
@@ -419,7 +434,7 @@ const DOCS_GUARD_TESTS = {
     'docs/pt-BR/how-to/design-a-ui-phase.md',
   ],
   'tests/verifier-behavior-unverified.test.cjs': ['docs/reference/planning-artifacts.md'],
-  'tests/verifier-coincidental-reliance.test.cjs': ['docs/AGENTS.md'],
+  'tests/verifier-coincidental-reliance.test.cjs': ['docs/reference/agents.md'],
   'tests/verify.test.cjs': ['docs/reference/plan-md.md'],
   // #5118 V43: asserts the deleted execute-phase/steps/stale-reverification.md
   // is absent from the generated inventory manifest.

package/scripts/gen-health-docs.cjs

@@ -122,6 +122,13 @@ const REMEDY_ACTION_METADATA = new Map([
       risk: 'None — additive only; triggered by `--backfill` flag',
     },
   ],
+  [
+    'repairVerificationStatus',
+    {
+      effect: 'Rewrite a known legacy verification `status` (`pass_with_caveats`) to `passed`, keeping the original as `legacy_status`',
+      risk: 'None — only the `status` line changes; unknown statuses are never touched',
+    },
+  ],
 ]);
 
 /** Order the Effect/Risk table renders in — matches `REMEDY_ACTION`'s own declaration order. */
@@ -132,6 +139,7 @@ const REMEDY_ACTION_ORDER = [
   'addNyquistKey',
   'addAiIntegrationPhaseKey',
   'backfillMilestones',
+  'repairVerificationStatus',
 ];
 
 /**
@@ -139,7 +147,11 @@ const REMEDY_ACTION_ORDER = [
  * whose remedy is conditional on a flag the plain `Yes`/`No` can't express
  * (mirrors the hand-written table's pre-existing `W018` row: `Yes (--backfill)`).
  */
-const REPAIRABLE_DISPLAY_OVERRIDE = new Map([['W018', 'Yes (`--backfill`)']]);
+const REPAIRABLE_DISPLAY_OVERRIDE = new Map([
+  ['W018', 'Yes (`--backfill`)'],
+  // #5291: only a known legacy status (`pass_with_caveats`) is rewritten.
+  ['W030', 'Yes (known legacy statuses only)'],
+]);
 
 const STATIC_NOT_REPAIRABLE_BULLETS = [
   'PROJECT.md, ROADMAP.md content',

package/scripts/gen-pi-package-skills.cjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * gen-pi-package-skills.cjs — generates pi/package-skills/gsd-<stem>/SKILL.md,
+ * the Pi skill templates the Pi package (`pi install npm:@opengsd/gsd-core`)
+ * renders at session start.
+ *
+ * Usage:
+ *   node scripts/gen-pi-package-skills.cjs            # print summary
+ *   node scripts/gen-pi-package-skills.cjs --write    # write pi/package-skills/
+ *   node scripts/gen-pi-package-skills.cjs --check    # exit 1 if committed templates are stale
+ *
+ * #5558 (Phase 1b of epic #5556). Pi skill bodies embed the absolute path of the
+ * engine tree they `@`-include, and a package's install location is unknown at
+ * build time. So the templates are produced by running the real installer
+ * (`bin/install.js --pi --global --config-dir <tmp>`), then replacing the temp
+ * config dir with PI_ENGINE_ROOT_TOKEN. Rendering a template with a root R
+ * (`renderSkillTemplate`, exported for the parity test; pi/gsd.cjs carries the
+ * same two-line substitution) is therefore byte-identical to what the installer
+ * writes for config dir R.
+ *
+ * Depends on a built lib (`npm run build:lib`); must run after it in the build chain.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const OUT_DIR = path.join(ROOT, 'pi', 'package-skills');
+// #5569: the converted Pi role files the package's gsd_dispatch reads (ADR-5559 amendment).
+const ROLES_DIR = path.join(ROOT, 'pi', 'package-agents');
+const ROLES_MANIFEST = 'manifest.json';
+const INSTALLER = path.join(ROOT, 'bin', 'install.js');
+const PI_ENGINE_ROOT_TOKEN = '__GSD_PI_ENGINE_ROOT__';
+const INSTALL_BOUND_MS = 30000;
+
+/** Forward-slash form of a path; the installer emits either form depending on platform. */
+function toSlash(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+/**
+ * Replace every occurrence of `root` (raw and forward-slash forms) with the token.
+ * @param {string} content
+ * @param {string} root
+ */
+function tokenizeSkill(content, root) {
+  // The installer may print either the path it was given or its symlink-resolved form (/private/var on macOS).
+  let real = root;
+  try { real = fs.realpathSync(root); } catch { /* removed already: only the given form */ }
+  const forms = [...new Set([root, toSlash(root), real, toSlash(real)])].sort((a, b) => b.length - a.length);
+  let out = content;
+  for (const form of forms) out = out.split(form).join(PI_ENGINE_ROOT_TOKEN);
+  return out;
+}
+
+/**
+ * Render a template for an engine root. The root is substituted in its
+ * forward-slash form, which is what the installer writes for the Pi skills.
+ * @param {string} template
+ * @param {string} engineRoot
+ */
+function renderSkillTemplate(template, engineRoot) {
+  return template.split(PI_ENGINE_ROOT_TOKEN).join(toSlash(engineRoot));
+}
+
+/**
+ * Run the installer for Pi into a fresh temp dir and return that dir. The run
+ * gets a separate throwaway HOME (removed straight after): the two must differ,
+ * because the installer writes a config dir that equals or sits under HOME as
+ * `~`/`$HOME`-relative paths.
+ */
+function installIntoTemp() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-pi-skills-'));
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-pi-home-'));
+  const res = spawnSync(process.execPath, [INSTALLER, '--pi', '--global', '--config-dir', tmp], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    timeout: INSTALL_BOUND_MS,
+    windowsHide: true,
+    // HOME is redirected too: the installer writes GSD's global defaults store under
+    // $HOME/.gsd, and a generator run must not touch the developer's real one.
+    // GSD_ARGS_NONCE_OFF keeps the templates canonical: they ship in the package, so a per-install
+    // nonce stamped here would be a build-time constant and would change on every generation.
+    env: { ...process.env, PI_CODING_AGENT_DIR: tmp, HOME: home, USERPROFILE: home, GSD_HOME: home, GSD_ARGS_NONCE_OFF: '1' },
+  });
+  fs.rmSync(home, { recursive: true, force: true });
+  if (res.status !== 0) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    throw new ExitError(
+      1,
+      `gen-pi-package-skills: installer failed (${res.error ? res.error.message : `exit ${res.status}`}).\n` +
+      `${(res.stderr || res.stdout || '').slice(-1500)}\nRun \`npm run build:lib\` first.`,
+    );
+  }
+  return tmp;
+}
+
+/**
+ * The role templates and their hash manifest, from an installed `agents/` dir. Roles `@`-reference
+ * files under the engine root, so like the skills they ship with PI_ENGINE_ROOT_TOKEN in place of the
+ * install path; gsd_dispatch verifies the template bytes against this manifest, then renders the root.
+ * @returns {{ roles: { name: string, content: string }[], manifest: string }}
+ */
+function collectRoles(tmp) {
+  const dir = path.join(tmp, 'agents');
+  const roles = fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => e.name)
+    .sort()
+    .map((name) => ({ name, content: tokenizeSkill(fs.readFileSync(path.join(dir, name), 'utf8'), tmp) }));
+  const files = {};
+  for (const { name, content } of roles) files[name] = crypto.createHash('sha256').update(content).digest('hex');
+  return { roles, manifest: `${JSON.stringify({ files }, null, 2)}\n` };
+}
+
+/** @returns {{ templates: { skillName: string, content: string }[], roles: { name: string, content: string }[], manifest: string }} */
+function generateAll() {
+  const tmp = installIntoTemp();
+  try {
+    const skillsDir = path.join(tmp, 'skills');
+    const names = fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('gsd-'))
+      .map((e) => e.name)
+      .sort();
+    const templates = names.map((skillName) => ({
+      skillName,
+      content: tokenizeSkill(fs.readFileSync(path.join(skillsDir, skillName, 'SKILL.md'), 'utf8'), tmp),
+    }));
+    return { templates, ...collectRoles(tmp) };
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/** @returns {{ skillName: string, content: string }[]} sorted by skill name */
+function generateTemplates() {
+  return generateAll().templates;
+}
+
+function main() {
+  const args = new Set(process.argv.slice(2));
+  const { templates: results, roles, manifest } = generateAll();
+
+  if (args.has('--write')) {
+    fs.rmSync(ROLES_DIR, { recursive: true, force: true });
+    fs.mkdirSync(ROLES_DIR, { recursive: true });
+    for (const { name, content } of roles) fs.writeFileSync(path.join(ROLES_DIR, name), content);
+    fs.writeFileSync(path.join(ROLES_DIR, ROLES_MANIFEST), manifest);
+    fs.rmSync(OUT_DIR, { recursive: true, force: true });
+    for (const { skillName, content } of results) {
+      fs.mkdirSync(path.join(OUT_DIR, skillName), { recursive: true });
+      fs.writeFileSync(path.join(OUT_DIR, skillName, 'SKILL.md'), content);
+    }
+    process.stdout.write(`gen-pi-package-skills: wrote ${results.length} templates to ${path.relative(ROOT, OUT_DIR)}/ and ${roles.length} roles to ${path.relative(ROOT, ROLES_DIR)}/\n`);
+    return 0;
+  }
+
+  if (args.has('--check')) {
+    if (!fs.existsSync(OUT_DIR)) {
+      throw new ExitError(1, 'gen-pi-package-skills: pi/package-skills/ missing. Run: npm run gen:pi-package-skills');
+    }
+    let stale = 0;
+    const expected = new Set(results.map((r) => r.skillName));
+    for (const { skillName, content } of results) {
+      const file = path.join(OUT_DIR, skillName, 'SKILL.md');
+      if (!fs.existsSync(file)) {
+        process.stderr.write(`gen-pi-package-skills: missing ${path.relative(ROOT, file)}\n`);
+        stale++;
+      } else if (fs.readFileSync(file, 'utf8') !== content) {
+        process.stderr.write(`gen-pi-package-skills: stale ${path.relative(ROOT, file)}\n`);
+        stale++;
+      }
+    }
+    for (const e of fs.readdirSync(OUT_DIR, { withFileTypes: true })) {
+      if (e.isDirectory() && !expected.has(e.name)) {
+        process.stderr.write(`gen-pi-package-skills: stale (no source) ${path.relative(ROOT, path.join(OUT_DIR, e.name))}\n`);
+        stale++;
+      }
+    }
+    const wantRoles = new Map([...roles.map((r) => [r.name, r.content]), [ROLES_MANIFEST, manifest]]);
+    const haveRoles = fs.existsSync(ROLES_DIR) ? fs.readdirSync(ROLES_DIR) : [];
+    for (const [name, content] of wantRoles) {
+      const file = path.join(ROLES_DIR, name);
+      if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) {
+        process.stderr.write(`gen-pi-package-skills: stale ${path.relative(ROOT, file)}\n`);
+        stale++;
+      }
+    }
+    for (const name of haveRoles) {
+      if (!wantRoles.has(name)) {
+        process.stderr.write(`gen-pi-package-skills: stale (no source) ${path.relative(ROOT, path.join(ROLES_DIR, name))}\n`);
+        stale++;
+      }
+    }
+    if (stale > 0) {
+      throw new ExitError(1, `gen-pi-package-skills: ${stale} stale template(s). Run: npm run gen:pi-package-skills`);
+    }
+    process.stdout.write(`gen-pi-package-skills: ${results.length} templates up to date\n`);
+    return 0;
+  }
+
+  process.stdout.write(
+    `gen-pi-package-skills: would write ${results.length} templates to ${path.relative(ROOT, OUT_DIR)}/\n` +
+    '  (use --write to generate, --check to verify staleness)\n',
+  );
+  return 0;
+}
+
+module.exports = { PI_ENGINE_ROOT_TOKEN, tokenizeSkill, renderSkillTemplate, toSlash, generateTemplates, generateAll };
+
+if (require.main === module) runMain(main);