session-orchestrator 5.1.0 → 5.3.0

package/scripts/sweep-expired-rules.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * sweep-expired-rules.mjs — CLI for the generated-rule expiry sweep (#1377).
+ *
+ * The sibling of `scripts/sweep-expired-learnings.mjs`, one corpus over:
+ * that one moves expired LEARNINGS out of `learnings.jsonl`, this one removes
+ * expired ENTRIES from the consolidated `.claude/rules/*.md` files that were
+ * generated from them. `scripts/lib/rule-loader.mjs` already refuses to inject
+ * an expired generated rule; nothing until now removed one from disk.
+ *
+ * All planning and writing logic lives in
+ * `scripts/lib/reconcile/rule-expiry-sweep.mjs`
+ * (`planRuleExpirySweep` / `applyRuleExpirySweep`). This file is argv parsing,
+ * output formatting, the event emit, and exit codes — nothing else.
+ *
+ * SAFETY: `--dry-run` is the DEFAULT and writes nothing. `--apply` is the only
+ * write path, and it rewrites or deletes TRACKED files under `.claude/rules/`.
+ *
+ * Usage:
+ *   node scripts/sweep-expired-rules.mjs [--dry-run|--apply] [--json]
+ *     [--grace-days N] [--now ISO] [--repo-root PATH] [--learnings PATH]
+ *
+ * Exit codes (the same contract as the learnings sweep CLI, deliberately —
+ * two sibling commands with inverted codes is a trap for the operator who
+ * learns one of them):
+ *   0  Success, including the no-op when nothing is expired
+ *   1  Usage/invocation error (bad flag or value)
+ *   2  Sweep error (an I/O or validation failure inside the lib, or any
+ *      per-file error on the `--apply` path)
+ */
+
+import { emitEvent } from './lib/events.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import {
+  RULE_EXPIRY_SWEEP_EVENT,
+  applyRuleExpirySweep,
+  planRuleExpirySweep,
+} from './lib/reconcile/rule-expiry-sweep.mjs';
+
+const DEFAULT_GRACE_DAYS = 0;
+
+function printHelp() {
+  process.stdout.write(
+    `Usage: node scripts/sweep-expired-rules.mjs [--dry-run|--apply] [--json] [--grace-days N] [--now ISO] [--repo-root PATH] [--learnings PATH]
+
+Removes EXPIRED entries from the consolidated machine-generated rule files in
+.claude/rules/. An expired entry's prose block is deleted; its "## Provenance"
+pair is KEPT as a "markers only" bullet, because /reconcile dedupes on those
+markers and dropping one re-proposes the learning. A file is deleted only when
+every substantive entry expired, and every provenance key is stamped terminal
+before the unlink.
+
+Options:
+  --dry-run         Preview the plan; write nothing (DEFAULT)
+  --apply           Perform the rewrites/deletes and emit the ledger event
+  --json            Emit a single machine-parseable JSON summary line
+  --grace-days N    Days past expiry before an entry is swept (default: ${DEFAULT_GRACE_DAYS})
+  --now ISO         Injected clock (testing / what-if planning)
+  --repo-root PATH  Repo root (default: process.cwd())
+  --learnings PATH  Learnings store, repo-relative (default: the metrics store)
+
+Exit codes:  0 success  1 usage/invocation error  2 sweep error
+`,
+  );
+}
+
+/** Exit 1 with a diagnostic on stderr (usage/invocation errors). */
+function usageError(message) {
+  process.stderr.write(`sweep-expired-rules: ${message}\n`);
+  process.exit(1);
+}
+
+export function parseArgs(argv) {
+  const args = {
+    dryRun: true,
+    json: false,
+    graceDays: DEFAULT_GRACE_DAYS,
+    now: null,
+    repoRoot: process.cwd(),
+    learnings: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--apply') args.dryRun = false;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--json') args.json = true;
+    else if (a === '--grace-days') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isFinite(v) || v < 0) {
+        usageError(`--grace-days requires a non-negative number, got: ${raw}`);
+      }
+      args.graceDays = v;
+    } else if (a === '--now') {
+      const raw = argv[++i];
+      if (typeof raw !== 'string' || !Number.isFinite(Date.parse(raw))) {
+        usageError(`--now requires an ISO timestamp, got: ${raw}`);
+      }
+      args.now = raw;
+    } else if (a === '--repo-root') {
+      const raw = argv[++i];
+      if (typeof raw !== 'string' || raw.length === 0) usageError('--repo-root requires a path');
+      args.repoRoot = raw;
+    } else if (a === '--learnings') {
+      const raw = argv[++i];
+      if (typeof raw !== 'string' || raw.length === 0) usageError('--learnings requires a path');
+      args.learnings = raw;
+    } else if (a === '--help' || a === '-h') {
+      printHelp();
+      process.exit(0);
+    } else {
+      usageError(`unknown argument: ${a}`);
+    }
+  }
+  return args;
+}
+
+/**
+ * Roll the plan up into the summary both output modes render.
+ *
+ * `header_raises` is additive (#1388 P7): a header-raise is an
+ * `action: 'rewrite'` plan carrying `reason: 'header-raise'`, so it was counted
+ * inside `rewrites` and invisible on the human stdout line although `--json`
+ * always carried `plans[].reason`. It is a SUBSET of `rewrites`, never a
+ * sibling category — the two are deliberately not disjoint.
+ */
+export function summarize(plan, args, applied) {
+  const counts = { rewrite: 0, delete: 0, keep: 0 };
+  for (const p of plan.plans) counts[p.action] = (counts[p.action] ?? 0) + 1;
+  const headerRaises = plan.plans.filter((p) => p.reason === 'header-raise').length;
+  return {
+    dry_run: args.dryRun,
+    grace_days: args.graceDays,
+    files_scanned: plan.plans.length,
+    rewrites: counts.rewrite,
+    header_raises: headerRaises,
+    deletes: counts.delete,
+    keeps: counts.keep,
+    expired_entries: plan.plans.reduce((n, p) => n + p.expiredPairIds.length, 0),
+    unresolved_pairs: plan.plans.reduce((n, p) => n + p.unresolvedPairIds.length, 0),
+    malformed_lines: plan.malformedLines,
+    rules_dir_readable: plan.ok,
+    skipped: plan.skipped,
+    plans: plan.plans.map(({ nextContent: _nextContent, ...rest }) => rest),
+    ...(applied ? { applied } : {}),
+  };
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+
+  let plan;
+  try {
+    plan = await planRuleExpirySweep({
+      repoRoot: args.repoRoot,
+      now: args.now ?? undefined,
+      graceDays: args.graceDays,
+      learningsPath: args.learnings ?? undefined,
+    });
+  } catch (err) {
+    process.stderr.write(`sweep-expired-rules: planning failed: ${err?.message ?? err}\n`);
+    process.exit(2);
+  }
+
+  let applied = null;
+  if (!args.dryRun) {
+    applied = applyRuleExpirySweep(plan, { repoRoot: args.repoRoot, now: args.now ?? undefined });
+  }
+
+  const summary = summarize(plan, args, applied);
+
+  if (args.json) process.stdout.write(`${JSON.stringify(summary)}\n`);
+  else {
+    process.stdout.write(
+      `sweep-expired-rules: ${args.dryRun ? 'dry-run' : 'applied'} — ` +
+        `${summary.files_scanned} generated rule file(s), ${summary.rewrites} rewrite(s) ` +
+        `(${summary.header_raises} header-raise(s)), ` +
+        `${summary.deletes} delete(s), ${summary.expired_entries} expired entr(ies), ` +
+        `${summary.unresolved_pairs} unresolved pair(s), ${summary.skipped.length} skipped, ` +
+        `${summary.malformed_lines} malformed learnings line(s)\n`,
+    );
+    for (const s of plan.skipped) process.stdout.write(`  skipped ${s.file}: ${s.reason}\n`);
+    for (const p of plan.plans) {
+      if (p.advisory) process.stdout.write(`  advisory ${p.file}: ${p.advisory}\n`);
+    }
+  }
+
+  if (applied) {
+    for (const e of applied.errors) {
+      process.stderr.write(`sweep-expired-rules: ${e.file}: ${e.error}\n`);
+    }
+    // Emitted on apply ONLY, and AFTER the writes: a record's presence is proof
+    // that `.claude/rules/` was actually changed, never that a preview ran.
+    // Wrapped because `emitEvent` THROWS `EventValidationError` — a telemetry
+    // failure must not turn a completed sweep into a non-zero exit.
+    try {
+      await emitEvent(
+        RULE_EXPIRY_SWEEP_EVENT,
+        {
+          rewritten: applied.rewritten.length,
+          deleted: applied.deleted.length,
+          stamped: applied.stamped,
+          write_errors: applied.errors.length,
+          expired_entries: summary.expired_entries,
+          files_scanned: summary.files_scanned,
+          source: 'sweep-expired-rules-cli',
+        },
+        { repoRoot: args.repoRoot },
+      );
+    } catch (err) {
+      process.stderr.write(`sweep-expired-rules: event emit failed: ${err?.message ?? err}\n`);
+    }
+    if (applied.errors.length > 0) process.exit(2);
+  }
+
+  if (!plan.ok) {
+    process.stderr.write(
+      'sweep-expired-rules: .claude/rules/ exists but could not be enumerated — ' +
+        'the plan above is INCOMPLETE, not clean.\n',
+    );
+    process.exit(2);
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  await main(process.argv.slice(2));
+}

package/scripts/validate-plugin.mjs

@@ -424,6 +424,27 @@ if (runCheck('check-unicode-safety.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-dead-bridge.mjs') !== 0) checkFailed = 1;
 
+// BLOCKING (#1371): a hand-written `process.argv[1] === import.meta.url` entry
+// guard is false under any symlinked invocation, so main() never runs and the
+// process still exits 0 — the caller reads silence as success. This can block
+// honestly because the backlog was drained to zero in the same change: the check
+// is not red on arrival for work nobody intends to do (contrast the WARN-only
+// censuses below, each of which had a standing backlog when it landed).
+process.stdout.write('\n');
+if (runCheck('check-entry-guard.mjs') !== 0) checkFailed = 1;
+
+// BLOCKING (#1422), the complement of the check above: `check-entry-guard`
+// judges the FORM of a guard that already exists, so a registered hook with NO
+// guard at all passes it trivially — the #1393 regression class exactly. This
+// one asks the other half of the question over the union of the four platform
+// manifests: does every registered hook run its entry only under
+// `isMainModule(import.meta.url)` / `invokedAsScript()`, and does no profile
+// gate sit at module top level where its `process.exit(0)` kills a mere
+// importer. Blocking honestly: 27/27 registered hooks were guarded at the
+// moment it landed, because #1393 drained the backlog first.
+process.stdout.write('\n');
+if (runCheck('check-hook-entry-guards.mjs') !== 0) checkFailed = 1;
+
 // FAIL-capable, unlike the WARN-only censuses below: R2+R4 were measured at
 // 1 hit / 1 TP / 0 FP each against the full test corpus, so this check cannot be
 // red on arrival for anything but a real instance of the class. The alternatives

package/scripts/validate-wave-scope.mjs

@@ -69,7 +69,6 @@
  *   2 — I/O error (file not found, unreadable stdin, unreadable sidecar file)
  */
 
-import path from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { warn } from './lib/common.mjs';
@@ -86,6 +85,17 @@ import {
   // which roles are allowed to grant zero paths.
   isReadOnlyWaveRole,
   READ_ONLY_WAVE_ROLES,
+  // #1398 cond. 4 / #1405 / #1406 — THE grading predicate for an absolute Gate 5b
+  // grant. Lives in scope-gate.mjs so this CLI and `hooks/enforce-scope.mjs`
+  // grade one and the same way (BV-003): before the move, only this CLI could
+  // grade at all, so the hook honoured grants the CLI would have refused and a
+  // manifest that skipped the CLI was never graded.
+  gradeScopeEntry,
+  // #1398 cond. 4 — the `resolve` injection the predicate above takes. Moved
+  // into scope-gate.mjs (from a private copy here) once the hot-path cost was
+  // measured rather than assumed, so this CLI and `hooks/enforce-scope.mjs` pass
+  // the SAME resolver and can no longer reach different verdicts for one grant.
+  canonicalizeGrantPrefix,
   // Aliased: `expandTestSiblings` is ALSO the name of the pre-existing
   // boolean parameter threaded through validate()/assertSubsetOrDie for the
   // #970 flag. Aliasing the import avoids shadowing that parameter rather than
@@ -338,79 +348,6 @@ function validateSessionBinding(obj, errors, warnings) {
   }
 }
 
-/**
- * Literal filesystem-root forms — POSIX "/" and the Windows equivalents "\"
- * and a bare drive root ("C:\", "C:\\", ...). Checked independently of
- * `path.isAbsolute()` because that primitive is platform-native: on a POSIX
- * host (this repo's dev/CI hosts) it never reports `C:\` as absolute, so a
- * Windows-literal-root entry would otherwise slip past every check below.
- * @type {ReadonlySet<string>}
- */
-const FILESYSTEM_ROOT_LITERALS = new Set(['/', '\\']);
-const WINDOWS_DRIVE_ROOT_RE = /^[A-Za-z]:\\+$/;
-
-/**
- * @param {string} entry
- * @returns {boolean}
- */
-function isFilesystemRootLiteral(entry) {
-  return FILESYSTEM_ROOT_LITERALS.has(entry) || WINDOWS_DRIVE_ROOT_RE.test(entry);
-}
-
-/**
- * Well-known top-level system/home directories. A FIXED DENYLIST (not a
- * segment-count threshold): the #792 legitimate grant
- * (`/private/tmp/<session>/scratchpad/**`) is itself a single-segment-deep
- * grant under an unusual root ("private"), so any segment-count heuristic
- * tight enough to catch `/etc/**` risks catching that too, or must be tuned
- * loosely enough to leave a gap. A fixed list of the directories a
- * hallucinated/mis-copied wave-scope entry could plausibly land on is
- * predictable, auditable in a one-line diff, and does not touch legitimate
- * deep grants under any other root.
- * @type {ReadonlySet<string>}
- */
-const DENIED_ABSOLUTE_TOP_SEGMENTS = new Set([
-  'etc',
-  'Users',
-  'home',
-  'root',
-  'bin',
-  'sbin',
-  'usr',
-  'System',
-  'var',
-  'boot',
-  'dev',
-  'proc',
-  'sys',
-  'Library',
-  'Applications',
-  'Windows',
-]);
-
-/**
- * The top-level path segment of an absolute POSIX-style entry (the segment
- * immediately after the leading "/"), if it is on the denylist above.
- * @param {string} entry
- * @returns {string|null}
- */
-function deniedTopSegment(entry) {
-  const first = entry.split('/').filter(Boolean)[0];
-  return first && DENIED_ABSOLUTE_TOP_SEGMENTS.has(first) ? first : null;
-}
-
-/**
- * Does this entry contain a glob wildcard? Mirrors this codebase's own glob
- * convention (`isGlobScopeEntry` in scripts/lib/scope-gate.mjs / #796): `*`
- * is the sole wildcard metachar used in allowedPaths/fileScope entries
- * throughout this repo (no `?`/`[]`/`{}` glob syntax is supported or tested
- * anywhere else in scope-gate.mjs or enforce-scope.mjs).
- * @param {string} entry
- * @returns {boolean}
- */
-function hasWildcard(entry) {
-  return entry.includes('*');
-}
 
 /**
  * Validate allowedPaths array: must exist, be an array of non-empty strings,
@@ -463,37 +400,27 @@ function validateAllowedPaths(obj, errors, warnings) {
       errors.push('allowedPaths contains empty string');
       continue;
     }
-    // #870: an explicit absolute entry is a SANCTIONED out-of-repo grant — mirrors
-    // hooks/enforce-scope.mjs Gate 5b (matchesAbsoluteAllowlist), which honours ANY
-    // syntactically-absolute allowedPaths entry (path.isAbsolute) against the
-    // realpath-resolved write candidate. Using `path.isAbsolute` (not a hand-rolled
-    // `startsWith('/')`) keeps the same platform-native semantics Gate 5b uses.
-    // WARN, not reject — the validator must not contradict the hook it validates
-    // for (#792 / #870) — EXCEPT for the narrow catastrophic subclass below
-    // (#870-followup), which hard-rejects regardless of what Gate 5b would do
-    // with it: pre-flight validation exists precisely to catch a grant this bad
-    // before the hook is ever consulted.
-    if (path.isAbsolute(entry) || isFilesystemRootLiteral(entry)) {
-      if (isFilesystemRootLiteral(entry)) {
-        errors.push(
-          `allowedPaths grants the entire filesystem root: ${entry} — refused unconditionally, this can never be a valid wave scope`,
-        );
-      } else {
-        const denied = deniedTopSegment(entry);
-        if (denied) {
-          errors.push(
-            `allowedPaths contains a well-known system/home directory grant: ${entry} (top-level segment "${denied}" is denylisted) — refused, scope a narrower path instead`,
-          );
-        } else if (!hasWildcard(entry)) {
-          errors.push(
-            `allowedPaths contains a bare absolute file grant with no wildcard: ${entry} — a single concrete out-of-repo file has no established legitimate use in this codebase; scope a glob instead`,
-          );
-        } else {
-          warnings.push(
-            `allowedPaths contains an absolute (out-of-repo) path: ${entry} — honoured by hooks/enforce-scope.mjs Gate 5b; verify this grant is intentional`,
-          );
-        }
-      }
+    // #870 / #1398 / #1405 / #1406 — grade the entry as a Gate 5b grant through
+    // the SHARED predicate (`scripts/lib/scope-gate.mjs` gradeScopeEntry), the
+    // same one `hooks/enforce-scope.mjs` Gate 5b calls. Most absolute entries are
+    // a SANCTIONED out-of-repo grant and only WARN — the validator must not
+    // contradict the hook it validates for (#792/#870) — while the catastrophic
+    // subclasses (filesystem root, denylisted system directory in either its
+    // literal or its canonical spelling, a home grant at or above the user level
+    // or into a credential directory, a tilde that nothing expands, and a
+    // non-canonical prefix Gate 5b can never match) hard-reject here, BEFORE the
+    // hook is ever consulted. `null` = an ordinary relative entry, nothing to say.
+    //
+    // SAME PREDICATE, SAME RESOLVER (#1398 cond. 4). The resolver used to live
+    // here, which made the two callers' ARGUMENT shapes differ and let one grant
+    // reach two verdicts (`/tmp/x/**`: hook `warn`, this CLI `error`). Since the
+    // hot-path cost was measured (+0.067 ms per Gate 5b hit — see
+    // {@link canonicalizeGrantPrefix}) both callers pass this exact function, so
+    // the only remaining asymmetry is the CONSEQUENCE: exit-1 refusal here,
+    // allow-with-notice there.
+    const grade = gradeScopeEntry(entry, { resolve: canonicalizeGrantPrefix });
+    if (grade !== null) {
+      (grade.verdict === 'error' ? errors : warnings).push(`allowedPaths ${grade.message}`);
     }
     // Reject path traversal: any `../` segment. INDEPENDENT of the absolute checks
     // above — an absolute entry that ALSO contains `../` must still be rejected

package/scripts/vault-consolidate.mjs

@@ -84,7 +84,6 @@
 
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { die, utcTimestamp, expandTilde } from './lib/common.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
@@ -96,6 +95,7 @@ import {
   stageBackup,
   compressAndCleanupBackup,
 } from './lib/vault-consolidate-fs.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_SOURCE = '~/Projects/vault';
 const DEFAULT_CANONICAL = '~/Projects/Bernhard/vault';
@@ -580,7 +580,7 @@ async function main() {
 // `process.argv[1]` is undefined when the module is loaded via `node -e
 // "import(...)"` (no script path in argv), so guard against it before calling
 // pathToFileURL — otherwise the import itself throws ERR_INVALID_ARG_TYPE.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   main().catch((e) => {
     console.error(e);
     process.exit(1);

package/scripts/vault-mirror.mjs

@@ -53,7 +53,6 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { createReadStream } from 'node:fs';
-import { pathToFileURL } from 'node:url';
 
 import { processLearning, processSession, getMaskerStats } from './lib/vault-mirror/process.mjs';
 import { emitMirrorEvent, emitMirrorRunEvent } from './lib/vault-mirror/telemetry.mjs';
@@ -64,6 +63,7 @@ import { resolveRepoNamespace } from './lib/vault-mirror/namespace.mjs';
 import { resolveCanonicalSuffixes } from './lib/named-vault-resolver.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
 import { canonicalizeSessions } from './lib/sessions-canonical.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ── Canonical-vault helpers (#600 D2 / #607 D2) ────────────────────────────────
 // These are module-level (above the CLI bootstrap) so the module is import-safe
@@ -166,8 +166,7 @@ export function _normalizeRemote(url) {
 // (`node vault-mirror.mjs ...`). When imported from a unit test, argv belongs to
 // the test runner — parsing it would spuriously process.exit. The exported
 // helpers above are unaffected by this guard.
-const _isDirectInvocation =
-  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+const _isDirectInvocation =isMainModule(import.meta.url);
 
 if (_isDirectInvocation) {
   let parsedFlags;
@@ -486,6 +485,10 @@ async function main() {
     kind,
     force,
     vaultName,
+    // #1389: the repo whose `.vault.yaml` declares the namespace slug. This CLI
+    // has no repo-root flag, so it is the invocation cwd — bound ONCE here and
+    // shared by every processor call and the auto-commit below.
+    repoRoot: process.cwd(),
     qualityMinNarrativeChars,
     qualityMinConfidence,
   };
@@ -694,7 +697,11 @@ async function main() {
   // Opt-in: triggers only when --session-id is provided. Callers (session-end, evolve)
   // pass it explicitly; bare invocations stay quiet to preserve legacy behaviour.
   if (!dryRun && !noCommit && sessionIdArg) {
-    autoCommitVaultMirror(resolve(vaultDir), sessionIdArg, resolveRepoNamespace({ vaultName }));
+    autoCommitVaultMirror(
+      resolve(vaultDir),
+      sessionIdArg,
+      resolveRepoNamespace({ vaultName, repoRoot: ctx.repoRoot }),
+    );
   }
 }
 

package/scripts/wave-scope-binding.mjs

@@ -37,10 +37,9 @@
  */
 
 import { parseArgs } from 'node:util';
-import { resolve as resolvePath } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { attributionForRecord, emitEvent } from './lib/events.mjs';
 import { MANIFEST_SESSION_KEYS } from './lib/session-identity/own-session.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const HELP = `Usage: node scripts/wave-scope-binding.mjs [--merge] [--wave N] [--role R] [--repo-root DIR]
 
@@ -210,6 +209,6 @@ function readStdin() {
 
 // `import.meta.main` is not available on every supported Node — compare argv[1]
 // instead, so importing this module from a test never runs the CLI.
-if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
+if (isMainModule(import.meta.url)) {
   await main(process.argv.slice(2));
 }

package/skills/_shared/bootstrap-gate.md

@@ -102,7 +102,7 @@ source: projects-baseline | plugin-template | claude-init
 
 A repo that has already been bootstrapped passes the gate on every subsequent invocation with zero overhead. The gate check reads three files and performs two grep operations — negligible cost.
 
-`/bootstrap --retroactive` exists for repos that predate the gate (have `CLAUDE.md` + Session Config but no `bootstrap.lock`). It writes the lock without re-scaffolding. Documented in `commands/bootstrap.md`.
+`/bootstrap --retroactive` exists for repos that predate the gate (have `CLAUDE.md` + Session Config but no `bootstrap.lock`). It writes the lock without re-scaffolding. Documented in `skills/bootstrap/SKILL.md`.
 
 ## Auto-Skill Dispatch (opt-in, default: off)
 

package/skills/_shared/monitor-patterns.md

@@ -23,7 +23,7 @@ coverage check.
 
 ## Pattern 1 — GitLab pipeline + GitHub mirror sync (post-push)
 
-**When.** After `git push origin main` from `commands/close.md` Phase 6.
+**When.** After `git push origin main` from `skills/close/SKILL.md` Phase 6.
 Watches the GitLab pipeline through to a terminal status, then prints
 the GitHub mirror's main-branch SHA so the operator can confirm parity.
 

package/skills/_shared/platform-tools.md

@@ -8,15 +8,17 @@ The current platform is determined by the `scripts/lib/platform.mjs` library:
 - `$SO_PLATFORM` = `claude` | `codex` | `cursor` | `pi`
 - Environment: `$CLAUDE_PLUGIN_ROOT` (Claude Code), `$CODEX_PLUGIN_ROOT` (Codex CLI), `$CURSOR_RULES_DIR` (Cursor IDE), or `$PI_PLUGIN_ROOT` (Pi)
 
-## Identical Tools (no mapping needed)
-
-These tools have the same name and behavior on all platforms. Cursor IDE uses equivalent built-in tools for file operations and terminal commands.
-- **Read** — read file contents
-- **Write** — create/overwrite files
-- **Edit** — string replacement in files
-- **Bash** — execute shell commands
-- **Glob** — file pattern matching
-- **Grep** — content search (ripgrep)
+## File and Shell Tool Adaptation
+
+Skill bodies use Claude Code names as operations, not as a requirement that every
+harness expose those exact tools. Use the current runtime's available tools.
+Measured in Codex Desktop 0.153.4 on 2026-09-19: `exec_command` runs shell
+commands (`cat`, `rg`, `rg --files` for Read/Grep/Glob); `apply_patch` performs
+file edits. These may be exposed through a `functions.exec` tools namespace.
+Never call an unavailable `Read`, `Bash`, or `Skill` tool by name. An instruction
+to invoke `session-orchestrator:<name>` means read and follow the canonical
+`skills/<name>/SKILL.md` relative to the plugin root when no Skill tool exists.
+Keep the user's project as the working directory for project operations.
 
 ## Platform-Specific Tool Mapping
 
@@ -24,7 +26,7 @@ These tools have the same name and behavior on all platforms. Cursor IDE uses eq
 
 | Function | Claude Code | Codex CLI | Cursor IDE | Pi |
 |----------|------------|-----------|------------|----|
-| Present choices to user | `AskUserQuestion` tool with structured options | Numbered Markdown list as plain text, wait for user reply | Numbered Markdown list (same as Codex) | Numbered Markdown list v1; native UI adapter planned |
+| Present choices to user | `AskUserQuestion` tool with structured options | Available native user-input tool, respecting its mode restrictions; plain-text fallback when unavailable | Available native choice tool or numbered Markdown list | Numbered Markdown list v1; native UI adapter planned |
 | Dispatch subagent | `Agent({ description, prompt, subagent_type })` | Native multi-agent collaboration namespace: `spawn_agent`, `list_agents`, `wait_agent`, `send_message`, `followup_task`, `interrupt_agent`, `close_agent`. Measured 2026-08-25 on `codex-cli 0.141.0` — `codex features list` → `multi_agent  stable  true`. | No native in-session Agent tool. Coordinator-side foreign dispatch via the headless `cursor-agent` CLI exists (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150) — measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. | Sequential execution v1. Do not assume native subagents until the Pi SDK dispatcher exists. |
 | Track tasks | `TaskCreate` / `TaskUpdate` / `TaskList` | Plain-text checklist in response context | Plain-text checklist (same as Codex) | Plain-text checklist (same as Codex) |
 | Enter plan mode | `EnterPlanMode` / `ExitPlanMode` tools | `/plan` slash command (prompt-level, not tool-based) | Instruction-based: "Focus on analysis and planning. Do not modify files until the user approves." | `/plan` prompt template; use instruction-based planning when tool mode is unavailable |
@@ -37,7 +39,13 @@ When a skill instructs "Use the AskUserQuestion tool", apply this pattern:
 
 **On Claude Code:** Use the AskUserQuestion tool with structured options as documented.
 
-**On Codex CLI / Cursor IDE / Pi:** Present the same choices as a numbered Markdown list and ask the user to respond:
+**On Codex:** Prefer the available native user-input tool. In the measured Desktop
+0.153.4 runtime (2026-09-19), `request_user_input_async` allows a question while
+independent work continues; `request_user_input` has mode restrictions. Follow
+the live tool contract. Existing user authorization remains valid; do not ask
+again merely because a workflow names `AskUserQuestion`.
+
+**When no suitable native tool is available (including Cursor IDE / Pi):** Present the same choices as a numbered Markdown list and ask the user to respond:
 ```
 Choose one:
 1. Option A — description
@@ -85,6 +93,10 @@ No Session Orchestrator Pi subagent dispatcher exists in v1. Execute wave tasks
 
 Skills use `model-preference` (Claude), `model-preference-codex` (Codex), `model-preference-cursor` (Cursor), and active-model fallback on Pi in YAML frontmatter.
 
+These are preferences, not authority to replace a user's selected model,
+reasoning effort, or service tier. Preserve the current settings unless the user
+requests a change; inherit them for native subagents.
+
 ## State Directory
 
 - **Claude Code:** `.claude/` (STATE.md, wave-scope.json)

package/skills/_shared/research-evidence.md

@@ -0,0 +1,53 @@
+# Research Evidence Contract
+
+Use this contract when research informs a plan, audit, recommendation, or
+research-agent handoff. Scale it to the decision: a trivial local lookup may be
+one sentence; a comparison with several sources needs one record per material
+claim. It does not require external research when repository evidence is enough.
+
+## Record
+
+For each finding that changes the recommendation, retain:
+
+- **Source:** stable reference plus source revision or publication/update date.
+  For repository evidence, prefer `SHA:path:line`; for changing external facts,
+  include the observation date.
+- **Basis:** label the finding `observed` for a measurement or source-code
+  inspection (name which), `documented` for a source's claim, or `inference`
+  when it follows from other evidence. A test found in source is not an
+  executed test. Never present one class as another. Counts, percentages and
+  distributions additionally require PSA-006's executed-command transcript
+  (`.claude/rules/parallel-sessions.md` § PSA-006) — command, file scope,
+  result, measurement time.
+- **Local equivalent:** name the existing repository feature, dependency, rule,
+  or workflow that already covers the need; use `none found` only after a search
+  proportionate to the task.
+- **Disposition:** `adopt`, `adapt`, `experiment`, `reject`, or
+  `already stronger`, with one short reason. `Adopt` still means implement
+  through the current repository's conventions; it does not authorize copying,
+  installing, publishing, or another external mutation.
+- **Next check:** state one falsifiable next step when uncertainty remains: what
+  result would confirm or overturn the disposition.
+
+Keep quoted text minimal. Record limitations that materially constrain the
+claim. A source revision proves which artifact was inspected; it does not prove
+that its documented behavior works.
+
+## Private sources
+
+Treat private/internal sources as evidence for an authorized private audience
+only. Follow [Private capability context](private-capability-context.md) for
+lookup and retention. Do not copy private identities, paths, excerpts, or
+derived implementation details into a public plan or handoff. Re-establish a
+public claim from an authorized public source, or omit it. Source access never
+expands the task's implementation or external-action authority.
+
+## Compact example
+
+```text
+Source: vendor guide, rev 3.2, observed 2026-09-15
+Basis: documented — retries use exponential backoff; runtime behavior untested
+Local equivalent: src/retry.mjs already provides capped linear retries
+Disposition: experiment — compare failure recovery before changing the default
+Next check: 100 replayed failures; reject if success rate does not improve
+```