yadflow 3.19.0-next.2 → 4.0.0-next.3

package/cli/checkpoint.mjs

@@ -1,4 +1,4 @@
-// `yad checkpoint` — commit the machine-written Build hub state (trust-log / build-log /
+// `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
@@ -22,13 +22,13 @@
 //      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 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 —
@@ -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,7 +138,7 @@ 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.
@@ -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;
@@ -176,15 +176,14 @@ export function stagedStoryIsStatusOnly(git, file) {
 // `--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);
@@ -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 Build 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);
 
@@ -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 = [...buildLedgerPathspecs(root), ...storyStatusPathspecs(root)];
-  if (!pathspecs.length) { rollbackRetro(); info('no Build ledgers found — nothing to checkpoint'); return; }
+  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
@@ -349,7 +368,7 @@ export async function runCheckpoint(root, opts = {}) {
   if (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
     rollbackRetro();
     info('Build state unchanged — nothing to commit');
-    return;
+    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/claims.mjs

@@ -0,0 +1,165 @@
+// `yad claims` (E46) — who else is editing which artifact, read from the E43 capture branches.
+//
+// "architecture.md — claimed by alice, 10:04." ADVICE, NOT A LOCK: with no server a real lock is impossible,
+// and a claim never stops anyone. The decisions were the user's (2026-09-25):
+//   1. SOURCE: the capture branches, and nothing else. There is no claim file and no `yad claim` command —
+//      "record" is E43's capture, which already commits every edit to `yad/wip/<name>/<epic>` and pushes it.
+//   2. SHOW: this command (it fetches everyone's capture branches first), and a warning at edit time from the
+//      post-edit capture hook, which reads only what is already fetched and never blocks. On Claude Code the
+//      warning reaches the agent (`additionalContext`); elsewhere it is a line on stderr.
+//   3. EXPIRY: 4 hours after the branch's last capture — and at once for a file whose change is on the default
+//      branch (its content there equals the capture's), so a merged fold releases its files.
+//   4. FRESHNESS: the hook's throttled background push also starts a background fetch of everyone's capture
+//      branches (cli/capture.mjs), so what the hook reads is minutes old, not hours.
+//
+// WHAT A CLAIM IS: a file of the epic that differs between the capture branch's tip and the tip's `Yad-Base`
+// — the HEAD that capture was built on. That is exactly the person's own in-progress edits. It is NOT the
+// diff against the previous capture: after a pull, a capture's tree is the NEW HEAD plus the edits, and the
+// pull's changes would read as that person's work. When `Yad-Base` is not in this clone (a later HEAD is not
+// an ancestor of the branch, so it was never pushed with it), the commit the branch's FIRST capture was built
+// on is the fallback, marked `basis: 'first-capture'` — over-reporting is the safe direction for advice.
+// The hook's background fetch and push can both move this person's own remote-tracking copies at once; one
+// may lose the race in silence. Nothing reads those copies while the local branch exists, and a capture by
+// hand fetches (with prune) before it relies on them.
+//
+// LIMITS, said in the README: capture off, or offline, is invisible; the push runs at most every 5 minutes;
+// two people with one git name share branches, so they never see each other; clocks are the committer's.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { ok, info, warn, fail, hand, readJSON, writeJSON } from './lib.mjs';
+import { productConfigPath } from './manifest.mjs';
+import { capturedEpic, gitIn, isOwnerPath, pushEnv, wipName, WIP_PREFIX, fetchAllArgs } from './capture.mjs';
+import { resolveDefaultBranch } from './hubcommit.mjs';
+
+export const CLAIM_HOURS = 4;
+const CLAIM_MS = CLAIM_HOURS * 60 * 60 * 1000;
+
+// The default branch as a ref this clone holds — origin's copy first, then a local branch — or null.
+function defaultRef(root, git) {
+  const hub = readJSON(productConfigPath(root), {}) || {};
+  const def = resolveDefaultBranch((...a) => { const r = git(a); return { ok: r.ok, stdout: r.out.trim() }; }, hub);
+  for (const ref of [`refs/remotes/origin/${def}`, `refs/heads/${def}`]) if (git(['rev-parse', '--verify', '-q', `${ref}^{commit}`]).ok) return { ref, name: def };
+  return { ref: null, name: def };
+}
+
+// Every open claim this clone can see. `epics` narrows to those epics; `now` is a number of milliseconds.
+// Returns { me, claims: [{ path, epic, name, person, lastSavedAt, mine, basis }], defaultBranch }.
+export function readClaims(root, { env = process.env, now = Date.now(), epics = null } = {}) {
+  const git = gitIn(root, env);
+  const prefix = git(['rev-parse', '--show-prefix']).out.trim();
+  const me = wipName(git(['config', 'user.name']).out.trim(), git(['config', 'user.email']).out.trim());
+  const def = defaultRef(root, git);
+  const empty = git(['hash-object', '-t', 'tree', '--stdin'], '').out.trim();
+  const fmt = '%(refname)%00%(objectname)%00%(committerdate:unix)%00%(authorname)%00%(trailers:key=Yad-Base,valueonly)';
+  // Others' branches from the remote-tracking copies; my own from the local branches, which are the freshest.
+  const roots = [`refs/remotes/origin/${WIP_PREFIX}/`, ...(me ? [`refs/heads/${WIP_PREFIX}/${me}/`] : [])];
+  // `trailer.separators=:` — capture writes `Yad-Base: <sha>`; a person's own separators setting would hide it.
+  const listed = git(['-c', 'trailer.separators=:', 'for-each-ref', `--format=${fmt}`, ...roots]);
+  const claims = [];
+  for (const line of listed.ok ? listed.out.split('\n').filter(Boolean) : []) {
+    const [ref, tip, date, person, baseRaw = ''] = line.split('\0');
+    const rest = ref.replace(/^refs\/(remotes\/origin|heads)\//, '').slice(WIP_PREFIX.length + 1);
+    const slash = rest.indexOf('/');
+    const name = rest.slice(0, slash);
+    const epic = rest.slice(slash + 1);
+    if (slash < 1 || !/^EP-[^/]+$/.test(epic)) continue;
+    if (epics && !epics.has(epic)) continue;
+    const remote = ref.startsWith('refs/remotes/');
+    if (remote && name === me) continue;   // my own: the local branch speaks for it
+    const savedMs = Number(date) * 1000;
+    if (!Number.isFinite(savedMs) || now - savedMs > CLAIM_MS) continue;
+    const base = baseRaw.trim();
+    let against;
+    let basis = 'yad-base';
+    if (base === 'none') against = empty;
+    else if (base && git(['cat-file', '-e', `${base}^{tree}`]).ok) against = base;
+    else {
+      // Not in this clone. The commit the branch's FIRST capture was built on always is (it is an ancestor, so
+      // it was pushed with the branch): diffing against it takes in every capture since, and maybe a pull's
+      // files too — over-reporting, the safe side for advice, where the previous capture would drop earlier edits.
+      basis = 'first-capture';
+      // One git call, however long the branch: the newest first-parent ancestor that is not a capture.
+      // `--basic-regexp` and `--no-show-signature` pin it against a person's own git config: another
+      // `grep.patternType` matches nothing (the tip comes back, and the claims vanish), and
+      // `log.showSignature` prints a signature check before the hash.
+      const first = git(['log', '--no-show-signature', '--basic-regexp', '--first-parent', '--invert-grep', '--grep=^wip(EP-[^)]*): capture$', '-n', '1', '--format=%H', tip]);
+      against = first.ok && first.out.trim() ? first.out.trim() : empty;
+    }
+    const diff = git(['diff-tree', '-r', '-z', '--name-only', '--no-renames', against, tip]);
+    if (!diff.ok) continue;
+    let files = diff.out.split('\0').filter((p) => p && p.startsWith(prefix)).map((p) => p.slice(prefix.length))
+      // A step owner file (E47) rides the assigner's capture, but assigning is not editing an artifact.
+      .filter((p) => capturedEpic(p) === epic && !isOwnerPath(p));
+    // Landed: the file's content on the default branch is the capture's — the work is merged, the claim ends.
+    if (files.length && def.ref) {
+      const differs = git(['diff-tree', '-r', '-z', '--name-only', '--no-renames', def.ref, tip]);
+      if (differs.ok) {
+        const set = new Set(differs.out.split('\0').filter((p) => p && p.startsWith(prefix)).map((p) => p.slice(prefix.length)));
+        files = files.filter((p) => set.has(p));
+      }
+    }
+    for (const p of files) {
+      claims.push({ path: p, epic, name, person: person || name, lastSavedAt: new Date(savedMs).toISOString(), mine: name === me, basis });
+    }
+  }
+  claims.sort((a, b) => a.path.localeCompare(b.path) || (a.mine - b.mine) || a.name.localeCompare(b.name));
+  return { me, claims, defaultBranch: def.name };
+}
+
+const clock = (iso) => iso.slice(11, 16);
+const ago = (iso, now) => {
+  const m = Math.max(0, Math.round((now - Date.parse(iso)) / 60000));
+  return m < 60 ? `${m} min ago` : `${Math.floor(m / 60)} h ${m % 60} min ago`;
+};
+export const claimLine = (c, now) => `${c.path} — ${c.person}${c.mine ? ' (you)' : ''}, last saved ${clock(c.lastSavedAt)} UTC (${ago(c.lastSavedAt, now)})`;
+
+// The capture hook's check (cli/capture.mjs): of the files this capture changed, which does someone ELSE
+// also have open? Reads only what is already fetched. Repeats are held back per person and file for an hour
+// (kept in the capture's per-clone state file), or an agent would hear the same line on every edit.
+export const WARN_AGAIN_MS = 60 * 60 * 1000;
+export function claimWarnings(root, changed, { env = process.env, now = Date.now(), statePath = null } = {}) {
+  if (!changed.length) return [];
+  const epics = new Set(changed.map((p) => capturedEpic(p)).filter(Boolean));
+  const mine = new Set(changed);
+  const hits = readClaims(root, { env, now, epics }).claims.filter((c) => !c.mine && mine.has(c.path));
+  if (!hits.length || !statePath) return hits;
+  let state;
+  try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); } catch (e) { if (e.code !== 'ENOENT') return hits; state = {}; }
+  if (!state || typeof state !== 'object' || Array.isArray(state)) return hits;   // not ours to overwrite
+  const warned = state.claimsWarned && typeof state.claimsWarned === 'object' ? state.claimsWarned : {};
+  const fresh = hits.filter((c) => !(now - (Number(warned[`${c.name}\0${c.path}`]) || 0) < WARN_AGAIN_MS));
+  const kept = Object.fromEntries(Object.entries(warned).filter(([, t]) => now - Number(t) < CLAIM_MS));
+  for (const c of fresh) kept[`${c.name}\0${c.path}`] = now;
+  try { writeJSON(statePath, { ...state, claimsWarned: kept }); } catch { /* a cache */ }
+  return fresh;
+}
+export const warningText = (hits, now) => `yad claims: ${hits.length === 1 ? 'this file is' : 'these files are'} also being edited by someone else — advice, not a lock; talk to them before you go further:\n${hits.map((c) => `  • ${claimLine(c, now)}`).join('\n')}`;
+
+// `yad claims [<epic>] [--no-fetch]`. Returns a plain object (E1 makes it the `--json` answer).
+export async function runClaims(root, { epic = null, noFetch = false, env = process.env, now = Date.now() } = {}) {
+  const refuse = (msg, hint) => { fail(msg); if (hint) hand(hint); process.exitCode = 1; };
+  const git = gitIn(root, env);
+  if (!git(['rev-parse', '--show-toplevel']).ok) return refuse('not a git repository — there are no capture branches to read');
+  if (!fs.existsSync(productConfigPath(root))) return refuse('not a Product (no .sdlc/hub.json or product.json here)', 'run it from the Product root, or pass --dir');
+  if (epic && !/^EP-[a-z0-9-]+$/.test(epic)) return refuse(`not an epic id: ${epic}`);
+  let fetched = 'skipped';
+  if (!noFetch) {
+    if (!git(['remote', 'get-url', 'origin']).ok) fetched = 'local';
+    else {
+      const opts = { cwd: root, encoding: 'utf8', timeout: 30_000, env: { ...env, ...pushEnv(env) } };
+      const r = spawnSync('git', fetchAllArgs({ prune: true }), opts);
+      fetched = r.status === 0 ? 'done' : 'failed';
+      // The default branch, for the "landed" rule — on its own: a name guessed wrong (no hub default, no
+      // origin/HEAD) must not stop the capture branches from arriving. Its failure changes nothing.
+      const def = defaultRef(root, git).name;
+      if (fetched === 'done') spawnSync('git', ['-c', 'http.lowSpeedLimit=1000', '-c', 'http.lowSpeedTime=20', 'fetch', '--quiet', '--no-tags', 'origin', `+refs/heads/${def}:refs/remotes/origin/${def}`], opts);
+    }
+  }
+  if (fetched === 'local') info('no remote named origin — only your own captures can be read here');
+  if (fetched === 'failed') warn('could not fetch the capture branches — showing what was last fetched, which may be old');
+  const { claims, defaultBranch } = readClaims(root, { env, now, epics: epic ? new Set([epic]) : null });
+  if (!claims.length) ok(`no open claims${epic ? ` on ${epic}` : ''} — nobody's capture branch has an unmerged change saved in the last ${CLAIM_HOURS} hours`);
+  for (const c of claims) info(claimLine(c, now));
+  if (claims.length) info(`advice, not a lock — a claim ends ${CLAIM_HOURS} hours after the last save, or once the file on ${defaultBranch} matches it`);
+  return { fetched, expireHours: CLAIM_HOURS, defaultBranch, claims };
+}

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 };
+}