continuous-improvement 3.9.2 → 3.11.0

package/plugins/continuous-improvement/skills/skill-distillation/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: skill-distillation
+tier: "2"
+description: Enforces Law 7 (Learn From Every Session) of the 7 Laws of AI Agent Discipline. Distills repeated successful tool sequences into reusable draft instincts, so a pattern that worked three times becomes a captured recipe instead of being re-derived from scratch every session.
+origin: continuous-improvement
+user-invocable: true
+---
+
+# Skill Distillation — Turn Repeated Wins Into Reusable Instincts
+
+Law 7 says learn from every session. The friction harvester already learns from failures. This skill learns from the other side: when the same tool sequence keeps ending in a passing verification, that is a recipe worth keeping — not a coincidence to forget.
+
+## When to Activate
+
+- At end of session, after a successful multi-step task — check whether the pattern is worth keeping.
+- When you notice you have solved a similar problem the same way more than once.
+- During a retrospective, to mine the observation log for patterns that have proven themselves.
+
+## Core Concept
+
+Distillation walks the observation log, groups it into contiguous trajectories (split on session change or a long time gap), and keeps only the trajectories that ended in success:
+
+```
+verify-exit-0   — a Bash test/build/verify command with a non-failing output
+reflection-pass — an observation containing "verified" / "phase 4" / "verify:all green"
+```
+
+It then mines the tool-name sequences of successful trajectories for n-grams (length 3–5) that recurred **across multiple distinct sessions**. A pattern repeated only within a single session is rejected — that is repetition, not a reusable skill.
+
+## The Promotion Ladder
+
+Drafts never affect behavior until you promote them. Three explicit steps, no auto-promotion:
+
+```
+1. ci_distill_candidates           — list patterns that qualify (read-only)
+2. ci_distill_propose id=<id>      — write a DRAFT to ~/.claude/instincts/<hash>/drafts/
+                                      (placeholder body — you fill in the real recipe)
+3. <edit the draft body by hand>   — the tool sequence is evidence, not a recipe
+4. ci_distill_promote id=<id>      — promote to a live instinct at 0.5 confidence (SUGGEST)
+```
+
+The draft starts at 0.4 confidence and lives in a `drafts/` subdirectory that the instinct loader ignores. Only `ci_distill_promote` writes a live instinct, at 0.5 (SUGGEST tier) — it suggests, it does not auto-apply, until the normal reinforcement loop earns it more confidence.
+
+## Why Drafts, Not Auto-Instincts
+
+A tool sequence alone is cargo-cult evidence: `Read → Edit → Bash → Edit → Bash` is a TDD loop, but the *value* is in the preconditions and the specific steps, which the sequence does not capture. Requiring a human to edit the body before promotion is the guard against the system fabricating confident-sounding skills from coincidental call ordering.
+
+## Limitations
+
+- **Pattern detection only (no LLM in v1).** The draft body is a placeholder; you write the recipe. An optional model-assisted body draft is a planned follow-up.
+- **Tool-name granularity.** Distillation sees tool names and summaries, not full intent. Two unrelated tasks with the same call shape will look like one pattern — the human edit step resolves this.
+
+## Pairs With
+
+- **`continuous-improvement`** (core SKILL.md, Law 7) — distillation is the success-side complement to the friction-harvest failure side of the same observation log.
+- **`recall`** — before promoting, recall whether an existing instinct already covers the pattern.
+- **`tdd-workflow`** — the most common distilled pattern is the RED-GREEN-REFACTOR loop; promote it with project-specific test commands filled in.

package/plugins/continuous-improvement/skills/state-reconciliation/SKILL.md

@@ -3,6 +3,7 @@ name: state-reconciliation
 tier: "2"
 description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Pre-dispatch invariant: reconcile DB-vs-disk-vs-memory state before any unit runs, so a stale flag, missing artifact, or out-of-sync row never re-dispatches a unit that already completed or never started."
 origin: continuous-improvement
+user-invocable: false
 ---
 
 # State Reconciliation Skill

package/plugins/continuous-improvement/skills/strategic-compact/SKILL.md

@@ -3,6 +3,7 @@ name: strategic-compact
 tier: "2"
 description: Enforces Law 5 (Reflect After Every Session) of the 7 Laws of AI Agent Discipline at phase boundaries. Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
 origin: continuous-improvement
+user-invocable: false
 ---
 
 # Strategic Compact Skill

package/plugins/continuous-improvement/skills/superpowers/SKILL.md

@@ -5,7 +5,7 @@ description: "Law activator for the 7 Laws of AI Agent Discipline. Unified four-
 origin: https://github.com/obra/superpowers
 ---
 
-# Superpowers — Mandatory Agent Workflows (Five-Source Dispatcher)
+# Superpowers — Mandatory Agent Workflows (Four-Source Dispatcher)
 
 Superpowers enforces a structured development workflow. Skills activate automatically when their trigger conditions are met. This is not optional guidance — it is mandatory workflow.
 
@@ -94,6 +94,80 @@ When a task trigger fires, the dispatcher resolves to the first available skill
 
 When no installed plugin in the chain resolves, the dispatcher falls back to the inline protocols below (Test-Driven Development, Brainstorming, Plan Format, etc.) so the workflow still works on a clean install.
 
+## Companion-Preference Override
+
+The four-source routing table above is **CI-first by default**: where a CI-bundled skill (`ci:tdd-workflow`, `ci:verification-loop`, `ci:planning-with-files`, `ci:context-budget`, `ci:ralph`, `ci:learn-eval`) and a companion skill resolve the same trigger, the table lists the CI skill first and the dispatcher picks it. That is the conservative default — the CI plugin ships with the marketplace, the companions are opt-in installs, so a clean install routes to skills that are guaranteed present.
+
+Once the operator has explicitly installed a companion plugin (`superpowers@continuous-improvement`, `agent-skills@continuous-improvement`, `ruflo-swarm@continuous-improvement`, `oh-my-claudecode@continuous-improvement`), the default starts working against them: the installed companion is shadowed by the CI fallback for the same trigger. This override flag respects the operator's explicit install choice without forcing every user to relitigate routing per task.
+
+### Setting the flag
+
+Add a `continuous_improvement.companion_preference` key to `~/.claude/settings.json`:
+
+```json
+{
+  "continuous_improvement": {
+    "companion_preference": "companions-first"
+  }
+}
+```
+
+Valid values:
+
+| Value | Behavior |
+|---|---|
+| `"ci-first"` (default) | Unchanged from the routing tables above. CI-bundled skills win every chain where they appear. |
+| `"companions-first"` | For any routing row that lists both a CI skill and a companion alternative, the dispatcher reads the chain right-to-left: companion first, CI as the silent fallback if the companion plugin is not installed. CI-only rows (`ci:gateguard`, `ci:deploy-receipt`, `ci:workspace-surface-audit`, `ci:proceed-with-the-recommendation`) are unaffected because no companion exists. |
+| `"strict-companions"` | Same as `companions-first`, but the CI fallback is suppressed. If the companion plugin is not installed, the dispatcher hard-halts with the same shape as the missing-companion detection in `/superpowers` and asks the operator to install the companion or change the flag. Use when you want a guarantee that the installed companion ran, not the CI shim. |
+
+### Which rows the override affects
+
+These are the routing rows where the override changes the resolved target. Rows not listed here are CI-only or companion-only and route the same under any setting.
+
+| Trigger | `ci-first` (default) | `companions-first` |
+|---|---|---|
+| Write a failing test before code | `ci:tdd-workflow` | `superpowers:test-driven-development`, then `agent-skills:test-driven-development` |
+| Verify before declaring done | `ci:verification-loop` | `superpowers:verification-before-completion` |
+| Curate the right context window | `ci:context-budget` | `agent-skills:context-engineering` |
+| Long autonomous run with quality gates | `ci:ralph` | `oh-my-claudecode:ultrawork`, then `ci:ralph` |
+| Reflect after session, extract patterns | `ci:learn-eval` | `oh-my-claudecode:retrospective` |
+
+`superpowers:writing-plans` already wins the planning chain under both settings — it is the first entry, with `ci:planning-with-files` as the third fallback — so that row is unchanged.
+
+### Hard halts that remain regardless of the flag
+
+The override does not disable:
+
+- `gateguard` PreToolUse fact-list enforcement (Law 1, runtime layer in `hooks/gateguard.mjs`)
+- Stop-hook three-section-close discipline (Law 4 + Law 7, runtime layer in `hooks/three-section-close.mjs`)
+- Dispatcher commitments 1–6 above (subagent-driven-development default, parallel fan-out routing, TDD RED-GREEN-REFACTOR, worktree isolation, finishing-a-development-branch before push, distinct Obra/CI variants)
+- Phase 0 P-MAG in `proceed-with-the-recommendation` (Law 5 + Law 7)
+
+These are framework invariants, not routing preferences. The flag re-orders which specialist runs; it does not weaken what the framework guarantees.
+
+### Runtime enforcement
+
+The override is enforced at the PreToolUse layer by `hooks/companion-preference.mjs`. On every `Skill` tool call, the hook reads `~/.claude/settings.json` for the `companion_preference` value and:
+
+- `ci-first` (default): no-op, allow.
+- `companions-first`: emit a one-line stderr advisory naming the preferred companion; allow.
+- `strict-companions`: block the call. Reason names the companion when its plugin is installed, or the `/plugin install <plugin>@continuous-improvement` hint when it is not.
+
+The override map inside `hooks/companion-preference.mjs` stays row-aligned with the "Which rows the override affects" table above. Drift surfaces in the hook test suite, which walks the same pairs and fails on any new CI→companion row that the hook does not recognize.
+
+The hook fails open. If `~/.claude/settings.json` is missing, malformed, or unreadable, the hook emits `{ "decision": "allow" }` and exits 0. Bugs in the hook never block tool calls — they only fail to enforce.
+
+### Telemetry
+
+Every hook invocation that touches a mapped CI skill appends one JSONL line to `~/.claude/instincts/<project-hash>/companion-preference.jsonl`. The line carries `ts`, `mode`, `action`, `ci_skill`, `companion`, `plugin`, and `companion_installed`. The action enum is:
+
+- `observation` — mode is `ci-first`; this is the shadow row showing what `companions-first` would have done.
+- `advisory` — mode is `companions-first`; stderr advisory was emitted.
+- `block` — mode is `strict-companions`; companion installed; tool call blocked.
+- `block-not-installed` — mode is `strict-companions`; companion missing; blocked with install hint.
+
+Non-mapped skills and non-`Skill` tool calls write nothing. The writer wraps `appendFileSync` in try/catch — telemetry failure never changes the hook decision, preserving the fail-open invariant. The JSONL file is the evidence base for a future default-flip decision: after a 7-day window, the operator can grep / aggregate the file to see which routing rows the override fires on, how often, and whether the companion was installed at the time.
+
 ## Stacked-PR Plan Precondition (≥3 files)
 
 Any change touching three or more files — across `skills/`, `src/`, `bin/`, `commands/`, or any combination — must produce a stacked-PR plan as a precondition to the first edit landing. The 28-day usage report shows a clean correlation: sessions that opened with a stacked-PR plan landed at `fully_achieved`; sessions that began as a single big-bang multi-file edit landed at `partially_achieved` (landing-page dark theme, market-data-hub wiring, RAG misrouting). Single-concern PRs are the lever that closes that gap.
@@ -206,7 +280,7 @@ Clean separation, parallel development, easy cleanup.
 
 ## Using Superpowers
 
-Superpowers skills activate when their trigger conditions are detected. The dispatcher resolves each trigger through the five-source routing table above:
+Superpowers skills activate when their trigger conditions are detected. The dispatcher resolves each trigger through the four-source routing table above:
 
 - "Create a feature" → `superpowers:brainstorming` → `superpowers:writing-plans` → `superpowers:executing-plans`
 - "Fix this bug" → `superpowers:systematic-debugging` → `superpowers:verification-before-completion`

package/plugins/continuous-improvement/skills/token-budget-advisor/SKILL.md

@@ -38,7 +38,7 @@ Intercept the response flow to offer the user a choice about response depth **be
 
 Use the repository's canonical context-budget heuristics to estimate the prompt's token count mentally.
 
-Use the same calibration guidance as [context-budget](../context-budget/SKILL.md):
+Use the same calibration guidance as `context-budget`:
 
 - prose: `words × 1.3`
 - code-heavy or mixed/code blocks: `chars / 4`

package/plugins/continuous-improvement/skills/verification-loop/SKILL.md

@@ -23,7 +23,21 @@ Invoke this skill:
 
 Every project has its own actual invocation for build / typecheck / lint / test / security / deploy-receipt. Hardcoding `npm run build` and `npm run test` works when the project happens to use those exact scripts; for everything else (pnpm, yarn, cargo, go, mise, just, custom scripts, monorepos with workspace-scoped commands) it returns "deps not installed" or "config not found" misreads from the wrong invocation. Phase 0 runs first so Phases 1–6 never have to guess.
 
-**Resolution priority** (first match wins):
+**Run [`scripts/resolve-verify-ladder.mjs`](../scripts/resolve-verify-ladder.mjs)** at the repo root. It encodes the full four-step resolution priority and emits the fenced block below. Use `--json` for machine consumption.
+
+```
+$ node scripts/resolve-verify-ladder.mjs
+verify-ladder (resolved):
+  build:             npm run build  (sniff:package.json:scripts.build)
+  typecheck:         npm run typecheck  (sniff:package.json:scripts.typecheck)
+  lint:              npm run lint  (sniff:package.json:scripts.lint)
+  test:              npm test  (sniff:package.json:scripts.test)
+  security:          (ask operator — no marker found)
+  deploy_receipt:    (ask operator — no marker found)
+  synthetic_checks:  (ask operator — no marker found)
+```
+
+**Resolution priority** (first match wins; the script implements this — the prose is documentation):
 
 1. **`.claude/verify-ladder.json` manifest** at the repo root. Schema:
    ```json
@@ -36,24 +50,12 @@ Every project has its own actual invocation for build / typecheck / lint / test
      "deploy_receipt": "npx wrangler deployments list --json"
    }
    ```
-   Any field omitted falls through to step 2 for that field only. A field set to the literal string `null` means "skip this phase for this project."
-2. **Sniff `package.json` `scripts`** for `build`, `typecheck` or `tsc`, `lint`, `test`, `audit` or `security`. Tie-breaker when multiple scripts could match a phase: prefer `verify:<phase>` over `<phase>` over `<phase>:*`. Do NOT pick `test` when `verify:test` exists; the operator's explicit verification surface always wins over the convenience alias.
-3. **Sniff per-language toolchain files** if `package.json` is absent: `Cargo.toml` → `cargo build` / `cargo test`, `go.mod` → `go build ./...` / `go test ./...`, `pyproject.toml` → `pytest` / `ruff check`, `Gemfile` → `bundle exec rspec`, etc.
-4. **Ask the operator** if none of the above resolves the field. Do not invent.
+   Any field omitted falls through to step 2 for that field only. A field set to the literal JSON `null` means "skip this phase for this project" — the resolver records source `manifest:null`. Underscore-prefixed keys (`_doc`, `_node_example`, etc.) are ignored as documentation/examples.
+2. **Sniff `package.json` `scripts`** for `build`, `typecheck` or `tsc`, `lint`, `test`, `audit` or `security`. Tie-breaker when multiple scripts could match a phase: prefer `verify:<phase>` over `<phase>` over `<phase>:*` (wildcard tail). Do NOT pick `test` when `verify:test` exists; the operator's explicit verification surface always wins over the convenience alias.
+3. **Sniff per-language toolchain files** if `package.json` is absent: `Cargo.toml` → `cargo build` / `cargo check` / `cargo clippy` / `cargo test` / `cargo audit`, `go.mod` → `go build ./...` / `go vet ./...` / `go test ./...`, `pyproject.toml` → `pyright` / `ruff check .` / `pytest`, `Gemfile` → `bundle exec rspec` / `bundle exec rubocop`.
+4. **Ask the operator** (source `ask-operator`) if none of the above resolves the field. Do not invent.
 
-**Output the resolved ladder** as a single fenced block before running any phase, so the operator can spot a wrong resolution before it costs a misread:
-
-```
-verify-ladder (resolved):
-  build:           npm run build
-  typecheck:       npx tsc --noEmit  (sniff: package.json scripts.typecheck)
-  lint:            npm run lint
-  test:            npm test
-  security:        (skipped — no script defined)
-  deploy_receipt:  npx wrangler deployments list --json  (manifest)
-```
-
-Each row shows the resolved command + its source (manifest, sniff, or skipped). The fenced block is the contract surface — every later phase reads from this resolved ladder, never from a hardcoded fallback.
+Each row shows the resolved command + its source (`manifest`, `sniff:<file>:<key>`, `manifest:null`, or `ask-operator`). The fenced block is the contract surface — every later phase reads from this resolved ladder, never from a hardcoded fallback.
 
 A starter manifest is provided at `templates/verify-ladder.example.json`; copy it to `.claude/verify-ladder.json` and trim per project.
 
@@ -143,7 +145,11 @@ If either is `No`, the verification report goes back to the operator with the ex
 
 ### Phase 8: Deploy Receipt (auto-deploy projects only)
 
-For repos whose `verify-ladder.json` declares a `deploy_receipt` field — or whose sniff path detects an auto-deploy target (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io) — the verify is not complete until the deployed SHA matches the merge SHA and a healthcheck returns 200. Hand off to the `deploy-receipt` skill (Law 4 deploy-seam companion landed in PR #83) and treat its `Receipt status: COMPLETE` as the gate.
+For repos whose `verify-ladder.json` declares a `deploy_receipt` field — or whose sniff path detects an auto-deploy target — the verify is not complete until the deployed SHA matches the merge SHA and a healthcheck returns 200. Hand off to the `deploy-receipt` skill (Law 4 deploy-seam companion landed in PR #83) and treat its `Receipt status: COMPLETE` as the gate.
+
+**Detection.** Run [`scripts/detect-deploy-target.sh`](../scripts/detect-deploy-target.sh) at the repo root. Output is one of `railway` / `cloudflare` / `vercel` / `netlify` / `fly` / `appengine` / `apprunner` / `gha-deploy` / `none`. Anything except `none` triggers handoff to `deploy-receipt`; `none` means Phase 8 is skipped (no deploy seam exists).
+
+**SHA extraction.** For the detected provider, [`scripts/get-deployed-sha.sh <provider>`](../scripts/get-deployed-sha.sh) returns the currently-deployed SHA via the provider CLI; `--show-command <provider>` prints the pipeline shape without executing (useful for dry-runs and citation). `deploy-receipt` owns the receipt's other components (health endpoint, build artifact, on-incomplete modes) and Route B/C fallbacks.
 
 INCOMPLETE receipts move to "Immediate operator action" in the close, never to "ready". Library-only / package-published repos skip this phase entirely (no deploy seam exists).
 
@@ -158,11 +164,13 @@ Phase 8 confirms the deploy seam. Phase 9 confirms the deployed surface matches
 
 **What the runner does:**
 
+Implementation: `scripts/run-synthetic.mjs` encodes the lexical walk, interpreter map, env injection, and exit-code aggregation below. The prose is documentation, not the contract — when the two disagree, the script wins.
+
 1. List every `*.synthetic.{sh,mjs,ts,py}` file in the resolved directory in lexical order.
 2. For each file, set the input env vars: `BASE_URL` (production base from project config), `BASELINE_URL` (staging baseline from project config), `EXPECTED_SHA` (the merge SHA Phase 8 reported COMPLETE), `DEPLOY_BRANCH` (the deploy branch name), `RECEIPT_TIMESTAMP` (ISO-8601 of the receipt).
 3. Invoke the file via the right interpreter (`bash` for `.sh`, `node` for `.mjs`, `tsx` for `.ts`, `python` for `.py`). Files with unrecognized extensions are skipped with a warning.
 4. Capture stdout + stderr + exit code per file. On exit 0, the check passed. On any non-zero exit, the check failed and stdout is the operator-facing diff.
-5. Aggregate: if every file exited 0, Phase 9 is `PASS`. If any file exited non-zero, Phase 9 is `FAIL — synthetic drift on <filenames>` and the captured diffs go into the verification report verbatim (no agent re-summarization).
+5. Aggregate: if every file exited 0, Phase 9 is `PASS`. If any file exited non-zero, Phase 9 is `FAIL — synthetic drift on <filenames>` and the captured diffs go into the verification report verbatim (no agent re-summarization). Exit code 2 with zero drift (every non-pass was a config error from the check itself) surfaces as `INCOMPLETE — config error` to distinguish "gate did not run" from "gate ran and found drift".
 
 **Surfacing rule:**
 

package/plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md

@@ -3,6 +3,7 @@ name: wild-risa-balance
 tier: "2"
 description: Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline. Decision-framing lens that pairs WILD generation with RISA execution when emitting recommendation lists. Not a runtime hook.
 origin: continuous-improvement
+user-invocable: false
 ---
 
 # WILD / RISA Balance

package/plugins/continuous-improvement/skills/workspace-surface-audit/SKILL.md

@@ -74,7 +74,7 @@ Probe and record (no destructive commands; quote results inline):
 - **jq availability.** `command -v jq` (or `Get-Command jq`). When jq is missing, observation-pipeline hooks fall back to a thin schema and curl/JSON one-liners need a node/python rewrite.
 - **Case-sensitive filesystem.** Test by creating two paths differing only in case in a tempdir. NTFS (Windows) and APFS (macOS default) are case-insensitive; Linux ext4 and case-sensitive APFS are case-sensitive. Affects `CLAUDE.md` vs `claude.md` resolution and import paths.
 - **CWD baseline.** `pwd` (or `Get-Location`) recorded at session start. `tsc`, build scripts, and some test runners change CWD as a side effect; subsequent commands run from the wrong directory return "deps not installed" or "config not found" misreads.
-- **Parallel-actor expectation.** Document whether a second Claude / Codex / Maulana session may operate on the same working tree. If yes, the `gateguard` Parallel-Actor Gate must baseline `git rev-parse HEAD` + `git status --porcelain` + upstream before the first mutation, and re-check on every subsequent mutation.
+- **Parallel-actor expectation.** Document whether a second Claude / Codex / Maulana session may operate on the same working tree. If yes, the `gateguard` Parallel-Actor Gate uses [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) to produce a single JSON envelope (`{head, upstream, dirty, root, branch}`) for the baseline and the divergence check. This skill records whether parallel-actor is expected; gateguard owns the runtime mechanics, so the audit doesn't restate the git-command triple.
 
 Output the recorded grain as a single fenced block so it survives context compaction and any later phase can reference it without re-probing:
 

package/plugins/continuous-improvement/skills/worktree-safety/SKILL.md

@@ -3,6 +3,7 @@ name: worktree-safety
 tier: "2"
 description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Pre-dispatch invariant: validate worktree root before any source-writing tool call. Catches missing .git, fallback path-only creation, stale leases, foreign-session ownership, and non-worktree git operations before they corrupt history."
 origin: continuous-improvement
+user-invocable: false
 ---
 
 # Worktree Safety Skill
@@ -31,10 +32,10 @@ The continuous-improvement repo runs on Windows + Git Bash with `autocrlf=true`
 
 Before any source-writing call, verify all five. Fail closed on any miss.
 
-1. **Root validity** — `git rev-parse --show-toplevel` resolves; the resolved path matches CWD after symlink-safe canonicalization.
+1. **Root validity** — `git rev-parse --show-toplevel` resolves; the resolved path matches CWD after symlink-safe canonicalization. The `root` field of [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) carries the canonicalized root, and its non-zero exit on `{"error":"not-a-git-repo"}` is itself the fail-closed signal — no second probe needed.
 2. **`.git` presence** — `.git` exists (file pointer for worktrees, directory for primary checkout). A missing or unreadable `.git` is an immediate stop.
 3. **Worktree registration** — `git worktree list` includes the resolved root with no `prunable` flag. Prunable worktrees can be deleted by another process at any moment.
-4. **Branch alignment** — current branch matches the lease ledger; `HEAD` is not detached unless the unit explicitly asked for detached state.
+4. **Branch alignment** — current branch matches the lease ledger; `HEAD` is not detached unless the unit explicitly asked for detached state. The snapshot script's `branch` field carries either the branch name or the literal `"detached"`, so detached-state is observable without a second probe.
 5. **Lease ownership** — the session ID in `.git/worktrees/<name>/lease` (or your equivalent ledger) matches this session. Stale or foreign leases block the call.
 
 Output a single fenced block before any source-writing dispatch:

package/plugins/expert.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.9.2",
+  "version": "3.11.0",
   "mode": "expert",
   "description": "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay disciplined and learnings survive context resets.",
   "tools": [
@@ -16,6 +16,10 @@
       "name": "ci_reflect",
       "what": "Reflect on what you did this session"
     },
+    {
+      "name": "ci_gateguard_clear",
+      "what": "Clear the GateGuard gate for files after presenting facts"
+    },
     {
       "name": "ci_reinforce",
       "what": "Accept or reject instinct suggestions to tune confidence"
@@ -51,6 +55,26 @@
     {
       "name": "ci_load_pack",
       "what": "Load starter instinct packs (react, python, go) into the current project"
+    },
+    {
+      "name": "ci_goal_check",
+      "what": "Detect when a session has drifted from its stated goal"
+    },
+    {
+      "name": "ci_recall",
+      "what": "Search past sessions for relevant prior activity (episodic recall)"
+    },
+    {
+      "name": "ci_distill_candidates",
+      "what": "Find repeated successful tool sequences worth turning into skills"
+    },
+    {
+      "name": "ci_distill_propose",
+      "what": "Draft a reusable instinct from a repeated successful pattern"
+    },
+    {
+      "name": "ci_distill_promote",
+      "what": "Promote an edited draft into a live instinct"
     }
   ],
   "setup": {
@@ -83,9 +107,10 @@
     "included": [
       "PreToolUse",
       "PostToolUse",
+      "UserPromptSubmit",
       "SessionStart",
       "SessionEnd"
     ],
-    "description": "Full hook suite: observation capture + session-level instinct loading and auto-reflection."
+    "description": "Full hook suite: observation capture, lazy prompt routing, session-level instinct loading, and auto-reflection."
   }
 }

package/skills/README.md

@@ -44,6 +44,9 @@ These ship in the same plugin bundle regardless of mode and are available the mo
 |-------|--------------|--------|
 | `ralph` | Autonomous loop that executes a PRD story-by-story with quality checks between iterations | [snarktank/ralph](https://github.com/snarktank/ralph) |
 | `superpowers` | **Law activator.** Routes tasks to the correct Law-aligned specialist (brainstorming → Law 2, writing-plans → Law 2, TDD → Law 3+4, verification-before-completion → Law 4, etc.) so the right discipline fires automatically. Not a peer skill — a dispatcher for the others. | [obra/superpowers](https://github.com/obra/superpowers) |
+| `handoff` | One-shot session compaction into an `mktemp`-backed markdown brief a fresh agent can pick up cold — goal, current state, decisions, open questions, next step, skills to load | [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/in-progress/handoff/SKILL.md) |
+| `grill-me` | Pre-execution alignment interrogation — interview the user one question at a time, walking every branch of the decision tree with a recommended answer for each, until the spec is shippable cold to a fresh agent | [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) |
+| `grill-with-docs` | Grilling-with-persistent-outcomes — challenges the plan against the existing `CONTEXT.md` glossary, sharpens fuzzy terminology, cross-references user statements against code, and updates `CONTEXT.md` + `docs/adr/` inline as decisions crystallise. Bundles a CONTEXT.md format spec and an ADR format spec as appendices | [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md) |
 | `workspace-surface-audit` | Audits the active repo, MCP servers, plugins, and env, then recommends high-value skills/workflows | continuous-improvement |
 
 ## How they get to your machine

package/skills/audit.md

@@ -0,0 +1,73 @@
+---
+name: audit
+tier: "2"
+description: Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Audits a window of recent commits for real defects, confirms each finding before touching code so false positives die first, and checks every surface a change touches — so 'looks done' is never mistaken for 'is correct'.
+origin: continuous-improvement
+user-invocable: true
+---
+
+# Audit — Confirm Recent Commits Before You Trust Them
+
+Law 4 says verify before reporting. A merged commit with green CI is a claim, not a proof. This skill runs the audit-driven loop: take a window of recent commits, hunt for real defects, prove each one before touching code, fix on a branch, and verify every surface the fix touches before declaring the audit clean.
+
+## When to Activate
+
+- After a batch of commits lands ("audit today's commits"), especially on money-handling, auth, or state-mutating code.
+- When a feature shipped across several surfaces (backend, frontend, admin, migration) and you suspect one was missed.
+- After a large refactor or a conflicted merge — exactly when individually-correct functions can still cancel each other out.
+- Before a release cut, as the last gate over "everything claimed done."
+
+## The Loop
+
+```
+1. Scope    — pick the commit window (e.g. main since last release, or HEAD~N..HEAD)
+2. Find     — hunt for real defects, one concern per pass
+3. Confirm  — prove each finding against the actual code; false positives die here
+4. Fix      — one branch, one concern per commit, smallest diff that closes the defect
+5. Verify   — exercise EVERY surface the fix touches, not just the one you edited
+6. Report   — confirmed defects, dismissed false positives, and no-op items, with evidence
+```
+
+## Find: One Concern Per Pass
+
+Run the find pass once per dimension rather than one undifferentiated sweep. The dimensions that have actually caught defects in this codebase's domain:
+
+- **Value/economy drift** — a constant duplicated across surfaces (a prize array hardcoded in the frontend while the backend reads an endpoint; a cap defined twice). Grep both sides; compare.
+- **Concurrency** — a read-modify-write with no guard, a settlement that is not idempotent, a row that can get stuck between two states.
+- **Surface coverage** — a change that updated the backend but not the admin filter or the client cache that mirrors it.
+- **Type/contract** — a payload shape that one side narrowed and the other did not.
+
+For a thorough audit, use the `superpowers:dispatching-parallel-agents` skill to fan these out as parallel reviewers — each blind to the others — then merge findings.
+
+## Confirm Before Fixing
+
+A finding is a hypothesis until proven against the code. Before writing any fix:
+
+- Read the actual lines, not the diff summary. Confirm the defect reproduces in the current tree.
+- State why it is real in one sentence. If you cannot, it is a false positive — record it as dismissed and move on.
+- Prefer a failing test that reproduces the defect, then fix to green (`tdd-workflow`).
+
+Defaulting findings to "real" is how plausible-but-wrong fixes get shipped. Default to skeptical; make the code prove the bug.
+
+## Verify Every Surface the Fix Touches
+
+The recurring failure this skill exists to stop: a fix that the agent claims is done while the frontend array, admin filter, or cached copy still carries the old value. This is the functional-surface check `audit` gates before reporting — not the build/test/lint ladder itself (that is `verification-loop`). Before reporting an item closed:
+
+- List every surface the changed value or behavior touches (backend, frontend, admin, migration, cache, generated artifact).
+- Re-check each surface yourself — do not assume one auto-updates from another.
+- On each surface, run the resolved `verification-loop` ladder against the code that implements it, not a manual spot-check.
+
+This applies the `verification-loop` (Law 4) and `goal-monitor` (Law 2) discipline to someone else's recent work.
+
+## Report Honestly
+
+Three buckets, with evidence: **confirmed** (defect + fix + the check that proves it), **dismissed** (looked like a bug, here is why it is not), **no-op** (in scope but nothing to change). Silence on a surface is not a pass.
+
+## Pairs With
+
+- **`code-review`** / **`security-review`** — the dimension passes; `audit` is the loop that runs them over a commit window and acts on the output.
+- **`superpowers:dispatching-parallel-agents`** — fan the find pass out across dimensions, then verify each finding adversarially.
+- **`verification-loop`** (Law 4) — the build/test/lint ladder `audit` runs on each surface before a finding is closed.
+- **`goal-monitor`** (Law 2) — confirms the fix still serves the task goal, not just that it compiles.
+- **`recall`** (Law 1) — before confirming a finding, recall whether this exact defect was hit and fixed before.
+- **`reconcile`** (Law 1) — when the audit ends in a fix, reconcile the branch state before pushing.

package/skills/deploy-receipt.md

@@ -3,6 +3,7 @@ name: deploy-receipt
 tier: "1"
 description: Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline at the deploy seam. A merge into a branch that auto-deploys is not "done" until the deploy provider reports the merged commit SHA running and a healthcheck endpoint returns 200. Companion to the vendored `finishing-a-development-branch` skill — does not replace it, runs after it for projects on Railway, Cloudflare Workers, Vercel, Netlify, Fly.io, or any other auto-deploy target.
 origin: https://github.com/naimkatiman/continuous-improvement
+disable-model-invocation: true
 ---
 
 # Deploy Receipt — Closing the Merge-to-Production Gap
@@ -20,14 +21,7 @@ This skill defines the receipt that closes that gap, without modifying the vendo
 Activate when ALL of the following are true:
 
 1. A merge into the deploy branch (typically `main` or `master`) has just landed
-2. The repo declares an auto-deploy target — detect via any of:
-   - `railway.toml`, `railway.json`, or `RAILWAY_*` env vars in `.env.example`
-   - `wrangler.toml` / `wrangler.jsonc` (Cloudflare Workers)
-   - `vercel.json` or `.vercel/` directory
-   - `netlify.toml`
-   - `fly.toml`
-   - `app.yaml` (App Engine), `apprunner.yaml` (App Runner)
-   - GitHub Actions workflow with `deploy:` job triggered on push to the deploy branch
+2. [`scripts/detect-deploy-target.sh`](../scripts/detect-deploy-target.sh) returns a value other than `none` at the repo root. The script encodes the full file-marker table — `railway.toml` / `railway.json` → `railway`, `wrangler.toml` / `wrangler.jsonc` → `cloudflare`, `vercel.json` / `.vercel/` → `vercel`, `netlify.toml` → `netlify`, `fly.toml` → `fly`, `app.yaml` → `appengine`, `apprunner.yaml` → `apprunner`, `.github/workflows/*.yml` with a `deploy:` job → `gha-deploy`. First match wins, in that order. The script is the source of truth; the file list above is documentation
 3. `finishing-a-development-branch` has reported "merged" — not "PR opened", not "review pending"
 
 Do NOT activate when:
@@ -51,17 +45,19 @@ The skill is provider-aware but never hardcodes a specific API key or token shap
 
 ### Route A — Provider CLI (preferred when authenticated)
 
-The CLI is the highest-fidelity source.
+The CLI is the highest-fidelity source. Run [`scripts/get-deployed-sha.sh <provider>`](../scripts/get-deployed-sha.sh) — the script owns the per-provider pipeline (CLI + jq filter) and prints just the SHA on stdout. Inspect the pipeline shape without executing via `bash scripts/get-deployed-sha.sh --show-command <provider>`.
 
-| Provider | Command shape | Receipt extraction |
-|---|---|---|
-| Railway | `railway status --json` | `.deployments[0].meta.commitHash` |
-| Cloudflare Workers | `wrangler deployments list --json` | `[0].metadata.deployment_trigger.metadata.commit_hash` |
-| Vercel | `vercel inspect <url> --json` | `.gitSource.sha` |
-| Netlify | `netlify api listSiteDeploys --data='{"site_id":"<id>"}'` | `[0].commit_ref` |
-| Fly.io | `fly releases --json` | `[0].commit_sha` |
+Provider-to-pipeline map (cited from the script, not redefined here):
 
-If the CLI is not installed or not authenticated in this session, fall through to Route B. Do NOT prompt the operator to install the CLI mid-session — that is a drive-by.
+| Provider value | CLI |
+|---|---|
+| `railway` | `railway` |
+| `cloudflare` | `wrangler` |
+| `vercel` | `vercel` |
+| `netlify` | `netlify` |
+| `fly` | `fly` |
+
+Exit codes from the script: `0` on success (SHA printed), `2` on missing/unknown provider (usage error), `3` when the required CLI is not installed locally — that is the fall-through signal to Route B, not a hard failure. Do NOT prompt the operator to install the CLI mid-session — that is a drive-by.
 
 ### Route B — GitHub Deployments API (works for any provider that posts back)
 

package/skills/gateguard.md

@@ -3,6 +3,7 @@ name: gateguard
 tier: "1"
 description: Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Fact-forcing gate that blocks Edit/Write/Bash (including MultiEdit) and demands concrete investigation (importers, data schemas, user instruction) before allowing the action. Measurably improves output quality by +2.25 points vs ungated agents.
 origin: community
+user-invocable: false
 ---
 
 # GateGuard — Fact-Forcing Pre-Action Gate
@@ -96,30 +97,37 @@ A second Claude/Codex/Maulana session can be running on the same host and the sa
 
 **On the first Edit / Write / mutating Bash of a session:**
 
+Run [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) and quote its JSON envelope verbatim. Example output:
+
+```
+{"head":"966ce51","upstream":"966ce51","dirty":0,"root":"/path/to/repo","branch":"main"}
 ```
-Baseline these three values and quote them in your response:
 
-1. `git rev-parse HEAD` — record the commit you started on
-2. `git rev-parse @{u}` (if branch tracks an upstream) — record where origin was
-3. `git status --porcelain` — record the working tree state
+Field meanings:
 
-If any value is "unknown" (detached HEAD, no upstream, untracked-only tree),
-say so explicitly. Do not proceed past the baseline silently.
-```
+1. `head` — short SHA of the commit you started on
+2. `upstream` — short SHA of `@{u}` if the branch tracks an upstream, else the literal `"none"`
+3. `dirty` — integer count of `git status --porcelain` lines (0 == clean)
+4. `root` — repo root path from `git rev-parse --show-toplevel`
+5. `branch` — current branch name, or the literal `"detached"`
+
+If `upstream` is `"none"` or `branch` is `"detached"`, say so explicitly. Do not proceed past the baseline silently. If the script exits non-zero (output is `{"error":"not-a-git-repo"}`), HALT — the harness is not running in a git checkout and no mutation should land here.
 
 **On every subsequent Edit / Write / mutating Bash, before allowing the action:**
 
-```
-Re-check the three baselines against current state:
+Re-run [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) and diff against the baseline:
 
-1. `git rev-parse HEAD` — has it advanced past your baseline without your commits?
-2. `git rev-parse @{u}` — did upstream move while you worked?
-3. `git status --porcelain` — are there modifications you did not introduce?
+1. `head` — has it advanced past your baseline without your commits?
+2. `upstream` — did upstream move while you worked?
+3. `dirty` — are there modifications you did not introduce (count increased)?
+4. `branch` — did the working tree switch branches under you?
 
 If ANY of those drifted from baseline, HALT. Emit:
-"Parallel-actor divergence: <field> moved from <baseline> to <current>.
+
+```
+Parallel-actor divergence: <field> moved from <baseline> to <current>.
 Working tree may belong to another session. Stop, surface to operator,
-get clearance before next mutation."
+get clearance before next mutation.
 ```
 
 This gate is what catches the squash-merge / ahead-of-origin trap recorded in the operator's memory (`feedback_pre_branch_check.md`, `feedback_parallel_actor.md`) — both classes of failure occurred because a baseline was never captured at session start.
@@ -132,14 +140,25 @@ This gate is what catches the squash-merge / ahead-of-origin trap recorded in th
 
 Smoke-test the runtime gate after install: ask Claude to write a throwaway file with no research first. The hook should return a `block` decision with a fact-list reason; Claude should pause rather than write.
 
+### Clearing the gate (after presenting the facts)
+
+The block reason prints the exact `gateguard-session.json` path and the clearance commands. Clearance matches a file regardless of drive-letter case or path separator (`d:\x` and `D:/x` resolve to the same key), so it no longer matters whether the hook and the helper spelled the project root differently. Any one of these allows the retry:
+
+- **MCP tool** (beginner + expert): `ci_gateguard_clear` with `file_paths: ["<path>", …]`.
+- **CLI** (Bash, never gated): `node "${CLAUDE_PLUGIN_ROOT}/bin/gateguard-clear.mjs" "<path>"`; add `--state <gateguard-session.json>` to write the exact file the block reason printed.
+- **Manual**: append each path to `cleared_files` in the printed `gateguard-session.json` via a non-destructive Bash write.
+
+The inline `_gateguard_facts_presented: true` retry still works on harnesses that forward unknown tool params, but Claude Code's strict tool schema (`additionalProperties: false`) rejects it with `InputValidationError` — use one of the above on Claude Code.
+
 ### V1 honest limitations (not mitigated, documented)
 
-- **Honor system.** Once the agent flips `_gateguard_facts_presented: true` in `tool_input`, the hook can't verify the investigation actually happened. The 50-file cap bounds damage from stuck loops or rogue agents.
+- **Honor system.** Clearance is recorded by `ci_gateguard_clear`, the `gateguard-clear.mjs` CLI, a manual state-file write, or the inline `_gateguard_facts_presented` flag where the harness allows it (see "Clearing the gate" above). The hook can't verify the investigation actually happened; the 50-file cap bounds damage from stuck loops or rogue agents.
 - **State-file deletion.** `rm`-ing the session state resets every gate. Acceptable because the session itself is the trust boundary.
 - **Parallel-hook race.** Two simultaneous hook invocations can race the read+write of the state file. Acceptable trade-off vs Windows atomic-rename complexity.
-- **MultiEdit V1.** Currently gates on `edits[0].file_path` only. Per-file batching is a TODO.
 
-All four documented in `src/hooks/gateguard.mts` and `src/lib/gateguard-state.mts` headers.
+**MultiEdit per-file gating.** The hook clears and checks every `edits[]` path individually, so a mixed-clearance batch blocks until *all* edited files are cleared or facts are presented. The block reason now names the whole batch, not just the first uncleared path.
+
+These behaviors are documented in `src/hooks/gateguard.mts` and `src/lib/gateguard-state.mts` headers.
 
 ### Future: third-party `gateguard-ai` package