yadflow 3.15.5 → 3.16.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [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)
 
 

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/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.5",
+  "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/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-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