kenaz 0.3.18 → 0.3.19

package/core/.specialist/tools/memory-action-log.js

@@ -1,839 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * memory-action-log.js — Unified Memory-to-Action instrumentation (TASK_1072 + TASK_1078)
- *
- * Tracks whether a recalled memory item (handoff, episode, rune, sigil,
- * self-model lesson, lesson guard) later influenced a design, dispatch,
- * validation or fix-loop decision.
- *
- * Why this exists:
- *   Recall has been a silent operation — we had no way to distinguish
- *   "loaded into context" from "actually changed the agent's behaviour".
- *   This module turns memory from passive context into a measurable
- *   decision-influence signal.
- *
- * Relationship to existing infrastructure:
- *   - Runes:          synapse rune_usage_log (TASK_589) — we delegate; our
- *                     log cross-references rune_id but does not duplicate
- *                     the rune table.
- *   - Lesson guards:  lesson-guard.js (TASK_1071/1076) — we call its module
- *                     API so the legacy lesson_guard_acted_on.jsonl and the
- *                     new unified log stay in sync.
- *   - Handoff/episode/sigil/self-model: NEW — no prior acted-on tracking.
- *
- * Storage:
- *   .kenaz/specialist/memory_action_log.jsonl   (append-only, JSONL)
- *
- * Schema (one JSON object per line):
- *   {
- *     "timestamp": "<ISO-8601>",
- *     "event": "recall" | "acted_on",
- *     "recall_id": "<stable ID, e.g. recall_1712345_abc123>",   // always present
- *     "source": "handoff" | "episode" | "rune" | "sigil" | "self_model" | "lesson_guard",
- *     "source_id": "<stable id: rune_id | episode_id | sigil_id | B-XXX | L-XXX | handoff session_id>",
- *     "task_id": "<TASK_XXXX or session id>",
- *     "phase": <int phase>  | null,
- *     "action_type": "design_decision" | "dispatch_choice" | "validation_behavior"
- *                  | "fix_loop_decision" | "scope_adjustment" | "blocked_exit"
- *                  | null,
- *     "reason": "<evidence text, >=20 chars for acted_on>",
- *     "conflict_with": "<winner_source_id>" | null,
- *     "priority_rank": <int from memory_source_priority.yaml> | null,
- *     "recalled_from_ids": ["<recall_id>", ...]   // for acted_on events: IDs of recall events that led to this decision
- *   }
- *
- * CLI:
- *   node memory-action-log.js record-recall --source=rune --source-id=rune_X --task=TASK_XXX [--phase=N] [--reason="text"]
- *   node memory-action-log.js record-acted  --source=rune --source-id=rune_X --task=TASK_XXX --action-type=design_decision --reason="why" [--recalled-from=recall_id1,recall_id2]
- *   node memory-action-log.js report        [--window-days=30] [--task=TASK_XXX] [--json]
- *   node memory-action-log.js priority      [--source-type=rune] [--type=decision] [--confidence=0.85]
- *   node memory-action-log.js list-recalls  --task=TASK_XXX [--phase=N] [--json]
- *
- * Module exports (for phase-gate.js and other callers):
- *   recordRecall(entry)         → { ok, recall_id, line?, error? }
- *   recordActedOn(entry)        → { ok, line?, error? }
- *   getMetrics(opts)            → { by_source, totals, window_days, link_rate }
- *   getPriorityRank(descriptor) → { rank, tier, mode }
- *   loadPriorityRules()         → parsed yaml object (cached)
- *   recordActedOnBatch(items, taskId, phase) → { recorded, failed[] }
- *   listRecalls(taskId, phase?) → [recall entries]
- *
- * Graceful degradation contract:
- *   Every write path is try/catch — a failure in the memory-action-log
- *   must never block a phase-gate exit or cause a specialist to crash.
- *   On failure the module returns { ok: false, error } and never throws.
- *
- * Exit codes (CLI):
- *   0 = success
- *   1 = fatal error (bad args, missing required field)
- */
-
-'use strict';
-
-const fs     = require('fs');
-const path   = require('path');
-const crypto = require('crypto');
-
-// ═══════════════════════════════════════
-//  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();
-const LOG_PATH        = path.join(BASE_DIR, '.kenaz', 'specialist', 'memory_action_log.jsonl');
-const PRIORITY_PATH   = path.join(BASE_DIR, '.kenaz', 'specialist', 'memory_source_priority.yaml');
-const LESSON_GUARD_JS = path.join(BASE_DIR, '.specialist', 'tools', 'lesson-guard.js');
-
-const VALID_SOURCES = new Set([
-  'handoff', 'episode', 'rune', 'sigil', 'self_model', 'lesson_guard',
-]);
-
-const VALID_ACTION_TYPES = new Set([
-  'design_decision',
-  'dispatch_choice',
-  'validation_behavior',
-  'fix_loop_decision',
-  'scope_adjustment',
-  'blocked_exit',
-]);
-
-const MIN_REASON_CHARS = 20;
-
-// ═══════════════════════════════════════
-//  recall_id generation (TASK_1078)
-// ═══════════════════════════════════════
-
-/**
- * Generate a stable, unique recall ID.
- * Format: recall_<timestamp_ms>_<6-hex-chars>
- * Stable within the same millisecond window; globally unique enough to
- * cross-reference within a session log. Not a cryptographic guarantee.
- */
-function generateRecallId() {
-  const ts  = Date.now();
-  const rnd = crypto.randomBytes(3).toString('hex');
-  return `recall_${ts}_${rnd}`;
-}
-
-// ═══════════════════════════════════════
-//  Minimal YAML parser for memory_source_priority.yaml
-//  (same pattern as lesson-guard.js — no external deps)
-// ═══════════════════════════════════════
-
-let _priorityCache = null;
-
-/**
- * Parse the priority yaml into a JS object. We only implement the subset
- * needed to answer getPriorityRank() — nested maps with scalar leaves and
- * small lists. If the file is missing or unparseable we fall back to the
- * hard-coded defaults below.
- */
-function loadPriorityRules() {
-  if (_priorityCache) return _priorityCache;
-  const fallback = {
-    version: 1,
-    sources: {
-      user_session_context:     { priority_rank: 100, conflict_mode: 'strict' },
-      verified_decision_rune:   { priority_rank: 90,  conflict_mode: 'strict',   source_type: 'rune' },
-      session_handoff:          { priority_rank: 80,  conflict_mode: 'advisory', source_type: 'handoff' },
-      self_model_lesson:        { priority_rank: 70,  conflict_mode: 'advisory', source_type: 'self_model' },
-      risk_or_fix_rune:         { priority_rank: 60,  conflict_mode: 'strict',   source_type: 'rune' },
-      sigil:                    { priority_rank: 50,  conflict_mode: 'advisory', source_type: 'sigil' },
-      insight_or_pattern_rune:  { priority_rank: 40,  conflict_mode: 'advisory', source_type: 'rune' },
-      episode:                  { priority_rank: 30,  conflict_mode: 'advisory', source_type: 'episode' },
-      summary_or_ash_rune:      { priority_rank: 20,  conflict_mode: 'advisory', source_type: 'rune' },
-      lesson_guard:             { priority_rank: 10,  conflict_mode: 'advisory', source_type: 'lesson_guard' },
-    },
-    acted_on_weights: {
-      verified_decision_rune: 1.0, session_handoff: 1.0, self_model_lesson: 1.5,
-      risk_or_fix_rune: 1.2, sigil: 0.8, insight_or_pattern_rune: 0.7,
-      episode: 0.5, summary_or_ash_rune: 0.5, lesson_guard: 0.4,
-    },
-  };
-
-  if (!fs.existsSync(PRIORITY_PATH)) {
-    _priorityCache = fallback;
-    return _priorityCache;
-  }
-
-  try {
-    const raw = fs.readFileSync(PRIORITY_PATH, 'utf8');
-    const parsed = parsePriorityYaml(raw);
-    _priorityCache = parsed || fallback;
-    return _priorityCache;
-  } catch {
-    _priorityCache = fallback;
-    return _priorityCache;
-  }
-}
-
-function parsePriorityYaml(content) {
-  const out = { version: 1, sources: {}, acted_on_weights: {}, tie_breakers: [], acted_on_evidence_requirements: {} };
-  const lines = content.split('\n');
-
-  let section = null;       // 'sources' | 'weights' | 'tiebreakers' | 'evidence'
-  let currentSource = null;
-  let currentNested = null; // 'rune_filter' | 'allowed_action_types' | etc.
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-
-    // Top-level: version
-    const v = line.match(/^version:\s*(\d+)/);
-    if (v) { out.version = parseInt(v[1], 10); continue; }
-
-    // Top-level section markers
-    if (/^sources:\s*$/.test(line)) { section = 'sources'; currentSource = null; continue; }
-    if (/^acted_on_weights:\s*$/.test(line)) { section = 'weights'; currentSource = null; continue; }
-    if (/^tie_breakers:\s*$/.test(line)) { section = 'tiebreakers'; currentSource = null; continue; }
-    if (/^acted_on_evidence_requirements:\s*$/.test(line)) { section = 'evidence'; currentSource = null; continue; }
-
-    if (section === 'sources') {
-      // Source key: "  name_of_source:"
-      const srcMatch = line.match(/^ {2}([a-z_]+):\s*$/);
-      if (srcMatch) {
-        currentSource = srcMatch[1];
-        out.sources[currentSource] = {};
-        currentNested = null;
-        continue;
-      }
-      if (!currentSource) continue;
-
-      // Nested rune_filter block
-      if (/^ {4}rune_filter:\s*$/.test(line)) {
-        out.sources[currentSource].rune_filter = {};
-        currentNested = 'rune_filter';
-        continue;
-      }
-
-      // Scalar fields at 4-space indent
-      const scalarMatch = line.match(/^ {4}([a-z_]+):\s*(.+?)\s*$/);
-      if (scalarMatch && currentNested !== 'rune_filter') {
-        const key = scalarMatch[1];
-        let val = scalarMatch[2];
-        // Strip trailing "> description" multi-line block continuations
-        if (val === '>') {
-          // Gather subsequent indented lines
-          let buf = [];
-          while (i + 1 < lines.length && /^ {6}/.test(lines[i + 1])) {
-            buf.push(lines[++i].trim());
-          }
-          out.sources[currentSource][key] = buf.join(' ');
-          continue;
-        }
-        val = val.replace(/^"|"$/g, '');
-        if (/^-?\d+$/.test(val))        out.sources[currentSource][key] = parseInt(val, 10);
-        else if (/^-?\d+\.\d+$/.test(val)) out.sources[currentSource][key] = parseFloat(val);
-        else if (val === 'true' || val === 'false') out.sources[currentSource][key] = (val === 'true');
-        else out.sources[currentSource][key] = val;
-        continue;
-      }
-
-      // Inside rune_filter (6-space indent)
-      if (currentNested === 'rune_filter') {
-        const nested = line.match(/^ {6}([a-z_]+):\s*(.+?)\s*$/);
-        if (nested) {
-          const key = nested[1];
-          let val = nested[2];
-          if (/^\[.*\]$/.test(val)) {
-            val = val.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
-          } else if (/^-?\d+\.\d+$/.test(val)) {
-            val = parseFloat(val);
-          } else {
-            val = val.replace(/^"|"$/g, '');
-          }
-          out.sources[currentSource].rune_filter[key] = val;
-          continue;
-        }
-        // End of nested if indent decreases
-        if (/^ {4}[a-z_]/.test(line)) currentNested = null;
-      }
-    }
-
-    if (section === 'weights') {
-      const m = line.match(/^ {2}([a-z_]+):\s*([\d.]+)/);
-      if (m) out.acted_on_weights[m[1]] = parseFloat(m[2]);
-    }
-  }
-
-  return out;
-}
-
-/**
- * Return the priority tier that best matches a recalled item.
- *
- * descriptor = { source, rune_type?, confidence?, verified? }
- *
- * The match order is:
- *   - Exact source_type tiers first (rune/handoff/episode/...).
- *   - Within runes: match rune_filter (type + min_confidence + verified_not).
- *   - Highest priority_rank wins on tie.
- * Returns { rank, tier, mode } or null if no tier matched.
- */
-function getPriorityRank(descriptor) {
-  const rules = loadPriorityRules();
-  const source = descriptor && descriptor.source;
-  if (!source) return null;
-
-  const matches = [];
-  for (const [tierName, tier] of Object.entries(rules.sources)) {
-    if (tier.source_type && tier.source_type !== source) continue;
-    // For generic source tiers (no source_type), only match by name
-    if (!tier.source_type && tierName !== source) continue;
-
-    if (source === 'rune' && tier.rune_filter) {
-      const f = tier.rune_filter;
-      if (f.type && descriptor.rune_type !== f.type) continue;
-      if (f.type_in && Array.isArray(f.type_in) && !f.type_in.includes(descriptor.rune_type)) continue;
-      if (typeof f.min_confidence === 'number' && (descriptor.confidence || 0) < f.min_confidence) continue;
-      if (f.verified_not && descriptor.verified === f.verified_not) continue;
-    }
-
-    matches.push({ tier: tierName, rank: tier.priority_rank || 0, mode: tier.conflict_mode || 'advisory' });
-  }
-
-  if (matches.length === 0) return null;
-  matches.sort((a, b) => b.rank - a.rank);
-  return matches[0];
-}
-
-// ═══════════════════════════════════════
-//  Append-only JSONL writer
-// ═══════════════════════════════════════
-
-function ensureLogDir() {
-  const dir = path.dirname(LOG_PATH);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-}
-
-function appendEntry(entry) {
-  try {
-    ensureLogDir();
-    fs.appendFileSync(LOG_PATH, JSON.stringify(entry) + '\n', 'utf8');
-    return { ok: true };
-  } catch (e) {
-    return { ok: false, error: e.message };
-  }
-}
-
-// ═══════════════════════════════════════
-//  recordRecall — module entry point
-// ═══════════════════════════════════════
-
-/**
- * Record a "memory was recalled into context" event.
- *
- * Minimal required fields: { source, source_id, task_id }
- * Accepted fields: phase, reason, rune_type, confidence, verified
- *
- * Does NOT enforce min-reason-chars — recall events are cheap, we log
- * everything. Action events have the stricter gate.
- *
- * Returns { ok, recall_id, line? } — recall_id is the stable ID for this
- * event, which can be passed into later recordActedOn calls via recalled_from_ids.
- */
-function recordRecall(input) {
-  if (!input || typeof input !== 'object') {
-    return { ok: false, error: 'input must be an object' };
-  }
-  const { source, source_id: sourceId, task_id: taskId } = input;
-
-  if (!VALID_SOURCES.has(source)) {
-    return { ok: false, error: `invalid source '${source}' (expected one of: ${[...VALID_SOURCES].join(', ')})` };
-  }
-  if (!sourceId) return { ok: false, error: 'source_id is required' };
-  if (!taskId)   return { ok: false, error: 'task_id is required' };
-
-  const prio = getPriorityRank({
-    source,
-    rune_type: input.rune_type || null,
-    confidence: input.confidence || null,
-    verified: input.verified || null,
-  });
-
-  const recallId = generateRecallId();
-
-  const entry = {
-    timestamp: new Date().toISOString(),
-    event: 'recall',
-    recall_id: recallId,
-    source,
-    source_id: String(sourceId),
-    task_id: String(taskId),
-    phase: Number.isFinite(input.phase) ? input.phase : null,
-    action_type: null,
-    reason: input.reason ? String(input.reason) : null,
-    conflict_with: null,
-    priority_rank: prio ? prio.rank : null,
-    priority_tier: prio ? prio.tier : null,
-    conflict_mode: prio ? prio.mode : null,
-    recalled_from_ids: [],
-  };
-
-  const write = appendEntry(entry);
-  if (!write.ok) return write;
-  return { ok: true, recall_id: recallId, line: entry };
-}
-
-// ═══════════════════════════════════════
-//  recordActedOn — module entry point
-// ═══════════════════════════════════════
-
-/**
- * Record a "recalled memory influenced a concrete decision" event.
- *
- * Required: { source, source_id, task_id, action_type, reason }
- * Optional: recalled_from_ids (array of recall_ids from prior recordRecall calls
- *           that directly led to this decision — enables linking recall→action)
- * reason must be >= MIN_REASON_CHARS to filter out rubber-stamping.
- *
- * Side effects:
- *   - Appends to memory_action_log.jsonl
- *   - If source=lesson_guard and source_id matches /^L-\d+$/, also calls
- *     lesson-guard.js recordActedOn() so the legacy per-guard counter and
- *     lesson_guard_acted_on.jsonl stay in sync.
- *   - If source=rune, the Synapse rune_usage_log acted_on bit should be
- *     set by the caller via synapse_inscribe related_rune_ids. We do NOT
- *     attempt a direct HTTP call here because the MCP layer is outside
- *     this tool's scope — we rely on the caller having already done it
- *     when they inscribed the follow-up rune. If they have not, our log
- *     still captures the event for reporting.
- */
-function recordActedOn(input) {
-  if (!input || typeof input !== 'object') {
-    return { ok: false, error: 'input must be an object' };
-  }
-  const { source, source_id: sourceId, task_id: taskId, action_type: actionType, reason } = input;
-
-  if (!VALID_SOURCES.has(source)) {
-    return { ok: false, error: `invalid source '${source}'` };
-  }
-  if (!sourceId) return { ok: false, error: 'source_id is required' };
-  if (!taskId)   return { ok: false, error: 'task_id is required' };
-  if (!VALID_ACTION_TYPES.has(actionType)) {
-    return { ok: false, error: `invalid action_type '${actionType}' (expected one of: ${[...VALID_ACTION_TYPES].join(', ')})` };
-  }
-  if (!reason || String(reason).trim().length < MIN_REASON_CHARS) {
-    return { ok: false, error: `reason must be >= ${MIN_REASON_CHARS} chars (got ${reason ? String(reason).length : 0})` };
-  }
-
-  const prio = getPriorityRank({
-    source,
-    rune_type: input.rune_type || null,
-    confidence: input.confidence || null,
-    verified: input.verified || null,
-  });
-
-  // recalled_from_ids: array of recall_id strings that led to this decision
-  const recalledFromIds = Array.isArray(input.recalled_from_ids)
-    ? input.recalled_from_ids.filter(id => typeof id === 'string' && id.startsWith('recall_'))
-    : [];
-
-  const entry = {
-    timestamp: new Date().toISOString(),
-    event: 'acted_on',
-    recall_id: generateRecallId(),   // stable ID for this acted_on event too
-    source,
-    source_id: String(sourceId),
-    task_id: String(taskId),
-    phase: Number.isFinite(input.phase) ? input.phase : null,
-    action_type: actionType,
-    reason: String(reason),
-    conflict_with: input.conflict_with || null,
-    priority_rank: prio ? prio.rank : null,
-    priority_tier: prio ? prio.tier : null,
-    conflict_mode: prio ? prio.mode : null,
-    recalled_from_ids: recalledFromIds,
-  };
-
-  const write = appendEntry(entry);
-  if (!write.ok) return write;
-
-  // Bridge to lesson-guard.js for L-XXX guards so the two logs agree.
-  if (source === 'lesson_guard' && /^L-\d+$/.test(String(sourceId))) {
-    try {
-      const lg = require(LESSON_GUARD_JS);
-      if (lg && typeof lg.recordActedOn === 'function') {
-        lg.recordActedOn(String(sourceId), String(taskId), String(reason));
-      }
-    } catch { /* graceful degradation */ }
-  }
-
-  return { ok: true, line: entry };
-}
-
-/**
- * Batch helper used by phase-gate.js exit. Accepts an array of items the
- * specialist reports as having influenced the current phase's decisions,
- * records them all, and returns per-item status.
- *
- * Input shape:
- *   items  = [{ source, source_id, action_type, reason, phase?, rune_type?,
- *              recalled_from_ids?: string[] }]
- *   taskId = string
- *   phase  = int (default applied to items lacking phase)
- */
-function recordActedOnBatch(items, taskId, phase) {
-  const result = { recorded: 0, failed: [] };
-  if (!Array.isArray(items) || items.length === 0) return result;
-  for (const raw of items) {
-    if (!raw || typeof raw !== 'object') {
-      result.failed.push({ item: raw, error: 'not an object' });
-      continue;
-    }
-    const item = Object.assign({ task_id: taskId, phase }, raw);
-    const r = recordActedOn(item);
-    if (r.ok) result.recorded += 1;
-    else result.failed.push({ item, error: r.error });
-  }
-  return result;
-}
-
-// ═══════════════════════════════════════
-//  listRecalls — session recall registry (TASK_1078)
-// ═══════════════════════════════════════
-
-/**
- * Return all recall events for a given task_id, optionally filtered by phase.
- * Useful for an agent to enumerate recall_ids that can be passed into
- * recordActedOn calls when linking decisions back to the recalls that shaped them.
- *
- * Returns array of recall entries (event='recall') sorted by timestamp ascending.
- * Graceful on missing log (returns empty array).
- */
-function listRecalls(taskId, phase) {
-  if (!taskId) return [];
-  if (!fs.existsSync(LOG_PATH)) return [];
-
-  let raw;
-  try { raw = fs.readFileSync(LOG_PATH, 'utf8'); }
-  catch { return []; }
-
-  const results = [];
-  for (const line of raw.split('\n')) {
-    if (!line.trim()) continue;
-    let entry;
-    try { entry = JSON.parse(line); } catch { continue; }
-    if (!entry || entry.event !== 'recall') continue;
-    if (entry.task_id !== String(taskId)) continue;
-    if (phase !== undefined && entry.phase !== phase) continue;
-    results.push(entry);
-  }
-  return results;
-}
-
-// ═══════════════════════════════════════
-//  Metrics / report
-// ═══════════════════════════════════════
-
-/**
- * Stream the jsonl log and aggregate recall-vs-impact counters.
- * Graceful on missing log (returns zeroed report).
- *
- * opts = { windowDays?: number, taskId?: string }
- * returns:
- *   {
- *     window_days, task_id, total_recalls, total_acted_on,
- *     impact_rate, weighted_impact_score,
- *     linked_acts,      // acted_on events with non-empty recalled_from_ids
- *     link_rate,        // linked_acts / total_acted_on (traceability)
- *     by_source: {
- *       <source>: { recalls, acted_on, impact_rate, weighted_score, linked_acts }
- *     },
- *     by_action_type: { <action>: count },
- *     unique_items_recalled: N,
- *     unique_items_acted_on: N
- *   }
- */
-function getMetrics(opts = {}) {
-  const windowDays = Number.isFinite(opts.windowDays) ? opts.windowDays : 30;
-  const taskFilter = opts.taskId || null;
-  const cutoff = Date.now() - windowDays * 86400 * 1000;
-
-  const report = {
-    window_days: windowDays,
-    task_id: taskFilter,
-    total_recalls: 0,
-    total_acted_on: 0,
-    impact_rate: 0,
-    weighted_impact_score: 0,
-    linked_acts: 0,
-    link_rate: 0,
-    by_source: {},
-    by_action_type: {},
-    unique_items_recalled: 0,
-    unique_items_acted_on: 0,
-  };
-
-  if (!fs.existsSync(LOG_PATH)) return report;
-
-  const rules = loadPriorityRules();
-  const weights = rules.acted_on_weights || {};
-  const recalledSet = new Set();
-  const actedSet    = new Set();
-
-  let raw;
-  try { raw = fs.readFileSync(LOG_PATH, 'utf8'); }
-  catch { return report; }
-
-  for (const line of raw.split('\n')) {
-    if (!line.trim()) continue;
-    let entry;
-    try { entry = JSON.parse(line); } catch { continue; }
-    if (!entry || !entry.source) continue;
-
-    const ts = Date.parse(entry.timestamp || '');
-    if (!Number.isFinite(ts) || ts < cutoff) continue;
-    if (taskFilter && entry.task_id !== taskFilter) continue;
-
-    const srcBucket = report.by_source[entry.source] || {
-      recalls: 0, acted_on: 0, impact_rate: 0, weighted_score: 0, linked_acts: 0,
-    };
-    const key = `${entry.source}:${entry.source_id}`;
-
-    if (entry.event === 'recall') {
-      report.total_recalls += 1;
-      srcBucket.recalls += 1;
-      recalledSet.add(key);
-    } else if (entry.event === 'acted_on') {
-      report.total_acted_on += 1;
-      srcBucket.acted_on += 1;
-      actedSet.add(key);
-      if (entry.action_type) {
-        report.by_action_type[entry.action_type] = (report.by_action_type[entry.action_type] || 0) + 1;
-      }
-      // linked_acts: this acted_on was explicitly traced to prior recall events
-      if (Array.isArray(entry.recalled_from_ids) && entry.recalled_from_ids.length > 0) {
-        report.linked_acts += 1;
-        srcBucket.linked_acts += 1;
-      }
-      // Weighted score: use the tier weight if available, else source weight, else 1.0.
-      const tierWeight = entry.priority_tier && weights[entry.priority_tier];
-      const srcWeight  = weights[entry.source];
-      const w = Number.isFinite(tierWeight) ? tierWeight
-              : Number.isFinite(srcWeight)  ? srcWeight
-              : 1.0;
-      report.weighted_impact_score += w;
-      srcBucket.weighted_score += w;
-    }
-
-    report.by_source[entry.source] = srcBucket;
-  }
-
-  report.unique_items_recalled = recalledSet.size;
-  report.unique_items_acted_on = actedSet.size;
-  report.impact_rate = report.total_recalls > 0
-    ? +(report.total_acted_on / report.total_recalls).toFixed(4)
-    : 0;
-  report.link_rate = report.total_acted_on > 0
-    ? +(report.linked_acts / report.total_acted_on).toFixed(4)
-    : 0;
-
-  for (const src of Object.keys(report.by_source)) {
-    const b = report.by_source[src];
-    b.impact_rate = b.recalls > 0 ? +(b.acted_on / b.recalls).toFixed(4) : 0;
-    b.weighted_score = +b.weighted_score.toFixed(3);
-  }
-  report.weighted_impact_score = +report.weighted_impact_score.toFixed(3);
-
-  return report;
-}
-
-// ═══════════════════════════════════════
-//  CLI
-// ═══════════════════════════════════════
-
-function parseArgs(argv) {
-  const args = { _: [] };
-  for (const arg of argv.slice(2)) {
-    const m = arg.match(/^--([^=]+)(?:=(.*))?$/);
-    if (m) args[m[1]] = m[2] !== undefined ? m[2] : true;
-    else args._.push(arg);
-  }
-  return args;
-}
-
-function cmdRecordRecall(args) {
-  const entry = {
-    source:     args.source,
-    source_id:  args['source-id'],
-    task_id:    args.task,
-    phase:      args.phase !== undefined ? parseInt(args.phase, 10) : null,
-    reason:     args.reason || null,
-    rune_type:  args['rune-type'] || null,
-    confidence: args.confidence !== undefined ? parseFloat(args.confidence) : null,
-    verified:   args.verified || null,
-  };
-  const r = recordRecall(entry);
-  if (!r.ok) { console.error(JSON.stringify(r)); process.exit(1); }
-  console.log(JSON.stringify(r, null, 2));
-}
-
-function cmdRecordActed(args) {
-  // --recalled-from=id1,id2,id3 → array
-  const recalledFrom = args['recalled-from']
-    ? String(args['recalled-from']).split(',').map(s => s.trim()).filter(Boolean)
-    : [];
-
-  const entry = {
-    source:            args.source,
-    source_id:         args['source-id'],
-    task_id:           args.task,
-    phase:             args.phase !== undefined ? parseInt(args.phase, 10) : null,
-    action_type:       args['action-type'],
-    reason:            args.reason || '',
-    rune_type:         args['rune-type'] || null,
-    confidence:        args.confidence !== undefined ? parseFloat(args.confidence) : null,
-    conflict_with:     args['conflict-with'] || null,
-    recalled_from_ids: recalledFrom,
-  };
-  const r = recordActedOn(entry);
-  if (!r.ok) { console.error(JSON.stringify(r)); process.exit(1); }
-  console.log(JSON.stringify(r, null, 2));
-}
-
-function cmdReport(args) {
-  const windowDays = args['window-days'] !== undefined ? parseInt(args['window-days'], 10) : 30;
-  const taskId = args.task || null;
-  const report = getMetrics({ windowDays, taskId });
-  if (args.json) {
-    console.log(JSON.stringify(report, null, 2));
-    return;
-  }
-  // Plain report
-  const lines = [];
-  lines.push(`Memory-to-Action report  (window: ${windowDays}d${taskId ? `, task: ${taskId}` : ''})`);
-  lines.push('');
-  lines.push(`  total_recalls:          ${report.total_recalls}`);
-  lines.push(`  total_acted_on:         ${report.total_acted_on}`);
-  lines.push(`  impact_rate:            ${(report.impact_rate * 100).toFixed(1)}%`);
-  lines.push(`  weighted_impact_score:  ${report.weighted_impact_score}`);
-  lines.push(`  linked_acts:            ${report.linked_acts}  (acted_on events with explicit recall linkage)`);
-  lines.push(`  link_rate:              ${(report.link_rate * 100).toFixed(1)}%  (traceability: linked_acts / total_acted_on)`);
-  lines.push(`  unique_items_recalled:  ${report.unique_items_recalled}`);
-  lines.push(`  unique_items_acted_on:  ${report.unique_items_acted_on}`);
-  lines.push('');
-  lines.push('  by source:');
-  const sources = Object.keys(report.by_source).sort();
-  if (sources.length === 0) lines.push('    (none)');
-  for (const src of sources) {
-    const b = report.by_source[src];
-    lines.push(`    ${src.padEnd(14)} recalls=${String(b.recalls).padStart(4)}  acted_on=${String(b.acted_on).padStart(4)}  rate=${(b.impact_rate * 100).toFixed(1).padStart(5)}%  linked=${b.linked_acts}  weight=${b.weighted_score}`);
-  }
-  lines.push('');
-  lines.push('  by action_type:');
-  const types = Object.keys(report.by_action_type).sort();
-  if (types.length === 0) lines.push('    (none)');
-  for (const t of types) lines.push(`    ${t.padEnd(22)} ${report.by_action_type[t]}`);
-  console.log(lines.join('\n'));
-}
-
-function cmdPriority(args) {
-  const rank = getPriorityRank({
-    source:     args['source-type'] || args.source,
-    rune_type:  args.type || args['rune-type'],
-    confidence: args.confidence !== undefined ? parseFloat(args.confidence) : null,
-    verified:   args.verified || null,
-  });
-  console.log(JSON.stringify({ ok: true, ...(rank || { rank: null, tier: null, mode: null }) }, null, 2));
-}
-
-function cmdListRecalls(args) {
-  const taskId = args.task;
-  const phase  = args.phase !== undefined ? parseInt(args.phase, 10) : undefined;
-  if (!taskId) { console.error(JSON.stringify({ error: '--task is required' })); process.exit(1); }
-  const recalls = listRecalls(taskId, phase);
-  if (args.json) {
-    console.log(JSON.stringify(recalls, null, 2));
-    return;
-  }
-  if (recalls.length === 0) {
-    console.log(`No recall events found for task=${taskId}${phase !== undefined ? `, phase=${phase}` : ''}`);
-    return;
-  }
-  console.log(`Recall events for task=${taskId}${phase !== undefined ? `, phase=${phase}` : ''} (${recalls.length} total):`);
-  for (const r of recalls) {
-    const phaseStr = r.phase !== null ? `  phase=${r.phase}` : '';
-    console.log(`  ${r.recall_id}  source=${r.source}:${r.source_id}${phaseStr}`);
-  }
-}
-
-// ═══════════════════════════════════════
-//  Module exports
-// ═══════════════════════════════════════
-
-module.exports = {
-  recordRecall,
-  recordActedOn,
-  recordActedOnBatch,
-  getMetrics,
-  listRecalls,
-  getPriorityRank,
-  loadPriorityRules,
-  // internal paths exported for tests
-  _LOG_PATH: LOG_PATH,
-  _PRIORITY_PATH: PRIORITY_PATH,
-  _VALID_SOURCES: VALID_SOURCES,
-  _VALID_ACTION_TYPES: VALID_ACTION_TYPES,
-  _MIN_REASON_CHARS: MIN_REASON_CHARS,
-};
-
-// ═══════════════════════════════════════
-//  CLI entry point
-// ═══════════════════════════════════════
-
-if (require.main === module) {
-  const args = parseArgs(process.argv);
-  const cmd  = args._[0];
-  switch (cmd) {
-    case 'record-recall': cmdRecordRecall(args); break;
-    case 'record-acted':  cmdRecordActed(args);  break;
-    case 'report':        cmdReport(args);       break;
-    case 'priority':      cmdPriority(args);     break;
-    case 'list-recalls':  cmdListRecalls(args);  break;
-    default:
-      console.error([
-        'Usage: memory-action-log.js <command> [options]',
-        '',
-        'Commands:',
-        '  record-recall --source=<src> --source-id=<id> --task=TASK_XXX',
-        '                [--phase=N] [--reason="text"]',
-        '                [--rune-type=<type>] [--confidence=0.85] [--verified=<state>]',
-        '                Returns: { ok, recall_id } — save recall_id for later linkage',
-        '',
-        '  record-acted  --source=<src> --source-id=<id> --task=TASK_XXX',
-        '                --action-type=<type> --reason="why this recall changed the plan (>=20 chars)"',
-        '                [--phase=N] [--conflict-with=<other_source_id>]',
-        '                [--recalled-from=recall_id1,recall_id2,...]',
-        '',
-        '  list-recalls  --task=TASK_XXX [--phase=N] [--json]',
-        '                List all recall events for a task (shows recall_ids for linkage)',
-        '',
-        '  report        [--window-days=30] [--task=TASK_XXX] [--json]',
-        '',
-        '  priority      --source-type=<src> [--type=<rune_type>] [--confidence=N] [--verified=<state>]',
-        '',
-        'Sources:',
-        `  ${[...VALID_SOURCES].join(', ')}`,
-        '',
-        'Action types:',
-        `  ${[...VALID_ACTION_TYPES].join(', ')}`,
-        '',
-        'Contract: .kenaz/specialist/memory_source_priority.yaml',
-        'Log:      .kenaz/specialist/memory_action_log.jsonl',
-      ].join('\n'));
-      process.exit(1);
-  }
-}