A completed spec no longer describes the codebase, and nothing in the tree says so. Agents read it as current, notice the drift, and open merge requests to "fix" a document whose plan shipped months ago. The decision, agreed in Slack: delete the spec and its plans, keep git history as the archive, and move anything that genuinely needs to be stated across several files into a dev doc. An `implemented/` folder was considered and rejected — it duplicates the codebase, and archaeology in git history answers the rare question that needs the original intent. ## What has landed Three pieces have run against the steps below. Everything in this section is read at `main` bf703e4b6; the measurements further down keep their declared 49d5c5689 basis unless they say otherwise. **Step 1, the definitions — partly.** c2bf2b29c wrote both definitions into docs/specs/README.md and docs/plans/README.md, together with the retired-row shape each index takes, and added a `## A reference to a retired spec or plan is repaired per site` section to docs/dev/writing-discipline.md covering the per-site repair, the bare-id ban, and what a line-pinned citation becomes. What step 1 still owes: the MR column's `[!N](url)` format, which is stated in neither docs/plans/TEMPLATE.md nor docs/dev/conventions.md, and the empty-cell reading, which still says "not yet recorded" in AGENTS.md guardrail 4, docs/dev/conventions.md and docs/plans/TEMPLATE.md. **The correction pass, greppable half — 15 of 24 rows.** c032e5463 recorded 13 rows across seven plans, and db54ed2c1 recorded docs/plans/2026-08-27-s32-container-virtual.md steps 2 and 3. The nine docs/plans/2026-09-10-s30-maven-virtual.md rows are the whole remainder; that plan still records none of its 25 steps. 86 empty MR cells stand across 16 plans, down from 102. The hand-checked half and the 275 bare `!N` conversions have not started. **The first retirement — S04-C.** https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2879 (e23208cca) deleted docs/specs/S04-c-column-level-encryption-wiring.md and docs/plans/2026-08-02-s04c-encryption-wiring.md, moved the composition-root wiring contract into docs/dev/column-encryption.md, and swept every reference in one merge request: retired rows in both indexes, the Go comment in internal/metrics/cardinality.go, prose in docs/dev/observability.md, docs/specs/S04-b-encryption-key-rotation-tooling.md, docs/specs/S13-virtual-remote-foundation.md, docs/specs/S32-container-virtual.md, two plans and docs/roadmap/closed-beta.md. The two plans keep the retired text where they need it, as commit-pinned permalinks rather than links into the deleted file. What survives at HEAD is the two retired index rows and dated roadmap narrative, which is what the rule allows. That merge request is the shape the rest of the batches take: one merge request retires the spec, its plans, their index rows and every reference, with the extraction merged first or carried in it. ## Why it matters The corpus an agent reads as current is large: at 49d5c5689, 32 Go-service specs total 33,843 lines and 55 Go-service plans total 71,313 lines. Every grep for a symbol crosses them, and every crossing invites a correction merge request against design intent that has already been served. The drift is not theoretical. These are all open bookkeeping issues against spec or plan text rather than against code: - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1189 — 17 comment sites in `internal/format/oci/upload.go` cite S12 line numbers, and all 18 numbers are stale - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1191 — a S20-A spec line goes stale as soon as the Maven reap order changes - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1185 — S20-A records a purge chunk order that https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2051 reversed - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1186 — monolith S06 and S14 Phase 2 tables are stale against the merged S17 contract - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1274 — a test hand-transcribes S11's Error Cases table and drifts from it - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1187 — the plans README index lacks a row for nine plan files Two conversions have already run and are the working template: 0d825f90c converted the S22 spec and plan into docs/dev/storage-accounting.md, and dddc6cc7b converted S06 into docs/dev/storage.md. Both left a landing-point stub behind (26 and 22 lines). The strategy this issue records goes one step further and removes the stubs too, so there is no half-live document left to read. ## What completed means The definition is strict: it reads the plan file and nothing else. ### A completed implementation plan **Every step in its Status table is implemented by an MR, and that MR is recorded in the table's MR column as a `[!N](url)` link.** No archaeology. A reader deciding whether a plan can be deleted opens the plan, reads the Status table, and is done. Where the table disagrees with what merged, the table is the defect and gets corrected — see the correction pass below, which is a prerequisite for the first deletion. This changes what an empty cell means. Today the convention reads "an empty cell means not yet recorded, not not-started", in AGENTS.md guardrail 4, docs/dev/conventions.md (`### Plan status-table updates`), docs/plans/TEMPLATE.md, and the Status footer each plan copies from the template. Under the strict definition an empty cell means the step has not merged, so the single writer records a row when the step MR merges rather than eventually, and all five of those places change together with step 1 below. ### A completed spec **At least one plan implements it, and every plan that implements it is completed.** Implements means the plan's `- Spec:` bullet names the spec. A plan that cites a spec for a contract it preserves but does not change is not related to it under this rule: docs/plans/2026-09-11-maven-metadata-purge.md names S17 as a preserved contract, and S17's completion does not wait on that plan. Where a plan's `- Spec:` bullet disclaims a single owner and then names the specs it amends, it implements every spec it amends — docs/plans/2026-09-03-repository-column-writers.md spans S10, S11, S12, S15 and S16 that way. Where the bullet disclaims a single owner and names no spec it amends, the plan implements nothing and blocks no spec, which is the shape of docs/plans/2026-05-21-blob-storage-attachments-foundation.md and docs/plans/2026-09-03-upload-session-concurrency-cap.md. A spec with no implementing plan is in progress, not completed, which is the state of S05 (distributed-state) and S34 (development-mode) at 49d5c5689. A spec whose plans were deleted by an earlier retirement counts zero plans for the opposite reason, so retirement is recorded rather than inferred: step 3 below keeps a retired row in docs/specs/README.md and docs/plans/README.md naming the dev doc and the deleting commit, and zero plans with no retired row means in progress. S06 (storage-layer) is the case that forces this — dddc6cc7b deleted its plan, so nothing else in the tree distinguishes it from a spec whose work has not begun. ## The correction pass The strict definition does not hold today, so it starts with a correction. All figures measured at 49d5c5689. Of 102 empty MR cells across 55 plans, 24 belong to a step that has merged. They are recorded in one `docs(plans)` branch, which is where Status rows are written from: the table has a single writer, and step MRs never edit it. | Plan | Step | MR | | --- | --- | --- | | 2026-05-21-blob-storage-attachments-foundation | 1 | [!276](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/276) | | 2026-08-27-s32-container-virtual | 2 | [!2277](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2277) | | 2026-08-27-s32-container-virtual | 3 | [!2682](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2682) | | 2026-09-01-package-id-fk-check-indexes | 1 | [!2762](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2762) | | 2026-09-03-repository-column-writers | 5 | [!2732](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2732) | | 2026-09-03-s04a-per-format-credential-columns | 4 | [!2553](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2553) | | 2026-09-03-s04a-per-format-credential-columns | 5 | [!2629](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2629), [!2630](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2630) | | 2026-09-03-s04a-per-format-credential-columns | 7 | [!2647](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2647) | | 2026-09-03-s04a-per-format-credential-columns | 8 | [!2658](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2658), [!2662](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2662) | | 2026-09-03-upload-session-concurrency-cap | 8 | [!2560](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2560) | | 2026-09-10-s30-maven-virtual | 1 | [!2697](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2697) | | 2026-09-10-s30-maven-virtual | 2 | [!2719](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2719) | | 2026-09-10-s30-maven-virtual | 3 | [!2758](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2758) | | 2026-09-10-s30-maven-virtual | 5 | [!2702](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2702) | | 2026-09-10-s30-maven-virtual | 6 | [!2703](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2703) | | 2026-09-10-s30-maven-virtual | 7 | [!2690](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2690) | | 2026-09-10-s30-maven-virtual | 8 | [!2737](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2737) | | 2026-09-10-s30-maven-virtual | 12 | [!2691](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2691) | | 2026-09-10-s30-maven-virtual | 16a | [!2692](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2692) | | 2026-09-11-maven-metadata-purge | 1 | [!2695](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2695) | | 2026-09-11-maven-metadata-purge | 2 | [!2731](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2731) | | 2026-09-11-maven-metadata-purge | 3 | [!2777](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2777) | | 2026-09-11-maven-metadata-purge | 4 | [!2759](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2759) | | 2026-09-11-npm-provenance-attestations | 1 | [!2773](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2773) | Fifteen of those 24 rows have since been recorded — see [What has landed](#what-has-landed) — and the nine `2026-09-10-s30-maven-virtual` rows are the remainder. That list is the greppable half of the sweep, derived from `git log --pretty='%H %s' origin/main`, a grep for the `(<plan token> plan: <step>/<total>)` marker, and `projects/:id/repository/commits/:sha/merge_requests` per hit. **A second half has no command.** 21 empty cells sit on plans whose steps predate or straddle the marker convention, so a marker's absence says nothing about them and each row is checked against its step work item by hand: docs/plans/2026-05-26-database-composition-root.md step 3; docs/plans/2026-07-15-npm-remote.md steps 1, 2, 3, 4 and 16; docs/plans/2026-07-16-s13-virtual-remote-foundation.md steps 6 and 13; docs/plans/2026-08-03-s04b-rotation-tooling.md steps 3 and 4; docs/plans/2026-08-11-s20a-lifecycle-closed-beta.md step 20b; docs/plans/2026-08-13-s17-phase6-virtual-remote-repositories.md steps 41 and 42; docs/plans/2026-08-17-gitlab-api-service-auth.md step 3; and docs/plans/2026-08-21-s31-npm-virtual.md steps 13 through 19. The npm-remote schema steps are the likeliest to have merged long ago; the S31 tail is the likeliest to be genuinely open. The remaining 57 empty cells are steps the marker sweep shows as unmerged, so they are correct as they stand. **The MR column's link format is a second defect, and a larger one.** Of 592 recorded MR references, 275 across 27 plans are bare `!N` rather than the `[!N](url)` link the column takes. A bare `!N` renders as a plain string wherever the file is read outside GitLab's own markdown renderer, which includes every agent that greps the tree. The format is not written down anywhere — not in docs/plans/TEMPLATE.md, not in docs/dev/conventions.md `### Plan status-table updates` — which is why it drifted, so step 1 states it and the correction pass converts the 275. Whether the 275 conversions ride the same `docs(plans)` branch as the 24 backfilled rows or a separate one is the author's call; they touch the same tables, so one branch avoids a rebase against itself. ## The steps 1. **Write the retention rule down.** The two definitions above, and where durable content goes. Lands in docs/specs/README.md, docs/plans/README.md, and docs/dev/writing-discipline.md, with an AGENTS.md routing row only if it opens a new module. The same step states the MR column's `[!N](url)` link format in docs/plans/TEMPLATE.md and docs/dev/conventions.md, and replaces the "not yet recorded" reading of an empty cell in AGENTS.md guardrail 4, docs/dev/conventions.md, docs/plans/TEMPLATE.md and every plan's Status footer. 1. **Extract what survives, per spec.** A contract that several files still depend on moves into a dev doc in present tense before the spec goes. Some destinations already exist (docs/dev/database.md, docs/dev/gitlab-api.md); some have to be written. A destination file existing is not the same as that file carrying the contract, so this step reads the spec against the dev doc rather than checking the dev doc off a list. 1. **Delete the spec and its plans.** `git rm`, plus the index rows in docs/specs/README.md and docs/plans/README.md, replaced by the retired row the definition above requires. 1. **Sweep the Go comments.** Nothing enforces these references, so the sweep is grep-driven: comments naming a spec section (`S12` Base Endpoint), a plan step (`S06 Step 22 decision 5`), a `docs/specs/...md` path, or a bare `S{NN} criterion N` all have to be re-pointed at the dev doc or dropped. Reference counts per spec are in the tables below. 1. **Sweep the markdown.** The `docs:lint` job runs `lychee --offline --include-fragments '**/*.md'`, so any surviving markdown link to a deleted file turns the pipeline red. This includes live specs and plans linking retired ones: at 49d5c5689, 15 files under docs/specs and 18 under docs/plans reference S06. 1. **Handle the ADR references separately.** docs/adr is synced from the handbook and must not be edited in this repo (AGENTS.md guardrail 13), and lychee.toml excludes the directory, so a dangling ADR link fails nothing and misleads every reader. ADR 007 and ADR 008 link the S06 spec, ADR 021 links S09, ADR 025 links S27-A. Each needs a handbook amendment merge request, or an explicit decision to leave the link dangling. 1. **Sweep `.claude/`.** 18 files under `.claude/` cite spec or plan paths, including agent definitions and the planner, spec-author, implement-step, validate-step, and mr-watch skills. Three citations are already dead: mr-watch/SKILL.md names docs/plans/2026-04-15-maven-uploads.md and docs/specs/maven/uploads.md, and monolith-planner/SKILL.md names docs/plans/monolith/2026-06-20-repository-browser.md. None of these files exist. 1. **Sweep the roadmap and the e2e catalogs.** docs/roadmap/closed-beta.md still links the S22 plan that 0d825f90c deleted. docs/testing/ references specs by id. 1. **Decide whether a gate is worth it.** A pre-commit grep or a vale rule could fail a new reference to a retired spec. Recommendation: ship the cleanup without one and see whether the references regrow; this connects to https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/95 on spec/plan drift resolution in `/validate-step`. ## Candidate specs Completion measured at 49d5c5689 under the definitions above. Reference counts are files, not occurrences: Go counts `*.go` files citing the id, md counts markdown files outside docs/specs and docs/plans, and a base id is counted excluding its lettered siblings, so S27's 14 excludes the files that name only S27-A. Eleven specs were completed at that basis, totalling 12,443 lines, and all eleven read as completed off the plan files as they stand today: the rows S04-A, S12 and S16 waited on landed with the correction pass. Two have moved since. S04-C is retired, and S06 joins from [Not candidates yet](#not-candidates-yet), because the rule c2bf2b29c landed settles the zero-plan case its own earlier retirement created. Eleven stand, totalling 12,247 lines. The three batches below order them by what step 2 costs, not by line count. ### Batch 1 — a dev-doc destination is merged | Spec | Lines | Destination | Go | md | | --- | ---: | --- | ---: | ---: | | S06 (storage-layer) | 22 | docs/dev/storage.md | — | — | | S22 (storage-accounting) | 26 | docs/dev/storage-accounting.md | 7 | 11 | | S23 (usage-data-collection) | 302 | docs/dev/usage-data.md | 4 | 5 | | S27-A (periodic-scheduling-foundation) | 742 | docs/dev/background-jobs.md | 3 | 4 | | S04-A (column-level-encryption) | 2,493 | docs/dev/column-encryption.md | 15 | 10 | | S27 (background-jobs-foundation) | 2,972 | docs/dev/background-jobs.md | 14 | 8 | S06 and S22 are already converted to stubs, so their whole cost is the sweep. The other four need step 2 to read the spec against the destination and move whatever the dev doc does not already state; the destination existing is what makes them cheap, not finished. S04-C (column-level-encryption-wiring, 218 lines) was the sixth row here and is retired. It priced the work: one Go file, two markdown files, the extraction into column-encryption.md, and the two index rows, all in one merge request. S22 and S23 are the next two at that scale — 11 Go files and 16 markdown files between them. S06 is deliberately not next: its stub is the smallest file in the issue and its sweep is the largest, at 15 files under docs/specs and 18 under docs/plans on top of the Go comments. ### Batch 2 — a destination covers part of the spec | Spec | Lines | Destination | Go | md | | --- | ---: | --- | ---: | ---: | | S14 (maven-remote) | 623 | docs/dev/remote-read-budgets.md, budgets only | 15 | 6 | | S16 (container-remote) | 1,520 | docs/dev/remote-read-budgets.md, budgets only | 27 | 6 | remote-read-budgets.md scopes itself to three budgets — the manifest fill's response write deadline, the process-wide detached-retention write cap, and the container remote's unbounded upstream fetch burst. The remote read path's own contract has no home, so step 2 either widens that file or writes a remote-read dev doc. ### Batch 3 — no destination yet | Spec | Lines | Destination | Go | md | | --- | ---: | --- | ---: | ---: | | S05-A (cache-abstractions) | 477 | none | 7 | 2 | | S09 (authorization) | 732 | none | 20 | 4 | | S12 (container-oci-hosted) | 2,338 | none | 100 | 12 | S09's extraction is already filed as https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/799, which asks for the authorization seam and management binding contracts under docs/dev; doing that issue is step 2 for S09. S12 is the most expensive and goes last. Three defects are open against its text — https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1190, https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1161 and https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/371 — and they are measured against the spec, so the hosted-OCI dev doc has to carry those contracts before the spec is deleted. The step-based definition above is silent on this, which is deliberate: the ordering is a step-2 obligation on S12, not a completion test. ### Batch 4 — plans whose spec stays At 49d5c5689, 37 Go-service plans were completed, totalling 39,505 lines. At bf703e4b6 it is **38 plans and 44,341 lines**, read straight off the Status tables now that the correction rows have landed and the S04-C plan is gone. A plan is a point-in-time snapshot by definition, so removing one costs no extraction work at all; the spec it implements stays in place. This is the cheapest line-count reduction available and it can run independently of every spec decision above. Three of the original 37 qualified only once the merged MRs were checked rather than the Status table — docs/plans/2026-05-21-blob-storage-attachments-foundation.md at 0/1, docs/plans/2026-09-03-repository-column-writers.md at 4/5, and docs/plans/2026-09-03-s04a-per-format-credential-columns.md at 7/11 — and all three now record every row, so the count above needs no side-reading. docs/plans/2026-04-08-bootstrap-db-tooling.md has no Status table at all and is not in the 38. ## Not candidates yet | Spec | Lines | Why | | --- | ---: | --- | | S33 (gitlab-api) | 299 | docs/plans/2026-08-17-gitlab-api-service-auth.md step 3, the staging-first ops rollout, is unrecorded and has no merged marker. | | S04 (database) | 482 | docs/plans/2026-05-26-database-composition-root.md step 3 is unrecorded, and docs/plans/2026-04-08-bootstrap-db-tooling.md has no Status table to read. | | S01 (http-server-and-routing) | 848 | docs/plans/2026-09-02-debug-pprof-listener.md implements it and neither of its two steps has merged. The same plan holds S03, S03-A and S03-B back. | | S08 (authentication) | — | A stub spec its own text says gets replaced, which makes it a different decision from a completed one. See https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/750. | | S05 (distributed-state), S34 (development-mode) | — | In progress: no plan implements either one. | Still out on open steps: S10, S11, S13, S15, S17, S20-A, S25, S30, S31, S32. Each has at least one implementing plan with a step neither the Status table nor a merged marker accounts for. The monolith specs and plans under docs/specs/monolith and docs/plans/monolith are a follow-on batch, and the beta UI work still lands against those specs. ## What closes this The two definitions are written down where step 1 says, the correction pass has landed so that every plan file states its own completion, Batch 1 and Batch 4 are removed with their references swept, and a decision is recorded per Batch 2 and Batch 3 spec: converted and removed, or explicitly kept with the reason. ## Related - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/95 — formalize spec/plan drift resolution in `/validate-step` - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/799 — document the authorization seam and management binding contracts, which is S09's extraction - https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/1187 — the plans README index is already incomplete - 0d825f90c and dddc6cc7b — the two conversions this strategy generalizes