deepflow 0.1.110 → 0.1.112

package/hooks/ac-coverage.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
+// @hook-event: PostToolUse
+// @hook-owner: deepflow
 /**
  * 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>
+ *   node ac-coverage.js --spec <path> --test-files <file1,file2,...> --status <pass|fail|revert>
+ *   node ac-coverage.js --spec <path> --snapshot <path> --status <pass|fail|revert>
  *
  * Exit codes:
  *   0 — all ACs covered, no ACs in spec, or input status was fail/revert
@@ -16,6 +18,7 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
 
 // ── Argument parsing ────────────────────────────────────────────────────────
 
@@ -24,8 +27,8 @@ function parseArgs(argv) {
   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 === '--test-files' && argv[i + 1]) { args.testFiles = argv[++i]; }
+    else if (a === '--snapshot' && argv[i + 1]) { args.snapshot = argv[++i]; }
     else if (a === '--status' && argv[i + 1]) { args.status = argv[++i]; }
   }
   return args;
@@ -82,28 +85,55 @@ function extractSpecACs(specContent) {
   });
 }
 
-// ── AC parsing from agent output ────────────────────────────────────────────
+// ── AC scanning from test files ─────────────────────────────────────────────
 
 /**
- * Parse AC_COVERAGE block from agent output.
- * Returns a Map of AC-N → { status: 'done'|'skip', reason: string|null }
+ * Scan test files for AC references in test names.
+ * Matches patterns like: it('AC-1: ...'), test('AC-2 ...'), describe('AC-3 ...')
+ * Returns a Set of AC-N identifiers found across all test files.
  */
-function parseACCoverage(outputText) {
-  const map = new Map();
+function scanTestFilesForACs(testFilePaths) {
+  const found = new Set();
+  const pattern = /\b(it|test|describe)\s*\(\s*['"`][^'"`]*\bAC-(\d+)\b/g;
 
-  const blockMatch = outputText.match(/AC_COVERAGE:([\s\S]*?)AC_COVERAGE_END/);
-  if (!blockMatch) return map;
+  for (const filePath of testFilePaths) {
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (e) {
+      // Skip unreadable files — not a fatal error
+      continue;
+    }
 
-  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,
-    });
+    pattern.lastIndex = 0;
+    let m;
+    while ((m = pattern.exec(content)) !== null) {
+      found.add(`AC-${m[2]}`);
+    }
   }
-  return map;
+
+  return found;
+}
+
+/**
+ * Resolve test file paths from --test-files (comma-separated list) or
+ * --snapshot (newline-separated list of paths from snapshot file).
+ */
+function resolveTestFiles(args) {
+  if (args.testFiles) {
+    return args.testFiles.split(',').map(f => f.trim()).filter(Boolean);
+  }
+  if (args.snapshot) {
+    let content;
+    try {
+      content = fs.readFileSync(args.snapshot, 'utf8');
+    } catch (e) {
+      console.error(`[ac-coverage] Error reading snapshot file: ${e.message}`);
+      process.exit(1);
+    }
+    return content.split('\n').map(f => f.trim()).filter(Boolean);
+  }
+  return [];
 }
 
 // ── Main logic ──────────────────────────────────────────────────────────────
@@ -127,77 +157,53 @@ function run(args) {
     process.exit(1);
   }
 
-  // Extract canonical ACs (AC-2, AC-7, AC-8)
+  // Extract canonical ACs from spec
   const specACs = extractSpecACs(specContent);
 
-  // AC-7: no Acceptance Criteria section → silent exit
+  // No Acceptance Criteria section → silent exit
   if (specACs === null) {
     process.exit(0);
   }
 
-  // AC-8: section exists but no AC-\d+ patterns → silent exit
+  // 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;
-  }
+  // Resolve test files to scan
+  const testFilePaths = resolveTestFiles(args);
 
-  // AC-3: parse AC_COVERAGE block from agent output
-  const reported = parseACCoverage(outputText);
+  // Scan test files for AC references
+  const coveredACs = scanTestFilesForACs(testFilePaths);
 
-  // AC-3: diff — identify missed ACs (not reported as done)
+  // Diff — identify missed ACs (not referenced in any test name)
   const missed = [];
-  const skipped = [];
   let coveredCount = 0;
 
   for (const id of specACs) {
-    const entry = reported.get(id);
-    if (entry && entry.status === 'done') {
+    if (coveredACs.has(id)) {
       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}`);
+  // Summary line
+  const summaryDetail = missed.length > 0 ? ` — missed: ${missed.join(', ')}` : '';
+  console.log(`[ac-coverage] ${coveredCount}/${totalACs} ACs covered${summaryDetail}`);
 
-  // AC-4 / AC-5: status override
+  // Status override
   const inputStatus = args.status;
   const hasMissed = missed.length > 0;
 
   if (hasMissed && inputStatus === 'pass') {
-    // AC-4: override to SALVAGEABLE
+    // Override to SALVAGEABLE
     console.log('OVERRIDE:SALVAGEABLE');
     process.exit(2);
   } else {
-    // AC-5: all done, or status was already fail/revert — no override
+    // All done, or status was already fail/revert — no override
     console.log('OVERRIDE:none');
     process.exit(0);
   }
@@ -210,4 +216,4 @@ if (require.main === module) {
   run(args);
 }
 
-module.exports = { extractSpecACs, parseACCoverage, extractACSection };
+module.exports = { extractSpecACs, extractACSection, scanTestFilesForACs, resolveTestFiles };

package/hooks/df-check-update.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: SessionStart
+// @hook-owner: deepflow
 /**
  * deepflow update checker
  * Runs in background, checks npm for newer versions

package/hooks/df-command-usage.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: PreToolUse, PostToolUse, SessionEnd
+// @hook-owner: dashboard
 /**
  * deepflow command usage tracker
  * Tracks df:* command invocations with token deltas and tool call counts.

package/hooks/df-dashboard-push.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: SessionEnd
+// @hook-owner: dashboard
 /**
  * deepflow dashboard push — SessionEnd hook
  * Collects session summary (tokens, duration, tool calls, model), gets

package/hooks/df-execution-history.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: PostToolUse
+// @hook-owner: dashboard
 /**
  * deepflow execution history recorder
  * PostToolUse hook: fires when the Agent tool completes.

package/hooks/df-explore-protocol.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: PreToolUse
+// @hook-owner: deepflow
 /**
  * deepflow explore protocol injector
  * PreToolUse hook: fires before the Agent tool executes.
@@ -244,27 +245,6 @@ readStdinIfMain(module, (payload) => {
       },
     };
 
-    // --- 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));
   } catch (_) {
     // AC-10: catch ALL errors — malformed JSON, missing tool_input, filesystem errors, etc.

package/hooks/df-harness-score.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+// @hook-event: PostToolUse
+// @hook-owner: deepflow
+/**
+ * deepflow harness quality scorer (REQ-6).
+ *
+ * Aggregates 4 deterministic signals about test harness health and emits a
+ * SALVAGEABLE signal when the combined score falls below the configured
+ * threshold (`harness_min_score`, default 0.6).
+ *
+ * Score = (D1 + D2 + D3 + D4) / 4, each dimension ∈ [0, 1]:
+ *   D1  AC test ratio          (AC-referenced tests) / (total ACs in spec)
+ *   D2  Diff sibling ratio     (test files in diff) / (impl files in diff)
+ *   D3  Complexity proxy       1 - min(1, branch_kw_in_±20 / 10)
+ *   D4  JSDoc ratio            (functions with JSDoc) / (total changed fns)
+ *
+ * Hook trigger: PostToolUse, tool_name "Bash", command contains "git commit".
+ *
+ * Exit codes:
+ *   0 — score >= threshold, or insufficient signal, or non-commit event
+ *   2 — SALVAGEABLE: score < threshold (written to stderr)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { readStdinIfMain } = require('./lib/hook-stdin');
+const { scanTestFilesForACs, extractSpecACs } = require('./ac-coverage');
+const {
+  queryLsp,
+  detectLanguageServer,
+  isBinaryAvailable,
+} = require('./df-invariant-check');
+
+const DEFAULT_MIN_SCORE = 0.6;
+const COMPLEXITY_THRESHOLD = 10;
+const CONTEXT_LINES = 20;
+const JSDOC_LOOKBACK_LINES = 3;
+
+const BRANCH_KEYWORDS = [
+  'if', 'else', 'switch', 'case', 'for', 'while', 'do',
+  'try', 'catch', 'finally', 'throw', '&&', '||', '??', '?',
+];
+
+const TEST_FILE_RE = /(^|\/)(__tests__\/|test\/|tests\/|spec\/)|\.(test|spec)\.(js|jsx|ts|tsx|mjs|cjs|py|go|rs)$/i;
+const IMPL_EXT_RE = /\.(js|jsx|ts|tsx|mjs|cjs|py|go|rs|java|rb)$/i;
+
+// ── Config loading ───────────────────────────────────────────────────────────
+
+/**
+ * Read harness_min_score from .deepflow/config.yaml. Returns DEFAULT_MIN_SCORE
+ * on any failure (missing file, malformed YAML, missing key).
+ */
+function readMinScore(cwd) {
+  const configPath = path.join(cwd, '.deepflow', 'config.yaml');
+  let content;
+  try {
+    content = fs.readFileSync(configPath, 'utf8');
+  } catch (_) {
+    return DEFAULT_MIN_SCORE;
+  }
+  // Minimal YAML scan — avoid a YAML dep. Look for "harness_min_score: <num>"
+  const m = content.match(/^\s*harness_min_score\s*:\s*([0-9]*\.?[0-9]+)\s*(#.*)?$/m);
+  if (!m) return DEFAULT_MIN_SCORE;
+  const v = parseFloat(m[1]);
+  if (Number.isNaN(v) || v < 0 || v > 1) return DEFAULT_MIN_SCORE;
+  return v;
+}
+
+// ── Active spec loader (mirrors df-invariant-check.js) ───────────────────────
+
+function loadActiveSpec(cwd) {
+  const candidates = [
+    path.join(cwd, '.deepflow'),
+    path.join(cwd, 'specs'),
+  ];
+  for (const dir of candidates) {
+    try {
+      const entries = fs.readdirSync(dir);
+      const doing = entries.find((e) => e.startsWith('doing-') && e.endsWith('.md'));
+      if (doing) {
+        const p = path.join(dir, doing);
+        try { return { path: p, content: fs.readFileSync(p, 'utf8') }; } catch (_) { /* ignore */ }
+      }
+    } catch (_) {
+      // dir missing — continue
+    }
+  }
+  return null;
+}
+
+// ── Diff helpers ─────────────────────────────────────────────────────────────
+
+function getChangedFiles(cwd) {
+  try {
+    const out = execFileSync('git', ['diff', '--name-only', 'HEAD~1', 'HEAD'], {
+      encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+function getFullDiff(cwd) {
+  try {
+    return execFileSync('git', ['diff', 'HEAD~1', 'HEAD'], {
+      encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (_) {
+    return '';
+  }
+}
+
+function isTestFile(p) {
+  return TEST_FILE_RE.test(p);
+}
+
+function isImplFile(p) {
+  return IMPL_EXT_RE.test(p) && !isTestFile(p);
+}
+
+// ── D1: AC test ratio ────────────────────────────────────────────────────────
+
+function dimensionAcTestRatio(specContent, testFilePaths) {
+  const specACs = extractSpecACs(specContent);
+  if (!specACs || specACs.length === 0) return { score: null, reason: 'no-acs' };
+
+  const covered = scanTestFilesForACs(testFilePaths);
+  let hits = 0;
+  for (const id of specACs) if (covered.has(id)) hits++;
+  return { score: hits / specACs.length, total: specACs.length, covered: hits };
+}
+
+// ── D2: diff sibling test ratio ─────────────────────────────────────────────
+
+function dimensionDiffSibling(changedFiles) {
+  const impl = changedFiles.filter(isImplFile);
+  const tests = changedFiles.filter(isTestFile);
+  if (impl.length === 0) return { score: null, reason: 'no-impl-files' };
+  // Ratio is clamped to [0, 1] — adding more test files than impl files still
+  // caps at a perfect score rather than over-inflating.
+  const raw = tests.length / impl.length;
+  return { score: Math.max(0, Math.min(1, raw)), impl: impl.length, tests: tests.length };
+}
+
+// ── D3: complexity proxy ────────────────────────────────────────────────────
+
+/**
+ * Count occurrences of branch keywords within ±CONTEXT_LINES around every
+ * changed hunk across the unified diff. Higher count = more complex change.
+ * Returns { score, branches } where score = 1 - min(1, branches / threshold).
+ */
+function dimensionComplexity(diffText) {
+  if (!diffText) return { score: null, reason: 'no-diff' };
+
+  // Build a regex that matches any branch keyword. Word-boundary for alphas,
+  // literal for symbolic operators.
+  const wordKw = BRANCH_KEYWORDS.filter((k) => /^[a-z]+$/i.test(k));
+  const symKw = BRANCH_KEYWORDS.filter((k) => !/^[a-z]+$/i.test(k));
+  const wordRe = new RegExp(`\\b(?:${wordKw.join('|')})\\b`, 'g');
+  const symParts = symKw.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  const symRe = symParts.length ? new RegExp(symParts.join('|'), 'g') : null;
+
+  // Walk file-by-file, track hunk line windows in the post-image (b/ side).
+  // For each hunk header "@@ -x,y +a,b @@" we mark [a - CTX, a + b + CTX] as
+  // the window of interest. We then count keyword occurrences on content
+  // lines (starting with " ", "+", or "-") whose b-side line number falls in
+  // any window. For simplicity we count keywords across the WHOLE hunk body
+  // (hunks are already the "±20 lines" surrounding a change), effectively
+  // implementing the ±20 context heuristic without tracking per-line numbers.
+  let branches = 0;
+  const lines = diffText.split('\n');
+  let inHunk = false;
+
+  for (const line of lines) {
+    if (line.startsWith('@@')) { inHunk = true; continue; }
+    if (line.startsWith('diff --git') || line.startsWith('+++ ') || line.startsWith('--- ')
+        || line.startsWith('index ') || line.startsWith('new file')
+        || line.startsWith('deleted file') || line.startsWith('similarity index')
+        || line.startsWith('rename ')) {
+      inHunk = false;
+      continue;
+    }
+    if (!inHunk) continue;
+    // Count within context + added + removed lines
+    if (!(line.startsWith(' ') || line.startsWith('+') || line.startsWith('-'))) continue;
+    const body = line.slice(1);
+    const wm = body.match(wordRe);
+    if (wm) branches += wm.length;
+    if (symRe) {
+      const sm = body.match(symRe);
+      if (sm) branches += sm.length;
+    }
+  }
+
+  const score = 1 - Math.min(1, branches / COMPLEXITY_THRESHOLD);
+  return { score, branches };
+}
+
+// ── D4: JSDoc ratio via queryLsp + lookback ─────────────────────────────────
+
+const FUNCTION_KINDS = new Set([
+  12, // Function
+  6,  // Method
+  9,  // Constructor
+]);
+
+function flattenSymbols(symbols, out = []) {
+  for (const s of symbols || []) {
+    out.push(s);
+    if (Array.isArray(s.children) && s.children.length) flattenSymbols(s.children, out);
+  }
+  return out;
+}
+
+function symbolStartLine(sym) {
+  // DocumentSymbol has .range; SymbolInformation has .location.range.
+  const range = sym.range || (sym.location && sym.location.range);
+  if (!range || !range.start) return null;
+  return range.start.line; // 0-based
+}
+
+function hasJsDocAbove(fileLines, startLine) {
+  const start = Math.max(0, startLine - JSDOC_LOOKBACK_LINES);
+  const slice = fileLines.slice(start, startLine).map((l) => l.trim());
+  // Accept any JSDoc-style comment: */ on a preceding line, or /** on one of
+  // the lookback lines, or leading // comments for non-JS languages.
+  for (const line of slice) {
+    if (line.startsWith('/**') || line.startsWith('*/') || line.startsWith('*')
+        || line.startsWith('///') || line.startsWith('# ') || line.startsWith('"""')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function dimensionJsDocRatio(cwd, changedFiles) {
+  const implFiles = changedFiles.filter(isImplFile);
+  if (implFiles.length === 0) return { score: null, reason: 'no-impl-files' };
+
+  const detected = detectLanguageServer(cwd, implFiles);
+  if (!detected || !isBinaryAvailable(detected.binary)) {
+    return { score: null, reason: 'lsp_unavailable' };
+  }
+
+  let totalFns = 0;
+  let documented = 0;
+
+  for (const rel of implFiles) {
+    const abs = path.isAbsolute(rel) ? rel : path.join(cwd, rel);
+    let source;
+    try { source = fs.readFileSync(abs, 'utf8'); } catch (_) { continue; }
+    const fileLines = source.split('\n');
+
+    const uri = 'file://' + abs;
+    let resp;
+    try {
+      resp = await queryLsp(detected.binary, cwd, uri, 'textDocument/documentSymbol', {
+        textDocument: { uri },
+      });
+    } catch (_) {
+      continue;
+    }
+    if (!resp || !resp.ok) continue;
+
+    const symbols = flattenSymbols(Array.isArray(resp.result) ? resp.result : []);
+    for (const sym of symbols) {
+      if (!FUNCTION_KINDS.has(sym.kind)) continue;
+      const startLine = symbolStartLine(sym);
+      if (startLine == null) continue;
+      totalFns++;
+      if (hasJsDocAbove(fileLines, startLine)) documented++;
+    }
+  }
+
+  if (totalFns === 0) return { score: null, reason: 'no-functions' };
+  return { score: documented / totalFns, total: totalFns, documented };
+}
+
+// ── Aggregation ──────────────────────────────────────────────────────────────
+
+/**
+ * Main scoring function.
+ * @param {object} opts
+ * @param {string} opts.cwd          project root
+ * @param {string} opts.specContent  active spec markdown
+ * @param {string} opts.diff         unified diff against HEAD~1
+ * @param {string[]} opts.changedFiles  changed file paths (relative)
+ * @param {string[]} [opts.testFilePaths]  test files to scan for AC refs
+ *   (defaults to all test files under cwd discovered from changedFiles +
+ *   existing on disk — callers may override for determinism).
+ * @returns {Promise<{ score: number|null, dimensions: object }>}
+ */
+async function scoreHarness(opts) {
+  const { cwd, specContent, diff, changedFiles } = opts;
+
+  // D1 — scan ALL test files in the repo for broad AC coverage, not just diff.
+  const testFilePaths = opts.testFilePaths
+    || changedFiles.filter(isTestFile).map((f) => path.isAbsolute(f) ? f : path.join(cwd, f));
+
+  const d1 = dimensionAcTestRatio(specContent, testFilePaths);
+  const d2 = dimensionDiffSibling(changedFiles);
+  const d3 = dimensionComplexity(diff);
+  const d4 = await dimensionJsDocRatio(cwd, changedFiles);
+
+  const dims = [d1, d2, d3, d4];
+  const scored = dims.filter((d) => d && typeof d.score === 'number');
+  if (scored.length === 0) {
+    return { score: null, dimensions: { d1, d2, d3, d4 }, reason: 'no-signal' };
+  }
+
+  // Equal-weight average over the 4 dimensions. Dimensions with null score
+  // (insufficient signal) are treated as 1.0 (neutral) to avoid penalising
+  // a change for something that cannot be measured deterministically.
+  const vals = dims.map((d) => (d && typeof d.score === 'number' ? d.score : 1));
+  const score = vals.reduce((a, b) => a + b, 0) / vals.length;
+
+  return { score, dimensions: { d1, d2, d3, d4 } };
+}
+
+// ── Hook entry ───────────────────────────────────────────────────────────────
+
+function isGitCommitBash(toolName, toolInput) {
+  if (toolName !== 'Bash') return false;
+  const cmd = (toolInput && (toolInput.command || toolInput.cmd || '')) || '';
+  return /git\s+commit\b/.test(cmd);
+}
+
+async function runHook(data) {
+  const toolName = data.tool_name || '';
+  const toolInput = data.tool_input || {};
+  if (!isGitCommitBash(toolName, toolInput)) return;
+
+  const cwd = data.cwd || process.cwd();
+
+  const diff = getFullDiff(cwd);
+  const changedFiles = getChangedFiles(cwd);
+  if (!diff || changedFiles.length === 0) return;
+
+  const spec = loadActiveSpec(cwd);
+  if (!spec) return; // no active spec — nothing to score against
+
+  const minScore = readMinScore(cwd);
+  const { score, dimensions, reason } = await scoreHarness({
+    cwd, specContent: spec.content, diff, changedFiles,
+  });
+
+  if (score == null) {
+    // No signal — silent pass
+    return;
+  }
+
+  const pct = (n) => (n == null ? 'n/a' : n.toFixed(2));
+  const summary = `[df-harness-score] score=${score.toFixed(2)} (min=${minScore.toFixed(2)}) `
+    + `D1=${pct(dimensions.d1.score)} D2=${pct(dimensions.d2.score)} `
+    + `D3=${pct(dimensions.d3.score)} D4=${pct(dimensions.d4.score)}`;
+
+  if (score < minScore) {
+    console.error(summary);
+    console.error('[df-harness-score] OVERRIDE:SALVAGEABLE — harness quality below threshold');
+    process.exit(2);
+  } else {
+    console.log(summary);
+  }
+}
+
+// ── Wire up stdin entry ──────────────────────────────────────────────────────
+
+readStdinIfMain(module, (data) => {
+  // runHook is async — fire and let the process exit naturally on resolution.
+  // We avoid awaiting inside readStdinIfMain's sync callback.
+  runHook(data).catch(() => { /* never break Claude Code on hook errors */ });
+});
+
+module.exports = {
+  scoreHarness,
+  dimensionAcTestRatio,
+  dimensionDiffSibling,
+  dimensionComplexity,
+  dimensionJsDocRatio,
+  readMinScore,
+  isGitCommitBash,
+  isTestFile,
+  isImplFile,
+};