oxe-cc 0.9.3 → 1.2.1

package/lib/runtime/context/context-pack-builder.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextPackBuilder = void 0;
+exports.scorePackQuality = scorePackQuality;
+function scorePackQuality(pack, profile) {
+    const expectedKinds = Object.keys(profile.artifact_kind_weights);
+    const presentKinds = new Set(pack.artifacts.map((a) => a.kind));
+    const completeness = expectedKinds.length > 0
+        ? expectedKinds.filter((k) => presentKinds.has(k)).length / expectedKinds.length
+        : 0;
+    const relevance_mean = pack.artifacts.length > 0
+        ? pack.artifacts.reduce((sum, a) => sum + a.relevanceScore, 0) / pack.artifacts.length
+        : 0;
+    const total = pack.total_artifacts_considered;
+    const redundancy = total > 0 ? 1 - (pack.artifacts.length / total) : 0;
+    const ageMs = Date.now() - new Date(pack.built_at).getTime();
+    const maxAgeMs = 24 * 60 * 60 * 1000;
+    const recency_score = Math.max(0, 1 - ageMs / maxAgeMs);
+    const overall = Math.min(1, 0.3 * completeness +
+        0.35 * relevance_mean +
+        0.1 * (1 - redundancy) +
+        0.25 * recency_score);
+    return {
+        completeness: Math.round(completeness * 100) / 100,
+        relevance_mean: Math.round(relevance_mean * 100) / 100,
+        redundancy: Math.round(redundancy * 100) / 100,
+        recency_score: Math.round(recency_score * 100) / 100,
+        overall: Math.round(overall * 100) / 100,
+    };
+}
+// ─── Relevance scoring ────────────────────────────────────────────────────────
+function scoreEvidenceRelevance(evidence, workItem) {
+    let score = 0.5;
+    const eid = evidence.evidence_id.toLowerCase();
+    const title = workItem.title.toLowerCase();
+    const scope = workItem.mutation_scope ?? [];
+    if (scope.some((s) => eid.includes(s.toLowerCase())))
+        score += 0.3;
+    if (title.split(/\s+/).some((w) => w.length > 3 && eid.includes(w)))
+        score += 0.1;
+    if (evidence.type === 'junit_xml')
+        score += 0.05;
+    if (evidence.type === 'diff')
+        score += 0.05;
+    return Math.min(score, 1.0);
+}
+function scoreLessonRelevance(lesson, workItem) {
+    const itemTags = new Set([
+        ...workItem.mutation_scope.map((s) => s.toLowerCase()),
+        ...workItem.title.toLowerCase().split(/\s+/).filter((w) => w.length > 3),
+    ]);
+    const lessonTags = lesson.tags.map((t) => t.toLowerCase());
+    const overlap = lessonTags.filter((t) => itemTags.has(t)).length;
+    const jaccard = overlap / (itemTags.size + lessonTags.length - overlap || 1);
+    return Math.min(0.3 + jaccard * 0.7, 1.0);
+}
+// ─── Redundancy elimination ───────────────────────────────────────────────────
+function cosineSimilarity(a, b) {
+    const wordsA = new Set(a.content.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
+    const wordsB = new Set(b.content.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
+    if (wordsA.size === 0 || wordsB.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const w of wordsA)
+        if (wordsB.has(w))
+            intersection++;
+    return intersection / Math.sqrt(wordsA.size * wordsB.size);
+}
+function deduplicateArtifacts(artifacts, threshold) {
+    const kept = [];
+    let removed = 0;
+    for (const candidate of artifacts) {
+        const isDuplicate = kept.some((existing) => cosineSimilarity(candidate, existing) >= threshold);
+        if (isDuplicate) {
+            removed++;
+        }
+        else {
+            kept.push(candidate);
+        }
+    }
+    return { kept, removed };
+}
+// ─── Token budget estimation ──────────────────────────────────────────────────
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function applyTokenBudget(artifacts, maxTokens) {
+    let used = 0;
+    const result = [];
+    for (const a of artifacts) {
+        const t = estimateTokens(a.content);
+        if (used + t > maxTokens)
+            break;
+        result.push(a);
+        used += t;
+    }
+    return result;
+}
+// ─── Context Pack Builder ─────────────────────────────────────────────────────
+class ContextPackBuilder {
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    build(workItem, state, evidenceItems, evidenceContents, lessons) {
+        const { maxArtifacts = 20, maxTokensEstimate = 8000, deduplicateThreshold = 0.85, } = this.opts;
+        const raw = [];
+        // Score and collect evidence
+        for (const ev of evidenceItems) {
+            const content = evidenceContents.get(ev.evidence_id) ?? '';
+            if (!content)
+                continue;
+            raw.push({
+                id: ev.evidence_id,
+                kind: 'evidence',
+                content,
+                relevanceScore: scoreEvidenceRelevance(ev, workItem),
+                tags: [ev.type, workItem.work_item_id],
+            });
+        }
+        // Score and collect lessons
+        for (const lesson of lessons) {
+            raw.push({
+                id: lesson.lesson_id,
+                kind: 'lesson',
+                content: lesson.content,
+                relevanceScore: scoreLessonRelevance(lesson, workItem),
+                tags: lesson.tags,
+            });
+        }
+        // Add run-level summary if available
+        const completedCount = state.completedWorkItems.size;
+        if (completedCount > 0) {
+            raw.push({
+                id: `run-summary-${workItem.run_id}`,
+                kind: 'summary',
+                content: `Run progress: ${completedCount} completed, ${state.failedWorkItems.size} failed, ${state.blockedWorkItems.size} blocked.`,
+                relevanceScore: 0.4,
+                tags: ['run-context'],
+            });
+        }
+        const totalConsidered = raw.length;
+        // Sort by relevance descending
+        raw.sort((a, b) => b.relevanceScore - a.relevanceScore);
+        // Deduplicate
+        const { kept, removed } = deduplicateArtifacts(raw, deduplicateThreshold);
+        // Apply max artifacts cap
+        const capped = kept.slice(0, maxArtifacts);
+        // Apply token budget
+        const final = applyTokenBudget(capped, maxTokensEstimate);
+        return {
+            work_item_id: workItem.work_item_id,
+            artifacts: final,
+            total_artifacts_considered: totalConsidered,
+            redundancy_removed: removed,
+            built_at: new Date().toISOString(),
+        };
+    }
+    /** Convenience: build with no evidence, just lessons and state summary */
+    buildLightweight(workItem, state, lessons) {
+        return this.build(workItem, state, [], new Map(), lessons);
+    }
+    /**
+     * Filter artifacts to those whose path-like tags are within mutation_scope.
+     * L0/L1 tiers apply the filter; L2/L3 skip it (full access).
+     */
+    filterByMutationScope(artifacts, mutationScope, autonomyTier) {
+        if (autonomyTier === 'L2' || autonomyTier === 'L3')
+            return artifacts;
+        const scope = mutationScope.map((s) => s.toLowerCase());
+        return artifacts.filter((a) => {
+            const pathTags = a.tags.filter((t) => t.includes('/') || t.includes('\\'));
+            if (pathTags.length === 0)
+                return true;
+            return pathTags.some((tag) => scope.some((s) => tag.toLowerCase().includes(s) || s.includes(tag.toLowerCase())));
+        });
+    }
+}
+exports.ContextPackBuilder = ContextPackBuilder;

package/lib/runtime/context/context-pack-store.d.ts

@@ -0,0 +1,38 @@
+import type { ContextPack, ContextQualityScore } from './context-pack-builder';
+export interface ContextPackMeta {
+    pack_id: string;
+    work_item_id: string;
+    run_id: string;
+    built_at: string;
+    artifact_count: number;
+    estimated_tokens: number;
+    stale: boolean;
+    stale_reason: string | null;
+}
+export interface ContextPackDiff {
+    added: string[];
+    removed: string[];
+    score_changed: Array<{
+        id: string;
+        before: number;
+        after: number;
+    }>;
+}
+export declare function savePack(projectRoot: string, runId: string, pack: ContextPack): ContextPackMeta;
+export declare function loadPack(projectRoot: string, runId: string, workItemId: string): ContextPack | null;
+export declare function markStale(projectRoot: string, runId: string, workItemId: string, reason: string): void;
+export declare function isStale(projectRoot: string, runId: string, workItemId: string): boolean;
+export declare function diffPacks(before: ContextPack, after: ContextPack): ContextPackDiff;
+export declare function listPackMeta(projectRoot: string, runId: string): ContextPackMeta[];
+export interface ContextPackRef {
+    ref_id: string;
+    pack_id: string;
+    attempt_id: string;
+    work_item_id: string;
+    run_id: string;
+    artifacts_used: string[];
+    quality: ContextQualityScore;
+    linked_at: string;
+}
+export declare function linkPackToAttempt(projectRoot: string, runId: string, attemptId: string, pack: ContextPack, quality: ContextQualityScore): ContextPackRef;
+export declare function getPackRefForAttempt(projectRoot: string, runId: string, attemptId: string): ContextPackRef | null;

package/lib/runtime/context/context-pack-store.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.savePack = savePack;
+exports.loadPack = loadPack;
+exports.markStale = markStale;
+exports.isStale = isStale;
+exports.diffPacks = diffPacks;
+exports.listPackMeta = listPackMeta;
+exports.linkPackToAttempt = linkPackToAttempt;
+exports.getPackRefForAttempt = getPackRefForAttempt;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+function packPath(projectRoot, runId, workItemId) {
+    return path_1.default.join(projectRoot, '.oxe', 'runs', runId, `context-pack-${workItemId}.json`);
+}
+function metaIndexPath(projectRoot, runId) {
+    return path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'context-packs.index.json');
+}
+function estimateTokens(pack) {
+    return Math.ceil(pack.artifacts.reduce((sum, a) => sum + a.content.length, 0) / 4);
+}
+function savePack(projectRoot, runId, pack) {
+    const p = packPath(projectRoot, runId, pack.work_item_id);
+    fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+    fs_1.default.writeFileSync(p, JSON.stringify(pack, null, 2), 'utf8');
+    const meta = {
+        pack_id: `cp-${runId}-${pack.work_item_id}`,
+        work_item_id: pack.work_item_id,
+        run_id: runId,
+        built_at: pack.built_at,
+        artifact_count: pack.artifacts.length,
+        estimated_tokens: estimateTokens(pack),
+        stale: false,
+        stale_reason: null,
+    };
+    updateMetaIndex(projectRoot, runId, meta);
+    return meta;
+}
+function loadPack(projectRoot, runId, workItemId) {
+    const p = packPath(projectRoot, runId, workItemId);
+    if (!fs_1.default.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function markStale(projectRoot, runId, workItemId, reason) {
+    const index = loadMetaIndex(projectRoot, runId);
+    const meta = index.find((m) => m.work_item_id === workItemId);
+    if (!meta)
+        return;
+    meta.stale = true;
+    meta.stale_reason = reason;
+    saveMetaIndex(projectRoot, runId, index);
+}
+function isStale(projectRoot, runId, workItemId) {
+    const index = loadMetaIndex(projectRoot, runId);
+    return index.find((m) => m.work_item_id === workItemId)?.stale ?? false;
+}
+function diffPacks(before, after) {
+    const beforeIds = new Set(before.artifacts.map((a) => a.id));
+    const afterIds = new Set(after.artifacts.map((a) => a.id));
+    const beforeMap = new Map(before.artifacts.map((a) => [a.id, a]));
+    const afterMap = new Map(after.artifacts.map((a) => [a.id, a]));
+    const added = [...afterIds].filter((id) => !beforeIds.has(id));
+    const removed = [...beforeIds].filter((id) => !afterIds.has(id));
+    const score_changed = [];
+    for (const id of afterIds) {
+        if (!beforeIds.has(id))
+            continue;
+        const bScore = beforeMap.get(id).relevanceScore;
+        const aScore = afterMap.get(id).relevanceScore;
+        if (Math.abs(bScore - aScore) > 0.05) {
+            score_changed.push({ id, before: bScore, after: aScore });
+        }
+    }
+    return { added, removed, score_changed };
+}
+function listPackMeta(projectRoot, runId) {
+    return loadMetaIndex(projectRoot, runId);
+}
+function packRefPath(projectRoot, runId, attemptId) {
+    return path_1.default.join(projectRoot, '.oxe', 'runs', runId, `context-ref-${attemptId}.json`);
+}
+function linkPackToAttempt(projectRoot, runId, attemptId, pack, quality) {
+    const ref = {
+        ref_id: `ref-${runId}-${attemptId}`,
+        pack_id: `cp-${runId}-${pack.work_item_id}`,
+        attempt_id: attemptId,
+        work_item_id: pack.work_item_id,
+        run_id: runId,
+        artifacts_used: pack.artifacts.map((a) => a.id),
+        quality,
+        linked_at: new Date().toISOString(),
+    };
+    const p = packRefPath(projectRoot, runId, attemptId);
+    fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+    fs_1.default.writeFileSync(p, JSON.stringify(ref, null, 2), 'utf8');
+    return ref;
+}
+function getPackRefForAttempt(projectRoot, runId, attemptId) {
+    const p = packRefPath(projectRoot, runId, attemptId);
+    if (!fs_1.default.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function loadMetaIndex(projectRoot, runId) {
+    const p = metaIndexPath(projectRoot, runId);
+    if (!fs_1.default.existsSync(p))
+        return [];
+    try {
+        return JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+function saveMetaIndex(projectRoot, runId, index) {
+    const p = metaIndexPath(projectRoot, runId);
+    fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+    fs_1.default.writeFileSync(p, JSON.stringify(index, null, 2), 'utf8');
+}
+function updateMetaIndex(projectRoot, runId, meta) {
+    const index = loadMetaIndex(projectRoot, runId);
+    const idx = index.findIndex((m) => m.work_item_id === meta.work_item_id);
+    if (idx >= 0)
+        index[idx] = meta;
+    else
+        index.push(meta);
+    saveMetaIndex(projectRoot, runId, index);
+}

package/lib/runtime/context/context-profiles.d.ts

@@ -0,0 +1,11 @@
+import type { ContextArtifact } from './context-pack-builder';
+export type ContextDecisionType = 'execute' | 'verify' | 'plan' | 'review' | 'debug' | 'migration';
+export interface ContextProfile {
+    decision_type: ContextDecisionType;
+    artifact_kind_weights: Record<ContextArtifact['kind'], number>;
+    quality_threshold: number;
+    max_artifacts: number;
+    max_tokens: number;
+}
+export declare const DEFAULT_PROFILES: Record<ContextDecisionType, ContextProfile>;
+export declare function getProfile(decisionType: ContextDecisionType): ContextProfile;

package/lib/runtime/context/context-profiles.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROFILES = void 0;
+exports.getProfile = getProfile;
+exports.DEFAULT_PROFILES = {
+    execute: {
+        decision_type: 'execute',
+        artifact_kind_weights: { evidence: 0.8, lesson: 0.3, file: 0.6, summary: 0.4 },
+        quality_threshold: 0.6,
+        max_artifacts: 20,
+        max_tokens: 8000,
+    },
+    verify: {
+        decision_type: 'verify',
+        artifact_kind_weights: { evidence: 0.9, lesson: 0.2, file: 0.5, summary: 0.5 },
+        quality_threshold: 0.7,
+        max_artifacts: 15,
+        max_tokens: 6000,
+    },
+    plan: {
+        decision_type: 'plan',
+        artifact_kind_weights: { evidence: 0.4, lesson: 0.9, file: 0.7, summary: 0.6 },
+        quality_threshold: 0.5,
+        max_artifacts: 25,
+        max_tokens: 10000,
+    },
+    review: {
+        decision_type: 'review',
+        artifact_kind_weights: { evidence: 0.6, lesson: 0.5, file: 0.8, summary: 0.5 },
+        quality_threshold: 0.55,
+        max_artifacts: 20,
+        max_tokens: 8000,
+    },
+    debug: {
+        decision_type: 'debug',
+        artifact_kind_weights: { evidence: 0.9, lesson: 0.6, file: 0.7, summary: 0.4 },
+        quality_threshold: 0.6,
+        max_artifacts: 20,
+        max_tokens: 8000,
+    },
+    migration: {
+        decision_type: 'migration',
+        artifact_kind_weights: { evidence: 0.7, lesson: 0.7, file: 0.9, summary: 0.5 },
+        quality_threshold: 0.65,
+        max_artifacts: 30,
+        max_tokens: 12000,
+    },
+};
+function getProfile(decisionType) {
+    return exports.DEFAULT_PROFILES[decisionType];
+}

package/lib/runtime/context/index.d.ts

@@ -0,0 +1,3 @@
+export * from './context-pack-builder';
+export * from './context-pack-store';
+export * from './context-profiles';

package/lib/runtime/context/index.js

@@ -0,0 +1,19 @@
+"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("./context-pack-builder"), exports);
+__exportStar(require("./context-pack-store"), exports);
+__exportStar(require("./context-profiles"), exports);

package/lib/runtime/decision/decision-engine.d.ts

@@ -0,0 +1,43 @@
+import type { DecisionMemo } from './decision-memo';
+export type DecisionType = 'proceed' | 'retry' | 'escalate_gate' | 'skip' | 'abort' | 'promote_lesson';
+export type DecisionSignal = 'policy_allowed' | 'policy_denied' | 'gate_pending' | 'gate_approved' | 'evidence_sufficient' | 'evidence_missing' | 'retry_budget_available' | 'retry_budget_exhausted' | 'lesson_match' | 'risk_high';
+export type SeniorityLevel = 'junior' | 'standard' | 'senior' | 'expert';
+export interface DecisionRecord {
+    decision_id: string;
+    work_item_id: string | null;
+    run_id: string;
+    type: DecisionType;
+    seniority: SeniorityLevel;
+    confidence: number;
+    signals: DecisionSignal[];
+    rationale: string;
+    timestamp: string;
+    memo?: DecisionMemo;
+}
+export interface DecisionLog {
+    run_id: string;
+    decisions: DecisionRecord[];
+}
+export interface DecisionInput {
+    work_item_id?: string;
+    run_id: string;
+    policy_allowed: boolean;
+    gate_pending: boolean;
+    gate_approved: boolean;
+    retry_count: number;
+    max_retries: number;
+    evidence_count: number;
+    risk_level: 'none' | 'low' | 'medium' | 'high' | 'critical';
+    lesson_match: boolean;
+    memo?: DecisionMemo;
+}
+export declare class DecisionEngine {
+    evaluate(input: DecisionInput): DecisionRecord;
+}
+export declare function appendDecision(projectRoot: string, runId: string, record: DecisionRecord): void;
+export declare function loadDecisionLog(projectRoot: string, runId: string): DecisionLog | null;
+export declare function queryDecisions(log: DecisionLog, filter: {
+    type?: DecisionType;
+    workItemId?: string;
+    minConfidence?: number;
+}): DecisionRecord[];

package/lib/runtime/decision/decision-engine.js

@@ -0,0 +1,127 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecisionEngine = void 0;
+exports.appendDecision = appendDecision;
+exports.loadDecisionLog = loadDecisionLog;
+exports.queryDecisions = queryDecisions;
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+function computeSeniority(confidence) {
+    if (confidence >= 0.9)
+        return 'expert';
+    if (confidence >= 0.75)
+        return 'senior';
+    if (confidence >= 0.5)
+        return 'standard';
+    return 'junior';
+}
+class DecisionEngine {
+    evaluate(input) {
+        const signals = [];
+        let type = 'proceed';
+        let confidence = 0.8;
+        let rationale = '';
+        if (!input.policy_allowed) {
+            signals.push('policy_denied');
+            type = 'abort';
+            confidence = 1.0;
+            rationale = 'Policy denied execution — aborting without retry.';
+        }
+        else {
+            signals.push('policy_allowed');
+            if (input.gate_pending && !input.gate_approved) {
+                signals.push('gate_pending');
+                type = 'escalate_gate';
+                confidence = 0.95;
+                rationale = 'Human gate pending — escalating for approval before proceeding.';
+            }
+            else {
+                if (input.gate_approved)
+                    signals.push('gate_approved');
+                if (input.risk_level === 'high' || input.risk_level === 'critical') {
+                    signals.push('risk_high');
+                    confidence = Math.max(0.4, confidence - 0.3);
+                    rationale += 'High residual risk detected. ';
+                }
+                if (input.retry_count >= input.max_retries) {
+                    signals.push('retry_budget_exhausted');
+                    type = 'abort';
+                    confidence = 0.9;
+                    rationale += `Retry budget exhausted (${input.retry_count}/${input.max_retries}).`;
+                }
+                else if (input.retry_count > 0) {
+                    signals.push('retry_budget_available');
+                    type = 'retry';
+                    confidence = 0.7;
+                    rationale += `Retrying (attempt ${input.retry_count + 1}/${input.max_retries + 1}).`;
+                }
+                else {
+                    if (input.evidence_count > 0) {
+                        signals.push('evidence_sufficient');
+                        confidence = Math.min(1.0, confidence + 0.1);
+                    }
+                    else {
+                        signals.push('evidence_missing');
+                        confidence = Math.max(0.3, confidence - 0.2);
+                    }
+                    if (input.lesson_match) {
+                        signals.push('lesson_match');
+                        type = 'promote_lesson';
+                        confidence = Math.min(1.0, confidence + 0.05);
+                    }
+                    if (!rationale)
+                        rationale = 'All signals green — proceeding with execution.';
+                }
+            }
+        }
+        return {
+            decision_id: `dec-${crypto_1.default.randomBytes(4).toString('hex')}`,
+            work_item_id: input.work_item_id ?? null,
+            run_id: input.run_id,
+            type,
+            seniority: computeSeniority(confidence),
+            confidence: Math.round(confidence * 100) / 100,
+            signals,
+            rationale: rationale.trim(),
+            timestamp: new Date().toISOString(),
+            ...(input.memo !== undefined ? { memo: input.memo } : {}),
+        };
+    }
+}
+exports.DecisionEngine = DecisionEngine;
+function appendDecision(projectRoot, runId, record) {
+    const p = logPath(projectRoot, runId);
+    fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+    const log = loadDecisionLog(projectRoot, runId) ?? { run_id: runId, decisions: [] };
+    log.decisions.push(record);
+    fs_1.default.writeFileSync(p, JSON.stringify(log, null, 2), 'utf8');
+}
+function loadDecisionLog(projectRoot, runId) {
+    const p = logPath(projectRoot, runId);
+    if (!fs_1.default.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function queryDecisions(log, filter) {
+    return log.decisions.filter((d) => {
+        if (filter.type && d.type !== filter.type)
+            return false;
+        if (filter.workItemId && d.work_item_id !== filter.workItemId)
+            return false;
+        if (filter.minConfidence !== undefined && d.confidence < filter.minConfidence)
+            return false;
+        return true;
+    });
+}
+function logPath(projectRoot, runId) {
+    return path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'decisions.json');
+}

package/lib/runtime/decision/decision-memo.d.ts

@@ -0,0 +1,53 @@
+export type ChangeStrategy = 'minimal_patch' | 'isolated_refactor' | 'expand_contract' | 'feature_flag' | 'no_op';
+export interface BlastRadiusEstimate {
+    estimated_files: number;
+    subsystems: string[];
+    risk_score: number;
+    reversible: boolean;
+}
+export interface RollbackPlan {
+    strategy: 'revert_commit' | 'restore_workspace' | 'undo_patch' | 'no_rollback';
+    steps: string[];
+    estimated_cost: 'low' | 'medium' | 'high';
+    preconditions: string[];
+}
+export interface DecisionMemo {
+    memo_id: string;
+    work_item_id: string;
+    run_id: string;
+    problem_summary: string;
+    chosen_strategy: ChangeStrategy;
+    alternatives_rejected: Array<{
+        strategy: ChangeStrategy;
+        reason: string;
+    }>;
+    blast_radius: BlastRadiusEstimate;
+    rollback_plan: RollbackPlan;
+    min_evidence_required: string[];
+    confidence: number;
+    created_at: string;
+}
+export declare function buildBlastRadius(mutationScope: string[], retryCount: number, riskLevel: string): BlastRadiusEstimate;
+export declare function buildRollbackPlan(blastRadius: BlastRadiusEstimate, retryCount: number): RollbackPlan;
+export declare class StrategySelector {
+    select(mutationScope: string[], retryCount: number, riskLevel: string): ChangeStrategy;
+    alternatives(chosen: ChangeStrategy, mutationScope: string[], riskLevel: string): Array<{
+        strategy: ChangeStrategy;
+        reason: string;
+    }>;
+    private rejectionReason;
+}
+export interface BuildMemoInput {
+    work_item_id: string;
+    run_id: string;
+    problem_summary: string;
+    mutation_scope: string[];
+    retry_count: number;
+    risk_level: string;
+    min_evidence_required?: string[];
+    confidence?: number;
+}
+export declare function buildMemo(input: BuildMemoInput): DecisionMemo;
+export declare function saveMemo(projectRoot: string, memo: DecisionMemo): void;
+export declare function loadMemo(projectRoot: string, runId: string, memoId: string): DecisionMemo | null;
+export declare function listMemos(projectRoot: string, runId: string): DecisionMemo[];