@onlineapps/conn-orch-validator 9.0.0 → 10.0.0

package/src/lint/scripts/lintScripts.js

@@ -30,12 +30,22 @@
  * biz repositories: 47 `@see` lines under their scripts directories, of which 4
  * open with the `api/` prefix.
  *
- * Two scopes, two rules. S001-S008 read the HEADER of every script under
- * `scripts/`. S009 reads the COMMENTS of every test under `tests/scripts/` and
- * nothing else in them: a `<path>.<ext>:<line>` citation in prose has no
- * mechanism keeping it true (`doc-code-binding.md` §1), while the same shape on
- * a CODE line is a fixture assertion whose target the test creates itself and
- * which therefore cannot rot.
+ * Two scopes, three rules. S001-S008 read the HEADER of every script under
+ * `scripts/`. S009 and S010 read the tests, and they read opposite halves of
+ * them. S009 reads the COMMENTS and nothing else: a `<path>.<ext>:<line>`
+ * citation in prose has no mechanism keeping it true (`doc-code-binding.md`
+ * §1), while the same shape on a CODE line is a fixture assertion whose target
+ * the test creates itself and which therefore cannot rot. S010 reads the CODE
+ * lines and nothing else: an inverted command is exempt from `errexit`, so an
+ * assertion written that way asserts nothing unless it happens to be the last
+ * command of the body.
+ *
+ * The test scope is `tests/`, not the one directory S009 was born in. A rule
+ * that reads `tests/scripts/` and not `tests/scripts-docker/` beside it has a
+ * hole nobody can see: the run reports `0 finding(s)` and never says which
+ * files it did not open. Widened in d.482 (2026-09-15) together with S010, over
+ * a scope measured clean for both rules first — no baseline
+ * (`automation-gates.md` §3).
  *
  * @see api/docs/standards/SCRIPTS-STANDARD.md
  * @see api/docs/governance/confirmations/biz-service-manifest.md
@@ -54,8 +64,8 @@ const SHELL_VOCAB = new Set(['bash>=4', 'bash>=3.2', 'sh', 'node>=18', 'node>=24
 /** The directory whose scripts carry the header. */
 const SCRIPT_SCOPE = 'scripts';
 
-/** The directory whose COMMENTS S009 reads, and nothing else in it. */
-const CITATION_SCOPE = 'tests/scripts';
+/** The directory whose tests S009 and S010 read, each one half of them. */
+const CITATION_SCOPE = 'tests';
 
 /**
  * The directories whose files are libraries rather than entry points.
@@ -111,6 +121,27 @@ const LINE_CITATION = /[A-Za-z0-9_/.-]+\.(?:js|mjs|cjs|ts|mts|sh|bash|bats|yml|j
 /** A comment line of a shell-family test. */
 const COMMENT_LINE = /^\s*#/;
 
+/**
+ * An assertion written as an inverted command, in the two shapes bats carries.
+ *
+ * Measured on bats 1.13.0: under `set -e` a command whose exit code is inverted
+ * is exempt from errexit, so `! cmd` in the middle of a test body fails nothing
+ * — the test stays green whatever `cmd` returns. Only the LAST command of the
+ * body decides the verdict, which is why the defect survives review: the line
+ * reads like an assertion and is one exactly when it happens to sit last.
+ *
+ * The rule does not try to tell the last command from the others. It reports
+ * every occurrence, because the position is a property of the file's current
+ * shape rather than of the assertion's intent: a line inserted below turns a
+ * working assertion into an inert one with no edit to the assertion itself.
+ * INFRA rewrote all 32 occurrences this platform carried before the rule landed
+ * (`572488c4`, `6100477e`, `d212d3c6`), so the stricter reading costs nothing.
+ *
+ * `if ! cmd; then … fi` is NOT this defect and matches neither pattern: there
+ * the `if` consumes the exit code on purpose, which is the shape the fix uses.
+ */
+const INERT_ASSERTION = Object.freeze([/^\s*!\s/, /\|\|\s*!\s/]);
+
 /** The prefix a citation of the api checkout opens with, as every document writes it. */
 const API_PREFIX = 'api/';
 
@@ -265,22 +296,38 @@ function lintScripts({ root, apiRoot = null }) {
     );
   }
 
-  // S009: a comment under tests/scripts/ cites a symbol or a literal string, and
-  // a covered defect cites the commit hash — never a line number.
+  // S009 on the comment lines, S010 on the code lines. One pass, because they
+  // partition the same file: a line is prose or it is a command, never both.
   for (const relative of citationScanned) {
     const lines = fs.readFileSync(path.join(root, ...relative.split('/')), 'utf8').split('\n');
     for (let n = 0; n < lines.length; n += 1) {
-      if (!COMMENT_LINE.test(lines[n])) continue;
-      const hit = lines[n].match(LINE_CITATION);
-      if (hit === null) continue;
+      // S009: a comment cites a symbol or a literal string, and a covered
+      // defect cites the commit hash — never a line number.
+      if (COMMENT_LINE.test(lines[n])) {
+        const hit = lines[n].match(LINE_CITATION);
+        if (hit === null) continue;
+        findings.push({
+          id: 'S009',
+          file: relative,
+          line: n + 1,
+          message: `Comment cites a line number - "${hit[0]}". A line number has no mechanism keeping it true: `
+            + 'the file moves and the number stays (doc-code-binding.md §1). Fix: cite a symbol or a literal '
+            + 'string; a covered defect cites the commit hash that introduced or repaired it '
+            + "(git log -S'<string>' --format=%h -- <file>) - DOC-STANDARD rule 11."
+        });
+        continue;
+      }
+
+      // S010: an assertion whose exit code is inverted is exempt from errexit.
+      if (!INERT_ASSERTION.some((shape) => shape.test(lines[n]))) continue;
       findings.push({
-        id: 'S009',
+        id: 'S010',
         file: relative,
         line: n + 1,
-        message: `Comment cites a line number - "${hit[0]}". A line number has no mechanism keeping it true: `
-          + 'the file moves and the number stays (doc-code-binding.md §1). Fix: cite a symbol or a literal '
-          + 'string; a covered defect cites the commit hash that introduced or repaired it '
-          + "(git log -S'<string>' --format=%h -- <file>) - DOC-STANDARD rule 11."
+        message: `Inert assertion - "${lines[n].trim()}". Under set -e a command with an inverted exit code `
+          + 'is exempt from errexit, so it fails nothing unless it is the last command of the test body. '
+          + 'Fix: if <what must not hold>; then echo "[ctx] problem - found: …" >&2; return 1; fi '
+          + '— SCRIPTS-STANDARD.md § Enforcement'
       });
     }
   }

package/src/manifest/checks/composeRunnerBlock.js

@@ -24,19 +24,24 @@
  * (here) — one concern, one rail (`.claude/rules/change-discipline.md` § One rail
  * per concern). Everything else in the block is compared byte for byte.
  *
- * The service's own identity is the other normalization: the runner's key is
- * `<container>_tests`, and the container name is the one thing that is per
- * repository by construction. It is substituted back to the template's
- * placeholders before the comparison, so the block is read as the template
- * wrote it.
+ * The service's own identity is the other half, and it is settled in ONE
+ * direction: the reference is RENDERED with this repository's names and the
+ * result compared against the file, never the file read back into placeholders
+ * (d.531). The runner's key is `<container>_tests` and the container name is per
+ * repository by construction, so a render is exact; reading a name back is not,
+ * because a name is also an ordinary word — for `api_biz/meta` it rewrote the
+ * template's own citation of that path and reported a conformant block as
+ * drifted. `renderRunnerIdentity` below is that one direction, and both the
+ * check and the generator go through it.
  *
  * ## The same definition renders
  *
- * `renderRunnerBlock` performs exactly the inverse: the template's block with
- * this repository's identity in it and this repository's three shared
- * declarations grafted in. That is what makes `npx oa-sync-template
- * docker-compose.yml` produce a block the check then finds clean — a generator
- * whose output its own check rejects is the defect this module exists to avoid.
+ * `renderRunnerBlock` is the generator's half: the same identity render, plus
+ * this repository's three shared declarations grafted in. That is what makes
+ * `npx oa-sync-template docker-compose.yml` produce a block the check then finds
+ * clean — a generator whose output its own check rejects is the defect this
+ * module exists to avoid, and it is measured over a service called `meta`
+ * (`tests/unit/manifestServiceFiles.test.js`).
  *
  * @see api/docs/governance/confirmations/biz-service-manifest.md §2, §3.2
  * @see api/docs/governance/confirmations/biz-test-container.md
@@ -156,8 +161,22 @@ function stripDeclarations(lines, keys) {
 }
 
 /**
- * A repository's runner block as the template wrote it: its identity replaced by
- * the placeholders, and the three shared declarations removed.
+ * The template's block with one repository's identity in it — the ONE direction
+ * this module substitutes (d.531).
+ *
+ * The other direction, reading a repository's block back into placeholders, was
+ * a second rail under the same rule and it could not be made right: a
+ * substitution of the service's NAME rewrites every occurrence of that string,
+ * including one in the template's own prose. Measured over `api_biz/meta`: the
+ * block cites `api_biz/meta/docker-compose.yml` as the file the memory numbers
+ * were taken in, so that service's conformant block was normalized into
+ * `api_biz/__SERVICE_NAME__/docker-compose.yml` and reported as drifted, while
+ * `oa-sync-template docker-compose.yml --check` — which renders — called the
+ * same file unchanged.
+ *
+ * A placeholder is a name nothing else can be, so rendering is total; a name is
+ * a word, and reading it back is a guess. One rail, and it is this one
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
  *
  * The container name is substituted BEFORE the service name on purpose: the
  * container name normally contains the service name (`api_service_converter`
@@ -167,10 +186,10 @@ function stripDeclarations(lines, keys) {
  * @param {{lines: string[], containerName: string, serviceName: string}} args
  * @returns {string[]}
  */
-function normalizeRunnerBlock({ lines, containerName, serviceName }) {
-  return stripDeclarations(lines, SHARED_DECLARATIONS).map((line) => line
-    .split(containerName).join(CONTAINER_PLACEHOLDER)
-    .split(serviceName).join(SERVICE_PLACEHOLDER));
+function renderRunnerIdentity({ lines, containerName, serviceName }) {
+  return lines.map((line) => line
+    .split(CONTAINER_PLACEHOLDER).join(containerName)
+    .split(SERVICE_PLACEHOLDER).join(serviceName));
 }
 
 /**
@@ -188,9 +207,7 @@ function normalizeRunnerBlock({ lines, containerName, serviceName }) {
  * @returns {string[]} the block's lines, markers included
  */
 function renderRunnerBlock({ reference, composeText, containerName, serviceName }) {
-  let rendered = reference.map((line) => line
-    .split(CONTAINER_PLACEHOLDER).join(containerName)
-    .split(SERVICE_PLACEHOLDER).join(serviceName));
+  let rendered = renderRunnerIdentity({ lines: reference, containerName, serviceName });
 
   const service = serviceLines(composeText, containerName);
 
@@ -217,6 +234,6 @@ module.exports = {
   serviceLines,
   replaceServiceNode,
   stripDeclarations,
-  normalizeRunnerBlock,
+  renderRunnerIdentity,
   renderRunnerBlock
 };

package/src/manifest/checks/discoveryOrphan.js

@@ -18,6 +18,7 @@
  */
 
 const { discoverBearers, rootOfPattern } = require('../discovery');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 
 const check = Object.freeze({
   scope: 'workspace',
@@ -31,7 +32,7 @@ const check = Object.freeze({
   /** What the run prints instead of a verdict when the workspace is unreachable. */
   describeNotRun({ block }) {
     const owner = block && block.from ? block.from.path : 'the referenced SSOT';
-    return `the workspace root is not reachable, so ${owner} cannot be read`;
+    return `the workspace root is not reachable, so ${owner} cannot be read. ${describeWorkspaceFix(owner)}`;
   },
 
   /**

package/src/manifest/checks/docsLintBridge.js

@@ -54,7 +54,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const { whereOf } = require('./libraryContext');
-const { resolveWorkspacePath } = require('../workspaceRoot');
+const { resolveWorkspacePath, describeWorkspaceFix, AS_THE_REASON_NAMES } = require('../workspaceRoot');
 
 /** The documentation lint, by the path the manifest writes every api path in. */
 const LINT_SCRIPT = 'api/scripts/ci/lint-biz-docs.mjs';
@@ -210,6 +210,55 @@ const ERROR_SEVERITY = 'error';
  */
 const errorGraded = (findings) => findings.filter((finding) => finding.severity === ERROR_SEVERITY);
 
+/**
+ * The NOT RUN sentence of a row the linter could not decide — the rules it could
+ * not evaluate, the linter's own reason for the first of them, and the command
+ * that turns this checkout into one where the question has an answer.
+ *
+ * Three things, and each has exactly one owner. The rule ids and the reason are
+ * the LINTER'S: this module cites the tool, it does not restate it, which is the
+ * whole point of the bridge (docblock at the top of this file). The remedy is
+ * `workspaceRoot.js` § describeWorkspaceFix, shared with
+ * `runManifest.js` § describeMissingRoots — the other place a row goes NOT RUN
+ * because a sibling was not there. Until d.516 this end of it stopped at the
+ * linter's reason: measured 2026-09-15 over a `git archive HEAD` export placed
+ * beside no `api_biz`, the run printed
+ *
+ *   NOT RUN  D-PORT — F002:http-ports could not be decided — api_biz/*/docker-compose.yml
+ *            lives in a sibling checkout this run does not have, so the probe could not
+ *            be evaluated
+ *
+ * while `U-ORPHAN`, in the SAME run and about the SAME absent directory, named
+ * the command. True, and nothing the reader could act on
+ * (`.claude/rules/automation-gates.md` §1 requirement 4).
+ *
+ * What the fix asks the reader to carry is left as the phrase pointing back at
+ * the reason, rather than a root resolved here. The linter's skipped channel
+ * names the absent THING — a probe target, a scan root, a manifest — and it
+ * carries no structured root to read (`api/scripts/ci/lint-biz-docs.mjs`
+ * § markSkipped: `{ rule, reason }` and nothing else). Deriving one would mean
+ * parsing that sentence, which is the private dialect between row and tool this
+ * bridge exists to avoid; naming the siblings here instead would make this
+ * module a second owner of the lint's own probe configuration.
+ *
+ * Collapsed into one reason per row: a checkout without siblings makes a dozen
+ * bans undecidable at once, and twelve identical sentences say nothing the first
+ * one does not.
+ *
+ * @param {Array<{rule: string, reason: string}>} undecided at least one entry
+ * @returns {string}
+ */
+function describeUndecided(undecided) {
+  if (!Array.isArray(undecided) || undecided.length === 0) {
+    throw new Error('[DocsLintBridge] Undecided rules are required - describeUndecided() was given '
+      + `${JSON.stringify(undecided)}, and a row with nothing undecided is not NOT RUN. `
+      + 'Fix: call it only when the linter reported at least one rule it could not evaluate.');
+  }
+
+  return `${undecided.map((entry) => entry.rule).join(', ')} could not be decided — `
+    + `${undecided[0].reason}. ${describeWorkspaceFix(AS_THE_REASON_NAMES)}`;
+}
+
 /**
  * Which row owns a lint finding: the one whose citation is the most specific.
  *
@@ -250,7 +299,11 @@ function claimantOf(ruleId, rows) {
  * @returns {{findings: Array<object>, skipped: Array<object>}|{problem: string}}
  */
 function lintOnce({ lintScript, docsDir, treeConfig }) {
-  const key = [lintScript, docsDir, treeConfig].join('');
+  // `\0` as the escape, never the raw byte: written literally it makes the
+  // whole file binary to grep, diff and every reader that asks what changed
+  // (measured 2026-09-16 — `grep -n` answered "Binary file … matches" and
+  // printed nothing). The value is identical; the source stays readable.
+  const key = [lintScript, docsDir, treeConfig].join('\0');
   if (answers.has(key)) return answers.get(key);
 
   const answer = runLint({ lintScript, docsDir, treeConfig });
@@ -394,15 +447,31 @@ function askLint({ block, serviceRoot, workspaceRoot }) {
   return { answer };
 }
 
+/**
+ * The absence BOTH documentation rows answer, in one sentence.
+ *
+ * `describeMissingRoots` answers "the workspace is there and the root is not";
+ * this one answers "there is no workspace at all". Until d.516b it stopped at
+ * the absence — the defect `.claude/rules/automation-gates.md` §1 requirement 4
+ * names, one channel over from the one d.516 closed. Until d.523 the sentence
+ * was then written TWICE, once per row, byte for byte: two rails for one
+ * concern (`.claude/rules/change-discipline.md` § One rail per concern), and
+ * the shape in which the first of the two would one day be improved alone.
+ *
+ * @returns {string}
+ */
+function describeLintNotRun() {
+  return `the workspace root is not reachable, so ${LINT_SCRIPT} cannot be run. `
+    + describeWorkspaceFix(LINT_SCRIPT);
+}
+
 const docsLint = Object.freeze({
   scope: 'bearer',
   requires: Object.freeze(['rule']),
 
   requiresSiblings: () => [LINT_DIR],
 
-  describeNotRun() {
-    return `the workspace root is not reachable, so ${LINT_SCRIPT} cannot be run`;
-  },
+  describeNotRun: describeLintNotRun,
 
   /**
    * @param {{ row: object, block: object, serviceRoot: string, workspaceRoot: string }} params
@@ -446,20 +515,15 @@ const docsLint = Object.freeze({
     // is `answer.problem` above, and the absent tree config before it, both of
     // which stay findings with a fix somebody can carry out.
     //
-    // Collapsed into one reason per row: a checkout without siblings makes a
-    // dozen bans undecidable at once, and twelve identical sentences say nothing
-    // the first one does not.
+    // The sentence itself is `describeUndecided` above — shared with `D-LINT`,
+    // which reports the same absence about the rules no row claims.
     const undecided = answer.skipped
       .filter((entry) => citations.some((citation) => covers(citation, entry.rule)))
       .filter((entry) => claimantOf(entry.rule, rows) === row.id);
 
     if (undecided.length === 0) return found;
 
-    return {
-      findings: found,
-      notRun: `${undecided.map((entry) => entry.rule).join(', ')} could not be decided — `
-        + `${undecided[0].reason}`
-    };
+    return { findings: found, notRun: describeUndecided(undecided) };
   }
 });
 
@@ -497,9 +561,7 @@ const docsLintClean = Object.freeze({
 
   requiresSiblings: () => [LINT_DIR],
 
-  describeNotRun() {
-    return `the workspace root is not reachable, so ${LINT_SCRIPT} cannot be run`;
-  },
+  describeNotRun: describeLintNotRun,
 
   /**
    * @param {{ block: object, serviceRoot: string, workspaceRoot: string }} params
@@ -531,11 +593,7 @@ const docsLintClean = Object.freeze({
     const undecided = answer.skipped.filter((entry) => claimantOf(entry.rule, rows) === null);
     if (undecided.length === 0) return found;
 
-    return {
-      findings: found,
-      notRun: `${undecided.map((entry) => entry.rule).join(', ')} could not be decided — `
-        + `${undecided[0].reason}`
-    };
+    return { findings: found, notRun: describeUndecided(undecided) };
   }
 });
 

package/src/manifest/checks/gitTracked.js

@@ -165,8 +165,19 @@ const check = Object.freeze({
     if (listed === null) {
       return {
         findings: [],
+        // The remedy of this row is NOT the one every other NOT RUN of this
+        // package carries. `workspaceRoot.js` § describeWorkspaceFix names
+        // `--workspace`, which points at a tree of checkouts; no value of it
+        // turns an export into a checkout, and this row asks git, not the
+        // workspace. So the sentence is this row's own — one remedy, one owner,
+        // and neither borrowed from the other
+        // (`.claude/rules/change-discipline.md` § One rail per concern).
+        // Until d.518 it stopped at the absence, which is the dead end
+        // `.claude/rules/automation-gates.md` §1 requirement 4 forbids.
         notRun: 'this tree is not a git checkout (git ls-files could not answer), so what a clone '
-          + 'would receive cannot be read — a container and an exported tarball are in exactly this state'
+          + 'would receive cannot be read — a container and an exported tarball are in exactly this state. '
+          + 'Fix: run this row over a git checkout — a clone of the repository, never an export, a tarball '
+          + 'or a built image.'
       };
     }
 

package/src/manifest/checks/libraryPackage.js

@@ -17,6 +17,7 @@ const fs = require('fs');
 const path = require('path');
 
 const { resolveFromValue } = require('../discovery');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 const {
   readPackage, whereOf, appliesTo, allDeps, scopedDeps, nodeMajorOf
 } = require('./libraryContext');
@@ -91,7 +92,8 @@ const libraryEngines = Object.freeze({
   requires: Object.freeze(['from']),
 
   describeNotRun({ row }) {
-    return `the workspace root is not reachable, so ${row.from.path} cannot be read`;
+    return `the workspace root is not reachable, so ${row.from.path} cannot be read. `
+      + describeWorkspaceFix(row.from.path);
   },
 
   run({ row, block, serviceRoot, workspaceRoot }) {

package/src/manifest/checks/libraryWorkspace.js

@@ -28,7 +28,7 @@ const path = require('path');
 const {
   discoverBearers, resolveFromReference, resolveFromMap, expandPattern, rootOfPattern
 } = require('../discovery');
-const { resolveWorkspacePath } = require('../workspaceRoot');
+const { resolveWorkspacePath, describeWorkspaceFix, AS_THE_REASON_NAMES } = require('../workspaceRoot');
 const {
   readJson, readPackage, whereOf, declaredCategory, appliesTo, scopedDeps, SCOPE
 } = require('./libraryContext');
@@ -39,8 +39,23 @@ const RUNTIME_SECTIONS = Object.freeze(['dependencies']);
 /** The sections `scripts/ci/verify-manifest-pins.mjs` compares against the SSOT. */
 const PINNED_SECTIONS = Object.freeze(['dependencies', 'devDependencies']);
 
-/** Why a workspace-scoped row prints nothing instead of a verdict. */
-const notRunBecause = (what) => `the workspace root is not reachable, so ${what} cannot be read`;
+/**
+ * Why a workspace-scoped row prints nothing instead of a verdict — and, since
+ * d.518, what to run so that it can.
+ *
+ * Five rows of the library uniform are reported through this one line
+ * (`U-ORPHAN`, `U-MISMATCH`, `L-PINS`, `L-CONSUMER`, `L-TOOLING`), so the
+ * command belongs here rather than at each of them: one remedy, one sentence,
+ * one owner (`workspaceRoot.js` § describeWorkspaceFix,
+ * `.claude/rules/change-discipline.md` § One rail per concern). Until d.518 all
+ * five stopped at the absence — true, and nothing a reader of a CI log can act
+ * on (`.claude/rules/automation-gates.md` §1 requirement 4).
+ *
+ * WHAT the checkout has to carry is already named by `what`, immediately before
+ * the fix, so the fix points back at it instead of repeating it in other words.
+ */
+const notRunBecause = (what) => `the workspace root is not reachable, so ${what} cannot be read. `
+  + describeWorkspaceFix(AS_THE_REASON_NAMES);
 
 /**
  * Every package the uniform's discovery pattern finds, indexed by the name its

package/src/manifest/checks/readmeRegion.js

@@ -32,6 +32,7 @@ const {
   readReadme, serviceRegion, libraryRegion, PACKAGE_IN_WORKSPACE
 } = require('../../sync/readmeLocation');
 const { whereOf, declaredCategory, readPackage } = require('./libraryContext');
+const { describeWorkspaceFix, AS_THE_REASON_NAMES } = require('../workspaceRoot');
 
 /**
  * The first line at which the region on disk stops being the rendered one, and
@@ -102,8 +103,15 @@ const libraryReadmeRegion = Object.freeze({
   // holds a copy of this package.
   requiresSiblings: () => (PACKAGE_IN_WORKSPACE === null ? [] : [PACKAGE_IN_WORKSPACE]),
 
+  // The absence, and then the command that removes it, from the one owner of
+  // that command (`workspaceRoot.js` § describeWorkspaceFix). What the checkout
+  // must carry is named by the sentence in front of it, so the fix points back
+  // at it rather than saying it a second time in other words — which is what
+  // `AS_THE_REASON_NAMES` is for. Until d.518 this ended at the absence
+  // (`.claude/rules/automation-gates.md` §1 requirement 4).
   describeNotRun() {
-    return 'the workspace root is not reachable, so the manifest the region links at cannot be located';
+    return 'the workspace root is not reachable, so the manifest the region links at cannot be located. '
+      + describeWorkspaceFix(AS_THE_REASON_NAMES);
   },
 
   run({ row, serviceRoot, workspaceRoot }) {

package/src/manifest/checks/serviceConfig.js

@@ -25,9 +25,10 @@
 const fs = require('fs');
 const path = require('path');
 
-const { readReferencedFile, isPackageReference, referenceOwner } = require('../discovery');
+const { resolveFromDocument, isPackageReference, referenceOwner } = require('../discovery');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 const { whereOf } = require('./libraryContext');
-const { diffAgainst } = require('../../sync/sharedEnv');
+const { diffAgainst, renderSharedEnv } = require('../../sync/sharedEnv');
 const { loadAndValidateIntegrationContract } = require('../../utils/bizCiGateContract');
 
 /** The generated platform file every service carries a copy of. */
@@ -333,14 +334,29 @@ const envTemplates = Object.freeze({
 });
 
 /**
- * `shared.env` is rendered from `api/config/shared-env.json`, and this row reads
- * the RENDER the package carries (d.229): the platform manifest stays the owner
- * of the key set, `templates/business-service/config/env-templates/shared.env`
- * is its output, and `sharedEnvTemplate.test.js` is what keeps the two equal.
- * Reading the render rather than the manifest is what lets the row run inside a
- * service container, where `api/config/` is not there at all — and that is the
- * only place a service's own `shared.env` is ever wrong for a reader who cannot
- * fix it from the workspace.
+ * `shared.env` is generated, never written, and this row reads the file that
+ * OWNS the key set — `api/config/shared-env.json` in the workspace — through the
+ * same renderer `npx oa-sync-template shared-env` writes with (`src/sync/sharedEnv.js`).
+ *
+ * Until d.536 it read the render this package carries (d.229), so the verdict
+ * depended on the day the validator was published rather than on the SSOT: the
+ * three services synced after the 9.0.0 publish were told "10 line(s) differ" by
+ * a row whose own fix command had just written the file, because the SSOT had
+ * gained `LOG_MAX_SIZE_BYTES`, `LOG_MAX_FILES` and a comment since. One fact
+ * cannot be read off two files (`.claude/rules/change-discipline.md` § One rail
+ * per concern), and a gate whose answer moves with a publication date is not
+ * predictable (`.claude/rules/automation-gates.md` §1.1).
+ *
+ * The reason d.229 gave for the packaged copy — "a service container has no
+ * `api/config/`" — no longer buys anything the row needs: the deploy job the
+ * uniform runs in clones the api checkout (confirmation `biz-service-manifest`
+ * 008), and where the workspace really is out of reach the row says NOT RUN and
+ * names the command, which is what every other workspace-reading row does. A
+ * silent pass measured against yesterday's key set is the false guarantee
+ * `automation-gates.md` §5 calls a defect.
+ *
+ * `templates/business-service/config/env-templates/shared.env` stays as the
+ * scaffold's own output, and `sharedEnvTemplate.test.js` stays the gate on it.
  */
 const sharedEnvGenerated = Object.freeze({
   scope: 'bearer',
@@ -349,7 +365,8 @@ const sharedEnvGenerated = Object.freeze({
   needsWorkspace: ({ row }) => !isPackageReference(row.from),
 
   describeNotRun({ row }) {
-    return `the workspace root is not reachable, so ${referenceOwner(row.from)} cannot be read`;
+    const owner = referenceOwner(row.from);
+    return `the workspace root is not reachable, so ${owner} cannot be read. ${describeWorkspaceFix(owner)}`;
   },
 
   run({ row, serviceRoot, workspaceRoot }) {
@@ -360,7 +377,7 @@ const sharedEnvGenerated = Object.freeze({
       return [{ where, what: `absent — it is rendered from ${owner}` }];
     }
 
-    const rendered = readReferencedFile({ from: row.from, workspaceRoot });
+    const rendered = renderSharedEnv(resolveFromDocument({ from: row.from, workspaceRoot }));
     if (rendered === text) return [];
 
     const differing = diffAgainst(rendered, text).split('\n').filter((line) => /^[-+]/.test(line)).length - 2;