gm-skill 2.0.1116 → 2.0.1117

package/README.md

@@ -28,7 +28,7 @@ npx gm-skill-bootstrap
 
 ## Version
 
-`2.0.1116` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` republishes this package alongside all 15 platform packages.
+`2.0.1117` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` republishes this package alongside all 15 platform packages.
 
 ## Source of truth
 

package/gm-plugkit/plugkit-wasm-wrapper.js

@@ -660,10 +660,14 @@ async function runSpoolWatcher(instance, spoolDir) {
       const dir = path.dirname(relPath);
       const verb = dir === '.' ? path.basename(filePath, path.extname(filePath)) : dir;
       const body = content.trim() || '{}';
+      const taskBase = path.basename(filePath, path.extname(filePath));
 
       const verbBytes = new TextEncoder().encode(verb);
       const bodyBytes = new TextEncoder().encode(body);
 
+      const t0 = Date.now();
+      console.log(`[dispatch] → verb=${verb} task=${taskBase} body=${bodyBytes.length}b`);
+
       const verbPtr = instance.exports.plugkit_alloc(verbBytes.length);
       const bodyPtr = instance.exports.plugkit_alloc(bodyBytes.length);
       new Uint8Array(instance.exports.memory.buffer, verbPtr, verbBytes.length).set(verbBytes);
@@ -676,9 +680,9 @@ async function runSpoolWatcher(instance, spoolDir) {
       const resultBytes = new Uint8Array(instance.exports.memory.buffer, ptr, len);
       const resultStr = new TextDecoder().decode(resultBytes);
 
-      const taskBase = path.basename(filePath, path.extname(filePath));
       const outName = dir === '.' ? `${taskBase}.json` : `${verb}-${taskBase}.json`;
       fs.writeFileSync(path.join(outDir, outName), resultStr);
+      console.log(`[dispatch] ← verb=${verb} task=${taskBase} ms=${Date.now() - t0} out=${resultStr.length}b`);
 
       try { instance.exports.plugkit_free(verbPtr, verbBytes.length); } catch (_) {}
       try { instance.exports.plugkit_free(bodyPtr, bodyBytes.length); } catch (_) {}
@@ -742,19 +746,22 @@ async function runSpoolWatcher(instance, spoolDir) {
   setInterval(() => {
     try {
       const cutoff = Date.now() - 3600_000;
+      let swept = 0;
       for (const entry of fs.readdirSync(outDir)) {
         try {
           const fp = path.join(outDir, entry);
           const s = fs.statSync(fp);
-          if (s.mtimeMs < cutoff) fs.unlinkSync(fp);
-        } catch (_) {}
+          if (s.mtimeMs < cutoff) { fs.unlinkSync(fp); swept++; }
+        } catch (e) { console.error(`[retention] failed to sweep ${entry}: ${e.message}`); }
       }
-    } catch (_) {}
+      if (swept > 0) console.log(`[retention] swept ${swept} out/ files older than 1h`);
+    } catch (e) { console.error(`[retention] sweep error: ${e.message}`); }
   }, 60_000);
 
   setInterval(() => {
     try {
       const cutoff = Date.now() - 600_000;
+      let stale = 0;
       const walk = (dir) => {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
           const fp = path.join(dir, entry.name);
@@ -768,14 +775,16 @@ async function runSpoolWatcher(instance, spoolDir) {
               const outName = verbDir === '.' ? `${base}.json` : `${verbDir}-${base}.json`;
               try {
                 fs.writeFileSync(path.join(outDir, outName), JSON.stringify({ ok: false, error: 'stale input — never dispatched or watcher crash mid-flight' }));
-              } catch (_) {}
-              try { fs.unlinkSync(fp); } catch (_) {}
+              } catch (e) { console.error(`[stale-sweep] failed to write error for ${rel}: ${e.message}`); }
+              try { fs.unlinkSync(fp); stale++; } catch (e) { console.error(`[stale-sweep] failed to unlink ${rel}: ${e.message}`); }
+              console.error(`[stale-sweep] auto-failed ${rel} (age >${600}s)`);
             }
           }
         }
       };
       walk(inDir);
-    } catch (_) {}
+      if (stale > 0) console.log(`[stale-sweep] failed ${stale} orphaned inputs`);
+    } catch (e) { console.error(`[stale-sweep] sweep error: ${e.message}`); }
   }, 300_000);
 
   const existing = walkDir(inDir);

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1116",
+  "version": "2.0.1117",
   "description": "Spool-dispatch orchestration engine with unified state machine, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/lib/skill-bootstrap.js

@@ -232,6 +232,24 @@ async function verifyBinaryHealth(filePath) {
   }
 }
 
+function openWatcherLog(projectDir) {
+  const spoolDir = path.join(projectDir, '.gm', 'exec-spool');
+  fs.mkdirSync(spoolDir, { recursive: true });
+  const logPath = path.join(spoolDir, '.watcher.log');
+  try {
+    const stat = fs.statSync(logPath);
+    if (stat.size > 10 * 1024 * 1024) {
+      const rotated = path.join(spoolDir, '.watcher.log.1');
+      try { fs.unlinkSync(rotated); } catch (_) {}
+      fs.renameSync(logPath, rotated);
+    }
+  } catch (_) {}
+  const fd = fs.openSync(logPath, 'a');
+  const header = `\n--- watcher boot ${new Date().toISOString()} pid=${process.pid} ---\n`;
+  try { fs.writeSync(fd, header); } catch (_) {}
+  return fd;
+}
+
 async function spawnPlugkitWatcher(wasmPath) {
   try {
     emitBootstrapEvent('info', 'Spawning plugkit WASM watcher daemon');
@@ -249,18 +267,23 @@ async function spawnPlugkitWatcher(wasmPath) {
       throw new Error(`WASM wrapper not found at ${wrapperPath}`);
     }
 
+    const projectDir = process.cwd();
+    const logFd = openWatcherLog(projectDir);
+
     const runtime = process.platform === 'win32' ? 'bun.exe' : 'bun';
     const proc = spawn(runtime, [wrapperPath, 'spool'], {
       detached: true,
-      stdio: 'ignore',
+      stdio: ['ignore', logFd, logFd],
       windowsHide: true,
-      env: { ...process.env, CLAUDE_PROJECT_DIR: process.cwd() },
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir },
     });
 
+    try { fs.closeSync(logFd); } catch (_) {}
+
     const pid = proc.pid;
     proc.unref();
 
-    emitBootstrapEvent('info', 'Plugkit WASM watcher spawned', { pid });
+    emitBootstrapEvent('info', 'Plugkit WASM watcher spawned', { pid, logPath: path.join(projectDir, '.gm', 'exec-spool', '.watcher.log') });
     return pid;
   } catch (e) {
     emitBootstrapEvent('error', 'Failed to spawn plugkit WASM watcher', { error: e.message });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1116",
+  "version": "2.0.1117",
   "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.1116"
+    "gm-plugkit": "^2.0.1117"
   },
   "engines": {
     "node": ">=16.0.0"

package/skills/gm-skill/SKILL.md

@@ -1,32 +1,86 @@
 ---
 name: gm-skill
-description: AI-native software engineering harness. plugkit serves all instructions, state, guardrails via the spool.
+description: AI-native software engineering harness. plugkit owns all state and serves every instruction via the spool. The agent dispatches verbs; plugkit tracks phase, mutables, PRD, and recall.
 allowed-tools: Skill, Read, Write, Bash(node *), Bash(bun *)
 ---
 
 # gm — single entry point
 
-The wasm artifact lives at `~/.claude/gm-tools/plugkit.wasm`; the spool watcher runs it.
+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)
 
-Check `.gm/exec-spool/.status.json`. If absent or `ts` > 15s old, run:
+Check `.gm/exec-spool/.status.json`. If absent or `ts` > 15s old:
 
 `node ~/.claude/gm-tools/plugkit-wasm-wrapper.js spool > /dev/null 2>&1 &`
 
-Wait 2 seconds, verify `.status.json` is fresh. Then proceed with dispatch.
+Wait 2 seconds, verify `.status.json` is fresh. Then proceed.
 
 ## Dispatch ABI
 
-Write request body to `.gm/exec-spool/in/<verb>/<N>.txt`. Read response from `.gm/exec-spool/out/<verb>-<N>.json` for nested verbs, `.gm/exec-spool/out/<N>.json` for root verbs.
+Write request body to `.gm/exec-spool/in/<verb>/<N>.txt`. Read response from `.gm/exec-spool/out/<verb>-<N>.json` (nested verbs) or `out/<N>.json` (root verbs). Bodies are JSON, raw code, or a single phase name depending on the verb.
+
+## Batch dispatch — never serial round-trips for independent verbs
+
+The watcher processes verbs sequentially internally, but the agent's bottleneck is round-trip latency, not the watcher. **Write N inputs in one message via parallel Write tool calls, then read N outputs in one message via parallel Read calls.** A 5-verb batch is one agent turn, not five.
+
+Example PLAN orient pack — 3 recalls + 3 codesearches in ONE message:
+```
+Write .gm/exec-spool/in/recall/1.txt        body: {"query":"<noun A>"}
+Write .gm/exec-spool/in/recall/2.txt        body: {"query":"<noun B>"}
+Write .gm/exec-spool/in/recall/3.txt        body: {"query":"<noun C>"}
+Write .gm/exec-spool/in/codesearch/1.txt    body: {"query":"<phrase X>"}
+Write .gm/exec-spool/in/codesearch/2.txt    body: {"query":"<phrase Y>"}
+Write .gm/exec-spool/in/codesearch/3.txt    body: {"query":"<phrase Z>"}
+```
+
+Then in the NEXT message, all 6 Reads in parallel.
+
+For dependent verbs (transition after instruction, prd-resolve after work), the agent must serialize — but only at the dependency boundary, not across independent dispatches.
+
+## State lives in plugkit, not in conversation context
+
+Never Read `.gm/prd.yml` or `.gm/mutables.yml` directly. Every `instruction` response carries the data you need:
+
+```
+{
+  phase,               // current phase
+  instruction,         // phase prose (the active discipline)
+  prd_items: [...],    // full PRD items with id, subject, status, fields
+  prd_pending_count,
+  mutables_pending: [{id, claim, witness_method, witness_evidence, status}, ...],
+  recall_hits: [...],  // auto-fired against phase + first pending PRD subject
+  next_phase_hint
+}
+```
+
+## Plugkit observability — read .watcher.log
+
+The watcher writes its own stdout + stderr (plus the wasm cdylib's `println!`/`eprintln!`) to `.gm/exec-spool/.watcher.log`. Useful when:
+
+- A dispatch returned an error you don't understand → tail the log for the stack
+- A verb seems slow → log shows `[dispatch] ← verb=X ms=N`
+- Sweep cleaned up something → log shows `[retention]` or `[stale-sweep]` lines
+- Watcher boot issues → `--- watcher boot ... ---` markers
+
+Read with `offset` to tail:
+```
+Read .gm/exec-spool/.watcher.log offset=<last-known-line>
+```
+
+The log is rotated at 10MB (older content moves to `.watcher.log.1`).
 
 ## The loop
 
-Dispatch `instruction` (empty body for current phase; `phase=<NAME>` line, `{"phase":"<NAME>"}`, or a raw phase name to override). The response carries `{phase, instruction, mutables_pending, prd_pending_count, next_phase_hint}`. Follow the `instruction` prose imperatively — it is the operative guidance for this phase. Resolve every `mutables_pending` entry through `mutable-resolve` before transitioning; the gate will refuse otherwise. When the phase's exit condition is met, dispatch `transition` (body: a phase name from `EXECUTE`/`EMIT`/`VERIFY`/`COMPLETE`, or empty to auto-advance), then re-enter with the new phase. Stop when `next_phase_hint` is null or phase is `COMPLETE`.
+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.
+
+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`.
 
 ## Orchestrator verbs
 
-`instruction`, `transition`, `phase-status`, `mutable-resolve`, `memorize-fire`, `residual-scan`, `auto-recall`.
+`instruction`, `transition`, `phase-status`, `prd-add`, `prd-resolve`, `prd-list`, `mutable-add`, `mutable-resolve`, `mutable-list`, `memorize-fire`, `residual-scan`, `auto-recall`.
 
 ## Host verbs
 
@@ -42,6 +96,4 @@ Dispatch `.gm/exec-spool/in/browser/<N>.txt` with raw JavaScript as the body. Th
 
 Special commands (body starts with `session `): `session new`, `session list`, `session close <id>` pass through to playwriter directly.
 
-Chrome is detected from system install paths; profile dir is project-scoped so cookies/login persist per project. Add `.plugkit-browser-profile/` to your repo's `.gitignore` — the wrapper does this automatically.
-
-Plugkit serves what prior skills (`gm:planning`, `gm:gm-execute`) used to serve, on demand, per phase. There is no other skill.
+Chrome is detected from system install paths; profile dir is project-scoped so cookies/login persist per project. The wrapper auto-adds `.plugkit-browser-profile/` to `.gitignore`.