Add canonical repo fixture builder

[flyingrobots]

Summary

• Adds test/helpers/repo-fixture.js, a fluent canonical fixture builder for temporary Git repos.
• Adds named base/overlay recipes for minimal docs+code, ADR references, issue/PR references, noisy files, history, and branch/merge scenarios.
• Adds self-tests proving deterministic commit handles, branch merge topology, chmod/tag/delete operations, cleanup, path safety, and dirty-checkout rejection.
• Documents the implementation location and isolation guardrails in the repo fixture strategy docs.

Problem Statement

• Hill 1 bootstrap tests need believable repository state and history without repeating mkdtemp, git init, identity config, file writes, commits, branches, and merges in every suite.
• The project has accepted ADR-0006, which makes canonical repo fixtures the preferred substrate for repository-shaped behavior.
• Without this helper, upcoming bootstrap slices would either duplicate shell plumbing or hide product intent behind local setup noise.

ADR Compliance (Required)

Relevant ADR(s)

• ADR-0002 (Worktree Independence and Materialization Architecture)
• ADR-0003 (Graph-Native Content, Deterministic Materialization, and Workspace Bridge)
• ADR-0006 (Design Acceptance Becomes Tests, Canonical Repo Fixtures Power Delivery)
• None

Compliance Declaration

• This PR is fully compliant with all checked ADRs.
• This PR intentionally deviates from one or more checked ADRs (complete Exception Request below).

Exception Request (Required if deviating)

• ADR clause(s) deviated from: N/A
• Why deviation is necessary now: N/A
• Risk introduced by deviation: N/A
• Mitigation and rollback plan: Revert this PR; it only adds test helper code and documentation.
• Follow-up ADR/issue to reconcile architecture debt: N/A

---

Architecture Laws Checklist (Hard Gates)

Canonical Truth & Context

• Graph remains canonical truth (no dual truth with generated files).
• No hidden worktree coupling introduced in core/domain/materialization paths.
• Context-sensitive behavior is explicit (--at, --observer, --trust) or deterministically defaulted.
• Resolved context is surfaced in output metadata where applicable.

Determinism & Provenance

• Pure query/materialization paths remain deterministic for identical inputs.
• Mutations/materializations include provenance receipts/envelopes where required.
• Cache keys (if used) are derived only from semantic inputs + pinned versions.

Artifact Hygiene

• No forbidden generated artifact paths are tracked.
• Any generated artifacts intentionally tracked are in allowlisted publish paths only.
• Pre-commit/CI policy checks updated or confirmed valid.

Contracts & Compatibility

• Machine-facing outputs are schema-versioned.
• Breaking contract changes include version bump + migration notes.
• Backward compatibility impact is documented below.

Extension/Effects Safety (if applicable)

• Extension behavior does not bypass capability restrictions.
• Effectful operations use explicit plan/apply semantics and emit receipts.
• Timeouts/resource bounds are defined for new script/effect paths.

---

Scope Control

• PR is single-purpose/cohesive (no unrelated refactors).
• Any non-essential refactor is split into separate PR(s) or explicitly justified.

Backward Compatibility

• CLI/API contract changes: None.
• Data model/storage changes: None.
• Migration required?: No.
• User-facing behavior changes: None. This is test substrate plus docs.

Test Plan (Required)

Unit

• Added/updated tests for changed logic
• Commands:

npx vitest run test/repo-fixture.test.js
npx eslint test/repo-fixture.test.js test/helpers/repo-fixture.js

Integration

• Added/updated integration tests
• Commands:

npm test

Determinism

• Determinism assertions included for relevant paths
• Method: fixture self-tests build identical repos twice and assert stable commit SHAs while preserving distinct temp roots.
• Commands:

npx vitest run test/repo-fixture.test.js

Contract/Schema

• Schema validation updated/passing
• Commands:

npm test

Policy Gates

• Mechanical architecture gates pass
• Commands:

npm run lint
npx vitest run test/design-docs.test.js
git diff --check
npm test

---

Security / Trust Impact

• Threat surface changed?: No production threat surface change. Test helper uses execFileSync('git', args) with argv arrays, not shell strings.
• Trust policy impact: None.
• Provenance/audit impact: Enables future provenance tests with deterministic repo history.
• New failure modes introduced: Fixture builder fails fast on path escapes and branch/merge/checkout operations with uncommitted changes.

Performance Impact

• Hot path affected?: No.
• Expected impact (latency/memory/io): Adds about one second to local test runtime for fixture self-tests.
• Benchmarks or profiling evidence: test/repo-fixture.test.js passed in roughly 1.3 seconds locally; full npm test passed.

Observability / Debuggability

• Errors are actionable and include context.
• Logs/diagnostics added or updated where needed.
• git mind status / diagnostics updated if writeback/eventing behavior changed.

Operational Notes

• Feature flag (if any): None.
• Rollback strategy: Revert commit 18b6362.
• Operational caveats: The builder intentionally isolates temp repos from inherited hook/signing/fsmonitor config to keep tests deterministic. This does not bypass this repository's real commit hooks.

Linked Issues / Milestones

• Closes test: build canonical repo fixture builder with base repos and overlays #311
• Refs test: migrate repo-shaped suites onto the canonical repo fixture builder #316
• Milestone: Hill 1 supporting foundation

---

Reviewer Quick Verdict Block (for maintainers)

MUST (Hard Gates)

•	PASS
•	CONDITIONAL
•	FAIL

SHOULD (Quality)

•	PASS
•	CONDITIONAL
•	FAIL

Verdict

•	APPROVE
•	APPROVE WITH CHANGES
•	REJECT

[coderabbitai]

Warning

Review limit reached

@flyingrobots, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 48 minutes and 30 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1df5eadf-7f93-4827-95dc-dba8eadd1d5e

📥 Commits

Reviewing files that changed from the base of the PR and between 18b98b6 and 18b6362.

📒 Files selected for processing (4)

• docs/design/feature-profiles/repo-fixture-builder.md
• docs/design/repo-fixture-strategy.md
• test/helpers/repo-fixture.js
• test/repo-fixture.test.js

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 18b63626d6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Scrub inherited Git env for fixture commands

When tests are launched from a Git hook or any wrapper that exports GIT_DIR, GIT_WORK_TREE, GIT_INDEX_FILE, etc., this env spread makes every fixture git command ignore the temp cwd and operate against the inherited repository/index instead. In that context the new canonical builder can fail with “no changes” or, worse, mutate the caller’s repo rather than the fixture; clear Git-specific environment variables before merging opts.env so fixture repos are actually isolated.

Useful? React with 👍 / 👎.