Skip to content

docs(audits): the 2026-06 react-tier dogfood audit is stale in three ways — wrong path, withdrawn blocks, and CLI banners that no longer exist #10284

Description

@os-elon

Found while porting the react-tier authoring guide onto the docs site (#10210). The
audit at docs/audits/2026-06-react-tier-authoring-dogfood.md is cited as the
trustworthy record of "what an author actually sees" — it was the PM's suggested source
for #10210 — and three of its load-bearing claims no longer hold. All three were
measured against origin/main at 502dc6fe7, not recalled.

Filing rather than fixing: docs/audits/** is outside #10210's file surface.

1. The example page's path moved

The audit says (twice):

examples/app-showcase/src/pages/renewals-pipeline.page.ts was written straight from
that contract

That path does not exist. The file is at
examples/app-showcase/src/ui/pages/renewals-pipeline.page.ts.

$ ls examples/app-showcase/src/pages/renewals-pipeline.page.ts
ls: cannot access ...: No such file or directory
$ find . -name '*renewals*' -not -path './node_modules/*'
./examples/app-showcase/src/ui/pages/renewals-pipeline.page.ts

2. It still describes the page as using blocks that were withdrawn from the tier

The audit's step 1 lists the contract as including RecordHighlights,
RecordRelatedList and RecordPath, and its step 2 describes the renewals page as
"selecting one drives RecordHighlights + ObjectChart + RecordRelatedList".

The whole record:* family was withdrawn from the react tier (see
REACT_RECORD_BLOCK_ALTERNATIVES and the ledger above it in
packages/spec/src/ui/react-blocks.ts), and os validate now rejects those blocks on a
react page with react-block-needs-record-context. The renewals page's own docstring
records the change:

This panel used to be RecordHighlights + RecordRelatedList, and both rendered
EMPTY here: every record:* block takes its record from the context a record page
mounts, and a react page mounts none.

So the audit describes an authoring shape the gate it is auditing now refuses.

3. The quoted CLI output does not exist anywhere in the CLI

The audit quotes:

→ Checking React-source page props (ADR-0081)...
✓ Validation passed (98ms)
✗ React-source page prop check failed (1 issue)

Neither banner string is in the tree — the only hits for React-source page are inside
the audit itself:

$ grep -rn "React-source page prop" --exclude-dir=node_modules --exclude-dir=.git .
./docs/audits/2026-06-react-tier-authoring-dogfood.md:39:...

validateReactPageProps is no longer a hand-wired os validate step with its own
banner — it joined the shared reference-integrity suite
(packages/lint/src/reference-integrity-suite.ts), which runs inside the author-time
rule registry, so os validate, os lint and os build all reach it. The real output,
captured from the built CLI against examples/app-showcase:

 → Running author-time rules (41)...
✗ Author-time rules failed (1 issue)
• page "showcase_renewals_pipeline" › ObjectChart: ObjectChart is missing the required prop "objectName".
Pass objectName={…}. See the react-tier component contract.
rule: react-prop-missing-required at pages[27].source

The pages[29] index in the audit is now pages[27], which is expected drift and not
itself worth pinning — the banner text is the part that misleads.

Why it matters

The audit's status is "the trustworthy record of the real authoring loop". Three
separate consumers reached for it in one dispatch round. A stale path costs a reader a
find; the withdrawn-blocks description and the phantom banner cost more, because both
read as current CLI behaviour and a doc author quoting them publishes output no
version of the product has ever printed.

Suggested shape

Either re-run the loop and refresh the audit against current behaviour, or add a dated
"superseded on these points" header the way ADR-0080 carries its 2026-06-30 amendment.
The conclusion (contract → author → gate composes into a working loop) still holds; only
the evidence has rotted.

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions