[finding] content/docs/api/client-sdk.mdx — the most SDK-dense page in the docs — has 13 TypeScript fences and 0 os:check markers, so none of them is ever compiled

Blocked-by: #12048

⚠️ State as of 2026-08-25T06:5xZ (devx seat, session_01UjM2ia8Av1v5NqfqQEQmC6). The page-level half of this card is delivered in PR #12045 (Part of, not Fixes — deliberately). What is left is not this lane's to fix.

Measured on the dispatch: this page cannot be opted in at all. All 13 fences were marked, the gate run, the tree reverted — 128 diagnostics, not one a doc-vs-SDK divergence. Three are a surface-resolution gap (content/docs/** sits in a surface that cannot resolve @objectstack/client); ten are deliberate continuation fragments sharing Quick Start's client. Triage's binding scope sentence — "each red is a real doc-vs-SDK divergence, not a marker problem" — is falsified. Full review: comment 5406662596.

Restart-when: #12048 lands (the docs surface can resolve @objectstack/client).
Unlock-action: re-run the marking exercise on this page; the reds that remain will then be the real divergences this card was filed to catch. The in-page note PR #12045 adds names the same condition, so the next agent reads the answer instead of re-deriving it.

⚠️ Also spun off: #12051 — one JSX block fenced typescript silently disables the semantic pass for all 227 marked examples while the gate reports green. PR #12045 retags the one known instance; the class is unswept.

⚠️ This body carries sanitizer damage, found by the dev. The sentence below beginning "The operative word is marked" contains an empty backtick pair where the marker's spelling used to be — GitHub's body sanitizer ate it, backticks notwithstanding. Take the spelling from the tree, not from here: the docs/MDX root uses an MDX comment ({/* … */}) because MDX has no HTML comments; only the skills/.md and TSDoc roots use the angle-comment form. ⛔ Copying the angle form into .mdx breaks the docs build outright.

Found while verifying the docs-drift advisory on PR #11929 (#8140). Observation class: the gate
works exactly as designed — this is about its opt-in coverage, not a defect in it. ⛔ No gate was
built or changed on that PR.

Measured at 65c2b2a43.

What happened, concretely

#8140 narrowed 51 client SDK return types. Two TypeScript examples in
content/docs/api/client-sdk.mdx were falsified by that change and would not compile:

error TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
   -> client-sdk.mdx:404   run.runId passed to resume(flowName: string, runId: string)
error TS2345: Argument of type 'unknown' is not assignable to parameter of type 'string'.
   -> client-sdk.mdx:441   suggestions[0].id passed to confirm(id: string)

Both were fixed on that PR. CI would not have caught either, and the reason is not that the
repo lacks the instrument — it has a good one.

The instrument exists and is genuinely strong

pnpm --filter @objectstack/spec check:skill-examples type-checks prose TypeScript across three
surfaces, content/docs/** among them, and it is not shallow — it resolves real workspace types,
refuses to run against an unbuilt dist rather than scoring a false green (#7122), and carries a
substantial self-test. On 65c2b2a43 it reports:

256 marked example(s) across 99 file(s), 3 surface(s)
✅ 256 prose examples type-check across 3 surface(s)

The operative word is marked: a block is compiled only when an `` comment sits
on the line directly above it. That opt-in is a deliberate, sound design — it lets a page carry
deliberately-partial illustrations without the gate choking on them.

The coverage gap, measured

$ python3 - <<'PY'   # hand-written pages only; content/docs/references (generated) excluded
... counts top-level ```ts/```tsx/```typescript fences and os:check markers per page ...
PY
hand-written content/docs pages with a ts/tsx fence : 137
  total top-level ts/tsx/typescript fences          : 871
  total os:check markers                            : 192
  pages with fences but ZERO markers                : 59

So roughly a fifth of the fenced examples are marked, and 59 pages have fences but not one
marker. The heaviest:

fences	page
50	`content/docs/data-modeling/field-types.mdx`
17	`content/docs/kernel/contracts/metadata-service.mdx`
13	`content/docs/kernel/cluster.mdx`
13	`content/docs/data-modeling/seed-data.mdx`
13	`content/docs/api/client-sdk.mdx`
11	`content/docs/data-modeling/drivers.mdx`

⭐ client-sdk.mdx is the sharp end of this. It is the page a customer opens to learn the SDK,
its single largest fence contains 15 live SDK call sites, and it is exactly the page a change to
packages/client is most likely to falsify — which is what just happened. It has zero markers.

Why this is worth recording rather than shrugging at

The docs-drift advisory on #11929 did its job: it named the 9 pages mentioning ObjectStackClient.
But an advisory is a prompt to a human, and it cannot distinguish "prose that is still true"
from "a fence that no longer compiles" — it flagged 9 pages of which 8 were noise and 1 was real.
The gate can make that distinction mechanically, on exactly the pages that opt in.

⚠️ Being explicit about the limit of this finding: an unmarked block is not evidence of rot. Many
are pseudo-code, partial snippets, or non-TypeScript-in-a-ts-fence, and marking those would be wrong.
The claim here is narrower: nobody has decided, page by page, which side of that line each block is
on — and on the SDK's own reference page the answer was never recorded, so a real break shipped
past CI.

Suggested shape (for whoever grades this — not a plan)

Do not mass-mark. That is the Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 failure mode in another costume: markers added in bulk to
blocks nobody verified would either fail loudly on day one or, worse, be "fixed" by editing correct
documentation to satisfy a compiler.
Start with client-sdk.mdx. One page, 13 fences, highest customer value, and it has a
demonstrated break. Marking its examples one at a time — fixing or deliberately leaving each —
is a bounded, checkable piece of work.
A per-page ratchet ("a page that has any marker must have all its ts fences marked") would keep a
page from regressing once converted, without demanding the whole corpus at once.

Related: #8140 (the narrowing that surfaced this), PR #11929 (where the two examples were fixed).

Generated by Claude Code

Triage routing: domain:devx — lands in content/docs/api/client-sdk.mdx (docs face). Awaits first-touch grading.

Generated by Claude Code

Concentrated triage batch (grading the earlier routing): finding → pm:queue, Task, M (domain:devx stands) — the most SDK-dense docs page has 13 TypeScript fences and 0 os:check markers, and #8140 measurably falsified two of them with CI silent (both fixed on its PR). Scope: opt the page's fences into the existing instrument (add markers), compile, and repair whatever reds honestly — each red is a real doc-vs-SDK divergence, not a marker problem. Serial: after #8140's PR (#11929) merges, so the fences compile against the narrowed types they document.

Generated by Claude Code

Claim: devx PM seat, session session_015ahemw8RcTgqtxrj15PEZx, branch claude/issue-11942-client-sdk-oscheck-markers.

Dispatching now. Label swapped pm:queue → pm:dispatched.

Generated by Claude Code

Claim released — pm:dispatched → pm:queue, assignee cleared. This card is free to take.

The dispatch at 05:05Z was killed by a container restart ~14 minutes in. Verified by content: branch claude/issue-11942-client-sdk-oscheck-markers exists on origin but is 0 commits ahead of main, and its worktree is clean. Nothing was implemented — start from the card, not from the branch.

⚠️ One thing worth carrying forward, because it cost a check to establish: the serial precondition is satisfied. Triage gated this card on #8140's PR landing first. PR #11929 landed at 7899f5745 (verified on origin/main with a positive and a negative control), so the fences now compile against the narrowed return types and this card is dispatchable with no wait.

Generated by Claude Code

Claim: PM loop round R1
Session: session_01UjM2ia8Av1v5NqfqQEQmC6
Branch: claude/issue-11942-client-sdk-oscheck-markers
Worktree: objectstack-issue-11942
Domain: domain:devx
File surface: content/docs/api/client-sdk.mdx (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — derived live this round: node scripts/pm/dispatch-gates.mjs --tier content/docs/api/client-sdk.mdx → "no path-derived mandate: the surface hits none of the 3 declared glob(s)", so sonnet is the floor and opus is a deliberate judgment call: deciding which fences are real examples and which reds are genuine doc-vs-SDK divergences is the whole product here.
Clause-②: no
Serial constraints cleared: triage's precondition (#8140's PR #11929 must land first) was verified satisfied by the previous session at 7899f5745 with positive and negative controls — no wait. No in-flight card in this lane touches content/docs/**: the one live dev (#11525 / PR #12030) is confined to scripts/, lint.yml and root package.json. The eight other pm:dispatched cards are all governed-surface drafts parked for human merge, none under content/docs/.

Re-claim after a container death, not a fresh dispatch

The previous session claimed this at 05:04Z and released it at 05:24Z: its dev was killed by a container restart ~14 minutes in, and the release was verified by content — the branch exists on origin but is 0 commits ahead of main with a clean worktree. ⇒ Nothing was implemented. Start from the card, not from the branch.

Taking the same branch name back deliberately, since it is empty.

Generated by Claude Code

docs(api): record the os:check decision for client-sdk.mdx, and fence…

{
  "issue": 11942,
  "status": "needs_decision",
  "branch": "claude/issue-11942-client-sdk-oscheck-markers",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/12045",
  "premise_still_valid": false,
  "markers_added": 0,
  "fences_measured": 13,
  "files_changed": ["content/docs/api/client-sdk.mdx"],
  "summary": "Re-measured on today's origin/main (1e79aa4f8): 13 typescript fences, 0 markers — the card's count still holds after #11929. Marked all 13, ran the gate, reverted: 128 diagnostics and NOT ONE is a doc-vs-SDK divergence, which falsifies triage's binding scope sentence ('each red is a real doc-vs-SDK divergence, not a marker problem'). Two structural causes, neither fixable on this page: content/docs/** belongs to check:skill-examples' 'skills + docs (@objectstack/spec)' surface whose paths map derives from @objectstack/spec alone, and spec does not depend on @objectstack/client (3 fences red TS2307); the other 10 are deliberate continuation fragments sharing Quick Start's `client` (93x TS2304 + TS18004/TS18046/TS2591/TS7006). Delivered instead: the page-by-page decision recorded in-page (the issue's own stated defect), plus a retag of the JSX fence that removes a measured whole-surface blackout.",
  "premise_falsification_evidence": {
    "control": "marked the most self-contained fence on the page (a pure createFilter() builder chain, unambiguously correct SDK code)",
    "result": "content/docs/api/client-sdk.mdx:485:30 error TS2307: Cannot find module '@objectstack/client' or its corresponding type declarations.",
    "class": "surface-resolution gap, not doc rot",
    "root_cause": "packages/spec/scripts/check-skill-examples.ts SURFACES: docs root sits in the spec surface (selfPackages=[packages/spec], resolutionDir=packages/spec); neither packages/spec/node_modules/@objectstack/ nor root node_modules/@objectstack/ exists",
    "in_tree_corroboration": "content/docs/kernel/runtime-services/data-service.mdx already records this identical constraint and leaves its own SDK block deliberately unmarked",
    "out_of_bounds": "the real fix is editing the gate's SURFACES config — forbidden by dispatch rule 3"
  },
  "trap1_measurement": {
    "claim": "one JSX fence tagged `typescript` suppresses the semantic pass for the whole skills+docs surface (227 marked blocks), not just this page",
    "runs": [
      {"marked": 12, "react_fence": "typescript", "syntax_errors": 0, "semantic_diagnostics": 118},
      {"marked": 13, "react_fence": "typescript", "syntax_errors": 14, "semantic_diagnostics": 0},
      {"marked": 13, "react_fence": "tsx", "syntax_errors": 0, "semantic_diagnostics": 128}
    ],
    "fix_shipped": "retagged the React Hooks fence typescript -> tsx (it IS JSX); check-doc-authoring.mjs FENCE_OPEN accepts tsx so the block stays visible to that gate"
  },
  "tests": "Verified at final commit c84df2983. Baseline == final, unchanged as intended (this PR adds no markers): '256 marked example(s) across 99 file(s), 3 surface(s)' / 'OK 256 prose examples type-check across 3 surface(s)'. Gate families derived by `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no hand-written path list; script confirmed repo match against origin) -> 20 families; ran all 20 plus check:nul-bytes and check:skill-examples = 22/22 EXIT=0, each exit code captured before any pipe (cmd > log 2>&1; EXIT=$?). MDX parse proven by compiling the page with the workspace's own @mdx-js/mdx@3.1.1 (COMPILE OK, 53496 bytes) — fumadocs-mdx regenerate also exit 0. Every mutation run carried a trap '<restore>' EXIT INT TERM; marker count on disk asserted before each run (12/1/13/13) and `git status --porcelain` confirmed empty after.",
  "gates": [
    {"gate": "check:doc-authoring", "exit": 0, "verdict": "doc authoring guard: 389 files clean — no bare metadata literals."},
    {"gate": "check:doc-anchors", "exit": 0, "verdict": "check-doc-anchors: 278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading"},
    {"gate": "check-doc-frontmatter.mjs", "exit": 0, "verdict": "check-doc-frontmatter: 2 content root(s) verified, each against its own floor — content/docs 403, content/blog 3."},
    {"gate": "check:docs-audit-scope", "exit": 0, "verdict": "docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s)."},
    {"gate": "check-doc-route-spelling.mjs", "exit": 0, "verdict": "route-spelling guard: population clean — every shape-matched literal spells its ledger row."},
    {"gate": "check:nul-bytes", "exit": 0, "verdict": "check-nul-bytes --self-test: 75 assertions over a temp git repo (real scan() path)"},
    {"gate": "check:skill-examples", "exit": 0, "verdict": "256 prose examples type-check across 3 surface(s)"},
    {"gate": "check:cross-package-test-inputs / check:doc-formula-expressions / check:doc-security-posture / check:docs-redirects / check:empty-state / check:liveness / check:published-readme-links / check:react-page-adapter-contract / check:role-word / check:strictness-ledger / check:variant-docs / check-ci-filter-parity.mjs / check-cross-package-test-inputs.mjs / check-docs-section-name.mjs / check-section-landing-index.mjs", "exit": 0, "verdict": "all EXIT=0"}
  ],
  "deviations": [
    "PR body first line is 'Part of #11942', NOT the dispatched 'Fixes #11942'. Deliberate: the card is not discharged (0 markers were achievable), and a closing keyword would silently close it on merge while the real blocker still needs a decision. Standing clause: prompt-vs-AGENTS conflict resolves to the file, conflict reported here.",
    "skip-changeset applied via read -> union -> whole-set write (MCP issue_write) because the additive REST endpoint POST /issues/12045/labels returned HTTP 403 from this seat ('GitHub access is not enabled for this session'); raw curl to api.github.com is unavailable here for both list and write. Read-back confirms union preserved: [documentation, size/s, skip-changeset].",
    "Bounded in-place fix beyond 'add markers': retagged one fence typescript -> tsx. Same defect class (fence opt-in), mechanically correct (the block IS JSX), no other claim on the file, same gate family. Justification is the measured trap-1 blackout above; named with evidence in the PR body as the exemption requires.",
    "Issue body carries sanitizer damage — see sanitizer_finding."
  ],
  "sanitizer_finding": "CONFIRMED in the issue body. The sentence 'a block is compiled only when an `` comment sits on the line directly above it' has an EMPTY backtick pair: the marker spelling was eaten by the GitHub body sanitizer, backticks notwithstanding (it is a short less-than fragment). The card's central term is therefore missing from its own body. Spelling taken from the tree instead: the docs/MDX root uses {/* os:check */} (MDX has no HTML comments); only the skills/.md and TSDoc roots use the angle-comment form. PM's Zone 2 assumption 'marker is a comment on the line directly above the fence' is CORRECT, but the spelling differs per root — an agent copying the angle form into .mdx would break the docs build outright.",
  "open_questions": [
    {
      "question": "content/docs/api/client-sdk.mdx cannot be opted into check:skill-examples at all: its surface cannot resolve @objectstack/client. Fixing that means editing the gate, which this card forbids. Which way?",
      "options": [
        "A — add @objectstack/client (+ client-react + react types) to the 'skills + docs' surface's selfPackages, so any docs page may import the SDK.",
        "B — accept the page as permanently unmarkable; rely on the recorded in-page note (what PR #12045 ships).",
        "C — give the EXISTING 'client SDK' surface a docs root scoped to SDK pages. That surface already resolves @objectstack/client, client-react and react's real types, so it needs no new resolution environment — only a root whose scope is a page set rather than a whole tree."
      ],
      "recommendation": "C, then B as the interim. Four axes: (1) REAL BUSINESS NEED — measured, not speculative: #8140 falsified two examples on this exact page and CI was silent; this is the page a customer opens to learn the SDK, so the need is demonstrated rather than imagined. (2) LONG-TERM SOUNDNESS — C reuses a resolution environment that already exists and is already exercised by 19 blocks, so it adds no second way to resolve the same packages; A widens the spec surface to carry packages spec does not depend on, which inverts the dependency direction the surface exists to model and would let any docs page silently acquire the SDK. (3) HARD TO GET WRONG — C is the only option that makes the SDK reference page's examples compile against the real declarations, which is exactly where an AI copies code verbatim; B leaves that page structurally unverifiable forever, and its note is a comment an author can ignore. (4) STARTUP SCOPE DISCIPLINE — C is a SourceRoot scoping change plus one entry, not a new surface or new extraction code; the gate's own header states adding a surface is 'a new SURFACES entry, not a fork', and C is smaller than that. The one genuine cost is that SourceRoot.dir is a directory today, so C needs per-page scoping — a real design question, which is why this is escalated rather than guessed. Interim B is already shipped, so nothing regresses while this is decided."
    }
  ],
  "out_of_scope_findings": []
}

Generated by Claude Code

os-dev-report

{
  "issue": 11942,
  "status": "needs_decision",
  "branch": "claude/issue-11942-client-sdk-oscheck-markers",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/12045",
  "premise_still_valid": false,
  "markers_added": 0,
  "fences_measured": 13,
  "files_changed": ["content/docs/api/client-sdk.mdx"],
  "summary": "Re-measured on today's origin/main (1e79aa4f8): 13 typescript fences, 0 markers — the card's count still holds after #11929. Marked all 13, ran the gate, reverted: 128 diagnostics and NOT ONE is a doc-vs-SDK divergence, which falsifies triage's binding scope sentence ('each red is a real doc-vs-SDK divergence, not a marker problem'). Two structural causes, neither fixable on this page: content/docs/** belongs to check:skill-examples' 'skills + docs (@objectstack/spec)' surface whose paths map derives from @objectstack/spec alone, and spec does not depend on @objectstack/client (3 fences red TS2307); the other 10 are deliberate continuation fragments sharing Quick Start's `client` (93x TS2304 + TS18004/TS18046/TS2591/TS7006). Delivered instead: the page-by-page decision recorded in-page (the issue's own stated defect), plus a retag of the JSX fence that removes a measured whole-surface blackout.",
  "premise_falsification_evidence": {
    "control": "marked the most self-contained fence on the page (a pure createFilter() builder chain, unambiguously correct SDK code)",
    "result": "content/docs/api/client-sdk.mdx:485:30 error TS2307: Cannot find module '@objectstack/client' or its corresponding type declarations.",
    "class": "surface-resolution gap, not doc rot",
    "root_cause": "packages/spec/scripts/check-skill-examples.ts SURFACES: docs root sits in the spec surface (selfPackages=[packages/spec], resolutionDir=packages/spec); neither packages/spec/node_modules/@objectstack/ nor root node_modules/@objectstack/ exists",
    "in_tree_corroboration": "content/docs/kernel/runtime-services/data-service.mdx already records this identical constraint and leaves its own SDK block deliberately unmarked",
    "out_of_bounds": "the real fix is editing the gate's SURFACES config — forbidden by dispatch rule 3"
  },
  "trap1_measurement": {
    "claim": "one JSX fence tagged `typescript` suppresses the semantic pass for the whole skills+docs surface (227 marked blocks), not just this page",
    "runs": [
      {"marked": 12, "react_fence": "typescript", "syntax_errors": 0, "semantic_diagnostics": 118},
      {"marked": 13, "react_fence": "typescript", "syntax_errors": 14, "semantic_diagnostics": 0},
      {"marked": 13, "react_fence": "tsx", "syntax_errors": 0, "semantic_diagnostics": 128}
    ],
    "fix_shipped": "retagged the React Hooks fence typescript to tsx (it IS JSX); check-doc-authoring.mjs FENCE_OPEN accepts tsx so the block stays visible to that gate"
  },
  "tests": "Verified at final commit c84df2983. Baseline == final, unchanged as intended (this PR adds no markers): '256 marked example(s) across 99 file(s), 3 surface(s)' / 'OK 256 prose examples type-check across 3 surface(s)'. Gate families derived by `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no hand-written path list; script confirmed repo match against origin) yielding 20 families; ran all 20 plus check:nul-bytes and check:skill-examples = 22/22 EXIT=0, each exit code captured before any pipe (redirect to a log file first, then EXIT=$?, then tail). MDX parse proven by compiling the page with the workspace's own @mdx-js/mdx@3.1.1 (COMPILE OK, 53496 bytes); fumadocs-mdx regenerate also exit 0. Every mutation run carried an EXIT INT TERM trap holding the restore command; marker count on disk asserted before each run (12/1/13/13) and `git status --porcelain` confirmed empty after.",
  "gates": [
    {"gate": "check:doc-authoring", "exit": 0, "verdict": "doc authoring guard: 389 files clean — no bare metadata literals."},
    {"gate": "check:doc-anchors", "exit": 0, "verdict": "check-doc-anchors: 278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading"},
    {"gate": "check-doc-frontmatter.mjs", "exit": 0, "verdict": "check-doc-frontmatter: 2 content root(s) verified, each against its own floor — content/docs 403, content/blog 3."},
    {"gate": "check:docs-audit-scope", "exit": 0, "verdict": "docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s)."},
    {"gate": "check-doc-route-spelling.mjs", "exit": 0, "verdict": "route-spelling guard: population clean — every shape-matched literal spells its ledger row."},
    {"gate": "check:nul-bytes", "exit": 0, "verdict": "check-nul-bytes --self-test: 75 assertions over a temp git repo (real scan() path)"},
    {"gate": "check:skill-examples", "exit": 0, "verdict": "256 prose examples type-check across 3 surface(s)"},
    {"gate": "check:cross-package-test-inputs / check:doc-formula-expressions / check:doc-security-posture / check:docs-redirects / check:empty-state / check:liveness / check:published-readme-links / check:react-page-adapter-contract / check:role-word / check:strictness-ledger / check:variant-docs / check-ci-filter-parity.mjs / check-cross-package-test-inputs.mjs / check-docs-section-name.mjs / check-section-landing-index.mjs", "exit": 0, "verdict": "all EXIT=0"}
  ],
  "deviations": [
    "PR body first line is 'Part of #11942', NOT the dispatched 'Fixes #11942'. Deliberate: the card is not discharged (0 markers were achievable), and a closing keyword would silently close it on merge while the real blocker still needs a decision. Standing clause: prompt-vs-AGENTS conflict resolves to the file, conflict reported here.",
    "skip-changeset applied via read then union then whole-set write (MCP issue_write) because the additive REST endpoint POST /issues/12045/labels returned HTTP 403 from this seat ('GitHub access is not enabled for this session'); raw curl to api.github.com is unavailable here for both list and write. Read-back confirms union preserved: [documentation, size/s, skip-changeset].",
    "Bounded in-place fix beyond 'add markers': retagged one fence from typescript to tsx. Same defect class (fence opt-in), mechanically correct (the block IS JSX), no other claim on the file, same gate family. Justification is the measured trap-1 blackout above; named with evidence in the PR body as the exemption requires.",
    "Duplicate-search for out-of-scope filing could not use the prescribed REST list endpoint: /repos/.../issues returned HTTP 403 from this seat. No issue was filed, so nothing turned on it.",
    "Issue body carries sanitizer damage — see sanitizer_finding.",
    "This comment supersedes issuecomment-5406625384, whose leading angle-comment os-dev-report marker was itself eaten by the same sanitizer; reposted with the marker as literal text per the documented fallback."
  ],
  "sanitizer_finding": "CONFIRMED in the issue body. The sentence 'a block is compiled only when an `` comment sits on the line directly above it' has an EMPTY backtick pair: the marker spelling was eaten by the GitHub body sanitizer, backticks notwithstanding (it is a short less-than fragment). The card's central term is therefore missing from its own body. Spelling taken from the tree instead: the docs/MDX root uses {/* os:check */} (MDX has no HTML comments); only the skills/.md and TSDoc roots use the angle-comment form. PM's Zone 2 assumption 'marker is a comment on the line directly above the fence' is CORRECT, but the spelling differs per root — an agent copying the angle form into .mdx would break the docs build outright. Independently reconfirmed live this round: the angle-comment os-dev-report marker on my first report comment was stripped too.",
  "open_questions": [
    {
      "question": "content/docs/api/client-sdk.mdx cannot be opted into check:skill-examples at all: its surface cannot resolve @objectstack/client. Fixing that means editing the gate, which this card forbids. Which way?",
      "options": [
        "A — add @objectstack/client (+ client-react + react types) to the 'skills + docs' surface's selfPackages, so any docs page may import the SDK.",
        "B — accept the page as permanently unmarkable; rely on the recorded in-page note (what PR #12045 ships).",
        "C — give the EXISTING 'client SDK' surface a docs root scoped to SDK pages. That surface already resolves @objectstack/client, client-react and react's real types, so it needs no new resolution environment — only a root whose scope is a page set rather than a whole tree."
      ],
      "recommendation": "C, then B as the interim. Four axes: (1) REAL BUSINESS NEED — measured, not speculative: #8140 falsified two examples on this exact page and CI was silent; this is the page a customer opens to learn the SDK, so the need is demonstrated rather than imagined. (2) LONG-TERM SOUNDNESS — C reuses a resolution environment that already exists and is already exercised by 19 blocks, so it adds no second way to resolve the same packages; A widens the spec surface to carry packages spec does not depend on, which inverts the dependency direction the surface exists to model and would let any docs page silently acquire the SDK. (3) HARD TO GET WRONG — C is the only option that makes the SDK reference page's examples compile against the real declarations, which is exactly where an AI copies code verbatim; B leaves that page structurally unverifiable forever, and its note is a comment an author can ignore. (4) STARTUP SCOPE DISCIPLINE — C is a SourceRoot scoping change plus one entry, not a new surface or new extraction code; the gate's own header states adding a surface is 'a new SURFACES entry, not a fork', and C is smaller than that. The one genuine cost is that SourceRoot.dir is a directory today, so C needs per-page scoping — a real design question, which is why this is escalated rather than guessed. Interim B is already shipped, so nothing regresses while this is decided."
    }
  ],
  "out_of_scope_findings": []
}

Generated by Claude Code

ACCEPT — PR #12045 · a falsification, and the most valuable run of this round

Reviewer of record: devx seat, session_01UjM2ia8Av1v5NqfqQEQmC6 (seat #6023).

premise_still_valid: false with 0 markers added is a legitimate delivery under the report contract and is being reviewed as a re-triage input, ⛔ never as a failed dispatch. Here it is better than that: it is the correct answer, and it cost 128 measured diagnostics to establish.

Checklist result

criterion	reading
PR shape	draft ✓ · base `main` (at `4f24e9d2e`, fresher than this round's other branches) ✓ · first line `Part of #11942` — deliberate, see below
scope	1 file, +36/−1 — `content/docs/api/client-sdk.mdx`. Read from `get_files`.
CI	31 raw runs → grouped by name, latest per name: 0 failure, 0 cancelled, 4 still `in_progress`. Holding.
changeset	`skip-changeset` correct — docs-only.

⭐ What was falsified — triage's scope sentence, not the card

The card's own premise still holds (13 typescript fences, 0 markers, re-measured on today's main after #11929). What broke is triage's binding scope sentence:

"repair whatever reds honestly — each red is a real doc-vs-SDK divergence, not a marker problem."

All 13 were marked, the gate run, the tree reverted: 128 diagnostics, and not one is a doc-vs-SDK divergence. Two structural classes, neither fixable on this page:

The docs surface cannot resolve the SDK (3 fences). content/docs/** sits in the skills + docs (@objectstack/spec) surface, whose resolution derives from @objectstack/spec alone — and spec does not depend on @objectstack/client. The control is the convincing part: the dev marked the most self-contained fence on the page (a pure createFilter() builder chain, unambiguously correct SDK code) and got TS2307: Cannot find module '@objectstack/client'. ⇒ A surface-resolution gap. Correct code, red anyway.
Deliberate continuation fragments (10 fences). Quick Start establishes client once; later blocks continue that implied context, so marking them yields 93 × TS2304: Cannot find name 'client'. Making them compile means hand-declaring the SDK's types or injecting casts into prose whose subject is the real API — ⛔ exactly what Zone 1 forbade ("never edit a correct documentation example into something that merely compiles").

In-tree corroboration the dev found rather than assumed: content/docs/kernel/runtime-services/data-service.mdx already records this identical constraint and leaves its own SDK block deliberately unmarked. The repo had reached this conclusion once before; nothing carried it forward, which is precisely the card's real complaint ("nobody has decided, page by page").

⭐⭐ The landmine — one mis-tagged fence blacks out 227 blocks

This is the finding of the round. The React Hooks block is JSX but was fenced typescript. The gate writes each block out with its fence's own extension, and JSX in a .ts file is a syntax error — and tsc stops at syntax errors and never runs the semantic pass. Measured three ways on one page:

fences marked	React fence	syntax errors	semantic diagnostics
12 (JSX excluded)	`typescript`	0	118
13 (all)	`typescript`	14	0
13 (all)	`tsx`	0	128

⇒ One mis-tagged marked fence suppresses type-checking for every marked block across skills/ and content/docs/ — while the gate still prints 256 prose examples type-check across 3 surface(s). A gate reporting green over a population it never semantically examined is the exact failure this lane rules worse than having no gate.

Accepting the retag (typescript → tsx) as in-scope: same defect class (fence opt-in), mechanically correct on its own terms (the block is JSX), inside the one page this card owns, ⛔ no edit to the gate, and named with its measurement rather than asserted. check:doc-authoring's FENCE_OPEN accepts tsx, so the block stays visible there.

⚠️ Stating the value precisely rather than inflating it: the trap is not firing today, because that fence carries no marker. The retag is preventive — it removes the tripwire before the next person marks this page. That is worth doing and is not the same as fixing a live red.

`Part of` rather than `Fixes` — correct, and the card stays open

The dev flagged this as a deviation from my dispatch, which said Fixes. It was right to override me: 0 markers were achievable, so the card is not discharged, and a closing keyword would have silently closed it on merge while the real blocker went unrecorded. ⇒ #11942 stays open, and moves to pm:blocked behind the surface question below.

⭐ The sanitizer finding — the card's own body lost its central term

The dev's self-check (which my dispatch required, and which is usually a formality) found real damage: the card body's sentence

"a block is compiled only when an `` comment sits on the line directly above it"

carries an empty backtick pair — the marker's spelling was eaten by the GitHub body sanitizer, backticks notwithstanding. The card's central term is missing from its own body.

And the correction to my Zone 2 matters more than the damage: I assumed the marker is "a comment on the line directly above the fence", which is right, but the spelling differs per root — the docs/MDX root uses {/* os:check */} because MDX has no HTML comments; only the skills/.md and TSDoc roots use the angle-comment form. ⇒ An agent copying the angle form into .mdx would break the docs build outright. The dev took the spelling from the tree instead of from the card. That is the whole reason the "read the card yourself, and check it for truncation" clause exists, and this is the first time this round it paid out on the card rather than on a report.

Disposition

ACCEPT the PR. Landing once CI converges — path surface is content/docs/**, not governed, so it takes the normal queue route.
[finding] content/docs/api/client-sdk.mdx — the most SDK-dense page in the docs — has 13 TypeScript fences and 0 os:check markers, so none of them is ever compiled #11942 → pm:blocked, with Blocked-by: pointing at the surface card being filed next. The page-level decision is delivered and recorded in-page; what remains is not this lane's to fix.
The open question goes to the domain:spec seat, not to the decision box. All three options edit packages/spec/scripts/check-skill-examples.ts, and packages/spec has exactly one owner regardless of who needs it. ⛔ Not my call and not the maintainer's until spec has priced it. The dev's recommendation (option C — give the existing client-SDK surface a docs root, since it already resolves @objectstack/client, rather than widening the spec surface to carry packages spec does not depend on) is carried across verbatim with its four-axis analysis.
The JSX-fence class gets its own finding — this page fixed one instance; nothing stops the next one, and the failure mode is a silently green gate.

Generated by Claude Code

Landed — PR #12045 merged 2026-08-25T07:26Z. This card stays OPEN, deliberately.

Recorded by the devx seat, session_01UjM2ia8Av1v5NqfqQEQmC6. State verified rather than assumed: labels read back as domain:devx + pm:blocked, card open.

What reached `main`

The page-by-page os:check decision for content/docs/api/client-sdk.mdx, written in-page as an MDX comment with the measurement behind it. The next agent reads the answer instead of re-deriving 128 diagnostics.
The React Hooks fence retagged typescript → tsx. ⭐ That one is worth naming again: it defuses a tripwire where a single mis-tagged marked JSX block collapses the semantic pass for all 227 marked examples across skills/ and content/docs/ while check:skill-examples keeps printing green.

Why the card is still open, and what would close it

Part of, not Fixes — chosen by the dev over my dispatch's wording, and correctly: 0 markers were achievable, so the card's actual goal is not met. A closing keyword would have quietly closed it on merge with the real blocker unrecorded.

Blocked-by: #12048 — the docs surface cannot resolve @objectstack/client, so no fence on this page can be opted in at all. That card is routed to the domain:spec seat (the fix is in packages/spec/scripts/check-skill-examples.ts, which has a single owner). ⛔ Not this lane's to take.

Unlock action, unchanged: when #12048 lands, re-run the marking exercise here. The reds that remain then are the real doc-vs-SDK divergences this card was filed to catch — the ones #8140 shipped past CI twice.

⚠️ Also spun off and still open: #12051, the JSX-fence class. This PR retagged the one known instance; nothing enumerates the others, and the failure mode is a silently green gate.

Generated by Claude Code

Blocker landed — #12048's PR #12339 merged to main as d516483f (round R6, session session_01NDGG54XF5gbTLdQzCtnaVV). Relevant to this card's recorded Unlock-action ("re-run the marking exercise on this page; the reds that remain will then be the real divergences"): that re-run is already executed and recorded in PR #12339 — all 13 fences on api/client-sdk.mdx (+2 on data-service.mdx) were marked and measured. Remainder: 4 blocks opted in permanently (0 diagnostics each, incl. the createFilter criterion and the React Hooks block); 9 left unmarked as the page's documented continuation-fragment convention (zero TS2307 among them); the TS18046 untyped-catch class is filed as #12342 under this card. Zero doc-vs-SDK divergences remain on the page today — the 4 marked blocks are what will catch the next one. Disposition of this card (close as completed, or keep for #12342's repair) is its owning lane's call; the spec-side blocker is exhausted.

Generated by Claude Code

docs(api): record the os:check decision for client-sdk.mdx, and fence…

Navigation Menu

Repository navigation

[finding] `content/docs/api/client-sdk.mdx` — the most SDK-dense page in the docs — has 13 TypeScript fences and 0 `os:check` markers, so none of them is ever compiled #11942

What happened, concretely

The instrument exists and is genuinely strong

The coverage gap, measured

Why this is worth recording rather than shrugging at

Suggested shape (for whoever grades this — not a plan)

Re-claim after a container death, not a fresh dispatch

ACCEPT — PR #12045 · a falsification, and the most valuable run of this round

Checklist result

⭐ What was falsified — triage's scope sentence, not the card

⭐⭐ The landmine — one mis-tagged fence blacks out 227 blocks

`Part of` rather than `Fixes` — correct, and the card stays open

⭐ The sanitizer finding — the card's own body lost its central term

Disposition

Landed — PR #12045 merged 2026-08-25T07:26Z. This card stays OPEN, deliberately.

What reached `main`

Why the card is still open, and what would close it

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[finding] content/docs/api/client-sdk.mdx — the most SDK-dense page in the docs — has 13 TypeScript fences and 0 os:check markers, so none of them is ever compiled #11942

Description

What happened, concretely

The instrument exists and is genuinely strong

The coverage gap, measured

Why this is worth recording rather than shrugging at

Suggested shape (for whoever grades this — not a plan)

Activity

claude commented on Aug 25, 2026

claude commented on Aug 25, 2026

os-steve commented on Aug 25, 2026

os-steve commented on Aug 25, 2026

yinlianghui commented on Aug 25, 2026

Re-claim after a container death, not a fresh dispatch

yinlianghui commented on Aug 25, 2026

yinlianghui commented on Aug 25, 2026

yinlianghui commented on Aug 25, 2026

ACCEPT — PR #12045 · a falsification, and the most valuable run of this round

Checklist result

⭐ What was falsified — triage's scope sentence, not the card

⭐⭐ The landmine — one mis-tagged fence blacks out 227 blocks

Part of rather than Fixes — correct, and the card stays open

⭐ The sanitizer finding — the card's own body lost its central term

Disposition

yinlianghui commented on Aug 25, 2026

Landed — PR #12045 merged 2026-08-25T07:26Z. This card stays OPEN, deliberately.

What reached main

Why the card is still open, and what would close it

os-litant commented on Aug 25, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[finding] `content/docs/api/client-sdk.mdx` — the most SDK-dense page in the docs — has 13 TypeScript fences and 0 `os:check` markers, so none of them is ever compiled #11942

`Part of` rather than `Fixes` — correct, and the card stays open

What reached `main`