continuous-improvement 3.9.2 → 3.12.3

package/plugins/continuous-improvement/skills/README.md

@@ -19,12 +19,20 @@ skill set on disk.
 - `deploy-receipt` — 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.
 - `gateguard` — 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.
 - `para-memory-files` — Enforces Law 5 (Reflect After Every Session) and Law 7 (Learn From Every Session) of the 7 Laws of AI Agent Discipline by giving the agent a durable file-based memory it can read on resume and write at session end. File-based memory system using Tiago Forte's PARA method. Use this skill whenever you need to store, retrieve, update, or organize knowledge across sessions. Covers three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts, (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also handles planning files, memory decay, weekly synthesis, and recall via qmd. Trigger on any memory operation: saving facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, or managing plans.
+- `recall` — Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Makes past sessions first-class research material by searching the observation log with BM25 ranking, so 'have I hit this before?' is answerable before re-deriving a fix or repeating a mistake.
 - `tdd-workflow` — Enforces Law 3 (One Thing at a Time) and Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
 - `verification-loop` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. A comprehensive verification system for agent coding sessions covering build, types, lint, tests, security, and diff with a PASS/FAIL report.
 
 ## Tier 2 — expert-mode add-ons
+- `audit` — 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'.
+- `goal-monitor` — 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.
+- `grill-me` — 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.
+- `grill-with-docs` — Enforces Law 1 (Research Before Executing) and Law 7 (Learn From Every Session) of the 7 Laws of AI Agent Discipline. Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates CONTEXT.md + ADRs inline as decisions crystallise. Ported from mattpocock/skills under MIT.
+- `handoff` — Enforces Law 5 (Reflect After Every Session) of the 7 Laws of AI Agent Discipline. Compact the current conversation into a handoff document for another agent to pick up. Ported from mattpocock/skills under MIT.
+- `reconcile` — Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Establishes git ground truth — branch, status, stashes, worktrees, ahead/behind — before any mutation, halts on protected or destructive operations, and verifies a push actually landed instead of assuming it did.
 - `recovery-classification` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. After any failure in the verification ladder or auto-loop, classify the failure class before retrying — provider, tool-schema, deterministic-policy, git, worktree, runtime — so retry-vs-pause-vs-self-heal-vs-stop is an intentional decision, not a generic 'try again'.
 - `safety-guard` — Enforces Law 3 (One Thing at a Time) of the 7 Laws of AI Agent Discipline by scoping edits to a directory and blocking destructive shell commands. Use this skill to prevent destructive operations when working on production systems or running agents autonomously.
+- `skill-distillation` — 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.
 - `state-reconciliation` — 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.
 - `strategic-compact` — 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.
 - `token-budget-advisor` — Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline by making token-budget tradeoffs explicit before the response is composed. Offers the user an informed choice about how much response depth to consume before answering. Use this skill when the user explicitly wants to control response length, depth, or token budget. TRIGGER when: "token budget", "token count", "token usage", "token limit", "response length", "answer depth", "short version", "brief answer", "detailed answer", "exhaustive answer", "respuesta corta vs larga", "cuántos tokens", "ahorrar tokens", "responde al 50%", "dame la versión corta", "quiero controlar cuánto usas", or clear variants where the user is explicitly asking to control answer size or depth. DO NOT TRIGGER when: user has already specified a level in the current session (maintain it), the request is clearly a one-word answer, or "token" refers to auth/session/payment tokens rather than response size.

package/plugins/continuous-improvement/skills/audit/SKILL.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/plugins/continuous-improvement/skills/continuous-improvement/SKILL.md

@@ -6,7 +6,7 @@ description: "Install structured self-improvement loops with instinct-based lear
 
 # continuous-improvement
 
-You follow the continuous-improvement framework. These 7 laws govern all your work.
+You follow the continuous-improvement framework. These 7 laws make every task sharper — each is a capability that compounds: research deeper, plan tighter, verify with evidence, reflect, and learn so the same lesson is never re-taught.
 
 ## Law 1: Research Before Executing
 

package/plugins/continuous-improvement/skills/deploy-receipt/SKILL.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/plugins/continuous-improvement/skills/gateguard/SKILL.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/plugins/continuous-improvement/skills/goal-monitor/SKILL.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/plugins/continuous-improvement/skills/grill-me/SKILL.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.