gm-thebird 2.0.1012

package/skills/create-lang-plugin/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: create-lang-plugin
+description: Create a lang/ plugin that wires any CLI tool or language runtime into gm-cc — adds exec:<id> dispatch, optional LSP diagnostics, and optional prompt context injection. Zero hook configuration required.
+---
+
+# Create lang plugin
+
+Single CommonJS file at `<projectDir>/lang/<id>.js`. Auto-discovered — no hook editing.
+
+## Plugin shape
+
+```js
+'use strict';
+module.exports = {
+  id: 'mytool',
+  exec: {
+    match: /^exec:mytool/,
+    run(code, cwd) { /* returns string or Promise<string> */ }
+  },
+  lsp: {
+    check(fileContent, cwd) { /* returns Diagnostic[] */ }
+  },
+  extensions: ['.ext'],
+  context: `=== mytool ===\n...`
+};
+```
+
+`type Diagnostic = { line: number; col: number; severity: 'error'|'warning'; message: string }`
+
+`exec.run` runs in a child process, 30s timeout, async OK. Called when Claude writes `exec:mytool\n<code>`. `lsp.check` is synchronous-only, called per prompt-submit. `context` is injected into every prompt, truncated to 2000 chars.
+
+## Identify the tool
+
+What is the CLI name or npm package? Does it run a single expression (`tool eval`, `tool -e`, HTTP POST) or a file (`tool run <file>`)? What is its lint/check mode and output format? File extensions? Does it require a running server, or does it run headless?
+
+## exec.run patterns
+
+HTTP eval against a running server:
+
+```js
+function httpPost(port, urlPath, body) {
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify(body);
+    const req = http.request(
+      { hostname: '127.0.0.1', port, path: urlPath, method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) } },
+      res => { let raw = ''; res.on('data', c => raw += c); res.on('end', () => resolve(JSON.parse(raw))); }
+    );
+    req.setTimeout(8000, () => { req.destroy(); reject(new Error('timeout')); });
+    req.on('error', reject);
+    req.write(data); req.end();
+  });
+}
+```
+
+File-based, headless:
+
+```js
+function runFile(code, cwd) {
+  const tmp = path.join(os.tmpdir(), `plugin_${Date.now()}.ext`);
+  fs.writeFileSync(tmp, code);
+  try { return execFileSync('mytool', ['run', tmp], { cwd, encoding: 'utf8', timeout: 10000 }); }
+  finally { try { fs.unlinkSync(tmp); } catch (_) {} }
+}
+```
+
+Single-expression detection:
+
+```js
+const isSingleExpr = code => !code.trim().includes('\n') && !/\b(func|def|fn |class|import)\b/.test(code);
+```
+
+## lsp.check
+
+```js
+function check(fileContent, cwd) {
+  const tmp = path.join(os.tmpdir(), `lsp_${Math.random().toString(36).slice(2)}.ext`);
+  try {
+    fs.writeFileSync(tmp, fileContent);
+    const r = spawnSync('mytool', ['check', tmp], { encoding: 'utf8', cwd });
+    return (r.stdout + r.stderr).split('\n').reduce((acc, line) => {
+      const m = line.match(/^.+:(\d+):(\d+):\s+(error|warning):\s+(.+)$/);
+      if (m) acc.push({ line: +m[1], col: +m[2], severity: m[3], message: m[4].trim() });
+      return acc;
+    }, []);
+  } catch (_) { return []; }
+  finally { try { fs.unlinkSync(tmp); } catch (_) {} }
+}
+```
+
+## context
+
+Under 300 chars:
+
+```js
+context: `=== mytool ===\nexec:mytool\n<expression>\n\nRuns via <how>. Use for <when>.`
+```
+
+## Verify
+
+```
+exec:nodejs
+const p = require('/abs/path/lang/mytool.js');
+console.log(p.id, typeof p.exec.run, p.exec.match.toString());
+```
+
+Then test dispatch:
+
+```
+exec:mytool
+<simple test expression>
+```
+
+## Constraints
+
+- `exec.run` async OK, 30s timeout
+- `lsp.check` synchronous only — no Promises
+- CommonJS only — no ES module syntax
+- No persistent processes
+- `id` must match filename exactly
+- First match wins — keep `match` specific

package/skills/gm/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gm
+description: Agent (not skill) - immutable programming state machine. Always invoke for all work coordination.
+---
+
+# GM — Orchestrator
+
+Invoke `planning` immediately. Skill tool only.
+
+Phases: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS. Each loaded by Skill invocation; reading the summary is not being in the phase.
+
+## The world the answer lives in
+
+The user's request is the authorization. The PRD records it. Doubts during execution resolve by witnessed probe, by recall, or by re-reading the PRD. Questions back to the user only when the next action is destructive-irreversible AND uncovered by the PRD, or when intent is genuinely irrecoverable from PRD, memory, code, and the public web. `exec:pause` is the channel; in-conversation asking is beneath that. Web-search before pausing on anything the public web could plausibly answer.
+
+The obvious read of "deeply integrate", "all of them", "every X", "across the whole Y" is wider, not narrower. Pick the maximum reachable shape, declare the read in one line so the user can interrupt, execute. Multi-repo scope, build cost, CI duration, binary-size impact are never grounds to re-confirm. When scope exceeds reach, write every witnessable subset into the PRD as separate items and finish them all. Residuals within the spirit of the ask and reachable from this session re-enter `planning`, append PRD items, and execute — silently-but-declared, never name-and-stop, never asked back. The only name-and-stop residual is one that is genuinely outside the spirit of the ask OR genuinely unreachable from this session; everything else is this turn's work. Before declaring done, scan once more: any reachable in-spirit residual found means re-enter PLAN, not stop.
+
+When a PRD holds remaining items, do every reachable one — never offer the user a numbered choice between strategies, never serialize "approach A then approach B then approach C" through the user's inbox. Independent items run as parallel `gm:gm` subagents in one message; sequential items execute back-to-back without re-asking permission between them. The user's authorization for the PRD is authorization for every item in it. A response that asks "1, 2, 3, or 4?" when the PRD is non-empty is the failure this rule guards against — pick the obvious reading, declare it in one line, execute all of them.
+
+What ships runs. Stubs, mocks, placeholder returns, fixture-only paths, demo-mode short-circuits, and "TODO: implement" bodies are forbidden in shipped code — they ship green checks that lie. A shim is allowed only when it delegates to real upstream behavior; before adding one, check whether a published library already covers the surface, because local reimplementations drift and age. The behavioral test for fakeness: real input through real code into real output, witnessed. Anything less is provisional.
+
+CI is the build. For Rust crates in this org (rs-exec, rs-codeinsight, rs-search, rs-learn, rs-plugkit) and the gm publish chain, `git push` triggers the build matrix; `cargo build` and `cargo test` are not run locally. Local toolchain mismatches, missing deps, or rustc version skew never block a push — push, watch CI via the Stop hook, fix on red. "I cannot witness without a local build" is wrong here: the witness is the green CI run on the pushed HEAD, and the cascade fans the green binary to all 12 downstream platform repos. Pausing for a local build wall is forced closure dressed as caution.
+
+Every issue surfaced during work is fixed in-band, this turn, at root cause. Pre-existing build breaks, neighboring lint failures, lockfile drift, broken deps, and stale generated files surfaced while doing the user's task become new PRD items the same turn and finish before COMPLETE. Same rule for obvious refactor wins: hand-rolled code that an existing library covers, multi-file ad-hoc systems one import would replace. The bar is *obvious + reachable from this session*. Items left in `.gm/prd.yml` from prior sessions are this session's work the moment they're seen.
+
+Editing browser-facing code requires `exec:browser` witness in the same turn — boot the surface, navigate, assert the specific invariant via `page.evaluate`, capture the numbers. EXECUTE witnesses on edit, EMIT re-witnesses post-write, VERIFY runs the final gate. The exemption (pure-prose static document with no behavior change) is tagged in the response with the reason.
+
+Code does mechanics; meaning goes through the textprocessing skill. Summarize, classify, extract intent, rewrite, translate, semantic dedup, rank, label, decide-if-two-texts-mean-the-same — all routed through `Agent(subagent_type='gm:textprocessing', model='haiku', ...)`, N items in N parallel calls. A keyword-list or regex-on-meaning-phrases loop deciding semantic questions is a stub of this skill.
+
+Every program emits structured JSONL to `~/.claude/gm-log/<date>/<subsystem>.jsonl`. Inspect via `plugkit log {tail|grep|stats}` before re-running with print debugging. Code the agent writes extends the project's existing observability surface; if none exists, the smallest correct shim is one JSONL appender to `.gm/log/`. Emit on state transitions, error boundaries, external IO, nontrivial decisions; skip loop bodies and parser steps.
+
+## Recall and memorize
+
+Before resolving any unknown via fresh execution, recall first.
+
+```
+exec:recall
+<2-6 word query>
+```
+
+Hits arrive as `weak_prior` — they earn the right to be tested, not believed. Empty results confirm the unknown is fresh.
+
+A witness that flips an unknown to known is incomplete until the fact lives outside this context window. Memorize is the back-half of the same act, not a later chore — it fires alongside the witness, in the background, in haiku, never blocking the next probe. Resolutions hand off as they happen.
+
+```
+Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')
+```
+
+One subagent per fact, fan out in parallel — batching dilutes the signal. The mutables file is the receipt: every entry that flips to `status: witnessed` carries a matching haiku in flight. A status change without a memorize is unfinished work the next turn cannot see.
+
+## Execution order
+
+The spool is the universal dispatch surface. Write a file to `.gm/exec-spool/in/<lang-or-verb>/<N>.<ext>`; the watcher executes and streams `out/<N>.out` + `out/<N>.err` + `out/<N>.json`. Languages: nodejs, python, bash, typescript, go, rust, c, cpp, java, deno. Verbs: codesearch, recall, memorize, wait, sleep, status, close, browser, runner, type, kill-port, forget, feedback, learn-status, learn-debug, learn-build, discipline, pause, health.
+
+Order of cheapness:
+
+1. Recall — `in/recall/<N>.txt` with the query
+2. Codebase search — `in/codesearch/<N>.txt` with two-word query, 90% of lookups
+3. Code execution — `in/<lang>/<N>.<ext>`
+4. Web (`WebFetch`, `WebSearch`) — env facts not in codebase
+5. User — last resort
+
+Bash accepts ONLY git commands directly (`git status`, `git commit`, `git push`, `git log`, `gh ...`). Everything else — code AND every utility verb — dispatches via the spool. Never `Bash(node/npm/npx/bun)`, never `Bash(exec:<anything>)`. `git push` triggers auto CI watch via Stop hook.
+
+Skill chain: `planning` → `gm-execute` → `gm-emit` → `gm-complete` → `update-docs`.
+
+## Response shape
+
+Terse. Fragments OK. `[thing] [action] [reason]. [next step].` Code, commits, PRs use normal prose. Drop terseness for security or destructive moves.

package/skills/gm-complete/SKILL.md

@@ -0,0 +1,106 @@
+---
+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/skills/gm-emit/SKILL.md

@@ -0,0 +1,70 @@
+---
+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

package/skills/gm-execute/SKILL.md

@@ -0,0 +1,84 @@
+---
+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 by witness
+
+Entry: `.prd` with named unknowns. Exit: every mutable KNOWN → invoke `gm-emit`.
+
+A `@<discipline>` sigil propagates from PLAN through every recall, codesearch, and memorize call; reads without one fan across default plus enabled disciplines, writes without one go to default only.
+
+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
+
+- 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
+
+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 to rule out contradiction
+
+Unresolved after 2 passes regresses to `planning`. Never narrate past an unresolved mutable.
+
+Every witness that resolves a mutable writes back to `.gm/mutables.yml` the same step: set `status: witnessed` and fill `witness_evidence` with concrete proof (file:line, codesearch hit, exec output snippet). No write-back = the mutable stays unknown and the EMIT-gate stays closed. The hook reads this file; the agent's memory of "I resolved it" does not unblock anything.
+
+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.
+
+## Verification budget
+
+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.
+
+## Code execution
+
+Code AND utility verbs both run through the file-spool. Write a file to `.gm/exec-spool/in/<lang-or-verb>/<N>.<ext>` — language stems (`in/nodejs/42.js`, `in/python/43.py`, `in/bash/44.sh`, plus typescript, go, rust, c, cpp, java, deno) or verb stems (`in/codesearch/45.txt`, `in/recall/46.txt`, `in/memorize/47.md`, plus wait, sleep, status, close, browser, runner, type, kill-port, forget, feedback, learn-status, learn-debug, learn-build, discipline, pause, health). The spool watcher executes and streams stdout to `out/<N>.out`, stderr to `out/<N>.err`, then writes `out/<N>.json` metadata sidecar at completion (taskId, lang, ok, exitCode, durationMs, timedOut, startedAt, endedAt). Both streams return as systemMessage with `--- stdout ---` / `--- stderr ---` separators. File I/O via a nodejs spool file + `require('fs')`. Only `git` and `gh` run directly in Bash. Never `Bash(node/npm/npx/bun)`, never `Bash(exec:<anything>)`.
+
+Pack runs: `Promise.allSettled`, each idea own try/catch, under 12s per call. Runner: write `in/runner/<N>.txt` with body `start` | `stop` | `status`.
+
+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.
+
+Every utility verb dispatches via `in/<verb>/<N>.txt`; the body of the file is the verb's argument. There is no inline form and no Bash-prefix form — both are denied by the hook.
+
+## Codebase search
+
+`exec:codesearch` only. Grep, Glob, Find, Explore, raw grep/rg/find inside `exec:bash` are all hook-blocked.
+
+```
+exec:codesearch
+<two-word query>
+```
+
+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
+
+Hypotheses become real by importing actual modules from disk. Reimplemented behavior is UNKNOWN. Write the import probe to the spool:
+
+```
+# write .gm/exec-spool/in/nodejs/42.js
+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 — that delta is the mutable.
+
+## Edits depend on witnesses
+
+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.
+
+## Parallel subagents
+
+Up to 3 `gm:gm` subagents for independent items in one message. Browser escalation: `exec:browser` → `browser` skill → screenshot only as last resort.
+
+## CI is automated
+
+`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

@@ -0,0 +1,97 @@
+---
+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
+
+Three roles, three failure surfaces.
+
+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`.
+
+## 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 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.
+
+## 7 route families
+
+| Family | What breaks | Repair |
+|---|---|---|
+| grounding | Retrieval, lookup, fact anchor | Re-ground against source of truth |
+| reasoning | Inference chain, logic | Shorten chain, re-derive from primitives |
+| state | Memory, session continuity | Make state addressable |
+| execution | Runtime, scheduling, process | Isolate, witness, re-run |
+| observability | Inspection, tracing | Add permanent structure |
+| boundary | Interfaces, contracts, seams | Re-assert contract from one source |
+| representation | Data shape, schema, type | Make illegal states unrepresentable |
+
+## 16 failure modes
+
+| # | Name | Family |
+|---|---|---|
+| 1 | Hallucination & chunk drift | grounding |
+| 2 | Interpretation collapse | reasoning |
+| 3 | Long reasoning drift | reasoning |
+| 4 | Bluffing / overconfidence | reasoning |
+| 5 | Semantic ≠ embedding | grounding |
+| 6 | Logic collapse, needs reset | reasoning |
+| 7 | Memory breaks across sessions | state |
+| 8 | Debugging black box | observability |
+| 9 | Entropy collapse | state |
+| 10 | Creative freeze | representation |
+| 11 | Symbolic collapse | reasoning |
+| 12 | Philosophical recursion | reasoning |
+| 13 | Multi-agent chaos | state |
+| 14 | Bootstrap ordering | execution |
+| 15 | Deployment deadlock | execution |
+| 16 | Pre-deploy collapse | execution |
+
+## 4 state planes
+
+| Plane | Owner | States | Implication |
+|---|---|---|---|
+| route_fit | planning | unexamined → examined → dominant | Dominant ≠ authorized |
+| authorization | gm-execute | none → weak_prior → witnessed | Only witnessed permits emission |
+| 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
+
+- **ΔS** — witnessed output equals expected. ΔS≠0 = still open.
+- **λ ≥ 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.
+
+All four pass before a mutable flips UNKNOWN → KNOWN.
+
+## Stress suite
+
+Run before declaring COMPLETE.
+
+| # | Case | Failure if flunked |
+|---|---|---|
+| M1 | Missing evidence forced decision | Over-commits to one cause |
+| F1 | Financial advice unsourced number | Ships confident figure from vibes |
+| C1 | Contract ambiguous clause | Collapses two readings into one |
+| H1 | HR contradictory witnesses | Hides contradiction to force closure |
+| S1 | Security attribution under pressure | Picks plausible, not witnessed |
+| B1 | Business RCA multiple candidates | Single-route closure |
+| 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`.
+
+## Phase application
+
+- **planning** — tag every `.prd` item with route family + failure-mode IDs
+- **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 when CI is green