kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/tools/failure-detector.js

@@ -0,0 +1,1132 @@
+#!/usr/bin/env node
+
+/**
+ * failure-detector.js — Guard Outcome Inference Engine (TASK_1163)
+ *
+ * Runs system-inferred detectors against task outcomes to determine whether
+ * an injected lesson guard succeeded or failed. Results drive hit_rate updates.
+ *
+ * 3-state result per detector:
+ *   - 'failure_detected'  : failure matching failure_signature occurred — guard failed to prevent it
+ *   - 'failure_avoided'   : guard topic was relevant and no failure detected — guard likely worked
+ *   - null (undetectable) : detector cannot determine outcome from available data
+ *
+ * Null detections are EXCLUDED from injection_count and hit_rate math.
+ *
+ * Shadow mode: first 10 injections per guard → log to guard_detector_shadow.jsonl
+ *   NO auto-expire during shadow. After 10 shadow runs, set guard.detector_mode=live.
+ * Live mode: auto-expire when injection_count>=5 AND hit_rate<0.3.
+ *
+ * Detector types (5):
+ *   1. git_commit_pattern         — git log --numstat delta + revert detection
+ *   2. acceptance_grep_miss       — acceptance_criteria presence check
+ *   3. merge_conflict             — task status=blocked + failure_reason=merge_conflict
+ *   4. regression_test_failure    — test verdict from post-complete result
+ *   5. surprise_file_in_scope     — ambient_signals.json surprise ∩ task scope_paths
+ *
+ * CLI:
+ *   node failure-detector.js run --task=TASK_XXX --guard=L-001 [--result-file=path]
+ *   node failure-detector.js run-all --task=TASK_XXX [--result-file=path]
+ *   node failure-detector.js shadow-log [--guard=L-001] [--limit=20]
+ *   node failure-detector.js expire-eligible [--dry-run]
+ *
+ * Used by: .formation/tools/attribution-report.js (called from post-complete)
+ */
+
+'use strict';
+
+const fs            = require('fs');
+const path          = require('path');
+const { execSync, execFileSync }  = require('child_process');
+// Shared project identity resolver (TASK_1701): CLI --project-path > session pin > cwd .kenaz > BASE_DIR.
+const projectResolver = require('./lib/project-resolver');
+// TASK_2163: chart files are keyed by project identity + task id (sub-projects reusing
+// bare TASK_ ids previously collided in the flat core sessions dir).
+const chartPathLib = require('./lib/chart-path');
+
+// ═══════════════════════════════════════
+//  Path resolution
+// ═══════════════════════════════════════
+
+function findProjectRoot() {
+  let dir = __dirname;
+  while (dir !== path.dirname(dir)) {
+    const parent = path.dirname(dir);
+    if (fs.existsSync(path.join(parent, '.specialist'))) return parent;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+const BASE_DIR = findProjectRoot();
+
+// TASK_1812: extract --project-path from argv BEFORE any .kenaz/ path constant is
+// computed at module load time (phase-gate.js resolveKenazPath paradigm, boot
+// boundary invariant 1 of sigil_d3b8f855).
+const CLI_PROJECT_PATH = (function () {
+  return projectResolver.extractCliProjectPath(process.argv.slice(2));
+}());
+
+// System/project split (mirrors phase-gate.js):
+//   .specialist/ paths (charts, lesson-guard tool require) = SYSTEM -> BASE_DIR (core).
+//   .kenaz/ paths (shadow/expire logs, ambient signals, task tree) = PROJECT state.
+//
+// MIGRATION DECISION (TASK_1812): leave-in-place, no copy, no dual-read.
+// Without --project-path and without a session pin the resolver returns BASE_DIR,
+// so existing core guard_detector_shadow.jsonl / guard_expire_log.jsonl keep being
+// read and written at their current location — behavior is byte-identical to
+// before. Pinned/flagged sub-project sessions get fresh per-project logs under
+// <project>/.kenaz/specialist/. Historical core entries stay in core: jsonl entries
+// carry no project identity, so any retroactive split would be guesswork.
+const PROJECT_DIR = projectResolver.resolveProjectPath({
+  cliProjectPath: CLI_PROJECT_PATH,
+  argv: process.argv.slice(2),
+}).projectPath;
+
+const SHADOW_LOG_PATH  = path.join(PROJECT_DIR, '.kenaz', 'specialist', 'guard_detector_shadow.jsonl');
+const EXPIRE_LOG_PATH  = path.join(PROJECT_DIR, '.kenaz', 'specialist', 'guard_expire_log.jsonl');
+const AMBIENT_SIGNALS  = path.join(PROJECT_DIR, '.kenaz', 'specialist', 'ambient_signals.json');
+
+// Shadow mode threshold: after this many runs, manual review to unlock live mode
+const SHADOW_THRESHOLD = 10;
+// Auto-expire threshold: hit_rate below this after N live injections
+const EXPIRE_HIT_RATE  = 0.3;
+const EXPIRE_MIN_COUNT = 5;
+
+// TASK_1894: task YAML `status:` field values (NOT .kenaz/tasks/ directory names)
+// that mean "task reached a terminal, non-blocked state". The previous allowlist
+// (['done','archived','axon']) was written against directory names, but the
+// status FIELD value actually written into task YAML is 'completed' (32/32 files
+// under tasks/done/) or, for older entries, 'done' (tasks/archived/). 'archived'
+// and 'axon' have never been observed as an actual status field value — they are
+// storage locations, not lifecycle states.
+const COMPLETED_STATUSES = ['completed', 'done'];
+
+// ═══════════════════════════════════════
+//  Utility helpers
+// ═══════════════════════════════════════
+
+function appendJsonl(filePath, record) {
+  try {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(filePath, JSON.stringify(record) + '\n', 'utf8');
+  } catch { /* never throw from logging */ }
+}
+
+function readJsonFile(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch { return null; }
+}
+
+/**
+ * Find a task YAML file by task ID.
+ * Checks .kenaz/tasks/ and .collaboration/tasks/ with common status dirs.
+ */
+function findTaskFile(taskId) {
+  // TASK_1812: tasks are PROJECT state — a pinned/flagged sub-project session must
+  // read its own task tree, not core's (same kenaz > collaboration order as task-api).
+  const searchRoots = [
+    path.join(PROJECT_DIR, '.kenaz', 'tasks'),
+    path.join(PROJECT_DIR, '.collaboration', 'tasks'),
+  ];
+  const statuses = ['active', 'done', 'archived', 'axon', 'backlog', 'blocked', 'cancel'];
+  for (const root of searchRoots) {
+    if (!fs.existsSync(root)) continue;
+    for (const status of statuses) {
+      const dir = path.join(root, status);
+      if (!fs.existsSync(dir)) continue;
+      try {
+        const files = fs.readdirSync(dir);
+        const match = files.find(f => f.startsWith(taskId + '_') || f === taskId + '.yaml');
+        if (match) return path.join(dir, match);
+      } catch { /* skip */ }
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse a minimal YAML task file to extract specific fields.
+ * No external deps: hand-rolled for the fields we actually need.
+ */
+function parseTaskYaml(content) {
+  const task = {};
+
+  // Extract scalar field: "field: value"
+  const scalarRe = (key) => {
+    const re = new RegExp(`^${key}:\\s*(.+)$`, 'm');
+    const m = content.match(re);
+    return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : null;
+  };
+
+  task.id = scalarRe('id');
+  task.status = scalarRe('status');
+  task.failure_reason = scalarRe('failure_reason');
+
+  // Extract scope_paths list
+  const scopeMatch = content.match(/^scope_paths:\s*\n((?:[ \t]+-[^\n]*\n?)*)/m);
+  if (scopeMatch) {
+    task.scope_paths = scopeMatch[1]
+      .split('\n')
+      .map(l => l.trim())
+      .filter(l => l.startsWith('- '))
+      .map(l => l.slice(2).replace(/^['"]|['"]$/g, '').trim());
+  } else {
+    task.scope_paths = [];
+  }
+
+  // Extract acceptance_criteria list
+  const acMatch = content.match(/^acceptance_criteria:\s*\n((?:[ \t]+-[^\n]*\n?)*)/m);
+  if (acMatch) {
+    task.acceptance_criteria = acMatch[1]
+      .split('\n')
+      .map(l => l.trim())
+      .filter(l => l.startsWith('- '))
+      .map(l => l.slice(2).replace(/^['"]|['"]$/g, '').trim());
+  } else {
+    task.acceptance_criteria = [];
+  }
+
+  return task;
+}
+
+/**
+ * Get the git branch name for a task.
+ * Convention: task/task_{lower_task_id}
+ */
+function getTaskBranch(taskId) {
+  const lower = taskId.toLowerCase().replace(/_/g, '_');
+  return `task/${lower}`;
+}
+
+/**
+ * Normalize a guard's failure_signature into a lowercase, whitespace-joined
+ * string for keyword matching.
+ *
+ * TASK_1894: failure_signature has TWO shapes in lesson_guards.yaml:
+ *   - string  (legacy/heuristic form — e.g. most guards, when present)
+ *   - object  { type, keywords: [...], rationale } (structured v2 form — L-004, L-010)
+ * Calling .toLowerCase() directly on the object form throws (objects have no
+ * such method); the exception was being silently swallowed by runDetector's
+ * try/catch and reported back as a null "exception" detection. This helper
+ * accepts either shape (or null/undefined) and never throws.
+ *
+ * TASK_1894 follow-up: for the object shape, use ONLY `keywords` — never
+ * `rationale` or `type`. `rationale` is prose written for a human reviewer,
+ * not a curated matcher vocabulary; `type` is a dispatch identifier, not a
+ * commit-message signal. Splitting either of them into >3-char tokens and
+ * feeding them to the keyword matcher below inflates the match set with
+ * generic English words. Measured against this repo's `git log -800
+ * --oneline`, L-004's 4 curated keywords (revert/conflict/stale/baseref)
+ * alone match 33/800 commits (4.1%); adding rationale-derived tokens
+ * (agent/commits/branches/produces/large-delta/...) nearly doubles that to
+ * 68/800 (8.5%) — and every one of the extra 35 hits is unrelated to stale
+ * baseRef (they fire on generic words like "agent" or "commits"). A detector
+ * that is ~50% false positives produces noise, not evidence, for the
+ * shadow-ledger review this guard is trying to earn. Do not add rationale
+ * (or type) back into this list without re-measuring the false-positive
+ * rate on a fresh commit sample.
+ */
+function normalizeFailureSignature(failureSignature) {
+  if (!failureSignature) return '';
+  if (typeof failureSignature === 'string') return failureSignature.toLowerCase().trim();
+  if (typeof failureSignature === 'object') {
+    if (Array.isArray(failureSignature.keywords)) {
+      return failureSignature.keywords.join(' ').toLowerCase().trim();
+    }
+    return '';
+  }
+  // Any other shape (number, boolean, etc.) — coerce defensively, never throw.
+  return String(failureSignature).toLowerCase().trim();
+}
+
+// ═══════════════════════════════════════
+//  Detector: git_commit_pattern
+//  Returns: failure_detected | failure_avoided | null
+//
+//  Checks task's git branch for:
+//    - Large line delta (>500 lines changed) → may indicate overreach
+//    - Revert commit detected → clear failure signal
+//  failure_signature is used as a keyword match against commit messages.
+// ═══════════════════════════════════════
+
+/**
+ * TASK_1896: Capture the raw git data detectGitCommitPattern needs, BEFORE
+ * post-complete.js's Step 2 merge runs. Step 2 is a read-after-mutation hazard
+ * for it: the worktree-mode merge rebases `task/<taskId>` onto main before
+ * merging, so `git log <branch> --not main` (what the live detector queries)
+ * comes back EMPTY once Step 2 has run — the branch itself is NOT deleted.
+ * (`git-merge.js` ~849/852's `branch -D` is stale-branch cleanup from a PRIOR
+ * attempt, immediately followed by `checkout -b` recreating the branch fresh
+ * — it is not what removes this run's content.) Confirmed by direct execution
+ * (TASK_1896 verification): after a successful worktree merge the branch
+ * still exists but has zero commits ahead of main, so Step 4.6 (which runs
+ * after Step 2, inside the same postComplete() call) saw `no_commits_on_branch`
+ * for real completed tasks.
+ *
+ * (TASK_1897 resolved the separate `branch_not_found` question referenced
+ * above. Verified against all 35 distinct task_ids behind the 125
+ * branch_not_found rows in guard_detector_shadow.jsonl as of 2026-08-27:
+ * 30 of them (TASK_817..847, minus 818) are a single `replay-detectors.js`
+ * validation run fired ~6.5h after TASK_1163 first shipped this detector
+ * (2026-04-11 ~11:58 +0800) — `findRecentDoneTasks(limit=30)` grabbed the 30
+ * most-recently-mtime'd files under .kenaz/tasks/archived/ and ran every
+ * shadow-mode guard against them via runDetectorsForTask(). All 30 have
+ * `branch: null` in their task YAML and a single non-merge commit each
+ * (direct-commit completions from March 2026, pre-dating task/<taskId>
+ * branches entirely) — `task/task_817` etc. never existed, so
+ * `branch_not_found` was the honest, structurally-correct answer, not a bug.
+ * The remaining 5 (TASK_1687/1688/1689/1690/1697, July 2026) show the same
+ * pattern live rather than via replay: single-parent non-merge commits on
+ * main, no task YAML left in .kenaz/tasks/ at all, no task/ branch ever
+ * created. This is why branch_not_found (92%) dwarfs no_commits_on_branch
+ * (1, from TASK_1896's worktree-merge case): the shadow log's population is
+ * overwhelmingly direct-commit tasks that structurally never had a branch to
+ * find, not branch-based tasks whose branch went missing. See
+ * rune_b937ad4103124287a8ff35861edcd35d for the full per-task evidence.
+ * Also recorded there: 120 of the log's 137 rows land in a single 8-second
+ * window from that one replay run, so ANY rate computed over the raw 137
+ * rows is measuring the replay script, not production guard behaviour —
+ * exclude the 2026-04-11 window before citing shadow-log statistics.)
+ *
+ * This function does not mutate anything — it only reads (rev-parse, log) —
+ * so it cannot change branch -D's own behavior or timing. Callers are
+ * expected to attach the result to a single postComplete() call's result
+ * object (see post-complete.js Step 1.9); it is never persisted to disk and
+ * never reused across invocations, so there is no cache-staleness surface.
+ *
+ * @param {string} taskId
+ * @returns {{branch:string, exists:boolean, logOk:boolean, commitLines:string[], numstatOutput:string, capturedAt:string}}
+ */
+function captureGitCommitSnapshot(taskId) {
+  const branch = getTaskBranch(taskId);
+  const snapshot = {
+    branch,
+    exists: false,
+    logOk: false,
+    commitLines: [],
+    numstatOutput: '',
+    capturedAt: new Date().toISOString(),
+  };
+
+  try {
+    execSync(`git rev-parse --verify ${branch}`, {
+      cwd: PROJECT_DIR, // TASK_1812: task branches live in the project's repo
+      stdio: 'pipe',
+      timeout: 10000,
+      windowsHide: true,
+    });
+    snapshot.exists = true;
+  } catch {
+    // Branch doesn't exist yet at capture time either — honest, not a timing artifact.
+    return snapshot;
+  }
+
+  try {
+    const logOutput = execFileSync(
+      'git', ['log', branch, '--not', 'main', '--oneline'],
+      { cwd: PROJECT_DIR, stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }
+    ).toString().trim();
+    snapshot.logOk = true;
+    snapshot.commitLines = logOutput ? logOutput.split('\n').filter(Boolean) : [];
+  } catch {
+    return snapshot; // logOk stays false — mirrors git_log_failed
+  }
+
+  try {
+    snapshot.numstatOutput = execFileSync(
+      'git', ['log', branch, '--not', 'main', '--numstat', '--format='],
+      { cwd: PROJECT_DIR, stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }
+    ).toString().trim();
+  } catch {
+    // No numstat — non-fatal, mirrors original tolerance for this failure
+  }
+
+  return snapshot;
+}
+
+/**
+ * Shared tail of detectGitCommitPattern: revert detection, failure_signature
+ * keyword match, and line-delta summary. Factored out so both the pre-captured
+ * snapshot path and the legacy live-query path evaluate identically.
+ */
+function _evaluateCommitLines(commitLines, numstatOutput, guard) {
+  // Check for revert commits
+  const hasRevert = commitLines.some(l => /\brevert\b/i.test(l));
+  if (hasRevert) {
+    return {
+      result: 'failure_detected',
+      reason: 'revert_commit_found',
+      revert_commits: commitLines.filter(l => /\brevert\b/i.test(l)),
+    };
+  }
+
+  // Check failure_signature keyword in commit messages
+  const sig = normalizeFailureSignature(guard.failure_signature);
+  if (sig) {
+    const keywords = sig.split(/\s+/).filter(w => w.length > 3);
+    const matchingCommits = commitLines.filter(l =>
+      keywords.some(kw => l.toLowerCase().includes(kw))
+    );
+    if (matchingCommits.length > 0) {
+      return {
+        result: 'failure_detected',
+        reason: 'failure_signature_matched_commit',
+        matched: matchingCommits,
+      };
+    }
+  }
+
+  // Get line delta via --numstat
+  let totalAdded = 0, totalRemoved = 0;
+  for (const line of (numstatOutput || '').split('\n')) {
+    const m = line.match(/^(\d+)\s+(\d+)\s+/);
+    if (m) {
+      totalAdded   += parseInt(m[1], 10);
+      totalRemoved += parseInt(m[2], 10);
+    }
+  }
+
+  const totalDelta = totalAdded + totalRemoved;
+
+  return {
+    result: 'failure_avoided',
+    reason: 'no_failure_signals',
+    line_delta: totalDelta,
+    commit_count: commitLines.length,
+  };
+}
+
+function detectGitCommitPattern(taskId, guard, taskData, postCompleteResult) {
+  try {
+    const branch = getTaskBranch(taskId);
+
+    // TASK_1896: prefer a snapshot captured before post-complete's Step 2 ran
+    // (see captureGitCommitSnapshot above). Only trust it when it is keyed to
+    // THIS taskId — defends against a future caller reusing one result object
+    // across multiple tasks. Any caller that doesn't thread a snapshot (CLI
+    // run/run-all, attribution-report.js, direct require() calls) falls
+    // through to the original live-query behavior, unchanged.
+    const snapshot = postCompleteResult && postCompleteResult.gitCommitSnapshot
+      && postCompleteResult.gitCommitSnapshot.taskId === taskId
+      ? postCompleteResult.gitCommitSnapshot
+      : null;
+
+    if (snapshot) {
+      if (!snapshot.exists) {
+        return { result: null, reason: 'branch_not_found', branch: snapshot.branch };
+      }
+      if (!snapshot.logOk) {
+        return { result: null, reason: 'git_log_failed' };
+      }
+      if (!snapshot.commitLines || snapshot.commitLines.length === 0) {
+        return { result: null, reason: 'no_commits_on_branch' };
+      }
+      return _evaluateCommitLines(snapshot.commitLines, snapshot.numstatOutput, guard);
+    }
+
+    // Check if branch exists
+    try {
+      execSync(`git rev-parse --verify ${branch}`, {
+        cwd: PROJECT_DIR, // TASK_1812: task branches live in the project's repo
+        stdio: 'pipe',
+        timeout: 10000,
+        windowsHide: true,
+      });
+    } catch {
+      // Branch doesn't exist — undetectable
+      return { result: null, reason: 'branch_not_found', branch };
+    }
+
+    // Get commits on this branch (not on main)
+    let logOutput = '';
+    try {
+      logOutput = execFileSync(
+        'git', ['log', branch, '--not', 'main', '--oneline'],
+        { cwd: PROJECT_DIR, stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }
+      ).toString().trim();
+    } catch {
+      return { result: null, reason: 'git_log_failed' };
+    }
+
+    if (!logOutput) {
+      return { result: null, reason: 'no_commits_on_branch' };
+    }
+
+    const commitLines = logOutput.split('\n').filter(Boolean);
+
+    // Get line delta via --numstat
+    let numstatOutput = '';
+    try {
+      numstatOutput = execFileSync(
+        'git', ['log', branch, '--not', 'main', '--numstat', '--format='],
+        { cwd: PROJECT_DIR, stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }
+      ).toString().trim();
+    } catch {
+      // No numstat — still evaluate revert/signature above
+    }
+
+    return _evaluateCommitLines(commitLines, numstatOutput, guard);
+  } catch (e) {
+    return { result: null, reason: `exception: ${e.message}` };
+  }
+}
+
+// ═══════════════════════════════════════
+//  Detector: acceptance_grep_miss
+//  Returns: failure_detected | failure_avoided | null
+//
+//  Short-circuits to null when acceptance_criteria is empty.
+//  When AC exists, checks if acceptance criteria keywords appear in
+//  the task's done output (task yaml + chart file).
+// ═══════════════════════════════════════
+
+function detectAcceptanceGrepMiss(taskId, guard, taskData) {
+  const ac = taskData.acceptance_criteria || [];
+
+  // Short-circuit: no AC → undetectable
+  if (!ac || ac.length === 0) {
+    return { result: null, reason: 'acceptance_criteria_empty' };
+  }
+
+  // Try to read the chart/progress notes for evidence of AC completion
+  const chartPath = chartPathLib.getChartReadPath(taskId, { cliProjectPath: CLI_PROJECT_PATH, argv: process.argv.slice(2) });
+  let chartData = null;
+  if (fs.existsSync(chartPath)) {
+    try {
+      chartData = JSON.parse(fs.readFileSync(chartPath, 'utf8'));
+    } catch { /* ignore */ }
+  }
+
+  // Check if progress notes record any AC as 'fail'
+  if (chartData && Array.isArray(chartData.progress_notes)) {
+    for (const note of chartData.progress_notes) {
+      if (!Array.isArray(note.acceptance_criteria)) continue;
+      const failedAC = note.acceptance_criteria.filter(c => c.status === 'fail');
+      if (failedAC.length > 0) {
+        return {
+          result: 'failure_detected',
+          reason: 'acceptance_criteria_failed_in_progress_note',
+          failed_count: failedAC.length,
+          failed_criteria: failedAC.map(c => c.criterion),
+        };
+      }
+    }
+    // Has progress notes with AC, all pass/partial
+    const hasAnyPass = chartData.progress_notes.some(n =>
+      Array.isArray(n.acceptance_criteria) && n.acceptance_criteria.length > 0
+    );
+    if (hasAnyPass) {
+      return {
+        result: 'failure_avoided',
+        reason: 'acceptance_criteria_addressed_in_progress_note',
+      };
+    }
+  }
+
+  // No chart data or no AC entries in progress notes — undetectable
+  return { result: null, reason: 'no_ac_verification_data_in_chart' };
+}
+
+// ═══════════════════════════════════════
+//  Detector: merge_conflict
+//  Returns: failure_detected | failure_avoided | null
+//
+//  If task status=blocked AND failure_reason=merge_conflict → detected.
+//  Otherwise: failure_avoided (task completed).
+// ═══════════════════════════════════════
+
+function detectMergeConflict(taskId, guard, taskData) {
+  const status = (taskData.status || '').toLowerCase();
+  // failure_reason can live at top-level OR under metadata (post-complete writes nested)
+  const failureReason = String(
+    taskData.failure_reason || (taskData.metadata && taskData.metadata.failure_reason) || ''
+  ).toLowerCase();
+
+  if (status === 'blocked' && failureReason.includes('merge_conflict')) {
+    return {
+      result: 'failure_detected',
+      reason: 'task_blocked_merge_conflict',
+      status,
+      failure_reason: taskData.failure_reason,
+    };
+  }
+
+  // Task not blocked by merge conflict — check if it completed.
+  // TASK_1894: match the task YAML's `status:` FIELD value, not the
+  // .kenaz/tasks/ DIRECTORY name it happens to live under (was 'done'/
+  // 'archived'/'axon' — a vocabulary mismatch that made every completed
+  // task ('status: completed') fall through to the inconclusive branch).
+  if (COMPLETED_STATUSES.includes(status)) {
+    return {
+      result: 'failure_avoided',
+      reason: 'task_completed_no_merge_conflict',
+      status,
+    };
+  }
+
+  // Task still active/unknown status — undetectable
+  return { result: null, reason: `task_status_inconclusive: ${status}` };
+}
+
+// ═══════════════════════════════════════
+//  Detector: regression_test_failure
+//  Returns: failure_detected | failure_avoided | null
+//
+//  Returns undetectable when no test verdict available.
+//  A test verdict is present if the chart has regression_test_result or
+//  post-complete wrote a test_verdict field.
+// ═══════════════════════════════════════
+
+function detectRegressionTestFailure(taskId, guard, taskData, postCompleteResult) {
+  // Check post-complete result for test verdict
+  const pcResult = postCompleteResult || {};
+
+  const testsPassed = pcResult.tests_passed;
+  const testsFailed = pcResult.tests_failed;
+  const testVerdict = pcResult.test_verdict || pcResult.regression_verdict;
+
+  if (testVerdict === 'fail' || testsFailed === true) {
+    return {
+      result: 'failure_detected',
+      reason: 'regression_tests_failed',
+      test_verdict: testVerdict,
+    };
+  }
+
+  if (testVerdict === 'pass' || testsPassed === true) {
+    return {
+      result: 'failure_avoided',
+      reason: 'regression_tests_passed',
+      test_verdict: testVerdict,
+    };
+  }
+
+  // Check chart for regression test info
+  const chartPath = chartPathLib.getChartReadPath(taskId, { cliProjectPath: CLI_PROJECT_PATH, argv: process.argv.slice(2) });
+  if (fs.existsSync(chartPath)) {
+    try {
+      const chart = JSON.parse(fs.readFileSync(chartPath, 'utf8'));
+      // Check vitals warnings for regression failures
+      const warnings = chart.vitals?.warnings || [];
+      const regressionFailed = warnings.some(w =>
+        /regression.*fail|test.*fail|fail.*test/i.test(String(w))
+      );
+      if (regressionFailed) {
+        return { result: 'failure_detected', reason: 'regression_warning_in_vitals' };
+      }
+    } catch { /* ignore */ }
+  }
+
+  // No test verdict available — undetectable (tests don't always run)
+  return { result: null, reason: 'no_test_verdict_available' };
+}
+
+// ═══════════════════════════════════════
+//  Detector: surprise_file_in_scope
+//  Returns: failure_detected | failure_avoided | null
+//
+//  Intersects ambient_signals.json surprise signals with task scope_paths.
+//  If a surprise file matches a scope_path → guard's predicted surprise occurred.
+// ═══════════════════════════════════════
+
+function detectSurpriseFileInScope(taskId, guard, taskData) {
+  const scopePaths = taskData.scope_paths || [];
+
+  // No scope paths — undetectable
+  if (scopePaths.length === 0) {
+    return { result: null, reason: 'no_scope_paths_in_task' };
+  }
+
+  // Read ambient_signals.json
+  const signals = readJsonFile(AMBIENT_SIGNALS);
+  if (!signals) {
+    return { result: null, reason: 'ambient_signals_not_found' };
+  }
+
+  // Extract surprise signals (files/symbols with surprise > threshold)
+  const surpriseFiles = [];
+
+  // Common shapes of ambient_signals.json
+  if (Array.isArray(signals.surprises)) {
+    for (const s of signals.surprises) {
+      const filePath = s.file || s.path || s.symbol_path || '';
+      if (filePath) surpriseFiles.push(filePath.replace(/\\/g, '/'));
+    }
+  } else if (Array.isArray(signals.signals)) {
+    for (const s of signals.signals) {
+      if (s.type === 'surprise' || s.surprise_score > 0.5) {
+        const filePath = s.file || s.path || '';
+        if (filePath) surpriseFiles.push(filePath.replace(/\\/g, '/'));
+      }
+    }
+  } else if (signals.prediction_errors && Array.isArray(signals.prediction_errors)) {
+    for (const pe of signals.prediction_errors) {
+      const filePath = pe.file || pe.path || '';
+      if (filePath) surpriseFiles.push(filePath.replace(/\\/g, '/'));
+    }
+  }
+
+  if (surpriseFiles.length === 0) {
+    return { result: null, reason: 'no_surprise_signals_in_ambient' };
+  }
+
+  // Normalize scope paths
+  const normalizedScope = scopePaths.map(p => p.replace(/\\/g, '/'));
+
+  // Intersect
+  const hits = surpriseFiles.filter(sf =>
+    normalizedScope.some(sp => sf.includes(sp) || sp.includes(sf))
+  );
+
+  if (hits.length > 0) {
+    return {
+      result: 'failure_detected',
+      reason: 'surprise_file_in_scope',
+      matched_files: hits,
+      surprise_count: surpriseFiles.length,
+    };
+  }
+
+  return {
+    result: 'failure_avoided',
+    reason: 'no_scope_surprise_intersection',
+    surprise_count: surpriseFiles.length,
+  };
+}
+
+// ═══════════════════════════════════════
+//  Dispatcher
+// ═══════════════════════════════════════
+
+const DETECTOR_MAP = {
+  git_commit_pattern:      detectGitCommitPattern,
+  acceptance_grep_miss:    detectAcceptanceGrepMiss,
+  merge_conflict:          detectMergeConflict,
+  regression_test_failure: detectRegressionTestFailure,
+  surprise_file_in_scope:  detectSurpriseFileInScope,
+};
+
+const ALL_DETECTOR_TYPES = Object.keys(DETECTOR_MAP);
+
+/**
+ * Run a single detector for a guard+task combination.
+ *
+ * @param {string} taskId
+ * @param {object} guard - Full guard object (from lesson_guards.yaml snapshot)
+ * @param {object} taskData - Parsed task YAML fields
+ * @param {object} [postCompleteResult] - Post-complete result payload (optional)
+ * @returns {{ detector_type, result, reason, detail }}
+ */
+function runDetector(taskId, guard, taskData, postCompleteResult) {
+  const detectorType = guard.detector_type || inferDetectorType(guard);
+
+  const fn = DETECTOR_MAP[detectorType];
+  if (!fn) {
+    return {
+      detector_type: detectorType,
+      result: null,
+      reason: `unknown_detector_type: ${detectorType}`,
+    };
+  }
+
+  let detection;
+  try {
+    detection = fn(taskId, guard, taskData, postCompleteResult);
+  } catch (e) {
+    detection = { result: null, reason: `detector_exception: ${e.message}` };
+  }
+
+  return {
+    detector_type: detectorType,
+    result: detection.result,
+    reason: detection.reason || null,
+    detail: detection,
+  };
+}
+
+/**
+ * Infer detector type from failure_signature if detector_type not set.
+ * Heuristic: look for keywords in the signature.
+ */
+function inferDetectorType(guard) {
+  // failure_signature can be a string (legacy/heuristic) or an object {type, ...}
+  const fs = guard.failure_signature;
+  if (!fs) return 'git_commit_pattern'; // default
+
+  // Object form: explicit type field wins
+  if (typeof fs === 'object' && fs.type) {
+    return fs.type;
+  }
+
+  // String form: keyword heuristic
+  const sig = String(fs).toLowerCase();
+  if (/revert|commit|branch|git/.test(sig)) return 'git_commit_pattern';
+  if (/acceptance|criteria|ac\b/.test(sig)) return 'acceptance_grep_miss';
+  if (/merge.conflict|conflict/.test(sig)) return 'merge_conflict';
+  if (/test|regression|failing/.test(sig)) return 'regression_test_failure';
+  if (/surprise|scope|unexpected/.test(sig)) return 'surprise_file_in_scope';
+  return 'git_commit_pattern';
+}
+
+// ═══════════════════════════════════════
+//  Shadow mode logging
+// ═══════════════════════════════════════
+
+/**
+ * Log a detection decision to shadow log.
+ * Used during shadow mode (first 10 injections per guard).
+ */
+function logShadowDecision(guardId, taskId, detection) {
+  appendJsonl(SHADOW_LOG_PATH, {
+    timestamp: new Date().toISOString(),
+    guard_id: guardId,
+    task_id: taskId,
+    detector_type: detection.detector_type,
+    result: detection.result,
+    reason: detection.reason,
+  });
+}
+
+// ═══════════════════════════════════════
+//  Hit rate update
+// ═══════════════════════════════════════
+
+/**
+ * Update a guard's inferred outcome stats based on a detection result.
+ * Null results are excluded (not counted toward injection_count or hit_rate).
+ *
+ * @param {object} g - Guard object (will be mutated)
+ * @param {string|null} detectionResult - 'failure_detected' | 'failure_avoided' | null
+ * @returns {{ updated: boolean, fields_changed: string[] }}
+ */
+function updateGuardStats(g, detectionResult) {
+  if (detectionResult === null) {
+    // Null = undetectable — EXCLUDED from stats
+    return { updated: false, fields_changed: [] };
+  }
+
+  const changed = [];
+
+  // Only live mode guards update stats (shadow mode only logs)
+  if (g.detector_mode !== 'live') {
+    return { updated: false, fields_changed: [], shadow_only: true };
+  }
+
+  // injection_count: only non-null results count
+  g.injection_count = (g.injection_count || 0) + 1;
+  changed.push('injection_count');
+
+  if (detectionResult === 'failure_avoided') {
+    g.inferred_acted_on = (g.inferred_acted_on || 0) + 1;
+    changed.push('inferred_acted_on');
+  } else if (detectionResult === 'failure_detected') {
+    g.inferred_failure = (g.inferred_failure || 0) + 1;
+    changed.push('inferred_failure');
+  }
+
+  // Recompute hit_rate
+  const total = (g.inferred_acted_on || 0) + (g.inferred_failure || 0);
+  if (total > 0) {
+    g.hit_rate = Math.round(((g.inferred_acted_on || 0) / total) * 1000) / 1000;
+    changed.push('hit_rate');
+  }
+
+  return { updated: true, fields_changed: changed };
+}
+
+// ═══════════════════════════════════════
+//  Auto-expire
+// ═══════════════════════════════════════
+
+/**
+ * Check if a guard should be auto-expired.
+ * Only applies to live-mode guards with enough data.
+ */
+function shouldAutoExpire(g) {
+  if (g.status !== 'active') return false;
+  if (g.detector_mode !== 'live') return false;
+  if ((g.injection_count || 0) < EXPIRE_MIN_COUNT) return false;
+  if (g.hit_rate == null) return false;
+  return g.hit_rate < EXPIRE_HIT_RATE;
+}
+
+/**
+ * Run auto-expire check and write expiry audit log.
+ * Returns list of expired guard IDs.
+ */
+function runAutoExpire(guardsData, dryRun = false) {
+  const expired = [];
+
+  for (const [id, g] of Object.entries(guardsData.guards)) {
+    if (!shouldAutoExpire(g)) continue;
+
+    const decision = {
+      timestamp: new Date().toISOString(),
+      guard_id: id,
+      reason: 'auto_expire: hit_rate < 0.3 after 5+ live injections',
+      detector_mode: g.detector_mode,
+      injection_count: g.injection_count,
+      hit_rate: g.hit_rate,
+      inferred_acted_on: g.inferred_acted_on || 0,
+      inferred_failure: g.inferred_failure || 0,
+      dry_run: dryRun,
+    };
+
+    appendJsonl(EXPIRE_LOG_PATH, decision);
+
+    if (!dryRun) {
+      g.status = 'expired';
+    }
+
+    expired.push({ id, decision });
+  }
+
+  return expired;
+}
+
+// ═══════════════════════════════════════
+//  Main run function (used by attribution-report.js)
+// ═══════════════════════════════════════
+
+/**
+ * Run all applicable detectors for a task and its injected guards.
+ *
+ * @param {string} taskId
+ * @param {Array<object>} guardSnapshots - Snapshots from phaseRec.data.lesson_guards_injected
+ * @param {object} [postCompleteResult] - Post-complete result payload (optional)
+ * @returns {{ task_id, detections: Array, stats_updated: Array, expired: Array }}
+ */
+function runDetectorsForTask(taskId, guardSnapshots, postCompleteResult) {
+  if (!guardSnapshots || guardSnapshots.length === 0) {
+    return { task_id: taskId, detections: [], stats_updated: [], expired: [] };
+  }
+
+  // Load task data
+  const taskFile = findTaskFile(taskId);
+  let taskData = { id: taskId, status: null, failure_reason: null, scope_paths: [], acceptance_criteria: [] };
+  if (taskFile) {
+    try {
+      taskData = parseTaskYaml(fs.readFileSync(taskFile, 'utf8'));
+    } catch { /* use defaults */ }
+  }
+
+  // Load guards yaml for stat updates
+  const lessonGuard = (() => {
+    try {
+      return require(path.join(BASE_DIR, '.specialist', 'tools', 'lesson-guard.js'));
+    } catch { return null; }
+  })();
+
+  const guardData = lessonGuard ? lessonGuard.readGuards() : { guards: {} };
+
+  const detections = [];
+  const statsUpdated = [];
+
+  for (const snapshot of guardSnapshots) {
+    const guardId = snapshot.id;
+    const guardFromYaml = guardData.guards[guardId];
+    if (!guardFromYaml) continue;
+
+    // Use snapshot for failure_signature (yaml may have mutated since injection)
+    const guardForDetection = { ...guardFromYaml, failure_signature: snapshot.failure_signature || guardFromYaml.failure_signature };
+
+    const detection = runDetector(taskId, guardForDetection, taskData, postCompleteResult);
+    detection.guard_id = guardId;
+    detection.snapshot = snapshot;
+
+    // Shadow mode check
+    const isShadow = guardFromYaml.detector_mode !== 'live';
+
+    if (isShadow) {
+      logShadowDecision(guardId, taskId, detection);
+      detection.shadow_logged = true;
+    } else {
+      // Live mode: update stats if result is non-null
+      if (detection.result !== null) {
+        const statsResult = updateGuardStats(guardFromYaml, detection.result);
+        if (statsResult.updated) {
+          statsUpdated.push({ guard_id: guardId, fields: statsResult.fields_changed });
+        }
+      }
+    }
+
+    detections.push(detection);
+  }
+
+  // Write updated guard stats
+  if (statsUpdated.length > 0 && lessonGuard) {
+    try {
+      lessonGuard.writeGuards(guardData);
+    } catch { /* non-fatal */ }
+  }
+
+  // Auto-expire check
+  const expired = runAutoExpire(guardData);
+  if (expired.length > 0 && lessonGuard) {
+    try {
+      lessonGuard.writeGuards(guardData);
+    } catch { /* non-fatal */ }
+  }
+
+  return { task_id: taskId, detections, stats_updated: statsUpdated, expired };
+}
+
+// ═══════════════════════════════════════
+//  CLI commands
+// ═══════════════════════════════════════
+
+// TASK_1812: --project-path/--session-id are consumed at module level by the
+// project resolver. Their space-separated value form ("--project-path X") must
+// not leak X into positionals.
+const RESOLVER_VALUE_FLAGS = new Set(['--project-path', '--session-id']);
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  const list = argv.slice(2);
+  for (let i = 0; i < list.length; i++) {
+    const arg = list[i];
+    if (RESOLVER_VALUE_FLAGS.has(arg) && i + 1 < list.length && !list[i + 1].startsWith('--')) {
+      i++; // skip the flag's value — already consumed by the module-level resolver
+      continue;
+    }
+    const m = arg.match(/^--([^=]+)(?:=(.*))?$/);
+    if (m) {
+      args[m[1]] = m[2] !== undefined ? m[2] : true;
+    } else {
+      args._.push(arg);
+    }
+  }
+  return args;
+}
+
+function cmdRun(args) {
+  const taskId = args.task;
+  if (!taskId) { console.error('Error: --task=TASK_XXX required'); process.exit(1); }
+
+  const guardId = args.guard;
+  const resultFile = args['result-file'];
+
+  // Load guard snapshots from chart if available, or build minimal snapshot
+  let snapshots = [];
+  if (guardId) {
+    // Single guard run
+    const lessonGuard = require(path.join(BASE_DIR, '.specialist', 'tools', 'lesson-guard.js'));
+    const guards = lessonGuard.readGuards();
+    const g = guards.guards[guardId];
+    if (!g) { console.error(`Error: Guard ${guardId} not found`); process.exit(1); }
+    snapshots = [{ id: guardId, failure_signature: g.failure_signature, phase: null }];
+  } else {
+    // Load from chart
+    const chartPath = chartPathLib.getChartReadPath(taskId, { cliProjectPath: CLI_PROJECT_PATH, argv: process.argv.slice(2) });
+    if (fs.existsSync(chartPath)) {
+      try {
+        const chart = JSON.parse(fs.readFileSync(chartPath, 'utf8'));
+        for (const phaseRec of Object.values(chart.phases || {})) {
+          const injected = phaseRec.data?.lesson_guards_injected;
+          if (Array.isArray(injected)) {
+            for (const item of injected) {
+              if (typeof item === 'object' && item.id) snapshots.push(item);
+              else if (typeof item === 'string') snapshots.push({ id: item, failure_signature: null, phase: null });
+            }
+          }
+        }
+      } catch { /* fallback: no snapshots */ }
+    }
+  }
+
+  const result = runDetectorsForTask(taskId, snapshots, null);
+  const output = JSON.stringify(result, null, 2);
+
+  if (resultFile) {
+    fs.writeFileSync(resultFile, output, 'utf8');
+    console.log(`Results written to ${resultFile}`);
+  } else {
+    console.log(output);
+  }
+}
+
+function cmdShadowLog(args) {
+  const guardFilter = args.guard || null;
+  const limit = parseInt(args.limit || '20', 10);
+
+  if (!fs.existsSync(SHADOW_LOG_PATH)) {
+    console.log(JSON.stringify({ ok: true, count: 0, entries: [] }, null, 2));
+    return;
+  }
+
+  let entries = fs.readFileSync(SHADOW_LOG_PATH, 'utf8')
+    .split('\n').filter(Boolean)
+    .map(l => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(Boolean);
+
+  if (guardFilter) {
+    entries = entries.filter(e => e.guard_id === guardFilter);
+  }
+
+  entries = entries.slice(-limit);
+  console.log(JSON.stringify({ ok: true, count: entries.length, entries }, null, 2));
+}
+
+function cmdExpireEligible(args) {
+  const dryRun = args['dry-run'] === true || args['dry-run'] === 'true';
+  const lessonGuard = require(path.join(BASE_DIR, '.specialist', 'tools', 'lesson-guard.js'));
+  const guardData = lessonGuard.readGuards();
+
+  const expired = runAutoExpire(guardData, dryRun);
+  if (!dryRun && expired.length > 0) {
+    lessonGuard.writeGuards(guardData);
+  }
+
+  console.log(JSON.stringify({
+    ok: true,
+    dry_run: dryRun,
+    expired_count: expired.length,
+    expired: expired.map(e => ({ id: e.id, hit_rate: e.decision.hit_rate, injection_count: e.decision.injection_count })),
+  }, null, 2));
+}
+
+module.exports = {
+  runDetector,
+  runDetectorsForTask,
+  captureGitCommitSnapshot,
+  updateGuardStats,
+  runAutoExpire,
+  shouldAutoExpire,
+  ALL_DETECTOR_TYPES,
+  SHADOW_THRESHOLD,
+  EXPIRE_HIT_RATE,
+  EXPIRE_MIN_COUNT,
+  // TASK_1812: exposed for path-resolution contract tests
+  SHADOW_LOG_PATH,
+  EXPIRE_LOG_PATH,
+  AMBIENT_SIGNALS,
+  PROJECT_DIR,
+  BASE_DIR,
+};
+
+if (require.main === module) {
+  const args = parseArgs(process.argv);
+  const cmd  = args._[0];
+
+  switch (cmd) {
+    case 'run':             cmdRun(args);              break;
+    case 'run-all':         cmdRun(args);              break;
+    case 'shadow-log':      cmdShadowLog(args);        break;
+    case 'expire-eligible': cmdExpireEligible(args);   break;
+    default:
+      console.error([
+        'Usage: failure-detector.js <command> [options]',
+        '',
+        'Commands:',
+        '  run           --task=TASK_XXX [--guard=L-001] [--result-file=path]',
+        '  run-all       --task=TASK_XXX [--result-file=path]',
+        '  shadow-log    [--guard=L-001] [--limit=20]',
+        '  expire-eligible [--dry-run]',
+      ].join('\n'));
+      process.exit(1);
+  }
+}