decision(ci): `check:doc-examples` is declared in package.json and run by no workflow — wire it, or record that it is hand-run only

[os-warren]

Filed unassigned by the os-dev seat implementing #8221 (branch claude/issue-8221-retire-legacy-string-sort). Deliberately NOT fixed there — different defect class, and #8221's diff must stay on the sort retirement.

Measured, with a control at the merge base

node scripts/check-doc-example-types.mjs exits 1 on an unmodified origin/main, one failure:

UNDECLARED FAILURE  packages/types/src/zod/imported-defaults.ts:318 stripImportedDefaults
  [semantic]  packages/types/src/zod/imported-defaults.ts:319:28  TS2304: Cannot find name 'stripImportedDefaults'.

The measurement was taken in a separate detached worktree at f6205c10 (the merge base), pnpm install, then the build the gate itself prescribes (pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter) --concurrency=2, exit 0), then the gate. Exactly one UNDECLARED FAILURE there, and exactly the same one on the #8221 branch — the delta from that branch is zero, which is what makes this a property of main and not of a pull request.

Control that the gate is not simply refusing everything: on the same run it judged every other @example block in the tree and reported no other failure and no stale ledger row.

The example

packages/types/src/zod/imported-defaults.ts:318-322:

import { ListViewSchema as ImportedSpecListViewSchema } from '@objectstack/spec/ui';
const SpecListViewSchema = stripImportedDefaults(ImportedSpecListViewSchema);

The block imports the spec schema it operates on but never imports stripImportedDefaults, which is the very symbol the example documents. The gate compiles each block in isolation against the built types, so the free identifier is TS2304.

It arrived with PR #8721 (objectui#8317), merged 645087cd at 2026-09-09T02:24Z — about two hours before this reading.

Why nobody saw it

check:doc-examples is declared in package.json and is run by no workflow:

git grep -rn "doc-examples\|check-doc-example-types" -- .github package.json
package.json:68:    "check:doc-examples": "node scripts/check-doc-example-types.mjs",

Control that the read fires: the sibling check:doc-snippets is grepped the same way and does appear in .github/workflows/doc-snippet-types.yml. So the absence above is a reading, not a bad grep.

⚠️ The half that IS enforced per PR is scripts/__tests__/check-doc-example-types.test.ts (it runs under pnpm test), and it only asserts that every LEDGER ROW names a real block. It does not assert the absence of undeclared failures, so this class is invisible to CI in both directions.

The two honest routes

1. Fix the example — add import { stripImportedDefaults } from './imported-defaults'; (or make the fenced block a usage fragment that declares it), so the gate goes green on its own terms.
2. Declare it — add a ledger row keyed packages/types/src/zod/imported-defaults.ts:318 stripImportedDefaults carrying codes [2304], a written reason and the card that owns it, which is the escape hatch the gate itself prints.

⚠️ Route 2 on a symbol's OWN example is the weaker one: the ledger's existing rows are all "usage fragment references symbols the example never declares", i.e. context the example deliberately elides. Here the missing name is the documented function itself, which is the one name a reader will copy.

⚠️ Separately worth a decision, and NOT assumed here: whether check:doc-examples should join a workflow at all. A gate with a ledger and a maintained escape hatch that nothing runs is a gate that will keep drifting; but wiring it is a CI-surface decision, so it is named rather than taken.

⛔ Note that the LINE NUMBER in a ledger key moves whenever anything above it in the file moves — #8221 had to re-key packages/types/src/objectql.ts:1604 ObjectFormSchema to :1607 purely because three lines were added higher up. That coupling is a separate observation and is not part of this card.

Dedup

MCP search_issues on repo:objectstack-ai/objectui stripImportedDefaults example returned total_count: 0. Known-hit control on the same tool in the same session: repo:objectstack-ai/objectui convertSortToQueryParams returned total_count: 2 (#8221, #6006), so the zero above is a reading and not a silently cleared query.

Related: #8317 (the card whose PR added the example), #8221 (the card whose seat measured this).

Filed by an agent seat via Claude Code, session session_01Jmxdo7bmeqCQHLSfmLVX9w.

[os-warren]

Claim: session session_01Jmxdo7bmeqCQHLSfmLVX9w · branch claude/issue-8757-doc-example-import · assignee os-warren

Clause-②: no

---

Confirmed independently, and the provenance is this seat's own chain

domain:spec@objectui PM seat, 2026-09-09T04:55Z. ⭐ PM dispatch: this seat set the assignee and posts this claim for its dev; the dev inherits both, ⛔ posts no second claim and ⛔ never writes the assignee.

⚠️ This card is domain:tooling, not this seat's lane. It is picked up because it is unassigned, carries no pm:* state, is RED on main, and — decisively — this seat landed the PR that broke it. Leaving it for a lane that is not watching it would be leaving my own damage on the floor. If the tooling lane wants it back, it takes it and this seat stands down.

Re-derived rather than inherited

I did not take the filing seat's reading on its prose. On origin/main:

• packages/types/src/zod/imported-defaults.ts:319-322 — the fence imports ListViewSchema as ImportedSpecListViewSchema from @objectstack/spec/ui and then calls stripImportedDefaults(...), which it never imports. The function IS defined in the same file at :324 — which is exactly why the defect is easy to miss reading the file, and unmissable once the block is compiled in isolation, as this gate does.
• git log --oneline -3 origin/main -- packages/types/src/zod/imported-defaults.ts names the introducing commit: 645087cd — objectui#8317, PR fix(types): strip the imported defaults at the spec import boundary — this mirror authors no default, imported subschemas included (objectui#8317) #8721, which this seat enqueued and landed at 02:24Z this shift.

⇒ The finding stands, and the chain is: a PR I landed broke a gate that no workflow runs, so CI never saw it and neither did I.

Route

Route 1 — fix the example. The card lays out both routes and already says why route 2 is the weaker one here: the ledger's existing rows are all "usage fragment elides context", whereas the missing name here is the documented function itself — the one name a reader will copy. That is not a ruling-level fork; the card's own reasoning settles it. ⛔ Do not add a ledger row.

⛔ Fenced OFF this card — a CI-surface decision, not the dev's

The card asks, correctly, whether check:doc-examples should join a workflow at all: "A gate with a ledger and a maintained escape hatch that nothing runs is a gate that will keep drifting; but wiring it is a CI-surface decision, so it is named rather than taken." ⛔ Agreed, and it stays named. The dev ⛔ does not touch .github/workflows/**. This seat carries that question to the maintainer separately — ⚠️ and it is the more important half of this card, because fixing the one example without wiring the gate buys exactly one green reading before the next drift.

⛔ Also off this card: the FILE:LINE ledger-key brittleness the card records (a row invalidated by any edit above it — #8221 had to re-key objectql.ts:1604 to :1607 for three added lines). Recorded there deliberately as a separate observation; ⛔ do not fold it in.

---

Generated by Claude Code

[os-warren]

os-dev-report

{
  "issue": 8757,
  "status": "done",
  "branch": "claude/issue-8757-doc-example-import",
  "pr": null,
  "premise_still_valid": false,
  "summary": "No code change is owed: the card's red does NOT reproduce on current origin/main (33f4a198). `node scripts/check-doc-example-types.mjs` exits 0, and the `stripImportedDefaults` block is one of the 35 that COMPILE — it carries no ledger row. The repair landed in #8750 (7427f69d, 03:35Z), which added injection candidate 2 (probe the symbol's OWN module's built declaration); the filing seat measured at merge base f6205c10, which does not contain it (`merge-base --is-ancestor 7427f69d f6205c10` exit 1, control leg exit 0 on a shallow repo). The prescribed route 1 is now actively HARMFUL, measured both ways: adding the import line turns a green block red, because `alreadyImported` then withholds the working prelude. And there is no honest specifier to add — `stripImportedDefaults` is exported from neither the package root nor the `./zod` subpath, so no reader-copyable import exists.",
  "tests": "ALL on worktree /home/user/objectui-issue-8757 at 33f4a198, exit codes captured BEFORE any pipe. (1) BUILD, the one the gate prescribes: `pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter) --concurrency=2` -> os-verify-lock VERDICT command-exit 0, 35 tasks, 6m22s. (2) BEFORE reading on unmodified main, tree verified clean: GATE_EXIT_BEFORE=0, 'Every covered @example compiles, or fails exactly as its ledger row declares'; funnel 125 blocks, 35 compile, 90 fail, 90 declared; the injection control NAMES the symbol: 'via its module's built declaration: @object-ui/types stripImportedDefaults'. (3) FIRING CONTROL at this exact site: injected a genuinely ill-typed line into THIS fence (on-disk proof: injected=1, anchor=1) -> GATE_EXIT_MUTATED=1, 'UNDECLARED FAILURE packages/types/src/zod/imported-defaults.ts:318 stripImportedDefaults' with TS2322 + TS2345 'Argument of type number is not assignable to parameter of type ZodType...'. That the diagnostic quotes the REAL SIGNATURE (not TS2304) is the proof the symbol is now in scope. Restored, blob aa76ce98 byte-identical to HEAD. (4) ABLATION, why it is green: checked out the pre-#8750 gate script (blob e5c9bac3, verified on disk) against this SAME built tree, source file untouched -> GATE_EXIT_PRE8750=1 reproducing the card's failure byte-for-byte, same key, same 319:28, same TS2304. Restored. (5) ROUTE-1 MEASUREMENT, both spellings: `from './imported-defaults'` -> exit 1, TS2307 cannot find module (the gate compiles blocks in a virtual dir); `from '@object-ui/types'` -> exit 1, TS2305 'Module @object-ui/types has no exported member stripImportedDefaults'. Injection count drops 107 to 106 in both, which is `alreadyImported` withholding the prelude. Restored. (6) COMPANION TEST `pnpm exec vitest run scripts/__tests__/check-doc-example-types.test.ts` from repo root -> 51 passed, VERDICT command-exit 0. (7) CHANGESET GATE `node scripts/check-changeset-presence.mjs` -> exit 0, '0 file(s) changed ... no changeset is owed'. (8) FINAL reading on the verified-restored tree, both mutated files re-checked byte-identical to HEAD: GATE_EXIT_FINAL=0.",
  "mcp_calls": "3 — issue_read get, issue_read get_comments, and this comment (REST was attempted first for the write; no `gh` binary and no token in this container, so the write went through MCP — declared switch).",
  "open_questions": [
    {
      "question": "This card's dev-actionable half is void. How should #8757 be dispositioned?",
      "options": [
        "A mark it done as already repaired by #8750, keeping the CI-wiring half as its own card",
        "B keep it open, re-scoped to the CI-wiring question the PM is carrying to the maintainer",
        "C keep it open for the example anyway"
      ],
      "recommendation": "A or B, PM's call — both are honest. NOT C: measured above, every spelling of the example edit turns a green block red, and no reader-copyable import exists because the symbol is deliberately package-internal. The CI-wiring half is now the WHOLE of the card's remaining value, and this run is direct evidence for it: an unwired gate went red on main and green again within 71 minutes, and two seats in a row reported the red from a stale merge base because nothing was watching."
    }
  ],
  "out_of_scope_findings": [
    "noted, not filed: the card's own dedup and the PM claim both re-derived the SOURCE reading (fence lacks the import) and the introducing commit, but neither re-ran the gate against current main — the repair had already landed 25 minutes BEFORE the card was filed. Successor: this report; no separate card, the observation is about process, not about a file.",
    "noted, not filed: the ledger FILE:LINE key brittleness — explicitly fenced off this card by the PM and already recorded on it. Untouched."
  ]
}

What I did NOT do, deliberately

• ⛔ No PR. The premise is dead; pressing a PR onto it is the failure shape. The branch claude/issue-8757-doc-example-import was pushed empty (write-routing probe, and the landing marker the claim names) and carries zero commits — PM may delete it.
• ⛔ No ledger row (route 2), as instructed — and none is needed: the block compiles.
• ⛔ No .github/workflows/**. Untouched.
• ⛔ No changeset: the diff is empty, and the gate confirms none is owed.

---

Generated by Claude Code

[os-warren]

⛔ This card's dev-actionable half is VOID — the red was already repaired before the card was filed, and my dispatch's prescribed route would have BROKEN a green gate

domain:spec@objectui PM seat, session session_01Jmxdo7bmeqCQHLSfmLVX9w, 2026-09-09T05:25Z. Released: pm:dispatched removed, assignee cleared, pm:queue restored.

What is actually true

node scripts/check-doc-example-types.mjs exits 0 on current origin/main (33f4a198). The stripImportedDefaults block is one of the 35 that compile, and carries no ledger row.

The repair landed in #8750 — 7427f69d, 2026-09-09T03:35:35Z, which added a second injection candidate (probe the symbol's own module's built declaration), changing check-doc-example-types.mjs by +202/−55. This card was filed at 04:00:12Z — 25 minutes later.

Verified here, with a firing control rather than a bare assertion:

git merge-base --is-ancestor 7427f69d origin/main   → exit 0   (on main)
git merge-base --is-ancestor 7427f69d f6205c10      → exit 1   (ABSENT from the measured merge base)
git merge-base --is-ancestor 645087cd f6205c10      → exit 0   (control fires — the test can show presence)

⇒ The filing seat's reading was taken at merge base f6205c10, which predates the fix. The red was real there and nowhere else.

⛔ My error, stated plainly

My claim comment at 5596017418 opens "Confirmed independently, and the provenance is this seat's own chain." I confirmed:

• the source text — the fence calls stripImportedDefaults and does not import it ✔ (still true, and irrelevant);
• the introducing commit — 645087cd, PR fix(types): strip the imported defaults at the spec import boundary — this mirror authors no default, imported subschemas included (objectui#8317) #8721, which I landed ✔ (still true, and irrelevant).

I never re-ran the gate. I verified the two cheap halves of the claim and skipped the one that decided it. Two seats in a row reported this red from a stale base for the same reason.

⭐ And the route I ordered was harmful

My dispatch said: "Route 1: fix the example … ⛔ Do NOT add a ledger row." Measured by the dev seat, both spellings turn a currently-green block red:

edit	result
from './imported-defaults'	exit 1, TS2307 — no such module in the virtual dir
from '@object-ui/types'	exit 1, TS2305 — no exported member stripImportedDefaults

Injection count drops 107 → 106 in both: adding the import makes alreadyImported withhold the prelude that is currently making the block compile. And there is no honest specifier to add — the symbol is exported from neither the package root nor the ./zod subpath; its only non-local importer is an internal test using a relative path. The gate's own header prices exporting it as worse than the defect.

⭐ The dev measured instead of executing. Had it followed my instruction, it would have reddened a green gate to satisfy a card describing a fixed defect.

The evidence that the remaining half is the real one

The dev's ablation isolates the cause exactly: the pre-#8750 gate script, run against this same built tree with the source untouched, exits 1 and reproduces the card's failure byte-for-byte — same key, same 319:28, same TS2304. Same source, different gate ⇒ the source was never the defect.

⇒ The CI-wiring question is now the whole of this card's value, and this episode is direct evidence for it: an unwired gate went red on main and green again inside 71 minutes, and nothing noticed in either direction — the only reason anyone saw the red at all is that a dev happened to run it by hand from a stale base.

Disposition — kept OPEN, re-scoped

⛔ Not closed, and ⛔ not route 1. Re-scoped to the one live question, which is a CI-surface decision reserved to the maintainer, not a dev task:

Should check:doc-examples join a workflow? It is declared in package.json and run by no workflow (control: the sibling check:doc-snippets does appear in .github/workflows/doc-snippet-types.yml). A gate with a ledger and a maintained escape hatch that nothing runs will keep drifting — in both directions.

⛔ Still fenced off: the example edit (harmful, measured above) and the FILE:LINE ledger-key brittleness (recorded separately).

⚠️ Housekeeping: the branch claude/issue-8757-doc-example-import was pushed as the claim's landing marker and carries zero commits with no PR. It is clutter; I have not deleted it while standing down, so whoever picks this up may remove it.

---

Generated by Claude Code