mustflow 1.18.16 → 1.31.0

package/dist/core/contract-lint.js

@@ -1,7 +1,60 @@
-import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, readPositiveInteger, readString, } from './config-loading.js';
-import { evaluateCommandIntentEligibility } from './command-intent-eligibility.js';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, readPositiveInteger, readString, readStringArray, } from './config-loading.js';
+import { evaluateCommandIntentEligibility, } from './command-intent-eligibility.js';
 import { commandIntentHasBlockedShellBackgroundPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
-const CONTRACT_LINT_SOURCE_FILES = ['.mustflow/config/commands.toml', '.mustflow/docs/agent-workflow.md', 'AGENTS.md'];
+import { commandEffectsConflict, normalizeCommandEffects } from './command-effects.js';
+import { listChangeClassificationValidationReasons } from './change-classification.js';
+import { parseSkillIndexRoutes } from './skill-route-alignment.js';
+const CONTRACT_LINT_SOURCE_FILES = [
+    '.mustflow/config/commands.toml',
+    '.mustflow/docs/agent-workflow.md',
+    'AGENTS.md',
+    'src/core/change-classification.ts',
+];
+export const DOCUMENTED_VERIFICATION_REASONS = [
+    'before_publish',
+    'before_final_report',
+    'before_task',
+    'behavior_change',
+    'behavior_removed',
+    'build_config_change',
+    'clean_mustflow_update_plan',
+    'commit_message_suggestion',
+    'coverage_request',
+    'cross_cutting_code_change',
+    'directory_change',
+    'formatting_change',
+    'image_asset_change',
+    'line_ending_warning',
+    'low_risk_code_change',
+    'snapshot_change',
+    'structure_change',
+    'style_change',
+    'template_update_apply',
+    'template_update_check',
+    'test_policy_change',
+    'user_approved_snapshot_update',
+    'user_requested_line_ending_normalization',
+    'web_asset_change',
+];
+const RELEASE_SENSITIVE_REASONS = new Set([
+    'package_metadata_change',
+    'packaging_change',
+    'release_risk',
+    'template_version_change',
+]);
+const COMMANDS_CONFIG_PATH = '.mustflow/config/commands.toml';
+const SKILL_INDEX_PATH = '.mustflow/skills/INDEX.md';
+const CHANGE_CLASSIFICATION_SOURCE_PATH = 'src/core/change-classification.ts';
+const AGENT_WORKFLOW_PATH = '.mustflow/docs/agent-workflow.md';
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function intersectSorted(left, right) {
+    const rightSet = new Set(right);
+    return uniqueSorted(left.filter((value) => rightSet.has(value)));
+}
 function readBoolean(intent, key) {
     const value = intent[key];
     return typeof value === 'boolean' ? value : null;
@@ -17,6 +70,17 @@ function writesAreValid(intent) {
 function pushIssue(issues, severity, code, intent, message) {
     issues.push({ severity, code, intent, message });
 }
+function pushCoverageFinding(issues, findings, severity, code, reason, intent, intents, message) {
+    findings.push({
+        severity,
+        code,
+        reason,
+        intent,
+        intents: [...intents].sort((left, right) => left.localeCompare(right)),
+        message,
+    });
+    pushIssue(issues, severity, code, intent, message);
+}
 function configuredIntentIsRunnable(intent) {
     return evaluateCommandIntentEligibility('summary', intent).ok;
 }
@@ -79,18 +143,209 @@ function lintIntent(name, value, issues) {
     }
     return value;
 }
+function collectRequiredAfterReasons(contract) {
+    const reasonToIntents = new Map();
+    for (const [name, intent] of Object.entries(contract.intents)) {
+        if (!isRecord(intent)) {
+            continue;
+        }
+        for (const reason of readStringArray(intent, 'required_after') ?? []) {
+            reasonToIntents.set(reason, [
+                ...(reasonToIntents.get(reason) ?? []),
+                {
+                    name,
+                    intent,
+                    runnable: evaluateCommandIntentEligibility(name, intent).ok,
+                },
+            ]);
+        }
+    }
+    return reasonToIntents;
+}
+function readSkillPathsByIntent(projectRoot) {
+    const skillPathsByIntent = new Map();
+    if (!projectRoot) {
+        return skillPathsByIntent;
+    }
+    const skillIndexPath = path.join(projectRoot, ...SKILL_INDEX_PATH.split('/'));
+    if (!existsSync(skillIndexPath)) {
+        return skillPathsByIntent;
+    }
+    const routes = parseSkillIndexRoutes(readFileSync(skillIndexPath, 'utf8'));
+    for (const route of routes) {
+        for (const intent of route.commandIntents) {
+            skillPathsByIntent.set(intent, [...(skillPathsByIntent.get(intent) ?? []), route.skillPath]);
+        }
+    }
+    return skillPathsByIntent;
+}
+function classifyReasonSource(reason, knownClassificationReasons, documentedVerificationReasons) {
+    if (knownClassificationReasons.includes(reason)) {
+        return 'classification';
+    }
+    if (documentedVerificationReasons.includes(reason)) {
+        return 'documented';
+    }
+    return 'required_after';
+}
+function buildRelatedDocs(source, relatedSkills) {
+    const docs = [COMMANDS_CONFIG_PATH];
+    if (source === 'classification') {
+        docs.push(CHANGE_CLASSIFICATION_SOURCE_PATH);
+    }
+    if (source === 'documented') {
+        docs.push(AGENT_WORKFLOW_PATH);
+    }
+    if (relatedSkills.length > 0) {
+        docs.push(SKILL_INDEX_PATH);
+    }
+    return uniqueSorted(docs);
+}
+function buildCoverageMatrix(reasonToIntents, knownClassificationReasons, documentedVerificationReasons, skillPathsByIntent) {
+    const matrixReasons = uniqueSorted([
+        ...knownClassificationReasons,
+        ...documentedVerificationReasons,
+        ...reasonToIntents.keys(),
+    ]);
+    return matrixReasons.map((reason) => {
+        const candidates = [...(reasonToIntents.get(reason) ?? [])].sort((left, right) => left.name.localeCompare(right.name));
+        const source = classifyReasonSource(reason, knownClassificationReasons, documentedVerificationReasons);
+        const intentNames = candidates.map((candidate) => candidate.name);
+        const relatedSkills = uniqueSorted(intentNames.flatMap((intent) => skillPathsByIntent.get(intent) ?? []));
+        const gaps = [];
+        if (candidates.length === 0) {
+            gaps.push('missing_required_after');
+        }
+        else if (!candidates.some((candidate) => candidate.runnable)) {
+            gaps.push('no_runnable_intent');
+        }
+        if (source === 'required_after') {
+            gaps.push('unknown_reason');
+        }
+        if (intentNames.length > 0 && intersectSorted(intentNames, [...skillPathsByIntent.keys()]).length === 0) {
+            gaps.push('no_related_skill_route');
+        }
+        return {
+            reason,
+            source,
+            intents: candidates.map((candidate) => {
+                const eligibility = evaluateCommandIntentEligibility(candidate.name, candidate.intent);
+                return {
+                    intent: candidate.name,
+                    status: eligibility.code,
+                    runnable: eligibility.ok,
+                    detail: eligibility.detail,
+                };
+            }),
+            gaps: uniqueSorted(gaps),
+            relatedSkills,
+            relatedDocs: buildRelatedDocs(source, relatedSkills),
+        };
+    });
+}
+function hasExplicitEffectMetadata(intent) {
+    return Array.isArray(intent.effects) && intent.effects.some((effect) => isRecord(effect));
+}
+function intentLooksReleaseFocused(name, intent) {
+    const text = `${name} ${readString(intent, 'description') ?? ''}`.toLowerCase();
+    return /(?:^|[_\W])(?:release|package|pack|packaging|publish)(?:$|[_\W])/u.test(text);
+}
+function addConflictingWriteCoverageWarnings(contract, projectRoot, reason, candidates, issues, findings) {
+    if (!projectRoot) {
+        return;
+    }
+    const runnableCandidates = candidates.filter((candidate) => candidate.runnable);
+    for (let leftIndex = 0; leftIndex < runnableCandidates.length; leftIndex += 1) {
+        const left = runnableCandidates[leftIndex];
+        const leftHasExplicitEffects = hasExplicitEffectMetadata(left.intent);
+        let leftEffects;
+        try {
+            leftEffects = normalizeCommandEffects(projectRoot, contract, left.name);
+        }
+        catch {
+            continue;
+        }
+        for (let rightIndex = leftIndex + 1; rightIndex < runnableCandidates.length; rightIndex += 1) {
+            const right = runnableCandidates[rightIndex];
+            const rightHasExplicitEffects = hasExplicitEffectMetadata(right.intent);
+            if (leftHasExplicitEffects && rightHasExplicitEffects) {
+                continue;
+            }
+            let rightEffects;
+            try {
+                rightEffects = normalizeCommandEffects(projectRoot, contract, right.name);
+            }
+            catch {
+                continue;
+            }
+            const conflicts = leftEffects.some((leftEffect) => rightEffects.some((rightEffect) => commandEffectsConflict(leftEffect, rightEffect)));
+            if (!conflicts) {
+                continue;
+            }
+            pushCoverageFinding(issues, findings, 'warning', 'coverage_conflicting_writes_without_effects', reason, null, [left.name, right.name], `Reason "${reason}" selects runnable intents ${left.name} and ${right.name} that share write effects without explicit effects or resource locks.`);
+        }
+    }
+}
+function lintCoverage(contract, options, issues) {
+    const findings = [];
+    const knownClassificationReasons = listChangeClassificationValidationReasons();
+    const documentedVerificationReasons = [...DOCUMENTED_VERIFICATION_REASONS];
+    const knownReasons = new Set([...knownClassificationReasons, ...documentedVerificationReasons]);
+    const reasonToIntents = collectRequiredAfterReasons(contract);
+    const skillPathsByIntent = readSkillPathsByIntent(options.projectRoot);
+    const requiredAfterReasons = uniqueSorted(reasonToIntents.keys());
+    const runnableReasons = uniqueSorted([...reasonToIntents.entries()]
+        .filter(([, candidates]) => candidates.some((candidate) => candidate.runnable))
+        .map(([reason]) => reason));
+    for (const reason of knownClassificationReasons) {
+        const candidates = reasonToIntents.get(reason) ?? [];
+        if (candidates.length === 0) {
+            pushCoverageFinding(issues, findings, 'warning', 'coverage_uncovered_classification_reason', reason, null, [], `Classification reason "${reason}" has no matching required_after entry in commands.toml.`);
+            continue;
+        }
+        if (!candidates.some((candidate) => candidate.runnable)) {
+            pushCoverageFinding(issues, findings, 'warning', 'coverage_reason_not_runnable', reason, null, candidates.map((candidate) => candidate.name), `Reason "${reason}" is covered only by non-runnable intents: ${candidates
+                .map((candidate) => candidate.name)
+                .sort((left, right) => left.localeCompare(right))
+                .join(', ')}.`);
+        }
+        addConflictingWriteCoverageWarnings(contract, options.projectRoot, reason, candidates, issues, findings);
+    }
+    for (const [reason, candidates] of reasonToIntents) {
+        if (knownReasons.has(reason)) {
+            continue;
+        }
+        pushCoverageFinding(issues, findings, 'warning', 'coverage_unknown_required_after', reason, null, candidates.map((candidate) => candidate.name), `required_after reason "${reason}" is not emitted by change classification or listed as a documented verification reason.`);
+    }
+    if (options.releaseVersioningEnabled === true) {
+        const hasReleaseVerificationPath = [...reasonToIntents.entries()].some(([reason, candidates]) => RELEASE_SENSITIVE_REASONS.has(reason) &&
+            candidates.some((candidate) => candidate.runnable && intentLooksReleaseFocused(candidate.name, candidate.intent)));
+        if (!hasReleaseVerificationPath) {
+            pushCoverageFinding(issues, findings, 'warning', 'coverage_release_path_missing', null, null, [], 'Release versioning is enabled, but release-sensitive reasons have no runnable release or package verification intent.');
+        }
+    }
+    return {
+        knownClassificationReasons,
+        documentedVerificationReasons,
+        requiredAfterReasons,
+        runnableReasons,
+        matrix: buildCoverageMatrix(reasonToIntents, knownClassificationReasons, documentedVerificationReasons, skillPathsByIntent),
+        findings,
+    };
+}
 function getStatus(errors, warnings) {
     if (errors > 0) {
         return 'failed';
     }
     return warnings > 0 ? 'warning' : 'passed';
 }
-export function lintCommandContract(contract) {
+export function lintCommandContract(contract, options = {}) {
     const issues = [];
     const intentEntries = Object.entries(contract.intents);
     const intentTables = intentEntries
         .map(([name, value]) => lintIntent(name, value, issues))
         .filter((intent) => intent !== null);
+    const coverage = options.coverage === true ? lintCoverage(contract, options, issues) : undefined;
     const errors = issues.filter((issue) => issue.severity === 'error').length;
     const warnings = issues.length - errors;
     return {
@@ -106,5 +361,6 @@ export function lintCommandContract(contract) {
         },
         issues,
         sourceFiles: CONTRACT_LINT_SOURCE_FILES,
+        coverage,
     };
 }

package/dist/core/contract-models.js

@@ -1,3 +1,6 @@
+import path from 'node:path';
+import { PUBLIC_SURFACE_UPDATE_POLICIES } from './change-classification.js';
+import { isRecord } from './config-loading.js';
 export const CONTRACT_MODEL_DEFINITIONS = [
     {
         id: 'changes',
@@ -51,3 +54,172 @@ export function getNonInstalledContractConfigPaths() {
         .filter((model) => !model.installByDefault)
         .map((model) => model.filePath);
 }
+const PATH_CLASSIFICATION_MODEL_IDS = new Set(['changes', 'surfaces']);
+const ALLOWED_TOP_LEVEL_FIELDS = new Set(['schema_version', 'rules']);
+const ALLOWED_RULE_FIELDS = new Set([
+    'id',
+    'description',
+    'match',
+    'change_kinds',
+    'surface_kind',
+    'category',
+    'is_public_surface',
+    'validation_reasons',
+    'affected_contracts',
+    'update_policy',
+    'drift_checks',
+]);
+const ALLOWED_MATCH_FIELDS = new Set(['kind', 'path']);
+const ALLOWED_MATCH_KINDS = new Set(['exact', 'prefix', 'glob']);
+const ALLOWED_UPDATE_POLICIES = new Set(PUBLIC_SURFACE_UPDATE_POLICIES);
+const FORBIDDEN_PATH_CLASSIFICATION_AUTHORITY_FIELDS = new Set([
+    'argv',
+    'cmd',
+    'run_policy',
+    'lifecycle',
+    'stdin',
+    'timeout_seconds',
+    'writes',
+    'network',
+    'destructive',
+    'required_after',
+    'skip_validation',
+    'status',
+    'intents',
+    'command_intents',
+    'commands',
+    'command',
+    'run',
+    'execute',
+    'action',
+    'actions',
+    'agent_action',
+    'agent_actions',
+]);
+function pushIssue(issues, code, pathLabel, message) {
+    issues.push({ code, path: pathLabel, message });
+}
+function isSafeRelativePath(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return false;
+    }
+    const normalized = value.replaceAll('\\', '/');
+    const segments = normalized.split('/').filter(Boolean);
+    if (path.posix.isAbsolute(normalized) || path.win32.isAbsolute(value)) {
+        return false;
+    }
+    return segments.length > 0 && segments.every((segment) => segment !== '.' && segment !== '..');
+}
+function validateStringArrayField(table, key, pathLabel, issues) {
+    if (!Object.hasOwn(table, key)) {
+        return;
+    }
+    const value = table[key];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)) {
+        pushIssue(issues, 'invalid_string_array', `${pathLabel}.${key}`, `${pathLabel}.${key} must be a string array`);
+    }
+}
+function validateForbiddenAuthorityFields(value, pathLabel, issues) {
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => validateForbiddenAuthorityFields(entry, `${pathLabel}[${index}]`, issues));
+        return;
+    }
+    if (!isRecord(value)) {
+        return;
+    }
+    for (const [key, nestedValue] of Object.entries(value)) {
+        const fieldPath = pathLabel ? `${pathLabel}.${key}` : key;
+        if (FORBIDDEN_PATH_CLASSIFICATION_AUTHORITY_FIELDS.has(key)) {
+            pushIssue(issues, 'command_authority_field', fieldPath, `${fieldPath} cannot define command authority; use .mustflow/config/commands.toml`);
+        }
+        validateForbiddenAuthorityFields(nestedValue, fieldPath, issues);
+    }
+}
+function validateMatchTable(match, pathLabel, issues) {
+    if (!isRecord(match)) {
+        pushIssue(issues, 'invalid_match', pathLabel, `${pathLabel} must be a TOML table`);
+        return;
+    }
+    for (const key of Object.keys(match)) {
+        if (!ALLOWED_MATCH_FIELDS.has(key)) {
+            pushIssue(issues, 'unknown_rule_field', `${pathLabel}.${key}`, `${pathLabel}.${key} is not allowed`);
+        }
+    }
+    if (!ALLOWED_MATCH_KINDS.has(String(match.kind))) {
+        pushIssue(issues, 'invalid_match_kind', `${pathLabel}.kind`, `${pathLabel}.kind must be "exact", "prefix", or "glob"; regular expressions are deferred`);
+    }
+    if (!isSafeRelativePath(match.path)) {
+        pushIssue(issues, 'invalid_match_path', `${pathLabel}.path`, `${pathLabel}.path must be a non-empty relative path inside the current root`);
+    }
+}
+function validatePathClassificationRule(rule, index, issues) {
+    const pathLabel = `rules[${index}]`;
+    if (!isRecord(rule)) {
+        pushIssue(issues, 'rule_not_table', pathLabel, `${pathLabel} must be a TOML table`);
+        return;
+    }
+    for (const key of Object.keys(rule)) {
+        if (!ALLOWED_RULE_FIELDS.has(key)) {
+            pushIssue(issues, 'unknown_rule_field', `${pathLabel}.${key}`, `${pathLabel}.${key} is not allowed`);
+        }
+    }
+    if (typeof rule.id !== 'string' || rule.id.trim().length === 0) {
+        pushIssue(issues, 'invalid_rule_id', `${pathLabel}.id`, `${pathLabel}.id must be a non-empty string`);
+    }
+    validateMatchTable(rule.match, `${pathLabel}.match`, issues);
+    validateStringArrayField(rule, 'change_kinds', pathLabel, issues);
+    validateStringArrayField(rule, 'validation_reasons', pathLabel, issues);
+    validateStringArrayField(rule, 'affected_contracts', pathLabel, issues);
+    validateStringArrayField(rule, 'drift_checks', pathLabel, issues);
+    if (Object.hasOwn(rule, 'is_public_surface') && typeof rule.is_public_surface !== 'boolean') {
+        pushIssue(issues, 'invalid_boolean', `${pathLabel}.is_public_surface`, `${pathLabel}.is_public_surface must be a boolean`);
+    }
+    if (Object.hasOwn(rule, 'update_policy') && !ALLOWED_UPDATE_POLICIES.has(String(rule.update_policy))) {
+        pushIssue(issues, 'invalid_update_policy', `${pathLabel}.update_policy`, `${pathLabel}.update_policy must be "update", "update_or_mark_stale", or "not_applicable"`);
+    }
+}
+function validatePathClassificationModelConfig(value) {
+    const issues = [];
+    if (!isRecord(value)) {
+        pushIssue(issues, 'root_not_table', '', 'must contain a TOML table');
+        return issues;
+    }
+    validateForbiddenAuthorityFields(value, '', issues);
+    for (const key of Object.keys(value)) {
+        if (!ALLOWED_TOP_LEVEL_FIELDS.has(key)) {
+            pushIssue(issues, 'unknown_top_level_field', key, `${key} is not allowed at the top level`);
+        }
+    }
+    if (Object.hasOwn(value, 'schema_version') && typeof value.schema_version !== 'string') {
+        pushIssue(issues, 'invalid_schema_version', 'schema_version', 'schema_version must be a string');
+    }
+    if (!Object.hasOwn(value, 'rules')) {
+        pushIssue(issues, 'missing_rules', 'rules', 'must define [[rules]]');
+        return issues;
+    }
+    const rules = value.rules;
+    if (!Array.isArray(rules) || rules.length === 0) {
+        pushIssue(issues, 'rules_not_array', 'rules', 'rules must be a non-empty array of TOML tables');
+        return issues;
+    }
+    rules.forEach((rule, index) => validatePathClassificationRule(rule, index, issues));
+    return issues;
+}
+export function validateCandidateContractModelConfig(model, value) {
+    if (model.status === 'deferred') {
+        return [
+            {
+                code: 'deferred_model_present',
+                path: model.filePath,
+                message: `${model.filePath} is deferred; use narrow candidate contract files instead`,
+            },
+        ];
+    }
+    if (!PATH_CLASSIFICATION_MODEL_IDS.has(model.id)) {
+        return [];
+    }
+    return validatePathClassificationModelConfig(value).map((issue) => ({
+        ...issue,
+        message: issue.path ? `${model.filePath} ${issue.message}` : `${model.filePath} ${issue.message}`,
+    }));
+}

package/dist/core/dashboard-verification.js

@@ -68,10 +68,16 @@ function createEmptyDashboardVerificationSnapshot(changedFiles) {
         skipped: [],
         schedule: {
             runner: 'serial_mf_run_receipts',
+            failurePolicy: {
+                mode: 'batch_boundary',
+                startedBatch: 'wait_for_completion',
+                nextBatch: 'stop_on_failure',
+            },
             batches: [],
             entries: [],
             notes: [],
         },
+        decision_graph: null,
     };
 }
 export function createDashboardVerificationSnapshot(projectRoot, rawCommandContract, commandIntents, changedFiles, manifestChangedFiles, manifestMissingFiles) {
@@ -103,6 +109,7 @@ export function createDashboardVerificationSnapshot(projectRoot, rawCommandContr
         skipped,
         schedule: {
             runner: verificationReport.schedule.runner,
+            failurePolicy: verificationReport.schedule.failurePolicy,
             batches: verificationReport.schedule.batches.map((batch) => ({
                 index: batch.index,
                 intents: batch.intents,
@@ -112,6 +119,8 @@ export function createDashboardVerificationSnapshot(projectRoot, rawCommandContr
             entries: verificationReport.schedule.entries.map((entry) => ({
                 intent: entry.intent,
                 command: `mf run ${entry.intent}`,
+                parallelEligible: entry.parallelEligible,
+                parallelReason: entry.parallelReason,
                 locks: entry.locks,
                 effects: entry.effects.map((effect) => ({
                     access: effect.access,
@@ -128,5 +137,6 @@ export function createDashboardVerificationSnapshot(projectRoot, rawCommandContr
             })),
             notes: verificationReport.schedule.notes,
         },
+        decision_graph: verificationReport.decision_graph,
     };
 }

package/dist/core/doc-review-triage.js

@@ -8,6 +8,7 @@ const P0_EXACT_PATHS = new Set([
 const AUTHORITY_OR_SECURITY_SKILLS = new Set([
     'contract-sync-check',
     'external-prompt-injection-defense',
+    'external-skill-intake',
     'instruction-conflict-scope-check',
     'migration-safety-check',
     'multi-agent-work-coordination',