pi-dev-team 0.2.0

package/docs/upstream/context-management.md

@@ -0,0 +1,111 @@
+# Context Management
+
+How the plugin keeps a session's context in check: the harness compacts at a
+percentage `/dev-team:setup` configures, a pair of small SessionStart hooks
+nudge and restore state, and `/handoff` stays available by hand. For the
+runtime procedure (what to load, when), see [Context Loading
+Protocol](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/context-loading-protocol/SKILL.md);
+for manual compression and side-task forks, see
+[Handoff](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/handoff/SKILL.md).
+
+The design record is [ADR 0043](../../../docs/adr/0043-replace-the-context-ceiling-guard-with-harness-autocompact.md),
+which replaced the former context-ceiling hook (ADRs 0011, 0016, 0037-0039).
+
+## How it works
+
+1. **Harness autocompact, configured per repo.** `/dev-team:setup` writes
+   `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` into the repo's `.claude/settings.json`
+   `env` block (default `40`). The harness then compacts the conversation
+   when it reaches that percentage of its auto-compact window. It applies to
+   subagents as well as the main session.
+2. **A setup nudge.** On `startup`, `resume` and `clear`, the SessionStart
+   hook `autocompact_setup_nudge.py` prints one line recommending
+   `/dev-team:setup` when the key is absent or invalid in the process env,
+   `.claude/settings.local.json`, `.claude/settings.json` and user settings.
+   It is advisory, never blocks, and never fires on `compact`.
+3. **State restore after compaction.** A SessionStart hook with matcher
+   `compact`, `post_compact_state_reinject.py`, re-injects the active `/build`
+   phase, step, plan path and unchecked `## Build Progress` items as
+   `additionalContext` (at most 10,000 characters; phase and step survive
+   truncation first). It reads `.claude/memory/build-phase.json`, so it only
+   has something to restore while a build is in progress (a step, or
+   between steps). It is
+   best-effort and fail-open.
+4. **`/handoff` is manual.** Run it yourself to compress the conversation
+   (continue mode) or split off a side task (fork mode).
+   Write a full summary to `.claude/memory/` so the next phase starts from a
+   file. Nothing forces or blocks on it.
+
+## Configuring the threshold
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/set_autocompact_env.py" --project-dir . --yes
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/set_autocompact_env.py" --project-dir . --autocompact-pct 30
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/set_autocompact_env.py" --project-dir . --no-autocompact
+```
+
+`/dev-team:setup` runs the same script (Step 9b). The value is an integer
+1-100 written as a string, merged into existing `env` entries. The harness
+can only lower its threshold; values above its default (about 83%, reported)
+have no effect, and the script warns when you pick one. It also warns when a
+process-env or `settings.local.json` entry shadows the project value.
+
+There is no absolute token cap: the percentage applies to the window, so 40%
+of a 1M window is 400K. The former 350K cap was deliberately dropped.
+
+To silence the nudge without configuring autocompact, set
+`DEV_TEAM_AUTOCOMPACT_NUDGE=0` or create `.claude/memory/autocompact-nudge-off`
+(`--no-autocompact` creates it).
+
+## What to expect
+
+- **Coverage is per repo.** A repo that never runs `/setup` keeps the harness
+  default, which is much later than 40%. The nudge advises; it does not
+  enforce.
+- **Compaction is generic.** The harness summary can drop plan-step state,
+  file:line anchors and acceptance criteria. The re-inject hook restores
+  `/build` phase/step and plan progress only; for anything else, write a
+  structured summary with `/handoff` before you need it.
+- **Timing.** The threshold is checked between turns (reported, not
+  verified), so one long tool loop can overshoot it.
+- **`compact` SessionStart firing is unconfirmed.** That it fires after a
+  real compaction and reaches the model is tracked in
+  [#2233](https://github.com/bdfinst/agentic-dev-team/issues/2233).
+
+## Why a low threshold
+
+The 40% default is a conservative planning target, not a claimed accuracy
+cliff:
+
+- Chroma's [Context Rot study](https://www.trychroma.com/research/context-rot)
+  found degradation across 18 models (including Claude 4) is gradual, not a
+  sharp drop at any single percentage.
+- Needle-in-a-haystack benchmarks like RULER and NoLiMa show a model's
+  *effective* context is often only about half its advertised window.
+- Anthropic's [effective context engineering
+  guidance](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+  recommends proactive compaction well ahead of the limit.
+
+## Troubleshooting
+
+**"The nudge keeps firing after I ran setup."** A process-env or
+`settings.local.json` value can shadow the project one; the nudge names the
+source of an invalid value. Fix or remove that entry.
+
+**"Nothing restored after compaction."** `build-phase.json` is deleted when the plan
+completes, and records older than four hours are ignored; with no active
+build there is nothing to restore. Also check #2233.
+
+**"The setup script refuses to write."** It aborts, leaving the file
+untouched, when `.claude/settings.json` is malformed, is a symlink, is not a
+JSON object, or has a non-object `env`. Fix the file and re-run.
+
+## Source
+
+- `plugins/dev-team/scripts/set_autocompact_env.py` (writer),
+  `plugins/dev-team/hooks/lib/autocompact_config.py` (shared detector).
+- `plugins/dev-team/hooks/autocompact_setup_nudge.py`,
+  `plugins/dev-team/hooks/post_compact_state_reinject.py`,
+  `plugins/dev-team/hooks/lib/build_state.py`.
+- Registered in `plugins/dev-team/hooks/hooks.json` and
+  `plugins/dev-team/settings.json` under `SessionStart`.

package/docs/upstream/developer-notes.md

@@ -0,0 +1,280 @@
+# Developer notes — extending and maintaining the plugin
+
+This page is for people working **on** the dev-team plugin: adding a tool,
+agent, or skill, maintaining the eval corpus, or extending the static-analysis
+suite to a new language. If you are *using* the plugin for your own
+development work, you want the [skills reference](skills.md) and the
+[workflows guide](workflows.md) instead — nothing here changes how the plugin
+behaves in your project.
+
+## Where plugin-development knowledge lives
+
+Plugin-development documentation is spread across a few focused files. This
+table is the jumping-off point; each doc stays the authority for its own
+topic.
+
+| Topic | Doc | What it covers |
+|---|---|---|
+| Agent architecture | [`agent-architecture.md`](agent-architecture.md) | How agents are structured, routed, and dispatched. |
+| Agent authoring | [`agent_info.md`](agent_info.md) | The per-agent file format and required sections. |
+| Eval architecture | [`eval-system.md`](eval-system.md) | How the agent-eval system is built and gated. |
+| Running evals | [`eval-running-guide.md`](eval-running-guide.md) | The operational procedure for eval runs and variance batches. |
+| Eval upkeep | [`eval-maintenance.md`](eval-maintenance.md) | Grading rules, the calibration trap, and corpus discipline. |
+| Adapter & ruleset lifecycle | [`static-analysis-integration/maintenance.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/maintenance.md) | Ownership, drift detection, and deprecation for shipped adapters and rulesets. |
+| Adding agents, skills, or hooks | [root `CLAUDE.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/CLAUDE.md) § "Adding agents, skills, or hooks" | Where each artifact type lives and the structural audit to run afterwards. |
+| Code knowledge graphs | [`codegraph-vs-graphify.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/codegraph-vs-graphify.md) | When to use CodeGraph vs Graphify, how `/project-init` installs each, and the CLAUDE.md-preservation guard. |
+| Script conventions | [ADR 0014](../../../docs/adr/0014-python-for-cross-os-scripts.md), [ADR 0015](../../../docs/adr/0015-bash-removal-complete.md), [ADR 0031](../../../docs/adr/0031-raise-shipped-python-floor-to-3-10.md) | Why every shipped script is Python 3.10+ stdlib-only, the completed bash removal, and the floor's move off EOL 3.8. |
+
+## Hooks
+
+`PreToolUse`/`PostToolUse` guard hooks are documented in
+[`agent-architecture.md` § Governance](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/docs/agent-architecture.md#governance).
+`SubagentStop` hooks aren't yet indexed there; this section is the entry
+point for them.
+
+### Subagent Completion Guard
+
+A `SubagentStop` hook (`hooks/subagent_completion_guard.py`, #2188)
+classifies each dispatched subagent's own transcript tail into `clean`,
+`empty-final-turn`, `truncated-final-turn`, or `unreadable`, and emits a
+`boundary-events.jsonl` "warn" record for the two non-clean, explainable
+outcomes (`empty-final-turn`, `truncated-final-turn`) via
+`hooks/lib/boundary_events.emit_boundary_event`; `clean` and `unreadable`
+stay silent — record-only, never blocking. It runs alongside the plugin's
+other `SubagentStop` hooks, `hooks/cost_meter.py` and
+`hooks/task_completion_metrics.py` (both undocumented as of this entry).
+Classification reads the last JSON row of the subagent's own transcript file
+directly — no sidechain filtering needed, since every row in a subagent's
+own `subagents/agent-<hash>.jsonl` file already belongs to it — and checks
+`message.stop_reason == "max_tokens"` (→ `truncated-final-turn`, checked
+first since a token-limit cutoff can itself produce empty content) before
+falling back to empty/whitespace-only content (→ `empty-final-turn`).
+Fail-open throughout: a missing/unreadable transcript, or a last row missing
+`message`/`content` entirely, classifies as `unreadable` and emits nothing.
+Tests: `tests/hooks/test_subagent_completion_guard.py`.
+
+The rest of this page covers the one extension path that touches several of
+these files at once and has no other single writeup: adding a new language to
+the static-analysis suite.
+
+## Playbook: adding a static-analysis language
+
+The static-analysis suite has two consumption sites that share one registry:
+
+- **`/code-review`'s full-repo pre-pass** — the
+  [static-analysis-integration skill](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/SKILL.md)
+  runs every detected tool over the target set, normalizes output to the
+  unified finding envelope, deduplicates, and hands confirmed findings to the
+  review agents.
+- **`/build`'s static self-heal pass** — at each review checkpoint, language
+  **lanes** fix or surface mechanical findings in the changed files before
+  semantic review. The mechanism (scoping, the shared fix loop, the 2-attempt
+  cap, detection and provider binding, the degradation ladder) is specified
+  once in [`static-self-heal.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/build/references/static-self-heal.md);
+  lanes are registered in
+  [`tool-configs.md` § Build-time lanes](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/references/tool-configs.md#build-time-lanes).
+
+Adding a language means wiring both sites plus the user-facing setup docs.
+The four landed lanes are the worked examples this playbook generalizes from:
+
+| Lane | Issue | Autofix slot | Diagnostic slot | Notable shape |
+|---|---|---|---|---|
+| Python | #807 | ruff (SARIF-native) → black + flake8 | mypy (Tier 3 JSON adapter) → pyright (gated) | Two independent slots, each with a recognized-equivalent fallback. |
+| JS/TS | #808 | oxlint → biome → eslint (demoted) | none — verify via autofix check mode | A slow-but-qualified provider bound with granularity demotion. |
+| C# | #809 | `dotnet format` (SDK-builtin) | Roslyn ErrorLog SARIF from the GREEN-confirming build | Diagnostics ride a build the pipeline already pays for. |
+| Java | #810 | none — no fast Java autofixer exists | PMD (SARIF-native) → checkstyle | Diagnostic-only lane; standalone installer (the exception). |
+
+**Audience boundary.** This playbook is for plugin maintainers wiring a new
+language *into the plugin*. The
+[per-language setup guide](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/references/language-setup.md)
+is for end users configuring their own repo's toolchain, and it remains the
+single source of truth for install/config/verification commands. The two
+cross-link and never duplicate: your job here includes *adding* that guide's
+new section, not restating its content anywhere else.
+
+### First, classify the candidate tool — two independent questions
+
+Every candidate tool gets sorted by two axes, and they are genuinely
+independent — knowing one tells you nothing about the other:
+
+1. **Output format: SARIF-native, or needs an adapter?** This decides the
+   tool's tier in `tool-configs.md`. A tool that emits SARIF is consumed raw
+   by the [shared SARIF parser](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/references/sarif-parser.md)
+   (Tier 1/2). A tool with only JSON or line-based output needs a bespoke
+   adapter (Tier 3), and the budget is hard: **≤ 40 LOC**. If an adapter
+   wants to be bigger than that, the tool is fighting the pipeline —
+   reconsider the candidate.
+2. **Capability: autofix-capable, or diagnostic-only?** This decides which
+   lane **slot** the tool can provide. An autofix tool runs the mechanical
+   pre-fix and can double as its own verifier in check mode; a
+   diagnostic-only tool feeds findings to the coding agent inside the shared
+   fix loop.
+
+The worked examples cover all four quadrants: ruff is SARIF-native *and*
+autofix-capable; PMD is SARIF-native but diagnostic-only; mypy needs an
+adapter and is diagnostic-only; `dotnet format` is autofix-capable and needs
+no output format at all, because verification comes from its own
+`--verify-no-changes` mode and from the Roslyn ErrorLog SARIF.
+
+Version-pin early, and re-check the format question against the pinned
+version: oxlint was specced as a Tier 3 JSON adapter, but by implementation
+time the pinned release had gained native SARIF, so it landed adapter-free.
+Upstream SARIF support arriving is the cheapest adapter deletion you will
+ever do.
+
+### Wiring the `/code-review` side
+
+A new tool becomes visible to `/code-review` through an entry in
+[`tool-configs.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/references/tool-configs.md),
+under the tier its output format earned. The existing entries define the
+house metadata shape; a complete entry carries:
+
+- **Invocation** — the exact command, SARIF-first.
+- **Install** — the repo-level form (see the install conventions below).
+- **Install hint** — in the skill's fixed format:
+  `<tool-name> — <capability-tier>. install: <command>`. This exact string
+  is what users see when the tool is missing, so it names the repo-level
+  install, never a global one.
+- **Detection** — how presence is probed. Repo-local locations come first,
+  then PATH: a project-local `node_modules/.bin` binary or a gitignored tool
+  directory must be found even when nothing is user-installed.
+- **Language-conditional dispatch** — the tool is probed, dispatched, and
+  its missing-tool hint surfaced *only when matching files are in the target
+  set*. A non-Java repo must never see a "pmd missing" warning. Absence is
+  never a pipeline failure.
+- **Adapter** — "none" for SARIF-native tools; otherwise the ≤ 40 LOC
+  adapter under the skill's `adapters/`, with its field-mapping table in the
+  entry. Per the [maintenance policy](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/maintenance.md),
+  a SARIF adapter comes first — bespoke JSON only when upstream genuinely
+  has no SARIF plan.
+- **Exit-code semantics** — when the tool distinguishes "findings exist"
+  from "tool broke" by exit code (PMD exits 4 on violations), the entry says
+  so, because the degradation ladder treats the two very differently.
+
+Two more pieces ride along with the entry:
+
+- **A fixture pair** under `evals/static-analysis-tools/tier1-mocks/<tool>/`
+  — a mock tool output plus the expected unified findings. This is the
+  regression harness proving the parser (or adapter) reads the tool
+  correctly, and the maintenance policy makes it a precondition for adding
+  any tool.
+- **A dedup-chain decision.** The pre-pass deduplicates findings across
+  tools and keeps the higher-priority source; the chain lives in the skill's
+  step 4. Most language-specific tools need no new thought — semgrep already
+  outranks them all, and the precedent (recorded on the pmd and Roslyn
+  entries) is to revisit only if a *second* source for the same language is
+  added. A tool that genuinely overlaps an existing one, as oxlint overlaps
+  legacy ESLint, gets an explicit ranking.
+
+### Wiring the build-time lane
+
+The self-heal pass never gains per-language logic. Everything a lane does —
+how changed files are scoped, how the fix loop retries, when it escalates,
+how providers bind — is specified once in
+[`static-self-heal.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/build/references/static-self-heal.md), and a
+new language plugs in as pure registry data: one subsection under
+`tool-configs.md` § Build-time lanes. If you find yourself writing loop or
+scoping logic for your language, stop — the mechanism doc forbids restating
+it, and an accommodation belongs in the mechanism doc (as with C#'s
+post-hoc SARIF filtering), not in the lane row.
+
+A lane row declares:
+
+- **Extensions** — the file patterns that route changed files into the lane.
+- **Up to two capability slots** — an **autofix** slot and a **diagnostic**
+  slot, either of which may be absent. Missing slots are normal, not
+  deficiencies: the degradation ladder runs Java diagnostic-only (no fast
+  Java autofixer exists), and JS/TS verifies with the autofix tool's own
+  check mode rather than carrying a diagnostic slot.
+- **An ordered provider list per slot** — the default provider first. The
+  default doubles as the **last-resort provider**: the one install hints
+  name and `/project-init` installs, chosen only when the probe finds no
+  recognized provider already configured. This is the bind-don't-replace
+  rule — a project that arrives with black + flake8, or checkstyle, or an
+  ESLint config keeps its own tool.
+- **A detection probe per provider** — repo-local install locations first,
+  then PATH, matching the `/code-review` detection convention.
+- **Scoped invocations** — the fix and verify commands as run against the
+  checkpoint's changed-file list, plus any wrapper contract the tool needs
+  (PMD requires a `--file-list` temp file and must never be invoked with an
+  empty set; `dotnet format` treats an empty `--include` as "format
+  everything", which is why the mechanism's empty-partition guarantee is
+  load-bearing).
+
+Every provider you list must satisfy the mechanism's **provider
+qualification contract**: scoped invocation, machine-readable output within
+the adapter budget, checkpoint-compatible latency, deterministic exit codes.
+A tool that fails the latency item can still bind with its lane demoted to
+slice-boundary granularity — that is how a project's existing ESLint config
+is honored without slowing the per-step loop. Keep provider lists short and
+explicit: every recognized provider is an adapter and a registry row someone
+maintains, and this is deliberately not an open-ended plugin system.
+
+### The user-facing setup section and `/project-init`
+
+Two more places make the lane usable by people who did not read any of the
+above:
+
+- **A language section in [`language-setup.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/references/language-setup.md)**,
+  following that guide's "Per-lane section contract": tools and roles,
+  repo-level install, configuration, verification, opt-out, and recognized
+  equivalent providers, in that order. This is where the actual install and
+  verification commands live — the lane row and this playbook link to it
+  rather than repeating them.
+- **A `/project-init` lane**, so the one-command scaffold performs the same
+  repo-level install the setup section documents manually. Each
+  `language-setup.md` section carries the one-line pointer to
+  `/project-init`; the guide stays the source of truth for the manual
+  commands.
+
+### Install conventions
+
+The four landed lanes established conventions that new lanes inherit:
+
+- **Shipped scripts are Python 3.10+ stdlib-only.** No bash, no Git Bash
+  requirement; Windows portability comes from the Python stdlib. See
+  [ADR 0014](../../../docs/adr/0014-python-for-cross-os-scripts.md) and
+  [ADR 0015](../../../docs/adr/0015-bash-removal-complete.md).
+- **Repo-level over user-level, always.** The install lands in the project's
+  own dependency mechanism so the toolchain is versioned with the repo and
+  reproducible for every contributor and CI: an npm devDependency (oxlint),
+  a venv / dev-requirements entry (ruff, mypy), a `global.json` SDK pin
+  (dotnet), or a repo-local gitignored tool directory (`.pmd/`). Never
+  `npm install -g`, `pip install --user`, or a global toolchain assumption.
+- **A standalone installer is the exception, not the rule.** Of the four
+  lanes, only Java needed one (`plugins/dev-team/scripts/install-java-static-analysis.py`),
+  because PMD has no project-level dependency mechanism to ride. Prefer the
+  project's own mechanism; write an installer only when none exists.
+- **Idempotent re-runs.** Running the install twice must be safe and cheap —
+  an existing install is detected and nothing is re-downloaded.
+- **Single-source version pinning.** The pinned version lives in exactly one
+  place (the lockfile, `global.json`, or one constant in the installer), so
+  a bump is a one-line change.
+
+### Retiring an older tool
+
+Bind-don't-replace means older tools do not disappear when a better one
+lands: a project configured for ESLint keeps ESLint, and legacy tools stay
+in the provider list and dedup chain as long as real projects arrive with
+them. Retirement is therefore a deliberate decision, and the precedent to
+copy is the oxlint/ESLint checklist ("When a project may drop ESLint
+entirely" in [`tool-configs.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/references/tool-configs.md))
+— a **decidable** test, not a vibe:
+
+1. Every rule the old tool enforces in this project is either covered by the
+   new tool's pinned version or explicitly acknowledged as not relied on.
+2. No plugin/extension of the old tool contributes an enabled rule the new
+   tool lacks (framework ESLint plugins were the real blocker there).
+3. A one-time dual run over the repo shows the old tool reporting nothing
+   the new tool misses.
+
+Until all three hold, both tools run, with overlap suppressed (the
+`eslint-plugin-oxlint` pattern) and the dedup chain ranking the newer tool
+higher. The same shape applies to any successor pair — Ruff replacing
+pylint/flake8 followed it: the legacy Python entry was retired outright only
+once ruff covered the surface, while black + flake8 remain a recognized
+*provider pair* for projects that arrive with them. Retiring a tool from the
+plugin (deleting its entry and adapter) additionally follows the
+[adapter deprecation policy](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/maintenance.md):
+demote, warn, then remove at the next major contract version — never a
+silent deletion.

package/docs/upstream/diagrams/architecture-overview.svg

@@ -0,0 +1,101 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 520" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif">
+  <defs>
+    <filter id="shadow" x="-4%" y="-4%" width="108%" height="116%">
+      <feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#000" flood-opacity="0.07"/>
+    </filter>
+    <marker id="arrow" viewBox="0 0 10 8" refX="9" refY="4" markerWidth="8" markerHeight="6" orient="auto-start-reverse">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#94A3B8"/>
+    </marker>
+    <marker id="arrow-red" viewBox="0 0 10 8" refX="9" refY="4" markerWidth="8" markerHeight="6" orient="auto-start-reverse">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#F43F5E"/>
+    </marker>
+  </defs>
+
+  <!-- Light background so the diagram stays readable in dark-mode docs -->
+  <rect width="600" height="520" fill="#ffffff"/>
+
+  <!-- User Request -->
+  <g filter="url(#shadow)">
+    <rect x="215" y="12" width="170" height="44" rx="22" fill="#F8FAFC" stroke="#CBD5E1" stroke-width="1.5"/>
+    <text x="300" y="39" text-anchor="middle" font-size="13" font-weight="500" fill="#475569">User Request</text>
+  </g>
+
+  <!-- Arrow -->
+  <line x1="300" y1="56" x2="300" y2="78" stroke="#94A3B8" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <!-- Orchestrator -->
+  <g filter="url(#shadow)">
+    <rect x="195" y="82" width="210" height="52" rx="12" fill="#EEF2FF" stroke="#6366F1" stroke-width="1.5"/>
+    <rect x="195" y="82" width="5" height="52" rx="2.5" fill="#6366F1"/>
+    <text x="300" y="113" text-anchor="middle" font-size="14" font-weight="600" fill="#1E293B">Orchestrator</text>
+  </g>
+
+  <!-- Branches from Orchestrator -->
+  <line x1="258" y1="134" x2="158" y2="166" stroke="#94A3B8" stroke-width="2" marker-end="url(#arrow)"/>
+  <line x1="342" y1="134" x2="358" y2="166" stroke="#94A3B8" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <!-- Model Tier Resolution (PreToolUse hook) -->
+  <g filter="url(#shadow)">
+    <rect x="65" y="170" width="170" height="48" rx="12" fill="#F5F3FF" stroke="#8B5CF6" stroke-width="1.5"/>
+    <rect x="65" y="170" width="5" height="48" rx="2.5" fill="#8B5CF6"/>
+    <text x="150" y="194" text-anchor="middle" font-size="12" font-weight="600" fill="#1E293B">Model Tier Resolution</text>
+    <text x="150" y="208" text-anchor="middle" font-size="10" font-weight="400" fill="#475569">(PreToolUse hook)</text>
+  </g>
+
+  <!-- Agent Selection -->
+  <g filter="url(#shadow)">
+    <rect x="275" y="170" width="170" height="48" rx="12" fill="#EFF6FF" stroke="#3B82F6" stroke-width="1.5"/>
+    <rect x="275" y="170" width="5" height="48" rx="2.5" fill="#3B82F6"/>
+    <text x="360" y="199" text-anchor="middle" font-size="13" font-weight="600" fill="#1E293B">Agent Selection</text>
+  </g>
+
+  <!-- Merge arrows down -->
+  <line x1="150" y1="218" x2="300" y2="248" stroke="#94A3B8" stroke-width="2"/>
+  <line x1="360" y1="218" x2="300" y2="248" stroke="#94A3B8" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <!-- Task Execution -->
+  <g filter="url(#shadow)">
+    <rect x="190" y="252" width="220" height="52" rx="12" fill="#ECFDF5" stroke="#10B981" stroke-width="1.5"/>
+    <rect x="190" y="252" width="5" height="52" rx="2.5" fill="#10B981"/>
+    <text x="300" y="274" text-anchor="middle" font-size="13" font-weight="600" fill="#1E293B">Task Execution</text>
+    <text x="300" y="292" text-anchor="middle" font-size="11" fill="#64748B">Coding Agent</text>
+  </g>
+
+  <!-- Arrow down -->
+  <line x1="300" y1="304" x2="300" y2="330" stroke="#94A3B8" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <!-- Inline Review -->
+  <g filter="url(#shadow)">
+    <rect x="170" y="334" width="260" height="52" rx="12" fill="#FDF2F8" stroke="#EC4899" stroke-width="1.5"/>
+    <rect x="170" y="334" width="5" height="52" rx="2.5" fill="#EC4899"/>
+    <text x="300" y="356" text-anchor="middle" font-size="13" font-weight="600" fill="#1E293B">Inline Review Checkpoint</text>
+    <text x="300" y="374" text-anchor="middle" font-size="11" fill="#64748B">Targeted Review Agents</text>
+  </g>
+
+  <!-- Fail loop back -->
+  <path d="M170,360 C100,360 100,278 190,278" stroke="#F43F5E" stroke-width="2" fill="none" stroke-dasharray="6,3" marker-end="url(#arrow-red)"/>
+  <text x="95" y="315" text-anchor="middle" font-size="10" fill="#F43F5E">fail</text>
+  <text x="95" y="328" text-anchor="middle" font-size="9" fill="#F43F5E">(max 5x)</text>
+
+  <!-- Escalate -->
+  <line x1="430" y1="360" x2="490" y2="360" stroke="#F43F5E" stroke-width="2" stroke-dasharray="6,3" marker-end="url(#arrow-red)"/>
+  <g filter="url(#shadow)">
+    <rect x="490" y="340" width="100" height="40" rx="20" fill="#FEF2F2" stroke="#F43F5E" stroke-width="1.5"/>
+    <text x="540" y="365" text-anchor="middle" font-size="11" font-weight="500" fill="#DC2626">Escalate</text>
+  </g>
+  <text x="460" y="352" text-anchor="middle" font-size="9" fill="#F43F5E">still fail</text>
+
+  <!-- Pass arrow down -->
+  <line x1="300" y1="386" x2="300" y2="415" stroke="#94A3B8" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="320" y="404" font-size="10" fill="#10B981">pass / warn</text>
+
+  <!-- Learning Loop -->
+  <g filter="url(#shadow)">
+    <rect x="195" y="420" width="210" height="48" rx="12" fill="#F8FAFC" stroke="#64748B" stroke-width="1.5"/>
+    <rect x="195" y="420" width="5" height="48" rx="2.5" fill="#64748B"/>
+    <text x="300" y="449" text-anchor="middle" font-size="13" font-weight="600" fill="#1E293B">Learning Loop</text>
+  </g>
+
+  <!-- Loop back to orchestrator -->
+  <path d="M405,444 C520,444 520,108 405,108" stroke="#94A3B8" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+</svg>

package/docs/upstream/diagrams/review-dispatch.svg

@@ -0,0 +1,139 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 480" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif">
+  <defs>
+    <filter id="shadow" x="-4%" y="-4%" width="108%" height="116%">
+      <feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#000" flood-opacity="0.07"/>
+    </filter>
+    <marker id="arrow" viewBox="0 0 10 8" refX="9" refY="4" markerWidth="8" markerHeight="6" orient="auto-start-reverse">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#94A3B8"/>
+    </marker>
+    <marker id="arrow-green" viewBox="0 0 10 8" refX="9" refY="4" markerWidth="8" markerHeight="6" orient="auto-start-reverse">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#10B981"/>
+    </marker>
+    <marker id="arrow-red" viewBox="0 0 10 8" refX="9" refY="4" markerWidth="8" markerHeight="6" orient="auto-start-reverse">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#F43F5E"/>
+    </marker>
+  </defs>
+
+  <!-- Light background so the diagram stays readable in dark-mode docs -->
+  <rect width="900" height="480" fill="#ffffff"/>
+
+  <!-- Orchestrator -->
+  <g filter="url(#shadow)">
+    <rect x="16" y="190" width="160" height="52" rx="12" fill="#6366F1" stroke="#4F46E5" stroke-width="1"/>
+    <text x="96" y="213" text-anchor="middle" font-size="13" font-weight="600" fill="#FFF">Orchestrator</text>
+    <text x="96" y="229" text-anchor="middle" font-size="10" fill="#C7D2FE">Agent Dispatch</text>
+  </g>
+
+  <!-- Arrow to spec-compliance -->
+  <line x1="176" y1="216" x2="210" y2="216" stroke="#94A3B8" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="193" y="208" text-anchor="middle" font-size="9" fill="#64748B">all</text>
+
+  <!-- Spec Compliance (first gate) -->
+  <g filter="url(#shadow)">
+    <rect x="214" y="190" width="180" height="52" rx="12" fill="#EEF2FF" stroke="#6366F1" stroke-width="1.5"/>
+    <rect x="214" y="190" width="5" height="52" rx="2.5" fill="#6366F1"/>
+    <text x="304" y="213" text-anchor="middle" font-size="12" font-weight="600" fill="#1E293B">spec-compliance</text>
+    <text x="304" y="229" text-anchor="middle" font-size="10" fill="#6366F1">sonnet</text>
+  </g>
+
+  <!-- Pass arrow to Quality Gate -->
+  <line x1="394" y1="216" x2="430" y2="216" stroke="#10B981" stroke-width="2" marker-end="url(#arrow-green)"/>
+  <text x="412" y="208" text-anchor="middle" font-size="9" fill="#10B981">pass</text>
+
+  <!-- Quality Gate label -->
+  <g filter="url(#shadow)">
+    <rect x="434" y="190" width="120" height="52" rx="12" fill="#ECFDF5" stroke="#10B981" stroke-width="1.5"/>
+    <text x="494" y="221" text-anchor="middle" font-size="13" font-weight="600" fill="#065F46">Quality Gate</text>
+  </g>
+
+  <!-- Fail arrow back -->
+  <path d="M304,242 L304,262 L96,262 L96,242" stroke="#F43F5E" stroke-width="1.5" fill="none" stroke-dasharray="5,3" marker-end="url(#arrow-red)"/>
+  <text x="200" y="276" text-anchor="middle" font-size="9" fill="#F43F5E">fail → correction</text>
+
+  <!-- Fan-out lines from Quality Gate to agents -->
+  <line x1="554" y1="200" x2="630" y2="42" stroke="#CBD5E1" stroke-width="1.5"/>
+  <line x1="554" y1="206" x2="630" y2="102" stroke="#CBD5E1" stroke-width="1.5"/>
+  <line x1="554" y1="213" x2="630" y2="162" stroke="#CBD5E1" stroke-width="1.5"/>
+  <line x1="554" y1="219" x2="630" y2="222" stroke="#CBD5E1" stroke-width="1.5"/>
+  <line x1="554" y1="226" x2="630" y2="282" stroke="#CBD5E1" stroke-width="1.5"/>
+  <line x1="554" y1="232" x2="630" y2="342" stroke="#CBD5E1" stroke-width="1.5"/>
+
+  <!-- Trigger labels (left of agents) -->
+  <text x="588" y="40" text-anchor="middle" font-size="8" fill="#94A3B8">JS/TS</text>
+  <text x="588" y="100" text-anchor="middle" font-size="8" fill="#94A3B8">Tests</text>
+  <text x="588" y="160" text-anchor="middle" font-size="8" fill="#94A3B8">API/auth</text>
+  <text x="588" y="220" text-anchor="middle" font-size="8" fill="#94A3B8">Domain</text>
+  <text x="588" y="280" text-anchor="middle" font-size="8" fill="#94A3B8">UI</text>
+  <text x="588" y="340" text-anchor="middle" font-size="8" fill="#94A3B8">All</text>
+
+  <!-- Review agents (right column) -->
+  <!-- naming-review (haiku) -->
+  <g filter="url(#shadow)">
+    <rect x="630" y="20" width="180" height="44" rx="10" fill="#F8FAFC" stroke="#94A3B8" stroke-width="1"/>
+    <rect x="630" y="20" width="4" height="44" rx="2" fill="#94A3B8"/>
+    <text x="720" y="40" text-anchor="middle" font-size="11" font-weight="600" fill="#1E293B">naming-review</text>
+    <text x="720" y="54" text-anchor="middle" font-size="9" fill="#94A3B8">haiku</text>
+  </g>
+
+  <!-- test-review (sonnet) -->
+  <g filter="url(#shadow)">
+    <rect x="630" y="80" width="180" height="44" rx="10" fill="#EFF6FF" stroke="#3B82F6" stroke-width="1"/>
+    <rect x="630" y="80" width="4" height="44" rx="2" fill="#3B82F6"/>
+    <text x="720" y="100" text-anchor="middle" font-size="11" font-weight="600" fill="#1E293B">test-review</text>
+    <text x="720" y="114" text-anchor="middle" font-size="9" fill="#3B82F6">sonnet</text>
+  </g>
+
+  <!-- security-review (opus) -->
+  <g filter="url(#shadow)">
+    <rect x="630" y="140" width="180" height="44" rx="10" fill="#FEF2F2" stroke="#EF4444" stroke-width="1"/>
+    <rect x="630" y="140" width="4" height="44" rx="2" fill="#EF4444"/>
+    <text x="720" y="160" text-anchor="middle" font-size="11" font-weight="600" fill="#1E293B">security-review</text>
+    <text x="720" y="174" text-anchor="middle" font-size="9" fill="#EF4444">opus</text>
+  </g>
+
+  <!-- domain-review (opus) -->
+  <g filter="url(#shadow)">
+    <rect x="630" y="200" width="180" height="44" rx="10" fill="#FEF2F2" stroke="#EF4444" stroke-width="1"/>
+    <rect x="630" y="200" width="4" height="44" rx="2" fill="#EF4444"/>
+    <text x="720" y="220" text-anchor="middle" font-size="11" font-weight="600" fill="#1E293B">domain-review</text>
+    <text x="720" y="234" text-anchor="middle" font-size="9" fill="#EF4444">opus</text>
+  </g>
+
+  <!-- a11y-review (sonnet) -->
+  <g filter="url(#shadow)">
+    <rect x="630" y="260" width="180" height="44" rx="10" fill="#EFF6FF" stroke="#3B82F6" stroke-width="1"/>
+    <rect x="630" y="260" width="4" height="44" rx="2" fill="#3B82F6"/>
+    <text x="720" y="280" text-anchor="middle" font-size="11" font-weight="600" fill="#1E293B">a11y-review</text>
+    <text x="720" y="294" text-anchor="middle" font-size="9" fill="#3B82F6">sonnet</text>
+  </g>
+
+  <!-- structure-review (sonnet) -->
+  <g filter="url(#shadow)">
+    <rect x="630" y="320" width="180" height="44" rx="10" fill="#EFF6FF" stroke="#3B82F6" stroke-width="1"/>
+    <rect x="630" y="320" width="4" height="44" rx="2" fill="#3B82F6"/>
+    <text x="720" y="340" text-anchor="middle" font-size="11" font-weight="600" fill="#1E293B">structure-review</text>
+    <text x="720" y="354" text-anchor="middle" font-size="9" fill="#3B82F6">sonnet</text>
+  </g>
+
+  <!-- Aggregate -->
+  <line x1="810" y1="42" x2="850" y2="216" stroke="#CBD5E1" stroke-width="1"/>
+  <line x1="810" y1="102" x2="850" y2="216" stroke="#CBD5E1" stroke-width="1"/>
+  <line x1="810" y1="162" x2="850" y2="216" stroke="#CBD5E1" stroke-width="1"/>
+  <line x1="810" y1="222" x2="850" y2="216" stroke="#CBD5E1" stroke-width="1"/>
+  <line x1="810" y1="282" x2="850" y2="216" stroke="#CBD5E1" stroke-width="1"/>
+  <line x1="810" y1="342" x2="850" y2="216" stroke="#CBD5E1" stroke-width="1"/>
+
+  <!-- Aggregate diamond -->
+  <polygon points="850,196 870,216 850,236 830,216" fill="#FFF7ED" stroke="#F97316" stroke-width="1.5" filter="url(#shadow)"/>
+  <text x="850" y="220" text-anchor="middle" font-size="8" font-weight="600" fill="#C2410C">AGG</text>
+
+  <!-- Legend -->
+  <g transform="translate(16, 440)">
+    <rect x="0" y="0" width="12" height="12" rx="3" fill="#F8FAFC" stroke="#94A3B8" stroke-width="1"/>
+    <text x="18" y="10" font-size="10" fill="#64748B">haiku (fast, pattern-matching)</text>
+    <rect x="220" y="0" width="12" height="12" rx="3" fill="#EFF6FF" stroke="#3B82F6" stroke-width="1"/>
+    <text x="238" y="10" font-size="10" fill="#64748B">sonnet (semantic analysis)</text>
+    <rect x="440" y="0" width="12" height="12" rx="3" fill="#FEF2F2" stroke="#EF4444" stroke-width="1"/>
+    <text x="458" y="10" font-size="10" fill="#64748B">opus (cross-file reasoning)</text>
+  </g>
+</svg>