v4.6.0: drop 4 generic brewcode agents, output-discipline + scope-fit in generated agents, codex mirror restored

2026-09-14 20:16:41 +08:00 · 2026-08-05 20:24:42 +01:00
parent d1b2a55ed3
commit caf4720cf5
143 changed files with 3500 additions and 1941 deletions
@@ -10,7 +10,7 @@ try {
  } else {
    const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
    const skip = /^(?:yes|no|y|n|ok|okay|thanks|done|cancel|stop|continue|proceed|approved?|confirm(?:ed)?|\d+)$/i;
-    if (!prompt || prompt.startsWith('$') || skip.test(prompt)) {
+    if (!prompt || skip.test(prompt)) {
      respond({});
    } else {
      respond({
@@ -10,9 +10,9 @@ const PROMPT_INTERVAL = 5;
 const STALE_MS = 24 * 60 * 60 * 1000;

 export const PROMPT_CONTEXT = [
-  '[SKILL?] Check the available Codex skills and invoke every matching skill before acting.',
-  '[HINT] Use Codex sub-agent collaboration for substantial independent work.',
-  '[ROLE] Coordinate specialized work when delegation is requested; keep simple tasks direct.'
+  '[ROLE] Coordinate: a project expert in .codex/agents matches this domain -> delegate via sub-agent collaboration; no expert or trivial one-off -> do it directly.',
+  '[SPLIT] One agent for an hour = drift you cannot observe: split into bounded units (1 deliverable, ~5 files, ~20 min), fan out in ONE message; a dependency must be a REAL data handoff, else parallel; every spawn brief carries goal + scope + what is already done + who consumes the result + acceptance.',
+  '[BRANCH] Stay on the current branch; none chosen -> main. No explicit branch/PR instruction -> work on main and take over ALL workspace changes, incl. from other sessions.'
 ].join('\n');

 function sessionKey(sessionId) {
@@ -1,6 +1,6 @@
 # Agents

-Manages Codex subagents across all scopes — create new agents, improve existing ones, audit quality, or inspect what is installed. Input is ONE free-form natural-language prompt; there are no keyword subcommands.
+Manages Codex subagents across all scopes — create new agents, improve existing ones, audit quality, sync agent knowledge with the codebase, or inspect what is installed. Input is ONE free-form natural-language prompt; there are no keyword subcommands.

 ## Quick Start

@@ -29,22 +29,43 @@ Every invocation goes through the same flow:
   - Create
   - Improve
   - Review
+   - Sync agents (memory sync)
   - List (plain)
   - Cancel
-4. **Dispatch** — routes to `brewcode:agent-creator` subagent (create / improve / review / batch) or runs Glob `*.md` over agent scopes directly (list mode).
-5. **Real status** — rich inventory by scope showing agent names, models, trigger coverage, and last-modified — not a flat file listing.
+4. **Dispatch** — routes create / improve / sync to `brewcode:agent-creator`, review to the project reviewer agent from `.codex/agents/` (else `general-purpose`, two-phase), or runs Glob `*.md` over agent scopes directly (list mode).
+5. **Real status** — inventory by scope (counts, names, load path); state (enabled/disabled via `_name.md`, model); overlaps/conflicts (same-name shadowing, duplicate triggers/descriptions); health flags (missing README/frontmatter, agents missing `Bash` in `tools:`, weak triggers, rules duplicated in AGENTS.md) — not a flat file listing.
 6. **Mandatory final output** — structured summary of what was created, modified, or reviewed. Omitted only for `list` mode.

 ## Modes

 | Mode | How it activates | What it does |
 |------|-----------------|--------------|
-| `status` | Default when no other mode is detected | Shows agents per scope, model breakdown, trigger coverage |
-| `list` | Explicit only — "list", "show agents", "what agents" | Globs `*.md` over all agent scopes, plain file listing |
-| `create` | "create", "add", "new agent" in prompt | agent-creator builds frontmatter + system prompt from description |
-| `improve` | "improve", "update", "refine", or agent name/path in prompt | agent-creator enhances an existing agent file per chosen focus |
-| `review` | "review", "check", "audit" in prompt | agent-creator audits agent files for quality and coverage gaps |
-| `batch` | "all", "multiple", "both" or plural scope detected | agent-creator fans out across all matching agents in one pass |
+| `status` | Default for any "show me" intent — "статус" / "что есть" / "состояние" | Inventory per scope, state and model, overlaps, health flags |
+| `list` | Explicit only — "list" / "список" / "перечисли" | Globs `*.md` over all agent scopes, plain file listing |
+| `create` | "создай" / "create" / "new" / "добавь" / "scaffold" | agent-creator builds frontmatter + system prompt from description |
+| `improve` | "улучши" / "improve" / "refactor" / "fix" / "почини", or a bare existing name/path | agent-creator enhances an existing agent file per chosen focus |
+| `review` | "ревью" / "review" / "validate" / "проверь корректность" | the project reviewer agent from `.codex/agents/` (else `general-purpose`) audits agent files, two-phase (review -> double-check findings -> report) |
+| `sync` | "sync", "синк", "memory sync", "актуализируй", "обнови знания", "приведи в соответствие с кодом" | agent-creator re-verifies agent claims against the codebase and corrects stale knowledge |
+
+Batch flag (not a mode): plural form, "все" / "all", or multiple names/paths — fan-out, one specialist spawn per item.
+
+## Sync mode
+
+Re-verifies every claim in agent files against the current codebase and corrects drift. Shared implementation with `$brewcode:skills sync`: `references/mode-sync.md` (path `<skill-directory>/../skills/references/mode-sync.md`).
+
+| Scope | Trigger | Evidence |
+|-------|---------|----------|
+| `repo` (default) | no scope given | whole working tree |
+| `session` | "session", "this conversation" | decisions, user corrections, bugs hit in the current conversation |
+| `commit` | "commit", "last commit" | `git show`/`git diff <ref>`, default `HEAD` |
+
+Announces `Sync scope: <scope> — <evidence> | targets: <N>` before editing. Non-growth: every edited file ends at or below its original line count, total delta <= 0. Order: DELETE stale/dead/duplicate/obvious content first, then FIX, then ADD (non-obvious, source-verified only).
+
+Verdicts: `STALE`, `DEAD`, `DUPLICATE`, `OBVIOUS`, `DRIFT`, `MISSING`.
+
+Report table: `File | Lines before -> after | Fixed | Deleted | Added | Key change`, plus corrected facts, additions with source, skipped files, and total delta.
+
+Targets: `.codex/agents/*.toml`, `*/agents/*.md` (repo-local only). Disabled files (`_name.md`) are skipped and reported. `$brewdoc:memory` applies the same non-growth sync to memory files, AGENTS.md, rules and conventions; its `full` mode also syncs the agent and skill rosters in-place — use this skill when you want a roster on its own.

 ## Parameters for Create / Improve

@@ -74,6 +95,12 @@ $brewcode:agents improve the reviewer agent's trigger keywords
 # Audit all agents for quality issues
 $brewcode:agents review all project agents

+# Sync agent knowledge with the codebase (default scope: repo)
+$brewcode:agents sync
+
+# Sync only what changed in the last commit
+$brewcode:agents sync commit
+
 # Plain listing of agent files across all scopes
 $brewcode:agents list
 ```
@@ -1,6 +1,6 @@
 ---
 name: agents
-description: "Creates and improves Codex subagents. Triggers: create agent, improve agent, scaffold agent, fix agent."
+description: "Creates, improves, syncs Codex subagents. Triggers: create agent, improve agent, sync agents, memory sync."
 ---

 # Codex agent authoring
@@ -25,11 +25,11 @@ Follow every phase below. When a phase delegates work, use Codex collaboration w
 | ARTIFACT | `agents` |
 | SPECIALIST | `brewcode:agent-creator` |
 | LIST_CMD | Glob `*.md` over `.codex/agents/`, `~/.codex/agents/`, `brewcode/agents/` |
+| SYNC_REF | `<skill-directory>/../skills/references/mode-sync.md` (shared with `$brewcode:skills`) |

 ## Step 1 — Input gate

-Treat the **entire** user input (`<arguments>`) as ONE free-form natural-language prompt.
-There is NO keyword grammar and NO argument parser — `argument-hint` is only a loose example.
+Treat the **entire** user input (`<arguments>`) as ONE free-form natural-language prompt — no keyword grammar, no argument parser (`argument-hint` is only a loose example).

 - prompt non-empty -> go to **Step 2**
 - prompt empty / whitespace-only -> go to **Step 3**
@@ -45,6 +45,7 @@ Classify the prompt + recent conversation context into exactly ONE mode:
 | `create` | "создай" / "create" / "new" / "добавь" / "scaffold" |
 | `improve` | "улучши" / "improve" / "refactor" / "fix" / "почини", OR a bare existing name/path |
 | `review` | "ревью" / "review" / "validate" / "проверь корректность" |
+| `sync` | "sync" / "синк" / "memory sync" / "меморисинк" / "актуализируй" / "обнови знания" / "приведи в соответствие с кодом" — alone or with a scope word |

 **Batch flag:** plural form, "все" / "all", or multiple names/paths -> fan-out (one specialist spawn per item).

@@ -66,6 +67,7 @@ Options (in this order):
 - `Create new agents`
 - `Improve existing agents`
 - `Review agents`
+- `Sync agents (memory sync)` — re-verify all knowledge vs code, shrink not grow
 - `List (plain)`
 - `Nothing / cancel`

@@ -75,6 +77,26 @@ After the choice:
  plus the artifact-specific params (see "Artifact-specific params" below).
 - Then ANNOUNCE the mode using the Step 2 format and proceed to **Step 4**.

+## Delegation (applies to EVERY sub-agent task spawn in this skill)
+
+A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct
+it, and it usually drifts off-target. One subagent = ONE bounded unit — one deliverable
+(here: ONE agent definition), ~<=5 files, ~<=10 steps. Bigger MUST be split into N tasks, all
+spawned in ONE message.
+
+Every spawn prompt MUST carry:
+
+| Field | Content |
+|-------|---------|
+| GOAL | the overall task and why it exists — the point beyond the file edit |
+| ROLE | what this agent owns; what it must NOT touch |
+| SCOPE | exact paths/commands in bounds + explicit out-of-bounds |
+| CONTEXT | what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs |
+| CONSUMER | who or what uses the result next, and the shape it must fit |
+| DONE | acceptance criteria + the exact report shape you want back |
+
+A bare one-line task is never enough.
+
 ## Step 4 — Dispatch

 - `status` -> go to **Step 5**.
@@ -83,7 +105,10 @@ After the choice:
 - `create` -> gather minimal params (Step 3 / artifact-specific), spawn `SPECIALIST` via sub-agent task.
  Batch -> spawn one `SPECIALIST` per item, ALL in ONE message (parallel).
 - `improve` -> resolve target(s), spawn `SPECIALIST` via sub-agent task per target (parallel for batch).
- `review` -> spawn `brewcode:reviewer` (two-phase: review -> double-check findings -> report).
+- `review` -> spawn the project's reviewer agent from `.codex/agents/`, else `general-purpose`
+  (two-phase: review -> double-check findings -> report).
+- `sync` -> read `SYNC_REF` and follow it end to end (S1 scope -> S6 report).
+  It replaces Steps 5-6 for this mode.

 ## Step 5 — Real status (NOT a flat list)

@@ -122,7 +147,25 @@ For `create`: ONE request_user_input batch — (Q1) scope: Project `.codex/agent
 Global `~/.codex/agents/` / Plugin `brewcode/agents/`; (Q2) model: balanced model (Recommended) /
 high-reasoning model / fast model / inherit (omit model: field); (Q3) update AGENTS.md agents table? yes/no.
 Frontmatter description budget: <= 100 chars, single line, role + 2-3 triggers, EN only.
-Spawn SPECIALIST (brewcode:agent-creator) with the description, scope+path, model.
+Spawn SPECIALIST (brewcode:agent-creator) using the Delegation shape, e.g.:
+
+```
+Codex delegation brief (task_role="brewcode:agent-creator", message="
+GOAL: user is building an agent roster for this project; this task delivers ONE agent
+      definition that fits alongside the existing ones.
+ROLE: you own exactly one file — {SCOPE_PATH}/{name}.md. Do NOT touch other agents,
+      AGENTS.md, skills, or project source.
+SCOPE: create {SCOPE_PATH}/{name}.md. Out of bounds: every other path.
+CONTEXT: description='{DESC}', scope={SCOPE_PATH} and reasoning_tier={MODEL} are already decided in
+      Step 3 — do NOT re-ask. Agents that already exist and must not be duplicated:
+      {EXISTING_NAMES}. In batch mode {N} sibling agent-creators run in parallel, one file each.
+CONSUMER: this skill's Step 6 report, and the AGENTS.md agents table row appended right after
+      you finish — the description line must drop into that row verbatim.
+DONE: file exists, valid frontmatter, description <= 100 chars single line with 2-3 triggers.
+      Report: path | model | description line | 1-line rationale.
+")
+```
+
 After creation, if user approved, update the AGENTS.md agents table via Edit (add/replace row).
 For `improve`: resolve agent by name/path across the 3 scopes; ONE request_user_input —
 (Q1) focus: triggers / system-prompt / both (Recommended) / full review; (Q2) update AGENTS.md? yes/no.
@@ -1,6 +1,6 @@
 interface:
  display_name: "Agents"
-  short_description: "Creates and improves Codex subagents. Triggers: create agent, im"
+  short_description: "Creates, improves, syncs Codex subagents. Triggers: create agent"
  default_prompt: "Use $brewcode:agents for this task."
 policy:
  allow_implicit_invocation: false
@@ -7,21 +7,39 @@ A **HUMAN-invoked generator skill**. It analyzes a target project and writes a s
 Like `skill-creator` and `task-board-init`, this skill produces a working artifact (a skill) rather than doing the
 review itself. The **emitted** skill is the one that reviews code.

+> Two axes decide whether the emitted review is worth running:
+> **domain experts** (a review routed to generic agents finds generic issues) and
+> **scope discipline** (was this change sanctioned, was all of it delivered, what else did it touch).
+> The generator treats both as mandatory, not optional extras.
+
 ## What it generates

-A project-tailored `superreview` skill modeled on the canonical finagra shape:
+A project-tailored `superreview` skill:

 1. **Deterministic MODE resolution** — `FULL_PROJECT | EXPLICIT | UNCOMMITTED | LAST_COMMITS`, computed (not guessed),
-   then ANNOUNCED (mode + branch + concrete scope + file count + focus) before any review.
-2. **Domain routing** — each changed file routed to its project domain-owner agent (from `.codex/agents/`).
-3. **Rule referencing** — points at the project's real `.codex/rules/*` + `.codex/convention/*` files; agents READ
+   with an explicit corpus rule (git-ignored = OUT, tracked-or-will-be = IN), then ANNOUNCED (mode + branch + scope +
+   file count + focus + gates + scope baseline + experts) before any review.
+2. **Mechanical gates first** — the project's real build/lint/type/test commands run before the fan-out. Their output
+   is the only verdict that needs no adversarial pass (`CONFIRMED-BY-EXECUTION`), and it is passed to every agent so
+   nobody re-runs or re-litigates it.
+3. **Domain experts selected at RUNTIME** — the live `.codex/agents/*.toml` roster is read each run, read-only recon
+   agents are excluded, and any surface without an owner is marked DEGRADED instead of quietly downgraded.
+4. **Scope discipline** — the sanctioned baseline (task + issue + recorded decisions) is resolved read-only, then two
+   dedicated passes audit it: **A** walks the diff inward (creep shapes 1-6), **B** reasons from the baseline outward
+   (delivery `D1-D4` with mandatory proof-of-absence, closeout `C1-C4`). No baseline -> `UNKNOWN` and a permanent P2
+   cap, never an invented yardstick.
+5. **Rule referencing** — points at the project's real `.codex/rules/*` + `.codex/convention/*` files; agents READ
   and CITE them (never restated in the skill).
-4. **ONE targeted parallel fan-out** — only the agents the changed files actually need, plus `{0,1,2}` general
-   cross-cutting agents by judgement. Far fewer spawns than a quorum + separate standards pass + arbiter.
-5. **Per-finding adversarial VALIDATION gate** — one arbiter agent reverse-validates EVERY candidate, drops false
-   positives, then merges + de-dups + prioritizes.
-6. **ONE merged P0-P3 report** at `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`. **READ-ONLY** — it recommends
-   `/simplify` and a Manager-mode fix session; it never edits code.
+6. **ONE targeted parallel fan-out** — only the agents the changed files actually need, plus the two scope passes and
+   `{0,1,2}` general cross-cutting agents by judgement.
+7. **Per-finding adversarial VALIDATION gate** — a NON-OWNING validator reverse-validates EVERY candidate (batched
+   <=40, max 4 spawns), drops false positives, merges + de-dups + prioritizes. Anything unvalidatable is reported as
+   `UNVALIDATED` and the run is marked `INCOMPLETE` — a degraded run can never look clean.
+8. **Scope gate** — `request_user_input` on unsanctioned expansion or an unproven absence; it rewrites priorities only,
+   never adds findings and never lifts the UNKNOWN-baseline cap.
+9. **ONE merged P0-P3 report** at `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`, every row carrying its verdict,
+   with a Scope Discipline / Blast Radius section. **READ-ONLY** — it recommends `/simplify` and a Manager-mode fix
+   session; it never edits code.

 ## How review + standards-review are merged

@@ -30,9 +48,11 @@ A project-tailored `superreview` skill modeled on the canonical finagra shape:
 | `review` engine | Canonical structure: deterministic mode, two-phase find->validate, merged report, agent contract |
 | `standards-review` | Reuse/duplication focus (rank 3, 90/70/50% reuse matrix), stack detection, file-grouping, per-stack guidelines, `/simplify` hand-off |
 | `setup` Phase 3.5 | Tech-specific check tables (Java/Node/Python/Go) folded into the per-stack reference docs; the placeholder->concrete generation mechanism |
+| Scope discipline | `references/scope.md.template`: baseline + precedence, ownership map + shared surfaces, 6-shape taxonomy, delivery D1-D4, closeout C1-C4, Phase 3b gate |
+| Runtime expertise | `references/agent-prompt.md`: live-roster selection, recon exclusion, DEGRADED marking |

-The finagra shape is the canonical structure; standards-review + the review template supply the per-stack checks,
-reuse matrix, and report scaffolding baked into that shape.
+The canonical shape is the structure; standards-review + the review template supply the per-stack checks, reuse
+matrix and report scaffolding baked into it; scope + expert selection make the emitted review project-specific.

 ## Usage

@@ -43,7 +63,8 @@ $brewcode:superreview "<fine-tune-prompt>" [scope]
 ```

 - `<fine-tune-prompt>` — what to emphasize in the emitted skill's focus ordering (e.g. "weight reuse highest",
-  "always treat auth as P0"). Woven into the emitted Focus table + emphasis line.
+  "always treat auth as P0"). Woven into the emitted Focus table + emphasis line. Scope discipline stays in rank 1
+  whatever the emphasis — it can be raised, never dropped.
 - `[scope]` — optional hint.

 Examples:
@@ -65,11 +86,12 @@ After generation, run the emitted skill in that project:
 | Phase | Action |
 |-------|--------|
 | 0 | Read the emit templates this skill ships (`references/`) |
-| 1 | `generate.sh scan` + analysis: tech stack, build, test, DB, `.codex/agents`, rules/convention, source groups |
-| 1.5 | request_user_input for genuinely ambiguous params (arbiter agent, domain mapping, dominant stack) |
-| 2 | Export scalar placeholders -> `generate.sh emit` (sed substitution, copies templates + chosen stack ref) |
-| 3 | AI fills BLOCK placeholders (agent table, rule pointers, file-group map, focus table) via Edit |
-| 4 | `generate.sh validate` — fail if any setup-time `{PLACEHOLDER}` remains |
+| 1 | `generate.sh scan` + analysis: tech stack, build, test, DB, agent roster, rules/convention, source groups, gate commands, tracker |
+| 1.5 | request_user_input for genuinely ambiguous params (scope baseline + tracker, shared surfaces, arbiter agent, domain mapping, dominant stack, gate commands) |
+| 1.6 | **Domain experts (mandatory)** — classify the roster, find uncovered groups, create the missing experts via `brewcode:agent-creator`, re-scan |
+| 2 | Export scalar placeholders -> `generate.sh emit` (sed substitution, copies templates + chosen stack ref + `scope.md`) |
+| 3 | AI fills BLOCK placeholders (agent table, rule pointers, file-group map, gate commands, focus table; scope baseline block, precedence table, ownership probe, shared surfaces) via Edit |
+| 4 | `generate.sh validate` — fails on a leftover setup-time `{PLACEHOLDER}`, an unknown agent name, a missing emitted asset, or **zero wired domain experts** |
 | 5 | Report what was written |

 ## Files
@@ -78,19 +100,23 @@ After generation, run the emitted skill in that project:
 |------|------|
 | `SKILL.md` | The generator orchestrator |
 | `scripts/generate.sh` | `scan` / `emit` / `validate` |
-| `references/SKILL.md.template` | The emitted finagra-shape SKILL.md (placeholder slots) |
-| `references/agent-prompt.md` | Emitted domain-owner prompt contract |
+| `references/SKILL.md.template` | The emitted SKILL.md (placeholder slots) |
+| `references/agent-prompt.md` | Emitted runtime expert-selection procedure + domain-owner prompt contract |
+| `references/scope.md.template` | Emitted scope-discipline reference (baseline, ownership, taxonomy, delivery, closeout, gate) |
 | `references/report-template.md` | Emitted merged-report layout |
 | `references/python.md` · `java-kotlin.md` · `typescript-react.md` · `go.md` | Per-stack reference docs (one emitted) |

 ## Re-run triggers

-Regenerate when: a project agent is added/renamed, a rule/convention file changes, the stack changes, or a new source
-group is added. Re-running re-wires the emitted skill to the current project shape.
+Regenerate when: a project agent is added/renamed, a rule/convention file changes, the stack changes, a new source
+group is added, the tracker or branch convention changes, or a new always-shared surface appears. Re-running re-wires
+the emitted skill to the current project shape.

 ## Notes

 - The emitted skill is **self-contained** — no plugin dependency, no sibling-skill orchestration. It uses only
-  project-local agents (`.codex/agents/`) and built-in `Explore` / `reviewer`.
+  project-local agents (`.codex/agents/`) and built-ins (`Explore` / `Plan` / `general-purpose`).
+- `validate` refuses a run with zero wired domain experts; accept a deliberately generic setup with
+  `SUPERREVIEW_ALLOW_NO_EXPERTS=1`.
 - Stack-generic: Java/Kotlin, Node/TypeScript, Python, Go.
 - READ-ONLY by design: it reports, it does not fix.
@@ -1,6 +1,6 @@
 ---
 name: superreview
-description: "Generates a project-tailored deep-review skill (review+standards merged). Triggers: superreview, generate review skill"
+description: "Generates a project-tailored deep-review skill: domain-expert routing + scope discipline (blast radius, delivery, closeout) + mechanical gates + adversarial validation. Triggers: superreview, generate review skill, deep review skill, scope discipline review"
 ---

 # Project-tailored review
@@ -19,12 +19,18 @@ project-local `.codex/skills/superreview/` into that project — the merged deep
 folded into one). It does NOT review code itself; it EMITS the skill that does.

 **OUTPUT:** A project-local skill at `<target>/.codex/skills/superreview/` (SKILL.md + references) modeled exactly on
-the canonical finagra shape: deterministic MODE resolution -> ANNOUNCE -> route changed files to project domain-owner
-agents -> reference (not restate) the project's `.codex/rules` + convention files -> ONE targeted parallel fan-out ->
-per-finding adversarial VALIDATION gate -> ONE merged P0-P3 report at `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`,
-READ-ONLY (recommends `/simplify`, never edits).
+the canonical shape: deterministic MODE resolution -> MECHANICAL GATES -> ANNOUNCE -> route changed files to project
+DOMAIN-EXPERT agents selected at RUNTIME -> resolve the SANCTIONED SCOPE baseline -> reference (not restate) the
+project's `.codex/rules` + convention files -> ONE targeted parallel fan-out (domain experts + 2 scope passes) ->
+per-finding adversarial VALIDATION gate -> scope gate (request_user_input) -> ONE merged P0-P3 report at
+`.codex/reports/{TIMESTAMP}_superreview/REPORT.md`, READ-ONLY (recommends `/simplify`, never edits).
+
+> **Two things make or break the emitted skill:**
+> **(1) DOMAIN EXPERTS** — a review routed to generic agents finds generic issues. Phase 1.6 below is mandatory:
+> discover the experts, and CREATE the missing ones before emitting.
+> **(2) SCOPE DISCIPLINE** — the emitted skill measures every change against the SANCTIONED baseline (task + issue
+> + recorded decisions): creep, blast radius, under-delivery, closeout. Phase 1.5 wires it to the target's tracker.

-> Like `skill-creator` / `task-board-init`: a multi-step analysis that deploys a working artifact into ANY repo.
 > The emitted skill is generic-capable (Java/Kotlin, Node/TS, Python, Go) and self-contained — NO plugin dependency,
 > NO sibling-skill orchestration once generated.

@@ -40,19 +46,46 @@ plus optional `[scope]` hint. The fine-tune prompt is woven into the emitted ski
 | `review` engine | Canonical STRUCTURE: deterministic mode, two-phase **find -> validate**, single merged P0-P3 report, agent prompt contract, report scaffolding |
 | `standards-review` | The **reuse/duplication** focus (rank 3: search-first 90/70/50% reuse matrix), tech-stack detection, file-grouping-by-type, per-stack reviewer guidelines, `/simplify` hand-off |
 | `setup` Phase 3.5 | Tech-specific check tables (Java/Node/Python/Go) folded into the per-stack reference docs; the placeholder -> concrete generation mechanism |
+| Scope discipline | `references/scope.md.template`: sanctioned-baseline resolution + precedence, ownership map + always-shared surfaces, the 6-shape creep taxonomy, the delivery map D1-D4 with PROOF OF ABSENCE, the closeout map C1-C4, the NOT-creep exclusion list, the Phase 3b user gate |
+| Runtime expertise | `references/agent-prompt.md`: live-roster expert selection, recon-agent exclusion, DEGRADED marking when a surface has no owner |
+| Execution ground truth | Mechanical gates -> `CONFIRMED-BY-EXECUTION`, the only non-adversarial verdict; `UNVALIDATED` -> the run is `INCOMPLETE` |

-> Reconcile rule: the **finagra shape is the canonical structure**; `standards-review` + the `review` template supply
-> the per-stack checks, the reuse matrix, and the report scaffolding that get baked INTO that shape.
+> Reconcile rule: the canonical shape is the STRUCTURE; `standards-review` + the `review` template supply the
+> per-stack checks, the reuse matrix and the report scaffolding baked INTO it; the scope + expert-selection
+> references supply the two axes that make the review project-specific rather than generic.

 ---

 ## Execution

+### Delegation (applies to every sub-agent task this generator spawns AND to the fan-out it emits)
+
+A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct
+it, and it usually drifts off-target. One subagent = ONE bounded unit — one deliverable
+(here: ONE file group's review), ~<=5 files, ~<=10 steps. Bigger MUST be split into N tasks, all
+spawned in ONE message — that is why the emitted skill routes file GROUPS to domain owners.
+
+Every spawn prompt MUST carry:
+
+| Field | Content |
+|-------|---------|
+| GOAL | the overall task and why it exists — the point beyond the file edit |
+| ROLE | what this agent owns; what it must NOT touch |
+| SCOPE | exact paths/commands in bounds + explicit out-of-bounds |
+| CONTEXT | what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs |
+| CONSUMER | who or what uses the result next, and the shape it must fit |
+| DONE | acceptance criteria + the exact report shape you want back |
+
+A bare one-line task is never enough. When filling `{FILE_GROUP_MAP}` in Phase 3, keep every group
+small enough to be one bounded unit — split an oversized group into two rows rather than emitting a
+single agent that owns half the repo.
+
 ### Phase 0 — Pre-analysis (read THIS skill's emit material)

 1. Read the emit templates this generator ships (relative to `<skill-directory>`):
-   - `references/SKILL.md.template` — the finagra-shape emitted SKILL.md (with `{PLACEHOLDER}` slots)
-   - `references/agent-prompt.md` — domain-owner agent prompt contract (emitted verbatim, scalar-substituted)
+   - `references/SKILL.md.template` — the emitted SKILL.md (with `{PLACEHOLDER}` slots)
+   - `references/agent-prompt.md` — runtime expert selection + domain-owner prompt contract (emitted, substituted)
+   - `references/scope.md.template` — scope-discipline reference (emitted as the target's `references/scope.md`)
   - `references/report-template.md` — emitted report layout
   - `references/{python,java-kotlin,typescript-react,go}.md` — per-stack reference docs (one is emitted)
 2. Confirm the TARGET project is the current working directory (the repo to be reviewed). All emitted paths are
@@ -74,10 +107,14 @@ From it (plus your own reads) determine:
 | Aspect | How to detect | Drives placeholder |
 |--------|---------------|--------------------|
 | Tech stack | build files: `pom.xml`/`build.gradle*` -> Java/Kotlin; `package.json`+react/ts -> Node/TS; `pyproject.toml`/`requirements*.txt` -> Python; `go.mod` -> Go | `STACK_LABEL`, `STACK_REF`, `SOURCE_GLOB`, `PATHSPEC_GLOBS` |
-| Project agents | `.codex/agents/*.toml` (name + description); map each to the path group it owns | `DOMAIN_AGENTS_TABLE`, `FILE_GROUP_MAP`, `GENERAL_AGENTS_TABLE` |
+| Project agents | `.codex/agents/*.toml` (name + description); map each to the path group it owns; flag READ-ONLY recon agents (cloud/SaaS/tracker consoles) as NON-reviewers | `DOMAIN_AGENTS_TABLE`, `FILE_GROUP_MAP`, `GENERAL_AGENTS_TABLE` |
 | Arbiter / validator | an architecture/reviewer agent in `.codex/agents/`, else built-in `general-purpose` | `ARBITER_AGENT`, `VALIDATOR_AGENT` |
 | Rule + convention files | `.codex/rules/*.md` + `.codex/convention/*.md` + `AGENTS.md` | `RULE_POINTER_TABLE`, `RULE_PREFLIGHT_LIST` |
 | Source path groups | top-level source dirs / service dirs / module layout | `FILE_GROUP_MAP` |
+| **Mechanical gates** | the REAL build/lint/type/test commands (`package.json` scripts, Makefile, gradle tasks, `pytest`, `go test`), plus where they run from | `GATE_COMMANDS` |
+| **Scope tracker** | `.codex/features/**` board, `gh` + `.github/`, Jira/Linear config, branch naming `<type>/<issue>-<slug>` | `TRACKER_LABEL`, `BASELINE_RESOLUTION_BASH`, `SANCTION_PRECEDENCE_TABLE`, `SCOPE_AGENT_A/B` |
+| **Shared surfaces** | public API/contract dirs, DB migrations, schema/registry files, CI workflows, dependency manifests, design tokens | `SHARED_SURFACES_TABLE`, `OWNERSHIP_SIGNALS_BASH` |
+| Team parallelism | contributors in `git shortlog -sn --since=3.months`, owner columns on the board | `TEAM_NOTE` |
 | DB / test stack | testcontainers, JPA/JOOQ, pytest, jest, etc. | folded into the per-stack reference note |

 **Multi-stack repos:** if more than one stack is detected, pick the DOMINANT one for the emitted `STACK_REF`, and note
@@ -88,14 +125,42 @@ pointers cover the rest.)

 Use request_user_input ONLY for params you cannot reliably infer. Never auto-guess a non-obvious choice. Typical questions:

+- **The scope baseline** — which tracker sanctions work (file board / GitHub issues / Jira / none), and the
+  branch -> issue convention. Without it the emitted skill caps every scope finding at P2, so ASK when unsure.
+- **Always-shared surfaces** — confirm the list whose edit widens blast radius across the whole team.
 - Which agent is the **architecture arbiter / Phase-3 validator** when several plausible reviewer/architect agents exist.
 - The **domain-owner mapping** when an agent's owned path group is unclear.
- Whether to include a **general second-pass agent** mapping (built-in `general-purpose`) when no project reviewer exists.
 - Confirm the **dominant stack** when the repo is genuinely multi-stack.
+- Confirm the **mechanical gate commands** when several plausible ones exist (CI is the tie-break: use what CI runs).

 > Weave the `<fine-tune-prompt>` argument into the emitted Focus ordering: if the user said "focus on X / weight Y
 > higher", reorder/emphasize the emitted `FOCUS_TABLE` accordingly (e.g. push security to P0-always, or raise reuse to
-> rank 1). Record the emphasis in `FOCUS_EMPHASIS`.
+> rank 1). Record the emphasis in `FOCUS_EMPHASIS`. Scope discipline stays inside rank 1 whatever the emphasis —
+> it may be raised, never dropped.
+
+### Phase 1.6 — DOMAIN EXPERTS (mandatory — the review is only as good as these)
+
+A superreview routed to generic agents produces generic findings. Before emitting, PROVE that every source group
+in `FILE_GROUP_MAP` has a real owner:
+
+1. **Classify the live roster** from the Phase 1 scan: for each `.codex/agents/*.toml`, does its `description` claim
+   a concrete path/responsibility in this repo? Exclude READ-ONLY recon agents (they inspect live external systems,
+   never source files) — they may never own a review group.
+2. **Find the gaps** — every group with no confident owner. A gap means the emitted skill falls back to `Explore`
+   for that surface, i.e. a permanently DEGRADED axis.
+3. **Fill the gaps (default action).** request_user_input listing the uncovered groups, recommending "create the
+   missing domain experts". On approval, spawn `brewcode:agent-creator` — ONE agent per missing domain, ALL in ONE
+   message — each with the group's paths, the project rules that bind it, and the responsibility it owns. Then
+   re-run the roster scan so the new agents enter `DOMAIN_AGENTS_TABLE` / `FILE_GROUP_MAP`.
+4. **If the user declines**, emit anyway but mark each uncovered group DEGRADED in `DOMAIN_AGENTS_TABLE`, and say
+   so in the Phase 5 summary. `generate.sh validate` fails when NO project expert is wired at all — pass
+   `SUPERREVIEW_ALLOW_NO_EXPERTS=1` to accept that consciously.
+5. **Never invent an agent name.** Every emitted `subagent_type` must resolve to a real file in `.codex/agents/`
+   or a built-in (`Explore`/`Plan`/`general-purpose`) — `validate` enforces it.
+
+> Scope passes need owners too: `SCOPE_AGENT_A` = the agent that owns the task board / tracker read path (e.g. a
+> `task-tracker` agent from `$brewtools:task-board-init`), else `Explore`. `SCOPE_AGENT_B` = a read-only searcher —
+> `Explore` is the correct default, since pass B's job is proving an ABSENCE across the corpus.

 ### Phase 2 — Resolve placeholders + emit (scalar substitution)

@@ -110,6 +175,9 @@ export SOURCE_GLOB="<*.py | *.java | *.ts | *.go ...>"
 export PATHSPEC_GLOBS="<'*.py' 'requirements*.txt' 'pyproject.toml' 'Dockerfile*' 'docker-compose.yml' '.github/workflows/*.yml'>"
 export ARBITER_AGENT="<project architect agent | general-purpose>"
 export VALIDATOR_AGENT="<project arbiter agent | general-purpose>"
+export SCOPE_AGENT_A="<task-board/tracker agent | Explore>"
+export SCOPE_AGENT_B="<read-only searcher | Explore>"
+export TRACKER_LABEL="<e.g. '.codex/features board + GitHub issues (read-only)' | 'GitHub issues only' | 'none'>"
 ```

 **EXECUTE** using shell:
@@ -119,27 +187,42 @@ bash "<skill-directory>/scripts/generate.sh" emit && echo "✅ emit" || echo "

 > **STOP if ❌** — verify `<skill-directory>/references/SKILL.md.template` exists and the target `.codex/` is writable.

-This writes `<target>/.codex/skills/superreview/SKILL.md` (scalars substituted), copies `agent-prompt.md` +
-`report-template.md` (scalar-substituted), and copies the chosen `${STACK_REF}` into the emitted `references/`.
+This writes `<target>/.codex/skills/superreview/SKILL.md` (scalars substituted), copies `agent-prompt.md`,
+`report-template.md` and `scope.md` (scalar-substituted), and copies the chosen `${STACK_REF}` into the emitted
+`references/`.

 ### Phase 3 — Adapt the BLOCK placeholders (AI Edit)

-Multi-row tables cannot go through sed (newlines). Using the **Edit** tool, replace each block placeholder in the
-EMITTED `<target>/.codex/skills/superreview/SKILL.md` with a table you build from Phase 1 analysis:
+Multi-row tables and multi-line bash cannot go through sed (newlines). Using the **Edit** tool, replace each block
+placeholder in the EMITTED files with content you build from Phase 1 analysis.
+
+**In `<target>/.codex/skills/superreview/SKILL.md`:**

 | Block placeholder | Replace with |
 |-------------------|--------------|
-| `{DOMAIN_AGENTS_TABLE}` | one row per project agent: `\| <agent> \| Domain owner — <path glob>: <responsibility> \|` (built-in `Explore` as graceful fallback row) |
+| `{DOMAIN_AGENTS_TABLE}` | one row per project domain expert: `\| <agent> \| Domain owner — <path glob>: <responsibility> \|`; mark any uncovered group `DEGRADED -> Explore` (Phase 1.6) |
 | `{GENERAL_AGENTS_TABLE}` | the `{0,1,2}` cross-cutting agents: `<reviewer>` (quality/correctness 2nd pass) + `<ARBITER_AGENT>` (boundary/architecture arbiter + Phase-3 validator), each with an "include WHEN" rule |
 | `{RULE_POINTER_TABLE}` | one row per real `.codex/rules/*.md` + `.codex/convention/*.md`: `\| <file> \| <one-line gist> \|` — REFERENCE, never restate |
 | `{RULE_PREFLIGHT_LIST}` | the bash `for f in ...; do [ -f "$f" ] || echo "WARN missing rule: $f"; done` listing the SAME real rule files |
-| `{FILE_GROUP_MAP}` | one row per source group: `\| <group> \| <path pattern> \| <subagent_type> \|` mapping each group to its domain owner; tests group -> the test agent (with test-bloat audit); build group -> the CI/build agent |
+| `{FILE_GROUP_MAP}` | one row per source group: `\| <group> \| <path pattern> \| <subagent_type> \|`; tests group -> the test agent (with test-bloat audit); build group -> the CI/build agent |
+| `{GATE_COMMANDS}` | the REAL gate block: captured exit codes, a subshell for any `cd`, a guard that SKIPS the gates when the toolchain/deps are missing, and one `GATE <name> OK\|FAIL (exit N)` line per gate. Never a bare `cmd \| tail && echo OK` (that reports `tail`'s status) |
 | `{FOCUS_TABLE}` | the ranked focus ordering (default: 1 correctness, 2 architecture/boundary, 3 reuse, 4 version pins, 5 business-reqs), REORDERED per the `<fine-tune-prompt>` |
 | `{FOCUS_EMPHASIS}` | one-line note capturing the fine-tune-prompt emphasis (or "default ordering" if none) |
-| `{SIMPLIFY_AGENTS}` | comma list of the domain-owner agents the fix-session should delegate to |
+| `{SIMPLIFY_AGENTS}` | comma list of the domain-expert agents the fix-session should delegate to |

-> Keep every emitted row pointing at a REAL agent (`.codex/agents/` or built-in `Explore`/`Plan`/`general-purpose`) and a REAL rule
-> file. Do NOT invent agents or rules. Built-in `Explore` is the only allowed fallback for an unavailable domain agent.
+**In `<target>/.codex/skills/superreview/references/scope.md`:**
+
+| Block placeholder | Replace with |
+|-------------------|--------------|
+| `{TEAM_NOTE}` | one line on why blast radius matters HERE — e.g. "N people work this repo in parallel" (from `git shortlog -sn --since=3.months`), or "the shared surfaces below are consumed by other services" for a solo repo |
+| `{BASELINE_RESOLUTION_BASH}` | the REAL resolution block: derive the issue id from the branch with an ANCHORED pattern (`^[a-z]+/([0-9]+)(-.*)?$`, never a bare digit run), read the task file / board, read the issue + its declared neighbours READ-ONLY, read the PR, read the decisions log, and read commit intent from `$RANGE` (report "not read" when unset). Degrade to `UNKNOWN` instead of inventing |
+| `{SANCTION_PRECEDENCE_TABLE}` | the precedence table for THIS project: user directive (1) > recorded decision / issue comment (2) > issue body + task acceptance (3) > docs decision log (4) > PR body / commit message (5, sanctions NOTHING — it is the artefact under review) |
+| `{OWNERSHIP_SIGNALS_BASH}` | the runtime ownership probe: recent authors (`git log -5 --format='%an' -- "$f"`) + any other task claiming the file, with a declared truncation bound |
+| `{SHARED_SURFACES_TABLE}` | the concrete always-shared surfaces of THIS repo (public API/contract dirs, migrations, schema/registry files, CI workflows, dependency manifests, design tokens) |
+
+> Keep every emitted row pointing at a REAL agent (`.codex/agents/` or built-in `Explore`/`Plan`/`general-purpose`), a
+> REAL rule file, a REAL path and a REAL command. Do NOT invent agents, rules or gate scripts. Built-in `Explore` is
+> the only allowed fallback for an unavailable domain agent.

 ### Phase 4 — Validate (NO `{PLACEHOLDER}` may remain)

@@ -148,9 +231,10 @@ EMITTED `<target>/.codex/skills/superreview/SKILL.md` with a table you build fro
 bash "<skill-directory>/scripts/generate.sh" validate && echo "✅ validate" || echo "❌ validate FAILED"
 ```

-> **STOP if ❌** — the script lists any unresolved setup-time `{PLACEHOLDER}` left in the emitted SKILL.md / references
-> (runtime tokens like `{MODE}`, `{COUNT}`, `{FILE_LIST}` are allow-listed and expected to remain). Go back to Phase 3
-> and Edit the leftovers, then re-run validate.
+> **STOP if ❌** — validate reports three classes of failure: an unresolved setup-time `{PLACEHOLDER}` (runtime
+> tokens like `{MODE}`, `{COUNT}`, `{FILE_LIST}`, `{SCOPE_BASELINE}` are allow-listed and expected to remain), an
+> agent name that resolves to nothing, and **no project domain expert wired at all**. Fix via Edit (or go back to
+> Phase 1.6 and create the experts), then re-run validate.

 ### Phase 5 — Report

@@ -159,16 +243,20 @@ Print the generation summary:
 ```
 superreview generated -> <target>/.codex/skills/superreview/

-Stack:      {STACK_LABEL}  (reference: {STACK_REF})
-Domain agents wired: {N}  ({list})
+Stack:          {STACK_LABEL}  (reference: {STACK_REF})
+Domain experts: {N} wired ({list}){; created this run: <list>}{; DEGRADED groups: <list>}
 General agents: {reviewer?}, {ARBITER_AGENT} (arbiter + validator)
-Rule pointers: {N} files referenced (not restated)
-File groups:   {N}  ({group->agent})
-Focus:         {resolved ordering — fine-tune: <emphasis>}
+Scope baseline: {TRACKER_LABEL}; passes A={SCOPE_AGENT_A} / B={SCOPE_AGENT_B}
+Shared surfaces: {N} listed in references/scope.md
+Mechanical gates: {list of commands}
+Rule pointers:  {N} files referenced (not restated)
+File groups:    {N}  ({group->agent})
+Focus:          {resolved ordering — fine-tune: <emphasis>}

 Files written:
 - .codex/skills/superreview/SKILL.md
 - .codex/skills/superreview/references/agent-prompt.md
+- .codex/skills/superreview/references/scope.md
 - .codex/skills/superreview/references/report-template.md
 - .codex/skills/superreview/references/{STACK_REF}

@@ -183,11 +271,14 @@ Recap of the canonical shape the emitted SKILL.md implements (full text in `refe

 | Phase | Behavior |
 |-------|----------|
-| Mode detection | Deterministic `FULL_PROJECT \| EXPLICIT \| UNCOMMITTED \| LAST_COMMITS`, COMPUTED not guessed; then ANNOUNCE mode+branch+scope+count+focus BEFORE any review |
-| Routing | Group changed files by path; enable ONLY non-empty groups; route each to its domain-owner agent; add `{0,1,2}` general agents by judgement |
-| Fan-out | ONE parallel message with the selected agents (find phase); each returns the shared JSON finding contract; search-first before flagging reuse/duplication |
-| Validation | ONE arbiter agent reverse-validates EVERY candidate (adversarial, per-finding gate), merges + de-dups + prioritizes P0-P3 |
-| Report | ONE merged report at `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`, sorted P0->P3; READ-ONLY; recommends `/simplify` + a Manager-mode fix session; never edits code |
+| Mode detection | Deterministic `FULL_PROJECT \| EXPLICIT \| UNCOMMITTED \| LAST_COMMITS`, COMPUTED not guessed; corpus = git-tracked-or-will-be (ignored = OUT); then ANNOUNCE mode+branch+scope+count+focus+gates+baseline+experts BEFORE any review |
+| Mechanical gates | Real build/lint/type/test run FIRST; their output is `CONFIRMED-BY-EXECUTION` (the only non-adversarial verdict), passed to every agent so nobody re-runs them |
+| Scope baseline | sub-agent task + issue + recorded decisions resolved read-only; no baseline -> `UNKNOWN` and a PERMANENT P2 cap on scope findings |
+| Routing | Experts selected at RUNTIME from the live roster; enable ONLY non-empty groups; recon agents excluded; no owner -> `Explore` + DEGRADED marker; add `{0,1,2}` general agents by judgement |
+| Fan-out | ONE parallel message: domain experts + scope pass A (diff side, shapes 1-6) + scope pass B (baseline side, delivery D1-D4 + closeout C1-C4); shared JSON finding contract; search-first before flagging reuse/duplication |
+| Validation | A NON-OWNING validator reverse-validates EVERY candidate (adversarial, per-finding gate, batched <=40), merges + de-dups + prioritizes P0-P3; unvalidatable -> `UNVALIDATED` and the run is `INCOMPLETE` |
+| Scope gate | `request_user_input` on unsanctioned expansion / unproven absence; rewrites priorities only, never adds findings, never lifts the UNKNOWN cap |
+| Report | ONE merged report at `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`, sorted P0->P3, every row carrying its verdict, with a Scope Discipline / Blast Radius section; READ-ONLY; recommends `/simplify` + a Manager-mode fix session; never edits code |

 ---

@@ -199,7 +290,10 @@ Recap of the canonical shape the emitted SKILL.md implements (full text in `refe
 | Emit templates | `<skill-directory>/references/` | Source templates for the generation |
 | Generation script | `<skill-directory>/scripts/generate.sh` | `scan` \| `emit` \| `validate` |
 | Stack reference | one of `python.md \| java-kotlin.md \| typescript-react.md \| go.md` | Emitted per the dominant detected stack |
-| Block placeholders | AI-filled (Edit) | Tables that cannot go through sed; validated post-emit |
+| Domain experts | MANDATORY (Phase 1.6) | gaps are filled via `brewcode:agent-creator`; `validate` fails with zero experts unless `SUPERREVIEW_ALLOW_NO_EXPERTS=1` |
+| Scope reference | `references/scope.md` (always emitted) | baseline + ownership + taxonomy + delivery + closeout + gate |
+| Scope agents | `SCOPE_AGENT_A` tracker owner, `SCOPE_AGENT_B` read-only searcher | default `Explore` for both |
+| Block placeholders | AI-filled (Edit) | Tables + bash blocks that cannot go through sed; validated post-emit |

 ---

@@ -207,7 +301,11 @@ Recap of the canonical shape the emitted SKILL.md implements (full text in `refe

 | Condition | Action |
 |-----------|--------|
-| No `.codex/agents/` in target | Emit with built-in `general-purpose` + `Explore` only; warn the user the routing is generic |
+| No `.codex/agents/` in target | Phase 1.6: offer to CREATE the domain experts (`brewcode:agent-creator`). Declined -> emit with `Explore`/`general-purpose`, mark every group DEGRADED, and run validate with `SUPERREVIEW_ALLOW_NO_EXPERTS=1` |
+| Some groups have no owner | Create the missing experts (Phase 1.6); declined -> that group is `Explore` + DEGRADED in `DOMAIN_AGENTS_TABLE` and in the Phase 5 summary |
+| Only recon agents match a group | Never route source review to them — treat the group as uncovered (create an expert or mark DEGRADED) |
+| No tracker / no issues in target | `TRACKER_LABEL="none"`; emit the scope reference anyway — the emitted skill resolves `UNKNOWN` and caps scope findings at P2 (documented, not silent) |
+| Gate commands unclear | Ask (Phase 1.5); CI config is the tie-break. Never emit an invented script name — an emitted gate that does not exist reports `not run` forever |
 | No `.codex/rules/`/`.codex/convention/` | Emit a minimal rule-pointer table (`AGENTS.md` only); WARN; the emitted skill degrades gracefully (preflight WARN) |
 | Unknown / unsupported stack | Emit with the closest per-stack ref + project rules only; warn |
 | Multi-stack repo | Pick dominant stack for `STACK_REF`; note secondaries in the agent/group tables |
@@ -218,22 +316,29 @@ Recap of the canonical shape the emitted SKILL.md implements (full text in `refe

 ## References

- `references/SKILL.md.template` — the finagra-shape emitted SKILL.md (placeholder slots).
- `references/agent-prompt.md` — domain-owner agent prompt contract (emitted).
+- `references/SKILL.md.template` — the emitted SKILL.md (placeholder slots).
+- `references/agent-prompt.md` — runtime expert-selection procedure + domain-owner prompt contract (emitted).
+- `references/scope.md.template` — scope discipline: baseline, ownership, taxonomy, delivery, closeout, gate (emitted).
 - `references/report-template.md` — emitted merged-report layout.
 - `references/{python,java-kotlin,typescript-react,go}.md` — per-stack reference docs (one is emitted).
- `scripts/generate.sh` — `scan` / `emit` / `validate`.
+- `scripts/generate.sh` — `scan` / `emit` / `validate` (validate also enforces the domain-expert requirement).

 <!--
 SKILL METADATA — brewcode:superreview (GENERATOR)

 HUMAN-invoked generator. Analyzes a target project and emits a self-contained project-local deep-review skill
-(review + standards-review merged) modeled on the canonical finagra shape. Stack-generic (Java/Kotlin, Node/TS,
-Python, Go). The EMITTED skill is the one that reviews code; this skill only writes it.
+(review + standards-review merged) on the canonical shape. Stack-generic (Java/Kotlin, Node/TS, Python, Go).
+The EMITTED skill is the one that reviews code; this skill only writes it.
+
+Two non-negotiables: DOMAIN EXPERTS (Phase 1.6 discovers gaps and creates the missing agents; validate enforces
+>=1 wired expert) and SCOPE DISCIPLINE (references/scope.md.template — baseline, ownership, 6-shape taxonomy,
+delivery D1-D4 with proof-of-absence, closeout C1-C4, Phase 3b gate).

 Re-run triggers:
 - New/renamed agent in target .codex/agents/  -> re-emit to refresh routing
 - New rule/convention file                      -> re-emit to refresh pointers
 - Stack change / new source group               -> re-emit
+- Tracker / branch convention changed           -> re-emit to refresh the scope baseline block
+- New always-shared surface                     -> re-emit (or Edit references/scope.md section 2)
 -->

@@ -1,6 +1,6 @@
 interface:
  display_name: "Superreview"
-  short_description: "Generates a project-tailored deep-review skill (review+standards"
+  short_description: "Generates a project-tailored deep-review skill: domain-expert ro"
  default_prompt: "Use $brewcode:superreview for this task."
 policy:
  allow_implicit_invocation: true
@@ -1,6 +1,6 @@
 ---
 name: superreview
-description: "Deep {PROJECT_NAME} code review the MODEL or the USER can invoke: routes changed files to domain-owner agents, checks correctness + architecture + reuse + version pins against the project rules, reverse-validates every finding, writes one merged report. Triggers: review code, deep review, superreview, super review, validate changes, check architecture, check standards, check reuse."
+description: "Deep {PROJECT_NAME} code review the MODEL or the USER can invoke: routes changed files to domain-expert agents, runs the mechanical gates, checks correctness + architecture + reuse + version pins + scope discipline (blast radius vs the sanctioned task/issue) against the project rules, reverse-validates every finding, writes one merged report. Triggers: review code, deep review, superreview, super review, validate changes, check architecture, check standards, check reuse, check scope, blast radius, scope creep."
 user-invocable: true
 argument-hint: "<prompt-or-file-path> [scope: commit|branch|folder]"
 ---
@@ -10,20 +10,31 @@ argument-hint: "<prompt-or-file-path> [scope: commit|branch|folder]"
 **ROLE:** Self-contained deep-review coordinator + final validator.
 **OUTPUT:** ONE merged, de-duplicated, severity-prioritized, validated report.

-The most thorough review in this repo, run INLINE — no sibling skills, no plugin dependency. It:
+The most thorough review in this repo, run INLINE — no sibling skills, no plugin dependency.

-0. **deterministically resolves ONE review MODE** and ANNOUNCES it to the user (mode + branch + concrete scope)
-   BEFORE any review work — no interactive guessing,
-1. routes each changed file to its **domain-owner agent** (uses project agents to the MAX),
-2. checks **functional correctness + architecture + reuse + version pins + business-requirements** against the
-   focus ordering below (folds in the old standards-review + review essence),
-3. runs a **single, targeted, parallel fan-out** — only the agents the changed files actually need (FEWER spawns
-   than a multi-vote quorum + a separate standards pass + a separate arbiter),
-4. ends with a **VALIDATION phase**: a per-finding adversarial double-check that re-verifies EVERY candidate is
-   REAL (rejects false positives) BEFORE it lands in the report, then merges + checks consistency.
+| # | Step |
+|---|------|
+| 0 | Deterministically resolve ONE review MODE; ANNOUNCE it (mode + branch + concrete scope) before any review work — no interactive guessing |
+| 1 | Run the MECHANICAL GATES (build/lint/test) — execution output is `CONFIRMED-BY-EXECUTION`, the ONE verdict needing no adversarial pass |
+| 2 | SELECT domain experts at RUNTIME from the live agent roster (`.codex/agents/*.toml`) and route each changed-file group to its best-matching owner — a newly added agent is picked up automatically |
+| 3 | Check the focus ordering below: principle/architecture conformance -> correctness -> reuse -> pins -> style |
+| 4 | Resolve the SANCTIONED SCOPE baseline (task + issue + recorded decisions); audit scope creep / blast radius / under-delivery — an unsanctioned touch is a first-class finding, not a nitpick |
+| 5 | Run ONE targeted parallel fan-out — only the agents the changed files actually need |
+| 6 | VALIDATION: per-finding adversarial re-verification of EVERY candidate, then an request_user_input gate on unsanctioned scope expansion, then merge + consistency check |

 > Two-phase by design: **find -> validate**. Only findings that survive per-finding reverse-validation are reported.

+> **Domain experts are the point.** A review run by generic agents finds generic issues. Every non-empty file group
+> goes to the agent that OWNS that surface; the built-in `Explore` is a graceful fallback, never the plan.
+
+> **Bash-first:** some macOS builds ship no native `Grep`/`Glob` tool. Every command here is shell-based
+> (`git`, `rg`/`grep`); agents are told the same.
+
+> **Single-source rule (applies to this file):** the domain-owner prompt contract + the runtime expert-selection
+> procedure live ONCE in `references/agent-prompt.md`; the sanctioned-scope resolution, ownership map, creep
+> taxonomy, delivery/closeout maps and the user gate live ONCE in `references/scope.md`; stack specifics live ONCE
+> in `references/{STACK_REF}`. This file POINTS at them. Where a subagent needs one, pass the PATH, never pasted prose.
+
 All agents are project-local (`.codex/agents/`) or a built-in (`Explore`/`Plan`/`general-purpose`). This skill
 never invokes any sibling skill, NO plugin cache; the validator/arbiter fallback is the
 built-in `general-purpose`.
@@ -40,35 +51,59 @@ the same rule applies on `master`/`main` and on feature branches.

 | # | Condition (checked in order) | Resolved `{MODE}` | Scope reviewed |
 |---|------------------------------|-------------------|----------------|
-| 1 | User prompt asks for the WHOLE project, in any language ("whole project", "entire project", "everything", "all the code", or the same intent in another language) | `FULL_PROJECT` | ALL tracked `{SOURCE_GLOB}` + build/CI files in the repo |
+| 1 | User prompt asks for the WHOLE project, in any language ("whole project", "entire project", "everything", "all the code", or the same intent in another language) | `FULL_PROJECT` | the WHOLE corpus matching `PATHSPEC` — tracked + untracked-but-not-ignored source, config, docs |
 | 2 | User passed an explicit scope token (commit SHA, branch name, or folder path) | `EXPLICIT` | that commit / branch-vs-main / folder |
 | 3a | DEFAULT + working tree has UNCOMMITTED changes (`git status --porcelain` non-empty) | `UNCOMMITTED` | working-tree diff vs `HEAD` |
 | 3b | DEFAULT + clean tree (everything committed) | `LAST_COMMITS` | last 1-2 commits: `HEAD~2..HEAD` if it exists, else `HEAD~1..HEAD`, else the single root commit |

 > A text prompt that is NOT a whole-project request and NOT a scope token is treated as a `{FOCUS}` directive
 > (see Focus below); the mode still resolves via rule 3.
+> Scope-token test (deterministic, this order): `[ -d "$TOK" ]` -> EXPLICIT folder; `[ -f "$TOK" ]` -> EXPLICIT
+> single file; `git rev-parse -q --verify "$TOK^{commit}"` succeeds -> EXPLICIT commit/branch; else -> `{FOCUS}`.
+
+### What the review corpus IS — the single rule: git TRACKING, not commit status
+
+**IGNORED = OUT. Everything else = IN.** One rule, applied everywhere:
+
+| | Rule |
+|---|------|
+| **OUT** | anything git does not track and never will — ignored by `.gitignore` OR by `.git/info/exclude`. Both matter equally, and `.git/info/exclude` is invisible in the tree, so it is the one people forget. Never enumerate either list from memory — ask git |
+| **IN** | everything git tracks OR will track. Commit status is irrelevant: staged, modified and untracked-but-not-ignored files are all IN |
+| Instrument | `git ls-files --others --exclude-standard` honours `.gitignore` AND `.git/info/exclude` in one call — **never drop that flag** to reach an ignored path |
+
+Consequence: an instruction file that is git-ignored (`.codex/**`, `AGENTS.md`, task-board files where the project
+ignores them) is never a review TARGET — it is the AUTHORITY reviewers cite, and the task board is the scope
+BASELINE input. Tracked docs are reviewed normally. There is therefore no separate ignored-path sweep anywhere.

 **Mode-resolution commands** (runnable as-written; `PATHSPEC` = the file globs every mode reviews):

 ```bash
+# leading * is REQUIRED on nested patterns: git pathspecs are root-anchored.
 PATHSPEC=({PATHSPEC_GLOBS})

 BRANCH=$(git rev-parse --abbrev-ref HEAD)
 PORCELAIN=$(git status --porcelain)
-# robust MAIN fallback: the `|| echo main` must bind to git, not sed
+# MAIN = default-branch name; the fallback binds to git, never to a pipeline stage
 MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null); MAIN=${MAIN##*/}; MAIN=${MAIN:-main}

 # Resolve FILES for the chosen mode, then derive an EXACT count (no head-truncation of the count).
-# FULL_PROJECT (rule 1): all tracked source + build/CI files
-FILES=$(git ls-files -- "${PATHSPEC[@]}")
+# CORPUS = tracked + untracked-but-not-ignored (the single tracking rule above).
+CORPUS() { { git ls-files -- "${PATHSPEC[@]}"; git ls-files --others --exclude-standard -- "${PATHSPEC[@]}"; } | sort -u; }

-# EXPLICIT commit (rule 2):  FILES=$(git diff --name-only "${SHA}^..${SHA}" -- "${PATHSPEC[@]}")
-# EXPLICIT branch (rule 2):  FILES=$(git diff --name-only "${MAIN}...HEAD" -- "${PATHSPEC[@]}")
-# EXPLICIT folder (rule 2):  build files are included too, not just source
-# FILES=$(find "$FOLDER" -type f \( -name '{SOURCE_GLOB}' -o -name 'Dockerfile*' -o -name 'docker-compose.yml' -o -name '*.yml' \))
+# FULL_PROJECT (rule 1): the whole corpus — source + build/CI + tracked docs
+FILES=$(CORPUS)

-# UNCOMMITTED (rule 3a): working-tree diff vs HEAD (staged + unstaged)
-# FILES=$(git diff --name-only HEAD -- "${PATHSPEC[@]}")
+# EXPLICIT commit (rule 2), parentless-safe (root commit OK):
+# FILES=$(git show --name-only --pretty="" "${TOK}" -- "${PATHSPEC[@]}")
+# EXPLICIT branch (rule 2) — diff the NAMED branch $TOK, never HEAD; prefer the remote ref:
+# FILES=$(git diff --name-only "origin/${MAIN}...${TOK}" -- "${PATHSPEC[@]}" 2>/dev/null \
+#         || git diff --name-only "${MAIN}...${TOK}" -- "${PATHSPEC[@]}")
+# EXPLICIT folder / single file (rule 2): the corpus, filtered — never raw find (build-output junk).
+# FILES=$(CORPUS | grep "^${TOK%/}/")                                   # single file: FILES="$TOK"
+
+# UNCOMMITTED (rule 3a): staged + unstaged + UNTRACKED-not-ignored (porcelain counts ?? files, so the scope must too)
+# FILES=$( { git diff --name-only HEAD -- "${PATHSPEC[@]}"; git ls-files --others --exclude-standard -- "${PATHSPEC[@]}"; } | sort -u )
+# Dirty tree but FILES empty (only ignored/out-of-scope files) -> fall through to LAST_COMMITS (rule 3b).

 # LAST_COMMITS (rule 3b): nested fallback so a single-commit repo never errors
 # if HEAD~2 exists -> HEAD~2..HEAD ; elif HEAD~1 exists -> HEAD~1..HEAD ; else the single root commit
@@ -80,20 +115,16 @@ FILES=$(git ls-files -- "${PATHSPEC[@]}")
 #   FILES=$(git show --name-only --pretty="" HEAD -- "${PATHSPEC[@]}")   # root commit
 # fi

+# RANGE = the commit range of the chosen mode. EXPORT it — references/scope.md step e reads commit intent from it
+# and reports "not read" rather than guessing when it is unset. FULL_PROJECT / UNCOMMITTED have no range: leave empty.
+# export RANGE="HEAD~2..HEAD" | "$TOK^!" | "origin/${MAIN}...${TOK}" | ""
+
 # EXACT count for the mandatory announcement (count, never the displayed list, is truncated):
 COUNT=$(printf '%s\n' "$FILES" | grep -c .)
 echo "$FILES" | head -50   # DISPLAY only — truncating the shown list is fine; COUNT above stays exact
 ```

-**MANDATORY announcement to the user (before reviewing):**
-
-```
-superreview MODE = {MODE}
-Branch: {BRANCH}
-Scope: {commit range | branch-vs-main | folder path | working-tree diff vs HEAD | full project}
-Files: {COUNT} ({list, or "see range"})
-Focus: {resolved focus — user directive, else default ordering}
-```
+**MANDATORY announcement before reviewing — exact template in Phase 0 step 7 (single source).**

 ---

@@ -106,15 +137,40 @@ order (highest first). Bake this exact ordering into BOTH the shared agent promp

 > **Project emphasis:** {FOCUS_EMPHASIS}

+> **SCOPE DISCIPLINE / minimal blast radius is part of focus rank 1 — never optional.** Measure every change
+> against the SANCTIONED baseline (Phase 0 step 5: task + issue + recorded decisions). Beyond it = `scope-creep`,
+> up to **P0**: shared contract / schema / migration / registry / CI edit, another owner's surface, past-acceptance
+> feature, drive-by refactor, doc silently rewritten to match code. The INVERSE ranks equally: an undelivered
+> acceptance criterion or an unrecorded scope reduction is **P0**. Correctness-driven overlap into a neighbour's
+> task is legit if recorded. Taxonomy, delivery/closeout maps, exclusion list and the user gate: `references/scope.md`.
+
 > **Security is explicitly NOT a priority.** Report a security finding ONLY when it is CRITICAL (P0) — e.g. logged
 > secret, missing auth on a public path, injection. Do NOT spend agent effort on low/medium security.

+> **SCALE CALIBRATION (every rank).** Judge harm against this project's REAL scale, not a hypothetical one. Harm
+> reachable only via concurrency / load / contention the system does not have -> P3 or DROP. A race claim MUST
+> state its traffic assumption ("same millisecond" is not one). Correctness invariants (constraints, unique keys,
+> state machines) are untouched by this calibration.
+
 ---

-## Project Agents (project-local + built-in ONLY)
+## Domain experts — selected at RUNTIME from the live roster
+
+The skill picks its own experts each run. The table below is the EXPECTED RESULT as of generation time, not a
+frozen contract: **READ `references/agent-prompt.md` FIRST and EXECUTE its "Dynamic expert selection" procedure** —
+it holds the roster command, the recon-agent exclusion list, the selection steps and the fallback chain. On any
+disagreement between the table and the live roster, **the live roster wins**.
+
+| Guard | Rule |
+|-------|------|
+| Domain expert first | every non-empty file group goes to the agent whose description claims that path/responsibility MOST specifically. A generic agent on a domain surface is a DEGRADED run — say so in the report |
+| Recon agents excluded | read-only external-system agents (cloud/SaaS/DB consoles, ticket readers) never review source files — list in `references/agent-prompt.md` |
+| No confident match | built-in `Explore` (read-only); note the fallback in the report |
+| Auditability | record the DERIVED map in the report's `Agents run` line |
+| Model override | do NOT pass a `model` override — project agents define their own |

 > Every `subagent_type` below resolves to a real file in `.codex/agents/`, or a built-in (`Explore`/`Plan`/`general-purpose`).
-> Do NOT pass a `model` override to project agents — they define their own. NO external/plugin agent is referenced.
+> NO external/plugin agent is referenced.

 {DOMAIN_AGENTS_TABLE}

@@ -141,44 +197,121 @@ One-line gist per pointer only — the file is the authority. Phase 0 PREFLIGHT-

 ---

+## Delegation (applies to EVERY sub-agent task this skill spawns)
+
+A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct it, and it
+usually drifts off-target. One subagent = ONE bounded unit — one deliverable (here: ONE file group's review),
+~<=5 files, ~<=10 steps. Bigger MUST be split into N tasks, all spawned in ONE message — split an oversized
+group into two groups rather than handing one agent half the repo.
+
+Every spawn prompt MUST carry:
+
+| Field | Content |
+|-------|---------|
+| GOAL | the overall task and why it exists — the point beyond the file edit |
+| ROLE | what this agent owns; what it must NOT touch |
+| SCOPE | exact paths/commands in bounds + explicit out-of-bounds |
+| CONTEXT | what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs |
+| CONSUMER | who or what uses the result next, and the shape it must fit |
+| DONE | acceptance criteria + the exact report shape you want back |
+
+A bare one-line task is never enough. Phase 2 fills these from `references/agent-prompt.md`; Phase 3 fills them
+for the validator.
+
+---
+
 ## Execution

-### Phase 0 — Preflight, Resolve MODE, ANNOUNCE, read references
+> **VALIDATION INVARIANT (binding on every phase below).** No finding is reported without a verdict. The verdict is
+> either the Phase 3 adversarial validation (`CONFIRM`) or, for mechanical gate output alone, execution itself
+> (`CONFIRMED-BY-EXECUTION`, citing the command and its output) — that is the ONLY non-adversarial verdict this
+> skill permits. A finding that could not be validated carries `verdict: UNVALIDATED` — claiming nothing — and
+> forces an `INCOMPLETE` run. Every report table is a VIEW over the merged set `{MERGED}`, never a paste of raw
+> Phase 2 candidates, and the unvalidated count appears in the report AND the chat summary, so a degraded run can
+> never look clean.

-1. **PREFLIGHT — validate the rule files before relying on them.** Verify the canonical rule/convention files
-   referenced above EXIST; WARN per missing file and degrade gracefully (do NOT hard-fail):
+### Phase 0 — Preflight, MODE, MECHANICAL GATES, SCOPE BASELINE, ANNOUNCE
+
+1. **PREFLIGHT — validate the files this run DEPENDS ON.** Two classes: the assets this skill EXECUTES against (a
+   missing one silently guts a whole phase) and the rule files reviewers cite. WARN per missing file; degrade
+   gracefully, do NOT hard-fail:

 ```bash
+S=".codex/skills/superreview"
+for f in "$S/references/agent-prompt.md" "$S/references/scope.md" "$S/references/{STACK_REF}" \
+         "$S/references/report-template.md"; do
+  [ -f "$f" ] || echo "WARN missing EXECUTED asset: $f (the phase that uses it degrades — say so in the report)"
+done
+
 {RULE_PREFLIGHT_LIST}
 ```

 2. **Resolve `{MODE}` + `{FOCUS}`** per the **Mode Detection** and **Focus** sections above (deterministic; not
-   interactive). Run the mode-resolution commands to get `{BRANCH}`, `{SCOPE}`, the `FILES` list, and EXACT `COUNT`.
-3. Compute a single `TIMESTAMP` for the report dir:
+   interactive). Run the mode-resolution commands to get `{BRANCH}`, `{SCOPE}`, `FILES`, EXACT `COUNT`, and export
+   `RANGE` (the resolved commit range) for `references/scope.md` step `e`.
+3. **Derive the expert map** — READ `references/agent-prompt.md`, run its roster command, build the group -> agent
+   map from the LIVE roster. Mark any group that fell back to a generic agent as DEGRADED.
+4. **MECHANICAL GATES (ground truth).** Run the project's real gates BEFORE the fan-out; their output is FACT, not
+   opinion. The block is HARD-GUARDED with captured exit codes (a pipe into `tail` would report `tail`'s status)
+   and runs in a SUBSHELL (the shell keeps cwd between calls, so a bare `cd` would re-root every later command):
+
+```bash
+{GATE_COMMANDS}
+```
+
+   | Rule | Detail |
+   |------|--------|
+   | Ground truth | a real gate error carries verdict **`CONFIRMED-BY-EXECUTION`**: the tool ran it and the output IS the proof. That verdict IS its validation — not an exemption from the invariant. Every such row MUST cite the command AND the output line |
+   | Priority | a hard-rule / boundary error from the gate = **P0**; other build/lint/type/test failures = **P1** |
+   | Missing deps | toolchain or dependencies absent -> the guard SKIPS the gates; record `Gates: not run (<reason>)`. **Never invent gate results** |
+   | Exit code only | report a gate OK only on an explicit `GATE <g> OK`. Never infer success from quiet output |
+   | Scope | gates run repo-wide; attribute a gate finding to a reviewed file only when the file appears in `FILES` — otherwise list it under "Pre-existing gate failures" and still report it (noticed -> owned) |
+   | No re-run | pass `{GATE_RESULTS}` to every agent so nobody re-runs or re-litigates them |
+
+5. **SCOPE BASELINE (what this change was SANCTIONED to touch).** READ `references/scope.md` and run its section 1
+   resolution block. Output is `{SCOPE_BASELINE}` — task id + file, issue id + acceptance criteria, recorded
+   decisions, the sanctioned file surface — plus `{OWNERSHIP}` (section 2) for every file in `FILES` outside it,
+   and `{PR_ISSUE_JSON}` — the RAW issue/PR data fetched once here (or `none` / `not reached`). `{SCOPE_BASELINE}` +
+   `{OWNERSHIP}` go to Phase 2 and to the validator; `{PR_ISSUE_JSON}` goes to scope pass B so nothing re-fetches it.
+
+   | Rule | Detail |
+   |------|--------|
+   | Board = INPUT, never a subject | task-board / planning files are read here as the BASELINE: never in `FILES`, never routed to an owner, never a finding target |
+   | Read-only on the tracker | view issues/PRs only. Never create, edit, comment on or close anything |
+   | Never invent | no task + no issue -> `{SCOPE_BASELINE} = UNKNOWN`; scope findings cap at P2 **permanently** — the Phase 3b gate may lower further but never restores a pre-cap priority |
+   | Precedence | `references/scope.md` section 1 table. A PR body / commit message sanctions NOTHING — it is the artefact under review |
+   | FULL_PROJECT | no single task exists -> scope axis is INFORMATIONAL: scope pass A only (shapes 3/4); pass B is SKIPPED. Say so in the report |
+
+6. Compute a single `TIMESTAMP` for the report dir:

 ```bash
 TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
 ```

-4. **ANNOUNCE to the user** (MANDATORY, before any review) the resolved mode block — `{COUNT}` is the EXACT count
-   computed in Mode Detection (never truncated); include any `WARN missing rule` lines:
+7. **ANNOUNCE to the user** (MANDATORY, before any review). `{COUNT}` is the EXACT count from Mode Detection (never
+   truncated); include any `WARN missing` lines:

 ```
-superreview MODE = {MODE}
+superreview MODE = {MODE} ({which rule resolved it: whole-project request | explicit token | dirty tree | clean tree})
 Branch: {BRANCH}
 Scope: {commit range | branch-vs-main | folder | working-tree diff vs HEAD | full project}
 Files: {COUNT} ({displayed list — may be truncated; COUNT stays exact})
 Focus: {resolved focus — user directive, else default ordering}
-Rules preflight: {OK | "WARN missing: <files>"}
+Gates: {gate name} {OK|FAIL|not run} / ...
+Scope baseline: task {T-ID} | none  /  issue {id} ({title}) | not reached | none  /  {K} of {COUNT} files outside the sanctioned surface
+Experts (derived from live roster): {group -> agent, ...}{, DEGRADED: <group> -> generic}
+Preflight: {OK | "WARN missing: <files>"}
 ```

-5. **READ** `references/{STACK_REF}` (relative to this skill dir) — {STACK_LABEL} stack guidelines passed to every
-   agent. Also note `references/agent-prompt.md` (the domain-owner prompt contract).
-6. If `FILES` is empty (`COUNT == 0`) -> **exit** ("Nothing to deep-review for {MODE} / {SCOPE}.").
-7. If `COUNT > 50` (and `{MODE}` != `FULL_PROJECT`) -> warn the user; suggest narrowing (per-folder or per-commit).
-   For `FULL_PROJECT`, proceed but warn it is a large, slower pass.
-8. Optionally study context with a few parallel read-only `Explore` agents (changed-file modules + `.codex/rules/**`).
-   This is context only, NOT findings.
+8. **READ** `references/{STACK_REF}` — {STACK_LABEL} stack guidelines. Agents get its PATH via the prompt contract
+   and read it themselves; never paste its content into a prompt. Same for `references/agent-prompt.md` and
+   `references/scope.md`.
+9. If `FILES` is empty (`COUNT == 0`) -> **exit** ("Nothing to deep-review for {MODE} / {SCOPE}.") — but still
+   report any gate failure from step 4.
+10. If `COUNT > 50` (and `{MODE}` != `FULL_PROJECT`) -> request_user_input: narrow the scope (per-folder / per-commit)
+    or proceed anyway. For `FULL_PROJECT`, proceed but warn it is a large, slower pass.
+11. Optionally study context with read-only `Explore` agents — at MOST 2, and only for `FULL_PROJECT` or an
+    unfamiliar area. Context only, NOT findings.

 ### Phase 1 — Agent selection (route changed files to domain owners)

@@ -187,15 +320,17 @@ Group the `{FILE_LIST}` by path. **Enable ONLY the groups whose files actually c

 {FILE_GROUP_MAP}

-PLUS up to two GENERAL cross-cutting agents (see **Project Agents** above). They are NOT auto-spawned every time;
+PLUS up to two GENERAL cross-cutting agents (see **Domain experts** above). They are NOT auto-spawned every time;
 **the model DECIDES** whether (and which) to include, by JUDGEMENT of the scope. Each, if included, runs ONCE over
 the full changed set (not per group).

-> Total spawns = (number of NON-EMPTY domain groups) + **{0, 1, or 2} general agents (model's call)**.
-> Examples: a tiny single-file tweak = its domain owner alone (**1 agent**); a change with non-trivial logic =
-> domain owner + `{VALIDATOR_AGENT}` (**2**); a change spanning multiple domains/abstractions = both domain owners +
-> `{ARBITER_AGENT}` (+ `{VALIDATOR_AGENT}` if logic is risky) (**3-4**). Far fewer than the old quorum + standards + arbiter
-> combo. If a mapped domain agent is unavailable, fall back to built-in `Explore`; note it in the report.
+> Total spawns = (NON-EMPTY domain groups) + the TWO scope passes (A diff-side, B baseline-side; A alone in
+> `FULL_PROJECT`) + **{0, 1, or 2} general agents (model's call)**.
+> Examples: a tiny single-file tweak = its domain owner + the scope passes; a change with non-trivial logic =
+> domain owner + `{VALIDATOR_AGENT}`; a change spanning multiple domains = both domain owners + `{ARBITER_AGENT}`.
+> A SMALL, single-domain, low-risk change MAY skip the general passes — **never a scope pass**: a small change is
+> exactly where an unnoticed foreign-surface edit hides, and a one-file diff is exactly where an undelivered
+> criterion hides. If a mapped domain agent is unavailable, fall back to built-in `Explore`; note it in the report.

 > **Test-bloat audit:** when the `tests` group is non-empty, its prompt MUST also audit for TEST OVER-PROLIFERATION
 > (LLMs over-write tests) — cite the project `testing` rule, do NOT restate it. Flag, as `category: test-quality`:
@@ -207,10 +342,13 @@ the full changed set (not per group).

 ### Phase 2 — ONE parallel fan-out (find candidates)

-Spawn ALL selected agents (the non-empty domain owners + whichever general agents the model chose in Phase 1) in
-**ONE message** (parallel). Use the prompt contract in `references/agent-prompt.md`: pass `{FILE_LIST}` (scoped to that
-group for domain owners; full set for any included general agent), the resolved `{FOCUS}`, and the
-`references/{STACK_REF}` guidelines. Each prompt MUST instruct the agent to **apply `.codex/rules/*` +
+Spawn ALL selected agents (the non-empty domain owners + the two scope passes + whichever general agents the model
+chose in Phase 1) in **ONE message** (parallel). Use the prompt contract in `references/agent-prompt.md` VERBATIM,
+substituting EVERY placeholder it contains — a template shipped with an unsubstituted placeholder sends the literal
+brace text to the agent: `{FILE_LIST}` (scoped to that
+group for domain owners; full set for any included general agent), the resolved `{FOCUS}`, `{GATE_RESULTS}`,
+`{SCOPE_BASELINE}` and `{OWNERSHIP}` (from Phase 0 step 5; `UNKNOWN` / `none` when unresolved — never leave the
+brace text in place), and the `references/{STACK_REF}` guidelines. Each prompt MUST instruct the agent to **apply `.codex/rules/*` +
 `.codex/convention/*` for its area and CITE the rule number it enforces** — the skill does NOT restate the rules; the
 agents read the canonical files. Each prompt MUST also embed the focus ordering verbatim so agents spend effort in
 priority order, and **report security findings ONLY when CRITICAL (P0)**. Each prompt MUST also include the
@@ -222,9 +360,9 @@ over-complexity`, citing the project best-practices + avoid rules. Every agent r
 {
  "findings": [{
    "file": "path/to/file{SOURCE_GLOB}", "lineStart": 42, "lineEnd": 45,
-    "category": "boundary|architecture|reuse|over-complexity|security|logic|persistence|test-quality|pins|style",
+    "category": "boundary|architecture|scope-creep|reuse|over-complexity|security|logic|persistence|test-quality|pins|style",
    "severity": "blocker|critical|major|minor",
-    "rule": "avoid#N|best-practices#N|architecture#N|containers#N|... or null",
+    "rule": "avoid#N|best-practices#N|architecture#N|containers#N|scope#<shape>|... or null",
    "title": "...", "description": "...", "suggestion": "...",
    "existing": "path|null", "reuse": "REUSE|EXTEND|CONSIDER|KEEP_NEW|null",
    "confidence": 0.85
@@ -232,23 +370,175 @@ over-complexity`, citing the project best-practices + avoid rules. Every agent r
 }
 ```

+**PLUS TWO DEDICATED SCOPE passes** (spawn BOTH in the SAME message as the rest of the fan-out). They are split by
+EVIDENCE SOURCE, not by axis: **A walks the DIFF inward** against the sanctioned surface, **B reasons from the
+BASELINE outward** and must SEARCH the corpus to settle an absence. Their rule-id spaces are disjoint — A emits
+`scope#<shape>` only, B emits `scope#D*` / `scope#C*` only — so neither can produce the other's finding. Neither is
+one of the {0,1,2} general passes. `{MODE}` = `FULL_PROJECT` -> run **pass A only**, restricted to shapes 3/4 and
+reported as INFORMATIONAL; **skip pass B** (no single task, so no criteria and no PR to close out).
+
+**Pass A — diff side.** Owner: `{SCOPE_AGENT_A}` (the agent that owns the task board / tracker read path; fall back
+to `Explore`):
+
+```
+Codex delegation brief (task_role="{SCOPE_AGENT_A}", message="
+## superreview — SCOPE pass A: DIFF SIDE (shapes 1-6, single axis)
+
+READ-ONLY run: audit ONLY the scope + blast radius OF THE CHANGED FILES. Do NOT edit the board, do NOT touch any
+file, do NOT create, edit or close an issue. Other agents own correctness, architecture and style; scope pass B
+owns delivery (scope#D*) and closeout (scope#C*) — do NOT score those and do NOT judge whether a criterion was
+delivered.
+
+READ (path only): .codex/skills/superreview/references/scope.md — section 2 (ownership map), section 3 (the
+6-shape taxonomy + severity map), section 4 (the binding NOT-creep exclusion list). Apply them verbatim.
+
+**Sanctioned baseline (already resolved in Phase 0 — re-verify anything you doubt, never widen it):**
+{SCOPE_BASELINE}
+**Ownership signals:** {OWNERSHIP}
+**Files changed:** {FILE_LIST}
+**Diff range:** {SCOPE}
+
+Per file: (1) is it inside the sanctioned surface implied by the acceptance criteria? (2) if not, is there a
+RECORDED decision sanctioning it (task notes / issue comment / docs decision log)? cite it; (3) if not, classify
+by shape 1-6 and score per the severity map; (4) name WHO ELSE is hit — other owner or shared surface.
+OVERLAP: a file owned by a neighbouring task is legitimate when the sanctioned deliverable cannot be correct
+without it AND the boundary is recorded (section 4) — unrecorded but correctness-driven overlap is shape 6, NEVER
+a shape-1 blocker.
+
+An unsanctioned edit to a shared surface is a P0, not a nitpick. But do not manufacture findings: the exclusion
+list in section 4 is binding, and a missing baseline caps you at P2.
+
+Report in the standard finding JSON, category \"scope-creep\", rule \"scope#<shape-number>\" ONLY. In every
+\"description\" state: the baseline source you checked against (task id / issue id / decision id / UNKNOWN), the
+shape id, and the owner or shared surface impacted. \"suggestion\" = split it out / revert it / record the decision.
+")
+```
+
+**Pass B — baseline side.** Owner: `{SCOPE_AGENT_B}`. Its core job is proving or disproving an ABSENCE across the
+whole corpus — a search problem, so a read-only searcher (built-in `Explore`) is a legitimate owner here. Delivery
+and closeout ride together: both reason from the baseline outward and share ONE tracker context, `{PR_ISSUE_JSON}`:
+
+```
+Codex delegation brief (task_role="{SCOPE_AGENT_B}", message="
+## superreview — SCOPE pass B: BASELINE SIDE (delivery scope#D*, closeout scope#C*)
+
+READ-ONLY run: audit ONLY whether the sanctioned scope was fully DELIVERED and correctly CLOSED OUT. Do not edit
+any file, do not touch the board, do not create, edit or close an issue, and do NOT re-fetch tracker data — the
+issue + PR data you need is pasted below. Scope pass A owns the changed-file shapes 1-6 — do NOT score those.
+
+You SEARCH the codebase; you do not read a diff. A criterion may be satisfied by code this change never touched,
+and a criterion delivered under a DIFFERENT NAME reads exactly like absence. Use `rg` / `grep` / `git ls-files`
+across the source tree AND the tests, by CONCEPT and by SYNONYM, before claiming anything is missing. Proving or
+disproving an absence IS the job, not a side task.
+
+READ (path only): .codex/skills/superreview/references/scope.md — section 3b (the DELIVERY map D1-D4 plus the
+mandatory PROOF OF ABSENCE rules) and section 4b (the CLOSEOUT map C1-C4). Apply them verbatim.
+
+**Sanctioned baseline (already resolved in Phase 0 — re-verify anything you doubt, never widen it):**
+{SCOPE_BASELINE}
+**Issue + PR data (fetched in Phase 0 — this is your whole tracker context; never re-fetch it):**
+{PR_ISSUE_JSON}
+**Files changed:** {FILE_LIST}
+**Diff range:** {SCOPE}
+
+DELIVERY (section 3b): score every acceptance criterion / issue done-when D1-D4 — full scope must be DELIVERED,
+and a reduction is clean ONLY when its blocker is recorded and named (then report it as an accepted reduction,
+not a finding).
+D1 and D4 are ABSENCE claims. Every scope#D* finding MUST carry, in \"description\": (a) the criterion QUOTED
+VERBATIM from the task/issue, and (b) the exact search command you ran and its empty result. No quote or no cited
+search = you may not claim P0: report it at P2 with \"deliveryProofMissing\": true, for the Phase 3b gate.
+CLOSEOUT (section 4b) — ONLY if the data above contains a PR, else record \"PR: none\" and skip it: PR body
+(shipped / deliberately NOT built / what consumers may rely on), the Closes-vs-Refs split, a closeout comment on
+every issue touched, AI attribution anywhere, and the short-and-clear bar in BOTH directions.
+
+Do not manufacture findings: a missing baseline caps you at P2, and an unquoted, unsearched absence is never P0.
+
+Report in the standard finding JSON, category \"scope-creep\", rule \"scope#D<n>\" | \"scope#C<n>\" ONLY.
+\"suggestion\" = deliver the criterion / record the blocker / fix the PR body or the Closes-Refs split / add the
+closeout comment.
+")
+```
+
 Each agent MUST search-first (Bash `grep`/`rg` + verify imports) before flagging any
 reuse/duplicate, and read the ACTUAL code at every cited line. Collect every agent's findings into one pool
-`{CANDIDATES}` (tag each finding with its producing agent as `source`).
+`{CANDIDATES}` (tag each finding with its producing agent as `source`). Gate failures from Phase 0 step 4 enter the
+pool with `source: gate` and verdict `CONFIRMED-BY-EXECUTION`, citing the command + output line: they carry their
+verdict already, so Phase 3 only RANKS them. Every OTHER candidate enters verdictless and may reach the report only
+via Phase 3.

 ### Phase 3 — VALIDATION (per-finding adversarial reverse-check, the GATE)

-Spawn ONE `{VALIDATOR_AGENT}` that **independently RE-VERIFIES EVERY candidate finding in reverse** against the real
-code BEFORE anything reaches the user report, AND merges the survivors into one consistent, de-duplicated, prioritized
-list. This is a per-finding gate, NOT a sample: a finding reaches the report ONLY after it survives reverse-validation.
+If `{CANDIDATES}` is EMPTY, skip Phase 3 — nothing needs a verdict (a pool of gate rows alone already carries
+`CONFIRMED-BY-EXECUTION`, so it skips straight to ranking); verdict APPROVED only under the Error-Handling
+conditions below. Otherwise spawn ONE validator that **independently RE-VERIFIES EVERY candidate finding in
+reverse** against the real code BEFORE anything reaches the user report, AND merges the survivors into one
+consistent, de-duplicated, prioritized list. Per-finding gate, NOT a sample.
+
+**Validator selection — walk this chain and take the FIRST agent that does NOT own a group the pool came from:**
+`{VALIDATOR_AGENT}` -> `{ARBITER_AGENT}` -> another domain expert with no findings in the pool -> built-in
+`general-purpose` -> built-in `Explore`.
+
+| Rule | Detail |
+|------|--------|
+| Disqualifier | ownership ONLY — an agent may not validate findings from the group IT reviewed in Phase 2. Merely having produced SOME candidate disqualifies nothing: on a multi-domain branch every expert has, which would drop every run to a generic agent exactly when the review is biggest |
+| Mixed pool | one validator whose own group is a MINORITY of the pool is fine — tell it, in the prompt, which findings are its own and to hold those to a stricter bar. Prefer a validator with zero findings in the pool when one exists |
+| Generic fallback | genuine LAST resort: a generic agent weakens the adversarial gate — use it only when every expert owns part of the pool, and note the downgrade in the report |
+
+**Batching (>~40 candidates):** split into batches of **<=40 candidates, max 4 spawns** — NOT per-group (a full
+sweep has many groups, and step 2's "merge and de-duplicate ACROSS agents" is impossible inside a single-group
+batch). Batch by descending severity so the worst findings are validated first. Each batch runs steps 1 and 3-4 on
+its own slice; **run step 2 (merge + de-duplicate) ONCE, in a final pass over the union of all batch outputs**.
+Sum `stats` from the final pass, never from the batches.
+
+> **Overflow past 4 batches — nothing may be silently dropped.** First RAISE the batch size (60-80 still validates
+> per-finding) so the whole pool fits in 4 spawns; a pool that big is usually duplicate-heavy, so de-duplicating
+> BEFORE batching often removes the overflow outright. Only if it still does not fit: validate the highest-severity
+> 4 batches and report every remaining candidate as `UNVALIDATED` — counted, named, forcing `INCOMPLETE`.

 ```
 Codex delegation brief (task_role="{VALIDATOR_AGENT}", message="
 ## superreview — per-finding VALIDATION + Merge ({PROJECT_NAME})

-You are the adversarial validator + final arbiter. For EVERY candidate finding (no sampling, no skipping),
+GOAL: produce ONE merged, de-duplicated, priority-sorted report for {MODE} / {SCOPE} that a human can act on
+without re-checking it. Candidates come from parallel domain owners who each saw only their own file group, so
+some are already fixed, misread, out of scope, or the same issue reported twice.
+ROLE: you are the adversarial validator + final arbiter. For EVERY candidate finding (no sampling, no skipping),
 READ the ACTUAL code at the cited file:line and try to DISPROVE it. Decide CONFIRM or REJECT per finding. Only
-CONFIRMed findings may appear in the final report. Then merge the survivors.
+CONFIRMed findings may appear in the final report. Then merge the survivors. Do NOT edit code, do NOT review
+files outside the set below, do NOT invent findings — the one exception is a miss you deliberately RESTORE.
+SCOPE: in — the candidate pool + the cited code + the files under review, listed below. Out — applying fixes,
+low/medium security, prose outside the JSON.
+
+**READ (paths only — read them yourself, nothing is pasted here):**
+  .codex/skills/superreview/references/{STACK_REF}      — stack facts + per-stack checks.
+  .codex/skills/superreview/references/agent-prompt.md  — the SAME focus ordering the Phase 2 agents were given;
+    apply it verbatim as your effort ordering and tie-break.
+  .codex/skills/superreview/references/scope.md         — baseline precedence, the 6-shape taxonomy + severity map,
+    the delivery/closeout maps and the NOT-creep exclusion list, for validating every 'scope-creep' candidate.
+
+**Your own Phase 2 findings, if any:** {OWN_FINDING_IDS | none}. Hold those to a STRICTER bar than the rest —
+argue against them twice, and REJECT on any doubt. You may not skip them, and you may not wave them through.
+
+**Sanctioned scope baseline (resolved in Phase 0 — the yardstick for every scope-creep candidate):**
+{SCOPE_BASELINE}
+**Ownership signals:** {OWNERSHIP}
+**Mechanical gate results (verdict CONFIRMED-BY-EXECUTION — never re-validate, never reject):** {GATE_RESULTS}
+Findings with source 'gate' already carry their verdict, issued by the run itself; pass them through untouched and
+only RANK them. No other source may use that verdict — everything else you output is \"CONFIRM\" or it does not ship.
+
+**Candidate findings (pool from the domain owners + the scope passes + any included general agents):**
+{CANDIDATES}
+**Files under review:** {FILE_LIST}
+**Focus:** {FOCUS}
+
+CONTEXT: Phase 0 resolved the mode/scope and announced it; Phase 2 already ran the targeted fan-out and each
+candidate is tagged with its producing agent as `source`. You are the GATE — nothing has been shown to the user
+yet, and no other agent runs after you except the report writer.
+CONSUMER: Phase 4 writes your JSON straight into `.codex/reports/{TIMESTAMP}_superreview/REPORT.md` using
+`references/report-template.md`, and Phase 5 prints your `stats` + `verdict` in the chat summary. Any text
+outside the JSON object breaks both; a finding without file + lineStart/lineEnd cannot be rendered.
+DONE: JSON only, in the schema below — findings ORDERED P0 -> P3, every row with file:line + an actionable
+suggestion, plus `dropped`, `verdict` and `stats` filled.

 **Focus ordering (effort + tie-breaks, highest first):** {FOCUS}
  Security = report ONLY if CRITICAL (P0); ignore low/medium.
@@ -256,28 +546,45 @@ CONFIRMed findings may appear in the final report. Then merge the survivors.
  premature generalization, KISS/YAGNI-removable indirection, collapsible duplication. Keep them (with the simpler
  shape) when real; drop if the complexity is justified.

-**Candidate findings (pool from the domain owners + any included general agents):**
-{CANDIDATES}
-**Files under review:** {FILE_LIST}
-**Focus:** {FOCUS}
-
 ### 1. Reverse-validate EACH candidate (per finding — drop false positives)
  a. Existence — does the cited code/line actually exist and exhibit the issue NOW? (REJECT if not / already fixed)
  b. Accuracy — is the claim a correct reading of the code? (REJECT if it misreads the code)
  c. Actionability — is there a concrete fix path? (REJECT if vague / not actionable)
-  d. Severity — is the severity right for the focus ordering? (adjust if wrong)
-  Adversarial: actively argue AGAINST the finding first. It survives ONLY if it withstands a-d. Do this for every
+  d. Severity — right for the focus ordering? SCALE CALIBRATION: harm reachable only under concurrency/load this
+     system does not have -> P3 or REJECT; a race claim with no stated traffic assumption -> REJECT.
+  e. Rule truth — does the cited rule actually say that, and does its scope cover the cited file? REJECT on scope
+     mismatch or an unverified framework-shape claim (verify against the installed dependency, not memory).
+  Adversarial: actively argue AGAINST each finding first. It survives ONLY if it withstands a-e. Do this for every
  single candidate; none is reported unverified.
+  Over-complexity: keep with the simpler-shape suggestion when real, drop if the complexity is justified.
+  Scope-creep: REJECT when the file is implied by the acceptance criteria, required to make the sanctioned change
+  compile/pass the gates, covered by a RECORDED decision (cited or found), board bookkeeping for THIS task, or on
+  the scope.md section-4 exclusion list. CONFIRM only with the baseline source named. Baseline UNKNOWN -> cap at P2
+  and set \"sanctionUnknown\": true — PERMANENT for this run; Phase 3b may lower further but never restores a
+  pre-cap P0/P1 while UNKNOWN. REJECT a shape-1 claim on a neighbour's file when the overlap was correctness-driven
+  AND recorded; demote to shape 6 when only the recording is missing.
+  DELIVERY (scope#D*): D1/D4 are ABSENCE claims, the easiest false P0 here. CONFIRM at P0 only when the finding
+  QUOTES the criterion verbatim AND cites the search that proved absence — then RE-RUN that search yourself plus
+  one synonym/concept variant across source AND tests; any hit -> REJECT. No quote or no cited search -> cap at P2,
+  set \"deliveryProofMissing\": true, route to Phase 3b. CLOSEOUT (scope#C*) — void when no PR exists.
+  You MAY ADD a finding of your own ONLY for a P0-grade issue you directly observe (source: \"validator\") — never
+  lower-priority. Run the SAME a-e pass on your own addition, quote the proof, set \"selfValidated\": true.

 ### 2. Merge + de-duplicate ACROSS agents
  Same file +/-5 lines + same category = ONE finding. Keep the most detailed description, highest severity,
  union of sources (comma-join). A 'duplicate/reuse' miss + an 'architecture' flag on the same code = one row.

 ### 3. Prioritize (MANDATORY P0 -> P3)
-  - P0 = architecture/boundary BLOCKERS + CRITICAL security (logged secret, missing auth, injection) + any miss you RESTORE.
-  - P1 = confirmed functional-correctness + architecture/boundary issues.
-  - P2 = reuse misses/duplication + over-complexity + library version-pin violations rated 'error'.
-  - P3 = business-requirements nits + minor over-complexity + warnings + minor/info.
+  - P0 = architecture/boundary BLOCKERS + hard-rule bypasses + CRITICAL security (logged secret, missing auth,
+         injection) + any miss you RESTORE + UNSANCTIONED scope shape 1 (foreign surface / shared contract /
+         another owner's files) + an undelivered acceptance criterion (scope#D1) + an unrecorded scope reduction
+         (scope#D4). D1/D4 reach P0 ONLY with the section-3b proof; `deliveryProofMissing` or `sanctionUnknown`
+         caps the row at P2 per step 1, and that cap wins over this map.
+  - P1 = confirmed functional-correctness + architecture/boundary issues + other gate failures + scope shapes 2
+         and 5 + a partially delivered criterion (scope#D2) + a misleading closeout artefact (scope#C2).
+  - P2 = reuse misses/duplication + over-complexity + version-pin violations + scope shapes 3, 4, 6, scope#D3, the
+         remaining scope#C* rows, and any scope finding with baseline UNKNOWN + test-quality issues rated major+.
+  - P3 = business-requirements nits + minor over-complexity + warnings + style + minor/info.

 ### 4. Consistency check on the merged list
  No duplicate rows, severities monotonic with priority, every row has file:line + actionable suggestion,
@@ -286,51 +593,100 @@ CONFIRMed findings may appear in the final report. Then merge the survivors.
 **Output JSON ONLY:**
 {
  \"findings\": [{
-    \"id\": \"P0-1\", \"priority\": \"P0|P1|P2|P3\", \"source\": \"agent(s)\",
+    \"id\": \"P0-1\", \"priority\": \"P0|P1|P2|P3\", \"source\": \"agent(s)|gate|validator\",
    \"file\": \"path\", \"lineStart\": 42, \"lineEnd\": 45,
-    \"category\": \"boundary|architecture|reuse|over-complexity|security|logic|persistence|test-quality|pins|style\",
+    \"category\": \"boundary|architecture|scope-creep|reuse|over-complexity|security|logic|persistence|test-quality|pins|style\",
    \"severity\": \"blocker|critical|major|minor\",
+    \"rule\": \"avoid#N|architecture#N|scope#1|scope#D1|scope#C2|... or null\",
    \"title\": \"...\", \"description\": \"...\", \"suggestion\": \"...\",
    \"existing\": \"path|null\", \"reuse\": \"REUSE|EXTEND|CONSIDER|KEEP_NEW|null\",
-    \"verdict\": \"CONFIRM\", \"confidence\": 0.9
+    \"scopeShape\": 1, \"sanctionUnknown\": false, \"deliveryProofMissing\": false,
+    \"impactedOwner\": \"task/person/shared surface|null\",
+    \"verdict\": \"CONFIRM|CONFIRMED-BY-EXECUTION|UNVALIDATED\", \"selfValidated\": false, \"confidence\": 0.9
  }],
-  \"dropped\": [{\"title\": \"...\", \"reason\": \"already-fixed|false-positive|not-actionable|duplicate-of:P0-1\"}],
+  \"dropped\": [{\"title\": \"...\", \"reason\": \"already-fixed|false-positive|not-actionable|unverified-rule|in-sanctioned-scope|duplicate-of:P0-1\"}],
  \"verdict\": \"APPROVED|CONDITIONAL|REWORK\",
-  \"stats\": {\"p0\": 0, \"p1\": 0, \"p2\": 0, \"p3\": 0, \"overComplexity\": 0, \"candidates\": 0, \"confirmed\": 0, \"dropped\": 0}
+  \"stats\": {\"p0\": 0, \"p1\": 0, \"p2\": 0, \"p3\": 0, \"scopeCreep\": 0, \"overComplexity\": 0, \"candidates\": 0, \"confirmed\": 0, \"confirmedByExecution\": 0, \"unvalidated\": 0, \"dropped\": 0}
 }
+(scopeShape / sanctionUnknown / deliveryProofMissing / impactedOwner: only on 'scope-creep', else null/false.)
+Every row MUST carry a \"verdict\". \"candidates\" = confirmed + confirmedByExecution + unvalidated + dropped;
+if that does not balance, a finding went missing — fix it before returning.

 ### Verdict rule
 - REWORK if any P0; CONDITIONAL if any P1/P2 (no P0); APPROVED if only P3 / none.
+- Any row with verdict UNVALIDATED -> append `- INCOMPLETE` to the verdict, whatever it is. An INCOMPLETE run may
+  never read as APPROVED without qualification.
 ")
 ```

-Record output as `{MERGED}`. If `{VALIDATOR_AGENT}` is unavailable, run the SAME prompt on the built-in `general-purpose`.
+Record output as `{MERGED}`. If the validator fails or is unavailable: retry once, then run the SAME prompt on the
+NEXT agent in the selection chain; if the whole chain is exhausted, ship the report with candidates explicitly
+marked `"verdict": "UNVALIDATED"` per row (never `CONFIRM`, never quietly dropped), the run marked **INCOMPLETE**,
+and the unvalidated COUNT carried into the report header, the Stats table and the chat summary. Gate rows keep
+`CONFIRMED-BY-EXECUTION` regardless — execution still happened.
+
+### Phase 3b — SCOPE GATE (request_user_input; after validation, before the report)
+
+Scan `{MERGED}` for CONFIRMED `scope-creep` findings of shape **1, 2 or 5** carrying `sanctionUnknown: true` or no
+cited decision, PLUS any `scope#D1` / `scope#D4` row carrying `deliveryProofMissing: true`. None -> skip silently.
+
+Otherwise ask the user — the full rule (batching, option wording, non-interactive fallback, recording duty) is
+`references/scope.md` section 5; do not restate it, apply it. In short: ONE `request_user_input` call, <=4 questions,
+each naming the files + the surface + who else is impacted + the baseline checked, recommended option first. The
+gate REWRITES existing validated rows only — it may never ADD a finding; an answer that reveals a new issue is
+material for the NEXT run. Then rewrite the affected rows in `{MERGED}`:
+
+| Answer | Effect on the finding |
+|--------|------------------------|
+| Sanctioned — decision exists | demote to **P3**, retitle `record the decision`, keep the row |
+| Not sanctioned | restore the mapped priority (P0/P1) **only if the baseline was KNOWN**; an UNKNOWN baseline keeps the P2 cap, with the answer recorded |
+| Intentional — accept for now | **P2**, tagged `accepted-scope` |
+| Gate not available (non-interactive) | keep the priority the finding ENTERED the gate with, tag `unconfirmed-sanction`. Never silently downgrade, never silently upgrade past a cap |
+
+> A `deliveryProofMissing` D1/D4 answered `Not sanctioned` (the criterion really is undelivered) returns to **P0** —
+> the user's answer IS the missing proof; unanswered, it stays P2.
+
+Re-derive `stats` and the VERDICT after the rewrite (a demotion can flip REWORK -> CONDITIONAL; an `UNVALIDATED`
+row keeps its `- INCOMPLETE` suffix through any rewrite). Verdicts are NOT rewritten here — this gate moves
+priorities, never validation status. Record every question + answer VERBATIM in the report's Scope section.

 ### Phase 4 — Write the merged report

+Shell variables do NOT survive between shell calls, so anchor the report at the repo root and echo the literal
+values you then substitute (never re-run `date` — two calls would disagree):
+
 ```bash
-REPORT_DIR=".codex/reports/${TIMESTAMP}_superreview"
-mkdir -p "${REPORT_DIR}"
+ROOT=$(git rev-parse --show-toplevel) || exit 1
+REPORT_DIR="${ROOT}/.codex/reports/${TIMESTAMP}_superreview"
+if mkdir -p "${REPORT_DIR}"; then echo "REPORT_DIR=${REPORT_DIR}"; else echo "MKDIR FAIL"; fi
 ```

-Write ONE consolidated report to `.codex/reports/{TIMESTAMP}_superreview/REPORT.md` using the layout in
-`references/report-template.md`. Findings section is MANDATORY-sorted by priority P0 -> P3 (highest severity first).
+Write ONE consolidated report to `${REPORT_DIR}/REPORT.md` using the layout in `references/report-template.md`.
+Every table is a VIEW over `{MERGED}` — never a paste of raw Phase 2 candidates. Findings are MANDATORY-sorted by
+priority P0 -> P3, every row carries its verdict, and the Scope section records the Phase 3b questions + answers.

 ### Phase 5 — Chat summary

 ```
 Super Review complete — MODE={MODE} (branch {BRANCH}), {COUNT} files, {N} agents.
+Gates: {gate} {OK|FAIL|not run} / ...
+Experts (live roster): {group -> agent, ...}{, DEGRADED: ...}

-VERDICT: {APPROVED | CONDITIONAL | REWORK}
+VERDICT: {APPROVED | CONDITIONAL | REWORK}{ - INCOMPLETE if anything went unvalidated}
+Validation: {all {N} findings validated | {U} of {N} UNVALIDATED ({reason}) — this run is INCOMPLETE}
+
+Scope: task {T-ID|none} / issue {id|none|not reached}; {K}/{COUNT} files outside the sanctioned surface;
+       delivery {D} undelivered/partial; gate {not triggered|answered|unavailable}

 Priority breakdown (sorted P0 -> P3):
- P0 (architecture blockers + CRITICAL security + validator-restored): {N}
- P1 (confirmed correctness + architecture/boundary): {N}
- P2 (reuse misses + over-complexity + version-pin errors): {N}
- P3 (business-requirements nits + warnings): {N}
-Over-complexity findings: {OC}
+- P0 (architecture blockers + CRITICAL security + unsanctioned foreign-surface scope + undelivered criterion): {N}
+- P1 (confirmed correctness + architecture/boundary + unsanctioned feature/doc scope + gate failures): {N}
+- P2 (reuse misses + over-complexity + drive-by scope + version-pin errors): {N}
+- P3 (business-requirements nits + warnings + style): {N}
+Scope-creep findings: {SC} | over-complexity findings: {OC}

 Per-finding reverse-validation dropped {N} candidates (false-positive/already-fixed/duplicate).
+Gate findings carry verdict CONFIRMED-BY-EXECUTION — validated by the run itself, command + output cited.

 Report: .codex/reports/{TIMESTAMP}_superreview/REPORT.md

@@ -351,12 +707,18 @@ superreview does NOT run /simplify or any skill and does NOT edit code — these
 | Setting | Default | Description |
 |---------|---------|-------------|
 | Mode | deterministic | `FULL_PROJECT` \| `EXPLICIT` \| `UNCOMMITTED` \| `LAST_COMMITS`; computed + announced |
-| Focus | ordered | user directive wins; default = correctness, architecture, reuse, pins, business-reqs; security only if P0 |
-| Fan-out | targeted | non-empty domain groups + {0,1,2} general agents, model's call |
-| Validation | ALWAYS, per-finding | Phase 3 reverse-checks EVERY candidate; only CONFIRMed findings reported |
-| Validator agent | `{VALIDATOR_AGENT}` (fallback built-in `general-purpose`) | Phase 3 merge + validate |
-| Report dir | `.codex/reports/{TIMESTAMP}_superreview/` | Merged report, findings sorted P0 -> P3 |
-| Max files | 50 (except `FULL_PROJECT`) | Warn + suggest narrowing above this |
+| Focus | ordered | user directive wins; default table above; scope discipline is part of rank 1; security only if P0 |
+| Review corpus | IGNORED = OUT, else IN | see "What the review corpus IS" |
+| Expert selection | RUNTIME from `.codex/agents/*.toml` | live roster each run; the emitted table = expected result at generation time |
+| Mechanical gates | `{GATE_COMMANDS}` (Phase 0 step 4) | verdict `CONFIRMED-BY-EXECUTION`, the only non-adversarial verdict |
+| Scope baseline | {TRACKER_LABEL} (read-only) | Phase 0 step 5 / `references/scope.md`; never invented — none -> `UNKNOWN`, findings cap P2 (permanent) |
+| Scope pass A / B | `{SCOPE_AGENT_A}` diff-side / `{SCOPE_AGENT_B}` baseline-side | always, except B in `FULL_PROJECT`; A = shapes 1-6, B = delivery + closeout |
+| Scope gate | `request_user_input`, Phase 3b | fires per the Phase 3b trigger; never lifts the UNKNOWN-baseline P2 cap |
+| Fan-out | targeted | non-empty domain groups + 2 scope passes + {0,1,2} general agents, model's call |
+| Validation | ALWAYS, per-finding | Phase 3 reverse-checks EVERY candidate; unvalidatable -> `UNVALIDATED`, run INCOMPLETE, counted everywhere |
+| Validator agent | first non-owning in the Phase 3 chain (`{VALIDATOR_AGENT}` -> `{ARBITER_AGENT}` -> generic) | batches <=40, max 4 spawns, merge/de-dup ONCE over all batches |
+| Report dir | `<repo-root>/.codex/reports/{TIMESTAMP}_superreview/` | Merged report, findings sorted P0 -> P3 |
+| Max files | 50 (except `FULL_PROJECT`) | request_user_input: narrow or proceed |
 | Search tool | Bash `rg`/`grep`/`git ls-files` | reuse-first search; note which in report |

 ---
@@ -365,33 +727,54 @@ superreview does NOT run /simplify or any skill and does NOT edit code — these

 | Condition | Action |
 |-----------|--------|
-| No changed files for scope | **Exit** ("Nothing to deep-review for {SCOPE}") |
-| >50 files | Warn the user; suggest narrowing (per-folder or per-commit) |
-| A domain agent unavailable | Fall back to built-in `Explore` with the same prompt; note in report |
-| `{VALIDATOR_AGENT}` unavailable | Run Phase 3 validation prompt on the built-in `general-purpose`; note in report |
-| Agent timeout | Retry once, then mark that source unavailable + warn in report |
-| Validation rejects everything | Report "No issues survived validation" — verdict APPROVED |
-| All sources clean | Report "No issues found across standards, architecture, and correctness" — verdict APPROVED |
+| No changed files for scope | **Exit** ("Nothing to deep-review for {SCOPE}") — still report any gate failure |
+| Gates cannot run (toolchain/deps missing) | Record `Gates: not run (<reason>)`; NEVER invent results; continue the fan-out |
+| Gate command fails to start | Non-zero exit -> `GATE <g> FAIL`; mark `not run` + reason if the script is absent; continue |
+| >50 files (non-`FULL_PROJECT`) | request_user_input: narrow (per-folder / per-commit) or proceed anyway |
+| Live roster empty/unreadable | Fall back to the emitted group->agent table; warn in the report |
+| A domain agent unavailable | Fall back to built-in `Explore` with the same prompt; mark the group DEGRADED in the report |
+| Only recon agents match a group | Do NOT use them — route to `Explore`, note it |
+| Empty candidate pool, gates green, >=1 agent RETURNED | Skip Phase 3 — verdict APPROVED |
+| Empty pool because agents FAILED | **Never APPROVED** — absence of evidence, not evidence of absence. Some returned -> verdict tagged `INCOMPLETE ({n}/{N} agents returned)`; NONE returned -> `INCOMPLETE — review did not run` |
+| Every validator-chain candidate owns part of the pool | Prefer the smallest-share owner, tell it which findings are its own; generic agent only if impossible, note the downgrade |
+| Validator unavailable / fails | Retry once, then the next agent in the chain; chain exhausted -> ship remaining as `UNVALIDATED`, verdict suffixed `- INCOMPLETE`, counted in header + Stats + chat |
+| Candidate pool exceeds the batch budget | Raise batch size + de-dup first to fit 4 spawns; still too big -> validate the highest-severity batches, mark the remainder `UNVALIDATED` (named + counted). Never truncate silently |
+| No task + no issue resolvable | `{SCOPE_BASELINE} = UNKNOWN`; run BOTH scope passes anyway, cap findings at P2, raise the Phase 3b gate |
+| Tracker missing / unauthenticated | Local task + docs baseline only; report `issue: not reached`; never assume an issue sanctions anything |
+| `{SCOPE_AGENT_A}` unavailable | Run scope pass A's prompt on `Explore`, note the downgrade |
+| `{PR_ISSUE_JSON}` empty | Pass B still runs DELIVERY vs the local task; records `PR: none`, skips closeout `scope#C*` |
+| Scope gate cannot be asked (non-interactive) | Report at the priority the finding ENTERED with, tagged `unconfirmed-sanction`; never silently downgrade or upgrade past a cap |
+| Agent timeout | Retry once, then mark that source unavailable + warn; the verdict inherits INCOMPLETE — a timed-out group was NOT reviewed |
+| Validation rejects everything, gates green | Report "No issues survived validation" — verdict APPROVED |
+| All sources clean | Report "No issues found across standards, architecture, scope and correctness" — verdict APPROVED |

 ---

 ## References

- `references/{STACK_REF}` — {STACK_LABEL} stack guidelines (passed to every agent).
- `references/agent-prompt.md` — domain-owner agent prompt contract (Phase 2) + the group->agent map.
+- `references/{STACK_REF}` — {STACK_LABEL} stack guidelines (path passed to every agent).
+- `references/agent-prompt.md` — runtime expert-selection procedure + recon-exclusion list + the domain-owner
+  prompt contract (Phase 2) with the detailed focus ordering and the test-bloat block.
+- `references/scope.md` — sanctioned-scope baseline resolution + precedence, ownership map, 6-shape taxonomy +
+  severity map, delivery (D1-D4) + closeout (C1-C4) maps, NOT-creep exclusion list, Phase 3b gate.
 - `references/report-template.md` — merged-report layout (Phase 4).

 <!--
 SKILL METADATA — generated {GENERATED_AT}

 Self-contained project-local deep-review skill for {PROJECT_NAME}. NO sibling-skill orchestration, never invokes
-another skill, NO plugin dependency. Two-phase: targeted domain-owner fan-out (find) -> adversarial validation (gate)
-> ONE merged report at .codex/reports/{TIMESTAMP}_superreview/REPORT.md.
-Agents: project-local (.codex/agents/) + built-in (Explore/Plan/general-purpose).
+another skill, NO plugin dependency. Two-phase: targeted domain-EXPERT fan-out + 2 scope passes (find) ->
+adversarial per-finding validation (gate) -> scope gate -> ONE merged report at
+.codex/reports/{TIMESTAMP}_superreview/REPORT.md. Agents: project-local (.codex/agents/) + built-in.
+
+Corpus rule: git-IGNORED is OUT, everything tracked-or-will-be-tracked is IN (commit status irrelevant). The
+instruction tree is AUTHORITY, never a subject; task-board files are the scope-baseline INPUT only.

 Re-adopt triggers:
- New / renamed agent in .codex/agents/
+- New / renamed agent in .codex/agents/ (auto-picked at runtime; refresh the emitted routing table)
 - AGENTS.md / .codex/rules invariants updated
- New service group (path pattern) added
+- New service group (path pattern) added -> extend PATHSPEC + the group map
+- New always-shared surface (dir / registry / workflow) -> add it to references/scope.md section 2
+- sub-agent task-tracker layout or branch->issue convention changed -> re-check references/scope.md section 1
 Regenerate with: $brewcode:superreview
 -->
@@ -1,20 +1,83 @@
-# Domain-Owner Agent Prompt Template (superreview Phase 2 — {PROJECT_NAME})
+# Domain-Expert Agent Prompt Contract (superreview Phase 2 — {PROJECT_NAME})

-Each changed-file group is routed to its DOMAIN-OWNER agent (see the group->agent map in `SKILL.md`). Spawn ALL
-non-empty groups in ONE message (parallel). Every agent gets the SAME finding contract so Phase 3 can validate and
-Phase 4 can merge.
+SINGLE home of: the runtime expert-selection procedure + roster command, the recon-exclusion list, the domain-owner
+prompt template with the detailed focus ordering, and the test-bloat block. `SKILL.md` points here and does not
+restate any of it.
+
+Each changed-file group is routed to the domain expert **selected at runtime** from the live roster
+(`.codex/agents/*.toml`); the group->agent map in `SKILL.md` is the EXPECTED RESULT at generation time, not a frozen
+contract. Spawn ALL non-empty groups in ONE message (parallel). Every agent gets the SAME finding contract so
+Phase 3 can validate and Phase 4 can merge.
+
+> Sizing: one agent = ONE file group — ~<=5 files, ~<=10 steps; a bigger group is split into two groups and both
+> are spawned in the SAME message.
+
+---
+
+## Dynamic expert selection (run BEFORE building any prompt)
+
+**A review is only as good as its experts.** A generic agent on a domain surface produces generic findings, so the
+selection below is mandatory, not an optimization: derive the real mapping each run so a newly added agent is used
+automatically.
+
+```bash
+# Live roster: name + description of every project agent
+for f in .codex/agents/*.toml; do
+  printf '%s :: %s :: %s\n' "$f" \
+    "$(grep -m1 '^name:' "$f" | sed 's/^name:[[:space:]]*//')" \
+    "$(grep -m1 '^description:' "$f" | sed 's/^description:[[:space:]]*//' | cut -c1-220)"
+done
+```
+
+Selection procedure per changed-file group:
+
+1. Group the changed files by owning path (the group map in `SKILL.md` is the starting point). Git-IGNORED paths
+   are outside the review corpus, never reach `FILES`, and never form a group — they stay the AUTHORITY you cite.
+2. For each group, pick the agent whose `description` claims that path/responsibility MOST specifically — honour
+   any explicit hand-off ("X, not Y") the descriptions declare.
+3. **Exclude READ-ONLY external-system recon agents** — agents that inspect a live external system (cloud console,
+   SaaS API, ticket tracker, DB console, deploy target) rather than source files. Never route source-file review to
+   them, and never pick one just because it sorts first alphabetically.
+4. No confident match -> built-in `Explore` (read-only). Mark that group **DEGRADED** in the report — it means the
+   project is missing a domain expert for that surface, which is worth fixing before the next run.
+5. Record the derived map in the report's `Agents run` line so the routing is auditable.
+
+> Route every file to EXACTLY ONE exclusive group. Tie-breaks: `tests` wins over any path group; a row naming an
+> explicit file wins over a row with a glob. A cross-cutting arbiter is an OVERLAY (an extra pass), not a group —
+> it never takes files away from their owner.

 ```
 Codex delegation brief (task_role="{AGENT}", message="
 ## superreview — {GROUP} pass ({PROJECT_NAME})

-You review ONLY the files below. Read the ACTUAL code. Report STANDARDS + ARCHITECTURE + CORRECTNESS issues.
-
-**SEARCH-FIRST (HARD rule — reuse-first):** before flagging a 'duplicate' or 'reuse' miss, grep the repo
-(Bash grep/find over the shared/util/common/domain/adapters dirs) and verify imports.
+GOAL: one deep review of the {MODE} change set in {PROJECT_NAME}, split by file group so each domain owner judges
+only the code it owns. The point is a single merged, validated report a human acts on — not a per-file opinion.
+ROLE: you own the {GROUP} group. Report STANDARDS + ARCHITECTURE + CORRECTNESS issues in it. Do NOT edit any
+file, do NOT review files outside your list, do NOT restate the project rules, do NOT report positives.
+SCOPE: in — the files below; read the ACTUAL code at every line you cite, plus `.codex/rules/*` +
+`.codex/convention/*` for your area and the stack guidelines you were passed. Out — every other file group,
+applying fixes, style-only churn, low/medium security.

 **Files:** {FILE_LIST}
 **Focus:** {FOCUS}
+**Mechanical gate results (ground truth — already run, do NOT re-run):** {GATE_RESULTS}
+Anything the build/lint/type/test gates already reported is CONFIRMED fact: cite it, do not re-litigate it, and do
+not duplicate it as a fresh finding unless you add a root cause the tool did not give.
+
+CONTEXT: Phase 0 already resolved the mode + scope and announced the file list; Phase 1 grouped it. Sibling domain
+owners review the OTHER groups in parallel right now, and up to two general cross-cutting agents may also be
+running — do not widen your group to cover them. Nothing you report is final: Phase 3 reverse-validates every
+finding against the code and REJECTS anything already fixed, misread, or vague.
+CONSUMER: the Phase 3 validator merges your findings with the siblings' (same file +/-5 lines + same category =
+ONE row), then Phase 4 writes one report sorted P0 -> P3. A finding without exact file + lineStart/lineEnd cannot
+be validated or merged and is dropped; the JSON below is the merge contract — emit that object and nothing else.
+DONE: JSON only, in the schema below; issues only; every finding with exact lines and an actionable suggestion.
+
+**SEARCH-FIRST (HARD rule — reuse-first):** before flagging a 'duplicate' or 'reuse' miss, grep the repo
+(Bash grep/find over the shared/util/common/domain/adapters dirs) and verify imports. No verification -> no finding.
+NOTE: git-IGNORED = outside the review corpus. Where the instruction tree (`.codex/**`, `AGENTS.md`) is ignored,
+you may READ it as authority (cite a rule id) but never raise a finding ON it. Untracked-but-not-ignored files ARE
+in scope — `git ls-files` alone misses them, so add `git ls-files --others --exclude-standard` to any reuse sweep.

 ### Focus ordering — spend effort in this priority (highest first)
  1. Functional correctness — does the code do what it should? logic, edge cases, race conditions.
@@ -23,8 +86,21 @@ You review ONLY the files below. Read the ACTUAL code. Report STANDARDS + ARCHIT
     Flag duplication + missed reuse (cite the project reuse-first rule).
  4. Library version pins — exact X.Y.Z, no floating/stale (cite the project pins rule).
  5. Business-requirements compliance.
+  6. SCOPE DISCIPLINE / minimal blast radius — measure every file you review against the SANCTIONED baseline:
+     does the task/issue actually ask for this? Flag (category \"scope-creep\", rule \"scope#<shape>\") anything
+     beyond it — a shared contract/schema/migration/registry/CI edit the task never mentions, another owner's
+     files, a feature past the acceptance criteria, a drive-by refactor, a doc rewritten to match the code.
+     Baseline: {SCOPE_BASELINE}
+     Ownership signals: {OWNERSHIP}
+     (Both are substituted by SKILL.md Phase 2. If either still reads as a literal brace placeholder, you have NO
+     baseline: say so and report every scope finding at P2 max — never rank against an empty yardstick.)
+     Taxonomy, severity map and the binding NOT-creep exclusion list:
+     .codex/skills/superreview/references/scope.md — READ it (path only) before flagging anything here. Two
+     dedicated scope passes work the same axis: report only what YOU see in YOUR files, and do not skip it.
  SECURITY is NOT a priority: report a security finding ONLY when CRITICAL (P0) — logged secret, missing auth on a
  public path, injection. Do NOT spend effort on low/medium security.
+  SCALE CALIBRATION: judge harm against this project's real scale. Harm reachable only under concurrency/load the
+  system does not have -> P3 or omit; a race claim MUST state its traffic assumption.
  (If the project fine-tune emphasis in SKILL.md reorders this, follow that ordering.)

 ### OVER-COMPLEXITY / over-engineering — report it as findings (category \"over-complexity\")
@@ -46,9 +122,9 @@ candidate (per the Focus ordering; security only as P0).
    \"file\": \"path/to/file{SOURCE_GLOB}\",
    \"lineStart\": 42,
    \"lineEnd\": 45,
-    \"category\": \"boundary|architecture|reuse|over-complexity|security|logic|persistence|test-quality|pins|style\",
+    \"category\": \"boundary|architecture|scope-creep|reuse|over-complexity|security|logic|persistence|test-quality|pins|style\",
    \"severity\": \"blocker|critical|major|minor\",
-    \"rule\": \"avoid#N|best-practices#N|architecture#N|containers#N|... (project rule namespace, or null)\",
+    \"rule\": \"avoid#N|best-practices#N|architecture#N|containers#N|scope#<shape>|... (project rule namespace, or null)\",
    \"title\": \"Short summary (<=80 chars)\",
    \"description\": \"What is wrong + which invariant/rule it breaks\",
    \"suggestion\": \"Concrete fix / where code belongs / what to reuse\",
@@ -59,10 +135,15 @@ candidate (per the Focus ordering; security only as P0).
 }

 **Severity guide:**
- blocker: prod outage / security breach / data loss / boundary violation in a critical path.
- critical: significant bug, perf degradation, boundary violation.
- major: important maintainability/correctness issue.
- minor: style, naming, minor improvement.
+- blocker: prod outage / security breach / data loss / boundary violation in a critical path / an UNSANCTIONED
+  edit to a shared surface or another owner's files (scope shape 1) — but overlap into another owner's files is
+  NOT automatically shape 1: apply the scope.md section-4 carve-out first (correctness-driven + recorded = not a
+  finding; correctness-driven + unrecorded = shape 6, P2).
+- critical: significant bug, perf degradation, boundary violation, behaviour past the acceptance criteria (shape 2),
+  documentation rewritten to match the code (shape 5).
+- major: important maintainability/correctness issue, missed reuse, drive-by refactor (shape 3), opportunistic
+  dependency (shape 4), floating version pin on a NEW/CHANGED dep.
+- minor: style, naming, comment quality, a needed-but-unrecorded expansion (shape 6), minor improvement.

 Report ONLY issues (not positives). Reference exact lines. Provide actionable suggestions. Read the real code.
 ")
@@ -10,8 +10,11 @@ Output: `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`. ONE consolidated, va
 **Scope:** {concrete scope — commit range | branch-vs-main | folder | working-tree vs HEAD | full project}
 **Focus:** {resolved focus — user directive, else default ordering; security only if P0}
 **Files Reviewed:** {COUNT}
+**Sanctioned scope:** task {T-ID | none} / issue {id | none | not reached} / decisions {ids | none} — {K}/{COUNT} files outside it
+**Gates:** {gate} {OK|FAIL|not run} / ...
+**Validation:** {all {N} findings validated | **{U} UNVALIDATED of {N} — run is INCOMPLETE ({reason})**} — every row below carries a verdict
 **Search tool used:** {Bash rg/grep/git ls-files}
-**Agents run (targeted fan-out):** {AGENT_LIST}
+**Agents run (derived from live roster):** {AGENT_LIST}{, DEGRADED: <group> -> generic}

 > Findings section below is MANDATORY-sorted by priority P0 -> P3 (highest severity first).

@@ -19,16 +22,39 @@ Output: `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`. ONE consolidated, va

 | Priority | Meaning | Count |
 |----------|---------|-------|
-| P0 | Architecture blockers + CRITICAL security + validator-restored misses | {N} |
-| P1 | Confirmed correctness + architecture/boundary | {N} |
-| P2 | Reuse misses + over-complexity + version-pin errors | {N} |
-| P3 | Business-requirements nits + minor over-complexity + warnings | {N} |
+| P0 | Architecture blockers + CRITICAL security + unsanctioned foreign-surface scope + undelivered criterion / unrecorded reduction + validator-restored misses | {N} |
+| P1 | Confirmed correctness + architecture/boundary + unsanctioned feature / silent doc mutation + partially delivered criteria + misleading closeout + other gate failures | {N} |
+| P2 | Reuse misses + over-complexity + drive-by scope + version-pin errors + test quality | {N} |
+| P3 | Business-requirements nits + minor over-complexity + style + warnings | {N} |
+
+## Scope Discipline / Blast Radius (category `scope-creep`; taxonomy in `references/scope.md`)
+
+**Baseline:** task {T-ID + file} | none — issue {id} "{title}" | not reached — decisions {ids} | none
+**Acceptance criteria covered:** {c}/{total} ({unmet ones listed as findings})
+**Files outside the sanctioned surface:** {K}/{COUNT}
+**Delivery (section 3b):** D1 {n} undelivered / D2 {n} partial-or-stubbed / D3 {n} unprovable — reductions: {none \| accepted, blocker recorded in {where} \| UNRECORDED -> D4}
+**Closeout (section 4b):** PR {id} — body {OK \| C1 gap \| too long \| too thin}; `Closes`/`Refs` {correct \| C2 {detail}}; issue comments {OK \| missing}; AI attribution {none \| C4 found in {artefact}} \| **PR: none — closeout skipped**
+
+| File:Line | Shape / rule | Sanctioned? | Who else is hit | Issue | Fix |
+|-----------|--------------|-------------|-----------------|-------|-----|
+| ... | 1 foreign-surface \| 2 unsanctioned-feature \| 3 drive-by \| 4 opportunistic-dep \| 5 silent-doc-mutation \| 6 unrecorded \| D1-D4 delivery \| C1-C4 closeout | NO \| UNKNOWN \| yes ({decision id}) | {task/owner/shared surface} | ... | split out \| revert \| deliver the criterion \| fix the PR body \| record the decision |
+
+**Scope gate (Phase 3b):** {not triggered | Q + user's answer, verbatim, per expansion | not available — findings kept at the priority they entered with}
+
+## Mechanical Gate Results (verdict `CONFIRMED-BY-EXECUTION` — validated by the run itself, cite command + output)
+
+| Gate | Result | Detail |
+|------|--------|--------|
+| {build/lint/type/test command} | {OK \| FAIL \| not run} | {first errors / reason not run} |

 ## Merged Prioritized Findings (sorted P0 -> P3, highest severity first)

-| ID | Priority | Source | File:Line | Category | Severity | Title | Suggestion |
-|----|----------|--------|-----------|----------|----------|-------|------------|
-| P0-1 | P0 | {agent} | path:42-45 | boundary | blocker | ... | ... |
+Every row carries a Verdict. `CONFIRM` = adversarially validated; `CONFIRMED-BY-EXECUTION` = gate output, cite the
+command; `UNVALIDATED` = validation could not run, run is INCOMPLETE. No other value, no blank.
+
+| ID | Priority | Verdict | Source | File:Line | Category | Severity | Rule | Title | Suggestion |
+|----|----------|---------|--------|-----------|----------|----------|------|-------|------------|
+| P0-1 | P0 | CONFIRM | {agent} | path:42-45 | boundary | blocker | architecture#3 | ... | ... |

 ## Boundary & Architecture

@@ -46,23 +72,26 @@ Output: `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`. ONE consolidated, va
 |-----------|------|------|---------------|
 | ... | speculative abstraction / gold-plating / premature generalization / collapsible dup | best-practices#N \| avoid#N | delete layer / inline one-caller / collapse dup / reuse existing |

-## Dropped in Validation (false-positive / already-fixed / de-dup)
+## Dropped in Validation (false-positive / already-fixed / unverified-rule / in-sanctioned-scope / de-dup)

 | Title | Reason |
 |-------|--------|

 ## VERDICT

-**{APPROVED | CONDITIONAL | REWORK}**
+**{APPROVED | CONDITIONAL | REWORK}{ - INCOMPLETE ({U} unvalidated) if any row is UNVALIDATED}**

 ## Stats

 | Metric | Value |
 |--------|-------|
 | P0 / P1 / P2 / P3 | {a} / {b} / {c} / {d} |
+| Scope-creep findings (files outside the sanctioned surface) | {SC} ({K}/{COUNT} files) |
 | Over-complexity findings | {OC} |
 | Candidate findings (pre-validation) | {N} |
 | Confirmed by validation | {N} |
+| Confirmed by execution (gate output) | {N} |
+| **UNVALIDATED (forces INCOMPLETE)** | **{N}** |
 | Dropped by validation | {N} |
 | Agents spawned | {N} |
 | Files reviewed | {COUNT} |
@@ -72,7 +101,11 @@ Output: `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`. ONE consolidated, va
 > **superreview is READ-ONLY — it does not apply fixes.** It only reports. Act on the findings as below.

 - **To FIX the findings:** start a NEW session (English), turn on **Manager mode (`++m`)**, and DELEGATE the fixes
-  to the domain-owner agents. Address **P0/P1 first, then P2/P3**.
+  to the domain-expert agents the routing map named. Address **P0/P1 first, then P2/P3**.
+- **Scope:** {SC} scope finding(s). {if any P0/P1: split the unsanctioned work into its own task + PR, or get the
+  decision recorded in the task notes and as a comment on the issue — superreview does NOT touch the board or the
+  issue. | if none: blast radius stayed inside the sanctioned surface.}
+- **Re-run the gates after fixing:** the same commands Phase 0 ran.
 - **To reduce over-complexity:** {OC} over-complexity / missed-reuse / duplication findings.
  {if {OC} > 0: **run the built-in `/simplify` skill** — it reviews the changed code for reuse / simplification /
  efficiency and APPLIES the cleanups. Run it in a fix-session, then re-run superreview to confirm.}
@@ -89,4 +122,10 @@ Output: `.codex/reports/{TIMESTAMP}_superreview/REPORT.md`. ONE consolidated, va
 - **Priority:** P0 (blocker — fix first) -> P3 (nice-to-have).
 - **Severity:** blocker (outage/breach/data-loss) > critical (significant bug/perf/boundary) > major (maintainability) > minor (style).
 - **Reuse:** REUSE (import existing 90-100%) | EXTEND (add params to existing 70-89%) | CONSIDER (evaluate 50-69%) | KEEP_NEW (<50%, justified).
- **Verdict:** REWORK if any P0; CONDITIONAL if any P1/P2 (no P0); APPROVED if only P3 / none.
+- **Run verdict:** REWORK if any P0; CONDITIONAL if any P1/P2 (no P0); APPROVED if only P3 / none; suffix
+  `- INCOMPLETE` whenever any row is UNVALIDATED.
+- **Row verdict:** CONFIRM (adversarially validated) | CONFIRMED-BY-EXECUTION (gate output, command + line cited) |
+  UNVALIDATED (validation could not run). No row ships without one.
+- **Scope shapes:** 1 foreign-surface (P0) | 2 unsanctioned-feature (P1) | 3 drive-by (P2) | 4 opportunistic-dep
+  (P2) | 5 silent-doc-mutation (P1) | 6 sanctioned-but-unrecorded (P2); delivery D1/D4 (P0, proof required),
+  D2 (P1), D3 (P2); closeout C2 (P1), C1/C3/C4 (P2).
@@ -0,0 +1,159 @@
+# Scope Discipline Reference (superreview — {PROJECT_NAME})
+
+SINGLE home of: sanctioned-scope resolution, sanction sources + precedence, the ownership map, the scope-creep
+taxonomy + severity map, the full-scope DELIVERY map, the CLOSEOUT map, the "not creep" exclusion list, and the
+Phase 3b user gate. `SKILL.md` and `references/agent-prompt.md` POINT here (path only) and never restate any of it.
+
+**WHY this ranks as a principle, not a style note:** {TEAM_NOTE}. Every file touched outside the task's sanctioned
+surface is a merge conflict, a contract changed under someone else's feet, or work nobody agreed to.
+**Minimal blast radius is a hard project principle.**
+
+---
+
+## 1. Resolve the SANCTIONED SCOPE baseline (Phase 0, before the fan-out)
+
+Tracker for this project: **{TRACKER_LABEL}**.
+
+`{RANGE}` = the commit range `SKILL.md` resolved for `{MODE}`. EXPORT it before running this block; unset, step `e`
+records "not read" rather than reading a range this run never chose. `FULL_PROJECT` / `UNCOMMITTED` have no range —
+leaving it empty is correct there.
+
+{BASELINE_RESOLUTION_BASH}
+
+{SANCTION_PRECEDENCE_TABLE}
+
+**Degradation (never invent a baseline):**
+
+| Condition | Action |
+|-----------|--------|
+| Issue tracker unreachable / unauthenticated / issue not found | baseline = local task + docs only; record `issue: not reached` |
+| No task file AND no issue resolvable | baseline = `UNKNOWN`; report scope findings at **P2 max** and raise the Phase 3b gate. The cap is PERMANENT for the run — the gate may lower a finding further but NEVER restores a pre-cap P0/P1 while the baseline is still `UNKNOWN` |
+| Branch carries no issue id in the agreed `<type>/<issue>-<slug>` position | match the task by branch NAME in the board; else `UNKNOWN`. Never take a digit run from elsewhere in the branch name (`fix/oauth2-login` -> 2 is the classic false match) |
+| Branch issue id disagrees with the matched task's recorded link | the branch id is unreliable -> baseline = `UNKNOWN`, recorded as `issue N from branch not in task links`. Cross-check ALWAYS |
+| sub-agent task matched by MENTION only (no explicit link) | usable as CONTEXT; treat the baseline as `UNKNOWN` for severity (P2 cap) unless the issue body independently confirms the deliverable |
+| MODE = `FULL_PROJECT` | scope axis is INFORMATIONAL only — a full-project sweep has no single task; report shapes 3/4 only. `SKILL.md` runs scope pass A alone there and SKIPS pass B: with no criteria and no single PR, sections 3b + 4b have nothing to score |
+
+---
+
+## 2. Ownership map (who else gets hit) — derived at RUNTIME, never hardcoded
+
+{OWNERSHIP_SIGNALS_BASH}
+
+Owners come from: the board's owner column, the task file's `owner:` field, the issue `assignees`, and recent
+authorship. A file whose recent authorship, or whose owning task, belongs to someone else = **another owner's
+surface** -> shape 1 below, UNLESS the overlap is correctness-driven (section 4: not a finding when recorded,
+shape 6 when only unrecorded).
+
+**Always-shared surfaces** (touching them widens blast radius across the whole team regardless of authorship):
+
+{SHARED_SURFACES_TABLE}
+
+> The instruction tree (`.codex/rules/**`, `.codex/convention/**`, `.codex/agents/**`, `.codex/skills/**`,
+> `AGENTS.md`, `AGENTS.md`) is NOT on this list: it is the AUTHORITY reviewers cite. Whether it is a review target
+> at all is decided by the corpus rule in `SKILL.md` (git-IGNORED = OUT) — a path that is never reviewed cannot
+> carry a review severity. sub-agent task-board files are the baseline INPUT, likewise never a finding target.
+
+---
+
+## 3. Scope-creep taxonomy (finding category `scope-creep`, rule ids `scope#1`..`scope#6`)
+
+| # | Shape | Example | Default severity / priority |
+|---|-------|---------|-----------------------------|
+| 1 | **foreign-surface** | a shared contract / schema / migration / design token / registry / CI / lint config edited while task + issue never mention it, or a file owned by another task AND not needed for correctness | `blocker` / **P0** |
+| 2 | **unsanctioned-feature** | behaviour beyond the acceptance criteria — extra endpoint, extra role, extra flag, "while I was here" capability | `critical` / **P1** |
+| 3 | **drive-by-refactor** | unrelated rename / reorg / format churn in files the task did not need | `major` / P2 |
+| 4 | **opportunistic-dependency** | new dependency / config / tooling not required by the acceptance criteria | `major` / P2 |
+| 5 | **silent-doc-mutation** | documentation edited to MATCH the code instead of the code following the doc | `critical` / **P1** |
+| 6 | **sanctioned-but-unrecorded** | genuinely needed, but the decision exists only in chat or a commit body — not in the issue or the task notes | `minor` / P2 + "record the decision" |
+
+**Overlap is NOT automatically shape 1.** Scope MAY expand into a neighbouring task's surface where correctness
+requires it (section 4). Shape 1 fires only on an UNSANCTIONED, correctness-irrelevant touch. Correctness-driven
+overlap that is merely UNRECORDED is **shape 6**, P2 + "record the boundary" — never a shape-1 blocker.
+
+**Inverse:** under-delivery is equally reportable and gets its own severity map — section 3b.
+
+Every scope finding MUST carry, in `description`: the baseline source it was checked against (issue id / task id /
+decision id, or `UNKNOWN`), the shape or rule id, and — for shape 1 — the other owner or shared surface hit.
+
+---
+
+## 3b. Full-scope DELIVERY (category `scope-creep`, rule ids `scope#D*`)
+
+Full sanctioned scope must be DELIVERED. Reducing it is legitimate ONLY against a real blocker, and only when that
+blocker is RECORDED and NAMED (task notes / issue comment). Under-delivery outranks over-delivery.
+
+| Rule | Condition | Default severity / priority |
+|------|-----------|-----------------------------|
+| `scope#D1` | acceptance criterion / issue done-when with NO corresponding code | `blocker` / **P0** |
+| `scope#D2` | criterion partially met, or met only by fixture/stub where the done-when says real | `critical` / **P1** |
+| `scope#D3` | criterion met but not provable — no test, no evidence cited | `major` / P2 |
+| `scope#D4` | scope reduced with NO recorded blocker — title `unrecorded scope reduction` | `blocker` / **P0** |
+| — | scope reduced WITH the blocker recorded + named | NOT a finding — report as an **accepted reduction**, citing where it is recorded |
+
+### PROOF OF ABSENCE — mandatory for D1 and D4 (the only P0s built on a negative)
+
+D1 and D4 assert that something is NOT there. A criterion delivered under a different NAME looks identical to a
+criterion never built, and the resulting false P0 flips the verdict to REWORK without anyone questioning it. So:
+
+| Requirement | Detail |
+|-------------|--------|
+| Quote | the criterion VERBATIM from the task acceptance list / issue done-when, plus its baseline source |
+| Search proof | the exact command run and its empty result — by CONCEPT and by SYNONYM, across the source tree AND the tests (e.g. `rg -n 'readiness\|Readiness\|ready_at' src` -> 0 hits). Reading the diff alone is NOT proof: the criterion may be met by code the diff never touched |
+| Missing either | you may NOT claim P0. Report at **P2** with `"deliveryProofMissing": true`; the Phase 3b gate then asks the user, and a `Not sanctioned` answer restores P0 |
+
+With quote + search proof present, D1/D4 stay P0 and bypass the gate. Every other `scope#D*` finding still quotes
+the criterion verbatim and names the baseline source it came from.
+
+---
+
+## 4. NOT scope creep — do NOT flag
+
+- Files the acceptance criteria imply: a use-case + its test + its interface + its wiring + its route.
+- A fix REQUIRED to make the sanctioned change compile / pass the gates.
+- An expansion covered by a recorded decision (cite it — decision id, issue comment, docs section).
+- Board / task-file bookkeeping for THIS task.
+- Anything the user explicitly asked for in this run.
+- A trivial one-liner fix in a file already inside the baseline surface.
+- **Overlap into a neighbouring task's surface** when BOTH hold: (a) the sanctioned deliverable cannot be CORRECT
+  without it, and (b) the boundary is recorded — which part we own, which part stays theirs. Both hold -> not a
+  finding. (a) only -> **shape 6**, P2 + "record the boundary". Neither -> shape 1.
+
+---
+
+## 4b. Closeout artefacts — PR/MR body + issue comments (rule ids `scope#C*`)
+
+Runs ONLY when a PR/MR exists for the branch (read-only). No PR -> record `PR: none`, SKIP, invent nothing. What
+shipped must be DISCOVERABLE from these artefacts by the next person who touches the surface.
+
+| Rule | Check | Default priority |
+|------|-------|------------------|
+| `scope#C1` | PR body states what SHIPPED, what is deliberately NOT built, what consumers may rely on | P2 |
+| `scope#C2` | `Closes #nn` only for an issue we FULLY own; `Refs #nn` for a shared or partially delivered one. Closing a co-assigned issue is a finding | **P1** |
+| `scope#C3` | every issue this work touches carries a closeout comment — what landed, what remains | P2 |
+| `scope#C4` | AI attribution in a PR body, commit message or issue comment | P2 |
+
+**Quality bar for both artefacts: maximally short and clear.** Flag an essay-length body, restated rationale,
+marketing tone, or a wall that buries the one fact a reader needs — and equally the opposite, a body so thin a
+colleague cannot tell what shipped. **P1** instead of P2 whenever the artefact would actively MISLEAD a colleague
+(wrong `Closes`, or a claim the diff does not support).
+
+---
+
+## 5. Phase 3b user gate (request_user_input) — MANDATORY
+
+**Trigger:** >=1 CONFIRMED scope-creep of shape **1, 2 or 5** whose sanction could NOT be found in section 1, OR a
+`scope#D1` / `scope#D4` row carrying `deliveryProofMissing: true` (section 3b — an absence claim with no verbatim
+criterion and no cited search must be asked about before it can weigh as a P0).
+
+| Rule | Detail |
+|------|--------|
+| Batch | ONE `request_user_input` call, one question per distinct expansion, max 4 (merge the rest into the largest) |
+| Question | name the FILES + the surface + who else owns it + the baseline checked; ask whether it is sanctioned. For a `deliveryProofMissing` row: quote the criterion and ask whether it was delivered (possibly under another name) |
+| Options | `Sanctioned — decision exists` (-> demote to P3 "record the decision") / `Not sanctioned — report as {P0\|P1}` (recommended, first) / `Intentional — accept for now` (-> P2, marked `accepted-scope`) |
+| Never ask | shapes 3, 4, 6, every `scope#C*` row, and any `scope#D*` row whose proof IS present — report those directly |
+| **Baseline UNKNOWN** | the P2 cap set in section 1 SURVIVES this gate. `Not sanctioned` restores the mapped P0/P1 **only when the baseline was known** — the user confirmed the expansion, not the baseline |
+| Non-interactive | gate unavailable -> report at the priority the finding ENTERED with (full severity when the baseline was known, the P2 cap when it was `UNKNOWN`), flagged `unconfirmed-sanction`. Never silently downgrade, never silently upgrade past a cap |
+| Record | the question and the user's answer go into the report VERBATIM, and into the chat summary |
+
+The gate runs AFTER Phase 3 validation (only survivors are worth asking about) and BEFORE the report is written.
+superreview is READ-ONLY: the gate never edits the board, an issue, or a PR.
@@ -23,43 +23,76 @@ TARGET=".codex/skills/superreview"
 TARGET_REFS="$TARGET/references"

 validate_templates() {
-  if [ ! -f "$REFS/SKILL.md.template" ]; then
-    echo "❌ Emit template not found: $REFS/SKILL.md.template"
-    exit 1
-  fi
+  for t in "$REFS/SKILL.md.template" "$REFS/scope.md.template" "$REFS/agent-prompt.md" "$REFS/report-template.md"; do
+    if [ ! -f "$t" ]; then
+      echo "❌ Emit template not found: $t"
+      exit 1
+    fi
+  done
 }

 # ── scan: report what the emitted skill must be wired to ────────────────────────
+# `find | sort` exits 0 on an empty result, so every listing goes through this helper:
+# a bare `find ... || echo "(none)"` would never print the fallback.
+# `|| true` is required: a missing dir makes find exit 1, and under `set -e` a failing command
+# substitution in an assignment aborts the whole script.
+_list() { _out=$(eval "$1" 2>/dev/null || true); if [ -n "$_out" ]; then printf '%s\n' "$_out"; else echo "${2:-(none)}"; fi; }
+
 scan_target() {
  echo "=== superreview: target scan ==="
  echo ""
  echo "--- Build files ---"
-  find . -maxdepth 3 -type f \( \
+  _list 'find . -maxdepth 3 -type f \( \
    -name "package.json" -o -name "pom.xml" -o -name "build.gradle" -o \
    -name "build.gradle.kts" -o -name "requirements*.txt" -o -name "pyproject.toml" -o \
    -name "Pipfile" -o -name "Cargo.toml" -o -name "go.mod" -o -name "composer.json" \
-  \) 2>/dev/null | sort || echo "(none found)"
+  \) | sort' "(none found)"

  echo ""
-  echo "--- Project agents (.codex/agents/) ---"
-  find .codex/agents -type f -name "*.md" 2>/dev/null | sort || echo "(none)"
+  echo "--- Project agents (.codex/agents/) — DOMAIN EXPERT roster ---"
+  if [ -d .codex/agents ]; then
+    for f in .codex/agents/*.toml; do
+      [ -f "$f" ] || continue
+      printf '%s :: %s :: %s\n' "$f" \
+        "$(grep -m1 '^name:' "$f" | sed 's/^name:[[:space:]]*//')" \
+        "$(grep -m1 '^description:' "$f" | sed 's/^description:[[:space:]]*//' | cut -c1-220)"
+    done
+    _n=$(find .codex/agents -maxdepth 1 -type f -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    echo "agents=$_n"
+    [ "$_n" -eq 0 ] && echo "⚠️ NO domain experts — superreview routed to generic agents is a DEGRADED review"
+  else
+    echo "(none)"
+    echo "⚠️ NO .codex/agents/ — create domain experts before generating (see SKILL.md Phase 1.6)"
+  fi
+
+  echo ""
+  echo "--- Scope baseline sources (tracker) ---"
+  test -d .codex/features && echo "✅ .codex/features/ (file-based Kanban)" || echo "— no .codex/features/"
+  command -v gh >/dev/null 2>&1 && echo "✅ gh CLI present" || echo "— no gh CLI"
+  git rev-parse --abbrev-ref HEAD 2>/dev/null | sed 's/^/branch: /' || true
+  test -d .github && echo "✅ .github/ present" || echo "— no .github/"

  echo ""
  echo "--- Rules (.codex/rules/) ---"
-  find .codex/rules -type f -name "*.md" 2>/dev/null | sort || echo "(none)"
+  _list 'find .codex/rules -type f -name "*.md" | sort'

  echo ""
  echo "--- Conventions (.codex/convention/) ---"
-  find .codex/convention -type f -name "*.md" 2>/dev/null | sort || echo "(none)"
+  _list 'find .codex/convention -type f -name "*.md" | sort'

  echo ""
  echo "--- Source / service dirs (top level) ---"
-  find . -maxdepth 2 -type d \( -name "src" -o -name "app" -o -name "lib" -o \
-    -name "pkg" -o -name "internal" -o -name "cmd" \) 2>/dev/null | sort || echo "(none)"
+  _list 'find . -maxdepth 2 -type d \( -name "src" -o -name "app" -o -name "lib" -o \
+    -name "pkg" -o -name "internal" -o -name "cmd" \) | sort'

  echo ""
  echo "--- Test dirs ---"
-  find . -type d \( -name "test" -o -name "tests" -o -name "__tests__" \) 2>/dev/null | head -20 || echo "(none)"
+  _list 'find . -type d \( -name "test" -o -name "tests" -o -name "__tests__" \) | head -20'
+
+  echo ""
+  echo "--- Gate commands (candidates for GATE_COMMANDS) ---"
+  _list 'grep -oE "\"(build|lint|typecheck|type-check|test)\"[[:space:]]*:" package.json | tr -d "\":" | sed "s/^/npm run /"'
+  _list 'grep -oE "^[a-zA-Z_-]+:" Makefile | tr -d ":" | sed "s/^/make /"' "(no Makefile targets)"

  echo ""
  echo "--- AGENTS.md ---"
@@ -81,13 +114,17 @@ emit_skill() {
  PATHSPEC_GLOBS="${PATHSPEC_GLOBS:-'*' 'Dockerfile*' 'docker-compose.yml' '.github/workflows/*.yml'}"
  ARBITER_AGENT="${ARBITER_AGENT:-general-purpose}"
  VALIDATOR_AGENT="${VALIDATOR_AGENT:-general-purpose}"
+  SCOPE_AGENT_A="${SCOPE_AGENT_A:-Explore}"
+  SCOPE_AGENT_B="${SCOPE_AGENT_B:-Explore}"
+  TRACKER_LABEL="${TRACKER_LABEL:-local task board + issue tracker (read-only)}"
  GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

  _sep=$'\x01'

  # Sanitize every scalar before it lands on a sed RHS: escape backslash FIRST, then ampersand
  # (& is the whole-match backreference in sed replacements). Order matters.
-  for _var in PROJECT_NAME STACK_LABEL STACK_REF SOURCE_GLOB PATHSPEC_GLOBS ARBITER_AGENT VALIDATOR_AGENT GENERATED_AT; do
+  for _var in PROJECT_NAME STACK_LABEL STACK_REF SOURCE_GLOB PATHSPEC_GLOBS ARBITER_AGENT VALIDATOR_AGENT \
+              SCOPE_AGENT_A SCOPE_AGENT_B TRACKER_LABEL GENERATED_AT; do
    v="${!_var}"; v="${v//\\/\\\\}"; v="${v//&/\\&}"; printf -v "$_var" '%s' "$v"
  done

@@ -101,6 +138,9 @@ emit_skill() {
      -e "s${_sep}{PATHSPEC_GLOBS}${_sep}${PATHSPEC_GLOBS}${_sep}g" \
      -e "s${_sep}{ARBITER_AGENT}${_sep}${ARBITER_AGENT}${_sep}g" \
      -e "s${_sep}{VALIDATOR_AGENT}${_sep}${VALIDATOR_AGENT}${_sep}g" \
+      -e "s${_sep}{SCOPE_AGENT_A}${_sep}${SCOPE_AGENT_A}${_sep}g" \
+      -e "s${_sep}{SCOPE_AGENT_B}${_sep}${SCOPE_AGENT_B}${_sep}g" \
+      -e "s${_sep}{TRACKER_LABEL}${_sep}${TRACKER_LABEL}${_sep}g" \
      -e "s${_sep}{GENERATED_AT}${_sep}${GENERATED_AT}${_sep}g" \
      "$1" > "$2"
  }
@@ -114,6 +154,9 @@ emit_skill() {
  _subst "$REFS/report-template.md" "$TARGET_REFS/report-template.md"
  echo "✅ $TARGET_REFS/report-template.md"

+  _subst "$REFS/scope.md.template" "$TARGET_REFS/scope.md"
+  echo "✅ $TARGET_REFS/scope.md"
+
  if [ -f "$REFS/$STACK_REF" ]; then
    cp "$REFS/$STACK_REF" "$TARGET_REFS/$STACK_REF"
    echo "✅ $TARGET_REFS/$STACK_REF"
@@ -135,10 +178,11 @@ validate_emit() {
  fi

  # Runtime tokens the emitted skill legitimately keeps (resolved at REVIEW time, not GENERATION time).
-  _runtime='MODE|BRANCH|SCOPE|FILES|COUNT|TIMESTAMP|FOCUS|FILE_LIST|AGENT_LIST|CANDIDATES|MERGED|PATHSPEC|MAIN|SHA|FOLDER|GROUP|AGENT|N|OC|REPORT_DIR'
+  _runtime='MODE|BRANCH|SCOPE|FILES|COUNT|TIMESTAMP|FOCUS|FILE_LIST|AGENT_LIST|CANDIDATES|MERGED|PATHSPEC|MAIN|SHA|FOLDER|GROUP|AGENT|N|OC|SC|K|U|D|ROOT|TOK|RANGE|REPORT_DIR|SCOPE_BASELINE|OWNERSHIP|GATE_RESULTS|PR_ISSUE_JSON'

  _errors=0
-  for f in "$TARGET/SKILL.md" "$TARGET_REFS/agent-prompt.md" "$TARGET_REFS/report-template.md"; do
+  for f in "$TARGET/SKILL.md" "$TARGET_REFS/agent-prompt.md" "$TARGET_REFS/report-template.md" \
+           "$TARGET_REFS/scope.md"; do
    [ -f "$f" ] || continue
    _unresolved=$(grep -oE '\{[A-Z_]+\}' "$f" | sort -u | grep -vE "^\{(${_runtime})\}$" || true)
    if [ -n "$_unresolved" ]; then
@@ -189,6 +233,32 @@ EOF
    fi
  done

+  # (c) required emitted assets — a missing one silently guts a phase of the emitted skill.
+  for _req in "$TARGET_REFS/agent-prompt.md" "$TARGET_REFS/report-template.md" "$TARGET_REFS/scope.md"; do
+    if [ ! -f "$_req" ]; then
+      echo "❌ missing emitted asset: $_req"
+      _errors=$((_errors+1))
+    fi
+  done
+
+  # (d) DOMAIN EXPERTS — a review routed only to generic agents is a degraded review.
+  # Override with SUPERREVIEW_ALLOW_NO_EXPERTS=1 when the target genuinely has no domain agents.
+  _experts=0
+  for _name in $_local_agents; do
+    grep -qF "$_name" "$TARGET/SKILL.md" && _experts=$((_experts+1))
+  done
+  if [ "$_experts" -eq 0 ]; then
+    if [ "${SUPERREVIEW_ALLOW_NO_EXPERTS:-0}" = "1" ]; then
+      echo "⚠️ no project domain expert wired (allowed by SUPERREVIEW_ALLOW_NO_EXPERTS=1) — the emitted review is DEGRADED"
+    else
+      echo "❌ no project domain expert (.codex/agents/*.toml) is wired into SKILL.md — create the missing experts"
+      echo "   (see SKILL.md Phase 1.6) or re-run with SUPERREVIEW_ALLOW_NO_EXPERTS=1 to accept a degraded review"
+      _errors=$((_errors+1))
+    fi
+  else
+    echo "✅ domain experts wired: $_experts"
+  fi
+
  if [ "$_errors" -eq 0 ]; then
    echo "✅ no unresolved setup-time placeholders"
  fi
@@ -155,10 +155,10 @@ When other skills (convention, superreview, e2e) spawn agents, they check for te
 |----------|--------|---------|
 | 1 | Team agent | `.codex/agents/backend-api-expert.toml` (from teams) |
 | 2 | Project agent | `.codex/agents/custom-agent.toml` (manually created) |
-| 3 | Plugin agent | `brewcode:developer`, `brewcode:tester` |
-| 4 | System agent | `Explore`, `Plan` |
+| 3 | Plugin specialist | `brewcode:agent-creator`, `brewcode:bash-expert` |
+| 4 | System agent | `Explore`, `Plan`, `general-purpose` |

-> If a team agent refuses a task (sub-agent task Acceptance Protocol), the skill re-delegates to the next priority level. Max 2 retries before falling back to plugin agents.
+> If a team agent refuses a task (sub-agent task Acceptance Protocol), the skill re-delegates to the next priority level. Max 2 retries before falling back to system agents.

 ## Related Skills

@@ -64,6 +64,28 @@ Output: `MODE:`, `TEAM_NAME:`, `PROMPT:` (optional). Store all three.

 ---

+## Delegation (applies to EVERY sub-agent task spawn in this skill)
+
+A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct
+it, and it usually drifts off-target. One subagent = ONE bounded unit — one deliverable
+(here: ONE agent file), ~<=5 files, ~<=10 steps. Bigger MUST be split into N tasks, all spawned
+in ONE message. That is why agents are created one-per-spawn and reviews are fanned out.
+
+Every spawn prompt MUST carry:
+
+| Field | Content |
+|-------|---------|
+| GOAL | the overall task and why it exists — the point beyond the file edit |
+| ROLE | what this agent owns; what it must NOT touch |
+| SCOPE | exact paths/commands in bounds + explicit out-of-bounds |
+| CONTEXT | what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs |
+| CONSUMER | who or what uses the result next, and the shape it must fit |
+| DONE | acceptance criteria + the exact report shape you want back |
+
+A bare one-line task is never enough. See C8 for the canonical spawn shape.
+
+---
+
 ## Mode: CREATE (9 phases)

 ### C1: Project Analysis
@@ -116,7 +138,7 @@ If "Mixed" -- ask model per agent in C3. Store as `DEFAULT_MODEL` (default: high
 ### C3: Agent Creation (agent-creator x N)

 1. Read `<skill-directory>/references/agent-template.md`
-2. For each agent, spawn `Codex delegation brief (task_role="brewcode:agent-creator")` with: placement=`.codex/agents/`, reasoning_tier=DEFAULT_MODEL (or per-agent), context=template + mission + domain + project analysis + colleague list. Agent `description` <= 100 chars (optimal ~80), single line, role + 2-3 triggers, no `<example>` blocks.
+2. For each agent, spawn `Codex delegation brief (task_role="brewcode:agent-creator")` — ONE agent file per spawn, never "create the whole team" in one task. Prompt carries GOAL (this roster is being built for {TEAM_NAME}; siblings own the other domains), ROLE (owns `.codex/agents/{name}.toml` only), SCOPE (that file; out of bounds: other agents, team.md, project source), CONTEXT (mission + domain + project analysis from C1 are settled; reasoning_tier={DEFAULT_MODEL or per-agent} chosen in C2; the 3-4 sibling agent-creators in this batch own {COLLEAGUE_NAMES} — stay off their domains and do not duplicate their triggers), CONSUMER (C4 writes `.codex/teams/{TEAM_NAME}/team.md` from your path + description line, C5 quorum-reviews the file, and colleagues re-delegate to it by domain via the sub-agent task Acceptance Protocol), DONE (file written, `description` <= 100 chars (optimal ~80), single line, role + 2-3 triggers, no `<example>` blocks; report path + description line).
 3. Batch 3-4 agents in parallel per message
 4. After each batch, optimize:
   ```
@@ -142,7 +164,8 @@ If "Mixed" -- ask model per agent in C3. Store as `DEFAULT_MODEL` (default: high

 ### C5: Quorum Review

-Spawn 3 reviewer agents in ONE message via sub-agent collaboration tools:
+Spawn 3 reviewer agents in ONE message via sub-agent collaboration tools. `REVIEWER` (here and in C7/C9) = the
+project's reviewer agent from `.codex/agents/`, else `general-purpose`:

 | # | Focus |
 |---|-------|
@@ -171,7 +194,7 @@ FIX: suggested fix
 ### C7: Verification

 ```
-Codex delegation brief (task_role="brewcode:reviewer", message="
+Codex delegation brief (task_role=REVIEWER, message="
  Verify these findings against actual agent files. For each:
  1. Read the agent file
  2. Check if the issue actually exists
@@ -187,11 +210,22 @@ Filter out false positives. Final list = verified critical + important issues.
 For each verified critical/important issue:
 ```
 Codex delegation brief (task_role="brewcode:agent-creator", message="
-  Fix this issue in {agent_file}:
-  ISSUE: {description}
-  FIX: {suggested_fix}
-  SEVERITY: {severity}
-  Read the file, apply the fix, validate.
+  GOAL: team '{TEAM_NAME}' was just generated and quorum-reviewed; this task clears ONE
+        confirmed defect so the roster ships clean.
+  ROLE: you own {agent_file} only. Do NOT touch other agent files, team.md, trace.jsonl,
+        AGENTS.md, or project source.
+  SCOPE: {agent_file}. Out of bounds: everything else.
+  CONTEXT: C3 already wrote the whole roster and C5-C7 quorum-reviewed it; this finding is
+    verified (2/3 reviewers + C7 double-check) — do NOT re-litigate it. Up to 3 sibling
+    agent-creators fix other agent files in this same batch; team.md already lists the final
+    roster, so do not rename the agent or change its domain.
+    ISSUE: {description}
+    FIX: {suggested_fix}
+    SEVERITY: {severity}
+  CONSUMER: C9 re-verifies your file for "issue resolved + no regression", and the team
+    manifest .codex/teams/{TEAM_NAME}/team.md must stay accurate — keep name, domain and
+    description shape intact so its roster row still matches.
+  DONE: fix applied and validated; report as: file | what changed | validation result.
 ")
 ```
 Batch: up to 3 parallel per message. Minor issues skipped.
@@ -199,7 +233,7 @@ Batch: up to 3 parallel per message. Minor issues skipped.
 ### C9: Re-verify

 ```
-Codex delegation brief (task_role="brewcode:reviewer", message="
+Codex delegation brief (task_role=REVIEWER, message="
  Re-verify these fixes. For each:
  1. Read the fixed agent file
  2. Check original issue is resolved
@@ -1,3 +1,7 @@
 # Native Codex agent template

 Create a TOML file under `.codex/agents/` with `name`, `description`, and `developer_instructions`. The instructions define mission, domain, scope, task acceptance, self-check, and colleague handoff. Delegate through Codex collaboration with `task_name` and `message` only. Do not add Markdown frontmatter, tool allowlists, or legacy model aliases.
+
+Every generated agent states output discipline: return only what the main session needs, a verdict or result plus `file:line` pointers; write bulk material such as long logs, full diffs, or long reports to a file under `.codex/reports/<YYYYMMDD-HHMMSS>_<name>/` and return the path instead of the content.
+
+Agents whose domain writes code, scripts, SQL, schemas, infrastructure, or configuration also state scope fit: build for the scale and problems that exist today, not imagined load or speculative abstraction, and make one simplification pass after finishing. Omit that paragraph for research, documentation, and review-only agents.
@@ -16,7 +16,7 @@ try {
        systemMessage: `Brewtools manager prompt mode is active (${current.level})`,
        hookSpecificOutput: {
          hookEventName: 'SessionStart',
-          additionalContext: 'Manager prompt mode is active. Codex PreToolUse cannot distinguish parent and sub-agent calls, so this package does not claim a hard enforcement boundary.'
+          additionalContext: 'Manager prompt mode is active: delegate in bounded units (one deliverable, ~5 files) and split a big job across several agents rather than leaving one agent running for an hour, briefing each with goal + scope + what is already done + who consumes the result + acceptance. Codex PreToolUse cannot distinguish parent and sub-agent calls, so this package does not claim a hard enforcement boundary.'
        }
      });
    }
@@ -4,8 +4,11 @@ The user's ++M codeword authorizes foreground delegation for this task. Orchestr

 1. Inspect the applicable AGENTS.md files, current task state, and the minimum repository evidence needed to understand the request.
 2. Use update_plan for the session execution plan. If the project requires a durable board, synchronize it through its task-tracker workflow before implementation and again at completion.
-3. Map dependencies and split only independent, bounded workstreams. Parallelize useful read-only or non-overlapping work; keep dependent work sequential.
+3. Map dependencies and split only independent, bounded workstreams. One agent = one bounded unit (one deliverable, ~5 files, ~10 steps); anything larger is split into N tasks and fanned out. A big task handed to one agent is an agent gone for an hour: you cannot observe it, cannot correct it, and it usually drifts off-target. Parallelize useful read-only or non-overlapping work; keep dependent work sequential. Widest fan-out: a dependency must be a REAL data handoff, else parallel. Size a unit to ~<=20 min of agent work; longer -> split again.
 4. When delegation is useful, select the matching project expert from .codex/agents before built-in or global agents. If the collaboration surface cannot select a custom type, name the expert explicitly and include its developer instructions in the brief without claiming the type was instantiated.
-5. Use spawn_agent, send_message, followup_task, and wait_agent for foreground collaboration. Give each agent concrete scope, expected evidence, allowed mutation surface, and validation duties.
+5. Use spawn_agent, send_message, followup_task, and wait_agent for foreground collaboration. Give each agent the goal it serves, concrete scope with explicit out-of-bounds, the context it needs (what is already done and what runs in parallel, trimmed to that agent), who consumes its result and in what shape, expected evidence, allowed mutation surface, and validation duties.
 6. Review every delegated result before using it. Reconcile conflicts against authoritative project files and run validation proportional to risk.
-7. Lead the final handoff with the outcome, changed surfaces, exact validation, and any genuine remaining risk.
+7. Once ALL code is written (not per-piece), file one recommended final task: simplify the whole written code and strip over-engineering. Delegate it like any other task.
+8. Lead the final handoff with the outcome, changed surfaces, exact validation, and any genuine remaining risk.
+
+Branch: work in the current branch; none chosen -> main. Unless the user says branch/PR, stay on main and take over ALL workspace changes, incl. from other sessions.
@@ -4,11 +4,14 @@ The user's ++M codeword authorizes foreground delegation for this task. Orchestr

 1. Inspect the applicable AGENTS.md files, current task state, and the minimum repository evidence needed to understand the request.
 2. Use update_plan for the session execution plan. If the project requires a durable board, synchronize it through its task-tracker workflow before implementation and again at completion.
-3. Map dependencies and split only independent, bounded workstreams. Parallelize useful read-only or non-overlapping work; keep dependent work sequential.
+3. Map dependencies and split only independent, bounded workstreams. One agent = one bounded unit (one deliverable, ~5 files, ~10 steps); anything larger is split into N tasks and fanned out. A big task handed to one agent is an agent gone for an hour: you cannot observe it, cannot correct it, and it usually drifts off-target. Parallelize useful read-only or non-overlapping work; keep dependent work sequential. Widest fan-out: a dependency must be a REAL data handoff, else parallel. Size a unit to ~<=20 min of agent work; longer -> split again.
 4. When delegation is useful, select the matching project expert from .codex/agents before built-in or global agents. If the collaboration surface cannot select a custom type, name the expert explicitly and include its developer instructions in the brief without claiming the type was instantiated.
-5. Use spawn_agent, send_message, followup_task, and wait_agent for foreground collaboration. Give each agent concrete scope, expected evidence, allowed mutation surface, and validation duties.
+5. Use spawn_agent, send_message, followup_task, and wait_agent for foreground collaboration. Give each agent the goal it serves, concrete scope with explicit out-of-bounds, the context it needs (what is already done and what runs in parallel, trimmed to that agent), who consumes its result and in what shape, expected evidence, allowed mutation surface, and validation duties.
 6. Review every delegated result before using it. Reconcile conflicts against authoritative project files and run validation proportional to risk.
-7. Lead the final handoff with the outcome, changed surfaces, exact validation, and any genuine remaining risk.
+7. Once ALL code is written (not per-piece), file one recommended final task: simplify the whole written code and strip over-engineering. Delegate it like any other task.
+8. Lead the final handoff with the outcome, changed surfaces, exact validation, and any genuine remaining risk.
+
+Branch: work in the current branch; none chosen -> main. Unless the user says branch/PR, stay on main and take over ALL workspace changes, incl. from other sessions.

 # [ADDON: PLAN MODE]

@@ -1 +1 @@
-Perform two passes: first correctness and safety, then maintainability, clarity, and missing validation. Keep findings evidence-based.
+Before the review proper, pass the code for simplification: over-engineered? simpler? Then perform two passes: first correctness and safety, then maintainability, clarity, and missing validation. Keep findings evidence-based.
@@ -1 +1 @@
-Review for behavioral regressions first. Compare old and new contracts, exercise negative paths, and require evidence for compatibility claims.
+Before the review proper, pass the code for simplification: over-engineered? simpler? Then review for behavioral regressions first. Compare old and new contracts, exercise negative paths, and require evidence for compatibility claims.
@@ -8,11 +8,25 @@ Goal: inspect the TARGET repo and produce a FINDINGS object, then CONFIRM it wit

 Spawn these in a SINGLE message so they run concurrently. Use `subagent_type` shown; fall back to `general-purpose` if an agent is unavailable.

-### Agent A -- domains + release style  (`brewcode:architect`)
+> Sizing: one agent = ONE analysis dimension — ~<=10 steps; a dimension too big for that is split further and all parts fanned out in the SAME message.
+
+### Agent A -- domains + release style  (`Plan`)

 ```
-Codex delegation brief (task_role="brewcode:architect", message="
-Analyze the repo at TARGET=<abs path>. You are scoping a file-based Kanban id scheme. Return ONLY this block, no prose:
+Codex delegation brief (task_role="Plan", message="
+GOAL: deploying a file-based Kanban into the repo at TARGET=<abs path>. You are scoping its id scheme —
+  every emitted artifact is parametrized from this, so a wrong domain list produces broken ids repo-wide.
+ROLE: you own DOMAINS + RELEASE_STYLE. Analyze and report only — do NOT create, write or edit any file, and
+  do NOT report exclusions, doc language or the doc inventory (Agent B owns those).
+SCOPE: in — read TARGET: top-level source dirs, module/package names, bounded contexts, `git tag -l | head`,
+  CI config, AGENTS.md release section. Out — writing anything; .codex/features/**.
+CONTEXT: nothing has been generated yet; this is the first pass, running in parallel with Agent B
+  (exclusions + doc inventory). The user reviews your output in an request_user_input and may override it
+  before generation.
+CONSUMER: DOMAINS becomes the allowed id-segment enum in the emitted task-tracker agent, the tasks.md rule
+  and every minted id (<PREFIX>-<DOMAIN>-<SLUG>); RELEASE_STYLE picks the closing-marker wording. Both are
+  shown to the user verbatim, so keep each segment short and self-explanatory.
+DONE: return ONLY this block, no prose:

 DOMAINS:
 - 6-12 SHORT UPPER-KEBAB segments naming the repo's functional areas (the first kebab segment after an id prefix). Derive from top-level source dirs, module names, package names, bounded contexts, major features. Example shape (brewpage): HTML, KV, JSON, FILES, SITE, SEO, ABUSE, PREVIEW, DEDUP, SWEEP. Yours must reflect THIS repo.
@@ -31,7 +45,19 @@ Evidence: bullet the files/commands you used (git tag -l | head, package.json/bu

 ```
 Codex delegation brief (task_role="Explore", message="
-Explore the repo at TARGET=<abs path>. Return ONLY this block, no prose:
+GOAL: deploying a file-based Kanban into the repo at TARGET=<abs path>. The curator agent that ships with it
+  must never write outside .codex/features/, and the board must be seeded from the task docs the repo already
+  has — both come from this inventory.
+ROLE: you own EXCLUSIONS + LANG + DOCS. Explore and report only — do NOT create, write or edit any file, and
+  do NOT propose domains or a release style (Agent A owns those).
+SCOPE: in — read anywhere under TARGET to inventory it. Out — writing anything; classifying or rewriting the
+  legacy docs you find (a later sweep does that).
+CONTEXT: nothing has been generated yet; this is the first pass, running in parallel with Agent A (domains +
+  release style). The user reviews your output in an request_user_input and may override it before generation.
+CONSUMER: EXCLUSIONS is pasted verbatim into the emitted task-tracker agent + tasks.md rule as a hard
+  never-write list, and into every sweep agent's prompt; DOCS is the migration inventory the doc-sweep agents
+  are partitioned over — a doc you miss never reaches the board. Keep both as plain path lists.
+DONE: return ONLY this block, no prose:

 EXCLUSIONS:
 - The top-level SOURCE / build / test dirs a docs-only curator agent must NEVER write to. Include things like src/, app/, backend/, frontend/, lib/, e2e-tests/, tests/, docs/, and any language/build dirs. List the ACTUAL dirs present in this repo.
@@ -9,3 +9,5 @@ Write `TARGET/.codex/agents/task-tracker.toml` with exactly these TOML keys:
 `developer_instructions` owns only `.codex/features/**`. It enforces folder equals status, updates `board.md` in the same change as every transition, keeps stable upper-kebab ids, requires a file for progress tasks, records the configured close marker, and never touches application code. It reads `.codex/features/TRACKER.md` and the active task rule before mutation.

 Substitute the analyzed domains, exclusions, release-marker policy, and artifact language. Validate the result with Python `tomllib`.
+
+`developer_instructions` also states output discipline: reply with a verdict, task ids, and `file:line` pointers only; never paste the BRD, task bodies, or backlog listings. Write bulk material to a file under `.codex/reports/<YYYYMMDD-HHMMSS>_<name>/` and return the path.
@@ -10,16 +10,31 @@ Goal: consolidate every existing backlog/feature/task doc found in Step 1 (`DOCS

 Partition the `DOCS` inventory across N subagents (1 if small, 2-3 if many docs / large). Each gets a slice + the same contract. Use `general-purpose` (it must Read source docs and Write under `.codex/features/`).

+> Sizing: one agent = ONE doc slice — ~<=5 docs, ~<=10 steps; a bigger slice is split into more slices, all fanned out in the SAME message.
+
 ```
 Codex delegation brief (task_role="general-purpose", message="
-TARGET=<abs path>. You are migrating legacy task/backlog docs into a new file-based Kanban at TARGET/.codex/features/.
-You may WRITE only under TARGET/.codex/features/**. NEVER edit these source dirs: <EXCLUSIONS>.
-Procedure + format: read TARGET/.codex/features/TRACKER.md and TARGET/.codex/rules/tasks.md FIRST and follow them exactly.
-Id domains allowed: <DOMAINS>. Language: <LANG>. Closing marker style: <CLOSE_MARKER_SHORT>.
+GOAL: deploying a file-based Kanban into TARGET=<abs path>; the board skeleton exists and this pass fills it
+  from the repo's pre-existing task/backlog docs. Skip it and the board ships empty while the repo keeps two
+  sources of truth.
+ROLE: you own the slice of legacy docs listed below. Do NOT create tasks no document supports, do NOT author
+  board.md (the orchestrator does that after merging all slices), do NOT delete the legacy source docs.
+SCOPE: in — read your slice; WRITE only under TARGET/.codex/features/**.
+  Out — NEVER edit these source dirs: <EXCLUSIONS>; TARGET/AGENTS.md; .codex/agents; .codex/skills.
+  Your slice of legacy docs: <subset of DOCS with paths>.
+CONTEXT: Step 1 already confirmed with the user — id domains allowed: <DOMAINS>; language: <LANG>; closing
+  marker style: <CLOSE_MARKER_SHORT>; exclusions above. Step 4a-b already wrote the rule, the empty board
+  skeleton and TASK_TEMPLATE.md. Procedure + format: read TARGET/.codex/features/TRACKER.md and
+  TARGET/.codex/rules/tasks.md FIRST and follow them exactly — do not reinvent either. Sibling agents sweep
+  the OTHER doc slices into the same tree right now, so touch only your slice.
+CONSUMER: the orchestrator globs the status folders, reads each file's frontmatter and authors the real
+  board.md from what is on disk (your manifest is cross-checked against disk, not trusted); the installed
+  task-tracker agent reads the same files from then on. An id or status folder that deviates from
+  TASK_TEMPLATE.md makes the task invisible to both.
+DONE: return ONLY a manifest: a table of every file you created (path | id | status-folder | one-line title)
+  + a count of items skipped as noise + any duplicates folded. A no-op slice must say so explicitly.

-Your slice of legacy docs: <subset of DOCS with paths>.
-
-For each legacy item:
+Procedure — for each legacy item:
 1. Classify: open/ready task | in-progress | done/shipped | duplicate | noise/obsolete.
 2. open + scoped       -> create TARGET/.codex/features/todo/<ID>.md from TASK_TEMPLATE.md (or a board row if thin).
 3. clearly in-progress -> create under progress/<ID>.md (progress REQUIRES a file).
@@ -28,9 +43,6 @@ For each legacy item:
 6. duplicate           -> fold into the existing task's ## Notes, do not create a second.
 7. noise/obsolete      -> skip (do NOT create anything).
 Mint UPPER-KEBAB ids: <PREFIX>-<DOMAIN>-<SLUG>, domain from the allowed list. Ensure unique (Glob .codex/features/**/<ID>.md).
-Do NOT author board.md (the orchestrator does that after merging all slices). Do NOT delete the legacy source docs.
-
-Return ONLY a manifest: a table of every file you created (path | id | status-folder | one-line title) + a count of items skipped as noise + any duplicates folded.
 ")
 ```

@@ -1,6 +1,6 @@
 ---
 name: text-human
-description: "Humanizes code, docs, articles, reddit/chat, javadoc -- strips AI artifacts, fixes unicode, injects context-fit human style. Triggers - humanize, ai artifacts, unicode fix, article, reddit, javadoc, text."
+description: "Humanizes code, docs, articles, reddit/chat, javadoc -- strips AI artifacts, fixes unicode, fits register. Triggers: humanize, ai artifacts, unicode fix, article, reddit, javadoc."
 ---

 # Humanize text
@@ -83,6 +83,40 @@ CUSTOM INSTRUCTIONS (highest priority, override defaults):
 ---
 ```

+### Delegation (mixed flow)
+
+A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct it, and it usually drifts off-target. One subagent = ONE bounded unit — ONE block of ~<=5 files, ~<=10 steps. A large commit or folder MUST be split into N blocks, all spawned in ONE message.
+
+Every spawn prompt MUST carry:
+
+| Field | Content |
+|-------|---------|
+| GOAL | the overall task and why it exists — the point beyond the file edit |
+| ROLE | what this agent owns; what it must NOT touch |
+| SCOPE | exact paths/commands in bounds + explicit out-of-bounds |
+| CONTEXT | what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs |
+| CONSUMER | who or what uses the result next, and the shape it must fit |
+| DONE | acceptance criteria + the exact report shape you want back |
+
+A bare one-line task is never enough. Shape:
+```
+Codex delegation brief (task_role="general-purpose", message="
+GOAL: humanizing <commit|folder> so it reads as human-written; you own block <N>/<M>,
+  siblings own the rest and the reports are merged into one Humanization Report.
+ROLE: edit only your block's files in place. Do NOT touch files outside the block,
+  do NOT auto-fix behavior-changing items — surface them instead.
+SCOPE: in — <exact file list>. Out — every other path, git history, build output.
+CONTEXT: classification is already done — flow=<code|docs|social|article> per file, PASS 2
+  inject <ON|OFF> for this domain, custom instructions (verbatim, highest priority) if any.
+  Sibling agents hold blocks <list> of the same commit; every file outside your list is
+  already claimed, so a "helpful" extra edit collides with another agent.
+CONSUMER: the skill merges each block's JSON into one Humanization Report; the user acts on
+  'surfaced' items by hand, so a surfaced item you silently fixed never reaches them.
+DONE: JSON per the mixed.md aggregation schema — stripped, injected, surfaced per file.
+  Surfaced items are listed, never applied.
+")
+```
+
 ---

 ## Output -- Humanization Report
@@ -52,8 +52,8 @@ Group by type and complexity (avoid mixing fast model/balanced model in one bloc
 Launch ALL sub-agent calls in a single message for true parallelism. Each block prompt states its files, the sub-flow each file uses, the two-pass rules, and requests JSON.

 ```
-Codex delegation brief (task_role="developer", reasoning_tier="fast model", message="> <plugin-root> is in your context (pre-task.mjs).\n[CUSTOM_INSTRUCTIONS_IF_ANY]\nBlock 1 files: [...]. Per file apply its flow rules from $<plugin-root>/skills/text-human/reference/flows/<flow>.md plus ai-patterns.md / human-patterns.md. Two-pass: STRIP then gated INJECT. Return JSON.")
-Codex delegation brief (task_role="developer", reasoning_tier="balanced model", message="> <plugin-root> is in your context (pre-task.mjs).\n[CUSTOM_INSTRUCTIONS_IF_ANY]\nBlock 2 files: [...]. Same rules. Return JSON.")
+Codex delegation brief (task_role="general-purpose", reasoning_tier="fast model", message="> <plugin-root> is in your context (pre-task.mjs).\n[CUSTOM_INSTRUCTIONS_IF_ANY]\nBlock 1 files: [...]. Per file apply its flow rules from $<plugin-root>/skills/text-human/reference/flows/<flow>.md plus ai-patterns.md / human-patterns.md. Two-pass: STRIP then gated INJECT. Return JSON.")
+Codex delegation brief (task_role="general-purpose", reasoning_tier="balanced model", message="> <plugin-root> is in your context (pre-task.mjs).\n[CUSTOM_INSTRUCTIONS_IF_ANY]\nBlock 2 files: [...]. Same rules. Return JSON.")
 ```

 If a custom prompt was provided, prepend to EVERY sub-agent prompt after the context line:
@@ -1,6 +1,6 @@
 # Text Optimizer

-Optimizes text files for LLM token efficiency with 4 compression modes — from light cleanup to deep dictionary-encoded compression for LLM-only documents. Applies 40+ validated rules for current Codex models, supports smart auto-detection of optimal mode, and verifies no information loss. Works on single files, multiple files in parallel, or entire directories.
+Optimizes text files for LLM token efficiency with 5 compression modes — from light cleanup to deep dictionary-encoded compression for LLM-only documents. Applies 52 validated rules for current Codex models, supports smart auto-detection of optimal mode, and verifies content against per-mode loss budgets (lossless through standard; small explicit loss at deep/max). Works on single files, multiple files in parallel, or entire directories. Includes a smart deduplication pass: accidental repeats merged, intentional emphasis capped at 2 per document.

 ## Quick Start

@@ -17,7 +17,8 @@ Auto-detects optimal mode for the file (deep for AGENTS.md, standard for README.
 | **Light** | `-l` | Critical files, production prompts | Filler removal, tone fixes, reference checks — structure untouched |
 | **Medium** | _(default)_ | General docs, agents, skills | Tables, bullets, merged sections, full rule set |
 | **Standard** | `-s` | README, docs, user-facing content | 30-50% compression preserving human readability. Filler removal, paragraph→bullets, prose→tables. 1 verification round |
-| **Deep** | `-d` | AGENTS.md, system prompts, agent/skill defs | 2-3x compression for LLM-only consumption. Dictionary encoding, symbol substitutions, abbreviation tables. 2 verification rounds |
+| **Deep** | `-d` | AGENTS.md, system prompts, agent/skill defs | 2-3x compression for LLM-only consumption. Dictionary encoding, symbol substitutions, abbreviation tables, plus aggressive lossy pass (line fusion, word drop, paraphrase, known-fact elision) gated at >=95% semantic match. 1-2 verification rounds |
+| **Max** | `-x` | Cost-critical LLM-only prompts (opt-in) | 3-4x. Atomic fact-lines, ASCII operators, Chain-of-Density pass, same aggressive lossy pass as deep (A.1-A.4), same gate. 2 independent verification rounds |

 ## Examples

@@ -97,12 +98,14 @@ Prompt text can also hint at the mode: "compress for LLM" → deep, "safe compre

 ## Verification

-Standard and deep modes include automatic verification to prevent information loss.
+Medium runs a self-check; standard, deep, and max run automatic verification rounds against per-mode loss budgets.

 | Mode | Rounds | Pass Threshold |
 |------|--------|----------------|
-| Standard | 1 | All facts preserved |
-| Deep | 2 | >= 95% semantic match |
+| Medium | self-check | Zero loss |
+| Standard | 1 | >= 98% fact inventory |
+| Deep | 1-2 | >= 95% |
+| Max | 2 (independent methods) | >= 95% + 100% of numbers/names/negations/scope qualifiers |

 The report includes a semantic match percentage and lists any facts that were lost or distorted during compression.

@@ -110,12 +113,14 @@ The report includes a semantic match percentage and lists any facts that were lo

 - Converts verbose prose to dense tables (up to 3x more token-efficient)
 - Removes filler words and passive constructions
+- Deduplicates: merges accidental repeats, caps intentional emphasis at 2 per document (full form early + short echo at end)
 - Restructures numbered lists to bullets where order does not matter
 - Converts multi-line code blocks to inline code when a single expression suffices
 - Merges redundant or overlapping sections
 - Applies positive framing ("do Y" instead of "don't do X")
 - Verifies all file paths (R.1), URLs (R.2), and circular references (R.3)
 - Uses standard abbreviations in tables only (full words in prose)
+- Deep/max apply the A.1-A.4 lossy pass (see Modes); A.2/A.4 drops logged in loss ledger

 ## Output

@@ -26,10 +26,22 @@ Parse `<arguments>`: `-l`/`--light` | `-s`/`--standard` | `-d`/`--deep` | `-x`/`
 | Mode | Flag | Target | Compression | Human-readable | Verification |
 |------|------|--------|-------------|----------------|--------------|
 | Light | `-l`, `--light` | Any | Minimal | Yes | None |
-| Medium | _(default)_ | Any | Moderate | Yes | None |
-| Standard | `-s`, `--standard` | Docs, README | 30-50% | Yes | 1 round |
-| Deep | `-d`, `--deep` | AGENTS.md, system prompts, agent/skill defs, KNOWLEDGE | 2-3x | No (LLM-only) | 1-2 rounds |
-| Max | `-x`, `--max` | AGENTS.md, system prompts, KNOWLEDGE | 3-4x | No (LLM-only) | 2 (mandatory) |
+| Medium | _(default)_ | Any | Moderate | Yes | Self-check (fact inventory) |
+| Standard | `-s`, `--standard` | Docs, README | 30-50% | Yes | 1 round (>=98%) |
+| Deep | `-d`, `--deep` | AGENTS.md, system prompts, agent/skill defs, KNOWLEDGE | 2-3x | No (LLM-only) | 1-2 rounds (>=95%) |
+| Max | `-x`, `--max` | AGENTS.md, system prompts, KNOWLEDGE | 3-4x | No (LLM-only) | 2 mandatory (>=95% + 100% sub-gate) |
+
+## Loss Budget per Mode
+
+Content essence is untouchable at light/medium/standard; small deliberate loss is allowed only at deep/max — explicitly reported. Dedup-merged facts count as preserved, never as loss.
+
+| Mode | Semantic match target | Allowed loss |
+|------|----------------------|--------------|
+| Light | 100% | None — wording cleanup only |
+| Medium | 100% | None — restructure, zero fact loss (self-check) |
+| Standard | >= 98% | None intended; verification patches any slip |
+| Deep | >= 95% | Word-level drops (A.2, ledgered, gate-neutral) + generic known-facts (A.4, `elided-known`, consumes gate), listed in report |
+| Max | >= 95% + 100% sub-gate (numbers/names/negations/scope) | Small, explicit, user-reviewed loss list |

 ## Smart Auto-Detection

@@ -63,46 +75,37 @@ When no flag provided AND input suggests compression (not just optimization):
 | Codex behavior | C.1-C.8 | Literal following, avoid "think", positive framing, match style, descriptive instructions, overengineering, avoid ALL-CAPS, prompt format |
 | Token efficiency | T.1-T.8, T.10 | Tables, bullets, one-liners, inline code, abbreviations, filler, comma lists, arrows, strip whitespace |
 | Structure | S.1-S.8 | XML tags, imperative, single source, context/motivation, blockquotes, progressive disclosure, consistent terminology, ref depth |
+| Deduplication | D.1-D.6 | Exact/near/cross-format merge, emphasis cap <=2, cross-file SSOT, wrong-merge guard |
 | Reference integrity | R.1-R.3 | Verify file paths, check URLs, linearize circular refs |
 | Perception | P.1-P.6 | Examples near rules, hierarchy, bold keywords, standard symbols, instruction order, default over options |
-| LLM Comprehension | L.1-L.7 | Critical info position, documents-first, conciseness, quote-first, add WHY, reiterate constraint, prompt repetition |
+| LLM Comprehension | L.1-L.8 | Critical info position, documents-first, conciseness, quote-first, add WHY, reiterate constraint, prompt repetition, preserve scope qualifiers |
+| Aggressive lossy | A.1-A.4 | Line fusion, word drop, paraphrase, known-fact elision (deep/max) |

-### ID-to-Rule Mapping
-
-| ID | Rule | ID | Rule |
-|----|------|----|------|
-| C.1 | Literal instruction following | C.2 | Avoid "think" word |
-| C.3 | Positive framing (do Y not don't X) | C.4 | Match prompt style to output |
-| C.5 | Descriptive over emphatic instructions | C.6 | Overengineering prevention |
-| T.1 | Tables over prose (multi-column) | T.2 | Bullets over numbered (~5-10%) |
-| T.3 | One-liners for rules | T.4 | Inline code over blocks |
-| T.5 | Standard abbreviations (tables only) | T.6 | Remove filler words |
-| T.7 | Comma-separated inline lists | T.8 | Arrows for flow notation |
-| S.1 | XML tags for sections | S.2 | Imperative form |
-| S.3 | Single source of truth | S.4 | Add context/motivation |
-| S.5 | Blockquotes for critical | S.6 | Progressive disclosure |
-| R.1 | Verify file paths | R.2 | Check URLs |
-| R.3 | Linearize circular refs | P.1 | Examples near rules |
-| P.2 | Hierarchy via headers (max 3-4) | P.3 | Bold for keywords (max 2-3/100 lines) |
-| P.4 | Standard symbols (→ + / ✅❌⚠️) | | |
-| S.7 | Consistent terminology | S.8 | One-level reference depth |
-| P.5 | Instruction order (anchoring) | P.6 | Default over options |
-| C.7 | Avoid ALL-CAPS emphasis (4.x) | C.8 | Prompt format → output format |
-| T.10 | Strip whitespace from code | | |
-| L.1 | Critical info at START or END | L.2 | Documents first, query last |
-| L.3 | Explicitly request conciseness | L.4 | Quote-first grounding |
-| L.5 | Add WHY to instructions | L.6 | Reiterate constraint at END |
-| L.7 | Prompt repetition (non-reasoning) | | |
+> Full per-ID definitions live in `references/rules-review.md` (loaded at Step 0) — do not restate them here.

 ## Mode-to-Rules Mapping

 | Mode | Applies | Notes |
 |------|---------|-------|
-| Light | C.1-C.8, T.6, R.1-R.3, P.1-P.4, L.1-L.7 | Text cleanup only — no restructuring |
-| Medium | All rules (C + T + S + R + P + L) | Balanced transformations |
-| Standard | All rules (C + T + S + R + P + L) + `references/standard-compression.md` | 30-50% compression, human-readable, 1 verification round |
-| Deep | All rules (C + T + S + R + P + L) + `references/deep-compression.md` | DICT header, symbol substitutions, 1-2 verification rounds (conditional) |
-| Max | All rules (C + T + S + R + P + L) + `references/deep-compression.md` + `references/max-compression.md` | Atomic fact-lines, ASCII operators, format-aware tables, 4 mandatory guardrails, 2 verification rounds |
+| Light | C.1-C.8, T.6, D.1, R.1-R.3, P.1-P.4, L.1-L.8 | Text cleanup + exact-dup removal — no restructuring |
+| Medium | All rules (C + T + S + D + R + P + L) | Balanced transformations |
+| Standard | All rules (C + T + S + D + R + P + L) + `references/standard-compression.md` | 30-50% compression, human-readable, 1 verification round |
+| Deep | All rules (C + T + S + D + R + P + L) + A.1-A.4 + `references/deep-compression.md` | DICT header, symbol substitutions, aggressive lossy pass, 1-2 verification rounds (conditional) |
+| Max | All rules (C + T + S + D + R + P + L) + A.1-A.4 + `references/deep-compression.md` + `references/max-compression.md` | Atomic fact-lines, ASCII operators, format-aware tables, 4 mandatory guardrails, 2 verification rounds |
+
+> D.5 (cross-file dedup) applies in ANY mode when processing multiple files or a folder. D.6 wrong-merge guard is mandatory wherever D.2/D.3/D.5 run.
+
+## Deduplication Pass (All Modes)
+
+Runs during analysis, BEFORE compression:
+
+1. Build fact inventory: one atomic fact per line, numbered
+2. Flag facts appearing 2+ times (exact, reworded, or cross-format)
+3. Classify each repeat: intentional emphasis (marked critical/blockquote, or start+end sandwich) vs accidental (everything else)
+4. Accidental -> merge to single MOST SPECIFIC statement (D.1-D.3), best position wins
+5. Intentional -> cap at 2: full form early + <=1-line echo at END (D.4)
+6. Wrong-merge guard (D.6): differing scope/numbers/conditions = NOT duplicates — keep both
+7. Deep/max: record merges in dedup ledger (kept <- dropped) for verification

 ## Usage Examples

@@ -135,18 +138,50 @@ When no flag provided AND input suggests compression (not just optimization):

 > **Orchestration:** Phase 1+2 are executed by the SKILL in the main conversation (manager level). The text-optimizer agent handles single-file optimization only — it cannot spawn sub-agents.

+### Delegation
+
+A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct it, and it usually drifts off-target. One subagent = ONE bounded unit — ONE file, ~<=10 steps. A folder or multi-path run MUST be split one-file-per-agent, all spawned in ONE message.
+
+Every spawn prompt MUST carry:
+
+| Field | Content |
+|-------|---------|
+| GOAL | the overall task and why it exists — the point beyond the file edit |
+| ROLE | what this agent owns; what it must NOT touch |
+| SCOPE | exact paths/commands in bounds + explicit out-of-bounds |
+| CONTEXT | what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs |
+| CONSUMER | who or what uses the result next, and the shape it must fit |
+| DONE | acceptance criteria + the exact report shape you want back |
+
+A bare one-line task is never enough.
+
 **Phase 1: Analysis** — Parallel `Explore` agents

 ```
 Codex delegation brief (task_role: "Explore", prompt: "Analyze {file}: structure, dependencies, cross-refs, redundancies")
 ```

-**Phase 2: Optimization** — Parallel text-optimizer agents
-
-> **Context:** <plugin-root> is available in your context (injected by pre-task.mjs hook). Use it to access plugin resources.
+**Phase 2: Optimization** — Parallel text-optimizer agents, full brief shape:

 ```
-Codex delegation brief (task_role: "text-optimizer", prompt: "FIRST: Read $<plugin-root>/skills/text-optimize/references/rules-review.md for validation rules. FOR STANDARD MODE: Also read $<plugin-root>/skills/text-optimize/references/standard-compression.md. FOR DEEP MODE: Also read $<plugin-root>/skills/text-optimize/references/deep-compression.md. FOR MAX MODE: Also read $<plugin-root>/skills/text-optimize/references/max-compression.md and apply atomic fact-line decomposition + ASCII operator dialect + guardrails; run 2 verification rounds. THEN optimize {file} using {mode} mode. Apply transformations, verify refs, output report with metrics.")
+Codex delegation brief (task_role: "text-optimizer", prompt: "
+GOAL: cutting token cost across {N} files for this repo without losing meaning; you own
+  {file} only, sibling agents own the rest and the reports are merged.
+ROLE: optimize {file} in place. Do NOT touch any other file, do NOT change behavior,
+  do NOT drop project-specific names, numbers, paths, versions or prohibitions.
+SCOPE: in — {file}. Out — every other path; references/ are read-only inputs.
+CONTEXT: mode={mode} is already chosen (loss budget per the mode table); Phase 1 Explore
+  already analyzed {file} — findings: {cross-refs, redundancies}, so do not re-analyze.
+  Sibling agents are optimizing the other {N-1} files of this run at the same time; rule and
+  compression references come from your agent definition Step 0/Step 2 (<plugin-root>
+  is natively substituted at spawn).
+CONSUMER: the skill merges every agent's Optimization Report into one summary for the user;
+  {file} itself is consumed by an LLM loading it as a prompt/doc, and other files still point
+  at its headings — a heading you rename must stay resolvable or you break a sibling's file.
+DONE: run the dedup pass (D.1-D.6) before compressing, apply transformations, verify refs
+  (R.1-R.3), run the mode's verification protocol, then output the Optimization Report
+  (metrics table + rules applied + fact-inventory result + semantic match %).
+")
 ```

 > **Spawn parallel:** For multiple files, spawn ALL agents in ONE message for speed.
@@ -168,26 +203,34 @@ Codex delegation brief (task_role: "text-optimizer", prompt: "FIRST: Read $<plug
 | S.1-S.8 (structure/clarity) | - | Yes | Yes | Yes | Yes |
 | R.1-R.3 (reference integrity) | Yes | Yes | Yes | Yes | Yes |
 | P.1-P.4 (LLM perception) | Yes | Yes | Yes | Yes | Yes |
-| L.1-L.7 (LLM comprehension) | Yes | Yes | Yes | Yes | Yes |
+| P.5-P.6 (anchoring, default-over-options) | - | Yes | Yes | Yes | Yes |
+| L.1-L.8 (LLM comprehension) | Yes | Yes | Yes | Yes | Yes |
+| D.1 (exact dedup) | Yes | Yes | Yes | Yes | Yes |
+| D.2-D.4, D.6 (smart dedup + emphasis cap) | - | Yes | Yes | Yes | Yes |
+| D.5 (cross-file dedup, multi-file runs) | Yes | Yes | Yes | Yes | Yes |
 | Standard compression ref | - | - | Yes | - | - |
 | Deep compression ref + DICT | - | - | - | Yes | Yes |
+| A.1-A.4 (aggressive lossy) | - | - | - | Yes | Yes |
 | Aggressive rephrasing | - | - | - | Yes | Yes |
 | Max compression ref (atomic fact-lines) | - | - | - | - | Yes |
 | Guardrails C1-C4 (scope, punctuation, signal/token) | - | - | - | - | Yes |
-| Verification round(s) | - | - | 1 | 2 | 2 |
-| No information loss | Yes | Yes | Yes | Yes | Yes |
+| Verification round(s) | - | self | 1 | 1-2 | 2 |
+| Loss within mode budget (see Loss Budget) | 100% | 100% | >=98% | >=95% | >=95% |

 ## Deep Mode Pipeline

 ### Phase 1: Compress
 - Load `references/deep-compression.md` for symbol/abbreviation tables
+- Dedup pass (D.1-D.6) + dedup ledger before symbol substitution (see deep-compression.md Redundancy Factoring + Token-Class Keep/Drop Heuristics)
+- Aggressive lossy pass (A.1-A.4) after dedup: line fusion (A.1) -> paraphrase (A.3) -> word drop (A.2) -> knowledge elision (A.4); record every A.2/A.4 drop in loss ledger (dropped -> reason)
 - Scan text for terms occurring 3+ times → build DICT header
 - Apply symbol substitutions, filler removal, structural compression
 - Apply existing rules (C, T, S, R, P) in addition to deep techniques

 ### Phase 2: Verify Round 1
 - Spawn verification agent with ORIGINAL + COMPRESSED text
- Agent reads both, lists all lost/distorted facts
+- Agent extracts numbered atomic-fact inventory from ORIGINAL, checks each in COMPRESSED, labels kept/merged/lost/distorted; match % = (kept + merged) / total; verifies no two distinct facts merged into one (D.6)
+- A.1 fused / A.3 paraphrased facts count as kept/merged; A.4 elisions labeled `elided-known` in loss list and count as loss against the 95% gate
 - Calculate semantic match %
 - If >= 95% → done
 - If < 95% → return loss list for patching
@@ -197,37 +240,43 @@ Codex delegation brief (task_role: "text-optimizer", prompt: "FIRST: Read $<plug
 - Re-verify
 - If still < 95% → warn user with loss list
 - Output final result + statistics
+- Optional reconstruction probe: expand compressed back to prose, diff entities/numbers vs original (entities are lost first)

 ## Max Mode Pipeline

 ### Phase 1: Compress
- Apply all Deep techniques (DICT header, symbol substitutions, structural compression)
+- Dedup pass (D.1-D.6) + build dedup ledger before symbol substitution (deep-compression.md Redundancy Factoring)
+- Apply all Deep techniques (DICT header, symbol substitutions, structural compression, aggressive lossy A.1-A.4 with loss ledger, inherited from deep)
 - Load `references/max-compression.md` for atomic fact-line decomposition, ASCII operator dialect, format-aware tables
 - Respect guardrails C1-C4: optimize for signal/token (not raw token count); preserve scope qualifiers; ~20% deletion ceiling — never strip punctuation; consistent terminology throughout
+- Chain-of-Density final pass (B4): fuse missing entities at fixed length

-### Phase 2: Verify Round 1
- Spawn verification agent with ORIGINAL + COMPRESSED text
- Calculate semantic match %
- Gate at >= 95% → proceed; if < 95% → return loss list
+### Phase 2: Verify Round 1 — Claim Inventory
+- Spawn verification agent with ORIGINAL + COMPRESSED
+- Agent decomposes original into numbered atomic claims (one predicate per claim), labels each kept/merged/lost/distorted
+- Semantic match % = (kept + merged) / total; merged (deduplicated) facts = preserved; A.1 fused / A.3 paraphrased facts = kept/merged; A.4 elisions labeled `elided-known` = loss against the 95% gate
+- Gate >= 95% -> proceed; < 95% -> return loss list

-### Phase 3: Patch + Verify Round 2 (MANDATORY)
- Apply patches for missing/distorted facts
- Re-verify — Round 2 is mandatory, NEVER skip
- If still < 95% → warn user with explicit loss list
+### Phase 3: Patch + Verify Round 2 — Self-QA Probe (MANDATORY)
+- Apply patches; Round 2 is mandatory, NEVER skip; use the INDEPENDENT method: generate 10-20 questions from original (entities, numbers, conditions, negations), answer from compressed only
+- Sub-gate: 100% of numbers, names, negations, scope qualifiers must survive
+- If still < 95% or sub-gate fails -> warn user with explicit loss list (lost/distorted/merged/elided-known labels)
 - Output final result + statistics

 ## Standard Mode Pipeline

 ### Phase 1: Compress
 - Load `references/standard-compression.md`
+- Dedup pass (D.1-D.4, D.6) on fact inventory — merge accidental repeats, cap emphasis at 2
+- Sentence-level zero-loss pruning before wording compression
 - Remove filler words/constructions
 - Merge repeated ideas
 - Convert paragraphs to bullets/tables where appropriate
 - Apply existing rules (C, T, S, R, P)

 ### Phase 2: Verify
- Compare compressed vs original
- List any lost facts → patch
+- Extract atomic-fact inventory from original; check each fact in compressed
+- Gate: (kept + merged) / total >= 98% — list lost facts -> patch
 - One round only

 ## Iron Rules (All Modes)
@@ -239,11 +288,13 @@ Codex delegation brief (task_role: "text-optimizer", prompt: "FIRST: Read $<plug
 | Preserve | At least one example per rule with examples |
 | Preserve | Scope qualifiers ("every section, not just the first") — high-reasoning model 4.8 literalism (Max/Deep) |
 | Deep only | DICT header at document start |
+| Deep/Max | A.2/A.4 drops recorded in loss ledger; never elide project-specific facts (names, numbers, paths, versions, prohibitions) |
 | Max only | Atomic fact-lines, ASCII operators over unicode glyphs, 2 mandatory verification rounds |
+| Dedup | Accidental dups merged; intentional emphasis <= 2/doc, 2nd occurrence short @ END (D.4); merged facts = preserved, never counted as loss |
 | Output | Statistics: original (chars/words/~tokens), compressed (chars/words/~tokens), ratio, semantic match % |

 ### After
- [ ] All facts preserved
+- [ ] All facts preserved (except ledgered A.2/A.4 drops at deep/max)
 - [ ] Logic consistent
 - [ ] References valid (R.1-R.3)
 - [ ] Tokens reduced
@@ -283,4 +334,5 @@ Codex delegation brief (task_role: "text-optimizer", prompt: "FIRST: Read $<plug
 | Overengineer prompts | high-reasoning model 4.5 follows literally (C.6) |
 | Overload single prompts | Divided attention, hallucinations (S.3) |
 | Over-focus on wording | Structure > word choice (T.1) |
+| Merge similar-looking facts blindly | Different scope/numbers/conditions = different facts (D.6) |

@@ -14,7 +14,7 @@ Reference for deep compression mode applied to LLM-only documents (AGENTS.md, sy
 | `so` / `->` | therefore, consequently (was `∴`) |
 | `bc` / `because` | because, since (was `∵`) |
 | `@` | at, located at |
-| `|` | or, alternative |
+| `\|` | or, alternative |
 | `:` | has property, contains |
 | `~` | approximately |
 | `includes` | includes, contains (set) (was `⊃`) |
@@ -99,6 +99,51 @@ Apply filler removal from `rules-review.md` rule T.6. Additional deep-mode remov
 - Headers: flatten to 2 levels max
 - Remove blank lines between items in lists/tables

+## Redundancy Factoring
+
+Run dedup pass (D.1-D.6, rules-review.md) BEFORE symbol substitution — merging first shrinks the text remaining passes must process and keeps verification cheap. Record merges in a dedup ledger (kept <- dropped).
+
+- Phrase-DICT: recurring phrase >= 3 words appearing 2+ times -> DICT entry (counts toward the 20-entry cap). Source: CompactPrompt arXiv:2510.18043
+- Path-prefix hoisting: repeated path/URL prefixes -> single DICT entry (e.g. `[DICT: SR=src/main/resources]`)
+- Header echo removal: subsection headers repeating parent header words -> drop the echo ("## Server Config / ### Server Config Ports" -> "### Ports")
+- Number/unit normalization: "approximately 30 percent" -> `~30%`; "greater than or equal to 21" -> `>=21`
+
+## Token-Class Keep/Drop Heuristics
+
+Source: LLMLingua-2 arXiv:2403.12968. When compressing at word level:
+
+| Keep | Drop (when meaning survives) |
+|------|------------------------------|
+| Nouns, verbs, numerals, NEGATIONS, named entities | Determiners, copulas ("is", "are"), auxiliaries, discourse connectors ("furthermore", "as a result") |
+
+Never drop negations or scope qualifiers (L.8; max-mode guardrail C2).
+
+## Aggressive Lossy Techniques (A.1-A.4)
+
+Deep/max only. Rule definitions: rules-review.md category A. Application order:
+
+dedup (D.1-D.6) -> line fusion (A.1) -> paraphrase (A.3) -> word drop (A.2) -> knowledge elision (A.4) -> symbol substitution
+
+Loss ledger REQUIRED: every A.2/A.4 drop recorded as `dropped -> reason`, listed in the report. A.4 elisions count against the fact-level loss budget (deep gate >= 95%) as `elided-known`; A.2 is word-level and gate-neutral — ledgered for transparency, no direct gate impact, but if a drop degrades a fact's meaning the verifier labels that fact `distorted` (normal gate impact). A.1/A.3 results count as preserved (kept/merged), no ledger entry. Guards: never drop negations, numbers, named entities, scope qualifiers (L.8, C2); D.6 wrong-merge guard applies before A.1 fusion; unsure whether A.4 knowledge is generic -> keep.
+
+### Example: A.1 fusion + A.3 paraphrase (loss-free)
+
+**Original**:
+> The deployment script should be executed from the project root directory. In the event that the script fails, you can check the log file which is located at `logs/deploy.log`.
+
+**Compressed**:
+> run deploy script from project root | fail -> check `logs/deploy.log`
+
+### Example: A.4 elision, project delta kept
+
+**Original**:
+> Always write unit tests for new code, since testing catches regressions early. Keep functions small and readable. The project coverage gate is 85% (jacoco); builds fail below it.
+
+**Compressed**:
+> coverage gate 85% (jacoco), build fails below
+
+Ledger: dropped "write unit tests / catches regressions" -> generic LLM knowledge; dropped "keep functions small" -> generic. Kept: 85%, jacoco, build-fail behavior (project-specific).
+
 ## Iron Rules

 Preserve in ALL cases regardless of compression level:
@@ -106,6 +151,8 @@ Preserve in ALL cases regardless of compression level:
 - Negative rule semantics (use `!=` notation)
 - At least one example per rule that originally has examples
 - DICT header at document start
+- Dedup ledger: every merged pair recorded (kept <- dropped); merged facts count as preserved in verification
+- Loss ledger: every A.2/A.4 drop recorded (dropped -> reason); never elide project-specific facts (names, numbers, paths, versions, prohibitions)

 ## Before/After Examples

@@ -2,7 +2,7 @@

 Max mode = deep compression + atomic-fact-line rewriting + format-aware tables. LLM-only. Opt-in via `-x`/`--max`. ALWAYS runs 2 verification rounds. Use only when caller explicitly wants maximum density and accepts review burden.

-> Inherits everything in `deep-compression.md`. Max adds 3 techniques (B1, A1, B3) + 4 guardrails (C1-C4) + mandatory 2-round verify.
+> Inherits everything in `deep-compression.md`, including aggressive lossy rules A.1-A.4 (dotted, rules-review.md category A) with their loss-ledger requirement. Max adds 4 techniques (B1, A1, B3, B4) + 4 guardrails (C1-C4) + mandatory 2-round verify. Dotless A1 below = ASCII operator dialect, distinct from dotted A.1 (line fusion).

 ## Atomic Fact-Line Decomposition (B1)

@@ -28,7 +28,7 @@ Prefer ASCII digraphs over unicode glyphs. Measured token cost (tiktoken cl100k/

 | Glyph | Tokens | ASCII | Tokens |
 |-------|--------|-------|--------|
-| `∵` `∴` `⊃` `≤` `≥` | 2-3 each | `->` `!=` `>=` `<=` `|` | 1 each |
+| `∵` `∴` `⊃` `≤` `≥` | 2-3 each | `->` `!=` `>=` `<=` `\|` | 1 each |
 | `→` | 1 | `->` | 1 (equally cheap + portable) |

 Mapping:
@@ -39,7 +39,7 @@ Mapping:
 | not / never | `!=` |
 | greater | `>=` |
 | less | `<=` |
-| or | `|` |
+| or | `\|` |
 | because | `bc` or `because` |
 | therefore | `so` |
 | includes | `includes` |
@@ -69,9 +69,13 @@ CONDITIONAL:
 > 1 ann admin
 > 2 bob user

+## Chain-of-Density Final Pass (B4)
+
+Source: arXiv:2309.04269. After all compression passes, run 1-3 rewrite iterations at FIXED length: each pass fuses 1-3 missing entities from the original back in WITHOUT growing the text (~3 iterations reach human-preferred density). Use to repair entity loss found by verification instead of re-inflating.
+
 ## Guardrails (MANDATORY)

-These CAP the aggression. Sources: Anthropic context-engineering blog; Anthropic high-reasoning model 4.8 prompting guide; arXiv:2502.15007 LLM-Microscope.
+These CAP the aggression. Sources: Anthropic context-engineering blog; Anthropic high-reasoning model 4.8 prompting guide; arXiv:2502.15007 LLM-Microscope. Dotless IDs C1-C4 are max-mode guardrails — distinct from Codex-behavior rules C.1-C.8 (dotted).

 | ID | Rule |
 |----|------|
@@ -89,19 +93,22 @@ Inherits ALL `deep-compression.md` iron rules:

 Max adds:
 - Scope qualifiers preserved verbatim (C2)
- 2 mandatory verification rounds (never optional)
+- 2 mandatory verification rounds, independent methods: claim inventory + self-QA probe (never optional)
 - Semantic match must be >= 95% -> else warn user with loss list
+- 100% sub-gate: numbers, names, negations, scope qualifiers

-## Verification (2 rounds, mandatory)
+## Verification (2 rounds, mandatory, INDEPENDENT methods)

-Never silently ship lossy max output.
+Never silently ship lossy max output. Two rounds use DIFFERENT methods — they catch different losses.

-| Round | Action |
+| Round | Method |
 |-------|--------|
-| 1 | Spawn verifier with ORIGINAL + COMPRESSED -> list lost/distorted facts -> compute semantic match % |
-| 2 | Patch losses -> re-verify -> recompute match % |
-| after R2 | match >= 95% -> ship. match < 95% -> output WARNING + full loss list, ship with caveat |
+| 1 — Claim inventory | Decompose ORIGINAL into numbered atomic claims, ONE predicate per claim (over-decomposition hurts verifier accuracy, arXiv:2411.02400). Check each claim derivable from COMPRESSED. Label: kept \| merged \| lost \| distorted \| elided-known (A.4). Match % = (kept + merged) / total |
+| 2 — Self-QA probe | Generate 10-20 questions from ORIGINAL targeting entities, numbers, conditions, negations. Answer each from COMPRESSED ONLY. Mismatch = loss. Patch, recompute both scores |
+| Gates | Overall >= 95% AND 100% sub-gate: every number, name, negation, and scope qualifier answerable/verbatim (CompactPrompt arXiv:2510.18043). Sub-gate fail -> patch via Chain-of-Density pass (B4) -> re-verify. Still failing -> WARNING + full loss list, ship with caveat |

-Loss list fmt (1 fact/line, atomic):
+Dedup audit: dedup-merged facts count as PRESERVED (kept once). Loss list fmt (1 fact/line, atomic):
 > lost: artifact retention policy (30d) dropped
 > distorted: "every endpoint" -> "endpoints" (scope weakened, C2 violation)
+> merged: TLS-required rule deduplicated, kept once @ Security section (NOT a loss)
+> elided-known: generic "write unit tests" advice elided (A.4, counts as loss)
@@ -1,6 +1,6 @@
 # LLM Text Optimization and Comprehension Rules

-Categorized rules for LLM token efficiency and comprehension optimization with 42 rules across 6 categories.
+Categorized rules for LLM token efficiency and comprehension optimization with 52 rules across 8 categories.
 Apply by category. Reference specific IDs in reviews (e.g., "violates T.1").

 ## C - Codex Behavior
@@ -13,21 +13,21 @@ Apply by category. Reference specific IDs in reviews (e.g., "violates T.1").
 | C.4 | Match Prompt Style to Output | Formatting in prompt influences response. Less markdown in prompt → less markdown in output |
 | C.5 | Descriptive Over Emphatic Instructions | high-reasoning model 4.5/4.6 overtrigger with aggressive language. "Use this tool when..." not "CRITICAL: You MUST..." |
 | C.6 | Overengineering Prevention | high-reasoning model 4.5 tends to overengineer. Add explicit constraints about minimal complexity |
-| C.7 | Avoid ALL-CAPS Emphasis in current Codex models | current Codex models is more responsive to system prompts than previous versions. Aggressive capitalization ("CRITICAL:", "MUST", "NEVER") causes the model to overapply the rule. Use normal-toned instructions instead. Source: Anthropic Codex best practices |
+| C.7 | Avoid ALL-CAPS Emphasis in current Codex models | current Codex models is more responsive to system prompts than previous versions. Aggressive capitalization ("CRITICAL:", "MUST", "NEVER") causes the model to overapply the rule. Use normal-toned instructions instead. Source: Anthropic Codex best practices. When compressing, also DOWNGRADE existing emphasis inflation (ALL-CAPS, repeated boosters) to normal tone — do not preserve it. Max one emphasis marker per constraint |
 | C.8 | Prompt Format Influences Output Format | If your prompt is written in prose, Codex responds in prose. If your prompt uses dense markdown, Codex uses dense markdown. Write the format you want to receive. Source: Anthropic Codex best practices |

 ## T - Token Efficiency

 | ID | Rule | Notes |
 |----|------|-------|
-| T.1 | Tables over Prose | Multi-column data is more token-efficient in tables. Single-column → use bullets instead. Exception: Markdown table syntax (`| col |`, alignment rows) costs ~2x tokens of the same data as minified JSON. For dense tabular data embedded in prompts, prefer minified JSON over Markdown tables |
+| T.1 | Tables over Prose | Multi-column data is more token-efficient in tables. Single-column → use bullets instead. Exception: Markdown table syntax (`\| col \|`, alignment rows) costs ~2x tokens of the same data as minified JSON. For dense tabular data embedded in prompts, prefer minified JSON over Markdown tables |
 | T.2 | Bullets over Numbered | `-` (1 char) vs `1. ` (3 chars). ~5-10% savings. Keep numbers when order matters |
 | T.3 | One-liners for Rules | `❌ bad → good` is self-documenting. Complex rules still need explanation |
 | T.4 | Inline Code over Blocks | Code blocks add markers + newlines. Inline `code` for <3 lines. Multi-line needs blocks for readability |
 | T.5 | Standard Abbreviations | Tables/technical contexts only. Allowed: impl, cfg, args, ret, env, prod, dev, repo, docs. Anti-pattern: Do NOT abbreviate domain terms, variable names, or constraint language in instructions. Abbreviations not defined in a DICT header risk being misread — unmarked abbreviations get missed; defining/marking them in a DICT mitigates (arXiv:2410.23866, abbreviation expansion) because the model otherwise resolves to the statistically dominant meaning of the abbreviation |
-| T.6 | Remove Filler Words | Cut: "please note", "it's important", "as mentioned", "basically" |
+| T.6 | Remove Filler Words | Cut: "please note", "it's important", "as mentioned", "basically". Also delete anti-laziness boosters written for older models ("be thorough", "do not be lazy", "make sure you always") — Codex.5+ overtriggers on them |
 | T.7 | Comma-separated Inline Lists | `a, b, c` instead of bullet list when items are short, order irrelevant. Use for 3-7 short items |
-| T.8 | Arrows for Flow Notation | `A → B → C` instead of prose descriptions of sequences. Dense, scannable. Measured fact: ASCII digraphs `-> != >= <= |` = 1 token each; unicode glyphs `∵ ∴ ⊃ ≤ ≥` = 2-3 tokens each (measured tiktoken cl100k/o200k). Prefer ASCII digraphs over unicode glyphs. `→` is 1 token but `->` is equally cheap and portable. The token win comes from deleting words, not the glyph |
+| T.8 | Arrows for Flow Notation | `A → B → C` instead of prose descriptions of sequences. Dense, scannable. Measured fact: ASCII digraphs `-> != >= <= \|` = 1 token each; unicode glyphs `∵ ∴ ⊃ ≤ ≥` = 2-3 tokens each (measured tiktoken cl100k/o200k). Prefer ASCII digraphs over unicode glyphs. `→` is 1 token but `->` is equally cheap and portable. The token win comes from deleting words, not the glyph |
 | T.10 | Strip Whitespace from Code in Prompts | Code in prompts (C/Java/C#): strip whitespace and indentation before embedding. arXiv:2508.13666 shows 11-22% fewer input tokens (Java: 18.7%, C++: 13.4%, C#: 11.7%) with <1.6% quality impact on Codex and GPT-4o. Python excluded — whitespace is syntactically required. Not for Gemini — significant degradation |

 ## S - Structure
@@ -36,13 +36,26 @@ Apply by category. Reference specific IDs in reviews (e.g., "violates T.1").
 |----|------|-------|
 | S.1 | XML Tags for Sections | `<rules>...</rules>`, `<examples>...</examples>`. Clear parsing boundaries. Injection safety: XML tags are the only reliable way to prevent `{{VARIABLE}}` template substitution content from being confused with instructions. Without XML tag boundaries, injected user content can look like instructions to the model |
 | S.2 | Imperative Form | "Do X" not "You should do X". Removes 2nd person pronouns |
-| S.3 | Single Source of Truth | Merge duplicate content. Repetition wastes tokens, causes contradictions. Strategic 2x max OK |
+| S.3 | Single Source of Truth | Merge duplicate content. Repetition wastes tokens, causes contradictions. Strategic 2x max OK. Details: D.1-D.6 |
 | S.4 | Add Context/Motivation | Providing context helps Codex understand goals. "Text-to-speech will read this, so avoid ellipses" |
 | S.5 | Blockquotes for Critical | Use `>` for warnings, critical notes. Visual hierarchy in markdown |
 | S.6 | Progressive Disclosure | Show minimum needed, reference details elsewhere. SKILL.md <500 lines |
 | S.7 | Consistent Terminology | One term per concept. Avoid synonyms ("config file" vs "configuration document") |
 | S.8 | One-Level Reference Depth | All refs link directly from main file. No chaining main→advanced→details |

+## D - Deduplication
+
+Smart dedup: merge accidental repetition, keep intentional emphasis capped at 2 per document. Dedup-merged facts count as PRESERVED in verification (fact kept once), never as loss. Deep/max: record each merge in a dedup ledger (kept <- dropped) to feed verification.
+
+| ID | Rule | Notes |
+|----|------|-------|
+| D.1 | Exact-Duplicate Merge | Identical sentences/rows/rules after whitespace+case normalization -> keep first occurrence, delete rest. All modes |
+| D.2 | Near-Duplicate Merge | Same fact reworded -> merge into ONE statement, keeping the MORE SPECIFIC variant (numbers, names, qualifiers beat vaguer phrasing) at its best position (S.7 one term per concept). Source: LLMLingua-2 arXiv:2403.12968 |
+| D.3 | Cross-Format Duplicate | Same fact in prose AND table/list -> keep the denser form once, drop the other |
+| D.4 | Emphasis Cap (max 2 per document) | Intentional repetition of a critical constraint: exactly 2x — full form early + <=1-line echo at END (sandwich, L.1/L.6), never middle. 3+ occurrences -> collapse to 2. Never zero a deliberately repeated critical constraint — cap, don't delete. Sources: arXiv:2512.14982 (x2 wins 47/70 tasks, 0 losses); arXiv:2507.11538 (repetition spends instruction budget) |
+| D.5 | Cross-File Dedup (multi-file runs) | Same rule in several files -> keep ONE canonical location (most-specific version / topical owner), replace others with a pointer + inline 1-line summary (bare pointer costs a context hop). Respect S.8 one-level depth |
+| D.6 | Wrong-Merge Guard | Before merging near-dups verify they state the SAME fact. Different scope qualifiers, numbers, versions, or conditions = different facts — keep both. Guards against silent contradiction/loss from over-eager dedup |
+
 ## R - Reference Integrity

 | ID | Rule | Notes |
@@ -58,7 +71,7 @@ Apply by category. Reference specific IDs in reviews (e.g., "violates T.1").
 | P.1 | Examples Near Rules | Place inline, not in appendix. Proximity improves pattern recognition |
 | P.2 | Hierarchy via Headers | Max 3-4 levels deep. Structured documents improve retrieval |
 | P.3 | Bold for Keywords | High-signal definitions only. Max 2-3 per 100 lines. Prefer XML tags or headers |
-| P.4 | Standard Symbols | → (flow), + (and), / (or). Dense formats only (tables, compact lists), NOT in prose. Prefer ASCII operators (-> != >= |) over unicode glyphs on token grounds |
+| P.4 | Standard Symbols | → (flow), + (and), / (or). Dense formats only (tables, compact lists), NOT in prose. Prefer ASCII operators (`-> != >= \|`) over unicode glyphs on token grounds |
 | P.5 | Instruction Order (Anchoring) | Place critical constraints BEFORE options/examples. First-position = strongest anchoring |
 | P.6 | Default Over Options | Recommend ONE default, mention exceptions only. Too many options cause decision paralysis |

@@ -77,6 +90,24 @@ How content is perceived and processed by the LLM — not about token count but
 | L.7 | Prompt Repetition for Non-Reasoning Models | Repeat the entire prompt once. Google Research (arXiv:2512.14982): wins 47/70 benchmark-model combinations with 0 losses. Extreme case: 21% to 97% accuracy. Causal LMs benefit because the second pass has full first-pass context. Only for non-reasoning models — reasoning models already repeat internally |
 | L.8 | Preserve Scope Qualifiers | high-reasoning model 4.8 follows instructions literally and does not silently generalize. Scope words ("every section, not just the first", "all files", "each") are load-bearing — never strip them during compression. Source: Anthropic high-reasoning model 4.8 prompting |

+## A - Aggressive Lossy (deep/max only)
+
+Deliberate-loss techniques, applied ONLY in deep and max modes. A.1/A.3 outputs count as PRESERVED (kept/merged) in verification. A.2 is word-level and gate-neutral: drops are recorded in the loss ledger (dropped -> reason) for transparency but do NOT move the fact-level (kept + merged)/total ratio; if an A.2 drop degrades a fact's meaning, the verifier labels that fact `distorted` (normal gate impact). A.4 elisions consume the fact-level loss budget as `elided-known` and MUST appear in the loss ledger. D.6 wrong-merge guard and L.8 scope qualifiers always win over A rules.
+
+| ID | Rule | Notes |
+|----|------|-------|
+| A.1 | Line Fusion | Merge related short lines/bullets/sentences into ONE line with `\|` separators or comma lists; fuse a rule + its reason via `bc`. Fusion is loss-free: fused facts count as preserved |
+| A.2 | Low-Value Word Drop | Drop words whose removal minimally degrades meaning: decorative adjectives/adverbs, politeness, meta-commentary, self-evident qualifiers. Never drop negations, numbers, named entities, scope qualifiers (L.8, C2 still win) |
+| A.3 | Aggressive Paraphrase | Rewrite whole phrases/sentences into shorter equivalents: restructure, not just delete. Meaning-preserving paraphrase counts as preserved in verification |
+| A.4 | Common-Knowledge Elision | Delete statements any modern LLM already knows from training (generic best practices like "write tests", "keep functions small", standard tool behavior, textbook definitions). Keep ONLY project-specific deltas: concrete names, numbers, paths, versions, prohibitions, deviations from defaults. Every elision -> loss ledger, counts against mode loss budget. Unsure whether generic -> keep |
+
+Examples (before -> after):
+
+- A.1: "Close the DB connection after use. Unclosed connections exhaust the pool." -> "close DB conn after use bc unclosed -> pool exhaustion"
+- A.2: "Carefully review the extremely important production configuration file" -> "review prod cfg file"
+- A.3: "In the event that the build process does not complete successfully, notify the team" -> "build fails -> notify team"
+- A.4: "Write unit tests for new code, tests catch regressions. Coverage gate is 85% (jacoco); build fails below." -> "coverage gate 85% (jacoco), build fails below" (generic "write tests" elided -> ledger; project delta kept)
+
 ## Rules NOT Recommended

 | Avoid | Reality |
@@ -89,6 +120,8 @@ How content is perceived and processed by the LLM — not about token count but
 | Overload single prompts | Multiple tasks in one prompt divide attention → hallucination |
 | Over-focus on wording | Structure and format matter more than specific word choice |
 | Strip all function words / punctuation | Punctuation is load-bearing for context memory (arXiv:2502.15007 LLM-Microscope); ~20% deletion is the safe ceiling — substitute, don't bulk-delete |
+| Blind merge of similar-looking facts | Different scope/numbers/conditions = different facts (D.6) |
+| Delete every repeated constraint | Sandwich repetition (2x) raises compliance (L.1/L.6); cap at 2 (D.4), don't zero |

 ## Compression Ratios (Token Efficiency)

@@ -107,8 +140,9 @@ These ratios reflect token savings from applying T and S category rules. L categ
 |------|-----------|--------|
 | Standard | `references/standard-compression.md` | 30-50% compression, human-readable. Filler removal, paragraph→bullets, prose→tables |
 | Deep | `references/deep-compression.md` | 2-3x compression, LLM-only. DICT header, symbol substitutions, abbreviation dictionary |
+| Max | `references/max-compression.md` | 3-4x, LLM-only, opt-in. Atomic fact-lines, ASCII operators, Chain-of-Density pass, 2 mandatory verify rounds |

-Standard/deep modes apply ALL rules above (C + T + S + R + P) plus their respective compression reference.
+Standard/deep/max modes apply ALL rules above (C + T + S + D + R + P + L) plus their compression reference. Deep/max additionally apply A.1-A.4 (aggressive lossy). All modes run the Deduplication pass (D.1-D.6) during analysis, before compression.

 ## Sources

@@ -126,3 +160,10 @@ Standard/deep modes apply ALL rules above (C + T + S + R + P) plus their respect
 - [LLM-Microscope / Punctuation (arXiv:2502.15007)](https://arxiv.org/abs/2502.15007)
 - [Whitespace Stripping (arXiv:2508.13666)](https://arxiv.org/abs/2508.13666)
 - [Brex Prompt Engineering Guide](https://github.com/brexhq/prompt-engineering)
+- [LLMLingua-2 (arXiv:2403.12968)](https://arxiv.org/abs/2403.12968)
+- [Instruction-Budget Degradation (arXiv:2507.11538)](https://arxiv.org/abs/2507.11538)
+- [Sentence-Level Pruning (arXiv:2410.12388)](https://arxiv.org/abs/2410.12388)
+- [Chain of Density (arXiv:2309.04269)](https://arxiv.org/abs/2309.04269)
+- [CompactPrompt (arXiv:2510.18043)](https://arxiv.org/abs/2510.18043)
+- [Claim-Decomposition Caution (arXiv:2411.02400)](https://arxiv.org/abs/2411.02400)
+- [Entity Loss in Compression (arXiv:2503.19114)](https://arxiv.org/abs/2503.19114)
@@ -32,6 +32,9 @@ Apply filler removal from `rules-review.md` rule T.6 as baseline. Standard mode
 - Remove redundant section headers
 - Combine related short sections
 - Order by importance + put bulk reference content first, instructions/query last (measured up to +30% response quality on long inputs, Anthropic; +21.4% LongLLMLingua). Reorder — never delete — to fix lost-in-the-middle.
+- Dedup pass first (D.1-D.4, D.6, rules-review.md): merge accidental repeats before any wording work; cap intentional emphasis at 2 (full early + short echo at end)
+- Sentence-level zero-loss pruning: rank sentences — does removal lose any unique atomic fact? Drop zero-loss sentences BEFORE token-level compression (15-20 pts better fidelity at same ratio, arXiv:2410.12388)
+- Structure-aware: compress within structural units, never across; keep headers, compress bodies (heading structure aids retrieval)

 ## 4. Abbreviation Rules (Conservative)

@@ -56,6 +59,8 @@ After compression, verify:
 - [ ] No information merged incorrectly (two different concepts collapsed into one)
 - [ ] Headers and structure still logical
 - [ ] Terminology kept consistent — same concept uses the SAME term throughout (no paraphrase-for-variety; synonym variation hurts LLM retrieval)
+- [ ] Fact-inventory gate: extract atomic facts from original, check each in compressed; (kept + dedup-merged) / total >= 98% — patch any slip, one round
+- [ ] Dedup-merged facts counted as preserved, not lost; no two DIFFERENT facts merged into one (D.6)

 ## 6. What NOT to Compress

@@ -47,13 +47,14 @@ echo "[Structure]"

 check_file_exists "$SKILL_DIR/SKILL.md" "SKILL.md exists"

-for section in "Modes" "Smart Auto-Detection" "Deep Mode Pipeline" "Standard Mode Pipeline" "Iron Rules"; do
+for section in "Modes" "Smart Auto-Detection" "Deep Mode Pipeline" "Standard Mode Pipeline" "Max Mode Pipeline" "Deduplication Pass" "Loss Budget" "Iron Rules"; do
  check_contains "$SKILL_DIR/SKILL.md" "$section" "SKILL.md contains '$section' section"
 done

 check_file_exists "$SKILL_DIR/references/rules-review.md" "Reference: rules-review.md exists"
 check_file_exists "$SKILL_DIR/references/deep-compression.md" "Reference: deep-compression.md exists"
 check_file_exists "$SKILL_DIR/references/standard-compression.md" "Reference: standard-compression.md exists"
+check_file_exists "$SKILL_DIR/references/max-compression.md" "Reference: max-compression.md exists"

 AGENT_DIR="$(cd "$SKILL_DIR/../../agents" && pwd)"
 AGENT_FILE="$AGENT_DIR/text-optimizer.md"
@@ -69,7 +70,7 @@ echo ""

 echo "[Content]"

-for flag in "\-l" "\-s" "\-d"; do
+for flag in "\-l" "\-s" "\-d" "\-x"; do
  check_contains "$SKILL_DIR/SKILL.md" "$flag" "SKILL.md contains mode flag '$flag'"
 done

@@ -82,6 +83,7 @@ check_contains "$SKILL_DIR/references/standard-compression.md" "Verification Che

 check_contains "$AGENT_DIR/text-optimizer.md" "standard-compression.md" "text-optimizer.md references standard-compression.md"
 check_contains "$AGENT_DIR/text-optimizer.md" "deep-compression.md" "text-optimizer.md references deep-compression.md"
+check_contains "$AGENT_DIR/text-optimizer.md" "max-compression.md" "text-optimizer.md references max-compression.md"

 check_contains "$SKILL_DIR/references/rules-review.md" "Compression References" "rules-review.md contains Compression References section"

@@ -99,10 +101,10 @@ else
 fi

 # Check that SKILL.md references L category
-if grep -q "L\.1-L\.7" "$SKILL_DIR/SKILL.md"; then
-  pass "SKILL.md references L.1-L.7 category"
+if grep -q "L\.1-L\.8" "$SKILL_DIR/SKILL.md"; then
+  pass "SKILL.md references L.1-L.8 category"
 else
-  fail "SKILL.md missing L.1-L.7 (LLM Comprehension) category"
+  fail "SKILL.md missing L.1-L.8 (LLM Comprehension) category"
 fi

 # Check that SKILL.md references T.10
@@ -112,6 +114,24 @@ else
  fail "SKILL.md missing T.10 (strip whitespace) rule"
 fi

+# Check D category present everywhere
+if grep -q "D\.1-D\.6" "$SKILL_DIR/SKILL.md"; then
+  pass "SKILL.md references D.1-D.6 (Deduplication) category"
+else
+  fail "SKILL.md missing D.1-D.6 (Deduplication) category"
+fi
+
+check_contains "$SKILL_DIR/references/rules-review.md" "## D - Deduplication" "rules-review.md contains D - Deduplication section"
+check_contains "$SKILL_DIR/references/rules-review.md" "52 rules" "rules-review.md declares 52 rules"
+check_contains "$SKILL_DIR/references/rules-review.md" "Wrong-Merge Guard" "rules-review.md contains D.6 Wrong-Merge Guard"
+check_contains "$SKILL_DIR/references/rules-review.md" "## A - Aggressive Lossy" "rules-review.md contains A - Aggressive Lossy section"
+check_contains "$SKILL_DIR/SKILL.md" "A\.1-A\.4" "SKILL.md references A.1-A.4 (aggressive lossy) range"
+check_contains "$SKILL_DIR/references/deep-compression.md" "Redundancy Factoring" "deep-compression.md contains Redundancy Factoring section"
+check_contains "$SKILL_DIR/references/max-compression.md" "Self-QA probe" "max-compression.md contains Self-QA probe round"
+check_contains "$SKILL_DIR/references/max-compression.md" "merged:" "max-compression.md loss list supports merged label"
+check_contains "$SKILL_DIR/SKILL.md" "Loss Budget" "SKILL.md contains Loss Budget section"
+check_contains "$AGENT_DIR/text-optimizer.md" "Dedup Pass" "Agent contains Dedup Pass step"
+
 # Check agent references Sources not Summary
 if grep -q '## Sources' "$AGENT_FILE" && ! grep -q '## Summary' "$AGENT_FILE"; then
  pass "Agent verifies '## Sources' (not '## Summary')"
@@ -1,5 +1,7 @@
 <!-- think-short -->
 Be terse. Lead with results. Use ASCII unless the requested artifact requires other text.
+Think short: keep internal reasoning minimal and do not narrate exploration.
 Search before opening large files. Prefer focused edits and parallel read-only checks.
 Plan the complete edit set, then execute it. Reuse existing code before adding new abstractions.
+After writing code, make one pass for simplification: if it can be simpler, simplify it.
 Keep comments only for non-obvious decisions and public contracts.