@soleri/core 9.0.3 → 9.2.0

package/dist/planning/impact-analyzer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Impact Analyzer — post-implementation impact analysis.
+ *
+ * Scans modified files for downstream consumers (imports/requires),
+ * detects scope violations, and assigns a risk level.
+ * Uses only `fs` and `path` — zero external dependencies.
+ */
+export interface AffectedConsumer {
+    file: string;
+    imports: string[];
+}
+export interface ImpactReport {
+    modifiedFiles: string[];
+    affectedConsumers: AffectedConsumer[];
+    untestedConsumers: string[];
+    scopeViolations: string[];
+    riskLevel: 'low' | 'medium' | 'high';
+    recommendations: string[];
+}
+export declare class ImpactAnalyzer {
+    /**
+     * Analyze the downstream impact of modified files.
+     */
+    analyzeImpact(modifiedFiles: string[], projectPath: string, planScope?: string[]): ImpactReport;
+}
+//# sourceMappingURL=impact-analyzer.d.ts.map

package/dist/planning/impact-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-analyzer.d.ts","sourceRoot":"","sources":["../../src/planning/impact-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AA6BD,qBAAa,cAAc;IACzB;;OAEG;IACH,aAAa,CACX,aAAa,EAAE,MAAM,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,YAAY;CAyBhB"}

package/dist/planning/impact-analyzer.js

@@ -0,0 +1,199 @@
+/**
+ * Impact Analyzer — post-implementation impact analysis.
+ *
+ * Scans modified files for downstream consumers (imports/requires),
+ * detects scope violations, and assigns a risk level.
+ * Uses only `fs` and `path` — zero external dependencies.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, basename, extname } from 'node:path';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CODE_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.vue', '.svelte',
+]);
+const TEST_PATTERNS = [
+    /\.test\./,
+    /\.spec\./,
+    /__tests__/,
+    /\.stories\./,
+];
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'coverage',
+    '.next', '.nuxt', '.svelte-kit', '.turbo',
+]);
+const MAX_FILES = 5000;
+// ---------------------------------------------------------------------------
+// ImpactAnalyzer
+// ---------------------------------------------------------------------------
+export class ImpactAnalyzer {
+    /**
+     * Analyze the downstream impact of modified files.
+     */
+    analyzeImpact(modifiedFiles, projectPath, planScope) {
+        if (modifiedFiles.length === 0 || !existsSync(projectPath)) {
+            return emptyReport(modifiedFiles);
+        }
+        const sourceFiles = collectSourceFiles(projectPath);
+        const consumers = findConsumers(modifiedFiles, sourceFiles, projectPath);
+        const untestedConsumers = filterUntested(consumers);
+        const scopeViolations = detectScopeViolations(modifiedFiles, planScope);
+        const riskLevel = assessRisk(consumers.length);
+        const recommendations = buildRecommendations(consumers, untestedConsumers, scopeViolations);
+        return {
+            modifiedFiles,
+            affectedConsumers: consumers,
+            untestedConsumers,
+            scopeViolations,
+            riskLevel,
+            recommendations,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers (all synchronous, all < 30 LOC)
+// ---------------------------------------------------------------------------
+function emptyReport(modifiedFiles) {
+    return {
+        modifiedFiles,
+        affectedConsumers: [],
+        untestedConsumers: [],
+        scopeViolations: [],
+        riskLevel: 'low',
+        recommendations: [],
+    };
+}
+/**
+ * Recursively collect source files under projectPath (up to MAX_FILES).
+ */
+function collectSourceFiles(dir, result = []) {
+    if (result.length >= MAX_FILES)
+        return result;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return result;
+    }
+    for (const entry of entries) {
+        if (result.length >= MAX_FILES)
+            break;
+        if (SKIP_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let stat;
+        try {
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            collectSourceFiles(full, result);
+        }
+        else if (CODE_EXTENSIONS.has(extname(entry))) {
+            result.push(full);
+        }
+    }
+    return result;
+}
+/**
+ * Find source files that import any of the modified files.
+ */
+function findConsumers(modifiedFiles, sourceFiles, projectPath) {
+    const patterns = buildImportPatterns(modifiedFiles, projectPath);
+    if (patterns.length === 0)
+        return [];
+    const consumers = [];
+    for (const file of sourceFiles) {
+        // Skip the modified files themselves
+        if (modifiedFiles.some((m) => file.endsWith(m) || file === m))
+            continue;
+        const matched = matchImports(file, patterns);
+        if (matched.length > 0) {
+            consumers.push({ file: relative(projectPath, file), imports: matched });
+        }
+    }
+    return consumers;
+}
+/**
+ * Build regex-friendly stems from modified file paths.
+ */
+function buildImportPatterns(modifiedFiles, projectPath) {
+    return modifiedFiles.map((f) => {
+        const rel = f.startsWith('/') ? relative(projectPath, f) : f;
+        // Strip extension for import matching
+        const stem = rel.replace(/\.[^.]+$/, '');
+        // Also match the bare filename without extension
+        const bare = basename(rel).replace(/\.[^.]+$/, '');
+        return bare.length >= 3 ? bare : stem;
+    }).filter((p) => p.length >= 3);
+}
+/**
+ * Read a file and return which patterns appear in its import/require lines.
+ */
+function matchImports(filePath, patterns) {
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const importRegex = /(?:import\s+.*?from\s+['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\))/g;
+    const importPaths = [];
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+        importPaths.push(match[1] ?? match[2]);
+    }
+    return patterns.filter((p) => importPaths.some((imp) => imp.includes(p)));
+}
+/**
+ * Filter consumers that are NOT test files.
+ */
+function filterUntested(consumers) {
+    return consumers
+        .map((c) => c.file)
+        .filter((f) => !TEST_PATTERNS.some((p) => p.test(f)));
+}
+/**
+ * Flag modified files not in the declared plan scope.
+ */
+function detectScopeViolations(modifiedFiles, planScope) {
+    if (!planScope || planScope.length === 0)
+        return [];
+    return modifiedFiles.filter((f) => {
+        const lower = f.toLowerCase();
+        return !planScope.some((s) => lower.includes(s.toLowerCase()));
+    });
+}
+/**
+ * Assign risk based on consumer count.
+ */
+function assessRisk(consumerCount) {
+    if (consumerCount <= 1)
+        return 'low';
+    if (consumerCount <= 5)
+        return 'medium';
+    return 'high';
+}
+/**
+ * Generate actionable recommendation strings.
+ */
+function buildRecommendations(consumers, untestedConsumers, scopeViolations) {
+    const recs = [];
+    if (consumers.length > 0) {
+        recs.push(`Run tests for ${consumers.length} affected consumer(s): ${consumers.map((c) => c.file).slice(0, 5).join(', ')}`);
+    }
+    for (const file of untestedConsumers.slice(0, 3)) {
+        recs.push(`Review import changes in ${file} (no test coverage detected)`);
+    }
+    for (const file of scopeViolations.slice(0, 3)) {
+        recs.push(`Scope violation: ${file} was modified but not in the declared plan scope`);
+    }
+    return recs;
+}
+//# sourceMappingURL=impact-analyzer.js.map

package/dist/planning/impact-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-analyzer.js","sourceRoot":"","sources":["../../src/planning/impact-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoB9D,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC5C,MAAM,EAAE,SAAS;CAClB,CAAC,CAAC;AAEH,MAAM,aAAa,GAAG;IACpB,UAAU;IACV,UAAU;IACV,WAAW;IACX,aAAa;CACd,CAAC;AAEF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU;IACnD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ;CAC1C,CAAC,CAAC;AAEH,MAAM,SAAS,GAAG,IAAI,CAAC;AAEvB,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,OAAO,cAAc;IACzB;;OAEG;IACH,aAAa,CACX,aAAuB,EACvB,WAAmB,EACnB,SAAoB;QAEpB,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3D,OAAO,WAAW,CAAC,aAAa,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,WAAW,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;QACpD,MAAM,SAAS,GAAG,aAAa,CAAC,aAAa,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;QACzE,MAAM,iBAAiB,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;QACpD,MAAM,eAAe,GAAG,qBAAqB,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QACxE,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,eAAe,GAAG,oBAAoB,CAC1C,SAAS,EACT,iBAAiB,EACjB,eAAe,CAChB,CAAC;QAEF,OAAO;YACL,aAAa;YACb,iBAAiB,EAAE,SAAS;YAC5B,iBAAiB;YACjB,eAAe;YACf,SAAS;YACT,eAAe;SAChB,CAAC;IACJ,CAAC;CACF;AAED,8EAA8E;AAC9E,0CAA0C;AAC1C,8EAA8E;AAE9E,SAAS,WAAW,CAAC,aAAuB;IAC1C,OAAO;QACL,aAAa;QACb,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;QACrB,eAAe,EAAE,EAAE;QACnB,SAAS,EAAE,KAAK;QAChB,eAAe,EAAE,EAAE;KACpB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,GAAW,EAAE,SAAmB,EAAE;IAC5D,IAAI,MAAM,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,MAAM,CAAC;IAE9C,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,MAAM,CAAC,MAAM,IAAI,SAAS;YAAE,MAAM;QACtC,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAEnC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC;QACT,IAAI,CAAC;YACH,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CACpB,aAAuB,EACvB,WAAqB,EACrB,WAAmB;IAEnB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,MAAM,SAAS,GAAuB,EAAE,CAAC;IAEzC,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,qCAAqC;QACrC,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC;YAAE,SAAS;QAExE,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAC1B,aAAuB,EACvB,WAAmB;IAEnB,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7B,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,sCAAsC;QACtC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACzC,iDAAiD;QACjD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,QAAgB,EAAE,QAAkB;IACxD,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,WAAW,GAAG,+EAA+E,CAAC;IACpG,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpD,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3B,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAC3C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,SAA6B;IACnD,OAAO,SAAS;SACb,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;GAEG;AACH,SAAS,qBAAqB,CAC5B,aAAuB,EACvB,SAAoB;IAEpB,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpD,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAChC,MAAM,KAAK,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9B,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,aAAqB;IACvC,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAC3B,SAA6B,EAC7B,iBAA2B,EAC3B,eAAyB;IAEzB,MAAM,IAAI,GAAa,EAAE,CAAC;IAE1B,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CACP,iBAAiB,SAAS,CAAC,MAAM,0BAA0B,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACjH,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,4BAA4B,IAAI,8BAA8B,CAAC,CAAC;IAC5E,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,oBAAoB,IAAI,kDAAkD,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/planning/plan-lifecycle.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Plan lifecycle FSM — state transitions, grade thresholds, and structural validation.
+ * Extracted from planner.ts to isolate pure lifecycle logic from persistence.
+ */
+import type { PlanGap } from './gap-types.js';
+/**
+ * Plan lifecycle status.
+ * Ported from Salvador's PlanLifecycleStatus with full 8-state lifecycle.
+ *
+ * Lifecycle: brainstorming → draft → approved → executing → [validating] → reconciling → completed → archived
+ */
+export type PlanStatus = 'brainstorming' | 'draft' | 'approved' | 'executing' | 'validating' | 'reconciling' | 'completed' | 'archived';
+/**
+ * Valid status transitions.
+ * Each key maps to the set of statuses it can transition to.
+ * Ported from Salvador's LIFECYCLE_TRANSITIONS.
+ */
+export declare const LIFECYCLE_TRANSITIONS: Record<PlanStatus, PlanStatus[]>;
+/**
+ * Statuses where the 30-minute TTL should NOT apply.
+ * Plans in these states may span multiple sessions.
+ */
+export declare const NON_EXPIRING_STATUSES: PlanStatus[];
+/**
+ * Validate a lifecycle status transition.
+ * Returns true if the transition is valid, false otherwise.
+ */
+export declare function isValidTransition(from: PlanStatus, to: PlanStatus): boolean;
+/**
+ * Get the valid next statuses for a given status.
+ */
+export declare function getValidNextStatuses(status: PlanStatus): PlanStatus[];
+/**
+ * Check if a status should have TTL expiration.
+ * Plans in executing/reconciling states persist indefinitely.
+ */
+export declare function shouldExpire(status: PlanStatus): boolean;
+/**
+ * Apply an FSM transition to a plan status.
+ * Throws if the transition is invalid. Returns the new status and timestamp.
+ * Does NOT mutate the plan — caller applies the result.
+ */
+export declare function applyTransition(currentStatus: PlanStatus, targetStatus: PlanStatus): {
+    status: PlanStatus;
+    updatedAt: number;
+};
+export type PlanGrade = 'A+' | 'A' | 'B' | 'C' | 'D' | 'F';
+/**
+ * Convert a numeric score to a letter grade.
+ * Thresholds: A+=95, A=90, B=80, C=70, D=60, F=<60
+ */
+export declare function scoreToGrade(score: number): PlanGrade;
+/**
+ * Convert a letter grade to the minimum score required.
+ */
+export declare function gradeToMinScore(grade: PlanGrade): number;
+/**
+ * Error thrown when a plan's grade is below the minimum required for approval.
+ */
+export declare class PlanGradeRejectionError extends Error {
+    readonly grade: PlanGrade;
+    readonly score: number;
+    readonly minGrade: PlanGrade;
+    readonly gaps: PlanGap[];
+    constructor(grade: PlanGrade, score: number, minGrade: PlanGrade, gaps: PlanGap[]);
+}
+/**
+ * Calculate score from gaps with severity-weighted deductions and iteration leniency.
+ */
+export declare function calculateScore(gaps: PlanGap[], iteration?: number): number;
+/**
+ * Detect circular dependencies among tasks.
+ * Uses DFS with in-stack tracking.
+ */
+export declare function hasCircularDependencies(tasks: ReadonlyArray<{
+    id: string;
+    dependsOn?: string[];
+}>): boolean;
+import type { PlanTask, TaskStatus, Plan, PlanDecision } from './planner-types.js';
+export interface IterateChanges {
+    objective?: string;
+    scope?: string;
+    decisions?: (string | PlanDecision)[];
+    addTasks?: Array<{
+        title: string;
+        description: string;
+    }>;
+    removeTasks?: string[];
+    approach?: string;
+    context?: string;
+    success_criteria?: string[];
+    tool_chain?: string[];
+    flow?: string;
+    target_mode?: string;
+}
+/**
+ * Apply iteration changes to a plan (mutates in place).
+ * Caller is responsible for status validation and persistence.
+ */
+export declare function applyIteration(plan: Plan, changes: IterateChanges): void;
+/**
+ * Replace plan tasks with a new split set, validating dependency references.
+ * Caller is responsible for status validation and persistence.
+ */
+/**
+ * Apply a task status update with auto-metrics (startedAt, completedAt, durationMs).
+ * Caller is responsible for plan status validation and persistence.
+ */
+export declare function applyTaskStatusUpdate(task: PlanTask, status: TaskStatus): void;
+/**
+ * Create a new Plan object (factory). Does not persist.
+ */
+export declare function createPlanObject(params: {
+    objective: string;
+    scope: string;
+    decisions?: (string | PlanDecision)[];
+    tasks?: Array<{
+        title: string;
+        description: string;
+    }>;
+    approach?: string;
+    context?: string;
+    success_criteria?: string[];
+    tool_chain?: string[];
+    flow?: string;
+    target_mode?: string;
+    alternatives?: import('./planner-types.js').PlanAlternative[];
+    initialStatus?: 'brainstorming' | 'draft';
+}): Plan;
+export declare function applySplitTasks(plan: Plan, tasks: Array<{
+    title: string;
+    description: string;
+    dependsOn?: string[];
+    acceptanceCriteria?: string[];
+}>): void;
+//# sourceMappingURL=plan-lifecycle.d.ts.map

package/dist/planning/plan-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-lifecycle.d.ts","sourceRoot":"","sources":["../../src/planning/plan-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/planning/plan-lifecycle.js

@@ -0,0 +1,296 @@
+/**
+ * Plan lifecycle FSM — state transitions, grade thresholds, and structural validation.
+ * Extracted from planner.ts to isolate pure lifecycle logic from persistence.
+ */
+import { SEVERITY_WEIGHTS, CATEGORY_PENALTY_CAPS, CATEGORY_BONUS_CAPS } from './gap-types.js';
+/**
+ * Valid status transitions.
+ * Each key maps to the set of statuses it can transition to.
+ * Ported from Salvador's LIFECYCLE_TRANSITIONS.
+ */
+export const LIFECYCLE_TRANSITIONS = {
+    brainstorming: ['draft'],
+    draft: ['approved'],
+    approved: ['executing'],
+    executing: ['validating', 'reconciling'],
+    validating: ['reconciling', 'executing'],
+    reconciling: ['completed'],
+    completed: ['archived'],
+    archived: [],
+};
+/**
+ * Statuses where the 30-minute TTL should NOT apply.
+ * Plans in these states may span multiple sessions.
+ */
+export const NON_EXPIRING_STATUSES = [
+    'brainstorming',
+    'executing',
+    'validating',
+    'reconciling',
+];
+/**
+ * Validate a lifecycle status transition.
+ * Returns true if the transition is valid, false otherwise.
+ */
+export function isValidTransition(from, to) {
+    return LIFECYCLE_TRANSITIONS[from].includes(to);
+}
+/**
+ * Get the valid next statuses for a given status.
+ */
+export function getValidNextStatuses(status) {
+    return LIFECYCLE_TRANSITIONS[status];
+}
+/**
+ * Check if a status should have TTL expiration.
+ * Plans in executing/reconciling states persist indefinitely.
+ */
+export function shouldExpire(status) {
+    return !NON_EXPIRING_STATUSES.includes(status);
+}
+/**
+ * Apply an FSM transition to a plan status.
+ * Throws if the transition is invalid. Returns the new status and timestamp.
+ * Does NOT mutate the plan — caller applies the result.
+ */
+export function applyTransition(currentStatus, targetStatus) {
+    if (!isValidTransition(currentStatus, targetStatus)) {
+        const valid = getValidNextStatuses(currentStatus);
+        throw new Error(`Invalid transition: '${currentStatus}' → '${targetStatus}'. ` +
+            `Valid transitions from '${currentStatus}': ${valid.length > 0 ? valid.join(', ') : 'none'}`);
+    }
+    return { status: targetStatus, updatedAt: Date.now() };
+}
+/**
+ * Convert a numeric score to a letter grade.
+ * Thresholds: A+=95, A=90, B=80, C=70, D=60, F=<60
+ */
+export function scoreToGrade(score) {
+    if (score >= 95)
+        return 'A+';
+    if (score >= 90)
+        return 'A';
+    if (score >= 80)
+        return 'B';
+    if (score >= 70)
+        return 'C';
+    if (score >= 60)
+        return 'D';
+    return 'F';
+}
+/**
+ * Convert a letter grade to the minimum score required.
+ */
+export function gradeToMinScore(grade) {
+    switch (grade) {
+        case 'A+':
+            return 95;
+        case 'A':
+            return 90;
+        case 'B':
+            return 80;
+        case 'C':
+            return 70;
+        case 'D':
+            return 60;
+        case 'F':
+            return 0;
+    }
+}
+/**
+ * Error thrown when a plan's grade is below the minimum required for approval.
+ */
+export class PlanGradeRejectionError extends Error {
+    grade;
+    score;
+    minGrade;
+    gaps;
+    constructor(grade, score, minGrade, gaps) {
+        const gapSummary = gaps
+            .filter((g) => g.severity === 'critical' || g.severity === 'major')
+            .map((g) => `- [${g.severity}] ${g.description}`)
+            .join('\n');
+        super(`Plan grade ${grade} (${score}/100) is below the minimum required grade ${minGrade} for approval. ` +
+            `Iterate on the plan to address gaps before approving.\n${gapSummary}`);
+        this.name = 'PlanGradeRejectionError';
+        this.grade = grade;
+        this.score = score;
+        this.minGrade = minGrade;
+        this.gaps = gaps;
+    }
+}
+// ─── Score Calculation ───────────────────────────────────────────
+/**
+ * Calculate score from gaps with severity-weighted deductions and iteration leniency.
+ */
+export function calculateScore(gaps, iteration = 1) {
+    const categoryDeductions = new Map();
+    const categoryBonuses = new Map();
+    for (const gap of gaps) {
+        let weight = SEVERITY_WEIGHTS[gap.severity];
+        if (gap.severity === 'minor') {
+            if (iteration === 1)
+                weight = 0;
+            else if (iteration === 2)
+                weight = 1;
+        }
+        const category = gap.category;
+        if (weight < 0) {
+            categoryBonuses.set(category, (categoryBonuses.get(category) ?? 0) + Math.abs(weight));
+        }
+        else {
+            categoryDeductions.set(category, (categoryDeductions.get(category) ?? 0) + weight);
+        }
+    }
+    let deductions = 0;
+    for (const [category, total] of categoryDeductions) {
+        const cap = CATEGORY_PENALTY_CAPS[category];
+        deductions += cap !== undefined ? Math.min(total, cap) : total;
+    }
+    let bonuses = 0;
+    for (const [category, total] of categoryBonuses) {
+        const cap = CATEGORY_BONUS_CAPS[category];
+        bonuses += cap !== undefined ? Math.min(total, cap) : total;
+    }
+    return Math.max(0, Math.min(100, 100 - deductions + bonuses));
+}
+// ─── Structural Validation ───────────────────────────────────────
+/**
+ * Detect circular dependencies among tasks.
+ * Uses DFS with in-stack tracking.
+ */
+export function hasCircularDependencies(tasks) {
+    const visited = new Set();
+    const inStack = new Set();
+    const taskMap = new Map(tasks.map((t) => [t.id, t]));
+    const dfs = (taskId) => {
+        if (inStack.has(taskId))
+            return true;
+        if (visited.has(taskId))
+            return false;
+        visited.add(taskId);
+        inStack.add(taskId);
+        const task = taskMap.get(taskId);
+        if (task?.dependsOn) {
+            for (const dep of task.dependsOn) {
+                if (dfs(dep))
+                    return true;
+            }
+        }
+        inStack.delete(taskId);
+        return false;
+    };
+    for (const task of tasks) {
+        if (dfs(task.id))
+            return true;
+    }
+    return false;
+}
+/**
+ * Apply iteration changes to a plan (mutates in place).
+ * Caller is responsible for status validation and persistence.
+ */
+export function applyIteration(plan, changes) {
+    const now = Date.now();
+    if (changes.objective !== undefined)
+        plan.objective = changes.objective;
+    if (changes.scope !== undefined)
+        plan.scope = changes.scope;
+    if (changes.decisions !== undefined)
+        plan.decisions = changes.decisions;
+    if (changes.approach !== undefined)
+        plan.approach = changes.approach;
+    if (changes.context !== undefined)
+        plan.context = changes.context;
+    if (changes.success_criteria !== undefined)
+        plan.success_criteria = changes.success_criteria;
+    if (changes.tool_chain !== undefined)
+        plan.tool_chain = changes.tool_chain;
+    if (changes.flow !== undefined)
+        plan.flow = changes.flow;
+    if (changes.target_mode !== undefined)
+        plan.target_mode = changes.target_mode;
+    if (changes.removeTasks?.length) {
+        const removeSet = new Set(changes.removeTasks);
+        plan.tasks = plan.tasks.filter((t) => !removeSet.has(t.id));
+    }
+    if (changes.addTasks?.length) {
+        const maxIndex = plan.tasks.reduce((max, t) => {
+            const num = parseInt(t.id.replace('task-', ''), 10);
+            return isNaN(num) ? max : Math.max(max, num);
+        }, 0);
+        for (let i = 0; i < changes.addTasks.length; i++) {
+            plan.tasks.push({
+                id: `task-${maxIndex + i + 1}`, title: changes.addTasks[i].title,
+                description: changes.addTasks[i].description, status: 'pending', updatedAt: now,
+            });
+        }
+    }
+    plan.updatedAt = now;
+}
+/**
+ * Replace plan tasks with a new split set, validating dependency references.
+ * Caller is responsible for status validation and persistence.
+ */
+/**
+ * Apply a task status update with auto-metrics (startedAt, completedAt, durationMs).
+ * Caller is responsible for plan status validation and persistence.
+ */
+export function applyTaskStatusUpdate(task, status) {
+    const now = Date.now();
+    if (status === 'in_progress' && !task.startedAt)
+        task.startedAt = now;
+    if (status === 'completed' || status === 'skipped' || status === 'failed') {
+        task.completedAt = now;
+        if (task.startedAt) {
+            if (!task.metrics)
+                task.metrics = {};
+            task.metrics.durationMs = now - task.startedAt;
+        }
+    }
+    task.status = status;
+    task.updatedAt = now;
+}
+/**
+ * Create a new Plan object (factory). Does not persist.
+ */
+export function createPlanObject(params) {
+    const now = Date.now();
+    return {
+        id: `plan-${now}-${Math.random().toString(36).slice(2, 8)}`,
+        objective: params.objective, scope: params.scope,
+        status: params.initialStatus ?? 'draft',
+        decisions: params.decisions ?? [],
+        tasks: (params.tasks ?? []).map((t, i) => ({
+            id: `task-${i + 1}`, title: t.title, description: t.description,
+            status: 'pending', updatedAt: now,
+        })),
+        ...(params.approach !== undefined && { approach: params.approach }),
+        ...(params.context !== undefined && { context: params.context }),
+        ...(params.success_criteria !== undefined && { success_criteria: params.success_criteria }),
+        ...(params.tool_chain !== undefined && { tool_chain: params.tool_chain }),
+        ...(params.flow !== undefined && { flow: params.flow }),
+        ...(params.target_mode !== undefined && { target_mode: params.target_mode }),
+        ...(params.alternatives !== undefined && { alternatives: params.alternatives }),
+        checks: [], createdAt: now, updatedAt: now,
+    };
+}
+export function applySplitTasks(plan, tasks) {
+    const now = Date.now();
+    plan.tasks = tasks.map((t, i) => ({
+        id: `task-${i + 1}`, title: t.title, description: t.description,
+        status: 'pending', dependsOn: t.dependsOn,
+        ...(t.acceptanceCriteria && { acceptanceCriteria: t.acceptanceCriteria }), updatedAt: now,
+    }));
+    const taskIds = new Set(plan.tasks.map((t) => t.id));
+    for (const task of plan.tasks) {
+        if (task.dependsOn) {
+            for (const dep of task.dependsOn) {
+                if (!taskIds.has(dep))
+                    throw new Error(`Task '${task.id}' depends on unknown task '${dep}'`);
+            }
+        }
+    }
+    plan.updatedAt = now;
+}
+//# sourceMappingURL=plan-lifecycle.js.map