Merge pull request #313 from flyingrobots/feat/delivery-cycle-governance

Docs/governance cycle landed; next enabling cycle is #312 git-warp audit and upgrade.

Author: flyingrobots

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
 
 ---
 

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
 
 ---
 

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
 

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

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)
 
 ---
 

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