deepflow 0.1.89 → 0.1.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.89",
+  "version": "0.1.90",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",

package/src/commands/df/auto-cycle.md

@@ -3,146 +3,4 @@ name: df:auto-cycle
 description: Execute one task from PLAN.md with ratchet health checks and state tracking for autonomous mode
 ---
 
-# /df:auto-cycle — Single Cycle of Auto Mode
-
-Execute one task from PLAN.md. Called by `/loop 1m /df:auto-cycle` — each invocation gets fresh context.
-
-**NEVER:** use EnterPlanMode, use ExitPlanMode
-
-## Behavior
-
-### 1. LOAD STATE
-
-Shell injection (use output directly):
-- `` !`cat PLAN.md 2>/dev/null || echo 'NOT_FOUND'` `` — required, error if missing
-- `` !`cat .deepflow/auto-memory.yaml 2>/dev/null || echo 'NOT_FOUND'` `` — optional cross-cycle state
-
-**auto-memory.yaml schema:** see `/df:execute`. Each section optional, missing keys = empty. Created on first write if absent.
-
-### 2. PICK NEXT TASK
-
-**Optimize-active override:** Check `optimize_state.task_id` in auto-memory.yaml first. If present and task still `[ ]` in PLAN.md, resume it (skip normal scan). If task is `[x]`, clear `optimize_state.task_id` and fall through.
-
-**Normal scan:** First `[ ]` task in PLAN.md where all `Blocked by:` deps are `[x]`.
-
-**No `[ ]` tasks:** Skip to step 5 (completion check).
-
-**All remaining blocked:** Error with blocker details, suggest `/df:execute` for manual resolution.
-
-### 3. EXECUTE
-
-Run via Skill tool: `skill: "df:execute", args: "{task_id}"`. Handles worktree, agent spawning, ratchet, commit.
-
-**Bootstrap handling:** If execute returns `"bootstrap: completed"` (zero pre-existing tests, baseline written):
-- Record as task `BOOTSTRAP`, status `passed`
-- Do NOT run a regular task in the same cycle
-- Next cycle picks up the first regular task
-
-### 3.5. WRITE STATE
-
-After execute returns, update `.deepflow/auto-memory.yaml` (read-merge-write, preserve all keys):
-
-| Outcome | Write |
-|---------|-------|
-| Success (non-optimize) | `task_results[id]: {status: success, commit: {hash}, cycle: {N}}` |
-| Revert (non-optimize) | `task_results[id]: {status: reverted, reason: "{msg}", cycle: {N}}` + append to `revert_history` |
-| Optimize cycle | Merge updated `optimize_state` from execute (confirm `cycles_run`, `current_best`, `history`) |
-
-### 3.6. CIRCUIT BREAKER
-
-**Failure = any L0-L5 verification failure** (build, files, coverage, tests, browser assertions). Does NOT count: L5 skip (no frontend), L5 pass-on-retry.
-
-**On revert (non-optimize):**
-1. Increment `consecutive_reverts[task_id]` in auto-memory.yaml
-2. Read `circuit_breaker_threshold` from `.deepflow/config.yaml` (default: 3)
-3. If `consecutive_reverts[task_id] >= threshold`: halt loop, report "Circuit breaker tripped: T{n} failed {N} times. Reason: {msg}"
-4. Else: continue to step 4
-
-**On success (non-optimize):** Reset `consecutive_reverts[task_id]` to 0.
-
-**Optimize stop conditions** (from execute terminal outcomes):
-
-| Outcome | Action |
-|---------|--------|
-| `"target reached: {value}"` | Confirm task [x], write optimize completion (3.7), report, continue |
-| `"max cycles reached, best: {value}"` | Confirm task [x], write optimize completion (3.7), report, continue |
-| `"circuit breaker: 3 consecutive reverts"` | Task stays [ ], write failure to experiments (3.7), preserve optimize_state, halt loop |
-
-### 3.7. OPTIMIZE COMPLETION
-
-**On target reached or max cycles (task [x]):**
-1. Write each `failed_hypotheses` entry to `.deepflow/experiments/{spec}--optimize-{task_id}--{slug}--failed.md`
-2. Write summary to `.deepflow/experiments/{spec}--optimize-{task_id}--summary--{status}.md` with metric/target/direction/baseline/best/cycles/history table
-3. Clear `optimize_state` from auto-memory.yaml
-
-**On circuit breaker halt:** Same experiment writes but with status `circuit_breaker`. Preserve `optimize_state` in auto-memory.yaml (add `halted: circuit_breaker` note).
-
-### 4. UPDATE REPORT
-
-Write to `.deepflow/auto-report.md` — append each cycle, never overwrite. First cycle creates skeleton, subsequent cycles update in-place.
-
-**File sections:** Summary table, Cycle Log, Probe Results, Optimize Runs, Secondary Metric Warnings, Health Score, Reverted Tasks.
-
-#### Per-cycle update rules
-
-| Section | When | Action |
-|---------|------|--------|
-| Cycle Log | Every cycle | Append row: `cycle | task_id | status | commit/reverted | delta | metric_delta | reason | timestamp` |
-| Summary | Every cycle | Recalculate from Cycle Log: total cycles, committed, reverted, optimize cycles/best (if applicable) |
-| Last updated | Every cycle | Overwrite timestamp |
-| Probe Results | Probe/spike task | Append row from `probe_learnings` in auto-memory.yaml |
-| Optimize Runs | Optimize terminal event | Append row: task/metric/baseline/best/target/cycles/status |
-| Secondary Metric Warnings | >5% regression | Append row (severity: WARNING, advisory only — no auto-revert) |
-| Health Score | Every cycle | Replace with latest: tests passed, build status, ratchet green/red, optimize status |
-| Reverted Tasks | On revert | Append row from `revert_history` |
-
-**Status values:** `passed`, `failed` (reverted), `skipped` (already done), `optimize` (inner cycle).
-
-**Delta format:** `tests: {before}→{after}, build: ok/fail`. Include coverage if available. On revert, show regression.
-
-**Optimize status in Health Score:** `in_progress` | `reached` | `max_cycles` | `circuit_breaker` | `—` (omit row if no optimize tasks in PLAN.md).
-
-### 5. CHECK COMPLETION
-
-Count `[x]` and `[ ]` tasks in PLAN.md. Per-spec verify+merge happens in `/df:execute` step 8 automatically.
-
-- **No `[ ]` remaining:** "All specs verified and merged. Workflow complete." → exit
-- **Tasks remain:** "Cycle complete. {N} tasks remaining." → exit (next /loop invocation picks up)
-
-## Rules
-
-| Rule | Detail |
-|------|--------|
-| One task per cycle | Fresh context each invocation — no multi-task batching |
-| Bootstrap = sole task | No regular task runs in a bootstrap cycle |
-| Idempotent | Safe to call with no work — reports "0 tasks remaining" |
-| Never modifies PLAN.md | `/df:execute` handles PLAN.md updates |
-| Auto-memory after every cycle | `task_results`, `revert_history`, `consecutive_reverts` always written |
-| Circuit breaker halts loop | Default 3 consecutive reverts (configurable: `circuit_breaker_threshold` in config.yaml) |
-| One optimize at a time | Defers other optimize tasks until active one terminates |
-| Optimize resumes across contexts | `optimize_state.task_id` overrides normal scan |
-| Optimize CB preserves state | On halt: task stays [ ], optimize_state kept for diagnosis |
-| Secondary metric regression advisory | >5% = WARNING in report, never auto-revert |
-| Optimize completion writes experiments | Failed hypotheses + summary to `.deepflow/experiments/` |
-
-## Example
-
-### Normal Cycle
-```
-/df:auto-cycle
-Loading PLAN.md... 3 tasks, 1 done, 2 pending
-Next: T2 (T1 satisfied)
-Running: /df:execute T2 → ✓ ratchet passed (abc1234)
-Updated auto-report.md: cycles=2, committed=2
-Cycle complete. 1 tasks remaining.
-```
-
-### Circuit Breaker Tripped
-```
-/df:auto-cycle
-Loading PLAN.md... 3 tasks, 1 done, 2 pending
-Next: T3
-Running: /df:execute T3 → ✗ ratchet failed — "2 tests regressed"
-Circuit breaker: consecutive_reverts[T3] = 3 (threshold: 3)
-Loop halted. Resolve T3 manually, then resume.
-```
+Use the Skill tool to invoke the `auto-cycle` skill, passing through any arguments.

package/src/commands/df/auto.md

@@ -42,4 +42,4 @@ Each invocation gets fresh context — zero LLM tokens on loop management.
 | Plan once | Only runs `/df:plan` if PLAN.md absent |
 | Snapshot before loop | Ratchet baseline set before any agents run |
 | No lead agent | `/loop` is native Claude Code — no custom orchestrator |
-| Cycle logic in `/df:auto-cycle` | This command is setup only |
+| Cycle logic in `src/skills/auto-cycle/SKILL.md` | This command is setup only; `/df:auto-cycle` is a shim that delegates to the skill |

package/src/commands/df/execute.md

@@ -185,7 +185,7 @@ Trigger: ≥2 [SPIKE] tasks with same blocker or identical hypothesis.
 4. Per notification: ratchet (§5.5). Record: ratchet_passed, regressions, coverage_delta, files_changed, commit.
 5. **Winner selection** (no LLM judge): disqualify regressions. Standard: fewer regressions > coverage > fewer files > first complete. Optimize: best metric delta > fewer regressions > fewer files. No passes → reset pending for debugger.
 6. Preserve all worktrees. Losers: branch + `-failed`. Record in checkpoint.json.
-7. Log all outcomes to `.deepflow/auto-memory.yaml` under `spike_insights`+`probe_learnings` (schema in auto-cycle.md). Both winners and losers.
+7. Log all outcomes to `.deepflow/auto-memory.yaml` under `spike_insights`+`probe_learnings` (schema in src/skills/auto-cycle/SKILL.md). Both winners and losers.
 8. Cherry-pick winner into shared worktree. Winner → `[x] [PROBE_WINNER]`, losers → `[~] [PROBE_FAILED]`.
 
 #### 5.7.1. PROBE DIVERSITY (Optimize Probes)
@@ -361,23 +361,31 @@ Before merge, spawn an independent Opus QA agent that sees ONLY the spec and exp
 
 3. On notification:
    a. Run ratchet check (§5.5) — all integration tests must pass.
-   b. **Tests pass** → commit stands. Proceed to step 8.2 (merge).
-   c. **Tests fail** → **merge is blocked**. Do NOT retry. Report:
-      `"✗ Final integration tests failed for {spec} — merge blocked, requires human review"`
-      Leave worktree intact. Set all spec tasks back to `TaskUpdate(status: "pending")`.
-      Write failure details to `.deepflow/results/final-test-{spec}.yaml`:
+   b. **Tests pass** → commit stands. Proceed to step 8.2 (full L0-L5 verify + merge).
+   c. **Tests fail** → **merge is blocked**. Do NOT retry. Run diagnostic verify:
+      ```
+      skill: "df:verify", args: "--diagnostic doing-{name}"
+      ```
+      Capture the L0-L4 results from verify output (pass/fail/warn per level). Write to `.deepflow/results/final-test-{spec}.yaml`:
       ```yaml
       spec: {spec}
       status: blocked
       reason: "Final integration tests failed"
       output: |
         {truncated test output — last 30 lines}
+      diagnostics:
+        L0: {pass|fail}
+        L1: {pass|fail}
+        L2: {pass|warn|fail}
+        L4: {pass|fail}
       ```
-      STOP. Do not proceed to merge.
+      Leave worktree intact. Set all spec tasks back to `TaskUpdate(status: "pending")`.
+      Report: `"✗ Final tests failed for {spec} — diagnostic verify: L0 {✓|✗} | L1 {✓|✗} | L2 {✓|⚠|✗} | L4 {✓|✗} — merge blocked"`
+      STOP. Do not proceed to merge. Diagnostic verify is informational only — no fix agents, no retries.
 
 **8.2. Merge and cleanup:**
 1. `skill: "df:verify", args: "doing-{name}"` — runs L0-L4 gates, merges, cleans worktree, renames doing→done, extracts decisions. Fail (fix tasks added) → stop; `--continue` picks them up.
-2. Remove spec's ENTIRE section from PLAN.md. Recalculate Summary table.
+2. PLAN.md section cleanup handled by verify (step 6).
 
 ---
 
@@ -428,5 +436,5 @@ Reverted task: `TaskUpdate(status: "pending")`, dependents stay blocked. Repeate
 | Plateau → probes | 3 cycles <1% triggers probes |
 | Circuit breaker = 3 reverts | Halts, needs human |
 | Wave test after ratchet | Opus writes tests; 3 attempts then revert |
-| Final test before merge | Opus black-box integration tests; failure blocks merge, no retry |
+| Final test before merge | Opus black-box integration tests; pass → full L0-L5 verify + merge; failure → diagnostic L0-L4 verify, results in final-test-{spec}.yaml, merge blocked |
 | Probe diversity | ≥1 contraditoria + ≥1 ingenua |

package/src/commands/df/verify.md

@@ -12,14 +12,36 @@ context: fork
 
 ## Usage
 ```
-/df:verify                  # Verify doing-* specs with all tasks completed
-/df:verify doing-upload     # Verify specific spec
-/df:verify --re-verify      # Re-verify done-* specs (already merged)
+/df:verify                        # Verify doing-* specs with all tasks completed
+/df:verify doing-upload           # Verify specific spec
+/df:verify --re-verify            # Re-verify done-* specs (already merged)
+/df:verify --diagnostic doing-upload  # L0-L4 only; write results to diagnostics yaml; no merge/fix/rename
 ```
 
 ## Spec File States
 `specs/feature.md` → unplanned (skip) | `doing-*.md` → default target | `done-*.md` → `--re-verify` only
 
+## Diagnostic Mode (`--diagnostic`)
+
+When invoked with `--diagnostic`:
+
+- Run **L0-L4 only** (skip L5 entirely, even if frontend detected).
+- Write results to `.deepflow/results/final-test-{spec}.yaml` under a `diagnostics:` key:
+  ```yaml
+  diagnostics:
+    spec: doing-upload
+    timestamp: 2024-01-15T10:30:00Z
+    L0: pass          # or fail
+    L1: pass          # or fail
+    L2: pass          # or warn (no tool)
+    L4: fail          # or pass
+    summary: "L0 ✓ | L1 ✓ | L2 ⚠ | L3 — | L4 ✗"
+  ```
+- Prefix all report output with `[DIAGNOSTIC]`.
+- **Skip entirely:** Post-Verification merge (§4), fix task creation, spec rename, decision extraction, PLAN.md cleanup (step 6).
+- Does **not** count as a revert for the circuit breaker.
+- Does **not** modify `auto-snapshot.txt`.
+
 ## Behavior
 
 ### 1. LOAD CONTEXT
@@ -71,7 +93,9 @@ No tool → pass with warning. When available: stash changes → run coverage on
 
 Algorithm: detect frontend → resolve dev command/port → start server → poll readiness → read assertions from PLAN.md → auto-install Playwright Chromium → evaluate via `locator.ariaSnapshot()` → screenshot → retry once on failure → report.
 
-**Step 1: Detect frontend.** Config `quality.browser_verify` overrides: `false` → always skip (`L5 — (no frontend)`), `true` → always run, absent → auto-detect from package.json (both deps and devDeps):
+**Step 1: Detect frontend.** Config `quality.browser_verify` overrides: `false` → always skip (`L5 — (no frontend)`), `true` → always run, absent → auto-detect using BOTH conditions:
+
+1. Frontend framework found in package.json (deps or devDeps):
 
 | Package(s) | Framework |
 |------------|-----------|
@@ -82,7 +106,12 @@ Algorithm: detect frontend → resolve dev command/port → start server → pol
 | `@sveltejs/kit` | SvelteKit |
 | `svelte`, `@sveltejs/*` | Svelte |
 
-No frontend detected and no config override → `L5 — (no frontend)`, skip remaining L5 steps.
+2. A `browser_assertions:` block exists in PLAN.md scoped to the current spec.
+
+**Auto-detect outcomes (no config override):**
+- No frontend detected → `L5 — (no frontend)`, skip remaining L5 steps.
+- Frontend detected but no `browser_assertions:` block in PLAN.md for current spec → `L5 — (no browser_assertions in PLAN.md)`, skip remaining L5 steps.
+- Both conditions met → proceed to Steps 2–6.
 
 **Step 2: Dev server lifecycle.**
 1. **Resolve dev command:** Config `quality.dev_command` wins → fallback to `npm run dev` if `scripts.dev` exists → none found → skip L5 with warning.
@@ -113,7 +142,7 @@ No frontend detected and no config override → `L5 — (no frontend)`, skip rem
 | Fail | Fail — same selectors | L5 ✗ — genuine failure |
 | Fail | Fail — different selectors | L5 ✗ (flaky) |
 
-All L5 outcomes: `✓` pass | `⚠` passed on retry | `✗` both failed (same) | `✗ (flaky)` both failed (different) | `— (no frontend)` | `— (no assertions)` | `✗ (install failed)`
+All L5 outcomes: `✓` pass | `⚠` passed on retry | `✗` both failed (same) | `✗ (flaky)` both failed (different) | `— (no frontend)` | `— (no browser_assertions in PLAN.md)` | `— (no assertions)` | `✗ (install failed)`
 
 **Fix task on L5 failure:** Append to PLAN.md under spec section with next T{n} ID. Include: failing assertions (selector + detail), first 40 lines of `locator('body').ariaSnapshot()` DOM excerpt, screenshot path, flakiness note if assertion sets differed.
 
@@ -158,12 +187,13 @@ Objective: ... | Approach: ... | Why it worked: ... | Files: ...
 
 ## Post-Verification: Worktree Merge & Cleanup
 
-**Only runs when ALL gates pass.**
+**Only runs when ALL gates pass AND `--diagnostic` was NOT used.**
 
 1. **Discover worktree:** Read `.deepflow/checkpoint.json` for `worktree_branch`/`worktree_path`. Fallback: infer from `doing-*` spec name + `git worktree list --porcelain`. No worktree → "nothing to merge", exit.
 2. **Merge:** `git checkout main && git merge ${BRANCH} --no-ff -m "feat({spec}): merge verified changes"`. On conflict → keep worktree, output "Resolve manually, run /df:verify --merge-only", exit.
 3. **Cleanup:** `git worktree remove --force ${PATH} && git branch -d ${BRANCH} && rm -f .deepflow/checkpoint.json`
 4. **Rename spec:** `mv specs/doing-${NAME}.md specs/done-${NAME}.md`
 5. **Extract decisions:** Read done spec, extract `[APPROACH]`/`[ASSUMPTION]`/`[PROVISIONAL]` decisions, append to `.deepflow/decisions.md` as `### {date} — {spec}\n- [TAG] decision — rationale`. Delete done spec after successful write; preserve on failure.
+6. **Clean PLAN.md:** Find the `### {spec-name}` section (match on name stem, strip `doing-`/`done-` prefix). Delete from header through the line before the next `### ` header (or EOF). Recalculate Summary table (recount `### ` headers for spec count, `- [ ]`/`- [x]` for task counts). If no spec sections remain, delete PLAN.md entirely. Skip silently if PLAN.md missing or section already gone.
 
-Output: `✓ Merged → main | ✓ Cleaned worktree | ✓ Spec complete | Workflow complete! Ready: /df:spec <name>`
+Output: `✓ Merged → main | ✓ Cleaned worktree | ✓ Spec complete | ✓ Cleaned PLAN.md | Workflow complete! Ready: /df:spec <name>`

package/src/skills/auto-cycle/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: auto-cycle
+description: Execute one task from PLAN.md with ratchet health checks and state tracking for autonomous mode
+---
+
+# auto-cycle — Single Cycle of Auto Mode
+
+Execute one task from PLAN.md. Called by `/loop 1m /df:auto-cycle` — each invocation gets fresh context.
+
+**NEVER:** use EnterPlanMode, use ExitPlanMode
+
+## Behavior
+
+### 1. LOAD STATE
+
+Shell injection (use output directly):
+- `` !`cat PLAN.md 2>/dev/null || echo 'NOT_FOUND'` `` — required, error if missing
+- `` !`cat .deepflow/auto-memory.yaml 2>/dev/null || echo 'NOT_FOUND'` `` — optional cross-cycle state
+
+**auto-memory.yaml schema:** see `/df:execute`. Each section optional, missing keys = empty. Created on first write if absent.
+
+### 2. PICK NEXT TASK
+
+**Optimize-active override:** Check `optimize_state.task_id` in auto-memory.yaml first. If present and task still `[ ]` in PLAN.md, resume it (skip normal scan). If task is `[x]`, clear `optimize_state.task_id` and fall through.
+
+**Normal scan:** First `[ ]` task in PLAN.md where all `Blocked by:` deps are `[x]`.
+
+**No `[ ]` tasks:** Skip to step 5 (completion check).
+
+**All remaining blocked:** Error with blocker details, suggest `/df:execute` for manual resolution.
+
+### 3. EXECUTE
+
+Run via Skill tool: `skill: "df:execute", args: "{task_id}"`. Handles worktree, agent spawning, ratchet, commit.
+
+**Bootstrap handling:** If execute returns `"bootstrap: completed"` (zero pre-existing tests, baseline written):
+- Record as task `BOOTSTRAP`, status `passed`
+- Do NOT run a regular task in the same cycle
+- Next cycle picks up the first regular task
+
+### 3.5. WRITE STATE
+
+After execute returns, update `.deepflow/auto-memory.yaml` (read-merge-write, preserve all keys):
+
+| Outcome | Write |
+|---------|-------|
+| Success (non-optimize) | `task_results[id]: {status: success, commit: {hash}, cycle: {N}}` |
+| Revert (non-optimize) | `task_results[id]: {status: reverted, reason: "{msg}", cycle: {N}}` + append to `revert_history` |
+| Optimize cycle | Merge updated `optimize_state` from execute (confirm `cycles_run`, `current_best`, `history`) |
+
+### 3.6. CIRCUIT BREAKER
+
+**Failure = any L0-L5 verification failure** (build, files, coverage, tests, browser assertions). Does NOT count: L5 skip (no frontend), L5 pass-on-retry.
+
+**On revert (non-optimize):**
+1. Increment `consecutive_reverts[task_id]` in auto-memory.yaml
+2. Read `circuit_breaker_threshold` from `.deepflow/config.yaml` (default: 3)
+3. If `consecutive_reverts[task_id] >= threshold`: halt loop, report "Circuit breaker tripped: T{n} failed {N} times. Reason: {msg}"
+4. Else: continue to step 4
+
+**On success (non-optimize):** Reset `consecutive_reverts[task_id]` to 0.
+
+**Optimize stop conditions** (from execute terminal outcomes):
+
+| Outcome | Action |
+|---------|--------|
+| `"target reached: {value}"` | Confirm task [x], write optimize completion (3.7), report, continue |
+| `"max cycles reached, best: {value}"` | Confirm task [x], write optimize completion (3.7), report, continue |
+| `"circuit breaker: 3 consecutive reverts"` | Task stays [ ], write failure to experiments (3.7), preserve optimize_state, halt loop |
+
+### 3.7. OPTIMIZE COMPLETION
+
+**On target reached or max cycles (task [x]):**
+1. Write each `failed_hypotheses` entry to `.deepflow/experiments/{spec}--optimize-{task_id}--{slug}--failed.md`
+2. Write summary to `.deepflow/experiments/{spec}--optimize-{task_id}--summary--{status}.md` with metric/target/direction/baseline/best/cycles/history table
+3. Clear `optimize_state` from auto-memory.yaml
+
+**On circuit breaker halt:** Same experiment writes but with status `circuit_breaker`. Preserve `optimize_state` in auto-memory.yaml (add `halted: circuit_breaker` note).
+
+### 4. UPDATE REPORT
+
+Write to `.deepflow/auto-report.md` — append each cycle, never overwrite. First cycle creates skeleton, subsequent cycles update in-place.
+
+**File sections:** Summary table, Cycle Log, Probe Results, Optimize Runs, Secondary Metric Warnings, Health Score, Reverted Tasks.
+
+#### Per-cycle update rules
+
+| Section | When | Action |
+|---------|------|--------|
+| Cycle Log | Every cycle | Append row: `cycle | task_id | status | commit/reverted | delta | metric_delta | reason | timestamp` |
+| Summary | Every cycle | Recalculate from Cycle Log: total cycles, committed, reverted, optimize cycles/best (if applicable) |
+| Last updated | Every cycle | Overwrite timestamp |
+| Probe Results | Probe/spike task | Append row from `probe_learnings` in auto-memory.yaml |
+| Optimize Runs | Optimize terminal event | Append row: task/metric/baseline/best/target/cycles/status |
+| Secondary Metric Warnings | >5% regression | Append row (severity: WARNING, advisory only — no auto-revert) |
+| Health Score | Every cycle | Replace with latest: tests passed, build status, ratchet green/red, optimize status |
+| Reverted Tasks | On revert | Append row from `revert_history` |
+
+**Status values:** `passed`, `failed` (reverted), `skipped` (already done), `optimize` (inner cycle).
+
+**Delta format:** `tests: {before}→{after}, build: ok/fail`. Include coverage if available. On revert, show regression.
+
+**Optimize status in Health Score:** `in_progress` | `reached` | `max_cycles` | `circuit_breaker` | `—` (omit row if no optimize tasks in PLAN.md).
+
+### 5. CHECK COMPLETION
+
+Count `[x]` and `[ ]` tasks in PLAN.md. Per-spec verify+merge happens in `/df:execute` step 8 automatically.
+
+- **No `[ ]` remaining:** "All specs verified and merged. Workflow complete." → exit
+- **Tasks remain:** "Cycle complete. {N} tasks remaining." → exit (next /loop invocation picks up)
+
+## Rules
+
+| Rule | Detail |
+|------|--------|
+| One task per cycle | Fresh context each invocation — no multi-task batching |
+| Bootstrap = sole task | No regular task runs in a bootstrap cycle |
+| Idempotent | Safe to call with no work — reports "0 tasks remaining" |
+| Never modifies PLAN.md | `/df:execute` handles PLAN.md updates |
+| Auto-memory after every cycle | `task_results`, `revert_history`, `consecutive_reverts` always written |
+| Circuit breaker halts loop | Default 3 consecutive reverts (configurable: `circuit_breaker_threshold` in config.yaml) |
+| One optimize at a time | Defers other optimize tasks until active one terminates |
+| Optimize resumes across contexts | `optimize_state.task_id` overrides normal scan |
+| Optimize CB preserves state | On halt: task stays [ ], optimize_state kept for diagnosis |
+| Secondary metric regression advisory | >5% = WARNING in report, never auto-revert |
+| Optimize completion writes experiments | Failed hypotheses + summary to `.deepflow/experiments/` |
+
+## Example
+
+### Normal Cycle
+```
+/df:auto-cycle
+Loading PLAN.md... 3 tasks, 1 done, 2 pending
+Next: T2 (T1 satisfied)
+Running: /df:execute T2 → ✓ ratchet passed (abc1234)
+Updated auto-report.md: cycles=2, committed=2
+Cycle complete. 1 tasks remaining.
+```
+
+### Circuit Breaker Tripped
+```
+/df:auto-cycle
+Loading PLAN.md... 3 tasks, 1 done, 2 pending
+Next: T3
+Running: /df:execute T3 → ✗ ratchet failed — "2 tests regressed"
+Circuit breaker: consecutive_reverts[T3] = 3 (threshold: 3)
+Loop halted. Resolve T3 manually, then resume.
+```

package/templates/config-template.yaml

@@ -82,9 +82,8 @@ quality:
   # Retry flaky tests once before failing (default: true)
   test_retry_on_fail: true
 
-  # Enable L5 browser verification after tests pass (default: false)
-  # When true, deepflow will start the dev server and run visual checks
-  browser_verify: false
+  # Three-state: true (force L5), false (skip L5), absent/commented (auto-detect from package.json + browser_assertions)
+  # browser_verify:
 
   # Override the dev server start command for browser verification
   # If empty, deepflow will attempt to auto-detect (e.g., "npm run dev", "yarn dev")

package/hooks/df-consolidation-check.js

@@ -1,67 +0,0 @@
-#!/usr/bin/env node
-/**
- * deepflow consolidation checker
- * Checks if decisions.md needs consolidation, outputs suggestion if overdue
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const DAYS_THRESHOLD = 7;
-const LINES_THRESHOLD = 20;
-const DEEPFLOW_DIR = path.join(process.cwd(), '.deepflow');
-const DECISIONS_FILE = path.join(DEEPFLOW_DIR, 'decisions.md');
-const LAST_CONSOLIDATED_FILE = path.join(DEEPFLOW_DIR, 'last-consolidated.json');
-
-function checkConsolidation() {
-  try {
-    // Check if decisions.md exists
-    if (!fs.existsSync(DECISIONS_FILE)) {
-      process.exit(0);
-    }
-
-    // Check if decisions.md has more than LINES_THRESHOLD lines
-    const decisionsContent = fs.readFileSync(DECISIONS_FILE, 'utf8');
-    const lineCount = decisionsContent.split('\n').length;
-    if (lineCount <= LINES_THRESHOLD) {
-      process.exit(0);
-    }
-
-    // Get last consolidated timestamp
-    let lastConsolidated;
-    if (fs.existsSync(LAST_CONSOLIDATED_FILE)) {
-      try {
-        const data = JSON.parse(fs.readFileSync(LAST_CONSOLIDATED_FILE, 'utf8'));
-        if (data.last_consolidated) {
-          lastConsolidated = new Date(data.last_consolidated);
-        }
-      } catch (e) {
-        // Fall through to use mtime
-      }
-    }
-
-    // Fallback: use mtime of decisions.md
-    if (!lastConsolidated || isNaN(lastConsolidated.getTime())) {
-      const stat = fs.statSync(DECISIONS_FILE);
-      lastConsolidated = stat.mtime;
-    }
-
-    // Calculate days since last consolidation
-    const now = new Date();
-    const diffMs = now - lastConsolidated;
-    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
-
-    if (diffDays >= DAYS_THRESHOLD) {
-      process.stderr.write(
-        `\u{1F4A1} decisions.md hasn't been consolidated in ${diffDays} days. Run /df:consolidate to clean up.\n`
-      );
-    }
-
-  } catch (e) {
-    // Fail silently
-  }
-
-  process.exit(0);
-}
-
-checkConsolidation();

package/src/commands/df/consolidate.md

@@ -1,42 +0,0 @@
----
-name: df:consolidate
-description: Remove duplicates and superseded entries from decisions file, promote stale provisionals
----
-
-# /df:consolidate — Consolidate Decisions
-
-Remove duplicates, superseded entries, and promote stale provisionals. Keep decisions.md dense and useful.
-
-**NEVER:** use EnterPlanMode, ExitPlanMode
-
-## Behavior
-
-### 1. LOAD
-Read `.deepflow/decisions.md` via `` !`cat .deepflow/decisions.md 2>/dev/null || echo 'NOT_FOUND'` ``. If missing/empty, report and exit.
-
-### 2. ANALYZE (model-driven, not regex)
-- Identify duplicates (same meaning, different wording)
-- Identify superseded entries (later contradicts earlier)
-- Identify stale `[PROVISIONAL]` entries (>30 days old, no resolution)
-
-### 3. CONSOLIDATE
-- Remove duplicates (keep more precise wording)
-- Remove superseded entries (later decision wins)
-- Promote stale `[PROVISIONAL]` → `[DEBT]`
-- Preserve `[APPROACH]` unless superseded, `[ASSUMPTION]` unless invalidated
-- Target: 200-500 lines if currently longer
-- When in doubt, keep both entries (conservative)
-
-### 4. WRITE
-- Rewrite `.deepflow/decisions.md` with consolidated content
-- Write `{ "last_consolidated": "{ISO-8601}" }` to `.deepflow/last-consolidated.json`
-
-### 5. REPORT
-`✓ Consolidated: {before} → {after} lines, {n} removed, {n} promoted to [DEBT]`
-
-## Rules
-
-- Conservative: when in doubt, keep both entries
-- Never add new decisions — only remove, merge, or re-tag
-- `[DEBT]` is only produced by consolidation, never manually assigned
-- Preserve chronological ordering within sections

package/src/commands/df/note.md

@@ -1,73 +0,0 @@
----
-name: df:note
-description: Capture decisions that emerged during free conversations outside of deepflow commands
----
-
-# /df:note — Capture Decisions from Free Conversations
-
-## Orchestrator Role
-
-Scan conversation for candidate decisions, present for user confirmation, persist to `.deepflow/decisions.md`.
-
-**NEVER:** Spawn agents, use Task tool, use Glob/Grep on source code, run git, use TaskOutput, EnterPlanMode, ExitPlanMode
-
-**ONLY:** Read `.deepflow/decisions.md`, present candidates via `AskUserQuestion`, append confirmed decisions
-
-## Behavior
-
-### 1. EXTRACT CANDIDATES
-
-Scan prior messages for resolved choices, adopted approaches, or stated assumptions. Look for:
-- **Approaches chosen**: "we'll use X instead of Y"
-- **Provisional choices**: "for now we'll use X"
-- **Stated assumptions**: "assuming X is true"
-- **Constraints accepted**: "X is out of scope"
-- **Naming/structural choices**: "we'll call it X", "X goes in the Y layer"
-
-Extract **at most 4 candidates**. For each, determine:
-
-| Field | Value |
-|-------|-------|
-| Tag | `[APPROACH]` (deliberate choice), `[PROVISIONAL]` (revisit later), or `[ASSUMPTION]` (unvalidated) |
-| Decision | One concise line describing the choice |
-| Rationale | One sentence explaining why |
-
-If <2 clear candidates found, say so and exit.
-
-### 2. CHECK FOR CONTRADICTIONS
-
-Read `.deepflow/decisions.md` if it exists. If a candidate contradicts a prior entry: keep prior entry unchanged, amend candidate rationale to `was "X", now "Y" because Z`.
-
-### 3. PRESENT VIA AskUserQuestion
-
-Single multi-select call. Each option: `label` = tag + decision text, `description` = rationale.
-
-### 4. APPEND CONFIRMED DECISIONS
-
-For each selected option:
-1. Create `.deepflow/decisions.md` with `# Decisions` header if absent
-2. Append a dated section: `### YYYY-MM-DD — note`
-3. Group all confirmed decisions under one section: `- [TAG] Decision text — rationale`
-4. Never modify or delete prior entries
-
-### 5. CONFIRM
-
-Report: `Saved N decision(s) to .deepflow/decisions.md` or `No decisions saved.`
-
-## Decision Tags
-
-| Tag | Meaning | Source |
-|-----|---------|--------|
-| `[APPROACH]` | Firm decision | /df:note, auto-extraction |
-| `[PROVISIONAL]` | Revisit later | /df:note, auto-extraction |
-| `[ASSUMPTION]` | Unverified | /df:note, auto-extraction |
-| `[DEBT]` | Needs revisiting | /df:consolidate only, never manually assigned |
-
-## Rules
-
-- Max 4 candidates per invocation (AskUserQuestion tool limit)
-- multiSelect: true — user confirms any subset
-- Never invent decisions — only extract what was discussed and resolved
-- Never modify prior entries in `.deepflow/decisions.md`
-- Source is always `note`; date is today (YYYY-MM-DD)
-- One AskUserQuestion call — all candidates in a single call