continuous-improvement 3.9.2 → 3.11.0

package/plugins/continuous-improvement/bin/mcp-server.mjs

@@ -11,13 +11,17 @@
  *   node bin/mcp-server.mjs --mode beginner  # explicit beginner
  */
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { PACKAGE_NAME, VERSION, getToolDefinitions, isPluginMode, } from "../lib/plugin-metadata.mjs";
+import { formatDriftReport, parseGoalFromPlan, scoreObservations, } from "../lib/goal-state.mjs";
+import { buildIndex, formatRecallHits, parseSince, query as queryRecall, } from "../lib/recall-index.mjs";
+import { draftFromCandidate, extractTrajectories, findCandidates, formatCandidates, serializeDraft, } from "../lib/skill-distill.mjs";
+import { MAX_CLEARED_FILES, clearFiles, resolveSessionDir, } from "../lib/gateguard-state.mjs";
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
@@ -32,6 +36,12 @@ function getString(value, fallback = "") {
 function getNumber(value, fallback = 0) {
     return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+// Draft ids are derived from slugified tool n-grams (src/lib/skill-distill.mts)
+// and are joined into a filesystem path, so a caller-supplied id must match the
+// safe shape before it is used to read/write/delete a draft file.
+function isSafeDraftId(id) {
+    return /^draft-[a-z0-9-]+$/.test(id);
+}
 function getBoolean(value, fallback = false) {
     return typeof value === "boolean" ? value : fallback;
 }
@@ -174,6 +184,12 @@ function countObservations(projectHash) {
     }
 }
 function getRecentObservations(projectHash, limit = 50) {
+    // Clamp a non-positive or non-integer limit to the default. slice(-0) would
+    // otherwise return the ENTIRE history (the limit:0 boundary), and a negative
+    // limit would drop rows from the front instead of taking the tail. ci_goal_check
+    // pre-rejects bad limits with a clear error(); this guards ci_observations and
+    // any other caller that passes a user-supplied limit straight through.
+    const cappedLimit = Number.isInteger(limit) && limit > 0 ? limit : 50;
     const observationsFile = join(INSTINCTS_DIR, projectHash, "observations.jsonl");
     if (!existsSync(observationsFile)) {
         return [];
@@ -182,7 +198,7 @@ function getRecentObservations(projectHash, limit = 50) {
         const lines = readFileSync(observationsFile, "utf8")
             .split("\n")
             .filter((line) => line.trim().length > 0);
-        return lines.slice(-limit).flatMap((line) => {
+        return lines.slice(-cappedLimit).flatMap((line) => {
             try {
                 return [JSON.parse(line)];
             }
@@ -195,6 +211,16 @@ function getRecentObservations(projectHash, limit = 50) {
         return [];
     }
 }
+function readDistillObservations(projectHash) {
+    return getRecentObservations(projectHash, 100000).map((observation) => ({
+        ts: getString(observation.ts),
+        session: getString(observation.session),
+        session_id: getString(observation.session_id),
+        tool: getString(observation.tool),
+        input_summary: getString(observation.input_summary),
+        output_summary: getString(observation.output_summary),
+    }));
+}
 function detectLevel(projectHash) {
     const observationCount = countObservations(projectHash);
     const instincts = readInstincts(projectHash);
@@ -480,6 +506,33 @@ function handleTool(name, params) {
             ].join("\n");
             return text(reflection);
         }
+        case "ci_gateguard_clear": {
+            // Beginner-available on purpose: the GateGuard hook fires for every
+            // install, so the clearance action must too. Resolves the session dir via
+            // gateguard-state (canonical), the same way the hook does, so the marker
+            // lands where the hook looks regardless of how each process spelled the
+            // project root.
+            const rawList = Array.isArray(params.file_paths) ? params.file_paths : [];
+            const listPaths = rawList.filter((value) => typeof value === "string" && value.length > 0);
+            const single = getString(params.file_path).trim();
+            const paths = single ? [...listPaths, single] : listPaths;
+            if (paths.length === 0) {
+                return error("file_paths is required — pass the file path(s) named in the GateGuard block reason, e.g. { file_paths: [\"src/x.ts\"] }.");
+            }
+            const sessionDir = resolveSessionDir();
+            const { cleared, skippedForCap } = clearFiles(sessionDir, paths);
+            const lines = [
+                "## GateGuard clearance",
+                "",
+                `**State file:** ${join(sessionDir, "gateguard-session.json")}`,
+                `**Cleared (${cleared.length}):** ${cleared.length > 0 ? cleared.join(", ") : "(none — already cleared)"}`,
+            ];
+            if (skippedForCap.length > 0) {
+                lines.push(`**Skipped — session cap of ${MAX_CLEARED_FILES} reached (${skippedForCap.length}):** ${skippedForCap.join(", ")}`, "Start a new session to reset the gate.");
+            }
+            lines.push("", "Retry the Edit/Write now — it will pass.");
+            return text(lines.join("\n"));
+        }
         case "ci_reinforce": {
             if (MODE !== "expert") {
                 return error("ci_reinforce requires expert mode. Start server with --mode expert");
@@ -665,6 +718,166 @@ function handleTool(name, params) {
             }
             return text(lines.join("\n"));
         }
+        case "ci_goal_check": {
+            if (MODE !== "expert") {
+                return error("ci_goal_check requires expert mode");
+            }
+            const limit = getNumber(params.limit, 30);
+            if (!Number.isInteger(limit) || limit <= 0) {
+                return error(`limit must be a positive integer; got ${limit}. Omit it to score the default 30 most recent observations.`);
+            }
+            const explicit = getString(params.goal_file).trim();
+            const workspaceRoot = getWorkspaceRoot();
+            const candidates = explicit
+                ? [explicit]
+                : [
+                    join(workspaceRoot, PLANNING_FILES.taskPlan),
+                    join(INSTINCTS_DIR, project.hash, "goal.md"),
+                ];
+            let goalContent = "";
+            let goalSource = "";
+            for (const candidate of candidates) {
+                if (!existsSync(candidate)) {
+                    continue;
+                }
+                try {
+                    goalContent = readFileSync(candidate, "utf8");
+                    goalSource = candidate;
+                    break;
+                }
+                catch {
+                    // try the next candidate
+                }
+            }
+            if (!goalContent) {
+                return text(`No goal source found. Looked for: ${candidates.join(", ")}.\nRun ci_plan_init (or /planning-with-files) to create ${PLANNING_FILES.taskPlan} with a '## Goal' section.`);
+            }
+            const goal = parseGoalFromPlan(goalContent);
+            if (!goal) {
+                return text(`Found ${goalSource} but it has no '## Goal' section. Add one — ci_plan_init seeds it. Optional '## Goal Keywords' and '## Goal Scope' sections sharpen the drift signal.`);
+            }
+            const goalObservations = getRecentObservations(project.hash, limit).map((observation) => ({
+                ts: getString(observation.ts),
+                tool: getString(observation.tool),
+                input_summary: getString(observation.input_summary),
+                output_summary: getString(observation.output_summary),
+            }));
+            const report = scoreObservations(goalObservations, goal, { window: limit });
+            return text(`## Goal Check\n\n**Goal source:** ${goalSource}\n\n${formatDriftReport(report)}`);
+        }
+        case "ci_recall": {
+            if (MODE !== "expert") {
+                return error("ci_recall requires expert mode");
+            }
+            const queryString = getString(params.query).trim();
+            if (!queryString) {
+                return error("query is required");
+            }
+            const k = getNumber(params.k, 5);
+            const since = getString(params.since).trim();
+            if (since && parseSince(since, Date.now()) === null) {
+                return error(`Could not parse since="${since}". Use an ISO timestamp (e.g. 2026-05-01) or a relative window like 7d, 24h, or 30m.`);
+            }
+            // Recall searches the full history, not just the recent window.
+            const recallObservations = getRecentObservations(project.hash, 100000).map((observation) => ({
+                ts: getString(observation.ts),
+                session: getString(observation.session),
+                session_id: getString(observation.session_id),
+                tool: getString(observation.tool),
+                input_summary: getString(observation.input_summary),
+                output_summary: getString(observation.output_summary),
+            }));
+            if (recallObservations.length === 0) {
+                return text("No observations yet. Hooks capture tool calls automatically; recall searches that history.");
+            }
+            const index = buildIndex(recallObservations);
+            const hits = queryRecall(index, queryString, { k, since: since || undefined });
+            return text(formatRecallHits(hits, queryString));
+        }
+        case "ci_distill_candidates": {
+            if (MODE !== "expert") {
+                return error("ci_distill_candidates requires expert mode");
+            }
+            const distillObservations = readDistillObservations(project.hash);
+            const candidates = findCandidates(extractTrajectories(distillObservations));
+            return text(formatCandidates(candidates));
+        }
+        case "ci_distill_propose": {
+            if (MODE !== "expert") {
+                return error("ci_distill_propose requires expert mode");
+            }
+            const id = getString(params.id).trim();
+            if (!id) {
+                return error("id is required — run ci_distill_candidates to list current candidate ids");
+            }
+            if (!isSafeDraftId(id)) {
+                return error(`Invalid draft id "${id}". Draft ids look like draft-<slug> (lowercase letters, digits, hyphens).`);
+            }
+            const distillObservations = readDistillObservations(project.hash);
+            const candidate = findCandidates(extractTrajectories(distillObservations)).find((entry) => entry.id === id);
+            if (!candidate) {
+                return error(`No candidate "${id}". Run ci_distill_candidates to list current ids.`);
+            }
+            const draft = serializeDraft(draftFromCandidate(candidate));
+            const draftsDir = join(INSTINCTS_DIR, project.hash, "drafts");
+            mkdirSync(draftsDir, { recursive: true });
+            const draftPath = join(draftsDir, `${id}.yaml`);
+            writeFileSync(draftPath, draft);
+            return text([
+                "## Draft written",
+                "",
+                `**Path:** ${draftPath}`,
+                "",
+                "Edit the body to capture the real recipe (preconditions, concrete steps, gotchas), then promote with:",
+                "",
+                `  ci_distill_promote id=${id}`,
+                "",
+                "```yaml",
+                draft.trimEnd(),
+                "```",
+            ].join("\n"));
+        }
+        case "ci_distill_promote": {
+            if (MODE !== "expert") {
+                return error("ci_distill_promote requires expert mode");
+            }
+            const id = getString(params.id).trim();
+            if (!id) {
+                return error("id is required");
+            }
+            if (!isSafeDraftId(id)) {
+                return error(`Invalid draft id "${id}". Draft ids look like draft-<slug> (lowercase letters, digits, hyphens).`);
+            }
+            const draftPath = join(INSTINCTS_DIR, project.hash, "drafts", `${id}.yaml`);
+            if (!existsSync(draftPath)) {
+                return error(`No draft at ${draftPath}. Run ci_distill_propose id=${id} first.`);
+            }
+            let parsed = null;
+            try {
+                parsed = parseYamlInstinct(readFileSync(draftPath, "utf8"));
+            }
+            catch {
+                parsed = null;
+            }
+            if (!parsed) {
+                return error(`Draft ${draftPath} could not be parsed as an instinct. Check the YAML shape.`);
+            }
+            const promoted = {
+                ...parsed,
+                confidence: 0.5,
+                source: "distilled",
+                scope: "project",
+                observation_count: 1,
+            };
+            writeInstinct(project.hash, promoted);
+            try {
+                rmSync(draftPath);
+            }
+            catch {
+                // best-effort cleanup; the live instinct is already written
+            }
+            return text(`Promoted **${promoted.id}** to a project instinct at confidence ${promoted.confidence} (SUGGEST tier). The draft has been consumed.`);
+        }
         case "ci_dashboard": {
             if (MODE !== "expert") {
                 return error("ci_dashboard requires expert mode");

package/plugins/continuous-improvement/commands/audit.md

@@ -0,0 +1,34 @@
+---
+name: audit
+description: Audit a window of recent commits for real defects, confirm each finding before fixing, verify every surface a fix touches, then report confirmed/dismissed/no-op with evidence. Enforces Law 4 (Verify Before Reporting).
+---
+
+# /audit — Confirm Recent Commits Before You Trust Them
+
+Run the audit-driven loop over recent work: a merged commit with green CI is a claim, not a proof.
+
+## What it does
+
+Takes a commit window, hunts for real defects one concern at a time, proves each finding against the actual code (false positives die before any edit), fixes on a branch with the smallest diff, verifies every surface the fix touches, and reports honestly. Backed by the `audit` skill.
+
+## The loop
+
+```
+1. Scope    git log to pick the window (e.g. HEAD~10..HEAD, or main since last release)
+2. Find     one pass per dimension: value/economy drift, concurrency, surface coverage, type/contract
+3. Confirm  read the actual lines; state in one sentence why it is real, or dismiss it
+4. Fix      one concern per commit; prefer a failing test first, then green
+5. Verify   exercise EVERY surface (backend, frontend, admin, cache, migration), not just the edited one
+6. Report   confirmed (with the proof), dismissed (with why), no-op (in scope, nothing to change)
+```
+
+## Default skeptical
+
+Findings are hypotheses. Default each to a false positive until the code proves the bug — defaulting to "real" is how plausible-but-wrong fixes ship. For a thorough audit, fan the find pass out across dimensions with parallel reviewers, then verify each survivor adversarially.
+
+## Pairs with
+
+- **`audit`** skill — the discipline this command runs.
+- **`code-review`** / **`security-review`** — the per-dimension passes.
+- **`reconcile`** — the safe branch→PR path once the audit produces a fix.
+- **`recall`** — check whether a finding was already hit and fixed before.

package/plugins/continuous-improvement/commands/companion-preference.md

@@ -0,0 +1,58 @@
+---
+name: companion-preference
+description: Inspect companion-preference hook telemetry — counts by CI skill, action breakdown, and companion-installed%.
+---
+
+# /companion-preference
+
+Read and aggregate the JSONL telemetry written by `hooks/companion-preference.mjs`. Reports per-skill totals, action breakdown (`observation`, `advisory`, `block`, `block-not-installed`), and the share of events where the companion plugin was installed at the time.
+
+The dataset is the evidence base for a future `companions-first` default-flip decision — once a 7-day shadow shows the `companions-first` path firing on a meaningful share of routed Skill calls, with companions installed in the majority of them, the flip is grounded.
+
+## Trigger phrases
+
+- `/companion-preference`
+- `/companion-preference status`
+- "show companion preference stats"
+- "what does the companion-preference hook see"
+
+## What happens
+
+1. Run `node bin/companion-preference-status.mjs` from the repo root with the operator's chosen window. Default `--days 7`. Pass `--all` for the entire file or `--days N` for a different window.
+2. Render the table the CLI emits to the user verbatim. Do not paraphrase the numbers — the JSONL is authoritative.
+3. If the CLI prints "no telemetry recorded yet," check three things in order: (a) `~/.claude/settings.json` has `continuous_improvement.companion_preference` set (otherwise the hook is a no-op and writes nothing); (b) the user has invoked at least one mapped CI skill (`tdd-workflow`, `verification-loop`, `context-budget`, `ralph`, `learn-eval`) since the hook landed; (c) the hook's PreToolUse registration is intact in `plugins/continuous-improvement/hooks/hooks.json`.
+4. Offer one decision-ready next step based on the totals — e.g., "ratio of `observation` rows with `companion_installed=true` suggests `companions-first` is safe to flip for X but not Y."
+
+## Subcommands
+
+### `/companion-preference status` (default)
+
+Same as `/companion-preference`.
+
+### `/companion-preference status --json`
+
+Emit the machine-readable JSON report. Useful when you want to pipe the output into another tool or write your own aggregator.
+
+```bash
+node bin/companion-preference-status.mjs --json --all
+```
+
+## CLI flags
+
+| Flag | Effect |
+|---|---|
+| `--days N` | Only count events from the last N days (default 7). |
+| `--all` | Ignore the window; count every row in the file. |
+| `--json` | Emit a machine-readable JSON report. |
+| `--path <file>` | Override the default JSONL path. Used by the test suite; rarely needed in practice. |
+| `-h`, `--help` | Print CLI help and exit. |
+
+## Path resolution
+
+By default the CLI reads `~/.claude/instincts/<project-hash>/companion-preference.jsonl`, where the hash is the same `sha256(projectRoot).slice(0, 12)` that the hook itself uses. The project root resolves via `CLAUDE_PROJECT_DIR` env var if set, else `git rev-parse --show-toplevel`, else the literal `"global"`. Hash and path scheme are reused verbatim from `hooks/companion-preference.mjs` to keep the read side aligned with the write side.
+
+## Companion skills
+
+- `hooks/companion-preference.mjs` — the writer that produces the JSONL this command reads.
+- `skills/superpowers.md` § "Companion-Preference Override" — the broader contract for the setting this command's dataset measures.
+- `commands/dashboard.md` — the broader continuous-improvement status surface; this command is the dispatcher-bias-specific narrower view.

package/plugins/continuous-improvement/commands/discipline.md

@@ -33,6 +33,20 @@ The Laws above are the *how*. These five principles are the *why*: code ships fr
 
 Code is a liability, not an asset. Speed without these five turns into someone else's incident at 3am — except the someone is you.
 
+## Goal-Driven Execution maps onto the Laws
+
+"Goal-Driven Execution" is the operator's global principle #4 — tie every change to a stated goal, refuse scope creep, stop when the goal is met. It is not a separate Law here; it is the spine of four existing Laws:
+
+| Sub-rule of Goal-Driven Execution | Lives in |
+|---|---|
+| Tie work to a stated goal; if none, ask | Law 2 — the `## Goal` in `task_plan.md` is the single source of truth |
+| Catch drift away from that goal mid-session | Law 2 — the `goal-monitor` skill / `/goal-check` scores recent activity against the goal |
+| Finish one thing; refuse "while I'm here" scope creep | Law 3 |
+| Commit messages lead with the outcome, not the mechanism | Law 4 — "done" is an observed outcome |
+| Iterate one change at a time toward the goal | Law 6 |
+
+The `goal-monitor` primitive (`/goal-check`, `ci_goal_check`) is the measurable arm of this principle: it reads the `## Goal` section and reports ON GOAL / DRIFT / NO DATA. Run it at phase boundaries to confirm the work and the plan still agree.
+
 ## The Loop
 
 ```

package/plugins/continuous-improvement/commands/distill.md

@@ -0,0 +1,39 @@
+---
+name: distill
+description: Distill repeated successful tool sequences from the observation log into reusable draft instincts, with an explicit propose-edit-promote ladder. Enforces Law 7 (Learn From Every Session).
+---
+
+# /distill — Trajectory Distillation
+
+Mine this project's observation log for tool sequences that recurred across multiple successful sessions, and turn the good ones into reusable instincts.
+
+## What it does
+
+Groups observations into trajectories, keeps the ones that ended in a passing verification, and finds tool-sequence n-grams that recurred across distinct sessions. Backed by the `ci_distill_candidates` / `ci_distill_propose` / `ci_distill_promote` MCP tools (expert mode) and the `skill-distillation` skill.
+
+## The ladder
+
+```
+ci_distill_candidates           # list patterns that qualify (read-only)
+ci_distill_propose id=<id>       # write a DRAFT (placeholder body) to drafts/<id>.yaml
+# ... edit the draft body to capture the real recipe ...
+ci_distill_promote id=<id>       # promote to a live instinct at 0.5 confidence (SUGGEST)
+```
+
+Drafts never affect behavior until promoted. The draft starts at 0.4 confidence in a `drafts/` subdirectory the instinct loader ignores; promotion writes a live instinct at 0.5 (SUGGEST tier).
+
+## Candidate criteria
+
+- The trajectory must have ended in success (`verify-exit-0` or `reflection-pass`).
+- The tool sequence must have recurred at least 3 times across at least 2 distinct sessions.
+- A pattern repeated only within one session is rejected — that is repetition, not a reusable skill.
+
+## Why the human edit step
+
+A tool sequence is evidence, not a recipe. `Read → Edit → Bash → Edit → Bash` is a TDD loop, but the value is in the preconditions and concrete steps. Editing the draft body before promotion is the guard against fabricating confident skills from coincidental call ordering.
+
+## Pairs with
+
+- **`skill-distillation`** skill — the discipline this command runs.
+- **`continuous-improvement`** (core SKILL.md, Law 7 — Learn From Every Session).
+- **`recall`** — before promoting, check whether an existing instinct already covers the pattern.

package/plugins/continuous-improvement/commands/goal-check.md

@@ -0,0 +1,53 @@
+---
+name: goal-check
+description: Check whether recent tool activity still relates to the stated goal in task_plan.md, reporting a drift score and the top off-goal tool calls. Enforces Law 2 (Plan Is Sacred).
+---
+
+# /goal-check — Goal Drift Check
+
+Score this session's recent tool activity against the stated goal and report whether the work is still ON GOAL or has DRIFTed.
+
+## What it does
+
+Reads the `## Goal` section of `task_plan.md` (plus optional `## Goal Keywords` and `## Goal Scope` sections), scores the most recent observations from `~/.claude/instincts/<project-hash>/observations.jsonl`, and reports a drift score with the top off-goal tool calls. Backed by the `ci_goal_check` MCP tool (expert mode) and the `goal-monitor` skill.
+
+## How to invoke
+
+```
+ci_goal_check                       # last 30 observations vs task_plan.md
+ci_goal_check limit=50              # widen the observation window
+ci_goal_check goal_file=docs/x.md   # score against a specific plan file
+```
+
+Goal source resolution order: `task_plan.md` in the project root, then `~/.claude/instincts/<project-hash>/goal.md`, then an explicit `goal_file`.
+
+## Output shape
+
+```
+## Goal Check
+
+**Goal source:** /home/me/repo/task_plan.md
+
+**Status:** DRIFT
+**Score:** 12% (1/8 matched, threshold 30%)
+**Reason:** Only 1/8 recent observations relate to the goal (threshold 0.3).
+**Goal keywords:** oauth, jwt, login, session
+
+**Top off-goal activity (most recent 5):**
+- [2026-05-28T12:01:00Z] Edit — src/marketing/landing.ts
+- ...
+
+_Drift detected. Either steer back to the goal, or update the `## Goal` section in your plan if the goal has legitimately changed._
+```
+
+## Acting on the result
+
+- **ON GOAL** — the plan and the work agree; proceed.
+- **DRIFT** — steer back to the goal, or update `## Goal` if it has legitimately changed. Keeping the plan and the work in disagreement is the Law 2 violation this command catches.
+- **NO DATA** — the observation window is still filling; keep working.
+
+## Pairs with
+
+- **`goal-monitor`** skill — the discipline this command runs.
+- **`continuous-improvement`** (core SKILL.md, Law 2 — Plan Is Sacred).
+- **`planning-with-files`** — creates the `task_plan.md` whose `## Goal` section this command reads.

package/plugins/continuous-improvement/commands/grill-me.md

@@ -0,0 +1,40 @@
+---
+name: grill-me
+description: "Interview the user relentlessly about a plan or design until shared understanding is reached. Ported from mattpocock/skills under MIT."
+---
+
+# /grill-me
+
+Stress-test the current plan or design by interviewing the user one question at a time, walking every branch of the decision tree, and recommending an answer for each.
+
+## Trigger phrases
+
+- `/grill-me`
+- "grill me"
+- "stress-test this plan"
+- "interview me about this"
+- "what am I missing?"
+
+## What happens
+
+1. Identify the current plan or design from the conversation — the high-level goal, the assumptions in play, the decisions already made.
+2. Walk the decision tree top-down. For each unresolved branch, ask exactly **one question** with a **recommended answer**.
+3. Before asking, check whether the codebase already answers the question (`grep`, `ls`, file reads). If it does, use that and skip the question.
+4. Resolve dependencies in order — do not ask about deployment before the data model is pinned.
+5. Stop when the plan is shippable cold to a fresh agent. Do not interview past the point of usefulness.
+
+## Five interview rules
+
+1. **One question at a time.** Never multi-question; force depth on every branch.
+2. **Always recommend.** Every question carries "my answer would be X because Y".
+3. **Explore before asking.** Code answers beat user-attention answers.
+4. **Walk the tree, do not jump.** Order matters.
+5. **Stop when shippable.** End state is a plan a fresh agent could execute, not an infinite interview.
+
+## Skill file
+
+Full behavior is defined in [`skills/grill-me.md`](../skills/grill-me.md). The verbatim upstream cold-storage copy lives 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).
+
+## Attribution
+
+Ported from [mattpocock/skills `productivity/grill-me`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) (MIT, © 2026 Matt Pocock).

package/plugins/continuous-improvement/commands/grill-with-docs.md

@@ -0,0 +1,38 @@
+---
+name: grill-with-docs
+description: "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."
+---
+
+# /grill-with-docs
+
+Stress-test the current plan or design by interviewing the user one question at a time AND updating the project's domain-language doc (`CONTEXT.md`) and architecture decision records (`docs/adr/`) inline as decisions land.
+
+## Trigger phrases
+
+- `/grill-with-docs`
+- "grill me and update the docs"
+- "stress-test this against our domain model"
+- "let's nail down the language and ADR this"
+
+## What happens
+
+1. Read `CONTEXT.md` (or `CONTEXT-MAP.md` + per-context `CONTEXT.md`) and `docs/adr/` if they exist. Use them as the source of truth for project language and prior decisions.
+2. Walk the decision tree top-down. One question at a time with a recommended answer.
+3. Challenge fuzzy terms against the glossary. Sharpen vague language. Stress-test relationships with concrete scenarios. Cross-reference user statements against the code.
+4. When a term is resolved, update `CONTEXT.md` immediately (lazy-create if missing). Use the format in the skill's Appendix A.
+5. Offer an ADR only when all three are true: hard to reverse, surprising without context, result of a real trade-off. Use the format in Appendix B.
+
+## When to fire this instead of `/grill-me`
+
+| Skill | Use when |
+|---|---|
+| `/grill-me` | Conversation-only grilling; no project to update yet, or no docs convention. |
+| `/grill-with-docs` | Project has `CONTEXT.md` or is ready to start one; decisions should persist past the session. |
+
+## Skill file
+
+Full behavior, format specs, and 7 Laws fit are defined in [`skills/grill-with-docs.md`](../skills/grill-with-docs.md). The verbatim upstream cold-storage copies live at [`third-party/mattpocock-skills/skills/engineering/grill-with-docs/`](../third-party/mattpocock-skills/skills/engineering/grill-with-docs/) (`SKILL.md`, `CONTEXT-FORMAT.md`, `ADR-FORMAT.md`); SHA pin in [`third-party/MANIFEST.md`](../third-party/MANIFEST.md).
+
+## Attribution
+
+Ported from [mattpocock/skills `engineering/grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md) (MIT, © 2026 Matt Pocock). Mattpocock calls this his most powerful skill: "It's hard to explain how powerful this is. It might be the single coolest technique in this repo."

package/plugins/continuous-improvement/commands/handoff.md

@@ -0,0 +1,42 @@
+---
+name: handoff
+description: "Compact the current conversation into a handoff document for another agent to pick up. Ported from mattpocock/skills under MIT."
+argument-hint: "What will the next session be used for?"
+---
+
+# /handoff
+
+Hand the current session off to a fresh agent by writing a brief, mktemp-backed markdown summary they can pick up cold.
+
+## Trigger phrases
+
+- `/handoff`
+- `/handoff <what the next session will focus on>`
+- "write a handoff doc"
+- "compact this into a handoff"
+
+## What happens
+
+1. Read the current conversation (and the user's argument, if given) to identify the goal, current state, decisions made, open questions, next concrete step, and skills to load.
+2. Generate a unique path with `mktemp -t handoff-XXXXXX.md` and read it (it will be empty).
+3. Write the handoff doc to that path. Reference PRDs, plans, ADRs, issues, commits, and diffs by path or URL — do not duplicate their content.
+4. Suggest the skills the next session should load.
+
+## What goes in the doc
+
+A one-screen brief, in this order:
+
+1. **Goal** — one sentence on the outcome the user is steering toward.
+2. **Current state** — what is actually true on disk / in the system right now.
+3. **Decisions made this session** — only what is not already captured in commits or other artifacts.
+4. **Open questions** — blocking choices the next agent needs the user to answer.
+5. **Next concrete step** — the single action the next agent should take first.
+6. **Skills to load** — names of the skills the next session should activate.
+
+## Skill file
+
+Full behavior is defined in [`skills/handoff.md`](../skills/handoff.md). The verbatim upstream cold-storage copy lives at [`third-party/mattpocock-skills/skills/in-progress/handoff/SKILL.md`](../third-party/mattpocock-skills/skills/in-progress/handoff/SKILL.md); SHA pin in [`third-party/MANIFEST.md`](../third-party/MANIFEST.md).
+
+## Attribution
+
+Ported from [mattpocock/skills `in-progress/handoff`](https://github.com/mattpocock/skills/blob/main/skills/in-progress/handoff/SKILL.md) (MIT, © 2026 Matt Pocock).

package/plugins/continuous-improvement/commands/proceed-with-the-recommendation.md

@@ -18,6 +18,26 @@ Invoke immediately after the agent has offered a numbered list of recommendation
 - "execute the recommendations"
 - "yes do it" / "all of them"
 
+## Fast-path: `--once` mode
+
+For a single-item, `safe`-tagged confirmation, append `--once` to skip P-MAG, Plan, Reflect, and the three-section close. Runs Phase 1 + Phase 3 + Phase 4 only and ends with one line: `Done: <item>. Verified: <check + output>.`
+
+Trigger phrases:
+
+- `/proceed-with-the-recommendation --once`
+- `/proceed --once`
+- "proceed once with that" / "just do that one"
+- Any standard trigger phrase plus the literal `--once` suffix
+
+Hard preconditions (the skill refuses `--once` and falls back to the full flow if any fail):
+
+- Recommendation list has exactly one item
+- Item is tagged `safe` (not `caution`, not `needs-approval`)
+- Item touches ≤3 files, ≤150 LOC, and none of `.github/`, `bin/`, `lib/`, `src/`, `third-party/`
+- Item is not destructive (no deploy, force-push, DB drop, secret rotation)
+
+Full behavior is defined in [`skills/proceed-with-the-recommendation.md`](../skills/proceed-with-the-recommendation.md) under § "Fast-Path: `--once` Mode".
+
 ## What happens
 
 1. **Pre-flight (Law 1)** — restate the recommendation list in original order, tag each `safe` / `caution` / `needs-approval`