codymaster 4.8.0 → 7.0.0

package/dist/execution/tdd-gate.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * TDD Enforcement Gate — blocks execution without tests.
+ *
+ * TRIZ Principle #10 (Prior Action):
+ *   Pre-flight check scans for test files BEFORE execution starts.
+ *
+ * TRIZ Principle #3 (Local Quality):
+ *   Each task must have its own test file before implementation.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findTestFile = findTestFile;
+exports.suggestTestFile = suggestTestFile;
+exports.runTests = runTests;
+exports.enforceTDD = enforceTDD;
+exports.hasTestFile = hasTestFile;
+const fs_1 = __importDefault(require("fs"));
+const child_process_1 = require("child_process");
+/**
+ * Find test file for a given source file.
+ * Mapping: src/foo.ts → test/foo.test.ts
+ *          src/bar/baz.ts → test/bar/baz.test.ts
+ */
+function findTestFile(sourceFile) {
+    const testFile = sourceFile
+        .replace(/^src\//, 'test/')
+        .replace(/\.ts$/, '.test.ts')
+        .replace(/\.js$/, '.test.js');
+    return fs_1.default.existsSync(testFile) ? testFile : null;
+}
+/**
+ * Suggest test file path for a given source file.
+ */
+function suggestTestFile(sourceFile) {
+    return sourceFile
+        .replace(/^src\//, 'test/')
+        .replace(/\.ts$/, '.test.ts')
+        .replace(/\.js$/, '.test.js');
+}
+/**
+ * Run tests for a specific test file and return failure count.
+ */
+function runTests(testFile) {
+    try {
+        const output = (0, child_process_1.execSync)(`npx vitest run ${testFile} --reporter=verbose`, {
+            encoding: 'utf-8',
+            timeout: 30000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return { failures: 0, output };
+    }
+    catch (error) {
+        // vitest exits with non-zero code when tests fail
+        const output = error.stdout || error.stderr || '';
+        const failMatch = output.match(/(\d+) failed/);
+        const failures = failMatch ? parseInt(failMatch[1], 10) : 1;
+        return { failures, output };
+    }
+}
+/**
+ * Enforce TDD: verify test file exists and has failing tests (RED phase).
+ *
+ * Rules:
+ * 1. Test file MUST exist for target source file
+ * 2. Tests MUST fail (RED phase) before implementation
+ * 3. If all tests pass, user must write a failing test first
+ */
+function enforceTDD(targetFiles) {
+    for (const file of targetFiles) {
+        // Skip test files themselves
+        if (file.includes('.test.') || file.includes('.spec.')) {
+            continue;
+        }
+        // Skip non-source files
+        if (!file.startsWith('src/') && !file.startsWith('lib/')) {
+            continue;
+        }
+        const testFile = findTestFile(file);
+        if (!testFile) {
+            return {
+                passed: false,
+                testFile: null,
+                message: `TDD GATE: No test file found for ${file}. Write test first: ${suggestTestFile(file)}`,
+            };
+        }
+        const result = runTests(testFile);
+        if (result.failures === 0) {
+            return {
+                passed: false,
+                testFile,
+                message: `TDD GATE: All tests pass in ${testFile}. Write a failing test for new behavior first (RED phase).`,
+            };
+        }
+    }
+    return { passed: true, testFile: null, message: 'TDD GATE: OK — failing tests found (RED phase)' };
+}
+/**
+ * Quick check: does test file exist? (no execution, fast)
+ */
+function hasTestFile(targetFiles) {
+    for (const file of targetFiles) {
+        if (file.includes('.test.') || file.includes('.spec.'))
+            continue;
+        if (!file.startsWith('src/') && !file.startsWith('lib/'))
+            continue;
+        if (!findTestFile(file))
+            return false;
+    }
+    return true;
+}

package/dist/execution-analyzer.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionAnalyzer = void 0;
+exports.qualityWeight = qualityWeight;
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+const context_bus_1 = require("./context-bus");
+const storage_backend_1 = require("./storage-backend");
+const retro_summary_1 = require("./retro-summary");
+function bucketLatency(latencyMs) {
+    if (latencyMs === undefined || latencyMs < 0)
+        return undefined;
+    if (latencyMs < 1000)
+        return 'subsecond';
+    if (latencyMs < 5000)
+        return 'fast';
+    if (latencyMs < 15000)
+        return 'medium';
+    return 'slow';
+}
+function buildRetroSummary(projectPath, limit = 3) {
+    const retroPath = path_1.default.join(projectPath, '.cm', 'operational-learnings.jsonl');
+    const entries = (0, retro_summary_1.loadRetroEntries)(retroPath).slice(-limit);
+    if (entries.length === 0)
+        return undefined;
+    return entries.map((entry) => `- [${entry.tool}] ${entry.note}`).join('\n');
+}
+function normalizeJudgments(input) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+    const map = new Map();
+    for (const skill of (_a = input.selectedSkills) !== null && _a !== void 0 ? _a : []) {
+        map.set(skill, {
+            skill,
+            selected: true,
+            applied: true,
+            task_completed: input.taskStatus === 'completed',
+            fallback_used: false,
+        });
+    }
+    for (const observation of (_b = input.skillObservations) !== null && _b !== void 0 ? _b : []) {
+        const current = (_c = map.get(observation.skill)) !== null && _c !== void 0 ? _c : { skill: observation.skill };
+        map.set(observation.skill, {
+            skill: observation.skill,
+            selected: (_e = (_d = observation.selected) !== null && _d !== void 0 ? _d : current.selected) !== null && _e !== void 0 ? _e : false,
+            applied: (_g = (_f = observation.applied) !== null && _f !== void 0 ? _f : current.applied) !== null && _g !== void 0 ? _g : ((_j = (_h = observation.selected) !== null && _h !== void 0 ? _h : current.selected) !== null && _j !== void 0 ? _j : false),
+            task_completed: input.taskStatus === 'completed',
+            fallback_used: (_l = (_k = observation.fallbackUsed) !== null && _k !== void 0 ? _k : current.fallback_used) !== null && _l !== void 0 ? _l : false,
+            token_estimate: (_m = observation.tokenEstimate) !== null && _m !== void 0 ? _m : current.token_estimate,
+            note: (_o = observation.note) !== null && _o !== void 0 ? _o : current.note,
+            relevance_score: (_p = observation.relevanceScore) !== null && _p !== void 0 ? _p : current.relevance_score,
+        });
+    }
+    return Array.from(map.values());
+}
+function qualityWeight(metric) {
+    if (!metric)
+        return 0.5;
+    const base = Math.max(metric.selections, 1);
+    const applicationRate = metric.applications / base;
+    const completionRate = metric.task_completions / base;
+    const fallbackPenalty = metric.fallbacks / base;
+    const weighted = (applicationRate * 0.35) + (completionRate * 0.5) + ((1 - fallbackPenalty) * 0.15);
+    return Math.max(0, Math.min(1, weighted));
+}
+function buildAdvisory(taskStatus, judgments, backend) {
+    const activeSkills = judgments.filter((judgment) => judgment.selected || judgment.applied).map((judgment) => judgment.skill);
+    const fallbackSkills = judgments.filter((judgment) => judgment.fallback_used).map((judgment) => judgment.skill);
+    if (taskStatus !== 'completed' && activeSkills.length > 0) {
+        const weakest = activeSkills
+            .map((skill) => ({ skill, weight: qualityWeight(backend.getSkillMetric(skill)) }))
+            .sort((a, b) => a.weight - b.weight)[0];
+        const targetSkills = weakest ? [weakest.skill] : activeSkills.slice(0, 1);
+        return {
+            action: 'FIX',
+            confidence: weakest ? Math.max(0.68, 0.82 - weakest.weight * 0.2) : 0.72,
+            reason: 'Task did not complete successfully while selected skills were active.',
+            targetSkills,
+        };
+    }
+    if (taskStatus === 'completed' && activeSkills.length === 0) {
+        return {
+            action: 'CAPTURED',
+            confidence: 0.76,
+            reason: 'Task completed without any tracked skill usage, suggesting a reusable pattern worth capturing.',
+            targetSkills: [],
+        };
+    }
+    if (taskStatus === 'completed' && fallbackSkills.length > 0) {
+        return {
+            action: 'DERIVED',
+            confidence: 0.74,
+            reason: 'Task completed, but fallback handling suggests the current skill may need a specialized derived variant.',
+            targetSkills: fallbackSkills,
+        };
+    }
+    return {
+        reason: 'No evolution action recommended from the current execution signal.',
+        targetSkills: [],
+    };
+}
+class ExecutionAnalyzer {
+    constructor(projectPath, backend) {
+        this.projectPath = projectPath;
+        this.backend = backend !== null && backend !== void 0 ? backend : (0, storage_backend_1.getBackend)(projectPath);
+        this.backend.initialize();
+    }
+    analyzeExecution(input) {
+        var _a, _b, _c;
+        const judgments = normalizeJudgments(input);
+        const bus = (0, context_bus_1.readBus)(this.projectPath);
+        const retroSummary = buildRetroSummary(this.projectPath);
+        const advisory = buildAdvisory(input.taskStatus, judgments, this.backend);
+        const analysis = {
+            id: crypto_1.default.randomUUID(),
+            task_title: input.taskTitle,
+            status: input.taskStatus,
+            summary: (_a = input.summary) !== null && _a !== void 0 ? _a : `${input.taskStatus.toUpperCase()}: ${input.taskTitle}`,
+            source_task_type: input.sourceTaskType,
+            session_id: (_b = input.sessionId) !== null && _b !== void 0 ? _b : bus === null || bus === void 0 ? void 0 : bus.session_id,
+            chain_id: input.chainId,
+            selected_skills: (_c = input.selectedSkills) !== null && _c !== void 0 ? _c : judgments.filter((judgment) => judgment.selected).map((judgment) => judgment.skill),
+            token_estimate: input.tokenEstimate,
+            latency_bucket: bucketLatency(input.latencyMs),
+            bus_snapshot: bus ? JSON.stringify(bus.shared_context) : undefined,
+            retro_summary: retroSummary,
+            recommended_action: advisory.action,
+            confidence: advisory.confidence,
+            skill_judgments: judgments,
+            created_at: new Date().toISOString(),
+        };
+        this.backend.recordExecutionAnalysis(analysis);
+        return analysis;
+    }
+}
+exports.ExecutionAnalyzer = ExecutionAnalyzer;

package/dist/executor/cancel.js

@@ -0,0 +1,34 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cancelTask = cancelTask;
+const child_process_1 = require("child_process");
+const os_1 = __importDefault(require("os"));
+function cancelTask(taskId, pgid) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (os_1.default.platform() === 'win32') {
+            (0, child_process_1.execFileSync)('taskkill', ['/PID', String(pgid), '/T', '/F'], { timeout: 10000 });
+        }
+        else {
+            process.kill(-pgid, 'SIGTERM');
+            yield new Promise(resolve => setTimeout(resolve, 5000));
+            try {
+                process.kill(-pgid, 'SIGKILL');
+            }
+            catch (_a) {
+                // already dead
+            }
+        }
+    });
+}

package/dist/executor/gc.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startGcLoop = startGcLoop;
+exports.gcPass = gcPass;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const WORKSPACES_ROOT = path_1.default.join(os_1.default.homedir(), '.cm', 'workspaces');
+const DEFAULT_GC_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const DEFAULT_GC_ORPHAN_TTL_MS = 72 * 60 * 60 * 1000; // 72h
+const GC_INTERVAL_MS = 60 * 60 * 1000; // 1h
+function startGcLoop() {
+    return setInterval(() => {
+        gcPass();
+    }, GC_INTERVAL_MS);
+}
+function gcPass() {
+    let removed = 0;
+    let errors = 0;
+    if (!fs_1.default.existsSync(WORKSPACES_ROOT)) {
+        return { removed, errors };
+    }
+    const now = Date.now();
+    try {
+        const projects = fs_1.default.readdirSync(WORKSPACES_ROOT);
+        for (const project of projects) {
+            const projectDir = path_1.default.join(WORKSPACES_ROOT, project);
+            if (!fs_1.default.statSync(projectDir).isDirectory())
+                continue;
+            try {
+                const tasks = fs_1.default.readdirSync(projectDir);
+                for (const task of tasks) {
+                    const taskDir = path_1.default.join(projectDir, task);
+                    if (!fs_1.default.statSync(taskDir).isDirectory())
+                        continue;
+                    const gcMetaPath = path_1.default.join(taskDir, '.gc_meta.json');
+                    try {
+                        if (fs_1.default.existsSync(gcMetaPath)) {
+                            const meta = JSON.parse(fs_1.default.readFileSync(gcMetaPath, 'utf-8'));
+                            if (meta.completedAt) {
+                                const completedTime = new Date(meta.completedAt).getTime();
+                                if (now - completedTime > DEFAULT_GC_TTL_MS) {
+                                    fs_1.default.rmSync(taskDir, { recursive: true, force: true });
+                                    removed++;
+                                }
+                            }
+                        }
+                        else {
+                            const stat = fs_1.default.statSync(taskDir);
+                            const age = now - stat.mtimeMs;
+                            if (age > DEFAULT_GC_ORPHAN_TTL_MS) {
+                                fs_1.default.rmSync(taskDir, { recursive: true, force: true });
+                                removed++;
+                            }
+                        }
+                    }
+                    catch (_a) {
+                        errors++;
+                    }
+                }
+            }
+            catch (_b) {
+                errors++;
+            }
+        }
+    }
+    catch (_c) {
+        errors++;
+    }
+    return { removed, errors };
+}

package/dist/executor/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cancelTask = exports.runTask = exports.gcPass = exports.startGcLoop = exports.reuseWorkdir = exports.writeGcMeta = exports.prepareWorkdir = void 0;
+var workdir_1 = require("./workdir");
+Object.defineProperty(exports, "prepareWorkdir", { enumerable: true, get: function () { return workdir_1.prepareWorkdir; } });
+Object.defineProperty(exports, "writeGcMeta", { enumerable: true, get: function () { return workdir_1.writeGcMeta; } });
+Object.defineProperty(exports, "reuseWorkdir", { enumerable: true, get: function () { return workdir_1.reuseWorkdir; } });
+var gc_1 = require("./gc");
+Object.defineProperty(exports, "startGcLoop", { enumerable: true, get: function () { return gc_1.startGcLoop; } });
+Object.defineProperty(exports, "gcPass", { enumerable: true, get: function () { return gc_1.gcPass; } });
+var runner_1 = require("./runner");
+Object.defineProperty(exports, "runTask", { enumerable: true, get: function () { return runner_1.runTask; } });
+var cancel_1 = require("./cancel");
+Object.defineProperty(exports, "cancelTask", { enumerable: true, get: function () { return cancel_1.cancelTask; } });

package/dist/executor/runner.js

@@ -0,0 +1,70 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTask = runTask;
+const workdir_1 = require("./workdir");
+function runTask(opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { backend, taskId, projectId, prompt, execOpts, eventBus, priorWorkdir, pinnedSessionId, } = opts;
+        const projectShort = projectId.slice(0, 8);
+        const taskShort = taskId.slice(0, 8);
+        const workdir = priorWorkdir !== null && priorWorkdir !== void 0 ? priorWorkdir : (0, workdir_1.prepareWorkdir)(projectShort, taskShort);
+        const resolvedOpts = Object.assign(Object.assign({}, execOpts), { cwd: workdir, resumeSessionId: pinnedSessionId !== null && pinnedSessionId !== void 0 ? pinnedSessionId : execOpts.resumeSessionId });
+        const session = yield backend.execute(prompt, resolvedOpts);
+        let lastSessionId = pinnedSessionId;
+        const messageLoop = (() => __awaiter(this, void 0, void 0, function* () {
+            var _a, e_1, _b, _c;
+            try {
+                for (var _d = true, _e = __asyncValues(session.messages), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const msg = _c;
+                    emitAgentMessage(eventBus, taskId, projectId, msg);
+                    if (msg.type === 'text' && msg.sessionId) {
+                        lastSessionId = msg.sessionId;
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }))();
+        const [result] = yield Promise.all([session.result, messageLoop]);
+        if (lastSessionId && !result.sessionId) {
+            result.sessionId = lastSessionId;
+        }
+        (0, workdir_1.writeGcMeta)(projectShort, taskShort, {
+            taskId,
+            projectId,
+            completedAt: new Date().toISOString(),
+        });
+        return result;
+    });
+}
+function emitAgentMessage(eventBus, taskId, projectId, msg) {
+    eventBus.emitTask({
+        type: 'task.message',
+        taskId,
+        projectId,
+        data: { message: msg },
+    });
+}

package/dist/executor/workdir.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareWorkdir = prepareWorkdir;
+exports.writeGcMeta = writeGcMeta;
+exports.reuseWorkdir = reuseWorkdir;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const WORKSPACES_ROOT = path_1.default.join(os_1.default.homedir(), '.cm', 'workspaces');
+function prepareWorkdir(projectShort, taskShort) {
+    const workdir = path_1.default.join(WORKSPACES_ROOT, projectShort, taskShort, 'workdir');
+    fs_1.default.mkdirSync(workdir, { recursive: true });
+    const outputDir = path_1.default.join(WORKSPACES_ROOT, projectShort, taskShort, 'output');
+    const logsDir = path_1.default.join(WORKSPACES_ROOT, projectShort, taskShort, 'logs');
+    fs_1.default.mkdirSync(outputDir, { recursive: true });
+    fs_1.default.mkdirSync(logsDir, { recursive: true });
+    return workdir;
+}
+function writeGcMeta(projectShort, taskShort, meta) {
+    const metaPath = path_1.default.join(WORKSPACES_ROOT, projectShort, taskShort, '.gc_meta.json');
+    fs_1.default.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+}
+function reuseWorkdir(existingPath) {
+    if (!fs_1.default.existsSync(existingPath)) {
+        throw new Error(`Workdir not found: ${existingPath}`);
+    }
+    return existingPath;
+}

package/dist/handoff/contracts.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Handoff JSON contracts for the sprint flow (v2.0).
+ *
+ * Each sprint phase emits a typed handoff JSON under `.cm/handoff/`.
+ * Downstream skills read the predecessor's handoff to pick up cold,
+ * eliminating re-derivation cost.
+ *
+ * Schema versioning: every contract has a `schema: "<name>@<n>"` field.
+ * Bump @n on breaking change; readers should reject unknown majors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HANDOFF_FILENAMES = void 0;
+exports.HANDOFF_FILENAMES = {
+    'intent@1': 'intent.json',
+    'plan@1': 'plan.json',
+    'exec@1': 'exec.json',
+    'review@1': 'review.json',
+    'quality@1': 'quality.json',
+    'retro@1': 'retro.json',
+    'party@1': 'party.json',
+};

package/dist/handoff/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./contracts.js"), exports);
+__exportStar(require("./io.js"), exports);

package/dist/handoff/io.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Handoff JSON read/write helpers.
+ *
+ * Files live under `<projectPath>/.cm/handoff/<name>.json`.
+ * Validation is intentionally lightweight (no zod dep) — schema field +
+ * required key presence is enough to catch drift early.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandoffError = void 0;
+exports.handoffPath = handoffPath;
+exports.ensureHandoffDir = ensureHandoffDir;
+exports.validateHandoff = validateHandoff;
+exports.writeHandoff = writeHandoff;
+exports.readHandoff = readHandoff;
+exports.listHandoffs = listHandoffs;
+exports.clearHandoffs = clearHandoffs;
+exports.nowIso = nowIso;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const contracts_js_1 = require("./contracts.js");
+class HandoffError extends Error {
+}
+exports.HandoffError = HandoffError;
+function handoffDir(projectPath) {
+    return path_1.default.join(projectPath, '.cm', 'handoff');
+}
+function handoffPath(projectPath, schema) {
+    return path_1.default.join(handoffDir(projectPath), contracts_js_1.HANDOFF_FILENAMES[schema]);
+}
+function ensureHandoffDir(projectPath) {
+    const d = handoffDir(projectPath);
+    if (!fs_1.default.existsSync(d))
+        fs_1.default.mkdirSync(d, { recursive: true });
+}
+/** Required top-level keys for every envelope. */
+const ENVELOPE_KEYS = ['schema', 'emitted_at', 'emitted_by', 'data'];
+/** Per-schema required keys inside `data`. */
+const DATA_KEYS = {
+    'intent@1': ['problem', 'success_criteria', 'constraints', 'options_considered'],
+    'plan@1': ['goal', 'decisions', 'first_tasks'],
+    'exec@1': ['completed_tasks', 'pending_tasks', 'files_changed', 'test_status'],
+    'review@1': ['verdict', 'findings', 'must_fix_count'],
+    'quality@1': ['gates_passed', 'gates_failed', 'safe_to_ship', 'evidence'],
+    'retro@1': ['sprint_id', 'learnings'],
+    'party@1': ['topic', 'personas'],
+};
+function validateHandoff(obj) {
+    if (!obj || typeof obj !== 'object') {
+        throw new HandoffError('handoff must be an object');
+    }
+    const o = obj;
+    for (const k of ENVELOPE_KEYS) {
+        if (!(k in o))
+            throw new HandoffError(`handoff missing key: ${k}`);
+    }
+    const schema = o.schema;
+    if (typeof schema !== 'string' || !(schema in contracts_js_1.HANDOFF_FILENAMES)) {
+        throw new HandoffError(`unknown schema: ${String(schema)}`);
+    }
+    const data = o.data;
+    if (!data || typeof data !== 'object') {
+        throw new HandoffError('handoff.data must be an object');
+    }
+    const required = DATA_KEYS[schema];
+    for (const k of required) {
+        if (!(k in data)) {
+            throw new HandoffError(`handoff[${schema}].data missing key: ${k}`);
+        }
+    }
+}
+function writeHandoff(projectPath, handoff) {
+    validateHandoff(handoff);
+    ensureHandoffDir(projectPath);
+    const file = handoffPath(projectPath, handoff.schema);
+    fs_1.default.writeFileSync(file, JSON.stringify(handoff, null, 2), 'utf8');
+    return file;
+}
+function readHandoff(projectPath, schema) {
+    const file = handoffPath(projectPath, schema);
+    if (!fs_1.default.existsSync(file))
+        return null;
+    const raw = fs_1.default.readFileSync(file, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new HandoffError(`handoff file is not valid JSON: ${file}`);
+    }
+    validateHandoff(parsed);
+    if (parsed.schema !== schema) {
+        throw new HandoffError(`handoff schema mismatch: expected ${schema}, got ${parsed.schema}`);
+    }
+    return parsed;
+}
+function listHandoffs(projectPath) {
+    const d = handoffDir(projectPath);
+    if (!fs_1.default.existsSync(d))
+        return [];
+    return fs_1.default.readdirSync(d).filter((f) => f.endsWith('.json'));
+}
+function clearHandoffs(projectPath) {
+    const d = handoffDir(projectPath);
+    if (!fs_1.default.existsSync(d))
+        return 0;
+    let n = 0;
+    for (const f of fs_1.default.readdirSync(d)) {
+        if (f.endsWith('.json')) {
+            fs_1.default.unlinkSync(path_1.default.join(d, f));
+            n++;
+        }
+    }
+    return n;
+}
+function nowIso() {
+    return new Date().toISOString();
+}

package/dist/index.js

@@ -31,9 +31,6 @@ function main() {
         // ─── Registration ──────────────────────────────────────────────────────────
         // Register all modular commands
         (0, command_registry_1.registerAllCommands)(program);
-        // ─── Update Check ──────────────────────────────────────────────────────────
-        // Run update check in background (non-blocking)
-        (0, update_check_1.checkForUpdates)().catch(() => { });
         // ─── Execution ─────────────────────────────────────────────────────────────
         // Parse arguments and execute
         program.parse(process.argv);
@@ -41,6 +38,13 @@ function main() {
         if (process.argv.length <= 2) {
             program.help();
         }
+        // ─── Update Check (after command runs, non-blocking) ───────────────────────
+        // Show update notification in background after command completes
+        (0, update_check_1.checkForUpdates)().then((info) => {
+            if (info) {
+                (0, update_check_1.promptForUpgrade)(info).catch(() => { });
+            }
+        }).catch(() => { });
     });
 }
 // Error handling for uncaught exceptions