session-orchestrator 4.1.0 → 5.0.0

package/README.md

@@ -1,23 +1,33 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-4.1.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.0.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
 [![Tests](https://img.shields.io/badge/tests-vitest-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
-Plan, run and verify coding sessions with **Claude Code, Codex CLI, Cursor IDE, or [Pi](docs/pi-setup.md)**. Session Orchestrator reads your repository and issues, proposes a plan, coordinates work in waves, and records what passed and what remains. Free, MIT-licensed, and community-maintained.
+**Give your agents a working rhythm.**
+
+Plan the work. Run it in checked waves. Pick up where you left off. Session Orchestrator is a free, MIT-licensed workflow plugin for **Claude Code, Codex CLI, Cursor IDE, or [Pi](docs/pi-setup.md)**. It reads your repository and issues, coordinates scoped work, and records what passed and what remains.
+
+[![Session Orchestrator: Plan, Go, Close, with an illustration of an agent workshop under human direction](site/og.png)](https://session-orchestrator.com)
+
+![One work item passes an automatic check; the one that fails is sent back](site/video/gate-readme.webp)
+
+[34-second film](site/video/session-orchestrator-film.mp4) · [watch it embedded on the site](https://session-orchestrator.com/#loop) · [22-second camera preview](site/video/session-orchestrator-4.3-preview.mp4) · [How the film is made](marketing/vidlab/README.md)
+
+The film shows the workflow: read first, then build in parallel lanes, check every step, send back what fails, and step in where it matters. Illustrations are generated with AI. The 22-second preview illustrates the workflow; it is not a recording of a product session.
 
 [Website](https://session-orchestrator.com) · [User guide](docs/USER-GUIDE.md) · [Platform support](#platform-support) · [Changelog](CHANGELOG.md)
 
-The same workflows are available on all four harnesses; Codex exposes commands as selectable skills. **Enforcement depth differs** — scope enforcement is full on Claude Code, bridged on Cursor and Pi, and currently unavailable on Codex CLI (see [Platform support](#platform-support)).
+The same workflows are available on all four harnesses; Codex exposes commands as selectable skills. **Guard enforcement depends on the harness.** Claude Code runs the guard hooks directly; Cursor and Pi use bridges with documented limits. On Codex, destructive-command and file-scope rules are instructions only. With an active compatible scope hook, `strict` blocks supported out-of-scope edits, `warn` reports them without denial, and `off` disables the check (see [Platform support](#platform-support)).
 
 ## Requirements
 
 | | |
 |---|---|
-| **Node.js** | **24 or later** (`node --version`) — `package.json` `engines.node` is `>=24.0.0`. The plugin is ES modules and needs a real Node runtime. [Install Node.js](https://nodejs.org/). |
+| **Node.js** | **24 or later** (`node --version`) ; `package.json` `engines.node` is `>=24.0.0`. The plugin is ES modules and needs a real Node runtime. [Install Node.js](https://nodejs.org/). |
 | **A coding agent** | Claude Code, Codex CLI, Cursor IDE, or Pi. This is a workflow layer *on top of* one of them, not a replacement. |
-| **Harness version** | Codex CLI **0.144.4 or later** ([docs/codex-setup.md](docs/codex-setup.md)). No minimum is pinned for Claude Code, Cursor, or Pi — if `/plugin` (or the Cursor/Pi installer) runs, the plugin loads. |
+| **Harness version** | Codex CLI **0.144.4 or later** ([docs/codex-setup.md](docs/codex-setup.md)). No minimum is pinned for Claude Code, Cursor, or Pi; if `/plugin` (or the Cursor/Pi installer) runs, the plugin loads. |
 | **OS** | macOS and Linux are tested in CI. Windows is untested and best-effort; shell hooks and the optional Bash/`jq` MCP server need WSL or Git Bash. |
 | **Git** | A git repository. Session-orchestrator reads git state at every session start and commits at close. |
 
@@ -28,7 +38,7 @@ The same workflows are available on all four harnesses; Codex exposes commands a
 | **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry` (run both inside Claude Code). |
 | **Codex CLI** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs` |
 | **Cursor IDE** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/cursor-install.mjs /path/to/your/project` |
-| **Pi** | `pi install npm:session-orchestrator` — or dev-fallback: `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only` |
+| **Pi** | `pi install npm:session-orchestrator` ; dev fallback: `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only` |
 
 For Claude Code, also install the package's Node dependencies **once** and restart Claude Code. First locate the installed plugin:
 
@@ -50,9 +60,9 @@ Setup guides: [Codex](docs/codex-setup.md) · [Cursor IDE](docs/cursor-setup.md)
 
 In Codex, select the corresponding **Session Orchestrator** skill in the picker or use `$session-orchestrator:<command>`; the slash commands below name the shared workflows. For example, bootstrap with `$session-orchestrator:bootstrap`. See [Codex usage](docs/codex-setup.md#usage).
 
-**1. Bootstrap the repo once.** Run `/bootstrap` in your project — it scaffolds the minimum structure and writes `.orchestrator/bootstrap.lock`, which session-start requires before `/session` will run.
+**1. Bootstrap the repo once.** Run `/bootstrap` in your project. It scaffolds the minimum structure and writes `.orchestrator/bootstrap.lock`, which session-start requires before `/session` will run.
 
-**2. Declare a Session Config.** Add a `## Session Config` section to your project's `CLAUDE.md` (Claude Code, Cursor IDE) or `AGENTS.md` (Codex CLI, Pi) — see [instruction-file-resolution](skills/_shared/instruction-file-resolution.md) for which file each platform reads. The smallest valid config is seven fields:
+**2. Declare a Session Config.** Add a `## Session Config` section to your project's `CLAUDE.md` (Claude Code, Cursor IDE) or `AGENTS.md` (Codex CLI, Pi). See [instruction-file-resolution](skills/_shared/instruction-file-resolution.md) for which file each platform reads. The smallest valid config is seven fields:
 
 ```yaml
 ## Session Config
@@ -73,7 +83,7 @@ Everything else is opt-in. Full template: [`docs/session-config-template.md`](do
 ```text
 .orchestrator/bootstrap.lock        # written by /bootstrap, the gate for every later run
 .orchestrator/current-session.json  # which session owns this working copy right now
-.orchestrator/session.lock          # heartbeat lock — stops two sessions colliding in one checkout
+.orchestrator/session.lock          # heartbeat lock; stops two sessions colliding in one checkout
 .orchestrator/host.json             # host-local identity for peer-session detection
 .orchestrator/metrics/*.jsonl       # append-only session, learning, event and subagent records
 .orchestrator/steering/             # stable product/tech/structure context injected each session
@@ -83,8 +93,8 @@ Everything else is opt-in. Full template: [`docs/session-config-template.md`](do
 ## A session in three commands
 
 ```text
-/session feature    # research + Q&A — inspect git, issues, history, then agree on scope
-/go                 # execute in five typed waves (fixed roles), with a quality gate between each
+/session feature    # research + Q&A: inspect git, issues, history, then agree on scope
+/go                 # execute in typed waves sized by session type (feature: 3, deep: 5); quality gate between each
 /close              # verify every item, commit cleanly, file carryover issues for the rest
 ```
 
@@ -106,18 +116,18 @@ These entries preserve each command's full workflow and prechecks. Codex's nativ
 
 Restart the harness afterwards, and re-run `npm install` in the plugin directory when the release adds dependencies. On Cursor and the Pi clone fallback, upgrade with `git pull` in your clone followed by the same install script you originally ran. Manage npm-installed Pi packages through Pi's package manager. For Codex, follow the [refresh instructions](docs/codex-setup.md#refresh-and-explicit-cache-invalidation) for your marketplace source, then reload the skill picker or restart Codex.
 
-Session-start tells you when the running copy is behind: `scripts/lib/plugin-update-banner.mjs` compares the version of the code **that is actually loaded** against the published npm version and warns in the session-start banner (minor or major; patch-only updates stay silent). It fails silent — offline, a non-2xx response, or a malformed answer produces *no statement*, never a false "up to date".
+Session-start tells you when the running copy is behind: `scripts/lib/plugin-update-banner.mjs` compares the version of the code **that is actually loaded** against the published npm version and warns in the session-start banner (minor or major; patch-only updates stay silent). It fails silent: offline, a non-2xx response, or a malformed answer produces *no statement*, never a false "up to date".
 
-Upgrading across a major version: **[docs/migration-v4.md](docs/migration-v4.md)** is the current one — v4.0.0 removes five skills, three commands and eight top-level scripts, each on a measured 90-day two-signal rule rather than a judgement call, and it names what replaces every removed invocation. [docs/migration-v3.md](docs/migration-v3.md) documents the older v2 → v3 path and the shape both guides follow (what changes · prerequisites · per-platform steps · what stays · known issues · rollback).
+Upgrading across a major version: **[docs/migration-v5.md](docs/migration-v5.md)** covers the current release: the agent-status reader API changes and close-time discovery is enabled by default. If upgrading from before v4, also follow **[docs/migration-v4.md](docs/migration-v4.md)** for the removed skills, commands and scripts and their replacements. [docs/migration-v3.md](docs/migration-v3.md) documents the older v2 → v3 path and the shape both guides follow (what changes · prerequisites · per-platform steps · what stays · known issues · rollback).
 
 ## Uninstall
 
-Remove the plugin through your harness's own plugin manager — `/plugin` in Claude Code (marketplace entry `session-orchestrator@kanevry`), `codex plugin remove` on Codex CLI ([docs/codex-setup.md](docs/codex-setup.md)), or Pi's package manager for an npm-installed Pi package. On Cursor and the Pi clone fallback, delete the files the installer wrote into your project.
+Remove the plugin through your harness's own plugin manager: `/plugin` in Claude Code (marketplace entry `session-orchestrator@kanevry`), `codex plugin remove` on Codex CLI ([docs/codex-setup.md](docs/codex-setup.md)), or Pi's package manager for an npm-installed Pi package. On Cursor and the Pi clone fallback, delete the files the installer wrote into your project.
 
-**What stays behind in your repo** — none of it is removed by uninstalling, and all of it is plain text you can delete by hand:
+**What stays behind in your repo.** None of it is removed by uninstalling, and all of it is plain text you can delete by hand:
 
-- `.orchestrator/` — `bootstrap.lock`, `metrics/` (your session and learning JSONL records), `policy/`, `steering/`, `runtime/`, `peers/`, `session.lock`
-- `STATE.md` under your harness's state directory (`.claude/STATE.md` on Claude Code — see [Platform support](#platform-support))
+- `.orchestrator/`: `bootstrap.lock`, `metrics/` (your session and learning JSONL records), `policy/`, `steering/`, `runtime/`, `peers/`, `session.lock`
+- `STATE.md` under your harness's state directory (`.claude/STATE.md` on Claude Code; see [Platform support](#platform-support))
 - The `## Session Config` block you added to `CLAUDE.md` / `AGENTS.md`
 - `.claude/rules/*.md` if you vendored the rule library via `/bootstrap --sync-rules`
 
@@ -125,66 +135,61 @@ Deleting `.orchestrator/metrics/` deletes your session history. Telemetry requir
 
 ## Lifecycle and waves
 
-![Session Orchestrator wave lifecycle: /bootstrap once per repo, then /session, then /go running five typed waves — Discovery, G1, Impl-Core, G2, Impl-Polish, G3, Quality, G4 Full Gate, Finalization — followed by /close](assets/wave-lifecycle.svg)
+**Plan, Go, Close** describes the working rhythm. Bootstrap once per project, then start a session, execute its agreed scope, and close with evidence.
 
-The rendered diagram above ([`assets/wave-lifecycle.svg`](assets/wave-lifecycle.svg)) survives anywhere Markdown does. The Mermaid source below is the maintainable version of the same two flows:
+| Step | What happens | What carries forward |
+|---|---|---|
+| **Plan** | Read the code, issues and prior session. Agree the objective and assign file scopes. | One shared plan and separate responsibilities. |
+| **Go** | Run independent tasks, combine the changes, check the result and fix findings. | Changes with verification evidence. |
+| **Close** | Check the plan against the work, commit the result and record unfinished tasks. | A handover for the next session. |
 
-```mermaid
-flowchart TD
-    Z["/bootstrap"] -->|once per repo, writes bootstrap.lock| B["/session [type]"]
-    A["/plan [feature|retro]"] -->|optional, defines WHAT| B
-    B -->|research + Q&A| C["/go"]
-    C -->|5 waves with quality gates| D["/close"]
-    D -->|verifies + commits| E["/evolve [analyze]"]
-    E -->|extracts cross-session learnings| B
-    style Z fill:#475569,color:#fff
-    style C fill:#1f6feb,color:#fff
-    style D fill:#238636,color:#fff
-```
+Housekeeping uses **one** wave. Deep uses **five**; the **ultradeep** profile uses **seven**. Claude Code and Codex can run independent work in parallel. Cursor and Pi execute tasks sequentially. A failing check sends the findings back for correction.
+
+<details>
+<summary>Deep-session stages and the ultradeep profile</summary>
 
 ```mermaid
 flowchart LR
-    W1["1·Discovery<br/>read-only audit"] --> G1{Gate}
-    G1 --> W2["2·Impl-Core<br/>primary code"]
-    W2 --> G2{Gate}
-    G2 --> W3["3·Impl-Polish<br/>integration, edges"]
-    W3 --> G3{Gate}
-    G3 --> W4["4·Quality<br/>simplify + tests"]
-    W4 --> G4{Full Gate}
-    G4 --> W5["5·Finalization<br/>commit + close"]
-    style G4 fill:#d29922,color:#000
+    D[Discovery] --> I[Implementation]
+    I --> P[Integration and polish]
+    P --> Q[Quality checks]
+    Q --> F[Finalization]
 ```
 
-`/plan` is optional — you can create issues manually and jump straight to `/session`. `/evolve` runs deliberately after 5+ sessions, not automatically. Both diagrams show the happy path; a failing gate stops the wave and hands the findings back.
+The deep session uses Discovery, Impl-Core, Impl-Polish, Quality and Finalization. Checks run between waves, with a full configured quality gate before completion. The diagram shows the successful path, not a guarantee that the first attempt passes.
+
+Ultradeep is a profile over `session-type: deep`, not a fourth session-type value. It runs Research, Code-Discovery, Impl-Core, Impl-Polish, a read-only Review-Panel, Quality and Release, with a coordinator Synthesis-Gate after the first two waves. Downstream tooling still sees `deep`.
+
+`/plan` is optional when you need a PRD or retrospective before a session. `/evolve` deliberately extracts patterns across sessions.
 
-For sessions that outgrow five waves there is a named **`ultradeep` profile**: a profile over `session-type: deep` that runs seven waves — Research + Code-Discovery, a blocking coordinator Synthesis-Gate, Impl-Core, Impl-Polish, a read-only Review-Panel, Quality, Release — instead of a fourth session-type enum value. Downstream tooling still sees `deep`.
+</details>
 
 ## How it works
 
-Most agentic-coding tools jump straight into writing code. Session Orchestrator adds a structured loop on top: research first, agree on scope, then execute in typed waves with verification gates between them.
+The workflow starts with the state of the project. The plan records what to change, who handles each part and what counts as verified.
 
 When you type `/session feature`:
 
-1. **Phase analysis runs in parallel** — git state, open issues, recent commits, SSOT freshness, resource health, and prior-session memory are all inspected, then distilled into a structured Session Overview with a recommendation, not a wall of raw data.
-2. **You agree on scope** — through a tool-rendered picker (Claude Code) or a numbered list (Codex / Cursor / Pi). The orchestrator has an opinion and tells you what it would do.
-3. **The plan is decomposed into waves** — Discovery (read-only), Impl-Core, Impl-Polish, Quality, Finalization. Each wave has a defined purpose and a deliverable; agent counts scale by session type.
-4. **`/go` executes** — agents work in parallel within a wave. A session-reviewer audits the output between waves on eight dimensions; only findings at confidence ≥ 80 reach you.
-5. **`/close` ships it** — every planned item is verified, quality gates run full, and unfinished work becomes carryover issues. Files are staged individually, so parallel sessions can't stomp each other.
+1. **Read the project.** Git state, open issues, recent commits, documentation, resource health and prior-session records inform a Session Overview with a recommendation.
+2. **Agree the scope.** Review the proposed work and correct the plan before implementation.
+3. **Assign the work.** The session type determines the wave structure. Each wave has a purpose, declared paths and a result to verify.
+4. **`/go` executes.** Independent agents can work in parallel on Claude Code and Codex; Cursor and Pi execute sequentially. Reviews and checks bring the work back together.
+5. **`/close` verifies and records it.** Check planned items, run the full quality gate, commit the result and record unfinished work as carryover. The coordinator stages files individually.
 
 Two complementary commands round out the loop: **`/plan`** runs *before* a session when you need a PRD or retrospective; **`/evolve`** runs occasionally to surface patterns across sessions and feed them back at the next start.
 
-The system is markdown-driven config plus a thin Node runtime — skills, commands, and agents are Markdown with YAML frontmatter; `scripts/lib/*.mjs` and `hooks/*.mjs` handle dispatch, validation, and telemetry. Everything is plain text: if something goes wrong, you can read every file and see what happened.
+The system is markdown-driven config plus a thin Node runtime. Skills, commands, and agents are Markdown with YAML frontmatter; `scripts/lib/*.mjs` and `hooks/*.mjs` handle dispatch, validation, and telemetry. Everything is plain text: if something goes wrong, you can read every file and see what happened.
 
 ## What you get
 
 Counts measured on 2026-09-07 with the command in brackets:
 
-- **43 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, and audits (`ls -d skills/*/ | grep -v _shared | wc -l`)
-- **25 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …) (`ls commands/*.md | wc -l`)
+- **44 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, UX grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, and audits (`ls -d skills/*/ | grep -v _shared | wc -l`)
+- **26 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/ux-grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …) (`ls commands/*.md | wc -l`)
 - **14 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …) (`ls agents/*.md | wc -l`)
-- **27 hook files across 10 event types**, enforcing scope, blocking destructive commands, gating templates-first, and capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged elsewhere ([Platform support](#platform-support)) (`ls hooks/*.mjs | wc -l`)
+- **27 hook files across 10 event types** for scope checks, destructive-command policy, templates-first gates and telemetry. Claude Code runs the guard hooks directly; Cursor and Pi bridge supported calls. Codex does not enforce the destructive-command or file-scope guard ([Platform support](#platform-support)) (`ls hooks/*.mjs | wc -l`)
 - **26 rule files** and **18 ADRs** carrying the reasoning behind the mechanisms (`ls .claude/rules/*.md | wc -l`, `ls docs/adr/*.md | wc -l`)
-- **667 vitest test files** covered by the full quality gate and CI — 13,827 static `it()`/`test()` definitions at that measurement, and the runtime total is higher because of parameterised blocks ([methodology](docs/telemetry/telemetry-claims.md)) (`find tests -name '*.test.mjs' | wc -l`)
+- **664 vitest test files** covered by the full quality gate and CI; 13,789 static `it()`/`test()` definitions at that measurement, and the runtime total is higher because of parameterised blocks ([methodology](docs/telemetry/telemetry-claims.md)) (`find tests -name '*.test.mjs' | wc -l`); Full Gate 2026-09-09: 16847 passed / 11 skipped / 664 files
 
 **Portable across harnesses by construction.** `scripts/generate-agents-skills.mjs` generates root `AGENTS.md` byte-identical from `CLAUDE.md` and the `.agents/skills/<name>/SKILL.md` mirrors, with spec-legal frontmatter and pointers to canonical instructions. `scripts/generate-codex-skills.mjs` generates the Codex command entrypoints. Plugin validation checks both surfaces. Separate manifests under `.claude-plugin/`, `.codex-plugin/` and `.cursor-plugin/` register each harness's components; see [Codex manifest compatibility](docs/codex-setup.md#manifest-compatibility).
 
@@ -192,44 +197,45 @@ Full component inventory: [`docs/components.md`](docs/components.md). Version hi
 
 ## Why this design
 
-- **Typed waves, not one big batch.** Discovery first, so implementers start with shared context. Impl-Core before Impl-Polish, so architecture lands before integrations. Quality runs a *simplification pass* on AI-generated code **before** tests are written — otherwise tests pin the AI patterns into place.
+- **Typed waves, not one big batch.** Discovery first, so implementers start with shared context. Impl-Core before Impl-Polish, so architecture lands before integrations. Quality runs a *simplification pass* on AI-generated code **before** tests are written; otherwise tests pin the AI patterns into place.
 - **Inter-wave reviews, not just end-of-session.** Catching regressions between waves stops a bad pattern from propagating into later work; the confidence floor filters speculative criticism so only high-signal findings reach you.
 - **State persists across crashes.** `STATE.md` records wave progress and deviations; the next `/session` offers to resume from the last completed wave.
-- **Hook enforcement has a defined platform boundary.** Claude Code hooks block covered destructive commands; writes outside declared paths warn in `warn` mode and block in `strict` mode. Cursor and Pi bridge supported events. Codex currently has no scope-enforcement adapter ([Platform support](#platform-support)).
-- **Parallel *operator* sessions are treated as a hazard.** Two humans — or two of your own sessions — in the same working copy share one git index, one filesystem, one `STATE.md`. A heartbeat session lock, peer-scope manifests, and the PSA rule set in [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) exist for exactly that axis.
+- **Hook enforcement has a defined platform boundary.** On Claude Code, the active destructive-command hook applies the policy’s blocking and warning rules. With an active compatible scope hook, supported writes outside declared paths warn in `warn` mode and block in `strict` mode; `off` disables scope checking. Cursor and Pi bridge supported events. Both guards are instructions only on Codex ([Platform support](#platform-support)).
+- **Parallel *operator* sessions are treated as a hazard.** Two humans, or two of your own sessions, in the same working copy share one git index, one filesystem, one `STATE.md`. A heartbeat session lock, peer-scope manifests, and the PSA rule set in [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) exist for exactly that axis.
 - **Cross-session learning is opt-in and inspectable.** Every session writes a record; after 5+ sessions `/evolve analyze` extracts confidence-scored patterns you can read and prune. Nothing is hidden.
 - **VCS dual support, no lock-in.** Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.
 
-How this compares to other orchestrators — with the parts that are measured and the parts that are not: [`docs/components.md` § Comparisons](docs/components.md#comparisons).
+A comparison with other orchestrators, distinguishing measured results from unmeasured claims: [`docs/components.md` § Comparisons](docs/components.md#comparisons).
 
-## Recent highlights (v4.1.0)
+## Recent highlights (v5.0.0)
 
-Highlights of the v4.1.0 line:
+Highlights of the v5.0.0 line:
 
-- **Privacy and session ownership.** The privacy scanner covers MDX and can include untracked files with `--include-untracked`. Native Codex task IDs now confirm session ownership; ambiguous inherited IDs remain unconfirmed.
-- **CI and release recovery.** Coverage verification now requires valid reports and measured thresholds. Audit detection checks executable workflow commands; GitHub release recovery retains the exact repository, tag and retry notes.
-- **Clearer onboarding.** README, English/German pages and the guide agree on installation and platform capabilities. Guide Copy buttons stay beside their command blocks, including on narrow screens.
+- **Agent status carries provenance.** `readCurrentStatus()` returns entries with their source, timestamp and degradation details. Integrations that need the former bare map can use `readCurrentStatusEntries()`. Read the [v5 migration guide](docs/migration-v5.md) before upgrading a deep-import consumer.
+- **Bounded operations use an explicit run contract.** Session-start can coordinate launch preparation, research and community work with a deadline, scoped accounts, one publisher and verified outcomes. It uses the active harness and does not install a background scheduler.
+- **Discovery runs at close by default.** Repos without `discovery-on-close` now receive the close-time scan; set it to `false` to retain the previous behavior. Failed issue creation refunds only a proven budget charge, and agent-status recovery reports stale data instead of silently trusting it.
 
-If upgrading from before 4.0, read [the v4 migration guide](docs/migration-v4.md). Full changes and verification: [CHANGELOG.md](CHANGELOG.md).
+If upgrading from before 4.0, also read [the v4 migration guide](docs/migration-v4.md). Full changes and verification: [CHANGELOG.md](CHANGELOG.md).
 
 ## Platform support
 
 | Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
 |---|---|---|---|---|
-| All 25 commands | Native slash commands | Generated skills (`$session-orchestrator:<name>`) | Native `.cursor/commands` slash commands | Prompt templates |
+| All 26 commands | Native slash commands | Generated skills (`$session-orchestrator:<name>`) | Native `.cursor/commands` slash commands | Prompt templates |
 | Parallel agents | Agent tool | Multi-agent roles | Sequential only | Sequential (parallel planned) |
 | Session persistence | `.claude/STATE.md` | `.codex/STATE.md` | `.cursor/STATE.md` | `.pi/STATE.md` |
-| Scope enforcement | PreToolUse hooks | Unavailable — pending a real `apply_patch` adapter | `preToolUse` + `beforeShellExecution` via cursor-hook-bridge; `afterFileEdit` post-hoc | `tool_call` bridge |
+| Scope enforcement | Active PreToolUse hook; blocking in `strict`, reporting in `warn` | Instructions only; no compatible `apply_patch` handler | `preToolUse` + `beforeShellExecution` bridge; scope blocking requires `strict`; `afterFileEdit` is post-hoc | `tool_call` bridge; scope blocking requires `strict` |
+| Destructive-command guard | Active PreToolUse hook applies policy severity | Instructions only; no handler wired | `beforeShellExecution` bridge for supported commands | `tool_call` bridge for supported commands |
 | AskUserQuestion | Native tool | Numbered-list fallback | Numbered-list fallback | Numbered-list fallback |
 | Quality gates | Full | Full | Full | Full |
 
-All platforms share the same skills, commands, and scripts; hooks use platform-specific adapters and event subsets. Codex intentionally wires only its six supported project event slots and omits Claude-only events plus Edit/Write payload handlers until a real Codex `apply_patch` adapter exists, so scope enforcement is currently unavailable there. Platform detection lives in `scripts/lib/platform.mjs`. Cursor and Pi have known event-coverage caveats — see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
+All platforms share the same skills, commands, and scripts; hooks use platform-specific adapters and event subsets. Codex leaves `PreToolUse` handlers empty because these guards do not yet match its tool names and edit payloads. Both the destructive-command and file-scope guards are instructions only there; see [`docs/codex-setup.md`](docs/codex-setup.md#why-our-pretooluse-guards-stay-unwired--the-reason-corrected). Platform detection lives in `scripts/lib/platform.mjs`. Cursor and Pi have known event-coverage limits; see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
 
 ## Safety & data & telemetry
 
-**Your data stays in your repo.** Session Orchestrator runs locally, requires no account, and writes its records as append-only JSONL under `.orchestrator/metrics/` in *your* repository — sessions, learnings, events, subagent records. Those files are yours: readable, greppable, deletable. Optional anonymous usage telemetry is **off until you explicitly consent** and is separate from the local records ([docs/telemetry.md](docs/telemetry.md) says exactly what it would collect and how to turn it off). Reported metrics describe *this* repository under its own conditions and will not transfer unchanged to yours ([details](docs/telemetry/telemetry-claims.md)).
+**Your data stays in your repo.** Session Orchestrator runs locally, requires no account, and writes its records as append-only JSONL under `.orchestrator/metrics/` in *your* repository: sessions, learnings, events, subagent records. Those files are yours: readable, greppable, deletable. Optional anonymous usage telemetry is **off until you explicitly consent** and is separate from the local records ([docs/telemetry.md](docs/telemetry.md) says exactly what it would collect and how to turn it off). Reported metrics describe *this* repository under its own conditions and will not transfer unchanged to yours ([details](docs/telemetry/telemetry-claims.md)).
 
-**Destructive-command guard.** On Claude Code, `hooks/pre-bash-destructive-guard.mjs` enforces `.orchestrator/policy/blocked-commands.json` — 14 rules, of which 10 block outright (`git reset --hard`, `rm -rf`, `git push --force`, and more) and 4 warn — in the main session *and* in subagent waves. Other harnesses depend on their event adapters; see [Platform support](#platform-support). Bypass per session only for intentional maintenance:
+**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 10 blocking rules (`git reset --hard`, `rm -rf`, `git push --force`, 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](#platform-support). Where the hook is active, bypass it per session only for intentional maintenance:
 
 ```yaml
 allow-destructive-ops: true
@@ -237,15 +243,15 @@ allow-destructive-ops: true
 
 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 "Internal hook error — request blocked", 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`.
+**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`.
 
 ## Troubleshooting
 
 **Codex plugin or hooks not loading.** Start with `codex plugin list --available --json`. Confirm `session-orchestrator@kanevry` is installed, enabled, unique, and at the tracked manifest version; then start a fresh task and review `/hooks`. Remove only the two allowlisted legacy IDs through `codex plugin remove`, and resolve marketplace conflicts through the public marketplace remove/add lifecycle before reinstalling. Any other pre-public plugin/config/cache/hook-state residue is unsupported: do not modify private Codex files; file an issue with `codex --version` plus the public plugin and marketplace list output. Full decision tree: [`docs/codex-setup.md`](docs/codex-setup.md#troubleshooting).
 
-**"'node' not found on the hook PATH — plugin hooks are skipped."** The harness executes hook commands via `/bin/sh -c` with its own PATH — that shell does not source `~/.zshrc`/`~/.bashrc`, so Node installed via Homebrew, nvm, volta, or asdf can be invisible to hooks even though `node` works in your terminal. All hook commands route through [`hooks/run-node.sh`](hooks/run-node.sh), which resolves Node via `$SO_NODE_BIN` → PATH → well-known install dirs → nvm and degrades gracefully: hooks are skipped with **one** warning per 6 hours instead of a shell error on every tool call. Fixes, in order of preference: launch the harness from a shell where `node` resolves; export `SO_NODE_BIN=/abs/path/to/node`; or install Node 24+ to a standard location.
+**Node is missing from the hook PATH.** The harness executes hook commands via `/bin/sh -c` with its own PATH. That shell does not source `~/.zshrc`/`~/.bashrc`, so Node installed via Homebrew, nvm, volta, or asdf can be invisible to hooks even though `node` works in your terminal. All hook commands route through [`hooks/run-node.sh`](hooks/run-node.sh), which resolves Node via `$SO_NODE_BIN` → PATH → well-known install dirs → nvm and degrades gracefully: hooks are skipped with **one** warning per 6 hours instead of a shell error on every tool call. Fixes, in order of preference: launch the harness from a shell where `node` resolves; export `SO_NODE_BIN=/abs/path/to/node`; or install Node 24+ to a standard location.
 
-**`/session` refuses to start.** It needs `.orchestrator/bootstrap.lock` — run `/bootstrap` first, or `/bootstrap --retroactive` if the repo already has a `## Session Config` block.
+**`/session` refuses to start.** It needs `.orchestrator/bootstrap.lock`. Run `/bootstrap` first, or `/bootstrap --retroactive` if the repo already has a `## Session Config` block.
 
 ## Development
 
@@ -257,45 +263,51 @@ npm run lint      # ESLint v10 + Prettier
 npm run typecheck # node --check on every .mjs file
 ```
 
-`.npmrc` ships with `ignore-scripts=true` (supply-chain defence), so Husky git hooks don't auto-wire on install — run `npx husky` once after cloning. `git commit` then runs gitleaks → owner-privacy scan → lint-staged → commitlint. CI re-runs everything, plus more.
+`.npmrc` ships with `ignore-scripts=true` (supply-chain defence), so Husky git hooks don't auto-wire on install. Run `npx husky` once after cloning. `git commit` then runs gitleaks → owner-privacy scan → lint-staged → commitlint. CI re-runs everything, plus more.
 
 Two directories share the name *rules* and play opposite roles: [`rules/`](rules/README.md) is the **deliverable rule library** shipped *out* to consumer repos via `/bootstrap --sync-rules`, while [`.claude/rules/`](https://github.com/Kanevry/session-orchestrator/tree/main/.claude/rules/) is this repo's own rule set with always-on and path-scoped entries.
 
 Contributor docs: [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) · [CONTRIBUTING.md](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md) · [sub-agent authoring spec](docs/agent-authoring.md).
 
+## Why I built it
+
+I kept a Notion page with 20–30 prompts for different projects. Before each session I copied the relevant row and explained how I wanted to work again. That routine gradually became Plan, Go, Close. I use it on my Mac M4 and the M5 at the office; Session Orchestrator is the tool that grew out of it.
+
 ## Support & scope
 
-Session Orchestrator is provided **as-is** — a community project with no SLA, no commercial support contract, and no guaranteed response time. Maintenance is best-effort.
+Session Orchestrator is provided **as-is**, a community project with no SLA, no commercial support contract, and no guaranteed response time. Maintenance is best-effort.
+
+[Buy me a coffee, if this helped.](https://paypal.me/Kanevry)
 
 - Questions, ideas, show-and-tell → [GitHub Discussions](https://github.com/Kanevry/session-orchestrator/discussions)
 - Bugs and feature requests → [Issues](https://github.com/Kanevry/session-orchestrator/issues)
 
 What it is **not**:
 
-- **Not an official product of any agent vendor.** An independent, community-maintained project — not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Cursor, or any agent it integrates with. (It is distributed through the Claude Code plugin marketplace, but is not an Anthropic product.)
-- **Not a replacement** for Claude Code / Codex CLI / Cursor / Pi. It is a workflow layer that runs *on top of* your existing agent — you still need one of those installed.
+- **Not an official product of any agent vendor.** An independent, community-maintained project, not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Cursor, or any agent it integrates with. (It is distributed through the Claude Code plugin marketplace, but is not an Anthropic product.)
+- **Not a replacement** for Claude Code / Codex CLI / Cursor / Pi. It is a workflow layer that runs *on top of* your existing agent; you still need one of those installed.
 - **Not a multi-user product.** Single-operator by design; the parallel-session machinery protects one operator's concurrent sessions, not a shared team workspace.
 
 ## Documentation
 
-- [docs/ Router](docs/README.md) — living reference vs. public decision history vs. active work documents
-- [User Guide](docs/USER-GUIDE.md) — installation, config reference, workflow walkthrough, FAQ
-- [Components & Reference](docs/components.md) — full skill/command/agent/hook inventory, repository anatomy, comparisons
-- [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) — contributor guide, layering, hook anatomy, testing
-- [Migration to v4](docs/migration-v4.md) — upgrade path, removed surfaces and replacements
-- [Telemetry](docs/telemetry.md) · [Telemetry claims](docs/telemetry/telemetry-claims.md) — what is collected, how metrics are measured, why they may not transfer
-- [Example Configs](https://github.com/Kanevry/session-orchestrator/tree/main/docs/examples/) — Session Config examples for Next.js, Express, Swift
-- [CHANGELOG.md](CHANGELOG.md) — version history
+- [docs/ Router](docs/README.md): living reference vs. public decision history vs. active work documents
+- [User Guide](docs/USER-GUIDE.md): installation, config reference, workflow walkthrough, FAQ
+- [Components & Reference](docs/components.md): full skill/command/agent/hook inventory, repository anatomy, comparisons
+- [Plugin Architecture (v3)](docs/plugin-architecture-v3.md): contributor guide, layering, hook anatomy, testing
+- [Migration to v4](docs/migration-v4.md): upgrade path, removed surfaces and replacements
+- [Telemetry](docs/telemetry.md) · [Telemetry claims](docs/telemetry/telemetry-claims.md): what is collected, how metrics are measured, why they may not transfer
+- [Example Configs](https://github.com/Kanevry/session-orchestrator/tree/main/docs/examples/): Session Config examples for Next.js, Express, Swift
+- [CHANGELOG.md](CHANGELOG.md): version history
 
-We follow [Conventional Commits](https://www.conventionalcommits.org/) — see [CONTRIBUTING.md](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md).
+We follow [Conventional Commits](https://www.conventionalcommits.org/). See [CONTRIBUTING.md](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md).
 
 ## Learn the method behind it
 
-This plugin is a methodology turned into code. The reasoning behind it — why execution runs in waves, why every wave ends at a verification gate, how to make an autonomous loop that actually finishes — is taught hands-on at **[agenticbuilders.at](https://agenticbuilders.at)**: [Multi-Agent Orchestration](https://agenticbuilders.at/orchestrierung) and [Loop Engineering](https://agenticbuilders.at/loop-engineering). The plugin is free and MIT; the courses are for going deeper, not a requirement for using it.
+This plugin is a methodology turned into code. The reasoning behind it is taught hands-on at **[agenticbuilders.at](https://agenticbuilders.at)**: [Multi-Agent Orchestration](https://agenticbuilders.at/orchestrierung) and [Loop Engineering](https://agenticbuilders.at/loop-engineering). The courses cover why execution runs in waves, why each wave ends at a verification gate, and how to make an autonomous loop that finishes. The plugin is free and MIT; the courses are for going deeper, not a requirement for using it.
 
 ## Links
 
-[Homepage](https://session-orchestrator.com) (also at [/de](https://session-orchestrator.com/de) in German, with a plain-words layer above the developer detail) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy) · [npm](https://www.npmjs.com/package/session-orchestrator)
+[Homepage](https://session-orchestrator.com) (also at [/de](https://session-orchestrator.com/de) in German, with the workflow, installation paths and platform limits) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy) · [npm](https://www.npmjs.com/package/session-orchestrator)
 
 ## License
 

package/agents/dialectic-deriver.md

@@ -95,6 +95,17 @@ Rules:
 
 - Emit **at most one block per target**. Omit a target entirely when no update is warranted.
 - The block body is the **FULL replacement body** — not a unified diff hunk.
+- **`## ` headings are the merge unit (#1310).** On `--apply` the orchestrator splits your body at each
+  level-2 (`## `) heading and maps each one onto a sentinel-delimited managed region via
+  `mergeDerivedBody()` (`scripts/lib/peer-cards/merger.mjs`). Consequences you control:
+  - **Reuse the existing card's heading text VERBATIM** for any section you mean to UPDATE. A
+    changed heading is a NEW section: the old one is kept (nothing auto-deletes) and yours is
+    appended beside it, so the card ends up carrying both.
+  - A heading not present in the card is appended as a new managed region — that is the
+    supported way to add a section.
+  - Put **nothing before the first `## ` heading**. Preamble prose has no section to live in; the
+    orchestrator surfaces it as an `unmapped-preamble` conflict and does not apply it.
+  - Do **not** emit `<!-- BEGIN/END MANAGED: … -->` sentinels yourself. The merger owns them.
 - Do **NOT** include `---` frontmatter lines in your block. The orchestrator preserves
   existing frontmatter and updates the `updated` field.
 - Optional footer comment after all blocks may report token usage to aid budget audits:

package/agents/ux-evaluator.md

@@ -51,7 +51,7 @@ Log a warning to stdout (not a finding) if an expected artifact type is absent.
 
 **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 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 project-owned `docs/apple-hig-exceptions.md` or similar). Fingerprint inputs: `scope='liquid-glass'`, `checkId='missing-glassEffect'`, `locator=<screen-name>.<frame-id>`. <!-- path-check: example -->
 
 **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>"`).
 

package/commands/close.md

@@ -10,9 +10,9 @@ 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`:** `status: completed` alone is NOT proof that session-end's Phase 3.7 writer ever ran (#429) — the field can be set by hand, or by any path that stops short of that write. Before treating the prior close as final, read STATE.md frontmatter's `session` field (the semantic session id, e.g. `main-2026-05-27-session-1`; see `skills/_shared/state-ownership.md`) and check whether `.orchestrator/metrics/sessions.jsonl` contains a record whose `session_id` equals it (`grep -c` for the literal id, or parse each line as JSON and compare `session_id`).
-   - **A matching record exists:** 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.
-   - **No `session` field is present in STATE.md frontmatter, OR no matching record exists:** Warn the user: "STATE.md completed ohne Ledger-Record — session-end wurde vorher nie ausgeführt (#429)." Do NOT stop — proceed to invoke the session-end skill exactly as in exit condition 3, so the missing record gets written this time. (The SessionEnd hook's `backfillCompletedFromStateMd` — `scripts/lib/session-close-backfill.mjs` — independently self-heals this same gap on a later session's teardown; this Pre-Check branch covers the case where /close is re-run before that hook has had a chance to fire.)
+2. **STATE.md exists and `status: completed`:** `status: completed` alone is NOT proof that session-end's Phase 3.7 writer ever ran (#429) — the field can be set by hand, or by any path that stops short of that write. Parse STATE.md with `parseStateMd` and parse `.orchestrator/metrics/sessions.jsonl` as JSONL. Import `findRecordedSession` from the plugin's `scripts/lib/session-close-backfill.mjs` and call it with the parsed records and `{ sessionId: frontmatter['session-id'], semanticSessionId: frontmatter.session, startedAt: frontmatter.started_at }`. This is the shared backfill identity reader: native UUIDs take precedence, conflicting native IDs never match through a label, and legacy semantic records remain readable. Do not substitute a text grep or compare the semantic label only against `session_id`. A missing ledger means no record; an unreadable or malformed ledger is inconclusive — report the read/parse failure and stop before repeating close side effects.
+   - **A matching completed record exists (including a legacy authoritative record without a `status` field):** 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.
+   - **No matching completed record exists:** Warn the user: "STATE.md completed ohne passenden Abschluss im Ledger — session-end wird zur Vervollständigung ausgeführt (#429)." An abandoned backfill stub does not prove finalization. Do NOT stop — proceed to invoke the session-end skill exactly as in exit condition 3, so the missing completion gets written this time. (The SessionEnd hook's `backfillCompletedFromStateMd` independently self-heals this same gap on a later session's teardown; this Pre-Check branch covers the case where /close is re-run before that hook has had a chance to fire.)
 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.

package/commands/go.md

@@ -18,6 +18,8 @@ Express path activated — <N> tasks, coordinator-direct, no inter-wave checks.
 
 If the banner is present (and the session-plan output emitted a 1-wave Express Path plan per `skills/session-plan/SKILL.md` § "Express Path Short-Circuit"):
 
+**The express 1-wave plan IS the housekeeping shape.** `node scripts/session-shape.mjs --repo-root "$PWD" --session-type housekeeping --no-event` resolves to a single wave with `coordinatorDirect: true` — the express path is not a bespoke shortcut but that shape executed. Consequently, when the session type is `housekeeping`, the coordinator-direct execution runs the **maintenance loop first** (drift-check, expired sweep, `/evolve analyze`, `/reconcile`, `/evolve dialectic`, `/memory-cleanup` — ordered scope, gates and proving artefacts in `skills/wave-executor/SKILL.md` § Housekeeping Sessions — the Maintenance Loop), and **then** the selected issues in dependency order.
+
 1. **Execute the agreed tasks directly** as coordinator actions, in dependency order. Do NOT dispatch subagents. Do NOT invoke the wave-executor skill.
 2. **Append the Express Path deviation to STATE.md** before invoking session-end. Use `appendDeviationOnDisk()` from `scripts/lib/state-md.mjs` — the on-disk wrapper takes the STATE.md lock automatically, serialising any concurrent writers. This step ensures the audit trail exists BEFORE session-end finalizes the file. Equivalent one-liner via Bash:
    ```bash

package/commands/memory-cleanup.md

@@ -13,12 +13,13 @@ The skill accepts two optional, mutually-exclusive flags (see PRD #502):
 
 | Flag | Behavior |
 |---|---|
-| `--dry-run` | Run Phases 1-3 read-only. Writes a complete-replacement MEMORY.md proposal (single fenced ` ```markdown ` block; topic-file changes carried as separate `### Topic-file change:` sections after it — never git-style diff hunks, see #717) to `.orchestrator/pending-dream.md` (atomic write). Prints `pending-dream written: <N> lines proposed` (or `no consolidation needed`). Exit 0. |
-| `--apply-pending` | Reads `.orchestrator/pending-dream.md`, refuses if older than 14 days or if MEMORY.md changed since the producing `--dry-run` (#788), applies the proposal, deletes the pending file. Prints `auto-dream applied: -<X> lines, +<Y> entries`. Exit 0 on apply; exit 1 when pending file is missing (`no pending dream to apply`), stale (`pending dream is stale (>14d), re-run --dry-run`), index-drifted (`MEMORY.md changed since the producing --dry-run; re-run --dry-run.`), or unsupported-format (`auto-dream NOT applied: pending-dream.md contains git-style diff hunks this applier cannot consume. MEMORY.md left untouched, sidecar preserved. Re-run /memory-cleanup --dry-run to regenerate a complete-body proposal.`). |
+| `--dry-run` | Run Phases 1-3 read-only. Writes a complete-replacement MEMORY.md proposal (single fenced ` ```markdown ` block; topic-file changes carried as separate `### Topic-file change:` sections after it — never git-style diff hunks, see #717) to `.orchestrator/pending-dream.md` (atomic write). Prints `pending-dream written: <N> lines proposed` (or `no consolidation needed`). Exit 0. <!-- path-check: example --> |
+| `--apply-pending` | Reads `.orchestrator/pending-dream.md`, refuses if older than 14 days or if MEMORY.md changed since the producing `--dry-run` (#788), applies the proposal, deletes the pending file. Prints `auto-dream applied: -<X> lines, +<Y> entries`. Exit 0 on apply; exit 1 when pending file is missing (`no pending dream to apply`), stale (`pending dream is stale (>14d), re-run --dry-run`), index-drifted (`MEMORY.md changed since the producing --dry-run; re-run --dry-run.`), or unsupported-format (`auto-dream NOT applied: pending-dream.md contains git-style diff hunks this applier cannot consume. MEMORY.md left untouched, sidecar preserved. Re-run /memory-cleanup --dry-run to regenerate a complete-body proposal.`). <!-- path-check: example --> |
 
 Passing both flags is an error. Absence of both = legacy interactive 4-phase mode.
 
-Session-end Phase 3.6.5 (`scripts/lib/auto-dream.mjs`) is nudge-only (#614) — it never dispatches a subagent to write the sidecar. The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock.
+Session-end Phase 3.6.5 (`scripts/lib/auto-dream.mjs`) is nudge-only (#614) — it never dispatches a subagent to write the sidecar.
+The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock. <!-- path-check: example -->
 
 ## Default (no flag)
 

package/commands/persona-panel.md

@@ -111,7 +111,7 @@ Resolves catalog and target, prints the planned dispatch list (persona names, mo
 /persona-panel docs/design-doc.md --grounding re-derive
 ```
 
-Each dispatched persona is instructed to independently re-derive supporting sources via Read/Grep/Glob rather than trusting a "Sources" section already present in `docs/design-doc.md`, and reports them as `derived_sources`. Advisory-only — `final_verdict` is unaffected.
+Each dispatched persona is instructed to independently re-derive supporting sources via Read/Grep/Glob rather than trusting a "Sources" section already present in the input document (for example, `docs/design-doc.md`), and reports them as `derived_sources`. Advisory-only — `final_verdict` is unaffected. <!-- path-check: example -->
 
 ## Related
 

package/commands/session.md

@@ -9,7 +9,7 @@ You are beginning a new development session. The user has invoked `/session` wit
 
 **Default rationale (measured, not assumed):** `deep` is the default because it is what operators actually run — 77.3 % of 489 recorded sessions across 5 repos, and 115 of 228 (50.4 %) in this repo's own `.orchestrator/metrics/sessions.jsonl`. The former `feature` default made the majority case the one that had to be typed out every time. A `deep` default costs a downgrade keystroke in the minority case; a `feature` default cost an upgrade keystroke in the majority case.
 
-**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. An explicit `$ARGUMENTS` value ALWAYS wins over the default — `/session housekeeping` and `/session feature` behave exactly as before. `ultradeep` is additionally accepted as an ARGUMENT ALIAS (see below); it is not a fourth type. If `$ARGUMENTS` is not empty and does not match any valid type or the alias, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep (alias: ultradeep)." Then fall back to `deep`.
+**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. An explicit `$ARGUMENTS` value ALWAYS wins over the default — `/session housekeeping` and `/session feature` behave exactly as before. `ultradeep` is additionally accepted as an ARGUMENT ALIAS (see below); it is not a fourth type. If `$ARGUMENTS` is not empty and does not match any valid type or the alias, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep (alias: ultradeep)." Then fall back to `deep`. Once the type (and any profile) is settled, the resolved execution shape is recorded at plan time by `node scripts/session-shape.mjs` (event `orchestrator.session.shape_resolved`), so the ledger can answer "how many waves did this session actually run".
 
 ### Argument alias: `ultradeep` (PRD `docs/prd/2026-09-06-ultradeep-session-profile.md`)
 
@@ -23,7 +23,8 @@ session-profile: ultradeep  # the only place the alias survives
 - **`session-type` NEVER becomes `ultradeep`.** The value is a closed set in `scripts/lib/session-schema/constants.mjs` (`VALID_SESSION_TYPES`) and in `scripts/lib/wave-sizing.mjs`; a fourth member would degrade silently in two places (`scripts/lib/telemetry/schema.mjs` maps an unknown type to `"other"`, `scripts/lib/session-close-backfill.mjs` labels it `housekeeping`). The alias exists so that no closed set has to change.
 - **`session-profile` is optional and absent by default.** A plain `/session deep` writes NO `session-profile` key. Absent means "no profile" — never write an empty string, `none`, or `null` to mean absence. Read/write helpers: `readSessionProfile` / `setSessionProfile` in `scripts/lib/state-md.mjs`.
 - **What the profile changes** is the WAVE SHAPE, not the session type: 7 waves with a coordinator-direct Synthesis-Gate at wave 2. See `skills/session-plan/SKILL.md` § Role-to-Wave Mapping and `skills/wave-executor/SKILL.md` § Ultradeep Profile.
-- **Precondition.** The profile needs 7 waves. If Session Config sets `waves` below 7, do NOT silently plan 5 waves under an ultradeep label — name the conflict to the user and let them raise `waves` or drop the alias.
+- **The profile OWNS its wave count.** `resolveSessionShape({ profile: 'ultradeep' })` returns 7 waves and reports `wavesConfigHonored: false` together with the ignored value; the `waves` key never applies to the profile (PRD AC-9 dropped 2026-09-09). Nothing to reconcile, nothing to ask the user about — read the count from `node scripts/session-shape.mjs --session-type deep --profile ultradeep`.
+- **Cost — why the alias stays the exception.** Measured 2026-09-09 over 6 ultradeep runs in three repos: 362–507 min wall-clock vs 131–164 min for deep, at similar output-token volume — use only with a named research question.
 - **Budgets are deliberately not implemented yet** (PRD § 7): no `ultradeep.max-*` key is read anywhere. Do not invent one; the PRD defers thresholds until three runs have been measured.
 
 > **Not read from Session Config.** There is deliberately no `session-type:` (or equivalent) key in the `## Session Config` block — `scripts/lib/config.mjs` `parseSessionConfig()` does not emit one, so any such key in a repo's CLAUDE.md (or its Codex CLI equivalent AGENTS.md) is inert prose. The `session-type:` scalar that IS live lives in STATE.md frontmatter (read by `scripts/print-applicable-rules.mjs` for rule mode-gating) and is written per session, not configured per repo. Do not reintroduce a Session Config key here without wiring it into the parser first.

package/commands/ux-grill.md

@@ -0,0 +1,51 @@
+---
+description: Grill a running web app's UX — a deterministic mechanical pass (axe, target size, overflow, journeys) followed by a screenshot-grounded interrogation of the operator.
+argument-hint: "[url | manifest-path]"
+---
+
+# UX-Grill
+
+Invokes the `ux-grill` skill (`skills/ux-grill/SKILL.md`). Stufe 1 measures a running loopback build route-by-route and viewport-by-viewport without any model judgment, writing `findings.jsonl` plus screenshots under `.orchestrator/metrics/ux-grill/<run-id>/` <!-- path-check: example -->. Stufe 2 then grills the operator journey by journey — one question per journey finding, every claim carrying a screenshot path. The user invoked `/ux-grill` with arguments: **$ARGUMENTS**
+
+## Argument Validation
+
+Parse `$ARGUMENTS` before anything else. Exactly one positional argument is recognised:
+
+- **An absolute `http(s)` URL** (e.g. `http://127.0.0.1:3100`) → bootstrap path. The target repo has no manifest yet; the skill asks for the env names, crawls the navigation and writes one. The URL must be loopback — anything else is refused before a browser starts.
+- **A file path** (ends in `.md`, or resolves to an existing file) → treat it as the manifest path, repo-relative to the target repo.
+- **Empty** → the manifest at `DEFAULT_MANIFEST_PATH` (`.orchestrator/ux-manifest.md` <!-- path-check: example -->). If that file does not exist, say so and name the bootstrap form `/ux-grill <url>` — do not invent a manifest from nothing.
+- **Anything else** → stop with: `ux-grill: argument must be a loopback URL or a manifest path (default .orchestrator/ux-manifest.md)`.
+
+Examples:
+- `/ux-grill` — runs against the target repo's existing manifest
+- `/ux-grill http://127.0.0.1:3100` — first run: AUQ for env names, crawl, write the manifest, stop with a fill-in hint
+- `/ux-grill .orchestrator/ux-manifest.md` — explicit manifest path
+
+## Behavior
+
+1. **Phase 0 — Target + Stufe 1** — resolve the argument, bootstrap or `loadManifest()`, run the mechanical pass as one coordinator-direct Bash call, then compare against the last run with the same `manifest_hash`.
+2. **Phase 1 — Journey map** — understand / decide / act / recover per journey step, from the step screenshots; mechanical findings tabled per route.
+3. **Phase 2 — Grill loop** — at most one `AskUserQuestion` per JOURNEY finding, option 1 `(Recommended)` with its cost, screenshot path in the description.
+4. **Phase 3 — Recap** — resolved decisions, contradictions between screens (the primary output), open questions, mechanical counts including everything skipped.
+5. **Phase 4 — Hand-off** — AUQ: audit dossier in the target repo, vault note, issues only, or done.
+
+## No CI, no HARD-GATE
+
+Stufe 1 is built CI-shaped (deterministic, exit-coded, LLM-free) but is deliberately not wired into any pipeline — the PRD's dose argument. `/ux-grill` gates nothing: it writes measurement artefacts, an optional dossier and — only through `reconcile.mjs` <!-- path-check: planned #1327 --> — issues. It never commits, never pushes, never edits product code.
+
+## When to use vs. /test and /grill
+
+| Situation | Use |
+|-----------|-----|
+| A running web app's UX and journeys need measuring and interrogating | `/ux-grill` |
+| A CI-shaped end-to-end run with driver + `ux-evaluator` over an existing profile | `/test` |
+| A plan, PRD or design needs stress-testing before any build | `/grill` |
+| Per-wave design drift against the design source | `design-reviewer` (SO#1300) |
+
+## Related
+
+- `skills/ux-grill/SKILL.md` — full skill specification (phases, budgets, hand-off)
+- `skills/ux-grill/rubric-v2.md` — check catalogue, severity table, skip reasons
+- `templates/_shared/ux-manifest.template.md` — the manifest a target repo commits
+- `skills/test-runner/SKILL.md` — severity routing and batched AUQ triage, adopted here
+- `.claude/rules/ask-via-tool.md` — AUQ usage convention (AUQ-001..006)