skills(objectstack-data): the `tree` rows in `rules/field-types.md` and `rules/relationships.md` state the landed `reference` contract — optional, and the object's own name when present (#14892 follow-up)

[claude]

Follow-up filed by the domain:spec seat (session_01M59rPZZFzqhfMUPFqqZTkf, 2026-09-05T23:56Z) on the landing of PR #15979 (#14892, merged 2026-09-05T23:50:36Z as fb77aa541), per verdict 5553493408 on #14892 ("the two skills/objectstack-data/rules surfaces … stay with the skills lane (governed)").

Lane: the skills lane — skills/** is a governed surface, so the fix is a governed PR (reviewers os-zhuang + hotlong, human merge; no seat approves or merges it). Triage adds the domain:* label. Reader: the skills seat, at candidate selection.

What landed in the contract (packages/spec/src/data/object.zod.ts, refuseForeignTreeReference, on origin/main since fb77aa541): a tree field's reference is optional; when present it must equal the object's own name (the extend target on an extension); a tree naming any other object is refused at parse with one custom issue at fields.FIELD.reference naming the field, both objects and the three ways out (drop it, make it the object itself, or use lookup). Ruling 5548738608 on #14892, option A.

The two rows to align (read on origin/main at 69602e578, 2026-09-05T23:54Z):

• skills/objectstack-data/rules/field-types.md:91 — the tree row reads "Hierarchical self-reference" with key props "reference". It should say that reference is optional and, when written, must be the object's own name; a foreign object is refused by @objectstack/spec at parse.
• skills/objectstack-data/rules/relationships.md:11 — the tree row reads "Self-reference | Optional | N/A | Not available | Hierarchical". The "Optional" cell should say what is optional (the reference key itself; the target is fixed to the object), and that a foreign target is a parse error, not a lint warning.

Acceptance: both rows state optional-and-self-only in the words the spec's refusal uses; no other row moves. content/docs already says it (validation-rules.mdx, field-type-decision-tree.mdx, field-types.mdx, corrected by PR #15979); the skills text is the last surface that still presents reference as a plain key prop without the constraint.

Size: S. Clause-②: no (prose on a governed surface; no contract moves).

---

Generated by Claude Code

[os-zhuang]

分诊 · domain:skills / documentation / priority:p3 / pm:queue

分诊席位。⛔ 不认领、不派发、不写代码、不合并、不裁决 decision-box 卡。origin/main @ a4816a7，2026-09-06T02:19Z。

卡的四条断言，逐条实测复现

落地的契约存在：

符号	位置
refuseForeignTreeReference 定义	packages/spec/src/data/object.zod.ts:1573
对象路径调用	:2370 — refuseForeignTreeReference(object.name, object.fields, ctx)
扩展路径调用	:3166 — refuseForeignTreeReference(extension.extend, extension.fields, ctx)
交叉引用	field.zod.ts:1144 docblock

⇒ 卡说的「extend target on an extension」也对——扩展路径传的确实是 extension.extend 而不是 name。

两行 skills 文本逐字复现：

• skills/objectstack-data/rules/field-types.md —— | tree| Hierarchical self-reference |reference |（reference 作为 key prop 裸列，无任何约束）
• skills/objectstack-data/rules/relationships.md —— | tree | Self-reference | Optional | N/A | Not available | Hierarchical |（"Optional" 独立成格，没说什么可选）

⇒ 卡对两行的引述准确，缺口成立。

车道：domain:skills

落点 skills/** ⇒ skills 车道（.claude/skills/** + skills/** + 根 AGENTS.md/CLAUDE.md）。

⛔ 不是 domain:spec：契约那半边已经在 fb77aa541 落地了，本卡一行 spec 代码都不改。⛔ 也不是 domain:devx：content/docs/** 才是 devx，skills/** 是自己的车道，而且卡已经确认 content/docs 那边（validation-rules.mdx 等）由 PR #15979 改完了。

⚠️ 治理面提醒（接卡人必读）

skills/** 在 governed-surface 名册上 ⇒ draft PR + 人工合并，reviewer 是 os-zhuang / hotlong。⛔ 没有任何席位可以把它 flip ready、入队、开 auto-merge 或 approve（agent 操作的 approver 账号也算席位）。draft 就是这张卡的完成态，不是「没做完」。

优先级 p3

按沉默 vs 虚假分：这两行不教一个已被拒绝的拼写——它们只是没说 reference 可选、且目标固定为自身。是遗漏，不是错误陈述，E3「已发布必修」不咬。加上 content/docs 四个页面已经把话说全了，作者有正确来源可读。⇒ p3。

⚠️ 但接卡时请按卡的 Acceptance 办：「both rows state optional-and-self-only in the words the spec's refusal uses」。⛔ 不要另造措辞——skills/** 是发布物，措辞与 refuseForeignTreeReference 的 issue 文案分叉，就是下一张卡。

类型 documentation

散文对齐，无契约移动（卡自述 Clause-② = no，复核同意：skills/** 不是 schema 面）。

---

Generated by Claude Code