Skip to content

feat: upgrade git-warp to v14.16.2 #314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
flyingrobots wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat: upgrade git-warp to v14.16.2 #314

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
12b9517
docs: frame git-warp upgrade audit cycle (#312)
flyingrobots Mar 25, 2026
8eba886
feat: upgrade git-warp to v14.16.2 (#312)
flyingrobots Mar 25, 2026
3964fb8
docs: align git-warp upgrade guidance (#312)
flyingrobots Mar 25, 2026
bc73cb0
fix: harden git-warp v14 compatibility boundary (#312)
flyingrobots Mar 25, 2026
4d88845
docs: record git-warp upgrade review fixes (#312)
flyingrobots Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,8 @@ Your space. Write about whatever you want:

## 5. TECH STACK REFERENCE

- **Runtime**: Node.js >= 20, ES modules
- **Core dependency**: `@git-stunts/git-warp` (local path, CRDT graph on Git)
- **Runtime**: Node.js >= 22, ES modules
- **Core dependency**: `@git-stunts/git-warp` (published package, CRDT graph on Git)
- **Plumbing**: `@git-stunts/plumbing` (must be installed as direct dependency)
- **Tests**: vitest
- **Style**: Plain JS with JSDoc, no TypeScript
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Fixed

- **git-warp v14 compatibility hardening** — Explicit `Map` detection in property-bag helpers, observer `match` validation, epoch/review malformed-record filtering, and edge-property normalization for export/merge (#312)
- **CLI contract canary timeout consistency** — Unified the CLI integration harness around a shared timeout budget and added edge-case coverage for the git-warp compatibility boundary (#312)

## [5.0.0] - 2026-02-25

### Breaking
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,8 @@ Your space. Write about whatever you want:

## 5. TECH STACK REFERENCE

- **Runtime**: Node.js >= 20, ES modules
- **Core dependency**: `@git-stunts/git-warp` (local path, CRDT graph on Git)
- **Runtime**: Node.js >= 22, ES modules
- **Core dependency**: `@git-stunts/git-warp` (published package, CRDT graph on Git)
- **Plumbing**: `@git-stunts/plumbing` (must be installed as direct dependency)
- **Tests**: vitest
- **Style**: Plain JS with JSDoc, no TypeScript
Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,9 +55,9 @@ GitHub milestones are not the primary planning surface for this repository.

## Prerequisites

- Node.js >= 20.0.0
- Node.js >= 22.0.0
- Git
- A local clone of [`@git-stunts/git-warp`](https://github.com/nicktomlin/git-warp) (git-mind depends on it via local path)
- npm access to install published dependencies, including [`@git-stunts/git-warp`](https://github.com/nicktomlin/git-warp)

## Setup

Expand Down
2 changes: 1 addition & 1 deletion GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ cd git-mind
npm install
```

git-mind depends on `@git-stunts/git-warp`, which is currently installed from a local path. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup details.
git-mind depends on the published `@git-stunts/git-warp` package. See [CONTRIBUTING.md](CONTRIBUTING.md) for current development setup details.
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify CONTRIBUTING.md mentions the published package model
echo "=== Checking CONTRIBUTING.md for git-warp setup guidance ==="
rg -n -C3 "git-warp|git-stunts" CONTRIBUTING.md | head -30

Repository: flyingrobots/git-mind

Length of output: 307

BLOCKING: GUIDE.md contradicts documented dependency model.

Line 67 claims git-mind "depends on the published @git-stunts/git-warp package," but AGENTS.md and CLAUDE.md explicitly require "git-stunts/git-warp (local path)" as the core dependency for CRDT graph on Git. This mismatch must be resolved before merging. Either:

  1. The documentation is stale and git-warp was never published (revert GUIDE.md to clarify local-path requirement), or
  2. AGENTS.md and CLAUDE.md require updating to reflect the published package model.

Additionally, CLAUDE.md explicitly mandates "git-stunts/plumbing is installed as a direct dependency"—ensure package.json reflects both requirements.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@GUIDE.md` at line 67, GUIDE.md currently states git-mind "depends on the
published `@git-stunts/git-warp` package" which contradicts AGENTS.md and
CLAUDE.md that require "git-stunts/git-warp (local path)" and also mandates
"git-stunts/plumbing" as a direct dependency; pick one model and make
consistent: either revert GUIDE.md to state the local-path requirement (update
the `git-stunts/git-warp` phrasing) and ensure CLAUDE.md/AGENTS.md remain
accurate, or update AGENTS.md and CLAUDE.md to reflect the published
`@git-stunts/git-warp` model; finally, ensure package.json lists the chosen
artifacts correctly (add or change entries for "git-stunts/git-warp" and
"git-stunts/plumbing" in dependencies or local path entries) so all three
documents (GUIDE.md, AGENTS.md, CLAUDE.md) and package.json are consistent.


### Verify the installation

Expand Down
4 changes: 3 additions & 1 deletion ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ 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
Expand All @@ -146,9 +147,10 @@ Primary references:

- [docs/design/git-mind.md](docs/design/git-mind.md)
- [docs/design/h1-semantic-bootstrap.md](docs/design/h1-semantic-bootstrap.md)
- [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), and [#311](https://github.com/flyingrobots/git-mind/issues/311)
- 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)

---

Expand Down
2 changes: 1 addition & 1 deletion TECH-PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The key insight: **Git is already a graph database.** It has an immutable object

## 2. Storage Layer: git-warp

git-mind delegates persistence to **@git-stunts/git-warp** (v10.3.2), a CRDT graph database that uses Git's object store as its backend.
git-mind delegates persistence to **@git-stunts/git-warp**. The specific version in use is defined in [package.json](package.json); this historical document originally described the `v10.3.2` era of the substrate.

### How data gets stored

Expand Down
1 change: 1 addition & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +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 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
Expand Down
163 changes: 163 additions & 0 deletions docs/design/git-warp-upgrade-audit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
# git-warp Upgrade Audit

Status: active execution on `feat/git-warp-upgrade-audit`

Related:

- [ROADMAP.md](../../ROADMAP.md)
- [ADR-0005](../adr/ADR-0005.md)
- [ADR-0006](../adr/ADR-0006.md)
- [Repo Fixture Strategy](./repo-fixture-strategy.md)
- issue [#312](https://github.com/flyingrobots/git-mind/issues/312)

## Purpose

Define the next enabling cycle before 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.

This is not a generic dependency bump.
It is a boundary audit plus upgrade cycle.

## Sponsor User

- A Git Mind maintainer extending the product who needs confidence that core graph, provenance, and time-travel behavior still behaves as Git Mind expects on a current git-warp version.

## Job To Be Done

- When I build new Git Mind behavior on top of git-warp, help me do it against a revalidated substrate with explicit compatibility evidence instead of stale assumptions.

## Context

Cycle starting state:

- declared in `package.json` as `^11.5.0`
- locked and installed at `11.5.0`

Live npm registry state checked on 2026-03-25:

- latest published `@git-stunts/git-warp` version: `14.16.2`

Chosen upgrade target for this cycle:

- `14.16.2`

That means this cycle upgrades Git Mind across three major versions of the substrate.

This does not automatically mean "upgrade immediately no matter what."
It does mean Git Mind should not keep expanding Hill 1 behavior without auditing the real upgrade surface first.

## Why This Cycle Exists

The goal is explicitly **not** to build a lot of new behavior on top of git-warp right now.

The goal is:

- understand the dependency boundary Git Mind actually uses
- strengthen the tests around that boundary
- upgrade deliberately
- keep future Hill 1 work from inheriting avoidable substrate drift

## Observed Dependency Boundary

Based on current code inspection, Git Mind directly imports and depends on a relatively narrow but important git-warp surface.

### Direct Imports

From `@git-stunts/git-warp`, Git Mind currently imports:

- default export `WarpGraph`
- `GitGraphAdapter`
- `CONTENT_PROPERTY_KEY`

### Verified Graph Instance Methods Used In `src/`

Git Mind currently relies on these graph instance methods:

- `createPatch()`
- `hasNode()`
- `getNodeProps()`
- `getNodes()`
- `getEdges()`
- `getContentOid()`
- `getContent()`
- `materialize({ ceiling })`
- `observer(name, config)`
- `discoverTicks()`

### Verified Patch Methods Used In `src/`

Git Mind currently relies on these patch methods:

- `addNode()`
- `addEdge()`
- `removeEdge()`
- `setProperty()`
- `setEdgeProperty()`
- `attachContent()`
- `commit()`

### High-Risk Semantics

The upgrade should pay special attention to:

1. `WarpGraph.open(...)` and `GitGraphAdapter` initialization semantics
2. time-travel behavior of `materialize({ ceiling })`
3. observer/filter behavior via `graph.observer(...)`
4. content attachment and retrieval APIs
5. tick discovery / historical traversal assumptions
6. patch commit semantics and idempotency

## Known Mismatches Already Exposed

This cycle exposed one concrete runtime compatibility change:

- `graph.getNodeProps()` now returns plain objects rather than `Map` instances

Git Mind must treat node property bags as a compatibility boundary rather than assuming a single container shape.

This cycle also started with contributor-facing docs that still claimed git-warp was installed via local path. Those docs should be corrected as part of the upgrade.

## Acceptance Criteria

This cycle succeeds when:

1. Git Mind's actual git-warp dependency surface is documented and reviewed.
2. Compatibility-sensitive behaviors are protected by tests.
3. The upgrade target version is chosen deliberately, not by vibes.
4. Git Mind installs and tests cleanly against the chosen upgraded version.
5. Docs reflect the real dependency model afterward.

## Execution Model

Per [ADR-0006](../adr/ADR-0006.md), this cycle should follow the normal design-to-test flow:

1. finalize the upgrade-audit design artifact
2. translate the risky boundary into failing tests
3. use shared repo fixtures where repository-shaped behavior matters
4. upgrade and implement until tests are green
5. run a playback / retrospective
6. update README and contributor docs if reality changed

## Recommended First Work Sequence

1. Inventory git-warp touchpoints in `src/` and relevant tests.
2. Add or strengthen tests around:
- graph open/init
- node/edge mutation
- content attachment
- time-travel / epoch behavior
- observer behavior if still relevant
3. Review upstream changes between `11.5.0` and the candidate target.
4. Upgrade the dependency and lockfile on a dedicated branch.
5. Fix breakage explicitly rather than papering over it.

## Playback Questions

Use these questions for the cycle retrospective:

1. Did we actually reduce substrate risk, or just move version numbers?
2. Are the important git-warp assumptions now executable as tests?
3. Did the upgrade simplify or complicate future Hill 1 work?
4. Did we discover any Git Mind behavior that was depending on accidental substrate quirks?
5. What follow-on work should be backlogged before deeper Hill 1 implementation resumes?
Loading
Loading