fix(lint): the react-prop-deprecated warning states its reason in words, not a tracker number

[objectstack-fleet]

Fixes #20597

Clause-②: no

The last stage of #20597, and the card's only author-shown site: the react-prop-deprecated finding message in packages/lint/src/validate-react-page-props.ts. It ended by citing #11284, which answers 404. Ruling C+D (5749154545) takes author-shown text in form D: the lesson in words, with no number to look up.

What changed

Three files, +15 / -2, against base f29c83db13.

• packages/lint/src/validate-react-page-props.ts:1198: the message's tail changes. The tag, prop and dep.replacedBy interpolations are byte-identical, and so are the rule id, the warning severity and the hint (dep.note). In placeholder spelling (TAG, PROP and REPLACED_BY stand for the three interpolations):
  • before: TAG prop "PROP" is the deprecated spelling of the metadata-tier "REPLACED_BY" and is removed after the deprecation window (#11284).
  • after: TAG prop "PROP" is the deprecated spelling of the metadata-tier "REPLACED_BY": the react tier converges on the metadata-tier vocabulary, so this spelling keeps working through the deprecation window and is removed after it.
• scripts/doc-authoring-prose-id.baseline.json: the #11284 pin for this file is removed (one line). The other pin for the same file (#5583) stays. The file was regenerated with the gate's own node scripts/check-doc-authoring.mjs --census-ledger, and its diff against the checked-in baseline is exactly that one line.
• .changeset/20597-react-prop-deprecated-message-words.md: one @objectstack/lint patch.

Where the words come from. #11284 answers 404, so its decision was read from the record that survives. The @objectstack/lint CHANGELOG entry for commit 5383fa6 records it (maintainer ruling 2026-08-23): the react tier converges on the metadata-tier spelling, deprecate-first. The deprecated spelling stays published and accepted for the whole deprecation window, every use warns, and removal comes after the window. The same deciding commit wrote this message line. The REACT_PROP_DEPRECATED docblock and the ReactInteractionProp.deprecated docblock in packages/spec/src/ui/react-blocks.ts still state the same contract. The new sentence says that decision and adds nothing else.

Verification record (head 6c463cec86)

Premise. GET /repos/objectstack-ai/objectstack/issues/11284 answers 404. The control issues/5583 answers 200.

The ratchet moves down by exactly this site.

• pnpm check:doc-authoring exits 0. Its sibling-package leg reads 809 pinned sites across 230 files, one fewer than the 810 it read at stage 1 and stage 2. The file count holds, because this file keeps its #5583 pin.
• Stale-arm control, working-tree only, restored after: the base baseline over the new message gives exit 1, STALE, listing exactly one pair, packages/lint/src/validate-react-page-props.ts #11284 (1 pinned, 0 measured). The restore was proven by blob equality with HEAD and an empty git diff HEAD.
• Growth-arm control, through scripts/ablation-replace.mjs: the old tail was put back over the new baseline (anchor x1 to x0, replacement x0 to x1). The mutated blob f5684f0774 equals the base blob. The gate exits 1 with validate-react-page-props.ts #11284 (0 pinned, 1 measured) at :1198. The tool proved the restore (blob equals HEAD 55de478256, git diff HEAD empty).
• No tracker number is added. The only number on a changed line is the removed #11284.

Pin sweep (whole repo, one round).

• git grep for deprecation window (#11284), removed after the deprecation window and deprecated spelling of the metadata-tier at the base finds only the source line itself, so the grep is not blind. At head the first two find nothing.
• REACT_PROP_DEPRECATED / react-prop-deprecated appear in the source, the barrel (index.ts), two release-owned CHANGELOGs, and validate-react-page-props.test.ts. The test asserts the rule id only: the pastDeprecation filter, and toEqual([]) at :116 and :204. No test, snapshot, doc or skill asserts the message text, so there is no pin to flip, and none was added. Wording is not pinned unless a consumer parses it, and none does. The sibling objectui checkout (at b120b66) has 0 hits for the rule id, the fragment and the number.

Build, tests, typecheck. All three ran under scripts/pm/os-verify-lock.sh (slot issue-20597-s3), which printed VERDICT command-exit 0.

• turbo run build --concurrency=2 --filter=./packages/* --filter=./packages/*/*: 71 successful of 71.
• pnpm --filter @objectstack/lint exec vitest run --maxWorkers=2: Test Files 115 passed (115), Tests 5379 passed (5379).
• pnpm --filter @objectstack/lint typecheck: exit 0, and check:test-typecheck OK.
• No consumer sweep is owed. No export, type or rule id moves. The only change is the text of one warning message, and nothing parses it.

Gates.

• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 62 commands. All 62 ran with exit 0, and --ran reconciles "62 derived, 62 run, 0 NOT-MEASURED, 0 UNRUN".
• The six build-reading gates ran after the build: check:docs-transcript-drift, check:dts-closure, check:dual-build-cjs-loads, check:lean-entry-closure, check:published-files and check:sourcemap-no-sources-content.
• check:doc-authoring and check:issue-citations are among the 62, and both exit 0 (check:issue-citations reads "no issue citations added against f29c83d").
• These roster families keep their roster in a directory this diff touches, so they ran too, all exit 0: check-changeset-fixed, check-published-list-mirrors (plus its --self-test), check-dts-references --self-test, check:authz-resolver, check:console-injection, check:engine-double-contract, check:error-code-casing, check:filter-alias-parity, check:i18n-stale-fill and check:published-readme-exports. The last one first exited 3 (prerequisite, before the build) and then 0 after the build.

Lint, as a proven narrowing. pnpm exec eslint --no-inline-config --format json packages/lint/src/validate-react-page-props.ts reports 1 file, 0 errors and 0 warnings. isPathIgnored is false through eslint's API, and the resolved config has no parserOptions.project or projectService. eslint.config.mjs:327 says type-aware linting is never enabled, so a string edit here cannot move any other file's verdict. The repo-wide pnpm lint is CI's to run.

Changeset. files[] ships dist. The new sentence is in dist/index.js, index.cjs, runtime.js and runtime.cjs, and the old deprecation window (#11284) is in none of them. The positive control Likely a typo of a contract prop. Fix it or remove it. is in all four. Hence patch.

Merge. A driver-free merge-tree of 6c463cec86 onto origin/main f1e921ab8e, run from a bare shared clone with no merge.* config, exits 0. The four commits main gained since the base touch none of the three paths.

No ablation of behaviour is owed, since no behaviour changes. The two gate-arm controls above are the one-time proof that this site is the gate's to see. No test file was left behind.

Acceptance notes

• The message is dormant today (noted, not filed). The built REACT_BLOCKS contract carries 0 props with deprecated (4 blocks, 37 interactions). The only deprecated spellings there ever were, ListView's objectName / viewType, now sit in REACT_RETIRED_OVERLAY_PROPS and report react-prop-retired. So react-prop-deprecated cannot fire until a new deprecation is declared. The mechanism is kept, and the new text states its contract. Carrier: none.
• Stale test comment (noted, not filed). The header comment of validate-react-page-props.test.ts (about :32–:36) still says every objectName ListView fixture "carries exactly one deprecation warning". The assertions at :116 and :204 say zero. The claim puts test comments out of this card's scope, so it is untouched. Carrier: none (承接者：无).
• The same file's other author-shown id (noted, not filed). :458 is the hint of the REACT_CHART_AGGREGATE_INVALID warning, and one sentence of it begins objectstack#5583 ruled that …. spec: ChartAggregateSchema 与 ChartGroupBySchema object 分支转 strictObject —— #5020 parse 接通后的收紧半边(#4001 后续批) #5583 is live (200), so it is not a dead citation and not on this card. It stays pinned in the prose-id baseline with the rest of the ledger's 809 adjudicated sites. Carrier: none.
• With this PR, all of dead tracker citations in the domain:spec packages (84 sites, 21 numbers, 23 files): the ruling C+D stage for this lane (from #20556) #20597's items are done: stage 1 (docs(lint): re-anchor the dead tracker citations in packages/lint/src to the commits that decided them #20612, 22 files), stage 2 (docs(lint): re-anchor the five dead tracker citations in authoring-rules.ts to the commits that decided them #20631, authoring-rules.ts) and this form-D string.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 4 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 f1e921ab8ebfe061baec70b6113dee12b6360b4f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ae7ef0e906bd74c4acd17d618d511739c2168921 — the merge of head 6c463cec86f9888920cc3341103add113c49b99c into base f1e921ab8ebfe061baec70b6113dee12b6360b4f, 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 ae7ef0e906bd74c4acd17d618d511739c2168921 && git checkout ae7ef0e906bd74c4acd17d618d511739c2168921
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin f1e921ab8ebfe061baec70b6113dee12b6360b4f 6c463cec86f9888920cc3341103add113c49b99c && git checkout -B drift-repro f1e921ab8ebfe061baec70b6113dee12b6360b4f && git merge --no-ff 6c463cec86f9888920cc3341103add113c49b99c

node scripts/docs-audit/affected-docs.mjs --json f1e921ab8ebfe061baec70b6113dee12b6360b4f

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6c463cec86f9888920cc3341103add113c49b99c
Local-runs: none

Read for this record: the card's body and all 11 comments (the stage-2 landing record 5889811174, the stage-3 claim 5889924912 and the stage-3 dev report 5890531733 among them), ruling C+D 5749154545, AGENTS.md's runtime-string rule and scripts/check-doc-authoring.mjs's ratchet, PR #20641's body, its one comment, its 3-file list and the net diff against main (merge base f29c83db13, the head's parent), the @objectstack/lint CHANGELOG entry 5383fa6, commit 5383fa670's own diff, and the head's check-runs, once. Nothing built, run or re-run.

① Derived judgments

Accept set: nothing moves — right. The diff changes one template literal's tail inside the REACT_PROP_DEPRECATED push at packages/lint/src/validate-react-page-props.ts:1198. The condition that reaches it (block.deprecated.get(u)), the rule id, the warning severity, where, path and hint: dep.note are untouched, and the prefix TAG prop "PROP" is the deprecated spelling of the metadata-tier "REPLACED_BY" (TAG, PROP and REPLACED_BY standing for the tag, u and dep.replacedBy interpolations, which are byte-identical) is the same on both sides. Only and is removed after the deprecation window (#11284). becomes : the react tier converges on the metadata-tier vocabulary, so this spelling keeps working through the deprecation window and is removed after it. Same findings, same shape, new words.

The words are true to the decision's surviving record — right. #11284 answers 404 (the dev's measurement, with #5583 as the 200 control; not re-probed here). The record that stands is the @objectstack/lint CHANGELOG entry 5383fa6 (maintainer ruling 2026-08-23: the react tier converges on the metadata-tier spelling, deprecate-first; the deprecated aliases stay published and accepted for the whole deprecation window, every use warns and never errors, removal comes after the window), and commit 5383fa670's own diff is where this exact message line was written, together with the REACT_PROP_DEPRECATED docblock and the ReactInteractionProp.deprecated docblock in packages/spec/src/ui/react-blocks.ts, both of which still state that contract at this head. The new sentence says that decision and adds nothing. The one clause the record later reversed (the ListView aliases went with no window, #14791) belongs to the retired path and its own rule and message; this message describes the deprecated mechanism, whose "removed after" clause the old text already carried. Form D as ruling C+D states it: the lesson in words, no number to look up. The gate's own id regex (INTERNAL_ID_SOURCE: a hash followed by 3 to 5 digits, not preceded by a hash or ampersand) matched 11284 in the old text and matches nothing in the new.

The prose-id ratchet moves in its allowed direction — right. The gate's header rules: growth (measured above pinned) reds; shrink (measured below pinned) reds as STALE with the remedy "regenerate the baseline in this same PR", and "shrink is the landing author's to take, growth is not". This diff is that remedy. scripts/doc-authoring-prose-id.baseline.json loses the one line "#11284": 1 under packages/lint/src/validate-react-page-props.ts, keeps "#5583": 1 there, and nothing else moves: 230 files on both sides, 621 (file, id) pairs before and 620 after, 948 pinned occurrences before and 947 after (the dev's 810 / 809 is the gate's own count of id-bearing string sites, one per string; not re-run here, and the JSON diff is exactly that one pair either way). The file parses as JSON at the head. Equality with the gate's ledger, read from the code: this leg counts ids in non-comment, non-test string literals under packages/ minus packages/spec; in the one file this diff touches, every hash-number at the head sits in a // or * comment except objectstack#5583 at :458, one string, so the measured entry is #5583: 1, equal to the head's baseline entry; no other file moved, and the 4 commits main gained since the base (f1e921ab8e, 04b202e5cb, 5363e2dc64, 4d04b6be30) touch neither this file nor the baseline nor the changeset (git log over the three paths is empty). The CI job that runs pnpm check:doc-authoring (Lint & Repo Gates, lint.yml:2145) is the authority for the measured equality and had not concluded at my read (③).

Pins: none — confirmed by grep. At the head, git grep for removed after the deprecation window and deprecation window (#11284) finds nothing; deprecated spelling of the metadata-tier finds only :1198. REACT_PROP_DEPRECATED / react-prop-deprecated appears in the source, the index.ts barrel, validate-react-page-props.test.ts (rule-id assertions only: the pastDeprecation filter at :37 and toEqual([]) at :116 and :204; every message assertion in that file is on another rule), two release-owned CHANGELOGs and this PR's changeset. No __snapshots__ under packages/lint; no content/docs or skills/ page names the rule. objectui at b120b66: 0 hits for the rule id, the fragment or the number; its one consumer of validateReactPageProps (apps/console/src/__tests__/sdui-workbench-preview-listview-binding-8510.test.tsx) reads react-prop-retired findings by rule id, and nothing in objectui parses a lint finding's message. No pin to flip, and none owed: wording is not pinned unless a consumer parses it.

Public surface. @objectstack/lint ships dist (files[]: dist, README.md, CHANGELOG.md), so the new sentence is published text; no export, type, rule id or finding shape moves. The baseline is a repo-internal gate ledger. The generated react-blocks contract and skills/objectstack-ui/references/react-blocks.md carry the contract's note and description, not the lint message, so nothing is owed there.

The rule is dormant today — true, from source. REACT_BLOCKS in packages/spec/src/ui/react-blocks.ts (4 tags: ObjectForm, ListView, ObjectChart, Block) declares deprecated on no interaction; the lint builds each block's deprecated map from exactly that field, so every map is empty and the branch at :1193 cannot run. The only spellings ever deprecated, ListView objectName / viewType, sit in REACT_RETIRED_OVERLAY_PROPS and report react-prop-retired. It does not change this diff: the mechanism and its message stay for the next deprecation, and the text an author would then read is the one judged above.

② Semver level

.changeset/20597-react-prop-deprecated-message-words.md: @objectstack/lint patch. Right: an author-shown string inside a released package changes its text and ships in dist (AGENTS.md: a fix in a released package takes patch, never none and never skip-changeset), and nothing an author can write, import or match on moves, so minor is not owed. The changeset body names no tracker number and no model. The Check Changeset run concluded success.

Clause-②: no — right. The accept set is unchanged: the same finding fires under the same condition with the same rule id and severity; only its prose differs.

③ Boundary flags

Dev flags in 5890531733 (open_questions empty; three out_of_scope_findings; six deviations):

1. react-prop-deprecated is dormant — answered, true (①). Carrier none is right: no class, no defect, the mechanism stays.
2. The stale header comment in validate-react-page-props.test.ts:32 to :36 ("carries exactly one deprecation warning" against toEqual([]) at :116 and :204), plus #11284 at :77 (comment) and :83 (describe title) — answered, true and outside this claim's surface (the claim says ⛔ not the test file's comments or describe titles; test files are a deferred surface of check-issue-citations). Carrier none stands; the next edit of that file should fix the comment.
3. :458's objectstack#5583 in the REACT_CHART_AGGREGATE_INVALID hint — answered: spec: ChartAggregateSchema 与 ChartGroupBySchema object 分支转 strictObject —— #5020 parse 接通后的收紧半边(#4001 后续批) #5583 answers 200 per the dev's control, so it is a live citation, not this card's class; it stays as one of the adjudicated pairs the shrink-only baseline pins. A form-D rewrite of live-numbered runtime strings would be its own burn-down card, not owed here.
4. Deviations — the commit's trailers are AGENTS.md's model-free pair (Claude-Session plus Co-authored-by: Claude), which is the rule, not a breach. The queue-timeout first run, the two re-run controls, the separate roster list and the scratch cleanup are process notes with no bearing on the diff. No merge of origin/main: the driver-free merge-tree exits 0 and the 4 new commits touch none of the 3 paths (confirmed above). Nothing escalated.

Fixes #20597 — right. The card's population is the citation gate's census (comment prose in packages/lint/src, string literals blanked), which read 84 at filing, 5 after stage 1 (PR #20612) and 0 after stage 2 (PR #20631, landing 5889811174); the one author-shown string the census cannot see is what this diff rewrites, and the diff adds no citation anywhere. Nothing in the card's population remains, and nothing else is owed by the card. Outside its declared surface, #11284 still appears at this head in deferred or other-lane sites — validate-react-page-props.test.ts:77 and :83, packages/spec/src/ui/react-blocks.test.ts:147, packages/spec/scripts/build-react-blocks-contract.ts:69 and :116, and the release-owned CHANGELOGs. As the card itself says, unswept is not the same as clean; none of those is this card's to sweep.

Check-runs on the head, read once (31): concluded success — Check Changeset, Type Check · source gates, The card this PR closes must claim this branch (the Fixes line against the stage-3 claim's branch), Part-of PR must not also close its card, No other open PR may claim the same issue, No other open PR may claim the same single-writer path, Governed Surface Queue Guard, Check PR Size, Check Documentation Links, Flag docs affected by code changes, Auto Label, filter, Dogfood Verify CLI. Roster skips — Console Pin Gate, Build Docs, Packed-tarball smoke (opt-in). Not concluded at the read — Lint & Repo Gates (the job that runs pnpm check:doc-authoring, pnpm check:issue-citations and pnpm lint: the ratchet's and the citation gate's verdicts on this head are therefore not yet read), Build Core, Test Core (1/6) through (6/6) (the lint package's tests), Dogfood Regression Gate (1/3) through (3/3), Temporal Conformance (live PG + MySQL), Type Check · consumer gates, Type Check · debt ledger, Type Check · workspace. None failed. This verdict is on the diff; landing waits for every one of those to conclude green or as a roster skip.

Implemented-by: claude/issue-20597-react-prop-deprecated-message
Reviewed-by: session_014EJ1ED8X4MMrT18BhVx4tx

VERDICT: PASS

---

Generated by Claude Code