@lsctech/polaris 0.5.11 → 0.5.12

package/dist/qc/providers/coderabbit.js

@@ -37,6 +37,8 @@ const FINDING_BOOKKEEPING_KEYS = [
     "findingId",
 ];
 const PROGRESS_SHAPE_KEYS = new Set(["event", "progress", "heartbeat", "complete", "review_context"]);
+const ERROR_TYPE_RATE_LIMIT = new Set(["rate_limit", "rate-limit", "ratelimit", "rate limit"]);
+const ERROR_TYPE_AUTH = new Set(["auth", "authentication", "unauthorized", "unauthorised", "forbidden"]);
 const PROGRESS_TYPE_VALUES = new Set([
     "progress",
     "status",
@@ -56,6 +58,14 @@ const PROGRESS_STATUS_VALUES = new Set([
     "ok",
     "success",
 ]);
+const TERMINAL_COMPLETE_STATUSES = new Set([
+    "review_completed",
+    "review_skipped",
+    "completed",
+    "complete",
+    "done",
+    "success",
+]);
 function hasFindingLocation(record) {
     return FINDING_LOCATION_KEYS.some((key) => record[key] !== undefined);
 }
@@ -112,6 +122,8 @@ function isProgressRecord(record) {
     return false;
 }
 function isActionableFinding(record) {
+    if (isErrorRecord(record))
+        return false;
     if (isProgressRecord(record))
         return false;
     return hasFindingLocation(record) || hasFindingContent(record);
@@ -124,6 +136,85 @@ function makeUnusableOutputError(message) {
     err.qcFailureReason = "unusable-output";
     return err;
 }
+function makeQcFailureError(reason, message) {
+    const err = new Error(message);
+    err.qcFailureReason = reason;
+    return err;
+}
+function isErrorRecord(record) {
+    if (record.type === "error")
+        return true;
+    if (typeof record.errorType === "string")
+        return true;
+    if (record.error === true || record.error === "true")
+        return true;
+    return false;
+}
+function errorTypeFromRecord(record) {
+    const fromType = typeof record.errorType === "string" ? record.errorType : undefined;
+    const fromMessage = typeof record.message === "string" ? record.message : undefined;
+    return fromType ?? fromMessage;
+}
+function classifyErrorType(record) {
+    const raw = errorTypeFromRecord(record);
+    const errorType = (raw ?? "").toString().toLowerCase().trim();
+    if (errorType === "")
+        return "unavailable-provider";
+    if (ERROR_TYPE_RATE_LIMIT.has(errorType))
+        return "rate-limited";
+    if (ERROR_TYPE_AUTH.has(errorType))
+        return "auth-failure";
+    if (errorType.includes("rate limit"))
+        return "rate-limited";
+    if (errorType.includes("auth"))
+        return "auth-failure";
+    if (errorType.includes("unauthorized"))
+        return "auth-failure";
+    if (errorType.includes("forbidden"))
+        return "auth-failure";
+    if (["timeout", "timed out"].includes(errorType))
+        return "timeout";
+    if (errorType.includes("not found") || errorType.includes("not_found"))
+        return "command-not-found";
+    if (errorType.includes("unavailable") || errorType.includes("api_error") || errorType.includes("apierror") || errorType.includes("server") || errorType.includes("network") || errorType.includes("connection") || errorType.includes("internal")) {
+        return "unavailable-provider";
+    }
+    return "unavailable-provider";
+}
+function getTerminalCompleteFindingsCount(record) {
+    if (record.findings !== undefined) {
+        if (Array.isArray(record.findings)) {
+            return record.findings.length;
+        }
+        const count = typeof record.findings === "number" ? record.findings : Number(record.findings);
+        if (Number.isFinite(count))
+            return count;
+    }
+    const summary = record.summary;
+    if (summary && typeof summary === "object") {
+        const summaryRecord = summary;
+        if (summaryRecord.total !== undefined) {
+            const count = Number(summaryRecord.total);
+            if (Number.isFinite(count))
+                return count;
+        }
+        if (summaryRecord.issues !== undefined) {
+            const count = Number(summaryRecord.issues);
+            if (Number.isFinite(count))
+                return count;
+        }
+    }
+    return undefined;
+}
+function isTerminalCompleteNoFindings(record) {
+    if (record.type !== "complete")
+        return false;
+    const status = typeof record.status === "string" ? record.status.trim().toLowerCase() : "";
+    if (!TERMINAL_COMPLETE_STATUSES.has(status))
+        return false;
+    const count = getTerminalCompleteFindingsCount(record);
+    return count === undefined || count === 0;
+}
 function buildRange(raw) {
     const startLine = coerceNumber(raw.startLine ?? raw.line) ?? 1;
     const endLine = coerceNumber(raw.endLine);
@@ -144,14 +235,27 @@ function parseFindingsFromPayload(payload) {
         return [];
     }
     const record = payload;
-    if (Array.isArray(record.findings)) {
-        return record.findings.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
-    }
-    if (Array.isArray(record.issues)) {
-        return record.issues.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
+    if (isErrorRecord(record)) {
+        throw makeQcFailureError(classifyErrorType(record), `CodeRabbit provider returned an error: ${record.message ?? record.errorType ?? "unknown"}`);
     }
-    if (Array.isArray(record.results)) {
-        return record.results.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
+    const arrays = [record.findings, record.issues, record.results];
+    for (const arr of arrays) {
+        if (Array.isArray(arr)) {
+            const findings = [];
+            for (const item of arr) {
+                if (typeof item !== "object" || item === null) {
+                    continue;
+                }
+                const itemRecord = item;
+                if (isErrorRecord(itemRecord)) {
+                    throw makeQcFailureError(classifyErrorType(itemRecord), `CodeRabbit provider returned an error in findings array: ${itemRecord.message ?? itemRecord.errorType ?? "unknown"}`);
+                }
+                if (isActionableFinding(itemRecord)) {
+                    findings.push(item);
+                }
+            }
+            return findings;
+        }
     }
     // Single finding wrapped in an object
     if (isActionableFinding(record)) {
@@ -172,6 +276,9 @@ function parseReport(output, format, parser) {
         const findings = parseFindingsFromPayload(data);
         const record = data;
         if (findings.length === 0) {
+            if (isTerminalCompleteNoFindings(record)) {
+                return { findings: [] };
+            }
             if (isProgressRecord(record)) {
                 throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
             }
@@ -198,7 +305,19 @@ function parseReport(output, format, parser) {
         try {
             const parsed = JSON.parse(text);
             if (Array.isArray(parsed)) {
-                const findings = parsed.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
+                const findings = [];
+                for (const item of parsed) {
+                    if (typeof item !== "object" || item === null) {
+                        continue;
+                    }
+                    const itemRecord = item;
+                    if (isErrorRecord(itemRecord)) {
+                        throw makeQcFailureError(classifyErrorType(itemRecord), `CodeRabbit provider returned an error in JSON array: ${itemRecord.message ?? itemRecord.errorType ?? "unknown"}`);
+                    }
+                    if (isActionableFinding(itemRecord)) {
+                        findings.push(item);
+                    }
+                }
                 if (findings.length === 0 && parsed.length > 0) {
                     const unusableCount = parsed.filter((item) => typeof item === "object" && item !== null && isUnusableFindingRecord(item)).length;
                     if (unusableCount > 0) {
@@ -210,6 +329,9 @@ function parseReport(output, format, parser) {
             const findings = parseFindingsFromPayload(parsed);
             if (findings.length === 0) {
                 const parsedRecord = parsed;
+                if (isTerminalCompleteNoFindings(parsedRecord)) {
+                    return { findings: [] };
+                }
                 if (isProgressRecord(parsedRecord)) {
                     throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
                 }
@@ -260,9 +382,12 @@ function parseReport(output, format, parser) {
                 continue;
             }
             const record = parsed;
-            if (record.type === "complete" && record.status === "review_skipped") {
+            if (isTerminalCompleteNoFindings(record)) {
                 sawExplicitSkip = true;
             }
+            if (isErrorRecord(record)) {
+                throw makeQcFailureError(classifyErrorType(record), `CodeRabbit provider returned an error in JSONL: ${record.message ?? record.errorType ?? "unknown"}`);
+            }
             if (isProgressRecord(record)) {
                 progressLineCount++;
                 continue;
@@ -274,7 +399,10 @@ function parseReport(output, format, parser) {
                 unusableLineCount++;
             }
         }
-        catch {
+        catch (err) {
+            if (typeof err === "object" && err !== null && "qcFailureReason" in err) {
+                throw err;
+            }
             // Ignore unparseable lines.
         }
     }

package/dist/qc/repair-loop.js

@@ -19,10 +19,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_REPAIR_DISPATCH_TIMEOUT_MS = exports.DEFAULT_MAX_REPAIR_ROUNDS = void 0;
 exports.partitionRepairPackets = partitionRepairPackets;
 exports.initRepairLoopState = initRepairLoopState;
+exports.getQcResolutionArtifactPath = getQcResolutionArtifactPath;
+exports.resolveQcResolutionFindings = resolveQcResolutionFindings;
+exports.getResolverIdentity = getResolverIdentity;
+exports.isValidQcResolutionArtifact = isValidQcResolutionArtifact;
+exports.readQcResolutionArtifact = readQcResolutionArtifact;
+exports.writeQcResolutionArtifact = writeQcResolutionArtifact;
 exports.runQcRepairLoop = runQcRepairLoop;
 const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
 const node_path_1 = require("node:path");
 const repair_packets_js_1 = require("./repair-packets.js");
+const types_js_1 = require("./types.js");
 const orchestration_js_1 = require("./orchestration.js");
 const store_js_1 = require("../cluster-state/store.js");
 // ── Constants ─────────────────────────────────────────────────────────────────
@@ -189,6 +197,127 @@ function initRepairLoopState(opts) {
         updated_at: now,
     };
 }
+// ── Operator resolution artifact helpers ──────────────────────────────────────
+/** Path for the operator-written resolution artifact for a repair round. */
+function getQcResolutionArtifactPath(clusterId, round, repoRoot) {
+    return (0, node_path_1.join)((0, repair_packets_js_1.getRepairRoundDir)(clusterId, round, repoRoot), "resolution.json");
+}
+/** Resolve the finding IDs covered by a resolution artifact. */
+function resolveQcResolutionFindings(manifest, explicitFindings) {
+    const manifestFindings = [
+        ...new Set(manifest.packets.flatMap((p) => p.findingIds)),
+    ].sort();
+    if (!explicitFindings || explicitFindings.length === 0) {
+        return manifestFindings;
+    }
+    const allowed = new Set(manifestFindings);
+    const unknown = explicitFindings.filter((id) => !allowed.has(id));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown finding IDs: ${unknown.join(", ")}. Expected one of: ${manifestFindings.join(", ") || "none"}`);
+    }
+    return [...new Set(explicitFindings)].sort();
+}
+/** Determine the resolver identity from git config or the default operator. */
+function getResolverIdentity(repoRoot) {
+    try {
+        const name = (0, node_child_process_1.execFileSync)("git", ["config", "user.name"], {
+            cwd: repoRoot || process.cwd(),
+            encoding: "utf-8",
+        }).trim();
+        return name || "lsctech";
+    }
+    catch {
+        return "lsctech";
+    }
+}
+const QC_RESOLUTION_OUTCOME_SET = new Set(types_js_1.QC_RESOLUTION_OUTCOMES);
+/** Validate a resolution artifact object. */
+function isValidQcResolutionArtifact(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    if (typeof v.schemaVersion !== "string")
+        return false;
+    if (typeof v.clusterId !== "string")
+        return false;
+    if (typeof v.round !== "number")
+        return false;
+    if (typeof v.resolvedAt !== "string")
+        return false;
+    if (typeof v.resolver !== "string" || v.resolver === "")
+        return false;
+    if (typeof v.resolvedOutcome !== "string" ||
+        !QC_RESOLUTION_OUTCOME_SET.has(v.resolvedOutcome)) {
+        return false;
+    }
+    if (typeof v.reason !== "string" || v.reason.trim() === "")
+        return false;
+    if (!Array.isArray(v.findings) ||
+        v.findings.length === 0 ||
+        !v.findings.every((f) => typeof f === "string")) {
+        return false;
+    }
+    return true;
+}
+/** Read and validate a resolution artifact, if it exists. */
+function readQcResolutionArtifact(clusterId, round, repoRoot) {
+    const artifactPath = getQcResolutionArtifactPath(clusterId, round, repoRoot);
+    try {
+        const data = (0, node_fs_1.readFileSync)(artifactPath, "utf-8");
+        const parsed = JSON.parse(data);
+        if (isValidQcResolutionArtifact(parsed)) {
+            // Verify identity matches expected clusterId and round
+            if (parsed.clusterId !== clusterId || parsed.round !== round) {
+                return null;
+            }
+            return parsed;
+        }
+        return null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        if (error instanceof SyntaxError) {
+            return null;
+        }
+        throw error;
+    }
+}
+/** Write a resolution artifact atomically and return its absolute path. */
+function writeQcResolutionArtifact(options) {
+    const { clusterId, round, resolver, resolvedOutcome, reason, findings, repoRoot, } = options;
+    const artifactPath = getQcResolutionArtifactPath(clusterId, round, repoRoot);
+    const dir = (0, node_path_1.dirname)(artifactPath);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const artifact = {
+        schemaVersion: "1.0",
+        clusterId,
+        round,
+        resolvedAt: new Date().toISOString(),
+        resolver,
+        resolvedOutcome,
+        reason,
+        findings,
+    };
+    const tempPath = `${artifactPath}.tmp.${process.pid}.${Date.now()}.${Math.random()
+        .toString(36)
+        .slice(2, 8)}`;
+    try {
+        (0, node_fs_1.writeFileSync)(tempPath, JSON.stringify(artifact, null, 2), "utf-8");
+        (0, node_fs_1.renameSync)(tempPath, artifactPath);
+    }
+    catch (error) {
+        try {
+            (0, node_fs_1.unlinkSync)(tempPath);
+        }
+        catch {
+            // Ignore cleanup failure.
+        }
+        throw error;
+    }
+    return artifactPath;
+}
 // ── Main repair loop ───────────────────────────────────────────────────────────
 /**
  * Run the bounded QC repair loop.
@@ -293,10 +422,21 @@ async function runQcRepairLoop(options) {
         else {
             const existingManifestPath = loopState.manifest_path ??
                 (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "qc", "repair-rounds", String(round), "repair-packets.json");
+            // Synchronize manifest packet statuses with the persisted loop state.
+            const completedSet = new Set(loopState.completed_packet_ids);
+            for (const packet of manifest.packets) {
+                if (completedSet.has(packet.packetId)) {
+                    packet.status = "completed";
+                }
+            }
+            (0, repair_packets_js_1.writeRepairPacketManifest)(manifest, repoRoot);
             loopState = {
                 ...loopState,
                 current_round: round,
                 manifest_path: existingManifestPath,
+                pending_packet_ids: manifest.packets
+                    .filter((p) => p.status === "pending" && !completedSet.has(p.packetId))
+                    .map((p) => p.packetId),
                 updated_at: new Date().toISOString(),
             };
             onStateUpdate?.(loopState);
@@ -367,10 +507,16 @@ async function runQcRepairLoop(options) {
             const result = await dispatchRepairWorkerWithTimeout(dispatchRepairWorker, pkt, round, manifest, repairDispatchTimeoutMs, telemetryFile, runId, clusterId);
             allWorkerResults.push(result);
         }
-        // Record completed packet IDs.
+        // Record completed packet IDs and update manifest statuses.
         const completedIds = allWorkerResults
             .filter((r) => r.status !== "skipped")
             .map((r) => r.packetId);
+        for (const packet of manifest.packets) {
+            if (completedIds.includes(packet.packetId)) {
+                packet.status = "completed";
+            }
+        }
+        (0, repair_packets_js_1.writeRepairPacketManifest)(manifest, repoRoot);
         loopState = {
             ...loopState,
             completed_packet_ids: [...loopState.completed_packet_ids, ...completedIds],

package/dist/qc/repair-packets.js

@@ -78,6 +78,16 @@ function subsystemFromFilePath(filePath) {
     const lastSlash = filePath.lastIndexOf("/");
     return lastSlash === -1 ? "root" : filePath.slice(0, lastSlash);
 }
+function deriveSourceQcRunId(finding, fallbackRunId) {
+    // Some findingId formats encode the source QC run as `<provider>-<index>-<runId>`
+    // (e.g. coderabbit-1-1783818427443). Prefer that provenance over the result
+    // run ID so packet sourceQcRunIds match the runs that emitted the findings.
+    const match = finding.findingId.match(/^(.+?)-(\d+)-(\d+)$/);
+    if (match) {
+        return `${match[1]}-${match[3]}`;
+    }
+    return fallbackRunId;
+}
 function enrichFinding(finding, config, sourceQcRunId) {
     return {
         ...finding,
@@ -85,7 +95,7 @@ function enrichFinding(finding, config, sourceQcRunId) {
         risk: riskLevel(finding),
         confidenceBand: confidenceBand(finding),
         subsystem: subsystemFromFilePath(finding.filePath),
-        sourceQcRunId,
+        sourceQcRunId: deriveSourceQcRunId(finding, sourceQcRunId),
     };
 }
 /**
@@ -213,6 +223,8 @@ function buildPacket(group, index, clusterId, round, allRunIds, validationComman
     const packetId = `pkt-${clusterId}-r${round}-${String(index).padStart(3, "0")}`;
     const findingIds = group.map((f) => f.findingId).sort();
     const sourceRunIds = [...new Set(group.map((f) => f.sourceQcRunId))].sort();
+    // Preserve the artifact run ID while also capturing the finding-level source run.
+    const combinedSourceRunIds = [...new Set([...allRunIds, ...sourceRunIds])].sort();
     const severityFloor = group.reduce((acc, f) => (0, severity_js_1.maxSeverity)(acc, f.severity), "info");
     const categories = [...new Set(group.map((f) => f.category).filter(Boolean))].sort();
     const filePaths = group.map((f) => f.filePath).filter((f) => Boolean(f));
@@ -230,7 +242,7 @@ function buildPacket(group, index, clusterId, round, allRunIds, validationComman
         packetId,
         round,
         clusterId,
-        sourceQcRunIds: sourceRunIds.length > 0 ? sourceRunIds : allRunIds,
+        sourceQcRunIds: combinedSourceRunIds,
         findingIds,
         severityFloor,
         rootCauseHint,
@@ -346,12 +358,13 @@ function compileRepairPackets(input) {
         packets.push(buildPacket(group, packets.length, clusterId, round, allRunIds, validationCommands, compiledAt));
     }
     const finalPackets = assignParallelGroups(packets);
+    const manifestSourceRunIds = [...new Set(finalPackets.flatMap((p) => p.sourceQcRunIds))].sort();
     const manifest = {
         schemaVersion: "1.0",
         clusterId,
         round,
         compiledAt,
-        sourceQcRunIds: allRunIds,
+        sourceQcRunIds: manifestSourceRunIds.length > 0 ? manifestSourceRunIds : allRunIds,
         packets: finalPackets,
     };
     const manifestPath = getRepairPacketManifestPath(clusterId, round, repoRoot);

package/dist/qc/routing.js

@@ -12,6 +12,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.decideRepairRouting = decideRepairRouting;
 const security_category_js_1 = require("./security-category.js");
 const severity_js_1 = require("./severity.js");
+function isStateRepairCategory(category) {
+    return category === "state-repair";
+}
 function getBlockThreshold(config, context) {
     const route = context.routeName ? config.routes?.[context.routeName] : undefined;
     return route?.blockThreshold ?? config.severityThresholds?.block ?? "high";
@@ -34,6 +37,9 @@ function decideRepairRouting(finding, config, autofixEligible, context = {}) {
     if ((0, security_category_js_1.isSecurityCategory)(finding.category)) {
         return "operator-review";
     }
+    if (isStateRepairCategory(finding.category)) {
+        return "operator-review";
+    }
     const attribution = finding.attribution;
     const clearAttribution = attribution.confidence === "high" || attribution.confidence === "medium";
     if (autofixEligible && clearAttribution && attribution.childId) {

package/dist/qc/types.js

@@ -7,3 +7,6 @@
  * shapes so that Polaris can support multiple QC backends without vendor lock-in.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.QC_RESOLUTION_OUTCOMES = void 0;
+/** Allowed outcomes for an operator resolution artifact. */
+exports.QC_RESOLUTION_OUTCOMES = ["pass", "no-repairable"];

package/dist/tracker/local-graph.js

@@ -15,6 +15,7 @@ const migration_js_1 = require("./migration.js");
  */
 class LocalGraph {
     graph;
+    orderingDependenciesMerged = false;
     constructor(graph) {
         this.graph = graph;
     }
@@ -54,19 +55,76 @@ class LocalGraph {
     }
     /**
      * Persists the graph to `.polaris/clusters/{clusterId}/clusters.json`.
-     * Creates the directory if it does not exist.
+     * Children are sorted topologically before writing so the saved cluster
+     * definition reflects dependency order.
      *
      * @param clusterId The cluster ID to use as the directory name (e.g., "POL-198").
      * @param repoRoot The root directory of the repository.
      * @returns The absolute path of the written file.
      */
     async save(clusterId, repoRoot = process.cwd()) {
+        this.mergeOrderingDependencies();
+        const persistedGraph = {
+            ...this.graph,
+            clusters: Object.fromEntries(Object.entries(this.graph.clusters).map(([id, cluster]) => [
+                id,
+                Array.isArray(cluster.children) && cluster.children.length > 1
+                    ? { ...cluster, children: this.topoSortChildren(cluster.children) }
+                    : cluster,
+            ])),
+        };
         const dir = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId);
         await (0, promises_1.mkdir)(dir, { recursive: true });
         const filePath = node_path_1.default.join(dir, "clusters.json");
-        await (0, promises_1.writeFile)(filePath, JSON.stringify(this.graph, null, 2), "utf-8");
+        await (0, promises_1.writeFile)(filePath, JSON.stringify(persistedGraph, null, 2), "utf-8");
         return filePath;
     }
+    /**
+     * Sort a list of children topologically using the graph dependencies.
+     * Children with no in-cluster dependencies come first; if a cycle exists,
+     * the remaining nodes are appended in their original order.
+     */
+    topoSortChildren(children) {
+        const childSet = new Set(children);
+        const inDegree = new Map();
+        const dependents = new Map();
+        for (const child of children) {
+            inDegree.set(child, 0);
+            dependents.set(child, []);
+        }
+        for (const child of children) {
+            for (const dep of this.getDependencies(child)) {
+                if (!childSet.has(dep))
+                    continue;
+                inDegree.set(child, (inDegree.get(child) ?? 0) + 1);
+                dependents.get(dep).push(child);
+            }
+        }
+        const queue = [];
+        for (const [child, deg] of inDegree) {
+            if (deg === 0)
+                queue.push(child);
+        }
+        const sorted = [];
+        while (queue.length > 0) {
+            const node = queue.shift();
+            sorted.push(node);
+            for (const dependent of dependents.get(node) ?? []) {
+                const newDeg = (inDegree.get(dependent) ?? 1) - 1;
+                inDegree.set(dependent, newDeg);
+                if (newDeg === 0)
+                    queue.push(dependent);
+            }
+        }
+        if (sorted.length < children.length) {
+            const sortedSet = new Set(sorted);
+            for (const child of children) {
+                if (!sortedSet.has(child))
+                    sorted.push(child);
+            }
+        }
+        return sorted;
+    }
     /**
      * Returns the full v2 execution graph.
      */
@@ -87,12 +145,57 @@ class LocalGraph {
         return this.graph.nodes[id];
     }
     /**
-     * Returns the dependencies for a given node.
+     * Returns the dependencies for a given node, merging any dependencies declared
+     * in the node's `## Ordering` body section.
      * @param id The ID of the node to get dependencies for.
      * @returns An array of node IDs that the given node is blocked by.
      */
     getDependencies(id) {
+        this.mergeOrderingDependencies();
         return this.graph.dependencies[id] ?? [];
     }
+    /**
+     * Extracts issue IDs from the `## Ordering` section of a node body.
+     *
+     * Only lines that explicitly declare ordering ("depends on" or "after" / "sequence after")
+     * contribute, and "before or after" clauses are ignored because they are not strict.
+     */
+    extractOrderingIds(body) {
+        const sectionMatch = body.match(/##\s*Ordering\b([\s\S]*?)(?:\n##\s|\n\n(?=\n##\s)|$)/i);
+        if (!sectionMatch)
+            return [];
+        const section = sectionMatch[1];
+        const cleaned = section.replace(/before\s+or\s+after\s*\[[^\]]*\]/gi, "");
+        const ids = new Set();
+        const re = /(?:depends\s+on|after)\s*\[?\s*(\w+-\d+)\b/gi;
+        for (const line of cleaned.split("\n")) {
+            if (!/^\s*[-*]\s/.test(line))
+                continue;
+            for (const match of line.matchAll(re)) {
+                ids.add(match[1]);
+            }
+        }
+        return [...ids];
+    }
+    /**
+     * Merges dependencies declared in node body `## Ordering` sections into the
+     * graph's explicit dependency map. This is idempotent for the loaded graph.
+     */
+    mergeOrderingDependencies() {
+        if (this.orderingDependenciesMerged)
+            return;
+        for (const node of Object.values(this.graph.nodes)) {
+            const orderingIds = this.extractOrderingIds(node.body ?? "");
+            if (orderingIds.length === 0)
+                continue;
+            const existing = new Set(this.graph.dependencies[node.id] ?? []);
+            for (const dep of orderingIds) {
+                if (dep !== node.id)
+                    existing.add(dep);
+            }
+            this.graph.dependencies[node.id] = [...existing].sort();
+        }
+        this.orderingDependenciesMerged = true;
+    }
 }
 exports.LocalGraph = LocalGraph;

package/package.json

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