67a9243cf1
* chore: rebuild ADR index as a generated artifact and enforce lifecycle invariants
The ADR index in docs/adr/README.md was hand-maintained with nothing checking
it, and had drifted to 40 of 65 ADRs. The absent rows included the entire
capability family (857/894/959/1016/1143/1213/1244) and ADR-1239 (EoS) itself,
so the decisions a reader most needed were the ones they could not find.
Make the index a derived artifact, matching the repo's existing generated-file
idiom (lint:generated-sync), and enforce the corpus' lifecycle invariants:
- scripts/gen-adr-index.cjs generates the index between markers and validates
the status vocabulary (Accepted/Proposed/Superseded/Legacy/Retired),
successor links, id/filename agreement, and supersession symmetry.
- Wire --check into lint:generated-sync so drift fails CI.
Correct the lifecycle metadata the gate surfaced, without flipping any status:
- ADR-1239 (EoS) declared it subsumed ADR-1016/58/3660/894; none recorded it.
Add reciprocal "Subsumed by" pointers + dated amendments. Subsumption keeps
the target Accepted -- these are live adapters, not dead decisions.
- ADR-857/894 carry dated status caveats: they read Proposed while the
capability system shipped and epic #857 is closed. Ratification is a
maintainer act and is deliberately left open.
- Link ADR-0005/0007/0012/3524 -> ADR-0174 and ADR-0010 -> ADR-0009; record
the reciprocal Supersedes on ADR-0009.
- ADR-218 declared itself "ADR-0175" -- an unfinished rename.
- The 0011 PRD moves from the non-canonical "Draft" to "Legacy".
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* test: capture stderr via spawnSync; record ADR-0010 draft supersession
Two fixes surfaced by the first gsd-test run and by regenerating the index:
- tests/adr-index-gate.test.cjs used execFileSync, which only surfaces stderr
through the thrown error on non-zero exit. The `--write` path exits 0 while
reporting outstanding violations on stderr, so the helper always saw ''.
spawnSync captures both streams on both outcomes.
- The hand-maintained index recorded 0010-skill-surface-budget-module.md as
"earlier draft superseded by ADR-0011" while the file itself still said
Proposed. Deriving the index from the files would have dropped that
assertion and resurrected a superseded draft as a live decision, so it is
recorded at its source, with the reciprocal Supersedes on ADR-0011.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: drop the dead sdk/ model-catalog candidate retired by ADR-0174
src/model-catalog.cts resolved model-catalog.json through three candidates, the
second being sdk/shared/model-catalog.json three levels up. That was the legacy
source-repo fallback kept by the #3288 fix ("check the co-located path FIRST,
before the legacy source-repo path").
ADR-0174 then retired the @opengsd/gsd-sdk package boundary and deleted the sdk/
tree (11918dcc3), so the candidate can no longer resolve in any layout: a source
repo has no sdk/, and an install layout points it at ~/.claude/sdk/shared/, which
the installer never writes -- the original #3288 bug. It was dead weight implying
a package boundary this repo no longer has.
No test depends on it: the #3288 regression tests in tests/install.test.cjs write
their own synthetic old-path fixture and assert it throws.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: ratify nine shipped ADRs; record why ten others stay Proposed
The corpus carried 19 Proposed ADRs, most describing architecture that had
already shipped. A Proposed label on live architecture tells contributors and
agents the decision is an unbuilt idea -- the capability system and EoS were
both being misread that way.
Audited all 19 against the shipped tree and GitHub. Each candidate flip then had
to survive two independent reviewers instructed to refute it.
Ratified Proposed -> Accepted, each with a dated Ratification section carrying
the verified evidence (file:line, symbols, tests, issue state):
857 capability system 894 declaration format 1244 capability ecosystem
1577 injection boundary 1610 size-budget ratchet 1990 existing-code onboarding
15 cross-AI convergence 22 plan-drift guard 0011 default reviewers
Held ten, each now carrying a "Why this is still Proposed" section naming the
blocker and its unblock condition, so the audit is not repeated:
2264 its own headline acceptance criterion is unmet in the tree
230 live branch protection contradicts the decided spec (1 approval, not 2)
660 the namesake release/<version> re-cut is manual, not automated
959 issue #2346 is approved and plans its graduation as its own ADR
1213 the shipped writer's return shape differs from the decided interface
443 the orchestrator override path has no live caller
1143 / 1606 each states its own bar for acceptance; neither is met
612 / 1671 legitimately open
Shipped code proved necessary but not sufficient: eight ADRs had every named
module, symbol, and test present with their epics closed, and still failed the
bar. That lesson is written into README.md's ratification procedure.
Also corrected ADR-857's "Supersedes (generalizes)" to "Subsumes": taken
literally it would have marked two live seams dead -- ADR-0011 (surface.cts:348)
and ADR-58 (runtime-artifact-install-plan.cts:82). Both keep Accepted status and
gain Subsumed-by pointers.
Index: Active 39->48, Proposed 19->10, Superseded/Legacy 7. 65 total.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: harden gen-adr-index against hostile titles and non-ADR filenames (#2356)
Three findings from the pre-PR orthogonal security review, all confirmed:
- An ADR title containing the literal ADR-INDEX:END marker was emitted verbatim
into its table cell, relocating the splice boundary so the NEXT --write
spliced against the wrong marker and truncated README.md. Titles now render
through cellText(), which escapes pipes and angle brackets -- making an HTML
comment (and any other HTML) unformable from ADR-authored text.
- A docs/adr/*.md without a numeric prefix crashed on match(...)[1] of null.
Such a file is also invisible to the index -- the very failure this gate
exists to prevent -- so it is now reported as a naming-convention violation
naming the file and the fix.
- Tests leaked their mkdtemp dirs. They now use helpers.createTempDir/cleanup
via t.after(); helpers.cleanup carries the Windows-EBUSY retry budget that a
raw fs.rmSync lacks (caught by local/no-raw-rmsync-in-tests).
Adds five regression tests: marker hijack, HTML injection, pipe cell-break,
non-conforming filename, and splice stability across repeated writes.
Refs #2356
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: close two gate false-passes; read ## Supersedes sections (#2356)
Second round of confirmed findings from the pre-PR orthogonal code review. Both
false-passes matter more than a false-fail: a gate that silently misses a
violation is worse than no gate, because it is trusted.
- A relation field mixing a link with a bare id silently dropped the bare claim:
the check tested `rel.links.length` (does this field have ANY link?) instead
of whether THAT id was linked. `Supersedes: [ADR-0001](...), ADR-0011` passed
clean -- accepting exactly the ambiguous bare reference the rule forbids. Now
each bare id is checked against the ids actually linked in the same field, so
a repeat in trailing prose stays quiet while an unlinked claim is flagged.
- The ratification guard (`statusToken !== 'Accepted'`) skipped BOTH relation
directions, which killed the IN check entirely: `supersedes.in` is only ever
populated on an ADR whose status IS `Superseded`, so a dangling `Superseded by
X` where X never claims it always passed. The guard now applies to OUT only --
a prospective claim must not obligate its target, but an ADR's statement about
ITSELF is always owed a reciprocal.
- Fixing that surfaced a parser gap: ADR-0174 declares its supersessions in a
`## Supersedes` table SECTION, not a header field, and headerBlock() stops at
the first `##`. The repo's best-documented supersession was invisible. Section
form is now parsed for both relations.
- Replaced a vacuous test: the em-dash negation case passed whether or not
NEGATED_RELATION_RE matched (a mutation to /$^/ survived). It now carries a
link that would create a failing asymmetric relation if negation did not fire.
Also removes docs/adr/9401-test-target.md -- a synthetic fixture a reviewer
created in the worktree while reproducing a finding, swept in by `git add -A`.
Adds regression tests for each: mixed link+bare, linked-and-repeated-in-prose,
dangling superseded-by from a non-Accepted ADR, and the ADR-0174 section shape.
Refs #2356
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: escape backslashes before pipes in the ADR index cell renderer (#2356)
CodeQL js/incomplete-sanitization (high) on scripts/gen-adr-index.cjs: cellText()
escaped `|` -> `\|` without first escaping the backslash. Markdown's escape
character is the backslash, so the input `\|` became `\\|`, which renders as a
literal backslash followed by an UNESCAPED pipe -- re-opening the cell break the
pipe escape exists to prevent. Order is load-bearing: escape the escape
character first, then everything that emits one.
Same class as the index-marker hijack fixed earlier: ADR-authored text breaking
out of the cell it is rendered into.
Adds a regression test asserting a `\|`-bearing title leaves exactly the row's
own 5 unescaped delimiters and cannot forge a Status cell. Uses split(/\r?\n/)
per local/no-crlf-fragile-split -- a literal "\n" split is CRLF-fragile on the
Windows CI leg.
Refs #2356
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
209 lines
13 KiB
Markdown
209 lines
13 KiB
Markdown
# ADR 660: Release from the head of `next`; immutable release tags; `@next` dist-tag as the RC surface [Proposed]
|
||
|
||
- **Status:** Proposed
|
||
- **Date:** 2026-06-03
|
||
|
||
## Why this is still `Proposed` (audited 2026-07-17)
|
||
|
||
Confirmed shipped: immutable per-release tags (`finalize` mints `v<version>` exactly once at
|
||
line 629; `rc` auto-increments `v<version>-rc.N` at line 353 — no force-push or re-tag anywhere
|
||
in the file), the `@next`/`@latest` dist-tag split (`npm publish --provenance --access public
|
||
--tag next` in the `rc` job at line 437 vs. the default/`latest` publish in `finalize` at line
|
||
636), and the Amendment (2026-06-12, #1104) "`next` rests at last published" behavior, wired
|
||
through `scripts/sync-next-version.cjs` in both the `rc` job (`release.yml:479`) and the
|
||
`main`→`next` back-merge (`auto-backmerge.yml:176-178`).
|
||
|
||
**The blocker.** Decision §1 — the mechanism this ADR is named for — is not implemented: "recreate
|
||
(or hard-reset) an **ephemeral** `release/<version>` branch from `origin/next` HEAD at the *start*
|
||
of each `rc`/`finalize` run." In the live `.github/workflows/release.yml`, the `create` job still
|
||
creates `release/<version>` once and hard-errors if it already exists ("Branch $BRANCH already
|
||
exists. Delete it first or use rc/finalize.", lines 126–133); the `rc` job's checkout (line 330)
|
||
and the `finalize` job's checkout (line 522) both simply check out that same pre-existing ref —
|
||
neither job fetches, resets, or recreates it from `origin/next`. This is exactly the "persistent
|
||
branch you never backport into" antipattern the ADR's own Context section set out to kill, and
|
||
precisely the alternative its own Alternatives section rejected ("Keep the persistent branch but
|
||
cherry-pick RC fixes into it ... Rejected as primary"). `docs/adr/README.md:98` already names this
|
||
ADR in the corpus audit as one whose "namesake mechanism is performed by hand." Issue #660 is
|
||
closed `COMPLETED`, but its scope was landing the ADR/design decision, not the `release.yml`
|
||
re-cut step — no commit since has added it; today, cutting an rc "on the head of `next`" still
|
||
requires a manual `git push --force origin <next-head>:refs/heads/release/<version>` before
|
||
dispatching the workflow.
|
||
|
||
**Unblock condition.** Add a step to both the `rc` and `finalize` jobs in
|
||
`.github/workflows/release.yml` that hard-resets (or recreates) `release/<version>` from
|
||
`origin/next` HEAD before the version bump, so the re-cut happens automatically on every
|
||
dispatch instead of via a manual force-push. Once that step exists in the file and one real
|
||
`rc`/`finalize` run has exercised it end to end, this ADR is ready for another ratification pass.
|
||
|
||
## Context
|
||
|
||
The release pipeline (`.github/workflows/release.yml`) is a three-mode `workflow_dispatch`
|
||
(`create` / `rc` / `finalize`) built around a **persistent, long-lived `release/<version>`
|
||
branch**:
|
||
|
||
- `create` cuts `release/<version>` from `next` and commits a version bump.
|
||
- `rc` checks out that same branch (`ref: release/<version>`), bumps to `-rc.N`, tags
|
||
`v<version>-rc.N`, and publishes to the `@next` npm dist-tag.
|
||
- `finalize` checks out that same branch, bumps to the final version, tags `v<version>`,
|
||
publishes to `@latest`, opens a PR back to `main`, and `auto-backmerge.yml` later merges
|
||
`main` → `next`.
|
||
|
||
This has a structural defect. **No job ever brings post-`create` work from `next` into the
|
||
release branch** — there is no `git merge`/`rebase`/`cherry-pick` from `next` anywhere in
|
||
`release.yml`. So the moment RC testing surfaces a bug:
|
||
|
||
1. The fix is (correctly) committed to `next` — our trunk.
|
||
2. The `release/<version>` branch does **not** receive it.
|
||
3. `finalize` therefore ships the *rc-cut* tree, **missing every RC fix**.
|
||
|
||
To compensate, we have been **hand-moving the `v<version>` tag forward** to the head of
|
||
`next` each cycle. This is the "dance every release." It is two documented antipatterns
|
||
stacked:
|
||
|
||
- **Freezing a release branch you never backport into.** Trunk-based development requires fixes
|
||
to flow *trunk → release branch* (fix on trunk, cherry-pick down), never "fix on trunk and
|
||
leave the release branch behind"
|
||
([trunkbaseddevelopment.com/branch-for-release](https://trunkbaseddevelopment.com/branch-for-release/)).
|
||
GitFlow's own author now steers continuous-delivery projects away from this model
|
||
([nvie.com](https://nvie.com/posts/a-successful-git-branching-model/)).
|
||
- **A movable release tag.** Git's manual ("On Re-tagging") and SemVer both forbid it —
|
||
*"Once a versioned package has been released, the contents of that version MUST NOT be
|
||
modified"* ([semver.org](https://semver.org/)). Moving a published tag breaks our SSH
|
||
signatures, already-fetched clones, caches, and the GitHub Release; GitHub shipped
|
||
*Immutable Releases* (GA 2025) specifically to stop this.
|
||
|
||
We have meaningful existing investment we want to **keep**: the homegrown changeset/CHANGELOG
|
||
fragment system (`scripts/changeset/*.cjs`, `changeset-required.yml`), the curated
|
||
release-notes formatter (`scripts/release-notes/format-github-release-notes.cjs`), the
|
||
inter-stage smoke-test gates, provenance publishing, and the `main`(@latest) / `next`(integration)
|
||
+ `auto-backmerge` topology — which is already the correct "main holds releases, next is
|
||
integration" shape.
|
||
|
||
## Decision
|
||
|
||
**Stop persisting/freezing the release branch. Always release from the current head of `next`,
|
||
create each release git tag exactly once, and treat the `@next` npm dist-tag — not a git branch
|
||
or a movable tag — as the RC surface.** Concretely:
|
||
|
||
1. **The release point is always `next`'s head at invocation time.** `rc` and `finalize` derive
|
||
their tree from the current `origin/next` HEAD rather than reusing a stale `release/<version>`
|
||
branch. Implementation: recreate (or hard-reset) an **ephemeral** `release/<version>` branch
|
||
from `origin/next` HEAD at the *start* of each `rc`/`finalize` run. The final version-bump
|
||
commit lands on this short-lived branch and reaches `main` via the release PR; the branch is
|
||
a scratch staging area, not a frozen snapshot — so it *always* contains every RC fix.
|
||
|
||
2. **`next` carries a `-dev` prerelease version (the dev stream).** Between releases, `next`'s
|
||
`package.json` no longer rests at the last-released number — it carries `X.Y.Z-dev.N` for the
|
||
*anticipated* next version, so the trunk self-identifies as unreleased. Default floor after
|
||
releasing `A.B.C` is the next patch, `A.B.(C+1)-dev.0` (precedence-safe: greater than `A.B.C`,
|
||
and it never overstates the eventual release, which `finalize` may set higher). `@next`
|
||
dist-tag publishes carry this `-dev` snapshot identity; `rc` overrides it with the chosen
|
||
`-rc.N`; `finalize` sets the final number. After `finalize` + the `main`→`next` backmerge, a
|
||
post-release step bumps `next` to the new `-dev` floor.
|
||
|
||
3. **Release tags are immutable, created once, by `finalize` only.** No tag is ever
|
||
pre-created as a placeholder or force-moved. `finalize` mints `v<version>` on the final
|
||
commit and pushes it once. (This also removes the manual step that currently *breaks*
|
||
`finalize`, whose tag-existence guard hard-errors on any pre-existing `v<version>` tag.)
|
||
RC tags `v<version>-rc.N` remain — each N is unique and never moved, so they are already
|
||
immutable and serve the GitHub prerelease.
|
||
|
||
4. **RC = the `@next` dist-tag, full stop.** Testers run `npm i -g @opengsd/gsd-core@next`.
|
||
Because each `rc` run is cut from `next` HEAD, every rc.N already includes all prior fixes.
|
||
No long-lived branch, no tag movement. `finalize` promotes the released version to `@latest`
|
||
(`@next` remains the prerelease channel managed exclusively by the `rc` job; `finalize` does not repoint it).
|
||
|
||
5. **Everything else stays:** custom changesets + CHANGELOG render, release-notes formatter,
|
||
smoke-test gates, provenance, `main`/`next`, `auto-backmerge` (main→next).
|
||
|
||
In short: the immutable `v<version>` tag that `finalize` creates — landing on `main` via the
|
||
release→main PR — **is** the "historical marker for the release" we wanted. The intuition was
|
||
right; only the *movable placeholder* mechanic was wrong.
|
||
|
||
## Alternatives considered
|
||
|
||
- **Adopt `release-please`.** Auto-updating Release PR off `next` would also kill the freeze, and
|
||
tags are immutable. **Rejected for now:** it generates CHANGELOG from conventional commits,
|
||
displacing our custom changeset-fragment system; its prerelease→stable transition has known
|
||
open bugs (googleapis/release-please #2515, #2447). Migration cost > the defect it fixes.
|
||
- **Adopt `@changesets/cli`.** Closest to our homegrown system and has a mature auto-updating
|
||
Version PR. **Rejected for now:** would replace working in-house tooling, and its `pre`
|
||
mode has real footguns (the `pre.json`-not-staged bug silently publishes stable under the
|
||
`rc` dist-tag — changesets #1150).
|
||
- **Adopt `semantic-release`.** Lowest ceremony, native `next`→`main` channel promotion.
|
||
**Rejected:** "auto-release on every conventional commit" removes the deliberate
|
||
"decide to cut a release" gate we want, and again displaces our changeset/changelog system.
|
||
- **Keep the persistent branch but cherry-pick RC fixes into it.** The textbook trunk-based
|
||
approach. **Rejected as primary:** for a single active version it is pure bookkeeping
|
||
overhead, and "forgot to cherry-pick" is exactly the regression trap the literature warns
|
||
about. Re-cutting from `next` HEAD gets the same result with zero manual cherry-picks.
|
||
|
||
## Consequences
|
||
|
||
**Positive**
|
||
- The "dance" is gone: RC fixes are included by construction; no manual tag moves; no frozen
|
||
branch to reconcile.
|
||
- Tags become trustworthy and signature-valid — one commit, one immutable tag, per release.
|
||
- We keep all existing investment (changesets, formatter, smoke gates, backmerge) — small,
|
||
low-risk diff to `release.yml`, no new third-party release dependency.
|
||
|
||
**Negative / costs**
|
||
- `release.yml` changes required: `rc`/`finalize` must recreate/reset the release branch from
|
||
`origin/next` at start; remove any reliance on a pre-existing tag.
|
||
- `create` becomes near-vestigial (its only job — seed the branch + bump — folds into `rc`/
|
||
`finalize` re-cutting from `next`). Decide whether to delete `create` or keep it as an
|
||
optional "open the release branch early" convenience.
|
||
- One-version assumption is now explicit: this model does **not** support maintaining multiple
|
||
live majors (LTS). If that need ever arises, revisit (long-lived `release/x.y` + cherry-pick
|
||
is the escape hatch).
|
||
|
||
## Rollout
|
||
|
||
- **File this ADR first** (maintainer decision): land the proposing issue + ADR PR before any
|
||
release action, so the model is documented before it is first exercised.
|
||
- **1.3.0 (first manual run):** ship it as the first *manual* application of this model —
|
||
recreate `release/1.3.0` from `next` HEAD (`6bd7ceb2`), delete the hand-moved `v1.3.0` tag so
|
||
`finalize` mints it fresh, then run `finalize` (dry-run first). This validates the model by
|
||
hand before we codify it. Immediately after, bump `next` to its first `-dev` floor
|
||
(`1.3.1-dev.0`).
|
||
- **Codify (1.4.0+):** update `release.yml` per the Decision (re-cut from `next`, `-dev` stream,
|
||
post-release `-dev` bump); update `docs/branching.md`; delete or repurpose `create`.
|
||
|
||
## Resolved by maintainer (2026-06-03)
|
||
|
||
- **Approach:** re-cut from `next`'s head; keep the in-house tooling (no third-party release tool).
|
||
- **`next` version:** move to a `-dev` stream (Decision §2), *not* resting at last-released.
|
||
- **Sequencing:** file this ADR first, then ship 1.3.0 as the first manual run.
|
||
|
||
## Open questions (remaining)
|
||
|
||
1. Delete the `create` action, or keep it as an optional early-branch convenience? *(Recommend:
|
||
delete; re-cut from `next` makes it redundant.)*
|
||
2. Keep immutable `v<version>-rc.N` git tags, or rely on the `@next` dist-tag alone for RCs?
|
||
*(Recommend: keep the rc tags — harmless, immutable, and they anchor the GitHub prerelease.)*
|
||
3. `-dev` floor increment: next-patch (`A.B.(C+1)-dev.0`, the precedence-safe default above) or
|
||
next-minor (`A.(B+1).0-dev.0`)? *(Recommend: next-patch floor.)*
|
||
|
||
## Amendment (2026-06-12, #1104): `next` tracks the last published release
|
||
|
||
**Supersedes** the §2 / "Resolved by maintainer" choice to rest `next` on a `-dev` stream.
|
||
|
||
The `-dev` floor (e.g. `1.3.1-dev.0`) was never published to npm, yet it became the
|
||
source-of-truth version on the default branch and leaked to the real world via source/dev
|
||
installs that report `package.json`'s version — a version no release ever bore. To eliminate
|
||
phantom versions, `next` now **rests at the last published release** and is synced
|
||
automatically by the release pipeline for **every** release type:
|
||
|
||
- **finalize / hotfix** (these push `main`): the existing `main → next` back-merge
|
||
(`.github/workflows/auto-backmerge.yml`) sets `next`'s version to `main`'s released version,
|
||
folded into the same back-merge PR.
|
||
- **rc** (publishes a pre-release to the `release/<version>` branch + `@next`; does **not** push
|
||
`main`): the `rc` job in `.github/workflows/release.yml` opens and admin-merges a
|
||
`chore: sync next package version` PR after a confirmed publish.
|
||
|
||
Both paths share `scripts/sync-next-version.cjs`, which sets `package.json` and stamps the
|
||
runtime manifests (`plugin.json`, `gemini-extension.json`) via the `version` lifecycle hook,
|
||
and **refuses any non-release version string** (fail-closed — a `-dev`/placeholder can never be
|
||
written to `next` again). Open question 3 (the `-dev` floor increment) is therefore moot: there
|
||
is no `-dev` floor.
|