mustflow 2.22.9 → 2.22.13

package/dist/cli/commands/check.js

@@ -1,7 +1,7 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
-import { checkMustflowProjectReport, describeCheckIssues } from '../lib/validation.js';
+import { checkMustflowProjectReport } from '../lib/validation.js';
 export function getCheckHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf check [options]',
@@ -51,7 +51,7 @@ export function runCheck(args, reporter, lang = 'en') {
             issues,
             warningCount: warnings.length,
             warnings,
-            issueDetails: describeCheckIssues([...issues, ...warnings]),
+            issueDetails: report.issueDetails,
         }, null, 2));
         return ok ? 0 : 1;
     }

package/dist/cli/commands/help.js

@@ -1,11 +1,9 @@
 import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
+import { isRecord } from '../lib/command-contract.js';
 import { t } from '../lib/i18n.js';
 import { readMustflowTextFileIfExists } from '../lib/mustflow-read.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { readMustflowTomlFile } from '../lib/toml.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function readTextIfExists(projectRoot, relativePath) {
     return readMustflowTextFileIfExists(projectRoot, relativePath) ?? undefined;
 }

package/dist/cli/commands/verify/state-paths.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { createStateRunId } from '../../../core/atomic-state-write.js';
+const RUN_STATE_DIR = path.join('.mustflow', 'state', 'runs');
+const LATEST_RUN_RECEIPT_PATH = path.join(RUN_STATE_DIR, 'latest.json');
+export function createVerifyRunStatePaths(projectRoot) {
+    const runDir = toPosixPath(path.join(RUN_STATE_DIR, createStateRunId('verify')));
+    const manifestPath = toPosixPath(path.join(runDir, 'manifest.json'));
+    const absoluteRunDir = path.join(projectRoot, runDir);
+    return {
+        runDir,
+        manifestPath,
+        absoluteRunDir,
+        absoluteIntentDir: path.join(absoluteRunDir, 'intents'),
+        absoluteManifestPath: path.join(projectRoot, manifestPath),
+    };
+}
+export function createVerifyIntentReceiptPath(statePaths, ordinal, intent) {
+    const fileName = `${String(ordinal).padStart(3, '0')}-${sanitizeIntentFilePart(intent)}.json`;
+    return {
+        receiptPath: toPosixPath(path.join(statePaths.runDir, 'intents', fileName)),
+        absoluteReceiptPath: path.join(statePaths.absoluteIntentDir, fileName),
+    };
+}
+export function resolveLatestVerifyRunReceiptPath(projectRoot) {
+    return path.join(projectRoot, LATEST_RUN_RECEIPT_PATH);
+}
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function sanitizeIntentFilePart(value) {
+    const sanitized = value.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+    return sanitized.length > 0 ? sanitized.slice(0, 80) : 'intent';
+}

package/dist/cli/commands/verify.js

@@ -1,11 +1,9 @@
 import { createHash } from 'node:crypto';
-import path from 'node:path';
 import { runRun } from './run.js';
 import { createChangeVerificationReport, } from '../../core/change-verification.js';
 import { createCorrelationId } from '../../core/correlation-id.js';
 import { readUtf8FileInsideWithoutSymlinks, writeJsonFileInsideWithoutSymlinks } from '../../core/safe-filesystem.js';
 import { createVerifyCompletionVerdict, } from '../../core/completion-verdict.js';
-import { createStateRunId } from '../../core/atomic-state-write.js';
 import { createExternalEvidenceRisks, } from '../../core/external-evidence.js';
 import { createRepeatedFailureRisks, createVerificationFailureFingerprint, updateRepeatedFailureState, } from '../../core/repeated-failure.js';
 import { countReproEvidenceVerdictEffects, createReproEvidenceRisks, } from '../../core/repro-evidence.js';
@@ -17,14 +15,13 @@ import { readCommandContract } from '../../core/config-loading.js';
 import { DEFAULT_VERIFY_PARALLELISM, parseVerifyArgs, resolveVerifyParallelism, } from './verify/args.js';
 import { createInputFromChanged, createSyntheticClassificationReport, planErrorMessageKey, readInputFromClassificationReport, resolveVerifyInputPath, writeChangedPlan, } from './verify/input.js';
 import { readExternalEvidenceFile, readReproEvidenceFile } from './verify/evidence-input.js';
+import { createVerifyIntentReceiptPath, createVerifyRunStatePaths, resolveLatestVerifyRunReceiptPath, } from './verify/state-paths.js';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
 import { readLocalCommandEffectGraphs, readLocalPathSurfaces, readLocalSourceAnchorVerdictRisks, } from '../lib/local-index.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 export { planErrorMessageKey, readInputFromClassificationReport } from './verify/input.js';
 const VERIFY_SCHEMA_VERSION = '1';
-const RUN_STATE_DIR = path.join('.mustflow', 'state', 'runs');
-const LATEST_RUN_RECEIPT_PATH = path.join(RUN_STATE_DIR, 'latest.json');
 function createBufferedOutput() {
     const stdout = [];
     const stderr = [];
@@ -80,25 +77,6 @@ export function getVerifyHelp(lang = 'en') {
 function uniqueStrings(values) {
     return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
 }
-function toPosixPath(value) {
-    return value.split(path.sep).join('/');
-}
-function createVerifyRunStatePaths(projectRoot) {
-    const runDir = toPosixPath(path.join(RUN_STATE_DIR, createStateRunId('verify')));
-    const manifestPath = toPosixPath(path.join(runDir, 'manifest.json'));
-    const absoluteRunDir = path.join(projectRoot, runDir);
-    return {
-        runDir,
-        manifestPath,
-        absoluteRunDir,
-        absoluteIntentDir: path.join(absoluteRunDir, 'intents'),
-        absoluteManifestPath: path.join(projectRoot, manifestPath),
-    };
-}
-function sanitizeIntentFilePart(value) {
-    const sanitized = value.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
-    return sanitized.length > 0 ? sanitized.slice(0, 80) : 'intent';
-}
 function skippedResult(candidate) {
     return {
         intent: candidate.intent || null,
@@ -572,7 +550,7 @@ function readVerificationFailureFingerprint(value) {
 }
 function readPreviousVerifyLatestSummary(projectRoot) {
     try {
-        const parsed = JSON.parse(readUtf8FileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, LATEST_RUN_RECEIPT_PATH)));
+        const parsed = JSON.parse(readUtf8FileInsideWithoutSymlinks(projectRoot, resolveLatestVerifyRunReceiptPath(projectRoot)));
         if (parsed.command !== 'verify' ||
             parsed.kind !== 'verify_run_summary' ||
             typeof parsed.verification_plan_id !== 'string' ||
@@ -652,9 +630,8 @@ function writeVerifyRunReceipts(projectRoot, output, report, sourceAnchorRisks,
         let receiptSha256 = null;
         let receipt = result.receipt;
         if (result.intent && result.receipt) {
-            const fileName = `${String(index + 1).padStart(3, '0')}-${sanitizeIntentFilePart(result.intent)}.json`;
-            const absoluteReceiptPath = path.join(statePaths.absoluteIntentDir, fileName);
-            receiptPath = toPosixPath(path.join(statePaths.runDir, 'intents', fileName));
+            const receiptStatePath = createVerifyIntentReceiptPath(statePaths, index + 1, result.intent);
+            receiptPath = receiptStatePath.receiptPath;
             receipt = {
                 ...result.receipt,
                 verification_plan_id: output.verification_plan_id,
@@ -662,7 +639,7 @@ function writeVerifyRunReceipts(projectRoot, output, report, sourceAnchorRisks,
             };
             const receiptContent = `${JSON.stringify(receipt, null, 2)}\n`;
             receiptSha256 = hashTextSha256(receiptContent);
-            writeJsonFileInsideWithoutSymlinks(projectRoot, absoluteReceiptPath, receipt);
+            writeJsonFileInsideWithoutSymlinks(projectRoot, receiptStatePath.absoluteReceiptPath, receipt);
         }
         receipts.push({
             intent: result.intent,
@@ -791,7 +768,7 @@ function writeVerifyRunReceipts(projectRoot, output, report, sourceAnchorRisks,
         run_dir: statePaths.runDir,
         manifest_path: statePaths.manifestPath,
     };
-    writeJsonFileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, LATEST_RUN_RECEIPT_PATH), latest);
+    writeJsonFileInsideWithoutSymlinks(projectRoot, resolveLatestVerifyRunReceiptPath(projectRoot), latest);
     return outputWithReceiptPaths;
 }
 async function createVerifyOutput(input, planSource, projectRoot, lang, reproEvidence = null, externalChecks = [], parallelism = DEFAULT_VERIFY_PARALLELISM, parallelismReport = null) {

package/dist/cli/lib/doc-review-ledger.js

@@ -2,14 +2,12 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { triageDocReview } from '../../core/doc-review-triage.js';
 import { ensureInside, ensureInsideWithoutSymlinks, readUtf8FileInsideWithoutSymlinks, toPosixPath, writeUtf8FileInsideWithoutSymlinks, } from './filesystem.js';
+import { isRecord } from './command-contract.js';
 import { parseTomlText, stringifyToml } from './toml.js';
 export const DOC_REVIEW_LEDGER_RELATIVE_PATH = '.mustflow/review/docs.toml';
 export const DOC_REVIEW_STATUSES = ['pending', 'in_review', 'changes_made', 'approved', 'needs_human', 'ignored'];
 export const DOC_REVIEW_ACTIVE_STATUSES = ['pending', 'in_review', 'changes_made', 'needs_human'];
 export const REVIEWER_KINDS = ['human', 'llm', 'tool', 'external'];
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function readOptionalString(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
 }

package/dist/cli/lib/manifest-lock.js

@@ -2,11 +2,9 @@ import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { ensureFileTargetInsideWithoutSymlinks, ensureInside, readFileInsideWithoutSymlinks, readUtf8FileInsideWithoutSymlinks, writeUtf8FileInsideWithoutSymlinks, } from './filesystem.js';
+import { isRecord } from './command-contract.js';
 import { parseTomlText, stringifyToml } from './toml.js';
 export const MANIFEST_LOCK_RELATIVE_PATH = '.mustflow/config/manifest.lock.toml';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function readString(table, key, label) {
     const value = table[key];
     if (typeof value !== 'string' || value.trim().length === 0) {

package/dist/cli/lib/repo-map-frontmatter.js

@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto';
+const REPO_MAP_DOC_ID = 'repo-map';
+const REPO_MAP_LIFECYCLE = 'generated';
+const REPO_MAP_GENERATOR = 'mustflow';
+const REPO_MAP_RELATIVE_ROOT = '.';
+const REPO_MAP_SOURCE_POLICY = 'anchors_only';
+const REPO_MAP_PRIVACY_MODE = 'minimal';
+export function getRepoMapSourceFingerprint(input) {
+    const payload = {
+        depth: input.depth,
+        includeNested: input.includeNested,
+        gitLsFilesStatus: input.gitLsFilesStatus,
+        priorityPaths: [...input.configuredPriorityPaths].sort(),
+        anchors: input.anchors.map((anchor) => anchor.relativePath).sort(),
+        nestedRepositories: input.nestedRepositories
+            .map((repository) => ({
+            relativePath: repository.relativePath,
+            mustflow: repository.mustflow,
+            agentRules: repository.agentRules,
+            repoMap: repository.repoMap,
+            mustflowConfig: repository.mustflowConfig,
+            commandContract: repository.commandContract,
+            contextIndex: repository.contextIndex,
+            skillIndex: repository.skillIndex,
+            rootDocuments: repository.rootDocuments.map((document) => document.relativePath).sort(),
+            machineContracts: [...repository.machineContracts].sort(),
+            manifests: [...repository.manifests].sort(),
+            commandAdapters: [...repository.commandAdapters].sort(),
+            editingPolicies: [...repository.editingPolicies].sort(),
+        }))
+            .sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
+    };
+    const digest = createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+    return `sha256:${digest}`;
+}
+export function renderRepoMapFrontmatter(anchorCount, sourceFingerprint, gitLsFilesStatus) {
+    const degraded = gitLsFilesStatus !== 'ok';
+    return [
+        '---',
+        `mustflow_doc: ${REPO_MAP_DOC_ID}`,
+        `lifecycle: ${REPO_MAP_LIFECYCLE}`,
+        `generated_by: ${REPO_MAP_GENERATOR}`,
+        `relative_root: "${REPO_MAP_RELATIVE_ROOT}"`,
+        `source_policy: ${REPO_MAP_SOURCE_POLICY}`,
+        `privacy_mode: ${REPO_MAP_PRIVACY_MODE}`,
+        `anchor_count: ${anchorCount}`,
+        `degraded: ${degraded ? 'true' : 'false'}`,
+        `git_ls_files_status: ${gitLsFilesStatus}`,
+        `source_fingerprint: "${sourceFingerprint}"`,
+        '---',
+        '',
+    ];
+}

package/dist/cli/lib/repo-map.js

@@ -1,17 +1,12 @@
 import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { toPosixPath } from './filesystem.js';
+import { getRepoMapSourceFingerprint, renderRepoMapFrontmatter, } from './repo-map-frontmatter.js';
 import { writeUtf8FileInsideWithoutSymlinks } from '../../core/safe-filesystem.js';
+import { isRecord } from './command-contract.js';
 import { readMustflowTomlFile } from './toml.js';
 const DEFAULT_DEPTH = 3;
-const REPO_MAP_DOC_ID = 'repo-map';
-const REPO_MAP_LIFECYCLE = 'generated';
-const REPO_MAP_GENERATOR = 'mustflow';
-const REPO_MAP_RELATIVE_ROOT = '.';
-const REPO_MAP_SOURCE_POLICY = 'anchors_only';
-const REPO_MAP_PRIVACY_MODE = 'minimal';
 const GIT_LS_FILES_TIMEOUT_MS = 5_000;
 const GIT_LS_FILES_MAX_BUFFER_BYTES = 1_048_576;
 const EXCLUDED_SEGMENTS = new Set([
@@ -196,9 +191,6 @@ const EXACT_ANCHOR_DESCRIPTIONS = new Map([
     ['.mustflow/docs/agent-workflow.md', 'Shared workflow policy for agent work.'],
     ['.mustflow/skills/INDEX.md', 'Index of available procedural skills.'],
 ]);
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function getStringArray(value) {
     return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
 }
@@ -624,52 +616,6 @@ function countNestedEntrypoints(repository) {
         ...repository.editingPolicies,
     ].filter(Boolean).length;
 }
-function getSourceFingerprint(depth, includeNested, configuredPriorityPaths, gitLsFilesStatus, anchors, nestedRepositories) {
-    const payload = {
-        depth,
-        includeNested,
-        gitLsFilesStatus,
-        priorityPaths: [...configuredPriorityPaths].sort(),
-        anchors: anchors.map((anchor) => anchor.relativePath).sort(),
-        nestedRepositories: nestedRepositories
-            .map((repository) => ({
-            relativePath: repository.relativePath,
-            mustflow: repository.mustflow,
-            agentRules: repository.agentRules,
-            repoMap: repository.repoMap,
-            mustflowConfig: repository.mustflowConfig,
-            commandContract: repository.commandContract,
-            contextIndex: repository.contextIndex,
-            skillIndex: repository.skillIndex,
-            rootDocuments: repository.rootDocuments.map((document) => document.relativePath).sort(),
-            machineContracts: [...repository.machineContracts].sort(),
-            manifests: [...repository.manifests].sort(),
-            commandAdapters: [...repository.commandAdapters].sort(),
-            editingPolicies: [...repository.editingPolicies].sort(),
-        }))
-            .sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
-    };
-    const digest = createHash('sha256').update(JSON.stringify(payload)).digest('hex');
-    return `sha256:${digest}`;
-}
-function renderRepoMapFrontmatter(anchorCount, sourceFingerprint, gitLsFilesStatus) {
-    const degraded = gitLsFilesStatus !== 'ok';
-    return [
-        '---',
-        `mustflow_doc: ${REPO_MAP_DOC_ID}`,
-        `lifecycle: ${REPO_MAP_LIFECYCLE}`,
-        `generated_by: ${REPO_MAP_GENERATOR}`,
-        `relative_root: "${REPO_MAP_RELATIVE_ROOT}"`,
-        `source_policy: ${REPO_MAP_SOURCE_POLICY}`,
-        `privacy_mode: ${REPO_MAP_PRIVACY_MODE}`,
-        `anchor_count: ${anchorCount}`,
-        `degraded: ${degraded ? 'true' : 'false'}`,
-        `git_ls_files_status: ${gitLsFilesStatus}`,
-        `source_fingerprint: "${sourceFingerprint}"`,
-        '---',
-        '',
-    ];
-}
 function renderSourceQuality(gitLsFilesStatus) {
     if (gitLsFilesStatus === 'ok') {
         return [];
@@ -701,7 +647,14 @@ export function generateRepoMap(projectRoot, options = {}) {
         .filter((anchor) => Boolean(anchor));
     const otherAnchors = anchors.filter((anchor) => !priorityPathSet.has(anchor.relativePath));
     const anchorCount = anchors.length + nestedRepositories.reduce((total, repository) => total + countNestedEntrypoints(repository), 0);
-    const sourceFingerprint = getSourceFingerprint(depth, mapConfig.includeNested, configuredPriorityPaths, gitLsFilesStatus, anchors, nestedRepositories);
+    const sourceFingerprint = getRepoMapSourceFingerprint({
+        depth,
+        includeNested: mapConfig.includeNested,
+        configuredPriorityPaths,
+        gitLsFilesStatus,
+        anchors,
+        nestedRepositories,
+    });
     return [
         ...renderRepoMapFrontmatter(anchorCount, sourceFingerprint, gitLsFilesStatus),
         '# REPO_MAP.md',

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

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { isRecord } from '../command-contract.js';
 import { validateCommandContractConfig, validateCommandContractStrictDefaults, } from '../../../core/command-contract-validation.js';
+import { describeCheckIssues } from '../../../core/check-issues.js';
 import { ALLOWED_RETENTION_ON_LIMIT, ALLOWED_RETENTION_STORES, DEFAULT_RETENTION_LIMITS, readNestedRetentionTable, readRetentionTable, resolveRetentionLimits, } from '../../../core/retention-policy.js';
 import { formatManagedMarkdownLabel, getManagedMarkdownExpectation, } from '../../../core/authority-resolution.js';
 import { SKILL_INDEX_ROUTE_COLUMN_COUNT, SKILL_INDEX_ROUTE_COLUMNS, SKILL_INDEX_SKILL_PATH_COLUMN_INDEX, findSkillRouteConflictWarnings, findSkillIndexRoutePathColumn, parseSkillIndexRoutes, readBacktickValues, } from '../../../core/skill-route-alignment.js';
@@ -1641,12 +1642,15 @@ function collectCheckIssues(projectRoot, options = {}) {
 }
 export function checkMustflowProjectReport(projectRoot, options = {}) {
     const issues = collectCheckIssues(projectRoot, options);
-    const errors = issues.filter((issue) => issue.severity !== 'warning').map((issue) => issue.message);
-    const warnings = issues.filter((issue) => issue.severity === 'warning').map((issue) => issue.message);
+    const errorIssues = issues.filter((issue) => issue.severity !== 'warning');
+    const warningIssues = issues.filter((issue) => issue.severity === 'warning');
+    const errors = errorIssues.map((issue) => issue.message);
+    const warnings = warningIssues.map((issue) => issue.message);
     return {
         issues: errors,
         warnings,
         allMessages: [...errors, ...warnings],
+        issueDetails: describeCheckIssues([...errorIssues, ...warningIssues]),
     };
 }
 export function checkMustflowProject(projectRoot, options = {}) {

package/dist/core/check-issues.js

@@ -86,11 +86,15 @@ export function getCheckIssueId(message) {
     }
     return null;
 }
-export function describeCheckIssues(messages) {
-    return messages.map((message) => ({
-        id: getCheckIssueId(message),
-        severity: message.startsWith('Strict warning: ') ? 'warning' : 'error',
-        mode: message.startsWith('Strict') ? 'strict' : 'base',
-        message,
-    }));
+export function describeCheckIssues(issues) {
+    return issues.map((issue) => {
+        const message = typeof issue === 'string' ? issue : issue.message;
+        const severity = message.startsWith('Strict warning: ') ? 'warning' : 'error';
+        return {
+            id: typeof issue === 'string' ? getCheckIssueId(message) : issue.id ?? getCheckIssueId(message),
+            severity: typeof issue === 'string' ? severity : issue.severity ?? severity,
+            mode: message.startsWith('Strict') ? 'strict' : 'base',
+            message,
+        };
+    });
 }

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

@@ -6,11 +6,11 @@ import { COMMAND_EFFECT_CONCURRENCY, COMMAND_EFFECT_MODES, COMMAND_EFFECT_TYPES,
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
 import { MAX_COMMAND_OUTPUT_BYTES, commandMaxOutputBytesLimitMessage } from './command-output-limits.js';
 import { SUCCESS_EXIT_CODES_CONTRACT_DESCRIPTION, successExitCodesAreValid } from './success-exit-codes.js';
-function commandContractIssue(message) {
-    return { message };
+function commandContractIssue(message, id) {
+    return id ? { id, message } : { message };
 }
-function commandContractWarning(message) {
-    return { message, severity: 'warning' };
+function commandContractWarning(message, id) {
+    return id ? { id, message, severity: 'warning' } : { message, severity: 'warning' };
 }
 function hasOwn(table, key) {
     return Object.prototype.hasOwnProperty.call(table, key);
@@ -56,7 +56,7 @@ function validatePositiveIntegerField(table, key, label, issues) {
 function validateMaxOutputBytesField(table, key, label, issues) {
     validatePositiveIntegerField(table, key, label, issues);
     if (isPositiveInteger(table[key]) && Number(table[key]) > MAX_COMMAND_OUTPUT_BYTES) {
-        issues.push(commandContractIssue(commandMaxOutputBytesLimitMessage(label)));
+        issues.push(commandContractIssue(commandMaxOutputBytesLimitMessage(label), 'mustflow.command_contract.max_output_bytes_exceeds_limit'));
     }
 }
 function validateAllowedStringField(table, key, label, allowedValues, issues) {
@@ -115,7 +115,7 @@ function validateCommandIntentEffects(intentName, intent, issues) {
         return;
     }
     if (!Array.isArray(intent.effects) || intent.effects.some((entry) => !isRecord(entry))) {
-        issues.push(commandContractIssue(`[commands.intents.${intentName}].effects must be an array of tables`));
+        issues.push(commandContractIssue(`[commands.intents.${intentName}].effects must be an array of tables`, 'mustflow.command_contract.effects_invalid'));
         return;
     }
     for (const effect of intent.effects) {
@@ -171,39 +171,39 @@ function validateCommandIntent(intentName, intent, issues) {
     const lifecycle = typeof intent.lifecycle === 'string' ? intent.lifecycle : undefined;
     const runPolicy = typeof intent.run_policy === 'string' ? intent.run_policy : undefined;
     if (!lifecycle) {
-        issues.push(commandContractIssue(`Configured intent ${intentName} must define lifecycle`));
+        issues.push(commandContractIssue(`Configured intent ${intentName} must define lifecycle`, 'mustflow.command_contract.configured_missing_lifecycle'));
     }
     if (!runPolicy) {
-        issues.push(commandContractIssue(`Configured intent ${intentName} must define run_policy`));
+        issues.push(commandContractIssue(`Configured intent ${intentName} must define run_policy`, 'mustflow.command_contract.configured_missing_run_policy'));
     }
     if (lifecycle === 'oneshot') {
         validatePositiveIntegerField(intent, 'timeout_seconds', `[commands.intents.${intentName}].timeout_seconds`, issues);
         if (!hasOwn(intent, 'timeout_seconds')) {
-            issues.push(commandContractIssue(`Oneshot intent ${intentName} must define timeout_seconds`));
+            issues.push(commandContractIssue(`Oneshot intent ${intentName} must define timeout_seconds`, 'mustflow.command_contract.oneshot_missing_timeout'));
         }
         if (intent.stdin !== 'closed') {
-            issues.push(commandContractIssue(`Oneshot intent ${intentName} must set stdin = "closed"`));
+            issues.push(commandContractIssue(`Oneshot intent ${intentName} must set stdin = "closed"`, 'mustflow.command_contract.oneshot_stdin_not_closed'));
         }
     }
     if (lifecycle && LONG_RUNNING_LIFECYCLES.has(lifecycle) && runPolicy === 'agent_allowed') {
-        issues.push(commandContractIssue(`Long-running intent ${intentName} must not use run_policy = "agent_allowed"`));
+        issues.push(commandContractIssue(`Long-running intent ${intentName} must not use run_policy = "agent_allowed"`, 'mustflow.command_contract.long_running_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`));
+        issues.push(commandContractIssue(`Agent-runnable shell intent ${intentName} must set allow_shell = true`, 'mustflow.command_contract.agent_shell_requires_allow'));
     }
     if (!commandIntentHasCommandSource(intent)) {
-        issues.push(commandContractIssue(`Configured intent ${intentName} must define argv or mode = "shell" with cmd`));
+        issues.push(commandContractIssue(`Configured intent ${intentName} must define argv or mode = "shell" with cmd`, 'mustflow.command_contract.executable_source_missing'));
     }
     const blockedCommandPattern = commandIntentBlockedCommandPattern(intent);
     if (blockedCommandPattern?.code === 'shell_background_pattern') {
-        issues.push(commandContractIssue(`Shell intent ${intentName} contains a blocked long-running or background pattern`));
+        issues.push(commandContractIssue(`Shell intent ${intentName} contains a blocked long-running or background pattern`, 'mustflow.command_contract.shell_background_pattern'));
     }
     if (blockedCommandPattern?.code === 'long_running_command_pattern') {
-        issues.push(commandContractIssue(`Intent ${intentName} contains a blocked long-running or background command pattern`));
+        issues.push(commandContractIssue(`Intent ${intentName} contains a blocked long-running or background command pattern`, 'mustflow.command_contract.long_running_command_pattern'));
     }
     if (hasOwn(intent, 'success_exit_codes')) {
         if (!successExitCodesAreValid(intent.success_exit_codes)) {
-            issues.push(commandContractIssue(`[commands.intents.${intentName}].success_exit_codes must be ${SUCCESS_EXIT_CODES_CONTRACT_DESCRIPTION}`));
+            issues.push(commandContractIssue(`[commands.intents.${intentName}].success_exit_codes must be ${SUCCESS_EXIT_CODES_CONTRACT_DESCRIPTION}`, 'mustflow.command_contract.success_exit_codes_invalid'));
         }
     }
     validateCommandIntentEffects(intentName, intent, issues);
@@ -281,7 +281,9 @@ function validateCommandEnvInheritanceWarnings(commandsToml) {
     const issues = [];
     for (const warning of findCommandEnvInheritanceWarnings(commandsToml)) {
         const message = formatCommandEnvInheritanceWarning(warning);
-        issues.push(warning.severity === 'warning' ? commandContractWarning(message) : commandContractIssue(message));
+        issues.push(warning.severity === 'warning'
+            ? commandContractWarning(message, 'mustflow.command_contract.broad_env_inheritance')
+            : commandContractIssue(message, 'mustflow.command_contract.broad_env_inheritance'));
     }
     return issues;
 }
@@ -316,7 +318,7 @@ function validateProjectLocalBinWarnings(projectRoot, commandsToml) {
         if (!projectLocalBinExecutableExists(projectRoot, executable)) {
             continue;
         }
-        issues.push(commandContractWarning(`configured agent-runnable intent ${intentName} uses bare executable "${executable}" that matches project-local node_modules/.bin; use a package-manager mediated command such as npm exec, pnpm exec, bun x, or yarn exec`));
+        issues.push(commandContractWarning(`configured agent-runnable intent ${intentName} uses bare executable "${executable}" that matches project-local node_modules/.bin; use a package-manager mediated command such as npm exec, pnpm exec, bun x, or yarn exec`, 'mustflow.command_contract.project_local_bin_bare_executable'));
     }
     return issues;
 }
@@ -336,12 +338,12 @@ export function validateCommandContractConfig(commandsToml) {
     validateCommandDefaults(commandsToml, issues);
     validateCommandResources(commandsToml, issues);
     if (!isRecord(commandsToml.intents)) {
-        issues.push(commandContractIssue('Missing [intents] table in .mustflow/config/commands.toml'));
+        issues.push(commandContractIssue('Missing [intents] table in .mustflow/config/commands.toml', 'mustflow.command_contract.intent_table_missing'));
         return issues;
     }
     for (const [intentName, intent] of Object.entries(commandsToml.intents)) {
         if (!isRecord(intent)) {
-            issues.push(commandContractIssue(`Intent ${intentName} must be a TOML table`));
+            issues.push(commandContractIssue(`Intent ${intentName} must be a TOML table`, 'mustflow.command_contract.intent_not_table'));
             continue;
         }
         validateCommandIntent(intentName, intent, issues);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.22.9",
+  "version": "2.22.13",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",
@@ -28,19 +28,20 @@
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "bun run test:full",
-    "test:fast": "bun run build && node scripts/run-cli-tests.mjs fast",
-    "test:related": "bun run build && node scripts/run-cli-tests.mjs related",
+    "test:fast": "node scripts/run-cli-tests.mjs --build fast",
+    "test:related": "node scripts/run-cli-tests.mjs --build related",
     "test:related:cached": "node scripts/run-cli-tests.mjs related-cached",
-    "test:related:profile": "bun run build && node scripts/run-cli-tests.mjs related-profile",
-    "test:cli": "bun run build && node scripts/run-cli-tests.mjs cli",
-    "test:coverage": "bun run build && node scripts/run-cli-tests.mjs coverage",
+    "test:related:profile": "node scripts/run-cli-tests.mjs --build related-profile",
+    "test:cli": "node scripts/run-cli-tests.mjs --build cli",
+    "test:coverage": "node scripts/run-cli-tests.mjs --build coverage",
     "test:audit": "node scripts/audit-tests.mjs --json",
-    "test:release": "bun run build && node scripts/run-cli-tests.mjs release",
-    "test:fast:node": "npm run build && node scripts/run-cli-tests.mjs fast",
-    "test:release:node": "npm run build && node scripts/run-cli-tests.mjs release",
-    "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",
+    "test:release": "node scripts/run-cli-tests.mjs --build release",
+    "test:fast:node": "node scripts/run-cli-tests.mjs --build-runner=npm fast",
+    "test:release:node": "node scripts/run-cli-tests.mjs --build-runner=npm release",
+    "test:full": "node scripts/run-cli-tests.mjs --build full-auto",
+    "test:full:auto": "node scripts/run-cli-tests.mjs --build full-auto",
+    "test:full:profile": "node scripts/run-cli-tests.mjs --build full-profile",
+    "test:full:serial": "node scripts/run-cli-tests.mjs --build full",
     "check": "bun run check:package && bun run test:full",
     "check:core:node": "node scripts/run-node-core-check.mjs",
     "check:package": "node -e \"const fs=require('fs'); JSON.parse(fs.readFileSync('package.json','utf8')); console.log('package.json ok')\"",