dw-kit 1.4.0 → 1.7.0-rc.1

package/src/lib/goal-store.mjs

@@ -0,0 +1,202 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parseFrontmatter, stringifyFrontmatter } from './frontmatter.mjs';
+
+const GOALS_DIR = '.dw/goals';
+const INDEX_FILE = '.dw/goals/goals-index.json';
+const TASKS_DIR = '.dw/tasks';
+
+export function goalsDir(rootDir = process.cwd()) {
+  return join(rootDir, GOALS_DIR);
+}
+
+export function goalDir(goalId, rootDir = process.cwd()) {
+  return join(rootDir, GOALS_DIR, goalId);
+}
+
+export function goalFile(goalId, rootDir = process.cwd()) {
+  return join(rootDir, GOALS_DIR, goalId, 'goal.md');
+}
+
+export function goalIndexFile(rootDir = process.cwd()) {
+  return join(rootDir, INDEX_FILE);
+}
+
+export function readGoalIndex(rootDir = process.cwd()) {
+  const file = goalIndexFile(rootDir);
+  if (!existsSync(file)) {
+    return {
+      schema_version: 'goals-index@v1',
+      last_updated: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+      goals: {},
+    };
+  }
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return { schema_version: 'goals-index@v1', last_updated: new Date().toISOString().replace(/\.\d+Z$/, 'Z'), goals: {} };
+  }
+}
+
+export function writeGoalIndex(index, rootDir = process.cwd()) {
+  const file = goalIndexFile(rootDir);
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const updated = {
+    ...index,
+    last_updated: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+  };
+  writeFileSync(file, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+}
+
+export function readGoal(goalId, rootDir = process.cwd()) {
+  const file = goalFile(goalId, rootDir);
+  if (!existsSync(file)) return null;
+  const content = readFileSync(file, 'utf8');
+  const fm = parseFrontmatter(content);
+  return { fm, content, file };
+}
+
+export function writeGoal(goalId, frontmatter, body, rootDir = process.cwd()) {
+  const file = goalFile(goalId, rootDir);
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(file, stringifyFrontmatter(frontmatter) + body, 'utf8');
+}
+
+export function updateGoalFrontmatter(goalId, mutator, rootDir = process.cwd()) {
+  const existing = readGoal(goalId, rootDir);
+  if (!existing) throw new Error(`Goal ${goalId} not found`);
+  const next = mutator({ ...existing.fm });
+  const body = existing.content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  writeGoal(goalId, next, body, rootDir);
+  return next;
+}
+
+export function listGoalIds(rootDir = process.cwd()) {
+  const dir = goalsDir(rootDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((entry) => {
+      try {
+        const path = join(dir, entry);
+        return statSync(path).isDirectory() && existsSync(join(path, 'goal.md'));
+      } catch { return false; }
+    });
+}
+
+export function syncIndexEntry(goalId, rootDir = process.cwd()) {
+  const goal = readGoal(goalId, rootDir);
+  if (!goal) return null;
+  const index = readGoalIndex(rootDir);
+  const linkedTasks = findLinkedTaskIds(goalId, rootDir);
+  const progress = computeGoalProgress(goalId, rootDir, linkedTasks);
+  index.goals[goalId] = {
+    title: extractTitle(goal.content) || goalId,
+    status: goal.fm.status || 'Draft',
+    owner: goal.fm.owner || 'unknown',
+    icon: goal.fm.icon || '🎯',
+    cycle: goal.fm.cycle || null,
+    summary: goal.fm.summary || null,
+    target_date: goal.fm.target_date || null,
+    goal_version: goal.fm.goal_version || 1,
+    archived_at: goal.fm.archived_at || null,
+    parent_goal_id: goal.fm.parent_goal_id || null,
+    linked_task_ids: linkedTasks,
+    progress,
+    last_updated: goal.fm.last_updated || new Date().toISOString().slice(0, 10),
+  };
+  writeGoalIndex(index, rootDir);
+  return index.goals[goalId];
+}
+
+export function computeGoalProgress(goalId, rootDir = process.cwd(), linkedTasksList = null) {
+  const linkedTasks = linkedTasksList || findLinkedTaskIds(goalId, rootDir);
+  if (linkedTasks.length === 0) return { percent: 0, total: 0, done: 0, in_progress: 0, blocked: 0, pending: 0 };
+
+  let total = 0;
+  let done = 0;
+  let inProgress = 0;
+  let blocked = 0;
+  let pending = 0;
+
+  for (const taskId of linkedTasks) {
+    const taskFile = join(rootDir, TASKS_DIR, taskId, 'task.md');
+    if (!existsSync(taskFile)) continue;
+    const content = readFileSync(taskFile, 'utf8');
+    const tracker = extractTrackerSection(content);
+    for (const row of parseTrackerRows(tracker)) {
+      total++;
+      if (row.status.includes('✅') || /Done/i.test(row.status)) done++;
+      else if (row.status.includes('🟡') || /In Progress/i.test(row.status)) inProgress++;
+      else if (row.status.includes('🔴') || /Blocked/i.test(row.status)) blocked++;
+      else pending++;
+    }
+  }
+
+  const percent = total === 0 ? 0 : Math.round((done / total) * 100);
+  return { percent, total, done, in_progress: inProgress, blocked, pending };
+}
+
+function extractTrackerSection(content) {
+  const m = content.match(/##\s+3\.\s+Subtask Tracker[\s\S]*?(?=^##\s+\d|\Z)/m);
+  return m ? m[0] : '';
+}
+
+function parseTrackerRows(section) {
+  const rows = [];
+  const lines = section.split('\n');
+  for (const line of lines) {
+    // Match table rows like: | ST-N | Description | Status | Date | Notes |
+    if (!/^\|\s*(ST|WS)-/.test(line)) continue;
+    const cells = line.split('|').map((c) => c.trim());
+    if (cells.length < 4) continue;
+    // cells[0] = "" (before first |), [1] = ID, [2] = subtask, [3] = status
+    rows.push({ id: cells[1], subtask: cells[2], status: cells[3] || '', date: cells[4] || '', notes: cells[5] || '' });
+  }
+  return rows;
+}
+
+export function removeIndexEntry(goalId, rootDir = process.cwd()) {
+  const index = readGoalIndex(rootDir);
+  if (index.goals[goalId]) {
+    delete index.goals[goalId];
+    writeGoalIndex(index, rootDir);
+    return true;
+  }
+  return false;
+}
+
+export function findLinkedTaskIds(goalId, rootDir = process.cwd()) {
+  const tasksRoot = join(rootDir, TASKS_DIR);
+  if (!existsSync(tasksRoot)) return [];
+  const linked = [];
+  for (const entry of readdirSync(tasksRoot)) {
+    if (entry === 'archive' || entry === 'ACTIVE.md') continue;
+    const taskFile = join(tasksRoot, entry, 'task.md');
+    if (!existsSync(taskFile)) continue;
+    try {
+      const fm = parseFrontmatter(readFileSync(taskFile, 'utf8'));
+      if (fm.parent_goal_id === goalId) linked.push(entry);
+      else if (Array.isArray(fm.contributing_goal_ids) && fm.contributing_goal_ids.includes(goalId)) linked.push(entry);
+    } catch { /* skip */ }
+  }
+  return linked;
+}
+
+function extractTitle(content) {
+  const m = content.match(/^#\s+Goal:\s+(.+?)\s*$/m) || content.match(/^#\s+(.+?)\s*$/m);
+  return m ? m[1].trim() : null;
+}
+
+export function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function nowUtc() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+export function validateGoalId(goalId) {
+  return /^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$/.test(goalId);
+}

package/src/lib/goal-svg.mjs

@@ -0,0 +1,293 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readGoal, findLinkedTaskIds, computeGoalProgress } from './goal-store.mjs';
+
+const TASKS_DIR = '.dw/tasks';
+
+const STATUS_COLOR = {
+  Draft: '#6b7280',
+  Active: '#0ea5e9',
+  Achieved: '#10b981',
+  Abandoned: '#ef4444',
+  Pivoted: '#f59e0b',
+  Pending: '#6b7280',
+  'In Progress': '#f59e0b',
+  Blocked: '#dc2626',
+  Done: '#10b981',
+  Paused: '#a855f7',
+};
+
+function esc(s) {
+  if (s == null) return '';
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function extractKeyResults(content) {
+  // Find "## 3. Key Results & Linked Tasks Tracker" → "### Key Results" → table
+  const krSectionMatch = content.match(/###\s+Key Results[\s\S]*?(?=^###\s+|^##\s+|\Z)/m);
+  if (!krSectionMatch) return [];
+  const krBlock = krSectionMatch[0];
+  const krs = [];
+  for (const line of krBlock.split('\n')) {
+    if (!/^\|\s*KR-/.test(line)) continue;
+    const cells = line.split('|').map((c) => c.trim());
+    if (cells.length < 5) continue;
+    krs.push({
+      id: cells[1],
+      description: cells[2],
+      target: cells[3] || '',
+      current: cells[4] || '',
+      status: cells[5] || '⬜ Pending',
+    });
+  }
+  return krs;
+}
+
+function statusFromGlyph(status) {
+  if (status.includes('✅') || /Done|Achieved/i.test(status)) return 'Done';
+  if (status.includes('🟡') || /In Progress/i.test(status)) return 'In Progress';
+  if (status.includes('🔴') || /Blocked/i.test(status)) return 'Blocked';
+  if (status.includes('⏸') || /Paused/i.test(status)) return 'Paused';
+  return 'Pending';
+}
+
+function readTaskInfo(taskId, rootDir) {
+  const file = join(rootDir, TASKS_DIR, taskId, 'task.md');
+  if (!existsSync(file)) return { id: taskId, status: 'Unknown', subtaskCount: 0, doneCount: 0 };
+  const content = readFileSync(file, 'utf8');
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  let status = 'Draft';
+  if (fmMatch) {
+    const statusLine = fmMatch[1].match(/^status:\s*(.+?)$/m);
+    if (statusLine) status = statusLine[1].trim();
+  }
+  // Count subtasks in Section 3
+  const trackerMatch = content.match(/##\s+3\.\s+Subtask Tracker[\s\S]*?(?=^##\s+\d|\Z)/m);
+  let subtaskCount = 0;
+  let doneCount = 0;
+  if (trackerMatch) {
+    for (const line of trackerMatch[0].split('\n')) {
+      if (!/^\|\s*(ST|WS)-/.test(line)) continue;
+      subtaskCount++;
+      if (line.includes('✅')) doneCount++;
+    }
+  }
+  return { id: taskId, status, subtaskCount, doneCount };
+}
+
+/**
+ * Render goal as constellation SVG.
+ * - Center: goal node (large) with icon + ID + progress arc
+ * - Inner orbit: Key Results (parsed from Section 3 table)
+ * - Outer orbit per KR: linked tasks
+ *
+ * Pure SVG string — no external deps.
+ *
+ * @param {string} goalId
+ * @param {string} rootDir
+ * @returns {string} SVG markup
+ */
+export function renderGoalSvg(goalId, rootDir = process.cwd()) {
+  const goal = readGoal(goalId, rootDir);
+  if (!goal) {
+    return errorSvg(`Goal ${goalId} not found`);
+  }
+
+  const linkedTasks = findLinkedTaskIds(goalId, rootDir);
+  const taskInfos = linkedTasks.map((t) => readTaskInfo(t, rootDir));
+  const krs = extractKeyResults(goal.content);
+  const progress = computeGoalProgress(goalId, rootDir, linkedTasks);
+
+  const W = 880;
+  const H = 600;
+  const cx = W / 2;
+  const cy = H / 2;
+  const goalRadius = 70;
+  const krOrbit = 180;
+  const taskOrbit = 80; // from each KR
+
+  const goalColor = STATUS_COLOR[goal.fm.status] || STATUS_COLOR.Draft;
+  const icon = goal.fm.icon || '🎯';
+
+  // KR satellite positions on circle around center
+  const krCount = Math.max(krs.length, 1);
+  const krNodes = krs.map((kr, i) => {
+    const angle = (Math.PI * 2 * i) / krCount - Math.PI / 2;
+    return {
+      ...kr,
+      x: cx + Math.cos(angle) * krOrbit,
+      y: cy + Math.sin(angle) * krOrbit,
+      angle,
+      status_canonical: statusFromGlyph(kr.status),
+    };
+  });
+
+  // Task leaves distributed evenly around their nearest KR (or directly around goal if no KRs)
+  const taskNodes = [];
+  if (krs.length === 0 && taskInfos.length > 0) {
+    // Tasks orbit goal directly when no KRs defined
+    const tCount = taskInfos.length;
+    taskInfos.forEach((t, i) => {
+      const angle = (Math.PI * 2 * i) / tCount - Math.PI / 2;
+      taskNodes.push({
+        ...t,
+        parentX: cx,
+        parentY: cy,
+        x: cx + Math.cos(angle) * (krOrbit + 30),
+        y: cy + Math.sin(angle) * (krOrbit + 30),
+      });
+    });
+  } else if (krs.length > 0 && taskInfos.length > 0) {
+    // Distribute tasks around KR satellites (round-robin)
+    taskInfos.forEach((t, i) => {
+      const krIdx = i % krNodes.length;
+      const kr = krNodes[krIdx];
+      const tasksOnThisKr = taskInfos.filter((_, j) => j % krNodes.length === krIdx).length;
+      const localIdx = Math.floor(i / krNodes.length);
+      const tAngle = kr.angle + ((localIdx + 1) * (Math.PI / 4) - Math.PI / 8);
+      taskNodes.push({
+        ...t,
+        parentX: kr.x,
+        parentY: kr.y,
+        x: kr.x + Math.cos(tAngle) * taskOrbit,
+        y: kr.y + Math.sin(tAngle) * taskOrbit,
+      });
+    });
+  }
+
+  // Progress arc around goal center
+  const arcRadius = goalRadius + 8;
+  const progressArc = renderProgressArc(cx, cy, arcRadius, progress.percent, goalColor);
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="system-ui, -apple-system, sans-serif">
+  <defs>
+    <radialGradient id="goalGlow" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="${goalColor}" stop-opacity="0.30"/>
+      <stop offset="100%" stop-color="${goalColor}" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="softGlow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="3" result="b"/>
+      <feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <rect width="${W}" height="${H}" fill="#0d1117"/>
+
+  <!-- background dot grid for constellation feel -->
+  ${renderDots(W, H)}
+
+  <!-- glow around goal center -->
+  <circle cx="${cx}" cy="${cy}" r="${goalRadius + 60}" fill="url(#goalGlow)"/>
+
+  <!-- connection lines: goal → KRs -->
+  ${krNodes.map((kr) => `<line x1="${cx}" y1="${cy}" x2="${kr.x}" y2="${kr.y}" stroke="${STATUS_COLOR[kr.status_canonical] || '#6b7280'}" stroke-opacity="0.4" stroke-width="1.5" stroke-dasharray="${kr.status_canonical === 'Done' ? '0' : '4 4'}"/>`).join('\n  ')}
+
+  <!-- connection lines: KR/goal → tasks -->
+  ${taskNodes.map((t) => `<line x1="${t.parentX}" y1="${t.parentY}" x2="${t.x}" y2="${t.y}" stroke="${STATUS_COLOR[t.status] || '#6b7280'}" stroke-opacity="0.25" stroke-width="1"/>`).join('\n  ')}
+
+  <!-- task leaf nodes -->
+  ${taskNodes.map((t) => renderTaskLeaf(t)).join('\n  ')}
+
+  <!-- KR satellite nodes -->
+  ${krNodes.map((kr) => renderKrSatellite(kr)).join('\n  ')}
+
+  <!-- goal center node -->
+  ${progressArc}
+  <circle cx="${cx}" cy="${cy}" r="${goalRadius}" fill="#161b22" stroke="${goalColor}" stroke-width="2.5" filter="url(#softGlow)"/>
+  <text x="${cx}" y="${cy - 8}" text-anchor="middle" font-size="36" dy="0.35em">${esc(icon)}</text>
+  <text x="${cx}" y="${cy + 22}" text-anchor="middle" font-size="11" font-weight="700" fill="#c9d1d9" font-family="ui-monospace, monospace">${esc(goalId)}</text>
+  <text x="${cx}" y="${cy + 38}" text-anchor="middle" font-size="9" fill="${goalColor}" font-weight="600" letter-spacing="0.5">${esc(goal.fm.status || 'Draft').toUpperCase()}</text>
+
+  <!-- title bar -->
+  <text x="32" y="36" font-size="18" font-weight="700" fill="#c9d1d9">${esc(icon)} ${esc(goalId)}</text>
+  <text x="32" y="58" font-size="12" fill="#8b949e">${esc(extractTitle(goal.content) || '')}</text>
+  ${goal.fm.cycle ? `<text x="32" y="76" font-size="10" fill="#58a6ff" letter-spacing="1">${esc(goal.fm.cycle).toUpperCase()}</text>` : ''}
+
+  <!-- stats bottom-right -->
+  <g transform="translate(${W - 32}, ${H - 60})">
+    <text text-anchor="end" font-size="11" fill="#8b949e">${krNodes.length} KR · ${taskNodes.length} tasks</text>
+    <text text-anchor="end" y="16" font-size="11" fill="#8b949e">${progress.percent}% (${progress.done}/${progress.total} subtasks)</text>
+    <text text-anchor="end" y="32" font-size="10" fill="#6b7280">v${goal.fm.goal_version || 1} · ${esc(goal.fm.target_date || 'TBD')}</text>
+  </g>
+
+  <!-- legend -->
+  <g transform="translate(32, ${H - 76})" font-size="9" fill="#8b949e">
+    ${renderLegendItem(0, 'Done', STATUS_COLOR.Done)}
+    ${renderLegendItem(58, 'In Progress', STATUS_COLOR['In Progress'])}
+    ${renderLegendItem(140, 'Blocked', STATUS_COLOR.Blocked)}
+    ${renderLegendItem(202, 'Pending', STATUS_COLOR.Pending)}
+  </g>
+</svg>`;
+}
+
+function renderDots(W, H) {
+  const dots = [];
+  for (let x = 20; x < W; x += 40) {
+    for (let y = 20; y < H; y += 40) {
+      dots.push(`<circle cx="${x}" cy="${y}" r="0.6" fill="#30363d" opacity="0.5"/>`);
+    }
+  }
+  return dots.join('');
+}
+
+function renderProgressArc(cx, cy, r, percent, color) {
+  if (percent <= 0) return `<circle cx="${cx}" cy="${cy}" r="${r}" fill="none" stroke="${color}" stroke-opacity="0.15" stroke-width="3"/>`;
+  if (percent >= 100) return `<circle cx="${cx}" cy="${cy}" r="${r}" fill="none" stroke="${color}" stroke-width="3"/>`;
+  const angle = (percent / 100) * Math.PI * 2;
+  const startX = cx;
+  const startY = cy - r;
+  const endX = cx + Math.sin(angle) * r;
+  const endY = cy - Math.cos(angle) * r;
+  const large = angle > Math.PI ? 1 : 0;
+  return `<circle cx="${cx}" cy="${cy}" r="${r}" fill="none" stroke="${color}" stroke-opacity="0.15" stroke-width="3"/>
+  <path d="M ${startX} ${startY} A ${r} ${r} 0 ${large} 1 ${endX} ${endY}" fill="none" stroke="${color}" stroke-width="3" stroke-linecap="round"/>`;
+}
+
+function renderKrSatellite(kr) {
+  const color = STATUS_COLOR[kr.status_canonical] || STATUS_COLOR.Pending;
+  return `<g>
+    <circle cx="${kr.x}" cy="${kr.y}" r="22" fill="#161b22" stroke="${color}" stroke-width="2"/>
+    <text x="${kr.x}" y="${kr.y}" text-anchor="middle" dy="0.35em" font-size="10" font-weight="700" font-family="ui-monospace, monospace" fill="${color}">${esc(kr.id)}</text>
+    <title>${esc(kr.id)}: ${esc(kr.description)} (target: ${esc(kr.target)}, current: ${esc(kr.current)})</title>
+  </g>`;
+}
+
+function renderTaskLeaf(t) {
+  const color = STATUS_COLOR[t.status] || STATUS_COLOR.Draft;
+  const r = 10;
+  // Show task name truncated below
+  return `<g>
+    <circle cx="${t.x}" cy="${t.y}" r="${r}" fill="${color}" fill-opacity="0.25" stroke="${color}" stroke-width="1.5"/>
+    <text x="${t.x}" y="${t.y}" text-anchor="middle" dy="0.35em" font-size="8" font-weight="700" fill="${color}">${t.doneCount}/${t.subtaskCount}</text>
+    <text x="${t.x}" y="${t.y + r + 12}" text-anchor="middle" font-size="9" fill="#8b949e">${esc(truncate(t.id, 18))}</text>
+    <title>${esc(t.id)} — ${esc(t.status)} (${t.doneCount}/${t.subtaskCount} subtasks done)</title>
+  </g>`;
+}
+
+function renderLegendItem(x, label, color) {
+  return `<g transform="translate(${x}, 0)"><circle cx="4" cy="4" r="4" fill="${color}"/><text x="12" y="7">${esc(label)}</text></g>`;
+}
+
+function truncate(s, n) {
+  if (!s) return '';
+  return s.length <= n ? s : s.slice(0, n - 1) + '…';
+}
+
+function extractTitle(content) {
+  const m = content.match(/^#\s+Goal:\s+(.+?)\s*$/m) || content.match(/^#\s+(.+?)\s*$/m);
+  return m ? m[1].trim() : null;
+}
+
+function errorSvg(msg) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 200" width="600" height="200">
+  <rect width="600" height="200" fill="#0d1117"/>
+  <text x="300" y="100" text-anchor="middle" dy="0.35em" font-size="14" fill="#ef4444" font-family="system-ui">${esc(msg)}</text>
+</svg>`;
+}

package/src/lib/goal-watch.mjs

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync, statSync, watch as fsWatch } from 'node:fs';
+import { eventsGlobalFile } from './goal-events.mjs';
+
+/**
+ * Subscribe to .dw/events-global.jsonl for goal events.
+ *
+ * Tier 1 vendor-neutral primitive per ADR-0010 W-6: this is the ONLY mechanism
+ * non-Claude agents (Codex, Gemini, CI jobs, cron) should use. Tier 2 SSE is
+ * browser-UI-only.
+ *
+ * Usage:
+ *   import { watchGoalEvents } from 'dw-kit/lib/goal-watch.mjs';
+ *
+ *   const unsubscribe = watchGoalEvents((event) => {
+ *     if (event.event === 'goal_status_changed' && event.goal_id === myGoal) {
+ *       // re-plan, re-read goal.md, etc.
+ *     }
+ *   }, { rootDir: process.cwd(), backfill: 0 });
+ *
+ *   // later: unsubscribe();
+ *
+ * @param {(event: object) => void} handler - called for each new event line
+ * @param {object} [opts]
+ * @param {string} [opts.rootDir=process.cwd()]
+ * @param {number} [opts.backfill=0] - number of past events to replay on subscribe
+ *                                      (0 = only new events from this moment forward)
+ * @param {(string) => boolean} [opts.filter] - optional event-type or goal-id filter
+ *                                              receives the parsed event; return true to deliver
+ * @returns {() => void} unsubscribe function
+ */
+export function watchGoalEvents(handler, opts = {}) {
+  const rootDir = opts.rootDir || process.cwd();
+  const backfill = opts.backfill || 0;
+  const filter = typeof opts.filter === 'function' ? opts.filter : null;
+  const file = eventsGlobalFile(rootDir);
+
+  let lastBytes = 0;
+  let watcher = null;
+  let closed = false;
+
+  function emit(event) {
+    if (closed) return;
+    if (filter && !filter(event)) return;
+    try { handler(event); } catch (e) { /* user handler error; don't break the loop */ }
+  }
+
+  function readNewLines() {
+    if (!existsSync(file)) return;
+    let content;
+    try { content = readFileSync(file, 'utf8'); } catch { return; }
+    if (content.length <= lastBytes) {
+      lastBytes = content.length;
+      return;
+    }
+    const newSegment = content.slice(lastBytes);
+    lastBytes = content.length;
+    const lines = newSegment.split('\n').filter(Boolean);
+    for (const line of lines) {
+      try { emit(JSON.parse(line)); } catch { /* malformed line; skip */ }
+    }
+  }
+
+  // Initial backfill
+  if (existsSync(file)) {
+    try {
+      const initial = readFileSync(file, 'utf8');
+      const allLines = initial.split('\n').filter(Boolean);
+      if (backfill > 0) {
+        const slice = allLines.slice(-backfill);
+        for (const line of slice) {
+          try { emit(JSON.parse(line)); } catch { /* skip */ }
+        }
+      }
+      lastBytes = initial.length;
+    } catch {
+      lastBytes = 0;
+    }
+  }
+
+  try {
+    watcher = fsWatch(file, { persistent: true }, () => readNewLines());
+  } catch {
+    // fs.watch unsupported on some platforms (rare); fall back to polling
+    const pollInterval = setInterval(readNewLines, 1000);
+    return () => { closed = true; clearInterval(pollInterval); };
+  }
+
+  return () => {
+    closed = true;
+    if (watcher) {
+      try { watcher.close(); } catch { /* ignore */ }
+      watcher = null;
+    }
+  };
+}
+
+/**
+ * Convenience: subscribe only to events for a specific goal_id.
+ */
+export function watchGoal(goalId, handler, opts = {}) {
+  return watchGoalEvents(handler, {
+    ...opts,
+    filter: (ev) => ev.goal_id === goalId && (!opts.filter || opts.filter(ev)),
+  });
+}
+
+/**
+ * Convenience: get an async iterator over goal events. Use with `for await`.
+ *
+ * Example:
+ *   for await (const event of iterateGoalEvents({ goalId: 'G-001' })) {
+ *     if (event.event === 'goal_status_changed') break;
+ *   }
+ */
+export async function* iterateGoalEvents(opts = {}) {
+  const queue = [];
+  let resolveNext = null;
+
+  const unsubscribe = watchGoalEvents((ev) => {
+    if (opts.goalId && ev.goal_id !== opts.goalId) return;
+    queue.push(ev);
+    if (resolveNext) { resolveNext(); resolveNext = null; }
+  }, opts);
+
+  try {
+    while (true) {
+      while (queue.length > 0) yield queue.shift();
+      await new Promise((r) => { resolveNext = r; });
+    }
+  } finally {
+    unsubscribe();
+  }
+}