continuous-improvement 3.22.1 → 3.23.0

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
   "plugins": [
     {
       "name": "continuous-improvement",
-      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.22.1",
+      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 29 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
+      "version": "3.23.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this skill are documented here.
 
 ---
 
+## [3.23.0] — 2026-08-15
+
+### Added
+
+- **`ship` is now a native tier-1 global skill** — the full single-defect workflow lives in `skills/ship.md`: detect `main` or `master` from the live remote, preserve unrelated dirty work in an owner-locked clean worktree, enforce RED/GREEN verification, open one PR, and return only eligible clean checkouts to the default branch. The legacy `/ship` command is now a thin argument-forwarding compatibility entry point, and the npm installer writes the user-invocable skill to `~/.claude/skills/ship/SKILL.md` without overwriting or removing an unowned skill at that generic path. Brings the bundle to 29 skills.
+
 ## [3.22.1] — 2026-08-04
 
 ### Fixed

package/README.md

@@ -270,7 +270,7 @@ Hooks capture every tool call. After ~20 observations Claude analyzes patterns a
 ## Slash commands
 
 <details>
-<summary><b>All 29 commands (Beginner gets every one)</b></summary>
+<summary><b>All 29 commands (marketplace bundle)</b></summary>
 
 `/seven-laws` is the canonical reflect-and-learn command. `/continuous-improvement` is kept as an alias for backward compatibility — both run the same workflow.
 
@@ -306,7 +306,7 @@ Hooks capture every tool call. After ~20 observations Claude analyzes patterns a
 /swarm                            Fan-out coordination across parallel sub-agents
 ```
 
-All 29 ship in the marketplace bundle. The Beginner install gets all of them — with one caveat: `/learn-eval`, `/harvest`, and `/distill` only produce useful output once Mulahazah has accumulated observation history (~20 observations), so running them on day 1 returns an empty result, not a broken command. `/swarm` and `/release-train` are orchestration commands aimed at larger multi-agent or multi-PR work. In Expert (`npx`) mode, the installer mirrors the full set into `~/.claude/commands/` and additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
+All 29 legacy commands ship in the marketplace bundle. The marketplace Beginner install gets all of them, with one caveat: `/learn-eval`, `/harvest`, and `/distill` only produce useful output once Mulahazah has accumulated observation history (~20 observations), so running them on day 1 returns an empty result, not a broken command. `/swarm` and `/release-train` are orchestration commands aimed at larger multi-agent or multi-PR work. The npm installer writes its curated command set and installs the native `ship` skill at `~/.claude/skills/ship/SKILL.md`; that user-invocable skill supplies `/ship` without creating a duplicate personal command. Expert npm mode additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
 
 </details>
 
@@ -314,7 +314,7 @@ All 29 ship in the marketplace bundle. The Beginner install gets all of them —
 
 ## Skills
 
-The plugin ships **28 skills** — 1 core + 1 featured + 6 tier-1 + 17 tier-2 + 3 always-bundled. Beginner install gets tier-1, featured, and the always-bundled companion; Expert adds tier-2, the MCP server, and observation hooks. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 29th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
+The plugin ships **29 skills** — 1 core + 1 featured + 7 tier-1 + 17 tier-2 + 3 always-bundled. Beginner install gets tier-1, featured, and the always-bundled companion; Expert adds tier-2, the MCP server, and observation hooks. The tier-1 `ship` skill is the single source for the `/ship` workflow and the npm installer makes it global across Claude Code projects. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 30th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
 
 ---
 
@@ -357,7 +357,7 @@ Proof-format templates ship in [templates/](templates/): `release_receipt_templa
 
 - [QUICKSTART.md](QUICKSTART.md) — 2-minute setup
 - [SKILL.md](SKILL.md) — full 7 Laws spec
-- [docs/skills.md](docs/skills.md) — full 28-skill catalog
+- [docs/skills.md](docs/skills.md) — full 29-skill catalog
 - [examples/](examples/) — bug fix, feature build, refactor walkthroughs
 - [templates/insights-claude-md.md](templates/insights-claude-md.md) — paste-in CLAUDE.md blocks for verification discipline, environment notes, think-before-acting, and git/deploy workflow (sourced from the 28-day usage report)
 - [CONTRIBUTING.md](CONTRIBUTING.md) — architecture, repo internals, adding a new skill

package/bin/install.mjs

@@ -9,10 +9,10 @@
  *   npx continuous-improvement install --target gemini,codex  # skill into other agents' rules files
  *   npx continuous-improvement install --uninstall    # remove everything
  */
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, realpathSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { execSync } from "node:child_process";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { PACKAGE_NAME, VERSION, getToolNames } from "../lib/plugin-metadata.mjs";
@@ -21,6 +21,7 @@ import { evaluateUpdateCheck, fetchLatestNpmVersion, isThrottled, pendingNotice,
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const SKILL_SOURCE = join(__dirname, "..", "SKILL.md");
+const SHIP_SKILL_SOURCE = join(__dirname, "..", "skills", "ship.md");
 const SKILL_NAME = "continuous-improvement";
 const REPO_ROOT = join(__dirname, "..");
 const COMMAND_FILES = [
@@ -124,17 +125,169 @@ const modeIndex = rawArgs.indexOf("--mode");
 const requestedMode = modeIndex !== -1 ? rawArgs[modeIndex + 1] : undefined;
 const INSTALL_MODE = isInstallMode(requestedMode) ? requestedMode : "beginner";
 const SKILL_DIR = join(getHomeDir(), ".claude", "skills", SKILL_NAME);
+const SHIP_SKILL_DIR = join(getHomeDir(), ".claude", "skills", "ship");
+const SHIP_SKILLS_DIR = dirname(SHIP_SKILL_DIR);
+const SHIP_STAGING_ROOT = join(getHomeDir(), ".claude", ".continuous-improvement-staging");
+const SHIP_SKILL_OWNER_FILE = join(SHIP_SKILL_DIR, ".continuous-improvement-owner");
+const SHIP_SKILL_OWNER = `${PACKAGE_NAME}\n`;
+function pathEntryExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function isOwnedShipSkill() {
+    try {
+        const dir = lstatSync(SHIP_SKILL_DIR);
+        const owner = lstatSync(SHIP_SKILL_OWNER_FILE);
+        if (!dir.isDirectory() || dir.isSymbolicLink())
+            return false;
+        if (!owner.isFile() || owner.isSymbolicLink() || owner.nlink !== 1)
+            return false;
+        return readFileSync(SHIP_SKILL_OWNER_FILE, "utf8") === SHIP_SKILL_OWNER;
+    }
+    catch {
+        return false;
+    }
+}
+function isSameOrChildPath(parent, candidate) {
+    const relativePath = relative(parent, candidate);
+    return (relativePath === "" ||
+        (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath)));
+}
+function getSafeShipStagingRoot() {
+    mkdirSync(dirname(SHIP_STAGING_ROOT), { recursive: true });
+    try {
+        mkdirSync(SHIP_STAGING_ROOT);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const stagingEntry = lstatSync(SHIP_STAGING_ROOT);
+    if (!stagingEntry.isDirectory() || stagingEntry.isSymbolicLink()) {
+        throw new Error(`Ship staging root must be a plain directory, not a link or junction: ${SHIP_STAGING_ROOT}`);
+    }
+    const stagingRoot = realpathSync(SHIP_STAGING_ROOT);
+    const skillsRoot = realpathSync(SHIP_SKILLS_DIR);
+    if (isSameOrChildPath(skillsRoot, stagingRoot)) {
+        throw new Error(`Ship staging root resolves inside skill discovery: ${stagingRoot}`);
+    }
+    return { stagingRoot, skillsRoot };
+}
+function stageShipSkill() {
+    mkdirSync(SHIP_SKILLS_DIR, { recursive: true });
+    const { stagingRoot, skillsRoot } = getSafeShipStagingRoot();
+    const createdStagingDir = mkdtempSync(join(stagingRoot, "ship-"));
+    try {
+        const stagingEntry = lstatSync(createdStagingDir);
+        const stagingDir = realpathSync(createdStagingDir);
+        if (!stagingEntry.isDirectory() ||
+            stagingEntry.isSymbolicLink() ||
+            !isSameOrChildPath(stagingRoot, stagingDir) ||
+            isSameOrChildPath(skillsRoot, stagingDir)) {
+            throw new Error(`Ship staging directory escaped its safe root: ${stagingDir}`);
+        }
+        copyFileSync(SHIP_SKILL_SOURCE, join(stagingDir, "SKILL.md"));
+        writeFileSync(join(stagingDir, ".continuous-improvement-owner"), SHIP_SKILL_OWNER);
+        return stagingDir;
+    }
+    catch (error) {
+        rmSync(createdStagingDir, { recursive: true, force: true });
+        throw error;
+    }
+}
+function installShipSkill() {
+    const shipSkillExists = pathEntryExists(SHIP_SKILL_DIR);
+    if (shipSkillExists && !isOwnedShipSkill()) {
+        console.warn(`  ! Preserved existing unowned ship skill at ${SHIP_SKILL_DIR}`);
+        return "preserved";
+    }
+    let stagingDir = "";
+    let preserveStagingDir = false;
+    try {
+        stagingDir = stageShipSkill();
+        if (shipSkillExists) {
+            const skillPath = join(SHIP_SKILL_DIR, "SKILL.md");
+            const previousSkillPath = join(stagingDir, "previous-SKILL.md");
+            let previousSkillMoved = false;
+            if (pathEntryExists(skillPath)) {
+                const skillEntry = lstatSync(skillPath);
+                if (skillEntry.isDirectory()) {
+                    throw new Error(`Refusing to replace directory at ${skillPath}`);
+                }
+                renameSync(skillPath, previousSkillPath);
+                previousSkillMoved = true;
+            }
+            try {
+                renameSync(join(stagingDir, "SKILL.md"), skillPath);
+            }
+            catch (error) {
+                if (previousSkillMoved) {
+                    try {
+                        renameSync(previousSkillPath, skillPath);
+                    }
+                    catch (restoreError) {
+                        preserveStagingDir = true;
+                        let recoveryRenameError = "";
+                        const stagedSkillPath = join(stagingDir, "SKILL.md");
+                        if (pathEntryExists(stagedSkillPath)) {
+                            try {
+                                renameSync(stagedSkillPath, join(stagingDir, "new-SKILL.md"));
+                            }
+                            catch (recoveryError) {
+                                recoveryRenameError = ` Recovery artifact rename also failed (${getErrorMessage(recoveryError)}).`;
+                            }
+                        }
+                        throw new Error(`Ship skill replacement failed (${getErrorMessage(error)}) and rollback failed (${getErrorMessage(restoreError)}).${recoveryRenameError} Recovery files retained outside skill discovery at ${stagingDir}`);
+                    }
+                }
+                throw error;
+            }
+            rmSync(stagingDir, { recursive: true });
+            stagingDir = "";
+        }
+        else {
+            renameSync(stagingDir, SHIP_SKILL_DIR);
+            stagingDir = "";
+        }
+        console.log(`  ✓ Global ship skill → ${SHIP_SKILL_DIR}/SKILL.md`);
+        return "installed";
+    }
+    catch (error) {
+        console.error(`  ✗ Global ship skill install failed: ${getErrorMessage(error)}`);
+        return "failed";
+    }
+    finally {
+        if (stagingDir && !preserveStagingDir) {
+            try {
+                if (pathEntryExists(stagingDir)) {
+                    rmSync(stagingDir, { recursive: true, force: true });
+                }
+            }
+            catch (cleanupError) {
+                console.error(`  ! Staged ship skill cleanup failed at ${stagingDir}: ${getErrorMessage(cleanupError)}`);
+            }
+        }
+    }
+}
 function installSkill() {
     try {
         mkdirSync(SKILL_DIR, { recursive: true });
         copyFileSync(SKILL_SOURCE, join(SKILL_DIR, "SKILL.md"));
         console.log(`  ✓ Claude Code skill → ${SKILL_DIR}/SKILL.md`);
+        const shipOutcome = installShipSkill();
         setupMulahazah();
-        return true;
+        return shipOutcome;
     }
     catch (error) {
         console.error(`  ✗ Install failed: ${getErrorMessage(error)}`);
-        return false;
+        return "failed";
     }
 }
 function setupMulahazah() {
@@ -326,9 +479,10 @@ function patchClaudeSettings(observePath) {
     }
 }
 function uninstallAll() {
-    console.log("\nUninstalling continuous-improvement skill...\n");
+    console.log("\nUninstalling continuous-improvement skills...\n");
     const home = getHomeDir();
     let removed = 0;
+    let failed = false;
     if (existsSync(SKILL_DIR)) {
         try {
             rmSync(SKILL_DIR, { recursive: true });
@@ -337,6 +491,23 @@ function uninstallAll() {
         }
         catch (error) {
             console.error(`  ✗ Skill removal failed: ${getErrorMessage(error)}`);
+            failed = true;
+        }
+    }
+    if (existsSync(SHIP_SKILL_DIR)) {
+        if (!isOwnedShipSkill()) {
+            console.warn(`  ! Preserved existing unowned ship skill at ${SHIP_SKILL_DIR}`);
+        }
+        else {
+            try {
+                rmSync(SHIP_SKILL_DIR, { recursive: true });
+                console.log("  ✓ Removed global ship skill");
+                removed++;
+            }
+            catch (error) {
+                console.error(`  ✗ Global ship skill removal failed: ${getErrorMessage(error)}`);
+                failed = true;
+            }
         }
     }
     for (const commandName of COMMAND_FILES) {
@@ -350,6 +521,7 @@ function uninstallAll() {
         }
         catch (error) {
             console.error(`  ✗ ${commandName}: ${getErrorMessage(error)}`);
+            failed = true;
         }
     }
     for (const hookFile of ["observe.sh", "session.sh", "session.mjs"]) {
@@ -363,6 +535,7 @@ function uninstallAll() {
         }
         catch (error) {
             console.error(`  ✗ ${hookFile}: ${getErrorMessage(error)}`);
+            failed = true;
         }
     }
     // Remove the Node observer artifacts deployed alongside observe.sh.
@@ -379,6 +552,7 @@ function uninstallAll() {
         }
         catch (error) {
             console.error(`  ✗ ${observerFile}: ${getErrorMessage(error)}`);
+            failed = true;
         }
     }
     const settingsPath = join(home, ".claude", "settings.json");
@@ -435,12 +609,17 @@ function uninstallAll() {
         }
         else {
             console.warn("  ! Could not clean settings.json — remove hooks manually");
+            failed = true;
         }
     }
     const desktopConfigPath = join(home, ".claude", "claude_desktop_config.json");
     if (existsSync(desktopConfigPath)) {
         const desktopConfig = readJsonFile(desktopConfigPath);
-        if (desktopConfig?.mcpServers?.["continuous-improvement"]) {
+        if (!desktopConfig) {
+            console.warn("  ! Could not clean claude_desktop_config.json — remove the MCP server manually");
+            failed = true;
+        }
+        else if (desktopConfig.mcpServers?.["continuous-improvement"]) {
             delete desktopConfig.mcpServers["continuous-improvement"];
             writeFileSync(desktopConfigPath, JSON.stringify(desktopConfig, null, 2) + "\n");
             console.log("  ✓ Removed MCP server from Claude Desktop config");
@@ -451,6 +630,7 @@ function uninstallAll() {
     }
     console.log("\n  Note: Instinct data in ~/.claude/instincts/ was preserved.\n" +
         "  To remove learned data too: rm -rf ~/.claude/instincts/\n");
+    return !failed;
 }
 function printUsage() {
     console.log(`
@@ -463,11 +643,11 @@ Subcommands:
 
 Options for 'install':
   --mode <mode>     Installation mode:
-                      beginner  — hooks + skill + commands (default)
+                      beginner  — hooks + skills + commands (default)
                       expert    — beginner + MCP server + session hooks
   --pack <name>     Load a starter instinct pack (react, python, go, meta)
   --target <names>  Comma-separated platform list (default: claude):
-                      claude    — full install: hooks + skill + commands
+                      claude    — full install: hooks + skills + commands
                       gemini    — GEMINI.md (Gemini CLI)
                       codex     — AGENTS.md (Codex CLI / agents.md standard)
                       cursor    — .cursor/rules/continuous-improvement.mdc
@@ -534,8 +714,7 @@ if (command === "backfill") {
     process.exit(0);
 }
 if (args.includes("--uninstall")) {
-    uninstallAll();
-    process.exit(0);
+    process.exit(uninstallAll() ? 0 : 1);
 }
 // --target <names>: comma-separated platform list, default claude-only.
 // Non-claude targets receive the skill text in their platform's rules file
@@ -597,7 +776,9 @@ Research → Plan → Execute → Verify → Reflect → Learn → Iterate
 `);
 warnOnMarketplaceCollision();
 console.log("Installing to Claude Code...\n");
-const installed = installSkill() ? 1 : 0;
+const installOutcome = installSkill();
+if (installOutcome === "failed")
+    process.exitCode = 1;
 const modeInfo = {
     beginner: "Hooks are capturing silently. System auto-levels as you use it.",
     expert: `Full plugin active: hooks + MCP server + session hooks. ${getToolNames("expert").length} tools available.`,
@@ -651,19 +832,23 @@ if (packIndex !== -1 && rawArgs[packIndex + 1]) {
         console.error(`  ✗ Unknown pack: ${packName}. Available: ${available.join(", ")}`);
     }
 }
-console.log(`
-${installed === 1 ? "Done." : "Failed."}
-${modeInfo[INSTALL_MODE]}
+const installedNextSteps = `${modeInfo[INSTALL_MODE]}
 
 Next steps:
   1. Start a new Claude Code session
   2. Say: "Use the continuous-improvement framework to [your task]"
-  3. If a task needs persistent planning, run: /planning-with-files
-  4. After your first task, run: /continuous-improvement
-  5. Try: /discipline for quick reference, /dashboard for instinct health
+  3. For one defect, run: /ship [one-line defect description]
+  4. If a task needs persistent planning, run: /planning-with-files
+  5. After your first task, run: /continuous-improvement
+  6. Try: /discipline for quick reference, /dashboard for instinct health
 ${INSTALL_MODE === "expert" ? `\nMCP tools available (${getToolNames("expert").length}): ${getToolNames("expert").join(", ")}` : ""}
-Available instinct packs: npx continuous-improvement install --pack react|python|go|meta
-`);
+Available instinct packs: npx continuous-improvement install --pack react|python|go|meta`;
+const installSummary = installOutcome === "installed"
+    ? `Done.\n${installedNextSteps}`
+    : installOutcome === "preserved"
+        ? `Done with warning.\n${modeInfo[INSTALL_MODE]}\n\nPackage /ship was not installed because an existing unowned ship skill was preserved. Resolve that collision, then reinstall before using the package workflow.`
+        : "Failed.\nInstallation incomplete. Fix the errors above and rerun the installer. Do not assume hooks, skills, or commands are ready.";
+console.log(`\n${installSummary}\n`);
 // Update-available nudge for the npm/CLI install path (the marketplace path is
 // covered by Claude Code's native plugin auto-update). Reads the public npm
 // registry only — no telemetry. Throttled, default-on, off via

package/commands/ship.md

@@ -1,57 +1,13 @@
 ---
 name: ship
-description: "Single-defect fast path — walk one bug from ground-truth audit through a TDD fix, full verification, a single-concern commit, and an open PR, then stop. Never auto-merges, never deploys. For multi-PR rollouts use /release-train instead."
+description: "Compatibility entry point for the native ship skill. Passes one defect request through unchanged."
+argument-hint: "[one-line defect description]"
 ---
 
 # /ship
 
-The one-defect fast path. `/release-train` is for stacked multi-PR rollouts and `/proceed-with-the-recommendation` walks an arbitrary recommendation list; `/ship` is the common case: fix one defect, open one PR, hand it back for review.
+Invoke the native `ship` skill with this complete defect request:
 
-Pure routing over existing skills. It adds no new orchestration logic and it does NOT bypass branch protection, force-push, auto-merge, or deploy.
+$ARGUMENTS
 
-## Usage
-
-```
-/ship <one-line description of the defect>
-```
-
-If the description is ambiguous or names more than one concern, `/ship` halts and asks you to narrow it — one defect per run.
-
-## Behavior
-
-In order, for the single defect:
-
-1. **Ground truth** — `reconcile` (or its inline fallback): confirm the working tree is clean and on a feature branch cut from an up-to-date `origin/<base>`. If on a protected branch or a stale base, halt and ask.
-2. **Reproduce (RED)** — `tdd-workflow`: write a failing test that reproduces the defect; watch it fail. Pre-test implementation code is deleted, not kept.
-3. **Fix (GREEN)** — write the minimal change that makes the test pass; watch it pass. One concern only.
-4. **Verify** — `verification-loop`: run the project's verify ladder (build, types, tests). Build-green is evidence of mechanism, not of the fix — confirm the defect itself no longer reproduces.
-5. **Commit** — one commit, one concern, staged by explicit filename (never `git add -A`). Use a Windows-safe commit message: a single-line `-m` (repeat `-m` for paragraphs) or `git commit -F <tempfile>` — no multi-line here-docs/here-strings.
-6. **Open PR** — `commit-commands:commit-push-pr` (or `gh pr create`): push the branch and open a single-concern PR that cites the plan or issue. **Stop here.** The merge is yours.
-7. **Deploy receipt (advisory)** — after you merge, `deploy-receipt` verifies the deployed SHA matches the merge SHA. Advisory only; `/ship` does not deploy.
-
-## Hard stops (halt and ask, never improvise)
-
-- Ambiguous or multi-concern defect description.
-- Working tree not clean, or branch is protected / cut from a stale base.
-- Any verification step fails with a non-obvious fix.
-- The fix would touch more than 15 non-generated files (that is no longer one concern — split it, or use `/release-train`).
-- Push would target a protected branch.
-
-## Anti-patterns this command refuses
-
-- **Auto-merge.** Never merges the PR it opens, even when CI is green.
-- **Deploy.** Never runs a deploy; `deploy-receipt` only verifies after you merge.
-- **Bypass.** No `--admin`, `--force`, `--no-verify`.
-- **Bundled concerns.** Will not fold an unrelated fix into the same commit; logs it as a deferred follow-up instead.
-
-## Composition
-
-Routes through, in order: `reconcile` → `tdd-workflow` → `verification-loop` → `commit-commands:commit-push-pr` → `deploy-receipt`. Each step falls back to its inline behavior when the preferred skill is not installed.
-
-## Example
-
-```
-/ship registration form accepts a negative deposit amount
-```
-
-Reconciles git state, writes a failing test asserting deposits must be positive, implements the guard, runs the verify ladder, commits one concern with a single-line message, opens the PR, and stops for your review.
+Follow that skill exactly. Do not reconstruct or duplicate its Git, worktree, TDD, return, cleanup, merge, or deploy rules here. If the native skill is unavailable, stop and tell the operator to update or reinstall `continuous-improvement`.

package/lib/plugin-metadata.mjs

@@ -26,7 +26,7 @@ const KEYWORDS = [
     "transcript-linter",
 ];
 const CLAUDE_PLUGIN_CATEGORY = "productivity";
-const SHARED_PLUGIN_DESCRIPTION = "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.";
+const SHARED_PLUGIN_DESCRIPTION = "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 29 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.";
 // Four vendored upstream companions registered alongside the CI plugin.
 // Each entry points at a pinned-SHA snapshot under third-party/<name>/.
 // See third-party/MANIFEST.md for refresh recipes and per-snapshot
@@ -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.",
     },

package/llms.txt

@@ -1,6 +1,6 @@
 # continuous-improvement
 
-> The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.
+> The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 29 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.
 
 ## What This Is
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "continuous-improvement",
-  "version": "3.22.1",
-  "description": "Claude Code that gets sharper every session: the persistent-memory and runtime-discipline layer built on the 7 Laws of AI Agent Discipline. It grounds every edit in real facts before it lands and, through the Mulahazah engine, turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
+  "version": "3.23.0",
+  "description": "Claude Code that gets sharper every session: the persistent-memory and runtime-discipline layer built on the 7 Laws of AI Agent Discipline. It grounds every edit in real facts before it lands and, through the Mulahazah engine, turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Shipped as 29 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
   "keywords": [
     "claude-code",
     "claude-code-plugin",

package/plugins/beginner.json

@@ -1,8 +1,8 @@
 {
   "name": "continuous-improvement",
-  "version": "3.22.1",
+  "version": "3.23.0",
   "mode": "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.",
   "tools": [
     {
       "name": "ci_status",

package/plugins/continuous-improvement/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
   "plugins": [
     {
       "name": "continuous-improvement",
-      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.22.1",
+      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 29 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
+      "version": "3.23.0",
       "source": "./",
       "author": {
         "name": "naimkatiman"

package/plugins/continuous-improvement/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "continuous-improvement",
-  "version": "3.22.1",
-  "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
+  "version": "3.23.0",
+  "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 29 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
   "author": {
     "name": "naimkatiman",
     "url": "https://github.com/naimkatiman"

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

@@ -1,57 +1,13 @@
 ---
 name: ship
-description: "Single-defect fast path — walk one bug from ground-truth audit through a TDD fix, full verification, a single-concern commit, and an open PR, then stop. Never auto-merges, never deploys. For multi-PR rollouts use /release-train instead."
+description: "Compatibility entry point for the native ship skill. Passes one defect request through unchanged."
+argument-hint: "[one-line defect description]"
 ---
 
 # /ship
 
-The one-defect fast path. `/release-train` is for stacked multi-PR rollouts and `/proceed-with-the-recommendation` walks an arbitrary recommendation list; `/ship` is the common case: fix one defect, open one PR, hand it back for review.
+Invoke the native `ship` skill with this complete defect request:
 
-Pure routing over existing skills. It adds no new orchestration logic and it does NOT bypass branch protection, force-push, auto-merge, or deploy.
+$ARGUMENTS
 
-## Usage
-
-```
-/ship <one-line description of the defect>
-```
-
-If the description is ambiguous or names more than one concern, `/ship` halts and asks you to narrow it — one defect per run.
-
-## Behavior
-
-In order, for the single defect:
-
-1. **Ground truth** — `reconcile` (or its inline fallback): confirm the working tree is clean and on a feature branch cut from an up-to-date `origin/<base>`. If on a protected branch or a stale base, halt and ask.
-2. **Reproduce (RED)** — `tdd-workflow`: write a failing test that reproduces the defect; watch it fail. Pre-test implementation code is deleted, not kept.
-3. **Fix (GREEN)** — write the minimal change that makes the test pass; watch it pass. One concern only.
-4. **Verify** — `verification-loop`: run the project's verify ladder (build, types, tests). Build-green is evidence of mechanism, not of the fix — confirm the defect itself no longer reproduces.
-5. **Commit** — one commit, one concern, staged by explicit filename (never `git add -A`). Use a Windows-safe commit message: a single-line `-m` (repeat `-m` for paragraphs) or `git commit -F <tempfile>` — no multi-line here-docs/here-strings.
-6. **Open PR** — `commit-commands:commit-push-pr` (or `gh pr create`): push the branch and open a single-concern PR that cites the plan or issue. **Stop here.** The merge is yours.
-7. **Deploy receipt (advisory)** — after you merge, `deploy-receipt` verifies the deployed SHA matches the merge SHA. Advisory only; `/ship` does not deploy.
-
-## Hard stops (halt and ask, never improvise)
-
-- Ambiguous or multi-concern defect description.
-- Working tree not clean, or branch is protected / cut from a stale base.
-- Any verification step fails with a non-obvious fix.
-- The fix would touch more than 15 non-generated files (that is no longer one concern — split it, or use `/release-train`).
-- Push would target a protected branch.
-
-## Anti-patterns this command refuses
-
-- **Auto-merge.** Never merges the PR it opens, even when CI is green.
-- **Deploy.** Never runs a deploy; `deploy-receipt` only verifies after you merge.
-- **Bypass.** No `--admin`, `--force`, `--no-verify`.
-- **Bundled concerns.** Will not fold an unrelated fix into the same commit; logs it as a deferred follow-up instead.
-
-## Composition
-
-Routes through, in order: `reconcile` → `tdd-workflow` → `verification-loop` → `commit-commands:commit-push-pr` → `deploy-receipt`. Each step falls back to its inline behavior when the preferred skill is not installed.
-
-## Example
-
-```
-/ship registration form accepts a negative deposit amount
-```
-
-Reconciles git state, writes a failing test asserting deposits must be positive, implements the guard, runs the verify ladder, commits one concern with a single-line message, opens the PR, and stops for your review.
+Follow that skill exactly. Do not reconstruct or duplicate its Git, worktree, TDD, return, cleanup, merge, or deploy rules here. If the native skill is unavailable, stop and tell the operator to update or reinstall `continuous-improvement`.

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

@@ -26,7 +26,7 @@ const KEYWORDS = [
     "transcript-linter",
 ];
 const CLAUDE_PLUGIN_CATEGORY = "productivity";
-const SHARED_PLUGIN_DESCRIPTION = "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.";
+const SHARED_PLUGIN_DESCRIPTION = "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 29 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.";
 // Four vendored upstream companions registered alongside the CI plugin.
 // Each entry points at a pinned-SHA snapshot under third-party/<name>/.
 // See third-party/MANIFEST.md for refresh recipes and per-snapshot
@@ -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.",
     },

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.
 

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.23.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,6 +22,7 @@ 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) |
 

package/skills/ship.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.