continuous-improvement 3.22.1 → 3.24.0

package/plugins/continuous-improvement/lib/destructive-bash.mjs

@@ -0,0 +1,216 @@
+/**
+ * Destructive-Bash classifier for hooks/gateguard.mjs.
+ *
+ * Two layers, pure and dependency-free so a table test and a future
+ * `gateguard-explain` CLI can drive it without spawning the hook:
+ *
+ *   1. Structured rules: the command is split at unquoted separators
+ *      (`|`, `||`, `&&`, `;`, newline) and each simple command is tokenized,
+ *      so flag order and spelling stop mattering. `rm -r -f`, `rm -Rf` and
+ *      `rm --recursive --force` are the same command; `git clean -fdx` and
+ *      `git clean --force -d` are the same command. Each rule has a stable id
+ *      the deny reason prints, so a block is explainable.
+ *   2. The original substring list, kept verbatim as the fallback so nothing
+ *      that was caught before stops being caught.
+ *
+ * What is deliberately NOT here: plain file writes through Bash (`cat > x`,
+ * `sed -i`). Gating those would break the operator workflow that uses Bash
+ * precisely to write files; that limit is disclosed on the site and README.
+ *
+ * Message-flag carve-out: the VALUE of a commit message, PR body, title, or
+ * note is prose, never a command. It is blanked before any rule runs, so
+ * `git commit -m "rm -rf the old helper"` stays allowed. `-c` is not a message
+ * flag: `bash -c "rm -rf /"` carries a real command and still gates.
+ */
+export const DESTRUCTIVE_PATTERNS = [
+    "rm -rf",
+    "rm -fr",
+    "git reset --hard",
+    "git push --force",
+    "git push -f",
+    "--force-with-lease",
+    "git branch -D",
+    "drop table",
+    "drop database",
+    "drop schema",
+    "truncate ",
+    "mkfs",
+    "dd if=",
+    "format ",
+    "rmdir /s",
+    "del /f /q",
+    "del /q /f",
+    "Remove-Item -Recurse",
+    "Remove-Item -Force",
+];
+// Flags whose VALUE is human prose (a commit message, a PR body) or a filename —
+// never a command to execute. Their contents must not trip the destructive scan.
+const MESSAGE_FLAG_RE = /(^|\s)(-m|--message|-F|--file|--body|--body-file|--title|--notes|-C|--reuse-message)(=|\s+)('[^']*'|"[^"]*"|\S+)/g;
+/** Blank the value of every message/body flag; the flag itself is preserved. */
+export function stripMessageArgs(command) {
+    return command.replace(MESSAGE_FLAG_RE, (_match, lead, flag) => `${lead}${flag} `);
+}
+// Split at shell separators that sit outside single or double quotes.
+function splitSimpleCommands(command) {
+    const segments = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === "\n" || ch === ";") {
+            segments.push(current);
+            current = "";
+            continue;
+        }
+        if (ch === "|" || ch === "&") {
+            // `||`, `&&`, `|`, `&` all end the simple command; collapse a doubled char.
+            if (command[i + 1] === ch)
+                i++;
+            segments.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    segments.push(current);
+    return segments.map((s) => s.trim()).filter((s) => s !== "");
+}
+function tokenize(segment) {
+    return segment.split(/\s+/).filter((t) => t !== "");
+}
+// Drop `sudo`, `env`, and leading VAR=value assignments so the command word is
+// the first token the rules look at.
+function commandTokens(segment) {
+    const tokens = tokenize(segment);
+    let i = 0;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        if (t === "sudo" || t === "env" || t === "command" || /^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) {
+            i++;
+            continue;
+        }
+        break;
+    }
+    return tokens.slice(i);
+}
+// For `git`, skip global options (`-C <dir>`, `-c k=v`, `--git-dir=…`) to find
+// the subcommand and its own arguments.
+function gitSubcommand(tokens) {
+    if (tokens[0] !== "git")
+        return null;
+    let i = 1;
+    while (i < tokens.length && tokens[i].startsWith("-")) {
+        const t = tokens[i];
+        i += t === "-C" || t === "-c" || t === "--git-dir" || t === "--work-tree" ? 2 : 1;
+    }
+    const sub = tokens[i];
+    if (!sub)
+        return null;
+    return { sub, args: tokens.slice(i + 1) };
+}
+const isShortFlag = (t) => /^-[A-Za-z]+$/.test(t);
+const hasShortLetter = (t, letters) => isShortFlag(t) && letters.test(t.slice(1));
+const STRUCTURED_RULES = [
+    {
+        id: "rm-recursive-force",
+        test: (tokens) => {
+            if (tokens[0] !== "rm")
+                return false;
+            const flags = tokens.slice(1).filter((t) => t.startsWith("-"));
+            const recursive = flags.some((t) => t === "--recursive" || hasShortLetter(t, /[rR]/));
+            const force = flags.some((t) => t === "--force" || hasShortLetter(t, /f/));
+            return recursive && force;
+        },
+    },
+    {
+        id: "git-clean-force",
+        test: (tokens) => {
+            const git = gitSubcommand(tokens);
+            if (!git || git.sub !== "clean")
+                return false;
+            const dryRun = git.args.some((t) => t === "--dry-run" || hasShortLetter(t, /n/));
+            const force = git.args.some((t) => t === "--force" || hasShortLetter(t, /f/));
+            return force && !dryRun;
+        },
+    },
+    {
+        id: "git-checkout-discard",
+        test: (tokens) => {
+            const git = gitSubcommand(tokens);
+            if (!git || git.sub !== "checkout")
+                return false;
+            const dash = git.args.indexOf("--");
+            if (dash !== -1)
+                return git.args.length > dash + 1; // `git checkout -- <pathspec>` discards
+            const first = git.args.find((t) => !t.startsWith("-"));
+            return first === "." || first === "./";
+        },
+    },
+    {
+        id: "git-restore-discard",
+        test: (tokens) => {
+            const git = gitSubcommand(tokens);
+            if (!git || git.sub !== "restore")
+                return false;
+            const pathspec = git.args.some((t) => !t.startsWith("-"));
+            if (!pathspec)
+                return false;
+            const staged = git.args.some((t) => t === "--staged" || hasShortLetter(t, /S/));
+            const worktree = git.args.some((t) => t === "--worktree" || hasShortLetter(t, /W/));
+            return !staged || worktree; // `--staged` alone only unstages
+        },
+    },
+    {
+        id: "find-delete",
+        test: (tokens) => tokens[0] === "find" && tokens.includes("-delete"),
+    },
+    {
+        id: "git-push-plus-refspec",
+        test: (tokens) => {
+            const git = gitSubcommand(tokens);
+            if (!git || git.sub !== "push")
+                return false;
+            return git.args.some((t) => t.startsWith("+") && t.length > 1);
+        },
+    },
+    {
+        id: "git-stash-drop",
+        test: (tokens) => {
+            const git = gitSubcommand(tokens);
+            if (!git || git.sub !== "stash")
+                return false;
+            return git.args[0] === "drop" || git.args[0] === "clear";
+        },
+    },
+];
+/** Classify one Bash command string. Pure; never throws on odd input. */
+export function classifyDestructiveBash(command) {
+    if (typeof command !== "string" || command.trim() === "")
+        return { destructive: false, rule: null };
+    const stripped = stripMessageArgs(command);
+    for (const segment of splitSimpleCommands(stripped)) {
+        const tokens = commandTokens(segment);
+        if (tokens.length === 0)
+            continue;
+        for (const rule of STRUCTURED_RULES) {
+            if (rule.test(tokens))
+                return { destructive: true, rule: rule.id };
+        }
+    }
+    const lower = stripped.toLowerCase();
+    const hit = DESTRUCTIVE_PATTERNS.find((p) => lower.includes(p.toLowerCase()));
+    if (hit !== undefined)
+        return { destructive: true, rule: `substring:${hit}` };
+    return { destructive: false, rule: null };
+}

package/plugins/continuous-improvement/lib/gateguard-state.mjs

@@ -45,7 +45,7 @@ export function resolveSessionDir(sessionId) {
     if (fromEnv)
         return fromEnv;
     const projectRoot = resolveProjectRoot();
-    const projectHash = createHash("sha256").update(canonicalizeProjectRoot(projectRoot)).digest("hex").slice(0, 12);
+    const projectHash = hashProjectRoot(projectRoot);
     const base = join(resolveInstinctsRoot(), projectHash);
     const scoped = sanitizeSessionId(sessionId);
     return scoped ? join(base, "sessions", scoped) : base;
@@ -160,6 +160,10 @@ export function canonicalizeProjectRoot(p) {
 export function canonicalizeFileKey(p) {
     return canonicalizePath(p);
 }
+/** SHA-256[:12] of the canonical project root. C:/x, c:/x, and C:\\x share a bucket. */
+export function hashProjectRoot(projectRoot) {
+    return createHash("sha256").update(canonicalizeProjectRoot(projectRoot)).digest("hex").slice(0, 12);
+}
 export function isFileCleared(state, filePath) {
     return canonicalizeFileKey(filePath) in state.cleared_files;
 }

package/plugins/continuous-improvement/lib/plugin-metadata.mjs

@@ -386,7 +386,7 @@ const EXPERT_TOOL_ENTRIES = [
 ];
 const MODE_METADATA = {
     beginner: {
-        description: "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles three grounding skills (gateguard, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
+        description: "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles the ship fast path plus grounding skills (gateguard, tdd-workflow, verification-loop) so one-defect delivery, research, tests, and verification happen by default — every edit starts from facts, not guesses.",
         hooks: ["PreToolUse", "PostToolUse", "UserPromptSubmit"],
         hookDescription: "Silently captures every tool call as observations and routes prompts to the matching skill via the route table. Lightweight and non-blocking.",
     },
@@ -474,6 +474,11 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-pack.mjs\"",
         timeout: hookTimeoutSeconds,
     };
+    const configGuardCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/config-guard.mjs\"",
+        timeout: hookTimeoutSeconds,
+    };
     const observeCommand = {
         type: "command",
         command: "node \"${CLAUDE_PLUGIN_ROOT}/bin/observe.mjs\"",
@@ -538,6 +543,12 @@ export function getPluginHooksConfig() {
                 // Edit/Read/etc. Warn-default (CLAUDE_CI_HOOKPACK_GATE) — never blocks
                 // until the operator opts in.
                 { matcher: "Bash", hooks: [hookPackCommand] },
+                // config-guard watches the files that wire the guardrails
+                // (.claude/settings*.json, .mcp.json, hooks.json, .claude/hooks/,
+                // .claude/plugins/, .claude-plugin/) and the `claude plugin|mcp|config`
+                // CLI forms. Matcher keeps read-only tools off the hot path.
+                // Warn-default (CI_CONFIG_GUARD) — denies only under block.
+                { matcher: "Bash|Edit|MultiEdit|Write|NotebookEdit", hooks: [configGuardCommand] },
             ],
             PostToolUse: [{ hooks: [observeCommand] }],
             UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],

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

@@ -20,6 +20,7 @@ skill set on disk.
 - `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.
 - `model-forward` — Enforces all 7 Laws as a standing stance — go with Claude Code and the model, not against it. Skills are scaffolding that merges into the model over time; the durable core is goal-driven execution (the higher the stated goal, the better) plus self-discipline guardrails.
 - `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.
+- `ship` — Enforces Law 1 (Research Before Executing), Law 3 (One Thing at a Time), and Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Fix one defect through TDD and one PR, isolate unrelated dirty checkouts in an owner-locked clean worktree, and return only eligible clean checkouts to the detected default branch. Use for urgent hotfixes, bug fixes from a messy checkout, or requests to ship one defect without stashing current work.
 - `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.
 
@@ -33,7 +34,6 @@ skill set on disk.
 - `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, then carries the known-good state through to a landed PR: stage by filename, commit one concern, push the feature branch, verify the push landed, open the PR, and after the PR merges fast-forward the default branch and check it out.
 - `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'.
 - `roast` — Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Convene a 5-persona adversarial council (Contrarian, Expansionist, Logician, Researcher, Buyer) that attacks an idea from every angle, then a Judge returns one GO / RESHAPE / KILL verdict plus the cheapest 48-hour test to de-risk it — so you pressure-test an idea before sinking time into building the wrong thing.
-- `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.
 - `simplicity-review` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Reviews the current diff for over-engineering (code that could reuse an existing file, a stdlib or native feature, or fewer lines) and reports trim findings without touching code, so 'it works' is never mistaken for 'it is the minimum that works'.
 - `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.

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

@@ -42,6 +42,8 @@ Before executing, state:
 - Build passes
 - You can explain what changed in one sentence
 
+"Done" is an audit, not a hope: settle the actual result against the Verification you stipulated in Law 2.
+
 ## Law 5: Reflect After Every Session
 
 After non-trivial tasks:
@@ -59,6 +61,8 @@ After non-trivial tasks:
 
 The "Rule to add" field feeds Law 7 — it becomes an instinct with 0.6 starting confidence.
 
+This block is the ledger: what worked and what failed are the session's gains and losses; the rule to add is what you carry into the session you will not be in.
+
 The "Iteration — Next best recommendations" field feeds Law 6. List the **top 3 ranked** core-development moves based on the current code state — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest recommendation; #2 and #3 are alternative directions the user can pick from. NOT git plumbing (commit, push, PR), NOT pure CI ceremony (run tests, type-check), NOT deploy steps. Those belong in the end-of-run summary, not here.
 
 Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.

package/plugins/continuous-improvement/skills/deploy-receipt/SKILL.md

@@ -157,7 +157,7 @@ The rollback command is **printed**, not run. The skill's job is to give the ope
 - `finishing-a-development-branch` (vendored, third-party/superpowers/) — runs first; reports the merge. This skill runs after.
 - `verification-loop` — same Law 4 family; this skill is the deploy-seam specialization
 - `proceed-with-the-recommendation` — routing-table row for "Merge / close branch" should pair `finishing-a-development-branch` with this skill when the project is auto-deploy
-- `safety-guard` — orthogonal; safety-guard prevents destructive ops, this verifies post-deploy state
+- `gateguard` — orthogonal; gateguard gates the destructive op, this verifies post-deploy state
 
 ## Close-the-Loop Rule
 

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

@@ -77,7 +77,7 @@ Before creating {file_path}, present these facts:
 
 ### Destructive Bash Gate (every destructive command)
 
-Triggers on: `rm -rf`, `git reset --hard`, `git push --force`, `drop table`, etc.
+Triggers on structured rules that ignore flag order and spelling — `rm` with any recursive plus any force flag (`rm -r -f`, `rm -Rf`, `rm --recursive --force`), `git clean` with a force flag and no dry run, `git checkout -- <path>` or `git checkout .`, `git restore <path>` unless it is `--staged` only, `find … -delete`, `git push` with a `+refspec`, `git stash drop|clear` — plus the original substring list (`rm -rf`, `git reset --hard`, `git push --force`, `git branch -D`, `drop table`, `truncate `, `Remove-Item -Recurse`, etc.). Each command is judged after `&&`, `||`, `|`, `;` splitting, and a commit message, PR body or title value is blanked first so prose never trips it. The deny reason prints `Matched rule: <id>` so a block is explainable; the classifier is `lib/destructive-bash.mjs`. Plain file writes through Bash (`cat > file`, `sed -i`) are deliberately not gated.
 
 ```
 1. List all files/data this command will modify or delete
@@ -154,10 +154,24 @@ The inline `_gateguard_facts_presented: true` retry still works on harnesses tha
 
 Set the `CI_GATEGUARD_EXCLUDE` environment variable to opt specific low-risk paths out of the gate entirely — an LLM-maintained prose wiki, a generated scratch directory, anything where the fact-forcing pause costs more than it saves. The value is a comma-separated list of path substrings, each matched case-insensitively against the forward-slash-normalized file path, so `/mywiki/` excludes `D:\Vault\MyWiki\notes\x.md`. Unset or empty (the default) changes nothing: every mutating file call is gated exactly as before, and a call that touches a mix of excluded and non-excluded paths still gates the non-excluded ones. Set it per project in `.claude/settings.json` under `env`, or globally in `~/.claude/settings.json`.
 
+An exclusion is never silent. When every target of a call is excluded, `hooks/gateguard.mjs` still allows it but prints one stderr line naming the fragment that matched (`gateguard: skipped by CI_GATEGUARD_EXCLUDE (fragment "docs/wiki" matched docs/wiki/page.md)`). A catch-all fragment that every path contains (`/`, `.`, any single character) is honoured too, but the line says what it really is: the file gate is off for this session. Destructive Bash is never excluded. If `/verify-install` reports the probe write went through, check this variable before concluding the hook is not wired.
+
 ### Locking edits to the current repo
 
 A fact-list can't catch a wrong-repo or wrong-worktree write — you can present perfect facts about the wrong file, in the wrong checkout. Set `CI_GATEGUARD_TARGET_LOCK=block` to make the runtime hook (`hooks/gateguard.mjs`) refuse any mutating call whose **absolute** target canonicalizes outside the session project root (`CLAUDE_PROJECT_DIR`, or the git toplevel). Relative paths resolve under the current directory (= the root) and always pass; only an absolute path into a different tree is denied, and the deny reason names both the stray target and the expected root. This runs before the fact gate and independent of clearance — a wrong-repo write is wrong even with facts. Unset (the default) checks nothing, so legitimate out-of-root edits (`~/.claude`, a `/tmp` scratch file, a sibling repo) are unaffected; turn it on per session in a multi-worktree or headless run where cross-repo writes are the real risk. Paths already covered by `CI_GATEGUARD_EXCLUDE` are never target-locked.
 
+### Migrating from `safety-guard` (retired 2026-08-07)
+
+`safety-guard` was a prose-only tier-2 skill describing three "modes" it never implemented — no hook, no command, no logger ever shipped with it. Every mode it described is already enforced here by the runtime hook (`hooks/gateguard.mjs`):
+
+| Retired `safety-guard` mode | What enforces it now |
+|---|---|
+| Careful — warn on `rm -rf`, `git push --force`, `git reset --hard`, `DROP TABLE`, `chmod 777`, `--no-verify` … | [Destructive Bash Gate](#destructive-bash-gate-every-destructive-command). Its pattern set is a superset of the retired watch list, and it blocks rather than warns. |
+| Freeze — restrict writes to one directory tree | `CI_GATEGUARD_TARGET_LOCK=block` (above). Canonicalizes the absolute target against the session project root and refuses strays — before the fact gate, independent of clearance. |
+| Guard — careful + freeze together | Both of the above; they compose. Narrow the surface further with `CI_GATEGUARD_EXCLUDE`. |
+
+If you previously opted into `safety-guard` for autonomous or production-adjacent runs, set `CI_GATEGUARD_TARGET_LOCK=block` for that session instead. That is a real refusal, not a checklist the agent can talk itself out of.
+
 ### Limitations and guarantees
 
 - **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 — counted per session — bounds damage from stuck loops or rogue agents.
@@ -188,5 +202,6 @@ The standalone `gateguard-ai` Python/CLI package referenced in earlier drafts of
 
 ## Related Skills
 
-- `safety-guard` — Runtime safety checks (complementary, not overlapping)
+- `worktree-safety` — validates the worktree root before a source write; this skill gates the write itself
+- `reconcile` — git ground truth before a destructive git action
 - `code-reviewer` — Post-edit review (GateGuard is pre-edit investigation)

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

@@ -177,6 +177,5 @@ git branch -d <type>/<slug>            # delete the merged feature branch (safe
 
 - **`recall`** (Law 1) — before a risky git op, recall whether the same operation failed on this repo before.
 - **`gateguard`** (Law 1) — the runtime gate (`hooks/gateguard.mjs`); `reconcile` is the procedure you run once a destructive git action is in play.
-- **`safety-guard`** — destructive-operation guardrails for production and autonomous runs.
 - **`audit`** (Law 4) — when an audit ends in a fix, `reconcile` is the safe path from branch to landed PR.
 - **`commit-commands:commit-push-pr`** — the external-plugin equivalent of the commit → push → PR tail; `reconcile` reimplements it inline so the flow works with no companion installed. For a TDD-gated single-defect variant, use `/ship`.

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

@@ -0,0 +1,139 @@
+---
+name: ship
+tier: "1"
+description: >-
+  Enforces Law 1 (Research Before Executing), Law 3 (One Thing at a Time), and Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Fix one defect through TDD and one PR, isolate unrelated dirty checkouts in an owner-locked clean worktree, and return only eligible clean checkouts to the detected default branch. Use for urgent hotfixes, bug fixes from a messy checkout, or requests to ship one defect without stashing current work.
+origin: continuous-improvement
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[one-line defect description]"
+---
+
+# Ship
+
+Fix one defect, open one PR, and hand it back for review. Use `release-train` for stacked multi-PR rollouts and `proceed-with-the-recommendation` for an arbitrary recommendation list.
+
+Preserve branch protection. Never force-push, auto-merge, or deploy from this skill.
+
+## Request
+
+Treat `$ARGUMENTS` as the defect request when supplied. Otherwise use the single concrete defect from the active conversation. Halt and ask for one narrower defect when the request is empty, ambiguous, or contains more than one concern.
+
+## Workflow
+
+Run these steps in order:
+
+1. **Capture ground truth and resolve the base**: run the read-only `reconcile` probes. Record the initiating checkout's absolute root, branch, HEAD, real tracked drift, staged drift, untracked files, in-progress Git operations, registered worktrees, and task ownership. Ownership requires the current session ID in the authoritative worktree lease or an equivalent active harness task ledger that names this exact checkout; merely starting there is not proof. Set `return_allowed=true` only when the initiating checkout is clean, that ownership proof matches the current session, and no other task reserves it. Without such a lease or ledger, fail closed with `return_allowed=false`. A dirty-tree blocker may continue only through the isolated path in step 2 after the changes are confirmed unrelated. Every other blocker still halts. After classification, make the fetch below the first allowed repository mutation and refresh the remote before choosing a base:
+   ```
+   git fetch --prune origin
+   git ls-remote --symref origin HEAD
+   ```
+   Use the live `refs/heads/<base>` returned for `HEAD`. Validate it with `git check-ref-format --branch "<base>"`. Compare it with `refs/remotes/origin/HEAD`, but never let a stale local symbolic ref override the live result. The query must also return the remote HEAD commit. If it succeeds without a symbolic ref, compare that remote HEAD commit with the resolved tips of `origin/main` and `origin/master`, and require exactly one matching candidate. Zero or multiple matches are ambiguous: halt instead of guessing. Halt on a fetch/query failure or if no verified base exists. Confirm `origin/<base>` resolves after the fetch, record its immutable commit as `<base-sha>`, require a full hexadecimal commit ID, and require that it equals the verified remote HEAD commit. Pin worktree creation to `<base-sha>`, not the mutable remote-tracking name.
+2. **Select a safe checkout**:
+   - Always perform the defect work in a separate isolated worktree created from the pinned `<base-sha>`. Do not reuse the initiating checkout, even when it is clean. One isolation path keeps ownership, retention, return, and cleanup behavior consistent.
+   - If dirty changes are not clearly unrelated to the defect, halt and ask. Never guess which changes belong to whom.
+   - Preserve the initiating checkout until the return decision in step 8. When it is dirty with unrelated work, protected, stale, ahead, or owned by another task, do not stash, switch, reset, clean, or copy its changes. Choose an absent absolute sibling or temporary path. Generate the feature branch from ASCII lowercase letters, digits, slash, underscore, and hyphen only (`[a-z0-9/_-]+`), require an alphanumeric first character, and validate the final name before any lookup. Prove the proposed branch is absent locally, then query the remote successfully and require empty output before using the name:
+     ```
+     git check-ref-format --branch "<feature-branch>"
+     git show-ref --verify "refs/heads/<feature-branch>"
+     git ls-remote --heads origin "refs/heads/<feature-branch>"
+     ```
+     The local command must report no ref. The remote command must complete without a network/authentication error and return no matching ref. If either branch exists, choose another unique name. Create a no-upstream worktree with an atomic owner lock:
+     ```
+     git worktree add --no-track --lock --reason "owner=<session-id>; purpose=/ship" -b "<feature-branch>" "<worktree-path>" "<base-sha>"
+     ```
+   - Use the current harness session ID as `<session-id>`. If it is unavailable, generate a unique recorded run token before creating the worktree and reuse that exact token through handoff and cleanup. Treat the lock reason as an advisory coordination ledger for compliant sessions, not as a filesystem write lock. Run `worktree-safety` in the new checkout and confirm its resolved root, `.git` pointer, registration, branch, pinned HEAD, and lock reason all match the current session. A missing or foreign owner blocks work. Recheck that envelope and observable branch, HEAD, and diff state before every source mutation. Halt when another writer cannot be excluded.
+3. **Reproduce (RED)**: use `tdd-workflow` to write a failing test that reproduces the defect and watch it fail. Delete any pre-test implementation code.
+4. **Fix (GREEN)**: write the minimal change that makes the failing test pass, then watch it pass. Keep one concern only.
+5. **Verify**: use `verification-loop` to run the project's verify ladder, including build, types, and relevant tests. A green build proves only the mechanism. Confirm the original defect no longer reproduces.
+6. **Commit**: make one single-concern commit, staged by explicit filename. Never use `git add -A` or `git add .`. Recheck the branch, HEAD, owner lock, and real diff immediately before staging and committing. Use a Windows-safe commit message with a single-line `-m`, repeated `-m` paragraphs, or `git commit -F <tempfile>`. Do not use multi-line here-docs or here-strings.
+7. **Push and open the PR**: confirm the feature branch has no upstream to the protected base. Re-run the remote collision query immediately before pushing, require empty output, then push its name explicitly without force:
+   ```
+   git ls-remote --heads origin "refs/heads/<feature-branch>"
+   git push -u origin "<feature-branch>"
+   ```
+   Verify the remote tip equals local HEAD. Use `commit-commands:commit-push-pr` only when it accepts the explicit base and head below; otherwise open the PR directly and cite the plan or issue:
+   ```
+   gh pr create --base "<base>" --head "<feature-branch>"
+   gh pr view "<pr-number-or-url>" --json baseRefName,headRefName,headRefOid
+   ```
+   Require `baseRefName=<base>`, `headRefName=<feature-branch>`, and `headRefOid` equal to local HEAD. Record that exact PR URL or number for cleanup. A mismatch halts. Do not merge it.
+8. **Return before stopping**:
+   - Confirm the fix checkout is clean and every commit is pushed. If the captured `return_allowed` value is true, immediately revalidate that the initiating checkout remains clean, current-session-owned, and unreserved. Freeze the final decision and its reason. Any drift changes the final value to false.
+   - Persist a local cleanup receipt at `<git-common-dir>/continuous-improvement/ship-receipts/<pr-number>.json` with the PR URL and number, base, base SHA, feature branch, feature tip SHA, absolute worktree path, owner token, initiating checkout path, and final `return_allowed` decision and reason. Write a sibling temporary file first, atomically rename it into place, then read and parse it back before continuing. Keep the local path and owner token out of the public PR body and comments. If later drift appears before a return mutation, atomically downgrade the receipt to `return_allowed=false`, read it back, and leave the initiating checkout unchanged.
+   - Only when the final `return_allowed=true`, meaning the initiating checkout was clean, owned by the current session, and not reserved by another task, consider returning it. Fetch immediately before any switch, revalidate the remote base, and prove no other worktree has `<base>` checked out:
+     ```
+     git fetch --prune origin
+     ```
+     If local `<base>` exists and is not the initiating checkout's current branch, require it to be an ancestor of `origin/<base>`, update that branch ref before switching, then switch only after every network and ref check has passed:
+     ```
+     git merge-base --is-ancestor "refs/heads/<base>" "origin/<base>"
+     git branch -f "<base>" "origin/<base>"
+     git switch "<base>"
+     ```
+     If local `<base>` does not exist, create it without switching, then switch:
+     ```
+     git branch --track "<base>" "origin/<base>"
+     git switch "<base>"
+     ```
+     If the initiating checkout is already on `<base>`, require ancestry and use `git merge --ff-only "origin/<base>"`; a non-fast-forward halts without switching branches. Verify local `<base>` equals `origin/<base>`. If the fetch, remote-base validation, checked-out-elsewhere check, ancestry preflight, branch update, branch creation, fast-forward, or switch fails, leave the initiating checkout's branch and files unchanged and report the blocker. Never switch first and pull afterward.
+   - When `return_allowed=false`, leave the initiating checkout's branch and path unchanged even if it appears clean later. Another task may own that state. Report the recorded reason instead of switching it.
+   - A dirty initiating checkout is the exception: leave its branch and files exactly as found. Return the shell to that path, but do not carry its changes onto `<base>`. Report that default-branch return is intentionally blocked by preserved local work.
+   - During PR review, only the recorded owner or an explicit operator-confirmed handoff may change the retained fix worktree. After every authorized review-fix commit and push, rerun the verification ladder, require a clean worktree, verify the remote feature tip equals local HEAD, and query the same PR again for base, head, and `headRefOid`. Atomically replace the receipt's feature tip SHA with that verified `headRefOid`, then read and parse the receipt back. Halt and retain the worktree if any verification or receipt refresh fails.
+   - Stop with the PR open for human review. Keep an isolated fix worktree registered and owner-locked until the PR is merged so review fixes remain safe.
+9. **Clean up after the PR merges**: run cleanup from the initiating checkout or another retained worktree, never from inside the worktree being removed. Refresh remote state and verify the actual PR merge commit is contained in the detected base, including for squash merges:
+   ```
+   git fetch --prune origin
+   gh pr view "<pr-number-or-url>" --json state,mergeCommit,baseRefName,headRefName,headRefOid
+   git merge-base --is-ancestor "<merge-sha>" "origin/<base>"
+   ```
+   Read `<git-common-dir>/continuous-improvement/ship-receipts/<pr-number>.json` and compare every field with the registered worktree, current refs, PR response, and initiating checkout before cleanup. Halt on a missing, malformed, or mismatched receipt. Halt unless the PR state is `MERGED`, its base and head still match the recorded receipt, its pre-merge `headRefOid` identifies the pushed feature tip, and the ancestry check succeeds. Cleanup may proceed only as the original owner recorded in the local receipt, or after an explicit operator-confirmed handoff that proves the original session is inactive, replaces the owner token in that receipt atomically, and reruns `worktree-safety`. Never silently treat a foreign lock as stale. Confirm the isolated worktree is clean, its HEAD equals both the receipt's feature tip SHA and the PR `headRefOid`, it still carries the authorized owner lock, and it has no observed competing writer. A missing remote feature ref after fetch is expected when GitHub deleted the merged branch; if that ref still exists, require its tip to equal the receipt's feature tip. Recheck immediately before unlock, then release the lock and remove only the named worktree without pausing between commands:
+   ```
+   git worktree unlock "<worktree-path>"
+   git worktree remove "<worktree-path>"
+   ```
+   If state shifts or removal fails, halt and re-establish ownership instead of forcing. Do not run repository-wide pruning. Return or refresh the initiating checkout on `<base>` only when its recorded `return_allowed` decision permits it, using the same fetch-before-switch, checked-out-elsewhere, ancestry, pre-update, create-if-missing, and already-on-base procedures from step 8, then verify local and remote HEADs match. Delete the local feature branch only if `git branch -d "<feature-branch>"` accepts it. Squash merges may make safe deletion refuse; retain and report the branch instead of forcing it. Remove the local receipt only after cleanup and every permitted return check succeeds. A dirty or foreign-owned initiating checkout remains untouched.
+10. **Deploy receipt (advisory)**: after the human merge and deployment, `deploy-receipt` may verify that the deployed SHA matches the merge SHA. This skill does not deploy.
+
+## Hard stops
+
+- The defect description is ambiguous or includes multiple concerns.
+- Dirty changes may overlap the defect or their ownership is unclear.
+- The live remote default branch cannot be resolved and refreshed.
+- The remote default is ambiguous because the live HEAD query has zero or multiple matching `main` or `master` candidates.
+- The selected feature branch or worktree path already exists.
+- The remote feature-branch collision query fails or returns an existing ref.
+- `worktree-safety` cannot prove the new checkout is registered, aligned, and owner-locked to this session.
+- The branch, HEAD, or owner lock shifts after the ground-truth snapshot.
+- Any verification step fails with a non-obvious fix.
+- The fix would touch more than 15 non-generated files. Split it or use `release-train`.
+- A push would target a protected branch or the remote feature tip cannot be verified.
+- Post-merge state or merge-commit ancestry cannot be verified.
+- Cleanup would require force or discard dirty, untracked, or unpushed work.
+
+## Refuse these anti-patterns
+
+- **Stashing unrelated work**: an isolated worktree removes the need.
+- **Moving dirty changes across branches**: preservation takes priority over returning to the default branch.
+- **Hardcoding `main`**: detect the live remote default and support `main` or `master`.
+- **Giving the feature branch a protected upstream**: create with `--no-track` and push the feature name explicitly.
+- **Force cleanup**: never use `git worktree remove --force`, `git branch -D`, `git reset --hard`, or `git clean -fd`.
+- **Repository-wide cleanup**: remove only the named worktree created by this run.
+- **Foreign checkout return**: never switch a checkout without a recorded current-session ownership decision.
+- **Silent lock takeover**: require explicit operator-confirmed handoff when cleanup runs under a different session.
+- **Auto-merge**: never merge the PR this skill opens, even when CI is green.
+- **Deploy**: never run a deploy. `deploy-receipt` only verifies after a human merges and deploys.
+- **Bypass**: never use `--admin`, `--force`, or `--no-verify`.
+- **Bundled concerns**: log unrelated defects as deferred follow-ups instead of adding them to the commit.
+
+## Composition
+
+Route through `reconcile`, mandatory `worktree-safety`, `tdd-workflow`, `verification-loop`, `commit-commands:commit-push-pr`, the safe-return and post-merge cleanup rules above, then advisory `deploy-receipt`. Fall back to equivalent inline checks when a companion skill is unavailable, except ownership: no proven single-writer ledger means no source mutation.
+
+## Example
+
+```
+/ship registration form accepts a negative deposit amount
+```
+
+If the initiating checkout contains unrelated feature work, leave it untouched. Create an owner-locked no-upstream worktree from the verified `<base-sha>`, reproduce and fix the defect, verify and push one commit, open one explicitly targeted PR, and return the shell to the initiating path. After the PR merges, read the local receipt, freshly verify the merge commit, and remove only the clean temporary worktree. Switch the initiating checkout to the default branch only when that checkout is clean and current-session-owned.

package/plugins/expert.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.22.1",
+  "version": "3.24.0",
   "mode": "expert",
   "description": "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay sharp and learnings survive context resets.",
   "tools": [

package/skills/README.md

@@ -22,16 +22,16 @@ These add concrete enforcement to the 7 Laws. Tier-1 skills are the always-on mi
 | `gateguard` | PreToolUse fact-forcing gate that blocks Edit/Write/destructive Bash until concrete investigation is presented | Law 1 (Research) |
 | `model-forward` | Standing stance: go with Claude Code and the model, not against it — skills are scaffolding that merges into the model; the durable core is goal-driven execution + guardrails | All 7 Laws (stance) |
 | `recall` | BM25 search over the observation log so "have I hit this before?" is answerable before re-deriving a fix | Law 1 (Research) |
+| `ship` | Single-defect delivery path that preserves unrelated dirty work in an owner-locked worktree, verifies through TDD, opens one PR, and safely returns eligible clean checkouts to `main` or `master` | Laws 1, 3, and 4 |
 | `tdd-workflow` | RED→GREEN→REFACTOR enforcement, 80%+ coverage gate across unit/integration/E2E | Law 3 (One Thing), Law 4 (Verify) |
 | `verification-loop` | Six-phase verification (build, types, lint, tests, security, diff) with a structured PASS/FAIL report | Law 4 (Verify Before Reporting) |
 
 ## Tier 2 — additional skills for **expert** mode
 
-Tier-2 skills layer on top of tier-1 for users running `npx continuous-improvement install --mode expert`. They cover autonomous-mode safety, response-depth control, and context-window discipline that matter once an agent runs longer or more aggressively.
+Tier-2 skills layer on top of tier-1 for users running `npx continuous-improvement install --mode expert`. They cover response-depth control and context-window discipline that matter once an agent runs longer or more aggressively. Autonomous-mode write safety lives in tier-1 `gateguard` (`CI_GATEGUARD_TARGET_LOCK=block`), which replaced the retired `safety-guard` skill on 2026-08-07.
 
 | Skill | What it does | When it pays off |
 |-------|--------------|------------------|
-| `safety-guard` | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory | Autonomous loops, prod systems, `--dangerously-skip-permissions` sessions |
 | `token-budget-advisor` | Heuristic input/output token estimator that offers 25%/50%/75%/100% depth choices before answering | Long sessions where response size matters |
 | `strategic-compact` | Manual phase-boundary checklist for deciding when to run `/compact` (research→plan, plan→implement, debug→next) instead of relying on arbitrary auto-compaction | Multi-phase tasks that approach context limits |
 | `wild-risa-balance` | Decision-framing lens that pairs WILD (Wild/Imaginative/Limitless/Disruptive) generation with RISA (Realistic/Important/Specific/Agreeable) execution, used to split recommendation lists into bold pilots above a safe baseline | Multi-item recommendation blocks where bold options keep losing to safe ones in a flat list |

package/skills/deploy-receipt.md

@@ -157,7 +157,7 @@ The rollback command is **printed**, not run. The skill's job is to give the ope
 - `finishing-a-development-branch` (vendored, third-party/superpowers/) — runs first; reports the merge. This skill runs after.
 - `verification-loop` — same Law 4 family; this skill is the deploy-seam specialization
 - `proceed-with-the-recommendation` — routing-table row for "Merge / close branch" should pair `finishing-a-development-branch` with this skill when the project is auto-deploy
-- `safety-guard` — orthogonal; safety-guard prevents destructive ops, this verifies post-deploy state
+- `gateguard` — orthogonal; gateguard gates the destructive op, this verifies post-deploy state
 
 ## Close-the-Loop Rule
 

package/skills/gateguard.md

@@ -77,7 +77,7 @@ Before creating {file_path}, present these facts:
 
 ### Destructive Bash Gate (every destructive command)
 
-Triggers on: `rm -rf`, `git reset --hard`, `git push --force`, `drop table`, etc.
+Triggers on structured rules that ignore flag order and spelling — `rm` with any recursive plus any force flag (`rm -r -f`, `rm -Rf`, `rm --recursive --force`), `git clean` with a force flag and no dry run, `git checkout -- <path>` or `git checkout .`, `git restore <path>` unless it is `--staged` only, `find … -delete`, `git push` with a `+refspec`, `git stash drop|clear` — plus the original substring list (`rm -rf`, `git reset --hard`, `git push --force`, `git branch -D`, `drop table`, `truncate `, `Remove-Item -Recurse`, etc.). Each command is judged after `&&`, `||`, `|`, `;` splitting, and a commit message, PR body or title value is blanked first so prose never trips it. The deny reason prints `Matched rule: <id>` so a block is explainable; the classifier is `lib/destructive-bash.mjs`. Plain file writes through Bash (`cat > file`, `sed -i`) are deliberately not gated.
 
 ```
 1. List all files/data this command will modify or delete
@@ -154,10 +154,24 @@ The inline `_gateguard_facts_presented: true` retry still works on harnesses tha
 
 Set the `CI_GATEGUARD_EXCLUDE` environment variable to opt specific low-risk paths out of the gate entirely — an LLM-maintained prose wiki, a generated scratch directory, anything where the fact-forcing pause costs more than it saves. The value is a comma-separated list of path substrings, each matched case-insensitively against the forward-slash-normalized file path, so `/mywiki/` excludes `D:\Vault\MyWiki\notes\x.md`. Unset or empty (the default) changes nothing: every mutating file call is gated exactly as before, and a call that touches a mix of excluded and non-excluded paths still gates the non-excluded ones. Set it per project in `.claude/settings.json` under `env`, or globally in `~/.claude/settings.json`.
 
+An exclusion is never silent. When every target of a call is excluded, `hooks/gateguard.mjs` still allows it but prints one stderr line naming the fragment that matched (`gateguard: skipped by CI_GATEGUARD_EXCLUDE (fragment "docs/wiki" matched docs/wiki/page.md)`). A catch-all fragment that every path contains (`/`, `.`, any single character) is honoured too, but the line says what it really is: the file gate is off for this session. Destructive Bash is never excluded. If `/verify-install` reports the probe write went through, check this variable before concluding the hook is not wired.
+
 ### Locking edits to the current repo
 
 A fact-list can't catch a wrong-repo or wrong-worktree write — you can present perfect facts about the wrong file, in the wrong checkout. Set `CI_GATEGUARD_TARGET_LOCK=block` to make the runtime hook (`hooks/gateguard.mjs`) refuse any mutating call whose **absolute** target canonicalizes outside the session project root (`CLAUDE_PROJECT_DIR`, or the git toplevel). Relative paths resolve under the current directory (= the root) and always pass; only an absolute path into a different tree is denied, and the deny reason names both the stray target and the expected root. This runs before the fact gate and independent of clearance — a wrong-repo write is wrong even with facts. Unset (the default) checks nothing, so legitimate out-of-root edits (`~/.claude`, a `/tmp` scratch file, a sibling repo) are unaffected; turn it on per session in a multi-worktree or headless run where cross-repo writes are the real risk. Paths already covered by `CI_GATEGUARD_EXCLUDE` are never target-locked.
 
+### Migrating from `safety-guard` (retired 2026-08-07)
+
+`safety-guard` was a prose-only tier-2 skill describing three "modes" it never implemented — no hook, no command, no logger ever shipped with it. Every mode it described is already enforced here by the runtime hook (`hooks/gateguard.mjs`):
+
+| Retired `safety-guard` mode | What enforces it now |
+|---|---|
+| Careful — warn on `rm -rf`, `git push --force`, `git reset --hard`, `DROP TABLE`, `chmod 777`, `--no-verify` … | [Destructive Bash Gate](#destructive-bash-gate-every-destructive-command). Its pattern set is a superset of the retired watch list, and it blocks rather than warns. |
+| Freeze — restrict writes to one directory tree | `CI_GATEGUARD_TARGET_LOCK=block` (above). Canonicalizes the absolute target against the session project root and refuses strays — before the fact gate, independent of clearance. |
+| Guard — careful + freeze together | Both of the above; they compose. Narrow the surface further with `CI_GATEGUARD_EXCLUDE`. |
+
+If you previously opted into `safety-guard` for autonomous or production-adjacent runs, set `CI_GATEGUARD_TARGET_LOCK=block` for that session instead. That is a real refusal, not a checklist the agent can talk itself out of.
+
 ### Limitations and guarantees
 
 - **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 — counted per session — bounds damage from stuck loops or rogue agents.
@@ -188,5 +202,6 @@ The standalone `gateguard-ai` Python/CLI package referenced in earlier drafts of
 
 ## Related Skills
 
-- `safety-guard` — Runtime safety checks (complementary, not overlapping)
+- `worktree-safety` — validates the worktree root before a source write; this skill gates the write itself
+- `reconcile` — git ground truth before a destructive git action
 - `code-reviewer` — Post-edit review (GateGuard is pre-edit investigation)

package/skills/reconcile.md

@@ -177,6 +177,5 @@ git branch -d <type>/<slug>            # delete the merged feature branch (safe
 
 - **`recall`** (Law 1) — before a risky git op, recall whether the same operation failed on this repo before.
 - **`gateguard`** (Law 1) — the runtime gate (`hooks/gateguard.mjs`); `reconcile` is the procedure you run once a destructive git action is in play.
-- **`safety-guard`** — destructive-operation guardrails for production and autonomous runs.
 - **`audit`** (Law 4) — when an audit ends in a fix, `reconcile` is the safe path from branch to landed PR.
 - **`commit-commands:commit-push-pr`** — the external-plugin equivalent of the commit → push → PR tail; `reconcile` reimplements it inline so the flow works with no companion installed. For a TDD-gated single-defect variant, use `/ship`.