@lsctech/polaris 0.5.11 → 0.5.13

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DRAFT_MARKER = void 0;
+exports.TEMPLATE_VERSION_STAMP = exports.TEMPLATE_VERSION = exports.GENERATED_END_MARKER = exports.GENERATED_START_MARKER = exports.DRAFT_MARKER = void 0;
 exports.hasDraftMarker = hasDraftMarker;
 exports.generateDraft = generateDraft;
 exports.generateSummaryDraft = generateSummaryDraft;
@@ -12,6 +12,7 @@ exports.seedInstructionsAll = seedInstructionsAll;
 exports.seedSummaryAll = seedSummaryAll;
 exports.seedIndex = seedIndex;
 exports.seedIndexAll = seedIndexAll;
+exports.reconcileAll = reconcileAll;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const loader_js_1 = require("../config/loader.js");
@@ -19,6 +20,10 @@ const atlas_js_1 = require("../map/atlas.js");
 const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
 const doctrine_js_1 = require("./doctrine.js");
 exports.DRAFT_MARKER = "<!-- polaris:draft -->";
+exports.GENERATED_START_MARKER = "<!-- BEGIN POLARIS GENERATED -->";
+exports.GENERATED_END_MARKER = "<!-- END POLARIS GENERATED -->";
+exports.TEMPLATE_VERSION = 1;
+exports.TEMPLATE_VERSION_STAMP = `<!-- polaris:template-version: ${exports.TEMPLATE_VERSION} -->`;
 function hasDraftMarker(filePath) {
     try {
         const content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
@@ -121,7 +126,7 @@ function generateDraft(targetDir, repoRoot, allRoutes) {
     lines.push("## Related routes", "");
     lines.push("<!-- Atlas route pointer to sibling or parent folders. -->");
     lines.push("");
-    return lines.join("\n");
+    return [exports.DRAFT_MARKER, exports.GENERATED_START_MARKER, exports.TEMPLATE_VERSION_STAMP, ...lines.slice(1), exports.GENERATED_END_MARKER].join("\n");
 }
 function generateSummaryDraft(targetDir, repoRoot, _allRoutes) {
     const dirLabel = (0, node_path_1.basename)(targetDir) || (0, node_path_1.basename)(repoRoot);
@@ -172,14 +177,51 @@ function generateSummaryDraft(targetDir, repoRoot, _allRoutes) {
         "```yaml",
         "canonical_docs:",
         "  - POLARIS.md",
-        "<!-- Add navigation paths to canonical docs, specs, or doctrine. These are retrieval paths, not reading assignments. -->",
         "```",
         "",
+        "<!-- Add navigation paths to canonical docs, specs, or doctrine. These are retrieval paths, not reading assignments. -->",
+        "",
         "## Known Drift",
         "<!-- Places where the summary may be stale (honesty field). -->",
         "",
     ];
-    return lines.join("\n");
+    return [exports.DRAFT_MARKER, exports.GENERATED_START_MARKER, exports.TEMPLATE_VERSION_STAMP, ...lines.slice(1), exports.GENERATED_END_MARKER].join("\n");
+}
+function generateDraftRegion(targetDir, repoRoot, allRoutes) {
+    const full = generateDraft(targetDir, repoRoot, allRoutes);
+    const lines = full.split("\n");
+    // Remove the DRAFT marker, GENERATED_START_MARKER, and GENERATED_END_MARKER;
+    // the remaining lines are the region body, including the template-version stamp.
+    return lines.slice(2, -1).join("\n");
+}
+function generateSummaryDraftRegion(targetDir, repoRoot, allRoutes) {
+    const full = generateSummaryDraft(targetDir, repoRoot, allRoutes);
+    const lines = full.split("\n");
+    return lines.slice(2, -1).join("\n");
+}
+const TEMPLATE_VERSION_RE = /^<!-- polaris:template-version:\s*(\d+)\s*-->/;
+function getGeneratedRegionVersion(content) {
+    const startIdx = content.indexOf(exports.GENERATED_START_MARKER);
+    if (startIdx === -1)
+        return null;
+    const startLineEnd = content.indexOf("\n", startIdx + exports.GENERATED_START_MARKER.length);
+    if (startLineEnd === -1)
+        return null;
+    const endIdx = content.indexOf(exports.GENERATED_END_MARKER, startLineEnd + 1);
+    if (endIdx === -1)
+        return null;
+    const region = content.slice(startLineEnd + 1, endIdx);
+    const firstLine = region.split("\n")[0] ?? "";
+    const match = TEMPLATE_VERSION_RE.exec(firstLine);
+    return match ? parseInt(match[1], 10) : undefined;
+}
+function replaceGeneratedRegion(content, newRegionBody) {
+    const startIdx = content.indexOf(exports.GENERATED_START_MARKER);
+    const startLineEnd = content.indexOf("\n", startIdx + exports.GENERATED_START_MARKER.length);
+    const endIdx = content.indexOf(exports.GENERATED_END_MARKER, startLineEnd + 1);
+    const before = content.slice(0, startLineEnd + 1);
+    const after = content.slice(endIdx);
+    return before + newRegionBody + "\n" + after;
 }
 const RESERVED_INDEX_NAMES = new Set(["index.md", "POLARIS.md", "SUMMARY.md", "log.md"]);
 function isReservedIndexName(name) {
@@ -569,3 +611,116 @@ function seedIndexAll(repoRoot, opts = {}) {
     }
     return { written, skippedExists, skippedDraft, skippedIneligible: [] };
 }
+function reconcileFile(relDir, fileName, repoRoot, allRoutes, dryRun, generateFull, generateRegion) {
+    const absDir = (0, node_path_1.resolve)(repoRoot, relDir);
+    const relCheck = (0, node_path_1.relative)(repoRoot, absDir).replace(/\\/g, "/");
+    if (relCheck.startsWith("..") || relCheck.startsWith("/")) {
+        throw new Error(`Path traversal detected: target path is outside repo root`);
+    }
+    const outFile = (0, node_path_1.join)(absDir, fileName);
+    const relPath = (0, node_path_1.relative)(repoRoot, outFile).replace(/\\/g, "/");
+    if (!(0, node_fs_1.existsSync)(outFile)) {
+        const content = generateFull(relDir, repoRoot, allRoutes);
+        if (!dryRun) {
+            (0, node_fs_1.writeFileSync)(outFile, content, "utf-8");
+        }
+        return "created";
+    }
+    const content = (0, node_fs_1.readFileSync)(outFile, "utf-8");
+    if (content.includes(exports.DRAFT_MARKER)) {
+        const newContent = generateFull(relDir, repoRoot, allRoutes);
+        if (!dryRun) {
+            (0, node_fs_1.writeFileSync)(outFile, newContent, "utf-8");
+        }
+        return "regenerated";
+    }
+    const regionVersion = getGeneratedRegionVersion(content);
+    if (regionVersion !== null) {
+        if (regionVersion === exports.TEMPLATE_VERSION) {
+            return "skipped";
+        }
+        const newRegionBody = generateRegion(relDir, repoRoot, allRoutes);
+        if (!dryRun) {
+            const newContent = replaceGeneratedRegion(content, newRegionBody);
+            (0, node_fs_1.writeFileSync)(outFile, newContent, "utf-8");
+        }
+        return "regenerated-region";
+    }
+    return "blocked";
+}
+function reconcileAll(repoRoot, opts = {}) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const atlasPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const allRoutes = {
+        ...(0, atlas_js_1.readFileRoutes)(atlasPath),
+        ...(0, atlas_js_1.readNeedsReview)(atlasPath),
+    };
+    // Root handling: skipped by default (root uses AGENTS.md/CLAUDE.md)
+    const rootEligibility = (0, smartdoc_ignore_js_1.isDirectoryEligible)(repoRoot, repoRoot, {
+        isRoot: true,
+        skipRoot: opts.includeRoot ? false : true,
+    });
+    let skippedRoot;
+    if (!rootEligibility.eligible) {
+        skippedRoot = { path: ".", reason: rootEligibility.reason || "root skipped" };
+    }
+    const eligibilityOpts = {
+        includeAgentFolders: opts.includeAgentFolders,
+        includeHidden: opts.includeHidden,
+        skipRoot: true,
+    };
+    const { eligible: dirs, ineligible: skippedIneligible } = collectDirs(repoRoot, repoRoot, eligibilityOpts);
+    const dirsToProcess = [];
+    if (rootEligibility.eligible) {
+        dirsToProcess.push(".");
+    }
+    dirsToProcess.push(...dirs);
+    const report = {
+        created: [],
+        regenerated: [],
+        regeneratedRegion: [],
+        skipped: [],
+        blocked: [],
+        skippedIneligible,
+        skippedRoot,
+    };
+    for (const relDir of dirsToProcess) {
+        const polarisStatus = reconcileFile(relDir, "POLARIS.md", repoRoot, allRoutes, opts.dryRun ?? false, generateDraft, generateDraftRegion);
+        switch (polarisStatus) {
+            case "created":
+                report.created.push(relDir === "." ? "POLARIS.md" : `${relDir}/POLARIS.md`);
+                break;
+            case "regenerated":
+                report.regenerated.push(relDir === "." ? "POLARIS.md" : `${relDir}/POLARIS.md`);
+                break;
+            case "regenerated-region":
+                report.regeneratedRegion.push(relDir === "." ? "POLARIS.md" : `${relDir}/POLARIS.md`);
+                break;
+            case "skipped":
+                report.skipped.push(relDir === "." ? "POLARIS.md" : `${relDir}/POLARIS.md`);
+                break;
+            case "blocked":
+                report.blocked.push(relDir === "." ? "POLARIS.md" : `${relDir}/POLARIS.md`);
+                break;
+        }
+        const summaryStatus = reconcileFile(relDir, "SUMMARY.md", repoRoot, allRoutes, opts.dryRun ?? false, generateSummaryDraft, generateSummaryDraftRegion);
+        switch (summaryStatus) {
+            case "created":
+                report.created.push(relDir === "." ? "SUMMARY.md" : `${relDir}/SUMMARY.md`);
+                break;
+            case "regenerated":
+                report.regenerated.push(relDir === "." ? "SUMMARY.md" : `${relDir}/SUMMARY.md`);
+                break;
+            case "regenerated-region":
+                report.regeneratedRegion.push(relDir === "." ? "SUMMARY.md" : `${relDir}/SUMMARY.md`);
+                break;
+            case "skipped":
+                report.skipped.push(relDir === "." ? "SUMMARY.md" : `${relDir}/SUMMARY.md`);
+                break;
+            case "blocked":
+                report.blocked.push(relDir === "." ? "SUMMARY.md" : `${relDir}/SUMMARY.md`);
+                break;
+        }
+    }
+    return report;
+}

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

@@ -129,6 +129,32 @@ function parseReadBeforeEditingLinks(content) {
     }
     return links;
 }
+function extractGeneratedRegion(content) {
+    const start = content.indexOf(seed_instructions_js_1.GENERATED_START_MARKER);
+    const end = content.indexOf(seed_instructions_js_1.GENERATED_END_MARKER);
+    if (start === -1 || end === -1 || start >= end)
+        return null;
+    return content.slice(start + seed_instructions_js_1.GENERATED_START_MARKER.length, end).trim();
+}
+function parseTemplateVersionStamp(content) {
+    const match = content.match(/<!--\s*polaris:template-version:\s*(\d+)\s*-->/);
+    if (!match)
+        return undefined;
+    return parseInt(match[1], 10);
+}
+function checkTemplateVersionStamp(content, fileLabel) {
+    const version = parseTemplateVersionStamp(content);
+    if (version === undefined) {
+        return { severity: "WARN", message: `${fileLabel} is unstamped (no template-version stamp)` };
+    }
+    if (version !== seed_instructions_js_1.TEMPLATE_VERSION) {
+        return {
+            severity: "WARN",
+            message: `${fileLabel} template version drift: found ${version}, expected ${seed_instructions_js_1.TEMPLATE_VERSION}`,
+        };
+    }
+    return null;
+}
 function getRequiredDirs(repoRoot) {
     const config = (0, loader_js_1.loadConfig)(repoRoot);
     // The config type may not yet have a docs key; access dynamically
@@ -178,6 +204,14 @@ function validateDir(relDir, repoRoot, allRoutes, similarityThreshold = DEFAULT_
     }
     const content = (0, node_fs_1.readFileSync)(polarisFile, "utf-8");
     const findings = [];
+    const polarisGeneratedRaw = extractGeneratedRegion(content);
+    const polarisGenerated = polarisGeneratedRaw ?? content;
+    // Signal 0: template-version stamp inside generated region (only when present)
+    if (polarisGeneratedRaw !== null) {
+        const polarisStampFinding = checkTemplateVersionStamp(polarisGeneratedRaw, "POLARIS.md");
+        if (polarisStampFinding)
+            findings.push(polarisStampFinding);
+    }
     // Signal 1: ≥3 files in directory changed since last POLARIS.md git modification
     const lastMod = getLastGitModDate(polarisFile, repoRoot);
     if (lastMod !== null) {
@@ -191,7 +225,7 @@ function validateDir(relDir, repoRoot, allRoutes, similarityThreshold = DEFAULT_
         }
     }
     // Signal 2: broken links in "Read before editing"
-    const links = parseReadBeforeEditingLinks(content);
+    const links = parseReadBeforeEditingLinks(polarisGenerated);
     for (const link of links) {
         const absLink = (0, node_path_1.resolve)(absDir, link);
         if (!(0, node_fs_1.existsSync)(absLink)) {
@@ -221,7 +255,7 @@ function validateDir(relDir, repoRoot, allRoutes, similarityThreshold = DEFAULT_
     const headingRe = /^##\s+(.+)$/gm;
     const parsedHeadings = [];
     let headingMatch;
-    while ((headingMatch = headingRe.exec(content)) !== null) {
+    while ((headingMatch = headingRe.exec(polarisGenerated)) !== null) {
         const original = headingMatch[1].trim();
         parsedHeadings.push({
             normalized: original.toLowerCase(),
@@ -289,9 +323,17 @@ function validateDir(relDir, repoRoot, allRoutes, similarityThreshold = DEFAULT_
     else {
         // Signal 6: SUMMARY.md doctrine-bleed scan
         const summaryContent = (0, node_fs_1.readFileSync)(summaryFile, "utf-8");
+        const summaryGeneratedRaw = extractGeneratedRegion(summaryContent);
+        const summaryGenerated = summaryGeneratedRaw ?? summaryContent;
         const summaryRel = (0, node_path_1.relative)(repoRoot, summaryFile).replace(/\\/g, "/");
+        // Signal 5.5: SUMMARY.md template-version stamp (only inside generated region)
+        if (summaryGeneratedRaw !== null) {
+            const summaryStampFinding = checkTemplateVersionStamp(summaryGeneratedRaw, "SUMMARY.md");
+            if (summaryStampFinding)
+                findings.push(summaryStampFinding);
+        }
         const modalVerbs = ["must", "never", "always"];
-        const lines = summaryContent.split("\n");
+        const lines = summaryGenerated.split("\n");
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i].toLowerCase();
             for (const verb of modalVerbs) {
@@ -305,7 +347,7 @@ function validateDir(relDir, repoRoot, allRoutes, similarityThreshold = DEFAULT_
         }
         // Signal 7: pairwise POLARIS.md / SUMMARY.md drift
         const routeName = relDir === "." ? undefined : (0, node_path_1.basename)(relDir);
-        const similarity = computeNormalizedSimilarity(content, summaryContent, routeName);
+        const similarity = computeNormalizedSimilarity(polarisGenerated, summaryGenerated, routeName);
         if (content === summaryContent) {
             findings.push({
                 severity: "ERROR",

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/dist/workspace/POLARIS.md

@@ -1,4 +1,6 @@
 <!-- polaris:draft -->
+<!-- BEGIN POLARIS GENERATED -->
+<!-- polaris:template-version: 1 -->
 # workspace
 
 > Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.
@@ -38,3 +40,5 @@
 ## Related routes
 
 <!-- Atlas route pointer to sibling or parent folders. -->
+
+<!-- END POLARIS GENERATED -->

package/dist/workspace/SUMMARY.md

@@ -0,0 +1,56 @@
+<!-- polaris:draft -->
+<!-- BEGIN POLARIS GENERATED -->
+<!-- polaris:template-version: 1 -->
+# Summary: workspace
+
+> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.
+
+## Purpose
+<!-- One-line statement of what this folder does. -->
+
+## Core Concepts
+<!-- 3–7 key concepts a reader needs before diving into source. -->
+
+## Architectural Role
+<!-- How this folder fits into the larger system. -->
+
+## Key Constraints
+<!-- The most important non-obvious behavioral limits. -->
+
+## Important Relationships
+<!-- Upstream/downstream dependencies on other folders. -->
+
+## Current State
+<!-- What is implemented, what is not yet, known gaps. -->
+
+## Route Health
+<!-- Current operational condition. Workers should understand route health in under 10 seconds. -->
+
+### Healthy
+<!-- If the route is healthy, state why. Otherwise omit this subsection. -->
+
+### Monitoring
+<!-- Any ongoing monitoring or observations. Omit if none. -->
+
+### Known Issues
+<!-- Any known problems or risks. Omit if none. -->
+
+### Recent Treatments
+<!-- Recent fixes or improvements, with chart references if applicable. Omit if none. -->
+
+### Improvement Opportunities
+<!-- Potential future improvements. Omit if none. -->
+
+## Canonical References
+
+```yaml
+canonical_docs:
+  - POLARIS.md
+```
+
+<!-- Add navigation paths to canonical docs, specs, or doctrine. These are retrieval paths, not reading assignments. -->
+
+## Known Drift
+<!-- Places where the summary may be stale (honesty field). -->
+
+<!-- END POLARIS GENERATED -->

package/package.json

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