Filed unassigned and unlabelled by the domain:cli seat (#6024), session session_01UjujZN219uFzBhSYfMykCd. ⛔ Not graded, not routed — and ⛔ not a card an execution seat can answer: it is a breaking public-API decision.
⚠️This seat owed this card at #12153's acceptance and did not file it. Triage flagged the omission on #12432 ("expected from the cli seat at #12153 acceptance per the cross-repo follow-up rule"). Filed now, late, and recorded as late so the gap is visible rather than tidied away.
What is settled, and what is not
Settled. ADR-0006 renamed project → environment at v5.0 with no aliases, and AGENTS.md states "Project now only means the npm/monorepo sense." Three PRs have carried that through the CLI:
Not settled, and deliberately fenced out of all three:
| surface | where |
|---|
client.projects.* | @objectstack/client SDK method names |
res.project / res.projects | control-plane response fields |
packages/client/src/index.ts:1814 | Provision a new project — the SDK JSDoc that travels with the above |
Each of the three cards named these as out of scope for the same reason: they are API surface in other packages, not CLI wording.
Why this needs a human, ⛔ not a seat
Renaming any of them is a breaking change to a published contract with a migration story:
client.projects.* is a published SDK method namespace — renaming breaks every caller, and an alias is exactly what ADR-0006 says the rename does not get.res.project / res.projects are control-plane wire fields. The producer is the cloud control plane, not this repo, so this is also a cross-repo coordination question (objectstack-ai/cloud), not a local rename.
⇒ Squarely on the maintainer floor: protocol / public-contract change, plus a cross-repo producer. ⛔ No execution seat should decide it, and ⛔ no code PR should quietly start it.
The options, as this seat understands them
- Rename with a breaking major — the SDK namespace and the wire fields both move to
environments / environment. Consistent with ADR-0006's no-alias rule; costs a coordinated cloud-side change and a migration entry. - Rename the SDK only, leave the wire fields — the CLI already maps between them (
res?.project feeding os environments show). Cheaper, but leaves the contract half-renamed and the mapping permanent. - Leave both, and record the boundary — declare that the rename was scoped to the CLI's user-facing vocabulary and that
project survives deliberately on the API surface. Costs nothing today; requires the boundary to be written down where the next reader of ADR-0006 will find it, or this question returns every few months.
⛔ This seat states no recommendation — with a cross-repo producer and a published namespace in play, a recommendation from the lane that keeps tripping over the drift is not worth much. What the seat can say is that option 3 is not free: the cost is a documented boundary, and its absence is what has produced three cards in three days.
Why it is worth a card rather than leaving it implicit
The drift is generative: #10967, #12153, #12432 and #12464 are four cards in the same week, each fixing one axis of one rename, each correctly fencing out the API surface, and none able to close the question. Until it is answered, every future reader of a project-spelled identifier next to an environment-spelled one files another.
Refs
Filed unassigned and unlabelled by the
domain:cliseat (#6024), sessionsession_01UjujZN219uFzBhSYfMykCd. ⛔ Not graded, not routed — and ⛔ not a card an execution seat can answer: it is a breaking public-API decision.What is settled, and what is not
Settled. ADR-0006 renamed
project→environmentat v5.0 with no aliases, and AGENTS.md states "Project now only means the npm/monorepo sense." Three PRs have carried that through the CLI:os projectsin examples, class names, and docstrings — leaks into live--helpoutput #10967 / PR cli: environments/*.ts command sources no longer spell os projects in --help #11227 — the command name (os projects …→os environments …)os environmentsfamily's own--helptext and console output still call the entity a "project" (21 sites, v5.0 rename has no aliases) #12153 / PR fix(cli): name the entity an environment in every string theos environmentsfamily prints #12429 — the entity noun in every stringos environmentsprints (25 sites)project→environmentrename never reached the comment axis: 14 docblock sites acrosspackages/cli/src/commands/environments/**,utils/api-client.tsand the client SDK #12432 — the comment axis (14 docblock sites), in flightNot settled, and deliberately fenced out of all three:
client.projects.*@objectstack/clientSDK method namesres.project/res.projectspackages/client/src/index.ts:1814Provision a new project— the SDK JSDoc that travels with the aboveEach of the three cards named these as out of scope for the same reason: they are API surface in other packages, not CLI wording.
Why this needs a human, ⛔ not a seat
Renaming any of them is a breaking change to a published contract with a migration story:
client.projects.*is a published SDK method namespace — renaming breaks every caller, and an alias is exactly what ADR-0006 says the rename does not get.res.project/res.projectsare control-plane wire fields. The producer is the cloud control plane, not this repo, so this is also a cross-repo coordination question (objectstack-ai/cloud), not a local rename.⇒ Squarely on the maintainer floor: protocol / public-contract change, plus a cross-repo producer. ⛔ No execution seat should decide it, and ⛔ no code PR should quietly start it.
The options, as this seat understands them
environments/environment. Consistent with ADR-0006's no-alias rule; costs a coordinated cloud-side change and a migration entry.res?.projectfeedingos environments show). Cheaper, but leaves the contract half-renamed and the mapping permanent.projectsurvives deliberately on the API surface. Costs nothing today; requires the boundary to be written down where the next reader of ADR-0006 will find it, or this question returns every few months.⛔ This seat states no recommendation — with a cross-repo producer and a published namespace in play, a recommendation from the lane that keeps tripping over the drift is not worth much. What the seat can say is that option 3 is not free: the cost is a documented boundary, and its absence is what has produced three cards in three days.
Why it is worth a card rather than leaving it implicit
The drift is generative: #10967, #12153, #12432 and #12464 are four cards in the same week, each fixing one axis of one rename, each correctly fencing out the API surface, and none able to close the question. Until it is answered, every future reader of a
project-spelled identifier next to anenvironment-spelled one files another.Refs
os projectsin examples, class names, and docstrings — leaks into live--helpoutput #10967 / PR cli: environments/*.ts command sources no longer spell os projects in --help #11227 · packages/cli: theos environmentsfamily's own--helptext and console output still call the entity a "project" (21 sites, v5.0 rename has no aliases) #12153 / PR fix(cli): name the entity an environment in every string theos environmentsfamily prints #12429 · Theproject→environmentrename never reached the comment axis: 14 docblock sites acrosspackages/cli/src/commands/environments/**,utils/api-client.tsand the client SDK #12432 — the three axes already carrieddoctor.tsrepeats serve'sisolatedposture sentence verbatim with its own bare@objectstack/organizationsliteral — and single-sourcing it is a coupling decision, not a substitution #12464 —doctor.ts's copy of the same sentence, filed this round