yadflow 3.16.0 → 3.16.2

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [3.16.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.16.1...v3.16.2) (2026-08-12)
+
+
+### Bug Fixes
+
+* **checkpoint:** make a --retro-ship dry run honest and side-effect free ([b03704f](https://github.com/abdelrahmannasr/yadflow/commit/b03704fb0564b1510dca121a24853758431f9374)), closes [112/#142](https://github.com/abdelrahmannasr/yadflow/issues/142) [#167](https://github.com/abdelrahmannasr/yadflow/issues/167)
+* **checkpoint:** name the shard path and the fold step after --retro-ship ([64c33b3](https://github.com/abdelrahmannasr/yadflow/commit/64c33b37171ee1cebf540b7a66c35ee56cdc61a7)), closes [#167](https://github.com/abdelrahmannasr/yadflow/issues/167) [#167](https://github.com/abdelrahmannasr/yadflow/issues/167)
+* **skills:** read build-log as the folded + shard union ([4302de2](https://github.com/abdelrahmannasr/yadflow/commit/4302de2e5f569989e8fc51c0a165aaae5abe1625)), closes [#167](https://github.com/abdelrahmannasr/yadflow/issues/167)
+
+## [3.16.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.16.0...v3.16.1) (2026-08-12)
+
+
+### Bug Fixes
+
+* **checkpoint:** guard --retro-ship per repo so a multi-repo story can be fully recorded ([d6d2fae](https://github.com/abdelrahmannasr/yadflow/commit/d6d2faeea91c0d59a00a532c0605f76c5b77eace)), closes [#166](https://github.com/abdelrahmannasr/yadflow/issues/166)
+* **checkpoint:** validate the retro-ship repo instead of relying on the duplicate guard ([f1e085e](https://github.com/abdelrahmannasr/yadflow/commit/f1e085e89e4eb10fbf853647ab10c1912237daf8)), closes [#166](https://github.com/abdelrahmannasr/yadflow/issues/166) [#166](https://github.com/abdelrahmannasr/yadflow/issues/166) [#166](https://github.com/abdelrahmannasr/yadflow/issues/166)
+* **ledger:** hold an exclusive lock across a ledger read-modify-write ([45b849a](https://github.com/abdelrahmannasr/yadflow/commit/45b849a7755a5bc58bc646e627218170a54b31bc)), closes [#166](https://github.com/abdelrahmannasr/yadflow/issues/166)
+
 # [3.16.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.5...v3.16.0) (2026-08-12)
 
 

package/bin/yad.mjs

@@ -115,7 +115,8 @@ ${c.bold('Build helpers')}
   yad checkpoint --retro-ship <epic>/<story> --repo <r>
                                        Record a retroactive build-log ship for a PRE-TRACKING story
                                        (merged before ledger tracking), then carry its status: shipped
-                                       flip in the same commit (--merge-commit <sha>, --task <t> opt.)
+                                       flip in the same commit (--merge-commit <sha>, --task <t> opt.);
+                                       one repo per run — re-run per --repo for a multi-repo story
   yad tidy up [<epic>] [--push]        Fold FINISHED back-half shards (a shipped story's
                                        trust-log/build-log entries) back into the single folded
                                        ledger, as one chore(hub) commit — the manual "pack it up"

package/cli/checkpoint.mjs

@@ -22,7 +22,7 @@
 //      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, pushWithRebase } from './lib.mjs';
+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';
@@ -171,7 +171,27 @@ export function stagedStoryIsStatusOnly(git, file) {
 // (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.
-export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, today }) {
+//
+// 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
+// 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);
+  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);
+  return { names, source: names.length ? 'registry' : 'none' };
+}
+
+export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, today, dryRun = false }) {
   if (!epic || !story) { fail('--retro-ship needs <epic>/<story> (e.g. --retro-ship EP-foo/EP-foo-S01)'); return { ok: false }; }
   if (!repo) { fail('--retro-ship needs --repo <name> (the repo the story shipped in)'); return { ok: false }; }
   const epicDir = path.join(root, 'epics', epic);
@@ -183,20 +203,78 @@ export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, to
   // 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
   // shard would commit while the artifact still says e.g. `approved` — the very drift #112 prevents.
-  if (!BACK_HALF_STATUSES.has(readFrontmatter(storyFile).status)) {
+  const storyStatus = readFrontmatter(storyFile).status;
+  if (!BACK_HALF_STATUSES.has(storyStatus)) {
     fail(`${story} frontmatter is not at in-build|shipped`);
-    hand(`set \`status: shipped\` in ${storyRel} first, then re-run — the ship and the flip land in one commit`);
+    hand(`set \`status: in-build\` or \`status: shipped\` in ${storyRel} first, then re-run — the ship and the flip land in one commit`);
     return { ok: false };
   }
 
+  // A ship is permanent audit evidence, so the repo it names must be one the story could have shipped
+  // in — an unrecognized `--repo` is a typo, not a discovery. Skipped only when nothing declares any
+  // 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`);
+    hand(`known: ${names.join(', ')} (names are case-sensitive)`);
+    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
+  // 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);
+  };
+  const left = remaining();
+
   let res;
   try { res = writeRetroShip(epicDir, { story, repo, task, mergeCommit, shippedAt: today }); }
   catch (e) { fail(`could not record retroactive ship — ${e.message}`); return { ok: false }; }
   if (!res.written) {
-    fail(`${story} already has a build-log ship — it is not pre-tracking; use the normal ship/checkpoint flow`);
+    if (res.reason === 'collision') {
+      // Distinct names, ONE shard file (`buildShardName` sanitizes each component) — recording this one
+      // would overwrite the other repo's ship record, so it is refused rather than silently clobbered.
+      // `writeRetroShip` reports a clash EITHER as `repo` (a ship readShips can see) OR as `file` (a shard
+      // on disk it cannot parse) — and a malformed shard can carry a blank `repo`, satisfying neither. Name
+      // whichever it gave us; never index into the one it did not, or the refusal becomes a stack trace.
+      const clashedWith = res.repo ? `the already-recorded ${res.repo}`
+        : res.file ? `an existing shard (${path.basename(res.file)})` : 'an existing ship record';
+      fail(`${repo} cannot be recorded: it shares a build-log shard name with ${clashedWith}`);
+      hand('recording it would overwrite that ship record — rename one of the repos in the registry, or record this ship through the normal ship/checkpoint flow');
+      return { ok: false };
+    }
+    // Per REPO, not per story (#166) — so the message names the repo. The follow-up hint names the
+    // story's OWN still-unrecorded repos; with none left there is nothing to re-run, and inventing a
+    // `--repo <other>` at that point would fabricate a ship for a repo the story never shipped in.
+    fail(`${story} already has a build-log ship in ${repo} — it is not pre-tracking there; use the normal ship/checkpoint flow`);
+    if (left.length) hand(`still unrecorded for ${story}: ${left.join(', ')} — re-run with \`--repo <name>\` for each`);
     return { ok: false };
   }
-  ok(`recorded retroactive ship for ${story} (${repo})${mergeCommit ? ` @ ${mergeCommit}` : ''}`);
+  // A dry run WROTE this shard only so the flip could be previewed; it is rolled back before the command
+  // returns. Every line below must therefore speak in the conditional — a past-tense "recorded" would tell
+  // the operator the backfill landed, they would never re-run for real, and the story would keep
+  // `status: shipped` with no ship behind it: exactly the #112/#142 drift this command exists to remove.
+  ok(`${dryRun ? 'would record' : 'recorded'} retroactive ship for ${story} (${repo})${mergeCommit ? ` @ ${mergeCommit}` : ''}`);
+  // Name WHERE the record landed. The ledger is shard-then-fold, so this ship is one loose shard and the
+  // folded `build-log.json` is untouched until `yad tidy up` runs — an operator who opens build-log.json,
+  // finds nothing, and concludes the write was lost is reading half the ledger (#167). Every reader unions
+  // the two; say so here, while they are looking. `tidy up` only folds a story whose frontmatter is
+  // `shipped`, so an `in-build` story's shard stays loose (and still readable) by design — mention the
+  // `shipped` precondition only when it is actually still outstanding.
+  const rel = path.relative(root, res.file).split(path.sep).join('/');
+  info(`${dryRun ? 'would land at' : 'landed at'} ${rel}`);
+  info(`readers union build-log/ shards with the folded build-log.json; \`yad tidy up\` folds it in${storyStatus === 'shipped' ? '' : ` once ${story} is \`shipped\``}`);
+  // A multi-repo story is only half-reconciled until every declared repo has evidence, and nothing
+  // downstream reports the gap (the story already reads `shipped`) — so say it here, while the
+  // operator is running the backfill. `left` excludes the repo just recorded; in a dry run that record is
+  // rolled back, so it is still unrecorded and belongs back in the list.
+  const stillLeft = dryRun && left.length ? [repo, ...left] : left;
+  if (stillLeft.length) hand(`${story} declares ${names.length} repos — still unrecorded: ${stillLeft.join(', ')}; re-run with \`--repo <name>\` for each`);
   return { ok: true, file: res.file };
 }
 
@@ -231,22 +309,30 @@ export async function runCheckpoint(root, opts = {}) {
   // already wrote is then carried by the normal storyStatusPathspecs path below — no raw git needed.
   let retroFile;
   if (opts.retroShip) {
-    const r = recordRetroShip(root, opts.retroShip);
+    const r = recordRetroShip(root, { ...opts.retroShip, dryRun: opts.dryRun });
     if (!r.ok) { process.exitCode = 1; return; }
     retroFile = r.file;
   }
 
+  // A --retro-ship DRY RUN wrote a real shard so the flip could be previewed, and it must be undone on
+  // EVERY exit path below, not just the happy one. An early return that skipped the rollback (git add
+  // failed, nothing staged) would leave an untracked retro shard behind — which then refuses the
+  // operator's next REAL backfill ("already has a build-log ship in <repo>") and rides into the next
+  // 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 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) { info('no back-half ledgers found — nothing to checkpoint'); return; }
+  if (!pathspecs.length) { rollbackRetro(); info('no back-half ledgers found — nothing to checkpoint'); return; }
 
   // 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
   // top-level ledger is intentionally NOT staged (its spec drops out on the existence check) — an
   // append-only audit ledger vanishing is an anomaly a human should see, not something to auto-commit.
   const add = git('add', '--', ...pathspecs);
-  if (!add.ok) { fail(`git add failed — ${add.stderr.split('\n')[0] || add.code}`); process.exitCode = 1; return; }
+  if (!add.ok) { rollbackRetro(); fail(`git add failed — ${add.stderr.split('\n')[0] || add.code}`); process.exitCode = 1; return; }
 
   // #112 review-bypass guard: a story is only carried when its staged change is the `status:` line
   // ALONE. Unstage any candidate whose working tree also touched prose/other frontmatter — those
@@ -261,6 +347,7 @@ export async function runCheckpoint(root, opts = {}) {
   }
 
   if (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
+    rollbackRetro();
     info('back-half state unchanged — nothing to commit');
     return;
   }
@@ -279,7 +366,7 @@ export async function runCheckpoint(root, opts = {}) {
     git('reset', '-q', '--', ...pathspecs); // restore the index — a dry run must not leave things staged
     // A --retro-ship dry run wrote a shard so the flip could be PREVIEWED above; undo it now so the dry
     // run leaves no side effect on disk (git reset only unstaged it, back to untracked).
-    if (retroFile) cleanupRetroShard(retroFile);
+    rollbackRetro();
     info('dry run — not committed');
     return { message };
   }

package/cli/errors.mjs

@@ -21,6 +21,7 @@ export const CODES = {
   'YAD-STATE-003': 'a registered repo path is missing or not a git repository',
   'YAD-STATE-004': 'an epic step cannot be skipped / un-skipped in its current state',
   'YAD-STATE-005': 'an authoring step is stranded behind its completed review gate',
+  'YAD-STATE-006': 'a back-half ledger is locked by another yad process that is writing it',
   'YAD-CFG-001': 'hub.json names an unknown platform (expected github, gitlab, or null)',
   'YAD-CFG-002': 'design.json names an unknown design tool (expected one of config.yaml design.tools, or none)',
   'YAD-CFG-003': 'testing.json names an unknown testing tool (expected one of config.yaml testing.tools, or none)',

package/cli/ledger.mjs

@@ -9,10 +9,69 @@
 //
 // A legacy epic that only has the folded file still reads correctly (no shards to union) → zero
 // migration; new writes simply go to shards.
+//
+// Shards remove the conflict BETWEEN entries; they do not make a single read-modify-write atomic, so
+// every writer that decides something from the ledger before writing takes an exclusive lock first
+// (see "ledger locking" below).
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJSON, readJSONStrict, writeJSON } from './lib.mjs';
 import { epicFiles } from './manifest.mjs';
+import { err } from './errors.mjs';
+
+// ---- ledger locking -------------------------------------------------------------------------------
+// Shards make concurrent writers conflict-free ACROSS entries, but a writer that READS THEN WRITES is
+// only safe if nothing slips in between. `writeRetroShip` decides "no ship for this (story, repo) yet"
+// and then writes; `updateShip` finds a ship and then rewrites it; a fold reads shards, merges them,
+// then deletes them. Two `--retro-ship` runs with different `--task` values both read "no ship", both
+// write, and the duplicate guard is defeated — two shards for one (story, repo). So every
+// read-modify-write on a ledger holds an exclusive lock for its whole span.
+//
+// `fs.mkdirSync` is the primitive: directory creation is atomic on POSIX and Windows, so exactly one
+// caller wins and the rest get EEXIST. It needs no fd bookkeeping, releases with one `rmdir`, and an
+// EMPTY DIRECTORY IS INVISIBLE TO GIT — a lock can never be committed, and `readShardDir` only reads
+// `*.json` files, so it is never mistaken for an entry either.
+//
+// The lock is per LEDGER, not per (story, repo). A per-identity lock keyed on the raw identity would
+// let the one pair that most needs serializing race: `api.v2` and `api_v2` are DIFFERENT identities
+// that share ONE shard filename (`safe()` maps both to `api_v2`), so they would take different locks
+// and then collide on the same file. A ledger-wide lock cannot be wrong that way, and what it
+// serializes is a handful of local file operations.
+const LOCK_STALE_MS = 30_000;   // a lock older than this belonged to a process that died holding it
+const LOCK_WAIT_MS = 50;
+const LOCK_RETRIES = 100;       // ≈5s — long enough for any real ledger write, short enough to report
+
+// Block the thread without spinning. `Atomics.wait` on the main thread is allowed in Node (only
+// browsers forbid it), and these ledger writers are synchronous by design.
+const sleep = (ms) => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+
+// Run `fn` while holding `lockPath` exclusively; always releases, even when `fn` throws. Throws
+// YAD-STATE-006 when the lock is held by a live process for the whole retry window — better to report
+// than to write over another writer's work.
+export function withLedgerLock(lockPath, fn, { retries = LOCK_RETRIES, waitMs = LOCK_WAIT_MS } = {}) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  for (let i = 0; ; i++) {
+    try {
+      fs.mkdirSync(lockPath);
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // A holder that died leaves its lock behind forever; reclaim one that is provably too old.
+      let age;
+      try { age = Date.now() - fs.statSync(lockPath).mtimeMs; } catch { continue; } // vanished → retry
+      if (age > LOCK_STALE_MS) { try { fs.rmdirSync(lockPath); } catch { /* someone else won */ } continue; }
+      if (i >= retries) {
+        throw err('YAD-STATE-006', `another process is writing ${path.basename(lockPath, '.lock')} in ${path.basename(path.dirname(path.dirname(lockPath)))}`,
+          'wait for the other yad command to finish and re-run; if nothing else is running, delete the stale .lock directory the message names');
+      }
+      sleep(waitMs);
+    }
+  }
+  try { return fn(); } finally { try { fs.rmdirSync(lockPath); } catch { /* already reclaimed */ } }
+}
+
+const buildLogLock = (epicDir) => `${epicFiles(epicDir).buildLog}.lock`;
+const trustLogLock = (epicDir) => `${epicFiles(epicDir).trustLog}.lock`;
 
 // ---- shard filenames — the ONE source of truth for the naming convention -------------------------
 // story ids already contain hyphens; the filename is just a unique handle (the entry inside carries
@@ -86,46 +145,68 @@ export function readShips(epicDir) {
 // ship: `task` defaults to the sentinel `retro`, `mergeCommit` is written only when the caller supplies
 // it (never invented), and `shippedAt` is the backfill date (the `retroactive` flag marks it as such).
 //
-// Guard: refuse when the story ALREADY has ANY build-log ship — then it isn't pre-tracking and the
-// normal ship/checkpoint flow applies; a retro record would only muddy the ledger. Returns
-// { written: false, reason } in that case, else { written: true, file, ship }.
-export function writeRetroShip(epicDir, { story, repo, task = 'retro', mergeCommit, shippedAt }) {
+// Guard: refuse when the story already has a build-log ship IN THIS REPO — then it isn't pre-tracking
+// there and the normal ship/checkpoint flow applies; a retro record would only muddy the ledger. The
+// key is (story, repo), NOT story alone (#166): a story tagged with several repos ships once per repo,
+// so a story-only guard let the FIRST backfill lock out every other repo and a multi-repo pre-tracking
+// story could never be fully recorded. Each repo is recorded by its own run — the shards are distinct
+// by construction (`buildShardName` keys on story+task+repo). Not keyed on `task` too: that would let
+// repeated `--task T0x` pile several retro shards into one repo, the very muddying this guard prevents.
+//
+// Two names can differ yet share ONE shard file: `buildShardName` sanitizes each component through
+// `safe()`, so `api.v2` and `api_v2` both become `api_v2` while the (story, repo) key sees them as
+// distinct. Writing the second would silently overwrite the first repo's ship — destroying evidence in
+// an append-only ledger, and (via the --dry-run cleanup) deleting an already-committed shard. So a
+// name that COLLIDES with an existing ship's shard name is refused as `reason: 'collision'`, and the
+// target file is never overwritten even when `readShips` cannot see it (a corrupt shard is skipped by
+// `readShardDir`). Returns { written: false, reason } when refused, else { written: true, file, ship }.
+export function writeRetroShip(epicDir, { story, repo, task = 'retro', mergeCommit, shippedAt }, lockOpts = {}) {
   if (!story) throw new Error('writeRetroShip: story is required');
   if (!repo) throw new Error('writeRetroShip: repo is required');
-  if (readShips(epicDir).some((s) => s.story === story)) {
-    return { written: false, reason: 'exists' };
-  }
-  const t = task || 'retro';
-  const ship = { story, task: t, repo, retroactive: true, note: 'pre-tracking backfill' };
-  if (mergeCommit) ship.mergeCommit = mergeCommit;
-  if (shippedAt) ship.shippedAt = shippedAt;
-  const f = epicFiles(epicDir);
-  const file = path.join(f.buildLogDir, buildShardName({ story, task: t, repo }));
-  writeJSON(file, ship);
-  return { written: true, file, ship };
+  // Both guards and the write are ONE critical section: read outside the lock and a concurrent run
+  // (notably a different `--task` for the same (story, repo)) can write between the check and ours.
+  return withLedgerLock(buildLogLock(epicDir), () => {
+    const ships = readShips(epicDir).filter((s) => s.story === story);
+    if (ships.some((s) => s.repo === repo)) return { written: false, reason: 'exists' };
+    const clash = ships.find((s) => safe(s.repo) === safe(repo));
+    if (clash) return { written: false, reason: 'collision', repo: clash.repo };
+    const t = task || 'retro';
+    const ship = { story, task: t, repo, retroactive: true, note: 'pre-tracking backfill' };
+    if (mergeCommit) ship.mergeCommit = mergeCommit;
+    if (shippedAt) ship.shippedAt = shippedAt;
+    const f = epicFiles(epicDir);
+    const file = path.join(f.buildLogDir, buildShardName({ story, task: t, repo }));
+    if (fs.existsSync(file)) return { written: false, reason: 'collision', file };
+    writeJSON(file, ship);
+    return { written: true, file, ship };
+  }, lockOpts);
 }
 
 // Find the ship matching `match(ship)` across loose shards (authoritative until folded) then the
 // folded file, apply `update(ship)`, and write back ONLY the file that holds it. Returns
-// { found, where, file, ship }; found:false writes nothing (the caller warns).
-export function updateShip(epicDir, match, update) {
-  const f = epicFiles(epicDir);
-  for (const { name, obj } of readShardDir(f.buildLogDir)) {
-    if (match(obj)) {
-      update(obj);
-      const file = path.join(f.buildLogDir, name);
-      writeJSON(file, obj);
-      return { found: true, where: 'shard', file, ship: obj };
+// { found, where, file, ship }; found:false writes nothing (the caller warns). The find and the
+// write-back are one locked span: a fold running between them would move the ship into the folded
+// file and delete the shard this call is about to rewrite, resurrecting the deleted shard.
+export function updateShip(epicDir, match, update, lockOpts = {}) {
+  return withLedgerLock(buildLogLock(epicDir), () => {
+    const f = epicFiles(epicDir);
+    for (const { name, obj } of readShardDir(f.buildLogDir)) {
+      if (match(obj)) {
+        update(obj);
+        const file = path.join(f.buildLogDir, name);
+        writeJSON(file, obj);
+        return { found: true, where: 'shard', file, ship: obj };
+      }
     }
-  }
-  const foldedObj = readJSONStrict(f.buildLog, null);
-  const ship = Array.isArray(foldedObj?.ships) ? foldedObj.ships.find(match) : null;
-  if (ship) {
-    update(ship);
-    writeJSON(f.buildLog, foldedObj);
-    return { found: true, where: 'folded', file: f.buildLog, ship };
-  }
-  return { found: false };
+    const foldedObj = readJSONStrict(f.buildLog, null);
+    const ship = Array.isArray(foldedObj?.ships) ? foldedObj.ships.find(match) : null;
+    if (ship) {
+      update(ship);
+      writeJSON(f.buildLog, foldedObj);
+      return { found: true, where: 'folded', file: f.buildLog, ship };
+    }
+    return { found: false };
+  }, lockOpts);
 }
 
 // ---- folding (used by `yad tidy up`) -------------------------------------------------------------
@@ -170,11 +251,16 @@ function fold(epicDir, { foldedPath, dir, arr, isTrust }, pick, { dryRun = false
   return { folded: toFold.length, remaining: shards.length - toFold.length, deleted };
 }
 
+// Both folds are read-fold-delete, so they hold their ledger's lock for the whole span — otherwise a
+// ship written (or stamped by `updateShip`) after the read but before the delete is folded away
+// without its change, or deleted without ever being folded.
 export function foldTrust(epicDir, pick, opts = {}) {
   const f = epicFiles(epicDir);
-  return fold(epicDir, { foldedPath: f.trustLog, dir: f.trustLogDir, arr: 'runs', isTrust: true }, pick, opts);
+  return withLedgerLock(trustLogLock(epicDir), () =>
+    fold(epicDir, { foldedPath: f.trustLog, dir: f.trustLogDir, arr: 'runs', isTrust: true }, pick, opts), opts);
 }
 export function foldBuild(epicDir, pick, opts = {}) {
   const f = epicFiles(epicDir);
-  return fold(epicDir, { foldedPath: f.buildLog, dir: f.buildLogDir, arr: 'ships', isTrust: false }, pick, opts);
+  return withLedgerLock(buildLogLock(epicDir), () =>
+    fold(epicDir, { foldedPath: f.buildLog, dir: f.buildLogDir, arr: 'ships', isTrust: false }, pick, opts), opts);
 }

package/cli/usage.mjs

@@ -243,11 +243,17 @@ function memberFlags(m) {
 
 // Team-level hygiene, keyed by epic/story — a ship with no recorded engineer review is a process gap,
 // not attributable to one person, so it lives here rather than in a member's flag list.
+//
+// A `retroactive: true` ship is EXCLUDED: it is a `yad checkpoint --retro-ship` reconciliation of a
+// story that shipped before the ledger existed, so it never had a tracked PR to review — counting it
+// as a missing review reports a gap the team could not have filled. It also scales with repo count
+// (one backfill shard per repo since #166), which would swamp the real gaps with reconciliation noise.
 export function shipHygiene(root, { since, until } = {}) {
   const items = [];
   for (const epic of listEpics(root)) {
     for (const s of readShips(path.join(root, 'epics', epic))) {
       if (!inWindow(s.shippedAt, since, until)) continue;
+      if (s.retroactive) continue;
       if (!Array.isArray(s.engineer_review) || s.engineer_review.length === 0) {
         items.push({ epic, story: s.story || null, task: s.task || null, repo: s.repo || null, shippedAt: s.shippedAt || null });
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.16.0",
+  "version": "3.16.2",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/config.yaml

@@ -139,7 +139,12 @@ build:
   risk_levels: [low, medium, high]   # high (or a contract/auth/payments surface) routes to domain owners (yad-review-gate escalation)
   # Step E (yad-engineer-review) — AI review (advisory) + engineer review (the human gate) + merge.
   ai_review: coderabbit            # advisory first pass; never the authority (.coderabbit.yaml)
-  build_log: "epics/EP-<slug>/.sdlc/build-log.json"   # append-only ship ledger (back-half analogue of approvals.json)
+  # Append-only ship ledger (back-half analogue of approvals.json), stored shard-then-fold: writers add one
+  # shard per ship under build_log_dir; `yad tidy up` folds a SHIPPED story's shards into build_log.
+  # READERS MUST UNION the two (dedupe by (story, task, repo); a shard wins) — build_log alone omits every
+  # unfolded ship, e.g. a `yad checkpoint --retro-ship` backfill or any ship on an `in-build` story.
+  build_log: "epics/EP-<slug>/.sdlc/build-log.json"   # folded ships
+  build_log_dir: "epics/EP-<slug>/.sdlc/build-log/"   # one <story>-<task>-<repo>.json shard per ship
   story_build_states: [in-build, shipped]   # in-build = some tasks shipped; shipped = all tasks in tasks.md shipped
   # Backfill (yad-backfill) — specs for already-built features in an existing repo.
   backfill:

package/skills/sdlc/module-help.csv

@@ -33,7 +33,7 @@ SDLC Workflow,yad-docs,Author Docs Site,DS,"Generate the per-epic interactive do
 SDLC Workflow,yad-docs-overview,Docs Overview Site,DO,"Generate the project SDLC-overview interactive site (docs/sdlc-site/) — every stage from setup to ship modeled as flow paths, system components, and stakeholder roles — reusing the same vendored shell, themed with yadflow's brand palette. Reads config.yaml + module-help.csv + the overview diagram as the pipeline source. Folds the hand-maintained docs/index.html report into the site as report.html (linked from the nav). Not a gate — a project-level enrichment that regenerates whenever the skill set / pipeline changes.",,{action: generate|deploy},,,,false,docs/sdlc-site/,sdlc-site/ .docs-build.json
 SDLC Workflow,yad-docs-sync,Docs Sync,DY,"Maintenance/CI: keep the generated doc sites fresh. Detect staleness (a content hash of the approved artifacts + the connected repos' HEAD shas + the doc-shell version vs each site's build manifest), report which sites drifted and why, regenerate + redeploy the stale ones, and wire a CI job that rebuilds on push (carrying [skip ci] + a concurrency group to prevent deploy loops). Generalizes the rule that feature work must hand-update docs/index.html + diagrams + skill counts. Refresh is always a human/CI decision; never a gate.",,{action: check|refresh|wire} {epic: EP-<slug>},,,,false,epics/EP-<slug>/.sdlc/,docs-build.json yad-docs.yml
 SDLC Workflow,yad-change,Change/Defect Intake,CH,"Phase 6 post-lock change management: the INTAKE + TRIAGE step of a feature thread. Classifies the change DEPTH (defect-fix / behavioral-no-surface / contract-surface / new-capability), seeds a NEW EP-<slug> change-epic threaded to its parent (lineage frontmatter kind/parent/thread/inherits/supersedes + a state.json whose inherited steps are pre-marked done and only the changed steps run; a pointer-lock contract-lock.json when architecture is inherited), and records the intake in change.json (escape_stage + root_cause for defects). For hotfixes it records the ship-first exception and opens reconcile-debt.json. Never auto-advances — hands off to the normal authoring skills + yad-review-gate.",,{parent: EP-<slug>} {title: one-line} {kind: change|defect|hotfix} {origin: production|staging|qa|review} {severity: sev1..sev4} {description: text} {affected: artifacts},1-front,,yad-review-gate,false,epics/EP-<slug>/,epic.md state.json change.json reconcile-debt.json contract-lock.json
-SDLC Workflow,yad-timeline,Feature Timeline,TL,"Render a feature THREAD (its linked epics, genesis->changes->defects) as an evolution view (the vendored React/Vite/Tailwind shell HTML + a TIMELINE.md summary) AND resolve the inheritance chain into the authoritative current artifact set (thread-resolved.md: the winning source per artifact + the resolved contract-lock hash) — the composed source-of-truth AI/humans read for the next change. Reads frontmatter lineage + each change.json + build-log.json. An OUTPUT ENRICHMENT — never a gate; never mutates state.",,{thread: EP-<genesis>} {action: generate|deploy},,,,false,epics/EP-<genesis>/,timeline-site/ thread-resolved.md TIMELINE.md
-SDLC Workflow,yad-defects,Quality-Gap Report,DF,"Generate a per-epic AND per-thread defect/bug report (same vendored shell + DEFECTS.md). Walks the thread for every kind:defect change-epic + each change.json defect block + shipped regressions in build-log.json, aggregates by escape_stage (the SDLC gate that should have caught it) and root_cause, and visualizes WHERE quality gaps systematically come from (e.g. % of thread defects that escaped at the test-cases gate) so the team can harden the originating stage. An OUTPUT ENRICHMENT — never a gate; never mutates state.",,{epic: EP-<slug> | thread: EP-<genesis>} {action: generate|deploy},,,,false,epics/EP-<slug>/,defects-site/ DEFECTS.md
+SDLC Workflow,yad-timeline,Feature Timeline,TL,"Render a feature THREAD (its linked epics, genesis->changes->defects) as an evolution view (the vendored React/Vite/Tailwind shell HTML + a TIMELINE.md summary) AND resolve the inheritance chain into the authoritative current artifact set (thread-resolved.md: the winning source per artifact + the resolved contract-lock hash) — the composed source-of-truth AI/humans read for the next change. Reads frontmatter lineage + each change.json + the build ledger (folded build-log.json UNIONed with every build-log/ shard). An OUTPUT ENRICHMENT — never a gate; never mutates state.",,{thread: EP-<genesis>} {action: generate|deploy},,,,false,epics/EP-<genesis>/,timeline-site/ thread-resolved.md TIMELINE.md
+SDLC Workflow,yad-defects,Quality-Gap Report,DF,"Generate a per-epic AND per-thread defect/bug report (same vendored shell + DEFECTS.md). Walks the thread for every kind:defect change-epic + each change.json defect block + shipped regressions in the build ledger (folded build-log.json UNIONed with every build-log/ shard), aggregates by escape_stage (the SDLC gate that should have caught it) and root_cause, and visualizes WHERE quality gaps systematically come from (e.g. % of thread defects that escaped at the test-cases gate) so the team can harden the originating stage. An OUTPUT ENRICHMENT — never a gate; never mutates state.",,{epic: EP-<slug> | thread: EP-<genesis>} {action: generate|deploy},,,,false,epics/EP-<slug>/,defects-site/ DEFECTS.md
 SDLC Workflow,yad-reconcile,Change Reconciler,RE,"Maintenance/CI (mirrors yad-docs-sync — never a gate): detect post-lock DRIFT/ORPHANS — shipped code or a repo HEAD advance (the repos.json syncedHead-vs-current-HEAD rule) with NO owning change-epic in any thread — plus open hotfix reconcile debt, and report which thread drifted and why. refresh points at yad-change to open a reconcile change-epic (or yad-stub first, to anchor orphan brownfield code that has no epic at all) — never silent; wire commits advisory CI ([skip ci] + concurrency, like yad-docs-sync). The actual merge BLOCK is the lineage-check / reconcile-debt gates; this only discovers.",,{action: check|refresh|wire} {thread: EP-<genesis>},,,,false,epics/EP-<genesis>/.sdlc/,(report) reconcile-debt.json yad-reconcile.yml
 SDLC Workflow,yad-stub,Stub Genesis Epic,SG,"Phase 6 brownfield helper: mint a STUB genesis epic for an already-built feature that has no epic in the hub, so a defect/change can thread off it TODAY (yad-change requires a real parent and dead-ends without one). Creates the smallest real thread anchor — a tiny epic.md (kind:feature, thread:self, verified:false, stub:backfill-pending) + a seeded state.json (kind:stub / currentStep:backfill-pending) + empty ledgers — never inventing behaviour. Defects thread off it immediately (gates pass; the bug list is derived by the thread rollup); yad-backfill + its promote step later flip it into a real feature epic. Never auto-advances.",,{feature: <name>} {repos: [<repo>]} {description: one-line},1-front,,yad-change,false,epics/EP-<slug>/,epic.md state.json approvals.json comments.json

package/skills/yad-defects/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-defects
-description: 'Phase 6 output enrichment (never a gate) — the quality-gap report. Generates a per-epic AND per-thread defect/bug report (the vendored React/Vite/Tailwind shell HTML + a DEFECTS.md) that aggregates every kind:defect change-epic + each change.json defect block + shipped regressions in build-log.json BY escape_stage (the SDLC gate that should have caught the defect) and root_cause, and visualizes WHERE quality gaps systematically come from — e.g. "% of this feature''s defects that escaped at the test-cases gate" — so the team hardens the originating stage instead of just fixing symptoms. Degrades to markdown-only when no docs target is connected. Use when the user says "show the defect report", "where are our quality gaps", "generate the bug report for this epic", or "which gate is leaking defects".'
+description: 'Phase 6 output enrichment (never a gate) — the quality-gap report. Generates a per-epic AND per-thread defect/bug report (the vendored React/Vite/Tailwind shell HTML + a DEFECTS.md) that aggregates every kind:defect change-epic + each change.json defect block + shipped regressions in the build ledger (the folded build-log.json unioned with every build-log/ shard) BY escape_stage (the SDLC gate that should have caught the defect) and root_cause, and visualizes WHERE quality gaps systematically come from — e.g. "% of this feature''s defects that escaped at the test-cases gate" — so the team hardens the originating stage instead of just fixing symptoms. Degrades to markdown-only when no docs target is connected. Use when the user says "show the defect report", "where are our quality gaps", "generate the bug report for this epic", or "which gate is leaking defects".'
 ---
 
 # SDLC — Quality-Gap Report (Phase 6, output enrichment)
@@ -32,10 +32,16 @@ risk), not just the symptom. It is an **output enrichment**, exactly like `yad-d
 Resolve the scope (`yad thread <id> --json` for a thread). Collect, across the scoped epic(s):
 - every `kind: defect` (and `kind: hotfix`) change-epic + its `.sdlc/change.json` `defect` block
   (`origin`, `severity`, `escape_stage`, `root_cause`);
-- the shipped regression fixes from each `.sdlc/build-log.json` (the fix that closed the defect, linking
+- the shipped regression fixes from each epic's build ledger (the fix that closed the defect, linking
   the change-epic → its regression story/test);
 - open reconcile debt (a hotfix whose front truth is not yet restored).
 
+The build ledger is **shard-then-fold**: read it as the **union** of the folded `.sdlc/build-log.json`
+`ships` PLUS every loose `.sdlc/build-log/` shard, deduped by `(story, task, repo)` — a shard WINS over a
+folded ship of the same key. Reading `build-log.json` alone drops every ship not yet folded by
+`yad tidy up` (including every `yad checkpoint --retro-ship` backfill, and every ship on a story still at
+`in-build`, which `tidy up` never folds), which would under-count the very fixes this report attributes.
+
 ### Step 2 — Attribute each defect to the gate that should have caught it
 A defect is attributed to its **earliest** responsible SDLC stage. Use `change.json.escape_stage`
 (human-set at intake), cross-checked against the fix's shape: a missing negative test → `test-cases`; a
@@ -73,7 +79,9 @@ Also write a plain `epics/<scope>/DEFECTS.md` mirror. On `action: deploy`, `yad
 - **Degrade gracefully.** No docs target → `DEFECTS.md` only; never fail because a tool is absent.
 
 ## Reference
-- The defect data: `.sdlc/change.json` `defect` blocks + `build-log.json` (`../yad-epic/references/state-schema.md`, Phase 6).
+- The defect data: `.sdlc/change.json` `defect` blocks + the build ledger, read as the folded
+  `build-log.json` unioned with every `.sdlc/build-log/` shard
+  (`../yad-epic/references/state-schema.md`, Phase 6; `../yad-engineer-review/references/ship-and-record.md`).
 - The shell + deterministic generation it reuses: `../yad-docs/SKILL.md`, `../yad-docs/references/data-mapping.md`.
 - The companion evolution view: `../yad-timeline/SKILL.md`.
 - The intake that records `escape_stage` + `root_cause`: `../yad-change/SKILL.md`.

package/skills/yad-docs-overview/references/pipeline-model.md

@@ -69,7 +69,7 @@ Per-story, per-repo: `spec → tasks → implement → checks → engineer-revie
 | `yad-checks` | `checks/*.sh`, CI workflows — the gate set: `spec-link · contract-check · build-test-lint · verified-commits · commit-message · pr-title · pr-template · lineage-check · epic-open · reconcile-debt`, plus `yad-update-guard` (push-on-default: re-checks any direct-to-default commit with `verified-commits · commit-message`) |
 | `yad-pr-template` | PR/MR template + routing helpers |
 | `yad-commit` / `yad-open-pr` / `yad-ship` | one commit / one PR/MR |
-| `yad-engineer-review` | engineer review + ship recorded in `build-log.json` |
+| `yad-engineer-review` | engineer review + ship recorded as a `build-log/` shard |
 | `yad-backfill` | DRAFT specs for legacy features |
 
 ### Path: Automation (the second dial + observation)
@@ -110,6 +110,11 @@ and the change-thread ledgers `change.json`, `reconcile-debt.json`, `build-log.j
 the **connected code repos**; the **design / testing / learning tools**; and the **platform**
 (GitHub/GitLab + Pages). A skill's `sideEffects` link its step to the component it writes.
 
+`trust-log.json` and `build-log.json` are the *folded* halves of two **shard-then-fold** ledgers — each
+also has a shard dir (`.sdlc/trust-log/`, `.sdlc/build-log/`) holding the entries `yad tidy up` has not
+folded yet. They render as one component each, but anything READING them must union the folded file with
+its shards (`../../yad-engineer-review/references/ship-and-record.md`).
+
 ## Roles = the lenses
 
 The eight yadflow lenses, each to its relevant phase sections + paths:

package/skills/yad-engineer-review/references/ship-and-record.md

@@ -81,10 +81,45 @@ yad checkpoint --retro-ship <epic>/<story> --repo <r> [--task <t>] [--merge-comm
 It writes ONE minimal ship shard marked `retroactive: true` (`task` defaults to the sentinel `retro`;
 `mergeCommit` is written only if you pass `--merge-commit`; `shippedAt` is the backfill date), then runs
 the normal checkpoint so the story's already-made `status:` flip rides along in the **same** commit. It
-refuses when the story already has a real ship (then it isn't pre-tracking — use the normal flow). It
-does **not** author the story frontmatter — and to keep evidence and the flip atomic (the no-drift
-invariant), it **refuses** unless you have already set `status: shipped` in `stories/<story>.md`, so a
-ship shard is never committed while the artifact still says `approved`.
+refuses when the story already has a ship **in that repo** (then it isn't pre-tracking there — use the
+normal flow). It does **not** author the story frontmatter — and to keep evidence and the flip atomic (the no-drift
+invariant), it **refuses** unless you have already set a back-half `status:` (`in-build` or `shipped`) in
+`stories/<story>.md`, so a ship shard is never committed while the artifact still says `approved`.
+
+**Where the record lands — it is a shard, not an append to `build-log.json`.** Like every other ship, a
+retroactive one is written to `.sdlc/build-log/` and the folded `build-log.json` is left untouched until
+`yad tidy up` folds it. Opening `build-log.json` and finding nothing does **not** mean the write was lost:
+read the ledger by the union rule above and the ship is there (#167). Note `tidy up` only folds a story
+whose frontmatter is `shipped`, so a backfill recorded against an `in-build` story stays a loose shard
+indefinitely — which is precisely why reading the folded file alone is never sufficient.
+
+**One repo per run (#166).** A ship is recorded per `(story, task, repo)`, so a story that shipped in
+several repos needs one retroactive shard **per repo** — the guard is keyed on `(story, repo)`, not on
+the story alone, so recording the first repo never locks out the rest. Re-run once per repo:
+
+```
+yad checkpoint --retro-ship EP-foo/EP-foo-S01 --repo web --push
+yad checkpoint --retro-ship EP-foo/EP-foo-S01 --repo api --push
+```
+
+The `status:` flip rides the **first** commit (it only needs one ship to be carried); each later run
+lands only its own ship shard, so the story ends up with complete per-repo evidence. After each run the
+command names the declared repos that still have none, so a half-finished backfill is visible instead of
+looking complete.
+
+A ship is permanent audit evidence, so `--repo` is checked before anything is written: it must be a repo
+the story's `repos:` frontmatter declares (or, for a legacy story that declares none, one connected in
+`.sdlc/repos.json`). A typo'd, mis-cased or invented name is **refused** — the per-repo guard means it
+would otherwise collide with nothing and quietly record a ship for a repo that never existed. A name
+that would share a shard **filename** with an already-recorded repo (shard names sanitize everything
+outside `[A-Za-z0-9_-]` to `_`, so `api.v2` and `api_v2` are one file) is refused for the same reason:
+recording it would overwrite the other repo's ship record in an append-only ledger.
+
+Those checks decide from the ledger and then write it, so each one runs under an exclusive **lock** on
+the epic's `build-log` — as does `yad review reconcile`'s stamp and `yad tidy up`'s fold. Two commands
+writing the same ledger at once would otherwise both read "no ship yet" and both write. The lock is an
+empty directory (`build-log.json.lock`), so git never sees it; one held by a process that died is
+reclaimed after 30s, and a live one reports `YAD-STATE-006` rather than writing over the other's work.
 
 **Engagement (the Review Companion).** Each `engineer_review` entry carries `engagement: verified | none`
 — `verified` when the engineer reviewed through the [companion](../../yad-review-companion/SKILL.md)
@@ -110,11 +145,12 @@ The story frontmatter `status` reflects build progress:
 You write this flip into `stories/<story>.md`, but **do not hand-commit it** — the next
 `yad checkpoint --push` carries it in the same `chore(hub)` commit as the ledgers (the story now has a
 build-log ship, so checkpoint stages it; #112). This is what keeps the story artifact from drifting
-from `build-log.json`, so there is never a reason to fall back to a raw `git push origin main`.
+from the build ledger, so there is never a reason to fall back to a raw `git push origin main`.
 
 So the chain is traceable both ways: from the epic down (`epic.md` → `stories/<story>.md` →
-`tasks.md` → `build-log.json` ship → `mergeCommit`) and from a merge commit back up (its `Task:`
-trailer → story → epic).
+`tasks.md` → the build-ledger ship → `mergeCommit`) and from a merge commit back up (its `Task:`
+trailer → story → epic). Resolve that ship by the union rule, not from `build-log.json` alone — until
+`yad tidy up` folds it, the ship lives only in its `build-log/` shard and the chain looks broken.
 
 ## Preconditions for ship (all required)
 

package/skills/yad-epic/references/state-schema.md

@@ -325,11 +325,17 @@ storage layout is noted here (it mirrors `trust-log.json`):
   ship object. `(story, task, repo)` is already a natural unique key, so no `uid` is needed.
 - **Folded file:** `epics/<epic>/.sdlc/build-log.json` = `{ "epic": "<id>", "ships": [ <ship>, … ] }`
   (also the legacy single-file layout, and the output of `yad tidy up`).
-- **Union-read rule:** union the folded `ships` with every `build-log/` shard, **deduping by
-  `(story, task, repo)`** — a shard WINS over a stale folded ship (so a `yad review reconcile` edit to a
-  ship's shard is authoritative until it is folded).
+- **Union-read rule (binding on every reader — never read the folded file alone):** union the folded
+  `ships` with every `build-log/` shard, **deduping by `(story, task, repo)`** — a shard WINS over a stale
+  folded ship (so a `yad review reconcile` edit to a ship's shard is authoritative until it is folded).
+  `build-log.json` on its own is only the *folded* half of the ledger: it omits every ship `yad tidy up`
+  has not folded, including every `yad checkpoint --retro-ship` backfill, and — because `tidy up` folds
+  only a story whose frontmatter is `shipped` — every ship on a story still at `in-build`, indefinitely.
+  A reader that skips the union silently under-reports what shipped (#167).
 - `yad checkpoint` commits the shard dir; `yad tidy up` folds a shipped story's finished shards into the
-  folded file (loose objects + `git gc`).
+  folded file (loose objects + `git gc`). No **ship** path ever appends to the folded file — that is what
+  keeps concurrent shippers conflict-free. (`yad review reconcile` does write it, but only to stamp a ship
+  already folded there; see `updateShip`.)
 
 ---
 

package/skills/yad-reconcile/SKILL.md

@@ -34,7 +34,7 @@ Run `yad reconcile check` (optionally `--thread EP-<genesis>`). For each thread
 `yad check` drift style, any of:
 - **Broken lineage** — a change-epic whose `parent` is missing, a cycle, or a `thread` cache that
   disagrees with the computed root (the same signal `yad doctor` reports).
-- **Orphan / drift** — code shipped (`build-log.json`) or a touched repo's HEAD advanced past its
+- **Orphan / drift** — code shipped (the build ledger) or a touched repo's HEAD advanced past its
   `repos.json` `syncedHead` with **no owning change-epic** in any thread — i.e. behaviour reached
   production that no epic in the thread describes. Name the repo (`<repo>: <old>→<new>`).
 - **Open hotfix debt** — a `reconcile-debt.json` entry still `open`; the next normal change on that
@@ -42,6 +42,14 @@ Run `yad reconcile check` (optionally `--thread EP-<genesis>`). For each thread
 
 Writes nothing. This is the read-only sweep a human (or CI) runs to see the picture.
 
+> **Read the build ledger as a union — a missed ship reads as "no drift".** It is **shard-then-fold**:
+> union the folded `.sdlc/build-log.json` `ships` with every loose `.sdlc/build-log/` shard, deduped by
+> `(story, task, repo)` (a shard WINS over a folded ship of the same key). Reading `build-log.json` alone
+> drops every ship not yet folded by `yad tidy up` — including every `yad checkpoint --retro-ship` backfill,
+> and every ship on a story still at `in-build`, which `tidy up` never folds. Those are exactly the ships
+> most likely to be orphaned, so missing them turns this check into a false all-clear. See
+> `../yad-engineer-review/references/ship-and-record.md`.
+
 ### Step 2 — `refresh` (advisory, never silent)
 For each flagged thread, **point the human at the fix** — open a reconcile change-epic with `yad-change`
 (`kind: change`, threaded to the affected feature) to bring the front artifacts back in step with what

package/skills/yad-timeline/SKILL.md

@@ -38,9 +38,15 @@ current-truth map, and any open reconcile debt. **STOP** and report if the linea
 
 ### Step 2 — Read each node's evolution facts
 For each epic in the chain read `epic.md` (lineage + the change brief), `.sdlc/change.json` (depth,
-defect block), `.sdlc/build-log.json` (ship events), and the contract-lock (a real lock = a re-lock
+defect block), the build ledger (ship events), and the contract-lock (a real lock = a re-lock
 event; a pointer-lock = inherited). Greenfield-safe: an absent input degrades its part of the view.
 
+The build ledger is **shard-then-fold**, so read it as the **union** of the folded `.sdlc/build-log.json`
+`ships` PLUS every loose `.sdlc/build-log/` shard, deduped by `(story, task, repo)` — a shard WINS over a
+folded ship of the same key. Reading `build-log.json` alone silently drops every ship not yet folded by
+`yad tidy up` (including every `yad checkpoint --retro-ship` backfill, and every ship on a story still at
+`in-build`, which `tidy up` never folds). See `../yad-engineer-review/references/ship-and-record.md`.
+
 ### Step 3 — Render the evolution view (yad-docs shell)
 Generate the site into `epics/<thread>/timeline-site/` (copy the shell verbatim; generate `src/data/*.ts`
 deterministically; theme from the design system). The thread maps onto the shell primitives: