gm-skill 2.0.2073 → 2.0.2075

package/AGENTS.md

@@ -67,7 +67,9 @@ Record only non-obvious multi-run-cost caveats; prune stale; never document the
 
 **No test files or test suites of any kind, ever -- manual troubleshooting and debugging through real code execution is the only verification surface.** No `*.test.*`/`*.spec.*` files, no `test/`/`__tests__/`/`spec/` directories, no jest/mocha/vitest/pytest/unittest/junit or any assertion/mocking library, in this repo or any repo gm drives work in -- and no standing root-level test file either. Verification is running the real thing and reading the real output -- `exec_js`/`browser` witnessing a live invariant, same turn as the code it checks. A PRD row for "add validation"/"handle edge case X" is closed by exercising that case live, never by authoring a test case that exercises it later. Rationale + measured impact on coder throughput: the recall store (`recall: synthetic-test-file coder-performance regression`). Full phase-level enforcement (PLAN's edge-case rows, EXECUTE's hard rule, VERIFY's adversarial corner-case sweep) lives in rs-plugkit's served `instruction` prose, not duplicated here.
 
-**No comments in code** -- no inline, block, or JSDoc comments anywhere (source, generated output, hooks, scripts). Checked manually on sight (leading `//` over tracked `.js/.mjs/.cjs`); one sighting spawns the full-tree sweep.
+**Self-explanatory code replaces the comment; the comment is never written in the first place.** A name, a function boundary, an extracted variable, or a small type IS the explanation -- prefer renaming/restructuring over annotating every single time a comment urge appears. No inline, block, doc (`///`, `/**`, `#`, JSDoc), or rationale comments anywhere (source, generated output, hooks, scripts, Rust, JS/TS, shell, YAML). A multi-line or paragraph-long comment is the same violation at higher volume, not a lesser one -- it is not exempted by explaining a "why"; that urge to explain is itself the signal that a name or structure is doing too little work, so restructure instead of narrating around the gap. If a rule/tradeoff genuinely needs recording for future sessions (not this code), it goes in AGENTS.md or the recall store, never inline next to the code.
+
+**A comment encountered anywhere -- pre-existing, another session's, a dependency's vendored copy inside this repo's own tracked tree -- is converted to self-explanatory code the moment it's seen, same turn, not left for a later cleanup pass.** Read the comment, understand what it was compensating for (an unclear name, an un-extracted step, an unstated invariant), fix that root cause so the comment's content becomes redundant, then delete the comment. "Already there, not part of this task" is not an exemption -- the same one-sighting-spawns-a-sweep discipline that governs every other tell-tale-AI class in this section applies here: a comment survives only until the next file touching it is opened. Checked manually on sight across every tracked source extension (`.rs`, `.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.sh`, `.ps1`); one sighting spawns the full-tree sweep.
 
 **No UTF-8 BOM in any tracked source file** -- always `-Encoding utf8` (no BOM) or the `Write` tool; PowerShell defaults betray this. Checked manually on sight; one sighting spawns the full-tree sweep. Cause + breakage mechanics in the recall store (`recall: BOM regression incident`).
 
@@ -105,7 +107,7 @@ A task that reduces to read/investigate/report, or a change confined to files th
 
 **Disciplines are isolated knowledge stores**, tracked, `@<name>` sigil-scoped, enabled list at `.gm/disciplines/enabled.txt` (one name per line; `discipline_note.rs::active_policies()` auto-surfaces each enabled discipline's `.gm/disciplines/<name>/policy.md` on every `instruction`). Detail: the recall store (`recall: gm disciplines mechanics`).
 
-**Every runtime config surface, indexed**: `.gm/instructions/<key>.md` + `.gm/instructions/source.json` (prose vendoring, see above); `.gm/instructions/fsm/graph.json` (phase-graph override, write path is the `fsm-vendor` verb, see SKILL.md); `.gm/instructions/hooks/<name>.js` (jit-hook: a real `exec_js` script the orchestrator runs automatically at a gate's evaluation, wired in via a `GateDef`'s `hook` field + `hook_mode` -- `"hook-only"` replaces the compiled predicate, `"both"` requires both, default `"predicate-only"` ignores the hook; an explicit `return true` passes, anything else -- `false`, a thrown error, non-boolean, missing `return`, missing/unreadable file -- fails CLOSED); `.gm/browser-config.json` (`BrowserConfig::load`, per-project -- `cdp_poll_timeout_ms` default 1000, `cdp_poll_interval_ms` default 250, `chrome_ready_deadline_ms` default 30000, `eval_timeout_grace_ms` default 6000, `headless` default false, `session_idle_timeout_ms` default 1800000); `.gm/daemon-project-config.json` (`gm_concurrency_limit`, per-project fairness cap on the shared pool); `~/.agentplug/daemon-config.json` (`DaemonConfig::load`, machine-wide daemon lifecycle timing, including the `side_plugin_concurrency` pool-size knob for the shared bert/treesitter/libsql instances); `.gm/disciplines/enabled.txt` + `.gm/disciplines/<name>/policy.md` (above); `AGENTPLUG_NO_DAEMON`/`CLAUDE_PROJECT_DIR`/`GM_PLUGKIT_SKIP_SELF_STALE_CHECK` (env toggles, SKILL.md documents the third). Daemon-scoped fields (`daemon-project-config.json`, `~/.agentplug/daemon-config.json`) fully detailed in `.gm/daemon-config-reference.md`; this line is the top-level index into that doc and the others.
+**Every runtime config surface, indexed**: `.gm/instructions/<key>.md`+`source.json` (prose vendoring, see above), `.gm/instructions/fsm/graph.json` (phase-graph override via `fsm-vendor`), `.gm/instructions/hooks/<name>.js` (jit-hook, fails closed), `.gm/browser-config.json`, `.gm/daemon-project-config.json`, `~/.agentplug/daemon-config.json`, `.gm/disciplines/enabled.txt`, env toggles (`AGENTPLUG_NO_DAEMON`/`CLAUDE_PROJECT_DIR`/`GM_PLUGKIT_SKIP_SELF_STALE_CHECK`). Field-level detail: `.gm/daemon-config-reference.md` and the recall store (`recall: gm runtime config surface field defaults`).
 
 **Nothing fake in source the user runs**: stub/mock/placeholder-return/fixture-only-path/demo-mode-short-circuit/"TODO: implement" forbidden in shipped code. Scaffolds/shims permitted only delegating to real behavior (upstream API, subprocess, disk); check for an existing library before adding a shim. Detection = behavioral: always-succeeds, input-invariant, or type-signature-satisfying short-circuit = stub. Acceptance = real input through real code into real output, witnessed. `Mock*`/`Fake*`/`Stub*` names checked at VERIFY explicitly, not left prose-only (`recall: nevil false-completion mock-network incident`). A row marked `completed` by documenting it (a README "Future Optimizations" section, a design note) instead of implementing it is the same violation -- `prd-resolve` structurally refuses two PRD rows sharing byte-identical `witness_evidence` text (`deviation.prd-resolve-duplicate-witness`), the copy-paste tell of rubber-stamped completion.
 

package/gm-plugkit/bootstrap.js

@@ -28,13 +28,15 @@ const {
   killPid,
   killSpoolWatcherInCwd,
   proactiveKillForNewInstall,
+  ensureNextStepWiring: ensureNextStepWiringShared,
 } = shared;
 
-// ensureNextStepWiring here is intentionally NOT imported from
-// bootstrap-shared -- this file's version does strictly more (CLAUDE.md
-// prepend, AGENTS.md append, managed .npmignore block) than bin/bootstrap.js's
-// leaner one, so it is genuinely-different logic, not accidental drift, and
-// stays local to this file.
+// This file's own ensureNextStepWiring below delegates the shared prefix
+// (seed next-step.md, prepend CLAUDE.md, append AGENTS.md) to
+// bootstrap-shared's ensureNextStepWiringShared, then adds strictly more
+// (a managed .npmignore block) that bootstrap-shared's leaner version does
+// not need -- genuinely-different logic on top of a shared base, not two
+// independent copies of the same first 40 lines.
 
 function resolveWindowsExe(cmd) {
   if (process.platform !== 'win32') return cmd;
@@ -177,48 +179,7 @@ function ensureInstructionsBundle(cwd) {
 }
 
 function ensureNextStepWiring(cwd) {
-  const changes = [];
-  const gmDir = path.join(cwd, '.gm');
-  try { fs.mkdirSync(gmDir, { recursive: true }); }
-  catch (e) { obsEvent('bootstrap', 'next-step.wiring.target-failed', { target: gmDir, error: e.message }); }
-
-  const nextStepPath = path.join(gmDir, 'next-step.md');
-  const nextStepBody = '# Next step\n\nDispatch the `instruction` verb to plugkit by writing `.gm/exec-spool/in/instruction/<N>.txt` (any unique N) with body `{}` (or `{"prompt":"<user request>"}` on the first dispatch of the turn). Read the response from `.gm/exec-spool/out/<N>.json` and follow the imperative in the `instruction` field.\n\nThis file is auto-rewritten by plugkit on every instruction dispatch.\n';
-  try {
-    if (!fs.existsSync(nextStepPath)) {
-      fs.writeFileSync(nextStepPath, nextStepBody);
-      changes.push('seeded .gm/next-step.md');
-    }
-  } catch (e) { obsEvent('bootstrap', 'next-step.wiring.target-failed', { target: nextStepPath, error: e.message }); }
-
-
-  const claudeMdPath = path.join(cwd, 'CLAUDE.md');
-  try {
-    if (!fs.existsSync(claudeMdPath)) {
-      fs.writeFileSync(claudeMdPath, '@AGENTS.md\n');
-      changes.push('created CLAUDE.md');
-    } else {
-      const cur = fs.readFileSync(claudeMdPath, 'utf8');
-      const hasLine = cur.split(/\r?\n/).some(l => l.trim() === '@AGENTS.md');
-      if (!hasLine) {
-        fs.writeFileSync(claudeMdPath, '@AGENTS.md\n' + cur);
-        changes.push('prepended @AGENTS.md to CLAUDE.md');
-      }
-    }
-  } catch (e) { obsEvent('bootstrap', 'next-step.wiring.target-failed', { target: claudeMdPath, error: e.message }); }
-
-  const agentsMdPath = path.join(cwd, 'AGENTS.md');
-  try {
-    if (fs.existsSync(agentsMdPath)) {
-      const cur = fs.readFileSync(agentsMdPath, 'utf8');
-      const hasLine = cur.split(/\r?\n/).some(l => l.trim() === '@.gm/next-step.md');
-      if (!hasLine) {
-        const sep = cur.endsWith('\n') ? '' : '\n';
-        fs.writeFileSync(agentsMdPath, cur + sep + '\n@.gm/next-step.md\n');
-        changes.push('appended @.gm/next-step.md to AGENTS.md');
-      }
-    }
-  } catch (e) { obsEvent('bootstrap', 'next-step.wiring.target-failed', { target: agentsMdPath, error: e.message }); }
+  const changes = ensureNextStepWiringShared(cwd);
 
   // gm writes its own runtime data into .gm/ in every project it drives; if that
   // project is an npm package, that data must never be published. Maintain a

package/gm-plugkit/gm-process.js

@@ -42,7 +42,7 @@ function sha256OfFileSync(filePath) {
 function pidCommandLineForKillGuard(pid) {
   try {
     if (process.platform === 'win32') {
-      const r = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-WmiObject Win32_Process -Filter "ProcessId=${Number(pid)}").CommandLine`], { encoding: 'utf8', windowsHide: true, timeout: 5000 });
+      const r = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}").CommandLine`], { encoding: 'utf8', windowsHide: true, timeout: 5000 });
       return String((r && r.stdout) || '');
     }
     const r = spawnSync('ps', ['-p', String(pid), '-o', 'args='], { encoding: 'utf8', timeout: 5000 });

package/gm-plugkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.2073",
+  "version": "2.0.2075",
   "description": "Bootstrap and daemon-spawn tool for gm plugkit binary. Downloads the correct platform wasm, verifies SHA256, and launches agentplug-runner (the native wasm host) as the spool watcher daemon.",
   "main": "index.js",
   "bin": {

package/gm.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.2073",
+  "version": "2.0.2075",
   "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/scripts/check-prose-bundle.mjs

@@ -19,9 +19,128 @@ for (const key of KEYS) {
   if (fs.readFileSync(fp, 'utf8').trim() === '') empty.push(key);
 }
 
+let bundleFailed = false;
 if (missing.length || empty.length) {
+  bundleFailed = true;
   if (missing.length) console.error(`prose bundle missing entries: ${missing.join(', ')}`);
   if (empty.length) console.error(`prose bundle empty entries: ${empty.join(', ')}`);
+} else {
+  console.log(`prose bundle complete: ${KEYS.length} keys present and non-empty`);
+}
+
+// Real conformance run: extract every `browser` verb mode-prefix and
+// exec_js `opts.*` field the served prose promises, and check that the
+// implementing native source (agentplug-host, the sole loader per this
+// repo's own architecture) actually references it. Static, not a live
+// dispatch -- this is a "did anyone even write the code" check, not a
+// behavioral one, but that is exactly what catches a "documented, zero
+// implementing code" gap: this check is what found the browser.md
+// screenshot/dom= gap live (agentplug-host/src/browser.rs had zero
+// BrowserMode variant for either, confirmed by grep before this script
+// was written). Runs against the checked-out submodules, so it only fires
+// in CI/local contexts where they're actually populated (a plain `git
+// clone` without --recurse-submodules leaves them empty per README.md's
+// own documented note -- absence there is skipped, not failed, matching
+// this repo's existing plain-clone tolerance).
+const proseSourceDir = path.join(root, 'rs-plugkit', 'crates', 'plugkit-core', 'src', 'orchestrator', 'instructions', 'prose');
+const browserMdPath = path.join(proseSourceDir, 'browser.md');
+const executeMdPath = path.join(proseSourceDir, 'execute.md');
+const browserRsPath = path.join(root, 'agentplug', 'crates', 'agentplug-host', 'src', 'browser.rs');
+const cdpEvalJsPath = path.join(root, 'agentplug', 'crates', 'agentplug-host', 'src', 'cdp_eval.js');
+const execJsRsPath = path.join(root, 'agentplug', 'crates', 'agentplug-host', 'src', 'exec_js.rs');
+
+// Every INDIVIDUAL file this check reads, not just the containing
+// directories -- a submodule can be present but shallow/partial (a
+// degenerate state distinct from "not cloned at all"), and the directory-
+// only check previously crashed with an unhandled ENOENT the moment any one
+// file was individually missing (live-reproduced this session: temporarily
+// removing browser.md alone, with every directory still present, crashed
+// the script instead of skipping gracefully).
+const requiredFiles = [browserMdPath, executeMdPath, browserRsPath, cdpEvalJsPath, execJsRsPath];
+const missingFiles = requiredFiles.filter((p) => !fs.existsSync(p));
+const submodulesPresent = missingFiles.length === 0;
+
+let conformanceFailed = false;
+if (!submodulesPresent) {
+  console.log(`prose-conformance: skipping -- missing file(s) (submodules not populated, or a partial/shallow checkout): ${missingFiles.map((p) => path.relative(root, p)).join(', ')}`);
+} else {
+  const browserMd = fs.readFileSync(path.join(proseSourceDir, 'browser.md'), 'utf8');
+  const browserRs = fs.readFileSync(browserRsPath, 'utf8');
+  const cdpEvalJs = fs.readFileSync(cdpEvalJsPath, 'utf8');
+  const executeMd = fs.readFileSync(path.join(proseSourceDir, 'execute.md'), 'utf8');
+  const execJsRs = fs.readFileSync(execJsRsPath, 'utf8');
+
+  // Extract every backtick-quoted `<word>\n<expression>` / `<word>=` mode
+  // prefix from browser.md's "Body shapes" code block -- the exact syntax
+  // the served prose promises as a real body-shape prefix.
+  const bodyShapesMatch = browserMd.match(/## Body shapes[\s\S]*?```\r?\n([\s\S]*?)```/);
+  const promisedPrefixes = [];
+  if (bodyShapesMatch) {
+    for (const line of bodyShapesMatch[1].split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t) continue;
+      // "session new" / "session list" / "session close <id>" -> session subcommands
+      const sessionMatch = t.match(/^session (\w+)/);
+      if (sessionMatch) { promisedPrefixes.push({ kind: 'session', name: sessionMatch[1] }); continue; }
+      // "<word>\n<expression>" or "<word> interval=...\n<expression>" -> bare mode word
+      const modeMatch = t.match(/^(\w+)(?:\s+\w+=<[^>]+>)*\\n/);
+      if (modeMatch && !['url', 'timeout', 'dom'].includes(modeMatch[1])) { promisedPrefixes.push({ kind: 'mode', name: modeMatch[1] }); continue; }
+      // "<word>=<...>" -> key= prefix (url=, timeout=, dom=)
+      const kvMatch = t.match(/^(\w+)=</);
+      if (kvMatch) { promisedPrefixes.push({ kind: 'kv', name: kvMatch[1] }); continue; }
+    }
+  }
+
+  const conformanceFindings = [];
+  for (const { kind, name } of promisedPrefixes) {
+    // Every promised prefix must appear as a real string literal in either
+    // the Rust prefix-stripping logic or the JS mode-dispatch logic -- one
+    // hit in either is sufficient (some prefixes are parsed Rust-side,
+    // others are only checked JS-side against the `mode` string agentplug
+    // passes through). `session <word>` prefixes are matched as the real
+    // "session <word>" literal parse_session_command uses, not the bare
+    // word alone (which would false-positive-pass on any incidental
+    // substring match).
+    let inRust, inJs;
+    if (kind === 'session') {
+      inRust = browserRs.includes(`"session ${name}`);
+      inJs = false;
+    } else if (kind === 'kv') {
+      inRust = browserRs.includes(`"${name}="`);
+      inJs = cdpEvalJs.includes(`${name}=`);
+    } else {
+      inRust = browserRs.includes(`"${name}\\n"`) || browserRs.includes(`"${name}"`);
+      inJs = cdpEvalJs.includes(`'${name}'`) || cdpEvalJs.includes(`"${name}"`);
+    }
+    if (!inRust && !inJs) {
+      conformanceFindings.push(`browser.md promises ${kind} prefix "${name}" with zero implementing-code reference in browser.rs or cdp_eval.js`);
+    }
+  }
+
+  // exec_js opts.* fields: extract every `opts.<fieldName>` token referenced
+  // in execute.md's prose and check exec_js.rs actually reads it via
+  // opts.get("<fieldName>").
+  const optsFieldRe = /opts\.([a-zA-Z][a-zA-Z0-9]*)/g;
+  const promisedOptsFields = new Set();
+  let m;
+  while ((m = optsFieldRe.exec(executeMd)) !== null) promisedOptsFields.add(m[1]);
+  for (const field of promisedOptsFields) {
+    if (field === 'true' || field === 'false') continue;
+    const needle = `opts.get("${field}")`;
+    if (!execJsRs.includes(needle)) {
+      conformanceFindings.push(`execute.md promises exec_js opts.${field} with no matching opts.get("${field}") in exec_js.rs`);
+    }
+  }
+
+  if (conformanceFindings.length) {
+    conformanceFailed = true;
+    console.error('prose-conformance FAILED -- prose promises capabilities with no confirmed implementing-code reference:');
+    for (const f of conformanceFindings) console.error(`  - ${f}`);
+  } else {
+    console.log(`prose-conformance: ${promisedPrefixes.length} browser mode-prefixes + ${promisedOptsFields.size} exec_js opts fields all have a matching implementing-code reference`);
+  }
+}
+
+if (bundleFailed || conformanceFailed) {
   process.exit(1);
 }
-console.log(`prose bundle complete: ${KEYS.length} keys present and non-empty`);