ADR-0006 D2 execution carrier (SDK half): rename `client.projects.*` → `client.environments.*` + wire unwrap shapes + JSDoc — parked until the next SDK/protocol breaking major

[os-litant]

Filed by the Director/skills seat (session session_01MnijPVVDakqK2J335JoJtq), 2026-08-27, on maintainer instruction in live PM chat (verbatim: 「我如何安排 cloud 项目继续处理完？」— arranging the deferred Option-1 rename so it actually fires). This card is the machine carrier for ADR-0006's D2 pre-registration (PR #12736): an ADR paragraph is a record, not an inbox — this card is the inbox half.

Restart-when: a maintainer ruling on this card declares the next SDK/protocol breaking major open

Hold record

Parked pm:on-hold at filing, 2026-08-27, by maintainer ruling (#12473 option 3, 「其他同意」; the deferral rationale is ADR-0006 D2, merged via PR #12736): doing this today buys a zero-pull cross-repo breaking change. ⛔ Do not dispatch, do not "tidy" the surfaces early — an early rename PR reverses a recorded decision (ADR-0006 D1 / Prime Directive 13).

Scope when it unparks (the SDK half of one coordinated rename)

• packages/client/src/index.ts: the projects method namespace → environments (all methods incl. the nested projects.packages block), no aliases (the standing v5.0 rename rule); the declared unwrap shapes' keys follow the wire rename ({ environments: … } / { environment: … }); the JSDoc sentence naming ProjectProvisioningService.provisionProject updated to whatever the server class is named at that time (it must keep describing the running system truthfully — ADR-0006 D1 point 3).
• CLI consumers of those shapes (packages/cli/src/commands/environments/list.ts / create.ts / show.ts) follow in the same PR.
• Migration entry in the major's notes; ADR-0006 D1 retired by an addendum in the same release (D2's own instruction: retire, never alias).

Pairing (hard)

Must land in the SAME coordinated release as the producer half — the cloud control plane's response fields project/projects → environment/environments (objectstack-ai/cloud; that repo's seat files and owns the paired card — requested at this card's filing; link lands in a comment below when filed). Neither half ships alone: shipping the SDK half alone is ADR-0006 D3, permanently declined; shipping the producer half alone breaks every current SDK caller mid-flight.

Timing note for the ruling-maker (from the 2026-08-27 Director discussion, recorded so it survives)

The rename's cost grows with SDK adoption — the caller base is smallest now. If one or two majors pass without touching the SDK/protocol face, re-adjudicate deliberately (「专门为它破一次值不值」) instead of letting this hold ride indefinitely. The window depreciates.

Refs: ADR-0006 v4 addendum (PR #12736) · #12473 (the ruled decision card) · the four predecessor cards the addendum exists to stop re-litigating

---

Epic delegation (2026-08-28, by maintainer ruling — see the unpark comment)

Epic PM: session session_65d2faee-1ff4-4be8-be28-72b972c539d9, branch claude/pm-dispatch-adr-0006-d2-sdk-eb8b61. The hold above is HISTORICAL — unparked 2026-08-28; the Restart-when clause was satisfied by the maintainer's ruling recorded in the unpark comment.

Declared file territory (other seats: batch selection avoids intersecting this):

• objectstack: packages/client/src/index.ts (the projects namespace), packages/client tests and packages/client/exported-any-returns.json, packages/cli/src/commands/environments/**, content/docs/api/environment-routing.mdx + content/docs/concepts/north-star.mdx (census-reached, recorded 2026-08-28), docs/adr/0006-project-environment-split.v4.md (retirement addendum only, after PR docs(adr): record the ADR-0006 API-surface boundary — three surfaces keep project deliberately #12736 lands)
• cloud: packages/service-cloud/src/routes/environment-crud.ts, packages/service-cloud/src/routes/environment-lifecycle.ts, and their tests
• Deliberately NOT territory: packages/spec (measured 2026-08-28: zero projects envelope contracts in spec)

[os-litant]

Pairing-card request could not be delivered by machine — relay is with the maintainer. Attempted channels from this seat, both refused: objectstack-ai/cloud is outside this session's GitHub authorization (add_repo: no access; list_repos: zero cloud hits), and a poke trigger to the cloud seat's session was rejected (that session belongs to a different account — the seat's assignee is baozhoutao). Per the cross-repo linked-card convention the producer half is the cloud seat's to file; the request text is ready in this card's Pairing section. One relay action closes this: the maintainer (or baozhoutao) tells the cloud seat 「按 objectstack#12865 立配对卡」 — the back-link comment here is the receipt. Until that comment lands, this card's Pairing section is the only carrier of the producer half; the unlock scan should treat a missing back-link at unpark time as a pre-flight blocker, not a reason to ship the SDK half alone.

---

Generated by Claude Code

[hotlong]

Unpark ruling + epic delegation (2026-08-28)

Maintainer instruction received in live PM chat, verbatim (Chinese, quoted as spoken):

作为 epic 卡，处理所有相关任务和开发

This satisfies this card's machine-readable restart clause — "Restart-when: a maintainer ruling on this card declares the next SDK/protocol breaking major open". The maintainer has directed full execution of all related tasks and development, which opens the D2 window. Unparking now: pm:on-hold comes off, pm:epic goes on, and this card becomes the epic parent (coordination node — never dispatched itself).

Epic PM: session session_65d2faee-1ff4-4be8-be28-72b972c539d9, branch claude/pm-dispatch-adr-0006-d2-sdk-eb8b61 (maintainer-directed dispatch channel).

Pre-flight readings (measured on origin/main today, not recalled)

1. Premise correction on this card's body: the body says the ADR-0006 addendum was "merged via PR docs(adr): record the ADR-0006 API-surface boundary — three surfaces keep project deliberately #12736". Measured: PR docs(adr): record the ADR-0006 API-surface boundary — three surfaces keep project deliberately #12736 is an OPEN DRAFT (governed surface, awaiting human merge). The D1/D2/D3 record is not on main yet. The D1-retirement addendum sub-task is therefore blocked behind that human merge.
2. Pairing relay is now resolved by seat capability, not maintainer relay: the earlier comment reported objectstack-ai/cloud unreachable — that was the MCP agent channel of a prior seat. This seat's local gh CLI has push access to objectstack-ai/cloud (verified via the repos endpoint). The producer-half pairing card will be filed by this seat directly; its back-link comment below is the receipt.
3. Producer surface located (cloud repo, origin/main): packages/service-cloud/src/routes/environment-crud.ts produces the projects+total list envelope and several project envelopes; packages/service-cloud/src/routes/environment-lifecycle.ts produces further project envelopes. URL paths are already on the environments spelling (the SDK calls /api/v1/cloud/environments); the rename scope is response FIELD keys, exactly as this card's Pairing section says.
4. Serial constraint: open PR Bind published response contracts for the 17 unbound client-SDK methods; retire the false PackageRollbackResponseSchema (#12038, ruling 1C·2C·3A·4A·5A) #12848 (issue 17 client-SDK methods have no published response contract to bind to: the whole meta.* history/diagnostics family (9) plus 8 packages.* routes whose handlers call (protocol as any).<method> #12038, response-contract binding) touches packages/client/src/index.ts and packages/client/exported-any-returns.json — the same files the SDK half must edit. Its diff does not touch the projects block lines, but the baseline file overlaps. SDK-half sub-card serializes behind PR Bind published response contracts for the 17 unbound client-SDK methods; retire the false PackageRollbackResponseSchema (#12038, ruling 1C·2C·3A·4A·5A) #12848's merge.
5. Spec is untouched: zero projects envelope contracts in packages/spec/src (positive control: environments hits exist in spec). Clause-② path limb not engaged; content limb — the spec contract's accept/reject behavior is unchanged; the breaking surface is the SDK package API, already ruled ([decision] Does the v5.0 project → environment rename extend to the API surface — client.projects.* and the res.project / res.projects response fields? #12473 option 3, ADR-0006 D2, today's unpark).
6. The JSDoc's named server class appears to no longer exist: zero hits for the provisioning-service spelling in cloud's service-cloud package — the SDK-half dev must measure the current truthful wording rather than copy the card's.

Sub-issues follow; each carries its own scope, pins, and blocking edges.

[hotlong]

Pairing back-link receipt: the producer-half card is filed — objectstack-ai/cloud#1691. The relay this card's earlier comment left with the maintainer is resolved (this seat's local gh has cloud push access; no relay was needed). Sub-issue tree: #12866 (SDK half, serialized behind PR #12848), objectstack-ai/cloud#1691 (producer half, dispatching now), #12867 (D1 retirement addendum, blocked behind PR #12736's human merge).

[hotlong]

Epic FULLY STAGED (2026-08-28) — all development done, window checklist below

• ADR-0006 D2 (SDK half): rename client.projects.* to client.environments.*; unwrap keys follow the wire; JSDoc tells the truth #12866 + ADR-0006 leftovers in @objectstack/client: client.project() / ScopedProjectClient / two test titles still speak the pre-v5.0 noun #12882 — PR ADR-0006 D2 (SDK half): rename client.projects.* to client.environments.*, unwrap keys follow the wire, JSDoc names the endpoint (#12866) #12885 ALL GREEN at c7a6a50 (draft-parked)
• cloud#1691 — cloud PR feat(spec)!: trim ChartTypeSchema to distinctly-renderable families #1692 all gates green, MERGEABLE at cf0f2475 (draft-parked)
• ADR-0006 D1 retirement addendum: record that D2 executed and the three retained-project surfaces are renamed #12867 — PR docs(adr): retire ADR-0006 D1 by execution — the three retained-project surfaces are renamed (#12867) #12908 human-merged; D1 retirement on main
• check-adr-0087-registration refuses a runtime-interface-only disposition on a symbol named only in a JSDoc comment inside a .zod.ts #12881 — PR fix(scripts): ADR-0087 runtime-interface-only reads CODE, not docblock prose (#12881) #12997 merged (a77e460)
• Ruling records: changeset stays minor+BREAKING (「不挂 major」); fourth surface folded (「可以」); identity fix pushed (「推」)

Window steps (deploy model MEASURED from cloud workflows)

Cloud staging deploys main on a 30-min timer; cloud PRODUCTION deploys only on a v* tag behind a Required-Reviewers approval — so merging the PRs exposes STAGING only, and the production cutover is inherently the maintainer's two human acts.

1. Maintainer says the word → epic PM flips ready + lands PR ADR-0006 D2 (SDK half): rename client.projects.* to client.environments.*, unwrap keys follow the wire, JSDoc names the endpoint (#12866) #12885 (objectstack merge queue) and cloud PR feat(spec)!: trim ChartTypeSchema to distinctly-renderable families #1692 (cloud's landing path), with a last freshness check first.
2. Staging picks up the renamed wire within ~30 min (old-SDK callers against STAGING break there — expected).
3. Maintainer, when ready for production: cut the cloud v* tag + approve the prod deploy, and merge the objectstack Version Packages PR that carries the client changeset — the two human acts, done near each other, ARE the coordinated release.
4. Epic PM afterwards: file the cloud .objectstack-sha bump card and the two METHOD-namespace conformance-file follow-ups (recorded), then close out the epic.