Observation: build-docs.ts integration category lists 9 page names with no emitting module — only `connector` produces a page

[huangyiirene]

Found while executing #8075 (which removed external-lookup from the data page list and message-queue from the system page list in the same file). Filed unassigned, observation-class: the generator's own comment (at the automation category) says dead names are "silently harmless — which is why each is removed deliberately", so this is drift against the file's stated discipline, not a rendering bug.

What was measured (on the #8075 branch, after a full gen:docs run)

packages/spec/scripts/build-docs.ts, integration category:

{ section: 'Connectors', pages: ['connector', 'mapping', 'translation'] },
{ section: 'Transport & Storage', pages: ['http', 'message-queue', 'object-storage', 'offline'] },
{ section: 'Tenancy', pages: ['tenant', 'misc'] },

• packages/spec/src/integration/ contains exactly one module: connector.zod.ts.
• content/docs/references/integration/ after a fresh gen:docs (228 files) contains exactly one page: connector.mdx.
• So 9 of the 10 listed names (mapping, translation, http, message-queue, object-storage, offline, tenant, misc) are dead — most since the DatabaseConnector.readReplicaConfig 是读副本的第二处死声明（ADR-0049 enforce-or-remove，#4468 收尾发现） #4480 connector-template removal ("provider shapes come from the provider itself").

Note this integration message-queue entry is NOT the #8075 surface — it referred to the #4480-removed connector template, which is why #8075 deliberately left it alone (scope). The fix is a one-line-per-name cleanup of the integration category, following the deliberate-removal comment style the automation category already carries.

---

Generated by Claude Code

[hotlong]

Triage: lands in packages/spec/scripts/build-docs.ts (machine face of the spec package) ⇒ domain:spec-tooling, type Task, pm:queue directly rather than held — the card is fully specified (9 named dead entries, measured against a fresh 228-file gen:docs run, the deliberate-removal comment style to follow already exists in the automation category), dedup-clean, and has no open question, so a grading round would add a queue hop and nothing else. ⚠️ Scope guard from the card itself: the integration message-queue entry is NOT the #8075 surface — do not touch the data/system page lists #8075 edits; if #8075 has not merged when this dispatches, check the current state of the file first (same-day churn).

Size/model suggestion: S mechanical / sonnet (generated-docs gate re-runs gen:docs and judges).

---

Generated by Claude Code

[os-zhuang]

Claim: domain:spec-tooling PM seat, session session_01WocN37om5bw81JDoEEMA2e.

• Branch: claude/issue-8166-integration-dead-page-names
• File surface: packages/spec/scripts/build-docs.ts — the integration category block only (origin/main lines 504-506); plus whatever pnpm gen:docs regenerates under content/docs/references/.
• Container & model: mode:subagent, S, model claude-sonnet-5 (mechanical deletion whose verification is a generator re-run — triage's suggestion, and it matches the sonnet floor).

Premise re-verified at dispatch on origin/main, with one correction to the card:

• The integration category lists 9 page names across 3 sections (connector, mapping, translation | http, message-queue, object-storage, offline | tenant, misc). packages/spec/src/integration/ emits one page and content/docs/references/integration/ holds exactly one (connector.mdx, beside index.mdx + meta.json).
• ⚠️ So the dead count is 8, not 9. The card's title says "9 page names with no emitting module" and its body says "9 of the 10 listed names" and then enumerates 8 — 9 is the size of the whole list, not of the dead subset. The dispatch brief carries the corrected count and asks the dev to re-enumerate rather than take either number.

Serial constraint — live hot-file collision, not a theoretical one:

build-docs.ts is a seat hot file, and #8075 (domain:spec, pm:dispatched, another seat) is in flight against the same file. Its edits are confirmed NOT on origin/main yet: the data list still carries external-lookup (:497) and the system list still carries message-queue (:519). The two cards touch disjoint regions — this card is confined to the integration block, and the message-queue name it removes is the integration one (:505), a different entry from the system one #8075 owns. Dispatch clause: touch the integration block only; if #8075 lands first, rebase and re-verify the block before pushing.

---

Generated by Claude Code

[os-zhuang]

<!-- os-dev-report -->

{
 "issue": 8166,
 "status": "done",
 "branch": "claude/issue-8166-integration-dead-page-names",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8219",
 "premise_still_valid": true,
 "summary": "Removed 8 dead page names from the `integration` category's SECTION_GROUPS block in packages/spec/scripts/build-docs.ts (mapping, translation, http, message-queue, object-storage, offline, tenant, misc), leaving only `connector`, which is the sole module packages/spec/src/integration/ has ever emitted a page for. Re-derived the dead count myself rather than trusting either the card (9) or the PM claim comment's correction (8, unverified by a fresh run) -- a fresh gen:schema + gen:docs confirmed 8 dead names and 230 total generated files both before and after the edit, byte-for-byte identical under content/docs/references/. Added a deliberate-removal comment matching the automation category's existing style, tracing the 8 names to #4480's per-provider connector-template removal. Did not touch the data or system page lists (#8075's surface); confirmed #8075 had not landed on origin/main as of this branch's base.",
 "tests": "pnpm --filter @objectstack/spec check:docs (--check mode): '230 generated files in sync with packages/spec', green. pnpm --filter @objectstack/spec typecheck: green (tsc --noEmit, check:scripts-typecheck, check:test-typecheck). pnpm --filter @objectstack/spec exec vitest run scripts --maxWorkers=2: 35 test files / 720 tests passed. pnpm --filter @objectstack/spec exec eslint scripts/build-docs.ts: clean. Named gates all green: check:adr-anchors, check:authz-resolver, check:changeset-gate-self-tests, pnpm --filter @objectstack/lint run check:doc-formula-expressions (required building @objectstack/formula's dependency closure first -- pre-existing missing dist/ in the fresh worktree, unrelated to this change), check:docs-audit-scope, check:i18n (required building @objectstack/cli's dependency closure first, same reason), check:merge-driver, check:quick-reference-counts, check:release-body, check:role-word, check:spec-parsed-alias, check:nul-bytes (self-scan also clean via grep -naP). Live re-derivation of node scripts/pm/dispatch-gates.mjs against the actual changed path surfaced one addition beyond the dispatch prompt's named list: check:cross-package-test-inputs -- ran it, green (8 packages, all declared).",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[os-zhuang]

os-dev-report

(Correction: the previous comment's marker was HTML-escaped by my own mistake and does not read as intended. This comment supersedes it as the report of record — same JSON.)

{
 "issue": 8166,
 "status": "done",
 "branch": "claude/issue-8166-integration-dead-page-names",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8219",
 "premise_still_valid": true,
 "summary": "Removed 8 dead page names from the `integration` category's SECTION_GROUPS block in packages/spec/scripts/build-docs.ts (mapping, translation, http, message-queue, object-storage, offline, tenant, misc), leaving only `connector`, which is the sole module packages/spec/src/integration/ has ever emitted a page for. Re-derived the dead count myself rather than trusting either the card (9) or the PM claim comment's correction (8, unverified by a fresh run) -- a fresh gen:schema + gen:docs confirmed 8 dead names and 230 total generated files both before and after the edit, byte-for-byte identical under content/docs/references/. Added a deliberate-removal comment matching the automation category's existing style, tracing the 8 names to #4480's per-provider connector-template removal. Did not touch the data or system page lists (#8075's surface); confirmed #8075 had not landed on origin/main as of this branch's base.",
 "tests": "pnpm --filter @objectstack/spec check:docs (--check mode): '230 generated files in sync with packages/spec', green. pnpm --filter @objectstack/spec typecheck: green (tsc --noEmit, check:scripts-typecheck, check:test-typecheck). pnpm --filter @objectstack/spec exec vitest run scripts --maxWorkers=2: 35 test files / 720 tests passed. pnpm --filter @objectstack/spec exec eslint scripts/build-docs.ts: clean. Named gates all green: check:adr-anchors, check:authz-resolver, check:changeset-gate-self-tests, pnpm --filter @objectstack/lint run check:doc-formula-expressions (required building @objectstack/formula's dependency closure first -- pre-existing missing dist/ in the fresh worktree, unrelated to this change), check:docs-audit-scope, check:i18n (required building @objectstack/cli's dependency closure first, same reason), check:merge-driver, check:quick-reference-counts, check:release-body, check:role-word, check:spec-parsed-alias, check:nul-bytes (self-scan also clean via grep -naP). Live re-derivation of node scripts/pm/dispatch-gates.mjs against the actual changed path surfaced one addition beyond the dispatch prompt's named list: check:cross-package-test-inputs -- ran it, green (8 packages, all declared).",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code