Add bootstrap command contract

[flyingrobots]

Summary

• Adds the first executable git mind bootstrap CLI contract.
• Publishes bootstrap.schema.json and validates dry-run JSON output through contract canaries.
• Adds a pure bootstrap summary builder plus human terminal formatting.
• Guards bootstrap --dry-run so it still fails outside a Git worktree without writing graph state.
• Updates README and design/teardown docs to mark bootstrap as an executable contract skeleton, not the completed scanner.

Problem Statement

• Hill 1 needs a stable command and JSON shape before scanner and inference slices can safely expand behavior.
• Agents and users need deterministic --dry-run --json output with no graph writes.
• The previous CLI had no bootstrap command, so the design docs were ahead of executable reality.

ADR Compliance (Required)

Relevant ADR(s)

• ADR-0002 (Worktree Independence and Materialization Architecture)
• ADR-0003 (Graph-Native Content, Deterministic Materialization, and Workspace Bridge)
• 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 if the command contract needs to be withdrawn.
• 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: Adds new git mind bootstrap command and bootstrap.schema.json; no existing command shape changes.
• Data model/storage changes: None. Default non-dry-run opens/initializes the graph but does not yet infer or persist semantic nodes/edges.
• Migration required?: No.
• User-facing behavior changes: git mind bootstrap now exists and emits a zero-count contract skeleton until scanner/inference slices land.

Test Plan (Required)

Unit

• Added/updated tests for changed logic
• Commands:

npx vitest run test/contracts.test.js

Integration

• Added/updated integration tests
• Commands:

npx vitest run test/contracts.integration.test.js -t 'bootstrap --dry-run --json'
npx vitest run test/contracts.test.js test/contracts.integration.test.js

Determinism

• Determinism assertions included for relevant paths
• Method: bootstrap --dry-run --json captures graph status before/after and asserts no graph state change.
• Commands:

npx vitest run test/contracts.integration.test.js -t 'bootstrap --dry-run --json'

Contract/Schema

• Schema validation updated/passing
• Commands:

npx vitest run test/contracts.test.js test/contracts.integration.test.js

Policy Gates

• Mechanical architecture gates pass
• Commands:

npm run lint
git diff --check
npm test

---

Security / Trust Impact

• Threat surface changed?: Minimal. Adds a local CLI command with no network calls and no external agent execution.
• Trust policy impact: None in this slice.
• Provenance/audit impact: JSON contract reserves provenance summary counts for follow-up scanner/inference slices.
• New failure modes introduced: bootstrap --dry-run now fails outside a Git worktree with an actionable error.

Performance Impact

• Hot path affected?: No.
• Expected impact (latency/memory/io): Bootstrap skeleton is constant-time aside from Git worktree validation and optional graph initialization.
• Benchmarks or profiling evidence: Full test suite remains green.

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 fdea284.
• Operational caveats: The command is an executable contract skeleton; scanner and inference behavior are planned follow-up slices.

Linked Issues / Milestones

• Closes bootstrap: define CLI contract and JSON output for git mind bootstrap #305
• Refs test: translate Hill 1 bootstrap acceptance criteria into failing tests #310
• Milestone: Hill 1 semantic bootstrap

---

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 4 minutes and 53 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: ba164702-98bc-4a58-9106-7fafba05d5fb

📥 Commits

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

📒 Files selected for processing (12)

• README.md
• TECHNICAL-TEARDOWN.md
• bin/git-mind.js
• docs/contracts/CLI_CONTRACTS.md
• docs/contracts/cli/bootstrap.schema.json
• docs/design/feature-profiles/bootstrap-command.md
• docs/design/h1-semantic-bootstrap.md
• src/bootstrap.js
• src/cli/commands.js
• src/cli/format.js
• test/contracts.integration.test.js
• test/contracts.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: fdea284395

ℹ️ 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]

Reject unknown bootstrap flags before running

In the new bootstrap dispatch, parseFlags accepts any unrecognized --... and this handler only reads dry-run/json, so a typo like git mind bootstrap --dryrun --json silently consumes --json as the unknown flag's value and runs in non-dry-run, non-JSON mode instead of failing. Because --dry-run is the command's no-write safety switch, validate the allowed bootstrap flags/positionals before calling bootstrap.

Useful? React with 👍 / 👎.