deepflow 0.1.89 → 0.1.91

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

@@ -101,24 +101,37 @@ Context ≥50% → checkpoint and exit. Before spawning: `TaskUpdate(status: "in
 
 ### 5.5. RATCHET CHECK
 
-Run health checks in worktree after each agent completes.
+Run `node bin/ratchet.js` in the worktree directory after each agent completes:
+```bash
+node bin/ratchet.js --worktree ${WORKTREE_PATH} --snapshot .deepflow/auto-snapshot.txt
+```
+
+The script handles all health checks internally and outputs structured JSON:
+```json
+{"status": "PASS"|"FAIL"|"SALVAGEABLE", "reason": "...", "details": "..."}
+```
 
-| File | Build | Test | Typecheck | Lint |
-|------|-------|------|-----------|------|
-| `package.json` | `npm run build` | `npm test` | `npx tsc --noEmit` | `npm run lint` |
-| `pyproject.toml` | — | `pytest` | `mypy .` | `ruff check .` |
-| `Cargo.toml` | `cargo build` | `cargo test` | — | `cargo clippy` |
-| `go.mod` | `go build ./...` | `go test ./...` | — | `go vet ./...` |
+**Exit codes:** 0 = PASS, 1 = FAIL (script already ran `git revert HEAD --no-edit`), 2 = SALVAGEABLE (lint/typecheck only; build+tests passed).
 
-Run Build → Test → Typecheck → Lint (stop on first failure). Ratchet uses ONLY pre-existing tests from `.deepflow/auto-snapshot.txt`.
+**You MUST NOT inspect, classify, or reinterpret test failures. FAIL means revert. No exceptions.**
+
+**Prohibited actions during ratchet:**
+- No `git stash` or `git checkout` for investigation purposes
+- No inline edits to pre-existing test files
+- No reading raw test output to decide what "really" failed
+
+**Broken-tests policy:** Updating pre-existing tests requires a separate dedicated task in PLAN.md with explicit justification — never inline during execution.
+
+**Orchestrator response by exit code:**
+- **Exit 0 (PASS):** Commit stands. Proceed to §5.6 wave test agent.
+- **Exit 1 (FAIL):** Script already reverted. Set `TaskUpdate(status: "pending")`. Report: `"✗ T{n}: reverted"`.
+- **Exit 2 (SALVAGEABLE):** Spawn `Agent(model="haiku")` to fix lint/typecheck issues. Re-run `node bin/ratchet.js`. If still non-zero → revert both commits, set status pending.
 
 **Edit scope validation:** `git diff HEAD~1 --name-only` vs allowed globs. Violation → revert, report.
 **Impact completeness:** diff vs Impact callers/duplicates. Gap → advisory warning (no revert).
 
 **Metric gate (Optimize only):** Run `eval "${metric_command}"` with cwd=`${WORKTREE_PATH}` (never `cd && eval`). Parse float (non-numeric → revert). Compare using `direction`+`min_improvement_threshold`. Both ratchet AND metric must pass → keep. Ratchet pass + metric stagnant → revert. Secondary metrics: regression > `regression_threshold` (5%) → WARNING in auto-report.md (no revert).
 
-**Output truncation:** Success → suppress. Build fail → last 15 lines. Test fail → names + last 20 lines. Typecheck/lint → count + first 5 errors.
-
 **Token tracking result (on pass):** Read `end_percentage`. Sum token fields from `.deepflow/token-history.jsonl` between start/end timestamps (awk ISO 8601 compare). Write to `.deepflow/results/T{N}.yaml`:
 ```yaml
 tokens:
@@ -131,10 +144,6 @@ tokens:
 ```
 Omit if context.json/token-history.jsonl/awk unavailable. Never fail ratchet for tracking errors.
 
-**Evaluate:** All pass → commit stands. Failure → partial salvage:
-1. Lint/typecheck-only (build+tests passed): spawn `Agent(model="haiku")` to fix. Re-ratchet. Fail → revert both.
-2. Build/test failure → `git revert HEAD --no-edit` (no salvage).
-
 ### 5.6. WAVE TEST AGENT
 
 <!-- AC-8: After wave ratchet passes, Opus test agent spawns and writes unit tests -->
@@ -147,8 +156,11 @@ Omit if context.json/token-history.jsonl/awk unavailable. Never fail ratchet for
 
 **Flow:**
 1. Capture the implementation diff: `git -C ${WORKTREE_PATH} diff HEAD~1` → store as `IMPL_DIFF`.
-2. Spawn `Agent(model="opus")` with Wave Test prompt (§6). `run_in_background=true`. End turn, wait.
-3. On notification:
+2. Gather dedup context:
+   - Read `.deepflow/auto-snapshot.txt` → store full file list as `SNAPSHOT_FILES`.
+   - Extract existing test function names: `grep -h 'describe\|it(\|test(\|def test_\|func Test' $(cat .deepflow/auto-snapshot.txt) 2>/dev/null | head -50` → store as `EXISTING_TEST_NAMES`.
+3. Spawn `Agent(model="opus")` with Wave Test prompt (§6), passing `SNAPSHOT_FILES` and `EXISTING_TEST_NAMES`. `run_in_background=true`. End turn, wait.
+4. On notification:
    a. Run ratchet check (§5.5) — all new + pre-existing tests must pass.
    b. **Tests pass** → commit stands. **Re-snapshot** immediately so wave N+1 ratchet includes wave N tests:
       ```bash
@@ -167,7 +179,7 @@ Omit if context.json/token-history.jsonl/awk unavailable. Never fail ratchet for
           {failure_feedback}
           Fix the issues above. Do NOT repeat the same mistakes.
           ```
-        - On implementer notification: ratchet check (§5.5). Passed → goto step 1 (spawn test agent again). Failed → same retry logic.
+        - On implementer notification: ratchet check (§5.5). Passed → goto step 2 (gather dedup context, spawn test agent again). Failed → same retry logic.
       - If `attempt_count >= 3`:
         - Revert ALL commits back to pre-task state: `git -C ${WORKTREE_PATH} reset --hard {pre_task_commit}`
         - `TaskUpdate(status: "pending")`
@@ -185,7 +197,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)
@@ -279,9 +291,16 @@ Implementation diff:
 Files changed: {changed_files}
 Existing test patterns: {test_file_examples from auto-snapshot.txt, first 3}
 
+Pre-existing test files (from auto-snapshot.txt):
+{SNAPSHOT_FILES}
+
+Existing test function names (do NOT duplicate these):
+{EXISTING_TEST_NAMES}
+
 --- END ---
 Write thorough unit tests covering: happy paths, edge cases, error handling.
 Follow existing test conventions in the codebase.
+Do not duplicate tests for functionality already covered by the existing tests listed above.
 Commit as: test({spec}): wave-{N} unit tests
 Do NOT modify implementation files. ONLY add/edit test files.
 Last line of your response MUST be: TASK_STATUS:pass or TASK_STATUS:fail
@@ -361,23 +380,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 +455,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")
@@ -96,6 +95,30 @@ quality:
   # Timeout in seconds to wait for the dev server to become ready (default: 30)
   browser_timeout: 30
 
+# Ratchet configuration for /df:verify health gate
+# Ratchet snapshots baseline metrics (tests passing, coverage, type checks) before execution
+# and ensures subsequent runs don't regress. These overrides control which commands ratchet monitors.
+ratchet:
+  # Override auto-detected build command for ratchet health checks
+  # If empty, ratchet will detect from indicator files (package.json scripts, Cargo.toml, etc.)
+  # Examples: "npm run build", "cargo build", "go build ./..."
+  build_command: ""
+
+  # Override auto-detected test command for ratchet health checks
+  # If empty, ratchet will detect from indicator files
+  # Examples: "npm test", "pytest", "go test ./...", "cargo test"
+  test_command: ""
+
+  # Override auto-detected typecheck command for ratchet health checks
+  # If empty, ratchet will detect from indicator files (e.g., "tsc --noEmit" for TypeScript)
+  # Examples: "tsc --noEmit", "mypy .", "cargo check"
+  typecheck_command: ""
+
+  # Override auto-detected lint command for ratchet health checks
+  # If empty, ratchet will detect from indicator files
+  # Examples: "eslint .", "flake8", "cargo clippy"
+  lint_command: ""
+
 # deepflow-dashboard team mode settings
 # dashboard_url: URL of the shared team server for POST ingestion
 # Leave blank (or omit) to use local-only mode (no data is pushed)

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();