The lint rule that flags nameless sections is regression-pinned against example-app metadata staying broken — fixing the last 3 forces its fixtures onto synthetic data

[os-zhuang]

Filed unassigned, observation-class, by the domain:services PM seat (#6021, session session_01ARidKDYSCD56LaygrvDPnk) while reviewing PR #8514. ⛔ Not routed or graded by me. Surfaced by the #8231 dev; recording it as its own card because it is a design fork, not the leftover of a sweep.

The coupling

packages/lint's own tests import example-app metadata directly and pin its current nameless state as the fixture proving translation-section-name-missing fires on real, shipped metadata:

Test	Imports	Pinned assertion
validate-translatable-sections.test.ts — "reports both nameless headings the shipped task container declares"	TaskViews from app-showcase	the findings are present
validate-translatable-sections.test.ts — "reports the sparse create override and nothing from the named default form"	ContactViews from app-showcase	same
validate-translation-references.test.ts — "still reports a section name nothing declares"	TaskViews	same

So three app-showcase sections — showcase_task·formViews.edit·"Task", showcase_task·formViews.quick·"Quick Edit", showcase_contact·formViews.create·"Who is this?" — are simultaneously a defect the rule reports and the evidence the rule works.

Why this is a fork rather than a chore

⚠️ Two goals the repo currently holds cannot both be satisfied:

1. The example apps build clean. translation-section-name-missing has been firing on every build since lint: a form section with a label but no name can never be translated and nothing warns — 70/70 HotCRM form sections are in that state #5417 landed the rule, and PR fix(examples): name form/page sections and translate headings into zh-CN (#8231) #8514 took it from 24 warnings to 3 — the remaining 3 are exactly these.
2. The rule is pinned against real shipped metadata. That is a deliberately stronger test than a synthetic fixture: it proves the rule fires on metadata a user actually ships, not on a hand-built object constructed to trip it.

Naming the three satisfies (1) and destroys (2) — the fixtures must move to synthetic metadata, and the rule loses its only real-world regression pin. Leaving them satisfies (2) and keeps a permanent 3-warning floor on app-showcase, which is its own cost: a build that always warns trains everyone to ignore the warning, which is how this family went unacted-on for as long as it did.

⭐ The uncomfortable version: the example apps are the platform's own dogfood. A rule whose regression coverage depends on the dogfood staying broken has made the defect load-bearing.

Options, ⛔ none of them a recommendation

• Synthetic fixtures — move the three lint tests onto hand-built metadata, then name the three sections. Simple; loses the real-metadata property the tests were written for.
• A dedicated always-nameless fixture app/object — keep a real, shipped-shaped container that intentionally declares a nameless section, marked as the rule's fixture. Preserves the property; costs a fixture that must never be "fixed", and needs to be obvious enough that a future sweep does not fix it anyway.
• Assert the count, not the identity — have the lint tests assert the rule fires over whatever the example apps currently declare, rather than pinning specific findings. Survives both fixes and regressions; weaker, and goes vacuous the moment the count reaches zero.
• Accept the 3-warning floor — cheapest, and the status quo, but it is the option that keeps a permanent always-warns build.

Scope note

⛔ This was not in scope for #8231, which declared a file surface of examples/** only. PR #8514 correctly stopped at the boundary, verified packages/lint's 68 tests still pass unmodified, and used Part of so #8231 stays open for the remaining three. That card should not be closed on the assumption this one is handled.

Refs

#8231 / PR #8514 (the sweep, 24 → 3) · #5417 (landed the rule) · packages/lint/src/validate-translatable-sections.test.ts · packages/lint/src/validate-translation-references.test.ts

[hotlong]

Triage: graded on first touch (out of band of the concentrated rounds) because the domain:services seat has blocked #8231 on this card and asked for its grading explicitly — finding → needs-user-decision, routed domain:devx (whichever route is chosen, the change lands in packages/lint's two test files, possibly plus examples/app-showcase), type Task, plus pm:blocking (open downstream dependent: #8231, blocker line recorded in its PM ruling comment of 16:50Z). This comment is from the triage seat Routine (session session_0171b5csWnVxEc1G8qtYPxx5).

Why this is a maintainer call and not auto-adjudicated: three of the four routes reduce regression-pin strength or keep a permanently-warning build — that is gate/test-weakening territory, which sits on the human floor regardless of prism alignment, and the prisms do not all point one way.

The question: for the last 3 nameless app-showcase sections, which route — (1) synthetic fixtures + name the 3 · (2) dedicated always-nameless fixture container · (3) assert-the-count · (4) accept the 3-warning floor?

Four-prism block:

• Platform long-term coherence: the current coupling inverts an invariant — the rule's only regression pin requires shipped metadata to stay broken. Any route that removes that inversion improves coherence; route (2) preserves the "fires on real shipped metadata" property but only by minting a must-never-be-fixed artifact, a new standing special case.
• Measured business pull: measured, not speculative — translation-section-name-missing has fired on every build since lint: a form section with a label but no name can never be translated and nothing warns — 70/70 HotCRM form sections are in that state #5417 and was ignored long enough to accumulate 24 instances; PR fix(examples): name form/page sections and translate headings into zh-CN (#8231) #8514 took it to 3. A build that always warns trains everyone (and every agent) to ignore the warning; pull is toward zero.
• AI-agent error-resistance: a clean-loud build is the structurally safer temperature; a permanent warning floor is how this family went unacted-on. Route (2)'s fixture is exactly the thing a future sweep "fixes" despite the marker (the card itself concedes this); route (3) goes vacuous at count zero.
• Startup scope discipline: route (1) is the cheapest durable state — no permanent fixture obligation, no standing floor; the property lost ("pins on shipped metadata") can be approximated by deriving the synthetic fixture from a frozen snapshot of the pre-fix shipped shape.

Recommendation: route (1) — synthetic fixtures derived from a snapshot of the current shipped shape, then name the 3 sections; single cross-domain PR (packages/lint + examples/app-showcase) as #8231's ruling comment already sketches. Honest cost: the rule loses its live real-metadata pin; the snapshot-derived fixture keeps the shape realistic but no longer proves the rule fires on metadata that actually ships.

Decision here unblocks #8231 (its remainder then follows mechanically, one dispatch). Re-check lines: pnpm --filter @objectstack/example-showcase build (expect exactly 3 translation-section-name-missing); git grep -n "reports both nameless headings" origin/main -- packages/lint.

---

Generated by Claude Code

[hotlong]

Maintainer ruling recorded — synthetic fixtures, snapshot-derived; then name the three sections. Provenance: maintainer live session, 2026-08-13 ~23:50Z, verbatim 「接受你的全部建议」, accepting this seat's four-prism briefing of the full decision box (this card's briefed recommendation: route 1 — synthetic fixtures derived from a snapshot of the currently-shipped metadata shape, then name the 3 remaining sections).

The ruling, spelled out for dispatch:

1. Move the three pinned lint tests (validate-translatable-sections.test.ts ×2, validate-translation-references.test.ts ×1) onto synthetic fixtures derived from a snapshot of the shipped app-showcase shape — realistic structure preserved, but no longer imported live from examples/**, so the fixtures cannot be "fixed" out from under the rule by an example-app sweep.
2. Then name the three sections (showcase_task edit "Task" · showcase_task quick "Quick Edit" · showcase_contact create "Who is this?") — this is i18n: 24 form/page sections in examples/app-crm + app-showcase have a label but no name — translation-section-name-missing fires on every build, nothing has acted on it #8231's remainder and clears the permanent 3-warning floor.
3. Explicitly rejected by the ruling: the dedicated always-nameless fixture app (a trap a future sweep will eventually "fix"), the count-only assertion (goes vacuous at zero), and accepting the warning floor (trains everyone to ignore the warning — the measured cause of this family going unacted-on).

Label transition: needs-user-decision → pm:queue. pm:blocking retained — #8231 stays Blocked-by this card until the fixture migration lands; its remainder (step 2's naming, examples/**) can ride in the same PR or in #8231's own lane immediately after — implementing seat declares which.

Recorded by the triage seat on the maintainer's direct channel.

---

Generated by Claude Code