session-orchestrator 5.0.0 → 5.2.0

package/scripts/sweep-expired-rules.mjs

@@ -0,0 +1,216 @@
+#!/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. */
+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;
+  return {
+    dry_run: args.dryRun,
+    grace_days: args.graceDays,
+    files_scanned: plan.plans.length,
+    rewrites: counts.rewrite,
+    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.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,15 @@ 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;
+
 // 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/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;

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/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
+```

package/skills/_shared/state-ownership.md

@@ -18,6 +18,7 @@ total-waves: <N>
 # Optional fields (schema-version 1, additive for backward-compat):
 updated: <ISO 8601 UTC>      # last write timestamp, touched by any writer
 session: <session-label>     # attribution/history label; normally semantic since #573, legacy UUID-v4 remains readable; never a lock/registry ownership key
+session-id: <raw id>         # the RAW/native harness session id from session.lock (#1368); omit when absent; never a lock/registry ownership key
 session-start-ref: <sha>     # git ref at session start
 ---
 ```
@@ -25,6 +26,8 @@ session-start-ref: <sha>     # git ref at session start
 ### Required vs. optional fields
 
 - `schema-version`, `session-type`, `branch`, `issues`, `started_at`, `status`, `current-wave`, `total-waves` — **required** in every session-owned STATE.md.
+- `session-id` — **optional**, additive under `schema-version: 1` (#1368). The RAW/native harness session id, taken from `.orchestrator/session.lock` via `resolveSessionIds()` (`scripts/lib/state-md.mjs`). Writers OMIT the key when the lock yields none; readers MUST tolerate its absence. It exists so `/close`'s #429 pre-check can join STATE.md to sessions.jsonl on a NATIVE identity (`findRecordedSession`'s UUID fast path) instead of falling through to the semantic label. Like `session`, it grants no lock or registry ownership.
+- `started_at` is SOURCED from the same lock (`resolveSessionStartedAt()`), never from the writer's clock — see `skills/wave-executor/references/wave-executor-state-init.md` § Pre-Wave 1b for the template and the 48-minute drift that motivated it (#1368). On the READ side `started_at` is a CORROBORATING signal, never an identity key: `findRecordedSession()` (`scripts/lib/session-close-backfill.mjs`) joins STATE.md to `sessions.jsonl` on the native `session-id` FIRST and never consults `started_at` on that path — only the legacy-LABEL path compares the two timestamps, and it tolerates up to `STARTED_AT_DRIFT_TOLERANCE_MS` = **6 h** of drift (`session-close-backfill.mjs:559`, the single definition) before vetoing a label match: wider than any plausible write-lag (the 48 minutes above), narrower than the day the label's own date component already distinguishes.
 - `updated`, `session`, `session-start-ref` — **optional**. Added by #184. STATE.md files without these fields remain valid and should be treated as `updated: null` / `session: null`. Writers SHOULD populate these fields but readers MUST tolerate their absence. `session` is an attribution/history label, normally `<branch>-<YYYY-MM-DD>-<mode>-<n>` since #573 (Epic #568 Parallel-Aware Sessions P2.2); pre-#573 files may contain a UUID-v4 — both formats are read via `parseSessionId()` from `scripts/lib/session-id.mjs` per PRD §3 P2 row 3 (backward-compat). Neither form grants lock or registry ownership.
 
 The `session-type: none` + `status: idle` combination is used only for bootstrap-scaffolded placeholder files (no active session).

package/skills/autopilot/SKILL.md

@@ -9,12 +9,47 @@ description: >
   record per loop run. Phase C scaffold (issue #277); implementation lives in
   scripts/lib/autopilot.mjs (Phase C-1 follow-up).
 user-invocable: true
+argument-hint: "[--headless] [--verbose] [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]"
 tags: [phase-c, autopilot, autonomous, loop]
 model: sonnet
 ---
 
 # Autopilot Skill
 
+## Invocation
+
+The user invokes `/autopilot` with arguments: **$ARGUMENTS**. This is autonomous
+session-orchestration mode — a top-level invocation only, never from inside a running
+session.
+
+Parse `$ARGUMENTS` before anything else. Unrecognized flags are ignored; out-of-range
+values silently clamp to bounds. Use `parseFlags` from `scripts/lib/autopilot.mjs` for
+canonical parsing — never re-implement clamping inline. The loop flags
+(`--max-sessions`, `--max-hours`, `--confidence-threshold`, `--dry-run`) and their
+defaults/bounds are tabled once in § Command Surface below. Two further flags belong to
+the invocation surface only:
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--headless` | `false` | Run via the standalone driver `scripts/autopilot.mjs`, which spawns `claude -p '/session <mode>'` as a child process per iteration. Required for unattended walk-away mode. Without it, `/autopilot` runs the in-process driver inside the current chat session (see § Production Wiring). |
+| `--verbose` | `false` | Verbose driver output. |
+
+### Headless (`claude -p`)
+
+Headless requirements:
+
+- Anthropic API key configured for `claude -p` (Claude Code CLI auth).
+- `scripts/autopilot.mjs` reads `sessions.jsonl` tail after each child exit to construct
+  the `sessionRunner` return shape — the spawned session must complete cleanly and append
+  its record (session-end Phase 3.7 handles this).
+- `AUTOPILOT_RUN_ID` env var is propagated to the child so session-end stamps it onto the
+  per-iteration `sessions.jsonl` record.
+
+Do NOT re-implement loop logic inline — this skill and `scripts/lib/autopilot.mjs` are
+authoritative. Kill-switches are enforced by `scripts/lib/autopilot.mjs`, not inline by
+Claude. The runtime writes ONE record to `.orchestrator/metrics/autopilot.jsonl` per
+invocation via atomic tmp+rename; no other code path appends to that file.
+
 ## Phase 0.5: Parallel-Aware Preamble
 
 > Skip silently when `persistence: false` in Session Config.
@@ -177,7 +212,8 @@ Phase C-1 ships `runLoop` as a pure controller. Phase C-1.c ships `buildLiveSign
 the canonical signals-assembly helper. This section documents the **in-process driver
 protocol** (Option B from #301): how Claude — running as the coordinator in a chat
 session — drives `runLoop` between manual `/session` invocations. The headless wrapper
-(Option A, `scripts/autopilot.mjs` CLI spawning `claude -p`) is reserved for Phase C-5.
+(Option A, `scripts/autopilot.mjs` CLI spawning `claude -p`) is selected with `--headless`
+— see § Invocation.
 
 ### Dependency-Injection Contract
 
@@ -187,8 +223,8 @@ session — drives `runLoop` between manual `/session` invocations. The headless
 |---|---|---|
 | `modeSelector` | `() => Promise<{mode, confidence, rationale?}>` | wraps `selectMode(await buildLiveSignals())` |
 | `sessionRunner` | `({mode, autopilotRunId}) => Promise<{session_id, agent_summary?, effectiveness?}>` | wraps a `/session <mode>` invocation; reads `sessions.jsonl` tail to construct return value |
-| `resourceEvaluator` | `() => {verdict}` | wraps `evaluate(await probe(), thresholds)` from `resource-probe.mjs` |
-| `peerCounter` | `() => number` | reads `claude_processes_count` from a fresh `probe()` snapshot |
+| `resourceEvaluator` | `() => {verdict}` | calls `evaluate(cachedProbeSnapshot, thresholds)` from `resource-probe.mjs` over a snapshot `peerCounter` refreshed on the prior iteration — never calls `probe()` itself, which is what keeps it synchronous |
+| `peerCounter` | `() => Promise<number>` | returns `peers.length` from `detectPeers({ sessionId, freshnessMin: 15 })` (a SESSION count, not a process count — see `host-resources.md` HR-103) while refreshing the cached `probe()` snapshot `resourceEvaluator` reads |
 
 `abortSignal` is optional (Ctrl+C / Esc → `user-abort` kill-switch).
 
@@ -256,6 +292,25 @@ The in-process driver has Claude (the coordinator) call `/session <mode>` betwee
 - **Con:** not truly autonomous — Claude must stay in the chat. Doesn't deliver
   walk-away UX. That's Phase C-5's job.
 
+### Headless Driver Wiring (Option A — `scripts/autopilot.mjs`)
+
+The standalone headless driver invoked via `--headless` (see § Invocation) wires all
+four required `runLoop` dependencies (`modeSelector`, `sessionRunner`,
+`resourceEvaluator`, `peerCounter`) plus the optional `abortSignal` to production
+sources — distinct from, and more concrete than, the in-process skeleton above:
+
+- `sessionRunner` — spawns `claude -p '/session <mode>'` as a child process; after it
+  exits cleanly, reads the `sessions.jsonl` tail to construct the return shape
+  `{session_id, agent_summary?, effectiveness?}` (`scripts/autopilot.mjs` `sessionRunner`).
+- `resourceEvaluator` — calls `evaluate(cachedProbeSnapshot, thresholds)` from
+  `scripts/lib/resource-probe.mjs`, reading a snapshot refreshed by `peerCounter` on the
+  prior iteration so the function itself stays synchronous, per the `runLoop` contract
+  (`scripts/autopilot.mjs` `resourceEvaluator`).
+- `peerCounter` — calls `detectPeers({ sessionId: autopilotRunId, freshnessMin: 15 })` from
+  `scripts/lib/session-registry.mjs` AND refreshes the cached `probe()` snapshot in the
+  same call, returning `peers.length` (`scripts/autopilot.mjs` `makePeerCounter`).
+- `abortSignal` — an `AbortController` aborted on the process's `SIGINT` handler.
+
 ### `autopilot_run_id` Propagation
 
 When `runLoop` invokes `sessionRunner({mode, autopilotRunId})`, the per-iteration
@@ -387,7 +442,6 @@ Single-story `/autopilot` takes no Session Config block. Multi-story
 - PRD: "Autopilot Loop" (#277; archived in the private Meta-Vault)
 - Implementation (Phase C-1 + C-1.b): `scripts/lib/autopilot.mjs` — exports `runLoop`, `parseFlags`, `writeAutopilotJsonl`, `KILL_SWITCHES`, `FLAG_BOUNDS`, `SCHEMA_VERSION`, `DEFAULT_PEER_ABORT_THRESHOLD`, `DEFAULT_JSONL_PATH`, `DEFAULT_CARRYOVER_THRESHOLD`
 - Tests (Phase C-1 + C-1.b): `tests/lib/autopilot.test.mjs`
-- Command file: `commands/autopilot.md`
 - Mode-Selector contract: `skills/mode-selector/SKILL.md`
 - Resource probe: `scripts/lib/resource-probe.mjs`
 - Session registry: `scripts/lib/session-registry.mjs`

package/skills/bootstrap/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bootstrap
 user-invocable: true
+disable-model-invocation: true
+argument-hint: "[--upgrade <tier>]"
 tags: [bootstrap, setup, scaffold, init]
 model: sonnet
 model-preference: sonnet
@@ -15,6 +17,54 @@ description: >
 
 # Bootstrap Skill
 
+## Invocation
+
+The user invokes `/bootstrap` with arguments: **$ARGUMENTS**. Direct invocation runs with
+`INVOCATION_MODE = direct` (see § Invocation Context) and is standalone: after bootstrap
+completes, report the files created and the git commit hash, and do NOT automatically
+continue into any other skill.
+
+**TL;DR — for first-time users:** Run `/bootstrap` with no flags. The skill auto-detects the right tier (fast/standard/deep) from your repo, recommends one with a one-line reason, then walks a **fixed questionnaire** — tier/stack (1–2 prompts), owner persona (5), dispatcher autonomy (1); **7–9 prompts** on a first-run full bootstrap. Bestätigen → fertig. Keine weiteren Schritte.
+
+The flags below cover special cases (re-adopting an existing repo, upgrading a tier, syncing rules). If you don't recognize the case in the description, you don't need the flag.
+
+> **Instruction file alias:** Bootstrap creates and reads `CLAUDE.md` (or `AGENTS.md` on Codex CLI). The two are transparent aliases — pick one, never both. Resolution rule: see `skills/_shared/instruction-file-resolution.md`.
+
+### Standard usage (no flags)
+
+This is the path 95 % of users want.
+
+| Invocation | Behavior |
+|------------|----------|
+| `/bootstrap` | Auto-detect tier (fast / standard / deep) from repo context. Present recommendation via `AskUserQuestion` with options to confirm or override. Tier/stack: 1–2 questions; first-run full bootstrap adds owner interview (5, `owner-interview.mjs`) + dispatcher-autonomy capture (1). Then scaffold files + commit. |
+
+What the user sees:
+
+```
+Skill: "Repo leer. Empfehle 'standard' weil <reason>. Passt das?"
+User: [Enter on "standard (Empfohlen)"]
+Skill: <writes files, commits, prints summary>
+```
+
+### Flag reference (special cases)
+
+Only use a flag if you have one of the situations described. Parsed flags decide the mode
+dispatch in § Invocation Context — `--fast` / `--standard` / `--deep` skip the tier
+confirmation question, while `--retroactive`, `--refresh-lock`, `--sync-rules` and
+`--ecosystem-health` are standalone short-circuit flows that run to completion in this
+skill without dispatching to a tier template.
+
+| Flag | When to use it |
+|------|----------------|
+| `--upgrade <tier>` | You bootstrapped `fast` earlier and now need `standard` or `deep`. Idempotent — writes only the delta. Refuses downgrade. Valid: `fast → standard`, `fast → deep`, `standard → deep`. |
+| `--retroactive` | The repo already has `CLAUDE.md` (or `AGENTS.md` on Codex CLI) + `## Session Config` but no `bootstrap.lock` (manually bootstrapped before the gate existed). Writes the lock based on file inventory; **makes no scaffolding changes**. Commit: `chore: bootstrap lock (retroactive)`. |
+| `--refresh-lock` | Your `bootstrap.lock` already has valid `version`/`tier` fields but the freshness probe flags it as stale or plugin-version-drifted — `--retroactive` is a no-op here. Acknowledges the current plugin version and resets the freshness clock (`refreshed-at` + `refreshed-plugin-version`) without touching the lock's original bootstrap provenance. No scaffolding, no auto-commit. |
+| `--sync-rules` | Pull canonical rules from the plugin's `rules/` library into `.claude/rules/`. Preserves local rules (files without the plugin source header). Standalone — does not touch `bootstrap.lock`. |
+| `--ecosystem-health` | Run the ecosystem-health wizard: detects CI provider + package manager, prompts for health endpoints, pipelines, and critical issue labels. Writes the config block + `.orchestrator/policy/ecosystem.json`. No scaffolding, no auto-commit. |
+| `--fast` / `--standard` / `--deep` | Skip the tier confirmation question (e.g., for scripted runs). Equivalent to running `/bootstrap` and selecting that option. |
+
+All flag-driven flows are idempotent — running twice with no upstream change is a no-op.
+
 ## Overview
 
 This skill runs when the Bootstrap Gate is closed (missing CLAUDE.md, Session Config, or `.orchestrator/bootstrap.lock`) or when the user invokes `/bootstrap` directly. It scaffolds the minimum structure required by all session-orchestrator skills, commits it, and writes the lock file that opens the gate for all future invocations.
@@ -26,7 +76,7 @@ This skill runs when the Bootstrap Gate is closed (missing CLAUDE.md, Session Co
 Before starting, determine how this skill was invoked:
 
 - **Transitive (gate-closed):** Invoked from another skill's Phase 0. The user's original intent (their first prompt) is available in context. After bootstrap completes, execution must return to the original skill's Phase 1.
-- **Direct (`/bootstrap`):** User invoked manually. Parse `$ARGUMENTS` for flags: `--fast`, `--standard`, `--deep`, `--upgrade <tier>`, `--retroactive`. See `commands/bootstrap.md` for flag semantics.
+- **Direct (`/bootstrap`):** User invoked manually. Parse `$ARGUMENTS` for flags: `--fast`, `--standard`, `--deep`, `--upgrade <tier>`, `--retroactive`. See § Invocation above for flag semantics.
 
 Store `INVOCATION_MODE = transitive | direct`.
 

package/skills/brainstorm/SKILL.md

@@ -3,6 +3,9 @@ name: brainstorm
 description: Use when you have a feature idea but the scope or UX is still ambiguous — runs a lightweight Socratic design dialogue (3-5 AUQ rounds) and writes a spec markdown file. Use BEFORE /plan feature when product intent needs validation; skip to /plan feature when scope is already clear. HARD-GATE prevents any code work until the design is user-approved.
 model: inherit
 color: cyan
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[topic-or-feature-slug]"
 tools: Read, Grep, Glob, Bash, Write
 ---
 
@@ -10,6 +13,19 @@ tools: Read, Grep, Glob, Bash, Write
 
 > Lightweight Socratic design dialogue for per-feature exploration. Sibling to `/plan feature`, not a replacement. Produces `docs/specs/YYYY-MM-DD-<slug>-design.md` after the user approves an approach.
 
+## Invocation
+
+The user invokes `/brainstorm` with arguments: **$ARGUMENTS**.
+
+The optional argument is a topic or feature slug used in the spec filename (lowercase, hyphens, no special characters). If absent, the skill derives a slug from the user's Phase 1 answer.
+
+Examples:
+- `/brainstorm` — no slug; skill prompts for the problem in Phase 1
+- `/brainstorm export-to-csv` — slug pre-set to `export-to-csv`
+- `/brainstorm "user notification system"` — normalize to `user-notification-system`
+
+The HARD-GATE in Phase 0 below prevents any Edit, Write (code), or Bash (implementation) call until the user approves the design in Phase 6 — the only Write permitted before approval is the spec file itself in Phase 4.
+
 ## Soul Reference
 
 Read `soul.md` in this skill directory before anything else. It defines WHO you are — a Design Facilitator who shapes vague ideas into approved designs through Socratic questioning. Every interaction in this skill should reflect that identity.