@lsctech/polaris 0.5.8 → 0.5.10

package/dist/autoresearch/sol-run-health-bridge.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * SOL → run-health bridge.
+ *
+ * Evaluates SOL score reports against operator-configured thresholds and,
+ * when policy enables it, appends run-health symptoms so that Medic can be
+ * engaged even when no worker explicitly wrote symptoms.
+ *
+ * Design rules:
+ *   - SOL is ADVISORY by default. No symptoms are created unless the operator
+ *     sets `sol.thresholds.enabled = true` AND at least one policy flag
+ *     (`createRunHealthReport` or `requireMedic`) is true.
+ *   - Symptoms reference the SOL evidence file as their source; they do NOT
+ *     mutate raw metric artifacts.
+ *   - Each threshold crossing produces exactly one symptom per evaluation.
+ *     Re-evaluating the same run does not duplicate symptoms because the
+ *     symptom id encodes the threshold name.
+ *   - Never throws — threshold evaluation must not block the run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSolThresholdCrossings = detectSolThresholdCrossings;
+exports.evaluateSolThresholds = evaluateSolThresholds;
+const index_js_1 = require("../run-health/index.js");
+// ── Defaults ─────────────────────────────────────────────────────────────────
+const DEFAULT_LOW_COMPOSITE_SCORE = 0.4;
+const DEFAULT_QC_REPAIR_LOOP_FAILURE_STATUSES = [
+    "max-rounds",
+    "medic-referral",
+    "all-providers-failed",
+];
+const DEFAULT_REPEATED_PROVIDER_FAILURES = 3;
+const DEFAULT_FOREMAN_INTERVENTION_COUNT = 2;
+const DEFAULT_STALE_WRONG_RUN_TELEMETRY = true;
+const DEFAULT_VALIDATION_FAILURES = 2;
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function makeSolSourceActor() {
+    return { role: "sol" };
+}
+function makeSolSymptom(crossing) {
+    return {
+        // Deterministic id: code only (no UUID) so repeated evaluations of the
+        // same run are idempotent — the same threshold crossing produces the
+        // same id, and a caller that deduplicates by id will skip the duplicate.
+        // ponytail: when run-health supports upsert-by-id, switch to that.
+        id: `sol:${crossing.code}`,
+        severity: solThresholdSeverity(crossing.code),
+        code: crossing.code,
+        message: crossing.message,
+        source_actor: makeSolSourceActor(),
+        evidence_refs: crossing.evidenceRefs,
+        occurred_at: new Date().toISOString(),
+    };
+}
+function solThresholdSeverity(code) {
+    switch (code) {
+        case "sol-qc-repair-loop-failure":
+        case "sol-repeated-provider-failures":
+            return "high";
+        case "sol-low-composite-score":
+        case "sol-high-foreman-intervention":
+        case "sol-validation-failures":
+            return "medium";
+        case "sol-stale-wrong-run-telemetry":
+            return "high";
+        default:
+            return "medium";
+    }
+}
+function upsertSolSymptom(runId, clusterId, symptom, repoRoot) {
+    const existing = (0, index_js_1.readRunHealthReport)(runId, repoRoot);
+    if (!existing) {
+        (0, index_js_1.createRunHealthReport)({
+            runId,
+            clusterId,
+            firstSymptom: symptom,
+            sourceActor: makeSolSourceActor(),
+            repoRoot,
+        });
+    }
+    else {
+        // Deduplicate: skip if a symptom with the same id already exists
+        if (existing.symptoms.some((s) => s.id === symptom.id)) {
+            return;
+        }
+        (0, index_js_1.appendSymptom)(runId, symptom, repoRoot);
+    }
+}
+// ── Threshold evaluation ──────────────────────────────────────────────────────
+/**
+ * Detect which thresholds are crossed given the SOL score report.
+ * Returns an array of crossing descriptors without any I/O side effects.
+ */
+function detectSolThresholdCrossings(scoreReport, thresholdsConfig, evidencePaths) {
+    const crossings = [];
+    const lowCompositeThreshold = thresholdsConfig.low_composite_score ?? DEFAULT_LOW_COMPOSITE_SCORE;
+    const qcFailureStatuses = thresholdsConfig.qc_repair_loop_failure_statuses ?? DEFAULT_QC_REPAIR_LOOP_FAILURE_STATUSES;
+    const providerFailureThreshold = thresholdsConfig.repeated_provider_failures ?? DEFAULT_REPEATED_PROVIDER_FAILURES;
+    const interventionThreshold = thresholdsConfig.foreman_intervention_count ?? DEFAULT_FOREMAN_INTERVENTION_COUNT;
+    const checkStaleWrongRun = thresholdsConfig.stale_wrong_run_telemetry ?? DEFAULT_STALE_WRONG_RUN_TELEMETRY;
+    const validationFailureThreshold = thresholdsConfig.validation_failures ?? DEFAULT_VALIDATION_FAILURES;
+    // 1. Low composite score
+    if (scoreReport.run_composite_score !== null &&
+        scoreReport.run_composite_score < lowCompositeThreshold) {
+        crossings.push({
+            code: "sol-low-composite-score",
+            message: `SOL run composite score ${scoreReport.run_composite_score.toFixed(4)} is below ` +
+                `configured threshold ${lowCompositeThreshold} — run health may be degraded.`,
+            evidenceRefs: evidencePaths,
+        });
+    }
+    // 2. QC repair-loop failure state
+    const foremanReport = scoreReport.foreman;
+    const qcRepairLoopDetail = foremanReport.qc_repair_loop?.detail ?? "";
+    for (const status of qcFailureStatuses) {
+        if (qcRepairLoopDetail.includes(`status=${status}`)) {
+            crossings.push({
+                code: "sol-qc-repair-loop-failure",
+                message: `SOL evidence shows QC repair loop reached failure status "${status}" — ` +
+                    `Medic consultation is recommended.`,
+                evidenceRefs: evidencePaths,
+            });
+            break; // One symptom per run for QC repair-loop failures
+        }
+    }
+    // Also detect via qc_repair_loop score == 0
+    if (foremanReport.qc_repair_loop?.score !== null &&
+        foremanReport.qc_repair_loop?.score === 0 &&
+        crossings.every((c) => c.code !== "sol-qc-repair-loop-failure")) {
+        crossings.push({
+            code: "sol-qc-repair-loop-failure",
+            message: `SOL evidence shows QC repair loop score 0.0 (worst outcome) — ` +
+                `Medic consultation is recommended.`,
+            evidenceRefs: evidencePaths,
+        });
+    }
+    // 3. Repeated provider failures — inferred from worker composite scores ≤ 0
+    //    and workers_failed count (available through foreman scores proxy).
+    const failedWorkers = Object.values(scoreReport.workers).filter((w) => w.composite_score !== null && w.composite_score <= 0);
+    if (failedWorkers.length >= providerFailureThreshold) {
+        crossings.push({
+            code: "sol-repeated-provider-failures",
+            message: `SOL evidence shows ${failedWorkers.length} worker(s) with zero composite score ` +
+                `(threshold: ${providerFailureThreshold}) — possible repeated provider failures.`,
+            evidenceRefs: evidencePaths,
+        });
+    }
+    // 4. High Foreman intervention count
+    // intervention.score: 0.0 = user_intervened, 0.5 = foreman_intervened
+    const interventionScore = foremanReport.intervention?.score;
+    if (interventionScore !== null && interventionScore !== undefined) {
+        // pre_analysis dimension uses escalation_events as a proxy
+        // intervention score < 0.5 means foreman_intervened; 0.0 means user_intervened
+        // We use the foreman.pre_analysis detail to extract escalation_events
+        const preAnalysisDetail = foremanReport.pre_analysis?.detail ?? "";
+        const escalationMatch = /escalation_events=(\d+)/.exec(preAnalysisDetail);
+        const escalationEvents = escalationMatch ? parseInt(escalationMatch[1], 10) : 0;
+        if (escalationEvents > interventionThreshold) {
+            crossings.push({
+                code: "sol-high-foreman-intervention",
+                message: `SOL evidence shows ${escalationEvents} escalation event(s) ` +
+                    `(threshold: ${interventionThreshold}) — possible Foreman intervention loop.`,
+                evidenceRefs: evidencePaths,
+            });
+        }
+    }
+    // 5. Stale / wrong-run telemetry
+    // Detected via foreman.dispatch and foreman.duration dimension details
+    if (checkStaleWrongRun) {
+        const dispatchDetail = foremanReport.dispatch?.detail ?? "";
+        const durationDetail = foremanReport.duration?.detail ?? "";
+        const hasRedispatch = /redispatched=\d+\//.exec(dispatchDetail);
+        const redispatchCount = hasRedispatch
+            ? parseInt(/redispatched=(\d+)/.exec(dispatchDetail)?.[1] ?? "0", 10)
+            : 0;
+        // dispatch_epoch >> continue_epoch suggests wrong-run telemetry
+        const dispatchEpochMatch = /dispatch_epoch=(\d+)/.exec(durationDetail);
+        const continueEpochMatch = /continue_epoch=(\d+)/.exec(durationDetail);
+        const dispatchEpoch = dispatchEpochMatch ? parseInt(dispatchEpochMatch[1], 10) : 0;
+        const continueEpoch = continueEpochMatch ? parseInt(continueEpochMatch[1], 10) : 0;
+        const epochOverhead = dispatchEpoch > 0 ? dispatchEpoch - (continueEpoch + 1) : 0;
+        if (redispatchCount >= providerFailureThreshold || epochOverhead >= 3) {
+            crossings.push({
+                code: "sol-stale-wrong-run-telemetry",
+                message: `SOL evidence suggests stale or wrong-run telemetry: ` +
+                    `redispatched=${redispatchCount}, epoch_overhead=${epochOverhead}. ` +
+                    `This pattern is consistent with the POL-509 wrong-run failure mode.`,
+                evidenceRefs: evidencePaths,
+            });
+        }
+    }
+    // 6. Validation failures
+    const validationFailedWorkers = Object.values(scoreReport.workers).filter((w) => w.validation?.score !== null && w.validation?.score === 0);
+    if (validationFailedWorkers.length >= validationFailureThreshold) {
+        crossings.push({
+            code: "sol-validation-failures",
+            message: `SOL evidence shows ${validationFailedWorkers.length} worker(s) with validation failures ` +
+                `(threshold: ${validationFailureThreshold}).`,
+            evidenceRefs: evidencePaths,
+        });
+    }
+    return crossings;
+}
+/**
+ * Evaluate SOL score thresholds and, when policy enables it, append
+ * run-health symptoms for each crossing.
+ *
+ * Advisory only by default. To activate run-health writes:
+ *   `sol.thresholds.enabled = true` AND one of:
+ *   `sol.thresholds.policy.createRunHealthReport = true`
+ *   `sol.thresholds.policy.requireMedic = true`
+ *
+ * Never throws — threshold evaluation must not block the run.
+ */
+function evaluateSolThresholds(params) {
+    const { runId, clusterId, scoreReport, evidencePaths = [], thresholdsConfig, repoRoot } = params;
+    const crossings = detectSolThresholdCrossings(scoreReport, thresholdsConfig, evidencePaths);
+    const policyEnabled = thresholdsConfig.enabled === true;
+    const createReport = thresholdsConfig.policy?.createRunHealthReport === true;
+    const requireMedic = thresholdsConfig.policy?.requireMedic === true;
+    const shouldWrite = policyEnabled && (createReport || requireMedic);
+    if (!shouldWrite || crossings.length === 0) {
+        return { crossings, symptomsAppended: 0, medicRequired: false };
+    }
+    let symptomsAppended = 0;
+    let medicDecisionWritten = false;
+    try {
+        for (const crossing of crossings) {
+            upsertSolSymptom(runId, clusterId, makeSolSymptom(crossing), repoRoot);
+            symptomsAppended++;
+        }
+        // If requireMedic is true, set medic_consult to pending so finalize gate fires.
+        if (requireMedic && crossings.length > 0) {
+            (0, index_js_1.markMedicDecision)(runId, { status: "pending" }, repoRoot);
+            medicDecisionWritten = true;
+        }
+    }
+    catch {
+        // Threshold evaluation must never block the run.
+        // ponytail: surface write errors to telemetry in a future pass
+    }
+    return {
+        crossings,
+        symptomsAppended,
+        medicRequired: medicDecisionWritten,
+    };
+}

package/dist/cli/adopt-canon.js

@@ -148,7 +148,7 @@ function dispatchCanonAgent(options) {
         .slice(0, 30)
         .map((d, i) => `${i + 1}. [${d.title}] path: ${d.path}`)
         .join("\n");
-    const prompt = `You are a Polaris librarian generating context files for an agent work area.
+    const prompt = `You are a Polaris librarian generating route cognition for an agent work area.
 
 Route folder: ${routeFolder}
 Repo root: ${repoRoot}
@@ -156,16 +156,27 @@ Repo root: ${repoRoot}
 Available doctrine documents:
 ${docList}
 
-Generate two outputs for this route area:
+Generate two outputs for this route area.
 
-1. SUMMARY.md content — a navigation index. Select relevant doctrine docs and write 2-4 lines describing what this area covers.
+1. SUMMARY.md content (current-state memory / navigation index):
+   - Include: 2-4 lines describing what this area covers, its current canonical status, and which doctrine docs are relevant.
+   - Avoid: operational procedures, step-by-step agent instructions, duplicated doctrine text, or per-run diary content.
 
-2. POLARIS.md content — operational instructions for agents entering this work area. Write 4-8 lines covering: what this area is responsible for, key patterns/conventions agents should follow, what to avoid, and which doctrine docs to consult for specific concerns. Be concise and directive — agents read this cold before starting work.
+2. POLARIS.md content (route operating guidance):
+   REQUIRED sections that must be present in polaris_lines:
+   - Purpose/boundaries: what this area is responsible for and what it excludes
+   - Invariants/safety rules: constraints and what to avoid
+   - Commands/workflows: key patterns/conventions agents must follow
+   - Canonical links: which doctrine docs to consult for specific concerns
+   - Read-before-edit references: upstream/downstream dependencies
+
+   Avoid: navigation-index content, summary-style history, per-run notes, or duplicating doctrine text instead of linking to it.
 
 Respond with ONLY valid JSON on a single line:
 {"relevant_docs":[{"path":"<doc path>","title":"<doc title>"}],"summary_lines":["line1","line2"],"polaris_lines":["line1","line2"]}
 
-If no doctrine docs are relevant, return an empty array for relevant_docs.`;
+If no doctrine docs are relevant, return an empty array for relevant_docs.
+The polaris_lines array must contain all required POLARIS contract sections or be empty if the agent cannot generate valid content.`;
     // Same dispatch pattern as dispatchLibrarianReview — pass args straight through,
     // letting the provider config (e.g. env CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=0) handle auth.
     const args = (cfg.args ?? []).map((a) => (a === "{{worker_prompt}}" ? prompt : a));

package/dist/cli/adopt-cognition.js

@@ -119,7 +119,7 @@ function buildPolarisDraft(folder) {
         "<!-- polaris:draft -->",
         `# ${folderName}`,
         "",
-        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "> Polaris draft — route operating guidance. Remove the `<!-- polaris:draft -->` marker to promote.",
         "",
         "## Purpose",
         "",
@@ -129,13 +129,15 @@ function buildPolarisDraft(folder) {
         `**Route:** ${folder}`,
         "**Taskchain:** unknown",
         "",
-        "## What belongs here",
+        "## Responsibilities",
         "",
-        "<!-- Describe the assets and responsibilities expected in this folder. -->",
+        "<!-- What agents entering this route must know, do, and check. -->",
         "",
-        "## What does not belong here",
+        "## Constraints and exclusions",
         "",
-        "<!-- Describe content that should be routed elsewhere. -->",
+        "- Do NOT duplicate doctrine from `smartdocs/doctrine/active/`; link to it instead.",
+        "- Do NOT use this file as a run diary; per-run notes belong in the run artifact, not here or in SUMMARY.md.",
+        "- Keep guidance operational and directive — this is not a history or index.",
         "",
     ].join("\n");
 }
@@ -145,15 +147,28 @@ function buildSummaryDraft(folder) {
         "<!-- polaris:draft -->",
         `# Summary — ${folderName}`,
         "",
-        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "> Polaris draft — current-state memory for this route. Remove the `<!-- polaris:draft -->` marker to promote.",
         "",
         `- Route: \`${folder}\``,
         "- Canon status: draft",
         "- Linked doctrine: `POLARIS.md`",
         "",
-        "## Notes",
+        "## Current state",
         "",
-        "<!-- Add concise context, references, and ownership details for this folder. -->",
+        "<!-- Synthesized current-state context: what's here, ownership, and domain. -->",
+        "",
+        "## Synthesized recent changes",
+        "",
+        "<!-- High-level summary of significant changes, not a per-run diary. Run-specific notes belong in run artifacts. -->",
+        "",
+        "## Caveats and drift",
+        "",
+        "<!-- Known gaps, stale areas, or planned changes that affect navigation. -->",
+        "",
+        "## Canonical sources",
+        "",
+        "- [POLARIS.md](POLARIS.md) — operational guidance for this route",
+        "<!-- Link to relevant doctrine from `smartdocs/doctrine/active/` -->",
         "",
     ].join("\n");
 }

package/dist/cli/medic.js

@@ -5,6 +5,10 @@ const commander_1 = require("commander");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const chart_id_js_1 = require("../medic/chart-id.js");
+const loader_js_1 = require("../config/loader.js");
+const terminal_cli_js_1 = require("../loop/adapters/terminal-cli.js");
+const run_health_consult_js_1 = require("../medic/run-health-consult.js");
+const treatment_packets_js_1 = require("../medic/treatment-packets.js");
 function createMedicCommand(options = {}) {
     const repoRootDefault = options.repoRoot ?? (0, node_path_1.resolve)(process.cwd());
     const medic = new commander_1.Command("medic")
@@ -34,6 +38,67 @@ function createMedicCommand(options = {}) {
             process.exit(1);
         }
     }));
+    medic
+        .command("run-health-consult")
+        .description("Run a Medic run-health consult from a packet file")
+        .requiredOption("--packet-file <path>", "Path to MedicRunHealthPacket JSON")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .action(async (cmdOptions) => {
+        const repoRoot = cmdOptions.repoRoot;
+        let packet;
+        try {
+            packet = JSON.parse((0, node_fs_1.readFileSync)(cmdOptions.packetFile, "utf-8"));
+        }
+        catch (err) {
+            process.stderr.write(`medic run-health-consult error: cannot read packet: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+            return;
+        }
+        if (packet.role !== "medic-run-health") {
+            process.stderr.write(`medic run-health-consult error: packet role must be \"medic-run-health\", got \"${packet.role}\"\n`);
+            process.exit(1);
+            return;
+        }
+        const config = (0, loader_js_1.loadConfig)(repoRoot);
+        const adapter = new terminal_cli_js_1.TerminalCliAdapter(config.execution);
+        // Use shared provider resolution logic: prefer rotation, fall back to first provider
+        const providerName = (config.execution.rotation && config.execution.rotation.length > 0)
+            ? config.execution.rotation[0]
+            : Object.keys(config.execution.providers ?? {})[0] ?? "terminal-cli";
+        // Get current branch from git
+        let branch = "main";
+        try {
+            const { execFileSync } = require("node:child_process");
+            branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+                cwd: repoRoot,
+                encoding: "utf-8",
+            }).trim();
+        }
+        catch {
+            // Fall back to main if git fails
+        }
+        try {
+            const result = await (0, run_health_consult_js_1.runMedicRunHealthConsult)({
+                packet,
+                repoRoot,
+                stateFile: packet.cluster_state_path,
+                telemetryFile: packet.telemetry_path,
+                branch,
+                dryRun: false,
+                dispatchTreatmentWorkerFn: (input) => (0, treatment_packets_js_1.dispatchTreatmentWorker)({
+                    ...input,
+                    repoRoot,
+                    dispatch: (workerPacket) => adapter.dispatch(workerPacket, { provider: providerName }),
+                }),
+            });
+            (0, node_fs_1.writeFileSync)(packet.result_path, JSON.stringify(result, null, 2), "utf-8");
+            process.stdout.write(`Medic run-health consult result written to ${packet.result_path}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`medic run-health-consult error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
     return medic;
 }
 function createChart(options) {

package/dist/cognition/closeout-librarian-types.js

@@ -118,6 +118,59 @@ function validateCloseoutLibrarianResult(value) {
     if (!Array.isArray(r["summary_md_updates"])) {
         errors.push("summary_md_updates must be an array");
     }
+    if (r["artifact_reconciliation"] !== undefined &&
+        !Array.isArray(r["artifact_reconciliation"])) {
+        errors.push("artifact_reconciliation must be an array when provided");
+    }
+    if (Array.isArray(r["artifact_reconciliation"])) {
+        const allowed = new Set([
+            "polaris-only",
+            "summary-only",
+            "both",
+            "no-change",
+        ]);
+        for (const [index, update] of r["artifact_reconciliation"].entries()) {
+            if (typeof update !== "object" || update === null) {
+                errors.push(`artifact_reconciliation[${index}] must be an object`);
+                continue;
+            }
+            const entry = update;
+            if (typeof entry["folder"] !== "string" || !entry["folder"]) {
+                errors.push(`artifact_reconciliation[${index}].folder must be a non-empty string`);
+            }
+            const decision = entry["decision"];
+            if (typeof entry["decision"] !== "string" ||
+                !allowed.has(decision)) {
+                errors.push(`artifact_reconciliation[${index}].decision must be one of: polaris-only, summary-only, both, no-change`);
+            }
+            if (typeof entry["polaris_md"] !== "string" || !entry["polaris_md"]) {
+                errors.push(`artifact_reconciliation[${index}].polaris_md must be a non-empty string`);
+            }
+            // Validate summary_md based on decision: required for summary-only and both, null for polaris-only and no-change
+            if (decision === "summary-only" || decision === "both") {
+                if (typeof entry["summary_md"] !== "string" || !entry["summary_md"]) {
+                    errors.push(`artifact_reconciliation[${index}].summary_md must be a non-empty string for decision "${decision}"`);
+                }
+            }
+            else if (decision === "polaris-only" || decision === "no-change") {
+                if (entry["summary_md"] !== null && (typeof entry["summary_md"] !== "string" || !entry["summary_md"])) {
+                    errors.push(`artifact_reconciliation[${index}].summary_md must be a non-empty string or null for decision "${decision}"`);
+                }
+            }
+            else {
+                // Fallback for any decision type: reject empty strings
+                if (entry["summary_md"] !== null && typeof entry["summary_md"] !== "string") {
+                    errors.push(`artifact_reconciliation[${index}].summary_md must be a string or null`);
+                }
+                if (typeof entry["summary_md"] === "string" && !entry["summary_md"]) {
+                    errors.push(`artifact_reconciliation[${index}].summary_md must not be an empty string when provided`);
+                }
+            }
+            if (typeof entry["reason"] !== "string" || !entry["reason"]) {
+                errors.push(`artifact_reconciliation[${index}].reason must be a non-empty string`);
+            }
+        }
+    }
     if (!Array.isArray(r["docs_ingested"])) {
         errors.push("docs_ingested must be an array");
     }

package/dist/cognition/librarian-packet.js

@@ -76,6 +76,24 @@ function generateLibrarianPacket(options) {
             cognition_index: node_fs_1.default.existsSync(cognitionIndexAbs)
                 ? node_path_1.default.relative(repoRoot, cognitionIndexAbs)
                 : null,
+            artifact_contract: {
+                polaris_md: {
+                    path: node_path_1.default.join(folder, "POLARIS.md"),
+                    intent: "must-reconcile",
+                    reason: "Affected folders must reconcile POLARIS.md to keep operational doctrine current.",
+                },
+                summary_md: node_fs_1.default.existsSync(summaryAbs)
+                    ? {
+                        path: node_path_1.default.join(folder, "SUMMARY.md"),
+                        intent: "reconcile-if-present",
+                        reason: "SUMMARY.md exists for this folder and may be reconciled independently when informational canon changed.",
+                    }
+                    : {
+                        path: null,
+                        intent: "not-present",
+                        reason: "SUMMARY.md is missing for this folder; skip SUMMARY reconciliation and evaluate POLARIS.md independently.",
+                    },
+            },
         };
     });
     const cognitionNotes = findPendingCognitionNotes(repoRoot, state.completed_children);
@@ -103,10 +121,16 @@ function generateLibrarianPacket(options) {
         node_path_1.default.join(repoRoot, "scripts"),
     ];
     // Allowed: documentation and cognition paths only
+    // Build explicit smartdocs paths instead of granting the entire root
+    const smartdocsRawDir = node_path_1.default.join(repoRoot, "smartdocs", "raw");
+    const smartdocsSpecsActiveDir = node_path_1.default.join(repoRoot, "smartdocs", "specs", "active");
+    const smartdocsDoctrineActiveDir = node_path_1.default.join(repoRoot, "smartdocs", "doctrine", "active");
     const allowedWritePaths = [
         ...polarisMdPaths.map((p) => node_path_1.default.join(repoRoot, p.polaris_md)),
         ...polarisMdPaths.filter((p) => p.summary_md).map((p) => node_path_1.default.join(repoRoot, p.summary_md)),
-        node_path_1.default.join(repoRoot, "smartdocs"),
+        smartdocsRawDir,
+        smartdocsSpecsActiveDir,
+        smartdocsDoctrineActiveDir,
         node_path_1.default.join(repoRoot, ".polaris", "cognition", "archive"),
         resultPath,
     ];

package/dist/cognition/validate.js

@@ -9,6 +9,7 @@
  * - Locality assumptions (route-local only, no repo-wide surface)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeNormalizedSimilarity = computeNormalizedSimilarity;
 exports.looksLikePolarisChurn = looksLikePolarisChurn;
 exports.validateCognitionSurfaces = validateCognitionSurfaces;
 exports.validateSummaryFile = validateSummaryFile;
@@ -17,6 +18,48 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const route_cognition_delta_js_1 = require("./route-cognition-delta.js");
 const summary_delta_js_1 = require("./summary-delta.js");
+const DEFAULT_PAIRWISE_DRIFT_THRESHOLD = 0.5;
+// ── Pairwise POLARIS.md / SUMMARY.md drift detection ───────────────────────────
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Normalize route artifact text so shared boilerplate (headings, links, route
+ * names) does not dominate similarity scores.
+ */
+function normalizeRouteArtifact(content, routeName) {
+    let s = content.toLowerCase();
+    // Strip markdown headings
+    s = s.replace(/^#+\s+.*$/gm, " ");
+    // Remove link URLs but keep link text
+    s = s.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+    // Remove bare URLs
+    s = s.replace(/https?:\/\/\S+/g, " ");
+    // Remove route name tokens
+    if (routeName) {
+        for (const token of routeName.split(/[-_\s]+/).filter(Boolean)) {
+            s = s.replace(new RegExp(`\\b${escapeRegExp(token)}\\b`, "g"), " ");
+        }
+    }
+    // Drop non-alphanumeric characters
+    s = s.replace(/[^\p{L}\p{N}\s]+/gu, " ");
+    // Collapse whitespace
+    s = s.replace(/\s+/g, " ").trim();
+    return s;
+}
+/**
+ * Compute a normalized Jaccard similarity between two route artifacts.
+ * Returns a value between 0 and 1.
+ */
+function computeNormalizedSimilarity(a, b, routeName) {
+    const tokensA = new Set(normalizeRouteArtifact(a, routeName).split(" ").filter(Boolean));
+    const tokensB = new Set(normalizeRouteArtifact(b, routeName).split(" ").filter(Boolean));
+    if (tokensA.size === 0 && tokensB.size === 0)
+        return 0;
+    const intersection = new Set([...tokensA].filter((t) => tokensB.has(t)));
+    const union = new Set([...tokensA, ...tokensB]);
+    return union.size === 0 ? 0 : intersection.size / union.size;
+}
 // ── POLARIS.md churn detection ────────────────────────────────────────────────
 /**
  * Signals that indicate a POLARIS.md change is likely non-operational churn
@@ -62,18 +105,21 @@ function* walkForCognitionFiles(dir, repoRoot) {
         }
     }
 }
-// ── Main validation entry point ───────────────────────────────────────────────
 /**
  * Validate all route-local cognition surfaces under repoRoot.
  *
  * Checks:
  * 1. SUMMARY.md size guard (≤ SUMMARY_MAX_BYTES)
  * 2. SUMMARY.md doctrine bleed
- * 3. Locality: POLARIS.md at root is not flagged (root is special)
+ * 3. Pairwise POLARIS.md / SUMMARY.md drift (exact duplicate → error,
+ *    high normalized similarity → warn)
+ * 4. Locality: POLARIS.md at root is not flagged (root is special)
  */
-function validateCognitionSurfaces(repoRoot) {
+function validateCognitionSurfaces(repoRoot, options = {}) {
     const violations = [];
     const warnings = [];
+    const threshold = options.similarityThreshold ?? DEFAULT_PAIRWISE_DRIFT_THRESHOLD;
+    const pairs = new Map();
     for (const { rel, name } of walkForCognitionFiles((0, node_path_1.resolve)(repoRoot), repoRoot)) {
         // Skip root-level files — root cognition is special (AGENTS.md / CLAUDE.md)
         if (!rel.includes("/"))
@@ -85,7 +131,16 @@ function validateCognitionSurfaces(repoRoot) {
         catch {
             continue;
         }
+        const absDir = (0, node_path_1.dirname)((0, node_path_1.resolve)(repoRoot, rel));
+        const dirRel = (0, node_path_1.relative)(repoRoot, absDir).replace(/\\/g, "/");
+        let entry = pairs.get(absDir);
+        if (!entry) {
+            entry = { dirRel };
+            pairs.set(absDir, entry);
+        }
         if (name === "SUMMARY.md") {
+            entry.summary = content;
+            entry.summaryRel = rel;
             if ((0, summary_delta_js_1.isSummaryOversized)(content)) {
                 const bytes = Buffer.byteLength(content, "utf-8");
                 violations.push({
@@ -106,6 +161,33 @@ function validateCognitionSurfaces(repoRoot) {
                 });
             }
         }
+        else if (name === "POLARIS.md") {
+            entry.polaris = content;
+            entry.polarisRel = rel;
+        }
+    }
+    for (const entry of pairs.values()) {
+        if (!entry.polaris || !entry.summary || !entry.polarisRel || !entry.summaryRel)
+            continue;
+        if (entry.polaris === entry.summary) {
+            violations.push({
+                type: "polaris-summary-drift",
+                file: entry.dirRel,
+                detail: `Route ${entry.dirRel}: POLARIS.md and SUMMARY.md are exact duplicates (${entry.polarisRel}, ${entry.summaryRel})`,
+                severity: "error",
+            });
+            continue;
+        }
+        const routeName = entry.dirRel === "." ? undefined : (0, node_path_1.basename)(entry.dirRel);
+        const similarity = computeNormalizedSimilarity(entry.polaris, entry.summary, routeName);
+        if (similarity >= threshold) {
+            warnings.push({
+                type: "polaris-summary-drift",
+                file: entry.dirRel,
+                detail: `Route ${entry.dirRel}: POLARIS.md and SUMMARY.md normalized similarity ${similarity.toFixed(2)} exceeds threshold ${threshold} (${entry.polarisRel}, ${entry.summaryRel})`,
+                severity: "warn",
+            });
+        }
     }
     return {
         valid: violations.length === 0,