|
| 1 | +# git-warp Upgrade Audit |
| 2 | + |
| 3 | +Status: active execution on `feat/git-warp-upgrade-audit` |
| 4 | + |
| 5 | +Related: |
| 6 | + |
| 7 | +- [ROADMAP.md](../../ROADMAP.md) |
| 8 | +- [ADR-0005](../adr/ADR-0005.md) |
| 9 | +- [ADR-0006](../adr/ADR-0006.md) |
| 10 | +- [Repo Fixture Strategy](./repo-fixture-strategy.md) |
| 11 | +- issue [#312](https://github.com/flyingrobots/git-mind/issues/312) |
| 12 | + |
| 13 | +## Purpose |
| 14 | + |
| 15 | +Define the next enabling cycle before major Hill 1 implementation: |
| 16 | + |
| 17 | +> 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. |
| 18 | +
|
| 19 | +This is not a generic dependency bump. |
| 20 | +It is a boundary audit plus upgrade cycle. |
| 21 | + |
| 22 | +## Sponsor User |
| 23 | + |
| 24 | +- 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. |
| 25 | + |
| 26 | +## Job To Be Done |
| 27 | + |
| 28 | +- 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. |
| 29 | + |
| 30 | +## Context |
| 31 | + |
| 32 | +Cycle starting state: |
| 33 | + |
| 34 | +- declared in `package.json` as `^11.5.0` |
| 35 | +- locked and installed at `11.5.0` |
| 36 | + |
| 37 | +Live npm registry state checked on 2026-03-25: |
| 38 | + |
| 39 | +- latest published `@git-stunts/git-warp` version: `14.16.2` |
| 40 | + |
| 41 | +Chosen upgrade target for this cycle: |
| 42 | + |
| 43 | +- `14.16.2` |
| 44 | + |
| 45 | +That means this cycle upgrades Git Mind across three major versions of the substrate. |
| 46 | + |
| 47 | +This does not automatically mean "upgrade immediately no matter what." |
| 48 | +It does mean Git Mind should not keep expanding Hill 1 behavior without auditing the real upgrade surface first. |
| 49 | + |
| 50 | +## Why This Cycle Exists |
| 51 | + |
| 52 | +The goal is explicitly **not** to build a lot of new behavior on top of git-warp right now. |
| 53 | + |
| 54 | +The goal is: |
| 55 | + |
| 56 | +- understand the dependency boundary Git Mind actually uses |
| 57 | +- strengthen the tests around that boundary |
| 58 | +- upgrade deliberately |
| 59 | +- keep future Hill 1 work from inheriting avoidable substrate drift |
| 60 | + |
| 61 | +## Observed Dependency Boundary |
| 62 | + |
| 63 | +Based on current code inspection, Git Mind directly imports and depends on a relatively narrow but important git-warp surface. |
| 64 | + |
| 65 | +### Direct Imports |
| 66 | + |
| 67 | +From `@git-stunts/git-warp`, Git Mind currently imports: |
| 68 | + |
| 69 | +- default export `WarpGraph` |
| 70 | +- `GitGraphAdapter` |
| 71 | +- `CONTENT_PROPERTY_KEY` |
| 72 | + |
| 73 | +### Verified Graph Instance Methods Used In `src/` |
| 74 | + |
| 75 | +Git Mind currently relies on these graph instance methods: |
| 76 | + |
| 77 | +- `createPatch()` |
| 78 | +- `hasNode()` |
| 79 | +- `getNodeProps()` |
| 80 | +- `getNodes()` |
| 81 | +- `getEdges()` |
| 82 | +- `getContentOid()` |
| 83 | +- `getContent()` |
| 84 | +- `materialize({ ceiling })` |
| 85 | +- `observer(name, config)` |
| 86 | +- `discoverTicks()` |
| 87 | + |
| 88 | +### Verified Patch Methods Used In `src/` |
| 89 | + |
| 90 | +Git Mind currently relies on these patch methods: |
| 91 | + |
| 92 | +- `addNode()` |
| 93 | +- `addEdge()` |
| 94 | +- `removeEdge()` |
| 95 | +- `setProperty()` |
| 96 | +- `setEdgeProperty()` |
| 97 | +- `attachContent()` |
| 98 | +- `commit()` |
| 99 | + |
| 100 | +### High-Risk Semantics |
| 101 | + |
| 102 | +The upgrade should pay special attention to: |
| 103 | + |
| 104 | +1. `WarpGraph.open(...)` and `GitGraphAdapter` initialization semantics |
| 105 | +2. time-travel behavior of `materialize({ ceiling })` |
| 106 | +3. observer/filter behavior via `graph.observer(...)` |
| 107 | +4. content attachment and retrieval APIs |
| 108 | +5. tick discovery / historical traversal assumptions |
| 109 | +6. patch commit semantics and idempotency |
| 110 | + |
| 111 | +## Known Mismatches Already Exposed |
| 112 | + |
| 113 | +This cycle exposed one concrete runtime compatibility change: |
| 114 | + |
| 115 | +- `graph.getNodeProps()` now returns plain objects rather than `Map` instances |
| 116 | + |
| 117 | +Git Mind must treat node property bags as a compatibility boundary rather than assuming a single container shape. |
| 118 | + |
| 119 | +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. |
| 120 | + |
| 121 | +## Acceptance Criteria |
| 122 | + |
| 123 | +This cycle succeeds when: |
| 124 | + |
| 125 | +1. Git Mind's actual git-warp dependency surface is documented and reviewed. |
| 126 | +2. Compatibility-sensitive behaviors are protected by tests. |
| 127 | +3. The upgrade target version is chosen deliberately, not by vibes. |
| 128 | +4. Git Mind installs and tests cleanly against the chosen upgraded version. |
| 129 | +5. Docs reflect the real dependency model afterward. |
| 130 | + |
| 131 | +## Execution Model |
| 132 | + |
| 133 | +Per [ADR-0006](../adr/ADR-0006.md), this cycle should follow the normal design-to-test flow: |
| 134 | + |
| 135 | +1. finalize the upgrade-audit design artifact |
| 136 | +2. translate the risky boundary into failing tests |
| 137 | +3. use shared repo fixtures where repository-shaped behavior matters |
| 138 | +4. upgrade and implement until tests are green |
| 139 | +5. run a playback / retrospective |
| 140 | +6. update README and contributor docs if reality changed |
| 141 | + |
| 142 | +## Recommended First Work Sequence |
| 143 | + |
| 144 | +1. Inventory git-warp touchpoints in `src/` and relevant tests. |
| 145 | +2. Add or strengthen tests around: |
| 146 | + - graph open/init |
| 147 | + - node/edge mutation |
| 148 | + - content attachment |
| 149 | + - time-travel / epoch behavior |
| 150 | + - observer behavior if still relevant |
| 151 | +3. Review upstream changes between `11.5.0` and the candidate target. |
| 152 | +4. Upgrade the dependency and lockfile on a dedicated branch. |
| 153 | +5. Fix breakage explicitly rather than papering over it. |
| 154 | + |
| 155 | +## Playback Questions |
| 156 | + |
| 157 | +Use these questions for the cycle retrospective: |
| 158 | + |
| 159 | +1. Did we actually reduce substrate risk, or just move version numbers? |
| 160 | +2. Are the important git-warp assumptions now executable as tests? |
| 161 | +3. Did the upgrade simplify or complicate future Hill 1 work? |
| 162 | +4. Did we discover any Git Mind behavior that was depending on accidental substrate quirks? |
| 163 | +5. What follow-on work should be backlogged before deeper Hill 1 implementation resumes? |
0 commit comments