continuous-improvement 3.9.2 → 3.12.3

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,8 +1,8 @@
 {
   "name": "continuous-improvement",
-  "version": "3.9.2",
+  "version": "3.12.3",
   "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.",
+  "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 sharp and learnings survive context resets.",
   "tools": [
     {
       "name": "ci_status",
@@ -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
 

package/skills/goal-monitor.md

@@ -0,0 +1,81 @@
+---
+name: goal-monitor
+tier: "2"
+description: Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline. Detects when a session has drifted away from its stated goal by scoring recent tool activity against the '## Goal' section of task_plan.md, so drift is caught mid-session instead of at end-of-session reflection.
+origin: continuous-improvement
+user-invocable: true
+---
+
+# Goal Monitor — Continuous Drift Detection
+
+A "Clear Goal" discipline: a stated goal is only useful if something keeps checking the work against it. `task_plan.md` captures the goal once; this skill turns it into a recurring check so a session that has quietly wandered off into unrelated files surfaces the drift while there is still budget to course-correct.
+
+## When to Activate
+
+- After a long stretch of edits, before claiming progress on the original goal.
+- When you suspect the work has sprawled across unrelated areas of the codebase.
+- Before a checkpoint or handoff, to confirm the session stayed on its stated goal.
+- Any time the goal in `task_plan.md` and the actual tool activity might have diverged.
+
+## Core Concept
+
+Law 2 says the plan is sacred. But "sacred" is hollow if nothing measures adherence. Goal Monitor scores the most recent observations against the goal and reports one of three states:
+
+```
+ON GOAL  — recent activity relates to the goal (score >= threshold)
+DRIFT    — most recent activity is unrelated, or touched forbidden paths
+NO DATA  — not enough observations in the window yet
+```
+
+The score is the fraction of recent observations whose tool name, input, or output references a goal keyword — or whose edited path falls under a goal-scope glob.
+
+## Goal Source
+
+The check reads, in order:
+
+1. `task_plan.md` in the project root (seeded by `ci_plan_init` / `/planning-with-files`).
+2. `~/.claude/instincts/<project-hash>/goal.md` (fallback for non-repo sessions).
+3. An explicit `goal_file` argument, if provided.
+
+The plan needs a `## Goal` section. Two optional sections sharpen the signal:
+
+```markdown
+## Goal
+Implement OAuth login with JWT session tokens for the auth service.
+
+## Goal Keywords
+oauth, jwt, login, session
+
+## Goal Scope
+paths: src/auth/**, test/auth/**
+forbidden: src/marketing/**
+```
+
+When `## Goal Keywords` is absent, keywords are auto-extracted from the goal prose (stopwords and short tokens dropped). `## Goal Scope` is optional: `paths` globs count as on-goal matches; `forbidden` globs are a hard drift signal even when keywords also match.
+
+## How to Invoke
+
+The check is exposed as the `ci_goal_check` MCP tool (expert mode) and the `/goal-check` slash command:
+
+```
+ci_goal_check                      # score the last 30 observations against task_plan.md
+ci_goal_check limit=50             # widen the window
+ci_goal_check goal_file=docs/x.md  # score against a specific plan file
+```
+
+## Acting on the Result
+
+- **ON GOAL** — proceed; the plan and the work agree.
+- **DRIFT** — stop and decide explicitly: either steer back to the goal, or, if the goal has legitimately changed, update the `## Goal` section so the plan stays the single source of truth. Do not silently let the work and the plan disagree — that is exactly the Law 2 violation this skill exists to catch.
+- **NO DATA** — keep working; the observation window is still filling.
+
+## Limitations
+
+- Keyword scoring is lexical, not semantic: a goal that says "login" will not match activity that only ever says "authentication". Add synonyms to `## Goal Keywords` when vocabulary diverges.
+- A deliberately broad goal ("refactor the whole repo") will score nearly everything as on-goal. Use `## Goal Scope` to add precision when the goal is narrow.
+
+## Pairs With
+
+- **`proceed-with-the-recommendation`** (orchestrator, Law 2) — run a goal check at phase boundaries to confirm the plan still matches the work.
+- **`para-memory-files`** / planning-with-files — the `## Goal` section this skill reads is the same one those workflows write.
+- **`strategic-compact`** — before compacting a long session, a goal check confirms what the session was actually about.

package/skills/grill-me.md

@@ -0,0 +1,66 @@
+---
+name: grill-me
+tier: "2"
+description: Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Interview the user relentlessly about a plan or design until shared understanding is reached, resolving every branch of the decision tree before any code is written. Ported from mattpocock/skills under MIT.
+origin: https://github.com/mattpocock/skills
+---
+
+# /grill-me — Interrogate the plan before executing it
+
+Ported verbatim in behavior from [mattpocock/skills `productivity/grill-me`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) (MIT, © 2026 Matt Pocock). Cold-storage snapshot at [`third-party/mattpocock-skills/skills/productivity/grill-me/SKILL.md`](../third-party/mattpocock-skills/skills/productivity/grill-me/SKILL.md); SHA pin in [`third-party/MANIFEST.md`](../third-party/MANIFEST.md).
+
+## What this skill does
+
+Interview the user relentlessly about every aspect of the plan until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide a recommended answer.
+
+Ask questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## When to fire it
+
+- The user has just stated a goal at a high level ("add auth", "speed up the API") with no spec underneath.
+- A `/proceed-with-the-recommendation` walk is about to start but the recommendation list itself is ambiguous about scope or success criteria.
+- An RFC, PRD, or plan doc is being drafted and the user wants pressure on the assumptions before writing it.
+- The user types "grill me", "stress-test this plan", or "interview me about X".
+- `gateguard` is firing because the agent does not have enough grounding to proceed safely on a Write/Edit/Bash — alignment is missing, not just facts.
+
+## How it differs from `gateguard`
+
+`gateguard` is a tool-boundary gate that blocks Edit / Write / Bash until the agent provides concrete investigation (importers, schemas, user instruction). It catches the case where the agent thinks it knows enough to mutate state. `grill-me` is the conversational layer one floor above: it surfaces the missing decisions before any tool call would even be attempted. They compose:
+
+| Gap | Caught by |
+|---|---|
+| Agent has no spec, no plan — about to invent one | `grill-me` |
+| Agent has a plan but specific branches are under-specified | `grill-me` |
+| Agent is about to Edit / Write / Bash without grounding | `gateguard` |
+| Plan exists, grounded, but the implementation drifts | `verification-loop`, `tdd-workflow` |
+
+## Interview discipline
+
+Five rules the agent should hold while grilling:
+
+1. **One question at a time.** Multi-question turns let the user skim and answer the easy ones. Force depth on each branch.
+2. **Always recommend.** Every question carries a "my answer would be X because Y" so the user can confirm, override, or expose a third option you hadn't considered.
+3. **Explore before asking.** If `grep` / `ls` / a quick read can answer the question, do that first. Do not waste user attention on questions the codebase already answers.
+4. **Walk the tree, do not jump.** Resolve dependencies in order — do not ask about deployment if you have not pinned the data model yet.
+5. **Stop when the spec is shippable.** The end state is a plan a fresh agent could execute cold, not an endless interview. When the next agent could pick up the doc and run, stop.
+
+## How it fits the 7 Laws
+
+| Law | Role of this skill |
+|---|---|
+| Law 1 (Research Before Executing) | Pre-execution interrogation closes the alignment gap that misaligns the agent with the user before any tool call. |
+| Law 2 (Plan Is Sacred) | The interview produces a plan grounded in real decisions, not invented defaults. |
+| Law 4 (Verify Before Reporting) | Every recommended answer is a falsifiable claim the user can correct in the moment. |
+
+## Companion / alternative skills
+
+- [`gateguard`](./gateguard.md) — tool-boundary gate; blocks Edit / Write / Bash until grounding is presented. Fires after `grill-me` has aligned the spec.
+- [`workspace-surface-audit`](./workspace-surface-audit.md) — Law 1 surface audit; inventory of MCP servers, plugins, env, hooks. Use when the missing context is "what is available in this repo" rather than "what should we build."
+- [`superpowers:brainstorming`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) — Socratic design refinement. Use for open-ended ideation; use `grill-me` once the idea is committed and needs hardening.
+- [`handoff`](./handoff.md) — session-end compaction. Pair with `grill-me`: grill at start, handoff at end.
+
+## Attribution
+
+This skill is a port of [mattpocock/skills `productivity/grill-me`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md). MIT-licensed upstream, MIT-licensed here. See [`third-party/mattpocock-skills/LICENSE`](../third-party/mattpocock-skills/LICENSE) for the verbatim license and [`third-party/mattpocock-skills/OUR_NOTES.md`](../third-party/mattpocock-skills/OUR_NOTES.md) for the vendoring rationale and drift radar.