deepflow 0.1.50 → 0.1.52

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
@@ -129,6 +130,16 @@ Execution happens in an isolated git worktree:
 - Resume with `/df:execute --continue`
 - On success, `/df:verify` merges to main and cleans up
 
+## LSP Integration
+
+deepflow automatically enables Claude Code's LSP tools during install, giving agents access to `goToDefinition`, `findReferences`, and `workspaceSymbol` for precise code navigation instead of grep-based searching.
+
+- **Global install:** sets `ENABLE_LSP_TOOL=1` in `~/.claude/settings.json`
+- **Project install:** sets it in `.claude/settings.local.json`
+- **Uninstall:** cleans up automatically
+
+Agents prefer LSP tools when available and fall back to Grep/Glob silently. You'll need a language server installed for your language (e.g. `typescript-language-server`, `pyright`, `rust-analyzer`, `gopls`).
+
 ## Context-Aware Execution
 
 Statusline shows context usage. At ≥50%:
@@ -145,8 +156,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 +168,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

@@ -142,6 +142,11 @@ async function main() {
     await configureHooks(CLAUDE_DIR);
   }
 
+  // Configure project settings (project only)
+  if (level === 'project') {
+    configureProjectSettings(CLAUDE_DIR);
+  }
+
   console.log('');
   console.log(`${c.green}Installation complete!${c.reset}`);
   console.log('');
@@ -152,6 +157,7 @@ async function main() {
   if (level === 'global') {
     console.log('  hooks/           — statusline, update checker');
   }
+  console.log('  env/             — ENABLE_LSP_TOOL (code navigation via goToDefinition, findReferences, workspaceSymbol)');
   console.log('');
   if (level === 'project') {
     console.log(`${c.dim}Note: Statusline is only available with global install.${c.reset}`);
@@ -196,6 +202,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 = {};
 
@@ -207,6 +214,11 @@ async function configureHooks(claudeDir) {
     }
   }
 
+  // Enable LSP tool
+  if (!settings.env) settings.env = {};
+  settings.env.ENABLE_LSP_TOOL = "1";
+  log('LSP tool enabled');
+
   // Configure statusline
   if (settings.statusLine) {
     const answer = await ask(
@@ -234,7 +246,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,11 +256,40 @@ 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));
 }
 
+function configureProjectSettings(claudeDir) {
+  const settingsPath = path.join(claudeDir, 'settings.local.json');
+
+  let settings = {};
+
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (e) {
+      settings = {};
+    }
+  }
+
+  // Enable LSP tool
+  if (!settings.env) settings.env = {};
+  settings.env.ENABLE_LSP_TOOL = "1";
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  log('LSP tool enabled (project)');
+}
+
 function ask(question) {
   const rl = readline.createInterface({
     input: process.stdin,
@@ -330,7 +371,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 +400,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;
@@ -374,6 +415,44 @@ async function uninstall() {
         // Fail silently
       }
     }
+
+    // Remove ENABLE_LSP_TOOL from global settings
+    if (fs.existsSync(settingsPath)) {
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        if (settings.env?.ENABLE_LSP_TOOL) {
+          delete settings.env.ENABLE_LSP_TOOL;
+          if (settings.env && Object.keys(settings.env).length === 0) delete settings.env;
+          fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+          console.log(`  ${c.green}✓${c.reset} Removed ENABLE_LSP_TOOL from settings`);
+        }
+      } catch (e) {
+        // Fail silently
+      }
+    }
+  }
+
+  // Remove ENABLE_LSP_TOOL from project settings.local.json
+  if (level === 'project') {
+    const localSettingsPath = path.join(PROJECT_DIR, 'settings.local.json');
+    if (fs.existsSync(localSettingsPath)) {
+      try {
+        const localSettings = JSON.parse(fs.readFileSync(localSettingsPath, 'utf8'));
+        if (localSettings.env?.ENABLE_LSP_TOOL) {
+          delete localSettings.env.ENABLE_LSP_TOOL;
+          if (localSettings.env && Object.keys(localSettings.env).length === 0) delete localSettings.env;
+          if (Object.keys(localSettings).length === 0) {
+            fs.unlinkSync(localSettingsPath);
+            console.log(`  ${c.green}✓${c.reset} Removed settings.local.json (empty after cleanup)`);
+          } else {
+            fs.writeFileSync(localSettingsPath, JSON.stringify(localSettings, null, 2));
+            console.log(`  ${c.green}✓${c.reset} Removed ENABLE_LSP_TOOL from settings.local.json`);
+          }
+        }
+      } catch (e) {
+        // Fail silently
+      }
+    }
   }
 
   console.log('');

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.52",
   "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

@@ -328,6 +328,9 @@ Commit format: {commit_type}({spec}): {description}
 Result file: {worktree_absolute_path}/.deepflow/results/{task_id}.yaml
 
 STOP after writing the result file. Do NOT merge branches, rename spec files, remove worktrees, or run git checkout on main. These are handled by the orchestrator and /df:verify.
+
+Navigation: Prefer LSP tools (goToDefinition, findReferences, workspaceSymbol) over Grep/Glob for code navigation. Fall back to Grep/Glob if LSP unavailable.
+If LSP errors, install the language server (TS→typescript-language-server, Python→pyright, Rust→rust-analyzer, Go→gopls) and retry. If still unavailable, use Grep/Glob.
 ```
 
 **Standard Task (append after preamble):**
@@ -380,13 +383,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 +417,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

@@ -72,6 +72,7 @@ Run the build command in the worktree:
 
 Check requirements, acceptance criteria, and quality (stubs/TODOs).
 Mark each: ✓ satisfied | ✗ missing | ⚠ partial
+Prefer LSP tools (goToDefinition, findReferences, workspaceSymbol) when available; fall back to Grep/Glob silently.
 
 **L4: Test execution** (if test command detected)
 
@@ -141,9 +142,9 @@ Files: ...
 | Level | Check | Method | Runner |
 |-------|-------|--------|--------|
 | L0: Builds | Code compiles/builds | Run build command | Orchestrator (Bash) |
-| L1: Exists | File/function exists | Glob/Grep | Explore agents |
+| L1: Exists | File/function exists | Glob/Grep (prefer workspaceSymbol if available) | Explore agents |
 | L2: Substantive | Real code, not stub | Read + analyze | Explore agents |
-| L3: Wired | Integrated into system | Trace imports/calls | Explore agents |
+| L3: Wired | Integrated into system | Trace imports/calls (prefer findReferences if available) | Explore agents |
 | L4: Tested | Tests pass | Run test command | Orchestrator (Bash) |
 
 **Default: L0 through L4.** L0 and L4 skipped ONLY if no build/test command detected (see step 1.5). L0 and L4 run via Bash — Explore agents cannot execute commands.
@@ -201,6 +202,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 +233,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.