@lsctech/polaris 0.4.8 → 0.4.9

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.4.9",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",