gm-skill 0.1.2 → 2.0.1081

package/scripts/run-hook.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT}}"
+[ -z "$PLUGIN_ROOT" ] && exit 0
+PLUGKIT="$PLUGIN_ROOT/bin/plugkit"
+[ -f "$PLUGIN_ROOT/bin/plugkit.exe" ] && PLUGKIT="$PLUGIN_ROOT/bin/plugkit.exe"
+[ ! -f "$PLUGKIT" ] && exit 0
+"$PLUGKIT" hook "$1"

package/scripts/watch-cascade.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+
+const REPOS = {
+  'rs-exec':       'AnEntrypoint/rs-exec',
+  'rs-codeinsight':'AnEntrypoint/rs-codeinsight',
+  'rs-search':     'AnEntrypoint/rs-search',
+  'rs-plugkit':    'AnEntrypoint/rs-plugkit',
+  'gm':            'AnEntrypoint/gm',
+  'gm-cc':         'AnEntrypoint/gm-cc',
+};
+
+const POLL_MS = 20000;
+const TIMEOUT_MS = 30 * 60 * 1000;
+
+function gh(args) {
+  const r = spawnSync('gh', args, { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(r.stderr.trim() || `gh ${args.join(' ')} failed`);
+  return r.stdout.trim();
+}
+
+function latestRun(repo) {
+  const out = gh(['run', 'list', '--repo', repo, '--limit', '1', '--json', 'databaseId,status,conclusion,name,headBranch,createdAt']);
+  const rows = JSON.parse(out);
+  return rows[0] || null;
+}
+
+function getGmCcSha() {
+  return gh(['api', 'repos/AnEntrypoint/gm-cc/git/refs/heads/main', '--jq', '.object.sha']);
+}
+
+function getInstalledSha() {
+  const os = require('os');
+  const path = require('path');
+  const fs = require('fs');
+  const base = path.join(os.homedir(), '.claude/plugins/cache/gm-cc/gm');
+  if (!fs.existsSync(base)) return null;
+  const dirs = fs.readdirSync(base).filter(d => /^[0-9a-f]{12,}$/.test(d));
+  dirs.sort((a, b) => {
+    try {
+      const av = JSON.parse(fs.readFileSync(path.join(base, a, 'gm.json'), 'utf8')).version || '0';
+      const bv = JSON.parse(fs.readFileSync(path.join(base, b, 'gm.json'), 'utf8')).version || '0';
+      return bv.localeCompare(av, undefined, { numeric: true });
+    } catch { return 0; }
+  });
+  if (!dirs[0]) return null;
+  const gm = JSON.parse(fs.readFileSync(path.join(base, dirs[0], 'gm.json'), 'utf8'));
+  return { hash: dirs[0], version: gm.version, plugkitVersion: gm.plugkitVersion };
+}
+
+function getPlugkitVersion() {
+  const fs = require('fs');
+  const cargo = 'C:/dev/rs-plugkit/Cargo.toml';
+  if (!fs.existsSync(cargo)) return null;
+  const m = fs.readFileSync(cargo, 'utf8').match(/^version\s*=\s*"([^"]+)"/m);
+  return m ? m[1] : null;
+}
+
+function validate(label, fn) {
+  try {
+    const result = fn();
+    console.log(`  ✓ ${label}: ${result}`);
+    return true;
+  } catch (e) {
+    console.log(`  ✗ ${label}: ${e.message}`);
+    return false;
+  }
+}
+
+async function watchRun(repo, runId, label) {
+  const start = Date.now();
+  while (Date.now() - start < TIMEOUT_MS) {
+    const out = gh(['run', 'view', String(runId), '--repo', repo, '--json', 'status,conclusion']);
+    const { status, conclusion } = JSON.parse(out);
+    process.stdout.write(`\r  ${label}: ${status} ${conclusion || ''}    `);
+    if (status === 'completed') {
+      process.stdout.write('\n');
+      if (conclusion !== 'success') throw new Error(`${label} concluded: ${conclusion}`);
+      return;
+    }
+    await sleep(POLL_MS);
+  }
+  throw new Error(`${label} timed out after ${TIMEOUT_MS / 60000}min`);
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+async function waitForNewRun(repo, label, afterTime, maxWaitMs = 5 * 60 * 1000) {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    const run = latestRun(repo);
+    if (run && new Date(run.createdAt).getTime() > afterTime) return run;
+    process.stdout.write(`\r  Waiting for ${label} run to appear...    `);
+    await sleep(POLL_MS);
+  }
+  process.stdout.write('\n');
+  throw new Error(`No new run appeared in ${repo} within ${maxWaitMs / 60000}min`);
+}
+
+async function main() {
+  const triggerTime = Date.now();
+
+  console.log('\n=== Cascade Watcher ===');
+  console.log('Monitoring full pipeline: rs-{exec,codeinsight,search} → rs-plugkit → gm → gm-cc\n');
+
+  console.log('[1] Baseline');
+  const baseGmCcSha = getGmCcSha();
+  const baseInstalled = getInstalledSha();
+  const basePlugkitVersion = getPlugkitVersion();
+  console.log(`  gm-cc HEAD:       ${baseGmCcSha}`);
+  console.log(`  installed hash:   ${baseInstalled ? baseInstalled.hash : 'unknown'} (gm v${baseInstalled?.version}, plugkit v${baseInstalled?.plugkitVersion})`);
+  console.log(`  local plugkit:    v${basePlugkitVersion}`);
+
+  console.log('\n[2] rs-plugkit Release run');
+  const plugkitRun = await waitForNewRun('AnEntrypoint/rs-plugkit', 'rs-plugkit Release', triggerTime - 10 * 60 * 1000);
+  console.log(`  Run #${plugkitRun.databaseId} "${plugkitRun.name}" on ${plugkitRun.headBranch}`);
+  await watchRun('AnEntrypoint/rs-plugkit', plugkitRun.databaseId, 'rs-plugkit Release');
+
+  console.log('\n[3] Validate rs-plugkit version bumped');
+  validate('rs-plugkit Cargo.toml version', () => {
+    const v = getPlugkitVersion();
+    if (!v) throw new Error('Could not read');
+    return `v${v}`;
+  });
+
+  validate('gm-starter/gm.json plugkitVersion', () => {
+    const fs = require('fs');
+    const p = 'C:/dev/plugforge/gm-starter/gm.json';
+    if (!fs.existsSync(p)) throw new Error('file not found');
+    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return `v${j.plugkitVersion}`;
+  });
+
+  console.log('\n[4] gm Build & Publish run');
+  const afterPlugkit = Date.now();
+  const pfRun = await waitForNewRun('AnEntrypoint/gm', 'Build & Publish Plugins', afterPlugkit - 3 * 60 * 1000);
+  console.log(`  Run #${pfRun.databaseId} "${pfRun.name}" on ${pfRun.headBranch}`);
+  await watchRun('AnEntrypoint/gm', pfRun.databaseId, 'Build & Publish Plugins');
+
+  console.log('\n[5] Validate gm-cc updated');
+  const newGmCcSha = getGmCcSha();
+  validate('gm-cc HEAD changed', () => {
+    if (newGmCcSha === baseGmCcSha) throw new Error(`still ${baseGmCcSha}`);
+    return newGmCcSha;
+  });
+
+  console.log('\n[6] Validate local installed plugin (requires /plugin + /reload-plugins)');
+  const installed = getInstalledSha();
+  validate('installed hash matches gm-cc HEAD prefix', () => {
+    if (!installed) throw new Error('no installed plugin found');
+    if (!newGmCcSha.startsWith(installed.hash)) throw new Error(`installed ${installed.hash} != gm-cc ${newGmCcSha.slice(0, 12)}`);
+    return `${installed.hash} (gm v${installed.version}, plugkit v${installed.plugkitVersion})`;
+  });
+
+  console.log('\n=== Cascade complete ===');
+  console.log(`  gm-cc: ${baseGmCcSha.slice(0, 12)} → ${newGmCcSha.slice(0, 12)}`);
+  if (installed && newGmCcSha.startsWith(installed.hash)) {
+    console.log('  Local plugin is up to date.');
+  } else {
+    console.log('  ⚠  Run /plugin then /reload-plugins to update local cache.');
+  }
+}
+
+main().catch(e => { console.error('\nFATAL:', e.message); process.exit(1); });

package/skills/browser/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: browser
+description: Browser automation via playwriter. Use when user needs to interact with websites, navigate pages, fill forms, click buttons, take screenshots, extract data, test web apps, or automate any browser task.
+allowed-tools: Skill
+---
+
+# Browser automation
+
+Two pathways — never mix in the same spool dispatch.
+
+`exec:browser` runs JS against `page`. Globals available: `page`, `snapshot`, `screenshotWithAccessibilityLabels`, `state`. 15s live window, then backgrounds; output drains automatically on every subsequent plugkit call.
+
+`browser:` prefix is playwriter session management. One command per block.
+
+## Core
+
+Write to `.gm/exec-spool/in/browser/<N>.txt`:
+
+```
+await page.goto('https://example.com')
+await snapshot({ page })
+```
+
+```
+browser:
+playwriter session new --direct
+```
+
+```
+browser:
+playwriter -s 1 -e 'await page.goto("http://example.com")'
+```
+
+Session state persists across `browser:` calls. `-e` arg uses single quotes outside, double inside JS strings.
+
+## Timing
+
+Never `await setTimeout(N)` with N > 10000. Poll instead.
+
+Write to `.gm/exec-spool/in/browser/<N>.txt`:
+
+```
+const start = Date.now()
+while (!state.done && Date.now() - start < 12000) {
+  await new Promise(r => setTimeout(r, 500))
+}
+console.log(state.result)
+```
+
+`Assertion failed: UV_HANDLE_CLOSING` is normal background-on-exit noise; ignore it.
+
+## Patterns
+
+Data extraction — write to `.gm/exec-spool/in/browser/<N>.txt`:
+
+```
+const items = await page.$$eval('.title', els => els.map(e => e.textContent))
+console.log(JSON.stringify(items))
+```
+
+Console monitoring — set listeners first, then poll. Write to `.gm/exec-spool/in/browser/<N>.txt`:
+
+```
+state.logs = []
+page.on('console', msg => state.logs.push({ type: msg.type(), text: msg.text() }))
+```
+
+Then write to `.gm/exec-spool/in/browser/<N+1>.txt`:
+
+```
+console.log(JSON.stringify(state.logs.slice(-20)))
+```
+
+## Constraints
+
+- One playwriter command per `browser:` block
+- `exec:browser` body is plain JS, no shell quoting
+- Browser tasks drain automatically on every plugkit interaction
+- Sessions reap after 5–15 min idle; cleaned up on session end
+- Never write standalone `.mjs`/`.js` Playwright scripts as a fallback — `exec:browser` errors must be debugged through `exec:browser` retries, not by creating test files on disk

package/skills/code-search/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: code-search
+description: Mandatory codebase search workflow. Use whenever you need to find anything in the codebase. Start with two words, iterate by changing or adding words until found.
+---
+
+# Codebase search
+
+`exec:codesearch` is the only codebase search tool. Never use Grep, Glob, Find, Explore, raw `grep`/`rg`/`find` inside `exec:bash`. No fallback.
+
+A `@<discipline>` first-token after the verb scopes the search to that discipline's index; absent the sigil, results fan across default plus enabled disciplines, prefixed by source.
+
+Handles exact symbols, exact strings, file-name fragments, regex-ish patterns, natural-language queries, and PDF pages (cite `path/doc.pdf:<page>`).
+
+Direct-read exceptions: known absolute path → `Read`. Known directory listing → `exec:nodejs` + `fs.readdirSync`.
+
+## Syntax
+
+```
+exec:codesearch
+<two-word query>
+```
+
+## Iteration
+
+Start at exactly two words. No results → change one word. Still none → add a third. Still none → swap the changed word again. Minimum four attempts before concluding absent. Never one word, never a full sentence, never switch tools.
+
+## Examples
+
+```
+exec:codesearch
+session cleanup idle
+```
+
+No results, then:
+
+```
+exec:codesearch
+cleanup sessions timeout
+```
+
+PDF:
+
+```
+exec:codesearch
+usb descriptor endpoint
+```
+
+Returns `docs/usb-spec.pdf:42` — cite the page; `Read` if surrounding text is needed.

package/skills/create-lang-plugin/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: create-lang-plugin
+description: Create a lang/ plugin that wires any CLI tool or language runtime into gm-cc — adds exec:<id> dispatch, optional LSP diagnostics, and optional prompt context injection. Zero hook configuration required.
+---
+
+# Create lang plugin
+
+Single CommonJS file at `<projectDir>/lang/<id>.js`. Auto-discovered — no hook editing.
+
+## Plugin shape
+
+```js
+'use strict';
+module.exports = {
+  id: 'mytool',
+  exec: {
+    match: /^exec:mytool/,
+    run(code, cwd) { /* returns string or Promise<string> */ }
+  },
+  lsp: {
+    check(fileContent, cwd) { /* returns Diagnostic[] */ }
+  },
+  extensions: ['.ext'],
+  context: `=== mytool ===\n...`
+};
+```
+
+`type Diagnostic = { line: number; col: number; severity: 'error'|'warning'; message: string }`
+
+`exec.run` runs in a child process, 30s timeout, async OK. Called when Claude writes `exec:mytool\n<code>`. `lsp.check` is synchronous-only, called per prompt-submit. `context` is injected into every prompt, truncated to 2000 chars.
+
+## Identify the tool
+
+What is the CLI name or npm package? Does it run a single expression (`tool eval`, `tool -e`, HTTP POST) or a file (`tool run <file>`)? What is its lint/check mode and output format? File extensions? Does it require a running server, or does it run headless?
+
+## exec.run patterns
+
+HTTP eval against a running server:
+
+```js
+function httpPost(port, urlPath, body) {
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify(body);
+    const req = http.request(
+      { hostname: '127.0.0.1', port, path: urlPath, method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) } },
+      res => { let raw = ''; res.on('data', c => raw += c); res.on('end', () => resolve(JSON.parse(raw))); }
+    );
+    req.setTimeout(8000, () => { req.destroy(); reject(new Error('timeout')); });
+    req.on('error', reject);
+    req.write(data); req.end();
+  });
+}
+```
+
+File-based, headless:
+
+```js
+function runFile(code, cwd) {
+  const tmp = path.join(os.tmpdir(), `plugin_${Date.now()}.ext`);
+  fs.writeFileSync(tmp, code);
+  try { return execFileSync('mytool', ['run', tmp], { cwd, encoding: 'utf8', timeout: 10000 }); }
+  finally { try { fs.unlinkSync(tmp); } catch (_) {} }
+}
+```
+
+Single-expression detection:
+
+```js
+const isSingleExpr = code => !code.trim().includes('\n') && !/\b(func|def|fn |class|import)\b/.test(code);
+```
+
+## lsp.check
+
+```js
+function check(fileContent, cwd) {
+  const tmp = path.join(os.tmpdir(), `lsp_${Math.random().toString(36).slice(2)}.ext`);
+  try {
+    fs.writeFileSync(tmp, fileContent);
+    const r = spawnSync('mytool', ['check', tmp], { encoding: 'utf8', cwd });
+    return (r.stdout + r.stderr).split('\n').reduce((acc, line) => {
+      const m = line.match(/^.+:(\d+):(\d+):\s+(error|warning):\s+(.+)$/);
+      if (m) acc.push({ line: +m[1], col: +m[2], severity: m[3], message: m[4].trim() });
+      return acc;
+    }, []);
+  } catch (_) { return []; }
+  finally { try { fs.unlinkSync(tmp); } catch (_) {} }
+}
+```
+
+## context
+
+Under 300 chars:
+
+```js
+context: `=== mytool ===\nexec:mytool\n<expression>\n\nRuns via <how>. Use for <when>.`
+```
+
+## Verify
+
+Write to `.gm/exec-spool/in/nodejs/<N>.js`:
+
+```js
+const p = require('/abs/path/lang/mytool.js');
+console.log(p.id, typeof p.exec.run, p.exec.match.toString());
+```
+
+Then test dispatch by writing to `.gm/exec-spool/in/mytool/<N>.txt`:
+
+```
+<simple test expression>
+```
+
+## Constraints
+
+- `exec.run` async OK, 30s timeout
+- `lsp.check` synchronous only — no Promises
+- CommonJS only — no ES module syntax
+- No persistent processes
+- `id` must match filename exactly
+- First match wins — keep `match` specific

package/skills/gm/SKILL.md

@@ -1,63 +1,24 @@
 ---
 name: gm
 description: Orchestrator dispatching PLAN→EXECUTE→EMIT→VERIFY→UPDATE-DOCS skill chain; spool-driven task execution with session isolation
-allowed-tools: Skill
-compatible-platforms:
-  - gm-cc
-  - gm-gc
-  - gm-oc
-  - gm-kilo
-  - gm-codex
-  - gm-copilot-cli
-  - gm-vscode
-  - gm-cursor
-  - gm-zed
-  - gm-jetbrains
+allowed-tools: Skill, Read, Write
 end-to-end: true
 ---
 
-# GM — Orchestrator
+# gm — ORCHESTRATOR
 
-Invoke `planning` immediately. Phases cascade: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS.
+The user's request is the authorization. The PRD is the receipt. Once the user has spoken, the chain runs to COMPLETE without re-asking, without permission gates between phases, without narrating each step as if it were a deliverable. Re-asking "want me to do X?" after the user said "do X" is forced closure dressed as deference.
 
-The user's request is authorization. When scope is unclear, pick the maximum reachable shape and declare it — the user can interrupt. Doubts resolve via witnessed probe or recall, never by asking back except for destructive-irreversible actions uncovered by the PRD.
+When scope exceeds reach, the response is a maximal cover, not a single slice with the rest deferred. Distributed refusal is the same failure dressed as triage. Pick the wider read, declare the read in one line so the user can interrupt mid-chain, execute.
 
-**What ships runs**: no stubs, mocks, placeholder returns, fixture-only paths, or demo-mode short-circuits. Real input through real code into real output. A shim is allowed only when delegating to real upstream behavior.
+The skill chain is one continuous motion: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS. No stop between phases. No approval gates. No summarizing-as-completion. The next skill fires the moment the current skill's transition is named. A skill that ends without invoking its successor has stalled the chain.
 
-**CI is the build**: for Rust crates and the gm publish chain, push triggers CI auto-watch. Green signals authority. Local cargo build is not a witness.
+## Dispatch
 
-**Every issue surfaces this turn**: pre-existing breaks, lint failures, drift, broken deps, stale generated files — all become PRD items and finish before COMPLETE.
+Every operation routes through the spool. Write `.gm/exec-spool/in/<verb>/<N>.txt` with the body. Read `.gm/exec-spool/out/<N>.json`. The orchestrator owns FSM state; the skill reads `nextSkill` and dispatches.
 
-**LLM provider**: acptoapi (127.0.0.1:4800) is the preferred provider when available. rs-plugkit session_start spawns acptoapi daemon and auto-detects ACP agents (opencode, kilo-code, codex, gemini-cli, qwen-code). All downstream platforms (rs-learn, freddie, gm-skill daemon mode) read OPENAI_BASE_URL environment variable and default to 127.0.0.1:4800. Anthropic SDK is fallback only when acptoapi socket is unavailable (CI, headless mode).
+Verbs available here: `phase-status`, `transition`, `mutable-resolve` (auto-fires memorize), `memorize-fire`, plus `recall`, `codesearch`, `memorize`, `health`, all language stems.
 
-**rs-learn failure contract**: exec:memorize, exec:recall, and exec:codesearch failures must be reported explicitly with error details to the user. Fallback to AGENTS.md for memory preservation when socket/network unavailable. Never silently absorb errors because memory preservation requires explicit fallback. This rule applies across all phases (PLAN through UPDATE-DOCS).
+## Transition
 
-**Spool dispatch chain**: write to `.gm/exec-spool/in/<lang>/<N>.<ext>` or `in/<verb>/<N>.txt`. Watcher executes and streams `out/<N>.out` + `out/<N>.err` + `out/<N>.json` metadata. Languages: nodejs, python, bash, typescript, go, rust, c, cpp, java, deno. Verbs: codesearch, recall, memorize, wait, sleep, status, close, browser, runner, type, kill-port, forget, feedback, learn-status, learn-debug, learn-build, discipline, pause, health.
-
-**Session isolation**: SESSION_ID environment variable (or uuid fallback) threads through task dispatch for cleanup scope. rs-exec RPC handlers verify session_id match on all task-scoped operations.
-
-**Code does mechanics; meaning routes through textprocessing skill**: summarize, classify, extract intent, rewrite, translate, semantic dedup, rank, label — all via `Agent(subagent_type='gm:textprocessing', ...)`.
-
-**Recall before fresh execution**: before witnessing unknown via execution, recall first. Hits arrive as weak_prior; empty results confirm fresh unknown.
-
-**Memorize is the back-half of witness**: resolution incomplete until fact lives outside this context window. Fire `Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')` alongside witness, in parallel, never blocking.
-
-**Parallel independent items**: up to 3 `gm:gm` subagents per message for independent PRD items. Serial for dependent items — no re-asking between them.
-
-**Terse response**: fragments OK. `[thing] [action] [reason]. [next step].` Code, commits, PRs use normal prose.
-
-## End-to-End Phase Chaining (Skills-Based Platforms)
-
-When `end-to-end: true` is present in SKILL.md frontmatter, skill output includes structured JSON on stdout (final line):
-
-```json
-{"nextSkill": "gm-execute" | "gm-emit" | "gm-complete" | "update-docs" | null, "context": {PRD and state dict}, "phase": "PLAN" | "EXECUTE" | "EMIT" | "COMPLETE"}
-```
-
-Platform adapters (vscode, cursor, zed, jetbrains) that support `end-to-end: true` detection:
-1. Invoke `Skill(skill="gm:gm")`
-2. Parse stdout for trailing JSON blob
-3. If `nextSkill` is non-null, invoke `Skill(skill="gm:<nextSkill>")` with context dict auto-passed
-4. Repeat until `nextSkill` is null
-
-This collapses 5 manual skill invocations into 1 user invocation + 4 transparent auto-dispatches, achieving perceived single-flow parity with gm-cc's subagent orchestration.
+Read `out/<N>.json::nextSkill`. Invoke `Skill(skill="gm:<nextSkill>")` immediately. End of skill body — no trailing narration, no "I will now". The invocation IS the transition.

package/skills/gm-complete/SKILL.md

@@ -1,106 +1,35 @@
 ---
 name: gm-complete
 description: VERIFY and COMPLETE phase. End-to-end system verification and git enforcement. Any new unknown triggers immediate snake back to planning — restart chain.
+allowed-tools: Skill, Read, Write
 ---
 
-# GM COMPLETE — Verify, then close
+# gm-complete — VERIFY
 
-Entry: EMIT gates clear, from `gm-emit`. Exit: `.prd` deleted + test.js green + pushed + CI green → `update-docs`.
+COMPLETE is earned, not declared. Three preconditions: git clean, pushed to remote, CI green. Any one missing means the phase has not concluded.
 
-Cross-cutting dispositions live in `gm` SKILL.md.
+## CI Is The Build
 
-## Transitions
+For Rust crates (rs-exec, rs-codeinsight, rs-search, rs-learn, rs-plugkit) and the gm publish chain, `git push` triggers the build matrix across six target platforms. `cargo build` and `cargo test` are not run locally — a local build covers exactly one platform and proves nothing about the other five. Push, watch CI, fix on red. Toolchain mismatches and rustc skew never block a push.
 
-- `.prd` items remain → `gm-execute`
-- `.prd` empty AND test.js green AND pushed AND CI green → `update-docs`
-- Broken file output → `gm-emit`
-- Wrong logic → `gm-execute`
-- New unknown or wrong requirements → `planning`
+Watch protocol: after push, poll `gh run list --branch <branch> --limit 3 --json status,conclusion,name` until the run completes, up to `GM_CI_WATCH_SECS` (default 180). On red, triage the failure shape (import error → check manifests; type error → snake to PLAN; test failure → root cause; lint → fix in-band; build timeout → re-trigger once, else PRD `blockedBy: external`). Fix at root, push, re-watch. Green CI is the precondition for VERIFY → UPDATE-DOCS.
 
-Failure triage: broken output to EMIT, wrong logic to EXECUTE, new unknown to PLAN. Never patch around surprises.
+## Single Integration Test
 
-## Mutables that must resolve before COMPLETE
+One `test.js` at project root. 200-line hard cap. No fixtures, no mocks, no scattered test files. `gm-complete` runs it. Failure = regression to EXECUTE. Prefer compaction over expansion when editing: merge groups, drop redundancy.
 
-- `witnessed_e2e` — real end-to-end run with witnessed output
-- `browser_validated` — for any change touching client / UI / browser-facing code, see gate below. test.js + node-side imports DO NOT satisfy this gate.
-- `git_clean` — `git status --porcelain` returns empty
-- `git_pushed` — `git log origin/main..HEAD --oneline` returns empty
-- `ci_passed` — every GitHub Actions run reaches `conclusion: success`
-- `mutables_resolved` — `.gm/mutables.yml` deleted OR every entry `status: witnessed`. Stop hook hard-blocks turn-stop while any entry is `status: unknown`.
-- `prd_empty` — `.gm/prd.yml` deleted AFTER residual scan: enumerate every in-spirit reachable residual surfaced this session; any hit re-enters `planning`, appends PRD items, executes. Empty PRD is necessary, not sufficient — done = empty PRD AND zero reachable in-spirit residuals. Out-of-spirit-or-unreachable residuals are named in the response and skipped; everything else is this turn's work.
-- `stress_suite_clear` — change walked through M1–D1 (governance), none flunked
-- `hidden_decision_posture` — open → down_weighted → closed only when CI is green AND stress suite is clear
+## Residual-Scan Gate
 
-## End-to-end verification
+Before allowing transition to update-docs, fire the `residual-scan` verb. Empty PRD is necessary but not sufficient — the gate asks what the agent should have decided to do but did not. Either re-enter planning with appended items and execute, or explicitly state "residual scan: none reachable in-spirit." The `.gm/residual-check-fired` marker makes this one-shot per stopping window. Common residuals: pre-existing build break surfaced this turn, neighboring lint failure, obvious refactor win, observability gap, doc drift, follow-on work the user clearly implied.
 
-Real system, real data, witness actual output. Doc updates, "saying done", and screenshots alone are not verification. Write the e2e probe to the spool (`.gm/exec-spool/in/nodejs/<N>.js`):
+## Git Gate
 
-```
-const { fn } = await import('/abs/path/to/module.js');
-console.log(await fn(realInput));
-```
+`git status` clean. `git log` shows the commit pushed. `gh run list` shows the most recent run for the branch concluded green. All three witnessed before transition.
 
-After every success, enumerate what remains — never stop at first green.
+## Dispatch
 
-## Browser validation gate
+`phase-status`, `transition`, `residual-scan`. Spool the CI watch through `in/bash/` so timeouts respect the spool budget.
 
-Required when this session changed any code that runs in a browser: anything under `client/`, UI components, shaders, page-loaded JS, served HTML, gh-pages assets, dev-server endpoints, or any module imported into the page bundle.
+## Transition
 
-Trigger detection (any one): `git diff --name-only origin/main..HEAD` includes paths under `client/`, `apps/*/index.js` with client export, `docs/`, `*.html`, shader files, or any file imported by a browser entry; new/changed export consumed by `window.*` or rendered in DOM/canvas/WebGL; visual, layout, animation, input, network-on-page, or shader behavior altered.
-
-Protocol: boot the real server (or open the static page) on a known URL — witness HTTP 200. `exec:browser` → `page.goto(url)` → wait for app init by polling for the global the change affects (`window.__app.<system>`). Probe via `page.evaluate(() => …)` asserting the specific invariant the change was supposed to establish — instance counts, scene meshes, DOM nodes, render stats, network frames. Capture witnessed numbers in the response — "looks fine" is not a witness. Failures route to `gm-execute` (logic) or `gm-emit` (output) — never paper over.
-
-Long-running probes split into navigate-call → `exec:wait N` → probe-call to stay under the per-call budget. Do not stack multi-second `setTimeout` inside one `exec:browser` invocation.
-
-Exempt only when: change is server-only with zero browser-facing surface, OR the repository has no browser surface at all (pure CLI / library). Exemption requires explicit tag in the response: `BROWSER EXEMPT: <reason — must reference diff paths showing zero browser-facing surface>`. Default posture is NOT exempt — burden is on the agent to prove exemption with diff evidence.
-
-Pre-flight: run `git diff --name-only origin/main..HEAD` directly via Bash, then dispatch a nodejs spool file that reads the diff list and filters lines matching `client/|docs/|\.html$|\.glsl$|\.frag$|\.vert$`. Any hit AND no `exec:browser` block in this session → mandatory regression to `gm-execute`.
-
-## Integration test gate
-
-Write to `.gm/exec-spool/in/nodejs/<N>.js`:
-
-```
-const { execSync } = require('child_process');
-try { execSync('node test.js', { stdio: 'inherit', timeout: 30000 }); console.log('PASS'); }
-catch (e) { console.error('FAIL'); process.exit(1); }
-```
-
-Failure → `gm-execute`. No test.js in a repo with testable surface → `gm-execute` to create it.
-
-## Git enforcement
-
-Run directly via Bash:
-
-```
-git status --porcelain
-git log origin/main..HEAD --oneline
-```
-
-Both must return empty. Local commit without push is not complete.
-
-## CI is automated
-
-The Stop hook watches Actions for the pushed HEAD. Do not call `gh run list` manually. All-green → Stop approves with CI summary in next-turn context. Failure → Stop blocks with run names + IDs; investigate via `gh run view <id> --log-failed`, fix, push, hook re-watches. Deadline 180s (override `GM_CI_WATCH_SECS`); slow jobs get a "still in progress" approve.
-
-## Hygiene sweep
-
-1. Files >200 lines → split
-2. Comments in code → remove
-3. Scattered test files (`.test.js`, `.spec.js`, `__tests__/`, `fixtures/`, `mocks/`) → delete, consolidate into root `test.js`
-4. Mock / stub / simulation files → delete
-5. Unnecessary doc files (not CHANGELOG, CLAUDE, README, TODO.md) → delete
-6. Duplicate concern → regress to `planning` with restructuring instructions
-7. Hardcoded values → derive from ground truth
-8. Fallback / demo modes → remove, fail loud
-9. TODO.md → empty or deleted
-10. CHANGELOG.md → entries for this session
-11. Observability gaps → server subsystems expose `/debug/<subsystem>`; client modules register in `window.__debug`
-12. Memorize → every fact from verification handed off via background `Agent(memorize)` at moment of resolution
-13. Deploy / publish → if deployable, deploy; if npm package, publish
-14. GitHub Pages → check `.github/workflows/pages.yml` + `docs/index.html` exist; invoke `pages` skill if absent
-15. Governance stress-suite → walk change through M1, F1, C1, H1, S1, B1, A1, D1; any flunk regresses to the owning phase
-
-## Completion
-
-All true at once: witnessed e2e | browser_validated when client work touched | failure paths exercised | test.js passes | `.prd` deleted | git clean and pushed | CI green | hygiene sweep clean | TODO.md gone | CHANGELOG.md updated.
+Residual-scan clear AND git clean AND CI green → `Skill(skill="gm:update-docs")`. Anything else → `Skill(skill="gm:planning")` or `Skill(skill="gm:gm-execute")` per the gap.