@sabaiway/agent-workflow-kit 3.1.0 → 3.3.0

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/recipes.mjs

@@ -394,7 +394,10 @@ const projectTopOf = (cwd) => {
   }
 };
 
-export const composeAutonomyFacts = async (cwd) => {
+// `deps` is threaded to the render check because that check now PROBES the installed harness: without
+// a seam the render state would vary with the machine composing the facts, and a caller could not
+// pin it. Production passes nothing and probes for real.
+export const composeAutonomyFacts = async (cwd, deps = {}) => {
   try {
     const root = projectTopOf(cwd);
     const { loadAutonomy, resolveAutonomy, isSparseSeedConfig } = await import('./autonomy-config.mjs');
@@ -411,7 +414,7 @@ export const composeAutonomyFacts = async (cwd) => {
     let renderState;
     try {
       const { checkAutonomyProfile } = await import('./velocity-profile.mjs');
-      renderState = checkAutonomyProfile({ cwd: root }).inSync
+      renderState = checkAutonomyProfile({ cwd: root }, deps).inSync
         ? 'in sync'
         : 'DRIFT — re-run the velocity --autonomy render';
     } catch (err) {

package/tools/release-scan.mjs

@@ -36,7 +36,10 @@ const ATTRIBUTION = [
   { re: /authored[- ]by[: ][^\n]{0,40}\b(claude|chatgpt|gemini|copilot)\b/i, label: 'AI authorship attribution' },
 ];
 const REVIEWER_IDENTITY = [
+  // backend-then-round: a bridge name, a separator, then r<N> (with optional +/round suffixes).
   { re: /\b(?:agy|codex)(?:\s+|-)r\d+(?:(?:\+|\/)r?\d+)*(?:-[a-z0-9]+)*\b/i, label: 'reviewer-round identity' },
+  // round-then-backend (reverse order): r<N>, a separator, then a bridge name — the release-review gap.
+  { re: /\br\d+(?:\s+|-)(?:agy|codex)\b/i, label: 'reviewer-round identity' },
 ];
 
 const allowlistCovers = (matched, allowlist) =>
@@ -60,6 +63,81 @@ export const scanText = (text, { allowlist = ALLOWLIST } = {}) => {
   return findings;
 };
 
+// ── the version-pin rung ─────────────────────────────────────────────────────────────────────────
+// A hardcoded harness version under tools/ is a documentation claim frozen in code: it goes stale by
+// default and nothing reports it. This rung refuses a BARE pin and demands a runtime probe beside
+// it — the probe is what converts silent staleness into a loud degrade.
+//
+// A line is a claim when it names the harness AND carries a version literal. The rung reports
+// exactly those lines — it deliberately does NOT spread the claimed series across the rest of the
+// file, which was measured to flag an unrelated dependency constant that merely shared a major.minor
+// with the claim two lines above it. Nothing is lost by the narrower rule: the exemption is
+// FILE-scoped, so a single refusal already forces the probe that makes every literal in the file
+// honest. (This comment names the harness without a literal on the same line ON PURPOSE — the rung
+// scans its own source, and a worked example here would make the scanner refuse itself.)
+//
+// STATED RESIDUAL, not an oversight: a claim split across lines — the harness named on one line, the
+// literal on another — is NOT detected. Closing it needs whole-file arming, which trades this narrow
+// miss for a broad false-positive class. Deliberate line splitting is left to human review; this rung
+// is a guard against staleness that accumulates by default, not against an author evading it.
+const HARNESS_CLAIM_RE = /\bclaude\b/i;
+const SEMVER_LITERAL_RE = /\b\d+\.\d+\.\d+\b/g;
+const TOOLS_SEGMENT = 'tools';
+const PATH_SEP_RE = /[/\\]/;
+const VERSION_PIN_REMEDY =
+  'pair it with a runtime probe (probeHarnessVersion) that compares the pin to the installed build '
+  + 'and degrades loudly, or move the literal into a test fixture or changelog entry, where it '
+  + 'records history instead of asserting a live platform fact';
+
+// Three exemptions, each because the literal is NOT a live claim there. A test fixture and a
+// changelog entry record what was true at a moment; a file that CALLS the probe already reports its
+// own staleness, which is the entire behaviour the rung exists to demand.
+//
+// The probe exemption is a REFERENCE test, deliberately: it asks exactly what the decision asks —
+// that a runtime probe sits beside the literal — and claims nothing more.
+//
+// It was briefly a CALL test. Separating a call from a declaration, a comment, a string and a regex
+// literal is JS lexing, and hand-rolling that opened a new hole in three consecutive review rounds:
+// a legitimate member call wrongly refused, then a per-character recursion that would crash this
+// scanner inside the commit gate, then a regex literal read as a call. The repo does own a real
+// lexical code mask — in root tooling a shipped kit tool cannot import — and extracting it is queued
+// as its own work rather than approximated again here.
+//
+// STATED RESIDUAL, and why the precision was not worth its risk: even a perfect call detector proves
+// only that the probe is REACHABLE in this file, never that its result is compared against the
+// literal. That stronger guarantee was never on offer, so the rung stops where the decision stops
+// and says so. The exemption stays scoped to files that could call anything at all — a `#` comment
+// in a shell script and a line of Markdown prose earn nothing.
+const PROBE_CALLABLE_EXT = new Set(['.mjs', '.js']);
+const PROBE_SYMBOL = 'probeHarnessVersion';
+const TEST_FILE_RE = /\.test\.mjs$/;
+const CHANGELOG_FILE_RE = /^CHANGELOG\.md$/i;
+
+const semverLiteralsIn = (line) => line.match(SEMVER_LITERAL_RE) ?? [];
+const isUnderTools = (path) => String(path).split(PATH_SEP_RE).includes(TOOLS_SEGMENT);
+const isRecordNotClaim = (path) => {
+  const name = basename(String(path));
+  return TEST_FILE_RE.test(name) || CHANGELOG_FILE_RE.test(name);
+};
+
+// PURE: classify one file's text. Path-aware — the same literal is a claim under tools/ and history
+// in a changelog, so the verdict cannot be made from the bytes alone.
+export const scanVersionPins = (text, path) => {
+  if (!isUnderTools(path) || isRecordNotClaim(path)) return [];
+  const probeCallable = PROBE_CALLABLE_EXT.has(extname(String(path)));
+  if (probeCallable && text.includes(PROBE_SYMBOL)) return [];
+  return text.split('\n').flatMap((line, idx) => {
+    const pinned = HARNESS_CLAIM_RE.test(line) ? semverLiteralsIn(line) : [];
+    return pinned.length === 0
+      ? []
+      : [{
+        line: idx + 1,
+        kind: 'version-pin',
+        detail: `harness version pin ${pinned.join(', ')} with no runtime probe in this file — a version literal frozen in code goes stale silently; ${VERSION_PIN_REMEDY}`,
+      }];
+  });
+};
+
 const TEXT_EXT = new Set(['.md', '.mjs', '.js', '.json', '.sh', '.yml', '.yaml', '.txt', '']);
 const EXCLUDE_DIR_NAMES = new Set(['node_modules', '.git', 'plans', 'scan-fixtures']);
 // Only the TEST is self-excluded — it necessarily contains attribution fixtures. The scanner source
@@ -78,34 +156,90 @@ const walk = (path, acc = []) => {
   return acc;
 };
 
-export const scanPaths = (paths, opts = {}) => {
+// Per-target outcomes. A caller-NAMED target that contributes no file must never fold into the
+// clean verdict — an empty file list and a clean one print identically, so a mis-aimed scan would
+// read as proof of cleanliness. `unmatchedGlob` is the one benign zero: the gate declaration lists
+// shell globs, and bash passes an unmatched glob through literally, so a path that still carries a
+// glob metacharacter is an optional target the shell found nothing for, not a mis-aim.
+export const TARGET = Object.freeze({
+  scanned: 'scanned',
+  missing: 'missing',
+  unmatchedGlob: 'unmatched-glob',
+  excluded: 'excluded',
+  empty: 'empty',
+});
+
+const GLOB_META_RE = /[*?[\]]/;
+
+// PURE-ish (one fs read): classify ONE caller-named target and collect the files it contributes.
+// Every zero-contribution status names its own cause, so the refusal can state the remedy rather
+// than a bare count (a count without a location is the defect class this family bans).
+export const classifyTarget = (path) => {
+  if (!existsSync(path)) {
+    return GLOB_META_RE.test(path)
+      ? { path, status: TARGET.unmatchedGlob, files: [] }
+      : { path, status: TARGET.missing, files: [] };
+  }
+  const st = statSync(path);
+  const name = basename(path);
+  if (st.isDirectory() && EXCLUDE_DIR_NAMES.has(name)) return { path, status: TARGET.excluded, files: [] };
+  if (st.isFile() && (EXCLUDE_FILE_NAMES.has(name) || !TEXT_EXT.has(extname(path)) || path.endsWith('.tgz'))) {
+    return { path, status: TARGET.excluded, files: [] };
+  }
+  const files = walk(path);
+  return { path, status: files.length > 0 ? TARGET.scanned : TARGET.empty, files };
+};
+
+// Why each zero-contribution status refuses, and the one legal remedy for it.
+const TARGET_REMEDY = Object.freeze({
+  [TARGET.missing]: 'the path does not exist — fix the target, or drop it from the target list',
+  [TARGET.excluded]: `the target itself is excluded (directory names: ${[...EXCLUDE_DIR_NAMES].join(', ')}; non-text or self-excluded files) — name the FILES to scan instead of the directory`,
+  [TARGET.empty]: 'the target exists but holds no scannable text file — fix the target, or drop it from the target list',
+});
+
+const findingsIn = (targets, opts) => {
   const report = [];
-  for (const p of paths) {
-    if (!existsSync(p)) continue;
-    for (const file of walk(resolve(p))) {
-      const findings = scanText(readFileSync(file, 'utf8'), opts);
-      for (const f of findings) report.push({ file, ...f });
+  for (const target of targets) {
+    for (const file of target.files) {
+      const text = readFileSync(file, 'utf8');
+      for (const finding of scanText(text, opts)) report.push({ file, ...finding });
+      for (const finding of scanVersionPins(text, file)) report.push({ file, ...finding });
     }
   }
   return report;
 };
 
+export const scanPaths = (paths, opts = {}) => findingsIn(paths.map((p) => classifyTarget(resolve(p))), opts);
+
 export const main = (argv) => {
   const reportOnly = argv.includes('--report');
   const paths = argv.filter((a) => a !== '--report');
   if (paths.length === 0) {
     console.error('usage: release-scan.mjs [--report] <path>...');
-    process.exit(2);
+    return 2;
+  }
+  const targets = paths.map((p) => classifyTarget(resolve(p)));
+  for (const target of targets) {
+    if (target.status === TARGET.unmatchedGlob) {
+      console.log(`[release-scan] skipped ${target.path} — no file matched this glob (an optional target, stated not silent).`);
+    }
+  }
+  const misaimed = targets.filter((target) => TARGET_REMEDY[target.status] !== undefined);
+  for (const target of misaimed) {
+    console.log(`[release-scan] target ${target.path} contributed NO file (${target.status}) — ${TARGET_REMEDY[target.status]}`);
   }
-  const report = scanPaths(paths);
+  const report = findingsIn(targets);
   for (const r of report) console.log(`[${r.kind}] ${r.file}:${r.line} — ${r.detail}`);
-  if (report.length === 0) {
+  if (misaimed.length > 0) {
+    console.log(`\n[release-scan] ${misaimed.length} mis-aimed target(s) — this run proves nothing about them, so the clean verdict is refused.`);
+  }
+  if (report.length > 0) console.log(`\n[release-scan] ${report.length} finding(s).`);
+  if (report.length === 0 && misaimed.length === 0) {
     console.log('[release-scan] clean — no AI attribution or reviewer-round identity found.');
-    return;
+    return 0;
   }
-  console.log(`\n[release-scan] ${report.length} finding(s).`);
-  if (!reportOnly) process.exit(1);
+  return reportOnly ? 0 : 1;
 };
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) main(process.argv.slice(2));
+if (isDirectRun) process.exitCode = main(process.argv.slice(2));

package/tools/run-gates.mjs

@@ -77,6 +77,12 @@ const USAGE = [
   '',
   `Runs the gates declared in <cwd>/${GATES_REL} (one bash command line each, project root as cwd).`,
   'Prints a per-gate PASS/FAIL table + one machine-readable summary line; exit 0 iff all green.',
+  '',
+  'Producer env: AW_GIT_DIR (inside a git tree) and AW_LCOV_FILE (--final only) are computed and',
+  'exported to every gate child, and STRIPPED from the inherited environment first — a host-set',
+  'value never stands in for a computed one. A selected gate referencing a producer variable this',
+  'run will not set is refused BEFORE anything spawns (exit 1), naming the gate, the variable, and',
+  'the remedy — never left to expand to empty and fail far from its cause.',
   'Sandbox-safe: the runner itself needs no network and writes only repo-local state — the D4 sandbox',
   'lane; each DECLARED gate command is the project\'s own, so ITS sandbox-safety is command-shape',
   'dependent (first try the sandbox-safe shape — cache under $TMPDIR, offline/notifier off).',
@@ -184,12 +190,37 @@ export const selectGates = (gates, onlyIds) => {
 // NODE_TEST_CONTEXT is stripped: a `node --test` gate spawned while run-gates is itself running
 // under a parent test context would otherwise inherit it, hit Node's recursive-run guard, silently
 // skip every file, and exit 0 — a vacuous false green.
+// The variables this runner PRODUCES for gate children. They are stripped from the inherited
+// environment before every spawn: composing the child env as {...process.env, ...injected} would
+// let a stale or hostile HOST value stand in whenever this run injects nothing, so a gate would
+// silently attest against the wrong git dir or lcov instead of the computed one.
+export const RESERVED_PRODUCER_ENV = Object.freeze(['AW_GIT_DIR', 'AW_LCOV_FILE']);
+
 export const spawnGateViaBash = (cmd, cwd, extraEnv = {}) => {
-  const env = { ...process.env, ...extraEnv };
+  const env = { ...process.env };
   delete env.NODE_TEST_CONTEXT;
-  return spawnSync('bash', ['-c', cmd], { cwd, env, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
+  for (const name of RESERVED_PRODUCER_ENV) delete env[name];
+  return spawnSync('bash', ['-c', cmd], { cwd, env: { ...env, ...extraEnv }, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
 };
 
+// A `$VAR` / `${VAR}` reference to a producer variable. A `${VAR:-default}` form is deliberately NOT
+// matched — a cmd carrying its own fallback does not depend on the injection.
+const referencesProducer = (cmd, name) => new RegExp(`\\$\\{${name}\\}|\\$${name}(?![A-Za-z0-9_])`).test(cmd);
+
+const PRODUCER_RECOVERY = Object.freeze({
+  AW_GIT_DIR: 'run from inside a git work tree — the runner resolves the git dir there and exports it to every gate.',
+  AW_LCOV_FILE: 'AW_LCOV_FILE is produced only by --final — run with --final, or drop the reference from the gate cmd.',
+});
+
+// Which SELECTED gates reference a producer variable this run will not set. Such a reference
+// expands to empty and fails the gate somewhere far from its cause, so it is refused before
+// anything spawns, naming the gate, the variable, and the one remedy.
+export const findUnmetProducerRefs = (gates, injected) =>
+  gates.flatMap((gate) =>
+    RESERVED_PRODUCER_ENV
+      .filter((name) => !injected.includes(name) && referencesProducer(gate.cmd, name))
+      .map((name) => ({ id: gate.id, name })));
+
 // The command the bash preflight runs before ANY gate: proves bash itself spawns on this host,
 // so "no bash" is one loud exit-6 error up front — never a per-gate spawn-failure cascade.
 export const BASH_PROBE_CMD = 'true';
@@ -378,6 +409,16 @@ export const runCli = (argv, deps = {}) => {
       // gate child env — a stray host AW_LCOV_FILE can never desync the checker from the receipt.
       gateSpawn = (cmd, cwd2) => spawn(cmd, cwd2, { AW_GIT_DIR: gitDir, AW_LCOV_FILE: join(gitDir, LCOV_BASENAME) });
     }
+    const injectedEnv = [...(gitDir === null ? [] : ['AW_GIT_DIR']), ...(opts.final ? ['AW_LCOV_FILE'] : [])];
+    const unmet = findUnmetProducerRefs(selected, injectedEnv);
+    if (unmet.length > 0) {
+      for (const { id, name } of unmet) {
+        logError(`[run-gates] gate "${id}" references $${name}, which this run will not set — it would expand to empty and fail far from its cause.`);
+        logError(`   Recovery: ${PRODUCER_RECOVERY[name]}`);
+      }
+      log(composeSummaryLine({ status: 'fail' }));
+      return EXIT.fail;
+    }
     const probe = spawn(BASH_PROBE_CMD, projectDir);
     if (probe.error && probe.error.code === 'ENOENT') {
       logError(