devflow-kit 3.9.0 → 3.11.0

package/dist/compliance-off/commands/code-review.md

@@ -0,0 +1,520 @@
+---
+description: Comprehensive branch review using specialized sub-agents for PR readiness
+---
+# Code Review Command
+
+Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing results into a local review summary.
+
+## Usage
+
+```
+/code-review           (review current branch — or all worktrees if multiple found)
+/code-review #42       (review specific PR)
+/code-review --full    (force full-branch review, ignore previous review state)
+/code-review --path /path/to/worktree  (review a specific worktree only)
+```
+
+## Phases
+
+### Phase 0: Worktree Discovery & Pre-Flight
+
+#### Step 0a: Discover Worktrees
+
+**Produces:** WORKTREES
+
+1. **Discover reviewable worktrees**:
+   - Run `git worktree list --porcelain` and count the worktrees it lists
+   - **More than one listed:** Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill. Parse the list, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - **Exactly one listed:** load neither the skill nor the reference — that worktree is the only candidate, and Step 0c's Git agent validates its branch
+2. **If `--path` flag provided:** use only that worktree, skip discovery
+   **`--path` validation**: the path must be a directory in `git worktree list` output; if not, report an error and stop.
+3. **If only 1 reviewable worktree**: proceed as single-worktree flow
+4. **If multiple reviewable worktrees:** report "Found N worktrees with reviewable branches: {list with paths and branches}" and proceed with multi-worktree flow
+
+#### Step 0b: Resolve the compliance lens and gate level
+
+**Produces:** COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS, GATE_LEVEL
+
+**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root in a one-worktree run:
+
+```bash
+node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
+```
+
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
+
+The accepted line is the only source of these values.
+
+**Resolve the compliance lens** for each worktree root, from its settings line — the line resolved above for that root, by the settings block when this run has not yet resolved it (every framework reference is installed on every machine, so no file check decides it).
+
+**Set the compliance lens** from that line: `COMPLIANCE_FRAMEWORKS` is the settings line's `COMPLIANCE` with `generic` written `none`: `off`, `none`, or the framework ids the machine and this repository declare.
+
+`COMPLIANCE_ACTIVE` is `true` unless `COMPLIANCE_FRAMEWORKS` is `off`.
+Keep each worktree's values for every downstream phase.
+
+#### Step 0b-ii: Resolve the evidence policy
+
+**Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
+
+**Resolve the evidence policy once per run**, from the repository root, before any step reads the values:
+
+```bash
+node "$HOME/.devflow/scripts/resolve-evidence-policy.cjs" 2>/dev/null; echo "exit=$?"
+```
+
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name such as `main`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
+
+Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AUTHOR_APPROVAL` from the accepted line. Pass agents only the three mechanism inputs, never `EVIDENCE_POLICY`. Report `Evidence policy: {EVIDENCE_POLICY} (source: {SOURCE})`, plus any `WARN` tokens as advisory, once in the final report.
+When `EVIDENCE_POLICY` is `required`, record `TRACEABILITY: DEGRADED (compliance off on this machine; the repository requires evidence)` once, for the Phase 4 report.
+
+#### Step 0c: Per-Worktree Pre-Flight (Git Agent)
+
+**Produces:** BRANCH_INFO, PR_INFO, PR_DESCRIPTION, PR_DESCRIPTION_GUIDANCE
+**Requires:** WORKTREES
+
+Discover PR description guidance from plan artifact (per worktree):
+1. List the design plans: `{worktree}/.devflow/docs/design/*.md` (a `/plan` artifact) and `{worktree}/.devflow/docs/design/*/*/*-plan.md` (a `/dynamic-plan` per-ticket plan)
+2. Sort by timestamp, newest first, and scan the 10 most recent. A `/plan` artifact's timestamp is the `YYYY-MM-DD_HHMM` before its `.md`; a per-ticket plan's is the name of its parent directory. Never sort by file name, which starts with an issue ID or a ticket slug. A per-ticket plan counts only when its `{ticket-slug}` (its file name without `-plan.md`) appears in the worktree's branch name
+3. Read the most recent file that carries the section, extract `## PR Description Guidance` section
+4. If no plan files exist or section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`
+
+For each reviewable worktree, spawn Git agent:
+
+```
+Agent(subagent_type="Git", run_in_background=false):
+"OPERATION: ensure-pr-ready
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
+Validate branch, commit if needed, push, create PR if needed.
+Return: branch, base_branch, base_ref, branch-slug, PR#"
+```
+
+In multi-worktree mode, spawn all pre-flight agents **in a single message**.
+
+**If BLOCKED:** In single-worktree mode, stop and report. In multi-worktree mode, report the failure but continue with other worktrees.
+
+**Extract from response:** `branch`, `base_branch`, `base_ref`, `branch_slug`, `pr_number` per worktree. Stop with cause and fix when the Base line reads (rejected) or `branch_slug` does not match the slug pattern above; name the Git agent's fix, never your own, and for the slug the allowed characters, never its value. In multi-worktree mode this blocks only that worktree.
+
+**Fetch PR body** (after extracting `pr_number`):
+```bash
+PR_DESCRIPTION=$(gh pr view {pr_number} --json body --jq '.body' 2>/dev/null || echo "(none)")
+```
+If `pr_number` is absent, set `PR_DESCRIPTION` to `(none)`.
+
+#### Step 0d: Incremental Detection & Timestamp Setup
+
+**Produces:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP
+**Requires:** BRANCH_INFO
+
+For each worktree:
+
+1. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`).
+2. Check if `{gd}/devflow/reviews/{branch-slug}/.last-review-head` exists, `{gd}` being what `git -C "{worktree}" rev-parse --absolute-git-dir` prints:
+   - **If yes AND `--full` NOT set:**
+     - The stored review head is checked as a commit ID: use it only when it is exactly 40 or 64 lowercase hex, else take the full-range path
+     - Verify reachable: `git -C "{worktree}" cat-file -t {sha}` must print `commit` (else take the full-range path)
+     - Check if SHA == current HEAD → if so, skip review: "No new commits since last review. Use --full for a full re-review."
+     - Set `DIFF_RANGE` to `{last-review-sha}...HEAD`
+   - **Full-range path (no marker, or `--full`):**
+     - Stop as for a (rejected) Base line unless `base_ref` is 40 or 64 hex.
+     - Set `DIFF_RANGE` to `{base_ref}...HEAD`
+3. Create timestamped review directory: `mkdir -p {worktree}/.devflow/docs/reviews/{branch-slug}/{timestamp}/`
+
+#### Step 0e-i: Load Prior Resolution and Count Cycles
+
+**Produces:** PRIOR_RESOLUTIONS, CYCLE_NUMBER
+**Requires:** BRANCH_INFO
+
+For each worktree:
+1. List the timestamped directories: `ls -1d {worktree}/.devflow/docs/reviews/{branch-slug}/20* 2>/dev/null | sort -r`
+2. Iterate once: count each directory containing `resolution-summary.md` as CYCLE_NUMBER; capture the first (newest) as PRIOR_DIR.
+3. If CYCLE_NUMBER = 0: set PRIOR_RESOLUTIONS=(none), CYCLE_NUMBER=1, proceed.
+4. Otherwise: set CYCLE_NUMBER = count + 1. Read `{PRIOR_DIR}/resolution-summary.md` as PRIOR_RESOLUTIONS minus each section from a heading line (fenced or not) with the word `Private` (any case) not followed by a letter or digit, to the next unfenced heading with as many `#` as its start or fewer, else at end of file. Close any fence it leaves open. When unsure, cut more; if the cut fails, PRIOR_RESOLUTIONS=(none).
+5. If `--full`: still load PRIOR_RESOLUTIONS.
+
+#### Step 0e-ii: Convergence Assessment
+
+**Produces:** (refines CYCLE_NUMBER)
+**Requires:** PRIOR_RESOLUTIONS, BRANCH_INFO
+
+MAX_REVIEW_CYCLES = 10
+
+1. If CYCLE_NUMBER > MAX_REVIEW_CYCLES:
+   Warn in output: "⚠️ Review pipeline has run {CYCLE_NUMBER-1} cycles (exceeds MAX_REVIEW_CYCLES=10). Consider merging or manual inspection."
+   Continue with review.
+2. Parse Statistics table from PRIOR_RESOLUTIONS:
+   - Extract False Positive, Fixed, Deferred counts
+   - `deferred_count` = the Deferred row value (= FIX_SEPARATE + TECH_DEBT); By Design and Escalated are excluded from the fp_ratio denominator
+   - fp_ratio = fp_count / (fp_count + fixed_count + deferred_count)
+   - If denominator = 0: fp_ratio = 0, skip warning
+   - If parsing fails: fp_ratio = 0, skip warning; note in output: "Warning: Could not parse Statistics table. Convergence tracking degraded."
+3. If fp_ratio > 0.7 AND CYCLE_NUMBER >= 3:
+   Warn in output: "⚠️ Convergence: {ratio}% false positives in cycle {N-1}. Consider merging or manual inspection."
+   Continue with review.
+
+**Decision table — Step 0e-ii paths:**
+
+| Condition | Outcome |
+|-----------|---------|
+| CYCLE_NUMBER > MAX_REVIEW_CYCLES | Warn in output, continue |
+| denominator = 0 OR parsing failed | fp_ratio = 0, skip warning (degraded note on parse failure) |
+| fp_ratio > 0.7 AND CYCLE_NUMBER >= 3 | Warn in output, continue |
+
+### Phase 1: Analyze Changed Files
+
+**Produces:** REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
+**Requires:** DIFF_RANGE, REVIEW_DIR, COMPLIANCE_ACTIVE, GATE_LEVEL (from Step 0b)
+
+Per worktree, in order. Each `git` command here writes to a file and prints nothing.
+
+#### Step 1.1: Classify the diff
+
+**Produces:** DIFF_CLASS, CHANGED_PATHS, REVIEW_FOCUS_LIST (reduced classes)
+**Requires:** DIFF_RANGE, REVIEW_DIR
+
+List the changed paths into `{REVIEW_DIR}/paths.txt` and print only the line count (drop `-C "{WORKTREE_PATH}"` when there is no `WORKTREE_PATH`):
+
+```bash
+git -C "{WORKTREE_PATH}" diff --name-only --no-renames {DIFF_RANGE} > "{REVIEW_DIR}/paths.txt"
+echo "exit=$?"
+wc -l < "{REVIEW_DIR}/paths.txt"
+```
+
+The `exit=` line is the diff's. A non-zero diff exit stops. Read `paths.txt` once when the count is about 40 or fewer, and in ranges of about 40 lines (Read with offset and limit) when it is more.
+
+Set `DIFF_CLASS` by these rules, in order; the first that decides wins:
+
+1. **Instruction and config paths are `code`.** Any changed path that is `CLAUDE.md`, `AGENTS.md`, under `.claude/` or `src/assets/`, a `*.mds` file, under a plugin's `agents/`, `skills/` or `commands/` directory, `.devflow/project.json`, `.devflow/conventions.md`, or a manifest or build file (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `requirements*.txt`, `CMakeLists.txt`). This rule runs first, so a diff made only of such files is `code` and never `docs-only`.
+2. **`docs-only`.** Every changed path matches `*.md`, `*.mdx`, `*.rst`, `*.txt`, `docs/**` or `CHANGELOG*`.
+3. **`tests-only`.** Every changed path matches `tests/**`, `**/__tests__/**`, `*.test.*`, `*.spec.*`, `*_test.go`, `test_*.py` or `*_test.py`.
+4. **`lockfile-only`.** Every changed path is `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, `Cargo.lock`, `go.sum`, `poetry.lock`, `uv.lock`, `Gemfile.lock` or `composer.lock`.
+5. **Mixed non-code.** Every changed path matches the docs, tests or lockfile patterns, but no single rule above holds (docs with tests, tests with a lockfile): `DIFF_CLASS` names each class involved.
+6. **Fail-safe is `code`.** A changed path that matches no class pattern makes the diff `code`, and so does an empty path list. A manifest change is `code` and never `lockfile-only`.
+
+Each reduced class runs only its focus set, every member reading `diff.patch`:
+
+- `docs-only`: documentation, consistency, security
+- `tests-only`: testing, reliability, consistency, security
+- `lockfile-only`: dependencies, security
+
+A mixed non-code diff runs the union of the sets of the classes it holds. Language and conditional triggers inside a reduced class are suppressed.
+
+#### Step 1.2: Choose the focuses
+
+**Produces:** REVIEW_FOCUS_LIST (code class)
+**Requires:** DIFF_CLASS, CHANGED_PATHS, COMPLIANCE_ACTIVE
+
+When `DIFF_CLASS` is `code`, read the file types from the paths in `paths.txt` to determine conditional reviews:
+
+| Condition | Adds Review |
+|-----------|-------------|
+| Any .ts or .tsx files | typescript |
+| .tsx or .jsx files (React components) | react |
+| .tsx or .jsx files (React components) | accessibility |
+| .tsx/.jsx/.css/.scss files | ui-design |
+| .go files | go |
+| .java files | java |
+| .py files | python |
+| .rs files | rust |
+| DB/migration files | database |
+| Dependency files changed | dependencies |
+| Docs or significant code | documentation |
+| COMPLIANCE_ACTIVE AND diff touches regulated surface | compliance |
+
+If `COMPLIANCE_ACTIVE` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): on a `code` diff, add `compliance`.
+
+**Language focus stamp.** The eight language focuses — `typescript`, `react`, `accessibility`, `ui-design`, `go`, `java`, `python`, `rust` — ship with optional plugins, and the installer stamps the ones installed on this machine onto this line, rewriting it on every install and on `uninstall --plugin`:
+
+Installed language focuses: (none)
+
+A language focus is spawned only when its file-type condition above fires AND its name appears in that stamped line. A focus missing from the line is never spawned, even when its trigger fires. On a `code` diff, REVIEW_FOCUS_LIST starts with the eight core focuses. Step 1.2b may narrow them; they are never stamp-gated.
+
+#### Step 1.2b: Narrow by gate level
+
+**Produces:** REVIEW_FOCUS_LIST, GATE_LEVEL
+**Requires:** REVIEW_FOCUS_LIST, DIFF_CLASS, CHANGED_PATHS, GATE_LEVEL
+
+**Gate level.** Narrow REVIEW_FOCUS_LIST, for every class, by this worktree's `GATE_LEVEL`. `full` keeps it and reads nothing.
+
+At `standard` or `lean`, once per run, run `d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"` in Bash and Read `<that directory>/skills/devflow:agent-references/references/commands/code-review-levels.md` with the Read tool.
+
+- Apply each class's row to that class's own set, then take the union of the results. A row only removes focuses.
+- If the Read fails, or a row is missing or malformed, set `GATE_LEVEL` to `full` for every worktree of this run and say `level reference unreadable: full sets applied`.
+- Security runs at every level and in every class.
+- Compliance keeps the trigger above at every level.
+
+#### Step 1.3: Write the diff files
+
+**Produces:** DIFF_FILES
+**Requires:** DIFF_RANGE, REVIEW_DIR, REVIEW_FOCUS_LIST
+
+Write `diff.patch` once per worktree, by redirect:
+
+```bash
+git -C "{WORKTREE_PATH}" diff --no-color --no-ext-diff --no-textconv {DIFF_RANGE} > "{REVIEW_DIR}/diff.patch"
+```
+
+It holds the whole diff of `DIFF_RANGE`. A non-zero exit of any patch write stops. On a `code` diff, add one patch for each language focus in REVIEW_FOCUS_LIST, by the same command with quoted pathspecs from this table:
+
+```bash
+git -C "{WORKTREE_PATH}" diff --no-color --no-ext-diff --no-textconv {DIFF_RANGE} -- '<pathspec>' ... > "{REVIEW_DIR}/diff-{focus}.patch"
+```
+
+| Focus | Pathspecs |
+|-------|-----------|
+| typescript | `'*.ts' '*.tsx'` |
+| react, accessibility | `'*.tsx' '*.jsx'` |
+| ui-design | `'*.tsx' '*.jsx' '*.css' '*.scss'` |
+| go | `'*.go'` |
+| java | `'*.java'` |
+| python | `'*.py'` |
+| rust | `'*.rs'` |
+
+The core, database, dependencies, documentation and compliance focuses, and every reduced-class focus, read `diff.patch`. A language focus sees only its own extensions and reaches anything else through `DIFF_RANGE`. Set `DIFF_FILES` to the files written. They live in `REVIEW_DIR`, under the gitignored `.devflow/` tree, with `paths.txt`: never committed, posted or passed to the Git agent.
+
+### Phase 1b: Load Decisions Index
+
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, COMPLIANCE_FRAMEWORKS (carried from Step 0b)
+
+### Load DECISIONS_CONTEXT
+
+When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
+
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+
+```bash
+git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
+```
+
+Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
+
+1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
+2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
+3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
+
+This is the rule the curation hooks apply, so you read the index the Curate agent writes.
+
+**Step 1 — Read the pre-rendered index:**
+
+Attempt to read `{ledger}/.devflow/curation/index.md`.
+
+- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
+- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+
+The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
+
+**Step 2 — Slice the index, then hand it on:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
+
+Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
+
+Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
+
+This produces a compact index of active ADR/PF entries. Pass `DECISIONS_CONTEXT` to all Review agents as one shared slice, cut over the diff's files. Review agents use `devflow:apply-decisions` to Read full entry bodies on demand.
+
+### Load Feature Knowledge
+
+Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the index cache:**
+
+Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
+
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
+
+**Step 3 — Pick relevant KBs:**
+
+Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+
+**Step 4 — Read each selected KB's Rules:**
+
+For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
+
+1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
+3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
+
+When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
+
+**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+
+Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
+
+```
+--- Feature knowledge: {slug} ---
+KB: .devflow/features/{slug}/KNOWLEDGE.md
+Rules:
+- **KB-AP-2** {bullet text, verbatim}
+- **KB-INV-1** {bullet text, verbatim}
+Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
+```
+
+A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
+
+**One git call, then direct reads — no `.cjs` script.**
+
+Pass `FEATURE_KNOWLEDGE` to all Review agents alongside `DECISIONS_CONTEXT`.
+
+### Phase 2: Run Reviews (Parallel)
+
+**Produces:** REVIEW_FOCUS_OUTPUTS
+**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION, PRIOR_RESOLUTIONS, REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
+
+Spawn Review agents **in a single message**, one per focus in REVIEW_FOCUS_LIST (max 20 per worktree):
+
+- `code`: the 8 core reviews on the full `diff.patch` (lean keeps 3), plus the language and conditional focuses Phase 1 added.
+- `docs-only`, `tests-only`, `lockfile-only`: only the reduced set Phase 1 names, each reading `diff.patch`; a mixed non-code diff runs the union. No language or conditional focus is spawned, whatever its trigger.
+
+| Focus | Runs | Pattern Skill | DIFF_FILE |
+|-------|------|---------------|-----------|
+| security | ✓ | devflow:security | diff.patch |
+| architecture | ✓ | devflow:architecture | diff.patch |
+| performance | ✓ | devflow:performance | diff.patch |
+| complexity | ✓ | devflow:complexity | diff.patch |
+| consistency | ✓ | devflow:consistency | diff.patch |
+| regression | ✓ | devflow:regression | diff.patch |
+| testing | ✓ | devflow:testing | diff.patch |
+| reliability | ✓ | devflow:reliability | diff.patch |
+| typescript | stamp-gated | devflow:typescript | diff-typescript.patch |
+| react | stamp-gated | devflow:react | diff-react.patch |
+| accessibility | stamp-gated | devflow:accessibility | diff-accessibility.patch |
+| ui-design | stamp-gated | devflow:ui-design | diff-ui-design.patch |
+| go | stamp-gated | devflow:go | diff-go.patch |
+| java | stamp-gated | devflow:java | diff-java.patch |
+| python | stamp-gated | devflow:python | diff-python.patch |
+| rust | stamp-gated | devflow:rust | diff-rust.patch |
+| database | conditional | devflow:database | diff.patch |
+| dependencies | conditional | devflow:dependencies | diff.patch |
+| documentation | conditional | devflow:documentation | diff.patch |
+| compliance | diff-driven | devflow:compliance | diff.patch |
+
+Review agent count: `code` runs 8 core +1-12 at `full`, up to 2 fewer at `standard`, 3-4 at lean; a reduced class or a mix runs 2-6.
+
+**Set the compliance focus directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_FOCUS_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`; only the compliance focus's spawn carries it:
+
+> For this compliance focus, invoke Skill(skill="devflow:compliance") and load references/{id}.md only for the ids in <ids> (none: generic controls only); never fabricate guidance for a framework you were not given.
+
+Each Review agent invocation (all in one message, **NOT background**):
+```
+Agent(subagent_type="Review", run_in_background=false):
+"Review focusing on {focus}. Load the pattern skill via the Skill tool: Skill(skill="devflow:{focus}").
+Follow 6-step process from devflow:review-methodology.
+PR: #{pr_number}, Base: {base_branch}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+DIFF_FILE: {diff_file}  (absolute: {REVIEW_DIR}/diff.patch, or {REVIEW_DIR}/diff-{focus}.patch for a language focus, per the table)
+DIFF_RANGE: {DIFF_RANGE}  (information only)
+DECISIONS_CONTEXT: {decisions_context}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
+PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
+{COMPLIANCE_FOCUS_DIRECTIVE}  (compliance focus only)
+If PRIOR_RESOLUTIONS is not (none), follow Cross-Cycle Awareness in review.md.
+Follow devflow:apply-decisions to scan the index and Read full ADR/PF bodies on demand.
+Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE — feature-specific patterns and anti-patterns inform findings.
+IMPORTANT: Write report to {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/{focus}.md using Write tool"
+```
+
+In multi-worktree mode, process worktrees **sequentially**: Phases 1-4 for each.
+
+### Phase 3: Synthesis → Review Summary (Sequential)
+
+**Produces:** REVIEW_SUMMARY
+**Requires:** REVIEW_FOCUS_OUTPUTS, REVIEW_DIR, PR_INFO, GATE_LEVEL, REVIEW_FOCUS_LIST
+
+**WAIT** for Phase 2. For each worktree, run step 3a:
+
+**Step 3a — Synthesize agent** per worktree:
+```
+Agent(subagent_type="Synthesize", run_in_background=false):
+"Mode: review
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+REVIEW_BASE_DIR: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}
+TIMESTAMP: {timestamp}
+CYCLE_NUMBER: {cycle_number}
+GATE_LEVEL: {GATE_LEVEL}
+FOCUSES: {REVIEW_FOCUS_LIST}
+PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
+Include Convergence Status section in review-summary.md.
+Aggregate findings, determine merge recommendation.
+Output: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md"
+```
+
+### Phase 4: Write Review Head Marker & Report
+
+**Requires:** BRANCH_INFO, REVIEW_DIR
+
+Per worktree, after successful completion:
+1. In one Bash call run `M="$(git -C "{worktree_path}" rev-parse --absolute-git-dir)/devflow/reviews/{branch-slug}" && mkdir -p "$M" && git -C "{worktree_path}" rev-parse HEAD > "$M/.last-review-head"`. A failed or refused write never stops the run and is not retried another way.
+2. Display results from all agents:
+   - Merge recommendation (from Synthesize agent)
+   - Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing)
+   - Review summary: `.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md` (local; not posted)
+   - Any base `TRACEABILITY: DEGRADED` line from Step 0c, as returned, and the compliance-off line of Step 0b-ii
+   - Artifact paths
+
+## Architecture
+
+```
+/code-review
+│
+├─ Phase 0: Worktree Discovery & Pre-flight, Steps 0a-0e (Git agent per worktree, parallel)
+│  ├─ Step 0b: Resolve the compliance lens and gate level
+│
+├─ Per worktree (SEQUENTIAL):
+│  │
+│  ├─ Phase 1: Analyze changed files
+│  │  ├─ Classify the diff (paths.txt → DIFF_CLASS)
+│  │  ├─ Choose the focuses
+│  │  └─ Write diff.patch and diff-{focus}.patch
+│  │
+│  ├─ Phase 2: Reviews (PARALLEL within worktree), one per REVIEW_FOCUS_LIST focus
+│  │  ├─ code: core (diff.patch), language (diff-{focus}.patch), conditional
+│  │  └─ docs-only / tests-only / lockfile-only: the reduced set (diff.patch)
+│  │
+│  ├─ Phase 3: Synthesis → Review Summary (SEQUENTIAL within worktree)
+│  │  └─ Step 3a: Synthesize agent (mode: review, writes review-summary.md)
+│  │
+│  └─ Phase 4: Write .last-review-head + display results
+```
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| `--full` in multi-worktree mode | Applies to all worktrees (global modifier). It sets the diff range, never the gate level |
+| Docs-only diff | Its Step 1.1 set, narrowed by level |
+| Tests-only diff | Its Step 1.1 set, narrowed by level |
+| Lockfile-only diff | Its Step 1.1 set, narrowed by level |
+| Mixed non-code diff | The union of the matching sets |
+| A path matching no class pattern, or an empty path list | `code` (fail-safe) |
+| A file moved across classes | `--no-renames` lists both paths, so a code path makes the diff `code` |
+| Path listing above about 40 lines | Read in ranges (Step 1.1) |
+| Language files changed, plugin not installed | The focus is absent from the stamped line: not spawned |
+
+## Backwards Compatibility
+
+- **Gate level**: `full` runs the sets named here; the default `standard` and `lean` narrow them. `devflow gates --set full` keeps them.
+
+## Principles
+
+1. **Orchestration only** - Command spawns agents, doesn't do git/review work itself. The exceptions are the read-only Phase 0 probes (`git worktree list`, `git -C ... branch --show-current`, `git -C ... cat-file -t`, `git -C ... rev-parse`), the bounded Phase 1 path listing and the writes (`diff.patch`, `diff-{focus}.patch`, the marker and its `mkdir -p`). These writes print nothing
+2. **Parallel, not background** - Multiple agents in one message, but `run_in_background=false` so phases complete before proceeding
+3. **Git agent for git work** - All git operations go through Git agent, except the exceptions named in Principle 1; its writes print nothing
+4. **Honest reporting** - Display agent outputs directly
+5. **Incremental by default** - Only review new changes unless `--full` specified