gm-skill 0.1.1 → 0.1.2

package/planning.SKILL.md

@@ -0,0 +1,118 @@
+---
+name: planning
+description: State machine orchestrator. Mutable discovery, PRD construction, and full PLAN→EXECUTE→EMIT→VERIFY→COMPLETE lifecycle. Invoke at session start and on any new unknown.
+allowed-tools: Skill
+---
+
+# Planning — PLAN phase
+
+Translate the request into `.gm/prd.yml` and hand to `gm-execute`. Re-enter on any new unknown in any phase.
+
+A `@<discipline>` sigil in the request scopes recall, codesearch, and memorize calls during PLAN to that discipline's store. Without one, retrievals fan across default plus enabled disciplines and writes land in default only.
+
+Cross-cutting dispositions (autonomy, fix-on-sight, nothing-fake, browser-witness, scope, recall, memorize) live in `gm` SKILL.md; this skill only carries what is unique to PLAN.
+
+## Transitions
+
+- PLAN done → `gm-execute`
+- New unknown anywhere in chain → re-enter PLAN
+- EXECUTE unresolvable after 2 passes → PLAN
+- VERIFY: `.prd` empty + git clean + pushed → `update-docs`; else → `gm-execute`
+
+Cannot stop while `.gm/prd.yml` has items, git is dirty, or commits are unpushed.
+
+## Orient
+
+Open every plan with one parallel pack of `exec:recall` + `exec:codesearch` against the request's nouns. Hits land as `weak_prior`; misses confirm the unknown is fresh. The pack runs in one message.
+
+**Auto-recall injection (skills-only platforms)**: derive a 2–6 word query from the request's nouns (subject, verb objects, key domain terms). Call `exec:recall <query>` at PLAN start before writing `.gm/prd.yml`, inline. This replaces the prompt-submit hook's auto-recall for platforms without hook infrastructure. Recall hits are injected as context into mutable discovery and PRD item acceptance criteria.
+
+## Mutable discovery
+
+For each aspect of the work, ask: what do I not know, what could go wrong, what depends on what, what am I assuming. Unwitnessed assumptions are mutables.
+
+Fault surfaces to scan: file existence, API shape, data format, dep versions, runtime behavior, env differences, error conditions, concurrency, integration seams, backwards compat, rollback paths, CI correctness.
+
+Tag every item with a route family (grounding | reasoning | state | execution | observability | boundary | representation) and cross-reference the 16-failure taxonomy. `governance` skill holds the table.
+
+`existingImpl=UNKNOWN` is the default; resolve via `exec:codesearch` before adding the item. An existing concern routes to consolidation, not addition.
+
+Plan exits when zero new unknowns surfaced last pass AND every item has acceptance criteria AND deps are mapped.
+
+## .gm/mutables.yml — co-equal with .gm/prd.yml
+
+Every unknown surfaced during PLAN lands as an entry in `.gm/mutables.yml` the same pass. Live during work, deleted when empty. Hook-gated: Write/Edit/NotebookEdit and `git commit`/`git push` are hard-blocked while any entry has `status: unknown`; turn-stop is hard-blocked the same way.
+
+```yaml
+- id: kebab-id
+  claim: One-line statement of what is assumed
+  witness_method: exec:codesearch <query> | exec:nodejs import | exec:recall <query> | Read <path>
+  witness_evidence: ""
+  status: unknown
+```
+
+`status: unknown` → `witnessed` only when `witness_evidence` is filled with concrete proof (file:line, codesearch hit, dispatched test output). Resolution lives in gm-execute. PRD items reference mutables via optional `mutables: [id1, id2]` field; an item is blocked while any referenced mutable is unresolved.
+
+## .prd format
+
+Path: `./.gm/prd.yml`. Write via the Write tool or by emitting a nodejs spool file (`in/nodejs/<N>.js`) that calls `fs.writeFileSync`. Delete the file when empty.
+
+```yaml
+- id: kebab-id
+  subject: Imperative verb phrase
+  status: pending
+  description: Precise criterion
+  effort: small|medium|large
+  category: feature|bug|refactor|infra
+  route_family: grounding|reasoning|state|execution|observability|boundary|representation
+  load: 0.0-1.0
+  failure_modes: []
+  route_fit: unexamined|examined|dominant
+  authorization: none|weak_prior|witnessed
+  blocking: []
+  blockedBy: []
+  acceptance:
+    - binary criterion
+  edge_cases:
+    - failure mode
+```
+
+`load` is consequence-if-wrong: 0.9 = headline collapses, 0.7 = sub-argument rebuilt, 0.4 = local patch, 0.1 = nothing breaks. Verification budget = `load × (1 − tier_confidence)`. λ>0.75 must reach witnessed before EMIT.
+
+`status`: pending → in_progress → completed (then remove). `effort`: small <15min | medium <45min | large >1h.
+
+## Parallel subagent launch
+
+After `.prd` is written, up to 3 parallel `gm:gm` subagents for independent items in one message. Browser tasks serialize.
+
+```
+Agent(subagent_type="gm:gm", prompt="Work on .prd item: <id>. .prd path: <path>. Item: <full YAML>.")
+```
+
+Items not parallelizable → invoke `gm-execute` directly.
+
+## Observability gates in the plan
+
+Server: every subsystem exposes `/debug/<subsystem>`; structured logs `{subsystem, severity, ts}`. Client: `window.__debug` live registry; modules register on mount. `console.log` is not observability. Discovery of a gap during PLAN adds a `.prd` item the same pass — never deferred.
+
+`window.__debug` is THE in-page registry; `test.js` at project root is the sole out-of-page test asset. Any new file whose purpose is to exercise, smoke-test, demo, or sandbox in-page behavior outside that registry fights the discipline — extend the registry instead.
+
+## Test discipline encoded in the plan
+
+One `test.js` at project root, 200-line hard cap, real data, real system. No fixtures, mocks, or scattered tests. A second test runner under any name in any directory is a smuggled parallel surface.
+
+The 200 lines are a *budget* for maximum surface coverage, not a target. Subsystems get one combined group each — names joined with `+` (`home+config+skin`, `mcp+swe+distributions+account+credpool`). When a new subsystem's failure mode overlaps an existing group's side-effects, fold the assertion in rather than creating a new group. When `wc -l test.js > 200`, the discipline is *merge groups + drop redundancy*, never split.
+
+## Execution norms encoded in the plan
+
+Code execution AND utility verbs both write to `.gm/exec-spool/in/<lang-or-verb>/<N>.<ext>`. Languages live under `in/<lang>/` (nodejs, python, bash, typescript, go, rust, c, cpp, java, deno); verbs live under `in/<verb>/` (codesearch, recall, memorize, wait, sleep, status, close, browser, runner, type, kill-port, forget, feedback, learn-status, learn-debug, learn-build, discipline, pause, health). The spool watcher runs the file and streams to `out/<N>.out` (stdout) + `out/<N>.err` (stderr) line-by-line, then writes `out/<N>.json` metadata (exitCode, durationMs, timedOut, startedAt, endedAt) at completion. Both streams return as systemMessage with `--- stdout ---` / `--- stderr ---` separators. `in/` and `out/` are wiped at session start and at real-exit session end. Only `git` (and `gh`) run directly via Bash; never `Bash(node/npm/npx/bun)`, never `Bash(exec:<anything>)`. Spool paths in nodejs files are platform-literal — use `os.tmpdir()` and `path.join`. The spool enforces per-task timeouts; on timeout, partial output is preserved and the watcher emits `[exec timed out after Nms; partial output above]`.
+
+`exec:codesearch` only — Grep/Glob/Find/Explore are hook-blocked. Start two words, change/add one per pass, minimum four attempts before concluding absent.
+
+Pack runs use `Promise.allSettled`, each idea its own try/catch, under 12s per call.
+
+## Dev workflow encoded in the plan
+
+No comments. 200-line per-file cap. Fail loud. No duplication. Scan before edit. AGENTS.md edits route through the memorize sub-agent only. CHANGELOG.md gets one entry per commit.
+
+Minimal-code process, stop at the first that resolves: native → library → structure (map / pipeline) → write.

package/skills/gm/SKILL.md

@@ -0,0 +1,63 @@
+---
+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
+end-to-end: true
+---
+
+# GM — Orchestrator
+
+Invoke `planning` immediately. Phases cascade: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS.
+
+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.
+
+**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.
+
+**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.
+
+**Every issue surfaces this turn**: pre-existing breaks, lint failures, drift, broken deps, stale generated files — all become PRD items and finish before COMPLETE.
+
+**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).
+
+**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).
+
+**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.

package/skills/gm/index.js

@@ -0,0 +1,113 @@
+const fs = require('fs');
+const path = require('path');
+
+async function gmSkill(input) {
+  const context = {
+    request: input.request || '',
+    taskId: input.taskId || require('crypto').randomUUID(),
+    sessionId: process.env.SESSION_ID || require('crypto').randomUUID(),
+    timestamp: new Date().toISOString(),
+    phases: [],
+    prd: [],
+    mutables: {},
+  };
+
+  const skillsDir = path.join(__dirname);
+  const gmDir = path.dirname(path.dirname(skillsDir));
+
+  let currentSkill = 'planning';
+  let chainDepth = 0;
+  const maxDepth = 6;
+
+  console.log(`[gm] orchestrator starting; request="${context.request}"; task=${context.taskId}`);
+
+  while (currentSkill && chainDepth < maxDepth) {
+    chainDepth++;
+    console.error(`[gm] depth=${chainDepth}; invoking ${currentSkill}`);
+
+    const skillPath = path.join(skillsDir, currentSkill, 'index.js');
+    if (!fs.existsSync(skillPath)) {
+      console.error(`[gm] ERROR: skill not found: ${skillPath}`);
+      return {
+        nextSkill: null,
+        context,
+        phase: 'ERROR',
+        error: `Skill ${currentSkill} not found`,
+      };
+    }
+
+    try {
+      const skillModule = require(skillPath);
+      const result = await skillModule(input, context);
+
+      if (!result || typeof result !== 'object') {
+        console.error(`[gm] ERROR: skill returned invalid result`);
+        return {
+          nextSkill: null,
+          context,
+          phase: 'ERROR',
+          error: `Skill ${currentSkill} returned invalid result`,
+        };
+      }
+
+      context.phases.push({
+        skill: currentSkill,
+        phase: result.phase,
+        timestamp: new Date().toISOString(),
+      });
+
+      currentSkill = result.nextSkill || null;
+
+      if (!currentSkill) {
+        console.error(`[gm] chain complete`);
+        return {
+          nextSkill: null,
+          context,
+          phase: 'COMPLETE',
+        };
+      }
+
+      input = { ...input, context };
+    } catch (error) {
+      console.error(`[gm] ERROR in ${currentSkill}:`, error.message);
+      return {
+        nextSkill: null,
+        context,
+        phase: 'ERROR',
+        error: `${currentSkill} failed: ${error.message}`,
+      };
+    }
+  }
+
+  if (chainDepth >= maxDepth) {
+    console.error(`[gm] ERROR: max chain depth exceeded`);
+    return {
+      nextSkill: null,
+      context,
+      phase: 'ERROR',
+      error: 'Skill chain exceeded maximum depth',
+    };
+  }
+
+  return {
+    nextSkill: null,
+    context,
+    phase: 'COMPLETE',
+  };
+}
+
+if (require.main === module) {
+  const input = {
+    request: process.argv[2] || 'test task',
+    context: null,
+  };
+
+  gmSkill(input).then(result => {
+    console.log(JSON.stringify(result, null, 2));
+  }).catch(err => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = gmSkill;

package/skills/gm-complete/SKILL.md

@@ -0,0 +1,106 @@
+---
+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.
+---
+
+# GM COMPLETE — Verify, then close
+
+Entry: EMIT gates clear, from `gm-emit`. Exit: `.prd` deleted + test.js green + pushed + CI green → `update-docs`.
+
+Cross-cutting dispositions live in `gm` SKILL.md.
+
+## Transitions
+
+- `.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`
+
+Failure triage: broken output to EMIT, wrong logic to EXECUTE, new unknown to PLAN. Never patch around surprises.
+
+## Mutables that must resolve before COMPLETE
+
+- `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
+
+## End-to-end verification
+
+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`):
+
+```
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
+
+After every success, enumerate what remains — never stop at first green.
+
+## Browser validation gate
+
+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.
+
+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.

package/skills/gm-complete/index.js

@@ -0,0 +1,118 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+const git = require('../../lib/git.js');
+
+async function completeSkill(input, parentContext) {
+  const context = parentContext || {
+    request: input.request || '',
+    taskId: input.taskId || require('crypto').randomUUID(),
+    sessionId: process.env.SESSION_ID || require('crypto').randomUUID(),
+  };
+
+  const gmDir = path.join(process.cwd(), '.gm');
+  const prdPath = path.join(gmDir, 'prd.yml');
+  const mutablesPath = path.join(gmDir, 'mutables.yml');
+
+  console.error(`[gm-complete] COMPLETE phase starting`);
+
+  let prd = [];
+
+  try {
+    if (fs.existsSync(prdPath)) {
+      const prdContent = fs.readFileSync(prdPath, 'utf8');
+      prd = yaml.parse(prdContent) || [];
+    }
+  } catch (err) {
+    console.error(`[gm-complete] ERROR reading prd.yml:`, err.message);
+  }
+
+  const verifications = {
+    gitClean: false,
+    gitPushed: false,
+    testsPassed: false,
+    prdEmpty: false,
+    mutablesResolved: false,
+  };
+
+  console.error(`[gm-complete] Running verifications...`);
+
+  try {
+    const statusResult = await git.status(context.sessionId);
+    verifications.gitClean = statusResult.ok && !statusResult.isDirty;
+    console.error(`[gm-complete] git clean: ${verifications.gitClean}`);
+  } catch (err) {
+    console.error(`[gm-complete] git status check failed:`, err.message);
+  }
+
+  try {
+    const logResult = await git.log(context.sessionId, 100);
+    verifications.gitPushed = logResult.ok && logResult.commits.length >= 0;
+    console.error(`[gm-complete] git log retrieved: ${verifications.gitPushed ? 'success' : 'failed'}`);
+  } catch (err) {
+    console.error(`[gm-complete] git log check failed:`, err.message);
+  }
+
+  if (fs.existsSync('test.js')) {
+    try {
+      execSync('node test.js', { stdio: 'pipe', timeout: 30000 });
+      verifications.testsPassed = true;
+      console.error(`[gm-complete] tests passed: true`);
+    } catch (err) {
+      console.error(`[gm-complete] tests failed:`, err.message);
+    }
+  } else {
+    verifications.testsPassed = true;
+    console.error(`[gm-complete] no test.js found, skipping tests`);
+  }
+
+  verifications.prdEmpty = !fs.existsSync(prdPath) || prd.length === 0;
+  console.error(`[gm-complete] prd empty: ${verifications.prdEmpty}`);
+
+  verifications.mutablesResolved = !fs.existsSync(mutablesPath);
+  console.error(`[gm-complete] mutables resolved: ${verifications.mutablesResolved}`);
+
+  const allVerified = Object.values(verifications).every(v => v);
+
+  if (!allVerified) {
+    console.error(`[gm-complete] Verifications failed, checking for incomplete work...`);
+    if (prd.length > 0) {
+      console.error(`[gm-complete] PRD still has items, returning to EXECUTE`);
+      return {
+        nextSkill: 'gm-execute',
+        context: { ...context, verifications },
+        phase: 'COMPLETE',
+      };
+    }
+  }
+
+  console.error(`[gm-complete] All verifications passed`);
+
+  const completeState = {
+    timestamp: new Date().toISOString(),
+    verifications,
+    ready: allVerified,
+  };
+
+  fs.writeFileSync(path.join(gmDir, 'complete-state.json'), JSON.stringify(completeState, null, 2), 'utf8');
+
+  context.verifications = verifications;
+
+  return {
+    nextSkill: allVerified ? 'update-docs' : null,
+    context,
+    phase: 'COMPLETE',
+  };
+}
+
+if (require.main === module) {
+  const input = { request: process.argv[2] || 'default task' };
+  completeSkill(input).then(result => {
+    console.log(JSON.stringify(result, null, 2));
+  }).catch(err => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = completeSkill;

package/skills/gm-complete.SKILL.md

@@ -0,0 +1,106 @@
+---
+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.
+---
+
+# GM COMPLETE — Verify, then close
+
+Entry: EMIT gates clear, from `gm-emit`. Exit: `.prd` deleted + test.js green + pushed + CI green → `update-docs`.
+
+Cross-cutting dispositions live in `gm` SKILL.md.
+
+## Transitions
+
+- `.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`
+
+Failure triage: broken output to EMIT, wrong logic to EXECUTE, new unknown to PLAN. Never patch around surprises.
+
+## Mutables that must resolve before COMPLETE
+
+- `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
+
+## End-to-end verification
+
+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`):
+
+```
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
+
+After every success, enumerate what remains — never stop at first green.
+
+## Browser validation gate
+
+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.
+
+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.