kenaz 0.3.10 → 0.3.12

package/core/.specialist/tools/MEMORY_RECALL_TRIGGERS.md

@@ -1,156 +0,0 @@
-# Memory Recall Trigger Map (TASK_1077)
-
-Canonical mapping of specialist decision points to required recall operations,
-source types, and conflict resolution. This document is the authoritative trigger
-contract. Telemetry instrumentation (`memory-action-log.js`, `acted_on` events)
-is built on top of this contract by TASK_1072 — do not mix the layers.
-
-**Machine-consumable counterpart:**
-`.kenaz/specialist/memory_source_priority.yaml`
-
-**Rule enforcement:**
-`.rule/general/memory-source-priority.yaml` (MSP-001 through MSP-005)
-
----
-
-## Core Principle
-
-> Memory is only valuable when it changes a decision.
-
-Every recall call has a **decision point** on the other side. If you cannot
-name the decision the recall will inform, you are loading context for show.
-The trigger map below makes this concrete: for each phase or moment, it
-specifies _what_ to recall, _from which source_, and _what happens next_.
-
----
-
-## Trigger Map
-
-| Phase / Moment | Tool | Sources Surfaced | Required vs Optional | Conflict Mode |
-|---|---|---|---|---|
-| **Phase 0 — Boot** | `cortex_recall(type=ash, limit=5)` | `summary_or_ash_rune` | Required | advisory |
-| **Phase 0 — Boot** | `synapse_sigils(projectPath)` | `sigil` | Required | advisory |
-| **Phase 0 — Boot** | `hippocampus_episode_recall(limit=3)` | `episode`, `session_handoff` | Conditional (prior session exists) | advisory |
-| **Phase 0 — Boot** | Read `ansuz_self_model.json` | `self_model_lesson` | Required | advisory |
-| **Phase 0 — Boot** | Auto-load handoff slot | `session_handoff` | Conditional (fatigue_warning in prior session) | advisory |
-| **Phase 1 — Requirements** | `synapse_recall(query=task_title+scope)` | `insight_or_pattern_rune`, `risk_or_fix_rune`, `episode` | Required | advisory |
-| **Before editing a symbol** | `synapse_recall(symbol_name)` + `kenaz_lsp_callers` | `risk_or_fix_rune`, `verified_decision_rune` | Required (non-trivial changes) | strict (risk/fix) |
-| **Phase 3 — Decomposition** | `kenaz_lsp_callers(scope symbols)` | `risk_or_fix_rune`, `sigil` | Required | strict (risk/fix) |
-| **Phase 8 — Dispatch** | `synapse_recall(dispatch patterns)` | `sigil`, `self_model_lesson`, `session_handoff` | Optional | advisory |
-| **Phase 9 — Verification** | `git diff --stat` + `synapse_recall(symbols)` | `risk_or_fix_rune`, `sigil` | Required | strict (risk) |
-| **Retry / Bail decision** | `synapse_recall(error signature)` | `risk_or_fix_rune`, `episode` | Required | strict (fix) |
-| **Phase-gate blocked exit** | `lesson_guards` auto-surfaced | `lesson_guard`, `session_handoff` | Auto (phase-gate handles) | advisory |
-
-### Conditional triggers (detail)
-
-- **Handoff load (Phase 0):** Only if a per-session slot exists under
-  `.kenaz/specialist/handoffs/` (newest `generated_at` wins — resolved via
-  `handoff-resolver.js readLatestHandoff`; the legacy singular
-  `ansuz_session_handoff.json` is retired read-only fallback, M3/TASK_1760)
-  AND its `generated_at` timestamp is within the `ttl_hours: 72` window. Stale handoffs
-  are ignored (they contain context from a cycle too far in the past).
-
-- **Episode recall (Phase 0):** Only when `hippocampus_episode_recall` returns ≥ 1 result.
-  If the project has no episodes yet (cold start), skip silently — do not error.
-
-- **Phase 1 deep episode drill:** If Phase 0 episode summary mentions a `task_id` relevant
-  to current requirements, call `hippocampus_episode_recall(task_id=that_id)` to get full entries.
-
-- **synapse_recall before edit:** May skip for trivial changes (config value, typo, < 5 lines).
-  Judgment required. If skipping, note it explicitly (FAIL-009 records past recall-skips that
-  caused regressions; pulse itself is retired, recall is the replacement).
-
----
-
-## Decision-Point Checklist
-
-Before a recalled item can be treated as **acted-on** (influencing a decision),
-confirm all three:
-
-1. **Name the specific recalled item.**
-   `source_id` = rune_id, episode_id, sigil_id, guard id (L-XXX), blind-spot id (B-XXX),
-   handoff `session_id`, or self_model `growth` entry hash.
-
-2. **The recall changed what you were about to do.**
-   State the "before" plan and the "after" plan in one sentence each. If the plan
-   did not change, the recall is informational only — still worth noting, but not acted-on.
-
-3. **The reason explains the delta, not the lookup.**
-   "Recalled L-003" is not evidence.
-   "L-003 flagged scope expansion requires a sub-task — created TASK_1077.1" is evidence.
-
----
-
-## Conflict Resolution Contract
-
-When two sources disagree (e.g. an episode says "retry", a rune says "bail"):
-
-1. Apply `priority_rank` from `memory_source_priority.yaml` — higher rank wins.
-2. If same rank: apply `tie_breakers` in order (confidence DESC → freshness ASC → source_id ASC).
-3. Apply the winner's `conflict_mode`:
-   - **strict** → hide the loser from the agent; log with `conflict_with: <winner_source_id>`
-   - **advisory** → show both; label the loser as "competing view (rank: N)"
-4. If the agent disagrees with the winner's guidance, it must document the override reason
-   before proceeding (no silent overrides).
-
-### Conflict examples
-
-| Winner | Loser | Mode | What happens |
-|---|---|---|---|
-| `risk_or_fix_rune` (rank 60) | `episode` (rank 30) says "proceed" | strict | Agent follows rune; episode suppressed; override requires user statement |
-| `session_handoff` (rank 80) | `insight_or_pattern_rune` (rank 40) | advisory | Both surfaced; agent chooses with documented reason |
-| `verified_decision_rune` (rank 90) | `self_model_lesson` (rank 70) | strict | Agent follows decision rune; self-model view logged only |
-
----
-
-## Anti-Patterns
-
-| Pattern | Why it fails |
-|---|---|
-| Recalling every source at every phase | Phase 0 boot cost grows unbounded; irrelevant context degrades signal |
-| Skipping recall at phase boundaries | Misses the decision point; FAIL-009 shows this causes regressions |
-| Treating lesson_guards as primary evidence | They are the *lowest* rank (10); trace back to the originating rune/episode |
-| Loading Phase 0 handoff even when > 72h old | Stale handoffs inject obsolete context; TTL exists for this reason |
-| "Recalling" from a source not actually queried | Incoherent audit trail; metrics show recall=0 / acted_on=1 |
-
----
-
-## Minimal Integration Contract for New Specialists
-
-A specialist flow integrating with this system needs exactly two behaviors:
-
-1. **At each trigger boundary** (see Trigger Map above), call the listed tool.
-   Pass `projectPath` to every Synapse/Hippocampus call — omitting it causes
-   multi-session collision on the global default project.
-
-2. **When a recalled item changes a decision**, mark it as acted-on via the
-   `memory_acted_on` field on phase-gate exit OR via `memory-action-log.js`
-   `recordActedOn()` directly (TASK_1072 adds this layer).
-
-Both behaviors are independently useful: #1 is the contract defined here;
-#2 is observability added by TASK_1072. Do not depend on #2 being present.
-
----
-
-## Rule References
-
-| Rule | File | Scope |
-|---|---|---|
-| MSP-001 through MSP-005 | `.rule/general/memory-source-priority.yaml` | Priority ordering, conflict modes, required triggers |
-| SYN-001 through SYN-007 | `.rule/general/synapse-code-intelligence.yaml` | Which Synapse tool at which moment |
-| SYN-008 through SYN-011 | `.rule/general/synapse-cognitive-fusion.yaml` | When to promote recalled patterns to runes/sigils |
-| MEM-LANG-001 | `.rule/general/memory-language.yaml` | All memory writes must be in English |
-| DDx stack | `.rule/general/ddx-synapse-stack.yaml` | Recall before writing code (pulse-or-recall gate) |
-
----
-
-## File Locations
-
-| File | Purpose |
-|---|---|
-| `.kenaz/specialist/memory_source_priority.yaml` | Machine-consumable priority + conflict contract |
-| `.specialist/tools/MEMORY_RECALL_TRIGGERS.md` | This file — human-readable trigger map |
-| `.specialist/tools/memory-action-log.js` | Telemetry layer (TASK_1072) — `recordRecall` / `recordActedOn` |
-| `.specialist/Ansuz/modules/recall.yaml` | Ansuz-specific recall protocol (Tier 1/2/3 boot sequence) |
-| `.specialist/Ansuz/guards/lesson_guards.yaml` | L-XXX lesson guards surfaced by phase-gate |
-| `.kenaz/specialist/memory_action_log.jsonl` | Append-only event log (TASK_1072) |

package/core/.specialist/tools/context-injection.js

@@ -1,395 +0,0 @@
-#!/usr/bin/env node
-/**
- * context-injection.js
- * Phase-Aware Synapse 注入工具
- *
- * 根據當前 phase 輸出具體的 Synapse 查詢建議，把「執行 synapse_recall」
- * 從模糊提醒變成具體查詢目標。
- *
- * CLI:
- *   node .specialist/tools/context-injection.js --phase=N --task=TASK_XXX [--project-path=PATH]
- *
- * Output: JSON to stdout
- *   { phase, task_id, synapse_suggestions: { ... } }
- *
- * Exit codes:
- *   0 = success (including graceful degradation)
- *   1 = task not found or fatal error
- */
-
-'use strict';
-
-const path = require('path');
-const fs = require('fs');
-const { execSync } = require('child_process');
-
-// ═══════════════════════════════════════
-//  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 TASK_API = path.join(BASE_DIR, '.collaboration', 'core', 'task-api.js');
-// TASK_2163: chart files are keyed by project identity + task id (sub-projects
-// reuse bare TASK_ ids and previously collided in the flat core sessions dir).
-const chartPathLib = require('./lib/chart-path');
-
-// ═══════════════════════════════════════
-//  CLI arg parsing
-// ═══════════════════════════════════════
-
-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;
-  }
-  return args;
-}
-
-// ═══════════════════════════════════════
-//  Task loading via task-api.js
-// ═══════════════════════════════════════
-
-function loadTask(taskId, projectPath) {
-  const ppFlag = projectPath ? ` --project-path="${projectPath}"` : '';
-  const cmd = `node "${TASK_API}" get ${taskId}${ppFlag}`;
-  try {
-    const raw = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
-    return JSON.parse(raw.trim());
-  } catch (err) {
-    // task-api exits non-zero when not found, or JSON parse fails
-    return null;
-  }
-}
-
-// ═══════════════════════════════════════
-//  Chart loading
-// ═══════════════════════════════════════
-
-function loadChart(taskId, projectPath) {
-  const chartPath = chartPathLib.getChartReadPath(taskId, projectPath ? { projectPath } : {});
-  try {
-    const raw = fs.readFileSync(chartPath, 'utf8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-// ═══════════════════════════════════════
-//  Symbol name inference
-// ═══════════════════════════════════════
-
-const GENERIC_FILENAMES = new Set(['mod', 'index', 'main', 'lib', 'utils', 'helpers', 'types', 'constants']);
-
-function inferSymbolName(scopePath) {
-  // Normalize slashes
-  const normalized = scopePath.replace(/\\/g, '/');
-  const parts = normalized.split('/').filter(Boolean);
-  if (parts.length === 0) return null;
-
-  const lastPart = parts[parts.length - 1];
-  const stem = lastPart.replace(/\.[^.]+$/, ''); // remove extension
-
-  const nameSource = GENERIC_FILENAMES.has(stem) && parts.length >= 2
-    ? parts[parts.length - 2].replace(/\.[^.]+$/, '')
-    : stem;
-
-  // underscore_case or kebab-case → PascalCase
-  return nameSource
-    .split(/[_\-]/)
-    .filter(Boolean)
-    .map(s => s.charAt(0).toUpperCase() + s.slice(1))
-    .join('');
-}
-
-function inferSymbolsFromPaths(scopePaths) {
-  if (!scopePaths || scopePaths.length === 0) return [];
-  return scopePaths
-    .map(inferSymbolName)
-    .filter(Boolean)
-    .filter((v, i, a) => a.indexOf(v) === i); // deduplicate
-}
-
-// ═══════════════════════════════════════
-//  Research notes token extraction (Phase 3)
-// ═══════════════════════════════════════
-
-function extractFilePathTokens(text) {
-  if (!text) return [];
-  // Matches words containing / or . (file-path-like tokens)
-  const matches = text.match(/\b[\w\-]+[./][\w\-./]+\b/g) || [];
-  return matches
-    .filter(t => !t.match(/^\d+\.\d+/)) // skip version numbers like 1.2.3
-    .filter((v, i, a) => a.indexOf(v) === i);
-}
-
-function extractResearchNoteTokens(chart) {
-  if (!chart) return [];
-  const notes = chart?.history?.research_notes || '';
-  const text = Array.isArray(notes) ? notes.join(' ') : String(notes);
-  return extractFilePathTokens(text);
-}
-
-// ═══════════════════════════════════════
-//  Phase handlers
-// ═══════════════════════════════════════
-
-function buildPhase1Suggestions(task) {
-  const scopePaths = task.scope_paths || [];
-  const tags = task.tags || [];
-  const description = task.description || task.title || '';
-
-  // Extract keywords: tags + meaningful words from description
-  const descWords = description
-    .toLowerCase()
-    .replace(/[^\w\s\-_]/g, ' ')
-    .split(/\s+/)
-    .filter(w => w.length >= 4 && !STOPWORDS.has(w));
-
-  const keywords = [...new Set([...tags, ...descWords])].slice(0, 10);
-
-  const query = keywords.join(' ') || task.title || task.id;
-
-  return {
-    recall_query: query,
-    recall_keywords: keywords,
-    hint: scopePaths.length === 0
-      ? 'No scope_paths defined — using description/tags as recall seeds'
-      : `Recall before touching: ${scopePaths.join(', ')}`,
-  };
-}
-
-function buildPhase2Suggestions(task) {
-  const scopePaths = task.scope_paths || [];
-  if (scopePaths.length === 0) {
-    return {
-      pulse_targets: [],
-      hint: 'scope_paths is empty - Grep/Glob for the task title keywords, then synapse_recall on what you find',
-      fallback_query: task.title || task.id,
-    };
-  }
-  const pulseTargets = inferSymbolsFromPaths(scopePaths);
-  return {
-    pulse_targets: pulseTargets,
-    scope_paths: scopePaths,
-    hint: 'synapse_recall on scope_paths-inferred targets: '
-      + (pulseTargets.length > 0 ? pulseTargets.join(', ') : 'Grep/Glob the scope_paths filenames first'),
-  };
-}
-
-function buildPhase3Suggestions(task, chart) {
-  const scopePaths = task.scope_paths || [];
-  const fromPaths = inferSymbolsFromPaths(scopePaths);
-  const fromNotes = extractResearchNoteTokens(chart);
-
-  // Combine: path-derived symbols + file-path-like tokens from research notes
-  const impactTargets = [...fromPaths, ...fromNotes]
-    .filter((v, i, a) => a.indexOf(v) === i);
-
-  return {
-    impact_targets: impactTargets,
-    scope_paths: scopePaths,
-    research_note_tokens: fromNotes,
-    hint: impactTargets.length > 0
-      ? `Run kenaz_lsp_callers for each: ${impactTargets.join(', ')}`
-      : 'No impact targets inferred - Grep the scope_paths filenames, then kenaz_lsp_callers on the symbols found',
-  };
-}
-
-function buildPhase9Suggestions(task) {
-  const scopePaths = task.scope_paths || [];
-  return {
-    detect_changes_scope: scopePaths,
-    hint: scopePaths.length === 0
-      ? 'scope_paths is empty - review the full diff with git diff --stat'
-      : `Review the diff for: ${scopePaths.join(', ')} (git diff --stat -- <paths>), then synapse_recall on the touched symbols`,
-  };
-}
-
-// ═══════════════════════════════════════
-//  Recall telemetry (TASK_1078)
-// ═══════════════════════════════════════
-
-/**
- * Per-phase source types to emit recall telemetry for.
- * Derived from .kenaz/specialist/memory_source_priority.yaml phase_bindings.
- * Each entry: { source, rune_type?, label }
- */
-const PHASE_RECALL_SOURCES = {
-  1: [
-    { source: 'rune',  rune_type: 'insight',  label: 'insight_or_pattern_rune' },
-    { source: 'rune',  rune_type: 'pattern',  label: 'insight_or_pattern_rune' },
-    { source: 'sigil',                         label: 'sigil' },
-  ],
-  2: [
-    { source: 'rune', rune_type: 'risk', label: 'risk_or_fix_rune' },
-    { source: 'rune', rune_type: 'fix',  label: 'risk_or_fix_rune' },
-    { source: 'sigil',                   label: 'sigil' },
-  ],
-  3: [
-    { source: 'rune', rune_type: 'risk', label: 'risk_or_fix_rune' },
-    { source: 'rune', rune_type: 'fix',  label: 'risk_or_fix_rune' },
-    { source: 'sigil',                   label: 'sigil' },
-    { source: 'rune', rune_type: 'decision', label: 'verified_decision_rune' },
-  ],
-  9: [
-    { source: 'rune',    rune_type: 'risk', label: 'risk_or_fix_rune' },
-    { source: 'rune',    rune_type: 'fix',  label: 'risk_or_fix_rune' },
-    { source: 'episode',                    label: 'episode' },
-  ],
-};
-
-/**
- * Emit recall telemetry events for the memory sources required by this phase.
- * Uses a deterministic synthetic source_id so the same phase+task combination
- * always generates the same recall records (idempotent within a session slot).
- *
- * Returns:
- *   { recalled: N, recall_ids: string[], sources: [{source, source_id, recall_id}] }
- *   or { recalled: 0, recall_ids: [], sources: [], error?: string } on failure.
- */
-function emitRecallTelemetry(phase, taskId) {
-  const telemetry = { recalled: 0, recall_ids: [], sources: [] };
-  if (!taskId) return telemetry;
-
-  const phaseSources = PHASE_RECALL_SOURCES[phase];
-  if (!phaseSources || phaseSources.length === 0) return telemetry;
-
-  let memLog;
-  try {
-    const memLogPath = path.join(BASE_DIR, '.specialist', 'tools', 'memory-action-log.js');
-    if (!fs.existsSync(memLogPath)) return telemetry;
-    memLog = require(memLogPath);
-  } catch {
-    return telemetry;
-  }
-
-  for (const src of phaseSources) {
-    try {
-      // Synthetic source_id: deterministic per phase+task+source type so
-      // list-recalls can group these as "context-injection-suggested sources"
-      const sourceId = `ctx-inject:phase${phase}:${src.label}`;
-      const entry = {
-        source:    src.source,
-        source_id: sourceId,
-        task_id:   taskId,
-        phase,
-        reason:    `context-injection phase ${phase} loaded ${src.label} sources for task ${taskId}`,
-        rune_type: src.rune_type || null,
-      };
-      const r = memLog.recordRecall(entry);
-      if (r.ok) {
-        telemetry.recalled += 1;
-        telemetry.recall_ids.push(r.recall_id);
-        telemetry.sources.push({
-          source:    src.source,
-          source_id: sourceId,
-          label:     src.label,
-          recall_id: r.recall_id,
-        });
-      }
-    } catch { /* graceful degradation per source */ }
-  }
-
-  return telemetry;
-}
-
-// ═══════════════════════════════════════
-//  Stopwords (for phase 1 keyword extraction)
-// ═══════════════════════════════════════
-
-const STOPWORDS = new Set([
-  'this', 'that', 'with', 'from', 'will', 'have', 'been', 'they',
-  'when', 'what', 'each', 'into', 'then', 'than', 'also', 'more',
-  'some', 'such', 'like', 'task', 'file', 'code', 'tool', 'node',
-  'spec', 'test', 'make', 'does', 'just', 'them', 'your', 'over',
-  'output', 'input', 'return', 'value', 'params', 'param', 'args',
-]);
-
-// ═══════════════════════════════════════
-//  Main
-// ═══════════════════════════════════════
-
-function main() {
-  const args = parseArgs(process.argv);
-
-  const phaseRaw = args['phase'];
-  const taskId = args['task'];
-  const projectPath = args['project-path'] || null;
-
-  const phase = phaseRaw !== undefined ? parseInt(phaseRaw, 10) : NaN;
-
-  if (!taskId) {
-    console.error(JSON.stringify({ error: 'missing --task argument', phase: phase || null }));
-    process.exit(1);
-  }
-
-  if (isNaN(phase)) {
-    console.error(JSON.stringify({ error: 'missing or invalid --phase argument', task_id: taskId }));
-    process.exit(1);
-  }
-
-  // Load task
-  const task = loadTask(taskId, projectPath);
-
-  if (!task) {
-    process.stdout.write(JSON.stringify({ error: 'task not found', phase, task_id: taskId }) + '\n');
-    process.exit(1);
-  }
-
-  // Load chart (optional)
-  const chart = loadChart(taskId, projectPath);
-
-  // Build suggestions by phase
-  let synapse_suggestions = {};
-
-  switch (phase) {
-    case 1:
-      synapse_suggestions = { phase_1: buildPhase1Suggestions(task) };
-      break;
-    case 2:
-      synapse_suggestions = { phase_2: buildPhase2Suggestions(task) };
-      break;
-    case 3:
-      synapse_suggestions = { phase_3: buildPhase3Suggestions(task, chart) };
-      break;
-    case 9:
-      synapse_suggestions = { phase_9: buildPhase9Suggestions(task) };
-      break;
-    default:
-      // Other phases: empty suggestions, exit 0
-      break;
-  }
-
-  // Emit recall telemetry for memory sources required by this phase (TASK_1078).
-  // Graceful — failure never blocks context-injection output.
-  const recallTelemetry = emitRecallTelemetry(phase, task.id || taskId);
-
-  const result = {
-    phase,
-    task_id: task.id || taskId,
-    task_title: task.title,
-    chart_loaded: chart !== null,
-    synapse_suggestions,
-    // recall_telemetry: stable recall_ids for this phase's required memory sources.
-    // Pass any of these recall_ids to memory-action-log.js record-acted --recalled-from=...
-    // to link a later decision back to the memory sources that shaped it.
-    recall_telemetry: recallTelemetry,
-  };
-
-  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-  process.exit(0);
-}
-
-main();