docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair (#13782)

`isCodeShaped` has called `OS_MODE` an identifier since the shape guard was written
(it is pinned as `SCREAMING_SNAKE` in the self-test's shape cases), while
`literalAnchorsFromLines` accepted only three lowercase-initial shapes and so declined
to mint any anchor from it. One predicate in the pair called the token an identifier,
the other silently called it prose, and nothing reported the split.

Measured both ways over the 60 most recent `packages/**` commits, attributing every
added row to the declaration that minted it (the provenance published by #13738):
rows 374 -> 383 (+2.4%), zero rows lost, `overbroadAnchors` unchanged at 8, and only
2 of 60 runs moved. On `b6d3d76b5` the advisory went from 0 to 2 of the 3 docs pages
that commit edited itself.

Also pins the agreement as an invariant, and pins the disagreements that remain as
deliberate: delegating the literal test to `isCodeShaped` was measured at +9.1% and
admits quoted sentence fragments.


Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

scripts/docs-audit/affected-docs.mjs

@@ -1238,6 +1238,64 @@ function noteFrom(map, token, clause) {
   set.add(clause);
 }
 
+/**
+ * Is this quoted span identifier-shaped enough to mint a `literal` anchor?
+ *
+ * FOUR SHAPES. Three of them say "an identifier starts lowercase" — snake_case,
+ * camelCase, a dotted client path. A quoted English word (`'ignore'`, `'utf8'`) is not a
+ * surface anyone documents by that spelling, and those three keep it out.
+ *
+ * THE FOURTH IS SCREAMING_SNAKE, AND IT IS HERE TO END A DISAGREEMENT (#13471). While the
+ * three lowercase-initial shapes were the whole rule, this predicate and `isCodeShaped`
+ * contradicted each other on every constant name: `isCodeShaped('OS_MODE')` is `true` —
+ * pinned as `SCREAMING_SNAKE` in the shape cases below since the guard was written — while
+ * this test declined to mint an anchor from it at all. One predicate in the pair called the
+ * token an identifier, the other silently called it prose, and nothing reported the split.
+ * A page that names env vars and essentially nothing else (`deployment/environment-variables.mdx`)
+ * has no other `literal` route onto an advisory.
+ *
+ * The fourth shape is earned by the same argument that earns `PHRASE_ANCHOR_KINDS` its
+ * exemption — DISTINCTIVE BY CONSTRUCTION, not by inspection. `OS_TENANCY_POSTURE` cannot
+ * be the English word this guard exists to drop: prose does not shout in underscores. Note
+ * the shape is MULTI-SEGMENT by construction (the `_` is required), so a bare all-caps word
+ * is not admitted by it — see the deliberate-disagreement pins in `--self-test`.
+ *
+ * MEASURED BOTH WAYS before widening, over the 60 most recent `packages/**` commits, using
+ * the per-row provenance #12824 published so each added row could be attributed to the
+ * declaration that minted it rather than counted in a lump:
+ *   - rows 374 -> 383 (+9, +2.4%), and ZERO rows lost;
+ *   - `overbroadAnchors` 8 -> 8: the corpus-share guard caught no new hub term, so the
+ *     widening minted no term broad enough to need catching;
+ *   - only 2 of the 60 runs moved at all. Every new anchor named its declaration:
+ *     `FlowRefusalCode`, `AUTHZ_STORE_UNAVAILABLE_CODE`, `codes`.
+ *   - GROUND TRUTH on `b6d3d76b5`, whose own commit edited three docs pages: the advisory
+ *     went from 0 of those 3 (it listed two `releases/**` pages and nothing else) to 2 of 3
+ *     — `api/client-sdk.mdx` and `automation/flows.mdx`, both minted from `FlowRefusalCode`.
+ *   - the four vendor codes in that window (`ER_DUP_KEYNAME` and friends, from a MySQL
+ *     driver table) minted anchors and matched NO page, so they cost nothing: an anchor
+ *     no doc names is not a row.
+ *
+ * BLAST RADIUS, KEPT HONEST. `4d98d9eab` is the commit this was found on, and the widening
+ * adds ZERO rows there: `environment-variables.mdx` was already listed through the `route`
+ * anchor `/api/v1/runtime/config`, so all the fourth shape adds is a second `via` clause
+ * saying `OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED` also pointed at it. The recall win is
+ * real and it is `b6d3d76b5`-shaped, not `4d98d9eab`-shaped.
+ *
+ * DO NOT COLLAPSE THIS INTO `isCodeShaped`. It looks like the same question and it is not,
+ * because the two run over DIFFERENT POPULATIONS: `isCodeShaped` judges a token already
+ * known to be a declaration NAME, while this one judges an arbitrary quoted span, which may
+ * be prose someone quoted. Measured on the same 60 commits, delegating this test to
+ * `isCodeShaped` gives rows 374 -> 408 (+9.1%, versus +2.4%) and admits `'unchanged.'`,
+ * `'means.'` and `'version.'` — sentence fragments that reach `isCodeShaped`'s `.` arm.
+ * Those three are pinned as non-anchors in `--self-test` so the collapse goes red.
+ */
+function isLiteralAnchorShape(lit) {
+  return /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit)          // snake_case
+    || /^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit)             // camelCase
+    || /^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)   // a dotted client path
+    || /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(lit);           // SCREAMING_SNAKE (#13471)
+}
+
 /** Route tails and identifier-shaped string literals appearing on the changed lines. */
 function literalAnchorsFromLines(lines, changed) {
   const routes = new Set();
@@ -1266,9 +1324,7 @@ function literalAnchorsFromLines(lines, changed) {
     for (const m of line.matchAll(/['"]([A-Za-z][\w.$-]{3,63})['"]/g)) {
       const lit = m[1];
       if (GENERIC_ANCHOR_NAMES.has(lit.toLowerCase())) continue;
-      // Identifier-shaped only: snake_case, camelCase or dotted. A quoted English word
-      // ('ignore', 'utf8') is not a surface anyone documents by that spelling.
-      if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/.test(lit) && !/^[a-z]+(?:[A-Z][A-Za-z0-9]*)+$/.test(lit) && !/^[a-z][a-z0-9]*(?:\.[a-z][A-Za-z0-9]*)+$/.test(lit)) continue;
+      if (!isLiteralAnchorShape(lit)) continue;
       literals.add(lit);
       const where = enclosingName();
       noteFrom(from, lit, where ? `a string literal in ${where}` : 'a string literal on a changed line');
@@ -4348,15 +4404,50 @@ function selfTest() {
   check('PHRASE_ANCHOR_KINDS', 'a rule expression is distinctive by construction', 'rule', true, PHRASE_ANCHOR_KINDS.has('rule'));
 
   // String literals on a changed line: an identifier-shaped one is surface, English is not.
-  const litLines = ["  if (rule === 'controlled_by_parent') return maskFieldValue(v);", "  fs.readFileSync(p, 'utf8');", "  logger.warn('ignore');"];
-  const lits = literalAnchorsFromLines(litLines, [1, 2, 3]).literals;
+  const litLines = ["  if (rule === 'controlled_by_parent') return maskFieldValue(v);", "  fs.readFileSync(p, 'utf8');", "  logger.warn('ignore');",
+    "  const ENV = 'OS_TENANCY_POSTURE';", "  if (c === 'FLOW_NO_START_NODE') return refuse(c);",
+    "  // the shape is 'unchanged.' in that arm", "  throw new Error('EEXIT');"];
+  const lits = literalAnchorsFromLines(litLines, [1, 2, 3, 4, 5, 6, 7]).literals;
   const literalCases = [
     ['controlled_by_parent', true, 'a snake_case literal IS an authoring surface'],
     ['utf8', false, 'an encoding name is not surface'],
     ['ignore', false, 'an English word is not surface'],
+    // #13471. The env-var name is the case the whole card was filed on: a page that names
+    // env vars and essentially nothing else has no other `literal` route onto an advisory.
+    ['OS_TENANCY_POSTURE', true, 'a SCREAMING_SNAKE env-var name IS an authoring surface'],
+    ['FLOW_NO_START_NODE', true, 'and so is a refusal code — the measured recall win'],
+    // ⛔ The guard rail on the widening, both halves measured on the same 60 commits.
+    ['unchanged.', false, 'a quoted sentence fragment is still not surface'],
+    ['EEXIT', false, 'a bare all-caps word is not SCREAMING_SNAKE — the shape needs a segment break'],
   ];
   for (const [lit, want, label] of literalCases) check('literalAnchorsFromLines', label, lit, want, lits.has(lit));
 
+  // ── THE PAIR MUST AGREE ON SCREAMING_SNAKE (#13471) ──
+  // The defect this closed was not "recall too low", it was TWO PREDICATES CONTRADICTING
+  // each other with nothing reporting the split: `isCodeShaped` called `OS_MODE` an
+  // identifier (pinned in `shapeCases` above) while `literalAnchorsFromLines` declined to
+  // mint any anchor from it. Pin the agreement itself, so neither side can drift back out
+  // of step silently — a check on one predicate alone could not have caught this.
+  for (const t of ['OS_CLOUD_URL', 'OS_MODE', 'OS_TENANCY_POSTURE', 'ERROR_CODE_LEDGER', 'FLOW_INPUT_SCHEMA_INVALID']) {
+    check('isCodeShaped/isLiteralAnchorShape', 'the pair agrees on a SCREAMING_SNAKE token', t,
+      true, isCodeShaped(t) === isLiteralAnchorShape(t) && isLiteralAnchorShape(t));
+  }
+
+  // ⛔ AND THE DISAGREEMENTS THAT REMAIN ARE DELIBERATE, so the next reader does not
+  // "finish the job" by collapsing this test into `isCodeShaped`. The two run over
+  // DIFFERENT POPULATIONS — a declaration NAME versus an arbitrary quoted span that may be
+  // prose — and delegating measured rows 374 -> 408 (+9.1%, versus +2.4% for the shape
+  // above) on the same 60 commits. These three fragments are what it admits.
+  const deliberateSplits = [
+    ['unchanged.', 'a sentence fragment reaches isCodeShaped through its `.` arm'],
+    ['means.', 'ditto — measured, not hypothetical'],
+    ['version.', 'ditto'],
+    ['IHttpRequest', 'a PascalCase name is already reachable through the `symbol` kind'],
+  ];
+  for (const [t, label] of deliberateSplits) {
+    check('isCodeShaped/isLiteralAnchorShape', label, t, true, isCodeShaped(t) && !isLiteralAnchorShape(t));
+  }
+
   // ── `computedOn` (#9519): the record that names WHICH TREE the answer is about ──
   // Pinned on the pure shaper, so these stay hermetic; the probing wrapper reads real
   // git state by construction. Two properties carry the field's whole value: a merge