continuous-improvement 3.22.1 → 3.24.0

package/bin/install.mjs

@@ -9,18 +9,18 @@
  *   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 { execSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, realpathSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 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";
+import { hashProjectRoot, resolveProjectRoot } from "../lib/gateguard-state.mjs";
 import { TARGET_IDS, planTargetWrites, resolveTargets } from "../lib/install-targets.mjs";
 import { evaluateUpdateCheck, fetchLatestNpmVersion, isThrottled, pendingNotice, } from "../lib/version-check.mjs";
 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 +124,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 +478,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 +490,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 +520,7 @@ function uninstallAll() {
         }
         catch (error) {
             console.error(`  ✗ ${commandName}: ${getErrorMessage(error)}`);
+            failed = true;
         }
     }
     for (const hookFile of ["observe.sh", "session.sh", "session.mjs"]) {
@@ -363,6 +534,7 @@ function uninstallAll() {
         }
         catch (error) {
             console.error(`  ✗ ${hookFile}: ${getErrorMessage(error)}`);
+            failed = true;
         }
     }
     // Remove the Node observer artifacts deployed alongside observe.sh.
@@ -379,6 +551,7 @@ function uninstallAll() {
         }
         catch (error) {
             console.error(`  ✗ ${observerFile}: ${getErrorMessage(error)}`);
+            failed = true;
         }
     }
     const settingsPath = join(home, ".claude", "settings.json");
@@ -435,12 +608,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 +629,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 +642,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
@@ -494,19 +673,10 @@ Examples:
 `);
 }
 function getProjectHashSync() {
-    try {
-        // No shell redirect — `2>/dev/null` breaks under cmd.exe (tries to open a
-        // file literally named /dev/null); ignore stderr via stdio instead.
-        const root = execSync("git rev-parse --show-toplevel", {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-        const hash = createHash("sha256").update(root).digest("hex").slice(0, 12);
-        return { root, hash };
-    }
-    catch {
+    const root = resolveProjectRoot();
+    if (root === "global")
         return { root: "global", hash: "global" };
-    }
+    return { root, hash: hashProjectRoot(root) };
 }
 const args = process.argv.slice(2);
 const command = args[0];
@@ -534,8 +704,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 +766,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 +822,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/mcp-server.mjs

@@ -16,12 +16,11 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
-import { createHash } from "node:crypto";
 import { PACKAGE_NAME, VERSION, getToolDefinitions, isPluginMode, } from "../lib/plugin-metadata.mjs";
 import { formatDriftReport, parseGoalFromPlan, scoreObservations, } from "../lib/goal-state.mjs";
 import { buildIndex, formatRecallHits, parseSince, query as queryRecall, } from "../lib/recall-index.mjs";
 import { draftFromCandidate, draftFromWorkflowRun, extractTrajectories, findCandidates, formatCandidates, serializeDraft, workflowRunFromObservations, } from "../lib/skill-distill.mjs";
-import { MAX_CLEARED_FILES, canonicalizeFileKey, clearFiles, resolveInstinctsRoot, resolveSessionDir, } from "../lib/gateguard-state.mjs";
+import { MAX_CLEARED_FILES, canonicalizeFileKey, clearFiles, hashProjectRoot, resolveInstinctsRoot, resolveProjectRoot, resolveSessionDir, } from "../lib/gateguard-state.mjs";
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
@@ -93,14 +92,10 @@ const modeIndex = args.indexOf("--mode");
 const requestedMode = args[modeIndex + 1];
 const MODE = isPluginMode(requestedMode) ? requestedMode : "beginner";
 function getProjectHash() {
-    try {
-        const root = execSync("git rev-parse --show-toplevel 2>/dev/null", { encoding: "utf8" }).trim();
-        const hash = createHash("sha256").update(root).digest("hex").slice(0, 12);
-        return { root, hash, name: basename(root) };
-    }
-    catch {
+    const root = resolveProjectRoot();
+    if (root === "global")
         return { root: "global", hash: "global", name: "global" };
-    }
+    return { root, hash: hashProjectRoot(root), name: basename(root) };
 }
 function readInstincts(projectHash) {
     const instincts = [];

package/bin/observe.mjs

@@ -16,10 +16,10 @@
 //
 // See docs/plans/2026-05-05-node-observer-rich-schema.md for the full design.
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
+import { canonicalizeProjectRoot, hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { parseHookPayload, summariseInput, summariseOutput } from "../lib/observe-event.mjs";
 const ROTATION_LINE_THRESHOLD = 10_000;
 const ARCHIVE_RETENTION = 10;
@@ -40,8 +40,8 @@ function runObserver() {
     const payload = parseHookPayload(raw);
     if (!payload)
         return;
-    const projectRoot = resolveProjectRoot();
-    const projectHash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    const projectRoot = canonicalizeProjectRoot(resolveProjectRoot());
+    const projectHash = hashProjectRoot(projectRoot);
     const projectName = basename(projectRoot.replace(/\.git$/, ""));
     const instinctsDir = join(getHomeDir(), ".claude", "instincts");
     const projectDir = join(instinctsDir, projectHash);

package/bin/reconcile-instinct-hashes.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Merge instinct buckets that are the same project under different path
+ * spellings (C:/ vs c:/ vs C:\). observe/gateguard now hash the canonical
+ * root; this CLI copies history into that hash and leaves an alias marker
+ * on the old dir. Idempotent. Never deletes a directory.
+ *
+ * Usage:
+ *   node bin/reconcile-instinct-hashes.mjs --dry-run
+ *   node bin/reconcile-instinct-hashes.mjs --apply
+ *   node bin/reconcile-instinct-hashes.mjs --apply --only 3ef4426c6e15 --only 137f2f54ec70
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, exit } from "node:process";
+import { canonicalizeProjectRoot, hashProjectRoot, resolveInstinctsRoot } from "../lib/gateguard-state.mjs";
+function countJsonl(path) {
+    if (!existsSync(path))
+        return 0;
+    return readFileSync(path, "utf8").split(/\n/).filter((line) => line.trim() !== "").length;
+}
+function isoNow() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function discoverGroups(instinctsRoot) {
+    const groups = new Map();
+    let entries;
+    try {
+        entries = readdirSync(instinctsRoot);
+    }
+    catch {
+        return [];
+    }
+    for (const name of entries) {
+        if (name === "global")
+            continue;
+        const dir = join(instinctsRoot, name);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (existsSync(join(dir, "alias.json")) && !existsSync(join(dir, "observations.jsonl"))) {
+            continue;
+        }
+        const projectPath = join(dir, "project.json");
+        if (!existsSync(projectPath))
+            continue;
+        let project;
+        try {
+            project = JSON.parse(readFileSync(projectPath, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (!project.root)
+            continue;
+        const canonicalRoot = canonicalizeProjectRoot(project.root);
+        const canonicalHash = hashProjectRoot(canonicalRoot);
+        const bucket = {
+            hash: name,
+            root: project.root,
+            name: project.name ?? name,
+            rows: countJsonl(join(dir, "observations.jsonl")),
+        };
+        const existing = groups.get(canonicalHash);
+        if (existing) {
+            existing.members.push(bucket);
+        }
+        else {
+            groups.set(canonicalHash, {
+                canonicalHash,
+                canonicalRoot,
+                name: project.name ?? name,
+                members: [bucket],
+            });
+        }
+    }
+    return [...groups.values()].filter((group) => group.members.some((member) => member.hash !== group.canonicalHash && member.rows > 0));
+}
+function parseTs(line) {
+    try {
+        const parsed = JSON.parse(line);
+        const value = Date.parse(parsed.ts ?? "");
+        return Number.isFinite(value) ? value : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function mergeJsonl(sources) {
+    const rows = [];
+    const seen = new Set();
+    for (const file of sources) {
+        if (!existsSync(file))
+            continue;
+        for (const line of readFileSync(file, "utf8").split(/\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed || seen.has(trimmed))
+                continue;
+            seen.add(trimmed);
+            rows.push(trimmed);
+        }
+    }
+    rows.sort((a, b) => parseTs(a) - parseTs(b) || a.localeCompare(b));
+    return rows.length === 0 ? "" : `${rows.join("\n")}\n`;
+}
+export function selectGroups(groups, only) {
+    if (only.length === 0)
+        return groups;
+    const wanted = new Set(only);
+    return groups.filter((group) => wanted.has(group.canonicalHash) || group.members.some((member) => wanted.has(member.hash)));
+}
+export function applyGroup(instinctsRoot, group) {
+    const destDir = join(instinctsRoot, group.canonicalHash);
+    mkdirSync(destDir, { recursive: true });
+    const destObs = join(destDir, "observations.jsonl");
+    const sources = group.members
+        .map((member) => join(instinctsRoot, member.hash, "observations.jsonl"))
+        .filter((path) => existsSync(path));
+    const merged = mergeJsonl(sources);
+    writeFileSync(destObs, merged, "utf8");
+    let createdAt = isoNow();
+    const destProject = join(destDir, "project.json");
+    if (existsSync(destProject)) {
+        try {
+            const existing = JSON.parse(readFileSync(destProject, "utf8"));
+            if (existing.created_at)
+                createdAt = existing.created_at;
+        }
+        catch {
+            // rewrite below
+        }
+    }
+    writeFileSync(destProject, `${JSON.stringify({
+        id: group.canonicalHash,
+        name: group.name,
+        root: group.canonicalRoot,
+        created_at: createdAt,
+    })}\n`, "utf8");
+    const aliases = [];
+    for (const member of group.members) {
+        if (member.hash === group.canonicalHash)
+            continue;
+        const srcDir = join(instinctsRoot, member.hash);
+        try {
+            for (const file of readdirSync(srcDir)) {
+                if (!file.endsWith(".yaml"))
+                    continue;
+                const dest = join(destDir, file);
+                if (!existsSync(dest))
+                    copyFileSync(join(srcDir, file), dest);
+            }
+        }
+        catch {
+            // missing dir is non-fatal
+        }
+        const srcObs = join(srcDir, "observations.jsonl");
+        if (existsSync(srcObs)) {
+            renameSync(srcObs, join(srcDir, `observations.migrated-to-${group.canonicalHash}.jsonl`));
+        }
+        writeFileSync(join(srcDir, "alias.json"), `${JSON.stringify({
+            canonical: group.canonicalHash,
+            canonical_root: group.canonicalRoot,
+            migrated_at: isoNow(),
+            rows: member.rows,
+        })}\n`, "utf8");
+        aliases.push(member.hash);
+    }
+    const copiedRows = merged === "" ? 0 : merged.trim().split("\n").length;
+    return { copiedRows, aliases };
+}
+function printPlan(groups) {
+    if (groups.length === 0) {
+        console.log("No alias observation buckets to merge.");
+        return;
+    }
+    console.log(`Alias groups: ${groups.length}`);
+    for (const group of groups) {
+        console.log(`  ${group.name} → ${group.canonicalHash} (${group.canonicalRoot})`);
+        for (const member of group.members) {
+            const mark = member.hash === group.canonicalHash ? "canonical" : "alias";
+            console.log(`    ${member.hash}  ${member.rows} rows  ${mark}  root=${member.root}`);
+        }
+    }
+}
+function parseOnly(args) {
+    const only = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === "--only" && args[i + 1]) {
+            only.push(args[i + 1]);
+            i += 1;
+        }
+    }
+    return only;
+}
+function main() {
+    const args = argv.slice(2);
+    const apply = args.includes("--apply");
+    const dryRun = args.includes("--dry-run") || !apply;
+    const instinctsRoot = resolveInstinctsRoot();
+    const groups = selectGroups(discoverGroups(instinctsRoot), parseOnly(args));
+    printPlan(groups);
+    if (dryRun) {
+        if (groups.length > 0)
+            console.log("\nRe-run with --apply to merge.");
+        return;
+    }
+    for (const group of groups) {
+        const result = applyGroup(instinctsRoot, group);
+        console.log(`merged ${result.copiedRows} rows into ${group.canonicalHash}; aliases ${result.aliases.join(",") || "(none)"}`);
+    }
+}
+const invokedDirectly = argv[1]?.endsWith("reconcile-instinct-hashes.mjs");
+if (invokedDirectly) {
+    try {
+        main();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        exit(1);
+    }
+}

package/commands/discipline.md

@@ -19,6 +19,8 @@ Print this card and check yourself against each law.
 | 6 | **Iterate One Change** | Am I changing one thing at a time? | "And also..." |
 | 7 | **Learn From Every Session** | Did I capture this as an instinct? | "Next time I'll..." |
 
+Read the seven as three moments around every act. **Before** (Laws 1, 2): set the terms. **During** (Laws 3, 6): watch yourself. **After** (Laws 4, 5, 7): settle the account and carry it forward. Every check is an audit you run on yourself; every red flag is you hoping instead. The sentence this comes from, and its sources: `docs/philosophy.md`.
+
 ## Operator Stakes
 
 The Laws above are the *how*. These five principles are the *why*: code ships from your account, the incident lands on your pager, the bill hits your budget. Each one pairs with the Law that prevents it from going wrong.
@@ -31,7 +33,7 @@ The Laws above are the *how*. These five principles are the *why*: code ships fr
 | 4 | **Problem framing** | Builds the websocket chat the ticket asked for | Finds out users wanted faster support replies, not chat | 1 |
 | 5 | **Constraints management** | Calls the $0.02/image model on every upload | Does the math, adds client-side validation + caching + cheaper triage model | 2 |
 
-Code is a liability, not an asset. Speed without these five turns into someone else's incident at 3am — except the someone is you.
+Code is a liability, not an asset. Speed without these five turns into someone else's incident at 3am — except the someone is you. The other half of the why is not fear: the session ends and the context is gone, so the only work that survives is what you verified and wrote down for the one who comes after, whether that is tomorrow's session or the engineer who inherits the repo.
 
 ## Goal-Driven Execution maps onto the Laws
 
@@ -61,5 +63,6 @@ Before saying "Done", verify ALL:
 - [ ] I checked the **actual** result (not assumed)
 - [ ] Build passes
 - [ ] I can explain the change in one sentence
+- [ ] For each item above I checked, not hoped
 
-If you're skipping a step, that's the step you need most.
+If you're skipping a step, that's the step you need most. The step you skip is the one you are hoping through.