docs: codify delivery cycle and fixture strategy#313
Merged
flyingrobots merged 1 commit intomainfrom Mar 25, 2026
Merged
Conversation
Contributor
Summary by CodeRabbitRelease Notes
WalkthroughThis PR codifies Git Mind's delivery cycle and repository fixture testing strategy through cross-referenced governance documentation. It establishes a design-to-test workflow requiring acceptance criteria translation into failing tests before implementation, canonical repo fixture usage for repository-shaped testing, and retrospective/README updates before PR landing. Updates span agent operational orders, contributor guidance, canonical planning docs, and new ADR-0006 formalization. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
AGENTS.md (1)
70-75:⚠️ Potential issue | 🟠 MajorDO THE JOB sequence has same fixture dependency as CLAUDE.md.
Line 71 mandates "shared repo fixtures (base repos + overlays)" but current test suite still uses ad hoc patterns (see
test/views.test.js:16-17,test/content.test.js:11-17).Fixture strategy doc's Migration Guidance (lines 177-179) confirms the builder/helpers must be built first. This operational order becomes executable only after Hill 1 delivers the fixture substrate.
The same verification script applies here to confirm fixture infrastructure gap:
#!/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🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 70 - 75, Tests still rely on ad-hoc mkdtemp patterns instead of the shared fixture substrate mandated by AGENTS.md; locate usages like mkdtemp/give-temp-repo patterns in test/views.test.js and test/content.test.js and replace them by wiring in the centralized fixture builders (search for symbols repoFixture, createRepoFixture, RepoBuilder) and base repo definitions (minimalDocsAndCodeBase, withAdrOverlay, withIssueRefOverlay); implement or import the missing fixture builder helper(s) per the Migration Guidance and update tests to call the shared createRepoFixture/repoFixture helpers rather than creating repos inline (also remove mkdtemp 'git-mind-test' usages).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 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.
In `@CONTRIBUTING.md`:
- Around line 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`".
In `@docs/adr/README.md`:
- Around line 126-140: The markdown headings in this file (e.g. "##
[ADR-0006](./ADR-0006.md)", "### What it establishes", "### Why it matters") are
missing required blank lines before and/or after, triggering MD022; add a single
blank line immediately before each heading and ensure there is a blank line
after each heading line (and before the following paragraph or list) so each
heading is separated from surrounding content to satisfy the linter.
---
Duplicate comments:
In `@AGENTS.md`:
- Around line 70-75: Tests still rely on ad-hoc mkdtemp patterns instead of the
shared fixture substrate mandated by AGENTS.md; locate usages like
mkdtemp/give-temp-repo patterns in test/views.test.js and test/content.test.js
and replace them by wiring in the centralized fixture builders (search for
symbols repoFixture, createRepoFixture, RepoBuilder) and base repo definitions
(minimalDocsAndCodeBase, withAdrOverlay, withIssueRefOverlay); implement or
import the missing fixture builder helper(s) per the Migration Guidance and
update tests to call the shared createRepoFixture/repoFixture helpers rather
than creating repos inline (also remove mkdtemp 'git-mind-test' usages).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 05b1aaef-0718-4d75-95d2-ba9f1d907b2a
📒 Files selected for processing (11)
AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.mdROADMAP.mddocs/README.mddocs/adr/ADR-0006.mddocs/adr/README.mddocs/design/git-mind.mddocs/design/h1-semantic-bootstrap.mddocs/design/repo-fixture-strategy.md
Comment on lines
+70
to
+75
| 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 |
Contributor
There was a problem hiding this comment.
🧩 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 -lRepository: 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.
Comment on lines
+74
to
+77
| 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` |
Contributor
There was a problem hiding this comment.
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`".
Comment on lines
+126
to
+140
| ## [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. | ||
|
|
||
| --- |
Contributor
There was a problem hiding this comment.
Fix missing blank lines around headings.
Static analysis correctly flagged MD022 violations. Headings require blank lines before and after for consistent markdown rendering.
📐 Proposed formatting fix
---
+
## [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.
---
+🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 126-126: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 130-130: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 137-137: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/adr/README.md` around lines 126 - 140, The markdown headings in this
file (e.g. "## [ADR-0006](./ADR-0006.md)", "### What it establishes", "### Why
it matters") are missing required blank lines before and/or after, triggering
MD022; add a single blank line immediately before each heading and ensure there
is a blank line after each heading line (and before the following paragraph or
list) so each heading is separated from surrounding content to satisfy the
linter.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Title
docs: codify delivery cycle and fixture strategySummary
Problem Statement
ADR Compliance (Required)
Relevant ADR(s)
Compliance Declaration
Exception Request (Required if deviating)
Architecture Laws Checklist (Hard Gates)
Canonical Truth & Context
--at,--observer,--trust) or deterministically defaulted.Determinism & Provenance
Artifact Hygiene
Contracts & Compatibility
Extension/Effects Safety (if applicable)
Scope Control
Backward Compatibility
Test Plan (Required)
Unit
# docs-only PR; no unit tests added or updatedIntegration
# docs-only PR; no integration tests added or updatedDeterminism
# docs-only PR; no determinism-specific test runContract/Schema
# docs-only PR; no schema/contract files changedPolicy Gates
# enforced by repo hooks and CISecurity / Trust Impact
Performance Impact
Observability / Debuggability
Operational Notes
Linked Issues / Milestones
Reviewer Quick Verdict Block (for maintainers)
MUST (Hard Gates)
SHOULD (Quality)
Verdict