devflow-kit 3.9.0 → 3.11.0

package/dist/commands/bug-analysis.md

@@ -3,15 +3,11 @@ description: Proactive bug finding with static and semantic analysis — hunts r
 ---
 # 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
 
@@ -96,7 +92,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.
 
@@ -104,75 +100,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.
+Skip if Step 2c set `STATIC_STATUS`.
 
-Run available tools on the changed files (from `CHANGED_FILES` computed in Step 2b).
-
-**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"
+```
+
+**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"
 ```
-Parse `SNYK_FILTERED` SARIF → extract findings. If `jq` is unavailable, fall back to the raw `SNYK_SARIF` and note the limitation.
+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.
-
-**Normalize** all findings to unified table, cap at top 50 by severity. Truncate each Description entry to 200 characters maximum:
+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).
 
-| Tool | File:Line | CWE | Severity | Title | Description |
-|------|-----------|-----|----------|-------|-------------|
-| {tool} | {file}:{line} | {CWE or —} | {CRITICAL/HIGH/MEDIUM/LOW} | {title} | {description truncated to 200 chars} |
+`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`.
 
-Write ALL raw findings to `{ANALYSIS_DIR}/static-findings.md`. Set `STATIC_FINDINGS` to the top-50 table.
+`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.
 
-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
 
@@ -285,23 +287,22 @@ A KB with no Rules section labels its entries `Rules ({section name}):` and give
 #### 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
@@ -319,25 +320,20 @@ 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>
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT}
 FEATURE_KNOWLEDGE: {FEATURE_KNOWLEDGE}
 PR_DESCRIPTION: <pr-description>{PR_DESCRIPTION}</pr-description>
 OUTPUT_PATH: {ANALYSIS_DIR}/{focus}.md
 Follow devflow:apply-decisions to Read full ADR/PF bodies on demand.
 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:
 
@@ -347,14 +343,15 @@ 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:
 
 ```
@@ -363,26 +360,22 @@ Output: {ANALYSIS_DIR}/bug-analysis-summary.md"
 **Branch**: {branch} -> {base_branch}
 {any base `TRACEABILITY: DEGRADED` line from Phase 1, as returned}
 **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.
@@ -390,70 +383,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
-│  ├─ index.md (pre-rendered) → DECISIONS_CONTEXT
-│  ├─ 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
-- [ ] Phase 3: Context Loading → DECISIONS_CONTEXT captured, FEATURE_KNOWLEDGE loaded (or `(none)`), PLAN_CONTEXT and ACCEPTANCE_RULES captured (or `(none)`)
-- [ ] 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/dist/commands/dynamic-build.md

@@ -155,7 +155,7 @@ The following agentType values are valid. Model tiers are shown for reference
 Before authoring, verify:
 
 1. **Workflow tool available:** if the `Workflow` tool is not in your available tools, STOP and tell the user: "The Workflow tool is not available in this session. dynamic-build requires Claude Code's dynamic workflow runtime."
-2. **`agentType` support:** confirmed available (spike F5, 2026-06-11). If spawned agents return no results, check that devflow is installed (`devflow init` has been run).
+2. **`agentType` support:** if spawned agents return no results, check that devflow is installed (`devflow init` has been run).
 3. **Tracker paths:** an issue reference or URL in the input is read through the Git agent, which resolves the configured tracker and its access itself and reports `TRACEABILITY: DEGRADED ({reason})` when it cannot read one — then note it and fall back to the issue text the user provided. No tracker CLI is checked here.
 4. **No-remote path:** if the repo has no remote, skip the remote-dependent steps (the wave PR and its evidence) and proceed with local branch operations only; the Git agent reports DEGRADED for any tracker step it cannot reach.
 
@@ -357,7 +357,7 @@ After implementing, commit your changes with a conventional-commit message and r
 );
 
 // Phase 3: Gate 1 #1 — post-code pipeline: Polish agent → Harden agent → Validate agent.
-// Validate runs last and unconditionally, so its one full run covers every commit the pass made (see gate1_postcode()).
+// Validate runs last and unconditionally, so its one full run covers every commit the pass made.
 const gate1 = await phase("gate1", async () => {
   await agent(`Polish and reduce complexity of recent changes on branch ${BRANCH}. Commit any improvements.`, { agentType: "Polish" });
 
@@ -416,8 +416,7 @@ Criteria: ${CRITERIA || "see plan"}
 Return: {"verdict": "PASS" | "FAIL", "rationale": "..."} — FAIL if either answer is no, naming the failing criterion or the drift.`, { agentType: "Evaluate" });
     evalVerdict = evaluation?.verdict === "PASS" ? "PASS" : "FAIL";
     if (evalVerdict === "FAIL") {
-      // fix-and-continue — no re-evaluate, no inline Gate 1. The final Gate 1 (#2)
-      // after the review pass is the build gate before the branch is handed back.
+      // fix-and-continue — no re-evaluate, no inline Gate 1.
       await agent(`OPERATION: alignment-fix
 Fix the alignment issues identified by the Evaluate agent on branch ${BRANCH}:
 ${evaluation?.rationale || "see the Evaluate agent's report"}
@@ -434,17 +433,19 @@ Self-verify your fix compiles, following your Running commands block. Commit fix
 ${CRITERIA || "(none)"}
 TEST_PLAN: ${TEST_PLAN || "(none)"}
 Follow your Running commands block for every scenario command.
-Cover: functionality, API contracts, performance, and cover every TEST_PLAN scenario. Report: PASS or FAIL per scenario.`, { agentType: "Test" });
-    testVerdict = testResult.verdict;
+Cover: functionality, API contracts, performance, and cover every TEST_PLAN scenario.
+Return: {"verdict": "PASS" | "FAIL" | "BLOCKED", "failures": "..."}`, { agentType: "Test" });
+    const word = testResult?.verdict?.split?.(/[ (]/)[0];
+    testVerdict = ["PASS", "FAIL"].includes(word) ? word : "BLOCKED";
     if (testVerdict === "FAIL") {
       // fix-and-continue — no re-test, no inline Gate 1.
       await agent(`OPERATION: qa-fix
 Fix the failing acceptance test scenarios on branch ${BRANCH}:
-${testResult.failures}
+${testResult.failures || "see the Test agent's report"}
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
 ${COMPLIANCE_DIRECTIVE}
 Self-verify your fix compiles and the scenarios pass, following your Running commands block. Commit fixes.`, { agentType: "Fix" });
-      testVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
+      testVerdict = "FAIL-FIXED";
     }
   }
 
@@ -590,8 +591,6 @@ Return: {"status": "fixed"|"blocked", "commitShas": ["<sha>"], "unresolved": ["<
 });
 
 // Phase 5.5: Gate 1 #2 — FINAL post-fix gate (Polish agent → Harden agent → full Validate agent, Validate last and unconditional).
-// Runs ONCE, after the review pass. Inside the pass the Code agent self-verified its own fixes;
-// this is the build gate before the branch is handed back. See gate1_postcode() cadence.
 const gate1Final = await phase("gate1-final", async () => {
   await agent(`Polish and reduce complexity of recent changes on branch ${BRANCH}. Commit any improvements.`, { agentType: "Polish" });
 
@@ -626,9 +625,9 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
 });
 
 // PASS requires survivingFindings.length === 0 && coverageGaps.length === 0 && gate1Final.verdict !== "ESCALATED"
-// and no FAIL-FIXED Gate 2 verdict: fixes applied but never re-run report UNVERIFIED, never PASS
+// and every Gate 2 verdict PASS or SKIPPED; any other reports UNVERIFIED, never PASS
 const coverageGaps = reviewResult.coverageGaps || [];
-const gate2Unverified = [gate2.evaluateVerdict, gate2.testVerdict].includes("FAIL-FIXED");
+const gate2Unverified = ![gate2.evaluateVerdict, gate2.testVerdict].every(v => v === "PASS" || v === "SKIPPED");
 const overallVerdict = (reviewResult.survivingFindings?.length || 0) === 0 && coverageGaps.length === 0 && gate1Final.verdict !== "ESCALATED" ? (gate2Unverified ? "UNVERIFIED" : "PASS") : "PARTIAL";
 
 // Phase 6: Report — the phase returns the engine result (engine_output_schema); its verdict is overallVerdict
@@ -674,17 +673,17 @@ This applies to both: multiple Code agents working on a single ticket AND multi-
 
 ### Build execution doctrine — the Running commands block (LOAD-BEARING)
 
-The Validate, Code and Test agents each carry this `## Running commands` block in their bodies, so each prompt in this engine names the block ("your Running commands block") instead of copying it:
+The Code, Fix, Refactor, Validate and Test agents each carry this `## Running commands` block in their bodies, so each prompt in this engine names the block ("your Running commands block") instead of copying it:
 
 Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
 
-- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
-- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
-- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
-- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
-- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Capture, then tail, in one Bash call: `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; printf '\nEXIT=%s\n' "$rc"`. The last `EXIT=` line is the result; never decide one from a grep count.
+- Never background a build or test, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change; for the whole set, one workspace command over per-package loops.
+- A run past its timeout moves to the background: no tool call, even a Read, until its end notice, then Read the last `EXIT=` line of the file the move names, not `$LOG`; it alone sets the label, not the notice. With none read it is BLOCKED: report its duration and log path. Report only after the end notice.
+- A run expected to exceed the ceiling may be split into parts, run in sequence.
 - Never re-run a command when nothing it reads has changed.
-- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they allow directly.
 - The same rules hold inside a dynamic Workflow sub-agent.
 
 **Cheapest-sufficient validation:** iterate with the fastest check that proves the change — `tsc --noEmit`, `cargo check`, `go vet`, a single test file — the ecosystem's cheapest sufficient signal. Reserve expensive full/optimized builds and whole-suite runs for the final gates only.
@@ -742,6 +741,7 @@ Gate 2 inputs are produced by `/devflow:dynamic-plan`'s plan-challenge step —
 **Test agent** (only if acceptance criteria or a test plan exist):
 - Scenario-based acceptance tests covering functionality, API contracts, performance
 - FAIL → fix-and-continue — a Fix agent applies the demanded fixes and self-verifies its own build. The recorded verdict becomes `FAIL-FIXED`; Gate 2 then proceeds. In SINGLE mode the run reports it as `UNVERIFIED`, never PASS.
+- BLOCKED (no result), or any other or missing verdict → no fix, and the run never reports PASS.
 
 **When Gate 2 inputs are absent:**
 - No plan → skip the Evaluate agent silently (note in output: "Gate 2 Evaluate agent skipped — no plan available")
@@ -910,7 +910,7 @@ Each ticket engine run returns a structured result. The Synthesize agent or the
   ],
   "gate2": {
     "evaluateVerdict": "PASS | FAIL | FAIL-FIXED | SKIPPED",
-    "testVerdict": "PASS | FAIL | FAIL-FIXED | SKIPPED",
+    "testVerdict": "PASS | FAIL | FAIL-FIXED | SKIPPED | BLOCKED",
     "skipReasons": ["string — why a gate was skipped, if applicable"]
   }
 }
@@ -1228,12 +1228,12 @@ Agent(subagent_type="Test"):
 FILES_CHANGED: {the file list that diff printed}
 TEST_PLAN: {the TP lines of the wave evidence file's ## Test Plan section}
 WORKTREE_PATH: {integration worktree root}
-Cover every TEST_PLAN line on the integration branch as it stands. Report PASS or FAIL with evidence."
+Cover every TEST_PLAN line on the integration branch as it stands. Report your Status with evidence."
 ```
 
-   Nothing is fixed here, PASS or FAIL: the wave is done and its PR is open. Report the Test agent's Status.
+   Nothing is fixed here, whatever the Status: the wave is done and its PR is open. Report the Test agent's Status.
 
-   **(b) Claims.** Append its TP claims, PASS or FAIL alike, to the `## Claims` section of `"{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md"` — the file's last section, created when absent. Append only: never edit or remove a claim. Each line is `/implement`'s TP claim, keyed to the 40-hex `HEAD:` the Test agent's report shows:
+   **(b) Claims.** Append its TP claims, whatever its Status, to the `## Claims` section of `"{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md"` — the file's last section, created when absent. Append only: never edit or remove a claim. Each line is `/implement`'s TP claim, keyed to the 40-hex `HEAD:` the Test agent's report shows:
 
 ```
 - TP-<n> <PASS|FAIL|SKIP> sha:<head> by:test exit:<0-255>