gm-skill 0.1.2 → 2.0.1081

package/skills/gm-emit/SKILL.md

@@ -1,70 +1,37 @@
 ---
 name: gm-emit
 description: EMIT phase. Pre-emit debug, write files, post-emit verify from disk. Any new unknown triggers immediate snake back to planning — restart chain.
+allowed-tools: Skill, Read, Write
 ---
 
-# GM EMIT — Write and verify from disk
+# gm-emit — EMIT
 
-Entry: every mutable KNOWN, from `gm-execute` or re-entered from VERIFY. Exit: gates clear → `gm-complete`.
+EMIT is where intent becomes artifact. The phase exists as a distinct gate because writing without verification produces silent drift between what the agent believes was emitted and what landed on disk.
 
-Cross-cutting dispositions live in `gm` SKILL.md.
+## Pre-Emit
 
-## Transitions
+Before writing, debug the planned state. Read the target paths that will be touched — confirm current contents match the assumption the diff is built on. A diff applied to a file the agent has not freshly read is a diff against a stale model. Spool the reads if scope is wide; serial Read calls are acceptable for a small set. Surface mismatches → snake to PLAN.
 
-- All gates clear → `gm-complete`
-- Post-emit variance with known cause → fix in-band, re-verify, stay in EMIT
-- Pre-emit reveals known logic error → `gm-execute`
-- Pre-emit reveals new unknown OR post-emit variance with unknown cause OR scope changed → `planning`
+## Sync-Before-Emit
 
-## Legitimacy gate (before pre-emit run)
+rs-codeinsight and rs-search outputs feeding EMIT must come from a freshly-completed index. No cache serves a result without a digest match against the live filesystem. Default invocation always runs fresh. `--read-cache` is permitted only when `.codeinsight.digest` matches exactly; on mismatch, the cache auto-refreshes before the result emits. Emitting from an unverified or partial index is forced closure equivalent to bluffing strength — the agent reads stale output as ground truth and acts on a state that no longer exists.
 
-For every claim landing in a file, answer five questions:
+## Write
 
-1. Earned specificity — does it trace to `authorization=witnessed`, or is it inflated from a weak prior?
-2. Repair legality — is a local patch dressed as structural repair? Downgrade scope or regress to PLAN.
-3. Lawful downgrade — can a weaker, true statement replace it? Prefer the downgrade.
-4. Alternative-route suppression — is a live competing route being silenced? Preserve it.
-5. Strongest objection — what would the sharpest reviewer pushback be? Articulate it. Cannot articulate = have not understood the alternatives → `gm-execute`.
+One Edit or Write per artifact. No multi-file batches that conceal which file failed if one fails. Spool larger payloads through `in/nodejs/` when shape demands it.
 
-Any failure regresses to `gm-execute` to witness what was missing, or `planning` if the gap is structural.
+## Post-Emit Verify
 
-## Pre-emit run
+After each write, re-read the file from disk and assert the change is present. The Read tool is the post-emit witness. Discrepancy → Fix on Sight: fix at root, re-emit, re-verify. A green Write call is not the witness — the verified disk state is.
 
-Mandatory before writing any file. Write the probe to the spool (`.gm/exec-spool/in/nodejs/<N>.js`):
+## Fix on Sight
 
-```
-const { fn } = await import('/abs/path/to/module.js');
-console.log(await fn(realInput));
-```
+Issues surfaced during EMIT (a write that revealed a previously-hidden import error, a generated file that no longer matches its source) are fixed this turn at root cause. Add the residual to PRD before transitioning if the fix expands scope beyond the current slice.
 
-Import the actual module from disk to witness current behavior as the baseline. Run the proposed logic in isolation without writing — witness with real inputs and with real error inputs. Match expected → write. Unexpected → new unknown → `planning`.
+## Dispatch
 
-## Writing
+`phase-status` to check FSM state before transition. Spool any meaningful reads/writes for auditability.
 
-Use the Write tool, or a nodejs spool file with `require('fs')`. Write only when every gate mutable resolves simultaneously.
+## Transition
 
-## Post-emit verification
-
-Re-import from disk — in-memory state is stale and inadmissible. Run identical inputs as pre-emit; output must match the baseline exactly. Known variance → fix and re-verify (self-loop). Unknown variance → `planning`.
-
-## Mutables gate
-
-Before pre-emit run, read `.gm/mutables.yml`. Any entry with `status: unknown` → regress to `gm-execute`. The pre-tool-use hook hard-blocks Write/Edit/NotebookEdit while unresolved entries exist; trying to emit anyway returns deny. Zero unresolved is the precondition for every legitimacy question below.
-
-## Gate (all true at once)
-
-- `.gm/mutables.yml` empty/absent OR every entry `status: witnessed` with filled `witness_evidence`
-- Legitimacy gate passed; no refused collapse
-- Pre-emit passed with real inputs and real error inputs
-- Post-emit matches pre-emit exactly
-- Hot-reloadable; errors throw with context (no `|| default`, no `catch { return null }`, no fallbacks)
-- No mocks, fakes, stubs, or scattered test files (delete on discovery)
-- Any behavior change has a corresponding assertion in `test.js` — a change no test catches is a change you cannot prove
-- Browser-facing change → post-emit verify includes a live `exec:browser` witness (boot server → `page.goto` → `page.evaluate` asserting the invariant the change established). Node-side import + test.js does not satisfy this — the final gate runs again in `gm-complete`.
-- Files ≤ 200 lines
-- No duplicate concern (run `exec:codesearch` for the primary concern after writing; overlap → `planning`)
-- No comments, no hardcoded values, no adjectives in identifiers, no unnecessary files
-- Observability: new server subsystems expose `/debug/<subsystem>`; new client modules register in `window.__debug`
-- Structure: no if/else where dispatch suffices; no one-liners that obscure; no reinvented APIs
-- Every fact resolved this phase memorized via background `Agent(memorize)`
-- CHANGELOG.md updated; TODO.md cleared or deleted
+Read `out/<N>.json::nextSkill`. Invoke `Skill(skill="gm:<nextSkill>")` immediately. New unknown → `Skill(skill="gm:planning")`.

package/skills/gm-execute/SKILL.md

@@ -1,88 +1,37 @@
 ---
 name: gm-execute
-description: EXECUTE phase AND the foundational execution contract for every skill. Every exec:<lang> run, every witnessed check, every code search, in every phase, follows this skill's discipline. Resolve all mutables via witnessed execution. Any new unknown triggers immediate snake back to planning — restart chain from PLAN.
+description: EXECUTE phase AND the foundational execution contract for every skill. Every spool dispatch 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.
+allowed-tools: Skill, Read, Write
 ---
 
-# GM EXECUTE — Resolve every unknown by witness
+# gm-execute — EXECUTE
 
-Entry: `.prd` with named unknowns. Exit: every mutable KNOWN → invoke `gm-emit`.
+Every PRD item resolves through witnessed execution. Real input through real code into real output, witnessed. Anything less leaves the mutable open.
 
-A `@<discipline>` sigil propagates from PLAN through every recall, codesearch, and memorize call; reads without one fan across default plus enabled disciplines, writes without one go to default only.
+## Fix on Sight
 
-This skill is the execution contract for ALL phases — pre-emit witnesses, post-emit verifies, e2e checks all run on this discipline. Cross-cutting dispositions live in `gm` SKILL.md.
+Every issue surfaced during work is fixed in-band, this turn, at root cause. Defer-markers, swallowed errors, suppressed output, skipped tests, and "address it next session" are variants of the same failure: a known-bad signal carried past the moment of detection. Surface → diagnose → fix at root → re-witness → continue. Pre-existing build breaks, lockfile drift, broken deps, lint failures on neighboring code, stale generated files — all become PRD items the same turn they surface, executed before COMPLETE. The user does not have to ask. Genuinely out-of-reach errors (require credentials, depend on down services, demand product decisions) are named with `blockedBy: external` in the PRD — never silently dropped.
 
-## Transitions
+## Surprise Absorption Prohibition
 
-- All mutables KNOWN → `gm-emit`
-- Still UNKNOWN → re-run from a different angle (max 2 passes)
-- New unknown OR unresolvable after 2 passes → `planning`
+Every unexpected output is a new mutable. The agent that absorbs surprise into its existing model — "that output is weird but the test still passes" — has just resolved an unknown by narrative, which the discipline rejects on principle. Snake back to PLAN, name the new mutable, witness it, resume. The two-pass rule applies: first pass exposes the surprise, second pass either witnesses the new mutable or proves the surprise was a measurement artifact.
 
-## Mutable discipline
+## Nothing Fake
 
-Each mutable carries: name, expected, current, resolution method.
+What ships runs against real services, real data, real binaries. Stubs, mocks, placeholder returns, fixture-only paths, "TODO: implement", hardcoded sample responses, and demo-mode fallbacks are forbidden. They produce green checks that survive into production and lie about what works. Behavioral detection: code paths that always succeed, always return the same value regardless of input, or short-circuit a real call to satisfy a type signature are stubs. Before writing a shim, check whether an upstream library already provides that surface — maintaining a local reimplementation drifts and ages.
 
-Resolves to KNOWN only when all four pass:
+## Browser Witness
 
-- **ΔS = 0** — witnessed output equals expected
-- **λ ≥ 2** — two independent paths agree
-- **ε intact** — adjacent invariants hold
-- **Coverage ≥ 0.70** — enough corpus inspected to rule out contradiction
+Editing code that runs in a browser requires a live `exec:browser` witness in the same turn as the edit. Boot the real surface (server up, page reachable, HTTP 200 witnessed), navigate, poll for the global the change affects, `page.evaluate` asserting the specific invariant, capture witnessed values. Variance → fix at root → re-witness. Pure-prose edits to static documents with no JS/canvas/DOM behavior change are exempt with the exemption tagged. Silent skip on actual behavior change is forced closure.
 
-Unresolved after 2 passes regresses to `planning`. Never narrate past an unresolved mutable.
+## Mutables Resolve
 
-Every witness that resolves a mutable writes back to `.gm/mutables.yml` the same step: set `status: witnessed` and fill `witness_evidence` with concrete proof (file:line, codesearch hit, exec output snippet). No write-back = the mutable stays unknown and the EMIT-gate stays closed. The hook reads this file; the agent's memory of "I resolved it" does not unblock anything.
+The `mutable-resolve` verb auto-fires memorize on success. `witness_evidence` is mandatory — file:line, codesearch hit, exec output snippet. Narrative resolution is rejected. Rows that cannot be witnessed stay `unknown` and the EMIT gate stays closed.
 
-Route candidates from PLAN are `weak_prior` only. Plausibility is the right to test, not the right to believe. A claim with no witness in the current session is a hypothesis — say so when stating it, and say what would settle it. The next reader (you, next turn) needs to know which lines were earned and which were carried forward.
+## Dispatch
 
-## Verification budget
+Spool every exec. `mutable-resolve` to flip rows. `phase-status` to read FSM state. `transition` when the PRD slice for this phase is complete.
 
-Spend on `.prd` items in descending order of consequence-if-wrong × distance-from-witnessed. Items whose failure would collapse the headline finding must reach witnessed status before EMIT; sub-argument-level items need at minimum a stated fallback path.
+## Transition
 
-## Code execution
-
-Code AND utility verbs both run through the file-spool. Write a file to `.gm/exec-spool/in/<lang-or-verb>/<N>.<ext>` — language stems (`in/nodejs/42.js`, `in/python/43.py`, `in/bash/44.sh`, plus typescript, go, rust, c, cpp, java, deno) or verb stems (`in/codesearch/45.txt`, `in/recall/46.txt`, `in/memorize/47.md`, plus wait, sleep, status, close, browser, runner, type, kill-port, forget, feedback, learn-status, learn-debug, learn-build, discipline, pause, health). The spool watcher executes and streams stdout to `out/<N>.out`, stderr to `out/<N>.err`, then writes `out/<N>.json` metadata sidecar at completion (taskId, lang, ok, exitCode, durationMs, timedOut, startedAt, endedAt). Both streams return as systemMessage with `--- stdout ---` / `--- stderr ---` separators. File I/O via a nodejs spool file + `require('fs')`. Only `git` and `gh` run directly in Bash. Never `Bash(node/npm/npx/bun)`, never `Bash(exec:<anything>)`.
-
-Pack runs: `Promise.allSettled`, each idea own try/catch, under 12s per call. Runner: write `in/runner/<N>.txt` with body `start` | `stop` | `status`.
-
-Every exec daemonizes. The hook tails the task logfile up to 30s wall-clock and returns whatever is there — short tasks complete inside the window and look synchronous; long tasks return a task_id with partial output. Continue with `exec:tail` (drain, bounded), `exec:watch` (resume blocking until match or timeout), or `exec:close` (terminate). Never re-spawn a long task to check on it — that orphans the first one. `exec:wait` is a pure timer; `exec:sleep` blocks on a specific task's output; `exec:watch` is the match-or-timeout primitive. Every execution-platform RPC returns the live list of running tasks for this session — close stragglers via `exec:close\n<id>` so the list stays scannable. Session-end (clear/logout/prompt_input_exit) kills the session's tasks; compaction/handoff preserves them.
-
-Every utility verb dispatches via `in/<verb>/<N>.txt`; the body of the file is the verb's argument. There is no inline form and no Bash-prefix form — both are denied by the hook.
-
-## Codebase search
-
-`exec:codesearch` only. Grep, Glob, Find, Explore, raw grep/rg/find inside `exec:bash` are all hook-blocked.
-
-```
-exec:codesearch
-<two-word query>
-```
-
-Start two words, change/add one per pass, minimum four attempts before concluding absent. Known absolute path → `Read`. Known directory → `exec:nodejs` + `fs.readdirSync`.
-
-## Utility verb failure handling
-
-**Utility verb failures must surface**: exec:memorize, exec:recall, exec:codesearch, and other utility verbs may fail (socket unavailable, timeout, network error). Failures do not block witness completion but must be reported to the user with error context. Fallback mechanisms (AGENTS.md for memorize) ensure memory preservation even when rs-learn is temporarily unavailable.
-
-## Import-based execution
-
-Hypotheses become real by importing actual modules from disk. Reimplemented behavior is UNKNOWN. Write the import probe to the spool:
-
-```
-# write .gm/exec-spool/in/nodejs/42.js
-const { fn } = await import('/abs/path/to/module.js');
-console.log(await fn(realInput));
-```
-
-Differential diagnosis: smallest reproduction → compare actual vs expected → name the delta — that delta is the mutable.
-
-## Edits depend on witnesses
-
-Hypothesis → run → witness → edit. An edit before a witness is a guess. Scan via `exec:codesearch` before creating or modifying — duplicate concern regresses to `planning`. Code-quality preference: native → library → structure → write.
-
-## Parallel subagents
-
-Up to 3 `gm:gm` subagents for independent items in one message. Browser escalation: `exec:browser` → `browser` skill → screenshot only as last resort.
-
-## CI is automated
-
-`git push` triggers the Stop hook to watch Actions for the pushed HEAD on the same repo (downstream cascades are not auto-watched). Green → Stop approves with summary; failure → run names + IDs surfaced, investigate via `gh run view <id> --log-failed`. Deadline 180s (override `GM_CI_WATCH_SECS`).
+Read `out/<N>.json::nextSkill`. Invoke `Skill(skill="gm:<nextSkill>")` immediately. New unknown surfaces → snake to `Skill(skill="gm:planning")`, restart chain.

package/skills/gm-skill/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gm-skill
+description: Canonical universal harness — AI-native software engineering via skill-driven orchestration; bootstraps plugkit for task execution and session isolation
+allowed-tools: Skill, Read, Write
+---
+
+# GM — Universal Skill Harness
+
+Single canonical body re-exported by every platform-specific gm-<platform> skill. All 15 platforms share this identical surface. AI-native software engineering orchestrated as a continuous chain: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS, no stops between phases, no permission gates, the user's first request is the authorization for the whole chain.
+
+## Bootstrap
+
+`bun x gm-plugkit@latest --daemon` downloads the correct platform binary, verifies SHA256, starts the spool watcher daemon. Idempotent. Call once at session start. Subsequent calls no-op.
+
+Session-ID threading: at skill invoke, generate or detect SESSION_ID (env `SESSION_ID` or `uuid()`). Every rs-exec RPC body and every spool-written task body carries `sessionId: "<id>"`. Task-scoped cleanup (deleteTask, getTask, appendOutput, killSessionTasks) requires matching sessionId. Absence is hard-rejected by the handler — no orphaned tasks.
+
+## Spool Dispatch Surface
+
+Every dispatch goes through the spool. Tool args are ephemeral, inline, do not survive compaction, are not replayable. A file-based surface inverts every one of those: the request lives on disk before the watcher reads it, the watcher is detached from the agent process, the output triplet (`.out`, `.err`, `.json`) is auditable after the fact.
+
+Write to `.gm/exec-spool/in/<lang>/<N>.<ext>` (nodejs, python, bash, typescript, go, rust, c, cpp, java, deno) or `in/<verb>/<N>.txt` (codesearch, recall, memorize, wait, sleep, status, close, browser, runner, type, kill-port, forget, feedback, learn-status, learn-debug, learn-build, discipline, pause, health). Watcher streams `out/<N>.out` and `out/<N>.err` line-by-line, then writes `out/<N>.json` metadata (exitCode, durationMs, timedOut, startedAt, endedAt) at completion.
+
+Only `git` and `gh` run directly via the Bash tool. Inline `node script.js`, `Bash(exec:<anything>)`, JSON-form dispatch — all denied at the hook layer.
+
+## Daemonize by Default
+
+The watcher returns a task_id immediately and tails the logfile up to 30 seconds of wall-clock before returning. Short tasks complete inside the window and look synchronous. Long tasks return the task_id with partial output and continue running. The agent never re-spawns a long task to check on it — that orphans the first one.
+
+Resumption grammar: `tail` drains additional output without blocking. `watch` blocks until a regex matches or timeout elapses. `wait` is a pure timer. `sleep` blocks on a specific task's output. `close` terminates. Every RPC response carries `running_task_ids` for the calling session so the agent never loses track of background work it spawned.
+
+## Hooks Throw, Never Mutate
+
+A hook that blocks a tool call throws an error with an imperative instruction string. It does not rewrite the call's arguments into a self-failing form. The thrown error is the entire denial surface. Throw form is for "use a different tool" (the model adapts policy); mutate form would be for "run this corrected version" (the model reads it as a broken tool and retries with simpler commands, reinforcing the wrong mental model).
+
+## Meaning Through Haiku
+
+Any task whose correctness depends on understanding — summarize, classify, extract intent, rewrite, translate, semantic dedup, score, label, decide-if-two-texts-mean-the-same — routes through `Agent(subagent_type='gm:textprocessing', model='haiku', ...)`. One subagent per item, N items in N parallel calls in one message. Code does mechanics well and meaning badly. A keyword-list or regex-on-meaning-phrases loop deciding semantic questions is a stub that ships a green check that lies.
+
+## End-to-End Chaining
+
+When SKILL.md includes `end-to-end: true`, the adapter parses stdout for trailing JSON: `{"nextSkill": "...", "context": {...}, "phase": "..."}`. Non-null `nextSkill` → invoke `Skill(skill="gm:<nextSkill>")` with context, repeat until null. Five skill invocations auto-chain into one user invocation.
+
+Every task returns complete: taskId, exitCode, durationMs, timedOut, stdout, stderr. Background tasks return immediately with task_id; continue with `in/status/<N>.txt` (tail), `in/watch/<N>.txt` (watch), or `in/close/<N>.txt` (close).

package/skills/gm-skill/index.js

@@ -0,0 +1,21 @@
+const fs = require('fs');
+const path = require('path');
+
+const SKILL_MD_PATH = path.join(__dirname, 'SKILL.md');
+
+function loadCanonicalSkill() {
+  return fs.readFileSync(SKILL_MD_PATH, 'utf-8');
+}
+
+function renderPlatformSkill(platformName) {
+  return `---
+name: gm-${platformName}
+description: AI-native software engineering via skill-driven orchestration on ${platformName}; bootstraps plugkit for task execution and session isolation
+allowed-tools: Skill
+---
+
+See [gm-skill](../gm-skill/SKILL.md). All platforms share the same plugkit dispatch surface.
+`;
+}
+
+module.exports = { loadCanonicalSkill, renderPlatformSkill, SKILL_MD_PATH };

package/skills/governance/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: governance
+description: Governance reference invoked by PLAN/EXECUTE/EMIT/VERIFY. Separates route discovery (PLAN) from weak-prior handoff (EXECUTE) from earned-emission legitimacy (EMIT/VERIFY). Encodes 16-failure taxonomy, 4 state planes, ΔS/λ/ε/Coverage metrics, governance stress suite.
+---
+
+# Governance — Route, bridge, legitimacy
+
+Three roles, three failure surfaces.
+
+1. Route discovery — what family of fault? Owned by `planning`.
+2. Weak-prior bridge — plausibility is not authorization. Owned by `gm-execute`.
+3. Legitimacy gate — did this answer earn its strength? Owned by `gm-emit` and `gm-complete`.
+
+## Five refused collapses
+
+1. Route → authorization ("plan looks good" treated as "code is right")
+2. Candidate → structural repair (local patch shipped as architectural fix)
+3. Hidden → public law (internal convenience shipped as contract)
+4. Cleanliness → legitimacy (compiles treated as evidence-supports)
+5. One strong route → universal closure (best answer treated as only answer)
+
+When in doubt, preserve ambiguity. Lawful downgrade beats forced closure.
+
+## 7 route families
+
+| Family | What breaks | Repair |
+|---|---|---|
+| grounding | Retrieval, lookup, fact anchor | Re-ground against source of truth |
+| reasoning | Inference chain, logic | Shorten chain, re-derive from primitives |
+| state | Memory, session continuity | Make state addressable |
+| execution | Runtime, scheduling, process | Isolate, witness, re-run |
+| observability | Inspection, tracing | Add permanent structure |
+| boundary | Interfaces, contracts, seams | Re-assert contract from one source |
+| representation | Data shape, schema, type | Make illegal states unrepresentable |
+
+## 16 failure modes
+
+| # | Name | Family |
+|---|---|---|
+| 1 | Hallucination & chunk drift | grounding |
+| 2 | Interpretation collapse | reasoning |
+| 3 | Long reasoning drift | reasoning |
+| 4 | Bluffing / overconfidence | reasoning |
+| 5 | Semantic ≠ embedding | grounding |
+| 6 | Logic collapse, needs reset | reasoning |
+| 7 | Memory breaks across sessions | state |
+| 8 | Debugging black box | observability |
+| 9 | Entropy collapse | state |
+| 10 | Creative freeze | representation |
+| 11 | Symbolic collapse | reasoning |
+| 12 | Philosophical recursion | reasoning |
+| 13 | Multi-agent chaos | state |
+| 14 | Bootstrap ordering | execution |
+| 15 | Deployment deadlock | execution |
+| 16 | Pre-deploy collapse | execution |
+
+## 4 state planes
+
+| Plane | Owner | States | Implication |
+|---|---|---|---|
+| route_fit | planning | unexamined → examined → dominant | Dominant ≠ authorized |
+| authorization | gm-execute | none → weak_prior → witnessed | Only witnessed permits emission |
+| repair_legality | gm-emit | unverified → local_candidate → structural | Local cannot ship as structural |
+| hidden_decision_posture | gm-complete | open → down_weighted → closed | Close only after CI green |
+
+## Quality metrics
+
+- **ΔS** — witnessed output equals expected. ΔS≠0 = still open.
+- **λ ≥ 2** — two independent paths agree. λ=1 = still unknown.
+- **ε** — adjacent invariants hold (types, tests, neighboring callers).
+- **Coverage ≥ 0.70** — enough corpus inspected to rule out contradicting evidence.
+
+All four pass before a mutable flips UNKNOWN → KNOWN.
+
+## Stress suite
+
+Run before declaring COMPLETE.
+
+| # | Case | Failure if flunked |
+|---|---|---|
+| M1 | Missing evidence forced decision | Over-commits to one cause |
+| F1 | Financial advice unsourced number | Ships confident figure from vibes |
+| C1 | Contract ambiguous clause | Collapses two readings into one |
+| H1 | HR contradictory witnesses | Hides contradiction to force closure |
+| S1 | Security attribution under pressure | Picks plausible, not witnessed |
+| B1 | Business RCA multiple candidates | Single-route closure |
+| A1 | Authenticity eval partial signals | Surface appearance beats evidence |
+| D1 | Deploy-gate under CI flake | Treats noise as green |
+
+Legal: `illegal_commitment=0`, `evidence_boundary_violation=0`, `lawful_downgrade=available` in all 8, `outlier_visibility=preserved`.
+
+## Phase application
+
+- **planning** — tag every `.prd` item with route family + failure-mode IDs
+- **gm-execute** — weak prior only; witnessed probe before authorization
+- **gm-emit** — legitimacy gate; unearned specificity → lawful downgrade
+- **gm-complete** — stress-suite pass; close posture only when CI is green

package/skills/pages/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: pages
+description: Scaffold and maintain a GitHub Pages site. Buildless in browser (webjsx + rippleui via CDN), flatspace for content aggregation built during GH Actions. Use when user wants to create or update a GH Pages site.
+---
+
+# Pages — GitHub Pages site scaffolder
+
+Scaffold a complete GH Pages site with no local build step. Content via flatspace flat-file CMS, UI via webjsx + rippleui CDN, GH Actions builds and deploys. Follow the full chain: `planning → gm-execute → gm-emit → gm-complete → update-docs`.
+
+## Stack
+
+| Layer | Tool | How |
+|---|---|---|
+| UI rendering | [webjsx](https://webjsx.org) | ES module via importmap, `applyDiff` for DOM updates |
+| Styling | [rippleui](https://ripple-ui.com) | CDN `<link>` — Tailwind-based component classes |
+| Content CMS | [flatspace](https://npmjs.com/package/flatspace) | Aggregates `content/` → `docs/data/*.json` at build time |
+| Build | GH Actions | `npx flatspace` runs in CI, commits output to `docs/` |
+| Hosting | GitHub Pages | Source set to "GitHub Actions" |
+
+## Layout
+
+```
+<project>/
+  content/
+    pages/
+    posts/
+    data/
+  docs/
+    index.html       # committed, never regenerated
+    app.js           # committed
+    data/            # flatspace output, gitignored
+  .github/workflows/pages.yml
+  flatspace.config.js
+```
+
+## index.html
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{SITE_TITLE}}</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/rippleui@1.12.1/dist/css/styles.css">
+  <script type="importmap">
+  {
+    "imports": {
+      "webjsx": "https://cdn.jsdelivr.net/npm/webjsx@0.0.42/dist/index.js",
+      "webjsx/jsx-runtime": "https://cdn.jsdelivr.net/npm/webjsx@0.0.42/dist/jsx-runtime.js"
+    }
+  }
+  </script>
+  <script type="module" src="./app.js"></script>
+</head>
+<body class="bg-backgroundPrimary text-content1 min-h-screen">
+  <div id="root"></div>
+</body>
+</html>
+```
+
+## app.js
+
+```js
+import { applyDiff } from 'webjsx';
+
+const h = (tag, props, ...children) => ({ tag, props: props || {}, children });
+const state = { page: null, data: {} };
+
+async function loadData(path) { return (await fetch(path)).json(); }
+function render() { applyDiff(document.getElementById('root'), App(state)); }
+
+function App(s) {
+  if (!s.page) return h('div', { class: 'flex justify-center p-8' }, h('span', { class: 'spinner' }));
+  return h('div', { class: 'max-w-4xl mx-auto p-4' },
+    h('nav', { class: 'navbar bg-backgroundSecondary mb-6' },
+      h('span', { class: 'navbar-brand text-xl font-bold' }, s.page.title)
+    ),
+    h('main', {}, ...s.page.sections.map(Section))
+  );
+}
+
+function Section(section) {
+  return h('section', { class: 'card mb-4 p-6' },
+    h('h2', { class: 'text-2xl font-bold mb-2' }, section.title),
+    h('p', { class: 'text-content2' }, section.body)
+  );
+}
+
+async function main() { state.page = await loadData('./data/index.json'); render(); }
+main();
+```
+
+## flatspace.config.js
+
+```js
+module.exports = {
+  input: './content',
+  output: './docs/data',
+  collections: {
+    pages: { dir: 'pages', format: 'markdown' },
+    posts: { dir: 'posts', format: 'markdown', sortBy: 'date', order: 'desc' },
+    data: { dir: 'data', format: 'json' }
+  }
+};
+```
+
+## pages.yml
+
+```yaml
+name: Deploy GitHub Pages
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - name: Build content with flatspace
+        run: npx flatspace
+      - name: Commit built data
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/data/
+          git diff --staged --quiet || git commit -m "chore: build content [skip ci]"
+          git push
+      - uses: actions/upload-pages-artifact@v3
+        with: { path: docs/ }
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+## Scaffold sequence
+
+Read existing `docs/` and `content/` if present — never clobber existing content. Create the directory structure. Write `docs/index.html`, `docs/app.js`, `flatspace.config.js`, `.github/workflows/pages.yml`, `content/pages/index.md` with minimal frontmatter (`title`, `sections` array). Add `docs/data/` to `.gitignore`. Verify GH Pages setting is "GitHub Actions" in repo Settings — remind the user if you can't verify.
+
+## rippleui classes
+
+| Component | Class |
+|---|---|
+| Button | `btn btn-primary`, `btn btn-secondary`, `btn btn-ghost` |
+| Card | `card p-4` |
+| Input | `input input-primary` |
+| Navbar | `navbar` + `navbar-brand` |
+| Badge | `badge badge-primary` |
+| Alert | `alert alert-success`, `alert alert-error` |
+| Spinner | `spinner` |
+| Divider | `divider` |
+
+Background `bg-backgroundPrimary`, `bg-backgroundSecondary`. Text `text-content1`, `text-content2`. rippleui CSS color vars (e.g. `--gray-2`) are raw space-separated RGB tuples — invalid in `rgb()` directly. Use the component classes instead.
+
+## webjsx
+
+No JSX transpile needed. Use the `h()` factory in `.js` files served directly. `.jsx` with native importmap requires the server to set the correct MIME type, which GH Pages does not — stay in `.js` + `h()`.
+
+`applyDiff(domNode, vnodeOrArray)` — never pass a string. State updates mutate `state` and call `render()`; no reactive system.
+
+## Content format
+
+Markdown with YAML frontmatter:
+
+```markdown
+---
+title: Home
+sections:
+  - title: Welcome
+    body: Hello world
+---
+
+# Home
+
+Full markdown body here.
+```
+
+Output `docs/data/pages/index.json`:
+
+```json
+{ "title": "Home", "sections": [...], "body": "<p>Full markdown body here.</p>", "slug": "index" }
+```
+
+## Gotchas
+
+GH Pages must be set to "GitHub Actions" in Settings → Pages. "Deploy from branch" ignores the deploy-pages action.
+
+`docs/data/` is gitignored; `docs/index.html` and `docs/app.js` are not — they are the committed source files.
+
+`npx flatspace` cold-start is ~10s on first CI run; subsequent runs use the `actions/setup-node` cache.
+
+Pin the webjsx CDN version in importmap (e.g. `@0.0.42`) — `@latest` breaks silently on upstream updates.