session-orchestrator 3.19.0 → 3.21.0

package/README.md

@@ -1,7 +1,7 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.19.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.21.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)
 
@@ -23,10 +23,14 @@ The same skills and commands run across all four, with platform-adapted hooks an
 For Claude Code, also install Node dependencies **once** (hooks import `zx`) and restart Claude Code:
 
 ```bash
-cd "$(claude plugin dir session-orchestrator 2>/dev/null || echo ~/.claude/plugins/session-orchestrator)"
-npm install
+# Claude Code has no `plugin dir` subcommand, so resolve the install path from the cache.
+SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
+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.
+
 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
@@ -127,17 +131,18 @@ The system is markdown-driven config plus a thin Node runtime — skills, comman
 - **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.19.0)
+## Recent highlights (v3.21.0)
 
-Every release is additive and backward-compatible. Highlights of the v3.19.0 line:
+Every release is additive and backward-compatible. Highlights of the v3.21.0 line:
 
-- **Destructive-command guard, hardened in depth** — wrapper unwrapping (`sudo`/`doas`/`env`/`nohup`/`timeout`/`nice`/`stdbuf`, with depth-capped `-c` payload recursion) closes six measured bypasses (#982); the blocked-commands policy becomes a floor ∪ overlay model that can only escalate, never weaken (#972); shell redirects gain a target denylist — an `&>` redirect into a protected instruction file was a silent allow-with-truncation before (#983); and the denylist now resolves absolute paths, not just repo-relative ones.
-- **Session identity with proof** — the session lock persists an owner proof at genesis, so an ending session can no longer release a living foreign lock, and the abandoned-session backfiller no longer deletes the very alarm it exists to raise (#987, #926, #914).
-- **Supply chain** — two high-severity transitive vulnerabilities that `npm audit fix` could not reach are closed via package overrides.
-- **Release as one dispatch** — `scripts/release.mjs` (#978, local half): a single surfaces table drives version rewrite and preflight (12 version literals across 10 files, CHANGELOG gate, tag/registry collision, drift sweep over all tracked files, CI-green-on-HEAD, leakage gate), and the git tag is created only AFTER a verified npm publish. Found two real gaps on its first run: v3.18.0 had been tagged but never published to npm, and the hidden `.codex-plugin` manifest was invisible to a plain ripgrep census.
-- **session-orchestrator.com redesigned** — terminal hero, wave pipeline, leaderboard shell.
+- **The site that proves its own numbers (#1043–#1046)** — the live page had served v3.19.0 against v3.20.0 in the repo for six days, all five legal paths were 404, and the `Measured` block — the honesty argument of the whole page — carried five wrong numbers. It is now generated: `scripts/site-numbers.mjs` reads **13 metrics** from the repo into `data-metric` spans, and its very first run caught three real errors, one of them the coordinator's own (`skills: page says 47, repo says 46`) and one a contract defect that would have shipped `vv3.20.0` at the next release. Deploy config moved from a dashboard into a versioned `vercel.json`. Rendered height fell to **52.4%** of the old page (10,350 → 5,428px), and mobile navigation — previously `display:none` with no hamburger — exists.
+- **The documented Claude Code install path was guaranteed broken** — `claude plugin dir` is not a subcommand; it exits 1, the fallback path does not exist, `cd` fails, `npm install` never runs, and every hook afterwards cannot find `zx`. Measured on Claude Code 2.1.235. That is the cause behind external issues #62/#63, whose reporters described the symptom — and **all four issues opened by people outside this repo are install or environment failures, not one a feature request**. The replacement was extracted from the shipped HTML, entity-decoded and executed verbatim.
+- **The scope guard shipped the instructions for its own disarmament (#1057)** — the stale-manifest denial ended on ``remove it with `rm -f <path>` ``, and that string travels in `permissionDecisionReason` into the context of the agent just denied. `rm -f` is not blocked (14 rules, only `rm-rf-destructive` bites), and with the manifest gone both allowedPaths **and** project-root containment fall. A parallel session in the same working copy received this suggestion for the live manifest of this one, and declined on an indicator rather than on knowledge.
+- **Two dead instruments, found by measuring rather than reading** — the v2 vault renderer's branch condition was **structurally false from its first commit** and matched **0 of 253** session records; the obvious fix would have been worse than the bug, because `agents` is polymorphic (210× a number, 14× an array over 599 wave objects) and a naive `??` would have written `[object Object]` into the vault. And `scanBacklog` read 50 of 89 open issues while reporting the window nowhere: `critical 0, high 10, stale 0` where the truth was `1 / 18 / 5`.
+- **Cross-session messaging is wired (Epic #1048, waves 1–2)** — a new always-on rule with CSM-001..005, and a peer-inform branch hung **below** the sibling check in the PSA decision tree so it can mask neither that branch nor the PSA-002 pause. The moat was never "peer sessions cannot talk to each other" — they demonstrably can — it is that they share one working copy, and what crosses the channel is information, never isolation.
+- **Guards that were green without biting** — the owner-leakage scanner did not read `.html` at all; admitting the class immediately found a live `U+00AD` breaking a word visibly on a legally required page. `harness-audit` category 6 awarded **2/2** outside a git repository. Six consecutive CI pipelines were red because a test depended on untracked ledger files: locally 23/23, on CI `23 tests | 23 skipped`. Each is now closed by a mechanism, and the review panel found further holes inside the fixes themselves — including one fail-open state inside the fix that was closing fail-open.
 
-Previous line (v3.18.0): panel-follow-ups and consolidation — bash-write-verify self-silencing vectors closed (#938), credential stripping at the source (#907), instruction-corpus diet 471→~440 directives, mutation-sweep-backed test consolidation.
+Previous line (v3.20.0): the memory pipeline — 233 sessions of learnings that reached no agent (#1014), agent-authored text neutralised at the render point (#1015), and a learning store made durable after 11 of 13 provenance pointers resolved to nothing (#1017).
 
 Full version history: [CHANGELOG.md](CHANGELOG.md).
 

package/agents/analyst.md

@@ -1,6 +1,6 @@
 ---
 name: analyst
-description: Use this agent for read-only PRD-quality review. Checks acceptance-criteria specificity, scope drift detection, and completeness of /plan output. <example>Context: /plan feature produced a PRD. user: "Review the PRD before /go." assistant: "I'll dispatch analyst to check acceptance-criteria specificity and scope drift before wave execution." <commentary>Analyst catches vague acceptance criteria before they cause carryover at session end.</commentary></example>
+description: 'Use this agent for read-only PRD-quality review. Checks acceptance-criteria specificity, scope drift detection, and completeness of /plan output. <example>Context: /plan feature produced a PRD. user: "Review the PRD before /go." assistant: "I''ll dispatch analyst to check acceptance-criteria specificity and scope drift before wave execution." <commentary>Analyst catches vague acceptance criteria before they cause carryover at session end.</commentary></example>'
 model: inherit
 color: yellow
 tools: Read, Grep, Glob, Bash

package/agents/architect-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: architect-reviewer
-description: Use this agent for read-only architectural audits between waves. Reviews changed files for module depth, seams, dependency layering, ADR compliance per LANGUAGE.md vocabulary. <example>Context: After Impl-Core wave shipped 8 files. user: "Audit the W2 architecture before proceeding." assistant: "I'll dispatch architect-reviewer to check module depth, seams, and adapter quality before W3." <commentary>Architect-reviewer catches design smells (shallow modules, speculative seams) earlier than Quality-Lite, which only catches lint/typecheck.</commentary></example>
+description: 'Use this agent for read-only architectural audits between waves. Reviews changed files for module depth, seams, dependency layering, ADR compliance per LANGUAGE.md vocabulary. <example>Context: After Impl-Core wave shipped 8 files. user: "Audit the W2 architecture before proceeding." assistant: "I''ll dispatch architect-reviewer to check module depth, seams, and adapter quality before W3." <commentary>Architect-reviewer catches design smells (shallow modules, speculative seams) earlier than Quality-Lite, which only catches lint/typecheck.</commentary></example>'
 model: inherit
 color: blue
 tools: Read, Grep, Glob, Bash

package/agents/code-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: code-implementer
-description: Use this agent for feature implementation, API development, refactoring, and general code changes. Handles backend logic, API routes, service layers, and cross-cutting concerns. <example>Context: Wave plan assigns a new API endpoint implementation. user: "Implement CRUD API for invoices" assistant: "I'll dispatch the code-implementer agent to build the invoice API endpoints." <commentary>Feature implementation with multiple files is the code-implementer's core strength.</commentary></example> <example>Context: Refactoring task in an implementation wave. user: "Extract shared validation logic into a utility module" assistant: "I'll use the code-implementer to extract and refactor the validation logic." <commentary>Cross-file refactoring requires systematic reading, extraction, and verification.</commentary></example>
+description: 'Use this agent for feature implementation, API development, refactoring, and general code changes. Handles backend logic, API routes, service layers, and cross-cutting concerns. <example>Context: Wave plan assigns a new API endpoint implementation. user: "Implement CRUD API for invoices" assistant: "I''ll dispatch the code-implementer agent to build the invoice API endpoints." <commentary>Feature implementation with multiple files is the code-implementer''s core strength.</commentary></example> <example>Context: Refactoring task in an implementation wave. user: "Extract shared validation logic into a utility module" assistant: "I''ll use the code-implementer to extract and refactor the validation logic." <commentary>Cross-file refactoring requires systematic reading, extraction, and verification.</commentary></example>'
 model: inherit
 color: green
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
@@ -25,7 +25,7 @@ You are a focused implementation agent. You write production code, refactor exis
 3. **Match conventions**: Match existing style for naming (camelCase vs snake_case), error patterns (typed errors vs result objects), and module structure (default vs named exports).
 4. **Implement minimally**: Touch only files in the assigned file scope. Do not refactor adjacent code that "could be cleaner" — that is out of scope unless the task explicitly says so.
 5. **Run a fast feedback loop**: After substantive edits, run the project's typecheck (`tsgo --noEmit`, `tsc --noEmit`, or the configured command) to catch type errors early. Do not run the full test suite as a routine loop — that is the Quality wave's responsibility. You MAY still run the typecheck/lint command or targeted tests to gather evidence for a `Status: done` claim (Verification gate below) — the bar is on the *routine full-suite run*, not on verifying your own scope.
-6. **Self-review the diff**: Before reporting completion, mentally walk the diff and verify each change serves the task. Delete dead branches, debug logging, and TODO stubs.
+6. **Self-review the diff — then hand it over anyway**: Before reporting completion, walk the diff and verify each change serves the task; delete dead branches, debug logging, and TODO stubs. Self-review is a precondition of handoff, never a substitute for review, and a green quality gate is not review either (`.claude/rules/receiving-review.md` § RCR-009). Never mark your own diff reviewed, however small it is.
 7. **Report**: Output a structured summary (see Output Format).
 - **Bite-sized plan**: If a bite-sized executable plan path is provided in your prompt (`docs/plans/<feature>.md`, see `skills/write-executable-plan/SKILL.md`), you own the **implement** and **verify-pass** steps of each Task's 5-step structure: write the production code, then run the Task's exact verification command. The **test-first** and **confirm-fail** steps belong to the test-writer and the **commit-stop** step to the coordinator — in this bite-sized structure the test is authored ahead of you, and you never run git-write operations (see Rules below), so do not attempt those three steps yourself. (Outside a bite-sized plan, a need-gated regression test for a bug you fix IS yours — see Rules.)
 - **Bugfix prerequisite**: For bugfix-classified tasks: reference an existing `.orchestrator/debug/<session>-<n>.md` Phase-1 artifact (per `skills/debug/SKILL.md` Iron Law). If no artifact exists, invoke `/debug` first.
@@ -42,6 +42,8 @@ You are a focused implementation agent. You write production code, refactor exis
 - Do NOT use destructive operations (`rm -rf`, `git reset --hard`, `git clean`). Stick to Edit/Write — the git-write ban above (PSA-007) already covers `git reset`/`git clean`'s VCS-specific forms.
 - **Verification gate**: Apply `.claude/rules/verification-before-completion.md` Gate Function before every `Status: done` claim — quote the verification command output inline, never claim "should pass" or "looks correct" without evidence.
 - **Receiving review**: When receiving review feedback (from session-reviewer, persona reviewers, or inter-wave checks): apply `.claude/rules/receiving-review.md` 6-step pattern (READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT). No performative agreement.
+- **Refusing an instruction you can refute**: your dispatch prompt states the coordinator's assumptions as facts. When you can REFUTE one by measurement, the measurement wins — implementing a refuted instruction is the more expensive error (RCR-009). Report it as: the instruction as given, the measurement that contradicts it (command + output, call-site census, or reproduction — never a preference), and what you did instead. Put it in Blockers / Notes so the coordinator cannot miss it.
+- **Sibling sites**: when your fix's defect provably recurs elsewhere, triage it per `receiving-review.md` § RCR-007 before patching — a `same-pattern-sweep` (identical pattern, all sites in your file scope, no contract change, population enumerated by a quoted census) is fixed in this cycle; anything failing one of those four is `follow-up`, and you report the census rather than half-sweeping.
 
 ## Quality Standards
 

package/agents/db-specialist.md

@@ -1,6 +1,6 @@
 ---
 name: db-specialist
-description: Use this agent for database work — schema design, migrations, queries, indexes, and database functions. Handles SQL, ORMs, and database architecture decisions. <example>Context: New feature requires database schema changes. user: "Create the migration for the invoice tables with proper indexes" assistant: "I'll dispatch the db-specialist agent to design the schema and create the migration." <commentary>Schema design requires understanding normalization, indexing, and the existing data model.</commentary></example> <example>Context: Performance issue with database queries. user: "Optimize the slow invoice listing query" assistant: "I'll use the db-specialist to analyze and optimize the query with proper indexing." <commentary>Query optimization requires understanding execution plans, indexes, and data access patterns.</commentary></example>
+description: 'Use this agent for database work — schema design, migrations, queries, indexes, and database functions. Handles SQL, ORMs, and database architecture decisions. <example>Context: New feature requires database schema changes. user: "Create the migration for the invoice tables with proper indexes" assistant: "I''ll dispatch the db-specialist agent to design the schema and create the migration." <commentary>Schema design requires understanding normalization, indexing, and the existing data model.</commentary></example> <example>Context: Performance issue with database queries. user: "Optimize the slow invoice listing query" assistant: "I''ll use the db-specialist to analyze and optimize the query with proper indexing." <commentary>Query optimization requires understanding execution plans, indexes, and data access patterns.</commentary></example>'
 model: inherit
 color: purple
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)

package/agents/dialectic-deriver.md

@@ -1,6 +1,6 @@
 ---
 name: dialectic-deriver
-description: Use this agent when reasoning over top-N learnings + last-K sessions + existing peer cards to derive updates to USER.md / AGENT.md. Called via /evolve --dialectic mode by the evolve skill. Reads inputs, writes one fenced diff block per peer-card target. Read-only by contract — never writes files. Cheap-by-default — model haiku, bounded per-call budget. <example>Context: /evolve --dialectic invoked at session-end Phase 3.6.7. user "Run dialectic derivation against recent learnings." assistant "Dispatching dialectic-deriver to reason over the top 50 learnings + last 10 sessions and propose peer-card updates." <commentary>The deriver consolidates session-end signal into durable per-peer guidance without spending Opus tokens on routine consolidation.</commentary></example>
+description: 'Use this agent when reasoning over top-N learnings + last-K sessions + existing peer cards to derive updates to USER.md / AGENT.md. Called via /evolve --dialectic mode by the evolve skill. Reads inputs, writes one fenced diff block per peer-card target. Read-only by contract — never writes files. Cheap-by-default — model haiku, bounded per-call budget. <example>Context: /evolve --dialectic invoked at session-end Phase 3.6.7. user "Run dialectic derivation against recent learnings." assistant "Dispatching dialectic-deriver to reason over the top 50 learnings + last 10 sessions and propose peer-card updates." <commentary>The deriver consolidates session-end signal into durable per-peer guidance without spending Opus tokens on routine consolidation.</commentary></example>'
 model: haiku
 color: cyan
 tools: Read, Grep, Glob

package/agents/docs-writer.md

@@ -1,6 +1,6 @@
 ---
 name: docs-writer
-description: Use this agent when documentation needs to be generated or updated as part of a session — user-facing READMEs, dev-focused CLAUDE.md sections, or vault narratives (context.md, decisions.md, people.md). <example>Context: a feature session added a new CLI flag. user: "Update the README with the new --no-vault flag." assistant: "I'll dispatch the docs-writer agent to scan the diff and update README plus the Dev CLAUDE.md section if warranted." <commentary>Scope touches user-facing docs — docs-writer decides audience split and cites the diff.</commentary></example>
+description: 'Use this agent when documentation needs to be generated or updated as part of a session — user-facing READMEs, dev-focused CLAUDE.md sections, or vault narratives (context.md, decisions.md, people.md). <example>Context: a feature session added a new CLI flag. user: "Update the README with the new --no-vault flag." assistant: "I''ll dispatch the docs-writer agent to scan the diff and update README plus the Dev CLAUDE.md section if warranted." <commentary>Scope touches user-facing docs — docs-writer decides audience split and cites the diff.</commentary></example>'
 model: inherit
 color: cyan
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)

package/agents/memory-proposal-collector.md

@@ -1,6 +1,6 @@
 ---
 name: memory-proposal-collector
-description: Reference documentation (NOT a dispatchable agent) for the coordinator-direct AUQ rendering flow at session-end Phase 3.6.3. The coordinator collects proposals from `.orchestrator/metrics/proposals.jsonl` via `collectProposals()` and renders the multiSelect AUQ in batches of 4. Approved proposals flow to `learnings.jsonl` with `_provenance: agent-proposed@<wave-id>` via `sink.writeApproved()`. AUQ is a coordinator-only tool — this flow does NOT dispatch as a subagent. <example>Context: session-end Phase 3.6.3, proposals.jsonl contains 5 entries from W2/W3 agents. user "Close the session." assistant "I'll render the AUQ in 2 batches of 4 + 1, then route the user's choices through writeApproved + archiveRejected per agents/memory-proposal-collector.md." <commentary>The collector flow is coordinator-direct because AskUserQuestion is unavailable inside subagents per .claude/rules/ask-via-tool.md AUQ-004.</commentary></example>
+description: 'Reference documentation (NOT a dispatchable agent) for the coordinator-direct AUQ rendering flow at session-end Phase 3.6.3. The coordinator collects proposals from `.orchestrator/metrics/proposals.jsonl` via `collectProposals()` and renders the multiSelect AUQ in batches of 4. Approved proposals flow to `learnings.jsonl` with `_provenance: agent-proposed@<wave-id>` via `sink.writeApproved()`. AUQ is a coordinator-only tool — this flow does NOT dispatch as a subagent. <example>Context: session-end Phase 3.6.3, proposals.jsonl contains 5 entries from W2/W3 agents. user "Close the session." assistant "I''ll render the AUQ in 2 batches of 4 + 1, then route the user''s choices through writeApproved + archiveRejected per agents/memory-proposal-collector.md." <commentary>The collector flow is coordinator-direct because AskUserQuestion is unavailable inside subagents per .claude/rules/ask-via-tool.md AUQ-004.</commentary></example>'
 model: inherit
 color: cyan
 tools: Read, Grep, Glob

package/agents/qa-strategist.md

@@ -1,6 +1,6 @@
 ---
 name: qa-strategist
-description: Use this agent for read-only test-coverage gap analysis between waves. Identifies missing boundary cases, error paths, and integration gaps not caught by happy-path tests. <example>Context: Impl-Core shipped a new auth flow with 6 unit tests. user: "Check the test coverage gaps." assistant: "I'll dispatch qa-strategist to identify boundary cases and error-path coverage gaps before Quality wave." <commentary>QA-strategist surfaces test depth gaps the test-writer agent missed.</commentary></example>
+description: 'Use this agent for read-only test-coverage gap analysis between waves. Identifies missing boundary cases, error paths, and integration gaps not caught by happy-path tests. <example>Context: Impl-Core shipped a new auth flow with 6 unit tests. user: "Check the test coverage gaps." assistant: "I''ll dispatch qa-strategist to identify boundary cases and error-path coverage gaps before Quality wave." <commentary>QA-strategist surfaces test depth gaps the test-writer agent missed.</commentary></example>'
 model: inherit
 color: purple
 tools: Read, Grep, Glob, Bash

package/agents/security-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: security-reviewer
-description: Use this agent for security analysis — OWASP checks, authentication flows, input validation, authorization, and vulnerability assessment. Read-only analysis with actionable findings. Prioritizes high-confidence exploitable issues over theoretical ones. <example>Context: Quality wave includes security review of new endpoints. user: "Review the new API endpoints for security vulnerabilities" assistant: "I'll dispatch the security-reviewer agent to audit the new endpoints." <commentary>Security review after implementation catches auth gaps, injection risks, and missing validation.</commentary></example> <example>Context: Pre-deployment security check. user: "Run a security audit on the authentication changes" assistant: "I'll use the security-reviewer to verify the auth changes are secure." <commentary>Auth changes are high-risk — dedicated security review prevents vulnerabilities in production.</commentary></example>
+description: 'Use this agent for security analysis — OWASP checks, authentication flows, input validation, authorization, and vulnerability assessment. Read-only analysis with actionable findings. Prioritizes high-confidence exploitable issues over theoretical ones. <example>Context: Quality wave includes security review of new endpoints. user: "Review the new API endpoints for security vulnerabilities" assistant: "I''ll dispatch the security-reviewer agent to audit the new endpoints." <commentary>Security review after implementation catches auth gaps, injection risks, and missing validation.</commentary></example> <example>Context: Pre-deployment security check. user: "Run a security audit on the authentication changes" assistant: "I''ll use the security-reviewer to verify the auth changes are secure." <commentary>Auth changes are high-risk — dedicated security review prevents vulnerabilities in production.</commentary></example>'
 model: inherit
 color: red
 tools: Read, Grep, Glob, Bash

package/agents/session-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: session-reviewer
-description: Use this agent between waves or at session end to verify work quality against the session plan. Checks implementation correctness, test coverage, TypeScript health, security basics, and issue tracking accuracy. <example>Context: Impl-Core wave is complete, coordinator needs quality check before Impl-Polish. user: "Impl-Core wave done, review before continuing" assistant: "I'll dispatch the session-reviewer to verify Impl-Core outputs." <commentary>Inter-wave quality gate ensures issues are caught early, not at session end.</commentary></example> <example>Context: Session end, verifying all work before committing. user: "/close" assistant: "Running session-reviewer to verify all session work before committing." <commentary>Final quality gate before any code is committed.</commentary></example>
+description: 'Use this agent between waves or at session end to verify work quality against the session plan. Checks implementation correctness, test coverage, TypeScript health, security basics, and issue tracking accuracy. <example>Context: Impl-Core wave is complete, coordinator needs quality check before Impl-Polish. user: "Impl-Core wave done, review before continuing" assistant: "I''ll dispatch the session-reviewer to verify Impl-Core outputs." <commentary>Inter-wave quality gate ensures issues are caught early, not at session end.</commentary></example> <example>Context: Session end, verifying all work before committing. user: "/close" assistant: "Running session-reviewer to verify all session work before committing." <commentary>Final quality gate before any code is committed.</commentary></example>'
 model: inherit
 color: pink
 tools: Read, Grep, Glob, Bash
@@ -129,6 +129,41 @@ For each finding across ALL sections (1-8), assign a confidence score (0-100):
 
 Only include findings with confidence >= 80 in the main section reports. Group findings with confidence 50-79 in the "Possible Issues" section at the end of the report.
 
+## Depth and Escalation Authority
+
+Both halves below are part of the deliverable, not optional extras — `.claude/rules/receiving-review.md` § RCR-009.
+
+### Report what held, not only what broke
+
+A review that returns findings only is indistinguishable from a review that never opened the file, so the next wave opens it again. Alongside the findings, report:
+
+- **CONFIRMED** — surfaces you examined that hold. Name the surface AND what makes it hold ("the 14.3% coverage gap is tolerable: <reasons>"), never a bare list of filenames. This is the only channel through which "I looked here and it is in order" reaches the next wave.
+- **REFUTED** — suspected defects that measurably do NOT exist. Name the suspicion, the measurement that killed it, and who raised it. A suspicion the coordinator stated in your dispatch prompt is the highest-value entry of all: it is the one the next wave would otherwise re-investigate from scratch.
+
+Neither list produces findings; both remove re-work. An empty CONFIRMED list means you reviewed nothing.
+
+### You may refuse an instruction you can refute
+
+Your dispatch prompt states the coordinator's assumptions as facts. When you can REFUTE one by measurement, the measurement wins and you say so — staying in your lane and reviewing against a refuted premise is the more expensive error. Valid only in this shape:
+
+1. Restate the instruction as given.
+2. Show the measurement that contradicts it — a command with its output, a call-site census, a reproduction. Never a preference, never "this seems wrong".
+3. State what you did instead, and why it serves the instruction's intent.
+
+Escalate on your own initiative rather than staying in your lane: a defect outside the surfaces you were pointed at is still your finding, reported with its confidence score like any other. Depth is your call, not the author's.
+
+### Classify every finding, and use all four classes
+
+Label each finding with its `.claude/rules/receiving-review.md` § RCR-007 class: `in-scope-blocker`, `same-pattern-sweep`, `follow-up`, or `stop-and-escalate`. **A dispatch prompt that quotes the older three-class form is out of date, not authoritative** — the rule file is, and it carries four.
+
+`same-pattern-sweep` is the one worth naming here, because it is the class a per-finding reviewer most easily misses: the identical defect recurring at further sites, all inside the file scope, none needing a contract change. It requires all four of RCR-007's conditions — identical pattern, every site in scope, no contract change, and a population ENUMERATED by a quoted census of **call sites** (not files, and not a payload-keyed grep, which misses consumers pinning only the channel). Cannot enumerate it → report `follow-up` with the census, not a sweep.
+
+The failure it exists to catch has a name and a live instance: one site fixed with its enumerated siblings left standing. The class was added to RCR-007 on 2026-08-14 — and its own consumer list was not swept, so this file went one wave without it while the rule that forbids exactly that shipped.
+
+The same standard binds your own conduct: a defect in your OWN review process — a probe that wrote outside its scope, a measurement you later found unsound — is reported with the weight of a finding, together with its cleanup. Never quietly dropped.
+
+Evidence for both halves (2026-08-14 quality panel, 18 findings / 2 HIGH): each of the three reviewers refuted at least one coordinator claim. The architect's 10-entry CONFIRMED list and the QA strategist's 12-entry REFUTED list produced no findings at all, yet two REFUTED entries closed gaps the coordinator had explicitly suspected — re-work the next wave would otherwise have repeated. The security reviewer reproduced a HIGH that no test and no gate had surfaced (self-review and a green gate are not review), and disclosed a defect in his own probe with its full cleanup. A fix-agent refused a coordinator-specified `needleCount > 0` coupling by showing it would disable the fix in the zero-needle run — i.e. in exactly the leaking run.
+
 ## Output Format
 
 ```
@@ -161,6 +196,12 @@ Only include findings with confidence >= 80 in the main section reports. Group f
 ### Possible Issues (confidence 50-79)
 - [lower-confidence findings across all sections, for human review]
 
+### Confirmed (examined, holds)
+- [surface — what makes it hold]
+
+### Refuted (suspected, measurably absent)
+- [suspicion — the measurement that killed it — who raised it]
+
 ### Verdict: [PROCEED / FIX REQUIRED]
 [If FIX REQUIRED: list specific items that must be addressed]
 ```

package/agents/skill-applied-judge.md

@@ -1,6 +1,6 @@
 ---
 name: skill-applied-judge
-description: Use this agent at session-end Phase 3.6.6 (#645 L3) to judge — from the session transcript tail — whether each selected skill was actually APPLIED and whether its work COMPLETED. Dispatched read-only by scripts/lib/skill-judge.mjs::runSkillJudge as Haiku with a bounded per-call budget. RETURNS one fenced json block of advisory per-skill judgments; the coordinator writes them. Read-only by contract — never writes files. Advisory-only — output never gates any action. <example>Context: session-end Phase 3.6.6 with skill-evolution.judge: true. user "Judge whether the skills this session selected were actually applied." assistant "Dispatching skill-applied-judge to read the transcript tail and emit advisory applied/completed judgments for each selected skill." <commentary>The judge produces a cheap advisory signal feeding the L3 skill-judgments sidecar — never an auto-action gate.</commentary></example>
+description: 'Use this agent at session-end Phase 3.6.6 (#645 L3) to judge — from the session transcript tail — whether each selected skill was actually APPLIED and whether its work COMPLETED. Dispatched read-only by scripts/lib/skill-judge.mjs::runSkillJudge as Haiku with a bounded per-call budget. RETURNS one fenced json block of advisory per-skill judgments; the coordinator writes them. Read-only by contract — never writes files. Advisory-only — output never gates any action. <example>Context: session-end Phase 3.6.6 with skill-evolution.judge: true. user "Judge whether the skills this session selected were actually applied." assistant "Dispatching skill-applied-judge to read the transcript tail and emit advisory applied/completed judgments for each selected skill." <commentary>The judge produces a cheap advisory signal feeding the L3 skill-judgments sidecar — never an auto-action gate.</commentary></example>'
 model: haiku
 color: cyan
 tools: Read, Grep, Glob

package/agents/test-writer.md

@@ -1,6 +1,6 @@
 ---
 name: test-writer
-description: Use this agent to close NAMED test gaps and to consolidate redundant tests. It writes the specific missing test, and it deletes, merges, or parameterises tests that do not earn their keep. <example>Context: Quality wave named one concrete gap — the invoice service never exercises the declined-payment branch. user: "The invoice service has no test for a declined payment" assistant: "I'll dispatch the test-writer to add that one error-path test and run the falsification check on it." <commentary>A named gap states a bug that would ship undetected; 'improve coverage' names nothing and is not a dispatchable task.</commentary></example> <example>Context: The auth test file has 14 tests — 6 assert the same validation branch and 3 only pin prose strings. user: "Clean up the auth test file" assistant: "I'll use the test-writer to merge the 6 duplicates into one parameterised test and delete the 3 prose-pinning tests — net test count falls 14 to 6 while catch-power rises, reported as test_delta.removed plus test_delta.consolidated." <commentary>Consolidation is a success outcome: fewer tests that each catch a distinct bug beat many that catch none, and a scope with no real gap legitimately ends with status no-tests-needed.</commentary></example>
+description: 'Use this agent to close NAMED test gaps and to consolidate redundant tests. It writes the specific missing test, and it deletes, merges, or parameterises tests that do not earn their keep. <example>Context: Quality wave named one concrete gap — the invoice service never exercises the declined-payment branch. user: "The invoice service has no test for a declined payment" assistant: "I''ll dispatch the test-writer to add that one error-path test and run the falsification check on it." <commentary>A named gap states a bug that would ship undetected; ''improve coverage'' names nothing and is not a dispatchable task.</commentary></example> <example>Context: The auth test file has 14 tests — 6 assert the same validation branch and 3 only pin prose strings. user: "Clean up the auth test file" assistant: "I''ll use the test-writer to merge the 6 duplicates into one parameterised test and delete the 3 prose-pinning tests — net test count falls 14 to 6 while catch-power rises, reported as test_delta.removed plus test_delta.consolidated." <commentary>Consolidation is a success outcome: fewer tests that each catch a distinct bug beat many that catch none, and a scope with no real gap legitimately ends with status no-tests-needed.</commentary></example>'
 model: inherit
 color: orange
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)

package/agents/ui-developer.md

@@ -1,6 +1,6 @@
 ---
 name: ui-developer
-description: Use this agent for frontend implementation — UI components, pages, styling, accessibility, and responsive design. Handles React/Next.js components, CSS, and design system work. <example>Context: Implementation wave includes UI component work. user: "Build the invoice list page with filters and pagination" assistant: "I'll dispatch the ui-developer agent to implement the invoice list UI." <commentary>Frontend page implementation with interactive components is the ui-developer's specialty.</commentary></example> <example>Context: Accessibility improvements needed. user: "Fix WCAG violations in the dashboard components" assistant: "I'll use the ui-developer to audit and fix the accessibility issues." <commentary>WCAG compliance requires understanding semantic HTML, ARIA attributes, and keyboard navigation.</commentary></example>
+description: 'Use this agent for frontend implementation — UI components, pages, styling, accessibility, and responsive design. Handles React/Next.js components, CSS, and design system work. <example>Context: Implementation wave includes UI component work. user: "Build the invoice list page with filters and pagination" assistant: "I''ll dispatch the ui-developer agent to implement the invoice list UI." <commentary>Frontend page implementation with interactive components is the ui-developer''s specialty.</commentary></example> <example>Context: Accessibility improvements needed. user: "Fix WCAG violations in the dashboard components" assistant: "I''ll use the ui-developer to audit and fix the accessibility issues." <commentary>WCAG compliance requires understanding semantic HTML, ARIA attributes, and keyboard navigation.</commentary></example>'
 model: inherit
 color: magenta
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)

package/agents/ux-evaluator.md

@@ -1,6 +1,6 @@
 ---
 name: ux-evaluator
-description: Use this agent for read-only UX evaluation of test-runner driver artifacts (Playwright AX-tree snapshots, screenshots, console output). Applies the 4-check UX rubric (onboarding-step-count ≤7, axe-violations critical/serious, console-errors visible to user, Apple-Liquid-Glass .glassEffect() conformance on SwiftUI 26+) and emits structured findings JSON with stable fingerprints. <example>Context: test-runner has just produced .orchestrator/metrics/test-runs/12345-1715688000123/ax-snapshots/. user: "Evaluate UX of the dashboard flow against rubric-v1." assistant: "I'll dispatch ux-evaluator to read the AX-tree snapshots and emit findings.json per skills/test-runner/rubric-v1.md." <commentary>ux-evaluator is the only agent that translates driver-captured artifacts into reconcilable findings; it never invokes drivers itself.</commentary></example>
+description: 'Use this agent for read-only UX evaluation of test-runner driver artifacts (Playwright AX-tree snapshots, screenshots, console output). Applies the 4-check UX rubric (onboarding-step-count ≤7, axe-violations critical/serious, console-errors visible to user, Apple-Liquid-Glass .glassEffect() conformance on SwiftUI 26+) and emits structured findings JSON with stable fingerprints. <example>Context: test-runner has just produced .orchestrator/metrics/test-runs/12345-1715688000123/ax-snapshots/. user: "Evaluate UX of the dashboard flow against rubric-v1." assistant: "I''ll dispatch ux-evaluator to read the AX-tree snapshots and emit findings.json per skills/test-runner/rubric-v1.md." <commentary>ux-evaluator is the only agent that translates driver-captured artifacts into reconcilable findings; it never invokes drivers itself.</commentary></example>'
 model: opus
 color: blue
 tools: Read, Grep, Glob, Bash

package/commands/release.md

@@ -0,0 +1,60 @@
+---
+description: Cut a release — the order the steps must run in, and the criteria that abort a release
+disable-model-invocation: true
+argument-hint: "[X.Y.Z]"
+---
+
+# Release
+
+The user wants to cut a release of this package. Optional argument — the target version: **$ARGUMENTS**.
+
+**The mechanism is `scripts/release.mjs`.** It exists, it is executable, and its pure half is unit-tested (`tests/scripts/release.test.mjs`). This command carries only the two things the script cannot carry: the **order**, and the **criteria that stop a release**. Do not restate the script's internals here — `node scripts/release.mjs --help` and the file header are the reference.
+
+## Why the order is written down
+
+`3.18.0` has a git tag, a GitHub release and a CHANGELOG entry — and the npm registry never saw it; a checklist line is not a mechanism.
+
+Verify it yourself before trusting the paragraph above:
+
+```bash
+npm view session-orchestrator versions --json          # read 2026-08-19: 3.16.0, 3.17.0, 3.19.0, 3.20.0 — no 3.18.0
+git for-each-ref --format='%(refname:short) %(creatordate:short)' refs/tags
+gh release list --repo Kanevry/session-orchestrator --limit 12
+```
+
+The same reading shows the other half: the GitHub releases for 3.15/3.18/3.19/3.20 were all created on 2026-08-19 within a three-second window — 5 to 31 days after their tags. Every step that lives only in prose gets skipped and backfilled later.
+
+## The order
+
+1. **Preconditions.** Working tree clean, on `main`, and `origin/main` **and** `github/main` both level with `HEAD`. The mirror is checked because the site deploy hangs off `github`, not `origin`.
+2. **Set the version.** `node scripts/release.mjs --set-version X.Y.Z` — rewrites every version surface, syncs `package-lock.json`, re-stamps the measured census on the site.
+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` — publishes, verifies the registry, tags **after** the verified publish, pushes `main` + tag to both remotes, then polls the live site. 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.
+
+## Abort criteria
+
+Stop and report. Do not work around, do not "fix it after the publish" — an npm publish is not revocable.
+
+| Signal | Why it stops the release |
+|---|---|
+| 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. |
+| `--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. |
+
+## After
+
+`--publish` prints the remaining manual items (token rotation, async gallery indexing). Rotate the npm token — write tokens are short-lived by policy, and a token that transited a log or a chat is burned.
+
+## See Also
+
+- `scripts/release.mjs` — the mechanism; `SURFACES` and `LEAKAGE_PATTERNS` are the single sources of truth for version surfaces and the tarball leak classes.
+- `skills/npm-publish/SKILL.md` — the human decisions: which version, what a leak means, when to abort instead of repair.
+- `docs/distribution/npm-publish-checklist.md` — operator runbook and post-publish verification.

package/commands/session.md

@@ -5,9 +5,13 @@ argument-hint: "[housekeeping|feature|deep]"
 
 # Session Start
 
-You are beginning a new development session. The user has invoked `/session` with type: **$ARGUMENTS** (if empty, auto-detect from the project's `## Session Config` block or default to `feature`).
+You are beginning a new development session. The user has invoked `/session` with type: **$ARGUMENTS** (if empty, default to **`deep`**).
 
-**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. If `$ARGUMENTS` is not empty and does not match any valid type, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep." Then auto-detect from the project's `## Session Config` block or default to `feature`.
+**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. If `$ARGUMENTS` is not empty and does not match any valid type, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep." Then fall back to `deep`.
+
+> **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.
 
 ## Resume Support
 

package/docs/USER-GUIDE.md

@@ -1297,7 +1297,7 @@ No. The orchestrator never commits code until you run `/close`. During wave exec
 
 ### What happens to unfinished work?
 
-During `/close`, any work that was planned but not completed is documented. The orchestrator creates carryover issues on your VCS platform with the title prefix `[Carryover]`, including context on what was done and what remains. Nothing is silently dropped.
+During `/close`, any work that was planned but not completed is documented. The orchestrator creates carryover issues on your VCS platform with the title prefix `[Carryover]`, including context on what was done, what remains, and a mandatory Revisit-Trigger naming the condition that reopens the work. Nothing is silently dropped.
 
 ### Can I use this across multiple repos?