kenaz 0.0.0-stage → 0.3.2

package/core/.formation/tools/post-complete/outcome.js

@@ -0,0 +1,874 @@
+/**
+ * OUTCOME_AND_SKILL_MATRIX — extracted from post-complete.js (D.4 refactor)
+ *
+ * Outcome recording, surprise detection, competence map,
+ * skill matrix tracking, valence accumulation.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { execSync, spawnSync } = require('child_process');
+const { ROOT, COLLABORATION_API, LOG_DIR, getLogDir } = require('../utils');
+const { recordTaskTranscript } = require('../transcript-recorder');
+const { maybeFileAutoWish, deriveWishReason } = require('./wish');
+
+// Dependencies injected from post-complete.js (avoids circular require)
+let _deps = {};
+function initOutcome(deps) { _deps = deps; }
+function resolveProjectRoot(p) { return _deps.resolveProjectRoot(p); }
+function resolveTasksBase(p) { return _deps.resolveTasksBase(p); }
+function loadTaskScopePaths(t, p) { return _deps.loadTaskScopePaths(t, p); }
+function getPostCompleteChangedFiles(r, g) { return _deps.getPostCompleteChangedFiles(r, g); }
+function isVerifiedMergeSuccess(gitResult) {
+  if (typeof _deps.isVerifiedMergeSuccess === 'function') {
+    return _deps.isVerifiedMergeSuccess(gitResult);
+  }
+  return Boolean(gitResult && gitResult.merged === true && gitResult.verify_merge_landed === true);
+}
+
+function deriveTaskOutcome(gitResult) {
+  if (isVerifiedMergeSuccess(gitResult) || gitResult?.noChanges || gitResult?.memoryOnly) {
+    return 'done';
+  }
+  if (gitResult?.mergeConflict || gitResult?.missingTaskBranch || gitResult?.scopePathsMissing) {
+    return 'blocked';
+  }
+  return 'failed';
+}
+
+/**
+ * Decode a git-quoted path to its real filename (TASK_1699).
+ * git wraps non-ASCII paths in double-quotes + octal-escapes bytes.
+ * Returns input unchanged if not wrapped in double-quotes.
+ */
+function decodeGitPath(rawPath) {
+  const s = String(rawPath || '');
+  if (!s.startsWith("\"") || !s.endsWith("\"")) return s;
+  const inner = s.slice(1, -1);
+  const bytes = [];
+  let i = 0;
+  while (i < inner.length) {
+    if (inner[i] === "\\" && i + 3 < inner.length && /^[0-7]{3}$/.test(inner.slice(i + 1, i + 4))) {
+      bytes.push(parseInt(inner.slice(i + 1, i + 4), 8));
+      i += 4;
+    } else if (inner[i] === "\\" && i + 1 < inner.length) {
+      const escMap = { n: 10, t: 9, r: 13, "\"": 34, "\\": 92 };
+      bytes.push(escMap[inner[i + 1]] !== undefined ? escMap[inner[i + 1]] : inner.charCodeAt(i + 1));
+      i += 2;
+    } else {
+      bytes.push(inner.charCodeAt(i));
+      i++;
+    }
+  }
+  try {
+    return Buffer.from(bytes).toString('utf8');
+  } catch {
+    return inner;
+  }
+}
+function normalizeOutcomePath(filePath) {
+  return String(filePath || '').replace(/\\/g, '/').toLowerCase();
+}
+
+function isAutoWritePath(filePath) {
+  const normalized = normalizeOutcomePath(filePath);
+  if (!normalized) return false;
+  return normalized.startsWith('.kenaz/specialist/')
+    || normalized.endsWith('/ansuz_self_model.json');
+}
+
+function filterOutcomeFilesForPrediction(actualFiles) {
+  const included = [];
+  const excluded = [];
+
+  for (const file of actualFiles || []) {
+    if (isAutoWritePath(file)) excluded.push(file);
+    else included.push(file);
+  }
+
+  return { included, excluded };
+}
+
+/**
+ * Best-effort task title lookup for the auto-wish content (TASK_1997).
+ * Searches the same status dirs task YAMLs can live in; never throws.
+ * @param {string} taskId
+ * @param {string|null} projectPath
+ * @returns {string}
+ */
+function readTaskTitleForWish(taskId, projectPath) {
+  try {
+    const tasksBase = resolveTasksBase(projectPath);
+    const dirs = ['blocked', 'done', 'active', 'backlog'];
+    for (const dir of dirs) {
+      const dirPath = path.join(tasksBase, dir);
+      if (!fs.existsSync(dirPath)) continue;
+      const files = fs.readdirSync(dirPath).filter((f) => f.startsWith(taskId) && f.endsWith('.yaml'));
+      if (files.length === 0) continue;
+      const content = fs.readFileSync(path.join(dirPath, files[0]), 'utf8');
+      const m = content.match(/^title:\s*["']?(.+?)["']?\s*$/m);
+      if (m) return m[1];
+      break;
+    }
+  } catch { /* best-effort */ }
+  return '';
+}
+
+/**
+ * Record actual vs predicted file changes after a task completes.
+ * Builds an empirical prediction-vs-reality loop (Gap 3: causal world model).
+ *
+ * - Reads actual touched files via git diff --name-only HEAD~1 HEAD
+ * - Loads scope_paths from task YAML as the prediction
+ * - Computes surprise_files = actual minus scope_paths intersection
+ * - If surprises found: appends prediction_surprise signal to ambient_signals.json (atomic write)
+ * - Writes outcome field to task YAML (actual_files, surprise_files, success)
+ *
+ * Fire-and-forget: never throws. Caller wraps in try/catch.
+ *
+ * @param {string} taskId - TASK_XXX
+ * @param {string|null} projectPath - sub-project path (null = core)
+ * @param {object} gitResult - result from gitBranchAndMerge
+ */
+/**
+ * Decide whether to file an auto-wish for this task outcome and, if so,
+ * do it (TASK_1997 R3). Extracted from recordOutcome so the trigger logic
+ * (when to fire, what title/reason to send) is unit-testable in isolation
+ * from recordOutcome's much heavier and unrelated side effects (transcript
+ * recording, competence map, etc).
+ *
+ * Fire-and-forget: never throws, returns the in-flight promise (or null
+ * when not applicable) so tests can await it — callers must not await it.
+ *
+ * @param {string} taskId
+ * @param {string|null} projectPath
+ * @param {object} gitResult
+ * @param {'done'|'blocked'|'failed'} taskOutcome
+ * @param {object} [deps] - forwarded to maybeFileAutoWish (test injection)
+ * @returns {Promise|null}
+ */
+function triggerAutoWishIfNeeded(taskId, projectPath, gitResult, taskOutcome, deps) {
+  if (!taskId || (taskOutcome !== 'failed' && taskOutcome !== 'blocked')) return null;
+  try {
+    const wishTitle = readTaskTitleForWish(taskId, projectPath);
+    const wishReason = deriveWishReason(gitResult, taskOutcome);
+    const promise = maybeFileAutoWish({
+      taskId,
+      title: wishTitle,
+      reason: wishReason,
+      projectPath: projectPath || undefined,
+      gitResult,
+    }, deps);
+    promise.catch(() => {});
+    return promise;
+  } catch {
+    return null; /* auto-wish must never block post-complete */
+  }
+}
+
+function recordOutcome(taskId, projectPath, gitResult) {
+  if (!taskId) return;
+
+  const projectRoot = resolveProjectRoot(projectPath);
+  const taskOutcome = deriveTaskOutcome(gitResult);
+
+  // TASK_1997 R3: file an auto-wish on failure/blocked, deduped by task_id.
+  // Fire-and-forget (not awaited): recordOutcome itself is synchronous and
+  // must never delay post-complete.
+  triggerAutoWishIfNeeded(taskId, projectPath, gitResult, taskOutcome);
+
+  // 1. Get actual touched files via git diff HEAD~1 HEAD
+  // Decode git-octal-quoted paths to real filenames (TASK_1699).
+  const actualFiles = (projectRoot ? getPostCompleteChangedFiles(projectRoot, gitResult) : []).map(decodeGitPath);
+  const filteredOutcome = filterOutcomeFilesForPrediction(actualFiles);
+  const predictedActualFiles = filteredOutcome.included;
+
+  // 2. Load scope_paths from task YAML (prediction)
+  const scopePaths = loadTaskScopePaths(taskId, projectPath);
+
+  // 3. Normalize paths for comparison (forward slashes, case-insensitive base match)
+  const normalize = (p) => normalizeOutcomePath(p);
+  const normalizedScope = scopePaths.map(normalize);
+
+  // 4. Compute surprise_files = actual minus scope_paths
+  //    A file is "expected" if it matches a scope path exactly or is a child of a scope dir
+  const surpriseFiles = predictedActualFiles.filter((f) => {
+    const nf = normalize(f);
+    return !normalizedScope.some((sp) => nf === sp || nf.startsWith(sp + '/'));
+  });
+
+  if (filteredOutcome.excluded.length > 0) {
+    console.log(`   🗂️  Outcome filtering: excluded ${filteredOutcome.excluded.length} auto-write file(s) from surprise metric`);
+  }
+
+  // 5. Append prediction_surprise signal to ambient_signals.json if surprises found
+  if (surpriseFiles.length > 0) {
+    const root = projectPath || ROOT;
+    const signalsDir = path.join(root, '.kenaz', 'specialist');
+    const signalsFile = path.join(signalsDir, 'ambient_signals.json');
+    const tmpFile = signalsFile + '.tmp.' + process.pid;
+
+    if (!fs.existsSync(signalsDir)) {
+      fs.mkdirSync(signalsDir, { recursive: true });
+    }
+
+    let existing = { signals: [] };
+    try {
+      if (fs.existsSync(signalsFile)) {
+        const parsed = JSON.parse(fs.readFileSync(signalsFile, 'utf8'));
+        existing = parsed;
+        if (!Array.isArray(existing.signals)) existing.signals = [];
+      }
+    } catch { existing = { signals: [] }; }
+
+    existing.signals.push({
+      detected_at: new Date().toISOString(),
+      source: 'post-complete',
+      signal_type: 'prediction_surprise',
+      summary: `Task ${taskId}: ${surpriseFiles.length} unexpected file(s) touched outside scope_paths`,
+      task_id: taskId,
+      symbols: surpriseFiles,
+    });
+
+    // Atomic write: write to tmp then rename
+    fs.writeFileSync(tmpFile, JSON.stringify(existing, null, 2), 'utf8');
+    fs.renameSync(tmpFile, signalsFile);
+    console.log(`   🎯 Outcome: ${surpriseFiles.length} surprise file(s) → ambient_signals.json`);
+  }
+
+  // Transcript capture: export the structured Claude Code session transcript
+  // for successful task sessions when the JSONL quality gate passes.
+  try {
+    const transcript = recordTaskTranscript({
+      taskId,
+      projectPath,
+      outcome: taskOutcome,
+      stripThinking: false,
+    });
+    if (transcript.written) {
+      console.log(`   📝 Transcript recorded: ${transcript.relativePath}`);
+      if (transcript.quality?.unknown_tool_calls?.length > 0) {
+        console.log(`   ⚠️  Transcript unknown tools: ${transcript.quality.unknown_tool_calls.join(', ')}`);
+      }
+    } else if (transcript.skipped) {
+      console.log(`   ℹ️  Transcript skipped: ${transcript.reason}`);
+    }
+  } catch (e) {
+    console.log(`   ⚠️  Transcript recording skipped: ${e.message}`);
+  }
+
+  // 6. Write outcome field back to task YAML
+  const tasksBase = resolveTasksBase(projectPath);
+  const searchDirs = ['done', 'active', 'blocked', 'backlog'];
+  for (const dir of searchDirs) {
+    const dirPath = path.join(tasksBase, dir);
+    if (!fs.existsSync(dirPath)) continue;
+    const files = fs.readdirSync(dirPath).filter(
+      (f) => f.startsWith(taskId) && f.endsWith('.yaml')
+    );
+    if (files.length === 0) continue;
+
+    const yamlPath = path.join(dirPath, files[0]);
+    let content = fs.readFileSync(yamlPath, 'utf8');
+
+    // Remove any existing outcome block before appending fresh one.
+    // NOTE: do NOT use the /m flag here. With /m, `$` matches end-of-line, so the
+    // lookahead `\s*$` is satisfied immediately after `outcome:` (zero whitespace +
+    // end-of-line), causing the non-greedy `[\s\S]*?` to match 0 characters. The
+    // result: only the literal `outcome:` line is removed and its indented children
+    // (success, actual_files, surprise_files) are left as orphan mappings under the
+    // previous key, producing invalid YAML. Without /m, `$` only matches end-of-string,
+    // forcing the non-greedy match to expand to the next top-level key or EOF.
+    content = content.replace(/\noutcome:[\s\S]*?(?=\n[a-z_]+:|\s*$)/, '');
+
+    const success = gitResult ? isVerifiedMergeSuccess(gitResult) : true;
+    const yamlList = (key, items) => {
+      if (items.length === 0) return `  ${key}: []`;
+      return `  ${key}:\n` + items.map((f) => `    - ${JSON.stringify(decodeGitPath(f))}`).join('\n');
+    };
+    const outcomeBlock = [
+      'outcome:',
+      `  success: ${success}`,
+      yamlList('actual_files', actualFiles),
+      yamlList('surprise_files', surpriseFiles),
+      '',
+    ].join('\n');
+
+    content = content.trimEnd() + '\n' + outcomeBlock;
+    fs.writeFileSync(yamlPath, content, 'utf8');
+    console.log(`   📊 Outcome recorded: ${actualFiles.length} actual, ${surpriseFiles.length} surprise`);
+    break;
+  }
+
+  // TASK_910: Compare prediction vs outcome and update accuracy
+  try {
+    const outcomeSuccess = gitResult ? isVerifiedMergeSuccess(gitResult) : true;
+    compareOutcomePrediction(taskId, projectPath, predictedActualFiles, outcomeSuccess);
+  } catch { /* prediction comparison failed — never block post-complete */ }
+}
+
+// ─────────────────────────────────────────
+// Outcome Tracker: Prediction-vs-Outcome Comparison (TASK_910)
+// ─────────────────────────────────────────
+
+/**
+ * Compare Phase 3 predictions with actual post-complete outcomes.
+ * Computes surprise_score (Jaccard distance) and valence.
+ * Updates cumulative accuracy in ansuz_accuracy.json.
+ *
+ * Fire-and-forget: never throws. Caller wraps in try/catch.
+ *
+ * @param {string} taskId - TASK_XXX
+ * @param {string|null} projectPath - sub-project path (null = core)
+ * @param {string[]} actualFiles - files actually touched (from git diff)
+ * @param {boolean} success - whether git merge succeeded
+ */
+function compareOutcomePrediction(taskId, projectPath, actualFiles, success) {
+  if (!taskId) return;
+
+  const root = projectPath || ROOT;
+  const specialistDir = path.join(root, '.kenaz', 'specialist');
+  const predictionsFile = path.join(specialistDir, 'ansuz_predictions.json');
+  const accuracyFile = path.join(specialistDir, 'ansuz_accuracy.json');
+
+  // 1. Load prediction for this task
+  if (!fs.existsSync(predictionsFile)) return;
+
+  let predictions;
+  try {
+    predictions = JSON.parse(fs.readFileSync(predictionsFile, 'utf8'));
+  } catch { return; }
+
+  if (!predictions || !Array.isArray(predictions.predictions)) return;
+
+  const prediction = predictions.predictions.find(p => p.task_id === taskId);
+  if (!prediction) return;
+
+  const expectedFiles = prediction.expected_files || [];
+
+  // 2. Compute surprise_score (Jaccard distance)
+  const normalize = (p) => p.replace(/\\/g, '/').toLowerCase();
+  const normalizedExpected = new Set(expectedFiles.map(normalize));
+  const normalizedActual = new Set(actualFiles.map(normalize));
+
+  // For Jaccard: consider file-level matching (actual file is "expected" if it
+  // matches a scope path exactly or is a child of a scope dir)
+  let intersectionCount = 0;
+  for (const af of normalizedActual) {
+    for (const ef of normalizedExpected) {
+      if (af === ef || af.startsWith(ef + '/')) {
+        intersectionCount++;
+        break;
+      }
+    }
+  }
+
+  const unionCount = normalizedExpected.size + normalizedActual.size - intersectionCount;
+  const surpriseScore = unionCount > 0 ? 1.0 - (intersectionCount / unionCount) : 0.0;
+
+  // 3. Compute valence
+  let valence;
+  if (success && surpriseScore < 0.3) {
+    valence = 'positive';
+  } else if (!success || surpriseScore >= 0.5) {
+    valence = 'negative';
+  } else {
+    valence = 'neutral';
+  }
+
+  console.log(`   🔮 Prediction comparison: surprise=${surpriseScore.toFixed(2)}, valence=${valence}`);
+
+  // 4. Update cumulative accuracy in ansuz_accuracy.json
+  if (!fs.existsSync(specialistDir)) {
+    fs.mkdirSync(specialistDir, { recursive: true });
+  }
+
+  let accuracy = { total_predictions: 0, accurate_predictions: 0, running_accuracy: 0, last_updated: '', recent_surprises: [] };
+  try {
+    if (fs.existsSync(accuracyFile)) {
+      accuracy = JSON.parse(fs.readFileSync(accuracyFile, 'utf8'));
+    }
+  } catch { /* start fresh */ }
+
+  accuracy.total_predictions = (accuracy.total_predictions || 0) + 1;
+  if (surpriseScore < 0.3) {
+    accuracy.accurate_predictions = (accuracy.accurate_predictions || 0) + 1;
+  }
+  accuracy.running_accuracy = accuracy.total_predictions > 0
+    ? accuracy.accurate_predictions / accuracy.total_predictions
+    : 0;
+  accuracy.last_updated = new Date().toISOString();
+
+  // Track recent high-surprise events (keep last 10)
+  if (!Array.isArray(accuracy.recent_surprises)) accuracy.recent_surprises = [];
+  if (surpriseScore >= 0.3) {
+    accuracy.recent_surprises.push({
+      task_id: taskId,
+      surprise_score: parseFloat(surpriseScore.toFixed(3)),
+      valence,
+      timestamp: new Date().toISOString(),
+    });
+    // Keep only last 10
+    if (accuracy.recent_surprises.length > 10) {
+      accuracy.recent_surprises = accuracy.recent_surprises.slice(-10);
+    }
+  }
+
+  // TASK_962: Accumulate per-task comparison details for competence map
+  if (!Array.isArray(accuracy.comparison_history)) accuracy.comparison_history = [];
+  accuracy.comparison_history.push({
+    task_id: taskId,
+    timestamp: new Date().toISOString(),
+    file_jaccard: parseFloat((1.0 - surpriseScore).toFixed(3)),
+    predicted_risk: prediction.risk || 'unknown',
+    predicted_health_delta: prediction.predicted_health_delta || 'unknown',
+    fallback: prediction.source === 'compression_fallback',
+    actual_success: success,
+    actual_valence: valence,
+    expected_file_count: expectedFiles.length,
+    actual_file_count: actualFiles.length,
+    intersection_count: intersectionCount,
+  });
+  // Keep last 100 comparisons
+  if (accuracy.comparison_history.length > 100) {
+    accuracy.comparison_history = accuracy.comparison_history.slice(-100);
+  }
+
+  // Atomic write
+  const tmpAccuracy = accuracyFile + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpAccuracy, JSON.stringify(accuracy, null, 2), 'utf8');
+  fs.renameSync(tmpAccuracy, accuracyFile);
+  console.log(`   📈 Accuracy: ${(accuracy.running_accuracy * 100).toFixed(1)}% (${accuracy.accurate_predictions}/${accuracy.total_predictions})`);
+
+  // TASK_962: Update competence map in ansuz_self_model.json
+  try {
+    updateCompetenceMap(specialistDir, accuracy.comparison_history);
+  } catch { /* competence map update failed — never block post-complete */ }
+
+  // 6. TASK_912: Valence Accumulator — inject emotional momentum neurons
+  try {
+    accumulateValence(taskId, projectPath, valence, success);
+  } catch { /* valence accumulation failed — never block post-complete */ }
+}
+
+// ─────────────────────────────────────────
+// Competence Map: Statistical Self-Model (TASK_962)
+// ─────────────────────────────────────────
+
+/**
+ * Compute per-dimension competence metrics from comparison history
+ * and write competence_map alongside narrative in ansuz_self_model.json.
+ *
+ * Dimensions:
+ *   - file_prediction_accuracy: mean Jaccard similarity across all comparisons
+ *   - risk_calibration_score: how well predicted risk matches actual outcomes
+ *
+ * Sets insufficient_data=true when N < 20.
+ *
+ * @param {string} specialistDir - path to .kenaz/specialist/
+ * @param {Array} history - comparison_history from ansuz_accuracy.json
+ */
+function updateCompetenceMap(specialistDir, history) {
+  if (!Array.isArray(history) || history.length === 0) return;
+
+  const selfModelFile = path.join(specialistDir, 'ansuz_self_model.json');
+  const n = history.length;
+  const insufficientData = n < 20;
+
+  // 1. File prediction accuracy: mean Jaccard similarity
+  const filePredictionAccuracy = history.reduce((sum, h) => sum + (h.file_jaccard || 0), 0) / n;
+
+  // 2. Risk calibration score
+  // Map risk levels to expected failure probability, then compare with actual outcomes
+  const riskToExpectedFailRate = { low: 0.1, medium: 0.3, high: 0.6, unknown: 0.3 };
+  let riskCalibrationError = 0;
+  let riskSamples = 0;
+
+  // Group by risk level and compute actual failure rate per group
+  const riskGroups = {};
+  for (const h of history) {
+    const risk = h.predicted_risk || 'unknown';
+    if (!riskGroups[risk]) riskGroups[risk] = { total: 0, failures: 0 };
+    riskGroups[risk].total++;
+    if (!h.actual_success) riskGroups[risk].failures++;
+  }
+
+  for (const [risk, group] of Object.entries(riskGroups)) {
+    const expectedFailRate = riskToExpectedFailRate[risk] || 0.3;
+    const actualFailRate = group.total > 0 ? group.failures / group.total : 0;
+    riskCalibrationError += Math.abs(expectedFailRate - actualFailRate) * group.total;
+    riskSamples += group.total;
+  }
+
+  // Risk calibration: 1.0 = perfect calibration, 0.0 = maximally miscalibrated
+  const riskCalibrationScore = riskSamples > 0 ? 1.0 - (riskCalibrationError / riskSamples) : 0;
+
+  const competenceMap = {
+    last_updated: new Date().toISOString(),
+    sample_count: n,
+    insufficient_data: insufficientData,
+    dimensions: {
+      file_prediction_accuracy: {
+        score: parseFloat(filePredictionAccuracy.toFixed(3)),
+        description: 'Mean Jaccard similarity between predicted and actual files touched',
+        sample_count: n,
+      },
+      risk_calibration_score: {
+        score: parseFloat(riskCalibrationScore.toFixed(3)),
+        description: 'How well predicted risk levels match actual failure rates (1.0 = perfect)',
+        sample_count: n,
+        breakdown: Object.fromEntries(
+          Object.entries(riskGroups).map(([risk, g]) => [
+            risk,
+            {
+              predicted_fail_rate: riskToExpectedFailRate[risk] || 0.3,
+              actual_fail_rate: parseFloat((g.total > 0 ? g.failures / g.total : 0).toFixed(3)),
+              count: g.total,
+            },
+          ])
+        ),
+      },
+    },
+  };
+
+  // Load existing self-model, add competence_map alongside narrative
+  let selfModel = {};
+  try {
+    if (fs.existsSync(selfModelFile)) {
+      selfModel = JSON.parse(fs.readFileSync(selfModelFile, 'utf8'));
+    }
+  } catch { /* start fresh */ }
+
+  selfModel.competence_map = competenceMap;
+
+  // Atomic write
+  const tmpSelfModel = selfModelFile + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpSelfModel, JSON.stringify(selfModel, null, 2), 'utf8');
+  fs.renameSync(tmpSelfModel, selfModelFile);
+
+  const status = insufficientData ? `(insufficient data, N=${n})` : `(N=${n})`;
+  console.log(`   🧠 Competence map: file_accuracy=${filePredictionAccuracy.toFixed(2)}, risk_calibration=${riskCalibrationScore.toFixed(2)} ${status}`);
+}
+
+// ─────────────────────────────────────────
+// Tag-to-Skill-Key Classification (TASK_987)
+// ─────────────────────────────────────────
+
+const DOMAIN_MAP = {
+  rust: 'rust', rs: 'rust', tauri: 'rust', synapse: 'rust',
+  typescript: 'typescript', ts: 'typescript', react: 'typescript', next: 'typescript',
+  database: 'database', sql: 'database', migration: 'database', kuzu: 'database',
+  formation: 'formation', dispatch: 'formation', agent: 'formation',
+  yaml: 'spec', spec: 'spec', config: 'spec',
+};
+
+const TASK_TYPE_MAP = {
+  fix: 'bug_fix', bug: 'bug_fix', regression: 'bug_fix',
+  feature: 'feature', new: 'feature', add: 'feature',
+  refactor: 'refactor', optimize: 'refactor', cleanup: 'refactor',
+  config: 'config', setup: 'config', infra: 'config',
+  test: 'test', coverage: 'test', e2e: 'test',
+  code: 'feature',
+};
+
+/**
+ * Classify task YAML tags into a skill key ({domain}:{task_type}).
+ * Used by Skill Matrix for per-skill performance tracking.
+ *
+ * @param {string[]} tags - Tags from task YAML tags field
+ * @returns {string} Skill key in format "domain:task_type"
+ */
+function classifySkillKey(tags) {
+  if (!Array.isArray(tags) || tags.length === 0) return 'general:general';
+
+  let domain = null;
+  let taskType = null;
+
+  for (const tag of tags) {
+    const t = String(tag).toLowerCase().trim();
+    if (!domain && DOMAIN_MAP[t]) domain = DOMAIN_MAP[t];
+    if (!taskType && TASK_TYPE_MAP[t]) taskType = TASK_TYPE_MAP[t];
+    if (domain && taskType) break;
+  }
+
+  return `${domain || 'general'}:${taskType || 'general'}`;
+}
+
+// ─────────────────────────────────────────
+// Skill Matrix: Per-Skill Tracking (TASK_986)
+// ─────────────────────────────────────────
+
+/**
+ * Infer skill key ({domain}:{task_type}) from task metadata.
+ * Domain is derived from scope_paths (e.g. "formation", "dashboard", "specialist").
+ * Task type is derived from task title keywords (e.g. "fix", "refactor", "feature").
+ *
+ * @param {string} taskId
+ * @param {string|null} projectPath
+ * @returns {{ domain: string, task_type: string, skill_key: string }}
+ */
+function inferSkillKey(taskId, projectPath) {
+  let domain = 'general';
+  let taskType = 'feature';
+
+  const tasksBase = resolveTasksBase(projectPath);
+  const dirs = ['done', 'active', 'backlog', 'blocked'];
+
+  for (const dir of dirs) {
+    const dirPath = path.join(tasksBase, dir);
+    if (!fs.existsSync(dirPath)) continue;
+    const files = fs.readdirSync(dirPath).filter(f => f.startsWith(taskId) && f.endsWith('.yaml'));
+    if (files.length === 0) continue;
+
+    try {
+      const content = fs.readFileSync(path.join(dirPath, files[0]), 'utf8');
+
+      // Primary: use tags via classifySkillKey (TASK_987) when available
+      const tagsMatch = content.match(/^tags:\s*\n((?:\s+-\s+.+\n?)*)/m);
+      if (tagsMatch) {
+        const tags = tagsMatch[1].match(/^\s+-\s+["']?([^"'\n]+?)["']?\s*$/gm);
+        if (tags && tags.length > 0) {
+          const tagValues = tags.map(t => t.replace(/^\s+-\s+["']?/, '').replace(/["']?\s*$/, ''));
+          const classified = classifySkillKey(tagValues);
+          if (classified !== 'general:general') {
+            const [d, t] = classified.split(':');
+            return { domain: d, task_type: t, skill_key: classified };
+          }
+        }
+      }
+
+      // Fallback: scope_paths + title heuristics (TASK_986)
+      const scopeMatch = content.match(/^scope_paths:\s*\n((?:\s+-\s+.+\n?)*)/m);
+      if (scopeMatch) {
+        const firstPath = scopeMatch[1].match(/^\s+-\s+"?([^"]+)"?\s*$/m);
+        if (firstPath) {
+          const p = firstPath[1].replace(/\\/g, '/');
+          // Extract top-level directory as domain
+          const segments = p.split('/').filter(Boolean);
+          if (segments.length > 0) {
+            domain = segments[0].replace(/^\./, ''); // strip leading dot
+          }
+        }
+      }
+
+      // Extract task_type from title keywords
+      const titleMatch = content.match(/^title:\s*["']?(.+?)["']?\s*$/m);
+      if (titleMatch) {
+        const title = titleMatch[1].toLowerCase();
+        if (/\bfix\b|bug\b|patch\b|hotfix\b/.test(title)) taskType = 'fix';
+        else if (/\brefactor\b|cleanup\b|clean.?up\b/.test(title)) taskType = 'refactor';
+        else if (/\btest\b|spec\b|coverage\b/.test(title)) taskType = 'test';
+        else if (/\bdoc\b|readme\b|comment\b/.test(title)) taskType = 'docs';
+        else if (/\bintegrat\b|connect\b|wire\b/.test(title)) taskType = 'integration';
+        else if (/\bdesign\b|schema\b|model\b|data.model\b/.test(title)) taskType = 'design';
+        else taskType = 'feature';
+      }
+    } catch { /* skip */ }
+    break;
+  }
+
+  return { domain, task_type: taskType, skill_key: `${domain}:${taskType}` };
+}
+
+/**
+ * Update the Skill Matrix after task completion.
+ * Reads/creates .kenaz/specialist/ansuz_skill_matrix.json with per-skill tracking.
+ *
+ * Each skill entry tracks: success_rate, avg_fix_cycles, file_prediction_accuracy,
+ * trend, trend_window, last_updated.
+ *
+ * Also maintains global_stats and regression_alerts.
+ *
+ * @param {{ taskId: string, projectPath: string|null, success: boolean, fixCycles: number, filePredictionAccuracy: number|null }} taskResult
+ */
+function updateSkillMatrix(taskResult) {
+  const { taskId, projectPath, success, fixCycles = 0, filePredictionAccuracy = null } = taskResult;
+  if (!taskId) return;
+
+  const root = projectPath || ROOT;
+  const specialistDir = path.join(root, '.kenaz', 'specialist');
+  const matrixFile = path.join(specialistDir, 'ansuz_skill_matrix.json');
+
+  // Ensure directory exists
+  if (!fs.existsSync(specialistDir)) {
+    fs.mkdirSync(specialistDir, { recursive: true });
+  }
+
+  // Load or initialize
+  let matrix = {
+    schema_version: '1.0.0',
+    skills: {},
+    global_stats: {
+      total_tasks: 0,
+      total_successes: 0,
+      overall_success_rate: 0,
+      last_updated: '',
+    },
+    regression_alerts: [],
+  };
+
+  try {
+    if (fs.existsSync(matrixFile)) {
+      matrix = JSON.parse(fs.readFileSync(matrixFile, 'utf8'));
+      // Ensure schema_version exists for older files
+      if (!matrix.schema_version) matrix.schema_version = '1.0.0';
+      if (!matrix.skills) matrix.skills = {};
+      if (!matrix.global_stats) matrix.global_stats = { total_tasks: 0, total_successes: 0, overall_success_rate: 0, last_updated: '' };
+      if (!matrix.regression_alerts) matrix.regression_alerts = [];
+    }
+  } catch { /* start fresh */ }
+
+  // Infer skill key
+  const { skill_key } = inferSkillKey(taskId, projectPath);
+
+  // Initialize skill entry if new
+  if (!matrix.skills[skill_key]) {
+    matrix.skills[skill_key] = {
+      total: 0,
+      successes: 0,
+      success_rate: 0,
+      fix_cycles_total: 0,
+      avg_fix_cycles: 0,
+      file_prediction_samples: 0,
+      file_prediction_sum: 0,
+      file_prediction_accuracy: 0,
+      trend: 'stable',
+      trend_window: [],
+      last_updated: '',
+    };
+  }
+
+  const skill = matrix.skills[skill_key];
+  const prevRate = skill.success_rate;
+
+  // Update counters
+  skill.total += 1;
+  if (success) skill.successes += 1;
+  skill.success_rate = parseFloat((skill.successes / skill.total).toFixed(3));
+  skill.fix_cycles_total += fixCycles;
+  skill.avg_fix_cycles = parseFloat((skill.fix_cycles_total / skill.total).toFixed(2));
+
+  if (filePredictionAccuracy !== null && filePredictionAccuracy !== undefined) {
+    skill.file_prediction_samples += 1;
+    skill.file_prediction_sum += filePredictionAccuracy;
+    skill.file_prediction_accuracy = parseFloat(
+      (skill.file_prediction_sum / skill.file_prediction_samples).toFixed(3)
+    );
+  }
+
+  // Trend window: keep last 10 outcomes (1=success, 0=fail)
+  skill.trend_window.push(success ? 1 : 0);
+  if (skill.trend_window.length > 10) {
+    skill.trend_window = skill.trend_window.slice(-10);
+  }
+
+  // Compute trend from window
+  if (skill.trend_window.length >= 3) {
+    const recent = skill.trend_window.slice(-3);
+    const recentRate = recent.reduce((a, b) => a + b, 0) / recent.length;
+    const older = skill.trend_window.slice(0, -3);
+    if (older.length >= 2) {
+      const olderRate = older.reduce((a, b) => a + b, 0) / older.length;
+      if (recentRate - olderRate > 0.15) skill.trend = 'improving';
+      else if (olderRate - recentRate > 0.15) skill.trend = 'declining';
+      else skill.trend = 'stable';
+    }
+  }
+
+  skill.last_updated = new Date().toISOString();
+
+  // Update global stats
+  matrix.global_stats.total_tasks += 1;
+  if (success) matrix.global_stats.total_successes += 1;
+  matrix.global_stats.overall_success_rate = parseFloat(
+    (matrix.global_stats.total_successes / matrix.global_stats.total_tasks).toFixed(3)
+  );
+  matrix.global_stats.last_updated = new Date().toISOString();
+
+  // Regression alert: rate drop > 20% for skills with sufficient history
+  if (skill.total >= 3 && prevRate > 0 && (prevRate - skill.success_rate) > 0.20) {
+    matrix.regression_alerts.push({
+      skill_key,
+      detected_at: new Date().toISOString(),
+      task_id: taskId,
+      previous_rate: prevRate,
+      current_rate: skill.success_rate,
+      drop: parseFloat((prevRate - skill.success_rate).toFixed(3)),
+      message: `Skill "${skill_key}" success rate dropped from ${(prevRate * 100).toFixed(1)}% to ${(skill.success_rate * 100).toFixed(1)}%`,
+    });
+    // Keep last 20 alerts
+    if (matrix.regression_alerts.length > 20) {
+      matrix.regression_alerts = matrix.regression_alerts.slice(-20);
+    }
+    console.log(`   ⚠️  Skill regression: ${skill_key} rate dropped ${(prevRate * 100).toFixed(0)}% → ${(skill.success_rate * 100).toFixed(0)}%`);
+  }
+
+  // Atomic write
+  const tmpFile = matrixFile + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpFile, JSON.stringify(matrix, null, 2), 'utf8');
+  fs.renameSync(tmpFile, matrixFile);
+
+  console.log(`   📊 Skill Matrix: ${skill_key} → rate=${(skill.success_rate * 100).toFixed(0)}% trend=${skill.trend} (N=${skill.total})`);
+}
+
+// ─────────────────────────────────────────
+// Valence Accumulator: Emotional Momentum SNN (TASK_912)
+// ─────────────────────────────────────────
+
+/**
+ * Accumulate positive and negative valence based on task outcome.
+ * Two thalamus neurons track emotional momentum:
+ *   - valence_pos_: +0.3 on success, +0.2 on health KEEP, +0.1 on user confirmation
+ *   - valence_neg_: +0.3 on failure, +0.2 on health REVERT, +0.1 on user correction
+ *
+ * Positive fire → log autonomy_boost event
+ * Negative fire → log caution event
+ * Both high simultaneously → trigger cognitive episode via hippocampus
+ *
+ * @param {string} taskId - TASK_XXX
+ * @param {string|null} projectPath - sub-project path (null = core)
+ * @param {string} valence - 'positive' | 'negative' | 'neutral'
+ * @param {boolean} success - whether task succeeded
+ */
+function accumulateValence(taskId, projectPath, valence, success) {
+  if (!taskId) return;
+
+  console.log(`   ${success ? '💚' : '🔴'} Valence: ${valence} (task ${success ? 'success' : 'failure'})`);
+}
+
+// ─────────────────────────────────────────
+// 主流程
+// ─────────────────────────────────────────
+
+/**
+ * 完整的 post-complete 流程
+ * @param {object} opts
+ * @param {string} opts.taskId - TASK_XXX
+ * @param {number} opts.keep - 保留的 done 任務數
+ * @param {boolean} opts.skipArchive - 跳過 archive
+ * @param {boolean} opts.skipGit - 跳過 git
+ * @param {boolean} opts.skipTests - 跳過回歸測試（PPL-113）
+ * @param {boolean} opts.dryRun - 模擬執行
+ * @param {string} opts.message - commit message
+ * @param {string} opts.projectPath - 子專案路徑（null = core）
+ * @param {string[]} opts.testCommands - Agent 指定的測試指令（PPL-113）
+ * @param {string} opts.logPath - Formation log 路徑（Cognitive Checkpoint 偵測用）
+ * @param {string} [opts.worktreePath] - Worktree 路徑（parallel dispatch 模式）
+ *   When set: agent already committed in worktree, skip stash/commit, only merge.
+ *   When null: legacy serial mode (stash → commit → merge).
+ */
+
+module.exports = {
+  initOutcome,
+  isAutoWritePath,
+  filterOutcomeFilesForPrediction,
+  recordOutcome,
+  compareOutcomePrediction,
+  updateCompetenceMap,
+  classifySkillKey,
+  inferSkillKey,
+  updateSkillMatrix,
+  accumulateValence,
+  readTaskTitleForWish,
+  triggerAutoWishIfNeeded,
+};