gm-skill 2.0.1872 → 2.0.1874

package/AGENTS.md

@@ -92,9 +92,9 @@ A task that reduces to read/investigate/report, or a change confined to files th
 
 ## Core Rules
 
-**Memory is human-readable md, tracked; derived stores are transient, never tracked**: canonical memory = `.gm/memories/<key>.md` (project facts) + `.gm/disciplines/<name>/memories/<key>.md` (transferable discipline knowledge), frontmatter `key/ns/created/updated`, UTF-8 no BOM, LF -- text shares cross-machine/session/CI as reviewable diffs. The md read path is live (recall serves the md-derived index once a project's corpus digest converges); legacy flat-JSON KV (`.gm/disciplines/<ns>/*.json`) is a frozen fallback + embedding-reuse source, tracked until the flat-write-removal follow-up retires it. Derived state (embeddings/`*-vec`, codeinsight manifests/digests, local sqlite/index dbs) is rebuildable-from-corpus, listed one-by-one between managed gitignore markers (parent-re-include caveat). Entry list + `ensureGitignored` mechanics: the recall store (`recall: gm managed-gitignore mechanics`). Project-local persistent state -> `.gm/<name>/`, never top-level dotfile/dotdir.
+**Memory is human-readable md, tracked; derived stores are transient, never tracked.** Detail: the recall store (`recall: gm memory storage mechanics`, `recall: gm managed-gitignore mechanics`).
 
-**Disciplines are isolated knowledge stores**: per-project `<project>/.gm/disciplines/<name>/{memories/, code-search/}`, own corpus+index each; memorize-time routing auto-creates a not-previously-known discipline's store rather than mixing it into project memories. `@<name>` sigil = strict isolation (cross-discipline reads forbidden). Sigil-less reads (recall/codesearch) fan across `default` + every `enabled.txt` line, merge-ranked `[discipline:<name>]`-prefixed; sigil-less writes -> project store only. Tracked, never ignored (`ensureGitignored` excludes `.gm/disciplines`); derived per-discipline caches follow the transient rule above. Harness + every spool verb propagate `@<name>` verbatim.
+**Disciplines are isolated knowledge stores**, tracked, `@<name>` sigil-scoped. Detail: the recall store (`recall: gm disciplines mechanics`).
 
 **Nothing fake in source the user runs**: stub/mock/placeholder-return/fixture-only-path/demo-mode-short-circuit/"TODO: implement" forbidden in shipped code. Scaffolds/shims permitted only delegating to real behavior (upstream API, subprocess, disk); check for an existing library before adding a shim. Detection = behavioral: always-succeeds, input-invariant, or type-signature-satisfying short-circuit = stub. Acceptance = real input through real code into real output, witnessed. `Mock*`/`Fake*`/`Stub*` names checked at VERIFY explicitly, not left prose-only (`recall: nevil false-completion mock-network incident`). A row marked `completed` by documenting it (a README "Future Optimizations" section, a design note) instead of implementing it is the same violation -- `prd-resolve` structurally refuses two PRD rows sharing byte-identical `witness_evidence` text (`deviation.prd-resolve-duplicate-witness`), the copy-paste tell of rubber-stamped completion.
 

package/gm-plugkit/bootstrap.js

@@ -931,11 +931,12 @@ async function probeSelfStaleness(timeoutMs) {
 async function ensureReady(opts) {
   opts = opts || {};
   const offline = opts.offline === true;
+  const skipSelfStaleCheck = offline || process.env.GM_PLUGKIT_SKIP_SELF_STALE_CHECK === '1';
 
   try { ensureNextStepWiring(process.env.CLAUDE_PROJECT_DIR || process.cwd()); } catch (_) {}
   try { ensureInstructionsBundle(process.env.CLAUDE_PROJECT_DIR || process.cwd()); } catch (_) {}
 
-  if (!offline) {
+  if (!skipSelfStaleCheck) {
     try {
       const selfStale = await probeSelfStaleness(2500);
       if (selfStale && selfStale.stale) {

package/gm-plugkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.1872",
+  "version": "2.0.1874",
   "description": "Bootstrap and daemon-spawn tool for gm plugkit binary. Downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Includes plugkit-wasm-wrapper for WASM-based spool watching.",
   "main": "index.js",
   "bin": {

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1872",
+  "version": "2.0.1874",
   "description": "Spool-dispatch orchestration engine with unified state machine, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1872",
+  "version": "2.0.1874",
   "description": "Canonical universal harness — AI-native software engineering via skill-driven orchestration; bootstraps plugkit for task execution and session isolation. Install in any AI coding agent host.",
   "author": "AnEntrypoint",
   "license": "MIT",

package/skills/gm/SKILL.md

@@ -26,7 +26,9 @@ allowed-tools: Skill, Read, Write, Bash(bun *), Bash(npx *), Bash(cat *), Bash(d
 
 Verbs are written to `.gm/exec-spool/in/<verb>/<N>.txt` as JSON. Plugkit processes on read. Phase transitions are explicit `transition {to:"PHASE"}` dispatches. Phase state is in responses and `.gm/exec-spool/.turn-summary.json`; never assume phase from context.
 
-Check `.gm/exec-spool/.turn-summary.json` at turn start. If `update_available` is set, dispatch `bun x gm-plugkit@latest spool` first. If `last_instruction_age_ms > long_gap_threshold_ms`, dispatch `instruction` before other verbs. Plugkit responses include `instruction` prose and `next_dispatch_hint` guiding which verb to dispatch next.
+Check `.gm/exec-spool/.turn-summary.json` at turn start. If `update_available` is set, dispatch `bun x gm-plugkit@latest spool` first. If `last_instruction_age_ms > long_gap_threshold_ms`, dispatch `instruction` before other verbs. Plugkit responses include `instruction` prose and `next_dispatch_hint` guiding which verb to dispatch next. `next_dispatch_hint: null` is not an error -- it means the served phase-prose itself (or `next_phase_hint`) is the guide for this dispatch; read the prose, act on it, never treat a null hint as a stall.
+
+A `phase` reading that disagrees between `.turn-summary.json` and the immediately-following `instruction` response is not a bug to chase -- the wasm state is the single source of truth and `.turn-summary.json` is a point-in-time snapshot that can lag a fresh dispatch (another concurrent writer, or the state simply advanced between the two reads). The `instruction` response's own `phase` field always wins; re-dispatch `instruction` once more if still uncertain, never reason from the stale snapshot.
 
 When `phase=COMPLETE` and `prd_pending_count=0`, work is terminal. New prompts are processed as new sessions. Dispatching another `instruction` after terminal state records as `deviation.complete-chain-poll`.
 
@@ -40,6 +42,8 @@ Spool verbs are the primary interface: `codesearch`, `recall`, `fetch`, `exec_js
 
 `prd-resolve` accepts an optional `commit_comment` (a one-line resolution note) alongside `id`/`witness_evidence`. When present, the row's note rides until the repo's next `git_commit`/`git_finalize`, which bundles every pending note for that repo into the commit message under a "Resolved PRD rows" section and clears those rows from `.gm/prd.yml`. Unrelated issues discovered mid-task are `prd-add`, never a same-turn detour and never dropped -- a later cover picks them up deliberately.
 
+**Single-writer discipline: `.gm/prd.yml` and `.gm/mutables.yml` are shared state, not exclusively yours.** A `prd_pending_count` that jumped since your last read, or a fresh `.gm/exec-spool/` file mtime you didn't write, means a second session is driving the same repo concurrently -- not a bug to chase. Detect it: unexplained pending-count growth between two close-together reads, or a repo's `git status --porcelain` showing edits mid-flight in files you have not touched this turn. On detection: name the actively-changing surface in a `prd-add`/`mutable-add` row (what's changing, why you are deferring), back off committing into that specific tree until it goes quiet (`git status --porcelain` empty, no fresh mtimes), and resume once it settles -- never race a commit against a concurrent writer's in-progress edit. This applies per-repo, not per-session: a multi-repo walk can safely keep working other repos while one is actively contended.
+
 Missing `.gm/exec-spool` on first use is normal. Boot the watcher before dispatching work.
 
 Boot probe at session start, one Bash call:
@@ -56,6 +60,8 @@ bun x gm-plugkit@latest spool
 
 (`npx -y gm-plugkit@latest spool` if no `bun`.) Fire-and-forget: spawns the detached daemon and returns immediately (already-alive watcher also returns at once, unchanged) -- it does NOT wait for the watcher to confirm serving. No `&`, no `sleep`, no re-`cat`; write your first verb to `in/` right after it returns. A first-read "file does not exist" on that verb is normal (the just-spawned watcher hasn't noticed the file yet) -- re-Read next message, same as any dead-watcher-adjacent recheck. If you need to actively confirm serving before dispatching (rare), read `.gm/exec-spool/.status.json` yourself and check `ts` freshness.
 
+The `Resolving dependencies` / `Saved lockfile` chatter before the JSON payload is `bunx` re-resolving the `@latest` tag against the registry, not gm-plugkit hanging -- the daemon already spawns detached+unref'd and the CLI itself exits the instant that happens; the visible delay is entirely bunx's own network round-trip, unavoidable on `@latest` (a pinned exact version, once bunx-cached, skips it). `GM_PLUGKIT_SKIP_SELF_STALE_CHECK=1` skips the CLI's own redundant npm-registry version probe (already covered by `@latest`'s resolution) for a faster boot on repeat same-session invocations. In PowerShell 5.1, never `2>&1`-redirect this command into another cmdlet (e.g. `| Select-Object`) -- PowerShell wraps every stderr line from a native exe in a `NativeCommandError` record and reports failure even on exit 0, turning bun's routine stderr progress output into a misleading red error block; run it bare or capture stdout only.
+
 **Dispatch shape: Write request + Read response, SAME tool-call block.** Never proceed/narrate/begin work before reading the response and following its `instruction` field. First-read "file does not exist" mid-verb = normal, re-Read next message. Never poll with `sleep && ls` -- plugkit is synchronous; missing response = dead watcher (recheck `ts`) or slow verb, never "still processing."
 
 **Dead-watcher recovery is mandatory, not optional.** Two consecutive missing re-Reads AND stale `ts` (>5min) AND no future `busy_until` = dead: `bun x gm-plugkit@latest spool` boots fresh, re-dispatch the original verb. If `busy_until` is set, the watcher is processing a long verb; wait instead of rebooting. Recovery = notice-dead -> boot -> re-dispatch, always -- never substitute a raw tool for the dead verb.