yadflow 3.7.1 → 3.8.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [3.7.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.7.0...v3.7.1) (2026-07-04)
+## [3.8.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.8.0...v3.8.1) (2026-07-05)
 
 
 ### Bug Fixes
 
-* **ledger:** sanitize shard-name components against path traversal ([5d85286](https://github.com/abdelrahmannasr/yadflow/commit/5d85286591cc9e6c78e449551c82d87683accba5))
+* **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)
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -77,8 +77,10 @@ In one pass it produces:
 - **`.sdlc/` config** — the product hub, connected repos, reviewer roster, and tool connections
   (design, testing, learning), all as plain JSON you can read and diff.
 - **CI gates**, wired into every connected repo and the hub as **GitHub Actions or GitLab CI** —
-  spec-link, contract-check, verified-commits, build/test/lint, and the feature-thread gates, shipped
-  as CI-agnostic bash under `checks/`.
+  spec-link, contract-check, verified-commits, build/test/lint, the feature-thread gates, and the
+  push-on-main **`yad-update-guard`** (which re-checks any direct-to-default commit — e.g. from
+  `yad update --push` — with just `verified-commits` + `commit-message`), shipped as CI-agnostic bash
+  under `checks/`.
 - **PR/MR templates** and an opt-in CodeRabbit config.
 
 Your first `yad-epic` seeds the `epics/EP-<slug>/` ledger — state, approvals, and the contract lock —

package/bin/yad.mjs

@@ -33,6 +33,11 @@ ${c.bold('Setup & maintenance')}
   yad update           Apply drift only (alias for: check --fix --scope=changed);
                        installs newly-added skills, updates changed skills + gate scripts,
                        and migrates pre-2.0 sdlc-* installs to the yad-* names
+  yad update --push    Also commit each repo's applied changes and push them straight to the
+                       default branch of the hub + every connected repo (a chore(yad-update)
+                       commit; no PR — the push-on-main yad-update-guard runs verified-commits
+                       + commit-message). Announce the team & pause merges first. Also works as
+                       'yad check --fix --push'; --allow-branch permits a non-default branch
   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)
@@ -130,6 +135,8 @@ ${c.bold('Options')}
   --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
+  --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
   -h, --help            Show this help
   -v, --version         Print version`;
 
@@ -198,10 +205,10 @@ async function main() {
       });
       break;
     case 'check':
-      await reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, today });
+      await reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, today });
       break;
     case 'update':
-      await reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, today });
+      await reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, today });
       break;
     case 'doctor':
       await runDoctor(o.dir, { json: o.json });

package/cli/manifest.mjs

@@ -209,10 +209,13 @@ export const REPO_WIRING = {
   ],
   github: [
     { src: 'skills/yad-checks/templates/github/yad-checks.yml', dest: '.github/workflows/yad-checks.yml' },
+    // Integrity gate for direct-to-default pushes (`yad update --push`): verified-commits + commit-message.
+    { src: 'skills/yad-checks/templates/github/yad-update-guard.yml', dest: '.github/workflows/yad-update-guard.yml' },
     { src: 'skills/yad-pr-template/templates/github/pull_request_template.md', dest: '.github/pull_request_template.md' },
   ],
   gitlab: [
     { src: 'skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml', dest: '.gitlab/ci/yad-checks.yml' },
+    { src: 'skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml', dest: '.gitlab/ci/yad-update-guard.yml' },
     { src: 'skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md', dest: '.gitlab/merge_request_templates/Default.md' },
   ],
 };
@@ -240,10 +243,14 @@ export const HUB_WIRING = {
     { src: 'skills/yad-hub-bridge/templates/github/yad-gate-sync.yml', dest: '.github/workflows/yad-gate-sync.yml' },
     { src: 'skills/yad-checks/templates/github/yad-verified-commits.yml', dest: '.github/workflows/yad-verified-commits.yml' },
     { src: 'skills/yad-checks/templates/github/yad-hub-checks.yml', dest: '.github/workflows/yad-hub-checks.yml' },
+    // Integrity gate for the hub's own direct-to-default pushes (`yad update --push`; the machine-
+    // state `yad checkpoint`/`gate ci` commits carry [skip ci] and are intentionally not re-checked).
+    { src: 'skills/yad-checks/templates/github/yad-update-guard.yml', dest: '.github/workflows/yad-update-guard.yml' },
   ],
   gitlab: [
     { src: 'skills/yad-hub-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml', dest: '.gitlab/ci/yad-gate-sync.yml' },
     { src: 'skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml', dest: '.gitlab/ci/yad-verified-commits.yml' },
     { src: 'skills/yad-checks/templates/gitlab/yad-hub-checks.gitlab-ci.yml', dest: '.gitlab/ci/yad-hub-checks.yml' },
+    { src: 'skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml', dest: '.gitlab/ci/yad-update-guard.yml' },
   ],
 };

package/cli/plan.mjs

@@ -11,17 +11,28 @@ import {
   LEGACY_SKILLS, REMOVED_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES,
 } from './manifest.mjs';
 
-// status: 'ok' | 'missing' | 'outdated'
-const fileAction = (scope, item, src, dest, opts = {}) => ({
+// A git pathspec (forward slashes, relative to a repo root) for `dest` under `root`. Actions carry
+// these so `yad update --push` can stage an EXPLICIT allowlist of exactly what it wrote per repo —
+// never `git add -A` (see cli/update-commit.mjs). A directory pathspec stages every added/changed/
+// removed file underneath it, so a dirAction needs only its top-level dest.
+const rel = (root, dest) => path.relative(root, dest).split(path.sep).join('/');
+
+// status: 'ok' | 'missing' | 'outdated'. `root` is the repo the write lands in (the hub for module
+// installs, a connected repo for its wiring); `paths` is the pathspec(s) touched, for the push stage.
+const fileAction = (scope, item, src, dest, { root, exec = false } = {}) => ({
   scope,
   item,
   status: !exists(dest) ? 'missing' : sameContent(src, dest) ? 'ok' : 'outdated',
-  apply: () => copyFile(src, dest, opts),
+  root,
+  paths: root ? [rel(root, dest)] : [],
+  apply: () => copyFile(src, dest, { exec }),
 });
-const dirAction = (scope, item, src, dest) => ({
+const dirAction = (scope, item, src, dest, { root } = {}) => ({
   scope,
   item,
   status: !exists(dest) ? 'missing' : dirMatches(src, dest) ? 'ok' : 'outdated',
+  root,
+  paths: root ? [rel(root, dest)] : [],
   apply: () => copyDir(src, dest),
 });
 
@@ -50,6 +61,7 @@ export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
           ide, s,
           asset('skills', s, 'SKILL.md'),
           path.join(root, IDE_OPENCODE_DIR, `${s}.md`),
+          { root },
         )));
       }
     } else {
@@ -58,6 +70,7 @@ export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
           ide, s,
           asset('skills', s),
           path.join(root, ide, 'skills', s),
+          { root },
         )));
       }
     }
@@ -67,6 +80,7 @@ export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
       '_bmad', f,
       asset('skills', 'sdlc', f),
       path.join(root, '_bmad', 'sdlc', f),
+      { root },
     ));
   }
   return actions;
@@ -83,26 +97,32 @@ export function legacyModuleActions(root, ideTargets = ideTargetsFor(root)) {
     for (const [skill, old] of Object.entries(LEGACY_SKILLS)) {
       if (ide === '.opencode') {
         const oldDest = path.join(root, IDE_OPENCODE_DIR, `${old}.md`);
+        const newDest = path.join(root, IDE_OPENCODE_DIR, `${skill}.md`);
         if (!exists(oldDest)) continue;
         actions.push({
           scope: ide,
           item: `${old}.md → ${skill}.md`,
           status: 'legacy',
+          root,
+          paths: [rel(root, oldDest), rel(root, newDest)],
           apply: () => {
             fs.rmSync(oldDest, { force: true });
-            copyFile(asset('skills', skill, 'SKILL.md'), path.join(root, IDE_OPENCODE_DIR, `${skill}.md`));
+            copyFile(asset('skills', skill, 'SKILL.md'), newDest);
           },
         });
       } else {
         const oldDest = path.join(root, ide, 'skills', old);
+        const newDest = path.join(root, ide, 'skills', skill);
         if (!exists(oldDest)) continue;
         actions.push({
           scope: ide,
           item: `${old} → ${skill}`,
           status: 'legacy',
+          root,
+          paths: [rel(root, oldDest), rel(root, newDest)],
           apply: () => {
             fs.rmSync(oldDest, { recursive: true, force: true });
-            copyDir(asset('skills', skill), path.join(root, ide, 'skills', skill));
+            copyDir(asset('skills', skill), newDest);
           },
         });
       }
@@ -127,6 +147,8 @@ export function removedModuleActions(root, ideTargets = ideTargetsFor(root)) {
           scope: ide,
           item: `${skill}.md (removed)`,
           status: 'removed',
+          root,
+          paths: [rel(root, dest)],
           apply: () => fs.rmSync(dest, { force: true }),
         });
       } else {
@@ -136,6 +158,8 @@ export function removedModuleActions(root, ideTargets = ideTargetsFor(root)) {
           scope: ide,
           item: `${skill} (removed)`,
           status: 'removed',
+          root,
+          paths: [rel(root, dest)],
           apply: () => fs.rmSync(dest, { recursive: true, force: true }),
         });
       }
@@ -162,10 +186,17 @@ function legacyFileActions(scope, baseRoot, fileMap, wiring) {
     if (!ownedByOldInstall(oldPath)) continue;
     const w = wiring.find((x) => x.dest === newDest);
     if (!w) continue; // never delete a working file without a replacement to install
+    // Only claim the root .gitlab-ci.yml when apply() will actually rewrite it (it references the old
+    // fragment) — else a --push would sweep the user's unrelated edits to that shared-ownership file
+    // into the chore(yad-update) commit. The old (deletion) + new (add) paths are always ours.
+    let rewritesRootCi = false;
+    try { rewritesRootCi = fs.readFileSync(path.join(baseRoot, '.gitlab-ci.yml'), 'utf8').includes(oldDest); } catch { /* no root ci */ }
     actions.push({
       scope,
       item: `${oldDest} → ${newDest}`,
       status: 'legacy',
+      root: baseRoot,
+      paths: rewritesRootCi ? [oldDest, newDest, '.gitlab-ci.yml'] : [oldDest, newDest],
       apply: () => {
         fs.rmSync(oldPath, { force: true });
         copyFile(asset(w.src), path.join(baseRoot, newDest), { exec: !!w.exec });
@@ -195,7 +226,7 @@ export function legacyHubActions(root) {
 export function repoActions(root, repo) {
   const repoRoot = path.resolve(root, repo.path);
   return wiringFor(repo.platform).map((w) =>
-    fileAction(repo.name, w.dest, asset(w.src), path.join(repoRoot, w.dest), { exec: !!w.exec }),
+    fileAction(repo.name, w.dest, asset(w.src), path.join(repoRoot, w.dest), { root: repoRoot, exec: !!w.exec }),
   );
 }
 
@@ -207,7 +238,7 @@ export function hubActions(root) {
   // wrote `bridge` — accept an explicit true in either spelling, wire nothing otherwise.
   if (!hub?.platform || !(hub.bridge_enabled === true || hub.bridge === true)) return [];
   return [...HUB_WIRING.common, ...(HUB_WIRING[hub.platform] || [])].map((w) =>
-    fileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { exec: !!w.exec }),
+    fileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { root, exec: !!w.exec }),
   );
 }
 
@@ -238,13 +269,18 @@ export function authorsActions(root, repos = []) {
     ...emails,
   ].join('\n') + '\n';
   const targets = [
-    { scope: 'hub', dest: path.join(root, '.sdlc', 'verified-authors') },
-    ...repos.map((r) => ({ scope: r.name, dest: path.join(path.resolve(root, r.path), '.sdlc', 'verified-authors') })),
+    { scope: 'hub', root, dest: path.join(root, '.sdlc', 'verified-authors') },
+    ...repos.map((r) => {
+      const repoRoot = path.resolve(root, r.path);
+      return { scope: r.name, root: repoRoot, dest: path.join(repoRoot, '.sdlc', 'verified-authors') };
+    }),
   ];
-  return targets.map(({ scope, dest }) => ({
+  return targets.map(({ scope, root: targetRoot, dest }) => ({
     scope,
     item: '.sdlc/verified-authors',
     status: !exists(dest) ? 'missing' : fs.readFileSync(dest, 'utf8') === desired ? 'ok' : 'outdated',
+    root: targetRoot,
+    paths: [rel(targetRoot, dest)],
     apply: () => {
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       fs.writeFileSync(dest, desired);

package/cli/reconcile.mjs

@@ -1,20 +1,41 @@
 // `yad check` (report) and `yad check --fix` (reconcile) — and `yad update`
 // as a thin alias (--scope=changed). Inspects actual project state against the
 // manifest: missing setup, drifted files, stale code-context.
+import fs from 'node:fs';
 import path from 'node:path';
 import {
-  c, log, ok, info, warn, hand, readJSON, writeJSON, exists,
+  c, log, ok, info, warn, hand, readJSON, writeJSON, exists, run,
 } 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 { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
 } from './plan.mjs';
 import { gitHead, packRepo } from './setup.mjs';
+import { groupByRoot, commitUpdates } from './update-commit.mjs';
 
 const MARK = { missing: c.red('missing'), new: c.cyan('new'), outdated: c.yellow('outdated'), stale: c.yellow('stale'), legacy: c.yellow('legacy'), removed: c.yellow('removed'), ok: c.green('ok') };
 
-export async function reconcile(root, { fix = false, scope = 'all', force = false } = {}) {
+export async function reconcile(root, { fix = false, scope = 'all', force = false, push = false, allowBranch = false } = {}) {
   log(c.bold(`\nSDLC reconcile  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}\n`));
 
@@ -41,7 +62,18 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     const head = gitHead(path.resolve(root, repo.path));
     if (head && repo.syncedHead && head !== repo.syncedHead) {
       staleRepos.push(repo);
-      actions.push({ scope: repo.name, item: 'code-context', status: 'stale', apply: () => packRepo(root, repo) });
+      // packRepo writes the repomix cache under the HUB root (root/repo.contextPack, e.g.
+      // .sdlc/code-context/<name>/pack.md), so the touched path belongs to the hub — and is commonly
+      // gitignored, in which case the push stage's check-ignore drops it. codeMap is AI-generated
+      // later, not here, so only the pack is claimed.
+      actions.push({
+        scope: repo.name,
+        item: 'code-context',
+        status: 'stale',
+        root,
+        paths: repo.contextPack ? [repo.contextPack] : [],
+        apply: () => packRepo(root, repo),
+      });
     }
   }
 
@@ -68,25 +100,55 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
   log(c.dim(`summary: ${counts.missing} missing, ${counts.new} new, ${counts.outdated} outdated, ${counts.stale} stale, ${counts.legacy} legacy, ${counts.removed} removed, ${counts.ok} ok`));
 
   if (!fix) {
+    if (push) warn('--push has no effect without --fix (there is nothing applied to commit).');
     if (fixable.length || gaps.length) hand('run `yad check --fix` to reconcile (or `yad setup` for missing one-time setup).');
     return { counts, gaps, applied: 0 };
   }
 
-  // --- apply ---
+  // --- apply --- (collect the applied actions so --push can stage each repo's exact allowlist) ---
   log('');
   let applied = 0;
+  const appliedActions = [];
   for (const a of fixable) {
     a.apply();
     applied++;
+    appliedActions.push(a);
     info(`${a.status} → fixed: ${a.scope}/${a.item}`);
   }
   if (force) {
-    for (const a of actions.filter((a) => a.status === 'ok')) a.apply();
+    for (const a of actions.filter((a) => a.status === 'ok')) { a.apply(); appliedActions.push(a); }
   }
-  // refresh the version stamp (preserve recorded ideTargets)
+  // refresh the version stamp (preserve recorded ideTargets) and let it ride the hub's update commit
   const rec = readJSON(path.join(root, PROJECT_FILES.version), {});
   writeJSON(path.join(root, PROJECT_FILES.version), { ...rec, version: VERSION });
+  appliedActions.push({ scope: 'hub', item: PROJECT_FILES.version, status: 'stamp', root, paths: [PROJECT_FILES.version] });
   applied ? ok(`reconciled ${applied} item(s)`) : info('nothing to fix');
   if (gaps.length) hand('one-time setup still missing — run `yad setup`.');
+
+  // --- publish: commit each repo's applied changes and push directly to its default branch ---
+  if (push) {
+    preflightGuardReadiness(root);
+    const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), {});
+    const defByRoot = new Map([[root, hub?.default_branch]]);
+    const platformByRoot = new Map([[root, hub?.platform]]);
+    for (const repo of registry.repos) {
+      const repoRoot = path.resolve(root, repo.path);
+      defByRoot.set(repoRoot, repo.default_branch);
+      platformByRoot.set(repoRoot, repo.platform);
+    }
+    commitUpdates(root, groupByRoot(appliedActions), {
+      push: true, allowBranch,
+      defaultBranchFor: (r) => defByRoot.get(r),
+      // GitLab's yad-update-guard is an includable fragment: unlike a GitHub workflow it does nothing
+      // until the root .gitlab-ci.yml `include:`s it (added by the yad-checks skill wire step, not by
+      // reconcile). Flag a gitlab repo whose root pipeline lacks the include so the direct-to-default
+      // push isn't left silently unguarded.
+      guardInactiveGitlab: (r) => {
+        if (platformByRoot.get(r) !== 'gitlab') return false;
+        const ci = path.join(r, '.gitlab-ci.yml');
+        return !exists(ci) || !readFileSafe(ci).includes('yad-update-guard.yml');
+      },
+    });
+  }
   return { counts, gaps, applied };
 }

package/cli/update-commit.mjs

@@ -0,0 +1,195 @@
+// `yad update --push` / `yad check --fix --push` — after reconcile applies drift into the working
+// trees, commit the applied changes PER REPO (the hub and every connected repo) and push them
+// straight to the default branch, so a package update "just lands" everywhere instead of leaving
+// dirty trees for someone to hand-commit across N repos. This is the update-flow analogue of the
+// back-half `yad checkpoint` (cli/checkpoint.mjs) and reuses its machine-commit machinery.
+//
+// Invariants (shared with checkpoint):
+//   1. Stage an EXPLICIT per-repo allowlist — exactly the paths the reconcile actions declared they
+//      wrote (never `git add -A`, which would sweep unrelated work in a connected repo). Ignored
+//      paths (a consumer repo that .gitignores .claude/ or the repomix code-context cache) are
+//      dropped, and the commit is scoped to the staged allowlist so any pre-staged unrelated file
+//      never rides along.
+//   2. Commit ONLY on each repo's default branch; a repo on a feature branch is SKIPPED with a
+//      warning (unless --allow-branch) — never disrupted.
+//
+// UNLIKE checkpoint, the commit is NOT marked `[skip ci]`: it goes straight to the default branch
+// with NO PR (so the pull_request gate suite never fires), and a push-on-main integrity workflow
+// (yad-update-guard) runs ONLY verified-commits + commit-message over it — the "skipped from CI
+// except verified-commits + the pattern gates" contract. The subject is a valid `chore` commit so it
+// passes commit-message and the story-linking gates treat it as an exempt maintenance commit; no
+// Task trailer, no Co-Authored-By (human-owned machine state, not an authored code change).
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, log, ok, info, warn, fail, hand, run, pushWithRebase } from './lib.mjs';
+import { VERSION } from './manifest.mjs';
+import { hubGit, resolveDefaultBranch } from './hubcommit.mjs';
+
+// Collapse whitespace/newline runs to a single space — keeps a stray path or hostile value from
+// breaking the one-line subject or injecting a fake trailer line.
+const oneLine = (s = '') => String(s).replace(/\s+/g, ' ').trim();
+
+// A short, human label for a repo root relative to the hub: 'hub' for the hub itself, else the
+// registered path (e.g. demo-repos/backend), else the basename.
+export function repoLabel(hubRoot, root) {
+  if (root === hubRoot) return 'hub';
+  const r = path.relative(hubRoot, root);
+  return r && !r.startsWith('..') ? r.split(path.sep).join('/') : path.basename(root);
+}
+
+// PURE — group applied reconcile actions by the repo root they wrote to. Each group carries the
+// deduped pathspecs to stage plus the human-readable item labels for the commit body. Actions with
+// no root/paths (e.g. gaps, or a status:'ok' that was force-reapplied without a root) are ignored.
+// Order follows first-encounter, so the hub (its module/_bmad/hub actions come first in reconcile)
+// leads and connected repos follow in registry order.
+export function groupByRoot(actions = []) {
+  const groups = new Map();
+  for (const a of actions) {
+    if (!a || !a.root || !Array.isArray(a.paths) || !a.paths.length) continue;
+    if (!groups.has(a.root)) groups.set(a.root, { root: a.root, paths: new Set(), items: [] });
+    const g = groups.get(a.root);
+    for (const p of a.paths) g.paths.add(p);
+    // Stage every path, but keep only real *changes* in the body list: a `--force` re-copy of an
+    // already-correct file (status 'ok') produces no diff, and the version stamp ('stamp') is implied
+    // by the subject — neither belongs in the "Updated:" list.
+    if (a.status !== 'ok' && a.status !== 'stamp') g.items.push(`${a.scope}/${a.item}`);
+  }
+  return [...groups.values()].map((g) => ({ root: g.root, paths: [...g.paths], items: g.items }));
+}
+
+// PURE — the update commit message. Subject `chore(yad-update): sync SDLC install to yadflow vX.Y.Z`
+// passes the commit-message gate (valid type `chore`, lowercase scope, non-empty description, no
+// trailing period) and the `chore` type makes it an exempt maintenance commit for the story-linking
+// gates. Deliberately NO `[skip ci]` (we want the yad-update-guard integrity workflow to run), NO
+// Task trailer, NO Co-Authored-By. Body lists the changed items; each is a `- ` bullet (never a
+// `key: value` line) so `git interpret-trailers` can't mistake it for a trailer.
+export function buildUpdateMessage({ version = VERSION, items = [] } = {}) {
+  const subject = oneLine(`chore(yad-update): sync SDLC install to yadflow v${version}`);
+  const body = items.length ? `Updated:\n${items.map((i) => `- ${oneLine(i)}`).join('\n')}` : '';
+  return body ? `${subject}\n\n${body}` : subject;
+}
+
+// Stage exactly `paths` under `root`, keeping only pathspecs safe to hand `git add`:
+//   - not git-ignored (naming an ignored path to `git add` is a hard error, not a no-op — so a
+//     consumer repo that .gitignores .claude/ or the repomix code-context cache is respected), AND
+//   - present in the working tree (an add/modify) OR tracked in the index (so a deletion — e.g. a
+//     legacy rename's old file — stages) — this also drops a no-match pathspec (the root
+//     .gitlab-ci.yml a github repo never has) that would otherwise abort `git add`.
+// Returns the pathspecs actually staged.
+function stageAllowlist(git, root, paths) {
+  const keep = paths.filter((p) => {
+    if (run('git', ['check-ignore', '-q', '--', p], { cwd: root }).ok) return false;
+    if (fs.existsSync(path.join(root, p))) return true;
+    return run('git', ['ls-files', '--error-unmatch', '--', p], { cwd: root }).ok;
+  });
+  if (!keep.length) return { staged: [] };
+  // `git add` can exit non-zero (index lock, permissions) yet run() never throws — surface it rather
+  // than silently reporting "nothing to commit". (A directory pathspec whose contents are ALL ignored
+  // also exits 1 after staging the rest; the empty-diff below then correctly drops it.)
+  const add = git('add', '--', ...keep);
+  const staged = git('diff', '--cached', '--name-only', '--', ...keep).stdout.split('\n').filter(Boolean);
+  return { staged, addError: !add.ok ? (add.stderr.split('\n')[0] || `exit ${add.code}`) : null };
+}
+
+// Commit (and, with push, push) one repo group. `defaultBranch` is the repo's configured default
+// (hub.default_branch / repo.default_branch); falls back to origin/HEAD then 'main'. Returns a small
+// result object; never throws. On any hard error it sets process.exitCode so the CLI reports failure.
+export function commitAndPush(group, { push = false, allowBranch = false, hubRoot, defaultBranch } = {}) {
+  const { root, paths, items } = group;
+  const label = repoLabel(hubRoot ?? root, root);
+  const git = hubGit(root);
+
+  // `root` must be the TOP of its OWN git repo — not merely "inside a work tree". A registered repo
+  // whose clone is missing (reconcile's apply() happily recreates the wiring files) but whose path
+  // sits under the hub would otherwise report inside-work-tree=true against the HUB: git resolves the
+  // pathspecs relative to cwd, so we would stage the connected repo's files into the HUB's index and
+  // push them to the HUB's remote, mislabeled. Require the worktree top to BE this root.
+  const top = git('rev-parse', '--show-toplevel');
+  const sameRepo = top.ok && (() => {
+    try { return fs.realpathSync(top.stdout) === fs.realpathSync(root); } catch { return false; }
+  })();
+  if (!sameRepo) {
+    warn(`${label}: not its own git repo (missing/renamed clone?) — skipped (changes left in the working tree)`);
+    return { label, committed: false, skipped: true };
+  }
+  const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
+  const target = defaultBranch || resolveDefaultBranch(git);
+
+  if (branch !== target) {
+    if (allowBranch) {
+      warn(`${label}: on '${branch}', not default '${target}' — --allow-branch: commit/push go to origin/${branch}`);
+    } else {
+      warn(`${label}: on '${branch}', not the default branch '${target}' — skipped (switch to '${target}' or pass --allow-branch)`);
+      return { label, committed: false, skipped: true };
+    }
+  }
+
+  const { staged, addError } = stageAllowlist(git, root, paths);
+  if (addError) warn(`${label}: git add reported "${addError}" — staging may be incomplete`);
+  if (!staged.length) { info(`${label}: nothing to commit (unchanged or ignored)`); return { label, committed: false }; }
+
+  // Pushing HEAD lands any local commits ahead of the remote too. Warn before we add ours so the
+  // operator sees unpublished WIP about to ride the update push (never silently publish it).
+  if (push) {
+    const ahead = git('rev-list', '--count', `origin/${branch}..HEAD`);
+    const n = Number(ahead.stdout);
+    if (ahead.ok && n > 0) warn(`${label}: ${n} local commit(s) ahead of origin/${branch} will also be pushed`);
+  }
+
+  const message = buildUpdateMessage({ items });
+  const cm = git('commit', '-m', message, '--', ...staged);
+  if (!cm.ok) {
+    git('reset', '-q', '--', ...staged); // don't leave our allowlist staged for an unrelated commit to sweep up
+    fail(`${label}: git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
+    process.exitCode = 1;
+    return { label, committed: false, error: true };
+  }
+  ok(`${label}: committed ${staged.length} file(s)`);
+
+  if (!push) return { label, committed: true };
+  if (pushWithRebase(root, branch).ok) { ok(`${label}: pushed to origin/${branch}`); return { label, committed: true, pushed: true }; }
+  // The commit already landed locally — a re-run of `yad update --push` would see no drift and skip
+  // this repo, so point the operator at the direct push of the commit that already exists.
+  fail(`${label}: could not push to origin/${branch} — a protected branch, or an unresolvable rebase conflict`);
+  hand(`resolve it in ${label === 'hub' ? '.' : label}, then push the existing commit with \`git push origin ${branch}\``);
+  process.exitCode = 1;
+  return { label, committed: true, pushed: false, error: true };
+}
+
+// Orchestrate the per-repo commit/push over the grouped applied actions, bookended by the announce
+// banners. `defaultBranchFor(root)` yields each repo's configured default branch (undefined ->
+// resolve from the remote). Prints, commits/pushes each group, then the done banner.
+export function commitUpdates(hubRoot, groups, { push = false, allowBranch = false, defaultBranchFor, guardInactiveGitlab } = {}) {
+  if (!groups.length) { info('no committable changes were applied'); return []; }
+
+  const labels = groups.map((g) => repoLabel(hubRoot, g.root));
+  log('');
+  log(c.bold(`yad update — ${push ? 'publishing to default branches' : 'committing locally (no --push)'}`));
+  warn(`about to ${push ? 'commit + push directly to the default branch' : 'commit'} on: ${labels.join(', ')}`);
+  hand('announce the team and pause merges on these repos until this completes');
+
+  const results = [];
+  for (const g of groups) {
+    const r = commitAndPush(g, { push, allowBranch, hubRoot, defaultBranch: defaultBranchFor?.(g.root) });
+    if (push && r.pushed && guardInactiveGitlab?.(g.root)) {
+      hand(`${r.label}: GitLab yad-update-guard is not active — add \`- local: '.gitlab/ci/yad-update-guard.yml'\` to the root .gitlab-ci.yml include (re-run the yad-checks wire step) so this direct-to-default push is gated`);
+    }
+    results.push(r);
+  }
+
+  const pushed = results.filter((r) => r.pushed).length;
+  const committed = results.filter((r) => r.committed).length;
+  const errored = results.filter((r) => r.error).length;
+  const skipped = results.filter((r) => r.skipped).length;
+  log('');
+  if (push) {
+    if (errored || skipped) {
+      // Some repos did NOT receive the update (a push/commit failure, or a branch/clone skip) — do not
+      // signal "all clear". commitAndPush already set process.exitCode on hard errors.
+      warn(`update incomplete — ${pushed}/${groups.length} repo(s) pushed, ${errored} failed, ${skipped} skipped; keep merges paused and finish the rest (see above).`);
+    } else {
+      ok(`update published — ${pushed}/${groups.length} repo(s) pushed; merges can resume`);
+    }
+  } else ok(`update committed locally — ${committed}/${groups.length} repo(s); push with \`yad update --push\``);
+  return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.7.1",
+  "version": "3.8.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/yad-checks/SKILL.md

@@ -96,6 +96,10 @@ Copy from this skill's `templates/`:
   - A **foreign** file occupies that path/name → write to a non-colliding filename
     (`yad-checks.gen.yml`) and ensure its `name:` does not clash. Never merge jobs into a foreign
     workflow; never edit one.
+  - Also install `templates/github/yad-update-guard.yml` → `.github/workflows/yad-update-guard.yml`
+    (marker `# yad-managed: yad-checks`) — the push-on-default integrity gate for direct-to-default
+    commits (`yad update --push`); it runs only `verified-commits` + `commit-message`. Same
+    own-a-file rules as above.
 
   **GitLab** (detect by a root `.gitlab-ci.yml` and/or `.gitlab/ci/*.yml`): install the includable
   fragment `templates/gitlab/yad-checks.gitlab-ci.yml` → `<repo>/.gitlab/ci/yad-checks.yml` (its jobs
@@ -105,6 +109,9 @@ Copy from this skill's `templates/`:
   - Root exists → read its top-level `include:`. Add the `include:` key if absent; append
     `- local: '.gitlab/ci/yad-checks.yml'` if the key exists but the entry is missing; **no-op** if it
     is already listed. Touch nothing else in the root.
+  - Also install `templates/gitlab/yad-update-guard.gitlab-ci.yml` → `<repo>/.gitlab/ci/yad-update-guard.yml`
+    (marker `# yad-managed-include: yad-checks`) — the push-on-default integrity gate — and append
+    `- local: '.gitlab/ci/yad-update-guard.yml'` to the root `include:` the same additive, idempotent way.
   - If the existing YAML cannot be parsed safely → **STOP** and print the exact include snippet for the
     human to paste (graceful degradation — never guess-edit a pipeline you cannot parse).
   - The legacy standalone `templates/gitlab/.gitlab-ci.yml` is retained only for a clean greenfield repo

package/skills/yad-checks/references/check-gates.md

@@ -88,8 +88,11 @@ repo. For each commit in `<base>..HEAD`, two independent checks:
 - **Known author** — the commit's **author email** must appear in `.sdlc/verified-authors`, generated
   by `yad check --fix` from the hub roster's `email`/`emails` fields plus hub.json's
   `verified_authors` list (edit hub.json, never the generated file). Only the author is checked:
-  platform-generated merge/squash commits set the platform as committer, and their integrity is
-  covered by the signature check.
+  platform-generated squash commits keep the PR author (who is on the roster). Two identities are
+  **allowlist-waived but still signature-covered**: the `yad-gate-sync` bot, and any **merge commit**
+  (2+ parents) — a merge's author is whoever pressed merge (often a platform noreply), not a roster
+  human, and its content already passed the PR gate suite. This waiver matters for the push-on-default
+  `yad-update-guard` (§9), which — unlike this PR-triggered gate — sees merge commits.
 
 Degradation is explicit, never silent: a missing allowlist SKIPs the author check with a warning
 (configure roster emails, re-wire); no GitHub/GitLab remote SKIPs the signature check (the badge is a
@@ -174,6 +177,38 @@ that path, and spec-link still proves the story link.
   **FAILS** the change (the thread is frozen until the hotfix debt is paid: artifacts updated + a
   regression test added, then `status: paid`). Thread-scoped — only the affected thread freezes.
 
+## 9. yad-update-guard (`templates/github/yad-update-guard.yml`, `templates/gitlab/yad-update-guard.gitlab-ci.yml`)
+
+The **integrity gate for direct pushes to the default branch**. `yad update --push` (`cli/update-commit.mjs`)
+commits the applied SDLC drift (skills, gate scripts, CI wiring, `verified-authors`) and pushes it
+**straight to the default branch with no PR/MR** — so the `pull_request`/`merge_request` gate suite never
+fires. This workflow is the "skipped from CI **except** verified-commits + the pattern gate" contract: on a
+**push** to the default branch it runs **only** `verified-commits` and `commit-message` over the pushed
+range (`github.event.before..HEAD` / `$CI_COMMIT_BEFORE_SHA..HEAD`, falling back to `HEAD~1` when the
+before-SHA is a zero/unresolvable ref). It is deliberately **not** scoped to `chore(yad-update)` commits:
+**any** direct-to-default commit (a hotfix, a force-push) is then signature- + subject-format-checked, a
+strictly-good invariant. Normal PR merges sail through — merge commits are platform-Verified and
+`commit-message` skips merges. The `yad update --push` commit itself carries **no `[skip ci]`** (unlike the
+machine-state `yad checkpoint`/`gate ci` commits) precisely so this guard runs on it.
+
+Wired into **every connected repo and the hub** (`REPO_WIRING`/`HUB_WIRING` in `cli/manifest.mjs`). On
+GitHub it is a self-contained workflow (`.github/workflows/yad-update-guard.yml`, marker `# yad-managed:
+yad-checks`), gated to the default branch by a job-level `if: github.ref_name ==
+github.event.repository.default_branch`. On GitLab it is an includable fragment
+(`.gitlab/ci/yad-update-guard.yml`, marker `# yad-managed-include: yad-checks`) whose jobs run on
+`$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH`; its `include:` line
+(`- local: '.gitlab/ci/yad-update-guard.yml'`) is added to the root `.gitlab-ci.yml` the same additive way
+as the other fragments (see *Sync with existing CI* below). **On GitLab the fragment is inert until that
+include line exists** — `yad update --push` warns when it pushes to a gitlab repo whose root pipeline
+lacks it.
+
+**Prerequisites / caveats.** Direct pushes to the default branch must be permitted for the committer
+(adjust branch protection). The commits `yad update --push` creates must be **signed** and their author
+**allowlisted**, or this guard rejects them — `yad update --push` runs a pre-flight that warns when local
+commit signing is unset or the operator's git email is not in `.sdlc/verified-authors`. Ordinary PR merges
+pass (merge commits are allowlist-waived + Verified), but a **rebase-merge** recreates the PR commits
+without the platform signature, so a rebase-merge team should sign commits or not wire this guard.
+
 ## CI wiring (both platforms)
 
 The gates run identically under either CI; the config just invokes the scripts with the PR/MR base.

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

@@ -100,7 +100,15 @@ while IFS= read -r sha; do
   is_bot=0
   case "${author}|$(git log -1 --format=%an "$sha" | tr '[:upper:]' '[:lower:]')" in *yad-gate-sync*) is_bot=1 ;; esac
 
-  if [ "$authors_on" = 1 ] && [ "$is_bot" = 0 ]; then
+  # A merge commit (2+ parents) is authored by whoever pressed "merge" — often a platform noreply
+  # address, not a roster human — while its CONTENT already passed the PR gate suite. Waive the
+  # allowlist for it (like the bot), but STILL require the signature below: a platform merge commit is
+  # Verified, so a locally-forged merge pushed direct-to-default cannot dodge the check. This matters
+  # for the push-on-default yad-update-guard, which (unlike the PR-triggered gates) sees merge commits.
+  is_merge=0
+  [ "$(git log -1 --format=%P "$sha" | wc -w | tr -d '[:space:]')" -ge 2 ] && is_merge=1
+
+  if [ "$authors_on" = 1 ] && [ "$is_bot" = 0 ] && [ "$is_merge" = 0 ]; then
     # tolerate CRLF / stray surrounding whitespace in a hand-edited allowlist
     if grep -vE '^[[:space:]]*(#|$)' "$ALLOWLIST" | tr -d '\r' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' \
         | tr '[:upper:]' '[:lower:]' | grep -qxF "$author"; then
@@ -111,6 +119,8 @@ while IFS= read -r sha; do
     fi
   elif [ "$is_bot" = 1 ]; then
     echo "PASS [verified-commits]: ${short} gate-sync bot — allowlist waived (signature still required)"
+  elif [ "$is_merge" = 1 ]; then
+    echo "PASS [verified-commits]: ${short} merge commit — allowlist waived (signature still required)"
   fi
 
   if [ -n "$platform" ]; then

package/skills/yad-checks/templates/github/yad-update-guard.yml

@@ -0,0 +1,48 @@
+# yad-managed: yad-checks
+# yad-update-guard — integrity gate for DIRECT pushes to the default branch.
+#
+# `yad update --push` commits the applied SDLC drift (skills, gate scripts, CI wiring, verified-
+# authors) and pushes it straight to the default branch with NO pull request — so the pull_request
+# gate suite never fires. This workflow is the "skipped from CI EXCEPT verified-commits + the pattern
+# gate" contract: on every push to the default branch it runs ONLY those two gates over the pushed
+# range. It is not scoped to yad-update commits on purpose — ANY direct-to-main commit (a hotfix, a
+# force-push) then gets signature + subject-format checked, which is a strictly-good invariant. A
+# normal PR merge sails through: a GitHub merge/squash commit is platform-Verified, verified-commits.sh
+# waives the allowlist for merge commits (whose author is whoever clicked merge), and commit-message.sh
+# skips merges. CAVEAT: a *rebase-merge* recreates the PR commits WITHOUT GitHub's signature, so they
+# lose the Verified badge and fail the signature check on the direct push — teams using rebase-merge
+# should sign their commits or not wire this guard.
+name: yad-update-guard
+on:
+  push:
+    branches: ["**"]
+
+permissions:
+  contents: read
+
+jobs:
+  update-guard:
+    # Only the default branch — pushes to feature branches are reviewed via their PR gate suite.
+    if: github.ref_name == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }} # read-only: gh api commits/<sha> for the Verified badge
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - name: Resolve the pushed range base
+        id: base
+        run: |
+          before="${{ github.event.before }}"
+          # First push / branch create / an unfetched before-SHA: fall back to the commit's parent.
+          # This checks only the tip commit (HEAD~1..HEAD) — a rare fail-open for the multi-commit
+          # first-push case, preferred over failing closed on a missing ref.
+          if [ -z "$before" ] || [ "$before" = "0000000000000000000000000000000000000000" ] \
+             || ! git rev-parse --verify --quiet "${before}^{commit}" >/dev/null; then
+            before="$(git rev-parse --verify --quiet HEAD~1 || git rev-parse HEAD)"
+          fi
+          echo "base=$before" >> "$GITHUB_OUTPUT"
+      - name: verified-commits
+        run: bash checks/verified-commits.sh "${{ steps.base.outputs.base }}"
+      - name: commit-message
+        run: bash checks/commit-message.sh "${{ steps.base.outputs.base }}"

package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml

@@ -0,0 +1,48 @@
+# yad-managed-include: yad-checks
+# yad-update-guard — integrity gate for DIRECT pushes to the default branch, as an INCLUDABLE
+# fragment. Pulled into the root .gitlab-ci.yml via:
+#   include:
+#     - local: '.gitlab/ci/yad-update-guard.yml'
+#
+# `yad update --push` commits the applied SDLC drift and pushes it straight to the default branch with
+# NO merge request — so the MR gate suite never fires. This fragment is the "skipped from CI EXCEPT
+# verified-commits + the pattern gate" contract: on a push pipeline for the default branch it runs
+# ONLY those two gates over the pushed range ($CI_COMMIT_BEFORE_SHA..HEAD). Not scoped to yad-update
+# commits on purpose — ANY direct-to-default commit gets signature + subject-format checked.
+#
+# verified-commits needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope —
+# CI_JOB_TOKEN cannot read the commit-signature API (same requirement as yad-verified-commits).
+# Job names are yad-prefixed with `needs: []` and no `stage:` so they coexist with any other fragment.
+.yad_update_guard_rules:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+.yad_update_guard_base: &yad_update_guard_base
+  tags: [$YAD_RUNNER_TAGS]
+  image: node:20
+  variables:
+    GIT_DEPTH: "0" # full history so the gates can diff the pushed range
+  before_script:
+    # First push / an unresolvable before-SHA: fall back to the commit's parent (tip commit only —
+    # a rare fail-open for a multi-commit first push, preferred over failing closed).
+    - |
+      BASE="$CI_COMMIT_BEFORE_SHA"
+      if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ] \
+         || ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
+        BASE="$(git rev-parse --verify --quiet HEAD~1 || git rev-parse HEAD)"
+      fi
+      export BASE
+
+yad-update-guard-verified-commits:
+  <<: *yad_update_guard_base
+  extends: .yad_update_guard_rules
+  needs: []
+  script:
+    - bash checks/verified-commits.sh "$BASE"
+
+yad-update-guard-commit-message:
+  <<: *yad_update_guard_base
+  extends: .yad_update_guard_rules
+  needs: []
+  script:
+    - bash checks/commit-message.sh "$BASE"

package/skills/yad-docs-overview/references/pipeline-model.md

@@ -66,7 +66,7 @@ Per-story, per-repo: `spec → tasks → implement → checks → engineer-revie
 |--------------|------------------------|
 | `yad-spec` | `specs/<story-id>/` (Spec Kit layout), `link.md` |
 | `yad-implement` | a branch + commit per atomic task |
-| `yad-checks` | `checks/*.sh`, CI workflows — the gate set: `spec-link · contract-check · build-test-lint · verified-commits · commit-message · pr-title · pr-template · lineage-check · epic-open · reconcile-debt` |
+| `yad-checks` | `checks/*.sh`, CI workflows — the gate set: `spec-link · contract-check · build-test-lint · verified-commits · commit-message · pr-title · pr-template · lineage-check · epic-open · reconcile-debt`, plus `yad-update-guard` (push-on-default: re-checks any direct-to-default commit with `verified-commits · commit-message`) |
 | `yad-pr-template` | PR/MR template + routing helpers |
 | `yad-commit` / `yad-open-pr` / `yad-ship` | one commit / one PR/MR |
 | `yad-engineer-review` | engineer review + ship recorded in `build-log.json` |

package/skills/yad-hub-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml

@@ -55,6 +55,11 @@ yad-gate-sync:
     # Pinned glab binary (node:20 has no glab). Alternative: image registry.gitlab.com/gitlab-org/cli.
     - GLAB_VERSION=1.55.0
     - curl -fsSL "https://gitlab.com/gitlab-org/cli/-/releases/v${GLAB_VERSION}/downloads/glab_${GLAB_VERSION}_linux_amd64.deb" -o /tmp/glab.deb && dpkg -i /tmp/glab.deb
+    # Pinned jq binary (node:20 has none, and `glab api` has NO built-in --jq like `gh api` does —
+    # it errors "unknown flag: --jq"). We fetch raw JSON from glab and filter it through real jq;
+    # jq streams glab's concatenated per-page --paginate arrays natively.
+    - JQ_VERSION=1.7.1
+    - curl -fsSL "https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}/jq-linux-amd64" -o /usr/local/bin/jq && chmod +x /usr/local/bin/jq
     - git config user.name "yad-gate-sync" && git config user.email "yad-gate-sync@noreply.${CI_SERVER_HOST}"
     - git remote set-url origin "https://oauth2:${SDLC_GATE_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
     - export GITLAB_TOKEN="$SDLC_GATE_TOKEN" GITLAB_HOST="$CI_SERVER_URL"
@@ -73,8 +78,8 @@ yad-gate-sync:
         # runs in a subshell, losing rc). An MR stuck beyond the window needs manual recovery — run
         # `yad gate ci --branch <review-branch> --pr <iid> --merged` locally on the default branch.
         SINCE="$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-7d +%Y-%m-%dT%H:%M:%SZ)"
-        glab api --paginate "projects/:id/merge_requests?state=merged&updated_after=${SINCE}&per_page=100&order_by=updated_at" \
-          --jq '.[] | select(.source_branch | startswith("review/EP-")) | "\(.iid) \(.source_branch)"' > /tmp/yad-merged-mrs || rc=1
+        glab api --paginate "projects/:id/merge_requests?state=merged&updated_after=${SINCE}&per_page=100&order_by=updated_at" > /tmp/yad-raw-mrs 2>/dev/null || rc=1
+        jq -r '.[] | select(.source_branch | startswith("review/EP-")) | "\(.iid) \(.source_branch)"' /tmp/yad-raw-mrs > /tmp/yad-merged-mrs || rc=1
         while read -r IID REF; do
           [ -n "$IID" ] || continue
           git checkout -q -B "$CI_DEFAULT_BRANCH" "origin/$CI_DEFAULT_BRANCH"
@@ -85,7 +90,9 @@ yad-gate-sync:
         # IID from its source branch so `gate ci` can re-read approvals, then advance there.
         REVIEW_BRANCH="$(printf '%s' "$CI_COMMIT_MESSAGE" | grep -oE 'review/EP-[A-Za-z0-9._/-]+' | head -n1 || true)"
         if [ -n "$REVIEW_BRANCH" ]; then
-          IID="$(glab api "projects/:id/merge_requests?source_branch=${REVIEW_BRANCH}&state=merged" --jq '.[0].iid' 2>/dev/null || true)"
+          # `.[0].iid // empty` so an empty MR array yields an empty IID (jq prints "null" otherwise),
+          # which keeps the "could not resolve" branch below correct.
+          IID="$(glab api "projects/:id/merge_requests?source_branch=${REVIEW_BRANCH}&state=merged" 2>/dev/null | jq -r '.[0].iid // empty' || true)"
           if [ -n "$IID" ]; then
             # Pass --pr + IID as two distinct args (avoid a fragile, shell-dependent ${IID:+...} split).
             npx -y -p yadflow@3 yad gate ci --branch "$REVIEW_BRANCH" --pr "$IID" --merged || rc=1