session-orchestrator 3.16.0

package/commands/dispatcher.md

@@ -0,0 +1,59 @@
+---
+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)

package/commands/eval.md

@@ -0,0 +1,28 @@
+---
+description: Run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed session against the pre-registered rubric-v1 dimensions
+argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"
+---
+
+# Eval
+
+The user wants to run a session-process evaluation. Invoke the eval skill with arguments: **$ARGUMENTS**.
+
+Scores ONE completed orchestrator session against the pre-registered **rubric-v1**
+check set via the deterministic engine (`scripts/eval-session.mjs`), appends a
+`session-eval` record to the journal (`.orchestrator/metrics/eval.jsonl`), and —
+when configured — renders an HTML report and overlays an advisory LLM judge.
+Deterministic-first; **no global score, by construction**; missing data yields an
+honest `cannot-determine` rather than a guess.
+
+**Usage:**
+
+- `/eval` — evaluate the last completed session (resolution cascade), append the record, render the report
+- `/eval --session <id>` — evaluate a specific session_id
+- `/eval --no-write` — evaluate + report without appending to the journal (dry-run)
+- `/eval --verify <run-id>` — re-score a stored run and diff for drift (the reproducibility proof; exit 1 on drift)
+
+**Seams used:** `scripts/eval-session.mjs` (deterministic CLI) · `runEvalJudge` / `mergeJudgeDimensions` (judge.mjs, opt-in) · `writeEvalReport` (report.mjs) · `appendEvalRecord` (sink.mjs) · `eval` config block · `skills/eval/rubric-v1.md` (frozen check set)
+
+Reads the `eval` block (`enabled`, `mode`, `judge`, `report`, `handle`) from
+Session Config. On-demand `/eval` runs regardless of `eval.enabled` — that flag
+gates only the automatic session-end eval phase.

package/commands/evolve.md

@@ -0,0 +1,10 @@
+---
+description: Extract session patterns into reusable learnings
+argument-hint: "[analyze|review|list|dialectic [--apply]]"
+---
+
+# Evolve
+
+The user wants to extract and manage session learnings. Invoke the evolve skill with mode: **$ARGUMENTS** (if empty, default to `analyze`).
+
+Analyze session history for patterns, review existing learnings, list active intelligence, or derive USER.md/AGENT.md peer-card updates via the dialectic mode. Every learning must be confirmed by the user before persisting. Evidence before assertions.

package/commands/go.md

@@ -0,0 +1,41 @@
+---
+description: Approve session plan and begin wave execution
+disable-model-invocation: true
+argument-hint: "[optional instructions]"
+---
+
+# Execute Session Plan
+
+The user has approved the session plan. Begin execution immediately.
+
+## Express Path Detection
+
+Before invoking the wave-executor, check the conversation context for the Express Path activation banner emitted by session-plan or session-start Phase 8.5:
+
+```
+Express path activated — <N> tasks, coordinator-direct, no inter-wave checks.
+```
+
+If the banner is present (and the session-plan output emitted a 1-wave Express Path plan per `skills/session-plan/SKILL.md` § "Express Path Short-Circuit"):
+
+1. **Execute the agreed tasks directly** as coordinator actions, in dependency order. Do NOT dispatch subagents. Do NOT invoke the wave-executor skill.
+2. **Append the Express Path deviation to STATE.md** before invoking session-end. Use `appendDeviationOnDisk()` from `scripts/lib/state-md.mjs` — the on-disk wrapper takes the STATE.md lock automatically, serialising any concurrent writers. This step ensures the audit trail exists BEFORE session-end finalizes the file. Equivalent one-liner via Bash:
+   ```bash
+   node --input-type=module -e "
+   import {execSync} from 'node:child_process';
+   import {appendDeviationOnDisk} from './scripts/lib/state-md.mjs';
+   const repoRoot = execSync('git rev-parse --show-toplevel', {encoding: 'utf8'}).trim();
+   await appendDeviationOnDisk(repoRoot, new Date().toISOString(), 'Express path: <N> tasks executed coord-direct (express-path.enabled: true, session-type: housekeeping, scope: <N> issues)');
+   "
+   ```
+3. **Invoke `session-orchestrator:session-end`** directly via the `Skill` tool. Session-end finalizes STATE.md (sets `status: completed`, writes `.orchestrator/metrics/sessions.jsonl`, runs vault-mirror if enabled). Without this auto-invocation, every Express Path run leaves no audit trail (issue #320).
+4. **Verify persistence after session-end completes:** read `<state-dir>/STATE.md` and confirm `frontmatter.status === 'completed'` and the body's `## Deviations` section contains an `Express path:` entry. If either is missing, warn the user inline with: `⚠ Express Path persistence verification failed — STATE.md not finalized. Re-run /close manually.` Then return the final summary.
+5. **Return** the session summary to the user. The express-path execution is complete.
+
+If the banner is **absent**: proceed to "Standard Execution" below.
+
+## Standard Execution
+
+**Invoke the wave-executor skill.** Follow the agreed plan wave by wave. Forward `$ARGUMENTS` (if any) to the wave-executor as priority guidance for agent prompts (see wave-executor Pre-Execution: User Instructions).
+
+Do NOT re-plan. Do NOT re-analyze. Execute the agreed plan NOW with maximum efficiency.

package/commands/grill.md

@@ -0,0 +1,45 @@
+---
+description: Stress-test a plan, design, or PRD before any build — relentless one-question-at-a-time interrogation that hunts contradictions against the code and challenges assumptions. Composable; no HARD-GATE.
+argument-hint: "[file-path-or-topic]"
+---
+
+# Grill
+
+Invokes the `grill` skill (`skills/grill/SKILL.md`). Relentlessly interrogates a plan/design/PRD one decision at a time, grounds every question in the codebase, and surfaces contradictions before implementation. Optionally writes `docs/specs/YYYY-MM-DD-<slug>-grill.md`.
+
+## Argument Validation
+
+The optional argument is either a file path to grill (a PRD, spec, `STATE.md`) or a topic/slug. If absent, the skill grills the plan already present in the current conversation; if there is none, it asks the user to state it first.
+
+Examples:
+- `/grill` — grills the plan in the current conversation context
+- `/grill docs/prd/2026-06-09-export.md` — grills a specific PRD file
+- `/grill "partial order cancellation"` — grills the named idea, slug pre-set
+
+## Behavior
+
+1. **Phase 0 — Target Acquisition** — resolve what's being grilled, ground it against the codebase (`CONTEXT.md`, steering docs, ADRs, relevant source), state the target back.
+2. **Phase 1 — Map the Decision Tree** — lay out the dependent decisions root-to-leaf; skip what the code already settles.
+3. **Phase 2 — Grill Loop** — one question per turn via `AskUserQuestion`, applying the Six Tactics (glossary conflict, sharpen fuzzy language, code contradiction, edge-case scenario, assumption audit, pre-mortem); read the repo before asking.
+4. **Phase 3 — Resolved-Decisions Recap** — decisions, contradictions surfaced, open questions, assumptions audited.
+5. **Phase 4 — Hand-off** — AUQ: write grill summary + `/plan feature`, summary only, hand off without a file, or done.
+
+## No HARD-GATE
+
+Unlike `/brainstorm`, grill imposes no implementation gate — it is a composable thinking tool. It writes no code and never commits; the only write it performs is the optional summary file in Phase 4. What happens after the grill is the user's call.
+
+## When to use vs. /brainstorm and /plan feature
+
+| Situation | Use |
+|-----------|-----|
+| A settled-feeling plan needs stress-testing before build | `/grill` |
+| The design is still ambiguous and needs narrowing | `/brainstorm` |
+| Scope is clear, need a formal PRD + issues | `/plan feature` |
+| Adversarial pass before formalizing | `/grill` → `/plan feature` |
+
+## Related
+
+- `skills/grill/SKILL.md` — full skill specification
+- `skills/brainstorm/SKILL.md` — cooperative sibling for ambiguous designs
+- `skills/plan/SKILL.md` — primary hand-off target
+- `.claude/rules/ask-via-tool.md` — AUQ usage convention (AUQ-001..005)

package/commands/harness-audit.md

@@ -0,0 +1,26 @@
+---
+description: Run the harness audit and report the rubric score for this repository
+argument-hint: ""
+---
+
+# Harness Audit
+
+The user wants to audit this repository against the session-orchestrator harness rubric. There are no arguments.
+
+Run the audit script and surface the results:
+
+```bash
+node scripts/harness-audit.mjs
+```
+
+The script writes a concise human-readable summary to stderr and emits a JSON record to stdout. Capture both:
+
+1. Print the stderr summary verbatim so the user sees it immediately.
+2. Parse the stdout JSON and report:
+   - `summary.overall_band` — `healthy`, `warn`, or `critical`
+   - `summary.overall_mean_0_10` — the numeric score
+   - Any category with `score_0_10 < 7`, listing its name and score
+
+The full JSON record is also appended automatically to `.orchestrator/metrics/audit.jsonl` by the script — no additional action needed.
+
+If the script exits non-zero, report the error output to the user verbatim. Do not interpret or retry.

package/commands/memory-cleanup.md

@@ -0,0 +1,25 @@
+---
+description: Manual memory consolidation — review, consolidate, and prune memory files (Dream-equivalent)
+argument-hint: "[--dry-run | --apply-pending]"
+---
+
+# Memory Cleanup
+
+The user wants to consolidate the project's auto-memory store. Invoke the `memory-cleanup` skill.
+
+## Flags
+
+The skill accepts two optional, mutually-exclusive flags (see PRD #502):
+
+| Flag | Behavior |
+|---|---|
+| `--dry-run` | Run Phases 1-3 read-only. Writes a complete-replacement MEMORY.md proposal (single fenced ` ```markdown ` block; topic-file changes carried as separate `### Topic-file change:` sections after it — never git-style diff hunks, see #717) to `.orchestrator/pending-dream.md` (atomic write). Prints `pending-dream written: <N> lines proposed` (or `no consolidation needed`). Exit 0. |
+| `--apply-pending` | Reads `.orchestrator/pending-dream.md`, refuses if older than 14 days or if MEMORY.md changed since the producing `--dry-run` (#788), applies the proposal, deletes the pending file. Prints `auto-dream applied: -<X> lines, +<Y> entries`. Exit 0 on apply; exit 1 when pending file is missing (`no pending dream to apply`), stale (`pending dream is stale (>14d), re-run --dry-run`), index-drifted (`MEMORY.md changed since the producing --dry-run; re-run --dry-run.`), or unsupported-format (`auto-dream NOT applied: pending-dream.md contains git-style diff hunks this applier cannot consume. MEMORY.md left untouched, sidecar preserved. Re-run /memory-cleanup --dry-run to regenerate a complete-body proposal.`). |
+
+Passing both flags is an error. Absence of both = legacy interactive 4-phase mode.
+
+Session-end Phase 3.6.5 (`scripts/lib/auto-dream.mjs`) is nudge-only (#614) — it never dispatches a subagent to write the sidecar. The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock.
+
+## Default (no flag)
+
+Run the 4-phase Dream process (Orient → Gather Signal → Consolidate → Prune & Index) against `~/.claude/projects/<encoded-cwd>/memory/`. Report files changed, `MEMORY.md` line count before/after, contradictions resolved, and any items that need manual attention.

package/commands/persona-panel.md

@@ -0,0 +1,121 @@
+---
+description: Run a parallel multi-persona domain-expert review panel against a file, directory, or output range
+argument-hint: "<target> [--personas <names,...>] [--mode <voting|hard-gate|summary>] [--threshold <M-of-N|all|any>] [--grounding <off|re-derive>] [--dry-run]"
+disable-model-invocation: false
+---
+
+# Persona Panel
+
+Dispatches N personas from the per-repo `.claude/personas/` catalog in parallel (one `Agent()` call per persona), consolidates their outputs, persists a sidecar to `.orchestrator/persona-panel/`, and reports the final verdict. Invoke the `persona-panel` skill with arguments: **$ARGUMENTS**
+
+## Argument Validation
+
+Parse `$ARGUMENTS` before doing anything else.
+
+**Positional argument (required):**
+
+- `<target>` — file path, directory, or range to review. Must be resolvable via `validatePathInsideProject` against the current project root. Relative paths are resolved from the project root. Globs are accepted (e.g., `src/app/api/*.ts`).
+
+**Recognized flags:**
+
+- `--personas <names,...>` — comma-separated subset of catalog names to include (e.g., `physicist,ai-expert`). Default: all personas discovered in `.claude/personas/`. Names are matched case-insensitively against `<name>.md` catalog files.
+- `--mode <voting|hard-gate|summary>` — consolidation mode. Default: `voting`.
+  - `voting` — M-of-N quorum; deterministic. Requires `--threshold M-of-N` or defaults to `all`.
+  - `hard-gate` — all N personas must PASS; deterministic. `--threshold all` is the default; `--threshold N-of-N` is also accepted.
+  - `summary` — coordinator LLM-aggregate of heterogeneous outputs. Emits an explicit WARN that this mode adds one additional LLM call.
+- `--threshold <spec>` — quorum spec. Accepted forms: `M-of-N` where M and N are integers 1..20, `all`, or `any`. Parsed by `scripts/lib/persona-panel/threshold.mjs::parseThreshold()`. Default: `all`.
+- `--grounding <off|re-derive>` — Grounding-Review mode (#730 Epic H). `off` (default): personas evaluate the target as-is. `re-derive`: each persona is instructed to independently re-derive supporting sources via Read/Grep/Glob instead of trusting a "Sources" section the target may already assert, and reports them as `derived_sources`. Advisory-only in v1 — never influences `final_verdict`. See `skills/persona-panel/persona-format.md` § "Grounding Mode (optional)".
+- `--dry-run` — resolve catalog, print dispatch plan, do NOT call `Agent()`, do NOT write sidecar. Exit 0 on success.
+
+**Validation errors (all exit 1):**
+
+- Missing `<target>`: `missing required arg <target>`.
+- Unknown flag (starts with `--` but not in the list above): `unknown flag: --<name>. Valid: --personas, --mode, --threshold, --grounding, --dry-run`.
+- `--mode` value not in enum: `invalid --mode value: '<value>'. Valid: voting, hard-gate, summary`.
+- `--threshold` value fails `parseThreshold()`: echo the parser error verbatim, e.g., `invalid threshold 'foo': expected M-of-N (M,N integers 1..20), 'all', or 'any'`.
+- `--grounding` value not in enum: `invalid --grounding value: '<value>'. Valid: off, re-derive`.
+- `<target>` outside project root: `target path outside project: <path>`.
+
+If `<target>` is missing, print the usage line and exit 1 without invoking the skill.
+
+## Behavior
+
+**Phase 1 — Catalog Discovery**
+
+The skill scans `.claude/personas/*.md` in the current repo. Each file must have YAML frontmatter with at minimum `name`, `role`, and `tier`. If `--personas` is given, only matching files are loaded; unmatched names produce a warning but do not abort (the remaining personas proceed). If zero personas are resolved after filtering, exit 1 with: `no personas resolved — check .claude/personas/ or --personas filter`.
+
+**Phase 2 — Target Resolution**
+
+`<target>` is validated via `validatePathInsideProject`. Globs are expanded; directories are passed as-is for the skill to recurse. The resolved target is attached to each persona's prompt context.
+
+**Phase 3 — Parallel Dispatch**
+
+One `Agent()` call per resolved persona. Agents run with the persona's `model` frontmatter field (default `claude-opus-4-7`). Each agent receives the persona body as its system prompt and the target file content (or directory listing) as context. Agent outputs are collected in an `outputs[]` array keyed by persona name.
+
+**Phase 4 — Consolidation**
+
+Mode determines the consolidation strategy:
+
+- `voting` — count PASS verdicts. Apply `--threshold` to determine final verdict. Dissenting personas (FAIL or UNCLEAR) are listed explicitly.
+- `hard-gate` — all resolved personas must return PASS. Any single FAIL or UNCLEAR produces a final verdict of FAIL. Dissenting personas are listed.
+- `summary` — coordinator LLM call aggregates heterogeneous outputs into a structured narrative. A WARN is emitted before dispatch: `summary mode adds one additional LLM call`.
+
+**Phase 5 — Sidecar Persist + Report**
+
+Unless `--dry-run`, a sidecar is written to `.orchestrator/persona-panel/<isoTs>-<run-id>.json` matching the schema at `agents/schemas/persona-panel-sidecar.schema.json`. The sidecar includes `run_id`, `target`, `personas_invoked[]`, `outputs[]`, and `consolidation` (mode, final-verdict, dissenting-personas, audit-reason).
+
+The command emits a summary line to stdout:
+
+```
+persona-panel: <final-verdict> (<M>/<N> PASS) — sidecar: .orchestrator/persona-panel/<filename>.json
+Dissenting: <name1>, <name2>  [omitted when none]
+```
+
+## Examples
+
+**1. Default — all catalog personas, voting mode:**
+
+```
+/persona-panel src/app/api/invoices.ts
+```
+
+Loads all `.claude/personas/*.md`, dispatches one agent per persona, applies voting with threshold `all`, writes sidecar.
+
+**2. Specific personas:**
+
+```
+/persona-panel src/app/api/invoices.ts --personas physicist,ai-expert
+```
+
+Only the `physicist` and `ai-expert` catalog entries are dispatched. Others are skipped.
+
+**3. Hard-gate mode, unanimous threshold:**
+
+```
+/persona-panel notes/draft.md --mode hard-gate --threshold all
+```
+
+All resolved personas must return PASS. A single FAIL produces a final FAIL verdict.
+
+**4. Dry-run — inspect dispatch plan without executing:**
+
+```
+/persona-panel src/ --dry-run
+```
+
+Resolves catalog and target, prints the planned dispatch list (persona names, models, target), exits 0 without calling `Agent()` or writing a sidecar.
+
+**5. Grounding-review mode — personas re-derive their own sources:**
+
+```
+/persona-panel docs/design-doc.md --grounding re-derive
+```
+
+Each dispatched persona is instructed to independently re-derive supporting sources via Read/Grep/Glob rather than trusting a "Sources" section already present in `docs/design-doc.md`, and reports them as `derived_sources`. Advisory-only — `final_verdict` is unaffected.
+
+## Related
+
+- `skills/persona-panel/SKILL.md` — skill spec: 6 phases, catalog format, dispatch mechanics, consolidation logic, sidecar schema
+- `agents/schemas/persona-panel-sidecar.schema.json` — AJV Draft 2020-12 sidecar schema
+- Issue #458 — wave-hook integration (persona-panel as inter-wave quality gate)
+- Issue #460 — trend tracking across persona-panel runs

package/commands/plan.md

@@ -0,0 +1,15 @@
+---
+description: Plan a new project, feature, or retrospective with structured requirement gathering
+disable-model-invocation: true
+argument-hint: "[new|feature|retro]"
+---
+
+# Plan
+
+You are beginning a structured planning session. The user has invoked `/plan` with mode: **$ARGUMENTS** (if empty, ask the user which mode they want: `new`, `feature`, or `retro`).
+
+**Modes:** `new` = project kickoff, `feature` = feature PRD, `retro` = retrospective.
+
+**Your job: Guide the user through structured requirement gathering and produce a complete plan document for the chosen mode.**
+
+**Invoke the plan skill.** Follow its instructions precisely. Do NOT skip any phase. Do NOT make assumptions — gather requirements interactively.

package/commands/portfolio.md

@@ -0,0 +1,97 @@
+---
+description: Aggregate cross-repo issue/MR/CI health across vault-registered projects into a single Markdown dashboard
+argument-hint: "[--dry-run] [--repo <name>]"
+---
+
+# Portfolio
+
+Aggregates open issues, MRs, and staleness signals across all vault-registered repositories and writes a structured dashboard to `<vault-dir>/01-projects/_PORTFOLIO.md`. Invoke the `gitlab-portfolio` skill with arguments: **$ARGUMENTS**
+
+## Argument Validation
+
+Parse `$ARGUMENTS` before doing anything else.
+
+Recognized flags:
+
+- `--dry-run` — run discovery + aggregation, print the diff to stdout, do NOT write the dashboard. Sets `dry_run = true`.
+- `--repo <name>` — limit the run to a single vault slug (e.g. `session-orchestrator`). Implies `--dry-run` unless explicitly combined with a write flag. Useful for testing repo discovery without refreshing the full portfolio.
+
+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>.
+```
+
+Then continue with the remaining valid arguments.
+
+## Behavior
+
+1. **Config gate** — Read the `gitlab-portfolio:` block from Session Config. If `enabled: false` (or the block is absent), log `Portfolio: disabled (gitlab-portfolio.enabled is false) — set enabled: true to activate.` and return exit code 0.
+
+2. **Mode gate** — If `mode: off`, the command is a silent no-op; log a single line and exit 0.
+
+3. **Vault resolution** — Read `vault-integration.vault-dir` from Session Config. If `vault-integration.enabled: false` or `vault-dir` is absent, exit 1 with: `Portfolio: vault-integration must be enabled with vault-dir set.`
+
+4. **Dispatch** — Invoke `scripts/lib/gitlab-portfolio/cli.mjs` with the resolved arguments:
+
+   ```bash
+   node scripts/lib/gitlab-portfolio/cli.mjs \
+     --vault-dir <vault-dir> \
+     [--dry-run] \
+     [--repo <name>]
+   ```
+
+5. **Report** — Print the action result emitted by the CLI (`action: written | skipped-noop | skipped-handwritten | dry-run`) and exit with the CLI's exit code.
+
+## Config Required
+
+Minimum Session Config to enable the command:
+
+```yaml
+vault-integration:
+  enabled: true
+  vault-dir: ~/Projects/vault
+gitlab-portfolio:
+  enabled: true
+```
+
+Full config reference (all fields with defaults):
+
+```yaml
+gitlab-portfolio:
+  enabled: true
+  mode: warn          # warn | strict | off
+  stale-days: 30
+  critical-labels: ["priority:critical", "priority:high"]
+```
+
+## Output Format
+
+See `skills/gitlab-portfolio/SKILL.md` § Output format for the full dashboard schema (frontmatter keys, summary table, per-repo sections, idempotency guard).
+
+## Error Modes
+
+Behaviour is governed by the `mode` config field:
+
+- `warn` (default): per-repo CLI failures are logged to stderr; the portfolio is rendered with the remaining repos. Exit 0.
+- `strict`: any repo fetch failure causes a non-zero exit before writing. The dashboard is NOT written.
+- `off`: command is a silent no-op. Logs a single line and exits 0.
+
+`--vault-dir` not found and write errors always exit 2 regardless of `mode`.
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success (or `mode: off` / `enabled: false` no-op) |
+| `1` | User/config error (bad args, missing vault config) |
+| `2` | System error (vault-dir not found, write failed) |
+| `3` | Repo fetch failures in `strict` mode |
+
+Exit codes follow `.claude/rules/cli-design.md` conventions.
+
+## Related
+
+- `skills/gitlab-portfolio/SKILL.md` — skill spec, aggregation phases, output schema, error handling (GH #41)
+- `skills/vault-mirror/SKILL.md` — vault registration conventions (`_overview.md` frontmatter, `.vault.yaml`)
+- Session-start Phase 2.7 — optional banner that surfaces portfolio staleness at session-start in dry-run mode

package/commands/reconcile.md

@@ -0,0 +1,23 @@
+---
+description: Reconcile learnings into .claude/rules/ proposals — on-demand version of session-end Phase 3.6.8
+argument-hint: "[--dry-run]"
+---
+
+# Reconcile
+
+The user wants to reconcile learnings into rule proposals. Invoke the reconcile skill with arguments: **$ARGUMENTS**.
+
+Runs the same pipeline as session-end Phase 3.6.8: filters eligible learnings from
+`.orchestrator/metrics/learnings.jsonl`, renders proposed `.claude/rules/<slug>.md` entries,
+and presents them to the operator via AUQ multiSelect (batches of 4) for approval before
+writing. Advisory-only — no rule is ever written without explicit operator confirmation.
+
+**Usage:**
+
+- `/reconcile` — full approval flow: engine → AUQ → write approved rules
+- `/reconcile --dry-run` — print proposals and rejections without writing anything or rendering the AUQ prompt
+
+**Engine seams used:** `runReconcile` (engine.mjs) · `writeApprovedRules` (writer.mjs) · `reconcile` config block · `.claude/rules/` write target
+
+Reads `reconcile.rule-expiry-days` and `reconcile.confidence-floor` from Session Config.
+The `reconcile.enabled` flag is NOT checked — this command always runs on-demand.

package/commands/repo-audit.md

@@ -0,0 +1,24 @@
+---
+description: Run a 9-category baseline compliance audit on the current repository
+argument-hint: ""
+---
+
+# Repo Audit
+
+The user wants to audit the current repository against the ecosystem baseline. There are no arguments.
+
+Invoke `skills/repo-audit/SKILL.md` to perform the audit.
+
+The skill will:
+1. Read Session Config to resolve `test-command`, `typecheck-command`, and `lint-command` (falls back to `pnpm test --run`, `tsgo --noEmit`, `pnpm lint`)
+2. Detect Clank integration markers (`.clank/`, `clank.config.*`) — Category 8 is skipped if absent
+3. Run all 9 audit categories with status: ✓ pass / ✗ fail / ⚠ warn / skipped
+4. Emit a structured Markdown report to stdout
+5. Write a JSON sidecar to `.orchestrator/metrics/repo-audit-<timestamp>.json`
+
+Do NOT skip any category (except Clank when not detected). Do NOT auto-fix findings — report only.
+
+Distinguish from related commands:
+- `/discovery` — broad quality probes, interactive triage, creates issues
+- `/harness-audit` — plugin installation health (is session-orchestrator installed correctly?)
+- `/repo-audit` — consuming-repo compliance (does this repo match the ecosystem baseline?)

package/commands/session.md

@@ -0,0 +1,30 @@
+---
+description: Start a development session (housekeeping, feature, deep)
+argument-hint: "[housekeeping|feature|deep]"
+---
+
+# Session Start
+
+You are beginning a new development session. The user has invoked `/session` with type: **$ARGUMENTS** (if empty, auto-detect from the project's `## Session Config` block or default to `feature`).
+
+**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. If `$ARGUMENTS` is not empty and does not match any valid type, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep." Then auto-detect from the project's `## Session Config` block or default to `feature`.
+
+## Resume Support
+
+When `<state-dir>/STATE.md` exists with `status: active` or `status: paused`, session-start surfaces a resume prompt (Phase 0.5). The `## Mission Status` body section in STATE.md — written by wave-executor via `setMissionStatus` from `scripts/lib/state-md.mjs` — identifies where execution left off:
+
+1. Read the `## Mission Status` section entries using `readMissionStatus(stateContent, taskId)` (one call per task ID from the wave plan).
+2. The task with the most-advanced status that is NOT yet `completed` is the **resume-from point**:
+   - `in-dev` entry → that agent was in-flight; re-dispatch it (or skip if its files show work done)
+   - `validated` entry with no `in-dev` items → the wave was approved but not started; begin wave dispatch
+   - All items `completed` → wave finished; proceed to the next wave
+3. Items still at `brainstormed` were not yet user-approved; re-present the plan excerpt for approval.
+4. Items at `testing` had implementation complete but Quality gate not yet run; treat as the Quality wave starting point.
+
+This read is informational — session-start uses it to populate the resume banner and recommend which wave to re-enter. The wave-executor then applies the actual transitions when `/go` is confirmed.
+
+**Your job: Autonomously research the full project state, then present structured findings with recommendations for the user to approve before creating a wave plan.**
+
+**Cold-start banner (PRD #500):** If `bootstrap.lock` exists with timestamp older than `cold-start.nudge-after-hours` (default 1h) and `sessions.jsonl` is empty, the SessionStart hook emits a one-time first-session nudge. Auto-silenced once `sessions.jsonl` has ≥ `cold-start.silence-after-sessions` entries (default 1).
+
+**Invoke `session-orchestrator:session-start` via the `Skill` tool.** Follow its instructions precisely. Do NOT skip any phase. Do NOT make assumptions — verify everything in code and on the VCS platform.

package/commands/spinout.md

@@ -0,0 +1,15 @@
+---
+description: Guided 5-step venture-spinout / sanitized-fork runbook (copy + fresh-init + SNAPSHOT-FREEZE) — interactive, not scripted
+argument-hint: "[--type venture|snapshot] [--dry-run]"
+---
+
+# Spinout
+
+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. Invoke the `spinout` skill.
+
+## Flags
+
+| 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. |

package/commands/sunset-review.md

@@ -0,0 +1,27 @@
+---
+description: Identify unused / near-zero-use / stale skills, agents, and commands as Demote or Retire candidates (read-only; never deletes)
+argument-hint: "[--kind skill|agent|command] [--window-days N]"
+---
+
+# Sunset Review
+
+The user wants to identify which skills, agents, and commands in the plugin surface are still in use and which are candidates to demote or retire. Optional arguments narrow the scope: `--kind` limits to one surface kind, `--window-days` overrides the default 90-day dispatch window.
+
+Invoke `skills/sunset-review/SKILL.md` to perform the review.
+
+The skill will:
+1. Resolve the dispatch window (default 90 days; honour any `--window-days` override)
+2. Run the read-only walker `node scripts/lib/sunset/walker.mjs --json` to combine agent-dispatch telemetry (start-events only) with static reference scanning
+3. Classify every surface item into Active / Investigate / Demote / Retire, grouped for review
+4. Emit a Markdown report + JSON sidecar at `.orchestrator/metrics/sunset-review-<timestamp>.{md,json}`
+5. Record the run time for the quarterly cadence nudge
+
+Critical guardrails:
+- The walker is READ-ONLY and NEVER deletes a skill/agent/command. It surfaces candidates for human decision only.
+- Telemetry only spans ~18 days, so the 90-day window cannot be satisfied — every Retire verdict is downgraded to Investigate and `meta.lowConfidence` is set. Do not retire anything while low-confidence.
+- Draft-issue creation for candidates is a coordinator-side AskUserQuestion decision (AUQ-004) — a dispatched agent cannot file issues itself.
+
+Distinguish from related commands:
+- `/repo-audit` — does this repo match the ecosystem baseline? (compliance pass/fail)
+- `/sunset-review` — which parts of OUR surface are unused? (prune candidates)
+- `/harness-audit` — is session-orchestrator installed correctly? (plugin health)