yadflow 3.18.1 → 4.0.0-next.1

package/cli/artifact-status.mjs

@@ -6,31 +6,41 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { c, log, ok, info, readJSONStrict } from './lib.mjs';
-import { epicRoot, artifactBase, artifactFromBase, findReviewStep, DISCOVERY_FILES } from './epic-state.mjs';
+import {
+  epicIds, epicRoot, artifactBase, artifactFromBase, findReviewStep, DISCOVERY_FILES, FOUNDATION_FILES, isPassed, stepStatus, FRONTMATTER_BLOCK,
+} from './epic-state.mjs';
 import { epicFiles } from './manifest.mjs';
 
-// The front-gate lifecycle this command manages. Forward-only: a status is only ever moved UP this
+// The Shape gate lifecycle this command manages. Forward-only: a status is only ever moved UP this
 // ladder, so a re-run never regresses anything.
 const RANK = { draft: 0, 'in-review': 1, approved: 2 };
 
 // Values owned by other parts of the workflow — left untouched. `locked` is the contract surface;
-// `in-build` / `shipped` are set by the build half (engineer-review) per story; `ready-for-build`,
-// `done`, `blocked` are roll-ups/states we must not overwrite from the front-gate view.
+// `in-build` / `shipped` are set by Build (engineer-review) per story; `ready-for-build`,
+// `done`, `blocked` are roll-ups/states we must not overwrite from the Shape gate view.
 const PRESERVE = new Set(['locked', 'in-build', 'shipped', 'ready-for-build', 'done', 'blocked']);
 
 // The per-epic artifact files this command considers (bases). Story files are handled separately
 // because they live under stories/ and all map to the single stories / stories-review step pair.
 const ARTIFACT_FILES = ['analysis.md', 'epic.md', 'architecture.md', 'contract.md', 'ui-design.md', 'test-cases.md'];
 
-// The desired front-gate status for an artifact base, derived purely from state.json. Returns null
+// The desired Shape gate status for an artifact base, derived purely from state.json. Returns null
 // when the chain has no steps for this base (nothing to manage) — e.g. contract has no own step.
 export function desiredStatus(state, base) {
   if (!state?.steps) return null;
   const review = findReviewStep(state, artifactFromBase(base));
   const author = state.steps.find((s) => s.type === 'author' && artifactBase(s.artifact) === base);
   if (!review && !author) return null;
-  if (review?.status === 'done') return 'approved';
-  if (review?.status === 'in_review' || author?.status === 'done') return 'in-review';
+  // `isPassed`, not `status === 'done'`: a gate that PASSED is what makes an artifact approved,
+  // however it passed. An inherited gate was approved upstream in the thread, and a skipped one has
+  // no artifact for this command to find — both used to reach here spelled `done`.
+  // A gate SET ASIDE — skipped or deferred — lets the chain continue without anybody reviewing the
+  // artifact, so it says nothing about the file. `isPassed` alone read it as approved: a skip taken over a half-written draft,
+  // or a deferral of one, would have had CI stamp `status: approved` on a file nobody reviewed (E37).
+  const reviewState = stepStatus(review);
+  if (reviewState === 'skipped' || reviewState === 'deferred') return null;
+  if (isPassed(review)) return 'approved';
+  if (stepStatus(review) === 'in_review' || isPassed(author)) return 'in-review';
   return 'draft';
 }
 
@@ -41,24 +51,27 @@ export function desiredStatus(state, base) {
 export function setFrontmatterStatus(file, status) {
   if (!fs.existsSync(file)) return null;
   const text = fs.readFileSync(file, 'utf8');
-  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  const fm = text.match(FRONTMATTER_BLOCK);
   if (!fm) return null;
   const cur = (fm[1].match(/^status:\s*(.*)$/m) || [])[1]?.trim();
   if (cur === undefined) return null;
   // Advance-only within the managed ladder; anything else (build-owned, roll-ups) is left as-is.
   if (PRESERVE.has(cur)) return null;
   if (!(cur in RANK) || !(status in RANK) || RANK[status] <= RANK[cur]) return null;
-  const block = fm[1].replace(/^status:\s*.*$/m, `status: ${status}`);
-  fs.writeFileSync(file, text.replace(fm[1], block));
+  // Replacement FUNCTIONS, not strings: in a replacement string `$'`, `$&` and `$$` are codes, so a
+  // frontmatter value holding one (`title: costs $' less`) rewrote the file wrongly — on the default
+  // branch, in the gate's merge commit.
+  const block = fm[1].replace(/^status:\s*.*$/m, () => `status: ${status}`);
+  fs.writeFileSync(file, text.replace(fm[1], () => block));
   return cur;
 }
 
 // Sweep one epic (or every epic under epics/) and reconcile artifact frontmatter with state.json.
 export async function syncStatuses(root, { epic, dryRun = false } = {}) {
-  const epicsDir = path.join(root, 'epics');
-  const epics = epic
-    ? [epic]
-    : (fs.existsSync(epicsDir) ? fs.readdirSync(epicsDir).filter((e) => fs.statSync(path.join(epicsDir, e)).isDirectory()).sort() : []);
+  // `epicIds` — the Foundation included (E75), and only VALID ids: a backup directory or any other
+  // folder left under `epics/` is not an epic, and rewriting frontmatter inside it would be a write to
+  // files nobody asked this command to touch.
+  const epics = epic ? [epic] : epicIds(root);
   if (!epics.length) { info('no epics found — nothing to sync'); return { changed: 0, files: [] }; }
 
   let changed = 0;
@@ -86,6 +99,12 @@ export async function syncStatuses(root, { epic, dryRun = false } = {}) {
     for (const f of DISCOVERY_FILES) {
       if (fs.existsSync(path.join(dir, f))) files.push({ base: 'discovery', file: path.join(dir, f) });
     }
+    // The Foundation's sections key to its one foundation / foundation-review pair the same way. Both
+    // spellings are offered; `desiredStatus` answers null for the base the chain does not carry, so
+    // a converted Foundation holding the six old files still reconciles them under `discovery`.
+    for (const f of FOUNDATION_FILES) {
+      if (fs.existsSync(path.join(dir, f))) files.push({ base: 'foundation', file: path.join(dir, f) });
+    }
 
     for (const { base, file } of files) {
       if (!fs.existsSync(file)) continue;
@@ -95,7 +114,7 @@ export async function syncStatuses(root, { epic, dryRun = false } = {}) {
         // Peek without writing so --dry-run reports exactly what would change. Scope the match to the
         // frontmatter block so a `status:` line in the Markdown body can't be mistaken for the value.
         const text = fs.readFileSync(file, 'utf8');
-        const fm = text.match(/^---\n([\s\S]*?)\n---/);
+        const fm = text.match(FRONTMATTER_BLOCK);
         const cur = (fm?.[1].match(/^status:\s*(.*)$/m) || [])[1]?.trim();
         if (cur && !PRESERVE.has(cur) && cur in RANK && RANK[want] > RANK[cur]) {
           log(`  ${c.dim('• would update')} ${path.relative(root, file)}: ${cur} → ${want}`);

package/cli/checkpoint.mjs

@@ -1,19 +1,19 @@
-// `yad checkpoint` — commit the machine-written back-half hub state (trust-log / build-log /
-// build-state) as one audit-trail commit. This is the back-half analogue of the front-half gate sync
-// (cli/gate.mjs): the SDLC back half (yad-run, yad-engineer-review) WRITES these ledgers into the
+// `yad checkpoint` — commit the machine-written Build state on the Product (trust-log / build-log /
+// build-state) as one audit-trail commit. This is the Build analogue of the Shape gate sync
+// (cli/gate.mjs): the SDLC's Build part (yad-run, yad-engineer-review) WRITES these ledgers into the
 // working tree but never commits them, so teammates/CI/`yad status` on other machines see stale trust
 // evidence. checkpoint lands them with a `chore(hub): ...` message.
 //
-// It also carries the back-half story `status:` flip (approved → in-build/shipped) that
+// It also carries the Build story `status:` flip (approved → in-build/shipped) that
 // yad-engineer-review writes into stories/<id>.md but no command committed — the #112 drift where
 // build-log said shipped while the story artifact still said approved. Only story files with build-log
 // ship evidence are carried (storyStatusPathspecs), AND only when their staged change is the `status:`
-// line alone (stagedStoryIsStatusOnly) — so it stays a back-half record, never a raw edit that would
+// line alone (stagedStoryIsStatusOnly) — so it stays a Build record, never a raw edit that would
 // slip prose onto the default branch under a `[skip ci]` commit that bypasses review.
 //
 // Two invariants keep it out of the gates' way:
-//   1. It stages ONLY the back-half ledgers + build-log-backed story flips by an explicit allowlist —
-//      never `git add -A`, which would sweep the CI-owned front-half ledger (state/approvals/
+//   1. It stages ONLY the Build ledgers + build-log-backed story flips by an explicit allowlist —
+//      never `git add -A`, which would sweep the CI-owned Shape ledger (state/approvals/
 //      comments/hub-prs.json, reviews/*.md) and trip the ledger-guard gate. (ledger-guard does NOT
 //      protect stories/*.md, and this commits to the default branch, never a PR range, so the carried
 //      story flip is safe.)
@@ -22,15 +22,15 @@
 //      marker would strand the PR's required checks.
 import fs from 'node:fs';
 import path from 'node:path';
-import { c, log, ok, info, fail, hand, exists, readJSON, pushWithRebase } from './lib.mjs';
-import { PROJECT_FILES } from './manifest.mjs';
-import { loadHub } from './gate.mjs';
-import { resolveCommitterLogin } from './platform.mjs';
-import { hubGit, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
+import { c, log, ok, info, fail, hand, exists, readJSON, readJSONStrict, pushWithRebase } from './lib.mjs';
+import { PROJECT_FILES , productConfigPath } from './manifest.mjs';
+import { loadProduct } from './gate.mjs';
+import { platformLogin } from './platform.mjs';
+import { productGit, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
 import { readShips, writeRetroShip } from './ledger.mjs';
-import { readFrontmatter } from './epic-state.mjs';
+import { readFrontmatter, declaredRepos } from './epic-state.mjs';
 
-// The machine-written back-half ledgers, relative to an epic's dir. The two append-only logs are
+// The machine-written Build ledgers, relative to an epic's dir. The two append-only logs are
 // shard-then-fold (cli/ledger.mjs): each is a folded file PLUS a shard dir of loose per-entry files —
 // both are allowlisted so a checkpoint commits new shards and any `yad tidy up` fold. `build-state` is
 // the whole dir (one JSON per story). Keep in sync with cli/manifest.mjs epicFiles.
@@ -40,9 +40,9 @@ const BACK_HALF = [
   '.sdlc/build-state',
 ];
 
-// PURE — the repo-relative pathspecs to stage: every back-half ledger that exists under any epic.
+// PURE — the repo-relative pathspecs to stage: every Build ledger that exists under any epic.
 // Explicit allowlist by design (see invariant 1 above).
-export function backHalfPathspecs(root) {
+export function buildLedgerPathspecs(root) {
   const epicsDir = path.join(root, 'epics');
   if (!fs.existsSync(epicsDir)) return [];
   const out = [];
@@ -55,17 +55,17 @@ export function backHalfPathspecs(root) {
   return out;
 }
 
-// The two back-half story statuses. `in-build` = some of a story's tasks shipped; `shipped` = all did.
-// Both are set ONLY by the build half (yad-engineer-review), never by the front-gate ladder
+// The two Build story statuses. `in-build` = some of a story's tasks shipped; `shipped` = all did.
+// Both are set ONLY by Build (yad-engineer-review), never by the Shape gate ladder
 // (cli/artifact-status.mjs PRESERVEs them). See #112.
 const BACK_HALF_STATUSES = new Set(['in-build', 'shipped']);
 
-// The repo-relative pathspecs for story files whose back-half `status:` flip we carry alongside the
+// The repo-relative pathspecs for story files whose Build `status:` flip we carry alongside the
 // ledgers (#112). The flip is authored by yad-engineer-review into the working tree but no command
 // committed it, so it drifted (build-log said shipped, stories/<id>.md still said approved) and the
 // only recovery was a raw git-to-main push. A story is a CANDIDATE iff BOTH hold:
-//   1. it has >=1 ship recorded in build-log (the build-half evidence), and
-//   2. its current frontmatter `status:` is a back-half value (in-build | shipped).
+//   1. it has >=1 ship recorded in build-log (the Build evidence), and
+//   2. its current frontmatter `status:` is a Build value (in-build | shipped).
 // A candidate is only actually carried when its staged diff is the `status:` line ALONE — runCheckpoint
 // drops any candidate whose working tree also changed prose/other frontmatter (stagedStoryIsStatusOnly),
 // so an unrelated edit can never ride into a `chore(hub) … [skip ci]` commit that bypasses review.
@@ -74,7 +74,7 @@ const BACK_HALF_STATUSES = new Set(['in-build', 'shipped']);
 //
 // A corrupt build-log in one epic must not block checkpointing every OTHER epic's ledgers, so a
 // readShips throw is caught per epic (that epic simply carries no story flip; its corrupt ledger is
-// still staged by backHalfPathspecs for a human to see).
+// still staged by buildLedgerPathspecs for a human to see).
 export function storyStatusPathspecs(root) {
   const epicsDir = path.join(root, 'epics');
   if (!fs.existsSync(epicsDir)) return [];
@@ -107,7 +107,7 @@ export function summarizeStaged(files = []) {
   const epics = new Set();
   const basenames = [];
   for (const f of files) {
-    // A back-half ledger (…/.sdlc/…) or a carried story-status flip (…/stories/<id>.md, #112).
+    // A Build ledger (…/.sdlc/…) or a carried story-status flip (…/stories/<id>.md, #112).
     const m = f.match(/^epics\/([^/]+)\/(?:\.sdlc\/(.+)|stories\/(.+\.md))$/);
     if (!m) continue;
     const [, epic] = m;
@@ -130,7 +130,7 @@ export function summarizeStaged(files = []) {
 // path from breaking the one-line subject or injecting a fake trailer line.
 const oneLine = (s = '') => String(s).replace(/\s+/g, ' ').trim();
 
-// `@login` from the roster (the auditable handle the user asked for), else the raw git user.name,
+// `@login` from the platform CLI (the auditable handle the user asked for), else the raw git user.name,
 // else a stable placeholder so the subject is never empty.
 export function checkpointAuthor(login, name) {
   if (login) return `@${oneLine(login)}`;
@@ -138,12 +138,12 @@ export function checkpointAuthor(login, name) {
   return n || 'unknown';
 }
 
-// PURE — the audit-trail commit message. The subject passes the hub commit-message gate (valid type
+// PURE — the audit-trail commit message. The subject passes the Product commit-message gate (valid type
 // `chore`, optional scope `hub`, non-empty description, no trailing period). No Task trailer and no
 // Co-Authored-By footer: this is human-owned machine state, not an authored code change. `label` and
 // `author` are collapsed to one line so nothing can split the subject or forge a trailer.
 export function buildCheckpointMessage({ label, author, basenames = [] }) {
-  const subject = `chore(hub): sync back-half state — ${oneLine(label)} by ${oneLine(author)} [skip ci]`;
+  const subject = `chore(hub): sync Build state — ${oneLine(label)} by ${oneLine(author)} [skip ci]`;
   const body = basenames.length ? `Updated: ${basenames.join(', ')}` : '';
   return body ? `${subject}\n\n${body}` : subject;
 }
@@ -151,7 +151,7 @@ export function buildCheckpointMessage({ label, author, basenames = [] }) {
 // True iff a story file's STAGED diff changes ONLY the frontmatter `status:` line — every added or
 // removed content line is a `status:` line. A newly-added file (all lines added) or any prose/other
 // edit fails, so only a clean flip is carried into the `[skip ci]` chore commit; anything broader is
-// left for a reviewed change (#112 review-bypass guard). `git` is a hubGit-style accessor.
+// left for a reviewed change (#112 review-bypass guard). `git` is a productGit-style accessor.
 export function stagedStoryIsStatusOnly(git, file) {
   const d = git('diff', '--cached', '-U0', '--', file);
   if (!d.ok) return false;
@@ -170,21 +170,20 @@ export function stagedStoryIsStatusOnly(git, file) {
 // normal checkpoint path carries the story's already-made `status:` flip. Returns { ok, file } — ok:false
 // (with a printed reason) aborts the commit; `file` is the shard just written, so a dry run can delete it
 // and leave no side effect. Does NOT author the story frontmatter — it only supplies the missing
-// evidence, and the human must have ALREADY flipped `status:` to a back-half value in the working tree.
+// evidence, and the human must have ALREADY flipped `status:` to a Build value in the working tree.
 //
 // ONE repo per run (#166). A story that shipped in several repos is backfilled by re-running with each
 // `--repo`; the second run finds the flip already committed, so it lands only the new ship shard.
 //
 // The repo names a retro ship MAY carry — the story's own `repos:` frontmatter (its statement of where
-// it was implemented), else the hub's connected-repo registry as the project-wide fallback. Used to
+// it was implemented), else the Product's connected-repo registry as the project-wide fallback. Used to
 // reject a typo'd/mis-cased/invented `--repo` (#166 review): once the duplicate guard is per repo, a
 // wrong name no longer collides with anything, so nothing else would stop it from committing a
 // `retroactive: true` ship for a repo that never existed. Returns `{ names: [], source: 'none' }` when
 // neither declares anything — a legacy story with no metadata is still backfillable, never blocked on
 // a missing list.
 export function retroShipRepos(root, storyFile) {
-  const declared = readFrontmatter(storyFile).repos;
-  const story = (Array.isArray(declared) ? declared : declared ? [declared] : []).map(String).filter(Boolean);
+  const story = declaredRepos(readFrontmatter(storyFile));
   if (story.length) return { names: story, source: 'story' };
   const reg = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
   const names = (Array.isArray(reg?.repos) ? reg.repos : []).map((r) => r?.name).filter(Boolean);
@@ -201,7 +200,7 @@ export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, to
   if (!exists(storyFile)) { fail(`no story ${story} under epics/${epic}/stories/`); return { ok: false }; }
 
   // Evidence and the flip must land TOGETHER — the #112 no-drift invariant. Refuse unless the human has
-  // already flipped the story frontmatter to a back-half status in the working tree; otherwise the ship
+  // already flipped the story frontmatter to a Build status in the working tree; otherwise the ship
   // shard would commit while the artifact still says e.g. `approved` — the very drift #112 prevents.
   const storyStatus = readFrontmatter(storyFile).status;
   if (!BACK_HALF_STATUSES.has(storyStatus)) {
@@ -215,20 +214,38 @@ export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, to
   // repo (`source: 'none'`), so a legacy story with no metadata is never blocked.
   const { names, source } = retroShipRepos(root, storyFile);
   if (names.length && !names.includes(repo)) {
-    fail(`${repo} is not a repo ${source === 'story' ? `${story} declares` : 'connected to this hub'} — a retroactive ship must name a real repo, never invent one`);
+    fail(`${repo} is not a repo ${source === 'story' ? `${story} declares` : 'connected to this Product'} — a retroactive ship must name a real repo, never invent one`);
     hand(`known: ${names.join(', ')} (names are case-sensitive)`);
     return { ok: false };
   }
+  // A lane SKIPPED whole (E39) did not ship: recording a ship for it would make the two records contradict.
+  // And a skipped repo is not "still unrecorded" — it is owed nothing — so it is left out of `remaining`.
+  // Read STRICTLY: a corrupt file would otherwise read as "nothing skipped" and let a permanent ship be
+  // recorded over a skip — the same refusal to guess this function makes for a corrupt build-log (E39 review).
+  let laneRepos;
+  try { laneRepos = readJSONStrict(path.join(epicDir, '.sdlc', 'build-state', `${story}.json`), null)?.repos; }
+  catch (e) {
+    fail(`could not read ${story}'s build-state — ${e.message}`);
+    hand('a ship is permanent audit evidence, so it is not recorded while the lane state cannot be read — fix the file, then re-run');
+    return { ok: false };
+  }
+  const skipped = new Set(laneRepos && typeof laneRepos === 'object'
+    ? Object.entries(laneRepos).filter(([, lane]) => lane?.status === 'skipped').map(([name]) => name) : []);
+  if (skipped.has(repo)) {
+    fail(`${story} / ${repo} is skipped — a lane that was skipped did not ship`);
+    hand(`if it did ship after all, put the lane back first: yad unskip ${epic} ${story} --repo ${repo}`);
+    return { ok: false };
+  }
   // Which of the story's OWN declared repos still lack evidence — read BEFORE the write so both the
   // refusal and the success path can report honestly how much of a multi-repo backfill is left. Only
-  // the story's own list is used: the hub registry lists every connected repo, which says nothing
+  // the story's own list is used: the Product registry lists every connected repo, which says nothing
   // about where THIS story shipped.
   const remaining = () => {
     if (source !== 'story') return [];
     let recorded;
     try { recorded = new Set(readShips(epicDir).filter((s) => s.story === story).map((s) => s.repo)); }
     catch { return []; } // corrupt build-log — the write below reports it; don't guess at progress
-    return names.filter((n) => !recorded.has(n) && n !== repo);
+    return names.filter((n) => !recorded.has(n) && n !== repo && !skipped.has(n));
   };
   const left = remaining();
 
@@ -289,14 +306,14 @@ function cleanupRetroShard(file) {
 export async function runCheckpoint(root, opts = {}) {
   log(c.bold('\nyad checkpoint'));
   if (!exists(path.join(root, '.git'))) { fail('not a git repo'); process.exitCode = 1; return; }
-  if (!exists(path.join(root, PROJECT_FILES.hubConfig))) {
-    fail('no .sdlc/hub.json — checkpoint commits the hub back-half ledger; run it from the product hub');
+  if (!exists(productConfigPath(root))) {
+    fail('no .sdlc/hub.json — checkpoint commits the Product Build ledger; run it from the Product');
     process.exitCode = 1;
     return;
   }
 
-  const { hub } = loadHub(root);
-  const git = hubGit(root);
+  const { hub } = loadProduct(root);
+  const git = productGit(root);
   const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
   const defaultBranch = resolveDefaultBranch(git, hub);
 
@@ -304,7 +321,7 @@ export async function runCheckpoint(root, opts = {}) {
   if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad checkpoint' })) return;
 
   // --retro-ship (#142): record a retroactive build-log ship for a PRE-TRACKING story (merged before
-  // the back-half ledger existed, so it has no ship and its `status:` flip can't be carried). Done
+  // the Build ledger existed, so it has no ship and its `status:` flip can't be carried). Done
   // AFTER the branch guard so we never leave a dangling shard on the wrong branch; the flip the human
   // already wrote is then carried by the normal storyStatusPathspecs path below — no raw git needed.
   let retroFile;
@@ -321,11 +338,13 @@ export async function runCheckpoint(root, opts = {}) {
   // plain `yad checkpoint` as permanent `retroactive: true` audit evidence nobody chose to record.
   // A real run deliberately keeps its shard on a failure (see the commit-failed path below).
   const rollbackRetro = () => { if (opts.dryRun && retroFile) cleanupRetroShard(retroFile); };
+  // The --json answer (E1) of a run that had nothing to commit.
+  const nothing = () => ({ message: null, files: [], committed: false, pushed: false, dryRun: !!opts.dryRun, retroShip: null });
 
   // The machine ledgers PLUS any build-log-backed story `status:` flip (#112) — one commit records
   // both, so the story artifact never drifts from build-log and no raw git-to-main push is needed.
-  const pathspecs = [...backHalfPathspecs(root), ...storyStatusPathspecs(root)];
-  if (!pathspecs.length) { rollbackRetro(); info('no back-half ledgers found — nothing to checkpoint'); return; }
+  const pathspecs = [...buildLedgerPathspecs(root), ...storyStatusPathspecs(root)];
+  if (!pathspecs.length) { rollbackRetro(); info('no Build ledgers found — nothing to checkpoint'); return nothing(); }
 
   // Stage the allowlist. `git add -- <spec>` picks up new + modified files, and deletions of tracked
   // files WITHIN a still-present spec (e.g. a removed build-state/<story>.json). A wholesale-deleted
@@ -348,8 +367,8 @@ export async function runCheckpoint(root, opts = {}) {
 
   if (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
     rollbackRetro();
-    info('back-half state unchanged — nothing to commit');
-    return;
+    info('Build state unchanged — nothing to commit');
+    return nothing();
   }
   // The exact files staged from the allowlist — all known to git by construction, so they are the
   // pathspec for the commit (a directory spec like build-state/ would make `git commit -- <dir>` fail
@@ -358,7 +377,7 @@ export async function runCheckpoint(root, opts = {}) {
   const staged = git('diff', '--cached', '--name-only', '--', ...pathspecs).stdout.split('\n').filter(Boolean);
 
   const { label, basenames } = summarizeStaged(staged);
-  const author = checkpointAuthor(resolveCommitterLogin(root, hub?.roster || []), git('config', 'user.name').stdout);
+  const author = checkpointAuthor(platformLogin(root, hub?.platform), git('config', 'user.name').stdout);
   const message = buildCheckpointMessage({ label, author, basenames });
 
   if (opts.dryRun) {
@@ -368,7 +387,7 @@ export async function runCheckpoint(root, opts = {}) {
     // run leaves no side effect on disk (git reset only unstaged it, back to untracked).
     rollbackRetro();
     info('dry run — not committed');
-    return { message };
+    return { message, files: staged, committed: false, pushed: false, dryRun: true, retroShip: null };
   }
 
   const cm = git('commit', '-m', message, '--', ...staged);
@@ -381,14 +400,15 @@ export async function runCheckpoint(root, opts = {}) {
     return { message };
   }
   ok(`checkpointed ${staged.length} file(s): ${c.dim(label)}`);
+  const done = { message, files: staged, committed: true, dryRun: false, retroShip: retroFile ? path.relative(root, retroFile) : null };
 
-  if (!opts.push) return { message };
+  if (!opts.push) return { ...done, pushed: false };
   // Push HEAD to its OWN branch — never to `defaultBranch` blindly. On the default branch these are the
   // same; with --allow-branch on a WIP branch, pushing HEAD:defaultBranch would publish the whole WIP
   // branch to the default branch (bypassing review), so the target is always the branch we are on.
-  if (pushWithRebase(root, branch).ok) { ok(`pushed to origin/${branch}`); return { message }; }
+  if (pushWithRebase(root, branch).ok) { ok(`pushed to origin/${branch}`); return { ...done, pushed: true }; }
   fail(`could not push to origin/${branch} — a protected branch, or the append-only ledgers hit an unresolvable rebase conflict`);
   hand(`run \`git pull --rebase\` and re-run \`yad checkpoint --push\``);
   process.exitCode = 1;
-  return { message };
+  return { ...done, pushed: false };
 }

package/cli/codeowners-command.mjs

@@ -0,0 +1,170 @@
+// `yad codeowners check [<repo>]` — warn where a code repo's CODEOWNERS has gone stale (E69). The rules for
+// reading the file are E68's (cli/codeowners.mjs); this finds the repos, reads each file from disk, and
+// prints. Part 3: "CODEOWNERS is a hint, never an authority — in practice these files rot." So this only
+// ever WARNS: it never sets a failing exit code for a finding, never writes the file (there is no
+// `--write`: any name yad wrote would become an owner the platform can enforce), and never says who owns
+// code.
+//
+// Two kinds of answer, kept apart:
+//   FACTS — a line that matches no file, a GitHub file of 3 MB or more, a second file the platform never
+//     reads, a line this reader cannot read. `yad doctor` prints these too.
+//   A HINT — the @logins with no commit in the last 90 days that carries their noreply address. Only a
+//     hint: a person may commit under a work address. Printed by this command only, never by the doctor,
+//     and only where a noreply address is evidence (a github.com or gitlab.com remote).
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+
+import { c, fail, hand, info, log, ok, run, warn, emitJSON } from './lib.mjs';
+import { deadLines, diskCodeowners, parseCodeowners } from './codeowners.mjs';
+import { OWNER_WINDOW, recentLoginsFor, repoFiles, targets } from './riskmap-command.mjs';
+import { PUBLIC_HOST, remoteHost } from './openpr.mjs';
+import { detectPlatform } from './platform.mjs';
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const PLATFORM_NAME = { github: 'GitHub', gitlab: 'GitLab' };
+// "90 days ago" → "90 days", for the sentences.
+const WINDOW_WORDS = OWNER_WINDOW.replace(/ ago$/, '');
+
+// The paths of a repo's submodules: their contents are not in its file list.
+function submodulesOf(repoRoot) {
+  const r = spawnSync('git', ['ls-files', '-z', '--stage'], { cwd: repoRoot, encoding: 'utf8', maxBuffer: 1 << 30 });
+  if (r.status !== 0) return [];
+  return r.stdout.split('\0').filter((l) => l.startsWith('160000 ')).map((l) => l.slice(l.indexOf('\t') + 1));
+}
+
+// A pattern is printed as written unless it holds an `@`: E67's rule that no e-mail address is ever printed.
+const shownPattern = (d) => (d.pattern.includes('@') ? '' : ` (\`${d.negate ? '!' : ''}${d.pattern}\`)`);
+
+// One repo → { git, platform, path?, none?, unknown?, tooBig?, ignored, notRead, dead, inactive? }. With
+// `hint`, `inactive` is { unknown } or { quiet, checked, notChecked } (see the header).
+export function checkCodeowners(repoRoot, { platform = null, remote, hint = false } = {}) {
+  // A work tree, not only a repo: a bare repo has no files on disk to check.
+  if (run('git', ['rev-parse', '--is-inside-work-tree'], { cwd: repoRoot }).stdout !== 'true') return { git: false };
+  // The platform reads CODEOWNERS from the repo's top folder, and the file list must be the whole repo's.
+  // `.native`: git names the folder as the disk stores it, and on a disk that ignores case the plain
+  // `realpathSync` keeps the case it was given (`../MyRepo` for `myrepo`) — never the same folder twice.
+  const top = run('git', ['rev-parse', '--show-toplevel'], { cwd: repoRoot }).stdout;
+  if (!top || fs.realpathSync.native(top) !== fs.realpathSync.native(repoRoot)) {
+    return { git: true, platform: null, ignored: [], notRead: [], dead: [], unknown: 'this folder is inside a git repo but is not its top folder, where the platform reads CODEOWNERS — check the repo\'s top folder instead' };
+  }
+  const url = remote ?? run('git', ['remote', 'get-url', 'origin'], { cwd: repoRoot }).stdout;
+  const plat = platform || detectPlatform(url || '');
+  const base = { git: true, platform: plat, ignored: [], notRead: [], dead: [] };
+  if (!plat) return { ...base, unknown: 'yad cannot tell whether this repo is on GitHub or GitLab (no `platform` in repos.json, and the origin remote names neither) — pass --platform' };
+  const co = diskCodeowners(repoRoot, plat);
+  if (co.unknown) return { ...base, unknown: co.unknown };
+  if (co.none) return { ...base, none: co.none };
+  const out = { ...base, path: co.path, ignored: co.ignored };
+  if (co.tooBig) return { ...out, tooBig: true };
+  // Only now the file list: it is slow on a large repo, and a repo with no CODEOWNERS never needs it.
+  const files = repoFiles(repoRoot);
+  if (!files) return { ...base, unknown: 'git could not list the files in this repo' };
+  const parsed = parseCodeowners(co.text, plat);
+  out.notRead = parsed.skipped;
+  out.dead = deadLines(parsed, files, { submodules: submodulesOf(repoRoot) });
+  if (hint) out.inactive = inactiveOwners(repoRoot, parsed, plat, url);
+  return out;
+}
+
+// The hint: which @logins no recent commit names. Only a person's login can be checked — a team, group,
+// role or address has no noreply commits of its own — and only on the public host a noreply login
+// belongs to. On GitLab an `@name` may be a group; the sentence printed is true either way.
+function inactiveOwners(repoRoot, parsed, platform, url) {
+  const persons = new Map();
+  const others = new Map();
+  for (const r of parsed.rules) {
+    if (r.negate) continue;
+    for (const o of r.owners) {
+      if (o.kind === 'user' || o.kind === 'name') {
+        const k = o.text.slice(1).toLowerCase();
+        if (!persons.has(k)) persons.set(k, o.text);
+      } else others.set(`${o.kind}\0${o.key || o.text}`, o.kind);
+    }
+  }
+  const notChecked = {};
+  for (const kind of others.values()) notChecked[kind] = (notChecked[kind] || 0) + 1;
+  if (!persons.size) return { quiet: [], checked: 0, notChecked };
+  const host = PUBLIC_HOST[platform];
+  if (remoteHost(url) !== host) {
+    return { unknown: `the origin remote is not on ${host}, and a noreply address is evidence only for a ${host} account (a self-managed server keeps its own accounts)` };
+  }
+  const h = recentLoginsFor(repoRoot, 'HEAD');
+  if (h.unknown) return { unknown: h.unknown };
+  const seen = new Set(h.logins.filter((l) => l.host === platform).map((l) => l.login.toLowerCase()));
+  return { quiet: [...persons].filter(([k]) => !seen.has(k)).map(([, text]) => text), checked: persons.size, notChecked };
+}
+
+// The facts as a list: [{ code, line?, target?, message }] — what `yad doctor` summarises and `--json` prints.
+export function codeownersFindings(r) {
+  const out = [];
+  const name = PLATFORM_NAME[r.platform] || r.platform;
+  if (r.tooBig) out.push({ code: 'too-big', target: r.path, message: `${r.path} is 3 MB or more — GitHub does not load a file that large, so it lists no owner for any file` });
+  for (const p of r.ignored) out.push({ code: 'never-read', target: p, message: `${p} is never read — ${name} reads ${r.path} first` });
+  for (const s of r.notRead) out.push({ code: 'not-read', line: s.line, message: `line ${s.line} not read — ${s.why}` });
+  for (const d of r.dead) {
+    out.push({ code: 'matches-nothing', line: d.line, message: `line ${d.line}${shownPattern(d)} ${d.negate ? 'excludes' : 'matches'} no file in this repo` });
+  }
+  return out;
+}
+
+const KIND_WORD = { team: ['team'], group: ['group'], role: ['role'], email: ['e-mail address', 'e-mail addresses'] };
+
+function printRepo(name, r) {
+  log(c.bold(`\ncodeowners — ${name}`));
+  if (!r.git) { warn('no files on disk to check (not a git repo, or a bare one) — skipped'); return; }
+  if (r.unknown) { warn(`CODEOWNERS: not known — ${r.unknown}`); return; }
+  if (r.none) { info(`none — ${r.none}; nothing to check`); return; }
+  const findings = codeownersFindings(r);
+  for (const f of findings) warn(f.message);
+  if (!findings.length) ok(`${r.path}: every line yad can read matches a file`);
+  const i = r.inactive;
+  if (i?.unknown) info(`owners with recent commits: not known — ${i.unknown}`);
+  else if (i) {
+    const host = PUBLIC_HOST[r.platform];
+    const partial = r.notRead.length ? ' (from the lines yad could read)' : '';
+    if (i.quiet.length) {
+      const gl = r.platform === 'gitlab' ? '; on GitLab an @name can also be a group, which never commits' : '';
+      hand(`no commit on the checked-out branch in the last ${WINDOW_WORDS} carries a ${host} noreply address for ${i.quiet.join(', ')}${partial} — a hint only: they may commit under another address or work in other repos, so this does not mean they have left${gl}`);
+    } else if (i.checked) {
+      info(`every @login ${r.path} lists${partial} has a commit in the last ${WINDOW_WORDS} with its ${host} noreply address`);
+    }
+    const nc = Object.entries(i.notChecked).map(([k, n]) => plural(n, ...(KIND_WORD[k] || [k])));
+    if (nc.length) info(`not checked for recent commits: ${nc.join(', ')} — the hint reads only @logins`);
+  }
+  if (findings.length) hand(`fix ${r.path} in ${name} through a PR — the warnings are advisory: CODEOWNERS is a hint, and yad never enforces it`);
+}
+
+export async function runCodeowners(root, { action = 'check', name, json = false, platform = null, write = false } = {}) {
+  if (action !== 'check' || write) {
+    // `--write` was part of E69's title and was dropped by decision: a name yad wrote into the file would
+    // become an owner the platform can enforce (GitHub's "Require review from Code Owners", GitLab's code
+    // owner approval), turning a hint into an authority. Said plainly, so a habit or a script learns why.
+    const refused = write || action === 'write' || action === '--write';
+    const error = refused ? 'yad never writes CODEOWNERS — any name it wrote would become an owner the platform can enforce'
+      : `unknown action: ${action} (use: yad codeowners check [repo])`;
+    const hint = refused ? 'edit CODEOWNERS by hand and commit it through a PR; `yad codeowners check` shows which lines look stale' : '';
+    if (json) emitJSON({ ok: false, error, ...(hint ? { hint } : {}) });
+    else { fail(error); if (hint) hand(hint); }
+    process.exitCode = 1;
+    return { ok: false };
+  }
+  const t = targets(root, name);
+  if (t.error) {
+    if (json) emitJSON({ ok: false, error: t.error, hint: t.hint });
+    else { fail(t.error); hand(t.hint); }
+    process.exitCode = 1;
+    return { ok: false };
+  }
+  const repos = t.list.map((x) => ({ name: x.name, root: x.root, ...checkCodeowners(x.root, { platform: platform || x.platform, hint: true }) }));
+  if (json) {
+    emitJSON({ ok: true, repos: repos.map((r) => ({
+      name: r.name, git: r.git, platform: r.platform ?? null, path: r.path ?? null,
+      ...(r.none ? { none: r.none } : {}), ...(r.unknown ? { unknown: r.unknown } : {}),
+      findings: r.git && !r.unknown && !r.none ? codeownersFindings(r) : [],
+      ...(r.inactive ? { inactive: r.inactive } : {}),
+    })) });
+    return { ok: true, repos };
+  }
+  for (const r of repos) printRepo(r.name, r);
+  return { ok: true, repos };
+}