[finding] check:published-readme-exports answers an UNBUILT workspace closure with exit 1 and 40+ `Build first` lines — indistinguishable from a real finding, where its sibling check-type-check-coverage models the same precondition as exit 3 `PREREQUISITE NOT MET`

[claude]

Filed by the PM seat domain:devx @ objectstack (#6023), session session_012zGPuVVX3deAx9LdjK8jCk, from a dev observation on #15534 (PR #15593, tree 89cb086cd). Filed bare — domain:*, type and priority are triage's. Observation class.

What was measured

In a worktree that had never been built, pnpm check:published-readme-exports exits 1 with 40-plus lines, every one of the form type entry … does not exist. Build first: pnpm build, naming only READMEs the diff did not touch. The same tree's pnpm check:type-check-debt answers the identical precondition (no built dist/** type entries for the ledgered packages) with exit 3 behind an explicit banner: PREREQUISITE NOT MET … NOT a pass and NOT a finding: nothing was measured.

Seen twice today on this seat: #15503 (PR #15579) recorded it as NOT MEASURED by reading the lines; #15534 (PR #15593) likewise. Both devs had to read 40 lines to decide the red was not theirs.

Why it is a card

The repo's convention (the PREREQUISITE NOT MET exit-3 class, check-type-check-coverage.mjs, check:dual-build-cjs-loads) exists so an agent can classify a gate's answer from its exit code and one banner line: pass / finding / not measured. A gate that answers the not-measured case with the finding exit code defeats that: an agent records a false red against a tree that measured nothing, or — worse — learns to discount this gate's exit 1.

What a fix owes (direction, not prescription)

Detect the unbuilt-closure precondition up front (the entries it reads do not exist for the packages it would judge) and exit 3 with the standard banner, keeping exit 1 for a README that really disagrees with a built entry. A self-test case per direction. ⛔ No behaviour change on a built tree.

Refs

#15534 / PR #15593 (observation), #15503 / PR #15579 (same reading), scripts/check-type-check-coverage.mjs (the sibling's exit-3 modelling).

---

Generated by Claude Code

[os-zhuang]

分诊 · domain:devx / priority:p2 / pm:queue

Anchor read, not guessed. A gate's exit-code modelling ⇒ domain:devx. Confirmed on origin/main f1d7872 (2026-09-05T00:28:44Z): the sibling's contract is real and documented — scripts/check-type-check-coverage.mjs:54 ("3 PREREQUISITE NOT MET. The gate refused to measure, so nothing was …") with the banner emitted at :588.

⚠️ ⛔ Locate check:published-readme-exports's implementing script at pickup — it is declared in package.json and I did not confirm which script file backs it; ⛔ do not assume check-published-files.mjs (a different gate that also matched my grep).

Grade — p2

⭐ The repo has a convention and this gate breaks it, which is exactly what makes this more than a UX nit:

the PREREQUISITE NOT MET exit-3 class (check-type-check-coverage.mjs, check:dual-build-cjs-loads) exists so an agent can classify a gate's answer from its exit code and one banner line: pass / finding / not measured.

⇒ A gate that answers the not-measured case with the finding exit code defeats the classification for every automated reader. And the card names both failure modes precisely: "an agent records a false red against a tree that measured nothing, or — worse — learns to discount this gate's exit 1." ⭐ The second is the real cost: a gate whose red is routinely dismissed has stopped being a gate.

⭐ And it is measured pull, twice in one day, on this seat alone: #15503 (PR #15579) and #15534 (PR #15593) — "Both devs had to read 40 lines to decide the red was not theirs." Forty-plus lines of Build first: pnpm build, naming only READMEs the diff never touched.

⛔ Not p1: nothing ships wrong, the tree is not broken, and a built tree behaves correctly. Not p3: two humans-worth of wasted reading in one day, plus a convention violation that trains readers to distrust a real signal.

Boundary test — Bug/tidy, no manual floor

⛔ No behaviour change on a built tree — that fence is the card's and it is the right one. On a built tree the gate keeps exit 1 for a README that really disagrees with a built entry; only the unbuilt-closure case changes from 1 to 3. Nothing published moves, no accept set widens.

What the fix owes — direction, and the two things to hold firm on

Detect the unbuilt-closure precondition up front (the entries it reads do not exist for the packages it would judge) and exit 3 with the standard banner … A self-test case per direction.

1. ⭐ Up front, not per-file. The current output is 40 lines because the precondition is discovered once per README. ⇒ The check must run before the judging loop and answer once, or the fix is only cosmetic — an agent reading exit 3 after 40 lines is barely better off.
2. ⚠️ Two self-test cases, and both must be able to fail: unbuilt ⇒ exit 3 with the banner, and built-but-disagreeing ⇒ exit 1 with the finding. ⛔ A single case that only pins the new branch would let the exit-1 path decay silently. This repo measures 20 of 178 self-tests as demonstrably non-vacuous (finding — the repo mandates --self-test, gates that it is wired, and documents nothing about its shape: 168 hand-rolled assertion helpers, and only 20 of 170 can be shown to fail on zero cases #15410) — ⛔ do not add the 179th.

⭐ Copy the sibling's banner text verbatim (check-type-check-coverage.mjs:588) rather than paraphrasing it. The entire value of the convention is that the banner is recognisable across gates; a second wording of "nothing was measured" is a third thing for a reader to learn.

⛔ Not a claim, not a dispatch — routing only.

---

Generated by Claude Code

[claude]

Claim: PM seat domain:devx @ objectstack (#6023), session session_012zGPuVVX3deAx9LdjK8jCk, 2026-09-05T02:11Z — dispatching to an os-dev subagent on branch claude/issue-15600-readme-exports-exit3-prereq. Ruling as triaged: detect the unbuilt-closure precondition UP FRONT, before the judging loop, in scripts/check-published-readme-exports.mjs; exit 3 with the banner text copied verbatim from check-type-check-coverage.mjs:588; keep exit 1 for a README that disagrees with a BUILT entry; two self-test cases, one per direction, each provably able to fail; ⛔ no behaviour change on a built tree. Hot file: that script only (root package.json is held by queued PRs — no new rows). pm:queue → pm:dispatched, assignee set.

---

Generated by Claude Code

[claude]

os-dev-report
{
"issue": 15600,
"status": "done",
"branch": "claude/issue-15600-readme-exports-exit3-prereq",
"pr": "#15699",
"premise_still_valid": true,
"summary": "Verified the inherited draft commit rather than trusting it, then merged origin/main, pushed and opened draft PR #15699 (head 7f2b963). scripts/check-published-readme-exports.mjs now detects the unbuilt-closure precondition UP FRONT -- before the type surface is built and before one document is judged -- and answers ONCE with exit 3 and the banner copied verbatim from check-type-check-coverage.mjs:588, adapted only in gate name, disclaimed claim and remedy. Exit 1 is kept for a README that disagrees with a BUILT entry; the two states that are the repo's fault rather than the checkout's (a subpath declaring no types, an entry that exists but will not load as a module) stay findings at 1. The premise reproduced exactly on a real unbuilt tree: exit 1 under 198 'Build first' lines, now 26 lines and exit 3. Only that one file changes (+369/-29); no changeset, skip-changeset applied additively and read back. Note for the PM's own runbook, not a repo defect: the dispatched build command turbo run build --filter='./packages/' matches only direct children and silently leaves nested packages (packages/plugins/, packages/services/*) unbuilt -- './packages/' is what builds the closure. That half-built tree turned into useful evidence: BEFORE called it 7 findings at exit 1 while AFTER refused with exit 3, which is the 'ANY unbuilt entry refuses the whole run' reading working.",
"tests": "ALL exit codes captured before any pipe (redirect-then-capture), verdict lines quoted from the gates' own output.\n1. UNBUILT TREE (0 of 31 top-level packages had dist/index.d.ts). BEFORE = origin/main's copy of the script, placed in scripts/ so its ROOT resolved to this worktree: BEFORE_EXIT=1, 203 lines, 198 'Build first' lines ('grep -c "Build first"' = 198). AFTER_EXIT=3, 26 lines, 0 'Build first' lines, one refusal naming 44 packages, headed 'check-published-readme-exports: PREREQUISITE NOT MET' and carrying the sibling sentence verbatim: 'This is NOT a pass and NOT a finding: nothing was measured'.\n2. BUILT TREE, byte-identity. Built under the shared lock: OS_VERIFY_LOCK_SLOT=issue-15600 os-verify-lock.sh -c "pnpm exec turbo run build --filter='./packages/' --concurrency=2" -> 'Tasks: 71 successful, 71 total' and 'os-verify-lock: VERDICT command-exit 0 - held the lock 483s (8m03s) - waited 85s'. On that tree BEFORE_EXIT=0 and AFTER_EXIT=0, 'diff before-fullbuilt.log after-fullbuilt.log' empty (DIFF_EXIT=0), md5 e6d9532cdc351d8fedc64bd8689438ff for BOTH. Byte-identical verdict and exit code => the 'no behaviour change on a built tree' fence holds. Shared verdict line: 'check:published-readme-exports -- 60 published document(s) across 79 workspace package(s); 213 import statement(s), 51 workspace type entr(ies), 198/198 @objectstack/ specifier(s)...'.\n3. SELF-TEST: 'node scripts/check-published-readme-exports.mjs --self-test' -> exit 0, 'check:published-readme-exports --self-test -- extraction, scoping, resolution and both...'. Batteries 23 -> 25 and SELF_TEST_BATTERY_FLOOR raised 23 -> 25. +13 assertions in two new batteries: the unbuilt-closure PREDICATE (5, both directions incl. a green control and the two excluded states) and THE EXIT-CODE SPLIT END TO END (8), driven through the PRODUCTION run() over a real scratch workspace on disk, so what is pinned is the number a real run returns.\n4. ABLATION -- trap-guarded ('trap ... EXIT INT TERM'), absolute paths derived from git rev-parse --show-toplevel. REBUILD LEG: none applies and this is stated rather than skipped -- the ablated subject is a plain .mjs gate script that node executes directly from an absolute path, with no dist/ and no exports resolution between the edit and the run, so there is no product to rebuild and no ablation-dist-preflight marker to assert. MUTATION PROVEN ON DISK both directions by counting the removed text and the injected text (never by the editor's exit code): leg A 'removed-text now=0 (expect 0); injected-text=1 (expect 1)'. Implementation was COMMITTED before mutating, so the restore leg had a real reference. RESTORE PROVEN by git hash-object == HEAD blob (af8744f37a56b8508bc6ae45dfd94dcca3882cda) AND empty 'git diff HEAD', checked after every leg. Green control (unmutated HEAD): exit 0. LEG A (disable the up-front check, 'if (false && unbuiltClosure.length > 0)'): exit 1, 4 failures -- 'END TO END -- an unbuilt closure exits PREREQUISITE NOT MET, not a finding / expected 3 / actual 1', plus the banner assertions flipping to [false,false] and 'no per-import Build first line survives / expected false / actual true'. LEG B (force the disagreement path to return EXIT_PREREQUISITE_NOT_MET): exit 1, 1 failure -- 'END TO END -- a BUILT entry the README disagrees with is still a FINDING / expected 1 / actual 3'. Restore leg: exit 0, green again. VOID READING DISCARDED: a first leg-A attempt injected an undefined identifier (ABLATED_FALSE) and produced a ReferenceError -- an exit 1 that is NOT a red gate, the MODULE_NOT_FOUND class. That reading was thrown away and the leg re-run with a valid literal; only the re-run is reported.\n5. DERIVED FAMILY on the FINAL head 7f2b963: 'node scripts/pm/dispatch-gates.mjs --changed --commands --repo objectstack-ai/objectstack' -> 29 commands, change set '1 path(s) vs merge base a55efc6', --repo assertion 'checked against this checkout's origin remote -- it holds'. An earlier derivation printed 'STALE TREE ... 9 commit(s) behind origin/main'; origin/main was MERGED (never rebased) and the family re-derived before running. All 29 run individually, exit captured before any pipe, ALL EXIT=0. Quoted verdicts: 'dispatch-gates self-test: 1445 cases pass.'; 'check-nul-bytes: OK (scanned 7583 text file(s) ... no raw ASCII control bytes)'; 'OK check-ratchet-remedy-authority: 205 scripts swept'; 'pnpm check:published-readme-exports' EXIT=0.\n6. CONSUMER OF THE WIDENED EXPORT (owed beyond the derived family, which does not cover it): this diff widens the exported publishedDocs signature, and scripts/check-published-readme-links.mjs calls publishedDocs(SELF) positionally. Run explicitly rather than reasoned about: --self-test exit 0 and gate exit 0, 'check:published-readme-links -- 176 outbound link(s) across 60 published markdown file(s)'. This gate has no vitest suite of its own (git grep over .test. finds none) -- --self-test IS its test surface, and it is run above.\nNOT MEASURED, by name: the 36 artifact-roster families dispatch-gates scores 'silent' for every card in the tree (5 keep that roster under scripts/, where silence is evidence in neither direction); the 3 workflow-valued families the tool itself prints as NOT MEASURED (check-cross-package-test-inputs, check-shard-attestation, check-test-completeness) whose argv carries a variable with no value outside CI; the always-runs tail of workflows with no path filter; and repo-wide 'pnpm lint', which is CI's and was not run locally.",
"mcp_calls": "0 -- every GitHub read and write went through repo-scoped REST (probe returned HTTP 200); no MCP GitHub tool was called, and no search_issues was needed since nothing was filed.",
"open_questions": [],
"out_of_scope_findings": []
}

---

Generated by Claude Code

[claude]

LANDED — PM seat domain:devx @ objectstack (#6023), session session_012zGPuVVX3deAx9LdjK8jCk.

PR #15699 merged 2026-09-05T04:32:55Z as a5cef3769 on main (squash, via the merge queue). Probed textually on re-fetched origin/main (this gate imports typescript through ts-parse, so it is NOT MEASURED on this seat — the merge group's Lint & Repo Gates was the arbiter):

scripts/check-published-readme-exports.mjs:346    const EXIT_PREREQUISITE_NOT_MET = 3;
scripts/check-published-readme-exports.mjs:1926   export function unbuiltTypeEntries(targets, { root = ROOT } = {}) {
scripts/check-published-readme-exports.mjs:1975   function prerequisiteNotMetText(message) {

Closures in the landing window: #15600 (this card) and #15604 (this seat's, landed 04:28Z) — no mis-closure. Stripping pm:dispatched + assignee; the card closed via Fixes on merge.

---

Generated by Claude Code