@izkac/forgekit 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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

@@ -98,12 +98,18 @@ function liveOrArchived(changesDir, change) {
 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 openspecChanges = path.join(cwd, 'openspec', 'changes');
   const openspecDir = path.join(openspecChanges, change);
-  if (session.planType === 'openspec') return liveOrArchived(openspecChanges, change);
+  if (session.planType === 'openspec') {
+    return forWrite ? openspecDir : liveOrArchived(openspecChanges, change);
+  }
 
   let specsRoot = DEFAULT_SPECS_DIR;
   try {
@@ -113,11 +119,14 @@ export function resolveChangeDir(opts = {}) {
   }
   const specsChanges = path.join(cwd, specsRoot, 'changes');
   const specsDir = path.join(specsChanges, change);
-  if (session.planType === 'specs') return liveOrArchived(specsChanges, change);
+  if (session.planType === 'specs') {
+    return forWrite ? specsDir : liveOrArchived(specsChanges, change);
+  }
 
   // planType unknown — prefer whichever exists (live first, then archived)
   if (fs.existsSync(openspecDir)) return openspecDir;
   if (fs.existsSync(specsDir)) return specsDir;
+  if (forWrite) return openspecDir;
   return (
     findArchivedChangeDir(openspecChanges, change) ??
     findArchivedChangeDir(specsChanges, change) ??

package/src/integrity.test.mjs

@@ -136,12 +136,36 @@ test('resolveChangeDir: falls back to the archived copy after archive', () => {
         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 {

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 {

package/vendor/skills/forge/references/operator-brief.md

@@ -25,8 +25,11 @@ forge brief stamp        # records specs hash + opens it in the operator's brows
 forge phase implement --tasks-total <N>   # hard-gated on a fresh stamped brief
 ```
 
-If any spec file changes later, the brief goes **stale** — update the affected
-sections and `forge brief stamp` again. `forge brief check` reports status.
+If any spec file changes later, the brief goes **stale** — the gate cannot
+tell meaning changes from typo fixes, so it flags both. Triage cheaply: if the
+edit doesn't change what the operator approved (typo, task renumber,
+formatting), just re-run `forge brief stamp` — no rewrite. If it does, update
+the affected sections first, then stamp. `forge brief check` reports status.
 Genuine edge case (operator explicitly waives it):
 `forge phase implement --allow-incomplete "<reason>"`.
 

package/vendor/skills/forge/references/runtime-integrity.md

@@ -80,6 +80,29 @@ driven by any command (e.g. requires a physical device). Reviewers police the
 reason; "no time" or "covered by unit tests" is a REJECT. Keep a short loop
 narrative under `## Product loop` in `verify-evidence.md` as reviewer context.
 
+### Keeping the loop cheap (cost policy)
+
+"Too complex to test" is usually a signal to test it, not to wave it through —
+a loop is complex exactly when the feature has many wiring seams, which is
+when wiring silently breaks. Never skip the loop for complexity; control its
+cost instead:
+
+- **Ask before building new harness infrastructure, not before testing.** If
+  a harness already exists (test server, isolated ports, scratch DB), the loop
+  is cheap — author it. If the loop would require building a harness from
+  scratch or driving a third-party service, stop and ask the user: that is a
+  project, not a test.
+- **One executed loop per capability, not per assertion.** Push edge cases
+  into unit tests; e2e proves the wiring exists.
+- **Set `timeoutMs` from the step count up front.** A 10-step loop is never a
+  30s test — a too-small budget fails at whatever line the clock runs out on,
+  which reads as a phantom regression.
+- **Run it once, at the end, serially** — never alongside unit suites; load
+  makes real assertions look flaky.
+- **Prefer a production/preview build over the dev server** when the loop
+  drives a web app — compile-on-demand and dev-mode socket noise dominate the
+  per-run cost and bury the actual assertion.
+
 ## 6. Job-kind closure
 
 Every job kind / entry point on the product surface (enums, API, UI) is, before