gm-kilo 2.0.887 → 2.0.889

package/skills/gm-complete/SKILL.md

@@ -3,35 +3,36 @@ 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 and Complete
+# GM COMPLETE — Verify, then close
 
-GRAPH: `PLAN → EXECUTE → EMIT → [VERIFY] → UPDATE-DOCS → COMPLETE`
-Entry: all EMIT gates passed. From `gm-emit`.
+Entry: EMIT gates clear, from `gm-emit`. Exit: `.prd` deleted + test.js green + pushed + CI green → `update-docs`.
 
-## TRANSITIONS
+Cross-cutting dispositions live in `gm` SKILL.md.
 
-**EXIT → EXECUTE**: .prd items remain → invoke `gm-execute` immediately.
-**EXIT → COMPLETE**: .prd deleted + test.js passes + pushed + CI green → invoke `update-docs`.
-**REGRESS → EMIT**: broken file output.
-**REGRESS → EXECUTE**: logic wrong.
-**REGRESS → PLAN**: new unknown or wrong requirements.
+## Transitions
 
-Failure triage: broken output → EMIT | wrong logic → EXECUTE | new unknown → PLAN. Never patch around surprises.
+- `.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`
 
-## MUTABLES — ALL MUST RESOLVE BEFORE COMPLETE
+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` — MANDATORY for any change touching client/UI/browser-facing code (anything served to a browser, rendered, or whose output is visible to a user). Must invoke `browser` skill, navigate the live page, and witness the change in `window` / DOM / scene state. test.js + node-side imports DO NOT satisfy this gate. See BROWSER VALIDATION GATE below.
+- `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` — all GitHub Actions runs reach `conclusion: success`
-- `prd_empty` — `.gm/prd.yml` deleted (file must not exist)
-- `stress_suite_clear` — change walked through all applicable governance stress cases (M1-D1), none flunk
-- `hidden_decision_posture` — advances open→down_weighted→closed only when CI green + stress suite clear
+- `ci_passed` — every GitHub Actions run reaches `conclusion: success`
+- `prd_empty` — `.gm/prd.yml` deleted
+- `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
+## End-to-end verification
 
-Run real system, real data, witness actual output. NOT verification: docs updates, saying done, screenshots alone.
+Real system, real data, witness actual output. Doc updates, "saying done", and screenshots alone are not verification.
 
 ```
 exec:nodejs
@@ -39,31 +40,23 @@ const { fn } = await import('/abs/path/to/module.js');
 console.log(await fn(realInput));
 ```
 
-Browser/UI: invoke `browser` skill. After every success: enumerate what remains — never stop at first green.
+After every success, enumerate what remains — never stop at first green.
 
-## BROWSER VALIDATION GATE — MANDATORY FOR CLIENT WORK
+## Browser validation gate
 
-If 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 — `browser_validated` MUST resolve before COMPLETE. Skipping it because "node tests pass" or "test.js is green" is a forced-closure refusal of witnessed verification.
+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 suffices):
-- `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.
+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.
 
-Required protocol:
-1. Boot the real server (or open the static page) on a known URL — witness HTTP 200.
-2. `exec:browser` → `page.goto(url)` → wait for app init (poll for the global the change affects, e.g. `window.__app.<system>`).
-3. Probe via `page.evaluate(() => …)` — assert the specific invariant the change was supposed to establish (instance counts, scene meshes, DOM nodes, render stats, network frames, etc.).
-4. Capture the witnessed numbers in the response. "Looks fine" is not a witness.
-5. Failures → regress to `gm-execute` (logic) or `gm-emit` (output) — never paper over.
+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.
+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 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>`. Silent skip = forced-closure failure. Default posture is NOT exempt — burden is on the agent to prove exemption with diff evidence, not to assume it.
+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 check before declaring complete**: run `git diff --name-only origin/main..HEAD` and grep for `client/|docs/|\.html$|\.glsl$|\.frag$|\.vert$`. Any hit AND no `exec:browser` block in this session = mandatory regression to `gm-execute` to witness the change live. No exceptions for "small CSS tweak" or "obvious string change".
+Pre-flight: run `git diff --name-only origin/main..HEAD` and grep for `client/|docs/|\.html$|\.glsl$|\.frag$|\.vert$`. Any hit AND no `exec:browser` block in this session → mandatory regression to `gm-execute`.
 
-## INTEGRATION TEST GATE
+## Integration test gate
 
 ```
 exec:nodejs
@@ -72,9 +65,9 @@ try { execSync('node test.js', { stdio: 'inherit', timeout: 30000 }); console.lo
 catch (e) { console.error('FAIL'); process.exit(1); }
 ```
 
-Failure → regress to `gm-execute`. No test.js + testable surface → regress to `gm-execute` to create it.
+Failure → `gm-execute`. No test.js in a repo with testable surface → `gm-execute` to create it.
 
-## GIT ENFORCEMENT
+## Git enforcement
 
 ```
 exec:bash
@@ -82,48 +75,30 @@ git status --porcelain
 git log origin/main..HEAD --oneline
 ```
 
-Both must return empty. Local commit without push ≠ complete.
-
-## CI — AUTOMATED
-
-Stop hook watches all GitHub Actions runs 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 with `gh run view <id> --log-failed`, fix, push, hook re-watches
-- Deadline 180s (override `GM_CI_WATCH_SECS`) → slow jobs get "still in progress" approve
+Both must return empty. Local commit without push is not complete.
 
-## FIX ON SIGHT — HARD RULE
+## CI is automated
 
-Any issue surfaced during verify (test.js failure, browser-validation mismatch, CI red, git-status dirt, hygiene-sweep finding, stress-suite flunk, observability gap) is fixed in-band before declaring complete. Never paper over, never `.skip`, never ship-and-followup, never silence stderr/CI signals. Failure routes to the owning phase: broken output → `gm-emit` | wrong logic → `gm-execute` | new unknown → `planning`. Never declare COMPLETE while a known-bad signal is live.
+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
+## Hygiene sweep
 
-Before declaring complete:
 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 → snake to `planning` with restructuring instructions
+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/deleted
-10. CHANGELOG.md → has entries for this session
+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
+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 = regress to owning phase
-
-## MEMORIZE
-
-```
-Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')
-```
-
-One per fact, parallel, same turn resolved. End-of-turn self-check mandatory.
-
-## COMPLETION DEFINITION
+15. Governance stress-suite → walk change through M1, F1, C1, H1, S1, B1, A1, D1; any flunk regresses to the owning phase
 
-All: witnessed e2e | browser_validated (when client work touched) | failure paths exercised | test.js passes | .prd deleted | git clean+pushed | CI green | hygiene sweep clean | TODO.md gone | CHANGELOG.md updated
+## Completion
 
-**Never**: claim done without witnessed output | claim done on a client change without browser-validation witness | stop while .prd has items | skip hygiene | skip test.js | uncommitted/unpushed work | stop at first green
+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/skills/gm-emit/SKILL.md

@@ -3,30 +3,34 @@ 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
+# GM EMIT — Write and verify from disk
 
-GRAPH: `PLAN → EXECUTE → [EMIT] → VERIFY → COMPLETE`
-Entry: all mutables KNOWN. From `gm-execute` or re-entered from VERIFY.
+Entry: every mutable KNOWN, from `gm-execute` or re-entered from VERIFY. Exit: gates clear → `gm-complete`.
 
-## TRANSITIONS
+Cross-cutting dispositions live in `gm` SKILL.md.
 
-**EXIT → VERIFY**: all gate conditions true → invoke `gm-complete` immediately.
-**SELF-LOOP**: post-emit variance with known cause → fix, re-verify, stay in EMIT.
-**REGRESS → EXECUTE**: pre-emit reveals known logic error.
-**REGRESS → PLAN**: pre-emit reveals new unknown | post-emit variance with unknown cause | scope changed.
+## Transitions
 
-## LEGITIMACY GATE (before pre-emit run)
+- 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`
 
-For every claim landing in a file:
-1. **Earned specificity** — traces to `authorization=witnessed`, not inflated from weak prior?
-2. **Repair legality** — local patch dressed as structural repair? Downgrade scope or snake to PLAN.
-3. **Lawful downgrade** — can a weaker, true statement replace it? PREFER the downgrade.
-4. **Alternative-route suppression** — live competing route being silenced? Preserve it.
-5. **Strongest objection** — if a reviewer pushed back on this change, what would the sharpest argument be? Articulate it. Cannot articulate = have not understood the alternatives = regress to `gm-execute`.
+## Legitimacy gate (before pre-emit run)
 
-Fail any → regress to `gm-execute` to witness what was missing, or `planning` if gap is structural.
+For every claim landing in a file, answer five questions:
 
-## PRE-EMIT RUN (mandatory before writing any file)
+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.
 
 ```
 exec:nodejs
@@ -34,58 +38,29 @@ const { fn } = await import('/abs/path/to/module.js');
 console.log(await fn(realInput));
 ```
 
-1. Import actual module from disk — witness current behavior as baseline
-2. Run proposed logic in isolation WITHOUT writing — witness with real inputs
-3. Probe failure paths with real error inputs
-4. Compare: matches expected → write. Unexpected → new unknown → `planning`.
+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 FILES
+## Writing
 
-`exec:nodejs` with `require('fs')`. Write only when every gate mutable resolved simultaneously.
+`exec:nodejs` with `require('fs')`. Write only when every gate mutable resolves simultaneously.
 
-## POST-EMIT VERIFICATION (immediately after writing)
+## Post-emit verification
 
-1. Re-import from disk (not in-memory — stale is inadmissible)
-2. Run identical inputs as pre-emit — must match pre-emit baseline exactly
-3. Known variance → fix immediately, re-verify (EMIT self-loop)
-4. Unknown variance → new unknown → invoke `planning`
+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`.
 
-## GATE CONDITIONS (all true simultaneously)
+## Gate (all true at once)
 
-- Legitimacy gate passed; none of five refused collapses
-- Pre-emit passed with real inputs + error inputs
+- 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 fallbacks, `|| default`, `catch { return null }`)
-- No mocks/fakes/stubs/scattered test files (delete on discovery)
-- Behavior change in this emit = a corresponding assertion in test.js (a change no test would catch is a change you cannot prove)
-- If this emit changes any browser-facing code (client/, served HTML/JS, shaders, page-bundle imports, gh-pages assets), the post-emit verify MUST include a live browser witness via `exec:browser` (boot server → page.goto → page.evaluate asserting the invariant the change established). Node-side import + test.js does NOT satisfy this — see `gm-complete` BROWSER VALIDATION GATE.
-- Files ≤200 lines
-- No duplicate concern (run exec:codesearch for primary concern after writing; any overlap → `planning`)
-- No comments; no hardcoded values; no adjectives in identifiers; no unnecessary files
-- Observability: new server subsystems expose `/debug/<subsystem>`; new client modules in `window.__debug`
-- Structure: no if/else where dispatch table suffices; no one-liners that require decoding; no reinvented APIs
-- All facts resolved this phase memorized via background Agent(memorize)
-- CHANGELOG.md updated; TODO.md cleared/deleted
-
-## FIX ON SIGHT — HARD RULE
-
-Pre-emit run, post-emit run, or legitimacy gate surfaces ANY issue (failing assertion, stderr, type/lint error, unexpected variance, broken import, runtime throw) → fix at root cause this turn, re-run pre-emit AND post-emit, advance only when all gates pass simultaneously. Never write-and-promise-fix-later, never `try/catch`-to-hide, never `.skip`, never silence with redirection. Known variance → fix and re-verify (self-loop). Unknown variance → regress to `planning`.
-
-## CODE EXECUTION
-
-`exec:<lang>` only. File writes via exec:nodejs + require('fs'). Never Bash(node/npm/npx/bun).
-Pack runs: Promise.allSettled, each idea own try/catch, under 12s per call.
-
-## CODEBASE SEARCH
-
-`exec:codesearch` only. Grep/Glob/Find/Explore = hook-blocked. Known path → `Read`.
-
-## MEMORIZE
-
-```
-Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')
-```
-
-Same turn as resolution. Parallel when multiple. End-of-turn self-check mandatory.
-
-**Never**: write before pre-emit | advance with post-emit variance | absorb surprises | respond to user mid-phase
+- 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

package/skills/gm-execute/SKILL.md

@@ -3,70 +3,61 @@ name: gm-execute
 description: EXECUTE phase AND the foundational execution contract for every skill. Every exec:<lang> run, every witnessed check, every code search, in every phase, follows this skill's discipline. Resolve all mutables via witnessed execution. Any new unknown triggers immediate snake back to planning — restart chain from PLAN.
 ---
 
-# GM EXECUTE — Resolve Every Unknown
+# GM EXECUTE — Resolve every unknown by witness
 
-GRAPH: `PLAN → [EXECUTE] → EMIT → VERIFY → COMPLETE`. Entry: .prd with named unknowns.
+Entry: `.prd` with named unknowns. Exit: every mutable KNOWN → invoke `gm-emit`.
 
-This skill = execution contract for ALL phases. About to run anything → load this first.
+This skill is the execution contract for ALL phases — pre-emit witnesses, post-emit verifies, e2e checks all run on this discipline. Cross-cutting dispositions live in `gm` SKILL.md.
 
-## TRANSITIONS
+## Transitions
 
-- **EXIT → EMIT**: all mutables KNOWN → invoke `gm-emit`.
-- **SELF-LOOP**: still UNKNOWN → re-run different angle (max 2 passes).
-- **REGRESS → PLAN**: new unknown | unresolvable after 2 passes.
+- All mutables KNOWN → `gm-emit`
+- Still UNKNOWN → re-run from a different angle (max 2 passes)
+- New unknown OR unresolvable after 2 passes → `planning`
 
-## MUTABLE DISCIPLINE
+## Mutable discipline
 
-Each mutable: name | expected | current | resolution method.
+Each mutable carries: name, expected, current, resolution method.
 
-Resolves to KNOWN only when ALL four pass:
-- **ΔS=0** — witnessed output equals expected
-- **λ≥2** — two independent paths agree
-- **ε intact** — adjacent invariants hold
-- **Coverage≥0.70** — enough corpus inspected
-
-Unresolved after 2 passes = regress to `planning`. Never narrate past an unresolved mutable.
-
-## PRIORS DON'T AUTHORIZE
-
-Route candidates from PLAN = `weak_prior` only. Plausibility = right to TEST, not BELIEVE.
-weak_prior → witnessed probe → witnessed → feed to EMIT. "The plan says" / "obviously X" = prior, not fact.
+Resolves to KNOWN only when all four pass:
 
-Claims in response prose stand or fall by their last witness. A claim with no witness in this session is a hypothesis, not a finding — say so when you state it, and say what would settle it. The next reader (you, next turn) needs to know which lines were earned and which were carried forward.
+- **ΔS = 0** — witnessed output equals expected
+- **λ ≥ 2** — two independent paths agree
+- **ε intact** — adjacent invariants hold
+- **Coverage ≥ 0.70** — enough corpus inspected to rule out contradiction
 
-## VERIFICATION BUDGET
+Unresolved after 2 passes regresses to `planning`. Never narrate past an unresolved mutable.
 
-Spend on `.prd` items in descending order of consequence-if-wrong × distance-from-witnessed. Items whose failure would collapse the headline finding must reach witnessed status before EMIT; items with sub-argument-level consequence need at minimum a stated fallback path.
+Route candidates from PLAN are `weak_prior` only. Plausibility is the right to test, not the right to believe. A claim with no witness in the current session is a hypothesis — say so when stating it, and say what would settle it. The next reader (you, next turn) needs to know which lines were earned and which were carried forward.
 
-## CODE EXECUTION
+## Verification budget
 
-`exec:<lang>` only via Bash: `exec:<lang>\n<code>`
+Spend on `.prd` items in descending order of consequence-if-wrong × distance-from-witnessed. Items whose failure would collapse the headline finding must reach witnessed status before EMIT; sub-argument-level items need at minimum a stated fallback path.
 
-Langs: `nodejs` (default) | `bash` | `python` | `typescript` | `go` | `rust` | `c` | `cpp` | `java` | `deno` | `cmd`
+## Code execution
 
-File I/O: exec:nodejs + require('fs'). Git directly in Bash. **Never** Bash(node/npm/npx/bun).
+`exec:<lang>` only via Bash. Languages: nodejs (default), bash, python, typescript, go, rust, c, cpp, java, deno, cmd. File I/O via `exec:nodejs` + `require('fs')`. Git directly in Bash. Never `Bash(node/npm/npx/bun)`.
 
-Pack runs: Promise.allSettled parallel, each idea own try/catch, under 12s per call.
-Runner: `exec:runner\nstart|stop|status`
+Pack runs: `Promise.allSettled`, each idea own try/catch, under 12s per call. Runner: `exec:runner\n{start|stop|status}`.
 
-Every exec daemonizes. The hook tails the task logfile up to 30s wall-clock and returns whatever it has — short tasks complete inside the window and look synchronous; long tasks return a task_id with partial output and the agent continues with `exec:tail` (drain more output, bounded), `exec:watch` (resume blocking until text/regex match or timeout), or `exec:close` (terminate). Never re-spawn a long task to "check on it" — that orphans the first one. `exec:wait` is a pure timer with no log scanning; `exec:sleep` blocks on a specific task's output; `exec:watch` is the match-or-timeout primitive. Every interaction with the execution platform returns the live list of running tasks for this session — close stragglers via `exec:close\n<id>` so the list stays scannable. Session-end (clear/logout/prompt_input_exit) kills the session's tasks; compaction/handoff preserves them.
+Every exec daemonizes. The hook tails the task logfile up to 30s wall-clock and returns whatever is there — short tasks complete inside the window and look synchronous; long tasks return a task_id with partial output. Continue with `exec:tail` (drain, bounded), `exec:watch` (resume blocking until match or timeout), or `exec:close` (terminate). Never re-spawn a long task to check on it — that orphans the first one. `exec:wait` is a pure timer; `exec:sleep` blocks on a specific task's output; `exec:watch` is the match-or-timeout primitive. Every execution-platform RPC returns the live list of running tasks for this session — close stragglers via `exec:close\n<id>` so the list stays scannable. Session-end (clear/logout/prompt_input_exit) kills the session's tasks; compaction/handoff preserves them.
 
-## CODEBASE SEARCH
+Utility verbs (`exec:wait`, `exec:sleep`, `exec:status`, `exec:close`, `exec:pause`, `exec:type`, `exec:runner`, `exec:kill-port`, `exec:recall`, `exec:memorize`, `exec:forget`) take their argument on the next line. Inline form (`exec:status <id>`) is denied by the hook.
 
-`exec:codesearch` only. Grep/Glob/Find/Explore/grep/rg/find = hook-blocked.
+## Codebase search
 
-Known absolute path → `Read`. Known dir → exec:nodejs + fs.readdirSync.
+`exec:codesearch` only. Grep, Glob, Find, Explore, raw grep/rg/find inside `exec:bash` are all hook-blocked.
 
 ```
 exec:codesearch
 <two-word query>
 ```
 
-Iterate: change/add one word per pass. Min 4 attempts before concluding absent.
+Start two words, change/add one per pass, minimum four attempts before concluding absent. Known absolute path → `Read`. Known directory → `exec:nodejs` + `fs.readdirSync`.
 
-## IMPORT-BASED EXECUTION
+## Import-based execution
 
-Always import actual modules. Reimplemented = UNKNOWN.
+Hypotheses become real by importing actual modules from disk. Reimplemented behavior is UNKNOWN.
 
 ```
 exec:nodejs
@@ -74,76 +65,16 @@ const { fn } = await import('/abs/path/to/module.js');
 console.log(await fn(realInput));
 ```
 
-Differential diagnosis: smallest reproduction → compare actual vs expected → name the delta = mutable.
-
-## CI — AUTOMATED
-
-`git push` → Stop hook auto-watches Actions for pushed HEAD. Same-repo only — downstream cascades not auto-watched.
-- Green → Stop approves with summary
-- Failure → run names+IDs → `gh run view <id> --log-failed`
-- Deadline 180s (override `GM_CI_WATCH_SECS`)
-
-## GROUND TRUTH
-
-Real services, real data, real timing. Mocks/stubs/scattered tests/fallbacks = delete.
-
-**Scan before edit**: exec:codesearch before creating/modifying. Duplicate concern = regress to `planning`.
-**Hypothesize via execution**: hypothesis → run → witness → edit. Never edit on unwitnessed assumption.
-**Code quality**: native → library → structure (map/pipeline) → write.
-
-## PARALLEL SUBAGENTS
-
-≤3 `gm:gm` subagents for independent items in ONE message. Browser escalation: exec:browser → browser skill → screenshot last resort.
-
-## RECALL — HARD RULE
-
-Before resolving any new unknown via fresh execution, recall first.
-
-```
-exec:recall
-<2-6 word query>
-```
-
-Triggers: "did we hit this" | feels familiar | new sub-task in known project | about to comment a non-obvious choice | about to ask user something likely discussed.
-
-Hits = weak_prior; still witness. Empty = proceed. Capped 6s, ~5ms when serve running. ~200 tokens / 5 hits.
-
-## MEMORIZE — HARD RULE
-
-Unknown→known = same-turn memorize.
-
-```
-Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')
-```
-
-Triggers: exec output answers prior unknown | CI log reveals root cause | code read confirms/refutes | env quirk | user states preference/constraint.
-
-N facts → N parallel Agent calls in ONE message. End-of-turn self-check mandatory.
-
-## FIX ON SIGHT — HARD RULE
-
-Issue surfaced mid-execution (failing test, exec stderr, broken import, runtime exception, lint/type error, deprecation warning, unexpected output) is fixed THIS turn, at root cause, in-band. Never `// TODO`, never `try/catch`-to-swallow, never `2>/dev/null`, never `.skip`, never "out of scope" inside the same file. Re-witness after fix. New unknown surfaced by the fix → regress to `planning`. Genuine out-of-scope → write a `.gm/prd.yml` item before continuing.
-
-**Incidental errors auto-plan**: a reasonably-fixable issue that is *not* what the user asked about — pre-existing build break, lockfile drift, broken dep feature, dead import in adjacent module, missing artifact, neighboring lint failure — still belongs to the agent. Add it to `.gm/prd.yml` the same turn it surfaces and execute it before COMPLETE. Do not ask the user; do not narrate past it; do not file it as "next session." Only errors that genuinely need user credentials, decisions, or external services that are down are name-and-stop, recorded with `blockedBy: external`.
-
-**Obvious re-architecting auto-plans**: same discipline for clear refactor wins surfaced mid-task — code competing with an existing library/package that does the same thing, multi-file ad-hoc logic one import would replace, duplicated logic asking for one helper. Regress to `planning`, add the item, execute. Bar is *obvious + reachable from this session*; speculative refactors stay out.
-
-**Cross-session PRD**: items in `.gm/prd.yml` from prior sessions are this session's work the moment they're discovered. Finish every item in the file before COMPLETE — including ones the current user message did not mention. "From another session" is not an exemption.
-
-## BROWSER WITNESS — HARD RULE
+Differential diagnosis: smallest reproduction → compare actual vs expected → name the delta — that delta is the mutable.
 
-Editing browser-facing code (under `client/`, `docs/`, `*.html`, shaders, page-bundle imports, served JS/CSS, gh-pages assets, anything imported by a browser entry, anything visible in DOM/canvas/WebGL) → live `exec:browser` witness in THIS phase, same turn as the edit. Not deferred to EMIT, not deferred to VERIFY — those layers re-witness on top, they don't replace this one.
+## Edits depend on witnesses
 
-Protocol on every client edit:
-1. Boot server / open page → HTTP 200 witnessed
-2. `exec:browser` → `page.goto(url)` → poll the affected global (`window.__app.<system>`, `window.__debug.<module>`)
-3. `page.evaluate` asserting the specific invariant the change establishes — capture numbers
-4. Variance → fix at root cause, re-witness (FIX ON SIGHT). Never advance to EMIT on unwitnessed client behavior.
+Hypothesis → run → witness → edit. An edit before a witness is a guess. Scan via `exec:codesearch` before creating or modifying — duplicate concern regresses to `planning`. Code-quality preference: native → library → structure → write.
 
-Forbidden: `node test.js` green as a substitute | screenshot without evaluate | "I'll check it in VERIFY" then skipping | committing a client diff without an `exec:browser` block this turn. Exempt only for server-only / no-browser repos; tag the exemption explicitly.
+## Parallel subagents
 
-## CONSTRAINTS
+Up to 3 `gm:gm` subagents for independent items in one message. Browser escalation: `exec:browser` → `browser` skill → screenshot only as last resort.
 
-**Never**: Bash(node/npm/npx/bun) | fake data | mocks | scattered tests | fallbacks | Grep/Glob/Find/Explore | sequential independent items | respond mid-phase | edit before witnessing | duplicate code | if/else where dispatch suffices | one-liners that obscure | reinvent native/library
+## CI is automated
 
-**Always**: witness every hypothesis | import real modules | scan before edit | regress on new unknown | delete mocks/comments/scattered tests on discovery | update test.js for behavior changes | invoke next skill immediately when done | weight verification by load
+`git push` triggers the Stop hook to watch Actions for the pushed HEAD on the same repo (downstream cascades are not auto-watched). Green → Stop approves with summary; failure → run names + IDs surfaced, investigate via `gh run view <id> --log-failed`. Deadline 180s (override `GM_CI_WATCH_SECS`).

package/skills/governance/SKILL.md

@@ -3,24 +3,25 @@ name: governance
 description: Governance reference invoked by PLAN/EXECUTE/EMIT/VERIFY. Separates route discovery (PLAN) from weak-prior handoff (EXECUTE) from earned-emission legitimacy (EMIT/VERIFY). Encodes 16-failure taxonomy, 4 state planes, ΔS/λ/ε/Coverage metrics, governance stress suite.
 ---
 
-# Governance — Route, Bridge, Legitimacy
+# Governance — Route, bridge, legitimacy
 
-Three roles, three failure surfaces:
-1. **Route discovery** — what family of fault? Owned by `planning`.
-2. **Weak-prior bridge** — plausibility ≠ authorization. Owned by `gm-execute`.
-3. **Legitimacy gate** — did this answer earn its strength? Owned by `gm-emit`/`gm-complete`.
+Three roles, three failure surfaces.
 
-## Five Refused Collapses
+1. Route discovery — what family of fault? Owned by `planning`.
+2. Weak-prior bridge — plausibility is not authorization. Owned by `gm-execute`.
+3. Legitimacy gate — did this answer earn its strength? Owned by `gm-emit` and `gm-complete`.
 
-1. Route → authorization ("plan looks good" → "code is right")
-2. Candidate → structural repair (local patch presented as architectural fix)
+## Five refused collapses
+
+1. Route → authorization ("plan looks good" treated as "code is right")
+2. Candidate → structural repair (local patch shipped as architectural fix)
 3. Hidden → public law (internal convenience shipped as contract)
-4. Cleanliness → legitimacy (compiles = evidence-supports)
+4. Cleanliness → legitimacy (compiles treated as evidence-supports)
 5. One strong route → universal closure (best answer treated as only answer)
 
-When in doubt: preserve ambiguity. Lawful downgrade beats forced closure.
+When in doubt, preserve ambiguity. Lawful downgrade beats forced closure.
 
-## 7 Route Families
+## 7 route families
 
 | Family | What breaks | Repair |
 |---|---|---|
@@ -32,7 +33,7 @@ When in doubt: preserve ambiguity. Lawful downgrade beats forced closure.
 | boundary | Interfaces, contracts, seams | Re-assert contract from one source |
 | representation | Data shape, schema, type | Make illegal states unrepresentable |
 
-## 16 Failure Modes
+## 16 failure modes
 
 | # | Name | Family |
 |---|---|---|
@@ -53,7 +54,7 @@ When in doubt: preserve ambiguity. Lawful downgrade beats forced closure.
 | 15 | Deployment deadlock | execution |
 | 16 | Pre-deploy collapse | execution |
 
-## 4 State Planes
+## 4 state planes
 
 | Plane | Owner | States | Implication |
 |---|---|---|---|
@@ -62,18 +63,18 @@ When in doubt: preserve ambiguity. Lawful downgrade beats forced closure.
 | repair_legality | gm-emit | unverified → local_candidate → structural | Local cannot ship as structural |
 | hidden_decision_posture | gm-complete | open → down_weighted → closed | Close only after CI green |
 
-## Quality Metrics
+## Quality metrics
 
 - **ΔS** — witnessed output equals expected. ΔS≠0 = still open.
-- **λ≥2** — two independent paths agree. λ=1 = still unknown.
+- **λ ≥ 2** — two independent paths agree. λ=1 = still unknown.
 - **ε** — adjacent invariants hold (types, tests, neighboring callers).
-- **Coverage≥0.70** — enough corpus inspected to rule out contradicting evidence.
+- **Coverage ≥ 0.70** — enough corpus inspected to rule out contradicting evidence.
 
-All four must pass before mutable flips UNKNOWN→KNOWN.
+All four pass before a mutable flips UNKNOWN → KNOWN.
 
-## Stress Suite (8 Cases)
+## Stress suite
 
-Run before declaring COMPLETE:
+Run before declaring COMPLETE.
 
 | # | Case | Failure if flunked |
 |---|---|---|
@@ -86,11 +87,11 @@ Run before declaring COMPLETE:
 | A1 | Authenticity eval partial signals | Surface appearance beats evidence |
 | D1 | Deploy-gate under CI flake | Treats noise as green |
 
-Legal: illegal_commitment=0, evidence_boundary_violation=0, lawful_downgrade=available in all 8, outlier_visibility=preserved.
+Legal: `illegal_commitment=0`, `evidence_boundary_violation=0`, `lawful_downgrade=available` in all 8, `outlier_visibility=preserved`.
 
-## Phase Application
+## Phase application
 
 - **planning** — tag every `.prd` item with route family + failure-mode IDs
-- **gm-execute** — weak prior only; witnessed probe required before authorization
+- **gm-execute** — weak prior only; witnessed probe before authorization
 - **gm-emit** — legitimacy gate; unearned specificity → lawful downgrade
-- **gm-complete** — stress-suite pass; close posture only CI green
+- **gm-complete** — stress-suite pass; close posture only when CI is green