session-orchestrator 5.0.0 → 5.2.0

package/skills/session-start/references/phase-2-7-portfolio-snapshot.md

@@ -71,5 +71,5 @@ Proceed to Phase 3 without blocking.
 
 ### Cross-reference
 
-See `commands/portfolio.md` for the `/portfolio` command (full write path, `--dry-run`, `--repo` single-repo testing).
+See `skills/portfolio/SKILL.md` for the `/portfolio` command (full write path, `--dry-run`, `--repo` single-repo testing).
 

package/skills/session-start/references/phase-4-ssot-environment-check.md

@@ -71,9 +71,9 @@
 
    The instruction-budget probe (`scripts/lib/instruction-budget-guard.mjs`, `checkInstructionBudget`) runs in the Phase 4 banner family as `id: 'instruction-budget'` in `scripts/lib/session-start-probes.mjs` `PROBES`. The helper returns `null` (silent no-op) when the always-on directive count is at or under the configured ceiling, or on any read failure. When a non-null result is returned (`{ severity: 'warn', message }`), render `result.message` alongside the other banners. Non-blocking. Cross-reference: "Instruction Budget Audit" (#687; archived in the private Meta-Vault).
 
-   The maintenance-due probe (`scripts/lib/maintenance-due-banner.mjs`, `checkMaintenanceDue`) runs in the Phase 4 banner family as `id: 'maintenance-due'` in `scripts/lib/session-start-probes.mjs` `PROBES`, called with `{ repoRoot, config }`. This probe REPLACED the former `reconcile-nudge` entry in `scripts/lib/session-start-probes.mjs` (it reuses `computeReconcileNudge` wholesale as one of its six signals) AND the two retired session-end nudges — Phase 3.6.5 auto-dream and Phase 3.6.7 auto-dialectic — which asked the operator at close for work only a housekeeping session can do. Return contract: `null` (silent no-op) or `{ severity: 'warn', message }`; never throws. `computeMaintenanceDue` exposes the same computation without the banner suppression.
+   The maintenance-due probe (`scripts/lib/maintenance-due-banner.mjs`, `checkMaintenanceDue`) runs in the Phase 4 banner family as `id: 'maintenance-due'` in `scripts/lib/session-start-probes.mjs` `PROBES`, called with `{ repoRoot, config }`. This probe REPLACED the former `reconcile-nudge` entry in `scripts/lib/session-start-probes.mjs` (it reuses `computeReconcileNudge` wholesale as one of its seven signals) AND the two retired session-end nudges — Phase 3.6.5 auto-dream and Phase 3.6.7 auto-dialectic — which asked the operator at close for work only a housekeeping session can do. Return contract: `null` (silent no-op) or `{ severity: 'warn', message }`; never throws. `computeMaintenanceDue` exposes the same computation without the banner suppression.
 
-   The six signals (`MAINTENANCE_TOTAL_SIGNALS = 6`), each side-effect-free:
+   The seven signals (`MAINTENANCE_TOTAL_SIGNALS = 7`), each side-effect-free:
 
    | id | due when | source |
    |---|---|---|
@@ -83,12 +83,13 @@
    | `dialectic` | `shouldDispatchAutoDialectic().trigger === true` | `scripts/lib/auto-dialectic.mjs` — the side-effect-free decision function; a variant that advanced the last-run stamp would consume the signal it reports (the former recording wrapper was removed in #1288) |
    | `memory-cleanup` | `shouldDispatchAutoDream().trigger === true` | `scripts/lib/auto-dream.mjs` |
    | `pending-sidecar` | an unapplied pending dream/dialectic proposal younger than `SIDECAR_MAX_AGE_DAYS` (14) | `.orchestrator/*-pending*.md` |
+   | `generated-rules-expiring` | a machine-generated rule in `.claude/rules/` is already expired or expires within `GENERATED_RULE_EXPIRY_HORIZON_DAYS` (7) days; the population comes from `listMachineGeneratedRules({ repoRoot })` — one definition of "machine-generated", shared with the byte ceiling that judges the same set. The detail names each file and its `expires-at` date (HR-106), soonest first, because those are exactly the files the operator has to open to repair it. An unreadable rules directory goes to `undeterminable`, never to "clean" | `scripts/lib/instruction-budget-guard.mjs` (via #1372) |
 
    Introduces NO new Session Config key — every threshold is an existing key or an existing module constant.
 
    - **Nothing due and everything readable**: silent (no banner).
    - **A housekeeping session completed within `HOUSEKEEPING_COOLDOWN_DAYS` (7) days**: silent, even when signals are due — the operator already did the thing the banner would ask for. This cooldown is what keeps the instrument rare (HR-101, `.claude/rules/host-resources.md`); the housekeeping session's own record IS the last-maintenance stamp.
-   - **Otherwise**: render `result.message`, shaped as `⚠ maintenance due: <N> of 6 (<id>: <detail> · <id>: <detail>) — run /session housekeeping.` Every due signal carries the number or date that made it due (HR-106) — no aggregate stands alone.
+   - **Otherwise**: render `result.message`, shaped as `⚠ maintenance due: <N> of 7 (<id>: <detail> · <id>: <detail>) — run /session housekeeping.` Every due signal carries the number or date that made it due (HR-106) — no aggregate stands alone.
    - **Unreadable inputs** append an ` · undeterminable: <id>, <id>` suffix before the `— run /session housekeeping.` tail. A signal whose inputs cannot be read is three-state: never folded into "clean" (the `never` vs `undeterminable` discipline inherited from `reconcile-nudge-banner.mjs`).
 
    Non-blocking. Cross-reference: `scripts/lib/reconcile-nudge-banner.mjs` (`computeReconcileNudge`), `scripts/lib/reconcile/engine.mjs` (`runReconcile`), `skills/reconcile/SKILL.md`, `skills/session-start/SKILL.md` Phase 7 (the housekeeping maintenance loop the banner routes to), and issues #723 / #1200.

package/skills/spinout/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spinout
 user-invocable: true
+argument-hint: "[--type venture|snapshot] [--dry-run]"
 model: sonnet
 description: >
   Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its
@@ -11,6 +12,17 @@ description: >
 
 # spinout — Guided Project-Extraction Runbook
 
+The user wants to extract this project (or a sub-path of it) into a new standalone repo — a venture spinout or a sanitized content-snapshot fork. Arguments: **$ARGUMENTS**
+
+## Invocation
+
+Parse `$ARGUMENTS` before Phase 0. Two optional flags are recognised; anything else is ignored.
+
+| Flag | Behavior |
+|---|---|
+| `--type venture\|snapshot` | Skips the extraction-type question in Phase 1 (`AskUserQuestion`) — still asks for destination path and sphere. |
+| `--dry-run` | Runs all 5 phases as a plan-print (target, sanitize checklist, copy plan, freeze-marker draft, remote plan) with no writes. |
+
 ## Status: Deliberately Not Scripted
 
 This is a 5-phase interactive runbook, not a CLI wrapper. Automate only after 2-3 hand-runs have stabilized the pattern — spinout is a low-frequency, high-stakes operation (new remote, fresh history, a frozen marker left behind in the source repo), and premature scripting bakes wrong defaults (wrong sphere, wrong sanitize scope, wrong remote layout) into something expensive to undo. See #730 / H2.
@@ -74,7 +86,6 @@ Confirm each write via `AskUserQuestion` before executing:
 
 ## See Also
 
-- `commands/spinout.md` — slash-command entry point.
 - `skills/_shared/bootstrap-gate.md` — Phase 0 gate contract.
 - `.claude/rules/ask-via-tool.md` — AUQ-001 (every user decision goes through the tool, not prose).
 - `.claude/rules/parallel-sessions.md` § PSA-003 — destructive-action safeguards apply to any write in Phase 3/4/5.

package/skills/sunset-review/SKILL.md

@@ -11,6 +11,8 @@ description: >
   / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision."
   <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker,
   presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>
+user-invocable: true
+argument-hint: "[--kind skill|agent|command] [--window-days N]"
 model: inherit
 color: amber
 ---
@@ -19,6 +21,17 @@ color: amber
 
 Identify which skills, agents, and commands in the plugin surface are still earning their keep, and which are candidates to **Demote** (downgrade docs/tier) or **Retire** (remove). The skill is advisory: it produces a ranked candidate list and a sidecar artifact. **It never deletes anything.**
 
+## Invocation
+
+Parse `$ARGUMENTS` before Phase 1. Two optional flags narrow the scope; anything else is ignored.
+
+| Flag | Behavior |
+|---|---|
+| `--kind skill\|agent\|command` | Limits the walk to one surface kind — passed straight through to the walker. |
+| `--window-days N` | Overrides the default 90-day dispatch window resolved in Phase 1. |
+
+`/harness-audit` answers a third question — "is session-orchestrator installed correctly?" (plugin health) — and is not this skill.
+
 ## Why this is a distinct skill (not /repo-audit)
 
 `/repo-audit` answers "does this repo match the ecosystem baseline?" — a pass/fail compliance check. `/sunset-review` answers a different question — "which parts of OUR surface are unused?" — with different inputs (dispatch telemetry + static ref scanning), a different cadence (quarterly, not per-session), and a different output (prune candidates, not compliance status). Folding it into repo-audit would muddy both.

package/{commands/test.md → skills/test/SKILL.md}

@@ -1,13 +1,19 @@
 ---
+name: test
 description: Agentic end-to-end test orchestrator — drive web/macOS flows, evaluate UX rubric, reconcile issues
+user-invocable: true
 argument-hint: "[scope|profile-name] [--since <git-ref>] [--full]"
+model: inherit
 ---
-
 # Test
 
 Run agentic end-to-end tests against the current project or a named target. The user invoked `/test` with arguments: **$ARGUMENTS**
 
-This command resolves a test target and profile, dispatches the appropriate driver (Playwright for web, Peekaboo for macOS), invokes the `ux-evaluator` agent against the captured artifacts, and reconciles findings with the open issue tracker. All logic lives in `skills/test-runner/SKILL.md` — this file is the user-facing entry point only.
+This skill resolves a test target and profile, dispatches the appropriate driver (Playwright for web, Peekaboo for macOS), invokes the `ux-evaluator` agent against the captured artifacts, and reconciles findings with the open issue tracker. All logic lives in `skills/test-runner/SKILL.md` — this file is the user-facing entry point only.
+
+## Invocation
+
+`$ARGUMENTS` carries the recognised flags (`--target`, `--profile`, `--dry-run`, `--since`, `--full`) and an optional bare scope token. Parse it per § Argument Validation, resolve per § Argument Precedence Resolution, and only then hand the six-argument § Handoff Contract to `skills/test-runner/SKILL.md`, which owns all further resolution, driver dispatch, evaluation, and issue reconciliation.
 
 ## Argument Validation
 
@@ -83,7 +89,7 @@ Pass the following handoff contract to the skill entry point.
 
 ## Handoff Contract
 
-The five named arguments below are the canonical contract between this command and `skills/test-runner/SKILL.md`. The skill reads them from context; do NOT reconstruct them inside the skill.
+The six named arguments below are the canonical contract between this skill and `skills/test-runner/SKILL.md`. The skill reads them from context; do NOT reconstruct them inside the skill.
 
 | Argument | Type | Value |
 |---|---|---|
@@ -94,4 +100,4 @@ The five named arguments below are the canonical contract between this command a
 | `explicit_profile` | `boolean` | `true` if `--profile` was present in `$ARGUMENTS`; `false` otherwise |
 | `since_ref` | `string \| undefined` | Git ref from `--since <git-ref>`, or `undefined` if not provided |
 
-The skill is the single source of truth for all further resolution, driver dispatch, evaluation, and issue reconciliation. Do NOT re-implement profile logic, driver selection, or issue triage in this command file.
+The skill is the single source of truth for all further resolution, driver dispatch, evaluation, and issue reconciliation. Do NOT re-implement profile logic, driver selection, or issue triage here.

package/skills/ux-grill/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: ux-grill
+user-invocable: true
+argument-hint: "[url | manifest-path]"
 description: Use when a running web app's UX has to be audited reproducibly rather than by feel — a deterministic mechanical pass over routes and viewports (axe, target size, horizontal overflow, page title, scripted journeys) followed by a screenshot-grounded interrogation of the operator, journey by journey, with two persona lenses from the target repo's manifest. Triggered by "grill the UX", "roast the dashboard", "UX-Audit", "/ux-grill". Bootstraps its own manifest from a loopback URL on the first run, so it never requires a hand-written file to start.
 model: inherit
 color: magenta
@@ -10,6 +12,22 @@ tools: Read, Grep, Glob, Bash, Write
 
 > Two stages, hard boundary. **Stufe 1** measures — a Node pass over routes × viewports that calls `agent-browser` and writes JSON, with no model in the loop. **Stufe 2** grills — the `/grill` loop applied to journeys, where every claim carries a screenshot path. Severity is never a judgment here; it comes out of `schema.mjs`.
 
+## Invocation
+
+The user invoked `/ux-grill` with arguments: **$ARGUMENTS**. Parse them before anything else — exactly one positional argument is recognised:
+
+- **An absolute `http(s)` URL** (e.g. `http://127.0.0.1:3100`) → bootstrap path (§ 0.2). The target repo has no manifest yet; ask for the env names, crawl the navigation and write one. The URL must be loopback — anything else is refused before a browser starts.
+- **A file path** (ends in `.md`, or resolves to an existing file) → treat it as the manifest path, repo-relative to the target repo.
+- **Empty** → the manifest at `DEFAULT_MANIFEST_PATH` (`.orchestrator/ux-manifest.md` <!-- path-check: example -->). If that file does not exist, say so and name the bootstrap form `/ux-grill <url>` — do not invent a manifest from nothing.
+- **Anything else** → stop with: `ux-grill: argument must be a loopback URL or a manifest path (default .orchestrator/ux-manifest.md)`.
+
+Examples:
+- `/ux-grill` — runs against the target repo's existing manifest
+- `/ux-grill http://127.0.0.1:3100` — first run: AUQ for env names, crawl, write the manifest, stop with a fill-in hint
+- `/ux-grill .orchestrator/ux-manifest.md` — explicit manifest path
+
+**No CI, no HARD-GATE.** Stufe 1 is built CI-shaped (deterministic, exit-coded, LLM-free) but is deliberately not wired into any pipeline — the PRD's dose argument. `/ux-grill` gates nothing: it writes measurement artefacts, an optional dossier and — only through `reconcile.mjs` <!-- path-check: planned #1327 --> — issues. It never commits, never pushes, never edits product code.
+
 ## Soul Reference
 
 Read `soul.md` in this skill directory before anything else. It defines WHO you are — the UX Interrogator — the persona-lens discipline, and the six tactics in their UX form. The rubric you measure against is `rubric-v2.md`; read it before Phase 1 so you can read `findings.jsonl` without guessing what a `checkId` means.
@@ -33,7 +51,7 @@ Read `soul.md` in this skill directory before anything else. It defines WHO you
 
 ### 0.1 Resolve the argument
 
-Per `commands/ux-grill.md` § Argument Validation: a loopback URL selects the bootstrap path, a file path or empty selects `DEFAULT_MANIFEST_PATH` from `scripts/lib/ux-grill/manifest.mjs`.
+Per § Invocation above: a loopback URL selects the bootstrap path, a file path or empty selects `DEFAULT_MANIFEST_PATH` from `scripts/lib/ux-grill/manifest.mjs`.
 
 ### 0.2 Bootstrap (URL, no manifest yet)
 

package/skills/wave-executor/SKILL.md

@@ -253,10 +253,13 @@ A housekeeping session is **ONE coordinator-direct wave**, not a shrunken multi-
 |---|---|---|---|
 | 1 | `claude-md-drift-check` | unconditional | checker JSON (`errors`/`warnings` counts) |
 | 2 | expired-learnings sweep | unconditional | `orchestrator.learnings.sweep_applied` |
-| 3 | `/evolve analyze` | AUQ-gated (the operator approves the proposed learnings) | `orchestrator.evolve.completed` |
-| 4 | `/reconcile` | AUQ-gated (rule proposals are never applied unasked) | `orchestrator.reconcile.completed` with `dry_run: false` |
-| 5 | `/evolve dialectic` | AUQ-gated (the derived thesis is presented, not committed) | `orchestrator.dialectic.completed` |
-| 6 | `/memory-cleanup` | AUQ-gated (deletions are operator-approved) | `orchestrator.memory.cleanup_completed` |
+| 3 | expired-generated-**rules** sweep — `node scripts/sweep-expired-rules.mjs` (`--dry-run` first, then `--apply`) | AUQ-gated (it rewrites and can DELETE tracked `.claude/rules/*.md` files) | `orchestrator.rules.expiry_sweep_applied` |
+| 4 | `/evolve analyze` | AUQ-gated (the operator approves the proposed learnings) | `orchestrator.evolve.completed` |
+| 5 | `/reconcile` | AUQ-gated (rule proposals are never applied unasked) | `orchestrator.reconcile.completed` with `dry_run: false` |
+| 6 | `/evolve dialectic` | AUQ-gated (the derived thesis is presented, not committed) | `orchestrator.dialectic.completed` |
+| 7 | `/memory-cleanup` | AUQ-gated (deletions are operator-approved) | `orchestrator.memory.cleanup_completed` |
+
+Row 3 runs directly after row 2 because its evidence comes from row 2's corpus: an entry's date is recoverable only via its `learning-id` → `learnings.jsonl` `expires_at`, so the rule sweep must see the store the learnings sweep left behind. Show the operator the dry-run plan — it names every rewrite, every delete, every `no-1to1-mapping` skip and every unresolvable pair — before asking. Contract: `docs/rule-authoring.md` § Consolidated rules → "The expiry sweep".
 
 The session-start probe `maintenance-due` (`scripts/lib/maintenance-due-banner.mjs`) says which of these are DUE for this repo; a run that is not due may be skipped, and the skip is reported. An AUQ-gated run the operator declines is reported as declined — never as done. **Absence of the artefact event is the only evidence that counts**: a run claimed in prose without its event is not a run (`.claude/rules/verification-before-completion.md`).
 

package/skills/wave-executor/references/wave-executor-state-init.md

@@ -16,7 +16,9 @@ schema-version: 1
 session-type: feature|deep|housekeeping
 branch: <current branch>
 issues: [<issue numbers from plan>]
-started_at: <ISO 8601 timestamp with timezone>
+session: <semantic session label, e.g. main-2026-01-01-deep-1>
+session-id: <raw session_id from .orchestrator/session.lock — OMIT the key when no lock exists>
+started_at: <resolveSessionStartedAt({ repoRoot }) — the lock's own started_at, NEVER new Date() at write time (#1368)>
 status: active
 current-wave: 0
 total-waves: <from session plan>
@@ -37,6 +39,16 @@ Wave 0 — Initializing
 (none yet)
 ```
 
+**`started_at` and `session-id` are SOURCED, not typed (#1368).** Read both from the live session-lock before writing — never from the clock, and never from memory:
+
+```bash
+node -e "import('./scripts/lib/state-md.mjs').then(m => console.log(JSON.stringify({ started_at: m.resolveSessionStartedAt({ repoRoot: process.cwd() }), ...m.resolveSessionIds({ repoRoot: process.cwd() }) })))"
+```
+
+`resolveSessionStartedAt()` returns `.orchestrator/session.lock`'s own `started_at`, which the `orchestrator.session.lock.acquired` and `orchestrator.session.started` events agree with to the millisecond; it falls back to the current time only when no lock exists (`persistence: false`, or the acquire failed). Writing `new Date()` here instead put STATE.md 48 minutes ahead of the lock (measured 2026-09-13) and made `/close`'s #429 pre-check unable to join STATE.md to its own ledger record.
+
+`session-id` is the raw/native harness id (`resolveSessionIds().session_id`), `session` the semantic label (`.semantic_session_id`). Both are OPTIONAL (`schema-version` stays `1`): when the lock yields `null`, OMIT the key entirely — never write a placeholder. Neither field grants lock or registry ownership; see `skills/_shared/state-ownership.md`.
+
 Create the `<state-dir>` directory if needed (`mkdir -p <state-dir>`) before writing. This file is the persistent state record — other skills and resumed sessions read it.
 
 **Then VALIDATE `total-waves` against the resolved shape — do not skip this.** A plan whose wave count the shape does not produce must never be dispatched silently:

package/skills/wave-executor/references/wave-loop-dispatch.md

@@ -559,7 +559,9 @@ Marker line plus fenced block, in that order: `hooks/pre-task-scope-disjoint.mjs
 node scripts/lib/scope-echo.mjs --scope-file "$AGENT_FILESCOPE_JSON" --instruction
 ```
 
-It prints exactly one line (`renderScopeEchoInstruction` in `scripts/lib/scope-echo.mjs`), naming the `scopeDigest` of that agent's own scope file: `End your final report with the line: SCOPE-DIGEST: <8-hex>`. Append it verbatim. It prints NOTHING when the scope file is empty, missing or unreadable — Discovery waves therefore inject nothing here, exactly as they inject no `FILE-SCOPE` block. The post-wave comparison is `wave-loop-review.md` step 3d-bis; what the echo does and does not prove is stated there.
+It prints exactly one line (`renderScopeEchoInstruction` in `scripts/lib/scope-echo.mjs`), naming the `scopeDigest` of that agent's own scope file: `End your final report with the line: SCOPE-DIGEST: <8-hex>`. Append it verbatim.
+
+**The echo line and the fenced block MUST come from the SAME `$AGENT_FILESCOPE_JSON`.** Since #1092 the dispatch hook digests the paths it extracted from the prompt and compares them against the digest that line names, recording `digest_consistent: false` when they disagree — so pasting agent A's block beside agent B's echo line is now caught at dispatch time, in the ledger, with no filesystem read. Nothing blocks on it (the hook stays ALLOW), but it is a wave deviation, and it is exactly the collapse the box at the top of this section warns about: one agent's block reused for the batch. It prints NOTHING when the scope file is empty, missing or unreadable — Discovery waves therefore inject nothing here, exactly as they inject no `FILE-SCOPE` block. The post-wave comparison is `wave-loop-review.md` step 3d-bis; what the echo does and does not prove is stated there.
 
 #### Structured Reasoning (STATE:/PLAN:) — opt-in via `reasoning-output: true` (#79)
 

package/skills/wave-executor/references/wave-loop-review.md

@@ -130,6 +130,22 @@ Log every non-`pass` result as an event to `.orchestrator/metrics/events.jsonl`
 
    `checkScopeEcho` prints the verdict as JSON and `--emit` appends one `orchestrator.wave_dispatch.scope_echo_checked` record (payload: `docs/events-schema.md`; counts, digests and closed enums only — no path, no prompt text). `match: false` or `echoed: false` is logged in the wave progress update as `scope-echo: <agent> missing|mismatch` and changes NOTHING else — no re-dispatch, no deviation write, no gate.
 
+   Then, ONCE for the wave — not once per agent — join the two halves:
+
+   ```bash
+   node scripts/lib/scope-echo.mjs --verify --wave <N> --state-dir "<state-dir>" --json --emit
+   ```
+
+   It joins the send-side `scope_checked` records, the `<state-dir>/filescopes/wave-<N>/*.json` artefacts and the echoes **on the digest** — never on `agent_id`, because the two halves spell the same agent differently (measured 2026-09-16: 609 send-side vs 51 receive-side records, agent-id overlap ZERO; one session had 23 echoes against 18 injections and nothing could be paired). Log one line in the wave progress update:
+
+   ```
+   scope-injection: <injected>/<dispatches> injected, <echoed> echoed
+   ```
+
+   Two verdicts are a **STATE.md deviation write** (`### Deviations`), never a block and never a re-dispatch: `injection-missing` — a scope file materialized for this wave that NO dispatch claimed, i.e. the #1020 failure where the coordinator dispatched without injecting — and `duplicate-claim` — one digest claimed by two distinct agent ids, i.e. agent A's scope reported for agent B. `injected-not-echoed` is the normal state for any agent whose report has not landed yet and is logged, not written.
+
+   **On `transport: unobservable`** (the report's own field, from the wave's `scope_materialized` record — Codex, Cursor and Pi have no `PreToolUse` `Agent` matcher, so the send-side record cannot exist at all) every verdict degrades to `echo-only`, and a MISSING send-side record is **not** evidence of a missing injection. Do not write a deviation from an absence on those platforms.
+
    **What it proves:** the agent's final report carried the digest the coordinator handed it, i.e. the injected line survived the round trip into the agent's context and back. **What it does not prove:** that the model read the `FILE-SCOPE` block, understood it, or obeyed it — the digest is in the prompt, so it can be copied without ever looking at the paths (BV-004 ceiling, `docs/scope-collision-guard.md` § 4.2). Obedience is still measured at write time (`enforce-scope.mjs`) and by the W5 verification pass.
 
 3e. **Collect Open Questions** (Close Handover-Alignment-Gate, PRD 2026-07-07): scan every completed agent's report from this wave for an optional `OPEN-QUESTIONS:` line (see the report-line convention in `wave-loop-dispatch.md` `#### Agent-Type Resolution` — an agent MAY emit `OPEN-QUESTIONS: <question> | context: <...> | candidates: <opt A / opt B>`; most agents emit none). For each such line found:
@@ -580,4 +596,4 @@ On a clean `PROCEED` no deviation is written — the sidecar alone is sufficient
 
 When the hook is skipped (gate condition false), omit the `persona_gate` field entirely — never write `triggered: false` for skipped runs, so a downstream consumer can distinguish "hook did not fire" from "hook fired but found no dissent".
 
-**Motivating example:** a flagship product's W5 Buyer-Panel pattern (six buyer personas at `hard-gate-threshold` `6-of-6`, `mode: 'strict'`, `after: 'quality'`) — UI work is gate-checked against every persona before commit, abort on any dissent. See `docs/session-config-reference.md § Persona-Gate Wave (#458)` and `commands/persona-panel.md` for the standalone CLI equivalent.
+**Motivating example:** a flagship product's W5 Buyer-Panel pattern (six buyer personas at `hard-gate-threshold` `6-of-6`, `mode: 'strict'`, `after: 'quality'`) — UI work is gate-checked against every persona before commit, abort on any dissent. See `docs/session-config-reference.md § Persona-Gate Wave (#458)` and `skills/persona-panel/SKILL.md` for the standalone CLI equivalent.

package/commands/autopilot.md

@@ -1,80 +0,0 @@
----
-description: Autonomous session-orchestration loop with kill-switches (Phase C-1.b — all 10 kill-switches shipped)
-argument-hint: "[--headless] [--verbose] [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]"
----
-
-# Autopilot
-
-You are entering autonomous session-orchestration mode. The user has invoked `/autopilot` with arguments: **$ARGUMENTS**
-
-## Status
-
-**Phase C-1.b complete (issues #295 + #300). Runtime at `scripts/lib/autopilot/kill-switches.mjs:18-32` (the frozen `KILL_SWITCHES` enum is SSOT).** All 10 kill-switches enforced — pre-iteration (6): `max-sessions-reached`, `max-hours-exceeded`, `resource-overload`, `low-confidence-fallback`, `user-abort`, `token-budget-exceeded`; post-iteration (1): `stall-timeout` (ADR-364 §3, default 600s); post-session (3): `spiral`, `failed-wave`, `carryover-too-high`. Post-session gates read schema-canonical fields off the `sessionRunner` return shape (`agent_summary.{spiral, failed}` numeric counts, `effectiveness.{carryover, planned_issues}`); absent fields are forward-compatible (no kill).
-
-Production `sessionRunner` callers MUST persist `args.autopilotRunId` into the per-iteration `sessions.jsonl` record (additive optional field, schema_version 1 compatible). Manual sessions write `null` or omit the field — readers treat both identically.
-
-## Verdict-Gated Launch (dispatcher handoff — #682)
-
-When the cross-repo dispatcher (`/dispatcher`) routes into an autopilot launch, a
-**pre-loop suitability verdict** decides whether the launch proceeds WITHOUT per-selection
-confirmation. The dispatcher launches autonomously ONLY when the effective dispatcher
-autonomy is `autonomous-gated` AND the verdict is green (`suitable === true`); in EVERY
-other case it informs the operator (rationale + warnings) and asks before launch
-(fail-closed — see `skills/dispatcher/SKILL.md § Phase 1.5`). This is **opt-in by design**:
-the autonomy dial defaults to `off`, and a direct `/autopilot` invocation is always
-operator-initiated.
-
-The verdict gate is a PRE-LAUNCH decision computed once at the handoff via
-`computeSuitabilityVerdict(...)` (`scripts/lib/autonomy/suitability.mjs`) over the effective
-dial from `resolveDispatcherAutonomy(...)` (`scripts/lib/config/dispatcher-autonomy.mjs`).
-It does NOT add or modify any of the 10 per-iteration kill-switches — those are reused
-unchanged once the loop is running. The verdict's kill-switch-rate gate reads this repo's
-recent run history via `readRecentAutopilotRuns(...)`
-(`scripts/lib/autopilot/recent-runs.mjs`).
-
-## Argument Parsing
-
-Parse `$ARGUMENTS` for these flags. Unrecognized flags are ignored. Out-of-range values silently clamp to bounds.
-
-| Flag | Default | Bounds |
-|------|---------|--------|
-| `--headless` | `false` | flag |
-| `--max-sessions=N` | `5` | 1..50 |
-| `--max-hours=H` | `4.0` | 0.5..24.0 |
-| `--confidence-threshold=0.X` | `0.85` | 0.0..1.0 |
-| `--dry-run` | `false` | flag |
-
-`--headless`: Run via `scripts/autopilot.mjs` driver — spawns `claude -p` per iteration. Required for unattended walk-away mode. Without this flag, `/autopilot` runs the in-process driver inside the current chat session.
-
-Use `parseFlags` from `scripts/lib/autopilot.mjs` for canonical parsing — never re-implement clamping inline.
-
-## Headless Mode
-
-When invoked with `--headless`, the slash command delegates to the standalone driver `scripts/autopilot.mjs` which spawns `claude -p '/session <mode>'` as a child process per iteration. Use this for true walk-away operation; the in-process default keeps you in the current chat. See `skills/autopilot/SKILL.md § Production Wiring` for the design contract and issue #302 for the implementation rationale.
-
-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.
-
-## Invocation
-
-**Invoke the autopilot skill.** Follow `skills/autopilot/SKILL.md` precisely. Do NOT re-implement loop logic inline — the skill and `scripts/lib/autopilot.mjs` are authoritative.
-
-The runtime entrypoint is `runLoop(opts)`. Production callers wire injectable dependencies as follows:
-
-- `modeSelector`: invokes `selectMode` from `scripts/lib/mode-selector.mjs` with live signals from session-start Phase 7.5.
-- `sessionRunner`: invokes the standard session-start → session-plan → wave-executor → session-end lifecycle for one iteration; returns `{session_id}` on success.
-- `resourceEvaluator`: calls `evaluate(probe(), thresholds)` from `scripts/lib/resource-probe.mjs`.
-- `peerCounter`: calls `detectPeers({sessionId})` from `scripts/lib/session-registry.mjs` and returns the array length.
-- `abortSignal`: hooked to Ctrl+C / Esc handlers.
-
-Loop semantics, kill-switches, resource-adaptive cap logic, and telemetry contract are documented in the skill. The PRD "Autopilot Loop" (#277; archived in the private Meta-Vault) is the underlying design document.
-
-## Critical Rules
-
-- Never invoke `/autopilot` from inside a running session — top-level command only.
-- Never modify `selectMode` output to force a specific mode — use `/session [mode]` manually for that.
-- Iteration boundaries are atomic; do NOT abort sessions mid-flight.
-- Kill-switches are enforced by `scripts/lib/autopilot.mjs`, not by this command file or by Claude inline.
-- The runtime writes ONE record to `.orchestrator/metrics/autopilot.jsonl` per invocation via atomic tmp+rename. Do not append directly to that file from any other code path.

package/commands/bootstrap.md

@@ -1,56 +0,0 @@
----
-description: Scaffold the minimum repo structure required by session-orchestrator
-disable-model-invocation: true
-argument-hint: "[--upgrade <tier>]"
----
-
-# Bootstrap
-
-**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.
-
----
-
-You are running the bootstrap skill directly. The user has invoked `/bootstrap` with arguments: **$ARGUMENTS**.
-
-> **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.
-
-| 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.
-
-## Invoke the skill
-
-Read `skills/bootstrap/SKILL.md` and follow its instructions with `INVOCATION_MODE = direct`.
-
-Pass the parsed flags so the skill can skip the tier confirmation question when `--fast`, `--standard`, or `--deep` is provided. `--retroactive`, `--sync-rules`, and `--ecosystem-health` are standalone short-circuit flows — they run to completion inside SKILL.md without dispatching to a tier template.
-
-After bootstrap completes, report the files created and the git commit hash. Do NOT automatically continue to any other skill — this is a standalone invocation.

package/commands/brainstorm.md

@@ -1,48 +0,0 @@
----
-description: Run a lightweight Socratic design dialogue (3-5 AUQ rounds) and write a spec markdown file before any implementation work. Use BEFORE /plan feature when scope/UX is ambiguous.
-disable-model-invocation: true
-argument-hint: "[topic-or-feature-slug]"
----
-
-# Brainstorm
-
-Invokes the `brainstorm` skill. Produces `docs/specs/YYYY-MM-DD-<slug>-design.md` after the user approves a design approach. HARD-GATE prevents any code or implementation work until the design is user-approved.
-
-## Argument Validation
-
-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"` — skill normalizes to `user-notification-system`
-
-## Behavior
-
-1. **Bootstrap gate** — reads `skills/_shared/bootstrap-gate.md`; halts if GATE_CLOSED until bootstrap completes.
-2. **Phase 1** — single AUQ to characterize the problem and capture the source of ambiguity.
-3. **Phase 2** — 3-5 Socratic AUQ rounds (user surface, data shape, integration points, risk, success criteria).
-4. **Phase 3** — synthesize 2-3 approaches via AUQ with explicit trade-offs; user selects one.
-5. **Phase 4** — write spec to `docs/specs/YYYY-MM-DD-<slug>-design.md`.
-6. **Phase 5** — self-review pass (no placeholders, consistent with answers, explicit out-of-scope).
-7. **Phase 6** — hand-off AUQ: proceed to `/plan feature`, `/write-executable-plan`, revise, or done.
-
-## HARD-GATE
-
-The skill enforces a HARD-GATE in Phase 0 that prevents any Edit, Write (code), or Bash (implementation) tool calls until the user approves the design via AskUserQuestion in Phase 6. The only Write call permitted before approval is writing the spec file itself in Phase 4. See `skills/brainstorm/SKILL.md` Phase 0 for the verbatim gate text.
-
-## When to use vs. /plan feature
-
-| Situation | Use |
-|-----------|-----|
-| Scope or UX is ambiguous | `/brainstorm` |
-| Scope is clear, need a formal PRD | `/plan feature` |
-| Full project kickoff | `/plan new` |
-| Spec already written, ready to formalize | `/plan feature` |
-
-## Related
-
-- `skills/brainstorm/SKILL.md` — full skill specification (GH #36, umbrella #35)
-- `skills/plan/SKILL.md` — primary hand-off target after design approval
-- `skills/write-executable-plan/SKILL.md` — alternative hand-off for direct execution (issue #39)
-- `.claude/rules/ask-via-tool.md` — AUQ tool usage convention (AUQ-001..005)

package/commands/debug.md

@@ -1,36 +0,0 @@
----
-description: Run a 4-phase systematic debugging investigation before proposing any fix. Iron Law — NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
-argument-hint: "[bug-description-or-issue-ref]"
----
-
-# Debug
-
-Invokes the `debug` skill. Runs 4 phases (Root Cause → Pattern → Impact → Solution) and writes an artifact to `.orchestrator/debug/<session>-<n>.md` before any fix code is written.
-
-## Argument Validation
-
-The optional argument is a short bug description or issue reference (e.g. `"test timeout in CI"` or `#408`). If absent, the skill will inspect recent errors and git log to surface the most likely candidate, then confirm with the user.
-
-## Behavior
-
-1. **Bootstrap gate** — reads `skills/_shared/bootstrap-gate.md`. Gate CLOSED blocks all further steps.
-2. **Phase 1: Root Cause Investigation** — quotes error verbatim, reproduces, checks recent commits via `git log --oneline -20`, instruments component boundaries, traces data flow backward. Writes artifact to `.orchestrator/debug/<session-id>-<n>.md`.
-3. **Phase 2: Pattern Identification** — recurrence? class of bug? missing test? similar code paths in the codebase?
-4. **Phase 3: Impact Analysis** — what else does the root-caused code touch? callers, dependents, transitive effects.
-5. **Phase 4: Solution** — proposes minimal fix + identifies test cases. Records resolution in the artifact.
-
-## Iron Law
-
-The skill enforces: **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.** Skipping Phase 1 is forbidden regardless of how obvious the fix appears. The artifact from Phase 1 is a prerequisite for Phase 4, not optional documentation.
-
-## Artifact location
-
-`.orchestrator/debug/<session-id>-<sequence>.md`
-
-Sequence resets per session (1, 2, 3, …). The artifact records: exact error, reproduction command, suspect commits, instrumentation data, hypothesized root cause (ONE sentence + confidence level), and eventually the resolution.
-
-## Related
-
-- `skills/debug/SKILL.md` — full skill spec (GH #37, umbrella #35)
-- `.claude/rules/verification-before-completion.md` — verify the fix passes fresh (#38)
-- `agents/code-implementer.md` — bugfix-classified tasks reference this skill

package/commands/discovery.md

@@ -1,32 +0,0 @@
----
-description: Systematic quality discovery and issue detection
-argument-hint: "[all|code|infra|ui|arch|session|audit|vault|feature] [--since <git-ref>] [--full]"
----
-
-# Quality Discovery
-
-The user wants to run systematic quality discovery. Invoke the discovery skill with scope: **$ARGUMENTS** (if empty, default to `all`).
-
-## Argument Parsing
-
-Parse `$ARGUMENTS` before doing anything else. Extract the following flags and tokens in any order:
-
-- `--since <git-ref>` — restrict discovery to files changed since the given git ref (e.g. `HEAD~5`, `main`, a commit hash). Sets `since_ref = <git-ref>`.
-- `--full` — explicit full-repo scan. Sets `full_scan = true`.
-- Any remaining tokens are treated as scope specifiers (see below).
-
-**Conflict check:** If BOTH `--since` and `--full` are present, stop immediately and report:
-
-```
-Error: Cannot use --since with --full. Provide one, not both.
-```
-
-Do NOT proceed with discovery when this conflict is present.
-
-**Argument validation:** Valid scopes: `all`, `code`, `infra`, `ui`, `arch`, `session`, `audit`, `vault`, `feature` (comma-separated for multiple). If any scope is invalid, inform the user: "Invalid scope '[token]'. Valid scopes: all, code, infra, ui, arch, session, audit, vault, feature." and default that token to `all`.
-
-When `--since <git-ref>` is provided, pass `since_ref` to the discovery skill (Phase 3 plumbing — see `skills/discovery/SKILL.md`).
-
-Scan the codebase for quality issues, technical debt, and improvement opportunities within the requested scope.
-
-Do NOT skip the interactive triage phase. Every finding must be confirmed by the user before issue creation. Evidence before assertions.

package/commands/dispatcher.md

@@ -1,59 +0,0 @@
----
-description: Pick the next-best repo to work on across the portfolio — rank free repos, recommend one, claim its lease atomically, and route to the entry command
-argument-hint: "[--dry-run] [--repo <name>]"
----
-
-# Dispatcher
-
-Enumerates candidate repos below the confinement root, resolves free/busy from each repo's `session.lock` lease, ranks the FREE ones by backlog priority × staleness × readiness, recommends the single most worthwhile one, claims its lease atomically, and routes you to the chosen entry command. Invoked with arguments: **$ARGUMENTS**
-
-## Argument Parsing
-
-Parse `$ARGUMENTS` before doing anything else.
-
-Recognized flags:
-
-- `--dry-run` — run the non-mutating rank only; print the recommendation and the free-candidate table; do NOT claim any lease.
-- `--repo <name>` — limit the human-readable output to a single `repoName` (informational; does not change ranking). Useful for previewing where one repo lands.
-- `--start-dir <path>` — override the scan root (defaults to the confinement root).
-- `--json` — emit the full `{ candidates, free, ranked, warnings, recommended }` object to stdout.
-
-If `$ARGUMENTS` contains an unrecognized flag (starts with `--` but is not one of the above), inform the user:
-
-```
-Unknown flag '<flag>'. Recognized flags: --dry-run, --repo <name>, --start-dir <path>, --json.
-```
-
-Then continue with the remaining valid arguments.
-
-## Handoff
-
-**Invoke the `dispatcher` skill via the `Skill` tool.** Follow `skills/dispatcher/SKILL.md` precisely:
-
-1. **Enumerate + Rank** — run `node scripts/lib/dispatcher/cli.mjs --json` and surface every warning.
-2. **Verdict gate (#682)** — for the recommended repo, compute `computeSuitabilityVerdict(...)` (four-gate engine). Wire the live signals through honestly: CI as `{ status: ciStatus }` (or `null` on fetch-failure — never a bare string or synthesized-absent object), the real resource verdict string (or `null` on probe-failure — never a fabricated `'green'`), and the TRUE `readRecentAutopilotRuns(...)` count (never `limit < 5`). **Verdict-gated launch:** when the effective dispatcher autonomy is `autonomous-gated` AND the verdict is green (`suitable === true`), the dispatcher MAY launch WITHOUT per-selection confirmation (skip step 3 AUQ → straight to claim). In EVERY other case (any non-`autonomous-gated` dial OR a non-suitable verdict — incl. the `FORCED: CI red` / `FORCED: resource critical` branch, which fails regardless of confidence) it INFORMS the operator of the verdict rationale + warnings, then asks before launch. **Fail-closed: never auto-launch outside the green-verdict autonomous-gated branch.**
-3. **Owner-AUQ** — present the top-ranked free repo as option 1 `(Recommended)` via `AskUserQuestion` (coordinator-only). Skipped only when step 2 green-lit an autonomous launch.
-4. **Atomic claim** — `acquire(...)` BEFORE launching (in BOTH branches); on `ok:false`, exclude the repo and re-rank.
-5. **Route** — invoke the chosen entry command (`/session`, `/plan`, `/discovery`) for the claimed repo.
-6. **Edge cases** — no free repo ⇒ report "all busy", offer resume/wait; never force a selection.
-
-## Exit Codes
-
-| Code | Meaning |
-|---|---|
-| `0` | Success |
-| `1` | User/input error (bad args, bad `--start-dir`) |
-| `2` | System error (unexpected dispatch failure) |
-
-Exit codes follow `.claude/rules/cli-design.md` conventions.
-
-## Related
-
-- `skills/dispatcher/SKILL.md` — skill spec: enumerate → rank → verdict gate → AUQ → atomic claim → route (issues #678, #682)
-- `scripts/lib/dispatcher/enumerate.mjs` — candidate enumeration + free/busy resolution (#676)
-- `scripts/lib/dispatcher/rank.mjs` — backlog priority × staleness × readiness scorer (#677)
-- `scripts/lib/autonomy/suitability.mjs` — `computeSuitabilityVerdict(...)` four-gate verdict engine (#680, wired into launch by #682)
-- `scripts/lib/config/dispatcher-autonomy.mjs` — `resolveDispatcherAutonomy(...)` effective autonomy dial (#679); opt-in by design, fail-closed to `off`
-- `scripts/lib/autopilot/recent-runs.mjs` — `readRecentAutopilotRuns(...)` per-repo kill-switch-history reader feeding the verdict's G2 gate (#682)
-- `scripts/lib/session-lock.mjs` — `acquire(...)` atomic-claim primitive (`linkSync` create-or-fail)
-- `commands/portfolio.md` — cross-repo read-only health dashboard (the dispatcher's read-only sibling)