continuous-improvement 3.22.0 → 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.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.",
+      "version": "3.23.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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
+
+- **`ci-reconcile` blocks an unborn HEAD instead of treating it as a usable baseline** — `git init` with no commit yet is a real git repository, but `git rev-parse HEAD` fails there. The runner accepted that as a pinnable state, and `--snapshot` emitted an empty `head` field that reads like success. Now reported as a `head-commit` blocker, with `--snapshot` emitting `head: "unborn"` and `blocked: true`. (#291)
+- **`isSafeRefName` rejects ref shapes git itself rejects** — empty path components (`a//b`), dot-prefixed or dot-suffixed components (`a/.b`, `a/b.`), and a per-component `.lock` suffix (`a/b.lock/c`) previously passed. Validation is now component-by-component, closer to `git check-ref-format`. (#291)
+- **`parseRevListCounts` uses `Number.isSafeInteger`** — `Number.isInteger` accepts values beyond `MAX_SAFE_INTEGER`, where arithmetic silently loses precision. Out-of-range counts now read as `unknown`, consistent with the module's fail-closed stance. (#291)
+- **The CLI rejects malformed argument combinations instead of resolving them silently** — a repeated `--verify-push` or `--cwd` used to be last-wins, an empty or whitespace-only `--cwd` fell back to the process working directory, and `--snapshot` / `--explain` / `--verify-push` together picked one arbitrarily. Each is now an explicit error. (#291)
+
+### Changed
+
+- **`--snapshot` follows the same exit contract as the default mode** (`0` clear / `1` blocked / `2` not a repository) where it previously always exited `0`, and its envelope gains `blocked` and `blockers`. It still writes the JSON on a blocker, so a `set -e` script capturing a baseline must tolerate exit 1. Documented in the skill and command, along with the unborn-HEAD row. (#291)
+
 ## [3.22.0] — 2026-08-02
 
 ### Added

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/bin/reconcile.mjs

@@ -54,6 +54,7 @@ function parseArgs(args) {
         verifyPush: null,
         root: cwd(),
     };
+    let cwdProvided = false;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i] ?? "";
         if (arg === "--json")
@@ -63,6 +64,9 @@ function parseArgs(args) {
         else if (arg === "--explain")
             options.explain = true;
         else if (arg === "--verify-push") {
+            if (options.verifyPush !== null) {
+                throw new Error("--verify-push may only be provided once");
+            }
             const value = args[i + 1];
             if (value === undefined || value.startsWith("--")) {
                 throw new Error("--verify-push requires a branch name");
@@ -74,11 +78,15 @@ function parseArgs(args) {
             i++;
         }
         else if (arg === "--cwd") {
+            if (cwdProvided) {
+                throw new Error("--cwd may only be provided once");
+            }
             const value = args[i + 1];
-            if (value === undefined || value.startsWith("--")) {
+            if (value === undefined || value.startsWith("--") || value.trim().length === 0) {
                 throw new Error("--cwd requires a directory");
             }
             options.root = value;
+            cwdProvided = true;
             i++;
         }
         else if (arg === "--help" || arg === "-h") {
@@ -88,6 +96,14 @@ function parseArgs(args) {
             throw new Error(`unknown argument: ${arg}`);
         }
     }
+    const actions = [
+        options.snapshot ? "--snapshot" : null,
+        options.explain ? "--explain" : null,
+        options.verifyPush !== null ? "--verify-push" : null,
+    ].filter((action) => action !== null);
+    if (actions.length > 1) {
+        throw new Error(`mutually exclusive action modes: ${actions.join(", ")}`);
+    }
     return options;
 }
 /** Probe each in-progress marker through `--git-path`, which is worktree-correct. */
@@ -160,20 +176,35 @@ function main() {
     const status = git(["status", "--porcelain=v1"], options.root);
     const drift = git(["diff", "--name-only", "--ignore-all-space"], options.root);
     const dirty = accountDirty(status.code === 0 ? status.stdout : null, drift.code === 0 ? drift.stdout : null);
+    const inProgress = probeInProgress(options.root);
+    const baseFindings = assessGitState({
+        headCommit: headSha.code === 0 ? headSha.stdout.trim() : null,
+        head,
+        upstreamRef,
+        counts,
+        inProgress,
+        dirty,
+    });
     if (options.snapshot) {
-        // Field-compatible with scripts/git-state-snapshot.sh, plus `contentDrift`
-        // and `inProgress`, which the shell version cannot report.
+        // Field-compatible with scripts/git-state-snapshot.sh, plus `contentDrift`,
+        // `inProgress`, and a fail-closed blocker summary the shell version cannot
+        // report. An unborn HEAD is a git repo, but not a usable mutation baseline;
+        // do not emit an empty `head` field that looks like success.
         const upstreamSha = upstreamRef === null ? "none" : git(["rev-parse", "--short", "@{u}"], options.root).stdout.trim() || "none";
+        const shortHead = headSha.code === 0 ? git(["rev-parse", "--short", "HEAD"], options.root).stdout.trim() : "";
+        const blockers = baseFindings.filter((finding) => finding.severity === "blocker").map((finding) => finding.id);
         stdout.write(`${JSON.stringify({
-            head: git(["rev-parse", "--short", "HEAD"], options.root).stdout.trim(),
+            head: shortHead.length > 0 ? shortHead : "unborn",
             upstream: upstreamSha,
             dirty: dirty.reported,
             root: repoRoot,
             branch: head.branch ?? "detached",
             contentDrift: dirty.contentDrift,
-            inProgress: probeInProgress(options.root),
+            inProgress,
+            blocked: blockers.length > 0,
+            blockers,
         })}\n`);
-        exit(0);
+        exit(blockers.length > 0 ? 1 : 0);
         return;
     }
     if (options.verifyPush !== null) {
@@ -191,14 +222,7 @@ function main() {
         exit(verdict.verdict === "landed" ? 0 : 1);
         return;
     }
-    const inProgress = probeInProgress(options.root);
-    const findings = assessGitState({
-        head,
-        upstreamRef,
-        counts,
-        inProgress,
-        dirty,
-    });
+    const findings = [...baseFindings];
     const stashes = git(["stash", "list"], options.root);
     const stashCount = stashes.code === 0
         ? stashes.stdout.split(/\r?\n/).filter((line) => line.trim().length > 0).length

package/commands/reconcile.md

@@ -42,6 +42,9 @@ Four boundaries where the obvious command lies:
 - **Detached HEAD** — the `--show-current` form of `git branch` prints "" and exits 0, indistinguishable from success. `symbolic-ref --quiet` exits non-zero instead. Detached blocks.
 - **Linked worktree** — `.git` is a *file* there, so a `.git/`-relative marker probe exits 2 exactly as it does on a clean tree: a real conflicted merge reads as clean. Use `rev-parse --git-path`.
 - **autocrlf** — `git status` overstates drift. Stage by explicit filename, never `git add -A`.
+- **Unborn HEAD** — `git init` with no commit is a real repo with no usable baseline; `rev-parse HEAD` fails. Reported as `head: "unborn"` and blocked, never as an empty field that reads like success.
+
+`--snapshot` shares the exit contract (`0` clear / `1` blocked / `2` not a repo) and adds `contentDrift`, `inProgress`, `blocked`, `blockers` to the shell script's envelope. It still writes the JSON on a blocker, so tolerate exit 1 when capturing a baseline under `set -e`.
 
 ## Then act, with gates
 

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`.