gm-skill 0.1.2 → 2.0.1081

package/skills/planning/SKILL.md

@@ -1,118 +1,42 @@
 ---
 name: planning
 description: State machine orchestrator. Mutable discovery, PRD construction, and full PLAN→EXECUTE→EMIT→VERIFY→COMPLETE lifecycle. Invoke at session start and on any new unknown.
-allowed-tools: Skill
+allowed-tools: Skill, Read, Write
 ---
 
-# Planning — PLAN phase
+# planning — PLAN
 
-Translate the request into `.gm/prd.yml` and hand to `gm-execute`. Re-enter on any new unknown in any phase.
+Every turn begins with prior memory already loaded by auto-recall. PLAN adds targeted reconnaissance on top of that injection. Before any unknown is named as absent, it has been searched for. Before an abstraction is designed, the codebase has been checked for one that already exists.
 
-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.
+## ORIENT
 
-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.
+The first action of PLAN is a parallel pack: 3–5 `exec:recall` calls and 3–5 `exec:codesearch` calls against the request's nouns, dispatched in one message. Hits become weak_prior — still witnessed before adoption. Misses confirm the unknown is fresh. The pack is free relative to the duplicated discovery and disagree-with-prior-witness risk it prevents. Serial probing of nouns one-at-a-time is the failure mode this discipline guards against.
 
-## Transitions
+Spool the pack as the opening move:
 
-- PLAN done → `gm-execute`
-- New unknown anywhere in chain → re-enter PLAN
-- EXECUTE unresolvable after 2 passes → PLAN
-- VERIFY: `.prd` empty + git clean + pushed → `update-docs`; else → `gm-execute`
-
-Cannot stop while `.gm/prd.yml` has items, git is dirty, or commits are unpushed.
-
-## Orient
-
-Open every plan with one parallel pack of `exec:recall` + `exec:codesearch` against the request's nouns. Hits land as `weak_prior`; misses confirm the unknown is fresh. The pack runs in one message.
-
-**Auto-recall injection (skills-only platforms)**: derive a 2–6 word query from the request's nouns (subject, verb objects, key domain terms). Call `exec:recall <query>` at PLAN start before writing `.gm/prd.yml`, inline. This replaces the prompt-submit hook's auto-recall for platforms without hook infrastructure. Recall hits are injected as context into mutable discovery and PRD item acceptance criteria.
-
-## Mutable discovery
-
-For each aspect of the work, ask: what do I not know, what could go wrong, what depends on what, what am I assuming. Unwitnessed assumptions are mutables.
-
-Fault surfaces to scan: file existence, API shape, data format, dep versions, runtime behavior, env differences, error conditions, concurrency, integration seams, backwards compat, rollback paths, CI correctness.
-
-Tag every item with a route family (grounding | reasoning | state | execution | observability | boundary | representation) and cross-reference the 16-failure taxonomy. `governance` skill holds the table.
-
-`existingImpl=UNKNOWN` is the default; resolve via `exec:codesearch` before adding the item. An existing concern routes to consolidation, not addition.
-
-Plan exits when zero new unknowns surfaced last pass AND every item has acceptance criteria AND deps are mapped.
-
-## .gm/mutables.yml — co-equal with .gm/prd.yml
-
-Every unknown surfaced during PLAN lands as an entry in `.gm/mutables.yml` the same pass. Live during work, deleted when empty. Hook-gated: Write/Edit/NotebookEdit and `git commit`/`git push` are hard-blocked while any entry has `status: unknown`; turn-stop is hard-blocked the same way.
-
-```yaml
-- id: kebab-id
-  claim: One-line statement of what is assumed
-  witness_method: exec:codesearch <query> | exec:nodejs import | exec:recall <query> | Read <path>
-  witness_evidence: ""
-  status: unknown
 ```
-
-`status: unknown` → `witnessed` only when `witness_evidence` is filled with concrete proof (file:line, codesearch hit, dispatched test output). Resolution lives in gm-execute. PRD items reference mutables via optional `mutables: [id1, id2]` field; an item is blocked while any referenced mutable is unresolved.
-
-## .prd format
-
-Path: `./.gm/prd.yml`. Write via the Write tool or by emitting a nodejs spool file (`in/nodejs/<N>.js`) that calls `fs.writeFileSync`. Delete the file when empty.
-
-```yaml
-- id: kebab-id
-  subject: Imperative verb phrase
-  status: pending
-  description: Precise criterion
-  effort: small|medium|large
-  category: feature|bug|refactor|infra
-  route_family: grounding|reasoning|state|execution|observability|boundary|representation
-  load: 0.0-1.0
-  failure_modes: []
-  route_fit: unexamined|examined|dominant
-  authorization: none|weak_prior|witnessed
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - binary criterion
-  edge_cases:
-    - failure mode
-```
-
-`load` is consequence-if-wrong: 0.9 = headline collapses, 0.7 = sub-argument rebuilt, 0.4 = local patch, 0.1 = nothing breaks. Verification budget = `load × (1 − tier_confidence)`. λ>0.75 must reach witnessed before EMIT.
-
-`status`: pending → in_progress → completed (then remove). `effort`: small <15min | medium <45min | large >1h.
-
-## Parallel subagent launch
-
-After `.prd` is written, up to 3 parallel `gm:gm` subagents for independent items in one message. Browser tasks serialize.
-
-```
-Agent(subagent_type="gm:gm", prompt="Work on .prd item: <id>. .prd path: <path>. Item: <full YAML>.")
+.gm/exec-spool/in/recall/1.txt   "<noun phrase 1>"
+.gm/exec-spool/in/recall/2.txt   "<noun phrase 2>"
+.gm/exec-spool/in/recall/3.txt   "<noun phrase 3>"
+.gm/exec-spool/in/codesearch/1.txt   "<two-word phrase 1>"
+.gm/exec-spool/in/codesearch/2.txt   "<two-word phrase 2>"
+.gm/exec-spool/in/codesearch/3.txt   "<two-word phrase 3>"
 ```
 
-Items not parallelizable → invoke `gm-execute` directly.
-
-## Observability gates in the plan
-
-Server: every subsystem exposes `/debug/<subsystem>`; structured logs `{subsystem, severity, ts}`. Client: `window.__debug` live registry; modules register on mount. `console.log` is not observability. Discovery of a gap during PLAN adds a `.prd` item the same pass — never deferred.
-
-`window.__debug` is THE in-page registry; `test.js` at project root is the sole out-of-page test asset. Any new file whose purpose is to exercise, smoke-test, demo, or sandbox in-page behavior outside that registry fights the discipline — extend the registry instead.
-
-## Test discipline encoded in the plan
-
-One `test.js` at project root, 200-line hard cap, real data, real system. No fixtures, mocks, or scattered tests. A second test runner under any name in any directory is a smuggled parallel surface.
+All in one message. Read `out/*.json` together.
 
-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.
+## Maximal Cover
 
-## Execution norms encoded in the plan
+Scope-exceeds-reach is a planning condition, not a stopping condition. The covering family is the plan. Enumerate every bounded subset of the request witnessable from this session; write the family into `.gm/prd.yml` with the dependency graph explicit. Residuals within the spirit of the ask AND reachable from this session are self-authorized — expand the PRD and declare the read in one line ("treating X as in-spirit because Y"). Only out-of-spirit or unreachable residuals are name-and-stop.
 
-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]`.
+## Mutables File
 
-`exec:codesearch` only — Grep/Glob/Find/Explore are hook-blocked. Start two words, change/add one per pass, minimum four attempts before concluding absent.
+`.gm/mutables.yml` is co-equal with `.gm/prd.yml`. Every unknown surfaced lands as a row with `status: unknown`. The hook layer hard-blocks Write, Edit, `git commit`, `git push`, and stop while any row remains unknown. Rows flip to `witnessed` only when `witness_evidence` carries concrete proof — file:line, codesearch hit, exec output snippet. Narrative resolution is rejected on read. PLAN exits only at ε = 0 on the final pass.
 
-Pack runs use `Promise.allSettled`, each idea its own try/catch, under 12s per call.
+## Dispatch
 
-## Dev workflow encoded in the plan
+`phase-status` to read FSM state. `transition` to advance. `mutable-resolve` to mark witnessed (auto-fires memorize). Plus the usual `recall`, `codesearch`, `memorize`, `health`, language stems.
 
-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.
+## Transition
 
-Minimal-code process, stop at the first that resolves: native → library → structure (map / pipeline) → write.
+Read `out/<N>.json::nextSkill`. Invoke `Skill(skill="gm:<nextSkill>")` immediately.

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

@@ -0,0 +1,71 @@
+---
+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
+
+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" },
+  "prod": { "host": "10.0.0.1", "username": "ubuntu", "keyPath": "/home/user/.ssh/id_rsa" }
+}
+```
+
+`host` and `username` required. `port` defaults to 22. Auth: `password` OR `keyPath` + optional `passphrase`.
+
+## Usage
+
+```
+exec:ssh
+<shell command>
+```
+
+Named host with `@name` on the first line:
+
+```
+exec:ssh
+@prod
+sudo systemctl restart myapp
+```
+
+## Process persistence
+
+SSH kills child processes on close. To survive disconnect:
+
+```
+exec:ssh
+sudo systemctl reset-failed myunit 2>/dev/null; systemd-run --unit=myunit bash -c 'your-command'
+```
+
+Unique unit name per launch:
+
+```
+exec:ssh
+systemd-run --unit=job-$(date +%s) bash -c 'nohup myprogram &'
+```
+
+No-systemd fallback:
+
+```
+exec:ssh
+setsid nohup bash -c 'myprogram > /tmp/out.log 2>&1' &
+```
+
+## Dependency
+
+Requires `ssh2` in `~/.claude/gm-tools`. Write to `.gm/exec-spool/in/nodejs/<N>.js`:
+
+```js
+const { execSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+const gmTools = path.join(os.homedir(), '.claude', 'gm-tools');
+execSync('npm install ssh2', { cwd: gmTools, stdio: 'inherit' });
+```

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

@@ -1,66 +1,47 @@
 ---
 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.
+allowed-tools: Skill, Read, Write
 ---
 
-# GM UPDATE-DOCS
+# update-docs — UPDATE-DOCS
 
-Entry: feature verified, committed, pushed. Exit: docs match disk, committed, pushed → COMPLETE. Unknown architecture change → `planning`.
+Docs reflect the current state of the system, not its history. Every rule in AGENTS.md is a present-tense statement about what must or must-not be the case in code now. Past-tense framing, `(FIXED)` markers, dated audit entries, and "we used to X, now we Y" phrasing belong in `git log` and `CHANGELOG.md` — never in AGENTS.md.
 
-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.
+## AGENTS.md and CLAUDE.md
 
-## Sequence
-
-What changed — run directly via Bash:
+Edits to AGENTS.md and CLAUDE.md route through the memorize subagent only — never inline-edit. Invocation:
 
 ```
-git log -5 --oneline
-git diff HEAD~1 --stat
+Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')
 ```
 
-Read current docs via Read tool, or via a nodejs spool file (`in/nodejs/<N>.js`):
+The classifier rejects changelog-shaped facts from AGENTS.md ingestion (rs-learn still accepts them). Multiple facts → multiple parallel Agent calls in one message.
 
-```
-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')); }
-  catch(e) { console.log(`MISSING: ${f}`); }
-});
-```
+## README.md
 
-Write changed sections only:
+Refresh to reflect the surface a new reader actually encounters. Remove stale install steps, version pins, and features that no longer exist. Add what was added this session if it changes the public surface.
 
-- **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
+## docs/index.html
 
-Verify from disk (Read tool, or a nodejs spool file):
+Regenerate or hand-edit to reflect the same surface. Site builds run from `site/`; the deployed `/` route renders from `site/content/pages/home.yaml` via flatspace. Landing edits go through `site/theme.mjs` (Hero) and the YAML — never `site/index.html` directly. `docs/styles.css` is generated from `site/input.css`; append to the source, not the output.
 
-```
-const content = require('fs').readFileSync('/abs/path/file.md', 'utf8');
-console.log(content.includes('expectedString'), content.length);
-```
+## CHANGELOG.md
 
-Commit and push directly via Bash:
+One entry per commit landed this session. The commit message line plus a one-sentence "why" — no recipe, no narration. CHANGELOG carries the history that AGENTS.md refuses.
 
-```
-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
-```
+## Commit and Push
 
-## Exit: browser cleanup
+Stage doc updates only — never bundle them with code changes from earlier phases (those committed at their own time). One commit, present-tense imperative subject. Push to main. The push triggers the docs pipeline if the repo has one.
 
-After docs push succeeds, close any browser sessions spawned during this or prior skill phases. Write a nodejs spool file calling rs-exec:
+## COMPLETE
 
-```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) {}
-```
+This is the terminal phase. After push lands, the chain signals COMPLETE. No further `Skill()` invocation; the orchestrator records the chain as concluded.
+
+## Dispatch
+
+`phase-status`, `transition` to COMPLETE.
+
+## Transition
 
-Best-effort: session context or rs-exec unavailable → skip gracefully. No error thrown.
+`nextSkill: null` from the orchestrator means the chain is done. End of skill body.

package/gm-complete.SKILL.md

@@ -1,106 +0,0 @@
----
-name: gm-complete
-description: VERIFY and COMPLETE phase. End-to-end system verification and git enforcement. Any new unknown triggers immediate snake back to planning — restart chain.
----
-
-# GM COMPLETE — Verify, then close
-
-Entry: EMIT gates clear, from `gm-emit`. Exit: `.prd` deleted + test.js green + pushed + CI green → `update-docs`.
-
-Cross-cutting dispositions live in `gm` SKILL.md.
-
-## Transitions
-
-- `.prd` items remain → `gm-execute`
-- `.prd` empty AND test.js green AND pushed AND CI green → `update-docs`
-- Broken file output → `gm-emit`
-- Wrong logic → `gm-execute`
-- New unknown or wrong requirements → `planning`
-
-Failure triage: broken output to EMIT, wrong logic to EXECUTE, new unknown to PLAN. Never patch around surprises.
-
-## Mutables that must resolve before COMPLETE
-
-- `witnessed_e2e` — real end-to-end run with witnessed output
-- `browser_validated` — for any change touching client / UI / browser-facing code, see gate below. test.js + node-side imports DO NOT satisfy this gate.
-- `git_clean` — `git status --porcelain` returns empty
-- `git_pushed` — `git log origin/main..HEAD --oneline` returns empty
-- `ci_passed` — every GitHub Actions run reaches `conclusion: success`
-- `mutables_resolved` — `.gm/mutables.yml` deleted OR every entry `status: witnessed`. Stop hook hard-blocks turn-stop while any entry is `status: unknown`.
-- `prd_empty` — `.gm/prd.yml` deleted AFTER residual scan: enumerate every in-spirit reachable residual surfaced this session; any hit re-enters `planning`, appends PRD items, executes. Empty PRD is necessary, not sufficient — done = empty PRD AND zero reachable in-spirit residuals. Out-of-spirit-or-unreachable residuals are named in the response and skipped; everything else is this turn's work.
-- `stress_suite_clear` — change walked through M1–D1 (governance), none flunked
-- `hidden_decision_posture` — open → down_weighted → closed only when CI is green AND stress suite is clear
-
-## End-to-end verification
-
-Real system, real data, witness actual output. Doc updates, "saying done", and screenshots alone are not verification. Write the e2e probe to the spool (`.gm/exec-spool/in/nodejs/<N>.js`):
-
-```
-const { fn } = await import('/abs/path/to/module.js');
-console.log(await fn(realInput));
-```
-
-After every success, enumerate what remains — never stop at first green.
-
-## Browser validation gate
-
-Required when this session changed any code that runs in a browser: anything under `client/`, UI components, shaders, page-loaded JS, served HTML, gh-pages assets, dev-server endpoints, or any module imported into the page bundle.
-
-Trigger detection (any one): `git diff --name-only origin/main..HEAD` includes paths under `client/`, `apps/*/index.js` with client export, `docs/`, `*.html`, shader files, or any file imported by a browser entry; new/changed export consumed by `window.*` or rendered in DOM/canvas/WebGL; visual, layout, animation, input, network-on-page, or shader behavior altered.
-
-Protocol: boot the real server (or open the static page) on a known URL — witness HTTP 200. `exec:browser` → `page.goto(url)` → wait for app init by polling for the global the change affects (`window.__app.<system>`). Probe via `page.evaluate(() => …)` asserting the specific invariant the change was supposed to establish — instance counts, scene meshes, DOM nodes, render stats, network frames. Capture witnessed numbers in the response — "looks fine" is not a witness. Failures route to `gm-execute` (logic) or `gm-emit` (output) — never paper over.
-
-Long-running probes split into navigate-call → `exec:wait N` → probe-call to stay under the per-call budget. Do not stack multi-second `setTimeout` inside one `exec:browser` invocation.
-
-Exempt only when: change is server-only with zero browser-facing surface, OR the repository has no browser surface at all (pure CLI / library). Exemption requires explicit tag in the response: `BROWSER EXEMPT: <reason — must reference diff paths showing zero browser-facing surface>`. Default posture is NOT exempt — burden is on the agent to prove exemption with diff evidence.
-
-Pre-flight: run `git diff --name-only origin/main..HEAD` directly via Bash, then dispatch a nodejs spool file that reads the diff list and filters lines matching `client/|docs/|\.html$|\.glsl$|\.frag$|\.vert$`. Any hit AND no `exec:browser` block in this session → mandatory regression to `gm-execute`.
-
-## Integration test gate
-
-Write to `.gm/exec-spool/in/nodejs/<N>.js`:
-
-```
-const { execSync } = require('child_process');
-try { execSync('node test.js', { stdio: 'inherit', timeout: 30000 }); console.log('PASS'); }
-catch (e) { console.error('FAIL'); process.exit(1); }
-```
-
-Failure → `gm-execute`. No test.js in a repo with testable surface → `gm-execute` to create it.
-
-## Git enforcement
-
-Run directly via Bash:
-
-```
-git status --porcelain
-git log origin/main..HEAD --oneline
-```
-
-Both must return empty. Local commit without push is not complete.
-
-## CI is automated
-
-The Stop hook watches Actions for the pushed HEAD. Do not call `gh run list` manually. All-green → Stop approves with CI summary in next-turn context. Failure → Stop blocks with run names + IDs; investigate via `gh run view <id> --log-failed`, fix, push, hook re-watches. Deadline 180s (override `GM_CI_WATCH_SECS`); slow jobs get a "still in progress" approve.
-
-## Hygiene sweep
-
-1. Files >200 lines → split
-2. Comments in code → remove
-3. Scattered test files (`.test.js`, `.spec.js`, `__tests__/`, `fixtures/`, `mocks/`) → delete, consolidate into root `test.js`
-4. Mock / stub / simulation files → delete
-5. Unnecessary doc files (not CHANGELOG, CLAUDE, README, TODO.md) → delete
-6. Duplicate concern → regress to `planning` with restructuring instructions
-7. Hardcoded values → derive from ground truth
-8. Fallback / demo modes → remove, fail loud
-9. TODO.md → empty or deleted
-10. CHANGELOG.md → entries for this session
-11. Observability gaps → server subsystems expose `/debug/<subsystem>`; client modules register in `window.__debug`
-12. Memorize → every fact from verification handed off via background `Agent(memorize)` at moment of resolution
-13. Deploy / publish → if deployable, deploy; if npm package, publish
-14. GitHub Pages → check `.github/workflows/pages.yml` + `docs/index.html` exist; invoke `pages` skill if absent
-15. Governance stress-suite → walk change through M1, F1, C1, H1, S1, B1, A1, D1; any flunk regresses to the owning phase
-
-## Completion
-
-All true at once: witnessed e2e | browser_validated when client work touched | failure paths exercised | test.js passes | `.prd` deleted | git clean and pushed | CI green | hygiene sweep clean | TODO.md gone | CHANGELOG.md updated.

package/gm-emit.SKILL.md

@@ -1,70 +0,0 @@
----
-name: gm-emit
-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 — Write and verify from disk
-
-Entry: every mutable KNOWN, from `gm-execute` or re-entered from VERIFY. Exit: gates clear → `gm-complete`.
-
-Cross-cutting dispositions live in `gm` SKILL.md.
-
-## Transitions
-
-- All gates clear → `gm-complete`
-- Post-emit variance with known cause → fix in-band, re-verify, stay in EMIT
-- Pre-emit reveals known logic error → `gm-execute`
-- Pre-emit reveals new unknown OR post-emit variance with unknown cause OR scope changed → `planning`
-
-## Legitimacy gate (before pre-emit run)
-
-For every claim landing in a file, answer five questions:
-
-1. Earned specificity — does it trace to `authorization=witnessed`, or is it inflated from a weak prior?
-2. Repair legality — is a local patch dressed as structural repair? Downgrade scope or regress to PLAN.
-3. Lawful downgrade — can a weaker, true statement replace it? Prefer the downgrade.
-4. Alternative-route suppression — is a live competing route being silenced? Preserve it.
-5. Strongest objection — what would the sharpest reviewer pushback be? Articulate it. Cannot articulate = have not understood the alternatives → `gm-execute`.
-
-Any failure regresses to `gm-execute` to witness what was missing, or `planning` if the gap is structural.
-
-## Pre-emit run
-
-Mandatory before writing any file. Write the probe to the spool (`.gm/exec-spool/in/nodejs/<N>.js`):
-
-```
-const { fn } = await import('/abs/path/to/module.js');
-console.log(await fn(realInput));
-```
-
-Import the actual module from disk to witness current behavior as the baseline. Run the proposed logic in isolation without writing — witness with real inputs and with real error inputs. Match expected → write. Unexpected → new unknown → `planning`.
-
-## Writing
-
-Use the Write tool, or a nodejs spool file with `require('fs')`. Write only when every gate mutable resolves simultaneously.
-
-## Post-emit verification
-
-Re-import from disk — in-memory state is stale and inadmissible. Run identical inputs as pre-emit; output must match the baseline exactly. Known variance → fix and re-verify (self-loop). Unknown variance → `planning`.
-
-## Mutables gate
-
-Before pre-emit run, read `.gm/mutables.yml`. Any entry with `status: unknown` → regress to `gm-execute`. The pre-tool-use hook hard-blocks Write/Edit/NotebookEdit while unresolved entries exist; trying to emit anyway returns deny. Zero unresolved is the precondition for every legitimacy question below.
-
-## Gate (all true at once)
-
-- `.gm/mutables.yml` empty/absent OR every entry `status: witnessed` with filled `witness_evidence`
-- Legitimacy gate passed; no refused collapse
-- Pre-emit passed with real inputs and real error inputs
-- Post-emit matches pre-emit exactly
-- Hot-reloadable; errors throw with context (no `|| default`, no `catch { return null }`, no fallbacks)
-- No mocks, fakes, stubs, or scattered test files (delete on discovery)
-- Any behavior change has a corresponding assertion in `test.js` — a change no test catches is a change you cannot prove
-- Browser-facing change → post-emit verify includes a live `exec:browser` witness (boot server → `page.goto` → `page.evaluate` asserting the invariant the change established). Node-side import + test.js does not satisfy this — the final gate runs again in `gm-complete`.
-- Files ≤ 200 lines
-- No duplicate concern (run `exec:codesearch` for the primary concern after writing; overlap → `planning`)
-- No comments, no hardcoded values, no adjectives in identifiers, no unnecessary files
-- Observability: new server subsystems expose `/debug/<subsystem>`; new client modules register in `window.__debug`
-- Structure: no if/else where dispatch suffices; no one-liners that obscure; no reinvented APIs
-- Every fact resolved this phase memorized via background `Agent(memorize)`
-- CHANGELOG.md updated; TODO.md cleared or deleted