Repository navigation
[NEW-SPEC-5] Define a formal protocol/model retirement process (spec/version.json retired[]/deprecated[] arrays) #143
Description
Problem. §19.2's existing deprecation policy (confirmed at current HEAD) governs only the removal
or inversion of a spec MUST requirement — it has nothing to say about retiring a protocol model
(e.g. the pre-TC18 RCP placeholder model retired by §15.5) or its downstream port code/docs. THEME-F
and THEME-M (filed separately in this batch) show what happens without such a process: retired-model
residue reportedly persists in code, tests, and docs across three of four RCP ports roughly a full
major version after the model was declared retired with no compatibility shim.
Proposal. Add a new §3.2 "Retiring a protocol or model" plus a retired[]/deprecated[] array in
spec/version.json. When a model is superseded, RELAY MUST record it with since/removal versions.
Implementations MUST NOT advertise a retired feature in capabilities past its removal version;
retired-model code MUST be removed, or fenced behind a documented capability-declared compat flag,
within the existing §19.2 deprecation window; docs MUST NOT reference retired models outside a
CHANGELOG. relay conform MUST FAIL a binary whose features/commands name a retired capability
past its removal version.
Filed from the 2026-07-29 ecosystem audit register; independently re-verified against current HEAD before filing.
Activity
feat: protocol/model retirement process (§3.2), §17 Requirement 17 (#184
SoundMatt commentedon Aug 21, 2026
Implemented and merged in #184 (v2.6 → v2.7, MINOR).
What shipped
spec/version.jsongains optionalretired[]/deprecated[]arrays, each entry{name, since, removal, reason}.since/removalare spec MINOR-version strings; per §19.2,removalmust be at least one MINOR release aftersince.relay conformMUST FAIL a capabilities document (§12.2) whose declaredspec_versionis at or past aretired[]entry'sremovalversion but still lists that entry'snameinfeatures/commands. This is classified as fully black-box observable (unlike Requirements 13–16) — the check only needs datarelay conformalready fetches over the CLI, compared against its own embeddedspec/version.json.checkRetiredCapabilities/specVersionAtLeast/loadRetiredCapabilitiesincmd/relay/conform.go, wired intovalidateCapabilitiesDoc. NewREQ-RELAY-099, 8 new tests including a real mutation test on the comparison logic.buildManifest's Requirement 1 and 6 statuses didn't account for the capabilities command failing to run/parse entirely (§17.7) as a superset failure once findings started being filtered by precise section citation. Fixed with a sharedcapsUnreachablecheck, mutation-tested (reverted, confirmed the regression test failed, restored).Scope note
retired[]/deprecated[]ship empty by design. RELAY's own historical RCP placeholder-model retirement (§15.5, v2.0) predates §3.2 and was an instant, compat-shim-free MAJOR break — not the kind of gracefulsince/removal-spaced retirement this mechanism tracks. Backfilling it would misrepresent that history as having had a deprecation window it never had. The mechanism governs retirements declared from here onward.Verification
Local, pre-merge:
go build/vet/testclean,gofmt -l .clean,golangci-lint run0 issues,gofusa check0 errors/PASS,gofusa trace -req-coverage 100100%/100%.Post-merge, independently re-verified from a fresh clone at
91cb6be: build/vet/gofmt/test clean,gofusa check0 errors/PASS,gofusa trace100%/100%, and end-to-end —relay conform --manifestagainst the built binary reports 17 total requirements with Requirement 17 PASS, and the manifest'scapabilities_sha256matches an independently recomputed SHA-256 ofrelay capabilities' output.CI green on the
mainmerge commit (DCO, Lint, Docker build, CodeQL, Security, Test, Self-conformance, go-FuSa full safety lifecycle — all pass).