test/docs: add canonical repo fixture builder and review hygiene

AGENTS.md

@@ -32,6 +32,7 @@
 - **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** resolve stale review threads and document false positives before merge
 - **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

CLAUDE.md

@@ -32,6 +32,7 @@
 - **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** resolve stale review threads and document false positives before merge
 - **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

CONTRIBUTING.md

@@ -45,7 +45,9 @@ For substantial work:
 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
+7. open the PR and process review feedback
+8. resolve stale review threads and document false positives before merge
+9. land it, then 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.

README.md

@@ -49,7 +49,9 @@ That means:
 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
+7. open the PR and process review feedback
+8. resolve stale review threads and document false positives before merge
+9. 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).

ROADMAP.md

@@ -100,7 +100,9 @@ Substantial delivery work should follow the repository's canonical cycle from [A
 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
+7. open the PR and process review feedback
+8. resolve stale review threads and document false positives before merge
+9. 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.
 
@@ -109,6 +111,7 @@ The first Hill 1 implementation cycles should explicitly invest in the testing s
 Status:
 
 - in progress
+- prerequisite substrate upgrade merged via issue [#312](https://github.com/flyingrobots/git-mind/issues/312)
 
 Sponsor user:
 
@@ -124,7 +127,6 @@ Goal:
 
 Deliverables:
 
-- git-warp audit / upgrade cycle before major Hill 1 implementation (issue [#312](https://github.com/flyingrobots/git-mind/issues/312))
 - 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
@@ -150,7 +152,7 @@ Primary references:
 - [docs/design/git-warp-upgrade-audit.md](docs/design/git-warp-upgrade-audit.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), [#310](https://github.com/flyingrobots/git-mind/issues/310), [#311](https://github.com/flyingrobots/git-mind/issues/311), and [#312](https://github.com/flyingrobots/git-mind/issues/312)
+- 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

@@ -12,7 +12,7 @@ These describe what Git Mind is now and how work should be judged:
 - [ROADMAP.md](../ROADMAP.md) — active Hills, supporting lanes, and playback cadence
 - [Git Mind Product Frame](./design/git-mind.md) — IBM Design Thinking style product frame
 - [Hill 1 Semantic Bootstrap Spec](./design/h1-semantic-bootstrap.md) — first executable Hill 1 slice
-- [git-warp Upgrade Audit](./design/git-warp-upgrade-audit.md) — next enabling cycle before major Hill 1 implementation
+- [git-warp Upgrade Audit](./design/git-warp-upgrade-audit.md) — completed enabling cycle that revalidated the git-warp substrate before Hill 1 implementation
 - [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
@@ -88,4 +88,5 @@ 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
+4. review-hygiene cleanup for stale threads and false positives before merge
+5. playback evidence and README reality updates before cycle close

docs/adr/ADR-0006.md

@@ -81,6 +81,7 @@ If the shipped behavior changes the user-facing truth of the product, update `RE
 The cycle does not end at "tests green."
 It ends after:
 
+- review feedback is processed and stale or false-positive threads are explicitly resolved
 - 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
@@ -95,8 +96,10 @@ The canonical Git Mind delivery cycle is:
 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.
+7. Open the PR and process review feedback.
+8. Resolve stale review threads and document false positives before merge.
+9. Land the PR to `main`.
+10. Capture post-merge review learnings and follow-on ideas in the backlog.
 
 ## Alternatives Rejected
 

docs/design/git-warp-upgrade-audit.md

@@ -1,6 +1,6 @@
 # git-warp Upgrade Audit
 
-Status: active execution on `feat/git-warp-upgrade-audit`
+Status: completed and merged via PR [#314](https://github.com/flyingrobots/git-mind/pull/314)
 
 Related:
 
@@ -12,7 +12,7 @@ Related:
 
 ## Purpose
 
-Define the next enabling cycle before major Hill 1 implementation:
+Define the enabling cycle that preceded major Hill 1 implementation:
 
 > audit and upgrade Git Mind's `@git-stunts/git-warp` dependency so new Hill 1 work is not built on an outdated substrate by accident.
 

test/context.test.js

@@ -1,10 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { execSync } from 'node:child_process';
 import { initGraph } from '../src/graph.js';
 import { createEdge } from '../src/edges.js';
+import { repoFixture } from './helpers/repo-fixture.js';
 import {
   extractFileContext,
   extractCommitContext,
@@ -14,27 +11,26 @@ import {
 } from '../src/context.js';
 
 describe('context', () => {
+  let repo;
   let tempDir;
   let graph;
 
   beforeEach(async () => {
-    tempDir = await mkdtemp(join(tmpdir(), 'gitmind-test-'));
-    execSync('git init', { cwd: tempDir, stdio: 'ignore' });
-    execSync('git config user.email "test@test.com"', { cwd: tempDir, stdio: 'ignore' });
-    execSync('git config user.name "Test"', { cwd: tempDir, stdio: 'ignore' });
+    repo = await repoFixture('context').build();
+    tempDir = repo.root;
     graph = await initGraph(tempDir);
   });
 
   afterEach(async () => {
-    await rm(tempDir, { recursive: true, force: true });
+    await repo.cleanup();
   });
 
   // ── extractFileContext ──────────────────────────────────────
 
   it('extracts tracked files with inferred languages', async () => {
-    await writeFile(join(tempDir, 'app.js'), 'console.log("hello")');
-    await writeFile(join(tempDir, 'README.md'), '# Hello');
-    execSync('git add app.js README.md && git commit -m "init"', { cwd: tempDir, stdio: 'ignore' });
+    await repo.write('app.js', 'console.log("hello")');
+    await repo.write('README.md', '# Hello');
+    await repo.commit('init');
 
     const files = extractFileContext(tempDir);
 
@@ -54,10 +50,10 @@ describe('context', () => {
   });
 
   it('respects the limit option', async () => {
-    await writeFile(join(tempDir, 'a.js'), '');
-    await writeFile(join(tempDir, 'b.js'), '');
-    await writeFile(join(tempDir, 'c.js'), '');
-    execSync('git add a.js b.js c.js && git commit -m "init"', { cwd: tempDir, stdio: 'ignore' });
+    await repo.write('a.js', '');
+    await repo.write('b.js', '');
+    await repo.write('c.js', '');
+    await repo.commit('init');
 
     const files = extractFileContext(tempDir, { limit: 2 });
     expect(files).toHaveLength(2);
@@ -66,11 +62,11 @@ describe('context', () => {
   // ── extractCommitContext ────────────────────────────────────
 
   it('extracts recent commits with files', async () => {
-    await writeFile(join(tempDir, 'app.js'), 'v1');
-    execSync('git add app.js && git commit -m "feat: initial"', { cwd: tempDir, stdio: 'ignore' });
+    await repo.write('app.js', 'v1');
+    await repo.commit('feat: initial');
 
-    await writeFile(join(tempDir, 'app.js'), 'v2');
-    execSync('git add app.js && git commit -m "fix: update app"', { cwd: tempDir, stdio: 'ignore' });
+    await repo.write('app.js', 'v2');
+    await repo.commit('fix: update app');
 
     const commits = extractCommitContext(tempDir);
 
@@ -170,8 +166,8 @@ describe('context', () => {
   // ── extractContext orchestrator ─────────────────────────────
 
   it('assembles full context with prompt', async () => {
-    await writeFile(join(tempDir, 'app.js'), 'console.log("hi")');
-    execSync('git add app.js && git commit -m "init"', { cwd: tempDir, stdio: 'ignore' });
+    await repo.write('app.js', 'console.log("hi")');
+    await repo.commit('init');
 
     await createEdge(graph, { source: 'file:app.js', target: 'spec:main', type: 'implements' });
     const ctx = await extractContext(tempDir, graph);

test/helpers/repo-bases.js

@@ -0,0 +1,25 @@
+/**
+ * Base repo catalog for repository-shaped tests.
+ */
+
+export function minimalDocsAndCodeBase() {
+  return async repo => {
+    await repo.writeFiles({
+      'README.md': '# Echo Service\n\nSee docs/overview.md and src/app.js.\n',
+      'docs/overview.md': '# Overview\n\nThe service entry point lives in `src/app.js`.\n',
+      'src/app.js': 'export function buildApp() {\n  return { ok: true };\n}\n',
+    });
+    await repo.commit('chore: scaffold minimal docs and code fixture');
+  };
+}
+
+export function adrLinkedServiceBase() {
+  return async repo => {
+    await repo.writeFiles({
+      'README.md': '# Auth Service\n\nSee docs/adr/0001-auth.md for the auth decision.\n',
+      'docs/adr/0001-auth.md': '# ADR 0001: Auth\n\nWe use token-based auth in `src/auth.js`.\n',
+      'src/auth.js': 'export function authenticate(token) {\n  return token === "ok";\n}\n',
+    });
+    await repo.commit('chore: scaffold adr-linked service fixture');
+  };
+}