devflow-kit 3.3.0 → 3.4.0

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

@@ -0,0 +1,525 @@
+---
+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 PR comments. Supports incremental reviews, timestamped report directories, and multi-worktree auto-discovery.
+
+## 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** using the `devflow:worktree-support` skill discovery algorithm:
+   - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - 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
+2. **If `--path` flag provided:** use only that worktree, skip discovery
+   **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
+3. **If only 1 reviewable worktree** (the common case): proceed as single-worktree flow — zero behavior change
+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
+
+**Produces:** COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS
+
+**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 when the run has one worktree:
+
+```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> LEARNING=<on|off> KNOWLEDGE=<on|off>` — 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=on LEARNING=on KNOWLEDGE=off` instead.
+
+The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+
+**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 of that worktree.
+
+#### 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.
+
+#### 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 `{worktree}/.devflow/docs/design/*.md` files
+2. Sort by timestamp in filename (descending -- timestamps are YYYY-MM-DD_HHMM, naturally sortable)
+3. Read the most recent file, extract `## PR Description Guidance` section
+4. If no plan files exist or section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`
+
+Render the test-plan block (per worktree) from `/implement`'s evidence file, and from nothing else:
+1. `branch_slug` is `git -C "{worktree}" branch --show-current` with every `/` replaced by `-`.
+2. Only when `branch_slug` matches `^[A-Za-z0-9._-]{1,200}$` and the file exists, run (the path double-quoted):
+
+```bash
+node "$HOME/.devflow/scripts/verify-evidence.cjs" render --plan "{worktree}/.devflow/docs/evidence-{branch_slug}.md"; echo "exit=$?"
+```
+
+3. On `exit=0`, `PR_TEST_PLAN_BLOCK` is its stdout byte for byte without that `exit=` line; in every other case it is `(none)`. Nothing here waits on it: the Git agent pastes it only behind its own check, and only into a PR it creates.
+
+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}
+PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
+Validate branch, commit if needed, push, create PR if needed.
+Return: branch, base_branch, branch-slug, PR#"
+```
+
+In multi-worktree mode, spawn all pre-flight agents **in a single message** (parallel).
+
+**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`, `branch_slug`, `pr_number` per 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 or the command fails, 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. Create timestamped review directory: `mkdir -p {worktree}/.devflow/docs/reviews/{branch-slug}/{timestamp}/`
+3. Check if `{worktree}/.devflow/docs/reviews/{branch-slug}/.last-review-head` exists:
+   - **If yes AND `--full` NOT set:**
+     - Read the SHA from the file
+     - Verify reachable: `git -C {worktree} cat-file -t {sha}` (handles rebases — if unreachable, fallback to full)
+     - 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`
+   - **If no (first review), or `--full`:**
+     - Set `DIFF_RANGE` to `{base_branch}...HEAD`
+
+#### Step 0e-i: Load Prior Resolution and Count Cycles
+
+**Produces:** PRIOR_RESOLUTIONS, CYCLE_NUMBER
+**Requires:** BRANCH_INFO
+
+For each worktree, perform a single pass over timestamped directories:
+1. List timestamped directories in `{worktree}/.devflow/docs/reviews/{branch-slug}/` sorted descending: `ls -1d {worktree}/.devflow/docs/reviews/{branch-slug}/20* 2>/dev/null | sort -r`
+2. Iterate once: accumulate CYCLE_NUMBER count for each directory containing `resolution-summary.md`; capture the first (most-recent) such directory 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.
+5. If `--full`: still load PRIOR_RESOLUTIONS (valuable for Review agent cross-cycle awareness).
+
+#### 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 from prior resolution. FP ratio unavailable — 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 |
+
+#### Step 0f: Resolve Publication Mode (Per Worktree)
+
+**Produces:** REVIEW_PUBLICATION
+**Requires:** WORKTREES, EVIDENCE_POLICY
+
+For each reviewable worktree, call:
+
+**Resolve `REVIEW_PUBLICATION` per worktree:** take `REVIEW_PUBLICATION` from that worktree's settings line — the line resolved above for `{root}`, the worktree's root, by the settings block when this run has not yet resolved that root; multi-worktree repos may resolve different values per worktree. The line already caps the personal choice at the team's (D-PUBLICATION-CEILING), so it is `off`, `auto` or `full`, and `off` when the line was unresolvable.
+
+**Evidence stub:** only when `EVIDENCE_POLICY` is `required`, a resolved `off` becomes `stub`, so a counts-only record still reaches the PR. `stub` is never a config value: the settings line never carries it.
+
+Note: `auto` is NOT fail-open — under `auto`, the Git agent probes the repository visibility and treats any error or unrecognised value as PUBLIC (mode STUB). What each value does is decided by the Git agent's publication gate (`references/publication-gate.md` step 2); this partial only resolves the value.
+
+### Phase 1: Analyze Changed Files
+
+**Produces:** REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
+**Requires:** DIFF_RANGE, REVIEW_DIR, COMPLIANCE_ACTIVE (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"
+wc -l < "{REVIEW_DIR}/paths.txt"
+```
+
+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. `--no-renames` lists a moved file under its old path and its new one, so a move cannot take a file out of its own class.
+
+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: they add no focus, and Step 1.2 applies to the `code` class only.
+
+#### 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): add `compliance` to REVIEW_FOCUS_LIST for this worktree.
+
+**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. The eight core focuses are unconditional and are never stamp-gated.
+
+#### 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`. 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 Context
+
+**Produces:** FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, COMPLIANCE_FRAMEWORKS (carried from Step 0b)
+
+### 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). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+
+**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.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+
+Pass `FEATURE_KNOWLEDGE` to all Review agents.
+
+### Phase 2: Run Reviews (Parallel)
+
+**Produces:** REVIEW_FOCUS_OUTPUTS
+**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, FEATURE_KNOWLEDGE, PR_DESCRIPTION, PRIOR_RESOLUTIONS, REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
+
+Spawn Review agents **in a single message**, for the focus set `DIFF_CLASS` selects (max 20 per worktree):
+
+- `code`: the 8 core reviews on the full `diff.patch`, 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 added by Phase 1 (max 20 total per worktree); a reduced class or a mix runs 2-6.
+
+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)
+FEATURE_KNOWLEDGE: {feature_knowledge}
+PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
+PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
+COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}  (compliance focus only)
+If PRIOR_RESOLUTIONS is not (none), follow Cross-Cycle Awareness in review.md.
+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** (one worktree at a time). Complete Phases 1-4 for each worktree before starting the next. This prevents agent overload — spawning 8-20 Review agents per worktree across multiple worktrees simultaneously overwhelms the system.
+
+### Phase 3: Synthesis → Review Comment (Sequential)
+
+**Produces:** REVIEW_SUMMARY, PR_COMMENT
+**Requires:** REVIEW_FOCUS_OUTPUTS, REVIEW_DIR, PR_INFO
+
+**WAIT** for Phase 2. For each worktree, run steps 3a and 3b in sequence:
+
+**Step 3a — Synthesize agent** per worktree (wait for completion before 3b):
+```
+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}
+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"
+```
+
+**Step 3b — Git agent (post-review-summary)** per worktree (after Step 3a writes review-summary.md):
+```
+Agent(subagent_type="Git", run_in_background=false):
+"OPERATION: post-review-summary
+PR_NUMBER: {pr_number}
+REVIEW_SUMMARY_PATH: .devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md
+CYCLE_NUMBER: {cycle_number}
+REVIEW_TIMESTAMP: {timestamp}
+REVIEW_PUBLICATION: {REVIEW_PUBLICATION}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+Posts the consolidated review-summary comment (marker-deduped by the operation on the cycle+timestamp pair)."
+```
+
+### Phase 4: Write Review Head Marker & Report
+
+**Requires:** BRANCH_INFO, REVIEW_DIR
+
+Per worktree, after successful completion:
+1. Write current HEAD SHA to `{worktree_path}/.devflow/docs/reviews/{branch-slug}/.last-review-head`
+2. Display results from all agents:
+   - Merge recommendation (from Synthesize agent)
+   - Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing)
+   - Review comment status: POSTED / POSTED+TRUNCATED (body exceeded 60k after redaction) / SKIPPED (D7 dedup) / DEGRADED (from Git)
+   - Publication status: FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config) | STUB (visibility undeterminable) | STUB (evidence policy) (from Git agent)
+   - Artifact paths
+
+In multi-worktree mode, report results per worktree.
+
+## Architecture
+
+```
+/code-review (orchestrator - spawns agents only)
+│
+├─ Phase 0: Worktree Discovery & Pre-flight
+│  ├─ Step 0a: git worktree list → filter reviewable
+│  ├─ Step 0b: Resolve the compliance lens
+│  ├─ Step 0c: Git agent (ensure-pr-ready) per worktree [parallel]
+│  ├─ Step 0d: Incremental detection + timestamp setup per worktree
+│  ├─ Step 0e-i: Load prior resolution-summary.md
+│  ├─ Step 0e-ii: Convergence assessment (warn if FP ratio > 70%)
+│  └─ Step 0f: Resolve REVIEW_PUBLICATION per worktree (publication gate)
+│
+├─ Per worktree (SEQUENTIAL — one worktree at a time):
+│  │
+│  ├─ Phase 1: Analyze changed files
+│  │  ├─ Classify the diff (paths.txt → DIFF_CLASS)
+│  │  ├─ Choose the focuses (code class: file types + the language stamp)
+│  │  └─ Write diff.patch and diff-{focus}.patch, by redirect
+│  │
+│  ├─ Phase 2: Reviews (PARALLEL within worktree)
+│  │  ├─ code: Review agents security, architecture, performance, complexity,
+│  │  │        consistency, regression, testing, reliability (diff.patch)
+│  │  ├─ code: + language (diff-{focus}.patch) and conditional Review agents
+│  │  └─ docs-only / tests-only / lockfile-only: the reduced set (diff.patch)
+│  │
+│  ├─ Phase 3: Synthesis → Review Comment (SEQUENTIAL within worktree)
+│  │  ├─ Step 3a: Synthesize agent (mode: review, writes review-summary.md)
+│  │  └─ Step 3b: Git agent (post-review-summary, D7 marker-dedup, REVIEW_PUBLICATION)
+│  │
+│  └─ Phase 4: Write .last-review-head + display results
+```
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No new commits since last review | Skip review, report: "No new commits since last review. Use --full for a full re-review." |
+| Rebase invalidates `.last-review-head` SHA | `git cat-file -t` check fails → fallback to full diff |
+| Same-minute review collision | `mkdir` fails → retry with seconds appended (`YYYY-MM-DD_HHMMSS`) |
+| Worktree in detached HEAD | Filtered out (no branch name → not reviewable) |
+| Worktree mid-rebase or mid-merge | Filtered out by status check |
+| Two worktrees on same branch | Deduplicate by branch — review once, use first worktree's path |
+| Worktree on protected branch | Filtered out (not reviewable) |
+| Worktree pre-flight fails | Report failure, continue with other worktrees |
+| `--full` in multi-worktree mode | Applies to all worktrees (global modifier) |
+| Many worktrees (5+) | Report count and proceed — user manages their worktree count |
+| Review comment already posted | Git agent matches its own marker on the `{cycle, timestamp}` pair → skip silently (D7); a re-review in the same cycle (different timestamp) posts its own comment. The marker's format belongs to the operation; this caller passes the pair and never restates the literal |
+| First review (no prior resolution) | PRIOR_RESOLUTIONS=(none), no convergence check |
+| fp_ratio denominator = 0 | fp_ratio = 0, no warning |
+| `--full` flag | Bypass incremental detection (Step 0d), still load PRIOR_RESOLUTIONS for cross-cycle awareness |
+| Parsing failure on resolution-summary.md | fp_ratio = 0, convergence tracking degraded (see Step 0e-ii) |
+| Concurrent sessions | Advisory only, each session computes independently |
+| Docs-only diff | `docs-only`: documentation, consistency, security on `diff.patch`; no language or conditional focus |
+| Tests-only diff | `tests-only`: testing, reliability, consistency, security on `diff.patch`; no language or conditional focus |
+| Lockfile-only diff | `lockfile-only`: dependencies, security on `diff.patch` |
+| Mixed non-code diff (docs with tests, tests with a lockfile) | The union of the matching sets, on `diff.patch` |
+| A path matching no class pattern, or an empty path list | `code` (fail-safe): the 8 core focuses on the full diff |
+| A file moved across classes | `--no-renames` lists the old and the new path, so a code path makes the diff `code` |
+| Path listing above about 40 lines | The count is printed; `paths.txt` is read in ranges of about 40 lines |
+| Language files changed, plugin not installed | The focus is absent from the stamped line: not spawned |
+| Public repo (`auto` mode) | Git agent probes visibility, posts counts-only STUB comment; full report stays local |
+| `reviewPublication: off` | Git agent skips posting the review comment (OFF) — except that, only when `EVIDENCE_POLICY` is `required`, Step 0f passes `stub` and a counts-only STUB comment posts |
+
+## Backwards Compatibility
+
+- **Single worktree**: Auto-discovery finds only one worktree → proceeds exactly as before. Zero behavior change.
+- **Legacy flat layout**: If `{worktree}/.devflow/docs/reviews/{branch-slug}/` contains flat `*.md` files (no timestamped subdirectories), new runs create timestamped subdirectories. Old flat files remain untouched.
+
+## 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`), the bounded Phase 1 path listing (a redirect into `paths.txt`, a `wc -l` count and ranged reads) and the redirect-only patch writes (`diff.patch`, `diff-{focus}.patch`). Redirect-only writes print nothing, so no diff content reaches this thread
+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; redirect-only writes print nothing
+4. **Clear ownership** - Each agent owns its output completely
+5. **Honest reporting** - Display agent outputs directly
+6. **Incremental by default** - Only review new changes unless `--full` specified
+7. **Auto-discover worktrees** - One command handles all reviewable branches