spec(api): after #25104 retires GET {base}/docs, rest-server.zod.ts still names the docs viewer (enableOpenApi's TSDoc and describe, and the documentation.enabled tombstone prescription) #25121

Activity

1. objectstack-fleet

   added

   bugSomething isn't workingSomething isn't working

   priority:p2Medium: important, M3Medium: important, M3

   pm:queue

   domain:spec

   area:apiThe API a customer can call, and integrations — REST, connectors, webhooks, jobsThe API a customer can call, and integrations — REST, connectors, webhooks, jobs

   on Oct 21, 2026
2. objectstack-fleet commented on Oct 21, 2026

   

   objectstack-fleetBot

   on Oct 21, 2026

   ContributorAuthor

   More actions

   Pointer from domain:cli seat 2 · os-justin · session session_01LmjU2x1faLZ39DVTFyVca6 · 2026-10-21T15:24Z. ⛔ Not a claim, and no label change.

   PR #25124 (#25104) retires GET {base}/docs. Its dev found more spec-side text naming the viewer, beyond this card's three sites. Same family, so for this card's sweep (read at origin/main edcc8ceae6):

   • packages/spec/liveness/rest_api.json:73: evidence that reads "mounts both /openapi.json and the /docs viewer";
   • packages/spec/scripts/lib/openapi-self-consistency.ts:34 (a comment) and :156 (a refusal message naming the Scalar viewer at GET /api/v1/docs);
   • packages/spec/migrations/entries/semantic/18.rest-api-config-dead-keys-retired.ts:20 and :46 (prose);
   • dormant, with zero pull: packages/spec/src/api/plugin-rest-api.zod.ts declares uiPath (default /api/docs, "URL path to serve documentation UI"), and packages/spec/REST_API_PLUGIN.md echoes it. No reader outside packages/spec was found. It is an ADR-0049 enforce-or-remove candidate beside ApiTestingUiConfigSchema.

   This card stays Blocked-by: #25104 until PR #25124 lands.

   ---

   Generated by Claude Code
3. objectstack-fleet commented on Oct 21, 2026

   

   objectstack-fleetBot

   on Oct 21, 2026

   ContributorAuthor

   More actions

   Pointer from domain:cli seat 2 · session session_01LmjU2x1faLZ39DVTFyVca6 · 2026-10-21T18:32Z. ⛔ Not a claim, and no label change.

   The blocker has cleared: #25104 landed as PR #25124 (1b3b65e64), and GET {base}/docs is retired on main. This card's spec text, and the extra sites in the pointer above, can now be brought to what main serves.

   ---

   Generated by Claude Code
4. objectstack-fleet

   added

   pm:dispatched

   and removed

   pm:queue

   on Oct 22, 2026
5. objectstack-fleet

   assigned

   os-bill

   on Oct 22, 2026
6. objectstack-fleet commented on Oct 22, 2026

   

   objectstack-fleetBot

   on Oct 22, 2026

   ContributorAuthor

   More actions

   Claim: PM loop round 3
   Session: session_01B2EeooonSXrANpkpgUSfFZ
   Account: os-bill
   Branch: claude/project-thread-7afd2e (at origin/main 23540582f, no commits of its own; restarted from the current main before the first edit)
   Worktree: objectstack-issue-25121
   Domain: domain:spec
   Seat: domain:spec#2 (seat post #18549)
   File surface: packages/spec/src/api/rest-server.zod.ts (TSDoc, the enableOpenApi describe, the documentation.enabled tombstone prescription), packages/spec/liveness/rest_api.json, packages/spec/scripts/lib/openapi-self-consistency.ts, packages/spec/src/migrations/entries/semantic/18.rest-api-config-dead-keys-retired.ts (prose), their regenerated references (gen:schema, gen:docs), one patch changeset (stop on breach; explain in the report)
   Container & model: S, mode:subagent, model: default (dispatch-gates --tier: no path-derived mandate; the describe text is judgement prose, not mechanical); the published-schema face owes one CONTRACT_REVIEW_TIER review of record before the queue
   Clause-②: no
   Metadata-protocol: none
   Responsibility: n/a — not a defect in a door; the defect is published prose naming a route that main no longer serves (PR #25124, 1b3b65e64)
   Thread-read: 6323560908
   Serial constraints cleared: no open PR touches the four files (open-PR file scan). The blocker #25104 has landed (PR #25124).
   Scope note: the two ADR-0049 candidates the card and pointer 6319661846 name (ApiTestingUiConfigSchema as ApiDocumentationConfigSchema.ui, and plugin-rest-api.zod.ts's uiPath) are retirements, a metadata-protocol narrowing the maintainer asked to be consulted on. They are NOT in this claim; the seat files them as their own card. Prose that describes them is left as it is.

   ---

   Generated by Claude Code
7. objectstack-fleet commented on Oct 22, 2026

   

   objectstack-fleetBot

   on Oct 22, 2026

   ContributorAuthor

   More actions

   os-dev-report
   {
   "issue": 25121,
   "status": "done",
   "branch": "claude/project-thread-7afd2e",
   "pr": "#25162",
   "session": "session_01B2EeooonSXrANpkpgUSfFZ",
   "premise_still_valid": true,
   "summary": "The spec text that still named the retired GET {basePath}/docs viewer page now names only the OpenAPI document. registerOpenApiEndpoints on origin/main 2354058 mounts GET {basePath}/openapi.json alone (packages/rest/src/discovery-routes.ts). Sites changed: the enableOpenApi TSDoc and describe and the documentation.enabled tombstone prescription (rest-server.zod.ts), the liveness/rest_api.json enableOpenApi evidence (verifiedAt restamped 2026-10-22), the rule-1 comment and the dangling-ref refusal in scripts/lib/openapi-self-consistency.ts, and the replacement and acceptanceCriteria prose in semantic entry 18.rest-api-config-dead-keys-retired.ts. Then gen:schema (no tracked change) and gen:docs (content/docs/references/api/rest-server.mdx), plus one patch changeset .changeset/25121-spec-openapi-viewer-prose.md with Clause-②: no / Metadata-protocol: none. A sweep of packages/spec for Scalar, docs-viewer and /docs-route mentions found no further site; the remaining /docs hits are unrelated test fixtures and the two out-of-scope schemas. PM assumption confirmed: the prescription edit is not an accept-set change. Both pins (spec DOCS_ENABLED_PRESCRIPTION, rest rest-api-config-dead-keys-refused) match only up to 'is the switch', which the new text keeps, so no pin flip was needed. The card assignee (os-bill) was left untouched. The PR is a draft, assigned to os-bill, with no labels. origin/main moved to 6b44efa after the branch point, touching none of the diff's packages, so no merge was taken.",
   "tests": "At head 32bfe10: pnpm --filter @objectstack/spec test, lock VERDICT command-exit 0, Test Files 706 passed (706), Tests 21462 passed, 1 todo. pnpm --filter @objectstack/spec typecheck, lock VERDICT command-exit 0. pnpm --filter @objectstack/rest exec vitest run --maxWorkers=2 src/rest-api-config-dead-keys-refused.test.ts src/rest-docs-viewer-retired.pin.test.ts, lock VERDICT command-exit 0, Test Files 2 passed, Tests 17 passed. pnpm --filter @objectstack/spec check:generated: first exit 1 (check:docs stale), after gen:docs exit 0 with all 14 artifacts current. No ablation: only description, TSDoc, comment and prescription text changed, and no tested behaviour moved.",
   "gates": "dispatch-gates --commands --repo objectstack-ai/objectstack at 32bfe10: 111 commands, each run with its exit captured before any pipe. --ran reconciliation exit 0: '111 derived famil(ies) accounted for — 110 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3)'. 110 exit 0. Five first exited 3 and were re-run green after building their prerequisites: check:doc-formula-expressions and check:doc-security-posture (needed the lint and formula dists), check:skill-examples (client-react dist), check:lean-entry-closure (objectql dist), check:exported-any (read a spec dist mid-rebuild). check:generated first exited 1 because a concurrent turbo build was rewriting spec dist; the re-run exited 0. NOT MEASURED: pnpm check:dual-build-cjs-loads, exit 3, needs the whole workspace built; CI Lint & Repo Gates runs it. Local-only families: check:skill-frame-freshness exit 0; check:dev-prereqs exit 1, NOT MEASURED, because the workspace is not built (33 of 70 packages have no dist) and it names no stale spec dist. CI families: PR #25162 check-runs were in_progress at report time; one read, no polling. 'No other open PR may claim the same issue' was success; Lint ×9, Type Check ×4, Governed Surface Queue Guard, Check Changeset and Spec property liveness were in_progress; Test Core and Build Core had not appeared yet.",
   "dogfood_battery": "n/a — no ! in the PR title and no (narrowing) arm (Clause-②: no)",
   "mcp_calls": "0 — no MCP GitHub calls; GitHub reads went through gh api REST GETs",
   "api_writes": "2 — (1) fleet-write relay repository_dispatch POST /repos/objectstack-ai/objectstack/dispatches carrying pr_create (the relay executed POST /repos/objectstack-ai/objectstack/pulls as a draft, then POST /repos//issues/25162/assignees [os-bill]; read-back reported 5797 bytes sent and 5797 stored, identical); (2) this os-dev-report comment, POST /repos//issues/25121/comments via scripts/pm/post-stamped.mjs. Branch pushes went through git push, which is not REST.",
   "open_questions": [
   {
   "question": "The dispatch requires the PR body to start with an HTML-comment attribution line, and os-dev.md says no HTML comments in GitHub text. Which rule governs PR-body attribution lines?",
   "options": [
   "A keep the dispatch's line verbatim (done; the relay read-back stored it byte-identical)",
   "B drop HTML-comment attribution from PR bodies"
   ],
   "recommendation": "A, because the line is platform attribution rather than a seat marker, and the read-back proved it survived. os-dev.md's no-HTML-comment clause could name this exception explicitly."
   }
   ],
   "out_of_scope_findings": [
   "class: none (zero-pull, dormant; not a filed class) · reach: none measured · ApiTestingUiConfigSchema as ApiDocumentationConfigSchema.ui (packages/spec/src/api/documentation.zod.ts:231, :488; ApiTestingUiType includes 'scalar' at :205) has no reader outside packages/spec at origin/main 2354058. A git grep -w for ApiTestingUiConfigSchema, ApiTestingUiConfig, ApiTestingUiType, ApiDocumentationConfigSchema and ApiDocumentationConfig outside packages/spec, the generated references and the changelogs finds only a comment at packages/runtime/src/http-dispatcher.ts:3061. Inside spec, only documentation.zod.ts composes it. Left untouched per the claim; it is an ADR-0049 enforce-or-remove candidate, and the seat files it. · dedupe words: ApiTestingUiConfigSchema, ApiDocumentationConfig ui, scalar testing ui, enforce-or-remove documentation.zod",
   "class: none (zero-pull, dormant) · reach: none measured · OpenApiGenerationConfigSchema.uiPath (packages/spec/src/api/plugin-rest-api.zod.ts, default /api/docs, under RestApiPluginConfigSchema.openApi at :713; echoed by packages/spec/REST_API_PLUGIN.md:179) has no reader outside packages/spec. The one uiPath hit outside spec is an unrelated local variable at packages/rest/src/ui-routes.ts:79. packages/rest's RestApiPluginConfig is its own interface (rest-api-plugin.ts:94), not the spec schema, and nothing outside spec names RestApiPluginConfigSchema or OpenApiGenerationConfigSchema. Left untouched per the claim. · dedupe words: uiPath, OpenApiGenerationConfigSchema, RestApiPluginConfigSchema, REST_API_PLUGIN.md",
   "carrier: none — noted, not filed: .changeset/25077-rest-docs-viewer-attr-escape.md (on main, unreleased) describes an escaping fix to the docs viewer page, which PR #25124 has since retired. It is release-owned input, so it was not touched here; the release compiler may want to know the page it names no longer ships."
   ]
   }
8. objectstack-fleet commented on Oct 22, 2026

   

   objectstack-fleetBot

   on Oct 22, 2026

   ContributorAuthor

   More actions

   ACCEPT → PR #25162 comment 6332467742 · contract review PASS 6331776073 · head 32bfe10cda · domain:spec#2 · session session_01B2EeooonSXrANpkpgUSfFZ

   ---

   Generated by Claude Code
9. objectstack-fleet

   closed this as completedin #25162on Oct 22, 2026
10. objectstack-fleet

    removed

    pm:dispatched

    on Oct 22, 2026
11. objectstack-fleet commented on Oct 22, 2026

    

    objectstack-fleetBot

    on Oct 22, 2026

    ContributorAuthor

    More actions

    Landing record · domain:spec seat 2 · session session_01B2EeooonSXrANpkpgUSfFZ · 2026-10-22T04:46Z

    Probe	Reading
    PR #25162	merged: true, merge commit e3aa111ad979cf019dda166ca0c6cf5a06946631
    origin/main	head e3aa111ad is the PR's merge (git log origin/main -1)
    Queue branch	no gh-readonly-queue/main/*25162* ref remains
    Card	closed completed by Fixes #25121; pm:dispatched removed in this act

    ACCEPT 6332467742 · contract review PASS 6331776073.

    ---

    Generated by Claude Code