session-orchestrator 3.23.0 → 4.0.0

package/scripts/run-quality-gate.mjs

@@ -14,6 +14,9 @@
  *                            defaults from the policy file or built-in defaults apply.
  *   --files <f1,f2,...>      Comma-separated file list (incremental + per-file).
  *   --session-start-ref <r>  Git ref for diff base (incremental, to find changed files).
+ *   --ledger-root <path>     Repo root the telemetry event is pinned to (and the
+ *                            root session attribution is read from). Only the
+ *                            pre-push hook passes it; see the emission block below.
  *   -h, --help               Show this help and exit.
  *
  * Exit codes:
@@ -31,8 +34,8 @@
  *   scripts/lib/gates/gate-{baseline,incremental,full,per-file}.mjs
  */
 
-import { existsSync, readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
@@ -80,7 +83,7 @@ const argv = process.argv.slice(2);
 if (argv.includes('-h') || argv.includes('--help')) {
   process.stdout.write(
     'Usage: run-quality-gate.mjs --variant <variant> [--config <json-or-file>] ' +
-    '[--files <file1,file2,...>] [--session-start-ref <ref>]\n\n' +
+    '[--files <file1,file2,...>] [--session-start-ref <ref>] [--ledger-root <path>]\n\n' +
     'Variants: baseline, incremental, full-gate, per-file\n\n' +
     'Exit codes:\n' +
     '  0 — pass (non-blocking variants always exit 0)\n' +
@@ -94,6 +97,7 @@ let variant = '';
 let config = '';
 let files = '';
 let sessionStartRef = '';
+let ledgerRootArg = '';
 
 for (let i = 0; i < argv.length; i++) {
   const arg = argv[i];
@@ -114,6 +118,10 @@ for (let i = 0; i < argv.length; i++) {
       if (i + 1 >= argv.length) die('Missing value for --session-start-ref');
       sessionStartRef = argv[++i];
       break;
+    case '--ledger-root':
+      if (i + 1 >= argv.length) die('Missing value for --ledger-root');
+      ledgerRootArg = argv[++i];
+      break;
     default:
       die(`Unknown argument: ${arg}`);
   }
@@ -208,6 +216,76 @@ function suiteCountsFromGateStdout(stdout) {
   return admitSuiteCounts(test);
 }
 
+/**
+ * Lift `test.failed_files` out of a gate sub-script's JSON stdout envelope.
+ *
+ * Envelope adapter, same posture as {@link suiteCountsFromGateStdout}: it
+ * decides only whether a NAMED-FILE measurement exists, never what the names
+ * mean. `null` — never `[]` — for every non-measurement, so the caller OMITS
+ * the key instead of publishing an empty array that reads as "no file failed".
+ *
+ * Only `gate-full.mjs` publishes the key, and only when the runner printed a
+ * file-level summary; every other variant emits a bare status string.
+ *
+ * Never throws.
+ *
+ * @param {string} stdout — the gate sub-script's captured stdout.
+ * @returns {string[]|null}
+ */
+function failedFilesFromGateStdout(stdout) {
+  if (typeof stdout !== 'string' || !stdout.trim()) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  const files = parsed?.test?.failed_files;
+  if (!Array.isArray(files) || files.length === 0) return null;
+  const named = files.filter((f) => typeof f === 'string' && f.trim());
+  return named.length > 0 ? named : null;
+}
+
+/**
+ * Validate and resolve the `--ledger-root` flag (see the telemetry block below).
+ *
+ * Only the pre-push hook passes this, and it hands over a path the gate then
+ * WRITES to — so a typo must not silently create an `.orchestrator/metrics/`
+ * tree somewhere arbitrary. The check is therefore two-part: the value must be
+ * an existing DIRECTORY, and it must already contain an `.orchestrator/`
+ * directory — the marker of a root this harness has already been initialised in.
+ *
+ * The alternative check (`git rev-parse --show-toplevel` with cwd = that path,
+ * compared against the value) is rejected on cost: it spawns a process on every
+ * gate run to prove a property two `statSync` calls already prove. The one case
+ * it accepts and this one rejects — a git root that has never run the
+ * orchestrator — is precisely the case with no ledger to pin to.
+ *
+ * A bad value NEVER crashes the gate: it warns once on stderr and returns
+ * `null`, which restores the previous resolution
+ * (`CLAUDE_PROJECT_DIR ?? CODEX_PROJECT_DIR ?? repoRoot`) at the call sites.
+ * The gate's exit code is the authoritative output; telemetry is best-effort.
+ *
+ * @param {string} value — raw flag value (`''` when the flag was not passed).
+ * @returns {string|null} absolute, validated root — or `null` to fall back.
+ */
+function resolveLedgerRoot(value) {
+  const raw = (value || '').trim();
+  if (!raw) return null;
+  const abs = resolve(raw);
+  try {
+    if (statSync(abs).isDirectory() && statSync(join(abs, '.orchestrator')).isDirectory()) {
+      return abs;
+    }
+  } catch { /* falls through to the warn below */ }
+  warn(
+    `--ledger-root '${raw}' is not an initialised project root ` +
+    '(existing directory containing .orchestrator/) — falling back to the default ' +
+    'telemetry destination.',
+  );
+  return null;
+}
+
 /**
  * Resolve the active wave number from the wave-scope sidecar (#966 step 1).
  *
@@ -325,24 +403,63 @@ if (result.error && typeof result.status !== 'number') {
 // (single emission path). `sessionAttribution` is the shared helper in
 // events.mjs (#941); this CLI wrapper runs against the CWD `repoRoot`, so the
 // bare emitEvent destination (SO_PROJECT_DIR default) is correct here.
+//
+// EXCEPT under the pre-push hook, which is the one caller that runs the gate in
+// a tree that is about to be DELETED. `.husky/pre-push` materialises the tracked
+// tree into a temp dir and deliberately scrubs every `*PROJECT_DIR` name before
+// invoking the gate there, so `getProjectDir()` resolves to that temp tree (it
+// carries both a CLAUDE.md (or AGENTS.md) and a .git) and the record lands in
+// `<tmp>/.orchestrator/metrics/events.jsonl`, which the hook's EXIT trap then
+// removes. Measured 2026-09-06: a pre-push run that BLOCKED a push left no
+// `orchestrator.quality_gate.failed` line in this repo's ledger at all — the
+// gate failure was, by construction, the one event that could never be recorded.
+//
+// `--ledger-root` is that hook's channel for handing back the root it already
+// knows (`git rev-parse --show-toplevel`, read BEFORE it cds). It pins ONLY the
+// telemetry destination and the attribution root — every other path the gate
+// resolves stays inside the tree actually under test, which is the whole point
+// of the materialisation. Absent (every other caller) → unchanged behaviour:
+// `emitEvent`'s own default resolution.
+//
+// It is an ARGV FLAG and not an env var, and that is load-bearing. Measured
+// 2026-09-06 with the env-var form: `SO_GATE_LEDGER_ROOT=$tmp npx vitest run
+// tests/scripts/run-quality-gate.test.mjs -t "telemetry emission"` → `8 failed |
+// 1 passed`. The chain was: hook exports the var → `npm run quality-gate` →
+// `gate-full.mjs` spawns `npm test` → every vitest worker inherits it → the
+// suite's own gate spawns spread `...process.env`, so the pinned root outranked
+// their per-test project dir and the gate's telemetry tests wrote to the hook's
+// root. The gate that releases 4.0.0 would have blocked on itself. An env var is
+// inherited by every descendant; a flag reaches exactly one process.
+//
 // Best-effort: a telemetry failure must NEVER alter the gate's authoritative
 // exit code — which is why the counts parse also lives inside this try.
 const exitCode = result.status ?? 1;
+const ledgerRoot = resolveLedgerRoot(ledgerRootArg);
 try {
   const counts = suiteCountsFromGateStdout(gateStdout);
+  // The names behind `counts.failed`. Absent, never `[]` — see
+  // `failedFilesFromGateStdout`.
+  const failedFiles = failedFilesFromGateStdout(gateStdout);
   // Wave-scope sidecar is read from the SAME project dir the event lands in
   // (emitEvent's own destination precedence), so a tmp-scoped run cannot pick
   // up the host repo's live wave. Mirrors the hook's projectDir resolution.
   const waveNumber = resolveWaveNumber(
-    process.env.CLAUDE_PROJECT_DIR ?? process.env.CODEX_PROJECT_DIR ?? repoRoot,
+    ledgerRoot ?? process.env.CLAUDE_PROJECT_DIR ?? process.env.CODEX_PROJECT_DIR ?? repoRoot,
+  );
+  await emitEvent(
+    `orchestrator.quality_gate.${exitCode === 0 ? 'passed' : 'failed'}`,
+    {
+      variant,
+      exit_code: exitCode,
+      ...(counts ? { counts } : {}),
+      ...(failedFiles ? { failed_files: failedFiles } : {}),
+      ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
+      ...sessionAttribution(ledgerRoot ?? repoRoot),
+    },
+    // `{}` is byte-identical to omitting the argument (`opts.repoRoot ??
+    // getProjectDir()`), so the default path is untouched.
+    ledgerRoot ? { repoRoot: ledgerRoot } : {},
   );
-  await emitEvent(`orchestrator.quality_gate.${exitCode === 0 ? 'passed' : 'failed'}`, {
-    variant,
-    exit_code: exitCode,
-    ...(counts ? { counts } : {}),
-    ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
-    ...sessionAttribution(repoRoot),
-  });
 } catch { /* best-effort telemetry — gate result is authoritative */ }
 
 process.exit(exitCode);

package/scripts/site-numbers.mjs

@@ -79,6 +79,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
+import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 /** Machine-readable schema tag for the --json envelope. */
 export const SCHEMA = 'site-numbers/1';
@@ -401,10 +402,31 @@ export const METRIC_DEFS = Object.freeze([
     // Gitignored ledger (`.gitignore`: local-only observability data) — absent
     // in every fresh clone, CI checkout and tarball build.
     snapshotFallback: true,
-    source: 'grep -c . .orchestrator/metrics/sessions.jsonl',
+    // #1186: `grep -c` over-counts — sessions.jsonl is append-only, so the same
+    // physical session can carry more than one line (crash-recovery re-appends,
+    // #1068 stub/supersede pairs). readCanonicalSessions collapses those to one
+    // record per session_id before the count; see scripts/lib/sessions-canonical.mjs
+    // for the three collapse rules. `learnings` below stays a raw line count —
+    // that ledger has no session_id-shaped identity to dedupe on.
+    // Measured on THIS repo's own ledger @ 2ccea0f2: raw line count 289 vs
+    // canonical (deduped) count 278 — an over-count of 11 records, which is the
+    // bug's magnitude this migration removes.
+    source: 'grep -c . .orchestrator/metrics/sessions.jsonl   (then deduped per session_id — see readCanonicalSessions, #1186)',
     compute: (root) => {
-      const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', 'sessions.jsonl'));
-      return r === null ? null : fmtCount(r.entries);
+      const file = join(root, '.orchestrator', 'metrics', 'sessions.jsonl');
+      // Same absent/non-file guard as countJsonlEntries, kept explicit here
+      // because readCanonicalSessions returns [] (not null) on a missing ledger
+      // — collapsing that into fmtCount(0) would silently defeat the
+      // snapshotFallback precedence above (a fresh clone would report "0
+      // sessions" instead of falling back to the tracked snapshot).
+      if (!existsSync(file) || !statSync(file).isFile()) return null;
+      // Same reader every other #1186 consumer uses (autopilot.mjs,
+      // build-live-signals.mjs, telemetry/sync.mjs) — a record with no
+      // `session_id` is dropped rather than counted, because it cannot be
+      // identified for dedup. Measured @ 2ccea0f2 on this repo's own ledger:
+      // 0 such rows (raw 289 lines == 289 identified), so the drop is inert
+      // here; it only matters for a future malformed/legacy row.
+      return fmtCount(readCanonicalSessions({ filePath: file }).length);
     },
   },
   {
@@ -623,7 +645,17 @@ export function collect(root) {
   ]) {
     const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', file));
     if (r && r.malformed > 0) {
-      warnings.push(`${file}: ${r.malformed} non-empty line(s) are not valid JSON — the ${name} count includes them`);
+      // #1186: the two ledgers now disagree on what a malformed line DOES to
+      // the published count. `learnings` is still the raw countJsonlEntries
+      // total, which counts a malformed line as an entry regardless of its
+      // content. `sessions` is readCanonicalSessions, whose parse loop skips a
+      // line it cannot JSON.parse — so a malformed session line is silently
+      // ABSENT from the count rather than included in it.
+      const consequence =
+        name === 'sessions'
+          ? `they are DROPPED from the sessions count (readCanonicalSessions skips unparseable lines)`
+          : `the ${name} count includes them`;
+      warnings.push(`${file}: ${r.malformed} non-empty line(s) are not valid JSON — ${consequence}`);
     }
   }
 

package/scripts/sweep-expired-learnings.mjs

@@ -23,6 +23,7 @@
  * Usage:
  *   node scripts/sweep-expired-learnings.mjs [--prune] [--dry-run|--apply] [--json]
  *     [--grace-days N] [--entries PATH] [--file PATH] [--archive PATH]
+ *     [--appended N] [--boosted M] [--duration-ms D] [--skipped a,b] [--repo-root PATH]
  *
  * Flags:
  *   --prune           Decision-driven prune+consolidate+rewrite instead of the
@@ -40,6 +41,23 @@
  *                      store.
  *   --file PATH       Learnings store (default: .orchestrator/metrics/learnings.jsonl)
  *   --archive PATH    Archive sidecar (default: .orchestrator/metrics/learnings-archive.jsonl)
+ *   --appended N      PRUNE ONLY (#1206). New learnings written this `/evolve`
+ *                      run (Step 3.5(4)); folded into the mechanical
+ *                      `orchestrator.evolve.completed` emit alongside this
+ *                      call's own `pruned` count. Default 0.
+ *   --boosted M       PRUNE ONLY (#1206). Existing learnings reinforced this
+ *                      run (Step 3.5(2)). Default 0.
+ *   --duration-ms D   PRUNE ONLY (#1206). Elapsed ms since the run's telemetry
+ *                      start marker. Default 0.
+ *   --skipped a,b     PRUNE ONLY (#1206). Comma-separated list of optional
+ *                      steps that ran but were themselves skipped this run
+ *                      (HR-105 — e.g. `skill-evolution-off`). Default none.
+ *   --repo-root PATH  PRUNE ONLY (#1206). Repo root the
+ *                      `orchestrator.evolve.completed` record is pinned to.
+ *                      No default and NO process.cwd() fallback (#1119) — when
+ *                      omitted, no event is emitted at all (stderr WARN, exit
+ *                      code unaffected). Emission is best-effort and never
+ *                      changes this command's exit code or stdout contract.
  *
  * Exit codes:
  *   0  Success (including no-op when nothing is archive-eligible)
@@ -51,6 +69,7 @@
 import { existsSync } from 'node:fs';
 import { sweepExpiredLearnings, pruneLearnings } from './lib/learnings/expiry-sweep.mjs';
 import { readLearnings } from './lib/learnings/io.mjs';
+import { emitEvolveCompleted } from './lib/learnings/evolve-telemetry.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
 const DEFAULT_ARCHIVE = '.orchestrator/metrics/learnings-archive.jsonl';
@@ -97,6 +116,20 @@ function parseArgs(argv) {
     entries: null,
     file: DEFAULT_FILE,
     archive: DEFAULT_ARCHIVE,
+    appended: 0,
+    boosted: 0,
+    durationMs: 0,
+    skipped: [],
+    // #1119 — NO process.cwd() fallback. Most CLI callers (every test in this
+    // file except the SKILL.md-extraction fixture, which sets its own tmp
+    // `cwd`) invoke this script from the repo root without `--repo-root`; a
+    // cwd fallback would silently append synthetic `orchestrator.evolve.
+    // completed` records to the operator's REAL fleet ledger on every
+    // `--prune --apply` run in `npm test`. `emitEvolveCompleted()` already
+    // refuses to emit (stderr WARN, no throw) when repoRoot is absent — same
+    // fail-closed contract as `emitReconcileCompleted` / `express-path.mjs`.
+    repoRoot: null,
+    telemetryExplicit: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -122,6 +155,37 @@ function parseArgs(argv) {
       args.file = argv[++i];
     } else if (a === '--archive') {
       args.archive = argv[++i];
+    } else if (a === '--appended') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isInteger(v) || v < 0) {
+        usageError(`--appended requires a non-negative integer, got: ${raw}`);
+      }
+      args.appended = v;
+      args.telemetryExplicit = true;
+    } else if (a === '--boosted') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isInteger(v) || v < 0) {
+        usageError(`--boosted requires a non-negative integer, got: ${raw}`);
+      }
+      args.boosted = v;
+      args.telemetryExplicit = true;
+    } else if (a === '--duration-ms') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isFinite(v) || v < 0) {
+        usageError(`--duration-ms requires a non-negative number, got: ${raw}`);
+      }
+      args.durationMs = v;
+      args.telemetryExplicit = true;
+    } else if (a === '--skipped') {
+      const raw = argv[++i];
+      args.skipped = typeof raw === 'string' ? raw.split(',').filter((s) => s.length > 0) : [];
+      args.telemetryExplicit = true;
+    } else if (a === '--repo-root') {
+      args.repoRoot = argv[++i];
+      args.telemetryExplicit = true;
     } else if (a === '--help' || a === '-h') {
       printHelp();
       process.exit(0);
@@ -140,6 +204,12 @@ function parseArgs(argv) {
   if (!args.prune && args.entries !== null) {
     usageError('--entries is only valid with --prune');
   }
+  if (!args.prune && args.telemetryExplicit) {
+    usageError(
+      '--appended/--boosted/--duration-ms/--skipped/--repo-root are only valid with --prune ' +
+        '(the sweep path never emits orchestrator.evolve.completed)',
+    );
+  }
   return args;
 }
 
@@ -265,6 +335,26 @@ async function runPrune(args) {
     ...result,
   };
 
+  // #1206 — the ONE mechanical call site for `orchestrator.evolve.completed`:
+  // this `--prune --apply` invocation IS `/evolve analyze`'s Step 3.5(5) store
+  // write, so folding the emit in here (instead of a separate
+  // `emit-event.mjs` call in skill prose) means the event can no longer be
+  // forgotten independently of the write it reports on. Gated on `!dryRun` —
+  // a `--prune --dry-run` preview (the docs' own recommended pre-check for a
+  // hand-assembled `--entries` sidecar) never wrote anything, so it must not
+  // report a completed run either. Best-effort — never changes this
+  // command's exit code or stdout contract.
+  if (!args.dryRun) {
+    await emitEvolveCompleted({
+      repoRoot: args.repoRoot,
+      appended: args.appended,
+      boosted: args.boosted,
+      pruned: result.archived,
+      durationMs: args.durationMs,
+      skipped: args.skipped,
+    });
+  }
+
   if (args.json) {
     process.stdout.write(JSON.stringify(summary) + '\n');
   } else {

package/scripts/sync-vault-schema.mjs

@@ -141,7 +141,9 @@ function stripCommentLine(line) {
     return null;
   }
   // Single-line doc comment
-  if (trimmed.startsWith('// ') && !trimmed.startsWith('// ──')) {
+  // A bare `//` (blank line inside a canonical comment run) is a comment too —
+  // without this the generated block carried a stray `//` (measured 2026-09-03).
+  if (trimmed === '//' || (trimmed.startsWith('// ') && !trimmed.startsWith('// ──'))) {
     // Keep structural separator comments, drop narrative ones
     return null;
   }

package/scripts/telemetry.mjs

@@ -33,7 +33,7 @@ import { queueStats } from './lib/telemetry/queue.mjs';
 import { flush, buildBatch } from './lib/telemetry/sync.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
 import { readPluginVersionFromPackageJson } from './lib/bootstrap-lock-freshness.mjs';
-import { SO_PLUGIN_ROOT } from './lib/platform.mjs';
+import { getPluginRoot } from './lib/platform.mjs';
 
 const EXIT_OK = 0;
 const EXIT_USER = 1;
@@ -69,7 +69,7 @@ ENV KILL-SWITCHES
 
 /** Plugin version for `--version` — single-sourced via readPluginVersionFromPackageJson (null → 'unknown'). */
 function readPkgVersion() {
-  return readPluginVersionFromPackageJson(SO_PLUGIN_ROOT) ?? 'unknown';
+  return readPluginVersionFromPackageJson(getPluginRoot()) ?? 'unknown';
 }
 
 // ---------------------------------------------------------------------------

package/scripts/validate-plugin.mjs

@@ -94,6 +94,42 @@ function runCheck(script) {
   return result.status ?? 1;
 }
 
+/**
+ * Advisory second pass for `check-skill-script-paths.mjs` (#1208): run it a
+ * second time with `--strict-sh --json` so the flag has a run surface inside
+ * validate-plugin, without promoting `.sh` findings to blocking here — the
+ * BLOCKING `.mjs`-only call above stays exactly as it is. Same non-blocking
+ * shape as the `check-unwired-features.mjs` / `check-learning-provenance.mjs`
+ * / `check-vcs-repo-flag.mjs` calls further down (exit code deliberately
+ * ignored; `checkFailed` is never set from this call). `runCheck()` cannot be
+ * reused here because it always spawns `[script, PLUGIN_ROOT]` with no room
+ * for extra flags, so this is a small dedicated spawn instead.
+ *
+ * @returns {void}
+ */
+function runStrictShAdvisory() {
+  const result = spawnSync(
+    'node',
+    [path.join(VALIDATE_DIR, 'check-skill-script-paths.mjs'), PLUGIN_ROOT, '--strict-sh', '--json'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout || '');
+  } catch {
+    process.stdout.write(
+      '  WARN: check-skill-script-paths --strict-sh: could not parse JSON output (advisory)\n',
+    );
+    return;
+  }
+  const shDead = (parsed.findings || []).filter(
+    (f) => f.kind === 'missing-path' && f.path.endsWith('.sh'),
+  ).length;
+  process.stdout.write(
+    `  check-skill-script-paths --strict-sh: ${shDead} dead .sh citation(s) (advisory)\n`,
+  );
+}
+
 /**
  * Run the surface-count drift family (issue #663) from the claude-md-drift-check
  * checker over the doc surfaces that carry artifact counts (README.md +
@@ -175,6 +211,105 @@ function runDriftCheck() {
   return 0;
 }
 
+/**
+ * BLOCKING (#1224): the committed hook-reachable allowlist
+ * (`hooks/_lib/hook-import-set.json`) must match a fresh crawl of the four hook
+ * manifests. The allowlist is what gates `hooks/post-edit-import-probe.mjs`, so
+ * a stale set silently NARROWS that probe — a newly hook-reachable module would
+ * be edited without ever being checked, which is precisely the 2026-09-04
+ * host-wide-block incident class the probe exists to catch. A rotting allowlist
+ * is therefore a real defect, not a cosmetic drift, hence FAIL rather than WARN.
+ *
+ * `scripts/generate-hook-import-set.mjs --check` owns the comparison (it exits 1
+ * on drift); this adapter only translates it into validate-plugin's vocabulary.
+ * `runCheck()` cannot be reused — it spawns from `scripts/lib/validate/` and
+ * passes PLUGIN_ROOT positionally, while the generator takes `--plugin-root`.
+ *
+ * @returns {number} 0 when in sync, 1 on drift or a generator error.
+ */
+function runHookImportSetCheck() {
+  console.log('--- Check: hook-import-set drift (#1224) ---');
+  const script = path.join(SCRIPT_DIR, 'generate-hook-import-set.mjs');
+  const result = spawnSync(
+    process.execPath,
+    [script, '--plugin-root', PLUGIN_ROOT, '--check'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  const combined = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
+
+  // A silent exit 0 is NOT a pass. The generator's CLI entry is gated on
+  // `import.meta.url === file://${process.argv[1]}`, which does not hold when
+  // the spawned path traverses a symlink (measured: `/tmp` → `/private/tmp` on
+  // macOS makes the whole CLI body a no-op that still exits 0). Demanding the
+  // in-sync marker turns that failure mode from a silent pass into a finding.
+  const inSync = combined.match(/(\d+) modules, in sync/);
+  if (result.status === 0 && inSync) {
+    console.log(`  PASS: hook-import-set: in sync (${inSync[1]} entries)`);
+    totalPass += 1;
+    return 0;
+  }
+  if (result.status === 0) {
+    console.log('  FAIL: hook-import-set: generator exited 0 without reporting a comparison '
+      + `(no in-sync marker in output: ${JSON.stringify(combined.slice(0, 120))})`);
+    totalFail += 1;
+    return 1;
+  }
+  const detail = combined.split('\n').filter(Boolean).pop()
+    ?? `generator exited ${result.status}`;
+  console.log(`  FAIL: hook-import-set: ${detail.replace(/^✗\s*hook-import-set:\s*/, '')}`);
+  console.log('        Remedy: node scripts/generate-hook-import-set.mjs && stage hooks/_lib/hook-import-set.json');
+  totalFail += 1;
+  return 1;
+}
+
+/**
+ * BLOCKING: the cross-harness portable surface (`AGENTS.md` +
+ * `.agents/skills/`) must match a fresh generation from `CLAUDE.md` +
+ * `skills/`. 7 of 8 surveyed harnesses read `AGENTS.md` and never `CLAUDE.md`,
+ * so a stale or absent copy means those harnesses silently see NO Session
+ * Config — a failure that is invisible from inside Claude Code, which is
+ * exactly why it needs a mechanical gate rather than a convention.
+ *
+ * `scripts/generate-agents-skills.mjs --check` owns the comparison (exit 1 on
+ * drift); this adapter only translates it. `runCheck()` cannot be reused — it
+ * spawns from `scripts/lib/validate/` and passes PLUGIN_ROOT positionally,
+ * while the generator takes `--plugin-root`. The in-sync marker is demanded
+ * for the same reason `runHookImportSetCheck()` demands one: a spawn whose
+ * path traverses a symlink can make the generator's CLI body a no-op that
+ * still exits 0.
+ *
+ * @returns {number} 0 when in sync, 1 on drift or a generator error.
+ */
+function runAgentsSurfaceCheck() {
+  console.log('--- Check: cross-harness portable surface (AGENTS.md + .agents/skills/) ---');
+  const script = path.join(SCRIPT_DIR, 'generate-agents-skills.mjs');
+  const result = spawnSync(
+    process.execPath,
+    [script, '--plugin-root', PLUGIN_ROOT, '--check'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  const combined = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
+
+  const inSync = combined.match(/agents-surface: (\d+) artefact\(s\), in sync/);
+  if (result.status === 0 && inSync) {
+    console.log(`  PASS: agents-surface: in sync (${inSync[1]} artefacts)`);
+    totalPass += 1;
+    return 0;
+  }
+  if (result.status === 0) {
+    console.log('  FAIL: agents-surface: generator exited 0 without reporting a comparison '
+      + `(no in-sync marker in output: ${JSON.stringify(combined.slice(0, 120))})`);
+    totalFail += 1;
+    return 1;
+  }
+  for (const line of combined.split('\n').filter((l) => l.startsWith('✗'))) {
+    console.log(`  FAIL: ${line.replace(/^✗\s*/, '')}`);
+    totalFail += 1;
+  }
+  console.log('        Remedy: node scripts/generate-agents-skills.mjs');
+  return 1;
+}
+
 // ---------------------------------------------------------------------------
 // Run all checks — same order as validate-plugin.sh
 // plugin.json checks are prerequisite; abort early if they fail.
@@ -220,6 +355,9 @@ if (runDriftCheck() !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-hooks-symmetry.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runHookImportSetCheck() !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-guard-requires-parity.mjs') !== 0) checkFailed = 1;
 
@@ -247,6 +385,18 @@ if (runCheck('check-pi-prompts.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-cursor-adapter.mjs') !== 0) checkFailed = 1;
 
+// BLOCKING: the vendor-neutral portable surface — root AGENTS.md ↔ CLAUDE.md
+// alias, root plugin.json (agent-plugins.org 1.0.0) manifest-version parity
+// against package.json, and the .agents/skills/ mirror against the
+// agentskills.io field list. The generator's own --check runs first (below);
+// this checker is the INDEPENDENT oracle over the same artefacts, so a
+// generator bug cannot vouch for its own output.
+process.stdout.write('\n');
+if (runCheck('check-agents-skills.mjs') !== 0) checkFailed = 1;
+
+process.stdout.write('\n');
+if (runAgentsSurfaceCheck() !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-session-plan-routing.mjs') !== 0) checkFailed = 1;
 
@@ -318,6 +468,27 @@ runCheck('check-vcs-repo-flag.mjs');
 process.stdout.write('\n');
 runCheck('check-doc-cli-commands.mjs');
 
+// BLOCKING (#1176): a `scripts/**.mjs` path cited in skills/, commands/ or
+// agents/ prose that does not exist. Unlike the WARN-only check above, the
+// oracle is this repository's own filesystem — no version skew of a foreign
+// binary can red an unrelated commit, so a finding is always a real defect.
+// A deliberately absent path is annotated in place:
+// `<!-- path-check: planned #<iid> | historical | example -->`, honoured on the
+// citation's own line or the line immediately above.
+process.stdout.write('\n');
+if (runCheck('check-skill-script-paths.mjs') !== 0) checkFailed = 1;
+runStrictShAdvisory();
+
+// BLOCKING (#1157 follow-up): a relative markdown link under skills/, commands/,
+// agents/ or .claude/rules/ that does not resolve from the LINKING file's own
+// directory. The check above judges cited SCRIPT paths; this one judges links
+// between the instruction files themselves — the defect class a `references/`
+// split creates, where the moved text is byte-identical and every `./sibling.md`
+// in it now points one directory too deep. Three such links shipped broken on
+// 2026-09-06 and no gate saw them; the worst silently detached the six
+// session-end tail phases from their dispatcher.
+if (runCheck('check-skill-links.mjs') !== 0) checkFailed = 1;
+
 // WARN-only: a state-mutating `git` call in tests/ that names no target resolves
 // its destination from the ambient cwd (or an inherited GIT_DIR) — the 2026-08-19
 // incident, where fixture commits, a fixture remote and a fixture identity landed
@@ -337,6 +508,22 @@ runCheck('check-doc-cli-commands.mjs');
 process.stdout.write('\n');
 runCheck('check-test-git-config-target.mjs');
 
+// BLOCKING (#1183): every `emitEvent()` call site under hooks/**/*.mjs must be
+// try/catch-guarded (emitEvent() throws EventValidationError on a malformed
+// record — an unguarded call aborts the hook process). Five pre-existing
+// unguarded sites are baselined inside the checker itself and report WARN,
+// never FAIL, so this can be blocking-by-default without going red on
+// arrival; only a NEW unguarded site fails the build.
+process.stdout.write('\n');
+if (runCheck('check-hooks-emit-event-guard.mjs') !== 0) checkFailed = 1;
+
+// BLOCKING (#1184): every scripts/lib/validate/check-*.mjs must be referenced
+// by basename from this file, .husky/pre-commit, or .gitlab-ci.yml — or carry
+// a `// registration: standalone <reason>` header marker declaring itself
+// deliberately CLI-only. A checker nobody runs is built work with no effect.
+process.stdout.write('\n');
+if (runCheck('check-validator-registration.mjs') !== 0) checkFailed = 1;
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------