devrites 3.0.6 → 3.1.0

package/docs/usage.md

@@ -1,10 +1,11 @@
 # Using DevRites
 
-These examples show the common DevRites workflows. A greenfield feature starts
-with `/rite-spec`; an existing codebase may enter through `/rite-adopt`.
-`/rite-quick` and `/rite-frame` handle bounded work outside the full feature arc.
-Workspace-operating phases read the active workspace (`.devrites/ACTIVE` →
-`.devrites/work/<slug>/`) first and report the appropriate on-ramp when none exists.
+These examples cover the common DevRites workflows. Start a new feature with
+`/rite-spec` and bring an existing codebase in with `/rite-adopt`.
+`/rite-quick` and `/rite-frame` handle bounded work outside the full feature
+lifecycle. Workspace phases first read the active workspace from
+`.devrites/ACTIVE` and `.devrites/work/<slug>/`. If none exists, they report the
+command that can create or select one.
 
 - **Full command reference** → [`command-map.md`](command-map.md)
 - **Flow diagrams** → [`flow.md`](flow.md)
@@ -14,15 +15,16 @@ Workspace-operating phases read the active workspace (`.devrites/ACTIVE` →
 ## The workspace
 
 `/rite-spec` creates `.devrites/work/<slug>/` and writes the spec.
-`/rite-define` adds the architecture, plan, tasks, and traceability. Together,
-these human-readable Markdown files carry the work across compaction and new
-sessions:
+`/rite-clarify` adds decision coverage, `/rite-define` adds the plan, and
+`/rite-vet` adds implementation readiness. These human-readable files preserve
+the work across compaction and new sessions:
 
 | File | Created by | Holds |
 |---|---|---|
 | `README.md` / `index.md` / `feature.md` | `/rite-spec` | compact workspace map: phase, status, next action, artifact map, read-next table, gates |
 | `brief.md` | `/rite-spec` | one-line objective + definition of done |
 | `spec.md` | `/rite-spec` | product WHAT/WHY, requirements, acceptance, boundaries, measurable success |
+| `decision-coverage.md` | `/rite-clarify` | topology-first coverage plus semantic `CLEAR` verdict bound to all decision inputs |
 | `architecture.md` | `/rite-define` | owning module/layer, integration points, data/API/events, dependencies, risks |
 | `flows.md` | `/rite-spec` or `/rite-define` | optional Mermaid diagrams when sequence/state/data flow clarifies behavior |
 | `references/` + `references.md` | `/rite-spec` | saved design refs: screenshots, Figma, video, links |
@@ -30,9 +32,11 @@ sessions:
 | `plan.md` | `/rite-define` | approach, dependency graph, checkpoints, rollback |
 | `tasks.md` | `/rite-define` | ordered `SLICE-###` vertical slices, each mapped to `AC-###` and tagged `Mode: AFK \| HITL` + gate fields |
 | `traceability.md` | `/rite-define` | AC/REQ → slices → tests/proofs → evidence → touched files matrix |
-| `eng-review.md` | `/rite-vet` | mandatory engineering plan review, light or full by stakes: scope challenge, axis findings, failure modes, parallelization |
+| `eng-review.md` | `/rite-vet` | mandatory engineering review with semantic, input-digest-bound readiness verdict |
 | `test-plan.md` | `/rite-vet` | build-readable coverage target: coverage diagram, per-gap test requirements, acceptance→test map (read by `/rite-build` + `/rite-prove`) |
-| `state.md` | every phase | working ledger: phase, active slice + slice mode, risk, next step; plus `Awaiting human` block when paused (run mode is derived from `.devrites/AFK`, not stored here) |
+| `state.md` | every phase | working cursor: phase, status, next action, slice, AFK budget, durable clarification return fields, and `Awaiting human` only when paused |
+| `recovery-attempts.jsonl` | technical recovery | durable three-failure budget per root-cause fingerprint |
+| `.wright-allowlist` | `/rite-build` root | exact normalized source/test paths the sole wright may change |
 | `status.md` | every phase | compatibility alias for the canonical `state.md` cursor |
 | `questions.md` | every phase | append-only Q&A: qid, slice, gate, status (`open` / `answered` / `dropped`), proposed answer, raised/answered timestamps |
 | `decisions.md` / `assumptions.md` | every phase | running logs |
@@ -49,14 +53,16 @@ sessions:
 
 When `/rite-ship` closes the task, it archives the whole workspace from
 `.devrites/work/<slug>/` to `.devrites/archive/<slug>/` and clears
-`.devrites/ACTIVE`. It preserves every Markdown file, so the audit trail remains
-under `.devrites/archive/<slug>/`.
+`.devrites/ACTIVE`. Every Markdown file remains in
+`.devrites/archive/<slug>/` as an audit trail.
 
 Backward compatibility: older `.devrites/features/<slug>/` workspaces remain
 readable; migration should add the canonical `.devrites/work` shape without
 deleting the old files. `feature.md`/`index.md` can still act as the workspace
 map, `status.md` as the cursor alias for `state.md`, and `proof.md` as the proof
-alias for `evidence.md`.
+alias for `evidence.md`. Workspace maps use schema v2; migration upgrades
+compatible declarations but never fabricates clarification, readiness, or proof
+evidence.
 
 Project-root sentinel (outside the workspace):
 
@@ -81,6 +87,10 @@ You: I want some kind of reporting thing for admins.
   → gathers any design references you give
   → writes spec.md (creates the workspace)
 
+/rite-clarify
+  → scans the full topology; asks zero questions when the contract is complete
+  → writes fresh Decision coverage: CLEAR
+
 /rite-define
   → reads the approved spec
   → writes plan.md + vertical task slices + state
@@ -95,7 +105,8 @@ You: I want some kind of reporting thing for admins.
 
 ```text
 /rite-spec add-csv-export    # investigate → spec.md
-/rite-define                 # spec → plan + vertical slices + state
+/rite-clarify                # topology scan → Decision coverage: CLEAR
+/rite-define                 # clarified spec → plan + vertical slices + state
 /rite-vet                    # mandatory plan review; light or full based on stakes
 /rite-build                  # slice 1 ("export endpoint returns CSV"); stops with evidence
 /rite-build                  # slice 2 ("download button + states"); repeat for each slice
@@ -106,7 +117,10 @@ You: I want some kind of reporting thing for admins.
 /rite-ship                   # type-GO + irreversible git ladder + close the task (archive + clear ACTIVE)
 ```
 
-`/rite-build` never auto-advances: you decide when the next slice runs.
+`/rite-build` never starts the next slice automatically; you decide when it
+runs. For each slice, the root writes an exact `.wright-allowlist`. The snapshot,
+reconciliation check, test/package integrity, and close steps use the same
+original baseline. A retry snapshot refreshes only the dispatch boundary.
 `/rite-seal` **decides**; `/rite-ship` **executes + closes**. To run the whole
 sequence unattended, see `/rite-autocomplete` (§11).
 
@@ -133,7 +147,7 @@ sequence unattended, see `/rite-autocomplete` (§11).
 You: 2
 
 /rite-plan repair    # updates spec/plan/tasks to per-session, marks drift resolved
-/rite-build          # resumes on the corrected plan
+/rite-vet            # rechecks the repaired plan before build
 ```
 
 ## 4) UI feature with Playwright MCP
@@ -170,14 +184,16 @@ You: 2
 /rite-ship
 ```
 
-If no browser tooling is available, proof is recorded as **pending (manual)**
-with exact steps: the seal then weighs the UI risk.
+If browser tooling is unavailable, the proof records exact manual steps and a
+status of **pending (manual)**. The seal then accounts for the remaining UI
+risk.
 
 ## 5) Backend-only feature
 
 ```text
 /rite-spec rate-limit-api    # investigate → spec.md (no UI)
-/rite-define                 # spec → plan + slices
+/rite-clarify                # topology scan; zero questions when already complete
+/rite-define                 # clarified spec → plan + slices
 /rite-vet                    # mandatory plan review; checks architecture, tests, perf
 /rite-build                  # no UI → no frontend craft / browser proof
 /rite-prove                  # targeted tests + build/typecheck; runtime check of the limiter
@@ -225,7 +241,7 @@ Other modes: `quieter` · `distill` · `harden`.
   → the next session (or a fresh agent) reads the workspace alone
 ```
 
-Run before `/clear` if leaving for > a few hours.
+Run this before `/clear` or a break of more than a few hours.
 
 ## 9) HITL gate: pre-code pause and resume
 
@@ -234,17 +250,17 @@ Run before `/clear` if leaving for > a few hours.
   → reads tasks.md slice 03; Mode: HITL, Gate: blocking
   → STOPS before writing any code:
 
-    SLICE-003: list endpoint is HITL (blocking, SLA 15m).
-    Checkpoint: Composite (user_id, created_at) index, or two single-col indexes?
-    Proposed approach: composite: single read path, both columns used together
-    in the most common filter; downside is rebuild cost on bulk updates.
-    Decision needed before this slice can build.
+    SLICE-003: export policy is HITL (blocking, SLA 15m).
+    Checkpoint: Should deactivated users appear in the admin export?
+    Proposed approach: exclude them by default and expose an explicit
+    include-deactivated filter; this changes visible product behavior.
+    Product decision needed before this slice can build.
     Resume: /rite-resolve q-2026-05-28-001 "<answer>"
 
   → appends q-...-001 to questions.md (status: open, gate: blocking)
   → writes `Awaiting human` block to state.md, sets Status: awaiting_human
 
-You: /rite-resolve q-2026-05-28-001 "composite: single-col is fine for now"
+You: /rite-resolve q-2026-05-28-001 "exclude by default; add the filter"
 
 /rite-resolve
   → flips q-...-001 status → answered (with answered_at + answer)
@@ -288,9 +304,12 @@ EOF
 /rite-build                    # continue
 ```
 
-The loop refuses to mark a slice `built` if tests / types / lint go red: it
-writes a blocking question and stops regardless of `allow_gates`. AFK never
-silently accepts irreversible risk; see
+The loop does not mark a slice `built` while tests, type checks, or lint are
+red. It uses the same wright and durable three-failure recovery budget for each
+root-cause fingerprint. If the budget runs out, it records a blocker with the
+reproduction and unsuccessful approaches instead of asking for retry approval.
+AFK never silently accepts
+genuine product, risk, or access decisions; see
 [`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md) for the
 full list.
 
@@ -298,9 +317,9 @@ full list.
 
 ```text
 /rite-autocomplete "add CSV export for admins" --max-slices 8
-  → vague idea → runs devrites-interview once, up front (the only interactive
-    window), to ~95% confidence
-  → arms AFK, then drives every phase in order: /rite-spec → /rite-temper →
+  → vague idea → runs devrites-interview, then /rite-spec + /rite-clarify in
+    the only interactive window
+  → Decision coverage: CLEAR → arms AFK, then drives: /rite-temper →
     /rite-define → /rite-vet → /rite-build ×N → /rite-prove → /rite-polish →
     /rite-review → /rite-seal (→ /rite-ship too when --ship is set)
   → at each soft gate, picks the option the relevant specialist/reviewer
@@ -311,12 +330,12 @@ full list.
 You: GO                        # → commit · push · tag, then archive + clear ACTIVE
 ```
 
-Add `--ship` (alias `--yolo`) to auto-confirm the final type-`GO` for a
-zero-touch push: autocomplete then proceeds straight to `/rite-ship`. It still
-pauses on hard irreversible-risk (auth / migration / public-API / red tests),
-blocking / escalating gates, an open `gate: validating`, a NO-GO, exhausted
-`max_slices`, or low confidence: writing `state.md` and surfacing *why* before
-it stops. Args: `[idea] [--ship|--yolo] [--max-slices N]`.
+Add `--ship` (alias `--yolo`) to confirm the final type-`GO` automatically.
+Autocomplete then proceeds directly to `/rite-ship` without another prompt. It
+still pauses for genuine product/scope/policy decisions, irreversible risk,
+human-only access/actions, a NO-GO, exhausted `max_slices`, or low confidence.
+Objective red checks use bounded recovery instead. Args:
+`[idea] [--ship|--yolo] [--max-slices N]`.
 
 ## Checking in
 

package/engine/cmd/releasepack/main.go

@@ -0,0 +1,219 @@
+// Command releasepack writes a deterministic tar.gz from a staged release tree.
+package main
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"math"
+	"os"
+	"path"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+type archiveEntry struct {
+	archiveName string
+	sourcePath  string
+	info        os.FileInfo
+}
+
+func main() {
+	root := flag.String("root", "", "staged release tree")
+	output := flag.String("output", "", "output .tar.gz")
+	prefix := flag.String("prefix", "", "archive top-level directory")
+	epochText := flag.String("epoch", "0", "SOURCE_DATE_EPOCH")
+	flag.Parse()
+
+	epoch, err := strconv.ParseUint(*epochText, 10, 32)
+	if err != nil {
+		exitf("invalid epoch %q: %v", *epochText, err)
+	}
+	if *root == "" || *output == "" || *prefix == "" {
+		exitf("-root, -output, and -prefix are required")
+	}
+	if err := writeArchive(*root, *output, *prefix, time.Unix(int64(epoch), 0).UTC()); err != nil {
+		exitf("%v", err)
+	}
+}
+
+func exitf(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, "releasepack: "+format+"\n", args...)
+	os.Exit(1)
+}
+
+func writeArchive(root, output, prefix string, epoch time.Time) error {
+	if err := validatePrefix(prefix); err != nil {
+		return err
+	}
+	if epoch.Unix() < 0 || epoch.Unix() > math.MaxUint32 {
+		return fmt.Errorf("epoch must fit the gzip timestamp field")
+	}
+
+	canonicalRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		return fmt.Errorf("resolve root: %w", err)
+	}
+	canonicalRoot, err = filepath.Abs(canonicalRoot)
+	if err != nil {
+		return fmt.Errorf("resolve root: %w", err)
+	}
+	outputDir, err := filepath.EvalSymlinks(filepath.Dir(output))
+	if err != nil {
+		return fmt.Errorf("resolve output: %w", err)
+	}
+	output, err = filepath.Abs(filepath.Join(outputDir, filepath.Base(output)))
+	if err != nil {
+		return fmt.Errorf("resolve output: %w", err)
+	}
+	if within(canonicalRoot, output) {
+		return errors.New("output must be outside the staged release tree")
+	}
+
+	entries, err := collectEntries(canonicalRoot, prefix)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(output), 0o755); err != nil {
+		return fmt.Errorf("create output directory: %w", err)
+	}
+
+	tmp, err := os.CreateTemp(filepath.Dir(output), "."+filepath.Base(output)+".tmp-*")
+	if err != nil {
+		return fmt.Errorf("create temporary archive: %w", err)
+	}
+	tmpName := tmp.Name()
+	defer os.Remove(tmpName)
+	if err := tmp.Chmod(0o644); err != nil {
+		return errors.Join(fmt.Errorf("set archive mode: %w", err), tmp.Close())
+	}
+
+	gz, err := gzip.NewWriterLevel(tmp, gzip.BestCompression)
+	if err != nil {
+		return errors.Join(fmt.Errorf("create gzip writer: %w", err), tmp.Close())
+	}
+	gz.Header.ModTime = epoch
+	gz.Header.OS = 255
+	tw := tar.NewWriter(gz)
+
+	writeErr := writeEntries(tw, entries, epoch)
+	if err := tw.Close(); writeErr == nil {
+		writeErr = err
+	}
+	if err := gz.Close(); writeErr == nil {
+		writeErr = err
+	}
+	if err := tmp.Close(); writeErr == nil {
+		writeErr = err
+	}
+	if writeErr != nil {
+		return fmt.Errorf("write archive: %w", writeErr)
+	}
+	if err := os.Remove(output); err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("replace output: %w", err)
+	}
+	if err := os.Rename(tmpName, output); err != nil {
+		return fmt.Errorf("publish archive: %w", err)
+	}
+	return nil
+}
+
+func validatePrefix(prefix string) error {
+	if prefix == "" || prefix == "." || path.IsAbs(prefix) || path.Clean(prefix) != prefix || strings.ContainsAny(prefix, `/\`) {
+		return fmt.Errorf("unsafe archive prefix %q", prefix)
+	}
+	return nil
+}
+
+func within(root, candidate string) bool {
+	rel, err := filepath.Rel(root, candidate)
+	return err == nil && (rel == "." || filepath.IsLocal(rel))
+}
+
+func collectEntries(root, prefix string) ([]archiveEntry, error) {
+	var entries []archiveEntry
+	err := filepath.Walk(root, func(sourcePath string, info os.FileInfo, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		if sourcePath == root {
+			entries = append(entries, archiveEntry{archiveName: prefix + "/", sourcePath: root, info: info})
+			return nil
+		}
+		rel, err := filepath.Rel(root, sourcePath)
+		if err != nil || !filepath.IsLocal(rel) {
+			return fmt.Errorf("path escapes staged release tree: %q", sourcePath)
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("symlink is not allowed in release payload: %s", filepath.ToSlash(rel))
+		}
+		if !info.Mode().IsRegular() && !info.IsDir() {
+			return fmt.Errorf("unsupported release payload entry: %s (%s)", filepath.ToSlash(rel), info.Mode())
+		}
+		archiveRel := filepath.ToSlash(rel)
+		if strings.Contains(archiveRel, `\`) {
+			return fmt.Errorf("non-portable release payload path: %s", archiveRel)
+		}
+		name := path.Join(prefix, archiveRel)
+		if info.IsDir() {
+			name += "/"
+		}
+		entries = append(entries, archiveEntry{archiveName: name, sourcePath: sourcePath, info: info})
+		return nil
+	})
+	if err != nil {
+		return nil, fmt.Errorf("collect release payload: %w", err)
+	}
+	sort.Slice(entries, func(i, j int) bool {
+		return entries[i].archiveName < entries[j].archiveName
+	})
+	return entries, nil
+}
+
+func writeEntries(tw *tar.Writer, entries []archiveEntry, epoch time.Time) error {
+	for _, entry := range entries {
+		mode := int64(0o644)
+		typeflag := byte(tar.TypeReg)
+		size := entry.info.Size()
+		if entry.info.IsDir() {
+			mode, typeflag, size = 0o755, tar.TypeDir, 0
+		} else if entry.info.Mode().Perm()&0o111 != 0 || path.Ext(entry.archiveName) == ".sh" {
+			mode = 0o755
+		}
+		header := &tar.Header{
+			Name:       entry.archiveName,
+			Mode:       mode,
+			Size:       size,
+			ModTime:    epoch,
+			AccessTime: epoch,
+			ChangeTime: epoch,
+			Typeflag:   typeflag,
+			Format:     tar.FormatPAX,
+		}
+		if err := tw.WriteHeader(header); err != nil {
+			return err
+		}
+		if typeflag != tar.TypeReg {
+			continue
+		}
+		file, err := os.Open(entry.sourcePath)
+		if err != nil {
+			return err
+		}
+		_, copyErr := io.Copy(tw, file)
+		closeErr := file.Close()
+		if copyErr != nil {
+			return copyErr
+		}
+		if closeErr != nil {
+			return closeErr
+		}
+	}
+	return nil
+}

package/engine/cmd/releasepack/main_test.go

@@ -0,0 +1,170 @@
+package main
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"io"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestWriteArchiveIsDeterministic(t *testing.T) {
+	t.Parallel()
+	epoch := time.Unix(1_700_000_000, 0).UTC()
+	firstRoot := makeTree(t, time.Unix(100, 0))
+	secondRoot := makeTree(t, time.Unix(2_000_000_000, 0))
+	firstArchive := filepath.Join(t.TempDir(), "release.tar.gz")
+	secondArchive := filepath.Join(t.TempDir(), "release.tar.gz")
+
+	if err := writeArchive(firstRoot, firstArchive, "devrites-v1.2.3", epoch); err != nil {
+		t.Fatal(err)
+	}
+	if err := writeArchive(secondRoot, secondArchive, "devrites-v1.2.3", epoch); err != nil {
+		t.Fatal(err)
+	}
+	firstBytes, err := os.ReadFile(firstArchive)
+	if err != nil {
+		t.Fatal(err)
+	}
+	secondBytes, err := os.ReadFile(secondArchive)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(firstBytes, secondBytes) {
+		t.Fatal("archives differ across source roots and mtimes")
+	}
+
+	got := readArchive(t, firstArchive, epoch)
+	wantNames := []string{
+		"devrites-v1.2.3/",
+		"devrites-v1.2.3/README.md",
+		"devrites-v1.2.3/install.sh",
+		"devrites-v1.2.3/nested/",
+		"devrites-v1.2.3/nested/data.txt",
+	}
+	if !reflect.DeepEqual(got.names, wantNames) {
+		t.Fatalf("archive names = %#v, want %#v", got.names, wantNames)
+	}
+	if got.modes["devrites-v1.2.3/"] != 0o755 ||
+		got.modes["devrites-v1.2.3/install.sh"] != 0o755 ||
+		got.modes["devrites-v1.2.3/README.md"] != 0o644 {
+		t.Fatalf("archive modes = %#v", got.modes)
+	}
+	if got.contents["devrites-v1.2.3/install.sh"] != "#!/bin/sh\nexit 0\n" ||
+		got.contents["devrites-v1.2.3/nested/data.txt"] != "payload\n" {
+		t.Fatalf("archive contents = %#v", got.contents)
+	}
+}
+
+func TestWriteArchiveRejectsUnsafePaths(t *testing.T) {
+	t.Parallel()
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "file"), []byte("safe"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	output := filepath.Join(t.TempDir(), "release.tar.gz")
+
+	if err := writeArchive(root, filepath.Join(root, "release.tar.gz"), "devrites-v1", time.Unix(0, 0)); err == nil {
+		t.Fatal("output inside the staged tree was accepted")
+	}
+	if err := writeArchive(root, output, "../escape", time.Unix(0, 0)); err == nil {
+		t.Fatal("escaping archive prefix was accepted")
+	}
+	if err := writeArchive(root, output, `devrites-v1\escape`, time.Unix(0, 0)); err == nil {
+		t.Fatal("non-portable archive prefix was accepted")
+	}
+
+	link := filepath.Join(root, "unsafe-link")
+	if err := os.Symlink(filepath.Join(t.TempDir(), "outside"), link); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	err := writeArchive(root, output, "devrites-v1", time.Unix(0, 0))
+	if err == nil || !strings.Contains(err.Error(), "symlink is not allowed") {
+		t.Fatalf("symlink error = %v", err)
+	}
+	if _, statErr := os.Stat(output); !os.IsNotExist(statErr) {
+		t.Fatalf("unsafe archive output exists: %v", statErr)
+	}
+}
+
+func makeTree(t *testing.T, mtime time.Time) string {
+	t.Helper()
+	root := t.TempDir()
+	files := map[string]struct {
+		content string
+		mode    os.FileMode
+	}{
+		"README.md":       {"read me\n", 0o644},
+		"install.sh":      {"#!/bin/sh\nexit 0\n", 0o644},
+		"nested/data.txt": {"payload\n", 0o644},
+	}
+	for name, file := range files {
+		fullPath := filepath.Join(root, name)
+		if err := os.MkdirAll(filepath.Dir(fullPath), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(fullPath, []byte(file.content), file.mode); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Chtimes(fullPath, mtime, mtime); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return root
+}
+
+type archiveContents struct {
+	names    []string
+	modes    map[string]int64
+	contents map[string]string
+}
+
+func readArchive(t *testing.T, archivePath string, epoch time.Time) archiveContents {
+	t.Helper()
+	file, err := os.Open(archivePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer file.Close()
+	gz, err := gzip.NewReader(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer gz.Close()
+	if !gz.ModTime.Equal(epoch) || gz.OS != 255 || gz.Name != "" || gz.Comment != "" || len(gz.Extra) != 0 {
+		t.Fatalf("gzip header is not normalized: %#v", gz.Header)
+	}
+
+	got := archiveContents{modes: map[string]int64{}, contents: map[string]string{}}
+	tr := tar.NewReader(gz)
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+		got.names = append(got.names, header.Name)
+		got.modes[header.Name] = header.Mode
+		if header.Uid != 0 || header.Gid != 0 || header.Uname != "" || header.Gname != "" {
+			t.Fatalf("%s ownership is not normalized: %#v", header.Name, header)
+		}
+		if !header.ModTime.Equal(epoch) || !header.AccessTime.Equal(epoch) || !header.ChangeTime.Equal(epoch) {
+			t.Fatalf("%s timestamps are not normalized: %#v", header.Name, header)
+		}
+		if header.Typeflag == tar.TypeReg {
+			content, err := io.ReadAll(tr)
+			if err != nil {
+				t.Fatal(err)
+			}
+			got.contents[header.Name] = string(content)
+		}
+	}
+	return got
+}