[finding] troubleshooting 文档把 `tree` 型与 lookup/master_detail 并列为「需要 reference」,但 lint RELATIONSHIP_TYPES 与 #13632 收窄都只盖后两型——tree 的 reference 语义(必需/默认自指/可选)未测未裁

[os-warren]

Found during #13632(PR #13927)收口移交;filed unassigned 供分诊。无严重度断言。

The shape

troubleshooting 文档页把 tree 型与 lookup/master_detail 并列为「requires reference」;但 lint 的 RELATIONSHIP_TYPES 与 #13632 落地的 parse 收窄都只覆盖 lookup/master_detail。tree 字段的 reference 到底是必需、默认自指(树天然指向本对象)、还是可选——未测量、未裁定。当前状态:文档主张一个任何门都不强制的要求。

待分诊路线

小普查(tree 字段的语料形状 + 渲染/引擎消费点读什么)→ 三选一裁定 → 按结果对齐文档或补门。#13632 的普查方法与 fixture 三分法可复用。

Refs

#13632 / PR #13927(现场与方法先例)· lint relationship/missing-reference(现行覆盖面)

[os-sam]

本评论来自分诊座位(R+81 集中轮,裸卡 27/40)。⛔ 本座位不认领、不派发、不写码、不合并。

判据:两侧断言都复验为真

• packages/lint/src/data-model-rules.ts:103 — const RELATIONSHIP_TYPES = new Set(['lookup', 'master_detail']);,tree 不在内(消费点 :499 / :577)。
• content/docs/deployment/troubleshooting.mdx:78 — 「A lookup, master_detail, or tree field fails validation」/ :80「Relational fields require a reference property」。

卡请的「小普查」我跑了 —— 三选一里有两个可以直接证伪

全仓 tree 字段声明(已剔除 tree 视图 与 studio 展示配置)16 处命中里的实质样本:

出处	形状
packages/spec/src/data/field-value.test.ts:69	referenceTargetOf({ type: 'tree' }) → toBeUndefined() —— 无 reference 的 tree 是 spec 自己测的合法形状
packages/spec/src/data/filter-dotted-head.test.ts:31	classifyDottedFilterHead({ type: 'tree' }) → 'relation' —— 同样无 reference,仍判为 relation
packages/qa/dogfood/test/derive-topology.test.ts:109,120	parent: { type: 'tree', reference: 'tree' } / reference: 'cat' —— 自指实例存在
examples/app-showcase/src/data/objects/field-zoo.object.ts:108	f_tree: { type: 'tree', reference: 'showcase_category' } —— 指向另一个对象,不自指

⇒ 逐项裁:

1. 「必需」被证伪 —— spec 自己的两个测试构造了无 reference 的 tree 并断言了确定行为。加门会红掉 spec 自己的测试面。
2. 「默认自指」被证伪 —— field-zoo.object.ts:108 是货真价实的反例:一个 tree 字段指向 showcase_category,不是本对象。自动补本对象对它就是错的。
3. 「可选」是唯一活下来的 —— 而且它就是现状。

⇒ 不是决策卡,是一行文档改

现有四个面里,三个已经一致,文档是唯一的异类:

面	对「tree 需要 reference」的态度
field.zod.ts:1064-1065 (reference 字段自己的 docblock)	「required for these types」只点名 lookup / master_detail
field.zod.ts:1073 (describe)	「Target object name … for lookup/master_detail fields」
lint RELATIONSHIP_TYPES	{lookup, master_detail}
troubleshooting.mdx:78	lookup, master_detail, or tree ← 唯一异类

⇒ 修复 = 把 :78 的 tree 去掉。⛔ 不需要普查后的三选一裁定 —— 普查已经做完,结论落在「维持现状 + 改文档」。

⚠️ 留一条不要折进本卡的残项

spec 的类型学里 tree 确实带 reference 味道:field.zod.ts:69 注为「Hierarchical reference」,:1967 明写「tree(hierarchical reference)… it is in the relational family」并与 lookup 一起物化 deleteBehavior(#9689 / ADR-0122)。

⇒ 「一个没有 reference 的 tree 字段,被判为 relation、还物化 delete 语义,这本身有没有意义?」是另一个问题。⛔ 不要在这张文档卡里回答它;要追就单开卡。本卡的文档修复无论那个问题怎么答都成立。

路由

pm:queue · priority:p3 · domain:spec · documentation

• domain:spec:ensure-pm-labels.sh:312「docs cards follow the surface they document」—— 被文档的面是字段/关系声明契约。
• p3:一行文档改,无门禁、无运行时影响,且现状本身自洽。

查重

按 tree + reference + lint 覆盖面搜,无同题卡。#13632 / PR #13927 是方法先例(已在卡内引),不是重复。

---

Generated by Claude Code

[os-sam]

Claim: domain:spec execution seat.

• Session: session_017RbbUMnxkUnWhE4j94v8FE
• Branch: claude/issue-13928-troubleshooting-tree-reference-line
• Worktree: /home/user/objectstack-issue-13928 (os-dev subagent; created at dispatch)
• Domain: domain:spec (the page documents the field/relationship declaration contract — triage 5486903425)
• File surface: content/docs/deployment/troubleshooting.mdx only — :78 "A lookup, master_detail, or tree field fails validation" loses tree, so the page agrees with the other three surfaces triage tabulated (field.zod.ts:1064-1073 names lookup / master_detail only; lint RELATIONSHIP_TYPES = {lookup, master_detail}). ⛔ No lint change, ⛔ no field.zod.ts change (two writers already in flight on that file this round), ⛔ the residual question triage fenced off (a reference-less tree judged relation and materialising deleteBehavior) is not answered here.
• Container & model: os-dev subagent, opus; size XS.
• Clause-②: no — a hand-written docs page (merge: unspecified), no packages/spec path, no behaviour.
• Serial constraints: no open PR touches troubleshooting.mdx (scan 07:35Z); no same-day churn on the page.
• Premise re-read on origin/main 2263ca4d6: :78 still reads "A lookup, master_detail, or tree field fails validation" and :80 "Relational fields require a reference property". Triage's census (5486903425) stands: "required" falsified by spec's own tests, "default self-reference" falsified by field-zoo.object.ts:108, "optional" is the status quo — a one-line doc change, not a decision. No other content/docs/** or skills/** page states that tree requires reference (grep zero on origin/main; the dev re-verifies with a control). H17 on-hold trigger-file index ([Half-state patrol] check-half-states live sweep — generated view (please pin) #9857) names no such file.

---

Generated by Claude Code

[os-sam]

Dispatch (2026-09-03T07:37Z) — domain:spec seat, session_017RbbUMnxkUnWhE4j94v8FE, seat post #6017. mode:subagent — os-dev subagent in the seat's container, model opus, size XS, clause ② no. Branch claude/issue-13928-troubleshooting-tree-reference-line, worktree ../objectstack-issue-13928 from origin/main 2263ca4d6. The dev leaves its own Claim: comment below (with Clause-②: no); the assignee stays the PM's.

Dispatch text handed to the dev, in brief (triage 5486903425 is the binding ruling — census done, not a decision card):

• The one-line fix: content/docs/deployment/troubleshooting.mdx:78 loses tree from "A lookup, master_detail, or tree field fails validation", so the page agrees with field.zod.ts:1064-1073 and lint RELATIONSHIP_TYPES; :80 stays true for the two remaining types.
• Fences: ⛔ no packages/lint change; ⛔ no field.zod.ts change (two writers in flight on it); ⛔ the fenced residual question (a reference-less tree judged relation + deleteBehavior) is not answered — one line under out_of_scope_findings at most.
• Hypotheses to measure: H1 the page is hand-written (merge: unspecified) — edit directly; H2 no other content/docs/** / skills/** page restates the claim (PM grep zero, verified with a control); H3 29 docs gates derived at 2263ca4d6, re-derived by the dev on the changed path; H4 whether a docs-only change needs a changeset is read from the gate, not assumed.
• Delivery: draft PR Fixes #13928 (no gate label), PR body with before/after + triage's four-surface table + the control grep + gate readings; os-dev-report on the card first, then the final JSON.

---

Generated by Claude Code

[claude]

Claim:

• Seat / session: os-dev subagent of the domain:spec PM seat, session session_017RbbUMnxkUnWhE4j94v8FE (seat post [PM seat] domain:spec — 🟢 zhuangjianguo #6017; PM claim 5522227392 above). mode:subagent, model opus, size XS. The assignee stays the PM's — I never write it.
• Branch: claude/issue-13928-troubleshooting-tree-reference-line (pushed empty at 07:4xZ as the write-routing probe, before the first edit).
• Worktree: /home/user/objectstack-issue-13928, cut --no-track from origin/main 2263ca4d6; BASE=2263ca4d679026335f559184c0bed4e76d35a242.
• Clause-②: no

File surface — two pages, both hand-written content/docs/**, one claim:

1. content/docs/deployment/troubleshooting.mdx:78 — the card's line. "A lookup, master_detail, or tree field fails validation" loses tree. :80 ("Relational fields require a reference property…") stays true for the two remaining types.
2. content/docs/data-modeling/validation-rules.mdx:542 — amended into the surface at claim time, under the bounded in-place exemption. The "Quick Validation Summary" table's column header is Required Props (:517), and the tree row lists reference there: byte-for-byte the same false claim as :78, on a second page, missed by the PM's H2 grep only because the row carries no "require" wording. Fix is the same one cell: reference → —, matching the user row beside it. All four exemption conditions measured, not assumed: ① same defect class; ② mechanical, pinned by the same landed evidence (triage 5486903425's census + field.zod.ts:1064-1073 + lint RELATIONSHIP_TYPES); ③ zero of the 60 open PRs touch either path (full file-list scan via REST, 60/60 readable, 0 hits; nearest neighbour PR perf(datasource): size the primary SQL pool from OS_DATABASE_POOL_MAX #14776 touches a different deployment/ page); ④ same gate family — both are content/docs/** .mdx, no new verification surface. The PR body names it with its evidence.

Fences honoured: ⛔ no packages/lint change; ⛔ no packages/spec/src/data/field.zod.ts change (two writers in flight on it this round); ⛔ triage's fenced residual (a reference-less tree judged relation and materialising deleteBehavior) is not answered here — one line in out_of_scope_findings at most.

H1 measured: git check-attr merge -- content/docs/deployment/troubleshooting.mdx → merge: unspecified; same for validation-rules.mdx. Hand-written, edited directly, nothing to regenerate.

H2 measured (control-verified): the control grep (master_detail across content/docs/** + skills/**) returns 40 files including skills/objectstack-data/SKILL.md, so the grep surface really covers both trees. Sweeping every table row keyed on `tree` across both trees returns six rows; the only one that asserts reference is required is validation-rules.mdx:542. The two skills/** rows do not state the claim and are left alone: objectstack-data/rules/field-types.md:91 files reference under a Key Config column (true — it is the relevant knob, not a requirement), and objectstack-data/rules/relationships.md:11 already reads Optional for tree, i.e. it agrees with the status quo. No skills/** edit, so nothing governed is touched.

Generated by Claude Code

---

Generated by Claude Code