yadflow 3.16.0 → 3.16.1

package/CHANGELOG.md

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

package/bin/yad.mjs

@@ -115,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"

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