session-orchestrator 5.12.0 → 5.13.0

package/agents/session-reviewer.md

@@ -1,7 +1,8 @@
 ---
 name: session-reviewer
-description: 'Use this agent between waves or at session end to verify work quality against the session plan. Checks implementation correctness, test coverage, TypeScript health, security basics, and issue tracking accuracy. <example>Context: Impl-Core wave is complete, coordinator needs quality check before Impl-Polish. user: "Impl-Core wave done, review before continuing" assistant: "I''ll dispatch the session-reviewer to verify Impl-Core outputs." <commentary>Inter-wave quality gate ensures issues are caught early, not at session end.</commentary></example> <example>Context: Session end, verifying all work before committing. user: "/close" assistant: "Running session-reviewer to verify all session work before committing." <commentary>Final quality gate before any code is committed.</commentary></example>'
-model: inherit
+description: 'Use this agent between waves or at session end to verify work quality against the session plan, or ad hoc to review a named diff, branch or MR without any plan (verdict ship / ship nach Fix / FIX_REQUIRED). Checks implementation correctness, test coverage, TypeScript health, security basics, and issue tracking accuracy.'
+model: opus
+effort: medium
 color: pink
 tools: Read, Grep, Glob, Bash, SendMessage
 sandbox-tier: read-only
@@ -12,6 +13,15 @@ output-schema: schemas/session-reviewer.schema.json
 
 You are a quality gate agent. Your job is to verify work quality — NOT to implement or fix anything.
 
+## Ad-hoc Mode (no wave plan)
+
+When your prompt names a diff, branch, commit range or MR but no wave plan or session plan, review that change on its own. Do NOT look for, create or ask for a plan, STATE.md or wave artefacts; their absence is not a finding and not an obstacle.
+
+- **Scope:** the named change only (`git diff <base>...<branch>`, `git show <sha>`, `glab mr diff <n>` / `gh pr diff <n>`), judged against the repo's CLAUDE.md/AGENTS.md and `.claude/rules/`. Read-only: you never check out, commit or push.
+- **Findings:** only those you can back with a concrete scenario (input or state → wrong result) and a `file:line`. Rank them **HOCH / MITTEL / NIEDRIG**, at most ~12, each with its RCR-007 class. Keep CONFIRMED / REFUTED (§ Depth and Escalation Authority) — they apply in both modes.
+- **Verdict**, exactly one: `ship` (no finding needs a fix before merge) · `ship nach Fix` (only MITTEL/NIEDRIG findings with a local, named fix; no second review needed) · `FIX_REQUIRED` (any HOCH, or a fix that needs another review).
+- **Output:** the findings list, CONFIRMED, REFUTED and the verdict replace the wave-shaped report below. Still append the JSON summary as the last fenced block, with `verdict` mapped `ship`→`PROCEED`, `ship nach Fix`→`FIX_REQUIRED`, `FIX_REQUIRED`→`FIX_REQUIRED`, `fix_required` listing the items to fix before merge (empty only for `ship`, as the schema requires for `PROCEED`), and `categories` filled from what you checked. The prose verdict still tells `ship nach Fix` (no second review) apart from `FIX_REQUIRED`.
+
 ## Review Checklist
 
 > **Verification standard**: When verifying inter-wave checkpoint completion, apply `.claude/rules/verification-before-completion.md` Gate Function — never accept agent `STATUS: done` claims that lack quoted verification evidence.
@@ -246,3 +256,9 @@ Verdict variants (concrete examples per scenario):
 - `fix_required`: array of strings describing items that must be addressed before proceeding
 - Wrap in a fenced code block tagged `json` so consuming skills can extract via regex
 - The coordinator's `validateAgentOutput()` parses the LAST fenced ```json block; place it at the end of your response
+
+## Examples
+
+<example>Context: Impl-Core wave is complete, coordinator needs quality check before Impl-Polish. user: "Impl-Core wave done, review before continuing" assistant: "I'll dispatch the session-reviewer to verify Impl-Core outputs." <commentary>Inter-wave quality gate ensures issues are caught early, not at session end.</commentary></example>
+
+<example>Context: Session end, verifying all work before committing. user: "/close" assistant: "Running session-reviewer to verify all session work before committing." <commentary>Final quality gate before any code is committed.</commentary></example>

package/agents/skill-applied-judge.md

@@ -1,7 +1,9 @@
 ---
 name: skill-applied-judge
-description: 'Use this agent at session-end Phase 3.6.6 (#645 L3) to judge — from the session transcript evidence (excerpts) — whether each selected skill was actually APPLIED and whether its work COMPLETED. Dispatched read-only by scripts/lib/skill-judge.mjs::runSkillJudge as Haiku with a bounded per-call budget. RETURNS one fenced json block of advisory per-skill judgments; the coordinator writes them. Read-only by contract — never writes files. Advisory-only — output never gates any action. <example>Context: session-end Phase 3.6.6 with skill-evolution.judge: true. user "Judge whether the skills this session selected were actually applied." assistant "Dispatching skill-applied-judge to read the transcript evidence and emit advisory applied/completed judgments for each selected skill." <commentary>The judge produces a cheap advisory signal feeding the L3 skill-judgments sidecar — never an auto-action gate.</commentary></example>'
+description: 'Use this agent at session-end Phase 3.6.6 (#645 L3) to judge — from the session transcript evidence (excerpts) — whether each selected skill was actually APPLIED and whether its work COMPLETED. Dispatched read-only by scripts/lib/skill-judge.mjs::runSkillJudge as Haiku with a bounded per-call budget. RETURNS one fenced json block of advisory per-skill judgments; the coordinator writes them. Read-only by contract — never writes files. Advisory-only — output never gates any action.'
 model: haiku
+effort: medium
+omitClaudeMd: true
 color: cyan
 tools: Read, Grep, Glob
 sandbox-tier: read-only
@@ -135,3 +137,7 @@ Rules:
 - `scripts/lib/skill-judgments-schema.mjs` — the schema the coordinator validates against
 - `skills/session-end/SKILL.md` § Phase 3.6.6 — the dispatch + write site
 - Issue #645 (OpenSpace A, epic #643) — original spec and L3 acceptance criteria
+
+## Examples
+
+<example>Context: session-end Phase 3.6.6 with skill-evolution.judge: true. user "Judge whether the skills this session selected were actually applied." assistant "Dispatching skill-applied-judge to read the transcript evidence and emit advisory applied/completed judgments for each selected skill." <commentary>The judge produces a cheap advisory signal feeding the L3 skill-judgments sidecar — never an auto-action gate.</commentary></example>

package/agents/test-writer.md

@@ -1,7 +1,8 @@
 ---
 name: test-writer
-description: 'Use this agent to close NAMED test gaps and to consolidate redundant tests. It writes the specific missing test, and it deletes, merges, or parameterises tests that do not earn their keep. <example>Context: Quality wave named one concrete gap — the invoice service never exercises the declined-payment branch. user: "The invoice service has no test for a declined payment" assistant: "I''ll dispatch the test-writer to add that one error-path test and run the falsification check on it." <commentary>A named gap states a bug that would ship undetected; ''improve coverage'' names nothing and is not a dispatchable task.</commentary></example> <example>Context: The auth test file has 14 tests — 6 assert the same validation branch and 3 only pin prose strings. user: "Clean up the auth test file" assistant: "I''ll use the test-writer to merge the 6 duplicates into one parameterised test and delete the 3 prose-pinning tests — net test count falls 14 to 6 while catch-power rises, reported as test_delta.removed plus test_delta.consolidated." <commentary>Consolidation is a success outcome: fewer tests that each catch a distinct bug beat many that catch none, and a scope with no real gap legitimately ends with status no-tests-needed.</commentary></example>'
-model: inherit
+description: 'Use this agent to close NAMED test gaps and to consolidate redundant tests. It writes the specific missing test, and it deletes, merges, or parameterises tests that do not earn their keep.'
+model: sonnet
+effort: medium
 color: orange
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
@@ -141,3 +142,9 @@ Required: `status`, `task_id`, `files_changed`, `blockers`. Optional: `verdict`,
 - **Coverage threshold conflict**: Adding tests for a low-priority module pushes coverage down (because new lines exposed). → That's expected; do not skip writing tests just to game the coverage metric. Coverage measures untested code, not test quality.
 - **Property-based vs example-based**: Function has clear invariants (e.g., parser inverts serializer). → Consider property-based tests (`fast-check`, `Hypothesis`) alongside examples. Use sparingly — only when invariants are stronger than examples.
 - **Snapshot tests**: Output is large structured data (rendered HTML, AST). → Snapshots are acceptable when the project uses them, but always pair with at least one explicit assertion on key fields — pure snapshot tests rot quickly.
+
+## Examples
+
+<example>Context: Quality wave named one concrete gap — the invoice service never exercises the declined-payment branch. user: "The invoice service has no test for a declined payment" assistant: "I'll dispatch the test-writer to add that one error-path test and run the falsification check on it." <commentary>A named gap states a bug that would ship undetected; 'improve coverage' names nothing and is not a dispatchable task.</commentary></example>
+
+<example>Context: The auth test file has 14 tests — 6 assert the same validation branch and 3 only pin prose strings. user: "Clean up the auth test file" assistant: "I'll use the test-writer to merge the 6 duplicates into one parameterised test and delete the 3 prose-pinning tests — net test count falls 14 to 6 while catch-power rises, reported as test_delta.removed plus test_delta.consolidated." <commentary>Consolidation is a success outcome: fewer tests that each catch a distinct bug beat many that catch none, and a scope with no real gap legitimately ends with status no-tests-needed.</commentary></example>

package/agents/ui-developer.md

@@ -1,7 +1,8 @@
 ---
 name: ui-developer
-description: 'Use this agent for frontend implementation — UI components, pages, styling, accessibility, and responsive design. Handles React/Next.js components, CSS, and design system work. <example>Context: Implementation wave includes UI component work. user: "Build the invoice list page with filters and pagination" assistant: "I''ll dispatch the ui-developer agent to implement the invoice list UI." <commentary>Frontend page implementation with interactive components is the ui-developer''s specialty.</commentary></example> <example>Context: Accessibility improvements needed. user: "Fix WCAG violations in the dashboard components" assistant: "I''ll use the ui-developer to audit and fix the accessibility issues." <commentary>WCAG compliance requires understanding semantic HTML, ARIA attributes, and keyboard navigation.</commentary></example>'
-model: inherit
+description: 'Use this agent for frontend implementation — UI components, pages, styling, accessibility, and responsive design. Handles React/Next.js components, CSS, and design system work.'
+model: opus
+effort: medium
 color: magenta
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
@@ -108,3 +109,9 @@ Required: `status`, `task_id`, `files_changed`, `blockers`. Optional: `verdict`.
 - **Mobile-first conflict**: Design mockup is desktop-only with no mobile spec. → Implement mobile-first with reasonable defaults (single column, stacked filters), flag the desktop-only spec in Notes for design clarification.
 - **Animation request**: Task asks for "smooth transitions" without specifics. → Use the project's existing motion tokens (typically `transition: 200ms ease`) and flag for design review if heavier animation is needed.
 - **JS-disabled fallback**: Server-rendered page must work without JS. → Confirm with the wave plan; if unspecified, use progressive enhancement (form posts work, JS adds client-side validation on top).
+
+## Examples
+
+<example>Context: Implementation wave includes UI component work. user: "Build the invoice list page with filters and pagination" assistant: "I'll dispatch the ui-developer agent to implement the invoice list UI." <commentary>Frontend page implementation with interactive components is the ui-developer's specialty.</commentary></example>
+
+<example>Context: Accessibility improvements needed. user: "Fix WCAG violations in the dashboard components" assistant: "I'll use the ui-developer to audit and fix the accessibility issues." <commentary>WCAG compliance requires understanding semantic HTML, ARIA attributes, and keyboard navigation.</commentary></example>

package/agents/ux-evaluator.md

@@ -1,7 +1,8 @@
 ---
 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>'
+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.'
 model: opus
+effort: medium
 color: blue
 tools: Read, Grep, Glob, Bash
 sandbox-tier: read-only
@@ -159,3 +160,7 @@ After the human-readable stdout summary, append a fenced ```json block matching
 ```
 
 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.
+
+## Examples
+
+<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>

package/commands/session.md

@@ -17,7 +17,7 @@ You are beginning a new development session. The complete text following `/sessi
 
 **Explicit execution requests:** Ordinary housekeeping uses the coordinator-direct maintenance shape returned by `scripts/session-shape.mjs`. If the user explicitly requests parallel subagents or waves in the context, carry that request into the session plan as an override for this run, following [User-authorized housekeeping execution deviation](../skills/session-plan/SKILL.md#user-authorized-housekeeping-execution-deviation). Retain `session-type: housekeeping`, keep the resolver's default shape distinct from the actual plan, and preserve global Session Config and the user's model settings. The planning and execution skills apply this exception before their housekeeping shortcuts; the request does not implicitly authorize unrelated external actions.
 
-### Argument alias: `ultradeep` (PRD `docs/prd/2026-09-06-ultradeep-session-profile.md`)
+### Argument alias: `ultradeep` (spec: internal session-profile PRD, 2026-09-06)
 
 `/session ultradeep` is an alias, NOT a fourth `session_type`. Resolve it to TWO STATE.md frontmatter values and then continue exactly as a `deep` session would:
 

package/commands/templates-ack.md

@@ -5,7 +5,7 @@ argument-hint: "[optional-reason]"
 
 # Templates Acknowledgement
 
-Write a session-scoped acknowledgement entry to `.orchestrator/runtime/templates-acknowledged.json`. Once written, the `pre-bash-templates-first` hook (G6) will allow `gh`/`glab` create operations for the rest of the current session without requiring a prior template Read.
+Write a session-scoped acknowledgement entry to `.orchestrator/runtime/templates-acknowledged.json` (inside a linked git worktree: the main checkout's `.orchestrator/runtime/`, where the hook reads it). Once written, the `pre-bash-templates-first` hook (G6) will allow `gh`/`glab` create operations for the rest of the current session without requiring a prior template Read.
 
 **Use this only when:**
 - You have already reviewed the relevant template externally (e.g. copy-paste workflow), OR
@@ -15,28 +15,76 @@ Write a session-scoped acknowledgement entry to `.orchestrator/runtime/templates
 
 Run the following node snippet to write the acknowledgement:
 
+The acknowledgement requires proof from the nearest ancestor whose process name
+(basename of `comm`) is `claude`: its `~/.claude/sessions/<pid>.json` must supply a valid `sessionId`.
+Only parent PID and process name are measured, with at most 64 processes and no
+cycles. Nonempty native environment IDs must agree with that invocation.
+Missing process/session evidence refuses the acknowledgement, including on
+harnesses without a Claude ancestor. Shared
+`.orchestrator/current-session.json` state is never used as identity. This guards against accidental acknowledgement
+for a parent session from a nested harness; it is not a security boundary against
+a hostile child (which could write the file directly). A Claude started as a
+plain `node` script has no `claude` ancestor and is refused. Run this
+from the target project with the harness's plugin-root environment set (or from
+the session-orchestrator repository itself).
+The hook accepts this acknowledgement only when its invocation supplies a valid,
+unambiguous `session_id` or `sessionId`; inherited environment IDs cannot grant
+an acknowledgement bypass when that invocation ID is missing.
+
 ```bash
 node --input-type=module -e "
-import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
 
 const cwd = process.cwd();
-const sessionFile = join(cwd, '.orchestrator', 'current-session.json');
-const ackFile = join(cwd, '.orchestrator', 'runtime', 'templates-acknowledged.json');
 const reason = process.argv[1] ?? '';
 const userId = process.env.USER ?? process.env.USERNAME ?? '';
 
-// Resolve session_id
-let sessionId = null;
-if (existsSync(sessionFile)) {
+// Bootstrap from the same root precedence as the plugin resolver. The cwd
+// fallback is restricted to the plugin repository, never an arbitrary project.
+const roots = [
+  ['claude', 'CLAUDE_PLUGIN_ROOT'], ['codex', 'CODEX_PLUGIN_ROOT'],
+  ['cursor', 'CURSOR_RULES_DIR'], ['pi', 'PI_PLUGIN_ROOT'],
+];
+const platform = (process.env.SO_PLATFORM ?? '').trim();
+const ordered = [...roots.filter(([p]) => p === platform), ...roots.filter(([p]) => p !== platform)];
+let pluginRoot = null;
+for (const name of ['PLUGIN_ROOT', ...ordered.map(([, name]) => name)]) {
+  const candidate = (process.env[name] ?? '').trim();
+  if (!candidate) continue;
+  try { if (statSync(candidate).isDirectory()) { pluginRoot = candidate; break; } } catch { /* try next root */ }
+}
+if (!pluginRoot) {
   try {
-    const raw = JSON.parse(readFileSync(sessionFile, 'utf8'));
-    sessionId = raw.session_id ?? raw.sessionId ?? null;
-  } catch { /* ignore */ }
+    if (JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')).name === 'session-orchestrator') pluginRoot = cwd;
+  } catch { /* no plugin-root evidence */ }
+}
+if (!pluginRoot) {
+  process.stderr.write('⚠ templates-ack: plugin root unavailable — ack not written\n');
+  process.exit(1);
+}
+// The ack file is runtime state: in a linked worktree it lives in the MAIN
+// checkout, the same root the pre-bash-templates-first hook reads (#1729).
+let ackFile = null;
+try {
+  const { resolveEventsLedgerRoot } = await import(pathToFileURL(join(pluginRoot, 'scripts/lib/platform.mjs')).href);
+  ackFile = join(resolveEventsLedgerRoot(cwd), '.orchestrator', 'runtime', 'templates-acknowledged.json');
+} catch {
+  process.stderr.write('⚠ templates-ack: root resolver unavailable — ack not written\n');
+  process.exit(1);
+}
+let sessionId = null;
+try {
+  const { readInvocationSessionId } = await import(pathToFileURL(join(pluginRoot, 'scripts/lib/session-identity/own-session.mjs')).href);
+  sessionId = readInvocationSessionId();
+} catch {
+  process.stderr.write('⚠ templates-ack: process-local identity helper unavailable — ack not written\n');
+  process.exit(1);
 }
 if (!sessionId) {
-  process.stderr.write('⚠ templates-ack: could not read session_id from .orchestrator/current-session.json — ack not written\n');
+  process.stderr.write('⚠ templates-ack: session id does not come from this invocation — ack not written\n');
   process.exit(1);
 }
 
@@ -67,15 +115,38 @@ if (reason) process.stdout.write('  Reason: ' + reason + '\n');
 
 ## Verification
 
-After writing, confirm the entry exists:
+After writing, confirm the entry exists. The check resolves the same root as
+the writer (main checkout for a linked worktree); the `Written:` line above
+names the same file.
 
 ```bash
-node -e "
-const f = require('fs');
-const p = '.orchestrator/runtime/templates-acknowledged.json';
-if (!f.existsSync(p)) { console.log('NOT FOUND'); process.exit(1); }
-const d = JSON.parse(f.readFileSync(p, 'utf8'));
-console.log(JSON.stringify(d, null, 2));
+node --input-type=module -e "
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const cwd = process.cwd();
+// Same plugin-root lookup as the writer: an env root first, the cwd only
+// when it IS the plugin repository, never an arbitrary project.
+let pluginRoot = null;
+for (const name of ['PLUGIN_ROOT', 'CLAUDE_PLUGIN_ROOT', 'CODEX_PLUGIN_ROOT', 'CURSOR_RULES_DIR', 'PI_PLUGIN_ROOT']) {
+  const candidate = (process.env[name] ?? '').trim();
+  if (!candidate) continue;
+  try { if (statSync(candidate).isDirectory()) { pluginRoot = candidate; break; } } catch { /* try next root */ }
+}
+if (!pluginRoot) {
+  try {
+    if (JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')).name === 'session-orchestrator') pluginRoot = cwd;
+  } catch { /* no plugin-root evidence */ }
+}
+if (!pluginRoot) { console.log('plugin root unavailable'); process.exit(1); }
+let root;
+try {
+  const { resolveEventsLedgerRoot } = await import(pathToFileURL(join(pluginRoot, 'scripts/lib/platform.mjs')).href);
+  root = resolveEventsLedgerRoot(cwd);
+} catch { console.log('root resolver unavailable'); process.exit(1); }
+const p = join(root, '.orchestrator', 'runtime', 'templates-acknowledged.json');
+if (!existsSync(p)) { console.log('NOT FOUND: ' + p); process.exit(1); }
+console.log(JSON.stringify(JSON.parse(readFileSync(p, 'utf8')), null, 2));
 "
 ```
 

package/docs/agent-authoring.md

@@ -48,8 +48,9 @@ Agent files live in `agents/` as Markdown with YAML frontmatter. Required fields
 ```yaml
 ---
 name: kebab-case-name                # 3-50 chars, lowercase + hyphens only
-description: Use this agent when [conditions]. <example>Context: ... user: "..." assistant: "..." <commentary>Why this agent is appropriate</commentary></example>
-model: inherit                        # inherit | sonnet | opus | haiku | fable — OR full ID like claude-opus-5-5, claude-sonnet-4-6, claude-haiku-4-5-20251001, claude-sonnet-5, claude-fable-5
+description: Use this agent when [conditions].   # single-line routing sentence; <example> blocks go in the body § Examples
+model: opus                           # inherit | sonnet | opus | haiku | fable — OR full ID like claude-opus-5-5, claude-sonnet-4-6, claude-haiku-4-5-20251001, claude-sonnet-5, claude-fable-5
+effort: medium                        # low | medium | high | xhigh | max — REQUIRED whenever model is not inherit (#1614)
 color: blue                           # blue | cyan | green | yellow | purple | orange | pink | red | magenta
 tools: Read, Grep, Glob, Bash         # comma-separated string OR JSON array (both accepted; we prefer comma-string for consistency)
 ---
@@ -59,8 +60,9 @@ tools: Read, Grep, Glob, Bash         # comma-separated string OR JSON array (bo
 
 **Required vs optional:**
 - Runtime canonical doc: only `name` + `description` are required.
-- Our validator (defensive for plugin-distribution): all four of `name + description + model + color` required; `tools` optional.
-- `description` MUST be a single-line inline string, NOT a YAML block scalar (`>` or `|`). Put `<example>` blocks inline.
+- Our validator (defensive for plugin-distribution): all four of `name + description + model + color` required; `effort` required as soon as `model` is not `inherit`; `tools` optional.
+- `omitClaudeMd: true|false` (optional, #1616) drops CLAUDE.md from the agent's start context. Set only on narrow judges that read nothing but the records they are handed (`eval-judge`, `skill-applied-judge`, `dialectic-deriver`); reviewers and implementers keep it because they check against the rules.
+- `description` MUST be a single-line inline string, NOT a YAML block scalar (`>` or `|`). It carries only the routing sentence(s) — the text the dispatcher matches on. `<example>…</example>` blocks (with `<commentary>`) do NOT go inline in the description: they live in a `## Examples` section at the end of the body, one block per paragraph (#887, #1157).
 - `tools` accepts BOTH comma-separated string (`Read, Edit, Write`) and JSON array (`["Read", "Edit", "Write"]`). Anthropic's own reference agents use array form; we use string form for consistency.
 
 **Body conventions** (from Anthropic's `plugins/plugin-dev/agents/*` reference set):
@@ -68,15 +70,25 @@ tools: Read, Grep, Glob, Bash         # comma-separated string OR JSON array (bo
 - Length: 500–3000 words is the recommended range. Below 500 reads as under-specified; above 3000 reads as bloated.
 - Read-only reviewer agents: tools `Read, Grep, Glob, Bash` (no Edit/Write). Implementer agents: `Read, Edit, Write, Glob, Grep, Bash`. Agents on the escalation allowlist append `SendMessage` to either baseline — see § Escalation Channel (#1051) for the six that do and why the rest do not.
 
-## Model Selection & Cost Routing (#768)
+## Model Selection & Cost Routing (#768, #1614)
 
-`model:` is not just a compatibility field — it is a cost/quality dial per agent. Pick deliberately, don't default to `sonnet` everywhere.
+Every agent pins `model:` AND `effort:` explicitly. `inherit` was the default until 2026-10-14 and cost the catalog its users: under a Fable lead, an inheriting agent ran on the most expensive model at the session's effort, and the fleet moved to private opus/medium agents (census in #1614: plugin share of dispatches fell from 61 % in the week of 15 September to 6 % in the week of 8 October).
 
-- **`haiku`** — cheap, fast, advisory/judge roles where the task is narrow classification or a single yes/no verdict, not open-ended reasoning. Precedent: `dialectic-deriver`, `skill-applied-judge`. Pin `haiku` when the agent's whole job is "read a short input, emit a structured verdict."
-- **`sonnet`** — an explicit cost cap, NOT a default. Pin it only when an agent must stay on the workhorse tier even in an Opus session, and state the reason inline. A bare `sonnet` on a working agent silently overrides the operator's session model — the failure mode that moved the implementation and review catalog to `inherit`.
-- **`inherit`** — **the default for the working catalog.** Lets the coordinator/session's active model tier flow through, so the agent runs at whatever tier the operator picked (an Opus session gives its implementers AND its reviewers Opus-quality judgment). Use it for implementation, test-writing, and review agents alike — `code-implementer`, `test-writer`, `security-reviewer`, `session-reviewer`, `db-specialist`, `ui-developer`, and the read-only analysis agents. Diverge only for a named cost/quality reason.
-- **`opus`** — reserve for agents whose task genuinely needs the strongest available reasoning (e.g. `ux-evaluator`) and where the cost is justified because the agent runs rarely (dispatched solo, not fanned out across a wave).
-- **Full model-ID pinning** (`claude-opus-5-5`, `claude-sonnet-5`, `claude-fable-5-20260101`, …) — only when the agent has a demonstrated dependency on a SPECIFIC model version, e.g. a reproducibility requirement that needs a dated snapshot, or a known behavioral regression on newer models for this agent's exact prompt. Pinning trades away automatic model-family upgrades — document the reason inline as a frontmatter comment when you do this.
+| Role | model | effort | Agents |
+|---|---|---|---|
+| Implementation and review | `opus` | `medium` | `code-implementer`, `db-specialist`, `ui-developer`, `session-reviewer`, `security-reviewer`, `architect-reviewer` |
+| Tests, docs, analysis | `sonnet` | `medium` | `test-writer`, `docs-writer`, `qa-strategist`, `analyst` |
+| Narrow judges | `haiku` | `medium` | `eval-judge`, `skill-applied-judge`, `dialectic-deriver` |
+| Rare solo evaluator | `opus` | `medium` | `ux-evaluator` (judges screenshots and AX trees against a rubric, dispatched alone, not fanned out) |
+
+- **`effort` is required whenever `model` is not `inherit`** (validated by `checkAgentEffort` in `scripts/lib/agent-frontmatter.mjs`). The per-model default differs: Sonnet 5.5 defaults to `high`, Opus 5.5 to `medium`, so a Sonnet agent without `effort` thinks longer than an Opus one. `medium` follows the owner's standing instruction (2026-09-30); raise it only for a named reason in the agent.
+- **`haiku`** — narrow classification or a single structured verdict over a short input. Whether read-only analysis roles move to Haiku is an open owner decision (#1614); do not switch them until it is made.
+- **`sonnet`** — work that needs judgment but not the strongest reasoning: test gaps, docs, PRD and coverage analysis.
+- **`opus`** — code changes and reviews, where a missed defect costs more than the tokens.
+- **`inherit`** — only with a reason written into the agent (e.g. the agent must follow whatever model the operator chose). It also inherits the session's effort.
+- **Full model-ID pinning** (`claude-opus-5-5`, `claude-sonnet-5`, `claude-fable-5-20260101`, …) — only for a demonstrated dependency on one model version (a reproducibility snapshot, a known regression on newer models). Document the reason inline as a frontmatter comment.
+
+Whether `effort` from a **plugin** agent's frontmatter takes effect is not stated in the upstream docs; the #1614 acceptance smoke checks it per role. If it does not, the dispatcher passes `effort` as a dispatch parameter (Claude Code v2.1.292+).
 
 **Resolution order** (highest precedence first): `CLAUDE_CODE_SUBAGENT_MODEL` environment variable → the invocation-time model parameter (if the dispatcher passes one explicitly) → the agent's own frontmatter `model:` value. An agent's `model:` is therefore a default, not a guarantee — a session or environment override can supersede it.
 
@@ -90,6 +102,13 @@ Every agent definition with `repo-write` sandbox-tier (i.e. `Edit`/`Write` prese
 
 This is deliberately more explicit than a bare "Do NOT commit" — the git index and stash are SHARED resources across concurrently-dispatched sibling agents in the same wave, and `git stash`/`git add`/`git mv`/`git rm` are index-mutating even when scoped to the agent's own files. `docs-writer.md` had NO git-write restriction at all until #724 closed the gap (its `repo-write` siblings at least carried a bare "Do NOT commit" line) — when adding a new repo-write agent, copy the ban line verbatim rather than re-deriving a weaker phrasing so this gap does not recur. See `.claude/rules/parallel-sessions.md` § PSA-007 for the full rationale and fleet evidence.
 
+**Sole exception — worktree mode (#1614).** Only `code-implementer` may stage its own files one by one and commit, and only when its prompt carries a line `WORKTREE-MODE: <absolute path> <branch>` that matches `git rev-parse --show-toplevel` and `git branch --show-current`; otherwise the ban applies unchanged. Coordinator duty: never grant the coordinator's own worktree, never put two agents in one worktree. The wave-executor never sets the line. A linked worktree has its own index, so the index race this ban prevents does not exist there. The commit hook briefly adds an entry to the shared stash via lint-staged; the agent itself never runs `git stash`. Push, merge, `git reset`, `git stash` and `git clean` stay banned. The exception lives in the agent's own Rules section, next to the unchanged ban line, so Check 10 still finds the ban. The detector `psa007-git-write` (`scripts/lib/wave-transcript-tail.mjs`) still reports every commit inside a wave; that is correct, because wave prompts never carry `WORKTREE-MODE`.
+
+## Waiting, Forks and Start Cost (#1615, #1616)
+
+- **Waiting longer than 5 minutes does not belong in a subagent.** A subagent's prompt cache lives 5 minutes, so every longer wait (pipeline, remote run, rerun) rebuilds its whole context on the next turn (#1615 measured 250 M rewritten tokens in 14 days). The agent reports its intermediate state and ends; the coordinator waits with Monitor and then continues it with `SendMessage` (or dispatches a fresh one).
+- **Fork or subagent.** A short task that needs the current conversation goes to a fork: it inherits system prompt, tools and history and reads the parent session's cache, so it does not pay the 60–80k token start context again. A task with its own file scope, worktree or model goes to a subagent. The wave-executor stays on subagents, because it needs scope boundaries.
+
 ## Escalation Channel (#1051)
 
 Six agents opt into `SendMessage` so a wave-blocking obstacle can reach the coordinator **while the wave is still running**, instead of surfacing only in the final report after the wave has ended. The allowlist is exactly:

package/docs/ci-setup.md

@@ -2,6 +2,8 @@
 
 > **Maintainer-internal.** This document describes the maintainer's private CI mirror setup. It is not required for using the plugin.
 
+GitHub's Linux/macOS test matrix is supplemented by two non-blocking Windows jobs on `windows-latest` (#1612): `test-windows-smoke` runs lint, typecheck and `scripts/ci/windows-smoke.mjs` (the product contract for Claude Code on Windows; it moves into `gate` after 10 green main runs), and `test-windows-suite` runs the full suite for information while the test-portability backlog is open. The fresh SessionStart smoke needs npm-registry access and reports unavailable network as unmeasurable.
+
 ## schema-drift-check job
 
 The `schema-drift-check` job compares the vendored `vault-frontmatter` schema
@@ -633,8 +635,42 @@ The router tries eligible aliases in configuration order, checking each with
 `offload doctor -H <alias> --brief --no-probe`. The alias selects a gate execution
 host; it is independent of the Git remote being pushed to. With no eligible
 host, no `offload` executable, or unavailable remote readiness/transport, the
-hook runs the same local full gate. A classified transport failure can first
-try the next configured host.
+hook falls back locally. A classified transport failure can first try the next
+configured host.
+
+The local fallback depends on the push target (#1642):
+
+- **A branch other than `main` on `origin`** (by remote name or its exact push
+  URL) takes the local **partial** gate, `scripts/lib/pre-push-local-partial.mjs`.
+  It computes the files changed since the merge-base with origin's default
+  branch and runs `node --check` and ESLint on the changed source files, plus
+  `vitest related --run` for all changed files. A red check blocks the push. The
+  full suite then runs in the MR pipeline on the pushed head SHA.
+- **Everything else** (any push that includes `main` or a tag — every pushed ref counts, not only the first — the GitHub mirror, a push
+  by URL to another host, a hand invocation without a remote) runs the full
+  gate locally. No MR pipeline stands between those pushes and their result.
+- The partial gate exits 10 and hands over to the full local gate when there is
+  no merge-base, when a source file was deleted or renamed, when `package.json`, `package-lock.json`, `vitest.config.*` or
+  `eslint.config.*` changed, or when `eslint`/`vitest` is missing from
+  `node_modules` (fail-closed). Its ledger event is
+  `orchestrator.quality_gate.{passed,failed}` with `variant: 'local-partial'`.
+- Ceiling: `vitest related` follows the import graph. A test that reaches a
+  changed file only by spawning it (hooks, `.husky/`, CLIs) or by reading it
+  from disk (policy JSON, Markdown, fixtures; edited or deleted) is not
+  selected locally, and the MR pipeline catches that class. Only a deleted or
+  renamed source file (`.mjs`/`.cjs`/`.js`) falls back to the full gate (#1643).
+
+`SO_GATE_HOSTS` overrides the host order for one push without a config commit:
+`SO_GATE_HOSTS=hostA,hostB git push` tries exactly those aliases, in that order,
+instead of the configured `remote-hosts` list (whitespace-only counts as unset).
+Every alias must have a regular file `<alias>.env` in offload's host registry
+(`${OFFLOAD_CONFIG_DIR:-$HOME/.config/remote-offload}/hosts/`, the same rule
+`offload -H` uses) and match `^[A-Za-z0-9._-]+$`. An unknown or invalid alias,
+or an override none of whose hosts can run the gate (not ready, transport
+failure, no `offload`), blocks the push with exit 2 and does **not** fall back
+to the local gate. The router logs the chosen host and its source (`config`,
+`override`, or `fallback` to local) on stderr, and the remote gate's ledger
+event carries `host` and `host_source`.
 
 On the remote checkout, the command checks out the pushed SHA again, verifies
 `HEAD` and a clean source tree, and runs `npm run --silent quality-gate`.

package/docs/codex-setup.md

@@ -11,7 +11,7 @@ Guide for using Session Orchestrator with OpenAI Codex through Codex's public pl
 
 ## Installation
 
-**Recommended:** the short remote form (`codex plugin marketplace add <owner>/<repo>`) needs no local clone — see "Short-Form Marketplace Add" below. The steps below are the maintainer/local-clone path used by `scripts/codex-install.mjs`.
+Two paths. The clone below is the complete install: it puts the runtime dependencies next to the plugin. The short remote form (`codex plugin marketplace add <owner>/<repo>`) needs no clone and takes two commands, but the installed plugin has no `node_modules`, so part of the plugin falls back or stops until you run `npm install` there — see "Short-Form Marketplace Add" below.
 
 Clone the repository, install its runtime dependencies, and run the installer from the plugin root:
 
@@ -34,7 +34,7 @@ A marketplace on the working checkout copies all of it into the Codex plugin cac
 
 It operates only through public Codex plugin commands; hook trust remains untouched.
 
-### Short-Form Marketplace Add (Recommended — Verified 2026-09-04, codex-cli 0.144.4)
+### Short-Form Marketplace Add (Verified 2026-09-04, codex-cli 0.144.4; dependencies measured 2026-10-21, codex-cli 0.160.1)
 
 `codex plugin marketplace add --help` documents a short remote form:
 
@@ -42,7 +42,7 @@ It operates only through public Codex plugin commands; hook trust remains untouc
 codex plugin marketplace add owner/repo --ref main
 ```
 
-This is the recommended install path — no local clone needed. Confirmed end-to-end on codex-cli **0.144.4** (2026-09-04), against this repo's unchanged flat layout (`.codex-plugin/plugin.json` + `.claude-plugin/marketplace.json` at repo root, no `plugins/<name>/`):
+This is the shortest install path — no local clone needed. Confirmed end-to-end on codex-cli **0.144.4** (2026-09-04), against this repo's unchanged flat layout (`.codex-plugin/plugin.json` + `.claude-plugin/marketplace.json` at repo root, no `plugins/<name>/`):
 
 ```
 $ codex plugin add session-orchestrator@kanevry --json
@@ -53,6 +53,13 @@ $ echo $?
 
 `codex plugin list --available --json --marketplace kanevry` confirms `installed: true, enabled: true` for the same layout — no `plugins/<name>/` restructuring was needed.
 
+**No runtime dependencies on this path (measured 2026-10-21, codex-cli 0.160.1, isolated `CODEX_HOME`).** `marketplace add` and `plugin add` both exit 0, but the installed path (`~/.codex/plugins/cache/kanevry/session-orchestrator/<version>`) has no `node_modules`. The SessionStart hook, the Bash guards and `scripts/parse-config.mjs` still run (the destructive-command guard's `git stash` check falls back to a warning, because it needs `zx`). Everything else that needs a runtime dependency (`zx`, `zod`, `js-yaml`, `ajv`, `remark`, …) either falls back or stops:
+
+- `owner.yaml` loads `js-yaml` lazily: when the file exists, owner preferences fall back to defaults and the process prints `WARN owner-yaml: 'js-yaml' is not installed … Run 'npm install' in the plugin directory`.
+- Scripts that import a dependency at the top stop with `ERR_MODULE_NOT_FOUND` and no warning: the worktree helpers (`zx`), the learnings index (`zod`), the persona panel and the PRD archive (`js-yaml`), among others (18 files import `js-yaml` that way).
+
+To restore them, run `npm install --omit=dev --ignore-scripts` in the `installedPath` that `codex plugin add --json` prints, and again after every update, because each version gets a new cache directory. The clone path above avoids this.
+
 **Historical note:** on codex-cli 0.141.0 (2026-08-28), the identical `plugin add` command failed against this same layout with `Error: plugin session-orchestrator was not found in marketplace kanevry`; upgrading to 0.144.4+ resolves it.
 
 ### Switching Marketplace Sources
@@ -160,9 +167,10 @@ $ strings -a "$(npm root -g)/@openai/codex/node_modules/@openai/codex-darwin-arm
 | Event | 0.144.4 | Wired here |
 |---|---|---|
 | `SessionStart` | yes | yes — banner + `on-session-start.mjs` |
-| `PostToolUse` | yes | yes — `loop-guard.mjs` |
+| `PostToolUse` | yes | yes — `loop-guard.mjs`; `Bash`: `post-bash-write-verify.mjs` (warn-only, #1691) |
 | `SubagentStop`, `Stop` | yes | yes — `on-stop.mjs` |
-| `PreToolUse`, `SubagentStart` | yes | declared, **empty** (see below) |
+| `PreToolUse` | yes | yes — `Bash`: destructive guard, staging fence, memory-propose audit, sessions-ledger guard, issue budget, `enforce-commands.mjs` (#1691); `pre-bash-templates-first.mjs` and the Edit/Write guards stay unwired (see below) |
+| `SubagentStart` | yes | declared, **empty** |
 | `UserPromptSubmit`, `PermissionRequest`, `PreCompact`, `PostCompact` | yes | no — this repo has no handler for them |
 | `SessionEnd`, `Interrupt` | **no — event does not exist** | n/a |
 | `PostToolUseFailure`, `PostToolBatch`, `CwdChanged` | no — Claude-only | n/a |
@@ -171,26 +179,42 @@ $ strings -a "$(npm root -g)/@openai/codex/node_modules/@openai/codex-darwin-arm
 
 For the day `SessionEnd` does land: upstream caps it (and `Interrupt`) at a **1 s default / 3 s maximum** timeout, where every other event gets 600 s. `hooks/on-session-end.mjs` measures ~221 ms median, so it fits — but only just, and only while it stays that fast.
 
-### Why our PreToolUse guards stay unwired — the reason, corrected
+### Which PreToolUse guards run on Codex — the reason, corrected
 
 Earlier revisions of this page said the handlers were unwired because "no Codex bridge delivers `tool_name`". **That was measuring the wrong thing** — it grepped our own adapter code rather than the Codex payload contract. There is no bridge because none is needed:
 
 - `pre-tool-use.command.input` REQUIRES `tool_name` and `tool_input`, alongside `cwd`, `hook_event_name`, `model`, `permission_mode`, `session_id`, `tool_use_id`, `transcript_path`, `turn_id`.
 - The deny envelope is `hookSpecificOutput.{hookEventName, permissionDecision, permissionDecisionReason}` — byte-identical to what `emitDeny()` already writes, and Codex enforces exactly that shape (its own error text: *"PreToolUse hook returned permissionDecision:deny without a non-empty permissionDecisionReason"*). Codex additionally rejects `permissionDecision: "allow"` and `"ask"`; our allow path is a bare `exit 0` with no stdout, so it is compatible.
 
-The real blocker is the **tool-name vocabulary**. Codex has no `Bash`, `Edit`, `Write` or `MultiEdit` tool — `strings -a <codex> | grep -c '"Bash"'` returns `0`; its tools are `shell`, `exec_command`, `unified_exec`, `apply_patch`, `update_plan`, `view_image`. Every PreToolUse guard in `hooks/` opens with an equality gate on a Claude tool name and returns `emitAllow()` otherwise, so wiring `pre-bash-destructive-guard.mjs` or `enforce-scope.mjs` today produces a hook that runs, matches nothing, and allows everything — **false enforcement, which is worse than a registered gap** (#919-P2 class).
+Until 2026-10-20 this page named the **tool-name vocabulary** as the real blocker: Codex's model-facing tools are `shell`, `exec_command`, `unified_exec`, `apply_patch`, `update_plan`, `view_image`, and `strings -a <codex> | grep -c '"Bash"'` returned `0` (codex-cli 0.144.4). **For the shell tool that is refuted** (#1669, measured 2026-10-20 on codex-cli 0.160.1 with a logging PreToolUse hook under `codex exec`): a shell call reaches the hook as `"tool_name":"Bash"` with `"tool_input":{"command":"<string>"}`, and `matcher: "Bash"` fires. Codex maps its shell tool to the Claude name at the hook boundary, so the Bash guards need no tool-name map. The allow-only `pre-bash-staging-fence.mjs` is wired on that basis. For the Edit/Write matchers (`apply_patch`) the vocabulary question is still unmeasured.
+
+**Codex honours a deny** (#1691, measured 2026-10-20 on codex-cli 0.160.1). `codex exec` with `pre-bash-destructive-guard.mjs` as the only PreToolUse hook and the prompt `printf x > CLAUDE.md` logged `Command blocked by PreToolUse hook: Destructive command blocked: '> CLAUDE.md' (rule: redirect-truncate-protected)`, and `CLAUDE.md` stayed unchanged. The control run with `hooks.PreToolUse=[]` ran the command and the file became `x`. The measured payload carries `session_id`, `turn_id`, `cwd` (the session workdir, which is also the hook's process cwd), `tool_name: "Bash"`, `tool_input.command` and `transcript_path: null`; PostToolUse adds `tool_response: ""`. A real Codex session exports no `CLAUDE_*` variables.
+
+Each Bash hook was then fed that payload and wired only where it enforces on it:
+
+| Hook | On Codex | Why |
+|---|---|---|
+| `pre-bash-destructive-guard.mjs` | wired | denies `> CLAUDE.md` |
+| `pre-bash-sessions-ledger-guard.mjs` | wired | denies a direct write to `.orchestrator/metrics/sessions.jsonl` |
+| `pre-bash-issue-budget.mjs` | wired | with a cap of 1 the second `glab issue create` is denied and parked |
+| `enforce-commands.mjs` | wired | applies `blockedCommands` from `.codex/wave-scope.json` |
+| `pre-bash-memory-propose-audit.mjs` | wired | appends its audit event (observe-only by design) |
+| `post-bash-write-verify.mjs` (PostToolUse) | wired | reports a write outside `allowedPaths` (warn-only by design) |
+| `pre-bash-templates-first.mjs` | **not wired** | it can only deny there: the template-Read proof needs `transcript_path`, which Codex sends as `null`, and `/templates-ack` needs a `claude` parent process |
+| `post-bash-issue-budget-refund.mjs` | n/a | runs on `PostToolUseFailure`, which Codex does not have; a failed create keeps its budget slot |
 
-Consequence to state plainly: **PSA-003 (destructive-command guard) and the file-scope guard are behavioural only on Codex today.** The repair is a tool-name map (`shell`/`exec_command`/`unified_exec` → `Bash`) for the Bash guards, plus an `apply_patch` payload adapter for the Edit/Write matchers specifically. Only the second half needs the adapter.
+What this still leaves open: **the file-scope guard is behavioural only on Codex today**, because the Edit/Write guards need an `apply_patch` payload adapter. `tests/hooks/codex-bash-guards-wiring.test.mjs` runs every registered Bash command on the measured payload.
 
 These per-event gaps are tracked as documented asymmetries in `scripts/lib/validate/check-hooks-symmetry.mjs` (Check 6, `handlerAsymmetries`) — an UNDOCUMENTED one-platform-only handler fails validation.
 
-An empty `PreToolUse` or `SubagentStart` array means the event belongs to the validated Codex surface but currently has no payload-compatible handler. It does not mean installation or hook trust failed.
+An empty `SubagentStart` array means the event belongs to the validated Codex surface but currently has no payload-compatible handler. It does not mean installation or hook trust failed.
 
 ## Usage
 
 After installation or refresh, start a fresh task. In the desktop composer, open the skill picker, search for `go` or `close`, and select the matching **Session Orchestrator** entry. In Codex CLI or the IDE extension, use `/skills` or mention the namespaced skill directly in your prompt. [OpenAI skill invocation](https://learn.chatgpt.com/docs/build-skills)
 
 ```text
+$session-orchestrator:bootstrap         # once per repository, before the first session
 $session-orchestrator:session           # start with the deep default
 $session-orchestrator:session housekeeping  # maintenance session
 $session-orchestrator:session deep      # explicit deep session

package/docs/components.md

@@ -57,7 +57,7 @@ Codex uses the curated six-event project subset `SessionStart`, `PreToolUse`, `P
 
 - **Output Styles (3):** `session-report`, `wave-summary`, `finding-report`.
 - **Policy & rules:** `.orchestrator/policy/blocked-commands.json` (destructive-command rules); `.claude/rules/parallel-sessions.md` (PSA-001..PSA-004).
-- **Destructive-command guard.** On Claude Code, the active `hooks/pre-bash-destructive-guard.mjs` applies `.orchestrator/policy/blocked-commands.json` in the main session and in subagent waves. The policy has 12 blocking rules (`git reset --hard`, `rm -rf`, `git push --force`, deletion of `.orchestrator/metrics/**`, and more) and 4 warning rules. Cursor and Pi use event bridges with documented limits; Codex does not enforce this guard. Scope `enforcement: warn` or `off` does not change the separate destructive-command policy — see [Platform support](../README.md#platform-support). Where the hook is active, bypass it per session only for intentional maintenance by setting `allow-destructive-ops: true` in Session Config. The rule source of truth is [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) (PSA-003), vendored to consumer repos via `/bootstrap`.
+- **Destructive-command guard.** On Claude Code, the active `hooks/pre-bash-destructive-guard.mjs` applies `.orchestrator/policy/blocked-commands.json` in the main session and in subagent waves. The policy has 13 blocking rules (`git reset --hard`, `rm -rf`, `git push --force`, deletion of `.orchestrator/metrics/**`, and more) and 4 warning rules. Cursor and Pi use event bridges with documented limits; On Codex the same hook runs as a `PreToolUse` Bash hook, and Codex honours its deny (measured 2026-10-20, codex-cli 0.160.1, #1691). Scope `enforcement: warn` or `off` does not change the separate destructive-command policy — see [Platform support](../README.md#platform-support). Where the hook is active, bypass it per session only for intentional maintenance by setting `allow-destructive-ops: true` in Session Config. The rule source of truth is [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) (PSA-003), vendored to consumer repos via `/bootstrap`.
 - **Import probe.** `hooks/post-edit-import-probe.mjs` (PostToolUse on `Edit`/`Write`/`MultiEdit`) guards the other direction: a hook-reachable helper saved in a broken intermediate state makes *every* Bash/Edit/Write call fail with an internal hook error, host-wide, for every session sharing the working copy. Right after such a file is saved the probe runs ESLint `no-undef` on it (plus a child-process `import()` for `scripts/lib/**`) and reports the blast radius; it never blocks and always exits 0. It only fires for files listed in the committed allowlist [`hooks/_lib/hook-import-set.json`](../hooks/_lib/hook-import-set.json), regenerated by `node scripts/generate-hook-import-set.mjs`. Kill switch: `SO_DISABLED_HOOKS=post-edit-import-probe`.
 - **Process-group kill + orphan reaper.** Both quality-gate paths spawn their commands `detached: true`, so the whole process GROUP is killed on timeout (SIGTERM → grace → SIGKILL, exit 124) instead of only the shell — the shell's own children used to be reparented to PID 1 and keep running. Every gate process this repo starts is recorded in `.orchestrator/runtime/gate-processes.jsonl`; `hooks/post-tool-batch-wave-signal.mjs` and `hooks/on-stop.mjs` trigger a throttled, detached orphan scan that reaps only what that register claims. Ships inert (`reaper.enabled: false`, `reaper.mode: report`) until its firing rate is measured — rule [`.claude/rules/host-resources.md`](../.claude/rules/host-resources.md) § HR-107, rationale [ADR-0015](adr/0015-process-group-kill-and-orphan-reaper.md), audit trail `.orchestrator/metrics/reaper-audit.jsonl`.
 - **ADR-0016 Cross-session messaging.** Adopt for the live cross-session axis (CSM-001..005), Spike for Remote Control (#1056, closed negative); anchors "entries vs messages" — files hold state, messages are hints — rationale [ADR-0016](adr/0016-cross-session-messaging.md).
@@ -72,13 +72,24 @@ Codex uses the curated six-event project subset `SessionStart`, `PreToolUse`, `P
 
 `scripts/harness-audit.mjs` runs **9 deterministic categories / 38 checks** over a repo and emits `.orchestrator/metrics/audit.jsonl`. Category 8 ("Large-Codebase Readiness") operationalises Anthropic's [Claude Code large-codebase best-practices](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start) checklist — layered `CLAUDE.md` (or `AGENTS.md`), codebase-map presence, LSP/code-intelligence wiring, scoped test/lint commands, `permissions.deny`, and root-file leanness — as scored signals you can run on yourself and on consumer repos. Category 9 ("Skill-Health Surfacing") surfaces the #648 per-skill health pipeline — telemetry hygiene, scorer wiring, and an advisory-only verdict tally that never affects points; non-adoption always scores full points. These checks are intentionally orthogonal to repo-audit's baseline-compliance pass/fail; both surfaces ship.
 
+## Design choices
+
+- **The wave order is deliberate.** Discovery runs first so every implementer starts from the same picture of the code. Impl-Core runs before Impl-Polish so the structure exists before anything integrates against it. The Quality wave simplifies generated code *before* tests are written; write the tests first and they assert whatever the model produced, so changing it later means rewriting the tests too.
+- **Checks run after each implementation wave, not only at the end.** A mistake caught after wave 2 costs one wave. The same mistake found at `/close` has already been copied into every wave after it. Findings below the configured confidence threshold are not shown to you.
+- **A crash does not lose the session.** `STATE.md` records which wave finished and what deviated from the plan. The next `/session` offers to continue from the last completed wave.
+- **Two sessions in one working copy is treated as a real risk.** Two people, or two of your own sessions, in the same checkout share one git index, one filesystem and one `STATE.md`, and neither can see the other's uncommitted work. A heartbeat session lock, per-agent file-scope manifests, and the rules in [`.claude/rules/parallel-sessions.md`](../.claude/rules/parallel-sessions.md) exist for exactly that case.
+- **Guards run where the harness supports them, and the [platform table](../README.md#platform-support) says where they do not.** The destructive-command policy (13 rules block, 4 warn) runs as a real hook on Claude Code and Codex and as a bridge on Cursor and Pi; file-scope enforcement is a hook on Claude Code, a bridge on Cursor and Pi, and instructions only on Codex (see [Other surfaces](#other-surfaces)).
+- **What it learns is opt-in and readable.** Every session appends a record. After 5 or more sessions, `/evolve analyze` proposes patterns with a confidence score; you read them and delete the ones you disagree with. Nothing is applied without you.
+- **GitLab and GitHub, both fully.** It detects which one your remote points at and drives issues and merge or pull requests for either.
+- **No build step.** Skills, commands and agents are Markdown with YAML frontmatter; the code that dispatches, validates and records runs in `scripts/lib/*.mjs` and `hooks/*.mjs`. When a session does something you did not expect, you can open the file that decided it.
+
 ## Comparisons
 
 Moved here from the README so that a claim about another project can carry its measurement next to it. Every row below names when and how it was measured; rows that could not be measured were **removed rather than softened** — an unverifiable comparison row is worse than none.
 
 ### vs. `open-gsd/gsd-core`
 
-Surface counts measured 2026-09-06 by this repo's 360° ecosystem probe (`docs/audits/2026-09-06-360-audit/w1/d11-github-overlap.md`); session-orchestrator's own counts measured the same day with the commands listed in the [README](../README.md#what-you-get).
+Surface counts measured 2026-09-06 by this repo's 360° ecosystem probe (GitHub-overlap report of the 2026-09-06 360° audit; audit reports stay in the private GitLab repository and are not part of the public mirror); session-orchestrator's own counts measured the same day with the commands listed in the [README](../README.md#what-you-get).
 
 | Axis | session-orchestrator | `open-gsd/gsd-core` |
 |---|---|---|