yadflow 3.15.4 → 3.16.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+# [3.16.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.5...v3.16.0) (2026-08-12)
+
+
+### Bug Fixes
+
+* **pr-template:** name GitLab's 2700-character description truncation ([475e2b7](https://github.com/abdelrahmannasr/yadflow/commit/475e2b7db8f0d24909ce5c874122f18dc6508985)), closes [#164](https://github.com/abdelrahmannasr/yadflow/issues/164)
+* **update:** reject an unusable provenance record instead of ignoring it ([5107381](https://github.com/abdelrahmannasr/yadflow/commit/5107381ae2c08b261fddda76433cfc2a3fe3ea46)), closes [#188](https://github.com/abdelrahmannasr/yadflow/issues/188) [#164](https://github.com/abdelrahmannasr/yadflow/issues/164)
+
+
+### Features
+
+* **update:** never silently overwrite a locally modified managed file ([28d6ee4](https://github.com/abdelrahmannasr/yadflow/commit/28d6ee4c1af250415c3ad50d999a263ebe91cd83)), closes [#164](https://github.com/abdelrahmannasr/yadflow/issues/164)
+
+## [3.15.5](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.4...v3.15.5) (2026-08-12)
+
+
+### Bug Fixes
+
+* **bridge:** resolve the wired gate-sync pin from the repo, not a floating major ([8489bf5](https://github.com/abdelrahmannasr/yadflow/commit/8489bf5298f529868dc65085068882b59e89bbb5)), closes [#163](https://github.com/abdelrahmannasr/yadflow/issues/163) [#163](https://github.com/abdelrahmannasr/yadflow/issues/163)
+* **checks:** require a platform for the ledger-guard bridge gate ([297d13a](https://github.com/abdelrahmannasr/yadflow/commit/297d13a0ebf26bec995ce64e0aacfa022b228e18)), closes [#185](https://github.com/abdelrahmannasr/yadflow/issues/185) [#186](https://github.com/abdelrahmannasr/yadflow/issues/186)
+* **checks:** scope the ledger-guard bridge read to root-level keys ([4fb83a9](https://github.com/abdelrahmannasr/yadflow/commit/4fb83a968d4537e89a9367d72418aede9cf305f0)), closes [#186](https://github.com/abdelrahmannasr/yadflow/issues/186) [#186](https://github.com/abdelrahmannasr/yadflow/issues/186)
+
 ## [3.15.4](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.3...v3.15.4) (2026-08-12)
 
 ## [3.15.3](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.2...v3.15.3) (2026-08-11)

package/README.md

@@ -65,6 +65,11 @@ Every step stops at a gate until a human approves. New here? **Walk it lesson-by
 
 Running `yad` tells you when a new release is out — upgrade with `npm install yadflow -g`, then
 `yad update` to re-sync this project's skills. See [staying up to date](docs/CLI.md#staying-up-to-date).
+An update rewrites the files yad manages (gate scripts, CI, PR/MR templates) — but not one **you**
+edited: yad records the sha of every file it writes, so an edit to one is reported as `modified` and
+left alone. A file it has no record of (an install predating that record) is still replaced, but only
+after saving a `.yad-orig` backup
+([managed files](docs/CLI.md#managed-files-what-yad-owns-and-what-you-edited)).
 
 ## What `npx yadflow setup` installs
 

package/bin/yad.mjs

@@ -30,11 +30,15 @@ ${c.bold('Setup & maintenance')}
   yad setup            Guided first-run setup (profile interview, install, connect & wire repos)
                        profile flags: --solo | --team <n>, --greenfield | --brownfield,
                        --monorepo | --separate, --tools (configure design/testing/learning now)
-  yad check            Report what is missing / drifted / stale / legacy (read-only)
+  yad check            Report what is missing / drifted / modified / stale / legacy (read-only)
   yad check --fix      Reconcile: fill what is missing, update what changed
   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
+                       and migrates pre-2.0 sdlc-* installs to the yad-* names.
+                       A managed file whose edit yad can prove (its recorded sha) is
+                       reported 'modified' and left alone; --overwrite-local replaces
+                       it. Anything else it cannot account for is replaced only after
+                       a <file>.yad-orig backup
   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
@@ -159,6 +163,8 @@ ${c.bold('Options')}
   --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 / repo refresh --push: allow committing on a non-default branch
+  --overwrite-local     check --fix / update: replace managed files reported as 'modified'
+                        (a <file>.yad-orig backup is written first)
   -h, --help            Show this help
   -v, --version         Print version
 
@@ -178,6 +184,7 @@ function parseArgs(argv) {
     else if (a === '--no-push') o.noPush = true;
     else if (a === '--push') o.push = true;
     else if (a === '--allow-branch') o.allowBranch = true;
+    else if (a === '--overwrite-local') o.overwriteLocal = 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
@@ -232,10 +239,10 @@ async function main() {
       });
       break;
     case 'check':
-      await reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, today });
+      await reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
       break;
     case 'update':
-      await reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, today });
+      await reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
       break;
     case 'doctor':
       await runDoctor(o.dir, { json: o.json });

package/cli/doctor.mjs

@@ -62,7 +62,11 @@ export function projectChecks(checks, root) {
   // version stamp
   const ver = readJSON(verPath, null);
   if (!ver) check(checks, 'cli-version', 'project', 'warn', `${PROJECT_FILES.version} missing or unreadable`, 'run `yad check --fix`');
-  else if (ver.version !== VERSION) check(checks, 'cli-version', 'project', 'warn', `project stamped v${ver.version}, CLI is v${VERSION}`, 'run `yad update` to reconcile');
+  // The stamp is not only cosmetic: in bridge mode the wired gate-sync job resolves the yadflow it
+  // RUNS from it — unless hub.json pins `gate_sync_version`, a YAD_VERSION variable overrides, or the
+  // stamp is not an exact release of the current major (then the job skips it and floats). So a stale
+  // stamp can mean CI is running an old gate; say so, or the warning reads as bookkeeping.
+  else if (ver.version !== VERSION) check(checks, 'cli-version', 'project', 'warn', `project stamped v${ver.version}, CLI is v${VERSION} — this also drives the wired gate-sync pin`, 'run `yad update` to reconcile');
   else check(checks, 'cli-version', 'project', 'ok', `version stamp matches (v${VERSION})`);
 
   // hub.json: parse + shape

package/cli/manifest.mjs

@@ -230,6 +230,17 @@ export const REPO_WIRING = {
   ],
 };
 
+// Provenance of the wired files above, per repo root. Wiring files are OURS to rewrite, but "the
+// on-disk copy differs from the shipped template" cannot tell a STALE copy (overwrite it) from one a
+// team deliberately CUSTOMIZED (ask first) — so every write records the sha256 of what it wrote here.
+// On the next update, on-disk == recorded proves the copy is untouched since we wrote it; anything
+// else is a local edit, reported as `modified` and left alone (#164). Committed, so the record
+// travels with the repo instead of living in one person's clone.
+export const MANAGED_LEDGER = '.sdlc/managed.json';
+// Suffix for the copy written beside a managed file before its content is replaced without that
+// proof — the local edit is always recoverable from the working tree, not only from git history.
+export const BACKUP_SUFFIX = '.yad-orig';
+
 export const wiringFor = (platform) => [
   ...REPO_WIRING.common,
   ...(REPO_WIRING[platform] || []),

package/cli/plan.mjs

@@ -3,12 +3,13 @@
 // setup (apply all), update (apply changed), and check (report; fix non-ok) share it.
 import fs from 'node:fs';
 import path from 'node:path';
+import { err } from './errors.mjs';
 import {
-  asset, exists, copyDir, copyFile, dirMatches, sameContent, readJSON,
+  asset, exists, copyDir, copyFile, dirMatches, sameContent, readJSON, readJSONStrict, writeJSON, fileSha,
 } from './lib.mjs';
 import {
-  SKILLS, IDE_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
-  LEGACY_SKILLS, REMOVED_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES,
+  VERSION, SKILLS, IDE_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
+  LEGACY_SKILLS, REMOVED_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES, MANAGED_LEDGER, BACKUP_SUFFIX,
 } from './manifest.mjs';
 
 // A git pathspec (forward slashes, relative to a repo root) for `dest` under `root`. Actions carry
@@ -36,6 +37,83 @@ const dirAction = (scope, item, src, dest, { root } = {}) => ({
   apply: () => copyDir(src, dest),
 });
 
+// ---- managed-file provenance (#164) --------------------------------------------------------
+// Read one repo root's ledger of "files yad wrote, and the sha it wrote". Strict, like every other
+// ledger read: only an ABSENT ledger means "no record" ({}). One that exists but does not parse — or
+// parses into something that is not a `files` map — must throw. Defaulting either to {} would
+// silently downgrade every locally-modified file to an unrecorded one and re-open, one backup short,
+// the silent clobber this record exists to prevent.
+const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export function readManagedLedger(root) {
+  const file = path.join(root, MANAGED_LEDGER);
+  const rec = readJSONStrict(file, null);
+  if (rec === null && !exists(file)) return {};
+  if (!isMap(rec) || !isMap(rec.files)) {
+    // Parses, but is not a record — YAD-STATE-002 (wrong shape), not -001 (does not parse).
+    throw err('YAD-STATE-002', `unreadable provenance record in ${file}: expected an object with a "files" map`,
+      'restore it from git — or delete it to start over, which costs the record (the next update then backs up every managed file it replaces)');
+  }
+  return rec.files;
+}
+
+// Where the pre-overwrite copy of `dest` goes.
+export const backupPathFor = (dest) => `${dest}${BACKUP_SUFFIX}`;
+
+// A wired file (gate script, CI fragment, PR/MR template) — a fileAction plus provenance:
+//   'ok'        bytes are the shipped template
+//   'missing'   not installed
+//   'outdated'  differs, and the recorded sha proves WE wrote what is there (a stale copy) — or the
+//               file predates the ledger (no record at all), in which case nothing is proven and
+//               apply() saves a .yad-orig copy before replacing it
+//   'modified'  differs, and the recorded sha says someone edited our copy — never overwritten by a
+//               plain update; `--overwrite-local` replaces it (after a .yad-orig backup)
+// apply() backs up whenever provenance is not proven, so no unproven content is ever discarded.
+const wiredFileAction = (scope, item, src, dest, { root, exec = false, ledger = {} } = {}) => {
+  const base = fileAction(scope, item, src, dest, { root, exec });
+  const managed = { src, dest, root };
+  if (base.status !== 'outdated') return { ...base, managed };
+  const recorded = ledger[rel(root, dest)];
+  const ours = !!recorded && recorded === fileSha(dest);
+  const backup = ours ? null : backupPathFor(dest);
+  return {
+    ...base,
+    // No record at all is a pre-ledger install, not evidence of an edit: keep the routine upgrade
+    // working (still 'outdated'), but never discard content we cannot prove we wrote — hence backup.
+    status: ours || !recorded ? 'outdated' : 'modified',
+    managed,
+    backup,
+    apply: () => {
+      if (backup) fs.copyFileSync(dest, backup);
+      copyFile(src, dest, { exec });
+    },
+  };
+};
+
+// Persist the provenance of every managed file whose on-disk bytes ARE the shipped template — the
+// ones just applied AND the ones already correct. Seeding the already-correct ones is what migrates
+// an install made before this ledger existed: from then on, an edit to any of them is detectable.
+// A file we skipped as `modified` is deliberately NOT recorded — it is the team's copy, not ours.
+// Keys are sorted so two repos' updates produce mergeable, byte-stable ledgers.
+// Returns the roots written, so the caller can stage them alongside what they describe.
+export function recordManagedWrites(actions = []) {
+  const byRoot = new Map();
+  for (const a of actions) {
+    const m = a?.managed;
+    if (!m || !m.root) continue;
+    if (!sameContent(m.src, m.dest)) continue;
+    if (!byRoot.has(m.root)) byRoot.set(m.root, {});
+    byRoot.get(m.root)[rel(m.root, m.dest)] = fileSha(m.dest);
+  }
+  const roots = [];
+  for (const [root, written] of byRoot) {
+    const files = { ...readManagedLedger(root), ...written };
+    const sorted = Object.fromEntries(Object.keys(files).sort().map((k) => [k, files[k]]));
+    writeJSON(path.join(root, MANAGED_LEDGER), { version: VERSION, files: sorted });
+    roots.push(root);
+  }
+  return roots;
+}
+
 // Persisted state gets one deliberately narrow compatibility repair. Explicit setup/planner input
 // does not: a caller typo is an error, while the known v3.11.1 `.cluade` stamp is safely migrated.
 const PERSISTED_IDE_ALIASES = new Map([['.cluade', '.claude']]);
@@ -371,8 +449,9 @@ export function legacyHubActions(root) {
 // Per-repo wiring (gate scripts, CI, PR template).
 export function repoActions(root, repo) {
   const repoRoot = path.resolve(root, repo.path);
+  const ledger = readManagedLedger(repoRoot);
   return wiringFor(repo.platform).map((w) =>
-    fileAction(repo.name, w.dest, asset(w.src), path.join(repoRoot, w.dest), { root: repoRoot, exec: !!w.exec }),
+    wiredFileAction(repo.name, w.dest, asset(w.src), path.join(repoRoot, w.dest), { root: repoRoot, exec: !!w.exec, ledger }),
   );
 }
 
@@ -383,8 +462,9 @@ export function hubActions(root) {
   // `bridge_enabled` is the canonical flag (the documented hub-config schema); older setup versions
   // wrote `bridge` — accept an explicit true in either spelling, wire nothing otherwise.
   if (!hub?.platform || !(hub.bridge_enabled === true || hub.bridge === true)) return [];
+  const ledger = readManagedLedger(root);
   return [...HUB_WIRING.common, ...(HUB_WIRING[hub.platform] || [])].map((w) =>
-    fileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { root, exec: !!w.exec }),
+    wiredFileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { root, exec: !!w.exec, ledger }),
   );
 }
 

package/cli/reconcile.mjs

@@ -10,18 +10,18 @@ import {
 const readFileSafe = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
 
 import { preflightGuardReadiness } from './hubcommit.mjs';
-import { VERSION, PROJECT_FILES } from './manifest.mjs';
+import { VERSION, PROJECT_FILES, MANAGED_LEDGER, BACKUP_SUFFIX } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
-  ideTargetStateFor,
+  ideTargetStateFor, recordManagedWrites,
 } from './plan.mjs';
 import { gitHead, packRepo } from './setup.mjs';
-import { groupByRoot, commitUpdates } from './update-commit.mjs';
+import { groupByRoot, commitUpdates, repoLabel } 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') };
+const MARK = { missing: c.red('missing'), new: c.cyan('new'), outdated: c.yellow('outdated'), modified: c.cyan('modified'), 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, push = false, allowBranch = false } = {}) {
+export async function reconcile(root, { fix = false, scope = 'all', force = false, push = false, allowBranch = false, overwriteLocal = false } = {}) {
   log(c.bold(`\nSDLC reconcile  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}\n`));
 
@@ -91,7 +91,7 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     if (!byScope.has(a.scope)) byScope.set(a.scope, []);
     byScope.get(a.scope).push(a);
   }
-  const counts = { missing: 0, new: 0, outdated: 0, stale: 0, legacy: 0, removed: 0, ok: 0 };
+  const counts = { missing: 0, new: 0, outdated: 0, modified: 0, stale: 0, legacy: 0, removed: 0, ok: 0 };
   for (const [scopeName, items] of byScope) {
     const notOk = items.filter((i) => i.status !== 'ok');
     items.forEach((i) => counts[i.status]++);
@@ -125,16 +125,29 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     warn('existing .cluade path was left untouched; review its contents and remove it manually');
   }
 
+  // A managed file the team edited is NEVER rewritten by a plain update — that silent clobber is what
+  // #164 reported. It is reported on every run (honest drift) until either the edit is dropped or
+  // `--overwrite-local` replaces it, which still saves the previous content beside it.
+  const modified = actions.filter((a) => a.status === 'modified');
+  for (const m of modified) {
+    warn(`${m.scope}/${m.item} is locally modified — it matches neither the shipped template nor the copy yad wrote`);
+  }
+  if (modified.length && !overwriteLocal) {
+    hand(`keep the edits (reported as \`modified\` on every check), or replace them with \`yad update --overwrite-local\` — each previous version is saved beside the file as <file>${BACKUP_SUFFIX}`);
+  }
+
   const fixable = actions.filter((a) =>
-    a.status !== 'ok' && (scope === 'all' ? true : a.status !== 'missing'),
+    a.status !== 'ok'
+    && (a.status !== 'modified' || overwriteLocal)
+    && (scope === 'all' ? true : a.status !== 'missing'),
   );
   log('');
-  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`));
+  log(c.dim(`summary: ${counts.missing} missing, ${counts.new} new, ${counts.outdated} outdated, ${counts.modified} modified, ${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 };
+    return { counts, gaps, applied: 0, modified: modified.length };
   }
 
   // --- apply --- (collect the applied actions so --push can stage each repo's exact allowlist) ---
@@ -145,16 +158,32 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     a.apply();
     applied++;
     appliedActions.push(a);
-    info(`${a.status} → fixed: ${a.scope}/${a.item}`);
+    // A backup means the replaced content was not provably ours (a pre-ledger install, or an edit
+    // --overwrite-local was told to discard). Never report that as an ordinary template adoption.
+    info(`${a.status} → fixed: ${a.scope}/${a.item}${a.backup ? ` ${c.yellow(`(previous content saved to ${path.basename(a.backup)})`)}` : ''}`);
   }
   if (force) {
+    // --force re-copies what is already correct; it deliberately does NOT reach a `modified` file —
+    // only --overwrite-local discards a local edit, and only after backing it up.
     for (const a of actions.filter((a) => a.status === 'ok')) { a.apply(); appliedActions.push(a); }
   }
   // Refresh the version stamp and persist only the canonical targets used to build actions. This also
   // completes legacy/corrupt target migration even when no skill content itself needed an update.
   writeCanonicalStamp();
   appliedActions.push({ scope: 'hub', item: PROJECT_FILES.version, status: 'stamp', root, paths: [PROJECT_FILES.version] });
+  // Record what we wrote (and what was already correct) so the NEXT update can tell a stale managed
+  // file from an edited one. Seeding the already-correct files is what migrates a pre-ledger install.
+  // A file left as `modified` records nothing — it differs from the template by definition.
+  for (const ledgerRoot of recordManagedWrites(actions)) {
+    appliedActions.push({
+      scope: repoLabel(root, ledgerRoot), item: MANAGED_LEDGER, status: 'stamp',
+      root: ledgerRoot, paths: [MANAGED_LEDGER],
+    });
+  }
   applied ? ok(`reconciled ${applied} item(s)`) : info('nothing to fix');
+  if (modified.length && !overwriteLocal) {
+    warn(`${modified.length} locally modified file(s) left untouched — this update did not reach them`);
+  }
   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 ---
@@ -182,5 +211,5 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
       },
     });
   }
-  return { counts, gaps, applied };
+  return { counts, gaps, applied, modified: modified.length };
 }

package/cli/setup.mjs

@@ -10,7 +10,7 @@ import { VERSION, IDE_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TEST
 import {
   moduleActions, repoActions, hubActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
-  safeIdeTargetsFor, detectedIdeTargetStateFor,
+  safeIdeTargetsFor, detectedIdeTargetStateFor, recordManagedWrites,
 } from './plan.mjs';
 import { validateLogin, rolesForScope } from './platform.mjs';
 
@@ -348,10 +348,16 @@ export function registerLearning(root, { tool, kb = null, today = null } = {}) {
 function applyActions(actions, { force = false } = {}) {
   let changed = 0;
   for (const a of actions) {
+    // A managed file the team edited is left alone here too — setup re-runs with force:true, so
+    // without this the wizard would be a second silent-clobber path for the same edits (#164).
+    if (a.status === 'modified') {
+      warn(`kept locally modified ${a.scope}/${a.item} — replace it with \`yad update --overwrite-local\``);
+      continue;
+    }
     if (a.status === 'ok' && !force) continue;
     a.apply();
     changed++;
-    info(`${a.status === 'missing' ? 'installed' : 'updated'} ${a.scope}/${a.item}`);
+    info(`${a.status === 'missing' ? 'installed' : 'updated'} ${a.scope}/${a.item}${a.backup ? ` (previous content saved to ${path.basename(a.backup)})` : ''}`);
   }
   if (!changed) info('already up to date');
   return changed;
@@ -708,9 +714,14 @@ export async function runSetup(root, opts = {}) {
   S('Wire connected repos + the hub (CI gates, PR template, gate-sync)');
   guide(['Installs the CI safety gates, PR/MR template, and gate-sync — automatic, no input needed.']);
   if (registry.repos.length === 0) info('no repos to wire');
+  // Every managed file this step writes is recorded (sha per repo root) so a LATER `yad update` can
+  // tell a stale copy from one the team edited, instead of silently rewriting both (#164).
+  const wired = [];
   for (const repo of registry.repos) {
     log(`  ${c.bold(repo.name)} ${c.dim(`(${repo.platform})`)}`);
-    applyActions(repoActions(root, repo), { force: true });
+    const repoWiring = repoActions(root, repo);
+    applyActions(repoWiring, { force: true });
+    wired.push(...repoWiring);
     // Migrate pre-2.0 wired CI (marker-owned sdlc-*.yml -> yad-*.yml); a user-authored
     // same-named file is never touched.
     applyActions(legacyRepoActions(root, repo), { force: true });
@@ -720,8 +731,12 @@ export async function runSetup(root, opts = {}) {
   if (hubWiring.length) {
     log(`  ${c.bold('hub')} ${c.dim('(gate-sync + verified-commits CI)')}`);
     applyActions(hubWiring, { force: true });
+    wired.push(...hubWiring);
   }
   applyActions(legacyHubActions(root), { force: true });
+  // After every write to a managed path has landed (including the legacy renames), so the recorded
+  // sha is the file's final state.
+  recordManagedWrites(wired);
   // author allowlists for the verified-commits gate (hub + every repo), from the roster emails
   applyActions(authorsActions(root, registry.repos), { force: true });
 

package/package.json

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

package/skills/yad-checks/SKILL.md

@@ -51,8 +51,11 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
 - Canonical gate sources live in this skill's `templates/` (the source of truth that gets installed
   into each code repo):
   - `templates/checks/{spec-link,contract-check,build-test-lint,verified-commits}.sh`
-  - `templates/checks/ledger-guard.sh` → **hub-only** gate, active **only in bridge mode** (a no-op
-    when humans legitimately own the ledger). On review PRs it FAILs any commit that touches the
+  - `templates/checks/ledger-guard.sh` → **hub-only** gate, active **only in bridge mode** — hub.json
+    carries BOTH a `platform` and `bridge_enabled` (or the legacy `bridge`) true, the same predicate
+    `isBridge` (`cli/gate.mjs`) applies, so the gate and the CLI can never disagree about who owns the
+    ledger (#186). A no-op otherwise, when humans legitimately own it. On review PRs it FAILs any
+    commit that touches the
     CI-owned gate ledger (`.sdlc/{state,approvals,comments,hub-prs}.json`, `reviews/*.md`) unless it
     is a **verified gate-bot commit** — bot-authored AND platform-Verified, since author text alone is
     spoofable. `.sdlc/contract-lock.json` is artifact-side and exempt. So is a **new epic's seed**:

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

@@ -203,6 +203,18 @@ catches a free-form description that bypassed it:
     (`epics/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
     must go through a `review/EP-*` PR.
 
+**GitLab truncates the description this gate reads.** `$CI_MERGE_REQUEST_DESCRIPTION` stops at **2700
+characters**, so a long but perfectly valid MR can lose a required section *before the gate sees it* —
+the author then reads "does not use the template" while looking at a description that visibly contains
+it (#164). GitHub is unaffected (`github.event.pull_request.body` is not truncated). Two mitigations,
+both shipped:
+
+- the GitLab MR templates (`yad-pr-template` `templates/gitlab/…` and `templates/hub/gitlab/…`) carry
+  the constraint as a comment and keep every required section early, so a truncated body still passes;
+- when a required section is missing **and** the body it read is ≥ 2700 characters, the gate prints a
+  `NOTE` naming the truncation and the fix — reorder the required sections above the cutoff and push
+  the long narrative to the end. Never delete a section: reordering is always allowed.
+
 ## 8. Phase 6 — feature-thread gates (`lineage-check.sh`, `epic-open.sh`, `reconcile-debt-check.sh`)
 
 After the contract locks and code ships, a change must not mutate a locked artifact — it becomes a new

package/skills/yad-checks/templates/checks/ledger-guard.sh

@@ -20,16 +20,55 @@
 # distinguishes CI-generated commits. A spoofed-author commit that is not Verified is treated as a
 # human edit and rejected.
 #
-# Scope: enforced ONLY when the bridge is enabled (a platform + gate-sync CI). Without the bridge
-# (file-only / non-bridge) humans legitimately write the ledger locally, so the gate is a no-op.
+# Scope: enforced ONLY when the bridge is enabled — hub.json carries BOTH a `platform` and
+# `bridge_enabled` (or the legacy `bridge`) true, the same predicate `isBridge` (cli/gate.mjs) and
+# `hubActions` (cli/plan.mjs) apply. Without the bridge (file-only / non-bridge, or a platform-less
+# hub) humans legitimately write the ledger locally, so the gate is a no-op.
 #
 # Degradation: a base ref that cannot be resolved FAILs closed; no platform (cannot read the Verified
 # badge) WARNs and waives the signature half — the same stance verified-commits takes.
 set -euo pipefail
 
 # ---- bridge gate: only CI-owned ledgers are guarded -------------------------------------------
+# The predicate is BOTH a platform and the bridge flag, exactly as `isBridge` (cli/gate.mjs) and
+# `hubActions` (cli/plan.mjs) define it. Requiring the flag alone put this gate out of step with every
+# other bridge detector (issue #186): a hub carrying `bridge_enabled: true` with no `platform` would
+# have its human ledger commits rejected here while the CLI, reading the same file, called it
+# file-only and kept the LOCAL write path — no CI writer and no permitted human writer, so no gate
+# could advance. Reachable through a stale install (platform set, script wired, platform later
+# nulled), not through `yad setup`, which derives both from one value.
+#
+# `tr -d '\n'` first, like every other hub.json read in these gates: a key and its value may legally
+# sit on separate lines, and a per-line match would MISS the flag and silently no-op a security gate
+# (the fail-open direction of issue #161).
+#
+# Matched at the ROOT LEVEL only. The shared `default_branch` read below is depth-blind, and that is
+# survivable there — a false match yields a bogus branch name and the gate fails loudly. Here it is
+# not: a nested `"bridge": true` (say under `review`) would silently ENABLE this gate on a hub whose
+# `isBridge` is false, recreating the exact no-writer deadlock #186 is about, from the other side. So
+# the nesting is stripped rather than ignored: peel the outermost braces, then delete innermost
+# objects/arrays until none remain, leaving only root-level pairs to match against. Not a JSON parser
+# — a value containing a literal brace would confuse it — but hub.json is machine-written and the
+# failure it prevents is the one that matters.
+#
+# Flattened ONCE into a variable and matched with here-strings, never `tr … | grep -q`: under the
+# `pipefail` set above, `grep -q` exits at the first match and can SIGPIPE `tr`, which would make a
+# MATCHING pipeline report failure. Reading from a here-string has no upstream process to kill.
 HUB="${SDLC_HUB_CONFIG:-.sdlc/hub.json}"
-if [ ! -f "$HUB" ] || ! grep -Eq '"(bridge_enabled|bridge)"[[:space:]]*:[[:space:]]*true' "$HUB"; then
+HUB_FLAT="$(tr -d '\n' < "$HUB" 2>/dev/null || true)"
+HUB_ROOT="${HUB_FLAT#*\{}"
+HUB_ROOT="${HUB_ROOT%\}*}"
+while :; do
+  _stripped="$(sed -E 's/\{[^{}]*\}//g; s/\[[^][]*\]//g' <<< "$HUB_ROOT")"
+  [ "$_stripped" = "$HUB_ROOT" ] && break
+  HUB_ROOT="$_stripped"
+done
+# One line in, so `sed` emits at most one line out — no `head` needed (which would re-introduce the
+# SIGPIPE-under-pipefail problem this avoids).
+hub_str() { sed -nE "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p" <<< "$HUB_ROOT"; }
+hub_true() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*true" <<< "$HUB_ROOT"; }
+
+if [ ! -f "$HUB" ] || [ -z "$(hub_str platform)" ] || { ! hub_true bridge_enabled && ! hub_true bridge; }; then
   echo "PASS [ledger-guard]: bridge not enabled — the ledger is locally owned, nothing to guard."
   exit 0
 fi

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

@@ -148,7 +148,11 @@ write only `{project-root}/.sdlc/hub.json` (`config.yaml` `hub.config`) — neve
 - **`detect-hub`** — detect the hub's own platform and upsert `.sdlc/hub.json`. Run
   `git remote get-url origin` **on the hub** and read the host with the SAME logic Step 1 uses for code
   repos: `github.com` → `github`, GitLab host → `gitlab`, no remote → `platform: null`. Record
-  `git_url`, `default_branch`, `detectedAt`, and `bridge_enabled: true` (preserve an existing roster).
+  `git_url`, `default_branch`, `detectedAt`, and `bridge_enabled` — **`true` only when a platform was
+  detected, `false` alongside `platform: null`** (preserve an existing roster). The two travel
+  together: bridge mode is a platform AND the flag (`isBridge`, `cli/gate.mjs`), and `yad setup`
+  derives both from one value, so writing the flag onto a platform-less hub creates a state no CLI
+  path can produce and the gates read differently (#186).
   Auth is the local user's own `gh`/`glab`/git; **store no tokens**. Idempotent — safe to re-run.
 - **`roster`** — set one roster entry mapping a platform `login` → SDLC `name` + `email` + a per-scope
   `roles` map (`roles: { hub: ["owner","reviewer"], <repo>: ["domain-owner", …] }`). Upsert by `login`;

package/skills/yad-connect-repos/references/hub-config.md

@@ -18,7 +18,8 @@ login to an SDLC name + role. It is a single object for the hub itself — the s
   "platform": "github",                                       // github | gitlab (from the hub's own remote host); null when local-only
   "git_url": "https://github.com/abdelrahmannasr/yadflow.git", // REQUIRED when platform is non-null (scopes auth + opens PRs); yad doctor warns YAD-CFG-005 if absent
   "default_branch": "main",
-  "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews
+  "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews; travels WITH platform — bridge mode is both (isBridge), so never true beside platform: null (#186)
+  "gate_sync_version": "3.15.3",                              // OPTIONAL exact pin for the wired gate-sync job; an exact 3.x.y, prereleases included (3.16.0-rc.1) — anything else is skipped. Omitted => the .sdlc/cli-version.json stamp if that qualifies, else floating 3
   "review": { "requireEngagement": false },                   // Review Companion: false (soft) counts bare approves but nudges; true counts only verified-engagement approvals
   "detectedAt": "2026-06-08",                                 // last detect-hub run (YYYY-MM-DD)
   "roster": [

package/skills/yad-hub-bridge/SKILL.md

@@ -103,9 +103,12 @@ default branch. (File-only mode keeps `yad gate sync` as the local writer.)
    - GitLab → `.gitlab/ci/yad-gate-sync.yml` (from `templates/gitlab/yad-gate-sync.gitlab-ci.yml`)
    - plus the hub-side **verified-commits** gate (`checks/verified-commits.sh` + its workflow/fragment,
      owned by `yad-checks`) so review PRs accept only signed commits from roster-known authors
-   - the wired job runs `yadflow@${YAD_VERSION}`, defaulting to the floating major `3` so a published
-     fix reaches the schedule on its own. To pin an exact version, set a `YAD_VERSION` CI/CD (GitLab) or
-     Actions (GitHub) **variable** — never edit it into the wired file, which `yad check --fix` rewrites
+   - the wired job runs an **exact** version, resolved at run time from the repo: the `YAD_VERSION`
+     variable, else `hub.json` `gate_sync_version`, else the `.sdlc/cli-version.json` stamp, else the
+     floating `3`. It stopped floating on the major because that let a release change a scheduled job's
+     behaviour unattended — how #163's churn reached hubs that never opted in. So upgrading is now a
+     deliberate act (`yad update`); if the resolved pin predates 3.15.3, upgrade or disable the
+     schedule. Never edit a version into the wired file — `yad check --fix` rewrites it byte-for-byte
      from the template. See `references/bridge.md`.
 2. **GitLab only — two one-time steps** (see the fragment's header for the exact recipes):
    - add `include: - local: '.gitlab/ci/yad-gate-sync.yml'` to the root `.gitlab-ci.yml`, or write

package/skills/yad-hub-bridge/references/bridge.md

@@ -111,6 +111,9 @@ login and requested too — otherwise an escalated step is structurally unsatisf
 reorder commit per epic (the records are the same; only their order changes), then converges
 permanently. On an older yadflow the workaround is to disable the pipeline schedule — merges still
 advance gates via the push path; only the catch-up for squash merges and bare approvals is lost.
+Since the wired job now runs an exact pin rather than floating on the major, that upgrade is a
+deliberate act: `yad update` (which re-stamps `.sdlc/cli-version.json`), or a `gate_sync_version` in
+`hub.json` — see the version table below.
 
 ## Contract re-lock invalidates prior platform approvals too
 
@@ -182,18 +185,32 @@ other way — up through its first review PR/MR; see "the seed of a new epic" be
 **Which yadflow the wired job runs.** Both fragments resolve the version from a `YAD_VERSION` variable
 and fall back to `3`:
 
-| Platform | Where the job reads it | Where you set the pin |
+| # | Source | Set it in |
 |---|---|---|
-| GitHub | workflow `env: YAD_VERSION: ${{ vars.YAD_VERSION \|\| '3' }}` | Settings → Secrets and variables → Actions → **Variables** |
-| GitLab | `npx -y -p "yadflow@${YAD_VERSION:-3}"` | Settings → CI/CD → **Variables** (beside `SDLC_GATE_TOKEN`) |
-
-The default `3` floats on the major, so a published fix reaches a scheduled job on its next pass with
-nobody in the loop — which is how you want a correctness or gate-churn fix to arrive (this page's own
-issue #163 is the example). To adopt releases deliberately instead, set `YAD_VERSION` to an exact
-version.
-The pin lives in **platform config, not in the wired file**: `yad` owns that file and `yad check --fix`
-rewrites it byte-for-byte from the template, so a version edited into it would be silently reverted on
-the next sync. A hub that pins then owns its own upgrade decision — including for fixes.
+| 1 | `YAD_VERSION` — used **verbatim**, the operator's override | GitHub: Settings → Secrets and variables → Actions → **Variables**. GitLab: Settings → CI/CD → **Variables** (beside `SDLC_GATE_TOKEN`) |
+| 2 | `.sdlc/hub.json` → `gate_sync_version` — this hub's committed pin | edit `hub.json`, commit it |
+| 3 | `.sdlc/cli-version.json` → `version` — the yadflow that last wired the hub | `yad update` re-stamps it |
+| 4 | `3` — floating major, only when nothing above resolves | — |
+
+Sources 2 and 3 are **validated** before use: an exact `3.x.y` release token, prereleases included
+(`3.16.0-rc.1` is a legitimate pin; `latest` and a bare `3` are not). A `.sdlc/cli-version.json`
+written by a long-untouched project can still say something like `1.0.2`, a version with no `yad gate ci`
+in it at all, and the value is interpolated into `npx -p "yadflow@$V"` on a runner holding a push token —
+so anything that is not an exact release of this major is skipped, loudly, in favour of the next source.
+`YAD_VERSION` is exempt: it is a human's deliberate act, and it is the only way to cross a major.
+
+**Why this is no longer a floating major.** It used to be, on the argument that a published fix should
+reach a scheduled job with nobody in the loop — this page's own issue #163 as the example. The same
+mechanism is how #163's churn *arrived*: the CI fragment ran `yadflow@3`, so 3.13.1 rolled onto every
+wired hub automatically and took the reporting one from 20 to 96 churn commits an hour, with nobody
+deciding to upgrade. Issue #163's fourth suggested fix was to stop that. The trade-off is real and cuts
+both ways — a hub is no longer carried onto a fix for free, so **if the resolved pin is older than
+3.15.3, run `yad update` or disable the schedule** (`yad doctor` flags a stale stamp).
+
+The pin is **never stamped into the wired file**: `yad` owns that file and `yad check --fix` rewrites it
+byte-for-byte from the template, so a version edited into it would report `outdated` on every check and
+be reverted on the next sync. That is exactly why the job resolves it from committed files at run time
+instead — the fragment itself stays byte-identical to what ships.
 
 **Why no pre-merge write fixes the gate.** Keeping CI off the PR head means an in-flight approval is
 never dismissed by a CI commit, and the PR's required checks never strand on a `[skip ci]` CI commit.
@@ -204,7 +221,10 @@ commit — the advance plus the `draft → approved` status flip — lands on th
 
 **The ledger is CI-owned (bridge mode only).** Humans never commit gate-state files: the `ledger-guard`
 check (yad-checks) FAILs any commit on a review PR that touches `.sdlc/{state,approvals,comments,hub-prs}
-.json` or `reviews/*.md` (`.sdlc/contract-lock.json` is artifact-side and allowed). Under Path B **no
+.json` or `reviews/*.md` (`.sdlc/contract-lock.json` is artifact-side and allowed). "Bridge mode" there
+means the same thing it means everywhere else — a `platform` **and** the bridge flag, `isBridge`'s
+predicate. The gate used to enable itself on the flag alone, which let a platform-less hub reject the
+human's ledger write while the CLI still expected one (#186). Under Path B **no
 CI commit lands in a review PR at all**, so the only ledger change the guard can see there is a human
 edit — which it rejects, with one carve-out for a new epic's seed (below). (The `verified-commits`
 gate still vets every commit's signature + author;

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

@@ -23,7 +23,9 @@
 #   and nothing is committed — re-visiting a merged review for a week costs one no-op read per pass. That
 #   last part is load-bearing: before the #163 fix the re-sync re-appended each step's approvals at the
 #   tail, so this job rotated approvals.json and committed the reorder every 15 minutes, forever (issue
-#   #163). If you pin YAD_VERSION (below) to something older, disable the schedule.
+#   #163). These jobs run an EXACT version resolved from the repo (see the resolver in each job), so a
+#   hub sitting on a pre-#163 yadflow keeps that behaviour until someone upgrades it — if the resolved
+#   pin is older than 3.15.3, run `yad update` or disable the schedule.
 #   On GitHub a scheduled workflow runs automatically once committed (no setup).
 #
 # CI never approves and never merges — the merge click is the human approval act.
@@ -45,13 +47,16 @@ permissions:
   pull-requests: read # gh pr view + reviewThreads GraphQL
 
 env:
-  # Which yadflow these jobs run. The default `3` floats on the major, so a published fix reaches the
-  # schedule on its next pass with nobody in the loop — which is how you want a correctness or
-  # gate-churn fix to arrive. To adopt releases deliberately instead, pin an exact version by setting a
-  # repository (or organization) Actions **variable** named YAD_VERSION to e.g. `3.15.2`:
-  # Settings → Secrets and variables → Actions → Variables. It lives there, deliberately NOT in this
-  # file, which `yad` owns and rewrites on every sync. A pinned hub then owns its own upgrade decision.
-  YAD_VERSION: ${{ vars.YAD_VERSION || '3' }}
+  # The manual override for which yadflow these jobs run: set a repository (or organization) Actions
+  # **variable** named YAD_VERSION to e.g. `3.15.2`, under Settings → Secrets and variables → Actions →
+  # Variables. It lives there and not in this file, which `yad` owns and rewrites byte-for-byte from
+  # its template on every sync — a version edited in here would be silently reverted.
+  #
+  # Left EMPTY the jobs resolve an exact pin from the repo itself instead of floating on the major (see
+  # the resolver step in each job). Floating meant a release could change what a scheduled job does with
+  # nobody deciding to upgrade — the amplification path in issue #163, where 3.13.1 took one hub from 20
+  # to 96 churn commits an hour.
+  YAD_VERSION: ${{ vars.YAD_VERSION || '' }}
 
 jobs:
   mergesync:
@@ -77,6 +82,39 @@ jobs:
       - uses: actions/setup-node@v7
         with:
           node-version: "20"
+      - name: Resolve the yadflow pin
+        run: |
+          # >>> yad-pin
+          # Which yadflow this job runs, most explicit source first:
+          #   1. $YAD_VERSION            — the platform variable, a human's deliberate override, verbatim
+          #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this hub
+          #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
+          #   4. 3                       — floating major, only when nothing above resolves
+          # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
+          # they are VALIDATED: an exact release token of the major this fragment was written for. That
+          # also keeps the value safe to interpolate into `npx -p "yadflow@$V"` — a repo-controlled
+          # string reaching a shell on a runner holding `contents: write` is the same class of hole the
+          # HEAD_REF fix closed. Anything unparseable is skipped loudly rather than failing the run.
+          # Pipes, not bash here-strings, so the block stays byte-identical to the GitLab fragment's
+          # (which must run under `sh` when an image has no bash). `sed` drains its input, so nothing
+          # SIGPIPEs `tr`.
+          yad_pin_read() { # <file> <key>
+            [ -f "$1" ] || return 0
+            tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
+          }
+          yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq '^3\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$'; }
+          YAD_PKG="${YAD_VERSION:-}"
+          if [ -z "$YAD_PKG" ]; then
+            for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+              [ -n "$_cand" ] || continue
+              if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
+              echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact 3.x release." >&2
+            done
+          fi
+          YAD_PKG="${YAD_PKG:-3}"
+          echo "yad-gate-sync: running yadflow@${YAD_PKG}"
+          # <<< yad-pin
+          echo "YAD_PKG=${YAD_PKG}" >> "$GITHUB_ENV"
       - name: Advance the gate on merge
         # The head ref reaches the shell through `env:`, never through `${{ }}` inside `run:`. A
         # branch name may legally contain `$`, backticks and parentheses, so a PR opened from
@@ -88,7 +126,7 @@ jobs:
         run: |
           git config user.name  "yad-gate-sync[bot]"
           git config user.email "yad-gate-sync[bot]@users.noreply.github.com"
-          npx -y -p "yadflow@${YAD_VERSION}" yad gate ci \
+          npx -y -p "yadflow@${YAD_PKG}" yad gate ci \
             --branch "$HEAD_REF" \
             --pr "$PR_NUMBER" \
             --merged
@@ -112,6 +150,39 @@ jobs:
       - uses: actions/setup-node@v7
         with:
           node-version: "20"
+      - name: Resolve the yadflow pin
+        run: |
+          # >>> yad-pin
+          # Which yadflow this job runs, most explicit source first:
+          #   1. $YAD_VERSION            — the platform variable, a human's deliberate override, verbatim
+          #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this hub
+          #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
+          #   4. 3                       — floating major, only when nothing above resolves
+          # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
+          # they are VALIDATED: an exact release token of the major this fragment was written for. That
+          # also keeps the value safe to interpolate into `npx -p "yadflow@$V"` — a repo-controlled
+          # string reaching a shell on a runner holding `contents: write` is the same class of hole the
+          # HEAD_REF fix closed. Anything unparseable is skipped loudly rather than failing the run.
+          # Pipes, not bash here-strings, so the block stays byte-identical to the GitLab fragment's
+          # (which must run under `sh` when an image has no bash). `sed` drains its input, so nothing
+          # SIGPIPEs `tr`.
+          yad_pin_read() { # <file> <key>
+            [ -f "$1" ] || return 0
+            tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
+          }
+          yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq '^3\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$'; }
+          YAD_PKG="${YAD_VERSION:-}"
+          if [ -z "$YAD_PKG" ]; then
+            for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+              [ -n "$_cand" ] || continue
+              if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
+              echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact 3.x release." >&2
+            done
+          fi
+          YAD_PKG="${YAD_PKG:-3}"
+          echo "yad-gate-sync: running yadflow@${YAD_PKG}"
+          # <<< yad-pin
+          echo "YAD_PKG=${YAD_PKG}" >> "$GITHUB_ENV"
       - name: Reconcile recently-merged review PRs
         run: |
           git config user.name  "yad-gate-sync[bot]"
@@ -130,7 +201,7 @@ jobs:
             [ -n "$N" ] || continue
             REF="$(gh pr view "$N" --json headRefName --jq '.headRefName' 2>/dev/null)" || rc=1
             case "$REF" in
-              review/EP-*) npx -y -p "yadflow@${YAD_VERSION}" yad gate ci --branch "$REF" --pr "$N" --merged || rc=1 ;;
+              review/EP-*) npx -y -p "yadflow@${YAD_PKG}" yad gate ci --branch "$REF" --pr "$N" --merged || rc=1 ;;
             esac
           done < /tmp/yad-merged-prs
           exit $rc

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

@@ -36,12 +36,16 @@
 # pipeline or run `yad gate ci --branch <review-branch> --pr <iid> --merged` locally on the default
 # branch (advisory `yad gate sync` is read-only in bridge mode and cannot recover a stuck gate).
 #
-# Which yadflow this job runs: `npx -y -p "yadflow@${YAD_VERSION:-3}"`. The default `3` floats on the
-# major, so a published fix reaches this job on its next run with nobody in the loop — which is how you
-# want a correctness or gate-churn fix to arrive. To adopt releases deliberately instead, pin an exact
-# version by setting a CI/CD variable YAD_VERSION (e.g. `3.15.2`) in project Settings → CI/CD →
-# Variables — the same place SDLC_GATE_TOKEN lives, and deliberately NOT in this file, which `yad`
-# owns and rewrites on every sync. A pinned hub then owns its own upgrade decision.
+# Which yadflow this job runs: an EXACT version resolved from the repo at run time — see the `yad-pin`
+# block in the script below for the precedence. It no longer floats on the major, because floating let a
+# release change what a scheduled job does with nobody deciding to upgrade (issue #163, where 3.13.1
+# took one hub from 20 to 96 churn commits an hour). The trade-off is deliberate and cuts both ways: a
+# hub is no longer carried onto a fix automatically, so if the resolved pin is older than 3.15.3, run
+# `yad update` or disable this schedule.
+#
+# To override it, set a CI/CD variable YAD_VERSION (e.g. `3.15.2`) in project Settings → CI/CD →
+# Variables — the same place SDLC_GATE_TOKEN lives, and deliberately NOT in this file, which `yad` owns
+# and rewrites byte-for-byte from its template on every sync.
 variables:
   GIT_DEPTH: "0" # full history: gate ci pushes the advance to the default branch
 
@@ -82,6 +86,37 @@ yad-gate-sync:
     - export GITLAB_TOKEN="$SDLC_GATE_TOKEN" GITLAB_HOST="$CI_SERVER_URL"
     - git fetch origin "$CI_DEFAULT_BRANCH"
     - git checkout -B "$CI_DEFAULT_BRANCH" "origin/$CI_DEFAULT_BRANCH"
+    - |
+      # >>> yad-pin
+      # Which yadflow this job runs, most explicit source first:
+      #   1. $YAD_VERSION            — the CI/CD variable, a human's deliberate override, verbatim
+      #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this hub
+      #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
+      #   4. 3                       — floating major, only when nothing above resolves
+      # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
+      # they are VALIDATED: an exact release token of the major this fragment was written for. That
+      # also keeps the value safe to interpolate into `npx -p "yadflow@$V"` — a repo-controlled
+      # string reaching a shell on a runner holding a push token. Anything unparseable is skipped
+      # loudly rather than failing the run. Resolved once here; GitLab runs every `script` line in
+      # the same shell, so YAD_PKG carries into the block below.
+      # Pipes, not bash here-strings: a GitLab runner falls back to `sh` when the image has no bash,
+      # and `<<<` is a bashism. `sed` drains its input (no early exit, so nothing SIGPIPEs `tr`).
+      yad_pin_read() { # <file> <key>
+        [ -f "$1" ] || return 0
+        tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
+      }
+      yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq '^3\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$'; }
+      YAD_PKG="${YAD_VERSION:-}"
+      if [ -z "$YAD_PKG" ]; then
+        for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+          [ -n "$_cand" ] || continue
+          if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
+          echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact 3.x release." >&2
+        done
+      fi
+      YAD_PKG="${YAD_PKG:-3}"
+      echo "yad-gate-sync: running yadflow@${YAD_PKG}"
+      # <<< yad-pin
     - |
       rc=0
       if [ "$CI_PIPELINE_SOURCE" = "schedule" ]; then
@@ -91,7 +126,8 @@ yad-gate-sync:
         # unchanged approval record produces an unchanged file and nothing is committed. That last part
         # is load-bearing — before the #163 fix the re-sync re-appended each step's approvals at the
         # tail, so this loop rotated approvals.json and committed the reorder on every pass, forever
-        # (issue #163). If you are on an older yadflow, disable this schedule.
+        # (issue #163). This job runs an exact pin resolved from the repo, so a hub still sitting on a
+        # pre-3.15.3 yadflow keeps that behaviour — upgrade it or disable this schedule.
         # A stuck review MR (a squash merge whose commit dropped the branch name, or a failed merge
         # push) is always RECENT, so sweep a generous recent window and PAGINATE it fully (--paginate)
         # — this bounds cost without the old hard 50-row cap that could permanently strand older MRs.
@@ -105,7 +141,7 @@ yad-gate-sync:
         while read -r IID REF; do
           [ -n "$IID" ] || continue
           git checkout -q -B "$CI_DEFAULT_BRANCH" "origin/$CI_DEFAULT_BRANCH"
-          npx -y -p "yadflow@${YAD_VERSION:-3}" yad gate ci --branch "$REF" --pr "$IID" --merged || rc=1
+          npx -y -p "yadflow@${YAD_PKG}" yad gate ci --branch "$REF" --pr "$IID" --merged || rc=1
         done < /tmp/yad-merged-mrs
       else
         # MERGE push to the default branch whose commit names a review branch: resolve the merged MR's
@@ -117,7 +153,7 @@ yad-gate-sync:
           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@${YAD_VERSION:-3}" yad gate ci --branch "$REVIEW_BRANCH" --pr "$IID" --merged || rc=1
+            npx -y -p "yadflow@${YAD_PKG}" yad gate ci --branch "$REVIEW_BRANCH" --pr "$IID" --merged || rc=1
           else
             # Without the IID, gate ci cannot re-read approvals — fail visibly (the scheduled sweep
             # retries) rather than running a green no-op that silently leaves the gate unadvanced.

package/skills/yad-pr-template/SKILL.md

@@ -26,6 +26,18 @@ touched domain). This step **never auto-advances**; it sets up the template and
     `templates/hub/gitlab/merge_request_templates/Default.md` →
     `{project-root}/.gitlab/merge_request_templates/Default.md`. The hub body carries no `Task:` trailer
     (hub PRs change artifacts, not code); its routing helper is `yad-hub-bridge`'s `hub-route.sh`.
+- **GitLab reads a truncated description.** The `pr-template` gate is fed
+  `$CI_MERGE_REQUEST_DESCRIPTION`, which GitLab cuts at **2700 characters** — a required section below
+  that cutoff is invisible to the gate even though the MR shows it, and the failure reads "does not use
+  the template" (#164). Both GitLab templates say so in a comment and keep `## Summary` /
+  `## Impact & Risk` / `## Checklist` (hub: `## Artifact under review` / `## Impact & Risk (front-half)`
+  / `## Checklist`) early, so a truncated body still passes. Long narrative goes **after** them.
+  Sections may be reordered freely; deleting one fails the gate. GitHub is unaffected.
+- **Installed templates are yad-managed.** `yad update` rewrites them on upgrade. An edit yad can
+  prove — the file's sha differs from the one it recorded when it wrote the template — is reported as
+  `modified` and left alone; a copy it has no record of is replaced after a `.yad-orig` backup (see
+  `docs/CLI.md` → *Managed files*). Either way, put knowledge that must survive an upgrade in an ADR
+  under `docs/`, not in the template.
 - The Impact & Risk block reuses the conventions of earlier steps: the `Task: <story>-<task>` trailer
   (`yad-implement`), the contract surface (`yad-architecture` / contract-check), and the
   domain-owner escalation (`yad-review-gate`).

package/skills/yad-pr-template/templates/checks/pr-template.sh

@@ -45,6 +45,18 @@ if [ -z "$BODY" ] || [ ! -f "$BODY" ]; then
   exit 1
 fi
 
+# GitLab TRUNCATES $CI_MERGE_REQUEST_DESCRIPTION at 2700 characters, so a long-but-valid description
+# can lose a required section before this gate ever reads it — the author then sees "does not use the
+# template" while looking at an MR that visibly contains it (#164). Measure the RAW body now (the
+# trailer strip below shortens it) so a failure at that boundary can say so. GitHub bodies are not
+# truncated, so the note is advisory and only ever printed alongside a real failure.
+GITLAB_DESC_LIMIT=2700
+# CHARACTERS, not bytes — GitLab counts characters, and a description full of multibyte punctuation
+# (an em-dash costs 3 bytes) would hit 2700 bytes long before it could ever be truncated. `wc -m`
+# would need a UTF-8 locale we cannot assume across CI images, so count UTF-8 code points the
+# locale-independent way: every byte that is NOT a continuation byte (0x80-0xBF) starts one.
+RAW_CHARS="$(LC_ALL=C tr -d '\200-\277' < "$BODY" | wc -c | tr -d '[:space:]')"
+
 # The Review Companion injects a `<!-- yad:trailer --> … <!-- /yad:trailer -->` briefing block (and
 # `<!-- yad:noblock -->` notes) into the description. Strip those before the template check so the
 # AI-generated prose can never hide a required section heading or be mistaken for the `Risk level:`
@@ -110,5 +122,10 @@ else
   check_code_body
 fi
 
+if [ "$rc" != 0 ] && [ "$RAW_CHARS" -ge "$GITLAB_DESC_LIMIT" ]; then
+  echo "NOTE [pr-template]: the description this gate read is ${RAW_CHARS} characters. On GitLab the gate reads \$CI_MERGE_REQUEST_DESCRIPTION, which is TRUNCATED at ${GITLAB_DESC_LIMIT} — a section below that cutoff is invisible here even though the MR shows it."
+  echo "NOTE [pr-template]: if the missing section IS in your description, move the required sections above the cutoff (reorder, never delete) and push the long narrative to the end."
+fi
+
 [ "$rc" = 0 ] && echo "PASS [pr-template]: body uses the ${KIND} template (required sections present)."
 exit "$rc"

package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md

@@ -1,4 +1,8 @@
 <!-- SDLC MR template (Phase 3 build plan §D). One atomic task per MR. -->
+<!-- GITLAB 2700-CHARACTER LIMIT: the yad-pr-template gate reads $CI_MERGE_REQUEST_DESCRIPTION, which
+     GitLab truncates at 2700 characters — a heading past the cutoff reads as missing even though you
+     can see it here. Keep Summary, Impact & Risk (with its filled risk-level line) and Checklist
+     within the first 2700 characters; put long narrative below them. Reorder, never delete. -->
 
 ## Summary
 <!-- What this MR does, in one or two sentences. -->

package/skills/yad-pr-template/templates/hub/gitlab/merge_request_templates/Default.md

@@ -2,6 +2,9 @@
 <!-- This MR is a REVIEW VEHICLE on the product hub, not a code merge. The file gate (yad-review-gate)
      advances the step; do NOT rely on merging this MR to advance. Reviewers approve/comment here, then a
      `yad-review-gate action: sync` pulls that into the file ledger. -->
+<!-- GITLAB 2700-CHARACTER LIMIT: the yad-pr-template gate reads $CI_MERGE_REQUEST_DESCRIPTION, which
+     GitLab truncates at 2700 characters — a heading past the cutoff reads as missing. The required
+     sections come first for that reason; keep long narrative last. Reorder, never delete. -->
 
 ## Artifact under review
 - Epic: `EP-<slug>`
@@ -9,14 +12,20 @@
 - Gate step: `<epic-review | architecture-review | ui-design-review | stories-review>`
 - Owner: `<epic.md owner>`
 
-## What changed
-<!-- One or two sentences on what this artifact says / what changed since the last review round. -->
-
 ## Impact & Risk (front-half)
 - **Domains / repos touched:** <epic.repos, e.g. backend, mobile>
 - **Risk tags:** <none | contract | auth | payments>  <!-- contract/auth/payments => escalates to domain owners -->
 - **Contract surface:** <n/a | locked @ sha256:…>  <!-- architecture only; a re-lock invalidates prior approvals -->
 
+## Checklist
+- [ ] `owner` set in the artifact frontmatter (inherited from `epic.md`)
+- [ ] Contract re-locked (`.sdlc/contract-lock.json`) if the surface changed (architecture only)
+- [ ] Risk tags reflect the real surface touched (contract/auth/payments escalate)
+- [ ] No secrets or tokens in the artifact or this description
+
+## What changed
+<!-- One or two sentences on what this artifact says / what changed since the last review round. -->
+
 ## Required approvals (yad-review-gate rule)
 - Base: **owner + 1 reviewer**.
 - Escalated (risk tag set, or a stories MR): **plus one domain-owner per touched repo** — see the
@@ -28,10 +37,4 @@
 - **Comment** to record review comments (synced into `reviews/<artifact>--<date>--comments.md`).
 - **Do NOT merge to advance** — `yad-review-gate action: sync` + `action: advance` move the step.
 
-## Checklist
-- [ ] `owner` set in the artifact frontmatter (inherited from `epic.md`)
-- [ ] Contract re-locked (`.sdlc/contract-lock.json`) if the surface changed (architecture only)
-- [ ] Risk tags reflect the real surface touched (contract/auth/payments escalate)
-- [ ] No secrets or tokens in the artifact or this description
-
 /assign me