deepflow 0.1.50 → 0.1.51

package/README.md

@@ -27,6 +27,7 @@
 - **Spike-first planning** — Validate risky hypotheses before full implementation
 - **Worktree isolation** — Main branch stays clean during execution
 - **Parallel execution** with context-aware checkpointing
+- **Automatic decision capture** on spec completion, periodic consolidation
 - **Atomic commits** for clean rollback
 
 ## Quick Start
@@ -65,7 +66,6 @@ claude
 ```
 /df:discover <name>
     │ Socratic questioning (motivation, scope, constraints...)
-    │ Captures decisions to .deepflow/decisions.md
     ▼
 /df:debate <topic>          ← optional
     │ 4 perspectives: User Advocate, Tech Skeptic,
@@ -90,7 +90,8 @@ claude
 /df:verify
     │ Checks requirements met
     │ Merges worktree to main, cleans up
-    │ Renames: doing-feature.md → done-feature.md
+    │ Extracts decisions → .deepflow/decisions.md
+    │ Deletes done-* spec after extraction
 ```
 
 ## Spec Lifecycle
@@ -99,7 +100,7 @@ claude
 specs/
   feature.md        → new, needs /df:plan
   doing-feature.md  → in progress, has tasks in PLAN.md
-  done-feature.md   → completed, history embedded
+  done-feature.md   → transient (decisions extracted, then deleted)
 ```
 
 ## Works With Any Project
@@ -145,8 +146,9 @@ Statusline shows context usage. At ≥50%:
 | `/df:spec <name>` | Generate spec from conversation |
 | `/df:plan` | Compare specs to code, create tasks |
 | `/df:execute` | Run tasks with parallel agents |
-| `/df:verify` | Check specs satisfied |
-| `/df:note` | Capture decisions from conversation |
+| `/df:verify` | Check specs satisfied, merge to main |
+| `/df:note` | Capture decisions ad-hoc from conversation |
+| `/df:consolidate` | Deduplicate and clean up decisions.md |
 | `/df:resume` | Session continuity briefing |
 | `/df:update` | Update deepflow to latest |
 
@@ -156,16 +158,16 @@ Statusline shows context usage. At ≥50%:
 your-project/
 ├── specs/
 │   ├── auth.md           # new spec
-│   ├── doing-upload.md   # in progress
-│   └── done-payments.md  # completed
+│   └── doing-upload.md   # in progress
 ├── PLAN.md               # active tasks
 └── .deepflow/
-    ├── config.yaml       # project settings
-    ├── decisions.md      # captured decisions (/df:note, /df:discover)
-    ├── context.json      # context % tracking
-    ├── experiments/      # spike results (pass/fail)
-    └── worktrees/        # isolated execution
-        └── upload/       # one worktree per spec
+    ├── config.yaml            # project settings
+    ├── decisions.md           # auto-extracted + ad-hoc decisions
+    ├── last-consolidated.json # consolidation timestamp
+    ├── context.json           # context % tracking
+    ├── experiments/           # spike results (pass/fail)
+    └── worktrees/             # isolated execution
+        └── upload/            # one worktree per spec
 ```
 
 ## Configuration

package/bin/install.js

@@ -196,6 +196,7 @@ async function configureHooks(claudeDir) {
   const settingsPath = path.join(claudeDir, 'settings.json');
   const statuslineCmd = `node "${path.join(claudeDir, 'hooks', 'df-statusline.js')}"`;
   const updateCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-check-update.js')}"`;
+  const consolidationCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-consolidation-check.js')}"`;
 
   let settings = {};
 
@@ -234,7 +235,7 @@ async function configureHooks(claudeDir) {
   // Remove any existing deepflow update check hooks
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter(hook => {
     const cmd = hook.hooks?.[0]?.command || '';
-    return !cmd.includes('df-check-update');
+    return !cmd.includes('df-check-update') && !cmd.includes('df-consolidation-check');
   });
 
   // Add update check hook
@@ -244,6 +245,14 @@ async function configureHooks(claudeDir) {
       command: updateCheckCmd
     }]
   });
+
+  // Add consolidation check hook
+  settings.hooks.SessionStart.push({
+    hooks: [{
+      type: 'command',
+      command: consolidationCheckCmd
+    }]
+  });
   log('SessionStart hook configured');
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
@@ -330,7 +339,7 @@ async function uninstall() {
   ];
 
   if (level === 'global') {
-    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js');
+    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js', 'hooks/df-consolidation-check.js');
   }
 
   for (const item of toRemove) {
@@ -359,7 +368,7 @@ async function uninstall() {
         if (settings.hooks?.SessionStart) {
           settings.hooks.SessionStart = settings.hooks.SessionStart.filter(hook => {
             const cmd = hook.hooks?.[0]?.command || '';
-            return !cmd.includes('df-check-update');
+            return !cmd.includes('df-check-update') && !cmd.includes('df-consolidation-check');
           });
           if (settings.hooks.SessionStart.length === 0) {
             delete settings.hooks.SessionStart;

package/hooks/df-consolidation-check.js

@@ -0,0 +1,67 @@
+#!/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/package.json

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

package/src/commands/df/consolidate.md

@@ -0,0 +1,58 @@
+# /df:consolidate — Consolidate Decisions
+
+## Purpose
+Remove duplicates, superseded entries, and promote stale provisionals. Keep decisions.md dense and useful.
+
+**NEVER:** use EnterPlanMode, use ExitPlanMode
+
+## Usage
+```
+/df:consolidate          # Consolidate decisions.md
+```
+
+## Behavior
+
+### 1. LOAD
+Read `.deepflow/decisions.md`. If missing or empty, report and exit.
+
+### 2. ANALYZE
+Model-driven analysis (not regex):
+- Identify duplicate decisions (same meaning, different wording)
+- Identify superseded decisions (later entry contradicts earlier)
+- Identify stale `[PROVISIONAL]` entries (>30 days old, no resolution)
+
+### 3. CONSOLIDATE
+- Remove duplicates (keep the more precise wording)
+- Silently remove superseded entries (the later decision wins)
+- Promote stale `[PROVISIONAL]` to `[DEBT]` (needs revisiting)
+- Preserve all `[APPROACH]` entries unless superseded
+- Preserve all `[ASSUMPTION]` entries 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 timestamp to `.deepflow/last-consolidated.json`:
+  ```json
+  { "last_consolidated": "{ISO-8601 timestamp}" }
+  ```
+
+### 5. REPORT
+```
+✓ Consolidated: {before} → {after} lines, {n} removed, {n} promoted to [DEBT]
+```
+
+## Tags
+| Tag | Meaning | Source |
+|-----|---------|--------|
+| `[APPROACH]` | Firm decision | Auto-extraction, /df:note |
+| `[PROVISIONAL]` | Revisit later | Auto-extraction, /df:note |
+| `[ASSUMPTION]` | Unverified | Auto-extraction, /df:note |
+| `[DEBT]` | Needs revisiting | Consolidation only |
+
+## Rules
+- Conservative: when in doubt, keep both entries
+- Never add new decisions — only remove, merge, or re-tag
+- [DEBT] is never manually assigned — only produced by consolidation
+- Preserve chronological ordering within sections
+- decisions.md stays a single flat file, human-readable

package/src/commands/df/debate.md

@@ -160,10 +160,6 @@ Create `specs/.debate-{name}.md` with sections: Context · Codebase Context · P
 
 Present key tensions and open decisions, then: `Next: Run /df:spec {name} to formalize into a specification`
 
-### 7. CAPTURE DECISIONS
-
-Follow the **default** variant from `templates/decision-capture.md`. Command name: `debate`.
-
 ---
 
 ## Rules

package/src/commands/df/discover.md

@@ -85,8 +85,6 @@ Example questions:
 - Keep your responses short between questions — don't lecture
 - Acknowledge answers briefly before asking the next question
 
-### Decision Capture
-Follow the **default** variant from `templates/decision-capture.md`. Command name: `discover`.
 ### When the User Wants to Move On
 When the user signals they want to advance (e.g., "I think that's enough", "let's move on", "ready for next step"):
 

package/src/commands/df/execute.md

@@ -380,13 +380,19 @@ When a task fails and cannot be auto-fixed:
 When all tasks done for a `doing-*` spec:
 1. Embed history in spec: `## Completed` section with task list and commit hashes
 2. Rename: `doing-upload.md` → `done-upload.md`
-3. Remove the spec's ENTIRE section from PLAN.md:
+3. Extract decisions from done-* spec: Read the `done-{name}.md` file. Model-extract architectural decisions — look for explicit choices (→ `[APPROACH]`), unvalidated assumptions (→ `[ASSUMPTION]`), and "for now" decisions (→ `[PROVISIONAL]`). Append as a new section to **main tree** `.deepflow/decisions.md`:
+   ```
+   ### {YYYY-MM-DD} — {spec-name}
+   - [TAG] decision text — rationale
+   ```
+   After successful append, delete `specs/done-{name}.md`. If write fails, preserve the file.
+4. Remove the spec's ENTIRE section from PLAN.md:
    - The `### doing-{spec}` header
    - All task entries (`- [x] **T{n}**: ...` and their sub-items)
    - Any `## Execution Summary` block for that spec
    - Any `### Fix Tasks` sub-section for that spec
    - Separators (`---`) between removed sections
-4. Recalculate the Summary table at the top of PLAN.md (update counts for completed/pending)
+5. Recalculate the Summary table at the top of PLAN.md (update counts for completed/pending)
 
 ### 10. ITERATE (Notification-Driven)
 
@@ -408,10 +414,6 @@ After spawning wave agents, your turn ENDS. Completion notifications drive the l
 
 **Repeat** until: all done, all blocked, or context ≥50% (checkpoint).
 
-### 11. CAPTURE DECISIONS
-
-Follow the **main-tree** variant from `templates/decision-capture.md`. Command name: `execute`.
-
 ## Rules
 
 | Rule | Detail |

package/src/commands/df/note.md

@@ -132,6 +132,7 @@ No decisions saved.
 - `[APPROACH]` — deliberate design or implementation choice
 - `[PROVISIONAL]` — works for now, will revisit at scale or with more information
 - `[ASSUMPTION]` — treating something as true without full confirmation
+- `[DEBT]` — needs revisiting; produced only by `/df:consolidate`, never manually assigned
 
 **Contradiction handling:** Never delete prior entries. When a new decision contradicts an older one, include a reference in the rationale: `was "X", now "Y" because Z`.
 

package/src/commands/df/plan.md

@@ -154,10 +154,6 @@ Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validatio
 
 `✓ Plan generated — {n} specs, {n} tasks. Run /df:execute`
 
-### 12. CAPTURE DECISIONS
-
-Follow the **default** variant from `templates/decision-capture.md`. Command name: `plan`.
-
 ## Rules
 - **Spike-first** — Generate spike task before full implementation if no `--passed.md` experiment exists
 - **Block on spike** — Full implementation tasks MUST be blocked by spike validation

package/src/commands/df/spec.md

@@ -130,10 +130,6 @@ Acceptance criteria: {count}
 Next: Run /df:plan to generate tasks
 ```
 
-### 6. CAPTURE DECISIONS
-
-Follow the **default** variant from `templates/decision-capture.md`. Command name: `spec`.
-
 ## Rules
 - **Orchestrator never searches** — Spawn agents for all codebase exploration
 - Do NOT generate spec if critical gaps remain

package/src/commands/df/verify.md

@@ -201,6 +201,28 @@ git branch -d "${WORKTREE_BRANCH}"
 rm -f .deepflow/checkpoint.json
 ```
 
+### 4. RENAME SPEC
+
+```bash
+# Rename spec to done
+mv specs/doing-${SPEC_NAME}.md specs/done-${SPEC_NAME}.md
+```
+
+### 5. EXTRACT DECISIONS
+
+Read the renamed `specs/done-${SPEC_NAME}.md` file. Model-extract architectural decisions:
+- Explicit choices → `[APPROACH]`
+- Unvalidated assumptions → `[ASSUMPTION]`
+- "For now" decisions → `[PROVISIONAL]`
+
+Append to `.deepflow/decisions.md`:
+```
+### {YYYY-MM-DD} — {spec-name}
+- [TAG] decision text — rationale
+```
+
+After successful append, delete `specs/done-${SPEC_NAME}.md`. If write fails, preserve the file.
+
 Output:
 ```
 ✓ Merged df/upload to main
@@ -210,6 +232,3 @@ Output:
 Workflow complete! Ready for next feature: /df:spec <name>
 ```
 
-### 4. CAPTURE DECISIONS (success path only)
-
-Follow the **success-path-only** variant from `templates/decision-capture.md`. Command name: `verify`.

package/templates/decision-capture.md

@@ -1,19 +0,0 @@
-# Decision Capture — Shared Pattern
-
-## Common Flow
-Extract up to 4 candidates → `AskUserQuestion(multiSelect: true)` → append confirmed to `.deepflow/decisions.md`.
-Each option: `label: "[TAG] <decision>"`, `description: "<rationale>"`. Tags: `[APPROACH]` `[PROVISIONAL]` `[ASSUMPTION]`.
-Format: `### {YYYY-MM-DD} — {command}` / `- [TAG] decision text — rationale`
-
-## Variant: default
-Used by: discover, debate, spec, plan, note.
-Append confirmed decisions to `.deepflow/decisions.md` (create if missing). Max 4 candidates.
-If a decision contradicts a prior entry, note conflict inline; never delete prior entries.
-
-## Variant: main-tree
-Used by: execute.
-Same as default but write to **main tree** `.deepflow/decisions.md` (repo root, parent of `.deepflow/worktrees/`), not the worktree path.
-
-## Variant: success-path-only
-Used by: verify.
-Same as default but **only run this step when verification passes**. Skip entirely on failure.