session-orchestrator 3.24.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/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;
 
@@ -327,6 +477,17 @@ runCheck('check-doc-cli-commands.mjs');
 // 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

package/scripts/validate-wave-scope.mjs

@@ -73,6 +73,7 @@ import path from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { warn } from './lib/common.mjs';
+import { MANIFEST_SESSION_KEYS } from './lib/session-identity/own-session.mjs';
 import {
   assertFileScopeSubset,
   assertTestSiblingCoverage,
@@ -289,10 +290,13 @@ function validateOptionalSessionId(obj, key, errors) {
 }
 
 /**
- * Validate the OPTIONAL session binding (#1123): `session` (the raw
- * `session_id` of the session that WROTE this manifest) and its human-readable
- * twin `semantic_session`. Both come from one `sessionAttribution(repoRoot)`
- * call — see `skills/wave-executor/wave-loop.md` § Scope Manifest.
+ * Validate the OPTIONAL session binding (#1123): `session_id` (the raw session
+ * id of the session that WROTE this manifest) and its human-readable twin
+ * `semantic_session_id`. Both come from one `sessionAttribution(repoRoot)`
+ * call — see `skills/wave-executor/wave-loop.md` § Scope Manifest. The
+ * pre-#1153 spellings `session` / `semantic_session` are still ACCEPTED here
+ * (read side only, until the next minor release) — key names come from
+ * `MANIFEST_SESSION_KEYS` so the writer and every reader share one list.
  *
  * Deliberately NOT part of {@link validateRequired}, and that is a compatibility
  * constraint rather than a preference: `wave-scope.json` is a shared
@@ -306,9 +310,25 @@ function validateOptionalSessionId(obj, key, errors) {
  * @param {string[]} errors
  * @param {string[]} warnings
  */
-function validateSession(obj, errors, warnings) {
-  const present = validateOptionalSessionId(obj, 'session', errors);
-  validateOptionalSessionId(obj, 'semantic_session', errors);
+function validateSessionBinding(obj, errors, warnings) {
+  let present = false;
+  MANIFEST_SESSION_KEYS.current.forEach((key, i) => {
+    const legacyKey = MANIFEST_SESSION_KEYS.legacy[i];
+    const hasCurrent = validateOptionalSessionId(obj, key, errors);
+    const hasLegacy = validateOptionalSessionId(obj, legacyKey, errors);
+    // Both spellings of the SAME slot, disagreeing, is the one case the reader
+    // cannot resolve honestly: it silently prefers `key` and drops the other
+    // id, so a manifest that names two different sessions would classify as
+    // `own` for one of them. Name it here rather than let the preference decide.
+    if (hasCurrent && hasLegacy && obj[key] !== obj[legacyKey]) {
+      errors.push(
+        `${key} and legacy ${legacyKey} are both present with DIFFERENT values — ` +
+          'a manifest binds to exactly one session; drop the legacy key (accepted on ' +
+          'the read side only, until the next minor release, #1153)',
+      );
+    }
+    if (i === 0) present = hasCurrent || hasLegacy;
+  });
   if (!present) {
     warnings.push(
       'no session field — manifest is not session-bound (legacy, #1123), so every session sharing this ' +
@@ -749,7 +769,7 @@ function validate(
   const warnings = [];
 
   validateRequired(obj, errors);
-  validateSession(obj, errors, warnings);
+  validateSessionBinding(obj, errors, warnings);
   validateAllowedPaths(obj, errors, warnings);
   validateBlockedCommands(obj, errors);
   validateGates(obj, errors);