@lsctech/polaris 0.5.9 → 0.5.10

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/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,

package/dist/config/defaults.js

@@ -123,5 +123,6 @@ exports.DEFAULT_CONFIG = {
         },
         routes: {},
         maxRepairRounds: 2,
+        repairDispatchTimeoutMs: 1_800_000,
     },
 };

package/dist/finalize/index.js

@@ -7,6 +7,7 @@ exports.validateAuthoritativeChildState = validateAuthoritativeChildState;
 exports.runFinalize = runFinalize;
 exports.createFinalizeCommand = createFinalizeCommand;
 const commander_1 = require("commander");
+const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
@@ -35,7 +36,11 @@ const index_js_1 = require("../tracker/sync/index.js");
 const finalize_evidence_js_1 = require("../loop/finalize-evidence.js");
 const delivery_integrity_js_1 = require("./delivery-integrity.js");
 const medic_gate_js_1 = require("./medic-gate.js");
+const qc_escalation_js_1 = require("../run-health/qc-escalation.js");
 const index_js_2 = require("../qc/index.js");
+const worker_packet_js_1 = require("../loop/worker-packet.js");
+const registry_js_1 = require("../loop/adapters/registry.js");
+const dispatch_js_1 = require("../loop/dispatch.js");
 function getBranch(repoRoot) {
     try {
         return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
@@ -368,6 +373,188 @@ async function runQcGate(options) {
     process.stderr.write(`${stepLabel} QC ${trigger} blocked finalize: ${result.summary}\n`);
     process.exit(1);
 }
+function parseWorkerSummary(summary) {
+    if (!summary)
+        return null;
+    try {
+        const parsed = JSON.parse(summary);
+        if (typeof parsed === "object" && parsed !== null) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function runCompletedClusterQcWithRepair(options) {
+    const { config, state, stateFile, repoRoot, branch, baseRef, stepLabel } = options;
+    const registry = (0, index_js_2.createQcRegistry)(config.qc);
+    const qcResult = await (0, index_js_2.runQcAtTrigger)({
+        config: config.qc,
+        registry,
+        trigger: "completed-cluster",
+        repoRoot,
+        runId: state.run_id,
+        clusterId: state.cluster_id,
+        branch,
+        baseRef,
+        telemetryFile: resolveQcTelemetryFile(state, repoRoot),
+        state,
+    });
+    if (qcResult.action === "pass") {
+        const maxRounds = config.qc.maxRepairRounds ?? index_js_2.DEFAULT_MAX_REPAIR_ROUNDS;
+        const sourceQcRunIds = qcResult.results.map((r) => r.qcRunId).filter(Boolean);
+        const existingLoop = state.qc_repair_loop;
+        const now = new Date().toISOString();
+        const passLoopState = existingLoop
+            ? {
+                ...existingLoop,
+                terminal_outcome: existingLoop.terminal_outcome ?? "pass",
+                updated_at: existingLoop.terminal_outcome == null ? now : (existingLoop.updated_at ?? now),
+            }
+            : {
+                ...(0, index_js_2.initRepairLoopState)({ maxRounds, sourceQcRunIds }),
+                terminal_outcome: "pass",
+                updated_at: now,
+            };
+        const passedState = { ...state, qc_repair_loop: passLoopState };
+        (0, checkpoint_js_1.writeStateAtomic)(stateFile, passedState);
+        console.log(`${stepLabel} QC completed-cluster passed: ${qcResult.summary}`);
+        return passedState;
+    }
+    // Append QC escalation symptoms for the initial non-passing completed-cluster QC result.
+    if (qcResult.results.length > 0) {
+        (0, qc_escalation_js_1.appendQcEscalationSymptoms)({
+            runId: state.run_id,
+            clusterId: state.cluster_id,
+            qcResults: qcResult.results,
+            afterRepair: false,
+            repoRoot,
+        });
+    }
+    const repairRouting = config.qc.repairRouting ?? "route";
+    if (repairRouting !== "route" && repairRouting !== "follow-up") {
+        process.stderr.write(`${stepLabel} QC completed-cluster blocked finalize: ${qcResult.summary}\n`);
+        process.exit(1);
+    }
+    const adapterName = config.execution?.adapter ?? "terminal-cli";
+    let providerName;
+    if (adapterName === "agent-subtask") {
+        providerName = "agent-subtask";
+    }
+    else {
+        try {
+            const providerEvidence = (0, dispatch_js_1.resolveProviderAndMode)({ stateFile, repoRoot }, "worker", config);
+            providerName = providerEvidence.provider ?? "default";
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`${stepLabel} QC repair loop provider resolution failed: ${msg}\n`);
+            process.exit(1);
+        }
+    }
+    const executionConfig = adapterName === "agent-subtask"
+        ? { ...(config.execution ?? { providers: {} }), adapter: "agent-subtask" }
+        : config.execution ?? { adapter: adapterName, providers: {} };
+    const adapter = (0, registry_js_1.createAdapter)(adapterName, executionConfig);
+    const maxConcurrentWorkers = config.execution?.routerPolicy?.defaultWorkerPool?.maxActiveWorkers ?? 1;
+    const telemetryFile = resolveQcTelemetryFile(state, repoRoot);
+    let nextState = state;
+    const repairDispatcher = async (packet, round, manifest, signal) => {
+        const dispatchId = (0, node_crypto_1.randomUUID)();
+        const repairResultPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", nextState.cluster_id, "results", `repair-${packet.packetId}-${dispatchId}.json`);
+        const workerPacket = (0, worker_packet_js_1.compileRepairWorkerPacket)({
+            runId: nextState.run_id,
+            clusterId: nextState.cluster_id,
+            packetId: packet.packetId,
+            branch,
+            stateFile,
+            telemetryFile,
+            round,
+            allowedScope: packet.allowedScope,
+            prohibitedScope: packet.prohibitedScope,
+            validationCommands: packet.validationCommands,
+            rootCauseHint: packet.rootCauseHint,
+            resultFile: repairResultPath,
+            maxConcurrentWorkers,
+        });
+        try {
+            // TODO: Propagate AbortSignal to adapter.dispatch() once ExecutionAdapter
+            // interface supports cancellation. Current limitation: timeout abandons the
+            // Promise but doesn't terminate the spawned worker process.
+            if (signal?.aborted) {
+                throw signal.reason || new Error("Repair dispatch aborted");
+            }
+            const dispatchResult = await adapter.dispatch(workerPacket, { provider: providerName });
+            const workerSummary = parseWorkerSummary(dispatchResult.summary);
+            const success = workerSummary?.status === "done";
+            const commitSha = workerSummary && typeof workerSummary["commit"] === "string"
+                ? workerSummary["commit"]
+                : undefined;
+            const errorMessage = workerSummary && typeof workerSummary["error_message"] === "string"
+                ? workerSummary["error_message"]
+                : "repair worker failed";
+            return {
+                packetId: packet.packetId,
+                status: success ? "success" : "failure",
+                commitSha,
+                errorMessage: success ? undefined : errorMessage,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                packetId: packet.packetId,
+                status: "failure",
+                errorMessage: msg,
+            };
+        }
+    };
+    const repairLoopResult = await (0, index_js_2.runQcRepairLoop)({
+        clusterId: nextState.cluster_id,
+        runId: nextState.run_id,
+        branch,
+        repoRoot,
+        telemetryFile,
+        config: config.qc,
+        registry,
+        initialQcResults: qcResult.results,
+        dispatchRepairWorker: repairDispatcher,
+        maxRounds: config.qc.maxRepairRounds ?? index_js_2.DEFAULT_MAX_REPAIR_ROUNDS,
+        priorLoopState: nextState.qc_repair_loop ?? null,
+        onStateUpdate: (loopState) => {
+            nextState = { ...nextState, qc_repair_loop: loopState };
+            (0, checkpoint_js_1.writeStateAtomic)(stateFile, nextState);
+        },
+    });
+    nextState = { ...nextState, qc_repair_loop: repairLoopResult.loop_state };
+    (0, checkpoint_js_1.writeStateAtomic)(stateFile, nextState);
+    // Append QC escalation symptoms for non-passing repair-loop outcomes and post-repair findings.
+    (0, qc_escalation_js_1.appendRepairLoopOutcomeSymptom)({
+        runId: nextState.run_id,
+        clusterId: nextState.cluster_id,
+        repairResult: repairLoopResult,
+        repoRoot,
+    });
+    if (repairLoopResult.final_qc_results.length > 0 && repairLoopResult.rounds_completed > 0) {
+        (0, qc_escalation_js_1.appendQcEscalationSymptoms)({
+            runId: nextState.run_id,
+            clusterId: nextState.cluster_id,
+            qcResults: repairLoopResult.final_qc_results,
+            afterRepair: true,
+            repoRoot,
+        });
+    }
+    const repairLoopBlocker = validateQcRepairLoopGate(nextState, config.qc);
+    if (repairLoopBlocker) {
+        process.stderr.write(`${stepLabel} QC completed-cluster blocked finalize: ${qcResult.summary}\n` +
+            `${repairLoopBlocker}\n`);
+        process.exit(1);
+    }
+    console.log(`${stepLabel} QC completed-cluster repaired: ${repairLoopResult.summary}`);
+    return nextState;
+}
 async function runFinalize(options) {
     const { repoRoot, stateFile, dryRun, skipDelivery, skipLibrarian, bypassMedicReason } = options;
     const config = (0, loader_js_1.loadConfig)(repoRoot);
@@ -554,13 +741,13 @@ async function runFinalize(options) {
     const qcBaseRef = clusterStateForQc?.base_branch ??
         config.finalize?.targetBranch ??
         "main";
-    await runQcGate({
-        config: config.qc,
+    state = await runCompletedClusterQcWithRepair({
+        config,
         state,
+        stateFile: (0, node_path_1.resolve)(stateFile),
         repoRoot,
         branch,
         baseRef: qcBaseRef,
-        trigger: "completed-cluster",
         stepLabel: "[5.8/14]",
     });
     // Step 5.9: QC repair-loop terminal state gate

package/dist/loop/adapters/terminal-cli.js

@@ -169,10 +169,11 @@ class TerminalCliAdapter {
         const primaryProvider = options.provider || "terminal-cli";
         const routerEvidence = options.routerDecision;
         const providerAttempts = [];
-        if ((0, worker_packet_js_1.isWorkerPacket)(packet) && packet.worker_role === "impl") {
+        if ((0, worker_packet_js_1.isWorkerPacket)(packet) &&
+            (packet.worker_role === "impl" || packet.worker_role === "repair")) {
             const allowed = Array.isArray(packet.instructions?.allowed_scope) ? packet.instructions.allowed_scope : [];
             if (allowed.length === 0) {
-                const blockedMsg = `Worker blocked: impl packet for ${packet.active_child} has empty allowed_scope. Foreman must provide scope or approve override.`;
+                const blockedMsg = `Worker blocked: ${packet.worker_role} packet for ${packet.active_child} has empty allowed_scope. Foreman must provide scope or approve override.`;
                 return {
                     exit_code: 1,
                     provider_used: primaryProvider,

package/dist/loop/parent.js

@@ -949,7 +949,7 @@ async function runParentLoop(options) {
                     const maxRepairRounds = config.qc.maxRepairRounds ?? repair_loop_js_1.DEFAULT_MAX_REPAIR_ROUNDS;
                     const priorLoopState = state.qc_repair_loop ?? null;
                     // Build the repair worker dispatcher using the existing adapter + provider.
-                    const repairDispatcher = async (packet, round, manifest) => {
+                    const repairDispatcher = async (packet, round, manifest, signal) => {
                         const repairPacketId = packet.packetId;
                         const dispatchId = (0, node_crypto_1.randomUUID)();
                         const repairWorkerId = `${state.run_id}:repair-${repairPacketId}:${Date.now()}`;
@@ -979,6 +979,12 @@ async function runParentLoop(options) {
                             timestamp: new Date().toISOString(),
                         });
                         try {
+                            // TODO: Propagate AbortSignal to adapter.dispatch() once ExecutionAdapter
+                            // interface supports cancellation. Current limitation: timeout abandons the
+                            // Promise but doesn't terminate the spawned worker process.
+                            if (signal?.aborted) {
+                                throw signal.reason || new Error("Repair dispatch aborted");
+                            }
                             const dispatchResult = await adapter.dispatch(workerPacket, { provider: providerName, dryRun });
                             const workerSummary = parseWorkerSummary(dispatchResult.summary);
                             const success = workerSummary?.status === "done";

package/dist/qc/providers/coderabbit.js

@@ -17,18 +17,20 @@ function pickString(...candidates) {
     return undefined;
 }
 const FINDING_LOCATION_KEYS = ["file", "filePath", "path"];
-const FINDING_REVIEW_KEYS = [
-    "severity",
+const FINDING_CONTENT_KEYS = [
     "message",
     "title",
     "summary",
     "description",
     "body",
-    "rule",
-    "category",
     "suggestion",
     "suggestedAction",
     "fix",
+];
+const FINDING_BOOKKEEPING_KEYS = [
+    "severity",
+    "category",
+    "rule",
     "providerFindingId",
     "id",
     "findingId",
@@ -56,8 +58,37 @@ const PROGRESS_STATUS_VALUES = new Set([
 function hasFindingLocation(record) {
     return FINDING_LOCATION_KEYS.some((key) => record[key] !== undefined);
 }
-function hasFindingReviewContent(record) {
-    return FINDING_REVIEW_KEYS.some((key) => record[key] !== undefined);
+function isGenuineTitle(record) {
+    const title = record.title;
+    if (typeof title !== "string" || title.trim().length === 0) {
+        return false;
+    }
+    const trimmedTitle = title.trim().toLowerCase();
+    const fallbackSources = [record.category, record.type, record.rule];
+    for (const source of fallbackSources) {
+        if (typeof source === "string" && source.trim().toLowerCase() === trimmedTitle) {
+            return false;
+        }
+    }
+    return true;
+}
+function hasFindingContent(record) {
+    for (const key of FINDING_CONTENT_KEYS) {
+        if (key === "title") {
+            if (isGenuineTitle(record))
+                return true;
+        }
+        else if (record[key] !== undefined) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasFindingBookkeeping(record) {
+    return FINDING_BOOKKEEPING_KEYS.some((key) => record[key] !== undefined);
+}
+function hasFindingShape(record) {
+    return hasFindingLocation(record) || hasFindingContent(record) || hasFindingBookkeeping(record);
 }
 function isProgressRecord(record) {
     // Check progress/status indicators FIRST before the generic finding-content guard
@@ -73,8 +104,8 @@ function isProgressRecord(record) {
     // Status-only records with category="status" are progress records even if they have message/title fields
     if (typeof record.category === "string" && record.category.toLowerCase() === "status")
         return true;
-    // Only reject as progress if it has both location AND review content (true finding shape)
-    if (hasFindingLocation(record) && hasFindingReviewContent(record)) {
+    // Only reject as progress if it has both location AND content (true finding shape)
+    if (hasFindingLocation(record) && hasFindingContent(record)) {
         return false;
     }
     return false;
@@ -82,7 +113,10 @@ function isProgressRecord(record) {
 function isActionableFinding(record) {
     if (isProgressRecord(record))
         return false;
-    return hasFindingLocation(record) || hasFindingReviewContent(record);
+    return hasFindingLocation(record) || hasFindingContent(record);
+}
+function isUnusableFindingRecord(record) {
+    return !isActionableFinding(record) && (isProgressRecord(record) || hasFindingShape(record));
 }
 function makeUnusableOutputError(message) {
     const err = new Error(message);
@@ -136,6 +170,21 @@ function parseReport(output, format, parser) {
     if (data !== undefined && typeof data === "object" && data !== null) {
         const findings = parseFindingsFromPayload(data);
         const record = data;
+        if (findings.length === 0) {
+            if (isProgressRecord(record)) {
+                throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
+            }
+            if (isUnusableFindingRecord(record)) {
+                throw makeUnusableOutputError("CodeRabbit output contained only bookkeeping records");
+            }
+            const rawFindings = record.findings ?? record.issues ?? record.results;
+            if (Array.isArray(rawFindings) && rawFindings.length > 0) {
+                const unusableCount = rawFindings.filter((item) => typeof item === "object" && item !== null && isUnusableFindingRecord(item)).length;
+                if (unusableCount > 0) {
+                    throw makeUnusableOutputError(`CodeRabbit output contained only bookkeeping/progress records (${unusableCount} items)`);
+                }
+            }
+        }
         return {
             findings,
             ...(typeof record.prUrl === "string" ? { prUrl: record.prUrl } : {}),
@@ -150,16 +199,29 @@ function parseReport(output, format, parser) {
             if (Array.isArray(parsed)) {
                 const findings = parsed.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
                 if (findings.length === 0 && parsed.length > 0) {
-                    const progressCount = parsed.filter((item) => typeof item === "object" && item !== null && isProgressRecord(item)).length;
-                    if (progressCount > 0) {
-                        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat records (${progressCount} items)`);
+                    const unusableCount = parsed.filter((item) => typeof item === "object" && item !== null && isUnusableFindingRecord(item)).length;
+                    if (unusableCount > 0) {
+                        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat and bookkeeping records (${unusableCount} items)`);
                     }
                 }
                 return { findings };
             }
             const findings = parseFindingsFromPayload(parsed);
-            if (findings.length === 0 && isProgressRecord(parsed)) {
-                throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
+            if (findings.length === 0) {
+                const parsedRecord = parsed;
+                if (isProgressRecord(parsedRecord)) {
+                    throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
+                }
+                if (isUnusableFindingRecord(parsedRecord)) {
+                    throw makeUnusableOutputError("CodeRabbit output contained only bookkeeping records");
+                }
+                const rawFindings = parsedRecord.findings ?? parsedRecord.issues ?? parsedRecord.results;
+                if (Array.isArray(rawFindings) && rawFindings.length > 0) {
+                    const unusableCount = rawFindings.filter((item) => typeof item === "object" && item !== null && isUnusableFindingRecord(item)).length;
+                    if (unusableCount > 0) {
+                        throw makeUnusableOutputError(`CodeRabbit output contained only bookkeeping/progress records (${unusableCount} items)`);
+                    }
+                }
             }
             return {
                 findings,
@@ -169,8 +231,14 @@ function parseReport(output, format, parser) {
             };
         }
         catch (jsonError) {
-            // When the format is explicitly JSON, a parse error is a real failure.
-            // Otherwise, treat the text as JSONL and fall through to line scanning.
+            // Semantic failures (e.g. unusable-output) surfaced during JSON object/array
+            // parsing must not be swallowed; only true JSON parse errors fall through to
+            // JSONL line scanning when the format is not explicitly JSON.
+            if (typeof jsonError === "object" &&
+                jsonError !== null &&
+                "qcFailureReason" in jsonError) {
+                throw jsonError;
+            }
             if (format === "json") {
                 throw jsonError;
             }
@@ -180,6 +248,7 @@ function parseReport(output, format, parser) {
     const lines = text.split("\n").filter((line) => line.trim().length > 0);
     const lineFindings = [];
     let progressLineCount = 0;
+    let unusableLineCount = 0;
     let parsedLineCount = 0;
     for (const line of lines) {
         try {
@@ -196,6 +265,9 @@ function parseReport(output, format, parser) {
             if (isActionableFinding(record)) {
                 lineFindings.push(parsed);
             }
+            else if (isUnusableFindingRecord(record)) {
+                unusableLineCount++;
+            }
         }
         catch {
             // Ignore unparseable lines.
@@ -204,8 +276,8 @@ function parseReport(output, format, parser) {
     if (lineFindings.length > 0) {
         return { findings: lineFindings };
     }
-    if (progressLineCount > 0) {
-        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat records (${progressLineCount} lines)`);
+    if (progressLineCount > 0 || unusableLineCount > 0) {
+        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat and bookkeeping records (${progressLineCount + unusableLineCount} lines)`);
     }
     if (parsedLineCount > 0) {
         throw new Error("CodeRabbit output contained no actionable findings");

package/dist/qc/repair-loop.js

@@ -16,7 +16,7 @@
  * Each repair packet becomes a sealed WorkerPacket with worker_role: "repair".
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MAX_REPAIR_ROUNDS = void 0;
+exports.DEFAULT_REPAIR_DISPATCH_TIMEOUT_MS = exports.DEFAULT_MAX_REPAIR_ROUNDS = void 0;
 exports.partitionRepairPackets = partitionRepairPackets;
 exports.initRepairLoopState = initRepairLoopState;
 exports.runQcRepairLoop = runQcRepairLoop;
@@ -28,11 +28,71 @@ const store_js_1 = require("../cluster-state/store.js");
 // ── Constants ─────────────────────────────────────────────────────────────────
 /** Default maximum repair rounds when not configured. */
 exports.DEFAULT_MAX_REPAIR_ROUNDS = 2;
+/** Default timeout for a single repair worker dispatch (30 minutes). */
+exports.DEFAULT_REPAIR_DISPATCH_TIMEOUT_MS = 1_800_000;
 // ── Helpers ────────────────────────────────────────────────────────────────────
 function appendTelemetry(telemetryFile, event) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
     (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
 }
+/**
+ * Emit a pre-dispatch telemetry checkpoint and wrap the dispatch call in a
+ * configurable timeout. A timed-out dispatch resolves to a failure/timeout
+ * RepairWorkerResult instead of blocking the loop indefinitely.
+ * On timeout, aborts the dispatch via AbortSignal to terminate the worker process.
+ */
+async function dispatchRepairWorkerWithTimeout(dispatch, packet, round, manifest, timeoutMs, telemetryFile, runId, clusterId) {
+    appendTelemetry(telemetryFile, {
+        event: "qc-repair-worker-dispatch-start",
+        run_id: runId,
+        cluster_id: clusterId,
+        round,
+        packet_id: packet.packetId,
+        medic: packet.medic,
+        parallel_group: packet.parallelGroup,
+        timestamp: new Date().toISOString(),
+    });
+    const controller = new AbortController();
+    let timer;
+    let timedOut = false;
+    try {
+        const result = await Promise.race([
+            dispatch(packet, round, manifest, controller.signal),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort(new Error(`Repair worker dispatch timed out after ${timeoutMs}ms`));
+                    reject(new Error(`Repair worker dispatch timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+        return result;
+    }
+    catch (err) {
+        if (timer)
+            clearTimeout(timer);
+        const msg = err instanceof Error ? err.message : String(err);
+        if (timedOut) {
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-worker-dispatch-timeout",
+                run_id: runId,
+                cluster_id: clusterId,
+                round,
+                packet_id: packet.packetId,
+                timeout_ms: timeoutMs,
+                error: msg,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        return {
+            packetId: packet.packetId,
+            status: "failure",
+            errorMessage: msg,
+        };
+    }
+}
 async function persistQcRepairOutcome(clusterId, repoRoot, outcome) {
     try {
         const clusterState = (0, store_js_1.readClusterStateSync)(clusterId, repoRoot);
@@ -96,8 +156,8 @@ function rerunPassed(results) {
 }
 /** Partition packets into safe-to-parallel and must-serialize groups. */
 function partitionRepairPackets(packets) {
-    // Medic (operator-review) packets are always serialized.
-    const serialized = packets.filter((p) => p.medic || p.routingTarget === "operator-review");
+    // Medic packets are always serialized; operator-review packets are never dispatched.
+    const serialized = packets.filter((p) => p.medic);
     const parallelizable = packets.filter((p) => !p.medic && p.routingTarget !== "operator-review");
     // Group by parallelGroup assignment from the compiler.
     const groups = new Map();
@@ -139,6 +199,7 @@ function initRepairLoopState(opts) {
  */
 async function runQcRepairLoop(options) {
     const { clusterId, runId, branch, repoRoot, telemetryFile, config, registry, initialQcResults, dispatchRepairWorker, validationCommands = [], timeoutMs, maxRounds = exports.DEFAULT_MAX_REPAIR_ROUNDS, priorLoopState, onStateUpdate, } = options;
+    const repairDispatchTimeoutMs = config.repairDispatchTimeoutMs ?? exports.DEFAULT_REPAIR_DISPATCH_TIMEOUT_MS;
     if (!config.enabled) {
         const state = initRepairLoopState({
             maxRounds,
@@ -194,25 +255,6 @@ async function runQcRepairLoop(options) {
                 summary: `QC repair loop halted: all QC providers failed at round ${round}`,
             };
         }
-        if (requiresOperatorReview(currentResults)) {
-            loopState = { ...loopState, terminal_outcome: "operator-review", updated_at: new Date().toISOString() };
-            onStateUpdate?.(loopState);
-            appendTelemetry(telemetryFile, {
-                event: "qc-repair-loop-terminal",
-                run_id: runId,
-                outcome: "operator-review",
-                round,
-                timestamp: new Date().toISOString(),
-            });
-            await persistQcRepairOutcome(clusterId, repoRoot, "operator-review");
-            return {
-                outcome: "operator-review",
-                rounds_completed: roundsCompleted,
-                final_qc_results: currentResults,
-                loop_state: loopState,
-                summary: `QC repair loop halted: unresolved operator-review findings at round ${round}`,
-            };
-        }
         // ── Compile / discover repair packets ──────────────────────────────────
         let manifest = null;
         // Try to read an existing manifest for this round first (idempotent re-entry).
@@ -261,10 +303,29 @@ async function runQcRepairLoop(options) {
             await persistQcRepairManifest(clusterId, repoRoot, round, existingManifestPath);
         }
         // ── Check for repairable packets ────────────────────────────────────────
-        const repairablePackets = manifest.packets.filter((p) => p.routingTarget === "repair-worker" &&
+        const dispatchablePackets = manifest.packets.filter((p) => p.routingTarget === "repair-worker" &&
             p.status === "pending" &&
             !loopState.completed_packet_ids.includes(p.packetId));
-        if (repairablePackets.length === 0 && !hasRepairableFindings(currentResults)) {
+        if (dispatchablePackets.length === 0 && requiresOperatorReview(currentResults)) {
+            loopState = { ...loopState, terminal_outcome: "operator-review", updated_at: new Date().toISOString() };
+            onStateUpdate?.(loopState);
+            appendTelemetry(telemetryFile, {
+                event: "qc-repair-loop-terminal",
+                run_id: runId,
+                outcome: "operator-review",
+                round,
+                timestamp: new Date().toISOString(),
+            });
+            await persistQcRepairOutcome(clusterId, repoRoot, "operator-review");
+            return {
+                outcome: "operator-review",
+                rounds_completed: roundsCompleted,
+                final_qc_results: currentResults,
+                loop_state: loopState,
+                summary: `QC repair loop halted: unresolved operator-review findings at round ${round}`,
+            };
+        }
+        if (dispatchablePackets.length === 0 && !hasRepairableFindings(currentResults)) {
             loopState = { ...loopState, terminal_outcome: "no-repairable", updated_at: new Date().toISOString() };
             onStateUpdate?.(loopState);
             appendTelemetry(telemetryFile, {
@@ -284,7 +345,7 @@ async function runQcRepairLoop(options) {
             };
         }
         // ── Dispatch repair workers (parallel groups, then serialized) ──────────
-        const { parallelGroups, serialized } = partitionRepairPackets(repairablePackets);
+        const { parallelGroups, serialized } = partitionRepairPackets(dispatchablePackets);
         const allWorkerResults = [];
         let hasMedicReferral = false;
         // Dispatch parallel groups.
@@ -298,12 +359,12 @@ async function runQcRepairLoop(options) {
                 timestamp: new Date().toISOString(),
             });
             // Within a group, packets are non-conflicting and can run concurrently.
-            const groupResults = await Promise.all(group.map((pkt) => dispatchRepairWorker(pkt, round, manifest)));
+            const groupResults = await Promise.all(group.map((pkt) => dispatchRepairWorkerWithTimeout(dispatchRepairWorker, pkt, round, manifest, repairDispatchTimeoutMs, telemetryFile, runId, clusterId)));
             allWorkerResults.push(...groupResults);
         }
-        // Dispatch serialized (medic/operator-review) packets sequentially.
+        // Dispatch serialized (medic) packets sequentially.
         for (const pkt of serialized) {
-            const result = await dispatchRepairWorker(pkt, round, manifest);
+            const result = await dispatchRepairWorkerWithTimeout(dispatchRepairWorker, pkt, round, manifest, repairDispatchTimeoutMs, telemetryFile, runId, clusterId);
             allWorkerResults.push(result);
         }
         // Record completed packet IDs.
@@ -438,6 +499,25 @@ async function runQcRepairLoop(options) {
         }
     }
     // ── Max rounds exhausted ──────────────────────────────────────────────────
+    if (requiresOperatorReview(currentResults)) {
+        loopState = { ...loopState, terminal_outcome: "operator-review", updated_at: new Date().toISOString() };
+        onStateUpdate?.(loopState);
+        appendTelemetry(telemetryFile, {
+            event: "qc-repair-loop-terminal",
+            run_id: runId,
+            outcome: "operator-review",
+            rounds_completed: roundsCompleted,
+            timestamp: new Date().toISOString(),
+        });
+        await persistQcRepairOutcome(clusterId, repoRoot, "operator-review");
+        return {
+            outcome: "operator-review",
+            rounds_completed: roundsCompleted,
+            final_qc_results: currentResults,
+            loop_state: loopState,
+            summary: `QC repair loop halted: unresolved operator-review findings after ${roundsCompleted} round(s)`,
+        };
+    }
     loopState = { ...loopState, terminal_outcome: "max-rounds", updated_at: new Date().toISOString() };
     onStateUpdate?.(loopState);
     appendTelemetry(telemetryFile, {

package/dist/qc/runner.js

@@ -76,6 +76,12 @@ function classifyTerminalFailure(error, output) {
     if (execError?.killed && execError?.signal === "SIGTERM") {
         return "timeout";
     }
+    // Exit code 143 is the standard shell convention for a process killed by SIGTERM
+    // (128 + SIGTERM). Some provider CLI wrappers report this directly instead of
+    // allowing Node's execFile to surface the signal, so treat it as a timeout.
+    if (output.exitCode === 143) {
+        return "timeout";
+    }
     if (execError?.code === "ENOENT") {
         return "command-not-found";
     }
@@ -174,8 +180,8 @@ async function runSingleProvider(provider, scope, options, fallbackSource) {
     const startedAt = new Date().toISOString();
     const command = provider.buildReviewCommand(scope);
     const execFn = options.execFileImpl ?? node_child_process_1.execFile;
-    const timeoutMs = options.timeoutMs ?? 300_000; // 5 minutes default
     const providerConfig = getProviderConfig(provider.name, options.config);
+    const timeoutMs = options.timeoutMs ?? providerConfig?.timeoutMs ?? 300_000; // 5 minutes default
     emitProviderAttempted(options.telemetryFile, scope.runId, scope.clusterId, provider.name, fallbackSource);
     if (!isModeSupported(provider, scope)) {
         const output = {

package/dist/smartdocs-engine/validate-instructions.js

@@ -13,6 +13,47 @@ const loader_js_1 = require("../config/loader.js");
 const atlas_js_1 = require("../map/atlas.js");
 const seed_instructions_js_1 = require("./seed-instructions.js");
 const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
+const DEFAULT_PAIRWISE_DRIFT_THRESHOLD = 0.5;
+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;
+}
 /**
  * Get the last git modification date of a file.
  * Returns null if the file is untracked or git is unavailable.
@@ -123,7 +164,7 @@ function collectDirs(dir, root, eligibilityOpts = {}, result = { eligible: [], i
 /**
  * Validate a single directory's POLARIS.md.
  */
-function validateDir(relDir, repoRoot, allRoutes) {
+function validateDir(relDir, repoRoot, allRoutes, similarityThreshold = DEFAULT_PAIRWISE_DRIFT_THRESHOLD) {
     const absDir = (0, node_path_1.resolve)(repoRoot, relDir);
     const polarisFile = (0, node_path_1.join)(absDir, "POLARIS.md");
     const polarisRel = (0, node_path_1.relative)(repoRoot, polarisFile).replace(/\\/g, "/");
@@ -248,6 +289,7 @@ function validateDir(relDir, repoRoot, allRoutes) {
     else {
         // Signal 6: SUMMARY.md doctrine-bleed scan
         const summaryContent = (0, node_fs_1.readFileSync)(summaryFile, "utf-8");
+        const summaryRel = (0, node_path_1.relative)(repoRoot, summaryFile).replace(/\\/g, "/");
         const modalVerbs = ["must", "never", "always"];
         const lines = summaryContent.split("\n");
         for (let i = 0; i < lines.length; i++) {
@@ -261,6 +303,21 @@ function validateDir(relDir, repoRoot, allRoutes) {
                 }
             }
         }
+        // Signal 7: pairwise POLARIS.md / SUMMARY.md drift
+        const routeName = relDir === "." ? undefined : (0, node_path_1.basename)(relDir);
+        const similarity = computeNormalizedSimilarity(content, summaryContent, routeName);
+        if (content === summaryContent) {
+            findings.push({
+                severity: "ERROR",
+                message: `Route ${relDir || "."}: POLARIS.md and SUMMARY.md are exact duplicates (${polarisRel}, ${summaryRel})`,
+            });
+        }
+        else if (similarity >= similarityThreshold) {
+            findings.push({
+                severity: "WARN",
+                message: `Route ${relDir || "."}: POLARIS.md and SUMMARY.md normalized similarity ${similarity.toFixed(2)} exceeds threshold ${similarityThreshold} (${polarisRel}, ${summaryRel})`,
+            });
+        }
     }
     if (findings.length === 0) {
         return { dir: relDir, polarisFile: polarisRel, status: "OK", findings: [] };
@@ -302,9 +359,10 @@ function validateInstructions(opts = {}) {
         });
         dirsToCheck = [".", ...dirs];
     }
+    const threshold = opts.similarityThreshold ?? DEFAULT_PAIRWISE_DRIFT_THRESHOLD;
     const results = [];
     for (const relDir of dirsToCheck) {
-        const result = validateDir(relDir, repoRoot, allRoutes);
+        const result = validateDir(relDir, repoRoot, allRoutes, threshold);
         // Upgrade MISSING → ERROR for required dirs
         if (result.status === "MISSING" && requiredDirs.includes(relDir)) {
             result.status = "ERROR";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",