session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/tests-src-ratio.mjs

@@ -22,8 +22,11 @@
  * Here `src` is defined by NEGATION, so a new top-level directory joins the
  * denominator the moment it is committed, with no rule edit and no re-derivation.
  *
- *   universe     `git ls-files`, filtered to CODE_EXTENSIONS
- *   numerator    tracked code under `tests/`
+ *   universe     `git ls-files`, filtered to CODE_EXTENSIONS, minus declaration
+ *                files (`*.d.ts`, `*.d.mts`, `*.d.cts` — types, not executable code)
+ *   numerator    tracked code under a top-level `tests/`, plus co-located tests
+ *                anywhere: basename `*.test.<ext>` / `*.spec.<ext>`, or any file
+ *                under a `__tests__/` directory
  *   denominator  every OTHER tracked code file
  *
  * ## The four questions, answered in code rather than left open
@@ -37,8 +40,8 @@
  *   Only git-tracked?                     YES — reproducible at a SHA, and it is
  *                                         what keeps node_modules/, coverage/ and
  *                                         untracked scratch out without an ignore list.
- *   Do `tests/fixtures/` count as test LOC? YES when they are code (`.mjs`/`.js`/
- *                                         `.cjs`). A code fixture is maintained
+ *   Do `tests/fixtures/` count as test LOC? YES when they are code (any of
+ *                                         CODE_EXTENSIONS). A code fixture is maintained
  *                                         code that exists only to serve the suite —
  *                                         that is test-corpus cost. Non-code
  *                                         fixtures (`.json`, `.jsonl`, `.md`) are
@@ -62,7 +65,9 @@
  *   <repo-root>    defaults to process.cwd()
  *   --json         emit a single JSON object on stdout, nothing else
  *   --check        exit 1 when the ratio exceeds the ceiling (consolidation
- *                  wave required); exit 0 when inside the corridor
+ *                  wave required); exit 3 when the ratio is not measurable
+ *                  (`reason: 'no-tests-found'`, #1451); exit 0 when inside
+ *                  the corridor
  *   --ceiling <n>  override the TV-003 ceiling (default 1.60)
  *   --stdin        take newline-separated paths from stdin instead of
  *                  enumerating via `git ls-files` (test seam / staged-only mode)
@@ -71,6 +76,12 @@
  *   0 — measurement completed (and, under --check, ratio is within the corridor)
  *   1 — --check only: ratio exceeds the ceiling
  *   2 — tool error (missing/unreadable root, bad argv)
+ *   3 — --check only: ratio not measurable — 0 test files counted while test-like
+ *       files ARE tracked (`reason: 'no-tests-found'`, e.g. a Python repo whose
+ *       `tests/test_*.py` sit outside CODE_EXTENSIONS). Fail-closed since #1451:
+ *       before, such a repo read `ratio 0, withinCorridor true` — "not found"
+ *       reported as "in corridor". TypeScript tests count since the 2026-10-01
+ *       owner decision on #1451; other stacks still get "not measurable".
  */
 
 import { readFileSync, existsSync, statSync } from 'node:fs';
@@ -90,23 +101,65 @@ import { isMainModule } from './is-main-module.mjs';
  * Applied symmetrically to numerator and denominator by construction — a file
  * type can never inflate one side while being invisible to the other.
  */
-export const CODE_EXTENSIONS = Object.freeze(['.mjs', '.js', '.cjs']);
+export const CODE_EXTENSIONS = Object.freeze([
+  '.mjs',
+  '.js',
+  '.cjs',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+]);
 
-/** Path prefix that makes a tracked code file part of the TEST corpus. */
+/**
+ * TypeScript declaration files end in a CODE_EXTENSION but carry only types —
+ * no executable line a test could exercise. Excluded from BOTH sides, so a
+ * generated `.d.ts` can never move the ratio.
+ */
+export const DECLARATION_SUFFIXES = Object.freeze(['.d.ts', '.d.mts', '.d.cts']);
+
+/** Top-level path prefix that makes a tracked code file part of the TEST corpus. */
 export const TEST_PREFIX = 'tests/';
 
+/**
+ * Co-located test files, wherever they sit: a `*.test.<ext>` / `*.spec.<ext>`
+ * basename (the vitest/jest default include shape) or a `__tests__/` segment.
+ */
+const COLOCATED_TEST_RE = /\.(test|spec)\.[^./]+$|(^|\/)__tests__\//;
+
+/**
+ * A tracked path that LOOKS like a test, counted or not: a `*.test.*` / `*.spec.*`
+ * JS/TS file, anything under a `__tests__/` segment, or any file under `tests/`
+ * regardless of extension. Used only to tell "this repo has no tests" apart from
+ * "this repo has tests the recipe cannot see" (#1451) — e.g. `tests/test_x.py`.
+ */
+const TEST_LIKE_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+
+/**
+ * @param {string} relPath repo-relative path
+ * @returns {boolean}
+ */
+export function isTestLikePath(relPath) {
+  const p = String(relPath).replace(/\\/g, '/').replace(/^\.\//, '');
+  return TEST_LIKE_RE.test(p) || p.startsWith(TEST_PREFIX) || /(^|\/)__tests__\//.test(p);
+}
+
 /** The TV-003 ceiling. Exceeding it switches the consolidation rule on. */
 export const DEFAULT_CEILING = 1.6;
 
 /** Machine-readable schema tag for the --json envelope. */
-export const SCHEMA = 'tests-src-ratio/1';
+export const SCHEMA = 'tests-src-ratio/2';
 
 /**
  * Which bucket a repo-relative path belongs to.
  *
- * `src` is defined by NEGATION — every tracked code file that is not under
- * `tests/`. That is what makes the two buckets a partition rather than two
- * globs that can overlap or leave a gap.
+ * `src` is defined by NEGATION — every tracked code file that is not a test
+ * (under `tests/`, or co-located per COLOCATED_TEST_RE). That is what makes the
+ * two buckets a partition rather than two globs that can overlap or leave a gap.
+ *
+ * Known blind spot: a nested `pkg/tests/helper.ts` that is not itself named
+ * `*.test.*` counts as src — only the TOP-LEVEL `tests/` is a test directory.
  *
  * @param {string} relPath repo-relative path, `/`-separated
  * @returns {'test'|'src'|null} null = outside the metric entirely
@@ -114,7 +167,8 @@ export const SCHEMA = 'tests-src-ratio/1';
 export function classifyPath(relPath) {
   const p = String(relPath).replace(/\\/g, '/').replace(/^\.\//, '');
   if (!CODE_EXTENSIONS.some((ext) => p.endsWith(ext))) return null;
-  return p === TEST_PREFIX.slice(0, -1) || p.startsWith(TEST_PREFIX) ? 'test' : 'src';
+  if (DECLARATION_SUFFIXES.some((ext) => p.endsWith(ext))) return null;
+  return p.startsWith(TEST_PREFIX) || COLOCATED_TEST_RE.test(p) ? 'test' : 'src';
 }
 
 /**
@@ -154,7 +208,8 @@ export function countPhysicalLines(content) {
  * @param {(relPath: string) => string|null} opts.readFile returns content, or null when unreadable
  * @param {number} [opts.ceiling]
  * @returns {{testFiles:number,testLoc:number,srcFiles:number,srcLoc:number,ratio:number|null,
- *            ceiling:number,withinCorridor:boolean,consolidationWaveRequired:boolean,skipped:number}}
+ *            ceiling:number,withinCorridor:boolean|null,consolidationWaveRequired:boolean|null,
+ *            skipped:number,testLikeFilesSeen:number,reason:'no-tests-found'|null}}
  */
 export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
   let testFiles = 0;
@@ -162,8 +217,10 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
   let srcFiles = 0;
   let srcLoc = 0;
   let skipped = 0;
+  let testLikeFilesSeen = 0;
 
   for (const rel of files) {
+    if (isTestLikePath(rel)) testLikeFilesSeen++;
     const bucket = classifyPath(rel);
     if (bucket === null) continue;
     const content = readFile(rel);
@@ -183,6 +240,26 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
 
   // A repo with no src code has an undefined ratio, not an infinite one. Saying
   // `null` keeps the consumer from reading Infinity as a corridor breach.
+  // Fail closed (#1451): a zero numerator next to tracked test-like files means
+  // the recipe cannot SEE this repo's tests (e.g. `tests/test_x.py`), not that
+  // there are none. Reporting ratio 0 / withinCorridor true there turned "not found"
+  // into "green". The verdict is unknown, so every verdict field is null.
+  if (testFiles === 0 && testLikeFilesSeen > 0) {
+    return {
+      testFiles,
+      testLoc,
+      srcFiles,
+      srcLoc,
+      ratio: null,
+      ceiling,
+      withinCorridor: null,
+      consolidationWaveRequired: null,
+      skipped,
+      testLikeFilesSeen,
+      reason: 'no-tests-found',
+    };
+  }
+
   const ratio = srcLoc === 0 ? null : Number((testLoc / srcLoc).toFixed(4));
   const withinCorridor = ratio === null ? true : ratio <= ceiling;
 
@@ -196,6 +273,8 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
     withinCorridor,
     consolidationWaveRequired: !withinCorridor,
     skipped,
+    testLikeFilesSeen,
+    reason: null,
   };
 }
 
@@ -208,11 +287,16 @@ export function definitionOf(source) {
   return {
     source: source === 'stdin' ? 'stdin path list' : 'git ls-files (tracked files only)',
     codeExtensions: [...CODE_EXTENSIONS],
-    numerator: `tracked code files under ${TEST_PREFIX}`,
+    declarationsExcluded: [...DECLARATION_SUFFIXES],
+    numerator:
+      `tracked code files under a top-level ${TEST_PREFIX}, plus co-located tests anywhere: ` +
+      'basename *.test.<ext> / *.spec.<ext>, or any file under a __tests__/ directory',
     denominator: `every OTHER tracked code file (src defined by negation, not by a directory list)`,
     lineRule: 'physical lines; blank + comment lines counted; EOF-newline-insensitive',
     excluded:
-      'non-code extensions (.md, .json, .jsonl, .yml) on BOTH sides; untracked files (node_modules/, coverage/, scratch)',
+      `declaration files (${DECLARATION_SUFFIXES.map((x) => `*${x}`).join(', ')}: types, not ` +
+      'executable code) and non-code extensions (.md, .json, .jsonl, .yml) on BOTH sides; ' +
+      'untracked files (node_modules/, coverage/, scratch)',
   };
 }
 
@@ -322,7 +406,11 @@ const USAGE =
  * because a measurement problem must not block a session start.
  *
  * @param {{ repoRoot?: string, ceiling?: number }} [opts]
- * @returns {{ severity: 'warn', message: string, ratio: number, ceiling: number } | null}
+ * The one non-null path besides a breach is `reason: 'no-tests-found'` (#1451):
+ * a repo whose tests the recipe cannot see gets a WARN, never silence — silence
+ * is what made the unmeasurable ratio read as green fleet-wide.
+ *
+ * @returns {{ severity: 'warn', message: string, ratio: number|null, ceiling: number, reason?: string } | null}
  */
 export function checkTestsSrcRatio({ repoRoot, ceiling = DEFAULT_CEILING } = {}) {
   try {
@@ -342,6 +430,18 @@ export function checkTestsSrcRatio({ repoRoot, ceiling = DEFAULT_CEILING } = {})
     };
 
     const result = measure({ files, readFile, ceiling });
+    if (result.reason === 'no-tests-found') {
+      return {
+        severity: 'warn',
+        ratio: null,
+        ceiling: result.ceiling,
+        reason: result.reason,
+        message:
+          `⚠ tests:src ratio nicht messbar — 0 Testdateien gezählt, ` +
+          `${result.testLikeFilesSeen} test-artige Dateien getrackt (#1451). ` +
+          `Detail: node scripts/lib/tests-src-ratio.mjs --json`,
+      };
+    }
     if (result.ratio === null || result.withinCorridor) return null;
 
     const dirty = isDirty(root);
@@ -402,17 +502,20 @@ function main() {
     console.log(USAGE);
     console.log('');
     console.log('The canonical tests:src LOC measurement for TV-003 (test-value.md).');
-    console.log('  numerator    tracked code under tests/');
+    console.log('  numerator    tracked code under tests/, plus *.test.* / *.spec.* / __tests__/ anywhere');
     console.log('  denominator  every other tracked code file (src by negation)');
     console.log(`  code exts    ${CODE_EXTENSIONS.join(' ')}   (.md / .json never counted)`);
+    console.log(`  excluded     declaration files ${DECLARATION_SUFFIXES.join(' ')} on both sides`);
     console.log('  lines        physical; blanks + comments counted; EOF-newline-insensitive');
     console.log('');
     console.log('  --json         machine-readable envelope on stdout');
-    console.log('  --check        exit 1 when the ratio exceeds the ceiling');
+    console.log('  --check        exit 1 when the ratio exceeds the ceiling, 3 when not measurable');
     console.log(`  --ceiling <n>  override the TV-003 ceiling (default ${DEFAULT_CEILING})`);
     console.log('  --stdin        read newline-separated paths instead of git ls-files');
     console.log('');
-    console.log('Exit: 0 ok / within corridor · 1 (--check) ceiling exceeded · 2 tool error');
+    console.log(
+      'Exit: 0 ok / within corridor · 1 (--check) ceiling exceeded · 2 tool error · 3 (--check) not measurable',
+    );
     process.exit(0);
   }
 
@@ -460,10 +563,17 @@ function main() {
     // fail-open class is not worth re-litigating per payload size.
     writeStdoutLineSync(JSON.stringify(envelope, null, 2));
   } else {
-    const r = result.ratio === null ? 'n/a (no src code)' : result.ratio.toFixed(4);
-    const verdict = result.withinCorridor
-      ? 'within corridor'
-      : `ABOVE ceiling ${result.ceiling} — TV-003 consolidation wave required`;
+    const notMeasurable = result.reason === 'no-tests-found';
+    const r = notMeasurable
+      ? 'n/a (no tests found)'
+      : result.ratio === null
+        ? 'n/a (no src code)'
+        : result.ratio.toFixed(4);
+    const verdict = notMeasurable
+      ? `NOT MEASURABLE — ${result.testLikeFilesSeen} test-like files tracked but 0 counted (#1451)`
+      : result.withinCorridor
+        ? 'within corridor'
+        : `ABOVE ceiling ${result.ceiling} — TV-003 consolidation wave required`;
     const at = envelope.ref ? ` @ ${envelope.ref}${dirty ? '+dirty' : ''}` : '';
     writeStdoutLineSync(
       `tests:src = ${r}  (${result.testLoc} test LOC / ${result.srcLoc} src LOC` +
@@ -472,6 +582,13 @@ function main() {
     );
   }
 
+  if (args.check && result.reason === 'no-tests-found') {
+    console.error(
+      `tests:src ratio not measurable — 0 test files counted but ${result.testLikeFilesSeen} ` +
+        `test-like files tracked (no-tests-found); see #1451`,
+    );
+    process.exit(3);
+  }
   process.exit(args.check && !result.withinCorridor ? 1 : 0);
 }
 

package/scripts/lib/tmux-layout/layouts.mjs

@@ -25,6 +25,7 @@
 
 import path from 'node:path';
 import { resolveStateDir } from '../platform.mjs';
+import { shellQuote } from '../sh-quote.mjs';
 import { detectVcsCommand } from './vcs-detector.mjs';
 import { isSessionCollision } from './tmux-shell.mjs';
 
@@ -48,17 +49,6 @@ try {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Single-quote a shell command string for use as a tmux send-keys argument.
- * Escapes embedded single-quotes using the POSIX `'...' '\'' '...'` pattern.
- *
- * @param {string} s
- * @returns {string}  e.g. 'tail -F /path/to/STATE.md'
- */
-function shellQuote(s) {
-  return "'" + String(s).replace(/'/g, "'\\''") + "'";
-}
-
 /** Poll interval (seconds) of the agent-status pane loop. */
 const STATUS_PANE_POLL_SECONDS = 2;
 

package/scripts/lib/tmux-layout/telemetry-stats.mjs

@@ -2,7 +2,8 @@
  * scripts/lib/tmux-layout/telemetry-stats.mjs
  *
  * Aggregator stub for /tmux-layout telemetry promotion gate (#563).
- * Reads .orchestrator/metrics/events.jsonl and computes:
+ * Reads the events ledger — active file AND every rotated archive (#1407) —
+ * and computes:
  *   - invocation count (total + per layout)
  *   - completion rate (completed / invoked) — promotion gate threshold 80%
  *   - top-K degradation reasons
@@ -13,26 +14,68 @@
  *   - CLI: `node scripts/lib/tmux-layout/telemetry-stats.mjs` (emits JSON to stdout)
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { readEventsWithRotations } from '../events.mjs';
 import { isMainModule } from '../is-main-module.mjs';
 
 const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
 
+/** Every event this module reports on carries this prefix. */
+const TMUX_EVENT_PREFIX = 'tmux-layout.';
+
+/**
+ * Read the tmux-layout events ACROSS rotation boundaries, together with the
+ * honesty verdict of that read.
+ *
+ * WHY THE ENVELOPE (#1407 acceptance criterion 3): the stats below are an
+ * ALL-TIME rate. Reading only the active file silently redefines "all time" as
+ * "since the last rotation", and a genuinely missing archive would then look
+ * identical to a quiet week. `complete === false` says which of the two it is;
+ * the CLI prints it and never computes over a partial set in silence.
+ *
+ * THREE states (#1423): `complete === null` is a THIRD reading — no source
+ * existed at all, so `invocations: 0` is UNMEASURED, not a measured zero, and
+ * `meetsPromotionGate: false` below rests on nothing. The CLI names that case
+ * separately; folding it into `false` would report a gap nobody found, folding
+ * it into `true` would report a measurement nobody took.
+ *
+ * CEILING (BV-004): `readEventsWithRotations` loads the active file and every
+ * archive fully into memory — up to ~60 MB transient at the default
+ * `max-size-mb: 10` / `max-backups: 5`. Acceptable here because this is a COLD
+ * ops path: a hand-run CLI / promotion-gate check, never a hook and never on
+ * the session path. Revisit if this module gains a hot-path caller or if
+ * `max-size-mb` is raised past ~100.
+ *
+ * @param {string} [eventsPath=.orchestrator/metrics/events.jsonl]
+ * @returns {{events: Array<object>, complete: boolean|null, gaps: Array<object>,
+ *            notices: Array<object>}}
+ */
+export function readTmuxEventsEnvelope(eventsPath = EVENTS_PATH) {
+  const { events, gaps, complete, notices } = readEventsWithRotations(undefined, {
+    filePath: eventsPath,
+  });
+  return {
+    events: events.filter(
+      (rec) => rec && typeof rec.event === 'string' && rec.event.startsWith(TMUX_EVENT_PREFIX),
+    ),
+    complete,
+    gaps,
+    notices: notices ?? [],
+  };
+}
+
 /**
- * Read events.jsonl and return tmux-layout-related events.
+ * Read the events ledger and return tmux-layout-related events.
+ *
+ * Thin array-returning view of {@link readTmuxEventsEnvelope} — the shape every
+ * existing caller expects. Use the envelope when the completeness of the read
+ * matters to the answer.
  *
  * @param {string} [eventsPath=.orchestrator/metrics/events.jsonl]
  * @returns {Array<object>}  parsed event records (filtered to tmux-layout.* events)
  */
 export function readTmuxEvents(eventsPath = EVENTS_PATH) {
-  if (!existsSync(eventsPath)) return [];
-  const raw = readFileSync(eventsPath, 'utf-8');
-  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
-  return lines
-    .map((l) => {
-      try { return JSON.parse(l); } catch { return null; }
-    })
-    .filter((rec) => rec && typeof rec.event === 'string' && rec.event.startsWith('tmux-layout.'));
+  return readTmuxEventsEnvelope(eventsPath).events;
 }
 
 /**
@@ -95,7 +138,23 @@ export function computeStats(events) {
 
 // CLI entry-point — emit stats as JSON to stdout when run directly
 if (isMainModule(import.meta.url)) {
-  const events = readTmuxEvents();
+  const { events, complete, gaps } = readTmuxEventsEnvelope();
   const stats = computeStats(events);
-  console.log(JSON.stringify(stats, null, 2));
+  if (complete === null) {
+    // NOT MEASURED — a different sentence from "incomplete" (#1423): no active
+    // file and no archive means the zeros below were never observed.
+    console.error(
+      'WARN: no events source was readable (no active file, no archive) — the stats below are UNMEASURED, not zero',
+    );
+  } else if (!complete) {
+    // A gap, never an empty window: diagnostics on stderr (cli-design.md),
+    // the machine-readable verdict in the JSON below.
+    const detail = gaps
+      .map((g) => `${g.kind}:${path.basename(String(g.archived_as ?? 'unknown'))}`)
+      .join(', ');
+    console.error(
+      `WARN: events ledger incomplete — the all-time rate below is computed over a PARTIAL set (${gaps.length} gap(s): ${detail})`,
+    );
+  }
+  console.log(JSON.stringify({ ...stats, ledgerComplete: complete, ledgerGaps: gaps }, null, 2));
 }

package/scripts/lib/tmux-layout/tmux-shell.mjs

@@ -6,6 +6,8 @@
 
 import { execSync } from 'node:child_process';
 
+import { shellQuote } from '../sh-quote.mjs';
+
 const MIN_MAJOR = 3;
 const MIN_MINOR = 0;
 
@@ -69,14 +71,3 @@ export function isSessionCollision(sessionName) {
     return { exists: false, error: `tmux has-session failed: ${err.message}` };
   }
 }
-
-/**
- * Shell-quote a string for safe interpolation into a shell command.
- * Uses single-quote wrapping with embedded single-quote escaping.
- *
- * @param {string} s
- * @returns {string}
- */
-function shellQuote(s) {
-  return "'" + String(s).replace(/'/g, "'\\''") + "'";
-}

package/scripts/lib/user-invocable-skills.mjs

@@ -102,11 +102,31 @@ function normaliseScalar(text) {
  * than inventing a fifth dialect. Because the demotion is the surprising half,
  * each one emits exactly one stderr WARN naming the file.
  *
+ * The same normalisation governs the SIBLING boolean marker
+ * `disable-model-invocation` (the Cursor and Codex adapters read it with this
+ * predicate). The WARN therefore names the key it was asked about rather than a
+ * hard-coded `user-invocable`: measured 2026-09-18, a `disable-model-invocation:
+ * yes` demotion reported `user-invocable: "yes"`, sending the operator to a
+ * line that does not exist in that file.
+ *
+ * The NOUN follows the key too (#1388 P10). Naming the key while hard-coding
+ * "is NOT a slash-command marker" told a `disable-model-invocation: yes` author
+ * that his value failed to be something it never was — a correct key with a
+ * wrong subject reads as a broken diagnostic. The default phrase is unchanged
+ * for `user-invocable`, so the four existing call sites see identical text.
+ *
  * @param {unknown} value the raw frontmatter value
  * @param {string} [file] path named in the WARN when a truthy-looking value is demoted
+ * @param {string} [key] frontmatter key named in the WARN (default `user-invocable`)
  * @returns {boolean}
  */
-export function isUserInvocableValue(value, file) {
+const MARKER_NOUN = Object.freeze({
+  'user-invocable': 'a slash-command marker',
+  'disable-model-invocation': 'a model-invocation opt-out marker',
+});
+const DEFAULT_MARKER_NOUN = 'a boolean marker';
+
+export function isUserInvocableValue(value, file, key = 'user-invocable') {
   if (value === true) return true;
   if (typeof value !== 'string') return false;
   const token = normaliseScalar(value);
@@ -114,8 +134,8 @@ export function isUserInvocableValue(value, file) {
   if (TRUTHY_LOOKALIKE.test(token)) {
     const where = file ? `${file}: ` : '';
     process.stderr.write(
-      `WARN ${where}user-invocable: ${JSON.stringify(value)} is NOT a slash-command marker — `
-        + 'only `true` is (YAML 1.2 reads yes/on/1 as strings). Write `user-invocable: true`.\n',
+      `WARN ${where}${key}: ${JSON.stringify(value)} is NOT ${MARKER_NOUN[key] ?? DEFAULT_MARKER_NOUN} — `
+        + `only \`true\` is (YAML 1.2 reads yes/on/1 as strings). Write \`${key}: true\`.\n`,
     );
   }
   return false;

package/scripts/lib/ux-grill/reconcile.mjs

@@ -37,12 +37,16 @@
  * mistaken import away from filing issues nobody asked for.
  *
  * Exports:
- *   UX_GRILL_LABELS, buildIssueTitle, buildIssueBody, reconcileFindings
+ *   UX_GRILL_LABELS, buildIssueTitle, buildUxGrillIssueBody, reconcileFindings
+ *   buildIssueBody — @deprecated alias of buildUxGrillIssueBody (5.2.0 name),
+ *     removed in 6.0.0
  */
 
 import {
   createFinding as defaultCreateFinding,
+  fingerprintSentinelLine,
   listExistingFindings as defaultListExisting,
+  neutralizeFingerprintSentinel,
   triageDecision,
   updateFinding as defaultUpdateFinding,
 } from '../test-runner/issue-reconcile.mjs';
@@ -69,31 +73,22 @@ const TITLE_MAX_LENGTH = 100;
 const AUTO_SEVERITIES = Object.freeze(['critical', 'high']);
 
 /**
- * Neutralise a fingerprint-sentinel literal in free text (#388 SEC-IR-MED-1).
+ * Neutralise fingerprint-sentinel literals (#388 SEC-IR-MED-1) and strip the
+ * characters `createFinding` rejects at the argv boundary, so a multi-line page
+ * title in a finding message cannot turn into a VALIDATION failure for the whole
+ * reconcile pass.
  *
- * `issue-reconcile.mjs` applies this to `recommendation` only, inside
- * `reconcileFinding` — a body built HERE and handed to `createFinding` is not
- * sanitised by anything, so a finding `message` echoing page text could forge
- * the authoritative `**Fingerprint:**` line and make the next run's
+ * The neutralisation is the SHARED one from `issue-reconcile.mjs` (#1339 P6): a
+ * body built HERE and handed to `createFinding` is not sanitised by anything
+ * else, so a finding `message` echoing page text could otherwise forge the
+ * authoritative `**Fingerprint:**` line and make the next run's
  * `triageDecision` dedup against the wrong issue.
  *
  * @param {unknown} text
  * @returns {string}
  */
-function sanitizeSentinel(text) {
-  return String(text ?? '').replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
-}
-
-/**
- * Strip the characters `createFinding` rejects at the argv boundary, so a
- * multi-line page title in a finding message cannot turn into a VALIDATION
- * failure for the whole reconcile pass.
- *
- * @param {unknown} text
- * @returns {string}
- */
 function oneLine(text) {
-  return sanitizeSentinel(text).replace(/[\n\r\0]+/g, ' ').trim();
+  return neutralizeFingerprintSentinel(text).replace(/[\n\r\0]+/g, ' ').trim();
 }
 
 /**
@@ -144,7 +139,7 @@ export function buildIssueTitle(finding) {
  * @param {string} [context.rubricHash]
  * @returns {string}
  */
-export function buildIssueBody(finding, { runId, rubricHash } = {}) {
+export function buildUxGrillIssueBody(finding, { runId, rubricHash } = {}) {
   const evidence = finding?.evidence ?? {};
   const evidenceLines = Object.entries(evidence)
     .filter(([, value]) => typeof value === 'string' || Array.isArray(value))
@@ -153,7 +148,7 @@ export function buildIssueBody(finding, { runId, rubricHash } = {}) {
   return [
     oneLine(finding?.message) || `${oneLine(finding?.checkId)} at ${oneLine(finding?.locator)}`,
     '',
-    `**Fingerprint:** \`${oneLine(finding?.fingerprint)}\``,
+    fingerprintSentinelLine(oneLine(finding?.fingerprint)),
     `**Severity:** ${oneLine(finding?.severity)}`,
     `**Check:** ${oneLine(finding?.checkId)}`,
     `**Locator:** \`${oneLine(finding?.locator)}\``,
@@ -168,6 +163,37 @@ export function buildIssueBody(finding, { runId, rubricHash } = {}) {
     .join('\n');
 }
 
+/** One stderr line per process for the deprecated alias below, not one per call. */
+let buildIssueBodyDeprecationWarned = false;
+
+/**
+ * Deprecated alias of {@link buildUxGrillIssueBody}, shipped under this name in
+ * 5.2.0.
+ *
+ * @deprecated since 5.3.0 — use buildUxGrillIssueBody; removed in 6.0.0.
+ * Kept one minor cycle (`.claude/rules/development.md` § Package Lifecycle &
+ * Versioning) because `package.json` carries no `exports` map: every packed
+ * `scripts/lib/` export is a public deep-import, and a consumer calling this
+ * name would otherwise get a runtime TypeError, not a compile error. It
+ * delegates to the LOCAL ux-grill body builder — never to the unrelated
+ * `buildIssueBody(finding, fp)` of `test-runner/issue-reconcile.mjs`, whose
+ * finding shape and second argument differ.
+ *
+ * @param {object} finding - a `makeFinding` record
+ * @param {object} [context] - same as {@link buildUxGrillIssueBody}
+ * @returns {string}
+ */
+export function buildIssueBody(finding, context) {
+  if (!buildIssueBodyDeprecationWarned) {
+    buildIssueBodyDeprecationWarned = true;
+    console.warn(
+      '[deprecated] buildIssueBody from scripts/lib/ux-grill/reconcile.mjs is deprecated since the 5.3 line ' +
+        'and will be removed in 6.0.0 — use buildUxGrillIssueBody instead.',
+    );
+  }
+  return buildUxGrillIssueBody(finding, context);
+}
+
 /**
  * Collect every string in a finding's `evidence` that looks like an absolute
  * host path (POSIX `/…` or Windows `C:\…`).
@@ -296,7 +322,7 @@ export async function reconcileFindings({
     }
 
     const title = buildIssueTitle(finding);
-    const body = buildIssueBody(finding, { runId, rubricHash });
+    const body = buildUxGrillIssueBody(finding, { runId, rubricHash });
     const decision = triageDecision({ fingerprint: finding?.fingerprint, title }, candidates);
 
     if (decision.action === 'ignore') {