docs(tasks): autonomous-dev brief names the lookup factory, not the retired reference_to key

[claude]

Fixes #1812

.github/tasks/autonomous_feature_dev.md — the copy-paste brief that puts an agent in the Autonomous Development role — closed with this self-correction bullet:

• Ensure all foreign keys (reference_to) point to valid objects defined in Phase 2.

FieldSchema has no reference_to key. Before that shape was closed the key was dropped silently: the field was still created, minus whatever the author wrote it to constrain, protect or compute. This was the fourth and last site in the repo that taught the retired key to an agent — PR #1809 corrected the other three (AGENTS.md :62, :141, :348 and .github/instructions/metadata.md) and recorded this one as outside its declared file surface.

It is also the worst place for it to have survived: this file is handed to an agent as a whole prompt, and the role file it loads (.github/instructions/architect.md) names no field factory at all — so the brief was the agent's only word on how to spell a relationship.

The change — one line

 **Self-Correction**:
-- Ensure all foreign keys (`reference_to`) point to valid objects defined in Phase 2.
+- Ensure all lookup / master-detail targets (`Field.lookup(...)` / `Field.masterDetail(...)`) name real objects defined in Phase 2.
 - Ensure all ObjectQL queries in Phase 4 match the fields defined in Phase 2.

Plus a changeset with empty frontmatter (agent-facing docs; nothing ships to users).

Wording provenance — mirrored, not a third phrasing

Three files stating one rule three ways is how this class recurs, so every fragment below is lifted from what PR #1809 actually landed:

fragment	source at this commit
lookup / master-detail targets … name real objects	AGENTS.md:141 — "Do all lookup / master-detail targets name real objects?"
(`Field.lookup(...)` / `Field.masterDetail(...)`)	AGENTS.md:62 and :348, verbatim including the punctuation
Ensure all … / defined in Phase 2	the brief's own frame and its own phase anchor, kept

The factory parenthetical is the one addition beyond the bare :141 checklist text. It is declared rather than folded in silently: batch #74 ruled stop teaching a raw key, name the factory, and in this file there is nowhere else for an agent to learn the factory from (architect.md is a file-mapping brief; it is the sibling new-feature.md — not this one — that points at .github/instructions/metadata.md).

Measurement — every zero paired with a control

Repo-wide, at this commit. The five tolerant-alias reads under test/** still match, so a naive zero would have been impossible and a naive non-zero proves nothing; each count below therefore names exactly what was counted.

measurement	before	after
reference_to teaching sites, repo-wide	1	0
reference_to lines under .github/ (whole tree, not just the file)	1	0
control: Field.lookup lines under .github/ — proves the pathspec is live	1	2
reference_to lines repo-wide, all kinds	11	10

The 10 survivors are all non-teaching and deliberately untouched:

• 3 in .changeset/metadata-brief-teaches-the-lookup-factory.md — PR docs: stop teaching the retired reference_to key and an object shape the repo never uses #1809's own release-notes record. Two quote the engine's error; one records this very site as unfixed there. Editing another PR's changeset would rewrite its history, so this PR's changeset closes the loop instead. Both ship in the same release.
• 2 in docs/archive/2026-02/CRM_INDUSTRY_AI_TRANSFORMATION_REPORT.md — an archived February direction under docs/archive/.
• 5 lines across 4 files under test/** — epic Epic: bring this repo's test farm back under the 2026-08-31 ruling — platform-first, os lint --strict first, then retire the local re-implementations by family #1579's fenced territory, untouched by instruction.

⚠️ One correction to the card's own count, offered as a measurement rather than a fix: the card and the dispatch both say five test/*.ts files. git grep -l returns four — lead-duplicate-management.test.ts (2 lines), sharing-coverage.test.ts, view-references.test.ts, and opportunity-line-item-add-picker.test.ts (the now-false comment at :91, not an alias read). Five is the line count, four is the file count. Nothing in test/** was touched either way.

Acceptance notes — found while measuring, NOT fixed here

The dispatch asked for the whole .github/tasks/ directory to be measured, not just the one line. reference_to appears there exactly once (now zero). The sweep did surface two same-shaped defects of different classes, both left alone and filed instead:

1. Filed as .github/instructions/automation.md §1 and .github/tasks/autonomous_feature_dev.md:17 still teach a *.workflow.ts metadata type no installed package defines — #852's class, two surviving sites #1818 — .github/tasks/autonomous_feature_dev.md:17 teaches Automation (.workflow.ts), and .github/instructions/automation.md §1 is a whole section titled Workflow Rules (.workflow.ts). AGENTS.md states there is no workflow metadata type (ADR-0019/0020). Measured here: WorkflowRuleSchema has 0 occurrences under node_modules/@objectstack/ (control: FlowSchema is present in @objectstack/spec/dist), src/** has 0 *.workflow.ts files and 22 *.flow.ts files. Line 17 sits inside this card's file surface, but it is a different defect from reference_to, and the ruled class here is a key, not a file suffix — so it takes the default route: filed, not folded in. AGENTS.md 第 120 行让 agent 用 WorkflowRuleSchema.parse() 校验「Workflows」—— 该导出在平台上不存在 #852 retired the same shape from AGENTS.md; these are surviving sites of that class.
2. Filed as .github/tasks/new-package.md still prescribes the retired packages/ scaffold — #1518's class, the site that card did not reach #1819 — .github/tasks/new-package.md teaches packages/[PACKAGE_NAME]/… scaffolding, a direction AGENTS.md retires by name ("The retired multi-package (packages/*) direction is archived under docs/archive/"), and which .github/workflows/code-quality.yml already calls "a directory this repo does not have". Outside this card's file surface. .github/instructions/architect.md prescribes a packages/ layout hotcrm does not have — in its standing rules and its mandatory Output Format, not only in its worked example #1518 retired the same shape from .github/instructions/architect.md; this is a surviving site of that class.

Both were dedup-searched before filing; the only prior cards are closed (#852, #1518, #1686). Neither is assigned or labelled — they are the PM's to triage.

⚠️ Note for the reviewer of #1818: one of its two sites is the line directly above the one this PR changes, in this very file. It was left alone on purpose. The class ruled by batch #74 is a retired key, replaced by naming its factory; a non-existent metadata type and file suffix is a different class with a different ruled answer (#852), and folding it in would have been an undeclared widening of a card whose landing question is still open.

Deliberately not filed, and not touched: the test/** items above (known, inert, fenced), and the FEATUE typo at line 7 of the same brief (style).

Gates

pnpm verify at 9b6ac5f — exit 0, 187s wall. The code was captured before any pipe (pnpm verify > log 2>&1; EXIT=$?), so it is the chain's own status and not a reader's.

All eight links ran. Verdict lines as each gate printed them:

link	verdict
validate	✓ Validation passed (1552ms) — Data: 18 Objects 331 Fields
typecheck	tsc --noEmit — no diagnostics
lint	1 warning(s), 12 suggestion(s)
lint:i18n-gate	✓ i18n lint gate: 0 i18n/missing-* issues
hygiene	✓ source hygiene clean
hygiene:tokens	✓ source token ratchet clean
build	✓ Build complete (1940ms) — Data: 18 Objects 331 Fields
test	Test Files 165 passed (165) · `Tests 3453 passed

The single lint warning is pre-existing and untouched — page "sales_home_page" · page:card: description is not a prop — and this diff contains no src/ file, so it cannot have moved.

Line budget. This diff is +46 / -1 across 2 files, measured against the branch point 7ddc88b rather than origin/main (which advanced to 5c329c6 under this branch mid-run). The authored-surface token ratchet reads authored total ~137,092 tokens (ceiling ~140,000) — byte-identical to the parent commit, because nothing under src/ moves.

Landing posture

⛔ Draft, and it stays one. ⛔ Not marked ready. ⛔ Auto-merge not armed.

By the letter of AGENTS.md §How a green PR lands, the governed set is AGENTS.md, CLAUDE.md, .claude/**, .github/instructions/** — .github/tasks/** is not in it, so this PR is non-governed and a seat could land it. But it is an agent-instruction surface of exactly the same kind, and the seat has raised that gap with the maintainer rather than deciding it. The flip is the seat's to make; nothing here depends on it happening fast.

维护者速读（草稿）

改了什么 — 只改一句话。.github/tasks/autonomous_feature_dev.md 是发给 AI 的「自主开发」整段提示词,它最后的自检清单要求 AI 检查 reference_to 这个键。该键在平台上不存在,本 PR 把它换成平台真正的写法:Field.lookup(...) / Field.masterDetail(...),用词直接抄 PR #1809 已落地的 AGENTS.md 原文。另加一个空 frontmatter 的 changeset(面向 AI 的文档,不对外发版)。

为什么改 — 这是全仓最后一处还在教 AI 用这个废弃键的地方。危害不是拼写难看:在平台收紧校验之前,写了这个键的字段会被静默创建但丢掉约束 —— 字段在,权限/关联/校验没了,而且没有任何报错。#1686 已修掉另外三处,唯独这份提示词在它的文件范围之外。更麻烦的是,这份提示词加载的角色文件里根本没提字段工厂,所以它是 AI 关于「关联字段怎么写」的唯一信息来源。

风险与代价(含回滚) — 风险接近零:不涉及 src/ 任何元数据,不发版,不改测试。回滚就是 revert 这一个 commit。真正的代价在别处:本次顺带量出两处同类问题(.workflow.ts 这个不存在的元数据类型、new-package.md 教的 packages/ 目录结构),按规矩没有夹带修复,已另立卡片,详见上面的 Acceptance notes。

席位意见 —

你要做的 — 一件事:.github/tasks/** 要不要纳入受管路径(governed set)?它和 .github/instructions/** 是同一类东西 —— 都是发给 AI 的行为指令,写错就是让 AI 系统性地写错元数据 —— 但 PR #1798 定的受管清单里没有它。您说纳入,以后这类 PR 就由您合并;您说不纳入,席位按普通 PR 处理。在您回话之前,本 PR 保持 draft 不动。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 9, 2026 12:30pm UTC