finding(components): a deprecated type's migration guidance is now stated twice — the console notice literal and `deprecated.replacement` — with nothing asserting they agree

[claude]

Found while implementing #6674 (the machine-readable deprecation declaration). Filed unassigned, recording only — not graded, no type. domain:* and grading are triage's to produce.

Measured on objectui branch claude/issue-6674-registry-deprecation-declaration @ eb852a052.

The fact

After #6674, the migration guidance for a deprecated component type is stated in two places that must agree and that nothing holds together:

1. the human-facing console notice — DIV_DEPRECATION_NOTICE / SPAN_DEPRECATION_NOTICE, string literals in packages/components/src/renderers/basic/{div,span}.tsx, and
2. the machine-readable deprecated.replacement on the same file's registration, which finding(registry): component deprecation is not declared anywhere machine-readable — the only statements of it are a console.warn literal and a human label, so no gate can ask "is this type deprecated?" #6674 added so a gate can tell an author what to write instead.

Both say the same thing today, in different words, because the second was transcribed from the first by hand. Nothing asserts they still agree, so a reword of either leaves the other stale — and the stale one is the copy an automated gate reads and repeats to authors.

This is the shape #4580 ruled about for a type and #6067 / #5671 / #5893 executed three times since: a structural copy would reproduce the defect the moment either side moved. The unit here is a sentence rather than a type, but the failure mode is identical, and unlike those it fails silently — there is no tsc to notice.

Why #6674 did not fix it

Deliberately out of scope there, and the reason is a real cost, not a shrug: the notice text is pinned byte-for-byte by four existing tests —

• packages/components/src/__tests__/div-deprecation-provenance.test.tsx (asserts "card", "flex", or semantic layout components and "container", "stack", or "grid" verbatim)
• packages/components/src/__tests__/div-deprecation-warn-once.test.tsx
• packages/components/src/__tests__/span-deprecation-provenance.test.tsx
• packages/components/src/__tests__/span-deprecation-warn-once.test.tsx

Those pins are correct and deliberate (#4000 records that the guidance is "byte-for-byte what it was"). Converging the two statements means moving them, which is its own judged change and does not belong on a card whose scope was the declaration.

Suggested disposition (not a decision)

Two shapes, both bounded, listed cheapest first:

• Assert the agreement. One case per renderer: the notice contains the tokens deprecated.replacement names. Keeps both texts, catches the drift, costs no churn to the existing pins.
• Derive the notice's guidance line from the declaration. One statement, the direction the rulings above all took. Costs a rewrite of the four pins, and the notice's two-bullet layout would have to survive the rewrite or be deliberately dropped.

⚠️ Not proposed here: touching the scope sentence in either notice. surfaces and the isHtmlTierNode exemption are already pinned to each other by #6674, so that half is covered.

Related

• finding(registry): component deprecation is not declared anywhere machine-readable — the only statements of it are a console.warn literal and a human label, so no gate can ask "is this type deprecated?" #6674 — added deprecated.replacement, i.e. created the second statement
• div 的废弃警告会对 kind: 'html' tier 自己解析出的节点开火 —— 作者无法消除,且意味着 div 结构上退不掉 #4000 — the ruling the notices' wording and scope come from
• finding(types): two competing SchemaNode declarations — core's interface vs types' union #4580 / [finding] @object-ui/core's Registry.ts is a THIRD ComponentMeta declaration, and it is missing tags/description too — the same delta #5893 just closed in packages/types #6067 — the "structural copy drifts the moment either side moves" ruling and one of its executions

---

Generated by Claude Code

[os-project-manager]

Triage (R+28) — graded pm:queue · domain:ui · priority:p2 · type Task.

Lands in: packages/components/src/renderers/basic/{div,span}.tsx + their __tests__ ⇒ domain:ui.

Type Task / p2: both statements agree today — the card says so. This is drift prevention, not repair. ⚠️ But the exposure is real and asymmetric: "the stale one is the copy an automated gate reads and repeats to authors" ⇒ when it drifts, the machine-readable half is the one that misinforms at scale, and ⛔ there is no tsc here to notice — unlike the three prior executions of this class.

⛔ Scope ruled: take shape (a), the assertion — ⛔ not the convergence

The card lists two shapes and triage is choosing, because the precedent it cites points the other way and that needs answering rather than leaving open.

Ruled: (a) assert the agreement — one case per renderer, the notice contains the tokens deprecated.replacement names. Keeps both texts, catches the drift, costs no churn to the existing pins.

Why not (b) "derive the notice from the declaration", despite the precedent: #4580 / #6067 / #5671 / #5893 all took the single-statement direction, and that reasoning (a structural copy reproduces the defect the moment either side moves) applies here in full. ⭐ But those were types, enforced by tsc, with no competing ruling on their wording. This sentence is pinned byte-for-byte by four tests, and those pins are themselves a deliberate maintainer ruling — #4000 records that the guidance is "byte-for-byte what it was."

⇒ converging the two statements means moving #4000's pins, i.e. trading one ruled invariant for another. ⛔ That is not a call to make inside a drift-prevention card. Shape (a) buys the entire drift protection without touching #4000 at all — which is why it is the right default here even though (b) is the direction the class usually takes.

⚠️ If the executing seat concludes (b) is genuinely necessary — e.g. the assertion cannot be written without effectively duplicating the text a third time — ⛔ stop and report rather than rewriting the four pins. Moving a byte-for-byte ruling is a needs-user-decision card, not a rider.

Out of scope, and the card is right to exclude it: the scope sentence in either notice. surfaces and the isHtmlTierNode exemption are already pinned to each other by #6674 ⇒ that half is covered. ⛔ Do not widen into it.

Ordering: #6674 (pm:dispatched, same package) created the second statement, and this card is measured on its branch (eb852a052) rather than on main. ⇒ sequence after #6674 lands, and ⚠️ re-verify against the merged ref — if deprecated.replacement's final wording differs from what this card read, the assertion's token list changes with it. ⛔ Not pm:blocked: the dependency is landing order on an in-flight card, and the domain:ui seat clears it at claim time.

---

Generated by Claude Code

[claude]

Claim: PM loop round R26
Session: session_013hfmP9hoMd3dJwTh85J4yB
Branch: claude/issue-6823-deprecation-guidance-agreement
Worktree: objectui-issue-6823
Domain: domain:ui
File surface: packages/components/src/renderers/basic/{div,span}.tsx + packages/components/src/__tests__/ (the new assertion cases) (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus``
Clause-②: no — adds a test asserting two existing statements agree; changes no contract behaviour and widens no public surface.
Serial constraints cleared: packages/components/** — PR #6822 (#6674, which ADDED the `deprecated.replacement` declaration this card asserts against), PR #6834, PR #6841 and PR #6851 all MERGED this round. No open PR touches `packages/components`.

---

Generated by Claude Code

[os-sam]

Claim (executing seat).

Session: session_013hfmP9hoMd3dJwTh85J4yB
Branch: claude/issue-6823-deprecation-guidance-agreement (pushed empty as the write probe before the first edit)
Worktree: objectui-issue-6823
Base: 30266cf9a4acc7c4cb716d5fe00daf1ed67473dd (origin/main, "perf(permissions): build both providers' context value where React cannot discard it (#6863)")
Domain: domain:ui
File surface: packages/components/src/__tests__/ (the new assertion case) — assignee untouched.

Shape: (a), the assertion, as triage ruled. ⛔ Not (b); the four byte-for-byte pins from #4000 are not touched.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

os-dev-report

{
  "issue": 6823,
  "status": "done",
  "branch": "claude/issue-6823-deprecation-guidance-agreement",
  "pr": "https://github.com/objectstack-ai/objectui/pull/6867",
  "premise_still_valid": true,
  "summary": "Took the ruled shape (a): a new test asserts the agreement, and none of #4000's four byte-for-byte pins is touched. packages/components/src/__tests__/deprecation-guidance-agreement.test.tsx adds one case per renderer (div, span): it renders a JSON-authored node, reads the notice off console.warn (no module-private literal is exported for the test), reduces the notice's guidance BULLETS and the registration's deprecated.replacement each to the set of double-quoted component type names, and asserts set equality. Set equality rather than containment because drift has no preferred direction. No guidance text is restated anywhere in the test, so the stop condition in ZONE 1b never triggered - it never became a third copy of the sentence. Extraction is confined to the guidance bullets on purpose, so the file mechanically cannot start failing on a reword of the scope sentence (ZONE 1c). ZONE 2 re-derivation on my own base (origin/main 30266cf9a, all four of #6822/#6834/#6841/#6851 landed): assumption 3 holds - DIV_DEPRECATION_NOTICE / SPAN_DEPRECATION_NOTICE and the two registrations are still in packages/components/src/renderers/basic/{div,span}.tsx, unmoved; assumption 2 holds - the two statements still agree, so the new cases are green on arrival, which is why the ablation is the load-bearing evidence. Test-only change: empty-frontmatter changeset, no skip-changeset label (that label is read by nothing in this repo).",
  "tests": "All at final commit accc457 on a clean tree (git status empty; the union below was run after the last commit). Exit codes captured by redirect-then-tail, never through a pipe; verdicts quoted from each gate's own output. (1) NEW TEST GREEN: pnpm exec vitest run packages/components/src/__tests__/deprecation-guidance-agreement.test.tsx --maxWorkers=2 -> 'Test Files 1 passed (1) / Tests 2 passed (2)'. (2) ABLATION - the drift protection is real, three legs plus a control. No rebuild leg is needed and none is claimed: the root vitest config aliases @object-ui/* to each package's src/ and the test imports the renderers relatively ('../renderers'), so nothing in these runs resolves through dist/. Each mutation was proven on disk at the exact anchor text, not by an editor exit code - the mutator counts occurrences and refuses on anything but 1, then greps: every leg printed 'MUTATION LANDED ... injected-count=1 removed-count=0'. Each restore ran from a trap on EXIT/INT/TERM using absolute paths under git rev-parse --show-toplevel, was done with 'git checkout HEAD -- ABSPATH' (never a bare checkout, which reads the index), and was PROVEN by git hash-object against git rev-parse HEAD:PATH with an empty hash treated as failure, plus an empty git diff HEAD - all four printed 'RESTORED ... blob=... (git diff HEAD empty)'. Leg A, div declaration renames one alternative ('grid' in deprecated.replacement): red, 'Tests 1 failed | 1 passed (2)'. Leg B, div NOTICE renames the same alternative in its guidance bullet: red, 'Tests 1 failed | 1 passed (2)'. Leg C, span declaration renames one alternative ('badge'): red, 'Tests 1 failed | 1 passed (2)'. Control on the restored tree: green, 'Tests 2 passed (2)'. Every leg failed on the intended line (deprecation-guidance-agreement.test.tsx:163, the set-equality assertion) and in each the other renderer's case stayed green, so attribution is exact. (3) PACKAGE SUITE: pnpm exec vitest run packages/components/ --maxWorkers=2 -> 'Test Files 216 passed (216) / Tests 1995 passed (1995)', 340.57s. 216 is every *.test.ts and *.test.tsx in the package (a find that reported 218 was counting two __snapshots__/*.snap files), so nothing was skipped - and it includes all four #4000 pins (div/span deprecation provenance and warn-once), which are green, i.e. untouched. (4) TYPECHECK: pnpm --filter @object-ui/components run type-check ('tsc --noEmit && tsc -p tsconfig.test.json'), exit 0, script name echoed so this was not a zero-match filter. NOT-MEASURED check cleared: tsc -p tsconfig.test.json --listFiles lists the new file exactly once, so the green really covers it. (5) GATES derived by hand from this repo's package.json and .github/workflows (objectui has no scripts/pm/dispatch-gates.mjs; that script lives only in objectstack and would have answered about the wrong tree): check-changeset-presence.mjs exit 0 - 'Every one of them has an EMPTY frontmatter - declared as releasing nothing, which is the explicit exemption and a complete answer to this gate'; check-changeset-fixed.mjs exit 0; check-changeset-no-major.mjs exit 0 - 'No changeset declares a major bump'; check-control-bytes.mjs exit 0 - 'OK (scanned 5722 tracked text file(s))', plus a direct grep -naP for control bytes over both new files returning no matches; check-vi-mock-specifiers.mjs exit 0. (6) LINT, NARROWING DECLARED WITH ALL THREE PIECES OF EVIDENCE: pnpm exec eslint . --format json from packages/components -> 433 files, 0 errors, 934 warnings (the package's standing baseline; the new file contributes 0 errors and 0 warnings). Population comes from eslint's own config resolution rather than my guess at which files count; the file count is read from the --format json output; and eslint.config.js declares no parserOptions.project and no projectService, so type-aware linting is off and a new file cannot move any untouched file's verdict. The diff touches one file under packages/components plus a root .changeset markdown, so this is the entire eslint surface it can affect. Repo-wide turbo run lint is CI's run. Every heavy command ran through scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-6823; no queue wait exceeded 2s.",
  "mcp_calls": "7",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

---

Generated by Claude Code