@lsctech/polaris 0.1.0

package/dist/cognition/route-cognition-delta.js

@@ -0,0 +1,350 @@
+"use strict";
+/**
+ * Route-local cognition delta logic.
+ *
+ * Workers call applyRouteCognitionDelta() after implementation to determine
+ * whether POLARIS.md needs updating for the folders they touched. Updates are
+ * delta-only: only apply when operationally-relevant changes occurred.
+ *
+ * Root cognition surfaces (POLARIS.md at repo root) are skipped unless
+ * explicitly opted in. Bounded by locality — no repo-wide scanning.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLARIS_OWNED_COGNITION_FOLDERS = void 0;
+exports.assessRouteHealth = assessRouteHealth;
+exports.isPolarisOwnedFolder = isPolarisOwnedFolder;
+exports.isUserCreatedCognitionSurface = isUserCreatedCognitionSurface;
+exports.isCognitionSkippedFolder = isCognitionSkippedFolder;
+exports.findNearestRoutePolarismd = findNearestRoutePolarismd;
+exports.detectOperationalReasons = detectOperationalReasons;
+exports.applyRouteCognitionDelta = applyRouteCognitionDelta;
+exports.readRoutePolarismd = readRoutePolarismd;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const smartdoc_ignore_js_1 = require("../smartdocs-engine/smartdoc-ignore.js");
+// ── Route Health Assessment ───────────────────────────────────────────────────
+/**
+ * Assess the health state of a route based on observable signals.
+ *
+ * Signals used:
+ * - Staleness: entry older than threshold (default 90 days)
+ * - Identity completeness: missing instructionFile or role_owner
+ *
+ * Returns:
+ * - "stale": entry is stale (older than threshold)
+ * - "known-issues": identity incomplete (missing instructionFile or role_owner)
+ * - "healthy": route is fresh, identity complete
+ */
+function assessRouteHealth(route, repoRoot, staleThresholdDays = 90) {
+    const daysSinceUpdate = (Date.now() - new Date(route.last_updated).getTime()) / (1000 * 60 * 60 * 24);
+    // Staleness check (highest priority)
+    if (daysSinceUpdate > staleThresholdDays) {
+        return "stale";
+    }
+    // Identity completeness check
+    const hasInstructionFile = route.instructionFile !== undefined && route.instructionFile !== null && route.instructionFile.trim() !== "";
+    const hasRoleOwner = route.role_owner !== undefined && route.role_owner !== null && route.role_owner.trim() !== "";
+    if (!hasInstructionFile || !hasRoleOwner) {
+        return "known-issues";
+    }
+    // Cognition surface check: instructionFile configured but file missing on disk
+    const instructionFileAbs = (0, node_path_1.join)(repoRoot, route.instructionFile);
+    if (!(0, node_fs_1.existsSync)(instructionFileAbs)) {
+        return "monitoring";
+    }
+    // Recovery window: recently updated (7–threshold days ago)
+    if (daysSinceUpdate > 7) {
+        return "recovering";
+    }
+    return "healthy";
+}
+// ── Skipped folder patterns ───────────────────────────────────────────────────
+const SKIP_FOLDER_PREFIXES = [
+    ".git/",
+    "node_modules/",
+    "dist/",
+    ".taskchain_artifacts/",
+];
+const AGENT_OPT_IN_FOLDERS = new Set([".claude", ".codex"]);
+const POLARIS_RUNTIME_COGNITION_FOLDERS = new Set([
+    ".polaris",
+    ".polaris/bootstrap",
+    ".polaris/clusters",
+    ".polaris/map",
+    ".polaris/runs",
+]);
+const POLARIS_RUNTIME_GENERATED_PREFIXES = [
+    ".polaris/bootstrap/",
+    ".polaris/clusters/",
+    ".polaris/graph/",
+    ".polaris/map/",
+    ".polaris/runs/",
+];
+exports.POLARIS_OWNED_COGNITION_FOLDERS = [
+    ".polaris",
+    "src",
+    "smartdocs/specs/active",
+    "smartdocs/doctrine/active",
+];
+function normalizeRelPath(input) {
+    return input.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+function readManagedSurfaceManifest(repoRoot) {
+    const manifestPath = (0, node_path_1.join)(repoRoot, ".polaris", "cognition", "managed-surfaces.json");
+    if (!(0, node_fs_1.existsSync)(manifestPath))
+        return new Set();
+    const raw = (0, node_fs_1.readFileSync)(manifestPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const paths = [];
+    if (Array.isArray(parsed)) {
+        for (const value of parsed) {
+            if (typeof value === "string")
+                paths.push(value);
+        }
+    }
+    else if (parsed && typeof parsed === "object") {
+        const candidateArrays = [
+            parsed["surfaces"],
+            parsed["managed_surfaces"],
+            parsed["managedSurfaces"],
+            parsed["paths"],
+        ];
+        for (const candidate of candidateArrays) {
+            if (!Array.isArray(candidate))
+                continue;
+            for (const value of candidate) {
+                if (typeof value === "string")
+                    paths.push(value);
+            }
+        }
+    }
+    return new Set(paths.map((p) => normalizeRelPath(p)));
+}
+/**
+ * Tier 1 folders that are always considered Polaris-owned cognition surfaces.
+ *
+ * Includes fixed roots and dynamic immediate children under src/<subdirectory>.
+ */
+function isPolarisOwnedFolder(folderRel) {
+    const normalized = normalizeRelPath(folderRel);
+    if (!normalized)
+        return false;
+    if (exports.POLARIS_OWNED_COGNITION_FOLDERS.includes(normalized)) {
+        return true;
+    }
+    return /^src\/[^/]+$/.test(normalized);
+}
+/**
+ * Returns true when a cognition surface should be treated as user-created and
+ * therefore protected from worker overwrites.
+ *
+ * A surface is protected when either:
+ * 1) It predates Polaris initialization (.polaris birth/creation time), or
+ * 2) It is listed in .polaris/cognition/managed-surfaces.json.
+ */
+function isUserCreatedCognitionSurface(filePath, repoRoot) {
+    const absFile = (0, node_path_1.resolve)(repoRoot, filePath);
+    const relFile = normalizeRelPath((0, node_path_1.relative)(repoRoot, absFile));
+    if (!relFile || relFile.startsWith(".."))
+        return false;
+    const managed = readManagedSurfaceManifest(repoRoot);
+    if (managed.has(relFile))
+        return true;
+    if (!(0, node_fs_1.existsSync)(absFile))
+        return false;
+    const polarisDir = (0, node_path_1.join)(repoRoot, ".polaris");
+    if (!(0, node_fs_1.existsSync)(polarisDir))
+        return false;
+    const fileStat = (0, node_fs_1.statSync)(absFile);
+    const polarisStat = (0, node_fs_1.statSync)(polarisDir);
+    const polarisInitializedAt = polarisStat.birthtimeMs > 0 ? polarisStat.birthtimeMs : polarisStat.ctimeMs;
+    return fileStat.mtimeMs < polarisInitializedAt;
+}
+/**
+ * Returns true when a folder is skipped for route-local cognition:
+ * generated, runtime, ignored, or agent-only-with-no-opt-in.
+ *
+ * When repoRoot is provided, also consults .smartdocignore and the shared
+ * smartdoc-ignore eligibility rules (RUNTIME_EXCLUDED_DIR_PATTERNS,
+ * AGENT_COGNITION_FOLDERS, HIDDEN_SYSTEM_FOLDERS). This ensures cognition
+ * scanning honours the same boundaries as Smart Docs ingest.
+ */
+function isCognitionSkippedFolder(folderRel, repoRoot) {
+    // Fast-path: hardcoded runtime/bootstrap prefixes (no fs needed)
+    for (const prefix of SKIP_FOLDER_PREFIXES) {
+        if (folderRel === prefix.slice(0, -1) || folderRel.startsWith(prefix)) {
+            return true;
+        }
+    }
+    if (POLARIS_RUNTIME_COGNITION_FOLDERS.has(folderRel))
+        return false;
+    for (const prefix of POLARIS_RUNTIME_GENERATED_PREFIXES) {
+        const rootPath = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+        if (folderRel === rootPath || folderRel.startsWith(prefix))
+            return true;
+    }
+    // Agent folders are opt-in only
+    const topLevel = folderRel.split("/")[0] ?? folderRel;
+    if (AGENT_OPT_IN_FOLDERS.has(topLevel))
+        return true;
+    // When repoRoot is available, defer to the smartdoc-ignore authority.
+    // This ensures .smartdocignore patterns and shared exclusion lists are
+    // honoured — POLARIS.md and SUMMARY.md are bounded agent/context files,
+    // not ingest candidates.
+    if (repoRoot) {
+        const eligibility = (0, smartdoc_ignore_js_1.isDirectoryEligible)(folderRel, repoRoot);
+        if (!eligibility.eligible)
+            return true;
+        // Also check .smartdocignore patterns directly for directory paths
+        if (!folderRel.startsWith(".polaris")) {
+            const ig = (0, smartdoc_ignore_js_1.parseSmartDocIgnore)(repoRoot);
+            if (ig.ignores(folderRel) || ig.ignores(`${folderRel}/`))
+                return true;
+        }
+    }
+    return false;
+}
+// ── Nearest route-local POLARIS.md ────────────────────────────────────────────
+/**
+ * Walk upward from `filePath` (relative to repoRoot) and return the nearest
+ * non-root POLARIS.md. Returns null when only root or no POLARIS.md exists.
+ */
+function findNearestRoutePolarismd(filePath, repoRoot, skipRoot) {
+    const parts = filePath.split("/");
+    // Walk from deepest dir upward, excluding the root level when skipRoot=true
+    for (let i = parts.length - 1; i >= 1; i--) {
+        const dir = parts.slice(0, i).join("/");
+        if (isCognitionSkippedFolder(dir, repoRoot))
+            continue;
+        const candidate = (0, node_path_1.join)(repoRoot, dir, "POLARIS.md");
+        if ((0, node_fs_1.existsSync)(candidate)) {
+            return (0, node_path_1.relative)(repoRoot, candidate).replace(/\\/g, "/");
+        }
+    }
+    // Fall back to root only when not skipping root
+    if (!skipRoot) {
+        const rootCandidate = (0, node_path_1.join)(repoRoot, "POLARIS.md");
+        if ((0, node_fs_1.existsSync)(rootCandidate))
+            return "POLARIS.md";
+    }
+    return null;
+}
+// ── Change signal detection ───────────────────────────────────────────────────
+/** Signals in a file path that suggest operational relevance. */
+const OPERATIONAL_SIGNALS = [
+    { pattern: /\/index\.ts$/, reason: "folder-responsibilities-changed" },
+    { pattern: /\/cli\//, reason: "commands-workflows-changed" },
+    { pattern: /\/commands?\//, reason: "commands-workflows-changed" },
+    { pattern: /scripts\//, reason: "commands-workflows-changed" },
+    { pattern: /\/config\//, reason: "execution-constraints-changed" },
+    { pattern: /\/schema\.ts$/, reason: "execution-constraints-changed" },
+    { pattern: /\/loader\.ts$/, reason: "execution-constraints-changed" },
+    { pattern: /\/map\//, reason: "ownership-routing-changed" },
+    { pattern: /\/atlas\.ts$/, reason: "ownership-routing-changed" },
+    { pattern: /\/inference\.ts$/, reason: "ownership-routing-changed" },
+    { pattern: /\/dispatch/, reason: "operational-behavior-changed" },
+    { pattern: /\/worker\.ts$/, reason: "operational-behavior-changed" },
+    { pattern: /\/parent\.ts$/, reason: "operational-behavior-changed" },
+    { pattern: /\/finalize\//, reason: "operational-behavior-changed" },
+    { pattern: /\/cognition\//, reason: "operational-behavior-changed" },
+];
+/**
+ * Determine whether a set of touched files warrants a POLARIS.md update.
+ * Returns the reasons found; empty array means no update warranted.
+ */
+function detectOperationalReasons(touchedFiles) {
+    const reasonSet = new Set();
+    for (const file of touchedFiles) {
+        // Skip test files, comments-only changes, etc.
+        if (file.endsWith(".test.ts") || file.endsWith(".test.js"))
+            continue;
+        if (file.endsWith(".md") || file.endsWith(".json")) {
+            // Only config json or doc-linking md are operationally relevant
+            if (!file.includes("config") && !file.endsWith("POLARIS.md") && !file.endsWith("SUMMARY.md")) {
+                continue;
+            }
+        }
+        for (const signal of OPERATIONAL_SIGNALS) {
+            if (signal.pattern.test(file)) {
+                reasonSet.add(signal.reason);
+            }
+        }
+    }
+    return Array.from(reasonSet);
+}
+// ── Missing surface detection ─────────────────────────────────────────────────
+/**
+ * For each touched file, check whether its nearest eligible folder has a
+ * POLARIS.md. Return folders that are newly eligible but missing one.
+ */
+function detectMissingCognitionSurfaces(touchedFiles, repoRoot, skipRoot) {
+    const missing = new Set();
+    for (const file of touchedFiles) {
+        const parts = file.split("/");
+        for (let i = parts.length - 1; i >= 1; i--) {
+            const dir = parts.slice(0, i).join("/");
+            if (isCognitionSkippedFolder(dir, repoRoot))
+                continue;
+            const candidate = (0, node_path_1.join)(repoRoot, dir, "POLARIS.md");
+            if (!(0, node_fs_1.existsSync)(candidate)) {
+                // Only report if there are source files in this folder (not empty dirs)
+                missing.add(dir);
+            }
+            break; // Only report the nearest ancestor folder per file
+        }
+    }
+    return Array.from(missing);
+}
+// ── Main delta entry point ────────────────────────────────────────────────────
+/**
+ * Apply route-local cognition delta logic after child implementation.
+ *
+ * Does NOT write POLARIS.md. Returns a result describing what was found so
+ * that the worker prompt can instruct the agent accordingly, or the caller can
+ * conditionally trigger an update.
+ */
+function applyRouteCognitionDelta(options) {
+    const { repoRoot, touchedFiles, skipRoot = true } = options;
+    const inspectedFolders = new Set();
+    const routeLocalTargets = new Set();
+    const missingCognitionSurfaces = [];
+    for (const file of touchedFiles) {
+        const dir = (0, node_path_1.dirname)(file);
+        if (dir && dir !== ".") {
+            if (!isCognitionSkippedFolder(dir)) {
+                inspectedFolders.add(dir);
+            }
+        }
+        const target = findNearestRoutePolarismd(file, repoRoot, skipRoot);
+        if (target)
+            routeLocalTargets.add(target);
+    }
+    const reasons = detectOperationalReasons(touchedFiles);
+    const updateWarranted = reasons.length > 0;
+    const missing = detectMissingCognitionSurfaces(touchedFiles, repoRoot, skipRoot);
+    missingCognitionSurfaces.push(...missing);
+    return {
+        inspectedFolders: Array.from(inspectedFolders),
+        routeLocalTargets: Array.from(routeLocalTargets),
+        updateWarranted,
+        reasons,
+        missingCognitionSurfaces,
+        healthState: undefined,
+    };
+}
+// ── POLARIS.md content read helper ────────────────────────────────────────────
+/**
+ * Read the content of a route-local POLARIS.md (relative to repoRoot).
+ * Returns null when missing.
+ */
+function readRoutePolarismd(polarisRel, repoRoot) {
+    const abs = (0, node_path_1.resolve)(repoRoot, polarisRel);
+    if (!(0, node_fs_1.existsSync)(abs))
+        return null;
+    try {
+        return (0, node_fs_1.readFileSync)(abs, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cognition/summary-delta.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * SUMMARY.md delta logic.
+ *
+ * SUMMARY.md is the informational/contextual compression surface for a route.
+ * It must stay short, remain informational only, and never become operational
+ * doctrine or a giant architecture dump.
+ *
+ * Workers and ingest pipelines call applySummaryDelta() to determine whether
+ * a SUMMARY.md update is warranted. Updates are delta-only: only spec/canon/
+ * architecture/doctrine-linkage changes trigger a SUMMARY.md refresh.
+ *
+ * Root SUMMARY.md is skipped — route-local cognition begins below root.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUMMARY_MAX_BYTES = void 0;
+exports.detectPrecedenceLevel = detectPrecedenceLevel;
+exports.detectSummaryReasons = detectSummaryReasons;
+exports.detectSourcePathSignals = detectSourcePathSignals;
+exports.findNearestSummarymd = findNearestSummarymd;
+exports.detectMissingSummaries = detectMissingSummaries;
+exports.applySummaryDelta = applySummaryDelta;
+exports.readSummarymd = readSummarymd;
+exports.isSummaryOversized = isSummaryOversized;
+exports.hasDoctrineBled = hasDoctrineBled;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const route_cognition_delta_js_1 = require("./route-cognition-delta.js");
+const doctrine_js_1 = require("../smartdocs-engine/doctrine.js");
+// ── Signals that trigger SUMMARY.md delta ─────────────────────────────────────
+const SUMMARY_SIGNALS = [
+    { pattern: /smartdocs\/docs\/specs\/raw\//, reason: "linked-docs-changed" },
+    { pattern: /smartdocs\/docs\/specs\/active\//, reason: "linked-docs-changed" },
+    { pattern: /smartdocs\/docs\/doctrine\/active\//, reason: "doctrine-spec-linkage-changed" },
+    { pattern: /smartdocs\/docs\/architecture\//, reason: "architecture-meaning-changed" },
+    { pattern: /smartdocs\/docs\/decisions\//, reason: "doctrine-spec-linkage-changed" },
+    { pattern: /\/canon\//, reason: "canon-relationships-changed" },
+    { pattern: /POLARIS\.md$/, reason: "canon-relationships-changed" },
+    { pattern: /AGENTS\.md$/, reason: "canon-relationships-changed" },
+    { pattern: /CLAUDE\.md$/, reason: "canon-relationships-changed" },
+    { pattern: /polaris\.config\.json$/, reason: "canon-relationships-changed" },
+];
+/**
+ * Determine the highest-precedence cognition source for the given touched files.
+ *
+ * Priority (highest first):
+ * 1. promoted-doctrine — active doctrine files in smartdocs/doctrine/active/
+ * 2. spec-or-arch      — linked specs, architecture, or decision docs
+ * 3. route-polaris-md  — a route-local POLARIS.md was touched
+ * 4. source-inference  — no above signals; fallback
+ */
+function detectPrecedenceLevel(touchedFiles) {
+    for (const file of touchedFiles) {
+        if (/smartdocs\/docs\/doctrine\/active\//.test(file))
+            return "promoted-doctrine";
+    }
+    for (const file of touchedFiles) {
+        if (/smartdocs\/docs\/specs\/active\//.test(file) ||
+            /smartdocs\/docs\/architecture\//.test(file) ||
+            /smartdocs\/docs\/decisions\//.test(file) ||
+            /smartdocs\/docs\/specs\/raw\//.test(file))
+            return "spec-or-arch";
+    }
+    for (const file of touchedFiles) {
+        if (/POLARIS\.md$/.test(file))
+            return "route-polaris-md";
+    }
+    return "source-inference";
+}
+/**
+ * Determine which summary-related delta reasons are triggered by the provided file paths.
+ *
+ * @param touchedFiles - List of touched file paths (relative-like strings) to evaluate against summary signal patterns
+ * @returns An array of unique `SummaryDeltaReason` values that matched any signal pattern for the given files
+ */
+function detectSummaryReasons(touchedFiles) {
+    const reasonSet = new Set();
+    for (const file of touchedFiles) {
+        for (const signal of SUMMARY_SIGNALS) {
+            if (signal.pattern.test(file)) {
+                reasonSet.add(signal.reason);
+            }
+        }
+    }
+    return Array.from(reasonSet);
+}
+// ── source_paths enrichment ───────────────────────────────────────────────────
+const SMARTDOC_SCAN_DIRS = [
+    "smartdocs/doctrine/active",
+    "smartdocs/specs/active",
+];
+/**
+ * Detects whether any active SmartDoc declares a `source_paths` entry that exactly matches a touched file.
+ *
+ * @param touchedFiles - Array of touched file paths (normalized-ish strings, typically repository-relative)
+ * @param repoRoot - Filesystem path to the repository root used to locate active SmartDocs
+ * @returns `true` if at least one `source_paths` entry in an active SmartDoc matches a touched file, `false` otherwise
+ */
+function detectSourcePathSignals(touchedFiles, repoRoot) {
+    if (touchedFiles.length === 0)
+        return false;
+    const touchedSet = new Set(touchedFiles.map((f) => f.replace(/\\/g, "/")));
+    for (const scanDir of SMARTDOC_SCAN_DIRS) {
+        const absDir = (0, node_path_1.join)(repoRoot, scanDir);
+        if (!(0, node_fs_1.existsSync)(absDir))
+            continue;
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(absDir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith(".md"))
+                continue;
+            const absFile = (0, node_path_1.join)(absDir, entry);
+            let content;
+            try {
+                content = (0, node_fs_1.readFileSync)(absFile, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const fm = (0, doctrine_js_1.parseFrontMatter)(content);
+            const sourcePaths = fm["source_paths"];
+            if (!sourcePaths)
+                continue;
+            const paths = sourcePaths
+                .split(",")
+                .map((p) => p.trim())
+                .filter(Boolean);
+            for (const sp of paths) {
+                if (touchedSet.has(sp))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// ── Nearest route SUMMARY.md ──────────────────────────────────────────────────
+/**
+ * Find the nearest SUMMARY.md relative to a given file (below root).
+ * Returns null when none found or only root exists.
+ */
+function findNearestSummarymd(filePath, repoRoot, skipRoot) {
+    const parts = filePath.split("/");
+    for (let i = parts.length - 1; i >= 1; i--) {
+        const dir = parts.slice(0, i).join("/");
+        if ((0, route_cognition_delta_js_1.isCognitionSkippedFolder)(dir, repoRoot))
+            continue;
+        const candidate = (0, node_path_1.join)(repoRoot, dir, "SUMMARY.md");
+        if ((0, node_fs_1.existsSync)(candidate)) {
+            return (0, node_path_1.relative)(repoRoot, candidate).replace(/\\/g, "/");
+        }
+    }
+    if (!skipRoot) {
+        const rootCandidate = (0, node_path_1.join)(repoRoot, "SUMMARY.md");
+        if ((0, node_fs_1.existsSync)(rootCandidate))
+            return "SUMMARY.md";
+    }
+    return null;
+}
+// ── Missing SUMMARY.md detection ──────────────────────────────────────────────
+/**
+ * For each touched file, find folders that have a POLARIS.md but are missing a
+ * SUMMARY.md. These are eligible for a SUMMARY.md draft.
+ *
+ * Informational only — callers should surface this as a hint, not pressure.
+ * Workers must NOT create SUMMARY.md automatically from this result.
+ */
+function detectMissingSummaries(touchedFiles, repoRoot, skipRoot) {
+    const missing = new Set();
+    for (const file of touchedFiles) {
+        const parts = file.split("/");
+        for (let i = parts.length - 1; i >= 1; i--) {
+            const dir = parts.slice(0, i).join("/");
+            if ((0, route_cognition_delta_js_1.isCognitionSkippedFolder)(dir, repoRoot))
+                continue;
+            const hasPolarismd = (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, dir, "POLARIS.md"));
+            const hasSummarymd = (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, dir, "SUMMARY.md"));
+            if (hasPolarismd && !hasSummarymd) {
+                missing.add(dir);
+            }
+            break;
+        }
+        if (!skipRoot) {
+            const hasPolarismd = (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "POLARIS.md"));
+            const hasSummarymd = (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "SUMMARY.md"));
+            if (hasPolarismd && !hasSummarymd) {
+                missing.add(".");
+            }
+        }
+    }
+    return Array.from(missing);
+}
+// ── Main delta entry point ────────────────────────────────────────────────────
+/**
+ * Determine whether a route-local SUMMARY.md should be updated based on the given touched files.
+ *
+ * Does not modify repository files; analyzes touched paths and repository state to decide
+ * whether a SUMMARY.md update is warranted and where updates or drafts might be targeted.
+ *
+ * @param options - Analysis options: `repoRoot` (repository root path), `touchedFiles` (list of touched file paths), and `skipRoot` (optional; when true, exclude root `SUMMARY.md` from consideration; defaults to `true`)
+ * @returns A `SummaryDeltaResult` containing:
+ *  - `updateWarranted`: `true` if an update is recommended, `false` otherwise;
+ *  - `reasons`: triggered `SummaryDeltaReason` values;
+ *  - `summaryTargets`: relative paths of nearest `SUMMARY.md` candidates;
+ *  - `missingSummaries`: directories that contain `POLARIS.md` but lack `SUMMARY.md`;
+ *  - `precedenceSource`: computed `SummaryPrecedenceLevel`.
+ */
+function applySummaryDelta(options) {
+    const { repoRoot, touchedFiles, skipRoot = true } = options;
+    const reasons = detectSummaryReasons(touchedFiles);
+    // Enrich signals: if any touched file appears in source_paths of an active SmartDoc,
+    // treat this as a linked-docs-changed signal even if path patterns didn't match.
+    if (detectSourcePathSignals(touchedFiles, repoRoot)) {
+        if (!reasons.includes("linked-docs-changed")) {
+            reasons.push("linked-docs-changed");
+        }
+    }
+    const updateWarranted = reasons.length > 0;
+    const precedenceSource = detectPrecedenceLevel(touchedFiles);
+    const summaryTargets = new Set();
+    for (const file of touchedFiles) {
+        const target = findNearestSummarymd(file, repoRoot, skipRoot);
+        if (target)
+            summaryTargets.add(target);
+    }
+    const missingSummaries = detectMissingSummaries(touchedFiles, repoRoot, skipRoot);
+    return {
+        updateWarranted,
+        reasons,
+        summaryTargets: Array.from(summaryTargets),
+        missingSummaries,
+        precedenceSource,
+    };
+}
+// ── SUMMARY.md content guard ──────────────────────────────────────────────────
+exports.SUMMARY_MAX_BYTES = 4096;
+/**
+ * Read SUMMARY.md content (relative to repoRoot). Returns null when missing.
+ */
+function readSummarymd(summaryRel, repoRoot) {
+    const abs = (0, node_path_1.resolve)(repoRoot, summaryRel);
+    if (!(0, node_fs_1.existsSync)(abs))
+        return null;
+    try {
+        return (0, node_fs_1.readFileSync)(abs, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns true when a SUMMARY.md content string exceeds the size guard.
+ */
+function isSummaryOversized(content) {
+    return Buffer.byteLength(content, "utf-8") > exports.SUMMARY_MAX_BYTES;
+}
+/**
+ * Returns true when a SUMMARY.md contains strong doctrine bleed patterns
+ * (operational imperatives that belong in POLARIS.md).
+ *
+ * Deliberately narrow to avoid false-positives from quoted text or normal
+ * prose that happens to contain "do not" or "never" in context.
+ * This check is WARN-only — it must never be a hard blocker.
+ */
+function hasDoctrineBled(content) {
+    const lower = content.toLowerCase();
+    // Only flag unambiguous operational section headings and strong imperatives
+    // that clearly belong in POLARIS.md rather than informational summaries.
+    return (lower.includes("## editing rules") ||
+        lower.includes("## constraints") ||
+        lower.includes("## stop rule") ||
+        lower.includes("## forbidden") ||
+        // Strong imperative pattern: "must always" or "must never" at line start
+        /^\s*[-*]?\s*\w[^.]*\bmust\s+(always|never)\b/m.test(lower));
+}