mustflow 2.22.4 → 2.22.5

package/dist/cli/lib/validation/index.js

@@ -11,13 +11,15 @@ import { listFilesRecursive, toPosixPath } from '../filesystem.js';
 import { readGitChangedFiles } from '../git-changes.js';
 import { inspectManifestLock } from '../manifest-lock.js';
 import { generateRepoMap } from '../repo-map.js';
-import { readTomlFile } from '../toml.js';
+import { parseTomlText, readMustflowTomlFile } from '../toml.js';
+import { MUSTFLOW_JSON_MAX_BYTES, readMustflowTextFileResult, } from '../mustflow-read.js';
 import { getContractModelDefinitions, validateCandidateContractModelConfig, } from '../../../core/contract-models.js';
 import { VERSIONING_CONFIG_PATH, detectVersionSourcePaths, readDeclaredVersionSources, releaseVersioningIsEnabled, } from '../../../core/version-sources.js';
-import { ALLOWED_APPROVAL_ACTIONS, ALLOWED_APPROVAL_GATES, ALLOWED_BUDGET_LIMIT_ACTIONS, ALLOWED_CAPABILITY_STATES, ALLOWED_COMMIT_MESSAGE_STYLES, ALLOWED_COMPACTION_CATEGORIES, ALLOWED_COMPACTION_LONG_LIMIT_ACTIONS, ALLOWED_COMPACTION_RAW_LIMIT_ACTIONS, ALLOWED_COMPACTION_STATE_STORES, ALLOWED_COMPACTION_STRATEGIES, ALLOWED_CONTEXT_AUTHORITIES, ALLOWED_CONTEXT_DOCUMENT_AUTHORITIES, ALLOWED_CONTEXT_READ_POLICIES, ALLOWED_HANDOFF_MODES, ALLOWED_HARNESS_FRESH_CONTEXT_MODES, ALLOWED_HARNESS_MODES, ALLOWED_HARNESS_PHASES, ALLOWED_ISOLATION_PREFERENCES, ALLOWED_MAP_MODES, ALLOWED_MAP_PRIVACY_LEVELS, ALLOWED_PROJECT_PROFILES, ALLOWED_PROMPT_CACHE_STABLE_PREFIX_POLICIES, ALLOWED_PROMPT_CACHE_STRATEGIES, ALLOWED_PROMPT_CACHE_TASK_READ_POLICIES, ALLOWED_REFRESH_CHECKPOINTS, ALLOWED_REFRESH_METHODS, ALLOWED_REFRESH_MODES, ALLOWED_REFRESH_STATE_STORES, ALLOWED_SKILL_RESOURCE_TYPES, ALLOWED_SKILL_ROUTE_CATEGORIES, ALLOWED_SKILL_ROUTE_PROFILES, ALLOWED_SKILL_ROUTE_TYPES, ALLOWED_STALE_TEST_ACTIONS, ALLOWED_TEST_AUTHORING_POLICIES, ALLOWED_TEST_DELETION_REASONS, ALLOWED_TESTING_POLICIES, ALLOWED_TRANSLATION_POLICIES, ALLOWED_VERIFICATION_SELECTION_STRATEGIES, ALLOWED_VERSION_SOURCE_AUTHORITIES, ALLOWED_VERSION_SOURCE_KINDS, CAPABILITY_BOOLEAN_FIELDS, CAPABILITY_STATE_FIELDS, CONTEXT_AUTHORITY_DRIFT_PATTERNS, DESIGN_TOKEN_DEFINITION_PATTERNS, FORBIDDEN_RELEASE_VERSIONING_CONTRACT_FIELDS, FORBIDDEN_TEST_DELETION_REASONS, FORBIDDEN_VERIFICATION_SELECTION_AUTHORITY_FIELDS, LOCAL_ABSOLUTE_PATH_PATTERNS, LOCAL_TASK_STATE_ROOTS, RAW_COMMAND_FENCE_PATTERN, RELEASE_VERSIONING_BOOLEAN_FIELDS, REPO_MAP_DOC_ID, REPO_MAP_GENERATOR, REPO_MAP_LIFECYCLE, REPO_MAP_PRIVACY_MODE, REPO_MAP_RELATIVE_ROOT, REPO_MAP_REMOTE_OR_BRANCH_PATTERNS, REPO_MAP_SOURCE_FINGERPRINT_PATTERN, REPO_MAP_SOURCE_POLICY, REQUIRED_AGENT_LOOP_PHASES, REQUIRED_SKILL_SCRIPT_RUN_POLICY, REQUIRED_SKILL_SECTION_IDS, ROUTER_INDEX_FILES, ROUTER_INDEX_PROCEDURE_SECTION_PATTERN, SECRET_LIKE_CONTEXT_PATTERNS, SKILL_COMMAND_PERMISSION_CLAIM_PATTERNS, SKILL_INDEX_PATH, SKILL_PACK_ID_PATTERN, SKILL_RESOURCE_MANIFEST, SKILL_RESOURCE_ROOTS, SKILL_RESOURCE_TYPE_BY_ROOT, SKILL_ROUTE_CATEGORY_LABELS, SKILL_ROUTES_METADATA_PATH, SKILL_SECTION_MARKER_PATTERN, SUPPORTED_SKILL_SCHEMA_VERSION, TEST_AUTHORING_BOOLEAN_FIELDS, VERIFICATION_SELECTION_BOOLEAN_FIELDS, VOLATILE_REPO_MAP_PATTERNS } from './constants.js';
+import { ALLOWED_APPROVAL_ACTIONS, ALLOWED_APPROVAL_GATES, ALLOWED_BUDGET_LIMIT_ACTIONS, ALLOWED_CAPABILITY_STATES, ALLOWED_COMMIT_MESSAGE_STYLES, ALLOWED_COMPACTION_CATEGORIES, ALLOWED_COMPACTION_LONG_LIMIT_ACTIONS, ALLOWED_COMPACTION_RAW_LIMIT_ACTIONS, ALLOWED_COMPACTION_STATE_STORES, ALLOWED_COMPACTION_STRATEGIES, ALLOWED_CONTEXT_AUTHORITIES, ALLOWED_CONTEXT_DOCUMENT_AUTHORITIES, ALLOWED_CONTEXT_READ_POLICIES, ALLOWED_HANDOFF_MODES, ALLOWED_HARNESS_FRESH_CONTEXT_MODES, ALLOWED_HARNESS_MODES, ALLOWED_HARNESS_PHASES, ALLOWED_ISOLATION_PREFERENCES, ALLOWED_MAP_MODES, ALLOWED_MAP_PRIVACY_LEVELS, ALLOWED_PROJECT_PROFILES, ALLOWED_REPO_MAP_DEGRADED_VALUES, ALLOWED_REPO_MAP_GIT_LS_FILES_STATUSES, ALLOWED_PROMPT_CACHE_STABLE_PREFIX_POLICIES, ALLOWED_PROMPT_CACHE_STRATEGIES, ALLOWED_PROMPT_CACHE_TASK_READ_POLICIES, ALLOWED_REFRESH_CHECKPOINTS, ALLOWED_REFRESH_METHODS, ALLOWED_REFRESH_MODES, ALLOWED_REFRESH_STATE_STORES, ALLOWED_SKILL_RESOURCE_TYPES, ALLOWED_SKILL_ROUTE_CATEGORIES, ALLOWED_SKILL_ROUTE_PROFILES, ALLOWED_SKILL_ROUTE_TYPES, ALLOWED_STALE_TEST_ACTIONS, ALLOWED_TEST_AUTHORING_POLICIES, ALLOWED_TEST_DELETION_REASONS, ALLOWED_TESTING_POLICIES, ALLOWED_TRANSLATION_POLICIES, ALLOWED_VERIFICATION_SELECTION_STRATEGIES, ALLOWED_VERSION_SOURCE_AUTHORITIES, ALLOWED_VERSION_SOURCE_KINDS, CAPABILITY_BOOLEAN_FIELDS, CAPABILITY_STATE_FIELDS, CONTEXT_AUTHORITY_DRIFT_PATTERNS, DESIGN_TOKEN_DEFINITION_PATTERNS, FORBIDDEN_RELEASE_VERSIONING_CONTRACT_FIELDS, FORBIDDEN_TEST_DELETION_REASONS, FORBIDDEN_VERIFICATION_SELECTION_AUTHORITY_FIELDS, LOCAL_ABSOLUTE_PATH_PATTERNS, LOCAL_TASK_STATE_ROOTS, RAW_COMMAND_FENCE_PATTERN, RELEASE_VERSIONING_BOOLEAN_FIELDS, REPO_MAP_DOC_ID, REPO_MAP_GENERATOR, REPO_MAP_LIFECYCLE, REPO_MAP_PRIVACY_MODE, REPO_MAP_RELATIVE_ROOT, REPO_MAP_REMOTE_OR_BRANCH_PATTERNS, REPO_MAP_SOURCE_FINGERPRINT_PATTERN, REPO_MAP_SOURCE_POLICY, REQUIRED_AGENT_LOOP_PHASES, REQUIRED_SKILL_SCRIPT_RUN_POLICY, REQUIRED_SKILL_SECTION_IDS, ROUTER_INDEX_FILES, ROUTER_INDEX_PROCEDURE_SECTION_PATTERN, SECRET_LIKE_CONTEXT_PATTERNS, SKILL_COMMAND_PERMISSION_CLAIM_PATTERNS, SKILL_INDEX_PATH, SKILL_PACK_ID_PATTERN, SKILL_RESOURCE_MANIFEST, SKILL_RESOURCE_ROOTS, SKILL_RESOURCE_TYPE_BY_ROOT, SKILL_ROUTE_CATEGORY_LABELS, SKILL_ROUTES_METADATA_PATH, SKILL_SECTION_MARKER_PATTERN, SUPPORTED_SKILL_SCHEMA_VERSION, TEST_AUTHORING_BOOLEAN_FIELDS, VERIFICATION_SELECTION_BOOLEAN_FIELDS, VOLATILE_REPO_MAP_PATTERNS } from './constants.js';
 import { hasOwn, isPositiveInteger, isSafeRelativePath, pushStrictIssue, pushStrictWarning, validateAllowedStringField, validateBooleanField, validateExactStringArrayField, validateNestedTable, validatePathArrayField, validatePathField, validatePositiveIntegerField, validateRequiredFiles, validateRequiredPathField, validateRequiredStringField, validateStringArrayField, validateStringArrayMembers, validateStringField, validateTable, validateToml, validateWorkspaceRoots } from './primitives.js';
 import { isConfiguredCommandIntent, isDeclaredCommandIntent } from './command-intents.js';
 import { validateStrictTestSelectionConfig } from './test-selection.js';
+import { getDefaultTemplate, getTemplateFiles } from '../templates.js';
 export { describeCheckIssues, getCheckIssueId, } from '../../../core/check-issues.js';
 function validateMustflowConfig(mustflowToml, issues) {
     if (!mustflowToml) {
@@ -454,13 +456,16 @@ function validateSkills(projectRoot, issues) {
     const skillsRoot = path.join(projectRoot, '.mustflow', 'skills');
     const skillFiles = listFilesRecursive(skillsRoot).filter((relativePath) => relativePath.endsWith('/SKILL.md'));
     for (const relativePath of skillFiles) {
-        const absolutePath = path.join(skillsRoot, relativePath);
-        const content = readFileSync(absolutePath, 'utf8');
+        const normalizedPath = `.mustflow/skills/${toPosixPath(relativePath)}`;
+        const content = readStrictMustflowText(projectRoot, normalizedPath, issues);
+        if (content === undefined) {
+            continue;
+        }
         const sectionIds = readSkillSectionIds(content);
         const missingSectionIds = REQUIRED_SKILL_SECTION_IDS.filter((sectionId) => !sectionIds.has(sectionId));
         if (missingSectionIds.length > 0) {
             issues.push({
-                message: `Missing required skill section ids in .mustflow/skills/${toPosixPath(relativePath)}: ${missingSectionIds.join(', ')}`,
+                message: `Missing required skill section ids in ${normalizedPath}: ${missingSectionIds.join(', ')}`,
             });
         }
     }
@@ -490,6 +495,16 @@ function parseSimpleFrontmatter(content) {
     }
     return frontmatter;
 }
+function readStrictMustflowText(projectRoot, relativePath, issues, options = {}) {
+    const result = readMustflowTextFileResult(projectRoot, relativePath, options);
+    if (result.ok) {
+        return result.content;
+    }
+    if (result.exists && result.error) {
+        pushStrictIssue(issues, `${toPosixPath(relativePath)} could not be read safely: ${result.error}`);
+    }
+    return undefined;
+}
 function readFrontmatterLines(content) {
     if (!content.startsWith('---')) {
         return [];
@@ -540,7 +555,10 @@ function validateContextDocuments(projectRoot, issues) {
     const contextFiles = listFilesRecursive(contextRoot).filter((relativePath) => relativePath.endsWith('.md'));
     for (const relativePath of contextFiles) {
         const normalizedPath = `.mustflow/context/${toPosixPath(relativePath)}`;
-        const content = readFileSync(path.join(contextRoot, relativePath), 'utf8');
+        const content = readStrictMustflowText(projectRoot, normalizedPath, issues);
+        if (content === undefined) {
+            continue;
+        }
         const frontmatter = parseSimpleFrontmatter(content);
         if (frontmatter.kind !== 'mustflow-context') {
             issues.push({ message: `${normalizedPath} frontmatter kind must be "mustflow-context"` });
@@ -630,7 +648,10 @@ function validateStrictRouterIndexes(projectRoot, issues) {
         if (!existsSync(filePath)) {
             continue;
         }
-        const content = readFileSync(filePath, 'utf8');
+        const content = readStrictMustflowText(projectRoot, relativePath, issues);
+        if (content === undefined) {
+            continue;
+        }
         if (ROUTER_INDEX_PROCEDURE_SECTION_PATTERN.test(content)) {
             pushStrictIssue(issues, `${relativePath} must stay a routing index and must not embed skill procedure sections`);
         }
@@ -724,7 +745,7 @@ function readSkillRouteMetadata(projectRoot, issues) {
     }
     let parsed;
     try {
-        parsed = readTomlFile(metadataPath);
+        parsed = readMustflowTomlFile(projectRoot, SKILL_ROUTES_METADATA_PATH);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -787,7 +808,10 @@ function validateSkillIndexRoutes(projectRoot, commandsToml, skillFiles, issues)
     if (!existsSync(skillIndexPath)) {
         return;
     }
-    const skillIndexContent = readFileSync(skillIndexPath, 'utf8');
+    const skillIndexContent = readStrictMustflowText(projectRoot, SKILL_INDEX_PATH, issues);
+    if (skillIndexContent === undefined) {
+        return;
+    }
     validateSkillIndexRouteShape(skillIndexContent, issues);
     const skillRoutes = parseSkillIndexRoutes(skillIndexContent);
     const routedSkillPaths = new Set();
@@ -824,7 +848,11 @@ function validateSkillIndexRoutes(projectRoot, commandsToml, skillFiles, issues)
             pushStrictIssue(issues, `${SKILL_INDEX_PATH} route ${route.skillPath} points to a missing skill document`);
             continue;
         }
-        const skillCommandIntents = new Set(readFrontmatterList(readFileSync(absoluteSkillPath, 'utf8'), 'command_intents'));
+        const skillContent = readStrictMustflowText(projectRoot, route.skillPath, issues);
+        if (skillContent === undefined) {
+            continue;
+        }
+        const skillCommandIntents = new Set(readFrontmatterList(skillContent, 'command_intents'));
         for (const intentName of route.commandIntents) {
             if (!isDeclaredCommandIntent(commandsToml, intentName)) {
                 pushStrictIssue(issues, `${SKILL_INDEX_PATH} route ${route.skillPath} references unknown command intent "${intentName}"`);
@@ -843,6 +871,223 @@ function validateSkillIndexRoutes(projectRoot, commandsToml, skillFiles, issues)
         validateSkillRouteMetadataAlignment(routeMetadata, routedSkillNames, expectedSkillNames, issues);
     }
 }
+function templateFileContent(file) {
+    return file.content ?? readFileSync(file.sourcePath, 'utf8');
+}
+function skillRouteCategoryByLabel(label) {
+    for (const [category, categoryLabel] of Object.entries(SKILL_ROUTE_CATEGORY_LABELS)) {
+        if (categoryLabel === label) {
+            return category;
+        }
+    }
+    return undefined;
+}
+function splitSkillIndexTableRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) {
+        return undefined;
+    }
+    return trimmed.slice(1, -1).split('|').map((cell) => cell.trim());
+}
+function collectSkillIndexCategoryHeadings(content) {
+    const categories = new Set();
+    let currentSection;
+    for (const line of content.split(/\r?\n/u)) {
+        const heading = /^(#{2,3})\s+(.+?)\s*$/u.exec(line.trim());
+        if (!heading) {
+            continue;
+        }
+        const [, level, title] = heading;
+        if (level === '##') {
+            currentSection = title;
+            continue;
+        }
+        if (currentSection === 'Specific Routes' && level === '###') {
+            const category = skillRouteCategoryByLabel(title);
+            if (category) {
+                categories.add(category);
+            }
+        }
+    }
+    return categories;
+}
+function collectSkillIndexCategoryGateRows(content) {
+    const categories = new Set();
+    let currentSection;
+    for (const line of content.split(/\r?\n/u)) {
+        const heading = /^(#{2,3})\s+(.+?)\s*$/u.exec(line.trim());
+        if (heading) {
+            const [, level, title] = heading;
+            if (level === '##') {
+                currentSection = title;
+            }
+            continue;
+        }
+        if (currentSection !== 'Route Category Gate') {
+            continue;
+        }
+        const cells = splitSkillIndexTableRow(line);
+        if (!cells || cells.length === 0 || /^:?-{3,}:?$/u.test(cells[0] ?? '') || cells[0] === 'Category') {
+            continue;
+        }
+        const category = skillRouteCategoryByLabel(cells[0] ?? '');
+        if (category) {
+            categories.add(category);
+        }
+    }
+    return categories;
+}
+function readSkillRouteMetadataFromTomlContent(content, sourceLabel, issues) {
+    let parsed;
+    try {
+        parsed = parseTomlText(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        pushStrictIssue(issues, `Invalid TOML in ${sourceLabel}: ${message}`);
+        return new Map();
+    }
+    if (!isRecord(parsed)) {
+        pushStrictIssue(issues, `${sourceLabel} must contain a TOML table`);
+        return new Map();
+    }
+    if (parsed.schema_version !== '1') {
+        pushStrictIssue(issues, `${sourceLabel} schema_version must be "1"`);
+    }
+    if (!isRecord(parsed.routes)) {
+        pushStrictIssue(issues, `${sourceLabel} must define a [routes] table`);
+        return new Map();
+    }
+    const metadata = new Map();
+    for (const [skillName, route] of Object.entries(parsed.routes)) {
+        if (!/^[a-z][a-z0-9-]*$/u.test(skillName)) {
+            pushStrictIssue(issues, `${sourceLabel} route key "${skillName}" must be a skill folder name`);
+            continue;
+        }
+        if (!isRecord(route)) {
+            pushStrictIssue(issues, `${sourceLabel} routes.${skillName} must be a TOML table`);
+            continue;
+        }
+        metadata.set(skillName, validateSkillRouteMetadataTable(skillName, route, issues));
+    }
+    return metadata;
+}
+function validateTemplateProfileSkillRoutes(profile, files, issues) {
+    const contentByPath = new Map(files.map((file) => [file.relativePath, templateFileContent(file)]));
+    const indexContent = contentByPath.get(SKILL_INDEX_PATH);
+    const routesContent = contentByPath.get(SKILL_ROUTES_METADATA_PATH);
+    const commandsContent = contentByPath.get('.mustflow/config/commands.toml');
+    if (!indexContent) {
+        pushStrictIssue(issues, `template profile "${profile}" is missing generated ${SKILL_INDEX_PATH}`);
+        return;
+    }
+    if (!routesContent) {
+        pushStrictIssue(issues, `template profile "${profile}" is missing generated ${SKILL_ROUTES_METADATA_PATH}`);
+        return;
+    }
+    let commandsToml;
+    if (commandsContent) {
+        try {
+            const parsedCommands = parseTomlText(commandsContent);
+            if (isRecord(parsedCommands)) {
+                commandsToml = parsedCommands;
+            }
+        }
+        catch {
+            commandsToml = undefined;
+        }
+    }
+    const routeMetadata = readSkillRouteMetadataFromTomlContent(routesContent, `template profile "${profile}" ${SKILL_ROUTES_METADATA_PATH}`, issues);
+    const skillRoutes = parseSkillIndexRoutes(indexContent);
+    const categoryHeadings = collectSkillIndexCategoryHeadings(indexContent);
+    const categoryGateRows = collectSkillIndexCategoryGateRows(indexContent);
+    const routesByCategory = new Map();
+    const selectedSkillContents = new Map();
+    const routedSkillNames = new Set();
+    for (const [relativePath, content] of contentByPath.entries()) {
+        const skillName = skillRouteName(relativePath);
+        if (skillName) {
+            selectedSkillContents.set(skillName, content);
+        }
+    }
+    for (const route of skillRoutes) {
+        const routeSkillName = skillRouteName(route.skillPath);
+        if (!routeSkillName) {
+            pushStrictIssue(issues, `template profile "${profile}" ${SKILL_INDEX_PATH} route "${route.skillPath}" must point to .mustflow/skills/<name>/SKILL.md`);
+            continue;
+        }
+        routedSkillNames.add(routeSkillName);
+        const metadata = routeMetadata.get(routeSkillName);
+        if (!selectedSkillContents.has(routeSkillName)) {
+            pushStrictIssue(issues, `template profile "${profile}" ${SKILL_INDEX_PATH} route "${routeSkillName}" points to a skill not installed by that profile`);
+        }
+        if (!metadata) {
+            pushStrictIssue(issues, `template profile "${profile}" ${SKILL_ROUTES_METADATA_PATH} is missing metadata for route "${routeSkillName}"`);
+        }
+        if (metadata?.category && route.category !== metadata.category) {
+            pushStrictIssue(issues, `template profile "${profile}" ${SKILL_INDEX_PATH} route "${routeSkillName}" must appear under the ${SKILL_ROUTE_CATEGORY_LABELS[metadata.category]} category section from ${SKILL_ROUTES_METADATA_PATH}`);
+        }
+        if (metadata?.category) {
+            routesByCategory.set(metadata.category, [...(routesByCategory.get(metadata.category) ?? []), routeSkillName]);
+        }
+        const skillContent = selectedSkillContents.get(routeSkillName);
+        const skillCommandIntents = new Set(skillContent ? readFrontmatterList(skillContent, 'command_intents') : []);
+        for (const intentName of route.commandIntents) {
+            if (commandsToml && !isDeclaredCommandIntent(commandsToml, intentName)) {
+                pushStrictIssue(issues, `template profile "${profile}" ${SKILL_INDEX_PATH} route "${routeSkillName}" references unknown command intent "${intentName}"`);
+            }
+            if (!skillCommandIntents.has(intentName)) {
+                pushStrictIssue(issues, `template profile "${profile}" ${SKILL_INDEX_PATH} route "${routeSkillName}" references command intent "${intentName}" not declared by the skill frontmatter`);
+            }
+        }
+    }
+    for (const [skillName, metadata] of routeMetadata.entries()) {
+        if (!routedSkillNames.has(skillName)) {
+            pushStrictIssue(issues, `template profile "${profile}" ${SKILL_ROUTES_METADATA_PATH} route "${skillName}" is not listed in ${SKILL_INDEX_PATH}`);
+        }
+        if (!selectedSkillContents.has(skillName)) {
+            pushStrictIssue(issues, `template profile "${profile}" ${SKILL_ROUTES_METADATA_PATH} route "${skillName}" points to a skill not installed by that profile`);
+        }
+    }
+    for (const skillName of selectedSkillContents.keys()) {
+        if (!routedSkillNames.has(skillName)) {
+            pushStrictIssue(issues, `template profile "${profile}" skill "${skillName}" is installed but not listed in ${SKILL_INDEX_PATH}`);
+        }
+    }
+    for (const category of categoryHeadings) {
+        if (!routesByCategory.has(category)) {
+            pushStrictIssue(issues, `template profile "${profile}" skill index category "${SKILL_ROUTE_CATEGORY_LABELS[category]}" has no route rows`);
+        }
+    }
+    for (const category of categoryGateRows) {
+        if (!routesByCategory.has(category)) {
+            pushStrictIssue(issues, `template profile "${profile}" route category gate references "${SKILL_ROUTE_CATEGORY_LABELS[category]}" without route rows`);
+        }
+    }
+    for (const [category, skillNames] of routesByCategory.entries()) {
+        const hasSelectableMainRoute = skillNames.some((skillName) => {
+            const routeType = routeMetadata.get(skillName)?.routeType;
+            return routeType === 'primary' || routeType === 'authoring';
+        });
+        if (!hasSelectableMainRoute) {
+            pushStrictIssue(issues, `template profile "${profile}" skill category "${SKILL_ROUTE_CATEGORY_LABELS[category]}" must include at least one primary or authoring route`);
+        }
+    }
+}
+function validateStrictTemplateSkillProfiles(issues) {
+    let template;
+    try {
+        template = getDefaultTemplate();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        pushStrictIssue(issues, `default template skill profiles could not be loaded: ${message}`);
+        return;
+    }
+    for (const profile of template.manifest.profiles) {
+        validateTemplateProfileSkillRoutes(profile, getTemplateFiles(template, template.manifest.defaultLocale, profile), issues);
+    }
+}
 function listManagedMarkdownDocuments(projectRoot) {
     const documents = [];
     for (const relativePath of ['AGENTS.md', '.mustflow/skills/INDEX.md']) {
@@ -872,7 +1117,10 @@ function validateStrictManagedMarkdownIdentities(projectRoot, issues) {
         if (!expectation) {
             continue;
         }
-        const content = readFileSync(path.join(projectRoot, relativePath), 'utf8');
+        const content = readStrictMustflowText(projectRoot, relativePath, issues);
+        if (content === undefined) {
+            continue;
+        }
         const frontmatter = parseSimpleFrontmatter(content);
         const documentLabel = formatManagedMarkdownLabel(relativePath, expectation);
         if (frontmatter.mustflow_doc !== expectation.docId) {
@@ -964,7 +1212,7 @@ function validateStrictCandidateContractModelConfigs(projectRoot, issues) {
         }
         let parsed;
         try {
-            parsed = readTomlFile(configPath);
+            parsed = readMustflowTomlFile(projectRoot, model.filePath);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -1015,9 +1263,9 @@ function listSkillDirectories(skillsRoot) {
     }
     return [...skillNames].sort();
 }
-function readSkillResourceManifest(manifestPath, manifestLabel, issues) {
+function readSkillResourceManifest(projectRoot, manifestLabel, issues) {
     try {
-        const parsed = readTomlFile(manifestPath);
+        const parsed = readMustflowTomlFile(projectRoot, manifestLabel);
         if (!isRecord(parsed)) {
             pushStrictIssue(issues, `${manifestLabel} must contain a TOML table`);
             return undefined;
@@ -1099,13 +1347,13 @@ function validateSkillResourceTable(skillDir, manifestLabel, resourcePath, resou
     }
     return normalizedPath;
 }
-function validateSkillResourceManifest(skillDir, manifestLabel, commandsToml, issues) {
+function validateSkillResourceManifest(projectRoot, skillDir, manifestLabel, commandsToml, issues) {
     const declaredResources = new Set();
     const manifestPath = path.join(skillDir, SKILL_RESOURCE_MANIFEST);
     if (!existsSync(manifestPath)) {
         return declaredResources;
     }
-    const manifest = readSkillResourceManifest(manifestPath, manifestLabel, issues);
+    const manifest = readSkillResourceManifest(projectRoot, manifestLabel, issues);
     if (!manifest) {
         return declaredResources;
     }
@@ -1173,13 +1421,15 @@ function validateStrictSkills(projectRoot, commandsToml, issues) {
             pushStrictIssue(issues, `.mustflow/skills/${skillName} is a skill folder without SKILL.md`);
         }
         const manifestLabel = `.mustflow/skills/${skillName}/${SKILL_RESOURCE_MANIFEST}`;
-        const declaredResources = validateSkillResourceManifest(skillDir, manifestLabel, commandsToml, issues);
+        const declaredResources = validateSkillResourceManifest(projectRoot, skillDir, manifestLabel, commandsToml, issues);
         validateDeclaredSkillScripts(skillDir, skillName, declaredResources, issues);
     }
     for (const relativePath of skillFiles) {
-        const absolutePath = path.join(skillsRoot, relativePath);
-        const content = readFileSync(absolutePath, 'utf8');
         const normalizedRelativePath = toPosixPath(relativePath);
+        const content = readStrictMustflowText(projectRoot, `.mustflow/skills/${normalizedRelativePath}`, issues);
+        if (content === undefined) {
+            continue;
+        }
         const skillName = normalizedRelativePath.split('/')[0] ?? '';
         const skillLabel = `.mustflow/skills/${normalizedRelativePath}`;
         const frontmatter = parseSimpleFrontmatter(content);
@@ -1206,7 +1456,10 @@ function validateStrictRepoMap(projectRoot, issues) {
     if (!existsSync(repoMapPath)) {
         return;
     }
-    const content = readFileSync(repoMapPath, 'utf8');
+    const content = readStrictMustflowText(projectRoot, 'REPO_MAP.md', issues);
+    if (content === undefined) {
+        return;
+    }
     const frontmatter = parseSimpleFrontmatter(content);
     if (frontmatter.mustflow_doc !== REPO_MAP_DOC_ID) {
         pushStrictIssue(issues, `REPO_MAP.md frontmatter mustflow_doc must be "${REPO_MAP_DOC_ID}"`);
@@ -1229,6 +1482,12 @@ function validateStrictRepoMap(projectRoot, issues) {
     if (!/^[1-9]\d*$/u.test(frontmatter.anchor_count ?? '')) {
         pushStrictIssue(issues, 'REPO_MAP.md frontmatter anchor_count must be a positive integer');
     }
+    if (!ALLOWED_REPO_MAP_DEGRADED_VALUES.has(frontmatter.degraded ?? '')) {
+        pushStrictIssue(issues, 'REPO_MAP.md frontmatter degraded must be true or false');
+    }
+    if (!ALLOWED_REPO_MAP_GIT_LS_FILES_STATUSES.has(frontmatter.git_ls_files_status ?? '')) {
+        pushStrictIssue(issues, 'REPO_MAP.md frontmatter git_ls_files_status must be ok, timeout, max_buffer, or error');
+    }
     if (!REPO_MAP_SOURCE_FINGERPRINT_PATTERN.test(frontmatter.source_fingerprint ?? '')) {
         pushStrictIssue(issues, 'REPO_MAP.md frontmatter source_fingerprint must be sha256:<64 lowercase hex characters>');
     }
@@ -1253,7 +1512,10 @@ function validateStrictContextDocuments(projectRoot, limits, issues) {
     for (const relativePath of contextFiles) {
         const normalizedPath = `.mustflow/context/${toPosixPath(relativePath)}`;
         const absolutePath = path.join(contextRoot, relativePath);
-        const content = readFileSync(absolutePath, 'utf8');
+        const content = readStrictMustflowText(projectRoot, normalizedPath, issues);
+        if (content === undefined) {
+            continue;
+        }
         if (exceedsKiBLimit(absolutePath, limits.contextMaxFileKb)) {
             pushStrictIssue(issues, formatStorageLimitMessage(normalizedPath, '[retention.context].max_file_kb', absolutePath, limits.contextMaxFileKb));
         }
@@ -1293,7 +1555,13 @@ function validateStrictRunReceipt(projectRoot, issues) {
         return;
     }
     try {
-        const parsed = JSON.parse(readFileSync(latestRunPath, 'utf8'));
+        const content = readStrictMustflowText(projectRoot, '.mustflow/state/runs/latest.json', issues, {
+            maxBytes: MUSTFLOW_JSON_MAX_BYTES,
+        });
+        if (content === undefined) {
+            return;
+        }
+        const parsed = JSON.parse(content);
         if (!isRecord(parsed)) {
             pushStrictIssue(issues, '.mustflow/state/runs/latest.json must contain a JSON object');
         }
@@ -1348,6 +1616,7 @@ function validateStrict(projectRoot, parsed, issues) {
     validateStrictManagedMarkdownIdentities(projectRoot, issues);
     validateStrictRouterIndexes(projectRoot, issues);
     validateStrictSkills(projectRoot, parsed.commandsToml, issues);
+    validateStrictTemplateSkillProfiles(issues);
     validateStrictRepoMap(projectRoot, issues);
     validateStrictContextDocuments(projectRoot, retentionLimits, issues);
     validateStrictSourceAnchors(projectRoot, issues);

package/dist/cli/lib/validation/primitives.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { isRecord } from '../command-contract.js';
-import { readTomlFile } from '../toml.js';
+import { readMustflowTomlFile } from '../toml.js';
 import { REQUIRED_FILES, } from './constants.js';
 import { VERSIONING_CONFIG_PATH } from '../../../core/version-sources.js';
 export function hasOwn(table, key) {
@@ -41,7 +41,7 @@ export function validateToml(projectRoot, issues) {
             continue;
         }
         try {
-            const parsed = readTomlFile(filePath);
+            const parsed = readMustflowTomlFile(projectRoot, relativePath);
             if (!isRecord(parsed)) {
                 issues.push({ message: `${relativePath} must contain a TOML table` });
                 continue;

package/dist/cli/lib/validation/test-selection.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { isRecord } from '../command-contract.js';
-import { readTomlFile } from '../toml.js';
+import { readMustflowTomlFile } from '../toml.js';
 import { ALLOWED_TEST_SELECTION_RISKS, FORBIDDEN_TEST_SELECTION_COMMAND_AUTHORITY_FIELDS, TEST_SELECTION_CONFIG_PATH, } from './constants.js';
 import { isConfiguredCommandIntent, isDeclaredCommandIntent } from './command-intents.js';
 import { hasOwn, pushStrictIssue, validateAllowedStringField, validateNestedTable, validatePathArrayField, validateRequiredStringField, validateStringArrayField, } from './primitives.js';
@@ -69,7 +69,7 @@ export function validateStrictTestSelectionConfig(projectRoot, commandsToml, iss
     }
     let parsed;
     try {
-        parsed = readTomlFile(configPath);
+        parsed = readMustflowTomlFile(projectRoot, TEST_SELECTION_CONFIG_PATH);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/core/bounded-output.js

@@ -22,6 +22,8 @@ export function decodeUtf8Tail(buffer, maxTailBytes) {
 export class BoundedOutputBuffer {
     #maxTailBytes;
     #chunks = [];
+    #headIndex = 0;
+    #headOffset = 0;
     #tailBytes = 0;
     #bytes = 0;
     constructor(maxTailBytes) {
@@ -35,26 +37,49 @@ export class BoundedOutputBuffer {
         }
         this.#chunks.push(buffer);
         this.#tailBytes += buffer.byteLength;
-        while (this.#tailBytes > this.#maxTailBytes && this.#chunks.length > 0) {
-            const first = this.#chunks[0];
+        while (this.#tailBytes > this.#maxTailBytes && this.#headIndex < this.#chunks.length) {
+            const first = this.#chunks[this.#headIndex];
             const overflow = this.#tailBytes - this.#maxTailBytes;
             if (!first) {
                 break;
             }
-            if (first.byteLength <= overflow) {
-                this.#chunks.shift();
-                this.#tailBytes -= first.byteLength;
+            const firstAvailableBytes = first.byteLength - this.#headOffset;
+            if (firstAvailableBytes <= overflow) {
+                this.#headIndex += 1;
+                this.#headOffset = 0;
+                this.#tailBytes -= firstAvailableBytes;
                 continue;
             }
-            this.#chunks[0] = first.subarray(overflow);
+            this.#headOffset += overflow;
             this.#tailBytes -= overflow;
         }
+        this.#compactRetainedChunks();
     }
     toSnapshot() {
-        const tail = decodeUtf8Tail(Buffer.concat(this.#chunks, this.#tailBytes), this.#maxTailBytes);
+        const tail = decodeUtf8Tail(Buffer.concat(this.#retainedChunks(), this.#tailBytes), this.#maxTailBytes);
         return {
             bytes: this.#bytes,
             tail: tail.text,
         };
     }
+    #retainedChunks() {
+        if (this.#tailBytes === 0 || this.#headIndex >= this.#chunks.length) {
+            return [];
+        }
+        const chunks = this.#chunks.slice(this.#headIndex);
+        if (this.#headOffset > 0 && chunks[0]) {
+            chunks[0] = chunks[0].subarray(this.#headOffset);
+        }
+        return chunks;
+    }
+    #compactRetainedChunks() {
+        if (this.#headIndex === 0) {
+            return;
+        }
+        if (this.#headIndex < 64 && this.#headIndex * 2 < this.#chunks.length) {
+            return;
+        }
+        this.#chunks = this.#chunks.slice(this.#headIndex);
+        this.#headIndex = 0;
+    }
 }

package/dist/core/check-issues.js

@@ -7,6 +7,7 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.command_contract.max_output_bytes_exceeds_limit', /^\[commands\.(?:defaults|intents\.[^\]]+)\]\.max_output_bytes must be less than or equal to \d+ per output stream$/u],
     ['mustflow.command_contract.oneshot_stdin_not_closed', /^Oneshot intent [^\s]+ must set stdin = "closed"$/u],
     ['mustflow.command_contract.long_running_agent_allowed', /^Long-running intent [^\s]+ must not use run_policy = "agent_allowed"$/u],
+    ['mustflow.command_contract.agent_shell_requires_allow', /^Agent-runnable shell intent [^\s]+ must set allow_shell = true$/u],
     ['mustflow.command_contract.executable_source_missing', /^Configured intent [^\s]+ must define argv or mode = "shell" with cmd$/u],
     ['mustflow.command_contract.shell_background_pattern', /^Shell intent [^\s]+ contains a blocked long-running or background pattern$/u],
     ['mustflow.command_contract.long_running_command_pattern', /^Intent [^\s]+ contains a blocked long-running or background command pattern$/u],
@@ -17,7 +18,7 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.command_contract.effects_invalid', /^(?:Strict: )?(?:\[commands\.(?:resources|intents\.[^\]]+\.effects)[^\]]*\]|Command effect for intent [^\s]+ must define path, paths, or lock)/u],
     ['mustflow.command_contract.effect_path_escape', /^Strict: Command effect path must stay inside the current root:/u],
     ['mustflow.command_contract.shared_writes_without_effects', /^Strict warning: configured agent-runnable intents .+ share path:.+ through writes without explicit effects or resource locks$/u],
-    ['mustflow.command_contract.broad_env_inheritance', /^Strict warning: configured agent-runnable intent [^\s]+ (?:implicitly inherits the host environment|uses env_policy = "inherit")/u],
+    ['mustflow.command_contract.broad_env_inheritance', /^Strict(?: warning)?: configured agent-runnable intent [^\s]+ (?:implicitly inherits the host environment|uses env_policy = "inherit")/u],
     ['mustflow.command_contract.project_local_bin_bare_executable', /^Strict warning: configured agent-runnable intent [^\s]+ uses bare executable "[^"]+" that matches project-local node_modules\/\.bin/u],
     ['mustflow.prompt_cache.required', /^Strict: \[prompt_cache\] table is required$/u],
     ['mustflow.prompt_cache.volatile_in_stable', /^Strict: \[prompt_cache\.layers\.stable\]\.read must not include volatile path /u],
@@ -48,6 +49,11 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.skill.route_metadata_category_mismatch', /^Strict: \.mustflow\/skills\/INDEX\.md route "[^"]+" must appear under the .+ category section from \.mustflow\/skills\/routes\.toml$/u],
     ['mustflow.skill.route_metadata_unknown_reference', /^Strict: \.mustflow\/skills\/routes\.toml route "[^"]+" references unknown mutually exclusive route "[^"]+"$/u],
     ['mustflow.skill.route_metadata_asymmetric_exclusion', /^Strict warning: \.mustflow\/skills\/routes\.toml route "[^"]+" lists "[^"]+" as mutually exclusive but the reverse route does not$/u],
+    ['mustflow.skill.template_profile_empty_category', /^Strict: template profile "[^"]+" (?:skill index category ".+" has no route rows|route category gate references ".+" without route rows)$/u],
+    ['mustflow.skill.template_profile_dead_route', /^Strict: template profile "[^"]+" (?:\.mustflow\/skills\/INDEX\.md route "[^"]+" points to a skill not installed by that profile|\.mustflow\/skills\/routes\.toml route "[^"]+" points to a skill not installed by that profile|skill "[^"]+" is installed but not listed in \.mustflow\/skills\/INDEX\.md)$/u],
+    ['mustflow.skill.template_profile_missing_main_route', /^Strict: template profile "[^"]+" skill category ".+" must include at least one primary or authoring route$/u],
+    ['mustflow.skill.template_profile_command_intent_drift', /^Strict: template profile "[^"]+" \.mustflow\/skills\/INDEX\.md route "[^"]+" references (?:unknown command intent "[^"]+"|command intent "[^"]+" not declared by the skill frontmatter)$/u],
+    ['mustflow.skill.template_profile_metadata_mismatch', /^Strict: template profile "[^"]+" (?:\.mustflow\/skills\/routes\.toml is missing metadata for route "[^"]+"|\.mustflow\/skills\/routes\.toml route "[^"]+" is not listed in \.mustflow\/skills\/INDEX\.md|\.mustflow\/skills\/INDEX\.md route "[^"]+" must appear under the .+ category section from \.mustflow\/skills\/routes\.toml)$/u],
     ['mustflow.skill.resource_unknown_command_intent', /^Strict: \.mustflow\/skills\/[^/]+\/resources\.toml script [^\s]+ references unknown command intent "[^"]+"$/u],
     ['mustflow.source_anchor.invalid_format', /^Strict: source anchor .+ has invalid format:/u],
     ['mustflow.source_anchor.duplicate_id', /^Strict: source anchor id "[^"]+" is duplicated:/u],