@warnyin/sdlc 0.1.0 → 0.2.0

package/lib/settings-merge.mjs

@@ -1,63 +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 };
-}
+// 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

@@ -1,46 +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;
-}
+// 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;
+}

package/lib/validate.mjs

@@ -1,186 +1,186 @@
-// Structural validator — the tool-agnostic enforcement floor.
-// Used by: CLI (`warnyin-sdlc validate`), CI, and the PostToolUse hook.
-// Exit codes: 0 = clean (warnings allowed), 1 = errors found, 2 = usage/setup error.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { parseFrontmatter } from './frontmatter.mjs';
-import { CAPS, TIERS, STATUSES, countEffectiveLines, capForChange } from './caps.mjs';
-import { parseDelta, parseSpec } from './delta.mjs';
-
-const CLARIFICATION_RE = /\[NEEDS CLARIFICATION/g;
-
-export function statusRank(status) {
-  const i = STATUSES.indexOf(status);
-  return i === -1 ? 0 : i;
-}
-
-function issue(level, where, msg) {
-  return { level, where, msg };
-}
-
-// ---------- change validation ----------
-
-export function validateChange(changeDir, { strict = false, specsDir = null } = {}) {
-  const issues = [];
-  const id = path.basename(changeDir);
-  const changePath = path.join(changeDir, 'change.md');
-  if (!fs.existsSync(changePath)) {
-    return [issue('error', id, 'change.md is missing')];
-  }
-  const text = fs.readFileSync(changePath, 'utf8');
-  const { data } = parseFrontmatter(text);
-
-  if (!data.id) issues.push(issue('error', id, 'frontmatter: missing id'));
-  else if (data.id !== id) issues.push(issue('error', id, `frontmatter id "${data.id}" != folder name "${id}"`));
-  if (!TIERS.includes(data.tier)) issues.push(issue('error', id, `frontmatter: tier must be one of ${TIERS.join('|')}`));
-  if (!STATUSES.includes(data.status)) issues.push(issue('error', id, `frontmatter: status must be one of ${STATUSES.join('|')}`));
-
-  const tier = TIERS.includes(data.tier) ? data.tier : 'standard';
-  const status = STATUSES.includes(data.status) ? data.status : 'new';
-
-  const lines = countEffectiveLines(text);
-  const cap = capForChange(tier);
-  if (lines > cap) issues.push(issue('error', id, `change.md is ${lines} effective lines (cap for ${tier}: ${cap})`));
-
-  const markers = (text.match(CLARIFICATION_RE) ?? []).length;
-  if (markers > 0) {
-    const level = strict || status !== 'new' ? 'error' : 'warn';
-    issues.push(issue(level, id, `${markers} unresolved [NEEDS CLARIFICATION] marker(s)`));
-  }
-
-  const { deltas, errors: deltaErrors } = parseDelta(text);
-  for (const e of deltaErrors) issues.push(issue('error', id, `delta: ${e}`));
-  if (tier !== 'vibe' && deltas.length === 0) {
-    issues.push(issue('warn', id, 'no ## Delta section — spec-driven changes should state their behavior delta'));
-  }
-
-  // MODIFIED/REMOVED must target requirements that exist in living specs.
-  if (specsDir) {
-    for (const d of deltas) {
-      const specPath = path.join(specsDir, d.capability, 'spec.md');
-      const spec = fs.existsSync(specPath) ? parseSpec(fs.readFileSync(specPath, 'utf8')) : null;
-      const names = new Set((spec?.requirements ?? []).map((r) => r.name.toLowerCase()));
-      for (const op of d.ops) {
-        if ((op.op === 'MODIFIED' || op.op === 'REMOVED') && !names.has(op.name.toLowerCase())) {
-          issues.push(issue(strict ? 'error' : 'warn', id,
-            `${op.op} Requirement "${op.name}" not found in specs/${d.capability}/spec.md`));
-        }
-      }
-    }
-  }
-
-  // Contract requirements by status/tier.
-  const testsPath = path.join(changeDir, 'contract', 'tests.md');
-  const evalsPath = path.join(changeDir, 'contract', 'evals.md');
-  if (tier !== 'vibe' && statusRank(status) >= statusRank('contracted') && !fs.existsSync(testsPath)) {
-    issues.push(issue('error', id, `status "${status}" requires contract/tests.md`));
-  }
-  if (tier === 'deep' && statusRank(status) >= statusRank('contracted') && !fs.existsSync(evalsPath)) {
-    issues.push(issue('error', id, 'deep tier requires contract/evals.md'));
-  }
-  if (fs.existsSync(testsPath)) {
-    const n = countEffectiveLines(fs.readFileSync(testsPath, 'utf8'));
-    if (n > CAPS.contractTests) issues.push(issue('error', id, `contract/tests.md is ${n} lines (cap ${CAPS.contractTests})`));
-  }
-  if (fs.existsSync(evalsPath)) {
-    const n = countEffectiveLines(fs.readFileSync(evalsPath, 'utf8'));
-    if (n > CAPS.contractEvals) issues.push(issue('error', id, `contract/evals.md is ${n} lines (cap ${CAPS.contractEvals})`));
-  }
-
-  return issues;
-}
-
-// ---------- context / harness validation ----------
-
-export function validateContext(sdlcRoot) {
-  const issues = [];
-  const constitutionPath = path.join(sdlcRoot, 'context', 'constitution.md');
-  let alwaysLines = 0;
-
-  if (fs.existsSync(constitutionPath)) {
-    const n = countEffectiveLines(fs.readFileSync(constitutionPath, 'utf8'));
-    alwaysLines += n;
-    if (n > CAPS.constitution) {
-      issues.push(issue('error', 'context', `constitution.md is ${n} lines (cap ${CAPS.constitution})`));
-    }
-  } else {
-    issues.push(issue('warn', 'context', 'constitution.md is missing (run /sdlc:init)'));
-  }
-
-  const steeringDir = path.join(sdlcRoot, 'context', 'steering');
-  if (fs.existsSync(steeringDir)) {
-    for (const f of fs.readdirSync(steeringDir).filter((f) => f.endsWith('.md')).sort()) {
-      const raw = fs.readFileSync(path.join(steeringDir, f), 'utf8');
-      const { data } = parseFrontmatter(raw);
-      const n = countEffectiveLines(raw);
-      if (n > CAPS.steeringFile) {
-        issues.push(issue('error', `steering/${f}`, `${n} lines (cap ${CAPS.steeringFile})`));
-      }
-      const mode = data.inclusion ?? 'manual';
-      if (!['always', 'paths', 'manual', 'agent'].includes(mode)) {
-        issues.push(issue('error', `steering/${f}`, `inclusion "${mode}" must be always|paths|manual|agent`));
-      }
-      if (mode === 'paths' && !Array.isArray(data.pathMatch)) {
-        issues.push(issue('error', `steering/${f}`, 'inclusion: paths requires pathMatch: ["glob", ...]'));
-      }
-      if (mode === 'always') alwaysLines += n;
-    }
-  }
-
-  if (alwaysLines > CAPS.alwaysBudget) {
-    issues.push(issue('error', 'context',
-      `always-loaded budget is ${alwaysLines} lines (cap ${CAPS.alwaysBudget}) — demote steering or distill the constitution`));
-  }
-
-  const harnessPath = path.join(sdlcRoot, 'harness.md');
-  if (fs.existsSync(harnessPath)) {
-    const n = countEffectiveLines(fs.readFileSync(harnessPath, 'utf8'));
-    if (n > CAPS.harness) issues.push(issue('error', 'harness', `harness.md is ${n} lines (cap ${CAPS.harness})`));
-  }
-
-  const specsDir = path.join(sdlcRoot, 'specs');
-  if (fs.existsSync(specsDir)) {
-    for (const cap of fs.readdirSync(specsDir, { withFileTypes: true }).filter((d) => d.isDirectory())) {
-      const specPath = path.join(specsDir, cap.name, 'spec.md');
-      if (!fs.existsSync(specPath)) continue;
-      const n = countEffectiveLines(fs.readFileSync(specPath, 'utf8'));
-      if (n > CAPS.spec) {
-        issues.push(issue('warn', `specs/${cap.name}`, `spec.md is ${n} lines (soft cap ${CAPS.spec}) — consider splitting the capability`));
-      }
-    }
-  }
-
-  return issues;
-}
-
-export function listChangeDirs(sdlcRoot) {
-  const changesDir = path.join(sdlcRoot, 'changes');
-  if (!fs.existsSync(changesDir)) return [];
-  return fs.readdirSync(changesDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && d.name !== 'archive')
-    .map((d) => path.join(changesDir, d.name))
-    .sort();
-}
-
-export function validateAll(sdlcRoot, { strict = false, changeId = null } = {}) {
-  const specsDir = path.join(sdlcRoot, 'specs');
-  const issues = [...validateContext(sdlcRoot)];
-  const dirs = changeId
-    ? [path.join(sdlcRoot, 'changes', changeId)]
-    : listChangeDirs(sdlcRoot);
-  for (const dir of dirs) {
-    if (!fs.existsSync(dir)) {
-      issues.push(issue('error', path.basename(dir), 'change folder not found'));
-      continue;
-    }
-    issues.push(...validateChange(dir, { strict, specsDir }));
-  }
-  return issues;
-}
-
-export function formatIssues(issues) {
-  return issues
-    .map((i) => `${i.level === 'error' ? '✖' : '⚠'} [${i.where}] ${i.msg}`)
-    .join('\n');
-}
+// Structural validator — the tool-agnostic enforcement floor.
+// Used by: CLI (`warnyin-sdlc validate`), CI, and the PostToolUse hook.
+// Exit codes: 0 = clean (warnings allowed), 1 = errors found, 2 = usage/setup error.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+import { CAPS, TIERS, STATUSES, countEffectiveLines, capForChange } from './caps.mjs';
+import { parseDelta, parseSpec } from './delta.mjs';
+
+const CLARIFICATION_RE = /\[NEEDS CLARIFICATION/g;
+
+export function statusRank(status) {
+  const i = STATUSES.indexOf(status);
+  return i === -1 ? 0 : i;
+}
+
+function issue(level, where, msg) {
+  return { level, where, msg };
+}
+
+// ---------- change validation ----------
+
+export function validateChange(changeDir, { strict = false, specsDir = null } = {}) {
+  const issues = [];
+  const id = path.basename(changeDir);
+  const changePath = path.join(changeDir, 'change.md');
+  if (!fs.existsSync(changePath)) {
+    return [issue('error', id, 'change.md is missing')];
+  }
+  const text = fs.readFileSync(changePath, 'utf8');
+  const { data } = parseFrontmatter(text);
+
+  if (!data.id) issues.push(issue('error', id, 'frontmatter: missing id'));
+  else if (data.id !== id) issues.push(issue('error', id, `frontmatter id "${data.id}" != folder name "${id}"`));
+  if (!TIERS.includes(data.tier)) issues.push(issue('error', id, `frontmatter: tier must be one of ${TIERS.join('|')}`));
+  if (!STATUSES.includes(data.status)) issues.push(issue('error', id, `frontmatter: status must be one of ${STATUSES.join('|')}`));
+
+  const tier = TIERS.includes(data.tier) ? data.tier : 'standard';
+  const status = STATUSES.includes(data.status) ? data.status : 'new';
+
+  const lines = countEffectiveLines(text);
+  const cap = capForChange(tier);
+  if (lines > cap) issues.push(issue('error', id, `change.md is ${lines} effective lines (cap for ${tier}: ${cap})`));
+
+  const markers = (text.match(CLARIFICATION_RE) ?? []).length;
+  if (markers > 0) {
+    const level = strict || status !== 'new' ? 'error' : 'warn';
+    issues.push(issue(level, id, `${markers} unresolved [NEEDS CLARIFICATION] marker(s)`));
+  }
+
+  const { deltas, errors: deltaErrors } = parseDelta(text);
+  for (const e of deltaErrors) issues.push(issue('error', id, `delta: ${e}`));
+  if (tier !== 'vibe' && deltas.length === 0) {
+    issues.push(issue('warn', id, 'no ## Delta section — spec-driven changes should state their behavior delta'));
+  }
+
+  // MODIFIED/REMOVED must target requirements that exist in living specs.
+  if (specsDir) {
+    for (const d of deltas) {
+      const specPath = path.join(specsDir, d.capability, 'spec.md');
+      const spec = fs.existsSync(specPath) ? parseSpec(fs.readFileSync(specPath, 'utf8')) : null;
+      const names = new Set((spec?.requirements ?? []).map((r) => r.name.toLowerCase()));
+      for (const op of d.ops) {
+        if ((op.op === 'MODIFIED' || op.op === 'REMOVED') && !names.has(op.name.toLowerCase())) {
+          issues.push(issue(strict ? 'error' : 'warn', id,
+            `${op.op} Requirement "${op.name}" not found in specs/${d.capability}/spec.md`));
+        }
+      }
+    }
+  }
+
+  // Contract requirements by status/tier.
+  const testsPath = path.join(changeDir, 'contract', 'tests.md');
+  const evalsPath = path.join(changeDir, 'contract', 'evals.md');
+  if (tier !== 'vibe' && statusRank(status) >= statusRank('contracted') && !fs.existsSync(testsPath)) {
+    issues.push(issue('error', id, `status "${status}" requires contract/tests.md`));
+  }
+  if (tier === 'deep' && statusRank(status) >= statusRank('contracted') && !fs.existsSync(evalsPath)) {
+    issues.push(issue('error', id, 'deep tier requires contract/evals.md'));
+  }
+  if (fs.existsSync(testsPath)) {
+    const n = countEffectiveLines(fs.readFileSync(testsPath, 'utf8'));
+    if (n > CAPS.contractTests) issues.push(issue('error', id, `contract/tests.md is ${n} lines (cap ${CAPS.contractTests})`));
+  }
+  if (fs.existsSync(evalsPath)) {
+    const n = countEffectiveLines(fs.readFileSync(evalsPath, 'utf8'));
+    if (n > CAPS.contractEvals) issues.push(issue('error', id, `contract/evals.md is ${n} lines (cap ${CAPS.contractEvals})`));
+  }
+
+  return issues;
+}
+
+// ---------- context / harness validation ----------
+
+export function validateContext(sdlcRoot) {
+  const issues = [];
+  const constitutionPath = path.join(sdlcRoot, 'context', 'constitution.md');
+  let alwaysLines = 0;
+
+  if (fs.existsSync(constitutionPath)) {
+    const n = countEffectiveLines(fs.readFileSync(constitutionPath, 'utf8'));
+    alwaysLines += n;
+    if (n > CAPS.constitution) {
+      issues.push(issue('error', 'context', `constitution.md is ${n} lines (cap ${CAPS.constitution})`));
+    }
+  } else {
+    issues.push(issue('warn', 'context', 'constitution.md is missing (run /sdlc:init)'));
+  }
+
+  const steeringDir = path.join(sdlcRoot, 'context', 'steering');
+  if (fs.existsSync(steeringDir)) {
+    for (const f of fs.readdirSync(steeringDir).filter((f) => f.endsWith('.md')).sort()) {
+      const raw = fs.readFileSync(path.join(steeringDir, f), 'utf8');
+      const { data } = parseFrontmatter(raw);
+      const n = countEffectiveLines(raw);
+      if (n > CAPS.steeringFile) {
+        issues.push(issue('error', `steering/${f}`, `${n} lines (cap ${CAPS.steeringFile})`));
+      }
+      const mode = data.inclusion ?? 'manual';
+      if (!['always', 'paths', 'manual', 'agent'].includes(mode)) {
+        issues.push(issue('error', `steering/${f}`, `inclusion "${mode}" must be always|paths|manual|agent`));
+      }
+      if (mode === 'paths' && !Array.isArray(data.pathMatch)) {
+        issues.push(issue('error', `steering/${f}`, 'inclusion: paths requires pathMatch: ["glob", ...]'));
+      }
+      if (mode === 'always') alwaysLines += n;
+    }
+  }
+
+  if (alwaysLines > CAPS.alwaysBudget) {
+    issues.push(issue('error', 'context',
+      `always-loaded budget is ${alwaysLines} lines (cap ${CAPS.alwaysBudget}) — demote steering or distill the constitution`));
+  }
+
+  const harnessPath = path.join(sdlcRoot, 'harness.md');
+  if (fs.existsSync(harnessPath)) {
+    const n = countEffectiveLines(fs.readFileSync(harnessPath, 'utf8'));
+    if (n > CAPS.harness) issues.push(issue('error', 'harness', `harness.md is ${n} lines (cap ${CAPS.harness})`));
+  }
+
+  const specsDir = path.join(sdlcRoot, 'specs');
+  if (fs.existsSync(specsDir)) {
+    for (const cap of fs.readdirSync(specsDir, { withFileTypes: true }).filter((d) => d.isDirectory())) {
+      const specPath = path.join(specsDir, cap.name, 'spec.md');
+      if (!fs.existsSync(specPath)) continue;
+      const n = countEffectiveLines(fs.readFileSync(specPath, 'utf8'));
+      if (n > CAPS.spec) {
+        issues.push(issue('warn', `specs/${cap.name}`, `spec.md is ${n} lines (soft cap ${CAPS.spec}) — consider splitting the capability`));
+      }
+    }
+  }
+
+  return issues;
+}
+
+export function listChangeDirs(sdlcRoot) {
+  const changesDir = path.join(sdlcRoot, 'changes');
+  if (!fs.existsSync(changesDir)) return [];
+  return fs.readdirSync(changesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && d.name !== 'archive')
+    .map((d) => path.join(changesDir, d.name))
+    .sort();
+}
+
+export function validateAll(sdlcRoot, { strict = false, changeId = null } = {}) {
+  const specsDir = path.join(sdlcRoot, 'specs');
+  const issues = [...validateContext(sdlcRoot)];
+  const dirs = changeId
+    ? [path.join(sdlcRoot, 'changes', changeId)]
+    : listChangeDirs(sdlcRoot);
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) {
+      issues.push(issue('error', path.basename(dir), 'change folder not found'));
+      continue;
+    }
+    issues.push(...validateChange(dir, { strict, specsDir }));
+  }
+  return issues;
+}
+
+export function formatIssues(issues) {
+  return issues
+    .map((i) => `${i.level === 'error' ? '✖' : '⚠'} [${i.where}] ${i.msg}`)
+    .join('\n');
+}