devflow-kit 1.8.2 → 2.0.0

package/dist/cli.js

@@ -3,13 +3,22 @@ import { Command } from 'commander';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { initCommand } from './commands/init.js';
-import { uninstallCommand } from './commands/uninstall.js';
-import { listCommand } from './commands/list.js';
-import { ambientCommand } from './commands/ambient.js';
-import { memoryCommand } from './commands/memory.js';
-import { skillsCommand } from './commands/skills.js';
-import { hudCommand } from './commands/hud.js';
+import { initCommand } from './cli/commands/init.js';
+import { uninstallCommand } from './cli/commands/uninstall.js';
+import { ambientCommand } from './cli/commands/ambient.js';
+import { memoryCommand } from './cli/commands/memory.js';
+import { skillsCommand } from './cli/commands/skills.js';
+import { hudCommand } from './cli/commands/hud.js';
+import { flagsCommand } from './cli/commands/flags.js';
+import { knowledgeCommand } from './cli/commands/knowledge/index.js';
+import { learningCommand } from './cli/commands/learning.js';
+import { rulesCommand } from './cli/commands/rules.js';
+import { debugCommand } from './cli/commands/debug.js';
+import { securityCommand } from './cli/commands/security.js';
+import { safeDeleteCommand } from './cli/commands/safe-delete.js';
+import { proxyCommand } from './cli/commands/proxy.js';
+import { agentsCommand } from './cli/commands/agents.js';
+import { complianceCommand } from './cli/commands/compliance.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Read version from package.json
@@ -20,17 +29,33 @@ program
     .description('Agentic Development Toolkit for Claude Code\n\nEnhance your AI-assisted development with intelligent commands and workflows.')
     .version(packageJson.version, '-v, --version', 'Display version number')
     .helpOption('-h, --help', 'Display help information')
-    .addHelpText('after', '\nExamples:\n  $ devflow init                       Install all DevFlow plugins\n  $ devflow init --plugin=implement    Install specific plugin\n  $ devflow init --plugin=implement,review  Install multiple plugins\n  $ devflow list                       List available plugins\n  $ devflow ambient --enable           Enable always-on ambient mode\n  $ devflow memory --status            Check working memory state\n  $ devflow hud --configure            Configure HUD preset\n  $ devflow uninstall                  Remove DevFlow from Claude Code\n  $ devflow --version                  Show version\n  $ devflow --help                     Show help\n\nDocumentation:\n  https://github.com/dean0x/devflow#readme');
+    .addHelpText('after', '\nExamples:\n  $ devflow init                       Install all Devflow plugins\n  $ devflow init --plugin=implement    Install specific plugin\n  $ devflow init --plugin=implement,code-review  Install multiple plugins\n  $ devflow ambient --enable           Enable always-on ambient mode\n  $ devflow memory --status            Check working memory state\n  $ devflow hud --status               Show current HUD config\n  $ devflow security --status          Check security deny list state\n  $ devflow security --disable         Remove the security deny list\n  $ devflow safe-delete --status       Check safe-delete shell function state\n  $ devflow safe-delete --enable       Install safe-delete shell function\n  $ devflow uninstall                  Remove Devflow from Claude Code\n  $ devflow --version                  Show version\n  $ devflow --help                     Show help\n\nDocumentation:\n  https://github.com/dean0x/devflow#readme');
 // Register commands
 program.addCommand(initCommand);
 program.addCommand(uninstallCommand);
-program.addCommand(listCommand);
 program.addCommand(ambientCommand);
 program.addCommand(memoryCommand);
 program.addCommand(skillsCommand);
 program.addCommand(hudCommand);
-// Handle no command
+program.addCommand(flagsCommand);
+program.addCommand(knowledgeCommand);
+program.addCommand(learningCommand);
+program.addCommand(rulesCommand);
+program.addCommand(debugCommand);
+program.addCommand(securityCommand);
+program.addCommand(safeDeleteCommand);
+program.addCommand(proxyCommand);
+program.addCommand(agentsCommand);
+program.addCommand(complianceCommand);
+// Handle no command (bare `devflow`) or unknown subcommand.
+// When Commander sees an unrecognised first argument it does not route to any
+// registered subcommand; instead the root action fires with that argument
+// present in program.args. Detect that case and exit non-zero so callers
+// (scripts, CI) can distinguish a typo from a successful no-op help print.
 program.action(() => {
+    if (program.args.length > 0) {
+        program.error(`unknown command '${program.args[0]}'`);
+    }
     program.help();
 });
 // Parse arguments

package/dist/commands/bug-analysis.md

@@ -0,0 +1,400 @@
+---
+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 by combining static analysis tools with parallel semantic analyzers, then synthesizing results into an actionable bug report. Supports incremental analysis, timestamped report directories, and `/resolve` compatibility.
+
+## 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)
+```
+
+## Phases
+
+### Phase 1: Pre-flight
+
+**Produces:** BRANCH_INFO, PR_DESCRIPTION, COMPLIANCE_SKILL_INSTALLED
+
+**Resolve `COMPLIANCE_SKILL_INSTALLED` once per run:** Check whether `~/.claude/skills/devflow:compliance/SKILL.md` exists (one file-existence check, read-only, silent). Set `COMPLIANCE_SKILL_INSTALLED = true` if the file exists, `false` otherwise.
+Reuse this result for every downstream phase.
+
+Spawn Git agent:
+
+```
+Agent(subagent_type="Git", run_in_background=false):
+"OPERATION: ensure-pr-ready
+COMPLIANCE: {COMPLIANCE_SKILL_INSTALLED ? "enabled" : "(none)"}
+Validate branch, commit if needed, push, create PR if needed.
+Return: branch, base_branch, branch-slug, PR#"
+```
+
+**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number`.
+
+**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)`.
+
+### Phase 2: Static Analysis
+
+**Requires:** BRANCH_INFO
+
+#### Step 2a: Incremental Detection & Timestamp Setup
+
+**Produces:** DIFF_RANGE, ANALYSIS_DIR
+**Requires:** BRANCH_INFO
+
+1. Check `.devflow/docs/bug-analysis/{branch-slug}/.last-analysis-head`:
+   - **If exists AND `--full` NOT set:**
+     - Read the SHA from the file
+     - Verify reachable: `git cat-file -t {sha}` — if exit code non-zero (rebase invalidated SHA), fall through to full
+     - If SHA == current HEAD → "No new commits since last analysis. Use --full for a full re-analysis." Stop.
+     - Set `DIFF_RANGE` to `{sha}...HEAD`
+   - **If not exists, unreachable SHA, or `--full`:**
+     - Set `DIFF_RANGE` to `{base_branch}...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 .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 result as `CHANGED_FILES` — used throughout Steps 2d and Phase 4 to avoid repeated git invocations and ensure consistency.
+
+If output is empty → "No changes to analyze." Stop.
+
+#### Step 2c: Tool Availability Check
+
+**Produces:** STATIC_TOOL_STATUS
+
+Skip if `--no-static` flag provided.
+
+```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")
+```
+
+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)`.
+
+If some are available: note which tools will run.
+
+#### Step 2d: Tiered Static Analysis
+
+**Produces:** STATIC_FINDINGS
+**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).
+
+**Semgrep and Snyk run in parallel** — launch both in the background, then wait for both before proceeding to CodeQL. CodeQL is conditional and sequential (it needs Semgrep/Snyk results to decide whether to run).
+
+**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
+```
+Parse SARIF output → extract findings.
+
+**Snyk Code** (if available):
+```bash
+# Run a single project-level scan; filter SARIF results programmatically to CHANGED_FILES before LLM processing.
+# Per-file invocation via xargs would invoke snyk O(n) times and --file is for dependency scanning, not source code.
+SNYK_SARIF=$(timeout 300 snyk code test --sarif 2>/dev/null)
+# Programmatic filter: keep only results whose file path appears in CHANGED_FILES.
+# This is defense-in-depth — filtering at the data layer 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")
+```
+Parse `SNYK_FILTERED` SARIF → extract findings. If `jq` is unavailable, fall back to the raw `SNYK_SARIF` and note the limitation.
+
+**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
+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_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)
+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 to bound the serialized size of `STATIC_FINDINGS`:
+
+| Tool | File:Line | CWE | Severity | Title | Description |
+|------|-----------|-----|----------|-------|-------------|
+| {tool} | {file}:{line} | {CWE or —} | {CRITICAL/HIGH/MEDIUM/LOW} | {title} | {description truncated to 200 chars} |
+
+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)`.
+
+### Phase 3: Context Loading
+
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PLAN_CONTEXT, ACCEPTANCE_RULES
+
+#### Decisions Index
+
+### Load DECISIONS_CONTEXT
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the pre-rendered index:**
+
+Attempt to read `{worktree}/.devflow/learning/index.md`.
+
+- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
+- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+
+**No subprocess, no `.cjs` script.** This is a single direct file read — the index is written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md`.
+
+**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+
+#### Feature Knowledge
+
+### Load Feature Knowledge
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). 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 selected KBs:**
+
+For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+
+**Step 5 — Set FEATURE_KNOWLEDGE:**
+
+Concatenate the selected KNOWLEDGE.md files under slug headers:
+
+```
+--- Feature knowledge: {slug} ---
+{full KNOWLEDGE.md content}
+```
+
+If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+
+**No subprocess, no git calls, no `.cjs` script.** This entire step is direct file reads — 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+
+#### Plan Artifact
+
+1. List `.devflow/docs/design/*.md` — sort descending by filename (timestamps are naturally sortable), scan the 10 most recent
+2. Read the most recent file if it exists
+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)`
+
+### 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`):
+
+| Focus | Condition |
+|-------|-----------|
+| `security` | Always |
+| `functional` | Always |
+| `integration` | 2+ distinct directories changed (`dirname` unique count ≥ 2) |
+| `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, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+
+Spawn ALL active Diagnose agents **in a single message** (parallel, NOT background):
+
+For each active focus, spawn:
+```
+Agent(subagent_type="Diagnose", 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 if focus == security, else (none)}
+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"
+```
+
+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
+
+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}
+Output: {ANALYSIS_DIR}/bug-analysis-summary.md"
+```
+
+### Phase 7: Finalize
+
+**Requires:** BRANCH_INFO, ANALYSIS_DIR
+
+1. Write current HEAD SHA to `.devflow/docs/bug-analysis/{branch-slug}/.last-analysis-head`
+2. Report to user:
+
+```
+## Bug Analysis Complete
+
+**Branch**: {branch} -> {base_branch}
+**Analysis**: {ANALYSIS_DIR}
+
+### 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} |
+
+### Top Findings
+{List 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)
+
+{if any CRITICAL or HIGH bugs found:}
+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
+│  ├─ Step 2a: Incremental detection + timestamp setup
+│  ├─ Step 2b: Check changed files (stop if none)
+│  ├─ Step 2c: Tool availability check
+│  └─ Step 2d: Tiered static analysis (semgrep → snyk → codeql)
+│              Write static-findings.md
+│
+├─ Phase 3: Context Loading
+│  ├─ index.md (pre-rendered) → DECISIONS_CONTEXT
+│  ├─ Feature knowledge load → FEATURE_KNOWLEDGE
+│  └─ .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)
+│  ├─ Diagnose agent: security (+ STATIC_FINDINGS)
+│  ├─ Diagnose agent: functional
+│  ├─ Diagnose agent: integration (conditional)
+│  └─ Diagnose agent: usability (conditional)
+│
+├─ Phase 6: Synthesis
+│  └─ Synthesize agent (mode: bug-analysis)
+│
+└─ Phase 7: Finalize
+   ├─ Write .last-analysis-head
+   └─ Display results + suggest /resolve if blocking bugs found
+```
+
+## 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 | 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 |
+| Static tool produces no findings | `STATIC_FINDINGS=(none)` — normal, proceed with semantic analysis |
+| No plan artifact found | `PLAN_CONTEXT=(none)`, `ACCEPTANCE_RULES=(none)` — proceed without acceptance criteria |
+| `integration` focus skipped | Not spawned when only 1 directory changed |
+| `usability` focus skipped | Not spawned when no UI files changed |
+
+## 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.
+
+## 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** — Diagnose agents self-verify every finding
+6. **Honest reporting** — Display risk level and counts directly from synthesis
+
+## 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.