docs(adr): record the v5.0 project to environment rename in ADR-0006, and land its inbound pointers

[zhuangjianguo]

Fixes #12747
Fixes #12748

Ruled convoy, one governed PR, per-member commits. Both rulings are the maintainer's 2026-08-29 director-batch adjudications on the two cards; nothing here re-opens them.

Member 1 (#12747) — the rename gets written down

ADR-0006 v4 gains one section, The v5.0 rename and its no-alias decision, recording what the v5.0 project to environment rename covered, that no alias was kept, and why. Every factual claim in it was measured on this branch rather than recalled:

Claim in the section	How it was measured
CLI command group is environments, no projects group	packages/cli/src/commands/environments/ holds list show create switch bind; packages/cli/src/commands/projects does not exist
Routes are /api/v1/cloud/environments	grep across packages/, non-test sources
Header X-Environment-Id, no X-Project-Id	read in packages/rest/src/rest-server.ts; x-project-id has zero hits
Env var OS_ENVIRONMENT_ID, no OS_PROJECT_ID	read in packages/runtime, service-job, cloud-connection; OS_PROJECT_ID has zero hits
No declared alias	ADR-0087's conversion registry carries no project to environment entry

The section states its reasons itself and does not cite the instruction file — that is the ruling's explicit constraint, because the loop it replaces was the record quoting back the very sentence the reader had just followed. Its three reasons are one-word-per-concept, alias-outlives-its-reason, and the pre-launch window, the last grounded in a quotation from this record's own Context rather than invented history.

It also carries a What this section does not claim paragraph. project is still correct in the npm/monorepo sense and in domain fixtures modelling a customer's own project object, so the claim is deliberately the narrow, checkable one.

The three banners moved together and are still byte-identical after the edit (measured: 1 distinct banner text across ADR-0004/0005/0008, the same property they had before). Each is repointed at the new section, and the changeset path they named for the breaking-change list is dropped — .changeset/v5-project-to-environment-rename.md is measurably absent, consumed at release, which is exactly why a durable doc should not have cited it.

AGENTS.md has a zero-line diff, as the ruling expected. Its See ADR-0006 becomes true as written because the target now exists; the pointer text needed no change, so the #13059 ceiling precedent was not invoked.

Member 2 (#12748) — the two Builds-on links land on the Accepted revision

docs/adr/0007-settings-manifest-and-kv-store.md:5 and docs/adr/0008-metadata-repository-and-change-log.md:8 linked ADR-0006 under the bare filename, which holds the Superseded v3. Both now point at .v4, each with the ruled short parenthetical recording that the record was originally built on v3 — so the reader lands on the revision carrying the API-surface boundary without the historical fact being silently destroyed. After the edit, anchored greps find zero bare-filename links left under docs/adr/.

Option 3, a mechanical Builds-on-vs-Superseded rule, is not taken, per the ruling.

The two inspect-only mentions — inspected, neither is a citation

The cards were right to fence these off. Both were read before anything was touched, and neither was changed:

• CHANGELOG.md:790,793 — entries in a past release's record, stating that the v4 file was added and that v3 was marked superseded. That is release history describing events, not a pointer a reader follows. Retargeting it would falsify the record of what shipped.
• scripts/check-adr-anchors.mjs:255-256,509 — a docblock example illustrating how the script parses stem and version out of a filename, and a failure-message hint naming the .vN convention. The script names the path as an illustration of a filename pattern; it holds no citation to ADR-0006's content. Retargeting it would be a silent behaviour change dressed as a docs fix.

Also carried: ADR-0006 v2's Status line

Two files under one ADR number both read Accepted. This was flagged as an assumption to verify before acting, not as ruled text, so it was verified by reading v2's body rather than inferred from its title. v2's Decision keeps sys_project as the physical table, plans a dual sys_project / sys_environment ORM name, and holds the API URLs at /api/v1/cloud/projects with provisionProject on the SDK. Every one of those is reversed by v4 and by the rename — and the dual-name plan is precisely the alias posture the rename refused. Nothing in it is uniquely live, so its Status is corrected to Superseded by v4, matching v3's existing spelling.

Worth noting why this one mattered: unlike v3, v2 carried no redirect of any kind, so a reader or a corpus scan keying on Status: Accepted had nothing telling it to go read v4.

Neither v2 nor v3 is deleted — they are part of the record.

Verification

Gate family re-derived against the actual diff with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (its first run warned STALE TREE; origin/main was merged in and it was re-derived clean). All runs below are at d0c713183, which is this branch's head:

Gate	Its own verdict line
check:adr-anchors	OK (52 anchored file(s) … 30457 citation(s) across 3894 file(s) resolve …)
node scripts/check-adr-links.mjs	579 relative link destination(s) under docs/adr/ resolve
check:doc-authoring	393 files clean — no bare metadata literals
check:doc-formula-expressions	22 record-scoped formula example(s) across 426 files / 1451 TS blocks judged clean
check:pm-governed-merges	206 assertions self-test pass
check:nul-bytes	OK (scanned 7408 text file(s) … no raw ASCII control bytes)

Also run green though not derived for this diff: check:agent-test-spelling, check:docs-audit-scope, check:pm-governed-prose, check:pm-skill-id-lint, check:pm-skill-ratchet, check:required-contexts, node scripts/check-required-contexts.mjs.

check:doc-formula-expressions first exited 1 with PREREQUISITE NOT MET on two unbuilt workspace packages. That is not a gate failure and is not recorded as one — nothing was measured until @objectstack/formula and @objectstack/lint were built, after which it ran and passed.

skip-changeset applies: the diff is entirely within docs/adr/**, publishes nothing from any package, and AGENTS.md and the anchors script both have a zero diff.

One deviation from the suggested route

The suggested placement was immediately after the existing v5.0-boundary addendum. Placing it there would have split #12473's addendum from the #12867 addendum that retires its D1 — a matched pair — and would have falsified two live cross-references inside the file, which name the second addendum at the end of this file and the first addendum. A third addendum appended at the end breaks the first; one inserted between them breaks the ordinals.

So the section sits after ## References and before both addenda, and is titled as a plain section rather than an addendum, leaving both ordinals and at the end of this file true. It is date-stamped in its first line so it is not misread as part of the 2026-05-20 body, and the logical order now reads: the rename and why, then where it stops, then that boundary's retirement.

Governed surface

docs/adr/** — this PR stays draft for the maintainer's hand merge. This seat does not flip it ready, does not queue it, and does not arm auto-merge.

---

Generated by Claude Code