Skip to content

docs: codify delivery cycle and fixture strategy #313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
flyingrobots merged 1 commit into from
Mar 25, 2026
Merged

docs: codify delivery cycle and fixture strategy #313

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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

---

Expand Down
22 changes: 15 additions & 7 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Comment on lines +70 to +75
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for fixture builder implementation or base repo helpers

echo "=== Searching for repo fixture builder/helper implementations ==="
rg -n -C3 'repoFixture|createRepoFixture|RepoBuilder' --type=js

echo ""
echo "=== Searching for base repo definitions ==="
rg -n -C3 'minimalDocsAndCodeBase|withAdrOverlay|withIssueRefOverlay' --type=js

echo ""
echo "=== Count of test files still using mkdtemp pattern ==="
rg -l 'mkdtemp.*git-?mind-test' test/ --type=js | wc -l

Repository: flyingrobots/git-mind

Length of output: 235

Fixture mandate isn't executable—required infrastructure doesn't exist.

Line 71 mandates "shared repo fixtures (base repos + overlays)" but the codebase has zero fixture builders (repoFixture, createRepoFixture, RepoBuilder all absent). Meanwhile, 15 test files still lean on ad hoc mkdtemp + git init anti-patterns. This creates an unresolvable bootstrapping problem: you're asking the team to follow a practice that has no substrate yet. Build the fixture infrastructure (step 1 of Migration Guidance, lines 177–179) and ship it before making this an operational mandate.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 70 - 75, The CLAUDE.md mandate to "Prefer shared repo
fixtures (base repos + overlays)" is unexecutable because the fixture builders
(repoFixture, createRepoFixture, RepoBuilder) don't exist; implement a minimal
fixture infrastructure before enforcing this rule: add a RepoBuilder class with
methods to create base repos and apply overlays, expose helper functions
createRepoFixture and repoFixture that wrap mkdtemp/git init setup and return a
consistent fixture API (create, applyOverlay, cleanup), and update Migration
Guidance step 1 to reference these symbols so tests can switch from ad-hoc
mkdtemp + git init to the new fixtures reliably.


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

---

Expand Down
38 changes: 33 additions & 5 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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`
Comment on lines +74 to +77
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Enforce the feature-branch naming rule in the updated workflow checklist.

This section now formalizes delivery workflow, but it still doesn’t require the documented feat/<topic> branch convention. Please make that explicit here to avoid governance drift between contributor docs and agent instructions.

Based on learnings, “Create a feature branch using git checkout -b feat/<topic> before writing any code.”

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CONTRIBUTING.md` around lines 74 - 77, Add an explicit checklist item
requiring contributors to create a feature branch with the documented naming
convention by inserting a step such as "Create a feature branch using `git
checkout -b feat/<topic>` before writing any code" into the existing workflow
list (near the steps that start "For substantial work..." and "Add or update
failing tests...") so the `feat/<topic>` branch convention is enforced; ensure
the wording matches the repository convention and appears before "Make your
changes" or "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

Expand Down Expand Up @@ -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

Expand Down
20 changes: 20 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
22 changes: 20 additions & 2 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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:
Expand All @@ -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:

Expand All @@ -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)

---

Expand Down
14 changes: 14 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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
Loading
Loading