@izkac/forgekit 0.3.0 → 0.3.2

package/README.md

@@ -1,36 +1,83 @@
-# @izkac/forgekit
-
-Portable agent skills + CLIs. One package, three bins:
-
-| Bin | Role |
-|-----|------|
-| **`forgekit`** | Install / list / update / uninstall skills × agents |
-| **`forge`** | Forge workflow sessions |
-| **`review`** | Thorough code review pipeline |
-
-## Install
-
-```bash
-npm i -g @izkac/forgekit
-forgekit install
-```
-
-Interactive install uses arrow-key checkboxes — space to toggle, **`a` to select all**, enter to confirm. Pickers come pre-checked with what you already have installed; choosing the full set reconciles (new picks install, deselected ones are removed).
-
-Supported environments: Claude Code, Cursor, Codex CLI, GitHub Copilot, Gemini CLI, Windsurf, opencode — each into its global Agent-Skills directory.
-
-Non-interactive:
-
-```bash
-forgekit install --skills forge,thorough-code-review --agents cursor,claude,copilot --force
-```
-
-## Docs
-
-- After install, full Forge reference: `~/.claude/skills/forge/docs/forge.md` (or the matching dir for your environment)
-- [How to use Forgekit](https://github.com/izkac/forgekit/blob/main/docs/usage.md)
-- [Repository README](https://github.com/izkac/forgekit#readme)
-
-## License
-
-MIT
+# @izkac/forgekit
+
+**A disciplined development workflow for AI coding agents — portable across Claude Code, Cursor, Codex, Copilot, Gemini, Windsurf, and opencode.**
+
+![npm](https://img.shields.io/npm/v/@izkac/forgekit) ![node](https://img.shields.io/node/v/@izkac/forgekit) ![license](https://img.shields.io/npm/l/@izkac/forgekit)
+
+AI agents are fast but undisciplined: they claim success on stubs, skip verification, over-build, and quietly leave the human behind. Forgekit installs a **gated workflow** that holds an agent to the standards a senior engineer would — and gives you, the operator, the visibility and control to stay in charge of a whole fleet of them.
+
+One package, three command-line tools:
+
+| Bin | What it does |
+|-----|--------------|
+| **`forgekit`** | Install / update the Forge skills into any supported agent |
+| **`forge`** | Run the Forge workflow — sessions, integrity gates, fleet control |
+| **`review`** | Standalone multi-pass thorough code review |
+
+## Why Forge (the workflow)
+
+Forge moves every substantial change through explicit phases — **triage → brainstorm → plan → implement → verify → review → done** — and enforces them with **executable gates**, not honor-system promises:
+
+- **Operator brief** — before any code is written, the agent produces a plain-language HTML explainer of what's about to be built (with diagrams). It opens in your browser and *gates implementation*: you approve what you actually understand, not a wall of spec markdown.
+- **Runtime spine** — every change declares how each capability wires up: library → runtime owner → what it writes → the evidence it works. No orphaned code that's "done" but never called.
+- **Executable product loop** — for jobs, workers, and pipelines the end-to-end acceptance is a *command that must exit green*, not a paragraph claiming it would.
+- **Registered deferrals** — "wire it up later" is only allowed when tracked; the finish gate refuses unresolved ones.
+- **Session scorecard** — every session leaves a graded, measurable trail (A–F).
+
+The result: agents that can't fake completion, and a workflow you can trust to run with less babysitting.
+
+## Fleet control — command every session from one terminal
+
+Running agents across three IDEs and two terminals? `forge fleet` is a single control surface over all of them, across every project and engine:
+
+```bash
+forge fleet list       # every session: phase, task progress, engine, activity
+forge fleet watch      # live-refreshing dashboard
+forge fleet view <s>   # detail + live transcript tail (Claude Code)
+forge fleet send <s> "pause and report"   # message any session; --all broadcasts
+```
+
+Sessions auto-register the moment they touch Forge — including ones running inside Claude Desktop or Cursor. You see where everything stands at a glance and steer any of them without switching windows.
+
+## Portable — one workflow, every agent
+
+The same skills and the same discipline, installed into each agent's native skills directory:
+
+**Claude Code · Cursor · Codex CLI · GitHub Copilot · Gemini CLI · Windsurf · opencode**
+
+Planning is engine-flexible too: use the **OpenSpec** CLI if you have it, or the **built-in specs engine** (plain markdown, same layout) if you don't. Optional **ADRs** archive each finished change into an Architecture Decision Record.
+
+## Install
+
+```bash
+npm i -g @izkac/forgekit
+forgekit install            # interactive: pick skills + agents (space toggles, `a` = all)
+```
+
+Non-interactive:
+
+```bash
+forgekit install --skills forge,thorough-code-review --agents claude,cursor --force
+```
+
+Then wire a project and start working:
+
+```bash
+cd your-project
+forge init --claude --cursor      # slash commands, rules, hooks, .forge/
+
+# in the agent chat:
+/forge add a health endpoint that returns { ok: true }
+```
+
+The agent triages, brainstorms with you, plans a tracked change, writes the operator brief for your approval, then implements task-by-task with TDD and per-task review — refusing to call itself done until the gates are green.
+
+## Docs
+
+- **[How to use Forgekit](https://github.com/izkac/forgekit/blob/main/docs/usage.md)** — full tutorial: install, project wiring, worked examples, integrity gates, fleet, cheat sheet
+- **[Full Forge reference](https://github.com/izkac/forgekit/blob/main/skills/forge/docs/forge.md)** — phases, pace matrix, integrity rules (also installed at `~/.claude/skills/forge/docs/forge.md`)
+- **[Repository](https://github.com/izkac/forgekit#readme)**
+
+## License
+
+MIT. The Forge skill and several of its workflows are adapted from [Superpowers](https://github.com/obra/superpowers) (MIT).

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {
-    "forgekit": "./bin/forgekit.mjs",
-    "forge": "./bin/forge.mjs",
-    "review": "./bin/review.mjs"
+    "forgekit": "bin/forgekit.mjs",
+    "forge": "bin/forge.mjs",
+    "review": "bin/review.mjs"
   },
   "files": [
     "bin",

package/src/integrity.mjs

@@ -58,14 +58,52 @@ 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;
   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 liveOrArchived(openspecChanges, change);
 
   let specsRoot = DEFAULT_SPECS_DIR;
   try {
@@ -73,13 +111,18 @@ 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 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;
+  return (
+    findArchivedChangeDir(openspecChanges, change) ??
+    findArchivedChangeDir(specsChanges, change) ??
+    openspecDir
+  );
 }
 
 /**

package/src/integrity.test.mjs

@@ -105,6 +105,70 @@ 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);
+    } 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 {