@lsctech/polaris 0.3.29 → 0.4.0

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) {

package/dist/cli/adoption-context.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadOperatorContext = loadOperatorContext;
+exports.saveOperatorContext = saveOperatorContext;
+exports.createEmptyOperatorContext = createEmptyOperatorContext;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ADOPTION_DIR = (0, node_path_1.join)(".polaris", "adoption");
+const CONTEXT_FILE = "operator-context.json";
+function contextPath(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, ADOPTION_DIR, CONTEXT_FILE);
+}
+function loadOperatorContext(repoRoot) {
+    const path = contextPath(repoRoot);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"));
+        if (!Array.isArray(parsed?.trusted_docs) ||
+            !Array.isArray(parsed?.never_touch) ||
+            typeof parsed?.instruction_file_intent !== "object" ||
+            parsed?.instruction_file_intent === null ||
+            Array.isArray(parsed?.instruction_file_intent)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function saveOperatorContext(repoRoot, context) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, ADOPTION_DIR), { recursive: true });
+    (0, node_fs_1.writeFileSync)(contextPath(repoRoot), `${JSON.stringify(context, null, 2)}\n`, "utf-8");
+}
+function createEmptyOperatorContext(now) {
+    return {
+        schema_version: "1.0",
+        answered_at: (now ?? new Date()).toISOString(),
+        trusted_docs: [],
+        stale_docs: [],
+        never_touch: [],
+        priority_systems: [],
+        instruction_file_intent: {},
+    };
+}

package/dist/cli/adoption-plan.js

@@ -11,14 +11,49 @@ function formatPlanId(isoTimestamp) {
 function normalizePath(path) {
     return path.endsWith("/") ? path.slice(0, -1) : path;
 }
+function isTrusted(path, operatorContext) {
+    const normalized = normalizePath(path);
+    return operatorContext?.trusted_docs.some((p) => normalizePath(p) === normalized) ?? false;
+}
+function isStale(path, operatorContext) {
+    const normalized = normalizePath(path);
+    return operatorContext?.stale_docs.some((p) => normalizePath(p) === normalized) ?? false;
+}
+function isNeverTouch(path, operatorContext) {
+    const normalized = normalizePath(path);
+    return operatorContext?.never_touch.some((p) => normalizePath(p) === normalized) ?? false;
+}
+function instructionIntent(path, operatorContext) {
+    return operatorContext?.instruction_file_intent[path];
+}
+function deriveSmartDocsRouting(candidate, operatorContext) {
+    const evidence_refs = [`scan:smartdocs_candidate:${candidate.path}`];
+    const operator_refs = [];
+    if (isNeverTouch(candidate.path, operatorContext) || isStale(candidate.path, operatorContext)) {
+        if (isNeverTouch(candidate.path, operatorContext))
+            operator_refs.push(`operator:never_touch:${candidate.path}`);
+        if (isStale(candidate.path, operatorContext))
+            operator_refs.push(`operator:stale_docs:${candidate.path}`);
+        return { routing: "hold", evidence_refs, operator_refs };
+    }
+    if (isTrusted(candidate.path, operatorContext)) {
+        operator_refs.push(`operator:trusted_docs:${candidate.path}`);
+        return { routing: "candidate", evidence_refs, operator_refs };
+    }
+    return { routing: "review-required", evidence_refs, operator_refs };
+}
 function createStep(order, partial) {
+    const { evidence_refs, operator_refs, routing, ...rest } = partial;
     return {
-        ...partial,
+        evidence_refs: evidence_refs ?? [],
+        operator_refs: operator_refs ?? [],
+        routing: routing ?? "candidate",
+        ...rest,
         order,
         status: "pending",
     };
 }
-function buildSteps(inventory) {
+function buildSteps(inventory, operatorContext) {
     const steps = [];
     let order = 1;
     steps.push(createStep(order++, {
@@ -31,6 +66,9 @@ function buildSteps(inventory) {
         destructive: true,
         requires_approval: false,
         estimated_risk: "low",
+        routing: "candidate",
+        evidence_refs: ["adoption:step:provider-config-lock"],
+        operator_refs: [],
     }));
     steps.push(createStep(order++, {
         step_id: "adoption-scaffold",
@@ -42,6 +80,9 @@ function buildSteps(inventory) {
         destructive: false,
         requires_approval: false,
         estimated_risk: "low",
+        routing: "candidate",
+        evidence_refs: ["adoption:step:adoption-scaffold"],
+        operator_refs: [],
     }));
     steps.push(createStep(order++, {
         step_id: "workspace-root-surfaces",
@@ -53,10 +94,15 @@ function buildSteps(inventory) {
         destructive: false,
         requires_approval: false,
         estimated_risk: "low",
+        routing: "candidate",
+        evidence_refs: ["adoption:step:workspace-root-surfaces"],
+        operator_refs: [],
     }));
     for (const candidate of inventory.smartdocs_candidates) {
-        steps.push(createStep(order++, {
-            step_id: `smartdocs-migrate-${order.toString().padStart(3, "0")}`,
+        const { routing, evidence_refs, operator_refs } = deriveSmartDocsRouting(candidate, operatorContext);
+        const stepOrder = order++;
+        steps.push(createStep(stepOrder, {
+            step_id: `smartdocs-migrate-${stepOrder.toString().padStart(3, "0")}`,
             phase: "C",
             category: "smartdocs-migrate",
             action: "move",
@@ -66,12 +112,27 @@ function buildSteps(inventory) {
             destructive: true,
             requires_approval: true,
             estimated_risk: candidate.estimated_risk,
+            routing,
+            evidence_refs,
+            operator_refs,
         }));
     }
     for (const folder of inventory.likely_canonical_folders) {
         const normalizedFolder = normalizePath(folder);
-        steps.push(createStep(order++, {
-            step_id: `cognition-generate-${order.toString().padStart(3, "0")}`,
+        const evidence_refs = [`scan:canonical_folder:${normalizedFolder}`];
+        const operator_refs = [];
+        let routing = "raw";
+        if (isNeverTouch(normalizedFolder, operatorContext)) {
+            routing = "hold";
+            operator_refs.push(`operator:never_touch:${normalizedFolder}`);
+        }
+        else if (isTrusted(normalizedFolder, operatorContext)) {
+            routing = "candidate";
+            operator_refs.push(`operator:trusted_docs:${normalizedFolder}`);
+        }
+        const stepOrder = order++;
+        steps.push(createStep(stepOrder, {
+            step_id: `cognition-generate-${stepOrder.toString().padStart(3, "0")}`,
             phase: "C",
             category: "cognition-generate",
             action: "create",
@@ -80,6 +141,9 @@ function buildSteps(inventory) {
             destructive: false,
             requires_approval: true,
             estimated_risk: "medium",
+            routing,
+            evidence_refs,
+            operator_refs,
         }));
     }
     for (const file of inventory.agent_instruction_files) {
@@ -90,8 +154,24 @@ function buildSteps(inventory) {
             : file.recommendation === "thin-adapter"
                 ? "medium"
                 : "low";
-        steps.push(createStep(order++, {
-            step_id: `instruction-refactor-${order.toString().padStart(3, "0")}`,
+        const evidence_refs = [`scan:agent_instruction_file:${file.path}`];
+        const operator_refs = [];
+        const intent = instructionIntent(file.path, operatorContext);
+        let routing;
+        if (intent === "preserve") {
+            routing = "hold";
+            operator_refs.push(`operator:instruction_file_intent:${file.path}:preserve`);
+        }
+        else if (intent === "migrate" || intent === "thin-adapter") {
+            routing = "candidate";
+            operator_refs.push(`operator:instruction_file_intent:${file.path}:${intent}`);
+        }
+        else {
+            routing = "review-required";
+        }
+        const stepOrder = order++;
+        steps.push(createStep(stepOrder, {
+            step_id: `instruction-refactor-${stepOrder.toString().padStart(3, "0")}`,
             phase: "C",
             category: "instruction-refactor",
             action,
@@ -105,11 +185,15 @@ function buildSteps(inventory) {
             destructive,
             requires_approval: destructive,
             estimated_risk: risk,
+            routing,
+            evidence_refs,
+            operator_refs,
         }));
     }
     for (const ignorePath of inventory.ignore_candidates) {
-        steps.push(createStep(order++, {
-            step_id: `ignore-rules-${order.toString().padStart(3, "0")}`,
+        const stepOrder = order++;
+        steps.push(createStep(stepOrder, {
+            step_id: `ignore-rules-${stepOrder.toString().padStart(3, "0")}`,
             phase: "C",
             category: "ignore-rules",
             action: "append",
@@ -118,6 +202,9 @@ function buildSteps(inventory) {
             destructive: true,
             requires_approval: true,
             estimated_risk: "low",
+            routing: "candidate",
+            evidence_refs: [`scan:ignore_candidate:${ignorePath}`],
+            operator_refs: [],
         }));
     }
     steps.push(createStep(order++, {
@@ -130,6 +217,9 @@ function buildSteps(inventory) {
         destructive: true,
         requires_approval: true,
         estimated_risk: "medium",
+        routing: "candidate",
+        evidence_refs: ["adoption:step:atlas-generate"],
+        operator_refs: [],
     }));
     steps.push(createStep(order++, {
         step_id: "stage-adoption",
@@ -141,6 +231,9 @@ function buildSteps(inventory) {
         destructive: true,
         requires_approval: true,
         estimated_risk: "medium",
+        routing: "candidate",
+        evidence_refs: ["adoption:step:stage-adoption"],
+        operator_refs: [],
     }));
     return steps;
 }
@@ -160,7 +253,7 @@ function buildImpactSummary(steps, inventory) {
 }
 function generateAdoptionPlan(inventory, options = {}) {
     const generatedAt = (options.now ?? new Date()).toISOString();
-    const steps = buildSteps(inventory);
+    const steps = buildSteps(inventory, options.operatorContext);
     return {
         plan_id: formatPlanId(generatedAt),
         generated_at: generatedAt,
@@ -206,7 +299,7 @@ function renderAdoptionPlanMarkdown(plan) {
         for (const step of phaseSteps) {
             const source = step.source_path ? ` source: \`${step.source_path}\`` : "";
             const dest = step.dest_path ? ` destination: \`${step.dest_path}\`` : "";
-            lines.push(`- **${step.order}. ${step.step_id}** — ${step.category} / ${step.action} / approval ${step.requires_approval ? "required" : "not required"} / risk ${step.estimated_risk} / status ${step.status}${source}${dest}`);
+            lines.push(`- **${step.order}. ${step.step_id}** — ${step.category} / ${step.action} / approval ${step.requires_approval ? "required" : "not required"} / risk ${step.estimated_risk} / routing ${step.routing} / status ${step.status}${source}${dest}`);
             lines.push(`  - ${step.description}`);
         }
         lines.push("");

package/dist/cli/agent-setup.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveForeman = resolveForeman;
 exports.runAgentSetup = runAgentSetup;
 const node_child_process_1 = require("node:child_process");
 const readline = __importStar(require("node:readline"));
@@ -86,6 +87,52 @@ async function selectProvider(role, detected, currentProviders) {
         });
     });
 }
+/**
+ * Resolves the Foreman provider for init/adopt.
+ *
+ * If `execution.providerPolicy.foreman.providers[0]` is already set in config,
+ * returns a binding immediately (no prompt). Otherwise prompts once, persists
+ * the choice to polaris.config.json, and returns the binding.
+ *
+ * The binding always references `.polaris/roles/foreman.md` — role text is not
+ * duplicated here.
+ */
+async function resolveForeman(repoRoot, config, opts) {
+    const execution = config.execution ?? {};
+    const providerPolicy = execution.providerPolicy ?? {};
+    const foremanPolicy = providerPolicy.foreman ?? {};
+    const existing = foremanPolicy.providers?.[0];
+    const roleFile = ".polaris/roles/foreman.md";
+    if (existing) {
+        return { provider: existing, roleFile };
+    }
+    // Prompt once for Foreman provider
+    const detected = opts?.detectProviders?.() ?? detectProviders();
+    const chosen = opts?.selectProvider
+        ? await opts.selectProvider(detected)
+        : await selectProvider("foreman", detected, []);
+    if (!chosen) {
+        throw new Error("No supported agent installed. Cannot assign a Foreman. " +
+            "Install one of: " + SUPPORTED_PROVIDERS.map((p) => p.name).join(", "));
+    }
+    // Persist choice
+    const updatedPolicy = {
+        ...providerPolicy,
+        foreman: { ...foremanPolicy, providers: [chosen] },
+    };
+    const updatedConfig = {
+        ...config,
+        execution: { ...execution, providerPolicy: updatedPolicy },
+    };
+    const configPath = (0, node_path_1.resolve)(repoRoot, "polaris.config.json");
+    if (opts?.writeConfig) {
+        opts.writeConfig(configPath, updatedConfig);
+    }
+    else {
+        (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(updatedConfig, null, 2) + "\n");
+    }
+    return { provider: chosen, roleFile };
+}
 async function runAgentSetup(repoRoot) {
     console.log("\nPolaris Agent Setup — configure one provider per role\n");
     const detected = detectProviders();

package/dist/cli/init.js

@@ -21,9 +21,15 @@ const index_js_1 = require("../map/index.js");
 const adopt_instructions_js_1 = require("./adopt-instructions.js");
 const adopt_workspace_js_1 = require("./adopt-workspace.js");
 const adopt_assets_js_1 = require("./adopt-assets.js");
+const agent_setup_js_1 = require("./agent-setup.js");
+const runner_js_1 = require("./setup-interview/runner.js");
+const generate_js_1 = require("./setup-interview/generate.js");
+const generator_js_1 = require("../skill-packet/generator.js");
+const foreman_dispatch_js_1 = require("../loop/adapters/foreman-dispatch.js");
 const adopt_genesis_js_1 = require("./adopt-genesis.js");
 const adopt_report_js_1 = require("./adopt-report.js");
 const artifact_policy_js_1 = require("../finalize/artifact-policy.js");
+const report_js_1 = require("./setup-interview/report.js");
 var init_detect_js_2 = require("./init-detect.js");
 Object.defineProperty(exports, "detectRepoState", { enumerable: true, get: function () { return init_detect_js_2.detectRepoState; } });
 const PLAN_COMPLETE_STATUSES = new Set(["completed", "skipped"]);
@@ -377,6 +383,50 @@ async function runInit(options = {}) {
         process.stdout.write("This repo has existing content. Run `polaris init --adopt` to begin adoption.\nThis repo has existing content. Run polaris init --adopt to begin adoption.\n");
         return;
     }
+    // New/empty repo: run the setup interview and generate artifacts behind an approval gate.
+    if (!options.adopt && (repoState === "empty" || repoState === "new")) {
+        const interviewFn = options.runInterview ?? runner_js_1.runInterview;
+        let record;
+        try {
+            record = await interviewFn(repoRoot, { now: options.now });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stdout.write(`${msg}\n`);
+            return;
+        }
+        const detected = detectCompaction(repoRoot);
+        const detectedRepoAnalysis = detectRepoAnalysis(repoRoot);
+        const generateFn = options.generateSetupArtifacts ?? generate_js_1.generateSetupArtifacts;
+        await generateFn(record, {
+            repoRoot,
+            dryRun: options.dryRun,
+            yes: options.yes,
+            now: options.now,
+            detectedProviders: detected,
+            detectedRepoAnalysis,
+            scaffoldRootSurfaces: options.scaffoldRootSurfaces,
+            generatePolarisRules: options.generatePolarisRules,
+            migrateSmartDocs: options.migrateSmartDocs,
+            runMapIndex: options.runMapIndex,
+        });
+        // Post-setup validation and checkpoint report
+        if (!options.dryRun) {
+            const checkpointReport = (0, report_js_1.buildCheckpointReport)({
+                repoRoot,
+                record,
+                now: options.now,
+            });
+            (0, report_js_1.writeCheckpointReport)(repoRoot, checkpointReport);
+            (0, report_js_1.printCheckpointReport)(checkpointReport);
+            // Check for validation failures
+            const failedValidations = Object.entries(checkpointReport.validationResults).filter(([_, result]) => !result.passed);
+            if (failedValidations.length > 0) {
+                process.stdout.write(`\nWarning: ${failedValidations.length} file(s) failed validation. Check the report above for details.\n`);
+            }
+        }
+        return;
+    }
     // Load existing config (if any) so we preserve user-authored fields.
     let existing = {};
     if ((0, node_fs_1.existsSync)(configPath)) {
@@ -415,6 +465,24 @@ async function runInit(options = {}) {
         process.stdout.write(`polaris.config.json written to ${configPath}\n${providerSummary}\n`);
     }
     if (!options.adopt) {
+        // Launch Foreman with setup-bootstrap packet when execution providers are configured.
+        const initExecution = asRecord(updated.execution);
+        const initProviders = asRecord(initExecution.providers);
+        if (Object.keys(initProviders).length > 0) {
+            try {
+                const binding = await (0, agent_setup_js_1.resolveForeman)(repoRoot, updated);
+                const setupPacket = (0, generator_js_1.generateSetupBootstrapPacket)("init");
+                await (0, foreman_dispatch_js_1.dispatchForeman)({
+                    packet: setupPacket,
+                    provider: binding.provider,
+                    executionConfig: updated.execution,
+                    dryRun: options.dryRun,
+                });
+            }
+            catch {
+                // Foreman dispatch is best-effort during init — don't block setup.
+            }
+        }
         return;
     }
     const adoptionPlanPath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-plan.json");
@@ -548,7 +616,7 @@ function createInitCommand(options = {}) {
         .option("--status", "detect and print current repository state without writing files")
         .option("--adopt", "run existing repository adoption flow")
         .option("--resume", "resume an approved adoption plan without prompting")
-        .option("--yes", "auto-approve adoption plan when used with --adopt")
+        .option("--yes", "auto-approve setup or adoption plan without prompting")
         .option("--commit", "create an adoption commit when used with --adopt")
         .action(async (cmdOptions) => {
         await runInit({