devflow-kit 3.9.0 → 3.11.0

package/src/assets/commands/bug-analysis.mds

@@ -9,15 +9,11 @@ output-dir: dist/commands
 @import "./_partials/_settings.mds" as settings
 # Bug Analysis Command
 
-Run a proactive bug analysis on the current branch by combining static analysis tools with parallel semantic analyzers, then synthesizing results into an actionable bug report.
+Run a proactive bug analysis on the current branch: static analysis tools and parallel semantic analyzers, synthesized into one bug report.
 
 ## Usage
 
-```
-/bug-analysis              (analyze current branch — incremental if prior analysis exists)
-/bug-analysis --full       (force full analysis, ignore incremental state)
-/bug-analysis --no-static  (skip static analysis track, semantic-only)
-```
+`/bug-analysis [--full] [--no-static]`: `--full` ignores incremental state; `--no-static` skips static analysis.
 
 ## Phases
 
@@ -28,7 +24,11 @@ Run a proactive bug analysis on the current branch by combining static analysis
 {{evidence_policy()}}
 
 {{docs_root()}}
+<!-- compliance:off -->
+When `EVIDENCE_POLICY` is `required`, record `TRACEABILITY: DEGRADED (compliance off on this machine; the repository requires evidence)` once, for the Phase 7 report.
+<!-- compliance:end -->
 
+<!-- compliance:on -->
 Render the test-plan block 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):
@@ -39,12 +39,15 @@ node "$HOME/.devflow/scripts/verify-evidence.cjs" render --plan "{worktree}/.dev
 
 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.
 
+<!-- compliance:end -->
 Spawn Git agent:
 
 ```
 Agent(subagent_type="Git", run_in_background=false):
 "OPERATION: ensure-pr-ready
+<!-- compliance:on -->
 PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}
+<!-- compliance:end -->
 APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
 Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, base_ref, branch-slug, PR#"
@@ -88,7 +91,7 @@ If `pr_number` is absent, set `PR_DESCRIPTION` to `(none)`.
 CHANGED_FILES=$(git diff --name-only {DIFF_RANGE})
 ```
 
-Store as `CHANGED_FILES`; Steps 2d and Phase 4 read it. A non-zero diff exit stops.
+Store as `CHANGED_FILES`; Phase 4 reads it. A non-zero diff exit stops.
 
 If output is empty → "No changes to analyze." Stop.
 
@@ -96,75 +99,81 @@ If output is empty → "No changes to analyze." Stop.
 
 **Produces:** STATIC_TOOL_STATUS
 
-Skip if `--no-static` flag provided.
+If `--no-static` is set: set `STATIC_FINDINGS` to "Static analysis skipped (--no-static)." and `STATIC_STATUS` to "skipped (--no-static): static analysis did not cover these commits". Skip the rest of Phase 2.
 
 ```bash
-SEMGREP_AVAILABLE=$(which semgrep 2>/dev/null && echo "yes" || echo "no")
-SNYK_AVAILABLE=$(which snyk 2>/dev/null && echo "yes" || echo "no")
-CODEQL_AVAILABLE=$(which codeql 2>/dev/null && echo "yes" || echo "no")
+for t in semgrep snyk codeql jq; do printf '%s=%s\n' "$t" "$(command -v "$t" || echo no)"; done
+set -o pipefail; export LC_ALL=C; git -C "{worktree}" diff --name-only -z --diff-filter=d {DIFF_RANGE} | tr '\0\n' '\n?' | sed -n 's/.*\.\([^./]*\)$/\1/p' | sort -u || echo "extension list failed"
 ```
 
-If all are `no`: warn user "No static analysis tools found. Proceeding with semantic analysis only. To enable static analysis, install semgrep (`pip install semgrep`) or snyk (`npm install -g snyk`)." Set `STATIC_FINDINGS` to `(none)`.
+Its second line lists the extensions of the changed files. `{lang}` is the first of javascript-typescript (js jsx mjs cjs ts tsx), python (py), ruby (rb) whose extension is listed; no other value reaches the command. With none, CodeQL does not run and its status is `no supported language`; `extension list failed` means it did not complete.
+
+If all three scanners print `no`: warn user "No static analysis tools found. Install semgrep or snyk." Set `STATIC_FINDINGS` to "Static analysis did not run: no scanner is installed." and `STATIC_STATUS` to `not installed` for each tool.
+
+If a scanner is installed but `jq` prints `no`: set `STATIC_FINDINGS` to "Static analysis did not complete: jq is not installed." and `STATIC_STATUS` to `did not complete (jq is not installed)` for an installed tool, else `not installed`.
 
 If some are available: note which tools will run.
 
 #### Step 2d: Tiered Static Analysis
 
-**Produces:** STATIC_FINDINGS
+**Produces:** STATIC_FINDINGS, STATIC_STATUS
 **Requires:** STATIC_TOOL_STATUS, DIFF_RANGE, ANALYSIS_DIR
 
-Skip if `--no-static` flag provided or all tools unavailable.
-
-Run available tools on the changed files (from `CHANGED_FILES` computed in Step 2b).
+Skip if Step 2c set `STATIC_STATUS`.
 
-**Semgrep and Snyk run in parallel** — launch both in the background, then wait for both before proceeding to CodeQL. CodeQL is conditional and sequential.
+Run each available tool in this order, each in its own foreground Bash call with the Bash `timeout` at the ceiling: 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set. Past it, make no tool call, even a Read, until its end notice, then Read the last `exit=` line of the output file that notice names, never a scanner file; the notice sets nothing. File names reach a scanner only through `-z`, `xargs -0` and after `--`.
 
 **Semgrep** (if available):
 ```bash
-# tr '\n' '\0' + xargs -0 is portable across GNU and BSD xargs (macOS ships BSD xargs, which lacks -d)
-echo "$CHANGED_FILES" | tr '\n' '\0' | xargs -0 timeout 300 semgrep scan --config auto --sarif --quiet 2>/dev/null
+cd "{worktree}" || exit
+set -o pipefail; git diff --name-only -z --diff-filter=d {DIFF_RANGE} | xargs -0 -r semgrep scan --config auto --sarif --quiet -- >"{ANALYSIS_DIR}/semgrep.part" 2>/dev/null; E=$?
+mv "{ANALYSIS_DIR}"/semgrep.{part,sarif}
+printf '\nexit=%s\n' "$E"
 ```
-Parse SARIF output → extract findings.
 
 **Snyk Code** (if available):
 ```bash
-# One project-level scan (a per-file xargs run would invoke snyk O(n) times; --file is for dependency scans).
-SNYK_SARIF=$(timeout 300 snyk code test --sarif 2>/dev/null)
-# Programmatic filter: keep only results whose file path is in CHANGED_FILES — defense-in-depth, before the LLM agent sees any output.
-SNYK_FILTERED=$(echo "$SNYK_SARIF" | jq --argjson files "$(echo "$CHANGED_FILES" | jq -R . | jq -s .)" \
-  '.runs[].results |= map(select(.locations[].physicalLocation.artifactLocation.uri as $uri | $files | index($uri) != null))' \
-  2>/dev/null || echo "$SNYK_SARIF")
+cd "{worktree}" || exit
+snyk code test --sarif >"{ANALYSIS_DIR}/snyk-all.json" 2>/dev/null; E=$?
+git diff --name-only -z {DIFF_RANGE} >"{ANALYSIS_DIR}/changed.z" && jq --rawfile n "{ANALYSIS_DIR}/changed.z" \
+  '($n|split("\u0000")) as $f|.runs[]?.results|=[.[]?|select([.locations[]?.physicalLocation.artifactLocation.uri//empty] as $u|($u|length)==0 or any($u[];IN($f[])))]' \
+  "{ANALYSIS_DIR}/snyk-all.json" >"{ANALYSIS_DIR}/snyk.sarif" \
+  && jq -nr '[inputs|[.runs[]?.results[]?]|length]|"total=\(.[0]) kept=\(.[1])"' "{ANALYSIS_DIR}/snyk-all.json" "{ANALYSIS_DIR}/snyk.sarif" \
+  || { echo "Snyk scope filter failed: unfiltered"; cp "{ANALYSIS_DIR}/snyk-all.json" "{ANALYSIS_DIR}/snyk.sarif"; }
+printf '\nexit=%s\n' "$E"
 ```
-Parse `SNYK_FILTERED` SARIF → extract findings. If `jq` is unavailable, fall back to the raw `SNYK_SARIF` and note the limitation.
+
+**Counts and table** (after Snyk with `{tools}` = `semgrep snyk`; after CodeQL with `codeql`):
+```bash
+cd "{ANALYSIS_DIR}" || exit
+L='def L($r):.ruleId as $i|.level//([$r.tool|.driver,.extensions[]?|.rules[]?|select(.id==$i)]|.[0].defaultConfiguration.level)//"warning";'
+for t in {tools}; do [ -f $t.sarif ] || continue
+  jq -rs --arg t $t "$L"'[.[].runs[]?|. as $r|.results[]?|L($r)] as $l|def c(k):[$l[]|select(.==k)]|length;"\($t) docs=\(length) results=\($l|length) error=\(c("error")) warning=\(c("warning")) note=\(c("note"))"' $t.sarif || echo "$t sarif=unreadable"
+  jq -r --arg t $t "$L"'.runs[]?|. as $r|.results[]?|[$t,(.locations[0].physicalLocation|.artifactLocation.uri,.region.startLine),L($r),(.ruleId//"—"),((.message.text//"")[:200])]|@tsv' $t.sarif >findings-$t.tsv || echo "findings table incomplete: $t"
+done
+cat findings-{semgrep,snyk,codeql}.tsv >findings.tsv 2>/dev/null
+jq -Rrs 'split("\n")|map(select(.!=""))|sort_by(split("\t")[3]|{error:0,warning:1}[.]//2)|.[:50][]' findings.tsv >findings-top.tsv || echo "findings table incomplete: top"
+```
+Read `error` as HIGH, `warning` as MEDIUM, `note` as LOW.
 
 **CodeQL** (if available AND (`--full` OR Semgrep/Snyk found HIGH/CRITICAL findings)):
 ```bash
-# Use a unique temp directory per run to prevent symlink attacks and concurrent-process clobbering
-CODEQL_TMP=$(mktemp -d)
-# Register cleanup trap immediately after mktemp — ensures rm -rf runs on EXIT, SIGTERM, and SIGINT
-# even if the session is interrupted before reaching the explicit rm -rf below
+CODEQL_TMP=$(mktemp -d) || exit
 trap 'rm -rf "${CODEQL_TMP}"' EXIT INT TERM
-timeout 600 codeql database create "${CODEQL_TMP}/db" --language={detected-language} --source-root=. 2>/dev/null && \
-timeout 600 codeql database analyze "${CODEQL_TMP}/db" --format=sarif-latest --output="${CODEQL_TMP}/results.sarif" 2>/dev/null
-# Capture exit status before cleanup so cleanup doesn't mask failures
+{ codeql database create "${CODEQL_TMP}/db" --language={lang} --source-root="{worktree}" && \
+codeql database analyze "${CODEQL_TMP}/db" --format=sarif-latest --output="{ANALYSIS_DIR}/codeql.sarif"; } >"{ANALYSIS_DIR}/codeql.log" 2>&1
 CODEQL_EXIT=$?
-# Parse SARIF output BEFORE cleanup — rm -rf destroys results.sarif
-CODEQL_SARIF=$(cat "${CODEQL_TMP}/results.sarif" 2>/dev/null || echo "")
-# Explicit cleanup (trap also covers this path; explicit rm is belt-and-suspenders)
+printf '\nexit=%s\n' "$CODEQL_EXIT"
 rm -rf "${CODEQL_TMP}"
 trap - EXIT INT TERM
 ```
-Parse `CODEQL_SARIF` → extract findings. If database creation fails, `CODEQL_EXIT` is non-zero — skip CodeQL findings and note it. The `trap` guarantees cleanup on SIGTERM/SIGINT/EXIT so orphaned temp directories do not accumulate across interrupted sessions.
+A tool's status is its last line, `exit={n}`; a tool that ran completed only on Semgrep 0, Snyk 0 or 1 (1 = issues, only with SARIF output), CodeQL 0. Snyk 3 (no supported file) is `no supported language`: its counts are not checked. Any other status, or no such line, means it did not complete (126-127: scanner did not start; else failed. Semgrep via xargs: number only). A call with no `exit=` line read did not complete. A tool that ran also did not complete when the counts fence prints no `{tool} docs=` line for it, `sarif=unreadable` or `findings table incomplete` for it (`: top` counts for every tool), or `docs=0` (Semgrep exit 0 with `docs=0`: no file to scan, completed).
 
-**Normalize** all findings to unified table, cap at top 50 by severity. Truncate each Description entry to 200 characters maximum:
+`findings.tsv` keeps every finding. Read only `findings-top.tsv` (top 50 by level: tool, file, line, level, rule, message cut to 200 chars), set `STATIC_FINDINGS` to the column names and its rows, and write them with the status lines to `{ANALYSIS_DIR}/static-findings.md`.
 
-| Tool | File:Line | CWE | Severity | Title | Description |
-|------|-----------|-----|----------|-------|-------------|
-| {tool} | {file}:{line} | {CWE or —} | {CRITICAL/HIGH/MEDIUM/LOW} | {title} | {description truncated to 200 chars} |
+`STATIC_FINDINGS` is `(none)` only when every tool that was to run completed, at least one did, and none found anything; when no tool was to run, it is "Static analysis did not run: no tool ran." For each tool that did not complete, add under any rows the line "Static analysis did not complete: {tool}: " plus "exit {n} ({meaning}).", "no exit status.", "no counts line." or "SARIF not read." A Snyk call (not Snyk 3) that printed "Snyk scope filter failed: unfiltered" adds that line too.
 
-Write ALL raw findings to `{ANALYSIS_DIR}/static-findings.md`. Set `STATIC_FINDINGS` to the top-50 table.
-
-If no tool produced findings: set `STATIC_FINDINGS` to `(none)`.
+Set `STATIC_STATUS` to one `{tool}: {value}` per tool: `completed`, `not installed`, `not needed` (CodeQL, not triggered) or `no supported language` (CodeQL with no table row, or Snyk 3), all covered, or `did not complete ({why})`, not covered. A covered tool other than `completed` was not to run.
 
 ### Phase 3: Context Loading
 
@@ -188,23 +197,22 @@ If no tool produced findings: set `STATIC_FINDINGS` to `(none)`.
 #### Plan Artifact
 
 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). 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
-2. Read the most recent file that carries an `## Acceptance Criteria` section
-3. Extract `## Acceptance Criteria` section → parse into table: `| ID | Criterion | Type | Testable Condition |`
-4. Set `PLAN_CONTEXT` to plan summary; `ACCEPTANCE_RULES` to the table
-5. If no plan files exist or section not found: `PLAN_CONTEXT=(none)`, `ACCEPTANCE_RULES=(none)`
+2. Read the most recent file that carries an `## Acceptance Criteria` section; parse it into the table `| ID | Criterion | Type | Testable Condition |`
+3. Set `PLAN_CONTEXT` to plan summary; `ACCEPTANCE_RULES` to the table
+4. If no plan files exist or section not found: `PLAN_CONTEXT=(none)`, `ACCEPTANCE_RULES=(none)`
 
 ### Phase 4: File Analysis
 
 **Produces:** ACTIVE_FOCUSES
 **Requires:** DIFF_RANGE
 
-Determine which focus analyzers to run using `CHANGED_FILES` (already computed in Step 2b — do not re-run `git diff`):
+Pick the focus analyzers from `CHANGED_FILES` (Step 2b; do not re-run `git diff`):
 
 | Focus | Condition |
 |-------|-----------|
 | `security` | Always |
 | `functional` | Always |
-| `integration` | 2+ distinct directories changed (`dirname` unique count ≥ 2) |
+| `integration` | 2+ distinct directories changed |
 | `usability` | Any `.tsx`, `.jsx`, `.html`, or `.css` file changed |
 
 ### Phase 5: Parallel Bug Analysis
@@ -226,7 +234,7 @@ FOCUS: {focus}
 DIFF_COMMAND: git diff {DIFF_RANGE}
 ACCEPTANCE_RULES: {ACCEPTANCE_RULES filtered to this focus type, or (none)}
 PLAN_CONTEXT: {PLAN_CONTEXT}
-STATIC_FINDINGS: {STATIC_FINDINGS if focus == security, else (none)}
+STATIC_FINDINGS: <static-findings>{STATIC_FINDINGS if focus == security, else (none)}</static-findings>
 <!-- curation:on -->
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT}
 <!-- curation:end -->
@@ -237,18 +245,13 @@ OUTPUT_PATH: {ANALYSIS_DIR}/{focus}.md
 Follow devflow:apply-decisions to Read full ADR/PF bodies on demand.
 <!-- curation:end -->
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE.
-IMPORTANT: Write report to {ANALYSIS_DIR}/{focus}.md using Write tool"
+IMPORTANT: Write the report to OUTPUT_PATH using the Write tool"
 ```
 
-Notes:
-- Security analyzer receives full `STATIC_FINDINGS`; all others receive `(none)`
-- Filter `ACCEPTANCE_RULES` by the `Type` column matching each focus: security criteria → security analyzer, functional criteria → functional analyzer, etc. Pass the filtered subset only
-- Spawn all in a single message for true parallel execution
-
 ### Phase 6: Synthesis
 
 **Produces:** BUG_ANALYSIS_SUMMARY
-**Requires:** ANALYZER_OUTPUTS, ANALYSIS_DIR, BRANCH_INFO
+**Requires:** ANALYZER_OUTPUTS, ANALYSIS_DIR, BRANCH_INFO, STATIC_STATUS
 
 Spawn Synthesize agent:
 
@@ -258,42 +261,43 @@ Agent(subagent_type="Synthesize", run_in_background=false):
 ANALYSIS_BASE_DIR: {ANALYSIS_DIR}
 BRANCH: {branch} -> {base_branch}
 TIMESTAMP: {timestamp}
+STATIC_STATUS: {STATIC_STATUS}
 Output: {ANALYSIS_DIR}/bug-analysis-summary.md"
 ```
 
 ### Phase 7: Finalize
 
-**Requires:** BRANCH_INFO, ANALYSIS_DIR
+**Requires:** BRANCH_INFO, ANALYSIS_DIR, STATIC_STATUS
 
-1. In one Bash call run `M="$(git -C "{worktree}" rev-parse --absolute-git-dir)/devflow/bug-analysis/{branch-slug}" && mkdir -p "$M" && git -C "{worktree}" rev-parse HEAD > "$M/.last-analysis-head"`. A failed or refused write never stops the run and is not retried another way.
+1. Run the write below only when every tool that was to run completed, or `--no-static` is set, also with `--full`. Else keep the marker; the report names the way out (fix the tool, or run with `--no-static`). In one Bash call run `M="$(git -C "{worktree}" rev-parse --absolute-git-dir)/devflow/bug-analysis/{branch-slug}" && mkdir -p "$M" && git -C "{worktree}" rev-parse HEAD > "$M/.last-analysis-head"`. A failed or refused write never stops the run and is not retried another way.
 2. Report to user:
 
 ```
 ## Bug Analysis Complete
 
 **Branch**: {branch} -> {base_branch}
+<!-- compliance:on -->
 {any base `TRACEABILITY: DEGRADED` line from Phase 1, as returned}
+<!-- compliance:off -->
+{any base `TRACEABILITY: DEGRADED` line from Phase 1, as returned, and the compliance-off line of Phase 1}
+<!-- compliance:end -->
 **Analysis**: {ANALYSIS_DIR}
+**Static analysis**: {STATIC_STATUS per tool; if a tool did not complete: "marker kept" and the way out; any Snyk filter note}
 
 ### Risk Assessment: {risk_level}
 
 {brief_reasoning}
 
 ### Bug Counts
-| Category | CRITICAL | HIGH | MEDIUM | LOW | Total |
-|----------|----------|------|--------|-----|-------|
-| Security | {n} | {n} | {n} | {n} | {n} |
-| Functional | {n} | {n} | {n} | {n} | {n} |
-| Integration | {n} | {n} | {n} | {n} | {n} |
-| Usability | {n} | {n} | {n} | {n} | {n} |
+{The summary's Bug Summary table: Security, Functional, Integration and Usability rows by CRITICAL, HIGH, MEDIUM, LOW and Total}
 
 ### Top Findings
-{List top 3-5 bugs by severity and confidence}
+{Top 3-5 bugs by severity and confidence}
 
 ### Artifacts
 - Bug report: {ANALYSIS_DIR}/bug-analysis-summary.md
-- Per-focus reports: {ANALYSIS_DIR}/{security|functional|integration|usability}.md
-- Static findings: {ANALYSIS_DIR}/static-findings.md (if static analysis ran)
+- Per-focus reports: {ANALYSIS_DIR}/{focus}.md
+- Static findings: {ANALYSIS_DIR}/static-findings.md (if it ran)
 
 {if any CRITICAL or HIGH bugs found:}
 Run `/resolve` to process and fix these findings.
@@ -301,76 +305,26 @@ Run `/resolve` to process and fix these findings.
 
 ## Architecture
 
-```
-/bug-analysis (orchestrator — spawns agents only)
-│
-├─ Phase 1: Pre-flight
-│  └─ Git agent (ensure-pr-ready)
-│
-├─ Phase 2: Static Analysis
-│  └─ 2a incremental range, 2b changed files (stop if none), 2c tools, 2d semgrep → snyk → codeql
-│
-├─ Phase 3: Context Loading
-<!-- curation:on -->
-│  ├─ index.md (pre-rendered) → DECISIONS_CONTEXT
-<!-- curation:end -->
-│  ├─ Feature knowledge load → FEATURE_KNOWLEDGE
-│  └─ {worktree}/.devflow/docs/design/*.md → PLAN_CONTEXT + ACCEPTANCE_RULES
-│
-├─ Phase 4: File Analysis
-│  └─ Detect active focuses (security + functional always; integration + usability conditional)
-│
-├─ Phase 5: Bug Analysis (PARALLEL)
-│  └─ Debug agent per active focus (security also reads STATIC_FINDINGS)
-│
-├─ Phase 6: Synthesis
-│  └─ Synthesize agent (mode: bug-analysis)
-│
-└─ Phase 7: Finalize
-   ├─ Write .last-analysis-head
-   └─ Display results + suggest /resolve if blocking bugs found
-```
+Seven phases: Phase 1 to Phase 7.
 
 ## Edge Cases
 
 | Case | Handling |
 |------|----------|
-| No new commits since last analysis | Stop: "No new commits since last analysis. Use --full for a full re-analysis." |
 | Rebase invalidates `.last-analysis-head` SHA | `git cat-file -t` check fails → fallback to full diff |
 | Zero changed files in DIFF_RANGE with exit 0 | Stop: "No changes to analyze." |
-| Same-minute analysis collision | `mkdir` with seconds suffix (`YYYY-MM-DD_HHMMSS`) |
-| All static tools unavailable | Warn, proceed with semantic-only analysis |
-| `--no-static` flag | Skip Phase 2c and 2d entirely; `STATIC_FINDINGS=(none)` |
 | `--full` flag | Bypass incremental detection (Step 2a), run full diff from base |
-| CodeQL database creation fails | Skip CodeQL, note in output, continue with other tools |
+| A scanner did not run or did not complete | Name the tool and why in `STATIC_FINDINGS`, not `(none)`; a tool that did not complete keeps the marker |
 
 ## Resolve Compatibility
 
-Run `/resolve` after `/bug-analysis` to fix identified bugs. `/resolve` automatically detects and uses bug analysis reports when no code review report exists.
+`/resolve` detects and uses bug analysis reports when no code review report exists.
 
 ## Principles
 
-1. **Orchestration only** — Command spawns agents, doesn't do analysis work itself
-2. **Parallel, not background** — Analyzers spawn in one message with `run_in_background=false`
-3. **Static + semantic** — Two complementary tracks, each validates the other
-4. **Incremental by default** — Only analyze new changes unless `--full` specified
-5. **Verify before reporting** — Debug agents self-verify every finding
-6. **Honest reporting** — Display risk level and counts directly from synthesis
+1. **Orchestration only** — the command spawns agents and does no analysis itself
+2. **Incremental by default** — only new changes, unless `--full`
 
 ## Phase Completion Checklist
 
-Before reporting results, verify every phase was executed:
-
-- [ ] Phase 1: Pre-flight → BRANCH_INFO captured, PR_DESCRIPTION fetched (or `(none)`)
-- [ ] Phase 2: Static Analysis → STATIC_FINDINGS captured (or `(none)` if skipped/no tools/no findings); ANALYSIS_DIR created; CHANGED_FILES populated
-<!-- curation:on -->
-- [ ] Phase 3: Context Loading → DECISIONS_CONTEXT captured, FEATURE_KNOWLEDGE loaded (or `(none)`), PLAN_CONTEXT and ACCEPTANCE_RULES captured (or `(none)`)
-<!-- curation:off -->
-- [ ] Phase 3: Context Loading → FEATURE_KNOWLEDGE loaded (or `(none)`), PLAN_CONTEXT and ACCEPTANCE_RULES captured (or `(none)`)
-<!-- curation:end -->
-- [ ] Phase 4: File Analysis → ACTIVE_FOCUSES determined (security + functional always present)
-- [ ] Phase 5: Parallel Bug Analysis → ANALYZER_OUTPUTS captured per active focus; all reports written to ANALYSIS_DIR
-- [ ] Phase 6: Synthesis → BUG_ANALYSIS_SUMMARY written to `{ANALYSIS_DIR}/bug-analysis-summary.md`
-- [ ] Phase 7: Finalize → `.last-analysis-head` updated; results displayed to user
-
-If any phase is unchecked, execute it before proceeding.
+Before reporting results, verify that every phase ran and that each variable it produces is captured, with STATIC_FINDINGS (`(none)` only if every tool that was to run completed clean), the report files in ANALYSIS_DIR present and `.last-analysis-head` written only if Phase 7's gate allows; run any missing phase first.

package/src/assets/commands/code-review.mds

@@ -10,7 +10,11 @@ output-dir: dist/commands
 @import "./_partials/_settings.mds" as settings
 # Code Review Command
 
+<!-- compliance:on -->
 Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing results into PR comments.
+<!-- compliance:off -->
+Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing results into a local review summary.
+<!-- compliance:end -->
 
 ## Usage
 
@@ -52,6 +56,9 @@ Keep each worktree's values for every downstream phase.
 **Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
 
 {{evidence_policy()}}
+<!-- compliance:off -->
+When `EVIDENCE_POLICY` is `required`, record `TRACEABILITY: DEGRADED (compliance off on this machine; the repository requires evidence)` once, for the Phase 4 report.
+<!-- compliance:end -->
 
 #### Step 0c: Per-Worktree Pre-Flight (Git Agent)
 
@@ -64,6 +71,7 @@ Discover PR description guidance from plan artifact (per worktree):
 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)`
 
+<!-- compliance:on -->
 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):
@@ -74,6 +82,7 @@ node "$HOME/.devflow/scripts/verify-evidence.cjs" render --plan "{worktree}/.dev
 
 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.
 
+<!-- compliance:end -->
 For each reviewable worktree, spawn Git agent:
 
 ```
@@ -81,7 +90,9 @@ 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}
+<!-- compliance:on -->
 PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}
+<!-- compliance:end -->
 APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
 Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, base_ref, branch-slug, PR#"
@@ -158,6 +169,7 @@ MAX_REVIEW_CYCLES = 10
 | 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 |
 
+<!-- compliance:on -->
 #### Step 0f: Resolve Publication Mode (Per Worktree)
 
 **Produces:** REVIEW_PUBLICATION
@@ -167,6 +179,7 @@ For each reviewable worktree, call:
 
 {{publication_gate()}}
 
+<!-- compliance:end -->
 ### Phase 1: Analyze Changed Files
 
 **Produces:** REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
@@ -371,12 +384,22 @@ IMPORTANT: Write report to {worktree_path}/.devflow/docs/reviews/{branch-slug}/{
 
 In multi-worktree mode, process worktrees **sequentially**: Phases 1-4 for each.
 
+<!-- compliance:on -->
 ### Phase 3: Synthesis → Review Comment (Sequential)
 
 **Produces:** REVIEW_SUMMARY, PR_COMMENT
+<!-- compliance:off -->
+### Phase 3: Synthesis → Review Summary (Sequential)
+
+**Produces:** REVIEW_SUMMARY
+<!-- compliance:end -->
 **Requires:** REVIEW_FOCUS_OUTPUTS, REVIEW_DIR, PR_INFO, GATE_LEVEL, REVIEW_FOCUS_LIST
 
+<!-- compliance:on -->
 **WAIT** for Phase 2. For each worktree, run steps 3a and 3b in sequence:
+<!-- compliance:off -->
+**WAIT** for Phase 2. For each worktree, run step 3a:
+<!-- compliance:end -->
 
 **Step 3a — Synthesize agent** per worktree:
 ```
@@ -394,6 +417,7 @@ Aggregate findings, determine merge recommendation.
 Output: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md"
 ```
 
+<!-- compliance:on -->
 **Step 3b — Git agent (post-review-summary)** per worktree (after Step 3a writes review-summary.md):
 ```
 Agent(subagent_type="Git", run_in_background=false):
@@ -407,6 +431,7 @@ WORKTREE_PATH: {worktree_path}  (omit if cwd)
 Posts the consolidated review-summary comment (marker-deduped on the cycle+timestamp pair)."
 ```
 
+<!-- compliance:end -->
 ### Phase 4: Write Review Head Marker & Report
 
 **Requires:** BRANCH_INFO, REVIEW_DIR
@@ -416,9 +441,14 @@ Per worktree, after successful completion:
 2. Display results from all agents:
    - Merge recommendation (from Synthesize agent)
    - Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing)
+<!-- compliance:on -->
    - 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)
    - Any base `TRACEABILITY: DEGRADED` line from Step 0c, as returned
+<!-- compliance:off -->
+   - 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
+<!-- compliance:end -->
    - Artifact paths
 
 ## Architecture
@@ -426,7 +456,11 @@ Per worktree, after successful completion:
 ```
 /code-review
 │
+<!-- compliance:on -->
 ├─ Phase 0: Worktree Discovery & Pre-flight, Steps 0a-0f (Git agent per worktree, parallel)
+<!-- compliance:off -->
+├─ Phase 0: Worktree Discovery & Pre-flight, Steps 0a-0e (Git agent per worktree, parallel)
+<!-- compliance:end -->
 │  ├─ Step 0b: Resolve the compliance lens and gate level
 │
 ├─ Per worktree (SEQUENTIAL):
@@ -440,9 +474,14 @@ Per worktree, after successful completion:
 │  │  ├─ code: core (diff.patch), language (diff-{focus}.patch), conditional
 │  │  └─ docs-only / tests-only / lockfile-only: the reduced set (diff.patch)
 │  │
+<!-- compliance:on -->
 │  ├─ 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)
+<!-- compliance:off -->
+│  ├─ Phase 3: Synthesis → Review Summary (SEQUENTIAL within worktree)
+│  │  └─ Step 3a: Synthesize agent (mode: review, writes review-summary.md)
+<!-- compliance:end -->
 │  │
 │  └─ Phase 4: Write .last-review-head + display results
 ```
@@ -452,7 +491,9 @@ Per worktree, after successful completion:
 | Case | Handling |
 |------|----------|
 | `--full` in multi-worktree mode | Applies to all worktrees (global modifier). It sets the diff range, never the gate level |
+<!-- compliance:on -->
 | Review comment already posted | Git agent matches its own marker on the `{cycle, timestamp}` pair → skip silently (D7) |
+<!-- compliance:end -->
 | 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 |
@@ -461,7 +502,9 @@ Per worktree, after successful completion:
 | 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 |
+<!-- compliance:on -->
 | `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 unless no public text remains |
+<!-- compliance:end -->
 
 ## Backwards Compatibility