@warnyin/sdlc 0.1.0

package/lib/delta.mjs

@@ -0,0 +1,160 @@
+// Delta-spec grammar (parser keys are frozen English regardless of any
+// UI language):
+//
+//   ## Delta: <capability>
+//   ### ADDED Requirement: <name>
+//   The system SHALL <behavior>.
+//   #### Scenario: <name>
+//   - WHEN <condition>
+//   - THEN <outcome>
+//   ### MODIFIED Requirement: <existing name>   ← full replacement body
+//   ### REMOVED Requirement: <existing name>
+//
+// Requirement heading text is the identity key (OpenSpec convention).
+// `mergeDelta` applies ops mechanically to a living spec; a missing key on
+// MODIFIED/REMOVED is a hard error — never merge silently.
+
+const DELTA_HEAD = /^## Delta:\s*(.+?)\s*$/;
+const OP_HEAD = /^### (ADDED|MODIFIED|REMOVED) Requirement:\s*(.+?)\s*$/;
+const BAD_OP_HEAD = /^### (\w+) Requirement:/;
+const SPEC_REQ_HEAD = /^### Requirement:\s*(.+?)\s*$/;
+
+export function parseDelta(changeText) {
+  const lines = (changeText ?? '').split(/\r?\n/);
+  const deltas = [];
+  const errors = [];
+  let current = null;   // { capability, ops }
+  let currentOp = null; // { op, name, bodyLines }
+
+  const closeOp = () => {
+    if (!currentOp) return;
+    const body = currentOp.bodyLines.join('\n').trim();
+    if (currentOp.op !== 'REMOVED' && body === '') {
+      errors.push(`${currentOp.op} Requirement "${currentOp.name}" has an empty body`);
+    }
+    current.ops.push({ op: currentOp.op, name: currentOp.name, body });
+    currentOp = null;
+  };
+
+  for (const line of lines) {
+    const deltaMatch = line.match(DELTA_HEAD);
+    if (deltaMatch) {
+      closeOp();
+      // Repeated `## Delta: <cap>` blocks merge into one entry — otherwise the
+      // last block would silently overwrite the first at ship time.
+      const existing = deltas.find((d) => d.capability.toLowerCase() === deltaMatch[1].toLowerCase());
+      current = existing ?? { capability: deltaMatch[1], ops: [] };
+      if (!existing) deltas.push(current);
+      continue;
+    }
+    if (/^## /.test(line) && !deltaMatch) {
+      closeOp();
+      current = null; // left the delta section
+      continue;
+    }
+    if (!current) continue;
+
+    const opMatch = line.match(OP_HEAD);
+    if (opMatch) {
+      closeOp();
+      currentOp = { op: opMatch[1], name: opMatch[2], bodyLines: [] };
+      continue;
+    }
+    const badOp = line.match(BAD_OP_HEAD);
+    if (badOp && !opMatch) {
+      errors.push(`Unknown delta operation "${badOp[1]}" (use ADDED, MODIFIED, or REMOVED)`);
+      continue;
+    }
+    if (currentOp) currentOp.bodyLines.push(line);
+  }
+  closeOp();
+
+  for (const d of deltas) {
+    const seen = new Set();
+    for (const op of d.ops) {
+      const key = op.name.toLowerCase();
+      if (seen.has(key)) errors.push(`Duplicate requirement "${op.name}" in Delta: ${d.capability}`);
+      seen.add(key);
+    }
+    if (d.ops.length === 0) errors.push(`Delta: ${d.capability} declares no requirement operations`);
+  }
+
+  return { deltas, errors };
+}
+
+export function parseSpec(specText) {
+  const lines = (specText ?? '').split(/\r?\n/);
+  const requirements = [];
+  const preamble = [];
+  let current = null;
+
+  for (const line of lines) {
+    const reqMatch = line.match(SPEC_REQ_HEAD);
+    if (reqMatch) {
+      current = { name: reqMatch[1], bodyLines: [] };
+      requirements.push(current);
+      continue;
+    }
+    if (current) current.bodyLines.push(line);
+    else preamble.push(line);
+  }
+
+  return {
+    preamble: preamble.join('\n').replace(/\n+$/, ''),
+    requirements: requirements.map((r) => ({
+      name: r.name,
+      body: r.bodyLines.join('\n').trim(),
+    })),
+  };
+}
+
+export function renderSpec({ preamble, requirements }) {
+  const parts = [preamble.replace(/\n+$/, '')];
+  for (const r of requirements) {
+    parts.push(`\n### Requirement: ${r.name}\n${r.body}`);
+  }
+  return parts.join('\n').replace(/\n+$/, '\n');
+}
+
+export function newSpecPreamble(capability) {
+  return [
+    `# Spec: ${capability}`,
+    '',
+    '## Purpose',
+    '<!-- one or two lines; commands grep this header first (progressive disclosure) -->',
+    '',
+    '## Requirements',
+  ].join('\n');
+}
+
+// Apply one capability's ops to a living spec (or null to create it).
+// Returns { ok, content, errors }.
+export function mergeDelta(specText, ops, capability) {
+  const errors = [];
+  const spec = specText == null
+    ? { preamble: newSpecPreamble(capability), requirements: [] }
+    : parseSpec(specText);
+
+  const byName = new Map(spec.requirements.map((r) => [r.name.toLowerCase(), r]));
+
+  for (const { op, name, body } of ops) {
+    const key = name.toLowerCase();
+    const existing = byName.get(key);
+    if (op === 'ADDED') {
+      if (existing) { errors.push(`ADDED Requirement "${name}" already exists in spec "${capability}"`); continue; }
+      const req = { name, body };
+      spec.requirements.push(req);
+      byName.set(key, req);
+    } else if (op === 'MODIFIED') {
+      if (!existing) { errors.push(`MODIFIED Requirement "${name}" not found in spec "${capability}"`); continue; }
+      existing.body = body;
+    } else if (op === 'REMOVED') {
+      if (!existing) { errors.push(`REMOVED Requirement "${name}" not found in spec "${capability}"`); continue; }
+      spec.requirements = spec.requirements.filter((r) => r.name.toLowerCase() !== key);
+      byName.delete(key);
+    }
+  }
+
+  if (errors.length) return { ok: false, content: null, errors };
+  return { ok: true, content: renderSpec(spec), errors: [] };
+}

package/lib/frontmatter.mjs

@@ -0,0 +1,59 @@
+// Minimal YAML-frontmatter reader (zero-dep). Supports the subset this
+// framework writes: strings, numbers, booleans, inline arrays, and
+// simple `- item` lists. Anything fancier is a validation error upstream.
+
+const FENCE = '---';
+
+export function parseFrontmatter(text) {
+  if (typeof text !== 'string') return { data: {}, body: '' };
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== FENCE) return { data: {}, body: text };
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === FENCE) { end = i; break; }
+  }
+  if (end === -1) return { data: {}, body: text };
+
+  const data = {};
+  let currentListKey = null;
+  for (let i = 1; i < end; i++) {
+    const raw = lines[i];
+    if (!raw.trim() || raw.trim().startsWith('#')) continue;
+
+    const listItem = raw.match(/^\s+-\s+(.*)$/);
+    if (listItem && currentListKey) {
+      data[currentListKey].push(coerce(listItem[1].trim()));
+      continue;
+    }
+
+    const kv = raw.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, rawValue] = kv;
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+    const value = rawValue.trim();
+    if (value === '') {
+      data[key] = [];
+      currentListKey = key;
+    } else {
+      data[key] = coerce(value);
+      currentListKey = null;
+    }
+  }
+
+  return { data, body: lines.slice(end + 1).join('\n') };
+}
+
+function coerce(value) {
+  if (value.startsWith('[') && value.endsWith(']')) {
+    const inner = value.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(',').map((v) => coerce(v.trim()));
+  }
+  const unquoted = value.replace(/^["']|["']$/g, '');
+  if (unquoted !== value) return unquoted;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  return value;
+}

package/lib/glob.mjs

@@ -0,0 +1,29 @@
+// Tiny glob matcher for steering pathMatch patterns. Supports the subset we
+// document: `**` (any depth), `*` (within a segment), literal text.
+// Paths are compared as POSIX, relative to the project root.
+
+export function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        // `**/` or trailing `**` — match any depth including nothing
+        if (glob[i + 2] === '/') { re += '(?:[^/]+/)*'; i += 2; }
+        else { re += '.*'; i += 1; }
+      } else {
+        re += '[^/]*';
+      }
+    } else if ('.+^$()[]{}|\\?'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+export function matchGlob(relPosixPath, patterns) {
+  const list = Array.isArray(patterns) ? patterns : [patterns];
+  return list.some((p) => globToRegExp(String(p)).test(relPosixPath));
+}

package/lib/manifest.mjs

@@ -0,0 +1,99 @@
+// Manifest + prune guards (ported from the battle-tested warnyin-agents
+// installer). The manifest records sha256 of every payload-owned file so
+// `update` can distinguish ours-unmodified (refresh), ours-modified-by-user
+// (keep + warn), and stale (prune with guards).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PRUNE_BLAST_CAP = 50;
+
+// Payload-owned roots — prune may only ever touch paths under these.
+const PRUNABLE_PREFIXES = [
+  'sdlc/.playbook/',
+  'sdlc/.hooks/',
+  '.claude/commands/sdlc/',
+];
+const AGENT_ALLOW_RE = /^\.claude\/agents\/sdlc-[^/]+\.md$/;
+const SKILL_ALLOW_RE = /^\.claude\/skills\/(delta-spec-format|contract-writing|sdlc-conventions)\/[^/]+$/;
+const ADAPTER_ALLOW = new Set([
+  '.cursor/rules/sdlc.mdc',
+  '.windsurf/rules/sdlc.md',
+]);
+
+export function parseManifest(text) {
+  const map = new Map();
+  for (const line of (text ?? '').split(/\r?\n/)) {
+    if (!line.trim() || line.startsWith('#')) continue;
+    const m = line.match(/^([a-f0-9]{64})\s{2}(.+)$/);
+    if (!m) continue;
+    map.set(m[2], m[1]);
+  }
+  return map;
+}
+
+export function renderManifest(map) {
+  const lines = ['# @warnyin/sdlc manifest — sha256  path (posix, relative to project root)'];
+  for (const [p, hash] of [...map.entries()].sort()) lines.push(`${hash}  ${p}`);
+  return lines.join('\n') + '\n';
+}
+
+// Guard 1: structural path safety (manifest is data — never trust it blindly).
+export function isSafeRelPath(relPosix) {
+  if (typeof relPosix !== 'string' || relPosix === '') return false;
+  if (relPosix.includes('\\') || relPosix.startsWith('/') || /^[A-Za-z]:/.test(relPosix)) return false;
+  if (/[\u0000-\u001f]/.test(relPosix)) return false;
+  const segments = relPosix.split('/');
+  return segments.every((s) => s !== '' && s !== '.' && s !== '..');
+}
+
+// Guard 2: scope — only payload-owned locations are ever prunable.
+export function isPrunablePath(relPosix) {
+  if (!isSafeRelPath(relPosix)) return false;
+  if (PRUNABLE_PREFIXES.some((p) => relPosix.startsWith(p))) return true;
+  if (AGENT_ALLOW_RE.test(relPosix)) return true;
+  if (SKILL_ALLOW_RE.test(relPosix)) return true;
+  if (ADAPTER_ALLOW.has(relPosix)) return true;
+  return false;
+}
+
+// Stale = in the old manifest but absent from the new payload set.
+// Every candidate must pass path + scope guards; the caller additionally
+// checks hash-match-on-disk and realpath containment before deleting.
+export function computeStale(oldManifest, newPaths) {
+  const stale = [];
+  const rejected = [];
+  for (const [relPath, hash] of oldManifest.entries()) {
+    if (newPaths.has(relPath)) continue;
+    if (!isPrunablePath(relPath)) {
+      rejected.push({ path: relPath, reason: 'outside prunable scope' });
+      continue;
+    }
+    stale.push({ path: relPath, hash });
+  }
+  return { stale, rejected, overCap: stale.length > PRUNE_BLAST_CAP };
+}
+
+export function containedIn(rootAbs, targetAbs) {
+  const rel = path.relative(rootAbs, targetAbs);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// Guard: no path segment between root and target may be a symlink. Without
+// this, a symlinked ancestor inside a prunable prefix redirects the delete to
+// whatever real file it points at (arbitrary-deletion class — the manifest is
+// untrusted, user-writable input).
+export function hasSymlinkSegment(rootAbs, targetAbs) {
+  const rel = path.relative(rootAbs, targetAbs);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return true; // suspicious → treat as unsafe
+  let cur = rootAbs;
+  for (const seg of rel.split(path.sep)) {
+    cur = path.join(cur, seg);
+    try {
+      if (fs.lstatSync(cur).isSymbolicLink()) return true;
+    } catch {
+      return false; // component missing — nothing to follow
+    }
+  }
+  return false;
+}

package/lib/observe.mjs

@@ -0,0 +1,174 @@
+// Observability aggregation — reads journals + context files, computes the
+// numbers /sdlc:observe reports. Pure given an sdlc root; no LLM involved.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+import { CAPS, countEffectiveLines } from './caps.mjs';
+
+function readJournal(dir) {
+  const p = path.join(dir, 'journal.ndjson');
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean);
+}
+
+function summarizeChange(dir, id, archived) {
+  const events = readJournal(dir);
+  const tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  let costUsd = 0;
+  let costKnown = false;
+  let sessions = 0;
+  const verify = { rounds: 0, firstPass: null };
+  let guards = 0;
+  let compacts = 0;
+
+  for (const e of events) {
+    if (e.event === 'session') {
+      sessions++;
+      for (const k of Object.keys(tokens)) tokens[k] += e.totals?.[k] ?? 0;
+      if (typeof e.costUsd === 'number') { costUsd += e.costUsd; costKnown = true; }
+    } else if (e.event === 'verify') {
+      verify.rounds++;
+      if (verify.firstPass === null) verify.firstPass = e.result === 'pass';
+    } else if (e.event === 'guard') guards++;
+    else if (e.event === 'compact') compacts++;
+  }
+
+  const first = events[0]?.ts ? Date.parse(events[0].ts) : null;
+  const shipEvent = events.find((e) => e.event === 'ship');
+  const shippedAt = shipEvent?.ts ? Date.parse(shipEvent.ts) : null;
+  const leadTimeMs = first != null && shippedAt != null ? shippedAt - first : null;
+
+  let tier = null;
+  let status = null;
+  const changePath = path.join(dir, 'change.md');
+  if (fs.existsSync(changePath)) {
+    const { data } = parseFrontmatter(fs.readFileSync(changePath, 'utf8'));
+    tier = data.tier ?? null;
+    status = data.status ?? null;
+  }
+
+  return {
+    id, archived, tier, status, sessions, tokens,
+    costUsd: costKnown ? Number(costUsd.toFixed(4)) : null,
+    verify, guards, compacts, leadTimeMs,
+    digest: archived ? fs.existsSync(path.join(dir, 'digest.md')) : null,
+  };
+}
+
+export function buildReport(sdlcRoot) {
+  const changes = [];
+
+  const changesDir = path.join(sdlcRoot, 'changes');
+  if (fs.existsSync(changesDir)) {
+    for (const d of fs.readdirSync(changesDir, { withFileTypes: true })) {
+      if (!d.isDirectory() || d.name === 'archive') continue;
+      changes.push(summarizeChange(path.join(changesDir, d.name), d.name, false));
+    }
+    const archiveDir = path.join(changesDir, 'archive');
+    if (fs.existsSync(archiveDir)) {
+      for (const d of fs.readdirSync(archiveDir, { withFileTypes: true })) {
+        if (!d.isDirectory()) continue;
+        changes.push(summarizeChange(path.join(archiveDir, d.name), d.name, true));
+      }
+    }
+  }
+
+  // Residency: constitution + always-steering effective lines vs budget.
+  let alwaysLines = 0;
+  const constitutionPath = path.join(sdlcRoot, 'context', 'constitution.md');
+  if (fs.existsSync(constitutionPath)) {
+    alwaysLines += countEffectiveLines(fs.readFileSync(constitutionPath, 'utf8'));
+  }
+  const steering = [];
+  const pointerHits = new Map();
+  for (const c of changes) {
+    const dir = c.archived
+      ? path.join(sdlcRoot, 'changes', 'archive', c.id)
+      : path.join(sdlcRoot, 'changes', c.id);
+    for (const e of readJournal(dir)) {
+      if (e.event === 'pointer' && e.steering) {
+        pointerHits.set(e.steering, (pointerHits.get(e.steering) ?? 0) + 1);
+      }
+    }
+  }
+  // Global journal (events with no active change) counts too.
+  for (const e of readJournal(path.join(sdlcRoot, '.state'))) {
+    if (e.event === 'pointer' && e.steering) {
+      pointerHits.set(e.steering, (pointerHits.get(e.steering) ?? 0) + 1);
+    }
+  }
+
+  const steeringDir = path.join(sdlcRoot, 'context', 'steering');
+  if (fs.existsSync(steeringDir)) {
+    for (const f of fs.readdirSync(steeringDir).filter((n) => n.endsWith('.md')).sort()) {
+      const raw = fs.readFileSync(path.join(steeringDir, f), 'utf8');
+      const { data } = parseFrontmatter(raw);
+      const inclusion = data.inclusion ?? 'manual';
+      if (inclusion === 'always') alwaysLines += countEffectiveLines(raw);
+      steering.push({ file: f, inclusion, pointerHits: pointerHits.get(f) ?? 0 });
+    }
+  }
+
+  // Flags — plain strings the playbook can surface with suggested fixes.
+  const flags = [];
+  if (alwaysLines > CAPS.alwaysBudget) {
+    flags.push(`residency: always-loaded is ${alwaysLines}/${CAPS.alwaysBudget} lines — distill via /sdlc:steer`);
+  }
+  const shipped = changes.filter((c) => c.archived);
+  for (const s of steering.filter((s) => s.inclusion === 'paths' && s.pointerHits === 0)) {
+    if (shipped.length >= 2) {
+      flags.push(`steering/${s.file}: zero pointer hits across ${shipped.length} shipped changes — demote or delete`);
+    }
+  }
+  for (const c of changes) {
+    if (c.compacts > 0) flags.push(`${c.id}: ${c.compacts} compact event(s) — context overflowed, find the resident artifact`);
+    if (c.verify.rounds > 3) flags.push(`${c.id}: ${c.verify.rounds} verify rounds — contract or routing needs attention`);
+  }
+  for (const c of shipped.filter((c) => c.digest === false)) {
+    flags.push(`${c.id}: archived without digest.md — ship playbook step 4 was skipped`);
+  }
+
+  const firstPassRuns = changes.filter((c) => c.verify.firstPass !== null);
+  const summary = {
+    active: changes.filter((c) => !c.archived).length,
+    shipped: shipped.length,
+    firstPassRate: firstPassRuns.length
+      ? Number((firstPassRuns.filter((c) => c.verify.firstPass).length / firstPassRuns.length).toFixed(2))
+      : null,
+  };
+
+  return {
+    summary,
+    changes,
+    residency: { alwaysLines, budget: CAPS.alwaysBudget },
+    steering,
+    flags,
+  };
+}
+
+const fmtK = (n) => (n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M`
+  : n >= 1_000 ? `${(n / 1_000).toFixed(1)}k` : String(n));
+
+export function renderReport(report) {
+  const lines = [];
+  const { summary, residency } = report;
+  lines.push(`changes: ${summary.active} active · ${summary.shipped} shipped`
+    + (summary.firstPassRate != null ? ` · first-pass ${(summary.firstPassRate * 100).toFixed(0)}%` : ''));
+  lines.push(`residency: ${residency.alwaysLines}/${residency.budget} always-loaded lines`);
+  for (const c of report.changes) {
+    const t = c.tokens;
+    const lead = c.leadTimeMs != null ? ` · lead ${(c.leadTimeMs / 3_600_000).toFixed(1)}h` : '';
+    lines.push(`  ${c.archived ? '✓' : '·'} ${c.id} [${c.tier ?? '?'}]`
+      + ` ${fmtK(t.input)}in/${fmtK(t.output)}out`
+      + (c.costUsd != null ? ` $${c.costUsd}` : '')
+      + ` · verify×${c.verify.rounds}${lead}`);
+  }
+  for (const s of report.steering) {
+    lines.push(`  steering/${s.file} [${s.inclusion}] hits:${s.pointerHits}`);
+  }
+  for (const f of report.flags) lines.push(`  ⚠ ${f}`);
+  return lines.join('\n');
+}

package/lib/settings-merge.mjs

@@ -0,0 +1,63 @@
+// Non-destructive management of our hook entries inside the project's
+// .claude/settings.json. Ownership marker: any hook command that references
+// `sdlc/.hooks/` is ours; everything else is the user's and is never touched.
+// Merge is idempotent: remove ours, re-add current set, preserve the rest.
+
+const OWNERSHIP_MARKER = 'sdlc/.hooks/';
+
+const hookCmd = (script, extraArgs = '') =>
+  `node "$CLAUDE_PROJECT_DIR/sdlc/.hooks/${script}"${extraArgs ? ' ' + extraArgs : ''}`;
+
+export function sdlcHookEntries() {
+  return {
+    SessionStart: [
+      { hooks: [{ type: 'command', command: hookCmd('inject-context.mjs') }] },
+    ],
+    PreToolUse: [
+      {
+        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+        hooks: [{ type: 'command', command: hookCmd('guard-writes.mjs') }],
+      },
+    ],
+    PostToolUse: [
+      {
+        matcher: 'Edit|Write|MultiEdit',
+        hooks: [{ type: 'command', command: hookCmd('validate-artifact.mjs') }],
+      },
+    ],
+    Stop: [
+      { hooks: [{ type: 'command', command: hookCmd('session-summary.mjs') }] },
+    ],
+    PreCompact: [
+      { hooks: [{ type: 'command', command: hookCmd('journal.mjs', 'note compact') }] },
+    ],
+  };
+}
+
+function isOurs(matcherEntry) {
+  return (matcherEntry?.hooks ?? []).some(
+    (h) => typeof h?.command === 'string' && h.command.includes(OWNERSHIP_MARKER),
+  );
+}
+
+// settingsJson: parsed object (or {}). Returns a NEW object (immutability).
+export function mergeHookSettings(settingsJson) {
+  const settings = structuredClone(settingsJson ?? {});
+  const hooks = { ...(settings.hooks ?? {}) };
+  for (const [event, entries] of Object.entries(sdlcHookEntries())) {
+    const existing = (hooks[event] ?? []).filter((e) => !isOurs(e));
+    hooks[event] = [...existing, ...entries];
+  }
+  return { ...settings, hooks };
+}
+
+export function removeHookSettings(settingsJson) {
+  const settings = structuredClone(settingsJson ?? {});
+  if (!settings.hooks) return settings;
+  const hooks = {};
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    const kept = entries.filter((e) => !isOurs(e));
+    if (kept.length) hooks[event] = kept;
+  }
+  return { ...settings, hooks };
+}

package/lib/usage.mjs

@@ -0,0 +1,46 @@
+// Transcript-usage parser: Claude Code transcripts are JSONL; assistant
+// entries carry `message.usage` and `message.model`. We sum per model and
+// price via the optional table in sdlc/config.yaml. Never guess: when a
+// price is unknown, cost stays null (reported as n/a).
+
+export function parseTranscriptUsage(jsonlText) {
+  const byModel = new Map();
+  for (const line of (jsonlText ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const msg = entry?.message;
+    const usage = msg?.usage;
+    if (!usage || typeof usage !== 'object') continue;
+    const model = msg.model ?? 'unknown';
+    const acc = byModel.get(model) ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    acc.input += usage.input_tokens ?? 0;
+    acc.output += usage.output_tokens ?? 0;
+    acc.cacheRead += usage.cache_read_input_tokens ?? 0;
+    acc.cacheWrite += usage.cache_creation_input_tokens ?? 0;
+    byModel.set(model, acc);
+  }
+  const models = Object.fromEntries(byModel);
+  const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  for (const m of byModel.values()) {
+    totals.input += m.input; totals.output += m.output;
+    totals.cacheRead += m.cacheRead; totals.cacheWrite += m.cacheWrite;
+  }
+  return { models, totals };
+}
+
+// prices: { "<model>": { input, output, cacheRead } } in USD per 1M tokens.
+export function costUsd(usage, prices) {
+  if (!prices) return null;
+  let usd = 0;
+  let priced = false;
+  for (const [model, u] of Object.entries(usage.models)) {
+    const p = prices[model];
+    if (!p) continue;
+    priced = true;
+    usd += (u.input * (p.input ?? 0)
+      + u.output * (p.output ?? 0)
+      + u.cacheRead * (p.cacheRead ?? 0)) / 1_000_000;
+  }
+  return priced ? Number(usd.toFixed(4)) : null;
+}