yadflow 1.0.1

package/cli/gate.mjs

@@ -0,0 +1,456 @@
+// `sdlc gate open|sync|comments|status` — the PR/MR-driven front-half review gate.
+// The platform PR/MR is the review UI; this command syncs its state into the file ledger and, when
+// the gate passes (approvals satisfied + all comment threads resolved + PR merged), auto-advances the
+// step. The merge click is the human approval act, so front steps still never machine_advance.
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  c, log, ok, info, warn, hand, fail, readJSONStrict, writeJSON, run,
+} from './lib.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
+import {
+  epicRoot, loadLedger, findReviewStep, artifactBase, artifactHash, gatePredicate,
+  advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
+  artifactPaths, upsertHubPr,
+} from './epic-state.mjs';
+import { readPr, mapApprovers, createPr } from './platform.mjs';
+
+// ---- tiny frontmatter reader (key: value, and `repos: [a, b]`) ----------------------------------
+function frontmatter(file) {
+  if (!fs.existsSync(file)) return {};
+  const m = fs.readFileSync(file, 'utf8').match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (!kv) continue;
+    const [, k, v] = kv;
+    out[k] = /^\[.*\]$/.test(v) ? v.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean) : v.trim();
+  }
+  return out;
+}
+
+// Touched domains, resolved from files (gating.md): architecture => epic.repos; stories => union of
+// every story's repos; otherwise none.
+export function touchedDomains(epicDir, step) {
+  if (!isEscalated(step)) return [];
+  if (step.id === 'stories-review') {
+    const dir = path.join(epicDir, 'stories');
+    if (!fs.existsSync(dir)) return [];
+    const set = new Set();
+    for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+      for (const r of (frontmatter(path.join(dir, f)).repos || [])) set.add(r);
+    }
+    return [...set];
+  }
+  return frontmatter(path.join(epicDir, 'epic.md')).repos || [];
+}
+
+const ownerOf = (epicDir) => frontmatter(path.join(epicDir, 'epic.md')).owner || '<owner>';
+
+// A null architecture hash with a BEGIN marker present means the surface block is malformed
+// (no END, or empty) — approvals would not be hash-bound, so make that visible.
+function warnUnlockedContract(epicDir, artifact) {
+  if (artifactBase(artifact) !== 'architecture') return;
+  if (artifactHash(epicDir, artifact) !== null) return;
+  const f = path.join(epicDir, 'contract.md');
+  if (fs.existsSync(f) && /CONTRACT-SURFACE:BEGIN/.test(fs.readFileSync(f, 'utf8'))) {
+    warn('contract.md has CONTRACT-SURFACE:BEGIN without a matching END (or an empty block) — surface not locked, approvals will not be hash-bound');
+  }
+}
+
+// Fail fast on a corrupt or wrong-shape hub config: a silently-defaulted hub.json would degrade
+// every gate to file-only without anyone noticing, and a typo'd platform would read as "no bridge".
+function loadHub(root) {
+  const hubFile = path.join(root, PROJECT_FILES.hubConfig);
+  const regFile = path.join(root, PROJECT_FILES.reposRegistry);
+  const hub = readJSONStrict(hubFile, null);
+  if (hub !== null) {
+    if (typeof hub !== 'object' || Array.isArray(hub)) throw new Error(`${hubFile}: expected a JSON object`);
+    if (![null, undefined, 'github', 'gitlab'].includes(hub.platform)) {
+      throw new Error(`${hubFile}: unknown platform '${hub.platform}' — expected github, gitlab, or null`);
+    }
+    if (hub.roster !== undefined && !Array.isArray(hub.roster)) {
+      throw new Error(`${hubFile}: expected \`roster\` to be an array`);
+    }
+  }
+  const registry = readJSONStrict(regFile, { repos: [] });
+  if (!Array.isArray(registry?.repos)) throw new Error(`${regFile}: expected a \`repos\` array`);
+  return { hub, repos: registry.repos };
+}
+
+// Re-add this step's bridge approvals from the current platform state (drop+re-add => dismissals and
+// revocations vanish idempotently; manual approvals are never touched). Preserve the artifactHash a
+// reviewer first approved against unless their review is newer (a genuine re-approval) — that is what
+// makes "revoke only when the artifact changed" work.
+function upsertBridge(approvals, recs, { stepId, artifact, curHash, today }) {
+  const keyOf = (name, role, domain) => `${stepId}|${name}|${role}|${domain || ''}`;
+  const prior = new Map(
+    approvals.filter((a) => a.step === stepId && a.source === 'bridge')
+      .map((a) => [keyOf(a.approver, a.role, a.domain), a]),
+  );
+  const kept = approvals.filter((a) => !(a.step === stepId && a.source === 'bridge'));
+  for (const r of recs) {
+    const was = prior.get(keyOf(r.name, r.role, r.domain));
+    let artHash = curHash;            // first time we see this approval => bind to current content
+    let approvedAt = r.submittedAt || today;
+    if (was) {
+      // We only adopt the new hash when the platform PROVES a genuinely newer review (a later
+      // submittedAt). Otherwise — same review, or a platform that gives no timestamp (GitLab) — we
+      // KEEP the hash they originally approved, so a later artifact change still revokes the approval.
+      const genuinelyNewer = r.submittedAt && was.approvedAt && r.submittedAt > was.approvedAt;
+      if (!genuinelyNewer) {
+        artHash = was.artifactHash ?? curHash;
+        approvedAt = was.approvedAt ?? approvedAt;
+      }
+    }
+    kept.push({
+      artifact, step: stepId, approver: r.name, role: r.role,
+      ...(r.domain ? { domain: r.domain } : {}),
+      status: 'approved', date: today, source: 'bridge',
+      artifactHash: artHash, approvedAt,
+      ...(r.unverified ? { unverified: true } : {}),
+    });
+  }
+  return kept;
+}
+
+function writeComments(epicDir, base, today, blocking) {
+  if (!blocking.length) return;
+  const file = path.join(epicDir, 'reviews', `${base}--${today}--comments.md`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const lines = [`# Review comments — ${base} — ${today}`, ''];
+  for (const t of blocking) {
+    lines.push(`## ${t.login || 'reviewer'} ${t.changesRequested ? '(changes requested — **blocking**)' : '(unresolved)'}`);
+    lines.push(`- ${(t.body || '').split('\n')[0] || '(no text)'}`);
+    lines.push('');
+  }
+  fs.writeFileSync(file, lines.join('\n') + '\n');
+}
+
+// Upsert machine-readable participation records into the comments ledger (the counterpart to the
+// markdown side file) so the ledger — not just reviews/*.md — reflects platform thread state. One
+// record per (step, commenter, round); `round` is the count of prior synced rounds for the step.
+function recordComments(comments, { artifact, stepId, today, roster, repos, blocking }) {
+  if (!blocking.length) return comments;
+  const byName = (login) => (roster.find((r) => r.login === login)?.name) || login || 'reviewer';
+  const roleOf = (login) => (roster.find((r) => r.login === login)?.role) || 'reviewer';
+  const round = (comments.filter((cm) => cm.step === stepId).reduce((m, cm) => Math.max(m, cm.round || 0), 0)) + 1;
+  const counts = new Map();
+  for (const t of blocking) counts.set(t.login, (counts.get(t.login) || 0) + 1);
+  const kept = comments.filter((cm) => !(cm.step === stepId && cm.round === round));
+  for (const [login, count] of counts) {
+    kept.push({ artifact, step: stepId, commenter: byName(login), role: roleOf(login), round, count, date: today });
+  }
+  return kept;
+}
+
+// ---- actions ------------------------------------------------------------------------------------
+
+export async function gateSync(root, { epic, artifact, today, reader = readPr } = {}) {
+  const { hub, repos } = loadHub(root);
+  if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — file-only gate, nothing to sync'); return { synced: 0 }; }
+  const platform = hub.platform;
+  const roster = hub.roster || [];
+  const defaultReviewers = 1;
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  if (!ledger.state) { fail(`no epic state at ${epicDir}/.sdlc/state.json`); process.exitCode = 1; return { synced: 0 }; }
+
+  let { approvals, comments, hubPrs, state } = ledger;
+  const targets = hubPrs.filter((p) => !artifact || p.artifact === artifact);
+  if (!targets.length) { warn(`no open review PR recorded for ${epic}${artifact ? ` / ${artifact}` : ''} (run \`sdlc gate open\` first)`); return { synced: 0 }; }
+
+  let synced = 0;
+  for (const pr of targets) {
+    const step = findReviewStep(state, pr.artifact);
+    if (!step) { warn(`no review step for ${pr.artifact}`); continue; }
+    // Already advanced: a re-sync must not re-run advance (it would reset the next step's status /
+    // currentStep backward). The gate is one-way per step.
+    if (step.status === 'done') { info(`${pr.artifact}: ${step.id} already done — skipping`); continue; }
+    const domains = touchedDomains(epicDir, step);
+    const pull = reader(platform, pr.number, { cwd: root });
+    if (!pull.ok) { warn(`${pr.artifact}: ${pull.reason} — skipping (file-only)`); continue; }
+
+    const curHash = artifactHash(epicDir, pr.artifact);
+    warnUnlockedContract(epicDir, pr.artifact);
+    const recs = mapApprovers(pull.reviews, { roster, repos, touchedDomains: domains });
+    approvals = upsertBridge(approvals, recs, { stepId: step.id, artifact: pr.artifact, curHash, today });
+
+    const changeRequested = pull.reviews.filter((r) => r.state === 'CHANGES_REQUESTED');
+    const unresolved = (pull.threads || []).filter((t) => !t.resolved);
+    const threadsResolved = unresolved.length === 0 && changeRequested.length === 0;
+    const blocking = [
+      ...changeRequested.map((r) => ({ login: r.login, changesRequested: true })),
+      ...unresolved,
+    ];
+    writeComments(epicDir, base(pr.artifact), today, blocking);
+    comments = recordComments(comments, { artifact: pr.artifact, stepId: step.id, today, roster, repos, blocking });
+
+    const pred = gatePredicate({
+      step, approvals, currentHash: curHash, touchedDomains: domains,
+      defaultReviewers, threadsResolved, merged: pull.merged,
+    });
+
+    log(`  ${c.bold(pr.artifact)} ${c.dim(`(PR #${pr.number}, rule: ${pred.rule})`)}`);
+    if (pred.passed) {
+      state = advanceState(state, step);
+      ok(`gate PASSED — ${step.id} → done; next: ${state.currentStep}`);
+    } else {
+      state = markInReview(state, step);
+      for (const m of pred.missing) hand(`still needed: ${m}`);
+    }
+    pr.lastSyncedAt = today;
+    synced++;
+  }
+
+  writeJSON(ledger.files.approvals, approvals);
+  writeJSON(ledger.files.comments, comments);
+  writeJSON(ledger.files.hubPrs, hubPrs);
+  writeJSON(ledger.files.state, state);
+  refreshRoster(epicDir, targets, approvals, today);
+  return { synced };
+}
+
+// `sdlc gate ci` — the self-sufficient entry point hub CI calls on platform events (review
+// submitted/dismissed, PR synchronize, PR merged) and on the GitLab schedule. Event mode derives
+// epic/artifact from the `review/EP-<slug>/<base>` head branch (so it works even when the author
+// never committed hub-prs.json); sweep mode (no --branch) re-syncs every open review PR. Either way
+// it runs the unchanged gateSync, then commits ONLY the ledger files to the hub default branch —
+// the artifact itself lands on main via the human merge, never via CI.
+export async function gateCi(root, { branch, pr, today, push = true, reader = readPr } = {}) {
+  const { hub } = loadHub(root);
+  if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — nothing to sync'); return { synced: 0 }; }
+  const git = (...args) => run('git', args, { cwd: root });
+  // Push target: an explicit hub.default_branch wins; else the branch CI actually checked out (the
+  // workflow checks out the PR base / $CI_DEFAULT_BRANCH — hub.json from `sdlc setup` has no
+  // default_branch field, so the checkout is the truth); 'main' only as the last resort.
+  const head = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
+  const target = hub.default_branch || (head && head !== 'HEAD' ? head : 'main');
+
+  // Build the work list: one job per (epic, artifact) — from the event branch, or a full sweep.
+  const jobs = [];
+  if (branch) {
+    const parsed = parseReviewBranch(branch);
+    if (!parsed) { warn(`${branch} is not a review/EP-*/<artifact> branch — nothing to sync`); return { synced: 0 }; }
+    jobs.push({ epic: parsed.epic, base: parsed.base, artifact: artifactFromBase(parsed.base), branch, pr });
+  } else {
+    const epicsDir = path.join(root, 'epics');
+    for (const e of fs.existsSync(epicsDir) ? fs.readdirSync(epicsDir).sort() : []) {
+      // Sweep mode isolates per-epic failures: one corrupt ledger must not block the other epics'
+      // syncs in an unattended CI run. The run still exits non-zero so the bad file gets fixed.
+      let ledger;
+      try {
+        ledger = loadLedger(epicRoot(root, e));
+      } catch (err) {
+        warn(`${e}: ${err.message} — skipping this epic`);
+        process.exitCode = 1;
+        continue;
+      }
+      if (!ledger.state) continue;
+      for (const p of ledger.hubPrs || []) {
+        const step = findReviewStep(ledger.state, p.artifact);
+        if (!step || step.status === 'done') continue;
+        jobs.push({ epic: e, base: base(p.artifact), artifact: p.artifact, branch: p.branch, pr: p.number });
+      }
+    }
+    if (!jobs.length) { info('no open review PRs to sync'); return { synced: 0 }; }
+  }
+
+  let synced = 0;
+  const touched = new Set();
+  for (const job of jobs) {
+    const epicDir = epicRoot(root, job.epic);
+    // Event mode (--branch) targets a single epic: fail loudly. Sweep mode skips the bad epic.
+    let ledger;
+    try {
+      ledger = loadLedger(epicDir);
+    } catch (err) {
+      if (branch) throw err;
+      warn(`${job.epic}: ${err.message} — skipping this epic`);
+      process.exitCode = 1;
+      continue;
+    }
+    if (!ledger.state) {
+      warn(`${job.epic}: no epic state on ${target} — commit epics/${job.epic}/.sdlc to ${target} first`);
+      continue;
+    }
+    const step = findReviewStep(ledger.state, job.artifact);
+    if (!step) { warn(`${job.epic}: no review step for ${job.artifact} — skipping`); continue; }
+
+    // The event may fire before the author ever committed hub-prs.json — build the entry from the
+    // event itself, so the first CI commit lands it on the default branch and the views converge.
+    const existing = (ledger.hubPrs || []).find((x) => x.artifact === job.artifact);
+    const number = Number(job.pr) || existing?.number || null;
+    if (!existing || existing.number !== number || existing.branch !== job.branch) {
+      ledger.hubPrs = upsertHubPr(ledger.hubPrs, {
+        step: step.id, artifact: job.artifact, platform: hub.platform, number,
+        url: existing?.url ?? null, branch: job.branch, lastSyncedAt: existing?.lastSyncedAt ?? null,
+      });
+      writeJSON(ledger.files.hubPrs, ledger.hubPrs);
+    }
+
+    // Overlay the artifact from the review branch so artifactHash binds approvals to what the
+    // reviewers actually approved (pre-merge, the default branch does not have it yet). A failed
+    // fetch (branch deleted after merge) is fine — the artifact already landed via the merge.
+    const overlay = artifactPaths(job.base).map((p) => path.join('epics', job.epic, p));
+    const fetched = job.branch ? git('fetch', 'origin', job.branch).ok : false;
+    if (fetched) for (const p of overlay) git('checkout', 'FETCH_HEAD', '--', p);
+
+    let failed = false;
+    try {
+      const r = await gateSync(root, { epic: job.epic, artifact: job.artifact, today, reader });
+      synced += r.synced;
+    } catch (err) {
+      if (branch) throw err; // event mode: one epic — surface the failure
+      warn(`${job.epic}: sync failed — ${err.message} — skipping this epic`);
+      process.exitCode = 1;
+      failed = true;
+    } finally {
+      // Drop the overlay — even when sync throws: only the ledger may reach the default branch via CI.
+      if (fetched) {
+        for (const p of overlay) {
+          git('checkout', 'HEAD', '--', p); // tracked files back to HEAD (no-op fail if not in HEAD)
+          git('clean', '-fd', '--', p);     // files new on the branch: remove
+        }
+      }
+    }
+    if (failed) continue; // a failed epic's partial state must not be committed by this run
+    touched.add(job.epic);
+  }
+  if (!touched.size) return { synced };
+
+  // Commit the ledger only, then push with a rebase-retry (ledger commits across epics touch
+  // disjoint files; same-repo runs are serialized by the CI concurrency group).
+  for (const e of touched) {
+    // Separate adds: a pathspec with no match (reviews/ not created yet) must not abort the other.
+    git('add', '-A', '--', path.join('epics', e, '.sdlc'));
+    git('add', '-A', '--', path.join('epics', e, 'reviews'));
+  }
+  if (git('diff', '--cached', '--quiet').ok) { info('ledger unchanged — nothing to commit'); return { synced }; }
+  const subject = branch
+    ? `chore(gate): sync ${jobs[0].epic}/${jobs[0].base} via CI [skip ci]`
+    : 'chore(gate): scheduled gate sync [skip ci]';
+  const cm = git('commit', '-m', subject);
+  if (!cm.ok) { fail(`commit failed: ${cm.stderr || cm.stdout}`); process.exitCode = 1; return { synced }; }
+  ok(`committed ledger update: ${c.dim(subject)}`);
+  if (!push) return { synced };
+
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    if (git('push', 'origin', `HEAD:${target}`).ok) { ok(`pushed ledger to origin/${target}`); return { synced }; }
+    if (attempt < 3) {
+      info(`push rejected — rebasing onto origin/${target} and retrying (${attempt}/3)`);
+      if (!git('pull', '--rebase', 'origin', target).ok) git('rebase', '--abort'); // never leave a wedged rebase
+    }
+  }
+  fail(`could not push the ledger to origin/${target} — protected branch? allow the CI actor to push (see sdlc-hub-bridge references/bridge.md) or run \`sdlc gate sync\` locally`);
+  process.exitCode = 1;
+  return { synced };
+}
+
+export async function gateComments(root, { epic, artifact, today, reader = readPr } = {}) {
+  const { hub } = loadHub(root);
+  if (!hub?.platform) { warn('no hub platform configured — nothing to fetch'); return; }
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  const targets = (ledger.hubPrs || []).filter((p) => !artifact || p.artifact === artifact);
+  if (!targets.length) { warn('no review PR recorded — run `sdlc gate open` first'); return; }
+  for (const pr of targets) {
+    const pull = reader(hub.platform, pr.number, { cwd: root });
+    if (!pull.ok) { warn(`${pr.artifact}: ${pull.reason}`); continue; }
+    const cr = pull.reviews.filter((r) => r.state === 'CHANGES_REQUESTED');
+    const unresolved = (pull.threads || []).filter((t) => !t.resolved);
+    log(`\n  ${c.bold(pr.artifact)} ${c.dim(`(PR #${pr.number})`)}`);
+    if (!cr.length && !unresolved.length) { ok('no unresolved comments — clear to approve/merge'); continue; }
+    for (const r of cr) hand(`${r.login}: changes requested ${c.red('(blocking)')}`);
+    for (const t of unresolved) info(`${t.login || 'reviewer'}: ${(t.body || '').split('\n')[0]}`);
+    writeComments(epicDir, base(pr.artifact), today, [
+      ...cr.map((r) => ({ login: r.login, changesRequested: true })),
+      ...unresolved,
+    ]);
+    hand('address them in the artifact, reply on the PR, then ask reviewers to resolve their threads');
+  }
+}
+
+export async function gateStatus(root, { epic } = {}) {
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  if (!ledger.state) { fail(`no epic state at ${epicDir}`); process.exitCode = 1; return; }
+  log(`\n  ${c.bold(epic)}  ${c.dim(`currentStep: ${ledger.state.currentStep}`)}`);
+  for (const s of ledger.state.steps.filter((x) => x.type === 'review+approve')) {
+    const cur = artifactHash(epicDir, s.artifact);
+    const live = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved' && !(a.artifactHash && cur && a.artifactHash !== cur));
+    const stale = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved' && a.artifactHash && cur && a.artifactHash !== cur).length;
+    const tags = `${isEscalated(s) ? ', escalated' : ''}${stale ? `, ${stale} stale (revoked)` : ''}`;
+    log(`    ${s.status === 'done' ? c.green('✓') : c.yellow('•')} ${s.id} ${c.dim(`— ${s.status}, ${live.length} approval(s)${tags}`)}`);
+  }
+}
+
+export async function gateOpen(root, { epic, artifact, today } = {}) {
+  const { hub, repos } = loadHub(root);
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  if (!ledger.state) { fail(`no epic state at ${epicDir}`); process.exitCode = 1; return; }
+  if (!artifact) { fail('artifact is required: `sdlc gate open <epic> <artifact>`'); process.exitCode = 1; return; }
+  const step = findReviewStep(ledger.state, artifact);
+  if (!step) { fail(`no review step for ${artifact}`); process.exitCode = 1; return; }
+  const b = base(artifact);
+  const branch = `review/${epic}/${b}`;
+  const domains = touchedDomains(epicDir, step);
+  warnUnlockedContract(epicDir, artifact);
+
+  // Mark in-review in the ledger regardless of platform (file-only still works).
+  ledger.state = markInReview(ledger.state, step);
+  writeJSON(ledger.files.state, ledger.state);
+
+  if (!hub?.platform) { warn('no hub platform — marked in_review file-only (no PR opened)'); ok(`${step.id} → in_review`); return; }
+
+  const body = fillHubTemplate({ epic, artifact, step, owner: ownerOf(epicDir), domains });
+  const reviewers = (hub.roster || []).filter((r) => r.role !== 'owner').map((r) => r.login);
+  const labels = isEscalated(step) ? domains.map((d) => `domain:${d}`) : [];
+  info(`opening review ${hub.platform === 'gitlab' ? 'MR' : 'PR'} on branch ${branch} …`);
+  const r = createPr(hub.platform, { title: `review: ${artifact} (${epic})`, body, base: hub.default_branch || 'main', head: branch, reviewers, labels, cwd: root });
+  if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'}); step is in_review file-only`); return; }
+
+  const number = Number((r.url.match(/\/(\d+)(?:[/?#]|$)/) || [])[1]) || null;
+  ledger.hubPrs = upsertHubPr(ledger.hubPrs, { step: step.id, artifact, platform: hub.platform, number, url: r.url, branch, lastSyncedAt: null });
+  writeJSON(ledger.files.hubPrs, ledger.hubPrs);
+  ok(`opened ${r.url}`);
+  hand(`reviewers approve/comment there; then run \`sdlc gate sync ${epic} ${artifact}\``);
+}
+
+// ---- helpers ------------------------------------------------------------------------------------
+const base = (artifact) => artifactBase(artifact);
+
+function fillHubTemplate({ epic, artifact, step, owner, domains }) {
+  return [
+    '## Artifact under review',
+    `- Epic: \`${epic}\``,
+    `- Artifact: \`${artifact}\``,
+    `- Gate step: \`${step.id}\``,
+    `- Owner: \`${owner}\``,
+    '',
+    '## Impact & Risk (front-half)',
+    `- **Domains / repos touched:** ${domains.join(', ') || 'n/a'}`,
+    `- **Risk tags:** ${(step.risk_tags || []).join(', ') || 'none'}`,
+    '',
+    '## How to review (this drives the gate)',
+    '- **Approve** to record your approval; **comment / request changes** to hold the gate.',
+    '- This step advances when approvals are satisfied, all threads are resolved, and this PR is merged.',
+  ].join('\n');
+}
+
+function refreshRoster(epicDir, targets, approvals, today) {
+  for (const pr of targets) {
+    const stepApprovals = approvals.filter((a) => a.step === pr.step && a.status === 'approved');
+    const file = path.join(epicDir, 'reviews', `${base(pr.artifact)}--${today}--approved.md`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const lines = [
+      `# Approval record — ${pr.artifact} — ${today}`, '',
+      '## Approved by',
+      ...stepApprovals.map((a) => `- ${a.approver} — ${a.role}${a.domain ? ` (${a.domain})` : ''} — approved ${a.date}${a.source ? ` (${a.source})` : ''}`),
+      '',
+    ];
+    fs.writeFileSync(file, lines.join('\n') + '\n');
+  }
+}

package/cli/lib.mjs

@@ -0,0 +1,142 @@
+// Shared helpers for the `sdlc` CLI. Node >=18 built-ins only — no dependencies.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Package root = one level up from this cli/ dir. Asset paths (skills/, etc.)
+// resolve from HERE, never from the user's cwd.
+export const PKG_ROOT = fileURLToPath(new URL('../', import.meta.url));
+
+// ---- output -------------------------------------------------------------
+const useColor = output.isTTY && !process.env.NO_COLOR;
+const paint = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const c = {
+  bold: (s) => paint('1', s),
+  dim: (s) => paint('2', s),
+  green: (s) => paint('32', s),
+  yellow: (s) => paint('33', s),
+  red: (s) => paint('31', s),
+  cyan: (s) => paint('36', s),
+};
+export const log = (s = '') => console.log(s);
+export const step = (n, total, title) => log(`\n${c.cyan(`[${n}/${total}]`)} ${c.bold(title)}`);
+export const ok = (s) => log(`  ${c.green('✓')} ${s}`);
+export const info = (s) => log(`  ${c.dim('•')} ${s}`);
+export const warn = (s) => log(`  ${c.yellow('!')} ${s}`);
+export const fail = (s) => log(`  ${c.red('✗')} ${s}`);
+export const hand = (s) => log(`  ${c.yellow('→')} ${s}`);
+
+// ---- prompts ------------------------------------------------------------
+let rl;
+const getRl = () => (rl ??= readline.createInterface({ input, output }));
+export function closePrompts() {
+  rl?.close();
+  rl = undefined;
+}
+export async function ask(question, def = '') {
+  if (process.env.SDLC_NONINTERACTIVE) return def;
+  const suffix = def ? c.dim(` (${def})`) : '';
+  const a = (await getRl().question(`  ${question}${suffix}: `)).trim();
+  return a || def;
+}
+export async function askYesNo(question, def = true) {
+  if (process.env.SDLC_NONINTERACTIVE) return def;
+  const hint = def ? 'Y/n' : 'y/N';
+  const a = (await getRl().question(`  ${question} ${c.dim(`(${hint})`)} `)).trim().toLowerCase();
+  if (!a) return def;
+  return a.startsWith('y');
+}
+
+// ---- filesystem ---------------------------------------------------------
+export const asset = (...p) => path.join(PKG_ROOT, ...p);
+export const exists = (p) => fs.existsSync(p);
+
+export function fileSha(p) {
+  if (!fs.existsSync(p)) return null;
+  return 'sha256:' + createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+}
+// True when dest exists and its bytes match src exactly.
+export function sameContent(src, dest) {
+  const a = fileSha(src);
+  const b = fileSha(dest);
+  return a !== null && a === b;
+}
+
+export function copyFile(src, dest, { exec = false } = {}) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  if (exec) fs.chmodSync(dest, 0o755);
+}
+export function copyDir(src, dest) {
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.cpSync(src, dest, { recursive: true });
+}
+// Recursive list of file paths relative to `dir`.
+export function listFiles(dir, base = dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...listFiles(full, base));
+    else out.push(path.relative(base, full));
+  }
+  return out;
+}
+// True only if every file under src exists in dest with identical bytes.
+export function dirMatches(src, dest) {
+  const files = listFiles(src);
+  if (files.length === 0) return false;
+  return files.every((rel) => sameContent(path.join(src, rel), path.join(dest, rel)));
+}
+
+export function readJSON(p, def = null) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return def;
+  }
+}
+// Strict variant for ledger files (the source of truth): a missing file is a normal state and
+// returns `def`, but a file that exists and fails to parse must throw — silently defaulting a
+// corrupt approvals.json to [] would let the next sync rewrite it and permanently lose approvals.
+export function readJSONStrict(p, def = null) {
+  if (!fs.existsSync(p)) return def;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`corrupt JSON in ${p}: ${e.message} — fix or delete the file`);
+  }
+}
+// Atomic: serialize first, write a sibling tmp file (same dir = same filesystem),
+// then rename over the target. A killed process can never leave a truncated ledger
+// file, and a failed rename never leaves a stray .tmp for `git add -A` to pick up.
+export function writeJSON(p, obj) {
+  const data = JSON.stringify(obj, null, 2) + '\n';
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = `${p}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, data);
+  try {
+    fs.renameSync(tmp, p);
+  } catch (e) {
+    fs.rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+// ---- subprocess ---------------------------------------------------------
+// Returns { ok, stdout, stderr, code }. Never throws on non-zero exit.
+export function run(cmd, args = [], opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return {
+    ok: r.status === 0,
+    code: r.status,
+    stdout: (r.stdout || '').trim(),
+    stderr: (r.stderr || '').trim(),
+    error: r.error,
+  };
+}
+export const has = (cmd) => run(process.platform === 'win32' ? 'where' : 'which', [cmd]).ok;