devflow-kit 3.8.0 → 3.10.0

package/dist/curation-compliance-off/commands/bug-analysis.md

@@ -0,0 +1,349 @@
+---
+description: Proactive bug finding with static and semantic analysis — hunts real bugs in changed code before merge
+---
+# Bug Analysis Command
+
+Run a proactive bug analysis on the current branch: static analysis tools and parallel semantic analyzers, synthesized into one bug report.
+
+## Usage
+
+`/bug-analysis [--full] [--no-static]`: `--full` ignores incremental state; `--no-static` skips static analysis.
+
+## Phases
+
+### Phase 1: Pre-flight
+
+**Produces:** BRANCH_INFO, PR_DESCRIPTION, 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.
+
+**Docs root (D-DOCS-ROOT).** Every `.devflow/docs/` path this command reads or writes lives at the checkout's toplevel, never under the directory the session started in. Resolve `{worktree}` from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — by running
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+and using its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. Every docs path below is written `{worktree}/.devflow/docs/…`; a repo-relative docs path handed to an agent always travels with a `WORKTREE_PATH` naming the checkout it is relative to.
+When `EVIDENCE_POLICY` is `required`, record `TRACEABILITY: DEGRADED (compliance off on this machine; the repository requires evidence)` once, for the Phase 7 report.
+
+Spawn Git agent:
+
+```
+Agent(subagent_type="Git", run_in_background=false):
+"OPERATION: ensure-pr-ready
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
+Validate branch, commit if needed, push, create PR if needed.
+Return: branch, base_branch, base_ref, branch-slug, PR#"
+```
+
+**Extract from response:** `branch`, `base_branch`, `base_ref`, `branch_slug`, `pr_number`. Stop with cause and fix when the Base line reads (rejected) or `branch_slug` does not match the slug pattern above; name the Git agent's fix, never your own, and for the slug the allowed characters, never its value.
+
+**Fetch PR body** (after extracting `pr_number`):
+```bash
+PR_DESCRIPTION=$(gh pr view {pr_number} --json body --jq '.body' 2>/dev/null || echo "(none)")
+```
+If `pr_number` is absent, set `PR_DESCRIPTION` to `(none)`.
+
+### Phase 2: Static Analysis
+
+**Requires:** BRANCH_INFO
+
+#### Step 2a: Incremental Detection & Timestamp Setup
+
+**Produces:** DIFF_RANGE, ANALYSIS_DIR
+**Requires:** BRANCH_INFO
+
+1. Check `{gd}/devflow/bug-analysis/{branch-slug}/.last-analysis-head`, `{gd}` being what `git -C "{worktree}" rev-parse --absolute-git-dir` prints:
+   - **If exists AND `--full` NOT set:**
+     - The stored analysis head is checked as a commit ID: use it only when it is exactly 40 or 64 lowercase hex, else take the full-range path
+     - Verify reachable: `git -C "{worktree}" cat-file -t {sha}` must print `commit`; if not (rebase invalidated SHA), take the full-range path
+     - If SHA == current HEAD → "No new commits since last analysis. Use --full for a full re-analysis." Stop.
+     - Set `DIFF_RANGE` to `{sha}...HEAD`
+   - **Full-range path (no marker, or `--full`):**
+     - Stop as for a (rejected) Base line unless `base_ref` is 40 or 64 hex.
+     - Set `DIFF_RANGE` to `{base_ref}...HEAD`
+2. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`).
+3. Create timestamped analysis directory: `mkdir -p "{worktree}/.devflow/docs/bug-analysis/{branch-slug}/{timestamp}/"`
+4. Set `ANALYSIS_DIR` to that path.
+
+#### Step 2b: Check Changed Files
+
+**Requires:** DIFF_RANGE
+
+```bash
+CHANGED_FILES=$(git diff --name-only {DIFF_RANGE})
+```
+
+Store as `CHANGED_FILES`; Phase 4 reads it. A non-zero diff exit stops.
+
+If output is empty → "No changes to analyze." Stop.
+
+#### Step 2c: Tool Availability Check
+
+**Produces:** STATIC_TOOL_STATUS
+
+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
+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"
+```
+
+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, STATIC_STATUS
+**Requires:** STATIC_TOOL_STATUS, DIFF_RANGE, ANALYSIS_DIR
+
+Skip if Step 2c set `STATIC_STATUS`.
+
+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
+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"
+```
+
+**Snyk Code** (if available):
+```bash
+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"
+```
+Read `error` as HIGH, `warning` as MEDIUM, `note` as LOW.
+
+**CodeQL** (if available AND (`--full` OR Semgrep/Snyk found HIGH/CRITICAL findings)):
+```bash
+CODEQL_TMP=$(mktemp -d) || exit
+trap 'rm -rf "${CODEQL_TMP}"' EXIT INT TERM
+{ 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=$?
+printf '\nexit=%s\n' "$CODEQL_EXIT"
+rm -rf "${CODEQL_TMP}"
+trap - EXIT INT TERM
+```
+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).
+
+`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`.
+
+`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.
+
+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
+
+**Produces:** FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PLAN_CONTEXT, ACCEPTANCE_RULES
+
+#### Feature Knowledge
+
+### Load Feature Knowledge
+
+Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the index cache:**
+
+Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
+
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
+
+**Step 3 — Pick relevant KBs:**
+
+Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+
+**Step 4 — Read each selected KB's Rules:**
+
+For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
+
+1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
+3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
+
+When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
+
+**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+
+Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
+
+```
+--- Feature knowledge: {slug} ---
+KB: .devflow/features/{slug}/KNOWLEDGE.md
+Rules:
+- **KB-AP-2** {bullet text, verbatim}
+- **KB-INV-1** {bullet text, verbatim}
+Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
+```
+
+A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
+
+**One git call, then direct reads — no `.cjs` script.**
+
+#### 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; 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
+
+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 |
+| `usability` | Any `.tsx`, `.jsx`, `.html`, or `.css` file changed |
+
+### Phase 5: Parallel Bug Analysis
+
+**Produces:** ANALYZER_OUTPUTS
+**Requires:** DIFF_RANGE, ANALYSIS_DIR, ACTIVE_FOCUSES, STATIC_FINDINGS, ACCEPTANCE_RULES, PLAN_CONTEXT, FEATURE_KNOWLEDGE
+
+Spawn ALL active Debug agents **in a single message** (parallel, NOT background):
+
+For each active focus, spawn:
+```
+Agent(subagent_type="Debug", run_in_background=false):
+"Analyze focusing on {focus}.
+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>{STATIC_FINDINGS if focus == security, else (none)}</static-findings>
+FEATURE_KNOWLEDGE: {FEATURE_KNOWLEDGE}
+PR_DESCRIPTION: <pr-description>{PR_DESCRIPTION}</pr-description>
+OUTPUT_PATH: {ANALYSIS_DIR}/{focus}.md
+Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE.
+IMPORTANT: Write the report to OUTPUT_PATH using the Write tool"
+```
+
+### Phase 6: Synthesis
+
+**Produces:** BUG_ANALYSIS_SUMMARY
+**Requires:** ANALYZER_OUTPUTS, ANALYSIS_DIR, BRANCH_INFO, STATIC_STATUS
+
+Spawn Synthesize agent:
+
+```
+Agent(subagent_type="Synthesize", run_in_background=false):
+"Mode: bug-analysis
+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, STATIC_STATUS
+
+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}
+{any base `TRACEABILITY: DEGRADED` line from Phase 1, as returned, and the compliance-off line of Phase 1}
+**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
+{The summary's Bug Summary table: Security, Functional, Integration and Usability rows by CRITICAL, HIGH, MEDIUM, LOW and Total}
+
+### Top Findings
+{Top 3-5 bugs by severity and confidence}
+
+### Artifacts
+- Bug report: {ANALYSIS_DIR}/bug-analysis-summary.md
+- 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.
+```
+
+## Architecture
+
+Seven phases: Phase 1 to Phase 7.
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| 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." |
+| `--full` flag | Bypass incremental detection (Step 2a), run full diff from base |
+| 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
+
+`/resolve` detects and uses bug analysis reports when no code review report exists.
+
+## Principles
+
+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 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.