@ikarmic/forge-core 4.4.0 → 5.0.0

package/dist/memory/memory-store.js

@@ -22,6 +22,8 @@
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
+import { TYPE_WEIGHT, scoreSections } from './rank.js';
+import { checkStale, staleKey } from './stale.js';
 /** Default location for project memory, relative to cwd. */
 export const PROJECT_MEMORY_DIR = '.forge';
 export const PROJECT_MEMORY_FILE = 'MEMORY.md';
@@ -31,6 +33,11 @@ export const GLOBAL_MEMORY_FILE = 'MEMORY.md';
 export const DEFAULT_MAX_BYTES = 50_000;
 /** Soft cap on bytes injected into the system prompt. */
 export const DEFAULT_INJECTION_BUDGET = 8_000;
+const MEMORY_TYPES = ['convention', 'decision', 'correction', 'reference'];
+/** Lowercase, NFKC-normalize and whitespace-collapse a heading so near-duplicates compare equal. */
+export function normalizeHeading(h) {
+    return h.normalize('NFKC').toLowerCase().replace(/\s+/g, ' ').trim();
+}
 /**
  * Walk up from `cwd` looking for a directory containing `.forge/`. Stops at
  * the first match; returns null past the filesystem root or past the home
@@ -80,12 +87,7 @@ export function parseMemory(text, source, updatedAt) {
         const h2 = /^##\s+(.+?)\s*$/.exec(line);
         if (h2) {
             if (currentHeading !== null) {
-                out.push({
-                    heading: currentHeading,
-                    body: currentBody.join('\n').trim(),
-                    source,
-                    updatedAt,
-                });
+                out.push(buildSection(currentHeading, currentBody, source, updatedAt));
             }
             currentHeading = h2[1];
             currentBody = [];
@@ -96,15 +98,69 @@ export function parseMemory(text, source, updatedAt) {
         // Lines before the first H2 are dropped (title / preamble).
     }
     if (currentHeading !== null) {
-        out.push({
-            heading: currentHeading,
-            body: currentBody.join('\n').trim(),
-            source,
-            updatedAt,
-        });
+        out.push(buildSection(currentHeading, currentBody, source, updatedAt));
     }
     return out;
 }
+/** Build a section from its heading and raw body lines, peeling off a leading metadata comment. */
+function buildSection(heading, bodyLines, source, fileUpdatedAt) {
+    const firstIdx = bodyLines.findIndex((l) => l.trim() !== '');
+    const meta = firstIdx === -1 ? null : parseMetaLine(bodyLines[firstIdx]);
+    const rest = meta ? bodyLines.slice(firstIdx + 1) : bodyLines;
+    return {
+        heading,
+        body: rest.join('\n').trim(),
+        source,
+        updatedAt: meta?.updatedAt ?? fileUpdatedAt,
+        type: meta?.type ?? 'convention',
+        refs: meta?.refs ?? [],
+        pinned: meta?.pinned ?? false,
+    };
+}
+/**
+ * Parse `<!-- forge: key=value, ... -->`. Returns null when the line is not a
+ * forge comment. Unknown keys and invalid values are ignored field by field, so a
+ * damaged comment degrades to defaults instead of failing the load.
+ */
+function parseMetaLine(line) {
+    const m = /^<!--\s*forge:(.*?)-->$/.exec(line.trim());
+    if (!m)
+        return null;
+    const meta = {};
+    for (const pair of m[1].split(',')) {
+        const eq = pair.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = pair.slice(0, eq).trim();
+        const value = pair.slice(eq + 1).trim();
+        if (key === 'type' && MEMORY_TYPES.includes(value)) {
+            meta.type = value;
+        }
+        else if (key === 'updated' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+            const ms = Date.parse(`${value}T00:00:00Z`);
+            if (!Number.isNaN(ms))
+                meta.updatedAt = ms;
+        }
+        else if (key === 'refs') {
+            const refs = value.split(';').map((r) => r.trim()).filter(Boolean);
+            if (refs.length > 0)
+                meta.refs = refs;
+        }
+        else if (key === 'pin' && value === 'true') {
+            meta.pinned = true;
+        }
+    }
+    return meta;
+}
+function formatMetaLine(meta) {
+    const date = (meta.now ?? new Date()).toISOString().slice(0, 10);
+    const parts = [`type=${meta.type ?? 'convention'}`, `updated=${date}`];
+    if (meta.refs && meta.refs.length > 0)
+        parts.push(`refs=${meta.refs.join(';')}`);
+    if (meta.pinned)
+        parts.push('pin=true');
+    return `<!-- forge: ${parts.join(', ')} -->`;
+}
 /**
  * Load both global and project memory. Project sections override global
  * sections with the same heading. Order: global first (oldest first),
@@ -164,70 +220,117 @@ export async function loadMemory(cwd) {
     const totalBytes = sources.reduce((sum, s) => sum + s.bytes, 0);
     return { sections: allSections, sources, totalBytes };
 }
+/** Cap on bytes spent on pinned sections when the file does not fit the budget. */
+const PIN_BUDGET_BYTES = 2_000;
+/** Cap on bytes spent on the section index. */
+const INDEX_BUDGET_BYTES = 1_000;
+/** Below this many bytes an index is not worth its header; skip it. */
+const MIN_INDEX_BYTES = 60;
 /**
- * Compose a memory injection for the system prompt. Truncates to fit the
- * budget by dropping the OLDEST sections first (lowest updatedAt). Returns
- * the assembled markdown plus diagnostics.
+ * Compose a memory injection for the system prompt.
+ *
+ * When every section fits the budget, all are injected in file order. When
+ * not: pinned sections first (capped), a one-line-per-section index so the
+ * model knows what else exists (`memory_read` fetches it), then the sections
+ * most relevant to `opts.task` that still fit, best last (closest to the
+ * prompt). Everything left out lands in `dropped`. Output never exceeds
+ * `budgetBytes`.
  */
-export function injectMemory(loaded, budgetBytes = DEFAULT_INJECTION_BUDGET) {
-    if (loaded.sections.length === 0) {
+export function injectMemory(loaded, budgetBytes = DEFAULT_INJECTION_BUDGET, opts = {}) {
+    const all = loaded.sections;
+    if (all.length === 0) {
         return { markdown: '', sections: [], dropped: [], found: false };
     }
-    // Always keep project sections; drop global oldest first.
-    const all = [...loaded.sections];
-    const dropped = [];
-    let kept = [];
-    // Take sections from the END (newest) downward, dropping older entries
-    // until the kept set fits. This is the right semantics for "keep the
-    // most recent / relevant content".
-    for (let i = all.length - 1; i >= 0; i--) {
-        const next = all[i];
-        const trialSize = memoryBytes([...kept, next]);
-        if (trialSize <= budgetBytes) {
-            kept.unshift(next);
-        }
-        else if (kept.length > 0) {
-            // Already over budget by the same accounting as the check above: 
-            // nothing more will fit (older sections only get evaluated with the
-            // same growing `kept` set), so stop here.
-            break;
-        }
-        else {
-            // Nothing kept yet and this section alone is too big: skip it.
-            dropped.push(next);
+    const stale = opts.stale;
+    if (memoryBytes(all, stale) <= budgetBytes) {
+        return { markdown: formatSections(all, stale), sections: [...all], dropped: [], found: true };
+    }
+    const ranked = scoreSections(all, opts.task ?? '').map((r) => r.section);
+    const pins = [];
+    let used = 0;
+    for (const s of ranked.filter((r) => r.pinned)) {
+        const size = sectionBytes(s, stale) + 2;
+        // A pin bigger than the whole pin cap can never be guaranteed; it competes as a ranked match below.
+        if (size <= PIN_BUDGET_BYTES && used + size <= PIN_BUDGET_BYTES && used + size <= budgetBytes) {
+            pins.push(s);
+            used += size;
         }
     }
-    for (const s of all) {
-        if (!kept.includes(s))
-            dropped.push(s);
+    const indexCap = Math.min(INDEX_BUDGET_BYTES, Math.floor(budgetBytes * 0.125), budgetBytes - used);
+    const index = buildIndex(all, indexCap);
+    if (index)
+        used += Buffer.byteLength(index, 'utf8') + 2;
+    const matches = [];
+    for (const s of ranked.filter((r) => !pins.includes(r) && (!r.pinned || sectionBytes(r, stale) + 2 > PIN_BUDGET_BYTES))) {
+        const size = sectionBytes(s, stale) + 2;
+        if (used + size <= budgetBytes) {
+            matches.push(s);
+            used += size;
+        }
     }
-    const markdown = kept.length === 0 ? '' : formatSections(kept);
+    // Best match last, closest to the user's prompt.
+    const kept = [...pins, ...matches.reverse()];
+    const dropped = all.filter((s) => !kept.includes(s));
+    const markdown = [index, ...kept.map((s) => formatSection(s, stale))].filter((p) => p.length > 0).join('\n\n');
     return { markdown, sections: kept, dropped, found: true };
 }
-function sectionBytes(s) {
-    // Approximate byte length: heading + 2 newlines + body.
-    return Buffer.byteLength(`## ${s.heading}\n\n${s.body}`, 'utf8');
+/** `## Memory index` with one `- heading (type)` line per section, within `capBytes`; '' if it cannot fit. */
+function buildIndex(sections, capBytes) {
+    if (capBytes < MIN_INDEX_BYTES)
+        return '';
+    const header = '## Memory index\n\n';
+    const lines = sections.map((s) => `- ${s.heading} (${s.type})`);
+    const render = (shown, hidden) => header + [...shown, ...(hidden > 0 ? [`- …and ${hidden} more`] : [])].join('\n');
+    const fits = (text) => Buffer.byteLength(text, 'utf8') + 2 <= capBytes;
+    if (fits(render(lines, 0)))
+        return render(lines, 0);
+    const shown = [];
+    for (const line of lines) {
+        if (!fits(render([...shown, line], lines.length - shown.length - 1)))
+            break;
+        shown.push(line);
+    }
+    const text = render(shown, lines.length - shown.length);
+    return fits(text) ? text : '';
+}
+function sectionBytes(s, stale) {
+    // Approximate byte length: heading (plus stale marker) + 2 newlines + body.
+    return Buffer.byteLength(formatSection(s, stale), 'utf8');
+}
+function memoryBytes(sections, stale) {
+    return sections.reduce((sum, s) => sum + sectionBytes(s, stale) + 2, 0); // +2 for separating blank line
 }
-function memoryBytes(sections) {
-    return sections.reduce((sum, s) => sum + sectionBytes(s) + 2, 0); // +2 for separating blank line
+function formatSection(s, stale) {
+    const reasons = stale?.get(staleKey(s));
+    const marker = reasons ? ` (possibly stale: ${reasons.join('; ')})` : '';
+    return `## ${s.heading}${marker}\n\n${s.body}`;
 }
-function formatSections(sections) {
-    return sections
-        .map((s) => `## ${s.heading}\n\n${s.body}`)
-        .join('\n\n');
+function formatSections(sections, stale) {
+    return sections.map((s) => formatSection(s, stale)).join('\n\n');
 }
 /**
  * Compose the system-prompt block for memory injection. Returns the empty
  * string when no memory is found (so the caller can skip the block).
  */
-export async function buildMemoryBlock(cwd, budgetBytes) {
+export async function buildMemoryBlock(cwd, budgetBytes, opts = {}) {
     const loaded = await loadMemory(cwd);
     if (loaded.sections.length === 0)
         return '';
-    const injection = injectMemory(loaded, budgetBytes);
+    let stale = new Map();
+    try {
+        stale = await checkStale(loaded.sections, (await findProjectMemoryRoot(cwd)) ?? cwd);
+    }
+    catch {
+        // A failed staleness check must never block memory injection.
+    }
+    const injection = injectMemory(loaded, budgetBytes, { ...opts, stale });
     if (!injection.found)
         return '';
-    return `<project-memory source="${cwd}">\n${injection.markdown}\n</project-memory>`;
+    const hasMarked = injection.sections.some((s) => stale.has(staleKey(s)));
+    const preamble = hasMarked
+        ? 'Entries marked (possibly stale) name things that may no longer exist; verify before relying on them.\n\n'
+        : '';
+    return `<project-memory source="${cwd}">\n${preamble}${injection.markdown}\n</project-memory>`;
 }
 // Mutation helpers: used by the memory_write tool and the test suite.
 /**
@@ -259,17 +362,20 @@ export async function writeMemoryFile(absPath, content) {
  * Append a new section (or replace an existing section with the same
  * heading) inside a memory file. Returns the new file contents.
  */
-export function composeSectionUpdate(current, heading, body) {
-    const header = `## ${heading}`;
+export function composeSectionUpdate(current, heading, body, meta) {
+    const title = heading.trim();
+    const header = `## ${title}`;
+    const content = meta ? `${formatMetaLine(meta)}\n${body.trim()}` : body.trim();
     if (!current.trim()) {
-        return `${header}\n\n${body.trim()}\n`;
+        return `${header}\n\n${content}\n`;
     }
     const lines = current.split(/\r?\n/);
-    const idx = lines.findIndex((l) => /^##\s+/.test(l) && l.slice(3).trim() === heading);
+    const wanted = normalizeHeading(title);
+    const idx = lines.findIndex((l) => /^##\s+/.test(l) && normalizeHeading(l.slice(3)) === wanted);
     if (idx === -1) {
         // Append.
         const trimmed = current.replace(/\s+$/, '');
-        return `${trimmed}\n\n${header}\n\n${body.trim()}\n`;
+        return `${trimmed}\n\n${header}\n\n${content}\n`;
     }
     // Replace existing section: drop from `idx` to next `##` or EOF.
     let end = lines.length;
@@ -281,28 +387,88 @@ export function composeSectionUpdate(current, heading, body) {
     }
     const before = lines.slice(0, idx).join('\n').replace(/\s+$/, '');
     const after = lines.slice(end).join('\n').replace(/^\s+/, '');
-    const middle = `${header}\n\n${body.trim()}\n`;
+    const middle = `${header}\n\n${content}\n`;
     return [before, middle, after].filter((s) => s.length > 0).join('\n\n') + '\n';
 }
+/** Split file text into its preamble and raw `## ` chunks, keeping each chunk verbatim. */
+function splitChunks(content) {
+    const preamble = [];
+    const chunks = [];
+    for (const line of content.split(/\r?\n/)) {
+        const h2 = /^##\s+(.+?)\s*$/.exec(line);
+        if (h2)
+            chunks.push({ heading: h2[1], lines: [line] });
+        else if (chunks.length > 0)
+            chunks[chunks.length - 1].lines.push(line);
+        else
+            preamble.push(line);
+    }
+    return {
+        preamble: preamble.join('\n').trim(),
+        chunks: chunks.map((c) => ({ heading: c.heading, raw: c.lines.join('\n').trim() })),
+    };
+}
+function joinChunks(preamble, chunks) {
+    const parts = [preamble, ...chunks.map((c) => c.raw)].filter((p) => p.length > 0);
+    return parts.length > 0 ? `${parts.join('\n\n')}\n` : '';
+}
+/**
+ * Remove the section whose heading matches `heading` (case and spacing
+ * ignored). Returns the file unchanged with `removed: false` when absent.
+ */
+export function removeSection(current, heading) {
+    const { preamble, chunks } = splitChunks(current);
+    const wanted = normalizeHeading(heading);
+    const kept = chunks.filter((c) => normalizeHeading(c.heading) !== wanted);
+    if (kept.length === chunks.length)
+        return { content: current, removed: false };
+    return { content: joinChunks(preamble, kept), removed: true };
+}
+/**
+ * Bring a memory file under `maxBytes` by dropping whole sections, lowest
+ * ranked first: lowest type weight, then oldest `updated`, then earliest in
+ * the file. Pinned sections and `keepHeading` are never dropped. If only
+ * those remain, the file is returned over the cap rather than losing them.
+ */
+export function capMemory(content, maxBytes, keepHeading) {
+    if (Buffer.byteLength(content, 'utf8') <= maxBytes)
+        return { content, dropped: [] };
+    const { preamble, chunks } = splitChunks(content);
+    const keep = normalizeHeading(keepHeading);
+    const candidates = chunks
+        .map((chunk, index) => ({ chunk, index, section: parseMemory(chunk.raw, '<cap>', 0)[0] }))
+        .filter((c) => !c.section.pinned && normalizeHeading(c.chunk.heading) !== keep)
+        .sort((a, b) => TYPE_WEIGHT[a.section.type] - TYPE_WEIGHT[b.section.type] ||
+        a.section.updatedAt - b.section.updatedAt ||
+        a.index - b.index);
+    const removed = new Set();
+    const dropped = [];
+    const render = () => joinChunks(preamble, chunks.filter((_, i) => !removed.has(i)));
+    let out = render();
+    for (const c of candidates) {
+        if (Buffer.byteLength(out, 'utf8') <= maxBytes)
+            break;
+        removed.add(c.index);
+        dropped.push(c.chunk.heading);
+        out = render();
+    }
+    return { content: out, dropped };
+}
 /**
  * Truncate a memory file to fit under `maxBytes` by dropping the oldest
- * sections. Returns the new content. Used by an auto-trim job (not yet
- * wired into the agent: see docs/ROADMAP.md).
+ * sections (file order). Sections are kept verbatim, metadata comment
+ * included. Returns the new content.
  */
 export function trimToBytes(content, maxBytes) {
     const totalBytes = Buffer.byteLength(content, 'utf8');
     if (totalBytes <= maxBytes)
         return content;
-    const sections = parseMemory(content, '<trim>', Date.now());
-    if (sections.length === 0)
-        return '';
+    let kept = splitChunks(content).chunks;
     // Drop oldest first.
-    let kept = sections;
-    while (kept.length > 0 && Buffer.byteLength(formatSections(kept), 'utf8') > maxBytes) {
+    while (kept.length > 0 && Buffer.byteLength(joinChunks('', kept), 'utf8') > maxBytes) {
         kept = kept.slice(1);
     }
-    return formatSections(kept) + (kept.length > 0 ? '\n' : '');
+    return joinChunks('', kept);
 }
 // Re-export for tests / downstream consumers.
 export { PROJECT_MEMORY_DIR as _PROJECT_MEMORY_DIR, PROJECT_MEMORY_FILE as _PROJECT_MEMORY_FILE };
-//# sourceMappingURL=memory-store.js.map

package/dist/memory/rank.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Relevance scoring for memory sections. Keyword-only (BM25-style term
+ * overlap), no embeddings: at the 8 KB injection scale it is enough, and it
+ * keeps Forge provider-agnostic with no extra service.
+ */
+import type { MemorySection, MemoryType } from './memory-store.js';
+/** Higher = more costly to ignore. A user correction outranks a plain convention. */
+export declare const TYPE_WEIGHT: Record<MemoryType, number>;
+/** Lowercase alphanumeric tokens of length >= 3, minus stopwords. Duplicates are kept. */
+export declare function tokenize(text: string): string[];
+export interface ScoredSection {
+    section: MemorySection;
+    score: number;
+}
+/**
+ * Score every section against `task`, best first. Ties break on type weight,
+ * then newer `updatedAt`, then later position in the input (so with no task
+ * the order degrades to v1's "later sections win").
+ */
+export declare function scoreSections(sections: MemorySection[], task: string): ScoredSection[];

package/dist/memory/rank.js

@@ -0,0 +1,64 @@
+/**
+ * Relevance scoring for memory sections. Keyword-only (BM25-style term
+ * overlap), no embeddings: at the 8 KB injection scale it is enough, and it
+ * keeps Forge provider-agnostic with no extra service.
+ */
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'are', 'was', 'were', 'will', 'can', 'not',
+    'you', 'your', 'has', 'have', 'had', 'but', 'all', 'any', 'how', 'what', 'when', 'where', 'which',
+    'who', 'why', 'use', 'using', 'into', 'out', 'its', 'our', 'then', 'than', 'too', 'just', 'let',
+]);
+/** Higher = more costly to ignore. A user correction outranks a plain convention. */
+export const TYPE_WEIGHT = {
+    correction: 1.5,
+    decision: 1.2,
+    convention: 1,
+    reference: 0.8,
+};
+const HEADING_WEIGHT = 2;
+const K1 = 1.2;
+const B = 0.75;
+/** Lowercase alphanumeric tokens of length >= 3, minus stopwords. Duplicates are kept. */
+export function tokenize(text) {
+    return (text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []).filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+}
+/**
+ * Score every section against `task`, best first. Ties break on type weight,
+ * then newer `updatedAt`, then later position in the input (so with no task
+ * the order degrades to v1's "later sections win").
+ */
+export function scoreSections(sections, task) {
+    const query = [...new Set(tokenize(task))];
+    const docs = sections.map((s) => {
+        const heading = tokenize(s.heading);
+        const body = tokenize(s.body);
+        const tf = new Map();
+        for (const t of heading)
+            tf.set(t, (tf.get(t) ?? 0) + HEADING_WEIGHT);
+        for (const t of body)
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        return { tf, length: heading.length * HEADING_WEIGHT + body.length };
+    });
+    const avgLen = docs.reduce((sum, d) => sum + d.length, 0) / Math.max(docs.length, 1) || 1;
+    const df = new Map();
+    for (const term of query)
+        df.set(term, docs.filter((d) => d.tf.has(term)).length);
+    const scored = sections.map((section, index) => {
+        const doc = docs[index];
+        let score = 0;
+        for (const term of query) {
+            const f = doc.tf.get(term) ?? 0;
+            if (f === 0)
+                continue;
+            const n = df.get(term);
+            const idf = Math.log(1 + (docs.length - n + 0.5) / (n + 0.5));
+            score += (idf * (f * (K1 + 1))) / (f + K1 * (1 - B + (B * doc.length) / avgLen));
+        }
+        return { section, score: score * TYPE_WEIGHT[section.type], index };
+    });
+    scored.sort((a, b) => b.score - a.score ||
+        TYPE_WEIGHT[b.section.type] - TYPE_WEIGHT[a.section.type] ||
+        b.section.updatedAt - a.section.updatedAt ||
+        b.index - a.index);
+    return scored.map(({ section, score }) => ({ section, score }));
+}

package/dist/memory/stale.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Staleness check for memory sections. A section is stale only when a ref it
+ * declares (`refs=` in its metadata comment) no longer exists. Age alone never
+ * counts: a convention can stay true for years.
+ */
+import type { MemorySection } from './memory-store.js';
+export interface StaleOptions {
+    /** Checks a `path#symbol` ref. When absent only the path is checked. */
+    symbolExists?: (file: string, symbol: string) => Promise<boolean> | boolean;
+}
+/** Key a section in the stale map. */
+export declare function staleKey(s: Pick<MemorySection, 'source' | 'heading'>): string;
+/**
+ * Returns reasons keyed by {@link staleKey} for every section with at least
+ * one dead ref. A ref that resolves outside `root` is reported without touching
+ * the filesystem, so a memory file cannot be used to probe other paths.
+ */
+export declare function checkStale(sections: MemorySection[], root: string, opts?: StaleOptions): Promise<Map<string, string[]>>;

package/dist/memory/stale.js

@@ -0,0 +1,45 @@
+/**
+ * Staleness check for memory sections. A section is stale only when a ref it
+ * declares (`refs=` in its metadata comment) no longer exists. Age alone never
+ * counts: a convention can stay true for years.
+ */
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+/** Key a section in the stale map. */
+export function staleKey(s) {
+    return `${s.source}#${s.heading}`;
+}
+/**
+ * Returns reasons keyed by {@link staleKey} for every section with at least
+ * one dead ref. A ref that resolves outside `root` is reported without touching
+ * the filesystem, so a memory file cannot be used to probe other paths.
+ */
+export async function checkStale(sections, root, opts = {}) {
+    const out = new Map();
+    for (const section of sections) {
+        const reasons = [];
+        for (const ref of section.refs) {
+            const hash = ref.indexOf('#');
+            const file = hash === -1 ? ref : ref.slice(0, hash);
+            const symbol = hash === -1 ? '' : ref.slice(hash + 1);
+            const rel = path.relative(root, path.resolve(root, file));
+            if (path.isAbsolute(file) || rel.startsWith('..') || path.isAbsolute(rel)) {
+                reasons.push(`${ref} is outside the project`);
+                continue;
+            }
+            try {
+                await stat(path.resolve(root, file));
+            }
+            catch {
+                reasons.push(`${file} no longer exists`);
+                continue;
+            }
+            if (symbol && opts.symbolExists && !(await opts.symbolExists(file, symbol))) {
+                reasons.push(`${ref} not found`);
+            }
+        }
+        if (reasons.length > 0)
+            out.set(staleKey(section), reasons);
+    }
+    return out;
+}

package/dist/model-alias.d.ts

@@ -13,4 +13,3 @@ export declare function resolveModelAlias(name: string, aliases: ModelAliases |
 };
 /** Human-readable alias list for `forge config`; '' when there are none. */
 export declare function formatAliasTable(aliases: ModelAliases | undefined): string;
-//# sourceMappingURL=model-alias.d.ts.map

package/dist/model-alias.js

@@ -47,4 +47,3 @@ export function formatAliasTable(aliases) {
     const rows = names.map((n) => `  ${n.padEnd(width)} → ${aliases[n]}`);
     return ['Model aliases (~/.forge/config.json):', ...rows].join('\n');
 }
-//# sourceMappingURL=model-alias.js.map

package/dist/model-catalog.d.ts

@@ -11,4 +11,3 @@ export interface ModelCatalogEntry {
  * short and prefer aliases; anything else is typed as a custom id.
  */
 export declare const MODEL_CATALOG: Record<ProviderName, ModelCatalogEntry[]>;
-//# sourceMappingURL=model-catalog.d.ts.map

package/dist/model-catalog.js

@@ -55,4 +55,3 @@ export const MODEL_CATALOG = {
     lmstudio: [{ id: 'local-model', label: 'Whatever model is loaded in LM Studio' }],
     'openai-compatible': [{ id: 'default', label: 'Model id your endpoint expects' }],
 };
-//# sourceMappingURL=model-catalog.js.map

package/dist/model-list.d.ts

@@ -13,4 +13,3 @@ export declare const LISTABLE_PROVIDERS: readonly ProviderName[];
 export declare function parseModels(provider: ProviderName, body: unknown): ModelCatalogEntry[];
 /** Asks the provider which models this key can use. Throws a readable message when it cannot. */
 export declare function fetchProviderModels(provider: ProviderName, opts?: FetchModelsOptions): Promise<ModelCatalogEntry[]>;
-//# sourceMappingURL=model-list.d.ts.map

package/dist/model-list.js

@@ -85,4 +85,3 @@ export async function fetchProviderModels(provider, opts = {}) {
         throw new Error('The provider returned no models.');
     return models;
 }
-//# sourceMappingURL=model-list.js.map

package/dist/orchestrator/board-tools.d.ts

@@ -4,4 +4,3 @@ import type { SpecialistId } from './types.js';
 export declare const BOARD_TOOL_NAMES: readonly ["board_post", "board_read"];
 /** Board tools for one specialist; `from` and the read cursor live in the closure. */
 export declare function createBoardTools(board: MessageBoard, selfId: SpecialistId): ToolDefinition[];
-//# sourceMappingURL=board-tools.d.ts.map

package/dist/orchestrator/board-tools.js

@@ -46,4 +46,3 @@ export function createBoardTools(board, selfId) {
     };
     return [post, read];
 }
-//# sourceMappingURL=board-tools.js.map

package/dist/orchestrator/board.d.ts

@@ -38,4 +38,3 @@ export declare class MessageBoard {
     /** How many early messages the ring buffer has dropped. */
     get trimmed(): number;
 }
-//# sourceMappingURL=board.d.ts.map

package/dist/orchestrator/board.js

@@ -39,4 +39,3 @@ export class MessageBoard {
         return this.dropped;
     }
 }
-//# sourceMappingURL=board.js.map

package/dist/orchestrator/index.d.ts

@@ -12,4 +12,3 @@ export { MessageBoard, DEFAULT_BOARD_CAP, type BoardMessage } from './board.js';
 export { createBoardTools, BOARD_TOOL_NAMES } from './board-tools.js';
 export { registerSpecialist, unregisterSpecialist, listSpecialists, getRegisteredSpecialist, loadSpecialistsFromConfig, saveSpecialistsToConfig, validateSpecialistConfig, defaultConfigPath, _resetSpecialistsForTests, _customSpecialistCount, type CustomSpecialistConfig, type SpecialistsConfigFile, type LoadSpecialistsResult, } from './specialists-registry.js';
 export type { BuiltInSpecialistId, OrchestratorPlan, OrchestratorRunResult, OrchestratorStep, OrchestratorStepResult, SpecialistConfig, SpecialistId, } from './types.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/orchestrator/index.js

@@ -11,4 +11,3 @@ export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel
 export { MessageBoard, DEFAULT_BOARD_CAP } from './board.js';
 export { createBoardTools, BOARD_TOOL_NAMES } from './board-tools.js';
 export { registerSpecialist, unregisterSpecialist, listSpecialists, getRegisteredSpecialist, loadSpecialistsFromConfig, saveSpecialistsToConfig, validateSpecialistConfig, defaultConfigPath, _resetSpecialistsForTests, _customSpecialistCount, } from './specialists-registry.js';
-//# sourceMappingURL=index.js.map

package/dist/orchestrator/orchestrator.d.ts

@@ -233,4 +233,3 @@ export declare function runRouter(args: {
  * without going through `Agent.run()`.
  */
 export declare function resolveEffectiveModel(spec: SpecialistConfig, baseModel: ModelConfig): ModelConfig;
-//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator/orchestrator.js

@@ -494,4 +494,3 @@ async function runSpecialist(args) {
     const agent = new Agent(config);
     return agent.run({ task: args.task });
 }
-//# sourceMappingURL=orchestrator.js.map

package/dist/orchestrator/router.d.ts

@@ -24,4 +24,3 @@ export declare const ROUTER_SYSTEM_PROMPT = "You are the IKarmic Forge ORCHESTRA
  * user's task to the 'code' specialist - better than crashing.
  */
 export declare function parseRouterOutput(raw: string, fallbackTask: string): OrchestratorPlan;
-//# sourceMappingURL=router.d.ts.map

package/dist/orchestrator/router.js

@@ -120,4 +120,3 @@ function fallbackPlan(task, reason = 'unparseable') {
         steps: [{ specialist: 'code', task }],
     };
 }
-//# sourceMappingURL=router.js.map