gm-skill 2.0.1149 → 2.0.1151

package/README.md

@@ -35,7 +35,7 @@ An earlier generation fanned out fifteen per-platform downstream repos (gm-cc, g
 
 ## Version
 
-`2.0.1149` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` (or any cascading sibling crate) republishes this package.
+`2.0.1151` — 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.414
+0.1.416

package/bin/plugkit.wasm.sha256

@@ -1 +1 @@
-74a7d080de71336c5d7c56a0edd4936c853259a21323c0ab797ce9a3782f5dac  plugkit.wasm
+748ab8b58d5c09a447b13cd880853ddecbe1ad3a49ca7ba52501a49e3a6b92d2  plugkit.wasm

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

@@ -14,6 +14,73 @@ const __dirname = path.dirname(__filename);
 const KV_DIR = path.join(os.homedir(), '.claude', 'gm-tools', 'kv');
 fs.mkdirSync(KV_DIR, { recursive: true });
 
+const GM_LOG_ROOT = process.env.GM_LOG_DIR || path.join(os.homedir(), '.claude', 'gm-log');
+const ORCHESTRATOR_VERBS = new Set(['instruction', 'transition', 'phase-status', 'prd-add', 'prd-resolve', 'prd-list', 'mutable-add', 'mutable-resolve', 'mutable-list', 'memorize-fire', 'residual-scan', 'auto-recall']);
+
+function logEvent(sub, event, fields) {
+  if (process.env.GM_LOG_DISABLE) return;
+  try {
+    const day = new Date().toISOString().slice(0, 10);
+    const dir = path.join(GM_LOG_ROOT, day);
+    fs.mkdirSync(dir, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      sub,
+      event,
+      pid: process.pid,
+      sess: process.env.CLAUDE_SESSION_ID || process.env.GM_SESSION_ID || '',
+      ...fields,
+    });
+    fs.appendFileSync(path.join(dir, `${sub}.jsonl`), line + '\n');
+  } catch (_) {}
+}
+
+function emitOrchestratorEvents(verb, taskBase, resultStr) {
+  if (!ORCHESTRATOR_VERBS.has(verb)) return;
+  let parsed;
+  try { parsed = JSON.parse(resultStr); } catch (_) { return; }
+  if (!parsed || parsed.ok !== true) {
+    logEvent('plugkit', 'orchestrator.error', { verb, task: taskBase, error: parsed && parsed.error ? String(parsed.error) : 'unknown' });
+    return;
+  }
+  const data = parsed.data || {};
+  switch (verb) {
+    case 'transition':
+      logEvent('plugkit', 'phase.transitioned', { task: taskBase, phase: data.phase, next_skill: data.nextSkill, recall_count: Array.isArray(data.recall_hits) ? data.recall_hits.length : 0 });
+      break;
+    case 'instruction':
+      logEvent('plugkit', 'instruction.served', { task: taskBase, phase: data.phase, prd_pending: data.prd_pending_count, mutables_pending: Array.isArray(data.mutables_pending) ? data.mutables_pending.length : 0, next_phase_hint: data.next_phase_hint });
+      break;
+    case 'phase-status':
+      logEvent('plugkit', 'phase.status', { task: taskBase, phase: data.phase, last_skill: data.last_skill });
+      break;
+    case 'prd-add':
+      logEvent('plugkit', 'prd.added', { task: taskBase, id: data.added });
+      break;
+    case 'prd-resolve':
+      logEvent('plugkit', 'prd.resolved', { task: taskBase, id: data.resolved });
+      break;
+    case 'mutable-add':
+      logEvent('plugkit', 'mutable.added', { task: taskBase, id: data.added });
+      break;
+    case 'mutable-resolve':
+      logEvent('plugkit', 'mutable.resolved', { task: taskBase, id: data.resolved, memorize_spool: data.memorize_spool });
+      break;
+    case 'memorize-fire':
+      logEvent('plugkit', 'memorize.fired', { task: taskBase, key: data.key, namespace: data.namespace, bytes: data.bytes });
+      break;
+    case 'residual-scan':
+      if (data.scan === 'fired') logEvent('plugkit', 'residual.fired', { task: taskBase, marker: data.marker });
+      else logEvent('plugkit', 'residual.skipped', { task: taskBase, reason: data.reason });
+      break;
+    case 'auto-recall':
+      logEvent('plugkit', 'auto_recall.hits', { task: taskBase, count: Array.isArray(data.hits) ? data.hits.length : 0 });
+      break;
+    default:
+      break;
+  }
+}
+
 const TMP_DIR = os.tmpdir();
 const BROWSER_PORTS_FILE = path.join(TMP_DIR, 'plugkit-browser-ports.json');
 const BROWSER_SESSIONS_FILE = path.join(TMP_DIR, 'plugkit-browser-sessions.json');
@@ -656,8 +723,10 @@ async function runSpoolWatcher(instance, spoolDir) {
     }
   } catch (e) { console.error(`[plugkit-wasm] wrapper self-install failed: ${e.message}`); }
 
-  console.log(`[plugkit-wasm] plugkit v${resolveVersion(instance)} (wasm)`);
+  const _bootVersion = resolveVersion(instance);
+  console.log(`[plugkit-wasm] plugkit v${_bootVersion} (wasm)`);
   console.log(`[plugkit-wasm] watching ${inDir}`);
+  logEvent('plugkit', 'watcher.boot', { version: _bootVersion, in_dir: inDir, out_dir: outDir, spool_dir: spoolDir });
 
   const PROCESSED_MAX = 10000;
   const processed = new Map();
@@ -692,6 +761,7 @@ async function runSpoolWatcher(instance, spoolDir) {
 
       const t0 = Date.now();
       console.log(`[dispatch] → verb=${verb} task=${taskBase} body=${bodyBytes.length}b`);
+      logEvent('plugkit', 'dispatch.start', { verb, task: taskBase, body_bytes: bodyBytes.length, cwd: process.cwd() });
 
       const verbPtr = instance.exports.plugkit_alloc(verbBytes.length);
       const bodyPtr = instance.exports.plugkit_alloc(bodyBytes.length);
@@ -707,7 +777,10 @@ async function runSpoolWatcher(instance, spoolDir) {
 
       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`);
+      const dur_ms = Date.now() - t0;
+      console.log(`[dispatch] ← verb=${verb} task=${taskBase} ms=${dur_ms} out=${resultStr.length}b`);
+      logEvent('plugkit', 'dispatch.end', { verb, task: taskBase, dur_ms, out_bytes: resultStr.length });
+      emitOrchestratorEvents(verb, taskBase, resultStr);
 
       try { instance.exports.plugkit_free(verbPtr, verbBytes.length); } catch (_) {}
       try { instance.exports.plugkit_free(bodyPtr, bodyBytes.length); } catch (_) {}
@@ -727,6 +800,7 @@ async function runSpoolWatcher(instance, spoolDir) {
       } catch (_) {}
       try { fs.unlinkSync(filePath); } catch (_) {}
       unmarkProcessed(key);
+      logEvent('plugkit', 'dispatch.error', { verb, task: taskBase, error: String(e && e.message || e) });
     }
   };
 
@@ -819,8 +893,14 @@ async function runSpoolWatcher(instance, spoolDir) {
           if (s.mtimeMs < cutoff) { fs.unlinkSync(fp); swept++; }
         } catch (e) { console.error(`[retention] failed to sweep ${entry}: ${e.message}`); }
       }
-      if (swept > 0) console.log(`[retention] swept ${swept} out/ files older than 1h`);
-    } catch (e) { console.error(`[retention] sweep error: ${e.message}`); }
+      if (swept > 0) {
+        console.log(`[retention] swept ${swept} out/ files older than 1h`);
+        logEvent('plugkit', 'sweep.retention', { swept });
+      }
+    } catch (e) {
+      console.error(`[retention] sweep error: ${e.message}`);
+      logEvent('plugkit', 'sweep.retention.error', { error: String(e.message || e) });
+    }
   }, 60_000);
 
   setInterval(() => {
@@ -848,8 +928,14 @@ async function runSpoolWatcher(instance, spoolDir) {
         }
       };
       walk(inDir);
-      if (stale > 0) console.log(`[stale-sweep] failed ${stale} orphaned inputs`);
-    } catch (e) { console.error(`[stale-sweep] sweep error: ${e.message}`); }
+      if (stale > 0) {
+        console.log(`[stale-sweep] failed ${stale} orphaned inputs`);
+        logEvent('plugkit', 'sweep.stale', { stale });
+      }
+    } catch (e) {
+      console.error(`[stale-sweep] sweep error: ${e.message}`);
+      logEvent('plugkit', 'sweep.stale.error', { error: String(e.message || e) });
+    }
   }, 300_000);
 
   const existing = walkDir(inDir);

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1149",
+  "version": "2.0.1151",
   "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.414"
+  "plugkitVersion": "0.1.416"
 }

package/lib/spool-dispatch.js

@@ -3,6 +3,27 @@ const path = require('path');
 const os = require('os');
 const { spawnSync } = require('child_process');
 
+const GM_LOG_ROOT = process.env.GM_LOG_DIR || path.join(os.homedir(), '.claude', 'gm-log');
+
+function logDeviation(event, fields) {
+  if (process.env.GM_LOG_DISABLE) return;
+  try {
+    const day = new Date().toISOString().slice(0, 10);
+    const dir = path.join(GM_LOG_ROOT, day);
+    fs.mkdirSync(dir, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      sub: 'hook',
+      event,
+      pid: process.pid,
+      sess: process.env.CLAUDE_SESSION_ID || process.env.GM_SESSION_ID || '',
+      cwd: process.cwd(),
+      ...fields,
+    });
+    fs.appendFileSync(path.join(dir, 'hook.jsonl'), line + '\n');
+  } catch (_) {}
+}
+
 function isWorktreeDirty(cwd) {
   try {
     const r = spawnSync('git', ['status', '--porcelain'], {
@@ -29,6 +50,33 @@ function hasUnpushedCommits(cwd) {
   }
 }
 
+const TOPLEVEL_DOC_ALLOWLIST = new Set(['AGENTS.md', 'CLAUDE.md', 'README.md', 'SKILLS.md', 'CHANGELOG.md', 'LICENSE', 'LICENSE.md']);
+
+function unsolicitedDocs(cwd) {
+  try {
+    const r = spawnSync('git', ['status', '--porcelain'], {
+      cwd: cwd || process.cwd(), encoding: 'utf8', timeout: 1500, windowsHide: true
+    });
+    if (r.status !== 0) return { count: 0, files: [], available: false };
+    const flagged = [];
+    for (const line of r.stdout.split('\n')) {
+      if (!line.startsWith('?? ')) continue;
+      const rel = line.slice(3).trim();
+      if (!rel) continue;
+      if (!/\.(md|txt)$/i.test(rel)) continue;
+      if (rel.includes('/')) {
+        if (rel.startsWith('node_modules/') || rel.startsWith('target/') || rel.startsWith('.gm/') || rel.startsWith('dist/') || rel.startsWith('build/')) continue;
+      } else {
+        if (TOPLEVEL_DOC_ALLOWLIST.has(rel)) continue;
+      }
+      flagged.push(rel);
+    }
+    return { count: flagged.length, files: flagged, available: true };
+  } catch (_) {
+    return { count: 0, files: [], available: false };
+  }
+}
+
 async function dispatchSpool(cmd, lang, body, timeoutMs, sessionId) {
   const taskId = `${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
   const langDir = lang.match(/^(nodejs|python|bash|typescript|go|rust|c|cpp|java|deno)$/) ? lang : 'nodejs';
@@ -99,7 +147,30 @@ async function pollForCompletion(jsonFile, timeoutMs, taskId) {
   };
 }
 
-function checkDispatchGates(sessionId, operation) {
+function sessionMarkerPath(sessionId, kind) {
+  const cwd = process.cwd();
+  return path.join(cwd, '.gm', 'exec-spool', `.session-${kind}-${sessionId || 'anon'}`);
+}
+
+function hasDispatchedInstruction(sessionId) {
+  try {
+    const outDir = path.join(process.cwd(), '.gm', 'exec-spool', 'out');
+    if (!fs.existsSync(outDir)) return false;
+    for (const f of fs.readdirSync(outDir)) {
+      if (f.startsWith('instruction-')) return true;
+    }
+  } catch (_) {}
+  return fs.existsSync(sessionMarkerPath(sessionId, 'instruction-seen'));
+}
+
+function markInstructionSeen(sessionId) {
+  try {
+    fs.mkdirSync(path.dirname(sessionMarkerPath(sessionId, 'instruction-seen')), { recursive: true });
+    fs.writeFileSync(sessionMarkerPath(sessionId, 'instruction-seen'), String(Date.now()));
+  } catch (_) {}
+}
+
+function checkDispatchGates(sessionId, operation, extra) {
   const cwd = process.cwd();
   const gm = path.join(cwd, '.gm');
   const prdPath = path.join(gm, 'prd.yml');
@@ -133,15 +204,32 @@ function checkDispatchGates(sessionId, operation) {
     if (unpushed.available && unpushed.unpushed) {
       residuals.push(`${unpushed.count} unpushed commit${unpushed.count === 1 ? '' : 's'} — push to remote before declaring done`);
     }
+    const docs = unsolicitedDocs(cwd);
+    if (docs.available && docs.count > 0) {
+      residuals.push(`${docs.count} unsolicited doc${docs.count === 1 ? '' : 's'} (${docs.files.slice(0, 3).join(', ')}${docs.files.length > 3 ? ', …' : ''}) — delete or fold into commit/PRD/memorize, do not ship`);
+      for (const f of docs.files) {
+        logDeviation('deviation.unsolicited-doc-created', { file: f, operation });
+      }
+    }
     if (residuals.length > 0) {
+      logDeviation('deviation.gate-deny', { operation, reason: 'stop-gate residuals', residuals });
       return { allowed: false, reason: `stop-gate residuals: ${residuals.join('; ')}`, residuals };
     }
     return { allowed: true };
   }
 
+  if (['write', 'edit'].includes(operation) && !hasDispatchedInstruction(sessionId)) {
+    logDeviation('deviation.write-before-instruction', { operation, sessionId });
+  }
+
+  if (operation === 'mutable-resolve' && extra && (!extra.witness_evidence || String(extra.witness_evidence).trim() === '')) {
+    logDeviation('deviation.mutable-without-evidence', { mutable_id: extra.id || null });
+  }
+
   if (!['write', 'edit', 'git'].includes(operation)) return { allowed: true };
 
   if (fs.existsSync(prdPath) && fs.existsSync(needsGmPath) && !fs.existsSync(gmFiredPath)) {
+    logDeviation('deviation.gate-deny', { operation, reason: 'gm orchestration in progress' });
     return { allowed: false, reason: 'gm orchestration in progress; skills must complete work before tools execute' };
   }
 
@@ -149,6 +237,7 @@ function checkDispatchGates(sessionId, operation) {
     try {
       const content = fs.readFileSync(mutsPath, 'utf8');
       if (content.includes('status: unknown')) {
+        logDeviation('deviation.gate-deny', { operation, reason: 'unresolved mutables' });
         return { allowed: false, reason: 'unresolved mutables block tool execution; resolve all mutables before proceeding' };
       }
     } catch (_) {}
@@ -157,4 +246,4 @@ function checkDispatchGates(sessionId, operation) {
   return { allowed: true };
 }
 
-module.exports = { dispatchSpool, checkDispatchGates, isWorktreeDirty, hasUnpushedCommits };
+module.exports = { dispatchSpool, checkDispatchGates, isWorktreeDirty, hasUnpushedCommits, unsolicitedDocs, logDeviation, markInstructionSeen, hasDispatchedInstruction };

package/package.json

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

package/skills/gm-skill/SKILL.md

@@ -12,6 +12,8 @@ Direct Read/Edit/Bash before the first `instruction` dispatch is the failure mod
 
 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.
 
+Do not create documentation files the user did not ask for. No COMPLETED.md, no SUMMARY.txt, no IMPLEMENTATION_NOTES.md, no START-HERE.md, no *-STATUS.md, no build-output.txt left behind, no new top-level `.md` or `.txt` of any kind. Closure narrative lives in the PRD (which plugkit owns), in `memorize-fire` (which becomes recallable next session), and in the commit message (which `git log` preserves) — those are the only sanctioned destinations. A new doc at project root, in `docs/`, or anywhere else is a residual the next stop-gate will flag.
+
 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.