docs(agents): keep only what is necessary — metadata-application principle first, rules not narratives, no inventories; add CLAUDE.md pointer; correct the two *.workflow.ts briefs

[os-justin]

Fixes #1823
Fixes #1745
Fixes #1620
Fixes #1618
Fixes #1818
Fixes #1681

Maintainer direct instruction to the skills seat, 2026-09-09, verbatim and untranslated:

「看一下 hotcrm 的agents.md 写的太乱了。只留下必要的。包括同时同时审核 hotcrm 的skills 任务，合并派发处理。」

「首先要明确 hotcrm 是元数据应用，平台功能应该在 objectstack中开发。 其次 claude.md 是不是直接让他阅读 agents.md 即可，没必要维护两套。所有仓库都有类似的问题」

One fold of six cards, landing as one rewrite of AGENTS.md, one new root CLAUDE.md, and #1818's two brief sites (its own commit, 0f446c1). Governed surface (AGENTS.md, CLAUDE.md, .github/instructions/**; .github/tasks/** treated as governed) — this PR stays a draft for the maintainer's own merge; skip-changeset applied (nothing shipped to users moves: the repo is private: true with no files[]).

Line budget (measured at 0f446c1): AGENTS.md 651 → 248 lines (a 61% cut; budget ≤ 250). CLAUDE.md 6 lines. .github/instructions/automation.md 64 → 46 lines; .github/tasks/autonomous_feature_dev.md unchanged at 23 lines, one line rewritten.

维护者速读（草稿）

改了什么

• AGENTS.md 从 651 行重写为 248 行：开篇即「HotCRM 是元数据应用，平台功能在 objectstack 开发」（两段裁决原文保留）加原有 🚫 Scope 四条；其后每条规则只留一到三行「规则 + 失败形态」。度量记录、「本文件曾说……」类的历史、来源轶事、「Supersedes …」尾注和先例名册全部移出（卡片与 ADR 是档案，每条规则最多保留一个引用）。
• 手抄清单全部删除：12 个文件后缀的名册（AGENTS.md File Suffix Protocol is an inventory that drifted both ways: 4 of its 12 declared suffixes have zero instances in src/, and 8 suffixes the app really authors are absent from it #1745）改为「照邻居文件写、三种编写形态」并指向 src/{type}/；规则 5 自己的漂移计数与名册（AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620）、图表类型清单、crm_ 名册历史都不再出现。
• 规则 6 按真实宽度重写（AGENTS.md rule 6 says "UI nouns take the zh-CN pack wording", but a pack-carried noun that is not a list view must stay English — and only an ablation reveals it #1618）：列表视图名取 zh-CN 语言包措辞；其它语言包也携带的 UI 名词（仪表盘磁贴、仪表、数据集度量、仪表盘自身标签）保持英文；判据是守卫的消融而非语言包是否携带；度量类同族但目前无守卫（写明，不建守卫）。
• 平台升级章保留步骤 1–4，新增第 5 步（AGENTS.md → Platform Upgrades has no step for re-scoping the claims that name the old pin — which is why #1460, #1467 and #1676 are the same card three times #1681，两行）：只改范围不改版本号、版本无关且跨行搜索、命中是候选需人工分类、诚实说明 grep 抓不到什么、标识符与人类可读标签同时搜。
• .github/instructions/automation.md §1 与 .github/tasks/autonomous_feature_dev.md 第 17 行不再教 *.workflow.ts（.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），措辞照抄 AGENTS.md 的「没有 workflow 元数据类型」段；automation 的示例（object: 'lead' 漏 crm_ 前缀）一并删除。这两个文件只动这两处。
• 新增根目录 CLAUDE.md：只指向 AGENTS.md，不复述任何规则（按 .github/copilot-instructions.md 的指针模型；[program] CLAUDE.md is a pointer to AGENTS.md in every repo — no second instruction set to maintain (maintainer 2026-09-09) objectstack#17161 项目锚）。

被移除的每一节的去向：

旧节	处置
🗣️ 沟通语言	规则保留于 🗣️ 沟通语言（压缩为一段双语）
🏗️ Project Architecture（目录树 + 退役 packages/ 说明）	规则保留于 🏗️ Project Architecture；目录树保留（test/docs-src-tree-paths.test.ts 解析它）
💻 Tech Stack 1 Metadata-First（含 crm_ 长段）	规则保留于 Tech Stack 1–2
💻 Tech Stack 2 ObjectQL（where/filter 度量叙事、「Superseded」段、「Measured … (17.2.0)」、flow/page 的 filter 形态）	规则保留于 Tech Stack 3 两条要点；度量记录、被取代主张的历史、「(17.2.0)」现在时 pin 声明：叙事，删除
💻 Tech Stack 3 AI-Native	规则保留于 Tech Stack 4（并入 skills-only、⛔ *.agent.ts）
🧠 Autonomous Iteration Protocol（三阶段）	叙事，删除（其清单项已由 Tech Stack 与 Schema Validation 覆盖）
📝 Coding Standards（File Suffix Protocol：Core + Extended 12 项）	手抄清单，删除（#1745）；邻居文件规则与三种形态保留于 🔒 Schema Validation Requirements
🔒 Schema Validation Requirements（三形态、执行点、bogusUnknownKey 度量记录、barrel、parse()、「无实例」名册、workflow 说明）	规则保留于同名章；bogusUnknownKey 记录与「无实例」名册：叙事/清单，删除
🏷️ Field Type Guidance（两张表）	规则保留为一张表
🧩 Metadata semantics 7–11 + 逃生仓裁决（含先例引用块）	规则保留（裁决原文保留）；先例名册缩为每条一个引用
🚀 Development Workflow	叙事，删除（与后缀规则重复）
⚠️ Constraint Checklist（含「Supersedes」尾注、Tone、No Engine Code、ADR-0048 命名注记）	五条规则保留；「Supersedes」尾注、Tone、命名注记历史：删除；No Engine Code 并入 Architecture；ADR-0048「advisory、勿批量改名」保留为 Tech Stack 2 的一句
Validation predicates must be TOTAL（含 rc.1/rc.2 日志块）	规则保留于同名节，两行 has() 表保留；日志记录删除
Documentation discipline 5（漂移计数 + 名册）	规则保留；计数与名册删除（#1620），保留一个引用
Documentation discipline 6	规则保留并按真实宽度改写（#1618）
⬆️ Platform Upgrades 1–4 + 「merged 不等于可用」注	规则保留 1–4 并压缩，新增第 5 步（#1681）；该注并入 Scope 规则 2
🚫 Scope 1–4（先例名册）+ Out of scope 清单 + Focus Area	规则保留为开篇章；先例名册缩为每条一个引用；Out of scope 清单并入规则 1 的一句
⚖️ Ruling discipline 12	规则保留
✅ Verify before opening a PR（「Supersedes」尾注、ADR-0021 轴说明）	规则保留；尾注删除；ADR-0021 缩为一句
Every PR carries a changeset	规则保留
How a green PR lands（裁决引用块：#1742 / #1233 / #1815 与 #1798 的来龙去脉）	规则保留于同名节；裁决历史删除，留一个引用
Verifying UI in the browser（规则 + 图表类型清单 + Origin 轶事）	规则保留为三步；图表类型清单与来源轶事删除
Other browser-verify gotchas	三条保留为一段

为什么改

维护者 2026-09-09 直接指示：agents.md 太乱，只留必要的；claude.md 直接让读 agents.md，不维护两套。651 行的指令文件里，度量记录和历史叙事让真正的规则难以被 AI 读到；手抄清单已被本仓自己的卡片证明会双向漂移（#1745：12 个后缀 4 个零实例、8 个真实后缀未列）。

风险与代价（含回滚）

• 风险：删掉的叙事里可能有某条对某个读者仍是负担性的。已对树实测：读取 AGENTS.md 的三个测试（zh-Hant 理由、目录树、角色层级词表）与 docs/MAINTENANCE.md、CONTRIBUTING.md、docs/architecture/module-split-plan.md 引用的节名全部保留并复跑绿。
• 代价：只有一份文件；CLAUDE.md 不再有任何摘要，只读 CLAUDE.md 的会话在读到指针之前没有规则（本仓无 hooks 作底，这是 objectstack#17161 已记录的已知成本）。
• 回滚：整个 PR 是三个文件的纯文档改动，git revert 两个提交即可，无数据、无元数据、无发布物变动。

席位意见

（留空，席位定稿成评论。）

你要做的

1. 读一遍新的 AGENTS.md（248 行），确认「只留下必要的」的取舍符合你的意图，尤其是上表中标「删除」的项。
2. 确认 skip-changeset 对本 PR 成立（此前同类 AGENTS.md PR 用的是空 frontmatter changeset，两者门禁等价）。
3. 合并（治理面，人工合并）。

Per-member acceptance

• AGENTS.md: keep only what is necessary — metadata-application principle first, rules not narratives, no hand-copied inventories; add a one-line CLAUDE.md pointer (maintainer 2026-09-09) #1823 — AGENTS.md rewritten top-down from the necessity test: 651 → 248 lines; first principle first with both rulings verbatim; rules not narratives; no hand-copied inventories; new CLAUDE.md pointer. Every kept line is addressed to the agent reading the file.
• AGENTS.md File Suffix Protocol is an inventory that drifted both ways: 4 of its 12 declared suffixes have zero instances in src/, and 8 suffixes the app really authors are absent from it #1745 — the 12-suffix File Suffix Protocol leaves the file (4 declared suffixes had zero instances, 8 authored ones were absent); the trimmed file states the neighbour-file rule and the three authoring forms and points at src/{type}/. No suffix roster is restated anywhere in the new file.
• AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620 — premise re-checked on origin/main 965933b: PR docs: stop teaching the retired reference_to key and an object shape the repo never uses #1809 moved the bullet; the "drifting four times" sentence and the ledger stood at AGENTS.md:412–418, not :348/:353. Executed per this fold's ruling (rule 5's own drift count and precedent ledger leave; the rule keeps one ref, #1620): the sentence now says "measured it drifting repeatedly". Deviation noted for the maintainer: the repo:hotcrm seat's grading on AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620 (5555833480) had ruled the roster be kept and extended; the later maintainer instruction 「只留下必要的」 and this fold's ruling 3 supersede it, and the cards remain the archive.
• AGENTS.md rule 6 says "UI nouns take the zh-CN pack wording", but a pack-carried noun that is not a list view must stay English — and only an ablation reveals it #1618 — rule 6 now states its real width: list view names take the zh-CN pack wording; dashboard and tile titles, gauges, dataset dimensions and measures, sharing-rule names and the dashboard's own label keep English; test/docs-dashboard-tiles.test.ts is named as the tile guard; measures are named as the same class, currently unguarded — no guard built (Scope rule 3, 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 step 6).
• .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 — both sites corrected in their own commit 0f446c1, mirroring the AGENTS.md wording; the object: 'lead' example is gone with the section. Re-measured before editing: WorkflowRuleSchema files under node_modules/@objectstack/ = 0 (control FlowSchema under spec/dist = 34); *.workflow.ts under src/ = 0 (control *.flow.ts = 23). Nothing else in either file moved; §2 and §3 of automation.md untouched.
• AGENTS.md → Platform Upgrades has no step for re-scoping the claims that name the old pin — which is why #1460, #1467 and #1676 are the same card three times #1681 — step 5 added in the shape its thread settled (5558732623 / 5558770183 / 5558918648), in two lines: re-scope never renumber; version-agnostic and cross-line; identifiers and labels; hits are candidates classified by hand with [finding] The 17.3.0 upgrade left 19 comments asserting 17.2.0 is "the pinned" version — third recurrence of #1460 / #1467, and #1669 names only 1 of the 13 files #1676's criterion; honest about what a grep cannot see. No literal version and no grep is written into the step. Its Restart-when named the AGENTS.md §🔒 Schema Validation Requirements: all seven items prescribe an XSchema.parse() call the repo makes nowhere — item 1 names the wrong method, and the section's premise sentence is false as written #1573 / AGENTS.md rule 6 says "UI nouns take the zh-CN pack wording", but a pack-carried noun that is not a list view must stay English — and only an ablation reveals it #1618 / AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620 chain: AGENTS.md rule 6 says "UI nouns take the zh-CN pack wording", but a pack-carried noun that is not a list view must stay English — and only an ablation reveals it #1618 and AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620 clear inside this fold. Its absorbed half (b) — the Tech Stack item-2 sentence "Measured per method against the pinned @objectstack packages (17.2.0)", AGENTS.md still says the pinned @objectstack packages are 17.2.0 — the same claim #1676 re-scoped everywhere else, in the file agents read first #1688, already closed 2026-09-06 — is resolved by removal: the where-rule is now version-free and points at test/hook-query-predicate.test.ts instead of carrying a pin claim.

Acceptance notes

Gates run locally (all at 0f446c1, docs-only diff):

• pnpm hygiene — exit 0, ✓ source hygiene clean (its byte scan reads AGENTS.md via ROOT_TEXT_FILES).
• pnpm validate — exit 0, ✓ Validation passed, Data: 18 Objects 331 Fields, Runtime: 0 plugins (unchanged; nothing under src/ moves).
• Targeted vitest under the shared verify lock — the five suites that read AGENTS.md (docs-zh-hant-justification, docs-src-tree-paths, docs-role-hierarchy, docs-declared-versions, docs-object-coverage): Test Files 5 passed (5), Tests 80 passed (80), VERDICT command-exit 0. One red on the first run — my own wording "subordinate to this one" tripped the role-hierarchy vocabulary guard — fixed before commit.
• Control-byte self-scan of the four changed files: no hits.
• Narrowing declared: pnpm verify in full was not run (typecheck / lint / build / the whole test suite read src/ and test/, which this diff does not touch; the three suites that parse AGENTS.md plus two that cite it ran). link-check — NOT MEASURED locally: markdown-link-check is not installed in this container and the workflow's action is not runnable here; CI runs it on this PR (the diff carries .md). The only links in the new files are relative (./AGENTS.md, docs/README.md, docs/archive/) and the release-notes URL kept from the old file.

External readers of section names, kept: docs/MAINTENANCE.md cites "§⬆️ Platform Upgrades step 4" (step 4 is still the changeset step) and "Verifying UI in the browser"; CONTRIBUTING.md cites "§How a green PR lands"; docs/architecture/module-split-plan.md cites "A platform defect means you WAIT for the platform fix", "Do not build platform-level tooling", "Documentation discipline item 5", "Project Architecture", "Platform Upgrades"; src/** comments cite "house rule 9", "metadata rule 8", "scope rule 3", "Validation predicates must be TOTAL", "Constraint Checklist → Dependencies" — all headings and rule numbers unchanged. test/docs-zh-hant-justification.test.ts parses the zh-Hant bullet by its opening text — kept byte-identical; test/docs-src-tree-paths.test.ts requires the file to draw a src/ tree — kept, every drawn directory exists.

Overlap of the other .github/instructions/*.md with AGENTS.md (reported, not edited — outside this fold's surface):

• architect.md — consistent with AGENTS.md (flat src/{kind}/, no workspace layout; .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). Its planned file names drop the crm_ prefix only in the object name column that it does not show; no contradiction.
• metadata.md — §1/§2 agree with AGENTS.md (explicit crm_, named export, ObjectSchema.create). §3 teaches validation: [{ formula: … }]; measured at 0f446c1 on the installed spec: ObjectSchema.create rejects it — unknown key(s) — validation — while the real validations[] form (control) is accepted; zero objects under src/ spell it that way. Same class as .github/instructions/metadata.md teaches reference_to: (an unrecognized key — the spec prescribes reference) and an ObjectSchema import/export shape the repo never uses #1686 (the reference_to key this file taught). Filed, see below.
• security.md — teaches .role.ts, .permission.ts and .rls.ts files (0 instances each under src/; AGENTS.md names *.permission.ts as authored nowhere) with an unprefixed object: 'account'; only §4 .sharing.ts is a real type. Same class 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. Filed, see below.
• ui.md — teaches export default view/action/dashboard literals with unprefixed object: 'account' / 'opportunity', where AGENTS.md says views are defineView() named exports registered through the barrel; .report.ts in §4 is real (5 files). Same class; included in the filed card.
• automation.md §3 — teaches .trigger.ts (0 instances under src/; TriggerSchema does exist in @objectstack/spec). Outside .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's ruling; included in the filed card as a question rather than a defect.
• logic.md — not re-measured here (10 KB; .github/instructions/logic.md points its action example at packages/crm/src/ — a layout hotcrm does not have, and no gate covers that directory #1233 already gates its paths).

Findings filed / noted: filed as #1832 — the remaining briefs (security.md, metadata.md §3, ui.md, automation.md §3) teaching forms the app authors nowhere or the spec rejects, same class as #1818; filed as #1833 (Blocked-by: #1830) — CLAUDE.md is a new root text file outside scripts/lib/source-hygiene-surface.mjs ROOT_TEXT_FILES, so the hygiene byte scan does not read it — that list's own comment says a new first-class root file must be added there; not done in this PR because it is a gate-surface edit outside the declared file surface. Noted, not filed (承接者: whoever takes #1819): src/objects/index.ts's header comment still mentions *.state.ts state machines "auto-associated by naming convention" — 0 such files exist.

Changeset: skip-changeset label (ruling C). Precedent: PR #1820 / #1798 used an empty-frontmatter changeset for the same "AGENTS.md only" case; the workflow treats the two as equivalent.

---

Generated by Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01MoTv7pn338AZ71owsp19gQ

---

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 2:23pm UTC

[os-justin]

维护者速读 — hotcrm PR #1830(#1823 折叠 #1745 #1620 #1618 #1818 #1681,skills 席终稿,2026-09-09T14:30Z)

改了什么 — AGENTS.md 651 行重写为 248 行(削 61%):你的两句裁决原文开篇(「hotcrm 是元数据应用，平台功能应该在 objectstack中开发」+ 8/31 那句),🚫 Scope 四条成为第一章;其后每条规则只留一到三行「规则 + 失败形态」,度量记录、「本文件曾说」历史、来源轶事、Supersedes 尾注、先例名册全部移出(每条最多留一个卡号);手抄清单全删(12 后缀名册 #1745、规则 5 的漂移计数与名册 #1620、图表类型表、crm_ 名册史),改为「照邻居文件写、三种编写形态、看 src/{type}/」;规则 6 改成真实宽度(#1618:只有列表视图名取语言包措辞,其它语言包也带的名词保持英文,判据是守卫的消融);升级章加第 5 步两行(#1681);两处 *.workflow.ts 简报改正(#1818);新增 6 行 CLAUDE.md 只指向 AGENTS.md。PR 正文附「每一旧节的去向」表(规则留在哪 / 叙事删除),供你逐行核。⛔ 未动:.github/tasks/new-package.md(#1819 在你的决策箱)。

为什么改 — 你的直接指示:agents.md 太乱,只留必要的;claude.md 直接让读 agents.md,不维护两套;并同时把 hotcrm 的指令面任务合并派发。651 行里叙事与手抄清单淹没规则,而清单已被本仓自己的卡证明会双向漂移。

风险与代价(含回滚) — 删掉的叙事里若有对某个读者负担性的句子:dev 实测读 AGENTS.md 的五个测试套件 80/80 绿,docs/MAINTENANCE.md 等引用的节名都保留;pnpm validate 不变(18 对象 / 331 字段 / 0 插件)。已知代价:本仓无 hooks 托底,只读 CLAUDE.md 的会话在读到指针前没有规则(程序卡 objectstack#17161 已记录)。一处判断需你留意:hotcrm 席此前对 #1620 的分诊要求「保留并扩充规则 5 的漂移名册」,本 PR 按你后来的「只留下必要的」删掉了名册、留一个引用——维护者裁决优先于席位分诊,写在 PR 的 #1620 验收行。回滚 = revert 两个提交。

席位意见 — 接受。本席在分支头通读了新 248 行:第一原则开篇、七条裁决逐条成立、无手抄清单、目录树因 test/docs-src-tree-paths.test.ts 解析它而保留并说明;*.workflow.ts 教学点残留 0;merge-tree 干净;控制字节 0;CI 7 绿 / 1 跳过 / 0 红(全部完成)。dev 顺手立了两张卡交 hotcrm 席分诊:#1832(另外四处 .github/instructions 章节教不存在的形态)、#1833(新 CLAUDE.md 不在 hygiene 扫描根列表,一行修复,等本 PR 合并)。

你要做的 — 读一遍新 AGENTS.md(248 行)与「去向表」里标「删除」的项;认可 #1620 名册删除;skip-changeset 对本 PR 成立(同类前例用空 frontmatter changeset,门禁等价);人工合并(受管面,席位不翻 ready、不入队、不挂 auto-merge)。

---

Generated by Claude Code