spec: four metadata type descriptions an admin reads in Setup (api, doc, book, capability) carry ADR numbers and schema vocabulary; the spec half of #23802

Filing gate ④: a split of #23802, cut by triage at that card's pm:retriage (filed by the epic PM from the 2026-10-16 Setup review, under the maintainer's 「全部立卡」). packages/spec is the spec seat's whatever needs it, so its half cannot ride #23802's domain:engine PR. ⛔ Not a claim.

Reader who acts: the domain:spec seat.

What an admin reads

packages/spec/src/kernel/metadata-plugin.zod.ts, DEFAULT_METADATA_TYPE_REGISTRY, on origin/main. Four description strings carry ADR vocabulary, and Setup surfaces them through packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts:

api: "Declarative HTTP endpoint — a stable URL and policy layer over an existing pipeline (ADR…"
doc: "Package documentation — flat Markdown items (ADR-0046)"
book: "Documentation navigation spine — ordered groups with derived membership (ADR-0046 §6)"
capability: "Package-declared authorization capability — the DEFINITION side of ADR-0066 D1 (grants live on permission sets; requirements on resources)"

The measurement: grep -E "description: '[^']*(ADR-|\bD[0-9]\b|finding F|emit\(\)|kernel)" over the registry's { type: '…' } lines gives 4 hits.

The change

Rewrite each as one sentence in an admin's words: what the items are and what you do with them. Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802's Target gives the voice, for example capability: "A permission a package defines; you grant it through permission sets."
Keep ADR references in the docblocks and comments, not in user-facing strings (Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802's constraint).
Spec 辅助面 only: the changeset is patch, and no accept/refuse result changes. Not the protocol-first class.

Acceptance

None of the four descriptions contains ADR-, D\d, finding F, emit() or kernel. Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802's acceptance lint, which lands with that card, sees them once this is in.
The generated metadata-forms translations regenerate. If Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802 lands first, this PR regenerates en.metadata-forms.generated.ts and the zh-CN / ja-JP files, and the reverse holds too.

Grade and order

p2, inherited from Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802.
It runs in parallel with Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802.

Dedupe

The parent is #23802. This is its split, with no separate search: the four strings were measured in this act.

Claim: PM loop round 4 · 2026-10-16T04:08Z · the four DEFAULT_METADATA_TYPE_REGISTRY descriptions an admin reads in Setup (api, doc, book, capability) become one sentence each in an admin's words. The ADR vocabulary moves to the docblocks and comments, and the generated metadata-forms translations regenerate.
Session: session_01HjR8RUwTPQ3TgbfKihmxp9 (the dispatching seat; the dev runs as a cloud session the seat post names)
Account: os-elon-musk (the seat's linked user as GET /user answers it; this card's assignee)
Branch: claude/issue-23808-type-descriptions-plain
Worktree: objectstack-issue-23808 (in the cloud session's container)
Domain: domain:spec
Seat: domain:spec#1 (seat post #6017)
File surface (at origin/main 74b436263 or later; stop on a breach and explain it in the report):

packages/spec/src/kernel/metadata-plugin.zod.ts, DEFAULT_METADATA_TYPE_REGISTRY: the four description strings (api at about :1131, doc :1139, book :1153, capability :1210), with any ADR reference moved to a comment beside the row;
the generated outputs their tooling rewrites: packages/platform-objects/src/apps/translations/*.metadata-forms.generated.ts (en, plus the zh-CN / ja-JP / es-ES entries if the generator owns them), and any spec reference page or ledger that carries the strings;
pins that assert the old strings, changed to the new ones, never deleted;
one @objectstack/spec patch changeset (plus @objectstack/platform-objects patch if its generated file ships).
⛔ Not any other registry row, and not Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802's engine-side lint.
Container & model: S, mode:cloud (the maintainer's word in this session's chat: 「batch 调到 5, 可以开云卡」), model: default tier (dispatch-gates --tier --repo objectstack-ai/objectstack: no path-derived mandate). The face is packages/spec/src/** (string values in a registry const, no accept-set move), so a CONTRACT_REVIEW_TIER review is owed before the queue.
Clause-②: no
Responsibility: n/a — a split of Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802 (filing gate ④)
Thread-read: none
Ruling-ref: none (Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802's constraint, quoted in the card: keep ADR references out of user-facing strings)
Serial constraints cleared: the file lists of all open PRs and the latest Claim: of every open pm:dispatched card were read in this act, and none names metadata-plugin.zod.ts or the metadata-forms generated files. Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802 (domain:engine) runs in parallel, per the card. Whichever lands second regenerates the shared generated files.

os-dev-report

{
  "issue": 23808,
  "status": "done",
  "branch": "claude/issue-23808-type-descriptions-plain",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/23817",
  "session": "session_014SHyy7c7ipsMkzJ3J9mdL9",
  "premise_still_valid": true,
  "summary": "The four DEFAULT_METADATA_TYPE_REGISTRY descriptions (api, doc, book, capability) in packages/spec/src/kernel/metadata-plugin.zod.ts are now one plain admin sentence each. Their ADR vocabulary (ADR-0121, ADR-0046, ADR-0046 §6, ADR-0066 D1) moved to the comment beside each row. The card's grep gives 4 hits at 74b436263 and 0 after. `pnpm i18n:extract` regenerated en.metadata-forms.generated.ts. The zh-CN/ja-JP/es-ES leaves were hand-written translations of the old wording, so they are rewritten as plain locale sentences, values only and no key moves; source-hash tables are unchanged. bare-type-display-echo-decisions.test.ts rows are re-decided against the new source, and a new assertion holds all four descriptions free of ADR vocabulary in the registry, en and every locale, with a dark control. Changeset: spec patch plus platform-objects patch. Where the string reaches an admin: MetadataManager type info, then the REST /meta types listing, translated per locale by resolveMetadataTypeDescription (rest-server.ts translateMetaTypesResponse). Setup and Studio metadata pages both read that listing.",
  "tests": "At head b625ac4c: `pnpm --filter @objectstack/spec build` VERDICT command-exit 0. `pnpm --filter @objectstack/platform-objects test`: Test Files 70 passed, Tests 1092 passed. `pnpm --filter @objectstack/platform-objects typecheck` exit 0, in the same && chain under VERDICT command-exit 0. `pnpm --filter @objectstack/spec check:generated`: all 14 generated artifacts up to date. Translations dir alone: 25 files / 437 tests passed. `pnpm i18n:extract` re-run after the locale edits was a no-op (git diff unchanged). No ablation: the diff changes copy strings, not tested behaviour. The new plain-copy assertion carries its own dark leg, which fires on the replaced prose.",
  "gates": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 88 families at b625ac4c. Each ran with its exit captured before any pipe: 86 exit 0, including check:i18n (OK, 10 packages, all bundles in sync), check:i18n-stale-fill, spec check:docs/check:api-surface/check:authorable-surface, check:doc-authoring and check:nul-bytes. 2 exited 3 on prerequisites and are NOT MEASURED locally: `node scripts/check-plugin-teardown-shape.mjs --self-test` (shallow clone, pinned positive-control commit 621a4876 unreachable) and `pnpm check:dual-build-cjs-loads` (not every workspace package built). `--ran` reconciliation: '88 derived famil(ies) accounted for — 86 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3)', exit 0. CI check-runs on PR #23817: in_progress at report time. check:dev-prereqs not run locally (spec dist was rebuilt by this run).",
  "mcp_calls": "3 — mcp__github__issue_read x3 (get #23808, get_comments #23808, get #23802); all reads, no write tool",
  "api_writes": "3 — via fleet-write relay: POST /repos/objectstack-ai/objectstack/pulls (draft #23817), POST /repos/objectstack-ai/objectstack/issues/23817/assignees (os-elon-musk); POST /repos/objectstack-ai/objectstack/issues/23808/comments (this os-dev-report). git push is not counted.",
  "open_questions": [
    { "question": "The new descriptions end without a full stop, matching the sibling registry descriptions (seed, picklist, mapping, dataset). The card's example sentence for capability ends with one. Which convention should hold?", "options": ["A no full stop, consistent with the other registry descriptions in Setup", "B full stop on all registry descriptions (touches rows outside this card)"], "recommendation": "A, because a mixed list would read inconsistently in Setup and B widens the file surface beyond the four rows" },
    { "question": "The api sentence names flows, scripts and data, the three common ApiEndpointSchema.type targets. proxy is left implicit to keep the sentence plain.", "options": ["A keep as is", "B mention forwarding to another service"], "recommendation": "A, because the admin reading Setup needs what the item is, not the full target enum" }
  ],
  "out_of_scope_findings": [
    "carrier: none · noted, not filed — packages/spec/src/stack.zod.ts:778-779 `docs`/`books` .describe() still say 'flat Markdown items … (ADR-0046)' / '(ADR-0046 §6)'; that is author-facing schema documentation (reference docs), not a Setup string, so no class applies",
    "carrier: none · noted, not filed — the cloud container's shallow clone cannot reach check-plugin-teardown-shape's pinned fixture commit; environment, not a defect"
  ],
  "line_budget": "+96 / -39 over 7 files (135 changed lines), under the 3000 human-merge threshold",
  "deviations": [
    "The PM's worktree name was used (../objectstack-issue-23808). To free the branch name for `git worktree add -b`, the shared container checkout was detached at origin/main and its local branch (identical to origin/main, no commits) deleted.",
    "No label-write: the dispatch's write budget names only git push, pr_create and the report comment.",
    "test:repo not run locally: the diff does not touch that project and the derivation does not name it; CI's Test Core runs it."
  ],
  "files_changed": [
    ".changeset/23808-type-descriptions-plain.md",
    "packages/spec/src/kernel/metadata-plugin.zod.ts",
    "packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts",
    "packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts",
    "packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts",
    "packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts",
    "packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts"
  ]
}

Generated by Claude Code

os-dev-report

{
  "issue": 23808,
  "status": "done",
  "branch": "claude/issue-23808-type-descriptions-plain",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/23817",
  "session": "session_014SHyy7c7ipsMkzJ3J9mdL9",
  "premise_still_valid": true,
  "summary": "Patch round on PR #23817 (claim 6207867989), head a8dd6f76. The seat's three corrections were verified against the code before editing. packages/spec/src/api/endpoint.zod.ts:174 says only flow and object_operation execute, with script and proxy rejected at publish; the doc and book rows are allowRuntimeCreate: true. New registry strings: api 'A stable HTTP URL that other systems call to run a flow or work with records in the app'; doc 'A help page written in Markdown that a package ships or you write yourself'; book 'A table of contents that groups help pages into ordered sections'; capability unchanged. ADR vocabulary stays in the row comments. en was regenerated by `pnpm i18n:extract`. zh-CN / ja-JP / es-ES values were rewritten to the new meaning, values only and no key moves. The ledger rows in bare-type-display-echo-decisions.test.ts and the changeset's quoted sentences carry the new text. The card's grep still gives 0 hits.",
  "tests": "At head a8dd6f76: the build closure (spec, cli, platform-objects and the nine i18n-config packages) `pnpm exec turbo run build --concurrency=2 --filter=…` VERDICT command-exit 0, spec rebuilt from source. `pnpm --filter @objectstack/platform-objects test` exit 0: Test Files 70 passed, Tests 1092 passed. `pnpm --filter @objectstack/platform-objects typecheck` exit 0. `pnpm i18n:extract` exit 0, rewriting only en.metadata-forms.generated.ts (3 leaves); source-hash tables unchanged.",
  "gates": "Each exit captured before any pipe, at a8dd6f76: `pnpm --filter @objectstack/spec check:generated` :: exit 0 (all 14 generated artifacts up to date); `pnpm check:i18n` :: exit 0 (OK, 10 packages, all bundles in sync); `pnpm check:i18n-stale-fill` :: exit 0 (11 bundle sets, 0 stale-fill leaves); `pnpm check:doc-authoring` :: exit 0; `pnpm check:nul-bytes` :: exit 0. The full 88-family derivation was not re-run this round: the path set is unchanged from the first round's 86-pass reconciliation at b625ac4c. CI check-runs on the new head: in_progress at report time.",
  "mcp_calls": "0 this round (first round: 3 issue_read reads)",
  "api_writes": "1 this round — POST /repos/objectstack-ai/objectstack/issues/23808/comments (this report) via the fleet-write relay; git push is not counted",
  "open_questions": [
    { "question": "The PR #23817 body (written once at create, never PATCHed by the dev) still quotes the first-round sentences for api, doc and book, and the dev's earlier open question about proxy is now moot. Should the seat rewrite the body?", "options": ["A seat edits the 'What changed' table's api/doc/book 'after' cells to the three new strings and drops the full-stop note's reference to the old api wording", "B leave the body; the diff and this report carry the current text"], "recommendation": "A, because reviewers read the body's table as the change" }
  ],
  "out_of_scope_findings": [],
  "line_budget": "this round +23 / -23 over 6 files; the PR stays well under 3000 changed lines",
  "deviations": [
    "A nohup line in this round wrote its PID file to /build2.pid (shell variable empty in that subshell). The container's safety check refused deleting it, so a 4-byte stray file remains at /build2.pid outside the repo.",
    "The worktree was re-created from origin/claude/issue-23808-type-descriptions-plain at b625ac4c. origin/main was not merged in, since no conflict or main-caused red was reported."
  ],
  "files_changed": [
    ".changeset/23808-type-descriptions-plain.md",
    "packages/spec/src/kernel/metadata-plugin.zod.ts",
    "packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts",
    "packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts",
    "packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts",
    "packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts",
    "packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts"
  ]
}

Generated by Claude Code

ACCEPT → PR #23817 comment 6208887367 · domain:spec seat 1 · session session_01HjR8RUwTPQ3TgbfKihmxp9 · 2026-10-16T05:38Z · the contract review (CONTRACT_REVIEW_TIER, face packages/spec/src/**) and an all-green head stand before the queue.

Patch round asked at the seat's review: the first-round api sentence named scripts, which endpoint.zod.ts refuses at publish. The doc and book sentences named a package as the only source, although both rows are allowRuntimeCreate: true. Head a8dd6f769f carries the corrected sentences in the registry and all four locales.

Landed · PR #23817 → `1ecb08a1cc` · `domain:spec` seat 1 · `os-elon-musk` · session `session_01HjR8RUwTPQ3TgbfKihmxp9` · 2026-10-16T06:36Z

probe	reading
PR object	merged 2026-10-16T06:36Z out of the merge queue (entered 06:05:15Z); merge commit `1ecb08a1cc`
`origin/main`	`git merge-base --is-ancestor 1ecb08a1cc origin/main` → exit 0
merged vs reviewed head	all 7 files' blobs at `1ecb08a1cc` equal the reviewed head `a8dd6f769f` (ACCEPT `6208887367`, contract review PASS `6209017603`, both on this head)
queue branch	no `gh-readonly-queue/main/pr-23817-*` ref remains
mis-close scan	the body's only closing keyword is `Fixes #23808`; this card closed `completed`

State: pm:dispatched is removed in this act; enhancement, priority:p2, domain:spec and area:devpath stay. The cloud dev session is archived in this act.

Setup now shows one plain sentence each for api, doc, book and capability, in en, zh-CN, ja-JP and es-ES, and the ADR vocabulary sits in the registry comments.
Setup copy: ADR numbers and schema vocabulary leave the object, type and navigation descriptions admins read #23802 (domain:engine, the engine-side lint) runs on its own card. Whichever of the two touches the generated metadata-forms bundles next regenerates them.

Generated by Claude Code

Navigation Menu

Repository navigation

spec: four metadata type descriptions an admin reads in Setup (api, doc, book, capability) carry ADR numbers and schema vocabulary; the spec half of #23802 #23808

What an admin reads

The change

Acceptance

Grade and order

Dedupe

Landed · PR #23817 → `1ecb08a1cc` · `domain:spec` seat 1 · `os-elon-musk` · session `session_01HjR8RUwTPQ3TgbfKihmxp9` · 2026-10-16T06:36Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

spec: four metadata type descriptions an admin reads in Setup (api, doc, book, capability) carry ADR numbers and schema vocabulary; the spec half of #23802 #23808

Description

What an admin reads

The change

Acceptance

Grade and order

Dedupe

Activity

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

Landed · PR #23817 → 1ecb08a1cc · domain:spec seat 1 · os-elon-musk · session session_01HjR8RUwTPQ3TgbfKihmxp9 · 2026-10-16T06:36Z

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Landed · PR #23817 → `1ecb08a1cc` · `domain:spec` seat 1 · `os-elon-musk` · session `session_01HjR8RUwTPQ3TgbfKihmxp9` · 2026-10-16T06:36Z