feat(spec): an object declares the business order of its related lists, and 'primary' places a list - #27215

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/lint, @objectstack/metadata-core, @objectstack/platform-objects, @objectstack/spec, touching 35 documentable anchor(s). ⚠️ 5 changed file(s) yielded no anchor (packages/lint/src/index.ts, packages/spec/authorable-surface/data.json, packages/spec/liveness/field.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

54 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 295699d51d1484a735989450238ec2e14c0c1104.

⛔ 13 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 959ac8483df2eeb637151e79babcf1d71835dd7c && git checkout 959ac8483df2eeb637151e79babcf1d71835dd7c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 295699d51d1484a735989450238ec2e14c0c1104 897e8d89aff69b18cc77197d807f4cd03cda4d73 && git checkout -B drift-repro 295699d51d1484a735989450238ec2e14c0c1104 && git merge --no-ff 897e8d89aff69b18cc77197d807f4cd03cda4d73

node scripts/docs-audit/affected-docs.mjs --json 295699d51d1484a735989450238ec2e14c0c1104

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 295699d51d1484a735989450238ec2e14c0c1104 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: d53bd33122bdf502502bb782de3a75ef46b8360b
Local-runs: none
Scope: packages/spec/src/data/field.zod.ts, packages/spec/src/data/object.form.ts, packages/spec/src/data/object.zod.ts, packages/spec/src/stack.zod.ts, skills/objectstack-data/rules/relationships.md, skills/objectstack-ui/SKILL.md + ui/packages/app-shell/src/utils/deriveRelatedLists.ts, ui/packages/app-shell/src/utils/tests/deriveRelatedLists.relatedListsOrder-27069.test.ts, packages/spec/src/stack-related-lists-order.test.ts, ui/packages/plugin-detail/src/synth/buildDefaultPageSchema.ts (buildDefaultTabs), ui/packages/app-shell/src/views/RecordDetailView.tsx (:1848, :3256-3299), packages/lint/src/validate-semantic-roles.ts (rules (a)/(b)/(d)), packages/lint/src/object-field-groups.ts, packages/lint/src/validate-object-field-refs.ts, docs/adr/0035-config-driven-master-detail.md (:84-96), docs/adr/0085-object-semantic-roles-over-surface-hint-blocks.md (§2), .changeset/27069-related-lists-order.md, packages/spec/liveness/object.json + field.json, packages/spec/src/compose-stacks-*.test.ts (the two pins), examples/app-crm/src/objects/opportunity-line-item.object.ts, examples/app-showcase/src/data/objects/invoice.object.ts, examples/app-showcase/src/data/objects/expense-report.object.ts, packages/metadata and packages/objectql hotcrm __fixtures__ (census only). The remainder of the diff (generated docs, authorable-surface baseline, platform-objects translation bundles and their two pins, the metadata-protocol count pin) is the lane seat's ACCEPT at TIER_DEFAULT.

Inputs read: card #27069 body and its two comments (claim 6465054400, os-dev-report 6467128510); epic #26676 round-3 comments 6459899198 and 6460478339; PR #27215 body, file list (27 files) and the net diff against the merge base 4265176cf3 (origin/main at 9dacccf961); the 41 check-runs on the head.

Check-runs on d53bd3312 at read time (2026-10-28), 41 in all: 11 completed success (Spec property liveness, Check Changeset, Governed Surface Queue Guard, PR-body guards, Dogfood Regression Gate, Check PR Size, Check Documentation Links, Flag docs affected, Auto Label, Plan Test Core shards, filter), 7 skipped (opt-in / schedule gates), 23 in progress (Type Check x4, Test Core 1-8/8, Lint x8, Build Core / Build UI Deps / Build Docs). No red at read time; the in-progress families are reported as counts, not verdicts.

① Derived judgments

Accept-set and public-surface changes the diff implies, each judged against the tree:

1. ObjectSchema.relatedLists?: string[], each entry ^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?$ — RIGHT. The grammar is the object/field machine-name grammar with at most one dot, judged at parse with no new refinement node; relatedLists: 'task', [1], ['Task'], ['a.b.c'] are refused by the shape (pinned in stack-related-lists-order.test.ts). Sits beside highlightFields, as the card asked. objectExtensions cannot contribute it (ObjectExtensionSchema is strict with no such key), the same as highlightFields.
2. ObjectFieldGroupSchema.relatedList?: string, same grammar — RIGHT in shape. The group schema carries no fields key (membership is Field.group → fieldGroups[].key), so "a group with relatedList carries no fields" is realised as refuseFieldsInRelatedListGroups: one located issue at ['fields', NAME, 'group'] per field naming such a group, inside the object's existing superRefine, so the JSON Schema projection drops nothing new. Judged against the lint gate it must co-exist with, it does NOT hold today — see ④ M2.
3. defineStack refuses a relatedLists entry or a group relatedList that matches no inbound lookup/master_detail field, STACK_CROSS_REFERENCE_INVALID with code + numeric status, the message naming the entry and the inbound relationships spelled as an entry may name them ('rlo_task', 'rlo_event.who_id', 'rlo_event.related_to', or it has none) — RIGHT, and placed where highlightFields' sibling cross-object checks sit (validateCrossReferences, after collectHydratedInlineColumnErrors). The walk covers config.objects, every packages[].manifest.objects (the assembled ArtifactPackageSchema body does carry object definitions there; the same pattern applyControlledByParentExtensionGate uses) and the fields objectExtensions add. Audit FKs (created_by/updated_by/owner_id) are excluded by field name, matching the reader's AUDIT_FK_FIELDS. Artifact-scoped: a child named only by a sibling package (artifactObjects) or a platform-prefixed object is left unjudged ONLY when the child is nowhere in fieldsByObject; a declared child with no such FK is refused. Consistent with the spec: defineStack's per-stack cross-reference validation refuses permissions[].objects and data[].object that name an object owned by ANOTHER PACKAGE OF THE SAME ARTIFACT — so ADR-0130's co-owned artifact and the "permission sets stay whole in the app package" addendum cannot both hold once the app package owns objects #18202 ARTIFACT-SCOPED classes. Two limits, graded should-fix in ④ (S3): the check sits below if (objectNames.size === 0) return errors;, so an artifact-only definition (objects only in package bodies) never reaches it, contrary to the docblock; and seen keys by object identity, so a name declared both top-level and in a body is judged twice.
4. relatedList: 'primary' re-read as placement, no longer ordering — RIGHT per the card's target 2 ("its meaning becomes PLACEMENT"). resolveRelatedListOrder is the one resolution: listed first in declared order (a list takes the position of the FIRST entry naming it; a bare child name takes every list of that child in their derived order; object.field takes one), unlisted after in today's derived order (owned then lookup, discovery order). relatedList: false still hides a listed relationship (the FK is skipped before the list exists, so the entry places nothing). An unknown entry places nothing. buildDefaultTabs is unchanged and filters isPrimary into own tabs and the rest into the Related tab, preserving order within each half, so the card's acceptance 2 holds on the tabbed page: ['task', 'campaign_member'] renders tasks, campaign members, then the rest; primary still promotes an unlisted list (own tab) without moving its order. All pinned in the 11-case app-shell test.
5. An absent relatedList on a master_detail FK that sets inlineEdit (true / 'grid' / 'form', the three arms FieldSchema.inlineEdit declares) is isPrimary by default; explicit true opts out; lookup + inlineEdit does not default — RIGHT per the maintainer's line-items ruling quoted in the card (「明细行的子表放在右侧合适嘛？」 → the body). Only one branch on the value exists under ui/ (deriveRelatedLists.ts; RecordDetailView forwards isPrimary, buildDefaultTabs splits on it; no second derivation under ui/apps), and MetadataProvider passes object keys through, so objectDef.relatedLists reaches the reader.
6. Census of what visibly moves on today's tabbed page from the default in 5 (whole head tree, non-test code): THREE in-repo parents — crm_opportunity (examples/app-crm, crm_opportunity_line_item.opportunity: inlineEdit: 'grid', no relatedList), showcase_invoice (showcase_invoice_line.invoice, same) and showcase_expense_report (showcase_expense_line.expense_report, same). Each gains its own "Products" / "Line Items" / "Expense Lines" tab and leaves the shared Related tab on merge. packages/platform-objects: no inlineEdit FK at all, nothing moves. The three hotcrm fixtures in repo (packages/metadata/src/__fixtures__/hotcrm-17.1-*, packages/objectql/src/__fixtures__/hotcrm-4.0.1-*) carry no inlineEdit and no relatedList, nothing moves. Field.masterDetail sets no relatedList default, so the builder path is the raw path. No test or e2e pins the Related tab for those three parents, so the move is silent in CI — which is exactly why the changeset should name them (④ S2).
7. Compose: relatedLists joins the derived object collection-key list, so two declarations of one object both carrying it are refused at merge, as highlightFields is — RIGHT (the two compose pins move by one row each). A relationship contributed by another package is seen by the check only when both halves are in one defineStack call (composed stacks, or an artifact's package bodies); a package validated alone with a parent naming a sibling's child relies on artifactObjects, exactly as the other artifact-scoped classes do.
8. Studio: object.form.ts gains the relatedLists string-tags row after highlightFields and a relatedList text sub-row in the fieldGroups repeater; labels and help in four locales (platform-objects, lane remainder) — RIGHT. The help text honestly states the publish-door gap ("os validate refuses it"), which is true: os validate imports the stack, so defineStack's throw is the refusal.
9. FieldSchema.relatedList TSDoc/describe re-read — RIGHT against the reader; the tabbed-page parenthetical keeps today's behaviour visible.
10. Liveness: object.relatedLists is live with the reader (resolveRelatedListOrder, deriveRelatedLists → RecordDetailView) and the authoring judge named; field.relatedList / relatedListTitle re-cited. The deriveRelatedLists citations (:367, :378-379) are exact on the head; the RecordDetailView.tsx:1827 citation is :1848 on the merge head (the pre-merge line; Spec property liveness is green, observation only). fieldGroups[].relatedList has no row and shelters under object/fieldGroups = live by a dogfood proof that never exercises relatedList — graded in ④ S4.

② Semver level

Clause-②: yes (widening) — RIGHT. Two new optional keys; the only new refusals (fields.X.group naming a relatedList group; a dangling relatedList name at defineStack) bite only input that could not exist before this head, so nothing previously accepted is refused.

Metadata-protocol: semantic — RIGHT, and the dev's step-3 upgrade from the card's added is the correct reading under AGENTS.md step 3 ("a changed meaning or default is semantic; several ⇒ narrowed over semantic over added"): 'primary' changes meaning (order → placement) and the absent value changes default on an inline-edited master_detail FK. Both declaration lines are line-initial in the PR body and the changeset body.

Changeset .changeset/27069-related-lists-order.md: @objectstack/spec minor (the kind takes at least minor), @object-ui/app-shell minor (the reader's behaviour moves without a metadata edit), @objectstack/platform-objects minor (the generated metadata-form bundles move), @objectstack/skills minor (a package 13 other changesets in the root .changeset already name) — all RIGHT. It is in the root .changeset, carries both declaration lines and a "What to do" migration note for the semantic default (relatedList: true keeps the old placement), which is what step 3 asks of a semantic change (the mandatory FROM → TO mapping is the breaking-only clause). Check Changeset is green on the head. One should-fix on the note's content, ④ S2: it does not census the movers.

③ Boundary flags

open_questions: [] — nothing to answer. The three out_of_scope_findings and the four PR acceptance notes:

• Publish-door gap (dev flag 1, seat ask (a)): CONFIRMED on this head. runtimeAuthoringRulesFor('object') dispatches no rule that reads relatedLists or fieldGroups[].relatedList; validate-object-field-refs.ts is same-object by design and validateSemanticRoles is fenced off that door ([P2] 运行时授权门扩到 object 写入 + 全量 runtime-safe 规则快照(#4463 P1 之后) #4716). A Studio / REST /meta / MCP save of relatedLists: ['nope'] is accepted and the reader places nothing. The form's help text says so. Recorded as ④ S3 for the delta review; the carrier the dev names (seat 1 / lint lane) is right, but the rule belongs in this card's delta, not a new card, because the key ships here.
• fieldGroups[].relatedList ahead of its renderer (dev flag 2, seat ask (b)): CONFIRMED. No reader on the head (git grep relatedList under ui/ branches only in deriveRelatedLists.ts, on the FK flag, never on a group). The key is live by inheritance from the object/fieldGroups container whose proof is the semantic-roles dogfood. Recorded as ④ S4: a row of its own at planned, carrier console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055.
• ADR-0035's read-side table (dev flag 3): the dev defers the amended status line to console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055 because "'primary' promotes it to its own tab" stays true on the tabbed page. ESCALATED to a must-fix (④ M1): the sentence this head falsifies is not that one but the DEFAULT sentence on the same page — "true / omitted shows the child under a single shared Related tab" — and "a prominence hint, not a layout switch". Both are reversed on this head, not on console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055's.
• Bare child name with several FKs orders all of that child's lists rather than being refused as ambiguous (acceptance note 4): ACCEPTED. The card's grammar says object.field is for the multi-FK case and never says a bare name is then refused; the dev's reading is the less surprising one and the refusal message spells the per-FK names for such a child, so an author who wants one list is told how.
• Reader drag order (console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055/console: one workspace-preference module (record open mode, drawer width, timeline / related column toggles) read per user × object, with a shared panel-toggle toolbar on the record page — defaults derived from the object, never metadata #27052) and HotCRM declarations (hotcrm follow-up): out of this card, correctly left.
• ADR-0085 §2 admission: relatedLists passes test 1 (business importance is not inferable) and test 2 (no page name; it binds the object's relationships across surfaces, the highlightFields precedent); fieldGroups[].relatedList is a layout-role entry under ADR-0085 §5 exactly as fieldGroups already is, and the maintainer ruled the placement (「他如果做到放在基本信息下面」). No contradiction with ADR-0085's text; the re-reading of 'primary' from "prominence" to "placement" should be noted beside ADR-0035's amendment (M1) since the old TSDoc cited prominence as the admission argument.

④ Design judgment

packages/spec/src/data/object.zod.ts — against ruling A and its first consumer (deriveRelatedLists). relatedLists: holds. Grammar, describe, placement beside highlightFields, extension-proof, compose-key: all as the card asks, and the reader resolves exactly what the describe promises. ObjectFieldGroupSchema.relatedList + refuseFieldsInRelatedListGroups: the parse-time half holds (correct path, message names the group and the list), but the design does not hold against the lint gate the same object passes through:

• M2 (must-fix): packages/lint/src/validate-semantic-roles.ts rule (b) FIELD_GROUP_EMPTY fires on every group that carries relatedList — "fieldGroups declares 'lines' but no field references it — the group never renders. Assign at least one field via group: 'lines', or remove the unused group declaration." — and that hint prescribes the one thing this head refuses at fields.X.group. The card's own example ({ name: 'lines', label: '报价明细', relatedList: 'crm_quote_line_item.crm_quote' }) run through os validate / os lint is told to undo itself. A rule and the gate it must co-exist with are one change: exempt a group carrying relatedList from rule (b) (and from (d), which already skips empty groups) in this PR, with a pin. Warning-tier and CLI-only, but a contract that contradicts its own gate on the authoring path the help text points to is not a cosmetic miss.

packages/spec/src/stack.zod.ts — collectRelatedListNameErrors against the ADR-0112 envelope and compose. Holds for the scenarios the card names (entry / object.field / unknown child / known child without FK / unknown field / no inbound at all / extension-added FK / sibling package / group relatedList), all pinned with code + numeric status + named subjects, never a bare toThrow().

• S3 (should-fix): the call sits below if (objectNames.size === 0) return errors;, so the package-body walk the docblock promises ("the stack's objects, every packages[].manifest.objects") never runs for a definition whose objects live only in package bodies. Either state that limit in the docblock (it is shared with every sibling check below that line) or hoist the call above it, since this check needs no top-level object to resolve against. Also, seen is keyed by record identity and dedupes nothing: a name declared both top-level and in a body is judged twice with merged fields, two identical issues. Minor; one line each.
• S3' (should-fix, the seat's ask (a)): the publish door. Add a relatedLists / fieldGroups[].relatedList dangling-name rule beside validate-object-field-refs at the tier that door dispatches, reading the registry the door has (the lint object-graph index, as object-field-groups.ts does), so a one-object save of relatedLists: ['nope'] is refused rather than silently placing nothing. Until it lands the form help text's "os validate refuses it" is the only door.

packages/spec/src/data/field.zod.ts — the relatedList TSDoc and describe against the reader: holds. Every sentence has a line in isMainContentList / buildDefaultTabs. The three inlineEdit arms the default keys on are the three the schema declares.

• M1 (must-fix): docs/adr/0035-config-driven-master-detail.md (Accepted) records, in its read-side table and the paragraph under it (:86-93): "true / omitted shows the child under a single shared Related tab; 'primary' promotes the relationship to its own tab" and "relatedList is tri-state (a prominence hint, not a layout switch — see ADR-0085)". This head makes an omitted relatedList on an inline-edited master_detail FK — the exact relationship ADR-0035 is about — land in its own tab, and re-reads 'primary' as placement. Prime Directive 13: reversing a recorded decision "needs a new ADR (or an amended status line on the old one), not a changeset that quietly does the opposite." The ruling is in hand (quoted in the card, 2026-10-28), so the fix is an amended status line on ADR-0035 citing spec: an object declares the business order of its related lists — relatedLists: ['task', 'event', …], an ordered list of child relationships like highlightFields is of fields; unlisted ones follow the derived order; a name that matches no inbound relationship is refused #27069 and that ruling, with a one-line note on the two sentences it changes; add the same note to ADR-0085 §2 for the prominence → placement reading since the old TSDoc cited prominence as the key's admission argument. docs/adr/** is Tier H, and the PR already carries Tier H through skills/**, so it changes nothing about the landing path. The dev's deferral to console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055 is wrong on the facts: console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055 changes WHERE a primary list is drawn; this head changes WHICH lists are primary.

packages/spec/src/data/object.form.ts — against Studio's form renderer and the spec: holds. Both rows match the key shapes (string-tags for string[], text for the group's string), sit where the card asked, and the help texts say what the tree does, gap included.

skills/objectstack-data/rules/relationships.md — against the spec on this head and the card's acceptance scenario: the tri-state bullets and the relatedLists bullet are accurate and the file is net smaller (ratchet green per the dev; CI's ratchet job in progress at read time).

• S1 (should-fix): the bullet "true / omitted — a side card (the shared Related tab)" is contradicted one bullet up for the inline-edit default; say "true, or omitted on anything but an inline-edited master_detail — a side card". Same file, the code comment "read side: a body table (default with inlineEdit)" is right.

skills/objectstack-ui/SKILL.md — the relatedList: 'primary' bullet is accurate. But the "Related-list layout" paragraph that follows it (:117-128), untouched by the diff, still closes with "For arrangements the relationship layer can't express — filtered splits, a chart/report tab, exact tab ordering — assign the object a custom record Page". After this head exact tab ordering IS expressible: relatedLists orders the own tabs among themselves and the Related tab's lists among themselves (buildDefaultTabs preserves the resolved order within each half).

• S1' (should-fix): drop "exact tab ordering" from that list (or point it at relatedLists), in the same file so the skill does not teach a custom Page for what the object key now does. Paid for by the line it removes.

Cross-cutting

• S2 (should-fix): the changeset's "What to do" note is generic. Name the three in-repo parents whose record page visibly changes on merge (crm_opportunity, showcase_invoice, showcase_expense_report each gain an own line-items tab) so an upgrader greps a concrete symbol; the PR body should carry the same census under "Risk". Nothing in CI pins those tabs, so the changeset is the only place the move is visible.
• S4 (should-fix, the seat's ask (b)): give fieldGroups[].relatedList a liveness row of its own at planned (reader console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055), instead of inheriting live from the object/fieldGroups container whose dogfood proof never exercises it; the object.relatedLists note already names the reader, so the row is a move of that sentence.
• Observations, not graded (non-hits, non-reviewed): buildDefaultPageSchema.ts:1003 "Owned-before-lookup order is preserved by deriveRelatedLists upstream" and the isPrimary TSDoc at :241-247 ("a CORE relationship") read as before this head; the liveness RecordDetailView.tsx:1827 citation is :1848 on the merge head.

Implemented-by: claude/project-thread-vr8ygc
Reviewed-by: session_01WGufzfhobWEgUUrjz4rrbh

VERDICT: FAIL

Two must-fixes, both one-sitting: M1 the ADR-0035 (and ADR-0085 §2) amended status line for the default and the re-reading this head ships; M2 the FIELD_GROUP_EMPTY exemption for a relatedList group. The resolution function, the strict-name check, the primary re-reading and the inline-edit default are right against the card and the tree; the semver level and both declaration lines are right. The delta review closes M1, M2 and the seat's two asks (S3', S4) together.

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 8a549c1e26aeec4c0ebc42eed2566e37639b36fd
Local-runs: none
Scope: packages/spec/src/data/field.zod.ts, packages/spec/src/data/object.form.ts, packages/spec/src/data/object.zod.ts, packages/spec/src/stack.zod.ts, skills/objectstack-data/rules/relationships.md, skills/objectstack-ui/SKILL.md + packages/lint/src/validate-related-list-refs.ts (the door rule, in scope by the round's order), packages/lint/src/reference-integrity-suite.ts (the validateRelatedListRefs member and its wholeCollection predicate), packages/lint/src/runtime-gate.ts (buildRuntimeWriteSnapshotSet, narrowObjectsToPackageClosure, runRuntimeAuthoringRules, fingerprint, RuntimeStackContext), packages/lint/src/validate-semantic-roles.ts (rules (b)/(d)), packages/lint/src/rule-explanations.ts, packages/metadata-protocol/src/runtime-authoring-gate.ts + protocol-authoring-gate.ts (listCollection('object', 'objects'), resolveWritePackageScope, pending), packages/objectql/src/registry.ts (listItems → getAllObjects → resolveObject, the extender fold), packages/spec/src/stack.zod.ts validateCrossReferences / collectObjectNames / isPlatformObjectName, ui/packages/app-shell/src/utils/deriveRelatedLists.ts, ui/packages/app-shell/src/views/metadata-admin/inspectors/ObjectFieldInspector.tsx (readRelatedListMode), docs/adr/0035-config-driven-master-detail.md, docs/adr/0085-object-semantic-roles-over-surface-hint-blocks.md (§2, §5), .changeset/27069-related-lists-order.md, packages/spec/liveness/object.json + field.json, and the pins: packages/spec/src/stack-related-lists-order.test.ts, packages/lint/src/validate-related-list-refs.test.ts, packages/lint/src/runtime-gate.object-writes.test.ts, packages/metadata-protocol/src/protocol.runtime-authoring-gate.test.ts, packages/lint/src/validate-semantic-roles.test.ts, ui/packages/app-shell/src/utils/tests/deriveRelatedLists.relatedListsOrder-27069.test.ts, ObjectFieldInspector.relatedList-27054.test.tsx. The remainder of the diff (generated content/docs/references/**, the authorable-surface baseline, platform-objects translation bundles and their two pins, the metadata-protocol count pin, lint index.ts re-exports, the compose-stacks pins) is the lane seat's ACCEPT at TIER_DEFAULT.

Delta review of the round-1 record 6467460418 (FAIL at d53bd3312). Inputs read: card #27069 body and its two comments (claim 6465054400, os-dev-report 6467128510); PR #27215 body as updated for this round, file list (42 files) and the net diff against the merge base 835b2d1cc9; the 14 commits on the branch, the five after d53bd3312 being 2c1525067 (the door rule), 3c90b4f2f (merge of main), bd3f1079d (Studio inspector), 8375ff9b6 (ADR amendments, relatedList groups, artifact-only stacks), 912f48922 (SKILL.md), 8a549c1e2 (merge of main); the check-runs on the head. No new os-dev-report was posted for this round; the PR body carries the round-2 account.

Check-runs on 8a549c1e at read time (2026-10-28T11:59Z), 65 in all: 28 completed success (Spec property liveness, Check Changeset x2, Governed Surface Queue Guard, PR-body guards x2, Dogfood Regression Gate, Check PR Size, Check Documentation Links, Flag docs affected, Auto Label, filter, Plan Test Core shards, Build UI Deps, Build Docs, Build and E2E UI, Lint and Repo Gates, Lint x8 (ESLint, PM dispatch-gates, docs and code guards, repo and tooling gates, CI/release/engine gates, three scoped), Type Check source gates, Type Check debt ledger), 9 skipped (opt-in / schedule gates), 28 in progress (Test Core 1-8/8, Test UI 1-16/16, Build Core, Lint UI, Type Check UI, Type Check workspace). No red at read time; the in-progress families are reported as counts, not verdicts.

Round-1 findings, each judged on this head

• M1 (ADR-0035 and ADR-0085 not amended) — CLOSED. docs/adr/0035-config-driven-master-detail.md carries an amended status line (Accepted · Amended (2026-10-28, #27069, …)) naming the ruling and the three changes (placement, the parent's relatedLists, the inline-edit default), plus a note under the read-side table that names the two sentences this head falsifies and states that "'primary' promotes it to its own tab" stays true on the tabbed page. docs/adr/0085-…md §2 carries the note on the two keys admitted under its test and on the prominence → placement re-reading at the relationship layer. Both say what the tree does.
• M2 (rules (b) and (d) fire on relatedList groups) — CLOSED. validate-semantic-roles.ts builds relatedListGroups from fieldGroups[].relatedList !== undefined and continues in both loops; the pin ([#27069] a group carrying relatedList …) holds the clean case and a control that differs by the key alone (FIELD_GROUP_EMPTY still fires). Rule (a) (a field naming an undeclared group) is untouched and correct. object-field-groups.ts answers only "declared at all", so it has no empty-group verdict to exempt.
• S1 / S1' (skill copy) — CLOSED. relationships.md: "true, or omitted (except inline-edited master_detail) — a side card (the shared Related tab)"; "exact tab ordering" is gone from SKILL.md's custom-Page list, and the layout paragraph says both halves keep the object's relatedLists order.
• S2 (changeset census) — CLOSED. The changeset names crm_opportunity, showcase_invoice and showcase_expense_report with their FKs; the PR body's 风险与回滚 line carries the same three.
• S3 (early return, seen) — CLOSED. collectRelatedListNameErrors is called before if (objectNames.size === 0) return errors; with the artifact scope computed inline; collectObjectNames reads config.objects only, so an artifact-only definition did need the hoist. seen keys by object name. Both pinned (judges an artifact whose objects live only in package bodies, once per object name).
• S3' (publish door) — CLOSED, by the new rule; judged below.
• S4 (planned liveness row) — CLOSED. object.fieldGroups is drilled (10 child rows, the undrilled-containers baseline entry removed); fieldGroups.relatedList is planned with the reader named (console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055). Spec property liveness is green on the head.

① Derived judgments

Judgments 1, 2 (parse half), 3 (now including artifact-only stacks), 4, 5, 6, 7, 8, 9, 10 of the round-1 record stand on this head unchanged; re-read, not restated. New or changed on this head:

11. Lint rule validateRelatedListRefs, related-list-ref-unknown at error, member of REFERENCE_INTEGRITY_RULES with runtimeTypes: ['flow', 'object'] — RIGHT. It resolves children from stack.objects (array or map form) with stack.objectExtensions merged by name, excludes the three audit FKs by name (the reader's AUDIT_FK_FIELDS), and refuses an entry that matches no inbound lookup / master_detail field. A child the snapshot does not hold is refused only under wholeCollection, which the suite sets exactly as it does for validateListViewFieldRefs: runtimeWriteType set and no packageScope (lint: an overlay write (no package) of a list view bound to an object that exists nowhere answers 200 with no issue — validateListViewFieldRefs skips it and no other rule judges a view write's binding #24668). The sentence is defineStack's word for word, held by a pin that runs both. Path spelling is positional on the raw snapshot and name-keyed on the wire (objects.rl_quote.relatedLists[0]), the finding: a publish refusal's issues[].path carries an array index into the gate's private snapshot (objects[417].sharingModel) that no caller can resolve #10064 shape. Pinned at three layers: the pure rule (8 cases), runRuntimeAuthoringRules on an object write (5 cases, closure case included), and the protocol's saveMetaItem (422 INVALID_METADATA, the row not stored; the control stores active with a body-table group beside it).
12. The door's universe, read in the cited code: protocol-authoring-gate.ts hands listCollection('object', 'objects') as objects, which is registry.listItems('object') → getAllObjects → resolveObject, the ADR-0029 D9 fold of extend contributors onto the base layer (plus the tenant's overlay rows and this batch's pending drafts). So at the door the child's fields are the FOLDED fields: an FK an objectExtension adds is in the snapshot. RuntimeStackContext carries no objectExtensions key, so the rule's own extension merge never runs at the door; it is the CLI shape's, and is harmless. packageScope comes from resolveWritePackageScope(evt.packageId); absent on a Studio/REST write that names no package, so such a write is judged on the whole collection, the lint: an overlay write (no package) of a list view bound to an object that exists nowhere answers 200 with no issue — validateListViewFieldRefs skips it and no other rule judges a view write's binding #24668 reading.
13. Studio inspector (ObjectFieldInspector.tsx, main's feat(app-shell): Studio authors relatedList, the related-list block's columns/sort/filter, ordered highlight fields, and slotted-by-default record pages #27163 control) — RIGHT, lane remainder read as the schema's first Studio consumer: readRelatedListMode(value, field) reads an absent value through the record page's own predicate isMainContentList, so the control shows what the reader will draw; picking the default clears the key, and "Show" on an inline-edited master_detail writes an explicit true (the only spelling that keeps a side card on this head). Pinned.

② Semver level

Clause-②: yes (widening) — RIGHT, as in round 1, and still right with the door rule: the only refusal it adds bites relatedLists / fieldGroups[].relatedList, keys no stored object could carry before this head (the strict object parse refused them), so nothing previously accepted at the door is refused. Metadata-protocol: semantic — RIGHT (unchanged reasoning). Changeset .changeset/27069-related-lists-order.md now also names @objectstack/lint minor (a new exported rule and a new door verdict), beside spec, platform-objects, app-shell and skills, all minor — RIGHT; both declaration lines are line-initial in the PR body and the changeset; Check Changeset is green on the head.

③ Boundary flags

open_questions: []. The three round-1 out_of_scope_findings are now in the PR (the door rule, the planned row, the ADR amendment). The PR body's acceptance notes on this head:

• "A parent written BEFORE its child exists is refused at the door; write the child's FK first, or add relatedLists after" — CONFIRMED and ACCEPTED. With no closure the snapshot is everything the host serves; a draft child is not served (D1) and the reader would place nothing for it, so refusing is the lint: an overlay write (no package) of a list view bound to an object that exists nowhere answers 200 with no issue — validateListViewFieldRefs skips it and no other rule judges a view write's binding #24668 reading validateListViewFieldRefs already takes. A batch publishing parent and child together is covered by pending.
• "Under a closure that child is not judged; on the CLI an absent child is left to defineStack's artifact scope" — CONFIRMED in narrowObjectsToPackageClosure (limbs: platform/system, no-provenance overlay rows, the written package, its declared dependencies) and in the rule's !fieldsByObject.has(child) && !options?.wholeCollection return; pinned in runtime-gate.object-writes.test.ts.
• fieldGroups[].relatedList ahead of its renderer — CONFIRMED, now a planned row (console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055).
• Bare child name with several FKs orders all of that child's lists — ACCEPTED in round 1, unchanged.
• The PR body's Verification section still cites the round-1 heads (1e4906889, d53bd3312) for its suite and gate runs; the five round-2 commits have no stated local run. Observation only: the check-runs on 8a549c1e are the gate verdicts here, and the new tests are in the shards those runs cover.

④ Design judgment

packages/lint/src/validate-related-list-refs.ts + reference-integrity-suite.ts — the door rule, tried against legitimate saves. It holds:

• A stored sibling parent carries a dangling entry (its child was uninstalled, or it was saved under a closure) and the author saves an unrelated object or flow. The finding is on another entry and identical in baseline and candidate (same rule, where, path, message; siblings keep their index across passes), so it cancels in the differential; the unrelated write is not refused.
• The child's FK comes from an objectExtension (a sibling or downstream package extends the child, or extends a platform object such as a sys_* task with a lookup to the parent). At the door the child row is the registry's folded view, so the FK is present and the parent's entry resolves; under a closure the fold has already happened before narrowing (narrowing drops rows, never fields), and a platform child survives limb 1. On the CLI collectRelatedListNameErrors merges the stack's and the package bodies' objectExtensions, pinned. Not refused.
• Package closure. A child in a downstream package that points in is outside the closure: unjudged, pinned. A child in the written package or a dependency is judged on its folded fields. A platform object with no FK to the parent is refused, which is what the reader does with it (places nothing).
• The write is the child, and it drops the FK a stored parent names. Accepted: the parent's finding reads the same with the child absent (baseline) as with it present without the FK (candidate), so it cancels. The parent's entry then dangles at runtime and the reader places nothing. This is the gate's located-on-another-entry policy, shared with every cross-object member, not a refusal; observation only.
• A polymorphic or array reference, a relatedList: false FK, a self-reference, an entry spelled object.field against a child with one FK. Each resolves exactly as deriveRelatedLists resolves it (string reference equal to the parent name; false is a relationship that exists and is hidden; a self FK is inbound; object.field matches that one FK).
• fields in array form. Not reachable: the written item has passed the object parse (fields is a record there) and registry rows are ObjectSchema-shaped.
• flow writes. The member runs, but objects is identical in both passes, so it can only cost time; no flow write can be refused by it.

No must-fix. The rule's docblock sentence "with the fields their objectExtensions add merged in" describes the CLI shape; at the door the merge is the registry's. Observation, not graded.

packages/spec/src/data/object.form.ts — the two rows and their help texts hold against the tree ("saving or validating the object refuses it" is now true at both doors). One contradiction inside the file:

• S1 (should-fix): the code comment above the relatedLists row (:1268-1272) says the dangling-name check runs "defineStack, so os validate / os build — not at a one-object save". On this head a one-object save IS refused (related-list-ref-unknown, 422); the help text one line below says so. Drop "not at a one-object save" and name the door rule, so the next reader of the form file is not told the opposite of what the row's own help text and the tree do.

skills/objectstack-ui/SKILL.md — the relatedList: 'primary' bullet and the custom-Page list are right on this head. One sentence the head falsifies remains:

• S2 (should-fix): "Related-list layout" (:117-119) still says "each relatedList: 'primary' child gets its own tab; every other related list stacks under a single shared Related tab". On this head an inline-edited master_detail with no relatedList also gets its own tab (isMainContentList), and nothing in this file teaches that default; the read-side intro ("every child relationship is shown as a related list by default (owned master_detail children first)") does not either. The same class as round 1's S1 on relationships.md, which now teaches it correctly and which this file points to. One parenthetical — "(an inline-edited master_detail counts as primary unless it writes relatedList: true)" — paid for inside the paragraph; the ratchet is green with 5 tokens of room on this file.

packages/spec/src/data/object.zod.ts — holds, as in round 1; the gate it must co-exist with (M2) now agrees with it. The relatedLists and group relatedList TSDoc say "refused at defineStack" and do not name the door; true, not complete; not graded.

packages/spec/src/stack.zod.ts — holds; S3 closed as above. The artifact scope handed to the hoisted call is objectNames ∪ artifactObjects when sibling packages are declared and objectNames otherwise, the same set the sibling checks below the early return compute; isPlatformObjectName is a module-level prefix test, so the exemption behaves the same above the line as below.

packages/spec/src/data/field.zod.ts — holds, as in round 1; ADR-0035 and ADR-0085 now record the re-reading (M1 closed).

skills/objectstack-data/rules/relationships.md — holds; S1 closed. The code sample's comment ("read side: a body table (default with inlineEdit)") and the four bullets match isMainContentList and resolveRelatedListOrder line for line.

Cross-cutting, observations not graded: the changeset's @objectstack/skills and @object-ui/app-shell entries describe the Studio control change; the liveness object.relatedLists evidence names both judges (collectRelatedListNameErrors, validateRelatedListRefs), which is the row's authoring half, right on this head. The buildDefaultPageSchema.ts:1003 comment ("Owned-before-lookup order is preserved by deriveRelatedLists upstream") still reads as before this head, non-hit, unchanged from round 1.

Implemented-by: claude/project-thread-vr8ygc
Reviewed-by: session_01WGufzfhobWEgUUrjz4rrbh

VERDICT: PASS

Every round-1 finding (M1, M2, S1-S4) is closed on this head in the tree, not only in the PR body. The door rule refuses nothing legitimate in the scenarios tried (package closure, extension-added FK, sibling dangling entries, child writes, flow writes); its universe is the registry's folded view, which is why the extension case holds. Two should-fixes remain, both copy inside hits files that contradicts the tree (the object.form.ts comment; the SKILL.md layout sentence), neither a must-fix.

席位核对 · ACCEPT (armed) · domain:spec seat 1 (#6017) · session session_01WGufzfhobWEgUUrjz4rrbh · 2026-10-28T13:07Z

Head 897e8d89aff69b18cc77197d807f4cd03cda4d73. Card #27069.

• Contract review:
  • Round 1, 6467460418 at d53bd331: FAIL. M1 was the ADR-0035/0085 amendment; M2 was semantic-roles rules (b)/(d) firing on relatedList groups.
  • Round 2, 6468417631 at 8a549c1e: PASS. Every round-1 finding was judged closed on the tree. The reviewer could not make the new door rule related-list-ref-unknown refuse a legitimate save; the cases tried were a package closure, an extension-added FK, a stored sibling's dangling entry, and flow writes.
• Since round 2:
  • 7f2760da closes both round-2 should-fixes. The object.form.ts comment names the door rule, and the objectstack-ui SKILL.md layout paragraph names the inline-edit default. The ratchet stays green (3843 → 3840).
  • 08cebee8 merges main (no rebase).
  • 897e8d89 fixes what Test Core 4/8 caught on 08cebee8. Metadata-core's FLS scrub had relatedLists unclassified, and it would have over-masked an entry whose child shares a denied field's name. relatedLists and a group's relatedList are now classified keep, pinned against the denied-name fixture, and @objectstack/metadata-core is added at minor. The seat read the hunk. Both keys name child relationships (a child object, or object.field for that child's FK), never a field of this object, so nothing in them is this object's to deny.
  • The seat applied the round-2 body delta, the metadata-core bullet and the final Verification section.
• Dev readings on this head: derived gates 125 run, 0 NOT-MEASURED, all exit 0. Metadata-core passes 845 tests.
• Gates: check-runs on this head are 58 success, 9 skipped and 0 red. Check Changeset and the PR-body guards are re-running after the body edit; auto-merge waits on them.
• Landing: check-governed-merges --pr 27215: GOVERNED (4 of 44 paths: docs/adr/** and skills/**), Tier H. os-zhuang's APPROVED review 5681527416 (at d53bd331, not dismissed) is a governed approval, which lifts Tier H. pr_ready + automerge_enable in this act.