mustflow 2.22.3 → 2.22.5

package/dist/core/command-contract-validation.js

@@ -160,6 +160,7 @@ function validateCommandIntent(intentName, intent, issues) {
     validateAllowedStringField(intent, 'lifecycle', `[commands.intents.${intentName}].lifecycle`, COMMAND_LIFECYCLES, issues);
     validateAllowedStringField(intent, 'run_policy', `[commands.intents.${intentName}].run_policy`, COMMAND_RUN_POLICIES, issues);
     validateAllowedStringField(intent, 'env_policy', `[commands.intents.${intentName}].env_policy`, COMMAND_ENV_POLICIES, issues);
+    validateBooleanField(intent, 'allow_shell', `[commands.intents.${intentName}].allow_shell`, issues);
     validateStringArrayField(intent, 'env_allowlist', `[commands.intents.${intentName}].env_allowlist`, issues);
     validateMaxOutputBytesField(intent, 'max_output_bytes', `[commands.intents.${intentName}].max_output_bytes`, issues);
     validatePositiveIntegerField(intent, 'kill_after_seconds', `[commands.intents.${intentName}].kill_after_seconds`, issues);
@@ -187,6 +188,9 @@ function validateCommandIntent(intentName, intent, issues) {
     if (lifecycle && LONG_RUNNING_LIFECYCLES.has(lifecycle) && runPolicy === 'agent_allowed') {
         issues.push(commandContractIssue(`Long-running intent ${intentName} must not use run_policy = "agent_allowed"`));
     }
+    if (intent.mode === 'shell' && runPolicy === 'agent_allowed' && intent.allow_shell !== true) {
+        issues.push(commandContractIssue(`Agent-runnable shell intent ${intentName} must set allow_shell = true`));
+    }
     if (!commandIntentHasCommandSource(intent)) {
         issues.push(commandContractIssue(`Configured intent ${intentName} must define argv or mode = "shell" with cmd`));
     }
@@ -238,26 +242,46 @@ export function findCommandEnvInheritanceWarnings(commandsToml) {
         if (envPolicy.policy !== 'inherit') {
             continue;
         }
+        const reasons = readCommandEnvInheritanceRiskReasons(intent);
         warnings.push({
             intentName,
             source: envPolicy.source,
+            severity: reasons.length > 0 ? 'error' : 'warning',
             network: intent.network === true,
+            reasons,
         });
     }
     return warnings;
 }
+function readCommandEnvInheritanceRiskReasons(intent) {
+    const reasons = [];
+    if (intent.network === true) {
+        reasons.push('network = true');
+    }
+    if (intent.destructive === true) {
+        reasons.push('destructive = true');
+    }
+    if (intent.mode === 'shell') {
+        reasons.push('mode = "shell"');
+    }
+    if (Array.isArray(intent.writes) && intent.writes.length > 0) {
+        reasons.push('declared writes');
+    }
+    return reasons;
+}
 function formatCommandEnvInheritanceWarning(warning) {
-    const networkScope = warning.network ? ' with network = true' : '';
+    const reasonScope = warning.reasons.length > 0 ? ` (${warning.reasons.join(', ')})` : '';
     const migration = 'set env_policy = "minimal" or "allowlist" unless broad host state is required';
     if (warning.source === 'implicit') {
-        return `configured agent-runnable intent ${warning.intentName} implicitly inherits the host environment${networkScope}; ${migration}`;
+        return `configured agent-runnable intent ${warning.intentName} implicitly inherits the host environment${reasonScope}; ${migration}`;
     }
-    return `configured agent-runnable intent ${warning.intentName} uses env_policy = "inherit"${networkScope}; ${migration}`;
+    return `configured agent-runnable intent ${warning.intentName} uses env_policy = "inherit"${reasonScope}; ${migration}`;
 }
 function validateCommandEnvInheritanceWarnings(commandsToml) {
     const issues = [];
     for (const warning of findCommandEnvInheritanceWarnings(commandsToml)) {
-        issues.push(commandContractWarning(formatCommandEnvInheritanceWarning(warning)));
+        const message = formatCommandEnvInheritanceWarning(warning);
+        issues.push(warning.severity === 'warning' ? commandContractWarning(message) : commandContractIssue(message));
     }
     return issues;
 }

package/dist/core/command-env.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { readString, readStringArray } from './config-loading.js';
 export const COMMAND_ENV_POLICIES = new Set(['inherit', 'minimal', 'allowlist']);
-export const DEFAULT_COMMAND_ENV_POLICY = 'inherit';
+export const DEFAULT_COMMAND_ENV_POLICY = 'minimal';
 const BASE_MINIMAL_ENV_KEYS = [
     'CI',
     'COLORTERM',

package/dist/core/config-loading.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { readTomlFile } from './toml.js';
+import { readUtf8FileInsideWithoutSymlinks } from './safe-filesystem.js';
+import { parseTomlText } from './toml.js';
 export const COMMAND_LIFECYCLES = new Set(['oneshot', 'server', 'watch', 'interactive', 'browser', 'background']);
 export const LONG_RUNNING_LIFECYCLES = new Set(['server', 'watch', 'interactive', 'browser', 'background']);
 export const COMMAND_RUN_POLICIES = new Set(['agent_allowed', 'requires_explicit_user_request', 'manual_only']);
@@ -12,8 +13,13 @@ export function isRecord(value) {
 export function resolveMustflowConfigPath(projectRoot, relativePath) {
     return path.join(projectRoot, ...relativePath.split('/'));
 }
+export function readMustflowOwnedTomlFile(projectRoot, relativePath) {
+    return parseTomlText(readUtf8FileInsideWithoutSymlinks(projectRoot, resolveMustflowConfigPath(projectRoot, relativePath), {
+        maxBytes: 256 * 1024,
+    }));
+}
 export function readMustflowConfig(projectRoot) {
-    const parsed = readTomlFile(resolveMustflowConfigPath(projectRoot, MUSTFLOW_CONFIG_RELATIVE_PATH));
+    const parsed = readMustflowOwnedTomlFile(projectRoot, MUSTFLOW_CONFIG_RELATIVE_PATH);
     if (!isRecord(parsed)) {
         throw new Error(`${MUSTFLOW_CONFIG_RELATIVE_PATH} must contain a TOML table`);
     }
@@ -24,7 +30,7 @@ export function readMustflowConfigIfExists(projectRoot) {
     return existsSync(configPath) ? readMustflowConfig(projectRoot) : undefined;
 }
 export function readCommandContract(projectRoot) {
-    const parsed = readTomlFile(resolveMustflowConfigPath(projectRoot, COMMANDS_CONFIG_RELATIVE_PATH));
+    const parsed = readMustflowOwnedTomlFile(projectRoot, COMMANDS_CONFIG_RELATIVE_PATH);
     if (!isRecord(parsed)) {
         throw new Error(`${COMMANDS_CONFIG_RELATIVE_PATH} must contain a TOML table`);
     }

package/dist/core/contract-lint.js

@@ -6,6 +6,7 @@ import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, comm
 import { MAX_COMMAND_OUTPUT_BYTES } from './command-output-limits.js';
 import { commandEffectsConflict, normalizeCommandEffects } from './command-effects.js';
 import { listChangeClassificationValidationReasons } from './change-classification.js';
+import { readUtf8FileInsideWithoutSymlinks } from './safe-filesystem.js';
 import { parseSkillIndexRoutes } from './skill-route-alignment.js';
 import { SUCCESS_EXIT_CODES_CONTRACT_DESCRIPTION, successExitCodesAreValid as successExitCodeValuesAreValid, } from './success-exit-codes.js';
 const CONTRACT_LINT_SOURCE_FILES = [
@@ -392,7 +393,7 @@ function readSkillPathsByIntent(projectRoot) {
     if (!existsSync(skillIndexPath)) {
         return skillPathsByIntent;
     }
-    const routes = parseSkillIndexRoutes(readFileSync(skillIndexPath, 'utf8'));
+    const routes = parseSkillIndexRoutes(readUtf8FileInsideWithoutSymlinks(projectRoot, skillIndexPath, { maxBytes: 1024 * 1024 }));
     for (const route of routes) {
         for (const intent of route.commandIntents) {
             skillPathsByIntent.set(intent, [...(skillPathsByIntent.get(intent) ?? []), route.skillPath]);

package/dist/core/safe-filesystem.js

@@ -1,4 +1,4 @@
-import { closeSync, constants, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 const NOFOLLOW_FLAG = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
@@ -103,19 +103,26 @@ export function ensureFileTargetInsideWithoutSymlinks(parentPath, childPath, opt
         throw error;
     }
 }
-export function readFileInsideWithoutSymlinks(parentPath, childPath) {
+export function readFileInsideWithoutSymlinks(parentPath, childPath, options = {}) {
     const absoluteChildPath = path.resolve(childPath);
     ensureInsideWithoutSymlinks(parentPath, absoluteChildPath);
     const fileDescriptor = openSync(absoluteChildPath, constants.O_RDONLY | NOFOLLOW_FLAG);
     try {
+        const stats = fstatSync(fileDescriptor);
+        if (!stats.isFile()) {
+            throw new Error(`Path must be a regular file: ${childPath}`);
+        }
+        if (options.maxBytes !== undefined && stats.size > options.maxBytes) {
+            throw new Error(`File exceeds maximum size ${options.maxBytes} bytes: ${childPath}`);
+        }
         return readFileSync(fileDescriptor);
     }
     finally {
         closeSync(fileDescriptor);
     }
 }
-export function readUtf8FileInsideWithoutSymlinks(parentPath, childPath) {
-    return readFileInsideWithoutSymlinks(parentPath, childPath).toString('utf8');
+export function readUtf8FileInsideWithoutSymlinks(parentPath, childPath, options = {}) {
+    return readFileInsideWithoutSymlinks(parentPath, childPath, options).toString('utf8');
 }
 export function writeFileInsideWithoutSymlinks(parentPath, childPath, content) {
     const absoluteChildPath = path.resolve(childPath);

package/dist/core/skill-route-alignment.js

@@ -172,6 +172,7 @@ export function isSkillRouteAlignmentIssue(issue) {
     return (issue.includes('.mustflow/skills/INDEX.md route') ||
         issue.includes('.mustflow/skills/INDEX.md .mustflow/skills/') ||
         issue.includes('.mustflow/skills/INDEX.md has duplicate route') ||
+        issue.includes('template profile "') ||
         issue.endsWith(' is not listed in .mustflow/skills/INDEX.md'));
 }
 export function summarizeSkillRouteAlignment(issues) {

package/dist/core/skill-route-explanation.js

@@ -1,6 +1,8 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { readUtf8FileInsideWithoutSymlinks } from './safe-filesystem.js';
 import { parseSkillIndexRoutes } from './skill-route-alignment.js';
+const MUSTFLOW_TEXT_MAX_BYTES = 1024 * 1024;
 const SKILL_INDEX_PATH = '.mustflow/skills/INDEX.md';
 const SKILL_ROUTE_SOURCE_FILES = [
     SKILL_INDEX_PATH,
@@ -84,11 +86,15 @@ function routeToSummary(route, skillContent) {
 }
 export function explainSkillRoute(projectRoot, target) {
     const indexPath = path.join(projectRoot, ...SKILL_INDEX_PATH.split('/'));
-    const indexContent = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : '';
+    const indexContent = existsSync(indexPath)
+        ? readUtf8FileInsideWithoutSymlinks(projectRoot, indexPath, { maxBytes: MUSTFLOW_TEXT_MAX_BYTES })
+        : '';
     const routes = parseSkillIndexRoutes(indexContent);
     for (const route of routes) {
         const absoluteSkillPath = path.join(projectRoot, ...route.skillPath.split('/'));
-        const skillContent = existsSync(absoluteSkillPath) ? readFileSync(absoluteSkillPath, 'utf8') : null;
+        const skillContent = existsSync(absoluteSkillPath)
+            ? readUtf8FileInsideWithoutSymlinks(projectRoot, absoluteSkillPath, { maxBytes: MUSTFLOW_TEXT_MAX_BYTES })
+            : null;
         if (!targetMatchesRoute(target, route, skillContent)) {
             continue;
         }

package/dist/core/test-selection.js

@@ -1,6 +1,5 @@
 import { existsSync } from 'node:fs';
-import { isRecord, readStringArray, resolveMustflowConfigPath, } from './config-loading.js';
-import { readTomlFile } from './toml.js';
+import { isRecord, readMustflowOwnedTomlFile, readStringArray, resolveMustflowConfigPath, } from './config-loading.js';
 import { classifyVerificationCandidate, } from './verification-plan.js';
 export const TEST_SELECTION_CONFIG_RELATIVE_PATH = '.mustflow/config/test-selection.toml';
 const STALE_OR_MISSING_RULES_NOTE = 'Project-declared test selection rules did not cover the current changed files; review .mustflow/config/test-selection.toml for stale or missing rules.';
@@ -73,7 +72,7 @@ function readRules(projectRoot) {
         };
     }
     try {
-        const parsed = readTomlFile(configPath);
+        const parsed = readMustflowOwnedTomlFile(projectRoot, TEST_SELECTION_CONFIG_RELATIVE_PATH);
         if (!isRecord(parsed) || parsed.schema_version !== '1' || !Array.isArray(parsed.rules)) {
             return {
                 status: 'invalid',

package/dist/core/verification-scheduler.js

@@ -1,6 +1,7 @@
-import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { commandEffectsConflict, normalizeCommandEffects, } from './command-effects.js';
+import { readUtf8FileInsideWithoutSymlinks } from './safe-filesystem.js';
+const MUSTFLOW_JSON_MAX_BYTES = 1024 * 1024;
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
@@ -18,9 +19,9 @@ function toScheduleEffect(effect) {
 function isObject(value) {
     return !!value && typeof value === 'object';
 }
-function readJsonFile(filePath) {
+function readJsonFile(projectRoot, filePath) {
     try {
-        return JSON.parse(readFileSync(filePath, 'utf8'));
+        return JSON.parse(readUtf8FileInsideWithoutSymlinks(projectRoot, filePath, { maxBytes: MUSTFLOW_JSON_MAX_BYTES }));
     }
     catch {
         return null;
@@ -56,7 +57,7 @@ function readVerifyManifestUndeclaredWriteIntents(projectRoot, latest) {
     if (!manifestPath) {
         return new Set();
     }
-    const manifest = readJsonFile(manifestPath);
+    const manifest = readJsonFile(projectRoot, manifestPath);
     if (!isObject(manifest) || manifest.command !== 'verify' || !Array.isArray(manifest.receipts)) {
         return new Set();
     }
@@ -69,7 +70,7 @@ function readVerifyManifestUndeclaredWriteIntents(projectRoot, latest) {
         if (!receiptPath) {
             continue;
         }
-        const intent = getUndeclaredWriteIntent(readJsonFile(receiptPath));
+        const intent = getUndeclaredWriteIntent(readJsonFile(projectRoot, receiptPath));
         if (intent) {
             intents.add(intent);
         }
@@ -78,7 +79,7 @@ function readVerifyManifestUndeclaredWriteIntents(projectRoot, latest) {
 }
 function readLatestUndeclaredWriteIntents(projectRoot) {
     const latestPath = path.join(projectRoot, '.mustflow', 'state', 'runs', 'latest.json');
-    const parsed = readJsonFile(latestPath);
+    const parsed = readJsonFile(projectRoot, latestPath);
     const directIntent = getUndeclaredWriteIntent(parsed);
     if (directIntent) {
         return new Set([directIntent]);

package/dist/core/version-sources.js

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { isRecord } from './config-loading.js';
-import { readTomlFile } from './toml.js';
+import { isRecord, readMustflowOwnedTomlFile } from './config-loading.js';
 const RELEASE_VERSIONING_ACTIVE_FIELDS = [
     'impact_check',
     'suggest_bump',
@@ -155,7 +154,7 @@ function hasGoModuleVersionSource(projectRoot) {
 }
 export function readDeclaredVersionSources(projectRoot) {
     try {
-        const versioningConfig = readTomlFile(path.join(projectRoot, VERSIONING_CONFIG_PATH));
+        const versioningConfig = readMustflowOwnedTomlFile(projectRoot, VERSIONING_CONFIG_PATH);
         if (!isRecord(versioningConfig) || !Array.isArray(versioningConfig.sources)) {
             return [];
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.22.3",
+  "version": "2.22.5",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",
@@ -36,7 +36,9 @@
     "test:coverage": "bun run build && node scripts/run-cli-tests.mjs coverage",
     "test:audit": "node scripts/audit-tests.mjs --json",
     "test:release": "bun run build && node scripts/run-cli-tests.mjs release",
-    "test:full": "bun run build && node scripts/run-cli-tests.mjs full",
+    "test:full": "bun run build && node scripts/run-cli-tests.mjs full-auto",
+    "test:full:auto": "bun run build && node scripts/run-cli-tests.mjs full-auto",
+    "test:full:serial": "bun run build && node scripts/run-cli-tests.mjs full",
     "check": "bun run check:package && bun run test:full",
     "check:package": "node -e \"const fs=require('fs'); JSON.parse(fs.readFileSync('package.json','utf8')); console.log('package.json ok')\"",
     "check:typecheck": "tsc -p tsconfig.json --noEmit",

package/schemas/commands.schema.json

@@ -135,6 +135,7 @@
           "items": { "type": "string" }
         },
         "cmd": { "type": "string" },
+        "allow_shell": { "type": "boolean" },
         "cwd": { "type": "string" },
         "timeout_seconds": { "type": "integer" },
         "kill_after_seconds": { "type": "integer" },

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -36,14 +36,18 @@ refer to `AGENTS.md` and `.mustflow/config/commands.toml` to implement the most
 
 ## Selection Convention
 
-- Choose one primary skill that best describes the main work. Prefer the most specific matching
-  skill over a broad architecture or review skill.
+- Choose one main route: a `primary` route for ordinary work or an `authoring` route for
+  mustflow authoring and maintenance work. Prefer the most specific matching skill over a broad
+  architecture or review skill.
+- Treat `authoring` routes as selectable main routes, not adjunct routes. Use them when the task
+  creates or maintains mustflow-owned skills, context files, command contracts, route metadata, or
+  public documentation entries.
 - Add no more than two adjunct skills for secondary risks such as tests, documentation, security,
   privacy, release, or contract drift.
 - Treat event-triggered skills as inactive until the event occurs. For example, read
   `failure-triage` only after a configured command intent or verification step fails.
-- If several primary skills appear to match, choose the one tied to the files and behavior being
-  changed now, then report the skipped plausible skills instead of reading every route.
+- If several main routes appear to match, choose the one tied to the files and behavior being
+  changed now, then report the skipped plausible routes instead of reading every route.
 
 ## Classification Prefilter
 
@@ -78,8 +82,8 @@ test tasks from requiring a full read of architecture-pattern routes. Categories
 
 ## Specific Routes
 
-After choosing a category, choose one primary route and at most two adjunct routes. Event routes
-stay inactive until their event occurs.
+After choosing a category, choose one main route (`primary` or `authoring`) and at most two adjunct
+routes. Event routes stay inactive until their event occurs.
 
 ### Bug and Failure
 

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -2,7 +2,7 @@ schema_version = "1"
 
 [routes."artifact-integrity-check"]
 category = "ui_assets"
-route_type = "adjunct"
+route_type = "primary"
 priority = 80
 applies_to_reasons = ["package_metadata_change", "release_risk"]
 
@@ -212,7 +212,7 @@ applies_to_reasons = ["test_change"]
 
 [routes."security-privacy-review"]
 category = "security_privacy"
-route_type = "adjunct"
+route_type = "primary"
 priority = 30
 applies_to_reasons = ["security_change", "privacy_change"]
 

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.22.3"
+version = "2.22.5"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"