yadflow 3.9.0 → 3.9.2

package/CHANGELOG.md

@@ -1,14 +1,9 @@
-# [3.9.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.8.1...v3.9.0) (2026-07-05)
+## [3.9.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.9.1...v3.9.2) (2026-07-06)
 
 
 ### Bug Fixes
 
-* **cli:** retry the publish push when the index is unchanged; note the registry in docs ([55209c0](https://github.com/abdelrahmannasr/yadflow/commit/55209c01e50e3a635e7311acd1ad10e8c61c5534))
-
-
-### Features
-
-* **cli:** add `yad repo refresh --push` to publish code-map refresh to the hub ([0e3697d](https://github.com/abdelrahmannasr/yadflow/commit/0e3697d0be4ec5d11c300be9b02e04468f07ba8c))
+* validate explicit --task id format in yad commit ([e3b0527](https://github.com/abdelrahmannasr/yadflow/commit/e3b05276b951dbeab6ce6bcb135e8228f73ede9d))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/bin/yad.mjs

@@ -89,9 +89,10 @@ ${c.bold('Build helpers')}
                                        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
+                                       (trust-log/build-log/build-state) — plus any story
+                                       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 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"
@@ -123,7 +124,7 @@ ${c.bold('Options')}
   --dir <path>          Target project root (default: cwd)
   --type <t>            commit: feat|fix|docs|refactor|test|perf|build|ci|chore|revert
   -m, --message <s>     commit: subject / PR title
-  --task <id>           commit: Task trailer (else derived from the branch)
+  --task <id>           commit: Task trailer, a <story>-T<NN> id (else derived from the branch)
   --ai <id>             commit: co-author — claude|copilot|cursor|coderabbit|none (default none)
   --contract-change     commit/open-pr: mark the contract surface touched
   --risk <level>        open-pr: low|medium|high (default low)

package/cli/checkpoint.mjs

@@ -4,10 +4,19 @@
 // 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.
 //
+// It also carries the back-half story `status:` flip (approved → in-build/shipped) that
+// yad-engineer-review writes into stories/<id>.md but no command committed — the #112 drift where
+// build-log said shipped while the story artifact still said approved. Only story files with build-log
+// ship evidence are carried (storyStatusPathspecs), AND only when their staged change is the `status:`
+// line alone (stagedStoryIsStatusOnly) — so it stays a back-half record, never a raw edit that would
+// slip prose onto the default branch under a `[skip ci]` commit that bypasses review.
+//
 // 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.
+//   1. It stages ONLY the back-half ledgers + build-log-backed story flips 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. (ledger-guard does NOT
+//      protect stories/*.md, and this commits to the default branch, never a PR range, so the carried
+//      story flip is safe.)
 //   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.
@@ -18,6 +27,8 @@ 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 { readFrontmatter } from './epic-state.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 —
@@ -44,6 +55,50 @@ export function backHalfPathspecs(root) {
   return out;
 }
 
+// The two back-half story statuses. `in-build` = some of a story's tasks shipped; `shipped` = all did.
+// Both are set ONLY by the build half (yad-engineer-review), never by the front-gate ladder
+// (cli/artifact-status.mjs PRESERVEs them). See #112.
+const BACK_HALF_STATUSES = new Set(['in-build', 'shipped']);
+
+// The repo-relative pathspecs for story files whose back-half `status:` flip we carry alongside the
+// ledgers (#112). The flip is authored by yad-engineer-review into the working tree but no command
+// committed it, so it drifted (build-log said shipped, stories/<id>.md still said approved) and the
+// only recovery was a raw git-to-main push. A story is a CANDIDATE iff BOTH hold:
+//   1. it has >=1 ship recorded in build-log (the build-half evidence), and
+//   2. its current frontmatter `status:` is a back-half value (in-build | shipped).
+// A candidate is only actually carried when its staged diff is the `status:` line ALONE — runCheckpoint
+// drops any candidate whose working tree also changed prose/other frontmatter (stagedStoryIsStatusOnly),
+// so an unrelated edit can never ride into a `chore(hub) … [skip ci]` commit that bypasses review.
+// The shared `git add`/`diff --cached` machinery then commits ONLY the ones that actually differ from
+// HEAD (so a story already committed at shipped is a no-op).
+//
+// A corrupt build-log in one epic must not block checkpointing every OTHER epic's ledgers, so a
+// readShips throw is caught per epic (that epic simply carries no story flip; its corrupt ledger is
+// still staged by backHalfPathspecs for a human to see).
+export function storyStatusPathspecs(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;
+    const epicDir = path.join(epicsDir, e.name);
+    const storiesDir = path.join(epicDir, 'stories');
+    if (!fs.existsSync(storiesDir)) continue;
+    let shipped;
+    try { shipped = new Set(readShips(epicDir).map((s) => s.story)); }
+    catch { continue; } // corrupt build-log — skip story-carry for this epic, leave its ledger to a human
+    for (const d of fs.readdirSync(storiesDir, { withFileTypes: true })) {
+      if (!d.isFile() || !d.name.endsWith('.md')) continue;
+      const storyId = d.name.slice(0, -3);
+      if (!shipped.has(storyId)) continue;
+      if (BACK_HALF_STATUSES.has(readFrontmatter(path.join(storiesDir, d.name)).status)) {
+        out.push(path.posix.join('epics', e.name, 'stories', d.name));
+      }
+    }
+  }
+  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.
@@ -52,9 +107,11 @@ export function summarizeStaged(files = []) {
   const epics = new Set();
   const basenames = [];
   for (const f of files) {
-    const m = f.match(/^epics\/([^/]+)\/\.sdlc\/(.+)$/);
+    // A back-half ledger (…/.sdlc/…) or a carried story-status flip (…/stories/<id>.md, #112).
+    const m = f.match(/^epics\/([^/]+)\/(?:\.sdlc\/(.+)|stories\/(.+\.md))$/);
     if (!m) continue;
-    const [, epic, rest] = m;
+    const [, epic] = m;
+    const rest = m[2] ?? m[3];
     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+)/);
@@ -91,6 +148,24 @@ export function buildCheckpointMessage({ label, author, basenames = [] }) {
   return body ? `${subject}\n\n${body}` : subject;
 }
 
+// True iff a story file's STAGED diff changes ONLY the frontmatter `status:` line — every added or
+// removed content line is a `status:` line. A newly-added file (all lines added) or any prose/other
+// edit fails, so only a clean flip is carried into the `[skip ci]` chore commit; anything broader is
+// left for a reviewed change (#112 review-bypass guard). `git` is a hubGit-style accessor.
+export function stagedStoryIsStatusOnly(git, file) {
+  const d = git('diff', '--cached', '-U0', '--', file);
+  if (!d.ok) return false;
+  let changes = 0;
+  for (const ln of d.stdout.split('\n')) {
+    if (ln.startsWith('+++') || ln.startsWith('---') || ln.startsWith('@@')) continue; // headers/hunks
+    if (ln.startsWith('+') || ln.startsWith('-')) {
+      if (!/^status:\s*\S/.test(ln.slice(1).trimStart())) return false; // a non-status change ⇒ not status-only
+      changes++;
+    }
+  }
+  return changes > 0;
+}
+
 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; }
@@ -108,7 +183,9 @@ 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;
 
-  const pathspecs = backHalfPathspecs(root);
+  // The machine ledgers PLUS any build-log-backed story `status:` flip (#112) — one commit records
+  // both, so the story artifact never drifts from build-log and no raw git-to-main push is needed.
+  const pathspecs = [...backHalfPathspecs(root), ...storyStatusPathspecs(root)];
   if (!pathspecs.length) { info('no back-half ledgers found — nothing to checkpoint'); return; }
 
   // Stage the allowlist. `git add -- <spec>` picks up new + modified files, and deletions of tracked
@@ -117,6 +194,19 @@ export async function runCheckpoint(root, opts = {}) {
   // 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; }
+
+  // #112 review-bypass guard: a story is only carried when its staged change is the `status:` line
+  // ALONE. Unstage any candidate whose working tree also touched prose/other frontmatter — those
+  // belong in a reviewed change, not a `[skip ci]` chore commit. Ledgers and clean flips are untouched.
+  const storyStaged = git('diff', '--cached', '--name-only', '--', ...pathspecs).stdout
+    .split('\n').filter((f) => /\/stories\/[^/]+\.md$/.test(f));
+  for (const f of storyStaged) {
+    if (!stagedStoryIsStatusOnly(git, f)) {
+      git('reset', '-q', '--', f);
+      info(`skipped ${f} — its change is more than the status: line; commit it through review`);
+    }
+  }
+
   if (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
     info('back-half state unchanged — nothing to commit');
     return;

package/cli/commit.mjs

@@ -2,12 +2,14 @@
 // Subject is Conventional Commits; trailers are emitted in the fixed order
 // Task -> Contract-Change -> Co-Authored-By. The human git author OWNS the commit; the AI is only a
 // co-author (flagged with --ai, or `none` for human-only). An atomic-commit guard keeps diffs small.
+// An explicit --task id is validated against the spec-link gate contract (<story>-T<NN>) so a
+// malformed trailer fails locally rather than after a push.
 import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, run, exists } from './lib.mjs';
 import {
   COMMIT_TYPES, AI_COAUTHORS, ATOMIC_FILE_LIMIT,
-  TASK_TRAILER, CONTRACT_CHANGE_TRAILER, COAUTHOR_TRAILER, PROJECT_FILES,
+  TASK_TRAILER, CONTRACT_CHANGE_TRAILER, COAUTHOR_TRAILER, PROJECT_FILES, TASK_ID_RE,
 } from './manifest.mjs';
 
 // PURE — unit tested directly. Build the full commit message text.
@@ -16,6 +18,13 @@ export function buildCommitMessage({ type, subject, task, contractChange = false
   if (!subject || !subject.trim()) throw new Error('commit subject is required');
   if (!(ai in AI_COAUTHORS)) throw new Error(`unknown --ai "${ai}" (one of: ${Object.keys(AI_COAUTHORS).join(', ')})`);
   if (/\.$/.test(subject.trim())) throw new Error('subject must not end with a period');
+  // A malformed task id (e.g. a bare story `EP-x-S01` with no -T<NN>) commits fine locally but
+  // then fails the spec-link CI gate — forcing a history rewrite + force-push. Reject it here so
+  // it never enters a trailer. Well-formed branch-derived ids (taskFromBranch) are stricter and pass;
+  // a lowercase-suffix branch is caught here, matching the case-sensitive spec-link grep.
+  if (task && !TASK_ID_RE.test(task)) {
+    throw new Error(`invalid --task "${task}" (expected <story>-T<NN>, e.g. EP-x-S01-T02) — the spec-link CI gate would reject it`);
+  }
 
   const trailers = [];
   if (task) trailers.push(`${TASK_TRAILER}: ${task}`);

package/cli/manifest.mjs

@@ -170,6 +170,10 @@ export const ATOMIC_FILE_LIMIT = 3;
 export const TASK_TRAILER = 'Task';
 export const CONTRACT_CHANGE_TRAILER = 'Contract-Change';
 export const COAUTHOR_TRAILER = 'Co-Authored-By';
+// A Task trailer id must be a real <story>-T<NN>. Mirrors the spec-link gate contract
+// (checks/spec-link.sh: `.+-T[0-9]+$`) so an explicit --task that would fail CI is
+// rejected locally at commit time instead of after a push + history rewrite.
+export const TASK_ID_RE = /.+-T\d+$/;
 
 // Per-epic ledger files under epics/<epic>/.sdlc/ (the file source of truth the gate reads/writes).
 export const epicFiles = (epicRoot) => ({

package/package.json

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

package/skills/yad-commit/SKILL.md

@@ -20,7 +20,9 @@ and `yad-ship` use. It **never auto-advances**; it just commits.
 - **Subject** — `<type>: <lowercase imperative description, no trailing period>`; types are
   `feat|fix|docs|refactor|test|perf|build|ci|chore|revert`; proper nouns/acronyms keep their case.
 - **Task trailer** — required on a code repo (anchors the `spec-link` + `commit-message` gates). Given
-  with `--task`, else derived from the branch (`feat/<story>-<task>-…`). Hub commits are not
+  with `--task` (a `<story>-T<NN>` id — an explicit value is validated against the `spec-link`
+  contract, so a malformed id like a bare `EP-x-S01` fails locally instead of after a push), else
+  derived from the branch (`feat/<story>-<task>-…`). Hub commits are not
   task-scoped, so the trailer is optional there — a missing-Task warning is informational on the hub
   (`spec-link` is a code-repo gate) and only flags a real gate failure in a code repo.
 - **Contract-Change trailer** — `--contract-change` only when the diff touches the locked contract

package/skills/yad-engineer-review/SKILL.md

@@ -97,9 +97,11 @@ engineer-review rule is satisfied (Step 2). Then:
   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.
+  never a front-half gate file. It is the back-half analogue of the front-half `yad gate` sync. The
+  same commit also **carries the story `status:` flip** you just wrote (`approved → in-build/shipped`,
+  #112) — because that story now has a build-log ship, checkpoint stages `stories/<story>.md` alongside
+  the ledgers, so the artifact never drifts from build-log and you never fall back to a raw git-to-main
+  push. (The code-repo `tasks.md` is committed in its own repo as usual.)
 
 ### 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

@@ -87,6 +87,11 @@ The story frontmatter `status` reflects build progress:
   records.
 - `shipped` — **every** task in `tasks.md` has a ship record.
 
+You write this flip into `stories/<story>.md`, but **do not hand-commit it** — the next
+`yad checkpoint --push` carries it in the same `chore(hub)` commit as the ledgers (the story now has a
+build-log ship, so checkpoint stages it; #112). This is what keeps the story artifact from drifting
+from `build-log.json`, so there is never a reason to fall back to a raw `git push origin main`.
+
 So the chain is traceable both ways: from the epic down (`epic.md` → `stories/<story>.md` →
 `tasks.md` → `build-log.json` ship → `mergeCommit`) and from a merge commit back up (its `Task:`
 trailer → story → epic).

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

@@ -53,7 +53,9 @@ resumable record.
 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]`
+`trust-log.json` / `build-log.json`) — plus any story `status:` flip (→ in-build/shipped) once that
+story has a build-log ship (#112) — 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 —