yadflow 3.6.0 → 3.7.0

package/CHANGELOG.md

@@ -1,10 +1,13 @@
-# [3.6.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.5.3...v3.6.0) (2026-07-03)
+# [3.7.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.6.1...v3.7.0) (2026-07-04)
 
 
 ### Features
 
-* wire stub anchors into change/backfill/reconcile flows ([54d20f1](https://github.com/abdelrahmannasr/yadflow/commit/54d20f10340831bca503f4246606b0181c74a2b0))
-* **yad-stub:** mint stub genesis epics for brownfield defect intake ([7e6c4cd](https://github.com/abdelrahmannasr/yadflow/commit/7e6c4cd74f5a6e7f886115f7b9e5c0a571c2e408))
+* **cli:** add shared hub-commit default-branch guard helpers ([44290f6](https://github.com/abdelrahmannasr/yadflow/commit/44290f6109c806f077609fec352904efe801f830))
+* **cli:** add yad checkpoint to commit machine-written back-half state ([c09089c](https://github.com/abdelrahmannasr/yadflow/commit/c09089c698884ad39fc8cf66a7e28d8d44321668))
+* **cli:** add yad tidy up to fold finished ledger shards ([59727f3](https://github.com/abdelrahmannasr/yadflow/commit/59727f32a7b5e3274c8fd96b8b39134b3acf6705))
+* **cli:** shard-then-fold storage for the back-half ledgers ([6182598](https://github.com/abdelrahmannasr/yadflow/commit/618259847e3dbdee5f00bce4fa2a5d64df0364a3))
+* **cli:** wire yad checkpoint and yad tidy up into the CLI ([fe4770d](https://github.com/abdelrahmannasr/yadflow/commit/fe4770de87ebec394c3a29c78077a0baf7a924cc))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/bin/yad.mjs

@@ -10,6 +10,8 @@ import { runCommit } from '../cli/commit.mjs';
 import { runOpenPr } from '../cli/openpr.mjs';
 import { reviewTrailer, reviewContext, reviewNudge, reviewReconcile, reviewWalkthrough } from '../cli/review.mjs';
 import { runShip } from '../cli/ship.mjs';
+import { runCheckpoint } from '../cli/checkpoint.mjs';
+import { runTidy } from '../cli/tidy.mjs';
 import { runRepo } from '../cli/repo.mjs';
 import { runRoster } from '../cli/roster.mjs';
 import { runDocs } from '../cli/docs.mjs';
@@ -81,6 +83,14 @@ ${c.bold('Build helpers')}
                                        branch opens the front-half artifact-review PR (delegates to
                                        gate open), any other hub branch uses the code-task template
   yad ship --type <t> -m <subject>     Commit AND open the task PR/MR in one step (stage-aware)
+  yad checkpoint [--push]              Commit the machine-written back-half hub state
+                                       (trust-log/build-log/build-state) as one audit-trail
+                                       chore(hub) commit — default branch only (--allow-branch
+                                       to override); a no-op when nothing changed
+  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"
+                                       for the shard files; a no-op when nothing is foldable
   yad review trailer --repo <r> --pr <n> --body <text>   Post the companion's 60-sec briefing to a code PR/MR
   yad review context --repo <r> --pr <n>                  Print the grounding bundle for cards/chat
   yad review walkthrough --repo <r> --pr <n>              Bundle + ordered risk-tagged stops for the
@@ -133,6 +143,8 @@ function parseArgs(argv) {
     else if (a === '--force') o.force = true;
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = true;
+    else if (a === '--push') o.push = true;
+    else if (a === '--allow-branch') o.allowBranch = true;
     else if (a === '--merged') o.merged = true;
     else if (a === '--overview') o.overview = true;
     // `--check` is a bare boolean for `docs sync --check`, but takes a value for
@@ -259,6 +271,15 @@ async function main() {
     case 'ship':
       await runShip(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force, repo: o.repo, platform: o.platform, base: o.base, title: o.title, risk: o.risk });
       break;
+    case 'checkpoint':
+      await runCheckpoint(o.dir, { push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun });
+      break;
+    case 'tidy': {
+      const [, action, epic] = o._;
+      if (action !== 'up') { log(`usage: yad tidy up [<epic>] [--push] [--dry-run]`); process.exitCode = action ? 1 : 0; break; }
+      await runTidy(o.dir, { epic: epic || o.epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun });
+      break;
+    }
     case 'repo': {
       const [, action, name] = o._;
       await runRepo(o.dir, { action: action || 'list', name, today });

package/cli/checkpoint.mjs

@@ -0,0 +1,159 @@
+// `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
+// 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.
+//
+// Two invariants keep it out of the gates' way:
+//   1. It stages ONLY the three back-half ledgers by an explicit allowlist — never `git add -A`,
+//      which would sweep the CI-owned front-half ledger (state/approvals/comments/hub-prs.json,
+//      reviews/*.md) and trip the ledger-guard gate.
+//   2. It commits ONLY on the default branch (mirroring gate.mjs), so the commit never enters a PR's
+//      base..HEAD range — where verified-commits would fail an unsigned commit and its [skip ci]
+//      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 { PROJECT_FILES } from './manifest.mjs';
+import { loadHub } from './gate.mjs';
+import { resolveCommitterLogin } from './platform.mjs';
+import { hubGit, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
+
+// The machine-written back-half 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.
+const BACK_HALF = [
+  '.sdlc/trust-log.json', '.sdlc/trust-log',
+  '.sdlc/build-log.json', '.sdlc/build-log',
+  '.sdlc/build-state',
+];
+
+// PURE — the repo-relative pathspecs to stage: every back-half ledger that exists under any epic.
+// Explicit allowlist by design (see invariant 1 above).
+export function backHalfPathspecs(root) {
+  const epicsDir = path.join(root, 'epics');
+  if (!fs.existsSync(epicsDir)) return [];
+  const out = [];
+  for (const e of fs.readdirSync(epicsDir, { withFileTypes: true })) {
+    if (!e.isDirectory()) continue;
+    for (const rel of BACK_HALF) {
+      if (fs.existsSync(path.join(epicsDir, e.name, rel))) out.push(path.posix.join('epics', e.name, rel));
+    }
+  }
+  return out;
+}
+
+// PURE — turn the staged pathspecs into the subject label + the body's file list. A story id is pulled
+// from any file that carries one (`build-state/<story>.json`, a `trust-log/`/`build-log/` shard whose
+// name starts with the story id); the folded logs are epic-scoped. Prefer the most specific label.
+export function summarizeStaged(files = []) {
+  const stories = new Set();
+  const epics = new Set();
+  const basenames = [];
+  for (const f of files) {
+    const m = f.match(/^epics\/([^/]+)\/\.sdlc\/(.+)$/);
+    if (!m) continue;
+    const [, epic, rest] = m;
+    epics.add(epic);
+    // the first `…-S0N` token in the filename is the story id (ids contain hyphens; `[\w-]` stops at `/`)
+    const s = rest.match(/([A-Za-z][\w-]*?-S\d+)/);
+    if (s) stories.add(`${epic}/${s[1]}`);
+    basenames.push(rest);
+  }
+  let label;
+  if (stories.size === 1) label = [...stories][0];
+  else if (stories.size > 1) label = `${stories.size} stories`;
+  else if (epics.size === 1) label = [...epics][0];
+  else label = `${epics.size} epics`;
+  return { label, basenames };
+}
+
+// Collapse any whitespace/newline runs to a single space — keeps a hostile `git user.name` or a stray
+// 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,
+// else a stable placeholder so the subject is never empty.
+export function checkpointAuthor(login, name) {
+  if (login) return `@${oneLine(login)}`;
+  const n = oneLine(name);
+  return n || 'unknown';
+}
+
+// PURE — the audit-trail commit message. The subject passes the hub 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 body = basenames.length ? `Updated: ${basenames.join(', ')}` : '';
+  return body ? `${subject}\n\n${body}` : subject;
+}
+
+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');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { hub } = loadHub(root);
+  const git = hubGit(root);
+  const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
+  const defaultBranch = resolveDefaultBranch(git, hub);
+
+  // Default-branch guard (invariant 2) — shared with `yad tidy up`.
+  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad checkpoint' })) return;
+
+  const pathspecs = backHalfPathspecs(root);
+  if (!pathspecs.length) { 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 (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
+    info('back-half state unchanged — nothing to commit');
+    return;
+  }
+  // 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
+  // when the dir is empty, e.g. created before its first story JSON). This also scopes the commit to
+  // ONLY the allowlist, so any unrelated pre-staged file never rides along.
+  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 message = buildCheckpointMessage({ label, author, basenames });
+
+  if (opts.dryRun) {
+    log('\n' + c.dim(message) + '\n');
+    git('reset', '-q', '--', ...pathspecs); // restore the index — a dry run must not leave things staged
+    info('dry run — not committed');
+    return { message };
+  }
+
+  const cm = git('commit', '-m', message, '--', ...staged);
+  if (!cm.ok) {
+    git('reset', '-q', '--', ...pathspecs); // don't leave the ledgers staged for an unrelated commit to sweep up
+    fail(`git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
+    process.exitCode = 1;
+    return { message };
+  }
+  ok(`checkpointed ${staged.length} file(s): ${c.dim(label)}`);
+
+  if (!opts.push) return { message };
+  // 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 }; }
+  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 };
+}

package/cli/gate.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
-  c, log, ok, info, warn, hand, fail, note, readJSONStrict, writeJSON, run,
+  c, log, ok, info, warn, hand, fail, note, readJSONStrict, writeJSON, run, pushWithRebase,
 } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
 import {
@@ -83,7 +83,7 @@ function warnIncompleteDiscovery(epicDir, artifact) {
 
 // Fail fast on a corrupt or wrong-shape hub config: a silently-defaulted hub.json would degrade
 // every gate to file-only without anyone noticing, and a typo'd platform would read as "no bridge".
-function loadHub(root) {
+export function loadHub(root) {
   const hubFile = path.join(root, PROJECT_FILES.hubConfig);
   const regFile = path.join(root, PROJECT_FILES.reposRegistry);
   // Distinguish an ABSENT hub.json (null default → fine, file-only gate) from one that exists but
@@ -441,13 +441,7 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
   ok(`committed gate update: ${c.dim(subject)}`);
   if (!push) return { synced };
 
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    if (git('push', 'origin', `HEAD:${target}`).ok) { ok(`pushed to origin/${target}`); return { synced }; }
-    if (attempt < 3) {
-      info(`push rejected — rebasing onto origin/${target} and retrying (${attempt}/3)`);
-      if (!git('pull', '--rebase', 'origin', target).ok) git('rebase', '--abort'); // never leave a wedged rebase
-    }
-  }
+  if (pushWithRebase(root, target).ok) { ok(`pushed to origin/${target}`); return { synced }; }
   fail(`could not push to origin/${target}${merged ? ' — protected default branch? allow the gate bot to push the merge advance (see yad-hub-bridge references/bridge.md)' : ''} — or run \`yad gate sync\` locally`);
   process.exitCode = 1;
   return { synced };
@@ -645,7 +639,7 @@ export async function gateTrailer(root, { epic, artifact, body, number, getBody
 // ---- helpers ------------------------------------------------------------------------------------
 const base = (artifact) => artifactBase(artifact);
 
-function fillHubTemplate({ epic, artifact, step, owner, domains }) {
+export function fillHubTemplate({ epic, artifact, step, owner, domains }) {
   return [
     '## Artifact under review',
     `- Epic: \`${epic}\``,
@@ -660,6 +654,15 @@ function fillHubTemplate({ epic, artifact, step, owner, domains }) {
     '## How to review (this drives the gate)',
     '- **Approve** to record your approval; **comment / request changes** to hold the gate.',
     '- This step advances when approvals are satisfied, all threads are resolved, and this PR is merged.',
+    '',
+    // Required by the hub `pr-template` gate (check_hub_body). Mirrors the Checklist block of the
+    // committed static template (yad-pr-template/templates/hub/<platform>/) so the generated body
+    // passes on the first CI run.
+    '## Checklist',
+    '- [ ] `owner` set in the artifact frontmatter (inherited from `epic.md`)',
+    '- [ ] Contract re-locked (`.sdlc/contract-lock.json`) if the surface changed (architecture only)',
+    '- [ ] Risk tags reflect the real surface touched (contract/auth/payments escalate)',
+    '- [ ] No secrets or tokens in the artifact or this description',
   ].join('\n');
 }
 

package/cli/hubcommit.mjs

@@ -0,0 +1,33 @@
+// Shared machinery for committing the machine-written back-half ledgers to the hub — used by both
+// `yad checkpoint` (sync new state) and `yad tidy up` (fold finished shards). Both must commit ONLY on
+// the default branch, so their `[skip ci]` commit never enters a PR's base..HEAD range (where it would
+// strand required checks and fail verified-commits). This module is the single home of that guard.
+import { warn, fail, hand, run } from './lib.mjs';
+
+export const hubGit = (root) => (...args) => run('git', args, { cwd: root });
+
+// The default branch: hub config, else the remote's published default (origin/HEAD), else 'main'.
+// NEVER the current branch — falling back to it (as gate.mjs does, safe there because CI checks out the
+// default branch) would make the guard below a no-op on a WIP branch and let an unsigned commit land in
+// a future PR's range.
+export function resolveDefaultBranch(git, hub) {
+  const originHead = git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD'); // e.g. "origin/main"
+  return hub?.default_branch
+    || (originHead.ok && originHead.stdout ? originHead.stdout.replace(/^origin\//, '') : '')
+    || 'main';
+}
+
+// Guard: only commit on the default branch. Returns true when OK; on a non-default branch it prints the
+// refusal + sets a non-zero exit code, unless `allowBranch` overrides (with a warning). `--allow-branch`
+// is the SINGLE documented override — never `--force` (which elsewhere only waives the atomic guard).
+export function guardDefaultBranch(branch, defaultBranch, { allowBranch = false, cmd = 'yad checkpoint' } = {}) {
+  if (branch === defaultBranch) return true;
+  if (allowBranch) {
+    warn(`--allow-branch: committing on '${branch}' — pushes go to origin/${branch}, and this commit needs a verified signature to pass the gate in a PR`);
+    return true;
+  }
+  fail(`on '${branch}', not the default branch '${defaultBranch}' — ${cmd} commits go to the default branch to stay out of PR-checked ranges`);
+  hand(`switch to '${defaultBranch}' and re-run, or pass --allow-branch to override (set default_branch in .sdlc/hub.json if '${defaultBranch}' is wrong)`);
+  process.exitCode = 1;
+  return false;
+}

package/cli/ledger.mjs

@@ -0,0 +1,147 @@
+// Shard-then-fold storage for the two append-only back-half ledgers (trust-log, build-log).
+//
+// The problem: both ledgers were ONE file per epic, so two people driving different stories of the
+// SAME epic both appended to the same file → git merge conflict on push. The fix ("loose objects +
+// `git gc`"): each writer writes ONE small file per entry under a shard dir, so concurrent writers
+// touch different files → zero conflict, by construction. Readers UNION the folded file (the legacy
+// single file, and the output of `yad tidy up`) with every loose shard. `yad tidy up` folds finished
+// shards back into the folded file on demand — a single, serialized, human-run act.
+//
+// A legacy epic that only has the folded file still reads correctly (no shards to union) → zero
+// migration; new writes simply go to shards.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJSON, readJSONStrict, writeJSON } from './lib.mjs';
+import { epicFiles } from './manifest.mjs';
+
+// ---- 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
+// the fields), so no parsing-back is needed. A trust entry needs `uid` to stay unique across re-runs
+// of the same (story, repo, step); a ship is unique by (story, task, repo) already.
+export const trustShardName = (e) => `${e.story}-${e.repo}-${e.step}-${e.uid}.json`;
+export const buildShardName = (e) => `${e.story}-${e.task}-${e.repo}.json`;
+
+// Read every shard object under `dir` (each file = ONE entry object). Sorted for determinism; a
+// corrupt/non-object shard is skipped (these ledgers are advisory evidence, never fatal).
+function readShardDir(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(dir).filter((n) => n.endsWith('.json')).sort()) {
+    const obj = readJSON(path.join(dir, name), null);
+    if (obj && typeof obj === 'object' && !Array.isArray(obj)) out.push({ name, obj });
+  }
+  return out;
+}
+
+// The half-applied-tidy guard key: a shard is a genuine duplicate of a folded entry ONLY when its FULL
+// identity matches — NOT `uid` alone. `uid` is minted by an LLM skill, so two runs of DIFFERENT
+// (story,repo,step) could share a short token; keying on uid alone would drop the second as a false
+// "duplicate" and corrupt the trust count (in the unsafe direction). Legacy folded entries lack `uid`,
+// so their key never collides with a real shard's key — they are never skipped.
+const trustKey = (e) => `${e.story}|${e.repo}|${e.step}|${e.uid}`;
+
+// trust-log = the evidence base. EVERY entry is a distinct step run (re-runs of a step share
+// story/repo/step), so we CONCATENATE folded runs + shards and never dedup by (story,repo,step) —
+// that would drop re-run history the trust threshold counts. The only guard is a shard whose full
+// identity (`trustKey`) already appears folded (a half-applied tidy). A corrupt folded file must throw
+// (readJSONStrict), never silently read as empty — under-reporting the evidence base is a safety bug.
+export function readTrustRuns(epicDir) {
+  const f = epicFiles(epicDir);
+  const foldedObj = readJSONStrict(f.trustLog, null);
+  const folded = Array.isArray(foldedObj?.runs) ? foldedObj.runs : [];
+  const seen = new Set(folded.filter((e) => e && e.uid).map(trustKey));
+  const out = [...folded];
+  for (const { obj } of readShardDir(f.trustLogDir)) {
+    if (obj.uid && seen.has(trustKey(obj))) continue; // a true full-identity twin already folded
+    out.push(obj);
+  }
+  return out;
+}
+
+// build-log = one ship per (story, task, repo) — a natural unique key. `yad review reconcile` mutates
+// a ship's engineer_review in its shard, so a shard is authoritative and WINS over a stale folded
+// ship of the same key.
+const shipKey = (s) => `${s.story}|${s.task}|${s.repo}`;
+export function readShips(epicDir) {
+  const f = epicFiles(epicDir);
+  const foldedObj = readJSONStrict(f.buildLog, null);
+  const folded = Array.isArray(foldedObj?.ships) ? foldedObj.ships : [];
+  const byKey = new Map();
+  for (const s of folded) byKey.set(shipKey(s), s);
+  for (const { obj } of readShardDir(f.buildLogDir)) byKey.set(shipKey(obj), obj);
+  return [...byKey.values()];
+}
+
+// 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 };
+    }
+  }
+  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 };
+}
+
+// ---- folding (used by `yad tidy up`) -------------------------------------------------------------
+const trustSort = (a, b) =>
+  `${a.date || ''}|${a.story || ''}|${a.repo || ''}|${a.step || ''}|${a.uid || ''}`
+    .localeCompare(`${b.date || ''}|${b.story || ''}|${b.repo || ''}|${b.step || ''}|${b.uid || ''}`);
+const buildSort = (a, b) =>
+  `${a.shippedAt || ''}|${a.story || ''}|${a.task || ''}|${a.repo || ''}`
+    .localeCompare(`${b.shippedAt || ''}|${b.story || ''}|${b.task || ''}|${b.repo || ''}`);
+
+// Fold the shards that `pick(entry)` selects into the folded file, then delete them. Returns
+// { folded, remaining, deleted } — `deleted` are the removed shard paths so the caller can stage them.
+// Idempotent: nothing picked → no write, no delete. Deterministic order so the folded output is stable.
+function fold(epicDir, { foldedPath, dir, arr, isTrust }, pick, { dryRun = false } = {}) {
+  const shards = readShardDir(dir);
+  const toFold = shards.filter((s) => pick(s.obj));
+  if (!toFold.length) return { folded: 0, remaining: shards.length, deleted: [] };
+  if (dryRun) return { folded: toFold.length, remaining: shards.length - toFold.length, deleted: [] };
+
+  // A corrupt folded file must ABORT the fold (readJSONStrict throws), never be silently rebuilt from
+  // scratch — rebuilding would erase all previously-folded history.
+  const foldedObj = readJSONStrict(foldedPath, null) || { epic: path.basename(epicDir), [arr]: [] };
+  if (!Array.isArray(foldedObj[arr])) foldedObj[arr] = [];
+  if (isTrust) {
+    // Guard on FULL identity (trustKey), not uid alone — a shard skipped here is a genuine twin of an
+    // already-folded run, so deleting it below is safe; two runs that merely share a uid keep both.
+    const seen = new Set(foldedObj.runs.filter((e) => e && e.uid).map(trustKey));
+    for (const s of toFold) if (!(s.obj.uid && seen.has(trustKey(s.obj)))) foldedObj.runs.push(s.obj);
+    foldedObj.runs.sort(trustSort);
+  } else {
+    const byKey = new Map(foldedObj.ships.map((s) => [shipKey(s), s]));
+    for (const s of toFold) byKey.set(shipKey(s.obj), s.obj);
+    foldedObj.ships = [...byKey.values()].sort(buildSort);
+  }
+  writeJSON(foldedPath, foldedObj);
+  const deleted = [];
+  for (const s of toFold) {
+    const p = path.join(dir, s.name);
+    fs.rmSync(p, { force: true });
+    deleted.push(p);
+  }
+  return { folded: toFold.length, remaining: shards.length - toFold.length, deleted };
+}
+
+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);
+}
+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);
+}

package/cli/lib.mjs

@@ -147,3 +147,19 @@ export function run(cmd, args = [], opts = {}) {
   };
 }
 export const has = (cmd) => run(process.platform === 'win32' ? 'where' : 'which', [cmd]).ok;
+
+// Push HEAD to origin/<target>, rebasing onto it and retrying on rejection — both the front-half gate
+// sync and the back-half checkpoint push append-only ledgers to the default branch, so a concurrent
+// push is a normal race, not an error. Returns { ok } after up to `attempts` tries; logs each retry.
+// A failed `pull --rebase` is aborted so we never leave a wedged rebase for the next command.
+export function pushWithRebase(cwd, target, { attempts = 3 } = {}) {
+  const git = (...args) => run('git', args, { cwd });
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    if (git('push', 'origin', `HEAD:${target}`).ok) return { ok: true };
+    if (attempt < attempts) {
+      info(`push rejected — rebasing onto origin/${target} and retrying (${attempt}/${attempts})`);
+      if (!git('pull', '--rebase', 'origin', target).ok) git('rebase', '--abort');
+    }
+  }
+  return { ok: false };
+}

package/cli/manifest.mjs

@@ -178,7 +178,13 @@ export const epicFiles = (epicRoot) => ({
   comments: `${epicRoot}/.sdlc/comments.json`,
   hubPrs: `${epicRoot}/.sdlc/hub-prs.json`,
   contractLock: `${epicRoot}/.sdlc/contract-lock.json`,
-  buildLog: `${epicRoot}/.sdlc/build-log.json`,
+  // The two append-only back-half ledgers use shard-then-fold storage (cli/ledger.mjs): writers add
+  // one loose shard per entry under the *Dir path (conflict-free concurrent writes); `yad tidy up`
+  // folds finished shards back into the single *Log file. Readers union the folded file + loose shards.
+  buildLog: `${epicRoot}/.sdlc/build-log.json`,         // folded ships (also the legacy single file)
+  buildLogDir: `${epicRoot}/.sdlc/build-log`,           // one <story>-<task>-<repo>.json per ship
+  trustLog: `${epicRoot}/.sdlc/trust-log.json`,         // folded runs (also the legacy single file)
+  trustLogDir: `${epicRoot}/.sdlc/trust-log`,           // one <story>-<repo>-<step>-<uid>.json per run
   buildStateDir: `${epicRoot}/.sdlc/build-state`,       // Phase 4 — per-story, per-repo back-half state
 
   change: `${epicRoot}/.sdlc/change.json`,             // Phase 6 — change/defect intake + triage

package/cli/review.mjs

@@ -6,8 +6,9 @@
 // The CLI never calls an LLM: the skill (yad-review-companion / yad-engineer-review) generates the
 // trailer/cards/chat text and posts it via these primitives, all to the PLATFORM (never a ledger file).
 import path from 'node:path';
-import { log, ok, info, warn, fail, note, run, readJSON, writeJSON } from './lib.mjs';
-import { PROJECT_FILES, epicFiles } from './manifest.mjs';
+import { log, ok, info, warn, fail, note, run, readJSON } from './lib.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
+import { updateShip } from './ledger.mjs';
 import { epicRoot } from './epic-state.mjs';
 import {
   detectPlatform, readPr, mapApprovers, getPrBody, editPrBody, postComment, prNumberFromUrl,
@@ -161,18 +162,19 @@ export async function reviewReconcile(root, { epic, repo, dir, pr, reader = read
     engineerReview.push({ approver: r.name, role: r.role, ...(r.domain ? { domain: r.domain } : {}), engagement: r.engagement === 'verified' ? 'verified' : 'none' });
   }
 
-  const file = epicFiles(epicRoot(root, epic)).buildLog;
-  const ledger = readJSON(file, null);
   // Match by exact PR number — never substring (`--pr 5` must not match a ship recorded against #15).
-  const ship = ledger?.ships?.find((s) => s.pr != null
-    && (String(s.pr) === String(pr) || prNumberFromUrl(s.pr) === String(pr)));
-  if (!ship) {
+  // build-log is shard-then-fold now: updateShip mutates the ship's own loose shard (authoritative
+  // until `yad tidy up` folds it), or the folded file if already folded — never both.
+  const res = updateShip(
+    epicRoot(root, epic),
+    (s) => s.pr != null && (String(s.pr) === String(pr) || prNumberFromUrl(s.pr) === String(pr)),
+    (s) => { s.engineer_review = engineerReview; },
+  );
+  if (!res.found) {
     warn(`no build-log ship record matches PR #${pr} in ${epic} — attach this at ship time:`);
     log(JSON.stringify({ engineer_review: engineerReview }, null, 2));
     return { engineerReview, written: false };
   }
-  ship.engineer_review = engineerReview;
-  writeJSON(file, ledger);
-  ok(`stamped engagement onto ${epic} ship ${ship.story || ''}${ship.task ? '/' + ship.task : ''} (PR #${pr})`);
+  ok(`stamped engagement onto ${epic} ship ${res.ship.story || ''}${res.ship.task ? '/' + res.ship.task : ''} (PR #${pr})`);
   return { engineerReview, written: true };
 }

package/cli/thread.mjs

@@ -5,6 +5,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, hand, readJSON, exists } from './lib.mjs';
+import { readShips } from './ledger.mjs';
 import {
   epicRoot, isValidEpicId, epicLineage, readFrontmatter, isStubEpic,
   resolveThread, threadEpics, resolveCurrentArtifacts, resolveCurrentStories, THREAD_ARTIFACT_BASES,
@@ -17,7 +18,9 @@ export const loadDebt = (root, epic) => {
   const v = readJSON(path.join(epicRoot(root, epic), '.sdlc', 'reconcile-debt.json'), []);
   return Array.isArray(v) ? v : [];
 };
-export const loadBuildLog = (root, epic) => readJSON(path.join(epicRoot(root, epic), '.sdlc', 'build-log.json'), null);
+// The build ledger is shard-then-fold now (cli/ledger.mjs): union the folded file + loose ship shards
+// so a caller sees every ship whether or not `yad tidy up` has folded them yet.
+export const loadBuildLog = (root, epic) => ({ epic, ships: readShips(epicRoot(root, epic)) });
 
 // An epic is SEALED once every authored story is `shipped` (config.yaml change.seal_on). A sealed epic
 // refuses new behaviour (epic-open.sh) — a further change must open a new threaded change-epic, which is

package/cli/tidy.mjs

@@ -0,0 +1,116 @@
+// `yad tidy up` — fold FINISHED back-half shards back into their single folded ledger, on demand.
+//
+// The two logs are shard-then-fold (cli/ledger.mjs): writers drop one loose file per entry so
+// concurrent writers never conflict. Left alone they accumulate; `yad tidy up` is the "pack it up"
+// step (git's loose-objects → `git gc`). It is a MANUAL, human-run act, so only one person folds at a
+// time — the fold is a rewrite (worse to conflict on than an append), and doing it deliberately keeps
+// it serialized. It folds ONLY shards of a SHIPPED story (terminal, no more writes coming), never an
+// in-progress one, so it can't race an active writer. Idempotent: nothing finished → no-op.
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, log, ok, info, fail, hand, exists, pushWithRebase } from './lib.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
+import { loadHub } from './gate.mjs';
+import { resolveCommitterLogin } from './platform.mjs';
+import { checkpointAuthor } from './checkpoint.mjs';
+import { hubGit, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
+import { foldTrust, foldBuild } from './ledger.mjs';
+import { epicRoot, isValidEpicId, readFrontmatter } from './epic-state.mjs';
+
+// Story ids in an epic whose frontmatter `status` is `shipped` — the terminal, safe-to-fold signal
+// (`yad-engineer-review` sets it once every task in the story has a ship record).
+export function shippedStories(root, epic) {
+  const dir = path.join(epicRoot(root, epic), 'stories');
+  const set = new Set();
+  if (!exists(dir)) return set;
+  for (const name of fs.readdirSync(dir).filter((n) => n.endsWith('.md'))) {
+    if (readFrontmatter(path.join(dir, name)).status === 'shipped') set.add(name.replace(/\.md$/, ''));
+  }
+  return set;
+}
+
+function epicsWithLedgers(root) {
+  const dir = path.join(root, 'epics');
+  if (!exists(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && isValidEpicId(e.name)).map((e) => e.name).sort();
+}
+
+export async function runTidy(root, opts = {}) {
+  log(c.bold('\nyad tidy up'));
+  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 — run `yad tidy up` from the product hub');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { hub } = loadHub(root);
+  const git = hubGit(root);
+  const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
+  const defaultBranch = resolveDefaultBranch(git, hub);
+  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad tidy up' })) return;
+
+  if (opts.epic && !isValidEpicId(opts.epic)) { fail(`invalid epic id '${opts.epic}'`); process.exitCode = 1; return; }
+  if (opts.epic && !exists(epicRoot(root, opts.epic))) { fail(`no such epic '${opts.epic}'`); process.exitCode = 1; return; }
+  const epics = opts.epic ? [opts.epic] : epicsWithLedgers(root);
+  const touched = [];
+  let folded = 0;
+  for (const epic of epics) {
+    const shipped = shippedStories(root, epic);
+    const pick = (e) => shipped.has(e.story); // only a shipped story's shards are safe to fold
+    const epicDir = epicRoot(root, epic);
+    const t = foldTrust(epicDir, pick, { dryRun: opts.dryRun });
+    const b = foldBuild(epicDir, pick, { dryRun: opts.dryRun });
+    if (t.folded + b.folded > 0) {
+      folded += t.folded + b.folded;
+      touched.push(epic);
+      info(`${epic}: ${opts.dryRun ? 'would fold' : 'folded'} ${t.folded} trust + ${b.folded} build shard(s)`);
+    }
+  }
+  if (!folded) { info('nothing to tidy — no finished shards to fold'); return { folded: 0 }; }
+
+  const author = checkpointAuthor(resolveCommitterLogin(root, hub?.roster || []), git('config', 'user.name').stdout);
+  const label = touched.length === 1 ? touched[0] : `${touched.length} epics`;
+  const message = `chore(hub): tidy back-half ledgers — ${label} by ${author} [skip ci]`;
+
+  if (opts.dryRun) {
+    log('\n' + c.dim(message) + '\n');
+    info('dry run — nothing folded or committed');
+    return { message, folded };
+  }
+
+  // Stage the fold (modified folded files + deleted shards) under each touched epic's ledger paths.
+  // A pathspec that matches NOTHING (neither on disk nor tracked) makes `git add` fatal (exit 128), so
+  // keep only the paths that exist OR are tracked — `git add -A` on those stages new/modified files AND
+  // the shard deletions (even when the shard dir is now empty or removed).
+  const candidates = touched.flatMap((e) => {
+    const rel = `epics/${e}/.sdlc`;
+    return [`${rel}/trust-log.json`, `${rel}/trust-log`, `${rel}/build-log.json`, `${rel}/build-log`];
+  });
+  const pathspecs = candidates.filter((spec) =>
+    exists(path.join(root, spec)) || git('ls-files', '--error-unmatch', '--', spec).ok);
+  if (!pathspecs.length) { info('fold produced no stageable change'); return { folded }; }
+  const add = git('add', '-A', '--', ...pathspecs);
+  if (!add.ok) { fail(`git add failed — ${add.stderr.split('\n')[0] || add.code}`); process.exitCode = 1; return { folded }; }
+  const staged = git('diff', '--cached', '--name-only', '--', ...pathspecs).stdout.split('\n').filter(Boolean);
+  if (!staged.length) { info('fold produced no net change — nothing to commit'); return { folded }; }
+
+  const cm = git('commit', '-m', message, '--', ...staged);
+  if (!cm.ok) {
+    // Leave the fold STAGED (don't reset) — the on-disk fold already happened, so a re-run would see
+    // "nothing to tidy"; keeping it staged lets a retry or `yad checkpoint` land it, never lose it.
+    fail(`git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
+    hand('the fold is staged — re-run `yad tidy up`, or `yad checkpoint` to land it');
+    process.exitCode = 1;
+    return { message, folded };
+  }
+  ok(`tidied ${folded} shard(s) into ${touched.length} epic ledger(s): ${c.dim(label)}`);
+
+  if (!opts.push) return { message, folded };
+  if (pushWithRebase(root, branch).ok) { ok(`pushed to origin/${branch}`); return { message, folded }; }
+  fail(`could not push to origin/${branch} — a protected branch, or an unresolvable rebase conflict`);
+  hand(`run \`git pull --rebase\` and re-run \`yad tidy up --push\``);
+  process.exitCode = 1;
+  return { message, folded };
+}

package/cli/usage.mjs

@@ -15,6 +15,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { c, log, ok, note, readJSON, run } from './lib.mjs';
 import { PROJECT_FILES, epicFiles } from './manifest.mjs';
+import { readShips } from './ledger.mjs';
 import { rolesForScope } from './platform.mjs';
 
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
@@ -105,8 +106,7 @@ function ledgerEvents(root, epic, resolver) {
   };
   for (const a of readLedger(f.approvals, []) || []) emit(a.approver, 'approved', a.date, { artifact: a.artifact, role: a.role });
   for (const cm of readLedger(f.comments, []) || []) emit(cm.commenter, 'commented', cm.date, { artifact: cm.artifact, role: cm.role });
-  const bl = readLedger(f.buildLog, null);
-  for (const s of bl?.ships || []) {
+  for (const s of readShips(path.join(root, 'epics', epic))) {
     for (const er of s.engineer_review || []) emit(er.approver, 'shipped', s.shippedAt, { story: s.story, task: s.task, repo: s.repo, risk: s.risk });
   }
   return events;
@@ -246,8 +246,7 @@ function memberFlags(m) {
 export function shipHygiene(root, { since, until } = {}) {
   const items = [];
   for (const epic of listEpics(root)) {
-    const bl = readLedger(epicFiles(path.join(root, 'epics', epic)).buildLog, null);
-    for (const s of bl?.ships || []) {
+    for (const s of readShips(path.join(root, 'epics', epic))) {
       if (!inWindow(s.shippedAt, since, until)) 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.6.0",
+  "version": "3.7.0",
   "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/yad-engineer-review/SKILL.md

@@ -16,7 +16,11 @@ then **ship** — merge, record the ship, and update the story state. This is th
 - `{project-root}` resolves from the project working directory — the **product** repo (the source of
   truth: it holds the story and the build ledger).
 - Code repos are separate git repos under `{project-root}/demo-repos/<repo>/`.
-- The build ledger is `{project-root}/epics/<epic>/.sdlc/build-log.json` (append-only).
+- The build ledger uses **shard-then-fold** storage: each ship is its own shard file
+  `{project-root}/epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json`, so concurrent shippers never
+  conflict; readers UNION the folded `build-log.json` with every loose shard, and `yad tidy up` folds
+  finished shards back into `build-log.json`. It — like the trust log and build-state — is committed by
+  `yad checkpoint` (see Step 3), not by hand.
 - The engineer-review rule reuses `yad-review-gate`: base = at least one `owner` AND one distinct
   `reviewer`; **escalated** (the PR's Impact & Risk is `high`, or it touches contract/auth/payments) =
   base PLUS one `domain-owner` per touched domain — the same routing `yad-pr-template`'s
@@ -59,7 +63,7 @@ and records an approval. Determine the rule from the PR's Impact & Risk block (r
 domain-owner per touched domain. Record each approval; re-evaluate whether the rule is satisfied.
 Record `engagement: verified` when the engineer reviewed through the companion (else `none` for a bare
 approve); `yad review reconcile --epic <id> --repo <r> --pr <n>` stamps it onto the ship record from the
-platform. Soft by default (both count; a bare approve draws `yad review nudge`); only gates when
+platform (mutating the ship's shard where it lives, or its folded entry if already tidied). Soft by default (both count; a bare approve draws `yad review nudge`); only gates when
 `hub.review.requireEngagement: true`. The signal is gameable by design and sits **beside** the CI gates,
 never above them.
 Recording an approval does **not** ship — shipping is a separate, explicit step. Front-half discipline:
@@ -69,7 +73,9 @@ the gate talks only through files; refuse to treat AI review as a human approval
 Ship **iff ALL hold**: the check gates pass (Step C), the AI review has run (advisory), and the
 engineer-review rule is satisfied (Step 2). Then:
 - **Merge** the task branch into the repo's default branch (the human performs/authorises the merge).
-- **Record the ship** — append to `epics/<epic>/.sdlc/build-log.json`:
+- **Record the ship** — write the ship to its own shard
+  `epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json` (readers union the folded `build-log.json` +
+  the loose shards, deduping by (story, task, repo) so a shard wins over a stale folded ship):
   ```json
   { "story": "<story>", "task": "<task>", "repo": "<repo>", "branch": "feat/<story>-<task>-…",
     "pr": "<url|#>", "mergeCommit": "<sha>", "gates": ["spec-link","contract-check","build-test-lint"],
@@ -81,11 +87,19 @@ engineer-review rule is satisfied (Step 2). Then:
   **epic → story → task → PR → mergeCommit** is now traceable end to end.
 - **Finalize the trust verdict (Phase 4).** If this story has a `build-state/<story>.json` (it ran
   through `yad-run`), the engineer **confirms or overrides** the provisional trust verdict that the
-  orchestrator derived for this run, and the final verdict is written to
-  `epics/<epic>/.sdlc/trust-log.json`. The human has the last word on the trust signal: a diff merged
+  orchestrator derived for this run, and the final verdict is written back into that run's trust shard
+  `epics/<epic>/.sdlc/trust-log/<story>-<repo>-implement-<uid>.json` (or, if the run was already folded
+  by `yad tidy up`, into its entry in the folded `trust-log.json`). The human has the last word on the trust signal: a diff merged
   as authored is `approved-unchanged`; one the engineer edited before merge is `approved-with-edits`;
   a rejected one is `rejected`. This is the evidence that later earns a step its `machine_advance`
   (it never weakens the merge gate — the engineer still owns the merge).
+- **Commit the machine-written ledgers.** Run `yad checkpoint --push` from `{project-root}` to commit
+  the back-half ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
+  `build-state/<story>.json` if the story ran through `yad-run`) as one `chore(hub): …` audit-trail
+  commit — default branch only, staging the shard dirs (`yad tidy up` folds finished shards later),
+  never a front-half gate file. It is the back-half analogue of the front-half `yad gate` sync; the
+  reviewable state (the story frontmatter `status`, the code-repo `tasks.md`) is committed as usual
+  alongside — checkpoint only lands the machine audit ledgers.
 
 ### Step 4 — Stop
 Report what shipped and the story's state. Do not advance anything else; the front-half `state.json`

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

@@ -15,9 +15,24 @@ ship. Shipping records the merge and updates the story state so the whole chain
    - **escalated:** when the PR's Impact & Risk is `high`, or it touches contract/auth/payments — base
      PLUS one `domain-owner` per touched domain (exactly what `risk-route.sh` prints).
 
-## The build ledger — `epics/<epic>/.sdlc/build-log.json`
+## The build ledger — shard-then-fold (`epics/<epic>/.sdlc/build-log/` → `build-log.json`)
 
-Append-only. One record per shipped task:
+Append-only, one record per shipped task. **Storage mirrors the trust log's "loose objects + `git gc`"
+model** so two people shipping different tasks of the same epic never collide on one file:
+- **Per-ship shard:** each ship is its own file `epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json`
+  = ONE ship object (the record below). `(story, task, repo)` is already unique, so no `uid` is needed;
+  concurrent shippers write different files → zero merge conflict.
+- **Folded file:** `epics/<epic>/.sdlc/build-log.json` = `{ "epic": "<id>", "ships": [ … ] }` — the
+  legacy single-file layout, and where `yad tidy up` folds finished shards.
+- **Union-read rule:** to read the ledger, union the folded `ships` with every `build-log/` shard,
+  **deduping by `(story, task, repo)`** — a loose shard WINS over a stale folded ship of the same key.
+- `yad review reconcile` stamps the engagement signal by **mutating the ship's shard** where it lives
+  (or the folded entry if the story was already tidied) — see below.
+- `yad checkpoint` commits the shard dir; `yad tidy up` (manual, one person) folds a shipped story's
+  finished shards into `build-log.json`.
+
+The folded file is shown below; a **shard** file is just one element of `ships` (the bare ship object,
+without the `{ epic, ships }` wrapper):
 
 ```json
 {
@@ -45,7 +60,11 @@ Append-only. One record per shipped task:
 ```
 
 This is the back-half analogue of the front half's `approvals.json` — files only, no hidden state, so a
-future service can drive ship by writing the same records.
+future service can drive ship by writing the same records. Like the trust log and build-state, it is a
+machine-written ledger committed by **`yad checkpoint`** (the back-half analogue of `yad gate` sync),
+not by hand: after recording the ship, `yad checkpoint --push` lands the new `build-log/` shard as a
+`chore(hub): …` audit-trail commit on the default branch (allowlist-scoped to the back-half ledgers,
+never a front-half gate file); `yad tidy up` folds finished shards into `build-log.json` later.
 
 **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)
@@ -53,7 +72,8 @@ future service can drive ship by writing the same records.
 approve. The optional `companion` block records which faces ran. It is **soft by default** (both count;
 a bare approve draws a friendly `yad review nudge`); it only gates ship when
 `hub.review.requireEngagement: true`. `yad review reconcile --epic <id> --repo <r> --pr <n>` reads the
-code PR's approvals (with the engagement signal) and stamps them onto the matching ship record — the
+code PR's approvals (with the engagement signal) and stamps them onto the matching ship record — writing
+back into the ship's shard where it lives (or its folded entry if the story was already tidied) — the
 back-half **bridge**, the analogue of `yad gate sync`. The signal is gameable by design ("visible, not
 impossible"): it makes engineer-review quality visible, it does not prove a human read the diff. It sits
 **beside** the CI gates (build/test/lint/contract/verified-commits) — never above them; CI still

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

@@ -149,6 +149,15 @@ Phase 3 recorded build progress only *after the fact* in `build-log.json`. Phase
 steps to carry their own `automation` dial so the orchestrator (`yad-run`) can read it and decide
 whether to advance on its own. Two new files under `.sdlc/` do this.
 
+> **Who commits these.** `build-state/<story-id>.json`, `trust-log.json`, and `build-log.json` are
+> **machine-written** by the back half (`yad-run`, `yad-engineer-review`) and committed by
+> **`yad checkpoint`** — the back-half analogue of the front-half `yad gate ci` sync. It lands them as
+> one `chore(hub): sync back-half state — <epic>/<story> by @<login>` audit-trail commit, on the
+> default branch, staging **only** these three ledgers by an explicit allowlist (never a front-half
+> gate file — `state/approvals/comments/hub-prs.json`, `reviews/*.md` — so `ledger-guard` never trips).
+> Teammates don't review these machine writes; the commit exists so CI, `yad status`, and other
+> machines always see current trust evidence.
+
 ## `build-state/<story-id>.json`
 One file per story that has entered the build half. The build half is **per-story, per-repo**, so the
 steps live under each repo (mirrors the per-repo shape of `build-log.json`).
@@ -189,15 +198,37 @@ story/repo's `currentStep` into the next build sub-step (`spec`/`tasks` → `yad
 `yad-implement`, `checks` → `yad-checks`, `engineer-review` → `yad-engineer-review`) and prints it with
 the remaining chain and the step's automation dial — so the build half is guided, not just hinted at.
 
-## `trust-log.json`
-Append-only ledger (an array), the back-half analogue of `approvals.json`. **This is the evidence
-base** that decides when a step is safe to automate (build plan Step A). One entry per step run:
+## `trust-log.json` (shard-then-fold)
+Append-only ledger, the back-half analogue of `approvals.json`. **This is the evidence base** that
+decides when a step is safe to automate (build plan Step A). One entry per step run.
+
+**Storage — loose shards + a folded file (the "loose objects + `git gc`" model).** Two people driving
+different stories of the same epic used to both append to one `trust-log.json` → a git merge conflict on
+push. So each writer now writes ONE small shard file per entry under a shard dir, and readers union it
+back:
+- **Shard dir & name:** `epics/<epic>/.sdlc/trust-log/<story>-<repo>-<step>-<uid>.json` — each file is
+  ONE trust entry object. `uid` is a short unique token the writer generates fresh per run (never
+  reused), so re-runs of the same `(story, repo, step)` stay distinct files → concurrent writers touch
+  different files → zero conflict by construction.
+- **Folded file:** `epics/<epic>/.sdlc/trust-log.json` = `{ "epic": "<id>", "runs": [ <entry>, … ] }`
+  (also the legacy single-file layout, and the output of `yad tidy up`).
+- **Union-read rule:** to read the ledger, take the folded file's `runs` array PLUS every file in the
+  `trust-log/` shard dir, and **concatenate** — every entry is a distinct run and the trust threshold
+  counts re-runs, so **never dedup by `(story, repo, step)`**. (The only guard: a shard whose FULL
+  identity `(story, repo, step, uid)` already appears in the folded `runs` is a half-applied tidy and is
+  skipped — keying on `uid` alone would wrongly drop a different run that happened to reuse a token.) A legacy epic with only
+  the folded file and no shard dir still reads correctly — nothing to union.
+- **`yad tidy up`** (manual, one person) folds a SHIPPED story's finished shards into the folded file's
+  `runs` and deletes them. Writers never fold — they only add shards; `yad checkpoint` commits the shard
+  dir, and `yad tidy up` is the back-half analogue of `git gc` folding loose objects.
+- The **threshold slice** (below) reads this same union, filtered to the step (and repo).
 
 ```json
 {
   "story": "EP-<slug>-S0N",
   "repo": "backend",
   "step": "checks",
+  "uid": "<short-unique-token>",
   "automation": "human_approve",
   "verdict": "approved-unchanged",
   "signals": { "checks": "pass", "human_edited_diff": false, "scope_overrun": false, "contract_touch": false },
@@ -210,6 +241,7 @@ base** that decides when a step is safe to automate (build plan Step A). One ent
 | Field | Values | Meaning |
 |-------|--------|---------|
 | `step` | a `back_steps` id | Which step this run is recorded against. |
+| `uid` | short unique token | Generated fresh per run (never reused) — makes each shard file and each re-run distinct; also the folded/loose de-dup guard. Legacy folded entries may lack it. |
 | `automation` | dial in force at run time | So the log shows whether the run was a manual or an automated advance. |
 | `verdict` | `approved-unchanged` \| `approved-with-edits` \| `rejected` | The trust signal. **Provisional verdict is derived** (below); the human gate for that step confirms or overrides it and finalizes the entry. |
 | `signals` | object | The raw inputs the provisional verdict was derived from. The fields present depend on the step (table below). |
@@ -231,10 +263,25 @@ same three-way shape, anchored to each step's human gate, never self-graded):
 - accepted as produced → `approved-unchanged`.
 
 **Trust threshold** (from `config.yaml` `automation.trust_threshold`): a step is a candidate for
-`machine_advance` only when its slice of `trust-log.json` (same `step`, this story's repo or the
-project) has `>= min_runs` entries AND the fraction with `verdict == "approved-unchanged"` is
+`machine_advance` only when its slice of the trust ledger — the **union** of the folded `trust-log.json`
+`runs` plus every `trust-log/` shard, filtered to the same `step` (this story's repo or the project) —
+has `>= min_runs` entries AND the fraction with `verdict == "approved-unchanged"` is
 `>= min_approved_unchanged`. The dial-setter in `yad-run` enforces this; `yad-status` surfaces it.
 
+## `build-log.json` (shard-then-fold)
+The build ledger records one ship per merged task. Its schema and the ship record's fields are
+documented authoritatively in `../../yad-engineer-review/references/ship-and-record.md`; only its
+storage layout is noted here (it mirrors `trust-log.json`):
+- **Shard dir & name:** `epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json` — each file is ONE
+  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).
+- `yad checkpoint` commits the shard dir; `yad tidy up` folds a shipped story's finished shards into the
+  folded file (loose objects + `git gc`).
+
 ---
 
 # Phase 6 — feature threads (post-lock change management)

package/skills/yad-implement/SKILL.md

@@ -121,8 +121,9 @@ finalize a `tasks` trust entry, anchored to what the human/dev actually did with
 - the task is **re-scoped** first (its `Files:`/boundary edited) → `approved-with-edits`
   (signal `task_rescoped: true`);
 - the task list is discarded / regenerated → `rejected`.
-Append the entry to `epics/<epic>/.sdlc/trust-log.json` (schema:
-`../yad-epic/references/state-schema.md`). `tasks` stays `human_approve` until its slice clears
+Write the entry to its own shard `epics/<epic>/.sdlc/trust-log/<story>-<repo>-tasks-<uid>.json` (a fresh
+`uid` per run, so concurrent writers never conflict; readers union the folded `trust-log.json` + the
+loose shards). Schema: `../yad-epic/references/state-schema.md`. `tasks` stays `human_approve` until its slice clears
 the threshold — this only *gathers* evidence. (The `implement` step's own verdict is finalized later,
 at the engineer review in `yad-engineer-review`: merged as authored → `approved-unchanged`; edited first →
 `approved-with-edits`; scope/contract/checks halt → `rejected`.)

package/skills/yad-run/SKILL.md

@@ -31,8 +31,15 @@ signal to seed them from, so they are earned only on real runs.
 - Automation config is `skills/sdlc/config.yaml` → `automation:` (`back_steps`, `default`,
   `trust_threshold`, `locked_steps`, `kill_switch`).
 - Per-story build-half state: `epics/<epic>/.sdlc/build-state/<story-id>.json` (per repo).
-- Trust ledger: `epics/<epic>/.sdlc/trust-log.json` (append-only). Schemas:
+- Trust ledger: **shard-then-fold** — each run is its own shard file
+  `epics/<epic>/.sdlc/trust-log/<story>-<repo>-<step>-<uid>.json` (a fresh `uid` per run, so concurrent
+  writers never conflict); readers UNION the folded `trust-log.json` with every loose shard, and
+  `yad tidy up` folds finished shards back into `trust-log.json`. Schemas:
   `../yad-epic/references/state-schema.md`.
+- These machine-written back-half files (`build-state/<story>.json`, the `trust-log/` shards) are
+  committed by **`yad checkpoint`** — the back-half analogue of the front-half `yad gate` sync; the loop
+  calls it each iteration so the state is durable and shared without a human commit. (`yad checkpoint`
+  stages the shard dirs; `yad tidy up` later folds finished shards — loose objects + `git gc`.)
 - The orchestrator **calls the existing step skills unchanged** — `yad-spec` (A), `yad-implement`
   (B), `yad-checks` (C). It owns only the *advance decision*, never what a step does.
 - To see (read-only, without driving the loop) the next build sub-step per story/repo, use
@@ -59,9 +66,10 @@ Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
 
 1. **Run the step's skill** — `spec`→`yad-spec`, `tasks`→ the tasks leg of `yad-spec`,
    `implement`→`yad-implement`, `checks`→`yad-checks (action: run)`. Capture its result.
-2. **Derive trust signals & append a trust-log entry** (`ranBy: machine` if this advance was
-   automated, else `human`) — see `references/run-loop.md` for the derivation. Do this for *every*
-   step run, pass or fail; the log is the evidence base.
+2. **Derive trust signals & write a trust-log shard** — write the entry to its own file
+   `trust-log/<story>-<repo>-<step>-<uid>.json` (a fresh `uid` per run; never append to a shared file),
+   with `ranBy: machine` if this advance was automated, else `human` — see `references/run-loop.md` for
+   the derivation. Do this for *every* step run, pass or fail; the log is the evidence base.
 3. **Compute the effective dial.** Start from the step's `automation` in build-state, then **force it
    to `human_approve`** if `automation.kill_switch` is true OR the step is `locked` OR the step id is
    in `automation.locked_steps`. (So a kill switch or a lock always wins.)
@@ -76,12 +84,21 @@ Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
 5. **Always stop at `engineer-review`** (it is `locked`): hand off to `yad-engineer-review` for the human merge
    gate, which finalizes the trust verdict (confirm/override the provisional one).
 
+**Commit the machine-written state.** After each iteration's writes (the trust-log shard in 2 and the
+build-state change in 4), run `yad checkpoint --push` from `{project-root}`. It commits *only* the
+`trust-log/` shards + `build-state/<story>.json` (never a front-half gate file) as one `chore(hub): …`
+audit-trail commit, and only ever on the default branch. It is a safe no-op when nothing changed, so
+call it every iteration — teammates don't review these machine writes, but CI and `yad status` on
+other machines must see current trust evidence. Never run it off the default branch (it will refuse):
+an unpushed or branch-stranded trust log quietly undermines the "earned automation" premise.
+
 ### `action: set-dial` — earn (or revert) a step's automation
 Flip `step`'s `automation` to `to` in build-state. Enforce, in order:
 - **Refuse** if `step` is in `automation.locked_steps` or is a front state or `engineer-review` —
   these can never be `machine_advance` (front-state lock, build plan §E). Report the refusal reason.
-- For `to: machine_advance`, **refuse unless the trust threshold is met**: the step's slice of
-  `trust-log.json` has `>= trust_threshold.min_runs` entries AND the fraction with
+- For `to: machine_advance`, **refuse unless the trust threshold is met**: the step's slice of the trust
+  ledger — the **union** of the folded `trust-log.json` `runs` PLUS every `trust-log/` shard, filtered to
+  this step (and repo) — has `>= trust_threshold.min_runs` entries AND the fraction with
   `verdict == "approved-unchanged"` is `>= trust_threshold.min_approved_unchanged`. If it is not met,
   report the current evidence (runs, % unchanged) and how far short it is — "it seems fine" is not
   evidence.

package/skills/yad-run/references/run-loop.md

@@ -28,17 +28,19 @@ while step is a back step (not engineer-review):
 
     signals = derive_signals(step, result)            # see "Deriving signals"
     verdict = derive_verdict(signals)                 # rejected | approved-with-edits | approved-unchanged
-    append trust-log entry { story, repo, step, automation: bs.step.automation,
-                             verdict, signals, ranBy, date }
+    uid = fresh_short_token()                          # e.g. `openssl rand -hex 4` — unique per run,
+                                                       #   never reuse; a collision would fuse two runs
+    write trust-log/<story>-<repo>-<step>-<uid>.json   # ONE shard file = ONE entry (never append to a shared file)
+      = { story, repo, step, uid, automation: bs.step.automation, verdict, signals, ranBy, date }
 
     eff = effective_dial(step, bs, cfg)               # see "Effective dial"
 
     if result is a HALT (failed / scope overrun / contract touch / ambiguous):
-        bs.step.status = "blocked"; persist; STOP and report the human action needed
+        bs.step.status = "blocked"; persist; checkpoint; STOP and report the human action needed
     elif eff == "machine_advance":
-        bs.step.status = "done"; advance bs.currentStep to next; persist; continue   # Step B advance
+        bs.step.status = "done"; advance bs.currentStep to next; persist; checkpoint; continue  # Step B advance
     else:  # human_approve
-        bs.step.status = "done"; persist; STOP and report "waiting for human at <next>"
+        bs.step.status = "done"; persist; checkpoint; STOP and report "waiting for human at <next>"
 
 # reached engineer-review: always stop, hand to yad-engineer-review (human gate, finalizes the verdict)
 ```
@@ -47,6 +49,18 @@ while step is a back step (not engineer-review):
 nudge; otherwise `human`. Persist build-state after every transition so a halt leaves an accurate,
 resumable record.
 
+`checkpoint` = run `yad checkpoint --push` from `{project-root}`. It commits the machine-written
+back-half ledgers (in this loop, the loose `trust-log/` shards this run wrote + `build-state/<story>.json`;
+also the `build-log/` shards at engineer-review) — the shard dirs are what checkpoint stages, the same
+way `git gc` folds loose objects later (`yad tidy up` folds finished shards into the folded
+`trust-log.json` / `build-log.json`) — as one `chore(hub): sync back-half state — <epic>/<story> by @<login> [skip ci]`
+audit-trail commit, on the default branch only,
+staging *only* those files by an explicit allowlist (never a front-half gate file — so `ledger-guard`
+never trips). It is idempotent (a no-op when nothing changed), so calling it after every transition —
+including a halt — is safe and keeps the shared trust evidence current for CI, teammates, and
+`yad status` on other machines. It refuses to run off the default branch (an unsigned `[skip ci]`
+commit inside a future PR range would fail `verified-commits` and strand the PR).
+
 ## Effective dial (kill switch & locks always win)
 
 ```
@@ -100,7 +114,10 @@ A step is a **candidate** for `machine_advance` only when its trust evidence cle
 to `machine_advance`:
 
 ```
-slice = trust-log entries for this step (this story's repo; widen to the project if you track it there)
+# read the ledger by UNION: the folded trust-log.json `runs` array PLUS every loose trust-log/ shard
+# (concatenate — every shard is a distinct run; never dedup by story/repo/step, the threshold counts re-runs)
+all   = trust-log.json.runs + [read each file in trust-log/]
+slice = entries in `all` for this step (this story's repo; widen to the project if you track it there)
 runs  = len(slice)
 unchanged = count(e.verdict == "approved-unchanged" in slice)
 earned = runs >= trust_threshold.min_runs

package/skills/yad-spec/SKILL.md

@@ -101,9 +101,10 @@ verdict is **anchored to the human who accepts the spec**, never self-graded:
   `human_edited_spec: true`);
 - the spec is rejected or the ceremony re-run → `rejected`.
 `yad-run` records a provisional entry when the spec is generated; this acceptance finalizes it (same
-pattern as the engineer review finalizing `implement` at `yad-engineer-review`). Append the finalized entry to
-`epics/<epic>/.sdlc/trust-log.json` (schema:
-`../yad-epic/references/state-schema.md`). **Run standalone, no trust entry is written** — the
+pattern as the engineer review finalizing `implement` at `yad-engineer-review`). Write/finalize the
+entry in its own shard `epics/<epic>/.sdlc/trust-log/<story>-<repo>-spec-<uid>.json` (a fresh `uid` per
+run; readers union the folded `trust-log.json` + the loose shards). Schema:
+`../yad-epic/references/state-schema.md`. **Run standalone, no trust entry is written** — the
 log measures orchestrated runs. `spec` stays `human_approve` until its slice clears the threshold;
 this step only *gathers* the evidence, it does not flip the dial.
 

package/skills/yad-status/SKILL.md

@@ -21,7 +21,12 @@ report all if the user asked for an overview).
 ### Step 2 — Read state
 Read `.sdlc/state.json`, `.sdlc/approvals.json`, `epic.md` frontmatter (for `repos`), and — if present
 — `.sdlc/contract-lock.json`. For the build half (Phase 4), also read — if present — every
-`.sdlc/build-state/<story-id>.json`, `.sdlc/trust-log.json`, and the `automation` block of
+`.sdlc/build-state/<story-id>.json`, and the trust ledger read as the **union** of the folded
+`.sdlc/trust-log.json` `runs` PLUS every loose `.sdlc/trust-log/` shard (concatenate — every shard is a
+distinct run; never dedup by story/repo/step — but DO skip a shard whose full identity
+`(story,repo,step,uid)` already appears in the folded `runs`, i.e. a half-applied `yad tidy up`). All are committed by `yad checkpoint` (so a fresh clone
+or another machine sees current evidence; `yad tidy up` folds finished shards into `trust-log.json`).
+Also read the `automation` block of
 `skills/sdlc/config.yaml` (`back_steps`, `trust_threshold`, `locked_steps`, `kill_switch`). For the
 cross-cutting learning layer, also read — if present — the **local-only** `.sdlc/learning-records.json`
 (the per-epic learning ledger, gitignored) and the project-wide `{project-root}/.sdlc/learning-records.json`.
@@ -72,8 +77,9 @@ Print, in this order:
    reads the same `build-state` files.)
 8. **Automation & trust** — print the system-wide **kill switch** state from `config.yaml`
    `automation.kill_switch` (when `on`, note that every step is forced to `human_approve`). Then, for
-   each back-half step that has entries in `.sdlc/trust-log.json`, print its **trust record**: number
-   of runs, the fraction with `verdict == "approved-unchanged"`, and whether that clears
+   each back-half step that has entries in the trust ledger — the **union** of the folded
+   `.sdlc/trust-log.json` `runs` plus every loose `.sdlc/trust-log/` shard — print its **trust record**:
+   number of runs, the fraction with `verdict == "approved-unchanged"`, and whether that clears
    `automation.trust_threshold` (`min_runs`, `min_approved_unchanged`) — i.e. whether the step is
    **earned** (eligible to be flipped to `machine_advance`) or still **gathering evidence**. Restate
    the predicate (self-contained): `earned = runs >= min_runs AND unchanged/runs >= min_approved_unchanged`.