gm-skill 2.0.1303 → 2.0.1319

package/AGENTS.md

@@ -1 +1,172 @@
-# gm-skill
+# AGENTS.md
+
+--JULES STOPGAP DONT EDIT START--
+
+## Skills
+
+This project has task-specific skills available.
+
+> **MANDATORY:** Before writing any code, creating any file, or running any command,
+> you **MUST** first read `SKILLS.md` and check for relevant skills.
+> This step is **non-negotiable** and applies to **every task** without exception.
+
+**Steps to follow before any task:**
+1. `view SKILLS.md` — discover all available skills
+2. `view` every skill file that is plausibly relevant to the task
+3. Only then proceed with the task
+
+Skipping this step is not allowed, even if you believe you already know how to do the task.
+Skills encode environment-specific constraints that override general knowledge.
+
+--JULES STOPGAP DONT EDIT STOP--
+
+# Architecture & Philosophy
+
+This repo IS the published `gm-skill` npm package. The repo root is the package root — no factory, no build step that generates a separate output dir. `skills/gm-skill/SKILL.md` is the ~12-line entry point; all phase prose and orchestration logic live in rs-plugkit and are served on demand via the `instruction` verb.
+
+## WASM-only
+
+The plugkit stack runs as a wasm cdylib loaded by `plugkit-wasm-wrapper.js` under Node/bun. No native binaries are built, downloaded, or published. The wasm artifact is small (<200KB) and ships inside the `gm-skill` npm package; atomic write to disk is sufficient — no kill-before-rename mechanics apply.
+
+## Spool dispatch ABI
+
+Agents dispatch verbs by writing to `.gm/exec-spool/in/<verb>/<N>.txt` (request body) and reading the response from `.gm/exec-spool/out/<verb>-<N>.json` (nested verbs) or `.gm/exec-spool/out/<N>.json` (root verbs). The wasm orchestrator services every verb; the harness never executes side effects directly.
+
+**Orchestrator verbs**: `instruction`, `transition`, `phase-status`, `mutable-resolve`, `memorize-fire`, `residual-scan`, `auto-recall`.
+
+**Wasm-direct verbs**: `fs_read`, `fs_write`, `fs_stat`, `fs_readdir`, `kv_get`, `kv_put`, `kv_query`, `fetch`, `exec_js`, `env_get`, `recall`, `codesearch`, `memorize`, `health`, `filter`, `git_status`, `branch_status`, `git_push`.
+
+**git verbs**: `git_status` returns `{dirty, modified, untracked, deleted, staged}` from `git status --porcelain`. `branch_status` returns `{branch, ahead, behind, remote}` — the `remote-pushed` witness. `git_push` is the ONLY admissible push surface — it gates on `git_porcelain()` non-empty (refuses dirty), emits `deviation.push-dirty` on attempt, and shells the push only when clean. A raw `git push` via Bash bypasses the gate and is itself a deviation; ccsniff `--git-discipline` flags it.
+
+**filter verb**: pure stdout → compact-stdout transformation. Body `{kind, input, ...opts}` where kind is one of `grep`, `ls`, `tree`, `json`, `diff`, `git-status`, `log`. Returns `{output, stats:{bytes_in, bytes_out, saved_pct, ...}}`. Pipe raw command output through filter before letting it enter context — rtk's role, in-wasm, no subprocess. Replaces the legacy detached rtk binary download in bootstrap.
+
+## Documentation Policy
+
+Only record non-obvious technical caveats that cost multiple runs to discover. Remove anything that no longer applies. Never document what is already obvious from reading the code.
+
+**No changelog history in AGENTS.md.** Every entry is a present-tense rule about what must or must-not be the case in code now. Forbidden: `(FIXED)` markers, commit hashes, dated audit entries, `## Learning audit` sections, "(added 2026-04-DD)" annotations, "we used to X, now we Y" phrasing. Historical framing belongs in `git log` and `CHANGELOG.md`.
+
+**Detail-heavy caveats live in rs-learn (`.gm/rs-learn.db`), not here.** Per-crate runtime quirks, Windows process-spawn mechanics, hook implementation details, ocw/site/workflow specifics, and similar fact-base material are exfiltrated to rs-learn and reachable via `exec:recall`. AGENTS.md keeps only top-level rules that govern gm-the-repo. When in doubt: gm-the-repo architecture or cross-cutting policy stays here; single-crate or single-platform mechanism goes to rs-learn.
+
+## Coding Style
+
+**No comments in code.** No inline, block, or JSDoc comments anywhere — source, generated output, hooks, scripts.
+
+**Skill SKILL.md files:** Strip explanatory prose. Keep ONLY invocation syntax, transition arrows, gate conditions, constraint lists, and code examples showing exact usage.
+
+**Implicit, not explicit, in skill prose.** Skill files (and prompt-submit.txt) elicit behavior — they do not describe it. Write terse imperative principles whose phrasing triggers the model's already-learned dispositions, not numbered procedures that spell out what to do. Forbidden: "1. agent runs N parallel calls 2. then writes 3. then…", "see paper IV §2.3", "as documented in docs/skills.html", citations to the site or papers, multi-step recipes. The skill is a prompt, not a manual; if it reads like a manual the behavior gets imitated as a script and breaks at the first edge case. The papers and site are *outputs* of the discipline, not *inputs* to it; never link from a skill into the docs. Cross-cutting rules that need a citation belong in this file (AGENTS.md), not in skills.
+
+## Build
+
+There is no build step. The repo root is the published artifact. `npm publish` from root publishes `gm-skill` directly; `package.json` `files:` pins which paths ship.
+
+`AnEntrypoint/gm-skill` is a back-compat repo mirror that receives only `skills/gm-skill/SKILL.md` per release. The canonical install is `bun x skills add AnEntrypoint/gm`.
+
+## the agent is the orchestrator; plugkit is the brain it drives
+
+**The agent orchestrates.** Plugkit is the stateful library the agent drives by dispatching verbs. Plugkit does not act autonomously, does not advance phases in the background, does not validate transitions while the agent waits. Every state change is a verb the agent writes into `.gm/exec-spool/in/<verb>/<N>.txt`. If a session shows zero dispatches but the agent narrated a full PLAN→COMPLETE walk, the agent fabricated the walk — plugkit's dispatch ledger is ground truth.
+
+The PLAN → EXECUTE → EMIT → VERIFY → COMPLETE state machine lives natively in rs-plugkit at `rs-plugkit/src/orchestrator/{mod,state,transitions,mutables,memorize}.rs`. Plugkit owns phase tracking, mutables resolution, memorize firing, and transition legality *as data structures and gate checks* — but the agent triggers every operation by dispatching one of the orchestrator verbs over the wasm surface (see Spool dispatch ABI above): `transition`, `mutable-resolve`, `memorize-fire`, `phase-status`, `instruction`, `residual-scan`, `auto-recall`. The gm-skill harness routes the agent's verb writes to plugkit; the harness never reimplements the state machine and the agent never expects plugkit to act without a verb. Polling the spool output dir (`sleep && ls`, `Start-Sleep && Test-Path`) instead of reading the response file is the canonical misuse — plugkit is synchronous from the agent's view.
+
+## gm-skill is the canonical universal harness
+
+`skills/gm-skill/SKILL.md` is the single source of truth for harness behavior. It is the only skill shipped — the legacy 15-platform fanout (gm-cc, gm-gc, gm-oc, gm-codex, gm-kilo, gm-qwen, gm-hermes, gm-thebird, gm-vscode, gm-cursor, gm-zed, gm-jetbrains, gm-copilot-cli, gm-antigravity, gm-windsurf) is retired; those downstream repos are archived. Users install gm-skill directly into whatever harness they use.
+
+## Tool surface is plugkit-only
+
+Every skill's `allowed-tools:` frontmatter is reduced to `Skill, Read, Write`. `Write` is permitted exclusively for spool dispatch (writing into `.gm/exec-spool/in/<lang>/`). All other side effects — code execution, git, browser, recall, memorize, codesearch — route through the spool and are serviced by plugkit. The harness never reaches around plugkit; if a capability is missing, add it as a plugkit verb, not as a skill-side tool.
+
+## Core Rules
+
+**Shared memory & search index are tracked, never ignored**: `.gm/rs-learn.db` and `.gm/code-search/` are committed so memory and index state shares across machines, sessions, and CI. Tooling, scripts, and any agent editing `.gitignore` must NEVER add `.gm/`, `.gm/rs-learn.db`, `.gm/code-search/`, or legacy `.code-search/` to ignore rules. Per the gitignore parent-re-include caveat (re-including a path past an ignored parent dir is impossible), individual `.gm/*` entries (prd-state.json, lastskill, turn-state.json, trajectory-drafts/, ingest-drafts/, rslearn-counter.json) are listed one-by-one between `# >>> gm managed` markers, leaving `.gm/rs-learn.db` and `.gm/code-search/` un-ignored. Same rule for downstream repos: `lib/template-builder.js::generateGitignore()` must not emit any of those paths. Any project-local persistent state (chunk index, DB, embeddings) must write under `.gm/<name>/`, never to a top-level dotfile/dotdir.
+
+**Disciplines are isolated knowledge stores**: per-project, at `<project>/.gm/disciplines/<name>/{rs-learn.db, code-search/}`. Each discipline owns its own rs-learn DB and code-search index. When a `@<name>` sigil is present in the request, isolation is strict — cross-discipline reads are forbidden. Without a sigil, reads (recall/codesearch) fan across `default` plus every enabled discipline (one per line in `<project>/.gm/disciplines/enabled.txt`) and merge-rank results with `[discipline:<name>]` prefixes; writes (memorize/ingest/index) without a sigil go to `default` only. Disciplines are tracked in git, never ignored — `lib/template-builder.js::generateGitignore()` and the gm-managed gitignore markers in downstream repos must not list `.gm/disciplines` or any subpath. The gm-skill harness and every spool verb propagate the `@<name>` sigil verbatim through their dispatch chain.
+
+**Clean build required**: `cleanBuildDir()` must delete the entire output dir before regenerating. Skipping causes stale files to silently shadow new ones.
+
+**Nothing fake in source the user runs**: stubs, mocks, placeholder returns, fixture-only paths, demo-mode short-circuits, and "TODO: implement" bodies are forbidden in shipped code. Scaffolds and shims are permitted only when they delegate to real behavior (real upstream API, real subprocess, real disk). Before adding a shim, check whether a published library or tool already provides that surface — maintaining a local reimplementation of an upstream solution drifts and ages. Detection is behavioral, not by keyword: code that always succeeds, returns the same value regardless of input, or short-circuits a real call to satisfy a type signature is a stub. Acceptance is real input through real code into real output, witnessed; anything less leaves the mutable open.
+
+**Spool dispatch gates**: `lib/spool-dispatch.js` implements marker-file gate logic that controls tool use, writes, and git operations. `checkDispatchGates(sessionId, operation)` reads marker files (`.gm/prd.yml`, `.gm/mutables.yml`, `.gm/needs-gm`, `.gm/gm-fired-<id>`) and returns `{allowed: bool, reason: string}`. Gates are checked at the CLI/bootstrap layer before tools execute. Tool denials via gate checks report the reason text to the model so it can adjust behavior (e.g., resolve mutables before retrying). Gate denials never mutate command arguments — they surface policy as imperative instruction via reason string.
+
+**Done is plugkit's pronouncement, never the agent's claim**: the chain is COMPLETE only when `transition to=COMPLETE` returns COMPLETE phase and plugkit's on-disk state file reflects it. "I think we're done" is not done. "The user seems satisfied" is not done. The COMPLETE gate (gates.rs) is the single arbiter — it refuses on PRD-open, mutables-unresolved, dirty worktree, or missing residual-scan marker. The agent's job is to drive the chain into a state where the gate allows, then dispatch the verb, then read the response. Anything else is narration.
+
+**Always seek the next state transition**: if the chain is not COMPLETE, there is a next move. Idle mid-chain is a deviation. The agent who finishes a verb and stops without dispatching the next instruction has stopped walking the chain. `phase-status` tells you where you are; `instruction` tells you what's next. There is no "I'll wait for the user" mid-chain — the user authorized closure at request time, not phase-by-phase.
+
+**Return to plugkit on every drift**: `instruction` is the recovery primitive. When the agent stalls, gets denied at a gate, hits an unexpected error, or feels uncertain about the next step, the response is always to dispatch `instruction` and read the prose — never to improvise. The verb is synchronous, cheap, idempotent; over-dispatching it has no cost, under-dispatching it is the canonical drift mechanism. A session that goes >N tool calls without an instruction dispatch in a non-trivial phase is hallucinating its own chain. Gate denials always name the next verb in their `reason` field — the agent reads the field and dispatches the named verb, never argues around the denial.
+
+**Push is part of COMPLETE, never optional, never asked**: every session that mutates tracked files ends with commit + push to origin. Asking the user "do you want me to push?" is a deviation — the push IS the validation dispatch (`verify.rs`: "The push you make IS the validation dispatch"). The chain is not COMPLETE until the remote reflects HEAD. ccsniff `--git-discipline` and a pending `deviation.complete-without-push` event flag sessions that close without pushing.
+
+**Push requires clean worktree**: `git push` is admissible only when `git status --porcelain` returns empty. A push from a dirty tree orphans the unstaged delta and breaks the next session's first read. Enforced in `lib/spool-dispatch.js::canExecuteGit('git-push')` (porcelain probe via spool exec) and rs-plugkit `gates.rs` COMPLETE branch; instruction prose (`verify.rs`, `update_docs.rs`) restates it imperatively; `residual.rs` skips the scan when dirty so the four-observation window cannot be claimed past an unwitnessed delta. ccsniff `--git-discipline` flags the deviation post-hoc.
+
+**memorize dispatch manages CLAUDE.md / AGENTS.md**: Do not inline-edit. Dispatch via spool: write `.gm/exec-spool/in/memorize/<N>.txt` with the fact text; the wasm orchestrator embeds and persists it. Classifier rejects changelog-shaped facts from AGENTS.md ingestion (rs-learn store still accepts them).
+
+**Behavioral discipline lives in plugkit's `instruction` verb** — Three-Layer Admission Filter (L1 cost, L2 bounds, L3 direction), maturity-first emit, response-not-mutation-surface, structural recognition of closure anti-shapes, code invariants (state-space minimization, hardware-reality, flat-structure, vertical-slice, async-boundary, naming-by-scale, fail-fast, binary-transport, single-focus). Dispatch `instruction` for the live prose; do not duplicate it here.
+
+**host_exec_js is synchronous**: wasm host runs `exec_js` via Node `child_process.spawnSync`; long subprocesses block the watcher. Pass a real per-call timeout; orphaned background work unsupported under wasm.
+
+**Sync-before-emit (codeinsight + search)**: outputs must come from freshly-completed indices. Cache serves only on digest match (mtime sum + git HEAD + dirty-tree marker). Default invocation runs fresh. `--read-cache` permitted only when `.codeinsight.digest` matches; mismatch auto-refreshes. rs-search runs scan + embed + sweep before first result; emits `[index fully synced: …]`. Unverified-index emit = stale ground truth.
+
+**Auto-recall on prompt-submit**: rs-plugkit prompt-submit hook derives 2-6 word recall query from user prompt, calls rs-learn `Searcher` directly via shared tokio Runtime, injects "## Recall for this prompt" into systemMessage. Session-start auto-search (codeinsight) + every-prompt auto-recall ensure every turn begins with prior memory loaded.
+
+**Skill SKILL.md frontmatter `allowed-tools:` is harness-enforced**: If a skill omits `allowed-tools` or does not list `Skill`, the model loses the ability to invoke downstream skills that turn. The shipped surface is a single skill (`gm-skill`); this rule governs any future skill that participates in a chain.
+
+**rs-learn observability**: every learning-pipeline state change emits a structured `evt: {event, sess, ts, ...}` line via `wasm_dispatch::emit_event` (host_log level 1) into `.gm/exec-spool/.watcher.log` and gm-log/<date>/plugkit.jsonl. Event taxonomy: `embed_fail` (step + error), `embed_init_ok/fail/cached_fail`, `memorize_reject` (reason, text_prefix, namespace), `memorize_embed_rollback` (key, namespace, error), `discipline_sigil_ignored` (sigil in @<name> request routed to default), `table_dropped` (dim-mismatch silent drops), `recall_score_unavailable` (host_vec_search strips score). Recall replies now include `mode` (vector_top_k|fallback_like|kv_query), `namespace`, `derived_query`, and per-hit `score` (null when host elides). gmsniff flags: `--embed-failures`, `--recall-misses`, `--recall-scores`, `--classifier-rejects`, `--memory-leverage`, `--recall-modes`, `--table-drops`, `--discipline-sigil-ignored`. ccsniff `--learning-xref` joins transcript turn windows to rs_learn events by sess (now stamped) + project + time-window. Learning quality is observable, not algorithmic black box.
+
+**SKILL.md auto-refresh**: every bootstrap call (`bootstrapPlugkit`) compares the sha256 of the bundled `gm-skill/skills/gm-skill/SKILL.md` (shipped inside the npm package) against the installed copies at `~/.agents/skills/gm-skill/SKILL.md` and `~/.claude/skills/gm-skill/SKILL.md`. Hash mismatch triggers atomic write (`.tmp` + rename) of both targets so the agent sees the latest prose on next session — no manual reinstall needed. Logged to `bootstrap.jsonl` as `SKILL.md refreshed`. The bundled SKILL.md is the source of truth; reinstalling gm-skill only matters when the npm package itself changes, which the cascade pipeline guarantees on every plugkit version bump.
+
+**Skill-initiated bootstrap contract**: `lib/skill-bootstrap.js` performs wasm initialization for skill-driven dispatch without hook infrastructure. `bootstrapPlugkit(sessionId)` accepts optional SESSION_ID, ensures the wasm artifact and `plugkit-wasm-wrapper.js` are in place, writes status/error to `.gm/exec-spool/.bootstrap-status.json` and `.bootstrap-error.json` for spool awareness, and returns `{ ok: true }` on success or `{ ok: false, error: message }` on failure. Failures are non-fatal — callers fall back to a degraded surface.
+
+## Cascade pipeline
+
+Push to any rs-* sibling repo (rs-exec, rs-search, rs-codeinsight, rs-learn) triggers `cascade.yml` which uses `gh workflow run` to invoke rs-plugkit's `release.yml` via PUBLISHER_TOKEN. rs-plugkit cargo-pulls the latest sibling crate revs at build time and emits a single `plugkit.wasm` artifact (no per-sibling npm wasm packages — that pattern was retired). Publishes to `plugkit-bin` Releases + npm `plugkit-wasm`, then auto-bumps `gm.json::plugkitVersion` and `bin/plugkit.wasm.sha256` in this repo. The version bump commit on this repo triggers `publish.yml`, which (a) `npm publish`es `gm-skill` from the repo root, (b) `npm publish`es `gm-plugkit` from `gm-plugkit/`, and (c) force-pushes `skills/gm-skill/SKILL.md` to the `AnEntrypoint/gm-skill` back-compat mirror repo.
+
+There is one published artifact: the `gm-skill` npm package. The legacy 15 downstream repos (gm-cc, gm-gc, gm-oc, gm-kilo, gm-codex, gm-qwen, gm-copilot-cli, gm-hermes, gm-thebird, gm-vscode, gm-cursor, gm-zed, gm-jetbrains, gm-antigravity, gm-windsurf) are archived on GitHub — no further releases, no orphan-commit publish step.
+
+**Repos involved (push to any triggers cascade):**
+- `AnEntrypoint/rs-exec` — exec runner, browser sessions, idle cleanup, session task isolation
+- `AnEntrypoint/rs-codeinsight` — code search backend, symbol indexing
+- `AnEntrypoint/rs-search` — file search backend, embedding and sweep
+- `AnEntrypoint/rs-plugkit` — CLI entry point, spool watcher dispatcher; version source of truth in `Cargo.toml`
+- `AnEntrypoint/rs-learn` — memory backend, recall/ingest via HTTP RPC
+- `AnEntrypoint/gm` — `gm.json` holds `plugkitVersion`; CI publishes the single `gm-skill` npm package
+
+**To update anything**: push to the relevant repo. No manual version bumps, no local cargo builds. Never run `cargo update` or `cargo build` locally — push and let CI build.
+
+**PUBLISHER_TOKEN required** in `rs-exec`, `rs-codeinsight`, `rs-search` for cascade.yml to trigger rs-plugkit. Set with: `gh secret set PUBLISHER_TOKEN --repo AnEntrypoint/<repo>`.
+
+**Timeout enforcement**: every `exec_js` dispatch carries a positive `timeoutMs`. The host treats missing or zero as a hard error.
+
+## Spool-dispatch architecture replaces hooks
+
+Orchestration state is tracked via marker files in `.gm/` instead of hook events. `SpoolDispatcher` reads these markers via `checkDispatchGates(sessionId, operation)` and gates tool use, writes, and git operations:
+
+**Marker files**: `.gm/prd.yml` (existence triggers needs-gm gate), `.gm/mutables.yml` (unresolved entries block Write/Edit/git), `.gm/needs-gm` (written by bootstrap, read by dispatcher), `.gm/gm-fired-<sessionId>` (written by gm skill/agent, cleared at turn start), `.gm/residual-check-fired` (ensures one-shot residual-scan per stop window).
+
+**Gate enforcement**: CLI layer (plugkit, rs-exec, downstream platforms) calls `checkDispatchGates()` before tool execution. On denial, reason text surfaces to the model. Bootstrap (lib/skill-bootstrap.js) handles daemon initialization and marker setup. Marker-driven dispatch replaces hook event pump entirely — no session event callbacks needed.
+
+**gm-skill tool-use sequencing**: Invoking `Skill(skill="gm-skill")` writes `.gm/gm-fired-<sessionId>` to clear the needs-gm gate. The marker is cleared at turn start to reset the gate. There is one shipped skill; no subagent variant exists.
+
+**Session lifecycle**: Session-end kills background tasks via `killSessionTasks` RPC on real-exit reasons (clear/logout/prompt_input_exit). Browser sessions and background tasks persist across turn-stops — cleanup happens exclusively on real-exit reasons. Residual-scan fires when PRD is empty/missing AND no open browser sessions AND no running tasks; agent either expands PRD with in-spirit residuals or explicitly states none.
+
+## Spool observability surface
+
+Every agent has a one-shot system-state probe: dispatch `plugkit health` via the file-spool (write `.gm/exec-spool/in/health/<N>.txt` empty body, read `out/<N>.json`). Returns plugkit version + pin-match, watcher liveness, runner state, rs-learn status, cache dirs, inbox/outbox counts, recent hook fires, recent errors. Use before assuming any component is broken.
+
+Three persistent diagnostic files at `.gm/exec-spool/` root are updated by the running stack (not the agent): `.status.json` (watcher state each tick; stale mtime = dead watcher), `.last-session-start.json` (most recent session-start spawn result), `.bootstrap-error.json` (pin-mismatch / fetch-fail surface — absent = healthy). Reading these directly via Read is allowed (runtime data exception); spool dispatch isn't needed to inspect them.
+
+## Site Build & Documentation
+
+**Mermaid integration**: `theme.mjs` (articleClient + landingClient) dynamic-imports mermaid from cdn.jsdelivr.net after `applyDiff` and calls `mermaid.run()` on `.mermaid` blocks. `startOnLoad` must be false—the parse happens before article injection, so `startOnLoad` would miss injected blocks. Theme auto-detects color scheme via `prefers-color-scheme`.
+
+**Navigation**: `site/content/globals/navigation.yaml` uses grouped entry format—each item is either `{label, href}` (single link) or `{label, group: [{label, href}, ...]}` (dropdown menu). Dropdowns render via `<details>/<summary>` in `theme.mjs::GmTopbar`; no JS required. In-page topbars in docs/paper*.html et al. render directly on file open and must be kept in sync with the same markup.
+
+**Landing page renderer**: the deployed `/` route on https://anentrypoint.github.io/gm/ is rendered by `site/theme.mjs` from `site/content/pages/home.yaml` via flatspace. `site/index.html` + `site/main.js` build `docs/bundle.js` for non-flatspace standalone preview only. Landing edits go through `site/theme.mjs` (Hero) and `site/content/pages/home.yaml` (content), never `site/index.html`.
+
+**docs/styles.css is generated**: regenerated from `site/input.css` by `site/package.json` build script (copies input.css → docs/styles.css after esbuild). Direct edits to docs/styles.css are wiped on next build — append to site/input.css instead.
+
+## Made with gm Page
+
+`docs/made-with.html` is a static showcase of notable AnEntrypoint projects. Update the PROJECTS array when a new notable project is added — projects with interesting descriptions, meaningful star counts, or technically unusual scope. Static data, no runtime API calls. Standalone HTML, not bundled.
+
+
+@.gm/next-step.md

package/README.md

@@ -1,42 +1,101 @@
-# gm-skill — Canonical Universal Harness
+# glootius maximus (gm)
 
-The single shipped skill for gm. Install into any harness that loads Claude-style skill directories — Claude Code, OpenCode, Cursor, Zed, VS Code, Codex, Kilo, JetBrains, Copilot CLI, Antigravity, Windsurf, Gemini CLI — and you dispatch the `instruction` verb each turn to read every phase directive, mutables row, and guardrail from plugkit via the spool. You are the state machine; plugkit serves the response the moment you write the request.
+> **more coushin' for the puhin'**
 
-## What this is
+gm is a skill that convinces your coding agent it already is a deterministic state machine — PLAN → EXECUTE → EMIT → VERIFY → COMPLETE — and then enforces that conviction with a wasm-backed orchestrator, witnessed execution, and a covering family of bounded subsets that refuses to let "follow-up" become a synonym for "I gave up."
 
-AI-native software engineering orchestrated as a state machine — PLAN → EXECUTE → EMIT → VERIFY → COMPLETE — backed by the `plugkit` WASM orchestrator. Spool-driven dispatch, no daemon, no native binaries.
+it is named after **glootius maximus**, the muscle that holds you in the chair while you finish the work. the name is the joke and the discipline at once: the agent that sits down through PLAN → EXECUTE → EMIT → VERIFY → COMPLETE actually ships. the agent that stands up early ships a stub with a green check on it.
 
-## Install
+built over ~200 commits of daily use. free, open source, maintained by one person.
 
-```bash
-bun x skills add AnEntrypoint/gm-skill -y -g
+disclaimer: this is extremely opinionated. it will block bash, redirect your tools, refuse to write test files, force you to push git before ending a session, and reject any execute call without an explicit timeout. if that sounds terrible, this is not for you. if that sounds like what you wish your agent did automatically, keep sitting down.
+
+## install
+
+```
+bun x skills add AnEntrypoint/gm -y -g
 ```
 
-Then add this line to your agent's global memory / system prompt:
+then add this line to your agent's global memory / system prompt:
 
 ```
 always use the gm-skill skill for everything, always fan out subagents
 ```
 
-You need bun installed: `curl -fsSL https://bun.sh/install | bash`
+you need bun installed: `curl -fsSL https://bun.sh/install | bash`
+
+> The legacy `AnEntrypoint/gm-skill` repo is now a back-compat mirror that only contains `skills/gm-skill/SKILL.md`. New installs should prefer `AnEntrypoint/gm`.
+
+## what's in this repo
+
+This repo IS the published `gm-skill` npm package. No build step, no factory. The directory layout you see at root is exactly what ships:
+
+```
+gm/
+├── skills/gm-skill/   ← the skill (SKILL.md + index.js, ~12 lines of prose)
+├── bin/               ← bootstrap, plugkit launcher, gmsniff, ccsniff
+├── lib/               ← runtime: spool dispatch, skill bootstrap, daemon mgmt
+├── agents/            ← subagent prompts (gm, memorize, research-worker, textprocessing)
+├── prompts/           ← bash-deny, session-start, prompt-submit, pre-compact
+├── lang/              ← language packs (browser, ssh)
+├── gm-plugkit/        ← separate npm package that ships the wasm-wrapper
+├── gm.json            ← version + plugkit pin
+├── package.json       ← npm publish manifest
+├── AGENTS.md          ← architectural rules (present-tense, no history)
+├── CHANGELOG.md       ← release history
+└── site/              ← flatspace site source (built to dist/ by CI)
+```
+
+The two npm packages this repo publishes:
+
+- **`gm-skill`** — the skill bundle, installed via `bun x skills`
+- **`gm-plugkit`** — the wasm-wrapper daemon, dependency of `gm-skill`
+
+## how it works
+
+### the state machine
+
+PLAN → EXECUTE → EMIT → VERIFY → COMPLETE. Every transition is a verb the agent dispatches by writing to `.gm/exec-spool/in/<verb>/<N>.txt`. The wasm orchestrator (rs-plugkit) services it and writes the response to `.gm/exec-spool/out/`. The agent reads, follows the imperative prose, dispatches the next verb. The chain isn't complete until `transition to=COMPLETE` returns COMPLETE phase AND the commit is pushed to origin.
+
+### tools
+
+Every tool the agent uses is a dispatch verb. No direct shell, no direct file writes outside the spool. The wasm host owns the side effects.
+
+- **`recall`** — vector + KV recall against `rs-learn`, scored by cosine × recency, namespace-aware
+- **`codesearch`** — semantic vector search across the project
+- **`memorize`** — write to the recall index (with the BGE query/passage prefix asymmetry)
+- **`browser`** — managed Chrome session with project-scoped profile at `.gm/browser-profile/`
+- **`git_status` / `branch_status` / `git_push`** — git verbs that gate on porcelain
+- **`filter`** — in-wasm stdout-compaction (grep/ls/tree/json/diff)
+
+### hooks
+
+- **session-start** — bootstraps plugkit, seeds `.gm/next-step.md`, sets `needs-gm` marker
+- **prompt-submit** — reminds the agent to dispatch instruction first; injects per-prompt auto-recall
+- **pre-tool-use** — blocks tool use before the gm skill fires for the turn
+- **stop** — blocks session end while `.gm/prd.yml` has open items, mutables are unresolved, residual-scan hasn't fired, or the worktree is dirty
+
+### ground truth
+
+No mocks, no fakes, no unit tests on disk. Real services, real responses only. The single `test.js` at project root is the integration harness; `gm-complete` runs it before allowing session end.
 
-## What's inside
+### memory
 
-- `skills/gm-skill/` — the canonical universal harness (`SKILL.md` is the ~12-line entry point)
-- `gm-plugkit/` — WASM bootstrap and spool watcher wrapper
-- `lib/` — skill-bootstrap, spool-dispatch, daemon-bootstrap, git, codeinsight modules
-- `bin/plugkit.wasm.sha256` — pinned hash of the plugkit WASM artifact
+`.gm/rs-learn.db` is the per-project memory store, committed to git so it travels with the project. Vector embeddings via BGE-small-en-v1.5 (with proper query/passage asymmetry: queries prefixed with `"Represent this sentence for searching relevant passages: "`, passages raw). LRU query-embedding cache (64 entries, 10-min TTL) sits in front to avoid re-embedding repeat queries.
 
-## Architecture
+## release pipeline
 
-All orchestration lives in `rs-plugkit/src/orchestrator/` as native Rust, compiled to a single `plugkit.wasm` (~<200KB). The agent dispatches verbs by writing to `.gm/exec-spool/in/<verb>/<N>.txt` and reading responses from `.gm/exec-spool/out/`. See [AGENTS.md](https://github.com/AnEntrypoint/gm/blob/main/AGENTS.md) for the full design.
+A push to `main` triggers `.github/workflows/publish.yml`:
 
-An earlier generation fanned out fifteen per-platform downstream repos (gm-cc, gm-gc, gm-oc, gm-kilo, gm-codex, gm-qwen, gm-copilot-cli, gm-hermes, gm-thebird, gm-vscode, gm-cursor, gm-zed, gm-jetbrains, gm-antigravity, gm-windsurf). Those are archived; `gm-skill` is the single source of truth.
+1. auto-bump `gm.json::version` + `package.json::version` + `gm-plugkit/package.json::version`
+2. publish `gm-skill` to npm from repo root (no build step)
+3. publish `gm-plugkit` to npm from `gm-plugkit/`
+4. mirror `skills/gm-skill/SKILL.md` to the `AnEntrypoint/gm-skill` repo (back-compat)
 
-## Version
+`.github/workflows/gh-pages.yml` builds the `site/` flatspace source to `dist/` and deploys to GitHub Pages.
 
-`2.0.1303` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` (or any cascading sibling crate) republishes this package.
+The plugkit wasm itself is built and released by [rs-plugkit](https://github.com/AnEntrypoint/rs-plugkit) on every push, published to npm as `plugkit-wasm` and to GitHub Releases as `plugkit-bin`. Bootstrapping the agent downloads the wasm at install time — it does not ship in this repo.
 
-## Source of truth
+## license
 
-This package is generated from [AnEntrypoint/gm](https://github.com/AnEntrypoint/gm) — do not edit files in this repo directly; they will be overwritten on next publish.
+MIT