@sabaiway/agent-workflow-kit 3.0.0 → 3.2.0

package/tools/inject-methodology.mjs

@@ -314,11 +314,31 @@ const isCapRefusal = (errorMessage) => typeof errorMessage === 'string' && error
 export const isFillCapRefusal = (errorMessage) =>
   isCapRefusal(errorMessage) && errorMessage.includes('injection would push');
 
-const main = async (argv) => {
+const EXIT = Symbol('inject-methodology.exit');
+
+// The return-code entry point (5.1): argv[] + injected env/home → { code, stdout, stderr }, no
+// process.argv / process.exit / console inside — an in-process caller is as hermetic as a spawned
+// one. The thin shell at the bottom is the only process-coupled code.
+export const runCli = async (argv, deps = {}) => {
   const { readFile, writeFile, rename, rm } = await import('node:fs/promises');
   const { dirname, basename, join, resolve } = await import('node:path');
   const { homedir } = await import('node:os');
   const { resolveEngineDir, readEngineFragment, detectEngine, ENGINE_FRAGMENT_REL, ORCHESTRATION_FRAGMENT_REL, AUTONOMY_FRAGMENT_REL } = await import('./engine-source.mjs');
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? homedir();
+
+  const stdoutLines = [];
+  const stderrLines = [];
+  const log = (line) => stdoutLines.push(line);
+  const logError = (line) => stderrLines.push(line);
+  const result = (code) => ({
+    code,
+    stdout: stdoutLines.length > 0 ? `${stdoutLines.join('\n')}\n` : '',
+    stderr: stderrLines.length > 0 ? `${stderrLines.join('\n')}\n` : '',
+  });
+  // Nested sourcing helpers end the run from arbitrary depth — a tagged throw the catch below
+  // translates into the result code (the process.exit of the pre-entry-point CLI).
+  const stop = (code) => Object.assign(new Error(`exit ${code}`), { [EXIT]: code });
 
   // `reconcile <AGENTS.md> [fragment.md]` = ensure-slot + inject-if-empty + cap (bootstrap/upgrade) for
   // ALL THREE slots; `<AGENTS.md> [fragment.md]` = the legacy inject-into-existing-(methodology)-slot mode.
@@ -326,10 +346,11 @@ const main = async (argv) => {
   const rest = mode === 'reconcile' ? argv.slice(1) : argv;
   const agentsPath = rest[0];
   if (!agentsPath) {
-    console.error('usage: inject-methodology.mjs [reconcile] <path/to/AGENTS.md> [fragment.md]');
-    process.exit(2);
+    logError('usage: inject-methodology.mjs [reconcile] <path/to/AGENTS.md> [fragment.md]');
+    return result(2);
   }
   const explicitFragmentArg = rest[1];
+  try {
   const text = await readFile(resolve(agentsPath), 'utf8');
 
   // Source a bounded fragment LAZILY, per slot. An explicit [fragment.md] arg (tests + manual) wins and
@@ -339,7 +360,7 @@ const main = async (argv) => {
   // the install command. The caller only invokes this when a fill is actually needed (the laziness).
   const sourceFragment = async (rel) => {
     if (explicitFragmentArg) return readFile(resolve(explicitFragmentArg), 'utf8');
-    const { dir, source } = resolveEngineDir({ env: process.env, home: homedir() });
+    const { dir, source } = resolveEngineDir({ env, home });
     return readEngineFragment(dir, { source, rel }); // sync; throws loudly when the engine is absent/invalid
   };
   const sourceFragmentOrStop = async (label, rel) => {
@@ -348,8 +369,8 @@ const main = async (argv) => {
     } catch (err) {
       // Engine needed-but-absent → a hard STOP, distinct from the soft cap-skip. The "methodology
       // engine not found/invalid" prefix lets the agent classify this exit (SKILL.md).
-      console.error(`[inject-methodology] ${label} — ${err.message}`);
-      process.exit(1);
+      logError(`[inject-methodology] ${label} — ${err.message}`);
+      throw stop(1);
     }
   };
 
@@ -362,16 +383,16 @@ const main = async (argv) => {
   // an unreadable fragment). Returns { fragment } on success, { skip } for the soft case, or
   // process.exit(1) for the hard STOP.
   const sourceChainedFragment = async (rel) => {
-    const { dir, source } = resolveEngineDir({ env: process.env, home: homedir() });
-    const stop = (err) => {
-      console.error(`[inject-methodology] reconcile STOP — ${err.message}`);
-      process.exit(1);
+    const { dir, source } = resolveEngineDir({ env, home });
+    const chainedStop = (err) => {
+      logError(`[inject-methodology] reconcile STOP — ${err.message}`);
+      throw stop(1);
     };
     if (detectEngine(dir, { source, rel }).ok) {
       try {
         return { fragment: readEngineFragment(dir, { source, rel }) };
       } catch (err) {
-        stop(err);
+        chainedStop(err);
       }
     }
     if (detectEngine(dir, { source }).ok) {
@@ -380,7 +401,7 @@ const main = async (argv) => {
     try {
       readEngineFragment(dir, { source, rel }); // throws the canonical install-me error
     } catch (err) {
-      stop(err);
+      chainedStop(err);
     }
   };
 
@@ -402,8 +423,8 @@ const main = async (argv) => {
     if (methResult.status === 'error') {
       // cap-refusal OR malformed/anchor STOP — preserve the single-slot classification (SKILL.md
       // distinguishes by the message); the file is byte-for-byte unchanged either way.
-      console.error(`[inject-methodology] reconcile refused — ${methResult.error}`);
-      process.exit(1);
+      logError(`[inject-methodology] reconcile refused — ${methResult.error}`);
+      return result(1);
     }
     const afterMeth = methResult.text; // === text when the methodology slot was already filled (custom)
     const describeMeth = {
@@ -421,18 +442,18 @@ const main = async (argv) => {
       const u = markerSlotUpgradeHint(afterMeth, METHODOLOGY_DESCRIPTOR); if (u) notes.push(u);
     }
     const reportNotes = () => {
-      for (const n of notes) console.log(`[inject-methodology] note: ${n}`);
+      for (const n of notes) log(`[inject-methodology] note: ${n}`);
     };
 
     // ── Explicit [fragment.md] binds methodology ONLY → skip the orchestration + autonomy reconciles ──
     if (explicitFragmentArg) {
       if (afterMeth === text) {
-        console.log('[inject-methodology] methodology slot already present and filled — nothing to do (zero-diff).');
-        return;
+        log('[inject-methodology] methodology slot already present and filled — nothing to do (zero-diff).');
+        return result(0);
       }
       await writeAtomic(afterMeth);
-      console.log(`[inject-methodology] reconcile: ${describeMeth}.`);
-      return;
+      log(`[inject-methodology] reconcile: ${describeMeth}.`);
+      return result(0);
     }
 
     // ── Slot 2: orchestration, reconciled on the methodology-reconciled text (the cap-check then guards
@@ -459,8 +480,8 @@ const main = async (argv) => {
           describeOrch = `orchestration-recipes pointer skipped — ${orchResult.error}`;
         } else {
           // Malformed orchestration slot/anchor → a hard STOP. No partial write.
-          console.error(`[inject-methodology] reconcile refused (orchestration) — ${orchResult.error}`);
-          process.exit(1);
+          logError(`[inject-methodology] reconcile refused (orchestration) — ${orchResult.error}`);
+          return result(1);
         }
       } else {
         finalText = orchResult.text;
@@ -493,8 +514,8 @@ const main = async (argv) => {
       // Malformed markers are a hard STOP on EVERY lane — validated before the soft-skip
       // short-circuits so a duplicate/reversed autonomy pair can never ride out as a "skip"
       // alongside a partial (methodology) write.
-      console.error(`[inject-methodology] reconcile refused (autonomy) — ${autSlot.reason}`);
-      process.exit(1);
+      logError(`[inject-methodology] reconcile refused (autonomy) — ${autSlot.reason}`);
+      return result(1);
     }
     if (orchSkipped) {
       // The chain is CAUSAL, not merely positional: a pointer never lands in a run that withheld
@@ -523,8 +544,8 @@ const main = async (argv) => {
             autSkipped = true;
             describeAut = `autonomy pointer skipped — ${autResult.error}`;
           } else {
-            console.error(`[inject-methodology] reconcile refused (autonomy) — ${autResult.error}`);
-            process.exit(1);
+            logError(`[inject-methodology] reconcile refused (autonomy) — ${autResult.error}`);
+            return result(1);
           }
         } else {
           finalText = autResult.text;
@@ -545,34 +566,44 @@ const main = async (argv) => {
     // ── One atomic write of the final (three-slot) text ──
     if (finalText === text) {
       // Byte-unchanged. Still report a skip (it is not "nothing to do" — a pointer was withheld).
-      if (orchSkipped || autSkipped) console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
-      else console.log('[inject-methodology] reconcile: all three pointers already present and filled — nothing to do (zero-diff).');
+      if (orchSkipped || autSkipped) log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
+      else log('[inject-methodology] reconcile: all three pointers already present and filled — nothing to do (zero-diff).');
       reportNotes();
-      return;
+      return result(0);
     }
     await writeAtomic(finalText);
-    console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
+    log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
     reportNotes();
-    return;
+    return result(0);
   }
 
   // Legacy inject-into-existing-slot mode (METHODOLOGY only). injectMethodology no-ops on absent markers
   // and errors on a malformed slot WITHOUT reading the fragment, so resolve+read the engine only when
   // there is a present (ok) slot to fill — a markerless legacy AGENTS.md stays a no-op without the engine.
   const fragment = findSlot(text).state === 'ok' ? await sourceFragmentOrStop('STOP', ENGINE_FRAGMENT_REL) : '';
-  const result = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
-  if (result.status === 'error') {
-    console.error(`[inject-methodology] malformed slot — refusing to edit: ${result.error}`);
-    process.exit(1);
+  const injected = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
+  if (injected.status === 'error') {
+    logError(`[inject-methodology] malformed slot — refusing to edit: ${injected.error}`);
+    return result(1);
+  }
+  if (injected.status === 'noop-absent') {
+    log('[inject-methodology] no methodology markers found — nothing to inject (legacy AGENTS.md).');
+    return result(0);
   }
-  if (result.status === 'noop-absent') {
-    console.log('[inject-methodology] no methodology markers found — nothing to inject (legacy AGENTS.md).');
-    return;
+  await writeAtomic(injected.text);
+  log('[inject-methodology] injected the bounded methodology fragment into the slot.');
+  return result(0);
+  } catch (err) {
+    if (err[EXIT] !== undefined) return result(err[EXIT]);
+    throw err;
   }
-  await writeAtomic(result.text);
-  console.log('[inject-methodology] injected the bounded methodology fragment into the slot.');
 };
 
 const { pathToFileURL } = await import('node:url');
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) await main(process.argv.slice(2));
+if (isDirectRun) {
+  const { code, stdout, stderr } = await runCli(process.argv.slice(2));
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  process.exitCode = code;
+}

package/tools/lens-region.mjs

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
-// Heading-anchored lens-region reconcile — the composition root's only mutation of a deployed
-// `docs/ai/agent_rules.md`. The planning/review/process-fidelity lens block (`### 2.x. Planning,
-// review & process-fidelity invariants`) has ONE canonical home — the installed engine's
-// `references/agent-rules-lens.md` — and every deployed/template copy is a RENDER of it (the
-// file's own section number substituted into the number-neutral heading). This tool refreshes a
-// deployed region to the current canon under the AD-025 discipline: refresh IFF the region's
-// normalized body matches the current fragment (already current → zero-diff) or a KNOWN PRIOR
-// canonical body (the engine's append-only `references/agent-rules-lens-priors.md`, read live
-// beside the fragment — no kit-side prior constants, so a canon wording change is an engine-only
-// release). Anything else is preserved byte-for-byte + a one-line advisory.
+// Heading-anchored region reconcile — the composition root's only mutation of a deployed
+// `docs/ai/agent_rules.md`. TWO regions, one policy (refresh IFF the region's normalized body
+// matches the current canon or a KNOWN PRIOR canonical body; anything else preserved
+// byte-for-byte + a one-line advisory — the AD-025 discipline):
+// - the planning/review/process-fidelity lens block (`### 2.x. Planning, review &
+//   process-fidelity invariants`) — canon home: the installed engine's
+//   `references/agent-rules-lens.md` + its append-only prior store, read live (no kit-side
+//   prior constants, so a lens wording change is an engine-only release);
+// - the Communication block (`### 2.x. Communication (user-facing messages)`, AD-061) — canon
+//   home: the §2.5 region of the kit's OWN bundled `references/templates/agent_rules.md`
+//   (byte-identical to the memory twin by the template-region parity guard); priors are inline
+//   constants below (a templates/-side prior file would be deployed into projects by the
+//   template loop), appended whenever the template region changes (the vintage rule).
 //
 // The region has NO markers (unlike the AGENTS.md pointer slots): it is located by the heading
 // through the next structural boundary (`---` / `##` / `###`) or EOF — the extraction rule the
@@ -31,6 +34,22 @@ import { normalizeCanonical } from './orchestration-config.mjs';
 export const LENS_HEADING_RE = /^### 2\.(\d+)\. Planning, review & process-fidelity/;
 const NEUTRAL_HEADING_RE = /^### 2\.x\. Planning, review & process-fidelity/;
 const HEADING_LABEL = '### 2.x. Planning, review & process-fidelity invariants';
+export const COMMS_HEADING_RE = /^### 2\.(\d+)\. Communication \(user-facing messages\)/;
+const NEUTRAL_COMMS_RE = /^### 2\.x\. Communication \(user-facing messages\)/;
+const COMMS_LABEL = '### 2.x. Communication (user-facing messages)';
+
+// The known prior canonical bodies of the Communication region (neutral-headed, like the engine's
+// lens prior store). Append the OUTGOING canon here in the same release that changes the template
+// §2.5 region — the fragment-or-prior reconcile depends on it.
+const COMMS_PRIOR_PRE_AD054 = `### 2.x. Communication (user-facing messages)
+Apply this as part of §2 before any user-facing summary:
+- **Deliver the artifact IN the message** — paste the prompt / diff / version / command inline; never "see §X / open the file / run it and you'll see" as a *substitute* for showing what was asked.
+- **Lead with the result**, then the details; show exactly what was asked — no deflection, no "almost done" when the ask was the finished thing.
+- **No condescension, no filler.** Own a miss plainly and fix it in the same message.
+- **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.`;
+const COMMS_PRIOR_AD054 = `${COMMS_PRIOR_PRE_AD054}
+- **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.`;
+export const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054];
 
 const stripCr = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
 const isBoundary = (bareLine) => bareLine === '---' || /^#{2,3} /.test(bareLine);
@@ -66,15 +85,18 @@ export const renderLens = (fragment, number) =>
 // (heading number → `2.x`, trim, CRLF→LF) every known-set match uses.
 export const normalizeLensBody = (body) =>
   normalizeCanonical(String(body).replace(/^### 2\.\d+\./, '### 2.x.'));
+export const normalizeCommsBody = normalizeLensBody;
+export const renderComms = (fragment, number) =>
+  normalizeCanonical(fragment).replace(NEUTRAL_COMMS_RE, (m) => m.replace('2.x', `2.${number}`));
 
 // extractLensRegion(text) → { found: false } | { found, start, end, number, body }.
 // `start`/`end` are line indices over text.split('\n') — heading line through (exclusive) the
 // next structural boundary; EOF is a valid region end (no following boundary required). `body`
 // is the CR-stripped block with trailing blank lines dropped (the comparison form); the raw
 // region lines (including trailing blanks) are what replaceLensRegion preserves around a render.
-export const extractLensRegion = (text) => {
+const extractRegionBy = (text, headingRe) => {
   const lines = String(text).split('\n');
-  const start = lines.findIndex((line) => LENS_HEADING_RE.test(stripCr(line)));
+  const start = lines.findIndex((line) => headingRe.test(stripCr(line)));
   if (start === -1) return { found: false };
   let end = lines.length;
   for (let i = start + 1; i < lines.length; i += 1) {
@@ -83,13 +105,15 @@ export const extractLensRegion = (text) => {
       break;
     }
   }
-  const number = stripCr(lines[start]).match(LENS_HEADING_RE)[1];
+  const number = stripCr(lines[start]).match(headingRe)[1];
   const regionLines = lines.slice(start, end);
   let bodyEnd = regionLines.length;
   while (bodyEnd > 0 && stripCr(regionLines[bodyEnd - 1]).trim() === '') bodyEnd -= 1;
   const body = regionLines.slice(0, bodyEnd).map(stripCr).join('\n');
   return { found: true, start, end, number, body };
 };
+export const extractLensRegion = (text) => extractRegionBy(text, LENS_HEADING_RE);
+export const extractCommsRegion = (text) => extractRegionBy(text, COMMS_HEADING_RE);
 
 // replaceLensRegion(text, region, renderedBody) → the document with ONLY the region's block
 // lines replaced; trailing blank lines inside the region and every byte outside it are
@@ -119,16 +143,20 @@ export const replaceLensRegion = (text, region, renderedBody) => {
 //                                   with the file's OWN number (cap-guard is the caller's, so the
 //                                   decision stays pure).
 //   { status: 'custom' }     — anything else → preserved byte-for-byte + advisory.
-export const reconcileLensText = (text, fragment, priors) => {
-  const region = extractLensRegion(text);
+const reconcileRegionText = (text, fragment, priors, { extract, normalize, render }) => {
+  const region = extract(text);
   if (!region.found) return { status: 'no-region', text };
-  const current = normalizeLensBody(region.body);
-  const canon = normalizeLensBody(fragment);
+  const current = normalize(region.body);
+  const canon = normalize(fragment);
   if (current === canon) return { status: 'current', text };
-  const known = priors.map((p) => normalizeLensBody(p));
+  const known = priors.map((p) => normalize(p));
   if (!known.includes(current)) return { status: 'custom', text };
-  return { status: 'refreshed', text: replaceLensRegion(text, region, renderLens(fragment, region.number)) };
+  return { status: 'refreshed', text: replaceLensRegion(text, region, render(fragment, region.number)) };
 };
+export const reconcileLensText = (text, fragment, priors) =>
+  reconcileRegionText(text, fragment, priors, { extract: extractLensRegion, normalize: normalizeLensBody, render: renderLens });
+export const reconcileCommsText = (text, fragment, priors) =>
+  reconcileRegionText(text, fragment, priors, { extract: extractCommsRegion, normalize: normalizeCommsBody, render: renderComms });
 
 // frontmatterMaxLines(text) → the file's own `maxLines:` frontmatter value, or null when the
 // file has no frontmatter block or the block carries no maxLines (→ the cap-guard is skipped
@@ -146,8 +174,9 @@ export const frontmatterMaxLines = (text) => {
 
 // ── CLI: `lens-region.mjs reconcile <path/to/agent_rules.md>` ─────────────────────
 // Outcome lines are the contract the upgrade/bootstrap prose relays in plain language; exit 0 on
-// every classified outcome (including the soft skips and the cap refusal), exit 1 ONLY on the
-// hard engine STOP or an unexpected fs error, exit 2 on usage.
+// every classified outcome (including the soft skips and the cap refusals), exit 1 ONLY on a
+// hard STOP — the absent/invalid engine, or the unreadable bundled template canon — or an
+// unexpected fs error, exit 2 on usage.
 export const runCli = async (argv, deps = {}) => {
   const log = deps.log ?? console.log;
   const logError = deps.logError ?? console.error;
@@ -155,6 +184,7 @@ export const runCli = async (argv, deps = {}) => {
   const fs = deps.fs ?? (await import('node:fs/promises'));
   const { dirname, basename, join, resolve } = await import('node:path');
   const { homedir } = await import('node:os');
+  const { fileURLToPath } = await import('node:url');
   const { resolveEngineDir, detectEngine, readEngineFragment, LENS_FRAGMENT_REL, LENS_PRIORS_REL } = await import('./engine-source.mjs');
 
   if (argv[0] !== 'reconcile' || !argv[1] || argv.length > 2) {
@@ -177,9 +207,63 @@ export const runCli = async (argv, deps = {}) => {
     return 0;
   }
 
-  // 2. No matching heading → preserve + advise, engine never consulted (the outcome is preserve
-  //    regardless, so the lazy contract holds).
-  if (!extractLensRegion(text).found) {
+  const atomicWrite = async (content) => {
+    const tmp = join(dirname(targetPath), `.${basename(targetPath)}.tmp-${process.pid}-${Date.now()}`);
+    try {
+      await fs.writeFile(tmp, content, 'utf8');
+      await fs.rename(tmp, targetPath);
+    } catch (err) {
+      await fs.rm(tmp, { force: true }).catch(() => {});
+      throw err;
+    }
+  };
+
+  // 2. The Communication half (AD-061) — canon from the kit's OWN bundled template (the engine is
+  //    never consulted for this region), same fragment-or-prior policy, own outcome lines.
+  const templatePath = join(dirname(fileURLToPath(import.meta.url)), '..', 'references', 'templates', 'agent_rules.md');
+  const templateRegion = await (async () => {
+    try {
+      return extractCommsRegion(await fs.readFile(templatePath, 'utf8'));
+    } catch (err) {
+      return { found: false, error: err?.message ?? String(err) };
+    }
+  })();
+  if (!templateRegion.found) {
+    logError(`[lens-region] reconcile STOP — the kit's bundled agent_rules.md template canon is unreadable${templateRegion.error ? ` (${templateRegion.error})` : ''}; reinstall the kit: npx @sabaiway/agent-workflow-kit@latest init`);
+    return 1;
+  }
+  const commsResult = reconcileCommsText(text, normalizeCommsBody(templateRegion.body), COMMS_PRIORS);
+  const currentText = await (async () => {
+    if (commsResult.status === 'no-region') {
+      log(`[lens-region] no "${COMMS_LABEL}" section in ${argv[1]} — left untouched.`);
+      log('[lens-region] note: the Communication section is absent or renamed — deployments seeded before it existed simply lack it; add it from the current template to enable refresh. Your file is never rewritten.');
+      return text;
+    }
+    if (commsResult.status === 'current') {
+      log('[lens-region] Communication section already current — nothing to do (zero-diff).');
+      return text;
+    }
+    if (commsResult.status === 'custom') {
+      log('[lens-region] Communication section carries a custom edit — preserved verbatim.');
+      log('[lens-region] note: the canonical Communication section has changed since this section was edited — compare it with the current template when convenient; your wording is never overwritten.');
+      return text;
+    }
+    const commsMax = frontmatterMaxLines(text);
+    if (commsMax === null) {
+      log('[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.');
+    }
+    if (commsMax !== null && lineCount(commsResult.text) > commsMax) {
+      log(`[lens-region] refused — refreshing the Communication section would push ${argv[1]} to ${lineCount(commsResult.text)} lines (cap ${commsMax}); trim the file and re-run. The Communication section was not changed.`);
+      return text;
+    }
+    await atomicWrite(commsResult.text);
+    log('[lens-region] refreshed the Communication section to the current canon.');
+    return commsResult.text;
+  })();
+
+  // 3. No matching lens heading → preserve + advise, engine never consulted (the outcome is
+  //    preserve regardless, so the lazy contract holds).
+  if (!extractLensRegion(currentText).found) {
     log(`[lens-region] no "${HEADING_LABEL}" section in ${argv[1]} — left untouched.`);
     log('[lens-region] note: the planning/review lens section is missing or renamed — it cannot be auto-refreshed; restore the canonical heading to re-enable refresh.');
     return 0;
@@ -215,8 +299,8 @@ export const runCli = async (argv, deps = {}) => {
     return 1;
   }
 
-  // 4. The pure decision + the cap-guard + one atomic write.
-  const result = reconcileLensText(text, fragment, priors);
+  // 5. The pure decision + the cap-guard + one atomic write.
+  const result = reconcileLensText(currentText, fragment, priors);
   if (result.status === 'current') {
     log('[lens-region] lens section already current — nothing to do (zero-diff).');
     return 0;
@@ -227,21 +311,14 @@ export const runCli = async (argv, deps = {}) => {
     return 0;
   }
   // refreshed → cap-guard from the TARGET's own frontmatter, then atomic write.
-  const maxLines = frontmatterMaxLines(text);
+  const maxLines = frontmatterMaxLines(currentText);
   if (maxLines === null) {
     log('[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.');
   } else if (lineCount(result.text) > maxLines) {
-    log(`[lens-region] refused — refreshing would push ${argv[1]} to ${lineCount(result.text)} lines (cap ${maxLines}); trim the file and re-run. Nothing was changed.`);
+    log(`[lens-region] refused — refreshing would push ${argv[1]} to ${lineCount(result.text)} lines (cap ${maxLines}); trim the file and re-run. The planning/review lens section was not changed.`);
     return 0;
   }
-  const tmp = join(dirname(targetPath), `.${basename(targetPath)}.tmp-${process.pid}-${Date.now()}`);
-  try {
-    await fs.writeFile(tmp, result.text, 'utf8');
-    await fs.rename(tmp, targetPath);
-  } catch (err) {
-    await fs.rm(tmp, { force: true }).catch(() => {});
-    throw err;
-  }
+  await atomicWrite(result.text);
   log('[lens-region] refreshed the planning/review lens section to the current canon.');
   return 0;
 };

package/tools/migrate-adr-store.mjs

@@ -125,7 +125,7 @@ const isUnder = (child, parent) => {
 
 // The ordered snapshot bases that are provably NOT stageable: the git dir first (always safe), then the
 // fallback base ONLY when its snapshot dir lands OUTSIDE cwd (else it is in the work tree and could be
-// committed — reject it; codex R1 minor). Returns [{ base, dir, viaGitDir }] (possibly empty).
+// committed — reject it). Returns [{ base, dir, viaGitDir }] (possibly empty).
 const snapshotBases = (cwd, stamp, gitDir, fallbackBase) => {
   const bases = [];
   if (gitDir) bases.push({ base: gitDir, dir: resolve(gitDir, `${SNAPSHOT_PREFIX}-${stamp}`), viaGitDir: true });
@@ -226,14 +226,14 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(`  snapshot → ${preview.dir ? `${preview.dir} (${preview.viaGitDir ? 'git dir' : 'out-of-tree fallback'})` : 'NONE — no out-of-tree location; run inside a git repo (apply would refuse otherwise)'}`);
       log(`  refresh ${refresh.length} enforcement script(s) to this kit's version${drifted.length ? ` (${drifted.length} locally differ: ${drifted.map((r) => r.name).join(', ')})` : ''}`);
       log('  then the conservation-checked rotation:');
-      // Surface the rotation's own exit code (codex R1 major): a failed dry-run must NOT print the
+      // Surface the rotation's own exit code: a failed dry-run must NOT print the
       // "run with --apply" go-ahead nor exit 0 — it would send the user to --apply on an unsafe tree.
       const code = runMigrate(['--migrate'], { root: cwd, log: (m) => log(`    ${m}`), logError: (m) => error(`    ${m}`) });
       if (code !== EXIT_OK) {
         throw stop(`the dry-run rotation would not conserve every ADR (exit ${code}) — NOT safe to --apply; fix the reported problem, then re-run.`);
       }
       // A null preview means --apply would refuse (no out-of-tree snapshot base) — never green-light it
-      // (codex R2 minor: a dry-run go-ahead must not send the user to an apply that will STOP).
+      // A dry-run go-ahead must not send the user to an apply that will STOP.
       if (preview.dir === null) {
         throw stop('no out-of-tree snapshot location — --apply would refuse; run inside a git repo (or point the fallback outside the project), then re-run.');
       }

package/tools/procedures.mjs

@@ -234,7 +234,7 @@ const groundingPreStepAdvice = (activity, slots, plans) => {
   if (!slots.some((s) => (s.backends ?? []).includes('agy-review'))) return [];
   const planArg = plans.length === 1 ? `--plan "${PLANS_REL}/${plans[0]}"` : '--plan <path>';
   // plan-authoring reviews the plan FILE — when exactly one plan is in flight, the review command
-  // is populated with the same discovered path (codex R3: a known path never renders a placeholder).
+  // is populated with the same discovered path (a known path never renders a placeholder).
   const reviewForm =
     activity === 'plan-authoring'
       ? plans.length === 1

package/tools/recipes.mjs

@@ -460,7 +460,7 @@ export const composeActiveRecipeLine = ({ config, source } = {}, detection, auto
   const rec = recommendRecipe(detection);
   const origin = source === 'none' || config == null ? 'no config file — computed defaults apply' : `from ${source}`;
   // A MALFORMED policy must surface LOUDLY on this paste surface too — silently rendering cells
-  // without levels would hide the required STOP signal (codex R1, Segment B). One line always.
+  // without levels would hide the required STOP signal (Segment B). One line always.
   const malformed = autonomy?.error
     ? ` · autonomy: MALFORMED policy — ${String(autonomy.error).replace(/[\s]+/g, ' ').trim()}`
     : '';
@@ -485,7 +485,7 @@ export const buildReport = (detection, settings = null, autonomy = null, posture
     recommendation,
     plans: RECIPES.map((r) => planRecipe(r.id, detection)),
     // The SAME autonomy facts the --status-line surface renders — the --json envelope must never
-    // expose a stale machine-composed status line (codex R1, Segment B).
+    // expose a stale machine-composed status line (Segment B).
     statusLine: composeStatusLine(detection, recommendation, settings, autonomy, posture),
   };
 };