mustflow 1.18.16 → 1.31.0

package/dist/cli/commands/explain-verify.js

@@ -0,0 +1,213 @@
+import { explainCommandIntent } from '../../core/command-explanation.js';
+import { readCommandContract } from '../../core/config-loading.js';
+import { createVerificationDecisionGraph, } from '../../core/verification-decision-graph.js';
+import { createVerificationPlan, } from '../../core/verification-plan.js';
+import { createVerificationSchedule } from '../../core/verification-scheduler.js';
+import { t } from '../lib/i18n.js';
+import { readLocalCommandEffectGraphs, } from '../lib/local-index.js';
+import { planErrorMessageKey, readInputFromPlan } from './verify.js';
+export function parseExplainVerifyArgs(args) {
+    let reason;
+    let fromPlan;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--reason') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('-')) {
+                return { reason, fromPlan, error: 'missing_reason_value' };
+            }
+            reason = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--from-plan') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('-')) {
+                return { reason, fromPlan, error: 'missing_from_plan_value' };
+            }
+            fromPlan = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--reason=')) {
+            const value = arg.slice('--reason='.length);
+            if (value.length === 0) {
+                return { reason, fromPlan, error: 'missing_reason_value' };
+            }
+            reason = value;
+            continue;
+        }
+        if (arg.startsWith('--from-plan=')) {
+            const value = arg.slice('--from-plan='.length);
+            if (value.length === 0) {
+                return { reason, fromPlan, error: 'missing_from_plan_value' };
+            }
+            fromPlan = value;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            return { reason, fromPlan, error: arg };
+        }
+        return { reason, fromPlan, error: `unexpected:${arg}` };
+    }
+    return { reason, fromPlan };
+}
+export function explainVerifyArgErrorMessage(error, lang) {
+    if (error === 'missing_reason_value') {
+        return t(lang, 'cli.error.missingValue', { option: '--reason' });
+    }
+    if (error === 'missing_from_plan_value') {
+        return t(lang, 'cli.error.missingValue', { option: '--from-plan' });
+    }
+    if (error.startsWith('unexpected:')) {
+        return t(lang, 'cli.error.unexpectedArgument', { argument: error.slice('unexpected:'.length) });
+    }
+    return t(lang, 'cli.error.unknownOption', { option: error });
+}
+export function explainVerifyPlanErrorMessage(error, lang) {
+    const code = error instanceof Error ? error.message : 'invalid_plan_file';
+    return t(lang, planErrorMessageKey(code));
+}
+export function readExplainVerifyPlanReasons(projectRoot, planPath) {
+    return readInputFromPlan(projectRoot, planPath).reasons;
+}
+export async function getVerifyExplainOutput(schemaVersion, projectRoot, reasons, inputReason, planSource) {
+    const contract = readCommandContract(projectRoot);
+    const plans = reasons.map((reason) => createVerificationPlan(contract, reason));
+    const graphRequirements = reasons.map((reason) => ({
+        reason,
+        files: [],
+        surfaces: [],
+        affectedContracts: [],
+        driftChecks: [],
+        updatePolicies: [],
+        source: 'change_classification',
+    }));
+    const graphCandidates = plans.flatMap((plan) => plan.candidates.map((candidate) => ({
+        reason: plan.reason,
+        intent: candidate.intent.length > 0 ? candidate.intent : null,
+        status: candidate.status,
+        skipReason: candidate.reason,
+        detail: candidate.detail,
+    })));
+    const graphGaps = graphRequirements
+        .filter((requirement) => graphCandidates.every((candidate) => candidate.reason !== requirement.reason || candidate.status !== 'runnable'))
+        .map((requirement) => ({
+        reason: requirement.reason,
+        files: requirement.files,
+        surfaces: requirement.surfaces,
+        detail: `No runnable command intents cover required_after = "${requirement.reason}".`,
+    }));
+    const schedule = createVerificationSchedule(projectRoot, contract, plans.flatMap((plan) => plan.candidates));
+    const decisionGraph = createVerificationDecisionGraph(contract, graphRequirements, graphCandidates, graphGaps, schedule);
+    const intentNames = [
+        ...new Set(plans.flatMap((plan) => plan.candidates.map((candidate) => candidate.intent).filter((intent) => intent.length > 0))),
+    ];
+    const graphsByIntent = intentNames.length > 0 ? await readLocalCommandEffectGraphs(projectRoot, intentNames) : new Map();
+    const requirements = plans.map((plan) => {
+        const candidates = plan.candidates.map((candidate) => {
+            const command = candidate.intent ? explainCommandIntent(contract, candidate.intent).intent : null;
+            return {
+                intent: candidate.intent.length > 0 ? candidate.intent : null,
+                status: candidate.status,
+                skipReason: candidate.reason,
+                detail: candidate.detail,
+                requiredAfter: command?.requiredAfter ?? [],
+                command,
+                effectGraph: candidate.intent ? graphsByIntent.get(candidate.intent) ?? null : null,
+            };
+        });
+        const matchingIntents = candidates
+            .map((candidate) => candidate.intent)
+            .filter((intent) => intent !== null)
+            .sort((left, right) => left.localeCompare(right));
+        const hasRunnableCandidate = candidates.some((candidate) => candidate.status === 'runnable');
+        return {
+            reason: plan.reason,
+            matchingIntents,
+            candidates,
+            gap: hasRunnableCandidate ? null : `No runnable command intents cover required_after = "${plan.reason}".`,
+        };
+    });
+    const allCandidates = requirements.flatMap((requirement) => requirement.candidates);
+    const runnableCount = allCandidates.filter((candidate) => candidate.status === 'runnable').length;
+    const skippedCount = allCandidates.filter((candidate) => candidate.status === 'skipped').length;
+    const reasonLabel = reasons.join(', ');
+    return {
+        schema_version: schemaVersion,
+        command: 'explain',
+        topic: 'verify',
+        mustflow_root: projectRoot,
+        decision: {
+            kind: 'verify',
+            input: {
+                reason: inputReason,
+                planSource,
+            },
+            decision: runnableCount > 0
+                ? `verification reason "${reasonLabel}" has ${runnableCount} runnable candidate(s)`
+                : `verification reason "${reasonLabel}" has no runnable candidates`,
+            reason: 'verify explanations reuse required_after matching and the same command eligibility rules used by mf run and mf verify.',
+            effectiveAction: runnableCount > 0
+                ? 'Use mf verify when you need execution receipts; this explanation only shows the selected verification candidates.'
+                : 'Do not guess a command; report the skipped candidate reasons or add a configured command intent.',
+            countsAsMustflowVerification: false,
+            sourceFiles: [
+                '.mustflow/config/commands.toml',
+                '.mustflow/docs/agent-workflow.md',
+                'src/core/verification-plan.ts',
+                'src/core/command-intent-eligibility.ts',
+            ],
+            verification: {
+                planSource,
+                reasons,
+                candidateCount: allCandidates.length,
+                runnableCount,
+                skippedCount,
+                requirements,
+                decisionGraph,
+            },
+        },
+    };
+}
+export function renderVerifyExplainDecision(decision, lang) {
+    const verification = decision.verification;
+    const lines = [
+        '',
+        'Verification explanation',
+        `- plan_source: ${verification.planSource ?? t(lang, 'value.none')}`,
+        `- reasons: ${verification.reasons.join(', ') || t(lang, 'value.none')}`,
+        `- candidates: ${verification.candidateCount}`,
+        `- runnable: ${verification.runnableCount}`,
+        `- skipped: ${verification.skippedCount}`,
+        `- decision_graph_nodes: ${verification.decisionGraph.summary.nodeCount}`,
+        `- decision_graph_gaps: ${verification.decisionGraph.summary.gapCount}`,
+    ];
+    for (const requirement of verification.requirements) {
+        lines.push(`- required_after: ${requirement.reason}`);
+        if (requirement.matchingIntents.length > 0) {
+            lines.push(`  matching_intents: ${requirement.matchingIntents.join(', ')}`);
+        }
+        if (requirement.gap) {
+            lines.push(`  gap: ${requirement.gap}`);
+        }
+        for (const candidate of requirement.candidates) {
+            const intent = candidate.intent ?? t(lang, 'value.none');
+            const reason = candidate.skipReason ? ` (${candidate.skipReason})` : '';
+            lines.push(`  - ${intent}: ${candidate.status}${reason}`);
+            if (candidate.detail) {
+                lines.push(`    detail: ${candidate.detail}`);
+            }
+            if (candidate.requiredAfter.length > 0) {
+                lines.push(`    required_after: ${candidate.requiredAfter.join(', ')}`);
+            }
+            if (candidate.effectGraph) {
+                lines.push(`    effect_graph: ${candidate.effectGraph.status}`, `    index_fresh: ${candidate.effectGraph.indexFresh ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
+                if (candidate.effectGraph.refreshHint) {
+                    lines.push(`    refresh_hint: ${candidate.effectGraph.refreshHint}`);
+                }
+            }
+        }
+    }
+    return lines;
+}

package/dist/cli/commands/explain.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 { explainAssetOptimization, explainCommandIntent } from '../../core/command-explanation.js';
+import { explainAssetOptimization, explainCommandIntent, } from '../../core/command-explanation.js';
 import { readCommandContract, readMustflowConfigIfExists } from '../../core/config-loading.js';
 import { explainManagedMarkdownAuthority, } from '../../core/authority-resolution.js';
 import { explainRetentionPolicy } from '../../core/retention-explanation.js';
@@ -11,10 +11,11 @@ import { explainPublicSurface } from '../../core/public-surface-explanation.js';
 import { explainSourceAnchor } from '../../core/source-anchor-explanation.js';
 import { checkMustflowProject } from '../lib/validation.js';
 import { readLocalCommandEffectGraph, readLocalPathSurface, } from '../lib/local-index.js';
+import { explainVerifyArgErrorMessage, explainVerifyPlanErrorMessage, getVerifyExplainOutput, parseExplainVerifyArgs, readExplainVerifyPlanReasons, renderVerifyExplainDecision, } from './explain-verify.js';
 const EXPLAIN_SCHEMA_VERSION = '1';
 export function getExplainHelp(lang = 'en') {
     return renderHelp({
-        usage: 'mf explain <topic> [target] [options]',
+        usage: 'mf explain <topic> [target] [options] | mf explain verify --reason <event> [options] | mf explain verify --from-plan <path> [options]',
         summary: t(lang, 'explain.help.summary'),
         options: [
             { label: '--json', description: t(lang, 'cli.option.json') },
@@ -31,6 +32,8 @@ export function getExplainHelp(lang = 'en') {
             'mf explain command lint --json',
             'mf explain retention',
             'mf explain retention --json',
+            'mf explain verify --reason code_change',
+            'mf explain verify --from-plan verify-plan.json --json',
             'mf explain skill code-review',
             'mf explain skill mustflow.core.code-review --json',
             'mf explain skills',
@@ -146,6 +149,9 @@ function renderExplainDecision(output, lang) {
     if ('expectation' in output.decision && output.decision.expectation) {
         lines.push('', t(lang, 'explain.label.expectedFrontmatter'), `- mustflow_doc: ${output.decision.expectation.docId}`, `- authority: ${output.decision.expectation.authority}`, `- lifecycle: ${output.decision.expectation.lifecycle}`);
     }
+    if ('verification' in output.decision) {
+        lines.push(...renderVerifyExplainDecision(output.decision, lang));
+    }
     if ('boundary' in output.decision) {
         lines.push('', t(lang, 'explain.label.authorityBoundary'), `- role: ${output.decision.boundary.role}`);
         if (output.decision.boundary.canDefine.length > 0) {
@@ -246,13 +252,51 @@ export async function runExplain(args, reporter, lang = 'en') {
         return 0;
     }
     const json = args.includes('--json');
+    const positional = args.filter((arg) => arg !== '--json');
+    const [topic, targetArg, ...rest] = positional;
+    if (topic === 'verify') {
+        const verifyArgs = targetArg === undefined ? rest : [targetArg, ...rest];
+        const parsed = parseExplainVerifyArgs(verifyArgs);
+        if (parsed.error) {
+            printUsageError(reporter, explainVerifyArgErrorMessage(parsed.error, lang), 'mf explain --help', getExplainHelp(lang), lang);
+            return 1;
+        }
+        const selectedInputCount = [parsed.reason, parsed.fromPlan].filter(Boolean).length;
+        if (selectedInputCount > 1) {
+            printUsageError(reporter, t(lang, 'verify.error.conflictingInputs'), 'mf explain --help', getExplainHelp(lang), lang);
+            return 1;
+        }
+        if (selectedInputCount === 0) {
+            printUsageError(reporter, t(lang, 'verify.error.missingReason'), 'mf explain --help', getExplainHelp(lang), lang);
+            return 1;
+        }
+        const projectRoot = resolveMustflowRoot();
+        let output;
+        try {
+            if (parsed.fromPlan) {
+                const reasons = readExplainVerifyPlanReasons(projectRoot, parsed.fromPlan);
+                output = await getVerifyExplainOutput(EXPLAIN_SCHEMA_VERSION, projectRoot, reasons, null, parsed.fromPlan);
+            }
+            else {
+                output = await getVerifyExplainOutput(EXPLAIN_SCHEMA_VERSION, projectRoot, [parsed.reason], parsed.reason, null);
+            }
+        }
+        catch (error) {
+            printUsageError(reporter, explainVerifyPlanErrorMessage(error, lang), 'mf explain --help', getExplainHelp(lang), lang);
+            return 1;
+        }
+        if (json) {
+            reporter.stdout(JSON.stringify(output, null, 2));
+            return 0;
+        }
+        reporter.stdout(renderExplainDecision(output, lang));
+        return 0;
+    }
     const unsupported = args.filter((arg) => arg.startsWith('-') && arg !== '--json');
     if (unsupported.length > 0) {
         printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf explain --help', getExplainHelp(lang), lang);
         return 1;
     }
-    const positional = args.filter((arg) => arg !== '--json');
-    const [topic, targetArg, ...rest] = positional;
     if (topic !== 'asset-optimization' &&
         topic !== 'anchor' &&
         topic !== 'authority' &&

package/dist/cli/commands/handoff.js

@@ -0,0 +1,136 @@
+import { lstatSync } from 'node:fs';
+import path from 'node:path';
+import { MAX_HANDOFF_RECORD_BYTES, validateHandoffRecordJson, } from '../../core/handoff-record.js';
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { ensureInsideWithoutSymlinks, readUtf8FileInsideWithoutSymlinks } from '../lib/filesystem.js';
+import { t } from '../lib/i18n.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+export function getHandoffHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf handoff validate <path> [options]',
+        summary: t(lang, 'handoff.help.summary'),
+        options: [
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf handoff validate .mustflow/work-items/MF-0001.json',
+            'mf handoff validate .mustflow/work-items/MF-0001.json --json',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'handoff.help.exit.ok') },
+            { label: '1', description: t(lang, 'handoff.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseHandoffArgs(args, lang) {
+    const [action, ...rest] = args;
+    let json = false;
+    let recordPath;
+    if (!action) {
+        return { action: 'validate', json, error: t(lang, 'handoff.error.missingAction') };
+    }
+    if (action !== 'validate') {
+        return { action: 'validate', json, error: t(lang, 'handoff.error.unknownAction', { action }) };
+    }
+    for (const arg of rest) {
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            return { action, path: recordPath, json, error: t(lang, 'cli.error.unknownOption', { option: arg }) };
+        }
+        if (recordPath) {
+            return { action, path: recordPath, json, error: t(lang, 'cli.error.unexpectedArgument', { argument: arg }) };
+        }
+        recordPath = arg;
+    }
+    if (!recordPath) {
+        return { action, json, error: t(lang, 'handoff.error.missingPath') };
+    }
+    return { action, path: recordPath, json };
+}
+function createReadFailureReport(mustflowRoot, recordPath, code, message) {
+    return {
+        schema_version: '1',
+        command: 'handoff_validate',
+        ok: false,
+        mustflow_root: mustflowRoot,
+        path: recordPath,
+        record_kind: null,
+        task_id: null,
+        summary: {
+            scope_count: 0,
+            acceptance_criteria_count: 0,
+            source_ref_count: 0,
+            verification_plan_count: 0,
+            coverage_count: 0,
+            remaining_risk_count: 0,
+        },
+        issues: [{ severity: 'error', code, path: '$', message }],
+    };
+}
+function toRelativePosixPath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).split(path.sep).join('/');
+}
+function renderHandoffReport(report, lang) {
+    const lines = [
+        t(lang, 'handoff.title'),
+        `${t(lang, 'label.mustflowRoot')}: ${report.mustflow_root}`,
+        `${t(lang, 'handoff.label.path')}: ${report.path}`,
+        `${t(lang, 'handoff.label.status')}: ${report.ok ? t(lang, 'handoff.value.valid') : t(lang, 'handoff.value.invalid')}`,
+        `${t(lang, 'handoff.label.kind')}: ${report.record_kind ?? t(lang, 'value.none')}`,
+        `${t(lang, 'handoff.label.task')}: ${report.task_id ?? t(lang, 'value.none')}`,
+        `${t(lang, 'handoff.label.issues')}: ${report.issues.length}`,
+    ];
+    if (report.issues.length > 0) {
+        lines.push('', t(lang, 'handoff.label.issues'));
+        for (const issue of report.issues) {
+            lines.push(`- [${issue.severity}] ${issue.code} ${issue.path}: ${issue.message}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function runHandoff(args, reporter, lang = 'en') {
+    const helpText = getHandoffHelp(lang);
+    if (args.includes('--help') || args.includes('-h')) {
+        reporter.stdout(helpText);
+        return 0;
+    }
+    const options = parseHandoffArgs(args, lang);
+    if (options.error || !options.path) {
+        printUsageError(reporter, options.error ?? t(lang, 'handoff.error.missingPath'), 'mf handoff --help', helpText, lang);
+        return 1;
+    }
+    const mustflowRoot = resolveMustflowRoot();
+    const recordPath = path.resolve(mustflowRoot, options.path);
+    let report;
+    try {
+        ensureInsideWithoutSymlinks(mustflowRoot, recordPath);
+        const stats = lstatSync(recordPath);
+        if (!stats.isFile()) {
+            report = createReadFailureReport(mustflowRoot, toRelativePosixPath(mustflowRoot, recordPath), 'record_not_regular_file', t(lang, 'handoff.error.notFile'));
+        }
+        else if (stats.size > MAX_HANDOFF_RECORD_BYTES) {
+            report = createReadFailureReport(mustflowRoot, toRelativePosixPath(mustflowRoot, recordPath), 'record_too_large', t(lang, 'handoff.error.tooLarge'));
+        }
+        else {
+            const content = readUtf8FileInsideWithoutSymlinks(mustflowRoot, recordPath);
+            report = validateHandoffRecordJson(content, {
+                mustflowRoot,
+                path: toRelativePosixPath(mustflowRoot, recordPath),
+            });
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        report = createReadFailureReport(mustflowRoot, options.path, 'record_unreadable', t(lang, 'handoff.error.unreadable', { message }));
+    }
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderHandoffReport(report, lang));
+    return report.ok ? 0 : 1;
+}