gm-copilot-cli 2.0.631 → 2.0.633

package/skills/planning/SKILL.md

@@ -6,115 +6,82 @@ allowed-tools: Write
 
 # Planning — State Machine Orchestrator
 
-Root of all work. Runs `PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS → COMPLETE`.
+Runs `PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS → COMPLETE`.
 
-**Entry**: prompt-submit hook → `gm` agent → invoke `planning` skill (here). Also re-entered any time a new unknown surfaces in any phase.
-
-## WHERE YOU ARE
-
-Phase where work shape still unknown. Codebase scans, `exec:codesearch` queries, quick imports to probe APIs = all executions. Execution contract in `gm-execute`; protocols not fresh → runs drift (reimplement over import, narrate over witness). Load first.
+Entry: prompt-submit hook → `gm` → here. Re-enter on any new unknown in any phase.
 
 ## UNKNOWNS = PRODUCT
 
-Output of this phase ≠ task list. Output = enumeration of every fault surface work could fail on. Each unknown named + resolved → cheaper downstream. Each unknown skipped → EMIT/VERIFY surprise → snake back anyway at higher cost.
-
-**Unknown emerges later (EXECUTE, EMIT, VERIFY) → return here. Not failure — machine working as designed.** Later-phase unknown means mutable map incomplete. Come back. Think laterally — what else could this touch, what invariant assumed, what subsystem unexamined? Enumerate newly-visible fault surfaces. Only then push forward.
-
-Patch-around-unknowns-in-place = compounding silent-failure debt. Regress early = stay inside contract.
+Output = every fault surface work could fail on. Unknown named+resolved = cheaper downstream. Unknown skipped = EMIT/VERIFY surprise = snake back at higher cost.
 
-## FRAGILE LEARNINGS — MEMORIZE ON RESOLUTION (HARD RULE)
+Later-phase unknown → return here. Not failure — machine working. Patch-around-in-place = compounding debt.
 
-Every unknown resolved in any phase (existingImpl absent, dep version confirmed, API shape witnessed, env quirk observed, CI failure root-caused, build flag required, user preference stated) = fact that dies on context compaction unless handed off. Not optional. Not batched at end. **Memorize at the moment of resolution, before the next tool call.**
+## MEMORIZE — HARD RULE
 
-**Trigger contract — memorize fires when ANY of these occur**:
-- An `exec:` run produces output that answers a prior "I don't know" / "let me check"
-- A code read confirms or refutes an assumption about existing structure
-- A CI log reveals the root cause of a failure
-- User states a preference, constraint, deadline, or decision
-- A fix works and the reason it worked is non-obvious (would be forgotten next session)
-- An environment / tooling quirk bites once (blocked tools, path oddities, platform differences)
+Every unknown resolved → memorize same turn. Not batched, not deferred.
 
-**Enforcement**:
-- Regardless of phase, a resolved unknown → spawn `memorize` subagent **in the same turn** as the resolution. Do not wait for phase end. Do not batch across multiple facts — one call per fact keeps classification clean.
-- Run in background (`run_in_background=true`). Non-blocking. Continue work in the same message.
-- If you notice at end of turn that an unknown resolved earlier was not memorized, spawn it now. Catching up is allowed. Skipping is not.
+Triggers: exec: output answers prior unknown | code read confirms/refutes | CI log reveals root cause | user states preference/constraint | fix worked non-obviously | env quirk observed.
 
-**Invocation (copy verbatim, substitute the fact)**:
 ```
-Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<single resolved fact with enough context for a cold-start agent to use it>')
+Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')
 ```
 
-**Parallelization**: multiple unknowns resolved in one turn → spawn multiple memorize agents in the **same message** (parallel tool blocks). Never serialize them.
-
-**Violations = memory leak**. If you leave the turn with a resolved unknown un-memorized, the fact is gone on next compaction. That is the failure mode this rule prevents. Treat every exit from a turn without memorize-catch-up as a bug.
+Multiple facts in one turn → parallel Agent calls in ONE message. End-of-turn: scan for missed → spawn now.
 
 ## STATE MACHINE
 
-**FORWARD**: PLAN complete → `gm-execute` | EXECUTE complete → `gm-emit` | EMIT complete → `gm-complete` | VERIFY .prd remains → `gm-execute` | VERIFY .prd empty+pushed → `update-docs`
+**FORWARD**: PLAN → `gm-execute` | EXECUTE → `gm-emit` | EMIT → `gm-complete` | VERIFY .prd remains → `gm-execute` | VERIFY .prd empty+pushed → `update-docs`
 
 **REGRESSIONS**: new unknown at any state → re-invoke `planning` | EXECUTE unresolvable 2 passes → `planning` | EMIT logic error → `gm-execute` | EMIT new unknown → `planning` | VERIFY broken output → `gm-emit` | VERIFY logic wrong → `gm-execute` | VERIFY new unknown → `planning`
 
-**Runs until**: .gm/prd.yml empty AND git clean AND all pushes confirmed AND CI green.
+Runs until: .gm/prd.yml empty AND git clean AND all pushes confirmed AND CI green.
+
+**Cannot stop while**: .gm/prd.yml has items | git has uncommitted changes | git has unpushed commits.
 
-## ENFORCEMENT — COMPLETE EVERY TASK END-TO-END
+## SKIP PLANNING (DEFAULT for small work)
 
-**Cannot respond or stop while**:
-- .gm/prd.yml exists and has items
-- git has uncommitted changes
-- git has unpushed commits
+Skip if ANY apply:
+- Single-file, single-concern edit
+- Task trivially bounded, under ~5 min
+- User gave explicit surgical instructions
+- Bug fix with identified root cause
+- Zero unknowns
 
-The skill chain MUST be followed completely end-to-end without exception. Partial execution = violation. After every phase: read .prd, check git, invoke next skill.
+Heavy ceremony (PRD + parallel subagents) for multi-file architectural work or genuinely unknown fault surfaces. If new unknown surfaces mid-work, THAT is when to regress — not preemptively.
 
 ## PLAN PHASE — MUTABLE DISCOVERY
 
-Planning = exhaustive fault-surface enumeration. For every aspect of the task:
+For every aspect of the task:
 - What do I not know? → mutable (UNKNOWN)
 - What could go wrong? → edge case item with failure mode
-- What depends on what? → blocking/blockedBy mapped explicitly
-- What assumptions am I making? → each = unwitnessed hypothesis = mutable until execution proves it
-
-**Fault surfaces**: file existence | API shape | data format | dependency versions | runtime behavior | environment differences | error conditions | concurrency hazards | integration seams | backwards compatibility | rollback paths | deployment steps | CI/CD correctness
+- What depends on what? → blocking/blockedBy mapped
+- What assumptions am I making? → each = unwitnessed hypothesis = mutable
 
-**Route family (`governance` skill)**: every `.prd` item is tagged with at least one of the 7 route families — `grounding | reasoning | state | execution | observability | boundary | representation`. The family disciplines the repair move. Bug in `grounding` does not get a `reasoning` fix; bug in `boundary` does not get a `state` fix. Mis-routed repair = wasted EXECUTE pass + snake back to PLAN. Add `route_family:` to the item YAML.
+Fault surfaces: file existence | API shape | data format | dependency versions | runtime behavior | environment differences | error conditions | concurrency hazards | integration seams | backwards compatibility | rollback paths | CI/CD correctness
 
-**Failure-mode mapping**: cross-reference against the 16-failure taxonomy in `governance`. If the fault you are enumerating does not map to any entry, either you have found a 17th mode (add to the governance skill) or the fault is not yet named sharply enough — refine until it maps. Items with no failure-mode mapping SHIP silent bugs.
+**Route family** (`governance`): tag every `.prd` item with family — grounding|reasoning|state|execution|observability|boundary|representation. Mis-routed repair = wasted EXECUTE pass.
 
-**Competing routes stay live**: if two route families plausibly explain the same symptom, keep both alive in the PRD until witnessed execution makes one dominant. Collapsing to one route pre-witness = route-into-authorization leak (see `governance` — the first of five refused collapses).
+**Failure-mode mapping**: cross-reference 16-failure taxonomy. No mapping = unexamined surface = silent bug.
 
-**MANDATORY CODEBASE SCAN**: For every planned item, add `existingImpl=UNKNOWN`. Resolve via exec:codesearch. Existing code serving same concern → consolidation task, not addition. `exec:codesearch` indexes PDFs page-by-page alongside source — spec PDFs, papers, vendor manuals, and RFCs are searchable as code. When planning against a protocol, hardware, or compliance requirement, search the PDF corpus the same way you search source: two words, iterate. A constraint the PRD is missing because it only lives in a PDF is a fault surface — enumerate doc PDFs as scan targets during mutable discovery.
+**Competing routes stay live** until witnessed execution makes one dominant. Pre-witness collapse = route-into-authorization leak.
 
-**EXIT PLAN**: zero new unknowns in last pass AND all .prd items have explicit acceptance criteria AND all dependencies mapped → launch subagents or invoke `gm-execute`.
+**MANDATORY CODEBASE SCAN**: For every item, `existingImpl=UNKNOWN`. Resolve via exec:codesearch. Existing code serving same concern → consolidation, not addition. PDFs indexed page-by-page — search specs same way you search source.
 
-**SELF-LOOP**: new items discovered → add to .prd → plan again.
+**EXIT PLAN**: zero new unknowns last pass AND all .prd items have acceptance criteria AND dependencies mapped → launch subagents or invoke `gm-execute`.
 
-**Skip planning entirely** (this is the DEFAULT for small work) if ANY of these apply:
-- Single-file, single-concern edit
-- Task is trivially bounded and under ~5 minutes
-- User gave explicit surgical instructions ("change X to Y")
-- Bug fix where root cause is already identified
-- Zero unknowns / no mutables to resolve
-
-Heavy ceremony (PRD + parallel subagents) is for multi-file architectural work or genuinely unknown fault surfaces. Writing a 7-item PRD for a 3-line change is waste. Err toward skipping — if a new unknown surfaces mid-work, THAT is when you regress to planning, not preemptively.
-
-**Contrast examples:**
-- "Fix the hold-detect logic at apcKey25.cpp:163" → SKIP planning. Read, edit, done.
-- "Add drift correction and watchdog and observability across the USB audio path" → DO plan. Multi-file, multiple unknowns.
-
-## OBSERVABILITY ENUMERATION — MANDATORY EVERY PASS
+## OBSERVABILITY — MANDATORY EVERY PASS
 
-During every planning pass, enumerate every possible aspect of the app's runtime observability that can be improved. The goal is permanent structures — not ad-hoc logs — that make any future debugging session start from a complete, live picture of system state.
+Enumerate every runtime observability gap:
 
-**Server-side permanent structures**: Every internal subsystem — state machine, queue, cache, connection pool, active task map, process registry, RPC handler, hook dispatcher — must expose a named, queryable inspection endpoint (e.g. `/debug/<subsystem>`). State must be readable, filterable, and ideally modifiable without restart. Profiling hooks on every hot path. Structured logs with subsystem tag, severity, and timestamp — filterable at runtime by subsystem, not just log level. Any internal state that requires a restart to inspect is an observability gap.
+**Server**: every subsystem exposes `/debug/<subsystem>`. State readable/filterable without restart. Structured logs with subsystem+severity+timestamp.
 
-**Client-side permanent structures**: `window.__debug` must be a live, structured registry — not a dump. Every component's state, every active request, every event queue, every WebSocket connection, every rendered prop, every error boundary — all addressable by key, all queryable without refreshing. New modules register themselves into `window.__debug` on mount and deregister on unmount. Any execution path not traceable via `window.__debug` is an observability gap.
+**Client**: `window.__debug` is live structured registry. Every component/request/queue/connection addressable by key. Modules register on mount, deregister on unmount.
 
-**Permanent vs ad-hoc**: `console.log` = ad-hoc = not observability. A structured logger with subsystem routing = permanent. `window.__debug.myModule.state` = permanent. `window.__debug = { ...window.__debug, tmp: x }` = ad-hoc = not acceptable. Permanent structures survive deploys and accumulate diagnostic value across sessions.
-
-**Mandate**: on discovery of any observability gap → immediately add a .prd item. Observability improvements are highest-priority — never deferred. The agent must be able to see specifically anything it wants and nothing else — no guessing, no blind spots.
+`console.log` = ad-hoc = not observability. `window.__debug.module.state` = permanent. Discovery of gap → add .prd item immediately. Observability = highest priority, never deferred.
 
 ## .PRD FORMAT
 
-Path: `./.gm/prd.yml`. YAML via `exec:nodejs` (use `fs.writeFileSync`). Ensure `.gm/` dir exists before writing. Delete when empty — never leave empty file. Delete `.gm/` dir when completely empty.
+Path: `./.gm/prd.yml`. Write via `exec:nodejs` + `fs.writeFileSync`. Delete when empty; delete `.gm/` when completely empty.
 
 ```yaml
 - id: kebab-id
@@ -135,9 +102,7 @@ Path: `./.gm/prd.yml`. YAML via `exec:nodejs` (use `fs.writeFileSync`). Ensure `
     - failure mode
 ```
 
-`route_family`, `failure_modes`, `route_fit`, `authorization` are defined in the `governance` skill. Required for items with emission impact (architecture, public API, contract change). Small surgical edits may omit. `authorization` starts `none`; gm-execute raises it to `weak_prior` on hypothesis, `witnessed` only when execution has proven it.
-
-Status: `pending` → `in_progress` → `completed` (remove completed items). Effort: small <15min | medium <45min | large >1h.
+Status: pending → in_progress → completed (remove completed). Effort: small <15min | medium <45min | large >1h.
 
 ## PARALLEL SUBAGENT LAUNCH
 
@@ -145,81 +110,43 @@ After .prd written, launch ≤3 parallel `gm:gm` subagents for all independent i
 
 `Agent(subagent_type="gm:gm", prompt="Work on .prd item: <id>. .prd path: <path>. Item: <full YAML>.")`
 
-After each wave: read .prd, find newly unblocked items, launch next wave. Exception: browser tasks serialize.
-
-When parallelism not applicable: invoke `gm-execute` skill directly.
-
-## MUTABLE DISCIPLINE
+After each wave: read .prd, find newly unblocked, launch next. Browser tasks serialize.
 
-Each mutable: name | expected | current | resolution method. Resolve by witnessed execution only. Zero variance = resolved. Unresolved after 2 passes = new unknown = re-invoke `planning`. Mutables live in conversation only.
+When parallelism not applicable: invoke `gm-execute` directly.
 
 ## CODE EXECUTION
 
-`exec:<lang>` only. Bash body: `exec:<lang>\n<code>`
+`exec:<lang>` only via Bash tool. File I/O: exec:nodejs + require('fs'). Git only in Bash directly. Never Bash(node/npm/npx/bun).
 
-`exec:nodejs` | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:c` | `exec:cpp` | `exec:java` | `exec:deno` | `exec:cmd`
-
-File I/O: exec:nodejs + require('fs'). Git only in Bash directly. `Bash(node/npm/npx/bun)` = violation.
-
-Pack runs: `Promise.allSettled` for parallel ops. Each idea its own try/catch. Under 12s per call.
-
-Background: `exec:sleep <id>` | `exec:status <id>` | `exec:close <id>`. Runner: `exec:runner start|stop|status`.
+Pack runs: `Promise.allSettled` for parallel. Each idea its own try/catch. Under 12s per call.
 
 ## CODEBASE EXPLORATION
 
-`exec:codesearch` only. Glob/Grep/Read/Explore/WebSearch = hook-blocked. Start 2 words → change one word → add third → minimum 4 attempts before concluding absent.
-
-## BROWSER AUTOMATION
-
-Invoke `browser` skill. Escalation: (1) `exec:browser <js>` → (2) browser skill → (3) navigate/click → (4) screenshot last resort. Browser tasks serialize — one Chrome instance per project.
-
-## SKILL REGISTRY
-
-`gm-execute` → `gm-emit` → `gm-complete` → `update-docs` | `browser` | `governance` (read once per session) | `memorize` (sub-agent, background only)
-
-`governance` carries the route-discovery / weak-prior-bridge / legitimacy-gate model, 7 route families, 16 failure taxonomy, 4 state planes, ΔS/λ/ε/Coverage metrics, and the 8-case governance stress suite. Load once per session at the top of `planning` so protocols stay fresh across phases.
-
-`memorize`: `Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<what>')`
+`exec:codesearch` only. Glob/Grep/Read/Explore = hook-blocked. Start 2 words → change one → add third → minimum 4 attempts before concluding absent.
 
 ## MANDATORY DEV WORKFLOW
 
-No comments. No scattered test files. 200-line limit — split before continuing. Fail loud. No duplication. Scan before every edit. Duplicate concern = regress to PLAN. Errors throw with context — no `|| default`, no `catch { return null }`. `window.__debug` exposes all client state. AGENTS.md via memorize only. CHANGELOG.md: append per commit.
-
-**Minimal code / maximal DX process**: Before writing any logic, run this process in order — stop at the first step that resolves the need:
-1. **Native first** — does the language or runtime already do this? Use it exactly as designed.
-2. **Library second** — does an existing dependency already solve this pattern? Use its API directly.
-3. **Structure third** — can the problem be encoded as data (map, table, pipeline) so the structure enforces correctness and eliminates branching entirely?
-4. **Write last** — only author new logic when the above three are exhausted. New logic = new surface area = new bugs.
+No comments. No scattered test files. 200-line limit. Fail loud. No duplication. Scan before edit. AGENTS.md via memorize only. CHANGELOG.md: append per commit.
 
-When structure eliminates a whole class of wrong states — name that pattern explicitly. Dispatch tables replacing switch chains, pipelines replacing loop-with-accumulator, maps replacing if/else forests — these are not just style preferences, they are correctness properties. Code that cannot be wrong because of how it is shaped is the goal. Readable top-to-bottom without mental simulation = done right. Requires decoding = not done.
+**Minimal code process** (stop at first that resolves need):
+1. Native — does language/runtime do this? Use it.
+2. Library — existing dep solve this? Use its API.
+3. Structure — encode as data (map/table/pipeline)? Make structure enforce correctness.
+4. Write — only when 1-3 exhausted.
 
 ## SINGLE INTEGRATION TEST POLICY
 
-Every project maintains exactly one `test.js` at project root. 200-line max. No other test files anywhere — no `.test.js`, `.spec.js`, `__tests__/`, `fixtures/`, `mocks/`. Delete all scattered tests on discovery and consolidate coverage into `test.js`.
-
-**test.js replaces all unit tests.** It tests the real system end-to-end with real data. No mocks, no stubs, no test frameworks. Plain node assertions or process exit codes.
-
-**Creation**: if `test.js` does not exist, create it during EXECUTE phase covering all testable surface of current work.
+One `test.js` at project root. 200-line max. No .test.js, .spec.js, __tests__/, fixtures/, mocks/. No frameworks, no mocks, no stubs — plain assertions, real data, real system.
 
-**Maintenance**: every code change that adds or modifies behavior must update `test.js` to cover it. Every bug fix must add a regression case that would have caught the bug.
-
-**Structure**: group by subsystem, each subsystem gets a section. When approaching 200 lines, compress older stable tests into tighter assertions to make room for new coverage.
-
-**Execution**: `gm-complete` runs `test.js` before allowing completion. Failure = regression to EXECUTE.
+`gm-complete` runs test.js before completion. Failure = regression to EXECUTE. Every behavior change updates test.js. Every bug fix adds regression case.
 
 ## RESPONSE POLICY
 
-Always terse. Technical substance stays. Fluff dies. Drop articles, filler, pleasantries, hedging. Fragments OK. Short synonyms. Technical terms exact. Pattern: `[thing] [action] [reason]. [next step].`
-
-Code, commits, and PR descriptions write in normal prose. Security warnings, destructive confirmations, and genuinely ambiguous sequences also drop terseness. Everything else stays terse.
+Terse. Drop filler. Fragments OK. Pattern: `[thing] [action] [reason]. [next step].`
+Code/commits/PRs = normal prose.
 
 ## CONSTRAINTS
 
-**Tier 0**: no_crash, no_exit, ground_truth_only, real_execution, fail_loud
-**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)` | skip planning | partial execution | stop while .gm/prd.yml has items | stop while git dirty | sequential independent items | screenshot before JS exhausted | fallback/demo modes | silently swallow errors | duplicate concern | leave comments | create scattered test files (only root test.js) | write if/else chains where a map or pipeline suffices | write one-liners that require decoding | branch on enumerated cases when a dispatch table exists | **leave a resolved unknown un-memorized** | batch memorize calls until end of turn | serialize parallel memorize spawns
+**Never**: Bash(node/npm/npx/bun) | skip planning | partial execution | stop while .prd has items | stop while git dirty | sequential independent items | screenshot before JS exhausted | fallback/demo modes | swallow errors | duplicate concern | leave comments | scattered test files | if/else chains where map suffices | one-liners that require decoding | leave resolved unknown un-memorized | batch memorize | serialize memorize spawns
 
-**Always**: invoke named skill at every state transition | regress to planning on any new unknown | witnessed execution only | scan codebase before edits | enumerate every possible observability improvement every planning pass | follow skill chain completely end-to-end on every task without exception | prefer dispatch tables over switch/if chains | prefer pipelines over loop-with-accumulator | make wrong states structurally impossible | name patterns when structure eliminates a whole class of bugs | **spawn `memorize` the same turn an unknown resolves** | parallel-spawn one memorize per fact when multiple resolve together | end-of-turn self-check: any resolved unknowns un-memorized? → spawn now before handing control back
+**Always**: invoke Skill at every transition | regress to planning on new unknown | witnessed execution only | scan before edits | enumerate observability gaps every pass | follow chain end-to-end | prefer dispatch tables | prefer pipelines | make wrong states unrepresentable | spawn memorize same turn unknown resolves | end-of-turn self-check

package/skills/ssh/SKILL.md

@@ -5,28 +5,15 @@ description: Run shell commands on remote SSH hosts via exec:ssh. Reads targets
 
 # exec:ssh — Remote SSH Execution
 
-**Use gm subagents for all independent work items. Invoke all skills in the chain: planning → gm-execute → gm-emit → gm-complete → update-docs.**
-
-
-Runs shell commands on a remote host over SSH. No shell open, no manual connection — just write the command.
+Runs shell commands on remote host. No manual connection needed.
 
 ## Setup
 
-Create `~/.claude/ssh-targets.json`:
-
+`~/.claude/ssh-targets.json`:
 ```json
 {
-  "default": {
-    "host": "192.168.1.10",
-    "port": 22,
-    "username": "pi",
-    "password": "yourpassword"
-  },
-  "prod": {
-    "host": "10.0.0.1",
-    "username": "ubuntu",
-    "keyPath": "/home/user/.ssh/id_rsa"
-  }
+  "default": { "host": "192.168.1.10", "port": 22, "username": "pi", "password": "pass" },
+  "prod": { "host": "10.0.0.1", "username": "ubuntu", "keyPath": "/home/user/.ssh/id_rsa" }
 }
 ```
 
@@ -39,39 +26,28 @@ exec:ssh
 <shell command>
 ```
 
-Target a named host with `@name` on the first line:
-
+Named host with `@name` on first line:
 ```
 exec:ssh
 @prod
 sudo systemctl restart myapp
 ```
 
-Multi-line scripts work:
-
-```
-exec:ssh
-cd /var/log && tail -20 syslog
-```
-
 ## Process Persistence
 
-SSH sessions kill child processes on close. To keep a process running after the command returns:
-
+SSH kills child processes on close. To persist:
 ```
 exec:ssh
-sudo systemctl reset-failed myunit 2>/dev/null; systemd-run --unit=myunit bash -c 'your-long-running-command'
+sudo systemctl reset-failed myunit 2>/dev/null; systemd-run --unit=myunit bash -c 'your-command'
 ```
 
-Always call `systemctl reset-failed <unit>` before reusing a unit name, or use a unique timestamped name:
-
+Unique name:
 ```
 exec:ssh
 systemd-run --unit=job-$(date +%s) bash -c 'nohup myprogram &'
 ```
 
-Fallback if systemd unavailable:
-
+Fallback (no systemd):
 ```
 exec:ssh
 setsid nohup bash -c 'myprogram > /tmp/out.log 2>&1' &
@@ -79,11 +55,8 @@ setsid nohup bash -c 'myprogram > /tmp/out.log 2>&1' &
 
 ## Dependency
 
-Requires `ssh2` npm package. Install in `~/.claude/gm-tools`:
-
+Requires `ssh2` npm package in `~/.claude/gm-tools`:
 ```
 exec:bash
 cd ~/.claude/gm-tools && npm install ssh2
 ```
-
-The plugin searches: `~/.claude/gm-tools/node_modules/ssh2`, `~/.claude/plugins/node_modules/ssh2`, then global.

package/skills/update-docs/SKILL.md

@@ -3,111 +3,58 @@ name: update-docs
 description: UPDATE-DOCS phase. Refresh README.md, AGENTS.md, and docs/index.html to reflect changes made this session. Commits and pushes doc updates. Terminal phase — declares COMPLETE.
 ---
 
-# GM UPDATE-DOCS — Documentation Refresh
+# GM UPDATE-DOCS
 
-You are in the **UPDATE-DOCS** phase. Feature work is verified and pushed. Refresh all documentation to match the actual codebase state right now.
+GRAPH: `PLAN → EXECUTE → EMIT → VERIFY → [UPDATE-DOCS] → COMPLETE`
+Entry: feature verified, committed, pushed. From `gm-complete`.
 
-**GRAPH POSITION**: `PLAN → EXECUTE → EMIT → VERIFY → [UPDATE-DOCS] → COMPLETE`
-- **Entry**: Feature work verified, committed, and pushed. Entered from `gm-complete`.
+**FORWARD**: docs updated + committed + pushed → COMPLETE
+**BACKWARD**: unknown architecture change → `planning`
 
-## TRANSITIONS
-
-**FORWARD**: All docs updated, committed, and pushed → COMPLETE (session ends)
-
-**BACKWARD**:
-- Diff reveals unknown architecture change → invoke `planning` skill, restart chain
-- Doc write fails post-emit verify → fix and re-verify before advancing
-
-## EXECUTION SEQUENCE
-
-**Step 1 — Understand what changed**:
+## Sequence
 
+**1 — What changed**:
 ```
 exec:bash
 git log -5 --oneline
 git diff HEAD~1 --stat
 ```
 
-Witness which files changed. Identify doc-sensitive changes: new skills, new states in the state machine, new platforms, modified architecture, new constraints, renamed files.
-
-**Step 2 — Read current docs**:
-
+**2 — Read current docs**:
 ```
 exec:nodejs
 const fs = require('fs');
-['README.md', 'AGENTS.md', 'docs/index.html',
- 'gm-starter/agents/gm.md'].forEach(f => {
+['README.md', 'AGENTS.md', 'docs/index.html', 'gm-starter/agents/gm.md'].forEach(f => {
   try { console.log(`=== ${f} ===\n` + fs.readFileSync(f, 'utf8')); }
   catch(e) { console.log(`MISSING: ${f}`); }
 });
 ```
 
-Identify every section that no longer matches the actual codebase state.
-
-**Step 3 — Write updated docs**:
-
-Write only sections that changed. Do not rewrite unchanged content. Rules per file:
-
-**README.md**: platform count matches adapters in `platforms/`, skill tree diagram matches current state machine, quick start commands work.
-
-**AGENTS.md**: Launch memorize sub-agent in background with session learnings. Do not inline-edit AGENTS.md — the memorize agent handles extraction, deduplication, and writing. Use: `Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<session learnings>')`
-
-**docs/index.html**: `PHASES` array matches current skill state machine phases. Platform lists match `platforms/` directory. State machine diagram updated if new phases added.
-
-**gm-starter/agents/gm.md**: Skill chain on the `gm skill →` line updated if new skills were added.
-
-```
-exec:nodejs
-const fs = require('fs');
-fs.writeFileSync('/abs/path/file.md', updatedContent);
-```
+**3 — Write changed sections only**:
 
-**Step 4 — Verify from disk**:
+- **README.md**: platform count, skill tree diagram, quick start commands
+- **AGENTS.md**: via memorize sub-agent only — never inline-edit. `Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<learnings>')`
+- **docs/index.html**: `PHASES` array, platform lists, state machine diagram
+- **gm-starter/agents/gm.md**: skill chain line if new skills added
 
+**4 — Verify from disk**:
 ```
 exec:nodejs
-const fs = require('fs');
-const content = fs.readFileSync('/abs/path/file.md', 'utf8');
+const content = require('fs').readFileSync('/abs/path/file.md', 'utf8');
 console.log(content.includes('expectedString'), content.length);
 ```
 
-Witness each written file from disk. Any variance from expected content → fix and re-verify.
-
-**Step 5 — Commit and push**:
-
+**5 — Commit and push**:
 ```
 exec:bash
 git add README.md docs/index.html gm-starter/agents/gm.md
-git diff --cached --stat
-```
-
-Witness staged files. Then commit and push:
-
-```
-exec:bash
 git commit -m "docs: update documentation to reflect session changes"
 git push -u origin HEAD
 ```
 
-Witness push confirmation. Zero variance = COMPLETE.
-
-## DOC FIDELITY RULES
-
-Every claim in docs must be verifiable against disk right now:
-- State machine phase names must match skill file `name:` frontmatter
-- Platform names must match adapter class names in `platforms/`
-- File paths must exist on disk
-- Constraint counts must match actual constraints
-
-If a doc section cannot be verified against disk: remove it, do not speculate.
+## Fidelity Rules
 
-## CONSTRAINTS
-
-**Never**: skip diff analysis | write docs from memory alone | push without verifying from disk | add comments to doc content | claim done without witnessed push output
-
-**Always**: witness git diff first | read current file before overwriting | verify each file from disk after write | push doc changes | confirm with witnessed push output
-
----
+Every claim verifiable against disk: phase names match frontmatter, platform names match `platforms/`, file paths exist, constraint counts accurate. Unverifiable section → remove, don't speculate.
 
-**→ COMPLETE**: Docs committed and pushed → session ends.
-**↩ SNAKE to PLAN**: New unknown about codebase state → invoke `planning` skill.
+**Never**: write from memory | push without disk verify | add comments | claim done without witnessed push
+**Always**: git diff first | read before overwriting | verify after write | push

package/tools.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.631",
+  "version": "2.0.633",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "tools": [
     {