deepflow 0.1.107 → 0.1.109

package/bin/worktree-deps.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * deepflow worktree-deps
+ * Symlinks node_modules from the main repo into a worktree so that
+ * TypeScript / LSP / builds resolve dependencies without a full install.
+ *
+ * Usage: node bin/worktree-deps.js --source /path/to/repo --worktree /path/to/worktree
+ *
+ * Walks the source repo looking for node_modules directories (max depth 2)
+ * and creates corresponding symlinks in the worktree.
+ *
+ * Exit codes: 0=OK, 1=ERROR
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--source' && args[i + 1]) opts.source = args[++i];
+    else if (args[i] === '--worktree' && args[i + 1]) opts.worktree = args[++i];
+  }
+  if (!opts.source || !opts.worktree) {
+    console.error('Usage: node bin/worktree-deps.js --source <repo> --worktree <worktree>');
+    process.exit(1);
+  }
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Find node_modules directories (depth 0 and 1 level of nesting)
+// ---------------------------------------------------------------------------
+
+function findNodeModules(root) {
+  const results = [];
+
+  // Root node_modules
+  const rootNM = path.join(root, 'node_modules');
+  if (fs.existsSync(rootNM)) {
+    results.push('node_modules');
+  }
+
+  // Scan common monorepo directory patterns for nested node_modules
+  const monorepoPatterns = ['packages', 'apps', 'libs', 'services', 'modules', 'plugins'];
+
+  for (const dir of monorepoPatterns) {
+    const dirPath = path.join(root, dir);
+    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dirPath);
+    } catch (_) {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(dirPath, entry);
+      if (!fs.statSync(entryPath).isDirectory()) continue;
+
+      const nm = path.join(entryPath, 'node_modules');
+      if (fs.existsSync(nm)) {
+        results.push(path.join(dir, entry, 'node_modules'));
+      }
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Create symlinks
+// ---------------------------------------------------------------------------
+
+function symlinkDeps(source, worktree) {
+  const nodeModulesPaths = findNodeModules(source);
+
+  if (nodeModulesPaths.length === 0) {
+    console.log('{"linked":0,"message":"no node_modules found in source"}');
+    return;
+  }
+
+  let linked = 0;
+  const errors = [];
+
+  for (const relPath of nodeModulesPaths) {
+    const srcAbs = path.join(source, relPath);
+    const dstAbs = path.join(worktree, relPath);
+
+    // Skip if already exists (symlink or directory)
+    if (fs.existsSync(dstAbs)) {
+      continue;
+    }
+
+    // Ensure parent directory exists in worktree
+    const parent = path.dirname(dstAbs);
+    if (!fs.existsSync(parent)) {
+      fs.mkdirSync(parent, { recursive: true });
+    }
+
+    try {
+      fs.symlinkSync(srcAbs, dstAbs, 'dir');
+      linked++;
+    } catch (err) {
+      errors.push({ path: relPath, error: err.message });
+    }
+  }
+
+  const result = { linked, total: nodeModulesPaths.length };
+  if (errors.length > 0) result.errors = errors;
+  console.log(JSON.stringify(result));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const opts = parseArgs();
+symlinkDeps(opts.source, opts.worktree);

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).
+  }
 });