@lsctech/polaris 0.4.0 → 0.4.2

package/dist/autoresearch/dev-gate.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Dev gate: autoresearch commands are only allowed inside a Polaris development context.
+ *
+ * "Polaris dev context" = the working directory or one of its ancestors contains a
+ * `package.json` whose `name` field equals `"@lsctech/polaris"`.
+ *
+ * This is intentionally narrow: it must match the monorepo where Polaris is developed,
+ * not arbitrary consumer repos that happen to depend on it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPolarisDevContext = isPolarisDevContext;
+exports.assertPolarisDevContext = assertPolarisDevContext;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function findPackageJson(startDir) {
+    let dir = (0, node_path_1.resolve)(startDir);
+    const root = (0, node_path_1.dirname)(dir); // stop at filesystem root
+    for (let i = 0; i < 20; i++) {
+        const candidate = (0, node_path_1.join)(dir, "package.json");
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+        const parent = (0, node_path_1.dirname)(dir);
+        if (parent === dir)
+            break; // reached root
+        dir = parent;
+    }
+    return null;
+}
+function isPolarisDevContext(startDir = process.cwd()) {
+    const pkgPath = findPackageJson(startDir);
+    if (!pkgPath)
+        return false;
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, "utf-8"));
+        return pkg["name"] === "@lsctech/polaris";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Throws if not in a Polaris dev context.
+ * Call this at the start of any dev-gated command.
+ */
+function assertPolarisDevContext(startDir) {
+    if (!isPolarisDevContext(startDir)) {
+        throw new Error("polaris autoresearch score is a dev-only command and can only run inside the Polaris development repository.\n" +
+            "It is not available in consumer repos.");
+    }
+}

package/dist/autoresearch/gates.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * Binary gate evaluators for the autoresearch scoring pipeline.
+ *
+ * Gates are binary: false = PASSED (no problem detected), true = FAILED.
+ * When data is unavailable the gate is SKIPPED (not counted in score denominator).
+ *
+ * Gate contract:
+ *   evaluate(artifacts): GateResult
+ *
+ * Gate names match the v1 spec from POL-422:
+ *   user-intervened, foreman-resent-packet, foreman-fixed-worker-output,
+ *   worker-output-required-fixing, validation-failed,
+ *   worker-went-out-of-scope, foreman-token-burn-over-budget, state-repair-required
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_GATES = void 0;
+exports.gateUserIntervened = gateUserIntervened;
+exports.gateForemanResentPacket = gateForemanResentPacket;
+exports.gateForemanFixedWorkerOutput = gateForemanFixedWorkerOutput;
+exports.gateWorkerOutputRequiredFixing = gateWorkerOutputRequiredFixing;
+exports.gateValidationFailed = gateValidationFailed;
+exports.gateWorkerWentOutOfScope = gateWorkerWentOutOfScope;
+exports.gateForemanTokenBurnOverBudget = gateForemanTokenBurnOverBudget;
+exports.gateStateRepairRequired = gateStateRepairRequired;
+exports.readJsonLines = readJsonLines;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ──────────────────────────────────────────────
+// Token-burn budget constant (heuristic: 150k combined tokens = over budget)
+// ──────────────────────────────────────────────
+const TOKEN_BURN_THRESHOLD = 150_000;
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+function readJson(filePath) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readJsonLines(filePath) {
+    if (!(0, node_fs_1.existsSync)(filePath))
+        return [];
+    const lines = (0, node_fs_1.readFileSync)(filePath, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim().length > 0);
+    const out = [];
+    for (const line of lines) {
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return out;
+}
+function asRecord(v) {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+        return v;
+    }
+    return undefined;
+}
+// ──────────────────────────────────────────────
+// Gate implementations
+// ──────────────────────────────────────────────
+/**
+ * user-intervened: Were any commits pushed to the branch after polaris-finalize
+ * but before PR merge?
+ *
+ * Evidence: WorkerResultContract.user_intervened (when populated by POL-421).
+ * Falls back to checking the last result file in results/ for the flag.
+ * Skips if no result files exist.
+ */
+function gateUserIntervened(artifacts) {
+    const contract = artifacts.workerResultContracts.find((c) => c.user_intervened !== null && c.user_intervened !== undefined);
+    if (!contract)
+        return { gate: "user-intervened", outcome: "skipped", detail: "no contract with user_intervened populated" };
+    return {
+        gate: "user-intervened",
+        outcome: contract.user_intervened ? "failed" : "passed",
+        detail: contract.user_intervened ? "user_intervened=true on result contract" : undefined,
+    };
+}
+/**
+ * foreman-resent-packet: Was the packet dispatched more than once (dispatch_epoch > 1)?
+ *
+ * Evidence: dispatch_boundary.dispatch_epoch in current-state.json.
+ */
+function gateForemanResentPacket(artifacts) {
+    const state = artifacts.currentState;
+    if (!state)
+        return { gate: "foreman-resent-packet", outcome: "skipped", detail: "current-state.json not found" };
+    const dispatchEpoch = asRecord(asRecord(state)?.["dispatch_boundary"])?.["dispatch_epoch"];
+    if (typeof dispatchEpoch !== "number") {
+        return { gate: "foreman-resent-packet", outcome: "skipped", detail: "dispatch_epoch not present in state" };
+    }
+    const failed = dispatchEpoch > 1;
+    return {
+        gate: "foreman-resent-packet",
+        outcome: failed ? "failed" : "passed",
+        detail: failed ? `dispatch_epoch=${dispatchEpoch}` : undefined,
+    };
+}
+/**
+ * foreman-fixed-worker-output: Did foreman make commits between child-complete
+ * and the next dispatch?
+ *
+ * Evidence: WorkerResultContract.foreman_intervened.
+ * Skips if no contracts present.
+ */
+function gateForemanFixedWorkerOutput(artifacts) {
+    const contract = artifacts.workerResultContracts.find((c) => c.foreman_intervened !== null && c.foreman_intervened !== undefined);
+    if (!contract) {
+        return {
+            gate: "foreman-fixed-worker-output",
+            outcome: "skipped",
+            detail: "no contract with foreman_intervened populated",
+        };
+    }
+    return {
+        gate: "foreman-fixed-worker-output",
+        outcome: contract.foreman_intervened ? "failed" : "passed",
+        detail: contract.foreman_intervened ? "foreman_intervened=true on result contract" : undefined,
+    };
+}
+/**
+ * worker-output-required-fixing: Were commits pushed after polaris-finalize?
+ *
+ * Evidence: WorkerResultContract.user_intervened or foreman_intervened OR
+ * checking ledger for a "finalized" event and comparing last_commit timing.
+ * Skips when insufficient data is available.
+ */
+function gateWorkerOutputRequiredFixing(artifacts) {
+    // If either intervention flag is set, worker output required fixing
+    const anyIntervention = artifacts.workerResultContracts.some((c) => (c.user_intervened !== null && c.user_intervened === true) ||
+        (c.foreman_intervened !== null && c.foreman_intervened === true));
+    if (anyIntervention) {
+        return {
+            gate: "worker-output-required-fixing",
+            outcome: "failed",
+            detail: "user or foreman intervention detected after finalize",
+        };
+    }
+    // Check ledger for finalized event + commit after finalize
+    const finalizedEvent = artifacts.ledgerEvents.find((e) => {
+        const rec = asRecord(e);
+        return rec?.["event"] === "finalized";
+    });
+    if (!finalizedEvent) {
+        return { gate: "worker-output-required-fixing", outcome: "skipped", detail: "no finalized event in ledger" };
+    }
+    // We can't easily inspect git log here (no exec in scoring engine — that is by design).
+    // With current artifact data, mark passed when finalized and no intervention flags.
+    return { gate: "worker-output-required-fixing", outcome: "passed" };
+}
+/**
+ * validation-failed: Did any child's result packet report a validation failure?
+ *
+ * Evidence: result JSONs in clusters/<cluster-id>/results/.
+ */
+function gateValidationFailed(artifacts) {
+    if (artifacts.resultPackets.length === 0) {
+        return { gate: "validation-failed", outcome: "skipped", detail: "no result packets found" };
+    }
+    const failed = artifacts.resultPackets.some((packet) => {
+        const rec = asRecord(packet);
+        if (!rec)
+            return false;
+        // SuccessResultPacket has validation: { passed: string[] } — non-empty = passed
+        const validation = rec["validation"];
+        if (!validation)
+            return true; // no validation record → treat as failed
+        const valRec = asRecord(validation);
+        if (valRec) {
+            // { passed: string[] } form
+            if (Array.isArray(valRec["passed"]) && valRec["passed"].length > 0)
+                return false;
+        }
+        // string form: "passed" / "failed" / "skipped"
+        if (typeof validation === "string") {
+            const v = validation.toLowerCase();
+            return v === "failed" || v === "failure";
+        }
+        return false;
+    });
+    const allFailed = artifacts.resultPackets.every((packet) => {
+        const rec = asRecord(packet);
+        return rec?.["status"] === "failure";
+    });
+    if (allFailed && artifacts.resultPackets.length > 0) {
+        return { gate: "validation-failed", outcome: "failed", detail: "all result packets have status=failure" };
+    }
+    return {
+        gate: "validation-failed",
+        outcome: failed ? "failed" : "passed",
+        detail: failed ? "one or more result packets report validation failure" : undefined,
+    };
+}
+/**
+ * worker-went-out-of-scope: Did any worker result indicate out-of-scope work
+ * or emit worker-blocked events with approval_type=out-of-scope?
+ *
+ * Evidence: telemetry.jsonl worker-blocked events + result status.
+ */
+function gateWorkerWentOutOfScope(artifacts) {
+    // Check telemetry for worker-blocked with out-of-scope
+    const outOfScopeBlock = artifacts.telemetryEvents.some((e) => {
+        const rec = asRecord(e);
+        return rec?.["event"] === "worker-blocked" && rec?.["approval_type"] === "out-of-scope";
+    });
+    if (outOfScopeBlock) {
+        return {
+            gate: "worker-went-out-of-scope",
+            outcome: "failed",
+            detail: "worker-blocked with approval_type=out-of-scope in telemetry",
+        };
+    }
+    // Check result packets for "blocked" status
+    const blockedResult = artifacts.resultPackets.some((packet) => {
+        const rec = asRecord(packet);
+        return rec?.["status"] === "blocked";
+    });
+    if (blockedResult) {
+        return { gate: "worker-went-out-of-scope", outcome: "failed", detail: "result packet status=blocked" };
+    }
+    if (artifacts.telemetryEvents.length === 0 && artifacts.resultPackets.length === 0) {
+        return { gate: "worker-went-out-of-scope", outcome: "skipped", detail: "no telemetry or result packets" };
+    }
+    return { gate: "worker-went-out-of-scope", outcome: "passed" };
+}
+/**
+ * foreman-token-burn-over-budget: Did the foreman's bootstrap context exceed the budget?
+ *
+ * Evidence: bootstrap-context-size events in telemetry.jsonl.
+ * Skipped when no such events are present.
+ */
+function gateForemanTokenBurnOverBudget(artifacts) {
+    const sizeEvents = artifacts.telemetryEvents.filter((e) => {
+        const rec = asRecord(e);
+        return rec?.["event"] === "bootstrap-context-size";
+    });
+    if (sizeEvents.length === 0) {
+        return {
+            gate: "foreman-token-burn-over-budget",
+            outcome: "skipped",
+            detail: "no bootstrap-context-size events in telemetry",
+        };
+    }
+    // Use the maximum combined_estimated_tokens across all events
+    const maxTokens = Math.max(...sizeEvents.map((e) => {
+        const rec = asRecord(e);
+        const v = rec?.["combined_estimated_tokens"];
+        return typeof v === "number" ? v : 0;
+    }));
+    const failed = maxTokens > TOKEN_BURN_THRESHOLD;
+    return {
+        gate: "foreman-token-burn-over-budget",
+        outcome: failed ? "failed" : "passed",
+        detail: failed ? `max combined_estimated_tokens=${maxTokens} exceeds threshold=${TOKEN_BURN_THRESHOLD}` : undefined,
+    };
+}
+/**
+ * state-repair-required: Were medic result artifacts created for this cluster?
+ *
+ * Evidence: clusters/<cluster-id>/ directory — presence of medic result files.
+ */
+function gateStateRepairRequired(artifacts) {
+    if (!artifacts.clusterDir || !(0, node_fs_1.existsSync)(artifacts.clusterDir)) {
+        return { gate: "state-repair-required", outcome: "skipped", detail: "cluster directory not found" };
+    }
+    // Medic results have filenames like CHART-xxx.json or medic-result-*.json
+    const files = safeReaddir(artifacts.clusterDir);
+    const hasMedicResult = files.some((f) => f.startsWith("CHART-") ||
+        f.startsWith("medic-result-") ||
+        f.includes("medic") && f.endsWith(".json"));
+    // Also check results/ subdirectory for any medic artifacts
+    const resultsDir = (0, node_path_1.join)(artifacts.clusterDir, "results");
+    const resultFiles = (0, node_fs_1.existsSync)(resultsDir) ? safeReaddir(resultsDir) : [];
+    const hasMedicInResults = resultFiles.some((f) => f.startsWith("CHART-") || f.startsWith("medic-result-"));
+    if (hasMedicResult || hasMedicInResults) {
+        return {
+            gate: "state-repair-required",
+            outcome: "failed",
+            detail: "medic result artifacts detected in cluster directory",
+        };
+    }
+    return { gate: "state-repair-required", outcome: "passed" };
+}
+function safeReaddir(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        return [];
+    }
+}
+exports.ALL_GATES = [
+    gateUserIntervened,
+    gateForemanResentPacket,
+    gateForemanFixedWorkerOutput,
+    gateWorkerOutputRequiredFixing,
+    gateValidationFailed,
+    gateWorkerWentOutOfScope,
+    gateForemanTokenBurnOverBudget,
+    gateStateRepairRequired,
+];

package/dist/autoresearch/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeProposals = exports.validateDiagnosisReport = exports.loadDiagnosisReport = exports.buildProposals = exports.FIX_ZONE_MAP = exports.ALL_GATES = exports.buildDiagnosisHints = exports.computeScore = exports.loadRunArtifacts = exports.scoreRun = exports.assertPolarisDevContext = exports.isPolarisDevContext = void 0;
+var dev_gate_js_1 = require("./dev-gate.js");
+Object.defineProperty(exports, "isPolarisDevContext", { enumerable: true, get: function () { return dev_gate_js_1.isPolarisDevContext; } });
+Object.defineProperty(exports, "assertPolarisDevContext", { enumerable: true, get: function () { return dev_gate_js_1.assertPolarisDevContext; } });
+var score_js_1 = require("./score.js");
+Object.defineProperty(exports, "scoreRun", { enumerable: true, get: function () { return score_js_1.scoreRun; } });
+Object.defineProperty(exports, "loadRunArtifacts", { enumerable: true, get: function () { return score_js_1.loadRunArtifacts; } });
+Object.defineProperty(exports, "computeScore", { enumerable: true, get: function () { return score_js_1.computeScore; } });
+Object.defineProperty(exports, "buildDiagnosisHints", { enumerable: true, get: function () { return score_js_1.buildDiagnosisHints; } });
+var gates_js_1 = require("./gates.js");
+Object.defineProperty(exports, "ALL_GATES", { enumerable: true, get: function () { return gates_js_1.ALL_GATES; } });
+var proposal_js_1 = require("./proposal.js");
+Object.defineProperty(exports, "FIX_ZONE_MAP", { enumerable: true, get: function () { return proposal_js_1.FIX_ZONE_MAP; } });
+Object.defineProperty(exports, "buildProposals", { enumerable: true, get: function () { return proposal_js_1.buildProposals; } });
+Object.defineProperty(exports, "loadDiagnosisReport", { enumerable: true, get: function () { return proposal_js_1.loadDiagnosisReport; } });
+Object.defineProperty(exports, "validateDiagnosisReport", { enumerable: true, get: function () { return proposal_js_1.validateDiagnosisReport; } });
+var routing_js_1 = require("./routing.js");
+Object.defineProperty(exports, "routeProposals", { enumerable: true, get: function () { return routing_js_1.routeProposals; } });

package/dist/autoresearch/proposal.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Autoresearch proposal schema and fix zone mapping.
+ *
+ * AutresearchProposal is the canonical output of the propose command.
+ * It maps failed binary gates to Polaris artifact fix zones and records
+ * the metadata needed for Linear issue creation.
+ *
+ * Non-goal: proposals are never auto-applied. They are filed for human review.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIX_ZONE_MAP = void 0;
+exports.buildProposals = buildProposals;
+exports.loadDiagnosisReport = loadDiagnosisReport;
+exports.validateDiagnosisReport = validateDiagnosisReport;
+const node_fs_1 = require("node:fs");
+// ──────────────────────────────────────────────
+// Fix zone mapping table: gate → artifact type + hint
+// ──────────────────────────────────────────────
+exports.FIX_ZONE_MAP = {
+    "user-intervened": {
+        artifact_type: "worker-template",
+        hint: "User pushed commits after polaris-finalize. Tighten worker packet scope and instructions to reduce ambiguity.",
+    },
+    "foreman-resent-packet": {
+        artifact_type: "foreman-template",
+        hint: "Foreman dispatched the same child more than once. Review dispatch-boundary logic in foreman templates.",
+    },
+    "foreman-fixed-worker-output": {
+        artifact_type: "worker-template",
+        hint: "Foreman made corrective commits after child-complete. Strengthen allowed_scope and acceptance criteria in the worker template.",
+    },
+    "worker-output-required-fixing": {
+        artifact_type: "worker-template",
+        hint: "Post-finalize commits indicate insufficient worker output. Add stricter validation commands to the worker template.",
+    },
+    "validation-failed": {
+        artifact_type: "scoring-rule",
+        hint: "One or more children failed validation. Review validation_commands in the worker packet and the scoring rule thresholds.",
+    },
+    "worker-went-out-of-scope": {
+        artifact_type: "worker-template",
+        hint: "Worker emitted out-of-scope blocks or returned blocked status. Narrow allowed_scope in the worker template.",
+    },
+    "foreman-token-burn-over-budget": {
+        artifact_type: "foreman-template",
+        hint: "Foreman bootstrap context exceeds token budget. Reduce packet size in foreman template or raise budget threshold.",
+    },
+    "state-repair-required": {
+        artifact_type: "medic-template",
+        hint: "Medic artifacts detected — state repair was required. Review medic template heuristics and state-repair triggers.",
+    },
+};
+// ──────────────────────────────────────────────
+// Build proposals from a DiagnosisReport
+// ──────────────────────────────────────────────
+/**
+ * Maps a DiagnosisReport's failed gates to AutresearchProposal objects.
+ * Gates without a fix zone entry are skipped.
+ */
+function buildProposals(report) {
+    const proposals = [];
+    for (const gateId of report.failed_gates) {
+        const entry = exports.FIX_ZONE_MAP[gateId];
+        if (!entry)
+            continue; // no mapping → skip
+        proposals.push({
+            gate_id: gateId,
+            artifact_type: entry.artifact_type,
+            hint: entry.hint,
+            run_id: report.run_id,
+            evidence_run_ids: [report.run_id],
+            confidence: report.score,
+            fix_zone: `${entry.artifact_type}/${gateId}`,
+        });
+    }
+    return proposals;
+}
+// ──────────────────────────────────────────────
+// Diagnosis file loader + schema validator
+// ──────────────────────────────────────────────
+/**
+ * Loads and validates a diagnosis file produced by `polaris autoresearch score`.
+ * Throws if the file is missing, unparseable, or does not match DiagnosisReport shape.
+ */
+function loadDiagnosisReport(filePath) {
+    if (!(0, node_fs_1.existsSync)(filePath)) {
+        throw new Error(`Diagnosis file not found: ${filePath}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse diagnosis file: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return validateDiagnosisReport(raw);
+}
+/**
+ * Validates a parsed value against the DiagnosisReport schema.
+ * Throws a descriptive error if required fields are missing or have wrong types.
+ */
+function validateDiagnosisReport(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("Diagnosis file must be a JSON object.");
+    }
+    const r = raw;
+    if (typeof r["run_id"] !== "string")
+        throw new Error("Diagnosis report missing required string field: run_id");
+    if (typeof r["evaluated_at"] !== "string")
+        throw new Error("Diagnosis report missing required string field: evaluated_at");
+    if (!Array.isArray(r["gate_results"]))
+        throw new Error("Diagnosis report missing required array field: gate_results");
+    if (!Array.isArray(r["failed_gates"]))
+        throw new Error("Diagnosis report missing required array field: failed_gates");
+    if (typeof r["score"] !== "number")
+        throw new Error("Diagnosis report missing required number field: score");
+    if (!Array.isArray(r["diagnosis_hints"]))
+        throw new Error("Diagnosis report missing required array field: diagnosis_hints");
+    return raw;
+}

package/dist/autoresearch/routing.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Autoresearch proposal routing.
+ *
+ * Routes AutresearchProposal objects to the Polaris development tracker (Linear)
+ * as new issues. Proposals are NEVER auto-applied — they are filed for human review.
+ *
+ * Each filed issue includes:
+ *   - gate IDs, fix zone, evidence run IDs, artifact type, confidence
+ *   - autoresearch-proposal label (when label ID is resolvable)
+ *
+ * This module is dev-gated: it must only run inside the Polaris dev context.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeProposals = routeProposals;
+const node_https_1 = require("node:https");
+async function linearGraphql(apiKey, query, variables) {
+    const payload = JSON.stringify({ query, variables });
+    const raw = await new Promise((resolve, reject) => {
+        const req = (0, node_https_1.request)({
+            hostname: "api.linear.app",
+            path: "/graphql",
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: apiKey,
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                const body = Buffer.concat(chunks).toString("utf-8");
+                if ((res.statusCode ?? 0) >= 400) {
+                    reject(new Error(`Linear API ${res.statusCode}: ${body}`));
+                    return;
+                }
+                resolve(body);
+            });
+        });
+        req.on("error", reject);
+        req.write(payload);
+        req.end();
+    });
+    const parsed = JSON.parse(raw);
+    if (parsed.errors && parsed.errors.length > 0) {
+        throw new Error(`Linear GraphQL errors: ${JSON.stringify(parsed.errors)}`);
+    }
+    if (!parsed.data)
+        throw new Error("Linear API returned no data.");
+    return parsed.data;
+}
+async function resolveTeamId(apiKey, teamKey) {
+    // teamKey may be a UUID or a display name
+    const data = await linearGraphql(apiKey, "query AutresearchTeams { teams(first: 250) { nodes { id name } } }", {});
+    const match = data.teams.nodes.find((t) => t.id === teamKey || t.name === teamKey || t.name.toLowerCase() === teamKey.toLowerCase());
+    if (!match)
+        throw new Error(`Linear team not found: '${teamKey}'. Available: ${data.teams.nodes.map((t) => t.name).join(", ")}`);
+    return match.id;
+}
+async function resolveAutoresearchLabelId(apiKey, teamId) {
+    try {
+        const data = await linearGraphql(apiKey, `query AutresearchLabel($teamId: String!) {
+        issueLabels(filter: { team: { id: { eq: $teamId } }, name: { containsIgnoreCase: "autoresearch-proposal" } }, first: 10) {
+          nodes { id name }
+        }
+      }`, { teamId });
+        return data.issueLabels.nodes[0]?.id;
+    }
+    catch {
+        // Label lookup is best-effort — don't fail the whole route if it fails
+        return undefined;
+    }
+}
+// ──────────────────────────────────────────────
+// Issue body builder
+// ──────────────────────────────────────────────
+function buildIssueBody(proposal) {
+    return [
+        `## Autoresearch Proposal`,
+        ``,
+        `> This issue was filed automatically by \`polaris autoresearch propose\`. **Do not auto-apply.** Human review is required.`,
+        ``,
+        `| Field | Value |`,
+        `|---|---|`,
+        `| Gate ID | \`${proposal.gate_id}\` |`,
+        `| Artifact type | \`${proposal.artifact_type}\` |`,
+        `| Fix zone | \`${proposal.fix_zone}\` |`,
+        `| Confidence | ${(proposal.confidence * 100).toFixed(1)}% |`,
+        `| Run ID | \`${proposal.run_id}\` |`,
+        `| Evidence run IDs | ${proposal.evidence_run_ids.map((id) => `\`${id}\``).join(", ")} |`,
+        ``,
+        `## Hint`,
+        ``,
+        proposal.hint,
+        ``,
+        `## Review checklist`,
+        ``,
+        `- [ ] Confirm the gate failure is reproducible`,
+        `- [ ] Identify the specific artifact to change`,
+        `- [ ] Draft the proposed change`,
+        `- [ ] Test against a real run`,
+        `- [ ] Approve and merge`,
+    ].join("\n");
+}
+/**
+ * Routes proposals to Linear as new issues for human review.
+ * Never auto-applies proposals.
+ */
+async function routeProposals(proposals, options) {
+    const { apiKey, teamKey, dryRun = false } = options;
+    const runId = proposals[0]?.run_id ?? "unknown";
+    const teamId = await resolveTeamId(apiKey, teamKey);
+    const labelId = dryRun ? undefined : await resolveAutoresearchLabelId(apiKey, teamId);
+    const filed = [];
+    for (const proposal of proposals) {
+        const title = `[autoresearch-proposal] ${proposal.artifact_type}: ${proposal.gate_id}`;
+        const body = buildIssueBody(proposal);
+        if (dryRun) {
+            filed.push({
+                proposal_gate_id: proposal.gate_id,
+                created: false,
+                issue_id: "(dry-run)",
+                issue_identifier: "(dry-run)",
+                issue_url: undefined,
+            });
+            continue;
+        }
+        try {
+            const data = await linearGraphql(apiKey, `mutation AutresearchPropose($teamId: String!, $title: String!, $body: String!, $labelIds: [String!]) {
+          issueCreate(input: {
+            teamId: $teamId
+            title: $title
+            description: $body
+            labelIds: $labelIds
+          }) {
+            success
+            issue { id identifier url }
+          }
+        }`, {
+                teamId,
+                title,
+                body,
+                labelIds: labelId ? [labelId] : [],
+            });
+            if (data.issueCreate.success && data.issueCreate.issue) {
+                filed.push({
+                    proposal_gate_id: proposal.gate_id,
+                    created: true,
+                    issue_id: data.issueCreate.issue.id,
+                    issue_identifier: data.issueCreate.issue.identifier,
+                    issue_url: data.issueCreate.issue.url,
+                });
+            }
+            else {
+                filed.push({
+                    proposal_gate_id: proposal.gate_id,
+                    created: false,
+                    error: "issueCreate returned success=false",
+                });
+            }
+        }
+        catch (err) {
+            filed.push({
+                proposal_gate_id: proposal.gate_id,
+                created: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const totalCreated = filed.filter((r) => r.created).length;
+    const totalErrors = filed.filter((r) => !r.created && r.error).length;
+    return {
+        run_id: runId,
+        team_id: teamId,
+        filed,
+        total_proposals: proposals.length,
+        total_created: totalCreated,
+        total_errors: totalErrors,
+    };
+}