@izkac/forgekit 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {

package/src/e2e.mjs

@@ -60,7 +60,9 @@ if (!sessionId) {
 }
 
 const { dir, session } = loadSession(sessionId);
-const file = e2ePath({ session, sessionDir: dir });
+// init writes: target the live change dir only (never fall back into the
+// archive). run/check/status read: allow the archive fallback.
+const file = e2ePath({ session, sessionDir: dir, forWrite: sub === 'init' });
 
 if (sub === 'init') {
   try {

package/src/integrity.mjs

@@ -58,14 +58,58 @@ function isNonEmptyString(value) {
  *
  * @param {{ cwd?: string, session?: Record<string, unknown> | null }} opts
  */
+/**
+ * The archived copy of a change, when the live dir is gone. Archiving moves
+ * `changes/<change>/` to `changes/archive/<YYYY-MM-DD>-<change>/`, so the
+ * done-gate integrity check (which runs *after* archive in the finish flow)
+ * would otherwise never find spine.json/e2e.json. Returns null if no match.
+ *
+ * @param {string} changesDir absolute path to `<root>/changes`
+ * @param {string} change change name
+ */
+function findArchivedChangeDir(changesDir, change) {
+  const archiveDir = path.join(changesDir, 'archive');
+  if (!fs.existsSync(archiveDir)) return null;
+  let entries;
+  try {
+    entries = fs.readdirSync(archiveDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const matches = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    // CLI + documented manual archive both name dirs `YYYY-MM-DD-<change>`;
+    // slice(11) drops the `YYYY-MM-DD-` prefix so the suffix must equal the
+    // change exactly (no false match on `…-other-<change>`).
+    .filter((name) => name === change || (/^\d{4}-\d{2}-\d{2}-/.test(name) && name.slice(11) === change))
+    .sort();
+  // Date-prefixed names sort lexically by date — newest archive wins.
+  return matches.length ? path.join(archiveDir, matches[matches.length - 1]) : null;
+}
+
+/** Live change dir if present, else its archived copy, else the live path. */
+function liveOrArchived(changesDir, change) {
+  const liveDir = path.join(changesDir, change);
+  if (fs.existsSync(liveDir)) return liveDir;
+  return findArchivedChangeDir(changesDir, change) ?? liveDir;
+}
+
 export function resolveChangeDir(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const session = opts.session ?? null;
+  // Write callers (spine/e2e init) must always target the LIVE change dir —
+  // scaffolding into an archived record would corrupt frozen history. Only
+  // read callers (checks, gates) fall back to the archive.
+  const forWrite = opts.forWrite === true;
   const change = session && isNonEmptyString(session.openspecChange) ? session.openspecChange : null;
   if (!change) return null;
 
-  const openspecDir = path.join(cwd, 'openspec', 'changes', change);
-  if (session.planType === 'openspec') return openspecDir;
+  const openspecChanges = path.join(cwd, 'openspec', 'changes');
+  const openspecDir = path.join(openspecChanges, change);
+  if (session.planType === 'openspec') {
+    return forWrite ? openspecDir : liveOrArchived(openspecChanges, change);
+  }
 
   let specsRoot = DEFAULT_SPECS_DIR;
   try {
@@ -73,13 +117,21 @@ export function resolveChangeDir(opts = {}) {
   } catch {
     // keep default
   }
-  const specsDir = path.join(cwd, specsRoot, 'changes', change);
-  if (session.planType === 'specs') return specsDir;
+  const specsChanges = path.join(cwd, specsRoot, 'changes');
+  const specsDir = path.join(specsChanges, change);
+  if (session.planType === 'specs') {
+    return forWrite ? specsDir : liveOrArchived(specsChanges, change);
+  }
 
-  // planType unknown — prefer whichever exists
+  // planType unknown — prefer whichever exists (live first, then archived)
   if (fs.existsSync(openspecDir)) return openspecDir;
   if (fs.existsSync(specsDir)) return specsDir;
-  return openspecDir;
+  if (forWrite) return openspecDir;
+  return (
+    findArchivedChangeDir(openspecChanges, change) ??
+    findArchivedChangeDir(specsChanges, change) ??
+    openspecDir
+  );
 }
 
 /**

package/src/integrity.test.mjs

@@ -105,6 +105,94 @@ test('resolveChangeDir: openspec plan type and session-dir fallback', () => {
   }
 });
 
+test('resolveChangeDir: falls back to the archived copy after archive', () => {
+  for (const [planType, root] of [
+    ['openspec', ['openspec', 'changes']],
+    ['specs', ['specs', 'changes']],
+  ]) {
+    const cwd = tmp('forge-changedir-arch-');
+    try {
+      const changesDir = path.join(cwd, ...root);
+      const liveDir = path.join(changesDir, 'add-customer-registry');
+      fs.mkdirSync(liveDir, { recursive: true });
+      const session = { planType, openspecChange: 'add-customer-registry' };
+
+      // Live dir present → live path.
+      assert.equal(resolveChangeDir({ cwd, session }), liveDir);
+
+      // Archive moves it → resolve follows into changes/archive/<date>-<name>.
+      const archived = path.join(changesDir, 'archive', '2026-07-20-add-customer-registry');
+      fs.mkdirSync(path.dirname(archived), { recursive: true });
+      fs.renameSync(liveDir, archived);
+      assert.equal(resolveChangeDir({ cwd, session }), archived);
+
+      // Newest archive wins when a change name recurs.
+      const older = path.join(changesDir, 'archive', '2025-01-01-add-customer-registry');
+      fs.mkdirSync(older, { recursive: true });
+      assert.equal(resolveChangeDir({ cwd, session }), archived);
+
+      // No false match on a different change that ends with the same words.
+      fs.mkdirSync(path.join(changesDir, 'archive', '2026-07-20-extra-add-customer-registry'), {
+        recursive: true,
+      });
+      assert.equal(resolveChangeDir({ cwd, session }), archived);
+
+      // forWrite (spine/e2e init) never follows into the archive — writes must
+      // target the live change dir so scaffolding can't corrupt frozen history.
+      assert.equal(resolveChangeDir({ cwd, session, forWrite: true }), liveDir);
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true });
+    }
+  }
+});
+
+test('spinePath/e2ePath forWrite target the live dir even after archive', () => {
+  const cwd = tmp('forge-write-guard-');
+  try {
+    const session = { planType: 'openspec', openspecChange: 'add-customer-registry' };
+    const changesDir = path.join(cwd, 'openspec', 'changes');
+    // Only the archived copy exists — mimics running init after archive.
+    const archived = path.join(changesDir, 'archive', '2026-07-20-add-customer-registry');
+    fs.mkdirSync(archived, { recursive: true });
+    const liveDir = path.join(changesDir, 'add-customer-registry');
+
+    // Read path resolves the archive; write path stays on the (absent) live dir.
+    assert.equal(spinePath({ cwd, session }), path.join(archived, 'spine.json'));
+    assert.equal(spinePath({ cwd, session, forWrite: true }), path.join(liveDir, 'spine.json'));
+    assert.equal(e2ePath({ cwd, session }), path.join(archived, 'e2e.json'));
+    assert.equal(e2ePath({ cwd, session, forWrite: true }), path.join(liveDir, 'e2e.json'));
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: passes after archive (spine resolves in archive dir)', () => {
+  const cwd = tmp('forge-int-archived-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    const session = { planType: 'openspec', openspecChange: 'add-customer-registry', slug: 'add-customer-registry' };
+
+    // Green while live: spine in the change dir (sync-only notApplicable).
+    const liveDir = path.join(cwd, 'openspec', 'changes', 'add-customer-registry');
+    fs.mkdirSync(liveDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(liveDir, 'spine.json'),
+      `${JSON.stringify({ rows: [], notApplicable: 'sync HTTP only' }, null, 2)}\n`,
+      'utf8',
+    );
+    assert.equal(runIntegrityChecks({ cwd, sessionDir, session }).ok, true);
+
+    // Archive the change — the mechanical gate must STILL pass (the bug: it
+    // used to look only at the vanished live path and fail).
+    const archived = path.join(cwd, 'openspec', 'changes', 'archive', '2026-07-20-add-customer-registry');
+    fs.mkdirSync(path.dirname(archived), { recursive: true });
+    fs.renameSync(liveDir, archived);
+    assert.equal(runIntegrityChecks({ cwd, sessionDir, session }).ok, true);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
 test('deferrals: add, list, resolve lifecycle', () => {
   const dir = tmp('forge-defer-');
   try {

package/src/spine.mjs

@@ -48,7 +48,9 @@ if (!sessionId) {
 }
 
 const { dir, session } = loadSession(sessionId);
-const file = spinePath({ session, sessionDir: dir });
+// init writes: target the live change dir only (never fall back into the
+// archive). check/status read: allow the archive fallback.
+const file = spinePath({ session, sessionDir: dir, forWrite: sub === 'init' });
 
 if (sub === 'init') {
   try {