cli: read package docs from each package directory under an ADR-0130 layout — the widening half of #18170, blocked on two contract questions

[os-support-ai]

The widening half of #18170 — and it needs a CONTRACT decision before any code

Filed by the domain:cli execution PM seat at #18170's ACCEPT. #18170 delivered its stated minimum (the loud warning, PR #18428); this card carries the capability half it deliberately did not deliver. ⛔ Not graded here — lane and kind are triage's.

The ask

Read package docs from each package directory under an ADR-0130 layout (src/<pkg>/docs/, or a docs key on the package's defineStack input), so a module can ship its own docs.

⭐ The capability request survives the diagnostic. #18428 makes the loss audible — an author who moves docs into a package now gets told what was not read. They still ⛔ cannot have per-module docs, and the new warning tells them so explicitly. ⇒ the warning raises the value of this card rather than replacing it.

⚠️ Why it was NOT delivered with #18170 — it is under-specified on today's tree

The delivering agent measured two open contract questions, ⛔ neither answerable by a dev:

1. Which packages[] body do per-package docs attach to? An ADR-0130 D4 artifact registers per package (packages[], option B), while compile.ts attaches collected docs to the artifact top level (finalBundle.docs). Per-package docs must first be told which package body they belong to.
2. Whose manifest.namespace does lintDocs's prefix rule use for them? lintDocs enforces a namespace prefix read from one stack.manifest.namespace, and a multi-package stack has ⛔ no single value for it.

⇒ this is 「a contract decision, not a defect fix」, which is why it is a successor card and ⛔ was not a rider.

Measured context worth keeping

The blast radius of the delivered tightening was zero — find examples packages -maxdepth 4 -type d -path '*/src/*/docs' returned nothing, both example apps keep a flat src/docs. ⇒ there is ⛔ no in-repo consumer of the widening today; the pull is external (objectstack-ai/hotcrm, which records the exception in its own AGENTS.md, objectstack-ai/hotcrm#1910).

⚠️ That matters for grading: under 〈创业阶段不扩散〉 a capability with zero in-repo pull and one named external app is exactly the shape that gets weighed rather than assumed.

Dedupe words

package docs · ADR-0130 layout · src/PACKAGE/docs · collect-docs · per-package docs · docs[] attachment · packages[] option B

⚠️ A dedupe search was run from the PM seat before filing. 5 hits, ⛔ none of them open on this ask: #18170 itself, and four closed ADR-0130 context cards (#15004 the reader program, #14164 composeStacks preserve mode, #6760, #6893).

Refs

#18170 / PR #18428 (the tightening half, delivered) · #14122 (the ADR-0130 tracker) · objectstack-ai/hotcrm#1910 (the external app carrying the exception)

---

Generated by Claude Code

[hotlong]

Ruling: batch #147 item 4 · letter 做 (read package docs from each package directory under an ADR-0130 layout; the two contract questions answered here) · maintainer 「18431 做」 2026-09-17T14:05Z

Director seat, summon #24, session_01Wj1HUjzyeiBQ8atRf1ZhaL. Presented as 停放 on the in-repo-pull reading; the maintainer corrected the standard (「我们是一个开发工具,你不能根据我们有没有在写来判断」, recorded 5715688324) and, after the seat's plain-language explanation, ruled 「18431 做」. Facts (this card, #18170's dev): the compiler reads docs only from a flat src/docs/; docs inside a package directory are skipped — loudly since PR #18428; the reference app's ADR-0130 split (hotcrm#1904) wants per-package docs and records an exception meanwhile (hotcrm#1910); in-repo examples are flat.

Ruling — 做, with the two contract questions decided

1. Where per-package docs attach: to the owning package's body in the artifact (packages[], ADR-0130 D4 option B) — packages[i].docs, ⛔ not the artifact top level. The flat src/docs/ of a single-package stack keeps attaching where it does today (top level = the one package), so nothing existing moves.
2. Whose namespace the doc lint uses: the owning package's namespace for that package's docs; a stack-level doc (outside any package) keeps using stack.manifest.namespace. A multi-package stack therefore has one prefix rule per package, ⛔ no single global prefix.
3. Source convention: src/<pkg>/docs/ (the ADR-0130 layout) and, equivalently, a docs input on the package's defineStack — the dev measures which the collector can read without a second traversal and implements that one first; both spellings are ⛔ not required in one PR.
4. Clause-②: yes (the compile input surface and the artifact shape widen), contract review at tier; changeset @objectstack/cli (and @objectstack/spec if packages[].docs is a schema addition) minor; the fix(cli): say what the ADR-0046 package-docs collector did not read (#18170) #18428 warning stays for docs in places neither convention reads.
5. Acceptance: hotcrm's split can drop the hotcrm#1910 exception — the reference app is the acceptance fixture (its per-package docs appear in the compiled artifact under the right package and pass lint with the package prefix).

Four-facet reading (corrected standard): ① modular apps carry docs per module on every mainstream platform's packaging model; ② the reference third-party app needs it for its split; ③ the loud warning stays for anything still unread; ④ a bounded widening with the two ambiguities closed by ruling, so no dev guesses.

Execution

needs-user-decision → pm:queue, domain:cli, p3 stands, type Feature per triage.

---

Generated by Claude Code

[os-support-ai]

Claim — domain:cli execution PM seat #6024

Claim: PM loop round 77
Session: `session_01DvvamiacK328idtBYJBxV3`
Branch: `claude/issue-18431-per-package-docs-collector`
Worktree: `objectstack-issue-18431`
Domain: `domain:cli`
Seat: `domain:cli#6024`
File surface: `packages/cli/src/`, `packages/lint/src/`, `packages/spec/src/`, `packages/cli/test/` (new files only)
Container & model: `L`, `mode:subagent`, `model: opus` (build) — quoted from this run of `node scripts/pm/dispatch-gates.mjs --tier --repo objectstack-ai/objectstack packages/cli/src packages/lint/src packages/spec/src`, derived at `031e5fbfa3` (== `origin/main`): *"The tier stays the PM's per-card judgment call (floor sonnet · default opus · ceiling fable)"* and *"Clause ② SUSPECT surface — a hint, not a verdict … `packages/spec/src` ⇢ `packages/spec/src/**` — the contract surface … the normal landing zone of a clause-② card"*
Clause-②: yes
Thread-read: 5715694492
Serial constraints cleared: PR #18878 (card #18779) MERGED at 2026-09-18T05:34:21Z as `031e5fbfa3` — it held `packages/cli/src/commands/compile.ts`, which is now free and is why this card could not be claimed until now. Card #18520 is IN FLIGHT (claim 5725386686) on `packages/cli/test/` — 20 named existing e2e files plus `scripts/check-comment-mask-adoption.mjs`; fenced below. No other in-flight claim names these packages.

⭐ 维护者已裁 —— 本卡的两个契约问题都已答,⛔ 不重新讨论

裁决在 5715694492(batch #147 item 4,hotlong,维护者原话「18431 做」)。三条执行要点,照抄:

1. 每包文档挂哪里:挂到拥有它的那个包的 body(packages[],ADR-0130 D4 option B)——packages[i].docs,⛔ 不是产物顶层。单包 stack 的扁平 src/docs/ 保持今天的挂法(顶层 = 那一个包),所以现存的东西一个都不动。
2. 文档 lint 用谁的 namespace:用拥有它的那个包的 namespace;包外的 stack 级文档继续用 stack.manifest.namespace。多包 stack 因此是每包一条前缀规则,⛔ 没有单一全局前缀。
3. 源码约定:src/<pkg>/docs/(ADR-0130 布局),以及等价地包的 defineStack 输入上的一个 docs 键 —— ⭐ 由 dev 实测收集器能在「不做第二次遍历」的前提下读哪一种,先实现那一种;两种拼写 ⛔ 不要求在一个 PR 里都做。

其余裁决条款:Clause-②: yes(编译输入面与产物形状都加宽)· changeset @objectstack/cli minor(若 packages[].docs 是 schema 新增则 @objectstack/spec 也 minor)· #18428 的那条响亮警告留着,给落在两种约定都读不到的位置的文档 · 验收:hotcrm 的拆分可以据此撤掉 hotcrm#1910 那条例外。

⭐ Clause-② 的处置 —— ⛔ 不是 dev 的事,也 ⛔ 不是本席自审

本席实测未达 CONTRACT_REVIEW_TIER:get_session 读 last_served_model = claude-opus-5,而 configured_model 读 claude-fable-5-1 —— ⚠️ 后者是创建期的值,是个会读成「已达档」的陷阱。⇒ 依 SKILL.md:522「未达档席 ⛔ 不自审,起隔离达档子代理转录核档采信」:PR 存在之后由本席起一个隔离的达档复核子代理,并从它自己的转录里数 per-request model 戳核档。dev ⛔ 不要自己安排复核,只需把 Clause-②: yes 写对位置。

围栏

• ⛔ 不碰 [finding] nightly-only e2e pins read their own src/ RAW, so a DOCBLOCK can break a pin whose code never moved — and no pull request can ever redden them, because the tier only runs on main #18520 在飞的那 20 个 packages/cli/test/*.e2e.test.ts 文件,也不碰 scripts/check-comment-mask-adoption.mjs。本卡的测试新增文件即可。开工前重测一次交集,若已非零 停下报告。
• ⛔ 不碰 content/docs/releases/、任何 packages/*/CHANGELOG.md。
• ⛔ 不动单包 stack 今天的挂法(裁决第 1 条明写「现存的东西一个都不动」)——这是可测的:落地前后,扁平 src/docs/ 的产物必须逐字节相同。
• ⛔ 不删、不弱化 fix(cli): say what the ADR-0046 package-docs collector did not read (#18170) #18428 那条警告。
• ⛔ 任何命令被本地权限分类器拒绝 ⇒ 停下并原样报告,不绕路,不回头要本席代做。

---

Generated by Claude Code

[os-support-ai]

os-dev-report

{
  "issue": 18431,
  "status": "done",
  "branch": "claude/issue-18431-per-package-docs-collector",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/18962",
  "session": "session_01DvvamiacK328idtBYJBxV3",
  "premise_still_valid": true,
  "summary": "Implemented the maintainer ruling (batch #147 item 4) as written. os build now collects src/PACKAGE/docs/*.md and attaches each set to the owning package body at packages[i].manifest.docs (ADR-0130 D4 option B, never the artifact top level); the doc lint is partitioned so a package-owned doc is judged by that package namespace and a doc outside any package keeps stack.manifest.namespace, with no fallback between the two. A new docs/duplicate-name error covers the one thing the per-package split can no longer see (two owners declaring one name, reachable because ADR-0130 D1 lets packages share a namespace). The #18428 warning is kept word-for-word for a stack with no packages[], and gains a distinct message naming the candidates when a directory matches no package or more than one. os dev mirrors os build so the two do not diverge, and the docs step line counts the whole collection. PREMISES, re-derived today rather than inherited. (1) Blast radius still zero: the card find over examples and packages for a src/PACKAGE/docs directory returns nothing; both example apps that ship docs keep a flat src/docs. (2) compile.ts does attach collected docs to finalBundle.docs at the top level, located from the symbol at the finalBundle assignment, not from any line number on the card. (3) FALSIFIED: lintDocs is NOT in packages/lint. It lives in packages/cli/src/utils/collect-docs.ts and had no per-package path at all; collectAndLintDocs read one stack.manifest.namespace. packages/lint carries no docs lint whatsoever. (4) MEASURED: packages[].docs is NOT a schema addition. AssembledPackageBodySchema derives its keys from COMPOSE_KEY_DISPOSITIONS minus ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS; the docs concat row has been in that table and outside that envelope all along, and reading the schema shape confirms docs is already declared on it. So there is NO spec changeset: cli minor only. CLAUSE 3 MEASUREMENT (which convention, and what the other costs). The two are not symmetric. The DIRECTORY convention costs NO new traversal: uncollectedDocsDirectories has walked every src/PACKAGE/docs and listed its Markdown files by name since #18428, purely in order to warn about them; collecting them adds the file reads and nothing else. The defineStack docs input costs no traversal EITHER, because there is nothing for the collector to do: assemblePackageBody in packages/spec/src/stack.zod.ts already folds docs onto each package body, so composeStacks with manifest preserve puts a package inline docs at packages[i].manifest.docs on main TODAY with zero code change. Measured directly and kept as a test so the claim is checkable rather than asserted. Hence the directory convention is the one implemented first: it is the one with a real capability gap. What the other costs from here: nothing for attachment, and its lint half (clause 2) is already in this PR because the per-package pass reads a package body docs and its directory docs as one set; what remains is documentation of the spelling plus a pin. SEAT ACTION, reported not performed: needs:contract-review is on NEITHER carrier. Running the repo own reader, PM_SWEEP_REPO=objectstack-ai/objectstack node scripts/pm/check-clause2-carriers.mjs --pair 18962, exits 4 (verdict C3: the card declares Clause-2 yes, and the label event stream on card #18431 and on PR #18962 shows the gate was never hung on either, rather than hung and cleared). Both declaration limbs read DECLARED yes by that same reader: the claim comment and the PR body. Per the dispatch the at-tier review is the seat to arrange; I neither hung nor cleared the label and did not block on it. FENCES. Card #18520 intersection re-measured before starting and again at the end: zero. Its population is 20 EXISTING e2e test files plus scripts/check-comment-mask-adoption.mjs; both of my test files are NEW, and the one pre-existing test file I edited, test/validate-build-gate-parity.test.ts, is not an e2e-tier file and is not in that population. content/docs/releases/ and every package CHANGELOG.md untouched. No test skipped, disabled, quarantined or weakened, and no assertion loosened. No command was refused by the local permission classifier. The assignee on the card was already set by the dispatch; I neither wrote nor cleared it.",
  "tests": "All readings at HEAD ccdc9f5389, the merge of origin/main 54145ccec0 into this branch; every exit code captured before any pipe, never through one. pnpm --filter @objectstack/cli test WHOLE, with no project narrowing (the spelling CI runs): 268 files / 3505 tests passed, exit 0. Run twice, once pre-merge and again after merging origin/main, because origin/main had moved packages/spec. The whole nightly tier, OS_TEST_TIERS=nightly with the same whole-suite command: 69 files / 698 tests passed, exit 0. Dependency-closure build (the upstream filter direction) then the package build then typecheck: exit 0 post-merge. The package build is required because some pins in this package refuse at load without it. GATE FAMILIES: dispatch-gates --commands --repo objectstack-ai/objectstack derived 63; all 63 were run; reconciled with --ran where every line carries its own exit code, giving \"63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN\" and the tool states that zero is DERIVED from the recorded codes rather than claimed. Two families first came back exit 3, PREREQUISITE NOT MET (check:dual-build-cjs-loads and check:i18n-coverage), because this worktree had no repo-wide dist. Recorded as NOT MEASURED, then pnpm build was run and both were re-run: both exit 0. The reconciliation above is the post-build reading. pnpm lint (eslint over the whole repo with no inline config) unnarrowed: exit 0, zero findings. No narrowing was declared because none was taken. BYTE-IDENTITY, the ruling clause that nothing existing moves, as a measurement: one flat fixture (inline docs, a flat src/docs carrying frontmatter, a locale variant, and a package-shaped docs directory no packages[] declares) compiled by this branch and by the merge base. before sha256 9294ad9c45b9093c9d80690152ed55036712ed39657b381238e39996e440b605, after sha256 identical, VERDICT byte-identical; stdout identical with timings normalised, and the #18170 warning fires exactly once on both legs. Re-run at the final HEAD after the merge with the same result. That measurement is a two-leg mutation with proof on both sides: each leg greps a marker AND compares git hash-object against the ref blob before building (an editor exit code proves nothing), the restore is proved by git diff HEAD being empty plus re-hashing against HEAD rather than by an exit code, paths are absolute, and the script carries trap restore on EXIT INT TERM. A determinism control builds twice on the head leg first, so a non-reproducible writer could not have been read as a match. It is one-off: no permanent test file is left behind. INCIDENT worth recording, because it is the AGENTS.md rule in practice: that script restore ran git checkout HEAD on three files while a syntax fix was still UNCOMMITTED and silently discarded it. git status then read CLEAN, because the tree matched HEAD exactly. It cost one whole-suite run (30 files failing to load on a comment that closed itself, src/*/docs inside a block comment carrying the comment terminator). The fix was re-applied, committed on its own, and everything after that point was re-run. NEW TESTS. packages/cli/src/utils/collect-docs.package-docs.test.ts (unit tier, runs per-PR): 60 cases together with the existing collect-docs.test.ts, covering all three resolution spellings, namespace deliberately NOT being one of them, both unresolved-directory reports, the per-package prefix rule with its refusal control, a stack-level doc keeping stack.manifest.namespace, an inline body doc judged once and not twice, the cross-owner duplicate, and the identity-when-empty contract of attachPackageDocs. Every positive case asserts PEDIGREE rather than a count: the directory read, the package index, the package id, the namespace, and a marker string written into exactly one file, because a count of 1 is satisfiable by an echo of the flat doc. packages/cli/test/build-package-docs-attachment.e2e.test.ts (NEW) pins the emitted artifact end to end. WHERE IT RUNS, stated so local green is not misread: the e2e filename tier is the NIGHTLY run, so this file does NOT run on this PR or in the merge queue. It is green locally under OS_TEST_TIERS=nightly. That tier is where every sibling that pins artifact shape through a spawned os build already lives (build-multi-package-artifact, compile-artifact-packages, build-docs-step-count); the per-PR coverage of this card is the unit file above. One pre-existing test file was edited, and it is a real finding my diff caused rather than a fixup: test/validate-build-gate-parity.test.ts holds a CLOSED roster of every call site in compile.ts and validate.ts, and attachPackageDocs was unclassified. It is filed under NOT_A_GATE with its own reason (artifact assembly: it places docs collectAndLintDocs already collected and already linted, judges nothing, and os validate emits no artifact to place them in) rather than dropped into BUILD_ONLY_GATES, whose rows assert a gate that cannot run read-only.",
  "mcp_calls": "0 - no MCP GitHub tool was called at any point. Every GitHub read and write went through the REST proxy with curl.",
  "api_writes": "3 REST proxy writes. POST /repos/objectstack-ai/objectstack/pulls (draft PR #18962, body read back: all 116 lines byte-identical, the channel appended its own rule-line footer block and there is exactly one of it). POST /repos/objectstack-ai/objectstack/issues/18962/labels (additive endpoint: domain:cli and priority:p3, mirrored from the card; read back and both hold, alongside the four the labeler bot applied - documentation, size/xl, tests, tooling). POST /repos/objectstack-ai/objectstack/issues/18431/comments (this report). No PATCH of any body. needs:contract-review deliberately NOT written: it is the seat to hang.",
  "open_questions": [],
  "out_of_scope_findings": [
    "to file (class a, reproducible defect, repro named) - dedupe words: src/packages/PACKAGE/docs, ADR-0130 nested package directory, uncollected-directory depth, app-multi-package docs layout, docs silently dropped. Both the #18170 warning and this card collector scan exactly ONE level under src (a src/PACKAGE/docs directory). examples/app-multi-package, the repo own ADR-0130 D4 reference fixture, nests its packages one level deeper, at src/packages/PACKAGE/. Repro: follow that fixture layout, put a doc at src/packages/orders/docs/ord_guide.md, run os build. The doc is silently dropped, the artifact carries no docs at all, exit 0, and NOTHING is printed, because the sweep checks src/packages/docs and finds nothing there. That is the #18170 defect verbatim at one greater depth, now unreachable by BOTH the diagnostic and the new collection. Deliberately not fixed here: the ruling fence is that nothing existing moves, and widening the scan depth is a convention decision this card did not make. Succeeding work that must touch it: the ADR-0130 tracker #14122 and the hotcrm split alignment the card names (hotcrm#1904 and hotcrm#1910), either of which has to settle which depth the convention means.",
    "noted, not filed: the card blast-radius measurement, taken 2026-09-16, was re-derived on this tree today and still holds - zero package-nested docs directories in examples or packages, and both doc-shipping example apps flat. Recorded because a premise nobody re-measures is a premise that rots. Nothing to fix, no card. Succeeding party: whoever next re-derives it, i.e. the next card in this family.",
    "noted, not filed: needs:contract-review is on neither carrier and check-clause2-carriers --pair 18962 exits 4. Not a card - it is a seat step the dispatch reserved to the seat, recorded here so it is not lost. Succeeding party: the domain:cli execution PM seat #6024, this round."
  ]
}

---

Generated by Claude Code