open-multi-agent-kit 0.78.1 → 0.78.3

package/dist/commands/goal-interview.js

@@ -0,0 +1,396 @@
+import { mkdir, writeFile, readFile, readdir } from "fs/promises";
+import { basename, join } from "path";
+import { getProjectRoot } from "../util/fs.js";
+import { style, header, status, label } from "../util/theme.js";
+import { NotFoundError, UsageError, emitError } from "../util/cli-contract.js";
+import { createGoalPersister } from "../goal/persistence.js";
+import { createGoalSpec, updateGoalStatus } from "../goal/intake.js";
+import { buildInterviewSession, ingestAnswers } from "../goal/interview-session.js";
+import { applyInterviewDelta } from "../goal/interview-assimilation.js";
+import { redactSecretText } from "../goal/intent-frame.js";
+import { readImageFile } from "../util/clipboard-image.js";
+const IMAGE_ATTACHMENT_QUESTION_ID = "q-image-attachment";
+function getGoalBasePath() {
+    return join(getProjectRoot(), ".omk", "goals");
+}
+function printAlphaWarning(json) {
+    if (json)
+        return;
+    if (!process.env.OMK_GOAL_ALPHA) {
+        console.log(style.orange("⚠️  Goal interview is alpha. Set OMK_GOAL_ALPHA=1 to suppress this warning."));
+    }
+}
+function parseDepth(value) {
+    if (!value)
+        return undefined;
+    if (value === "light" || value === "standard" || value === "deep")
+        return value;
+    throw new UsageError(`Invalid depth: ${value} (expected light | standard | deep)`);
+}
+function parseMode(value) {
+    if (!value || value === "create")
+        return "create";
+    if (value === "refine")
+        return "refine";
+    throw new UsageError(`Invalid mode: ${value} (expected create | refine)`);
+}
+async function loadAnswersFile(root, filePath) {
+    const abs = join(root, filePath);
+    let content;
+    try {
+        content = await readFile(abs, "utf-8");
+    }
+    catch {
+        throw new NotFoundError(`Answers file not found: ${filePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new UsageError(`Answers file is not valid JSON: ${filePath}`);
+    }
+    const rows = Array.isArray(parsed)
+        ? parsed
+        : (parsed && typeof parsed === "object" && Array.isArray(parsed.answers)
+            ? parsed.answers
+            : null);
+    if (!rows) {
+        throw new UsageError(`Answers file must be an array or { "answers": [...] }: ${filePath}`);
+    }
+    const now = new Date().toISOString();
+    const answers = [];
+    for (const row of rows) {
+        if (!row || typeof row !== "object")
+            continue;
+        const r = row;
+        if (typeof r.questionId !== "string")
+            continue;
+        answers.push({
+            questionId: r.questionId,
+            answer: typeof r.answer === "string" ? r.answer : "",
+            answeredAt: typeof r.answeredAt === "string" ? r.answeredAt : now,
+            skipped: r.skipped === true ? true : undefined,
+        });
+    }
+    return answers;
+}
+function buildImageAttachment(imagePath) {
+    const img = readImageFile(imagePath);
+    if (!img.ok) {
+        throw new UsageError(img.error ?? `Unable to read image file: ${imagePath}`);
+    }
+    if (typeof img.dataUri !== "string" || typeof img.ext !== "string") {
+        throw new UsageError(`Image file could not be converted to a data URI: ${imagePath}`);
+    }
+    return {
+        name: basename(imagePath),
+        path: imagePath,
+        mimeType: `image/${img.ext}`,
+        dataUri: img.dataUri,
+        ext: img.ext,
+        source: "file",
+    };
+}
+function attachImageToSession(session, imagePath) {
+    const attachment = buildImageAttachment(imagePath);
+    const answeredAt = new Date().toISOString();
+    return {
+        ...session,
+        updatedAt: answeredAt,
+        answers: [
+            ...session.answers.filter((answer) => answer.questionId !== IMAGE_ATTACHMENT_QUESTION_ID),
+            {
+                questionId: IMAGE_ATTACHMENT_QUESTION_ID,
+                answer: `Image file: ${imagePath}`,
+                answeredAt,
+                skipped: false,
+            },
+        ],
+        findings: [
+            ...session.findings.filter((finding) => finding.sourceQuestionId !== IMAGE_ATTACHMENT_QUESTION_ID),
+            {
+                field: "attachments",
+                value: attachment,
+                sourceQuestionId: IMAGE_ATTACHMENT_QUESTION_ID,
+                confidence: 1,
+            },
+        ],
+    };
+}
+function renderQuestionsMarkdown(session) {
+    const lines = [
+        `# Interview Questions — ${session.sessionId}`,
+        "",
+        `**Mode:** ${session.mode}  |  **Depth:** ${session.depth}  |  **Ambiguity:** ${session.ambiguity}`,
+        "",
+        "| # | Score | Req | Target | Kind | Prompt |",
+        "|---|-------|-----|--------|------|--------|",
+    ];
+    session.questions.forEach((q, i) => {
+        const req = q.required ? "✓" : "";
+        lines.push(`| ${i + 1} | ${q.score} | ${req} | ${q.targetField} | ${q.kind} | ${q.prompt.replace(/\|/g, "\\|")} |`);
+    });
+    lines.push("");
+    return lines.join("\n");
+}
+function renderReportMarkdown(session) {
+    const c = session.completeness;
+    const lines = [
+        `# Interview Report — ${session.sessionId}`,
+        "",
+        `**Status:** ${session.status}  |  **Mode:** ${session.mode}  |  **Depth:** ${session.depth}`,
+        `**Ambiguity:** ${session.ambiguity}  |  **Completeness:** ${c.overall}`,
+        "",
+        "## Completeness by axis",
+        "",
+        `- objective: ${c.objective}`,
+        `- successCriteria: ${c.successCriteria}`,
+        `- evidence: ${c.evidence}`,
+        `- artifacts: ${c.artifacts}`,
+        `- constraints: ${c.constraints}`,
+        `- risks: ${c.risks}`,
+        `- authority: ${c.authority}`,
+        "",
+    ];
+    if (c.criticalMissing.length > 0) {
+        lines.push("## Critical missing fields", "", ...c.criticalMissing.map((m) => `- ${m}`), "");
+    }
+    if (c.contradictions.length > 0) {
+        lines.push("## Unresolved contradictions", "", ...c.contradictions.map((m) => `- ${m}`), "");
+    }
+    lines.push("## Answers", "");
+    if (session.answers.length === 0) {
+        lines.push("_No answers recorded yet._", "");
+    }
+    else {
+        for (const a of session.answers) {
+            if (a.skipped) {
+                lines.push(`- **${a.questionId}**: _(skipped)_`);
+            }
+            else {
+                lines.push(`- **${a.questionId}**: ${a.answer}`);
+            }
+        }
+        lines.push("");
+    }
+    lines.push("## Spec delta", "");
+    if (session.specDelta.changes.length === 0) {
+        lines.push("_No structured changes derived._", "");
+    }
+    else {
+        for (const ch of session.specDelta.changes) {
+            lines.push(`- \`${ch.op}\` **${String(ch.field)}** (conf ${ch.confidence}): ${JSON.stringify(ch.value)}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+async function writeSessionArtifacts(dir, session) {
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "interview.json"), `${JSON.stringify(session, null, 2)}\n`);
+    await writeFile(join(dir, "spec-delta.json"), `${JSON.stringify(session.specDelta, null, 2)}\n`);
+    await writeFile(join(dir, "questions.md"), renderQuestionsMarkdown(session));
+    await writeFile(join(dir, "interview-report.md"), renderReportMarkdown(session));
+    const answersJsonl = session.answers.map((a) => JSON.stringify(a)).join("\n");
+    await writeFile(join(dir, "answers.jsonl"), answersJsonl.length > 0 ? `${answersJsonl}\n` : "");
+}
+function printSessionSummary(session, sessionDir) {
+    console.log(header("Goal Interview"));
+    console.log(label("Session", session.sessionId));
+    console.log(label("Mode", session.mode));
+    console.log(label("Depth", session.depth));
+    console.log(label("Ambiguity", String(session.ambiguity)));
+    console.log(label("Completeness", String(session.completeness.overall)));
+    console.log(label("Status", session.status));
+    console.log(label("Questions", String(session.questions.length)));
+    console.log(label("Answers", String(session.answers.length)));
+    if (session.completeness.criticalMissing.length > 0) {
+        console.log(label("Missing", session.completeness.criticalMissing.join(", ")));
+    }
+    if (session.completeness.contradictions.length > 0) {
+        console.log(style.pink(`Contradictions: ${session.completeness.contradictions.join("; ")}`));
+    }
+    console.log("");
+    if (session.answers.length === 0) {
+        console.log(style.purpleBold("Top questions"));
+        for (const q of session.questions.slice(0, 6)) {
+            const req = q.required ? style.pink("[required]") : style.gray("[optional]");
+            console.log(`  ${req} (${q.score}) ${q.prompt}`);
+        }
+        console.log("");
+        console.log(style.gray("Answer via: omk goal interview \"<prompt>\" --answers answers.json --write-spec"));
+    }
+    console.log(status.success(`interview.json → ${join(sessionDir, "interview.json")}`));
+}
+export async function goalInterviewCommand(input, options) {
+    printAlphaWarning(options.json);
+    const root = getProjectRoot();
+    const persister = createGoalPersister(getGoalBasePath());
+    const mode = parseMode(options.mode);
+    const depth = parseDepth(options.depth);
+    const maxQuestions = options.maxQuestions ? Number.parseInt(options.maxQuestions, 10) : undefined;
+    if (maxQuestions !== undefined && (!Number.isFinite(maxQuestions) || maxQuestions <= 0)) {
+        throw new UsageError(`Invalid --max-questions: ${options.maxQuestions}`);
+    }
+    // Resolve existing goal for refine mode or when --goal-id / id positional is given.
+    const goalIdHint = options.goalId ?? (mode === "refine" ? input : undefined);
+    let existingGoal = null;
+    if (goalIdHint) {
+        existingGoal = await persister.load(goalIdHint);
+        if (!existingGoal) {
+            const msg = `Goal not found: ${goalIdHint}`;
+            emitError(msg, Boolean(options.json));
+            throw new NotFoundError(msg);
+        }
+    }
+    const rawPrompt = existingGoal
+        ? (existingGoal.rawPrompt || existingGoal.objective || existingGoal.title)
+        : (input ?? "");
+    if (!rawPrompt.trim()) {
+        throw new UsageError("A raw goal prompt or an existing --goal-id is required.");
+    }
+    // Redact secrets from the prompt before it reaches the session, the GoalSpec,
+    // persisted artifacts, or --json output.
+    const safePrompt = redactSecretText(rawPrompt);
+    const seed = {
+        rawPrompt: safePrompt,
+        riskLevel: existingGoal?.riskLevel,
+        goal: existingGoal ?? undefined,
+    };
+    let session = buildInterviewSession({
+        seed,
+        mode: existingGoal ? "refine" : mode,
+        depth,
+        maxQuestions,
+        goalId: existingGoal?.goalId,
+    });
+    if (options.answers) {
+        const answers = await loadAnswersFile(root, options.answers);
+        session = ingestAnswers(session, seed, answers);
+    }
+    if (options.image) {
+        session = attachImageToSession(session, options.image);
+    }
+    // Optionally apply the delta to a GoalSpec.
+    let savedGoalId = existingGoal?.goalId;
+    if (options.writeSpec) {
+        let goal;
+        if (existingGoal) {
+            const result = applyInterviewDelta(existingGoal, session.specDelta);
+            goal = updateGoalStatus(result.goal, result.goal.status, { planRevision: result.goal.planRevision + 1 });
+        }
+        else {
+            const base = createGoalSpec(safePrompt);
+            goal = applyInterviewDelta(base, session.specDelta).goal;
+        }
+        await persister.save(goal);
+        await persister.appendHistory(goal.goalId, {
+            at: new Date().toISOString(),
+            action: existingGoal ? "interview-refine" : "interview-create",
+            detail: {
+                sessionId: session.sessionId,
+                ambiguity: session.ambiguity,
+                completeness: session.completeness.overall,
+                changes: session.specDelta.changes.length,
+            },
+        });
+        savedGoalId = goal.goalId;
+        session.goalId = goal.goalId;
+        session.specDelta.goalId = goal.goalId;
+    }
+    // Persist interview artifacts. With a goal id, store under the goal dir.
+    const sessionDir = savedGoalId
+        ? join(getGoalBasePath(), savedGoalId, "interviews", session.sessionId)
+        : join(root, ".omk", "interviews", session.sessionId);
+    await writeSessionArtifacts(sessionDir, session);
+    if (options.json) {
+        console.log(JSON.stringify(session, null, 2));
+        return;
+    }
+    printSessionSummary(session, sessionDir);
+    if (savedGoalId) {
+        console.log(status.success(`goal spec written → ${savedGoalId}`));
+        console.log(style.gray(`Next: omk goal plan ${savedGoalId}`));
+    }
+}
+async function findLatestInterviewSessionId(goalDir) {
+    const interviewsDir = join(goalDir, "interviews");
+    try {
+        const entries = await readdir(interviewsDir, { withFileTypes: true });
+        const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+        return dirs.length > 0 ? dirs[dirs.length - 1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function goalRefineCommand(goalId, options) {
+    printAlphaWarning(options.json);
+    const persister = createGoalPersister(getGoalBasePath());
+    const goal = await persister.load(goalId);
+    if (!goal) {
+        const msg = `Goal not found: ${goalId}`;
+        emitError(msg, Boolean(options.json));
+        throw new NotFoundError(msg);
+    }
+    const goalDir = join(getGoalBasePath(), goalId);
+    const from = options.fromInterview ?? "latest";
+    const sessionId = from === "latest" ? await findLatestInterviewSessionId(goalDir) : from;
+    if (!sessionId) {
+        const msg = `No interview session found for goal: ${goalId}. Run: omk goal interview ${goalId} --mode refine --answers answers.json`;
+        emitError(msg, Boolean(options.json));
+        throw new NotFoundError(msg);
+    }
+    const deltaPath = join(goalDir, "interviews", sessionId, "spec-delta.json");
+    let delta;
+    try {
+        delta = JSON.parse(await readFile(deltaPath, "utf-8"));
+    }
+    catch {
+        const msg = `Interview spec-delta not found: ${deltaPath}`;
+        emitError(msg, Boolean(options.json));
+        throw new NotFoundError(msg);
+    }
+    const result = applyInterviewDelta(goal, delta);
+    const refined = updateGoalStatus(result.goal, result.goal.status, { planRevision: result.goal.planRevision + 1 });
+    await persister.save(refined);
+    await persister.appendHistory(goalId, {
+        at: new Date().toISOString(),
+        action: "refine",
+        detail: {
+            sessionId,
+            applied: result.appliedChanges.length,
+            skipped: result.skippedChanges.length,
+            contradictions: result.contradictions.length,
+            planRevision: refined.planRevision,
+        },
+    });
+    if (options.plan) {
+        const { goalPlanCommand } = await import("./goal.js");
+        await goalPlanCommand(goalId, { json: options.json });
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            goalId,
+            sessionId,
+            applied: result.appliedChanges.length,
+            skipped: result.skippedChanges.length,
+            contradictions: result.contradictions,
+            planRevision: refined.planRevision,
+            status: refined.status,
+        }, null, 2));
+        return;
+    }
+    console.log(header("Goal Refined"));
+    console.log(label("ID", goalId));
+    console.log(label("From interview", sessionId));
+    console.log(label("Applied changes", String(result.appliedChanges.length)));
+    console.log(label("Skipped changes", String(result.skippedChanges.length)));
+    console.log(label("Plan revision", String(refined.planRevision)));
+    if (result.contradictions.length > 0) {
+        console.log(style.pink(`Contradictions: ${result.contradictions.join("; ")}`));
+    }
+    console.log(style.gray(`Next: omk goal plan ${goalId}`));
+}

package/dist/commands/merge.js

@@ -11,6 +11,7 @@ import { getOmkResourceSettings } from "../util/resource-profile.js";
 import { defaultScopedRoleAgentFile, writeScopedAgentFile } from "../util/scoped-agent-file.js";
 import { createOmkJsonEnvelope } from "../util/json-envelope.js";
 import { emitJson } from "../util/cli-contract.js";
+import { runMergeArbiter, } from "../orchestration/merge-arbiter.js";
 /**
  * JSON path for `omk merge --json`.
  * Read-only preview: resolves the run, collects worktree diffs (git diff +
@@ -138,65 +139,110 @@ export async function mergeCommand(options) {
     if (dryRun)
         console.log(style.orange("🟡 DRY RUN — no changes will be applied"));
     console.log("");
-    // ── 1. Collect diffs from all worktrees ──
-    const workers = [];
-    for (const name of workerNames) {
-        const wtPath = join(worktreesDir, name);
-        const diffResult = await runShell("git", ["-C", wtPath, "diff", currentBranch], { timeout: 15000 });
-        if (diffResult.failed || !diffResult.stdout.trim()) {
-            console.log(style.gray(`  ${name}: no changes`));
-            continue;
-        }
-        const diff = diffResult.stdout;
-        const diffLines = diff.split("\n").length;
-        // Check apply-ability
-        const applyCheck = await runShell("git", ["apply", "--check"], {
-            cwd: root,
-            input: diff,
-            timeout: 15000,
+    let report;
+    let winner = null;
+    if (strategy === "arbiter") {
+        // ── Arbiter path ──
+        console.log(style.purple("Running merge arbiter..."));
+        const config = await readTextFile(join(root, ".omk", "config.toml"), "");
+        const arbiterResult = await runMergeArbiter(worktreesDir, currentBranch, root, config, {
+            threshold: 0.6,
+            testTimeoutMs: 120_000,
         });
-        const canApply = !applyCheck.failed;
-        workers.push({ name, path: wtPath, diff, diffLines, canApply });
-        console.log(`  ${style.purpleBold(name)} ${canApply ? style.mint("(clean)") : style.pink("(conflicts)")} ${style.gray(`${diffLines} lines`)}`);
-    }
-    if (workers.length === 0) {
-        console.log(status.warn("No worker changes to merge."));
-        return;
-    }
-    // ── 2. Reviewer scoring ──
-    console.log("");
-    console.log(style.purple("Scoring diffs with reviewer..."));
-    for (const w of workers) {
-        const score = await scoreDiff(w.diff, w.name);
-        w.reviewScore = score.score;
-        w.reviewReason = score.reason;
-        const color = score.score >= 80 ? style.mint : score.score >= 50 ? style.orange : style.pink;
-        console.log(`  ${w.name}: ${color(`${score.score}/100`)} ${style.gray(score.reason)}`);
-    }
-    // ── 3. Test verification in worktrees ──
-    console.log("");
-    console.log(style.purple("Running tests in worktrees..."));
-    for (const w of workers) {
-        const testResult = await runShell("sh", ["-c", "npm test 2>/dev/null || pnpm test 2>/dev/null || yarn test 2>/dev/null || true"], {
-            cwd: w.path,
-            timeout: 120_000,
+        // Map arbiter candidates back to WorkerDiff for reporting
+        const arbiterWorkers = arbiterResult.trace.steps
+            .filter((s) => s.step === "evidence-suite" || s.step === "score")
+            .map((s) => {
+            return {
+                name: s.candidateId.replace("candidate-", ""),
+                path: "",
+                diff: "",
+                diffLines: 0,
+                canApply: s.detail.includes("apply=true"),
+                reviewScore: 50,
+                reviewReason: s.detail,
+                testsPassed: s.detail.includes("tests=true"),
+            };
         });
-        w.testsPassed = !testResult.failed;
-        console.log(`  ${w.name}: ${w.testsPassed ? style.mint("tests passed") : style.pink("tests failed")}`);
+        // De-duplicate by name
+        const workerMap = new Map();
+        for (const w of arbiterWorkers)
+            workerMap.set(w.name, w);
+        report = {
+            winner: arbiterResult.winner?.name ?? null,
+            reason: arbiterResult.rationale.summary,
+            conflicts: arbiterResult.rationale.conflicts,
+            filesApplied: 0,
+            dryRun,
+            workers: [...workerMap.values()],
+        };
+        if (arbiterResult.requiresHumanApproval) {
+            console.log(status.error(arbiterResult.rationale.humanApprovalReason ?? "No candidate meets threshold — human approval required."));
+            printReport(report);
+            process.exit(1);
+        }
+        winner = arbiterResult.winner ? { name: arbiterResult.winner.name, path: arbiterResult.winner.path, diff: arbiterResult.winner.diff, diffLines: arbiterResult.winner.diffLines, canApply: arbiterResult.winner.canApply, reviewScore: arbiterResult.winner.evidence.reviewerScore, reviewReason: arbiterResult.winner.evidence.reviewerReason, testsPassed: arbiterResult.winner.evidence.testsPassed } : null;
+    }
+    else {
+        // ── 1. Collect diffs from all worktrees ──
+        const workers = [];
+        for (const name of workerNames) {
+            const wtPath = join(worktreesDir, name);
+            const diffResult = await runShell("git", ["-C", wtPath, "diff", currentBranch], { timeout: 15000 });
+            if (diffResult.failed || !diffResult.stdout.trim()) {
+                console.log(style.gray(`  ${name}: no changes`));
+                continue;
+            }
+            const diff = diffResult.stdout;
+            const diffLines = diff.split("\n").length;
+            // Check apply-ability
+            const applyCheck = await runShell("git", ["apply", "--check"], {
+                cwd: root,
+                input: diff,
+                timeout: 15000,
+            });
+            const canApply = !applyCheck.failed;
+            workers.push({ name, path: wtPath, diff, diffLines, canApply });
+            console.log(`  ${style.purpleBold(name)} ${canApply ? style.mint("(clean)") : style.pink("(conflicts)")} ${style.gray(`${diffLines} lines`)}`);
+        }
+        if (workers.length === 0) {
+            console.log(status.warn("No worker changes to merge."));
+            return;
+        }
+        // ── 2. Reviewer scoring ──
+        console.log("");
+        console.log(style.purple("Scoring diffs with reviewer..."));
+        for (const w of workers) {
+            const score = await scoreDiff(w.diff, w.name);
+            w.reviewScore = score.score;
+            w.reviewReason = score.reason;
+            const color = score.score >= 80 ? style.mint : score.score >= 50 ? style.orange : style.pink;
+            console.log(`  ${w.name}: ${color(`${score.score}/100`)} ${style.gray(score.reason)}`);
+        }
+        // ── 3. Test verification in worktrees ──
+        console.log("");
+        console.log(style.purple("Running tests in worktrees..."));
+        for (const w of workers) {
+            const testResult = await runShell("sh", ["-c", "npm test 2>/dev/null || pnpm test 2>/dev/null || yarn test 2>/dev/null || true"], {
+                cwd: w.path,
+                timeout: 120_000,
+            });
+            w.testsPassed = !testResult.failed;
+            console.log(`  ${w.name}: ${w.testsPassed ? style.mint("tests passed") : style.pink("tests failed")}`);
+        }
+        // ── 4. Select winner ──
+        console.log("");
+        console.log(style.purple("Selecting winner..."));
+        winner = selectWinner(workers, strategy);
+        report = {
+            winner: winner?.name ?? null,
+            reason: winner?.reviewReason ?? "No suitable candidate",
+            conflicts: workers.filter((w) => !w.canApply).map((w) => w.name),
+            filesApplied: 0,
+            dryRun,
+            workers,
+        };
     }
-    // ── 4. Select winner ──
-    console.log("");
-    console.log(style.purple("Selecting winner..."));
-    const winner = selectWinner(workers, strategy);
-    // ── 5. Apply or preview ──
-    const report = {
-        winner: winner?.name ?? null,
-        reason: winner?.reviewReason ?? "No suitable candidate",
-        conflicts: workers.filter((w) => !w.canApply).map((w) => w.name),
-        filesApplied: 0,
-        dryRun,
-        workers,
-    };
     if (!winner) {
         console.log(status.error("No worker diff can be applied cleanly."));
         printReport(report);

package/dist/contracts/interview.d.ts

@@ -0,0 +1,106 @@
+import type { GoalSpec, RiskLevel } from "./goal.js";
+export declare const INTERVIEW_SCHEMA_VERSION: "omk.interview.v1";
+export declare const INTERVIEW_DELTA_SCHEMA_VERSION: "omk.interview-delta.v1";
+export type InterviewDepth = "light" | "standard" | "deep";
+export type InterviewMode = "create" | "refine";
+export type InterviewQuestionKind = "objective" | "success-criteria" | "artifact" | "constraint" | "non-goal" | "risk" | "authority" | "evidence" | "dependency" | "rollback";
+/**
+ * Field on GoalSpec (or a derived structure) that an answer is meant to fill.
+ * A question without a targetField is low quality and must be dropped.
+ */
+export type InterviewTargetField = "objective" | "successCriteria" | "expectedArtifacts" | "constraints" | "nonGoals" | "risks" | "riskLevel" | "intentFrame" | "actionAtoms";
+export interface InterviewQuestion {
+    id: string;
+    kind: InterviewQuestionKind;
+    prompt: string;
+    required: boolean;
+    targetField: InterviewTargetField;
+    /** 0..1 — how much answering reduces uncertainty about the goal. */
+    informationGain: number;
+    /** 0..1 — how much answering reduces execution risk. */
+    riskReduction: number;
+    /** 0..1 — how strongly the answer reshapes the execution DAG. */
+    dagImpact: number;
+    /** 0..1 — how strongly the answer strengthens evidence gates. */
+    evidenceImpact: number;
+    /** 0..1 — burden on the user (penalty). */
+    userCost: number;
+    /** Derived ranking score, 0..1, rounded to 2 decimals. */
+    score: number;
+}
+export interface InterviewAnswer {
+    questionId: string;
+    answer: string;
+    answeredAt: string;
+    skipped?: boolean;
+}
+export interface InterviewFinding {
+    field: InterviewTargetField | string;
+    value: unknown;
+    sourceQuestionId: string;
+    /** 0..1 confidence that this finding is correct and explicit. */
+    confidence: number;
+    /** True when this finding contradicts an existing explicit value. */
+    conflict?: boolean;
+}
+export interface InterviewCompleteness {
+    /** Weighted overall completeness, 0..1. */
+    overall: number;
+    objective: number;
+    successCriteria: number;
+    evidence: number;
+    artifacts: number;
+    constraints: number;
+    risks: number;
+    authority: number;
+    /** Required fields with no usable value yet. */
+    criticalMissing: string[];
+    /** Unresolved contradictions between answers and existing values. */
+    contradictions: string[];
+}
+export type InterviewDeltaField = keyof GoalSpec | "successCriteria" | "expectedArtifacts" | "riskLevel";
+export interface InterviewSpecChange {
+    field: InterviewDeltaField;
+    op: "add" | "replace" | "remove";
+    value: unknown;
+    sourceQuestionId: string;
+    /** 0..1 confidence used by the conflict resolver. */
+    confidence: number;
+}
+export interface InterviewSpecDelta {
+    schemaVersion: typeof INTERVIEW_DELTA_SCHEMA_VERSION;
+    goalId?: string;
+    changes: InterviewSpecChange[];
+}
+export type InterviewStatus = "open" | "complete" | "blocked";
+export interface InterviewSession {
+    schemaVersion: typeof INTERVIEW_SCHEMA_VERSION;
+    sessionId: string;
+    goalId?: string;
+    mode: InterviewMode;
+    depth: InterviewDepth;
+    createdAt: string;
+    updatedAt: string;
+    rawPrompt?: string;
+    /** Ambiguity score 0..1; higher means more interview is needed. */
+    ambiguity: number;
+    questions: InterviewQuestion[];
+    answers: InterviewAnswer[];
+    findings: InterviewFinding[];
+    completeness: InterviewCompleteness;
+    specDelta: InterviewSpecDelta;
+    status: InterviewStatus;
+}
+/** Inputs the question bank needs to derive candidate questions. */
+export interface InterviewSeed {
+    rawPrompt: string;
+    riskLevel?: RiskLevel;
+    goal?: GoalSpec;
+}
+/** Result of applying a spec delta to a GoalSpec. */
+export interface InterviewApplyResult {
+    goal: GoalSpec;
+    appliedChanges: InterviewSpecChange[];
+    skippedChanges: InterviewSpecChange[];
+    contradictions: string[];
+}