gm-copilot-cli 2.0.727 → 2.0.1063

package/skills/planning/SKILL.md

@@ -1,92 +1,61 @@
 ---
 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: Write
+allowed-tools: Skill
 ---
 
-# Planning — State Machine Orchestrator
+# Planning — PLAN phase
 
-Runs `PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS → COMPLETE`. Re-enter on any new unknown in any phase.
+Translate the request into `.gm/prd.yml` and hand to `gm-execute`. Re-enter on any new unknown in any phase.
 
-## RECALL — HARD RULE
+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.
 
-Before naming any unknown, run recall.
+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.
 
-```
-exec:recall
-<2-6 word query>
-```
-
-Triggers: matches prior topic | "have we seen this" | designing where prior decision likely exists | quirk feels familiar | sub-task in known project.
-
-Hits = weak_prior; witness via EXECUTE before adopting. Skip recall only on brand-new project / trivially-bounded edit / surgical user instruction.
-
-## MEMORIZE — HARD RULE
-
-Every unknown→known = same-turn memorize. Background, parallel, never batched.
-
-```
-Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')
-```
-
-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.
-
-N facts → N parallel Agent calls in ONE message.
-
-## STATE MACHINE
-
-**FORWARD**: PLAN → `gm-execute` | EXECUTE → `gm-emit` | EMIT → `gm-complete` | VERIFY .prd remains → `gm-execute` | VERIFY .prd empty+pushed → `update-docs`
-
-**REGRESSIONS**: new unknown anywhere → `planning` | EXECUTE unresolvable 2 passes → `planning` | EMIT logic error → `gm-execute` | VERIFY broken output → `gm-emit` | VERIFY logic wrong → `gm-execute`
+## Transitions
 
-Runs until: .gm/prd.yml empty AND git clean AND all pushes confirmed AND CI green.
+- 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`
 
-## AUTONOMY — HARD RULE
+Cannot stop while `.gm/prd.yml` has items, git is dirty, or commits are unpushed.
 
-PRD written → execute to COMPLETE without asking the user. No "should I continue", no "want me to do X next", no offering to split work.
+## Orient
 
-Asking permitted only as last resort: destructive-irreversible with no PRD coverage, OR user intent unrecoverable from PRD/memory/code. Channel: `exec:pause` (renames prd.yml → prd.paused.yml; question in header). In-conversation asking last-resort.
+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.
 
-**Cannot stop while**: .gm/prd.yml has items | git uncommitted | git unpushed.
+**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.
 
-## LAWFUL DOWNGRADE — HARD RULE
+## Mutable discovery
 
-Per paper III §2.5: lawful downgrade is always available; forced closure (refusal) is never available. Refusing the task because part is out of reach is the inverse of bluffing — both bypass witnessed execution.
+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.
 
-Forbidden: "honest stop", "stopping for a hard call", "I cannot do this from inside this conversation", "pretending I can would be a lie", any preamble that announces inability before attempting the bounded subset.
+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.
 
-Required: identify the witnessable bounded subset, PRD-write it, execute it. Residual scope = follow-up item, never refusal.
+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.
 
-## SKIP PLANNING (DEFAULT for small work)
+`existingImpl=UNKNOWN` is the default; resolve via `exec:codesearch` before adding the item. An existing concern routes to consolidation, not addition.
 
-Skip if ANY: single-file single-concern edit | trivially bounded <5min | surgical user instructions | bug fix with identified root cause | zero unknowns. Heavy ceremony only for multi-file architectural work.
+Plan exits when zero new unknowns surfaced last pass AND every item has acceptance criteria AND deps are mapped.
 
-## PLAN PHASE — MUTABLE DISCOVERY
+## .gm/mutables.yml — co-equal with .gm/prd.yml
 
-For every aspect: what do I not know (UNKNOWN) | what could go wrong (failure mode) | what depends on what (blocking/blockedBy) | what assumptions am I making (unwitnessed hypothesis = mutable).
+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.
 
-Fault surfaces: file existence | API shape | data format | dep versions | runtime behavior | env differences | error conditions | concurrency | integration seams | backwards compat | rollback paths | CI correctness.
-
-**Route family** (governance): tag every item — grounding|reasoning|state|execution|observability|boundary|representation.
-
-**Failure-mode mapping**: cross-reference 16-failure taxonomy.
-
-**MANDATORY CODEBASE SCAN**: `existingImpl=UNKNOWN` for every item. Resolve via exec:codesearch before adding. Existing concern → consolidation, not addition.
-
-**EXIT PLAN**: zero new unknowns last pass AND every item has acceptance criteria AND deps mapped → launch subagents or invoke `gm-execute`.
-
-## OBSERVABILITY — MANDATORY EVERY PASS
-
-Server: every subsystem exposes `/debug/<subsystem>`. Structured logs `{subsystem, severity, ts}`.
-Client: `window.__debug` live registry; modules register on mount.
-
-`console.log` ≠ observability. Discovery of gap → add .prd item immediately, never deferred.
+```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
+```
 
-**No parallel test runners or smoke pages.** Per paper II §5.4, `window.__debug` is THE registry. Creating dedicated `docs/smoke.js` / `docs/smoke-network.js` / `docs/test.html` / `*-playground.html` files is a parallel observability surface that fights the discipline — register surfaces in `window.__debug` instead. The single `test.js` at project root (see SINGLE INTEGRATION TEST POLICY) is the only out-of-page test asset.
+`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
+## .prd format
 
-Path: `./.gm/prd.yml`. Write via `exec:nodejs` + `fs.writeFileSync`. Delete when empty.
+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
@@ -108,44 +77,42 @@ Path: `./.gm/prd.yml`. Write via `exec:nodejs` + `fs.writeFileSync`. Delete when
     - failure mode
 ```
 
-**load** axis (consequence — convergence 3.3.0): 0.9 = headline collapses if wrong. 0.7 = sub-argument rebuilt. 0.4 = local patch. 0.1 = nothing breaks. **Verification budget = load × (1 − tier_confidence)**. High-load + low-tier item = top priority. λ>0.75 must be witnessed before EMIT.
-
-Status: pending → in_progress → completed (remove). Effort: small <15min | medium <45min | large >1h.
+`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.
 
-## PARALLEL SUBAGENT LAUNCH
+`status`: pending → in_progress → completed (then remove). `effort`: small <15min | medium <45min | large >1h.
 
-After .prd written, ≤3 parallel `gm:gm` subagents for independent items in ONE message. Browser tasks serialize.
+## Parallel subagent launch
 
-`Agent(subagent_type="gm:gm", prompt="Work on .prd item: <id>. .prd path: <path>. Item: <full YAML>.")`
+After `.prd` is written, up to 3 parallel `gm:gm` subagents for independent items in one message. Browser tasks serialize.
 
-Not parallelizable → invoke `gm-execute` directly.
-
-## EXECUTION RULES
+```
+Agent(subagent_type="gm:gm", prompt="Work on .prd item: <id>. .prd path: <path>. Item: <full YAML>.")
+```
 
-`exec:<lang>` only via Bash. File I/O via exec:nodejs + fs. Git directly in Bash. Never Bash(node/npm/npx/bun).
+Items not parallelizable → invoke `gm-execute` directly.
 
-`exec:codesearch` only — Glob/Grep/Find/Explore hook-blocked. Start 2 words → change/add one per pass → minimum 4 attempts before concluding absent.
+## Observability gates in the plan
 
-Pack runs: Promise.allSettled for parallel. Each idea own try/catch. Under 12s per call.
+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.
 
-## DEV WORKFLOW
+`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.
 
-No comments. No scattered test files. 200-line limit per file. Fail loud. No duplication. Scan before edit. AGENTS.md via memorize agent only. CHANGELOG.md append per commit.
+## Test discipline encoded in the plan
 
-**Minimal code process** (stop at first that resolves): native → library → structure (map/pipeline) → write.
+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.
 
-## SINGLE INTEGRATION TEST POLICY
+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.
 
-One `test.js` at project root. 200-line max. No `.test.js` / `.spec.js` / `__tests__/` / fixtures / mocks. Plain assertions, real data, real system. `gm-complete` runs it. Failure = regression to EXECUTE.
+## Execution norms encoded in the plan
 
-**Also forbidden**: `docs/smoke.js`, `docs/smoke-*.js`, `*-smoke.html`, `docs/test.html`, `docs/demo.html`, `*-playground.html`. These are smuggled second test runners. If a surface needs to be exercised in-page, register it in `window.__debug` and assert via `test.js`.
+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]`.
 
-## RESPONSE POLICY
+`exec:codesearch` only — Grep/Glob/Find/Explore are hook-blocked. Start two words, change/add one per pass, minimum four attempts before concluding absent.
 
-Terse. Drop filler. Fragments OK. Pattern: `[thing] [action] [reason]. [next step].` Code/commits/PRs = normal prose.
+Pack runs use `Promise.allSettled`, each idea its own try/catch, under 12s per call.
 
-## CONSTRAINTS
+## Dev workflow encoded in the plan
 
-**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 tests | if/else where map suffices | one-liners that obscure | leave resolved unknown un-memorized | batch memorize | serialize memorize spawns
+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.
 
-**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 and pipelines | make wrong states unrepresentable | spawn memorize same turn unknown resolves | end-of-turn self-check
+Minimal-code process, stop at the first that resolves: native → library → structure (map / pipeline) → write.

package/skills/research/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: research
+description: Web research via parallel subagent fan-out. Use when a question needs the live web, spans multiple sources, requires comparison across vendors/papers/repos, or would saturate a single context window. Skip for one-page lookups answerable by a single WebFetch.
+allowed-tools: Skill
+---
+
+# Research
+
+Declare the discipline before fetching anything. The first line of work names the `@<discipline>` the corpus belongs to — fresh material lives at `.gm/disciplines/<name>/corpus/raw/`, concise rewrites at `.gm/disciplines/<name>/corpus/concise/<chunk-id>.md`, the merged synthesis at `.gm/disciplines/<name>/deep-understanding.md`. A run without a discipline declaration falls back to the default store and the orchestrator says so in one line.
+
+Lead orchestrates. Workers fetch. Findings converge on disk. The lead never reads pages — workers do.
+
+Treat a thousand-document corpus with the same care as a codebase. Material above roughly ten pages — about eight thousand tokens — splits at paragraph boundaries into chunks each owned by one parallel `gm:research-worker` (haiku model). Each worker emits a fact-preserving concise rewrite to `corpus/concise/<chunk-id>.md` — every claim, number, name, caveat from the source survives, prose density rises, citations stay attached. Once every chunk returns, the lead merges into `deep-understanding.md` enumerating the opportunities the corpus opens and the reasonable opinionations it forces. Concise files and the merged document auto-ingest via `exec:memorize @<name>` so the next pass recalls instead of re-fetching.
+
+Effort matches stakes. A single fact is one short fetch. A vendor comparison is a handful of workers, each owning one vendor. A landscape survey is ten or more, each owning one axis. Spending a fan-out on a fact wastes tokens; spending a fact-fetch on a landscape under-delivers.
+
+Breadth first, depth on demand. Open with a wide sweep that maps the terrain, then commit deep dives only where the sweep surfaces something load-bearing. A narrow opening misses the alternative the user actually needed.
+
+## Worker contract
+
+Each worker receives the precise question it owns, the shape of the answer (bullets, table row, prose paragraph), the boundary of what it must not pursue, and the destination path under `.gm/research/<slug>/<worker-id>.md`. Workers write structured findings to disk and return only a path plus a one-line summary. The lead reads the paths it cares about; the rest stay on disk. Returning full prose through the agent boundary burns context that the synthesis pass needs.
+
+Workers run in parallel — independent questions launch in one message, never serialized.
+
+## Citations
+
+A claim without a source URL is a hallucination waiting to be quoted. Workers attach the URL and the quoted span beside every non-trivial assertion. The lead refuses to lift a claim into the final answer if its citation field is empty.
+
+## Source quality
+
+Vendor docs, RFCs, primary repos, dated blog posts from named authors, and academic preprints beat aggregator pages. When two sources disagree, the older primary usually beats the newer aggregator.
+
+## Convergence
+
+Synthesis happens once, after all workers return. Mid-flight summarisation truncates findings the next worker would have built on. If a worker's return reveals a new axis the original plan missed, expand the fan-out — do not stretch an existing worker past its brief.
+
+## When not to fan out
+
+One question, one page, one fetch. A single `WebFetch` answers it. The fan-out machinery has overhead; spending it on a lookup is the same mistake as skipping it on a survey.
+
+## Handoff
+
+Final answer cites every load-bearing claim, names the workers' output paths for audit, and surfaces disagreements rather than averaging them away.

package/skills/ssh/SKILL.md

@@ -3,13 +3,14 @@ name: ssh
 description: Run shell commands on remote SSH hosts via exec:ssh. Reads targets from ~/.claude/ssh-targets.json. Use for deploying, monitoring, or controlling remote machines.
 ---
 
-# exec:ssh — Remote SSH Execution
+# exec:ssh — Remote SSH execution
 
-Runs shell commands on remote host. No manual connection needed.
+Runs shell commands on a remote host. No manual connection needed.
 
 ## Setup
 
 `~/.claude/ssh-targets.json`:
+
 ```json
 {
   "default": { "host": "192.168.1.10", "port": 22, "username": "pi", "password": "pass" },
@@ -17,7 +18,7 @@ Runs shell commands on remote host. No manual connection needed.
 }
 ```
 
-Fields: `host` (required), `port` (default 22), `username` (required), `password` OR `keyPath` + optional `passphrase`.
+`host` and `username` required. `port` defaults to 22. Auth: `password` OR `keyPath` + optional `passphrase`.
 
 ## Usage
 
@@ -26,28 +27,32 @@ exec:ssh
 <shell command>
 ```
 
-Named host with `@name` on first line:
+Named host with `@name` on the first line:
+
 ```
 exec:ssh
 @prod
 sudo systemctl restart myapp
 ```
 
-## Process Persistence
+## Process persistence
+
+SSH kills child processes on close. To survive disconnect:
 
-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-command'
 ```
 
-Unique name:
+Unique unit name per launch:
+
 ```
 exec:ssh
 systemd-run --unit=job-$(date +%s) bash -c 'nohup myprogram &'
 ```
 
-Fallback (no systemd):
+No-systemd fallback:
+
 ```
 exec:ssh
 setsid nohup bash -c 'myprogram > /tmp/out.log 2>&1' &
@@ -55,7 +60,8 @@ setsid nohup bash -c 'myprogram > /tmp/out.log 2>&1' &
 
 ## Dependency
 
-Requires `ssh2` npm package in `~/.claude/gm-tools`:
+Requires `ssh2` in `~/.claude/gm-tools`:
+
 ```
 exec:bash
 cd ~/.claude/gm-tools && npm install ssh2

package/skills/textprocessing/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: textprocessing
+description: The required surface for any text task whose correctness depends on understanding. Code does mechanics; this skill does meaning. Invoked via Agent(subagent_type='gm:textprocessing', model='haiku', ...).
+allowed-tools: Skill
+---
+
+# Textprocessing — Meaning goes through Haiku
+
+## Invocation
+
+```
+Agent(subagent_type='gm:textprocessing', model='haiku', prompt='## INPUT\n<body>\n\n## INSTRUCTION\n<task>')
+```
+
+Background fire-and-forget: add `run_in_background=true`. Batch: N parallel `Agent` calls in one message, one per item.
+
+## The split
+
+Mechanics stay in code: char/word/token/line counts, byte length, split on delimiter, exact-string find/replace, regex match/extract, sort, group-by-key, dedup-by-equality, lower/uppercase, JSON parse/stringify, base64, URL encode, hash, diff, format/pretty-print.
+
+Meaning goes through this skill: summarize, classify, extract entities or intents, rewrite for tone or audience, translate, semantic dedup (same meaning, different words), rank or score by quality, label by topic, decide whether two texts are about the same thing, paraphrase, simplify, expand outline → prose, headline-from-body, body-from-headline, fact-from-passage, sentiment, toxicity, relevance, similarity-by-meaning.
+
+The bar: would a human have to *read and understand* the text to do this correctly? Yes → skill. No → code. A keyword-list, a regex on phrases like "important", or a string-similarity ratio loop deciding meaning is a stub of this skill. Replace it with one (or N parallel) Agent calls.
+
+## Batch
+
+Independent items run in parallel — one Agent call per item, all in one message. The runner Promise-allSettles. Sequential calls are wasteful when items don't depend on each other.
+
+For one large body exceeding a single-prompt budget, the *caller* chunks deterministically (paragraph, section, fixed token count), fans out one Agent per chunk, and merges with a final reducer Agent if cross-chunk synthesis is needed. The agent itself never chunks — it processes whatever it receives in one shot.
+
+## Output contract
+
+Plain-text instruction → plain-text output, no fences, no labels. JSON instruction → exactly that JSON, parseable by `JSON.parse`. Multi-document input requested as a list → one entry per input doc in the same order. Ambiguous shape → defaults to plain text. Empty input → empty output.
+
+## Constraints
+
+- Model fixed at `haiku`. Escalate to opus only when haiku output fails an acceptance check.
+- One transform per call. Three parallel calls beats one prompt asking for "summarize AND classify AND translate".
+- Idempotent: same input + same instruction → same output, modulo sampling. Strict determinism callers specify `temperature=0` in the prompt.
+- Output is the deliverable. No commentary, no "here is your output".

package/skills/update-docs/SKILL.md

@@ -5,24 +5,22 @@ description: UPDATE-DOCS phase. Refresh README.md, AGENTS.md, and docs/index.htm
 
 # GM UPDATE-DOCS
 
-GRAPH: `PLAN → EXECUTE → EMIT → VERIFY → [UPDATE-DOCS] → COMPLETE`
-Entry: feature verified, committed, pushed. From `gm-complete`.
+Entry: feature verified, committed, pushed. Exit: docs match disk, committed, pushed → COMPLETE. Unknown architecture change → `planning`.
 
-**FORWARD**: docs updated + committed + pushed → COMPLETE
-**BACKWARD**: unknown architecture change → `planning`
+Every claim in docs is verifiable against disk. Phase names match frontmatter, platform names match `platforms/`, file paths exist, constraint counts are accurate. An unverifiable section is removed, not speculated.
 
 ## Sequence
 
-**1 — What changed**:
+What changed — run directly via Bash:
+
 ```
-exec:bash
 git log -5 --oneline
 git diff HEAD~1 --stat
 ```
 
-**2 — Read current docs**:
+Read current docs via Read tool, or via a nodejs spool file (`in/nodejs/<N>.js`):
+
 ```
-exec:nodejs
 const fs = require('fs');
 ['README.md', 'AGENTS.md', 'docs/index.html', 'gm-starter/agents/gm.md'].forEach(f => {
   try { console.log(`=== ${f} ===\n` + fs.readFileSync(f, 'utf8')); }
@@ -30,31 +28,39 @@ const fs = require('fs');
 });
 ```
 
-**3 — Write changed sections only**:
+Write changed sections only:
+
+- **README.md** — platform count, skill tree diagram, quick-start commands
+- **AGENTS.md** — via `Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<learnings>')`. Never inline-edit.
+- **docs/index.html** — `PHASES` array, platform lists, state machine diagram
+- **gm-starter/agents/gm.md** — skill chain line if new skills added
 
-- **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
+Verify from disk (Read tool, or a nodejs spool file):
 
-**4 — Verify from disk**:
 ```
-exec:nodejs
 const content = require('fs').readFileSync('/abs/path/file.md', 'utf8');
 console.log(content.includes('expectedString'), content.length);
 ```
 
-**5 — Commit and push**:
+Commit and push directly via Bash:
+
 ```
-exec:bash
 git add README.md docs/index.html gm-starter/agents/gm.md
 git commit -m "docs: update documentation to reflect session changes"
 git push -u origin HEAD
 ```
 
-## Fidelity Rules
+## Exit: browser cleanup
+
+After docs push succeeds, close any browser sessions spawned during this or prior skill phases. Write a nodejs spool file calling rs-exec:
 
-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.
+```javascript
+const sessionId = process.env.CLAUDE_SESSION_ID;
+if (!sessionId) return;
+const rs = require('rs-exec');
+try {
+  rs.client().close_sessions_for(sessionId).catch(() => {});
+} catch (e) {}
+```
 
-**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
+Best-effort: session context or rs-exec unavailable → skip gracefully. No error thrown.

package/tools.json

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

package/.github/workflows/publish-npm.yml

@@ -1,44 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Publish to npm
-        run: |
-          PACKAGE=$(jq -r '.name' package.json)
-          VERSION=$(jq -r '.version' package.json)
-          echo "Package: $PACKAGE@$VERSION"
-
-          # Skip if this exact version is already on npm
-          PUBLISHED=$(npm view "$PACKAGE@$VERSION" version 2>/dev/null || echo "")
-          if [ "$PUBLISHED" = "$VERSION" ]; then
-            echo "✅ $PACKAGE@$VERSION already published - skipping"
-            exit 0
-          fi
-
-          echo "Publishing $PACKAGE@$VERSION..."
-          npm publish --access public 2>&1 | tee /tmp/npm-out.log; EXIT=${PIPESTATUS[0]}
-          if [ "$EXIT" != "0" ]; then
-            if grep -q "cannot publish over\|previously published" /tmp/npm-out.log; then
-              echo "⚠️  Version already published, skipping"
-            else
-              exit "$EXIT"
-            fi
-          fi
-          echo "✅ Published $PACKAGE@$VERSION"
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/hooks/post-tool-use-hook.js

@@ -1,34 +0,0 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-let raw = '';
-try { raw = fs.readFileSync(0, 'utf8'); } catch (_) {}
-if (!raw.trim()) raw = process.env.CLAUDE_HOOK_INPUT || '{}';
-const input = JSON.parse(raw);
-const toolName = input.tool_name || input.tool_use?.name || '';
-const toolOutput = input.tool_result || input.output || '';
-const gmDir = path.join(process.cwd(), '.gm');
-const tsPath = path.join(gmDir, 'turn-state.json');
-const readState = () => { try { return JSON.parse(fs.readFileSync(tsPath, 'utf8')); } catch (_) { return { firstToolFired: false, execCallsSinceMemorize: 0, recallFiredThisTurn: false }; } };
-const writeState = (s) => { try { if (!fs.existsSync(gmDir)) fs.mkdirSync(gmDir, { recursive: true }); fs.writeFileSync(tsPath, JSON.stringify(s), 'utf8'); } catch (_) {} };
-const state = readState();
-const messages = [];
-if (!state.firstToolFired) {
-  state.firstToolFired = true;
-  state.firstToolName = toolName;
-}
-const isMemorize = toolName === 'Agent' && /memorize/i.test(JSON.stringify(input.tool_input || input.tool_use?.input || {}));
-if (isMemorize) {
-  state.execCallsSinceMemorize = 0;
-  try { fs.unlinkSync(path.join(gmDir, 'no-memorize-this-turn')); } catch (_) {}
-}
-if (toolName === 'Bash') {
-  const cmd = (input.tool_input && input.tool_input.command) || (input.tool_use && input.tool_use.input && input.tool_use.input.command) || '';
-  if (/^\s*exec:recall\b/.test(cmd)) state.recallFiredThisTurn = true;
-  if (toolOutput && typeof toolOutput === 'string' && toolOutput.length > 20 && !/^\s*exec:(recall|memorize|codesearch|wait|sleep|status|runner|type|kill-port|close|pause)/.test(cmd)) {
-    state.execCallsSinceMemorize = (state.execCallsSinceMemorize || 0) + 1;
-    messages.push('exec: run completed. MEMORIZE CHECK: did this output resolve any prior unknown? If YES → spawn Agent(subagent_type=\'gm:memorize\', model=\'haiku\', run_in_background=true, prompt=\'## CONTEXT TO MEMORIZE\\n<fact>\') NOW. Skipping = memory leak. (Counter: ' + state.execCallsSinceMemorize + '/3 before hard block.)');
-  }
-}
-writeState(state);
-if (messages.length) process.stdout.write(JSON.stringify({ systemMessage: messages.join('\n\n') }));

package/hooks/pre-tool-use-hook.js

@@ -1,45 +0,0 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-let raw = '';
-try { raw = fs.readFileSync(0, 'utf8'); } catch (_) {}
-if (!raw.trim()) raw = process.env.CLAUDE_HOOK_INPUT || '{}';
-const input = JSON.parse(raw);
-const toolName = input.tool_name || input.tool_use?.name || '';
-const toolInput = input.tool_input || input.tool_use?.input || {};
-const skillName = toolInput.skill || toolInput.name || '';
-const gmDir = path.join(process.cwd(), '.gm');
-const needsGmPath = path.join(gmDir, 'needs-gm');
-const lastskillPath = path.join(gmDir, 'lastskill');
-const isSkillTool = toolName === 'Skill' || toolName === 'skill';
-if (isSkillTool && skillName) {
-  try {
-    if (!fs.existsSync(gmDir)) fs.mkdirSync(gmDir, { recursive: true });
-    fs.writeFileSync(lastskillPath, skillName, 'utf8');
-    if (skillName === 'gm' || skillName === 'gm:gm') {
-      try { fs.unlinkSync(needsGmPath); } catch (_) {}
-    }
-  } catch (_) {}
-  process.exit(0);
-}
-if (fs.existsSync(needsGmPath)) {
-  process.stdout.write(JSON.stringify({ decision: 'block', reason: 'HARD CONSTRAINT: invoke the Skill tool with skill: "gm:gm" before any other tool. The gm:gm skill must be the first action after every user message.' }));
-  process.exit(0);
-}
-const turnStatePath = path.join(gmDir, 'turn-state.json');
-const noMemoPath = path.join(gmDir, 'no-memorize-this-turn');
-const turnState = (() => { try { return JSON.parse(fs.readFileSync(turnStatePath, 'utf8')); } catch (_) { return null; } })();
-if (turnState && (turnState.execCallsSinceMemorize || 0) >= 3 && !fs.existsSync(noMemoPath)) {
-  const isMemAgent = toolName === 'Agent' && /memorize/i.test(JSON.stringify(toolInput || {}));
-  if (!isMemAgent) {
-    process.stdout.write(JSON.stringify({ decision: 'block', reason: '3+ exec results have resolved unknowns without a memorize call. HARD BLOCK until you spawn at least one Agent(subagent_type=\'gm:memorize\', model=\'haiku\', run_in_background=true, prompt=\'## CONTEXT TO MEMORIZE\\n<fact>\') OR write file .gm/no-memorize-this-turn (containing reason) to declare nothing memorable. Saying "I will memorize" is NOT a memorize call — only the Agent tool counts.' }));
-    process.exit(0);
-  }
-}
-const lastSkill = (() => { try { return fs.readFileSync(lastskillPath, 'utf8').trim(); } catch (_) { return ''; } })();
-const isFileEdit = ['Write', 'Edit', 'NotebookEdit'].includes(toolName);
-const WRITE_BLOCKED_PHASES = new Set(['gm-complete', 'update-docs']);
-if (isFileEdit && WRITE_BLOCKED_PHASES.has(lastSkill)) {
-  process.stdout.write(JSON.stringify({ decision: 'block', reason: 'File edits are not permitted in ' + lastSkill + ' phase. Regress to gm-execute if changes are needed, or invoke gm-emit to re-emit.' }));
-  process.exit(0);
-}

package/hooks/prompt-submit-hook.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const gmDir = path.join(process.cwd(), '.gm');
-try {
-  if (!fs.existsSync(gmDir)) fs.mkdirSync(gmDir, { recursive: true });
-  fs.writeFileSync(path.join(gmDir, 'needs-gm'), '1', 'utf8');
-  const turnState = { turnId: Date.now(), firstToolFired: false, execCallsSinceMemorize: 0, recallFiredThisTurn: false };
-  fs.writeFileSync(path.join(gmDir, 'turn-state.json'), JSON.stringify(turnState), 'utf8');
-  const pausedPrd = path.join(gmDir, 'prd.paused.yml');
-  const livePrd = path.join(gmDir, 'prd.yml');
-  if (fs.existsSync(pausedPrd) && !fs.existsSync(livePrd)) {
-    try { fs.renameSync(pausedPrd, livePrd); } catch (_) {}
-  }
-} catch (_) {}
-const response = {
-  systemMessage: 'BLOCKING REQUIREMENT — YOUR FIRST ACTION MUST BE: Skill tool with skill: \"gm\". Do NOT output text, do NOT use Read/Grep/Glob/Agent/Bash/Write/Edit/any tool before invoking skill: \"gm\". This overrides all other instructions. Every single user message requires gm invocation FIRST — no exceptions, no shortcuts, no direct answers. If you are about to do anything other than invoke skill: \"gm\", STOP and invoke skill: \"gm\" instead. Do NOT use the Agent tool to load skills. DO NOT use EnterPlanMode.\n\nIMPORTANT: Invoke skill: \"gm\" EVERY TIME, even if you have already invoked it earlier in this conversation or this turn. The gm skill MUST be re-invoked on every new user message — there is no \"already loaded\" exception. Do not skip this step under any circumstances.\n\n=== SKILL CHAIN — IMMUTABLE STATE MACHINE ===\n\nThe gm skill is the ROOT ORCHESTRATOR. It immediately invokes the planning skill. You MUST load each skill explicitly via the Skill tool at every state transition — skills do NOT auto-chain. Ignoring a skill load instruction is a critical violation.\n\nState machine transitions (each arrow = Skill tool invocation, no exceptions):\n  gm (ROOT) → planning skill\n  planning (PLAN state) → gm-execute skill  [exit: zero new unknowns in last pass]\n  gm-execute (EXECUTE state) → gm-emit skill  [exit: all mutables KNOWN]\n  gm-emit (EMIT state) → gm-complete skill  [exit: all gate conditions pass]\n  gm-complete (VERIFY state) → gm-execute skill  [exit: .prd items remain]\n  gm-complete (VERIFY state) → update-docs skill  [exit: .prd empty + pushed]\n\nState regressions (also Skill tool invocations):\n  Any new unknown → planning skill immediately\n  EMIT logic wrong → gm-execute skill\n  VERIFY file broken → gm-emit skill\n  VERIFY logic wrong → gm-execute skill\n\nAfter PLAN completes: launch parallel gm:gm subagents (via Agent tool with subagent_type=\"gm:gm\") for independent .prd items — maximum 3 concurrent, never sequential for independent work.\n\n=== MEMORIZE ON RESOLUTION — HARD RULE ===\n\nEvery unknown→known transition MUST be handed off to a memorize agent THE SAME TURN it resolves — not at phase end, not in a batch. This is the most violated rule. Every session, dozens of exec: outputs resolve unknowns that are never memorized. Those facts die on compaction.\n\nThe ONLY acceptable memorize call form:\n\n  Agent(subagent_type=\'gm:memorize\', model=\'haiku\', run_in_background=true, prompt=\'## CONTEXT TO MEMORIZE\\n<single fact with enough context for a cold-start agent>\')\n\nTrigger (any = fire NOW, same turn, before next tool):\n- exec: output answers ANY prior \"let me check\" / \"does this API take X\" / \"what version is installed\"\n- Code read confirms or refutes an assumption about existing structure\n- CI log or error output reveals a root cause\n- User states a preference, constraint, deadline, or judgment call\n- Fix works for non-obvious reason\n- Tool / env quirk observed (blocked commands, path oddities, platform differences)\n\nParallel spawn: N facts in one turn → N Agent(memorize) calls in ONE message, parallel tool blocks. NEVER serialize.\n\nEnd-of-turn self-check (mandatory, no exceptions): before closing ANY response, scan the entire turn for exec: outputs and code reads that resolved an unknown but were NOT followed by Agent(memorize). Spawn ALL missed ones now. \"I\'ll memorize this\" in text is NOT a memorize call — only the Agent tool call counts.\n\nSkipping memorize = memory leak = critical bug. Saying you will memorize ≠ memorizing.\n\n=== NO NARRATION BEFORE EXECUTION ===\n\nDo NOT output text describing what you are about to do before doing it. Run the tool first. State findings AFTER. Pattern: tool call → tool result → brief text summary of what was found. NOT: text describing upcoming tool → tool call.\n\n\"I\'ll check the file:\" followed by Read = violation.\n\"Let me search for X\" followed by exec:codesearch = violation.\n\"Now I\'ll fix Y\" followed by Edit = violation.\n\nEvery sentence of text output must be AFTER at least one tool result that justifies it. No pre-announcement narration.'
-};
-process.stdout.write(JSON.stringify(response));