deepflow 0.1.108 → 0.1.109

package/bin/ratchet.js

@@ -282,6 +282,10 @@ const SALVAGEABLE_STAGES = new Set(['lint']);
 // CLI argument parser
 // ---------------------------------------------------------------------------
 
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 function parseArgs(argv) {
   const args = { task: null, worktree: null, snapshot: null };
   for (let i = 0; i < argv.length; i++) {
@@ -316,8 +320,9 @@ function updatePlanMd(repoRoot, taskId, cwd) {
   }
 
   const text = fs.readFileSync(planPath, 'utf8');
+  const safeTaskId = escapeRegExp(taskId);
   // Match lines like: - [ ] **T54** ...
-  const re = new RegExp(`(^.*- \\[ \\].*\\*\\*${taskId}\\*\\*.*)`, 'm');
+  const re = new RegExp(`(^.*- \\[ \\].*\\*\\*${safeTaskId}\\*\\*.*)`, 'm');
   const updated = text.replace(re, (line) => {
     let result = line.replace('- [ ]', '- [x]');
     if (hash) result += ` (${hash})`;

package/hooks/ac-coverage.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * deepflow AC coverage checker
+ * Standalone script called by the orchestrator after ratchet checks.
+ *
+ * Usage:
+ *   node ac-coverage.js --spec <path> --output <text> --status <pass|fail|revert>
+ *   node ac-coverage.js --spec <path> --output-file <path> --status <pass|fail|revert>
+ *
+ * Exit codes:
+ *   0 — all ACs covered, no ACs in spec, or input status was fail/revert
+ *   2 — SALVAGEABLE: missed ACs detected and input status was pass
+ *   1 — script error only
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+// ── Argument parsing ────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--spec' && argv[i + 1]) { args.spec = argv[++i]; }
+    else if (a === '--output' && argv[i + 1]) { args.output = argv[++i]; }
+    else if (a === '--output-file' && argv[i + 1]) { args.outputFile = argv[++i]; }
+    else if (a === '--status' && argv[i + 1]) { args.status = argv[++i]; }
+  }
+  return args;
+}
+
+// ── Section extraction ──────────────────────────────────────────────────────
+
+/**
+ * Extract content of `## Acceptance Criteria` section (up to next ## or EOF).
+ * Returns null if the section is absent.
+ */
+function extractACSection(content) {
+  const lines = content.split('\n');
+  let capturing = false;
+  const captured = [];
+
+  for (const line of lines) {
+    const headerMatch = line.match(/^##\s+(.+)/);
+    if (headerMatch) {
+      if (capturing) break; // next section — stop
+      if (/^acceptance criteria$/i.test(headerMatch[1].trim())) {
+        capturing = true;
+      }
+      continue;
+    }
+    if (capturing) {
+      captured.push(line);
+    }
+  }
+
+  return capturing ? captured.join('\n') : null;
+}
+
+// ── AC extraction from spec ─────────────────────────────────────────────────
+
+/**
+ * Extract canonical AC-N identifiers from the spec's Acceptance Criteria section.
+ * Returns null if no section found, empty array if section exists but has no AC-\d+ patterns.
+ */
+function extractSpecACs(specContent) {
+  const section = extractACSection(specContent);
+  if (section === null) return null;
+
+  const ids = new Set();
+  const pattern = /\bAC-(\d+)\b/g;
+  let m;
+  while ((m = pattern.exec(section)) !== null) {
+    ids.add(`AC-${m[1]}`);
+  }
+  return [...ids].sort((a, b) => {
+    const na = parseInt(a.replace('AC-', ''), 10);
+    const nb = parseInt(b.replace('AC-', ''), 10);
+    return na - nb;
+  });
+}
+
+// ── AC parsing from agent output ────────────────────────────────────────────
+
+/**
+ * Parse AC_COVERAGE block from agent output.
+ * Returns a Map of AC-N → { status: 'done'|'skip', reason: string|null }
+ */
+function parseACCoverage(outputText) {
+  const map = new Map();
+
+  const blockMatch = outputText.match(/AC_COVERAGE:([\s\S]*?)AC_COVERAGE_END/);
+  if (!blockMatch) return map;
+
+  const block = blockMatch[1];
+  const linePattern = /^(AC-\d+):(done|skip)(?::(.+))?$/gm;
+  let m;
+  while ((m = linePattern.exec(block)) !== null) {
+    map.set(m[1], {
+      status: m[2],
+      reason: m[3] ? m[3].trim() : null,
+    });
+  }
+  return map;
+}
+
+// ── Main logic ──────────────────────────────────────────────────────────────
+
+function run(args) {
+  if (!args.spec) {
+    console.error('[ac-coverage] Error: --spec is required');
+    process.exit(1);
+  }
+  if (!args.status) {
+    console.error('[ac-coverage] Error: --status is required');
+    process.exit(1);
+  }
+
+  // Read spec
+  let specContent;
+  try {
+    specContent = fs.readFileSync(args.spec, 'utf8');
+  } catch (e) {
+    console.error(`[ac-coverage] Error reading spec: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Extract canonical ACs (AC-2, AC-7, AC-8)
+  const specACs = extractSpecACs(specContent);
+
+  // AC-7: no Acceptance Criteria section → silent exit
+  if (specACs === null) {
+    process.exit(0);
+  }
+
+  // AC-8: section exists but no AC-\d+ patterns → silent exit
+  if (specACs.length === 0) {
+    process.exit(0);
+  }
+
+  // Read agent output
+  let outputText = '';
+  if (args.outputFile) {
+    try {
+      outputText = fs.readFileSync(args.outputFile, 'utf8');
+    } catch (e) {
+      console.error(`[ac-coverage] Error reading output file: ${e.message}`);
+      process.exit(1);
+    }
+  } else if (args.output !== undefined) {
+    outputText = args.output;
+  }
+
+  // AC-3: parse AC_COVERAGE block from agent output
+  const reported = parseACCoverage(outputText);
+
+  // AC-3: diff — identify missed ACs (not reported as done)
+  const missed = [];
+  const skipped = [];
+  let coveredCount = 0;
+
+  for (const id of specACs) {
+    const entry = reported.get(id);
+    if (entry && entry.status === 'done') {
+      coveredCount++;
+    } else if (entry && entry.status === 'skip') {
+      skipped.push({ id, reason: entry.reason });
+    } else {
+      missed.push(id);
+    }
+  }
+
+  const totalACs = specACs.length;
+  const reportedDoneCount = coveredCount;
+
+  // AC-6: summary line
+  const summaryParts = [];
+  if (missed.length > 0) {
+    summaryParts.push(`missed: ${missed.join(', ')}`);
+  }
+  if (skipped.length > 0) {
+    const skipDesc = skipped.map(s => s.reason ? `${s.id} (${s.reason})` : s.id).join(', ');
+    summaryParts.push(`skipped: ${skipDesc}`);
+  }
+
+  const summaryDetail = summaryParts.length > 0 ? ` — ${summaryParts.join('; ')}` : '';
+  console.log(`[ac-coverage] ${reportedDoneCount}/${totalACs} ACs covered${summaryDetail}`);
+
+  // AC-4 / AC-5: status override
+  const inputStatus = args.status;
+  const hasMissed = missed.length > 0;
+
+  if (hasMissed && inputStatus === 'pass') {
+    // AC-4: override to SALVAGEABLE
+    console.log('OVERRIDE:SALVAGEABLE');
+    process.exit(2);
+  } else {
+    // AC-5: all done, or status was already fail/revert — no override
+    console.log('OVERRIDE:none');
+    process.exit(0);
+  }
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const args = parseArgs(process.argv.slice(2));
+  run(args);
+}
+
+module.exports = { extractSpecACs, parseACCoverage, extractACSection };

package/hooks/df-explore-protocol.js

@@ -10,6 +10,10 @@
  *   1. {cwd}/templates/explore-protocol.md  (repo checkout)
  *   2. ~/.claude/templates/explore-protocol.md  (installed copy)
  *
+ * Phase 1: globs source files and extracts symbols via inline regex — no subprocess,
+ * no model calls. Results are filtered to strip noise paths and injected as
+ * structured context for Phase 2.
+ *
  * Exits silently (code 0) on all errors — never blocks tool execution (REQ-8).
  */
 
@@ -20,6 +24,135 @@ const path = require('path');
 const os = require('os');
 const { readStdinIfMain } = require('./lib/hook-stdin');
 
+/**
+ * Regex patterns per language extension for symbol extraction.
+ * Spike-validated against JS/TS/Python/Go/Rust codebases.
+ */
+const PATTERNS = {
+  '.js':  /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class|interface|type|enum)\s+(\w+)/gm,
+  '.ts':  /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class|interface|type|enum)\s+(\w+)/gm,
+  '.py':  /^(?:async\s+)?(?:def|class)\s+(\w+)/gm,
+  '.go':  /^(?:func(?:\s*\([^)]*\))?\s+(\w+)|type\s+(\w+)\s+(?:struct|interface|func))/gm,
+  '.rs':  /^(?:pub\s+)?(?:async\s+)?(?:fn|struct|enum|trait|impl|type|mod)\s+(\w+)/gm,
+};
+
+/**
+ * Generic fallback pattern for unknown extensions.
+ * Covers the most common declaration keywords across languages.
+ */
+const PATTERN_GENERIC = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class|def|fn|struct|enum|trait|type|interface|mod)\s+(\w+)/gm;
+
+/**
+ * Map extensions that share a pattern with a canonical key.
+ */
+const EXTENSION_MAP = {
+  '.jsx':  '.js',
+  '.tsx':  '.ts',
+  '.mjs':  '.js',
+  '.cjs':  '.js',
+};
+
+/**
+ * Path filter — returns true if the filepath should be excluded.
+ * Strips node_modules, .claude/worktrees, dist, .git, vendor,
+ * __pycache__, .next, and build directories.
+ */
+function isNoisePath(filepath) {
+  return /(node_modules|\.claude\/worktrees|\/dist\/|\.git\/|\/vendor\/|__pycache__|\/\.next\/|\/build\/)/.test(filepath);
+}
+
+/**
+ * Recursively walk a directory, yielding absolute file paths.
+ * Silently skips unreadable directories.
+ */
+function* walkDir(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!isNoisePath(full + '/')) yield* walkDir(full);
+    } else if (entry.isFile()) {
+      yield full;
+    }
+  }
+}
+
+/**
+ * Run Phase 1: glob source files and extract symbols via inline regex.
+ * Returns { symbols: [{name, kind, line, filepath}], hit: boolean }.
+ * No subprocess, no model calls — pure Node.js (AC-1).
+ *
+ * @param {string} query  - The explore prompt used for substring filtering (AC-15).
+ * @param {string} cwd    - Project root to walk.
+ */
+function runPhase1(query, cwd) {
+  const queryLower = query.toLowerCase();
+  const symbols = [];
+
+  try {
+    for (const filepath of walkDir(cwd)) {
+      if (isNoisePath(filepath)) continue;
+
+      const ext = path.extname(filepath).toLowerCase();
+      const canonExt = EXTENSION_MAP[ext] || ext;
+      const pattern = PATTERNS[canonExt] || PATTERN_GENERIC;
+
+      // AC-15: filter by substring match on file path
+      const filepathLower = filepath.toLowerCase();
+      const pathMatches = filepathLower.includes(queryLower);
+
+      let content;
+      try {
+        content = fs.readFileSync(filepath, 'utf8');
+      } catch (_) {
+        continue;
+      }
+
+      const lines = content.split('\n');
+      // Reset lastIndex before each use of the shared regex
+      const re = new RegExp(pattern.source, pattern.flags);
+      let m;
+      while ((m = re.exec(content)) !== null) {
+        // Capture group 1 is always the symbol name (Go uses group 2 for type decls)
+        const name = m[1] || m[2];
+        if (!name) continue;
+
+        // AC-15: filter by substring match on symbol name or file path
+        const nameLower = name.toLowerCase();
+        if (!nameLower.includes(queryLower) && !pathMatches) continue;
+
+        // Compute 1-based line number from the match offset
+        const before = content.slice(0, m.index);
+        const line = before.split('\n').length;
+
+        // Derive kind from the matched keyword
+        const matchedText = m[0];
+        let kind = 'symbol';
+        if (/\bclass\b/.test(matchedText)) kind = 'class';
+        else if (/\bfunction\b|\bfn\b|\bdef\b|\bfunc\b/.test(matchedText)) kind = 'function';
+        else if (/\binterface\b/.test(matchedText)) kind = 'interface';
+        else if (/\btype\b/.test(matchedText)) kind = 'type';
+        else if (/\benum\b/.test(matchedText)) kind = 'enum';
+        else if (/\bstruct\b/.test(matchedText)) kind = 'struct';
+        else if (/\btrait\b/.test(matchedText)) kind = 'trait';
+        else if (/\bmod\b/.test(matchedText)) kind = 'module';
+        else if (/\bimpl\b/.test(matchedText)) kind = 'impl';
+
+        symbols.push({ name, kind, line, filepath });
+      }
+    }
+  } catch (_) {
+    // Fail-open: return whatever was gathered so far
+  }
+
+  return { symbols, hit: symbols.length > 0 };
+}
+
 /**
  * Locate the explore-protocol.md template.
  * Prefers project-local copy, falls back to installed global copy.
@@ -36,39 +169,105 @@ function findProtocol(cwd) {
 }
 
 readStdinIfMain(module, (payload) => {
-  const { tool_name, tool_input, cwd } = payload;
+  try {
+    const { tool_name, tool_input, cwd } = payload;
 
-  // Only intercept Agent calls with subagent_type "Explore"
-  if (tool_name !== 'Agent') {
-    return;
-  }
-  const subagentType = (tool_input.subagent_type || '').toLowerCase();
-  if (subagentType !== 'explore') {
-    return;
-  }
+    // Only intercept Agent calls with subagent_type "Explore"
+    if (tool_name !== 'Agent') {
+      return;
+    }
+    const subagentType = (tool_input.subagent_type || '').toLowerCase();
+    if (subagentType !== 'explore') {
+      return;
+    }
 
-  const protocolPath = findProtocol(cwd || process.cwd());
-  if (!protocolPath) {
-    // No template found — allow without modification
-    return;
-  }
+    const effectiveCwd = cwd || process.cwd();
+
+    // --- Deduplication guard (AC-8) ---
+    // If the prompt already carries injected markers, skip re-injection entirely.
+    const existingPrompt = tool_input.prompt || '';
+    if (
+      existingPrompt.includes('Search Protocol (auto-injected') ||
+      existingPrompt.includes('LSP Phase')
+    ) {
+      return;
+    }
+
+    const protocolPath = findProtocol(effectiveCwd);
+    const originalPrompt = existingPrompt;
 
-  const protocol = fs.readFileSync(protocolPath, 'utf8').trim();
-  const originalPrompt = tool_input.prompt || '';
+    // --- Phase 1: inline regex symbol extraction (AC-1, AC-7, AC-9) ---
+    const { symbols, hit: phase1Hit } = runPhase1(originalPrompt, effectiveCwd);
 
-  // Append protocol as a system-level suffix the agent must follow
-  const updatedPrompt = `${originalPrompt}\n\n---\n## Search Protocol (auto-injected — MUST follow)\n\n${protocol}`;
+    let updatedPrompt;
 
-  const result = {
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'allow',
-      updatedInput: {
-        ...tool_input,
-        prompt: updatedPrompt,
+    if (phase1Hit) {
+      // Phase 1 succeeded — inject symbol locations + protocol (requires template)
+      if (!protocolPath) {
+        // No template found and Phase 1 succeeded — allow without modification
+        return;
+      }
+      const protocol = fs.readFileSync(protocolPath, 'utf8').trim();
+
+      // AC-3: Format each symbol as `filepath:line -- name (kind)`
+      const locationLines = symbols
+        .map((s) => `${s.filepath}:${s.line} -- ${s.name} (${s.kind})`)
+        .join('\n');
+      const phase1Block =
+        '\n\n---\n## [LSP Phase -- locations found]\n\n' +
+        locationLines +
+        '\n\nRead ONLY these ranges. Do not use Grep, Glob, or Bash.';
+
+      updatedPrompt =
+        `${originalPrompt}${phase1Block}\n\n---\n## Search Protocol (auto-injected — MUST follow)\n\n${protocol}`;
+    } else {
+      // Phase 1 empty — fall back to static template injection (AC-5)
+      if (!protocolPath) {
+        // AC-6: no template and regex found nothing — exit silently with no modification
+        return;
+      }
+      const protocol = fs.readFileSync(protocolPath, 'utf8').trim();
+
+      // Inject static template only, with auto-injected marker so dedup guard fires next time
+      updatedPrompt =
+        `${originalPrompt}\n\n---\n## Search Protocol (auto-injected — MUST follow)\n\n${protocol}`;
+    }
+
+    const result = {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: {
+          ...tool_input,
+          prompt: updatedPrompt,
+        },
       },
-    },
-  };
+    };
+
+    // --- Metrics logging (fail-open) ---
+    // Log phase 1 hit rate to explore-metrics.jsonl.
+    // Wraps in try/catch so metrics failures never block hook execution.
+    try {
+      const metricsDir = path.join(effectiveCwd, '.deepflow');
+      const metricsPath = path.join(metricsDir, 'explore-metrics.jsonl');
+      if (!fs.existsSync(metricsDir)) {
+        fs.mkdirSync(metricsDir, { recursive: true });
+      }
+      const metricsEntry = {
+        timestamp: new Date().toISOString(),
+        query: originalPrompt,
+        phase1_hit: phase1Hit,
+        // tool_calls intentionally omitted: PreToolUse hooks fire before tool execution,
+        // so actual tool call counts are not observable here without a PostToolUse hook.
+      };
+      fs.appendFileSync(metricsPath, JSON.stringify(metricsEntry) + '\n', 'utf8');
+    } catch (_) {
+      // Metrics logging failure is silent — never blocks execution (REQ-8).
+    }
 
-  process.stdout.write(JSON.stringify(result));
+    process.stdout.write(JSON.stringify(result));
+  } catch (_) {
+    // AC-10: catch ALL errors — malformed JSON, missing tool_input, filesystem errors, etc.
+    // Always exit 0; never block tool execution (REQ-8).
+  }
 });

package/hooks/df-explore-protocol.test.js

@@ -1,8 +1,12 @@
 /**
  * Tests for df-explore-protocol.js — PreToolUse hook
  *
- * Verifies that the hook injects the explore-protocol.md search protocol
- * into Explore agent prompts via updatedInput.
+ * Two-phase behavior coverage:
+ *   Phase 1: inline regex extraction from source files in cwd
+ *   Phase 2: inject symbol locations + static template into prompt
+ *
+ * All tests control Phase 1 by writing fixture source files to a tmpDir,
+ * then passing that tmpDir as cwd. No subprocess, no fake `claude` binary.
  */
 
 'use strict';
@@ -15,6 +19,43 @@ const path = require('node:path');
 const os = require('node:os');
 
 const HOOK_PATH = path.resolve(__dirname, 'df-explore-protocol.js');
+const PROTOCOL_CONTENT =
+  '# Explore Agent Pattern\n\nReturn ONLY:\n- filepath:startLine-endLine -- why relevant';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a temp project directory with an optional explore-protocol.md template
+ * and optional .deepflow/config.yaml.
+ */
+function createTempProject({ withTemplate = true, configYaml = null } = {}) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'df-explore-test-'));
+  if (withTemplate) {
+    const templatesDir = path.join(tmpDir, 'templates');
+    fs.mkdirSync(templatesDir, { recursive: true });
+    fs.writeFileSync(path.join(templatesDir, 'explore-protocol.md'), PROTOCOL_CONTENT);
+  }
+  if (configYaml) {
+    const dfDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(dfDir, { recursive: true });
+    fs.writeFileSync(path.join(dfDir, 'config.yaml'), configYaml);
+  }
+  return tmpDir;
+}
+
+/**
+ * Write a fixture source file into tmpDir/src/ with the given content.
+ * Returns the absolute path of the written file.
+ */
+function writeFixtureFile(tmpDir, filename, content) {
+  const srcDir = path.join(tmpDir, 'src');
+  fs.mkdirSync(srcDir, { recursive: true });
+  const filepath = path.join(srcDir, filename);
+  fs.writeFileSync(filepath, content);
+  return filepath;
+}
 
 /**
  * Run the hook as a child process with JSON piped to stdin.
@@ -23,19 +64,14 @@ const HOOK_PATH = path.resolve(__dirname, 'df-explore-protocol.js');
 function runHook(input, { cwd, home } = {}) {
   const json = typeof input === 'string' ? input : JSON.stringify(input);
   const env = { ...process.env };
-  if (cwd) env.CWD_OVERRIDE = cwd;
   if (home) env.HOME = home;
   try {
-    const stdout = execFileSync(
-      process.execPath,
-      [HOOK_PATH],
-      {
-        input: json,
-        encoding: 'utf8',
-        timeout: 5000,
-        env,
-      }
-    );
+    const stdout = execFileSync(process.execPath, [HOOK_PATH], {
+      input: json,
+      encoding: 'utf8',
+      timeout: 10000,
+      env,
+    });
     return { stdout, stderr: '', code: 0 };
   } catch (err) {
     return {
@@ -46,19 +82,9 @@ function runHook(input, { cwd, home } = {}) {
   }
 }
 
-/**
- * Create a temp directory with a mock explore-protocol.md template.
- */
-function createTempProject(protocolContent) {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'df-explore-test-'));
-  const templatesDir = path.join(tmpDir, 'templates');
-  fs.mkdirSync(templatesDir, { recursive: true });
-  fs.writeFileSync(
-    path.join(templatesDir, 'explore-protocol.md'),
-    protocolContent || '# Explore Agent Pattern\n\nReturn ONLY:\n- filepath:startLine-endLine -- why relevant'
-  );
-  return tmpDir;
-}
+// ---------------------------------------------------------------------------
+// Test suite
+// ---------------------------------------------------------------------------
 
 describe('df-explore-protocol hook', () => {
   let tmpDir;
@@ -71,65 +97,103 @@ describe('df-explore-protocol hook', () => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
-  test('injects protocol into Explore agent prompt', () => {
+  // -------------------------------------------------------------------------
+  // AC-1: Phase 1 uses inline regex extraction — no subprocess required
+  // -------------------------------------------------------------------------
+  test('AC-1: Phase 1 uses inline regex extraction without requiring a claude binary', () => {
+    // Write a fixture file with a function whose name matches the query substring
+    writeFixtureFile(tmpDir, 'index.js', 'function databaseConfig() { return {}; }\n');
+
+    // Query is just the symbol name so it substring-matches the symbol "databaseConfig"
     const input = {
       tool_name: 'Agent',
-      tool_input: {
-        subagent_type: 'Explore',
-        prompt: 'Find: config files related to database',
-        model: 'haiku',
-      },
+      tool_input: { subagent_type: 'Explore', prompt: 'databaseConfig' },
       cwd: tmpDir,
     };
 
-    const { stdout, code } = runHook(input);
+    // Run without any PATH manipulation — no fake claude binary needed
+    const { code, stdout } = runHook(input);
     assert.equal(code, 0);
 
+    // Phase 1 should have found the symbol; LSP block injected
     const result = JSON.parse(stdout);
-    const updated = result.hookSpecificOutput.updatedInput;
-
-    assert.ok(updated.prompt.includes('Find: config files related to database'));
-    assert.ok(updated.prompt.includes('filepath:startLine-endLine'));
-    assert.ok(updated.prompt.includes('Search Protocol (auto-injected'));
-    assert.equal(updated.subagent_type, 'Explore');
-    assert.equal(updated.model, 'haiku');
-    assert.equal(result.hookSpecificOutput.permissionDecision, 'allow');
+    const prompt = result.hookSpecificOutput.updatedInput.prompt;
+    assert.ok(
+      prompt.includes('[LSP Phase -- locations found]'),
+      'Expected [LSP Phase -- locations found] section from regex extraction'
+    );
   });
 
-  test('ignores non-Agent tool calls', () => {
+  // -------------------------------------------------------------------------
+  // AC-2: Phase 1 hit injects [LSP Phase -- locations found] section
+  // -------------------------------------------------------------------------
+  test('AC-2: Phase 1 hit injects [LSP Phase -- locations found] section into prompt', () => {
+    // Write fixture files whose symbol names contain the query substring "connect"
+    writeFixtureFile(tmpDir, 'config.ts', 'export function dbConnect() { return {}; }\n');
+    writeFixtureFile(tmpDir, 'db.ts', 'export async function connectDB() {}\n');
+
+    // Query "connect" matches both symbols by substring
     const input = {
-      tool_name: 'Read',
-      tool_input: { file_path: '/some/file.ts' },
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore', prompt: 'connect' },
       cwd: tmpDir,
     };
 
     const { stdout, code } = runHook(input);
     assert.equal(code, 0);
-    assert.equal(stdout, '');
+
+    const result = JSON.parse(stdout);
+    const prompt = result.hookSpecificOutput.updatedInput.prompt;
+
+    assert.ok(
+      prompt.includes('[LSP Phase -- locations found]'),
+      'Expected [LSP Phase -- locations found] section'
+    );
+    assert.ok(
+      prompt.includes('Search Protocol (auto-injected'),
+      'Expected Search Protocol section'
+    );
+    assert.ok(prompt.includes(PROTOCOL_CONTENT.slice(0, 30)), 'Expected protocol content');
   });
 
-  test('ignores non-Explore agent calls', () => {
+  // -------------------------------------------------------------------------
+  // AC-3: Reader-phase entries in filepath:line format
+  // -------------------------------------------------------------------------
+  test('AC-3: LSP locations are formatted as filepath:line -- symbolName (symbolKind)', () => {
+    // Write a fixture file whose symbol name contains "myFunc" (matches query substring)
+    const srcDir = path.join(tmpDir, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    const filepath = path.join(srcDir, 'utils.ts');
+    // Place the function at line 1
+    fs.writeFileSync(filepath, 'export function myFunc() {}\n');
+
+    // Query "myFunc" matches the symbol name by substring
     const input = {
       tool_name: 'Agent',
-      tool_input: {
-        subagent_type: 'reasoner',
-        prompt: 'Analyze this code',
-      },
+      tool_input: { subagent_type: 'Explore', prompt: 'myFunc' },
       cwd: tmpDir,
     };
 
     const { stdout, code } = runHook(input);
     assert.equal(code, 0);
-    assert.equal(stdout, '');
+
+    const prompt = JSON.parse(stdout).hookSpecificOutput.updatedInput.prompt;
+    assert.ok(
+      prompt.includes(`${filepath}:1 -- myFunc (function)`),
+      `Expected filepath:line format, prompt: ${prompt}`
+    );
   });
 
-  test('handles case-insensitive subagent_type', () => {
+  // -------------------------------------------------------------------------
+  // AC-5: No matching symbols → fallback to static template injection
+  // -------------------------------------------------------------------------
+  test('AC-5: no matching symbols falls back to static template injection', () => {
+    // Write a fixture file whose symbol/path do NOT match the query "xyzRouteHandler"
+    writeFixtureFile(tmpDir, 'unrelated.js', 'function completelyDifferent() {}\n');
+
     const input = {
       tool_name: 'Agent',
-      tool_input: {
-        subagent_type: 'explore',
-        prompt: 'Find: test utilities',
-      },
+      tool_input: { subagent_type: 'Explore', prompt: 'xyzRouteHandler' },
       cwd: tmpDir,
     };
 
@@ -137,45 +201,245 @@ describe('df-explore-protocol hook', () => {
     assert.equal(code, 0);
 
     const result = JSON.parse(stdout);
-    assert.ok(result.hookSpecificOutput.updatedInput.prompt.includes('Search Protocol'));
+    const prompt = result.hookSpecificOutput.updatedInput.prompt;
+
+    // Should inject protocol but NOT the LSP phase block
+    assert.ok(prompt.includes('Search Protocol (auto-injected'), 'Expected protocol injection');
+    assert.ok(
+      !prompt.includes('[LSP Phase -- locations found]'),
+      'Must NOT include LSP phase block when no symbols match'
+    );
+    assert.ok(prompt.includes('xyzRouteHandler'), 'Original prompt preserved');
   });
 
-  test('exits cleanly when no template found', () => {
-    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'df-explore-empty-'));
+  // -------------------------------------------------------------------------
+  // AC-6: No template + no matching symbols → exit 0 with no output
+  // -------------------------------------------------------------------------
+  test('AC-6: no template and no matching symbols exits 0 with no output', () => {
+    const emptyDir = createTempProject({ withTemplate: false });
     const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'df-explore-home-'));
+
     try {
       const input = {
         tool_name: 'Agent',
-        tool_input: {
-          subagent_type: 'Explore',
-          prompt: 'Find: something',
-        },
+        tool_input: { subagent_type: 'Explore', prompt: 'Find: something' },
         cwd: emptyDir,
       };
 
       const { stdout, code } = runHook(input, { home: fakeHome });
       assert.equal(code, 0);
-      assert.equal(stdout, '');
+      assert.equal(stdout, '', 'Expected empty stdout when no template and no symbols match');
     } finally {
       fs.rmSync(emptyDir, { recursive: true, force: true });
       fs.rmSync(fakeHome, { recursive: true, force: true });
     }
   });
 
-  test('exits cleanly on malformed JSON input', () => {
-    const { code } = runHook('not valid json');
+  // -------------------------------------------------------------------------
+  // AC-7: Path filtering removes node_modules, .claude/worktrees, dist paths
+  // -------------------------------------------------------------------------
+  test('AC-7: noise paths filtered out — node_modules, .claude/worktrees, dist, .git', () => {
+    // Write a good source file with a symbol name that IS the query
+    const srcDir = path.join(tmpDir, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    const goodFile = path.join(srcDir, 'main.ts');
+    fs.writeFileSync(goodFile, 'export function targetSymbol() {}\n');
+
+    // Write noise files that also declare targetSymbol but live in noise paths
+    const nodeModDir = path.join(tmpDir, 'node_modules', 'lib');
+    fs.mkdirSync(nodeModDir, { recursive: true });
+    fs.writeFileSync(path.join(nodeModDir, 'index.js'), 'function targetSymbol() {}\n');
+
+    const worktreeDir = path.join(tmpDir, '.claude', 'worktrees', 'branch');
+    fs.mkdirSync(worktreeDir, { recursive: true });
+    fs.writeFileSync(path.join(worktreeDir, 'file.ts'), 'function targetSymbol() {}\n');
+
+    const distDir = path.join(tmpDir, 'dist');
+    fs.mkdirSync(distDir, { recursive: true });
+    fs.writeFileSync(path.join(distDir, 'bundle.js'), 'function targetSymbol() {}\n');
+
+    const gitDir = path.join(tmpDir, '.git', 'hooks');
+    fs.mkdirSync(gitDir, { recursive: true });
+    fs.writeFileSync(path.join(gitDir, 'pre-commit'), 'function targetSymbol() {}\n');
+
+    const input = {
+      // Query "targetSymbol" substring-matches the symbol name in all files,
+      // but only the good file should survive the noise-path filter
+      tool_input: { subagent_type: 'Explore', prompt: 'targetSymbol' },
+      tool_name: 'Agent',
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+
+    const prompt = JSON.parse(stdout).hookSpecificOutput.updatedInput.prompt;
+    assert.ok(prompt.includes(goodFile), 'Good path should be present');
+    assert.ok(!prompt.includes('node_modules'), 'node_modules should be filtered');
+    assert.ok(!prompt.includes('.claude/worktrees'), '.claude/worktrees should be filtered');
+    assert.ok(!prompt.includes('/dist/'), 'dist should be filtered');
+    assert.ok(!prompt.includes('.git/hooks'), '.git should be filtered');
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-7 edge: all symbols in noise paths → falls back to static template (no LSP block)
+  // -------------------------------------------------------------------------
+  test('AC-7: all symbols filtered → falls back to static template (no LSP block)', () => {
+    // Write only a noise file that would match the query but lives in node_modules
+    const nodeModDir = path.join(tmpDir, 'node_modules', 'lib');
+    fs.mkdirSync(nodeModDir, { recursive: true });
+    fs.writeFileSync(path.join(nodeModDir, 'index.js'), 'function badNodeModules() {}\n');
+
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore', prompt: 'Find: functions' },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
     assert.equal(code, 0);
+
+    const prompt = JSON.parse(stdout).hookSpecificOutput.updatedInput.prompt;
+    assert.ok(
+      !prompt.includes('[LSP Phase -- locations found]'),
+      'Should not inject LSP block when all paths filtered'
+    );
+    assert.ok(prompt.includes('Search Protocol (auto-injected'), 'Should still inject protocol');
   });
 
-  test('preserves all original tool_input fields', () => {
+  // -------------------------------------------------------------------------
+  // AC-8: Deduplication guard prevents double-injection
+  // -------------------------------------------------------------------------
+  test('AC-8: dedup guard — skips injection if Search Protocol already present', () => {
     const input = {
       tool_name: 'Agent',
       tool_input: {
         subagent_type: 'Explore',
-        prompt: 'Find: API routes',
+        prompt:
+          'Find: config\n\n---\n## Search Protocol (auto-injected — MUST follow)\n\nalready here',
+      },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+    // Dedup guard should fire — no output (hook returns without modification)
+    assert.equal(stdout, '', 'Expected no output when dedup guard fires');
+  });
+
+  test('AC-8: dedup guard — skips injection if LSP Phase already present', () => {
+    const input = {
+      tool_name: 'Agent',
+      tool_input: {
+        subagent_type: 'Explore',
+        prompt: 'Find: config\n\n## [LSP Phase -- locations found]\n\n/some/file.ts:10 -- foo (Fn)',
+      },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+    assert.equal(stdout, '', 'Expected no output when LSP Phase marker already present');
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-9: No subprocess means timeout config has no effect — static fallback still works
+  // -------------------------------------------------------------------------
+  test('AC-9: config with explore_lsp_timeout_ms is ignored — regex extraction always runs inline', () => {
+    // Create project with a very short timeout config (no longer relevant, but must not crash)
+    const projectWithConfig = createTempProject({
+      configYaml: 'explore_lsp_timeout_ms: 100\n',
+    });
+
+    // No matching symbols in the project directory
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore', prompt: 'Find: symbols' },
+      cwd: projectWithConfig,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+
+    // Should fall back to static template since no matching symbols
+    const result = JSON.parse(stdout);
+    const prompt = result.hookSpecificOutput.updatedInput.prompt;
+    assert.ok(prompt.includes('Search Protocol (auto-injected'), 'Should inject static protocol');
+    assert.ok(
+      !prompt.includes('[LSP Phase -- locations found]'),
+      'Should NOT have LSP block (no matching symbols)'
+    );
+
+    fs.rmSync(projectWithConfig, { recursive: true, force: true });
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-10: Exit 0 on malformed JSON input
+  // -------------------------------------------------------------------------
+  test('AC-10: exits 0 on malformed JSON stdin', () => {
+    const { code, stdout } = runHook('not valid json {{ }}');
+    assert.equal(code, 0);
+    assert.equal(stdout, '');
+  });
+
+  // AC-10: missing tool_input field
+  test('AC-10: exits 0 when tool_input is missing', () => {
+    const input = {
+      tool_name: 'Agent',
+      // tool_input deliberately omitted
+      cwd: tmpDir,
+    };
+
+    const { code } = runHook(input);
+    assert.equal(code, 0);
+  });
+
+  // AC-10: filesystem error (cwd that does not exist)
+  test('AC-10: exits 0 when cwd does not exist (filesystem error)', () => {
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore', prompt: 'Find: something' },
+      cwd: '/nonexistent/path/that/does/not/exist',
+    };
+
+    const { code } = runHook(input);
+    assert.equal(code, 0);
+  });
+
+  // AC-10: no source files in cwd → fallback to static protocol
+  test('AC-10: exits 0 and falls back to static protocol when cwd has no matching source files', () => {
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore', prompt: 'Find: something' },
+      cwd: tmpDir,
+    };
+
+    const { code, stdout } = runHook(input);
+    assert.equal(code, 0);
+    // Should fall back to static protocol
+    const result = JSON.parse(stdout);
+    assert.ok(
+      result.hookSpecificOutput.updatedInput.prompt.includes('Search Protocol (auto-injected')
+    );
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-12: All original tool_input fields preserved in updatedInput
+  // -------------------------------------------------------------------------
+  test('AC-12: all original tool_input fields preserved after Phase 1 hit', () => {
+    // Write a fixture whose symbol name contains "ApiRoutes" — matches query by substring
+    writeFixtureFile(tmpDir, 'api.ts', 'export class ApiRoutes {}\n');
+
+    const input = {
+      tool_name: 'Agent',
+      tool_input: {
+        subagent_type: 'Explore',
+        // Query "ApiRoutes" substring-matches the class name
+        prompt: 'ApiRoutes',
         model: 'haiku',
-        description: 'search for routes',
+        description: 'search for API routes',
         run_in_background: false,
+        custom_field: 'custom_value',
       },
       cwd: tmpDir,
     };
@@ -184,18 +448,24 @@ describe('df-explore-protocol hook', () => {
     assert.equal(code, 0);
 
     const updated = JSON.parse(stdout).hookSpecificOutput.updatedInput;
+    assert.equal(updated.subagent_type, 'Explore');
     assert.equal(updated.model, 'haiku');
-    assert.equal(updated.description, 'search for routes');
+    assert.equal(updated.description, 'search for API routes');
     assert.equal(updated.run_in_background, false);
-    assert.equal(updated.subagent_type, 'Explore');
+    assert.equal(updated.custom_field, 'custom_value');
+    // Prompt is modified (has injection) but still contains original text
+    assert.ok(updated.prompt.includes('ApiRoutes'));
   });
 
-  test('does not double-inject if protocol already present', () => {
+  test('AC-12: all original tool_input fields preserved after Phase 1 fallback', () => {
+    // No matching files → fallback path
     const input = {
       tool_name: 'Agent',
       tool_input: {
         subagent_type: 'Explore',
-        prompt: 'Find: config\n\n---\n## Search Protocol (auto-injected — MUST follow)\n\nalready here',
+        prompt: 'Find: something',
+        model: 'sonnet',
+        extra: 'value',
       },
       cwd: tmpDir,
     };
@@ -204,18 +474,127 @@ describe('df-explore-protocol hook', () => {
     assert.equal(code, 0);
 
     const updated = JSON.parse(stdout).hookSpecificOutput.updatedInput;
-    const matches = updated.prompt.match(/Search Protocol \(auto-injected/g);
-    // Currently will double-inject — documenting current behavior
-    // If this becomes a problem, add dedup logic
-    assert.ok(matches.length >= 1);
+    assert.equal(updated.model, 'sonnet');
+    assert.equal(updated.extra, 'value');
+    assert.equal(updated.subagent_type, 'Explore');
   });
 
-  test('handles missing prompt gracefully', () => {
+  // -------------------------------------------------------------------------
+  // Existing behavior: non-Explore/non-Agent pass-through
+  // -------------------------------------------------------------------------
+  test('ignores non-Agent tool calls', () => {
+    const input = {
+      tool_name: 'Read',
+      tool_input: { file_path: '/some/file.ts' },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+    assert.equal(stdout, '');
+  });
+
+  test('ignores non-Explore agent calls', () => {
     const input = {
       tool_name: 'Agent',
-      tool_input: {
-        subagent_type: 'Explore',
-      },
+      tool_input: { subagent_type: 'reasoner', prompt: 'Analyze this code' },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+    assert.equal(stdout, '');
+  });
+
+  test('handles case-insensitive subagent_type (EXPLORE)', () => {
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'EXPLORE', prompt: 'Find: test utilities' },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+
+    const result = JSON.parse(stdout);
+    assert.ok(result.hookSpecificOutput.updatedInput.prompt.includes('Search Protocol'));
+  });
+
+  // -------------------------------------------------------------------------
+  // AC-15: Phase 1 filters symbols by substring match on symbol name OR file path
+  // -------------------------------------------------------------------------
+  test('AC-15: Phase 1 includes symbols matching query in name or filepath', () => {
+    // File path contains "database" — all functions in it should be included
+    writeFixtureFile(tmpDir, 'database.ts', 'export function connect() {}\nexport function close() {}\n');
+    // File name does not match, but symbol name "databaseHelper" contains "database"
+    writeFixtureFile(tmpDir, 'utils.ts', 'export function databaseHelper() {}\nexport function unrelated() {}\n');
+
+    // Query "database" matches filepath of database.ts and symbol name databaseHelper
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore', prompt: 'database' },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+
+    const prompt = JSON.parse(stdout).hookSpecificOutput.updatedInput.prompt;
+    assert.ok(prompt.includes('[LSP Phase -- locations found]'), 'Should have LSP block');
+    // databaseHelper matches by symbol name substring
+    assert.ok(prompt.includes('databaseHelper'), 'Symbol matching query by name should be included');
+    // connect/close match because their file path includes "database"
+    assert.ok(prompt.includes('connect'), 'Symbol in matching filepath should be included');
+    // unrelated in utils.ts should not be included (path has "utils", not "database"; name "unrelated" doesn't match)
+    assert.ok(!prompt.includes('unrelated'), 'Unrelated symbol in non-matching file excluded');
+  });
+
+  // -------------------------------------------------------------------------
+  // Phase 1 no matching symbols → static fallback
+  // -------------------------------------------------------------------------
+  test('Phase 1 no matching symbols falls back to static template injection', () => {
+    // Write a file with a symbol that does NOT match the query
+    writeFixtureFile(tmpDir, 'unrelated.js', 'function completelyDifferent() {}\n');
+
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore', prompt: 'Find: nothing here' },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+
+    const prompt = JSON.parse(stdout).hookSpecificOutput.updatedInput.prompt;
+    assert.ok(prompt.includes('Search Protocol (auto-injected'), 'Should inject static protocol');
+    assert.ok(!prompt.includes('[LSP Phase -- locations found]'), 'No LSP block for empty results');
+  });
+
+  // -------------------------------------------------------------------------
+  // permissionDecision is always 'allow'
+  // -------------------------------------------------------------------------
+  test('hookSpecificOutput has permissionDecision allow', () => {
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore', prompt: 'Find: something' },
+      cwd: tmpDir,
+    };
+
+    const { stdout, code } = runHook(input);
+    assert.equal(code, 0);
+
+    const out = JSON.parse(stdout).hookSpecificOutput;
+    assert.equal(out.permissionDecision, 'allow');
+    assert.equal(out.hookEventName, 'PreToolUse');
+  });
+
+  // -------------------------------------------------------------------------
+  // Missing prompt field — should inject into empty string base
+  // -------------------------------------------------------------------------
+  test('handles missing prompt field gracefully', () => {
+    const input = {
+      tool_name: 'Agent',
+      tool_input: { subagent_type: 'Explore' },
       cwd: tmpDir,
     };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.108",
+  "version": "0.1.109",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",
@@ -42,5 +42,8 @@
   },
   "dependencies": {
     "playwright": "^1.58.2"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2"
   }
 }

package/src/commands/df/execute.md

@@ -167,7 +167,7 @@ The script handles all health checks internally and outputs structured JSON:
 **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. TaskUpdate(status: "completed"), update PLAN.md [x] + commit hash. **Extract decisions** (see §5.5.1).
+- **Exit 0 (PASS):** Commit stands. **AC coverage check** (see §5.5.1). TaskUpdate(status: "completed"), update PLAN.md [x] + commit hash. **Extract decisions** (see §5.5.2).
 - **Exit 1 (FAIL):** Script already reverted. Set `TaskUpdate(status: "pending")`. Recompute remaining waves:
   ```
   WAVE_JSON=!`node "${HOME}/.claude/bin/wave-runner.js" --json --plan PLAN.md --recalc --failed T{N} 2>/dev/null || echo 'WAVE_ERROR'`
@@ -176,7 +176,21 @@ The script handles all health checks internally and outputs structured JSON:
   Report: `"✗ T{n}: reverted"`.
 - **Exit 2 (SALVAGEABLE):** Spawn `Agent(model="sonnet")` to fix lint/typecheck issues. Re-run `node "${HOME}/.claude/bin/ratchet.js"`. If still non-zero → revert both commits, set status pending.
 
-#### 5.5.1. DECISION EXTRACTION (on ratchet pass)
+#### 5.5.1. AC COVERAGE CHECK (after ratchet pass)
+
+After ratchet PASS (exit 0), run AC coverage check to verify agent reported all acceptance criteria:
+```bash
+node "${HOME}/.claude/bin/hooks/ac-coverage.js" --spec {spec_path} --output-file {agent_output_file} --status pass
+```
+
+where `{spec_path}` is the path to `specs/doing-{spec_name}.md` and `{agent_output_file}` is the task agent's full output transcript (from TaskOutput or notification context).
+
+**Exit codes from ac-coverage.js:**
+- **Exit 0:** All ACs covered or no ACs in spec. Status remains PASS. Proceed to decision extraction (§5.5.2).
+- **Exit 2 (SALVAGEABLE):** Missed ACs detected despite agent reporting TASK_STATUS:pass. Script outputs summary: `[ac-coverage] N/M ACs covered — missed: AC-X, AC-Y; ...`. Override final status to SALVAGEABLE. Commit stands. TaskUpdate(status: "completed") with note that ACs are incomplete.
+- **Exit 1 (script error):** Log error, do not change status. Proceed as if ratchet PASS (exit 0 from ac-coverage).
+
+#### 5.5.2. DECISION EXTRACTION (on ratchet pass)
 
 Parse the agent's response for `DECISIONS:` line. If present:
 1. Split by ` | ` to get individual decisions
@@ -324,6 +338,25 @@ TASK_DETAIL=!`cat .deepflow/plans/doing-{task_id}.md 2>/dev/null || echo 'NOT_FO
 ```
 If `TASK_DETAIL` is not `NOT_FOUND`, use it as the full Middle section (Steps, ACs, Impact) in the agent prompt, overriding the inline PLAN.md block. If `NOT_FOUND`, fall back to the inline PLAN.md task block.
 
+**Pre-prompt type context extraction (before building agent prompt):**
+
+Run LSP `documentSymbol` on the task's `files` list to collect existing type definitions. This runs BEFORE prompt construction so the result can be injected as `EXISTING_TYPES`.
+
+<!-- AC-7: No new tool calls or latency added when context sources are empty -->
+**Early exit (AC-7):** If the task's `Files:` list is empty, skip all `documentSymbol` calls entirely. Set `EXISTING_TYPES` to empty string immediately and proceed to prompt construction.
+
+Steps (only when `Files:` list is non-empty):
+1. Cap the file list at 10 files (take the first 10 from the task's `Files:` list).
+2. For each file (up to the cap), call `documentSymbol` via LSP.
+3. Filter results: keep only symbols with kind ∈ {Class, Interface, Enum, TypeAlias} (LSP SymbolKind values 5, 11, 10, 26 respectively).
+4. For each matching symbol, extract the source range (`range.start.line` to `range.end.line`) — read those lines from the file.
+5. Accumulate extracted lines with a **120-line total budget** — stop adding symbols once the budget is reached.
+6. Join all extracted ranges into a single string: `EXISTING_TYPES`.
+
+**AC-8 — graceful no-op:** If no matching symbols are found across all processed files (either `documentSymbol` returns nothing or no Class/Interface/Enum/TypeAlias symbols exist), set `EXISTING_TYPES` to empty string. No context block is added to the prompt.
+
+<!-- AC-6: Backward-compatible no-op — when neither Domain Model section exists in the spec nor Existing Types extraction yields content (EXISTING_TYPES is empty string), the Standard Task prompt contains no extra context blocks and is identical to the pre-injection baseline. Zero prompt overhead, zero tool calls for tasks that lack these context sources. -->
+
 **Standard Task** (`Agent(model="{Model}", ...)`):
 ```
 --- START ---
@@ -337,6 +370,16 @@ spike_results:
   insight: {insight from probe_learnings}
 }
 Success criteria: {ACs from spec relevant to this task}
+{If spec contains ## Domain Model section:
+--- CONTEXT: Domain Model ---
+{Domain Model section content from doing-*.md, extracted via shell injection:
+  DOMAIN_MODEL=!`sed -n '/^## Domain Model$/,/^## [^D]/p' specs/doing-{spec_name}.md | head -n -1 2>/dev/null || echo 'NOT_FOUND'`
+}
+}
+{If EXISTING_TYPES is non-empty:
+--- CONTEXT: Existing Types ---
+{EXISTING_TYPES}
+}
 --- MIDDLE (omit for low effort; omit deps for medium) ---
 {TASK_DETAIL if available, else inline block:}
 Impact: Callers: {file} ({why}) | Duplicates: [active→consolidate] [dead→DELETE] | Data flow: {consumers}
@@ -344,6 +387,14 @@ Prior tasks: {dep_id}: {summary}
 Steps: 1. chub search/get for APIs 2. LSP findReferences, add unlisted callers 3. LSP documentSymbol on Impact files → Read with offset/limit on relevant ranges only (never read full files) 4. Implement 5. Commit
 --- END ---
 Duplicates: [active]→consolidate [dead]→DELETE. ONLY job: code+commit. No merge/rename/checkout.
+**Acceptance Criteria Coverage:** If the spec has acceptance criteria (AC-N), emit this block:
+```
+AC_COVERAGE:
+AC-1:done
+AC-2:skip:reason here (if applicable)
+AC_COVERAGE_END
+```
+Format: one line per AC with either `AC-N:done` or `AC-N:skip:reason`. Omit this block if the spec has no acceptance criteria.
 DECISIONS: If you made non-obvious choices, append to the LAST LINE BEFORE TASK_STATUS:
 DECISIONS: [TAG] {decision} — {rationale} | [TAG] {decision2} — {rationale2}
 Tags:
@@ -373,6 +424,14 @@ RULES:
 - Do NOT create new variables or intermediate adapters to paper over mismatches. Fix the actual call site.
 - Do NOT modify acceptance criteria or spec definitions.
 - Commit as fix({spec}): {contract description}. One commit per contract fix.
+**Acceptance Criteria Coverage:** If the spec has acceptance criteria (AC-N), emit this block:
+```
+AC_COVERAGE:
+AC-1:done
+AC-2:skip:reason here (if applicable)
+AC_COVERAGE_END
+```
+Format: one line per AC with either `AC-N:done` or `AC-N:skip:reason`. Omit this block if the spec has no acceptance criteria.
 DECISIONS: Report each contract fix as: [TAG] {what was mismatched} — {which side changed and why}. Use [APPROACH] for definitive fixes, [PROVISIONAL] if the fix is a workaround, [UPDATE] if changing a prior decision.
 Last line: TASK_STATUS:pass or TASK_STATUS:fail
 ```

package/src/commands/df/verify.md

@@ -86,7 +86,7 @@ Nothing found → `⚠ No build/test commands detected. L0/L4 skipped. Set quali
 
 No tool → pass with warning. When available: stash changes → run coverage on baseline → stash pop → run coverage on current → compare. Drop → FAIL. Same/improved → pass.
 
-**L3: Integration** — Subsumed by L0 + L4. No separate check.
+**L3: AC coverage verification** — Verify that agent-reported acceptance criteria coverage matches the spec's acceptance criteria section. Parse spec file for `## Acceptance Criteria` section, extract all ACs. For each AC, verify that agent execution explicitly claimed coverage (via agent output or PLAN.md task completion notes). Missing or uncovered ACs → FAIL with list of uncovered ACs. All ACs claimed → pass.
 
 **L4: Tests** — Run AFTER L0 passes. Run even if L1-L2 had issues. Exit 0 → pass. Non-zero → FAIL with last 50 lines + fix task. If `quality.test_retry_on_fail: true`: re-run once; second pass → warn (flaky); second fail → genuine failure.
 

package/templates/config-template.yaml

@@ -38,6 +38,7 @@ models:
 
 explore:
   max_tokens: 500      # Controls Explore agent response length
+  explore_lsp_timeout_ms: 15000  # Timeout (ms) for the Phase 1 LSP subprocess; on timeout the static template is injected as fallback
 
 commits:
   format: "feat({spec}): {description}"