yadflow 3.12.1 → 3.13.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* **checks:** waive verified-commits signature for content-free merge commits ([1e73837](https://github.com/abdelrahmannasr/yadflow/commit/1e738372f821e93020069b565d40315cd7be2591)), closes [#138](https://github.com/abdelrahmannasr/yadflow/issues/138)
+
 ## [3.12.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.12.0...v3.12.1) (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.1",
+  "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-checks/references/check-gates.md

@@ -93,6 +93,13 @@ repo. For each commit in `<base>..HEAD`, two independent checks:
   (2+ parents) — a merge's author is whoever pressed merge (often a platform noreply), not a roster
   human, and its content already passed the PR gate suite. This waiver matters for the push-on-default
   `yad-update-guard` (§9), which — unlike this PR-triggered gate — sees merge commits.
+  A merge commit is **additionally signature-waived when it introduces no content of its own** (its
+  combined diff — `git diff-tree --cc` — is empty, i.e. no conflict-resolution or evil-merge hunks):
+  every change it carries already lives in an individually author+signature-checked parent, so there
+  is nothing to protect. This unblocks **self-hosted GitLab**, which does not sign UI-created merge
+  commits (the signature API returns 404) — without it every routine merge would red the branch. A
+  merge that *does* introduce content of its own still requires a verified signature (fail-closed),
+  so an evil merge pushed direct-to-default cannot smuggle in unverified changes.
 
 Degradation is explicit, never silent: a missing allowlist SKIPs the author check with a warning
 (configure roster emails, re-wire); no GitHub/GitLab remote SKIPs the signature check (the badge is a

package/skills/yad-checks/templates/checks/verified-commits.sh

@@ -11,6 +11,12 @@
 # commits set the platform itself as the committer (e.g. noreply@github.com), and their integrity is
 # covered by the signature check (the platform signs them).
 #
+# Merge-commit signature exemption: a merge that introduces NO content of its own (its combined diff
+# is empty — no conflict-resolution / evil-merge hunks) is signature-waived, because every change it
+# carries already lives in its individually author+signature-checked parents. This unblocks self-hosted
+# GitLab, which does not sign UI-created merge commits (the signature API returns 404). A merge that
+# DOES introduce content of its own still requires a verified signature (fail-closed).
+#
 # Degradation is explicit, never silent:
 #   - no allowlist file        -> author check SKIPPED with a warning (configure emails, re-wire)
 #   - no GitHub/GitLab remote  -> signature check SKIPPED with a warning (no platform, no badge)
@@ -88,6 +94,19 @@ signature_verified() {
   esac
 }
 
+# 0 when a merge commit introduced NO content of its own. The combined diff (--cc) lists only hunks
+# that differ from ALL parents, so empty output means every change lives in an individually-checked
+# parent — there is no conflict-resolution or evil-merge content unique to the merge commit, hence
+# nothing an unverified author could smuggle in past the per-parent author+signature checks.
+merge_introduces_no_content() {
+  # `local` on its own line: `local out=$(...)` would mask the substitution's exit status (local
+  # always returns 0). A git error (e.g. a parent tree missing in a shallow clone) must fail closed —
+  # an empty stdout from a *failed* command is not evidence the merge is content-free.
+  local out
+  out="$(git diff-tree --cc --no-commit-id -r "$1")" || return 1
+  [ -z "$out" ]
+}
+
 rc=0
 while IFS= read -r sha; do
   [ -z "$sha" ] && continue
@@ -126,6 +145,11 @@ while IFS= read -r sha; do
   if [ -n "$platform" ]; then
     if signature_verified "$sha"; then
       echo "PASS [verified-commits]: ${short} signature verified by ${platform}"
+    elif [ "$is_merge" = 1 ] && merge_introduces_no_content "$sha"; then
+      # Content-free merge: nothing to protect. Self-hosted GitLab does not sign UI merge commits, so
+      # requiring a signature here would block every routine merge. An evil merge (content of its own)
+      # falls through to FAIL below.
+      echo "WARN [verified-commits]: ${short} unsigned merge commit — introduces no content of its own (covered by verified parents); signature waived. (Self-hosted GitLab does not sign UI merge commits; on a platform that signs its merges an unsigned content-free merge is unusual but still harmless.)"
     else
       echo "FAIL [verified-commits]: ${short} signature missing/unverified — sign commits (GPG/SSH key registered on ${platform}), or the signature API was unreachable (GitLab: set GITLAB_TOKEN/SDLC_API_TOKEN with read_api)."
       rc=1

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