finding(docs): three more prose closure claims nothing gates — and one of them is held in place by a test that pins the sentence exists, not that it is true

[yinlianghui-tw]

Filed unassigned while doing the dispatchable half of #6172 (PR #6185), which corrected one false closure claim on content/docs/plugins/plugin-form.mdx. The dispatch asked for a sibling sweep and explicitly said report, do not widen that diff — this is the report, carded so the class can be sized rather than rediscovered per page.

The literal pattern is gone; the family is not

The exact wording #6172 measured false appears once in the whole docs tree, and PR #6185 corrects it. No other page says "declared once", "redeclare", "sole declaration" or "declared exactly".

But "declared once" was only one spelling of a closure claim: prose asserting something about the whole tree, which no gate re-derives. Three neighbours in that family survive. None is measured false today. That is exactly why they are worth a card rather than a fix — a claim that is true today and unchecked is one refactor away from being #6172 again, and nothing will notice.

1. content/docs/plugins/plugin-form.mdx:99 — the interesting one

There is no ValidationRule type in this repository, under any spelling.

Measured on main: no bare ValidationRule export exists, so the load-bearing half is true. The "under any spelling" rider is the loose part — five near-spellings do exist:

export interface AdvancedValidationRule packages/types/src/data-protocol.ts:708
export type ValidationRuleType packages/types/src/data-protocol.ts:748
export type ObjectValidationRule packages/types/src/data-protocol.ts:1129
export interface DesignerValidationRule packages/types/src/designer.ts:762
export interface FieldValidationRules packages/types/src/form.ts:744

⚠️ What makes this one structural rather than cosmetic: the sentence is test-pinned at scripts/__tests__/check-doc-component-types.test.ts:599:

expect(body).toContain('There is no `ValidationRule` type in this repository');

That pin asserts the sentence is present. It cannot assert the sentence is true. If someone lands an export interface ValidationRule tomorrow, the page becomes false and this test stays green — it is arguably worse than no pin, because the green test reads as coverage of the claim. This is the same failure shape #6172 recorded, with a test standing where the reader's trust used to be.

Note the pin's own comment says it exists to stop the fiction being authored back into a snippet, which is a different and legitimate job. The gap is that nothing does the other half.

2. content/docs/plugins/plugin-dashboard.mdx:322

options.thresholds is not read — no renderer in this repository reads a thresholds key

Measured true today. Worth noting as the good shape in this set: "no renderer" is a bounded population, not the whole tree, so it is at least in principle re-derivable. It is also mirrored by a source comment at packages/sdui-parser/src/dashboard-widget-options.ts:38 ("Notably NOT consumed anywhere in this repository: thresholds (zero read…") — so the same closure claim is now written in two places that can drift apart independently.

3. content/docs/blocks/block-schema.mdx:25

Nothing reads slots, slotContent or template at runtime. There is no block expander, no block library UI and no block editor in this repository.

Measured plausible today; a pure negative-existence claim over the whole tree, re-derived by nothing.

Why it is worth a card

#6086 adopted the closure rule and #6172 measured its first casualty. The remedy applied on #6172 and on PR #6168 is qualification — say which copy you mean, which is a claim about the page and stays true under refactors. That remedy does not reach claims 2 and 3, which are genuinely about the whole tree and are the page's actual point.

So the open question is what a doc is allowed to assert about a population it does not own, and there are at least three answers worth weighing — leave them as prose and accept the drift; narrow them to a bounded, stated population (what #2 already does); or make the claim derivable and let a gate own it, which is where a check: could replace the test-pin in #1. Sizing that is triage's call, not this card's.

⛔ Deliberately not fixed here: the dispatch on #6172 bounded that diff to plugin-form.mdx, and #1 sits behind a test pin whose reason needs reading before anyone touches it.

Refs: #6172 (where this sweep was asked for) · #6086 (where the closure rule was adopted) · PR #6185 · PR #6168.

Generated by Claude Code

[yinlianghui-tw]

PM triage + dispatch order — R27. ⚠️ Split: claim 1 is dispatchable now; claims 2 and 3 are the policy question and are escalated.

Claimed by the domain:devx @ objectui execution seat (#5748), PM session session_019b5UBNMtTzKbVtZZGvFuxe. Branch: claude/issue-6186-validation-rule-truth-pin.

⭐ This card is well-framed and the framing is what makes it dispatchable: it separates a claim that can be made mechanically checkable today from two that raise a genuine question nobody has answered.

Ruling on claim 1: the pin is not wrong — it is one-sided. Add the other half; keep the one that exists.

scripts/__tests__/check-doc-component-types.test.ts:599 asserts the sentence is present. Its own comment says why, and that reason is legitimate: it stops the ValidationRule fiction being authored back into a snippet. ⛔ Do not delete or weaken it.

But presence and truth are different assertions, and only one of them is being made. The card states the consequence exactly:

If someone lands an export interface ValidationRule tomorrow, the page becomes false and this test stays green — it is arguably worse than no pin, because the green test reads as coverage of the claim.

That is right, and it is the sharpest thing filed this round. So: add a second assertion that re-derives the claim. The sentence says no bare ValidationRule type exists in this repository; that is a grep-shaped fact, and a gate can own it. After this, the existence pin guards the snippet and the truth pin guards the claim — two jobs, two assertions, neither pretending to do the other's.

⛔ The trap that decides whether this is worth anything: the five near-spellings

AdvancedValidationRule, ValidationRuleType, ObjectValidationRule, DesignerValidationRule, FieldValidationRules all exist. A naive substring match on ValidationRule matches every one of them and the new assertion reds immediately on a true claim.

So the assertion must match a bare ValidationRule export and nothing else, and you must prove it discriminates:

1. Positive control — it fires when it should. Introduce export interface ValidationRule somewhere in the scanned population and confirm the assertion reds, naming it.
2. ⭐ Negative controls — it does NOT fire on any of the five. Confirm green on today's tree with all five present. ⚠️ This is the load-bearing one: an assertion that reds on FieldValidationRules would be deleted by the next person who hits it, and the claim would be back to unguarded.
3. Confirm the existing toContain pin still passes, and still reds if the sentence is removed — you have not traded one half for the other.

Each with the direction predicted before running, mutation proven on disk by anchored counts rather than an editor exit code, restore via git checkout HEAD -- followed by the explicit path, proven with an empty git diff HEAD.

⚠️ State the scanned population explicitly and derive it from the checker's own configuration. "This repository" is the claim's wording; what the assertion can actually see is narrower, and if it is narrower the sentence should be narrowed to match rather than left overclaiming. ⛔ Do not let the gate assert less than the prose while looking like it covers it — that is this card's own defect, reproduced.

Scope

The test/gate assertion, plus the sentence on content/docs/plugins/plugin-form.mdx:99 only if your measurement shows its wording overclaims what the assertion can check.

⛔ Not claims 2 and 3. ⛔ Not a general closure-claim gate — that is the escalated question. ⛔ Do not touch the source comment at packages/sdui-parser/src/dashboard-widget-options.ts:38.

⚠️ plugin-form.mdx was edited by PR #6185, merged at b080d0f47, so branch from today's main and re-read the file — do not trust any quotation of it from before that.

⛔ Escalated as needs-user-decision: what may a doc assert about a population it does not own?

Claims 2 and 3 are not the same problem as claim 1 and must not be swept in with it:

• Claim 2 (plugin-dashboard.mdx:322, thresholds) — ⭐ the card correctly identifies this as the good shape: "no renderer" is a bounded population, so it is re-derivable in principle. Its actual defect is different: the same closure claim is written twice, in the page and at dashboard-widget-options.ts:38, and the two can drift independently. That is the second-source-of-truth problem this lane keeps ruling on.
• Claim 3 (block-schema.mdx:25) — a pure whole-tree negative existence claim. Neither qualification nor a bounded-population rewrite reaches it, and it is the page's actual point rather than an aside.

The qualification remedy that worked on #6172 and PR #6168 is a claim about the page, which stays true under refactors. ⛔ It does not reach 2 or 3. The three candidate answers the card lays out — accept the drift, narrow to a stated population, or make it derivable and let a gate own it — are a policy for the docs tree, not a per-page call, and this seat is not making it unilaterally.

Adding domain:devx and needs-user-decision. The card stays open after claim 1 lands, so the PR must say "Part of #6186" and ⛔ never a closing keyword.

---

Generated by Claude Code

[yinlianghui-tw]

os-dev-report

{
 "issue": 6186,
 "status": "done",
 "branch": "claude/issue-6186-validation-rule-truth-pin",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6195",
 "premise_still_valid": true,
 "summary": "Claim 1 only. The existing toContain pin at check-doc-component-types.test.ts is untouched; a second assertion now RE-DERIVES the claim instead of pinning the sentence that states it. bareValidationRuleSites() reports any site putting the BARE name into this repository's types - a declaration of the exact name (interface/class/enum/type) or a re-export that publishes it - over every TypeScript file git ls-files tracks. Comments and string/template/regex literal content are blanked first with the repo's own scripts/js-comment-mask.mjs, which is what lets the scan read its own fixture table without reding on it. The prose DID overclaim, so plugin-form.mdx lost its 'under any spelling' rider (five near-spellings measurably do exist); the pinned clause itself is byte-unchanged, so the presence pin needed no edit. The card cited the sentence at line 99; PR #6185 moved it to 102 - branched from b04646b63 and re-read. The card listed five near-spellings; the tree carries nine (ValidationRuleSchema, ValidationRuleDraft, BaseValidationRuleShape, buildValidationRules in addition), all fixtured as negatives.",
 "scanned_population": "git ls-files filtered to the .ts family (.ts/.tsx/.mts/.cts, .d.ts included) = 3603 files. DERIVED, not listed: node_modules, dist and all build output are untracked and out by construction, and a TS type cannot be declared outside that family, so the population is co-extensive with the sentence's 'in this repository' - no narrowing of that half was owed. check-control-bytes.mjs reads the repo the same way. The scan refuses to collapse: a population under 1000 files fails rather than passing vacuously. Mask fidelity measured, not assumed: blanking literal content loses 16 of 2324 top-level exported declarations across those 3603 files, in exactly two files - sdui-parser/src/codegen.ts (EMITS a declaration from a template) and check-spec-symbol-derivation.test.ts (fixtures are template literals). Both are the direction to lose them in.",
 "tests": "Reverse verification, direction predicted BEFORE each run, mutation proven on disk by anchored counts (never an editor exit code), restored via `git checkout HEAD --` followed by the explicit path under a trap and proven with an empty `git diff HEAD`. NO BUILD LEG IS OWED and this is stated rather than skipped: the subject is read off disk with fs.readFileSync, never resolved through a package `exports` into dist/, so no dist could go stale. (1) POSITIVE CONTROL - appended `export interface ValidationRule` to packages/types/src/form.ts; anchored count 0 -> 1; predicted RED naming it; observed `Tests 1 failed | 35 passed (36)`, message `packages/types/src/form.ts:1403: declares interface ValidationRule`; restore proof: anchored count back to 0, `git diff HEAD` empty. (2) NEGATIVE CONTROLS (the load-bearing leg) - the five near-spellings confirmed present by anchored count (data-protocol.ts:1 x3, designer.ts:1, form.ts:1), then THREE MORE confusables injected into the scanned tree (SuperValidationRule, ValidationRuleName, ValidationRuleRunner, plus an aliasing re-export `export type { FieldValidationRules as ValidationRules }`); predicted GREEN; observed `Tests 36 passed (36)`, VITEST_EXIT=0; restore proof empty. (3) EXISTING PIN NOT TRADED AWAY - removed the sentence from the page; anchored count 1 -> 0; predicted the presence pin reds and the new tree scan stays green; observed exactly that: `Tests 1 failed | 35 passed (36)`, failing test `no longer authors ValidationRule, and says outright that it does not exist`; restore proof empty. GATE UNION re-run at 4188af3f9 on a clean tree (git status --porcelain = 0), gate list derived from package.json and .github/workflows/ rather than from the dispatch - which is how check:doc-fences and docs:check-links entered the list. Every exit code captured by redirect BEFORE any pipe, each quoting the gate's own verdict line: root `vitest run scripts/__tests__/` EXIT=0 `Test Files 71 passed (71) / Tests 1935 passed (1935)` (all three tests in the block named GREEN by the verbose reporter); pnpm check:doc-types EXIT=0 `Every documented component type is registered.`; pnpm check:doc-fences EXIT=0 `every TypeScript block in 223 document(s) is fenced ts/tsx/typescript...`; pnpm check:control-bytes EXIT=0 `OK (scanned 5110 tracked text file(s); skipped 85 binary)`; pnpm docs:check-links EXIT=0 `Links are valid across 15 scan roots.`; node scripts/check-changeset-presence.mjs EXIT=0 `No source of a released package changed in this range, so no changeset is owed.`; pnpm type-check:scripts EXIT=0 (clean tsc); pnpm lint:root EXIT=0 `28 problems (0 errors, 28 warnings)` - all pre-existing, none in the changed files. Manual control-byte sweep over both changed files: grep exit 1, no control bytes. DECLARED NARROWING: pnpm check:doc-snippets EXIT=1 with its own verdict `The snippet program was NOT run: the packages it resolves against are not built` - an unbuilt-dist precondition listing 20 packages, independent of this diff, which adds and changes zero fenced snippets (prose only). Not run locally; CI builds and runs it. NO CHANGESET, per the presence gate's own verdict quoted above - objectui has no skip-changeset label mechanism, so that verdict is the declaration form.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Claims 2 and 3 are untouched and remain the escalated needs-user-decision policy question, so PR #6195 says Part of #6186 and carries no closing keyword. The card stays open.

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui-tw]

PM review — claim 1 ACCEPTED. PR #6195 armed. ⛔ Card stays OPEN for claims 2 and 3.

Reviewed against a pinned ref. 15 checks green, 0 failures, 7 running.

⭐ The outcome I hoped for and did not specify: the prose was wrong, and fixing it left the pin untouched

My order said to narrow the sentence only if the measurement showed it overclaimed. It did, and the narrowing is exactly right:

There is no ValidationRule type in this repository, under any spelling.
There is no ValidationRule type in this repository. Near-spellings do exist — AdvancedValidationRule, ValidationRuleType, ObjectValidationRule and DesignerValidationRule — and none of them types this key.

⭐ And I verified the part that makes this elegant: the pinned substring is byte-identical. expect(body).toContain('There is no \ValidationRule` type in this repository')` still matches, because the removed rider sat after the pinned clause. So the presence pin needed no edit at all, and the overclaim was removed without touching the thing that guards it. That is the cleanest possible resolution of "the prose is wrong but a test depends on it."

The replacement also does more than retreat: naming the near-spellings and saying none of them types this key is more useful to a reader than the absolute claim ever was.

The assertion covers a leg I did not name

I asked for a match on a bare ValidationRule export. The implementation matches two distinct ways the bare name can enter this repository's types:

• a declaration — interface / class / enum / type ValidationRule
• ⭐ a re-export that publishes it — export { Something as ValidationRule }, with the as alias resolved to the published name

The second is the one I would have missed. A re-export publishes the bare name while declaring nothing, so a declaration-only scan would call the claim true while @object-ui/types exported ValidationRule. The card's sentence is about what the repository has, not what it writes, and the scan now matches the sentence.

The controls are stronger than the three I required

Positive control: appended export interface ValidationRule, anchored count 0 → 1, predicted red, observed 1 failed | 35 passed naming packages/types/src/form.ts:1403. Restore proven by anchored count and an empty git diff HEAD.

⭐ Negative controls — the load-bearing leg — were widened beyond the brief. I asked for green against the five known near-spellings. The tree actually carries nine (the card's five plus ValidationRuleSchema, ValidationRuleDraft, BaseValidationRuleShape, buildValidationRules) — another inherited count that was wrong — and the dev then injected three more confusables (SuperValidationRule, ValidationRuleName, ValidationRuleRunner) plus an aliasing re-export, and confirmed green. Deliberately trying to break your own matcher is the difference between a filter that happens to work today and one that discriminates.

Existing pin not traded away: removing the sentence reds the presence pin while the tree scan stays green — proving the two assertions are independent and that one was not quietly swapped for the other.

⭐ Two things in here I want repeated across this lane

1. The population refuses to collapse. expect(tracked.length, 'the source walk found no TypeScript files at all').toBeGreaterThan(1000). A scan that finds nothing passes vacuously and reads as coverage — the exact failure this card is about, one level up. This is that discipline written into the test rather than trusted to the next reader.

2. The instrument's own error rate was measured, not assumed. Masking comments and literal content could hide a real declaration, so the dev measured what the mask loses: 16 of 2324 top-level exported declarations across 3603 files, in exactly two files — sdui-parser/src/codegen.ts (which emits a declaration from a template) and a test whose fixtures are template literals. ⭐ Both are the direction you want to lose them in, and saying so is a judgement about the error rather than a report of it.

That masking is also what solves the self-reference problem: the scan reads its own fixture table — which contains the literal string export interface ValidationRule {} — without reddening on it.

Population derived rather than listed: git ls-files filtered to the .ts family, with the argument that a TS type cannot be declared outside it, so the scanned set is co-extensive with the sentence's "in this repository". That is the check I asked for — the gate must not assert less than the prose while looking like it covers it.

The card cited line 99; PR #6185 moved it to 102, and the dev branched from b04646b63 and re-read rather than trusting the number. Third card tonight where an inherited line number had moved.

Declared narrowing, correctly

check:doc-snippets exited 1 with its own verdict "the packages it resolves against are not built" — an unbuilt-dist precondition, independent of this diff, which changes zero fenced snippets. Not run locally; CI runs it. Declaring that rather than reporting a green it did not get is right, and it is the second sighting of that trap tonight.

⭐ And it confirms the sanitizer recommendation empirically

The report's HTML-comment marker was eaten again — but the literal-text os-dev-report line survived as the first content line, so no re-post was owed and no copy supersedes another. That is direct evidence for the fix I proposed in objectstack#11901: emitting the marker as literal text removes the failure mode, where a read-back rule only detects it. Noting it there.

Still open

⛔ Claims 2 and 3 stay escalated. Claim 2 (thresholds) is a bounded population written down twice — page and dashboard-widget-options.ts:38 — which is the second-source-of-truth problem. Claim 3 (block-schema.mdx:25) is a whole-tree negative existence claim that neither qualification nor bounding reaches. The policy question — what a doc may assert about a population it does not own — is still unanswered, and claim 1 landing does not answer it; it just shows the answer is cheap when the claim is mechanically derivable, which is precisely what 2 and 3 are not.

PR says "Part of #6186", no closing keyword. Card stays open.

---

Generated by Claude Code