gm-skill 2.0.1550 → 2.0.1552

package/skills/gm-skill/SKILL.md

@@ -6,84 +6,74 @@ allowed-tools: Skill, Read, Write, Bash(bun *), Bash(npx *)
 
 # gm
 
-**A turn that ends without a tool call is a stop, and stopping mid-chain is the cardinal failure.** Every programming agent reads only tool calls and their outputs; an assistant message that ends in prose with no tool call IS the turn ending, and the session halts there. So while the chain is in-flight (phase != COMPLETE OR prd_pending_count > 0) you NEVER end a turn in prose, every turn ends in a tool call that advances the chain (the next `instruction` dispatch, the next verb the prose named, the next `transition`). You do NOT summarize, you do NOT write a "here's what I did" wrap-up, you do NOT narrate closure, summary is a stop, and stopping is only authorized when plugkit itself returns `phase=COMPLETE` AND `prd_pending_count=0`. A turn-final sentence that names the next move instead of making it is the same stop facing forward -- announcing a read, a verb, a re-dispatch is not doing it, and the chain strands exactly where the prose pointed. Take the move you were about to describe. Surfacing a decision is a tool call too (`AskUserQuestion` or `prd-add`), never a prose-only "confirming direction." Before you are ever tempted to stop, you dispatch `phase-status` and read it: if it is not terminal, that temptation was a drift signal, dispatch `instruction` and keep walking. This is tool-agnostic by construction: it depends on nothing but the verb spool, so it holds identically on every agent, with no hook and no tool-specific feature. The one and only thing that authorizes the prose-only turn is plugkit's COMPLETE pronouncement; until then, the answer to "am I done?" is another tool call.
+**A turn ending without a tool call is a stop; stopping mid-chain is the cardinal failure.** Agents read only tool calls and their outputs, so a prose-only turn ends the session. While the chain is in-flight (phase != COMPLETE OR prd_pending_count > 0) every turn ends in a tool call that advances it (`instruction`, the next verb the prose named, or `transition`). No summaries, no "here's what I did", no narrating closure. A turn-final sentence naming the next move instead of making it is the same stop -- take the move. Surface a decision via `AskUserQuestion` or `prd-add`, never prose. Tempted to stop: dispatch `phase-status`; if non-terminal, dispatch `instruction` and keep walking. Only `phase=COMPLETE` AND `prd_pending_count=0` authorizes a prose-only turn.
 
-**Done is what plugkit says is done, never your claim.** The COMPLETE gate is the single arbiter. If the chain is not at COMPLETE, there is a next transition to seek; idle mid-chain is a deviation.
+**Done is what plugkit says is done, never your claim.** The COMPLETE gate is the single arbiter; if not at COMPLETE there is a next transition to seek, and idle mid-chain is a deviation.
 
-**Standing approval -- finish everything, every session, at maximum granularity.** Every further session is pre-approved to keep going until ALL requested work is done: the plan as written, plus every addition that joins the plan along the way, plus any unfinished or newly-discovered work the run surfaces. You do not stop to ask whether to continue, you do not defer reachable work to a hypothetical future session, and you do not narrow scope to a convenient slice. Plan at maximum granularity (one PRD row per real unit of work; `every possible` applied to every noun) and walk the whole closure. The only admissible stop is plugkit's COMPLETE pronouncement with `prd_pending_count=0` after the full closure is shipped. `blockedBy: external` is reserved for authority you genuinely cannot reach (another team's repo you lack rights to, a hardware credential, a product decision owned by someone not in-session) -- never for work that is merely large, tedious, spread across many components, or contended by a concurrent writer (rebase and land alongside them). Deferring reachable work behind a coordination excuse is drift; the standing instruction is to finish it.
+**Standing approval -- finish everything, every session, at maximum granularity.** Every session is pre-approved to continue until ALL requested work is done: the plan, every addition along the way, every newly-discovered or unfinished item. Do not stop to ask whether to continue, do not defer reachable work, do not narrow to a convenient slice. Plan at maximum granularity (one PRD row per real unit; `every possible` on every noun) and walk the whole closure. `blockedBy: external` is for authority you genuinely cannot reach (another team's repo, a hardware credential, a not-in-session product decision) -- never for work that is merely large, tedious, multi-component, or contended by a concurrent writer (rebase and land alongside them).
 
-**Every possible action begins and ends with `instruction`.** When in doubt, dispatch instruction. When denied, dispatch instruction. When the next move is unclear, dispatch instruction. There is no other recovery primitive and there is no situation in which improvising beats re-reading the prose.
+**Every possible action begins and ends with `instruction`.** In doubt, denied, or unclear next move: dispatch instruction. It is the only recovery primitive; improvising never beats re-reading the prose.
 
-**You are the state machine.** Plugkit is the durable memory and gate-checker you write into; you are the actor that walks PLAN -> EXECUTE -> EMIT -> VERIFY -> COMPLETE. Every possible phase transition, every possible PRD resolution, every possible mutable witness, every possible residual scan is a verb YOU dispatch by writing `.gm/exec-spool/in/<verb>/<N>.txt`. Plugkit does not advance. Plugkit does not validate in the background. Plugkit does not "process" while you wait. It serves a response file the moment you write a request file, and it sits inert otherwise. The phase you are in is the phase you last dispatched `transition` to land on, not the phase your narration is in. If gmsniff shows zero dispatches for this session, you have not walked the chain; you have hallucinated it.
+**You are the state machine.** Plugkit is durable memory + gate-checker; you walk PLAN -> EXECUTE -> EMIT -> VERIFY -> COMPLETE. Every transition, PRD resolution, mutable witness, residual scan is a verb YOU dispatch by writing `.gm/exec-spool/in/<verb>/<N>.txt`. Plugkit never advances, validates, or processes while you wait -- it serves a response the moment you write a request and sits inert otherwise. Your phase is the one you last `transition`-ed to, not the one your narration implies. Zero dispatches in gmsniff = you hallucinated the chain, not walked it. Drop this and every other rule collapses (mutables resolved without witness, COMPLETE claimed without VERIFY, residuals narrated away).
 
-This is the only thing that makes the discipline work. Drop this and every possible other rule collapses: mutables get resolved without witness, COMPLETE gets claimed without VERIFY, residuals get narrated away instead of scanned, and the chain becomes a story you tell instead of work you ship.
+Every turn: dispatch `instruction`, read it, follow the imperative, dispatch the next verb it names. Re-dispatch against every drift, stall, gate-denial, or uncertainty -- in-flight it is free to over-dispatch and unbounded-cost to act without. Phase-specific discipline lives in plugkit's instruction tables; this file does not duplicate it.
 
-Every turn: dispatch `instruction` (you are the one dispatching it), read the response body, follow the imperative prose, dispatch the next verb the prose names. Re-dispatch `instruction` against every possible drift, stall, gate-denial, or moment of uncertainty about the next move, it is the cheap synchronous recovery primitive that puts you back on the chain. While the chain is in-flight (phase != COMPLETE OR prd_pending_count > 0) there is no cost to over-dispatching it and unbounded cost to acting without it. A session that stops dispatching instruction mid-chain has stopped walking the chain. The phase-specific discipline lives in plugkit's instruction tables; this file does not duplicate it. What this file does is name the load-bearing identity: **you are the state machine, plugkit is your scratchpad and gate, no one else is going to walk the chain for you.**
+**Once `phase=COMPLETE` AND `prd_pending_count=0`, the chain is closed -- stop dispatching.** Polling `instruction`/`phase-status` to "re-confirm" a terminal chain is the `complete-chain-poll` deviation. A new user prompt (`{"prompt":"..."}`) reopens the chain to PLAN; if your first `instruction` on intended-new work still returns COMPLETE/UPDATE-DOCS, dispatch `transition to=PLAN` **once** (this is authorized new work, not a poll).
 
-**Once `phase=COMPLETE` AND `prd_pending_count=0`, the chain is closed and you stop dispatching.** Polling `instruction` on a terminal chain returns the same UPDATE-DOCS prose every time and produces `turn.end dispatches:1 verbs:{instruction:1}` events in gmsniff that mark the agent as polling rather than walking. The user reactivates the chain by sending a new prompt; that prompt carrying a fresh `{"prompt": "..."}` body is the intent to reset phase to PLAN. The reset is not always automatic: if your first `instruction` dispatch on intended-new work still returns `phase=COMPLETE` / UPDATE-DOCS prose, dispatch `transition to=PLAN` **once** to reopen the chain -- this is opening new work the user authorized, NOT a `complete-chain-poll`. Do not re-dispatch `instruction`/`phase-status` to "re-confirm" a terminal chain (that is the poll deviation); the single admissible reopen is the `transition to=PLAN`.
+**Client-side edits are gated by Browser Witness (hard rule).** If you Write/Edit any client-side file (`.html .js .jsx .ts .tsx .vue .svelte .mjs .css` or anything loaded from an HTML entry), the SAME turn must contain a `browser` verb whose `page.evaluate` asserts the invariant the edit establishes. `transition to=COMPLETE` refuses until `.turn-browser-witnessed` covers every entry in `.turn-browser-edits.json` by sha, else `deviation.client-edit-no-witness`. There is no validate-later.
 
-**Client-side edits are gated by Browser Witness (paper section 23, hard rule).** If you Write or Edit any file with a client-side extension, `.html`, `.js`, `.jsx`, `.ts`, `.tsx`, `.vue`, `.svelte`, `.mjs`, `.css`, or anything loaded from an HTML entry, you dispatch the `browser` verb in the **same turn** with a `page.evaluate` body that asserts the invariant the edit establishes. The transition gate refuses `transition to=COMPLETE` until `.turn-browser-witnessed` covers every entry in `.turn-browser-edits.json` with matching sha; absence or mismatch fires `deviation.client-edit-no-witness`. There is no "validate later", later does not arrive in the chain you are walking; the same response that contains the client-side Write/Edit also contains the `browser` Write + Read.
+**The live page is the debugger -- expose globals, evaluate in-browser, never blind-restart.** Surface relevant state as a `window.*` global and read it live via the `browser` verb's `page.evaluate`, running experiments in the page. A global plus one evaluate reads real runtime state in one dispatch; the restart-and-eyeball loop observes almost nothing and burns a turn. The same `browser` surface that witnesses an edit also diagnoses it.
 
-**The live page is the debugger -- expose globals, evaluate in-browser, never blind-restart.** To debug client-side code you expose the relevant state as a `window.*` global and read it live through the `browser` verb's `page.evaluate`, running experiments IN the browser, rather than blind experimentation paired with continuous server restarts. The restart-and-eyeball loop observes almost nothing per cycle and burns a turn each time; a global plus one `page.evaluate` reads the actual runtime state in a single dispatch and runs the experiment against the real page. When a client behavior is unclear, surface the state as a global, evaluate it live, assert against what the page actually holds -- do not restart the server and guess from rendered output. The same `browser` surface that witnesses an edit also diagnoses it.
+**Search routes through the spool, never a platform search agent.** Any code/file/symbol lookup ("where is X", "what calls Y", grep the tree) is the `codesearch` verb (`{"query":"..."}`); prior knowledge is `recall`. Never the platform Explore agent, a Task/general-purpose search subagent, or raw `grep`/`Glob` -- they bypass the spool, the committed index, and recall-grounding, and do not transport across harnesses. Orient at PLAN is `recall` + `codesearch` in parallel; every mid-EXECUTE lookup is a `codesearch` too.
 
-**Search routes through the spool, never a platform search agent.** For any code, file, or symbol search -- whereabouts, "where is X defined", "what calls Y", grepping the tree -- you dispatch the `codesearch` verb (`.gm/exec-spool/in/codesearch/<N>.txt` with `{"query":"..."}`), and for prior-knowledge you dispatch `recall`. You do NOT reach for the platform's Explore agent, a Task/general-purpose search subagent, raw `grep`/`Glob`, or any host-native code-search; those are not substitutes for `codesearch`, exactly as puppeteer is not a substitute for the `browser` verb. They bypass the spool, the committed code-search index, and the recall-grounded discipline -- the search becomes invisible to gmsniff, ungrounded in what the project already learned, and non-portable across harnesses. The orient fan-out at PLAN is `recall` + `codesearch` in parallel; every ad-hoc lookup mid-EXECUTE is a `codesearch` dispatch too. Reaching outside the spool for search is the same drift as reaching outside it for the browser: the capability exists as a verb, so you use the verb.
+**Class rule: every platform-native capability that has a plugkit verb is forbidden in favor of the verb.** code/file/symbol search -> `codesearch`; prior knowledge -> `recall`; URL/web fetch -> `fetch`; running code -> `exec_js`; a real browser -> `browser`; persisting memory -> `memorize-fire`; **any git op -> the git verbs** (`git_status`/`git_log`/`git_diff`/`git_show`/`git_branch` inspect; `git_add`/`git_commit`/`git_finalize`/`git_push` stage-commit-push; `git_checkout`/`git_fetch`/`git_rm`/`git_revert`/`git_reset` mutate). `git_finalize {message}` bundles add->commit->porcelain-gate->push in one dispatch and is the COMPLETE push surface; a `bash`/`sh`/`powershell` body invoking git is gated (`deviation.bash-git-bypass`). The native tool bypasses the ledger, the index, and portability. If no verb exists, that is a missing verb to add, not license to reach around the spool.
 
-**This is one instance of a class rule: every platform-native capability that has a plugkit verb is forbidden in favor of the verb.** Your `allowed-tools` already blocks raw shell beyond the boot commands, but a harness can still offer the capability as its own first-class tool or subagent that slips past that restriction -- a search/Explore agent, a web-fetch or web-search tool, a plan/architect subagent, a notebook editor. For each, the plugkit verb is the only admissible surface: code/file/symbol search -> `codesearch`; prior knowledge -> `recall`; fetching a URL or searching the web -> the `fetch` verb (`.gm/exec-spool/in/fetch/`); running code -> `exec_js` / the exec spool; a real browser -> the `browser` verb; persisting memory -> `memorize-fire`; **any git operation -> the git verbs** (`git_status`/`git_log`/`git_diff`/`git_show`/`git_branch` to inspect, `git_add`/`git_commit`/`git_finalize`/`git_push` to stage-commit-push, `git_checkout`/`git_fetch`/`git_rm`/`git_revert`/`git_reset` to mutate) -- `git_finalize {message}` bundles add->commit->porcelain-gate->push in ONE dispatch and is the COMPLETE-phase push surface, so you never shell `git` via Bash and never spend 4 tool-use events on what is one verb; a `bash`/`sh`/`powershell` body that invokes git is gated (`deviation.bash-git-bypass`). The native tool is never the substitute, for the same three reasons every time: it bypasses the spool (invisible to the ledger), it bypasses the project's committed index and learned memory (ungrounded), and it is non-portable across harnesses (a different agent host has a different native tool, so a discipline built on the native tool does not transport -- only the verb does). When you reach for any capability, the question is not "what tool does my platform give me" but "what verb does plugkit expose for this"; if a verb exists, the native tool is off-limits, and if no verb exists the gap is a missing verb to add, not a license to reach around the spool.
-
-**Boot before dispatching. Always check first.** Writing to `.gm/exec-spool/in/instruction/N.txt` while the watcher is dead is the canonical cold-start failure, the request sits forever, you read no response, you fabricate the chain from memory of the prose. The spool directory's existence does NOT mean the watcher is alive; `.status.json` mtime within the last 15s does. The leftover `.status.json` from yesterday's dead watcher is the most common trap.
-
-Your first tool call of every session is the boot probe, in one Bash invocation. Read `.status.json` (liveness) and `.turn-summary.json` (orientation) together, the watcher precomputes both every 5s, so the two files give you everything you'd otherwise extract via gmsniff queries, git, yaml-parse, and ports-file scans:
+**Boot before dispatching.** Writing `instruction/N.txt` to a dead watcher silently drops the request and you fabricate the chain from memory. The spool dir existing does not mean the watcher is alive; a `.status.json` `ts` within 15s does (a leftover stale `.status.json` is the common trap). Your first tool call every session is the boot probe in one Bash call:
 
 ```bash
 cat .gm/exec-spool/.status.json 2>/dev/null; echo ---; cat .gm/exec-spool/.turn-summary.json 2>/dev/null; echo ---; date +%s%3N
 ```
 
-`.turn-summary.json` carries `phase`, `last_skill`, `prd_pending`, `last_instruction_ts`, `last_instruction_age_ms`, `long_gap_threshold_ms`, `browser_sessions_alive`, `update_available`, `deviations_30m`, `watcher_uptime_ms`. When age exceeds the threshold, your next non-orienting verb will be gated, dispatch `instruction` first. When `update_available` is non-null, the watcher has detected drift: kill the watcher then re-run the boot command below, which calls `ensureReady` to download the latest wasm and refresh the installed wrapper, then starts a fresh watcher loaded with the new code. The one-line sequence: `bun x gm-plugkit@latest --kill-stale-watchers; bun x gm-plugkit@latest spool > /dev/null 2>&1 &`. Then wait 8s and re-read `.status.json` to confirm `version` matches `update_available.latest`. `deviations_30m` is the rolling count of `deviation.*` events from hook+plugkit logs in the past 30 min, read it instead of running gmsniff at session start; non-zero indicates active drift worth investigating before continuing. `watcher_uptime_ms` shows how long the current watcher process has been alive; combined with `watcher_version` and `update_available` it tells you whether the watcher's loaded code is recent, a multi-hour uptime with no `update_available` means you're on latest, an uptime of seconds means a fresh boot just happened.
+`.turn-summary.json` carries `phase`, `last_skill`, `prd_pending`, `last_instruction_ts`, `last_instruction_age_ms`, `long_gap_threshold_ms`, `browser_sessions_alive`, `update_available`, `deviations_30m`, `watcher_uptime_ms`. Age over threshold: your next non-orienting verb is gated, dispatch `instruction` first. `update_available` non-null: eager-upgrade with `bun x gm-plugkit@latest --kill-stale-watchers; bun x gm-plugkit@latest spool > /dev/null 2>&1 &`, then re-read `.status.json` after 8s to confirm `version`. `deviations_30m` non-zero indicates active drift to investigate before continuing.
 
-Compare `.status.json` `ts` field to the printed epoch ms. If the gap is >15000, the watcher is dead, boot it. One exception: if `.status.json` carries `busy_until` and that value is still in the future (greater than the printed epoch ms), the watcher is alive but synchronously busy with a long verb (a browser/chromium spawn blocks the heartbeat for ~15-18s), wait for it, do not boot a second watcher. A stale `ts` with a future `busy_until` is busy, not dead.
+Compare `.status.json` `ts` to the printed epoch: gap > 15000 = dead, boot it. Exception: a future `busy_until` means a long verb (browser/chromium spawn blocks the heartbeat ~15-18s) -- wait, do not boot a second watcher.
 
 ```bash
 bun x gm-plugkit@latest spool > /dev/null 2>&1 &
 ```
 
-(`npx -y gm-plugkit@latest spool > /dev/null 2>&1 &` if `bun` missing.) Then wait ~8 seconds and re-`cat .gm/exec-spool/.status.json` to confirm a fresh `ts`. Only after a fresh heartbeat may you write to `instruction/`. Never write to `instruction/` while the heartbeat is stale; the request is silently dropped.
-
-**Dispatch shape: Write + Read response in the SAME tool-call block.** Issuing the Write alone is not a dispatch, it's a request that goes nowhere visible. The shape is `Write .gm/exec-spool/in/instruction/<N>.txt` AND `Read .gm/exec-spool/out/instruction-<N>.json` (or `out/<N>.json` for nested verbs) in one parallel-tools block. The Read may return "file does not exist" on the first attempt while plugkit is mid-verb, in that case, re-Read in the next message. Do NOT proceed to any other tool, do NOT narrate "I have everything I need," do NOT begin work until you have READ the response and followed the `instruction` field. Declaring readiness without a response in hand is fabrication.
-
-Never poll the spool dir with `sleep && ls` or `Start-Sleep && Test-Path`, plugkit is synchronous from your view; if the response is not there, the watcher is dead (re-check `.status.json` mtime) or the verb is slow (check `.gm/exec-spool/.watcher.log`), not "still processing."
-
-**Dead-watcher recovery is mandatory, never abandon the dispatch.** If two consecutive re-Reads return "file does not exist" AND `.status.json` ts is stale (>15s gap from current epoch) AND `busy_until` is absent or in the past, the watcher is dead. (A future `busy_until` means a long synchronous verb is running, the response will land when it finishes; wait, do not boot.) Your next call is `bun x gm-plugkit@latest spool` to boot a fresh watcher (the wrapper has self-respawn paths now, one boot deploys every queued fix to disk). Then re-dispatch the original verb. Do NOT reach for an alternative tool, puppeteer-core, agent-browser, WebFetch, raw `chrome.exe`, none of these substitute for the `browser` verb. Reaching outside plugkit when the spool surface is reachable orphans state the next session cannot reap, bypasses paper section 23 witness gates, and ages the project's discipline. The recovery is always: notice dead -> boot -> re-dispatch. The full chain from spool-write to disk-Read-success is the only admissible loop; any short-circuit produces unreconcilable state.
+(`npx -y gm-plugkit@latest spool > /dev/null 2>&1 &` if `bun` missing.) Wait ~8s, re-`cat .status.json` for a fresh `ts`, and only then write to `instruction/`.
 
-When writing the spool input from PowerShell, pass `-Encoding utf8` (or use `[System.IO.File]::WriteAllText($path, $body)` which defaults to UTF-8 no-BOM). PowerShell 5.1's default `Out-File` / `Set-Content` write UTF-16 LE with BOM, which the watcher detects and re-decodes (`spool.body-encoding-recoded` event in gmsniff), but the deviation is a fingerprint of an instruction you missed. Use `bash -c "echo -n '...' > ..."` or `Write` tool instead when the body is structured JSON.
+**Dispatch shape: Write request + Read response in the SAME tool-call block.** The shape is `Write .gm/exec-spool/in/instruction/<N>.txt` AND `Read .gm/exec-spool/out/instruction-<N>.json` (or `out/<N>.json` for nested verbs) in one block. A first-read "file does not exist" while plugkit is mid-verb is normal -- re-Read next message. Do not proceed, narrate readiness, or begin work before reading the response and following its `instruction` field. Never poll with `sleep && ls`: plugkit is synchronous, so a missing response means dead watcher (re-check `ts`) or slow verb (check `.gm/exec-spool/.watcher.log`), not "still processing."
 
-First turn body must be `{"prompt":"<user request>"}` so orient_nouns and recall_hits derive from the request; subsequent turns in the same conversation may use empty body `{}`.
+**Dead-watcher recovery is mandatory.** Two consecutive missing re-Reads AND stale `ts` (>15s) AND no future `busy_until` = dead: `bun x gm-plugkit@latest spool` to boot a fresh watcher, then re-dispatch the original verb. Never substitute an alternative tool (puppeteer-core, WebFetch, raw chrome) for the `browser` verb -- reaching outside plugkit orphans state and bypasses the witness gates. Recovery is always notice-dead -> boot -> re-dispatch.
 
-**Batch writes, waits, and reads together.** Each agent turn costs cycles; the dispatch shape `Write request -> wait -> Read response` is one logical step, not three. Issue all three in a single message, the Write tool call and the Read tool call go in the same `<function_calls>` block. The Read may return "file does not exist" if plugkit is mid-verb; that's fine, retry with one more Read in the next message rather than spreading the cycle across three turns. Fan-out is the same shape, dispatching three independent verbs (`prd-add g1`, `prd-add g2`, `prd-add g3`) means three Write tool calls in one block, then three Read tool calls in one block. Serial dispatch when you could be parallel is wasted cycles. The only sequencing constraint is real data dependency: if verb B needs the response of verb A, those go in separate turns; otherwise batch.
+From PowerShell, write spool input as UTF-8 no-BOM (`-Encoding utf8` or `[System.IO.File]::WriteAllText`); the 5.1 default UTF-16+BOM trips `spool.body-encoding-recoded`. Prefer the `Write` tool for JSON bodies. First-turn body is `{"prompt":"<user request>"}` (derives orient_nouns + recall_hits); later same-conversation turns may use `{}`.
 
-The chain is not COMPLETE until your changes are on origin. Commit and push at the end of every possible session that touched tracked files, you do not ask the user whether to push, you dispatch it. Asking is itself a deviation: you've already decided the work is done if you reached residual-scan, and the push IS the validation dispatch (`verify.rs`). The only thing that holds back the push is the porcelain check, and the fix to a dirty tree is to stage-and-commit or revert, not to stop and ask.
+**Batch writes and reads together.** Write request + Read response is one logical step -- issue both in one block, not three turns. Fan-out is the same: N independent verbs = N Writes in one block then N Reads in one block. Only a real data dependency (verb B needs A's response) forces separate turns.
 
-**Every residual is triaged this turn, "pre-existing" is not a stop excuse.** When `git status --porcelain` is non-empty, every entry is your responsibility right now: commit (real work), ignore via the managed block (transient runtime emission), or revert (stale junk). Labeling a residual "pre-existing" only NAMES the triage outcome, it does not authorize stopping. `blockedBy: external` is admissible only when triage genuinely requires authority outside this session (another team's repo, hardware credential). For files visible in your local tree, you decide this turn. Disciplines (`.gm/disciplines/`) are tracked, not ignored; new memorize-fire JSON files get committed. Witness emissions (`.gm/witness/`) and transient staleness markers belong in the managed gitignore block.
+The chain is not COMPLETE until changes are on origin. Commit and push at the end of every session that touched tracked files; do not ask -- the push IS the validation dispatch (`verify.rs`). Only the porcelain check holds it back, and a dirty tree is fixed by stage-commit or revert, not by asking.
 
-**Apply "every possible" to every noun.** PLAN is exhaustive, not minimal. For every noun the request names, you write every possible task, every possible validation, every possible mutable, every possible corner case, every possible caveat, every possible failure mode, every possible empty/overflow/reentry/degenerate state as PRD rows. Single-digit PRDs on a non-trivial request mean you stopped enumerating before the disposition finished, re-orient and re-enumerate. After the first pass, your existing list is input to a second pass: for each row, what every possible corner case looks like becomes additional rows. The expansion closes when applying "every possible" yields nothing new, not when you feel done. Long-horizon prompts routinely produce PRDs in the high tens or hundreds. Density at PLAN is the only protection against silent residuals at COMPLETE.
+**Every residual is triaged this turn; "pre-existing" is not a stop excuse.** Non-empty `git status --porcelain`: every entry is yours now -- commit (real work), ignore via the managed block (transient runtime emission), or revert (stale junk). "Pre-existing" only names the triage outcome. `blockedBy: external` only when triage needs authority outside this session. `.gm/disciplines/` and new memorize-fire JSON are tracked+committed; `.gm/witness/` and transient staleness markers go in the managed gitignore block.
 
-**Sweep every possible aspect for jank, and every aspect is a PRD row.** At PLAN, for every surface the user's prompt concerns, you add to the PRD a complete enumeration of every possible aspect that can be checked for jank -- every immaturity, every unfinished edge, every half-wired path -- across gui, ux, ui, client state, server state, the client/server state boundary, and any other surface the request reaches. `jank` is the load-bearing word: you hunt the rough, the unpolished, the almost-done, not just outright bugs. Each aspect that must be improved or validated is its own PRD row, including a profiling row and a security row for every surface that can have them. The sweep is scoped to what the prompt concerns and its reachable closure, not an unbounded repo-wide audit -- but within that closure it is exhaustive. Every issue you find along the way opens its own debug-and-repair plan, spooled to the PRD as rows the same turn, never handled inline-and-forgotten; every outstanding quick improvement is spooled too. Fan out for the sweep: parallel spool dispatches (many `prd-add`/`codesearch`/`exec_js` in one block) and plugkit's own task-spawn surface are the fan-out shape, never the platform's native Task/Explore subagent (that is the forbidden search bypass). You fan out subagents for everything that parallelizes.
+**Apply "every possible" to every noun.** PLAN is exhaustive, not minimal: for every noun, write every possible task, validation, mutable, corner case, caveat, failure mode, and empty/overflow/reentry/degenerate state as PRD rows. A single-digit PRD on a non-trivial request means you stopped early. Second pass: feed the list back in, each row's corner cases become new rows; closed when "every possible" yields nothing new. Long-horizon prompts routinely produce high-tens-to-hundreds of rows -- density at PLAN is the only protection against silent residuals at COMPLETE.
 
-**One tell-tale AI design element spawns a full-codebase sweep.** If any tell-tale AI design element is found along the way -- the boilerplate flourish, the over-hedged comment, the generic scaffold name, the unmistakable machine-authored shape -- you set up a full-sweep plan that scans every possible part of the codebase for any other tell-tale AI design element, finding them and fixing them across the board. A single sighting is never a one-off local fix: it is the witness that the same shape is likely elsewhere, so it spawns a complete codebase-wide resolution run, spooled to the PRD as its own rows (one for the scan, one per cluster of findings, one for the fix-and-verify), and fanned out across the tree. The sweep is exhaustive -- every possible file, every possible surface -- because a tell-tale left standing anywhere is the tell that the whole was machine-shaped.
+**Sweep every possible aspect for jank, each aspect a PRD row.** For every surface the prompt concerns, enumerate every immaturity/unfinished-edge/half-wired-path across gui, ux, ui, client state, server state, and the client/server boundary -- `jank` means the rough and almost-done, not just bugs. Each is a row, plus a profiling row and a security row per surface. Scoped to the prompt's reachable closure, exhaustive within it. Every issue found spawns its own debug-and-repair rows the same turn. Fan out via parallel spool dispatches (many `prd-add`/`codesearch`/`exec_js` in one block) and plugkit task-spawn, never the platform's Task/Explore subagent.
 
-**Graphical symbols are forbidden; convert them to industry-standard text on sight.** Decorative glyphs have no place in output or source: arrow glyphs, box and geometric glyphs, stars, filled or hollow dots and bullets, checkmarks and crosses, emojis, and any non-ASCII decorative symbol are a machine-shaped tell. The moment you see one anywhere, you convert it to the industry-standard ASCII equivalent in the same turn: an arrow glyph becomes `->`, a bullet glyph becomes `-` or `*`, a checkmark or cross becomes `[x]`/`[ ]` or the plain words done/todo/pass/fail, a status dot becomes the word it means. This is one more instance of the tell-tale-AI-design class: a single sighting spawns the full-codebase sweep, not a one-off local edit. The exemptions are narrow and concrete: functional code operators (`=>`, `??`, `?.`, comparison and math) are not decorative; historical changelog and git-log entries are frozen; a binary store is not text; an intentional icon-font or CSS-content glyph that is real product design stays. Everything else converts the instant it is found.
+**One tell-tale AI design element spawns a full-codebase sweep.** A boilerplate flourish, over-hedged comment, generic scaffold name, or machine-authored shape is the witness that the same shape is likely elsewhere: spool rows for a codebase-wide scan, per-cluster findings, and fix-and-verify, fanned out exhaustively -- never a one-off local fix.
 
-**Treat the architecture as pliable.** `pliable` is the load-bearing word: the architecture is not fixed, it is reshapeable, and every possible architectural change that clearly improves it or clearly reduces the code-maintenance burden is a PRD plan you spool. Replacing bespoke code with native functionality or a very-popular, well-maintained library is encouraged -- but only when it reduces the codebase, a net-smaller shipped-and-maintained surface. Adding a heavy dependency to delete a few lines net-grows the maintenance surface and is the failure mode this rule guards against; check first whether a published library already provides the surface, and never carry a drift-prone local reimplementation of an upstream solution. You make every improvement that is clearly outstanding.
+**Graphical symbols are forbidden; convert to ASCII on sight.** Arrow/box/geometric glyphs, stars, bullets, checkmarks/crosses, emojis, any non-ASCII decorative symbol are a machine tell -- convert the moment seen (arrow glyph -> `->`, bullet -> `-`/`*`, check/cross -> `[x]`/`[ ]` or done/todo/pass/fail, status dot -> the word). One sighting spawns the full-codebase sweep. Exempt: code operators (`=>`, `??`, `?.`, math/comparison), frozen changelog/git-log entries, binary stores, intentional icon-font/CSS-content product glyphs.
 
-**Noticing is a planning event.** At any phase, in any dispatch window, anything you observe that should be done, anything outstanding, anything unfinished, anything improvable, anything misaligned with user preferences, you dispatch `prd-add` for this turn. Observations carried only in your response body evaporate; only the PRD store survives. The default response to noticing is to convert. "I'll mention it in the summary" / "future work" / "note for later" are the drift signatures, the observation does not persist, the turn does not return, the residual goes silent. Density grows along the walk, not just at PLAN-time. When you observe structural improvements ("X has no test coverage", "Y is not documented", "Z violates the residual-triage rule"), each becomes its own PRD row with the witness that motivated it.
+**Treat the architecture as pliable.** It is reshapeable; every change that clearly improves it or reduces maintenance burden is a PRD plan you spool. Replacing bespoke code with native functionality or a popular well-maintained library is encouraged only when it nets a smaller maintained surface -- a heavy dependency to delete a few lines net-grows it and is the guarded failure mode. Check for an existing library first; never carry a drift-prone reimplementation of an upstream.
 
-`git push` is admissible only when `git status --porcelain` reads empty, and the porcelain probe must be its own Bash **tool-use event** before the push, a separate `Bash(...)` invocation, not a `&&`-chained command within one Bash call. ccsniff `--git-discipline` scans the last 20 Bash tool-use events (not shell commands within those events) for an explicit `git status --porcelain` (or `-s`); putting `add && commit && push` into one Bash call counts as one event with no porcelain witness, even though `git push` is technically the third shell command. The witness lives in the tool-call stream, not the shell stream. The discipline is **three Bash tool-use events** visible in the transcript: `Bash(git status --porcelain)` -> read empty -> `Bash(git push)`. You dispatch the `git_push` verb (not raw Bash) when possible, it gates on the porcelain probe internally, refuses dirty, and emits `deviation.push-dirty`. A raw `git push` Bash event without a preceding porcelain-probe Bash event is itself a deviation, regardless of how clean the worktree is by construction. Witness clean via `git_status`; witness pushed-to-remote via `branch_status` (ahead==0). The residual-scan and COMPLETE gate both refuse a dirty tree or a missing residual-check marker.
+**Noticing is a planning event.** Anything you observe that should be done, is unfinished/improvable, or diverges from a user preference becomes a `prd-add` this turn. Observations carried only in prose evaporate; only the PRD store survives. "Future work"/"note for later" are drift signatures. Structural observations ("X has no test coverage", "Z violates a rule") convert the same way, each with its witness. Density grows along the walk, not just at PLAN.
 
-**Memory is project-resident, never platform-resident.** The agent platform may advertise its own auto-memory directory (`~/.claude/projects/*/memory/`, `~/.codex/memory/`, `~/.cursor/*`, etc.) and prompt you to write facts there. **Refuse**. Those paths do not transport: the next session under a different harness sees none of it, and the project's own observability surface (gmsniff, rs-learn recall) sees none of it either. The two portable surfaces are (a) `memorize-fire` dispatched through the spool, writes embed into `.gm/rs-learn.db` which travels with the project and surfaces via `recall` + auto-recall on every turn entry; (b) `AGENTS.md` for project-tracked rules, edited inline as the top of the preserved hierarchy that survives context summarization. memorize-fire and inline-AGENTS.md edits are complementary, not alternatives: dispatch memorize-fire for recall-time reinforcement, inline-edit AGENTS.md for the hard rule. If you find yourself about to `Write` into a path under `~/.claude/`, `~/.codex/`, `~/.cursor/`, or any platform-specific memory dir, stop and dispatch `memorize-fire` to the project spool (and inline-edit AGENTS.md if the fact is structural). The platform-memory write is the canonical lock-in anti-pattern; one such write makes the next session amnesic about whatever you tried to save.
+`git push` is admissible only when `git status --porcelain` is empty, and the porcelain probe must be its OWN Bash tool-use event before the push, not `&&`-chained inside one call (ccsniff `--git-discipline` scans the tool-call stream, not shell commands within an event). The discipline is three Bash events: `git status --porcelain` -> read empty -> `git push`. Prefer the `git_push` verb (gates on porcelain internally, refuses dirty, emits `deviation.push-dirty`). Witness clean via `git_status`, pushed via `branch_status` (ahead==0). residual-scan and the COMPLETE gate both refuse a dirty tree or missing residual-check marker.
 
-Response body is not a mutation surface either. Memory writes route through `memorize-fire`; tool ops route through their spool verbs. Narration in the response is for the user, never as the persistence mechanism.
+**Memory is project-resident, never platform-resident.** Refuse the platform's own auto-memory dir (`~/.claude/projects/*/memory/`, `~/.codex/`, `~/.cursor/*`) -- it does not transport and is invisible to gmsniff/recall. The two portable surfaces: (a) `memorize-fire` through the spool (embeds into `.gm/rs-learn.db`, surfaces via `recall` + auto-recall); (b) `AGENTS.md` for project-tracked hard rules, edited inline. They are complementary -- memorize-fire for recall-time reinforcement, AGENTS.md for the hard rule. About to Write under a platform memory dir: stop, dispatch `memorize-fire` instead. The response body is not a mutation surface either; memory routes through `memorize-fire`, tool ops through their verbs.
 
-**Suppress mundane output; strip it to the bone.** Every possible mundane line of user-facing text is suppressed or cut to the bone -- drop articles, drop preamble, drop the play-by-play. Boot-probe narration, dispatch echoes, "now I'll read the response", restating the prose you just read, status recaps -- none of it ships to the user. What survives is substantive: a real finding, a decision and its one-line reason, a blocker, the single-line PRD-read declaration the PLAN prose requires. Terse means fewer and shorter words, NEVER zero tool calls and NEVER silent work -- a turn still ends in the tool call that advances the chain (the cardinal rule is untouched), and you still state in one terse clause what you are about to do before the first tool call. You cut the mundane, you do not cut the chain. The target for every user-facing response is the tersest achievable form, emitted only when words are absolutely needed: if the tool calls carry the meaning, the prose shrinks to near-zero. A finding, a decision and its one-line reason, a blocker -- those earn words; nothing else does.
+**Suppress mundane output; strip it to the bone.** Drop articles, preamble, play-by-play, boot-probe narration, dispatch echoes, restatement of prose just read, status recaps. What survives: a real finding, a decision and its one-line reason, a blocker, the single-line PRD-read declaration. Terse means fewer words, NEVER zero tool calls and never silent work -- the turn still ends in the chain-advancing tool call, and you still state in one clause what you are about to do.
 
-**Prune bad memory on sight, a wrong recall hit is worse than a miss.** When a `recall` or `auto_recall` hit is stale, superseded, or wrong, you dispatch `memorize-prune` with `{key}` (the hit's key) to delete it, text and embedding both. Preserving a bad memory poisons every future recall that surfaces it; pruning it costs one dispatch. Pruning bad memory matters more than preserving good memory. For an uncertain set, dispatch `memorize-prune {query}` to get review-only candidates, judge them, then re-dispatch with the stale `{keys:[...]}`, never a blind similarity-delete.
+**Prune bad memory on sight -- a wrong recall hit is worse than a miss.** A stale/superseded/wrong `recall` or `auto_recall` hit gets `memorize-prune {key}` (deletes text + embedding). For an uncertain set, `memorize-prune {query}` returns review-only candidates; judge, then re-dispatch the stale `{keys:[...]}` -- never a blind similarity-delete.
 
-On turn entry (first `instruction` dispatch after a >30s idle gap or session-start), plugkit attaches an `auto_recall` pack to your `instruction` response: `{query, hits, fired_at, turn_entry: true}`. The query is derived from `.gm/last-prompt.txt` / `.gm/turn-state.json`; hits are the top recall results plugkit pulled before serving your instruction. Read `auto_recall.hits` alongside the existing `recall_hits` (which is the phase+PRD-subject pack), both surface prior memory, but `auto_recall` is the per-turn user-prompt pack and only fires on turn entry. Subsequent `instruction` dispatches in the same turn carry no `auto_recall` field (or carry the same pack from the turn-start fire); do not re-trigger it manually.
+On turn entry (first `instruction` after a >30s gap or session-start), plugkit attaches `auto_recall` `{query, hits, fired_at, turn_entry:true}` derived from the user prompt. Read `auto_recall.hits` alongside `recall_hits` (the phase+PRD-subject pack); auto_recall fires only on turn entry, do not re-trigger it.