gm-skill 2.0.1147 → 2.0.1149

package/README.md

@@ -35,7 +35,7 @@ An earlier generation fanned out fifteen per-platform downstream repos (gm-cc, g
 
 ## Version
 
-`2.0.1147` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` (or any cascading sibling crate) republishes this package.
+`2.0.1149` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` (or any cascading sibling crate) republishes this package.
 
 ## Source of truth
 

package/bin/plugkit.version

@@ -1 +1 @@
-0.1.413
+0.1.414

package/bin/plugkit.wasm.sha256

@@ -1 +1 @@
-4032ac9258c6fb79106ef9e02a40c9cba7a509a6e0507d4d0c062645b25799a6  plugkit.wasm
+74a7d080de71336c5d7c56a0edd4936c853259a21323c0ab797ce9a3782f5dac  plugkit.wasm

package/gm-plugkit/cli.js

@@ -1,18 +1,52 @@
 #!/usr/bin/env node
 'use strict';
 
-const { ensureReady, startSpoolDaemon, getBinaryPath, isReady } = require('./bootstrap');
+const fs = require('fs');
+const path = require('path');
+const { ensureReady, startSpoolDaemon } = require('./bootstrap');
 
 const usage = `gm-plugkit — Bootstrap and daemon-spawn for gm plugkit binary.
 
 Usage:
   bun x gm-plugkit@latest          Bootstrap + start spool daemon
-  bun x gm-plugkit@latest --daemon  Same as default
-  bun x gm-plugkit@latest --binary  Print binary path only
-  bun x gm-plugkit@latest --status  JSON status check
-  bun x gm-plugkit@latest --help    Show this help
+  bun x gm-plugkit@latest spool    Same as default (explicit)
+  bun x gm-plugkit@latest --daemon Same as default
+  bun x gm-plugkit@latest --binary Print binary path only
+  bun x gm-plugkit@latest --status JSON status check
+  bun x gm-plugkit@latest --help   Show this help
 `;
 
+function spoolDir() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return path.join(projectDir, '.gm', 'exec-spool');
+}
+
+function ensureSpoolDir() {
+  try { fs.mkdirSync(spoolDir(), { recursive: true }); } catch (_) {}
+}
+
+function writeCliStatus(spec) {
+  try {
+    ensureSpoolDir();
+    fs.writeFileSync(
+      path.join(spoolDir(), '.cli-status.json'),
+      JSON.stringify({ ts: new Date().toISOString(), pid: process.pid, ...spec }, null, 2)
+    );
+  } catch (_) {}
+}
+
+function writeCliError(phase, err) {
+  try {
+    ensureSpoolDir();
+    const msg = err && err.message ? err.message : String(err);
+    const stack = err && err.stack ? err.stack : null;
+    fs.writeFileSync(
+      path.join(spoolDir(), '.bootstrap-error.json'),
+      JSON.stringify({ ts: new Date().toISOString(), pid: process.pid, error_phase: phase, error_message: msg, stack }, null, 2)
+    );
+  } catch (_) {}
+}
+
 (async () => {
   const args = process.argv.slice(2);
 
@@ -21,28 +55,54 @@ Usage:
     process.exit(0);
   }
 
+  ensureSpoolDir();
+  writeCliStatus({ phase: 'starting', args });
+
+  let bootstrapResult;
   try {
-    const result = await ensureReady();
-    if (!result.ok) {
-      console.error('Bootstrap failed:', result.error);
-      process.exit(1);
-    }
-
-    const daemon = startSpoolDaemon();
-    if (!daemon.ok) {
-      console.error('Daemon start failed:', daemon.error);
-      process.exit(1);
-    }
-
-    console.log(JSON.stringify({
-      ok: true,
-      binary: result.binaryPath,
-      daemon: daemon,
-      message: 'plugkit ready, spool watcher running'
-    }));
-    process.exit(0);
+    bootstrapResult = await ensureReady();
+  } catch (err) {
+    writeCliError('ensure-ready', err);
+    console.error('Bootstrap failed:', err.message);
+    process.exit(1);
+  }
+
+  if (!bootstrapResult || !bootstrapResult.ok) {
+    const errMsg = (bootstrapResult && bootstrapResult.error) || 'ensureReady returned non-ok';
+    writeCliError('ensure-ready', new Error(errMsg));
+    console.error('Bootstrap failed:', errMsg);
+    process.exit(1);
+  }
+
+  writeCliStatus({ phase: 'bootstrapped', version: bootstrapResult.version, binary: bootstrapResult.binaryPath });
+
+  let daemon;
+  try {
+    daemon = startSpoolDaemon();
   } catch (err) {
-    console.error('gm-plugkit failed:', err.message);
+    writeCliError('start-daemon', err);
+    console.error('Daemon start failed:', err.message);
     process.exit(1);
   }
-})();
+
+  if (!daemon || !daemon.ok) {
+    const errMsg = (daemon && daemon.error) || 'startSpoolDaemon returned non-ok';
+    writeCliError('start-daemon', new Error(errMsg));
+    console.error('Daemon start failed:', errMsg);
+    process.exit(1);
+  }
+
+  writeCliStatus({ phase: 'ready', version: bootstrapResult.version, daemon_pid: daemon.pid, log: daemon.logPath });
+
+  console.log(JSON.stringify({
+    ok: true,
+    binary: bootstrapResult.binaryPath,
+    daemon,
+    message: 'plugkit ready, spool watcher running'
+  }));
+  process.exit(0);
+})().catch((err) => {
+  writeCliError('uncaught', err);
+  console.error('gm-plugkit failed:', err && err.message ? err.message : err);
+  process.exit(1);
+});

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1147",
+  "version": "2.0.1149",
   "description": "Spool-dispatch orchestration engine with unified state machine, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",
@@ -17,5 +17,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "plugkitVersion": "0.1.413"
+  "plugkitVersion": "0.1.414"
 }

package/lib/spool-dispatch.js

@@ -1,6 +1,33 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { spawnSync } = require('child_process');
+
+function isWorktreeDirty(cwd) {
+  try {
+    const r = spawnSync('git', ['status', '--porcelain'], {
+      cwd: cwd || process.cwd(), encoding: 'utf8', timeout: 1500, windowsHide: true
+    });
+    if (r.status !== 0) return { dirty: false, files: [], available: false };
+    const lines = r.stdout.split('\n').filter(l => l.length > 0);
+    return { dirty: lines.length > 0, files: lines, available: true };
+  } catch (_) {
+    return { dirty: false, files: [], available: false };
+  }
+}
+
+function hasUnpushedCommits(cwd) {
+  try {
+    const r = spawnSync('git', ['log', '@{u}..HEAD', '--oneline'], {
+      cwd: cwd || process.cwd(), encoding: 'utf8', timeout: 1500, windowsHide: true
+    });
+    if (r.status !== 0) return { unpushed: false, count: 0, available: false };
+    const lines = r.stdout.split('\n').filter(l => l.length > 0);
+    return { unpushed: lines.length > 0, count: lines.length, available: true };
+  } catch (_) {
+    return { unpushed: false, count: 0, available: false };
+  }
+}
 
 async function dispatchSpool(cmd, lang, body, timeoutMs, sessionId) {
   const taskId = `${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
@@ -73,12 +100,45 @@ async function pollForCompletion(jsonFile, timeoutMs, taskId) {
 }
 
 function checkDispatchGates(sessionId, operation) {
-  const gm = path.join(process.cwd(), '.gm');
+  const cwd = process.cwd();
+  const gm = path.join(cwd, '.gm');
   const prdPath = path.join(gm, 'prd.yml');
   const mutsPath = path.join(gm, 'mutables.yml');
   const needsGmPath = path.join(gm, 'needs-gm');
   const gmFiredPath = path.join(gm, `gm-fired-${sessionId}`);
 
+  if (['stop', 'complete'].includes(operation)) {
+    const residuals = [];
+    if (fs.existsSync(prdPath)) {
+      try {
+        const content = fs.readFileSync(prdPath, 'utf8');
+        if (content.includes('status: pending') || content.includes('status: in_progress')) {
+          residuals.push('PRD has open items — resolve or name-and-stop before declaring done');
+        }
+      } catch (_) {}
+    }
+    if (fs.existsSync(mutsPath)) {
+      try {
+        const content = fs.readFileSync(mutsPath, 'utf8');
+        if (content.includes('status: unknown')) {
+          residuals.push('unresolved mutables present — resolve with witness_evidence before declaring done');
+        }
+      } catch (_) {}
+    }
+    const dirty = isWorktreeDirty(cwd);
+    if (dirty.available && dirty.dirty) {
+      residuals.push(`worktree dirty (${dirty.files.length} file${dirty.files.length === 1 ? '' : 's'}) — commit and push before declaring done`);
+    }
+    const unpushed = hasUnpushedCommits(cwd);
+    if (unpushed.available && unpushed.unpushed) {
+      residuals.push(`${unpushed.count} unpushed commit${unpushed.count === 1 ? '' : 's'} — push to remote before declaring done`);
+    }
+    if (residuals.length > 0) {
+      return { allowed: false, reason: `stop-gate residuals: ${residuals.join('; ')}`, residuals };
+    }
+    return { allowed: true };
+  }
+
   if (!['write', 'edit', 'git'].includes(operation)) return { allowed: true };
 
   if (fs.existsSync(prdPath) && fs.existsSync(needsGmPath) && !fs.existsSync(gmFiredPath)) {
@@ -97,4 +157,4 @@ function checkDispatchGates(sessionId, operation) {
   return { allowed: true };
 }
 
-module.exports = { dispatchSpool, checkDispatchGates };
+module.exports = { dispatchSpool, checkDispatchGates, isWorktreeDirty, hasUnpushedCommits };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1147",
+  "version": "2.0.1149",
   "description": "Canonical universal harness — AI-native software engineering via skill-driven orchestration; bootstraps plugkit for task execution and session isolation. Install in any AI coding agent host.",
   "author": "AnEntrypoint",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "gm.json"
   ],
   "dependencies": {
-    "gm-plugkit": "^2.0.1147"
+    "gm-plugkit": "^2.0.1149"
   },
   "engines": {
     "node": ">=16.0.0"

package/skills/gm-skill/SKILL.md

@@ -6,6 +6,14 @@ allowed-tools: Skill, Read, Write, Bash(node *), Bash(bun *)
 
 # gm — single entry point
 
+Every turn begins with `instruction`. Write `.gm/exec-spool/in/instruction/<N>.txt` (empty body) and read the response — its `instruction` field is the active phase prose, its `prd_items` is the live work plan, its `mutables_pending` is what blocks the EMIT gate, its `recall_hits` is the prior memory already loaded for you. Follow that prose imperatively until the phase's exit condition is met, then `transition`. The user's request is the authorization; the PRD is the receipt; the chain runs PLAN → EXECUTE → EMIT → VERIFY → COMPLETE without re-asking between phases.
+
+Direct Read/Edit/Bash before the first `instruction` dispatch is the failure mode this skill prevents. If you find yourself reaching for a tool to "just take a quick look", you have already dropped the loop — dispatch `instruction` first, then act on its prose.
+
+Fix on Sight. Every unexpected output, broken neighbor, lockfile drift, suppressed error, or stale generated file surfaced during work becomes a PRD item the same turn and is executed before COMPLETE. Surprise is a new mutable, not noise to absorb. Stubs, mocks, placeholder returns, fixture-only paths, and "always succeeds" code paths are forbidden in shipped material; acceptance is real input through real code into real output, witnessed. Edits to code that runs in a browser require a live `browser` verb witness in the same turn — Browser Witness is non-negotiable.
+
+Before any apparent stop, dispatch `residual-scan`. If it returns work that fits the spirit of the original ask and is reachable from this session, expand the PRD and execute; only residuals genuinely out-of-spirit or out-of-reach are name-and-stop. A turn that ends with uncommitted changes, an open PRD slice, or unresolved mutables has not actually stopped — it has stalled the chain.
+
 The wasm artifact lives at `~/.claude/gm-tools/plugkit.wasm`; the spool watcher runs it. The watcher's own stdout/stderr is appended to `.gm/exec-spool/.watcher.log` — Read it to see plugkit's internal trace, dispatch timings, sweep actions, errors.
 
 ## Boot the spool watcher (first turn only)
@@ -18,7 +26,11 @@ bun x gm-plugkit@latest spool > /dev/null 2>&1 &
 
 If `bun` is not available, fall back to `npx -y gm-plugkit@latest spool > /dev/null 2>&1 &` or to the local wrapper if it's already installed: `node ~/.claude/gm-tools/plugkit-wasm-wrapper.js spool > /dev/null 2>&1 &`. The wrapper has a self-heal: if it detects a `LinkError` or missing wasm at instantiation, it re-runs bootstrap automatically and retries.
 
-Wait 2 seconds, verify `.status.json` is fresh. Then proceed.
+Wait 2 seconds, then verify boot:
+
+- Read `.gm/exec-spool/.cli-status.json` — the launcher writes its phase here (`starting` → `bootstrapped` → `ready`). Present with `phase: "ready"` = good.
+- Read `.gm/exec-spool/.status.json` — the watcher writes its heartbeat here every 5s. Fresh `ts` (within 15s) = watcher alive.
+- If neither file exists or `.cli-status.json` is stuck at an earlier phase, read `.gm/exec-spool/.bootstrap-error.json` — the launcher writes `{error_phase, error_message, stack}` on any failure even when stdout/stderr were redirected to `/dev/null`. Also read `.gm/exec-spool/.watcher.log` for the post-spawn trace. Surface the error to the user; do not retry blindly.
 
 ## Plugkit version updates
 
@@ -80,11 +92,11 @@ The log is rotated at 10MB (older content moves to `.watcher.log.1`).
 
 ## The loop
 
-Dispatch `instruction` with empty body to get current-phase guidance + full state snapshot. Follow the `instruction` prose imperatively. Add PRD items via `prd-add` (JSON body), resolve via `prd-resolve` (id as body). Add mutables via `mutable-add`, resolve via `mutable-resolve` once `witness_evidence` is filled. Every resolve auto-fires `memorize-fire` so the evidence becomes recall-able.
+Add PRD items via `prd-add` (JSON body), resolve via `prd-resolve` (id as body). Add mutables via `mutable-add`, resolve via `mutable-resolve` once `witness_evidence` is filled — narrative resolution is rejected; only file:line, codesearch hit, or exec output snippet counts. Every `mutable-resolve` auto-fires memorize so the witness becomes recall-able next session.
 
 Resolve every entry in `mutables_pending` before transitioning. When the phase's exit condition is met, dispatch `transition` with the next phase name (or empty for auto-advance). Each transition response embeds `recall_hits` automatically — relevant prior memos surface without you asking.
 
-Stop when `next_phase_hint` is null or phase is `COMPLETE`.
+Stop only when `phase` is `COMPLETE` AND `residual-scan` returns empty AND the worktree is clean AND CI is green. Any of those false means the chain has not finished.
 
 ## Orchestrator verbs
 
@@ -100,8 +112,8 @@ Stop when `next_phase_hint` is null or phase is `COMPLETE`.
 
 ### Browser
 
-Dispatch `.gm/exec-spool/in/browser/<N>.txt` with raw JavaScript as the body. The wrapper spawns Chrome (managed profile at `<cwd>/.gm/browser-profile/`) and runs the JS via playwriter. Globals available inside the body: `page` (playwright Page), `snapshot` (accessibility snapshot), `screenshotWithAccessibilityLabels` (screenshot helper), `state` (per-session state object).
+The `browser` verb is the only sanctioned way to drive a live page. Do not reach for any other browser tool, library, or skill — the host owns the managed session and a parallel surface fragments witness state. Dispatch `.gm/exec-spool/in/browser/<N>.txt` with raw JavaScript as the body. The host runs Chrome under a project-scoped profile at `<cwd>/.gm/browser-profile/` (cookies/login persist per project) and exposes the body to four globals: `page` (the live page handle — `await page.goto(...)`, `await page.evaluate(...)`, etc.), `snapshot` (accessibility-tree snapshot), `screenshotWithAccessibilityLabels` (annotated screenshot helper), and `state` (a per-session object that persists across dispatches within the same session).
 
-Special commands (body starts with `session `): `session new`, `session list`, `session close <id>` pass through to playwriter directly.
+Special commands (body starts with `session `): `session new`, `session list`, `session close <id>` manage session lifecycle.
 
-Chrome is detected from system install paths; profile dir is project-scoped so cookies/login persist per project. The wrapper writes the managed gitignore block (which includes `.gm/browser-profile/`) on first launch.
+Required for any edit to code that runs in a browser — Browser Witness is non-negotiable. A `node test.js passes` does not substitute for a live `page.evaluate` asserting the invariant the edit was supposed to change.