mustflow 2.59.0 → 2.68.6

package/dist/cli/lib/agent-context.js

@@ -6,28 +6,31 @@ import { readRetentionStore } from '../../core/retention-policy.js';
 import { toPosixPath } from './filesystem.js';
 import { readLocalIndexPromptContext } from './local-index.js';
 import { inspectManifestLock } from './manifest-lock.js';
-import { MUSTFLOW_JSON_MAX_BYTES, readMustflowTextFile, readMustflowTextFileIfExists, } from './mustflow-read.js';
+import { MUSTFLOW_JSON_MAX_BYTES, readMustflowTextFile, readMustflowTextFileIfExists, readMustflowTextFileResult, } from './mustflow-read.js';
 import { createRunPlan } from './run-plan.js';
 import { readMustflowTomlFile } from './toml.js';
 import { normalizeTechnologyPreferencesTable, TECHNOLOGY_CONFIG_RELATIVE_PATH, } from '../../core/technology-preferences.js';
+import { isPromptCacheStableLeafSkillSurface, measurePromptCacheReferenceBlockBytes, renderPromptCacheReferenceBlock, } from '../../core/prompt-cache-rendering.js';
+import { resolveSkillRoutes } from '../../core/skill-route-resolution.js';
 const CONTEXT_SCHEMA_VERSION = '1';
 const COMMANDS_RELATIVE_PATH = '.mustflow/config/commands.toml';
 const MUSTFLOW_RELATIVE_PATH = '.mustflow/config/mustflow.toml';
 const PREFERENCES_RELATIVE_PATH = '.mustflow/config/preferences.toml';
+const SKILL_ROUTER_RELATIVE_PATH = '.mustflow/skills/router.toml';
+const SKILL_ROUTE_CANDIDATES_VIRTUAL_PATH = '.mustflow/generated/skill-route-candidates.compact.json';
 const TECHNOLOGY_RELATIVE_PATH = TECHNOLOGY_CONFIG_RELATIVE_PATH;
 const LATEST_RUN_RELATIVE_PATH = '.mustflow/state/runs/latest.json';
 const CACHE_RELATIVE_PATH = '.mustflow/cache/';
 const STATE_RELATIVE_PATH = '.mustflow/state/';
 const DEFAULT_PROMPT_CACHE_STABLE_READ = [
     'AGENTS.md',
-    '.mustflow/docs/agent-workflow.md',
-    '.mustflow/config/mustflow.toml',
-    '.mustflow/config/commands.toml',
-    '.mustflow/skills/INDEX.md',
+    '.mustflow/skills/router.toml',
 ];
 const DEFAULT_PROMPT_CACHE_TASK_SOURCES = [
     '.mustflow/context/INDEX.md',
-    'REPO_MAP.md',
+    'skill_route_candidates',
+    'route_metadata_fallback',
+    'repo_map_navigation',
     'matching_skill',
     'relevant_source_files',
 ];
@@ -108,6 +111,145 @@ function readScalarObject(table) {
 function sha256(content) {
     return `sha256:${createHash('sha256').update(content).digest('hex')}`;
 }
+function estimateTokens(renderedBytes) {
+    return Math.ceil(renderedBytes / 4);
+}
+function budgetBytes(budgetKb) {
+    return budgetKb === null ? null : Math.round(budgetKb * 1024);
+}
+function budgetStatus(renderedBytes, budget) {
+    if (renderedBytes === null || budget === null) {
+        return 'unknown';
+    }
+    return renderedBytes <= budget ? 'within_budget' : 'over_budget';
+}
+function renderedDigest(relativePath, content) {
+    return sha256(renderPromptCacheReferenceBlock(relativePath, content));
+}
+function calculateBudgetShare(renderedBytes, budget) {
+    if (renderedBytes === null || budget === null || budget <= 0) {
+        return null;
+    }
+    return Number((renderedBytes / budget).toFixed(6));
+}
+function isDirectPromptCacheSource(source) {
+    return (source.includes('/') ||
+        source.endsWith('.md') ||
+        source.endsWith('.toml') ||
+        source.endsWith('.json') ||
+        source.endsWith('.yaml') ||
+        source.endsWith('.yml'));
+}
+function taskSourceReferencePath(source) {
+    const normalized = toPosixPath(source);
+    if (normalized === 'route_metadata_fallback') {
+        return '.mustflow/skills/routes.toml';
+    }
+    if (normalized === 'expanded_skill_index_fallback') {
+        return '.mustflow/skills/INDEX.md';
+    }
+    if (isDirectPromptCacheSource(normalized)) {
+        return normalized;
+    }
+    return null;
+}
+function taskSourceSelectionPolicy(source) {
+    const normalized = toPosixPath(source);
+    if (normalized === '.mustflow/skills/routes.toml' ||
+        normalized === '.mustflow/skills/INDEX.md' ||
+        normalized === 'route_metadata_fallback' ||
+        normalized === 'expanded_skill_index_fallback') {
+        return 'fallback_when_needed';
+    }
+    if (isDirectPromptCacheSource(normalized)) {
+        return 'read_when_selected';
+    }
+    return 'selected_at_runtime';
+}
+function taskSourceKind(source) {
+    return taskSourceReferencePath(source) === null ? 'dynamic_selection' : 'file_reference';
+}
+function taskSourceCacheability(source, selectionPolicy) {
+    if (selectionPolicy === 'fallback_when_needed') {
+        return 'task_fallback';
+    }
+    return taskSourceKind(source) === 'file_reference' ? 'task_selective' : 'runtime_selection';
+}
+function taskSourceReloadOn(source, selectionPolicy) {
+    if (selectionPolicy === 'fallback_when_needed') {
+        return ['route_resolution_changed'];
+    }
+    if (source === 'repo_map_navigation') {
+        return ['navigation_scope_changed', 'source_anchor_selection_changed'];
+    }
+    if (taskSourceKind(source) === 'file_reference') {
+        return ['task_selection_changed', 'source_file_hash_changed'];
+    }
+    if (source === 'relevant_source_files') {
+        return ['source_selection_changed'];
+    }
+    return ['route_resolution_changed'];
+}
+function isDeferredTaskFallback(selectionPolicy) {
+    return selectionPolicy === 'fallback_when_needed';
+}
+function taskSourceIssue(source, measurementStatus) {
+    if (measurementStatus === 'hash_only_deferred') {
+        return `task source is selection-gated; hash is recorded, but content is measured only when selected: ${toPosixPath(source)}`;
+    }
+    return `task source is selected at runtime and cannot be measured before the current task is assembled: ${source}`;
+}
+function hasPromptCacheRouteInput(input) {
+    return Boolean(input?.taskText?.trim() || input?.paths.length || input?.reasons.length);
+}
+function resolvePromptCacheSkillRoutes(projectRoot, input) {
+    if (!hasPromptCacheRouteInput(input)) {
+        return null;
+    }
+    return resolveSkillRoutes(projectRoot, input);
+}
+function selectedSkillRoutePaths(routeReport) {
+    return routeReport?.read_plan.selected_skill_paths ?? [];
+}
+function selectedTaskBlockOrder(sourceIndex, selectedIndex) {
+    return ((sourceIndex + 1) * 100) + selectedIndex + 1;
+}
+function compactSkillRouteCandidate(candidate) {
+    return {
+        skill: candidate.skill,
+        skill_path: candidate.skill_path,
+        category: candidate.category,
+        route_type: candidate.route_type,
+        score: Number(candidate.score.toFixed(3)),
+        selection_reasons: candidate.selection_reasons,
+        verification_intents: candidate.verification_intents,
+    };
+}
+function readCompactSkillRouteCandidateContent(routeReport) {
+    if (routeReport === null) {
+        return null;
+    }
+    return `${JSON.stringify({
+        schema_version: '1',
+        kind: 'skill_route_candidates_compact',
+        input: routeReport.input,
+        signals: {
+            task_terms: routeReport.signals.task_terms,
+            path_terms: routeReport.signals.path_terms,
+            reasons: routeReport.signals.reasons,
+        },
+        selected: {
+            main: routeReport.selected.main === null ? null : compactSkillRouteCandidate(routeReport.selected.main),
+            adjuncts: routeReport.selected.adjuncts.map(compactSkillRouteCandidate),
+        },
+        candidates: routeReport.candidates.map(compactSkillRouteCandidate),
+        read_plan: {
+            selected_skill_paths: routeReport.read_plan.selected_skill_paths,
+            candidate_skill_paths: routeReport.read_plan.candidate_skill_paths,
+            avoid_by_default: routeReport.read_plan.avoid_by_default,
+        },
+    }, null, 2)}\n`;
+}
 function readCommandContractContext(projectRoot) {
     const commands = readTomlTableIfExists(projectRoot, COMMANDS_RELATIVE_PATH);
     if (!commands || !isRecord(commands.intents)) {
@@ -283,6 +425,66 @@ function mapLocalIndexPromptContext(context) {
         refresh_hint: context.refreshHint,
     };
 }
+function readSkillRouterTable(projectRoot) {
+    try {
+        const parsed = readMustflowTomlFile(projectRoot, SKILL_ROUTER_RELATIVE_PATH);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readTaskPromptCacheRouteReadPlan(projectRoot) {
+    const router = readSkillRouterTable(projectRoot);
+    const readWhen = readNestedTable(router, 'read_when');
+    const fullRoutes = readOptionalString(router, 'full_routes') ?? '.mustflow/skills/routes.toml';
+    const expandedIndex = readOptionalString(router, 'expanded_index') ?? '.mustflow/skills/INDEX.md';
+    const skillRoot = readOptionalString(router, 'skill_root') ?? '.mustflow/skills';
+    const candidates = readNumber(router, 'selection_limit') ?? 5;
+    const main = readNumber(router, 'main_limit') ?? 1;
+    const adjuncts = readNumber(router, 'adjunct_limit') ?? 2;
+    return {
+        resolver_command: ['mf', 'skill', 'route', '--json'],
+        stable_kernel: [toPosixPath(SKILL_ROUTER_RELATIVE_PATH)],
+        route_sources: [
+            toPosixPath(fullRoutes),
+            `${toPosixPath(skillRoot)}/*/SKILL.md frontmatter`,
+        ],
+        selected_skill_paths_source: 'mf skill route --json read_plan.selected_skill_paths',
+        route_metadata_fallback: {
+            path: toPosixPath(fullRoutes),
+            read_when: readOptionalStringArray(readWhen, 'full_routes') ?? [],
+            avoid_by_default: true,
+        },
+        expanded_index_fallback: {
+            path: toPosixPath(expandedIndex),
+            read_when: readOptionalStringArray(readWhen, 'expanded_index') ?? [],
+            avoid_by_default: true,
+        },
+        selection_limits: { candidates, main, adjuncts },
+    };
+}
+function readTaskPromptCacheRepoMapReadPlan() {
+    return {
+        source: 'repo_map_navigation',
+        strategy: 'select_anchors_or_spans_before_full_map',
+        anchor_sources: [
+            'local_index source anchors',
+            'REPO_MAP.md Priority Anchors',
+            'REPO_MAP.md Source Anchors',
+        ],
+        fallback: {
+            path: 'REPO_MAP.md',
+            read_when: [
+                'broader repository navigation is needed',
+                'local index is missing, stale, or unavailable',
+                'selected anchors or spans do not identify the needed files',
+                'task edits the repository map generator or generated map contract',
+            ],
+            avoid_by_default: true,
+        },
+    };
+}
 async function readTaskPromptCacheLayer(projectRoot, mustflow) {
     const layer = readPromptCacheLayer(mustflow, 'task');
     const localIndex = await readLocalIndexPromptContext(projectRoot);
@@ -290,6 +492,8 @@ async function readTaskPromptCacheLayer(projectRoot, mustflow) {
         cache_layer: 'task',
         read_policy: readOptionalString(layer, 'read_policy'),
         sources: readOptionalStringArray(layer, 'sources') ?? [...DEFAULT_PROMPT_CACHE_TASK_SOURCES],
+        route_read_plan: readTaskPromptCacheRouteReadPlan(projectRoot),
+        repo_map_read_plan: readTaskPromptCacheRepoMapReadPlan(),
         local_index: mapLocalIndexPromptContext(localIndex),
     };
 }
@@ -303,14 +507,783 @@ function readVolatilePromptCacheLayer(mustflow) {
         include_latest_run: false,
     };
 }
-export async function getPromptCacheProfileContext(projectRoot, profile) {
+function readStablePromptBundleLayer(projectRoot, mustflow) {
+    const layer = readPromptCacheLayer(mustflow, 'stable');
+    const read = readOptionalStringArray(layer, 'read') ?? [...DEFAULT_PROMPT_CACHE_STABLE_READ];
+    return {
+        cache_layer: 'stable',
+        blocks: read.map((relativePath, index) => {
+            const path = toPosixPath(relativePath);
+            const content = safeRead(projectRoot, relativePath);
+            const renderedBytes = content === null ? null : measurePromptCacheReferenceBlockBytes(relativePath, content);
+            const issue = content === null ? `stable prefix document is missing: ${path}` : null;
+            return {
+                id: `stable:${index + 1}:${path}`,
+                cache_layer: 'stable',
+                order: index + 1,
+                kind: content === null ? 'source_placeholder' : 'file',
+                path: content === null ? null : path,
+                source: null,
+                source_kind: 'file_reference',
+                selection_policy: 'always_rendered',
+                content_included: false,
+                content_hash: content === null ? null : sha256(content),
+                rendered_digest: content === null ? null : renderedDigest(relativePath, content),
+                rendered_bytes: renderedBytes,
+                estimated_tokens: renderedBytes === null ? null : estimateTokens(renderedBytes),
+                cacheability: 'provider_prefix_candidate',
+                reload_on: ['stable_file_hash_changed'],
+                issue,
+            };
+        }),
+    };
+}
+function readTaskPromptBundleLayer(projectRoot, mustflow, routeReport) {
+    const layer = readPromptCacheLayer(mustflow, 'task');
+    const sources = readOptionalStringArray(layer, 'sources') ?? [...DEFAULT_PROMPT_CACHE_TASK_SOURCES];
+    const selectedSkillPaths = selectedSkillRoutePaths(routeReport);
+    return {
+        cache_layer: 'task',
+        blocks: sources.flatMap((source, index) => {
+            const selectionPolicy = taskSourceSelectionPolicy(source);
+            const sourceKind = taskSourceKind(source);
+            const referencePath = taskSourceReferencePath(source);
+            const content = referencePath === null ? null : safeRead(projectRoot, referencePath);
+            const routeCandidateContent = source === 'skill_route_candidates'
+                ? readCompactSkillRouteCandidateContent(routeReport)
+                : null;
+            const deferFallback = isDeferredTaskFallback(selectionPolicy);
+            let contentHash = null;
+            let renderedBytes = null;
+            let blockRenderedDigest = null;
+            if (routeCandidateContent !== null) {
+                contentHash = sha256(routeCandidateContent);
+                renderedBytes = measurePromptCacheReferenceBlockBytes(SKILL_ROUTE_CANDIDATES_VIRTUAL_PATH, routeCandidateContent);
+                blockRenderedDigest = renderedDigest(SKILL_ROUTE_CANDIDATES_VIRTUAL_PATH, routeCandidateContent);
+            }
+            else if (content !== null) {
+                contentHash = sha256(content);
+                if (referencePath !== null && !deferFallback) {
+                    renderedBytes = measurePromptCacheReferenceBlockBytes(referencePath, content);
+                    blockRenderedDigest = renderedDigest(referencePath, content);
+                }
+            }
+            const hasResolvedMatchingSkill = source === 'matching_skill' && selectedSkillPaths.length > 0;
+            const hasResolvedDynamicSource = hasResolvedMatchingSkill || routeCandidateContent !== null;
+            const issue = !hasResolvedDynamicSource && (content === null || deferFallback)
+                ? taskSourceIssue(referencePath ?? source, sourceKind === 'file_reference' ? 'hash_only_deferred' : 'dynamic_unmeasured')
+                : null;
+            const baseBlock = {
+                id: `task:${index + 1}:${source}`,
+                cache_layer: 'task',
+                order: index + 1,
+                kind: sourceKind === 'file_reference' && content !== null && !deferFallback ? 'file' : 'source_placeholder',
+                path: sourceKind === 'file_reference' && content !== null ? referencePath : null,
+                source,
+                source_kind: sourceKind,
+                selection_policy: selectionPolicy,
+                content_included: false,
+                content_hash: contentHash,
+                rendered_digest: blockRenderedDigest,
+                rendered_bytes: renderedBytes,
+                estimated_tokens: renderedBytes === null ? null : estimateTokens(renderedBytes),
+                cacheability: taskSourceCacheability(source, selectionPolicy),
+                reload_on: taskSourceReloadOn(source, selectionPolicy),
+                issue,
+            };
+            if (source !== 'matching_skill') {
+                return [baseBlock];
+            }
+            const selectedBlocks = selectedSkillPaths.map((skillPath, selectedIndex) => {
+                const normalizedPath = toPosixPath(skillPath);
+                const skillContent = safeRead(projectRoot, normalizedPath);
+                const skillRenderedBytes = skillContent === null ? null : measurePromptCacheReferenceBlockBytes(normalizedPath, skillContent);
+                const skillIssue = skillContent === null
+                    ? taskSourceIssue(normalizedPath, 'hash_only_deferred')
+                    : null;
+                return {
+                    id: `task:${index + 1}:matching_skill:${selectedIndex + 1}:${normalizedPath}`,
+                    cache_layer: 'task',
+                    order: selectedTaskBlockOrder(index, selectedIndex),
+                    kind: skillContent === null ? 'source_placeholder' : 'file',
+                    path: skillContent === null ? null : normalizedPath,
+                    source,
+                    source_kind: skillContent === null ? 'dynamic_selection' : 'file_reference',
+                    selection_policy: 'selected_at_runtime',
+                    content_included: false,
+                    content_hash: skillContent === null ? null : sha256(skillContent),
+                    rendered_digest: skillContent === null ? null : renderedDigest(normalizedPath, skillContent),
+                    rendered_bytes: skillRenderedBytes,
+                    estimated_tokens: skillRenderedBytes === null ? null : estimateTokens(skillRenderedBytes),
+                    cacheability: 'runtime_selection',
+                    reload_on: ['route_resolution_changed', 'source_file_hash_changed'],
+                    issue: skillIssue,
+                };
+            });
+            return [baseBlock, ...selectedBlocks];
+        }),
+    };
+}
+function readVolatilePromptBundleLayer(mustflow) {
+    const layer = readPromptCacheLayer(mustflow, 'volatile');
+    const sources = readOptionalStringArray(layer, 'sources') ?? [...DEFAULT_PROMPT_CACHE_VOLATILE_SOURCES];
+    const issue = 'volatile suffix sources are runtime-only; current task, changed files, and command tails are not rendered here';
+    return {
+        cache_layer: 'volatile',
+        blocks: sources.map((source, index) => ({
+            id: `volatile:${index + 1}:${source}`,
+            cache_layer: 'volatile',
+            order: index + 1,
+            kind: 'source_placeholder',
+            path: null,
+            source,
+            source_kind: 'runtime_volatile',
+            selection_policy: 'volatile_runtime',
+            content_included: false,
+            content_hash: null,
+            rendered_digest: null,
+            rendered_bytes: null,
+            estimated_tokens: null,
+            cacheability: 'volatile_suffix',
+            reload_on: ['volatile_state_changed'],
+            issue,
+        })),
+    };
+}
+function readPromptBundle(projectRoot, mustflow, profile, routeReport = null) {
+    const layers = [];
+    if (profile === 'stable' || profile === 'all') {
+        layers.push(readStablePromptBundleLayer(projectRoot, mustflow));
+    }
+    if (profile === 'task' || profile === 'all') {
+        layers.push(readTaskPromptBundleLayer(projectRoot, mustflow, routeReport));
+    }
+    if (profile === 'volatile' || profile === 'all') {
+        layers.push(readVolatilePromptBundleLayer(mustflow));
+    }
+    const blocks = layers.flatMap((layer) => layer.blocks);
+    const shapeMaterial = blocks
+        .map((block) => [block.cache_layer, block.order, block.kind, block.path ?? '', block.source ?? '', block.selection_policy, block.cacheability].join('\0'))
+        .join('\n');
+    const bundleMaterial = blocks
+        .map((block) => [block.id, block.content_hash ?? '', block.rendered_digest ?? '', block.issue ?? ''].join('\0'))
+        .join('\n');
+    return {
+        schema_version: '1',
+        renderer: 'reference_bundle_utf8_lf_v1',
+        content_included: false,
+        request_shape_hash: sha256(shapeMaterial),
+        bundle_hash: sha256(bundleMaterial),
+        layers,
+        issues: [...new Set(blocks.flatMap((block) => (block.issue === null ? [] : [block.issue])))],
+    };
+}
+function isPromptBundleBlock(value) {
+    return isRecord(value) && typeof value.id === 'string' && typeof value.cache_layer === 'string' && typeof value.order === 'number';
+}
+function isPromptBundleLayer(value) {
+    return isRecord(value) && typeof value.cache_layer === 'string' && Array.isArray(value.blocks) && value.blocks.every(isPromptBundleBlock);
+}
+function isPromptBundleContext(value) {
+    return (isRecord(value) &&
+        typeof value.request_shape_hash === 'string' &&
+        typeof value.bundle_hash === 'string' &&
+        Array.isArray(value.layers) &&
+        value.layers.every(isPromptBundleLayer));
+}
+function readBaselinePromptBundle(projectRoot, baselinePath) {
+    const normalizedPath = toPosixPath(baselinePath);
+    const readResult = readMustflowTextFileResult(projectRoot, normalizedPath, { maxBytes: MUSTFLOW_JSON_MAX_BYTES });
+    if (!readResult.ok) {
+        if (!readResult.exists) {
+            return {
+                status: 'baseline_missing',
+                bundle: null,
+                issues: [`baseline context report is missing: ${normalizedPath}`],
+            };
+        }
+        return {
+            status: 'baseline_unreadable',
+            bundle: null,
+            issues: [`baseline context report is unreadable: ${readResult.error ?? normalizedPath}`],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readResult.content);
+    }
+    catch (error) {
+        return {
+            status: 'baseline_invalid',
+            bundle: null,
+            issues: [`baseline context report is not valid JSON: ${error instanceof Error ? error.message : String(error)}`],
+        };
+    }
+    if (!isRecord(parsed) || !('prompt_bundle' in parsed)) {
+        return {
+            status: 'baseline_without_prompt_bundle',
+            bundle: null,
+            issues: [`baseline context report does not contain prompt_bundle: ${normalizedPath}`],
+        };
+    }
+    if (!isPromptBundleContext(parsed.prompt_bundle)) {
+        return {
+            status: 'baseline_invalid',
+            bundle: null,
+            issues: [`baseline prompt_bundle has an unsupported shape: ${normalizedPath}`],
+        };
+    }
+    return { status: 'unchanged', bundle: parsed.prompt_bundle, issues: [] };
+}
+function blockKey(block) {
+    return `${block.cache_layer}:${block.order}`;
+}
+function blockLocation(block) {
+    return [blockKey(block), block.path ?? block.source ?? block.id].join(':');
+}
+function compareStringArray(left, right) {
+    return left.length === right.length && left.every((entry, index) => entry === right[index]);
+}
+function changedBlockFields(current, baseline) {
+    const fields = [];
+    if (current.id !== baseline.id) {
+        fields.push('id');
+    }
+    if (current.kind !== baseline.kind) {
+        fields.push('kind');
+    }
+    if (current.path !== baseline.path) {
+        fields.push('path');
+    }
+    if (current.source !== baseline.source) {
+        fields.push('source');
+    }
+    if (current.source_kind !== baseline.source_kind) {
+        fields.push('source_kind');
+    }
+    if (current.selection_policy !== baseline.selection_policy) {
+        fields.push('selection_policy');
+    }
+    if (current.content_hash !== baseline.content_hash) {
+        fields.push('content_hash');
+    }
+    if (current.rendered_digest !== baseline.rendered_digest) {
+        fields.push('rendered_digest');
+    }
+    if (current.rendered_bytes !== baseline.rendered_bytes) {
+        fields.push('rendered_bytes');
+    }
+    if (current.estimated_tokens !== baseline.estimated_tokens) {
+        fields.push('estimated_tokens');
+    }
+    if (current.cacheability !== baseline.cacheability) {
+        fields.push('cacheability');
+    }
+    if (!compareStringArray(current.reload_on, baseline.reload_on)) {
+        fields.push('reload_on');
+    }
+    if (current.issue !== baseline.issue) {
+        fields.push('issue');
+    }
+    return fields;
+}
+function flattenBundleBlocks(bundle) {
+    return bundle.layers.flatMap((layer) => layer.blocks);
+}
+function stableBundleBlocks(bundle) {
+    return flattenBundleBlocks(bundle).filter((block) => block.cache_layer === 'stable');
+}
+function promptBundleBlocksMatch(current, baseline) {
+    return changedBlockFields(current, baseline).length === 0;
+}
+function comparePromptBundles(current, baseline) {
+    const currentBlocks = flattenBundleBlocks(current);
+    const baselineBlocks = flattenBundleBlocks(baseline);
+    const currentByKey = new Map(currentBlocks.map((block) => [blockKey(block), block]));
+    const baselineByKey = new Map(baselineBlocks.map((block) => [blockKey(block), block]));
+    const keys = [...new Set([...baselineBlocks.map(blockKey), ...currentBlocks.map(blockKey)])].sort();
+    const diffs = [];
+    for (const key of keys) {
+        const currentBlock = currentByKey.get(key);
+        const baselineBlock = baselineByKey.get(key);
+        if (currentBlock && !baselineBlock) {
+            diffs.push({
+                kind: 'added',
+                cache_layer: currentBlock.cache_layer,
+                order: currentBlock.order,
+                current_id: currentBlock.id,
+                baseline_id: null,
+                reason: `prompt bundle block added at ${key}`,
+                fields: [],
+            });
+            continue;
+        }
+        if (!currentBlock && baselineBlock) {
+            diffs.push({
+                kind: 'removed',
+                cache_layer: baselineBlock.cache_layer,
+                order: baselineBlock.order,
+                current_id: null,
+                baseline_id: baselineBlock.id,
+                reason: `prompt bundle block removed at ${key}`,
+                fields: [],
+            });
+            continue;
+        }
+        if (!currentBlock || !baselineBlock) {
+            continue;
+        }
+        const fields = changedBlockFields(currentBlock, baselineBlock);
+        if (fields.length > 0) {
+            diffs.push({
+                kind: 'changed',
+                cache_layer: currentBlock.cache_layer,
+                order: currentBlock.order,
+                current_id: currentBlock.id,
+                baseline_id: baselineBlock.id,
+                reason: `prompt bundle block changed at ${key}: ${fields.join(', ')}`,
+                fields,
+            });
+        }
+    }
+    return diffs;
+}
+function emptyStableDiff(currentBundle) {
+    return {
+        stable_block_count: stableBundleBlocks(currentBundle).length,
+        baseline_stable_block_count: null,
+        matching_prefix_blocks: 0,
+        matching_prefix_ratio: null,
+        stable_prefix_preserved: null,
+        first_stable_difference: null,
+        first_stable_invalidation_reason: null,
+    };
+}
+function readStablePrefixDifference(currentBlock, baselineBlock, index) {
+    const key = `stable prefix block ${index + 1}`;
+    if (currentBlock && !baselineBlock) {
+        return {
+            kind: 'added',
+            cache_layer: currentBlock.cache_layer,
+            order: currentBlock.order,
+            current_id: currentBlock.id,
+            baseline_id: null,
+            reason: `${key} added at ${blockLocation(currentBlock)}`,
+            fields: [],
+        };
+    }
+    if (!currentBlock && baselineBlock) {
+        return {
+            kind: 'removed',
+            cache_layer: baselineBlock.cache_layer,
+            order: baselineBlock.order,
+            current_id: null,
+            baseline_id: baselineBlock.id,
+            reason: `${key} removed at ${blockLocation(baselineBlock)}`,
+            fields: [],
+        };
+    }
+    if (!currentBlock || !baselineBlock) {
+        throw new Error('stable prefix comparison reached an impossible block state');
+    }
+    const fields = changedBlockFields(currentBlock, baselineBlock);
+    return {
+        kind: 'changed',
+        cache_layer: currentBlock.cache_layer,
+        order: currentBlock.order,
+        current_id: currentBlock.id,
+        baseline_id: baselineBlock.id,
+        reason: `${key} changed at ${blockLocation(currentBlock)}: ${fields.join(', ')}`,
+        fields,
+    };
+}
+function readPromptBundleStableDiff(currentBundle, baselineBundle) {
+    const currentStableBlocks = stableBundleBlocks(currentBundle);
+    const baselineStableBlocks = stableBundleBlocks(baselineBundle);
+    const comparedBlockCount = Math.max(currentStableBlocks.length, baselineStableBlocks.length);
+    let matchingPrefixBlocks = 0;
+    let firstStableDifference = null;
+    let index = 0;
+    while (index < comparedBlockCount) {
+        const currentBlock = currentStableBlocks[index];
+        const baselineBlock = baselineStableBlocks[index];
+        if (!currentBlock || !baselineBlock || !promptBundleBlocksMatch(currentBlock, baselineBlock)) {
+            firstStableDifference = readStablePrefixDifference(currentBlock, baselineBlock, index);
+            break;
+        }
+        matchingPrefixBlocks += 1;
+        index += 1;
+    }
+    return {
+        stable_block_count: currentStableBlocks.length,
+        baseline_stable_block_count: baselineStableBlocks.length,
+        matching_prefix_blocks: matchingPrefixBlocks,
+        matching_prefix_ratio: comparedBlockCount === 0
+            ? null
+            : Number((matchingPrefixBlocks / comparedBlockCount).toFixed(6)),
+        stable_prefix_preserved: firstStableDifference === null && currentStableBlocks.length === baselineStableBlocks.length,
+        first_stable_difference: firstStableDifference,
+        first_stable_invalidation_reason: firstStableDifference?.reason ?? null,
+    };
+}
+function readPromptBundleDiff(projectRoot, currentBundle, baselinePath) {
+    const normalizedPath = toPosixPath(baselinePath);
+    const baseline = readBaselinePromptBundle(projectRoot, normalizedPath);
+    if (!baseline.bundle) {
+        return {
+            baseline_path: normalizedPath,
+            status: baseline.status,
+            baseline_request_shape_hash: null,
+            current_request_shape_hash: currentBundle.request_shape_hash,
+            request_shape_changed: null,
+            baseline_bundle_hash: null,
+            current_bundle_hash: currentBundle.bundle_hash,
+            bundle_changed: null,
+            first_difference: null,
+            stable_diff: emptyStableDiff(currentBundle),
+            changed_blocks: [],
+            issues: baseline.issues,
+        };
+    }
+    const changedBlocks = comparePromptBundles(currentBundle, baseline.bundle);
+    const requestShapeChanged = baseline.bundle.request_shape_hash !== currentBundle.request_shape_hash;
+    const bundleChanged = baseline.bundle.bundle_hash !== currentBundle.bundle_hash;
+    return {
+        baseline_path: normalizedPath,
+        status: requestShapeChanged || bundleChanged || changedBlocks.length > 0 ? 'changed' : 'unchanged',
+        baseline_request_shape_hash: baseline.bundle.request_shape_hash,
+        current_request_shape_hash: currentBundle.request_shape_hash,
+        request_shape_changed: requestShapeChanged,
+        baseline_bundle_hash: baseline.bundle.bundle_hash,
+        current_bundle_hash: currentBundle.bundle_hash,
+        bundle_changed: bundleChanged,
+        first_difference: changedBlocks[0] ?? null,
+        stable_diff: readPromptBundleStableDiff(currentBundle, baseline.bundle),
+        changed_blocks: changedBlocks.slice(0, 20),
+        issues: [],
+    };
+}
+function readStablePromptCacheAuditLayer(projectRoot, mustflow, settings) {
+    const layer = readPromptCacheLayer(mustflow, 'stable');
+    const read = readOptionalStringArray(layer, 'read') ?? [...DEFAULT_PROMPT_CACHE_STABLE_READ];
+    const budget = budgetBytes(settings.max_stable_prefix_kb);
+    const targetKb = readNumber(layer, 'target_kb');
+    const target = budgetBytes(targetKb);
+    const issues = [];
+    const blocks = read.map((relativePath, index) => {
+        const content = safeRead(projectRoot, relativePath);
+        const id = `stable:${index + 1}:${toPosixPath(relativePath)}`;
+        if (content === null) {
+            const issue = `stable prefix document is missing: ${toPosixPath(relativePath)}`;
+            issues.push(issue);
+            return {
+                id,
+                kind: 'file',
+                path: toPosixPath(relativePath),
+                source: null,
+                source_kind: 'file_reference',
+                selection_policy: 'always_rendered',
+                measurement_status: 'measured',
+                candidate_exists: false,
+                candidate_content_hash: null,
+                exists: false,
+                content_hash: null,
+                rendered_bytes: 0,
+                estimated_tokens: 0,
+                budget_share: calculateBudgetShare(0, budget),
+                issue,
+            };
+        }
+        const renderedBytes = measurePromptCacheReferenceBlockBytes(relativePath, content);
+        const contentHash = sha256(content);
+        return {
+            id,
+            kind: 'file',
+            path: toPosixPath(relativePath),
+            source: null,
+            source_kind: 'file_reference',
+            selection_policy: 'always_rendered',
+            measurement_status: 'measured',
+            candidate_exists: true,
+            candidate_content_hash: contentHash,
+            exists: true,
+            content_hash: contentHash,
+            rendered_bytes: renderedBytes,
+            estimated_tokens: estimateTokens(renderedBytes),
+            budget_share: calculateBudgetShare(renderedBytes, budget),
+            issue: null,
+        };
+    });
+    const renderedBytes = blocks.reduce((total, block) => total + (block.rendered_bytes ?? 0), 0);
+    const estimatedTokens = estimateTokens(renderedBytes);
+    const status = budgetStatus(renderedBytes, budget);
+    const targetStatus = budgetStatus(renderedBytes, target);
+    if (status === 'over_budget') {
+        issues.push(`stable prefix exceeds max_stable_prefix_kb: ${renderedBytes} rendered bytes > ${budget} budget bytes`);
+    }
+    return {
+        cache_layer: 'stable',
+        budget_kb: settings.max_stable_prefix_kb,
+        budget_bytes: budget,
+        target_kb: targetKb,
+        target_bytes: target,
+        target_status: targetStatus,
+        rendered_bytes: renderedBytes,
+        estimated_tokens: estimatedTokens,
+        budget_status: status,
+        blocks,
+        largest_blocks: [...blocks]
+            .sort((left, right) => (right.rendered_bytes ?? 0) - (left.rendered_bytes ?? 0))
+            .slice(0, 5),
+        issues,
+    };
+}
+function readTaskSourceAuditLayer(projectRoot, sources, budgetKb, routeReport) {
+    const budget = budgetBytes(budgetKb);
+    const issues = new Set();
+    const selectedSkillPaths = selectedSkillRoutePaths(routeReport);
+    const blocks = sources.flatMap((source, index) => {
+        const selectionPolicy = taskSourceSelectionPolicy(source);
+        const sourceKind = taskSourceKind(source);
+        const referencePath = taskSourceReferencePath(source);
+        const content = referencePath === null ? null : safeRead(projectRoot, referencePath);
+        const routeCandidateContent = source === 'skill_route_candidates'
+            ? readCompactSkillRouteCandidateContent(routeReport)
+            : null;
+        const deferFallback = isDeferredTaskFallback(selectionPolicy);
+        let contentHash = null;
+        let renderedBytes = null;
+        if (routeCandidateContent !== null) {
+            contentHash = sha256(routeCandidateContent);
+            renderedBytes = measurePromptCacheReferenceBlockBytes(SKILL_ROUTE_CANDIDATES_VIRTUAL_PATH, routeCandidateContent);
+        }
+        else if (content !== null) {
+            contentHash = sha256(content);
+            if (referencePath !== null && !deferFallback) {
+                renderedBytes = measurePromptCacheReferenceBlockBytes(referencePath, content);
+            }
+        }
+        const measurementStatus = routeCandidateContent !== null
+            ? 'measured'
+            : sourceKind === 'file_reference'
+                ? content === null || deferFallback
+                    ? 'hash_only_deferred'
+                    : 'measured'
+                : 'dynamic_unmeasured';
+        const hasResolvedMatchingSkill = source === 'matching_skill' && selectedSkillPaths.length > 0;
+        const hasResolvedDynamicSource = hasResolvedMatchingSkill || routeCandidateContent !== null;
+        const issue = !hasResolvedDynamicSource && (content === null || deferFallback)
+            ? taskSourceIssue(referencePath ?? source, measurementStatus)
+            : null;
+        if (issue) {
+            issues.add(issue);
+        }
+        if (!hasResolvedDynamicSource && sourceKind === 'dynamic_selection') {
+            issues.add(taskSourceIssue(source, measurementStatus));
+        }
+        const baseBlock = {
+            id: `task:${index + 1}:${source}`,
+            kind: sourceKind === 'file_reference' && content !== null && !deferFallback ? 'file' : 'source_placeholder',
+            path: sourceKind === 'file_reference' && content !== null ? referencePath : null,
+            source,
+            source_kind: sourceKind,
+            selection_policy: selectionPolicy,
+            measurement_status: measurementStatus,
+            candidate_exists: sourceKind === 'file_reference' ? content !== null : null,
+            candidate_content_hash: contentHash,
+            exists: sourceKind === 'file_reference' ? content !== null : null,
+            content_hash: contentHash,
+            rendered_bytes: renderedBytes,
+            estimated_tokens: renderedBytes === null ? null : estimateTokens(renderedBytes),
+            budget_share: calculateBudgetShare(renderedBytes, budget),
+            issue,
+        };
+        if (source !== 'matching_skill') {
+            return [baseBlock];
+        }
+        const selectedBlocks = selectedSkillPaths.map((skillPath, selectedIndex) => {
+            const normalizedPath = toPosixPath(skillPath);
+            const skillContent = safeRead(projectRoot, normalizedPath);
+            const skillRenderedBytes = skillContent === null ? null : measurePromptCacheReferenceBlockBytes(normalizedPath, skillContent);
+            const skillMeasurementStatus = skillContent === null
+                ? 'hash_only_deferred'
+                : 'measured';
+            const skillIssue = skillContent === null ? taskSourceIssue(normalizedPath, skillMeasurementStatus) : null;
+            if (skillIssue) {
+                issues.add(skillIssue);
+            }
+            return {
+                id: `task:${index + 1}:matching_skill:${selectedIndex + 1}:${normalizedPath}`,
+                kind: skillContent === null ? 'source_placeholder' : 'file',
+                path: skillContent === null ? null : normalizedPath,
+                source,
+                source_kind: skillContent === null ? 'dynamic_selection' : 'file_reference',
+                selection_policy: 'selected_at_runtime',
+                measurement_status: skillMeasurementStatus,
+                candidate_exists: skillContent !== null,
+                candidate_content_hash: skillContent === null ? null : sha256(skillContent),
+                exists: skillContent !== null,
+                content_hash: skillContent === null ? null : sha256(skillContent),
+                rendered_bytes: skillRenderedBytes,
+                estimated_tokens: skillRenderedBytes === null ? null : estimateTokens(skillRenderedBytes),
+                budget_share: calculateBudgetShare(skillRenderedBytes, budget),
+                issue: skillIssue,
+            };
+        });
+        return [baseBlock, ...selectedBlocks];
+    });
+    const measuredBytes = blocks.reduce((total, block) => total + (block.rendered_bytes ?? 0), 0);
+    const renderedBytes = measuredBytes > 0 ? measuredBytes : null;
+    const hasDynamicSources = blocks.some((block) => block.measurement_status === 'dynamic_unmeasured');
+    const measuredStatus = budgetStatus(renderedBytes, budget);
+    const status = measuredStatus === 'over_budget' || !hasDynamicSources
+        ? measuredStatus
+        : 'unknown';
+    if (measuredStatus === 'over_budget' && renderedBytes !== null && budget !== null) {
+        issues.add(`task context measured sources exceed max_task_context_kb: ${renderedBytes} rendered bytes > ${budget} budget bytes`);
+    }
+    return {
+        cache_layer: 'task',
+        budget_kb: budgetKb,
+        budget_bytes: budget,
+        target_kb: null,
+        target_bytes: null,
+        target_status: 'unknown',
+        rendered_bytes: renderedBytes,
+        estimated_tokens: renderedBytes === null ? null : estimateTokens(renderedBytes),
+        budget_status: status,
+        blocks,
+        largest_blocks: [...blocks]
+            .filter((block) => block.rendered_bytes !== null)
+            .sort((left, right) => (right.rendered_bytes ?? 0) - (left.rendered_bytes ?? 0))
+            .slice(0, 5),
+        issues: [...issues],
+    };
+}
+function readVolatileSourceAuditLayer(sources, budgetKb) {
+    const issue = 'volatile suffix sources are runtime-only; current task, changed files, and command tails are not rendered here';
+    const blocks = sources.map((source, index) => ({
+        id: `volatile:${index + 1}:${source}`,
+        kind: 'source_placeholder',
+        path: null,
+        source,
+        source_kind: 'runtime_volatile',
+        selection_policy: 'volatile_runtime',
+        measurement_status: 'dynamic_unmeasured',
+        candidate_exists: null,
+        candidate_content_hash: null,
+        exists: null,
+        content_hash: null,
+        rendered_bytes: null,
+        estimated_tokens: null,
+        budget_share: null,
+        issue,
+    }));
+    return {
+        cache_layer: 'volatile',
+        budget_kb: budgetKb,
+        budget_bytes: budgetBytes(budgetKb),
+        target_kb: null,
+        target_bytes: null,
+        target_status: 'unknown',
+        rendered_bytes: null,
+        estimated_tokens: null,
+        budget_status: 'unknown',
+        blocks,
+        largest_blocks: [],
+        issues: [issue],
+    };
+}
+function readPromptCacheAuditSummary(layers) {
+    const blocks = layers.flatMap((layer) => layer.blocks);
+    const measuredBytes = blocks.reduce((total, block) => total + (block.rendered_bytes ?? 0), 0);
+    const measuredBlockCount = blocks.filter((block) => block.measurement_status === 'measured').length;
+    const stableLayer = layers.find((layer) => layer.cache_layer === 'stable') ?? null;
+    const taskLayer = layers.find((layer) => layer.cache_layer === 'task') ?? null;
+    const volatileLayer = layers.find((layer) => layer.cache_layer === 'volatile') ?? null;
+    const stableLayerIndex = layers.findIndex((layer) => layer.cache_layer === 'stable');
+    const volatileBeforeStableCount = stableLayerIndex === -1
+        ? 0
+        : layers.slice(0, stableLayerIndex).filter((layer) => layer.cache_layer === 'volatile').length;
+    const stableLargestBlockBudgetShare = stableLayer?.largest_blocks
+        .map((block) => block.budget_share)
+        .filter((share) => share !== null)
+        .sort((left, right) => right - left)[0] ?? null;
+    const stableLeafSkillRiskPaths = stableLayer?.blocks
+        .map((block) => block.path)
+        .filter((blockPath) => blockPath !== null && isPromptCacheStableLeafSkillSurface(blockPath)) ?? [];
+    return {
+        rendered_bytes: measuredBlockCount === 0 ? null : measuredBytes,
+        estimated_tokens: measuredBlockCount === 0 ? null : estimateTokens(measuredBytes),
+        measured_block_count: measuredBlockCount,
+        dynamic_source_count: blocks.filter((block) => block.source_kind !== 'file_reference').length,
+        unresolved_reference_count: blocks.filter((block) => block.source_kind === 'file_reference' && block.measurement_status !== 'measured').length,
+        volatile_before_stable_count: volatileBeforeStableCount,
+        serialization_deterministic: true,
+        stable_leaf_skill_isolated: stableLayer === null ? null : stableLeafSkillRiskPaths.length === 0,
+        stable_leaf_skill_risk_paths: stableLeafSkillRiskPaths,
+        leaf_skill_change_stable_hash_delta: stableLeafSkillRiskPaths.length === 0 ? 0 : null,
+        stable_rendered_bytes: stableLayer?.rendered_bytes ?? null,
+        stable_estimated_tokens: stableLayer?.estimated_tokens ?? null,
+        stable_budget_status: stableLayer?.budget_status ?? null,
+        stable_largest_block_budget_share: stableLargestBlockBudgetShare,
+        task_budget_status: taskLayer?.budget_status ?? null,
+        volatile_budget_status: volatileLayer?.budget_status ?? null,
+    };
+}
+function readPromptCacheAudit(projectRoot, mustflow, profile, settings, routeReport = null) {
+    const layers = [];
+    if (profile === 'stable' || profile === 'all') {
+        layers.push(readStablePromptCacheAuditLayer(projectRoot, mustflow, settings));
+    }
+    if (profile === 'task' || profile === 'all') {
+        const taskLayer = readPromptCacheLayer(mustflow, 'task');
+        layers.push(readTaskSourceAuditLayer(projectRoot, readOptionalStringArray(taskLayer, 'sources') ?? [...DEFAULT_PROMPT_CACHE_TASK_SOURCES], settings.max_task_context_kb, routeReport));
+    }
+    if (profile === 'volatile' || profile === 'all') {
+        const volatileLayer = readPromptCacheLayer(mustflow, 'volatile');
+        layers.push(readVolatileSourceAuditLayer(readOptionalStringArray(volatileLayer, 'sources') ?? [...DEFAULT_PROMPT_CACHE_VOLATILE_SOURCES], settings.max_volatile_suffix_kb));
+    }
+    return {
+        measurement: 'reference_bundle',
+        estimator: {
+            name: 'reference_bundle_utf8_lf_v1',
+            estimated_bytes_per_token: 4,
+            caveat: 'Token counts are rough byte-based estimates, not provider billing or tokenizer output.',
+        },
+        canonicalization: [
+            'UTF-8 byte length',
+            'LF line endings',
+            'trim trailing blank lines',
+            'stable document path header before each block',
+        ],
+        summary: readPromptCacheAuditSummary(layers),
+        layers,
+        issues: layers.flatMap((layer) => layer.issues),
+    };
+}
+export async function getPromptCacheProfileContext(projectRoot, profile, options = {}) {
     const mustflow = readTomlTableIfExists(projectRoot, MUSTFLOW_RELATIVE_PATH);
     const lockInspection = inspectManifestLock(projectRoot);
+    const promptCacheSettings = readPromptCacheSettings(mustflow);
+    const routeReport = resolvePromptCacheSkillRoutes(projectRoot, options.routeInput);
+    const promptBundle = readPromptBundle(projectRoot, mustflow, profile, routeReport);
     const output = {
         schema_version: CONTEXT_SCHEMA_VERSION,
         command: 'context',
         cache_profile: profile,
-        prompt_cache: readPromptCacheSettings(mustflow),
+        prompt_cache: promptCacheSettings,
+        prompt_bundle: promptBundle,
+        ...(options.comparePath
+            ? {
+                prompt_bundle_diff: readPromptBundleDiff(projectRoot, promptBundle, options.comparePath),
+            }
+            : {}),
+        ...(options.includeAudit
+            ? {
+                cache_audit: readPromptCacheAudit(projectRoot, mustflow, profile, promptCacheSettings, routeReport),
+            }
+            : {}),
         issues: lockInspection.issues,
     };
     if (profile === 'stable' || profile === 'all') {