npm - yadflow - Versions diffs - 2.14.0 → 2.15.0 - Mend

yadflow 2.14.0 → 2.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/CHANGELOG.md +2 -2
package/bin/yad.mjs +19 -5
package/cli/artifact-status.mjs +102 -0
package/cli/doctor.mjs +14 -1
package/cli/epic-state.mjs +1 -1
package/cli/gate.mjs +121 -58
package/cli/manifest.mjs +2 -0
package/cli/platform.mjs +44 -6
package/package.json +1 -1
package/skills/yad-checks/SKILL.md +7 -0
package/skills/yad-checks/templates/checks/ledger-guard.sh +117 -0
package/skills/yad-checks/templates/checks/verified-commits.sh +9 -1
package/skills/yad-checks/templates/github/yad-hub-checks.yml +8 -0
package/skills/yad-checks/templates/gitlab/yad-hub-checks.gitlab-ci.yml +7 -0
package/skills/yad-hub-bridge/SKILL.md +41 -14
package/skills/yad-hub-bridge/references/bridge.md +93 -51
package/skills/yad-hub-bridge/templates/github/yad-gate-sync.yml +85 -35
package/skills/yad-hub-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +63 -32
package/skills/yad-review-gate/SKILL.md +12 -10

package/CHANGELOG.md CHANGED Viewed

@@ -1,9 +1,9 @@
-# [2.14.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.13.0...v2.14.0) (2026-06-21)
+# [2.15.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.14.0...v2.15.0) (2026-06-24)
 ### Features
-* yad next driver, precondition guards, solo mode, and guided setup interview ([#72](https://github.com/abdelrahmannasr/yadflow/issues/72)) ([7125c9d](https://github.com/abdelrahmannasr/yadflow/commit/7125c9d80043cb282a7be4f08dfaa95ddf94594a))
+* merge-driven review gate (Path B) — CI never pushes the review branch ([#78](https://github.com/abdelrahmannasr/yadflow/issues/78)) ([d4d983a](https://github.com/abdelrahmannasr/yadflow/commit/d4d983ab4efddb4e6ec259bb940b393e9237f9cf)), closes [#76](https://github.com/abdelrahmannasr/yadflow/issues/76)
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)

package/bin/yad.mjs CHANGED Viewed

@@ -14,6 +14,7 @@ import { runRoster } from '../cli/roster.mjs';
 import { runDocs } from '../cli/docs.mjs';
 import { runDoctor } from '../cli/doctor.mjs';
 import { runNext } from '../cli/next.mjs';
+import { syncStatuses } from '../cli/artifact-status.mjs';
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
@@ -27,6 +28,8 @@ ${c.bold('Setup & maintenance')}
                        also migrates pre-2.0 sdlc-* installs to the yad-* names
   yad doctor [--json]  Environment + state health: tools/auth, config files,
                        repo paths, epic ledgers (exit 1 on any failure)
+  yad sync-status [epic]   Update artifact frontmatter status (draft/in-review/approved)
+                       from .sdlc/state.json — all epics if omitted (--dry-run to preview)
 ${c.bold('Reviewer roster')}
   yad roster list                      Show every member + their roles per scope (hub + each repo)
@@ -47,9 +50,9 @@ ${c.bold('Review gate (front half)')}
   yad gate sync <epic> [artifact]      Pull PR state -> ledger; advance on approved+resolved+merged
   yad gate comments <epic> [artifact]  Fetch unresolved review comments to address
   yad gate status <epic>               Show each review step + approvals
-  yad gate ci [--branch <head>] [--pr <n>]
-                        CI entry (hub workflow): derive epic/artifact from the review branch,
-                        sync, commit the ledger to the default branch (sweep all PRs if no --branch)
+  yad gate ci [--branch <head>] [--pr <n>] [--merged]
+                        CI entry (hub workflow): pre-merge is read-only (nothing pushed);
+                        --merged advances the step + flips artifact status on the default branch
 ${c.bold('Build helpers')}
   yad commit --type <t> -m <subject>   Commit by convention (trailers, atomic guard)
@@ -80,6 +83,7 @@ ${c.bold('Options')}
   --force               commit: bypass the atomic-file guard / re-copy unchanged files
   --branch <head>       gate ci: the review PR/MR head branch (review/EP-<slug>/<artifact>)
   --pr <n>              gate ci: the PR/MR number from the CI event
+  --merged              gate ci: merge phase — advance the step on the default branch
   --no-push             gate ci: commit the ledger but do not push
   -h, --help            Show this help
   -v, --version         Print version`;
@@ -94,6 +98,7 @@ function parseArgs(argv) {
     else if (a === '--force') o.force = true;
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = true;
+    else if (a === '--merged') o.merged = true;
     else if (a === '--overview') o.overview = true;
     // `--check` is a bare boolean for `docs sync --check`, but takes a value for
     // `next <epic> --check <step>`. Only the `next` command consumes the following token as a value —
@@ -153,6 +158,12 @@ async function main() {
     case 'doctor':
       await runDoctor(o.dir, { json: o.json });
       break;
+    case 'sync-status': {
+      const [, epic] = o._;
+      if (epic && !isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      await syncStatuses(o.dir, { epic, dryRun: o.dryRun });
+      break;
+    }
     case 'next': {
       const [, epic] = o._;
       // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
@@ -163,12 +174,15 @@ async function main() {
     case 'gate': {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
-      if (action === 'ci') { await gateCi(o.dir, { branch: o.branch, pr: o.pr, push: !o.noPush, today }); break; }
+      if (action === 'ci') { await gateCi(o.dir, { branch: o.branch, pr: o.pr, merged: o.merged, push: !o.noPush, today }); break; }
       if (!epic) { log(c.red('usage: yad gate <open|sync|comments|status|ci> <epic> [artifact]')); process.exitCode = 1; break; }
       // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
       if (!isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      // In bridge mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
+      // advisory (reads the platform, prints status, writes nothing). The artifact status flip is
+      // CI's job at merge — never wired into the local gate. File-only mode keeps local writes.
       if (action === 'open') await gateOpen(o.dir, { epic, artifact, today });
-      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today });
+      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, local: true });
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
       else if (action === 'status') await gateStatus(o.dir, { epic });
       else { log(c.red(`unknown gate action: ${action} (open|sync|comments|status|ci)`)); process.exitCode = 1; }

package/cli/artifact-status.mjs ADDED Viewed

@@ -0,0 +1,102 @@
+// `yad sync-status [epic]` — reconcile each artifact's frontmatter `status:` with the real
+// source of truth, the per-epic state machine in .sdlc/state.json. The authoring skills hard-code
+// `status: draft` at creation and never update it, so artifacts read as "draft" long after their
+// gate has passed. This derives draft / in-review / approved from the step statuses and rewrites
+// only the `status:` line — advance-only, and never touching build-owned values.
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, log, ok, info, readJSONStrict } from './lib.mjs';
+import { epicRoot, artifactBase, artifactFromBase, findReviewStep } from './epic-state.mjs';
+import { epicFiles } from './manifest.mjs';
+// The front-gate lifecycle this command manages. Forward-only: a status is only ever moved UP this
+// ladder, so a re-run never regresses anything.
+const RANK = { draft: 0, 'in-review': 1, approved: 2 };
+// Values owned by other parts of the workflow — left untouched. `locked` is the contract surface;
+// `in-build` / `shipped` are set by the build half (engineer-review) per story; `ready-for-build`,
+// `done`, `blocked` are roll-ups/states we must not overwrite from the front-gate view.
+const PRESERVE = new Set(['locked', 'in-build', 'shipped', 'ready-for-build', 'done', 'blocked']);
+// The per-epic artifact files this command considers (bases). Story files are handled separately
+// because they live under stories/ and all map to the single stories / stories-review step pair.
+const ARTIFACT_FILES = ['analysis.md', 'epic.md', 'architecture.md', 'contract.md', 'ui-design.md', 'test-cases.md'];
+// The desired front-gate status for an artifact base, derived purely from state.json. Returns null
+// when the chain has no steps for this base (nothing to manage) — e.g. contract has no own step.
+export function desiredStatus(state, base) {
+  if (!state?.steps) return null;
+  const review = findReviewStep(state, artifactFromBase(base));
+  const author = state.steps.find((s) => s.type === 'author' && artifactBase(s.artifact) === base);
+  if (!review && !author) return null;
+  if (review?.status === 'done') return 'approved';
+  if (review?.status === 'in_review' || author?.status === 'done') return 'in-review';
+  return 'draft';
+}
+// Rewrite ONLY the `status:` line inside the first `---\n...\n---` frontmatter block, preserving
+// everything else. Returns the prior status when a change was written, or null for a no-op (no
+// frontmatter, no status line, preserved value, or not an advance). Mirrors the frontmatter regex
+// in gate.mjs.
+export function setFrontmatterStatus(file, status) {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return null;
+  const cur = (fm[1].match(/^status:\s*(.*)$/m) || [])[1]?.trim();
+  if (cur === undefined) return null;
+  // Advance-only within the managed ladder; anything else (build-owned, roll-ups) is left as-is.
+  if (PRESERVE.has(cur)) return null;
+  if (!(cur in RANK) || !(status in RANK) || RANK[status] <= RANK[cur]) return null;
+  const block = fm[1].replace(/^status:\s*.*$/m, `status: ${status}`);
+  fs.writeFileSync(file, text.replace(fm[1], block));
+  return cur;
+}
+// Sweep one epic (or every epic under epics/) and reconcile artifact frontmatter with state.json.
+export async function syncStatuses(root, { epic, dryRun = false } = {}) {
+  const epicsDir = path.join(root, 'epics');
+  const epics = epic
+    ? [epic]
+    : (fs.existsSync(epicsDir) ? fs.readdirSync(epicsDir).filter((e) => fs.statSync(path.join(epicsDir, e)).isDirectory()).sort() : []);
+  if (!epics.length) { info('no epics found — nothing to sync'); return { changed: 0 }; }
+  let changed = 0;
+  for (const e of epics) {
+    const dir = epicRoot(root, e);
+    const state = readJSONStrict(epicFiles(dir).state, null);
+    if (!state?.steps) { info(`${e}: no state.json — skipping`); continue; }
+    // Single-file artifacts + each story file (all keyed to the stories step pair).
+    const files = ARTIFACT_FILES.map((f) => ({ base: artifactBase(f), file: path.join(dir, f) }));
+    const storiesDir = path.join(dir, 'stories');
+    if (fs.existsSync(storiesDir)) {
+      for (const f of fs.readdirSync(storiesDir).filter((x) => x.endsWith('.md'))) {
+        files.push({ base: 'stories', file: path.join(storiesDir, f) });
+      }
+    }
+    for (const { base, file } of files) {
+      if (!fs.existsSync(file)) continue;
+      const want = desiredStatus(state, base);
+      if (!want) continue;
+      if (dryRun) {
+        // Peek without writing so --dry-run reports exactly what would change. Scope the match to the
+        // frontmatter block so a `status:` line in the Markdown body can't be mistaken for the value.
+        const text = fs.readFileSync(file, 'utf8');
+        const fm = text.match(/^---\n([\s\S]*?)\n---/);
+        const cur = (fm?.[1].match(/^status:\s*(.*)$/m) || [])[1]?.trim();
+        if (cur && !PRESERVE.has(cur) && cur in RANK && RANK[want] > RANK[cur]) {
+          log(`  ${c.dim('• would update')} ${path.relative(root, file)}: ${cur} → ${want}`);
+          changed++;
+        }
+        continue;
+      }
+      const prev = setFrontmatterStatus(file, want);
+      if (prev) { ok(`${path.relative(root, file)}: ${prev} → ${want}`); changed++; }
+    }
+  }
+  if (!changed) info(dryRun ? 'no status changes needed' : 'all artifact statuses already in sync');
+  else if (!dryRun) ok(`updated ${changed} artifact status(es)`);
+  return { changed };
+}

package/cli/doctor.mjs CHANGED Viewed

@@ -244,7 +244,20 @@ export function epicChecks(checks, root) {
     try {
       const ledger = loadLedger(epicRoot(root, e));
       if (!ledger.state) check(checks, `epic:${e}`, 'epics', 'warn', `${e}: no state.json — epic not seeded`, 'author it via yad-epic, or remove the directory');
-      else check(checks, `epic:${e}`, 'epics', 'ok', `${e}: currentStep ${ledger.state.currentStep}`);
+      else {
+        check(checks, `epic:${e}`, 'epics', 'ok', `${e}: currentStep ${ledger.state.currentStep}`);
+        // Migration guard (pre-3.0 model): under the current model CI records the ledger on the
+        // default branch only at merge (when the step is already done), and writes nothing during
+        // review — so an OPEN (non-done) review PR recorded here means it was opened under an older
+        // model. Merge/close it under the version that opened it before relying on the CI flow.
+        const openPr = (ledger.hubPrs || []).find((p) => {
+          const st = (ledger.state.steps.find((s) => s.id === p.step) || {}).status;
+          return st && st !== 'done';
+        });
+        if (openPr) check(checks, `epic:${e}:migration`, 'epics', 'warn',
+          `${e}: an open review PR (${openPr.artifact}${openPr.number ? ` #${openPr.number}` : ''}) is recorded on the default branch`,
+          'opened under a pre-3.0 yadflow? merge/close it before continuing — CI now records the gate ledger on the default branch only at merge');
+      }
     } catch (err) {
       check(checks, `epic:${e}`, 'epics', 'fail', `${e}: ${err.message} [${err.code || 'YAD-STATE-001'}]`, err.hint || 'fix the file or restore it from git');
     }

package/cli/epic-state.mjs CHANGED Viewed

@@ -42,7 +42,7 @@ export function artifactFromBase(base) {
 }
 // The files (relative to the epic dir) a review of this artifact covers — what `gate open` commits
-// on the review branch, and what the CI overlay checks out from the head ref (and never commits).
+// on the review branch (the owner's artifact), and what CI re-reads to bind the approval at merge.
 // Architecture mirrors artifactHash(): the approval is bound to the locked contract surface too.
 export function artifactPaths(base) {
   if (base === 'architecture') return ['architecture.md', 'contract.md', '.sdlc/contract-lock.json'];

package/cli/gate.mjs CHANGED Viewed

@@ -11,9 +11,10 @@ import { PROJECT_FILES } from './manifest.mjs';
 import {
   epicRoot, loadLedger, findReviewStep, artifactBase, artifactHash, gatePredicate,
   advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
-  artifactPaths, upsertHubPr,
+  upsertHubPr,
 } from './epic-state.mjs';
 import { readPr, mapApprovers, createPr, reviewersForScopes, resolveCommitterLogin } from './platform.mjs';
+import { syncStatuses } from './artifact-status.mjs';
 import { err } from './errors.mjs';
 // ---- tiny frontmatter reader (key: value, and `repos: [a, b]`) ----------------------------------
@@ -90,6 +91,12 @@ function loadHub(root) {
 // merge advances the step). Recorded per-project in hub.json by `yad setup`.
 const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+// Bridge mode: a platform AND the gate-sync CI explicitly enabled (the canonical `bridge_enabled`,
+// or the older `bridge`). ONLY then is CI the sole ledger writer — so `gate open`/`sync` stay
+// hands-off. A platform without the bridge (no gate-sync CI installed) keeps the local write path,
+// or reviews could never advance. Mirrors plan.mjs hubActions.
+const isBridge = (hub) => !!(hub?.platform && (hub.bridge_enabled === true || hub.bridge === true));
 // Re-add this step's bridge approvals from the current platform state (drop+re-add => dismissals and
 // revocations vanish idempotently; manual approvals are never touched). Preserve the artifactHash a
 // reviewer first approved against unless their review is newer (a genuine re-approval) — that is what
@@ -158,13 +165,19 @@ function recordComments(comments, { artifact, stepId, today, roster, blocking })
 // ---- actions ------------------------------------------------------------------------------------
-export async function gateSync(root, { epic, artifact, today, reader = readPr } = {}) {
+export async function gateSync(root, { epic, artifact, today, reader = readPr, local = false, dryRun = false } = {}) {
   const { hub, repos } = loadHub(root);
   if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — file-only gate, nothing to sync'); return { synced: 0 }; }
   const platform = hub.platform;
   const roster = hub.roster || [];
   const defaultReviewers = 1;
   const solo = isSolo(hub);
+  // Local invocation in bridge mode is ADVISORY: CI is the sole ledger writer, so a human run reads
+  // the platform and prints the predicate but writes nothing. CI calls gateSync with local=false.
+  // Without the bridge (platform but no gate-sync CI) the local command stays the writer.
+  // dryRun forces the same read-only behavior regardless of bridge — used for the Path B pre-merge
+  // evaluation, which must persist nothing (gateCi passes dryRun for a held branch event).
+  const readOnly = (local && isBridge(hub)) || dryRun;
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir}/.sdlc/state.json`); process.exitCode = 1; return { synced: 0 }; }
@@ -174,6 +187,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
   if (!targets.length) { warn(`no open review PR recorded for ${epic}${artifact ? ` / ${artifact}` : ''} (run \`yad gate open\` first)`); return { synced: 0 }; }
   let synced = 0;
+  let advanced = 0;
   for (const pr of targets) {
     const step = findReviewStep(state, pr.artifact);
     if (!step) { warn(`no review step for ${pr.artifact}`); continue; }
@@ -182,11 +196,13 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
     if (step.status === 'done') { info(`${pr.artifact}: ${step.id} already done — skipping`); continue; }
     const domains = touchedDomains(epicDir, step);
     const pull = reader(platform, pr.number, { cwd: root });
-    if (!pull.ok) { warn(`${pr.artifact}: ${pull.reason} — skipping (file-only)`); continue; }
+    // A failed platform read must not pass as a green no-op: flag the run non-zero so CI surfaces it
+    // (the wired workflow's reconcile/sweep aggregates this exit) instead of silently not advancing.
+    if (!pull.ok) { warn(`${pr.artifact}: ${pull.reason} — skipping (file-only)`); process.exitCode = 1; continue; }
     const curHash = artifactHash(epicDir, pr.artifact);
     warnUnlockedContract(epicDir, pr.artifact);
-    const recs = mapApprovers(pull.reviews, { roster, repos, touchedDomains: domains });
+    const recs = mapApprovers(pull.reviews, { roster, repos, touchedDomains: domains, headOid: pull.headOid });
     approvals = upsertBridge(approvals, recs, { stepId: step.id, artifact: pr.artifact, curHash, today });
     const changeRequested = pull.reviews.filter((r) => r.state === 'CHANGES_REQUESTED');
@@ -196,7 +212,8 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
       ...changeRequested.map((r) => ({ login: r.login, changesRequested: true })),
       ...unresolved,
     ];
-    writeComments(epicDir, base(pr.artifact), today, blocking);
+    // Advisory (read-only) sync must not touch the working tree — defer the reviews/*.md write.
+    if (!readOnly) writeComments(epicDir, base(pr.artifact), today, blocking);
     comments = recordComments(comments, { artifact: pr.artifact, stepId: step.id, today, roster, repos, blocking });
     const pred = gatePredicate({
@@ -207,6 +224,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
     log(`  ${c.bold(pr.artifact)} ${c.dim(`(PR #${pr.number}, rule: ${pred.rule})`)}`);
     if (pred.passed) {
       state = advanceState(state, step);
+      advanced++;
       ok(`gate PASSED — ${step.id} → done; next: ${state.currentStep}`);
     } else {
       state = markInReview(state, step);
@@ -216,29 +234,42 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
     synced++;
   }
+  if (readOnly) {
+    info('bridge mode: advisory view — CI owns the ledger, nothing written locally');
+    return { synced, advanced };
+  }
   writeJSON(ledger.files.approvals, approvals);
   writeJSON(ledger.files.comments, comments);
   writeJSON(ledger.files.hubPrs, hubPrs);
   writeJSON(ledger.files.state, state);
   refreshRoster(epicDir, targets, approvals, today);
-  return { synced };
+  return { synced, advanced };
 }
-// `yad gate ci` — the self-sufficient entry point hub CI calls on platform events (review
-// submitted/dismissed, PR synchronize, PR merged) and on the GitLab schedule. Event mode derives
-// epic/artifact from the `review/EP-<slug>/<base>` head branch (so it works even when the author
-// never committed hub-prs.json); sweep mode (no --branch) re-syncs every open review PR. Either way
-// it runs the unchanged gateSync, then commits ONLY the ledger files to the hub default branch —
-// the artifact itself lands on main via the human merge, never via CI.
-export async function gateCi(root, { branch, pr, today, push = true, reader = readPr } = {}) {
+// `yad gate ci` — the self-sufficient entry point hub CI calls on platform events. Path B: CI
+// never writes the ledger to the review branch — during review the platform PR/MR is the source of
+// truth, and the ledger is reconciled onto the default branch at merge.
+//
+//   PRE-MERGE (a held step, no --merged and nothing advanced): READ-ONLY. The predicate is
+//   evaluated for visibility, but nothing is committed or pushed — so an in-flight approval is never
+//   dismissed and the PR's required checks never strand on a CI commit.
+//
+//   MERGE (--merged, PR/MR closed+merged): the artifact reached the default branch via the human
+//   merge; the workflow checks out the default branch. CI runs the sync — the PR reads merged=true,
+//   so the predicate ADVANCES the step, flips the artifact `status:` to approved (syncStatuses), and
+//   commits the advance to the default branch. CI re-reads approvals fresh from the platform, so it
+//   needs no ledger pre-seeded on the branch.
+//
+// CI is the SOLE writer of the ledger and only ever commits to the default branch; humans never
+// commit gate-state files (enforced by the ledger-guard check). Sweep mode (no --branch) advances
+// merged-but-stuck reviews found in the locally checked-out default-branch ledgers.
+export async function gateCi(root, { branch, pr, merged = false, today, push = true, reader = readPr } = {}) {
   const { hub } = loadHub(root);
   if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — nothing to sync'); return { synced: 0 }; }
   const git = (...args) => run('git', args, { cwd: root });
-  // Push target: an explicit hub.default_branch wins; else the branch CI actually checked out (the
-  // workflow checks out the PR base / $CI_DEFAULT_BRANCH — hub.json from `yad setup` has no
-  // default_branch field, so the checkout is the truth); 'main' only as the last resort.
-  const head = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
-  const target = hub.default_branch || (head && head !== 'HEAD' ? head : 'main');
+  const defaultBranch = hub.default_branch || (() => { const h = git('rev-parse', '--abbrev-ref', 'HEAD').stdout; return h && h !== 'HEAD' ? h : 'main'; })();
+  // Push is decided AFTER the sync, once we know whether any step advanced: a held step (no advance,
+  // not merged) is read-only and pushes nothing; an advance lands on the default branch (see below).
   // Build the work list: one job per (epic, artifact) — from the event branch, or a full sweep.
   const jobs = [];
@@ -271,6 +302,7 @@ export async function gateCi(root, { branch, pr, today, push = true, reader = re
   let synced = 0;
   const touched = new Set();
+  const advancedEpics = new Set(); // epics whose step actually passed this run (merge OR a swept merge)
   for (const job of jobs) {
     const epicDir = epicRoot(root, job.epic);
     // Event mode (--branch) targets a single epic: fail loudly. Sweep mode skips the bad epic.
@@ -284,14 +316,14 @@ export async function gateCi(root, { branch, pr, today, push = true, reader = re
       continue;
     }
     if (!ledger.state) {
-      warn(`${job.epic}: no epic state on ${target} — commit epics/${job.epic}/.sdlc to ${target} first`);
+      warn(`${job.epic}: no epic state on the checked-out branch — the review branch is cut from the default branch, so it should carry it`);
       continue;
     }
     const step = findReviewStep(ledger.state, job.artifact);
     if (!step) { warn(`${job.epic}: no review step for ${job.artifact} — skipping`); continue; }
-    // The event may fire before the author ever committed hub-prs.json — build the entry from the
-    // event itself, so the first CI commit lands it on the default branch and the views converge.
+    // The merge event may fire before any hub-prs record exists (Path B never wrote one pre-merge) —
+    // build the entry from the event itself so the advance commit carries it onto the default branch.
     const existing = (ledger.hubPrs || []).find((x) => x.artifact === job.artifact);
     const number = Number(job.pr) || existing?.number || null;
     if (!existing || existing.number !== number || existing.branch !== job.branch) {
@@ -302,60 +334,78 @@ export async function gateCi(root, { branch, pr, today, push = true, reader = re
       writeJSON(ledger.files.hubPrs, ledger.hubPrs);
     }
-    // Overlay the artifact from the review branch so artifactHash binds approvals to what the
-    // reviewers actually approved (pre-merge, the default branch does not have it yet). A failed
-    // fetch (branch deleted after merge) is fine — the artifact already landed via the merge.
-    const overlay = artifactPaths(job.base).map((p) => path.join('epics', job.epic, p));
-    const fetched = job.branch ? git('fetch', 'origin', job.branch).ok : false;
-    if (fetched) for (const p of overlay) git('checkout', 'FETCH_HEAD', '--', p);
+    // No overlay: at merge the artifact is on the default branch CI checked out, so artifactHash
+    // binds to the reviewed content directly when CI re-reads the platform.
     let failed = false;
     try {
-      const r = await gateSync(root, { epic: job.epic, artifact: job.artifact, today, reader });
+      // A branch event that is not a merge can never advance (the predicate requires merged), so it
+      // is read-only under Path B — run it as a dry sync that persists nothing to the working tree.
+      const r = await gateSync(root, { epic: job.epic, artifact: job.artifact, today, reader, dryRun: !!branch && !merged });
       synced += r.synced;
+      // When the step actually ADVANCED (the merge phase, or a swept merge the schedule observed),
+      // reflect it in the artifact frontmatter (draft → approved). Keyed off the advance, not the
+      // --merged flag, so the GitLab scheduled sweep also flips status on a merge it catches. Never
+      // on a held step: CI must not touch the artifact while the owner is editing it pre-merge.
+      if (r.advanced > 0) { advancedEpics.add(job.epic); await syncStatuses(root, { epic: job.epic }); }
     } catch (err) {
       if (branch) throw err; // event mode: one epic — surface the failure
       warn(`${job.epic}: sync failed — ${err.message} — skipping this epic`);
       process.exitCode = 1;
       failed = true;
-    } finally {
-      // Drop the overlay — even when sync throws: only the ledger may reach the default branch via CI.
-      if (fetched) {
-        for (const p of overlay) {
-          git('checkout', 'HEAD', '--', p); // tracked files back to HEAD (no-op fail if not in HEAD)
-          git('clean', '-fd', '--', p);     // files new on the branch: remove
-        }
-      }
     }
     if (failed) continue; // a failed epic's partial state must not be committed by this run
     touched.add(job.epic);
   }
   if (!touched.size) return { synced };
-  // Commit the ledger only, then push with a rebase-retry (ledger commits across epics touch
-  // disjoint files; same-repo runs are serialized by the CI concurrency group).
+  // Path B: CI never writes the ledger to the review branch. A held step that did not advance is
+  // read-only here — during review the platform PR/MR is the source of truth (native approvals/
+  // threads); the ledger is reconciled onto the default branch at merge. Keeping CI off the PR head
+  // is what stops an approval from being dismissed and required checks from stranding. Correctness is
+  // unaffected: the merge phase re-reads approvals fresh from the platform (readPr).
+  const advancedAny = advancedEpics.size > 0;
+  if (!merged && !advancedAny) {
+    // Pre-merge is read-only (Path B): the gate was evaluated with a dry sync that persists nothing.
+    // The one working-tree write is the hub-prs.json seed above (so the dry sync could find the PR);
+    // restore exactly that file per epic so the checkout stays clean — never touching anything else,
+    // so a local `yad gate ci --branch` cannot disturb unrelated files.
+    for (const e of touched) {
+      const hp = path.join('epics', e, '.sdlc', 'hub-prs.json');
+      git('checkout', '-q', '--', hp); // restore it if it was tracked
+      git('clean', '-fq', '--', hp);   // remove it if the event first-seeded it (untracked)
+    }
+    info('pre-merge: gate evaluated; the ledger reconciles on the default branch at merge — nothing pushed');
+    return { synced };
+  }
+  const target = defaultBranch; // CI only ever commits the ledger to the default branch
+  // Stage what this merge-phase run owns, per epic (everything lands on the default branch):
+  //  - advanced → the whole epic (ledger advance + the status flip syncStatuses wrote into the .md).
+  //  - merged but not advanced (merged before the rule passed) → the ledger (.sdlc) + the generated
+  //    reviews/ summaries only; the artifact is the owner's, left untouched.
   for (const e of touched) {
-    // Separate adds: a pathspec with no match (reviews/ not created yet) must not abort the other.
-    git('add', '-A', '--', path.join('epics', e, '.sdlc'));
-    git('add', '-A', '--', path.join('epics', e, 'reviews'));
+    if (advancedEpics.has(e)) git('add', '-A', '--', path.join('epics', e));
+    else { git('add', '-A', '--', path.join('epics', e, '.sdlc')); git('add', '-A', '--', path.join('epics', e, 'reviews')); }
   }
   if (git('diff', '--cached', '--quiet').ok) { info('ledger unchanged — nothing to commit'); return { synced }; }
-  const subject = branch
-    ? `chore(gate): sync ${jobs[0].epic}/${jobs[0].base} via CI [skip ci]`
-    : 'chore(gate): scheduled gate sync [skip ci]';
+  // [skip ci]: the advance lands on the default branch (no PR trigger) but keeps the marker to guard
+  // sibling workflows. CI never pushes the review branch (Path B), so there is no synchronize loop.
+  const subject = !branch
+    ? 'chore(gate): scheduled gate sync [skip ci]' // sweep is a batch; one subject for the run
+    : `chore(gate): advance ${jobs[0].epic}/${jobs[0].base} on merge [skip ci]`;
   const cm = git('commit', '-m', subject);
   if (!cm.ok) { fail(`commit failed: ${cm.stderr || cm.stdout}`); process.exitCode = 1; return { synced }; }
-  ok(`committed ledger update: ${c.dim(subject)}`);
+  ok(`committed gate update: ${c.dim(subject)}`);
   if (!push) return { synced };
   for (let attempt = 1; attempt <= 3; attempt++) {
-    if (git('push', 'origin', `HEAD:${target}`).ok) { ok(`pushed ledger to origin/${target}`); return { synced }; }
+    if (git('push', 'origin', `HEAD:${target}`).ok) { ok(`pushed to origin/${target}`); return { synced }; }
     if (attempt < 3) {
       info(`push rejected — rebasing onto origin/${target} and retrying (${attempt}/3)`);
       if (!git('pull', '--rebase', 'origin', target).ok) git('rebase', '--abort'); // never leave a wedged rebase
     }
   }
-  fail(`could not push the ledger to origin/${target} — protected branch? allow the CI actor to push (see yad-hub-bridge references/bridge.md) or run \`yad gate sync\` locally`);
+  fail(`could not push to origin/${target}${merged ? ' — protected default branch? allow the gate bot to push the merge advance (see yad-hub-bridge references/bridge.md)' : ''} — or run \`yad gate sync\` locally`);
   process.exitCode = 1;
   return { synced };
 }
@@ -412,12 +462,22 @@ export async function gateOpen(root, { epic, artifact } = {}) {
   const domains = touchedDomains(epicDir, step);
   warnUnlockedContract(epicDir, artifact);
-  // Mark in-review in the ledger regardless of platform (file-only still works).
-  ledger.state = markInReview(ledger.state, step);
-  writeJSON(ledger.files.state, ledger.state);
-  if (!hub?.platform) { warn('no hub platform — marked in_review file-only (no PR opened)'); ok(`${step.id} → in_review`); return; }
+  const bridge = isBridge(hub);
+  // Outside bridge mode (file-only, OR a platform with no gate-sync CI) there is no CI to write the
+  // ledger, so the local command marks the step in_review. In bridge mode CI is the sole writer.
+  if (!bridge) {
+    ledger.state = markInReview(ledger.state, step);
+    writeJSON(ledger.files.state, ledger.state);
+  }
+  if (!hub?.platform) {
+    warn('no hub platform — marked in_review file-only (no PR opened)');
+    ok(`${step.id} → in_review`);
+    return;
+  }
+  // Open the PR. In bridge mode CI records the hub-prs entry (and advances) on the default branch at
+  // merge — `yad gate open` never commits gate-state files (the ledger-guard check enforces that), and
+  // CI writes nothing pre-merge. Without the bridge, the local command records the PR itself (no CI will).
   const body = fillHubTemplate({ epic, artifact, step, owner: ownerOf(epicDir), domains });
   // Assignee = whoever opens the review PR (the committer); reviewers = the hub's reviewers +
   // domain-owners of the touched repos, minus the committer (the owner/author is recorded, not asked
@@ -428,13 +488,16 @@ export async function gateOpen(root, { epic, artifact } = {}) {
   const labels = isEscalated(step) ? domains.map((d) => `domain:${d}`) : [];
   info(`opening review ${hub.platform === 'gitlab' ? 'MR' : 'PR'} on branch ${branch} …`);
   const r = createPr(hub.platform, { title: `review: ${artifact} (${epic})`, body, base: hub.default_branch || 'main', head: branch, reviewers, assignees, labels, cwd: root });
-  if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'}); step is in_review file-only`); return; }
+  if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'})${bridge ? ' — open it manually; CI records the gate on merge' : '; step is in_review file-only'}`); return; }
-  const number = Number((r.url.match(/\/(\d+)(?:[/?#]|$)/) || [])[1]) || null;
-  ledger.hubPrs = upsertHubPr(ledger.hubPrs, { step: step.id, artifact, platform: hub.platform, number, url: r.url, branch, lastSyncedAt: null });
-  writeJSON(ledger.files.hubPrs, ledger.hubPrs);
+  if (!bridge) {
+    ledger.hubPrs = upsertHubPr(ledger.hubPrs, { step: step.id, artifact, platform: hub.platform, number: Number((r.url.match(/\/(\d+)(?:[/?#]|$)/) || [])[1]) || null, url: r.url, branch, lastSyncedAt: null });
+    writeJSON(ledger.files.hubPrs, ledger.hubPrs);
+  }
   ok(`opened ${r.url}`);
-  hand(`reviewers approve/comment there; then run \`yad gate sync ${epic} ${artifact}\``);
+  hand(bridge
+    ? 'reviewers approve/comment there; CI advances the gate on the default branch when it is merged'
+    : `reviewers approve/comment there; then run \`yad gate sync ${epic} ${artifact}\``);
 }
 // ---- helpers ------------------------------------------------------------------------------------

package/cli/manifest.mjs CHANGED Viewed

@@ -195,6 +195,8 @@ export const wiringFor = (platform) => [
 export const HUB_WIRING = {
   common: [
     { src: 'skills/yad-checks/templates/checks/verified-commits.sh', dest: 'checks/verified-commits.sh', exec: true },
+    // The ledger is CI-owned: block non-bot commits to gate-state files on hub review PRs.
+    { src: 'skills/yad-checks/templates/checks/ledger-guard.sh', dest: 'checks/ledger-guard.sh', exec: true },
     // Pattern gates run on the hub too (profile: hub) — commit subject + PR title + PR body.
     { src: 'skills/yad-checks/templates/checks/commit-message.sh', dest: 'checks/commit-message.sh', exec: true },
     { src: 'skills/yad-pr-template/templates/checks/pr-title.sh', dest: 'checks/pr-title.sh', exec: true },