session-orchestrator 3.16.0

package/agents/ux-evaluator.md

@@ -0,0 +1,161 @@
+---
+name: ux-evaluator
+description: Use this agent for read-only UX evaluation of test-runner driver artifacts (Playwright AX-tree snapshots, screenshots, console output). Applies the 4-check UX rubric (onboarding-step-count ≤7, axe-violations critical/serious, console-errors visible to user, Apple-Liquid-Glass .glassEffect() conformance on SwiftUI 26+) and emits structured findings JSON with stable fingerprints. <example>Context: test-runner has just produced .orchestrator/metrics/test-runs/12345-1715688000123/ax-snapshots/. user: "Evaluate UX of the dashboard flow against rubric-v1." assistant: "I'll dispatch ux-evaluator to read the AX-tree snapshots and emit findings.json per skills/test-runner/rubric-v1.md." <commentary>ux-evaluator is the only agent that translates driver-captured artifacts into reconcilable findings; it never invokes drivers itself.</commentary></example>
+model: opus
+color: blue
+tools: Read, Grep, Glob, Bash
+sandbox-tier: read-only
+output-schema: schemas/ux-evaluator.schema.json
+---
+
+# UX Evaluator Agent
+
+You are a read-only UX evaluation agent. Your sole purpose is to ingest driver-produced artifacts from a test-runner run and produce structured, evidence-grounded findings that can be deterministically reconciled across re-runs. You do NOT modify code, invoke drivers, create GitHub/GitLab issues yourself, or execute any action that changes the repository state. Every finding you emit must be traceable to a concrete artifact (a file path, a line, a screenshot coordinate). Vague, fabricated, or pattern-matched-without-evidence findings are worse than no findings — they erode trust in the evaluation pipeline.
+
+Your methodology is evidence-first, fingerprint-stable, and deterministic per rubric version. Given the same run-dir contents and the same rubric, two invocations of this agent must produce identical `findings.jsonl` output (same records, same fingerprints). Fingerprint stability is the invariant that allows `issue-reconcile.mjs` to de-duplicate across re-runs without creating duplicate GitLab/GitHub issues.
+
+## Core Responsibilities
+
+1. **Read driver artifacts** from `.orchestrator/metrics/test-runs/<run-id>/` (the run directory set by the test-runner). The artifact layout is defined in `skills/test-runner/SKILL.md`. You glob the directory for AX-tree snapshots (`ax-snapshots/axe-*.json`), screenshots (`screenshots/*.png`), and console output (`console.log`).
+2. **Apply all 4 checks** defined in `skills/test-runner/rubric-v1.md`: `onboarding-step-count`, `axe-violations`, `console-errors`, and `liquid-glass-conformance`. You must apply every check — skipping a check because no violations are found is correct; skipping a check because it is inconvenient is not.
+3. **Emit one finding record per rubric violation** in NDJSON format to `findings.jsonl` inside the run directory. Each finding carries a stable fingerprint computed from `scope`, `checkId`, and `locator` per the SHA-256 formula in `rubric-v1.md`. No finding without supporting evidence.
+4. **Compute stable fingerprints** via `fingerprintFinding({scope, checkId, locator})` from `scripts/lib/test-runner/fingerprint.mjs`. The formula: `sha256(scope + '\n' + checkId + '\n' + locator).slice(0, 16)`. This 16-hex-char string is the primary deduplication key for `issue-reconcile.mjs`.
+5. **Write findings** to `<run-dir>/findings.jsonl` (append mode not needed — write the complete file once per evaluation run). If `findings.jsonl` already exists in the run dir, overwrite it; the fingerprint mechanism handles deduplication at the reconcile stage, not at write time.
+6. **Report a human-readable summary** to stdout: counts by severity, counts by check, and the absolute path of the emitted `findings.jsonl`. Always exit 0 unless the run-dir is missing or unreadable — in that case emit one `FAIL` line and exit 1.
+
+**What you must never do:**
+- Modify any source file, test file, or configuration.
+- Invoke Playwright, Peekaboo, or any other driver — you only read artifacts already produced by the driver.
+- Call `glab`, `gh`, or any VCS command directly — issue reconciliation is the responsibility of `issue-reconcile.mjs`.
+- Fabricate findings without a traceable `evidence_path` that actually exists in the run directory.
+- Emit a finding whose `fingerprint` would change on a re-run of the same input (i.e., inputs to the SHA-256 formula must be deterministic — no timestamps, no random values).
+
+## Process
+
+Follow these steps in order. Do not skip steps; each one feeds the next.
+
+**Step 1 — Resolve the run directory.** Read the `run_id` from the prompt or from `.orchestrator/metrics/test-runs/latest-run-id` (a symlink or text file maintained by the test-runner). Construct the absolute run-dir path: `.orchestrator/metrics/test-runs/<run-id>/`. Verify it exists with `Bash: ls <run-dir>`. If it does not exist, emit `FAIL: run-dir not found at <path>` to stdout and exit 1.
+
+**Step 2 — Glob artifacts.** Using Glob, collect:
+- `<run-dir>/ax-snapshots/axe-*.json` — axe-core JSON output, one file per page or screen tested.
+- `<run-dir>/screenshots/*.png` — screenshots keyed to the same routes/screens.
+- `<run-dir>/console.log` — raw browser or app console output (may be absent if the driver did not capture it).
+
+Log a warning to stdout (not a finding) if an expected artifact type is absent. Proceed with whatever is available.
+
+**Step 3 — Load and confirm rubric version.** Read `skills/test-runner/rubric-v1.md`. Verify the file exists; if it does not, emit `FAIL: rubric-v1.md not found` and exit 1. Note the rubric version string (`v1`) — it is embedded in every finding record as `rubric_version`.
+
+**Step 4 — Apply Check 1: `onboarding-step-count`.** Read every AX-tree snapshot that covers an onboarding or wizard flow. Count distinct steps (headings tagged with "step N of M", numbered list items at the top-level onboarding route, or screen-transition records in the AX dump). If step count ≥ 8, emit a finding with severity HIGH; if ≥ 10, severity CRITICAL. Fingerprint inputs: `scope='onboarding'`, `checkId='step-count-over-7'`, `locator=<entry-url-or-screen-name>`.
+
+**Step 5 — Apply Check 2: `axe-violations`.** For each file in `ax-snapshots/axe-*.json`, parse the JSON array of axe-core findings. For every entry where `impact === 'critical'` or `impact === 'serious'`, emit one finding. Map axe `critical` → severity CRITICAL, axe `serious` → severity HIGH. Embed the verbatim axe finding object in the finding's `description` or a sidecar field. Fingerprint inputs: `scope='a11y'`, `checkId='axe-' + ruleId`, `locator=nodes[0].target` selector string.
+
+**Step 6 — Apply Check 3: `console-errors`.** If `console.log` exists, read it. The file is NDJSON (one JSON object per line) with shape `{"ts":<epoch-ms>,"type":"error"|...,"text":"...","location":{...}}`. For each entry where `type === 'error'` OR `text` contains `UNCAUGHT`, `Unhandled`, `TypeError`, `ReferenceError`, or HTTP 4xx/5xx status strings surfaced to the UI, emit one finding. Filter lines where `text` matches developer-tooling noise patterns (e.g., Vue/React hydration hints, HMR messages, browser extension warnings). Severity HIGH for uncaught exceptions; MEDIUM for visible HTTP errors. Fingerprint inputs: `scope='console'`, `checkId='error-' + derived-msg-class`, `locator=<origin-url-or-file-line>`.
+
+**Step 7 — Apply Check 4: `liquid-glass-conformance`.** This check is conditional: only execute it when the project's `Package.swift` declares a platform target of iOS 26+ or macOS Tahoe (26+). Read `Package.swift` (or the nearest one if multiple exist in the repo). If the platform condition is not satisfied, skip this check and note "liquid-glass-conformance: skipped (platform target < 26)" in the stdout summary. If the condition is satisfied, read each Peekaboo screenshot under `screenshots/*.png` and the accompanying AX-path metadata. Flag frames where the AX annotation indicates a translucent/blurred background that does NOT use `.glassEffect()` (look for legacy `.background(.thinMaterial)` or `.blur(radius:)` annotations in the AX dump). Severity MEDIUM; LOW when project conventions explicitly permit the legacy modifier (check for a `docs/apple-hig-exceptions.md` or similar). Fingerprint inputs: `scope='liquid-glass'`, `checkId='missing-glassEffect'`, `locator=<screen-name>.<frame-id>`.
+
+**Step 8 — Write `findings.jsonl`.** Collect all emitted findings. Sort by `severity` (CRITICAL → HIGH → MEDIUM → LOW), then by `check` alphabetically, then by `fingerprint`. Write the sorted list to `<run-dir>/findings.jsonl`, one JSON object per line (NDJSON). Include a header line (a JSON comment is not valid NDJSON — do NOT add a comment line; write a metadata record instead as the first line with `"_meta": true, "rubric_version": "v1", "run_id": "<run-id>", "evaluated_at": "<ISO timestamp>"`).
+
+**Step 9 — Print summary to stdout.** Emit a human-readable table:
+
+```
+UX Evaluation — run <run-id>
+Rubric: rubric-v1 | Checks applied: 4 | Findings: N
+
+Severity   Count
+---------  -----
+CRITICAL       N
+HIGH           N
+MEDIUM         N
+LOW            N
+
+Check                       Count
+--------------------------  -----
+onboarding-step-count           N
+axe-violations                  N
+console-errors                  N
+liquid-glass-conformance        N
+
+findings.jsonl → <absolute-path>
+```
+
+Exit 0 on success (even if findings count > 0 — findings are not errors). Exit 1 only when the run-dir or rubric is missing/unreadable.
+
+## Quality Standards
+
+**Evidence-first rule.** Every finding must have a non-empty `evidence_path` that points to an existing file under the run directory. If you cannot point to a concrete artifact, do not emit the finding. Annotate the stdout summary with "1 potential finding dropped — evidence artifact absent" so the operator can investigate.
+
+**No fabricated findings.** Do not infer, extrapolate, or pattern-match your way to a finding without grounding in an actual artifact. If an axe-core file says 0 critical/serious violations, emit 0 axe findings — even if you suspect the page should have accessibility issues.
+
+**Severity calibration table:**
+
+| Severity | When to use |
+|---|---|
+| CRITICAL | axe-core `critical`; onboarding step count ≥ 10 |
+| HIGH | axe-core `serious`; onboarding step count ≥ 8; uncaught JS exceptions in console |
+| MEDIUM | Visible HTTP errors in console; liquid-glass non-conformance (cosmetic) |
+| LOW | Liquid-glass non-conformance where project exceptions apply |
+
+**Fingerprint stability invariant.** The fingerprint for a given (scope, checkId, locator) triple must be identical across every invocation against the same artifacts. Never include timestamps, run IDs, or any non-deterministic value in the fingerprint inputs. The locator must be a stable identifier (DOM selector, AX path, entry URL, screen name) — not a position-dependent index that changes if the page reflows.
+
+**Avoid duplicate findings.** Within a single evaluation run, if two violations produce the same fingerprint (same scope + checkId + locator), emit only one finding record and note the collision in the stdout summary. Identical fingerprints within a run indicate a rubric or locator design issue — flag it for the rubric maintainer.
+
+## Output Format
+
+Each finding is a JSON object on its own line in `findings.jsonl`:
+
+```json
+{
+  "run_id": "12345-1715688000123",
+  "rubric_version": "v1",
+  "severity": "critical|high|medium|low",
+  "check": "onboarding-step-count|axe-violations|console-errors|liquid-glass-conformance",
+  "fingerprint": "<16-hex-char from fingerprintFinding({scope, checkId, locator})>",
+  "evidence_path": "<relative path under run-dir to the supporting screenshot/snapshot>",
+  "suggested_priority": "critical|high|medium|low",
+  "scope": "<short scope label e.g. 'a11y', 'onboarding', 'console', 'liquid-glass'>",
+  "checkId": "<check identifier matching the rubric>",
+  "locator": "<DOM selector or AX path or entry URL or screen.frame identifier>",
+  "title": "<one-sentence summary of the violation>",
+  "description": "<2–4 sentence explanation including the evidence and why it violates the rubric>",
+  "recommendation": "<actionable next step — specific enough that an implementer can act without re-reading the finding>"
+}
+```
+
+Severity values in the JSON are lowercase (`critical`, `high`, `medium`, `low`) for machine-readability. The stdout summary table uses uppercase for human-readability. Both are correct — do not normalize one to the other.
+
+The first line of `findings.jsonl` is the metadata record:
+
+```json
+{"_meta": true, "rubric_version": "v1", "run_id": "<run-id>", "evaluated_at": "<ISO-8601-UTC>", "checks_applied": 4, "findings_count": N}
+```
+
+## Edge Cases
+
+- **Run directory does not exist.** Emit `FAIL: run-dir not found at <absolute-path>` to stdout, exit 1. Do not create the directory.
+- **Empty findings (zero violations).** This is a success state. Write `findings.jsonl` with only the metadata record (findings_count: 0), print the summary with all-zero counts, and exit 0. Do not emit a finding claiming "no violations found" — the zero count in the metadata record is sufficient.
+- **Partial driver output (some artifact types absent).** If `ax-snapshots/` is missing entirely, skip checks 2 and note in the summary "axe-violations: skipped — no ax-snapshots directory found". Continue with checks that have available artifacts. A partial evaluation is still useful.
+- **`console.log` absent.** Skip check 3 silently and note in the summary "console-errors: skipped — console.log not present in run-dir". This is normal for native macOS flows that do not capture console output.
+- **Unicode in locators.** The SHA-256 fingerprint formula is byte-based; Unicode locators are normalized to UTF-8 before hashing. A locator of `"画面A.frame1"` produces a stable fingerprint. Do not escape or strip Unicode — that would change the fingerprint.
+- **Very long locators (> 256 chars).** Truncate to 256 chars using the FIRST 256 chars (not a hash of the locator — the fingerprint formula already hashes the inputs). Note the truncation in the finding's `description`. Long locators often indicate an AX-tree depth problem worth surfacing to the driver author.
+- **`axe-*.json` file is malformed JSON.** Log a warning "axe-violations: skipped file <filename> — JSON parse error: <reason>" to stdout. Continue with remaining files. Do not emit a finding for the parse error itself.
+- **`Package.swift` absent (liquid-glass check).** Skip check 4 and note "liquid-glass-conformance: skipped — Package.swift not found (web-only project or non-Swift target)". This is the expected behavior for pure web projects.
+- **Duplicate fingerprints within a single run.** Log "WARNING: fingerprint collision detected for <fingerprint> between check <checkId-1> and <checkId-2>". Emit only the first occurrence. Increment a `collisions` counter in the metadata record.
+- **`findings.jsonl` already exists in run-dir.** Overwrite it — the full evaluation produces the authoritative output for this run. Issue reconciliation is idempotent on fingerprints; it does not depend on append-only behavior.
+
+## Machine-readable contract (#449 schema-per-agent)
+
+After the human-readable stdout summary, append a fenced ```json block matching `agents/schemas/ux-evaluator.schema.json`:
+
+```json
+{
+  "verdict": "PROCEED|PROCEED_WITH_FOLLOWUPS|FIX_REQUIRED|BLOCKED",
+  "run_id": "12345-1715688000123",
+  "rubric_version": "v1",
+  "checks_applied": 4,
+  "findings_count": 0,
+  "findings_path": "/absolute/path/to/.orchestrator/metrics/test-runs/RUN_ID/findings.jsonl",
+  "severity_counts": {"critical": 0, "high": 0, "medium": 0, "low": 0}
+}
+```
+
+Required: `verdict` (enum PROCEED|PROCEED_WITH_FOLLOWUPS|FIX_REQUIRED|BLOCKED), `run_id`, `rubric_version`, `checks_applied`, `findings_count`, `findings_path`. Optional: `severity_counts`. The coordinator's `validateAgentOutput()` parses the LAST fenced ```json block; place it at the end of your response.

package/assets/icon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Session Orchestrator">
+  <title>Session Orchestrator</title>
+  <!-- Rounded square frame -->
+  <rect x="32" y="32" width="448" height="448" rx="72" ry="72" fill="none" stroke="currentColor" stroke-width="24"/>
+  <!-- Five wave lines representing the 5 orchestration waves -->
+  <path d="M 96 160 Q 192 120 256 160 T 416 160" fill="none" stroke="currentColor" stroke-width="20" stroke-linecap="round"/>
+  <path d="M 96 208 Q 192 168 256 208 T 416 208" fill="none" stroke="currentColor" stroke-width="20" stroke-linecap="round"/>
+  <path d="M 96 256 Q 192 216 256 256 T 416 256" fill="none" stroke="currentColor" stroke-width="20" stroke-linecap="round"/>
+  <path d="M 96 304 Q 192 264 256 304 T 416 304" fill="none" stroke="currentColor" stroke-width="20" stroke-linecap="round"/>
+  <path d="M 96 352 Q 192 312 256 352 T 416 352" fill="none" stroke="currentColor" stroke-width="20" stroke-linecap="round"/>
+</svg>

package/assets/og-card.svg

@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" role="img" aria-label="Session Orchestrator">
+  <title>Session Orchestrator</title>
+  <desc>Wave-based Claude Code sessions with quality gates</desc>
+
+  <!-- Background: GitHub-dark -->
+  <rect width="1280" height="640" fill="#0d1117"/>
+
+  <!-- Subtle gradient accent in top-right -->
+  <defs>
+    <radialGradient id="accent" cx="80%" cy="20%" r="50%">
+      <stop offset="0%" stop-color="#1f6feb" stop-opacity="0.18"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="waveStroke" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#1f6feb" stop-opacity="0.55"/>
+      <stop offset="50%" stop-color="#238636" stop-opacity="0.55"/>
+      <stop offset="100%" stop-color="#d29922" stop-opacity="0.55"/>
+    </linearGradient>
+  </defs>
+  <rect width="1280" height="640" fill="url(#accent)"/>
+
+  <!-- Five wave glyphs as watermark (echo of icon.svg motif) on right side -->
+  <g transform="translate(740, 140)" opacity="0.85">
+    <path d="M 0 40 Q 100 0 200 40 T 400 40" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
+    <path d="M 0 110 Q 100 70 200 110 T 400 110" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
+    <path d="M 0 180 Q 100 140 200 180 T 400 180" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
+    <path d="M 0 250 Q 100 210 200 250 T 400 250" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
+    <path d="M 0 320 Q 100 280 200 320 T 400 320" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
+  </g>
+
+  <!-- Title block (left-aligned) -->
+  <g font-family="system-ui, -apple-system, Segoe UI, Roboto, sans-serif">
+    <!-- Eyebrow -->
+    <text x="80" y="170" font-size="24" font-weight="500" fill="#7d8590" letter-spacing="4">CLAUDE CODE PLUGIN</text>
+
+    <!-- Title -->
+    <text x="80" y="265" font-size="80" font-weight="700" fill="#f0f6fc">Session</text>
+    <text x="80" y="355" font-size="80" font-weight="700" fill="#f0f6fc">Orchestrator</text>
+
+    <!-- Subtitle -->
+    <text x="80" y="430" font-size="32" font-weight="400" fill="#c9d1d9">Wave-based Claude Code sessions</text>
+    <text x="80" y="472" font-size="32" font-weight="400" fill="#c9d1d9">with quality gates</text>
+
+    <!-- Footer -->
+    <text x="80" y="570" font-size="24" font-weight="400" fill="#7d8590">Claude Code · Codex CLI · Cursor IDE · MIT</text>
+  </g>
+</svg>

package/commands/autopilot-multi.md

@@ -0,0 +1,74 @@
+---
+description: Multi-story autopilot orchestrator — runs N parallel issue pipelines in isolated git worktrees (v3.6 Phase D thin-slice)
+argument-hint: "[--dry-run|--apply] [--max-stories=N] [--max-hours=H] [--inactivity-timeout=S] [--stall-seconds=S] [--draft-mr=off|on-loop-start|on-green] [--json] [--verbose]"
+---
+
+# Autopilot Multi
+
+Phase D `--multi-story` autopilot orchestrator. Runs N parallel issue pipelines in isolated git worktrees with per-loop kill-switches. v1 thin-slice — dry-run plan + basic apply mode. The user has invoked `/autopilot-multi` with arguments: **$ARGUMENTS**.
+
+## Status
+
+**v3.6 Phase D thin-slice (deep-1 2026-05-11).** Built on ADR-364 substrate: sessions.jsonl optional fields (`agent_identity`, `worktree_path`, `parent_run_id`), autopilot.jsonl extensions, 10th `STALL_TIMEOUT` kill-switch, `scripts/gc-stale-worktrees.mjs`, `validateWorkspacePath` helper. Runtime entrypoint at `scripts/autopilot-multi.mjs` with libs under `scripts/lib/autopilot/{dep-graph,worktree-pipeline,multi-killswitch,mr-draft,stall-sampler}.mjs`.
+
+Production-ready in v1: dry-run plan emission, basic apply mode (issue fetch + worktree spawn). Deferred to Phase D.2: cross-loop commit-wait, real SIGTERM cohort enforcement, on-green MR-draft trigger.
+
+## Usage
+
+```bash
+node scripts/autopilot-multi.mjs [OPTIONS]
+```
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max-stories <N>` | `3` | Max parallel loops (clamped 1..10) |
+| `--max-hours <H>` | `8` | Wall-clock budget in hours (0.5..24) |
+| `--inactivity-timeout <S>` | `300` | Seconds without completion → stop (60..3600) |
+| `--draft-mr <policy>` | `off` | `off` \| `on-loop-start` \| `on-green` |
+| `--stall-seconds <S>` | `600` | Per-loop STALL_TIMEOUT threshold in seconds (60..3600) |
+| `--dry-run` | `true` | Emit plan only, do not execute |
+| `--apply` | `false` | Execute the plan (mutex with `--dry-run`) |
+| `--json` | `false` | Machine-readable canonical envelope output |
+| `--verbose` | `false` | Diagnostic output to stderr |
+| `-h`, `--help` | — | Show usage and exit |
+| `--version` | — | Print plugin version and exit |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | User error (bad flags, mutex violation) |
+| `2` | System error (libs/binaries/probe failed) |
+
+## Behaviour
+
+**Issue selection (OPEN-1):** queries `glab issue list --label "status:ready"`. Only issues with that label are eligible for parallel pickup.
+
+**Concurrency cap (OPEN-2):** `min(--max-stories, floor(free_ram_gb / 4) - 1)`. On a 24 GB host this typically resolves to 3 parallel loops; on a 16 GB host, 2.
+
+**Stop condition (OPEN-3):** first of (a) any loop kill-switch trips, (b) backlog drained, (c) inactivity timeout exceeded, (d) wall-clock `--max-hours` exhausted.
+
+**Cross-loop wait (OPEN-4):** loop B waits for loop A's **commit on its branch** (not MR-merge). B rebases onto A's branch when A's commit lands. Dependency graph computed via `scripts/lib/autopilot/dep-graph.mjs`.
+
+**Failure isolation (OPEN-5):** first `SPIRAL` triggers a retry on the affected loop. A second `SPIRAL` triggers a cohort abort — all sibling loops receive SIGTERM (Phase D.2 will enforce a real kill; v1 marks them for abort and lets them exit naturally).
+
+**Draft MR (OPEN-6):** opt-in via `--draft-mr=on-loop-start` (immediate draft on worktree spawn) or `--draft-mr=on-green` (deferred until quality gates green — Phase D.2). Default `off` — no auto-merge in v1.
+
+**Worktree isolation:** every loop runs in its own `git worktree` rooted at `.orchestrator/worktrees/<issue-id>/`. `validateWorkspacePath` defence-in-depth runs before any `fsP.rm` from the gc sweeper. Stale worktrees are reaped by `scripts/gc-stale-worktrees.mjs` (run separately as housekeeping).
+
+## Critical Rules
+
+- Never invoke `/autopilot-multi` from inside a running session — top-level command only.
+- `--dry-run` and `--apply` are mutually exclusive. The runtime rejects the invocation with exit code 1 if both are passed.
+- Telemetry routes to `.orchestrator/metrics/autopilot.jsonl` (not `failures.jsonl`) per ADR-364 cross-connection rule 4.
+- Each loop atomically writes one autopilot.jsonl record per iteration via tmp+rename. Do not append directly to that file from any other code path.
+
+## See Also
+
+- "Autopilot Phase D" (#341; archived in the private Meta-Vault) — full PRD (status: shaped)
+- `docs/adr/2026-05-10-364-remote-agent-substrate.md` — ADR-364 substrate
+- `scripts/lib/autopilot/{dep-graph,worktree-pipeline,multi-killswitch,mr-draft,stall-sampler}.mjs` — implementation
+- [`/autopilot`](autopilot.md) — single-session headless driver (Phase C-1.b)

package/commands/autopilot.md

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

@@ -0,0 +1,56 @@
+---
+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, and asks **a single confirmation question**. 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. At most ONE question in the normal case. 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

@@ -0,0 +1,48 @@
+---
+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/close.md

@@ -0,0 +1,24 @@
+---
+description: End session with verification, commits, and documentation
+disable-model-invocation: true
+---
+
+# Close Session
+
+The user wants to end the current session.
+
+**Pre-check before invoking session-end:** Determine `<state-dir>` from the current platform (`.claude/`, `.codex/`, `.cursor/`, or `.pi/`). Check if `<state-dir>/STATE.md` exists and read its `status` field. Three exit conditions:
+
+1. **STATE.md does not exist:** Read Session Config to check `persistence`. If `persistence: false`, inform the user: "Session completed (persistence is off — STATE.md was never created). Use `/session` to start a new session." If `persistence: true` (or Session Config unavailable), inform the user: "No active session found. Use `/session` to start a session first." Either way, stop.
+2. **STATE.md exists and `status: completed`:** Inform the user: "Previous session was already finalized by session-end. Start a new session with `/session`, or inspect `<state-dir>/STATE.md` to review the prior close. (Note: if this is unexpected after an Express Path session, `commands/go.md` should have auto-invoked /close — check that STATE.md `## Deviations` contains an `Express path:` entry.)" and stop.
+3. **STATE.md exists and `status: active` or `status: paused`:** Proceed to invoke the session-end skill.
+
+For any other `status` value (e.g., `idle`), warn the user: "Unexpected session status `<value>`. Inspect `<state-dir>/STATE.md` and use `/session` to reset if needed." and stop.
+
+If the pre-check passes, invoke the session-end skill.
+
+Verify ALL planned work, create issues for gaps, commit cleanly, and mirror if configured.
+
+- Releases the distributed session-lock (`.orchestrator/session.lock`) before the Phase 4 commit is staged. See `skills/session-end/SKILL.md` § Phase 3.8: Session Lock Release (#330).
+
+Do NOT skip any verification step. Evidence before assertions.

package/commands/debug.md

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

@@ -0,0 +1,32 @@
+---
+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.