@lsctech/polaris 0.4.4 → 0.4.5

package/dist/cli/adopt-smartdocs.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffoldBundleRoot = scaffoldBundleRoot;
 exports.migrateSmartDocs = migrateSmartDocs;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -110,6 +111,20 @@ function normalizeStatus(step, status, completedAt) {
         error: status === "completed" || status === "skipped" ? undefined : step.error,
     };
 }
+const SMARTDOCS_BUNDLE_INDEX_CONTENT = `---\nokf_version: "0.1"\n---\n\n# SmartDocs — Polaris Cognition Bundle\n\n# Governance\n\n- [Docs authority model](specs/active/docs-authority-model.md)\n- [Doctrine](doctrine/active/)\n\n# Routes\n\n<!-- Routes placeholder: dynamic file-routes.json generation deferred. -->\n`;
+const SMARTDOCS_BUNDLE_LOG_CONTENT = "# SmartDocs — Change Log\n";
+function scaffoldBundleRoot(repoRoot) {
+    const smartdocsDir = (0, node_path_1.join)(repoRoot, "smartdocs");
+    (0, node_fs_1.mkdirSync)(smartdocsDir, { recursive: true });
+    const indexPath = (0, node_path_1.join)(smartdocsDir, "index.md");
+    if (!(0, node_fs_1.existsSync)(indexPath)) {
+        (0, node_fs_1.writeFileSync)(indexPath, SMARTDOCS_BUNDLE_INDEX_CONTENT, "utf-8");
+    }
+    const logPath = (0, node_path_1.join)(smartdocsDir, "log.md");
+    if (!(0, node_fs_1.existsSync)(logPath)) {
+        (0, node_fs_1.writeFileSync)(logPath, SMARTDOCS_BUNDLE_LOG_CONTENT, "utf-8");
+    }
+}
 function migrateSmartDocs(plan, repoRoot = (0, node_path_1.resolve)(process.cwd())) {
     const effectivePlan = loadPlan(repoRoot, plan);
     const provenanceRecords = [];
@@ -194,6 +209,7 @@ function migrateSmartDocs(plan, repoRoot = (0, node_path_1.resolve)(process.cwd(
             seenRecords.add(recordKey(record));
         }
     }
+    scaffoldBundleRoot(repoRoot);
     savePlan(repoRoot, effectivePlan);
     saveProvenance(repoRoot, provenanceRecords);
     Object.assign(plan, effectivePlan);

package/dist/cognition/librarian-packet.js

@@ -90,6 +90,7 @@ function generateLibrarianPacket(options) {
     // Prohibited: anything that is not documentation or cognition
     const prohibitedWritePaths = [
         stateFile,
+        node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "cluster-state.json"),
         node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "state.json"),
         node_path_1.default.join(repoRoot, ".taskchain_artifacts"),
         node_path_1.default.join(repoRoot, ".polaris", "runs"),
@@ -143,16 +144,24 @@ function generateLibrarianPacket(options) {
 }
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function resolveStateFile(repoRoot, clusterId) {
-    const canonical = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "state.json");
-    if (node_fs_1.default.existsSync(canonical))
-        return canonical;
+    // Check current convention: cluster-state.json
+    const clusterState = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "cluster-state.json");
+    if (node_fs_1.default.existsSync(clusterState))
+        return clusterState;
+    // Check legacy convention: state.json
+    const legacyState = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "state.json");
+    if (node_fs_1.default.existsSync(legacyState))
+        return legacyState;
+    // Check taskchain artifacts fallback
     const taskchain = node_path_1.default.join(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
     if (node_fs_1.default.existsSync(taskchain))
         return taskchain;
-    const legacy = node_path_1.default.join(repoRoot, ".polaris", "runs", "current-state.json");
-    if (node_fs_1.default.existsSync(legacy))
-        return legacy;
-    return canonical;
+    // Check legacy runs fallback
+    const legacyRuns = node_path_1.default.join(repoRoot, ".polaris", "runs", "current-state.json");
+    if (node_fs_1.default.existsSync(legacyRuns))
+        return legacyRuns;
+    // Return current convention path as default
+    return clusterState;
 }
 function findResultFile(resultsDir, childId) {
     try {

package/dist/loop/adapters/cli-subtask-bridge.js

@@ -65,6 +65,7 @@ function writeSealedResultFromSummary(packet, parsedSummary) {
     const validation = parsedSummary["validation"] ?? parsedSummary["validation_summary"];
     const sealedResult = {
         run_id: packet.run_id,
+        cluster_id: packet.cluster_id,
         child_id: packet.active_child,
         status: normalizeSealedStatus(parsedSummary["status"]),
     };

package/dist/loop/adapters/terminal-cli.js

@@ -320,6 +320,7 @@ class TerminalCliAdapter {
             const sealedResult = {
                 ...normalized,
                 run_id: packet.run_id,
+                cluster_id: packet.cluster_id,
                 child_id: String(normalized["child_id"] ?? packet.active_child),
                 status: effectiveStatus,
                 commit: typeof normalized["commit"] === "string"

package/dist/loop/body-parser.js

@@ -123,6 +123,10 @@ function parseSections(body) {
 /**
  * Extracts bullet list items from the given text and returns them as trimmed strings.
  *
+ * This is a generic list parser used by all section types (Validation, Acceptance
+ * Criteria, Ordering, Non-goals, etc.). It does NOT strip parenthetical annotations
+ * — that logic is scope-specific and handled separately.
+ *
  * @param text - Section content to scan for bullet list lines (lines starting with `- ` or `* `)
  * @returns The extracted list item strings, trimmed of whitespace; empty items are omitted.
  */
@@ -133,9 +137,25 @@ function parseListItems(text) {
         .map((line) => line.replace(/^\s*[-*]\s+/, '').trim())
         .filter((s) => s.length > 0);
 }
+/**
+ * Removes trailing parenthetical annotations from a string.
+ *
+ * Used exclusively for Scope section items to strip annotations like "(new)" or
+ * "(thread flag through...)" so that allowed_scope entries in worker packets
+ * contain only bare file paths or valid glob patterns.
+ *
+ * @param s - The string to process
+ * @returns The input string with trailing `(...)` removed, re-trimmed
+ */
+function stripTrailingParenthetical(s) {
+    return s.replace(/\s*\([^)]*\)\s*$/, '').trim();
+}
 /**
  * Extracts list items from the first section whose header matches a provided set.
  *
+ * This is a generic section parser that does NOT apply any parenthetical stripping.
+ * For Scope sections, use `findScopeSection` instead.
+ *
  * @param sections - Map of normalized header names to their section content; iteration follows the map's order
  * @param headers - Set of normalized header names to match against section headers
  * @returns An array of parsed list-item strings from the first matching section, or an empty array if no match is found
@@ -148,6 +168,25 @@ function findSection(sections, headers) {
     }
     return [];
 }
+/**
+ * Extracts list items from the Scope section, stripping trailing parenthetical annotations.
+ *
+ * Scope section items often include human-readable annotations like "(new)" or
+ * "(thread flag through...)". These are stripped so that allowed_scope entries in
+ * worker packets contain only bare file paths or valid glob patterns.
+ *
+ * @param sections - Map of normalized header names to their section content
+ * @param headers - Set of normalized Scope header variants (e.g., SCOPE_HEADERS)
+ * @returns An array of scope paths with parentheticals removed, or an empty array if no Scope section is found
+ */
+function findScopeSection(sections, headers) {
+    for (const [header, content] of sections) {
+        if (headers.has(header)) {
+            return parseListItems(content).map(stripTrailingParenthetical).filter((s) => s.length > 0);
+        }
+    }
+    return [];
+}
 /**
  * Returns trimmed prose text from the first section matching a header set.
  * Used for single-paragraph sections (Objective, Context, Goal).
@@ -189,7 +228,7 @@ function parseIssueBody(body) {
         };
     }
     const sections = parseSections(body);
-    const rawScope = findSection(sections, SCOPE_HEADERS);
+    const rawScope = findScopeSection(sections, SCOPE_HEADERS);
     const scopeBlocked = rawScope.length > 0 && rawScope.every((item) => TBD_BLOCKED_RE.test(item));
     const filteredScope = rawScope.filter((item) => !TBD_BLOCKED_RE.test(item));
     return {

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

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCanonCheck = runCanonCheck;
+exports.runSmartDocsLinkCheck = runSmartDocsLinkCheck;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const doctrine_js_1 = require("./doctrine.js");
 // Modal verbs that indicate behavioral assertions in doctrine/spec files
 const MODAL_VERBS = /\b(must|never|always|should|required|requires|shall)\b/i;
 // Domains matched by filename keywords
@@ -338,3 +340,81 @@ function writeCandidateDraftDocs(conflicts, repoRoot, childId) {
         // Non-fatal
     }
 }
+/** Subdirectories of smartdocs/ that are subject to strict link checking */
+const STRICT_SMARTDOCS_DIRS = [
+    (0, node_path_1.join)("smartdocs", "doctrine", "candidate"),
+    (0, node_path_1.join)("smartdocs", "doctrine", "active"),
+    (0, node_path_1.join)("smartdocs", "specs", "candidate"),
+    (0, node_path_1.join)("smartdocs", "specs", "active"),
+];
+/**
+ * Recursively walk a directory and return all .md file paths.
+ *
+ * @param dir - Directory to walk
+ * @returns Array of absolute paths to all .md files found recursively
+ */
+function walkMarkdownFiles(dir) {
+    const results = [];
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const fullPath = (0, node_path_1.join)(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkMarkdownFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+/**
+ * Walk the strict-tier smartdocs directories (candidate/ and active/ under doctrine/ and specs/)
+ * and check every .md file for broken cross-links into smartdocs/.
+ *
+ * Recursively traverses subdirectories to find nested documents.
+ * Files in raw/ are never checked (OKF §5.3 permissive default).
+ * Broken links are reported as SpecConflict entries with type "stale-assumption".
+ *
+ * @param options - Options including repoRoot, runId, and telemetryFile
+ * @returns Object with all detected conflicts and the count of files checked
+ */
+function runSmartDocsLinkCheck(options) {
+    const { repoRoot, runId, telemetryFile, childId } = options;
+    const root = (0, node_path_1.resolve)(repoRoot);
+    const allConflicts = [];
+    let filesChecked = 0;
+    for (const subdir of STRICT_SMARTDOCS_DIRS) {
+        const dir = (0, node_path_1.join)(root, subdir);
+        if (!(0, node_fs_1.existsSync)(dir))
+            continue;
+        const markdownFiles = walkMarkdownFiles(dir);
+        for (const filePath of markdownFiles) {
+            let content;
+            try {
+                content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            filesChecked++;
+            const conflicts = (0, doctrine_js_1.checkSmartDocsLinks)(filePath, content, root);
+            allConflicts.push(...conflicts);
+        }
+    }
+    appendTelemetry(telemetryFile, {
+        event: "smartdocs-link-check-result",
+        run_id: runId,
+        child_id: childId ?? null,
+        files_checked: filesChecked,
+        broken_links: allConflicts.length,
+        conflicts: allConflicts,
+        timestamp: new Date().toISOString(),
+    });
+    return { conflicts: allConflicts, filesChecked };
+}

package/dist/smartdocs-engine/doctrine.js

@@ -7,6 +7,8 @@ exports.stampIngestFrontMatter = stampIngestFrontMatter;
 exports.doctrineDraft = doctrineDraft;
 exports.doctrinePromote = doctrinePromote;
 exports.doctrineDeprecate = doctrineDeprecate;
+exports.detectDoctrineSupersession = detectDoctrineSupersession;
+exports.checkSmartDocsLinks = checkSmartDocsLinks;
 exports.specPromote = specPromote;
 exports.migrateProvenance = migrateProvenance;
 const node_fs_1 = require("node:fs");
@@ -186,6 +188,59 @@ function appendLifecycle(lifecyclePath, event) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(lifecyclePath), { recursive: true });
     (0, node_fs_1.appendFileSync)(lifecyclePath, JSON.stringify(event) + "\n", "utf-8");
 }
+const DIRECTORY_LOG_HEADER = "# Directory Update Log";
+/**
+ * Append a dated prose entry to a per-directory log.md file, following the OKF convention:
+ * date-grouped YYYY-MM-DD headings, newest-first, with a bold verb prefix.
+ *
+ * Creates the file with the canonical header if it does not yet exist. If the
+ * newest heading already matches today's date, the entry is inserted under that
+ * heading; otherwise a new today's heading is prepended before the existing entries.
+ *
+ * This function is best-effort: failures during read/write are caught and logged
+ * as warnings but do not propagate to the caller, ensuring log.md update failures
+ * do not block directory transitions.
+ *
+ * @param directory - Directory that contains (or will contain) log.md
+ * @param verb - Lifecycle verb rendered as the bold prefix (Draft, Promote, Deprecate)
+ * @param reason - Human-readable prose entry for this change
+ */
+function logDirectoryChange(directory, verb, reason) {
+    try {
+        const logPath = (0, node_path_1.join)(directory, "log.md");
+        const today = new Date().toISOString().slice(0, 10);
+        const entry = `**${verb}**: ${reason}`;
+        let content = (0, node_fs_1.existsSync)(logPath) ? (0, node_fs_1.readFileSync)(logPath, "utf-8") : "";
+        content = content.replace(/\r\n/g, "\n");
+        const todayHeading = `## ${today}`;
+        // Use anchored regex to match heading at start of line, not substring in prose.
+        const firstHeadingMatch = content.match(/^## (\d{4}-\d{2}-\d{2})/m);
+        if (firstHeadingMatch && firstHeadingMatch[1] === today) {
+            // Find the actual heading line position using anchored search.
+            const headingMatch = content.match(new RegExp(`^${todayHeading}`, 'm'));
+            if (headingMatch && headingMatch.index !== undefined) {
+                const headingIndex = headingMatch.index;
+                const afterHeading = headingIndex + todayHeading.length;
+                const newContent = `${content.slice(0, afterHeading)}\n${entry}${content.slice(afterHeading)}`;
+                (0, node_fs_1.writeFileSync)(logPath, newContent, "utf-8");
+            }
+        }
+        else if (content.trim().startsWith(DIRECTORY_LOG_HEADER)) {
+            const afterHeader = content.indexOf(DIRECTORY_LOG_HEADER) + DIRECTORY_LOG_HEADER.length;
+            const tail = content.slice(afterHeader).replace(/^\n*/, "\n\n");
+            const newContent = `${DIRECTORY_LOG_HEADER}\n\n${todayHeading}\n${entry}${tail}`;
+            (0, node_fs_1.writeFileSync)(logPath, newContent, "utf-8");
+        }
+        else {
+            const existing = content.trim() ? `${content}\n\n` : "";
+            (0, node_fs_1.writeFileSync)(logPath, `${DIRECTORY_LOG_HEADER}\n\n${todayHeading}\n${entry}\n${existing}`, "utf-8");
+        }
+    }
+    catch (err) {
+        // Best-effort: log warning but do not propagate failure.
+        console.warn(`[warn] Failed to update log.md in ${directory}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 /**
  * Resolve a filesystem path against a repository root and return an absolute path.
  *
@@ -236,6 +291,8 @@ function doctrineDraft(path, options) {
         destination,
         timestamp: new Date().toISOString(),
     });
+    const reason = options.reason ?? `${(0, node_path_1.basename)(destination)} drafted to doctrine/candidate/`;
+    logDirectoryChange((0, node_path_1.dirname)(destination), "Draft", reason);
     return { source, destination, runId, lifecyclePath };
 }
 /**
@@ -322,6 +379,8 @@ function doctrinePromote(path, options) {
         destination,
         timestamp: new Date().toISOString(),
     });
+    const reason = options.reason ?? `${(0, node_path_1.basename)(destination)} promoted to doctrine/active/`;
+    logDirectoryChange((0, node_path_1.dirname)(destination), "Promote", reason);
     return { source, destination, runId, lifecyclePath };
 }
 /**
@@ -371,6 +430,8 @@ function doctrineDeprecate(path, options) {
         deprecated_at: deprecatedAt,
         timestamp: deprecatedAt,
     });
+    const reason = options.reason ?? `${(0, node_path_1.basename)(destination)} deprecated to doctrine/deprecated/`;
+    logDirectoryChange((0, node_path_1.dirname)(destination), "Deprecate", reason);
     return { source, destination, runId, lifecyclePath };
 }
 // ── Spec verb-keyword conflict detection ──────────────────────────────────────
@@ -390,6 +451,174 @@ function extractSpecKeywords(content, pattern) {
     }
     return result;
 }
+/**
+ * Compute the Jaccard similarity between two keyword sets.
+ * Returns a value in [0, 1]; 0 means no overlap, 1 means identical.
+ */
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const kw of a) {
+        if (b.has(kw))
+            intersection++;
+    }
+    return intersection / (a.size + b.size - intersection);
+}
+/**
+ * Extract a combined keyword set from a document using both REQUIRES and PROHIBITS patterns.
+ * Reuses the existing extractSpecKeywords function — no second algorithm.
+ */
+function extractAllKeywords(content) {
+    const requires = extractSpecKeywords(content, MODAL_REQUIRES);
+    const prohibits = extractSpecKeywords(content, MODAL_PROHIBITS);
+    return new Set([...requires, ...prohibits]);
+}
+// Jaccard threshold above which an active doc is considered a supersession candidate.
+// 0.3 is deliberately permissive: better to surface an advisory than to miss it.
+const SUPERSESSION_THRESHOLD = 0.3;
+/**
+ * Detect whether an incoming doctrine-candidate document has high content overlap with
+ * any existing active doctrine document. When overlap exceeds the threshold, the active
+ * doc is returned as a suggested-supersession advisory conflict.
+ *
+ * This is report-only: it never writes to `supersedes`/`superseded_by` frontmatter.
+ * The caller (or the user via CLI) decides whether to act on the suggestion.
+ *
+ * @param candidatePath - Absolute or repo-relative path to the candidate document
+ * @param options       - Doctrine options (must include `repoRoot`)
+ * @returns Array of SpecConflict entries with type "suggested-supersession"; empty when
+ *          no active docs exist or no overlap exceeds the threshold
+ */
+function detectDoctrineSupersession(candidatePath, options) {
+    const repoRoot = (0, node_path_1.resolve)(options.repoRoot);
+    const source = resolvePath(candidatePath, repoRoot);
+    if (!(0, node_fs_1.existsSync)(source))
+        return [];
+    let candidateContent;
+    try {
+        candidateContent = (0, node_fs_1.readFileSync)(source, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const candidateKeywords = extractAllKeywords(candidateContent);
+    // No keywords in candidate → no meaningful overlap can be computed
+    if (candidateKeywords.size === 0)
+        return [];
+    const activeDir = (0, node_path_1.resolve)(repoRoot, "smartdocs", "doctrine", "active");
+    if (!(0, node_fs_1.existsSync)(activeDir))
+        return [];
+    const conflicts = [];
+    let activeFiles;
+    try {
+        activeFiles = (0, node_fs_1.readdirSync)(activeDir).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+    for (const file of activeFiles) {
+        let activeContent;
+        try {
+            activeContent = (0, node_fs_1.readFileSync)((0, node_path_1.join)(activeDir, file), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const activeKeywords = extractAllKeywords(activeContent);
+        if (activeKeywords.size === 0)
+            continue;
+        const score = jaccardSimilarity(candidateKeywords, activeKeywords);
+        if (score >= SUPERSESSION_THRESHOLD) {
+            conflicts.push({
+                type: "suggested-supersession",
+                conflictingFile: file,
+                detail: `candidate has ${Math.round(score * 100)}% keyword overlap with active doc "${file}" — consider adding supersedes: ${file.replace(/\.md$/, "")} to frontmatter`,
+            });
+        }
+    }
+    return conflicts;
+}
+// Regex to extract markdown links: [text](href)
+const MD_LINK_RE = /\[([^\]]*)\]\(([^)]+)\)/g;
+// Tiers that are subject to strict link checking (raw/ is permissive per OKF §5.3)
+const STRICT_LINK_TIERS = ["candidate", "active"];
+/**
+ * Determine whether a file path is in a strict-check tier (candidate/ or active/)
+ * under smartdocs/. Returns false for raw/ or anything outside smartdocs/.
+ */
+function isStrictTier(filePath, repoRoot) {
+    const rel = (0, node_path_1.relative)((0, node_path_1.resolve)(repoRoot), (0, node_path_1.resolve)(filePath)).replace(/\\/g, "/");
+    if (!rel.startsWith("smartdocs/"))
+        return false;
+    return STRICT_LINK_TIERS.some((tier) => rel.includes(`/${tier}/`) || rel.includes(`/${tier}\\`));
+}
+/**
+ * Resolve a markdown link href found in `sourceFile` to an absolute filesystem path.
+ *
+ * Supports two forms:
+ *   - Bundle-relative: `/smartdocs/...` — resolved from repoRoot
+ *   - Relative: `./foo.md`, `../foo.md`, `foo.md` — resolved from the source file's directory
+ *
+ * Returns null if the href does not point into smartdocs/ (e.g. external URLs, src/ links).
+ */
+function resolveSmartDocsLink(href, sourceFile, repoRoot) {
+    // Strip anchors
+    const bare = href.split("#")[0];
+    if (!bare.endsWith(".md"))
+        return null;
+    let abs;
+    if (bare.startsWith("/")) {
+        // Bundle-relative: treat / as repoRoot
+        abs = (0, node_path_1.join)((0, node_path_1.resolve)(repoRoot), bare.slice(1));
+    }
+    else if (bare.startsWith("http://") || bare.startsWith("https://")) {
+        return null;
+    }
+    else {
+        // Relative to source file's directory
+        abs = (0, node_path_1.join)((0, node_path_1.dirname)((0, node_path_1.resolve)(sourceFile)), bare);
+    }
+    // Only check links that land inside smartdocs/
+    const rel = (0, node_path_1.relative)((0, node_path_1.resolve)(repoRoot), abs).replace(/\\/g, "/");
+    if (!rel.startsWith("smartdocs/"))
+        return null;
+    return abs;
+}
+/**
+ * Check all markdown cross-links in a strict-tier (candidate/ or active/) SmartDoc.
+ *
+ * For each link whose href resolves into smartdocs/**, verifies the target exists.
+ * Missing targets are returned as SpecConflict entries with type "stale-assumption".
+ * Files from raw/ are never checked — pass isRaw=true or detect via filePath.
+ *
+ * @param filePath - Absolute path to the source document
+ * @param content  - File content (already read by caller)
+ * @param repoRoot - Repository root directory
+ * @returns Array of stale-assumption conflicts for every broken smartdocs/ link
+ */
+function checkSmartDocsLinks(filePath, content, repoRoot) {
+    if (!isStrictTier(filePath, repoRoot))
+        return [];
+    const conflicts = [];
+    const re = new RegExp(MD_LINK_RE.source, MD_LINK_RE.flags);
+    for (const match of content.matchAll(re)) {
+        const href = match[2];
+        if (!href)
+            continue;
+        const target = resolveSmartDocsLink(href, filePath, repoRoot);
+        if (target === null)
+            continue; // not a smartdocs/ link — skip
+        if (!(0, node_fs_1.existsSync)(target)) {
+            conflicts.push({
+                type: "stale-assumption",
+                conflictingFile: (0, node_path_1.relative)((0, node_path_1.resolve)(repoRoot), (0, node_path_1.resolve)(filePath)).replace(/\\/g, "/"),
+                detail: `broken link: "${href}" → target not found: ${(0, node_path_1.relative)((0, node_path_1.resolve)(repoRoot), target).replace(/\\/g, "/")}`,
+            });
+        }
+    }
+    return conflicts;
+}
 /**
  * Promotes a spec file from smartdocs/raw/ into smartdocs/specs/active/.
  *
@@ -529,6 +758,8 @@ function specPromote(path, options) {
         approved: options.approve ?? false,
         timestamp: new Date().toISOString(),
     });
+    const reason = options.reason ?? `${(0, node_path_1.basename)(destination)} promoted to specs/active/`;
+    logDirectoryChange((0, node_path_1.dirname)(destination), "Promote", reason);
     return { source, destination, runId, lifecyclePath, conflicts, halted: false, report };
 }
 /**

package/dist/smartdocs-engine/index.js

@@ -402,6 +402,42 @@ function createDocsCommand(options = {}) {
             console.log(`skipped (draft exists): ${pathArg}/SUMMARY.md`);
         }
     });
+    docs
+        .command("seed-index [path]")
+        .description("Generate OKF-conformant index.md files for smartdocs/")
+        .option("-r, --repo-root <path>", "Repository root", defaultRepoRoot)
+        .option("--all", "Generate index.md for all smartdocs directories lacking one")
+        .option("--dry-run", "Print what would be written without writing files")
+        .action((pathArg, options) => {
+        if (options.all) {
+            const { written, skippedExists, skippedDraft, } = (0, seed_instructions_js_1.seedIndexAll)(options.repoRoot, {
+                dryRun: options.dryRun,
+            });
+            for (const dir of written) {
+                console.log(`${options.dryRun ? "[dry-run] would write" : "written"}: ${dir}/index.md`);
+            }
+            for (const dir of skippedExists) {
+                console.log(`skipped (human-edited): ${dir}/index.md`);
+            }
+            for (const dir of skippedDraft) {
+                console.log(`skipped (draft exists): ${dir}/index.md`);
+            }
+            console.log(`\nDone. ${written.length} written, ${skippedExists.length} skipped (exists), ${skippedDraft.length} skipped (draft).`);
+            return;
+        }
+        const targetPath = pathArg || "smartdocs";
+        const result = (0, seed_instructions_js_1.seedIndex)(targetPath, options.repoRoot, { dryRun: options.dryRun });
+        if (result === "written") {
+            const label = options.dryRun ? "[dry-run] would write" : "written";
+            console.log(`${label}: ${targetPath}/index.md`);
+        }
+        else if (result === "skipped-exists") {
+            console.warn(`warning: ${targetPath}/index.md already exists (no draft marker) — skipped`);
+        }
+        else {
+            console.log(`skipped (draft exists): ${targetPath}/index.md`);
+        }
+    });
     docs
         .command("audit")
         .description("Scan repo for files at risk of recursive ingestion")
@@ -464,9 +500,10 @@ function createDoctrineCommand() {
         .description("Move a doc from smartdocs/raw/ or smartdocs/doctrine/raw/ to docs/doctrine/candidate/")
         .option("-r, --repo-root <path>", "Repository root", process.cwd())
         .option("--run-id <id>", "Override the generated doctrine run ID")
+        .option("--reason <text>", "Reason for this draft")
         .action((path, options) => {
         try {
-            const result = (0, doctrine_js_1.doctrineDraft)(path, { repoRoot: options.repoRoot, runId: options.runId });
+            const result = (0, doctrine_js_1.doctrineDraft)(path, { repoRoot: options.repoRoot, runId: options.runId, reason: options.reason });
             console.log(`drafted: ${result.destination}`);
             console.log(`provenance: ${result.lifecyclePath}`);
         }
@@ -480,11 +517,13 @@ function createDoctrineCommand() {
         .description("Move a doc from smartdocs/doctrine/candidate/ to smartdocs/doctrine/active/")
         .option("-r, --repo-root <path>", "Repository root", process.cwd())
         .option("--run-id <id>", "Override the generated doctrine run ID")
+        .option("--reason <text>", "Reason for this promotion")
         .action((path, options) => {
         try {
             const result = (0, doctrine_js_1.doctrinePromote)(path, {
                 repoRoot: options.repoRoot,
-                runId: options.runId
+                runId: options.runId,
+                reason: options.reason,
             });
             console.log(`promoted: ${result.destination}`);
             console.log(`provenance: ${result.lifecyclePath}`);
@@ -499,11 +538,13 @@ function createDoctrineCommand() {
         .description("Move a doc from smartdocs/doctrine/active/ to smartdocs/doctrine/deprecated/")
         .option("-r, --repo-root <path>", "Repository root", process.cwd())
         .option("--run-id <id>", "Override the generated doctrine run ID")
+        .option("--reason <text>", "Reason for this deprecation")
         .action((path, options) => {
         try {
             const result = (0, doctrine_js_1.doctrineDeprecate)(path, {
                 repoRoot: options.repoRoot,
                 runId: options.runId,
+                reason: options.reason,
             });
             console.log(`deprecated: ${result.destination}`);
             console.log(`provenance: ${result.lifecyclePath}`);
@@ -519,12 +560,14 @@ function createDoctrineCommand() {
         .option("-r, --repo-root <path>", "Repository root", process.cwd())
         .option("--run-id <id>", "Override the generated run ID")
         .option("--approve", "Proceed despite detected conflicts")
+        .option("--reason <text>", "Reason for this promotion")
         .action((path, options) => {
         try {
             const result = (0, doctrine_js_1.specPromote)(path, {
                 repoRoot: options.repoRoot,
                 runId: options.runId,
                 approve: options.approve,
+                reason: options.reason,
             });
             console.log(result.report);
             if (result.halted) {

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

@@ -4,15 +4,20 @@ exports.DRAFT_MARKER = void 0;
 exports.hasDraftMarker = hasDraftMarker;
 exports.generateDraft = generateDraft;
 exports.generateSummaryDraft = generateSummaryDraft;
+exports.generateBundleRootIndex = generateBundleRootIndex;
+exports.generateDirectoryIndex = generateDirectoryIndex;
 exports.seedInstructions = seedInstructions;
 exports.seedSummary = seedSummary;
 exports.seedInstructionsAll = seedInstructionsAll;
 exports.seedSummaryAll = seedSummaryAll;
+exports.seedIndex = seedIndex;
+exports.seedIndexAll = seedIndexAll;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const loader_js_1 = require("../config/loader.js");
 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 -->";
 function hasDraftMarker(filePath) {
     try {
@@ -176,6 +181,132 @@ function generateSummaryDraft(targetDir, repoRoot, _allRoutes) {
     ];
     return lines.join("\n");
 }
+const RESERVED_INDEX_NAMES = new Set(["index.md", "POLARIS.md", "SUMMARY.md", "log.md"]);
+function isReservedIndexName(name) {
+    return RESERVED_INDEX_NAMES.has(name);
+}
+function listConceptFiles(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(".md") && !isReservedIndexName(e.name))
+            .map((e) => (0, node_path_1.join)(dir, e.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function conceptLabel(filePath) {
+    try {
+        const content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+        const fm = (0, doctrine_js_1.parseFrontMatter)(content);
+        const base = (0, node_path_1.basename)(filePath);
+        return fm.description || fm.title || base.replace(/\.md$/, "");
+    }
+    catch {
+        return (0, node_path_1.basename)(filePath).replace(/\.md$/, "");
+    }
+}
+function collectSmartDocsDirs(dir, root, result = []) {
+    try {
+        const rel = (0, node_path_1.relative)(root, dir).replace(/\\/g, "/");
+        if (rel.split("/").some((s) => s === "raw" || s.startsWith("."))) {
+            return result;
+        }
+        result.push(rel);
+        for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith(".") || entry.name === "raw")
+                continue;
+            const full = (0, node_path_1.join)(dir, entry.name);
+            collectSmartDocsDirs(full, root, result);
+        }
+    }
+    catch {
+        // ignore unreadable dirs
+    }
+    return result;
+}
+function generateBundleRootIndex(repoRoot, allRoutes) {
+    const lines = [
+        "---",
+        "okf_version: \"0.1\"",
+        "---",
+        "",
+        exports.DRAFT_MARKER,
+        "# SmartDocs — Polaris Cognition Bundle",
+        "",
+        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "",
+        "## Governance",
+        "",
+    ];
+    const doctrineDir = (0, node_path_1.join)(repoRoot, "smartdocs", "doctrine", "active");
+    const doctrineFiles = listConceptFiles(doctrineDir);
+    if (doctrineFiles.length > 0) {
+        for (const file of doctrineFiles) {
+            const relPath = (0, node_path_1.relative)((0, node_path_1.join)(repoRoot, "smartdocs"), file).replace(/\\/g, "/");
+            lines.push(`- [${conceptLabel(file)}](${relPath})`);
+        }
+    }
+    else {
+        lines.push("- [Doctrine — Active](doctrine/active/)");
+    }
+    lines.push("");
+    lines.push("## Specs", "");
+    const specsDir = (0, node_path_1.join)(repoRoot, "smartdocs", "specs", "active");
+    const specsFiles = listConceptFiles(specsDir);
+    if (specsFiles.length > 0) {
+        for (const file of specsFiles) {
+            const relPath = (0, node_path_1.relative)((0, node_path_1.join)(repoRoot, "smartdocs"), file).replace(/\\/g, "/");
+            lines.push(`- [${conceptLabel(file)}](${relPath})`);
+        }
+    }
+    else {
+        lines.push("- [Specs — Active](specs/active/)");
+    }
+    lines.push("");
+    lines.push("## Routes", "");
+    const instructionFiles = [
+        ...new Set(Object.values(allRoutes).map((e) => e.instructionFile).filter(Boolean)),
+    ].sort();
+    if (instructionFiles.length > 0) {
+        for (const file of instructionFiles) {
+            lines.push(`- [${file}](../${file})`);
+        }
+    }
+    else {
+        lines.push("<!-- Route POLARIS.md files will be listed here from atlas signals. -->");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function generateDirectoryIndex(targetDir, repoRoot) {
+    const absDir = (0, node_path_1.resolve)(repoRoot, targetDir);
+    const dirLabel = (0, node_path_1.basename)(absDir) || "SmartDocs";
+    const files = listConceptFiles(absDir);
+    const lines = [
+        exports.DRAFT_MARKER,
+        `# ${dirLabel}`,
+        "",
+        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "",
+        "## Concepts",
+        "",
+    ];
+    if (files.length > 0) {
+        for (const file of files) {
+            const relPath = (0, node_path_1.relative)(absDir, file).replace(/\\/g, "/");
+            lines.push(`- [${conceptLabel(file)}](${relPath})`);
+        }
+    }
+    else {
+        lines.push("<!-- No concept files in this directory yet. -->");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
 function seedInstructions(targetPath, repoRoot, opts = {}) {
     const absTarget = (0, node_path_1.resolve)(repoRoot, targetPath);
     // Path traversal check: ensure absTarget is within repoRoot
@@ -333,3 +464,78 @@ function seedSummaryAll(repoRoot, opts = {}) {
     }
     return { written, skippedExists, skippedDraft, skippedIneligible, skippedRoot };
 }
+function seedIndex(targetPath, repoRoot, opts = {}) {
+    const absTarget = (0, node_path_1.resolve)(repoRoot, targetPath);
+    const relCheck = (0, node_path_1.relative)(repoRoot, absTarget);
+    if (relCheck.startsWith("..") || relCheck.startsWith("/")) {
+        throw new Error(`Path traversal detected: target path is outside repo root`);
+    }
+    // Reject targets outside smartdocs/
+    const relTarget = relCheck.replace(/\\/g, "/");
+    if (!relTarget.startsWith("smartdocs/") && relTarget !== "smartdocs") {
+        throw new Error(`seedIndex only writes index.md under smartdocs/; rejecting target: ${relTarget}`);
+    }
+    const outFile = (0, node_path_1.join)(absTarget, "index.md");
+    if ((0, node_fs_1.existsSync)(outFile)) {
+        if (hasDraftMarker(outFile)) {
+            return "skipped-draft";
+        }
+        return "skipped-exists";
+    }
+    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),
+    };
+    const isBundleRoot = relTarget === "smartdocs";
+    const content = isBundleRoot
+        ? generateBundleRootIndex(repoRoot, allRoutes)
+        : generateDirectoryIndex(relTarget, repoRoot);
+    if (!opts.dryRun) {
+        (0, node_fs_1.writeFileSync)(outFile, content, "utf-8");
+    }
+    return "written";
+}
+function seedIndexAll(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),
+    };
+    const smartdocsRoot = (0, node_path_1.resolve)(repoRoot, "smartdocs");
+    if (!(0, node_fs_1.existsSync)(smartdocsRoot)) {
+        return { written: [], skippedExists: [], skippedDraft: [], skippedIneligible: [] };
+    }
+    const dirs = collectSmartDocsDirs(smartdocsRoot, repoRoot);
+    const smartdocsRel = "smartdocs";
+    if (!dirs.includes(smartdocsRel)) {
+        dirs.unshift(smartdocsRel);
+    }
+    const written = [];
+    const skippedExists = [];
+    const skippedDraft = [];
+    for (const relDir of dirs) {
+        const absDir = (0, node_path_1.resolve)(repoRoot, relDir);
+        const outFile = (0, node_path_1.join)(absDir, "index.md");
+        if ((0, node_fs_1.existsSync)(outFile)) {
+            if (hasDraftMarker(outFile)) {
+                skippedDraft.push(relDir);
+            }
+            else {
+                skippedExists.push(relDir);
+            }
+            continue;
+        }
+        const isBundleRoot = relDir === "smartdocs";
+        const content = isBundleRoot
+            ? generateBundleRootIndex(repoRoot, allRoutes)
+            : generateDirectoryIndex(relDir, repoRoot);
+        if (!opts.dryRun) {
+            (0, node_fs_1.writeFileSync)(outFile, content, "utf-8");
+        }
+        written.push(relDir);
+    }
+    return { written, skippedExists, skippedDraft, skippedIneligible: [] };
+}

package/package.json

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