Skip to content

adr

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

adr

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
ADR-0001.md
ADR-0001.md
 
 
ADR-0002.md
ADR-0002.md
 
 
ADR-0003.md
ADR-0003.md
 
 
ADR-0004.md
ADR-0004.md
 
 
ADR-0005.md
ADR-0005.md
 
 
ADR-0006.md
ADR-0006.md
 
 
README.md
README.md
 
 

README.md

Architecture Decision Records (ADRs)

This directory captures durable architecture and governance decisions for Git Mind.

These ADRs are architecture references, not the canonical product narrative. Some of them were written during a broader platform and bridge planning phase, but they still matter where they establish substrate or invariants that remain in force. Some ADRs also capture repository-level planning and governance rules when those rules are intended to constrain how future work is framed.

Use ADRs for decisions that are hard to reverse, cross-cut multiple subsystems, or define platform invariants.

ADR Index

ADR-0002 — Worktree Independence and Materialization Architecture

Status: Accepted Date: 2026-02-15

What it establishes

  • Git worktree state is not authoritative for Git Mind graph state.
  • Graph truth (WARP causal graph + provenance) is canonical.
  • Materialized artifacts are derived outputs, non-canonical by default.
  • Context-sensitive operations must be explicit (asOf, observer, trust).
  • Generated artifact hygiene requires defense-in-depth (not .gitignore alone).

Why it matters

Defines the core separation model: worktree-aware, never worktree-bound.

ADR-0003 — Graph-Native Content, Deterministic Materialization, and Workspace Bridge

Status: Accepted Date: 2026-02-15

What it adds

  • “Content-on-node” remains canonical, but editing must be file-native in UX.
  • SyncAdapter projected workspace is the default compatibility bridge.
  • FuseAdapter is optional advanced/performance mode.
  • Graph→editor invalidation/signaling is required infra.
  • Writeback is transactional, conflict-aware, deterministic, and receipt-backed.
  • Workspace path policy: editable entities vs read-only derived outputs.

Why it matters

Turns the separation model into an adoption-ready product path without breaking architecture laws.

What changed from ADR-0002 to ADR-0003

  1. From principle to execution:
    ADR-0002 defined boundaries; ADR-0003 defines how users actually work within them.

  2. Editing UX became first-class:
    The project now explicitly treats editing ergonomics as a top adoption risk.

  3. Bridge strategy finalized:
    Universal Sync Workspace Mode first, FUSE later for performance.

  4. Live update correctness added:
    Graph subscription + path invalidation are required to prevent stale editor state.

  5. Writeback semantics hardened:
    Base frontier/hash checks + explicit conflict paths + receipts.

ADR Authoring Guidelines

Create a new ADR when a decision is:

  • hard to reverse,
  • architecture-wide,
  • policy-defining,
  • or likely to be questioned later.

Recommended sections:

  1. Context
  2. Decision
  3. Alternatives considered
  4. Consequences
  5. Risks & mitigations
  6. Acceptance criteria
  7. Implementation impact

ADR Lifecycle

  • Proposed: Draft under discussion.
  • Accepted: Approved and active.
  • Superseded: Replaced by a newer ADR (link both ways).
  • Deprecated: No longer applied, retained for historical context.

ADR-0004 — Content Attachments Belong in git-warp

Status: Accepted Date: 2026-02-20

What it establishes

  • Content-on-node (CAS-backed blob attachment) is a git-warp responsibility, not git-mind.
  • git-warp should install git-cas and expose an API for attaching content-addressed blobs to nodes.
  • git-mind provides the CLI/UX layer (content set/show/edit) on top.
  • This aligns git-warp with Paper I's (S, α, β) formalism — nodes carrying Atom(p) payloads.

Why it matters

Prevents git-mind from duplicating CRDT, time-travel, observer, and provenance guarantees that already exist in the substrate. Makes the attachment primitive available to any git-warp consumer, not just git-mind.

ADR-0005 — IBM Design Thinking Governs Product Planning

Status: Accepted Date: 2026-03-24

What it establishes

  • IBM Design Thinking is the official planning model for Git Mind.
  • Sponsor user, jobs, Hills, and Playbacks are the primary product framing tools.
  • GitHub issues are the execution backlog.
  • GitHub milestones are not the primary planning control plane.
  • Canonical planning docs must stay aligned with that model.

Why it matters

Prevents Git Mind from drifting back into milestone theater, architecture-first planning, or backlog-only decision making.

ADR-0006 — 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.

Quick Contribution Rules

  • Keep ADRs concise but specific.
  • Avoid ambiguous wording (“usually”, “maybe”) in core invariants.
  • Include explicit consequences and operational impact.
  • Link relevant Hill(s), issue(s), contracts, and tooling gates affected by the decision.