@lsctech/polaris 0.1.3 → 0.2.1

package/dist/governance/authority-risk.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeAuthorityRisk = computeAuthorityRisk;
+const HIGH_AUTHORITY_PATH_SEGMENTS = [
+    "doctrine/active",
+    "architecture",
+    "decisions",
+    "specs/active",
+];
+const MEDIUM_AUTHORITY_PATH_SEGMENTS = [
+    "doctrine/candidate",
+];
+const HIGH_AUTHORITY_CLASSIFICATIONS = new Set([
+    "architecture",
+    "decision",
+    "spec-active",
+]);
+const MEDIUM_AUTHORITY_CLASSIFICATIONS = new Set([
+    "doctrine-candidate",
+]);
+function containsPathSegment(normalized, segment) {
+    return (normalized === segment ||
+        normalized.startsWith(segment + "/") ||
+        normalized.endsWith("/" + segment) ||
+        normalized.includes("/" + segment + "/"));
+}
+function riskFromPath(destinationPath) {
+    const normalized = destinationPath.replace(/\\/g, "/");
+    for (const seg of HIGH_AUTHORITY_PATH_SEGMENTS) {
+        if (containsPathSegment(normalized, seg))
+            return "high";
+    }
+    for (const seg of MEDIUM_AUTHORITY_PATH_SEGMENTS) {
+        if (containsPathSegment(normalized, seg))
+            return "medium";
+    }
+    return null;
+}
+function riskFromClassification(classification) {
+    if (HIGH_AUTHORITY_CLASSIFICATIONS.has(classification))
+        return "high";
+    if (MEDIUM_AUTHORITY_CLASSIFICATIONS.has(classification))
+        return "medium";
+    return "low";
+}
+/**
+ * Determine the authority risk of placing a document at the given destination.
+ * Path wins over classification when they disagree, because authority is
+ * determined by where an artifact lands, not what it was classified as.
+ */
+function computeAuthorityRisk(classification, destinationPath) {
+    const pathRisk = riskFromPath(destinationPath);
+    if (pathRisk !== null)
+        return pathRisk;
+    return riskFromClassification(classification);
+}

package/dist/governance/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyReviewDecisions = exports.readReviewQueue = exports.writeReviewQueue = exports.buildReviewPacket = exports.route = exports.computeAuthorityRisk = void 0;
+var authority_risk_js_1 = require("./authority-risk.js");
+Object.defineProperty(exports, "computeAuthorityRisk", { enumerable: true, get: function () { return authority_risk_js_1.computeAuthorityRisk; } });
+var routing_js_1 = require("./routing.js");
+Object.defineProperty(exports, "route", { enumerable: true, get: function () { return routing_js_1.route; } });
+var review_packet_js_1 = require("./review-packet.js");
+Object.defineProperty(exports, "buildReviewPacket", { enumerable: true, get: function () { return review_packet_js_1.buildReviewPacket; } });
+Object.defineProperty(exports, "writeReviewQueue", { enumerable: true, get: function () { return review_packet_js_1.writeReviewQueue; } });
+Object.defineProperty(exports, "readReviewQueue", { enumerable: true, get: function () { return review_packet_js_1.readReviewQueue; } });
+Object.defineProperty(exports, "applyReviewDecisions", { enumerable: true, get: function () { return review_packet_js_1.applyReviewDecisions; } });

package/dist/governance/review-packet.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildReviewPacket = buildReviewPacket;
+exports.writeReviewQueue = writeReviewQueue;
+exports.readReviewQueue = readReviewQueue;
+exports.applyReviewDecisions = applyReviewDecisions;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function buildReviewPacket(result, sourcePath, proposedDestination, conflicts, outcomeReason, recommendation) {
+    return {
+        sourcePath,
+        proposedDestination,
+        classificationConfidence: result.classificationConfidence,
+        destinationCertainty: result.destinationCertainty,
+        authorityRisk: result.authorityRisk,
+        reasoning: result.reasoning,
+        conflicts,
+        recommendation,
+        outcomeReason,
+    };
+}
+const RISK_ORDER = { high: 0, medium: 1, low: 2 };
+function renderPacketMarkdown(p) {
+    const lines = [
+        `## ${p.reviewDecision ? `✓ ${p.reviewDecision}` : "review-required"} · ${p.authorityRisk.toUpperCase()} authority risk`,
+        ``,
+        `**Source:** ${p.sourcePath}`,
+        `**Proposed destination:** ${p.proposedDestination}`,
+        `**Classification confidence:** ${p.classificationConfidence.toFixed(2)}`,
+        `**Destination certainty:** ${p.destinationCertainty.toFixed(2)}`,
+        `**Outcome reason:** ${p.outcomeReason}`,
+        ``,
+        `**Reasoning:**`,
+        ...p.reasoning.map((r) => `- ${r}`),
+        ``,
+        `**Conflicts:** ${p.conflicts.length === 0 ? "none detected" : p.conflicts.join(", ")}`,
+        ``,
+        `**Recommendation:** ${p.recommendation}`,
+        `**Review decision:** ${p.reviewDecision ?? "← set this to \`approve\`, \`reject\`, or \`defer\`"}`,
+    ];
+    return lines.join("\n");
+}
+function groupAndSort(packets) {
+    return [...packets].sort((a, b) => {
+        const riskCompare = RISK_ORDER[a.authorityRisk] - RISK_ORDER[b.authorityRisk];
+        if (riskCompare !== 0)
+            return riskCompare;
+        return a.sourcePath.localeCompare(b.sourcePath);
+    });
+}
+/**
+ * Write _review-queue.json (canonical) and _review-queue.md (display-only) to outputDir.
+ * Markdown is regenerated from JSON — never parse markdown to recover decisions.
+ */
+function writeReviewQueue(packets, runId, outputDir) {
+    (0, node_fs_1.mkdirSync)(outputDir, { recursive: true });
+    const queueFile = {
+        generated_at: new Date().toISOString(),
+        run_id: runId,
+        packets,
+    };
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, "_review-queue.json"), JSON.stringify(queueFile, null, 2) + "\n", "utf-8");
+    const sorted = groupAndSort(packets);
+    const sections = sorted.map(renderPacketMarkdown).join("\n\n---\n\n");
+    const md = [
+        `# Polaris Review Queue`,
+        ``,
+        `**Run ID:** ${runId}`,
+        `**Generated:** ${queueFile.generated_at}`,
+        `**Pending review:** ${packets.length} document(s)`,
+        ``,
+        `> Markdown is display-only. Edit \`_review-queue.json\` to set \`reviewDecision\` fields.`,
+        `> Rerun \`polaris docs ingest\` to apply decisions.`,
+        ``,
+        `---`,
+        ``,
+        sections,
+    ].join("\n");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, "_review-queue.md"), md, "utf-8");
+}
+/**
+ * Read review queue from JSON. Returns empty array if no queue file exists.
+ * Never reads markdown.
+ */
+function readReviewQueue(outputDir) {
+    const jsonPath = (0, node_path_1.join)(outputDir, "_review-queue.json");
+    if (!(0, node_fs_1.existsSync)(jsonPath))
+        return [];
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(jsonPath, "utf-8"));
+        return Array.isArray(parsed.packets) ? parsed.packets : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Merge user decisions from a reviewed queue into a set of pending packets.
+ * Matches by sourcePath. Unmatched pending packets are returned unchanged.
+ */
+function applyReviewDecisions(pending, reviewed) {
+    const bySource = new Map(reviewed.map((r) => [r.sourcePath, r]));
+    return pending.map((p) => {
+        const decision = bySource.get(p.sourcePath);
+        if (!decision?.reviewDecision)
+            return p;
+        return {
+            ...p,
+            reviewDecision: decision.reviewDecision,
+            reviewedAt: decision.reviewedAt,
+            reviewedBy: decision.reviewedBy,
+        };
+    });
+}

package/dist/governance/routing.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.route = route;
+function buildMinimalPacket(result, outcomeReason, recommendation) {
+    return {
+        sourcePath: "",
+        proposedDestination: "",
+        classificationConfidence: result.classificationConfidence,
+        destinationCertainty: result.destinationCertainty,
+        authorityRisk: result.authorityRisk,
+        reasoning: result.reasoning,
+        conflicts: [],
+        recommendation,
+        outcomeReason,
+    };
+}
+/**
+ * Pure routing function — no I/O.
+ * Implements the five-row governance decision table:
+ *
+ * Row 1: high conf + high dest + low risk  → auto-route
+ * Row 2: high conf + high dest + med risk  → candidate
+ * Row 3: high conf + low dest  + med risk  → review-required
+ * Row 4: high conf + any dest  + high risk → review-required
+ * Row 5: low conf  + any                   → review-required
+ *
+ * sourcePath and proposedDestination in the returned packet are empty strings;
+ * the caller fills them in after routing.
+ */
+function route(result, thresholds) {
+    const highConf = result.classificationConfidence >= thresholds.confidence;
+    const highDest = result.destinationCertainty >= thresholds.destinationCertainty;
+    // Row 1
+    if (highConf && highDest && result.authorityRisk === "low") {
+        return { outcome: "auto-route" };
+    }
+    // Row 2
+    if (highConf && highDest && result.authorityRisk === "medium") {
+        return {
+            outcome: "candidate",
+            reviewPacket: buildMinimalPacket(result, "Routed to candidate: classification and destination certainty are high, but canonical approval is still required.", "approve"),
+        };
+    }
+    // Row 3
+    if (highConf && !highDest && result.authorityRisk === "medium") {
+        return {
+            outcome: "review-required",
+            reviewPacket: buildMinimalPacket(result, "Routed to review-required: destination certainty is below threshold for medium authority risk placement.", "defer"),
+        };
+    }
+    // Row 4
+    if (highConf && result.authorityRisk === "high") {
+        return {
+            outcome: "review-required",
+            reviewPacket: buildMinimalPacket(result, "Routed to review-required: high authority risk destination requires user approval.", "defer"),
+        };
+    }
+    // Row 5
+    return {
+        outcome: "review-required",
+        reviewPacket: buildMinimalPacket(result, `Routed to review-required: classification confidence ${result.classificationConfidence.toFixed(2)} is below threshold ${thresholds.confidence}.`, "defer"),
+    };
+}

package/dist/governance/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Shared types for document governance decisions: authority risk assessment, routing,
+ * and review packets. Intentionally decoupled from Smart Docs vocabulary so this module
+ * can be reused by any Polaris workflow that requires authority-boundary enforcement.
+ * The `classification` field is opaque (string) — callers define their own vocabulary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/smartdocs-engine/index.js

@@ -6,6 +6,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const commander_1 = require("commander");
 const ingest_js_1 = require("./ingest.js");
+const review_js_1 = require("./review.js");
 const migrate_js_1 = require("./migrate.js");
 const seed_instructions_js_1 = require("./seed-instructions.js");
 const validate_instructions_js_1 = require("./validate-instructions.js");
@@ -45,14 +46,25 @@ function createDocsCommand(options = {}) {
     docs
         .command("ingest [path]")
         .description("Classify and place docs into the smartdocs/ canonical authority structure")
-        .option("--file <path>", "Single file to ingest")
         .option("--batch <cluster-id>", "Cluster ID for bounded batch ingest (reads .polaris/docs-ingest/<cluster-id>.json)")
         .option("--cluster <id>", "Alias for --batch")
         .option("--files <paths...>", "Bounded batch file list")
         .option("--dry-run", "Classify and report without moving files")
         .option("--approve-authority", "Allow placement in high-authority docs areas")
+        .option("--file <path>", "Single file to ingest; also scopes --approve-authority to a single file path")
+        .option("--from-review-queue", "scope --approve-authority to items in the review queue")
+        .option("--decision-id <id>", "scope --approve-authority to a specific decision ID")
+        .option("--interactive", "pause and prompt for review decisions on each review-required document")
+        .option("--confidence-threshold <n>", "classification confidence threshold (0–1, default 0.75)", parseFloat)
+        .option("--destination-certainty-threshold <n>", "destination certainty threshold (0–1, default 0.70)", parseFloat)
         .option("-r, --repo-root <path>", "Repository root", defaultRepoRoot)
-        .action((pathArg, options) => {
+        .action(async (pathArg, opts) => {
+        if (opts.approveAuthority && !opts.file && !opts.fromReviewQueue && !opts.decisionId) {
+            console.error("error: --approve-authority requires an explicit scope: --file <path>, --from-review-queue, or --decision-id <id>");
+            process.exit(1);
+        }
+        // Alias opts to options for compatibility with existing code below
+        const options = opts;
         const clusterId = options.batch ?? options.cluster;
         // Validate clusterId
         if (clusterId && !/^[A-Za-z0-9_-]+$/.test(clusterId)) {
@@ -111,6 +123,9 @@ function createDocsCommand(options = {}) {
                 dryRun: options.dryRun,
                 clusterId,
                 approveAuthority: options.approveAuthority,
+                interactive: opts.interactive,
+                confidenceThreshold: opts.confidenceThreshold,
+                destinationCertaintyThreshold: opts.destinationCertaintyThreshold,
             });
             (0, ingest_js_1.printIngestResults)(results);
         }
@@ -119,6 +134,23 @@ function createDocsCommand(options = {}) {
             process.exit(1);
         }
     });
+    docs
+        .command("review")
+        .description("Interactively review pending governance decisions in the review queue")
+        .option("--queue <path>", "path to _review-queue.json (default: smartdocs/raw/_review-queue.json)")
+        .option("-r, --repo-root <path>", "Repository root", defaultRepoRoot)
+        .action(async (opts) => {
+        try {
+            const queueDir = opts.queue
+                ? (0, node_path_1.resolve)(opts.repoRoot, opts.queue).replace(/_review-queue\.json$/, "").replace(/\/$/, "")
+                : (0, node_path_1.resolve)(opts.repoRoot, "smartdocs", "raw");
+            await (0, review_js_1.runReviewSession)({ repoRoot: opts.repoRoot, queueDir });
+        }
+        catch (err) {
+            console.error(`polaris docs review: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     docs
         .command("migrate")
         .description("Find scattered markdown files, move them to smartdocs/raw/, and produce an ingest cluster list")

package/dist/smartdocs-engine/ingest.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SMART_DOCS_SCAFFOLD_DIRS = exports.CANONICAL_TARGET = void 0;
 exports.classifyDoc = classifyDoc;
+exports.classifyDocWithConfidence = classifyDocWithConfidence;
 exports.ensureDocsScaffold = ensureDocsScaffold;
 exports.ingestDocs = ingestDocs;
 exports.printIngestResults = printIngestResults;
@@ -13,6 +14,8 @@ const monotonic_timestamp_js_1 = require("../utils/monotonic-timestamp.js");
 const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
 const doctrine_js_1 = require("./doctrine.js");
 const summary_delta_js_1 = require("../cognition/summary-delta.js");
+const authority_risk_js_1 = require("../governance/authority-risk.js");
+const index_js_1 = require("../governance/index.js");
 exports.CANONICAL_TARGET = "smartdocs";
 const DOCS_INGEST_STATE_FILE = ".taskchain_artifacts/polaris-docs-ingest/current-state.json";
 const DOCS_INGEST_RUNS_DIR = ".taskchain_artifacts/polaris-docs-ingest/runs";
@@ -23,7 +26,7 @@ const TARGET_DIRS = {
     "spec-raw": `${exports.CANONICAL_TARGET}/raw`,
     "spec-active": `${exports.CANONICAL_TARGET}/specs/active`,
     "audit-finding": `${exports.CANONICAL_TARGET}/audits/findings`,
-    "doctrine-candidate": `${exports.CANONICAL_TARGET}/doctrine/active`,
+    "doctrine-candidate": `${exports.CANONICAL_TARGET}/doctrine/candidate`,
     architecture: `${exports.CANONICAL_TARGET}/architecture`,
     decision: `${exports.CANONICAL_TARGET}/decisions`,
     "deprecated-noise": `${exports.CANONICAL_TARGET}/runtime/generated`,
@@ -38,7 +41,6 @@ exports.SMART_DOCS_SCAFFOLD_DIRS = [
     `${exports.CANONICAL_TARGET}/doctrine/active`,
     `${exports.CANONICAL_TARGET}/doctrine/deprecated`,
 ];
-const APPROVAL_REQUIRED = new Set(["spec-active", "architecture", "decision"]);
 /**
  * Conflict detection uses subject-verb-keyword triples rather than bare
  * verb-keyword pairs. A conflict only fires when both the subject AND the
@@ -107,6 +109,87 @@ function classifyDoc(content, filePath = "") {
     }
     return "spec-raw";
 }
+const DOMAIN_KEYWORDS_RE = /\b(loop|map|finalize|config|cli|docs|doctrine|spec|audit)\b/i;
+function classifyDocWithConfidence(content, filePath) {
+    const classification = classifyDoc(content, filePath ?? "");
+    const reasoning = [];
+    // --- classificationConfidence ---
+    let classConf = 0.3;
+    const docType = frontMatterValue(content, "doc-type");
+    if (docType) {
+        classConf += 0.4;
+        reasoning.push(`Explicit frontmatter doc-type: ${docType}`);
+    }
+    const authority = frontMatterValue(content, "authority")?.toLowerCase();
+    const status = frontMatterValue(content, "status")?.toLowerCase();
+    const hasSupportingFm = authority || status;
+    if (hasSupportingFm) {
+        // check alignment: authority or status loosely matches classification
+        const classLower = classification.toLowerCase();
+        if ((authority && classLower.includes(authority)) ||
+            (status && classLower.includes(status))) {
+            classConf += 0.2;
+            reasoning.push(`Frontmatter authority/status aligns with classification`);
+        }
+    }
+    // Count independent keyword signals from classifyDoc logic
+    const lower = `${filePath ?? ""}\n${content}`.toLowerCase();
+    let keywordSignals = 0;
+    if (lower.includes("run report") || lower.includes("run-report"))
+        keywordSignals++;
+    if (lower.includes("runtime summary") || lower.includes("session summary"))
+        keywordSignals++;
+    if (lower.includes("audit finding") || lower.includes("vulnerability") || lower.includes("security audit"))
+        keywordSignals++;
+    if (lower.includes("doctrine") || lower.includes("must always") || lower.includes("never silently"))
+        keywordSignals++;
+    if (lower.includes("architecture decision record") || /^#\s*adr[:\s-]/im.test(content))
+        keywordSignals++;
+    if (lower.includes("architecture") || lower.includes("structural design"))
+        keywordSignals++;
+    if (lower.includes("active spec"))
+        keywordSignals++;
+    if (lower.includes("acceptance criteria") || lower.includes("implementation plan"))
+        keywordSignals++;
+    if (keywordSignals >= 2) {
+        classConf += 0.3;
+        reasoning.push(`Multiple (${keywordSignals}) independent keyword signals matched`);
+    }
+    else if (keywordSignals === 1) {
+        classConf += 0.1;
+        reasoning.push(`Single keyword signal matched`);
+    }
+    else {
+        reasoning.push(`Default spec-raw fallback with no signals`);
+    }
+    classConf = Math.min(classConf, 1.0);
+    // --- destinationCertainty ---
+    let destCert = 0.2;
+    const linkedMapArea = frontMatterValue(content, "linked-map-area");
+    if (linkedMapArea) {
+        destCert += 0.4;
+        reasoning.push(`Frontmatter linked-map-area: ${linkedMapArea}`);
+    }
+    if (filePath && DOMAIN_KEYWORDS_RE.test(filePath)) {
+        destCert += 0.2;
+        reasoning.push(`Domain keyword found in filename`);
+    }
+    const isDefaultFallback = classification === "spec-raw" && keywordSignals === 0 && !docType;
+    if (!isDefaultFallback) {
+        destCert += 0.2;
+        reasoning.push(`Classification is not default fallback`);
+    }
+    destCert = Math.min(destCert, 1.0);
+    const proposedDest = TARGET_DIRS[classification] ?? "";
+    const authorityRisk = (0, authority_risk_js_1.computeAuthorityRisk)(classification, proposedDest);
+    return {
+        classification,
+        classificationConfidence: classConf,
+        destinationCertainty: destCert,
+        authorityRisk,
+        reasoning,
+    };
+}
 function readCurrentState(repoRoot) {
     return readJson((0, node_path_1.resolve)(repoRoot, DOCS_INGEST_STATE_FILE), {});
 }
@@ -315,6 +398,9 @@ function ingestDocs(files, options) {
     const priorState = readCurrentState(repoRoot);
     const clusterId = options.clusterId ?? null;
     const runId = generateRunId(repoRoot);
+    const rawDir = (0, node_path_1.resolve)(repoRoot, exports.CANONICAL_TARGET, "raw");
+    // Read existing review queue to apply prior human decisions
+    const priorQueue = (0, index_js_1.readReviewQueue)(rawDir);
     // Emit run-start telemetry (STOP CONDITION if this write fails)
     emitRunStartTelemetry(repoRoot, runId, priorState.run_id ?? null);
     const telPath = docsIngestTelemetryPath(repoRoot, runId);
@@ -349,10 +435,6 @@ function ingestDocs(files, options) {
         if (!(0, node_fs_1.existsSync)(absSource))
             throw new Error(`polaris docs ingest: file not found: ${source}`);
         const content = (0, node_fs_1.readFileSync)(absSource, "utf-8");
-        const classification = classifyDoc(content, relSource);
-        if (APPROVAL_REQUIRED.has(classification) && !options.approveAuthority) {
-            throw new Error(`polaris docs ingest: ${classification} requires explicit approval; rerun with --approve-authority`);
-        }
         // Conflict detection against active doctrine (STOP CONDITION)
         const conflict = detectDoctrineConflict(content, repoRoot);
         if (conflict) {
@@ -365,8 +447,46 @@ function ingestDocs(files, options) {
             });
             throw new Error(`polaris docs ingest: conflict detected — ${conflict.detail}`);
         }
+        // ── Governance routing ────────────────────────────────────────────────
+        const classificationResult = classifyDocWithConfidence(content, relSource);
+        const docClassification = classificationResult.classification;
+        const thresholds = {
+            confidence: options.confidenceThreshold ?? 0.75,
+            destinationCertainty: options.destinationCertaintyThreshold ?? 0.70,
+        };
+        const routingDecision = (0, index_js_1.route)(classificationResult, thresholds);
+        const proposedDest = (0, node_path_1.relative)(repoRoot, (0, node_path_1.join)((0, node_path_1.resolve)(repoRoot, TARGET_DIRS[docClassification]), (0, node_path_1.basename)(absSource))).replace(/\\/g, "/");
+        // review-required: leave in raw/, emit packet, skip move
+        if (routingDecision.outcome === "review-required") {
+            const packet = {
+                ...routingDecision.reviewPacket,
+                sourcePath: relSource,
+                proposedDestination: proposedDest,
+                conflicts: [],
+            };
+            emitTelemetry(telPath, runId, {
+                event: "docs-ingest-review-required",
+                file: relSource,
+                classification: docClassification,
+                outcome_reason: packet.outcomeReason,
+                cluster_id: clusterId,
+            });
+            results.push({
+                sourcePath: relSource,
+                destinationPath: relSource,
+                classification: docClassification,
+                linkedMapArea: null,
+                runId,
+                dryRun: Boolean(options.dryRun),
+                nearestSummary: null,
+                summaryDeltaWarranted: false,
+                routingDecision: "review-required",
+                reviewPacket: packet,
+            });
+            continue;
+        }
         const { label: linkedMapArea, entry: linkedEntry } = deriveLinkedArea(content, routes);
-        const targetDir = (0, node_path_1.resolve)(repoRoot, TARGET_DIRS[classification]);
+        const targetDir = (0, node_path_1.resolve)(repoRoot, TARGET_DIRS[docClassification]);
         (0, node_fs_1.mkdirSync)(targetDir, { recursive: true });
         const rawDestination = (0, node_path_1.join)(targetDir, (0, node_path_1.basename)(absSource));
         const destination = (0, node_path_1.resolve)(rawDestination) === (0, node_path_1.resolve)(absSource)
@@ -379,7 +499,7 @@ function ingestDocs(files, options) {
         emitTelemetry(telPath, runId, {
             event: "docs-ingest-classified",
             file: relSource,
-            classification,
+            classification: docClassification,
             destination: relDestination,
             linked_map_area: linkedMapArea,
             cluster_id: clusterId,
@@ -390,7 +510,7 @@ function ingestDocs(files, options) {
             }
             const stampedContent = (0, doctrine_js_1.stampIngestFrontMatter)((0, node_fs_1.readFileSync)(destination, "utf-8"), {
                 originalPath: relSource,
-                classifiedAs: classification,
+                classifiedAs: docClassification,
                 ingestRunId: runId,
                 ingestClusterId: clusterId,
                 linkedMapArea,
@@ -399,11 +519,11 @@ function ingestDocs(files, options) {
             (0, node_fs_1.writeFileSync)(destination, stampedContent, "utf-8");
             updateMapEntry(repoRoot, destination, linkedEntry);
         }
-        if (classification === "doctrine-candidate" && !options.dryRun) {
+        if (docClassification === "doctrine-candidate" && !options.dryRun) {
             emitTelemetry(telPath, runId, {
                 event: "doc-auto-promoted",
                 file: relDestination,
-                classification,
+                classification: docClassification,
                 linked_map_area: linkedMapArea,
                 cluster_id: clusterId,
             });
@@ -411,7 +531,7 @@ function ingestDocs(files, options) {
         emitTelemetry(telPath, runId, {
             event: "docs-ingest",
             file: relSource,
-            classification,
+            classification: docClassification,
             destination: relDestination,
             linked_map_area: linkedMapArea,
             cluster_id: clusterId,
@@ -457,12 +577,16 @@ function ingestDocs(files, options) {
         results.push({
             sourcePath: relSource,
             destinationPath: relDestination,
-            classification,
+            classification: docClassification,
             linkedMapArea,
             runId,
             dryRun: Boolean(options.dryRun),
             nearestSummary,
             summaryDeltaWarranted: summaryDelta.updateWarranted,
+            routingDecision: routingDecision.outcome,
+            reviewPacket: routingDecision.reviewPacket
+                ? { ...routingDecision.reviewPacket, sourcePath: relSource, proposedDestination: relDestination, conflicts: [] }
+                : undefined,
         });
     }
     emitTelemetry(telPath, runId, {
@@ -470,6 +594,15 @@ function ingestDocs(files, options) {
         count: results.length,
         cluster_id: clusterId,
     });
+    // Write review queue if any review-required results exist
+    const reviewPackets = results
+        .filter(r => r.routingDecision === "review-required" && r.reviewPacket)
+        .map(r => r.reviewPacket);
+    if (reviewPackets.length > 0) {
+        // Apply any prior human decisions before writing
+        const mergedPackets = (0, index_js_1.applyReviewDecisions)(reviewPackets, priorQueue);
+        (0, index_js_1.writeReviewQueue)(mergedPackets, runId, rawDir);
+    }
     if (!options.dryRun) {
         writeDocsIngestState(repoRoot, {
             run_id: runId,

package/dist/smartdocs-engine/review.js

@@ -0,0 +1,149 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterUndecided = filterUndecided;
+exports.formatPacketCard = formatPacketCard;
+exports.runReviewSession = runReviewSession;
+const node_child_process_1 = require("node:child_process");
+const readline = __importStar(require("node:readline"));
+const node_path_1 = require("node:path");
+const index_js_1 = require("../governance/index.js");
+const ingest_js_1 = require("./ingest.js");
+function filterUndecided(packets) {
+    return packets.filter((p) => p.reviewDecision === undefined || p.reviewDecision === "defer");
+}
+function formatPacketCard(packet, index, total) {
+    const divider = "─".repeat(65);
+    return [
+        divider,
+        `[${index}/${total}] ${packet.sourcePath}`,
+        `  → ${packet.proposedDestination}`,
+        `  Authority risk:  ${packet.authorityRisk.toUpperCase()}`,
+        `  Recommendation:  ${packet.recommendation}`,
+        ``,
+        `[a]pprove  [r]eject  [d]efer  [s]kip  [q]uit`,
+        divider,
+    ].join("\n");
+}
+function defaultGetReviewedBy() {
+    try {
+        return (0, node_child_process_1.execSync)("git config user.name", { encoding: "utf-8" }).trim() || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function readSingleKey() {
+    return new Promise((resolve) => {
+        readline.emitKeypressEvents(process.stdin);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        const handler = (_str, key) => {
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(false);
+            process.stdin.removeListener("keypress", handler);
+            if (key?.ctrl && key.name === "c")
+                process.exit(0);
+            resolve(key?.name ?? _str ?? "");
+        };
+        process.stdin.on("keypress", handler);
+    });
+}
+async function runReviewSession(options) {
+    const { repoRoot, readKey, getReviewedBy = defaultGetReviewedBy, output = (msg) => process.stdout.write(msg + "\n"), } = options;
+    const queueDir = options.queueDir ?? (0, node_path_1.resolve)(repoRoot, "smartdocs", "raw");
+    const packets = (0, index_js_1.readReviewQueue)(queueDir);
+    if (packets.length === 0) {
+        output("No review queue found. Run polaris docs ingest first.");
+        return;
+    }
+    const undecided = filterUndecided(packets);
+    if (undecided.length === 0) {
+        output("Nothing to review. All decisions are final — run polaris docs ingest to apply.");
+        return;
+    }
+    let decided = 0;
+    for (let i = 0; i < undecided.length; i++) {
+        const packet = undecided[i];
+        output(formatPacketCard(packet, i + 1, undecided.length));
+        const key = readKey ? await readKey() : await readSingleKey();
+        if (key === "q") {
+            const remaining = undecided.length - decided;
+            output(`\nSession ended. ${decided} decision(s) saved, ${remaining} packet(s) still pending.`);
+            output("Run polaris docs review to continue.");
+            return;
+        }
+        if (key === "s") {
+            continue;
+        }
+        const decision = key === "a" ? "approve" :
+            key === "r" ? "reject" :
+                key === "d" ? "defer" :
+                    null;
+        if (!decision) {
+            output("Unrecognized key. Use [a], [r], [d], [s], or [q].");
+            i--;
+            continue;
+        }
+        const idx = packets.findIndex((p) => p.sourcePath === packet.sourcePath);
+        if (idx !== -1) {
+            packets[idx] = {
+                ...packets[idx],
+                reviewDecision: decision,
+                reviewedAt: new Date().toISOString(),
+                reviewedBy: getReviewedBy(),
+            };
+        }
+        (0, index_js_1.writeReviewQueue)(packets, "review-session", queueDir);
+        decided++;
+    }
+    const approved = packets.filter((p) => p.reviewDecision === "approve").length;
+    const rejected = packets.filter((p) => p.reviewDecision === "reject").length;
+    const deferred = packets.filter((p) => p.reviewDecision === "defer").length;
+    output(`\nReview complete: ${approved} approved, ${rejected} rejected, ${deferred} deferred.`);
+    const pendingFiles = packets
+        .filter((p) => p.reviewDecision === "approve" || p.reviewDecision === "reject")
+        .map((p) => p.sourcePath);
+    if (pendingFiles.length > 0) {
+        output("Running docs ingest to apply decisions...");
+        try {
+            const results = (0, ingest_js_1.ingestDocs)(pendingFiles, { repoRoot });
+            (0, ingest_js_1.printIngestResults)(results);
+        }
+        catch (err) {
+            output(`Ingest error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/package.json

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