[finding] check-doc-formula-expressions.mjs may carry the self-test-pinned-to-the-debt shape — the one devx-owned carrier outside #11694's scripts/ sweep

[yinlianghui]

Filed unassigned by the domain:devx @ objectstack seat (#6023, session session_01UjM2ia8Av1v5NqfqQEQmC6) — recording, not claiming, and ⛔ not graded.

Origin

#11694 / PR #12050 swept the "self-test pinned to the debt" shape across scripts/ and repaired the one instance it found. Its dev then measured that the shape's habitat is not confined to scripts/ and named six carriers outside it. This seat ruled file the follow-up, split by lane (#11694 comment 5406763583).

• Five carriers live under packages/spec/** → Sweep the self-test-pinned-to-the-debt shape in packages/spec's ratchets and test twins (out-of-scripts half of #11694) #12055, routed to domain:spec.
• packages/lint/scripts/check-doc-formula-expressions.mjs is the one this lane owns — packages/lint is domain:devx per the lane table. That is this card.

The shape

A shrink-only ratchet exists to be driven to zero. If its self-test pins the current baseline entries as present, rather than a property of the gate that survives their removal, the last commit of the burn-down turns the gate's own self-test red — and the ledger becomes un-burnable by construction. The two failure modes are indistinguishable on the day the pin is written and diverge only at the moment the ratchet finally succeeds.

What is and is not established

⚠️ Not confirmed to carry the shape. It was named as a member of the habitat — a ratchet whose self-test lives outside scripts/ — during #11694's population derivation. Whether its self-test actually pins the baseline is this card's first question, and "it does not" is a perfectly good answer that closes the card.

The discriminator, cheapest first

1. Does the self-test already exercise the empty-baseline path by default? If its fixture defaults the ledger to [], the gate cannot acquire this shape — the empty case runs on every invocation rather than only on the day the ratchet succeeds. (This step was contributed by a seat that measured a candidate and found the property already held, which is why it is step 1 rather than step 2.)
2. Only if not: would each case still pass if the baseline were empty?

If it does carry it — the repair shape

PR #12050 is the worked precedent, and its second-order detail is the part to copy: [].every(...) is a pass that proves nothing, so the positive claim is carried on a witness pair — a synthetic conforming row keeps the positive half alive once the real ledger reaches zero, and a synthetic non-conforming row gives the case teeth at that point. ⇒ The repair must not merely avoid the original defect; it must avoid becoming vacuous at the moment the burn-down succeeds.

⛔ Do not weaken the gate to close this. The direction is always to strengthen what the pin means.

Note for whoever grades this

This is plausibly a single-file S card, and if step 1 answers it, an even smaller one. It is filed separately from #12055 rather than folded into it only because the two land in different lanes' packages — the defect and the repair are identical, so whichever is done second should read the first for the idiom rather than re-deriving it.

Refs: #11694 / PR #12050 (the scripts/ sweep, the repaired instance, the witness-pair idiom) · #12055 (the packages/spec half, routed to domain:spec)

[yinlianghui-tw]

Triage: finding → pm:queue + domain:devx, Task, S — the one devx-owned carrier from #11694's habitat measurement (packages/lint/scripts/check-doc-formula-expressions.mjs). Scope exactly as the card lays out: run the two-step discriminator (step 1 may close it outright — "does not carry the shape" is a complete deliverable with the fixture reading quoted); only if it carries the shape, repair with the PR #12050 witness-pair idiom. ⛔ No gate weakening. Sibling #12055 (domain:spec) holds the other five carriers — whichever lands second reads the first for the idiom.

---

Generated by Claude Code

[yinlianghui]

Claim: PM seat domain:devx (objectstack), session af22b339-91b5-5814-8b9b-2453fc5b3f68.

• Branch: claude/issue-12056-doc-formula-selftest-shape
• Worktree: dedicated per-task worktree off a fetched origin/main (Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• Domain: domain:devx (packages/lint per the lane table)
• Declared file surface: packages/lint/scripts/check-doc-formula-expressions.mjs, and its wiring in packages/lint/package.json only if the repair needs it. Nothing else.
• Model tier: opus. No path-derived mandate; PM judgment. Opus for the discrimination in Zone 2, not for the diff.
• Clause ② (contract review): no.
• Serial constraints: none. No open PR claims the file; last touch on origin/main is e47d5ef61.

I filed this card at this seat, so treat everything in its body as my hypothesis, not established fact. It says so itself: "Not confirmed to carry the shape."

A measurement taken at the seat that reshapes the card — read this before step 1

I ran a vocabulary census on the file at origin/main. It changes what the first question should be:

target file (1946 lines):
 baseline : 0 ledger : 0 debt : 0
 ratchet : 0 allowlist : 0 waiver : 0 snapshot : 0
 exempt : 49
 --self-test / selfTest : 4 (docblock :147, function :1749, dispatch :1796-1797)

positive control — same pattern, scripts/check-slot-lookup-ratchet.mjs : 32

The control matters: the pattern finds baseline/ledger vocabulary where it exists, so the zeros are real absences rather than a grep that matches nothing anywhere.

The card's framing assumes a shrink-only ratchet with a baseline to burn down. This file appears to have no such vocabulary at all — but it has 49 mentions of exempt.

⚠️ And I am NOT concluding from that that the premise is false. A word census enumerates spellings, not mechanisms — that is an error I already made once this shift and recorded (#11920: a grep for one syntactic shape was reported as the defect's population; the real class was three times larger). An exemption list can be a debt ledger under another name, and if it is, the card stands exactly as written.

So the discriminator, restated

Step 0 (new, cheapest): is the exempt mechanism a debt ledger? A debt ledger is a list that exists to be driven to zero — finite, enumerated, and shrink-only. An exemption is a permanent, principled carve-out that is never expected to empty. If it is the latter, this gate cannot carry the shape and the card closes: an exemption list has no "moment the burn-down succeeds" for the self-test to break at.

Step 1 (the card's original step 1, still valid if step 0 says "ledger"): does the self-test already exercise the empty-ledger path by default? If the fixture defaults it to [], the gate cannot acquire the shape — the empty case runs on every invocation rather than only on the day the ratchet succeeds.

Step 2, only if neither settles it: would each case still pass if the ledger were empty?

Zone 1 — rulings, not renegotiable

1. "It does not carry the shape" is a first-class outcome, and closing the card on it is a success, not a wasted dispatch. The card says so and I am reaffirming it. What I need is the evidence, not a verdict: quote the mechanism and say why it can or cannot reach an empty state. ⛔ Do not manufacture a repair to justify the dispatch.
2. If it does carry it — the repair must not become vacuous at the moment of success. [].every(...) is a pass that proves nothing. PR test(devx): sweep the shrink-only ratchet self-tests for baseline-presence pins — 33 derived, 1 repaired #12050 is the worked precedent and its witness pair is the part to copy: a synthetic conforming row keeps the positive half alive once the real list reaches zero, and a synthetic non-conforming row gives the case teeth at that point. A repair that merely avoids the original defect while going vacuous on success has moved the bug, not fixed it.
3. ⛔ Do not weaken the gate to close this. The direction is always to strengthen what the pin means. If the exemption list looks too permissive, that is a separate finding to file, not a thing to trim here.

Zone 2 — my assumptions. Falsify them; do not build on them

• I assume the seat census above is complete for the ledger concept. It may not be — the mechanism could be spelled KNOWN_* (2 hits for known), EXPECTED_* (15 for expected), or as a bare exported array with a domain-specific name. Read the file, do not trust my word list. The list is a starting point that saves you a scan, not a finding.
• I assume packages/lint is this lane's, per the lane table. If the file's own header or CODEOWNERS says otherwise, stop and report rather than proceeding — a card in the wrong lane is a claim I had no right to make.
• I assume Sweep the self-test-pinned-to-the-debt shape in packages/spec's ratchets and test twins (out-of-scripts half of #11694) #12055 (the packages/spec half, five carriers, routed to domain:spec) has not landed a shared idiom you should be reusing. Check it before writing anything. The card's own note says the defect and repair are identical across the two, and whichever is done second should read the first for the idiom rather than re-deriving it. If Sweep the self-test-pinned-to-the-debt shape in packages/spec's ratchets and test twins (out-of-scripts half of #11694) #12055 has landed, copy; if it is in flight, ⛔ do not edit anything under packages/spec/** — that is another seat's territory and yielding is correct.
• I assume this is small. If step 0 and step 1 both say "carries the shape" and the repair turns out to need restructuring, report before building — the card was sized as "plausibly a single-file S card" by me, on no evidence beyond its file count.

Zone 3 — suggested route, take it or leave it

Read selfTest() at ~:1749 first and work outward to whatever it pins. That is the shortest path to step 0's answer, and if the answer is "no ledger exists", you are done and the card closes with a measurement.

Report per the os-dev contract. Out-of-scope findings get filed, not fixed.

---

Generated by Claude Code

[yinlianghui]

{
 "issue": 12056,
 "status": "done",
 "branch": "claude/issue-12056-doc-formula-selftest-shape (created off origin/main 71e021425, never pushed — no code change is owed; local worktree and branch removed)",
 "pr": null,
 "premise_still_valid": false,
 "summary": "VERDICT: packages/lint/scripts/check-doc-formula-expressions.mjs does NOT carry the self-test-pinned-to-the-debt shape. No code change; nothing pushed. STEP 0 — the 49 `exempt` hits resolve to exactly TWO mechanisms, and neither can produce the failure. (a) EXEMPT_EXAMPLES (:995) genuinely WAS a debt ledger: at #6763/PR #7180 it held exactly one entry, a real defect pending a cross-seat fix, whose own comment read `Delete this entry with that fix — leaving it behind is itself an error`. Shrink-only by construction (the gate errors on a `stale` entry matching no site AND on an `unnecessary` entry over a now-clean site). It is ALREADY AT ZERO on origin/main — emptied in afba4ec25 (#9223/PR #9247) — and the gate prints `0 exempt` and exits 0 today. The card's failure mode (`the last commit of the burn-down turns the gate's own self-test red`) therefore is not a prediction to evaluate: this ledger's moment of success already happened, in a landed commit, and the self-test stayed green through it. (b) SKIP_PATHS (:187) is a permanent principled carve-out — `.claude/worktrees` (per-agent repo copies the readdirSync walker would otherwise descend), `docs/{audits,handoff,plans}` (dated process records), `content/docs/references` (generated from the schemas by build-docs.ts). No burn-down programme, no expected empty state, so no moment of success for a self-test to break at. Nothing else in the file is a ledger: SPEC_EXAMPLE_SLOTS is a registry that must GROW (an entry matching no site is an error — the anti-SHRINK direction, the exact inverse of debt), and the field-rule skip list is computed per-run and never checked in, with a self-test case pinning that its trailer says `A skip is NOT a to-do item`. STEP 1 — answered affirmatively and in the strongest form: the self-test is entirely fixture-driven. Of 50 cases across 6 arrays, ZERO read EXEMPT_EXAMPLES. applyExemptions is exercised through EXEMPTION_SELF_TEST_CASES, which pass their OWN synthetic `judged` + `exemptions` arrays and assert violations/stale/unnecessary counts on them — i.e. the witness-pair idiom PR #12050 had to retrofit onto check-driver-memory-census.mjs is NATIVE here, present since the mechanism was written. Only 6 DECLARATION cases read live module state (ROOTS, ROOT_WATCH_HINTS, SKIP_PATHS, SPEC_ROOT) plus one REPORT case that reads the file's own source text; and `renderFieldRuleSkips([]) === ''` is a case that literally pins the empty-list path on every invocation. CHANGESET: moot (no change). Had I changed the file it would be `skip-changeset`, not a real changeset: packages/lint/package.json declares `files: [dist, README.md, CHANGELOG.md]`, so `packages/lint/scripts/**` publishes nothing — it is a repo gate, not shipped output. #12055 (the packages/spec half) is OPEN, UNASSIGNED, with no branch and no PR; I touched nothing under packages/spec/**.",
 "tests": "All runs at origin/main 71e021425 (= worktree HEAD; the file is byte-identical to origin/main at the end — sha256 5e1b8c6c3e559f97e844ac5a29e4e574b4e2cff5016a281a63e4c0a3b45e7f3b on both sides, `git status --porcelain` empty). Exit codes captured by redirect-then-capture, never after a pipe. FIRST ATTEMPT DISCARDED, honestly: `pnpm --filter '@objectstack/lint^...' build` builds only the DEPS, so the gate hit its own prerequisite guard — `PREREQUISITE NOT MET — @objectstack/lint is not built ... Nothing was measured`. That exit 1 is not a finding and is not counted. After `pnpm --filter @objectstack/lint build` (VERDICT command-exit 0): BASELINE `pnpm --filter @objectstack/lint run check:doc-formula-expressions` -> os-verify-lock VERDICT command-exit 0; the gate's own verdict lines: `check:doc-formula-expressions self-test: 50 cases passed` / `22 record-scoped formula example(s) across 422 files / 1449 TS blocks judged clean` / `9 @example(s) judged clean across 1018 packages/spec/src files — rls-predicate=8, hook-record-condition=1, record-formula=0; 0 exempt.` / `14 predicate(s) ... judged clean; 6 skipped as undeterminable.` STEP 2 EXECUTED AS AN ABLATION, BOTH DIRECTIONS, with a `trap '<restore>' EXIT INT TERM` on the script. No rebuild is implicated for the mutation subject: the gate runs as `node scripts/check-doc-formula-expressions.mjs` directly from source, so the mutated file IS the executed file — there is no exports/dist indirection for the script (the dist of @objectstack/lint and @objectstack/formula WAS built first, and the prerequisite guard above is the proof it was needed). MUTATION CONFIRMED ON DISK by anchoring on the exact text, not by the editor's exit code — injected-marker grep -c AND deleted-text grep -c, both quoted per leg. (A) control, unmutated: exit 0, 50 green. (B) SHRINK-TO-EMPTY, the burn-down-succeeds simulation: `SKIP_PATHS = new Set([])`; on disk `ABLATED-EMPTY` count 1, `claude/worktrees'` count 0 -> self-test EXIT=0, `50 cases passed`, all six DECLARATION cases green. The self-test SURVIVES the list reaching zero — this is the direction the card is about, and it does not go red. (C) POSITIVE CONTROL, proving those cases are live rather than already vacuous: SKIP_PATHS gains `'packages/witness'` (a subtree under no ROOT); on disk `ABLATED-BADENTRY` count 1, `packages/witness` count 1 -> self-test EXIT=1 with exactly `x DECLARATION — every skipped subtree is one this declaration knowingly over-claims, and none is a surprise from outside the declared roots` and `x ... self-test: 1 case(s) failed`. So the pin has teeth on the GROWTH direction while tolerating shrinkage — which is precisely the post-repair shape PR #12050 had to construct, already present here. (D) RESTORE LEG, run rather than assumed: `grep -c ABLATED` = 0 on disk (the --absent direction), self-test EXIT=0, `50 cases passed`.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Reported, deliberately NOT filed as an issue

The two SKIP_PATHS DECLARATION cases are [...SKIP_PATHS].every(...) and [...SKIP_PATHS].some(...), so leg (B) above is green vacuously when the set is empty. I am naming this because it is the second-order concern Zone 1 ruling 2 is about — but I did not file it, and I think filing would be manufacturing work:

• SKIP_PATHS has no burn-down programme. It is a permanent carve-out, so there is no "moment of success" at which the vacuity would arrive unnoticed.
• Emptying it is not a silent event: the walker would immediately descend into .claude/worktrees (a full per-agent copy of the repo) and content/docs/references, so the scan counts move loudly in the same commit.
• The positive half of this declaration's claim is carried by cases 1-3 over ROOTS / ROOT_WATCH_HINTS, a population that never empties — so the vacuity is not load-bearing.

Flagging for PM judgment rather than acting on it unilaterally.

---

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui]

os-dev-report

(Re-posting the report of comment 5409874139: the sanitizer ate the HTML-comment marker on that one, so it is invisible to the PM scan. This copy leads with the literal text instead, per the os-dev contract. Comment editing is not available from this seat, so the earlier copy stands as-is — same content, unscannable header. Two <...>-shaped fragments inside it were also eaten and are respelled here.)

{
 "issue": 12056,
 "status": "done",
 "branch": "claude/issue-12056-doc-formula-selftest-shape (created off origin/main 71e021425, never pushed — no code change is owed; local worktree and branch removed)",
 "pr": null,
 "premise_still_valid": false,
 "summary": "VERDICT: packages/lint/scripts/check-doc-formula-expressions.mjs does NOT carry the self-test-pinned-to-the-debt shape. No code change; nothing pushed. STEP 0 — the 49 `exempt` hits resolve to exactly TWO mechanisms, and neither can produce the failure. (a) EXEMPT_EXAMPLES (:995) genuinely WAS a debt ledger: at #6763/PR #7180 it held exactly one entry, a real defect pending a cross-seat fix, whose own comment read `Delete this entry with that fix — leaving it behind is itself an error`. Shrink-only by construction (the gate errors on a `stale` entry matching no site AND on an `unnecessary` entry over a now-clean site). It is ALREADY AT ZERO on origin/main — emptied in afba4ec25 (#9223/PR #9247) — and the gate prints `0 exempt` and exits 0 today. The card's failure mode (`the last commit of the burn-down turns the gate's own self-test red`) therefore is not a prediction to evaluate: this ledger's moment of success already happened, in a landed commit, and the self-test stayed green through it. (b) SKIP_PATHS (:187) is a permanent principled carve-out — `.claude/worktrees` (per-agent repo copies the readdirSync walker would otherwise descend), `docs/{audits,handoff,plans}` (dated process records), `content/docs/references` (generated from the schemas by build-docs.ts). No burn-down programme, no expected empty state, so no moment of success for a self-test to break at. Nothing else in the file is a ledger: SPEC_EXAMPLE_SLOTS is a registry that must GROW (an entry matching no site is an error — the anti-SHRINK direction, the exact inverse of debt), and the field-rule skip list is computed per-run and never checked in, with a self-test case pinning that its trailer says `A skip is NOT a to-do item`. STEP 1 — answered affirmatively and in the strongest form: the self-test is entirely fixture-driven. Of 50 cases across 6 arrays, ZERO read EXEMPT_EXAMPLES. applyExemptions is exercised through EXEMPTION_SELF_TEST_CASES, which pass their OWN synthetic `judged` + `exemptions` arrays and assert violations/stale/unnecessary counts on them — i.e. the witness-pair idiom PR #12050 had to retrofit onto check-driver-memory-census.mjs is NATIVE here, present since the mechanism was written. Only 6 DECLARATION cases read live module state (ROOTS, ROOT_WATCH_HINTS, SKIP_PATHS, SPEC_ROOT) plus one REPORT case that reads the file's own source text; and `renderFieldRuleSkips([]) === ''` is a case that literally pins the empty-list path on every invocation. CHANGESET: moot (no change). Had I changed the file it would be `skip-changeset`, not a real changeset: packages/lint/package.json declares `files: [dist, README.md, CHANGELOG.md]`, so `packages/lint/scripts/**` publishes nothing — it is a repo gate, not shipped output. #12055 (the packages/spec half) is OPEN, UNASSIGNED, with no branch and no PR; I touched nothing under packages/spec/**.",
 "tests": "All runs at origin/main 71e021425 (= worktree HEAD; the file is byte-identical to origin/main at the end — sha256 5e1b8c6c3e559f97e844ac5a29e4e574b4e2cff5016a281a63e4c0a3b45e7f3b on both sides, `git status --porcelain` empty). Exit codes captured by redirect-then-capture, never after a pipe. FIRST ATTEMPT DISCARDED, honestly: `pnpm --filter '@objectstack/lint^...' build` builds only the DEPS, so the gate hit its own prerequisite guard — `PREREQUISITE NOT MET — @objectstack/lint is not built ... Nothing was measured`. That exit 1 is not a finding and is not counted. After `pnpm --filter @objectstack/lint build` (VERDICT command-exit 0): BASELINE `pnpm --filter @objectstack/lint run check:doc-formula-expressions` gave os-verify-lock VERDICT command-exit 0; the gate's own verdict lines: `check:doc-formula-expressions self-test: 50 cases passed` / `22 record-scoped formula example(s) across 422 files / 1449 TS blocks judged clean` / `9 @example(s) judged clean across 1018 packages/spec/src files — rls-predicate=8, hook-record-condition=1, record-formula=0; 0 exempt.` / `14 predicate(s) ... judged clean; 6 skipped as undeterminable.` STEP 2 EXECUTED AS AN ABLATION, BOTH DIRECTIONS, with a bash EXIT/INT/TERM trap restoring the script. No rebuild is implicated for the mutation subject: the gate runs as `node scripts/check-doc-formula-expressions.mjs` directly from source, so the mutated file IS the executed file — there is no exports/dist indirection for the script (the dist of @objectstack/lint and @objectstack/formula WAS built first, and the prerequisite guard above is the proof it was needed). MUTATION CONFIRMED ON DISK by anchoring on the exact text, not by the editor's exit code — injected-marker grep -c AND deleted-text grep -c, both quoted per leg. (A) control, unmutated: exit 0, 50 green. (B) SHRINK-TO-EMPTY, the burn-down-succeeds simulation: `SKIP_PATHS = new Set([])`; on disk `ABLATED-EMPTY` count 1, deleted-text `claude/worktrees` count 0 — self-test EXIT=0, `50 cases passed`, all six DECLARATION cases green. The self-test SURVIVES the list reaching zero — this is the direction the card is about, and it does not go red. (C) POSITIVE CONTROL, proving those cases are live rather than already vacuous: SKIP_PATHS gains `packages/witness` (a subtree under no ROOT); on disk `ABLATED-BADENTRY` count 1, `packages/witness` count 1 — self-test EXIT=1 with exactly `FAIL DECLARATION — every skipped subtree is one this declaration knowingly over-claims, and none is a surprise from outside the declared roots` and `FAIL ... self-test: 1 case(s) failed`. So the pin has teeth on the GROWTH direction while tolerating shrinkage — which is precisely the post-repair shape PR #12050 had to construct, already present here. (D) RESTORE LEG, run rather than assumed: `grep -c ABLATED` = 0 on disk (the --absent direction), self-test EXIT=0, `50 cases passed`.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Reported, deliberately NOT filed as an issue

The two SKIP_PATHS DECLARATION cases are [...SKIP_PATHS].every(...) and a negated [...SKIP_PATHS].some(...), so leg (B) above is green vacuously when the set is empty. I am naming this because it is the second-order concern Zone 1 ruling 2 is about — but I did not file it, and I think filing would be manufacturing work:

• SKIP_PATHS has no burn-down programme. It is a permanent carve-out, so there is no "moment of success" at which the vacuity would arrive unnoticed.
• Emptying it is not a silent event: the walker would immediately descend into .claude/worktrees (a full per-agent copy of the repo) and content/docs/references, so the scan counts move loudly in the same commit.
• The positive half of this declaration's claim is carried by cases 1-3 over ROOTS / ROOT_WATCH_HINTS, a population that never empties — so the vacuity is not load-bearing.

Flagging for PM judgment rather than acting on it unilaterally.

---

Generated by Claude Code

---

Generated by Claude Code