@prodero/curator 0.0.0-stage → 0.2.0

package/dist/core/context.js

@@ -0,0 +1,489 @@
+import { ContextAllocation, marginalValue, REQUIRED_HARD_ITEMS, REQUIRED_HARD_TOKENS, RELEVANT_HARD_ITEMS } from './context-allocation.js';
+import { buildTaskContext, evaluateApplicability, applicabilityOf } from "./applicability.js";
+import { RetrievalEvidenceCollector } from "./memory-pressure.js";
+import { readConfig } from "./storage.js";
+import { pathScopeRelevant, isPathScope } from "./path-scope.js";
+import { tokens } from "./matching.js";
+import { conflictWarnings } from "./bootstrap.js";
+import { listProjectSkills, skillContext, scoreSkill } from "./skills.js";
+import { isStaleSummary, loadMemoryCatalog, memoryHealth } from "./memory-index.js";
+import { loadKnowledgeGraph } from "./knowledge-graph.js";
+import { contextPressure, DEFAULT_CONTEXT_BUDGET_TOKENS, DEFAULT_REQUIRED_CONTEXT_BUDGET_TOKENS, safeRatio, TOKEN_COUNT_METHOD } from "./telemetry.js";
+export const MAX_CONTEXT_REQUIRED_ITEMS = REQUIRED_HARD_ITEMS;
+export const MAX_CONTEXT_RELEVANT_ITEMS = 8;
+export const MAX_CONFIGURED_CONTEXT_ITEMS = 128;
+export const MAX_CONTEXT_SKILLS = 4;
+export const MAX_OMITTED_CONTEXT_DETAILS = 32;
+export const MAX_GRAPH_EXPANSIONS = 4;
+export const MAX_GRAPH_DEPTH = 2;
+export const MAX_GRAPH_TRAVERSED_EDGES = 32;
+export const DEFAULT_CONTEXT_BUDGET_ESTIMATED_TOKENS = DEFAULT_CONTEXT_BUDGET_TOKENS;
+export const DEFAULT_REQUIRED_CONTEXT_BUDGET_ESTIMATED_TOKENS = DEFAULT_REQUIRED_CONTEXT_BUDGET_TOKENS;
+const PRIORITY_SCORE = { critical: 80, important: 40, normal: 20, contextual: 10 };
+const RELEVANCE_PRIORITY_SCORE = { critical: 8, important: 4, normal: 2, contextual: 1 };
+const CATEGORY_ORDER = ["instruction", "principle", "invariant", "constraint", "decision", "lesson", "state"];
+function lexicalScore(queryTokens, item) {
+    if (!queryTokens.size)
+        return { score: 0, signals: [] };
+    const searchable = new Set(item.tokens);
+    const titleTokens = tokens(item.title);
+    const scopeTokens = tokens(item.scopeRef ?? "");
+    const matched = [];
+    const titleMatched = [];
+    const scopeMatched = [];
+    let queryScore = 0;
+    for (const token of queryTokens) {
+        if (!searchable.has(token))
+            continue;
+        matched.push(token);
+        queryScore += token.length > 6 ? 6 : 4;
+        if (titleTokens.has(token))
+            titleMatched.push(token);
+        if (scopeTokens.has(token))
+            scopeMatched.push(token);
+    }
+    if (!matched.length)
+        return { score: 0, signals: [] };
+    const signals = [
+        { kind: "query-token", label: `Query token overlap: ${matched.join(", ")}`, score: queryScore },
+    ];
+    if (titleMatched.length)
+        signals.push({ kind: "title-token", label: `Title token match: ${titleMatched.join(", ")}`, score: titleMatched.length * 8 });
+    if (scopeMatched.length)
+        signals.push({ kind: "scope-token", label: `Scope token match: ${scopeMatched.join(", ")}`, score: scopeMatched.length * 10 });
+    signals.push({ kind: "priority", label: `${item.priority[0].toUpperCase()}${item.priority.slice(1)} priority`, score: RELEVANCE_PRIORITY_SCORE[item.priority] });
+    return { score: signals.reduce((total, signal) => total + signal.score, 0), signals };
+}
+/** Storage freshness is a small ranking hint, never evidence of semantic replacement.
+ * UTC-day precision keeps identical daily snapshots stable across reads/cache rebuilds.
+ */
+function recencySignal(item, now) {
+    const dayMs = 86_400_000;
+    const updatedDay = Math.floor(Date.parse(item.updatedAt) / dayMs);
+    const today = Math.floor(now.getTime() / dayMs);
+    if (!Number.isFinite(updatedDay) || !Number.isFinite(today))
+        return { kind: "recency", label: "Storage freshness unavailable", score: 0 };
+    const ageDays = Math.max(0, today - updatedDay);
+    const score = Math.round(0.5 * 30 / (30 + ageDays) * 1_000_000) / 1_000_000;
+    return { kind: "recency", label: `Storage freshness: updated ${ageDays} UTC day(s) ago (${item.updatedAt}); not a fact-effective date`, score };
+}
+function requiredOrder(a, b) {
+    return Number(b.contextPolicy === "required") - Number(a.contextPolicy === "required")
+        || PRIORITY_SCORE[b.priority] - PRIORITY_SCORE[a.priority]
+        || CATEGORY_ORDER.indexOf(a.category) - CATEGORY_ORDER.indexOf(b.category)
+        || a.title.localeCompare(b.title)
+        || a.id.localeCompare(b.id);
+}
+const recencyTie = (a, b) => (b.recencyTime ?? 0) - (a.recencyTime ?? 0);
+function* diverseRank(candidates, limit) {
+    // Within each scope/category group the diversity penalty is identical. Sort
+    // once, then compare group heads instead of repeatedly sorting the corpus.
+    const groups = new Map();
+    for (const candidate of candidates) {
+        const key = JSON.stringify([candidate.item.scopeRef ?? candidate.item.scope, candidate.item.category]);
+        if (!groups.has(key))
+            groups.set(key, { items: [], cursor: 0 });
+        groups.get(key).items.push(candidate);
+    }
+    const tie = (a, b) => b.score - a.score || recencyTie(a, b) || a.item.title.localeCompare(b.item.title) || a.item.id.localeCompare(b.item.id);
+    for (const group of groups.values())
+        group.items.sort(tie);
+    const scopeCounts = new Map();
+    const categoryCounts = new Map();
+    const utility = (c) => c.score * 100 - (scopeCounts.get(c.item.scopeRef ?? c.item.scope) ?? 0) * 120 - (categoryCounts.get(c.item.category) ?? 0) * 30;
+    let visited = 0;
+    while (groups.size && visited++ < limit) {
+        let bestKey = '', best;
+        for (const [key, group] of groups) {
+            const head = group.items[group.cursor];
+            if (!best || utility(head) > utility(best) || (utility(head) === utility(best) && tie(head, best) < 0)) {
+                best = head;
+                bestKey = key;
+            }
+        }
+        const group = groups.get(bestKey);
+        const next = group.items[group.cursor++];
+        if (group.cursor === group.items.length)
+            groups.delete(bestKey);
+        const scope = next.item.scopeRef ?? next.item.scope;
+        const scopePenalty = (scopeCounts.get(scope) ?? 0) * 1.2;
+        const categoryPenalty = (categoryCounts.get(next.item.category) ?? 0) * 0.3;
+        const signals = [...next.signals];
+        if (scopePenalty)
+            signals.push({ kind: "scope-diversity", label: `Scope diversity penalty: ${scope}`, score: -scopePenalty });
+        if (categoryPenalty)
+            signals.push({ kind: "category-diversity", label: `Category diversity penalty: ${next.item.category}`, score: -categoryPenalty });
+        const ranked = { ...next, signals, rankScore: next.score - scopePenalty - categoryPenalty };
+        yield ranked;
+        scopeCounts.set(scope, (scopeCounts.get(scope) ?? 0) + 1);
+        categoryCounts.set(next.item.category, (categoryCounts.get(next.item.category) ?? 0) + 1);
+    }
+}
+export async function getContext(root, query, options = {}) {
+    const evidence = options.onRetrievalEvidence ? new RetrievalEvidenceCollector() : undefined;
+    const catalog = await loadMemoryCatalog(root, options);
+    const graph = await loadKnowledgeGraph(root, catalog, options);
+    const now = options.now ?? new Date();
+    const knownSubsystems = catalog.summaries.flatMap(i => i.applicability?.kind === 'scoped' ? i.applicability.subsystems ?? [] : []);
+    const taskContext = buildTaskContext(query, options.taskContext, knownSubsystems, catalog.summaries.flatMap(i => i.applicability?.kind === 'scoped' ? i.applicability.paths ?? [] : []));
+    const decisions = new Map(catalog.summaries.map(i => [i.id, evaluateApplicability(i, taskContext, i.contextPolicy === 'required' ? 'required' : 'relevant')]));
+    const applies = (i) => i.contextPolicy === 'required' && decisions.get(i.id).state === 'applicable';
+    const relevantApplies = (i) => applicabilityOf(i).kind === 'legacy' ? evaluateApplicability(i, taskContext, 'relevant').state === 'applicable' : decisions.get(i.id).state !== 'not_applicable' && (i.contextPolicy !== 'required' || decisions.get(i.id).state === 'applicable');
+    const shadowed = new Set(catalog.summaries.filter((item) => item.status === "active" || item.status === "disputed").flatMap((item) => item.supersedes));
+    const active = catalog.summaries.filter((item) => {
+        const eligible = item.status === "active" && !shadowed.has(item.id);
+        if (!eligible)
+            evidence?.observe(item, "filtered", shadowed.has(item.id) || item.status === "superseded" ? "superseded" : "inactive");
+        return eligible;
+    });
+    const health = memoryHealth(catalog.summaries, now);
+    const contextBudgetTokens = Math.max(1, Math.floor(options.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS));
+    const requiredContextBudgetTokens = Math.min(contextBudgetTokens, Math.max(0, Math.floor(options.requiredContextBudgetTokens ?? DEFAULT_REQUIRED_CONTEXT_BUDGET_TOKENS)));
+    const maxContextItems = Math.min(MAX_CONFIGURED_CONTEXT_ITEMS, Math.max(1, Math.floor(options.maxContextItems ?? MAX_CONTEXT_RELEVANT_ITEMS)));
+    const allocation = new ContextAllocation(contextBudgetTokens, requiredContextBudgetTokens);
+    const queryTokens = tokens(query ?? "");
+    const requiredCandidates = active
+        .filter((item) => applies(item))
+        .sort((a, b) => Number(b.priority === "critical") - Number(a.priority === "critical")
+        || lexicalScore(queryTokens, b).score - lexicalScore(queryTokens, a).score || requiredOrder(a, b));
+    const requiredGlobalCandidateTokens = requiredCandidates.reduce((total, item) => total + item.estimatedTokens, 0);
+    const requiredSummaries = [];
+    const omittedRequired = [];
+    let requiredGlobalTokens = 0;
+    let requiredGlobalOmittedByBudget = 0;
+    let requiredGlobalOmittedByBudgetTokens = 0;
+    let requiredGlobalOmittedByItemLimit = 0;
+    let requiredGlobalOmittedByItemLimitTokens = 0;
+    let omittedCritical = 0;
+    for (const item of requiredCandidates) {
+        let reason = null;
+        const constraint = allocation.take('required', item.estimatedTokens);
+        if (constraint)
+            reason = constraint === 'required-item-ceiling' ? 'item-limit' : 'budget';
+        if (reason) {
+            if (item.priority === "critical")
+                omittedCritical += 1;
+            if (reason === "budget") {
+                requiredGlobalOmittedByBudget += 1;
+                requiredGlobalOmittedByBudgetTokens += item.estimatedTokens;
+            }
+            else {
+                requiredGlobalOmittedByItemLimit += 1;
+                requiredGlobalOmittedByItemLimitTokens += item.estimatedTokens;
+            }
+            evidence?.observe(item, "required", reason === "budget" ? "required-budget" : "item-limit", PRIORITY_SCORE[item.priority], PRIORITY_SCORE[item.priority]);
+            omittedRequired.push({ id: item.id, title: item.title, category: item.category, scope: item.scope, scopeRef: item.scopeRef, priority: item.priority, estimatedTokens: item.estimatedTokens, score: PRIORITY_SCORE[item.priority], rankScore: PRIORITY_SCORE[item.priority], signals: [{ kind: "priority", label: `${item.priority[0].toUpperCase()}${item.priority.slice(1)} priority`, score: PRIORITY_SCORE[item.priority] }], reason, constraint: constraint });
+            continue;
+        }
+        requiredSummaries.push(item);
+        requiredGlobalTokens += item.estimatedTokens;
+    }
+    options.onRequiredOmitted?.(omittedRequired);
+    const required = await Promise.all(requiredSummaries.map((item) => catalog.load(item.id)));
+    const requiredSelection = Object.fromEntries(requiredSummaries.map((item) => [item.id, { estimatedTokens: item.estimatedTokens, applicability: decisions.get(item.id), ...lexicalScore(queryTokens, item), rankScore: lexicalScore(queryTokens, item).score }]));
+    for (const item of requiredSummaries) {
+        const selected = requiredSelection[item.id];
+        evidence?.observe(item, "required", "selected", selected.score, selected.rankScore, selected.signals);
+    }
+    const requiredIds = new Set(requiredCandidates.map((item) => item.id));
+    const requiredGlobalExcludedItems = requiredCandidates.length - requiredSummaries.length;
+    const requiredGlobalExcludedTokens = requiredGlobalCandidateTokens - requiredGlobalTokens;
+    let contextTokens = requiredGlobalTokens;
+    const lexicalMatches = active
+        .filter((item) => !requiredIds.has(item.id))
+        .filter((item) => { const matches = relevantApplies(item); if (!matches)
+        evidence?.observe(item, "filtered", "scope-mismatch"); return matches; })
+        .map((item) => {
+        const lexical = lexicalScore(queryTokens, item);
+        const applicability = decisions.get(item.id);
+        if (applicabilityOf(item).kind === 'scoped' && applicability.state === 'applicable') {
+            lexical.score += 10 * applicability.matched;
+            lexical.signals.push({ kind: 'scope-token', label: applicability.reasons.join('; '), score: 10 * applicability.matched });
+        }
+        if (isPathScope(item) && applicability.state === 'applicable') {
+            lexical.score += 10;
+            lexical.signals.push({ kind: "scope-token", label: "Exact or descendant repository path", score: 10 });
+        }
+        return { item, ...lexical, stale: isStaleSummary(item, now) };
+    })
+        .filter(({ item, score, signals }) => { if (score <= 0)
+        evidence?.observe(item, "filtered", "no-match", score, null, signals); return score > 0; });
+    const requiredSeedMatches = requiredSummaries
+        .map((item) => ({ item, ...lexicalScore(queryTokens, item), stale: isStaleSummary(item, now) }))
+        .filter(({ score }) => score > 0);
+    const matchingRelevant = [...lexicalMatches];
+    const graphCandidates = new Set([...matchingRelevant, ...requiredSeedMatches].map(({ item }) => item.id));
+    const activeById = new Map(active.map((item) => [item.id, item]));
+    const traversalSeeds = [...lexicalMatches, ...requiredSeedMatches].sort((a, b) => b.score - a.score || a.item.id.localeCompare(b.item.id)).slice(0, maxContextItems);
+    const queue = traversalSeeds.map((seed) => ({ id: seed.item.id, depth: 0, seed }));
+    let traversedEdges = 0;
+    let expandedItems = 0;
+    for (let cursor = 0; cursor < queue.length && expandedItems < MAX_GRAPH_EXPANSIONS && traversedEdges < MAX_GRAPH_TRAVERSED_EDGES; cursor += 1) {
+        const current = queue[cursor];
+        if (current.depth >= MAX_GRAPH_DEPTH)
+            continue;
+        const graphPathPriority = (id) => {
+            const item = activeById.get(id);
+            return item && isPathScope(item) && pathScopeRelevant(query ?? "", item) ? 1 : 0;
+        };
+        const edges = graph.neighbors(current.id).filter((edge) => edge.weight > 0)
+            .sort((a, b) => graphPathPriority(b.to) - graphPathPriority(a.to) || b.weight - a.weight || a.type.localeCompare(b.type) || a.to.localeCompare(b.to));
+        for (const edge of edges) {
+            if (traversedEdges >= MAX_GRAPH_TRAVERSED_EDGES || expandedItems >= MAX_GRAPH_EXPANSIONS)
+                break;
+            traversedEdges += 1;
+            const item = activeById.get(edge.to);
+            if (!item || requiredIds.has(item.id) || graphCandidates.has(item.id) || !relevantApplies(item) || (applicabilityOf(item).kind === 'scoped' && decisions.get(item.id).state === 'unknown' && lexicalScore(queryTokens, item).score <= 0))
+                continue;
+            const graphScore = Math.max(1, current.seed.score * 0.25 + edge.weight / (current.depth + 1));
+            const priorityScore = RELEVANCE_PRIORITY_SCORE[item.priority];
+            const score = graphScore + priorityScore;
+            matchingRelevant.push({
+                item,
+                score,
+                stale: isStaleSummary(item, now),
+                signals: [
+                    { kind: "graph-edge", label: `${edge.type} from ${current.seed.item.title} at depth ${current.depth + 1}`, score: graphScore },
+                    { kind: "priority", label: `${item.priority[0].toUpperCase()}${item.priority.slice(1)} priority`, score: priorityScore },
+                ],
+            });
+            graphCandidates.add(item.id);
+            expandedItems += 1;
+            queue.push({ id: item.id, depth: current.depth + 1, seed: current.seed });
+        }
+    }
+    // Purpose adjusts only already-retrieved candidates; it never admits unrelated knowledge.
+    if (options.purpose === "explain") {
+        for (const candidate of matchingRelevant) {
+            if (!["decision", "lesson", "state"].includes(candidate.item.category))
+                continue;
+            candidate.score += 2;
+            candidate.signals.push({ kind: "purpose", label: "Explain: decisions, lessons and state history", score: 2 });
+        }
+    }
+    // Apply only after lexical/path/graph eligibility and purpose scoring. Freshness
+    // never admits unrelated records, alters graph expansion or ranks required rules.
+    for (const candidate of matchingRelevant) {
+        if (requiredIds.has(candidate.item.id))
+            continue;
+        const recency = recencySignal(candidate.item, now);
+        candidate.score += recency.score;
+        candidate.signals.push(recency);
+        const updated = Date.parse(candidate.item.updatedAt);
+        // Same-day evidence still orders by update time; clock skew gets no future advantage.
+        candidate.recencyTime = Number.isFinite(updated) ? Math.min(updated, now.getTime()) : 0;
+    }
+    const activeSkills = (await listProjectSkills(root)).filter((skill) => skill.status === "active");
+    const projectSkillsTokens = activeSkills.reduce((total, skill) => total + skillContext(skill).estimatedTokens, 0);
+    const matchingSkills = activeSkills.map((skill) => ({ skill, ...scoreSkill(query ?? "", skill) }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score || a.skill.id.localeCompare(b.skill.id));
+    const skills = [];
+    const omittedSkills = [];
+    let selectedSkillsTokens = 0;
+    let omittedSkillsByBudget = 0;
+    let omittedSkillsByItemLimit = 0;
+    const skillBudgetTokens = Math.min(1_500, allocation.remaining);
+    const strongSkill = (s) => s.score >= 14;
+    function selectSkills(candidates) {
+        for (const { skill, score, signals } of candidates) {
+            const context = skillContext(skill);
+            const constraint = allocation.take('skill', context.estimatedTokens);
+            if (constraint) {
+                if (constraint === 'skill-item-ceiling')
+                    omittedSkillsByItemLimit++;
+                else
+                    omittedSkillsByBudget++;
+                omittedSkills.push({ id: skill.id, reason: constraint, estimatedTokens: context.estimatedTokens });
+                continue;
+            }
+            skills.push({ ...context, score, signals });
+            selectedSkillsTokens += context.estimatedTokens;
+            contextTokens += context.estimatedTokens;
+        }
+    }
+    selectSkills(matchingSkills.filter(strongSkill));
+    const protectedSkillTokens = selectedSkillsTokens;
+    const rankedIds = new Set();
+    const ranked = diverseRank(matchingRelevant, matchingRelevant.length);
+    const relevant = [];
+    const relevantSelection = {};
+    const omittedRelevant = [];
+    let omittedRelevantByBudget = 0;
+    let omittedRelevantByItemLimit = 0;
+    let omittedRelevantByMarginalValue = 0;
+    const suppliedTerms = new Set(requiredSummaries.flatMap(i => i.tokens));
+    const peakScore = matchingRelevant.reduce((peak, c) => Math.max(peak, c.score), 0);
+    let outsideReason = 'item-limit';
+    const minimumRelevantCost = matchingRelevant.reduce((n, c) => Math.min(n, c.item.estimatedTokens), Infinity);
+    let selectedContextualTokens = 0;
+    let staleRelevantItems = 0;
+    for (const candidate of ranked) {
+        rankedIds.add(candidate.item.id);
+        let reason = null;
+        const marginal = marginalValue(candidate.item.tokens, queryTokens, suppliedTerms, candidate.rankScore, peakScore);
+        let constraint = null;
+        if (candidate.item.estimatedTokens > allocation.remaining) {
+            reason = 'budget';
+            omittedRelevantByBudget++;
+            constraint = 'total-capacity';
+        }
+        else if (relevant.length >= maxContextItems && !marginal.useful) {
+            reason = 'marginal-value';
+            omittedRelevantByMarginalValue++;
+        }
+        else {
+            constraint = allocation.take('relevant', candidate.item.estimatedTokens);
+            if (constraint) {
+                reason = constraint === 'relevant-item-ceiling' ? 'item-limit' : 'budget';
+                if (reason === 'item-limit')
+                    omittedRelevantByItemLimit++;
+                else
+                    omittedRelevantByBudget++;
+            }
+        }
+        if (relevant.length >= maxContextItems)
+            candidate.signals.push({ kind: 'marginal-value', label: `New information terms: ${marginal.novelTerms}; fraction ${marginal.novelFraction.toFixed(2)}`, score: 0 });
+        if (reason) {
+            evidence?.observe(candidate.item, "contextual", reason === "budget" ? "context-budget" : reason === "marginal-value" ? "marginal-value" : "item-limit", candidate.score, candidate.rankScore, candidate.signals);
+            if (omittedRelevant.length < MAX_OMITTED_CONTEXT_DETAILS)
+                omittedRelevant.push({ id: candidate.item.id, title: candidate.item.title, category: candidate.item.category, scope: candidate.item.scope, scopeRef: candidate.item.scopeRef, priority: candidate.item.priority, estimatedTokens: candidate.item.estimatedTokens, score: candidate.score, rankScore: candidate.rankScore, signals: candidate.signals, reason, ...(constraint ? { constraint } : {}) });
+            if (allocation.remaining < minimumRelevantCost) {
+                outsideReason = 'budget';
+                break;
+            }
+            if (relevant.length >= maxContextItems && candidate.rankScore < Math.max(12, peakScore * 0.3)) {
+                outsideReason = 'marginal-value';
+                break;
+            }
+            continue;
+        }
+        evidence?.observe(candidate.item, "contextual", "selected", candidate.score, candidate.rankScore, candidate.signals);
+        relevant.push(await catalog.load(candidate.item.id));
+        relevantSelection[candidate.item.id] = { applicability: decisions.get(candidate.item.id), estimatedTokens: candidate.item.estimatedTokens, score: candidate.score, rankScore: candidate.rankScore, signals: candidate.signals };
+        selectedContextualTokens += candidate.item.estimatedTokens;
+        contextTokens += candidate.item.estimatedTokens;
+        if (candidate.stale)
+            staleRelevantItems += 1;
+        for (const token of candidate.item.tokens)
+            suppliedTerms.add(token);
+        if (relevant.length >= RELEVANT_HARD_ITEMS)
+            break;
+    }
+    const outsideRankWindow = matchingRelevant.length - rankedIds.size;
+    if (outsideReason === 'budget')
+        omittedRelevantByBudget += outsideRankWindow;
+    else if (outsideReason === 'marginal-value')
+        omittedRelevantByMarginalValue += outsideRankWindow;
+    else
+        omittedRelevantByItemLimit += outsideRankWindow;
+    for (const candidate of matchingRelevant)
+        if (!rankedIds.has(candidate.item.id))
+            evidence?.observe(candidate.item, "contextual", outsideReason === 'budget' ? 'context-budget' : outsideReason, candidate.score, null, candidate.signals);
+    for (const candidate of matchingRelevant
+        .filter(({ item }) => !rankedIds.has(item.id))
+        .sort((a, b) => b.score - a.score || recencyTie(a, b) || a.item.title.localeCompare(b.item.title) || a.item.id.localeCompare(b.item.id))) {
+        if (omittedRelevant.length >= MAX_OMITTED_CONTEXT_DETAILS)
+            break;
+        omittedRelevant.push({ id: candidate.item.id, title: candidate.item.title, category: candidate.item.category, scope: candidate.item.scope, scopeRef: candidate.item.scopeRef, priority: candidate.item.priority, estimatedTokens: candidate.item.estimatedTokens, score: candidate.score, rankScore: candidate.score, signals: candidate.signals, reason: outsideReason, ...(outsideReason === 'item-limit' ? { constraint: 'relevant-item-ceiling' } : outsideReason === 'budget' ? { constraint: 'total-capacity' } : {}) });
+    }
+    const omittedRelevantTotal = omittedRelevantByBudget + omittedRelevantByItemLimit + omittedRelevantByMarginalValue;
+    selectSkills(matchingSkills.filter(s => !strongSkill(s)));
+    const projectKnowledgeTokens = active.reduce((total, item) => total + item.estimatedTokens, 0);
+    const pressure = contextPressure(requiredGlobalCandidateTokens, requiredContextBudgetTokens);
+    const attention = [];
+    const relevantDisputes = catalog.summaries.filter((item) => item.status === "disputed" && !shadowed.has(item.id) && relevantApplies(item) && (applies(item) || lexicalScore(queryTokens, item).score > 0));
+    if (relevantDisputes.length)
+        attention.push({ kind: "conflict", severity: "critical", title: `${relevantDisputes.length} disputed knowledge item(s) match this task`, detail: relevantDisputes.slice(0, 2).map((item) => item.title).join(" vs ") });
+    const instructionConflicts = conflictWarnings(catalog.summaries.filter(item => !shadowed.has(item.id) && ["active", "disputed"].includes(item.status) && applies(item)));
+    const applicableRequired = catalog.summaries.filter(item => !shadowed.has(item.id) && ['active', 'disputed'].includes(item.status) && applies(item));
+    const applicableRequiredIds = new Set(applicableRequired.map(i => i.id));
+    const blockingConflict = applicableRequired.some(i => i.status === 'disputed' || i.relations.some(r => r.type === 'contradicts' && applicableRequiredIds.has(r.target)));
+    const unknownRequired = catalog.summaries.filter(i => !shadowed.has(i.id) && ['active', 'disputed'].includes(i.status) && i.contextPolicy === 'required' && decisions.get(i.id).state === 'unknown');
+    const policyReadiness = { state: blockingConflict ? 'review-required' : unknownRequired.length ? 'context-needed' : requiredGlobalExcludedItems ? 'required-incomplete' : 'ready', blocking: blockingConflict || unknownRequired.length > 0 || requiredGlobalExcludedItems > 0 };
+    if (unknownRequired.length)
+        attention.push({ kind: 'memory-health', severity: 'important', title: 'Resolve task context before continuing', detail: `${unknownRequired.length} scoped required policies need task paths, subsystem or activity signals. The agent can enrich Task Context and retry Prepare; no knowledge approval is requested.` });
+    if (blockingConflict)
+        attention.push({ kind: 'conflict', severity: 'critical', title: 'Resolve required policies before continuing', detail: 'Applicable required knowledge has an explicit conflict or unresolved dispute. Keep the original task and retry Prepare after the policy is resolved.' });
+    if (instructionConflicts.length && !relevantDisputes.length)
+        attention.push({ kind: "conflict", severity: "critical", title: "Required instruction conflicts", detail: instructionConflicts.join(" ") });
+    if (requiredGlobalExcludedItems)
+        attention.push({ kind: "context-budget", severity: "critical", title: "Required context is incomplete", detail: `${requiredGlobalExcludedItems} applicable required records cannot be delivered within total capacity or safety ceilings. Do not proceed as if mandatory context were complete; inspect omissions and retry with a suitably scoped task or explicit capacity change.` });
+    if (evidence)
+        options.onRetrievalEvidence?.(evidence.finish(query ?? "", options.purpose ?? "work", { contextBudgetTokens, requiredContextBudgetTokens, maxRequiredItems: MAX_CONTEXT_REQUIRED_ITEMS, maxContextItems }));
+    return {
+        projectRoot: root,
+        allocation: { version: 2, required: { demandItems: requiredCandidates.length, demandTokens: requiredGlobalCandidateTokens, selectedItems: required.length, selectedTokens: requiredGlobalTokens, reserveTokens: requiredContextBudgetTokens, borrowedTokens: Math.max(0, requiredGlobalTokens - requiredContextBudgetTokens), complete: requiredGlobalExcludedItems === 0 && unknownRequired.length === 0 && !blockingConflict, hardTokens: REQUIRED_HARD_TOKENS, hardItems: REQUIRED_HARD_ITEMS }, relevant: { candidates: matchingRelevant.length, selected: relevant.length, softTarget: maxContextItems, hardItems: RELEVANT_HARD_ITEMS, beyondTarget: Math.max(0, relevant.length - maxContextItems), omissions: { capacity: omittedRelevantByBudget, safety: omittedRelevantByItemLimit, marginalValue: omittedRelevantByMarginalValue }, stopReason: omittedRelevantByItemLimit ? 'safety-ceiling' : omittedRelevantByBudget ? 'capacity' : omittedRelevantByMarginalValue ? 'marginal-value' : 'candidates-exhausted' }, skills: { candidates: matchingSkills.length, selected: skills.length, tokens: selectedSkillsTokens, protectedTokens: protectedSkillTokens, omitted: omittedSkills }, unusedTokens: allocation.remaining },
+        policyReadiness,
+        taskContext,
+        applicability: { unknownRequired: unknownRequired.length, decisions: Object.fromEntries([...required, ...relevant, ...unknownRequired.slice(0, 32), ...active.filter(i => !requiredIds.has(i.id)).slice(0, 32)].map(i => [i.id, decisions.get(i.id)])), truncated: Math.max(0, unknownRequired.length - 32) },
+        purpose: options.purpose ?? "work",
+        query: query?.trim() || null,
+        required,
+        relevant,
+        skills,
+        snapshot: { version: 1, sessionId: null, task: query?.trim() || null },
+        selection: {
+            required: requiredSelection,
+            relevant: relevantSelection,
+            omittedRequired: omittedRequired.slice(0, MAX_OMITTED_CONTEXT_DETAILS),
+            omittedRelevant,
+            omittedRelevantByMarginalValue,
+            omittedRelevantByBudget,
+            omittedRelevantByItemLimit,
+            omittedRelevantDetailsTruncated: Math.max(0, omittedRelevantTotal - omittedRelevant.length),
+            omittedSkillsByBudget,
+            omittedSkillsByItemLimit,
+            loadedKnowledgeItems: required.length + relevant.length,
+            graphTraversal: { seedCount: traversalSeeds.length, traversedEdges, expandedItems, maxDepth: MAX_GRAPH_DEPTH, expansionLimit: MAX_GRAPH_EXPANSIONS },
+        },
+        warnings: [
+            ...(options.pendingSessions ? [`${options.pendingSessions} session file(s) contain unsynchronized changes.`] : []),
+            ...(requiredGlobalExcludedItems ? [`Required context was truncated (required-incomplete): ${requiredGlobalExcludedItems} applicable records exceeded total capacity or a hard safety ceiling.`] : []),
+        ],
+        attention,
+        memoryHealth: health,
+        knowledgeGraph: graph.diagnostics,
+        metrics: {
+            tokenCountMethod: TOKEN_COUNT_METHOD,
+            estimated: true,
+            projectKnowledgeTokens,
+            requiredGlobalTokens,
+            requiredGlobalCandidateTokens,
+            requiredGlobalExcludedItems,
+            requiredCriticalOmitted: omittedCritical,
+            requiredNormalOmitted: requiredGlobalExcludedItems - omittedCritical,
+            requiredGlobalExcludedTokens,
+            requiredGlobalOmittedByBudget,
+            requiredGlobalOmittedByBudgetTokens,
+            requiredGlobalOmittedByItemLimit,
+            requiredGlobalOmittedByItemLimitTokens,
+            requiredContextBudgetTokens,
+            selectedContextualTokens,
+            selectedSkillsTokens,
+            projectSkillsTokens,
+            skillSelectivity: safeRatio(selectedSkillsTokens, projectSkillsTokens),
+            contextTokens,
+            contextBudgetTokens,
+            contextSelectivity: safeRatio(requiredGlobalTokens + selectedContextualTokens, projectKnowledgeTokens),
+            requiredGlobalPressure: pressure,
+            staleRelevantItems,
+        },
+        agentUsage: null,
+        limits: { maxSkills: MAX_CONTEXT_SKILLS, skillBudgetTokens, maxRequiredItems: MAX_CONTEXT_REQUIRED_ITEMS, maxRelevantItems: maxContextItems, contextBudgetTokens, requiredContextBudgetTokens, tokenCountMethod: TOKEN_COUNT_METHOD, estimated: true },
+    };
+}
+/** Shared read-only Context Engine entry point. Lifecycle owns sync and session association. */
+export async function prepareContext(root, options = {}) {
+    const config = await readConfig(root);
+    if (!config)
+        throw new Error("Prodero is not initialized for this project.");
+    return getContext(root, options.query, {
+        ...options,
+        persistCache: false,
+        contextBudgetTokens: config.context?.max_tokens ?? config.context?.budgetTokens,
+        maxContextItems: config.context?.max_items,
+        requiredContextBudgetTokens: config.context?.required_max_tokens ?? config.context?.requiredBudgetTokens,
+    });
+}
+//# sourceMappingURL=context.js.map

package/dist/core/curation-clauses.js

@@ -0,0 +1,68 @@
+/** Curation-only semantic roles. These are proposals, never authorization. */
+import { analyzeKnowledgeText } from './knowledge-analysis.js';
+const labels = /^(Decision|Impact|Constraint|Correction|Guard Pattern|Workflow Note|Test-Quality Note|State|Lesson|Principle|Invariant):\s*$/gmi;
+const norm = /\b(?:must|should|never|always|required|only|cannot|do not|keep|preserve)\b/i;
+function role(label, body) {
+    // Explicit supporting fields do not gain authority from imperative grammar.
+    if (/test-quality|lesson|correction/.test(label))
+        return 'lesson';
+    if (/workflow/.test(label))
+        return 'procedure';
+    if (!/\b(?:must|required|only)\b/i.test(body) && (/^(?:Run\b|For .*\b(?:run|coverage),?\b)/i.test(body.trim()) || /^`?\.\/vendor\/bin\//m.test(body)))
+        return 'command';
+    if (label === 'state' || /\b(?:currently fails|remains? blocked|planned work owns|temporary workaround)\b/i.test(body) && !/\b(?:must|should|only|unless|never)\b/i.test(body))
+        return 'history';
+    if (label === 'invariant' || /\btransactional invariant\b/i.test(body))
+        return 'invariant';
+    if (norm.test(body))
+        return /constraint|guard/.test(label) || /\b(?:must not|never|cannot|fail.closed)\b/i.test(body) ? 'constraint' : 'convention';
+    if (label === 'impact')
+        return 'rationale';
+    return 'unresolved';
+}
+export function refineCurationClauses(title, content) {
+    const fields = [...content.matchAll(labels)];
+    // Unstructured authored rules stay intact; no speculative policy demotion.
+    if (!fields.length)
+        return analyzeKnowledgeText(title, content).map(p => ({ ...p, role: 'unresolved', normative: true }));
+    const fieldsWithBounds = fields.map((m, i) => ({ start: i === 0 ? 0 : m.index, end: fields[i + 1]?.index ?? content.length, label: m[1].toLowerCase(), bodyStart: m.index + m[0].length }));
+    const chunks = fieldsWithBounds.flatMap(c => {
+        // Split only at complete sentence boundaries, then immediately coalesce equal
+        // roles. Exact offsets include labels/whitespace, so nothing disappears.
+        const breaks = [...content.slice(c.bodyStart, c.end).matchAll(/(?<=[.!?])\s+(?=[A-Z`])/g)].map(m => c.bodyStart + m.index + m[0].length);
+        const starts = [c.start, ...breaks];
+        return starts.map((start, i) => ({ ...c, start, end: starts[i + 1] ?? c.end, bodyStart: i === 0 ? c.bodyStart : start }));
+    });
+    const parts = [];
+    for (const c of chunks) {
+        const r = role(c.label, content.slice(c.bodyStart, c.end));
+        const p = analyzeKnowledgeText(title, content.slice(c.start, c.end))[0];
+        const normative = ['constraint', 'invariant', 'convention'].includes(r);
+        const previous = parts.at(-1);
+        // Adjacent normative clauses form one coherent constraint; adjacent support of
+        // the same lifecycle/role stays together. Never discard the original labels.
+        if (previous && (previous.normative && normative || previous.role === r)) {
+            previous.end = c.end;
+            previous.content = content.slice(previous.start, c.end).trim();
+            previous.evidence.push(`Source field ${c.label}: ${r}`);
+            continue;
+        }
+        parts.push({ ...p, start: c.start, end: c.end, content: content.slice(c.start, c.end).trim(), role: r, normative,
+            category: r === 'history' ? 'state' : r === 'lesson' ? 'lesson' : p.category,
+            transient: r === 'history', evidence: [`Source characters ${c.start}–${c.end}`, `Semantic role: ${r}; ${normative ? 'source-supported normative clause' : 'supporting knowledge, not independently mandatory'}`] });
+    }
+    const grouped = [];
+    for (const p of parts) {
+        const prior = grouped.find(g => (g.normative && p.normative || g.role === p.role) && JSON.stringify(g.applicability) === JSON.stringify(p.applicability));
+        if (prior) {
+            prior.segments ??= [{ start: prior.start, end: prior.end }];
+            prior.segments.push({ start: p.start, end: p.end });
+            prior.content += '\n\n' + p.content;
+            prior.evidence.push(...p.evidence);
+        }
+        else
+            grouped.push({ ...p });
+    }
+    return grouped.map((p, i) => ({ ...p, title: grouped.length === 1 ? title : `${title.slice(0, 155)} · ${p.role} ${i + 1}` }));
+}
+//# sourceMappingURL=curation-clauses.js.map