kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/Ansuz/tools/bootstrap-anchors.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * bootstrap-anchors.js
+ *
+ * Scans .kenaz/tasks/done/ for historical FIX tasks (tag=fix), groups them
+ * by tag overlap into clusters, and proposes ansuz_motivational_state.json
+ * anchors with data-derived values.
+ *
+ * Usage:
+ *   node bootstrap-anchors.js [--project-path <path>] [--write]
+ *
+ * Output:
+ *   Prints proposed anchors as JSON to stdout (human review).
+ *   --write: merges proposed anchors into .kenaz/ansuz_motivational_state.json
+ *            (only adds anchors whose source_tags don't match any existing anchor)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Generic tags excluded from source_tags ───────────────────────────────────
+const GENERIC_TAGS = new Set(['fix', 'code', 'feature', 'analysis', 'bug', 'hotfix', 'patch', 'refactor', 'test', 'docs', 'chore']);
+
+// ─── CLI arg parsing ──────────────────────────────────────────────────────────
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let projectPath = process.cwd();
+  let write = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project-path' && args[i + 1]) {
+      projectPath = path.resolve(args[++i]);
+    } else if (args[i] === '--write') {
+      write = true;
+    }
+  }
+  return { projectPath, write };
+}
+
+// ─── Minimal YAML tag/date extractor (no external deps if unavailable) ────────
+function parseTaskFile(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  // Try js-yaml first (installed at project root)
+  try {
+    const rootNodeModules = path.resolve(__dirname, '../../..', 'node_modules');
+    // eslint-disable-next-line import/no-dynamic-require
+    const yaml = require(path.join(rootNodeModules, 'js-yaml'));
+    return yaml.load(content);
+  } catch {
+    // fallback: manual extraction
+  }
+
+  // Fallback: regex-based extraction for the fields we need
+  const task = {};
+
+  // id
+  const idMatch = content.match(/^id:\s*(.+)$/m);
+  if (idMatch) task.id = idMatch[1].trim().replace(/^['"]|['"]$/g, '');
+
+  // title
+  const titleMatch = content.match(/^title:\s*(.+)$/m);
+  if (titleMatch) task.title = titleMatch[1].trim().replace(/^['"]|['"]$/g, '');
+
+  // status
+  const statusMatch = content.match(/^status:\s*(.+)$/m);
+  if (statusMatch) task.status = statusMatch[1].trim().replace(/^['"]|['"]$/g, '');
+
+  // created_at
+  const createdMatch = content.match(/^created_at:\s*['"]?(.+?)['"]?$/m);
+  if (createdMatch) task.created_at = createdMatch[1].trim();
+
+  // tags: parse block list
+  const tagsSection = content.match(/^tags:\s*\n((?:\s*-\s*.+\n?)*)/m);
+  if (tagsSection) {
+    task.tags = tagsSection[1]
+      .split('\n')
+      .map(l => l.replace(/^\s*-\s*/, '').trim())
+      .filter(Boolean);
+  } else {
+    // inline tags: [a, b, c]
+    const inlineMatch = content.match(/^tags:\s*\[(.+)\]/m);
+    if (inlineMatch) {
+      task.tags = inlineMatch[1].split(',').map(t => t.trim().replace(/^['"]|['"]$/g, ''));
+    }
+  }
+
+  // executed_by timestamp (most reliable completion date)
+  const execMatch = content.match(/executed_by:[\s\S]*?timestamp:\s*['"]?(.+?)['"]?$/m);
+  if (execMatch) task.executed_at = execMatch[1].trim();
+
+  return task;
+}
+
+// ─── Scan done directory for FIX tasks ────────────────────────────────────────
+function scanFixTasks(doneDir) {
+  if (!fs.existsSync(doneDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(doneDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+  const fixTasks = [];
+
+  for (const file of files) {
+    const task = parseTaskFile(path.join(doneDir, file));
+    if (!task) continue;
+    if (!Array.isArray(task.tags)) continue;
+    if (!task.tags.includes('fix')) continue;
+
+    // Determine best date: created_at > executed_at
+    const date = (task.created_at || task.executed_at || '').replace(/T.*/, '');
+
+    fixTasks.push({
+      id: task.id || file.replace('.yaml', ''),
+      title: task.title || '',
+      tags: task.tags,
+      date: date || null,
+    });
+  }
+
+  return fixTasks;
+}
+
+// ─── Tag clustering: union-find by 2+ shared domain tags ─────────────────────
+function domainTags(tags) {
+  return tags.filter(t => !GENERIC_TAGS.has(t));
+}
+
+function buildClusters(fixTasks) {
+  // Union-Find
+  const parent = fixTasks.map((_, i) => i);
+
+  function find(i) {
+    while (parent[i] !== i) {
+      parent[i] = parent[parent[i]];
+      i = parent[i];
+    }
+    return i;
+  }
+
+  function union(i, j) {
+    const pi = find(i), pj = find(j);
+    if (pi !== pj) parent[pi] = pj;
+  }
+
+  // Merge tasks that share 2+ domain tags
+  for (let i = 0; i < fixTasks.length; i++) {
+    const dA = new Set(domainTags(fixTasks[i].tags));
+    for (let j = i + 1; j < fixTasks.length; j++) {
+      const dB = domainTags(fixTasks[j].tags);
+      const overlap = dB.filter(t => dA.has(t));
+      if (overlap.length >= 2) {
+        union(i, j);
+      }
+    }
+  }
+
+  // Group by root
+  const clusters = new Map();
+  for (let i = 0; i < fixTasks.length; i++) {
+    const root = find(i);
+    if (!clusters.has(root)) clusters.set(root, []);
+    clusters.get(root).push(fixTasks[i]);
+  }
+
+  return Array.from(clusters.values());
+}
+
+// ─── Convert cluster → proposed anchor ────────────────────────────────────────
+function clusterToAnchor(tasks) {
+  // Count domain tag frequency across cluster
+  const tagFreq = {};
+  for (const task of tasks) {
+    for (const tag of domainTags(task.tags)) {
+      tagFreq[tag] = (tagFreq[tag] || 0) + 1;
+    }
+  }
+
+  // source_tags: domain tags appearing in >= half the cluster tasks, sorted by freq desc
+  const threshold = Math.max(1, Math.floor(tasks.length / 2));
+  const sourceTags = Object.entries(tagFreq)
+    .filter(([, count]) => count >= threshold)
+    .sort((a, b) => b[1] - a[1])
+    .map(([tag]) => tag);
+
+  // concept: top 3 source_tags joined, or fallback to all top tags
+  const topTags = Object.entries(tagFreq)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([tag]) => tag);
+  const concept = topTags.join(' / ');
+
+  // Most recent task date
+  const dates = tasks.map(t => t.date).filter(Boolean).sort();
+  const lastTouched = dates.length ? dates[dates.length - 1] : new Date().toISOString().slice(0, 10);
+
+  const fixCycleCount = tasks.length;
+  const incompleteness = Math.min(fixCycleCount * 0.15, 0.9);
+
+  return {
+    concept,
+    source_tags: sourceTags.length ? sourceTags : topTags,
+    incompleteness: Math.round(incompleteness * 100) / 100,
+    fix_cycle_count: fixCycleCount,
+    last_touched: lastTouched,
+    decay_halflife_days: 45,
+  };
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+function main() {
+  const { projectPath, write } = parseArgs();
+
+  const doneDir = path.join(projectPath, '.kenaz', 'tasks', 'done');
+  const statePath = path.join(projectPath, '.kenaz', 'specialist', 'ansuz_motivational_state.json');
+
+  // Scan FIX tasks
+  const fixTasks = scanFixTasks(doneDir);
+
+  if (fixTasks.length === 0) {
+    process.stderr.write(`[bootstrap-anchors] No FIX tasks found in ${doneDir}\n`);
+    process.stdout.write(JSON.stringify([], null, 2) + '\n');
+    return;
+  }
+
+  process.stderr.write(`[bootstrap-anchors] Found ${fixTasks.length} FIX task(s) in ${doneDir}\n`);
+
+  // Build clusters
+  const clusters = buildClusters(fixTasks);
+  process.stderr.write(`[bootstrap-anchors] Formed ${clusters.length} cluster(s)\n`);
+
+  // Convert to proposed anchors
+  const proposed = clusters.map(clusterToAnchor);
+
+  if (!write) {
+    // Read-only mode: print proposed anchors as JSON
+    process.stdout.write(JSON.stringify(proposed, null, 2) + '\n');
+    process.stderr.write('\n[bootstrap-anchors] Review the proposed anchors above.\n');
+    process.stderr.write('[bootstrap-anchors] To merge into ansuz_motivational_state.json, run with --write\n');
+    return;
+  }
+
+  // --write mode: merge proposed anchors into existing state
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch {
+    process.stderr.write(`[bootstrap-anchors] ERROR: could not read ${statePath}\n`);
+    process.exit(1);
+  }
+
+  const existing = Array.isArray(state.anchors) ? state.anchors : [];
+  let added = 0;
+
+  for (const anchor of proposed) {
+    // Skip if existing anchor already covers these source_tags (any overlap)
+    const alreadyCovered = existing.some(ex =>
+      Array.isArray(ex.source_tags) &&
+      ex.source_tags.some(t => anchor.source_tags.includes(t))
+    );
+    if (alreadyCovered) {
+      process.stderr.write(`[bootstrap-anchors] SKIP (covered): ${anchor.concept}\n`);
+      continue;
+    }
+    existing.push(anchor);
+    added++;
+    process.stderr.write(`[bootstrap-anchors] ADD: ${anchor.concept}\n`);
+  }
+
+  if (added > 0) {
+    state.anchors = existing;
+    state.last_updated = new Date().toISOString();
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n', 'utf8');
+    process.stderr.write(`[bootstrap-anchors] Wrote ${added} new anchor(s) to ${statePath}\n`);
+  } else {
+    process.stderr.write('[bootstrap-anchors] No new anchors to add (all clusters already covered by existing anchors)\n');
+  }
+
+  process.stdout.write(JSON.stringify(existing, null, 2) + '\n');
+}
+
+main();

package/core/.specialist/Ansuz/tools/handoff-freshness-milestone.test.js

@@ -0,0 +1,73 @@
+'use strict';
+/**
+ * handoff-freshness-milestone.test.js — TASK_2325 (field report)
+ *
+ * The freshness guard skips a snapshot while the session's slot is < window old, so an
+ * auto-snapshot cannot clobber richer content. But a caller that passes its own NEW
+ * --last-milestone is the author: restoring a negative control stayed recorded as
+ * "source disabled" until the window passed. A new milestone must write; the same
+ * milestone (or none) inside the window must still skip.
+ *
+ * Run: node --test .specialist/Ansuz/tools/handoff-freshness-milestone.test.js
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const HERE = __dirname;
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+function mkProject() {
+  const proj = fs.mkdtempSync(path.join(os.tmpdir(), 'task2325-'));
+  fs.mkdirSync(path.join(proj, '.kenaz', 'specialist', 'handoffs'), { recursive: true });
+  fs.writeFileSync(path.join(proj, '.kenaz', 'project.yaml'), 'name: task2325-fixture\n');
+  const ansuzTools = path.join(proj, '.specialist', 'Ansuz', 'tools');
+  const libDir = path.join(proj, '.specialist', 'tools', 'lib');
+  fs.mkdirSync(ansuzTools, { recursive: true });
+  fs.mkdirSync(libDir, { recursive: true });
+  for (const f of ['ansuz-handoff-snapshot.js', 'handoff-resolver.js']) {
+    fs.copyFileSync(path.join(HERE, f), path.join(ansuzTools, f));
+  }
+  fs.copyFileSync(path.join(REPO_ROOT, '.specialist', 'tools', 'lib', 'project-resolver.js'), path.join(libDir, 'project-resolver.js'));
+  fs.copyFileSync(path.join(REPO_ROOT, '.specialist', 'tools', 'stream-lease.js'), path.join(proj, '.specialist', 'tools', 'stream-lease.js'));
+  return proj;
+}
+
+function snap(proj, milestone) {
+  const args = [path.join(proj, '.specialist', 'Ansuz', 'tools', 'ansuz-handoff-snapshot.js'),
+    '--trigger=live_decision_point', `--project-path=${proj}`, '--session-id=s-2325'];
+  if (milestone) args.push(`--last-milestone=${milestone}`);
+  const r = spawnSync(process.execPath, args, {
+    input: '', encoding: 'utf8', timeout: 30000, windowsHide: true,
+    env: Object.assign({}, process.env, { CLAUDE_PROJECT_DIR: proj }),
+  });
+  const slot = path.join(proj, '.kenaz', 'specialist', 'handoffs', 's-2325.json');
+  return { out: (r.stdout || '') + (r.stderr || ''), slot: fs.existsSync(slot) ? JSON.parse(fs.readFileSync(slot, 'utf8')) : null };
+}
+
+test('a new --last-milestone inside the freshness window updates the slot; same milestone still skips', () => {
+  const proj = mkProject();
+  try {
+    const a = snap(proj, 'source deliberately disabled (negative control)');
+    assert.equal(a.slot && a.slot.last_milestone, 'source deliberately disabled (negative control)', a.out);
+
+    // Control: same milestone seconds later -> skipped by the freshness guard.
+    const same = snap(proj, 'source deliberately disabled (negative control)');
+    assert.match(same.out, /handoff skip: existing slot is fresh/);
+
+    // Control: no milestone (auto-snapshot) -> skipped, richer content kept.
+    const auto = snap(proj, null);
+    assert.match(auto.out, /handoff skip: existing slot is fresh/);
+    assert.equal(auto.slot.last_milestone, 'source deliberately disabled (negative control)');
+
+    // The fix: a new milestone from the author writes immediately.
+    const b = snap(proj, 'source restored and verified');
+    assert.doesNotMatch(b.out, /handoff skip/);
+    assert.equal(b.slot.last_milestone, 'source restored and verified');
+  } finally {
+    fs.rmSync(proj, { recursive: true, force: true });
+  }
+});

package/core/.specialist/Ansuz/tools/handoff-resolver.js

@@ -0,0 +1,207 @@
+'use strict';
+/**
+ * handoff-resolver.js — TASK_1829
+ * Single definition site for Ansuz session-handoff slot resolution.
+ *
+ * M3 (TASK_1760) migrated handoff storage from the singular slot
+ *   .kenaz/specialist/ansuz_session_handoff.json      (RETIRED — read-only legacy)
+ * to per-session slots
+ *   .kenaz/specialist/handoffs/<sessionId>.json
+ *
+ * TWO read semantics exist and MUST NOT be merged into one "latest" function
+ * (TASK_1829 design decision):
+ *
+ *   readOwnHandoff(projectPath, sessionId)
+ *     "Did THIS session write a handoff, and what does it say?"
+ *     Consumers: phase-gate L4 staleness nudge, phase-gate Phase 11 augment,
+ *     fatigue guard. A latest-pointer here would let another
+ *     session's fresh slot masquerade as ours — turning a true warning into a
+ *     false pass (the exact degraded-path-reports-pass class TASK_1825 removed).
+ *
+ *   readLatestHandoff(projectPath)
+ *     "What is the most recent handoff from ANY session?"
+ *     Consumers: bifrost boot-context (previous-session context restore).
+ *     Mirrors post-complete.js readLatestHandoff (TASK_1828).
+ *
+ * Slot filename families (TASK_1828): <conversation-uuid>.json AND
+ * ansuz-prompt-<ts>.json coexist by design, so filename ordering is
+ * meaningless. generated_at (ISO-8601 UTC, fixed width → lexicographic ==
+ * chronological) is the only valid ordering for "latest". writeHandoff
+ * therefore always stamps generated_at when the payload lacks one.
+ *
+ * Cleared sentinels ({cleared:true}, Phase 11 exit) are returned as-is by both
+ * readers — callers gate on `handoff.cleared === true`, same as the legacy
+ * single-slot contract.
+ *
+ * CommonJS; required from .specialist/tools/phase-gate.js,
+ * .formation/bifrost/shared/*.js (ES5-style callers) and .claude/hooks/*.js.
+ * Pin-aware: an explicit projectPath argument wins; when omitted, falls back
+ * to the shared project-resolver (TASK_1701 conventions — pin file lookup).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HANDOFFS_RELDIR = path.join('.kenaz', 'specialist', 'handoffs');
+// Legacy singular slot — RETIRED by M3 (TASK_1760). Read-only fallback below;
+// writeHandoff never targets it. Do NOT add writers for this path.
+const LEGACY_HANDOFF_RELPATH = path.join('.kenaz', 'specialist', 'ansuz_session_handoff.json');
+
+function resolveProject(projectPath) {
+  if (projectPath) return path.resolve(String(projectPath));
+  // Pin-aware fallback (TASK_1701): shared resolver consults the session-keyed
+  // pin file so handoffs land in the correct project even without --project-path.
+  try {
+    const projectResolver = require(path.join(__dirname, '..', '..', 'tools', 'lib', 'project-resolver.js'));
+    return projectResolver.resolveProjectPath({ cliProjectPath: null, argv: process.argv.slice(2) }).projectPath;
+  } catch (e) {
+    return process.cwd();
+  }
+}
+
+function handoffsDir(projectPath) {
+  return path.join(resolveProject(projectPath), HANDOFFS_RELDIR);
+}
+
+function legacyHandoffPath(projectPath) {
+  return path.join(resolveProject(projectPath), LEGACY_HANDOFF_RELPATH);
+}
+
+// Slot name mapping — must stay in sync with ansuz-handoff-snapshot.js, which
+// writes raw `<sessionId>.json`. Real ids (conversation UUIDs, ansuz-prompt-<ts>,
+// codex-<ts>) contain only safe characters, so sanitize is a no-op for them;
+// it only guards against path-separator injection from malformed ids.
+function safeSlotName(sessionId) {
+  return String(sessionId).replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+function readJsonSafe(fp) {
+  try {
+    if (!fs.existsSync(fp)) return null;
+    return JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Read THIS session's handoff. Returns the parsed handoff object or null.
+ * Legacy singular slot is accepted ONLY when its session_id field equals the
+ * requested sessionId — otherwise it is some other session's leftover and
+ * must not be attributed to us.
+ * Degraded paths (no sessionId, missing slot, parse error) return null —
+ * callers MUST handle null explicitly and MUST NOT substitute
+ * readLatestHandoff (see header; TASK_1825 lesson).
+ */
+function readOwnHandoff(projectPath, sessionId) {
+  if (!sessionId) return null;
+  const root = resolveProject(projectPath);
+  const own = readJsonSafe(path.join(root, HANDOFFS_RELDIR, safeSlotName(sessionId) + '.json'));
+  if (own) return own;
+  const legacy = readJsonSafe(path.join(root, LEGACY_HANDOFF_RELPATH));
+  if (legacy && legacy.session_id === String(sessionId)) return legacy;
+  return null;
+}
+
+/**
+ * Read the most recent handoff across ALL sessions (newest generated_at wins;
+ * slots without generated_at sort oldest). Falls back to the legacy singular
+ * slot when handoffs/ has no readable slot. Returns null when nothing exists.
+ */
+function readLatestHandoff(projectPath) {
+  const root = resolveProject(projectPath);
+  const dir = path.join(root, HANDOFFS_RELDIR);
+  let names = [];
+  try {
+    names = fs.readdirSync(dir);
+  } catch (e) {
+    names = [];
+  }
+  let latest = null;
+  let latestKey = '';
+  for (let i = 0; i < names.length; i++) {
+    if (!names[i].endsWith('.json')) continue;
+    const data = readJsonSafe(path.join(dir, names[i]));
+    if (!data) continue;
+    const key = typeof data.generated_at === 'string' ? data.generated_at : '';
+    if (latest === null || key > latestKey) {
+      latest = data;
+      latestKey = key;
+    }
+  }
+  if (latest) return latest;
+  // Legacy fallback — deliberate (M3 read-only back-compat, TASK_1760/TASK_1828).
+  return readJsonSafe(path.join(root, LEGACY_HANDOFF_RELPATH));
+}
+
+/**
+ * Write a handoff to the per-session slot (atomic: .tmp + rename).
+ * NEVER writes the legacy singular slot. Throws on missing sessionId — a
+ * degraded silent fallback here would resurrect the retired single-slot
+ * behavior the M3 migration removed.
+ * Returns the absolute slot path written.
+ */
+function writeHandoff(projectPath, sessionId, payload) {
+  if (!sessionId) {
+    throw new Error('writeHandoff requires a sessionId — the singular legacy slot is retired (M3/TASK_1760)');
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('writeHandoff requires a payload object');
+  }
+  const root = resolveProject(projectPath);
+  const dir = path.join(root, HANDOFFS_RELDIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const obj = Object.assign({}, payload);
+  if (!obj.session_id) obj.session_id = String(sessionId);
+  if (typeof obj.generated_at !== 'string' || !obj.generated_at) {
+    obj.generated_at = new Date().toISOString();
+  }
+  const fp = path.join(dir, safeSlotName(sessionId) + '.json');
+  const tmp = fp + '.' + process.pid + '.tmp';
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2), 'utf8');
+    fs.renameSync(tmp, fp);
+  } catch (e) {
+    try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch (e2) { /* ignore */ }
+    throw e;
+  }
+  return fp;
+}
+
+/**
+ * Best-effort enumeration of "this session's" candidate ids, ordered by
+ * reliability. Two id namespaces exist (TASK_1711): boot-registered
+ * 'ansuz-prompt-<ts>' ids (ansuz_session.json) and Claude Code conversation
+ * UUIDs (CLAUDE_CODE_SESSION_ID env). A session's slot may live under either,
+ * so callers should try readOwnHandoff with each candidate in order.
+ * Returns [] when identity cannot be established — callers MUST treat that as
+ * "own handoff unknown" and must NOT substitute readLatestHandoff (TASK_1829).
+ */
+function resolveOwnSessionCandidates(projectPath) {
+  const root = resolveProject(projectPath);
+  const out = [];
+  // (1) Live boot-registered session file. Dead-pid guard (TASK_1615): a
+  // session file left by a dead process is stale and must not be trusted.
+  const sess = readJsonSafe(path.join(root, '.kenaz', 'specialist', 'ansuz_session.json'));
+  if (sess && sess.session_id) {
+    let alive = true;
+    if (sess.pid) {
+      try { process.kill(sess.pid, 0); } catch (e) { alive = false; }
+    }
+    if (alive) out.push({ id: String(sess.session_id), source: 'ansuz_session.json' });
+  }
+  // (2) Conversation UUID from environment (interactive Claude Code sessions).
+  if (process.env.CLAUDE_CODE_SESSION_ID) {
+    out.push({ id: String(process.env.CLAUDE_CODE_SESSION_ID), source: 'env:CLAUDE_CODE_SESSION_ID' });
+  }
+  return out;
+}
+
+module.exports = {
+  readOwnHandoff,
+  readLatestHandoff,
+  writeHandoff,
+  resolveOwnSessionCandidates,
+  handoffsDir,
+  legacyHandoffPath,
+};