@lsctech/polaris 0.3.29 → 0.4.1

package/dist/autoresearch/score.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Autoresearch scoring engine.
+ *
+ * Reads run artifacts, evaluates binary gates, and produces a structured
+ * diagnosis report:
+ *
+ *   {
+ *     run_id, cluster_id, evaluated_at,
+ *     gate_results: GateResult[],
+ *     failed_gates: string[],
+ *     score: number (0.0–1.0),
+ *     diagnosis_hints: { gate, fix_zone, hint }[]
+ *   }
+ *
+ * Score = passed_gates / evaluable_gates (skipped gates are not counted).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRunArtifacts = loadRunArtifacts;
+exports.computeScore = computeScore;
+exports.buildDiagnosisHints = buildDiagnosisHints;
+exports.scoreRun = scoreRun;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const gates_js_1 = require("./gates.js");
+// ──────────────────────────────────────────────
+// Diagnosis hints table
+// ──────────────────────────────────────────────
+const HINTS = {
+    "user-intervened": {
+        fix_zone: "worker-prompt / packet-scope",
+        hint: "User pushed commits after polaris-finalize. Review the worker packet scope and instructions for ambiguity.",
+    },
+    "foreman-resent-packet": {
+        fix_zone: "foreman-dispatch / dispatch-boundary",
+        hint: "Foreman dispatched the same child more than once. Check for state-machine bugs in dispatch-boundary.ts or loop continue logic.",
+    },
+    "foreman-fixed-worker-output": {
+        fix_zone: "worker-prompt / scope-contract",
+        hint: "Foreman made corrective commits after child-complete. Tighten the worker packet's allowed_scope and acceptance criteria.",
+    },
+    "worker-output-required-fixing": {
+        fix_zone: "worker-prompt / validation-commands",
+        hint: "Post-finalize commits indicate worker output was insufficient. Add stricter validation commands to the worker packet.",
+    },
+    "validation-failed": {
+        fix_zone: "worker-validation / build-setup",
+        hint: "One or more children failed validation. Check the validation_commands in the worker packet and the worker's implementation.",
+    },
+    "worker-went-out-of-scope": {
+        fix_zone: "worker-packet / scope-contract",
+        hint: "Worker emitted out-of-scope blocks or returned blocked status. Narrow allowed_scope in the worker packet.",
+    },
+    "foreman-token-burn-over-budget": {
+        fix_zone: "bootstrap-context / prompt-size",
+        hint: "Foreman bootstrap context exceeds token budget. Reduce current-state.json or worker packet size before dispatch.",
+    },
+    "state-repair-required": {
+        fix_zone: "medic / cluster-state",
+        hint: "Medic artifacts detected — state repair was required during this run. Review the medic chart and root cause.",
+    },
+};
+// ──────────────────────────────────────────────
+// Artifact loader
+// ──────────────────────────────────────────────
+function findRunDir(repoRoot, runId) {
+    // Standard taskchain location
+    const taskchainPath = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "runs", runId);
+    if ((0, node_fs_1.existsSync)(taskchainPath))
+        return taskchainPath;
+    // Legacy .polaris/runs location
+    const polarisPath = (0, node_path_1.join)(repoRoot, ".polaris", "runs", runId);
+    if ((0, node_fs_1.existsSync)(polarisPath))
+        return polarisPath;
+    return null;
+}
+function findClusterDir(repoRoot, clusterId) {
+    const path = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId);
+    return (0, node_fs_1.existsSync)(path) ? path : null;
+}
+function readJson(filePath) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function readResultPackets(clusterDir) {
+    if (!clusterDir)
+        return [];
+    const resultsDir = (0, node_path_1.join)(clusterDir, "results");
+    if (!(0, node_fs_1.existsSync)(resultsDir))
+        return [];
+    return safeReaddir(resultsDir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => readJson((0, node_path_1.join)(resultsDir, f)))
+        .filter((v) => v !== undefined);
+}
+function extractWorkerResultContracts(resultPackets) {
+    const contracts = [];
+    for (const packet of resultPackets) {
+        const rec = packet;
+        // WorkerResultContract has packet_hash, worker_id, role as distinguishing fields
+        if (rec && typeof rec["packet_hash"] === "string" && typeof rec["worker_id"] === "string") {
+            contracts.push(rec);
+        }
+    }
+    return contracts;
+}
+function loadRunArtifacts(repoRoot, runId) {
+    const runDir = findRunDir(repoRoot, runId);
+    // Derive cluster from current-state.json in the run dir, or fallback to the default
+    let clusterId = null;
+    let currentState = null;
+    // Try run dir's current-state.json first
+    if (runDir) {
+        const runStatePath = (0, node_path_1.join)(runDir, "current-state.json");
+        if ((0, node_fs_1.existsSync)(runStatePath)) {
+            currentState = readJson(runStatePath);
+        }
+    }
+    // Fall back to the active current-state.json
+    if (!currentState) {
+        const taskchainState = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
+        const polarisState = (0, node_path_1.join)(repoRoot, ".polaris", "runs", "current-state.json");
+        const statePath = (0, node_fs_1.existsSync)(taskchainState) ? taskchainState : polarisState;
+        if ((0, node_fs_1.existsSync)(statePath)) {
+            currentState = readJson(statePath);
+        }
+    }
+    if (currentState && typeof currentState === "object" && currentState !== null) {
+        const rec = currentState;
+        if (typeof rec["cluster_id"] === "string")
+            clusterId = rec["cluster_id"];
+        if (typeof rec["run_id"] === "string" && rec["run_id"] !== runId) {
+            // State belongs to a different run — don't use it for cluster_id derivation
+            clusterId = null;
+        }
+    }
+    const clusterDir = clusterId ? findClusterDir(repoRoot, clusterId) : null;
+    // Ledger
+    const ledgerPath = (0, node_path_1.join)(repoRoot, ".polaris", "runs", "ledger.jsonl");
+    const ledgerEvents = (0, gates_js_1.readJsonLines)(ledgerPath).filter((e) => {
+        const rec = e;
+        return rec?.["run_id"] === runId;
+    });
+    // Telemetry — prefer the run dir; some older runs have it in .polaris/runs/<runId>/
+    const telemetryPath = runDir ? (0, node_path_1.join)(runDir, "telemetry.jsonl") : null;
+    const telemetryEvents = telemetryPath ? (0, gates_js_1.readJsonLines)(telemetryPath) : [];
+    // Result packets from cluster results dir
+    const resultPackets = readResultPackets(clusterDir);
+    // Also check for WorkerResultContracts inside result packets
+    const workerResultContracts = extractWorkerResultContracts(resultPackets);
+    return {
+        runId,
+        runDir,
+        clusterDir,
+        currentState,
+        ledgerEvents,
+        resultPackets,
+        workerResultContracts,
+        telemetryEvents,
+    };
+}
+// ──────────────────────────────────────────────
+// Scoring
+// ──────────────────────────────────────────────
+function computeScore(gateResults) {
+    const evaluable = gateResults.filter((g) => g.outcome !== "skipped");
+    if (evaluable.length === 0)
+        return 1.0; // nothing to evaluate — no known problems
+    const passed = evaluable.filter((g) => g.outcome === "passed").length;
+    return passed / evaluable.length;
+}
+function buildDiagnosisHints(failedGateNames) {
+    return failedGateNames.map((gate) => {
+        const h = HINTS[gate] ?? { fix_zone: "unknown", hint: `Gate ${gate} failed — no hint available.` };
+        return { gate, ...h };
+    });
+}
+// ──────────────────────────────────────────────
+// Main entry point
+// ──────────────────────────────────────────────
+function scoreRun(repoRoot, runId) {
+    const artifacts = loadRunArtifacts(repoRoot, runId);
+    const gateResults = gates_js_1.ALL_GATES.map((evaluator) => evaluator(artifacts));
+    const failedGates = gateResults.filter((g) => g.outcome === "failed").map((g) => g.gate);
+    const score = computeScore(gateResults);
+    const diagnosisHints = buildDiagnosisHints(failedGates);
+    const clusterId = artifacts.currentState &&
+        typeof artifacts.currentState === "object" &&
+        !Array.isArray(artifacts.currentState)
+        ? artifacts.currentState["cluster_id"] ?? null
+        : null;
+    return {
+        run_id: runId,
+        cluster_id: clusterId,
+        evaluated_at: new Date().toISOString(),
+        gate_results: gateResults,
+        failed_gates: failedGates,
+        score,
+        diagnosis_hints: diagnosisHints,
+    };
+}

package/dist/cli/adopt-approve.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.persistApprovedAdoptionPlan = persistApprovedAdoptionPlan;
 exports.logAdoptionApprovalTelemetry = logAdoptionApprovalTelemetry;
 exports.promptApproval = promptApproval;
+exports.promptCategoryApproval = promptCategoryApproval;
+exports.requireApprovalGates = requireApprovalGates;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const promises_1 = require("node:readline/promises");
@@ -36,9 +38,10 @@ async function promptApproval(plan, options = {}) {
     const stdout = options.stdout ?? process.stdout;
     const stdin = options.stdin ?? process.stdin;
     const markdownPath = adoptionPlanMarkdownPath(repoRoot);
-    const markdown = (0, node_fs_1.existsSync)(markdownPath)
-        ? (0, node_fs_1.readFileSync)(markdownPath, "utf-8")
-        : (0, adoption_plan_js_1.renderAdoptionPlanMarkdown)(plan);
+    const markdown = options.markdown ??
+        ((0, node_fs_1.existsSync)(markdownPath)
+            ? (0, node_fs_1.readFileSync)(markdownPath, "utf-8")
+            : (0, adoption_plan_js_1.renderAdoptionPlanMarkdown)(plan));
     stdout.write(`${markdown.replace(/\s*$/, "")}\n\n`);
     const rl = (0, promises_1.createInterface)({
         input: stdin,
@@ -52,9 +55,126 @@ async function promptApproval(plan, options = {}) {
         rl.close();
     }
     if (response.trim().toLowerCase() === "y") {
-        persistApprovedAdoptionPlan(plan, repoRoot, options.now ?? new Date());
+        const approvalNow = options.now ?? new Date();
+        if (options.persist) {
+            options.persist(plan, repoRoot, approvalNow);
+        }
+        else {
+            persistApprovedAdoptionPlan(plan, repoRoot, approvalNow);
+        }
         return true;
     }
     stdout.write("Adoption aborted: explicit approval required.\n");
     return false;
 }
+/** Map of category → step categories in AdoptionStep */
+const CATEGORY_STEP_MAP = {
+    "doc-movement": ["smartdocs-migrate"],
+    "instruction-file": ["instruction-refactor"],
+    "graph-root": ["cognition-generate", "atlas-generate"],
+    "route-scaffold": ["scaffold"],
+};
+const CATEGORY_LABELS = {
+    "doc-movement": "Document Movement",
+    "instruction-file": "Instruction-File Changes",
+    "graph-root": "Graph-Root / Cognition Changes",
+    "route-scaffold": "Route Scaffolding",
+};
+/**
+ * Render a compact diff preview for the given steps.
+ */
+function renderStepDiff(steps) {
+    if (steps.length === 0)
+        return "  (no steps)\n";
+    return steps
+        .map((s) => {
+        const src = s.source_path ? ` ${s.source_path} →` : "";
+        const dst = s.dest_path ? ` ${s.dest_path}` : "";
+        const routing = s.routing ? ` [${s.routing}]` : "";
+        return `  ${s.action.toUpperCase()}${src}${dst}${routing}  — ${s.description}`;
+    })
+        .join("\n") + "\n";
+}
+/**
+ * Ask the operator for approval of a single mutation category.
+ * Returns true if approved, false if declined.
+ * Logs the decision via adoption telemetry.
+ */
+async function promptCategoryApproval(category, steps, options = {}) {
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const stdout = options.stdout ?? process.stdout;
+    const stdin = options.stdin ?? process.stdin;
+    const label = CATEGORY_LABELS[category];
+    const actionableSteps = steps.filter((s) => s.action !== "skip");
+    if (actionableSteps.length === 0)
+        return true;
+    stdout.write(`\n--- ${label} (${actionableSteps.length} step(s)) ---\n`);
+    stdout.write(renderStepDiff(actionableSteps));
+    const rl = (0, promises_1.createInterface)({ input: stdin, output: stdout });
+    let response = "";
+    try {
+        response = await rl.question(`Approve ${label}? [y/N] `);
+    }
+    finally {
+        rl.close();
+    }
+    const approved = response.trim().toLowerCase() === "y";
+    const now = (options.now ?? new Date()).toISOString();
+    logAdoptionApprovalTelemetry(repoRoot, {
+        event: "category-approval",
+        category,
+        approved,
+        step_count: actionableSteps.length,
+        timestamp: now,
+    });
+    if (!approved) {
+        stdout.write(`Adoption aborted: ${label} approval required.\n`);
+    }
+    return approved;
+}
+/**
+ * Fire approval gates for all four mutation categories in sequence.
+ * Returns false (and stops) at the first declined category.
+ *
+ * For non-interactive runs (no tty + no supplied stdin), returns false immediately
+ * unless `options.stdin` is explicitly set (which signals the caller supplied a context stream).
+ */
+async function requireApprovalGates(plan, options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    // Non-interactive guard: if stdin is not a TTY and the caller hasn't explicitly supplied one,
+    // block before mutation (acceptance criterion 2).
+    if (!options.nonInteractiveSafe && stdin === process.stdin && !process.stdin.isTTY) {
+        const stdout = options.stdout ?? process.stdout;
+        stdout.write("Adoption aborted: non-interactive run requires a supplied context file (--context) or explicit approval.\n");
+        logAdoptionApprovalTelemetry(options.repoRoot ?? process.cwd(), {
+            event: "category-approval-blocked",
+            reason: "non-interactive",
+            timestamp: new Date().toISOString(),
+        });
+        return false;
+    }
+    const categories = [
+        "route-scaffold",
+        "doc-movement",
+        "instruction-file",
+        "graph-root",
+    ];
+    for (const category of categories) {
+        const stepCategories = CATEGORY_STEP_MAP[category];
+        const steps = plan.steps.filter((s) => {
+            if (!stepCategories.includes(s.category))
+                return false;
+            // Doc-movement gate only fires for steps that migrateSmartDocs will execute
+            if (category === "doc-movement" && s.routing !== "candidate")
+                return false;
+            return true;
+        });
+        // Skip gate if no actionable steps in this category
+        if (steps.filter((s) => s.action !== "skip").length === 0)
+            continue;
+        const approved = await promptCategoryApproval(category, steps, options);
+        if (!approved)
+            return false;
+    }
+    return true;
+}

package/dist/cli/adopt-assets.js

@@ -6,6 +6,7 @@ exports.runGraphBuild = runGraphBuild;
 const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = require("node:path");
+const sync_js_1 = require("../agent-plugin/sync.js");
 function isAncestorSymlink(repoRoot, relPath) {
     const parts = relPath.split("/").filter(Boolean);
     for (let i = 0; i < parts.length - 1; i++) {
@@ -168,7 +169,14 @@ function installWorkspaceAssets(repoRoot, workspaceDir) {
             installed.push(rulesRel);
         }
     }
-    return { installed, alreadyPresent, skipped, conflicted };
+    // 6. Agent-plugin shims (Claude Code commands)
+    const shimOutDir = (0, node_path_1.join)(repoRoot, ".claude", "commands");
+    if (isAncestorSymlink(repoRoot, ".claude/commands")) {
+        skipped.push(".claude/commands");
+        return { installed, alreadyPresent, skipped, conflicted };
+    }
+    const shimSync = (0, sync_js_1.syncShims)(shimOutDir);
+    return { installed, alreadyPresent, skipped, conflicted, shimSync };
 }
 function runGraphBuild(repoRoot) {
     try {

package/dist/cli/adopt-command.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAdoptionInterview = runAdoptionInterview;
 exports.runAdoptPhase = runAdoptPhase;
 exports.runFullAdoption = runFullAdoption;
 exports.createAdoptCommand = createAdoptCommand;
 const node_path_1 = require("node:path");
+const node_readline_1 = require("node:readline");
+const node_fs_1 = require("node:fs");
 const commander_1 = require("commander");
 const adopt_scan_js_1 = require("./adopt-scan.js");
 const adoption_plan_js_1 = require("./adoption-plan.js");
@@ -14,6 +17,71 @@ const adopt_rules_js_1 = require("./adopt-rules.js");
 const adopt_cognition_js_1 = require("./adopt-cognition.js");
 const adopt_canon_js_1 = require("./adopt-canon.js");
 const adopt_genesis_js_1 = require("./adopt-genesis.js");
+const generator_js_1 = require("../skill-packet/generator.js");
+const foreman_dispatch_js_1 = require("../loop/adapters/foreman-dispatch.js");
+const adoption_context_js_1 = require("./adoption-context.js");
+const adopt_approve_js_1 = require("./adopt-approve.js");
+/** Prompt a single question via stdin and return the trimmed answer. */
+async function prompt(question) {
+    const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Run a Foreman-led interview seeded from inventory gaps.
+ * Skips questions already answered (resume support).
+ */
+async function runAdoptionInterview(repoRoot, inventory) {
+    const existing = (0, adoption_context_js_1.loadOperatorContext)(repoRoot);
+    const ctx = existing ?? (0, adoption_context_js_1.createEmptyOperatorContext)();
+    // Seed: untrusted docs (smartdocs candidates not yet classified as trusted/stale)
+    const candidatePaths = inventory.smartdocs_candidates.map((c) => c.path);
+    const unclassified = candidatePaths.filter((p) => !ctx.trusted_docs.includes(p) && !ctx.stale_docs.includes(p));
+    if (unclassified.length > 0) {
+        process.stdout.write(`\nFound ${unclassified.length} doc candidate(s) not yet classified:\n` +
+            unclassified.map((p) => `  - ${p}`).join("\n") +
+            "\n");
+        const trusted = await prompt("Which of these are authoritative/trusted? (comma-separated paths, or leave blank to skip): ");
+        const stale = await prompt("Which are stale/outdated? (comma-separated paths, or leave blank to skip): ");
+        if (trusted)
+            ctx.trusted_docs.push(...trusted.split(",").map((s) => s.trim()).filter(Boolean));
+        if (stale)
+            ctx.stale_docs.push(...stale.split(",").map((s) => s.trim()).filter(Boolean));
+    }
+    // Seed: ambiguous source roots (more than one detected)
+    if (inventory.source_roots.length > 1 && ctx.priority_systems.length === 0) {
+        process.stdout.write(`\nMultiple source roots detected: ${inventory.source_roots.join(", ")}\n`);
+        const priority = await prompt("Which are the primary/priority systems? (comma-separated, or leave blank): ");
+        if (priority)
+            ctx.priority_systems.push(...priority.split(",").map((s) => s.trim()).filter(Boolean));
+    }
+    // Seed: instruction files not yet assigned intent
+    const unintended = inventory.agent_instruction_files
+        .map((f) => f.path)
+        .filter((p) => !(p in ctx.instruction_file_intent));
+    for (const filePath of unintended) {
+        const file = inventory.agent_instruction_files.find((f) => f.path === filePath);
+        const suggestion = file?.recommendation ?? "preserve";
+        const answer = await prompt(`Instruction file "${filePath}" — intent? [preserve/migrate/thin-adapter] (default: ${suggestion}): `);
+        const intent = ["preserve", "migrate", "thin-adapter"].find((v) => v === answer) ?? suggestion;
+        ctx.instruction_file_intent[filePath] = intent;
+    }
+    // Seed: canonical-folder candidates not yet classified as trusted or never-touch
+    const uncheckedFolders = inventory.likely_canonical_folders.filter((f) => !ctx.trusted_docs.includes(f) && !ctx.never_touch.includes(f));
+    if (uncheckedFolders.length > 0) {
+        process.stdout.write(`\nLikely canonical folders: ${uncheckedFolders.join(", ")}\n`);
+        const neverTouch = await prompt("Any folders that should never be touched by adoption? (comma-separated, or leave blank): ");
+        if (neverTouch)
+            ctx.never_touch.push(...neverTouch.split(",").map((s) => s.trim()).filter(Boolean));
+    }
+    ctx.answered_at = new Date().toISOString();
+    (0, adoption_context_js_1.saveOperatorContext)(repoRoot, ctx);
+    return ctx;
+}
 function estimateTokenCost(inventory) {
     const total = inventory.smartdocs_candidates.length +
         inventory.likely_canonical_folders.length;
@@ -29,11 +97,17 @@ async function runAdoptPhase(phase, repoRoot, options = {}) {
     switch (phase) {
         case "scan": {
             const inventory = await (0, adopt_scan_js_1.scanRepo)(repoRoot, { rescan: true });
-            const plan = (0, adoption_plan_js_1.generateAdoptionPlan)(inventory);
-            (0, adoption_plan_js_1.generateAdoptionPlanArtifacts)(repoRoot, inventory);
+            const operatorContext = (0, adoption_context_js_1.loadOperatorContext)(repoRoot) ?? undefined;
+            (0, adoption_plan_js_1.generateAdoptionPlanArtifacts)(repoRoot, inventory, { operatorContext });
             console.log(`Scan complete: ${inventory.smartdocs_candidates.length} doc(s), ${inventory.likely_canonical_folders.length} folder(s).`);
             break;
         }
+        case "interview": {
+            const inventory = options.inventory ?? (await (0, adopt_scan_js_1.scanRepo)(repoRoot, { rescan: false }));
+            await runAdoptionInterview(repoRoot, inventory);
+            console.log("Interview complete. Operator context saved.");
+            break;
+        }
         case "agents": {
             if (options.inventory) {
                 const cost = estimateTokenCost(options.inventory);
@@ -42,6 +116,24 @@ async function runAdoptPhase(phase, repoRoot, options = {}) {
             if (!options.skipAgents) {
                 await (0, agent_setup_js_1.runAgentSetup)(repoRoot);
             }
+            // Dispatch the Foreman with the setup-bootstrap packet.
+            try {
+                const configPath = (0, node_path_1.join)(repoRoot, "polaris.config.json");
+                const config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+                const execution = config.execution;
+                if (execution?.providers && Object.keys(execution.providers).length > 0) {
+                    const binding = await (0, agent_setup_js_1.resolveForeman)(repoRoot, config);
+                    const setupPacket = (0, generator_js_1.generateSetupBootstrapPacket)("adopt");
+                    await (0, foreman_dispatch_js_1.dispatchForeman)({
+                        packet: setupPacket,
+                        provider: binding.provider,
+                        executionConfig: execution,
+                    });
+                }
+            }
+            catch {
+                // Foreman dispatch is best-effort — don't block adoption.
+            }
             break;
         }
         case "consolidate": {
@@ -91,25 +183,34 @@ async function runAdoptPhase(phase, repoRoot, options = {}) {
     }
 }
 async function runFullAdoption(repoRoot, options = {}) {
-    console.log("[1/7] scan");
+    console.log("[1/8] scan");
     await runAdoptPhase("scan", repoRoot);
-    // Re-read inventory and plan for later phases
+    // Re-read inventory for later phases
     const inventory = await (0, adopt_scan_js_1.scanRepo)(repoRoot, { rescan: false });
-    const plan = (0, adoption_plan_js_1.generateAdoptionPlan)(inventory);
-    console.log("[2/7] agents");
+    console.log("[2/8] interview");
+    await runAdoptPhase("interview", repoRoot, { inventory });
+    // Regenerate plan after interview to incorporate operator context
+    const operatorContext = (0, adoption_context_js_1.loadOperatorContext)(repoRoot) ?? undefined;
+    const plan = (0, adoption_plan_js_1.generateAdoptionPlan)(inventory, { operatorContext });
+    console.log("[3/8] agents");
     await runAdoptPhase("agents", repoRoot, {
         inventory,
         skipAgents: options.skipAgents,
     });
-    console.log("[3/7] consolidate");
+    // Approval gates: one per mutation category before any broad mutation.
+    const gatesApproved = await (0, adopt_approve_js_1.requireApprovalGates)(plan, { repoRoot });
+    if (!gatesApproved) {
+        return;
+    }
+    console.log("[4/8] consolidate");
     await runAdoptPhase("consolidate", repoRoot, { inventory, plan });
-    console.log("[4/7] map");
+    console.log("[5/8] map");
     await runAdoptPhase("map", repoRoot);
-    console.log("[5/7] skills");
+    console.log("[6/8] skills");
     await runAdoptPhase("skills", repoRoot);
-    console.log("[6/7] rules");
+    console.log("[7/8] rules");
     await runAdoptPhase("rules", repoRoot, { inventory });
-    console.log("[7/7] canon");
+    console.log("[8/8] canon");
     await runAdoptPhase("canon", repoRoot, { inventory, plan });
 }
 function createAdoptCommand(opts) {
@@ -124,6 +225,17 @@ function createAdoptCommand(opts) {
         .action(async () => {
         await runAdoptPhase("scan", repoRoot);
     });
+    cmd
+        .command("interview")
+        .description("Run Foreman-led interview to capture operator context")
+        .action(async () => {
+        if (!process.stdin.isTTY) {
+            process.stderr.write("Error: the interview subcommand requires an interactive terminal.\n");
+            process.exit(1);
+        }
+        const inventory = await (0, adopt_scan_js_1.scanRepo)(repoRoot, { rescan: false });
+        await runAdoptPhase("interview", repoRoot, { inventory });
+    });
     cmd
         .command("agents")
         .description("Set up agent instruction files")

package/dist/cli/adopt-instructions.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleInstructionFiles = handleInstructionFiles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const adopt_approve_js_1 = require("./adopt-approve.js");
 const DELEGATION_MARKERS = ["<!-- polaris:delegate", "POLARIS_RULES.md", "POLARIS.md", "Polaris runtime"];
 function isSupportedInstructionPath(path) {
     return (path === "CLAUDE.md" ||
@@ -100,9 +101,23 @@ function appendInstructionProvenance(repoRoot, records) {
     };
     (0, node_fs_1.writeFileSync)(provenancePath, `${JSON.stringify(updated, null, 2)}\n`, "utf-8");
 }
-function handleInstructionFiles(plan, inventory, repoRoot) {
+async function handleInstructionFiles(plan, inventory, repoRoot, options = {}) {
     if (plan.dry_run) {
-        return Promise.resolve([]);
+        return [];
+    }
+    // Approval gate: show instruction-refactor steps and ask before mutating,
+    // unless the overall plan is already approved or the caller opts out.
+    if (!options.skipApprovalGate && !plan.approved) {
+        const instructionSteps = plan.steps.filter((s) => s.category === "instruction-refactor");
+        if (instructionSteps.filter((s) => s.action !== "skip").length > 0) {
+            const approved = await (0, adopt_approve_js_1.promptCategoryApproval)("instruction-file", instructionSteps, {
+                repoRoot,
+                stdin: options.stdin,
+                stdout: options.stdout,
+            });
+            if (!approved)
+                return [];
+        }
     }
     const doctrineExists = hasDoctrine(repoRoot);
     const now = new Date().toISOString();

package/dist/cli/adopt-smartdocs.js

@@ -120,6 +120,15 @@ function migrateSmartDocs(plan, repoRoot = (0, node_path_1.resolve)(process.cwd(
         if (step.category !== "smartdocs-migrate" || COMPLETE_STATUSES.has(step.status)) {
             continue;
         }
+        if (step.routing !== undefined && step.routing !== "candidate") {
+            effectivePlan.steps[index] = {
+                ...step,
+                status: "skipped",
+                completed_at: now,
+                error: `routing not candidate: ${step.routing}`,
+            };
+            continue;
+        }
         const sourcePath = step.source_path ?? "";
         const destPath = step.dest_path ?? `smartdocs/raw/${(0, node_path_1.basename)(sourcePath || `step-${step.order}.md`)}`;
         if (!sourcePath) {