pi-dev-team 0.2.0

package/docs/upstream/artifact-migration.md

@@ -0,0 +1,124 @@
+# Artifact migration guide (upgrading an existing project)
+
+Audience: **operators** — anyone upgrading an existing project's `dev-team` plugin
+install across the `.claude/`-scoped runtime artifact change (issue #1406, plan
+`opt-in-metrics-and-claude-scoped-artifacts.md`). This is not a maintainer doc —
+see [`developer-notes.md`](developer-notes.md) for plugin-development docs.
+
+## What changed
+
+Two coordinated changes:
+
+1. **Consent flips from on-by-default to off-by-default**, gated by a single
+   user-level config file: `~/.claude/telemetry.json`. `telemetry.jsonl` and
+   `artifact-usage.json` move to `~/.claude/metrics/`.
+2. **Every other project-scoped runtime artifact directory** (`metrics/`,
+   `memory/`, `plans/`) moves under the project's own `.claude/` instead of the
+   repo root, and the reports domain (`reports/` + `DEV_TEAM_REPORTS/`)
+   consolidates into a new top-level `.dev-team-reports/`.
+
+Each pre-existing file falls into exactly one of three treatments below —
+**never assume a file you rely on was auto-migrated; check which bucket it's in.**
+
+## 1. One-time move (writers with a real Python touchpoint)
+
+These files are moved — not copied — from their old bare path into
+`.claude/<category>/` **the first time their owning hook/script writes (or, for
+one case, reads) after upgrade**. The move is per-file, never a directory
+sweep, and skips any file that is git-tracked (a tracked legacy file is left in
+place rather than silently moved out from under version control).
+
+| File | Old path | New path |
+| --- | --- | --- |
+| `cost-metering.jsonl` | `metrics/cost-metering.jsonl` | `.claude/metrics/cost-metering.jsonl` |
+| `{date}-task-log.jsonl` | `metrics/{date}-task-log.jsonl` | `.claude/metrics/{date}-task-log.jsonl` |
+| `config-changelog.jsonl` | `metrics/config-changelog.jsonl` | `.claude/metrics/config-changelog.jsonl` |
+| `pending-review.jsonl` | `metrics/pending-review.jsonl` | `.claude/metrics/pending-review.jsonl` |
+| `learning-loop-state.json` | `metrics/learning-loop-state.json` | `.claude/metrics/learning-loop-state.json` |
+| boundary-events log | `metrics/boundary-events.jsonl` | `.claude/metrics/boundary-events.jsonl` |
+| `/test-improve`'s phase-state tree | `memory/test-improve/<slug>/` | `.claude/memory/test-improve/<slug>/` (directory-migrated file-by-file on the next resume; `refactor-backlog.md` is excluded — see § 2) |
+
+The shared mechanism is `hooks/lib/artifact_paths.py`'s `resolve_file()` (single
+file) and `migrate_dir()` (whole subtree, one call per invocation, still
+file-by-file — never overwrites an existing destination). Both are fail-open:
+a failed move logs one diagnostic line to stderr and the calling operation
+proceeds unaffected — it never blocks or raises.
+
+`verify-log.jsonl` is a deliberate exception: it stays at the bare
+`metrics/verify-log.jsonl` and is **not** part of this migration at all (it
+was never moved, gated, or relocated).
+
+## 2. Documented clean break (agent-instruction-driven writers, no Python write call site)
+
+These files are written by agent *instructions* (skill/agent markdown telling
+Claude where to `Write`), not by a Python hook. There is no code path that can
+migrate them, so pre-existing top-level content is **left in place
+permanently** — it is not moved, and new writes after upgrade go straight to
+the new location, meaning old and new content end up split across two paths
+with no automatic reconciliation.
+
+| File / tree | Old path | New path (new writes only) |
+| --- | --- | --- |
+| `review-value.jsonl` | `metrics/review-value.jsonl` | `.claude/metrics/review-value.jsonl` |
+| `build-phase.json` | `memory/build-phase.json` | `.claude/memory/build-phase.json` (read side uses `migrate=False` deliberately — it never moves the legacy file) |
+| `refactor-backlog.md` (`/test-improve`) | `memory/test-improve/<slug>/refactor-backlog.md` | `.dev-team-reports/test-improve/<slug>/refactor-backlog.md` (a report, not runtime state — explicitly excluded from `migrate_dir()`'s `.claude/memory/` sweep; see the reports-domain row below) |
+| `/test-improve` reports output | `reports/test-improve/<slug>/` | `.dev-team-reports/test-improve/<slug>/` |
+| `/test-improve` plan artifacts | `plans/test-improve/` | `.claude/plans/test-improve/` |
+| `DEV_TEAM_REPORTS/`-domain writers (`/review-agent`, `/code-review` interactive, `/triage`, `/report-pdf`, `/ship`, `/exploratory-testing`, `/session-review`) | `DEV_TEAM_REPORTS/...` / `reports/...` | `.dev-team-reports/...` |
+
+**Practical consequence:** if a project has an in-flight `/build` session (a
+recorded `build-phase.json`) or unresolved review-value/reports content at the
+moment it crosses the upgrade boundary, that in-flight state is effectively
+orphaned at the old path — `/build`'s phase tracking for that session will
+behave as if no phase is recorded. There is no data-loss risk (nothing is
+deleted), but the record will not be picked up post-upgrade.
+
+## 3. Dual-read fallback (transition-window self-healing)
+
+Three reader commands tolerate the split between old and new locations
+without any manual step:
+
+- **`/cost-report`** and **`/harness-audit`** read `cost-metering.jsonl`,
+  `review-value.jsonl`, and `config-changelog.jsonl` by preferring
+  `.claude/metrics/<file>`, falling back to the bare `metrics/<file>` if the
+  new path doesn't exist yet. This self-heals during the transition window —
+  no operator action needed.
+- **`/artifact-lifecycle`** reads `artifact-usage.json` exclusively from
+  `~/.claude/metrics/artifact-usage.json` (home-scoped). This file was already
+  home-scoped as of the telemetry-consent change, so there is no legacy
+  project-scoped fallback to read — any older doc reference to a
+  project-scoped path was a documentation bug, now corrected to point at the
+  one location the file has ever actually been written to.
+
+## Consent-file migration is manual — not automatic
+
+If a project previously had a `.claude/telemetry.json` (or, pre-this-change,
+any project-level telemetry consent setting) with `{"enabled": true}`, **that
+setting is not carried forward.** Consent is now resolved exclusively from
+`~/.claude/telemetry.json` (home-scoped). `DEV_TEAM_TELEMETRY` also has no
+effect any more.
+
+**Action required:** if you want telemetry after upgrading, re-opt-in at the
+new location:
+
+```bash
+mkdir -p ~/.claude
+echo '{"enabled": true}' > ~/.claude/telemetry.json
+```
+
+Nothing reads or migrates a project's old consent file automatically — an
+un-migrated project simply defaults to telemetry disabled (fail-open), which
+is the deliberate new default posture, not a bug.
+
+## Quick reference: what to check after upgrading
+
+- [ ] If you rely on telemetry, artifact-usage, or cost data: re-opt-in via
+      `~/.claude/telemetry.json` (see above) — nothing carries over.
+- [ ] If you have an in-flight `/build` session across the upgrade: expect its
+      phase-tracking state to reset (§ 2, `build-phase.json`).
+- [ ] Old top-level `reports/`, `DEV_TEAM_REPORTS/`, `memory/`,
+      `plans/test-improve/` content stays exactly where it is — read it from
+      the old path, or move it by hand if you want it under the new tree.
+- [ ] `.gitignore` rules for these directories were rewritten to match the new
+      paths; if you have local overrides, re-check them against the new
+      `.claude/`-scoped and `.dev-team-reports/`-scoped paths.

package/docs/upstream/code-intelligence-nudge.md

@@ -0,0 +1,149 @@
+# code-intelligence-nudge
+
+A PreToolUse hook that recommends whichever of **CodeGraph**, **Repowise**,
+and **Graphify** are indexed in the project over multi-file `Read` / `Grep` /
+`Glob` exploration. Renamed and generalized from `codegraph-nudge` (#1368):
+the original only ever recommended CodeGraph, even on projects where
+Repowise and/or Graphify were also indexed, pushing agents toward the
+narrowest tool even when the question called for a different one.
+
+## What it does
+
+The hook fires on every `Read`, `Grep`, and `Glob` tool call. It exits 0
+silently unless **all** of the following are true:
+
+1. The tool call looks like multi-file exploration:
+   - `Grep` with `path` unset, or `path` pointing to a directory, or `path` containing glob metacharacters.
+   - `Glob` with a `pattern` containing `*`, `?`, or `[`.
+   - (Single-file `Read` calls are always silent; `Read` is one path.)
+2. At least one of `.codegraph/`, `.repowise/`, or `graphify-out/graph.json`
+   is present in the project's cwd.
+3. That tool hasn't already been used earlier in the current turn (see
+   "Sentinel mechanism" below) — Graphify is the one exception; see
+   "Known asymmetry: Graphify never suppresses" below.
+
+Detection is independent per tool: `.codegraph/` must be a directory,
+`.repowise/` must be a directory, and `graphify-out/graph.json` must be a
+regular file. A path that exists but is the wrong type (e.g. `.repowise` as
+a plain file, or `graphify-out/graph.json` as a directory) is treated as
+"not present," never as a crash. `graphify-out/` existing without
+`graph.json` inside it produces no Graphify nudge.
+
+**One tool present** — the hook prints a single-tool nudge to stderr, e.g.:
+
+```text
+[code-intelligence-nudge] CodeGraph is initialized in this project. Prefer codegraph_explore — structure, call graph, blast radius (not risk, rationale, or non-code content) for multi-file exploration; Grep/Glob/Read for confirming a specific detail.
+```
+
+**Two or more tools present** — the hook composes one combined message
+naming each present-and-unused tool, in a **fixed precedence order**
+(Graphify, then Repowise, then CodeGraph — never the order in which the
+filesystem checks happened to run), each with a short differentiator clause
+so a reader knows *why* to pick one tool over another, not just its name:
+
+```text
+[code-intelligence-nudge] Multiple code-intelligence indexes found. Pick whichever matches your question:
+- graphify query "<question>" — cross-artifact: code + docs + schemas + infra (non-code content; not a faster CodeGraph/Repowise)
+- repowise get_context / get_risk / get_why — risk, rationale, code health, dead code (not raw call-graph structure)
+- codegraph_explore — structure, call graph, blast radius (not risk, rationale, or non-code content)
+Grep/Glob/Read for confirming a specific detail.
+```
+
+Only the present-and-not-yet-used-this-turn tools appear in the bulleted
+list — a tool already used this turn (per the sentinel) drops out of the
+message entirely; if that leaves zero qualifying tools, the hook is fully
+silent (no output at all, not an empty bulleted list).
+
+The hook **always exits 0** unless `/careful` mode is active, in which
+case it exits 2 (blocking the tool call) and appends `[blocked by /careful]`
+to the message. This matches the precedent set by `hooks/destructive_guard.py`.
+
+## Fail-open
+
+Any internal error — malformed JSON on stdin, an unreadable transcript, a
+missing or corrupt sentinel, a wrong-type `.codegraph/`/`.repowise/`
+directory or `graphify-out/graph.json` file — exits 0 without output. The
+hook is a nudge, never a gate. A broken hook must never block legitimate
+`Read` / `Grep` / `Glob` calls, and a malformed sentinel is always read as
+"no tool used this turn" rather than raised.
+
+## Sentinel mechanism
+
+A companion hook, `hooks/code_intelligence_turn_mark.py`, runs as a
+`PostToolUse` hook on two matchers: `mcp__codegraph__.*` and
+`mcp__plugin_repowise_repowise__.*`. Each time a recognized CodeGraph or
+Repowise MCP tool completes, it writes a small JSON sentinel to
+`${CLAUDE_PROJECT_DIR}/.claude/code-intelligence-turn-state.json`:
+
+```json
+{ "transcript_id": "<basename of transcript_path minus extension>",
+  "turn_counter": <count of `"type":"user"` markers in the last ~1 MiB of the transcript>,
+  "tools_used": ["codegraph", "repowise"] }
+```
+
+`tools_used` **accumulates** rather than overwrites within the same turn —
+if a `codegraph_*` tool ran earlier this turn and a `repowise` tool runs
+next, the sentinel ends up listing both families, deduplicated, in
+first-used order. A new turn (the transcript's `turn_counter` incremented,
+i.e. the user sent another message) or a new `transcript_id` resets the
+list to just the family that triggered the write — the accumulation never
+carries across a turn boundary.
+
+The nudge hook reads this sentinel on each invocation and re-computes the
+current `transcript_id` and `turn_counter` from the live transcript. If
+both match the sentinel, every family listed in `tools_used` is subtracted
+from the set of qualifying tools before composing the message — so a
+two-tool project where CodeGraph was already used this turn shows only the
+Repowise line (or is fully silent if Repowise was used too). If the sentinel
+is missing, unparseable, has no `tools_used` field at all (the pre-upgrade
+schema), or has a `tools_used` field that isn't a list, it's treated as an
+empty list — "no tool used this turn" — never a crash.
+
+This avoids walking the full transcript on every `Read` / `Grep` / `Glob`
+call (the mark hook does the lookup once, after the CodeGraph/Repowise tool
+runs).
+
+### Known asymmetry: Graphify never suppresses
+
+Graphify has no MCP surface — it's conventionally invoked via `Bash`
+(`graphify query "<question>"`, `graphify explain "<concept>"`, etc.), and
+no `Bash` matcher was added to write into the sentinel (a deliberate
+scope decision — see the plan's "Decision-defaults stances" section, not an
+oversight). CodeGraph's and Repowise's nudge lines drop out of the combined
+message once either tool has actually been used this turn; Graphify's line
+cannot be suppressed the same way and can re-fire immediately after a
+CLI-based `graphify query` call, even within the same turn. This is an
+accepted tradeoff, not an unfixed bug — flagging it here so a future
+contributor doesn't mistake the asymmetry for a regression.
+
+## How to silence it
+
+1. Run a `codegraph_*` MCP tool and/or a `repowise` MCP tool first in the
+   same turn — the rest of the turn's `Read` / `Grep` / `Glob` calls omit
+   that tool's line (or go fully silent if every present tool has been used).
+   Graphify is the exception — see "Known asymmetry" above.
+2. Use single-file shapes when you really do want raw file IO:
+   - `Read` is always silent.
+   - `Grep` with `path` set to an explicit file is silent.
+   - `Glob` with a literal `pattern` (no metacharacters) is silent.
+3. Remove `.codegraph/`, `.repowise/`, and/or `graphify-out/` from the
+   project — the hook is project-scoped and only nudges for tools it
+   detects as present.
+
+## How to escalate it
+
+`/careful` makes the nudge a hard block (`exit 2`). Useful for
+production-critical sessions where you want to force use of an available
+code-intelligence tool.
+
+## Source
+
+- `plugins/dev-team/hooks/code_intelligence_nudge.py`
+- `plugins/dev-team/hooks/code_intelligence_turn_mark.py`
+- `plugins/dev-team/hooks/lib/turn_identity.py` (shared `transcript_id`/
+  `count_user_lines` computation used by both hooks)
+- Registered in `plugins/dev-team/settings.json` under PreToolUse
+  (`Read`, `Grep`, `Glob`) and PostToolUse (`mcp__codegraph__.*`,
+  `mcp__plugin_repowise_repowise__.*`).
+- Tests: `plugins/dev-team/tests/hooks/test_code_intelligence_nudge.py` and
+  `plugins/dev-team/tests/hooks/test_code_intelligence_turn_mark.py`.

package/docs/upstream/code-review-process.md

@@ -0,0 +1,294 @@
+# Code Review Process
+
+How `/code-review` (and its alias `/review`) works end-to-end: from invocation to final report, including the auto-fix loop and the artifacts it produces.
+
+> **Authoritative source**: the skill spec at [`skills/code-review/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/code-review/SKILL.md). This document is a reader-friendly walkthrough that links to the spec, rubric, template, and output format for details.
+
+**On this page**: [What it does](#what-it-does) · [Invocation](#invocation) · [Pipeline](#pipeline) · [Artifacts](#artifacts) · [Customization points](#customization-points) · [Relationship to other workflows](#relationship-to-other-workflows) · [Concurrent use](#concurrent-use) · [References](#references)
+
+## What it does
+
+`/code-review` is an **orchestrator-only** workflow. It does not review code itself — it dispatches a suite of focused review agents in parallel, aggregates their structured findings, optionally auto-fixes actionable issues in a bounded loop, and produces a health-scored report.
+
+It follows the [Minimum CD agent configuration](https://migration.minimumcd.org/docs/agentic-cd/agent-configuration/) pattern: delegate all semantic analysis, minimize context passed to each agent, run cheap deterministic checks before spending tokens on AI, and return structured results.
+
+## Invocation
+
+```bash
+/code-review                    # auto-scope
+/code-review --path src/auth    # targeted directory
+/code-review --since main       # everything changed since ref
+/code-review --all              # full repository
+/code-review --agent test-review  # single agent (delegates to /review-agent)
+/code-review --json             # machine-readable output (CI)
+/code-review --background       # drift review (no gates, structural agents only)
+/code-review --force --reason "release freeze"  # skip gates, logged
+```
+
+See the [skill spec](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/code-review/SKILL.md#parse-arguments) for the full argument list.
+
+## Pipeline
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#dbeafe', 'primaryTextColor': '#1e3a5f', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f1f5f9', 'tertiaryColor': '#e0f2fe', 'background': '#ffffff', 'mainBkg': '#dbeafe', 'nodeBorder': '#2563eb', 'clusterBkg': '#eff6ff', 'clusterBorder': '#bfdbfe', 'titleColor': '#1e3a5f', 'edgeLabelBackground': '#f8fafc'}}}%%
+flowchart TD
+    A[/code-review invoked/] --> B[1. Determine target files]
+    B --> C{Auto-scope}
+    C -->|dirty tree| D1[Uncommitted files]
+    C -->|clean tree| D2[Full repo]
+    D1 --> DC{1a. All files docs-only?}
+    D2 --> DC
+    DC -->|yes — no --force/--agent/--background| SC[Short-circuit: notice +<br/>write .pr-review-passed if auto-scoped + stop]
+    DC -->|no| E[1b. REVIEW-CONTEXT.md]
+    E --> F[1c. Probe MCP tools]
+    F --> G[2. Pre-flight gates]
+    G -->|fail| X1[Stop — no agents run]
+    G -->|pass| H[2b. Static analysis pre-pass]
+    H --> I[3. Select enabled agents]
+    I --> J[4. Dispatch agents in parallel]
+    J --> K[5. Apply ACCEPTED-RISKS suppression]
+    K --> L[5b. Compute health score]
+    L --> M{Actionable issues?}
+    M -->|no| R[7. Generate report]
+    M -->|yes| N[6. Ask: fix or report only?]
+    N -->|report only| R
+    N -->|fix| O[6a. Review-fix loop<br/>max 5 iterations]
+    O --> P{Converged?}
+    P -->|yes| R
+    P -->|no| Q[Escalate remaining to human]
+    Q --> R
+    R --> S[8. Save correction prompts]
+    S --> T[9. Write .pr-review-passed if applicable]
+```
+
+### 1. Determine target files
+
+File scope is resolved with this priority: `--path` → `--since` → `--all` → **auto-scope**.
+
+Auto-scope (the default) runs `git diff --name-only` plus `git diff --cached --name-only`. If either shows changes, only those files are reviewed. If the working tree is clean, the full repository is reviewed.
+
+| File count (full-repo mode) | Behavior |
+| ----------------------------- | ---------- |
+| ≤ 200 | Proceed |
+| 201–500 | Warn, proceed |
+| > 500 | Warn and request confirmation |
+
+### 1a. Documentation-only short-circuit
+
+After the target set is known, if **every** file is documentation, `/code-review` short-circuits: it emits `Documentation-only changeset — skipping code review`, writes the `.pr-review-passed` gate file when auto-scoped to uncommitted changes (so the eventual `gh pr create` isn't blocked, #1886), and stops before any gate or agent runs. In `--json` mode it emits `{"status": "skipped", "reason": "documentation-only"}`.
+
+Documentation = `.md`/`.mdx`/`.rst`/`.txt`/`.adoc`, `docs/**`, and root docs (`README*`, `CHANGELOG*`, `LICENSE*`, …) — **except functional Claude-config markdown** (`.claude/**`, `agents/`, `skills/`, `prompts/`, `knowledge/`, `templates/agents/`, `CLAUDE.md`, `AGENTS.md`), which is always reviewed. `--force --reason`, `--agent`, and `--background` bypass the short-circuit.
+
+### 1b. Institutional context
+
+If `REVIEW-CONTEXT.md` exists at the repo root, its contents are read and passed to every agent as "Institutional context provided for this review". This is where a team records domain knowledge, related services, known quirks, or architectural history that agents cannot discover from code alone. The file is optional.
+
+### 1c. Optional MCP tools
+
+The orchestrator probes for enhanced analysis tools (RoslynMCP, code knowledge graph, documentation MCP, Semgrep) and records availability. Agents fall back to Glob/Grep/Read when a tool is unavailable — all agents work without them. Tool availability appears in the final report.
+
+### 2. Pre-flight gates (fail fast, fail cheap)
+
+Deterministic checks run before any AI agent is invoked. Cheaper checks block expensive ones.
+
+| # | Gate | Tool | Stops on |
+| --- | ------ | ------ | ---------- |
+| 1 | Lint | `npx eslint` (or project's lint) | errors |
+| 2 | Type check | `npx tsc --noEmit` (if `tsconfig.json` exists) | errors |
+| 3 | Secret scan | grep for common secret patterns | any match |
+| 4 | Semgrep SAST | `semgrep scan --config auto` | ERROR-severity findings |
+| 5 | Pipeline-red check | `gh run list` on current branch | failing CI (warn only) |
+
+Missing tools are skipped silently. Gate failures stop the pipeline — no agents run. `--force --reason "<text>"` skips all gates (and the step-1a documentation-only short-circuit) and logs an entry to `.claude/metrics/override-audit.jsonl`. `--background` skips gates entirely.
+
+### 2b. Static analysis pre-pass
+
+If static analysis tools are available (Semgrep, ESLint, TypeScript, Ruff, mypy), they run against the target files and collect structured findings. Results are **deduplicated across tools** and injected into each agent's prompt as pre-confirmed context:
+
+> "These issues were detected by static analysis tools. Do not re-report them. Focus on semantic and architectural concerns."
+
+Unlike pre-flight gates, the pre-pass never stops the pipeline — its purpose is to give agents a head start. If Semgrep already ran in gate 4, findings are reused rather than re-collected. See [`skills/static-analysis-integration/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/static-analysis-integration/SKILL.md) for detection, execution, and deduplication rules.
+
+### 3. Select enabled agents
+
+All review agents in `agents/*.md` that declare an `effort:` band are enabled by default. Two language-agnostic agents always run regardless of tech stack:
+
+- `doc-review` — README, API docs, inline comments, ADRs
+- `arch-review` — layer boundaries, dependency direction, pattern consistency
+
+`claude-setup-review`, `token-efficiency-review`, and `ai-provenance-review` are deliberately absent (#1733). `claude-setup-review` reviews the **harness** rather than the changeset, so it had nothing to say about a diff — `Scope: always` put it in an 18-lens panel for a two-file JavaScript change in a project with no Claude configuration at all. `token-efficiency-review` (CLAUDE.md/rule verbosity, file-size drift) and `ai-provenance-review` (AI-provenance verification debt) are properties of the whole tree, not any single diff, for the same reason. All three are now dispatched instead by the whole-tree `/repo-review` command — `claude-setup-review` also stays reachable on demand via `/claude-setup-review`.
+
+A project-local `review-config.json` can disable specific agents. `--background` mode restricts the run to `doc-review`, `arch-review`, `naming-review`, and `structure-review`.
+
+### 4. Dispatch agents in parallel
+
+Each enabled agent is spawned as a sub-agent via the Agent tool, all in a single message for maximum parallelism. Each sub-agent:
+
+- Runs in isolation (context is **not** shared with the parent)
+- Receives only the files matching its declared scope (e.g., `js-fp-review` gets JS/TS only)
+- Receives the minimum context its `Context needs` field requires
+
+| `Context needs` | Input | When to use |
+| ----------------- | ------- | ------------- |
+| `diff-only` | Git diff output only | Pattern-matching agents (naming, FP) |
+| `full-file` | Complete file contents | Agents needing function-level context |
+| `project-structure` | Full files + directory tree | Agents reasoning about architecture |
+
+When the target is the full repository (`--all`, `--path`, or clean auto-scope), agents always receive full files regardless of `Context needs`.
+
+**Model selection** is declared per agent, not orchestrator-controlled. Each
+agent declares `model:` (an alias, a full model ID, or `inherit`) and
+`effort:` directly in its frontmatter — the native Claude Code sub-agent
+contract, resolved by the harness itself before dispatch (ADR 0026).
+
+Each agent returns a JSON result: `{agentName, status, modelTier, issues[], summary}`. See [`skills/code-review/output-format.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/code-review/output-format.md).
+
+### 5. Aggregate results
+
+**5a. ACCEPTED-RISKS suppression.** If `ACCEPTED-RISKS.md` exists at the repo root, its YAML rules are applied in declaration order. The first matching rule suppresses a finding and emits a one-line audit entry. Expired rules become inert and emit a WARN. Broad rules (wildcard `rule_id` or multi-file globs) emit an informational notice. Schema-invalid rules fail the run. Suppressed findings bypass the fix loop and appear in a dedicated report section grouped by rule id. See [`knowledge/accepted-risks-schema.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/accepted-risks-schema.md).
+
+**5b. Health scoring** per [`knowledge/review-rubric.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/review-rubric.md):
+
+| Score | Condition |
+| ------- | ----------- |
+| 🟢 HEALTHY | 0 fail AND ≤ 2 warn |
+| 🟠 NEEDS ATTENTION | 1–2 fail OR 3+ warn |
+| 🔴 CRITICAL | 3+ fail OR any `security-review` fail |
+
+**Actionability classification** determines what the fix loop touches:
+error/warning findings at high or medium confidence are auto-applied, and
+everything else (any `confidence: none`, and all suggestions) is report-only.
+The canonical rubric — severity × confidence → actionable — lives in the
+[review-corrections flow](triage-workflow.md#4-the-review-corrections-flow).
+
+### 6. Fix or report only?
+
+If there are zero actionable issues, skip to report generation. Otherwise the orchestrator presents a summary and asks the user:
+
+> **"Fix these issues automatically, or save as report only?"**
+
+- **Fix** → enter the review-fix loop
+- **Report only** → skip to report generation with all findings intact
+
+**Exception — non-interactive mode**: when `/code-review` runs inside `/build` or `/pr`, the prompt is skipped and the fix loop runs automatically. The caller already owns the human gate — the orchestrator's Phase 3 approval for `/build`, and the pre-PR confirmation for `/pr`.
+
+### 6a. Review-fix loop
+
+```
+iteration = 1
+while actionable_issues > 0 and iteration ≤ 5:
+    1. Apply fixes (file-by-file, top-to-bottom by line number)
+    2. Run tests; if tests fail, revert the last fix and mark it human-required
+    3. Re-run only the agents that reported actionable issues, against only the modified files
+    4. Re-aggregate: merge new results with carry-forward passes
+    5. iteration += 1
+```
+
+**Exit conditions**:
+
+| Condition | Outcome |
+| ----------- | --------- |
+| Zero actionable issues | Converged → generate report |
+| Iteration limit (5) reached | Escalate remaining issues to human |
+| Same issues persist after fix attempt | Not converging → exit and escalate |
+| Test failure after fix + revert | Mark issue human-required, continue |
+
+The final report includes a loop table showing iterations, issues fixed, and agents re-run.
+
+### 7. Generate report
+
+Output format depends on the `--json` flag:
+
+- **JSON** — a single aggregated object with overall status, per-agent results, totals, fix summary, and token estimate. Consumable by CI.
+- **Prose** — a markdown report following [`knowledge/review-template.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/review-template.md): summary table, pre-flight status, institutional context, issues by file (sorted by severity), loop iteration table, recommendations, tool availability.
+
+Remaining issues (not auto-fixed) are tagged `[confidence: none]`, `[auto-fix failed — human review required]`, or `[suggestion]`.
+
+### 8. Correction prompts
+
+For every unfixed actionable issue — plus suggestions worth addressing — a correction prompt JSON is written to `corrections/`. Each prompt includes priority, confidence, category, instruction, context, affected files, and `autoFixResult`. These can be addressed manually or with [`/apply-fixes`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/apply-fixes/SKILL.md).
+
+The full lifecycle of these files — discovery to applied fix, including who owns a `corrections/*.json` after its branch merges — is documented in [triage-workflow.md](triage-workflow.md).
+
+### 9. Pre-PR gate file
+
+When the review was auto-scoped to uncommitted changes, the final status is `pass` or `warn`, and step 6a's fix loop (if it ran) did not exit with actionable issues still outstanding, the orchestrator writes `.pr-review-passed` to `.claude/memory/` (#1886) — a SHA-256 hash of the branch's diff against its base (`git diff <base>...HEAD`), not just the staged patch — an edit or commit after review changes this hash and invalidates the gate:
+
+```bash
+HASH=$(python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/review_gate_hash.py" --branch-diff)
+mkdir -p .claude/memory && echo "$HASH" > .claude/memory/.pr-review-passed
+```
+
+Always use this shared helper, not a hand-rolled `git diff | shasum` pipeline — the helper pins several git config overrides (relative-path scoping, external diff drivers, submodule visibility) that a raw pipeline would not.
+
+**#1886: the gate moved from `git commit` to `gh pr create`.** `hooks/pre_pr_review.py` reads `.claude/memory/.pr-review-passed` at PR-creation time, bound to the branch's diff vs. its base (`branch_diff_gate_hash()`), not the staged-patch hash (`review_gate_hash()`) the retired `.review-passed` used. `hooks/pre_commit_review.py` (the former reader of `.review-passed`) is now a documented no-op, and `.review-passed` itself is no longer written by this step or read by anything.
+
+**Known limitation.** `agent_dispatch_ledger.py` still stamps every dispatch's corroborating evidence with the staged-patch hash, never the branch-diff hash. The two are identical only in the common single-commit-then-PR shape (branch cut from base, reviewed once while staged, committed, then a PR opened immediately) — a branch with multiple separate review-and-commit cycles will correctly fail this gate at `gh pr create` time and need a fresh `/code-review` run against its current diff. Closing this for every shape is tracked as a follow-up, not fixed here.
+
+### Reasoned bypass (`PR_GATE_BYPASS_REASON`)
+
+**#1886:** `git commit --no-verify`/`-n` + `GATE_BYPASS_REASON` was the
+historical bypass for the commit-time gate — both still work as ordinary git
+flags/env vars, but `hooks/pre_commit_review.py` no longer reads either, so
+they no longer gate anything at commit time.
+
+The current gate (`hooks/pre_pr_review.py`, triggered by `gh pr create`)
+requires a non-empty `PR_GATE_BYPASS_REASON` environment variable to bypass
+— `gh` has no native `--no-verify`-shaped flag, so the env var alone is both
+the trigger and the reason:
+
+```bash
+PR_GATE_BYPASS_REASON="hotfix, review to follow" gh pr create ...
+```
+
+With it set, the hook allows the PR to open and appends an accountability
+line — timestamp, branch, which mechanism triggered it, the reason,
+branch-diff file count, and plugin version — to
+`.claude/metrics/gate-bypass-audit.jsonl`, unconditionally (this log is not
+gated by `DEV_TEAM_TELEMETRY`). Same accountability posture as the original
+commit-time bypass (#709), relocated to the new trigger point (#1886).
+
+## Artifacts
+
+| Artifact | When | Purpose |
+| ---------- | ------ | --------- |
+| Stdout report (markdown or JSON) | Every run | Human or CI consumption |
+| `corrections/*.json` | When unfixed actionable or suggestion issues remain | Feeds `/apply-fixes` |
+| `.pr-review-passed` | Auto-scoped clean/warn runs | Read by `hooks/pre_pr_review.py` at `gh pr create` time (#1886 — see § 9 above) |
+| `.claude/metrics/override-audit.jsonl` | `--force --reason ...` | Audit trail for skipped gates |
+| `.claude/metrics/gate-bypass-audit.jsonl` | `gh pr create` with `PR_GATE_BYPASS_REASON` set (#1886) | Audit trail for reasoned pre-PR-gate bypasses |
+
+## Customization points
+
+| File | Location | Effect |
+| ------ | ---------- | -------- |
+| `review-config.json` | Project root | Disables specific agents per project |
+| `REVIEW-CONTEXT.md` | Project root | Injects institutional knowledge into every agent's prompt |
+| `ACCEPTED-RISKS.md` | Project root | Suppresses known findings with audit trail and expiry |
+
+All three are optional and project-local — they are not part of the plugin.
+
+## Relationship to other workflows
+
+- **Inline review checkpoints** (Phase 3 of `/build`) use the same review-fix loop mechanics, but the orchestrator selects a **targeted** subset of agents based on what changed in the unit of work. `/code-review` is the **final gate** before commit and runs the full enabled suite.
+- **[`/review-agent`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/review-agent/SKILL.md)** runs a single agent — used for targeted checks and as the worker for inline checkpoints.
+- **[`/apply-fixes`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/apply-fixes/SKILL.md)** consumes the `corrections/` directory produced here.
+- **[`/pr`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/pr/SKILL.md)** runs `/code-review --json` as part of its pre-PR quality gate. It runs non-interactively (fix loop auto-applies, no "fix or report?" prompt) and `/pr` branches on the returned status — `overall: pass/warn` or `status: skipped` proceeds, `overall: fail` re-engages the user.
+
+## Concurrent use
+
+The `.pr-review-passed` gate is a single, gitignored file per working tree, so two
+agents sharing **one** checkout overwrite each other's gate. Give each
+concurrent agent its own git worktree — the full rationale and setup are in
+[concurrent-use.md](concurrent-use.md).
+
+## References
+
+- [Skill spec](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/code-review/SKILL.md) — operational detail for the orchestrator
+- [Triage workflow](triage-workflow.md) — the discovery-to-applied-fix lifecycle: `/triage`, correction prompts, `/apply-fixes`, and leftover-corrections ownership
+- [Concurrent use](concurrent-use.md) — one worktree per agent; why the gate is per-checkout
+- [Output format](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/code-review/output-format.md) — per-agent JSON, aggregated JSON, correction prompts
+- [Report template](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/review-template.md) — prose report structure
+- [Scoring rubric](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/review-rubric.md) — health scoring and severity mapping
+- [Agent catalog](agent_info.md) — list of review agents and what each checks
+- [Architecture](agent-architecture.md) — where `/code-review` fits in the three-phase workflow

package/docs/upstream/concurrent-use.md

@@ -0,0 +1,73 @@
+# Concurrent use — multiple agents or people on one repo
+
+Short version: **the normal team workflow is safe; for two *agents* on one
+machine, give each its own git worktree.**
+
+This resolves the concurrency question (#109) for the per-checkout state in
+the table below: the plugin **documents** a safe pattern rather than
+enforcing locks there, because git worktrees already solve the problem
+cleanly. Separately, a handful of small on-disk state files that a single
+worktree's own hooks read-modify-write or append to — session/retry counters
+(`bash_retry_guard.py`, `session_learning_trigger.py`), and four of the
+`.claude/metrics/*.jsonl` telemetry streams (`boundary-events.jsonl`,
+`workflow-states.jsonl`, `iteration-journal.jsonl`, and an `/autoship`
+round log) — *are* lock-serialized (`hooks/lib/atomic_state.py`,
+#1501/#1874/#1889). Those races are within one worktree, between concurrent
+tool calls or sliced-mode parallel dispatches, not the cross-worktree case
+this doc is about. Other `.claude/metrics/*.jsonl` streams are not yet
+converted (#1896).
+
+## Why the normal case is already safe
+
+The plugin's local coordination state is per-checkout, not shared:
+
+| State | Where | Shared across checkouts? |
+| --- | --- | --- |
+| Review gate `.pr-review-passed` | `.claude/memory/`, **gitignored** | No — local to each working tree |
+| Plan / build progress | `plans/<name>.md` (**tracked**) | Merges through normal git |
+
+So two developers, each with their **own clone**, never collide on these — and
+plan files reconcile the way any tracked file does. "Designed for teams" holds
+for the standard one-checkout-per-person workflow.
+
+## The unsafe case: two agents sharing ONE working tree
+
+Two background agents, two terminals in the same directory, or a human and an
+agent in the same checkout share **one** `.git/index` and **one** set of local
+state files. That is where collisions occur (reproduced in
+[`../../../tests/repo/test_multiplayer_collision.py`](https://github.com/bdfinst/agentic-dev-team/blob/main/tests/repo/test_multiplayer_collision.py),
+characterized in issue #109):
+the shared `.pr-review-passed` gets overwritten (false blocks) and the staged
+set interleaves.
+
+## The rule: one worktree per agent
+
+Use a separate [git worktree](https://git-scm.com/docs/git-worktree) for each
+concurrent agent. Each worktree has its own working directory, its own index,
+and its own gitignored local state — so the agents never share a gate or a
+staging area, while still sharing one clone's history and branches.
+
+```bash
+# From your main checkout, create an isolated worktree per task/agent:
+git worktree add ../myrepo-feature-a feature-a
+git worktree add ../myrepo-feature-b feature-b
+
+# Run each agent in its own worktree directory. When done:
+git worktree remove ../myrepo-feature-a
+```
+
+Guidance:
+
+- **One agent (or session) per worktree.** Don't point two agents at the same
+  directory.
+- Worktrees are cheap (they share the object store) — make one per parallel task.
+- The review gate, model overrides, and staged set are now per-worktree, so the
+  collisions above cannot occur.
+
+## Known limitation (separate from concurrency)
+
+The review gate currently binds to staged **paths**, not **content**, so editing
+a file's content after review can commit it unreviewed even for a single user.
+That is an independent correctness bug tracked in **#193** — fixing it (hash the
+staged patch) also hardens the shared-tree case, but the worktree rule above is
+the recommended isolation regardless.