brainclaw 1.8.0 → 1.9.1

package/dist/core/security-scoring.js

@@ -1,3 +1,27 @@
+import { matchesAnyEntry, parseListEntry } from './security-packages.js';
+/**
+ * Map an intrinsic verdict (pass/warn/block) to the effective decision under
+ * a given mode. In advisory mode, a block is downgraded to warn so the
+ * operator sees the issue but the wrapper does not abort the install.
+ */
+export function applyMode(decision, mode) {
+    if (mode === 'enforced')
+        return decision;
+    return decision === 'block' ? 'warn' : decision;
+}
+/**
+ * Map an effective decision to a CLI exit code.
+ *   pass  -> 0
+ *   warn  -> 1   (wrapper continues, but surfaces the warning)
+ *   block -> 2   (wrapper aborts the install)
+ */
+export function decisionExitCode(decision) {
+    if (decision === 'block')
+        return 2;
+    if (decision === 'warn')
+        return 1;
+    return 0;
+}
 const DEFAULT_WEIGHTS = {
     supply_chain: 0.35,
     vulnerability: 0.30,
@@ -11,8 +35,47 @@ const DEFAULT_THRESHOLDS = {
     supply_chain_block: 30,
     vulnerability_block: 20,
 };
+/**
+ * Normalize weights so they sum to 1.0. Without this, custom configs like
+ * `{ supply_chain: 1, vulnerability: 1 }` produce a composite that can
+ * exceed 100, making thresholds meaningless. If all weights are zero the
+ * defaults are used (degenerate config — fail open to the project default).
+ */
+export function normalizeWeights(weights) {
+    const merged = { ...DEFAULT_WEIGHTS, ...weights };
+    const sum = merged.supply_chain + merged.vulnerability + merged.quality + merged.maintenance + merged.license;
+    if (sum <= 0)
+        return { ...DEFAULT_WEIGHTS };
+    if (Math.abs(sum - 1) < 1e-9)
+        return merged;
+    return {
+        supply_chain: merged.supply_chain / sum,
+        vulnerability: merged.vulnerability / sum,
+        quality: merged.quality / sum,
+        maintenance: merged.maintenance / sum,
+        license: merged.license / sum,
+    };
+}
+/**
+ * Clamp thresholds to the [0,100] band and enforce the invariant
+ * `composite_warn <= composite_pass`. The CLI loader can call this so a
+ * mis-configured YAML never produces a "composite=60 → block when
+ * pass=50, warn=80" non-monotonic verdict.
+ */
+export function normalizeThresholds(thresholds) {
+    const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+    const clamp = (n) => Math.max(0, Math.min(100, n));
+    t.composite_pass = clamp(t.composite_pass);
+    t.composite_warn = clamp(t.composite_warn);
+    t.supply_chain_block = clamp(t.supply_chain_block);
+    t.vulnerability_block = clamp(t.vulnerability_block);
+    if (t.composite_warn > t.composite_pass) {
+        t.composite_warn = t.composite_pass;
+    }
+    return t;
+}
 export function computeComposite(scores, weights) {
-    const w = { ...DEFAULT_WEIGHTS, ...weights };
+    const w = normalizeWeights(weights);
     return Math.round((scores.supplyChain * w.supply_chain +
         scores.vulnerability * w.vulnerability +
         scores.quality * w.quality +
@@ -20,15 +83,18 @@ export function computeComposite(scores, weights) {
         scores.license * w.license) * 10) / 10;
 }
 export function evaluatePackage(scores, config) {
-    const thresholds = { ...DEFAULT_THRESHOLDS, ...config?.thresholds };
-    const weights = { ...DEFAULT_WEIGHTS, ...config?.weights };
+    const thresholds = normalizeThresholds(config?.thresholds);
+    const weights = normalizeWeights(config?.weights);
     const allowlist = config?.allowlist ?? [];
     const denylist = config?.denylist ?? [];
     const pkgName = scores.purl.replace(/^pkg:\w+\//, '');
     const ecosystem = scores.purl.startsWith('pkg:pypi') ? 'pypi' : 'npm';
     const reasons = [];
-    // Denylist check (exact match on package name)
-    if (denylist.some(d => pkgName === d || scores.purl.includes(d))) {
+    const parsedDeny = denylist.map(parseListEntry);
+    const parsedAllow = allowlist.map(parseListEntry);
+    // Denylist check — canonical (ecosystem, name, optional version) match.
+    const denyHit = matchesAnyEntry(parsedDeny, ecosystem, pkgName, scores.version);
+    if (denyHit) {
         return {
             package: pkgName,
             ecosystem,
@@ -36,11 +102,12 @@ export function evaluatePackage(scores, config) {
             scores,
             composite: 0,
             decision: 'block',
-            reasons: [`Package "${pkgName}" is on the denylist`],
+            reasons: [`Package "${pkgName}@${scores.version}" matches denylist entry "${denyHit.raw.trim()}"`],
         };
     }
-    // Allowlist check (skip scoring)
-    if (allowlist.some(a => pkgName === a || scores.purl.includes(a))) {
+    // Allowlist check — canonical match; skips scoring.
+    const allowHit = matchesAnyEntry(parsedAllow, ecosystem, pkgName, scores.version);
+    if (allowHit) {
         return {
             package: pkgName,
             ecosystem,
@@ -48,7 +115,7 @@ export function evaluatePackage(scores, config) {
             scores,
             composite: 100,
             decision: 'pass',
-            reasons: [`Package "${pkgName}" is on the allowlist`],
+            reasons: [`Package "${pkgName}@${scores.version}" matches allowlist entry "${allowHit.raw.trim()}"`],
         };
     }
     const composite = computeComposite(scores, weights);

package/dist/core/security.js

@@ -1,6 +1,14 @@
+import { runEntropyDetector, runStructuralDetectors } from './security-detectors.js';
 /**
- * Scan a text string for sensitive patterns defined in the config.
- * Returns a list of warnings.
+ * Scan a text string for sensitive content. Three signal layers run:
+ *   1. User-configured regex patterns from `config.redaction.patterns`
+ *      (the legacy MVP behavior).
+ *   2. Structural detectors — exact token shapes for GitHub PATs, AWS
+ *      access keys, JWTs, etc. High precision; on by default.
+ *   3. Entropy detector — flags high-entropy token-like substrings near
+ *      a sensitive keyword. Tunable, on by default.
+ *
+ * In strict mode all signals escalate to `block`; otherwise `warn`.
  */
 export function scanText(text, config) {
     const warnings = [];
@@ -24,6 +32,30 @@ export function scanText(text, config) {
             // skip invalid regex patterns
         }
     }
+    // Structural detectors — only run when token_detection is enabled.
+    const td = config.security?.token_detection;
+    if (td?.enabled !== false) {
+        const disabled = td?.detectors;
+        for (const m of runStructuralDetectors(text, disabled)) {
+            warnings.push({
+                level,
+                message: `${m.label} (id=${m.detectorId}) detected: ${m.excerpt}`,
+            });
+        }
+        if (td?.entropy?.enabled !== false) {
+            const entropyMatches = runEntropyDetector(text, {
+                enabled: td?.entropy?.enabled ?? true,
+                minLength: td?.entropy?.min_length,
+                minEntropy: td?.entropy?.min_entropy,
+            });
+            for (const m of entropyMatches) {
+                warnings.push({
+                    level,
+                    message: `High-entropy token-shaped substring near a secret keyword (entropy=${m.entropy}): ${m.excerpt}`,
+                });
+            }
+        }
+    }
     const blockPaths = config.security?.block_sensitive_paths ?? true;
     if (blockPaths) {
         for (const sp of config.sensitive_paths) {

package/dist/core/sequence.js

@@ -5,6 +5,7 @@ import { generateIdWithLabel, nowISO } from './ids.js';
 import { resolveEntityDir } from './io.js';
 import { SequenceItemSchema, SequenceSchema } from './schema.js';
 import { refreshLiveCompanions } from '../commands/export.js';
+import { emitRegistryPostImage, emitRegistryTombstone, registryFaultPoint } from './events/registry-post-image.js';
 function sequencesDir(cwd, mode = 'read') {
     return resolveEntityDir('sequences', cwd ?? process.cwd(), mode);
 }
@@ -39,7 +40,13 @@ function validateRanks(items) {
 export function saveSequence(sequence, cwd) {
     mutate({ cwd }, () => {
         ensureSequencesDir(cwd);
-        sequenceStore(cwd, 'write').save(SequenceSchema.parse(sequence));
+        const store = sequenceStore(cwd, 'write');
+        const parsed = SequenceSchema.parse(sequence);
+        // pln#568 (I2): journal the post-image BEFORE the projection write.
+        const created = !store.exists(parsed.id);
+        emitRegistryPostImage('sequence', parsed, { created, agent: parsed.author, agent_id: parsed.author_id, session_id: parsed.session_id, cwd });
+        registryFaultPoint('after_registry_journal');
+        store.save(parsed);
         // Auto-refresh live companions after sequence changes (non-fatal)
         try {
             refreshLiveCompanions(cwd);
@@ -99,6 +106,8 @@ export function deleteSequence(id, cwd) {
         if (!current) {
             throw new Error(`Sequence not found: ${id}`);
         }
+        emitRegistryTombstone('sequence', current.id, { agent: current.author, agent_id: current.author_id, session_id: current.session_id, cwd });
+        registryFaultPoint('after_registry_journal');
         store.delete(current.id);
         return { id: current.id, name: current.name };
     });
@@ -123,7 +132,7 @@ export function updateSequence(input, cwd) {
             tags: input.tags ?? current.tags,
             updated_at: nowISO(),
         };
-        store.save(SequenceSchema.parse(next));
+        saveSequence(SequenceSchema.parse(next), cwd);
         return next;
     });
 }

package/dist/core/setup-flow.js

@@ -11,13 +11,150 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { memoryExists } from './io.js';
+import { spawnSync } from 'node:child_process';
+import { memoryDir, memoryExists } from './io.js';
 import { detectAiAgent } from './ai-agent-detection.js';
 import { resolveStoreChain } from './store-resolution.js';
 import { analyzeRepository } from './repo-analysis.js';
 import { getAgentCapabilityProfile, getAllAgentCapabilityProfiles } from './agent-capability.js';
 import { describeAgentSurfaces } from './agent-capability.js';
 import { loadState } from './state.js';
+/** Entries that don't count as "repo content" when deciding the bootstrap route. */
+const CONTENT_IGNORED = new Set(['.git', '.brainclaw', '.gitignore', '.gitattributes', '.DS_Store', 'Thumbs.db']);
+/** True when cwd contains anything beyond git/brainclaw plumbing. */
+export function repoHasContent(cwd) {
+    try {
+        return fs.readdirSync(cwd).some((e) => !CONTENT_IGNORED.has(e));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * THE decision rule for "the memory store is empty — what now?", emitted
+ * identically by the three onboarding surfaces (bclaw_work hint, quick_init
+ * preview, init preflight):
+ *
+ *   - repo with existing content → bclaw_bootstrap (extract context from docs/manifests/history)
+ *   - greenfield (nothing to extract) → bootstrap loop (ideate the vision first)
+ *
+ * The two routes are chainable: extraction first, then a bootstrap loop for
+ * whatever vision the docs could not provide — or ideation first, then
+ * extraction once content exists.
+ * Documented in docs/concepts/workspace-bootstrapping.md ("Empty memory: one rule").
+ */
+export function resolveEmptyMemoryRecommendation(cwd = process.cwd()) {
+    if (repoHasContent(cwd)) {
+        return {
+            route: 'extract',
+            reason: 'repo has existing content to extract from',
+            mcp_next_action: 'bclaw_bootstrap()',
+            cli_next_action: 'brainclaw bootstrap',
+            chained_mcp_action: "bclaw_coordinate(intent='ideate', preset='bootstrap')",
+            text: "Memory is empty and the repo has existing content → run bclaw_bootstrap (CLI: brainclaw bootstrap) to extract initial context. If the project vision is still missing afterwards, chain a bootstrap loop: bclaw_coordinate(intent='ideate', preset='bootstrap').",
+        };
+    }
+    return {
+        route: 'ideate',
+        reason: 'greenfield repo — nothing to extract yet',
+        mcp_next_action: "bclaw_coordinate(intent='ideate', preset='bootstrap')",
+        cli_next_action: 'brainclaw bootstrap-loop',
+        chained_mcp_action: 'bclaw_bootstrap()',
+        text: "Memory is empty and the repo is greenfield → open a bootstrap loop to ideate the project vision: bclaw_coordinate(intent='ideate', preset='bootstrap') (CLI: brainclaw bootstrap-loop). Once content exists, chain bclaw_bootstrap to extract it.",
+    };
+}
+/** Event log this large reads as a mature store, not a from-scratch case. */
+const RICH_EVENT_LOG_BYTES = 64 * 1024;
+/** This many memory items reads as a mature store. */
+const RICH_STATE_ITEMS = 25;
+/** PROJECT.md this much older than the latest repo/store activity is fossil. */
+const FOSSIL_GAP_MS = 30 * 86_400_000;
+function lastCommitEpochMs(cwd) {
+    try {
+        const probe = spawnSync('git', ['log', '-1', '--format=%ct'], {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 2000,
+            windowsHide: true,
+        });
+        if (probe.status !== 0)
+            return undefined;
+        const epoch = Number.parseInt(probe.stdout.trim(), 10);
+        return Number.isFinite(epoch) ? epoch * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Composite replacement for the one-bit PROJECT.md stat() that backed
+ * `bootstrap_recommended` (pln#513). The single bit had two failure modes on
+ * a mature ("amorcé") project:
+ *   - false positive: rich store, missing PROJECT.md → recommended a
+ *     from-scratch bootstrap over 17k events of accumulated memory;
+ *   - eternal false negative: PROJECT.md exists but fossilized — never
+ *     flagged again no matter how far the repo drifted.
+ *
+ * Signals combined: PROJECT.md presence × its mtime vs recent activity
+ * (last commit, last memory write) × store density (event-log size,
+ * memory item count). 'refresh' maps to `bclaw_bootstrap(refresh: true)` —
+ * coordinate with the pln#514 step 1 force-flag on the bootstrap-loop side.
+ */
+export function assessBootstrapNeed(cwd = process.cwd()) {
+    const reasons = [];
+    // Signal 1 — PROJECT.md presence.
+    const projectMdPath = path.join(cwd, 'PROJECT.md');
+    let projectMdPresent = false;
+    let projectMdMtimeMs;
+    try {
+        const stat = fs.statSync(projectMdPath);
+        if (stat.isFile() && stat.size > 0) {
+            projectMdPresent = true;
+            projectMdMtimeMs = stat.mtimeMs;
+        }
+    }
+    catch { /* absent */ }
+    // Signal 2 — store density.
+    let eventLogBytes = 0;
+    let eventLogMtimeMs;
+    try {
+        const stat = fs.statSync(path.join(memoryDir(cwd), 'events.jsonl'));
+        eventLogBytes = stat.size;
+        eventLogMtimeMs = stat.mtimeMs;
+    }
+    catch { /* no event log */ }
+    let stateItems = 0;
+    try {
+        const state = loadState(cwd);
+        stateItems = state.active_constraints.length + state.recent_decisions.length
+            + state.known_traps.length + state.open_handoffs.length + state.plan_items.length;
+    }
+    catch { /* unreadable state → 0 */ }
+    const storeDensity = eventLogBytes >= RICH_EVENT_LOG_BYTES || stateItems >= RICH_STATE_ITEMS
+        ? 'rich'
+        : eventLogBytes === 0 && stateItems === 0
+            ? 'empty'
+            : 'low';
+    if (!projectMdPresent) {
+        if (storeDensity === 'rich') {
+            // The store already knows this project — regenerate PROJECT.md from it
+            // (scanner + memory), do NOT restart discovery from scratch.
+            reasons.push(`PROJECT.md missing but the store is rich (${stateItems} items, ${Math.round(eventLogBytes / 1024)} KB events) — regenerate from existing memory instead of bootstrapping from scratch`);
+            return { verdict: 'refresh', reasons, project_md_present: false, store_density: storeDensity };
+        }
+        reasons.push('PROJECT.md missing and the store is sparse — initial bootstrap applies');
+        return { verdict: 'bootstrap', reasons, project_md_present: false, store_density: storeDensity };
+    }
+    // Signal 3 — fossil check: PROJECT.md much older than the latest activity.
+    const lastActivityMs = Math.max(lastCommitEpochMs(cwd) ?? 0, eventLogMtimeMs ?? 0);
+    if (projectMdMtimeMs !== undefined && lastActivityMs > 0 && lastActivityMs - projectMdMtimeMs > FOSSIL_GAP_MS) {
+        const gapDays = Math.round((lastActivityMs - projectMdMtimeMs) / 86_400_000);
+        reasons.push(`PROJECT.md is ${gapDays} days older than the latest repo/store activity — likely fossil, refresh it`);
+        return { verdict: 'refresh', reasons, project_md_present: true, store_density: storeDensity };
+    }
+    reasons.push('PROJECT.md present and current relative to recent activity');
+    return { verdict: 'none', reasons, project_md_present: true, store_density: storeDensity };
+}
 /**
  * Probe the current working directory to understand what we're working with.
  * This is the first step of the quick setup flow — no questions yet, just detection.
@@ -37,16 +174,7 @@ export function probeForQuickSetup(cwd = process.cwd()) {
         : getAllAgentCapabilityProfiles();
     // Scan nearby stores
     const nearbyStores = resolveStoreChain(cwd);
-    // Has content?
-    const IGNORED = new Set(['.git', '.brainclaw', '.gitignore', '.gitattributes', '.DS_Store', 'Thumbs.db']);
-    let hasContent = false;
-    try {
-        const entries = fs.readdirSync(cwd);
-        hasContent = entries.some((e) => !IGNORED.has(e));
-    }
-    catch {
-        // empty or unreadable
-    }
+    const hasContent = repoHasContent(cwd);
     // Analyze repo for project type suggestion
     let suggestedProjectType = 'standalone';
     let analysisReasons = [];
@@ -164,7 +292,7 @@ export function buildOnboardingPreview(cwd) {
         const traps = state.known_traps.filter((t) => t.visibility === 'shared' && (!t.status || t.status === 'active'));
         const plans = state.plan_items.filter((p) => p.status === 'in_progress' || p.status === 'todo');
         if (constraints.length === 0 && traps.length === 0 && plans.length === 0) {
-            return 'Memory is empty. Run bclaw_bootstrap to extract initial context from this repo.';
+            return resolveEmptyMemoryRecommendation(cwd).text;
         }
         const lines = ['Here is what your agent will see:'];
         if (constraints.length > 0) {
@@ -185,7 +313,7 @@ export function buildOnboardingPreview(cwd) {
         return lines.join('\n');
     }
     catch {
-        return 'Memory is empty. Run bclaw_bootstrap to extract initial context from this repo.';
+        return resolveEmptyMemoryRecommendation(cwd).text;
     }
 }
 //# sourceMappingURL=setup-flow.js.map

package/dist/core/spawn-check.js

@@ -48,7 +48,14 @@ function initProbeGitRepo(root) {
 export async function checkAgentSpawn(agent, options = {}) {
     const start = Date.now();
     const profile = getCapabilityProfile(agent);
-    if (!profile?.invoke_template || !profile?.invoke_binary || !profile.runtime.canBeSpawnedCli) {
+    if (!profile) {
+        // Distinct from no_template: the name didn't resolve to any profile at all
+        // (resolution is case-insensitive, so this is a genuine typo/unknown agent,
+        // not a casing slip). Reported separately so the pre-flight reason points at
+        // the spelling instead of the misleading "IDE-only?" template message.
+        return { agent, status: 'unknown_agent', delivered: false, completed: false, duration_ms: 0, detail: `unknown agent '${agent}' — not a registered brainclaw profile` };
+    }
+    if (!profile.invoke_template || !profile.invoke_binary || !profile.runtime.canBeSpawnedCli) {
         return { agent, status: 'no_template', delivered: false, completed: false, duration_ms: 0, detail: 'no CLI invoke template' };
     }
     const binary = resolveBinaryOnPath(profile.invoke_binary);
@@ -120,7 +127,7 @@ export async function runSpawnCheck(options = {}) {
             });
         }
     }
-    const installed = entries.filter((e) => e.status !== 'not_installed' && e.status !== 'no_template');
+    const installed = entries.filter((e) => e.status !== 'not_installed' && e.status !== 'no_template' && e.status !== 'unknown_agent');
     const ok = installed.filter((e) => e.status === 'ok').length;
     const failures = installed.filter((e) => e.status === 'failed' || e.status === 'delivered_no_completion').length;
     const not_installed = entries.filter((e) => e.status === 'not_installed').length;
@@ -172,6 +179,13 @@ export function preflightResultFromEntry(entry) {
     if (entry.status === 'ok' || entry.status === 'delivered_no_completion') {
         return { agent, ok: true, status: entry.status, reason: entry.detail };
     }
+    if (entry.status === 'unknown_agent') {
+        return {
+            agent, ok: false, status: entry.status,
+            reason: `unknown agent '${agent}' — not a registered brainclaw profile (check spelling/case)`,
+            recommended_next_action: `Use a registered agent name (e.g. codex, claude-code, github-copilot). Names are case-insensitive — list installed agents with \`brainclaw doctor --spawn-check\`.`,
+        };
+    }
     if (entry.status === 'not_installed') {
         return {
             agent, ok: false, status: entry.status,

package/dist/core/staleness.js

@@ -4,6 +4,8 @@
  * Staleness is a soft signal — items are warned, not auto-archived.
  * Users choose to dismiss, resolve, or archive via explicit commands.
  */
+import fs from 'node:fs';
+import path from 'node:path';
 import { resolvedSource } from './candidates.js';
 /** Thresholds in days. Adjust via config in the future. */
 export const STALENESS_THRESHOLDS = {
@@ -106,7 +108,7 @@ const VERIFIED_STALE_DAYS = 30;
  * pln#530 — flag perishable memories (traps that opted in by carrying a
  * `verify_cmd` and/or `verified_at`) whose last empirical verification is stale
  * or never happened, so an agent re-probes the live system instead of trusting a
- * value that may have drifted (the LeaseUp `service_tier` trap that the API later
+ * value that may have drifted (the `service_tier` trap that the API later
  * rejected is the motivating case). Only traps with these fields are considered —
  * durable facts are untouched.
  */
@@ -135,6 +137,66 @@ export function detectUnverifiedMemory(traps, nowMs = Date.now()) {
     }
     return warnings;
 }
+/** Glob chars / URL schemes — entries we cannot meaningfully existsSync. */
+const NON_CHECKABLE_PATH = /[*?[\]]|:\/\//;
+/**
+ * Detect memory entities whose `related_paths` point at files that no longer
+ * exist — memory that stayed "confident" through a refactor and is now wrong.
+ * Staleness today is purely temporal; this is the structural complement
+ * (pln#557 step 2, bridge to pln_79a995b6 memory-lifecycle confirm/decay).
+ *
+ * Only plain paths are probed: glob patterns and URLs are skipped, and a
+ * single missing path among several is enough to flag (the warning lists
+ * exactly which ones are gone).
+ */
+export function detectDeadReferences(items, projectRoot, nowMs = Date.now()) {
+    const warnings = [];
+    for (const item of items) {
+        if (!item.related_paths || item.related_paths.length === 0)
+            continue;
+        const missing = [];
+        for (const ref of item.related_paths) {
+            const trimmed = ref.trim();
+            if (!trimmed || NON_CHECKABLE_PATH.test(trimmed))
+                continue;
+            const resolved = path.isAbsolute(trimmed) ? trimmed : path.join(projectRoot, trimmed);
+            try {
+                if (!fs.existsSync(resolved))
+                    missing.push(trimmed);
+            }
+            catch { /* unreadable path — treat as non-checkable, not dead */ }
+        }
+        if (missing.length === 0)
+            continue;
+        warnings.push({
+            id: item.id,
+            entity: item.entity,
+            text: truncate(item.text),
+            age_days: ageDays(item.created_at, nowMs),
+            reason: `References missing path${missing.length > 1 ? 's' : ''}: ${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ` (+${missing.length - 3} more)` : ''} — likely stale after a refactor`,
+            suggested_action: `bclaw_update(entity: "${item.entity}", id: "${item.short_label ?? item.id}", { related_paths: [<current paths>] })  # or archive if obsolete`,
+        });
+    }
+    return warnings;
+}
+/** Map active entities into the dead-reference detector's input shape. */
+export function collectDeadReferenceCandidates(scan) {
+    const items = [];
+    for (const d of scan.decisions ?? []) {
+        items.push({ id: d.id, entity: 'decision', text: d.text, created_at: d.created_at, related_paths: d.related_paths, short_label: d.short_label });
+    }
+    for (const c of scan.constraints ?? []) {
+        if ((c.status ?? 'active') !== 'active')
+            continue;
+        items.push({ id: c.id, entity: 'constraint', text: c.text, created_at: c.created_at, related_paths: c.related_paths, short_label: c.short_label });
+    }
+    for (const t of scan.traps ?? []) {
+        if (t.status !== 'active')
+            continue;
+        items.push({ id: t.id, entity: 'trap', text: t.text, created_at: t.created_at, related_paths: t.related_paths, short_label: t.short_label });
+    }
+    return items;
+}
 /**
  * Detect open handoffs that have not been acted on for a long time.
  */
@@ -238,7 +300,7 @@ export function detectStaleRuntimeNotes(notes, nowMs = Date.now(), thresholds =
  * @param candidates Pending candidates
  * @param nowMs Optional timestamp override (for testing)
  */
-export function detectStaleness(plans, traps, handoffs, candidates, nowMs = Date.now(), runtimeNotes = []) {
+export function detectStaleness(plans, traps, handoffs, candidates, nowMs = Date.now(), runtimeNotes = [], deadRefScan) {
     const nowIso = new Date(nowMs).toISOString();
     const planWarnings = detectStalePlans(plans, nowMs);
     const trapWarnings = detectExpiredTraps(traps, nowIso, nowMs);
@@ -246,7 +308,13 @@ export function detectStaleness(plans, traps, handoffs, candidates, nowMs = Date
     const handoffWarnings = detectStaleHandoffs(handoffs, nowMs);
     const candidateWarnings = detectStaleCandidates(candidates, nowMs);
     const noteWarnings = detectStaleRuntimeNotes(runtimeNotes, nowMs);
+    // pln#557 step 2 — structural staleness: dead related_paths. The trap list
+    // for the scan defaults to the traps already passed in.
+    const deadRefWarnings = deadRefScan
+        ? detectDeadReferences(collectDeadReferenceCandidates({ traps, ...deadRefScan }), deadRefScan.projectRoot, nowMs)
+        : [];
     const warnings = [
+        ...deadRefWarnings,
         ...planWarnings,
         ...trapWarnings,
         ...unverifiedWarnings,
@@ -261,6 +329,7 @@ export function detectStaleness(plans, traps, handoffs, candidates, nowMs = Date
         handoff_count: handoffWarnings.length,
         candidate_count: candidateWarnings.length,
         runtime_note_count: noteWarnings.length,
+        ...(deadRefScan ? { dead_reference_count: deadRefWarnings.length } : {}),
     };
 }
 /** Total warning count across all entity types. */
@@ -278,6 +347,8 @@ export function staleSummary(report) {
         parts.push(`${report.candidate_count} pending candidate${report.candidate_count > 1 ? 's' : ''}`);
     if (report.runtime_note_count > 0)
         parts.push(`${report.runtime_note_count} stale runtime note${report.runtime_note_count > 1 ? 's' : ''}`);
+    if ((report.dead_reference_count ?? 0) > 0)
+        parts.push(`${report.dead_reference_count} item${report.dead_reference_count > 1 ? 's' : ''} with dead file references`);
     return parts.join(', ');
 }
 //# sourceMappingURL=staleness.js.map