@lsctech/polaris 0.5.12 → 0.5.13

package/dist/skill-packet/generator.js

@@ -1,9 +1,15 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_SKILLS = exports.SKILL_ROLE_MAP = void 0;
 exports.generateSetupBootstrapPacket = generateSetupBootstrapPacket;
 exports.generateSkillPacket = generateSkillPacket;
 const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 exports.SKILL_ROLE_MAP = {
     analyze: "Analyst",
     run: "Foreman",
@@ -362,7 +368,37 @@ function buildCatalogPacket() {
         ],
     };
 }
-function buildReconcilePacket() {
+function buildReconcilePacket(_config, options) {
+    const repoRoot = node_path_1.default.resolve(options?.repoRoot ?? process.cwd());
+    const issueId = resolveIssueId(repoRoot, options?.issueId);
+    const runId = buildReconcileRunId(issueId);
+    const changedFiles = getReconcileChangedFiles(repoRoot);
+    const affectedFolders = resolveAffectedFolders(repoRoot, changedFiles);
+    if (affectedFolders.length === 0) {
+        return buildBlockedReconcilePacket(runId, issueId, repoRoot);
+    }
+    const allowedWritePaths = affectedFolders.flatMap((folder) => {
+        const paths = [node_path_1.default.join(repoRoot, folder, "POLARIS.md")];
+        const summaryPath = node_path_1.default.join(repoRoot, folder, "SUMMARY.md");
+        if (node_fs_1.default.existsSync(summaryPath)) {
+            paths.push(summaryPath);
+        }
+        return paths;
+    });
+    const workInventory = {
+        affected_folders: affectedFolders,
+        all_changed_files: changedFiles,
+        child_summaries: [],
+        pending_cognition_notes: [],
+        polaris_md_files: Object.fromEntries(affectedFolders.map((folder) => [
+            folder,
+            readFileOrNull(node_path_1.default.join(repoRoot, folder, "POLARIS.md")),
+        ])),
+        summary_md_files: Object.fromEntries(affectedFolders.map((folder) => [
+            folder,
+            readFileOrNull(node_path_1.default.join(repoRoot, folder, "SUMMARY.md")),
+        ])),
+    };
     return {
         authority_boundaries: [
             "Read packet-scoped folders and their POLARIS.md and SUMMARY.md files",
@@ -389,9 +425,204 @@ function buildReconcilePacket() {
             "A requested write falls outside packet-allowed paths",
             "Work evidence is missing or contradictory",
         ],
+        packet_kind: "reconcile",
+        run_id: runId,
+        issue_id: issueId,
+        affected_folders: affectedFolders,
+        work_inventory: workInventory,
+        allowed_write_paths: allowedWritePaths,
+        prohibited_write_paths: [repoRoot],
+        constraints: {
+            max_summary_addition_lines: 50,
+        },
     };
 }
-function generateSkillPacket(skillName, config) {
+function buildBlockedReconcilePacket(runId, issueId, repoRoot) {
+    return {
+        authority_boundaries: [
+            "Read packet-scoped folders and their POLARIS.md and SUMMARY.md files",
+            "Update cognition files only within packet-allowed write paths",
+            "Create one sealed local cognition commit",
+        ],
+        prohibited_actions: [
+            "Modify implementation source code, tests, or configuration",
+            "Move, ingest, classify, or promote documents",
+            "Write outside packet-allowed paths",
+            "Call polaris loop continue or polaris finalize",
+            "Git push or create a pull request",
+            "Fabricate affected folders or work inventory when no git diff is available",
+        ],
+        allowed_outputs: [
+            "Updated POLARIS.md and SUMMARY.md files in packet-allowed paths",
+            "A sealed local cognition commit",
+        ],
+        deliverables: [
+            "Packet-scoped cognition reconciled with completed work",
+            "All cognition changes recorded in one sealed local commit",
+        ],
+        stop_conditions: [
+            "All packet-scoped cognition reconciled",
+            "A requested write falls outside packet-allowed paths",
+            "Work evidence is missing or contradictory",
+            "No git diff is available to scope reconciliation",
+        ],
+        packet_kind: "reconcile",
+        run_id: runId,
+        issue_id: issueId,
+        affected_folders: [],
+        work_inventory: {
+            affected_folders: [],
+            all_changed_files: [],
+            child_summaries: [],
+            pending_cognition_notes: [],
+            polaris_md_files: {},
+            summary_md_files: {},
+        },
+        allowed_write_paths: [],
+        prohibited_write_paths: [repoRoot],
+        constraints: {
+            max_summary_addition_lines: 50,
+        },
+    };
+}
+// ── Reconcile helpers ─────────────────────────────────────────────────────────
+function resolveIssueId(repoRoot, explicitIssueId) {
+    if (explicitIssueId)
+        return explicitIssueId;
+    const stateCandidates = [
+        node_path_1.default.join(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json"),
+        node_path_1.default.join(repoRoot, ".polaris", "runs", "current-state.json"),
+    ];
+    for (const candidate of stateCandidates) {
+        try {
+            const raw = JSON.parse(node_fs_1.default.readFileSync(candidate, "utf-8"));
+            const activeChild = raw["active_child"];
+            if (typeof activeChild === "string" && activeChild)
+                return activeChild;
+            const clusterId = raw["cluster_id"];
+            if (typeof clusterId === "string" && clusterId)
+                return clusterId;
+        }
+        catch {
+            // ignore missing or malformed state
+        }
+    }
+    try {
+        const branch = execGit(repoRoot, ["branch", "--show-current"]).join("").trim();
+        const match = /^pol-?(\d+)(?:-.*)?$/i.exec(branch);
+        if (match && match[1]) {
+            return `POL-${match[1]}`;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return "unknown";
+}
+function buildReconcileRunId(issueId) {
+    const slug = issueId.replace(/\s+/g, "-");
+    const date = new Date().toISOString().slice(0, 10);
+    // Minimal sequence: 001 for now; each call is a distinct run by packet_id.
+    const seq = "001";
+    return `polaris-reconcile-${slug}-${date}-${seq}`;
+}
+function getReconcileChangedFiles(repoRoot) {
+    const files = new Set();
+    try {
+        for (const file of execGit(repoRoot, ["diff", "--name-only", "HEAD"])) {
+            if (file)
+                files.add(file);
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const base = resolveReconcileBase(repoRoot);
+        if (base) {
+            for (const file of execGit(repoRoot, ["diff", "--name-only", `${base}..HEAD`])) {
+                if (file)
+                    files.add(file);
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return [...files].sort();
+}
+function resolveReconcileBase(repoRoot) {
+    const candidates = [
+        resolveRemoteDefaultBranch(repoRoot),
+        "origin/main",
+        "origin/master",
+        "main",
+        "master",
+    ];
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        try {
+            const base = execGit(repoRoot, ["merge-base", "HEAD", candidate]).join("").trim();
+            if (base)
+                return base;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+function resolveRemoteDefaultBranch(repoRoot) {
+    try {
+        const ref = execGit(repoRoot, ["rev-parse", "--abbrev-ref", "refs/remotes/origin/HEAD"]).join("").trim();
+        return ref || null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveAffectedFolders(repoRoot, changedFiles) {
+    const routeMap = loadFileRouteMap(repoRoot);
+    const folders = new Set();
+    for (const file of changedFiles) {
+        const entry = routeMap[file];
+        if (entry && typeof entry.route === "string") {
+            folders.add(entry.route.replace(/\/+$/, "") + "/");
+        }
+    }
+    return [...folders].sort();
+}
+function loadFileRouteMap(repoRoot) {
+    const mapPath = node_path_1.default.join(repoRoot, ".polaris", "map", "file-routes.json");
+    try {
+        const raw = JSON.parse(node_fs_1.default.readFileSync(mapPath, "utf-8"));
+        const normalized = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (value && typeof value === "object") {
+                const entry = value;
+                normalized[key] = { route: typeof entry.route === "string" ? entry.route : undefined };
+            }
+        }
+        return normalized;
+    }
+    catch {
+        return {};
+    }
+}
+function readFileOrNull(filePath) {
+    try {
+        return node_fs_1.default.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function execGit(repoRoot, args) {
+    const output = (0, node_child_process_1.execFileSync)("git", args, { cwd: repoRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    return output.split("\n").filter(Boolean);
+}
+function generateSkillPacket(skillName, config, options) {
     const active_role = exports.SKILL_ROLE_MAP[skillName];
     const role_summary = ROLE_SUMMARIES[active_role];
     const generated_at = new Date().toISOString();
@@ -425,7 +656,7 @@ function generateSkillPacket(skillName, config) {
             body = buildCatalogPacket();
             break;
         case "reconcile":
-            body = buildReconcilePacket();
+            body = buildReconcilePacket(config, options);
             break;
     }
     return {

package/dist/smartdocs-engine/canon-check.js

@@ -43,7 +43,7 @@ function locateCanonFiles(changedFiles, repoRoot) {
             canon.add(polarisMd);
     }
     // Active doctrine
-    const doctrineDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "active");
+    const doctrineDir = (0, node_path_1.join)(repoRoot, "smartdocs", "doctrine", "active");
     if ((0, node_fs_1.existsSync)(doctrineDir)) {
         for (const f of (0, node_fs_1.readdirSync)(doctrineDir)) {
             if (f.endsWith(".md") && (0, node_path_1.basename)(f).toLowerCase() !== "summary.md")
@@ -61,7 +61,7 @@ function locateCanonFiles(changedFiles, repoRoot) {
         }
     }
     for (const specSubdir of ["active", "implemented"]) {
-        const specDir = (0, node_path_1.join)(repoRoot, "docs", "specs", specSubdir);
+        const specDir = (0, node_path_1.join)(repoRoot, "smartdocs", "specs", specSubdir);
         if (!(0, node_fs_1.existsSync)(specDir))
             continue;
         for (const f of (0, node_fs_1.readdirSync)(specDir)) {
@@ -124,7 +124,7 @@ function checkPolarisMd(canonFile, changedFiles, repoRoot) {
                 // Determine conflict type based on rule text and changed file
                 let conflictType = "stale-implementation";
                 const ext = changedFile.split(".").pop()?.toLowerCase() ?? "";
-                const isDocFile = ext === "md" || changedFile.startsWith("docs/");
+                const isDocFile = ext === "md" || changedFile.startsWith("smartdocs/");
                 const hasDocKeywords = /\b(doc|documentation|readme|guide|spec)\b/i.test(lower);
                 const hasCandidateKeywords = /\b(candidate|divergence|proposal)\b/i.test(lower);
                 if (isDocFile || hasDocKeywords) {
@@ -282,7 +282,7 @@ function runCanonCheck(options) {
     return result;
 }
 function writeStaleDraftDocs(conflicts, repoRoot, childId) {
-    const rawDir = (0, node_path_1.join)(repoRoot, "docs", "raw");
+    const rawDir = (0, node_path_1.join)(repoRoot, "smartdocs", "raw");
     try {
         (0, node_fs_1.mkdirSync)(rawDir, { recursive: true });
         for (const conflict of conflicts) {
@@ -309,7 +309,7 @@ function writeStaleDraftDocs(conflicts, repoRoot, childId) {
     }
 }
 function writeCandidateDraftDocs(conflicts, repoRoot, childId) {
-    const candidateDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate");
+    const candidateDir = (0, node_path_1.join)(repoRoot, "smartdocs", "doctrine", "candidate");
     try {
         (0, node_fs_1.mkdirSync)(candidateDir, { recursive: true });
         for (const conflict of conflicts) {

package/dist/smartdocs-engine/index.js

@@ -38,6 +38,32 @@ function printSeedAllResult(filename, dryRun, { written, skippedExists, skippedD
     }
     console.log(`${leadingBlankLine ? "\n" : ""}Done. ${written.length} written, ${skippedExists.length} skipped (exists), ${skippedDraft.length} skipped (draft)${extraSummary}.`);
 }
+function printReconcileReport(report, dryRun) {
+    for (const path of report.created) {
+        console.log(`${dryRun ? "[dry-run] would create" : "created"}: ${path}`);
+    }
+    for (const path of report.regenerated) {
+        console.log(`${dryRun ? "[dry-run] would regenerate" : "regenerated"}: ${path}`);
+    }
+    for (const path of report.regeneratedRegion) {
+        console.log(`${dryRun ? "[dry-run] would regenerate (region)" : "regenerated (region)"}: ${path}`);
+    }
+    for (const path of report.skipped) {
+        console.log(`skipped (up-to-date): ${path}`);
+    }
+    for (const path of report.blocked) {
+        console.log(`blocked (manual migration): ${path}`);
+    }
+    if (report.skippedRoot) {
+        console.log(`skipped (root): ${report.skippedRoot.path}/ (${report.skippedRoot.reason})`);
+    }
+    if (report.skippedIneligible.length > 0) {
+        for (const entry of report.skippedIneligible) {
+            console.log(`skipped (ineligible): ${entry.path}/ (${entry.reason})`);
+        }
+    }
+    console.log(`\nDone. ${report.created.length} created, ${report.regenerated.length} regenerated, ${report.regeneratedRegion.length} regenerated (region), ${report.skipped.length} skipped, ${report.blocked.length} blocked.`);
+}
 /**
  * Build and return the top-level "docs" Commander command group for Polaris docs lifecycle workflows.
  *
@@ -434,6 +460,34 @@ function createDocsCommand(options = {}) {
             console.log(`skipped (draft exists): ${targetPath}/index.md`);
         }
     });
+    docs
+        .command("reconcile")
+        .description("Reconcile POLARIS.md and SUMMARY.md files across all eligible route folders")
+        .option("--all", "Reconcile all eligible directories")
+        .option("--dry-run", "Print what would be changed without writing files")
+        .option("--include-agent-folders", "Include .codex, .claude, .agents folders (default: skip)")
+        .option("--include-hidden", "Include all hidden directories starting with . (default: skip)")
+        .option("--include-root", "Include root directory (default: skip)")
+        .option("-r, --repo-root <path>", "Repository root", defaultRepoRoot)
+        .action((options) => {
+        if (!options.all) {
+            console.error("Error: provide --all to reconcile all eligible directories");
+            process.exit(1);
+        }
+        try {
+            const report = (0, seed_instructions_js_1.reconcileAll)(options.repoRoot, {
+                dryRun: options.dryRun,
+                includeAgentFolders: options.includeAgentFolders,
+                includeHidden: options.includeHidden,
+                includeRoot: options.includeRoot,
+            });
+            printReconcileReport(report, options.dryRun);
+        }
+        catch (err) {
+            console.error(`polaris docs reconcile: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     docs
         .command("backfill-type")
         .description("Add OKF-conformant `type` frontmatter to existing smartdocs/ files that are missing it, " +

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",