Merge pull request #321 from flyingrobots/feat/isolated-warp-upgrade-fixture

[codex] Add isolated git-warp v17 upgrade harness

Author: flyingrobots

bin/git-mind.js

@@ -499,3 +499,21 @@ switch (command) {
     process.exitCode = command ? 1 : 0;
     break;
 }
+
+async function flushStream(stream) {
+  if (!stream.writable || stream.destroyed) return;
+
+  await new Promise((resolve, reject) => {
+    stream.write('', err => {
+      if (!err || err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED') {
+        resolve();
+        return;
+      }
+      reject(err);
+    });
+  });
+}
+
+await flushStream(process.stdout);
+await flushStream(process.stderr);
+process.exit(process.exitCode ?? 0);

docs/design/git-warp-upgrade-audit.md

@@ -1,6 +1,8 @@
 # git-warp Upgrade Audit
 
-Status: active execution on `feat/git-warp-upgrade-audit`
+Status: active execution. The original 14.x audit ran on
+`feat/git-warp-upgrade-audit`; the v17 continuation is running on
+`feat/isolated-warp-upgrade-fixture`.
 
 Related:
 
@@ -47,6 +49,39 @@ That means this cycle upgrades Git Mind across three major versions of the subst
 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.
 
+## 2026-05-31 v17 Continuation
+
+The original audit cycle moved Git Mind to the 14.x substrate. A follow-on
+modernization is now needed because the live npm registry reports:
+
+- latest published `@git-stunts/git-warp` version: `17.0.0`
+- latest published `@git-stunts/plumbing` version: `3.0.3`
+
+`@git-stunts/git-warp@17.0.0` depends on `@git-stunts/plumbing@^3.0.3`, so
+the next substrate upgrade should move those packages together.
+
+This pass keeps the upgrade sequence explicit:
+
+1. freeze a sanitized Git-native fixture from the current v5 / git-warp 14 state
+2. include only `HEAD` and the relevant `refs/warp/gitmind/*` graph refs
+3. test that fixture in Docker without mounting this checkout into the container
+4. pack the current Git Mind package and copy it into the Docker context
+5. run graph/status/export assertions with a scrubbed home and Git config
+6. upgrade to git-warp 17 / plumbing 3 and prove the migrated fixture still reads
+
+This fixture is intentionally a Git bundle rather than a raw working-directory
+archive. It preserves the exact Git object and WARP ref state under test while
+excluding `node_modules`, local Git config, remotes, hooks, reflogs, stash state,
+and host-specific paths.
+
+Related issue: [#320](https://github.com/flyingrobots/git-mind/issues/320)
+
+The local playback command for this safety rail is:
+
+```bash
+npm run test:upgrade-fixture
+```
+
 ## Why This Cycle Exists
 
 The goal is explicitly **not** to build a lot of new behavior on top of git-warp right now.