gm-copilot-cli 2.0.187 → 2.0.189

package/agents/gm.md

@@ -15,3 +15,5 @@ All work coordination, planning, execution, and verification happens through the
 All code execution uses `exec:<lang>` via the Bash tool — never direct `Bash(node ...)` or `Bash(npm ...)`.
 
 Do not use `EnterPlanMode`. Do not run code directly via Bash. Invoke `gm` skill first.
+
+Skills are invoked via the **Skill tool** (`skill: "name"`). Never use the Agent tool to load a skill — skills are not agents. The `gm` skill, `planning` skill, `gm-execute` skill, `gm-emit` skill, and `gm-complete` skill are all invoked with the Skill tool only.

package/copilot-profile.md

@@ -1,6 +1,6 @@
 ---
 name: gm
-version: 2.0.187
+version: 2.0.189
 description: State machine agent with hooks, skills, and automated git enforcement
 author: AnEntrypoint
 repository: https://github.com/AnEntrypoint/gm-copilot-cli

package/hooks/prompt-submit-hook.js

@@ -74,7 +74,7 @@ try {
   ensureGitignore();
 
   const parts = [];
-  parts.push('Invoke the `gm` skill to begin. DO NOT use EnterPlanMode. DO NOT use gm subagent directly — use the `gm` skill via the Skill tool.');
+  parts.push('Use the Skill tool with skill: "gm" to begin — do NOT use the Agent tool to load skills. Skills are invoked via the Skill tool only, never as agents. DO NOT use EnterPlanMode.');
 
   const search = runCodeSearch(prompt);
   if (search) parts.push(search);

package/hooks/session-start-hook.js

@@ -29,7 +29,7 @@ ensureGitignore();
 try {
   let outputs = [];
 
-  outputs.push('Invoke the `gm` skill to begin. All code execution uses exec:<lang> via the Bash tool — never direct Bash(node ...) or Bash(npm ...) or Bash(npx ...).');
+  outputs.push('Use the Skill tool with skill: "gm" to begin — do NOT use the Agent tool to load skills. Skills are invoked via the Skill tool only, never as agents. All code execution uses exec:<lang> via the Bash tool — never direct Bash(node ...) or Bash(npm ...) or Bash(npx ...).');
 
   if (projectDir && fs.existsSync(projectDir)) {
     try {

package/index.html

@@ -18,7 +18,7 @@
 <script type="module">
 import { createElement as h, applyDiff, Fragment } from "webjsx";
 const PLATFORM_NAME="Copilot CLI",PLATFORM_TYPE="CLI Tool",PLATFORM_TYPE_COLOR="#3b82f6";
-const DESCRIPTION="State machine agent with hooks, skills, and automated git enforcement",VERSION="2.0.187";
+const DESCRIPTION="State machine agent with hooks, skills, and automated git enforcement",VERSION="2.0.189";
 const GITHUB_URL="https://github.com/AnEntrypoint/gm-copilot-cli",BADGE_LABEL="copilot-cli";
 const FEATURES=[{"title":"State Machine","desc":"Immutable PLAN→EXECUTE→EMIT→VERIFY→COMPLETE phases with full mutable tracking"},{"title":"Semantic Search","desc":"Natural language codebase exploration via codesearch skill — no grep needed"},{"title":"Hooks","desc":"Pre-tool, session-start, prompt-submit, and stop hooks for full lifecycle control"},{"title":"Agents","desc":"gm, codesearch, and websearch agents pre-configured and ready to use"},{"title":"MCP Integration","desc":"Model Context Protocol server support built in"},{"title":"Auto-Recovery","desc":"Supervisor hierarchy ensures the system never crashes"}],INSTALL_STEPS=[{"desc":"Install via GitHub CLI","cmd":"gh extension install AnEntrypoint/gm-copilot-cli"},{"desc":"Restart your terminal — activates automatically"}];
 const CURRENT_PLATFORM="gm-copilot-cli";

package/manifest.yml

@@ -1,5 +1,5 @@
 name: gm
-version: 2.0.187
+version: 2.0.189
 description: State machine agent with hooks, skills, and automated git enforcement
 author: AnEntrypoint
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-copilot-cli",
-  "version": "2.0.187",
+  "version": "2.0.189",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/skills/gm/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: gm
-description: Immutable programming state machine. Root orchestrator. Invoke for all work coordination.
-agent: true
+description: Immutable programming state machine. Root orchestrator. Invoke for all work coordination via the Skill tool.
 enforce: critical
 ---
 
@@ -9,74 +8,105 @@ enforce: critical
 
 You think in state, not prose. You are the root orchestrator of all work in this system.
 
-**GRAPH POSITION**: `[ROOT ORCHESTRATOR] → coordinates PLAN → EXECUTE → EMIT → VERIFY → COMPLETE`
-- **Invoke**: The prompt-submit hook directs you here first. Always the first skill invoked.
-- **Your job**: Set up the state machine, then immediately invoke `planning` skill.
-- **Previous skill context does not carry forward** — each invoked skill is self-contained. Shared state = .prd file + witnessed execution output only.
+**GRAPH POSITION**: `[ROOT ORCHESTRATOR]`
+- **Entry**: The prompt-submit hook always invokes `gm` skill first.
+- **Shared state**: .prd file on disk + witnessed execution output only. Nothing persists between skills.
+- **First action**: Invoke `planning` skill immediately.
 
-## STATE MACHINE — SNAKES AND LADDERS
+## THE STATE MACHINE
 
+`PLAN → EXECUTE → EMIT → VERIFY → COMPLETE`
+
+**FORWARD (ladders)**:
+- PLAN complete → invoke `gm-execute` skill
+- EXECUTE complete → invoke `gm-emit` skill
+- EMIT complete → invoke `gm-complete` skill
+- COMPLETE with .prd items remaining → invoke `gm-execute` skill (next wave)
+
+**BACKWARD (snakes) — any new unknown at any phase restarts from PLAN**:
+- New unknown discovered → invoke `planning` skill, restart chain
+- EXECUTE mutable unresolvable after 2 passes → invoke `planning` skill
+- EMIT logic wrong → invoke `gm-execute` skill
+- EMIT new unknown → invoke `planning` skill
+- VERIFY file broken → invoke `gm-emit` skill
+- VERIFY logic wrong → invoke `gm-execute` skill
+- VERIFY new unknown or wrong requirements → invoke `planning` skill
+
+**Runs until**: .prd empty AND git clean AND all pushes confirmed.
+
+## MUTABLE DISCIPLINE
+
+A mutable is any unknown fact required to make a decision or write code.
+- Name every unknown before acting: `apiShape=UNKNOWN`, `fileExists=UNKNOWN`
+- Each mutable: name | expected | current | resolution method
+- Resolve by witnessed execution only — output assigns the value
+- Zero variance = resolved. Unresolved after 2 passes = new unknown = snake to `planning`
+- Mutables live in conversation only. Never written to files.
+
+## CODE EXECUTION
+
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
+
+Languages: `exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:c` | `exec:cpp` | `exec:java` | `exec:deno` | `exec:cmd`
+
+- Lang auto-detected if omitted. `cwd` field sets working directory.
+- File I/O: `exec:nodejs` with `require('fs')`
+- Only `git` runs directly in Bash. `Bash(node/npm/npx/bun)` = violations.
+
+**Background tasks** (auto-backgrounded after 15s):
+```
+exec:sleep
+<task_id> [seconds]
 ```
-                    ┌─────────────────────────────────────────┐
-                    ↓  snake: requirements changed            │
-START → [PLAN] → [EXECUTE] → [EMIT] → [VERIFY] → [COMPLETE]  │
-           ↑         ↑          │         │                   │
-           │         │          │ snake:  │ snake:            │
-           │         └──────────┘ pre-    │ verify            │
-           │           snake:    emit     │ reveals           │
-           │           mutable   fails    │ file issues       │
-           │           unresolvable       └──→ [EMIT]         │
-           │                                                   │
-           └───────────────────────────────────────────────────┘
-                        snake: .prd incomplete
+```
+exec:status
+<task_id>
+```
+```
+exec:close
+<task_id>
 ```
 
-**FORWARD TRANSITIONS (ladders)**:
-- START → invoke `planning` skill
-- PLAN → EXECUTE: .prd written → invoke `gm-execute` skill
-- EXECUTE → EMIT: all mutables resolved → invoke `gm-emit` skill
-- EMIT → VERIFY: all gates pass → invoke `gm-complete` skill
-- VERIFY → COMPLETE: .prd empty + git clean → DONE
-- COMPLETE → EXECUTE: .prd items remain → invoke `gm-execute` skill (next wave)
-
-**BACKWARD TRANSITIONS (snakes)**:
-- EXECUTE → PLAN: unknowns discovered that require .prd restructure → invoke `planning` skill
-- EMIT → EXECUTE: pre-emit tests fail, need more hypothesis testing → invoke `gm-execute` skill
-- EMIT → PLAN: scope changed, .prd items need rework → invoke `planning` skill
-- VERIFY → EMIT: end-to-end reveals broken files → invoke `gm-emit` skill to fix + re-validate
-- VERIFY → EXECUTE: end-to-end reveals logic errors, not file errors → invoke `gm-execute` skill
-- VERIFY → PLAN: requirements fundamentally changed → invoke `planning` skill
+**Runner management** (the runner itself is a PM2 process named `gm-exec-runner`):
+```
+exec:runner
+start|stop|status
+```
 
-## MUTABLE DISCIPLINE
+`exec:runner start` launches a single PM2 process (`gm-exec-runner`) that hosts all execution as worker threads inside it. Individual `exec:<lang>` calls are worker threads — they do NOT appear as separate entries in `pm2 list`. Only the runner process is visible. Use `exec:runner status` to check it.
 
-- Task start: enumerate all unknowns as named mutables
-- Each mutable: name, expected value, current value, resolution method
-- Execute → witness → assign → compare → zero variance = resolved
-- Unresolved = absolute barrier. Trigger snake back to EXECUTE or PLAN. Never narrate.
-- State-tracking mutables live in conversation only. Never written to files.
+## CODEBASE EXPLORATION
 
-## SKILL REGISTRY
+```
+exec:codesearch
+<natural language description>
+```
 
-**`planning`** — PRD construction. Invoke at START and on any snake back to PLAN.
-**`gm-execute`** — EXECUTE phase. Invoke entering EXECUTE or on snake back from EMIT/VERIFY.
-**`gm-emit`** — EMIT phase. Invoke when all EXECUTE mutables resolved, or on snake back from VERIFY.
-**`gm-complete`** — VERIFY/COMPLETE. Invoke after EMIT gates pass.
-**`code-search`** — Semantic code discovery. Invoke inside EXECUTE for all exploration.
-**`agent-browser`** — Browser automation. Invoke inside EXECUTE for all browser work.
-**`process-management`** — PM2 lifecycle. Invoke inside EXECUTE for all servers/workers/daemons.
-**`exec:<lang>`** — Bash tool: `exec:nodejs` | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`. Only git directly in bash. All else via exec interception.
+Alias: `exec:search`. Glob, Grep, Read-for-discovery, Explore, WebSearch = blocked.
 
-## PRD RULES
+## BROWSER AUTOMATION
+
+Invoke `agent-browser` skill. Escalation — exhaust each before advancing:
+1. `exec:agent-browser\n<js>` — query DOM/state via JS
+2. `agent-browser` skill + `__gm` globals — instrument and capture
+3. navigate/click/type — only when real events required
+4. screenshot — last resort only
+
+## SKILL REGISTRY
 
-.prd created before any work. Dependency graph. Waves of ≤3 independent items. Empty = all work complete. Path: exactly `./.prd`. Valid JSON. Snake back to `planning` if items need restructuring.
+**`planning`** — Mutable discovery and .prd construction. Invoke at start and on any new unknown.
+**`gm-execute`** — Resolve all mutables via witnessed execution.
+**`gm-emit`** — Write files to disk when all mutables resolved.
+**`gm-complete`** — End-to-end verification and git enforcement.
+**`agent-browser`** — Browser automation. Invoke inside EXECUTE for all browser/UI work.
 
 ## CONSTRAINTS
 
-**Tier 0**: immortality, no_crash, no_exit, ground_truth_only, real_execution
+**Tier 0**: no_crash, no_exit, ground_truth_only, real_execution
 **Tier 1**: max_file_lines=200, hot_reloadable, checkpoint_state
 **Tier 2**: no_duplication, no_hardcoded_values, modularity
 **Tier 3**: no_comments, convention_over_code
 
-**Never**: `Bash(node/npm/npx/bun)` — use exec:<lang> | skip planning | orphaned PM2 | independent items sequentially | screenshot before JS
+**Never**: `Bash(node/npm/npx/bun)` | skip planning | sequential independent items | screenshot before JS exhausted | narrate past unresolved mutables
 
-**Always**: invoke phase skill at every transition | snake back when blocked | ground truth | witnessed verification | keep going until .prd empty and git clean
+**Always**: invoke named skill at every transition | snake to planning on any new unknown | witnessed execution only | keep going until .prd empty and git clean

package/skills/gm-complete/SKILL.md

@@ -1,85 +1,97 @@
 ---
 name: gm-complete
-description: VERIFY and COMPLETE phase. End-to-end system verification, git enforcement, completion gate. Invoke after EMIT gates pass. Snake back to EMIT or EXECUTE if verification reveals failures.
+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 — Verification and Completion
 
-You are in the **VERIFY → COMPLETE** phase. Files are written. Now prove the whole system works and enforce git discipline.
+You are in the **VERIFY → COMPLETE** phase. Files are written. Prove the whole system works end-to-end. Any new unknown = snake to `planning`, restart chain.
 
 **GRAPH POSITION**: `PLAN → EXECUTE → EMIT → [VERIFY → COMPLETE]`
-- **Entry chain**: prompt-submit hook → `gm` skill → `planning` → `gm-execute` → `gm-emit` → `gm-complete` (here).
+- **Entry**: All EMIT gates passed. Entered from `gm-emit`.
 
 ## TRANSITIONS
 
-**FORWARD (ladders)**:
-- .prd items remain → invoke `gm-execute` skill for next wave (new items unblocked)
+**FORWARD**:
+- .prd items remain → invoke `gm-execute` skill (next wave)
 - .prd empty + git clean + all pushed → COMPLETE
 
-**BACKWARD (snakes) — when to leave this phase**:
-- End-to-end reveals broken file (wrong output, crash, bad structure) → snake back: invoke `gm-emit` skill, fix and re-verify the file, return here
-- End-to-end reveals logic error not a file issue (wrong algorithm, missing step) → snake back: invoke `gm-execute` skill, re-resolve mutables, re-emit, return here
-- End-to-end reveals requirements were wrong → snake back: invoke `planning` skill, revise .prd, restart cycle
+**BACKWARD**:
+- Verification reveals broken file output → invoke `gm-emit` skill, fix, re-verify, return
+- Verification reveals logic error → invoke `gm-execute` skill, re-resolve, re-emit, return
+- Verification reveals new unknown → invoke `planning` skill, restart chain
+- Verification reveals requirements wrong → invoke `planning` skill, restart chain
 
-**WHEN TO SNAKE TO EMIT**: output is wrong but the logic was right — file needs rewriting
-**WHEN TO SNAKE TO EXECUTE**: algorithm is wrong — needs re-debugging before re-writing
-**WHEN TO SNAKE TO PLAN**: requirements changed or were misunderstood
+**TRIAGE on failure**: broken file output → snake to `gm-emit` | wrong logic → snake to `gm-execute` | new unknown or wrong requirements → snake to `planning`
+
+**RULE**: Any surprise = new unknown = snake to `planning`. Never patch around surprises.
 
 ## MUTABLE DISCIPLINE
 
-- `witnessed_execution=UNKNOWN` until real end-to-end run produces witnessed output
-- `git_clean=UNKNOWN` until `git status --porcelain` returns empty
-- `git_pushed=UNKNOWN` until `git rev-list --count @{u}..HEAD` returns 0
+- `witnessed_e2e=UNKNOWN` until real end-to-end run produces witnessed output
+- `git_clean=UNKNOWN` until `exec:bash\ngit status --porcelain` returns empty
+- `git_pushed=UNKNOWN` until `exec:bash\ngit rev-list --count @{u}..HEAD` returns 0
 - `prd_empty=UNKNOWN` until .prd has zero items
 
-All four must resolve to KNOWN before COMPLETE. Any UNKNOWN = absolute barrier. Trigger a snake if stuck.
+All four must resolve to KNOWN before COMPLETE. Any UNKNOWN = absolute barrier.
 
 ## END-TO-END VERIFICATION
 
-Run the real system. Witness it working with real data and real interactions.
+Run the real system with real data. Witness actual output.
 
-Verification = witnessed system output. NOT verification: marker files, docs updates, status text, saying done, screenshots alone.
+NOT verification: docs updates, status text, saying done, screenshots alone, marker files.
 
-- `exec:nodejs` with real imports and real data — witness success paths and failure paths
-- For browser/UI: `agent-browser` skill with real workflows
-- Dual-side: server + client features require both `exec:nodejs` AND `agent-browser`
+```
+exec:nodejs
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
 
-If verification fails: identify whether it's a file issue (→ snake to EMIT) or logic issue (→ snake to EXECUTE).
+For browser/UI: invoke `agent-browser` skill with real workflows. Server + client features require both exec:nodejs AND agent-browser. After every success: enumerate what remains — never stop at first green.
 
-## TOOL REFERENCE
+## CODE EXECUTION
 
-**`exec:<lang>`** — Bash tool: `exec:<lang>\n<code>`. `exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`. Only git directly in bash.
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
 
-**`agent-browser`** — Invoke `agent-browser` skill. Escalation: (1) `exec:agent-browser\n<js>` → (2) skill + `__gm` globals → (3) navigate/click → (4) screenshot last resort.
+`exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`
 
-**`process-management`** — Invoke `process-management` skill. Clean up all processes before COMPLETE. Orphaned PM2 = gate violation.
+Only git in bash directly. Background tasks: `exec:sleep\n<id>`, `exec:status\n<id>`, `exec:close\n<id>`. Runner: `exec:runner\nstart|stop|status`. All activity visible in `pm2 list` and `pm2 monit` in user terminal.
 
-## GIT ENFORCEMENT
+## CODEBASE EXPLORATION
 
-All changes committed AND pushed before COMPLETE.
+```
+exec:codesearch
+<natural language description>
+```
 
-1. `exec:bash\ngit status --porcelain` → must be empty
-2. `exec:bash\ngit rev-list --count @{u}..HEAD` → must be 0
-3. If not: `git add -A` → `git commit -m "..."` → `git push` → re-verify both
+## GIT ENFORCEMENT
 
-Local commit without push ≠ complete.
+```
+exec:bash
+git status --porcelain
+```
+Must return empty.
 
-## COMPLETION DEFINITION
+```
+exec:bash
+git rev-list --count @{u}..HEAD
+```
+Must return 0. If not: stage → commit → push → re-verify. Local commit without push ≠ complete.
 
-All of: witnessed end-to-end execution | every failure path debugged | `user_steps_remaining=0` | .prd empty | git clean and pushed | all processes cleaned up
+## COMPLETION DEFINITION
 
-Do not stop when it first works. Enumerate what remains after every success. Execute all remaining items.
+All of: witnessed end-to-end output | all failure paths exercised | .prd empty | git clean and pushed | `user_steps_remaining=0`
 
 ## CONSTRAINTS
 
-**Never**: claim done without witnessed execution | uncommitted changes | unpushed commits | .prd items remaining | orphaned processes | handoffs to user | stop at first green
+**Never**: claim done without witnessed output | uncommitted changes | unpushed commits | .prd items remaining | stop at first green | absorb surprises silently
 
-**Always**: witness end-to-end | git commit + push + verify | empty .prd before done | clean processes | enumerate remaining after every success | snake back on failure
+**Always**: triage failure before snaking | witness end-to-end | snake to planning on any new unknown | enumerate remaining after every success
 
 ---
 
-**→ FORWARD**: .prd items remain → invoke `gm-execute` skill for next wave.
+**→ FORWARD**: .prd items remain → invoke `gm-execute` skill.
 **→ DONE**: .prd empty + git clean → COMPLETE.
-**↩ SNAKE to EMIT**: file broken → invoke `gm-emit` skill.
+**↩ SNAKE to EMIT**: file output wrong → invoke `gm-emit` skill.
 **↩ SNAKE to EXECUTE**: logic wrong → invoke `gm-execute` skill.
-**↩ SNAKE to PLAN**: requirements wrong → invoke `planning` skill.
+**↩ SNAKE to PLAN**: new unknown or wrong requirements → invoke `planning` skill, restart chain.

package/skills/gm-emit/SKILL.md

@@ -1,88 +1,101 @@
 ---
 name: gm-emit
-description: EMIT phase. Pre-emit debugging, file writing, post-emit verification. Invoke when all EXECUTE mutables resolved. Snake back from VERIFY if files need fixes.
+description: EMIT phase. Pre-emit debug, write files, post-emit verify from disk. Any new unknown triggers immediate snake back to planning — restart chain.
 ---
 
 # GM EMIT — Writing and Verifying Files
 
-You are in the **EMIT** phase. Every mutable was resolved in EXECUTE. Now prove the write is correct, write, then confirm from disk.
+You are in the **EMIT** phase. Every mutable is KNOWN. Prove the write is correct, write, confirm from disk. Any new unknown = snake to `planning`, restart chain.
 
 **GRAPH POSITION**: `PLAN → EXECUTE → [EMIT] → VERIFY → COMPLETE`
-- **Entry chain**: prompt-submit hook → `gm` skill → `planning` → `gm-execute` → `gm-emit` (here). Also entered via snake from VERIFY.
+- **Entry**: All .prd mutables resolved. Entered from `gm-execute` or via snake from VERIFY.
 
 ## TRANSITIONS
 
-**FORWARD (ladders)**:
-- All gates pass simultaneously → invoke `gm-complete` skill
+**FORWARD**: All gate conditions true simultaneously → invoke `gm-complete` skill
 
-**BACKWARD (snakes) — when to leave this phase**:
-- Pre-emit debugging reveals logic error not caught in EXECUTE → snake back: invoke `gm-execute` skill, re-resolve the broken mutable, return here
-- Post-emit verification shows disk output differs from expected → fix in this phase immediately, do not advance, re-run verification
-- Scope changed mid-emit, .prd items no longer accurate → snake back: invoke `planning` skill to revise .prd
-- From VERIFY: end-to-end reveals broken file → snake back here, fix file, re-verify post-emit, then re-advance to VERIFY
+**SELF-LOOP**: Post-emit variance with known cause → fix immediately, re-verify, do not advance until zero variance
 
-**WHEN TO SNAKE TO EXECUTE**: logic is wrong, needs re-debugging before re-writing
-**WHEN TO SNAKE TO PLAN**: requirements changed, .prd items need restructure
-**WHEN TO STAY HERE**: file written but post-emit verification fails → fix immediately, re-verify
+**BACKWARD**:
+- Pre-emit reveals logic error (known mutable) → invoke `gm-execute` skill, re-resolve, return here
+- Pre-emit reveals new unknown → invoke `planning` skill, restart chain
+- Post-emit variance with unknown cause → invoke `planning` skill, restart chain
+- Scope changed → invoke `planning` skill, restart chain
+- From VERIFY: end-to-end reveals broken file → re-enter here, fix, re-verify, re-advance
 
 ## MUTABLE DISCIPLINE
 
-Each gate condition is a mutable. Pre-emit run = expected value. Post-emit run = current value. Zero variance required. Any unresolved gate = absolute barrier. State-tracking mutables in conversation only, never written to files.
+Each gate condition is a mutable. Pre-emit run witnesses expected value. Post-emit run witnesses current value. Zero variance = resolved. Variance with unknown cause = new unknown = snake to `planning`.
+
+## CODE EXECUTION
+
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
+
+`exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`
+
+Only git in bash directly. `Bash(node/npm/npx/bun)` = violations. File writes via exec:nodejs + require('fs').
 
 ## PRE-EMIT DEBUGGING (before writing any file)
 
 1. Import actual module from disk via `exec:nodejs` — witness current on-disk behavior
-2. Run proposed logic in isolation WITHOUT writing any file — witness output with real inputs
-3. Debug failure paths with real error inputs
-4. For browser code: inject `__gm` globals, run interactions, dump captures, verify
+2. Run proposed logic in isolation WITHOUT writing — witness output with real inputs
+3. Debug failure paths with real error inputs — record expected values
 
-`exec:nodejs\nconst { fn } = await import('/abs/path')` — never rewrite logic inline.
+```
+exec:nodejs
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
 
-Pre-emit run failing → snake back to `gm-execute` skill, do not write.
+Pre-emit revealing unexpected behavior → new unknown → snake to `planning`.
 
 ## WRITING FILES
 
-Use `exec:nodejs` with `require('fs')`. Write only when every gate mutable is `resolved=true` simultaneously.
+`exec:nodejs` with `require('fs')`. Write only when every gate mutable is `resolved=true` simultaneously.
 
 ## POST-EMIT VERIFICATION (immediately after writing)
 
-1. Load actual modified file from disk via real import — not in-memory version
-2. Output must match pre-emit run exactly — any variance = regression
+1. Re-import the actual file from disk — not in-memory version
+2. Run same inputs as pre-emit — output must match exactly
 3. For browser: reload from disk, re-inject `__gm` globals, re-run, compare captures
-4. Variance → fix immediately, re-verify. Never advance with variance.
+4. Known variance → fix and re-verify | Unknown variance → snake to `planning`
 
-## GATE CONDITIONS (all must be true simultaneously)
+## GATE CONDITIONS (all true simultaneously before advancing)
 
-- Pre-emit run passed with real inputs and real error inputs
-- Post-emit verification matches pre-emit run exactly
+- Pre-emit debug passed with real inputs and error inputs
+- Post-emit verification matches pre-emit exactly
 - Hot reloadable: state outside reloadable modules, handlers swap atomically
 - Crash-proof: catch at every boundary, recovery hierarchy
 - No mocks/fakes/stubs anywhere
-- Files ≤200 lines
-- No duplicate code, no comments, no hardcoded values
-- Docs-code sync: CLAUDE.md reflects actual behavior
+- Files ≤200 lines, no duplicate code, no comments, no hardcoded values
+- CLAUDE.md reflects actual behavior
+
+## CODEBASE EXPLORATION
 
-## TOOL REFERENCE
+```
+exec:codesearch
+<natural language description>
+```
 
-**`exec:<lang>`** — Bash tool: `exec:<lang>\n<code>`. `exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`. Only git directly in bash.
+Alias: `exec:search`. Glob, Grep, Explore = blocked.
 
-**`agent-browser`** — Invoke `agent-browser` skill. Escalation: (1) `exec:agent-browser\n<js>` → (2) skill + `__gm` globals → (3) navigate/click → (4) screenshot last resort.
+## BROWSER DEBUGGING
 
-**`code-search`** — Invoke `code-search` skill. Glob/Grep/Explore blocked.
+Invoke `agent-browser` skill. Escalation: (1) `exec:agent-browser\n<js>` → (2) skill + `__gm` globals → (3) navigate/click → (4) screenshot last resort.
 
 ## SELF-CHECK (before and after each file)
 
-File ≤200 lines | No duplication | Pre-emit run passed | No mocks | No comments | Docs match | All spotted issues fixed immediately
+File ≤200 lines | No duplication | Pre-emit passed | No mocks | No comments | Docs match | All spotted issues fixed
 
 ## CONSTRAINTS
 
-**Never**: write before pre-emit run passes | advance with post-emit variance | skip doc sync | defer spotted issues | comments in code | hardcoded values
+**Never**: write before pre-emit passes | advance with post-emit variance | absorb surprises silently | comments | hardcoded values | defer spotted issues
 
-**Always**: pre-emit debug before writing | post-emit verify after writing | dual-side for full-stack | fix immediately | snake back when blocked
+**Always**: pre-emit debug before writing | post-emit verify from disk | snake to planning on any new unknown | fix immediately
 
 ---
 
 **→ FORWARD**: All gates pass → invoke `gm-complete` skill.
-**↩ SNAKE to EXECUTE**: logic wrong → invoke `gm-execute` skill.
-**↩ SNAKE to PLAN**: scope changed → invoke `planning` skill.
-**↩ SNAKE from VERIFY**: file broken → fix here, re-verify, re-advance.
+**↺ SELF-LOOP**: Known post-emit variance → fix, re-verify.
+**↩ SNAKE to EXECUTE**: Known logic error → invoke `gm-execute` skill.
+**↩ SNAKE to PLAN**: Any new unknown → invoke `planning` skill, restart chain.