pi-dev-team 0.2.0

package/knowledge/report-template.md

@@ -0,0 +1,114 @@
+# Report Template
+
+Shared header/footer/empty-section contract for dev-team's ~15
+report-writing skills (`test-health`, `cd-test-architecture`,
+`competitive-analysis`, `docker-image-audit`, `test-improve`,
+`harness-audit`, `session-review`, `explore`, `test-design`,
+`frontend-architecture`, `agent-eval`, and others) to adopt over time.
+Generalized from `test-improve`'s Phase 9 template
+(`skills/test-improve/templates/executive-summary.md`), the most complete
+existing example in the plugin — same role as `knowledge/review-template.md`
+plays for code-review agents, but for standalone reports rather than the
+review aggregation step.
+
+**Adoption status**: only `test-health`, `cd-test-architecture`, and
+`competitive-analysis` have migrated onto this contract so far. Every other
+skill named above — including `docker-image-audit`, which still uses its own
+unrelated local template at `skills/docker-image-audit/references/report-template.md`
+(same filename, different, non-conforming structure), and `test-improve`,
+which keeps its own local `skills/test-improve/templates/executive-summary.md`
+body — has **not** adopted this contract yet; being named above is a
+statement of intended scope, not current compliance.
+
+**Scope**: this file defines the shared header, closing Provenance section,
+and empty-section rule only. Skill-specific body content — findings tables,
+per-skill scoring, detail sections — stays local to each skill's own Output
+section. A skill's Output section references this file for the shared parts
+instead of inlining its own; see the Reference sentence below.
+
+## Reference sentence
+
+Every report-writing skill that adopts this contract points at it with this
+exact sentence, so the reference reads identically across skills instead of
+being reworded per skill:
+
+> For the header block and closing Provenance section, follow
+> `knowledge/report-template.md`; the sections below are this skill's own
+> body.
+
+## Header block
+
+Every report opens with:
+
+```markdown
+# <Report Title> — <target> (<date>)
+
+**Date**: <ISO 8601>
+**Target**: <repo / image / component / scope of comparison>
+**Tool versions**: <relevant tool versions, e.g. coverage tool, mutation tool — omit fields with no applicable tool>
+**Scope**: <what was analyzed — full repo, --path <dir>, single component, etc.>
+```
+
+Skills with an existing single-line summary convention (e.g. `## Test Health
+— <repo> (<date>)`, `**Shape**: ... **Fit**: ...`) keep that line as their
+own body content — it is not replaced by this header block, only preceded
+by it.
+
+## Empty-section rule
+
+Scope: **header/footer fields only** — the fields in the Header block above
+and the Provenance section below. A header/footer field with no value
+renders `_Not applicable — <reason>._` rather than being silently omitted
+(e.g. `**Tool versions**: _Not applicable — no coverage tool detected._`).
+
+This rule does not govern skill-specific body content. A skill's own
+body-level empty-value conventions are unaffected and are not required to
+follow this rule — for example, `test-health`'s Farley Score row uses its
+own convention (verbatim scope-labelled value, or the literal `no in-scope
+test files`) rather than the generic `_Not applicable_` phrasing.
+
+## Default section ordering
+
+For a **new** report-writing skill with no established structure of its own,
+default to this ordering:
+
+1. Header block
+2. Executive Summary
+3. Findings / Detail (skill-specific)
+4. Next Actions
+5. Provenance (closing section, below)
+
+This ordering is **illustrative guidance for new skills only**. It is not
+grounds to rename an existing report-writing skill's established section
+headings (e.g. `cd-test-architecture`'s `### Next steps`, `competitive-
+analysis`'s `## Next Steps`) to match this ordering's example names when
+migrating that skill onto this shared contract — a migrated skill's body
+stays exactly as it already is.
+
+## Provenance (closing section)
+
+Every report closes with a Provenance section, generalized from
+`test-improve`'s Phase 9 §10:
+
+```markdown
+## Provenance
+
+- Repository: `<repo path>`
+- Branch / SHA: `<branch>` / `<sha>`
+- Run parameters: `<flags, scope, or other invocation parameters>`
+- `dev-team` plugin version: `<plugin_version>`
+```
+
+Omit fields that don't apply to a given skill (e.g. a skill with no
+run-scoping flags), applying the empty-section rule above rather than
+deleting the field.
+
+## Related
+
+- `knowledge/review-template.md` — the equivalent shared contract for
+  code-review agents' aggregation step.
+- `knowledge/report-to-pdf.md` — rendering any report produced under this
+  contract to PDF.
+- `skills/test-improve/templates/executive-summary.md` — the precedent this
+  contract generalizes from; `test-improve` keeps its own local template body
+  unchanged and is not required to migrate onto this file.

package/knowledge/report-to-pdf.md

@@ -0,0 +1,69 @@
+# Rendering a report to PDF
+
+**Prefer the built-in command.** `/report-pdf <path.md> [--out <path>]` renders
+any dev-team Markdown report (`.dev-team-reports/*.md` or `reports/*.md`) to a
+styled PDF, and the `--pdf` flag on `/code-review`, `/test-health`,
+`/cd-test-architecture`, `/triage`, and `/harness-audit` renders the report
+that run just wrote. Both share `hooks/lib/report_pdf.py`, which bundles the
+print stylesheet (`knowledge/report-print.css`), detects an engine with
+graceful fallback, and skips with an install hint when none is present — see
+[`report-pdf-integration.md`](report-pdf-integration.md). The recipe below is
+the underlying mechanism, kept for reference and manual use.
+
+A copy-pasteable recipe for turning any markdown report produced under
+`knowledge/report-template.md`'s contract into a shareable PDF, without
+assuming a LaTeX engine (`pdflatex`, `xelatex`) or a headless-rendering
+package (`wkhtmltopdf`, `weasyprint`) is installed. Requires only:
+
+- `pandoc` (`brew install pandoc` on macOS, `apt-get install pandoc` on
+  Debian/Ubuntu)
+- A Chrome or Chromium install (already present on most developer machines)
+
+This is an on-request recipe, not automation — no hook runs it
+automatically on every report write.
+
+**Security note.** `report_pdf.py` hardens this recipe for report content that
+may embed snippets from a repo under review: it runs pandoc with `--sandbox`
+(no build-time resource fetches — blocks SSRF via a remote URL in the content),
+injects the stylesheet in Python rather than via `--css` (sandbox blocks that
+read), and invokes headless Chrome with `--disable-javascript`. The manual
+recipe below omits these; use the command for untrusted content.
+
+## Recipe
+
+```bash
+# 1. Markdown -> standalone HTML (self-contained: styling inlined, no external assets)
+pandoc report.md -o report.html --standalone --embed-resources --metadata title="Report"
+
+# 2. Standalone HTML -> PDF via headless Chrome's native print-to-pdf
+#    macOS:
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --headless --disable-gpu --no-pdf-header-footer \
+  --print-to-pdf="report.pdf" "$(pwd)/report.html"
+
+#    Linux (path varies by distro/package: google-chrome, google-chrome-stable, chromium, chromium-browser):
+google-chrome --headless --disable-gpu --no-pdf-header-footer \
+  --print-to-pdf="report.pdf" "$(pwd)/report.html"
+```
+
+`report.pdf` is written to the current directory.
+
+## Why this toolchain
+
+- **No LaTeX assumption.** `pdflatex`/`xelatex` are not installed by default
+  on most developer machines and are a heavy dependency to add just for
+  occasional PDF export; `wkhtmltopdf`/`weasyprint` have their own native
+  dependency chains (Qt WebKit, Cairo/Pango) that are equally not guaranteed
+  present.
+- **Chrome and pandoc are already common.** Both are already installed on
+  most developer machines for unrelated reasons, so this recipe typically
+  requires zero new installs.
+- **`--embed-resources`** (pandoc ≥ 3.0; use `--self-contained` on older
+  pandoc) inlines any CSS/images into the HTML so the print-to-pdf step has
+  no external asset dependency, keeping the recipe reproducible from the
+  markdown file alone.
+
+## Related
+
+- `knowledge/report-template.md` — the shared header/footer/empty-section
+  contract most reports rendered with this recipe will already follow.

package/knowledge/request-processing-flow.md

@@ -0,0 +1,63 @@
+<!-- Extracted from CLAUDE.md — do not duplicate here -->
+
+This file contains the orchestration workflow details extracted from CLAUDE.md to keep the main config file lean.
+
+## Request Processing Flow
+
+For trivial tasks (typo fix, simple query), the Orchestrator routes directly to a single agent. For non-trivial tasks, the Orchestrator follows the **Research → Plan → Implement** workflow:
+
+### Three-Phase Workflow
+
+1. **Research** — Understand the system: find relevant files, trace data flows, identify the problem surface area. Sub-agents explore the codebase and return concise findings to keep the parent context clean. For non-trivial features, produce a **design document** at `docs/specs/` with problem statement, approach, alternatives, and scope boundaries. Optionally run **Design Interrogation** to stress-test the design and surface unresolved decisions before planning. For module boundaries, use **Design It Twice** to generate parallel alternative interfaces via sub-agents. Output: research progress file + design doc written to `.claude/memory/`.
+2. **Human Review Gate** — Human reviews research findings and design doc. Catching a misunderstanding here prevents hundreds of bad lines of code.
+3. **Plan** — Decompose the feature into **vertical slices**, author each slice's **Gherkin scenarios** (the behavioral contract), then specify every change: files, snippets, TDD steps, verification. Before the human sees the plan, **plan review personas** run in parallel as critical outside reviewers — the reviewer set scales to plan tier; see the plan skill's [Run plan review personas step](../skills/plan/SKILL.md#5-run-plan-review-personas) for the tier classification (that table is the single source of truth — do not re-duplicate the reviewer set here, it drifts). See `${CLAUDE_PLUGIN_ROOT}/knowledge/three-phase-workflow.md#phase-2-plan` for how an unresolved `needs-revision` verdict is handled before the human gate — that statement is the single source of truth, not restated here. The plan is the primary review artifact — 200 lines of plan is far more reviewable than 2,000 lines of code. After approval, optionally run `/issues-from-plan` to create GitHub issues for team distribution. Output: implementation plan progress file written to `.claude/memory/`.
+4. **Human Review Gate** — Human reviews the plan. This replaces traditional line-by-line code review as the primary quality gate.
+5. **Implement** — Execute the plan by dispatching the `software-engineer` agent (by `subagent_type`) for each step. All code is built in **small per-behavior batches** with **vertical slices** — **Code-First Small Batches** (IMPLEMENT → TEST → REFACTOR), the sole build cadence, refactoring on every green (`docs/experiments/RECOMMENDATIONS.md`). The build runs **wave by wave** (the plan's `## Parallelization` schedule): independent slices in a wave build concurrently in **worktree isolation** (`isolation: "worktree"`), then a barrier reconciles the wave and gates on the full suite before the next wave. Worktree isolation requires Claude Code's `worktree.baseRef` setting to be `"head"` — set it in `.claude/settings.json` or `~/.claude/settings.json` (plugin- and project-local-scope settings are not honored for this key per issue #553's Slice 0 spike; full evidence: `docs/spikes/worktree-baseref-head-spike.md`). Effective concurrency is `min(--jobs, DEV_TEAM_MAX_PARALLEL_BUILDS, wave width)` — parallel fan-out is opt-in: when neither `--jobs` nor the env var **`DEV_TEAM_MAX_PARALLEL_BUILDS`** is set the default is sequential (effective 1), and you opt into fan-out with `--jobs N` or the env var, each capped by wave width (#1515). A fully-dependent plan degrades to today's one-slice-at-a-time behavior. A **three-stage inline review** runs at a granularity that scales with step complexity — per step for `complex` steps, batched once at the slice boundary for `standard`/`trivial` steps: a deterministic static self-heal pass (scoped static analysis with a capped fix loop, `skills/build/references/static-self-heal.md`) runs to pass-or-cap first, then (1) spec-compliance-review checks code matches spec, (2) quality review agents check code quality, (3) browser verification for UI changes. Each checkpoint's find/fix/no-op outcome is logged to `.claude/metrics/review-value.jsonl` so the overhead is measurable. Actionable issues (error/warning severity with high/medium confidence) are **auto-fixed and re-reviewed** in a loop (up to 5 iterations) — only issues requiring human judgment are escalated. Run `/code-review` before committing (which auto-scopes to uncommitted changes and runs its own fix loop). Then invoke `dev-team:tech-writer` to verify all affected documentation is current. All agents must provide **verification evidence** (fresh test output) before claiming completion. Output: working code + test results + code review pass + docs verified.
+6. **Human Review Gate** — Human reviews the final output. Lightweight if the plan was correct.
+7. **Branch Workflow** — Create PR, choose merge strategy, clean up branch (see Branch Workflow skill).
+8. **Learning loop** — Update configs if needed, log metrics, refine routing.
+
+### Skills by Phase
+
+| Phase | Skills Used | Purpose |
+|-------|-----------|---------|
+| **Research** | Design Doc, Domain Analysis, Domain-Driven Design, Threat Modeling, Design Interrogation, Design It Twice, Competitive Analysis | Understand the system, explore alternatives, stress-test designs |
+| **Plan** | Specs, API Design, Hexagonal Architecture, Legacy Code | Define what to build, specify interfaces and test strategy |
+| **Plan → Team** | `/issues-from-plan` | Break plan into GitHub issues for team distribution |
+| **Implement** | Test-Driven Development (advisory, on request), Systematic Debugging, Mutation Testing, Browser Testing, Performance Benchmark, CI Debugging | Build in small per-behavior batches (Code-First Small Batches), debug issues (reproduce defects with a failing test first), validate quality, measure performance |
+| **Bug Triage** | `/triage` (Systematic Debugging + file-based triage record in `.dev-team-reports/triage/`) | Investigate bugs and write actionable triage records |
+| **Review** | Quality Gate Pipeline, Farley Score | Validate output before delivery |
+| **Cross-phase** | Context Loading Protocol, Context Summarization, Feedback & Learning, Human Oversight Protocol, Performance Metrics, Governance & Compliance, Branch Workflow | Orchestration, context management, learning |
+
+### Phase Transitions
+
+Each phase runs in a fresh context window. The output of each phase is a structured progress file in `.claude/memory/` that onboards the next phase. See the Orchestrator agent for the full protocol.
+
+## Multi-Agent Collaboration Protocol
+
+### Sub-Agents as Context Isolation
+
+The primary value of sub-agents is **context isolation**, not persona specialization. When a parent agent dispatches a sub-agent to explore, search, or analyze, the sub-agent absorbs the context burden of reading files and tracing code flows. Only a concise, structured finding returns to the parent — keeping the parent's context clean and focused on the actual task.
+
+**Design sub-agent calls for minimal context return**:
+
+- Send the sub-agent a specific question ("Where is user authentication handled? Return file paths and line numbers.")
+- The sub-agent reads 20 files; the parent receives 10 lines of structured findings
+- The parent can get right to work without the context burden of exploration
+
+Persona specialization (Software Engineer, Architect, etc.) provides behavioral guardrails and domain expertise, but context isolation is what makes multi-agent workflows scale.
+
+### Multi-Agent Coordination
+
+When a task requires multiple agents:
+
+1. Orchestrator identifies multi-agent task and assigns the three-phase workflow
+2. Load primary agent + sub-agents for the current phase only
+3. Sub-agents explore and return concise findings (context isolation)
+4. Primary agent coordinates (defines interfaces, manages dependencies, resolves conflicts)
+5. Phase output is written to `.claude/memory/` as a progress file
+6. Human reviews before next phase begins
+7. Integration and validation (QA validates, Architect reviews if architectural changes)
+8. Unified result delivery
+
+Referenced from: `plugins/dev-team/CLAUDE.md`

package/knowledge/result-verification.md

@@ -0,0 +1,52 @@
+# Result Verification
+
+Reference file for `test-review`, `test-smell-review`, and the `test-design-advisor` skill. This file covers the **Verify** phase — how a test asserts the outcome — and the patterns that make a failure point straight at its cause. Where `test-doubles.md` chooses the collaborator stand-in, this file chooses the *assertion*.
+
+Source: Gerard Meszaros, *xUnit Test Patterns* (xunitpatterns.com) — Result Verification chapter. Language- and framework-agnostic — described by role, not any assertion library's API.
+
+Core principle: **verify one logical condition per test, and make every assertion say what it expected and why** — so a red test localizes the defect instead of hiding it.
+
+---
+
+## Verification style: state vs behavior
+
+| Style | What it checks | Use when |
+|---|---|---|
+| **State verification** | The SUT's resulting state / return value after exercise | **Default.** The outcome is observable as a value or state |
+| **Behavior verification** | That the SUT *called* a collaborator a certain way | Only at a true side-effect boundary with no observable state (e.g. a message was published) |
+
+Prefer state verification; reach for behavior verification only when there is no state to assert. The *double* that enables behavior verification (spy/mock) is chosen in `test-doubles.md`; here, decide *whether* behavior verification is even the right approach.
+
+---
+
+## Assertion patterns
+
+| Pattern | What it is | Use when | Fixes |
+|---|---|---|---|
+| **Assertion Method** | A single primitive assert on one value, with a message | A single expected value | baseline |
+| **Expected Object** | Build the whole expected object and assert equality in **one** comparison | Asserting many fields of one result | **Assertion Roulette**, field-by-field clutter |
+| **Custom Assertion** | A domain-named assertion encapsulating a comparison **and** an intent-revealing failure message (`assertIsOverdue(account)`) | The same non-trivial comparison recurs, or the default failure message is opaque | duplication + poor diagnostics |
+| **Verification Method** | A named sequence of assertions reused across tests | A multi-assertion check repeats with the same meaning | Test Code Duplication in the Verify phase |
+| **Guard Assertion** | Assert a precondition **before** the main assertion, so a missing precondition fails clearly | The main assertion would otherwise throw a cryptic null/empty error | misleading failures |
+| **Delta Assertion** | Assert the *change* relative to a captured baseline, not an absolute value | Working against a Shared/persistent fixture whose absolute state you don't control | brittle absolute assertions on shared fixtures |
+| **Unfinished Test Assertion** | A deliberate `fail("not yet implemented")` placeholder that keeps a stubbed-out test **red** until it's written | You've named a test condition you intend to cover but haven't implemented it yet | a silently-passing empty test that masquerades as coverage (a Buggy Test) |
+
+---
+
+## Rules
+
+- **One logical condition per test.** Several unrelated assertions in one method is an Eager Test — split it (`test-organization.md` / `test-refactoring.md`).
+- **Locatable intent.** Every assertion carries a message or is self-describing, so a failure names the expectation.
+- **No magic values.** Don't assert against unexplained literals; name the expected value or derive it visibly (avoid hard-coded values whose meaning is lost).
+
+**Decision flow:** single value → Assertion Method with a message → multi-field object → **Expected Object** → repeated/complex domain comparison → **Custom Assertion** / **Verification Method** → precondition that would fail cryptically → **Guard Assertion** → outcome relative to a shared fixture → **Delta Assertion**.
+
+---
+
+## How this connects to the rest of the toolkit
+
+- **`test-smells.md`** — the smells these fix: Assertion Roulette, Obscure Test, Fragile/Overspecified Test, Hard-Coded Values.
+- **`test-doubles.md`** — behavior verification with mocks/spies; choose the double there, decide the verification approach here.
+- **`test-strategy.md`** — Delta Assertion is the verification counterpart of a Shared/persistent Fixture.
+- **`test-organization.md`** — Verify is the third of the Four-Phase Test.
+- **`test-refactoring.md`** — the moves that get an existing test here: Introduce Expected Object, Extract Custom Assertion / Verification Method, Add Guard Assertion, Split Test.

package/knowledge/review-agent-output-contract.md

@@ -0,0 +1,121 @@
+# Review-agent output contract
+
+The JSON shape every read-only `*-review` agent emits. This is the single
+source of truth — agent files cite this instead of inlining the schema, so
+the contract can't drift between the ~20 agents that share it.
+
+## Canonical schema
+
+```json
+{"status": "pass|warn|fail|skip", "issues": [{"category": "", "severity": "error|warning|suggestion", "confidence": "high|medium|none", "file": "", "line": 0, "message": "", "suggestedFix": ""}], "summary": ""}
+```
+
+`category` is optional per finding — omit it rather than emit an empty
+string when a finding genuinely has no natural taxonomy tag.
+
+## `category` (#1639)
+
+A short, stable tag identifying the *kind* of finding within an agent's own
+taxonomy — not a cross-agent enum, and not required to be a strict
+linter-style rule ID. Its purpose is round-to-round finding identity:
+`skills/code-review/scripts/finding_signature.py`'s `signature()` hashes
+`(agent, file, category, normalized-message)`, with the finding's `line`
+compared separately at a `±3` tolerance by `same_finding()` rather than
+folded into the hash. The `category` component of that hash is resolved
+from a fallback chain — `category` → `smell` → `rule` → `ruleId` (#1692) —
+so an agent that spells its taxonomy tag `smell` (`test-smell-review`) gets
+the same round-to-round identity protection as an agent that spells it
+`category`. Message normalization strips quoted spans and numbers
+by design, so two genuinely *different* findings from the same agent, same
+file, and within a few lines of each other can normalize to the same text
+(e.g. two distinct missing-guard-clause defects a couple of lines apart
+whose messages differ only in the quoted identifier that normalization
+strips). Without `category` to tell them apart, those collide into one
+signature, and — because they also fall inside the `±3` proximity window —
+a later round's genuinely new defect matches a prior round's key and reads
+as `carried` rather than new, silently suppressing a fix round the
+loop-until-dry/severity-floor termination rules #1625 added were supposed to
+run.
+
+Each agent defines its own taxonomy in its own body — see each agent's
+`## Detect` (or equivalent) section for its specific category values. Three
+worked examples already shipping on this contract (kept in sync with the
+named agent files by `tests/repo/test_review_agent_output_contract_examples.py`):
+
+- **`security-review`**: `"category": "A<NN>.<slug>"` (the OWASP category the
+  finding maps to), e.g. `"A03.sql-injection"`.
+- **`ai-provenance-review`**: `"category": "verification-debt|regeneration-risk"`.
+- **`spec-compliance-review`**: `"category": "unmet-criterion|uncovered-scenario|scope-violation|plan-deviation"`.
+
+Four more agents converge on the same field name independently: the
+`plan-review-*` critics (`plan-review-design`, `plan-review-parallelization`,
+`plan-review-strategic`, `plan-review-ux`) each emit their own `category`
+values too, on a different `{"verdict", "issues"}` schema dispatched by
+`/plan` rather than this contract's `{"status", "issues"}` shape — not a
+fourth spelling to reconcile, but further evidence the name reads naturally
+across this repo's own review agents.
+
+A new agent that reports findings across more than one natural taxonomy
+bucket should add its own `category` values the same way — a short,
+lower-case, hyphenated tag per bucket, documented in the agent's own body —
+rather than leaving the field unset.
+
+**Not the same `category` as `apply-fixes`'s correction-prompt schema.**
+`skills/apply-fixes/SKILL.md`'s correction-prompt `category` field holds the
+*reporting agent's name* (e.g. `"structure-review"`), grouping fixes for
+display — a different concept that happens to share this field name in a
+downstream artifact generated *from* findings. Do not assume a correction
+prompt's `category` carries a finding's taxonomy tag through unchanged.
+
+## Status values
+
+- **pass**: zero issues
+- **warn**: issues found, none are errors
+- **fail**: at least one error-severity issue
+- **skip**: agent had nothing to review this run — no files in scope (e.g.,
+  no JS/TS files for `js-fp-review`), or excluded by a pre-flight gate.
+  Canonical definition — `output-format.md` and `SKILL.md` cite this rather
+  than restate it.
+
+**Documented per-agent status exception:** `doc-review` and `naming-review`
+escalate a `warning`-severity finding to `fail` as well as `error` — for
+these two, a misleading name or a stale/incomplete doc is high-cost enough
+on its own that it doesn't wait for a second, error-severity finding to
+raise the tier. Every other agent uses the default rule above.
+
+## `severity` values
+
+`error` (must fix), `warning` (should fix), `suggestion` (could improve).
+
+## `confidence` values
+
+| Value | Meaning | `apply-fixes` behavior |
+|-------|---------|----------------------|
+| `high` | Mechanical fix; correct with high certainty | Auto-apply |
+| `medium` | Direction right; tradeoffs possible | Present as suggested diff — require confirmation |
+| `none` | Requires human judgment | Present finding only; do not generate correction prompt |
+
+## Documented per-agent extensions
+
+A handful of agents extend the canonical schema with extra fields specific
+to their domain, beyond the canonical `category` documented above. These are
+intentional, documented exceptions — not drift:
+
+- **`test-smell-review`**: adds `"smell": ""` and
+  `"remedyFamily": "fixture-construction|result-verification|test-organization|test-refactoring|null"`
+  to each issue. `smell` is this agent's own taxonomy tag; `signature()`'s
+  fallback chain is `category` → `smell` → `rule` → `ruleId` (#1692), so its
+  findings hash with `smell` as their taxonomy component instead of an empty
+  segment.
+
+An agent that needs a new field beyond these documents it here rather than
+drifting silently.
+
+## Aggregation
+
+`/code-review` wraps each agent's raw result with `agentName` and
+`modelTier` when assembling the panel-wide report — see
+[`skills/code-review/output-format.md`](../skills/code-review/output-format.md)
+for the aggregated `--json` shape, the per-slice section artifact, and the
+progress-ledger/consolidation formats sliced mode adds on top of this
+per-agent contract.

package/knowledge/review-lens-classification.md

@@ -0,0 +1,113 @@
+# Review Roster: Discovery Lens vs. Verification Gate (#2007)
+
+Two classes of review agent need two different value metrics, and pricing
+both the same way misreads one of them:
+
+- **Discovery lens** — scans an open-ended set of possible defects across a
+  domain (SRP violations, race conditions, N+1 queries, ...). `$/finding` is
+  a meaningful cost signal for this class: a lens that consistently costs a
+  lot per finding is a real tier-down/removal candidate.
+- **Verification gate** — confirms one specific, fixed thing (does the
+  implementation match the spec, does the diff follow the plan). `$/finding`
+  is the **wrong** metric here: a verification gate that mostly passes is a
+  gate doing its job, not evidence of low value (see #2007's own framing —
+  pricing silence as waste is the mirror image of the "gate that cannot
+  fail" failure `CLAUDE.md` warns about). The meaningful measure for this
+  class is **escape rate**: how often something the gate should have caught
+  reached a later stage anyway.
+
+This file is the durable record of that classification, per issue #2007's
+acceptance criterion ("every roster agent classified ... with the
+classification recorded"). The roster itself is
+[`agent-registry.md`](agent-registry.md)'s Review Agents table — this file
+classifies it, it does not duplicate the roster.
+
+**Scope note.** This is a classification, not a routing decision. No entry
+here tiers down, removes, or reweights any agent — see #2007's own scope
+("Coordinate with #1980 and #1982 ... you're building the classification
+and attempting the recomputation, not acting on either yet").
+
+## Classification
+
+| Agent | Class | Rationale |
+| --- | --- | --- |
+| a11y-review | discovery-lens | Scans WCAG/ARIA/keyboard-nav for an open set of possible violations — no single fixed contract to confirm against. |
+| ai-provenance-review | discovery-lens | Surfaces unverified AI-authored assertions and regeneration-risk candidates — an open detection surface. |
+| arch-review | discovery-lens | Scans layer boundaries, dependency direction, and pattern consistency broadly; its ADR-compliance sub-check is verification-flavored, but the majority of its surface is open-ended discovery. |
+| claude-setup-review | discovery-lens | Scans for an open set of CLAUDE.md/rule/path gaps, not one pass/fail check. |
+| component-architecture-review | discovery-lens | Scans for reusable-component extraction, duplication, and prop-drilling — open-ended. |
+| concurrency-review | discovery-lens | Scans for race conditions, async pitfalls, shared state — open-ended. |
+| correctness-review | discovery-lens | Named explicitly as discovery in `skills/code-review/SKILL.md` ("an inverted assertion is exactly its subject"). |
+| data-flow-tracer | discovery-lens (analysis-only) | Surfaces data-flow traces with no pass/fail verdict — `$/finding` needs adapting to "value per trace surfaced," but it is a discovery tool, not a gate. |
+| doc-review | discovery-lens | Scans README/API-doc/ADR drift across an open set of possible staleness. |
+| domain-review | discovery-lens | Scans domain-boundary and abstraction-leak violations — open-ended. |
+| js-fp-review | discovery-lens | Scans array-mutation and impure-pattern violations — open-ended. |
+| mutation-kill | **not applicable** | Explicitly documented in `agent-registry.md` as "Not a reviewer" — an autonomous survivor-reduction loop, not a panel lens. Neither `$/finding` nor escape rate applies; excluded from this classification rather than force-fit. |
+| naming-review | discovery-lens | Scans naming-convention and magic-value violations — open-ended. |
+| performance-review | discovery-lens | Scans resource leaks, N+1 queries, unbounded growth — open-ended. |
+| progress-guardian | verification-gate | Checks plan adherence and commit discipline against one fixed contract (the plan itself) — `docs/team-structure.md` names it "a process gate-keeper, not a code reviewer," not part of the standard review-dispatch fan-out. |
+| quality-reviewer | verification-gate (coordinator caveat) | Coordinates the Inline Review Checkpoint's fix loop to convergence rather than producing its own domain findings — its meaningful measure is "did the checkpoint converge," closer to a gate's pass/fail than a lens's per-finding cost. |
+| refactor-opportunity-review | discovery-lens | Scans for post-GREEN refactoring opportunities — open-ended. |
+| security-review | discovery-lens | Named explicitly as a discovery lens in `skills/code-review/SKILL.md`, and explicitly excluded from the test-only-diff skip candidates precisely because it finds real issues (credentials, injection payloads) across every diff shape. |
+| session-analysis | discovery-lens (analysis-only) | Surfaces ranked improvement suggestions from a session digest — no pass/fail verdict, but an open discovery surface, not a fixed-contract check. |
+| spec-compliance-review | **verification-gate** | The paradigm case named directly in #2007: confirms the implementation matches the spec. A gate that usually passes ("145 of 248 runs are pure pass") is doing its job — `$/finding` prices that silence as waste, which is the wrong metric for this class. |
+| spec-reviewer | verification-gate | Same family as `spec-compliance-review`, narrower — spec-to-diff matching for a single freshly-implemented unit (Stage 1 of the three-stage inline review). |
+| structure-review | discovery-lens | Scans SRP violations, DRY, coupling, file organization, nesting depth, cognitive load, and async-pattern pitfalls (folds `complexity-review`, retired #2093) — open-ended. |
+| angular-reactivity-review | discovery-lens | Scans Zone.js change-detection pitfalls, OnPush/immutability violations, RxJS leaks — open-ended. |
+| react-reactivity-review | discovery-lens | Scans hook-rule violations, stale closures, missing dependency arrays, subscription leaks — open-ended. |
+| vue-reactivity-review | discovery-lens | Scans ref/reactive unwrapping pitfalls and watchEffect dependency tracking — open-ended. |
+| test-review | discovery-lens | Scans coverage gaps, assertion quality, test hygiene — open-ended. |
+| test-smell-review | discovery-lens | Scans xUnit test smells, test-double selection, test-pyramid placement — open-ended. |
+| token-efficiency-review | discovery-lens | Scans file/function size and LLM anti-patterns for token cost — open-ended. |
+
+**Tally:** 24 discovery-lens (2 of them analysis-only, noted), 4
+verification-gate, 1 not-applicable — 29 agents total, matching
+`agent-registry.md`'s Review Agents table row count exactly.
+
+## Applying the two metrics
+
+- **Discovery lenses**: `$/finding` from `metrics/review-value.jsonl` (per
+  `skills/harness-audit/SKILL.md` Step 4) remains the right cost signal.
+  Tier-down/removal candidates are agents with a consistently high
+  `$/finding` **and** a low finding-rate, per that step's existing
+  drop-candidate logic.
+- **Verification gates** (`spec-compliance-review`, `spec-reviewer`,
+  `progress-guardian`): the meaningful measure is **escape rate** — how
+  often a defect the gate should have caught was instead caught later (a
+  subsequent review round, a production incident, a later gate). No
+  instrumentation for escape rate exists yet; this is a gap this
+  classification surfaces, not one it closes. A future slice would need a
+  way to trace "the gate passed, but the defect it should have caught
+  surfaced anyway" — out of scope for #2007 itself.
+
+## `$/finding` recomputation attempt (#2007, post-#1998)
+
+#1998 (the 18.2% silent-drop fix) has merged, so recomputation is no longer
+blocked on principle. Attempted here against whatever data this checkout
+actually has:
+
+- `.claude/metrics/review-value.jsonl` — **absent**. No `/build`/`/code-review`
+  review rounds have been logged in this checkout.
+- `.claude/metrics/contract-failures.jsonl` (#1998's own instrumentation,
+  the repaired denominator `$/finding` needs) — **absent**. No JSON-contract
+  failures have been logged either.
+- `.claude/metrics/boundary-events.jsonl` — present, but 17 lines, all
+  `hook: "pre-commit-gate"` records from this session's own git commits (the
+  #2051/#1983 work above). Zero `dispatch-evidence-*`/`agent_dispatch_ledger`
+  records for any review agent.
+
+**Verdict: no recomputation is possible from this checkout's data — not "a
+thin sample," an empty one.** `.claude/metrics/` is deny-by-default
+gitignored (`**/metrics/*`, with an explicit allowlist for a handful of
+files that does not include `review-value.jsonl` or
+`contract-failures.jsonl`), so a fresh checkout or worktree starts with
+none of this history regardless of what a maintainer's long-running local
+clone has accumulated. Per the epic's evidence-first constraint and #2007's
+own instruction ("say so explicitly rather than presenting a thin number as
+authoritative"), no `$/finding` figure is reported here. The next
+recomputation attempt needs to run from a checkout that has actually
+accumulated post-#1998 `/code-review`/`/build` sessions — most likely a
+maintainer's own long-running local clone, not a fresh worktree — and
+should re-run `skills/harness-audit/SKILL.md` Step 4 (which already gates
+on `review_value_coverage.py`'s sample-validity verdict) rather than
+re-deriving the query here.

package/knowledge/review-rubric.md

@@ -0,0 +1,62 @@
+# Code Review Scoring Rubric
+
+The orchestrator reads this file during Step 5 to compute the overall
+health score from individual agent results.
+
+## The review-agent panel is the primary quality gate
+
+The review-agent panel is the primary quality gate for structural quality
+(Rec 5, `docs/experiments/RECOMMENDATIONS.md`). Coverage, mutation score, and
+the informational Farley Score are **saturating metrics**: every workflow
+shape drives them to near-identical values, so they cannot rank structural
+quality and must never gate or rank workflows. A higher mutation score must
+never be treated as evidence that a costlier workflow — or the code it
+produced — is better; in the experiment line the losing arms posted the
+higher mutation scores. Score health from the agent verdicts below, nothing
+else.
+
+## Health Score Calculation
+
+Collect the status from each agent: `pass`, `warn`, `fail`, `skip`.
+
+```
+🟢 HEALTHY  = 0 fail AND ≤2 warn
+🟠 NEEDS ATTENTION = 1-2 fail OR 3+ warn
+🔴 CRITICAL = 3+ fail OR any security-review fail
+```
+
+Agents that returned `skip` are excluded from scoring.
+
+## Category Weights
+
+Not all agent failures carry equal weight. Security and domain
+integrity failures escalate faster than style or naming issues.
+
+| Category | Agents | Escalation |
+|----------|--------|------------|
+| Security | security-review | Any fail → 🔴 overall |
+| Architecture | arch-review, domain-review | 2+ fail → 🔴 overall |
+| Correctness | test-review, concurrency-review | Normal scoring |
+| Quality | structure-review, js-fp-review, naming-review | Normal scoring |
+| Accessibility | a11y-review | Normal scoring |
+| Ops | doc-review, performance-review | Normal scoring |
+
+This table is not exhaustive — an agent absent from every row above (e.g. `correctness-review`, `spec-compliance-review`, `component-architecture-review`) still scores under the general pass/warn/fail rule, it just carries no category escalation. `claude-setup-review`, `token-efficiency-review`, and `ai-provenance-review` are the specific case worth calling out: none are dispatched by `/code-review`'s panel at all (#1733) — `claude-setup-review` runs on demand via the `/claude-setup-review` command, and all three run unconditionally in the whole-tree `/repo-review` skill (#1735) — so none ever contributes to a code-review verdict, in any row or under the general rule.
+
+## Issue Severity Mapping
+
+Agent issues map to the report as follows:
+
+| Agent severity | Report display | Correction prompt priority |
+|----------------|---------------|---------------------------|
+| error | 🔴 error | high |
+| warning | 🟠 warning | medium |
+| suggestion | 💡 suggestion | low |
+
+## Confidence and Actionability
+
+| Confidence | Meaning | Auto-fixable |
+|------------|---------|--------------|
+| high | Mechanical fix, single correct answer | Yes |
+| medium | Direction clear, implementation varies | Yes (with review) |
+| none | Requires human judgment | No — report only |