deepflow 0.1.67 → 0.1.69

package/README.md

@@ -77,20 +77,21 @@ You write the specs, then walk away. The AI runs the full pipeline — hypothesi
 ```bash
 # You define WHAT (the specs), the AI figures out HOW, overnight
 
+# Requires Agent Teams (experimental feature)
+export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+
 deepflow auto                    # process all specs in specs/
-deepflow auto --parallel=3       # 3 approaches in parallel
-deepflow auto --hypotheses=4     # 4 hypotheses per cycle
-deepflow auto --max-cycles=5     # cap retry cycles
 ```
 
 **What the AI does alone:**
-1. Discovers specs (auto-promotes plain specs to `doing-*`)
-2. Generates N hypotheses for how to implement each spec
-3. Runs parallel spikes in isolated worktrees (one per hypothesis)
-4. Implements the passing approaches
-5. Adversarial selection: a fresh AI context compares approaches by artifacts only (never reads code), picks the best or rejects all
-6. If rejected: generates new hypotheses, retries (up to max-cycles)
-7. On convergence: verifies, merges to main
+1. Pre-checks if spec is already satisfied (skips if so)
+2. Discovers specs, respects `depends_on` ordering
+3. Generates N hypotheses for how to implement each spec
+4. Runs parallel spikes in isolated worktrees (one per hypothesis)
+5. Implements the passing approaches
+6. Adversarial selection: a fresh AI context compares approaches by artifacts only (never reads code), picks the best or rejects all
+7. If rejected: generates new hypotheses, retries (up to max-cycles)
+8. On convergence: verifies (L0-L4 gates), creates PR, merges to main
 
 **What you do:** Write specs (via interactive mode or manually) in `specs/`, run `deepflow auto`, read the morning report at `.deepflow/auto-report.md`. No need to run `/df:plan` first — auto mode promotes plain specs to `doing-*` automatically.
 
@@ -102,7 +103,8 @@ $ claude
 > /df:spec auth          # creates specs/auth.md
 > /exit
 
-# In your terminal — run auto mode and walk away
+# In your terminal — enable agent teams and run auto mode
+$ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
 $ deepflow auto
 
 # Next morning — check what happened
@@ -165,9 +167,11 @@ $ git log --oneline
 
 ```
 deepflow auto
-    | Discover specs (auto-promote plain specs to doing-*)
+    | Discover specs (auto-promote, topological sort by depends_on)
     | For each doing-* spec:
     |
+    |   Pre-check (Haiku: already satisfied? skip)
+    |       v
     |   Validate spec (malformed? skip)
     |       v
     |   Generate N hypotheses
@@ -177,7 +181,7 @@ deepflow auto
     |     | Fail? -> record experiment, discard
     |       v
     |   Adversarial selection (fresh context, artifacts only)
-    |     | Winner? -> verify & merge
+    |     | Winner? -> verify (L0-L4) -> PR -> merge
     |     | Reject all? -> new hypotheses, retry
     |       v
     |   Morning report -> .deepflow/auto-report.md

package/bin/install.js

@@ -24,7 +24,7 @@ if (process.argv[2] === 'auto') {
     process.exit(1);
   }
   try {
-    execFileSync('claude', ['--agent', '.claude/agents/deepflow-auto.md', ...process.argv.slice(3)], { stdio: 'inherit' });
+    execFileSync('claude', ['--agent', '.claude/agents/deepflow-auto.md', '-p', 'Run the full autonomous cycle. Process all doing-* specs.', ...process.argv.slice(3)], { stdio: 'inherit' });
   } catch (e) {
     process.exit(e.status || 1);
   }
@@ -198,8 +198,7 @@ async function main() {
   console.log(`Installed to ${c.cyan}${CLAUDE_DIR}${c.reset}:`);
   console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:note, /df:resume, /df:update');
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness');
-  console.log('  agents/          — reasoner');
-  console.log('  bin/             — deepflow auto (autonomous overnight execution)');
+  console.log('  agents/          — reasoner, deepflow-auto (autonomous overnight execution)');
   if (level === 'global') {
     console.log('  hooks/           — statusline, update checker');
   }
@@ -414,7 +413,8 @@ async function uninstall() {
     'skills/atomic-commits',
     'skills/code-completeness',
     'skills/gap-discovery',
-    'agents/reasoner.md'
+    'agents/reasoner.md',
+    'agents/deepflow-auto.md'
   ];
 
   if (level === 'global') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "description": "Stay in flow state - lightweight spec-driven task orchestration for Claude Code",
   "keywords": [
     "claude",

package/src/agents/deepflow-auto.md

@@ -0,0 +1,667 @@
+---
+name: deepflow-auto-lead
+description: Lead orchestrator — drives specs from discovery through convergence via teammate agents
+model: sonnet
+env:
+  CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "50"
+---
+
+# Deepflow Auto Lead Agent
+
+You orchestrate the autonomous deepflow cycle: discover → hypothesize → spike → implement → select → verify → PR. Each phase spawns fresh teammates — never reuse context across phase boundaries.
+
+## Model Routing
+
+| Role | Model | Rationale |
+|------|-------|-----------|
+| Lead (you) | Sonnet | Cheap coordination |
+| Pre-check subagent | Haiku | Fast read-only exploration |
+| Spike teammates | Sonnet | Exploratory, disposable |
+| Implementation teammates | Opus | Thorough, production code |
+| Judge subagent | Opus | Adversarial quality gate |
+| Verifier subagent | Opus | Rigorous gate checks |
+
+## Logging
+
+Append every decision to `.deepflow/auto-decisions.log` in this format:
+```
+[YYYY-MM-DDTHH:MM:SSZ] message
+```
+Log: phase starts, hypothesis generation, spike pass/fail, selection verdicts, errors, worktree operations.
+
+## Phase 1: DISCOVER (you do this)
+
+1. Run spec lint if `hooks/df-spec-lint.js` exists: `node hooks/df-spec-lint.js specs/doing-*.md --mode=auto`. Skip specs that fail.
+2. List all `specs/doing-*.md` files. Auto-promote any unprefixed `specs/*.md` to `doing-*.md` (skip `done-*`, dotfiles).
+3. If no specs found → log error, generate report, stop.
+4. **Build dependency DAG and determine processing order.**
+
+   #### 4a. Parse dependencies
+
+   For each spec file collected in step 2, extract its `## Dependencies` section. Parse each line matching the pattern `- depends_on: <name>`. The `<name>` value may appear in several forms — normalize all of them to the bare spec name:
+   - `doing-foo.md` → `foo`
+   - `doing-foo` → `foo`
+   - `foo.md` → `foo`
+   - `foo` → `foo` (already bare)
+
+   Build an **adjacency list** (map of spec-name → list of dependency spec-names). If a dependency references a spec not in the current set of `doing-*` files, log a warning: `dependency '{dep}' referenced by '{spec}' not found in active specs — ignoring` and skip that edge.
+
+   #### 4b. Topological sort (Kahn's algorithm)
+
+   Compute a processing order that respects dependencies:
+
+   1. Build an **in-degree map**: for each spec, count how many other specs it depends on (among active specs only).
+   2. Initialize a **queue** with all specs that have in-degree 0 (no dependencies).
+   3. Initialize an empty **sorted list**.
+   4. While the queue is not empty:
+      - Remove a spec from the queue and append it to the sorted list.
+      - For each spec that depends on the removed spec, decrement its in-degree by 1.
+      - If any spec's in-degree reaches 0, add it to the queue.
+   5. After the loop, if the sorted list contains fewer specs than the total number of active specs, a **circular dependency** exists — proceed to step 4c.
+   6. Otherwise, use the sorted list as the processing order for all subsequent phases.
+
+   #### 4c. Circular dependency handling
+
+   If a cycle is detected (sorted list is shorter than total specs):
+
+   1. Identify the cycle: collect all specs NOT in the sorted list. Walk their dependency edges to find and report one cycle path (e.g., `A → B → C → A`).
+   2. Log a fatal error to `.deepflow/auto-decisions.log`:
+      ```
+      [YYYY-MM-DDTHH:MM:SSZ] FATAL: circular dependency detected: A → B → C → A
+      ```
+   3. Generate the error report (Phase 8) with overall status `halted` and the cycle path in the summary.
+   4. **Stop immediately** — do not proceed to any further phases.
+
+   #### 4d. Processing order enforcement
+
+   Process specs in the topological order determined in step 4b. When processing a spec through phases 1.5–7, all of its dependencies (specs it `depends_on`) must have already completed successfully (reached Phase 7 or been skipped by pre-check). If a dependency was halted or failed, mark the dependent spec as `blocked` and skip it — log: `spec '{spec}' blocked by failed dependency '{dep}'`.
+
+## Phase 1.5: PRE-CHECK (spawn a fresh subagent per spec, model: haiku, tools: Read/Grep/Glob only)
+
+Before generating hypotheses, check if each spec's requirements are already satisfied by existing code.
+
+### 1.5a. Spawn pre-check subagent (model: haiku, read-only)
+
+For each spec, spawn a fresh Haiku subagent with tools limited to Read, Grep, and Glob.
+
+**Subagent prompt:**
+```
+You are checking whether a spec's requirements are already satisfied by existing code.
+
+--- SPEC CONTENT ---
+{spec content}
+--- END SPEC ---
+
+For each requirement in the spec, determine if the existing codebase already satisfies it.
+
+Output ONLY a JSON object (no markdown fences). The JSON must have:
+{
+  "requirements": [
+    {"id": "REQ-1", "status": "DONE|PARTIAL|MISSING", "evidence": "brief explanation"}
+  ],
+  "overall": "DONE|PARTIAL|MISSING"
+}
+
+Rules:
+- DONE = requirement is fully satisfied by existing code
+- PARTIAL = some aspects exist but gaps remain
+- MISSING = not implemented at all
+- overall is DONE only if ALL requirements are DONE
+```
+
+### 1.5b. Process pre-check result
+
+1. Parse JSON from subagent output.
+2. If `overall: "DONE"`:
+   - Log: `already-satisfied: {spec-name} — all requirements met, skipping`
+   - Skip this spec entirely (do not hypothesize, spike, or implement).
+3. If `overall: "PARTIAL"`:
+   - Log each PARTIAL/MISSING requirement.
+   - Include the pre-check results in the hypothesis prompt (Phase 2b) so the teammate focuses on gaps.
+4. If `overall: "MISSING"` or parse fails:
+   - Proceed normally to Phase 2.
+
+## Phase 2: HYPOTHESIZE (spawn a fresh teammate per spec, model: sonnet)
+
+For each spec:
+
+### 2a. Gather failed experiment context
+
+1. Glob `.deepflow/experiments/{spec-name}--*--failed.md` files.
+2. For each failed file, extract:
+   - The `## Hypothesis` section (from header to next `##`)
+   - The `## Conclusion` section (from header to next `##` or EOF)
+3. Build a `failed_context` block:
+   ```
+   --- Failed experiment: {filename} ---
+   ## Hypothesis
+   {extracted hypothesis}
+   ## Conclusion
+   {extracted conclusion}
+   ```
+
+### 2b. Spawn hypothesis teammate
+
+Spawn a fresh teammate with this prompt:
+
+```
+You are helping with an autonomous development workflow. Given the following spec, generate exactly {N} approach hypotheses for implementing it.
+
+--- SPEC CONTENT ---
+{spec content}
+--- END SPEC ---
+{if failed_context is not empty:}
+The following hypotheses have already been tried and FAILED. Do NOT repeat them or suggest similar approaches:
+
+{failed_context}
+{end if}
+{if pre_check_context is not empty (from Phase 1.5, overall=PARTIAL):}
+A pre-check found that some requirements are already partially satisfied. Focus your hypotheses on the gaps:
+
+{pre_check_context — the JSON requirements array filtered to PARTIAL/MISSING only}
+{end if}
+Generate exactly {N} hypotheses as a JSON array. Each object must have:
+- "slug": a URL-safe lowercase hyphenated short name (e.g. "stream-based-parser")
+- "hypothesis": a one-sentence description of the approach
+- "method": a one-sentence description of how to validate this approach
+
+Output ONLY the JSON array. No markdown fences, no explanation, no extra text. Just the raw JSON array.
+```
+
+### 2c. Process teammate output
+
+1. Extract JSON array from output (handle accidental wrapping — try `[...\n...]` first, then single-line `[...]`).
+2. If JSON parse fails → log error, return failure for this spec.
+3. Write to `.deepflow/hypotheses/{spec-name}-cycle-{N}.json`.
+4. Log each hypothesis slug. Warn if count differs from requested N.
+5. Default N = 2 (configurable).
+
+## Phase 3: SPIKE (parallel teammates, model: sonnet)
+
+For each hypothesis from the cycle JSON file:
+
+### 3a. Create worktree per hypothesis
+
+```bash
+WORKTREE=".deepflow/worktrees/{spec-name}-{slug}"
+BRANCH="df/{spec-name}-{slug}"
+
+# Try create new; fall back to reuse existing branch
+git worktree add -b "$BRANCH" "$WORKTREE" HEAD 2>/dev/null \
+  || git worktree add "$WORKTREE" "$BRANCH" 2>/dev/null
+
+# If worktree already exists on disk, reuse it
+```
+
+If both fail and worktree directory exists, reuse it. If worktree truly cannot be created, treat hypothesis as failed and continue.
+
+### 3b. Extract acceptance criteria
+
+Read the spec file. Extract the `## Acceptance Criteria` section (from that header to the next `##` or EOF). Pass this to the spike teammate as the human's judgment proxy.
+
+### 3c. Spawn spike teammate (model: sonnet)
+
+Spawn up to 2 teammates in parallel (configurable). Each runs in its worktree directory.
+
+**Teammate prompt:**
+```
+You are running a spike experiment to validate a hypothesis for spec '{spec-name}'.
+
+--- HYPOTHESIS ---
+Slug: {slug}
+Hypothesis: {hypothesis}
+Method: {method}
+--- END HYPOTHESIS ---
+
+--- ACCEPTANCE CRITERIA (from spec — the human's judgment proxy) ---
+{acceptance criteria}
+--- END ACCEPTANCE CRITERIA ---
+
+Your tasks:
+1. Validate this hypothesis by implementing the minimum necessary to prove or disprove it.
+   The spike must demonstrate that the approach can satisfy the acceptance criteria above.
+2. Create directories if needed: .deepflow/experiments/ and .deepflow/results/
+3. Write an experiment file at: .deepflow/experiments/{spec-name}--{slug}--active.md
+   Sections:
+   - ## Hypothesis: restate the hypothesis
+   - ## Method: what you did to validate
+   - ## Results: what you observed
+   - ## Criteria Check: for each acceptance criterion, can this approach satisfy it? (yes/no/unclear)
+   - ## Conclusion: PASSED or FAILED with reasoning
+4. Write a result YAML file at: .deepflow/results/spike-{slug}.yaml
+   Fields: slug, spec, status (passed/failed), summary
+5. Stage and commit all changes: spike({spec-name}): validate {slug}
+
+Important:
+- Be concise and focused — this is a spike, not a full implementation.
+- If the hypothesis is not viable, mark it as failed and explain why.
+```
+
+### 3d. Post-spike result processing
+
+After ALL spike teammates complete, process results sequentially:
+
+For each hypothesis slug:
+1. Read `{worktree}/.deepflow/results/spike-{slug}.yaml`
+2. If file exists and `status: passed`:
+   - Log `PASSED spike: {slug}`
+   - Rename experiment: `{worktree}/.deepflow/experiments/{spec-name}--{slug}--active.md` → `--passed.md`
+   - Add slug to passed list
+3. If file exists and `status: failed`, OR file is missing:
+   - Log `FAILED spike: {slug}` (or `MISSING RESULT: {slug} — treating as failed`)
+   - Rename experiment: `--active.md` → `--failed.md`
+   - Copy failed experiment to main project: `{project-root}/.deepflow/experiments/{spec-name}--{slug}--failed.md`
+4. Write passed hypotheses JSON: `.deepflow/hypotheses/{spec-name}-cycle-{N}-passed.json`
+   - Array of `{slug, hypothesis, method}` objects for passed slugs only
+   - Empty array `[]` if none passed
+
+## Phase 4: IMPLEMENT (parallel teammates, model: opus)
+
+For each passed hypothesis (from `{spec-name}-cycle-{N}-passed.json`), spawn a teammate in the EXISTING worktree (`.deepflow/worktrees/{spec-name}-{slug}`). The implementation teammate builds on spike commits — this is critical.
+
+### 4a. Pre-checks
+
+1. Read passed hypotheses JSON. If empty or missing → skip implementations, proceed to SELECT (it will reject).
+2. For each slug, verify worktree exists at `.deepflow/worktrees/{spec-name}-{slug}`. If missing → log error, skip that slug.
+
+### 4b. Spawn implementation teammate (model: opus)
+
+Spawn up to 2 teammates in parallel. Each runs in its hypothesis worktree.
+
+**Teammate prompt:**
+```
+You are implementing tasks for spec '{spec-name}' in an autonomous development workflow.
+The spike experiment for approach '{slug}' has passed validation. Now implement the full solution.
+
+--- SPEC CONTENT ---
+{full spec content}
+--- END SPEC ---
+
+The validated experiment file is at: .deepflow/experiments/{spec-name}--{slug}--passed.md
+Review it to understand the approach that was validated during the spike.
+
+Your tasks:
+1. Read the spec carefully and generate a list of implementation tasks from it.
+2. Implement each task with atomic commits. Each commit message must follow the format:
+   feat({spec-name}): {task description}
+3. For each completed task, write a result YAML file at:
+   .deepflow/results/{task-slug}.yaml
+   Each YAML must contain:
+   - task: short task name
+   - spec: {spec-name}
+   - status: passed OR failed
+   - summary: one-line summary of what was implemented
+4. Create the .deepflow/results directory if it does not exist.
+
+Important:
+- Build on top of the spike commits already in this worktree.
+- Be thorough — this is the full implementation, not a spike.
+- Stage and commit each task separately for clean atomic commits.
+```
+
+### 4c. Post-implementation result collection
+
+After ALL implementation teammates complete:
+
+For each slug:
+1. Read all `.deepflow/results/*.yaml` files from the worktree (exclude `spike-*.yaml`)
+2. Count by status: passed vs failed
+3. Log: `Implementation {slug}: {N} tasks ({P} passed, {F} failed)`
+4. If no result files found → log warning
+
+## Phase 5: SELECT (single subagent, model: opus, tools: Read/Grep/Glob only)
+
+### 5a. Gather artifacts
+
+For each approach slug (from the cycle hypotheses JSON):
+1. Read ALL `.deepflow/results/*.yaml` files from the approach worktree
+2. Read the passed experiment file: `.deepflow/experiments/{spec-name}--{slug}--passed.md`
+3. Build an artifacts block:
+   ```
+   === APPROACH {N}: {slug} ===
+   --- Result: {filename}.yaml ---
+   {yaml content}
+   --- Experiment: {spec-name}--{slug}--passed.md ---
+   {experiment content}
+   === END APPROACH {N} ===
+   ```
+
+Do NOT include source code or file paths in the artifacts block.
+
+### 5b. Spawn judge subagent (model: opus, tools: Read/Grep/Glob only)
+
+Extract acceptance criteria from the spec (`## Acceptance Criteria` section).
+
+**Subagent prompt:**
+```
+You are an adversarial quality judge in an autonomous development workflow.
+Your job is to compare implementation approaches for spec '{spec-name}' and select the best one — or reject all if quality is insufficient.
+
+IMPORTANT:
+- This selection phase ALWAYS runs, even with only 1 approach. With a single approach you act as a quality gate.
+- You CAN and SHOULD reject all approaches if the quality is insufficient. Do not rubber-stamp poor work.
+- Base your judgment ONLY on the artifacts provided below. Do NOT read code files.
+- Judge each approach against the ACCEPTANCE CRITERIA below — these represent the human's intent.
+
+--- ACCEPTANCE CRITERIA (from spec) ---
+{acceptance criteria}
+--- END ACCEPTANCE CRITERIA ---
+
+There are {N} approach(es) to evaluate:
+
+{artifacts block}
+
+Respond with ONLY a JSON object (no markdown fences, no explanation). The JSON must have this exact structure:
+
+{
+  "winner": "slug-of-winner-or-empty-string-if-rejecting-all",
+  "rankings": [
+    {"slug": "approach-slug", "rank": 1, "rationale": "why this rank"},
+    {"slug": "approach-slug", "rank": 2, "rationale": "why this rank"}
+  ],
+  "reject_all": false,
+  "rejection_rationale": ""
+}
+
+Rules for the JSON:
+- rankings must include ALL approaches, ranked from best (1) to worst
+- If reject_all is true, winner must be an empty string and rejection_rationale must explain why
+- If reject_all is false, winner must be the slug of the rank-1 approach
+- Output ONLY the JSON object. No other text.
+```
+
+### 5c. Process verdict
+
+Parse the JSON output. Handle extraction failures gracefully (try `{...}` block first, then single-line match).
+
+**If `reject_all: true`:**
+1. Log rejection rationale
+2. Keep only the best-ranked worktree (rank 1), clean up others: `git worktree remove --force`, `git branch -D`
+3. Loop back to HYPOTHESIZE (next cycle). The failed context from Phase 2a will prevent repeats.
+
+**If winner selected:**
+1. Log: `SELECTED winner '{slug}'`
+2. Write `.deepflow/selection/{spec-name}-winner.json`:
+   ```json
+   {"spec": "{spec-name}", "cycle": {N}, "winner": "{slug}", "selection_output": {full JSON verdict}}
+   ```
+3. Clean up ALL non-winner worktrees and branches: `git worktree remove --force {path}`, `git branch -D df/{spec-name}-{slug}`
+
+## Phase 6: VERIFY (subagent, model: opus)
+
+Spawn a fresh verifier subagent on the winner worktree (`.deepflow/worktrees/{spec-name}-{winner-slug}`).
+
+### 6a. Spawn verifier subagent (model: opus)
+
+**Subagent prompt:**
+```
+You are verifying the implementation for spec '{spec-name}' in worktree '.deepflow/worktrees/{spec-name}-{winner-slug}'.
+
+Run the following verification gates in order. Stop at the first failure.
+
+L0 — Build: Run the project build command (npm run build, cargo build, go build ./..., make build, etc.) if one exists. Must succeed. If no build command detected, skip.
+L1 — Exists: Verify that all files and functions referenced in the spec exist (use Glob/Grep).
+L2 — Substantive: Read key files and verify real implementations, not stubs or TODOs.
+L3 — Wired: Verify implementations are integrated into the system (imports, calls, routes, etc.).
+L4 — Tests: Run the project test command (npm test, pytest, cargo test, go test ./..., make test, etc.). All must pass. If no test command detected, skip.
+
+After L0-L4 gates, also check acceptance criteria from the spec against the implementation.
+
+Skip PLAN.md readiness check (not applicable in auto mode).
+
+Output a JSON object:
+{
+  "passed": true/false,
+  "gates": [
+    {"level": "L0", "status": "passed|failed|skipped", "detail": "..."},
+    {"level": "L1", "status": "passed|failed|skipped", "detail": "..."},
+    {"level": "L2", "status": "passed|failed|skipped", "detail": "..."},
+    {"level": "L3", "status": "passed|failed|skipped", "detail": "..."},
+    {"level": "L4", "status": "passed|failed|skipped", "detail": "..."}
+  ],
+  "summary": "one-line summary"
+}
+```
+
+### 6b. Process verification result
+
+1. Parse JSON from verifier output.
+2. If `passed: false`:
+   - Log: `VERIFY FAILED for {spec-name}/{winner-slug}: {summary}`
+   - Log each failed gate with detail.
+   - Mark spec as `halted`. Preserve winner worktree for inspection.
+   - Proceed to REPORT (Phase 8). Do NOT create PR.
+3. If `passed: true`:
+   - Log: `VERIFY PASSED for {spec-name}/{winner-slug}`
+   - Proceed to PR (Phase 7).
+
+## Phase 7: PR (you do this)
+
+### 7a. Push winner branch
+
+```bash
+git push -u origin df/{spec-name}-{slug}
+```
+
+If push fails (e.g., no remote, auth error), log the error and skip PR creation — proceed directly to REPORT (Phase 8) with `pr_url` unset.
+
+### 7b. Create PR via `gh`
+
+First check if `gh` is available:
+
+```bash
+command -v gh >/dev/null 2>&1
+```
+
+**If `gh` IS available**, create a PR with a rich body. Gather these inputs:
+
+1. **Spec objective** — read the first paragraph or `## Objective` section from the spec file.
+2. **Winner rationale** — read `.deepflow/selection/{spec-name}-winner.json`, extract the rank-1 entry's `rationale` field from `selection_output.rankings`.
+3. **Diff stats** — run `git diff --stat main...df/{spec-name}-{slug}`.
+4. **Verification gates** — read the verification JSON from Phase 6 and format each gate (L0-L4) with status and detail.
+5. **Spike summary** — read `.deepflow/hypotheses/{spec-name}-cycle-{N}.json` and `.deepflow/hypotheses/{spec-name}-cycle-{N}-passed.json` to list which spikes passed and which failed.
+
+Create the PR:
+
+```bash
+gh pr create \
+  --base main \
+  --head "df/{spec-name}-{slug}" \
+  --title "feat({spec-name}): {short objective from spec}" \
+  --body "$(cat <<'PRBODY'
+## Spec: {spec-name}
+
+**Objective:** {spec objective}
+
+## Winner: {slug}
+
+**Rationale:** {rank-1 rationale from selection JSON}
+
+## Spike Summary
+
+| Spike | Status |
+|-------|--------|
+| {slug-1} | passed/failed |
+| {slug-2} | passed/failed |
+
+## Verification Gates
+
+| Gate | Status | Detail |
+|------|--------|--------|
+| L0 Build | {status} | {detail} |
+| L1 Exists | {status} | {detail} |
+| L2 Substantive | {status} | {detail} |
+| L3 Wired | {status} | {detail} |
+| L4 Tests | {status} | {detail} |
+
+## Diff Stats
+
+```
+{output of git diff --stat main...df/{spec-name}-{slug}}
+```
+
+---
+*Generated by deepflow auto*
+PRBODY
+)"
+```
+
+Capture the PR URL from `gh pr create` output. Store it as `pr_url` for Phase 8.
+
+Log: `PR created: {pr_url}`
+
+### 7c. Fallback: direct merge if `gh` unavailable
+
+**If `gh` is NOT available** (i.e., `command -v gh` fails):
+
+```bash
+git checkout main
+git merge df/{spec-name}-{slug}
+```
+
+Log a warning: `WARNING: gh CLI not available — merged directly to main instead of creating PR`
+
+Set `pr_url` to `"(direct merge — no PR created)"` for Phase 8.
+
+After the direct merge, the spec lifecycle still applies (rename `doing-*` to `done-*` etc.).
+
+### 7d. Spec lifecycle
+
+Spec stays `doing-*` until the PR is merged (or the direct merge completes). After merge/direct-merge, execute the following steps in order:
+
+#### Step 1 — Rename doing → done
+
+```bash
+git mv specs/doing-{name}.md specs/done-{name}.md
+git commit -m "lifecycle({name}): doing → done"
+```
+
+If `specs/doing-{name}.md` does not exist (e.g., already renamed), skip this step and log a warning.
+
+#### Step 2 — Decision extraction
+
+Read `specs/done-{name}.md` and extract architectural decisions. Scan the entire file for:
+
+1. **Explicit choices** (phrases like "we chose", "decided to", "selected", "approach:", "going with") → tag as `[APPROACH]`
+2. **Unvalidated assumptions** (phrases like "assuming", "we assume", "expected to", "should be") → tag as `[ASSUMPTION]`
+3. **Temporary decisions** (phrases like "for now", "temporary", "placeholder", "revisit later", "tech debt", "TODO") → tag as `[PROVISIONAL]`
+
+For each extracted decision, capture:
+- The tag (`[APPROACH]`, `[ASSUMPTION]`, or `[PROVISIONAL]`)
+- A concise one-line summary of the decision
+- The rationale (surrounding context or explicit reasoning)
+
+If no decisions are found, log: `no decisions extracted from {name}` and skip to Step 4.
+
+#### Step 3 — Write to decisions.md
+
+Append a new section to `.deepflow/decisions.md` (create the file if it does not exist):
+
+```markdown
+### {YYYY-MM-DD} — {name}
+- [APPROACH] decision text — rationale
+- [ASSUMPTION] decision text — rationale
+- [PROVISIONAL] decision text — rationale
+```
+
+Use today's date in `YYYY-MM-DD` format. Only include tags that were actually extracted.
+
+Commit the update:
+
+```bash
+git add .deepflow/decisions.md
+git commit -m "lifecycle({name}): extract decisions"
+```
+
+#### Step 4 — Delete done file
+
+After successful decision extraction (or if no decisions were found), delete the done spec:
+
+```bash
+git rm specs/done-{name}.md
+git commit -m "lifecycle({name}): archive done spec"
+```
+
+#### Step 5 — Failed extraction preserves done file
+
+If decision extraction fails (e.g., file read error, unexpected format), do NOT delete `specs/done-{name}.md`. Log the error: `decision extraction failed for {name} — preserving done file for manual review`. Proceed to Phase 8 (REPORT) normally.
+
+## Phase 8: REPORT (you do this)
+
+Generate `.deepflow/auto-report.md`. Always generate a report, even on errors or interrupts.
+
+### 8a. Determine status
+
+For each spec:
+- Winner file exists (`.deepflow/selection/{spec-name}-winner.json`) → `converged`
+- Interrupted/incomplete → `in-progress`
+- Failed without recovery → `halted`
+
+Overall status: `converged` only if ALL specs converged. Any `halted` → overall `halted`. Any `in-progress` → overall `in-progress`.
+
+### 8b. Build report
+
+```markdown
+# deepflow auto report
+
+**Status:** {overall_status}
+**Date:** {UTC timestamp}
+
+---
+
+## {spec-name}
+
+**Status:** {converged|halted|in-progress}
+**Winner:** {slug} (if converged)
+
+### Hypotheses
+{for each hypothesis in .deepflow/hypotheses/{spec-name}-cycle-{N}.json:}
+- **{slug}:** {hypothesis description}
+
+### Spike Results
+{for each worktree .deepflow/worktrees/{spec-name}-{slug}:}
+- {pass_icon} **{slug}** — {summary from spike-{slug}.yaml}
+
+### Selection Rationale
+{parse rankings from .deepflow/selection/{spec-name}-winner.json:}
+{rank 1 icon} **#{rank} {slug}:** {rationale}
+
+### Verification
+{if verification ran, show gate results from Phase 6:}
+- {status_icon} **L0 Build:** {detail}
+- {status_icon} **L1 Exists:** {detail}
+- {status_icon} **L2 Substantive:** {detail}
+- {status_icon} **L3 Wired:** {detail}
+- {status_icon} **L4 Tests:** {detail}
+{if halted: "Verification FAILED — worktree preserved for inspection at .deepflow/worktrees/{spec-name}-{winner-slug}"}
+
+### Pull Request
+{if pr_url is set and not a direct merge: "**PR:** [{pr_url}]({pr_url})"}
+{if pr_url indicates direct merge: "**Merged directly** — `gh` CLI was not available. No PR created."}
+{if pr_url is unset (e.g., push failed or verification failed): "No PR created."}
+
+### Changes
+{run: git diff --stat main...df/{spec-name}-{winner-slug}}
+
+---
+
+## Next Steps
+{if converged and pr_url is a real PR: "Review and merge PR: {pr_url}"}
+{if converged and direct merge: "Already merged to main."}
+{if in-progress: "Run `deepflow auto --continue` to resume."}
+{if halted: "Review the spec and run `deepflow auto` again."}
+```
+
+## Cycle Control
+
+| Condition | Action |
+|-----------|--------|
+| No specs found | Stop with error |
+| All spikes failed | Proceed to SELECT (it will reject) |
+| SELECT rejects all | Loop to HYPOTHESIZE (next cycle) |
+| SELECT picks winner | Verify → PR → next spec |
+| MAX_CYCLES reached | Mark halted, generate report |
+| Teammate fails to produce artifacts | Treat as failed |
+| JSON parse error | Log error, treat as failed |
+
+Always generate a report, even on errors or interrupts.