fix(client): publishItem JSDoc names NO_DRAFT, not the retired [no_draft] opener

[objectstack-fleet]

Fixes #19704

Clause-②: no

publishItem's JSDoc in packages/client/src/index.ts (ships into dist/index.d.ts) documented the publish-refusal spelling as 404 [no_draft] — the bracketed lowercase message opener the 2026-08-29 maintainer ruling retired from every @objectstack/metadata-protocol producer via #16245 / PR #19683 (7a25a3ee9c). The runtime has answered status: 404, code: 'NO_DRAFT' with no bracketed opener since that PR landed. This corrects the docstring to name NO_DRAFT on the code axis, following the same 404 NO_DRAFT convention already used in packages/spec/src/api/plugin-rest-api.zod.ts. No behaviour change.

The card's own Blocked-by: #16245 is satisfied — that PR merged on 2026-09-22 (7a25a3ee9c). Triage originally planned to fold this card into #19705's round; per the claim's serial-constraints note, that round closed via a PR touching only QA files and never picked this line up, so this card proceeded on its own.

Measured

• Site confirmed: packages/client/src/index.ts:2152 read 404 [no_draft] when there is nothing to publish. on origin/main 455dcc06.
• Tree-wide sweep: git grep -n --fixed-strings "[no_draft]" over the tracked tree (excluding content/docs/releases/ and CHANGELOG.mds) found no other present-tense claim of this spelling inside packages/client/src/. Control words in the same file — NO_DRAFT and [item_locked] are zero there while publish hits 55 times — show the grep discriminates rather than being silently broken.
• Published-surface question (triage's UNMEASURED item): built @objectstack/client and grepped the emitted dist/index.d.ts — the docstring does ship (with positive controls, two neighbouring JSDoc lines, confirmed present too). This is a published-surface correction, so it carries .changeset/19704-client-no-draft-jsdoc.md (patch), not the skip-changeset route.
• Runtime producer: SysMetadataRepository.promoteDraft (packages/metadata-protocol/src/sys-metadata-repository.ts:946) throws status: 404, code: 'NO_DRAFT', message "No pending draft exists for {type}/{name} — nothing to publish." — no bracketed opener. The new docstring names exactly that.
• No test pins the old [no_draft] text (zero git grep hits across packages/client/'s test files).

Acceptance notes

Two more present-tense claims of the same retired bracketed-opener shape turned up while measuring the above, both outside this card's file surface (packages/client/src/ + the [no_draft] spelling specifically) — reported rather than fixed here:

• packages/rest/src/rest-server.ts:8427 — a source comment (404 [no_draft] when nothing to publish.) on the same POST /meta/:type/:name/publish route this card's producer serves. Same defect family as [finding] packages/client/src/index.ts:2151 JSDoc still documents 404 [no_draft], a spelling the runtime no longer emits after #16245 #19704 and finding(metadata-protocol): 30 refusal messages open with a bracketed tag that restates the code the same throw declares — the shape #12975 rules out, and it reaches the wire #16245, different file.
• packages/client/src/index.ts:6297 — a sibling docstring (Get a sharing rule by id or name. 404 [RULE_NOT_FOUND] when absent.) for a different code. Its producer (packages/plugins/plugin-sharing/src/sharing-rule-service.ts:818, bare throw new Error('RULE_NOT_FOUND')) and REST mapping (packages/rest/src/rest-server.ts:12807-12808, :12920) never emit a bracketed message either — the finding(metadata-protocol): 30 refusal messages open with a bracketed tag that restates the code the same throw declares — the shape #12975 rules out, and it reaches the wire #16245 shape recurring on a code that ruling never touched.

Neither is the [no_draft] spelling this card claims, and the second isn't in scope by spelling; both are named in the round report for the dispatching seat to route.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 15 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 172b4cf30c4aab44608cf689176f44be0aacbe74 → packageMentionDocs.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 8b2e8a33a1f2be7ff5133dd1cb193cca0da71491

① Derived judgments

• **Docstring truth (404 \NO_DRAFT` when there is nothing to publish)** — CORRECT. Producer: SysMetadataRepository.promoteDraft, packages/metadata-protocol/src/sys-metadata-repository.ts:942-948onorigin/main, throws Error('No pending draft exists for ${type}/${name} — nothing to publish.')witherr.code = 'NO_DRAFT', err.status = 404, no bracketed opener; git log -S'[no_draft]'on that file names7a25a3e(PR #19683, merged 2026-09-22) as the commit that turned[no_draft] No pending draft…intoNo pending draft…. REST: the POST ${metaPath}/:type/:name/publish handler (packages/rest/src/rest-server.ts:8428-8590) catches into handleRouteError (packages/rest/src/error-response.ts:2703) → resolveErrorResponsedeclared-status passthrough →res.status(404).json({ error: msg, code: 'NO_DRAFT' }), pinned byte-for-byte in packages/rest/src/rest-4xx-message-truncation.test.ts:344-352andrest-expected-error-logging.test.ts:127; NO_DRAFT is a ledger member (packages/spec/src/api/error-code-ledger.zod.ts:614) so it is never demoted to declaredCode. SDK: ObjectStackClient.fetch (packages/client/src/index.ts:7307-7395) rejects on !res.okwith anErrorwhose.messageis the server'serrorstring,.code = 'NO_DRAFT', .httpStatus = 404 (unwrapResponse` is never reached). Status, code axis and message all match the corrected line.
• Changeset prose facts — CORRECT on every claim: "ships into dist/index.d.ts" is measured independently of the dev's build — the published npm tarball @objectstack/client@17.4.0 carries the old sentence at dist/index.d.ts:1594 (404 [no_draft] when there is nothing to publish. [#12195] The name is …), and packages/client/package.json publishes files: ['dist','README.md','CHANGELOG.md'], types: dist/index.d.ts; "no behaviour change" — the source diff is one comment line; "since PR fix(metadata-protocol): refusal messages stop restating their own code in a bracketed opener #19683 (finding(metadata-protocol): 30 refusal messages open with a bracketed tag that restates the code the same throw declares — the shape #12975 rules out, and it reaches the wire #16245)" — that PR's diff is the removal at this exact producer; "that PR removed from the message" — true (git show 7a25a3ee9 -- …sys-metadata-repository.ts).
• Changeset markdown — WRONG. The body spells the corrected token as `404 \`NO_DRAFT\ ; CommonMark does not honour backslash escapes inside a code span, so the first span closes at the escaped backtick. GitHub's own renderer (the `body_html` of the PR body, which carries the identical string) and a CommonMark renderer run in scratch over `.changeset/19704-client-no-draft-jsdoc.md` both produce: a code span holding only `404 \`, then plain text `NO_DRAFT, then on the as a code span, code as plain text, then axis, instead of the retired bracketed lowercase opener as a code span, then plain [no_draft]``. @changesets/cli/changelogcopies this body verbatim intopackages/client/CHANGELOG.md(RELEASE-OWNED, ships in the npm tarball — "the text an upgrading agent greps", and a post-release correction costs a dedicated docs-only PR per AGENTS.md). The one sentence the changeset exists to deliver renders garbled. The sibling.changeset/16245-bracketed-tag-refusal-openers.mdshows the working spellings: a plain ``NO_DRAFT` `` span, and a double-backtick span for nesting.
• Backtick vs bracket notation — the PR's spelling is CORRECT and is the repo convention, not a novelty: the spec's own describe text reads '404 \NO_DRAFT` when there is nothing to publish; …' (packages/spec/src/api/plugin-rest-api.zod.ts:898) and 'answers 404 `NO_DRAFT`' (protocol.zod.ts:820); across packages/*/srcnon-test sources there are 79NNN `CODE`sites versus 3NNN [CODE] sites, and all 3 bracket sites are in this same client file (index.ts:6227, :6278 400 [VALIDATION_FAILED], :6297 404 [RULE_NOT_FOUND]), while the same file already uses backticks at :4833 (409 `PASSWORD_ALREADY_SET`). The inconsistency is pre-existing and more than a nit for those 3 lines: 404 [RULE_NOT_FOUND]is exactly the shape the #16245 ruling retired from messages, so a reader or AI takes it as "the message opens with[RULE_NOT_FOUND]", which no producer emits (packages/plugins/plugin-sharing/src/sharing-rule-service.ts:818throws a bareError('RULE_NOT_FOUND')`), and ADR-0112's own table names a contract docstring as what "teaches the old spelling to the next author (and to AI)". Outside this card's file-surface and spelling claim; correctly reported, not fixed, here.
• Dropping [#12195] — SOUND. GET /repos/objectstack-ai/objectstack/issues/12195 answers 404 (neither issue nor PR) and a board search for "12195" returns nothing; scripts/check-issue-citations.mjs (diff-scoped by design; package docblocks and .changeset/** are declared surfaces) reddened the prior head 053c6ec7 on exactly this line — job 108569681412, step "Issue citations this change adds resolve on the board" — as allocated-but-absent. A phantom tracker number in a published .d.ts is provenance no consumer can follow; the sentence's substance (percent-encoded name, retired compound arity) is kept and its history survives in packages/client/CHANGELOG.md ("Two SDK doc comments that promised 'compound names pass through unencoded' (meta.getPublished, meta.publishItem) are corrected"). Three other [#12195] citations remain in untouched lines of the same file (tarball dist/index.d.ts:581, :625, :1508) — outside the gate's diff scope and the card, consistent with the gate header's "standing sites are census, not verdict". #7294 in the same docblock resolves (closed issue).

② Semver level

patch is the right level. The change publishes (the docstring is in the tarball's dist/index.d.ts), so AGENTS.md Post-Task #3 forbids skip-changeset; nothing on the wire, in the request, or in the return type moves, so Clause-②: no holds and minor is not owed; @objectstack/client is in the fixed lockstep group, where patch is the floor for the group bump. Precedent in packages/client/CHANGELOG.md entry 1bb5a56 ("JSDoc/.d.ts wording only") shipped at the same level. A patch changeset lacking a Clause-② line matches sibling patch changesets (12271, 13272, 14361); the ADR-0087 gate reads that line only for a breaking arm.

③ Boundary flags

• CI on the head at read time: 31 check-runs — 20 success, 3 skipped, 8 still in_progress (Lint & Repo Gates with its "Issue citations…" step still pending, Type Check · workspace, Test Core 1/2/3/6, Dogfood 2/3); no failure; combined status success; PR mergeable: true, mergeable_state: blocked (draft, unreviewed). Prior head 053c6ec7 failed only that citation step; the head removed its cause. Not green yet; landing waits on the remaining 8.
• PR title misnames the method: "promoteItem JSDoc …" — git grep -i promoteItem origin/main finds nothing anywhere in the tree; the method is meta.publishItem. The repo squash-merges with squash_merge_commit_title: PR_TITLE, so this false name becomes the commit subject on main (the round-0 commit 053c6ec7 carries the same "promoteItem/publishItem" subject).
• PR body date error: "that PR landed on 2026-08-29 (7a25a3ee9c)" — the commit is dated 2026-09-22 12:50 UTC and PR fix(metadata-protocol): refusal messages stop restating their own code in a bracketed opener #19683 merged 2026-09-22T13:11:59Z; 2026-08-29 is the maintainer ruling date. Prose only, not in the diff.
• Two class-(b) findings noted, none filed: packages/rest/src/rest-server.ts:8427 route comment 404 [no_draft] (source-only) and packages/client/src/index.ts:6297 404 [RULE_NOT_FOUND] (published — tarball dist/index.d.ts:4027). Prime Directive chore: version packages #10 wants a published-declaration-vs-runtime disagreement filed as a card, not left to a round report; no card for either was found on the board.
• No other live carrier of the retired spelling: the remaining [no_draft] hits on origin/main are pre-fix narration in test comments, self-constructed fixtures in packages/rest tests, a dated revision note in docs/qa/platform-checklist/areas/access-security.json:1876, and the finding(metadata-protocol): 30 refusal messages open with a bracketed tag that restates the code the same throw declares — the shape #12975 rules out, and it reaches the wire #16245 changeset — none a present-tense claim; content/docs/references/api/protocol.mdx was regenerated by the finding(metadata-protocol): 30 refusal messages open with a bracketed tag that restates the code the same throw declares — the shape #12975 rules out, and it reaches the wire #16245 round.
• Branch base: head is 2 commits on 455dcc060; origin/main has moved to 560b724c9; GitHub reports mergeable: true, and the file surface is disjoint from what landed.
• Draft state: the PR is still draft: true with no review; the relay forced it.

Implemented-by: claude/issue-19704-client-no-draft-jsdoc
Reviewed-by: session_01UYBdGBzWSrAMzpW8ah3GbP

Independence: INDEPENDENT AGENT (fed the card, the rulings and the PR only; not the dispatch order or the seat's conclusions)

VERDICT: FAIL

• .changeset/19704-client-no-draft-jsdoc.md: replace the malformed code span `404 \`NO_DRAFT\ with a spelling CommonMark renders — plain404 NO_DRAFT (no nesting), or a double-backtick span around the whole `404 \`NO_DRAFT\ — so the shipped CHANGELOG.md entry reads the token it exists to deliver.
• Retitle the PR to name publishItem (the squash-merge subject is the PR title; promoteItem exists nowhere in the tree).

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: ab7a61340de3219805339725efd5b61449be8b21

Delta of: 5853960447 (FAIL on 8b2e8a33)

① Derived judgments

• Required change 1 — changeset code span — MET. Delta git diff 8b2e8a33 ab7a6134 is one line of .changeset/19704-client-no-draft-jsdoc.md: `404 \`NO_DRAFT\ →404 NO_DRAFT `` (front matter '@objectstack/client': patch untouched). Mechanical CommonMark pairing (a run of N backticks closes at the next run of exactly N; backslash is not an escape inside a span) over the head body yields exactly five spans: `publishItem`, `dist/index.d.ts`, `NO_DRAFT`, `code`, `[no_draft]`, with `404 ` as plain text before `NO_DRAFT`. GitHub's own renderer (GET `/contents/.changeset/19704-client-no-draft-jsdoc.md?ref=ab7a6134`, `Accept: application/vnd.github.html`) produces the same five `` spans and the fragment `404 NO_DRAFT on the code axis`. Control: the same GET at `8b2e8a33` yields the garbled spans the prior review reported (`404 `, `on the`, `axis, instead of the retired bracketed lowercase opener`). `@changesets/cli/changelog` (`.changeset/config.json`) copies the body verbatim into `packages/client/CHANGELOG.md`, so the shipped entry now reads the token it exists to deliver.
• Required change 2 — PR title names the real method — MET. Title now fix(client): publishItem JSDoc names NO_DRAFT, not the retired [no_draft] opener (timeline: renamed by objectstack-fleet[bot] 2026-09-27T07:52:45Z). publishItem: async ( is at packages/client/src/index.ts:2169 on head, under meta = { (:1749), and the corrected JSDoc (:2149-2168) closes immediately above it; git grep promoteItem origin/main → 0 hits. Repo settings (GET /repos/...): squash-only, squash_merge_commit_title: PR_TITLE, so the landed subject will now be correct.
• Changeset claims — all CORRECT. "ships into dist/index.d.ts": published tarball @objectstack/client@17.4.0 (registry latest, published 2026-09-09) carries dist/index.d.ts:1594 * 404 [no_draft] when there is nothing to publish. [#12195] … inside meta: { (:1382) beside publishItem (:1603); package.json files: ['dist','README.md','CHANGELOG.md'], types: dist/index.d.ts. "the runtime has emitted since PR #19683 (#16245)": PR #19683 (Fixes #16245) merged 2026-09-22T13:11:59Z as 7a25a3ee9c, whose diff on packages/metadata-protocol/src/sys-metadata-repository.ts is - \[no_draft] No pending draft exists …`/+ `No pending draft exists …`; on origin/main SysMetadataRepository.promoteDraft (:885) throws at :943-948with messageNo pending draft exists for ${ref.type}/${ref.name} — nothing to publish., err.code = 'NO_DRAFT', err.status = 404. "No behaviour change": the source diff is one comment line. "404 `NO_DRAFT`on thecode axis" is the spec's own spelling (packages/spec/src/api/plugin-rest-api.zod.ts:898`).
• PR body claims — all CORRECT on re-check. Dates: "2026-08-29 maintainer ruling" is the ruling date quoted in card #16245's body ("maintainer, 2026-08-29") and PR #19683's body; "that PR merged on 2026-09-22 (7a25a3ee9c)" matches merged_at; the earlier wrong "landed on 2026-08-29" sentence is gone. packages/client/src/index.ts:2152 reads 404 [no_draft] when there is nothing to publish. [#12195] … at merge-base 455dcc060 and still at current origin/main. Control counts in that file at 455dcc06: NO_DRAFT 0, [item_locked] 0, publish 55, [no_draft] 1 — as stated. Tree-wide [no_draft] (excluding releases/CHANGELOGs): the only packages/client hit is :2152; 0 hits in packages/client test files. #19705 closed completed 2026-09-24 via PR #19843, whose file list is exactly docs/qa/platform-checklist/areas/access-security.json. Out-of-scope citations verified verbatim: packages/rest/src/rest-server.ts:8427 (// overlay to live. 404 [no_draft] when nothing to publish.), packages/client/src/index.ts:6297 (404 [RULE_NOT_FOUND] when absent.), packages/plugins/plugin-sharing/src/sharing-rule-service.ts:818 (throw new Error('RULE_NOT_FOUND')), rest-server.ts:12807-12808 and :12920 (res.status(404).json({ code: 'RULE_NOT_FOUND' … })). Fixes #19704, Clause-②: no present. Spelling: no errors found; no model identifier in title, body or changeset (AGENTS.md line 454).
• Dropped [#12195] — still SOUND: GET /issues/12195 → 404; #7294 in the same docblock resolves (closed).
• New in this round — nothing wrong found. The only file change is the one changeset line; the head commit carries the model-free trailer pair AGENTS.md prescribes (Claude-Session: + Co-authored-by: Claude <noreply@anthropic.com>), matching recent origin/main commits. git merge-tree --write-tree origin/main ab7a6134 → clean.

② Semver level

Unchanged: patch + Clause-②: no. The delta edits only changeset prose; the front matter still grades @objectstack/client patch. The correction reaches a published surface (tarball dist/index.d.ts), so AGENTS.md Post-Task #3 (lines 1071-1073) forbids skip-changeset; nothing on the wire, in the request or in the return type moves, so no clause-② arm and no minor; @objectstack/client is in the fixed lockstep group, where patch is the floor.

③ Boundary flags

• CI on ab7a6134 at read time: 38 check-runs — 26 success, 5 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke, plus Auto Label / Check PR Size on the title-edit run), 7 still in_progress (Test Core 1/3/4/6, Dogfood Regression Gate 2/3, Type Check · workspace, Lint & Repo Gates); 0 failures; combined status success. Not green yet; nothing red. The prior head's only red step (issue citations) stayed green on 8b2e8a33 and the delta adds no citations.
• Branch base: head is 3 commits on 455dcc060; origin/main is now 0bd11261e. Drift on the PR's paths is 14 unrelated .changeset/*.md files; packages/client/src/index.ts and packages/client/package.json (17.4.0) are unchanged on main; in-memory merge is clean.
• Release timing: .changeset/16245-bracketed-tag-refusal-openers.md is still unconsumed on origin/main and @objectstack/client@17.4.0 predates #19683, so the producer change and this docstring correction ship in the same next release; the CHANGELOG sentence "since PR #19683" reads coherently there. Not a defect.
• Out-of-scope carriers unchanged on origin/main: packages/rest/src/rest-server.ts:8427 404 [no_draft] (source comment; the seat's rework comment routes it as a rider on #20139) and packages/client/src/index.ts:6297 404 [RULE_NOT_FOUND] (the seat dropped it as the sharing block's local [CODE] notation, which :6213, :6227, :6278 confirm exists; the pre-existing notation split with the file's backtick sites remains). Neither is this card's spelling or file surface.
• Draft state: draft: true, 0 reviews, mergeable: true, mergeable_state: blocked.
• No workflow gates on the PR title and no commit-msg hook in the tree; the [no_draft] token in the squash subject trips nothing.

Implemented-by: claude/issue-19704-client-no-draft-jsdoc
Reviewed-by: session_01UYBdGBzWSrAMzpW8ah3GbP

Independence: INDEPENDENT AGENT (fed the card, the prior review, and the PR only; not the dispatch order or the seat's conclusions)

VERDICT: PASS