session-orchestrator 3.23.0 → 4.0.0

package/NOTICE

@@ -21,20 +21,25 @@ at the commit above:
     skills/architecture/LANGUAGE.md
     skills/architecture/DEEPENING.md
     skills/architecture/INTERFACE-DESIGN.md
-    skills/domain-model/CONTEXT-FORMAT.md
-    skills/domain-model/ADR-FORMAT.md
+    skills/architecture/references/CONTEXT-FORMAT.md
+    skills/architecture/references/ADR-FORMAT.md
 
   Adapted SKILL.md files (description and frontmatter re-tuned for our
   trigger conventions; process body and structural content preserved):
     skills/architecture/SKILL.md
       (from improve-codebase-architecture/SKILL.md)
-    skills/domain-model/SKILL.md
-      (from domain-model/SKILL.md)
+    skills/architecture/references/domain-model.md
+      (from domain-model/SKILL.md; merged into skills/architecture/ as a
+      reference doc in 4.0.0 — the former skills/domain-model/ directory
+      is gone)
     skills/ubiquitous-language/SKILL.md
       (from ubiquitous-language/SKILL.md)
+      (removed in 4.0.0; attribution retained for the history of the
+      vendored content)
 
-Each adapted SKILL.md carries `derived-from: mattpocock/skills@90ea8ee`
-and `license: MIT` in its YAML frontmatter for traceability.
+Each adapted file still present in this repository carries
+`derived-from: mattpocock/skills@90ea8ee` and `license: MIT` in its YAML
+frontmatter for traceability.
 
 The MIT License notice from the upstream project is reproduced below in
 satisfaction of the "above copyright notice and this permission notice

package/README.md

@@ -1,21 +1,29 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.23.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-4.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-12%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
+[![Tests](https://img.shields.io/badge/tests-vitest-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
-Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on **Claude Code, Codex CLI, Cursor, and [Pi](docs/pi-setup.md)**.
+Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on **Claude Code, Codex CLI, Cursor IDE, and [Pi](docs/pi-setup.md)**, as a community plugin (MIT, community-maintained) for solo devs and small teams.
 
-The same skills and commands run across all four, with platform-adapted hooks and enforcement (see [Platform support](#platform-support)). Community plugin (MIT, community-maintained) for solo devs and small teams.
+The same skills and commands are available on all four harnesses; **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)).
 
-## Install
+## 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/). |
+| **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. |
+| **OS** | macOS and Linux are first-class and run in CI (`ubuntu-latest`, `macos-latest`). Windows is **not** covered by CI and has not been tested natively — treat it as best-effort. The Node core is portable (paths via `path.join`, tmp via `os.tmpdir()`), but `hooks/hooks.json` invokes hook commands via `sh` (see line 14) and the optional MCP server (`scripts/mcp-server.sh`) is a Bash script that needs `jq` on `PATH` — both need WSL or Git Bash on Windows. |
+| **Git** | A git repository. Session-orchestrator reads git state at every session start and commits at close. |
 
-> **Prerequisite:** Node.js 24 or later (`node --version`). v3.x runs as ES modules and needs a real Node runtime. [Install Node.js](https://nodejs.org/).
+## Install
 
 | Platform | Install |
 |---|---|
-| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry` (run both inside Claude Code). Also listed on the official community catalog: `/plugin install session-orchestrator@claude-community` (that catalog can lag HEAD). |
+| **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` |
@@ -28,33 +36,40 @@ SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*'
 cd "$SO_DIR" && npm install
 ```
 
-If `SO_DIR` comes back empty, the plugin is not installed from a marketplace — check
-`/plugin list` inside Claude Code first.
+If `SO_DIR` comes back empty, the plugin is not installed from a marketplace — check `/plugin list` inside Claude Code first.
 
 Setup guides: [Codex](docs/codex-setup.md) · [Cursor IDE](docs/cursor-setup.md) · [Pi](docs/pi-setup.md). Per-IDE notes on `CLAUDE.md` vs `AGENTS.md`: [instruction-file-resolution](skills/_shared/instruction-file-resolution.md).
 
-## What makes it different
-
-- **Verification gates** — every wave ends at a typecheck/lint/test gate; a confidence-filtered session-reviewer catches regressions between waves, not only at the end.
-- **Wave orchestration** — five typed roles (Discovery → Impl-Core → Impl-Polish → Quality → Finalization), parallel subagents inside each wave, not one big batch.
-- **Persistent memory & learnings** — `STATE.md` survives crashes and resumes the next session; `/evolve` extracts confidence-scored patterns across sessions, nothing hidden.
-- **Multi-harness** — the same skills and commands run on Claude Code, Codex CLI, Cursor IDE, and Pi, with platform-adapted hooks and enforcement.
-
-## A session in three commands
+## Upgrade
 
 ```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
-/close              # verify every item, commit cleanly, file carryover issues for the rest
+/plugin update session-orchestrator@kanevry     # Claude Code
 ```
 
-That is the whole loop. `/plan` and `/evolve` extend it (see [Lifecycle](#lifecycle-at-a-glance)), but you can start with just these three.
+Restart the harness afterwards, and re-run `npm install` in the plugin directory when the release adds dependencies. On Codex CLI, Cursor, and Pi the upgrade is `git pull` in your clone followed by the same install script you originally ran.
+
+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).
+
+## 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)). On Cursor and Pi, 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:
+
+- `.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`
+
+Deleting `.orchestrator/metrics/` deletes your session history. Nothing is sent anywhere without your explicit consent (see [Data & telemetry](#safety--data--telemetry)) — the one exception is the session-start update check (`scripts/lib/plugin-update-banner.mjs`): a single anonymous `GET` to the npm registry, at most once per day per repo, comparing your installed version against the latest release. Set `SO_DISABLE_UPDATE_CHECK=1` (or `DO_NOT_TRACK=1`) to turn it off. Beyond that, there is nothing else to revoke.
 
 ## Quick Start
 
-Run `/bootstrap` in your project repo first — it 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.
 
-Add a `## Session Config` section to your project's `CLAUDE.md` (Claude Code and Cursor IDE) or `AGENTS.md` (Codex CLI and 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
@@ -68,37 +83,49 @@ persistence: true
 enforcement: warn
 ```
 
-Everything else is opt-in. See [`docs/session-config-template.md`](docs/session-config-template.md) for the full template and [`docs/session-config-reference.md`](docs/session-config-reference.md) for the canonical type and default reference.
+Everything else is opt-in. Full template: [`docs/session-config-template.md`](docs/session-config-template.md). Canonical types and defaults: [`docs/session-config-reference.md`](docs/session-config-reference.md).
 
-## What you get
+**3. What the first `/session` writes into your repo.** Nothing outside these paths, all plain text, all local:
+
+```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/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
+.claude/STATE.md                    # wave progress and deviations (harness-specific directory)
+```
+
+## 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
+/close              # verify every item, commit cleanly, file carryover issues for the rest
+```
+
+That is the whole loop. `/plan` and `/evolve` extend it, but you can start with just these three.
 
-- **48 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, audits, and more
-- **28 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …)
-- **15 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …)
-- **10 hook event types** enforcing scope, blocking destructive commands, gating templates-first, capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged on the other platforms ([Platform support](#platform-support))
-- **10,000+ vitest tests** run on every commit ([telemetry methodology](docs/telemetry/telemetry-claims.md))
+## Lifecycle and waves
 
-Full component inventory: [`docs/components.md`](docs/components.md).
+![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)
 
-## Lifecycle at a glance
+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:
 
 ```mermaid
 flowchart TD
-    A["/plan [feature|retro]"] -->|optional, defines WHAT| B["/session [type]"]
+    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
 ```
 
-`/plan` is optional — you can create issues manually and jump straight to `/session`. `/evolve` runs deliberately after 5+ sessions, not automatically.
-
-## 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 five typed waves with verification gates between them.
-
 ```mermaid
 flowchart LR
     W1["1·Discovery<br/>read-only audit"] --> G1{Gate}
@@ -112,11 +139,19 @@ flowchart LR
     style G4 fill:#d29922,color:#000
 ```
 
+`/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.
+
+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`.
+
+## 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.
+
 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 five 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.
+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.
 
@@ -124,68 +159,65 @@ Two complementary commands round out the loop: **`/plan`** runs *before* a sessi
 
 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-06 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`)
+- **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`)
+- **26 always-on rule files** and **18 ADRs** carrying the reasoning behind the mechanisms (`ls .claude/rules/*.md | wc -l`, `ls docs/adr/*.md | wc -l`)
+- **661 vitest test files** run on every commit — 13,962 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`)
+
+**Portable across harnesses by construction.** The repo ships a root `AGENTS.md` generated byte-identical from `CLAUDE.md`, a root `plugin.json` following the [agent-plugins.org](https://agent-plugins.org) 1.0.0 schema, and a `.agents/skills/<name>/SKILL.md` mirror of all 43 skills carrying spec-legal frontmatter plus a pointer body. All three are generated by `scripts/generate-agents-skills.mjs` and drift-checked in `scripts/validate-plugin.mjs` — never hand-edited.
+
+Full component inventory: [`docs/components.md`](docs/components.md). Version history and per-release detail: [CHANGELOG.md](CHANGELOG.md).
+
 ## Why this design
 
-- **Five 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 — not only at the end — stops a bad pattern from propagating into later work; the confidence floor filters speculative criticism so only high-signal findings reach you.
+- **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.
-- **Hooks enforce, not just warn.** A pre-Bash guard blocks destructive shell commands, and pre-Edit scope enforcement blocks writes outside an agent's allowed paths — in main sessions and subagent waves alike (specifics in [Safety](#safety)). This hard enforcement is full on Claude Code; Cursor and Pi reach it through payload bridges; Codex is still pending a real `apply_patch` adapter (see [Platform support](#platform-support)).
+- **Hooks enforce, not just warn.** A pre-Bash guard blocks destructive shell commands, and pre-Edit scope enforcement blocks writes outside an agent's allowed paths — in main sessions and subagent waves alike ([Safety](#safety--data--telemetry)).
+- **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`](.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.
 
-## Recent highlights (v3.23.0)
+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).
 
-Every release is additive and backward-compatible. Highlights of the v3.23.0 line: the first shaped by three external bug reports on the public mirror (Kanevry#64, #65, #66), all three reproduced, fixed and live-verified:
+## Recent highlights (v4.0.0)
 
-- **Codex CLI mints UUIDv7 session ids; every reader accepted only v4 (#66 / #1091)** — each SessionStart minted a fresh v4, so a resumed or compacted thread read its own lock as a foreign session. `parseSessionId` now accepts RFC 9562 versions 1–8 and the stop/end hooks apply the writer's rule, so one id owns the lock from start through release. The `UUID_V4_RE` alias is gone: zero importers, and a name that said v4 while matching v1–8.
-- **Every `/close` wrote 0 of 5 recommendation fields (#65 / #1036)** — the documented Phase 3.7a call passed `undefined` where a repo root is required, and the fail-open catch hid it on every run. The snippet binds the root; the catch now names the cause. A second defect found while verifying the fix: backticks in a comment inside a `node -e "…"` string made bash execute `undefined` on each close.
-- **Codex copies a marketplace plugin and starts the MCP child with no plugin-root variable (#64)** — measured: the copy lives under `~/.codex/plugins/cache/<marketplace>/session-orchestrator/<version>/`, and from a non-git cwd the launcher resolved to `/scripts/mcp-server.sh`. `.mcp.json` and `plugin-root.mjs` gained a cache-scan tier with a name-matched `package.json`, and `.mcp.json` now mirrors the module's tier order under two drift tests. Existing installs need a reinstall — Codex snapshots `.mcp.json` at install time.
-- **Worktree-Auto-Promotion is a process boundary, not a live migration (#1069, ADR-0013)** — the source session deregisters and releases its lock before the new worktree's session acquires (`leaveSourceRoot()`), which removes the phantom peer that stayed visible for up to 60 minutes. Because the new session's id never equals the worktree suffix, Phase 4a cleanup keys on a promotion marker written at creation time; the review panel found that key dead before any user did.
-- **The host registry contributed nothing to session numbering (#1066)** — the census projected only raw UUIDs, which the n-increment discards. It now counts `semantic_session_id`, so two sessions on one host cannot mint the same label. The semantic id stays a best-effort label; ownership remains the raw id plus owner proof.
-- **The mode selector scored a field no record carries (#1071)** — `completion_rate` sits under `effectiveness` in all 281 ledger records; the flat read was always `undefined`, so the high-completion bonus was unreachable and the fixtures pinned a shape production never writes. Fixed with a nested-first read and a divisor test for the 99 records that carry no rate at all.
-- **Semgrep regained two rules a path filter had dropped (#1129)** — re-aimed at this repo's real trust boundary (hook stdin, child-process stdout), taint-mode; the first true positives were three unguarded `JSON.parse` calls on `glab`/`gh` output in the CI banner. A proposed spread-sink was refused with a measurement: object spread cannot pollute a prototype.
+v4.0.0 is the first release that REMOVES public surfaces, so read [docs/migration-v4.md](docs/migration-v4.md) before upgrading. Highlights of the v4.0.0 line: less surface, an instruction layer that loads on demand, and three instruments that were reporting numbers nobody could reproduce:
 
-Previous line (v3.22.0): instruments that confidently measured the wrong quantity — the 99%-firing resource warning, the AUQ audit, and the lock-release identity split.
+- **Five skills, three commands and eight top-level scripts are gone.** Removal followed a measured two-signal rule — 0 telemetry ∧ 0 fleet invocation over 90 days ∧ no runtime consumer — never a judgement call. Prose-invoked skills, which register 0 by construction, were exempt. `skills/domain-model/` was merged into `skills/architecture/` rather than dropped.
+- **`.claude/rules/` goes 61 → 26 files.** Forty-three machine-generated learning files were consolidated into eight thematic ones, each keeping its provenance markers so the reconcile engine still dedupes on them.
+- **The three largest instruction files are split, not shortened.** `session-start`, `session-end` and the wave loop keep every phase; the bodies move into per-phase files under `references/`, and the top-level file becomes an index that is heading-complete against the original. Nothing was summarised away.
+- **`ultradeep` is a profile over `deep`, not a fourth session type.** Seven waves with a blocking synthesis gate and a read-only review panel. Downstream tooling still sees `deep`, which is why it costs about eight touchpoints instead of forty-eight.
+- **A session-start banner now says when the plugin you are RUNNING is behind the one published** (minor or major; patch-only updates stay silent). This host had been running a copy five minors old for four weeks with no warning, because nothing anywhere compared installed against available.
+- **Two instruments were corrected rather than tuned.** Telemetry attributed the operator's own second machine to the external fleet, and the abandoned-session rate was an artefact of backfilled records. Both now report what they measure.
+- **A root `AGENTS.md`, a root `plugin.json` and a portable `.agents/skills/` mirror.** The repo now speaks the cross-harness instruction conventions it documents, generated and validated rather than hand-maintained.
 
-Full version history: [CHANGELOG.md](CHANGELOG.md).
-
-## Comparison
-
-| Capability | Session Orchestrator | Manual `CLAUDE.md` | Other orchestrators |
-|---|---|---|---|
-| Session lifecycle (start → plan → execute → close) | Full, automated | Manual | Partial |
-| Typed waves with quality gates | 5 roles, progressive verification | None | Batch execution |
-| Session persistence and crash recovery | `STATE.md` plus memory files | None | Partial |
-| Scope and command enforcement hooks | PreToolUse with strict / warn / off | None | None |
-| Circuit breaker and spiral detection | Per-agent, with recovery | None | Partial |
-| Cross-session learning | Confidence-scored learnings | None | None |
-| VCS integration (GitLab + GitHub) | Dual, auto-detected | Manual CLI | Usually GitHub only |
-| Session close with carryover | Verified, with issue creation | Manual | Partial |
-
-The design goal is engineering quality: every wave exits verified, every unfinished issue gets a carryover ticket, every session closes with a clean commit. A detailed head-to-head vs. [maestro-orchestrate](https://github.com/josstei/maestro-orchestrate) is in [`docs/components.md`](docs/components.md#comparison-vs-maestro-orchestrate).
+Full list, with the evidence for each claim: [CHANGELOG.md](CHANGELOG.md).
 
 ## Platform support
 
 | Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
 |---|---|---|---|---|
-| All 28 commands | Native slash commands | Native plugin commands | Native `.cursor/commands` slash commands | Prompt templates |
+| All 25 commands | Native slash commands | Native plugin commands | 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 |
 | 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 and adaptation live in `scripts/lib/platform.mjs`. **OS:** macOS and Linux are first-class and run in CI (`ubuntu-latest`, `macos-latest`). Windows runs natively (all paths via `path.join`, tmp via `os.tmpdir()`) but is **not** covered by CI — treat it as best-effort and run smoke tests locally when changing OS-sensitive code. 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 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).
 
-## Troubleshooting
+## Safety & data & telemetry
 
-**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. The full decision tree is in [`docs/codex-setup.md`](docs/codex-setup.md#troubleshooting).
+**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)).
 
-**"'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 (`/opt/homebrew/bin`), nvm, volta, or asdf can be invisible to hooks even though `node` works fine 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 when nothing is found: 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.
-
-## Safety
-
-`hooks/pre-bash-destructive-guard.mjs` blocks destructive shell commands (`git reset --hard`, `rm -rf`, `git push --force`, and more) in the main session *and* in subagent waves. Policy lives in `.orchestrator/policy/blocked-commands.json`. Bypass per session only for intentional maintenance:
+**Destructive-command guard.** `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. Bypass per session only for intentional maintenance:
 
 ```yaml
 allow-destructive-ops: true
@@ -193,6 +225,16 @@ allow-destructive-ops: true
 
 The rule source of truth is [`.claude/rules/parallel-sessions.md`](.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`.
+
+## 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.
+
+**`/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
 
 ```bash
@@ -207,7 +249,7 @@ npm run typecheck # node --check on every .mjs file
 
 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/`](.claude/rules/) is this repo's own always-on rule set.
 
-Contributor docs: [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [agent authoring spec](agents/AGENTS.md).
+Contributor docs: [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [sub-agent authoring spec](docs/agent-authoring.md).
 
 ## Support & scope
 
@@ -220,18 +262,16 @@ 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.
-- **Local by default.** Runs locally — no account required. Optional, strictly opt-in anonymous usage telemetry (off until you consent; see [docs/telemetry.md](docs/telemetry.md)).
-- **No guarantee that telemetry numbers transfer to your repo.** Reported test counts and metrics describe *this* repository under its own conditions ([details](docs/telemetry/telemetry-claims.md)). Your results will vary by stack, project size, and configuration.
+- **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; what moved to the private Meta-Vault and why
+- [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 v3](docs/migration-v3.md) — upgrade path from v2.x, known issues, rollback
-- [Telemetry](docs/telemetry.md) — what the optional opt-in usage telemetry collects, and how to turn it off
-- [Telemetry claims](docs/telemetry/telemetry-claims.md) — how reported metrics are measured, and why they may not transfer
+- [Migration guide](docs/migration-v3.md) — upgrade path, known issues, rollback
+- [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](docs/examples/) — Session Config examples for Next.js, Express, Swift
 - [CHANGELOG.md](CHANGELOG.md) — version history
 
@@ -239,16 +279,11 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/) — see [
 
 ## Learn the method behind it
 
-This plugin is a methodology turned into code. If you want 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 — those playbooks are taught hands-on at **[agenticbuilders.at](https://agenticbuilders.at)**:
-
-- **[Multi-Agent Orchestration](https://agenticbuilders.at/orchestrierung)** — leading several agents in coordinated waves: when parallelism pays, briefing subagents cleanly, turning failures into firm gates.
-- **[Loop Engineering](https://agenticbuilders.at/loop-engineering)** — designing autonomous loops that finish verifiably: done-conditions, verification gates, kill-switches.
-
-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 — 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.
 
 ## Links
 
-- [Homepage](https://session-orchestrator.com) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy)
+[Homepage](https://session-orchestrator.com) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy) · [npm](https://www.npmjs.com/package/session-orchestrator)
 
 ## License
 

package/agents/db-specialist.md

@@ -93,7 +93,6 @@ Append a fenced ```json block at the end of your response per `agents/schemas/db
 ```
 
 Required: `status`, `task_id`, `files_changed`, `blockers`. Optional: `verdict`. **Emit `verdict` alongside `status` (status→verdict mapping: done→PROCEED, partial→PROCEED_WITH_FOLLOWUPS, blocked→BLOCKED). `status` is deprecated and will be removed in v4.0 (#472).** The coordinator parses the LAST fenced ```json block.
-```
 
 ## Edge Cases
 

package/agents/eval-judge.md

@@ -25,7 +25,7 @@ blended into the deterministic five-dimension tally and **never** produce or
 feed a global/overall score — they are visibly separated, advisory verdicts a
 reader can discard and still have a complete deterministic evaluation.
 
-> **Color rationale (AGENTS.md exception (b) — mutually-exclusive phase):** this
+> **Color rationale (`docs/agent-authoring.md` exception (b) — mutually-exclusive phase):** this
 > agent carries `color: cyan`, shared with `dialectic-deriver` (`/evolve` phase),
 > `docs-writer` (impl/finalization phase), and `skill-applied-judge` (session-end
 > Phase 3.6.6). This judge runs **solo**, dispatched coordinator-side during the

package/agents/skill-applied-judge.md

@@ -22,7 +22,7 @@ gates any action** — not a sunset decision, not a C2 repair, not a promotion.
 Per #645 R9(b) the C2 repair gate stays deterministic; your judgment is a signal
 for humans and dashboards, not a control input.
 
-> **Color rationale (AGENTS.md exception (b) — mutually-exclusive phase):** this
+> **Color rationale (`docs/agent-authoring.md` exception (b) — mutually-exclusive phase):** this
 > agent carries `color: cyan`, shared with `dialectic-deriver` (`/evolve` phase)
 > and `docs-writer` (impl/finalization phase). The judge runs **solo** at
 > session-end Phase 3.6.6 and never co-runs in a dispatch wave, so the shared

package/assets/wave-lifecycle.svg

@@ -0,0 +1,98 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1062 372" width="1062" height="372" role="img" aria-labelledby="wl-title wl-desc" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
+  <title id="wl-title">Session Orchestrator wave lifecycle</title>
+  <desc id="wl-desc">Flow diagram. Precondition: /bootstrap runs once per repository, then /session agrees the scope, then /go executes. /go runs five typed waves left to right: 1 Discovery (read-only audit), gate G1, 2 Impl-Core (primary code), gate G2, 3 Impl-Polish (integration and edge cases), gate G3, 4 Quality (simplification pass, then tests), gate G4 Full Gate, 5 Finalization (commit and close). Gates G1 to G3 are Quality-Lite (typecheck, lint, test); G4 is the Full Gate and additionally runs the full suite plus a debug-artifact scan. After wave 5, /close verifies every planned item, runs the Full Gate, files carryover issues, commits, and writes the session record.</desc>
+
+  <defs>
+    <marker id="wl-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#94A3B8"/>
+    </marker>
+  </defs>
+
+  <!-- heading -->
+  <rect x="28" y="16" width="430" height="32" rx="6" fill="#1E293B"/>
+  <text x="44" y="37" font-size="14" font-weight="600" fill="#F8FAFC">Session Orchestrator — wave lifecycle and gates</text>
+
+  <!-- row A: the three commands -->
+  <rect x="28" y="68" width="196" height="48" rx="8" fill="#475569"/>
+  <text x="126" y="90" font-size="14" font-weight="600" fill="#F8FAFC" text-anchor="middle">/bootstrap</text>
+  <text x="126" y="106" font-size="11" fill="#E2E8F0" text-anchor="middle">once per repo — writes bootstrap.lock</text>
+
+  <line x1="228" y1="92" x2="248" y2="92" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+
+  <rect x="252" y="68" width="196" height="48" rx="8" fill="#1F6FEB"/>
+  <text x="350" y="90" font-size="14" font-weight="600" fill="#FFFFFF" text-anchor="middle">/session [type]</text>
+  <text x="350" y="106" font-size="11" fill="#DBEAFE" text-anchor="middle">research + Q&#38;A — agree the scope</text>
+
+  <line x1="452" y1="92" x2="472" y2="92" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+
+  <rect x="476" y="68" width="140" height="48" rx="8" fill="#1F6FEB"/>
+  <text x="546" y="90" font-size="14" font-weight="600" fill="#FFFFFF" text-anchor="middle">/go</text>
+  <text x="546" y="106" font-size="11" fill="#DBEAFE" text-anchor="middle">executes the waves</text>
+
+  <!-- /go down into wave 1 -->
+  <polyline points="546,116 546,134 93,134 93,146" fill="none" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+
+  <!-- row B: waves and gates -->
+  <rect x="28" y="150" width="130" height="76" rx="8" fill="#0F766E"/>
+  <text x="93" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">1 · Discovery</text>
+  <text x="93" y="198" font-size="11" fill="#CCFBF1" text-anchor="middle">read-only audit</text>
+  <text x="93" y="213" font-size="11" fill="#CCFBF1" text-anchor="middle">no writes</text>
+
+  <line x1="160" y1="188" x2="170" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+  <rect x="172" y="166" width="56" height="44" rx="6" fill="#64748B"/>
+  <text x="200" y="185" font-size="13" font-weight="700" fill="#FFFFFF" text-anchor="middle">G1</text>
+  <text x="200" y="200" font-size="9" fill="#F1F5F9" text-anchor="middle">lite</text>
+
+  <line x1="230" y1="188" x2="240" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+  <rect x="242" y="150" width="130" height="76" rx="8" fill="#1F6FEB"/>
+  <text x="307" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">2 · Impl-Core</text>
+  <text x="307" y="198" font-size="11" fill="#DBEAFE" text-anchor="middle">primary code</text>
+  <text x="307" y="213" font-size="11" fill="#DBEAFE" text-anchor="middle">architecture first</text>
+
+  <line x1="374" y1="188" x2="384" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+  <rect x="386" y="166" width="56" height="44" rx="6" fill="#64748B"/>
+  <text x="414" y="185" font-size="13" font-weight="700" fill="#FFFFFF" text-anchor="middle">G2</text>
+  <text x="414" y="200" font-size="9" fill="#F1F5F9" text-anchor="middle">lite</text>
+
+  <line x1="444" y1="188" x2="454" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+  <rect x="456" y="150" width="130" height="76" rx="8" fill="#3B82F6"/>
+  <text x="521" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">3 · Impl-Polish</text>
+  <text x="521" y="198" font-size="11" fill="#EFF6FF" text-anchor="middle">integration</text>
+  <text x="521" y="213" font-size="11" fill="#EFF6FF" text-anchor="middle">edge cases</text>
+
+  <line x1="588" y1="188" x2="598" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+  <rect x="600" y="166" width="56" height="44" rx="6" fill="#64748B"/>
+  <text x="628" y="185" font-size="13" font-weight="700" fill="#FFFFFF" text-anchor="middle">G3</text>
+  <text x="628" y="200" font-size="9" fill="#F1F5F9" text-anchor="middle">lite</text>
+
+  <line x1="658" y1="188" x2="668" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+  <rect x="670" y="150" width="130" height="76" rx="8" fill="#7C3AED"/>
+  <text x="735" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">4 · Quality</text>
+  <text x="735" y="198" font-size="11" fill="#EDE9FE" text-anchor="middle">simplify first,</text>
+  <text x="735" y="213" font-size="11" fill="#EDE9FE" text-anchor="middle">then write tests</text>
+
+  <line x1="802" y1="188" x2="812" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+  <rect x="814" y="160" width="76" height="56" rx="6" fill="#D29922"/>
+  <text x="852" y="182" font-size="13" font-weight="700" fill="#1F2937" text-anchor="middle">G4</text>
+  <text x="852" y="199" font-size="10" font-weight="600" fill="#1F2937" text-anchor="middle">Full Gate</text>
+
+  <line x1="892" y1="188" x2="902" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+  <rect x="904" y="150" width="130" height="76" rx="8" fill="#238636"/>
+  <text x="969" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">5 · Finalization</text>
+  <text x="969" y="198" font-size="11" fill="#DCFCE7" text-anchor="middle">commit + close</text>
+
+  <!-- gate legend -->
+  <rect x="28" y="246" width="880" height="30" rx="6" fill="#1E293B"/>
+  <text x="44" y="266" font-size="11" fill="#CBD5E1">G1–G3 = Quality-Lite gate (typecheck · lint · test) + inter-wave session-reviewer · G4 = Full Gate (adds the full suite and a debug-artifact scan)</text>
+
+  <!-- wave 5 down into /close -->
+  <polyline points="969,228 969,296" fill="none" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
+
+  <!-- row C -->
+  <rect x="28" y="300" width="862" height="48" rx="8" fill="#334155"/>
+  <text x="44" y="321" font-size="12" font-weight="600" fill="#F8FAFC">After the last wave: every planned item is verified against evidence, the Full Gate runs once more,</text>
+  <text x="44" y="338" font-size="12" font-weight="600" fill="#F8FAFC">unfinished work becomes carryover issues, files are staged individually, the session record is written.</text>
+
+  <rect x="904" y="300" width="130" height="48" rx="8" fill="#238636"/>
+  <text x="969" y="330" font-size="14" font-weight="600" fill="#FFFFFF" text-anchor="middle">/close</text>
+</svg>

package/commands/release.md

@@ -31,8 +31,10 @@ The same reading shows the other half: the GitHub releases for 3.15/3.18/3.19/3.
 3. **Write the editorial half.** The dated `## [X.Y.Z] - YYYY-MM-DD` CHANGELOG entry, `[Unreleased]` folded, README highlights. The script does not write these; `--check` enforces them.
 4. **Preflight.** `node scripts/release.mjs --check --json` — every row green. This runs *after* step 2, never before: `--check` derives its target from `package.json`, so on the pre-bump version the registry- and tag-collision rows are red by construction.
 5. **Gate, commit, push.** Full quality gate, then commit and push to **both** remotes.
-6. **CI green — on the commit that will be published.** Not on its predecessor. A green pipeline from before step 5's commit is evidence about a different tree.
-7. **Publish.** `node scripts/release.mjs --publish` — the target-confirmed npm receipt is the irreversible boundary. Before that receipt, any failure aborts normally. After it, never rerun `--publish`: registry propagation timeout/query/wait failures are reconciliation while the script still tags, pushes `main` + tag to both remotes, handles the GitHub release, and polls the live site. If tag/push fails after the receipt, the dependent GitHub-release and site steps are skipped and the script returns structured reconciliation guidance instead. Add the GitHub release for the new tag (`gh release create`) as part of this step, not "later" — "later" is what produced the three-second backfill above.
+6. **CI green — on the commit that will be published, on BOTH platforms.** Not on its predecessor: a green pipeline from before step 5's commit is evidence about a different tree. And not on GitLab alone — `--check` carries two CI rows, `ci-green-on-head` (GitLab, via `origin`) and `ci-green-on-head-github` (the mirror). The GitLab pipeline is Linux-only; the **macOS** matrix leg exists solely in `.github/workflows/test.yml`, i.e. on the operator's own platform. The github row self-disables (`skipped — no github remote`) in a checkout without a mirror, and fails on `unknown`/`degraded` exactly like the GitLab one — "could not read the mirror" is not "the mirror is green".
+7. **Publish.** `node scripts/release.mjs --publish` — **give it ≥600 s of wall clock, or run it in the background.** The script sets no spawn timeout on purpose (a kill mid-`npm publish` or mid-push is the very failure the receipt boundary exists to avoid), and the tail is slow by construction: each of the two `git push` remotes re-runs the husky pre-push full gate, plus up to 120 s of live-site polling. A 3-minute default command timeout kills it mid-tail.
+
+   The target-confirmed npm receipt is the irreversible boundary. Before that receipt, any failure aborts normally. After it, never rerun `--publish`: registry propagation timeout/query/wait failures are reconciliation while the script still tags, pushes `main` + tag to both remotes, handles the GitHub release, and polls the live site. If tag/push fails after the receipt, the dependent GitHub-release and site steps are skipped and the script returns structured reconciliation guidance instead. Add the GitHub release for the new tag (`gh release create`) as part of this step, not "later" — "later" is what produced the three-second backfill above.
 
 Steps 2–7 are one continuous act. A release left parked between step 5 and step 7 is exactly the `3.18.0` state: every surface says released, the registry disagrees.
 
@@ -45,7 +47,8 @@ Steps 2–7 are one continuous act. A release left parked between step 5 and ste
 | Any red row in `--check` | The preflight is the gate. A red row is a fact about this tree, not a formality. |
 | `github/main` behind `origin/main` or `HEAD` | The mirror carries the site deploy and the GitHub release. Publishing over a lagging mirror is how the site falls a release behind. |
 | `npm whoami` returns nothing or non-zero | The token is dead or absent. Publishing proceeds far enough to fail loudly *after* surfaces are committed. |
-| CI not green on the exact commit being published | Green-on-the-previous-commit is the silent-regression class this repo exists to catch. |
+| CI not green on the exact commit being published (`ci-green-on-head`) | Green-on-the-previous-commit is the silent-regression class this repo exists to catch. |
+| GitHub mirror CI not green (`ci-green-on-head-github`) | The GitLab pipeline is Linux-only; the macOS matrix leg runs only on the mirror, and macOS is the operator's own platform. An `unknown`/`degraded` reading stops the release too — it means the mirror was never read. Only a checkout with no `github` remote passes this row, as `skipped`. |
 | `--skip-ci` together with `--publish` | **Refused by the script** (`validateFlags`), not merely discouraged. `--skip-ci` marks the CI row green without checking anything; a green tick that verified nothing must never authorise an irreversible publish. It is an inspection aid for `--check`, never a release path. |
 | Working tree dirty, or not on `main` | The published tarball would not correspond to any pushed commit. |