diff --git a/AGENTS.md b/AGENTS.md
index b01b744..ac14e9e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,6 +6,8 @@
 - Documentation map and canonical docs: [docs/README.md](docs/README.md)
 - Product frame: [docs/design/git-mind.md](docs/design/git-mind.md)
 - Planning governance: [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
+- Delivery governance: [docs/adr/ADR-0006.md](docs/adr/ADR-0006.md)
+- Repo fixture strategy: [docs/design/repo-fixture-strategy.md](docs/design/repo-fixture-strategy.md)
 - CLI/user reference: [GUIDE.md](GUIDE.md)
 
 ## FORBIDDEN ACTIONS
@@ -28,6 +30,8 @@
 - **YOU MUST** use IBM Design Thinking when framing substantial product work
 - **YOU MUST** identify the sponsor user, job to be done, and relevant Hill(s) when planning
 - **YOU MUST** use Playbacks to judge whether work actually moved a Hill
+- **YOU MUST** treat tests as the executable form of design acceptance criteria for substantial work
+- **YOU MUST** prefer canonical repo fixtures over ad hoc temp-repo setup when testing repository-shaped behavior
 - **YOU MUST** tag all memories saved to your memory banks with at least `#git-mind`
 - **YOU MUST** include the POSIX timestamp (via `$(date +%s)`) in memory file names
 - **YOU MUST** document significant decisions or events
@@ -63,19 +67,23 @@
 ### 2.2. DO THE JOB
 
 1. Green the builds, green the tests
-2. Drop micro-commits as you complete steps — always use conventional commit format
-3. Drop a SITREP if you hit a snag or need input
-4. Drop a DEVLOG for ideas, observations, or anything you want to remember
-5. Use your memory banks freely
+2. Translate design acceptance criteria into failing tests before implementation when behavior is changing substantially
+3. Prefer shared repo fixtures (base repos + overlays) where repository history or artifact shape matters
+4. Drop micro-commits as you complete steps — always use conventional commit format
+5. Drop a SITREP if you hit a snag or need input
+6. Drop a DEVLOG for ideas, observations, or anything you want to remember
+7. Use your memory banks freely
 
 > **ALWAYS** overwrite files, **NEVER** create secondary copies — that creates confusion and tech debt.
 
 ### 2.3. FINISH THE JOB
 
 1. Green the builds, green the tests
-2. Git commit (do NOT use `git add -A`)
-3. Ask the user if they want you to push and open a PR
-4. Drop a SITREP as you finish
+2. Run a playback / retrospective and capture backlog items or COOL IDEAS explicitly
+3. Update `README.md` if shipped reality changed
+4. Git commit (do NOT use `git add -A`)
+5. Ask the user if they want you to push and open a PR
+6. Drop a SITREP as you finish
 
 ---
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 326939e..f603db0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,8 @@
 - Documentation map and canonical docs: [docs/README.md](docs/README.md)
 - Product frame: [docs/design/git-mind.md](docs/design/git-mind.md)
 - Planning governance: [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
+- Delivery governance: [docs/adr/ADR-0006.md](docs/adr/ADR-0006.md)
+- Repo fixture strategy: [docs/design/repo-fixture-strategy.md](docs/design/repo-fixture-strategy.md)
 - CLI/user reference: [GUIDE.md](GUIDE.md)
 
 ## FORBIDDEN ACTIONS
@@ -28,6 +30,8 @@
 - **YOU MUST** use IBM Design Thinking when framing substantial product work
 - **YOU MUST** identify the sponsor user, job to be done, and relevant Hill(s) when planning
 - **YOU MUST** use Playbacks to judge whether work actually moved a Hill
+- **YOU MUST** treat tests as the executable form of design acceptance criteria for substantial work
+- **YOU MUST** prefer canonical repo fixtures over ad hoc temp-repo setup when testing repository-shaped behavior
 - **YOU MUST** tag all memories saved to your memory banks with at least `#git-mind`
 - **YOU MUST** include the POSIX timestamp (via `$(date +%s)`) in memory file names
 - **YOU MUST** document significant decisions or events
@@ -63,19 +67,23 @@
 ### 2.2. DO THE JOB
 
 1. Green the builds, green the tests
-2. Drop micro-commits as you complete steps — always use conventional commit format
-3. Drop a SITREP if you hit a snag or need input
-4. Drop a DEVLOG for ideas, observations, or anything you want to remember
-5. Use your memory banks freely
+2. Translate design acceptance criteria into failing tests before implementation when behavior is changing substantially
+3. Prefer shared repo fixtures (base repos + overlays) where repository history or artifact shape matters
+4. Drop micro-commits as you complete steps — always use conventional commit format
+5. Drop a SITREP if you hit a snag or need input
+6. Drop a DEVLOG for ideas, observations, or anything you want to remember
+7. Use your memory banks freely
 
 > **ALWAYS** overwrite files, **NEVER** create secondary copies — that creates confusion and tech debt.
 
 ### 2.3. FINISH THE JOB
 
 1. Green the builds, green the tests
-2. Git commit (do NOT use `git add -A`)
-3. Ask the user if they want you to push and open a PR
-4. Drop a SITREP as you finish
+2. Run a playback / retrospective and capture backlog items or COOL IDEAS explicitly
+3. Update `README.md` if shipped reality changed
+4. Git commit (do NOT use `git add -A`)
+5. Ask the user if they want you to push and open a PR
+6. Drop a SITREP as you finish
 
 ---
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d427732..c360f3e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -31,6 +31,24 @@ Canonical planning references:
 - [docs/design/git-mind.md](docs/design/git-mind.md)
 - [ROADMAP.md](ROADMAP.md)
 - [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
+- [docs/adr/ADR-0006.md](docs/adr/ADR-0006.md)
+
+## Delivery Cycle
+
+Git Mind uses a design-to-test delivery cycle.
+
+For substantial work:
+
+1. write or update the relevant design artifact
+2. make the acceptance criteria explicit
+3. translate those acceptance criteria into failing tests
+4. implement until the tests are green
+5. run a playback / retrospective and capture backlog follow-ups
+6. update [README.md](README.md) if user-facing reality changed
+7. open the PR, land it, and capture review-cycle learnings back into the backlog
+
+This is not just for happy paths.
+Tests should cover edge cases, failure modes, and fuzz/stress behavior when the design risk justifies it.
 
 GitHub issues are the execution backlog.
 GitHub milestones are not the primary planning surface for this repository.
@@ -53,16 +71,18 @@ npm test
 ## Making changes
 
 1. Create a branch from `main` (or the current development branch)
-2. Make your changes
-3. Run the tests: `npm test`
-4. Commit using [Conventional Commits](https://www.conventionalcommits.org/):
+2. For substantial work, start from a design artifact and acceptance criteria
+3. Add or update failing tests before implementation when behavior is changing
+4. Make your changes
+5. Run the tests: `npm test`
+6. Commit using [Conventional Commits](https://www.conventionalcommits.org/):
    - `feat:` — new feature
    - `fix:` — bug fix
    - `docs:` — documentation only
    - `chore:` — maintenance, tooling
    - `refactor:` — code change that neither fixes a bug nor adds a feature
    - `test:` — adding or updating tests
-5. Open a pull request
+7. Open a pull request
 
 ## Commit messages
 
@@ -94,7 +114,15 @@ npm test          # single run
 npm run test:watch  # watch mode
 ```
 
-Each test creates a temporary Git repo in the OS temp directory and cleans up after itself.
+Testing doctrine:
+
+- tests are the executable form of design acceptance criteria
+- cover golden paths, edge cases, failure cases, and fuzz/stress behavior where warranted
+- prefer repository-shaped fixtures for repository-shaped behavior
+- avoid copying `mkdtemp + git init + config` boilerplate across suites when a shared fixture helper would do better
+
+Canonical fixture guidance lives in [docs/design/repo-fixture-strategy.md](docs/design/repo-fixture-strategy.md).
+The intended direction is a fluent repo builder with reusable base repos and scenario overlays.
 
 ## Project structure
 
diff --git a/README.md b/README.md
index 9ae6e72..9005376 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,24 @@ Canonical planning sources:
 - [docs/design/git-mind.md](docs/design/git-mind.md)
 - [ROADMAP.md](ROADMAP.md)
 - [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
+- [docs/adr/ADR-0006.md](docs/adr/ADR-0006.md)
+
+## Delivery Cycle
+
+Git Mind officially uses a design-to-test cycle.
+
+That means:
+
+1. frame the work in a design artifact using sponsor user, job to be done, Hill, and acceptance criteria
+2. translate those acceptance criteria into failing tests
+3. cover not only the golden path, but also edge cases, failure modes, and fuzz/stress when warranted
+4. implement until the tests are green
+5. run a playback / retrospective and capture backlog items and follow-on ideas explicitly
+6. update `README.md` if product reality changed
+7. land the PR, then capture review-cycle learnings back into the backlog
+
+For repository-shaped behavior, prefer canonical repo fixtures over one-off temporary repo setup.
+See [docs/design/repo-fixture-strategy.md](docs/design/repo-fixture-strategy.md) and [docs/adr/ADR-0006.md](docs/adr/ADR-0006.md).
 
 ## What Git Mind Is For
 
@@ -154,8 +172,10 @@ Canonical docs:
 - [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md)
 - [ROADMAP.md](ROADMAP.md)
 - [docs/adr/ADR-0005.md](docs/adr/ADR-0005.md)
+- [docs/adr/ADR-0006.md](docs/adr/ADR-0006.md)
 - [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md)
 - [docs/design/git-mind.md](docs/design/git-mind.md)
+- [docs/design/repo-fixture-strategy.md](docs/design/repo-fixture-strategy.md)
 - [docs/adr/](docs/adr/)
 
 ## License
diff --git a/ROADMAP.md b/ROADMAP.md
index 7752986..bc2a7bc 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -50,6 +50,7 @@ Git Mind now uses:
 - IBM Hills to define the strategic outcomes
 - Playbacks to assess whether recent work actually moved a Hill
 - GitHub issues to track concrete implementation work
+- the design-to-test delivery cycle in [ADR-0006](docs/adr/ADR-0006.md) to move work from design acceptance criteria into implementation
 
 This is not an informal preference.
 It is the repository's official planning model per [ADR-0005](docs/adr/ADR-0005.md).
@@ -89,6 +90,20 @@ Before significant work is accepted into an active Hill or supporting lane, we s
 
 If those answers are fuzzy, the work is not ready for planning commitment yet.
 
+## Execution Cycle
+
+Substantial delivery work should follow the repository's canonical cycle from [ADR-0006](docs/adr/ADR-0006.md):
+
+1. write or revise the design artifact
+2. turn acceptance criteria into failing tests
+3. use canonical repo fixtures where repository-shaped behavior is under test
+4. implement until the tests are green
+5. run a playback / retrospective
+6. update `README.md` if shipped reality changed
+7. land the PR and capture review learnings back into the backlog
+
+The first Hill 1 implementation cycles should explicitly invest in the testing substrate needed to make bootstrap behavior executable and trustworthy.
+
 ## Current Focus: Hill 1 Semantic Bootstrap
 
 Status:
@@ -110,12 +125,14 @@ Goal:
 Deliverables:
 
 - bootstrap command contract with default write behavior and `--dry-run`
+- canonical repo fixture substrate for repository-shaped bootstrap scenarios (issue [#311](https://github.com/flyingrobots/git-mind/issues/311))
 - repo-local artifact inventory and scan boundaries
 - first-pass entity extraction for files, docs, ADRs, modules, commits, and repo-local issue/PR references
 - first-pass relationship inference for `documents`, `references`, `touches`, `groups`, and conservative `implements`
 - provenance and confidence surfacing for inferred assertions
 - a reviewable follow-up path for weak-confidence bootstrap output
-- implementation issues `#304` through `#307` moved into merged runnable behavior
+- acceptance criteria translated into failing executable tests (issue [#310](https://github.com/flyingrobots/git-mind/issues/310))
+- implementation issues `#304` through `#307`, plus enabling test issues [#310](https://github.com/flyingrobots/git-mind/issues/310) and [#311](https://github.com/flyingrobots/git-mind/issues/311), moved into merged runnable behavior
 
 Exit criteria:
 
@@ -129,8 +146,9 @@ Primary references:
 
 - [docs/design/git-mind.md](docs/design/git-mind.md)
 - [docs/design/h1-semantic-bootstrap.md](docs/design/h1-semantic-bootstrap.md)
+- [docs/design/repo-fixture-strategy.md](docs/design/repo-fixture-strategy.md)
 - issue [#303](https://github.com/flyingrobots/git-mind/issues/303)
-- issues [#304](https://github.com/flyingrobots/git-mind/issues/304), [#305](https://github.com/flyingrobots/git-mind/issues/305), [#306](https://github.com/flyingrobots/git-mind/issues/306), [#307](https://github.com/flyingrobots/git-mind/issues/307)
+- issues [#304](https://github.com/flyingrobots/git-mind/issues/304), [#305](https://github.com/flyingrobots/git-mind/issues/305), [#306](https://github.com/flyingrobots/git-mind/issues/306), [#307](https://github.com/flyingrobots/git-mind/issues/307), [#310](https://github.com/flyingrobots/git-mind/issues/310), and [#311](https://github.com/flyingrobots/git-mind/issues/311)
 
 ---
 
diff --git a/docs/README.md b/docs/README.md
index 1a6ed46..bac1d45 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,7 @@ These describe what Git Mind is now and how work should be judged:
 - [Hill 1 Semantic Bootstrap Spec](./design/h1-semantic-bootstrap.md) — first executable Hill 1 slice
 - [Git Mind North Star](./VISION_NORTH_STAR.md) — longer-form strategic articulation
 - [ADR-0005](./adr/ADR-0005.md) — official planning and governance model
+- [ADR-0006](./adr/ADR-0006.md) — official delivery cycle and tests-as-spec model
 
 ## Canonical Engineering Guardrails
 
@@ -22,6 +23,7 @@ These define constraints and contracts that remain in force:
 - [GRAPH_SCHEMA.md](../GRAPH_SCHEMA.md) — graph contract
 - [Architecture Laws](./ARCHITECTURE.md) — non-negotiable engineering laws
 - [Review Rubric](./REVIEW_RUBRIC.md) — architectural review gates
+- [Repo Fixture Strategy](./design/repo-fixture-strategy.md) — canonical repository-shaped test substrate strategy
 - [ADRs](./adr/README.md) — durable architecture decisions
 - [Contracts](./contracts/CLI_CONTRACTS.md) and related schemas — machine-facing contracts
 
@@ -62,6 +64,11 @@ Hills and Playbacks live in:
 - [Git Mind Product Frame](./design/git-mind.md)
 - [ADR-0005](./adr/ADR-0005.md)
 
+The execution cycle and tests-as-spec rules live in:
+
+- [ADR-0006](./adr/ADR-0006.md)
+- [Repo Fixture Strategy](./design/repo-fixture-strategy.md)
+
 GitHub milestones are not the primary planning system for this repository.
 
 ## Contributor Rule
@@ -74,3 +81,10 @@ When planning work, start with:
 4. playback evidence
 
 Do not start with architecture breadth, an old milestone, or a flat pile of backlog items.
+
+When implementing substantial work, continue with:
+
+1. explicit acceptance criteria
+2. failing tests
+3. shared repo fixtures where repository behavior matters
+4. playback evidence and README reality updates before cycle close
diff --git a/docs/adr/ADR-0006.md b/docs/adr/ADR-0006.md
new file mode 100644
index 0000000..f24cb84
--- /dev/null
+++ b/docs/adr/ADR-0006.md
@@ -0,0 +1,147 @@
+# ADR-0006: Design Acceptance Becomes Tests, Canonical Repo Fixtures Power Delivery
+
+- **Status:** Accepted
+- **Date:** 2026-03-25
+- **Deciders:** Git Mind maintainers
+- **Related:** [ADR-0005](./ADR-0005.md), [ROADMAP.md](../../ROADMAP.md), [Git Mind Product Frame](../design/git-mind.md), [Repo Fixture Strategy](../design/repo-fixture-strategy.md), issue #309
+
+## Context
+
+Git Mind now has a clearer product frame and a concrete Hill 1 execution target.
+What it does not yet have is an equally explicit delivery model for how work should move from design into implementation.
+
+Without that delivery model, the repository is vulnerable to familiar failure modes:
+
+- design intent living only in prose
+- implementation drifting ahead of acceptance criteria
+- tests proving only happy paths instead of the real design boundary
+- repeated ad hoc temporary-repo setup scattered across suites
+- playback and backlog updates happening informally instead of as part of the cycle
+- README and high-visibility docs lagging behind the actual shipped behavior
+
+Git Mind's product promise is inherently repository-shaped.
+That means both implementation and testing need to operate on realistic Git repositories with believable artifacts and history, not only on isolated functions or loose files.
+
+## Decision
+
+Git Mind adopts a **design-to-test delivery cycle**.
+
+### 1. Design documents define acceptance criteria first
+
+Substantial work starts from a canonical design artifact framed in IBM Design Thinking terms:
+
+- sponsor user
+- job to be done
+- relevant Hill(s) or supporting lane
+- playback evidence
+- explicit acceptance criteria
+
+### 2. Tests are the spec
+
+Before implementation is considered complete, the acceptance criteria from the design artifact should be translated into failing tests in the repository.
+
+Those tests should cover, where appropriate:
+
+- golden-path behavior
+- edge cases
+- failure cases
+- regression cases
+- fuzz or stress behavior when the risk profile justifies it
+
+Implementation should then continue until those tests pass.
+
+### 3. Canonical repo fixtures are the preferred testing substrate
+
+For repository-shaped behavior, Git Mind should prefer a shared fixture-repo system over repeated one-off `mkdtemp + git init` setup.
+
+That fixture system should center on:
+
+- a fluent repo builder
+- reusable base repositories
+- scenario overlays that add commits, branches, references, or other history/state
+- archived repo snapshots only when exact Git object state or topology must be preserved
+
+The canonical strategy for that substrate lives in `docs/design/repo-fixture-strategy.md`.
+
+### 4. Playbacks and retrospectives close the implementation loop
+
+Once implementation tests are green, maintainers should do a playback/retrospective that asks:
+
+- did this work actually move the intended Hill?
+- did the implementation satisfy the design acceptance criteria?
+- what should be added to the backlog?
+- what new ideas should be captured for later instead of smuggled into the current cycle?
+
+### 5. README reality should be updated before cycle close
+
+If the shipped behavior changes the user-facing truth of the product, update `README.md` before the cycle is considered closed.
+
+### 6. PR and post-merge learning are part of the cycle
+
+The cycle does not end at "tests green."
+It ends after:
+
+- the PR is reviewed and merged to `main`
+- learnings from review are captured back into the backlog
+- any follow-on ideas are explicitly recorded instead of left implicit
+
+## Required Delivery Cycle
+
+The canonical Git Mind delivery cycle is:
+
+1. Write or revise the design artifact using IBM Design Thinking framing.
+2. Translate design acceptance criteria into failing tests.
+3. Use canonical repo fixtures when repository-shaped behavior is under test.
+4. Implement until the tests are green.
+5. Run the playback / retrospective.
+6. Update the README if product reality changed.
+7. Open and land the PR to `main`.
+8. Capture post-merge review learnings and follow-on ideas in the backlog.
+
+## Alternatives Rejected
+
+### 1. Design docs without executable acceptance criteria
+
+Rejected because they make it too easy for implementation to drift while still sounding aligned.
+
+### 2. Tests as a post-hoc verification layer
+
+Rejected because it encourages design and implementation to converge only after code already exists.
+
+### 3. One-off temporary repos in each suite forever
+
+Rejected because the codebase already shows repeated setup boilerplate, which will get worse as Hill 1 introduces more repository-shaped scenarios.
+
+### 4. Golden-path-only testing
+
+Rejected because Git Mind's value depends on trust, provenance, and behavior under messy repository conditions, not only happy-path demos.
+
+## Consequences
+
+### Positive
+
+- Design intent becomes executable.
+- Hill progress becomes easier to audit.
+- Tests become a stronger contract boundary for humans and agents.
+- Repository-shaped features get a shared, realistic testing substrate.
+- Retrospectives become part of the standard work loop instead of an optional add-on.
+
+### Costs
+
+- Early cycles will spend deliberate effort on fixture and test harness setup.
+- Contributors need more discipline before they get to implementation code.
+- Some "quick" changes will slow down because they now need explicit acceptance translation.
+
+## Enforcement
+
+This ADR should be reflected in:
+
+- `README.md`
+- `ROADMAP.md`
+- `CONTRIBUTING.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `docs/README.md`
+- `docs/design/repo-fixture-strategy.md`
+
+If those documents drift away from this cycle model, they should be corrected.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 2cd5fcb..002ef3e 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -123,6 +123,22 @@ Prevents Git Mind from drifting back into milestone theater, architecture-first
 
 ---
 
+## [ADR-0006](./ADR-0006.md) — Design Acceptance Becomes Tests, Canonical Repo Fixtures Power Delivery
+**Status:** Accepted
+**Date:** 2026-03-25
+
+### What it establishes
+- substantial work follows a design-to-test delivery cycle
+- design acceptance criteria should be translated into failing tests
+- tests are expected to cover more than golden paths when risk justifies it
+- canonical repository-shaped fixtures should replace growing ad hoc temp-repo boilerplate
+- playback, README reality updates, and post-merge backlog capture are part of cycle close
+
+### Why it matters
+Turns IBM Design Thinking from planning discipline into an executable delivery model, and gives Git Mind a realistic test substrate for repository-shaped behavior.
+
+---
+
 ## Quick Contribution Rules
 
 - Keep ADRs concise but specific.
diff --git a/docs/design/git-mind.md b/docs/design/git-mind.md
index 651f02e..f037818 100644
--- a/docs/design/git-mind.md
+++ b/docs/design/git-mind.md
@@ -4,6 +4,7 @@ Status: canonical product frame
 
 This document is the canonical IBM Design Thinking product frame for Git Mind.
 Planning governance is defined in [ADR-0005](../adr/ADR-0005.md).
+Delivery governance is defined in [ADR-0006](../adr/ADR-0006.md).
 
 ## Purpose
 
diff --git a/docs/design/h1-semantic-bootstrap.md b/docs/design/h1-semantic-bootstrap.md
index 1e06f53..ebf8df1 100644
--- a/docs/design/h1-semantic-bootstrap.md
+++ b/docs/design/h1-semantic-bootstrap.md
@@ -7,6 +7,7 @@ Related:
 - [Git Mind Product Frame](./git-mind.md)
 - [ROADMAP.md](../../ROADMAP.md)
 - [ADR-0005](../adr/ADR-0005.md)
+- [ADR-0006](../adr/ADR-0006.md)
 - issue [#303](https://github.com/flyingrobots/git-mind/issues/303)
 
 ## Purpose
@@ -34,6 +35,12 @@ The first slice succeeds if, on a representative unfamiliar repository:
 3. The user can answer a few repository-understanding questions faster than they could with filenames, grep, and commit browsing alone.
 4. The system is obviously incomplete, but already worth using.
 
+## Execution Note
+
+Per [ADR-0006](../adr/ADR-0006.md), the acceptance criteria in this spec should be translated into failing tests before Hill 1 implementation is considered complete.
+
+Those tests should cover not only the happy path, but also edge cases, failure cases, and repository-shaped scenarios that need canonical fixture repos to exercise meaningfully.
+
 ## First-Slice Scope
 
 This first slice is intentionally narrow.
diff --git a/docs/design/repo-fixture-strategy.md b/docs/design/repo-fixture-strategy.md
new file mode 100644
index 0000000..0ff8b29
--- /dev/null
+++ b/docs/design/repo-fixture-strategy.md
@@ -0,0 +1,196 @@
+# Repo Fixture Strategy
+
+Status: canonical engineering test strategy
+
+Related:
+
+- [ADR-0006](../adr/ADR-0006.md)
+- [ADR-0005](../adr/ADR-0005.md)
+- [Hill 1 Semantic Bootstrap Spec](./h1-semantic-bootstrap.md)
+- issue [#309](https://github.com/flyingrobots/git-mind/issues/309)
+
+## Purpose
+
+Git Mind needs canonical repository-shaped test fixtures.
+
+The product now aims to infer meaning from:
+
+- file trees
+- source files
+- Markdown docs
+- ADRs
+- repo-local issue / PR / commit references
+- commit history
+- branches and merges over time
+
+That means the test substrate should be **repositories with believable state and history**, not only loose files or ad hoc temp directories.
+
+## Core Principles
+
+1. Tests are the spec.
+   - Fixture repos exist to make design acceptance criteria executable.
+
+2. Prefer readable construction over opaque archives.
+   - A contributor should be able to understand why a fixture exists and what shape it has.
+
+3. Prefer reusable repo shapes over one-off setup boilerplate.
+   - Repeated `mkdtemp + git init + config + write + commit` logic should converge into shared helpers.
+
+4. Preserve realistic Git behavior where it matters.
+   - Branches, merges, and commit history are part of the product surface.
+
+5. Freeze exact Git object state only when necessary.
+   - Archived fixture repos are a last resort, not the default pattern.
+
+## Canonical Model
+
+Git Mind fixture repos should use three layers:
+
+### 1. Fluent repo builder
+
+A shared helper should create and mutate temporary Git repos for tests.
+
+Expected responsibilities:
+
+- create temporary repos
+- initialize Git
+- configure test identity
+- write, update, and delete files
+- create commits with controlled messages
+- create branches and merges
+- expose useful handles for paths, refs, and repo root
+
+### 2. Base repos
+
+Base repos define a stable semantic starting point.
+
+Examples:
+
+- minimal docs + code repo
+- ADR-driven service repo
+- module-heavy repo
+- intentionally noisy repo
+
+Base repos answer:
+
+- what repository shape are we testing?
+
+### 3. Scenario overlays
+
+Scenario overlays add state or evolution to a base repo.
+
+Examples:
+
+- add ADR references
+- add issue / PR references
+- add recent commit history
+- add a feature branch and merge
+- add ambiguous or low-confidence signals
+
+Overlays answer:
+
+- what happened to this repo?
+- what additional evidence or ambiguity do we want to test?
+
+## Preferred API Shape
+
+The exact implementation can evolve, but the intended model is:
+
+```js
+const repo = await repoFixture()
+  .base(minimalDocsAndCodeBase())
+  .overlay(withAdrOverlay())
+  .overlay(withIssueRefOverlay())
+  .overlay(withFeatureBranchOverlay())
+  .build();
+```
+
+Or, for smaller cases:
+
+```js
+const repo = await createRepoFixture('minimal-service')
+  .withFile('README.md', '# Echo Service')
+  .withFile('src/auth.js', 'export function auth() {}')
+  .commit('feat: add auth module')
+  .applyOverlay(withAdrOverlay())
+  .build();
+```
+
+The point is not the exact method names.
+The point is:
+
+- readable setup
+- reusable repo shapes
+- composable history/state overlays
+
+## Archived Repo Snapshots
+
+Tarballs or archived repos are allowed when:
+
+- exact `.git` object state matters
+- merge topology must be preserved exactly
+- performance or regression fixtures should be frozen
+- recreating the scenario programmatically would be too brittle or too expensive
+
+They should not be the default for routine tests.
+
+Default rule:
+
+- builder first
+- archive only when exact historical state is the thing under test
+
+## Initial Canonical Scenario Set
+
+The first useful fixture catalog should likely include:
+
+1. `minimal-doc-code`
+   - a source file, README, one supporting doc, simple commit history
+
+2. `adr-linked-service`
+   - ADRs that explicitly point at modules or files
+
+3. `history-shaped`
+   - recent commits and references that support provenance testing
+
+4. `branching-evolution`
+   - a feature branch and merge for history-sensitive cases
+
+5. `noisy-repo`
+   - ambiguous references and weak signals for low-confidence behavior
+
+## Test Expectations
+
+When writing tests against this substrate:
+
+- start from design acceptance criteria
+- cover golden paths
+- add negative and edge cases
+- add fuzz or stress tests when the design risk justifies them
+- name fixtures for the repository story they represent
+- keep fixture intent obvious from the test body
+
+## Migration Guidance
+
+The existing suite already contains many temporary Git repo setups.
+We do not need to rewrite all of them at once.
+
+Recommended path:
+
+1. build the shared repo fixture helper
+2. add the first base repos and overlays
+3. use them for new Hill 1 work first
+4. gradually migrate older suites when they are touched
+
+## Why This Matters For Hill 1
+
+Hill 1 is about low-input semantic bootstrap on an unfamiliar repository.
+
+That is a repository-shaped promise.
+
+If our tests only exercise isolated helpers or handwritten one-off temp dirs, we will miss:
+
+- artifact classification drift
+- provenance blind spots
+- history-sensitive edge cases
+- ambiguous signal handling
+- the real user experience of "point it at a repo and see what it finds"