docs(deployment): reconcile the gate section with the four doors, the real rule count and the retired alias rule (#7465)

[os-help]

Fixes #7465

Three drifts between content/docs/deployment/validating-metadata.mdx and content/docs/deployment/cli.mdx, fixed in one commit — because the first of them provably cannot be fixed in one file.

1. The heading — a three-site coordinated edit

validating-metadata.mdx:349 read ## The one gate, three entry points. Since #4463 P1 the matrix below it has four columns: os validate, os build, os lint, and the runtime publish gate that #7458 documented three hours ago.

Chosen wording: ## The one gate, four doors — not "four entry points". The section's own prose rules that out: it introduces the fourth as "There is a fourth door, and it is not a command", and the sentence directly under the heading enumerates the three commands. "Entry point" in the original meant a CLI invocation, so stretching it over a saveMetaItem write path would make the heading false in the same way the old one was. "Door" is the noun the section already uses for the superset (it appears four times in the section), and it matches the four table columns. The later "for someone authoring in Studio that door is not one of four — it is the only one" is a perspective note about one author's reachable surface, not a competing count, so it stays untouched and still reads correctly under the new heading.

Three sites moved together — heading, anchor fragment, link text:

site	before	after
validating-metadata.mdx:349	## The one gate, three entry points	## The one gate, four doors
cli.mdx:458 (fragment)	#the-one-gate-three-entry-points	#the-one-gate-four-doors
cli.mdx:458 (link text)	The one gate, three entry points	The one gate, four doors

Repo-wide grep for the-one-gate-three-entry-points and one gate, three entry found exactly these two files — both inside the ruled file surface, nothing to widen to. (The three packages/spec hits for the bare phrase "three entry points" are about npm package exports and are unrelated.)

Anchor verified mechanically with this repo's own github-slugger@2.0.0: slug("The one gate, four doors") → the-one-gate-four-doors, which is the fragment cli.mdx now links.

2. The transcript count — measured, not quoted

validating-metadata.mdx:482 read → Running author-time rules (26)....

That line is printed by packages/cli/src/commands/validate.ts:117 as `Running author-time rules (${registered.length})...` where registered = authoringRulesFor('validate') — i.e. AUTHORING_RULES filtered to entries whose commands include validate, not the raw table length. Executed against the live registry:

AUTHORING_RULES.length            = 38
authoringRulesFor('validate')     = 38   ← what this transcript prints
authoringRulesFor('build')        = 38
authoringRulesFor('lint')         = 35

The transcript is a ◆ Validate run, so 38 is the number that command would actually print. The two counts happen to coincide here because every entry currently runs on validate; they are not the same quantity, and an os lint transcript would have to say 35.

Deliberately not changed: validating-metadata.mdx:466, "the last audit (#4409) found 23 of 26 rules running on some strict subset of the three" — that is a statement about a past audit, not a live count.

3. The retired rule

cli.mdx:473 listed deprecated visibility aliases among the advisories os lint reports. visibility-alias-deprecated was retired by #6318, and every surviving mention in the tree is commentary about the retirement (validate-visibility-predicates.ts:14,631, authoring-rules.ts:242,796), a test pinning it retired (authoring-rule-input-tier.test.ts:218, validate-visibility-predicates.test.ts:43), a CHANGELOG entry, or the changeset — no live rule. The item is dropped; the rest of the advisory list is unchanged.

This was the only one of the three in the user-facing declared ≠ enforced direction: the docs promised a lint output that can never appear.

Verification

gate	invocation	result
doc authoring	pnpm check:doc-authoring	✅ 374 files clean
doc formula expressions	pnpm --filter @objectstack/lint run check:doc-formula-expressions	✅ 24 self-test cases; 22 + 9 examples clean
NUL bytes	node scripts/check-nul-bytes.mjs	✅ 6981 files, none
ADR cross-links	node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs	✅ 524 destinations resolve
Check Documentation Links (lychee)	lychee 0.24.2 — the exact version and argv from .github/workflows/check-links.yml	✅ 1756 total / 775 unique / 0 errors

⚠️ The link gate does not check anchors, so it could not have caught a half-done rename. lychee.toml sets include_fragments = "none", and I falsified the assumption directly rather than trusting the comment: a probe file linking /docs/deployment/validating-metadata#this-anchor-does-not-exist-at-all is reported [200] ✅ OK by the pinned lychee under the CI argv. It resolves the file target only. The anchor half of this rename is therefore verified by the github-slugger computation above and by the grep showing no residual references — not by any CI gate.

Notes

• Docs-only ⇒ no changeset (skip-changeset is the PM's to apply).
• Independence checked (not assumed): the three drifts do not interact. No neighbouring sentence becomes false under the new heading — every other "three" in both files is the three commands / all three, which is still correct, and the historical "23 of 26" is left as-is.
• Out-of-surface drift found, deliberately not touched: the stale count also survives in two code comments — packages/objectql/src/plugin.ts:76 ("the 26 shared AUTHORING_RULES") and packages/metadata-protocol/src/protocol.ts:2542 ("all 26 shared AUTHORING_RULES"). Both are outside this card's ruled file surface and outside its docs-only shape; recording here so they stay discoverable rather than widening this PR.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 7:40pm

[os-help]

CI: one red, and it is not mine to fix.

Check Changeset ❌ — job 93575426384. The gate's own message names the resolution:

This PR adds no changeset. If it releases nothing […] apply the skip-changeset label; otherwise run pnpm changeset and name the packages.

This PR releases nothing — it changes two .mdx files under content/docs/ and no package — so the label is the correct route, not a changeset. Dispatch ruling 2 for #7465 reserves that label for the PM seat (#6018) at accept time and forbids this seat from applying it or writing a changeset, so I am deliberately not clearing this check. It goes green the moment skip-changeset lands; nothing in the diff needs to change.

⛔ Not taking the third route: an empty-frontmatter changeset is rejected by the step below (#5471) and is the #4898 silent-release-stall failure mode.

Everything else on bd5d66a:

check	result
Check Documentation Links	✅ success — matches the local lychee 0.24.2 run (1756 links, 0 errors)
Check PR Size · Auto Label · filter	✅
Spec property liveness · Console Pin Freshness	✅
ADR maintainer approval	✅
No other open PR may claim the same issue	✅
Test Core · Dogfood Regression Gate	✅ (matrix legs skipped by the docs-only path filter)
Build Docs · TypeScript Type Check · ESLint	⏳ in progress at time of writing
Check Changeset	❌ — the above

⚠️ Worth flagging for whoever reviews: Check Documentation Links being green says nothing about the anchor this PR renamed. lychee.toml sets include_fragments = "none", so lychee resolves the file target and ignores the #fragment. I verified that by probe rather than by reading the config comment — a link to …/validating-metadata#this-anchor-does-not-exist-at-all is reported [200] ✅ OK under the exact CI argv. The heading/anchor/link-text rename in this PR is verified instead by computing the slug with this repo's own github-slugger@2.0.0 (slug("The one gate, four doors") → the-one-gate-four-doors) and by a repo-wide grep showing zero residual references to the old anchor or phrase. Details in the PR body.

Per dispatch ruling 3 this seat does not poll; the PM owns CI convergence, the ready-flip and landing. I remain subscribed and will act on any further event.

---

Generated by Claude Code