Pin the derived related-list sort-inheritance rule as contract text in relatedList's .describe() — the #8704 pattern #13294

Activity

1. os-project-manager

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   priority:p2Medium: important, M3Medium: important, M3

   pm:queueReady for the PM dispatch loopReady for the PM dispatch loop

   domain:specDomain lane — seat card indexed by label:pm:seatDomain lane — seat card indexed by label:pm:seat

   needs:contract-reviewMarker only — PR awaits its at-tier Contract review PASS; no check reads it, the record decidesMarker only — PR awaits its at-tier Contract review PASS; no check reads it, the record decides

   on Aug 30, 2026
2. os-project-manager

   added the

   Task

   issue type on Aug 30, 2026
3. os-project-manager commented on Aug 30, 2026

   

   os-project-manager

   on Aug 30, 2026 – with Claude

   CollaboratorAuthor

   More actions

   Triage 审计 · R+34

   定级:documentation · domain:spec · priority:p2 · pm:queue · needs:contract-review · type Task

   锚定:domain:spec —— 读码确认,不是照标题猜

   在 origin/main(7404925)上核过落点:

   • relatedList 声明:packages/spec/src/data/field.zod.ts:1135;
   • feat(spec): no declarative filter for auto-derived related lists — add field-level relatedListFilter so soft-deleted child rows can be excluded without abandoning the auto record page #8704 立下的先例(relatedListFilter 的 .describe() 合同句)就在同一族的 :1190,确认那条 describe 确实承载"AND 合成 / 徽标计数一致"这类被钉住的合同文本 —— 先例成立,可照抄形制。

   ⇒ 落点全在 packages/spec/**,domain:spec 确认。

   ⚠️ 卡里那个行号已经漂了 —— 执行者别用

   卡写「#8704 precedent sits at field.test.ts:602-608 as of that ruling」。今天 :595-615 是 useGrouping 的 describe-pin,不是 relatedListFilter。

   真正要抄的那条在 packages/spec/src/data/field.test.ts:968:

   it('relatedListFilter contract text states AND-composition and badge-count parity', () => {
     const description = FieldSchema.shape.relatedListFilter.description ?? '';
   

   ⛔ 用 git grep -n relatedListFilter -- packages/spec/src/data/field.test.ts 定位,不要用卡里的行号。同族还有 :874–:958 一整组(round-trip、$and/$or/$not 全形、#8793 裸预设门、#8371 点号头、POSITIVE CONTROL)—— 那组是形制的完整样板,新增的 pin 至少要带一条同样的正对照。

   为什么 p2

   四棱:

   • 真实业务需要:中。行为本身已落地并过了浏览器验收(派生相关列表(relatedList:'primary')查询不带 $orderby 且无任何排序声明位;17.0.0 defaultSort 迁移说明与实测矛盾 #11345,2026-08-29),没有东西是坏的;缺的是合同文本。
   • 平台长期正确:高。describe 文本是这个仓库对外的合同陈述面(它同时进 JSON Schema 的 description 和生成的 reference 页),行为只活在实现里而不在合同里,就是下一次回归时没有任何东西会红。
   • 让 AI 写元数据应用不易出错:⭐ 这是本卡的主轴。"派生关联列表继承子对象默认列表视图的 sort"这条规则,一个照着 spec 写应用的作者完全看不见;看不见就会猜,而它有两个反直觉的半边(继承源是默认视图、无排序 ⇒ 不发排序参数而回落记录 id 序)。
   • 创业期聚焦:小而有界 —— 一句 describe + 一条 pin 测试 + 工具重生成 reference 页。

   ⇒ 不是 p1(没有东西坏),也不该压到 p3(便宜、有现成形制、且正落在 AI 出错这一棱上)。

   条款②:PATH 限触发,内容限不触发 ⇒ needs:contract-review,tier claude-fable-5

   采纳卡自己的判断并明确落槌:

   • 内容限 = 否。不改任何 accept/reject 行为;.describe() 是纯散文,zod 的校验语义不动。
   • PATH 限 = 是(packages/spec/src/**)⇒ 打 needs:contract-review,PR 停在 draft 等合同审查链,tier 升 claude-fable-5。
   • ⇒ 因为内容限为否,审查链应当很短:审查者要确认的只有一件事 —— 这句散文陈述的,和 派生相关列表(relatedList:'primary')查询不带 $orderby 且无任何排序声明位;17.0.0 defaultSort 迁移说明与实测矛盾 #11345 验收跑出来的行为,是不是同一件事。

   执行者必须带上的三条实测事实(⛔ 不得凭记忆改写)

   1. 继承源 = 子对象的默认列表视图(isDefault 的展开项;未声明 list 时取第一项),解析器 expandViewContainer 在 ui/view.zod.ts。
   2. 线上拼写是 sort=seq_no / sort=-seq_no —— objectui 的 serializeOrderBy 把 QueryParams.$orderby 降成服务端简写。⛔ pin 测试若断言线形,断言 sort=,不要断言 OData 记号。
   3. 负半边:列表视图无排序 ⇒ 不发排序参数 ⇒ 回落记录 id 序。这一半必须和正半边一起钉,否则又是一条只能朝一个方向失败的断言。

   交付面

   文本面 ⇒ patch changeset;reference 页用工具重生成,⛔ 不手改。

   Refs: #11345(已验收的行为与关闭条件)· #8704(形制)· objectui#6088(实现)

   ---

   Generated by Claude Code
4. claude

   added

   pm:dispatchedDispatched to a dev agent by /pm-dispatchDispatched to a dev agent by /pm-dispatch

   and removed

   pm:queueReady for the PM dispatch loopReady for the PM dispatch loop

   on Aug 30, 2026
5. claude

   assigned

   os-project-manager

   on Aug 30, 2026
6. claude commented on Aug 30, 2026

   

   claudeBot

   on Aug 30, 2026 – with Claude

   Contributor

   More actions

   Claim: domain:spec seat (executive PM), dispatching to an os-dev subagent.

   • Session: session_01KX8wnyjStaZcuMyAMNsy3N
   • Branch: claude/issue-13294-relatedlist-sort-pin
   • Worktree: ../objectstack-13294 (worktree-first; no stash)
   • Domain: domain:spec (text face — describe/JSDoc prose)
   • File surface: packages/spec/src/data/field.zod.ts (the relatedList describe at ~:1135) + a patch changeset (text face ⇒ changeset恒patch) + any regenerated references product of the describe change.
   • Container & model: dispatched at claude-sonnet (pure text-face pin; the rule statement to transcribe is already settled and browser-verified on 派生相关列表(relatedList:'primary')查询不带 $orderby 且无任何排序声明位;17.0.0 defaultSort 迁移说明与实测矛盾 #11345). dispatch-gates.mjs --tier over field.zod.ts: "Model tier — no path-derived mandate… floor sonnet · default opus · ceiling fable. Clause ② SUSPECT surface — packages/spec/src/** — a hint, not a verdict."
   • Clause-②: content limb does NOT fire — describe text only; the set of accepted metadata is byte-identical before and after (语义/文本判据). PATH limb FIRES (packages/spec/src/**) ⇒ the PR parks as DRAFT with needs:contract-review on both carriers; the review chain owns enqueue.
   • Serial constraints: none known — no in-flight PR touches field.zod.ts (hot-file notes cover error-code-ledger.zod.ts only).

   ---

   Generated by Claude Code
7. os-project-manager commented on Aug 30, 2026

   

   os-project-manager

   on Aug 30, 2026 – with Claude

   CollaboratorAuthor

   More actions

   Dev claim: os-dev seat picking up this dispatch.

   • Session: session_01KX8wnyjStaZcuMyAMNsy3N
   • Branch: claude/issue-13294-relatedlist-sort-pin
   • Worktree: ../objectstack-13294

   Starting work.

   ---

   Generated by Claude Code
8. os-project-manager commented on Aug 30, 2026

   

   os-project-manager

   on Aug 30, 2026 – with Claude

   CollaboratorAuthor

   More actions

   os-dev-report

   {
     "issue": 13294,
     "status": "done",
     "branch": "claude/issue-13294-relatedlist-sort-pin",
     "pr": "https://github.com/objectstack-ai/objectstack/pull/13310",
     "premise_still_valid": true,
     "summary": "Pinned the derived related-list sort-inheritance rule as contract text on relatedList's .describe() in packages/spec/src/data/field.zod.ts, following the #8704 relatedListFilter pattern: inherits child DEFAULT list view sort, wire spelling sort=FIELD/sort=-FIELD (never $orderby), negative half (no sort => no ordering param => record-id order). Added two pin tests, a patch changeset, and regenerated the 3 affected reference docs pages. PR opened as DRAFT with needs:contract-review (path limb of clause-2 fires; content limb does not) per the card's landing note.",
     "tests": "At commit 3865d2c7: pnpm --filter @objectstack/spec build (clean, 34/34 .d.ts present); pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/data/field.test.ts -> 203 passed (203), incl. 2 new pin tests; pnpm --filter @objectstack/spec check:generated -> all 14 generated artifacts up to date (after gen:docs regenerated the 1 stale artifact, content/docs/references/**); pnpm --filter @objectstack/spec typecheck -> clean; pnpm check:nul-bytes -> OK, 7360 files scanned.",
     "mcp_calls": 8,
     "open_questions": [],
     "out_of_scope_findings": []
   }

   ---

   Generated by Claude Code
9. claude commented on Aug 30, 2026

   

   claudeBot

   on Aug 30, 2026 – with Claude

   Contributor

   More actions

   ACCEPT — domain:spec seat, session session_01KX8wnyjStaZcuMyAMNsy3N. PR: #13310 (DRAFT, head 3865d2c7, Fixes #13294).

   • Rule pinned on relatedList's .describe() following the feat(spec): no declarative filter for auto-derived related lists — add field-level relatedListFilter so soft-deleted child rows can be excluded without abandoning the auto record page #8704 relatedListFilter precedent: inherits the child object's DEFAULT list view sort; wire spelling sort=FIELD/sort=-FIELD (never $orderby); negative half stated (no sort ⇒ no ordering param ⇒ record-id order). Byte-invariance holds — describe text only, schema shape untouched.
   • 2 pin tests (field.test.ts 203/203 green), patch changeset, 3 reference pages regenerated (check:generated 14/14 up to date), typecheck clean.
   • Clause-②: content limb does not fire; PATH limb fires ⇒ parked DRAFT with needs:contract-review on both carriers (verified: PR and card both labeled). Review chain owns enqueue — this seat will not ready/arm it.

   ---

   Generated by Claude Code
10. hotlong commented on Aug 30, 2026

    

    hotlong

    on Aug 30, 2026

    Contributor

    More actions

    Contract review — PASS (director seat, session local_c32e5a25-0581-4665-952f-60c1be74b250, tier machine-read claude-fable-5 = CONTRACT_REVIEW_TIER). PR #13310's increment is a describe-text pin only — the relatedList union/optionality is byte-identical, so the accept set is untouched; the pinned sentences carry exactly the facts of #11345's browser-verified acceptance run (inheritance from the child's default list-view sort, first-declared fallback, sort=/- wire spelling, no-sort ⇒ no ordering parameter), mirroring the #8704 relatedListFilter precedent with the twin pin test beside it. Contract text catches up to enforced behaviour — declared=enforced in the safe direction. Clearing needs:contract-review on both carriers and landing (ready → queue).
11. hotlong

    removed

    needs:contract-reviewMarker only — PR awaits its at-tier Contract review PASS; no check reads it, the record decidesMarker only — PR awaits its at-tier Contract review PASS; no check reads it, the record decides

    on Aug 30, 2026
12. hotlong

    closed this as completedin #13310on Aug 30, 2026
13. claude

    removed

    pm:dispatchedDispatched to a dev agent by /pm-dispatchDispatched to a dev agent by /pm-dispatch

    on Aug 30, 2026