yadflow 3.15.5 → 3.16.1

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [3.16.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.16.0...v3.16.1) (2026-08-12)
+
+
+### Bug Fixes
+
+* **checkpoint:** guard --retro-ship per repo so a multi-repo story can be fully recorded ([d6d2fae](https://github.com/abdelrahmannasr/yadflow/commit/d6d2faeea91c0d59a00a532c0605f76c5b77eace)), closes [#166](https://github.com/abdelrahmannasr/yadflow/issues/166)
+* **checkpoint:** validate the retro-ship repo instead of relying on the duplicate guard ([f1e085e](https://github.com/abdelrahmannasr/yadflow/commit/f1e085e89e4eb10fbf853647ab10c1912237daf8)), closes [#166](https://github.com/abdelrahmannasr/yadflow/issues/166) [#166](https://github.com/abdelrahmannasr/yadflow/issues/166) [#166](https://github.com/abdelrahmannasr/yadflow/issues/166)
+* **ledger:** hold an exclusive lock across a ledger read-modify-write ([45b849a](https://github.com/abdelrahmannasr/yadflow/commit/45b849a7755a5bc58bc646e627218170a54b31bc)), closes [#166](https://github.com/abdelrahmannasr/yadflow/issues/166)
+
+# [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
@@ -111,7 +115,8 @@ ${c.bold('Build helpers')}
   yad checkpoint --retro-ship <epic>/<story> --repo <r>
                                        Record a retroactive build-log ship for a PRE-TRACKING story
                                        (merged before ledger tracking), then carry its status: shipped
-                                       flip in the same commit (--merge-commit <sha>, --task <t> opt.)
+                                       flip in the same commit (--merge-commit <sha>, --task <t> opt.);
+                                       one repo per run — re-run per --repo for a multi-repo story
   yad tidy up [<epic>] [--push]        Fold FINISHED back-half shards (a shipped story's
                                        trust-log/build-log entries) back into the single folded
                                        ledger, as one chore(hub) commit — the manual "pack it up"
@@ -159,6 +164,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 +185,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 +240,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/checkpoint.mjs

@@ -22,7 +22,7 @@
 //      marker would strand the PR's required checks.
 import fs from 'node:fs';
 import path from 'node:path';
-import { c, log, ok, info, fail, hand, exists, pushWithRebase } from './lib.mjs';
+import { c, log, ok, info, fail, hand, exists, readJSON, pushWithRebase } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
 import { loadHub } from './gate.mjs';
 import { resolveCommitterLogin } from './platform.mjs';
@@ -171,6 +171,26 @@ export function stagedStoryIsStatusOnly(git, file) {
 // (with a printed reason) aborts the commit; `file` is the shard just written, so a dry run can delete it
 // and leave no side effect. Does NOT author the story frontmatter — it only supplies the missing
 // evidence, and the human must have ALREADY flipped `status:` to a back-half value in the working tree.
+//
+// ONE repo per run (#166). A story that shipped in several repos is backfilled by re-running with each
+// `--repo`; the second run finds the flip already committed, so it lands only the new ship shard.
+//
+// The repo names a retro ship MAY carry — the story's own `repos:` frontmatter (its statement of where
+// it was implemented), else the hub's connected-repo registry as the project-wide fallback. Used to
+// reject a typo'd/mis-cased/invented `--repo` (#166 review): once the duplicate guard is per repo, a
+// wrong name no longer collides with anything, so nothing else would stop it from committing a
+// `retroactive: true` ship for a repo that never existed. Returns `{ names: [], source: 'none' }` when
+// neither declares anything — a legacy story with no metadata is still backfillable, never blocked on
+// a missing list.
+export function retroShipRepos(root, storyFile) {
+  const declared = readFrontmatter(storyFile).repos;
+  const story = (Array.isArray(declared) ? declared : declared ? [declared] : []).map(String).filter(Boolean);
+  if (story.length) return { names: story, source: 'story' };
+  const reg = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+  const names = (Array.isArray(reg?.repos) ? reg.repos : []).map((r) => r?.name).filter(Boolean);
+  return { names, source: names.length ? 'registry' : 'none' };
+}
+
 export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, today }) {
   if (!epic || !story) { fail('--retro-ship needs <epic>/<story> (e.g. --retro-ship EP-foo/EP-foo-S01)'); return { ok: false }; }
   if (!repo) { fail('--retro-ship needs --repo <name> (the repo the story shipped in)'); return { ok: false }; }
@@ -189,14 +209,51 @@ export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, to
     return { ok: false };
   }
 
+  // A ship is permanent audit evidence, so the repo it names must be one the story could have shipped
+  // in — an unrecognized `--repo` is a typo, not a discovery. Skipped only when nothing declares any
+  // repo (`source: 'none'`), so a legacy story with no metadata is never blocked.
+  const { names, source } = retroShipRepos(root, storyFile);
+  if (names.length && !names.includes(repo)) {
+    fail(`${repo} is not a repo ${source === 'story' ? `${story} declares` : 'connected to this hub'} — a retroactive ship must name a real repo, never invent one`);
+    hand(`known: ${names.join(', ')} (names are case-sensitive)`);
+    return { ok: false };
+  }
+  // Which of the story's OWN declared repos still lack evidence — read BEFORE the write so both the
+  // refusal and the success path can report honestly how much of a multi-repo backfill is left. Only
+  // the story's own list is used: the hub registry lists every connected repo, which says nothing
+  // about where THIS story shipped.
+  const remaining = () => {
+    if (source !== 'story') return [];
+    let recorded;
+    try { recorded = new Set(readShips(epicDir).filter((s) => s.story === story).map((s) => s.repo)); }
+    catch { return []; } // corrupt build-log — the write below reports it; don't guess at progress
+    return names.filter((n) => !recorded.has(n) && n !== repo);
+  };
+  const left = remaining();
+
   let res;
   try { res = writeRetroShip(epicDir, { story, repo, task, mergeCommit, shippedAt: today }); }
   catch (e) { fail(`could not record retroactive ship — ${e.message}`); return { ok: false }; }
   if (!res.written) {
-    fail(`${story} already has a build-log ship — it is not pre-tracking; use the normal ship/checkpoint flow`);
+    if (res.reason === 'collision') {
+      // Distinct names, ONE shard file (`buildShardName` sanitizes each component) — recording this one
+      // would overwrite the other repo's ship record, so it is refused rather than silently clobbered.
+      fail(`${repo} cannot be recorded: it shares a build-log shard name with ${res.repo ? `the already-recorded ${res.repo}` : `an existing shard (${path.basename(res.file)})`}`);
+      hand('recording it would overwrite that ship record — rename one of the repos in the registry, or record this ship through the normal ship/checkpoint flow');
+      return { ok: false };
+    }
+    // Per REPO, not per story (#166) — so the message names the repo. The follow-up hint names the
+    // story's OWN still-unrecorded repos; with none left there is nothing to re-run, and inventing a
+    // `--repo <other>` at that point would fabricate a ship for a repo the story never shipped in.
+    fail(`${story} already has a build-log ship in ${repo} — it is not pre-tracking there; use the normal ship/checkpoint flow`);
+    if (left.length) hand(`still unrecorded for ${story}: ${left.join(', ')} — re-run with \`--repo <name>\` for each`);
     return { ok: false };
   }
   ok(`recorded retroactive ship for ${story} (${repo})${mergeCommit ? ` @ ${mergeCommit}` : ''}`);
+  // A multi-repo story is only half-reconciled until every declared repo has evidence, and nothing
+  // downstream reports the gap (the story already reads `shipped`) — so say it here, while the
+  // operator is running the backfill.
+  if (left.length) hand(`${story} declares ${names.length} repos — still unrecorded: ${left.join(', ')}; re-run with \`--repo <name>\` for each`);
   return { ok: true, file: res.file };
 }
 

package/cli/errors.mjs

@@ -21,6 +21,7 @@ export const CODES = {
   'YAD-STATE-003': 'a registered repo path is missing or not a git repository',
   'YAD-STATE-004': 'an epic step cannot be skipped / un-skipped in its current state',
   'YAD-STATE-005': 'an authoring step is stranded behind its completed review gate',
+  'YAD-STATE-006': 'a back-half ledger is locked by another yad process that is writing it',
   'YAD-CFG-001': 'hub.json names an unknown platform (expected github, gitlab, or null)',
   'YAD-CFG-002': 'design.json names an unknown design tool (expected one of config.yaml design.tools, or none)',
   'YAD-CFG-003': 'testing.json names an unknown testing tool (expected one of config.yaml testing.tools, or none)',

package/cli/ledger.mjs

@@ -9,10 +9,69 @@
 //
 // A legacy epic that only has the folded file still reads correctly (no shards to union) → zero
 // migration; new writes simply go to shards.
+//
+// Shards remove the conflict BETWEEN entries; they do not make a single read-modify-write atomic, so
+// every writer that decides something from the ledger before writing takes an exclusive lock first
+// (see "ledger locking" below).
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJSON, readJSONStrict, writeJSON } from './lib.mjs';
 import { epicFiles } from './manifest.mjs';
+import { err } from './errors.mjs';
+
+// ---- ledger locking -------------------------------------------------------------------------------
+// Shards make concurrent writers conflict-free ACROSS entries, but a writer that READS THEN WRITES is
+// only safe if nothing slips in between. `writeRetroShip` decides "no ship for this (story, repo) yet"
+// and then writes; `updateShip` finds a ship and then rewrites it; a fold reads shards, merges them,
+// then deletes them. Two `--retro-ship` runs with different `--task` values both read "no ship", both
+// write, and the duplicate guard is defeated — two shards for one (story, repo). So every
+// read-modify-write on a ledger holds an exclusive lock for its whole span.
+//
+// `fs.mkdirSync` is the primitive: directory creation is atomic on POSIX and Windows, so exactly one
+// caller wins and the rest get EEXIST. It needs no fd bookkeeping, releases with one `rmdir`, and an
+// EMPTY DIRECTORY IS INVISIBLE TO GIT — a lock can never be committed, and `readShardDir` only reads
+// `*.json` files, so it is never mistaken for an entry either.
+//
+// The lock is per LEDGER, not per (story, repo). A per-identity lock keyed on the raw identity would
+// let the one pair that most needs serializing race: `api.v2` and `api_v2` are DIFFERENT identities
+// that share ONE shard filename (`safe()` maps both to `api_v2`), so they would take different locks
+// and then collide on the same file. A ledger-wide lock cannot be wrong that way, and what it
+// serializes is a handful of local file operations.
+const LOCK_STALE_MS = 30_000;   // a lock older than this belonged to a process that died holding it
+const LOCK_WAIT_MS = 50;
+const LOCK_RETRIES = 100;       // ≈5s — long enough for any real ledger write, short enough to report
+
+// Block the thread without spinning. `Atomics.wait` on the main thread is allowed in Node (only
+// browsers forbid it), and these ledger writers are synchronous by design.
+const sleep = (ms) => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+
+// Run `fn` while holding `lockPath` exclusively; always releases, even when `fn` throws. Throws
+// YAD-STATE-006 when the lock is held by a live process for the whole retry window — better to report
+// than to write over another writer's work.
+export function withLedgerLock(lockPath, fn, { retries = LOCK_RETRIES, waitMs = LOCK_WAIT_MS } = {}) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  for (let i = 0; ; i++) {
+    try {
+      fs.mkdirSync(lockPath);
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // A holder that died leaves its lock behind forever; reclaim one that is provably too old.
+      let age;
+      try { age = Date.now() - fs.statSync(lockPath).mtimeMs; } catch { continue; } // vanished → retry
+      if (age > LOCK_STALE_MS) { try { fs.rmdirSync(lockPath); } catch { /* someone else won */ } continue; }
+      if (i >= retries) {
+        throw err('YAD-STATE-006', `another process is writing ${path.basename(lockPath, '.lock')} in ${path.basename(path.dirname(path.dirname(lockPath)))}`,
+          'wait for the other yad command to finish and re-run; if nothing else is running, delete the stale .lock directory the message names');
+      }
+      sleep(waitMs);
+    }
+  }
+  try { return fn(); } finally { try { fs.rmdirSync(lockPath); } catch { /* already reclaimed */ } }
+}
+
+const buildLogLock = (epicDir) => `${epicFiles(epicDir).buildLog}.lock`;
+const trustLogLock = (epicDir) => `${epicFiles(epicDir).trustLog}.lock`;
 
 // ---- shard filenames — the ONE source of truth for the naming convention -------------------------
 // story ids already contain hyphens; the filename is just a unique handle (the entry inside carries
@@ -86,46 +145,68 @@ export function readShips(epicDir) {
 // ship: `task` defaults to the sentinel `retro`, `mergeCommit` is written only when the caller supplies
 // it (never invented), and `shippedAt` is the backfill date (the `retroactive` flag marks it as such).
 //
-// Guard: refuse when the story ALREADY has ANY build-log ship — then it isn't pre-tracking and the
-// normal ship/checkpoint flow applies; a retro record would only muddy the ledger. Returns
-// { written: false, reason } in that case, else { written: true, file, ship }.
-export function writeRetroShip(epicDir, { story, repo, task = 'retro', mergeCommit, shippedAt }) {
+// Guard: refuse when the story already has a build-log ship IN THIS REPO — then it isn't pre-tracking
+// there and the normal ship/checkpoint flow applies; a retro record would only muddy the ledger. The
+// key is (story, repo), NOT story alone (#166): a story tagged with several repos ships once per repo,
+// so a story-only guard let the FIRST backfill lock out every other repo and a multi-repo pre-tracking
+// story could never be fully recorded. Each repo is recorded by its own run — the shards are distinct
+// by construction (`buildShardName` keys on story+task+repo). Not keyed on `task` too: that would let
+// repeated `--task T0x` pile several retro shards into one repo, the very muddying this guard prevents.
+//
+// Two names can differ yet share ONE shard file: `buildShardName` sanitizes each component through
+// `safe()`, so `api.v2` and `api_v2` both become `api_v2` while the (story, repo) key sees them as
+// distinct. Writing the second would silently overwrite the first repo's ship — destroying evidence in
+// an append-only ledger, and (via the --dry-run cleanup) deleting an already-committed shard. So a
+// name that COLLIDES with an existing ship's shard name is refused as `reason: 'collision'`, and the
+// target file is never overwritten even when `readShips` cannot see it (a corrupt shard is skipped by
+// `readShardDir`). Returns { written: false, reason } when refused, else { written: true, file, ship }.
+export function writeRetroShip(epicDir, { story, repo, task = 'retro', mergeCommit, shippedAt }, lockOpts = {}) {
   if (!story) throw new Error('writeRetroShip: story is required');
   if (!repo) throw new Error('writeRetroShip: repo is required');
-  if (readShips(epicDir).some((s) => s.story === story)) {
-    return { written: false, reason: 'exists' };
-  }
-  const t = task || 'retro';
-  const ship = { story, task: t, repo, retroactive: true, note: 'pre-tracking backfill' };
-  if (mergeCommit) ship.mergeCommit = mergeCommit;
-  if (shippedAt) ship.shippedAt = shippedAt;
-  const f = epicFiles(epicDir);
-  const file = path.join(f.buildLogDir, buildShardName({ story, task: t, repo }));
-  writeJSON(file, ship);
-  return { written: true, file, ship };
+  // Both guards and the write are ONE critical section: read outside the lock and a concurrent run
+  // (notably a different `--task` for the same (story, repo)) can write between the check and ours.
+  return withLedgerLock(buildLogLock(epicDir), () => {
+    const ships = readShips(epicDir).filter((s) => s.story === story);
+    if (ships.some((s) => s.repo === repo)) return { written: false, reason: 'exists' };
+    const clash = ships.find((s) => safe(s.repo) === safe(repo));
+    if (clash) return { written: false, reason: 'collision', repo: clash.repo };
+    const t = task || 'retro';
+    const ship = { story, task: t, repo, retroactive: true, note: 'pre-tracking backfill' };
+    if (mergeCommit) ship.mergeCommit = mergeCommit;
+    if (shippedAt) ship.shippedAt = shippedAt;
+    const f = epicFiles(epicDir);
+    const file = path.join(f.buildLogDir, buildShardName({ story, task: t, repo }));
+    if (fs.existsSync(file)) return { written: false, reason: 'collision', file };
+    writeJSON(file, ship);
+    return { written: true, file, ship };
+  }, lockOpts);
 }
 
 // Find the ship matching `match(ship)` across loose shards (authoritative until folded) then the
 // folded file, apply `update(ship)`, and write back ONLY the file that holds it. Returns
-// { found, where, file, ship }; found:false writes nothing (the caller warns).
-export function updateShip(epicDir, match, update) {
-  const f = epicFiles(epicDir);
-  for (const { name, obj } of readShardDir(f.buildLogDir)) {
-    if (match(obj)) {
-      update(obj);
-      const file = path.join(f.buildLogDir, name);
-      writeJSON(file, obj);
-      return { found: true, where: 'shard', file, ship: obj };
+// { found, where, file, ship }; found:false writes nothing (the caller warns). The find and the
+// write-back are one locked span: a fold running between them would move the ship into the folded
+// file and delete the shard this call is about to rewrite, resurrecting the deleted shard.
+export function updateShip(epicDir, match, update, lockOpts = {}) {
+  return withLedgerLock(buildLogLock(epicDir), () => {
+    const f = epicFiles(epicDir);
+    for (const { name, obj } of readShardDir(f.buildLogDir)) {
+      if (match(obj)) {
+        update(obj);
+        const file = path.join(f.buildLogDir, name);
+        writeJSON(file, obj);
+        return { found: true, where: 'shard', file, ship: obj };
+      }
     }
-  }
-  const foldedObj = readJSONStrict(f.buildLog, null);
-  const ship = Array.isArray(foldedObj?.ships) ? foldedObj.ships.find(match) : null;
-  if (ship) {
-    update(ship);
-    writeJSON(f.buildLog, foldedObj);
-    return { found: true, where: 'folded', file: f.buildLog, ship };
-  }
-  return { found: false };
+    const foldedObj = readJSONStrict(f.buildLog, null);
+    const ship = Array.isArray(foldedObj?.ships) ? foldedObj.ships.find(match) : null;
+    if (ship) {
+      update(ship);
+      writeJSON(f.buildLog, foldedObj);
+      return { found: true, where: 'folded', file: f.buildLog, ship };
+    }
+    return { found: false };
+  }, lockOpts);
 }
 
 // ---- folding (used by `yad tidy up`) -------------------------------------------------------------
@@ -170,11 +251,16 @@ function fold(epicDir, { foldedPath, dir, arr, isTrust }, pick, { dryRun = false
   return { folded: toFold.length, remaining: shards.length - toFold.length, deleted };
 }
 
+// Both folds are read-fold-delete, so they hold their ledger's lock for the whole span — otherwise a
+// ship written (or stamped by `updateShip`) after the read but before the delete is folded away
+// without its change, or deleted without ever being folded.
 export function foldTrust(epicDir, pick, opts = {}) {
   const f = epicFiles(epicDir);
-  return fold(epicDir, { foldedPath: f.trustLog, dir: f.trustLogDir, arr: 'runs', isTrust: true }, pick, opts);
+  return withLedgerLock(trustLogLock(epicDir), () =>
+    fold(epicDir, { foldedPath: f.trustLog, dir: f.trustLogDir, arr: 'runs', isTrust: true }, pick, opts), opts);
 }
 export function foldBuild(epicDir, pick, opts = {}) {
   const f = epicFiles(epicDir);
-  return fold(epicDir, { foldedPath: f.buildLog, dir: f.buildLogDir, arr: 'ships', isTrust: false }, pick, opts);
+  return withLedgerLock(buildLogLock(epicDir), () =>
+    fold(epicDir, { foldedPath: f.buildLog, dir: f.buildLogDir, arr: 'ships', isTrust: false }, pick, opts), opts);
 }

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/cli/usage.mjs

@@ -243,11 +243,17 @@ function memberFlags(m) {
 
 // Team-level hygiene, keyed by epic/story — a ship with no recorded engineer review is a process gap,
 // not attributable to one person, so it lives here rather than in a member's flag list.
+//
+// A `retroactive: true` ship is EXCLUDED: it is a `yad checkpoint --retro-ship` reconciliation of a
+// story that shipped before the ledger existed, so it never had a tracked PR to review — counting it
+// as a missing review reports a gap the team could not have filled. It also scales with repo count
+// (one backfill shard per repo since #166), which would swamp the real gaps with reconciliation noise.
 export function shipHygiene(root, { since, until } = {}) {
   const items = [];
   for (const epic of listEpics(root)) {
     for (const s of readShips(path.join(root, 'epics', epic))) {
       if (!inWindow(s.shippedAt, since, until)) continue;
+      if (s.retroactive) continue;
       if (!Array.isArray(s.engineer_review) || s.engineer_review.length === 0) {
         items.push({ epic, story: s.story || null, task: s.task || null, repo: s.repo || null, shippedAt: s.shippedAt || null });
       }

package/package.json

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

package/skills/yad-checks/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-engineer-review/references/ship-and-record.md

@@ -81,11 +81,39 @@ yad checkpoint --retro-ship <epic>/<story> --repo <r> [--task <t>] [--merge-comm
 It writes ONE minimal ship shard marked `retroactive: true` (`task` defaults to the sentinel `retro`;
 `mergeCommit` is written only if you pass `--merge-commit`; `shippedAt` is the backfill date), then runs
 the normal checkpoint so the story's already-made `status:` flip rides along in the **same** commit. It
-refuses when the story already has a real ship (then it isn't pre-tracking — use the normal flow). It
-does **not** author the story frontmatter — and to keep evidence and the flip atomic (the no-drift
+refuses when the story already has a ship **in that repo** (then it isn't pre-tracking there — use the
+normal flow). It does **not** author the story frontmatter — and to keep evidence and the flip atomic (the no-drift
 invariant), it **refuses** unless you have already set `status: shipped` in `stories/<story>.md`, so a
 ship shard is never committed while the artifact still says `approved`.
 
+**One repo per run (#166).** A ship is recorded per `(story, task, repo)`, so a story that shipped in
+several repos needs one retroactive shard **per repo** — the guard is keyed on `(story, repo)`, not on
+the story alone, so recording the first repo never locks out the rest. Re-run once per repo:
+
+```
+yad checkpoint --retro-ship EP-foo/EP-foo-S01 --repo web --push
+yad checkpoint --retro-ship EP-foo/EP-foo-S01 --repo api --push
+```
+
+The `status:` flip rides the **first** commit (it only needs one ship to be carried); each later run
+lands only its own ship shard, so the story ends up with complete per-repo evidence. After each run the
+command names the declared repos that still have none, so a half-finished backfill is visible instead of
+looking complete.
+
+A ship is permanent audit evidence, so `--repo` is checked before anything is written: it must be a repo
+the story's `repos:` frontmatter declares (or, for a legacy story that declares none, one connected in
+`.sdlc/repos.json`). A typo'd, mis-cased or invented name is **refused** — the per-repo guard means it
+would otherwise collide with nothing and quietly record a ship for a repo that never existed. A name
+that would share a shard **filename** with an already-recorded repo (shard names sanitize everything
+outside `[A-Za-z0-9_-]` to `_`, so `api.v2` and `api_v2` are one file) is refused for the same reason:
+recording it would overwrite the other repo's ship record in an append-only ledger.
+
+Those checks decide from the ledger and then write it, so each one runs under an exclusive **lock** on
+the epic's `build-log` — as does `yad review reconcile`'s stamp and `yad tidy up`'s fold. Two commands
+writing the same ledger at once would otherwise both read "no ship yet" and both write. The lock is an
+empty directory (`build-log.json.lock`), so git never sees it; one held by a process that died is
+reclaimed after 30s, and a live one reports `YAD-STATE-006` rather than writing over the other's work.
+
 **Engagement (the Review Companion).** Each `engineer_review` entry carries `engagement: verified | none`
 — `verified` when the engineer reviewed through the [companion](../../yad-review-companion/SKILL.md)
 (`yad review trailer/context/nudge`, a real trailer/cards/chat session over the diff), `none` for a bare

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