dw-kit 1.8.0-rc.2 → 1.9.0

package/src/lib/board-data.mjs

@@ -0,0 +1,220 @@
+// board-data.mjs — pure data builder for the `dw voice` Kanban board.
+//
+// Scans .dw/goals/*/goal.md, .dw/tasks/*/task.md (Section 3 Subtask Tracker),
+// and the session index. Returns a structured JSON object the browser page
+// can render as columns + cards. No I/O beyond reading these files; the
+// function is sync and unit-testable.
+//
+// Shape:
+//   {
+//     goals: [{
+//       goal_id, title, status, summary, icon, progress: {percent, ...},
+//       tasks: [{
+//         task_id, status, phase, parent_goal_id, target_ship,
+//         subtasks: [{ st_id, title, status_bucket, status_icon, date, notes }],
+//         path: '.dw/tasks/<id>/task.md',
+//       }],
+//     }],
+//     orphan_tasks: [...],   // tasks with no parent_goal_id or unknown parent
+//     sessions: [...],         // running + recent terminal (from session index)
+//     totals: { goals_active, tasks_active, subtasks_pending, subtasks_in_progress, subtasks_done, sessions_running },
+//     generated_at: ISO,
+//   }
+//
+// Per ADR-0001: zero-dep, Node built-ins + js-yaml.
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import yaml from 'js-yaml';
+import { listSessions } from './session-store.mjs';
+
+const GOALS_INDEX_PATH = '.dw/goals/goals-index.json';
+const GOALS_DIR = '.dw/goals';
+const TASKS_DIR = '.dw/tasks';
+const MAX_TASKS_PER_GOAL = 20;
+const MAX_SESSIONS = 20;
+
+// ─ Helpers ─────────────────────────────────────────────────────────────────
+
+function safeReadGoalsIndex(rootDir) {
+  const p = join(rootDir, GOALS_INDEX_PATH);
+  if (!existsSync(p)) return { goals: {} };
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return { goals: {} }; }
+}
+
+// Extract frontmatter (between --- markers) from a markdown file. Returns
+// an object via js-yaml, or {} if absent / malformed.
+function readFrontmatter(file) {
+  if (!existsSync(file)) return {};
+  let txt;
+  try { txt = readFileSync(file, 'utf8'); } catch { return {}; }
+  const m = txt.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  try { return yaml.load(m[1]) || {}; } catch { return {}; }
+}
+
+// Section 3 Subtask Tracker parser. Matches the `| ST-N | title | status | date | notes |`
+// row pattern used across the repo. Returns an array of subtask rows.
+const STATUS_ICONS = {
+  '⬜': 'pending',
+  '🟡': 'in_progress',
+  '✅': 'done',
+  '🔴': 'blocked',
+  '⏸': 'paused',
+};
+function parseSubtasks(taskPath) {
+  if (!existsSync(taskPath)) return [];
+  let txt;
+  try { txt = readFileSync(taskPath, 'utf8'); } catch { return []; }
+  const sec = txt.match(/^## 3\.[^\n]*\n([\s\S]*?)(?=^## 4\.|$(?![\s\S]))/m);
+  if (!sec) return [];
+  const out = [];
+  for (const line of sec[1].split('\n')) {
+    // | ST-1 | "Subtask title" | ✅ Done | 2026-05-25 | notes |
+    const m = line.match(/^\|\s*(ST-[\w.-]+)\s*\|\s*(.+?)\s*\|\s*([⬜🟡✅🔴⏸])\s*([A-Za-z ]+)?\s*\|\s*([^|]*)\|\s*([^|]*)\|/);
+    if (!m) continue;
+    const icon = m[3];
+    const statusBucket = STATUS_ICONS[icon] || 'unknown';
+    const statusLabel = (m[4] || '').trim();
+    out.push({
+      st_id: m[1].trim(),
+      title: m[2].replace(/`/g, '').trim(),
+      status_bucket: statusBucket,
+      status_icon: icon,
+      status_label: statusLabel,
+      date: m[5].trim(),
+      notes: m[6].trim().slice(0, 160),
+    });
+  }
+  return out;
+}
+
+function listTaskDirs(rootDir) {
+  const dir = join(rootDir, TASKS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((entry) => {
+      if (entry.startsWith('.') || entry === 'archive') return false;
+      try { return statSync(join(dir, entry)).isDirectory(); } catch { return false; }
+    });
+}
+
+// ─ Public API ──────────────────────────────────────────────────────────────
+
+export function buildBoardData(rootDir, opts = {}) {
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const idx = safeReadGoalsIndex(rootDir);
+  const goalsIndexEntries = Object.entries(idx.goals || {});
+
+  // Collect task -> goal mapping by scanning each task's frontmatter.
+  const taskDirs = listTaskDirs(rootDir);
+  const allTasks = [];
+  for (const taskName of taskDirs) {
+    const taskPath = join(rootDir, TASKS_DIR, taskName, 'task.md');
+    const fm = readFrontmatter(taskPath);
+    if (!fm || !fm.task_id) continue;
+    const subtasks = parseSubtasks(taskPath).slice(0, 30);
+    allTasks.push({
+      task_id: fm.task_id,
+      status: fm.status || 'Unknown',
+      phase: fm.phase || '',
+      parent_goal_id: fm.parent_goal_id || null,
+      target_ship: fm.target_ship || null,
+      last_updated: fm.last_updated || null,
+      schema_version: fm.schema_version || '',
+      path: `.dw/tasks/${taskName}/task.md`,
+      subtasks,
+    });
+  }
+
+  // Bucket tasks under goals.
+  const byGoal = new Map(); // goal_id → [task,...]
+  const orphans = [];
+  for (const t of allTasks) {
+    const pg = t.parent_goal_id;
+    if (pg && pg !== 'none' && idx.goals && idx.goals[pg]) {
+      if (!byGoal.has(pg)) byGoal.set(pg, []);
+      byGoal.get(pg).push(t);
+    } else {
+      orphans.push(t);
+    }
+  }
+
+  // Build goal cards.
+  const goals = [];
+  for (const [goal_id, g] of goalsIndexEntries) {
+    if (g.archived_at) continue; // hide archived
+    const tasks = (byGoal.get(goal_id) || []).slice(0, MAX_TASKS_PER_GOAL);
+    goals.push({
+      goal_id,
+      title: g.title || goal_id,
+      status: g.status || 'Active',
+      summary: (g.summary || '').slice(0, 280),
+      icon: g.icon || '',
+      cycle: g.cycle || '',
+      target_date: g.target_date || null,
+      progress: g.progress || null,
+      last_updated: g.last_updated || null,
+      linked_task_ids: g.linked_task_ids || [],
+      tasks,
+    });
+  }
+
+  // Sort goals: Active first, then by last_updated desc, with North-Star (cycle:north-star) pinned to top.
+  goals.sort((a, b) => {
+    const aN = a.cycle === 'north-star' ? 0 : 1;
+    const bN = b.cycle === 'north-star' ? 0 : 1;
+    if (aN !== bN) return aN - bN;
+    const aA = a.status === 'Active' ? 0 : 1;
+    const bA = b.status === 'Active' ? 0 : 1;
+    if (aA !== bA) return aA - bA;
+    return (b.last_updated || '').localeCompare(a.last_updated || '');
+  });
+
+  // Sessions (running first, then recent terminal capped at MAX_SESSIONS).
+  let sessions = [];
+  try {
+    sessions = listSessions({}, rootDir).slice(0, MAX_SESSIONS);
+  } catch { /* ignore */ }
+  sessions = sessions.map((s) => ({
+    session_id: s.session_id,
+    agent: s.agent,
+    status: s.status,
+    goal_preview: typeof s.goal === 'string' ? s.goal.slice(0, 80) : '',
+    started_at: s.started_at,
+    workspace_path: s.workspace_path,
+  }));
+
+  // Totals.
+  const totals = {
+    goals_active: goals.filter((g) => g.status === 'Active').length,
+    goals_total: goals.length,
+    tasks_active: allTasks.filter((t) => t.status === 'Active').length,
+    tasks_total: allTasks.length,
+    subtasks_pending: 0,
+    subtasks_in_progress: 0,
+    subtasks_done: 0,
+    subtasks_blocked: 0,
+    sessions_running: sessions.filter((s) => s.status === 'running').length,
+    sessions_total: sessions.length,
+  };
+  for (const t of allTasks) {
+    for (const st of t.subtasks) {
+      if (st.status_bucket === 'pending') totals.subtasks_pending++;
+      else if (st.status_bucket === 'in_progress') totals.subtasks_in_progress++;
+      else if (st.status_bucket === 'done') totals.subtasks_done++;
+      else if (st.status_bucket === 'blocked') totals.subtasks_blocked++;
+    }
+  }
+
+  return {
+    goals,
+    orphan_tasks: orphans.slice(0, MAX_TASKS_PER_GOAL),
+    sessions,
+    totals,
+    generated_at: new Date(now).toISOString().replace(/\.\d+Z$/, 'Z'),
+  };
+}
+
+// Exposed for tests.
+export const _internals = { parseSubtasks, readFrontmatter, listTaskDirs };

package/src/lib/debate.mjs

@@ -0,0 +1,325 @@
+// debate.mjs — multi-agent live debate (ADR-0015, KR-D of G-rgoal-realtime-orch).
+//
+// Spawn 2+ agents in parallel with a shared debate prompt; stream each agent's
+// reply to events-global.jsonl as soon as it lands so the SSE broker can fan
+// it out to the browser. No automated arbitration — the user is the tie-breaker
+// for MVP. v2.0+ may add consensus scoring.
+//
+// Per ADR-0001: zero-dep, Node built-ins only. Reuses sse-broker.mjs +
+// goal-events.mjs (events-global.jsonl write pattern).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import yaml from 'js-yaml';
+import {
+  createSession, updateSessionStatus, appendEvent, listSessions,
+} from './session-store.mjs';
+import { resolveCommandPath, spawnAgent } from './spawn-helpers.mjs';
+import { logGoalEvent } from './goal-events.mjs';
+import { collectContext } from './orchestrator.mjs';
+
+const AGENTS_CONFIG_PATH = '.dw/config/agents.yml';
+const DEFAULT_TIMEOUT_MS = 30000;
+const MAX_TOPIC_CHARS = 1000;
+const PROMPT_MAX_CHARS = 8000;
+
+function loadAgentsConfig(rootDir) {
+  const p = join(rootDir, AGENTS_CONFIG_PATH);
+  if (!existsSync(p)) return { agents: {} };
+  return yaml.load(readFileSync(p, 'utf8')) || { agents: {} };
+}
+
+/**
+ * Resolve the debate roster from agents.yml.
+ *
+ * Config shape (under top-level `voice_debate:`):
+ *   roster: [claude, codex]
+ *   timeout_ms: 30000
+ *
+ * Falls back to [claude, codex] when unset. Validates that every roster
+ * entry has a corresponding `agents.{name}` definition.
+ */
+export function resolveDebateRoster(rootDir) {
+  const cfg = loadAgentsConfig(rootDir);
+  const wanted = (cfg.voice_debate && Array.isArray(cfg.voice_debate.roster) && cfg.voice_debate.roster.length > 0)
+    ? cfg.voice_debate.roster
+    : ['claude', 'codex'];
+  const available = wanted.filter((name) => cfg.agents && cfg.agents[name] && cfg.agents[name].command);
+  return {
+    roster: available,
+    timeout_ms: Number(cfg.voice_debate?.timeout_ms) || DEFAULT_TIMEOUT_MS,
+    agents: cfg.agents || {},
+  };
+}
+
+export function generateDebateId() {
+  return 'D-' + randomBytes(6).toString('hex');
+}
+
+/**
+ * Compose the debate system prompt seen by EACH agent. We tell every agent
+ * who their peer is so they can phrase replies as "I agree / I disagree
+ * because ..." rather than monologue. Workspace context is included via
+ * collectContext() so agents can ground their answer in real state.
+ */
+export function buildDebatePrompt({ topic, agentName, peerNames, lang = 'en-US', rootDir }) {
+  const ctx = collectContext(rootDir, topic, lang);
+  const langHint = lang.startsWith('vi')
+    ? `Người dùng nói tiếng Việt. Trả lời tiếng Việt, ≤3 câu, không preamble.`
+    : `Reply in ${lang}, ≤3 sentences, no preamble.`;
+  const peers = peerNames.join(', ');
+  const prompt = [
+    `You are ${agentName}, one of ${peerNames.length + 1} AI agents debating live in a voice session.`,
+    `Your peers on this debate: ${peers}.`,
+    `The user wants multiple perspectives, then chooses themselves — do NOT defer to your peer; state your own view.`,
+    ``,
+    langHint,
+    ``,
+    `Workspace context (read-only):`,
+    `- sessions running: ${ctx.sessionsRunning} / total: ${ctx.sessionsTotal}`,
+    `- goals active: ${ctx.goalsActive} / total: ${ctx.goalsTotal}`,
+    ``,
+    `Debate topic from the user: ${topic}`,
+    ``,
+    `Reply with YOUR position. Be concrete. If you'd recommend an action, end with [ACTION: <name> args] following ADR-0014 — but only ONE agent's action will execute (first user-confirm wins).`,
+  ].join('\n').slice(0, PROMPT_MAX_CHARS);
+  return prompt;
+}
+
+/**
+ * Kick off a debate. Spawns every roster agent in parallel; each agent's
+ * lifecycle (started / replied / failed / timed_out) writes to
+ * .dw/events-global.jsonl tagged with `debate_id` so the SSE broker can
+ * fan frames to the browser. Also creates a parent audit session
+ * `voice-debate:<topic-slug>` so `dw session show <id>` works for replay.
+ *
+ * Returns synchronously after spawning: { ok, debate_id, agents: [...], sessionId }.
+ * Replies arrive on the SSE stream, not in this return value.
+ */
+export function startDebate({ topic, rootDir, lang = 'en-US', timeoutMsOverride }) {
+  if (!topic || typeof topic !== 'string') {
+    return { ok: false, error: 'debate topic missing' };
+  }
+  const cleanTopic = topic.trim().slice(0, MAX_TOPIC_CHARS);
+  if (!cleanTopic) return { ok: false, error: 'debate topic empty after trim' };
+
+  const { roster, timeout_ms, agents } = resolveDebateRoster(rootDir);
+  if (roster.length < 2) {
+    return { ok: false, error: `debate needs ≥2 agents on PATH; available: ${roster.join(',') || '(none)'}` };
+  }
+
+  const debate_id = generateDebateId();
+  const timeoutMs = Number(timeoutMsOverride) || timeout_ms;
+
+  // Parent audit session — one .dw/cache/sessions/ entry per debate.
+  const topicSlug = cleanTopic.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'debate';
+  const auditSession = createSession({
+    agent: `voice-debate:${topicSlug}`,
+    goal: `[debate] ${cleanTopic}`,
+    workspacePath: rootDir,
+    command: ['debate', ...roster],
+  }, rootDir);
+
+  // Global event: debate_started.
+  logGoalEvent({
+    event: 'debate_started',
+    debate_id,
+    topic: cleanTopic,
+    roster,
+    lang,
+    audit_session_id: auditSession.session_id,
+  }, rootDir);
+  appendEvent(auditSession.session_id, {
+    event: 'debate_started', debate_id, topic: cleanTopic, roster, lang,
+  }, rootDir);
+
+  // Spawn each agent in parallel — fire-and-forget at the dispatch level;
+  // sse-broker tails events-global.jsonl so each agent's completion frame
+  // reaches the browser asynchronously.
+  const agentMeta = [];
+  for (const agentName of roster) {
+    const def = agents[agentName];
+    const peerNames = roster.filter((a) => a !== agentName);
+    const prompt = buildDebatePrompt({ topic: cleanTopic, agentName, peerNames, lang, rootDir });
+    const meta = spawnDebateAgent({
+      debate_id, agentName, def, prompt, timeoutMs, rootDir, auditSessionId: auditSession.session_id,
+    });
+    agentMeta.push(meta);
+  }
+
+  return {
+    ok: true,
+    debate_id,
+    agents: agentMeta.map((m) => ({ agent: m.agent, ok: m.ok, pid: m.pid || null, error: m.error || null })),
+    sessionId: auditSession.session_id,
+    timeout_ms: timeoutMs,
+  };
+}
+
+/**
+ * Spawn one agent for a debate. Captures stdout/stderr in-memory (debate
+ * replies are short, ≤4KB after our prompt caps); on exit writes a
+ * `debate_agent_replied` or `debate_agent_failed` event with the full
+ * reply + timing so the SSE broker can broadcast it.
+ *
+ * Synchronous return: { agent, ok, pid?, error? }. Reply arrives later
+ * via events-global.jsonl.
+ */
+function spawnDebateAgent({ debate_id, agentName, def, prompt, timeoutMs, rootDir, auditSessionId }) {
+  if (!def || !def.command) {
+    logGoalEvent({
+      event: 'debate_agent_failed', debate_id, agent: agentName,
+      error: `agent "${agentName}" not configured in agents.yml`,
+    }, rootDir);
+    return { agent: agentName, ok: false, error: 'not configured' };
+  }
+  const resolved = resolveCommandPath(def.command);
+  if (!resolved.found && process.platform === 'win32') {
+    logGoalEvent({
+      event: 'debate_agent_failed', debate_id, agent: agentName,
+      error: `agent CLI "${def.command}" not on PATH`,
+    }, rootDir);
+    return { agent: agentName, ok: false, error: 'not on PATH' };
+  }
+
+  const args = [...(def.args || [])];
+  const mode = def.goal_mode || 'trailing-arg';
+  if (mode === 'trailing-arg') args.push(prompt);
+
+  const startedAt = Date.now();
+  let child;
+  try {
+    child = spawnAgent(resolved, args, {
+      cwd: rootDir,
+      stdio: [mode === 'stdin' ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+      env: { ...process.env, ...(def.env || {}) },
+      windowsHide: true,
+    });
+  } catch (e) {
+    logGoalEvent({
+      event: 'debate_agent_failed', debate_id, agent: agentName, error: `spawn failed: ${e.message}`,
+    }, rootDir);
+    return { agent: agentName, ok: false, error: e.message };
+  }
+
+  logGoalEvent({
+    event: 'debate_agent_started', debate_id, agent: agentName, pid: child.pid,
+  }, rootDir);
+  appendEvent(auditSessionId, {
+    event: 'debate_agent_started', debate_id, agent: agentName, pid: child.pid,
+  }, rootDir);
+
+  if (mode === 'stdin') {
+    try { child.stdin.write(prompt + '\n'); child.stdin.end(); }
+    catch { /* harmless — child may already have exited */ }
+  }
+
+  let stdout = '';
+  let stderr = '';
+  let settled = false;
+  const timer = setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    try { child.kill('SIGTERM'); } catch { /* harmless */ }
+    logGoalEvent({
+      event: 'debate_agent_failed', debate_id, agent: agentName,
+      error: `timeout after ${timeoutMs}ms`,
+      ms: Date.now() - startedAt,
+    }, rootDir);
+    appendEvent(auditSessionId, {
+      event: 'debate_agent_failed', debate_id, agent: agentName,
+      error: 'timeout', ms: Date.now() - startedAt,
+    }, rootDir);
+  }, timeoutMs);
+
+  child.stdout.on('data', (c) => { stdout += c.toString(); });
+  child.stderr.on('data', (c) => { stderr += c.toString(); });
+
+  child.on('exit', (code) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    const ms = Date.now() - startedAt;
+    const reply = stdout.trim();
+    if (code === 0 && reply.length > 0) {
+      logGoalEvent({
+        event: 'debate_agent_replied',
+        debate_id, agent: agentName, ms,
+        reply: reply.slice(0, 4000),
+        reply_chars: reply.length,
+      }, rootDir);
+      appendEvent(auditSessionId, {
+        event: 'debate_agent_replied', debate_id, agent: agentName, ms,
+        reply_preview: reply.slice(0, 4000),
+      }, rootDir);
+    } else {
+      logGoalEvent({
+        event: 'debate_agent_failed',
+        debate_id, agent: agentName,
+        error: (stderr.trim() || `exit ${code} with empty stdout`).slice(0, 500),
+        exit_code: code, ms,
+      }, rootDir);
+      appendEvent(auditSessionId, {
+        event: 'debate_agent_failed', debate_id, agent: agentName,
+        error: stderr.slice(0, 500) || `exit ${code}`,
+        exit_code: code, ms,
+      }, rootDir);
+    }
+    maybeMarkComplete({ debate_id, auditSessionId, rootDir });
+  });
+
+  child.on('error', (e) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    logGoalEvent({
+      event: 'debate_agent_failed', debate_id, agent: agentName, error: e.message,
+    }, rootDir);
+    appendEvent(auditSessionId, {
+      event: 'debate_agent_failed', debate_id, agent: agentName, error: e.message,
+    }, rootDir);
+    maybeMarkComplete({ debate_id, auditSessionId, rootDir });
+  });
+
+  return { agent: agentName, ok: true, pid: child.pid };
+}
+
+/**
+ * Inspect events-global.jsonl and emit `debate_completed` once every
+ * roster agent has either replied or failed. Cheap O(tail) scan.
+ */
+function maybeMarkComplete({ debate_id, auditSessionId, rootDir }) {
+  try {
+    const file = join(rootDir, '.dw/events-global.jsonl');
+    if (!existsSync(file)) return;
+    const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean).slice(-500);
+    let rosterSize = 0;
+    let terminalCount = 0;
+    const agentsTerminal = new Set();
+    for (const line of lines) {
+      try {
+        const e = JSON.parse(line);
+        if (e.debate_id !== debate_id) continue;
+        if (e.event === 'debate_started') rosterSize = Array.isArray(e.roster) ? e.roster.length : 0;
+        if ((e.event === 'debate_agent_replied' || e.event === 'debate_agent_failed') && e.agent && !agentsTerminal.has(e.agent)) {
+          agentsTerminal.add(e.agent);
+          terminalCount++;
+        }
+        if (e.event === 'debate_completed') return; // already marked
+      } catch { /* skip */ }
+    }
+    if (rosterSize > 0 && terminalCount >= rosterSize) {
+      logGoalEvent({
+        event: 'debate_completed', debate_id, agents: Array.from(agentsTerminal),
+      }, rootDir);
+      appendEvent(auditSessionId, {
+        event: 'debate_completed', debate_id, agents: Array.from(agentsTerminal),
+      }, rootDir);
+      updateSessionStatus(auditSessionId, { status: 'completed' }, rootDir);
+    }
+  } catch { /* best-effort */ }
+}
+
+// Exposed for tests
+export const _internals = { buildDebatePrompt, spawnDebateAgent, maybeMarkComplete };

package/src/lib/decision-store.mjs

@@ -0,0 +1,146 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// DW Document Schema + Index v1.0 — decisions (ADR) half (ADR-0017 v1.1).
+// ADRs use TWO metadata styles in the wild:
+//   - YAML frontmatter (early ADRs, e.g. ADR-0001)
+//   - markdown headers `# ADR-NNNN: Title` + `## Status:` / `## Date:` / ...
+// The parser tolerates both so external adapters consume one normalized index.
+
+const DECISIONS_DIR = '.dw/decisions';
+const INDEX_FILE = '.dw/decisions/decisions-index.json';
+const SCHEMA_VERSION = 'decisions-index@v1';
+const STATUS_KEYWORDS = ['Proposed', 'Accepted', 'Deprecated', 'Superseded'];
+
+export function decisionsDir(rootDir = process.cwd()) {
+  return join(rootDir, DECISIONS_DIR);
+}
+
+export function decisionIndexFile(rootDir = process.cwd()) {
+  return join(rootDir, INDEX_FILE);
+}
+
+function nowUtc() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+function emptyIndex() {
+  return { schema_version: SCHEMA_VERSION, last_updated: nowUtc(), decisions: {} };
+}
+
+export function readDecisionIndex(rootDir = process.cwd()) {
+  const file = decisionIndexFile(rootDir);
+  if (!existsSync(file)) return emptyIndex();
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || !parsed.decisions) return emptyIndex();
+    return parsed;
+  } catch {
+    return emptyIndex();
+  }
+}
+
+export function writeDecisionIndex(index, rootDir = process.cwd()) {
+  const file = decisionIndexFile(rootDir);
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const updated = { ...index, schema_version: SCHEMA_VERSION, last_updated: nowUtc() };
+  writeFileSync(file, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+}
+
+// .dw/decisions/NNNN-slug.md → { id: 'ADR-NNNN', num: 'NNNN', file }
+export function listDecisionFiles(rootDir = process.cwd()) {
+  const dir = decisionsDir(rootDir);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.md')) continue;
+    if (name.startsWith('_')) continue; // _template.md
+    const m = name.match(/^(\d{3,4})-/);
+    if (!m) continue;
+    out.push({ id: `ADR-${m[1]}`, num: m[1], file: join(dir, name), rel: `${DECISIONS_DIR}/${name}` });
+  }
+  return out;
+}
+
+function firstDate(s) {
+  if (!s) return null;
+  const m = String(s).match(/\d{4}-\d{2}-\d{2}/);
+  return m ? m[0] : null;
+}
+
+function normalizeStatus(raw) {
+  if (!raw) return { status: 'Proposed', superseded_by: null };
+  const text = String(raw);
+  const kw = STATUS_KEYWORDS.find((k) => new RegExp(`^\\s*${k}`, 'i').test(text));
+  const status = kw || (/superseded/i.test(text) ? 'Superseded' : 'Proposed');
+  const sb = text.match(/superseded by\s+(ADR-\d{3,4})/i);
+  return { status, superseded_by: sb ? sb[1] : null };
+}
+
+function adrRefs(s, selfId) {
+  if (!s) return [];
+  const refs = [...String(s).matchAll(/ADR-\d{3,4}/g)].map((m) => m[0]);
+  return [...new Set(refs)].filter((r) => r !== selfId);
+}
+
+function mdHeader(content, label) {
+  const m = content.match(new RegExp(`^##\\s+${label}:\\s*(.+)$`, 'm'));
+  return m ? m[1].trim() : null;
+}
+
+// Tolerant extractor: YAML frontmatter wins; falls back to markdown headers.
+export function parseDecisionMeta(id, content) {
+  const fm = parseFrontmatter(content);
+  const hasFm = fm && (fm.status || fm.title || fm.id);
+
+  const title = (hasFm && fm.title)
+    || (content.match(/^#\s+ADR-\d{3,4}:\s*(.+?)\s*$/m)?.[1])
+    || (content.match(/^#\s+(.+?)\s*$/m)?.[1])
+    || id;
+
+  const rawStatus = (hasFm && fm.status) || mdHeader(content, 'Status');
+  const { status, superseded_by } = normalizeStatus(rawStatus);
+
+  const date = firstDate((hasFm && fm.date) || mdHeader(content, 'Date'));
+  const deciders = ((hasFm && fm.deciders) || mdHeader(content, 'Deciders') || null);
+
+  const relatedSrc = `${(hasFm && fm.related) || mdHeader(content, 'Related') || ''} ${rawStatus || ''}`;
+  const related = adrRefs(relatedSrc, id);
+  const supersedes = hasFm && fm.supersedes && fm.supersedes !== 'null'
+    ? adrRefs(String(fm.supersedes), id)
+    : [];
+
+  return {
+    title: String(title).trim(),
+    status,
+    status_raw: rawStatus ? String(rawStatus).trim() : null,
+    date,
+    deciders: deciders ? String(deciders).trim() : null,
+    related,
+    supersedes,
+    superseded_by: superseded_by || (hasFm && fm['superseded-by'] && fm['superseded-by'] !== 'null' ? String(fm['superseded-by']) : null),
+  };
+}
+
+function decisionEntry(file, id, rootDir) {
+  if (!existsSync(file)) return null;
+  const content = readFileSync(file, 'utf8');
+  const meta = parseDecisionMeta(id, content);
+  return { ...meta, file: `${DECISIONS_DIR}/${file.split(/[\\/]/).pop()}` };
+}
+
+export function rebuildDecisionIndex(rootDir = process.cwd()) {
+  const index = emptyIndex();
+  for (const d of listDecisionFiles(rootDir)) {
+    const entry = decisionEntry(d.file, d.id, rootDir);
+    if (entry) index.decisions[d.id] = entry;
+  }
+  const existing = readDecisionIndex(rootDir);
+  if (JSON.stringify(existing.decisions) === JSON.stringify(index.decisions)) {
+    return existing;
+  }
+  writeDecisionIndex(index, rootDir);
+  return index;
+}