yadflow 3.12.2 → 3.13.1

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## [3.13.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.13.0...v3.13.1) (2026-07-29)
+
+
+### Bug Fixes
+
+* **checks:** apply the Task-trailer rule to the thread gates too ([18aed8d](https://github.com/abdelrahmannasr/yadflow/commit/18aed8df958718483fe929cea84275ca86ae67be)), closes [#157](https://github.com/abdelrahmannasr/yadflow/issues/157)
+* **checks:** do not build a /-rooted lock path when product-repo is absent ([0d2a214](https://github.com/abdelrahmannasr/yadflow/commit/0d2a214a30c7fc31ad087fa127277b50637a00de))
+* **checks:** keep product-repo resolution backward-compatible and loud ([4c00c92](https://github.com/abdelrahmannasr/yadflow/commit/4c00c928642fbab4517805be14a1c6926f41b84c)), closes [#149](https://github.com/abdelrahmannasr/yadflow/issues/149) [#149](https://github.com/abdelrahmannasr/yadflow/issues/149)
+* **checks:** resolve link.md product-repo the same way in every gate ([47c9b30](https://github.com/abdelrahmannasr/yadflow/commit/47c9b30548153ef5be607cf760c3e9ec9e73699f)), closes [#149](https://github.com/abdelrahmannasr/yadflow/issues/149)
+* **checks:** spec-link resolves a Task trailer even on a maintenance commit ([d24dd83](https://github.com/abdelrahmannasr/yadflow/commit/d24dd83abadc63bb00e8c8d6d7c6008e32344db8)), closes [#157](https://github.com/abdelrahmannasr/yadflow/issues/157)
+* **doctor:** refuse a decorative contract lock, and report a gate that went stale ([1ee3296](https://github.com/abdelrahmannasr/yadflow/commit/1ee3296dbddfdd308949b8013b3bf678f638fc80)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** bound the review-branch probe so it can never hang gate open ([afa5416](https://github.com/abdelrahmannasr/yadflow/commit/afa54167efd5879537c4bc19ab29531fe08ed31b))
+* **gate:** hash the contract surface exactly as the documented recipe does ([f29e781](https://github.com/abdelrahmannasr/yadflow/commit/f29e78183b92c7baf33b46dbdfa7a4776aa06e4e)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** keep the recorded PR entry when --pr names that same PR ([b1febe1](https://github.com/abdelrahmannasr/yadflow/commit/b1febe184278109f0bafc2968648da362d68483a))
+* **gate:** make a merged review PR reachable by hand ([4ccbd17](https://github.com/abdelrahmannasr/yadflow/commit/4ccbd1736640935175d63bac15a01a94e381b44e)), closes [#158](https://github.com/abdelrahmannasr/yadflow/issues/158)
+* **gate:** never drop a done step's approval record on re-sync ([1a5e434](https://github.com/abdelrahmannasr/yadflow/commit/1a5e4348d00edd4e775a735a49fc0a86a3f0e391)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** re-bind approvals recorded before PR provenance existed ([6b7e816](https://github.com/abdelrahmannasr/yadflow/commit/6b7e816638a329d9365c6e727b2c12debdbd24aa)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156) [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** re-sync a re-opened review so its approvals re-bind ([28eabd2](https://github.com/abdelrahmannasr/yadflow/commit/28eabd222214ad2af7d18ef20c56795c9eb171d1)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** require the review branch on origin, and check before writing state ([27f0d92](https://github.com/abdelrahmannasr/yadflow/commit/27f0d92ce680c26df6ea7ff6510879a11f05d00f)), closes [#158](https://github.com/abdelrahmannasr/yadflow/issues/158)
+* **gate:** stop a done-step re-sync from churning the ledger ([68462a6](https://github.com/abdelrahmannasr/yadflow/commit/68462a622753c0d30b458d22d9e1ad890ad8e61f)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** validate --pr and confirm it names this artifact's review ([f5d7773](https://github.com/abdelrahmannasr/yadflow/commit/f5d7773da474784a43cc3e24298da94c8f38bbdb)), closes [#7](https://github.com/abdelrahmannasr/yadflow/issues/7) [#158](https://github.com/abdelrahmannasr/yadflow/issues/158)
+* **hub-bridge:** serialize the GitLab gate-sync job ([4294979](https://github.com/abdelrahmannasr/yadflow/commit/4294979f80cb4491d074fe27e74f9af454a2f62a)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+
+# [3.13.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.12.2...v3.13.0) (2026-07-14)
+
+
+### Features
+
+* **checkpoint:** add --retro-ship to reconcile pre-tracking shipped stories ([#142](https://github.com/abdelrahmannasr/yadflow/issues/142)) ([d7988a3](https://github.com/abdelrahmannasr/yadflow/commit/d7988a335da7d675dd7b53456c12610c3f442d97)), closes [#112](https://github.com/abdelrahmannasr/yadflow/issues/112) [#112](https://github.com/abdelrahmannasr/yadflow/issues/112)
+
 ## [3.12.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.12.1...v3.12.2) (2026-07-14)
 
 

package/bin/yad.mjs

@@ -74,8 +74,13 @@ ${c.bold('Where am I / what next')}
                                        --undo reverses it until the stories review opens
 
 ${c.bold('Review gate (front half)')}
-  yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review
-  yad gate sync <epic> [artifact]      Pull PR state -> ledger; advance on approved+resolved+merged
+  yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review. The review
+                                       branch must already be on origin (it is never created here)
+  yad gate sync <epic> [artifact] [--pr <n>]
+                                       Pull PR state -> ledger; advance on approved+resolved+merged.
+                                       With no recorded PR, resolves it from the review branch; --pr
+                                       names one (and overrides a stale recorded pointer). Advisory
+                                       in bridge mode — there, recover with 'yad gate ci' below
   yad gate comments <epic> [artifact]  Fetch unresolved review comments to address
   yad gate status <epic>               Show each review step + approvals
   yad gate repair <epic> [--push]      Close an author step stranded behind a passed review gate
@@ -101,6 +106,10 @@ ${c.bold('Build helpers')}
                                        status: flip (→ in-build/shipped) backed by a build-log
                                        ship — as one audit-trail chore(hub) commit; default
                                        branch only (--allow-branch to override); no-op when clean
+  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.)
   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"
@@ -155,7 +164,7 @@ ${c.bold('Environment')}
   YAD_NO_UPDATE_NOTIFIER=1   Silence the "update available" notice (also off in CI)
   YAD_NO_REPORT=1            Never offer to file a bug report after a failure`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--retro-ship', '--merge-commit']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -268,7 +277,7 @@ async function main() {
       // advisory (reads the platform, prints status, writes nothing). The artifact status flip is
       // CI's job at merge — never wired into the local gate. File-only mode keeps local writes.
       if (action === 'open') await gateOpen(o.dir, { epic, artifact });
-      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, local: true });
+      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, number: o.pr, local: true });
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
       else if (action === 'status') await gateStatus(o.dir, { epic });
       else if (action === 'repair') await gateRepair(o.dir, { epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun });
@@ -301,9 +310,20 @@ 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 });
+    case 'checkpoint': {
+      let retroShip;
+      if (o['retro-ship']) {
+        const [epic, story] = String(o['retro-ship']).split('/');
+        if (!epic || !isValidEpicId(epic)) { log(c.red(`invalid --retro-ship: expected <epic>/<story> with epic EP-<slug> (got ${o['retro-ship']})`)); process.exitCode = 1; break; }
+        // The story id becomes a path element (stories/<story>.md) — pin it to the id shape (and to its
+        // own epic) so a `..` or a slash can never traverse out of the epic's stories dir, and a typo'd
+        // cross-epic id is caught here rather than failing obscurely later.
+        if (!story || !/^EP-[a-z0-9-]+-S\d+$/.test(story) || !story.startsWith(`${epic}-S`)) { log(c.red(`invalid --retro-ship: expected <epic>/<story> with story <epic>-S<NN> (got ${o['retro-ship']})`)); process.exitCode = 1; break; }
+        retroShip = { epic, story, repo: o.repo, task: o.task, mergeCommit: o['merge-commit'], today };
+      }
+      await runCheckpoint(o.dir, { push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, retroShip });
       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; }

package/cli/checkpoint.mjs

@@ -27,7 +27,7 @@ import { PROJECT_FILES } from './manifest.mjs';
 import { loadHub } from './gate.mjs';
 import { resolveCommitterLogin } from './platform.mjs';
 import { hubGit, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
-import { readShips } from './ledger.mjs';
+import { readShips, writeRetroShip } from './ledger.mjs';
 import { readFrontmatter } from './epic-state.mjs';
 
 // The machine-written back-half ledgers, relative to an epic's dir. The two append-only logs are
@@ -166,6 +166,48 @@ export function stagedStoryIsStatusOnly(git, file) {
   return changes > 0;
 }
 
+// --retro-ship orchestration (#142): validate the target, then write the retroactive ship shard so the
+// normal checkpoint path carries the story's already-made `status:` flip. Returns { ok, file } — ok:false
+// (with a printed reason) aborts the commit; `file` is the shard just written, so a dry run can delete it
+// and leave no side effect. Does NOT author the story frontmatter — it only supplies the missing
+// evidence, and the human must have ALREADY flipped `status:` to a back-half value in the working tree.
+export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, today }) {
+  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);
+  const storyRel = path.posix.join('epics', epic, 'stories', `${story}.md`);
+  const storyFile = path.join(epicDir, 'stories', `${story}.md`);
+  if (!exists(epicDir)) { fail(`no epic ${epic} under epics/`); return { ok: false }; }
+  if (!exists(storyFile)) { fail(`no story ${story} under epics/${epic}/stories/`); return { ok: false }; }
+
+  // Evidence and the flip must land TOGETHER — the #112 no-drift invariant. Refuse unless the human has
+  // already flipped the story frontmatter to a back-half status in the working tree; otherwise the ship
+  // shard would commit while the artifact still says e.g. `approved` — the very drift #112 prevents.
+  if (!BACK_HALF_STATUSES.has(readFrontmatter(storyFile).status)) {
+    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`);
+    return { ok: false };
+  }
+
+  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`);
+    return { ok: false };
+  }
+  ok(`recorded retroactive ship for ${story} (${repo})${mergeCommit ? ` @ ${mergeCommit}` : ''}`);
+  return { ok: true, file: res.file };
+}
+
+// Undo a retro shard a dry run wrote so the preview leaves NO side effect: delete the shard, and if its
+// `.sdlc/build-log/` dir was created just for it (now empty), drop that too. Best-effort — a non-empty
+// dir (pre-existing shards) or a benign rmdir race is ignored.
+function cleanupRetroShard(file) {
+  fs.rmSync(file, { force: true });
+  try { fs.rmdirSync(path.dirname(file)); } catch { /* not empty / already gone — leave it */ }
+}
+
 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; }
@@ -183,6 +225,17 @@ export async function runCheckpoint(root, opts = {}) {
   // Default-branch guard (invariant 2) — shared with `yad tidy up`.
   if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad checkpoint' })) return;
 
+  // --retro-ship (#142): record a retroactive build-log ship for a PRE-TRACKING story (merged before
+  // the back-half ledger existed, so it has no ship and its `status:` flip can't be carried). Done
+  // AFTER the branch guard so we never leave a dangling shard on the wrong branch; the flip the human
+  // already wrote is then carried by the normal storyStatusPathspecs path below — no raw git needed.
+  let retroFile;
+  if (opts.retroShip) {
+    const r = recordRetroShip(root, opts.retroShip);
+    if (!r.ok) { process.exitCode = 1; return; }
+    retroFile = r.file;
+  }
+
   // 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)];
@@ -224,6 +277,9 @@ export async function runCheckpoint(root, opts = {}) {
   if (opts.dryRun) {
     log('\n' + c.dim(message) + '\n');
     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);
     info('dry run — not committed');
     return { message };
   }
@@ -231,6 +287,8 @@ export async function runCheckpoint(root, opts = {}) {
   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
+    // The retro shard stays on disk (untracked) — a follow-up `yad checkpoint` picks it up and carries
+    // the flip; re-running `--retro-ship` would refuse ("already has a build-log ship").
     fail(`git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
     process.exitCode = 1;
     return { message };

package/cli/doctor.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, hand, run, has, exists, readJSON, readJSONStrict } from './lib.mjs';
 import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS } from './manifest.mjs';
-import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread, stateInvariants } from './epic-state.mjs';
+import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread, stateInvariants, contractSurfaceHash, artifactHash } from './epic-state.mjs';
 import { loadDebt } from './thread.mjs';
 import { gitHead, insideWorkspace } from './setup.mjs';
 import { cliFor, validateLogin, hostFromGitUrl } from './platform.mjs';
@@ -280,6 +280,116 @@ export function ciTagsChecks(checks, root, hub, registry) {
   }
 }
 
+// Is `.sdlc/contract-lock.json` still the hash of the surface it claims to lock? The lock is what the
+// spec pins and what contract-check compares a code repo's slice against, but nothing ever verified it
+// against the live contract.md — so a surface edited without a re-lock (or locked with a different
+// recipe) read as "locked" while binding nothing. FAIL on a mismatch: a decorative lock is worse than
+// none, because everyone downstream treats it as proof.
+//
+// Two shapes (yad-change references/triage.md): a SURFACE lock, verified against this epic's own
+// contract.md, and a POINTER lock — a change-epic that inherited architecture, which carries no
+// contract.md at all and instead copies the parent's hash verbatim. Its integrity property is that the
+// copy still equals what the referenced lock holds, so verify it there.
+function contractLockCheck(checks, root, epic, ledger) {
+  const id = `epic:${epic}:contract-lock`;
+  const lock = ledger.contractLock;
+  const epicDir = epicRoot(root, epic);
+  // An epic that has not reached the lock yet simply has no lock file — that is the normal pre-lock
+  // state and stays silent. A lock file that EXISTS but carries no usable hash is the opposite: it is
+  // the decorative lock this check was added to catch, so it must never read as "not locked yet".
+  // `readJSONStrict` yields null both for an absent file and for one holding literal `null`, so ask the
+  // filesystem — the second is a malformed lock, not a missing one.
+  if (lock === null && !exists(ledger.files.contractLock)) return;
+  const stored = typeof lock?.hash === 'string' && /^sha256:[0-9a-f]{64}$/.test(lock.hash) ? lock.hash : null;
+  if (!stored) {
+    check(checks, id, 'epics', 'fail',
+      `${epic}: contract-lock.json exists but carries no usable sha256 hash`,
+      're-lock the surface (yad-architecture Step 5) or delete the file — a lock nobody can verify is worse than none');
+    return;
+  }
+  const short = (h) => `${h.slice(0, 19)}…`;
+
+  if (lock.inheritedFrom || lock.ref) {
+    // The ref is repo-controlled text, so keep it inside this hub's epics/ — a lock file must not be
+    // able to point the check at arbitrary JSON elsewhere on disk.
+    const epicsDir = path.join(root, 'epics');
+    const refPath = path.resolve(path.join(epicDir, '.sdlc'), lock.ref || `../../${lock.inheritedFrom}/.sdlc/contract-lock.json`);
+    if (refPath !== epicsDir && !refPath.startsWith(epicsDir + path.sep)) {
+      check(checks, id, 'epics', 'fail',
+        `${epic}: pointer-lock ref '${lock.ref}' resolves outside epics/`,
+        'a pointer-lock must reference another epic in this hub — fix `ref` (yad-change writes ../../EP-<parent>/.sdlc/contract-lock.json)');
+      return;
+    }
+    const parent = readJSON(refPath, null);
+    if (!parent || typeof parent.hash !== 'string') {
+      check(checks, id, 'epics', 'fail',
+        `${epic}: pointer-lock references ${lock.inheritedFrom || lock.ref}, whose contract-lock.json is missing or has no hash`,
+        're-thread the change-epic (yad-change) so it points at a real parent lock');
+      return;
+    }
+    if (parent.hash !== stored) {
+      check(checks, id, 'epics', 'fail',
+        `${epic}: pointer-lock pins ${short(stored)} but ${lock.inheritedFrom || 'its parent'} now locks ${short(parent.hash)}`,
+        'the inherited surface was re-locked upstream — re-copy the parent hash, or re-author architecture in this epic');
+      return;
+    }
+    // A pointer-lock epic has no contract.md by construction (the surface physically cannot drift).
+    // One that DOES have a contract.md is a change-epic that re-authored architecture but left the
+    // inherited fields behind, so verify the live surface as well rather than trusting the pointer.
+    if (!exists(path.join(epicDir, 'contract.md'))) {
+      check(checks, id, 'epics', 'ok', `${epic}: pointer-lock matches ${lock.inheritedFrom || 'its parent'} (${short(stored)})`);
+      return;
+    }
+    check(checks, `${id}:inherited`, 'epics', 'warn',
+      `${epic}: lock is marked inherited from ${lock.inheritedFrom || lock.ref} but this epic has its own contract.md`,
+      're-authored architecture? drop `inheritedFrom`/`ref` and re-lock against this epic\'s surface');
+    // and fall through to verify the live surface too
+  }
+
+  if (!exists(path.join(epicDir, 'contract.md'))) {
+    check(checks, id, 'epics', 'fail',
+      `${epic}: contract-lock.json pins ${short(stored)} but there is no contract.md to lock`,
+      'restore contract.md, or record the lock as inherited (`inheritedFrom` + `ref`) if this epic threads off a parent');
+    return;
+  }
+  const current = contractSurfaceHash(epicDir);
+  if (current === null) {
+    check(checks, id, 'epics', 'fail',
+      `${epic}: contract-lock.json pins ${short(stored)} but contract.md has no readable CONTRACT-SURFACE block`,
+      'restore the BEGIN/END markers around the surface, then re-lock (see yad-architecture Step 5)');
+    return;
+  }
+  if (current !== stored) {
+    check(checks, id, 'epics', 'fail',
+      `${epic}: contract surface drifted from its lock — contract.md hashes ${short(current)}, contract-lock.json pins ${short(stored)}`,
+      'the surface changed without a re-lock: re-run the yad-architecture Step 5 recipe and re-open the architecture gate');
+    return;
+  }
+  check(checks, id, 'epics', 'ok', `${epic}: contract surface matches its lock (${short(stored)})`);
+}
+
+// A review step that is `done` but whose approvals no longer bind to the artifact as it stands today.
+// The gate is deliberately one-way — nothing pulls a chain backward once work is built on it — so the
+// only way this surfaces is if something reports it. `gate sync` records the gap on the step it is
+// syncing; this reports it for the whole epic, so a re-locked surface that was never re-approved is
+// visible in the one command people run when something looks wrong. WARN, not FAIL: the state is a
+// fact about history, and the fix (re-open the review) is a human decision.
+function staleGateCheck(checks, root, epic, ledger) {
+  const epicDir = epicRoot(root, epic);
+  for (const s of ledger.state.steps) {
+    if (s.type !== 'review+approve' || s.status !== 'done' || s.inherited || s.skipped) continue;
+    const cur = artifactHash(epicDir, s.artifact);
+    if (!cur) continue; // nothing to bind to (no locked surface / incomplete set) — not a staleness claim
+    const forStep = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved');
+    if (!forStep.length) continue; // solo mode waives approvals entirely; absence is not staleness
+    const live = forStep.filter((a) => !a.artifactHash || a.artifactHash === cur);
+    if (live.length) continue;
+    check(checks, `epic:${epic}:${s.id}:stale`, 'epics', 'warn',
+      `${epic}: ${s.id} is done, but all ${forStep.length} approval(s) are bound to an older ${s.artifact}`,
+      'the artifact changed after it was approved — re-open the review (a fresh PR/MR) so the record matches what shipped');
+  }
+}
+
 export function epicChecks(checks, root) {
   const epicsDir = path.join(root, 'epics');
   if (!exists(epicsDir)) return;
@@ -308,6 +418,8 @@ export function epicChecks(checks, root) {
         if (openPr) check(checks, `epic:${e}:migration`, 'epics', 'warn',
           `${e}: an open review PR (${openPr.artifact}${openPr.number ? ` #${openPr.number}` : ''}) is recorded on the default branch`,
           'opened under a pre-3.0 yadflow? merge/close it before continuing — CI now records the gate ledger on the default branch only at merge');
+        contractLockCheck(checks, root, e, ledger);
+        staleGateCheck(checks, root, e, ledger);
       }
     } catch (err) {
       check(checks, `epic:${e}`, 'epics', 'fail', `${e}: ${err.message} [${err.code || 'YAD-STATE-001'}]`, err.hint || 'fix the file or restore it from git');

package/cli/epic-state.mjs

@@ -57,11 +57,19 @@ export function upsertHubPr(hubPrs = [], rec) {
   return [...hubPrs.filter((p) => p.artifact !== rec.artifact), rec];
 }
 
-// SHA-256 of the contract surface block (architecture only). Mirrors
-// yad-architecture/references/contract-format.md (awk markers + sha256).
-// Line endings are normalized to LF so the same surface hashes identically across
-// platforms (a CRLF re-save must not revoke approvals). A BEGIN without an END is
-// malformed and yields null — never a silent hash of everything to end-of-file.
+// SHA-256 of the contract surface block (architecture only). Byte-for-byte identical to the recipe
+// yad-architecture/references/contract-format.md publishes — the one the architect runs to write
+// contract-lock.json:
+//
+//   awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' contract.md \
+//     | tr -d '\r' | shasum -a 256
+//
+// Canonicalization, in the order awk applies it: every line strictly between the markers, CRLF
+// normalized to LF (so a CRLF re-save never revokes approvals), joined by LF, and TERMINATED by a
+// trailing LF — awk emits a newline after every line it prints, so that last newline is part of the
+// hashed bytes. Omitting it made the CLI digest and the documented recipe disagree by exactly one
+// byte on every surface, so contract-lock.json could never equal what approvals bind to (issue #156).
+// A BEGIN without an END is malformed and yields null — never a silent hash of everything to EOF.
 export function contractSurfaceHash(epicDir) {
   const file = path.join(epicDir, 'contract.md');
   if (!fs.existsSync(file)) return null;
@@ -75,7 +83,7 @@ export function contractSurfaceHash(epicDir) {
     if (inside) body.push(ln);
   }
   if (!terminated || !body.length) return null;
-  return 'sha256:' + createHash('sha256').update(body.join('\n')).digest('hex');
+  return 'sha256:' + createHash('sha256').update(body.join('\n') + '\n').digest('hex');
 }
 
 // Deterministic fingerprint of the whole stories/ set: hash each story file, sort, combine. Lets an