gm-cc 2.0.520 → 2.0.521

package/.claude-plugin/marketplace.json

@@ -4,7 +4,7 @@
     "name": "AnEntrypoint"
   },
   "description": "State machine agent with hooks, skills, and automated git enforcement",
-  "version": "2.0.520",
+  "version": "2.0.521",
   "metadata": {
     "description": "State machine agent with hooks, skills, and automated git enforcement"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-cc",
-  "version": "2.0.520",
+  "version": "2.0.521",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.520",
+  "version": "2.0.521",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": {
     "name": "AnEntrypoint",

package/skills/gm/SKILL.md

@@ -9,6 +9,33 @@ description: Agent (not skill) - immutable programming state machine. Always inv
 
 **CRITICAL: Skills are invoked via the Skill tool ONLY. Do NOT use the Agent tool to load skills.**
 
+## WHERE YOU ARE
+
+Top of state machine. No mutables resolved, no files read, no phase protocols loaded. Each phase (PLAN, EXECUTE, EMIT, VERIFY, UPDATE-DOCS) carries its own protocols (mutable discipline, pre-emit diagnostic, post-emit verify, hygiene sweep, CI watch). Protocols enter context only when you invoke the corresponding Skill. Reading a summary ≠ being in them.
+
+Transitions = state changes, not reminders. Phase exit condition met → next Skill invocation moves you. Without invocation: still in prior state, regardless of prose.
+
+`gm-execute` = execution contract. Defines "running code" across every phase: `exec:<lang>` = only runner; `exec:codesearch` = only exploration; witnessed output = only ground truth; import real modules over reimplementation. Execution happens in every phase, not only EXECUTE. About to run anything, `gm-execute` protocols not fresh in context → operating outside contract → reload `gm-execute` first.
+
+## FRAGILE LEARNINGS
+
+Every fact resolved this session lives only in current context. Context compacts. Sessions end. Next agent starts blind. `memorize` subagent = handoff. One background call per fact at moment of resolution. Non-blocking; work continues. Worth memorizing: API shapes, environment quirks, timeouts, user preferences, build cadences, CI behaviors — facts that would have saved today's time if in memory at start.
+
+Resolve a mutable, skip memorize = forget on purpose.
+
+## USER DONE TALKING
+
+User gave task. User waiting. Not co-pilot — person whose time you conserve by running chain end-to-end. Mid-chain questions ("should I proceed?", "which approach?", "look right before continue?") = chain breaks. Every break forces user back into loop they offloaded.
+
+Unknown resolution order — fixed:
+1. **Code execution** — witnessed run (`exec:<lang>`, `exec:codesearch`, import real module). Covers 90%+ of mutables.
+2. **Web** — `WebFetch` / `WebSearch` for API docs, spec PDFs, library versions, framework conventions. Covers environment facts not in this codebase.
+3. **User** — only after code and web exhausted. Only for genuinely ambiguous scope that makes planning impossible, or destructive-irreversible decisions (force-push, drop prod table, publish). Not for preferences resolvable from existing code conventions.
+
+An unknown that could fall to step 1 or 2 is not a clarifying question — it is a missed run. "Want me to..." or "Should I..." mid-chain = invoke next skill instead.
+
+Clarification allowed at top of chain (before first `planning`) when scope is genuinely unreadable. After chain starts: policy carries it.
+
 All work coordination, planning, execution, and verification happens through the skill tree starting with `planning`:
 - `planning` skill → `gm-execute` skill → `gm-emit` skill → `gm-complete` skill → `update-docs` skill
 - `memorize` sub-agent — background only, non-sequential. `Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<what was learned>')`

package/skills/gm-complete/SKILL.md

@@ -10,6 +10,27 @@ You are in the **VERIFY → COMPLETE** phase. Files are written. Prove the whole
 **GRAPH POSITION**: `PLAN → EXECUTE → EMIT → [VERIFY] → UPDATE-DOCS → COMPLETE`
 - **Entry**: All EMIT gates passed. Entered from `gm-emit`.
 
+## WHERE YOU ARE
+
+Files written. Question now: does the whole system work end-to-end, and does the world outside local repo (CI, downstream pipelines, deployed surfaces) agree. Every check = witnessed execution: `node test.js`, `gh run watch`, diagnostic repros on failure. Contract in `gm-execute`; protocols not fresh → verification drifts to narrated claims ("change should work") over witnessed ones ("change produced output X"). Load first.
+
+## VERIFICATION → UNKNOWNS
+
+Failing test, red CI, surprising downstream cascade ≠ things to patch around. = new fault surfaces becoming visible. Classify failure:
+- Wrong file output → regress to EMIT
+- Wrong logic → regress to EXECUTE
+- Genuinely new unknown or wrong requirement → regress to PLANNING
+
+Let chain carry you. Stop-and-fix-here = how silent-failure bugs reach prod. Machine assumes you regress; trust it.
+
+## FRAGILE LEARNINGS
+
+Phase where environment reality hits hardest — CI runner quirks, flaky-test patterns, timing thresholds, deploy cadences, cross-repo cascade behaviors. These facts most reward future sessions. Each → memorize call, one per fact, non-blocking, at moment of resolution:
+
+```
+Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')
+```
+
 ## TRANSITIONS
 
 **EXIT — .gm/prd.yml items remain**: Verified items completed, .gm/prd.yml still has pending items → invoke `gm-execute` skill immediately (next wave). Do not stop.
@@ -156,7 +177,7 @@ Before declaring complete, sweep the entire codebase for violations:
 9. **TODO.md** → must be empty/deleted before completion
 10. **CHANGELOG.md** → must have entries for this session's changes
 11. **Observability gaps** → every server subsystem added this session exposes a `/debug/<subsystem>` endpoint; every client module added this session registers into `window.__debug` by key. Ad-hoc console.log is not observability — permanent queryable structures are. Any gap found → fix before advancing.
-12. **memorize** → launch memorize sub-agent in background with session learnings before invoking update-docs: `Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<session learnings>')`
+12. **memorize** → every fact surfaced during verification that would have saved this session's time if it had been in memory at the start (CI timing, flaky-test patterns, environment quirks, runtime behaviors, user preferences stated this session) is handed off via a background memorize call at the moment of resolution. One call per fact, non-blocking. `Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')`
 13. **Deploy/publish** → if deployable, deploy. If npm package, publish.
 14. **GitHub Pages** → check if repo has a GH Pages site. If `.github/workflows/pages.yml` is absent OR `docs/index.html` is absent: invoke the `pages` skill to scaffold the site before advancing.
 

package/skills/gm-emit/SKILL.md

@@ -10,6 +10,32 @@ You are in the **EMIT** phase. Every mutable is KNOWN. Prove the write is correc
 **GRAPH POSITION**: `PLAN → EXECUTE → [EMIT] → VERIFY → COMPLETE`
 - **Entry**: All .gm/prd.yml mutables resolved. Entered from `gm-execute` or via snake from VERIFY.
 
+## WHERE YOU ARE
+
+About to mutate on-disk state. Every write bracketed by two witnessed executions: pre-emit (import module from disk, run proposed logic in isolation, record expected outputs as baseline) and post-emit (re-import from disk, confirm identical output to pre-emit baseline). Both = executions. Contract in `gm-execute`. Protocols not fresh → runs drift to reimplementation + narrated assumption → write ships unfalsified. Load first.
+
+## SURPRISE → STATE REGRESSION
+
+Pre-emit unexpected output ≠ bug to patch in this phase. Classify:
+- Identifiable logic error against a known mutable → regress to `gm-execute` (re-resolve the mutable properly, return here)
+- Newly visible unknown (cause not nameable) → regress to `planning` (enumerate, let chain return you with complete mutable map)
+
+Post-emit divergence from pre-emit baseline:
+- Identified cause → known mutable → fix in place, re-verify (EMIT self-loop, zero variance before advancing)
+- Unidentified cause → unknown → regress to `planning`
+
+Urge to "just fix real quick" = signal mutable map was incomplete. Trust state machine: regress to correct phase, resolve, return.
+
+## FRAGILE LEARNINGS
+
+Pre-emit and post-emit runs surface facts you lacked: actual function signatures, edge-case return values, adjacent-module interactions, hidden invariants. Each dies on context compaction unless handed off.
+
+```
+Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact witnessed this phase>')
+```
+
+One call per fact, non-blocking, at moment of resolution.
+
 ## TRANSITIONS
 
 **EXIT — invoke `gm-complete` skill immediately when**: All gate conditions are true simultaneously. Do not pause. Invoke the skill.
@@ -87,7 +113,7 @@ The post-emit verification is a differential diagnosis against the pre-emit base
 - No unnecessary files — clean anything not required for the program to function
 - Observability: every new server subsystem exposes a named inspection endpoint; every new client module registers into `window.__debug` by key and deregisters on unmount. Ad-hoc `console.log` is not observability — permanent queryable structure is. Any new code path not reachable via `window.__debug` or a `/debug/<subsystem>` endpoint → do NOT advance, add observability before writing feature code.
 - Structural quality: if/else chains where a dispatch table or pipeline suffices → regress to `gm-execute` for restructuring. One-liners that compress logic at the cost of readability → expand. Any logic that reinvents a native API or library → replace with the native/library call. Structure must make wrong states unrepresentable — if it doesn't, it's not done.
-- memorize sub-agent launched in background before advancing: `Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<what was learned>')`
+- every fact resolved in this phase (pre-emit discoveries, post-emit surprises, newly-confirmed behaviors) has been handed off via a background memorize call at the moment of resolution: `Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<what was learned>')`
 - CHANGELOG.md updated with changes
 - TODO.md cleared or deleted
 

package/skills/gm-execute/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: gm-execute
-description: EXECUTE phase. Resolve all mutables via witnessed execution. Any new unknown triggers immediate snake back to planning — restart chain from PLAN.
+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 — Resolving Every Unknown
 
-You are in the **EXECUTE** phase. Resolve every named mutable via witnessed execution. Any new unknown = stop, snake to `planning`, restart chain.
+You are in the **EXECUTE** phase. Every mutable on `.gm/prd.yml` carries UNKNOWN status until witnessed execution resolves it. Job here = the witnessing.
+
+This skill also carries the **execution contract** applying in every phase, not only this one. Planning runs codebase scans; EMIT runs pre-emit diagnostics; VERIFY runs integration tests and CI watches — all executions, all subject to discipline below. Other skills reference this skill because protocols stay live in context only while this text is nearby. About to run anything → this skill freshly loaded OR operating outside contract.
+
+New unknown surfaced by a run → stop, state-regress to `planning`, restart chain.
 
 **GRAPH POSITION**: `PLAN → [EXECUTE] → EMIT → VERIFY → COMPLETE`
 - **Entry**: .prd exists with all unknowns named. Entered from `planning` or via snake from EMIT/VERIFY.
@@ -134,13 +138,17 @@ Real services, real data, real timing. Mocks/fakes/stubs/simulations = diagnosti
 
 **CODE QUALITY PROCESS**: The goal is minimal code / maximal DX. When writing or reviewing any block of code, run this mental process: (1) What native language/platform feature already does this? Use it. (2) What library already solves this pattern? Use it. (3) Can this branch/loop be a data structure — a map, array, or pipeline — where the structure itself enforces correctness? Make it so. (4) Would a newcomer read this top-to-bottom and immediately understand what it does without running it? If no, restructure. One-liners that compress logic are the opposite of DX — clarity comes from structure, not brevity. Dispatch tables, pipeline chains, and native APIs eliminate entire categories of bugs by making wrong states unrepresentable.
 
-## MEMORY
+## FRAGILE LEARNINGS
+
+Every UNKNOWN→KNOWN transition = fact living only in current context. Session ends. Next agent starts blind. `memorize` subagent = only bridge. One background call per fact at moment of resolution:
 
-When any mutable resolves from UNKNOWN to KNOWN (zero variance confirmed), launch memorize subagent in background — non-blocking, execution continues:
+```
+Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<resolved fact>')
+```
 
-`Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<resolved fact>')`
+Non-blocking; work continues. Highest-value facts = ones that would have saved today's time if in memory at start: API shapes resolved by import-and-witness, environment quirks, runtime constraints, user-stated preferences, project-specific cadences. Resolve a mutable, skip memorize = forget on purpose.
 
-Qualifies for memorization: new API shapes discovered, environment differences, behavioral constraints, runtime quirks, user feedback observed during execution.
+Self-check: after any witnessed run that resolved something, next action = another witnessing run (more mutables) OR `Agent` memorize call (fact was memorable). Neither = something evaporated.
 
 ## DO NOT STOP
 

package/skills/planning/SKILL.md

@@ -10,6 +10,26 @@ Root of all work. Runs `PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS →
 
 **Entry**: prompt-submit hook → `gm` agent → invoke `planning` skill (here). Also re-entered any time a new unknown surfaces in any phase.
 
+## WHERE YOU ARE
+
+Phase where work shape still unknown. Codebase scans, `exec:codesearch` queries, quick imports to probe APIs = all executions. Execution contract in `gm-execute`; protocols not fresh → runs drift (reimplement over import, narrate over witness). Load first.
+
+## UNKNOWNS = PRODUCT
+
+Output of this phase ≠ task list. Output = enumeration of every fault surface work could fail on. Each unknown named + resolved → cheaper downstream. Each unknown skipped → EMIT/VERIFY surprise → snake back anyway at higher cost.
+
+**Unknown emerges later (EXECUTE, EMIT, VERIFY) → return here. Not failure — machine working as designed.** Later-phase unknown means mutable map incomplete. Come back. Think laterally — what else could this touch, what invariant assumed, what subsystem unexamined? Enumerate newly-visible fault surfaces. Only then push forward.
+
+Patch-around-unknowns-in-place = compounding silent-failure debt. Regress early = stay inside contract.
+
+## FRAGILE LEARNINGS
+
+Every mutable resolved here (existingImpl absent, dep version confirmed, user constraint stated, build quirk observed) = fact that dies on context compaction unless handed off. `memorize` subagent = handoff. One background call per fact at moment of resolution. Non-blocking; continue.
+
+```
+Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<single resolved fact>')
+```
+
 ## STATE MACHINE
 
 **FORWARD**: PLAN complete → `gm-execute` | EXECUTE complete → `gm-emit` | EMIT complete → `gm-complete` | VERIFY .prd remains → `gm-execute` | VERIFY .prd empty+pushed → `update-docs`