[objectstack-fleet]

Requested by Leehom · project thread

Fixes #28954

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：脚手架生成的 AGENTS.md 里「Project Structure」目录树，现在只列 objectstack.config.ts 真正加载的 8 个目录（objects、views、actions、flows、dashboards、apps、skills、picklists），去掉了从不加载的 reports/、agents/、i18n/、handlers/，并加一句：新目录必须在 config 里接线，否则既不加载也不被 validate 检查。另加一条包内测试，把这棵目录树和模板 config 的 barrel 导入对齐。
• 为什么改：按「Build with Claude Code」路径的新手，coding agent 先读 AGENTS.md，再照着目录树写元数据；写进那四个死目录的东西不会加载，npm run validate 还照样通过，用户以为是 AI 写坏了。
• 风险与回滚：极低。只改模板里的说明文字和一条测试，config 加载什么完全不变；已生成的项目不受影响。回滚即撤销本 PR。
• 先看：packages/create-objectstack/src/templates/AGENTS.md（Project Structure 一节）；packages/create-objectstack/src/agents-project-structure.test.ts（新增的对齐测试）。
• 两分钟验证：pnpm --filter create-objectstack exec vitest run src/agents-project-structure.test.ts，预期 3/3 通过（main 上 2 条红：多出 agents/handlers/i18n/reports，缺 picklists/skills）。
• 需要你做的：无，席位落地。

Why

A newcomer on the "Build with Claude Code" path has a coding agent read AGENTS.md before it writes any metadata. The block told the agent to put reports in src/reports/, AI agents in src/agents/, translations in src/i18n/ and hooks in src/handlers/. The scaffolded objectstack.config.ts imports none of those, so what the agent wrote there was never loaded, and npm run validate neither counted nor checked it (the card's repro: an invalid report there, ✓ Validation passed).

What changes

• packages/create-objectstack/src/templates/AGENTS.md, the Project Structure block. The src/ tree now lists exactly the eight directories the config wires, in the config's order: objects/, views/, actions/, flows/, dashboards/, apps/, skills/, picklists/. reports/, agents/, i18n/ and handlers/ are gone. Below the tree, one paragraph: these are exactly the directories objectstack.config.ts wires, and a new src/ directory is never loaded, and npm run validate neither counts nor checks what it holds, until its index.ts barrel is imported in objectstack.config.ts and handed to its stack key there (the config's own comment says the same).
• New packages/create-objectstack/src/agents-project-structure.test.ts. For every bundled template in TEMPLATES that has an objectstack.config.ts, the block's src/ directories equal the config's import * as X from './src/X' barrels, as sets, both ways. A third case pins that the section names objectstack.config.ts and says "never loaded". A package test, not a gate script.
• What any config loads is unchanged. No template file other than AGENTS.md is touched.
• Changeset .changeset/scaffold-agents-md-wired-dirs.md: patch on create-objectstack (the templates ship inside its dist), with both declaration lines and the one-line adoption note for an existing project.

Step 1 measurement (the order's ruling 2). TEMPLATES (src/template-registry.ts) has one bundled template, blank. All templates share one AGENTS.md (src/templates/AGENTS.md, rendered by index.ts into every project); no template carries its own. blank/objectstack.config.ts imports eight barrels: objects, views, actions, flows, dashboards, apps, skills, picklists. The old block named ten src/ directories: six of those eight, plus reports/, agents/, i18n/, handlers/; skills/ and picklists/ were missing. blank/README.md (its Layout section) already names exactly the eight, so it is unchanged.

Tests

• Red on base ee7518f9 (AGENTS.md checked out from base, the new test kept): 2 failed, 1 passed. The set case received agents, handlers, i18n, reports and lacked picklists, skills; the wiring-sentence case failed. Restored: git status --porcelain empty, blob 8f0801f4fac0 equal to HEAD.
• Green on head: 3/3.

Ablation (one-off, from committed HEAD)

node scripts/ablation-replace.mjs inserted │ ├── reports/ # ABLATED-28954 Analytics reports back into the tree (anchor # BI dashboards + newline + the apps/ line, 1 → 0; blob 8f0801f4fac0 → fad5dd511c4f; the marker counted once on disk). The test: 1 failed, 2 passed, the set case receiving + "reports". The tool restored the file and proved it: blob equal to HEAD 8f0801f4fac0, git diff HEAD empty; git status --porcelain empty after.

Acceptance notes

• Wiring the four directories instead. Not done, by ruling: what the config loads stays as it is. Reports, agents, translations and hooks each have their own stack key, but whether a starter should wire them is a product choice for its own card; this report names none.
• Existing projects. An already-scaffolded project keeps its AGENTS.md. The changeset says how to adopt the fix by hand.

Verification

Package tests and typecheck

All readings at head 499412ef (base ee7518f9), after pnpm install --frozen-lockfile and pnpm --filter 'create-objectstack...' build.

• pnpm --filter create-objectstack test: 20 files, 304 tests passed (the new file included). Lock verdict command-exit 0.
• pnpm --filter create-objectstack typecheck (tsc --noEmit): exit 0; --listFiles counts the new test file once, so the typecheck covers it.
• eslint --no-inline-config packages/create-objectstack: exit 0.
• Not done: a scaffold-and-validate run from the local package (the order called it welcome, not required).

Derived gates

• node scripts/pm/dispatch-gates.mjs --commands at 499412ef: 59 commands. The lane was wound down mid-run (the maintainer's call to wrap up), so the record is partial: 55 ran, 4 NOT MEASURED because the run was stopped before them (check:type-check-debt, check:undeclared-dep-imports, check:watch-hint-literal, check:where-matcher). CI runs all four.
• Of the 55: 53 exit 0. check:dual-build-cjs-loads exit 3, PREREQUISITE NOT MET (needs a full repo build), NOT MEASURED, left to CI. check:lean-entry-closure exit 3 in the loop (objectql dist missing); after pnpm --filter '@objectstack/objectql...' build it answered exit 0 ("Admitted set held exactly (15 packages)").
• Not run locally, as the os-dev scope says: test:repo, the repo-wide lint, and the families outside the derivation. The PR's CI check-runs carry them.
• No dogfood battery: the title has no !, and Clause-② has no (narrowing) arm.

Human Minimum

None: the seat reviews and lands it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/create-objectstack/src/templates/AGENTS.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/create-objectstack/src/templates/AGENTS.md) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 13 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json d1f3ac05038cffc28b9f8bcbe2116afe1b5f1a2e → packageMentionDocs.

[objectstack-fleet]

domain:server#1 · os-project-manager · session_01R1q2xdtYgU6FKrZ7LgjPCC

席位核对 · ACCEPT · domain:server seat 1 · os-project-manager · session_01R1q2xdtYgU6FKrZ7LgjPCC · 2026-11-02T07:16Z

Head 499412ef, report 6571379306 (on #28954), claim 6570928385. Clause-②: no, with no arm: no contract review is owed. The seat read the diff itself.

item	reading
Shape	Draft, base main, Fixes #28954. 3 files (+90 / −6): the scaffolded AGENTS.md Project Structure block, a package test (agents-project-structure.test.ts) and a create-objectstack patch changeset. Metadata-protocol: none. No config change, no packages/spec/**, no gate.
Rule	The block lists exactly the eight directories the template's config wires (objects, views, actions, flows, dashboards, apps, skills, picklists) and drops reports/, agents/, i18n/ and handlers/. One added paragraph says a new src/ directory is never loaded nor validated until its barrel is imported in objectstack.config.ts. The test pins the block to the config's barrel imports.
Evidence	Pin red on base and green on head; ablation red, restore clean; create-objectstack suite 304 tests, typecheck and lint green. Local gates 55 of 59 (the last four were not run at the maintainer's wrap-up; CI runs them, and the PR body says so). CI on head decides; auto-merge waits for it.
Landing	「按照 pm-dispatch 规则复核过的都授权」 (Leehom, 2026-10-25T11:35Z), and 「先确保已有的pr都合并」 (Leehom, 2026-11-02T07:11Z): ready and auto-merge through the relay, with every check green or an expected skip.

---

Generated by Claude Code