contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/pipeline-validate.mjs

@@ -0,0 +1,136 @@
+/**
+ * DevPipeline metadata v2 validators (ticket 040, ADR-0022 follow-through).
+ *
+ * Two concerns kept together because they share a single mental model — the
+ * `dependencies: []` DAG over ticket ids:
+ *
+ *   1. `detectCycles(tasks)` — DFS-based cycle detector. Returns the offending
+ *      cycle (array of ids in order) or `null`. Pure; no I/O.
+ *   2. `blockedBy(task, tasks)` — counts how many of `task.dependencies` are
+ *      *still open* (stage ≠ conclusion). Used by the board renderer to show
+ *      the "↘ blocked by N" hint.
+ *
+ * Also exports the valid enums (`VALID_TYPES`, `VALID_COMPLEXITY`) so the CLI
+ * + selfcheck + render layer single-source them.
+ *
+ * Pure ESM, zero-dep. See [ADR-0022](../../memory/decisions/0022-run-dispatcher-task-dependencies.md)
+ * for the DAG semantics this ships even though no dispatcher reads it yet.
+ */
+
+export const VALID_TYPES = new Set(['bug', 'chore', 'feature', 'increment', 'spike', 'docs', 'task']);
+export const VALID_COMPLEXITY = new Set(['S', 'M', 'L', 'XL']);
+
+/**
+ * Parses a YAML inline array — `[040, 041, 042]` — into a string array.
+ * Trims, drops empty entries, returns `[]` for absent / empty / malformed.
+ *
+ * @param {string | undefined | null} raw
+ * @returns {string[]}
+ */
+export function parseInlineArray(raw) {
+  if (typeof raw !== 'string') return [];
+  const trimmed = raw.trim();
+  if (trimmed === '' || trimmed === '[]') return [];
+  const stripped = trimmed.startsWith('[') && trimmed.endsWith(']') ? trimmed.slice(1, -1) : trimmed;
+  return stripped.split(',').map((s) => s.replace(/['"]/g, '').trim()).filter(Boolean);
+}
+
+/**
+ * Validates a single ticket's metadata v2 fields. Returns `{ ok, errors }`.
+ * Permissive: missing fields are accepted (backward-compat with v1 tickets).
+ *
+ * @param {object} task — shape from `listTasks()` (id, type, complexity, dependencies)
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateTaskV2(task) {
+  const errors = [];
+  if (task.type && !VALID_TYPES.has(task.type)) errors.push(`${task.id}: unknown type "${task.type}"`);
+  if (task.complexity && !VALID_COMPLEXITY.has(task.complexity)) errors.push(`${task.id}: complexity must be S | M | L | XL (got "${task.complexity}")`);
+  if (Array.isArray(task.dependencies)) {
+    for (const dep of task.dependencies) if (dep === task.id) errors.push(`${task.id}: self-dependency`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * DFS cycle detector over the task graph.
+ *
+ * Returns the offending cycle as an ordered array of ids (`['040', '041', '040']`)
+ * when one exists, or `null` when the graph is acyclic. An edge to an unknown
+ * id (`042` depends on `999` which doesn't exist) is ignored — that's a
+ * dangling reference, not a cycle. The validator should surface those
+ * separately if/when it grows.
+ *
+ * @param {Array<{ id: string, dependencies?: string[] }>} tasks
+ * @returns {string[] | null}
+ */
+export function detectCycles(tasks) {
+  const graph = new Map();
+  for (const t of tasks) graph.set(String(t.id), (t.dependencies || []).map(String));
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const colour = new Map();
+  for (const id of graph.keys()) colour.set(id, WHITE);
+  const stack = [];
+
+  function dfs(node) {
+    colour.set(node, GRAY);
+    stack.push(node);
+    for (const next of graph.get(node) || []) {
+      if (!graph.has(next)) continue; // dangling reference — not a cycle
+      if (colour.get(next) === GRAY) {
+        const start = stack.indexOf(next);
+        return [...stack.slice(start), next];
+      }
+      if (colour.get(next) === WHITE) {
+        const cycle = dfs(next);
+        if (cycle) return cycle;
+      }
+    }
+    colour.set(node, BLACK);
+    stack.pop();
+    return null;
+  }
+
+  for (const id of graph.keys()) {
+    if (colour.get(id) !== WHITE) continue;
+    const cycle = dfs(id);
+    if (cycle) return cycle;
+  }
+  return null;
+}
+
+/**
+ * Lints every task's type / complexity / dependencies and refuses on cycles.
+ * Returns the list of error strings (empty when clean). Pure; the CLI prints +
+ * exits. Lives here (not in pipeline.mjs) so pipeline.mjs stays under budget.
+ *
+ * @param {Array<{ id: string, type?: string, complexity?: string, dependencies?: string[] }>} tasks
+ * @returns {string[]}
+ */
+export function runValidate(tasks) {
+  const errors = tasks.flatMap((t) => validateTaskV2(t).errors);
+  const cycle = detectCycles(tasks);
+  if (cycle) errors.push(`dependency cycle: ${cycle.join(' → ')}`);
+  return errors;
+}
+
+/**
+ * Counts how many of `task.dependencies` are still open — stage is `backlog`,
+ * `working`, or `testing`. Used by the board renderer to show "↘ blocked by N".
+ * Dangling references (deps that don't exist in the task set) are silently
+ * ignored.
+ *
+ * @param {{ dependencies?: string[] }} task
+ * @param {Array<{ id: string, stage: string }>} allTasks
+ * @returns {number}
+ */
+export function blockedBy(task, allTasks) {
+  if (!Array.isArray(task.dependencies) || task.dependencies.length === 0) return 0;
+  const byId = new Map(allTasks.map((t) => [String(t.id), t.stage]));
+  let blocked = 0;
+  for (const dep of task.dependencies) {
+    const stage = byId.get(String(dep));
+    if (stage && stage !== 'conclusion') blocked += 1;
+  }
+  return blocked;
+}

package/templates/contextkit/tools/scripts/pipeline.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * DevPipeline engine — execution board (≠ roadmap). Stages: backlog → working
+ * (ADR-0015 §B) → testing → conclusion. Renderer in pipeline-board.mjs,
+ * scoring in pipeline-prioritize.mjs, session-coupled start/stop in
+ * pipeline-session.mjs, schema-v2 validators in pipeline-validate.mjs.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfigSync } from '../../runtime/config/load.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+import { writeFileAtomicSync } from '../../runtime/hooks/safe-io.mjs';
+import { wsjfScore, wsjfToPriority, severityToPriority, bugSeverityToPriority, slaDue, DEFAULTS } from './pipeline-prioritize.mjs';
+import { renderBoard, renderKnownBugs } from './pipeline-board.mjs';
+import { parseInlineArray, runValidate } from './pipeline-validate.mjs';
+
+const ROOT = process.cwd();
+const PIPE = pathsFor(ROOT).pipeline;
+const STAGES = { backlog: 'backlog', working: 'working', testing: 'testing', conclusion: 'conclusion' };
+const STATUS = { backlog: 'backlog', working: 'working', testing: 'testing', conclusion: 'done' };
+const CFG = loadConfigSync(ROOT).pipeline || {};
+const BANDS = CFG.wsjfBands || DEFAULTS.wsjfBands;
+const SEVMAP = CFG.severityPriority || DEFAULTS.severityPriority;
+const SLADAYS = CFG.slaDays || DEFAULTS.slaDays;
+
+function ensureDirs() {
+  for (const s of Object.keys(STAGES)) mkdirSync(resolve(PIPE, s), { recursive: true });
+}
+
+function parseFrontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  const fm = {};
+  if (m) for (const line of m[1].split('\n')) {
+    const i = line.indexOf(':');
+    if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return fm;
+}
+
+function listTasks() {
+  ensureDirs();
+  const tasks = [];
+  for (const stage of Object.keys(STAGES)) {
+    let files = [];
+    try {
+      files = readdirSync(resolve(PIPE, stage)).filter((f) => f.endsWith('.md'));
+    } catch {
+      /* none */
+    }
+    for (const f of files) {
+      const fm = parseFrontmatter(readFileSync(resolve(PIPE, stage, f), 'utf-8'));
+      tasks.push({ stage, file: f, id: fm.id || f.split('-')[0], title: fm.title || f, type: fm.type || 'task', priority: fm.priority || 'P2', severity: fm.severity || '', wsjf: fm.wsjf || '', bugType: fm.bugType || '', sla: fm.sla || '', roadmap: fm.roadmap || '', source: fm.source || '', created: fm.created || '', complexity: fm.complexity || '', dependencies: parseInlineArray(fm.dependencies) });
+    }
+  }
+  return tasks.sort((a, b) => (a.priority + a.id).localeCompare(b.priority + b.id));
+}
+
+function nextId() {
+  const ids = listTasks().map((t) => parseInt(t.id, 10)).filter((n) => !Number.isNaN(n));
+  return String((ids.length ? Math.max(...ids) : 0) + 1).padStart(3, '0');
+}
+
+function slug(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'task';
+}
+
+function getArg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 ? process.argv[i + 1] : undefined;
+}
+
+/** Writes one backlog task file and returns its id. Shared by add + ingest. */
+function writeTask({ type = 'task', priority = 'P2', title, sla = '', roadmap = '', source = '', context = '', severity = '', wsjf = '', bugType = '', complexity = '', dependencies = [] }) {
+  ensureDirs();
+  const created = new Date().toISOString().slice(0, 10);
+  const deps = Array.isArray(dependencies) ? `[${dependencies.join(', ')}]` : '[]';
+  const buildBody = (id) => [
+    '---',
+    `id: ${id}`,
+    `title: ${title}`,
+    `type: ${type}`,
+    `priority: ${priority}`,
+    `severity: ${severity}`,
+    `wsjf: ${wsjf}`,
+    `bugType: ${bugType}`,
+    `complexity: ${complexity}`,
+    `dependencies: ${deps}`,
+    `status: backlog`,
+    `created: ${created}`,
+    `sla: ${sla || slaDue(priority, created, SLADAYS)}`,
+    `roadmap: ${roadmap}`,
+    `source: ${source}`,
+    '---',
+    '',
+    `## ${title}`,
+    '',
+    `**Context / why:** ${context}`,
+    '',
+    '**Acceptance criteria:**',
+    '- [ ] ',
+    '',
+  ].join('\n');
+  // Collision-safe id allocation: claim the file with an exclusive create (`wx`).
+  // If two concurrent `add`s race for the same id, the loser sees EEXIST (or finds
+  // the id already taken) and retries with the next id — two tasks never share one.
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    const id = nextId();
+    if (listTasks().some((t) => t.id === id)) continue;
+    try {
+      writeFileSync(resolve(PIPE, 'backlog', `${id}-${slug(title)}.md`), buildBody(id), { encoding: 'utf-8', flag: 'wx' });
+      return id;
+    } catch (err) {
+      if (err?.code === 'EEXIST') continue;
+      throw err;
+    }
+  }
+  throw new Error('pipeline: could not allocate a unique task id (50 attempts exhausted)');
+}
+
+function add() {
+  const type = getArg('type') || 'task';
+  const title = getArg('title');
+  if (!title) {
+    console.error('Usage: pipeline.mjs add --type <bug|feature|chore> --title "..." [--priority P0-P3] [--severity S1-S4] [--wsjf uv,tc,rr,js] [--bug-type <t>]');
+    process.exit(1);
+  }
+  const sev = getArg('severity');
+  const wsjfArg = getArg('wsjf');
+  let priority = getArg('priority');
+  let wsjf = '';
+  if (wsjfArg) {
+    const [uv, tc, rr, js] = wsjfArg.split(',').map(Number);
+    wsjf = wsjfScore({ userValue: uv, timeCriticality: tc, riskReduction: rr, jobSize: js });
+    priority = priority || wsjfToPriority(wsjf, BANDS);
+  } else if (sev) {
+    priority = priority || bugSeverityToPriority(sev, SEVMAP);
+  }
+  priority = priority || 'P2';
+  const id = writeTask({ type, priority, title, sla: getArg('sla') || '', roadmap: getArg('roadmap') || '', source: getArg('source') || '', severity: sev || '', wsjf, bugType: getArg('bug-type') || '', complexity: getArg('complexity') || '', dependencies: parseInlineArray(getArg('depends-on')) });
+  sync();
+  console.log(`✅ Added ${type} ${id} (${priority}${wsjf ? `, WSJF ${wsjf}` : ''}${sev ? `, ${sev}` : ''}) to backlog: ${title}`);
+}
+
+/**
+ * Bulk-import findings from a JSON file (e.g. `tech-debt-scan --json`) into the
+ * backlog — one task per finding, priority auto-mapped from `severity`. Idempotent:
+ * a finding whose `source` fingerprint already has a non-concluded task is skipped,
+ * so re-running an analysis never spams duplicates. The user re-prioritizes freely.
+ */
+function ingest() {
+  const fileArg = process.argv[3] && !process.argv[3].startsWith('--') ? process.argv[3] : getArg('file');
+  if (!fileArg) {
+    console.error('Usage: pipeline.mjs ingest <findings.json> [--type chore]');
+    process.exit(1);
+  }
+  let data;
+  try {
+    data = JSON.parse(readFileSync(resolve(ROOT, fileArg), 'utf-8').replace(/^/, ''));
+  } catch (err) {
+    console.error(`Could not read findings JSON: ${err?.message ?? err}`);
+    process.exit(1);
+  }
+  const findings = Array.isArray(data) ? data : data.findings || [];
+  const type = getArg('type') || 'chore';
+  const taken = new Set(listTasks().filter((t) => t.stage !== 'conclusion').map((t) => t.source).filter(Boolean));
+  let added = 0;
+  let skipped = 0;
+  for (const f of findings) {
+    const where = f.path ? `${f.path}${f.line ? ':' + f.line : ''}` : '';
+    const source = f.source || `${f.kind || 'finding'}:${where}`;
+    if (taken.has(source)) {
+      skipped += 1;
+      continue;
+    }
+    const priority = /^P[0-3]$/.test(f.priority || '') ? f.priority : severityToPriority(f.severity);
+    const title = String(f.title || `${f.kind ? f.kind + ': ' : ''}${where || 'finding'}`).slice(0, 80);
+    writeTask({ type, priority, title, source, context: f.message || '' });
+    taken.add(source);
+    added += 1;
+  }
+  sync();
+  console.log(`✅ Ingested ${added} finding(s) into backlog (${skipped} already present). Re-prioritize any with: pipeline.mjs prioritize <id> <P0-P3>`);
+}
+
+/** User override: change a task's auto-assigned priority. */
+function prioritize() {
+  const id = process.argv[3];
+  const priority = process.argv[4];
+  if (!id || !/^P[0-3]$/.test(priority || '')) {
+    console.error('Usage: pipeline.mjs prioritize <id> <P0|P1|P2|P3>');
+    process.exit(1);
+  }
+  const task = listTasks().find((t) => t.id === id.padStart(3, '0') || t.id === id);
+  if (!task) {
+    console.error(`No task with id ${id}.`);
+    process.exit(1);
+  }
+  const p = resolve(PIPE, task.stage, task.file);
+  writeFileAtomicSync(p, readFileSync(p, 'utf-8').replace(/^priority:.*$/m, `priority: ${priority}`));
+  sync();
+  console.log(`✅ ${task.id} priority → ${priority}`);
+}
+
+/** (Re)score a task with WSJF and re-derive its priority + SLA due date. */
+function setWsjf() {
+  const id = process.argv[3];
+  const [uv, tc, rr, js] = process.argv.slice(4).map(Number);
+  if (!id || [uv, tc, rr, js].some((n) => Number.isNaN(n))) {
+    console.error('Usage: pipeline.mjs wsjf <id> <userValue> <timeCriticality> <riskReduction> <jobSize>  (each 1-10)');
+    process.exit(1);
+  }
+  const task = listTasks().find((t) => t.id === id.padStart(3, '0') || t.id === id);
+  if (!task) {
+    console.error(`No task with id ${id}.`);
+    process.exit(1);
+  }
+  const score = wsjfScore({ userValue: uv, timeCriticality: tc, riskReduction: rr, jobSize: js });
+  const pr = wsjfToPriority(score, BANDS);
+  const due = slaDue(pr, task.created, SLADAYS);
+  const p = resolve(PIPE, task.stage, task.file);
+  writeFileAtomicSync(p, readFileSync(p, 'utf-8')
+    .replace(/^priority:.*$/m, `priority: ${pr}`)
+    .replace(/^wsjf:.*$/m, `wsjf: ${score}`)
+    .replace(/^sla:.*$/m, `sla: ${due}`));
+  sync();
+  console.log(`✅ ${task.id} WSJF ${score} → ${pr} (SLA ${due})`);
+}
+
+function move() {
+  const id = process.argv[3];
+  const stage = process.argv[4];
+  if (!id || !STAGES[stage]) {
+    console.error('Usage: pipeline.mjs move <id> <backlog|working|testing|conclusion>');
+    process.exit(1);
+  }
+  const task = listTasks().find((t) => t.id === id.padStart(3, '0') || t.id === id);
+  if (!task) {
+    console.error(`No task with id ${id}.`);
+    process.exit(1);
+  }
+  const from = resolve(PIPE, task.stage, task.file);
+  const to = resolve(PIPE, stage, task.file);
+  let text = readFileSync(from, 'utf-8').replace(/^(status:).*$/m, `status: ${STATUS[stage]}`);
+  if (stage === 'conclusion' && !/^concluded:/m.test(text)) {
+    text = text.replace(/^---\n([\s\S]*?)\n---/, (full, fm) => `---\n${fm}\nconcluded: ${new Date().toISOString().slice(0, 10)}\n---`);
+  }
+  writeFileAtomicSync(from, text);
+  renameSync(from, to);
+  sync();
+  // ADR-0015 §C — fire-and-forget state.json mirror (observability, best-effort).
+  import('../../runtime/state/state-io.mjs').then((m) => m.readState(PIPE, task.id) && m.writeState(PIPE, task.id, stage === 'conclusion' ? { status: STATUS[stage], endedAt: Date.now() } : { status: STATUS[stage] })).catch(() => {});
+  console.log(`✅ Moved ${task.id} → ${stage}`);
+}
+
+
+/** Session-coupled transitions (start/stop) — see `pipeline-session.mjs`. */
+async function sessionCli(verb, marker, dest) {
+  const id = process.argv[3];
+  if (!id) { console.error(`Usage: pipeline.mjs ${verb} <id>`); process.exit(1); }
+  const sess = await import('./pipeline-session.mjs');
+  try {
+    const result = await (verb === 'start' ? sess.startTask : sess.stopTask)(PIPE, id, sync);
+    console.log(`${marker}  ${result.id} → ${dest}`);
+  } catch (err) { console.error(err.message); process.exit(1); }
+}
+
+function sync() {
+  ensureDirs();
+  const all = listTasks();
+  writeFileAtomicSync(resolve(PIPE, 'devpipeline.md'), renderBoard(all));
+  writeFileAtomicSync(resolve(PIPE, 'known-bugs.md'), renderKnownBugs(all));
+}
+
+/** Print + regenerate the known-bugs map. */
+function bugs() {
+  sync();
+  const open = listTasks().filter((t) => t.type === 'bug' && t.stage !== 'conclusion');
+  console.log(`🐞 Known bugs: ${open.length} open. Map → contextkit/pipeline/known-bugs.md`);
+  for (const b of open) console.log(`   ${b.severity || '—'} ${b.priority} ${b.id} ${b.bugType || ''} — ${b.title}`);
+}
+
+const cmd = process.argv[2];
+if (cmd === 'add') add();
+else if (cmd === 'ingest') ingest();
+else if (cmd === 'prioritize') prioritize();
+else if (cmd === 'wsjf') setWsjf();
+else if (cmd === 'bugs') bugs();
+else if (cmd === 'move') move();
+else if (cmd === 'start') await sessionCli('start', '▶', 'working/ (owner: this session)');
+else if (cmd === 'stop') await sessionCli('stop', '⏸', 'backlog/ (released)');
+else if (cmd === 'validate') { const t = listTasks(); const e = runValidate(t); e.length ? (e.forEach((m) => console.error(`✗ ${m}`)), process.exit(1)) : console.log(`✅ ${t.length} tickets validated.`); }
+else if (cmd === 'sync') {
+  sync();
+  console.log('✅ devpipeline.md regenerated.');
+} else if (cmd === 'list') {
+  const all = listTasks();
+  if (process.argv.includes('--json')) console.log(JSON.stringify(all, null, 2));
+  else for (const t of all) console.log(`[${t.stage}] ${t.id} ${t.priority} ${t.type} — ${t.title}`);
+} else {
+  console.error('Usage: pipeline.mjs <add|ingest|prioritize|wsjf|bugs|move|start|stop|validate|sync|list>');
+  process.exit(1);
+}

package/templates/contextkit/tools/scripts/playbook.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Playbook registry + runner (roadmap #8 / L6).
+ *
+ * Playbooks are the reusable procedures in `contextkit/workflows/playbooks/` — the
+ * "why / how / anti-patterns" behind a slash command. This turns that folder into
+ * a managed layer: list what exists (the registry), show one, and record a run so
+ * repeatable procedures become tracked, auditable assets. "Running" a playbook =
+ * recording the run and printing the procedure for the agent to follow; the steps
+ * themselves are executed by Claude, not this script.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/playbook.mjs list
+ *   node contextkit/tools/scripts/playbook.mjs show <name>
+ *   node contextkit/tools/scripts/playbook.mjs run  <name> [outcome note...]
+ *   node contextkit/tools/scripts/playbook.mjs runs
+ *
+ * Zero third-party deps; defensive (never throws fatally on a missing dir).
+ */
+import { existsSync, readdirSync, readFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const PLAYBOOKS_DIR = P.playbooks;
+const RUNS_LOG = resolve(P.memory, 'playbook-runs.md');
+
+/** All playbook files in the registry, sorted. */
+function listFiles() {
+  try {
+    return readdirSync(PLAYBOOKS_DIR).filter((f) => f.endsWith('.md')).sort();
+  } catch {
+    return [];
+  }
+}
+
+/** First `# ` heading of a playbook, as its human title. */
+function titleOf(file) {
+  try {
+    const heading = readFileSync(join(PLAYBOOKS_DIR, file), 'utf-8').split('\n').find((l) => l.startsWith('# '));
+    return heading ? heading.replace(/^#\s+/, '').trim() : file;
+  } catch {
+    return file;
+  }
+}
+
+/** Resolves a user-given name to an existing playbook file (exact or sans-.md). */
+function resolveName(name) {
+  if (!name) return null;
+  const files = listFiles();
+  const want = name.endsWith('.md') ? name : `${name}.md`;
+  return files.find((f) => f === want) || files.find((f) => f.replace(/\.md$/, '') === name) || null;
+}
+
+function unknown(name) {
+  console.error(`Unknown playbook "${name}". Try: playbook.mjs list`);
+  process.exit(1);
+}
+
+function list() {
+  const files = listFiles();
+  if (files.length === 0) {
+    console.log('No playbooks found in contextkit/workflows/playbooks/.');
+    return;
+  }
+  console.log(`📓 Playbooks (${files.length}) — contextkit/workflows/playbooks/\n`);
+  for (const f of files) console.log(`  • ${f.replace(/\.md$/, '')} — ${titleOf(f)}`);
+  console.log('\nRun one with:  node contextkit/tools/scripts/playbook.mjs run <name>');
+}
+
+function show(name) {
+  const file = resolveName(name);
+  if (!file) unknown(name);
+  console.log(`# contextkit/workflows/playbooks/${file}\n`);
+  console.log(readFileSync(join(PLAYBOOKS_DIR, file), 'utf-8'));
+}
+
+/** Records a run (best-effort) and prints the procedure for the agent to follow. */
+function run(name, note) {
+  const file = resolveName(name);
+  if (!file) unknown(name);
+  const when = new Date().toISOString();
+  try {
+    mkdirSync(P.memory, { recursive: true });
+    if (!existsSync(RUNS_LOG)) {
+      appendFileSync(RUNS_LOG, '# Playbook runs\n\n| When | Playbook | Note |\n| --- | --- | --- |\n', 'utf-8');
+    }
+    appendFileSync(RUNS_LOG, `| ${when} | ${file.replace(/\.md$/, '')} | ${note || '—'} |\n`, 'utf-8');
+  } catch {
+    /* tracking is best-effort — never block the run */
+  }
+  console.log(`▶️  Running playbook: ${file.replace(/\.md$/, '')} (recorded ${when.slice(0, 10)})`);
+  console.log('   Follow the procedure below and apply its judgment:\n');
+  console.log(readFileSync(join(PLAYBOOKS_DIR, file), 'utf-8'));
+}
+
+function runs() {
+  if (!existsSync(RUNS_LOG)) {
+    console.log('No playbook runs recorded yet.');
+    return;
+  }
+  console.log(readFileSync(RUNS_LOG, 'utf-8'));
+}
+
+function main() {
+  const [cmd, name, ...rest] = process.argv.slice(2);
+  switch (cmd) {
+    case 'list':
+      return list();
+    case 'show':
+      return show(name);
+    case 'run':
+      return run(name, rest.join(' '));
+    case 'runs':
+      return runs();
+    default:
+      console.error('Usage: playbook.mjs <list | show <name> | run <name> [note] | runs>');
+      process.exit(1);
+  }
+}
+
+main();

package/templates/contextkit/tools/scripts/predictions-review.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Closes the predicted-vs-actual loop (ancestor parity).
+ *
+ * `/simulate-impact` (mark-simulation.mjs) writes a prediction file per run with
+ * an empty "Actual" section. This script fills that section from the session
+ * ledger: the paths actually changed (`modifications[]`) compared against what
+ * the simulation predicted (`simulations[].coveredPaths`). It computes the delta
+ * in both directions so a later review can see where the prediction was right or
+ * wrong.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/predictions-review.mjs            # current session
+ *   node contextkit/tools/scripts/predictions-review.mjs <sessionId>
+ *
+ * Defensive: never throws fatally; exits 0 with a message when there is nothing
+ * to review. Zero third-party deps (hot-path invariant).
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { readLedger, readMostRecentLedger, toRepoRelative } from '../../runtime/hooks/ledger.mjs';
+
+const ROOT = process.cwd();
+const PREDICTIONS_PREFIX = 'contextkit/memory/predictions/';
+
+/** True when a covered entry (file, or dir prefix ending in `/`) matches a path. */
+function covers(coveredEntry, actualPath) {
+  if (coveredEntry.endsWith('/')) return actualPath.startsWith(coveredEntry);
+  return actualPath === coveredEntry;
+}
+
+/** Unique repo-relative paths this session actually changed (excludes prediction files). */
+function actualChangedPaths(ledger) {
+  const seen = new Set();
+  for (const mod of ledger.modifications || []) {
+    const rel = toRepoRelative(mod?.path);
+    if (!rel || rel.startsWith(PREDICTIONS_PREFIX)) continue;
+    seen.add(rel);
+  }
+  return [...seen];
+}
+
+const fmt = (paths) => (paths.length ? paths.map((p) => `\`${p}\``).join(', ') : '— none');
+
+/** Builds the filled "Actual" section for one prediction vs the actual changes. */
+function actualSection(covered, actual, date) {
+  const predictedHit = covered.filter((c) => actual.some((a) => covers(c, a)));
+  const predictedMiss = covered.filter((c) => !actual.some((a) => covers(c, a)));
+  const unforeseen = actual.filter((a) => !covered.some((c) => covers(c, a)));
+  return [
+    `## Actual (reviewed ${date})`,
+    '',
+    `- **Paths actually changed this session**: ${fmt(actual)}`,
+    `- **Predicted ✓ and changed**: ${fmt(predictedHit)}`,
+    `- **Predicted ✗ but NOT changed**: ${fmt(predictedMiss)}`,
+    `- **Changed but NOT predicted**: ${fmt(unforeseen)}`,
+    '- **Risk accuracy**: _was the `/simulate-impact` risk level right? note it here_',
+    '',
+  ].join('\n');
+}
+
+/** Replaces the trailing "## Actual" section (stub or prior review) in place. */
+function withActual(content, section) {
+  return /^## Actual/m.test(content)
+    ? content.replace(/^## Actual[\s\S]*$/m, section)
+    : `${content.trimEnd()}\n\n${section}`;
+}
+
+async function reviewOne(simulation, actual, date) {
+  const rel = simulation?.predictionFile;
+  if (typeof rel !== 'string' || !rel) return { skipped: true };
+  const abs = resolve(ROOT, rel);
+  let content;
+  try {
+    content = await readFile(abs, 'utf-8');
+  } catch {
+    return { skipped: true, rel };
+  }
+  const covered = Array.isArray(simulation.coveredPaths) ? simulation.coveredPaths : [];
+  await writeFile(abs, withActual(content, actualSection(covered, actual, date)), 'utf-8');
+  return { reviewed: true, rel };
+}
+
+async function main() {
+  const argSid = process.argv[2];
+  const found = argSid ? { sessionId: argSid, ledger: await readLedger(argSid) } : await readMostRecentLedger();
+  if (!found?.ledger) {
+    console.log('ℹ️  No session ledger found — nothing to review.');
+    return;
+  }
+  const simulations = (found.ledger.simulations || []).filter((s) => s?.predictionFile);
+  if (simulations.length === 0) {
+    console.log(`ℹ️  Session ${found.sessionId.slice(0, 8)} has no /simulate-impact predictions to review.`);
+    return;
+  }
+  const actual = actualChangedPaths(found.ledger);
+  const date = new Date().toISOString().slice(0, 10);
+  let reviewed = 0;
+  for (const simulation of simulations) {
+    const outcome = await reviewOne(simulation, actual, date);
+    if (outcome.reviewed) {
+      reviewed++;
+      console.log(`✅ Closed predicted-vs-actual loop: ${outcome.rel}`);
+    }
+  }
+  if (reviewed === 0) console.log('ℹ️  Prediction file(s) missing — nothing written.');
+  else console.log(`\n${reviewed} prediction(s) reviewed against ${actual.length} changed path(s).`);
+}
+
+main().catch((err) => {
+  console.error('❌ predictions-review failed:', err?.message ?? err);
+  process.exit(1);
+});