mustflow 1.30.0 → 2.11.0

package/dist/core/contract-lint.js

@@ -1,8 +1,11 @@
+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 { evaluateCommandIntentEligibility, } from './command-intent-eligibility.js';
 import { commandIntentHasBlockedShellBackgroundPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
 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',
@@ -41,9 +44,20 @@ const RELEASE_SENSITIVE_REASONS = new Set([
     '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';
+const PACKAGE_SCRIPT_RUNNERS = new Set(['bun', 'npm', 'pnpm', 'yarn']);
+const MAKEFILE_CANDIDATES = ['Makefile', 'makefile'];
+const JUSTFILE_CANDIDATES = ['justfile', 'Justfile'];
 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;
@@ -56,6 +70,195 @@ function writesAreValid(intent) {
     const value = intent.writes;
     return value === undefined || (Array.isArray(value) && value.every((entry) => typeof entry === 'string'));
 }
+function readStringList(value) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        return null;
+    }
+    return [...value];
+}
+function normalizeCommandName(value) {
+    return path.basename(value).replace(/\.(?:cmd|exe)$/iu, '').toLowerCase();
+}
+function readPackageScriptReference(intent) {
+    const argv = readStringList(intent.argv);
+    if (!argv || argv.length < 3) {
+        return null;
+    }
+    const runner = normalizeCommandName(argv[0]);
+    if (!PACKAGE_SCRIPT_RUNNERS.has(runner) || argv[1] !== 'run') {
+        return null;
+    }
+    const scriptName = argv[2];
+    return scriptName && !scriptName.startsWith('-') ? scriptName : null;
+}
+function resolveIntentCwd(projectRoot, intent) {
+    const cwd = readString(intent, 'cwd') ?? '.';
+    const root = path.resolve(projectRoot);
+    const resolved = path.resolve(root, cwd);
+    if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+        return null;
+    }
+    return resolved;
+}
+function toProjectRelativePath(projectRoot, absolutePath) {
+    const relativePath = path.relative(projectRoot, absolutePath) || '.';
+    return relativePath.split(path.sep).join('/');
+}
+function readPackageScripts(projectRoot, intent) {
+    const intentCwd = resolveIntentCwd(projectRoot, intent);
+    if (!intentCwd) {
+        return null;
+    }
+    const packagePath = path.join(intentCwd, 'package.json');
+    if (!existsSync(packagePath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(packagePath, 'utf8'));
+        if (!isRecord(parsed) || !isRecord(parsed.scripts)) {
+            return {
+                relativePath: toProjectRelativePath(projectRoot, packagePath),
+                scripts: new Set(),
+            };
+        }
+        return {
+            relativePath: toProjectRelativePath(projectRoot, packagePath),
+            scripts: new Set(Object.keys(parsed.scripts)),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function readRootPackageScripts(projectRoot) {
+    const packagePath = path.join(projectRoot, 'package.json');
+    if (!existsSync(packagePath)) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(packagePath, 'utf8'));
+        if (!isRecord(parsed) || !isRecord(parsed.scripts)) {
+            return [];
+        }
+        return Object.entries(parsed.scripts)
+            .filter((entry) => typeof entry[1] === 'string')
+            .sort((left, right) => left[0].localeCompare(right[0]));
+    }
+    catch {
+        return [];
+    }
+}
+function readFirstExistingFile(projectRoot, candidates) {
+    for (const candidate of candidates) {
+        if (existsSync(path.join(projectRoot, candidate))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function readMakeTargets(projectRoot) {
+    const relativePath = readFirstExistingFile(projectRoot, MAKEFILE_CANDIDATES);
+    if (!relativePath) {
+        return [];
+    }
+    const content = readFileSync(path.join(projectRoot, relativePath), 'utf8');
+    const targets = [];
+    for (const line of content.split(/\r?\n/u)) {
+        if (/^\s/u.test(line) || line.startsWith('#') || line.includes(':=')) {
+            continue;
+        }
+        const match = /^([A-Za-z0-9][A-Za-z0-9_-]*)\s*:/u.exec(line);
+        if (match) {
+            targets.push(match[1]);
+        }
+    }
+    return uniqueSorted(targets);
+}
+function readJustRecipes(projectRoot) {
+    const relativePath = readFirstExistingFile(projectRoot, JUSTFILE_CANDIDATES);
+    if (!relativePath) {
+        return [];
+    }
+    const content = readFileSync(path.join(projectRoot, relativePath), 'utf8');
+    const recipes = [];
+    for (const line of content.split(/\r?\n/u)) {
+        if (/^\s/u.test(line) || line.startsWith('#') || line.startsWith('set ') || line.includes(' := ')) {
+            continue;
+        }
+        const match = /^([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s+[^:]*)?:\s*(?:#.*)?$/u.exec(line);
+        if (match) {
+            recipes.push(match[1]);
+        }
+    }
+    return uniqueSorted(recipes);
+}
+function toTomlString(value) {
+    return JSON.stringify(value);
+}
+function normalizeIntentSegment(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '_')
+        .replace(/^_+|_+$/gu, '');
+}
+function uniqueSuggestionIntentName(baseName, usedIntentNames) {
+    let candidate = baseName;
+    let suffix = 2;
+    while (usedIntentNames.has(candidate)) {
+        candidate = `${baseName}_${suffix}`;
+        suffix += 1;
+    }
+    usedIntentNames.add(candidate);
+    return candidate;
+}
+function createUnknownIntentSnippet(intentName, description, reason) {
+    return [
+        `[intents.${intentName}]`,
+        'status = "unknown"',
+        `description = ${toTomlString(description)}`,
+        `reason = ${toTomlString(reason)}`,
+        'agent_action = "review_and_configure_before_run"',
+    ].join('\n');
+}
+function createSuggestion(usedIntentNames, sourceFile, sourceKind, sourceName, commandHint) {
+    const sourcePrefix = sourceKind.replace(/_script$/u, '').replace(/_target$/u, '').replace(/_recipe$/u, '');
+    const intentName = uniqueSuggestionIntentName(`suggest_${sourcePrefix}_${normalizeIntentSegment(sourceName) || 'command'}`, usedIntentNames);
+    const reason = `Suggested from ${sourceFile} entry "${sourceName}". Review before adding runnable command fields.`;
+    const description = `Review ${commandHint} for a possible command intent.`;
+    return {
+        sourceFile,
+        sourceKind,
+        sourceName,
+        commandHint,
+        suggestedIntent: intentName,
+        status: 'unknown',
+        reason,
+        snippet: createUnknownIntentSnippet(intentName, description, reason),
+    };
+}
+function suggestCommandContracts(projectRoot, existingIntentNames) {
+    if (!projectRoot) {
+        return [];
+    }
+    const usedIntentNames = new Set(existingIntentNames);
+    const suggestions = [];
+    for (const [scriptName] of readRootPackageScripts(projectRoot)) {
+        suggestions.push(createSuggestion(usedIntentNames, 'package.json', 'package_script', scriptName, `npm run ${scriptName}`));
+    }
+    const makefilePath = readFirstExistingFile(projectRoot, MAKEFILE_CANDIDATES);
+    if (makefilePath) {
+        for (const target of readMakeTargets(projectRoot)) {
+            suggestions.push(createSuggestion(usedIntentNames, makefilePath, 'make_target', target, `make ${target}`));
+        }
+    }
+    const justfilePath = readFirstExistingFile(projectRoot, JUSTFILE_CANDIDATES);
+    if (justfilePath) {
+        for (const recipe of readJustRecipes(projectRoot)) {
+            suggestions.push(createSuggestion(usedIntentNames, justfilePath, 'just_recipe', recipe, `just ${recipe}`));
+        }
+    }
+    return suggestions;
+}
 function pushIssue(issues, severity, code, intent, message) {
     issues.push({ severity, code, intent, message });
 }
@@ -132,6 +335,25 @@ function lintIntent(name, value, issues) {
     }
     return value;
 }
+function lintReferencedPackageScripts(projectRoot, intents, issues) {
+    if (!projectRoot) {
+        return;
+    }
+    for (const [name, intent] of intents) {
+        if (readString(intent, 'status') !== 'configured') {
+            continue;
+        }
+        const scriptName = readPackageScriptReference(intent);
+        if (!scriptName) {
+            continue;
+        }
+        const packageScripts = readPackageScripts(projectRoot, intent);
+        if (!packageScripts || packageScripts.scripts.has(scriptName)) {
+            continue;
+        }
+        pushIssue(issues, 'warning', 'referenced_package_script_missing', name, `Intent ${name} references package script "${scriptName}" in ${packageScripts.relativePath}, but that script is not declared.`);
+    }
+}
 function collectRequiredAfterReasons(contract) {
     const reasonToIntents = new Map();
     for (const [name, intent] of Object.entries(contract.intents)) {
@@ -151,6 +373,87 @@ function collectRequiredAfterReasons(contract) {
     }
     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));
 }
@@ -200,6 +503,7 @@ function lintCoverage(contract, options, issues) {
     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))
@@ -236,6 +540,7 @@ function lintCoverage(contract, options, issues) {
         documentedVerificationReasons,
         requiredAfterReasons,
         runnableReasons,
+        matrix: buildCoverageMatrix(reasonToIntents, knownClassificationReasons, documentedVerificationReasons, skillPathsByIntent),
         findings,
     };
 }
@@ -249,24 +554,28 @@ 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);
+        .map(([name, value]) => [name, lintIntent(name, value, issues)])
+        .filter((entry) => entry[1] !== null);
+    lintReferencedPackageScripts(options.projectRoot, intentTables, issues);
+    const validIntents = intentTables.map(([, intent]) => intent);
     const coverage = options.coverage === true ? lintCoverage(contract, options, issues) : undefined;
+    const suggestions = options.suggest === true ? suggestCommandContracts(options.projectRoot, intentEntries.map(([name]) => name)) : undefined;
     const errors = issues.filter((issue) => issue.severity === 'error').length;
     const warnings = issues.length - errors;
     return {
         status: getStatus(errors, warnings),
         summary: {
             totalIntents: intentEntries.length,
-            configured: intentTables.filter((intent) => readString(intent, 'status') === 'configured').length,
-            runnable: intentTables.filter(configuredIntentIsRunnable).length,
-            manualOnly: intentTables.filter((intent) => readString(intent, 'status') === 'manual_only').length,
-            unknown: intentTables.filter((intent) => readString(intent, 'status') === 'unknown').length,
+            configured: validIntents.filter((intent) => readString(intent, 'status') === 'configured').length,
+            runnable: validIntents.filter(configuredIntentIsRunnable).length,
+            manualOnly: validIntents.filter((intent) => readString(intent, 'status') === 'manual_only').length,
+            unknown: validIntents.filter((intent) => readString(intent, 'status') === 'unknown').length,
             errors,
             warnings,
         },
         issues,
         sourceFiles: CONTRACT_LINT_SOURCE_FILES,
         coverage,
+        suggestions,
     };
 }

package/dist/core/dashboard-verification.js

@@ -68,6 +68,11 @@ 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: [],
@@ -104,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,
@@ -113,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,

package/dist/core/external-evidence.js

@@ -0,0 +1,9 @@
+export function createExternalEvidenceRisks(checks) {
+    return checks
+        .filter((check) => check.status !== 'passed')
+        .map((check) => ({
+        code: 'external_evidence_requires_review',
+        severity: 'medium',
+        detail: `External ${check.provider} check ${check.name} reported ${check.status}; review it as supporting evidence, not command authority.`,
+    }));
+}

package/dist/core/public-json-contracts.js

@@ -38,6 +38,13 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         packaged: true,
         documented: true,
     },
+    {
+        id: 'test-selection',
+        schemaFile: 'test-selection.schema.json',
+        producer: 'parsed .mustflow/config/test-selection.toml',
+        packaged: true,
+        documented: true,
+    },
     {
         id: 'contract-lint-report',
         schemaFile: 'contract-lint-report.schema.json',
@@ -46,6 +53,13 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         documented: true,
         installedCommand: ['mf', 'contract-lint', '--json'],
     },
+    {
+        id: 'dashboard-export',
+        schemaFile: 'dashboard-export.schema.json',
+        producer: 'mf dashboard --export-json <path>',
+        packaged: true,
+        documented: true,
+    },
     {
         id: 'classify-report',
         schemaFile: 'classify-report.schema.json',
@@ -71,6 +85,13 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         installedCommand: ['mf', 'line-endings', 'check', '--json'],
         expectedExitCodes: [0, 1],
     },
+    {
+        id: 'latest-run-pointer',
+        schemaFile: 'latest-run-pointer.schema.json',
+        producer: '.mustflow/state/runs/latest.json when written by mf verify',
+        packaged: true,
+        documented: true,
+    },
     {
         id: 'handoff-validation-report',
         schemaFile: 'handoff-validation-report.schema.json',
@@ -111,6 +132,13 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         documented: true,
         installedCommand: ['mf', 'verify', '--reason', 'schema_verify', '--json'],
     },
+    {
+        id: 'verify-run-manifest',
+        schemaFile: 'verify-run-manifest.schema.json',
+        producer: '.mustflow/state/runs/verify-latest/manifest.json',
+        packaged: true,
+        documented: true,
+    },
     {
         id: 'change-verification-report',
         schemaFile: 'change-verification-report.schema.json',

package/dist/core/repeated-failure.js

@@ -0,0 +1,17 @@
+const UNRESOLVED_VERIFY_STATUSES = new Set(['failed', 'blocked', 'partial']);
+export function createRepeatedFailureRisk(input) {
+    if (input.previousVerificationPlanId === null ||
+        input.previousStatus === null ||
+        input.previousVerificationPlanId !== input.currentVerificationPlanId ||
+        !UNRESOLVED_VERIFY_STATUSES.has(input.previousStatus) ||
+        !UNRESOLVED_VERIFY_STATUSES.has(input.currentStatus)) {
+        return null;
+    }
+    return {
+        code: 'repeated_verification_failure',
+        severity: 'high',
+        previous_status: input.previousStatus,
+        verification_plan_id: input.currentVerificationPlanId,
+        detail: 'The previous verify summary has the same verification_plan_id and an unresolved status; provide new evidence or a narrower hypothesis before marking the task complete.',
+    };
+}

package/dist/core/repro-evidence.js

@@ -0,0 +1,53 @@
+const TEXT_FIELD_LABELS = {
+    reported_symptom: 'reported symptom',
+    expected_behavior: 'expected behavior',
+    observed_behavior: 'observed behavior',
+};
+const ITEM_FIELD_LABELS = {
+    original_reproduction: 'original reproduction path',
+    evidence_before_fix: 'before-fix evidence',
+    evidence_after_fix: 'after-fix evidence',
+    regression_guard: 'regression guard',
+};
+export function createReproEvidenceRisks(report) {
+    if (!report) {
+        return [];
+    }
+    const risks = [];
+    for (const [field, label] of Object.entries(TEXT_FIELD_LABELS)) {
+        if (!report[field]) {
+            risks.push({
+                code: 'repro_evidence_missing',
+                severity: 'high',
+                detail: `Bug-fix repro evidence is missing ${label}; do not mark the task verified from command receipts alone.`,
+            });
+        }
+    }
+    for (const [field, label] of Object.entries(ITEM_FIELD_LABELS)) {
+        const item = report[field];
+        if (item.status === 'missing') {
+            risks.push({
+                code: 'repro_evidence_missing',
+                severity: 'high',
+                detail: `Bug-fix repro evidence is missing ${label}; rerun or explicitly mark it unavailable before claiming verification.`,
+            });
+            continue;
+        }
+        if (item.status === 'present' && !item.summary) {
+            risks.push({
+                code: 'repro_evidence_missing',
+                severity: 'high',
+                detail: `Bug-fix repro evidence marks ${label} present but does not summarize the evidence.`,
+            });
+            continue;
+        }
+        if (item.status === 'unavailable' && !item.reason) {
+            risks.push({
+                code: 'repro_evidence_missing',
+                severity: 'high',
+                detail: `Bug-fix repro evidence marks ${label} unavailable without explaining why.`,
+            });
+        }
+    }
+    return risks;
+}