docs: retire migration/evolution docs; keep the living parity contracts

The project stands on its own now, so the migration-narrative docs no longer earn
their place:

- Delete GO-REWRITE-STATUS.md and RELEASE-CHECKLIST.md (the "how the port is
  going" / "declare parity" storytelling). Their durable substance already lives
  in DIVERGENCES.md, README, and release.yml; releasing is now just "cut a tag".
- Move the two LOAD-BEARING contracts out of docs/migration/ into docs/parity/
  (parity-matrix.yaml, cli-flags-inventory.yaml) — they are ongoing validation
  data the tests read, not migration history. Update the two test paths and the
  README/DIVERGENCES/go-only-features links; the docs/migration/ folder is gone.

Verified: build + parity contract lane + TestFlagInventoryParity green (both
YAMLs load from their new path), no dangling references.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aledbf

README.md

@@ -112,8 +112,9 @@ matrix of ~200 cases runs the *same* command through both CLIs and asserts the
 outputs match (exit code, normalized stdout/stderr, and container/registry state).
 Deliberate divergences (like the Go-only features above) are recorded, not hidden.
 
-If you're evaluating a switch, the parity methodology and current status live in
-[`docs/migration/`](docs/migration/).
+If you're evaluating a switch, the deliberate divergences are documented in
+[`docs/DIVERGENCES.md`](docs/DIVERGENCES.md) and the full case matrix in
+[`docs/parity/parity-matrix.yaml`](docs/parity/parity-matrix.yaml).
 
 ## Contributing / building
 
@@ -134,9 +135,11 @@ task parity:contract  # hermetic contract lane (no Docker)
 task parity:runtime   # full matrix; creates real containers/images via Docker
 ```
 
-- **[`docs/migration/GO-REWRITE-STATUS.md`](docs/migration/GO-REWRITE-STATUS.md)** — parity status.
 - **[`docs/DIVERGENCES.md`](docs/DIVERGENCES.md)** — deliberate divergences, decisions & accepted limitations.
-- **[`docs/migration/parity-matrix.yaml`](docs/migration/parity-matrix.yaml)** — the case matrix.
+- **[`docs/parity/parity-matrix.yaml`](docs/parity/parity-matrix.yaml)** — the case matrix.
+
+Releases are cut by tagging (`YYYYMMDD.NN`); `release.yml` then builds the static
+binaries, SBOMs and the signed multi-arch image.
 
 ```
 cmd/, internal/      the Go CLI implementation

docs/DIVERGENCES.md

@@ -1,7 +1,7 @@
 # Divergences, decisions & accepted limitations
 
 This CLI is validated for behavioral parity with the reference TypeScript
-`@devcontainers/cli` (pinned at **v0.88.0**, see [`migration/`](migration/)). Where it
+`@devcontainers/cli` (pinned at **v0.88.0**, see [`parity/`](parity/)). Where it
 deliberately differs, the difference is recorded here — this is the durable record of
 *intentional* departures from the oracle, not a backlog. User-facing additions are
 documented in [`go-only-features.md`](go-only-features.md).

docs/go-only-features.md

@@ -2,7 +2,7 @@
 
 These commands and flags are **exclusive to this Go CLI** — they are not part of the
 official `@devcontainers/cli`. Everything else mirrors the upstream behavior (see the
-[parity docs](migration/)); the items here are deliberate additions or documented
+[parity docs](parity/)); the items here are deliberate additions or documented
 divergences, each covered by tests.
 
 - [`devcontainer check`](#devcontainer-check) — host preflight

docs/migration/GO-REWRITE-STATUS.md

@@ -13,7 +13,7 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
-// TestFlagInventoryParity validates docs/migration/cli-flags-inventory.yaml against
+// TestFlagInventoryParity validates docs/parity/cli-flags-inventory.yaml against
 // the live Cobra command tree so the inventory cannot silently drift from the code.
 //
 // The Cobra tree is the source of truth: the test walks NewRootCommand().Commands()
@@ -81,7 +81,7 @@ func TestFlagInventoryParity(t *testing.T) {
 
 	// --- load the YAML mirror ------------------------------------------------
 	repoRoot := findRepoRoot(t)
-	yamlPath := filepath.Join(repoRoot, "docs", "migration", "cli-flags-inventory.yaml")
+	yamlPath := filepath.Join(repoRoot, "docs", "parity", "cli-flags-inventory.yaml")
 	data, err := os.ReadFile(yamlPath)
 	if err != nil {
 		t.Fatalf("read inventory: %v", err)

docs/migration/RELEASE-CHECKLIST.md

@@ -190,7 +190,7 @@ func writeParityReport(path string, snapshot map[parityOutcome][]string) error {
 
 func TestParityMatrix(t *testing.T) {
 	repoRoot := findRepoRoot(t)
-	matrixPath := filepath.Join(repoRoot, "docs", "migration", "parity-matrix.yaml")
+	matrixPath := filepath.Join(repoRoot, "docs", "parity", "parity-matrix.yaml")
 
 	data, err := os.ReadFile(matrixPath)
 	if err != nil {