gm-skill 2.0.1589 → 2.0.1591

package/AGENTS.md

@@ -56,9 +56,9 @@ Record only non-obvious technical caveats that cost multiple runs to discover; r
 
 ## Coding Style
 
-**No comments in code** -- no inline, block, or JSDoc comments anywhere (source, generated output, hooks, scripts).
+**No comments in code** -- no inline, block, or JSDoc comments anywhere (source, generated output, hooks, scripts). `test.js checkNoComments()` is the structural guard (fails on any leading `//` over tracked `.js/.mjs/.cjs`); one sighting spawns the full-tree sweep.
 
-**No UTF-8 BOM in any tracked source file.** A leading `efbbbf` breaks `node` (`SyntaxError: Invalid or unexpected token`) and strict `JSON.parse`; a BOM in `gm-plugkit/bootstrap.js` shipped a `bun x gm-plugkit@latest spool` that was unbootable for every user. Cause is editing JS/JSON with PowerShell's default UTF-16/UTF-8-BOM encoding -- always `-Encoding utf8` (no BOM) or the `Write` tool. `test.js checkNoBom()` is the structural guard (fails on any leading BOM over tracked text exts); one sighting spawns the full-tree sweep. Mechanics in rs-learn (`recall: BOM regression incident`).
+**No UTF-8 BOM in any tracked source file.** A leading `efbbbf` breaks `node` and strict `JSON.parse`; cause is PowerShell's default UTF-16/UTF-8-BOM encoding -- always `-Encoding utf8` (no BOM) or the `Write` tool. `test.js checkNoBom()` is the structural guard; one sighting spawns the full-tree sweep. Incident + mechanics in rs-learn (`recall: BOM regression incident`).
 
 **No graphical symbols; convert to industry-standard text on sight.** Decorative glyphs are forbidden in all output and source: arrows, box/geometric glyphs, stars, filled/hollow dots and bullets, checks/crosses, emojis, any non-ASCII decorative symbol. Convert on sight in the same turn (arrow -> `->`, bullet -> `-`/`*`, check/cross -> `[x]`/`[ ]` or done/todo/pass/fail, status dot -> the word). Tell-tale-AI class: one sighting spawns the full-codebase sweep, never a one-off edit. Exempt: functional code operators (`=>`, `??`, `?.`, comparison/math), frozen changelog/git-log entries, binary stores, intentional icon-font/CSS-content product glyphs. `ccsniff --glyph-discipline` flags decorative glyphs post-hoc (run each audit, like `--git-discipline`/`--search-discipline`).
 

package/bin/bootstrap.js

@@ -114,11 +114,6 @@ function ensureNextStepWiring(cwd) {
   }
 }
 
-// Resolve a bare command name to its actual .exe on Windows. cmd.exe + .cmd
-// shim chains re-enter conhost (visible window flash) even with
-// windowsHide:true on the parent. Spawning the real .exe directly lets
-// CREATE_NO_WINDOW propagate. Falls back to .cmd or the original name when
-// no .exe is found. See [[windows-spawn-cmd-shim-flash]].
 function resolveWindowsExe(cmd) {
   if (process.platform !== 'win32') return cmd;
   try {
@@ -213,13 +208,6 @@ function gmToolsDir() {
   return primary;
 }
 
-// Copy the freshly-resolved plugkit binary + its version+sha manifests to
-// ~/.gm-tools (or ~/.claude/gm-tools for legacy installs) so hooks.json can
-// invoke plugkit directly without going through node. Self-update inside the
-// Rust binary keeps gm-tools fresh from
-// here on. Skipped silently on any error -- the next session-start hook will
-// retry via ensure_tools_current.
-
 function copyWasmToGmTools(wasmPath, wrapperDir, version) {
   const dst = gmToolsDir();
   fs.mkdirSync(dst, { recursive: true });
@@ -584,17 +572,6 @@ function getWasmPath(opts) {
   return null;
 }
 
-// ---------------------------------------------------------------------------
-// Daemon kill on version change.
-//
-// The plugin tarball pins `plugkit.version`. When that pin advances and we
-// install a newer cached binary, any long-running daemon (the runner) holds
-// stale code and serves stale RPCs until killed. We track which version the
-// daemon was last started under via `.daemon-version`; on every wrapper
-// invocation, if the wrapper-pinned version differs, we kill the daemon so
-// the next exec spawns it fresh under the new binary.
-// ---------------------------------------------------------------------------
-
 function daemonVersionSentinel() {
   const root = (() => {
     try { const r = cacheRoot(); ensureDir(r); return r; }

package/bin/gm-validate.js

@@ -226,8 +226,8 @@ async function validateBrowserEmbed() {
   const pw = which('playwriter') || which('playwriter.cmd');
   if (!pw) { v.skipped = true; v.errors.push('playwriter not found'); return v; }
 
-  const tbDir = 'C:/dev/thebird';
-  if (!fs.existsSync(path.join(tbDir, 'docs'))) { v.skipped = true; v.errors.push('thebird docs missing'); return v; }
+  const tbDir = path.resolve(__dirname, '..');
+  if (!fs.existsSync(path.join(tbDir, 'docs'))) { v.skipped = true; v.errors.push('repo docs/ missing -- cannot serve a fixture page'); return v; }
 
   let serveProc = null;
   const port = 3088;
@@ -250,7 +250,7 @@ async function validateBrowserEmbed() {
       ready = true; break;
     } catch (_) { await sleep(500); }
   }
-  if (!ready) { v.errors.push('thebird serve never came up on ' + port); return v; }
+  if (!ready) { v.errors.push('docs serve never came up on ' + port); return v; }
 
   let sessionId = '';
   try {

package/bin/plugkit.js

@@ -38,7 +38,6 @@ function readExpectedSha() {
   return null;
 }
 
-// Returns true if gm-tools WASM matches pinned version by sha. Fast: no network.
 function isReady() {
   const home = process.env.USERPROFILE || process.env.HOME || os.homedir();
   const primaryWasm = path.join(home, '.gm-tools', 'plugkit.wasm');
@@ -51,9 +50,6 @@ function isReady() {
   return actual && actual.toLowerCase() === expected;
 }
 
-// Synchronously run bootstrap.js in a child node. Blocks until install finishes
-// (or fails). Bootstrap itself is cache-aware: re-download only when sha differs
-// from manifest. Wraps stdio:inherit so the user sees progress.
 function ensureReady(silent) {
   if (isReady()) return true;
   const bootstrap = path.join(wrapperDir, 'bootstrap.js');

package/bin/plugkit.version

@@ -1 +1 @@
-0.1.673
+0.1.674

package/bin/plugkit.wasm.sha256

@@ -1 +1 @@
-d98bd5e7040372a6d0965337ebd831597675b66e30bca581456923e483f83a3d  plugkit.wasm
+4b5920d31272fa0371440b50d174ac5688053e9db5d689e412871c30f706a1f4  plugkit.wasm

package/gm-plugkit/instructions/browser.md

@@ -1,6 +1,6 @@
 # BROWSER
 
-## Hard Rule: Browser Witness Mandate (paper section 23)
+## Hard Rule: Browser Witness Mandate
 
 **Every edit to code that runs in a browser requires a live `browser` dispatch in the same turn as the edit.** Client-side surfaces -- `.html`, `.js`, `.jsx`, `.ts`, `.tsx`, `.vue`, `.svelte`, `.mjs`, `.css`, web components, service workers, every asset loaded by `<script>`, every path reached by `import` from a browser-side entry -- must be witnessed by a live `page.evaluate` of the specific invariant the edit establishes. A passing node test, build, `curl` of the HTML, or static-analysis pass witnesses server delivery, not browser behavior, and is non-substitutive. The witness IS the proof; prose is not.
 

package/gm-plugkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.1589",
+  "version": "2.0.1591",
   "description": "Bootstrap and daemon-spawn tool for gm plugkit binary. Downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Includes plugkit-wasm-wrapper for WASM-based spool watching.",
   "main": "index.js",
   "bin": {

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

@@ -2342,8 +2342,6 @@ async function runSpoolWatcher(instance, spoolDir) {
     lastActivityMs = Date.now();
   }
 
-  /* killPidQuiet, purgeProfileLockFiles, gracefulCloseBrowser are module-scope (defined above spool()). */
-
   function teardownAll(reason) {
     try {
       logEvent('plugkit', 'watcher.teardown', { reason, idle_ms: Date.now() - lastActivityMs });

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1589",
+  "version": "2.0.1591",
   "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.673"
+  "plugkitVersion": "0.1.674"
 }

package/lang/ssh.js

@@ -83,7 +83,12 @@ function runSsh(target, cmd, onData) {
     };
 
     const timeout = setTimeout(() => {
-      if (!done) { done = true; try { ssh.end(); } catch (_) {} resolve(out.trimEnd() || '[timeout after 55s]'); }
+      if (!done) {
+        done = true;
+        try { ssh.end(); } catch (_) {}
+        const partial = out.trimEnd();
+        resolve(partial ? `${partial}\n[ssh timed out after 55s; output above is partial]` : '[ssh timed out after 55s; no output]');
+      }
     }, 55000);
 
     ssh.on('ready', () => {

package/lib/browser-spool-handler.js

@@ -46,7 +46,7 @@ async function handleBrowserVerb(body, sessionId) {
     const available = await isBrowserAvailable();
     if (!available) {
       throw new Error(
-        'Browser API unavailable at 127.0.0.1:5000. Ensure rs-exec is running with browser support enabled.'
+        'Browser unavailable: the plugkit health probe did not respond. Check the watcher is alive (.gm/exec-spool/.status.json ts within 15s); if dead, boot it with `bun x gm-plugkit@latest spool`.'
       );
     }
 

package/lib/skill-bootstrap.js

@@ -373,13 +373,13 @@ function findPlugkitWasmPids() {
   try {
     if (process.platform === 'win32') {
       const ps = "Get-CimInstance Win32_Process -Filter \"Name='bun.exe' OR Name='node.exe'\" | Where-Object { $_.CommandLine -match 'plugkit-wasm-wrapper' } | Select-Object -ExpandProperty ProcessId";
-      const output = execFileSync('powershell', ['-NoProfile', '-Command', ps], { encoding: 'utf8', windowsHide: true });
+      const output = execFileSync('powershell', ['-NoProfile', '-Command', ps], { encoding: 'utf8', windowsHide: true, timeout: 3000 });
       for (const line of output.split(/\r?\n/)) {
         const trimmed = line.trim();
         if (/^\d+$/.test(trimmed)) pids.push(trimmed);
       }
     } else {
-      const output = execSync("ps -eo pid,args", { encoding: 'utf8' });
+      const output = execSync("ps -eo pid,args", { encoding: 'utf8', timeout: 3000 });
       const lines = output.split('\n').filter(Boolean);
       for (const line of lines) {
         if (!line.includes('plugkit-wasm-wrapper')) continue;
@@ -722,10 +722,14 @@ async function bootstrapPlugkit(sessionId, options) {
     if (forceLatest) {
       const latest = await getLatestRemoteVersion();
       if (latest && latest.version) {
-        targetVersion = latest.version;
-        expectedHash = latest.sha || expectedHash;
-        if (latest.version !== manifest.version) {
+        if (latest.version === manifest.version) {
+          expectedHash = latest.sha || expectedHash;
+        } else if (latest.sha) {
+          targetVersion = latest.version;
+          expectedHash = latest.sha;
           emitBootstrapEvent('info', 'forceLatest: using newer remote version', { latest: latest.version, manifest: manifest.version });
+        } else {
+          emitBootstrapEvent('warn', 'forceLatest: no sha for newer version; staying on pinned manifest version', { latest: latest.version, manifest: manifest.version });
         }
       }
     }

package/lib/spool-dispatch.js

@@ -173,19 +173,22 @@ function unsolicitedDocs(cwd) {
   }
 }
 
+function yamlStatusValues(content) {
+  const values = [];
+  for (const raw of String(content).split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '');
+    const m = line.match(/^\s*(?:-\s*)?status\s*:\s*([A-Za-z0-9_-]+)\s*$/);
+    if (m) values.push(m[1]);
+  }
+  return values;
+}
+
 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'));
 }
 
@@ -318,16 +321,18 @@ function checkDispatchGates(sessionId, operation, extra) {
     const residuals = [];
     if (fs.existsSync(prdPath)) {
       try {
-        const content = fs.readFileSync(prdPath, 'utf8');
-        if (content.includes('status: pending') || content.includes('status: in_progress')) {
+        const statuses = yamlStatusValues(fs.readFileSync(prdPath, 'utf8'));
+        if (statuses.includes('pending') || statuses.includes('in_progress')) {
           residuals.push('PRD has open items -- resolve or name-and-stop before declaring done');
         }
-      } catch (_) {}
+      } catch (e) {
+        residuals.push(`prd.yml unreadable (${e.message}) -- cannot verify PRD state`);
+      }
     }
     if (fs.existsSync(mutsPath)) {
       try {
-        const content = fs.readFileSync(mutsPath, 'utf8');
-        if (content.includes('status: unknown')) {
+        const statuses = yamlStatusValues(fs.readFileSync(mutsPath, 'utf8'));
+        if (statuses.includes('unknown')) {
           residuals.push('unresolved mutables present -- resolve with witness_evidence before declaring done');
         }
       } catch (e) {
@@ -353,7 +358,7 @@ function checkDispatchGates(sessionId, operation, extra) {
     if (browserEdits.length > 0 && !isBrowserWitnessed(cwd)) {
       const files = browserEdits.map(e => e.file);
       const shown = files.slice(0, 5).join(', ') + (files.length > 5 ? `, +${files.length - 5} more` : '');
-      residuals.push(`Browser Witness required: you edited ${shown} without dispatching the browser verb to witness the change in a live page. Per paper section 23 this is non-negotiable. Either dispatch browser to verify the edit works in-browser, or revert the changes.`);
+      residuals.push(`Browser Witness required: you edited ${shown} without dispatching the browser verb to witness the change in a live page. This is non-negotiable. Either dispatch browser to verify the edit works in-browser, or revert the changes.`);
       logDeviation('deviation.browser-witness-missing', { files, operation });
     } else if (browserEdits.length > 0 && isBrowserWitnessed(cwd)) {
       const witness = readBrowserWitness(cwd) || {};
@@ -413,7 +418,7 @@ function checkDispatchGates(sessionId, operation, extra) {
       logDeviation('deviation.commit-message-defer', { marker, operation });
       return {
         allowed: false,
-        reason: `commit message rejected: deferral phrase '${marker}' detected. Per paper section 22 Fix on Sight, defer markers are forced closure. Either inline-fix and re-witness, or split the deferred work as a separate PRD item with blockedBy: [external] before committing. Rewrite the commit message and retry.`,
+        reason: `commit message rejected: deferral phrase '${marker}' detected. Defer markers force closure: either inline-fix and re-witness, or split the deferred work as a separate PRD item with blockedBy: [external] before committing. Rewrite the commit message and retry.`,
       };
     }
   }

package/lib/spool.js

@@ -13,7 +13,10 @@ function generateTaskId() {
 
 function validateLang(lang) {
   const valid = ['nodejs', 'python', 'bash', 'typescript', 'go', 'rust', 'c', 'cpp', 'java', 'deno'];
-  return valid.includes(lang) ? lang : 'nodejs';
+  if (!valid.includes(lang)) {
+    throw new Error(`unknown lang '${lang}'; valid: ${valid.join(', ')}`);
+  }
+  return lang;
 }
 
 function getExtForLang(lang) {
@@ -33,8 +36,10 @@ function getExtForLang(lang) {
 }
 
 function validateVerb(verb) {
-  const valid = ['codesearch', 'recall', 'memorize', 'wait', 'sleep', 'status', 'close', 'browser', 'runner', 'type', 'kill-port', 'forget', 'feedback', 'learn-status', 'learn-debug', 'learn-build', 'discipline', 'pause', 'health'];
-  return valid.includes(verb) ? verb : 'status';
+  if (typeof verb !== 'string' || !/^[a-z][a-z0-9_-]*$/.test(verb)) {
+    throw new Error(`invalid verb '${verb}'; expected a kebab/snake-case identifier`);
+  }
+  return verb;
 }
 
 function writeSpool(body, lang = 'nodejs', options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1589",
+  "version": "2.0.1591",
   "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",

package/skills/gm-skill/index.js

@@ -7,15 +7,4 @@ function loadCanonicalSkill() {
   return fs.readFileSync(SKILL_MD_PATH, 'utf-8');
 }
 
-function renderPlatformSkill(platformName) {
-  return `---
-name: gm-${platformName}
-description: AI-native software engineering via skill-driven orchestration on ${platformName}; bootstraps plugkit for task execution and session isolation
-allowed-tools: Skill
----
-
-See [gm-skill](../gm-skill/SKILL.md). All platforms share the same plugkit dispatch surface.
-`;
-}
-
-module.exports = { loadCanonicalSkill, renderPlatformSkill, SKILL_MD_PATH };
+module.exports = { loadCanonicalSkill, SKILL_MD_PATH };