Skip to content

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

Merged
os-project-manager merged 1 commit into
mainfrom
claude/issue-13471-screaming-snake-anchor
Aug 31, 2026
Merged

docs-audit: let a SCREAMING_SNAKE literal mint an anchor, and pin the predicate pair#13782
os-project-manager merged 1 commit into
mainfrom
claude/issue-13471-screaming-snake-anchor

Conversation

@claude

@claude claude Bot commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Fixes #13471

isCodeShaped has called OS_MODE an identifier since the shape guard was written — it is
pinned as SCREAMING_SNAKE in the self-test's own 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. This makes the pair agree on that
shape, and then pins the agreement so neither side can drift back out of step quietly.

Re-derived against today's file first

The card warned its own shape description might be stale, and it was worth checking: the file
has drifted three times since the record window (blob 0a42496… to 61e0f44c… to
be1584869 today, the last move being #13738 at 09:40Z). The description survived — the
literal test was still exactly three lowercase-initial regexes. Both predicates, run on the
same tokens, on today's implementation:

OS_CLOUD_URL           isCodeShaped=true  literalAnchorsFromLines=false  DISAGREE
OS_MODE                isCodeShaped=true  literalAnchorsFromLines=false  DISAGREE
OS_TENANCY_POSTURE     isCodeShaped=true  literalAnchorsFromLines=false  DISAGREE
ERROR_CODE_LEDGER      isCodeShaped=true  literalAnchorsFromLines=false  DISAGREE
controlled_by_parent   isCodeShaped=true  literalAnchorsFromLines=true   agree
auditMetaItem          isCodeShaped=true  literalAnchorsFromLines=true   agree
meta.getAudit          isCodeShaped=true  literalAnchorsFromLines=true   agree
label                  isCodeShaped=false literalAnchorsFromLines=false  agree

Measured before changing anything

Two arms of the real tool over the 60 most recent packages/** commits, with every added row
attributed to the declaration that minted it — the per-row provenance published by #13738 is
what turned "will widening get noisier?" from a judgement call into a count.

baseline accepting SCREAMING_SNAKE
rows across 60 runs 374 383 (+9, +2.4%)
rows lost 0
overbroadAnchors (hub terms the corpus-share guard caught) 8 8 (+0)
runs that moved at all 2 of 60

Every new anchor named its declaration: FlowRefusalCode, AUTHZ_STORE_UNAVAILABLE_CODE,
codes. Four of the nine were vendor MySQL driver codes (ER_DUP_KEYNAME and friends) which
matched no page at all, so they cost nothing — an anchor no doc names is not a row.

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 structural alternative was measured too, and rejected

Collapsing the literal test into isCodeShaped looks like the tidier fix — one predicate
instead of two — and the same 60 commits say no: rows 374 to 408 (+9.1%), and it admits
'unchanged.', 'means.' and 'version.', quoted sentence fragments that reach
isCodeShaped's . arm. The two predicates run over different populations — a
declaration NAME versus an arbitrary quoted span that may be prose — so they must stay
separate. Those three fragments are now pinned as non-anchors, so a future collapse goes red
with the reason attached.

Blast radius, kept as small as the card measured it

⛔ The card's own pull commit 4d98d9eab gains zero rows from this. That page was already
listed there, through the route anchor /api/v1/runtime/config; all this adds is a second
via clause naming OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED. The recall win is real and
it is b6d3d76b5-shaped, not 4d98d9eab-shaped. The three sibling misses in #13306's record
window remain out of scope and unfixed by this — those env vars were new to the page, so no
anchor of any shape could have matched.

Also unchanged, deliberately: a bare all-caps word such as EEXIT is not admitted, because the
shape requires a segment break. Prose does not shout in underscores; it can shout in one word.

Verification

  • --self-test 503 to 516 cases, all pass (exit 0, captured before any pipe).
  • The shipped file reproduces the measured arm on 60 of 60 runs, so the numbers above
    describe this diff rather than a throwaway mutant.
  • Reverse-verified: removing the fourth shape takes --self-test to exit 1, 7 cases
    failing
    , the agreement pin among them. Restore proven by observed state — working blob
    f1315ee83874ece9fdaba707005ff79f295ff020 equal to HEAD's, empty git diff HEAD, empty
    git status. No rebuild is involved: this script is dependency-free and node runs the source
    directly, so there is no dist/ between the edit and the run.
  • Gate families derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
    after the final commit (4a26def1c): 18 GREEN, 0 RED, 1 NOT MEASURED —
    check-test-completeness.mjs exits 3 PREREQUISITE NOT MET because it grades a saved
    turbo run test log that only CI produces, which its own failure text says to record as NOT
    MEASURED rather than as a red. Both convention-triggered obligations for a gate-script edit
    (bare-root-worklist.mjs --self-test, check:pm-dispatch-gates) are in that green set, as are
    check:docs-audit-scope, check-affected-docs.mjs, check-drift-comment.mjs and
    check:nul-bytes.

skip-changeset: the diff is one repo-root dev script. The root manifest is private: true and
no package manifest covers scripts/, so nothing is published. Check Changeset has no
path-based exemption — it enforces on any diff unless labelled — so the label is applied rather
than assumed.


Generated by Claude Code

… predicate pair

`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.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC
@claude claude Bot added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Aug 31, 2026
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see
  • a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4301f78461c7733850ee0dc75aab39a9ee782f77packageMentionDocs.

@os-project-manager
os-project-manager marked this pull request as ready for review August 31, 2026 12:08
@os-project-manager
os-project-manager added this pull request to the merge queue Aug 31, 2026
Merged via the queue into main with commit e5461ba Aug 31, 2026
35 checks passed
@os-project-manager
os-project-manager deleted the claude/issue-13471-screaming-snake-anchor branch August 31, 2026 12:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/m skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

2 participants