session-orchestrator 3.17.0 → 3.19.0

package/README.md

@@ -1,9 +1,9 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.17.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.19.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-10%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
+[![Tests](https://img.shields.io/badge/tests-12%2C000%2B-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)**.
 
@@ -127,16 +127,17 @@ 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.17.0)
+## Recent highlights (v3.19.0)
 
-Every release is additive and backward-compatible. Highlights of the v3.17.0 line:
+Every release is additive and backward-compatible. Highlights of the v3.19.0 line:
 
-- **Opt-in anonymous usage telemetry (#841)** — consent-gated client (`scripts/lib/telemetry/`) with anonymous IDs, a local queue, and record_kind-generic ingest. Off by default; nothing leaves the machine without explicit opt-in.
-- **Vault-curation probes (#831 B2/B4/B5)** — MOC-staleness banner, context-coverage line, and a candidates-only worktree-orphan sweep (never deletes — PSA-003), plus the completed abandoned-session sweep.
-- **Review-panel & gates hardening** — base-branch injection, fail-open quality gates, torn-write `jq`, vault-sync register/mode vocabulary, and enumerate scan depth fixed in one pass.
-- **npm distribution line complete** — first publish shipped (v3.16.0 on npm, #825); this line adds the `npm-publish` token-runbook skill and broadened registry metadata.
+- **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.
 
-Previous line (v3.16.0): class-wide bold-key parser fix (`matchBlockHeader`), vault-namespace de-collapse (`VAULT_CLEAR_SLUGS`), vault-board TTL self-healing, provenance-honest `/bootstrap --refresh-lock`.
+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.
 
 Full version history: [CHANGELOG.md](CHANGELOG.md).
 
@@ -196,6 +197,8 @@ npm run typecheck # node --check on every .mjs file
 
 `.npmrc` ships with `ignore-scripts=true` (supply-chain defence), so Husky git hooks don't auto-wire on install — run `npx husky` once after cloning. `git commit` then runs gitleaks → owner-privacy scan → lint-staged → commitlint. CI re-runs everything, plus more.
 
+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).
 
 ## Support & scope

package/SECURITY.md

@@ -4,8 +4,11 @@
 
 | Version | Supported |
 |---------|-----------|
-| 2.0.x-alpha | Yes |
-| 1.x | No |
+| 3.x | Yes |
+| 2.x and earlier | No |
+
+Only the latest 3.x minor receives fixes. See [CHANGELOG.md](CHANGELOG.md) for the
+current release.
 
 ## Reporting a Vulnerability
 
@@ -23,15 +26,41 @@ Please include:
 
 ## Scope
 
-Session Orchestrator is a **Claude Code plugin** composed entirely of Markdown instructions and shell scripts. It does not:
-- Run a web server or accept network connections
-- Store credentials or secrets
+Session Orchestrator is a plugin for AI coding agents (Claude Code, Codex CLI,
+Cursor, Pi), composed of Markdown instructions plus a Node ESM runtime under
+`scripts/` and `hooks/`. It requires Node 24+.
+
+What it **does** touch:
+
+- **Local filesystem** — reads/writes repo files, `.orchestrator/` runtime state,
+  and (when vault integration is enabled) a host-local vault directory under `$HOME`.
+- **Your VCS CLI** — spawns `glab` / `gh` using your existing authentication.
+- **Credentials via environment** — reads `GITLAB_TOKEN` (baseline fetch),
+  `CLANK_EVENT_SECRET` (event-bus bearer token), and `NPM_TOKEN` from a gitignored
+  `.env.local` (publish flow only). It never persists them; `CLANK_EVENT_SECRET` is
+  transmitted as a bearer token when the event bus is configured. See
+  [.env.example](.env.example).
+- **Outbound network, all opt-in and off by default** — event-bus webhook POSTs
+  (only when `CLANK_EVENT_URL` *and* `CLANK_EVENT_SECRET` are set), GitLab API
+  baseline fetches (only with `GITLAB_TOKEN`), and anonymous usage telemetry
+  (strictly opt-in, one-time consent, whitelist-projected — see
+  [docs/telemetry.md](docs/telemetry.md)).
+- **An optional self-hosted ingest server** — `server/ingest/` is a small HTTP
+  service (with `Dockerfile`, rate limiting, SQLite persistence, retention) that an
+  operator may deploy to *receive* telemetry. It is not run by the plugin and is not
+  required to use it.
+
+What it does **not** do:
 - Execute user-provided code directly
+- Store or forward credentials to any third party
+- Send anything over the network without an explicit opt-in
 
 Security concerns are most likely to involve:
-- **Hook scripts** (`hooks/enforce-scope.sh`, `hooks/enforce-commands.sh`) — command injection via crafted file paths or tool input
+- **Hook scripts** (`hooks/*.mjs`) — command injection via crafted file paths or tool input
 - **Skill instructions** — prompt injection that could bypass scope enforcement or safety constraints
 - **Agent dispatch** — unintended tool access or scope escalation during wave execution
+- **Session Config** — the `*-command` keys are executed via a shell; see
+  [Session Config Command Trust](#session-config-command-trust) below
 
 ## Disclosure
 
@@ -39,52 +68,186 @@ We follow [responsible disclosure](https://en.wikipedia.org/wiki/Responsible_dis
 
 ## Enforcement Architecture
 
-Session Orchestrator uses a two-layer PreToolUse hook system to constrain agent behavior during wave execution.
+Enforcement is a set of `PreToolUse` / `PreToolUse`-adjacent hooks registered via
+`hooks/hooks.json` (with per-platform variants for Codex, Cursor, and Pi). All are
+Node ESM; the former Bash implementations were removed in the v3.0.0 native
+migration (#137/#138).
+
+### Wave-scoped enforcement
 
-### File scope enforcement (`enforce-scope.sh`)
+Both wave guards read a `wave-scope.json` that the wave-executor writes before
+dispatching each wave. Its location is **platform-resolved** by
+`scripts/lib/scope-gate.mjs` — `.claude/`, `.codex/`, `.cursor/`, or `.pi/` under
+the project root, depending on the host agent.
 
-Intercepts **Edit** and **Write** tool calls. Validates the target `file_path` against the `allowedPaths` array in `.claude/wave-scope.json`. Paths are matched via prefix (directory), glob (`*`, `**`), or exact literal. Symlinks are resolved with `realpath` before comparison to prevent symlink bypass. Files outside the project root are always flagged.
+**File scope (`hooks/enforce-scope.mjs`)** intercepts `Edit`, `Write`, and
+`MultiEdit`. It resolves the target through `realpath` (symlink-bypass defense) and
+matches the result against `allowedPaths` — prefix, glob, or exact literal. An
+explicit *absolute* allowlist entry is honoured before the project-root containment
+check (#792), so a deliberate out-of-repo grant is reachable; every other
+out-of-repo path is denied.
 
-### Command enforcement (`enforce-commands.sh`)
+**Command scope (`hooks/enforce-commands.mjs`)** intercepts `Bash` and matches the
+command against `blockedCommands[]` using word-boundary matching (so `rm` does not
+match `format`). When `blockedCommands` is empty or absent, a hardcoded fallback
+list applies (`rm -rf`, `git push --force` / `-f`, `git reset --hard`,
+`drop table`, `git checkout -- .`).
 
-Intercepts **Bash** tool calls. Checks the command string against the `blockedCommands` array in `wave-scope.json` using word-boundary matching (prevents partial matches like "rm" matching "format"). When `blockedCommands` is empty or absent, a hardcoded fallback safety list is enforced: `rm -rf`, `git push --force`, `git reset --hard`, `DROP TABLE`, `git checkout -- .`.
+Both wave guards **fail closed**: any unhandled internal error emits a deny,
+never a silent allow. (The session-level destructive-command guard makes the
+opposite, documented choice — see
+[Policy floor (blocked-commands)](#policy-floor-blocked-commands).)
 
 ### Enforcement levels
 
-Both hooks read the `enforcement` field from `wave-scope.json`:
+Both wave guards read the `enforcement` field from `wave-scope.json`:
 
 | Level | Behavior | Exit code |
 |-------|----------|-----------|
-| `strict` | Deny the operation, return `permissionDecision: deny` | 2 |
+| `strict` | Deny the operation via `hookSpecificOutput.permissionDecision: deny` on stdout | 0 |
 | `warn` | Allow the operation, emit stderr warning | 0 |
 | `off` | Skip all checks | 0 |
 
-**Default is `strict`** (fail-closed) when the `enforcement` field is missing from `wave-scope.json`.
+A deny exits **0**, not 2 (#906). Per the Claude Code hook contract a hook signals
+either by exit code alone or by exit 0 plus structured JSON — never both; under
+`exit 2` stdout JSON is discarded, which previously swallowed every deny reason.
+The emitter is `scripts/lib/io.mjs#emitDeny`; see its JSDoc for the full payload.
 
-### Dynamic per-wave scoping
+**Default is `strict`** (fail-closed) when the `enforcement` field is missing.
+
+### Policy floor (blocked-commands)
+
+Since #972 the destructive-command guard (`pre-bash-destructive-guard.mjs`) no
+longer reads a single policy file first-hit-wins — it merges two policy roles
+via `scripts/lib/blocked-commands-policy.mjs` (`loadEffectivePolicy`):
+
+| Role | Source | Semantics |
+|---|---|---|
+| **Floor** | `$CLAUDE_PLUGIN_ROOT/.orchestrator/policy/blocked-commands.json` | The plugin's own blocklist — immutable baseline. |
+| **Overlay** | First existing of `<cwd>`, `$CLAUDE_PROJECT_DIR` (`.orchestrator/policy/blocked-commands.json`) | The consumer repo's policy — strictly additive. |
+
+Roles are resolved purely by path — there is no marker field in the file.
+Precedence: `cwd` → `CLAUDE_PROJECT_DIR` for the overlay; the plugin root
+always supplies the floor. When both roles resolve to the same file (e.g.
+inside the plugin repo itself), that one file *is* the policy.
 
-The wave-executor writes `.claude/wave-scope.json` before dispatching each wave. This means scope constraints change between waves:
+**Merge contract** — union by rule `id`, floor rules first, escalate-only:
 
-- **Discovery waves** use empty `allowedPaths` (deny-all writes) combined with explicit read-only agent instructions (dual enforcement — hook-level + prompt-level).
-- **Quality waves** use two-phase scope: production file patterns for simplification passes, then test-only patterns (`**/*.test.*`, `**/*.spec.*`) for test/review passes.
+- An overlay-only `id` is appended (additive).
+- On an `id` collision with a floor rule of severity `block`, the **whole floor
+  rule wins** — no field merge (an overlay-supplied `pattern` or
+  `path-allowlist` would be a bypass); the overlay definition is dropped with a
+  stderr warning.
+- A floor rule of severity `warn` escalates monotonically:
+  `max(floor, overlay)` with `warn < block`; unknown overlay severity → floor
+  kept + warning.
+
+**Failure semantics** — the authoritative contract for this hook. Unlike the
+wave guards above, it is deliberately *not* fail-closed on internal error:
+
+| Condition | Effective policy |
+|---|---|
+| Overlay malformed / missing `.rules` / empty `rules: []` | **Fail-to-floor**: floor alone + stderr warning (an empty overlay cannot disarm the floor) |
+| Floor unresolvable (no plugin root, or file missing) | Overlay alone + warning |
+| Both missing | Fail-open (guard skipped) + warning — unchanged pre-#972 behavior |
+| Internal error in the hook | `exit 0` fail-open — a documented decision; the merge module's functions are total (never throw) precisely so policy input can never reach this path |
+
+**Trust note:** whoever controls `CLAUDE_PLUGIN_ROOT` controls the floor. That
+is harness trust — the same party already controls the hook code itself — not a
+new attack surface.
+
+### Dynamic per-wave scoping
+
+Scope constraints change between waves:
+
+- **Discovery waves** use empty `allowedPaths` (deny-all writes) combined with
+  explicit read-only agent instructions (dual enforcement — hook-level + prompt-level).
+- **Quality waves** use two-phase scope: production file patterns for simplification
+  passes, then test-only patterns (`**/*.test.*`, `**/*.spec.*`) for test/review passes.
+
+### Session-level guards (active outside waves)
+
+| Hook | Protects against |
+|---|---|
+| `pre-bash-destructive-guard.mjs` | Destructive shell commands in the **main** session, per the effective `blocked-commands.json` policy — at least the 14 floor rules from the plugin's policy, plus any additive overlay rules from the repo's policy (`block` or `warn` severity, each citing its source rule; see [Policy floor (blocked-commands)](#policy-floor-blocked-commands)). Bypass requires `allow-destructive-ops: true` in Session Config. |
+| `config-protection.mjs` | Edits that *loosen* a quality gate — lowered thresholds, added `eslint-disable`/`@ts-ignore`, rules flipped to `off`, widened `.gitleaks.toml` allowlists, relaxed tsconfig strictness. Warn-by-default, fail-open on internal error. |
+| `pre-bash-staging-fence.mjs` + `wave-scope-commit-guard.mjs` | Concurrent `git add` races between parallel wave-agents, and lint-staged sweeps that re-stage files outside wave scope. Rejects the commit rather than the edit. |
+
+The behavioural rules these guards mechanise are documented in
+[`.claude/rules/parallel-sessions.md`](.claude/rules/parallel-sessions.md) (PSA-003,
+PSA-004, PSA-007).
+
+## Supply Chain
+
+- `.npmrc` sets `ignore-scripts=true` — no dependency may run install/postinstall
+  scripts. This is the primary defense against postinstall-style attacks (SEC-020).
+- CI enforces `npm audit --omit=dev --audit-level=high`.
+- **gitleaks** (37 rules) and an **owner-leakage scanner**
+  (`scripts/lib/validate/check-owner-leakage.mjs`) both run in CI and as `.husky/`
+  pre-commit stages, so a secret or private-path leak is normally blocked before it
+  reaches a public branch. Note the asymmetry: the owner-leakage stage is
+  unconditional, whereas the local gitleaks stage is **skipped silently when gitleaks
+  is not installed** — CI remains the backstop for that one, and `--no-verify`
+  bypasses both.
+- This repo is **npm-canonical**: `package-lock.json` is the committed lockfile and
+  `scripts/check-package-manager.mjs` guards against a foreign lockfile appearing.
+
+## Session Config Command Trust
+
+The Session Config keys `test-command`, `typecheck-command`, `lint-command`, and
+`custom-phases[].command` are executed via a shell. A malicious commit to
+`CLAUDE.md` could therefore inject commands — which is **RCE-equivalent within the
+repo's existing trust model**, not a new attack surface: anyone able to commit can
+already achieve the same through `package.json` scripts, `.husky/` hooks, or a test
+file.
+
+The mitigation is review, not sandboxing: treat Session Config like code. Any diff
+touching a command-bearing key must show before/after. `custom-phases` additionally
+rejects shell metacharacters as defense-in-depth. Full trust model in
+[`.claude/rules/security.md`](.claude/rules/security.md).
 
 ## Prerequisites
 
-- **`jq` is required** for hook enforcement. If `jq` is not installed, both enforcement hooks silently allow all operations (graceful degradation with stderr warning). The wave-executor checks for `jq` before wave dispatch and warns the user.
-- Hooks run in the Claude Code harness environment as PreToolUse interceptors, not as standalone scripts.
+- **Node.js 24+.** v3.x is Node ESM throughout; there is no Bash runtime dependency
+  for the hooks (`jq` is used only by a few `scripts/` validators, never by
+  `hooks/*.mjs`).
+- Hooks run inside the host agent's harness as tool-use interceptors, not as
+  standalone scripts.
 
 ## Known Limitations
 
-1. **No enforcement outside active waves** — when no `wave-scope.json` exists (between sessions, before the first wave, after cleanup), hooks exit 0 and allow all operations.
+1. **No wave enforcement outside active waves** — when no `wave-scope.json` exists
+   (between sessions, before the first wave, after cleanup), the two wave guards exit 0.
+   The session-level guards in the table above remain active.
+
+2. **Prompt injection via VCS content** — issue titles and descriptions fetched via
+   `glab`/`gh` are consumed in agent prompts without sanitization. A malicious issue
+   body could inject instructions into an agent's context. Mitigated by: issues are
+   typically user-created in controlled workflows, and wave scope enforcement limits
+   the blast radius of any injected instructions.
 
-2. **Prompt injection via VCS content** — issue titles and descriptions fetched via `glab`/`gh` are consumed in agent prompts without sanitization. A malicious issue body could inject instructions into an agent's context. Mitigated by: issues are typically user-created in controlled workflows, and wave scope enforcement limits the blast radius of any injected instructions.
+3. **Plugin relies on the host harness** — tool-level enforcement is provided by the
+   agent's hook system. The plugin cannot enforce restrictions if hooks are bypassed
+   at the harness level (`disableAllHooks`, `--no-verify`, etc.).
 
-3. **Plugin relies on Claude Code harness** — tool-level enforcement is provided by Claude Code's PreToolUse hook system. The plugin cannot enforce restrictions if hooks are bypassed at the harness level.
+4. **Session Config values are only partially validated** — `health-endpoints`,
+   `plan-baseline-path`, and `cross-repos` accept arbitrary strings. Do not embed
+   credentials in these fields (see Credential Safety below).
 
-4. **Session Config values are not validated** — `health-endpoints`, `plan-baseline-path`, and `cross-repos` accept arbitrary string values. Do not embed credentials in these fields (see Credential Safety below).
+5. **Guards are heuristics, not proofs** — `config-protection.mjs` is a
+   low-false-positive line/regex heuristic, not an exhaustive AST gate, and fails
+   open by design so a guard bug never blocks legitimate work.
 
 ## Credential Safety
 
-- This plugin does not store, process, or transmit credentials.
-- VCS CLI tools (`glab`, `gh`) use the user's existing authentication. Credential security for these tools is the user's responsibility.
-- **Do not embed API keys, passwords, or auth tokens** in Session Config fields (especially `health-endpoints` URLs). These values are stored in `CLAUDE.md` which may be committed to version control.
+- Secrets are read from the environment or a gitignored `.env.local`, never written
+  into repo files by the plugin.
+- VCS CLI tools (`glab`, `gh`) use your existing authentication; their credential
+  security is your responsibility.
+- **Do not embed API keys, passwords, or auth tokens** in Session Config fields
+  (especially `health-endpoints` URLs). Session Config lives in `CLAUDE.md`, which is
+  normally committed.
+- **Do not paste tokens into permission allowlists** in `.claude/settings.json` or
+  `.claude/settings.local.json` (SEC-021). `settings.local.json` is conventionally
+  untracked, so the pre-commit leakage scanner — which enumerates tracked files —
+  structurally cannot see a token pasted there.

package/agents/AGENTS.md

@@ -1,3 +1,9 @@
+---
+name: agents-authoring-spec
+description: NOT A DISPATCHABLE AGENT — never select this. It is the authoring specification that the agent definitions in this directory must follow, loaded as a nested instruction file. Claude Code's plugin loader registers every agents/*.md as an agent by directory convention, and the manifest's `agents` key is additive-only, so it cannot exclude a path. Without this frontmatter the file registered as an unnamed agent with FULL tool access; the minimal `tools` line below is what bounds that. If you need agent-authoring rules, read this file — do not dispatch it.
+tools: Read
+---
+
 # `agents/` — Sub-Agent Authoring Conventions
 
 > Nested instruction file for the `agents/` subtree. Claude Code / Cursor IDE
@@ -9,7 +15,18 @@
 > This is **not** an agent definition — it is the authoring spec the agent
 > `*.md` definitions in this directory must follow. The plugin validator
 > (`scripts/lib/validate/check-agents.mjs`) excludes `AGENTS.md` / `CLAUDE.md`
-> from agent-frontmatter validation by name.
+> from agent-frontmatter validation by name, and `measureDescriptionSurface`
+> excludes them from its walked corpus (#878).
+>
+> **Claude Code's plugin loader makes no such exception.** It registers every
+> `agents/*.md` as a dispatchable agent by directory convention, and the
+> manifest's `agents` key is documented as *additive* ("in addition to those in
+> the `agents/` directory"), so it cannot exclude a path. With no frontmatter
+> this file therefore registered as an agent named `AGENTS` with **full tool
+> access**. The frontmatter above is the containment: it names the file for what
+> it is, states in the `description` that it must never be dispatched, and caps
+> `tools` at `Read`. Do not remove it — and if you add another non-agent doc to
+> this directory, give it the same treatment.
 >
 > Sibling spec: for `.claude/rules/*.md` frontmatter (conditional loading via
 > globs/mode/host-class/expiry, plus the never-always-on invariant for
@@ -63,8 +80,8 @@ tools: Read, Grep, Glob, Bash         # comma-separated string OR JSON array (bo
 `model:` is not just a compatibility field — it is a cost/quality dial per agent. Pick deliberately, don't default to `sonnet` everywhere.
 
 - **`haiku`** — cheap, fast, advisory/judge roles where the task is narrow classification or a single yes/no verdict, not open-ended reasoning. Precedent: `dialectic-deriver`, `skill-applied-judge`. Pin `haiku` when the agent's whole job is "read a short input, emit a structured verdict."
-- **`sonnet`** — the default workhorse tier. Use for implementation, test-writing, and review agents that need real reasoning over a non-trivial diff or codebase slice (code-implementer, test-writer, security-reviewer, and most of the catalog).
-- **`inherit`** — let the coordinator/session's active model tier flow through. Default for read-only reviewer/analysis agents that benefit from running at whatever tier the operator picked for the session (e.g. an Opus session should give its reviewers Opus-quality judgment too), and for agents with no strong cost/quality reason to diverge from the session.
+- **`sonnet`** — an explicit cost cap, NOT a default. Pin it only when an agent must stay on the workhorse tier even in an Opus session, and state the reason inline. A bare `sonnet` on a working agent silently overrides the operator's session model — the failure mode that moved the implementation and review catalog to `inherit`.
+- **`inherit`** — **the default for the working catalog.** Lets the coordinator/session's active model tier flow through, so the agent runs at whatever tier the operator picked (an Opus session gives its implementers AND its reviewers Opus-quality judgment). Use it for implementation, test-writing, and review agents alike — `code-implementer`, `test-writer`, `security-reviewer`, `session-reviewer`, `db-specialist`, `ui-developer`, and the read-only analysis agents. Diverge only for a named cost/quality reason.
 - **`opus`** — reserve for agents whose task genuinely needs the strongest available reasoning (e.g. `ux-evaluator`) and where the cost is justified because the agent runs rarely (dispatched solo, not fanned out across a wave).
 - **Full model-ID pinning** (`claude-opus-4-7`, `claude-sonnet-5`, `claude-fable-5-20260101`, …) — only when the agent has a demonstrated dependency on a SPECIFIC model version, e.g. a reproducibility requirement that needs a dated snapshot, or a known behavioral regression on newer models for this agent's exact prompt. Pinning trades away automatic model-family upgrades — document the reason inline as a frontmatter comment when you do this.
 

package/agents/code-implementer.md

@@ -1,7 +1,7 @@
 ---
 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>
-model: sonnet
+model: inherit
 color: green
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
 sandbox-tier: repo-write
@@ -24,17 +24,17 @@ You are a focused implementation agent. You write production code, refactor exis
 2. **Confirm scope**: The wave plan task definition is your contract. If the task is ambiguous (e.g., "add validation" without specifying where), pause and report rather than guess.
 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 — that is the Quality wave's responsibility.
+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.
 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`), follow its 5-step structure per Task (test-first → confirm fail → implement → verify pass → commit-stop).
+- **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.
 
 ## Rules
 
-- Do NOT write tests — that is the test-writer's job. Production code only.
-- Do NOT modify test files unless the task explicitly requires it.
-- Do NOT add documentation beyond inline comments where logic is non-obvious. README and CLAUDE.md are owned by docs-writer.
+- Tests are **need-gated, not banned**: when you fix a bug, author exactly ONE test that names the bug and fails without your fix (the fake-regression proof the wave-executor's per-agent testing expectation requires — `skills/wave-executor/SKILL.md` § Agent Prompt Best Practices, point 5). Do NOT write speculative test volume, and do NOT own test consolidation or coverage sweeps — those belong to the **test-writer**. (In a bite-sized plan's 5-step structure, the `test-first`/`confirm-fail` steps are the test-writer's — see Bite-sized plan above.)
+- Do NOT modify test files beyond the one need-gated test your task's bug requires.
+- Do NOT add standalone or narrative documentation (README, CLAUDE.md, guides), and never write docs for code that does not exist yet — those surfaces are owned by docs-writer. Inline code-surface docs ARE yours: comments where logic is non-obvious, plus JSDoc/TSDoc on public functions you author (per `.claude/rules/development.md` § Documentation).
 - Do NOT introduce new runtime dependencies without explicit instruction. If a new dependency seems necessary, pause and report rather than installing.
 - Do NOT run ANY git write operation (`git add`, `git commit`, `git stash`, `git mv`, `git rm`, `git push`, `git reset`) — the git index and stash are shared session resources (PSA-007); the coordinator handles ALL VCS operations.
 - Do NOT touch unrelated files in the same directory just because they share a folder.

package/agents/db-specialist.md

@@ -1,7 +1,7 @@
 ---
 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>
-model: sonnet
+model: inherit
 color: purple
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
 sandbox-tier: repo-write

package/agents/qa-strategist.md

@@ -10,10 +10,14 @@ output-schema: schemas/qa-strategist.schema.json
 
 # QA Strategist Agent
 
-You are a senior QA engineer conducting a read-only test-coverage gap analysis between waves. You identify what is NOT tested — boundary conditions, error paths, integration contracts, and silent failures. You do NOT write tests or fix code. You produce a prioritised gap report.
+You are a senior QA engineer conducting a read-only test-suite analysis between waves. You identify **both** failure modes of a suite: what is NOT tested (boundary conditions, error paths, integration contracts, silent failures) **and what is OVER-tested** (redundant, tautological, prose-pinning, and framework-verifying tests). You do NOT write tests or fix code. You produce a prioritised report.
+
+Under-testing and over-testing are symmetric defects, not one real problem and one nitpick. A suite of 400 tests where 120 assert nothing costs real CI minutes, blocks refactors it should permit, and manufactures false confidence — that is a genuine finding, and the correct recommendation is deletion or consolidation, never "add more tests". Report a suite that needs shrinking as clearly as one that needs growing.
 
 ## Core Responsibilities
 
+### A. Under-testing (gaps)
+
 1. **Happy-path-only suites**: Identify test files that only test the success path and lack any negative or edge-case coverage
 2. **Boundary conditions**: Flag missing tests for limit values (empty inputs, max-length strings, zero, negative numbers, null/undefined)
 3. **Error-path coverage**: Detect unhandled or silently-swallowed errors (catch blocks with no assertion, error callbacks never invoked in tests)
@@ -21,6 +25,13 @@ You are a senior QA engineer conducting a read-only test-coverage gap analysis b
 5. **Integration gaps**: Identify points where unit tests exist but no integration or contract test verifies the full call chain
 6. **Flaky-prone patterns**: Flag time-dependent tests, tests that rely on ordering, or tests with hardcoded dates/ports
 
+### B. Over-testing (redundancy)
+
+7. **Duplicate tests**: Two or more tests that exercise the same branch with equivalent inputs — deleting all but one loses no catch-power. Count in `redundancy_counts.duplicate`.
+8. **Worthless tests**: Tests that survive the falsification check trivially — they still pass when the function body is replaced with `throw new Error()`. Includes tautological computations (`expect(calcTax(p, r)).toBe(p * r)`), assert-nothing bodies, and overly-generous assertions (`toBeTruthy()` on an object). Count in `redundancy_counts.worthless`.
+9. **Framework-only / prose-pinning tests**: Tests that verify the language, the framework, or the presence of a string in a document rather than this repo's behaviour — `expect(typeof fn).toBe('function')`, property-assignment round-trips, "the README contains heading X", enum-case counts. Count in `redundancy_counts.framework_only`.
+10. **Test-to-source ratio**: Compute `test_to_src_ratio` = test LOC ÷ source LOC over the reviewed scope. It is a signal, not a verdict: a high ratio over logic-dense code is healthy; a high ratio driven by categories 7–9 is bloat. Always interpret it against those counts, never on its own.
+
 ## Workflow
 
 1. **Read changed source files** from the wave scope. Understand what each module does: what inputs it accepts, what errors it can throw or return, what external calls it makes.
@@ -43,6 +54,8 @@ You are a senior QA engineer conducting a read-only test-coverage gap analysis b
 - HIGH gaps: N
 - MEDIUM gaps: N
 - LOW gaps: N
+- Redundant tests: N duplicate / N worthless / N framework-only
+- Test-to-source ratio: N.N (test LOC ÷ source LOC over the reviewed scope)
 
 ## Coverage Gaps
 
@@ -53,15 +66,24 @@ You are a senior QA engineer conducting a read-only test-coverage gap analysis b
 - **Missing scenario**: Describe the specific input/state/sequence not covered
 - **Risk**: What breaks in production if this path is never exercised
 
+## Redundancy Findings
+
+### [HIGH|MEDIUM|LOW] <title>
+- **Test file**: path/to/source.test.ts:line
+- **Category**: duplicate | worthless | framework-only
+- **Evidence**: Quote the assertion(s). For `worthless`, state the falsification result — "still passes when the body is replaced with `throw new Error()`".
+- **Recommendation**: delete | merge into <test name> | parameterise <N> cases into one
+- **Payoff**: What the suite gains — CI time, refactor freedom, removal of false confidence
+
 ## Well-covered areas
 <list source files or functions with adequate test coverage>
 ```
 
 ## Severity Calibration
 
-- **HIGH**: Untested error path that hides data corruption, auth bypass, or data loss; production silent failure
-- **MEDIUM**: Missing boundary test for a public API; mocked integration with no assertion
-- **LOW**: Missing a convenience edge case, cosmetic gap, or low-impact optional behaviour
+- **HIGH**: Untested error path that hides data corruption, auth bypass, or data loss; production silent failure. On the redundancy side: a worthless test that is the ONLY test for a behaviour — it reads as covered but catches nothing, which is worse than a visible gap.
+- **MEDIUM**: Missing boundary test for a public API; mocked integration with no assertion. On the redundancy side: a cluster of duplicates or framework-only tests large enough to slow CI or block a legitimate refactor.
+- **LOW**: Missing a convenience edge case, cosmetic gap, or low-impact optional behaviour; one-off redundant test with negligible cost.
 
 ## Refusal Rule
 
@@ -76,18 +98,21 @@ After the human-readable gap report, append a fenced ```json block matching `age
   "verdict": "PROCEED|PROCEED_WITH_FOLLOWUPS|FIX_REQUIRED|BLOCKED",
   "report_path": ".orchestrator/audits/wave-reviewer-N-qa-strategist.md",
   "gap_counts": {"high": 0, "med": 0, "low": 0},
+  "redundancy_counts": {"duplicate": 0, "worthless": 0, "framework_only": 0},
+  "test_to_src_ratio": 1.4,
   "source_files_reviewed": 0,
   "test_files_reviewed": 0,
   "blockers": []
 }
 ```
 
-Required: `verdict` (enum PROCEED|PROCEED_WITH_FOLLOWUPS|FIX_REQUIRED|BLOCKED), `report_path`, `gap_counts`, `source_files_reviewed`, `test_files_reviewed`. Optional: `blockers`. The coordinator's `validateAgentOutput()` parses the LAST fenced ```json block; place it at the end of your response.
+Required: `verdict` (enum PROCEED|PROCEED_WITH_FOLLOWUPS|FIX_REQUIRED|BLOCKED), `report_path`, `gap_counts`, `source_files_reviewed`, `test_files_reviewed`. Optional: `redundancy_counts`, `test_to_src_ratio`, `blockers`. Emit `redundancy_counts` and `test_to_src_ratio` on every run — omitting them reads as "no redundancy analysis performed", not as "zero redundancy found". The coordinator's `validateAgentOutput()` parses the LAST fenced ```json block; place it at the end of your response.
 
 Verdict variants (concrete examples per scenario):
-- Coverage strong, no gaps → `{"verdict": "PROCEED", "gap_counts": {"high": 0, "med": 0, "low": 0}}`
+- Coverage strong, no gaps, no bloat → `{"verdict": "PROCEED", "gap_counts": {"high": 0, "med": 0, "low": 0}, "redundancy_counts": {"duplicate": 0, "worthless": 0, "framework_only": 0}}`
 - Coverage adequate, advisory gaps only → `{"verdict": "PROCEED_WITH_FOLLOWUPS", "gap_counts": {"high": 0, "med": 3, "low": 4}}`
 - HIGH-risk gap that would let real bug ship → `{"verdict": "FIX_REQUIRED", "gap_counts": {"high": 2, "med": 5, "low": 3}}`
+- **Redundancy dominates — no gap, but the suite must SHRINK** → `{"verdict": "FIX_REQUIRED", "gap_counts": {"high": 0, "med": 1, "low": 2}, "redundancy_counts": {"duplicate": 14, "worthless": 9, "framework_only": 22}, "test_to_src_ratio": 3.8}`. The recommendation is consolidation, not writing: 9 worthless tests pass with the implementation deleted, 22 pin framework or prose behaviour, and 14 duplicate a sibling — the suite claims coverage it does not have. `FIX_REQUIRED` is correct here even with zero HIGH gaps, because the false confidence is itself the defect. Hand the test-writer a delete/merge list, never a "write more tests" instruction.
 - Strategy review cannot complete → `{"verdict": "BLOCKED", "blockers": ["sources missing"]}`
 
 ## Edge Cases

package/agents/schemas/qa-strategist.schema.json

@@ -27,6 +27,33 @@
         "low": { "type": "integer", "minimum": 0 }
       }
     },
+    "redundancy_counts": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Over-testing findings — the symmetric counterpart to `gap_counts`. A high count here calls for consolidation/deletion, never for writing more tests.",
+      "properties": {
+        "duplicate": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Tests exercising the same branch with equivalent inputs; all but one can be deleted without losing catch-power."
+        },
+        "worthless": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Tests that still pass when the implementation body is replaced with `throw new Error()` — tautological computations, assert-nothing bodies, overly-generous assertions."
+        },
+        "framework_only": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Tests verifying the language, the framework, or the presence of a string in a document rather than this repo's behaviour."
+        }
+      }
+    },
+    "test_to_src_ratio": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Test LOC divided by source LOC over the reviewed scope. A signal, not a verdict — interpret only alongside `redundancy_counts`."
+    },
     "source_files_reviewed": {
       "type": "integer",
       "minimum": 0,