docs(spec): relatedList describe states each value's role, not the record page's tabs by objectstack-fleet[bot] · Pull Request #29799 · objectstack-ai/objectstack

objectstack-fleet · 2026-11-03T05:19:46Z

domain:spec#3 · os-support-ai · session_01WGufzgh6TyUUCFMAfapZqb

Requested by Yibo Wang · project thread

Fixes #28888
Ruling-ref: 6568787922

Clause-②: no
Metadata-protocol: none
Skills-docs: none — this PR moves no skill text. One skill sentence still names the old chrome for the same placement, skills/objectstack-data/rules/relationships.md:345-348 ("in the Details tab, no tab of its own", "a side card"); it is out of this card's file surface (spec only) and is reported to the seat for its own card.

维护者速读

改了什么：relatedList 字段的说明文字（.describe() 与上方 TSDoc）不再提任何标签页或栏位：false = 父记录页不显示该子对象；true 或不写 = 记录页上的一个辅助面板；'primary' = 记录详情主体里的一张通栏表格。版式只引 ADR-0085，不复述。
为什么改：裁决 6568787922（字母 B）。旧文字描述的共用「Related」标签和「Details」标签在现在的记录页上已不存在，AI 作者照着读会把用户引向不存在的标签。
风险与回滚：只改文字，不动键、默认值、可接受值；@objectstack/spec patch。生成的参考页（field / object / migration 三页的同一行）随之重生成。回滚即还原本 PR。
先看：packages/spec/src/data/field.zod.ts（describe 与 TSDoc）、packages/spec/src/data/record-page-describes.test.ts（原来钉着旧措辞的用例改钉新措辞，并加一条「不提 tab / column / Related / Details / side card」）。
两分钟验证：pnpm --filter @objectstack/spec exec vitest run src/data/record-page-describes.test.ts 全绿；换回 origin/main 的 field.zod.ts 再跑，2 条红。
需要你做的：无，席位落地。

What changes

packages/spec/src/data/field.zod.ts, the relatedList .describe() and the TSDoc block above it. Every other clause keeps its meaning: the master_detail + inlineEdit 'primary' default, relatedLists ordering, and the derived-list sort sentences are unchanged.

Before (the value clauses):

false = suppress; true/absent = shown as a supporting list, a side card in the record's related column (the shared "Related" tab on the tabbed page); 'primary' = part of the record's main content, drawn in the record's body (the details column, after its first field section) as a full-width table (inside the Details tab on the tabbed page, with no tab of its own). Absent on a master_detail field that sets inlineEdit, the list is 'primary' by default; write true to keep it a side card. 'primary' places a list and does not order it: the parent object's relatedLists orders the body tables and the side cards (ADR-0085).

After:

false = the child object is not shown on the parent record page; true/absent = shown as an auxiliary panel on the record page; 'primary' = part of the record's main content, shown as a full-width table in the record's detail body. Absent on a master_detail field that sets inlineEdit, the list is 'primary' by default; write true to keep it an auxiliary panel. 'primary' places a list and does not order it: the parent object's relatedLists orders the full-width tables and the auxiliary panels. The page layout is defined by ADR-0085.

The TSDoc drops "related column", "shared "Related" tab", "details column", "Details tab ... no tab of its own" and "side card" the same way, and adds one line saying the layout is ADR-0085's to define. It keeps the sentence that a field group's relatedList can place a primary list among the field sections, since that is a real placement key, not page chrome.

Generated: content/docs/references/data/field.mdx, data/object.mdx, system/migration.mdx (the same relatedList row; check:generated --fix, then check:generated clean).

Why

Ruling 6568787922, letter B: the describe states the field's meaning, not the page's chrome, so the next layout card under #26676 does not make it wrong again.

Verification

Acceptance: git grep -n 'Related tab\|Details tab' -- packages/spec/src/data/field.zod.ts is empty at head.
record-page-describes.test.ts: the [#27312] case that pinned "the details column, after its first field section" and "inside the Details tab on the tabbed page, with no tab of its own" now pins the three new value clauses and the ADR-0085 sentence; a new case refuses tab(s), column, "Related", Details and side card in the describe. Red first: with origin/main's field.zod.ts, Tests 2 failed | 9 passed (11); restored, green.
pnpm exec vitest run src/data/record-page-describes.test.ts src/data/field.test.ts under os-verify-lock: Tests 303 passed (303), VERDICT command-exit 0.
Derived gates: dispatch-gates --commands derived 102 families at 9a801adf; 95 exit 0, 0 red, 7 NOT MEASURED (exit 3, prerequisite not met: check-plugin-teardown-shape --self-test needs its pinned fixture commit in this shallow clone; check:doc-formula-expressions, check:doc-security-posture, check:skill-examples, check:docs-transcript-drift, check:dual-build-cjs-loads, check:lean-entry-closure need a full build). dispatch-gates --ran: 102 accounted, 0 unrun. CI covers the 7.

Acceptance notes

Grep of packages/spec/src/** for the record page's "Related" / "Details" tab and its columns, other than this describe:

src/data/record-page-describes.test.ts (the old pin, changed here).
src/data/object.zod.ts:1251,1273 and src/data/object.form.ts:113: fieldGroups[i].relatedList says "details column", "body table" and "side card". That is a different key (a field group's placement), so per the order it is reported, not fixed.
src/migrations/entries/semantic/18.field-group-related-list-side-card-refused.ts: migration history text, left as it is.

Human Minimum

None; the seat lands it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WGufzgh6TyUUCFMAfapZqb

…cord page's tabs false = not shown on the parent record page; true/absent = an auxiliary panel; 'primary' = a full-width table in the detail body. The layout is cited as ADR-0085 instead of naming the retired "Related"/"Details" tabs and the page's columns. TSDoc, generated references and the describe pin follow. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WGufzgh6TyUUCFMAfapZqb

github-actions · 2026-11-03T05:21:05Z

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 1 documentable anchor(s).

11 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

content/docs/concepts/metadata-driven.mdx (via FieldSchema (symbol, a top-level const))
content/docs/data-modeling/external-datasources.mdx (via FieldSchema (symbol, a top-level const))
content/docs/data-modeling/field-types.mdx (via FieldSchema (symbol, a top-level const))
content/docs/data-modeling/validation-rules.mdx (via FieldSchema (symbol, a top-level const))
content/docs/deployment/troubleshooting.mdx (via FieldSchema (symbol, a top-level const))
content/docs/deployment/validating-metadata.mdx (via FieldSchema (symbol, a top-level const))
content/docs/getting-started/quick-reference.mdx (via FieldSchema (symbol, a top-level const))
content/docs/kernel/contracts/data-engine.mdx (via FieldSchema (symbol, a top-level const))
content/docs/protocol/backward-compatibility.mdx (via FieldSchema (symbol, a top-level const))
content/docs/protocol/objectql/types.mdx (via FieldSchema (symbol, a top-level const))
content/docs/protocol/objectui/concept.mdx (via FieldSchema (symbol, a top-level const))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

content/docs/releases/v17/17-0.mdx (via FieldSchema (symbol, a top-level const))
content/docs/releases/v17/17-1.mdx (via FieldSchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 103 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
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 — 168 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 97c2982c001e106e846511e4cdc760ac66a3b2ed → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 534a82f27a378b8d9fc0b1093b91e315d6e8c7ef — the merge of head 9a801adf289bb527025710c50c57e4e3ecdf5183 into base 97c2982c001e106e846511e4cdc760ac66a3b2ed, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 534a82f27a378b8d9fc0b1093b91e315d6e8c7ef && git checkout 534a82f27a378b8d9fc0b1093b91e315d6e8c7ef
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 97c2982c001e106e846511e4cdc760ac66a3b2ed 9a801adf289bb527025710c50c57e4e3ecdf5183 && git checkout -B drift-repro 97c2982c001e106e846511e4cdc760ac66a3b2ed && git merge --no-ff 9a801adf289bb527025710c50c57e4e3ecdf5183

node scripts/docs-audit/affected-docs.mjs --json 97c2982c001e106e846511e4cdc760ac66a3b2ed

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 97c2982c001e106e846511e4cdc760ac66a3b2ed → pass the list as
args.docs, on the commit named under Which tree this was computed on.

objectstack-fleet · 2026-11-03T05:22:06Z

domain:spec#3 · os-support-ai · session_01WGufzfgvGexKn9vLHsy89K

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 9a801adf289bb527025710c50c57e4e3ecdf5183
Local-runs: none

Inputs read: card #28888 (decision card body, ruling 6568787922 letter B, the seat's claims 6595386663 and 6595407202, os-dev-report 6596124364), PR #29799 body and its six-file list, and the net diff against the merge base. reviewFace on the PR's paths: face declaration, no schema or governed hit, so this record is the lane seat's at TIER_DEFAULT.

① Derived judgments

Prose only, right. The relatedList .describe() and the TSDoc above it in packages/spec/src/data/field.zod.ts change wording; the union z.boolean() | 'primary', its optionality, the master_detail + inlineEdit default and the ordering and sort clauses keep their meaning. No key, default, accept set or export moves.
The ruling's acceptance holds at this head. The describe names no tab, no column and no "Related" / "Details": git show 9a801adf:packages/spec/src/data/field.zod.ts has no hit for Related tab, Details tab, "Related" or side card. The three values read as the ruling binds them (false not shown; true/absent an auxiliary panel; 'primary' a full-width table in the detail body), and the layout is cited to ADR-0085, not restated.
The three regenerated content/docs/references/** rows (data/field.mdx, data/object.mdx, system/migration.mdx) are the pages the describe feeds.
record-page-describes.test.ts: the spec: the describe() of relatedList 'primary' and of enable.trackHistory still narrate the v2 record page (own tab, History tab) after the v3 layout #27312 pin moved from the old phrases to the new role phrases, and a new [Decision] spec: the relatedList describe still names the retired "Related" and "Details" tabs of the old record page — fix now, after record page v2 settles, or leave it #28888 pin refuses tab, column, "Related", Details and side card in the describe. That holds the ruling's acceptance in CI instead of by grep. The v2-phrase pin ("its own tab", "History tab") is kept.

② Semver level

.changeset/28888-related-list-describe.md: '@objectstack/spec': patch. The PR body carries Clause-②: no and Metadata-protocol: none, as the ruling binds, and the dev reports check-changeset-no-major exit 0 against the body. The meaning an author reads is unchanged (unlike a reversed promise, which would be semantic), so none at patch is right.

③ Boundary flags

Deviation 1, the test file outside the claimed surface: accepted. It pinned the stale phrase, so the describe fix moves it by necessity.
Deviations 2 and 3 (the red-first swap overlapping the gate run's start, the kept worktree) are process notes; the gates that read the file ran after it and are green at this head.
Gates: 102 derived, 95 exit 0, 7 exit 3. The 7 are prerequisite exits (a shallow fixture and six that need a full build), and CI's check-runs answer them.
Out of scope, seat-carried: skills/objectstack-data/rules/relationships.md:343-348 still teaches the old chrome for the same placement. It is governed and token-ratcheted, so it goes to the skills lane, not this PR. The fieldGroups[i].relatedList wording in object.zod.ts and object.form.ts names no tab; left, as the order says.
open_questions: none.

Implemented-by: claude/project-thread-vud2s3
Reviewed-by: session_01WGufzfgvGexKn9vLHsy89K

VERDICT: PASS

objectstack-fleet · 2026-11-03T05:46:05Z

domain:spec#3 · os-support-ai · session_01WGufzfgvGexKn9vLHsy89K

维护者速读

改了什么:字段 relatedList 的说明文字(.describe() 和上方 TSDoc)不再提「Related 标签页 / Details 标签页 / 某某栏」,只说三种取值的作用:false 不在父记录页显示,true 或不写是辅助面板,'primary' 是详情主体里的通栏表格;版式引 ADR-0085。
为什么改:执行 [Decision] spec: the relatedList describe still names the retired "Related" and "Details" tabs of the old record page — fix now, after record page v2 settles, or leave it #28888 裁决 B(记录 6568787922):旧文字描述的是已经不存在的标签页,AI 作者和 Studio 帮助照着它会指向不存在的地方。
风险与回滚:只改文字,键、默认值、接受集都不动;回滚即撤回本 PR。
先看:packages/spec/src/data/field.zod.ts 的 relatedList(≈:1908-1941)。
两分钟验证:pnpm --filter @objectstack/spec exec vitest run src/data/record-page-describes.test.ts,其中 [Decision] spec: the relatedList describe still names the retired "Related" and "Details" tabs of the old record page — fix now, after record page v2 settles, or leave it #28888 用例确认说明里没有 tab / column / Related / Details / side card。
需要你做的:无,席位落地。

席位意见:裁决 B 的验收条款逐条满足,而且被新的 pin 固定在 CI 里;技能文本里同样的旧说法已由 skills 车道立卡 #29801;同意落地。

席位核对 — ACCEPT · domain:spec#3 · head `9a801adf289bb527025710c50c57e4e3ecdf5183`

Shape: the relatedList describe and TSDoc in packages/spec/src/data/field.zod.ts, the three regenerated content/docs/references/** rows, the pins in record-page-describes.test.ts, one changeset. 6 files, +43 −28; no governed path.
Premise measured: ruling B on [Decision] spec: the relatedList describe still names the retired "Related" and "Details" tabs of the old record page — fix now, after record page v2 settles, or leave it #28888 (record 6568787922); on origin/main, field.zod.ts:1942 said "the shared "Related" tab on the tabbed page" and "inside the Details tab on the tabbed page".
Gates (check-runs at this head): 65 total, 57 success, 8 skipped, 0 red; mergeable_state: clean.
Contract review: record 6596143633, Served-tier: TIER_DEFAULT (face declaration), this head, VERDICT PASS.
Declarations: Clause-②: no, Metadata-protocol: none, @objectstack/spec patch, as the ruling binds. Skills-docs: none with its reason: accepted.
Accepted deviation: record-page-describes.test.ts is outside the claimed file surface; it pinned the stale phrase, so the fix moves it by necessity.
Carried: skills/objectstack-data/rules/relationships.md:343-348 → skills lane card skills(objectstack-data): relationships.md still teaches relatedList as "in the Details tab" and "a side card (the shared Related tab)", the retired record-page chrome the spec describe drops in PR #29799 #29801 (Blocked-by this PR).
Landing: ready + auto-merge.

github-actions Bot added size/s documentation Improvements or additions to documentation protocol:data tests tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Nov 3, 2026

objectstack-fleet Bot mentioned this pull request Nov 3, 2026

[Decision] spec: the relatedList describe still names the retired "Related" and "Details" tabs of the old record page — fix now, after record page v2 settles, or leave it #28888

Closed

objectstack-fleet Bot marked this pull request as ready for review November 3, 2026 05:47

objectstack-fleet Bot enabled auto-merge November 3, 2026 05:47

objectstack-fleet Bot added this pull request to the merge queue Nov 3, 2026

objectstack-fleet Bot mentioned this pull request Nov 3, 2026

[PM seat] triage (objectstack-wide) — 🟢 Routine · session_01AavokzJ5DndAwitDXvKy4U · trig_01NcnCtMS2tH46nUg1a5TaMJ (hourly) · state = body + the round records newer than it #6015

Open

Merged via the queue into main with commit 138dacf Nov 3, 2026
66 checks passed

objectstack-fleet Bot deleted the claude/project-thread-vud2s3 branch November 3, 2026 06:10

objectstack-fleet Bot mentioned this pull request Nov 3, 2026

docs(skills): objectstack-data teaches relatedList placement by each value’s role, not by record-page tabs or columns #29929

Merged

8 tasks done

Navigation Menu

Repository navigation

docs(spec): relatedList describe states each value's role, not the record page's tabs - #29799

docs(spec): relatedList describe states each value's role, not the record page's tabs#29799
objectstack-fleet[bot] merged 1 commit into
mainfrom
claude/project-thread-vud2s3

objectstack-fleet Bot commented Nov 3, 2026

Uh oh!

github-actions Bot commented Nov 3, 2026

Uh oh!

objectstack-fleet Bot commented Nov 3, 2026

Uh oh!

objectstack-fleet Bot commented Nov 3, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

objectstack-fleet Bot commented Nov 3, 2026

维护者速读

What changes

Why

Verification

Acceptance notes

Human Minimum

Uh oh!

github-actions Bot commented Nov 3, 2026

📓 Docs Drift Check

Uh oh!

objectstack-fleet Bot commented Nov 3, 2026

Contract review

① Derived judgments

② Semver level

③ Boundary flags

Uh oh!

objectstack-fleet Bot commented Nov 3, 2026

维护者速读

席位核对 — ACCEPT · domain:spec#3 · head 9a801adf289bb527025710c50c57e4e3ecdf5183

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

席位核对 — ACCEPT · domain:spec#3 · head `9a801adf289bb527025710c50c57e4e3ecdf5183`