yadflow 3.18.1 → 4.0.0-next.1

package/cli/ledger.mjs

@@ -1,4 +1,4 @@
-// Shard-then-fold storage for the two append-only back-half ledgers (trust-log, build-log).
+// Shard-then-fold storage for the two append-only Build ledgers (trust-log, build-log).
 //
 // The problem: both ledgers were ONE file per epic, so two people driving different stories of the
 // SAME epic both appended to the same file → git merge conflict on push. The fix ("loose objects +
@@ -57,9 +57,30 @@ export function withLedgerLock(lockPath, fn, { retries = LOCK_RETRIES, waitMs =
     } 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; }
+      //
+      // NEITHER BRANCH BELOW MAY `continue`. Both used to, which skipped the retry cap AND the sleep
+      // underneath them — an unbounded, unpaused, fully synchronous loop. The reclaim path is the one
+      // that bites: `fs.rmdirSync` throws ENOTEMPTY when anything at all is inside the lock directory
+      // (a stray file, an editor's dotfile), so a lock that is older than LOCK_STALE_MS and not empty
+      // can NEVER be removed, and the old code retried it forever at 100% CPU. Because the loop is
+      // synchronous, node cannot reach its event loop, so the process also ignores SIGTERM: it has to
+      // be killed with -9. Observed here for 2h27m before it was noticed (2026-09-21).
+      //
+      // Now every path falls through to the cap and the sleep. A stale lock nobody can remove is
+      // REPORTED as YAD-STATE-006 after the normal retry window — and that error's hint already says
+      // to delete the lock directory it names, which is exactly the fix for a non-empty one.
+      let age = null;
+      try { age = Date.now() - fs.statSync(lockPath).mtimeMs; } catch { /* it vanished — just retry */ }
+      if (age !== null && age > LOCK_STALE_MS) {
+        let reclaimed = false;
+        try { fs.rmdirSync(lockPath); reclaimed = true; } catch { /* someone else won, or it is not empty */ }
+        // TAKE IT IMMEDIATELY. Without this, a reclaim on the LAST pass deleted the stale lock and then
+        // reported "another process is writing" about a lock that no longer existed — the user re-ran
+        // and it worked, with no idea why. Losing the race here is normal: fall through and retry.
+        if (reclaimed) {
+          try { fs.mkdirSync(lockPath); break; } catch { /* another writer took it first */ }
+        }
+      }
       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');
@@ -93,7 +114,7 @@ export const buildShardName = (e) => `${safe(e.story)}-${safe(e.task)}-${safe(e.
 // `schemaVersion` is dropped here on purpose. It describes the shape of a FILE, and a shard file has
 // one — but `fold()` copies these objects into the folded log's `ships`/`runs` array, where they stop
 // being files and become records inside one. Carrying the stamp across that boundary would bake a
-// per-record version into an append-only ledger for good: after SCHEMA_VERSION moves to 2, a
+// per-record version into an append-only ledger for good: once the shape moves — as it has, to 2 — a
 // build-log.json stamped 2 would hold entries stamped 1 from shards folded today. The folded file
 // states its own shape; its rows do not have one.
 function readShardDir(dir) {
@@ -108,6 +129,35 @@ function readShardDir(dir) {
   return out;
 }
 
+// The shards in `dir` that do NOT parse as a JSON object, by file name. `readShardDir` SKIPS such a
+// shard on purpose — these ledgers are advisory evidence and one bad file must not abort a report. A
+// caller that COUNTS PEOPLE cannot accept that: a skipped ship shard is an engineer-review approval
+// that vanishes, and a person who vanishes makes the active count SMALLER, which lowers E72's cap and
+// weakens every gate (E71). Such a caller asks this first and reports "unknown" rather than a number.
+// Deliberately cheap: it parses, it does not validate a ship's fields.
+// Returns { bad: [names], unreadable: null | reason }. It NEVER throws: `fs.existsSync` is true for a
+// FILE as well as a directory, so a stray file named `build-log` under an epic's `.sdlc/` made
+// `readdirSync` throw ENOTDIR — and since the caller counts people for `yad gate sync`, `gate status`
+// and `gate open`, that exception escaped and turned three working commands into a crash. A directory
+// the user cannot list (EACCES) did the same. Both are now "we could not read this", which is exactly
+// what the counter needs to hear.
+export function corruptShards(dir) {
+  let names;
+  try {
+    if (!fs.existsSync(dir)) return { bad: [], unreadable: null };
+    if (!fs.statSync(dir).isDirectory()) return { bad: [], unreadable: `${path.basename(dir)} is not a directory` };
+    names = fs.readdirSync(dir).filter((n) => n.endsWith('.json')).sort();
+  } catch (e) {
+    return { bad: [], unreadable: `${path.basename(dir)} could not be listed: ${e.code || e.message}` };
+  }
+  const bad = [];
+  for (const name of names) {
+    const obj = readJSON(path.join(dir, name), null);
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) bad.push(name);
+  }
+  return { bad, unreadable: null };
+}
+
 // The half-applied-tidy guard key: a shard is a genuine duplicate of a folded entry ONLY when its FULL
 // identity matches — NOT `uid` alone. `uid` is minted by an LLM skill, so two runs of DIFFERENT
 // (story,repo,step) could share a short token; keying on uid alone would drop the second as a false
@@ -117,7 +167,7 @@ const trustKey = (e) => `${e.story}|${e.repo}|${e.step}|${e.uid}`;
 
 // trust-log = the evidence base. EVERY entry is a distinct step run (re-runs of a step share
 // story/repo/step), so we CONCATENATE folded runs + shards and never dedup by (story,repo,step) —
-// that would drop re-run history the trust threshold counts. The only guard is a shard whose full
+// that would drop re-run history the run record `yad dial` shows counts. The only guard is a shard whose full
 // identity (`trustKey`) already appears folded (a half-applied tidy). A corrupt folded file must throw
 // (readJSONStrict), never silently read as empty — under-reporting the evidence base is a safety bug.
 export function readTrustRuns(epicDir) {
@@ -147,7 +197,7 @@ export function readShips(epicDir) {
   return [...byKey.values()];
 }
 
-// Record a RETROACTIVE ship for a pre-tracking story — one merged & shipped before the back-half
+// Record a RETROACTIVE ship for a pre-tracking story — one merged & shipped before the Build
 // ledger existed, so it has no build-log ship and `yad checkpoint` can't carry its `status:` flip
 // (issue #142). Writes ONE minimal ship shard, marked `retroactive: true`, so `readShips` now proves
 // the story shipped and checkpoint carries the human's already-made flip. It is NOT a fabricated real

package/cli/lib.mjs

@@ -1,7 +1,7 @@
 // Shared helpers for the `yad` CLI. Node >=18 built-ins only — no dependencies.
 import { createHash } from 'node:crypto';
 import { err } from './errors.mjs';
-import { SCHEMA_VERSION } from './manifest.mjs';
+import { MIRRORED_FILES, SCHEMA_VERSION, VERSION } from './manifest.mjs';
 import { spawnSync } from 'node:child_process';
 import * as readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
@@ -13,9 +13,76 @@ import path from 'node:path';
 // resolve from HERE, never from the user's cwd.
 export const PKG_ROOT = fileURLToPath(new URL('../', import.meta.url));
 
+// ---- --json (E1) ---------------------------------------------------------
+// Every command answers `--json` with ONE object on stdout, built here and nowhere else:
+//   { jsonVersion, version, command, ok, ...the command's own keys, warnings }
+// and a refusal adds `error`, `code` (a `YAD-` code, or null) and `hint` (or null). `jsonVersion` is
+// the contract's own number: adding a key keeps it, renaming or removing one — or changing what a key
+// means — bumps it. `version` is the package that answered.
+//
+// While a `--json` run is on, `log` (and so every helper built on it) writes to STDERR, so stdout
+// holds the one object and nothing else — a progress line printed before the answer would otherwise
+// make the whole output unparseable. Each `warn` is also collected into `warnings`, as plain text.
+// A command never calls JSON.stringify toward stdout itself; a test greps for it.
+export const JSON_VERSION = 1;
+export const ENVELOPE_KEYS = ['jsonVersion', 'version', 'command'];
+let jsonRun = null;
+export function beginJSON(command) { jsonRun = { command, emitted: false, warnings: [], failures: [] }; }
+export const inJSON = () => jsonRun !== null;
+// A warning said some other way than `warn` (straight to stderr, before a command's own output) still
+// belongs in `warnings`: a --json reader must never read `warnings: []` while stderr warned (E1 review).
+export const collectWarning = (s) => { if (jsonRun) jsonRun.warnings.push(stripAnsi(s)); };
+export const jsonEmitted = () => jsonRun?.emitted === true;
+// The refusal a command SAID in prose (`fail`, then the `hand` under it), for the run that ends with a
+// non-zero exit and no answer: most refusals are written that way, and turning each by hand into a
+// JSON one is how one arm gets fixed and its twin missed. `bin/yad.mjs` answers with the first.
+// Every failure after the first goes into `warnings`, so a sweep that skipped several epics says all of
+// them (E1 review 2) — `error` holds one line, and none is lost.
+export const jsonFailure = () => {
+  const [f, ...more] = jsonRun?.failures ?? [];
+  if (!f) return null;
+  // With its hint: for a repo whose push failed, the hint is the only recovery step.
+  for (const m of more) jsonRun.warnings.push(m.hint ? `${m.error} — ${m.hint}` : m.error);
+  const code = /\b(YAD-[A-Z]+-\d{3})\b/.exec(f.error)?.[1] ?? null;
+  return { error: f.error, hint: f.hint, code };
+};
+// For a test that drives several commands in one process.
+export function endJSON() { jsonRun = null; }
+// eslint-disable-next-line no-control-regex -- removing the colour codes is the point
+export const stripAnsi = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, '');
+
+// Written with console.log, which is stdout: during a --json run `log` has moved to stderr, so the
+// answer is the only thing left there. Called outside a run (a test calling a command with
+// `json: true`), it still answers, with `command: null` and no collected warnings.
+export function emitJSON(payload = {}) {
+  const command = jsonRun?.command ?? null;
+  // A second answer would make stdout two documents; a bug, and said as one.
+  if (jsonRun?.emitted) throw new Error(`yad ${command}: a second JSON answer`);
+  const clash = ENVELOPE_KEYS.filter((k) => Object.hasOwn(payload, k));
+  if (clash.length) throw new Error(`yad ${command}: the answer sets the envelope key(s) ${clash.join(', ')}`);
+  if (jsonRun) jsonRun.emitted = true;
+  const { ok = true, warnings, ...rest } = payload;
+  // A refusal always carries all three keys, so a reader never tests whether one exists.
+  const refusal = ok === false && typeof rest.error === 'string'
+    ? { error: stripAnsi(rest.error), code: rest.code ?? null, hint: rest.hint == null ? null : stripAnsi(rest.hint) } : {};
+  const all = [...(jsonRun?.warnings ?? []), ...(Array.isArray(warnings) ? warnings.map(stripAnsi) : [])];
+  console.log(JSON.stringify({ jsonVersion: JSON_VERSION, version: VERSION, command, ok, ...rest, ...refusal, warnings: all }, null, 2));
+}
+
+// A refusal: one object under --json, the red line and its hint otherwise. Exit code 1 either way.
+// `json` answers in JSON outside a CLI run too (a command called with `json: true`); `extra` carries
+// keys a command adds to its refusal (never an envelope key).
+export function refuse(message, hint = null, { code = null, json = false, ...extra } = {}) {
+  process.exitCode = 1;
+  if (jsonRun || json) return emitJSON({ ok: false, error: stripAnsi(message), code, hint: hint === null || hint === undefined ? null : stripAnsi(hint), ...extra });
+  log(c.red(message));
+  if (hint) log(c.yellow(`  → ${hint}`));
+}
+
 // ---- output -------------------------------------------------------------
-const useColor = output.isTTY && !process.env.NO_COLOR;
-const paint = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+// Colour follows the stream the prose goes to: stderr during a --json run, stdout otherwise.
+const useColor = () => (jsonRun ? process.stderr.isTTY : output.isTTY) && !process.env.NO_COLOR;
+const paint = (code, s) => (useColor() ? `\x1b[${code}m${s}\x1b[0m` : s);
 export const c = {
   bold: (s) => paint('1', s),
   dim: (s) => paint('2', s),
@@ -24,13 +91,28 @@ export const c = {
   red: (s) => paint('31', s),
   cyan: (s) => paint('36', s),
 };
-export const log = (s = '') => console.log(s);
+export const log = (s = '') => {
+  if (!jsonRun) return console.log(s);
+  jsonRun.afterFail = false;
+  console.error(s);
+};
 export const step = (n, total, title) => log(`\n${c.cyan(`[${n}/${total}]`)} ${c.bold(title)}`);
 export const ok = (s) => log(`  ${c.green('✓')} ${s}`);
 export const info = (s) => log(`  ${c.dim('•')} ${s}`);
-export const warn = (s) => log(`  ${c.yellow('!')} ${s}`);
-export const fail = (s) => log(`  ${c.red('✗')} ${s}`);
-export const hand = (s) => log(`  ${c.yellow('→')} ${s}`);
+export const warn = (s) => {
+  if (jsonRun) jsonRun.warnings.push(stripAnsi(s));
+  log(`  ${c.yellow('!')} ${s}`);
+};
+export const fail = (s) => {
+  log(`  ${c.red('✗')} ${s}`);
+  if (jsonRun) { jsonRun.failures.push({ error: stripAnsi(s), hint: null }); jsonRun.afterFail = true; }
+};
+// A hint belongs to a failure only when it is the very next line under it — never a later `hand`.
+export const hand = (s) => {
+  const attach = jsonRun?.afterFail ? jsonRun.failures.at(-1) : null;
+  log(`  ${c.yellow('→')} ${s}`);
+  if (attach) attach.hint = stripAnsi(s);
+};
 // Like `info`, but to STDERR — for diagnostics emitted by commands whose STDOUT must stay pure (e.g. a
 // JSON bundle a tool parses). Keeps the human hint visible without corrupting machine-readable output.
 export const note = (s) => console.error(`  ${c.dim('•')} ${s}`);
@@ -45,14 +127,20 @@ export function closePrompts() {
   rl?.close();
   rl = undefined;
 }
+// A --json run never prompts: its stdin is a program's, and a question on stderr would hang it.
+const noPromptInJSON = (question) => {
+  if (jsonRun) throw err('YAD-CLI-001', `a --json run cannot ask: ${stripAnsi(question)}`, 'pass the answer as a flag where one exists (`yad --help` lists them), set SDLC_NONINTERACTIVE=1 to take every default, or run without --json');
+};
 export async function ask(question, def = '') {
   if (process.env.SDLC_NONINTERACTIVE) return def;
+  noPromptInJSON(question);
   const suffix = def ? c.dim(` (${def})`) : '';
   const a = (await getRl().question(`  ${question}${suffix}: `)).trim();
   return a || def;
 }
 export async function askYesNo(question, def = true) {
   if (process.env.SDLC_NONINTERACTIVE) return def;
+  noPromptInJSON(question);
   const hint = def ? 'Y/n' : 'y/N';
   const a = (await getRl().question(`  ${question} ${c.dim(`(${hint})`)} `)).trim().toLowerCase();
   if (!a) return def;
@@ -124,7 +212,10 @@ export function dirMatches(src, dest) {
 // file in a project that merely happened to live somewhere under a directory called `.sdlc` — the
 // user's own .claude/settings.json included, which is exactly what this must never touch. A new kind
 // nested deeper than that has to be added here on purpose.
-const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// Exported so the dial stampers (migrate.mjs, epic-state.mjs) and doctor all decide "is this a step
+// object" the same way. Three private copies drifted once already: one guarded arrays, one did not,
+// so an array-valued step came out as `["x"]` from one and `{"0":"x"}` from the other.
+export const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const underSdlcDir = (p) => {
   const dir = path.dirname(path.resolve(p));
   return path.basename(dir) === '.sdlc' || path.basename(path.dirname(dir)) === '.sdlc';
@@ -132,16 +223,30 @@ const underSdlcDir = (p) => {
 const carriesShape = (p, v) => isPlainObject(v) && underSdlcDir(p);
 
 // Always FIRST in the serialized object. A stamp that moved around between writers would change the
-// bytes without changing the meaning. An existing version is preserved, never forced back to 1, so a
-// file already on a newer shape survives being read and written by this release.
-const withShape = (p, v) =>
-  (carriesShape(p, v) ? { schemaVersion: v.schemaVersion ?? SCHEMA_VERSION, ...v } : v);
+// bytes without changing the meaning. An existing version is preserved, never forced back or forward,
+// so a file already on another shape survives being read and written by this release.
+//
+// Reading and writing do NOT default the same way, and the difference is load-bearing:
+//
+//   read  — a file with no version IS shape 1 (rule 1). Defaulting it to the engine's current shape
+//           would be the engine telling itself an old file is already current. Everything downstream
+//           believes it: `yad doctor` stops reporting drift, and a plain read-modify-write stamps the
+//           engine's shape onto content that was never migrated — after which `yad migrate` skips the
+//           file forever, because its own claim says there is nothing to do. Silent, permanent, and
+//           invisible until someone asks why a field never got renamed.
+//   write — a NEW object, one that was never read from disk and so has no version of its own, is
+//           written by this engine and therefore has this engine's shape.
+//
+// This was harmless while SCHEMA_VERSION was 1, because the two defaults were the same number. It
+// stops being harmless the moment the shape moves, which is why it is fixed in the commit that moves it.
+const readShape  = (p, v) => (carriesShape(p, v) ? { schemaVersion: v.schemaVersion ?? 1, ...v } : v);
+const writeShape = (p, v) => (carriesShape(p, v) ? { schemaVersion: v.schemaVersion ?? SCHEMA_VERSION, ...v } : v);
 
 export function readJSON(p, def = null) {
   try {
     // "Read old, write new" (rule 2): an unstamped file reads back as shape 1, so a caller never has
     // to ask whether the file it just loaded predates the stamp.
-    return withShape(p, JSON.parse(fs.readFileSync(p, 'utf8')));
+    return readShape(p, JSON.parse(fs.readFileSync(p, 'utf8')));
   } catch {
     // The caller's own default is returned untouched: it is not a file, and stamping it would invent
     // a shape for something that was never read from disk.
@@ -154,7 +259,7 @@ export function readJSON(p, def = null) {
 export function readJSONStrict(p, def = null) {
   if (!fs.existsSync(p)) return def;
   try {
-    return withShape(p, JSON.parse(fs.readFileSync(p, 'utf8')));
+    return readShape(p, JSON.parse(fs.readFileSync(p, 'utf8')));
   } catch (e) {
     throw err('YAD-STATE-001', `corrupt JSON in ${p}: ${e.message}`, 'fix the file or restore it from git — never delete a ledger blindly');
   }
@@ -163,7 +268,7 @@ export function readJSONStrict(p, def = null) {
 // then rename over the target. A killed process can never leave a truncated ledger
 // file, and a failed rename never leaves a stray .tmp for `git add -A` to pick up.
 export function writeJSON(p, obj) {
-  const data = JSON.stringify(withShape(p, obj), null, 2) + '\n';
+  const data = JSON.stringify(writeShape(p, obj), null, 2) + '\n';
   // Byte-identical content is not a write. The ledger writers are unconditional — they re-serialize
   // whether or not anything changed — so this keeps an unchanged sync from touching the file at all
   // (no mtime churn, nothing for a watcher or a `git add -A` to notice). A backstop, not the fix: the
@@ -185,7 +290,10 @@ export function writeJSON(p, obj) {
 // ---- subprocess ---------------------------------------------------------
 // Returns { ok, stdout, stderr, code }. Never throws on non-zero exit.
 export function run(cmd, args = [], opts = {}) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  // A subprocess that shares our stdout (`npm run build`) would print into a --json answer: during a
+  // --json run its stdout is our stderr instead (E1).
+  const stdio = jsonRun && opts.stdio === 'inherit' ? ['inherit', 2, 'inherit'] : opts.stdio;
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts, ...(stdio === undefined ? {} : { stdio }) });
   return {
     ok: r.status === 0,
     code: r.status,
@@ -196,8 +304,8 @@ export function run(cmd, args = [], opts = {}) {
 }
 export const has = (cmd) => run(process.platform === 'win32' ? 'where' : 'which', [cmd]).ok;
 
-// Push HEAD to origin/<target>, rebasing onto it and retrying on rejection — both the front-half gate
-// sync and the back-half checkpoint push append-only ledgers to the default branch, so a concurrent
+// Push HEAD to origin/<target>, rebasing onto it and retrying on rejection — both the Shape gate
+// sync and the Build checkpoint push append-only ledgers to the default branch, so a concurrent
 // push is a normal race, not an error. Returns { ok } after up to `attempts` tries; logs each retry.
 // A failed `pull --rebase` is aborted so we never leave a wedged rebase for the next command.
 export function pushWithRebase(cwd, target, { attempts = 3 } = {}) {
@@ -211,3 +319,61 @@ export function pushWithRebase(cwd, target, { attempts = 3 } = {}) {
   }
   return { ok: false };
 }
+
+// ---- the product config, which lives under two names for one major -----------------------------
+//
+// Read through `productConfigPath` (manifest.mjs), which every reader in cli/ now does. Write
+// through here: BOTH names, every time.
+//
+// The duplicate is not sloppiness. `templates/checks/ledger-guard.sh` sits committed inside the
+// user's own repository and opens `.sdlc/hub.json` by that literal path; it is refreshed by
+// `yad update`, which is a separate act from `yad migrate`. So a migrated-but-not-updated project is
+// a real state, and if only the new name existed its guard would find nothing, read no platform,
+// call the ledger local, and stop rejecting human commits to it. An upgrade that silently disarms a
+// safety gate is worse than a duplicated file.
+//
+// Order matters, and it follows which file is AUTHORITATIVE — the old name, this major
+// (`productConfigPath`, cli/manifest.mjs). The new name is written first, so if the second write
+// fails the readers are all still on the untouched old copy: nothing has half-changed underneath
+// them. Writing the authoritative file first would leave every reader on new settings while the
+// mirror still says something else, which is the harder failure to notice.
+//
+// `yad doctor` reports the two copies disagreeing either way, so a half-written pair is visible
+// rather than silent.
+// Write a file that lives under two names. Returns the paths it actually wrote — empty when there
+// was nothing to do.
+//
+// The "nothing to do" case is load-bearing, not an optimisation. The ledger writers are
+// UNCONDITIONAL: `yad gate` re-serializes and writes every time, and relies on `writeJSON` doing
+// nothing when the bytes match, which is what keeps a read-only pre-merge run from touching the
+// working tree at all. A naive mirror breaks that on day one — the new name does not exist yet, so
+// every read-only run would create it and leave the tree dirty, and `gate ci` would try to push a
+// file it never meant to write. So the comparison happens FIRST, against whichever name is currently
+// readable; only a genuine change writes, and then it writes both.
+export function writeMirrored(canonicalPath, legacyPath, obj) {
+  // Compare against the AUTHORITATIVE copy — the same one readers use (`preferring`,
+  // cli/manifest.mjs), which is the legacy name while it exists. Comparing against the other file
+  // would let the two rules disagree about whether anything changed.
+  const readable = fs.existsSync(legacyPath) ? legacyPath : canonicalPath;
+  const next = `${JSON.stringify(writeShape(canonicalPath, obj), null, 2)}\n`;
+  // "Unchanged" means BOTH names are already right. A half-made pair — one side missing — is work
+  // to do even when the readable copy matches, or the pair can never be repaired: the comparison
+  // says nothing changed, nothing is written, and `yad doctor` reports the missing file for ever.
+  const bothPresent = fs.existsSync(canonicalPath) && fs.existsSync(legacyPath);
+  try {
+    if (bothPresent && fs.readFileSync(readable, 'utf8') === next) return [];
+  } catch { /* unreadable — treat as a first write and fall through */ }
+  writeJSON(canonicalPath, obj);
+  writeJSON(legacyPath, obj);
+  return [canonicalPath, legacyPath];
+}
+
+export function writeProductConfig(root, obj) {
+  const written = [];
+  for (const { canonical, legacy } of MIRRORED_FILES) {
+    const wrote = writeMirrored(path.join(root, canonical), path.join(root, legacy), obj);
+    if (wrote.length) written.push(canonical, legacy);
+  }
+  return written;
+}
+