yadflow 3.8.1 → 3.9.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [3.8.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.8.0...v3.8.1) (2026-07-05)
+## [3.9.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.9.0...v3.9.1) (2026-07-06)
 
 
 ### Bug Fixes
 
-* **hub-bridge:** filter glab api output with jq in gate-sync ([352c681](https://github.com/abdelrahmannasr/yadflow/commit/352c681f9e5c6d43688410cfc5092c2382ec881e)), closes [#108](https://github.com/abdelrahmannasr/yadflow/issues/108)
+* carry ship-backed story status flip in yad checkpoint ([#112](https://github.com/abdelrahmannasr/yadflow/issues/112)) ([478230c](https://github.com/abdelrahmannasr/yadflow/commit/478230cdfccafbcc80913dd3b0a69262a45cbea6))
 
 # [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"
@@ -103,7 +104,9 @@ ${c.bold('Build helpers')}
   yad review nudge --repo <r> --pr <n>                    Friendly @-mention on a bare code-PR approve
   yad review reconcile --epic <id> --repo <r> --pr <n>    Bridge: stamp engagement onto the build-log ship
   yad repo list                        Show connected repos (fresh / stale)
-  yad repo refresh [name]              Re-pack a stale repo (a human decision)
+  yad repo refresh [name] [--push]     Re-pack a stale repo (a human decision). --push commits the
+                       refreshed code-maps + registry as a chore(hub): sync code-context … [skip ci]
+                       audit commit and pushes it to the hub default branch (--allow-branch to override)
 
 ${c.bold('Feature threads (post-lock change management)')}
   yad thread                           List every feature thread (genesis → changes → defects)
@@ -136,7 +139,7 @@ ${c.bold('Options')}
   --merged              gate ci: merge phase — advance the step on the default branch
   --no-push             gate ci: commit the ledger but do not push
   --push                check --fix / update: commit + push applied changes to the default branch
-  --allow-branch        check --fix --push / update --push: allow committing on a non-default branch
+  --allow-branch        check --fix --push / update --push / repo refresh --push: allow committing on a non-default branch
   -h, --help            Show this help
   -v, --version         Print version`;
 
@@ -289,7 +292,7 @@ async function main() {
     }
     case 'repo': {
       const [, action, name] = o._;
-      await runRepo(o.dir, { action: action || 'list', name, today });
+      await runRepo(o.dir, { action: action || 'list', name, today, push: o.push, allowBranch: o.allowBranch });
       break;
     }
     case 'roster': {

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/hubcommit.mjs

@@ -2,10 +2,32 @@
 // `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 fs from 'node:fs';
+import path from 'node:path';
 import { warn, fail, hand, run } from './lib.mjs';
 
 export const hubGit = (root) => (...args) => run('git', args, { cwd: root });
 
+const readFileSafe = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
+
+// A direct-to-default push (`yad update --push`, `yad repo refresh --push`) will be rejected by the
+// yad-update-guard unless the commits are signed AND their author email is allowlisted. Warn up front
+// (never block) so the operator isn't surprised by a reddened default branch. Best-effort, hub-identity
+// based.
+export function preflightGuardReadiness(root) {
+  const gitcfg = (k) => run('git', ['config', '--get', k], { cwd: root }).stdout;
+  // Only commit.gpgsign actually enables signing — user.signingkey merely picks WHICH key once
+  // signing is on, so it must not count (it would hide the warning while commits stay unsigned).
+  const signing = run('git', ['config', '--bool', '--get', 'commit.gpgsign'], { cwd: root }).stdout === 'true';
+  if (!signing) warn('commit signing is not enabled (git config commit.gpgsign true) — the yad-update-guard requires a platform-Verified signature; unsigned pushes will fail the gate.');
+  const email = gitcfg('user.email').toLowerCase();
+  const allow = readFileSafe(path.join(root, '.sdlc', 'verified-authors'));
+  const known = allow.split('\n').map((l) => l.trim().toLowerCase()).filter((l) => l && !l.startsWith('#'));
+  if (known.length && email && !known.includes(email)) {
+    warn(`your git email <${email}> is not in .sdlc/verified-authors — the yad-update-guard will reject these commits (add it to the hub roster and re-run \`yad check --fix\`).`);
+  }
+}
+
 // 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

package/cli/reconcile.mjs

@@ -4,27 +4,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
-  c, log, ok, info, warn, hand, readJSON, writeJSON, exists, run,
+  c, log, ok, info, warn, hand, readJSON, writeJSON, exists,
 } from './lib.mjs';
 
 const readFileSafe = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
 
-// The yad-update-guard will reject the very commits `--push` is about to create unless they are
-// signed AND their author email is allowlisted. Warn up front (never block) so the operator isn't
-// surprised by a reddened default branch across every repo. Best-effort, hub-identity based.
-function preflightGuardReadiness(root) {
-  const gitcfg = (k) => run('git', ['config', '--get', k], { cwd: root }).stdout;
-  // Only commit.gpgsign actually enables signing — user.signingkey merely picks WHICH key once
-  // signing is on, so it must not count (it would hide the warning while commits stay unsigned).
-  const signing = run('git', ['config', '--bool', '--get', 'commit.gpgsign'], { cwd: root }).stdout === 'true';
-  if (!signing) warn('commit signing is not enabled (git config commit.gpgsign true) — the yad-update-guard requires a platform-Verified signature; unsigned pushes will fail the gate.');
-  const email = gitcfg('user.email').toLowerCase();
-  const allow = readFileSafe(path.join(root, '.sdlc', 'verified-authors'));
-  const known = allow.split('\n').map((l) => l.trim().toLowerCase()).filter((l) => l && !l.startsWith('#'));
-  if (known.length && email && !known.includes(email)) {
-    warn(`your git email <${email}> is not in .sdlc/verified-authors — the yad-update-guard will reject these commits (add it to the hub roster and re-run \`yad check --fix\`).`);
-  }
-}
+import { preflightGuardReadiness } from './hubcommit.mjs';
 import { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,

package/cli/repo-publish.mjs

@@ -0,0 +1,145 @@
+// `yad repo refresh --push` — after a repack + registry stamp, commit the connected-repo code-context
+// (the tracked `code-map.md` per repo + the registry `.sdlc/repos.json`) and push it straight to the
+// hub's default branch, so a code-map refresh "just lands" for teammates / CI / `yad status` on other
+// machines instead of leaving a dirty tree for someone to hand-commit. This is the code-context
+// analogue of `yad checkpoint` (cli/checkpoint.mjs) and reuses its default-branch commit machinery.
+//
+// Invariants (shared with checkpoint):
+//   1. Stage an EXPLICIT allowlist — exactly the tracked code-maps + the registry (never `git add -A`,
+//      which would sweep unrelated work in the hub). The gitignored repomix pack.md is never staged.
+//   2. Commit ONLY on the hub's default branch (unless --allow-branch), so the `[skip ci]` audit
+//      commit never enters a PR's base..HEAD range where it would strand required checks.
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, 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, preflightGuardReadiness } from './hubcommit.mjs';
+import { checkpointAuthor } from './checkpoint.mjs';
+
+// 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();
+
+// The tracked code-map for a repo: the registered path, else the conventional location.
+const codeMapOf = (repo) => repo.codeMap || path.posix.join('.sdlc/code-context', repo.name, 'code-map.md');
+
+// PURE — the repo-relative pathspecs to stage: the registry plus each registered repo's code-map that
+// exists on disk. When `name` is given (a scoped `yad repo refresh <name> --push`), only that repo's
+// code-map is staged, so an unrelated repo's uncommitted code-map never rides along in a named refresh's
+// audit commit. Explicit allowlist by design (invariant 1); the gitignored pack.md is never included.
+export function codeMapPathspecs(root, registry = { repos: [] }, name = null) {
+  const out = [];
+  for (const repo of registry.repos || []) {
+    if (name && repo.name !== name) continue;
+    const rel = codeMapOf(repo);
+    if (fs.existsSync(path.join(root, rel))) out.push(rel);
+  }
+  // The registry always rides along — `yad repo refresh` stamps syncedHead/lastSyncedAt into it.
+  if (fs.existsSync(path.join(root, PROJECT_FILES.reposRegistry))) out.push(PROJECT_FILES.reposRegistry);
+  return out;
+}
+
+// PURE — turn the staged pathspecs into the subject `label` + the body's file list. A `<name>` is
+// pulled from any `.sdlc/code-context/<name>/code-map.md` path; a commit that only touched the
+// registry is labelled `registry`.
+export function summarizeCodeContext(files = []) {
+  const repos = new Set();
+  const basenames = [];
+  for (const f of files) {
+    basenames.push(f);
+    const m = f.match(/\.sdlc\/code-context\/([^/]+)\/code-map\.md$/);
+    if (m) repos.add(m[1]);
+  }
+  let label;
+  if (repos.size === 1) label = [...repos][0];
+  else if (repos.size > 1) label = `${repos.size} repos`;
+  else label = 'registry';
+  return { label, basenames };
+}
+
+// PURE — the audit-trail commit message. Subject passes the hub commit-message gate (valid type
+// `chore`, scope `hub`, non-empty description, no trailing period). No Task trailer and no
+// Co-Authored-By: this is human-owned machine state, not an authored code change. `[skip ci]` mirrors
+// `yad checkpoint` — it lands on the default branch and needs no PR gate suite. `label`/`author` are
+// collapsed to one line so nothing can split the subject or forge a trailer.
+export function buildCodeMapMessage({ label, author, basenames = [] }) {
+  const subject = `chore(hub): sync code-context — ${oneLine(label)} by ${oneLine(author)} [skip ci]`;
+  const body = basenames.length ? `Updated: ${basenames.join(', ')}` : '';
+  return body ? `${subject}\n\n${body}` : subject;
+}
+
+// Commit the tracked code-context (and, with push, push it) on the hub's default branch. Mirrors
+// `runCheckpoint`. Never throws; sets process.exitCode on a hard error so the CLI reports failure.
+export async function publishCodeContext(root, { push = false, allowBranch = false, name = null } = {}) {
+  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 — --push publishes the hub code-context; run it from the product hub');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { hub, repos } = loadHub(root);
+  const registry = { repos: repos || [] };
+  const git = hubGit(root);
+
+  const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
+  const defaultBranch = resolveDefaultBranch(git, hub);
+  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch, cmd: 'yad repo refresh --push' })) return;
+
+  const pathspecs = codeMapPathspecs(root, registry, name);
+  if (!pathspecs.length) { info('no code-context to publish — nothing to commit'); return; }
+
+  const add = git('add', '--', ...pathspecs);
+  if (!add.ok) { fail(`git add failed — ${add.stderr.split('\n')[0] || add.code}`); process.exitCode = 1; return; }
+
+  // Push HEAD to its OWN branch — on the default branch this is the same; with --allow-branch it keeps a
+  // WIP branch from being force-published onto the default branch. Shared by the fresh-commit path and
+  // the retry-after-failed-push path below.
+  const pushHead = () => {
+    if (pushWithRebase(root, branch).ok) { ok(`pushed to origin/${branch}`); return true; }
+    fail(`could not push to origin/${branch} — a protected branch, or an unresolvable rebase conflict`);
+    hand(`run \`git pull --rebase\` and re-run \`yad repo refresh --push\``);
+    process.exitCode = 1;
+    return false;
+  };
+
+  if (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
+    // Nothing new to commit. A non-push run is simply done. But on a push run a PRIOR run may have
+    // committed and then FAILED to push (the commit sits ahead of origin) — a plain re-run must land
+    // that commit, not silently no-op and exit 0 while it stays stranded. Push any unpushed commit(s).
+    if (!push) { info('code-context unchanged — nothing to commit'); return; }
+    const rev = git('rev-list', '--count', `origin/${branch}..HEAD`);
+    const ahead = rev.ok ? (Number(rev.stdout) || 0) : 1; // no upstream ref yet -> attempt the push
+    if (!ahead) { info('code-context unchanged and already published — nothing to do'); return; }
+    info(`code-context unchanged — pushing ${ahead} already-committed change(s) not yet on origin/${branch}`);
+    pushHead();
+    return;
+  }
+  // The exact files staged from the allowlist — 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);
+
+  // Only relevant when we are about to push a commit straight to the default branch: warn (never block)
+  // if signing/allowlisting would make the yad-update-guard reject it. Gated on `push` and deferred to
+  // here so it isn't noise on a guard-refused branch or a nothing-to-commit run.
+  if (push) preflightGuardReadiness(root);
+
+  const { label, basenames } = summarizeCodeContext(staged);
+  const author = checkpointAuthor(resolveCommitterLogin(root, hub?.roster || []), git('config', 'user.name').stdout);
+  const message = buildCodeMapMessage({ label, author, basenames });
+
+  const cm = git('commit', '-m', message, '--', ...staged);
+  if (!cm.ok) {
+    git('reset', '-q', '--', ...pathspecs); // don't leave the allowlist 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(`published ${staged.length} file(s): ${c.dim(label)}`);
+
+  if (!push) return { message };
+  pushHead();
+  return { message };
+}

package/cli/repo.mjs

@@ -7,6 +7,7 @@ import path from 'node:path';
 import { c, log, ok, info, warn, hand, fail, readJSON, writeJSON, run } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
 import { gitHead, packRepo } from './setup.mjs';
+import { publishCodeContext } from './repo-publish.mjs';
 
 function load(root) {
   const regPath = path.join(root, PROJECT_FILES.reposRegistry);
@@ -35,7 +36,7 @@ function defaultBranch(cwd, repo) {
   return r.ok && r.stdout ? r.stdout.replace(/^origin\//, '') : 'main';
 }
 
-export async function runRepo(root, { action = 'list', name, today } = {}) {
+export async function runRepo(root, { action = 'list', name, today, push = false, allowBranch = false } = {}) {
   const { regPath, registry } = load(root);
   if (!registry.repos.length) { warn('no repos registered (.sdlc/repos.json) — run `yad setup`'); return { repos: 0 }; }
 
@@ -69,7 +70,16 @@ export async function runRepo(root, { action = 'list', name, today } = {}) {
     }
     writeJSON(regPath, registry);
     refreshed ? ok(`refreshed ${refreshed} repo(s)`) : info('nothing refreshed');
-    hand('regenerate the code-map in Claude Code (yad-connect-repos) — the pack is cached, the map is the AI step');
+    if (push) {
+      // Publish whatever tracked code-context now differs (the AI-regenerated code-maps + the stamped
+      // registry) straight to the hub's default branch as one audit-trail commit. The pack itself is
+      // gitignored; the code-map is regenerated by the AI (yad-connect-repos) — run that first if a
+      // repo's map is stale, then `yad repo refresh --push` lands it.
+      await publishCodeContext(root, { push: true, allowBranch, name });
+    } else {
+      hand('regenerate the code-map in Claude Code (yad-connect-repos) — the pack is cached, the map is the AI step');
+      hand('then publish it to the hub default branch with `yad repo refresh --push`');
+    }
     return { refreshed };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.8.1",
+  "version": "3.9.1",
   "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/sdlc/module-help.csv

@@ -9,7 +9,7 @@ SDLC Workflow,yad-architecture,Author Architecture,AA,"Front state 3: with the a
 SDLC Workflow,yad-ui,Author UI Design,AU,"Front state 5: with the ux-designer author ui-design.md and DESIGN.md, driving Impeccable slash-commands when installed. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,ui-design.md DESIGN.md state.json
 SDLC Workflow,yad-stories,Author Stories,AS,"Front state 7: with the pm break the epic into repo-tagged stories with stable EP-<slug>-S0N IDs, one file each under stories/. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/stories/,stories/EP-<slug>-S0N.md state.json
 SDLC Workflow,yad-test-cases,Author Test Cases,TC,"Front state 9 (PARALLEL, non-blocking): opens when the stories gate passes — the epic is already ready-for-build, so the build half can start at the same time the tester works here. With the test architect (Murat) author test-cases.md covering the approved stories, and — when a testing tool is connected (.sdlc/testing.json) — generate/link the actual automation tests in it, recording test-links.json; otherwise produce the test-case artifact only. Its review never moves currentStep off ready-for-build. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,test-cases.md test-links.json state.json
-SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the product hub so the front/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>} {domain_owner: <who>},0-setup,,yad-sync-repos,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
+SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the product hub so the front/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. yad repo refresh --push publishes the refreshed code-maps + registry to the hub default branch as a chore(hub): sync code-context [skip ci] audit commit. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>} {domain_owner: <who>},0-setup,,yad-sync-repos,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
 SDLC Workflow,yad-sync-repos,Sync Connected Repos,SR,"Setup/maintenance: bring every connected repo up to date in one shot — switch each repo in .sdlc/repos.json to its default_branch and fast-forward it from origin (local-user git, no stored tokens). Working-tree only; never a gate and never writes the registry. A dirty repo is skipped and reported (never overwritten); a diverged branch is left for manual resolution (fast-forward only). After pulling, a repo's cached pack goes stale — points the human at yad repo refresh.",,{action: sync} {repo: <name>},0-setup,yad-connect-repos,yad-connect-design,false,,(none — working-tree only)
 SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: connect a design tool (Figma-first, pluggable) to the product hub so the UI design step can materialize the actual feature design (mobile screens / web pages) inside it, alongside ui-design.md + DESIGN.md. Records the tool + project/file references in .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: figma|pencil|none} {project_url: <team/project/file url>} {files: {web,mobile}},0-setup,,yad-ui,false,.sdlc/,design.json
 SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the product hub so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json

package/skills/yad-connect-repos/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-connect-repos
-description: 'Connects code repos to the product hub so the front/"brain" phases are code-aware. Registers N code repos (GitHub or GitLab, local-user auth, no stored tokens) into the project-wide .sdlc/repos.json, then caches an AI-readable picture of each — a compressed Repomix pack and a lightweight code-map (existing endpoints/events/data-models/modules), secret-scanned. Run at one-time setup or any time a new repo is added. Reusable, idempotent, refreshable; staleness is tracked by HEAD sha. Use when the user says "connect a repo", "connect the code repos", "refresh the code context", or "list connected repos".'
+description: 'Connects code repos to the product hub so the front/"brain" phases are code-aware. Registers N code repos (GitHub or GitLab, local-user auth, no stored tokens) into the project-wide .sdlc/repos.json, then caches an AI-readable picture of each — a compressed Repomix pack and a lightweight code-map (existing endpoints/events/data-models/modules), secret-scanned. Run at one-time setup or any time a new repo is added. Reusable, idempotent, refreshable; staleness is tracked by HEAD sha. `yad repo refresh --push` publishes the refreshed code-maps + registry to the hub default branch as a chore(hub): sync code-context [skip ci] audit commit. Use when the user says "connect a repo", "connect the code repos", "refresh the code context", "list connected repos", or "push the code-map refresh".'
 ---
 
 # SDLC — Connect Code Repos (make the brain code-aware)
@@ -109,7 +109,13 @@ the front phases will now load this repo's code-map. Nothing auto-advances; this
 ## Other actions
 
 - **`refresh`** — re-run Steps 2–4 for an already-connected repo (after its code moves). Updates
-  `syncedHead` + `lastSyncedAt`. Same machinery as `connect`.
+  `syncedHead` + `lastSyncedAt`. Same machinery as `connect`. Once the AI has regenerated the
+  `code-map.md` (Step 3), publish it to the product hub with **`yad repo refresh <repo> --push`**: it
+  commits the tracked code-maps + `.sdlc/repos.json` (never the gitignored `pack.md`) as one
+  audit-trail commit `chore(hub): sync code-context — <repos> by @<login> [skip ci]` and pushes it
+  straight to the hub's **default branch** (add `--allow-branch` to commit on a non-default branch).
+  This is the code-context analogue of `yad checkpoint` — human-owned machine state, no Task trailer,
+  no Co-Authored-By.
 - **`list`** — print every registry entry with a **fresh/stale** flag: compare each repo's current HEAD
   (`git -C <path> rev-parse HEAD`) to its `syncedHead`; differ ⇒ **stale** (suggest `refresh`).
 - **`disconnect`** — remove the repo from the registry and delete its cache dir. Leaves the **code repo

package/skills/yad-connect-repos/references/code-context.md

@@ -80,7 +80,9 @@ This is for a one-off look at a specific area. **Staleness is a human decision,
 side-effect:** when a repo is stale (HEAD ≠ `syncedHead`), the phase **flags it and stops** —
 "`<repo>` is stale; run `yad repo refresh <repo>` to re-pack the cache + `syncedHead`" — rather than
 silently re-packing the whole repo. A phase never refreshes the registry on its own; the human runs
-`yad repo refresh` (or `yad check --fix`).
+`yad repo refresh` (or `yad check --fix`). After the AI regenerates the code-map, `yad repo refresh
+--push` publishes the refreshed code-maps + registry to the hub's default branch as a `chore(hub): sync
+code-context … [skip ci]` audit commit (never `pack.md`; `--allow-branch` overrides the branch guard).
 
 ## Why this stays DRY with backfill
 

package/skills/yad-connect-repos/references/repos-registry.md

@@ -52,6 +52,8 @@ not under any `epics/EP-<slug>/.sdlc/`.
 
 Commit the **registry** (`repos.json`) and each repo's **`code-map.md`** — they are small, reviewable,
 and are what the front phases actually read (a diff on a code-map shows when a repo's surface moved).
+`yad repo refresh --push` commits and pushes exactly these (never `pack.md`) to the hub's default
+branch as one `chore(hub): sync code-context … [skip ci]` audit commit.
 **Ignore** the full Repomix `pack.md` — it is large and regenerable (`action: refresh`). The product
 hub's `.gitignore` carries `.sdlc/code-context/*/pack.md` for this. This mirrors how the per-epic
 `.sdlc/` state (state.json, approvals.json, build-log.json) is committed.

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 —

package/skills/yad-sync-repos/SKILL.md

@@ -63,7 +63,9 @@ Never create a merge commit, rebase, or force.
 Per repo: `switched to <branch>, pulled (ff)` / `already current` / `SKIPPED (...)`. Pulling moves HEAD,
 so any repo whose `HEAD` now differs from its registry `syncedHead` has a **stale code-context pack** —
 the command ends by pointing the human at `yad repo refresh` to repack (that is a separate human
-decision; this skill never repacks or writes the registry).
+decision; this skill never repacks or writes the registry). After the repack + AI code-map
+regeneration, `yad repo refresh --push` publishes the refreshed code-maps + registry to the hub's
+default branch as a `chore(hub): sync code-context … [skip ci]` audit commit.
 
 ## Hard rules