@lsctech/polaris 0.3.29 → 0.4.1

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/autoresearch.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAutoresearchCommand = createAutoresearchCommand;
+const node_path_1 = require("node:path");
+const commander_1 = require("commander");
+const dev_gate_js_1 = require("../autoresearch/dev-gate.js");
+const score_js_1 = require("../autoresearch/score.js");
+const proposal_js_1 = require("../autoresearch/proposal.js");
+const routing_js_1 = require("../autoresearch/routing.js");
+function createAutoresearchCommand(options) {
+    const repoRoot = options.repoRoot;
+    const autoresearch = new commander_1.Command("autoresearch")
+        .description("Autoresearch tools (dev-gated — Polaris development context only)")
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    autoresearch
+        .command("score <run-id>")
+        .description("Score a completed Polaris run against the binary gate scorecard and output a diagnosis report")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--json", "Output raw JSON (default: pretty-printed)")
+        .action((runId, cmdOptions) => {
+        const root = (0, node_path_1.resolve)(cmdOptions.repoRoot ?? repoRoot);
+        try {
+            (0, dev_gate_js_1.assertPolarisDevContext)(root);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        try {
+            const report = (0, score_js_1.scoreRun)(root, runId);
+            const output = cmdOptions.json
+                ? JSON.stringify(report)
+                : JSON.stringify(report, null, 2);
+            process.stdout.write(`${output}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`autoresearch score error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    autoresearch
+        .command("propose <diagnosis-file>")
+        .description("File Linear improvement proposals from a diagnosis report (dev-gated — never auto-applied)")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--team <team>", "Linear team name or ID to file issues in", "Polaris")
+        .option("--dry-run", "Log what would be created without calling Linear")
+        .option("--json", "Output raw JSON (default: pretty-printed)")
+        .action(async (diagnosisFile, cmdOptions) => {
+        const root = (0, node_path_1.resolve)(cmdOptions.repoRoot ?? repoRoot);
+        try {
+            (0, dev_gate_js_1.assertPolarisDevContext)(root);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        let report;
+        try {
+            report = (0, proposal_js_1.loadDiagnosisReport)((0, node_path_1.resolve)(diagnosisFile));
+        }
+        catch (err) {
+            process.stderr.write(`autoresearch propose: invalid diagnosis file: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        const proposals = (0, proposal_js_1.buildProposals)(report);
+        if (proposals.length === 0) {
+            process.stdout.write("No failed gates with fix zone mappings — nothing to propose.\n");
+            process.exit(0);
+        }
+        const apiKey = process.env["LINEAR_API_KEY"];
+        if (!apiKey && !cmdOptions.dryRun) {
+            process.stderr.write("autoresearch propose: LINEAR_API_KEY environment variable is required.\n");
+            process.exit(1);
+        }
+        try {
+            const result = await (0, routing_js_1.routeProposals)(proposals, {
+                apiKey: apiKey ?? "",
+                teamKey: cmdOptions.team,
+                dryRun: cmdOptions.dryRun,
+            });
+            const output = cmdOptions.json
+                ? JSON.stringify(result)
+                : JSON.stringify(result, null, 2);
+            process.stdout.write(`${output}\n`);
+            if (result.total_errors > 0) {
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`autoresearch propose error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    return autoresearch;
+}

package/dist/cli/index.js

@@ -28,6 +28,7 @@ const medic_js_1 = require("./medic.js");
 const welfare_js_1 = require("../map/welfare.js");
 const adopt_command_js_1 = require("./adopt-command.js");
 const simplicity_js_1 = require("../loop/simplicity.js");
+const autoresearch_js_1 = require("./autoresearch.js");
 function resolveStateFile(repoRoot, explicit) {
     if (explicit)
         return (0, node_path_1.resolve)(explicit);
@@ -109,6 +110,7 @@ function createPolarisCommand(options = {}) {
         repoRoot,
     }));
     program.addCommand((0, adopt_command_js_1.createAdoptCommand)({ repoRoot }));
+    program.addCommand((0, autoresearch_js_1.createAutoresearchCommand)({ repoRoot }));
     program
         .command("simplicity")
         .description("View or override the simplicity discipline mode for the active run")

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