gm-copilot-cli 2.0.187 → 2.0.189

package/skills/gm-execute/SKILL.md

@@ -1,57 +1,70 @@
 ---
 name: gm-execute
-description: EXECUTE phase. Hypothesis proving, chain decomposition, import-based debugging, browser protocols, ground truth enforcement. Invoke when entering EXECUTE or snaking back from EMIT/VERIFY.
+description: EXECUTE phase. Resolve all mutables via witnessed execution. Any new unknown triggers immediate snake back to planning — restart chain from PLAN.
 ---
 
 # GM EXECUTE — Resolving Every Unknown
 
-You are in the **EXECUTE** phase. Every mutable must resolve to KNOWN via witnessed execution before advancing.
+You are in the **EXECUTE** phase. Resolve every named mutable via witnessed execution. Any new unknown = stop, snake to `planning`, restart chain.
 
 **GRAPH POSITION**: `PLAN → [EXECUTE] → EMIT → VERIFY → COMPLETE`
-- **Entry chain**: prompt-submit hook → `gm` skill → `planning` → `gm-execute` (here). Also entered via snake from EMIT or VERIFY.
+- **Entry**: .prd exists with all unknowns named. Entered from `planning` or via snake from EMIT/VERIFY.
 
 ## TRANSITIONS
 
-**FORWARD (ladders)**:
-- All mutables resolved to KNOWN → invoke `gm-emit` skill
+**FORWARD**: All mutables KNOWN → invoke `gm-emit` skill
 
-**BACKWARD (snakes) — when to re-enter here**:
-- From EMIT: pre-emit debugging reveals logic error, hypothesis was wrong → snake back, re-run execution with corrected approach
-- From VERIFY: end-to-end debugging reveals runtime failure not caught in execution → snake back, re-execute with real system state
-- Self-loop: mutables still UNKNOWN after a pass → re-invoke `gm-execute` with broader debug scope. Never add stages.
+**SELF-LOOP**: Mutable still UNKNOWN after one pass → re-run with different angle (max 2 passes then snake)
 
-**WHEN TO SNAKE BACK TO PLAN instead**: discovered hidden dependencies that require .prd restructure → invoke `planning` skill
-
-**Sub-skills** (invoke from within EXECUTE):
-- Code exploration → invoke `code-search` skill
-- Browser/UI debugging → invoke `agent-browser` skill
-- Servers/workers/daemons → invoke `process-management` skill
+**BACKWARD**:
+- New unknown discovered → invoke `planning` skill immediately, restart chain
+- From EMIT: logic error → re-enter here, re-resolve mutable
+- From VERIFY: runtime failure → re-enter here, re-resolve with real system state
 
 ## MUTABLE DISCIPLINE
 
-Enumerate every unknown as a named mutable. Each: name, expected value, current value, resolution method. Execute → witness → assign → compare → zero variance = resolved. Unresolved = absolute barrier. Never narrate past an unresolved mutable. Trigger a snake if stuck.
+Each mutable: name | expected | current | resolution method. Execute → witness → assign → compare. Zero variance = resolved. Unresolved after 2 passes = new unknown = snake to `planning`. Never narrate past an unresolved mutable.
 
-## EXECUTION DENSITY
+## CODE EXECUTION
 
-Each run ≤15s, packed with every related hypothesis. Group all related unknowns into one run. Never one idea per run. Witnessed output = ground truth. Narrated assumption = nothing.
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
 
-**Parallel waves**: Launch ≤3 `gm:gm` subagents per wave via Task tool. Independent items simultaneously. Sequential execution of independent items = violation.
+`exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:c` | `exec:cpp` | `exec:java` | `exec:deno` | `exec:cmd`
 
-## CHAIN DECOMPOSITION
+Lang auto-detected if omitted. `cwd` sets directory. File I/O via exec:nodejs + require('fs'). Only git in bash directly. `Bash(node/npm/npx/bun)` = violations.
 
-Break every multi-step operation before running end-to-end:
-1. Number every distinct step (parse → validate → transform → write → confirm)
-2. Per step: input shape, output shape, success condition, failure condition
-3. Run step 1 in isolation → witness → assign mutable → proceed only when KNOWN
-4. Run step 2 with step 1's witnessed output. Repeat for each step.
-5. Debug adjacent pairs (1+2, 2+3...) for handoff correctness
-6. Only after all pairs pass: run full chain
+**Background tasks** (auto-backgrounded when execution exceeds 15s):
+```
+exec:sleep
+<task_id> [seconds]
+```
+```
+exec:status
+<task_id>
+```
+```
+exec:close
+<task_id>
+```
 
-Step failure → debug that step only, re-run from there. Never skip forward.
+**Runner** (PM2-backed — all activity visible in `pm2 list` and `pm2 monit` in user terminal):
+```
+exec:runner
+start|stop|status
+```
+
+## CODEBASE EXPLORATION
+
+```
+exec:codesearch
+<natural language description of what you need>
+```
+
+Alias: `exec:search`. Glob, Grep, Read-for-discovery, Explore, WebSearch = blocked.
 
 ## IMPORT-BASED DEBUGGING
 
-Always import actual codebase modules. Never rewrite logic inline — that debugs your reimplementation, not the real code.
+Always import actual codebase modules. Never rewrite logic inline.
 
 ```
 exec:nodejs
@@ -61,41 +74,48 @@ console.log(await fn(realInput));
 
 Witnessed import output = resolved mutable. Reimplemented output = UNKNOWN.
 
-## TOOL REFERENCE
+## EXECUTION DENSITY
 
-**`exec:<lang>`** — THE ONLY WAY TO RUN CODE. Bash tool body: `exec:<lang>\n<code>`. Languages: `exec:nodejs` (default) | `exec:python` | `exec:bash` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:c` | `exec:cpp` | `exec:java` | `exec:deno` | `exec:cmd`. `cwd` sets directory. File I/O via exec:nodejs with require('fs'). Only git directly in bash.
+Pack every related hypothesis into one run. Each run ≤15s. Witnessed output = ground truth. Narrated assumption = nothing.
 
-`Bash(node ...)` `Bash(npm ...)` `Bash(npx ...)` `Bash(bun ...)` = violations. Use `exec:<lang>`.
+Parallel waves: ≤3 `gm:gm` subagents via Task tool — independent items simultaneously, never sequentially.
 
-**`code-search`** — Invoke `code-search` skill. MANDATORY for all exploration. Glob/Grep/Read/Explore/WebSearch blocked. Fallback: `bun x codebasesearch <query>`.
+## CHAIN DECOMPOSITION
+
+Break every multi-step operation before running end-to-end:
+1. Number every distinct step
+2. Per step: input shape, output shape, success condition, failure mode
+3. Run each step in isolation — witness — assign mutable — KNOWN before next
+4. Debug adjacent pairs for handoff correctness
+5. Only when all pairs pass: run full chain end-to-end
 
-**`agent-browser`** — Invoke `agent-browser` skill. Escalation: (1) `exec:agent-browser\n<js>` first → (2) skill + `__gm` globals → (3) navigate/click → (4) screenshot last resort.
+Step failure revealing new unknown → snake to `planning`.
 
-**`process-management`** — Invoke `process-management` skill. MANDATORY for all servers/workers/daemons. Pre-check before start. Delete on completion.
+## BROWSER DEBUGGING
 
-## BROWSER DEBUGGING SCAFFOLD
+Invoke `agent-browser` skill. Escalation — exhaust each before advancing:
+1. `exec:agent-browser\n<js>` — query DOM/state. Always first.
+2. `agent-browser` skill + `__gm` globals — instrument and capture
+3. navigate/click/type — only when real events required
+4. screenshot — last resort
 
-Inject before any browser state assertion:
+`__gm` scaffold:
 ```js
 window.__gm = { captures: [], log: (...a) => window.__gm.captures.push({t:Date.now(),a}), assert: (l,c) => { window.__gm.captures.push({l,pass:!!c,val:c}); return !!c; }, dump: () => JSON.stringify(window.__gm.captures,null,2) };
 ```
 
-## DUAL-SIDE DEBUGGING
-
-Backend via `exec:nodejs`, frontend via `agent-browser` + `__gm`. Neither substitutes the other. Single-side = UNKNOWN mutable = blocked gate.
-
 ## GROUND TRUTH
 
-Real services, real API responses, real timing. On discovering mocks/fakes/stubs: delete immediately, implement real paths. No .test.js/.spec.js files. No mock files. Delete on discovery.
+Real services, real data, real timing. Mocks/fakes/stubs = delete immediately. No .test.js/.spec.js. Delete on discovery.
 
 ## CONSTRAINTS
 
-**Never**: `Bash(node/npm/npx/bun/python)` | fake data | mock files | Glob/Grep/Explore for discovery | puppeteer/playwright | screenshot before JS exhausted | independent items sequentially
+**Never**: `Bash(node/npm/npx/bun)` | fake data | mock files | Glob/Grep/Explore | sequential independent items | absorb surprises silently
 
-**Always**: import real modules | witness every hypothesis | delete mocks on discovery | fix immediately | snake back when blocked
+**Always**: witness every hypothesis | import real modules | snake to planning on any new unknown | fix immediately on discovery
 
 ---
 
 **→ FORWARD**: All mutables KNOWN → invoke `gm-emit` skill.
-**↩ SNAKE to EXECUTE**: hypothesis wrong → re-invoke `gm-execute` with corrected approach.
-**↩ SNAKE to PLAN**: .prd needs restructure → invoke `planning` skill.
+**↺ SELF-LOOP**: Still UNKNOWN → re-run (max 2 passes).
+**↩ SNAKE to PLAN**: Any new unknown → invoke `planning` skill, restart chain.

package/skills/planning/SKILL.md

@@ -1,82 +1,84 @@
 ---
 name: planning
-description: PRD construction for work planning. Compulsory in PLAN phase. Builds .prd file as frozen dependency graph of every possible work item before execution begins. Triggers on any new task, multi-step work, or when gm enters PLAN state.
+description: Mutable discovery and PRD construction. Invoke at session start and any time new unknowns surface during execution. Loop until no new mutables are discovered.
 allowed-tools: Write
 ---
 
-# PRD Construction
+# PRD Construction — Mutable Discovery Loop
 
-You are in the **PLAN** phase. Build the .prd before any execution begins.
+You are in the **PLAN** phase. Your job is to discover every unknown before execution begins.
 
 **GRAPH POSITION**: `[PLAN] → EXECUTE → EMIT → VERIFY → COMPLETE`
-- **Session entry chain**: prompt-submit hook → `gm` skill → `planning` skill (here).
+- **Entry chain**: prompt-submit hook → `gm` skill → `planning` skill (here).
+- **Also entered**: any time a new unknown surfaces in EXECUTE, EMIT, or VERIFY.
 
 ## TRANSITIONS
 
-**FORWARD (ladders)**:
-- .prd written → invoke `gm-execute` skill to begin EXECUTE
+**FORWARD**:
+- No new mutables discovered in latest pass → .prd is complete → invoke `gm-execute` skill
 
-**BACKWARD (snakes) — when to return here**:
-- From EXECUTE: discovered unknowns require .prd restructure → re-invoke `planning` skill, revise .prd, re-enter EXECUTE
-- From EMIT: scope changed, current .prd items no longer match what needs to be done → re-invoke `planning` skill
-- From VERIFY: end-to-end reveals requirements were wrong → re-invoke `planning` skill, rewrite affected items
+**SELF-LOOP (stay in PLAN)**:
+- Each planning pass may surface new unknowns → add them to .prd → plan again
+- Loop until a full pass produces zero new items
+- Do not advance to EXECUTE while unknowns remain discoverable through reasoning alone
 
-**When to snake back to PLAN**: requirements changed | discovered hidden dependencies | .prd items are wrong/missing | scope expanded beyond current .prd
+**BACKWARD (snakes back here from later phases)**:
+- From EXECUTE: execution reveals an unknown not in .prd → snake here, add it, re-plan
+- From EMIT: scope shifted mid-write → snake here, revise affected items, re-plan
+- From VERIFY: end-to-end reveals requirement was wrong → snake here, rewrite items, re-plan
 
-## Purpose
+## WHAT PLANNING MEANS
 
-The `.prd` is the single source of truth for remaining work. A frozen dependency graph capturing every possible item — steps, substeps, edge cases, corner cases, dependencies, transitive dependencies, unknowns, assumptions, decisions, trade-offs, acceptance criteria, scenarios, failure paths, recovery paths, integration points, state transitions, error conditions, boundary conditions, configuration variants, environment differences, backwards compatibility, rollback paths, verification steps.
+Planning = exhaustive mutable discovery. For every aspect of the task ask:
+- What do I not know? → name it as a mutable
+- What could go wrong? → name it as an edge case item
+- What depends on what? → map blocking/blockedBy
+- What assumptions am I making? → validate each as a mutable
 
-Longer is better. Missing items means missing work.
+**Iterate until**: a full reasoning pass adds zero new items to .prd.
 
-## File Rules
+Categories of unknowns to enumerate: file existence | API shape | data format | dependency versions | runtime behavior | environment differences | error conditions | concurrency | integration points | backwards compatibility | rollback paths | deployment steps | verification criteria
 
-Path: exactly `./.prd` in current working directory. No variants. Valid JSON.
+## .PRD SCHEMA
 
-## Item Schema
+Path: exactly `./.prd` in current working directory. Valid JSON array.
 
 ```json
 {
   "id": "descriptive-kebab-id",
-  "subject": "Imperative verb describing outcome",
+  "subject": "Imperative verb phrase — what must be true when done",
   "status": "pending",
-  "description": "What must be true when this is done",
-  "blocking": ["ids-this-prevents"],
-  "blockedBy": ["ids-that-must-finish-first"],
+  "description": "Precise completion criterion",
+  "blocking": ["ids this prevents from starting"],
+  "blockedBy": ["ids that must complete first"],
   "effort": "small|medium|large",
-  "category": "feature|bug|refactor|docs|infra",
-  "acceptance": ["measurable criteria"],
-  "edge_cases": ["known complications"]
+  "category": "feature|bug|refactor|infra",
+  "acceptance": ["measurable, binary criteria"],
+  "edge_cases": ["known failure modes and boundary conditions"]
 }
 ```
 
-**Subject**: imperative form. **Status**: `pending` → `in_progress` → `completed`. **Effort**: `small` (<15min) | `medium` (<45min) | `large` (1h+). **Blocking/blockedBy**: bidirectional, every dependency explicit.
+**Status flow**: `pending` → `in_progress` → `completed` (completed items are removed from file).
+**Effort**: `small` = single execution, under 15min | `medium` = 2-3 rounds, under 45min | `large` = multiple rounds, over 1h.
+**blocking/blockedBy**: always bidirectional. Every dependency must be explicit in both directions.
 
-## Construction
+## EXECUTION WAVES
 
-1. Enumerate every possible unknown as a work item.
-2. Map every possible dependency (blocking/blockedBy).
-3. Group independent items into parallel waves (max 3 per wave).
-4. Capture every edge case as either a separate item or edge_case field.
-5. Write `./.prd` to disk.
-6. **FREEZE** — no additions after creation. Only mutation: removing finished items.
+Independent items (empty `blockedBy`) run in parallel waves of ≤3 subagents.
+- Find all pending items with empty `blockedBy`
+- Launch ≤3 parallel `gm:gm` subagents via Task tool
+- Each subagent handles one item: resolves it, witnesses output, removes from .prd
+- After each wave: check newly unblocked items, launch next wave
+- Never run independent items sequentially. Never launch more than 3 at once.
 
-## Execution
+## COMPLETION CRITERION
 
-1. Find all `pending` items with empty `blockedBy`.
-2. Launch ≤3 parallel subagents (`subagent_type: gm:gm`) per wave.
-3. Each subagent completes one item, verifies via witnessed execution.
-4. On completion: remove item from `.prd`, write updated file.
-5. Check for newly unblocked items. Launch next wave.
-6. Continue until `.prd` is empty.
+.prd is ready when: one full reasoning pass produces zero new items AND all items have explicit acceptance criteria AND all dependencies are mapped.
 
-Never execute independent items sequentially. Never launch more than 3 at once.
-
-## Completion
-
-`.prd` must be empty at COMPLETE. Skip this skill if task is trivially single-step (under 5 minutes, no dependencies, no unknowns).
+**Skip planning entirely** if: task is single-step, trivially bounded, zero unknowns, under 5 minutes.
 
 ---
 
-**→ FORWARD**: .prd written → invoke `gm-execute` skill.
-**↩ SNAKE**: re-invoke `planning` if requirements change at any later phase.
+**→ FORWARD**: No new mutables → invoke `gm-execute` skill.
+**↺ SELF-LOOP**: New items discovered → add to .prd → plan again.
+**↩ SNAKE here**: New unknown surfaces in any later phase → add it, re-plan, re-advance.

package/tools.json

@@ -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",
   "tools": [
     {