@lsctech/polaris 0.4.8 → 0.5.0

package/dist/loop/worker-packet.js

@@ -195,6 +195,10 @@ function compileStartupPacket(input) {
         prompt_mode: 'full',
         prompt_metrics: { mode: 'full', char_count: 0, estimated_tokens: 0 },
         role_context: roleContextForWorkerRole('startup'),
+        routing_context: {
+            task_type: "startup",
+            required_capabilities: ["orchestration"],
+        },
         result_file_contract: {
             result_file: input.resultFile,
             result_required_fields: Object.fromEntries([
@@ -287,6 +291,10 @@ function compileImplPacket(input) {
         prompt_mode: promptMode,
         prompt_metrics: promptResult.metrics,
         role_context: roleContextForWorkerRole('impl'),
+        routing_context: {
+            task_type: "impl",
+            required_capabilities: ["implementation"],
+        },
         prohibited_write_paths: exports.WORKER_PROHIBITED_WRITE_PATHS,
         result_file_contract: {
             result_file: input.resultFile,
@@ -341,6 +349,10 @@ function compileFinalizePacket(input) {
         prompt_mode: 'full',
         prompt_metrics: { mode: 'full', char_count: 0, estimated_tokens: 0 },
         role_context: roleContextForWorkerRole('finalize'),
+        routing_context: {
+            task_type: "finalize",
+            required_capabilities: ["finalization"],
+        },
         result_file_contract: {
             result_file: input.resultFile,
             result_required_fields: Object.fromEntries([
@@ -390,6 +402,10 @@ function compilePreflightPacket(input) {
         prompt_mode: 'full',
         prompt_metrics: { mode: 'full', char_count: 0, estimated_tokens: 0 },
         role_context: roleContextForWorkerRole('preflight'),
+        routing_context: {
+            task_type: "startup",
+            required_capabilities: ["orchestration"],
+        },
         result_file_contract: {
             result_file: input.resultFile,
             result_required_fields: Object.fromEntries([

package/dist/runtime/scheduling/child-selector.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.selectNextChild = selectNextChild;
+exports.selectChildSlotClaims = selectChildSlotClaims;
 /**
  * Select the next child to execute.
  *
@@ -14,3 +15,83 @@ function selectNextChild(state) {
         return null;
     return [...state.open_children].sort()[0] ?? null;
 }
+function countActiveSlotsByProvider(claims) {
+    const activeSlotsByProvider = {};
+    for (const claim of claims) {
+        if (!claim.provider)
+            continue;
+        activeSlotsByProvider[claim.provider] = (activeSlotsByProvider[claim.provider] ?? 0) + 1;
+    }
+    return activeSlotsByProvider;
+}
+function selectChildSlotClaims(args) {
+    const now = args.now ?? new Date();
+    const nowMs = now.getTime();
+    const openSet = new Set(args.open_children);
+    const completedSet = new Set(args.completed_children);
+    const expired_claims = [];
+    const retainedClaims = args.existing_claims.filter((claim) => {
+        const expiresAt = new Date(claim.expires_at).getTime();
+        const notExpired = Number.isFinite(expiresAt) && expiresAt > nowMs;
+        const stillOpen = openSet.has(claim.child_id);
+        if (!notExpired || !stillOpen) {
+            expired_claims.push(claim.child_id);
+            return false;
+        }
+        return true;
+    });
+    const rejected_children = {};
+    const claimedChildren = new Set(retainedClaims.map((claim) => claim.child_id));
+    const availableSlots = Math.max(0, args.max_concurrent - retainedClaims.length);
+    const newClaims = [];
+    if (availableSlots > 0) {
+        for (const childId of args.open_children) {
+            if (newClaims.length >= availableSlots)
+                break;
+            if (childId === args.active_child)
+                continue;
+            if (claimedChildren.has(childId))
+                continue;
+            const dependencies = args.get_dependencies(childId);
+            const unmetDependencies = dependencies.filter((dependency) => openSet.has(dependency) && !completedSet.has(dependency));
+            if (unmetDependencies.length > 0) {
+                rejected_children[childId] = "blocked-dependency";
+                continue;
+            }
+            const decision = args.decide_route({
+                childId,
+                activeSlotsByProvider: countActiveSlotsByProvider([...retainedClaims, ...newClaims]),
+            });
+            const hardIneligibleReasons = new Set([
+                "role-disabled",
+                "not-in-policy",
+                "quota-exhausted",
+                "trust-too-low",
+                "capability-mismatch",
+                "cost-policy",
+                "no-slot",
+            ]);
+            const routingExhausted = decision.exhaustedReason !== undefined &&
+                (hardIneligibleReasons.has(decision.exhaustedReason) || decision.mode !== "delegated");
+            const canClaim = decision.selectedProvider !== undefined || decision.mode === "delegated";
+            if (routingExhausted || !canClaim) {
+                rejected_children[childId] = "router-ineligible";
+                continue;
+            }
+            newClaims.push({
+                child_id: childId,
+                provider: decision.selectedProvider ?? null,
+                claimed_at: now.toISOString(),
+                expires_at: new Date(nowMs + args.claim_ttl_ms).toISOString(),
+                selection_reason: decision.selectionReason,
+            });
+        }
+    }
+    const slot_claims = [...retainedClaims, ...newClaims];
+    return {
+        selected_child: slot_claims[0]?.child_id ?? null,
+        slot_claims,
+        rejected_children,
+        expired_claims,
+    };
+}

package/dist/smartdocs-engine/doctrine.js

@@ -4,6 +4,7 @@ exports.CANDIDATE_MARKER = void 0;
 exports.parseFrontMatter = parseFrontMatter;
 exports.addCandidateGovernanceMetadata = addCandidateGovernanceMetadata;
 exports.stampIngestFrontMatter = stampIngestFrontMatter;
+exports.deriveTypeFromDirectory = deriveTypeFromDirectory;
 exports.backfillOkfType = backfillOkfType;
 exports.doctrineDraft = doctrineDraft;
 exports.doctrinePromote = doctrinePromote;
@@ -212,13 +213,102 @@ function addMissingFrontMatterField(content, key, value) {
     }
     return `---\n${key}: ${value}\n---\n\n${normalized}`;
 }
+/**
+ * Sets a frontmatter field to a new value, replacing it if present or adding
+ * it if absent. Unlike `addMissingFrontMatterField`, this always applies the
+ * given value — used when a lifecycle transition (promote/deprecate) must
+ * make `type` agree with the doc's new directory tier, overriding whatever
+ * value it carried in its previous tier.
+ */
+function setFrontMatterField(content, key, value) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    if (normalized.startsWith("---\n")) {
+        const end = normalized.indexOf("\n---", 4);
+        if (end !== -1) {
+            const frontMatter = normalized.slice(4, end);
+            const afterFrontMatter = normalized.slice(end + 4);
+            const lowerKey = key.toLowerCase();
+            let found = false;
+            const newLines = frontMatter.split("\n").map((l) => {
+                const colonIdx = l.indexOf(":");
+                if (colonIdx !== -1 && l.slice(0, colonIdx).trim().toLowerCase() === lowerKey) {
+                    found = true;
+                    return `${key}: ${value}`;
+                }
+                return l;
+            });
+            if (found) {
+                return `---\n${newLines.join("\n")}\n---${afterFrontMatter}`;
+            }
+            return `---\n${frontMatter}\n${key}: ${value}\n---${afterFrontMatter}`;
+        }
+    }
+    return `---\n${key}: ${value}\n---\n\n${normalized}`;
+}
+/**
+ * Directory-tier defaults for `type`, keyed by the first two path segments
+ * relative to `smartdocs/`. Mirrors the lifecycle-tier vocabulary already
+ * used by `ingest.ts`'s `DocsClassification`, since directory position — not
+ * frontmatter — is the authoritative signal for a doc's lifecycle state
+ * (docs-authority-model.md "Key rule"). Falling back to a literal `"raw"`
+ * for every file regardless of directory (the prior behavior) let a doc
+ * sitting in `doctrine/active/` end up with `type: raw`, contradicting its
+ * own directory-encoded authority tier.
+ */
+const DIRECTORY_TYPE_DEFAULTS = {
+    "raw": "raw",
+    "doctrine/active": "doctrine",
+    "doctrine/candidate": "doctrine-candidate",
+    "doctrine/deprecated": "doctrine-deprecated",
+    "doctrine": "doctrine",
+    "specs/raw": "raw",
+    "specs/active": "spec",
+    "specs/implemented": "spec-implemented",
+    "specs/superseded": "spec-superseded",
+    "specs/archive": "spec-archive",
+    "specs": "spec",
+    "audits/findings": "audit-finding",
+    "audits/resolved": "audit-resolved",
+    "audits": "audit",
+    "decisions": "decision",
+    "architecture": "architecture",
+    "integrations": "integration",
+    "medic": "medic",
+    "runtime/run-reports": "run-report",
+    "runtime/summaries": "runtime-summary",
+    "runtime": "runtime",
+};
+/**
+ * Derives a directory-tier-appropriate `type` default for a SmartDocs file
+ * that has neither `kind` nor `doc-type` set. `relPath` is relative to
+ * `smartdocs/` (forward-slash separated). Reserved front-door filenames
+ * (`POLARIS.md`, `SUMMARY.md`, `index.md`) get `"index"` regardless of tier,
+ * since they're navigational scaffolding, not tier content.
+ */
+function deriveTypeFromDirectory(relPath) {
+    const name = (0, node_path_1.basename)(relPath);
+    if (name === "POLARIS.md" || name === "SUMMARY.md" || name === "index.md") {
+        return "index";
+    }
+    const segments = relPath.split("/").slice(0, -1);
+    if (segments.length >= 2) {
+        const twoLevel = `${segments[0]}/${segments[1]}`;
+        if (DIRECTORY_TYPE_DEFAULTS[twoLevel])
+            return DIRECTORY_TYPE_DEFAULTS[twoLevel];
+    }
+    if (segments.length >= 1 && DIRECTORY_TYPE_DEFAULTS[segments[0]]) {
+        return DIRECTORY_TYPE_DEFAULTS[segments[0]];
+    }
+    return "raw";
+}
 /**
  * Retrofit existing SmartDocs with an OKF-conformant `type` frontmatter field.
  *
  * Walks every `.md` file under `smartdocs/`. For each file already missing a
  * `type` key: derives the value from `kind` if present, else `doc-type` if
- * present, else defaults to `"raw"`. Files that already declare `type` are
- * left untouched and reported in `skipped`.
+ * present, else derives a directory-tier-appropriate default via
+ * `deriveTypeFromDirectory` (see that function for the tier mapping). Files
+ * that already declare `type` are left untouched and reported in `skipped`.
  *
  * This is the retroactive counterpart to `addCandidateGovernanceMetadata`,
  * which stamps `type` on newly-governed candidate docs going forward — this
@@ -264,7 +354,8 @@ function backfillOkfType(repoRoot, options = {}) {
             result.skipped.push(filePath);
             return;
         }
-        const derivedType = fm.kind ?? fm["doc-type"] ?? "raw";
+        const relPath = (0, node_path_1.relative)(smartdocsDir, filePath).replace(/\\/g, "/");
+        const derivedType = fm.kind ?? fm["doc-type"] ?? deriveTypeFromDirectory(relPath);
         if (!options.dryRun) {
             (0, node_fs_1.writeFileSync)(filePath, addMissingFrontMatterField(content, "type", derivedType), "utf-8");
         }
@@ -437,7 +528,8 @@ function doctrinePromote(path, options) {
     if ((0, node_fs_1.existsSync)(destination)) {
         throw new Error(`Destination already exists: ${destination}`);
     }
-    const activeContent = content.replace(`${exports.CANDIDATE_MARKER}\n`, "").replace(exports.CANDIDATE_MARKER, "");
+    const strippedContent = content.replace(`${exports.CANDIDATE_MARKER}\n`, "").replace(exports.CANDIDATE_MARKER, "");
+    const activeContent = setFrontMatterField(strippedContent, "type", "doctrine");
     (0, node_fs_1.writeFileSync)(destination, activeContent, "utf-8");
     (0, node_fs_1.unlinkSync)(source);
     // Move co-located provenance sidecar if present
@@ -501,7 +593,8 @@ function doctrineDeprecate(path, options) {
     }
     const content = (0, node_fs_1.readFileSync)(source, "utf-8");
     const deprecatedAt = new Date().toISOString();
-    const deprecatedContent = `<!-- polaris:doctrine-deprecated deprecatedAt="${deprecatedAt}" runId="${runId}" -->\n${content}`;
+    const retypedContent = setFrontMatterField(content, "type", "doctrine-deprecated");
+    const deprecatedContent = `<!-- polaris:doctrine-deprecated deprecatedAt="${deprecatedAt}" runId="${runId}" -->\n${retypedContent}`;
     (0, node_fs_1.writeFileSync)(destination, deprecatedContent, "utf-8");
     (0, node_fs_1.unlinkSync)(source);
     // Move co-located provenance sidecar if present
@@ -834,7 +927,9 @@ function specPromote(path, options) {
     if ((0, node_fs_1.existsSync)(destination)) {
         throw new Error(`Destination already exists: ${destination}`);
     }
-    (0, node_fs_1.renameSync)(source, destination);
+    const retypedContent = setFrontMatterField(content, "type", "spec");
+    (0, node_fs_1.writeFileSync)(destination, retypedContent, "utf-8");
+    (0, node_fs_1.unlinkSync)(source);
     if ((0, node_fs_1.existsSync)(provenanceSrcPath)) {
         (0, node_fs_1.renameSync)(provenanceSrcPath, destination.replace(/\.md$/, ".provenance.json"));
     }

package/dist/smartdocs-engine/ingest.js

@@ -456,8 +456,14 @@ function ingestDocs(files, options) {
         };
         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, "/");
+        // A prior human/agent review decision or a scoped --approve-authority call
+        // overrides an otherwise-review-required outcome so the placement it
+        // decided on actually happens.
+        const priorDecision = priorQueue.find((p) => p.sourcePath === relSource)?.reviewDecision;
+        const forcedApprove = routingDecision.outcome === "review-required" &&
+            (priorDecision === "approve" || Boolean(options.approveAuthority));
         // review-required: leave in raw/, emit packet, skip move
-        if (routingDecision.outcome === "review-required") {
+        if (routingDecision.outcome === "review-required" && !forcedApprove) {
             const packet = {
                 ...routingDecision.reviewPacket,
                 sourcePath: relSource,
@@ -504,6 +510,16 @@ function ingestDocs(files, options) {
             linked_map_area: linkedMapArea,
             cluster_id: clusterId,
         });
+        if (forcedApprove) {
+            emitTelemetry(telPath, runId, {
+                event: "docs-ingest-approved-override",
+                file: relSource,
+                classification: docClassification,
+                destination: relDestination,
+                reason: priorDecision === "approve" ? "prior-review-decision" : "approve-authority-flag",
+                cluster_id: clusterId,
+            });
+        }
         if (!options.dryRun) {
             if ((0, node_path_1.resolve)(absSource) !== (0, node_path_1.resolve)(destination)) {
                 (0, node_fs_1.renameSync)(absSource, destination);
@@ -583,7 +599,7 @@ function ingestDocs(files, options) {
             dryRun: Boolean(options.dryRun),
             nearestSummary,
             summaryDeltaWarranted: summaryDelta.updateWarranted,
-            routingDecision: routingDecision.outcome,
+            routingDecision: forcedApprove ? "approved-override" : routingDecision.outcome,
             reviewPacket: routingDecision.reviewPacket
                 ? { ...routingDecision.reviewPacket, sourcePath: relSource, proposedDestination: relDestination, conflicts: [] }
                 : undefined,

package/dist/smartdocs-engine/migrate.js

@@ -11,6 +11,7 @@ const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
 const ALLOWED_BASENAMES = new Set([
     "README.md",
     "POLARIS.md",
+    "POLARIS_RULES.md",
     "SUMMARY.md",
     "CHANGELOG.md",
     "LICENSE.md",

package/package.json

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