fix(cli): os validate runs the per-package author-time rule pass os build already ran

[os-support-ai]

Fixes #18677

Clause-②: no — no key is added to any published payload, and no newly-refused input could be exhibited (measurement below). Verified through readClause2Line from scripts/pm/check-clause2-carriers.mjs, ⛔ not an ad-hoc regex.

os build runs the artifact's authoring rules twice: once over the union-folded stack, then a second runAuthoringRules('build', …) pass over each artifactPackages(…) entry with packageBodyAsStack(…) as resolution context, de-duplicated against the union run. os validate ran the union pass and stopped — importing neither seam. By compile.ts' own description the survivors of that second pass are "exactly the set the union could not see", so that whole set was findings os build reported and os validate structurally could not. False-clean, on the worse door: the fast pre-flight is what an author runs before shipping.

The measurement

examples/app-multi-package — the repo's only two-package fixture — at origin/main 09e16a5, both commands exiting 0:

	os build --json	os validate --json
before	warnings 4 (3 union + 1 per-package survivor)	warnings 3
after	warnings 4	warnings 4 — same set, same order

os build's own output is unchanged: text face byte-identical modulo timings and artifact size, --json payload identical.

Red/green, both legs, from the committed state. With validate.ts alone restored to its pre-change blob (pinned commit 09e16a574, ⛔ never a moving ref) and artifact-packages.ts left carrying the shared pass, so the reverted change is exactly the one the card is about:

runPerPackageAuthoringRules occurrences: committed=3  mutated=0
mutated blob bafa54b07f… != HEAD blob 340cec6253…        == proof the mutation reached disk

unit  seam   1 failed | 5 passed  -> "both `os build` and `os validate` CALL the shared pass"
integ parity 1 failed | 3 passed  -> "these per-package findings ride `os build` and `os validate`
                                      cannot see them — the #18677 false-clean set:
                                      expected [ Array(1) ] to deeply equal []
                                      + "package 'com.example.ppparity.core' — object \"pp_account\" · field \"industry\""

Restored with git checkout HEAD -- … (⛔ not a bare git checkout --, which reads the poisoned index); git diff HEAD empty and the blob hash back to 340cec6253…. After: 28 passed in the unit run (the two pins + vitest-tiers-partition) and 4 passed in the integration run.

The card's declared-unmeasured limb, answered

"Does any authoring rule fire ONLY under packageBodyAsStack resolution today?" — measured against the registry, ⛔ not guessed from rule names, with the instrument's positive control lit:

reading	result
per-package survivors on examples/app-multi-package	1
of those, genuinely new (a finding the union could not see)	0
of those, ECHOES (same rule + same message as a union finding, differing only in positional path)	1
⭐ positive control — the same instrument on a stack with a top-level-only consumer	1 genuinely new ⇒ the zero is measured, not a blind instrument
per-package findings at error severity, any fixture tried	0

⇒ a measured "none today" for the gating tier, and the mechanism is packageBodyAsStack's own design, not luck: it hands each package the artifact's whole packages[] as resolution context, and the reference-integrity suite resolves object names through it (artifactProvidedObjectNames, packages/lint/src/validate-object-references.ts). Two constructed attempts at a per-package-only error — a view on a sibling's object, an app whose own navigation names a sibling's object — resolved identically in both runs and produced nothing. defineStack refuses the first shape outright at definition time.

⛔ NOT MEASURED: whether any of the 30 gating rules is reachable per-package-only. Two candidate shapes were measured and both were negative; the remaining rules were not swept one by one.

Why this is not a second copy of the loop

runPerPackageAuthoringRules lives beside artifactPackages / packageBodyAsStack in utils/artifact-packages.ts, whose header already forbids a second copy of that shape by name. What would have drifted between two hand-written loops is not the package reading but the verdict — the de-duplication key, the severity split, the where prefix. The severity mapping is os build's, unchanged: a per-package error refuses, an advisory joins warnings.

Tiers — both pins gate the merge queue

• test/validate-per-package-authoring-seam.test.ts → UNIT (tierSignals = none). Source ratchet + the pass's door-independence, with a non-vacuity case.
• test/validate-per-package-authoring-parity.test.ts → INTEGRATION (childProcess, helperCliOrTsx). Deliberately carries no .e2e segment, so by the orthogonal nightly cut it stays QUEUE-tier — the combination vitest-tiers.ts names as deliberate. Both were confirmed present in testFilesOnDisk() with OS_TEST_TIERS unset, and test/vitest-tiers-partition.test.ts passes.

⚠️ test/build-json-advisory-parity.e2e.test.ts — whose standing assertion "nothing rides in build's warnings that validate does not also report" stayed green through this entire defect, its fixtures declaring no packages[] — is NIGHTLY tier by name, so the queue run skips it. Run explicitly under OS_TEST_TIERS=nightly: 8 passed, unaffected.

Acceptance notes — out of scope, noted, not fixed here

1. The de-duplication key is leaky, and the file's own sentence overstates what survives. findingKey includes the positional path, and a collection index inside one package's body is not the index the flattened top level gives the same item — so what survives is "the set the union could not see" plus every finding whose two coordinates differ. On examples/app-multi-package the single survivor is an echo of the union's own crm_account.industry finding at the package-local index. ⛔ Not fixed here: changing the key changes what os build reports, a different decision from making the two doors agree. To file. Dedupe words: findingKey positional path · per-package echo · de-duplication key collection index.
2. os build counts per-package advisories on its text face that it never prints. printAuthoringAdvisories(ruleAdvisories) runs before the per-package loop appends to that list, so the closing line reads ⚠ 4 author-time warning(s) — see above above a list of 3. Measured on examples/app-multi-package; --json carries all 4, so this is the text face only and is not os build --json also drops the capability-provider and package-docs warnings that os validate --json carries #11727. After this change os validate prints all 4 — the direction is now build-side. To file. Dedupe words: printAuthoringAdvisories before per-package loop · see above count mismatch · build text face advisory omitted.
3. os lint has the same structural gap and it is not fixed here. The card's table reads compile.ts vs validate.ts; measured, the asymmetry was 2 of 3 doors. lint.ts imports artifactPackages and packageBodyAsStack — but for its own intra-package duplicate-name advisory (os lint's naming/namespace-prefix reports a legitimate cross-package name reuse as an intra-package duplicate, contradicting the ADR-0048 §3.4 sentence in its own message #17821), not the shared table. Its runAuthoringRules('lint', …) is union-only, exactly as validate.ts' was. ⛔ A count is not a reading: opening the hits is what separates the two. Out of the dispatch fence, which named os validate. To file. Dedupe words: os lint per-package authoring pass · lint.ts union-only runAuthoringRules · third door #18677.

origin/main merged at 4c837a58aa; gates re-run on the merged tree.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 5 documentable anchor(s).

17 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 062f5cdd7116a56d687e87dec71d789ef5c593b6.

⛔ 3 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 49 pages)
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 24 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 062f5cdd7116a56d687e87dec71d789ef5c593b6 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 75b93a3124346c7df60764918003eea3fff9f911 — the merge of head e62c44e48bbde25eb01109e3f1383c44df880796 into base 062f5cdd7116a56d687e87dec71d789ef5c593b6, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 75b93a3124346c7df60764918003eea3fff9f911 && git checkout 75b93a3124346c7df60764918003eea3fff9f911
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 062f5cdd7116a56d687e87dec71d789ef5c593b6 e62c44e48bbde25eb01109e3f1383c44df880796 && git checkout -B drift-repro 062f5cdd7116a56d687e87dec71d789ef5c593b6 && git merge --no-ff e62c44e48bbde25eb01109e3f1383c44df880796

node scripts/docs-audit/affected-docs.mjs --json 062f5cdd7116a56d687e87dec71d789ef5c593b6

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 062f5cdd7116a56d687e87dec71d789ef5c593b6 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-support-ai]

Docs rider — NOT FALSIFIED, and the one page that states the invariant was RIGHT while the code was wrong · 2026-09-17T20:04Z

⚠️ The drift bot's own note says the main anchor is unusable as a work list: os validate (command, **49 pages**) was dropped as overbroad. So a page merely naming os validate was never the predicate here.

The predicate, stated BEFORE reading

A page is falsified by this diff only if it states one of:

• (a) os validate does NOT run the per-package authoring-rule pass, or that only os build does;
• (b) it enumerates what os validate runs as a CLOSED list that excludes that pass;
• (c) it asserts a difference between os validate and os build in which rules, or which stack tiers, they judge — in the direction this diff removes;
• (d) it reproduces os validate's step lines as a closed transcript that would now be missing → Running author-time rules per package (N)...;
• (e) it states a finding or warning COUNT for os validate on a multi-package project.

The population — the corpus, ⛔ not the bot's 17 rows

Re-derived on the tree the bot named (7f86ed685af3…, the merge of head 4c837a58aa into base 74327d3f054d), in a detached worktree, ⛔ not on my own worktree cut from an older main: 20 docs, of which 3 are release-owned. The predicate was then swept over the whole hand-written corpus — 181 pages under content/docs outside references/ and releases/, plus the release-owned three read separately — because a statement-shaped predicate must not inherit a symbol-shaped population.

The readings

predicate	pages matching	verdict
(a) / (b) / (c) — any statement about the per-package authoring pass, in either direction	0 corpus-wide	nothing to falsify
(d) — declared transcript=os-validate blocks	4 (deployment/cli.mdx, deployment/validating-metadata.mdx, getting-started/build-with-claude-code.mdx, ui/react-pages.mdx)	all single-package runs — the new step line is emitted only when packages[] is non-empty, so all four are byte-unchanged. node scripts/docs-audit/check-docs-transcript-drift.mjs → exit 0, "4 declared transcript value(s) across 404 page(s) … equal what the registry derives today"
(e) — a validate finding count on a multi-package project	0	—

⭐ The one page that carries the invariant states it CORRECTLY — the code was the falsified half

content/docs/deployment/validating-metadata.mdx:518, in "The one gate, four doors":

Some rows are deliberately not universal across the three commands, and each is
one-directional (none lets a stack through a gate another command enforces)

That sentence was false on origin/main and my diff makes it true: the per-package pass is precisely a gate os build enforces that os validate let a stack through. ⇒ the page needs no edit, and the direction is worth recording — the documentation held the invariant the implementation had drifted from, which is the opposite of the usual drift finding.

Release-owned pages — read, ⛔ not edited, nothing to route

content/docs/releases/{v12,v13,v14}.mdx. Only one carries a relevant sentence — v12.mdx:224, "Re-run os compile / os validate — the new … lints may flag pre-existing authoring mistakes" — which treats the two commands as interchangeable for authoring findings. This diff makes that more true, not less. v13 and v14 carry no statement the predicate reaches. ⇒ nothing falsified, so there is no docs-only PR and no issue to route.

Noted, ⛔ not done here

The per-package pass is undocumented for both doors: the "one gate, four doors" table enumerates rule FAMILIES (all of which run in both passes), never the two stack TIERS the pass adds. Documenting it is a real improvement, but it is an ADR-0130 D4 statement about os build as much as os validate, so writing it for one door only would restate the asymmetry this PR removes. Out of the dispatch fence; reported rather than ridden.

---

Generated by Claude Code