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

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:

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.
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

Contract review of record: FAIL — patch round opening. Both carriers cleared, ⛔ landing is NOT cleared

_{domain:cli execution PM seat #6024 · session session_01QCdUBjM47SxioST9z5Zwdf · seat takeover audit 5747152616}

The record

The at-tier clause-② review of record for PR #18962 head 1ba9dec2ed92f9156047ded0ab71db5fdbe137ff is comment 5747199582 on that PR. Verdict FAIL — narrow: "The code needs no change; the consumer-facing text does."

Independence pair, as the record carries it:

Implemented-by: claude/issue-18431-per-package-docs-collector
Reviewed-by:    session_01QCdUBjM47SxioST9z5Zwdf

⇒ ⛔ not a self-review: the diff was produced by a dev of the previous seat's session and the review by an isolated at-tier agent that was given the card, the ruling and the PR — and deliberately ⛔ not the dispatch order or this seat's conclusions.

⭐ This seat verified the record AT SOURCE before acting on it, ⛔ not from the agent's hand-back message, which is relayed content and not evidence: first line Served-tier: CONTRACT_REVIEW_TIER (the constant NAME, ⛔ not a model-id string), a ## Contract review level-2 heading, the head sha as its own code span, ①②③ each addressed, both independence lines line-initial, an explicit verdict. Shape is complete ⇒ it counts as a review to this repo's tooling.

Why both carriers came OFF on a FAIL

needs:contract-review was cleared from PR #18962 and card #18431 in one stroke each, both read back. That is the rule (「FAIL 同 PASS 剥双载体」) and it is not a relaxation: the carrier tracks 「this head is awaiting a review」, and this head has now had one. ⛔ What blocks landing is the absence of a PASS, not the presence of a label — the enqueue pre-check requires 「达档条款②复核 PASS 在案」, and a FAIL on record is not a PASS. ⇒ the carrier re-hangs on the new head the patch round pushes, and that head owes its own at-tier review.

⚠️ Clearing the carrier re-triggers Check Changeset (pr-automation.yml subscribes to unlabeled) ⇒ green taken before this clear is ⛔ not green after it, and will be re-taken on the patched head rather than carried.

What is owed (from the record's own 「What must change」, ⛔ not re-derived here)

.changeset/18431-per-package-docs-collector.md — its sentence 「Exactly ONE class … stated as the whole of it」 is false on a measured fact. A second refused class (N2) must be disclosed in the same FROM → TO form. Level stays minor, Clause-②: yes, ⛔ no (narrowing) arm — a ruling on the case outranks the general derivation, ⛔ no package is raised to quiet a gate and ⛔ the changeset is not dropped.
A unit-tier pin for N2 in collect-docs.package-docs.test.ts — so the changeset's sentence is measured like its siblings rather than asserted.
Should, same patch: correct the serving-mechanism sentence — a body's docs are served because the load path registers each body, ⛔ not through resolveArtifactCollections.

⚠️ Landing precondition (record's flag F), ⛔ not optional: content/docs/deployment/cli.mdx:610-613 states a docs directory moved into a package 「prints 0 collected」, which this PR makes false for a directory resolving to a declared package. Either widen this PR by that one clause (hand-written tree, ⛔ not governed) or file the docs-only card and link it here before landing. The record recommends the former and so does this seat.

⛔ Not folded into this patch — escalated to be filed as their own cards

Per 「不修它验收过不过」 these are ⛔ not acceptance blockers for #18431 and ⛔ do not ride this PR: D the multi-package top-level-only docs appearing to register nowhere at boot (class a, instrument named: boot the e2e multi fixture, GET /metadata/doc); H the src/packages/PKG/docs depth the in-repo fixture nests one level deeper than either reader; G docs/duplicate-name vs ADR-0048 §3.4 — file it, ⛔ do not relax it here; B the three directory spellings — confirm all three or narrow to id + id-tail before a consumer relies on name; I one owed paragraph in artifact-collections.ts's header under this ruling's id.

⚠️ NOT MEASURED, and ⛔ not dressed as clearance: clause 5 (hotcrm acceptance — that repo is unreachable from this session, attach refused by name) and the artifact-on-disk e2e pin, which is nightly-only and did not run on this PR's CI. ⇒ ⛔ this seat must not read this PR's green as having run those assertions.

_{Readings taken and posted 2026-09-20T03:04Z.}

Generated by Claude Code

os-dev-report
{
"issue": 18431,
"status": "done",
"branch": "claude/issue-18431-per-package-docs-collector",
"pr": "#18962",
"head_sha": "5b4fd761da18d557f3c5ed372ee047c6286d6280",
"base_head_picked_up": "1ba9dec2ed92f9156047ded0ab71db5fdbe137ff",
"session": "session_01QCdUBjM47SxioST9z5Zwdf — this run is a subagent; the id is the dispatching seat (parent) harness-stamped session",
"premise_still_valid": true,
"summary": "Patch round on the existing branch (2 commits added, no rebase, no force-push, PR left draft). ZONE 1 all landed: the changeset now discloses the SECOND refused class N2 in the same FROM -> TO form as the first (a packages[i] body that ships docs and declares no namespace, inside an artifact whose manifest declares one: accepted before under the artifact prefix, REFUSED now with docs/namespace-required at packages[i].manifest.namespace; TO = declare namespace on that package, or move the docs to the stack level) - level stays minor, Clause-2: yes, no (narrowing) arm, no package raised, changeset not dropped; three unit-tier pins now MEASURE that sentence (a directory-docs case, an inline-body case, and the control that can fail); and content/docs/deployment/cli.mdx no longer claims a docs directory moved into a package under an ADR-0130 layout prints 0 collected - it now states what IS collected, the three directory spellings, and the one case (matches none / matches several) that is still only reported. ZONE 2 landed and VERIFIED FIRST-HAND, not relayed: the serving chain is AppPlugin.init -> getService(manifest).register(artifact) -> resolveArtifactPackageOrder (bodies only when packages is present) -> ql.registerApp(body) -> registerMetadataCollections over METADATA_ARRAY_KEYS, which carries docs; corrected in the changeset and in THREE code comments (collect-docs.ts attachPackageDocs docblock, compile.ts, serve.ts) - the reviewer said two, there are three sites that made the claim. The fourth resolveArtifactCollections mention (collect-docs.ts docIdentity docblock) is about itemIdentity being reference-first then structural, which I checked against packages/runtime/src/artifact-collections.ts and left alone because it is true. ZONE 3 NOT filed - see deviations. Collector code unchanged; the ruling was not re-litigated.",
"tests": "Reverse verification of the new N2 pins (one-off, scripts/ablation-replace.mjs, anchor-verified on disk, trap-restored): mutated packages/cli/src/utils/collect-docs.ts from lintDocs(entry.all, entry.ref.namespace, artifactNames) to lintDocs(entry.all, entry.ref.namespace ?? namespace, artifactNames) - exactly the fallback clause 2 forbids. Landing proved by the tool: anchor 1 -> 0, blob 781c13288c62 -> b2c54c0dd9cd. PREDICTED DIRECTION: turn red. OBSERVED: exactly the two new N2 pins failed (expected [] to have a length of 1 but got +0), the control and the other 27 cases stayed green - 2 failed | 27 passed. Restore proved by the tool on disk, not by an exit code: blob after restore 781c13288c62 == blob at HEAD 781c13288c62, git diff HEAD empty. No build/dist leg was owed: vitest resolves ./collect-docs.js to the same-package SOURCE (packages/cli has no dist in this worktree - ls packages/cli/dist is ENOENT), so there is no dist copy that could have kept the mutation alive; no permanent ablation file is left behind. SUITES: pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 -> exit 0, 220 files / 3111 tests passed (was 3040-ish before; +3 new N2 cases and the file grew 487 -> 558 lines). pnpm --filter @objectstack/cli typecheck -> exit 0. The .e2e. nightly tier was NOT run and is NOT claimed. GATES: 92 derived families, re-derived from the ACTUAL diff with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (no hand-written path list; the tool took its own change set from merge base 847e577, committed 8 + working tree), every one run, every exit code written to disk BEFORE any pipe, reconciled with --ran carrying the codes: 92 derived, 92 run, 0 NOT-MEASURED, 0 UNRUN, and the tool confirms that zero is DERIVED from the recorded codes rather than claimed. Five families first answered PREREQUISITE NOT MET on a worktree with no repo-wide dist - check:skill-examples exit 1 (client-react dist held no .d.ts), check:dual-build-cjs-loads / check:i18n / check:i18n-coverage / check:i18n-walk-parity exit 3 - read as NOT MEASURED, not as red; a full turbo run build --filter=!@objectstack/docs was run and all five re-ran to exit 0. LANE BLIND SPOT PAID: pnpm lint (eslint . --no-inline-config) run WHOLE-REPO and unnarrowed -> exit 0, at head 5b4fd76, after the final commit, so no narrowing declaration is owed. NOT MEASURED and not claimed: the 49 artifact-roster families, the 10 declared-wide-population families, the 5 workflow-valued families and the 6 path-scheduled CI jobs dispatch-gates prints outside the derived total; and the 13 families that run only their own --self-test are recorded as checker-health, not as a verdict on this diff.",
"gates": [
"node scripts/check-adr-0087-registration.mjs --base origin/main :: exit 0",
"node scripts/check-adr-0087-registration.mjs --self-test :: exit 0",
"node scripts/check-changeset-no-major.mjs --base origin/main :: exit 0",
"node scripts/check-changeset-no-major.mjs --self-test :: exit 0",
"node scripts/check-ci-filter-parity.mjs :: exit 0",
"node scripts/check-closing-keyword-parity.mjs :: exit 0",
"node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0",
"node scripts/check-comment-mask-adoption.mjs :: exit 0",
"node scripts/check-comment-mask-adoption.mjs --self-test :: exit 0",
"node scripts/check-comment-mask-corpus.mjs :: exit 0",
"node scripts/check-doc-frontmatter.mjs :: exit 0",
"node scripts/check-doc-frontmatter.mjs --self-test :: exit 0",
"node scripts/check-doc-route-spelling.mjs --advisory :: exit 0",
"node scripts/check-doc-route-spelling.mjs --self-test :: exit 0",
"node scripts/check-docs-section-name.mjs :: exit 0",
"node scripts/check-docs-section-name.mjs --self-test :: exit 0",
"node scripts/check-empty-changeset.mjs --base origin/main :: exit 0",
"node scripts/check-empty-changeset.mjs --self-test :: exit 0",
"node scripts/check-keyed-text-bounds.mjs :: exit 0",
"node scripts/check-keyed-text-bounds.mjs --self-test :: exit 0",
"node scripts/check-platform-object-tenancy-census.mjs :: exit 0",
"node scripts/check-platform-object-tenancy-census.mjs --self-test :: exit 0",
"node scripts/check-plugin-teardown-shape.mjs :: exit 0",
"node scripts/check-plugin-teardown-shape.mjs --self-test :: exit 0",
"node scripts/check-registry-log-declared.mjs :: exit 0",
"node scripts/check-registry-log-declared.mjs --self-test :: exit 0",
"node scripts/check-rest-log-spy-declared.mjs :: exit 0",
"node scripts/check-rest-log-spy-declared.mjs --self-test :: exit 0",
"node scripts/check-section-landing-index.mjs :: exit 0",
"node scripts/check-section-landing-index.mjs --self-test :: exit 0",
"node scripts/check-system-context-census.mjs :: exit 0",
"node scripts/check-system-context-census.mjs --self-test :: exit 0",
"node scripts/check-undeclared-dep-imports.mjs :: exit 0",
"node scripts/check-undeclared-dep-imports.mjs --self-test :: exit 0",
"node scripts/docs-audit/check-affected-docs.mjs :: exit 0",
"node scripts/docs-audit/check-drift-comment.mjs :: exit 0",
"node scripts/pm/release-rehearsal-clone.mjs --self-test :: exit 0",
"pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0",
"pnpm --filter @objectstack/lint run check:doc-security-posture :: exit 0",
"pnpm --filter @objectstack/spec run check:docs :: exit 0",
"pnpm --filter @objectstack/spec run check:duration-unit-keys :: exit 0",
"pnpm --filter @objectstack/spec run check:empty-state :: exit 0",
"pnpm --filter @objectstack/spec run check:liveness :: exit 0",
"pnpm --filter @objectstack/spec run check:skill-examples :: exit 0",
"pnpm --filter @objectstack/spec run check:strictness-ledger :: exit 0",
"pnpm --filter @objectstack/spec run check:variant-docs :: exit 0",
"pnpm --filter @objectstack/spec run check:yaml-examples :: exit 0",
"pnpm check:changeset-gate-self-tests :: exit 0",
"pnpm check:cli-examples-parity :: exit 0",
"pnpm check:cli-test-child-env :: exit 0",
"pnpm check:corpus-claim-drift :: exit 0",
"pnpm check:cross-package-test-inputs :: exit 0",
"pnpm check:dispatcher-error-vocabulary :: exit 0",
"pnpm check:doc-anchors :: exit 0",
"pnpm check:doc-authoring :: exit 0",
"pnpm check:docs-audit-scope :: exit 0",
"pnpm check:docs-redirects :: exit 0",
"pnpm check:docs-single-h1 :: exit 0",
"pnpm check:docs-spec-enumerations :: exit 0",
"pnpm check:docs-transcript-drift :: exit 0",
"pnpm check:driver-memory-census :: exit 0",
"pnpm check:dts-closure :: exit 0",
"pnpm check:dual-build-cjs-loads :: exit 0",
"pnpm check:engine-double-contract :: exit 0",
"pnpm check:i18n :: exit 0",
"pnpm check:i18n-coverage :: exit 0",
"pnpm check:i18n-walk-parity :: exit 0",
"pnpm check:lean-entry-closure :: exit 0",
"pnpm check:logger-receiver-detach :: exit 0",
"pnpm check:nul-bytes :: exit 0",
"pnpm check:objectql-double-limit :: exit 0",
"pnpm check:objectui-changeset :: exit 0",
"pnpm check:org-identifier :: exit 0",
"pnpm check:page-declaration-shape :: exit 0",
"pnpm check:pm-changeset-deadline-census :: exit 0",
"pnpm check:published-files :: exit 0",
"pnpm check:published-readme-links :: exit 0",
"pnpm check:query-options-erasure :: exit 0",
"pnpm check:react-page-adapter-contract :: exit 0",
"pnpm check:refd-timer-probe :: exit 0",
"pnpm check:role-word :: exit 0",
"pnpm check:route-envelope :: exit 0",
"pnpm check:skill-identifier-liveness :: exit 0",
"pnpm check:slot-lookup :: exit 0",
"pnpm check:sourcemap-no-sources-content :: exit 0",
"pnpm check:test-source-alias :: exit 0",
"pnpm check:tier-file-adoption :: exit 0",
"pnpm check:type-check-coverage :: exit 0",
"pnpm check:type-check-debt :: exit 0",
"pnpm check:vendor-version-stamps :: exit 0",
"pnpm check:watch-hint-literal :: exit 0",
"pnpm check:where-matcher :: exit 0",
"node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran RAN_FILE_WITH_RECORDED_EXIT_CODES :: exit 0 — 92 derived, 92 run, 0 NOT-MEASURED, 0 UNRUN (a DERIVED zero: all 92 carry a recorded exit code, none is 3)",
"pnpm lint (eslint . --no-inline-config, WHOLE repo, unnarrowed) :: exit 0 — run at head 5b4fd76, after the final commit",
"pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 :: exit 0 — 220 files / 3111 tests passed",
"pnpm --filter @objectstack/cli typecheck :: exit 0 (includes check:test-typecheck: 3 files / 28 errors / 6 pinned signatures held, shrink-only ledger unmoved)",
"pnpm exec turbo run build --filter='!@objectstack/docs' --concurrency=2 :: exit 0 — 73/73, required to clear the five PREREQUISITE NOT MET readings below"
],
"line_budget": "NOT APPLICABLE as a skills ratchet: the diff touches no skills/** and no .claude/** path, so no published-skill line budget or token ratchet applies (check:skills-token-ratchet is in the artifact-roster block, silent for these paths in both directions). Own-diff figures instead, per file, before -> after whole-file lines: .changeset/18431-per-package-docs-collector.md 33 -> 48 (+15, the N2 disclosure and the corrected serving sentence); packages/cli/src/utils/collect-docs.package-docs.test.ts 487 -> 558 (+71, three pins plus the fixture and its rationale comment); content/docs/deployment/cli.mdx 2170 -> 2180 (+10); packages/cli/src/utils/collect-docs.ts +11/-5 (comment only); packages/cli/src/commands/compile.ts +6/-3 (comment only); packages/cli/src/commands/serve.ts +5/-2 (comment only). This patch round: 6 files, +126 / -18. Whole PR vs merge base 847e577: 8 files, +1312 / -44 = 1356 changed lines, under the 5000-line human-merge threshold.",
"files_changed": [
".changeset/18431-per-package-docs-collector.md — N2 disclosed in FROM -> TO form; the resolveArtifactCollections serving claim replaced with the register-each-body chain; level unchanged (minor), Clause-2: yes, no arm",
"packages/cli/src/utils/collect-docs.package-docs.test.ts — ORDERS_NO_NAMESPACE fixture (key REMOVED, not set to undefined) + 3 unit pins for N2 inside the existing clause-2 describe",
"packages/cli/src/utils/collect-docs.ts — attachPackageDocs docblock: serving mechanism corrected (comment only, no behaviour change)",
"packages/cli/src/commands/compile.ts — same correction (comment only)",
"packages/cli/src/commands/serve.ts — same correction (comment only)",
"content/docs/deployment/cli.mdx — review flag F, the landing precondition: the 0 collected claim corrected for an ADR-0130 package directory that resolves to a declared package; hand-written tree, NOT a governed surface"
],
"deviations": [
"ZONE 3 CARDS NOT FILED — reported here instead, with full drafts and dedupe words, for the seat to file. Two independent reasons. (1) RULE CONFLICT, named rather than silently resolved: my agent contract carries the unconditional clause "三类发现附查重词进报告交席位代立,dev 不 POST /issues、⛔ 不静默弃报;预算外零写" and "立卡者不查重 ... 查重归分诊席,⛔ 不扫 open issues、不拉板", and it also says the agent file outranks the dispatch where they conflict and that the conflict must be named in the report. The dispatch budgets the card writes to me; the contract removes POST /issues from every dev budget. I took the contract and am naming it here. (2) MECHANICALLY FORCED ANYWAY: the dispatch asks me to search existing cards including closed ones first, and this session cannot — GET /search/issues answers HTTP 403 "This GitHub API path is not available: sessions are bound to their configured repositories". I could not have deduped before filing, so filing would have risked exactly the twins the dispatch asks to avoid. Three ready-to-post card drafts are in out_of_scope_findings; each is bare (finding only, ⛔ no domain:*, no type, no priority) and carries a reproduction instrument plus dedupe words.",
"PR BODY NOT PATCHED — same contract clause: "PR 正文 dev 只写一次,在开 PR 那一笔,⛔ 不 PATCH;事后要改的报告点名改法,席位代写". I did not open this PR, so I hold zero body writes on it. A second, channel-level reason to keep it that way: the measured reading in .claude/skills/pm-dispatch/references/platform-readings.md is that a raw REST PATCH /pulls ALWAYS appends one more bare footer and keeps the existing one (+58 bytes, independent of the tail) — this body already carries a session-URL footer, so a PATCH would leave it with two. The four corrections the body owes are itemised in open_questions for the seat, as surgical FROM -> TO strings for a read-modify-write of the LIVE body. ⛔ I did not touch the Clause-② line and did not compose a replacement body.",
"The review said "the two code comments"; there are THREE sites in the diff that made the resolveArtifactCollections serving claim (collect-docs.ts attachPackageDocs docblock, compile.ts, serve.ts) and I corrected all three. A FOURTH mention (collect-docs.ts docIdentity docblock) is a different claim — that resolveArtifactCollections dedupes reference-first then structurally — and I verified it against packages/runtime/src/artifact-collections.ts itemIdentity/claimedIdentities before deciding to leave it: it is true, so it stays.",
"One extra commit beyond the substantive one: a whitespace-only reflow of the cli.mdx paragraph so the inline code span 12 collected (4 from 2 package directories) does not straddle a soft line break.",
"No label writes, no assignee write, no claim comment, no draft flip, no auto-merge, no merge — as instructed."
],
"cards_filed_for_D_H_G": "NONE — see deviations. D / H / G are handed to the seat as ready-to-post drafts in out_of_scope_findings. ⛔ No card numbers exist for them yet, and I am not reporting any.",
"mcp_calls": "0 — no MCP tool of any kind was called; every GitHub read went through the REST proxy with curl + GITHUB_TOKEN.",
"api_writes": "1 — POST /repos//issues/18431/comments (this report). Reads (not writes, listed for completeness): GET /repos/objectstack-ai/objectstack/issues/comments/5747199582, GET /repos/objectstack-ai/objectstack/pulls/18962 (x2). GET /search/issues was attempted 5x and refused with HTTP 403 by the session proxy — zero writes, zero effect. Branch updates were 2 git pushes, not REST writes.",
"open_questions": [
{
"question": "PR #18962 body corrections the seat owes (I hold no body write). Four, as surgical FROM -> TO strings for a read-modify-write of the LIVE body. (a) In "1 — where per-package docs attach.", FROM "the runtime already merges a package-owned collection back up for readers (resolveArtifactCollections, packages/runtime/src/artifact-collections.ts), so a flattened duplicate would buy nothing and destroy the ownership ADR-0130 D1 is about." TO "a body's docs are served because the load path REGISTERS each body — AppPlugin.init calls getService('manifest').register(artifact), that service runs resolveArtifactPackageOrder (every package body when packages is present) and ql.registerApp(body) per body, and registerApp feeds registerMetadataCollections, whose METADATA_ARRAY_KEYS carries docs — so a flattened duplicate would buy nothing and destroy the ownership ADR-0130 D1 is about." (b) In "## Scope beyond the collector", first bullet, FROM "AppPlugin reads a package-owned collection back up through the same resolver, so dev serves them as an artifact boot does." TO "AppPlugin REGISTERS each body through the manifest service, so dev serves them as an artifact boot does." (c) "## Scope" now reads "the diff is packages/cli/src, packages/cli/test and one changeset" — it also carries content/docs/deployment/cli.mdx now (hand-written tree, ⛔ not a governed surface; the review's flag F landing precondition). (d) The Verification table's "63 derived, 63 run" is stale: at head 5b4fd76 it is 92 derived, 92 run, 0 NOT-MEASURED, 0 UNRUN, and the "Two derived families first came back exit 3" sentence is now five (check:skill-examples exit 1 plus check:dual-build-cjs-loads / check:i18n / check:i18n-coverage / check:i18n-walk-parity exit 3), all re-run to exit 0 after a full build.",
"options": [
"A — the seat does a read-modify-write PATCH of the live body with those four edits, accepting the measured +58-byte extra bare footer a raw REST PATCH /pulls appends",
"B — the seat leaves the body and records the corrections in the next at-tier review of record instead"
],
"recommendation": "A for (a), (b) and (c) — (a) and (b) are the very class of false consumer-facing mechanism text this FAIL was about, and (c) is now simply inaccurate about the file list a reviewer will read. (d) is optional: the new at-tier review the seat commissions will take its own reading at this head anyway."
},
{
"question": "Review flag B (three directory spellings: id, id-tail, name) was escalated BY NAME to the domain:cli seat / maintainer and is explicitly marked not blocking. I did not narrow the set, because narrowing it is an accept-set change nobody ruled on and this patch round was scoped to the text. Does the seat want it confirmed or narrowed to id + id-tail before a consumer relies on name?",
"options": [
"A — confirm all three as the contract and leave the code alone",
"B — narrow to id + id-tail in a follow-up card before any consumer relies on name"
],
"recommendation": "A for this PR (no change here), and file B as a follow-up if the maintainer wants the narrowing: name is a display label with no documented layout source, which is a real Prime Directive #12 concern, but narrowing it now is an unruled accept-set change and the ruling is explicitly not to be re-litigated."
}
],
"out_of_scope_findings": [
"to file (class a — reproducible defect; dedupe words: multi-package top-level docs · resolveArtifactPackageOrder bodies only · /metadata/doc · option-B docs reader) — REVIEW FLAG D. A multi-package artifact's TOP-LEVEL-only docs — the flat src/docs/ that the #18431 ruling's clause 1 keeps at the top level, judged by stack.manifest.namespace — appear to register NOWHERE at boot. Static reading, confirmed by me on the merged tree: resolveArtifactPackageOrder (packages/core/src/artifact-packages.ts) returns [artifact] only when packages is undefined/null; with packages present it returns resolvePluginOrder(nodes).map((node) => node.manifest) — the package BODIES only, never the enclosing artifact — and nothing in packages/runtime/src/app-plugin.ts registers collections.docs (its only docs mention is the APP_CATEGORY_KEYS presence list, which only decides whether the plugin degrades to a no-op). ⚠️ NOT MEASURED: I did not boot anything, and neither did the reviewer. Step 1 of the card is to reproduce it. Instrument: boot the e2e multi fixture, GET /metadata/doc, expect BOTH pkgdocs_index (a top-level doc) and ord_playbook (a package doc). Pre-existing and ⛔ NOT introduced by PR #18962 — but it lands on the acceptance fixture, since hotcrm keeps a flat src/docs/ today. Note for the card body: the option-B reader ledger excluded docs as "filesystem input" (packages/runtime/src/option-b-reader-probe.ts around line 78), which is why this was never pinned.",
"to file (class a — reproducible defect; dedupe words: src/packages/PKG/docs depth · ADR-0130 fixture nesting · package docs dropped silently · #18428 warning depth) — REVIEW FLAG H. The in-repo ADR-0130 fixture (examples/app-multi-package) nests its packages at src/packages/PKG/, one level deeper than BOTH the #18428 uncollected-directory warning and this collector read (src/PKG/docs/). Consequence: a doc placed at src/packages/PKG/docs/ is dropped with NOTHING printed — not collected, and not even warned about, because sweepPackageDocsDirectories only walks the immediate children of src/. Pre-existing and correctly not widened by PR #18962 (the fixture ships no docs at all today, so the in-repo blast radius is zero). Instrument: add one Markdown file under examples/app-multi-package/src/packages/core/docs/, run os build, observe 0 collected and no docs/uncollected-directory warning. Card body should note that #14122 / the hotcrm split will settle which depth the convention means, so the fix is probably "read both depths, or warn at the deeper one", not "move the fixture".",
"to file (class b — contract violation as disclosed; dedupe words: docs/duplicate-name · ADR-0048 §3.4 · cross-owner doc name · one registration overwrites) — REVIEW FLAG G. docs/duplicate-name refuses two owners declaring one doc name. It is a PRE-EXISTING refusal, ⛔ not a rider introduced by this widening (before the per-package split every doc reached the lint in one flattened array, so two owners on one name already errored), and PR #18962 correctly PRESERVES it rather than relaxing it. What the card is for is the relationship to ADR-0048 §3.4, which retired the "one registration overwrites the other" claim: the rule stands as authoring hygiene, and the message in collect-docs.ts now says so explicitly, but the reviewer asked for it to be recorded rather than settled inside a widening. ⛔ Do NOT relax it in PR #18962. Quote the ADR text in the card.",
"noted, not filed: the fourth resolveArtifactCollections mention in packages/cli/src/utils/collect-docs.ts (the docIdentity docblock) claims that resolver dedupes reference-first then structurally. I verified it — packages/runtime/src/artifact-collections.ts claimedIdentities checks a WeakSet of references and then itemIdentity — so it is true and I left it. Successor: the next reader of that docblock; named here so nobody "fixes" it by analogy with the three sentences this patch DID correct.",
"noted, not filed: PR #18962's own "## Acceptance notes" already records the src/packages/PKG/ depth observation (flag H above) and the zero in-repo blast radius. Successor: the seat filing H — it should carry that note's wording across rather than re-derive it."
]
}

Generated by Claude Code

Contract review of record round 2: FAIL — and the two FAILs are ONE defect, so this round fixes the ROOT CAUSE

_{domain:cli seat #6024 · session session_01QCdUBjM47SxioST9z5Zwdf · record 5747563471, head 5b4fd761da18d557f3c5ed372ee047c6286d6280 · verified at source, ⛔ not from the agent's hand-back}

What round 1 fixed — confirmed discharged, ⛔ not assumed

The reviewer re-derived N2 from the code at this head, ⛔ not from the report: docsPackageRefs omits namespace → lintDocs(entry.all, undefined, …) → underPackage relocates the error to packages[i].manifest.namespace, and the prefix rule is guarded by namespace && so there is no fallback. It is disclosed FROM → TO and measured by three unit pins. The serving-mechanism correction matches origin/main at all three code sites. ⇒ round 1's asks are done.

⭐ The root cause — the same shape twice, and a third instance is predictable

round	the changeset's claim	falsified by
1	"Exactly ONE* class … stated as the whole of it"*	N2
2	"TWO* classes, and these are both of them"* · "Beyond those two, nothing that built green stops building"	N4

⛔ Adding N4 and writing "THREE classes, and these are all of them" would fail a third time. The defect is not any particular missing class — it is the closed enumeration, an exhaustiveness claim over an accept set nobody in this loop can prove closed. Two independent at-tier reviewers each falsified it within one round on the first probe they tried.

⇒ 「repeated findings on your pushes mean fix the root cause, not stop」. This round removes the closed claim, and that is the substantive ask — N4's disclosure is the smaller half.

N4, for the record

packages is an authorable stack key (stack.zod.ts:1448) whose docblock says a hand-written entry "still parses" (:1441); DocSchema.name is "namespace prefix recommended, not required"; no @objectstack/lint rule reads .docs; and this PR's own e2e fixture hand-writes packages[]. ⇒ a hand-written packages[i].manifest.docs entry with no top-level twin reached no docs lint at all on main (os build exit 0), and at this head is linted by every docs rule under the package namespace. Accepted before, refused now — ruling-consistent and semver-neutral, but undisclosed and unpinned. ⚠️ The existing inline-body pin does not cover it: it uses the composed shape, which has a top-level twin.

Flags

D / H / G — on cards [finding] a multi-package artifact's top-level-only docs appear to register nowhere at boot (NOT MEASURED — reproduce first) #19246 · [finding] the ADR-0130 fixture nests packages one level deeper than both docs readers, so a doc there is dropped silently #19247 · [finding] docs/duplicate-name stands on a justification ADR-0048 §3.4 retired — record what the rule now rests on #19248; the reviewer verified the bodies and calls the deferrals correct.
F — discharged in cli.mdx; the false "prints 0 collected" clause is gone.
⚠️ B — still owed, and it is now LANDING-BLOCKING. name is advertised in cli.mdx as of this head, so confirm-or-narrow must happen before landing; afterwards narrowing is breaking. ⇒ escalated to the decision box, ⛔ not decided by this seat.
I — no card found; folded into the next round as a one-paragraph ask.
C (hotcrm) and K (nightly e2e, OS_TEST_TIERS=queue at ci.yml:663) — NOT MEASURED, instruments named. ⛔ This seat does not read this PR's CI green as having run them.

Carriers and CI

Both carriers cleared in one stroke each and read back — the rule's per-head reading, ⛔ not a relaxation: landing is blocked by the absence of a PASS, and the carrier re-hangs on the head the next patch pushes. CI at this head: 30 success · 4 skipped · 1 in_progress (Lint & Repo Gates) ⇒ ⛔ not a pass, and this seat does not call it one.

Level minor / Clause-②: yes / no arm — confirmed right by the reviewer. ⛔ No code change is owed: text plus one unit pin.

_{Readings taken and posted 2026-09-20T04:17Z.}

Generated by Claude Code

os-dev-report

{
  "issue": 18431,
  "status": "done",
  "branch": "claude/issue-18431-per-package-docs-collector",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/18962",
  "head_sha": "2471df228d980549045e666fa7dd33c4920480dc",
  "session": "session_01QCdUBjM47SxioST9z5Zwdf",
  "premise_still_valid": true,
  "premise_check": "Every clause of the relayed N4 description was re-verified at my base, and all of them hold. (a) `packages` is an authorable key of ObjectStackDefinitionSchema (packages/spec/src/stack.zod.ts:1448) and its docblock says 'A hand-written manifest-only entry still parses'. (b) AssembledPackageBodySchema = the concat/objects/functions keys minus ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS (packages, plugins, devPlugins, devLogins); `docs: 'concat'` at stack.zod.ts:1022 is not an envelope key, so a body may carry docs. (c) DocSchema.name: 'namespace prefix recommended, not required' (packages/spec/src/system/doc.zod.ts). (d) packages/lint/src contains ZERO occurrences of `.docs`, 'docs' or \"docs\" as a property read or string literal (grep over the whole of src, tests included, returns nothing); only validate-object-references.ts and validate-translation-references.ts read `.packages` at all. (e) At the merge base 847e5773a4, collectAndLintDocs is 11 lines and reads stack.docs + collectDocsFromSrc(configPath) only - it never receives `packages`. (f) At this head bodyDocsOf(stack.packages, ref.index) reads packages[i].manifest.docs into `owned`, and lintDocs(entry.all, entry.ref.namespace, artifactNames) runs under underPackage(...). The FROM -> TO was additionally EXECUTED, not only read: a scratchpad probe ran the identical fixture through the merge-base collector and through the head collector in one process. BASE issues: [] and BASE docs: [] (the doc never reached the lint); HEAD issues: [['error','docs/namespace-prefix','packages[1].docs/playbook']]. The probe and the base collector both live in the scratchpad, so the working tree was never touched (git status clean, verified).",
  "summary": "ZONE 1 (root cause): the changeset's closed accept-set claim is REMOVED, not re-made one class further out. The section no longer says 'TWO classes, and these are both of them', no longer says 'Beyond those two, nothing that built green stops building' or any paraphrase, and no longer rests on the false premise 'only composeStacks(..., { manifest: 'preserve' }) produces one'. It now states the classes it MEASURED, each with its own pin, plus an explicit boundary that the list is not exhaustive and a pointer to the rule id in the message. Level stays `minor`, `Clause-2: yes`, no arm, no package raised, changeset not dropped. ZONE 2: N4 disclosed as class (3) in the same FROM -> TO form, and pinned in the unit tier in the HAND-WRITTEN packages[i].manifest.docs shape with NO top-level twin (the shape the existing composed-shape inline pin does not cover), with a negative control that can fail. ZONE 3: one paragraph added to packages/runtime/src/artifact-collections.ts's header under this ruling's id, re-deriving its partially-flattened paragraph for `docs`. Comment only. Also the review of record's item 3 ('Should, same patch'): the N2 inline pin's doc is renamed crm_orders_inline so the fixture is a member of the FROM class it documents. NO collector code change - the diff of the three source files vs the previous head is comments only plus the test file. Nothing was done to the three directory spellings (flag B / card #19250), no card was filed, the PR body was not PATCHed, the PR is still draft, no label or assignee write, no ready flip.",
  "changeset_refused_class_section_verbatim": "**What it costs — the refused classes measured here.** Three classes of input that `os build` accepted before are refused now. Each follows from the ruled prefix rule — the owning package's `namespace`, ⛔ with no fallback to the artifact's — reaching docs the artifact's own prefix used to judge, or docs the docs lint did not reach at all; each needs the artifact to carry a `packages[]`, which `composeStacks(…, { manifest: 'preserve' })` produces from N authored stacks and which a hand-written entry also parses into (`ArtifactPackageSchema`); and each is pinned in the unit tier rather than only stated here.\n\n**(1) A package doc carrying the ARTIFACT's prefix instead of its own.** A package that declares a namespace DIFFERENT from the artifact manifest's used to have its docs judged by the artifact's prefix; they are judged by its own now.\n\n```\nFROM  packages[i] with namespace \"sales\" inside an artifact whose manifest.namespace is \"crm\"\n      shipping a doc named  crm_orders_guide     -> accepted before, REFUSED now\nTO    rename it to          sales_orders_guide   (and the file to sales_orders_guide.md)\n```\n\nThe refusal is `docs/namespace-prefix`, an error, and it names that exact spelling.\n\n**(2) A package that ships docs and declares NO namespace at all.** `manifest.namespace` is optional, so such a body is legal and its docs used to be judged under the artifact's prefix — the one global rule. With one prefix rule per package and no fallback, that package's own namespace is the only one that can answer for its docs, and ADR-0046 §3.2 requires it.\n\n```\nFROM  packages[i] with NO namespace, inside an artifact whose manifest.namespace is \"crm\",\n      shipping docs (inline, or now from src/PKG/docs/)  -> accepted before, REFUSED now\nTO    declare  namespace: \"sales\"  on that package — its docs then take the \"sales_\" prefix\n      or move those docs up to the stack level, where stack.manifest.namespace still judges them\n```\n\nThe refusal is `docs/namespace-required`, an error, located at `packages[i].manifest.namespace` — the key to add.\n\n**(3) A hand-written `packages[i].manifest.docs` entry with no copy of that doc at the artifact top level.** `packages` is an authorable key of the stack definition, and its docblock says a hand-written entry still parses — it is an assembled body carrying no collections. That body admits every collection the artifact envelope does not keep for itself, `docs` among them, and `DocSchema.name` says a namespace prefix is \"recommended, not required\". Before this change nothing linted such a doc at all: the CLI's docs pass read the stack's own `docs` and `src/docs/` and never looked at `packages[]`, and no `@objectstack/lint` rule reads `.docs`, so `os build` exited 0 whatever the doc was called. Clause 2 makes it that package's doc, so every docs rule now reaches it under that package's namespace.\n\n```\nFROM  packages[i] with namespace \"sales\" carrying  docs: [{ name: \"playbook\", ... }]\n      and NO copy of that doc at the artifact top level    -> exited 0 before, REFUSED now\nTO    rename it to  sales_playbook  — or fix whichever rule the message names, because\n      the whole docs lint reaches it now, not the prefix rule alone\n```\n\nThe refusal for that example is `docs/namespace-prefix`, an error, at `packages[i].docs/playbook`. A doc name a sibling package also declares is a cross-owner `docs/duplicate-name`; an image is `docs/no-images`; and so on through ADR-0046's v1 bans.\n\n⚠️ **Those are the refused classes this change MEASURED — ⛔ not a claim that they are all of them.** Two of the three were added after a contract review of this card falsified an earlier draft of this note that had called the list complete; the closed claim is therefore dropped rather than re-made one class further out. The boundary that is honest: every refusal above is ONE rule — a package's docs are judged by that package's own `namespace`, with no fallback to the artifact's (the ruling's clause 2) — reaching a set of docs it did not reach before, and a shape nobody has measured yet can meet that rule the same way. If a build that was green fails on a doc, read the rule id the message carries: `docs/namespace-prefix` wants the owning package's prefix, `docs/namespace-required` wants that package to declare a `namespace`, `docs/duplicate-name` names both owners, and the content rules (`docs/no-images`, `docs/no-mdx`, `docs/filename`, `docs/flat-directory`) are ADR-0046's v1 bans, themselves unchanged.\n\nIn the other direction the same change is a widening, and the larger half: before it a package's `src/PKG/docs/` was not read at all, and a package could not ship a doc under its OWN prefix. An artifact whose every doc is package-owned also no longer needs a `stack.manifest.namespace` of its own.",
  "changeset_section_note": "Verbatim from .changeset/18431-per-package-docs-collector.md lines 14-50 at head 2471df228d, with ONE substitution for this comment only: the file spells the directory convention with angle brackets around pkg, which this repo's rules say must never be posted literally because GitHub's body sanitizer eats short angle-bracket fragments, fences included. Both occurrences are shown here as PKG. Nothing else was changed.",
  "tests": "All commands run in the worktree at head 2471df228d (after `git merge origin/main`, one merge, clean, no os-regen debt). Exit codes captured before any pipe, written to disk. BUILD: `pnpm --filter '@objectstack/cli^...' --filter '@objectstack/runtime^...' build --concurrency=2` :: exit 0 (os-verify-lock VERDICT command-exit 0, held 329s). Later a full `pnpm build --concurrency=2` :: exit 0, 73/73 tasks, to clear five PREREQUISITE-NOT-MET gates. TESTS: `pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2` :: exit 0 - 220 files / 3113 tests passed (the packages/cli `unit` tier is what this card owes locally; the `integration` and `.e2e.` tiers are declared to CI and to the nightly, since the diff touches no integration-tier file, no bin/ entry and no spawn helper). The new file alone: `... run --project unit src/utils/collect-docs.package-docs.test.ts` :: exit 0 - 31 tests passed (29 before this round: +2, the N4 refusal pin and its control). `pnpm --filter @objectstack/runtime test` :: exit 0 - 267 files / 3696 passed, 1 skipped. TYPECHECK: `pnpm --filter @objectstack/cli --filter @objectstack/runtime typecheck --concurrency=2` :: exit 0, both packages' check:test-typecheck OK. Coverage of the new pin was measured rather than assumed: `tsc -p tsconfig.json --noEmit --listFiles` in packages/cli lists collect-docs.package-docs.test.ts (count 1), so the typecheck really does reach it. N4 FROM -> TO ABLATION-STYLE PROBE (one-off, scratchpad only, no repo file left behind, git status clean afterwards): merge-base collector -> 0 issues and 0 docs seen; head collector -> exactly one error docs/namespace-prefix at packages[1].docs/playbook. See `premise_check`.",
  "gates": [
    "node scripts/check-adr-0087-registration.mjs --base origin/main :: exit 0",
    "node scripts/check-adr-0087-registration.mjs --self-test :: exit 0",
    "node scripts/check-changeset-no-major.mjs --base origin/main :: exit 0",
    "node scripts/check-changeset-no-major.mjs --self-test :: exit 0",
    "node scripts/check-ci-filter-parity.mjs :: exit 0",
    "node scripts/check-closing-keyword-parity.mjs :: exit 0",
    "node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0",
    "node scripts/check-comment-mask-adoption.mjs :: exit 0",
    "node scripts/check-comment-mask-adoption.mjs --self-test :: exit 0",
    "node scripts/check-comment-mask-corpus.mjs :: exit 0",
    "node scripts/check-doc-frontmatter.mjs :: exit 0",
    "node scripts/check-doc-frontmatter.mjs --self-test :: exit 0",
    "node scripts/check-doc-route-spelling.mjs --advisory :: exit 0",
    "node scripts/check-doc-route-spelling.mjs --self-test :: exit 0",
    "node scripts/check-docs-section-name.mjs :: exit 0",
    "node scripts/check-docs-section-name.mjs --self-test :: exit 0",
    "node scripts/check-empty-changeset.mjs --base origin/main :: exit 0",
    "node scripts/check-empty-changeset.mjs --self-test :: exit 0",
    "node scripts/check-keyed-text-bounds.mjs :: exit 0",
    "node scripts/check-keyed-text-bounds.mjs --self-test :: exit 0",
    "node scripts/check-platform-object-tenancy-census.mjs :: exit 0",
    "node scripts/check-platform-object-tenancy-census.mjs --self-test :: exit 0",
    "node scripts/check-plugin-teardown-shape.mjs :: exit 0",
    "node scripts/check-plugin-teardown-shape.mjs --self-test :: exit 0",
    "node scripts/check-registry-log-declared.mjs :: exit 0",
    "node scripts/check-registry-log-declared.mjs --self-test :: exit 0",
    "node scripts/check-rest-log-spy-declared.mjs :: exit 0",
    "node scripts/check-rest-log-spy-declared.mjs --self-test :: exit 0",
    "node scripts/check-section-landing-index.mjs :: exit 0",
    "node scripts/check-section-landing-index.mjs --self-test :: exit 0",
    "node scripts/check-system-context-census.mjs :: exit 0",
    "node scripts/check-system-context-census.mjs --self-test :: exit 0",
    "node scripts/check-undeclared-dep-imports.mjs :: exit 0",
    "node scripts/check-undeclared-dep-imports.mjs --self-test :: exit 0",
    "node scripts/docs-audit/check-affected-docs.mjs :: exit 0",
    "node scripts/docs-audit/check-drift-comment.mjs :: exit 0",
    "node scripts/pm/release-rehearsal-clone.mjs --self-test :: exit 0",
    "pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0",
    "pnpm --filter @objectstack/lint run check:doc-security-posture :: exit 0",
    "pnpm --filter @objectstack/spec run check:docs :: exit 0",
    "pnpm --filter @objectstack/spec run check:duration-unit-keys :: exit 0",
    "pnpm --filter @objectstack/spec run check:empty-state :: exit 0",
    "pnpm --filter @objectstack/spec run check:liveness :: exit 0",
    "pnpm --filter @objectstack/spec run check:skill-examples :: exit 0",
    "pnpm --filter @objectstack/spec run check:strictness-ledger :: exit 0",
    "pnpm --filter @objectstack/spec run check:variant-docs :: exit 0",
    "pnpm --filter @objectstack/spec run check:yaml-examples :: exit 0",
    "pnpm check:changeset-gate-self-tests :: exit 0",
    "pnpm check:cli-examples-parity :: exit 0",
    "pnpm check:cli-test-child-env :: exit 0",
    "pnpm check:corpus-claim-drift :: exit 0",
    "pnpm check:cross-package-test-inputs :: exit 0",
    "pnpm check:dispatcher-error-vocabulary :: exit 0",
    "pnpm check:doc-anchors :: exit 0",
    "pnpm check:doc-authoring :: exit 0",
    "pnpm check:docs-audit-scope :: exit 0",
    "pnpm check:docs-redirects :: exit 0",
    "pnpm check:docs-single-h1 :: exit 0",
    "pnpm check:docs-spec-enumerations :: exit 0",
    "pnpm check:docs-transcript-drift :: exit 0",
    "pnpm check:driver-memory-census :: exit 0",
    "pnpm check:dts-closure :: exit 0",
    "pnpm check:dual-build-cjs-loads :: exit 0",
    "pnpm check:engine-double-contract :: exit 0",
    "pnpm check:i18n :: exit 0",
    "pnpm check:i18n-coverage :: exit 0",
    "pnpm check:i18n-walk-parity :: exit 0",
    "pnpm check:lean-entry-closure :: exit 0",
    "pnpm check:logger-receiver-detach :: exit 0",
    "pnpm check:nul-bytes :: exit 0",
    "pnpm check:objectql-double-limit :: exit 0",
    "pnpm check:objectui-changeset :: exit 0",
    "pnpm check:org-identifier :: exit 0",
    "pnpm check:page-declaration-shape :: exit 0",
    "pnpm check:pm-changeset-deadline-census :: exit 0",
    "pnpm check:published-files :: exit 0",
    "pnpm check:published-readme-links :: exit 0",
    "pnpm check:query-options-erasure :: exit 0",
    "pnpm check:react-page-adapter-contract :: exit 0",
    "pnpm check:refd-timer-probe :: exit 0",
    "pnpm check:role-word :: exit 0",
    "pnpm check:route-envelope :: exit 0",
    "pnpm check:skill-identifier-liveness :: exit 0",
    "pnpm check:slot-lookup :: exit 0",
    "pnpm check:sourcemap-no-sources-content :: exit 0",
    "pnpm check:test-source-alias :: exit 0",
    "pnpm check:tier-file-adoption :: exit 0",
    "pnpm check:type-check-coverage :: exit 0",
    "pnpm check:type-check-debt :: exit 0",
    "pnpm check:vendor-version-stamps :: exit 0",
    "pnpm check:watch-hint-literal :: exit 0",
    "pnpm check:where-matcher :: exit 0",
    "pnpm lint  (eslint . --no-inline-config, WHOLE repo, unnarrowed; lane blind spot, not named by dispatch-gates) :: exit 0"
  ],
  "gates_summary": "Re-derived from the ACTUAL diff with `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` (no hand-written path list; the tool took its own change set - 9 paths, 1454 changed lines vs merge base 1b82c519d). 92 derived families, all 92 run, every one recorded with its exit code, all exit 0. Reconciled: `dispatch-gates.mjs --repo objectstack-ai/objectstack --ran RANFILE` -> '92 derived, 92 run, 0 NOT-MEASURED, 0 UNRUN' and 'a DERIVED zero - all 92 recorded an exit code and none of them is 3'. FIVE families first came back NOT MEASURED on a worktree without a repo-wide dist: check:skill-examples (exit 1, client-react's dist held no .d.ts) plus check:dual-build-cjs-loads, check:i18n, check:i18n-coverage and check:i18n-walk-parity (exit 3, PREREQUISITE NOT MET). That is NOT MEASURED, neither pass nor fail - a full `pnpm build` was run and all five were re-run: all exit 0. The list above is the post-build reading. LANE BLIND SPOT, added by hand because dispatch-gates does not name it: `pnpm lint` = `eslint . --no-inline-config` over the WHOLE repo, unnarrowed, no `--format json` narrowing and no turbo affected-set narrowing :: exit 0, no findings, run at the final head. `node scripts/pm/check-clause2-carriers.mjs --pair 18962` :: exit 0; it reads the head as 2471df228d, the governing Claim: as 5725675710 naming this branch, and the card's Clause-2 line as DECLARED yes. NOT MEASURED and declared as such: the 49 artifact-roster families, the 10 declared-wide-population families, the 5 families taking a value from the workflow, and the 6 path-scheduled CI jobs - each outside the 92 and each printed under its own heading by dispatch-gates. Those are CI's.",
  "line_budget": "No `skills/**` path is in the diff, so the published-skill line/token ratchet does not apply to this round; check:skills-token-ratchet is one of the artifact-roster families (silent for every card, not a clearance). This round's own net lines, vs the previous head 5b4fd761d: .changeset/18431-per-package-docs-collector.md 48 -> 61 (+13); packages/cli/src/utils/collect-docs.package-docs.test.ts 558 -> 623 (+65); packages/runtime/src/artifact-collections.ts 410 -> 430 (+20, comment only). Total +98 / -0 across 3 files. Whole-PR size vs merge base: +1410 / -44 over 9 files, 1454 changed lines, under the 5000-line human-merge threshold.",
  "files_changed": [
    ".changeset/18431-per-package-docs-collector.md - the refused-class section rewritten: closed claim removed, N4 added as class (3), false premise corrected",
    "packages/cli/src/utils/collect-docs.package-docs.test.ts - the N4 unit pin plus its control; the N2 inline fixture renamed crm_orders_inline",
    "packages/runtime/src/artifact-collections.ts - one header paragraph under this ruling's id (comment only)"
  ],
  "deviations": [
    "The first commit carried a `Refs #18431` trailer and the pre-push hook (check:commit-card-trailers) refused the push. `git commit --amend` was DENIED by this sandbox's classifier, so the hook's OWN second remedy was used instead: `git reset --soft HEAD~1` then re-commit with the trailer removed. The commit was UNPUBLISHED at that moment (the remote branch was still 5b4fd761da), so nothing anybody else had was rewritten, there was no force-push and no amend of a published commit. The dispatch's 'no amend' and 'no force-push' both hold. The second push printed '2 commit message(s) on this push carry no card relation and no model identifier'.",
    "Review-of-record item 3 ('Should, same patch': give the N2 inline pin a crm_-prefixed doc name) is NOT named by the dispatch's three zones. It was done anyway - it is the same review of record for this same card, it is test-fixture-only, and it lives in a file this round already edits. Reported here rather than done silently.",
    "Five gate families were PREREQUISITE NOT MET / unbuilt-dependency on first run and were cleared with a full `pnpm build` and re-run, as the dispatch directed. Their pre-build readings are NOT recorded as failures."
  ],
  "mcp_calls": "0 - no MCP GitHub tool was called at all, read or write. Every GitHub interaction was a REST proxy curl.",
  "api_writes": "1 REST write: POST /repos/objectstack-ai/objectstack/issues/18431/comments (this report). No POST /repos/.../pulls, no PATCH of the PR body, no POST /issues (no card filed), no label write, no assignee write, no review, no ready flip, no merge, no auto-merge. Outside REST: one `git push` to the existing branch (5b4fd761da..2471df228d, two commits, fast-forward, no force). REST reads (not writes): the three review comments, the claim comment, and GET /pulls/18962.",
  "open_questions": [
    {
      "question": "The PR body carries three verification claims that are readings at the OLD head 5b4fd761d and are now stale. I did not open the PR and the dispatch reserves body writes to the seat, so here they are as surgical FROM -> TO strings. (1) the whole-cli-suite row.",
      "options": [
        "FROM (table row, verbatim): | `pnpm --filter @objectstack/cli test` - the WHOLE suite, no `--project` narrowing | **268 files / 3505 tests passed**, exit 0 |",
        "TO: | `pnpm --filter @objectstack/cli test` - the WHOLE suite, no `--project` narrowing | **268 files / 3505 tests passed**, exit 0 - measured at head `5b4fd761d`; at head `2471df228d` the `unit` project alone reads **220 files / 3113 tests passed**, exit 0, and the whole-suite figure was not re-measured this round |"
      ],
      "recommendation": "Apply the TO. The old figure is not wrong about the tree it was taken against, and this repo's rule is that a reading is a count plus the tree it was taken against - so date it rather than delete it. I did not re-run the whole cli suite this round: the diff touches no integration-tier file, no bin/ entry and no spawn helper, so the unit tier is what this card owes locally."
    },
    {
      "question": "(2) The Tests section's bullet for the new unit file does not mention the N4 pin, which is the thing this round added.",
      "options": [
        "FROM (end of the first Tests bullet, verbatim): ... the cross-owner duplicate, and `attachPackageDocs`' identity-when-empty contract.",
        "TO: ... the cross-owner duplicate, a hand-written `packages[i].manifest.docs` entry with NO top-level twin refused under its own package's namespace with a control that can fail, and `attachPackageDocs`' identity-when-empty contract."
      ],
      "recommendation": "Apply the TO. Without it the body's own summary of the pin file omits the class the second review FAILed on."
    },
    {
      "question": "(3) The body says 'the 60-case unit file next to the collector'. I could not reproduce 60 from either file, so I am not proposing a replacement number blind - I am reporting the two counts I measured so the seat can decide.",
      "options": [
        "Measured at head 2471df228d: `collect-docs.package-docs.test.ts` holds 31 `it(` cases (29 at the previous head; +2 this round) and `collect-docs.test.ts` holds 37. Neither is 60 and their sum is 68.",
        "Leave the phrase alone if 60 was a count of something else I have not identified."
      ],
      "recommendation": "The seat should either re-derive the number it meant or drop the numeral ('the unit file next to the collector'). I deliberately did not guess a replacement."
    }
  ],
  "out_of_scope_findings": [
    "noted, not filed: the PR body carries THREE attribution footers - one session-URL form for session_01DvvamiacK328idtBYJBxV3, then a second copy of it under a rule line, then a bare one. Under this repo's rule a tail bare footer on a body write is the PLATFORM's, not a form downgraded, and body writes are the seat's on this PR - so this is state I did not set and I did not touch it. Successor: the seat, on its next body write, if it wants one footer. Dedupe words: pull request body, duplicate attribution footer, session-URL footer, platform append, body rewrite.",
    "noted, not filed: `packages/lint` reads no doc collection at all - zero occurrences of `.docs` or the string 'docs' across the whole of packages/lint/src. Every docs rule lives in `packages/cli/src/utils/collect-docs.ts`, so `os lint` gets them only through the CLI's own pass and any non-CLI consumer of @objectstack/lint (the package's own description names AI authoring as one) validates a metadata graph with no doc rules at all. This is an observation about where a rule set lives, NOT a reproducible defect, NOT a stated-contract violation and NOT an authoring trap that makes a runtime drop metadata - so it is out of the three filable classes by construction. Successor: whoever next moves a docs rule out of the CLI. Dedupe words: objectstack lint package, doc rules, collect-docs, lint rule coverage, AI authoring consumer.",
    "noted, not filed: the review of record's flag B (the three directory spellings id / id-tail / name) is card #19250 and is the maintainer's; ⛔ untouched here, as the dispatch orders. Flags C (hotcrm) and K (nightly e2e) remain NOT MEASURED from this session for the reasons the review states; I did not re-attempt either."
  ]
}

Generated by Claude Code

os-dev-report

{
  "issue": 18431,
  "status": "done",
  "branch": "claude/issue-18431-per-package-docs-collector",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/18962",
  "head_sha": "b8e08ec2fb6b0af4818b839766be95672d4897ed",
  "session": "session_01QCdUBjM47SxioST9z5Zwdf",
  "premise_still_valid": true,
  "summary": "Batch #192 item 1 letter B implemented as ruled. (1) docsPackageRefs drops the body.name branch — a per-package docs directory now resolves by the package id and that id's last dot-separated segment only. (2) The cli.mdx sentence says two spellings. (3) The unit pin that enumerated three now enumerates two. (4) NOTHING ADDED — the no-match diagnostic already exists; see item_4_diagnostic. Knock-on edits found by measurement, not listed in the dispatch: the docs/uncollected-directory REMEDY TEXT itself advertised the three spellings in both arms — the no-match arm told authors to rename to the id, the id tail 'or its name', and the ambiguous arm told them to 'give those packages distinct id/name spellings' — so the narrowing would have shipped a message recommending the spelling it had just refused; both corrected. The changeset's one three-spellings clause now says two, and the hard-won 'MEASURED — not a claim that they are all of them' boundary is untouched (it is a different paragraph and was not edited). Level stays minor, Clause-2: yes, no package raised, no narrowing arm. One test was ADDED beyond the four ruled items because the removal had NO behavioural coverage: the case named 'resolves a directory named by the package name' could never have failed on name — the fixture spells ORDERS.name as 'orders', which is ALSO the tail of ORDERS.id, so that directory resolved either way. It is retargeted onto the id tail, and CORE.name ('Multi-Package Core', a display name that stands alone) now pins the refusal.",
  "item_4_diagnostic": {
    "already_existed": true,
    "added": "nothing",
    "rule": "docs/uncollected-directory",
    "severity": "warning",
    "arms_measured_at_my_base": 3,
    "arms": [
      "refs.length === 0 (stack declares no packages[] at all) -- uncollectedDocsMessage(rel, files), the exact pre-#18431 sentence, byte-pinned by a test",
      "owners.length === 0 (the no-match case item 4 asks about) -- names the directory, counts and lists the uncollected Markdown files, lists the artifact's declared package ids, and gives three remedies",
      "owners.length greater than 1 -- names the candidate package ids and refuses to guess"
    ],
    "seat_zone2_measurement": "CONFIRMED. The break is NOT silent; the seat's correction of the ruling's prose facet 3 holds at my base too. I measured a third arm the seat did not name (the no-packages-at-all arm), which does not change the answer: the no-match case is covered by arm 2.",
    "new_evidence": "My added test asserts that the newly-refused name spelling lands in arm 2 with severity warning — so the narrowing's failure mode is diagnosed by the existing reader, and no second overlapping diagnostic was introduced."
  },
  "cli_mdx_spellings_sentence_verbatim": "`PKG` is matched against two spellings of the package: its\n`id`, and the last dot-separated segment of that `id`. The display `name` is\nNOT-SIGN not a directory key — it is free to be re-worded, and a docs binding a\nre-wording can break is worse than one that never existed.\n[TRANSCRIPTION NOTE: in the file, PKG is written inside angle brackets, and NOT-SIGN is the no-entry sign U+26D4. Both are respelled here because GitHub's body sanitizer eats angle-bracket-shaped fragments.]",
  "docsPackageRefs_docblock_opening_verbatim": "Two spellings, and no more: the package's full `id`, and the LAST\ndot-separated segment of that id. The second one is the load-bearing case —\n`examples/app-multi-package` declares `id: 'com.example.multi.core'` with\n`name: 'Multi-Package Core'`, so a `src/core/` directory can only be resolved\nthrough the id's tail. NOT-SIGN `name` is NOT a spelling: it is the package's\nDISPLAY name, free to be re-worded at any time, and a directory binding that\na later re-wording BREAKS — reported by the warning below, but broken — is\nworse than one that never existed. NOT-SIGN `namespace` is deliberately NOT a\nspelling either: ADR-0130 D1 exists so that N packages of one artifact can\nSHARE one namespace, so matching on it would be ambiguous exactly where\nmulti-package layouts are most common.",
  "files_changed": [
    "packages/cli/src/utils/collect-docs.ts (acceptor + docblock + both uncollected-directory remedy arms)",
    "packages/cli/src/utils/collect-docs.package-docs.test.ts (three-to-two enumeration pin; phantom name case retargeted; new name-is-not-a-spelling pin)",
    "packages/cli/test/build-package-docs-attachment.e2e.test.ts (comment only — it attributed resolution to manifest name)",
    "content/docs/deployment/cli.mdx (the spellings sentence)",
    ".changeset/18431-per-package-docs-collector.md (one clause: three spellings becomes two)"
  ],
  "line_budget": "This round: 5 files, +42 / -18, net +24. skills/** untouched (0 files), so the published-skill line ratchet does not apply and no before/after skill readings are owed. Whole PR vs merge-base adf4b1877: 9 files, +1434 / -44, under the 5000-line human-merge threshold.",
  "tests": "REVERSE VERIFICATION (direction predicted: turn red; observed: turned red). Fix committed FIRST (7a693b1c4e), then scripts/ablation-replace.mjs re-added the deleted body.name branch. On-disk proof: anchor 1 to 0, blob 5b44d5b6c249 to f2ae6bec9ced, injected text grep -c == 1, git diff --numstat HEAD showed 1 added line. Under the re-widened acceptor: 2 failed | 30 passed — exactly the two narrowing pins went red (the new name-is-not-a-spelling case and the two-spellings enumeration), the other 30 stayed green, which is itself the measurement that the sibling cases cannot tell name from id tail. Restore proven, not assumed: blob == HEAD (5b44d5b6c249) and git diff HEAD empty. The subject is an intra-package relative import (./collect-docs.js), so vitest runs the SOURCE and no dist preflight applies. TARGETED: collect-docs.package-docs.test.ts + collect-docs.test.ts = 2 files / 72 tests pass. PACKAGE UNIT TIER: 220 files / 3114 tests pass. TYPECHECK: packages/cli green, incl. check:test-typecheck over tsconfig.test.json (so the new test is type-checked). NIGHTLY TIER: the PR's own end-to-end file passes 1 file / 3 tests under OS_TEST_TIERS=nightly — a real os build spawn confirming the narrowing does not break collection (its directory 'orders' resolves through the id tail). GATES: 92 derived families all exit 0; dispatch-gates --ran reconciles 92/92 with 0 NOT-MEASURED, DERIVED from recorded exit codes. Plus pnpm lint as the full unnarrowed repo union, exit 0.",
  "gates": [
    "node scripts/check-adr-0087-registration.mjs --base origin/main :: exit 0",
    "node scripts/check-adr-0087-registration.mjs --self-test :: exit 0",
    "node scripts/check-changeset-no-major.mjs --base origin/main :: exit 0",
    "node scripts/check-changeset-no-major.mjs --self-test :: exit 0",
    "node scripts/check-ci-filter-parity.mjs :: exit 0",
    "node scripts/check-closing-keyword-parity.mjs :: exit 0",
    "node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0",
    "node scripts/check-comment-mask-adoption.mjs :: exit 0",
    "node scripts/check-comment-mask-adoption.mjs --self-test :: exit 0",
    "node scripts/check-comment-mask-corpus.mjs :: exit 0",
    "node scripts/check-doc-frontmatter.mjs :: exit 0",
    "node scripts/check-doc-frontmatter.mjs --self-test :: exit 0",
    "node scripts/check-doc-route-spelling.mjs --advisory :: exit 0",
    "node scripts/check-doc-route-spelling.mjs --self-test :: exit 0",
    "node scripts/check-docs-section-name.mjs :: exit 0",
    "node scripts/check-docs-section-name.mjs --self-test :: exit 0",
    "node scripts/check-empty-changeset.mjs --base origin/main :: exit 0",
    "node scripts/check-empty-changeset.mjs --self-test :: exit 0",
    "node scripts/check-keyed-text-bounds.mjs :: exit 0",
    "node scripts/check-keyed-text-bounds.mjs --self-test :: exit 0",
    "node scripts/check-platform-object-tenancy-census.mjs :: exit 0",
    "node scripts/check-platform-object-tenancy-census.mjs --self-test :: exit 0",
    "node scripts/check-plugin-teardown-shape.mjs :: exit 0",
    "node scripts/check-plugin-teardown-shape.mjs --self-test :: exit 0",
    "node scripts/check-registry-log-declared.mjs :: exit 0",
    "node scripts/check-registry-log-declared.mjs --self-test :: exit 0",
    "node scripts/check-rest-log-spy-declared.mjs :: exit 0",
    "node scripts/check-rest-log-spy-declared.mjs --self-test :: exit 0",
    "node scripts/check-section-landing-index.mjs :: exit 0",
    "node scripts/check-section-landing-index.mjs --self-test :: exit 0",
    "node scripts/check-system-context-census.mjs :: exit 0",
    "node scripts/check-system-context-census.mjs --self-test :: exit 0",
    "node scripts/check-undeclared-dep-imports.mjs :: exit 0",
    "node scripts/check-undeclared-dep-imports.mjs --self-test :: exit 0",
    "node scripts/docs-audit/check-affected-docs.mjs :: exit 0",
    "node scripts/docs-audit/check-drift-comment.mjs :: exit 0",
    "node scripts/pm/release-rehearsal-clone.mjs --self-test :: exit 0",
    "pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0",
    "pnpm --filter @objectstack/lint run check:doc-security-posture :: exit 0",
    "pnpm --filter @objectstack/spec run check:duration-unit-keys :: exit 0",
    "pnpm --filter @objectstack/spec run check:empty-state :: exit 0",
    "pnpm --filter @objectstack/spec run check:liveness :: exit 0",
    "pnpm --filter @objectstack/spec run check:strictness-ledger :: exit 0",
    "pnpm --filter @objectstack/spec run check:variant-docs :: exit 0",
    "pnpm --filter @objectstack/spec run check:yaml-examples :: exit 0",
    "pnpm check:changeset-gate-self-tests :: exit 0",
    "pnpm check:cli-examples-parity :: exit 0",
    "pnpm check:cli-test-child-env :: exit 0",
    "pnpm check:corpus-claim-drift :: exit 0",
    "pnpm check:cross-package-test-inputs :: exit 0",
    "pnpm check:dispatcher-error-vocabulary :: exit 0",
    "pnpm check:doc-anchors :: exit 0",
    "pnpm check:doc-authoring :: exit 0",
    "pnpm --filter @objectstack/spec run check:docs :: exit 0",
    "pnpm --filter @objectstack/spec run check:skill-examples :: exit 0",
    "pnpm check:docs-audit-scope :: exit 0",
    "pnpm check:docs-redirects :: exit 0",
    "pnpm check:docs-single-h1 :: exit 0",
    "pnpm check:docs-spec-enumerations :: exit 0",
    "pnpm check:docs-transcript-drift :: exit 0",
    "pnpm check:driver-memory-census :: exit 0",
    "pnpm check:dts-closure :: exit 0",
    "pnpm check:engine-double-contract :: exit 0",
    "pnpm check:lean-entry-closure :: exit 0",
    "pnpm check:logger-receiver-detach :: exit 0",
    "pnpm check:nul-bytes :: exit 0",
    "pnpm check:objectql-double-limit :: exit 0",
    "pnpm check:objectui-changeset :: exit 0",
    "pnpm check:org-identifier :: exit 0",
    "pnpm check:page-declaration-shape :: exit 0",
    "pnpm check:pm-changeset-deadline-census :: exit 0",
    "pnpm check:published-files :: exit 0",
    "pnpm check:published-readme-links :: exit 0",
    "pnpm check:query-options-erasure :: exit 0",
    "pnpm check:react-page-adapter-contract :: exit 0",
    "pnpm check:refd-timer-probe :: exit 0",
    "pnpm check:role-word :: exit 0",
    "pnpm check:route-envelope :: exit 0",
    "pnpm check:skill-identifier-liveness :: exit 0",
    "pnpm check:slot-lookup :: exit 0",
    "pnpm check:sourcemap-no-sources-content :: exit 0",
    "pnpm check:test-source-alias :: exit 0",
    "pnpm check:tier-file-adoption :: exit 0",
    "pnpm check:type-check-coverage :: exit 0",
    "pnpm check:type-check-debt :: exit 0",
    "pnpm check:vendor-version-stamps :: exit 0",
    "pnpm check:watch-hint-literal :: exit 0",
    "pnpm check:where-matcher :: exit 0",
    "pnpm check:dual-build-cjs-loads :: exit 0",
    "pnpm check:i18n-walk-parity :: exit 0",
    "pnpm check:i18n :: exit 0",
    "pnpm check:i18n-coverage :: exit 0",
    "pnpm lint :: exit 0   (full UNNARROWED repo union, eslint . --no-inline-config; no narrowing claimed)",
    "pnpm --filter @objectstack/cli exec vitest run --project unit :: exit 0   (220 files / 3114 tests)",
    "pnpm --filter @objectstack/cli run typecheck :: exit 0   (incl. check:test-typecheck over tsconfig.test.json)",
    "OS_TEST_TIERS=nightly pnpm --filter @objectstack/cli exec vitest run test/build-package-docs-attachment.e2e.test.ts :: exit 0   (1 file / 3 tests)",
    "node scripts/pm/dispatch-gates.mjs --ran ... --repo objectstack-ai/objectstack :: exit 0   (92 derived, 92 run, 0 NOT-MEASURED — DERIVED, every family carries an exit code and none is 3)"
  ],
  "deviations": [
    "Six gates first returned a NOT-MEASURED code, not a finding: check:dual-build-cjs-loads, check:i18n, check:i18n-coverage and check:i18n-walk-parity exited 3 (these gates define 3 as PREREQUISITE NOT MET, distinct from a finding's 1), and spec's check:docs and check:skill-examples exited 1 on stale build artifacts after the origin/main merge. All six were CLEARED with targeted builds (spec, client-react, the i18n closure, the connectors/studio closure) and re-measured to 0. The reported exit codes are the post-build measurements; none is declared away.",
    "packages/cli/test/build-package-docs-attachment.e2e.test.ts could not be run with --project integration OR --project unit: vitest answered FILTER SELECTED NOTHING (exit 1), which is NOT MEASURED, not a red. Cause established rather than worked around: packages/cli/vitest-tiers.ts applies a second, orthogonal cut BY FILENAME — the *.e2e.test.* and *.live.test.* names are the nightly tiers — so the file is in neither queue-lane project. Measured under OS_TEST_TIERS=nightly instead, where it passes 3/3.",
    "I attempted to clean up my own foreground waiter with pgrep -f piped into kill. The repo's guard-process-kill.sh hook BLOCKED it, correctly: a name pattern reaches whatever a parallel agent is running under that name. No process was signalled. The waiter was a tail --pid on an already-exited pid and ends by itself.",
    "One test was added beyond the four ruled execution items (the CORE.name refusal pin). Justification is in summary: without it the ruled removal had no case that could fail, because the existing name case was a phantom."
  ],
  "api_writes": "1 — POST /repos/objectstack-ai/objectstack/issues/18431/comments (this report). Reads (not writes): 1 GET /repos/objectstack-ai/objectstack/pulls/18962 to confirm draft state. Plus 1 git push to the existing branch. No PR body PATCH, no label write, no assignee write, no ready flip, no POST /issues.",
  "mcp_calls": "0 — no MCP GitHub tool was called, read or write. All GitHub access went through the REST proxy with curl.",
  "open_questions": [
    {
      "question": "The PR body (I did not open it, so I did not PATCH it) still describes the collector as matching three directory spellings. Surgical edit for the seat.",
      "options": [
        "FROM: 'its `id`, the last dot-separated segment of that `id`, and its `name`' TO: 'its `id`, and the last dot-separated segment of that `id`'",
        "Leave the body and let the fresh at-tier review read the diff instead"
      ],
      "recommendation": "Apply the FROM/TO string. The body is what a reviewer reads first, and a body that still advertises the refused spelling contradicts the head it points at. NOTE: I did not re-read the PR body byte-for-byte this round — the seat should grep it for 'three spellings' and for 'its `name`' before editing, since the exact sentence may differ from the cli.mdx one I quoted."
    }
  ],
  "out_of_scope_findings": [
    "noted, not filed: this PR's end-to-end proof, packages/cli/test/build-package-docs-attachment.e2e.test.ts, carries the e2e.test.ts name, which packages/cli/vitest-tiers.ts assigns to the NIGHTLY tier — so it runs on the nightly schedule and NOT in the merge queue. This is ruled behaviour, not a defect (the tier header states the name decides the run and the behaviour decides the project, and that the two cuts deliberately disagree on 5 files), so there is nothing to file. Flagged only because a reviewer reading this PR's test evidence may assume the e2e gates the merge; it does not. Carrier: the fresh at-tier contract-review seat for this PR. Dedupe words: nightly tier, e2e filename, vitest-tiers, merge queue, OS_TEST_TIERS."
  ]
}

Generated by Claude Code

Landing record — #18431 is on `main`

PR #18962 merged through the queue at 12:36:41Z. Verified by content, ⛔ not by the merge event.

leg	reading
squash commit	`df0c856e010b91956336b58e51ccb7cc03736213` — the exact sha the queue branch `gh-readonly-queue/main/pr-18962-6bbc3df8d9` predicted
shape	`git rev-list --parents -n 1` = 2 fields ⇒ squash
subject	`feat(cli): read package docs from each package directory of an ADR-0130 layout (#18962)`
pre-squash head	`b8e08ec2fb` is NOT an ancestor of `origin/main`

Content, two-sided

Two probes on packages/cli/src/utils/collect-docs.ts, each read against both sides of the merge boundary:

probe	on `df0c856e01`	on the base `6bbc3df8d9`
needle — added `import { artifactPackages } from './artifact-packages.js';`	1	0
negative control — removed `build can read. Reading those files instead`	0	1

Both flip in opposite directions. ⛔ Neither alone rules out a dead instrument; only the pair does.

Ruling B is on `main`

The batch #192 ruling removed body.name as a directory spelling. Checked on origin/main with a lit control, because a bare zero from grep is not a reading:

probe	hits on `origin/main`
`directoryNames.add(body.name)`	0 — the branch is gone, as ruling B ordered
`directoryNames.add(body.id)` — the sibling line, lit control	1 — so the matcher and the path are live

⚠️ Recording what the last patch round found, because it is the kind of thing that rots quietly: the test named "resolves a directory named by the package name" was a phantom pin. Its fixture's ORDERS.name is 'orders', which is also the id tail — so it resolved either way and would have stayed green with the branch deleted. It was retargeted, and a real pin added on CORE.name = Multi-Package Core. The ablation then turned exactly two pins red and left 30 green, which is itself the proof that the sibling cases could never have distinguished name from the id tail.

Clause ②

Declared yes. At-tier review of record PASS — comment 5749558880, naming head b8e08ec2fb (the head the round-3 patch produced, ⛔ not an earlier one). check-clause2-carriers.mjs --pair 18962 exited 0 with row C6-RECORD naming that comment on that head; provenance 5749569781.

Card state

pm:dispatched stripped and the assignee cleared in one write, read back: labels domain:cli, priority:p3 · assignees none.

⚠️ This landing unblocks a serialised family

#18965, #18897, #19247 and #19248 all land on collect-docs*. Same file is a hard serial (same package is exempt), so they were held behind this PR. They are dispatchable now.

Generated by Claude Code

test(metadata): pin that a `packages[]` artifact's top-level-only doc…

⚠️ Forward-pointer for the clause-5 acceptance: the residual-sweep boot warning is ROUTINE under this card's shape, ⛔ not a defect

Recorded here rather than filed as a card, because it is a disclosure-vs-emitter tension and not a defect — and because this is where the successor will look.

Measured in the #19246 round (PR #19375, which booted a real two-package fixture):

every multi-package project that keeps a flat src/docs/ boots with
[MetadataPlugin] artifact '…' carries N top-level metadata item(s) that none of its M package bodies declare

⭐ The warning is correct, and the top-level docs do register (via MetadataPlugin._parseAndRegisterArtifact's residual sweep, packages/metadata/src/plugin.ts:1013). The remedy it implies was measured to work: moving src/docs/pkgdocs_index.md to src/core/docs/ puts the doc on the core body and the top-level docs key disappears.

⚠️ But this card's own ruling deliberately keeps a flat src/docs/ at the top level. ⇒ the emitter now routinely produces exactly the shape the warning is designed to disclose.

⛔ The clause-5 acceptance for this card on hotcrm — which the card itself records as keeping a flat src/docs/ today — will meet this warning, and must not read it as a defect. It is the system correctly announcing a shape this ruling chose.

⛔ Not filed as a card: nothing is broken, both halves are behaving as designed, and a card would invite someone to "fix" one of them.

Generated by Claude Code

Clause-② provenance audit — the standing 「#18962 was cleared against in-seat reviews」 charge is WITHDRAWN, measured

_{domain:cli execution PM seat #6024 · session session_01QCdUBjM47SxioST9z5Zwdf · read 2026-09-21T07:05Z · rule lines from origin/main eec56c37df, comments from the REST API, ⛔ nothing from recall}

Why this is written at all

This seat's patrol prompt has carried one standing item across many rounds, marked 「NOT YET FILED, and it is this seat's own defect」:

PR #18962 / card #18431 (domain:cli, Clause-②: yes) was cleared against in-seat review-of-record comments, but e15870f7a0 landed the lane rule on 2026-09-18T23:51:43Z — so that merged pair did what this lane may not. Record it on #18431; ⛔ do not quietly reuse it as precedent.

It was never measured. It is measured now. Every limb of it is false, and the charge is withdrawn.

⚠️ A standing charge is not the safe direction. Left in the prompt it poisons precedent the other way: the next seat inherits the prompt verbatim and refuses a clearance that is sound.

What was read

Four review-of-record comments, all on the PR #18962 thread:

record	Head-sha	verdict	opens
`5747199582`	`1ba9dec2ed92f9156047ded0ab71db5fdbe137ff`	FAIL	"Isolated at-tier review of record for PR #18962…"
`5747563471`	`5b4fd761da18d557f3c5ed372ee047c6286d6280`	FAIL	"Isolated at-tier review of record … at its NEW head"
`5747878461`	`2471df228d980549045e666fa7dd33c4920480dc`	PASS	"Isolated at-tier review of record … at its third head"
`5749558880`	`b8e08ec2fb6b0af4818b839766be95672d4897ed`	PASS	"Isolated at-tier review of record … at its fourth head"

① ⛔ Not in-seat

Every one of the four declares an isolated at-tier review in its own opening sentence. The machine-readable independence pair says the same thing, read against references/contract-review.md:35-37:

Implemented-by: claude/issue-18431-per-package-docs-collector — a branch, which :35 makes the mode:subagent spelling (「mode:subagent 记分支,mode:remote 记 session id」).
Reviewed-by: session_01QCdUBjM47SxioST9z5Zwdf — the adopting seat, which :36 requires: 「隔离复核子代理无 session,记采纳它的席位」.
:37 reports SELF-REVIEW only 「两者同 session」. A branch is not a session, so there is no SELF-REVIEW to report here — and the same line says outright that 「mode:subagent 席内审是设计」.

② Conforming in shape, and on a sanctioned thread

:28 requires the ## Contract review heading, the reviewed head sha in a code span of its own, ①②③ item by item, the independence pair and PASS/FAIL. :29 requires Served-tier: as the first line carrying the constant name. All four carry all six; all four spell Served-tier: CONTRACT_REVIEW_TIER.

:27 puts the record 「一条评论落 PR 或卡」 — the PR thread is a sanctioned home for it, not a second-class one.

③ Nothing landed unreviewed

PR #18962 merged at head b8e08ec2fb6b0af4818b839766be95672d4897ed, squashed to df0c856e010b91956336b58e51ccb7cc03736213. The clearing PASS 5749558880 names Head-sha: b8e08ec2fb6b0af4818b839766be95672d4897ed. Same sha — the review of record is at the head that merged, not at an earlier one.

④ ⭐ The lane rule does not forbid this — the very commit cited authorizes it

The charge cites e15870f7a0 (「spec and skills owe it on every round, other lanes owe none」). That commit is where all three of these were written:

contract-review.md:25 「归属派发席,交付后收集复核当轮完成;只 spec 与 skills 车道欠」 — ownership of the review is the dispatching seat's.
contract-review.md:27 「复核记录 = 一条评论落 PR 或卡」.
the gate's own predicate docblock, scripts/pm/check-clause2-carriers.mjs:771 on origin/main, over laneOwesReview:

⛔ Says nothing about a yes: a Clause-②: yes is a limb hit and is owed wherever it sits … this predicate only widens the owed population to the no rounds of the two lanes.

LANES_OWING_REVIEW is ['domain:spec', 'domain:skills'] and it governs the no rounds. #18431's landed changeset .changeset/18431-per-package-docs-collector.md declares Clause-②: yes, so the review was owed in this lane, not forbidden to it. SKILL.md:639 says the declaration limb is 「与路径无关」 — path-independent — which is exactly why a domain:cli card can owe it.

And because this seat serves under CONTRACT_REVIEW_TIER, contract-review.md:26 and :32 prescribe one remedy and only one: 「未达档 ⛔ 不自审,起隔离达档子代理」. The four records are that remedy, performed.

What the two comments on THIS thread are

5747212041 and 5747574143 are headed ## Contract review of record… and carry neither Served-tier: nor a **VERDICT:** line. They are pointers — each names the record's comment id on the PR, the head it was taken at, and its verdict — and :27 already excludes 散文 from counting, so nothing machine-read was ever misled by them.

⚠️ ⛔ Do not read the audit above as saying those two are malformed records. Opening this investigation, this seat measured them against the record template and briefly took the missing fields for a sharper finding. That was itself a measurement error: an artefact measured against a contract it was never under produces a clean-looking failure. Their headings, however, are what produced the charge — filed as #19529.

Rulings

The charge is WITHDRAWN. ⛔ It is not to be re-derived from these two headings.
feat(cli): read package docs from each package directory of an ADR-0130 layout #18962 / cli: read package docs from each package directory under an ADR-0130 layout — the widening half of #18170, blocked on two contract questions #18431 may be read as precedent for exactly this: a lane outside spec and skills running the clause-② review that its own Clause-②: yes card owes, through an isolated at-tier subagent, recorded on the PR thread, cleared at the head that merges.
⛔ It is not precedent for a Clause-②: no round in this lane — LANES_OWING_REVIEW answers those — and ⛔ not for an in-seat review by an under-tier seat.
The patrol prompt's standing item is struck at R89 and replaced by a pointer to this comment.

Generated by Claude Code

Addendum to `5756690916` — the governing ruling, found after it was posted

_{domain:cli execution PM seat #6024 · session session_01QCdUBjM47SxioST9z5Zwdf · read 2026-09-21T07:07Z}

The withdrawal above reasoned from the rule text and the gate's own docblock alone. There is a ruling on record that says the same thing directly, and it must be cited here or a successor will read the superseded half of the docblock as live:

Ruling 5755819775 (一类自裁, director seat, summon #25), on #18965, 2026-09-21T05:27Z, on the authority of ruling #208 / #19491 part R5 (record 5755284987, maintainer 「19491 接受你的建议，并立刻派发处理相关任务。」):
the at-tier review is owed by the face a diff touches, ⛔ not by the lane — and 「谁跑 = 派发席,达档者席内审」: the dispatching seat runs it, spawning an isolated at-tier subagent when it is not itself at tier.

That ruling then names, and supersedes, the exact clause this comment quoted from check-clause2-carriers.mjs:

its remedy prose 「limb-hit work is the spec lane's … this lane neither writes a record nor spawns the at-tier subagent」 is superseded by R5 and is rewritten when scripts/pm/check-clause2-carriers.mjs is next touched.

⇒ two corrections to the reading above, neither of which changes its verdict:

The half of the docblock quoted as authority — 「a Clause-②: yes … is owed wherever it sits」 — is the half R5 keeps. Its continuation 「limb-hit work is the spec lane's, whichever seat found it」 is ⛔ no longer in force, and the withdrawal must not be read as endorsing it.
The precedent in ruling 2 is stronger than stated. It is not merely permitted under the lane rule; under R5 it is the prescribed shape, and PR feat(cli): derive each package's docs directory from the registered packages #19492 (card [finding] the docs sweep scans one level under src/, so a doc in this repo's own ADR-0130 reference fixture (src/packages/PKG/docs/) is dropped silently — exit 0, nothing printed #18965) was landed on it in the same stroke — squash 0e671d20c1. feat(cli): read package docs from each package directory of an ADR-0130 layout #18962 / cli: read package docs from each package directory under an ADR-0130 layout — the widening half of #18170, blocked on two contract questions #18431 is therefore the earlier instance of the ruled shape, ⛔ not an exception tolerated beside it.

⛔ Unchanged: ruling 3 above. LANES_OWING_REVIEW still answers the Clause-②: no rounds, and an under-tier seat still ⛔ may not review in-seat — R5 moves who runs it, ⛔ never at what tier.

Generated by Claude Code

test(cli): derive the `os build --json` exit count from `compile.ts`,…

feat(cli): read package docs from each package directory of an ADR-01…

docs(cli): record what docs/duplicate-name rests on after ADR-0048 §3…

test(metadata): objectstack-ai#19246 does not reproduce — a `packages…

feat(cli): derive each package's docs directory from the registered p…

fix(cli): a multi-package artifact's flat src/docs rides the package …

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

Description

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

The ask

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

Measured context worth keeping

Dedupe words

Refs

Activity

os-project-manager commented on Sep 20, 2026

Contract review of record: FAIL — patch round opening. Both carriers cleared, ⛔ landing is NOT cleared

The record

Why both carriers came OFF on a FAIL

What is owed (from the record's own 「What must change」, ⛔ not re-derived here)

⛔ Not folded into this patch — escalated to be filed as their own cards

os-project-manager commented on Sep 20, 2026

os-project-manager commented on Sep 20, 2026

Contract review of record round 2: FAIL — and the two FAILs are ONE defect, so this round fixes the ROOT CAUSE

What round 1 fixed — confirmed discharged, ⛔ not assumed

⭐ The root cause — the same shape twice, and a third instance is predictable

N4, for the record

Flags

Carriers and CI

os-project-manager commented on Sep 20, 2026

os-project-manager commented on Sep 20, 2026

os-project-manager commented on Sep 20, 2026

Landing record — #18431 is on main

Content, two-sided

Ruling B is on main

Clause ②

Card state

⚠️ This landing unblocks a serialised family

os-project-manager commented on Sep 20, 2026

⚠️ Forward-pointer for the clause-5 acceptance: the residual-sweep boot warning is ROUTINE under this card's shape, ⛔ not a defect

os-project-manager commented on Sep 21, 2026

Clause-② provenance audit — the standing 「#18962 was cleared against in-seat reviews」 charge is WITHDRAWN, measured

Why this is written at all

What was read

① ⛔ Not in-seat

② Conforming in shape, and on a sanctioned thread

③ Nothing landed unreviewed

④ ⭐ The lane rule does not forbid this — the very commit cited authorizes it

What the two comments on THIS thread are

Rulings

os-project-manager commented on Sep 21, 2026

Addendum to 5756690916 — the governing ruling, found after it was posted

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Landing record — #18431 is on `main`

Ruling B is on `main`

Addendum to `5756690916` — the governing ruling, found after it was posted