yadflow 3.12.2 → 3.13.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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

@@ -101,6 +101,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 +159,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' };
@@ -301,9 +305,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/ledger.mjs

@@ -79,6 +79,32 @@ export function readShips(epicDir) {
   return [...byKey.values()];
 }
 
+// Record a RETROACTIVE ship for a pre-tracking story — one merged & shipped before the back-half
+// ledger existed, so it has no build-log ship and `yad checkpoint` can't carry its `status:` flip
+// (issue #142). Writes ONE minimal ship shard, marked `retroactive: true`, so `readShips` now proves
+// the story shipped and checkpoint carries the human's already-made flip. It is NOT a fabricated real
+// ship: `task` defaults to the sentinel `retro`, `mergeCommit` is written only when the caller supplies
+// it (never invented), and `shippedAt` is the backfill date (the `retroactive` flag marks it as such).
+//
+// Guard: refuse when the story ALREADY has ANY build-log ship — then it isn't pre-tracking and the
+// normal ship/checkpoint flow applies; a retro record would only muddy the ledger. Returns
+// { written: false, reason } in that case, else { written: true, file, ship }.
+export function writeRetroShip(epicDir, { story, repo, task = 'retro', mergeCommit, shippedAt }) {
+  if (!story) throw new Error('writeRetroShip: story is required');
+  if (!repo) throw new Error('writeRetroShip: repo is required');
+  if (readShips(epicDir).some((s) => s.story === story)) {
+    return { written: false, reason: 'exists' };
+  }
+  const t = task || 'retro';
+  const ship = { story, task: t, repo, retroactive: true, note: 'pre-tracking backfill' };
+  if (mergeCommit) ship.mergeCommit = mergeCommit;
+  if (shippedAt) ship.shippedAt = shippedAt;
+  const f = epicFiles(epicDir);
+  const file = path.join(f.buildLogDir, buildShardName({ story, task: t, repo }));
+  writeJSON(file, ship);
+  return { written: true, file, ship };
+}
+
 // 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.12.2",
+  "version": "3.13.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/references/ship-and-record.md

@@ -66,6 +66,26 @@ not by hand: after recording the ship, `yad checkpoint --push` lands the new `bu
 `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.
 
+### Retroactive ship — a pre-tracking story (#142)
+
+A story that was merged and shipped **before** the back-half ledger existed has no build-log ship, so
+`yad checkpoint` can't carry its `status: shipped` flip (the flip is only carried when a ship backs it,
+#112) — leaving a raw `git push origin main` as the only way to land it, against the never-raw-git
+convention. To reconcile it through yad, record a **retroactive** ship, then checkpoint carries the flip
+in the same commit:
+
+```
+yad checkpoint --retro-ship <epic>/<story> --repo <r> [--task <t>] [--merge-commit <sha>] [--push]
+```
+
+It writes ONE minimal ship shard marked `retroactive: true` (`task` defaults to the sentinel `retro`;
+`mergeCommit` is written only if you pass `--merge-commit`; `shippedAt` is the backfill date), then runs
+the normal checkpoint so the story's already-made `status:` flip rides along in the **same** commit. It
+refuses when the story already has a real ship (then it isn't pre-tracking — use the normal flow). It
+does **not** author the story frontmatter — and to keep evidence and the flip atomic (the no-drift
+invariant), it **refuses** unless you have already set `status: shipped` in `stories/<story>.md`, so a
+ship shard is never committed while the artifact still says `approved`.
+
 **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)
 (`yad review trailer/context/nudge`, a real trailer/cards/chat session over the diff), `none` for a bare