README.md

Documentation Map

This file defines which documents are canonical, which are transitional, and which are historical references.

Use it to avoid treating old planning artifacts as the active product story.

Canonical Product Docs

These describe what Git Mind is now and how work should be judged:

• README.md — current product summary
• ROADMAP.md — active Hills, supporting lanes, and playback cadence
• Git Mind Product Frame — IBM Design Thinking style product frame
• Hill 1 Semantic Bootstrap Spec — first executable Hill 1 slice
• git-warp Upgrade Audit — next enabling cycle before major Hill 1 implementation
• Git Mind North Star — longer-form strategic articulation
• ADR-0005 — official planning and governance model
• ADR-0006 — official delivery cycle and tests-as-spec model

Canonical Engineering Guardrails

These define constraints and contracts that remain in force:

• GRAPH_SCHEMA.md — graph contract
• Architecture Laws — non-negotiable engineering laws
• Review Rubric — architectural review gates
• Repo Fixture Strategy — canonical repository-shaped test substrate strategy
• ADRs — durable architecture decisions
• Contracts and related schemas — machine-facing contracts

Transitional Docs

These are still useful, but they carry some older framing and should not be treated as the primary product narrative:

• GUIDE.md — CLI and usage reference; still contains manual graph-authoring examples
• CONTRIBUTING.md — contributor workflow with current frame pointers added

Historical Reference Docs

These should not drive planning or product identity without explicit review:

• CHANGELOG.md — release history, not product strategy
• TECH-PLAN.md — deep technical artifact from an earlier planning era
• Risk Register — bridge/platform-era risk control document
• Risk Review Checklist — bridge/platform-era operating checklist
• Strategic Conversation Summary — historical context
• Dogfood Session — historical evidence, not current plan

Practical Rule

When documents disagree:

1. trust the canonical product docs first
2. then trust canonical engineering guardrails
3. treat transitional docs as implementation help, not product truth
4. treat historical docs as reference only

Planning Rule

GitHub issues are the execution backlog.

Hills and Playbacks live in:

• ROADMAP.md
• Git Mind Product Frame
• ADR-0005

The execution cycle and tests-as-spec rules live in:

• ADR-0006
• Repo Fixture Strategy

GitHub milestones are not the primary planning system for this repository.

Contributor Rule

When planning work, start with:

1. sponsor user
2. jobs to be done
3. Hills
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