mustflow 1.30.0 → 2.11.0

package/dist/core/verification-evidence.js

@@ -0,0 +1,249 @@
+function uniqueSorted(values) {
+    return [...new Set([...values].filter((value) => typeof value === 'string' && value.length > 0))].sort((left, right) => left.localeCompare(right));
+}
+function receiptEntries(results) {
+    return results
+        .filter((result) => !result.skipped)
+        .map((result) => ({
+        intent: result.intent,
+        status: result.status,
+        skipped: false,
+        verification_plan_id: result.verification_plan_id,
+        receipt_path: result.receipt_path,
+        receipt_sha256: result.receipt_sha256,
+    }));
+}
+function skippedCheckEntries(results) {
+    return results
+        .filter((result) => result.skipped)
+        .map((result) => ({
+        intent: result.intent,
+        reason: result.reason,
+        detail: result.detail,
+    }));
+}
+function resultForIntent(results, intent) {
+    return results.find((result) => result.intent === intent && !result.skipped) ?? null;
+}
+function requirementOutcome(input) {
+    if (input.selectedIntents.some((intent) => {
+        const result = resultForIntent(input.results, intent);
+        return result?.status === 'failed' || result?.status === 'timed_out' || result?.status === 'start_failed';
+    })) {
+        return 'contradicted';
+    }
+    if (input.gapCount > 0 || (input.selectedIntents.length === 0 && input.skippedIntents.length > 0)) {
+        return 'blocked';
+    }
+    if (input.selectedIntents.length === 0) {
+        return 'unverified';
+    }
+    if (input.skippedIntents.length > 0) {
+        return 'partially_verified';
+    }
+    return input.selectedIntents.every((intent) => resultForIntent(input.results, intent)?.status === 'passed')
+        ? 'verified'
+        : 'unverified';
+}
+function explanationFromVerdict(verdict) {
+    return {
+        verified_by: verdict.status === 'verified' ? [verdict.primary_reason] : [],
+        downgraded_by: verdict.status === 'partially_verified' || verdict.status === 'unverified' ? verdict.limitations : [],
+        blocked_by: verdict.status === 'blocked' ? verdict.blockers : [],
+        contradicted_by: verdict.status === 'contradicted' ? verdict.contradictions : [],
+    };
+}
+function coverageStatusFromOutcome(outcome) {
+    if (outcome === 'verified') {
+        return 'covered';
+    }
+    if (outcome === 'partially_verified') {
+        return 'partially_covered';
+    }
+    if (outcome === 'unverified') {
+        return 'uncovered';
+    }
+    return outcome;
+}
+function receiptPathsForIntents(receipts, intents) {
+    const selected = new Set(intents);
+    return uniqueSorted(receipts
+        .filter((receipt) => receipt.intent !== null && selected.has(receipt.intent))
+        .map((receipt) => receipt.receipt_path));
+}
+function coverageMatrixFromRequirements(input) {
+    return input.requirements.map((requirement, index) => {
+        const matchingGaps = input.source === 'dashboard_snapshot'
+            ? input.gaps
+            : input.gaps.filter((gap) => gap.reason === requirement.reason);
+        const matchingSourceAnchorRisks = input.sourceAnchorRisks.filter((risk) => requirement.files.includes(risk.path));
+        const status = coverageStatusFromOutcome(requirement.outcome);
+        return {
+            criterion_id: `${input.source}:${index + 1}:${requirement.reason}`,
+            source: input.source,
+            statement: `Verification requirement: ${requirement.reason}`,
+            status: matchingSourceAnchorRisks.length > 0 && status === 'covered' ? 'partially_covered' : status,
+            requirement_reason: requirement.reason,
+            evidence: {
+                intents: uniqueSorted([...requirement.selected_intents, ...requirement.skipped_intents]),
+                receipt_paths: receiptPathsForIntents(input.receipts, requirement.selected_intents),
+                gap_reasons: uniqueSorted(matchingGaps.map((gap) => gap.detail)),
+                source_anchor_ids: uniqueSorted(matchingSourceAnchorRisks.map((risk) => risk.anchorId)),
+            },
+        };
+    });
+}
+function sourceAnchorRemainingRisks(sourceAnchorRisks) {
+    return sourceAnchorRisks.map((risk) => ({
+        code: 'source_anchor_invariant_review_required',
+        severity: 'high',
+        detail: `${risk.anchorId} in ${risk.path}:${risk.lineStart} is ${risk.status}; review its invariant before marking the task verified.`,
+    }));
+}
+function scopeDiffRemainingRisks(scopeDiffRisks) {
+    return scopeDiffRisks.map((risk) => ({
+        code: risk.code,
+        severity: risk.severity,
+        detail: risk.detail,
+    }));
+}
+function repeatedFailureRemainingRisks(repeatedFailureRisks) {
+    return repeatedFailureRisks.map((risk) => ({
+        code: risk.code,
+        severity: risk.severity,
+        detail: risk.detail,
+    }));
+}
+function validationRatchetRemainingRisks(validationRatchetRisks) {
+    return validationRatchetRisks.map((risk) => ({
+        code: risk.code,
+        severity: risk.severity,
+        detail: risk.detail,
+    }));
+}
+function reproEvidenceRemainingRisks(reproEvidenceRisks) {
+    return reproEvidenceRisks.map((risk) => ({
+        code: risk.code,
+        severity: risk.severity,
+        detail: risk.detail,
+    }));
+}
+function externalEvidenceRemainingRisks(externalEvidenceRisks) {
+    return externalEvidenceRisks.map((risk) => ({
+        code: risk.code,
+        severity: risk.severity,
+        detail: risk.detail,
+    }));
+}
+export function createVerifyEvidenceModel(input) {
+    const requirements = input.report.requirements.map((requirement) => {
+        const candidates = input.report.candidates.filter((candidate) => candidate.reason === requirement.reason);
+        const selectedIntents = uniqueSorted(candidates
+            .filter((candidate) => candidate.selectionState === 'selected')
+            .map((candidate) => candidate.intent));
+        const skippedIntents = uniqueSorted(candidates
+            .filter((candidate) => candidate.status !== 'runnable')
+            .map((candidate) => candidate.intent));
+        const gapCount = input.report.gaps.filter((gap) => gap.reason === requirement.reason).length;
+        return {
+            reason: requirement.reason,
+            files: [...requirement.files],
+            surfaces: [...requirement.surfaces],
+            candidate_intents: uniqueSorted(candidates.map((candidate) => candidate.intent)),
+            selected_intents: selectedIntents,
+            skipped_intents: skippedIntents,
+            gap_count: gapCount,
+            outcome: requirementOutcome({
+                selectedIntents,
+                skippedIntents,
+                gapCount,
+                results: input.results,
+            }),
+        };
+    });
+    const receipts = receiptEntries(input.results);
+    const sourceAnchorRisks = input.sourceAnchorRisks ?? [];
+    const scopeDiffRisks = input.scopeDiffRisks ?? [];
+    const repeatedFailureRisks = input.repeatedFailureRisks ?? [];
+    const validationRatchetRisks = input.validationRatchetRisks ?? [];
+    const reproEvidence = input.reproEvidence ?? null;
+    const reproEvidenceRisks = input.reproEvidenceRisks ?? [];
+    const externalChecks = input.externalChecks ?? [];
+    const externalEvidenceRisks = input.externalEvidenceRisks ?? [];
+    const gaps = input.report.gaps.map((gap) => ({
+        reason: gap.reason,
+        intent: null,
+        status: 'missing',
+        detail: gap.detail,
+        files: [...gap.files],
+        surfaces: [...gap.surfaces],
+    }));
+    return {
+        schema_version: '1',
+        source: 'mf_verify',
+        verification_plan_id: input.verificationPlanId,
+        requirements,
+        coverage_matrix: coverageMatrixFromRequirements({
+            source: 'verification_requirement',
+            requirements,
+            receipts,
+            gaps,
+            sourceAnchorRisks,
+        }),
+        receipts,
+        skipped_checks: skippedCheckEntries(input.results),
+        gaps,
+        remaining_risks: [
+            ...sourceAnchorRemainingRisks(sourceAnchorRisks),
+            ...scopeDiffRemainingRisks(scopeDiffRisks),
+            ...repeatedFailureRemainingRisks(repeatedFailureRisks),
+            ...validationRatchetRemainingRisks(validationRatchetRisks),
+            ...reproEvidenceRemainingRisks(reproEvidenceRisks),
+            ...externalEvidenceRemainingRisks(externalEvidenceRisks),
+        ],
+        ...(reproEvidence ? { repro_evidence: reproEvidence } : {}),
+        ...(externalChecks.length > 0 ? { external_checks: externalChecks } : {}),
+        explanation: explanationFromVerdict(input.verdict),
+    };
+}
+export function createDashboardEvidenceModel(input) {
+    const requirements = input.changedSurfaces.length > 0 || input.runnableIntents.length > 0
+        ? [
+            {
+                reason: 'dashboard_snapshot',
+                files: [],
+                surfaces: [...input.changedSurfaces],
+                candidate_intents: uniqueSorted(input.runnableIntents),
+                selected_intents: [],
+                skipped_intents: uniqueSorted(input.skippedChecks.map((check) => check.intent)),
+                gap_count: input.gaps.length,
+                outcome: input.verdict.status,
+            },
+        ]
+        : [];
+    const receipts = input.latestReceipt ? [input.latestReceipt] : [];
+    const sourceAnchorRisks = input.sourceAnchorRisks ?? [];
+    const scopeDiffRisks = input.scopeDiffRisks ?? [];
+    return {
+        schema_version: '1',
+        source: 'dashboard_export',
+        verification_plan_id: null,
+        requirements,
+        coverage_matrix: coverageMatrixFromRequirements({
+            source: 'dashboard_snapshot',
+            requirements,
+            receipts,
+            gaps: input.gaps,
+            sourceAnchorRisks,
+        }),
+        receipts,
+        skipped_checks: input.skippedChecks,
+        gaps: input.gaps,
+        remaining_risks: [
+            ...input.remainingRisks,
+            ...sourceAnchorRemainingRisks(sourceAnchorRisks),
+            ...scopeDiffRemainingRisks(scopeDiffRisks),
+        ],
+        explanation: explanationFromVerdict(input.verdict),
+    };
+}

package/dist/core/verification-scheduler.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { commandEffectsConflict, normalizeCommandEffects, } from './command-effects.js';
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
@@ -13,6 +15,79 @@ function toScheduleEffect(effect) {
         concurrency: effect.concurrency,
     };
 }
+function isObject(value) {
+    return !!value && typeof value === 'object';
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function getUndeclaredWriteIntent(value) {
+    if (!isObject(value) || typeof value.intent !== 'string') {
+        return null;
+    }
+    const writeDrift = value.write_drift;
+    if (!isObject(writeDrift) || writeDrift.has_undeclared_changes !== true) {
+        return null;
+    }
+    return value.intent;
+}
+function resolveStateRelativePath(projectRoot, relativePath) {
+    if (typeof relativePath !== 'string' || relativePath.length === 0 || path.isAbsolute(relativePath)) {
+        return null;
+    }
+    const normalized = relativePath.replaceAll('\\', '/');
+    if (!normalized.startsWith('.mustflow/state/runs/')) {
+        return null;
+    }
+    const resolved = path.resolve(projectRoot, normalized);
+    const relative = path.relative(projectRoot, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return null;
+    }
+    return resolved;
+}
+function readVerifyManifestUndeclaredWriteIntents(projectRoot, latest) {
+    const manifestPath = resolveStateRelativePath(projectRoot, latest.manifest_path);
+    if (!manifestPath) {
+        return new Set();
+    }
+    const manifest = readJsonFile(manifestPath);
+    if (!isObject(manifest) || manifest.command !== 'verify' || !Array.isArray(manifest.receipts)) {
+        return new Set();
+    }
+    const intents = new Set();
+    for (const entry of manifest.receipts) {
+        if (!isObject(entry)) {
+            continue;
+        }
+        const receiptPath = resolveStateRelativePath(projectRoot, entry.receipt_path);
+        if (!receiptPath) {
+            continue;
+        }
+        const intent = getUndeclaredWriteIntent(readJsonFile(receiptPath));
+        if (intent) {
+            intents.add(intent);
+        }
+    }
+    return intents;
+}
+function readLatestUndeclaredWriteIntents(projectRoot) {
+    const latestPath = path.join(projectRoot, '.mustflow', 'state', 'runs', 'latest.json');
+    const parsed = readJsonFile(latestPath);
+    const directIntent = getUndeclaredWriteIntent(parsed);
+    if (directIntent) {
+        return new Set([directIntent]);
+    }
+    if (!isObject(parsed) || parsed.command !== 'verify') {
+        return new Set();
+    }
+    return readVerifyManifestUndeclaredWriteIntents(projectRoot, parsed);
+}
 function entriesConflict(left, right) {
     const conflicts = [];
     for (const leftEffect of left.effects) {
@@ -33,7 +108,8 @@ function entriesConflict(left, right) {
 function addEntryToBatches(batches, batchEntries, entry) {
     for (let batchIndex = 0; batchIndex < batchEntries.length; batchIndex += 1) {
         const existingEntries = batchEntries[batchIndex] ?? [];
-        const hasConflict = existingEntries.some((existing) => entriesConflict(entry, existing).length > 0);
+        const hasConflict = !entry.parallelEligible ||
+            existingEntries.some((existing) => !existing.parallelEligible || entriesConflict(entry, existing).length > 0);
         if (hasConflict) {
             continue;
         }
@@ -55,14 +131,24 @@ function addEntryToBatches(batches, batchEntries, entry) {
     });
 }
 export function createVerificationSchedule(projectRoot, commandContract, candidates) {
+    const latestUndeclaredWriteIntents = readLatestUndeclaredWriteIntents(projectRoot);
     const runnableIntents = uniqueSorted(candidates
         .filter((candidate) => candidate.status === 'runnable' && candidate.intent.length > 0)
         .map((candidate) => candidate.intent));
     const baseEntries = runnableIntents.map((intent) => {
         const effects = normalizeCommandEffects(projectRoot, commandContract, intent).map(toScheduleEffect);
+        const hasExplicitEffects = effects.length > 0 && effects.every((effect) => effect.source === 'effects');
+        const hasUndeclaredWriteDrift = latestUndeclaredWriteIntents.has(intent);
+        const parallelEligible = hasExplicitEffects && !hasUndeclaredWriteDrift;
         return {
             intent,
             status: 'runnable',
+            parallelEligible,
+            parallelReason: hasUndeclaredWriteDrift
+                ? 'undeclared_write_drift'
+                : hasExplicitEffects
+                    ? 'explicit_effects'
+                    : 'missing_explicit_effects',
             effects,
             locks: uniqueSorted(effects.map((effect) => effect.lock)),
             conflicts: [],
@@ -82,11 +168,19 @@ export function createVerificationSchedule(projectRoot, commandContract, candida
     }
     return {
         runner: 'serial_mf_run_receipts',
+        failurePolicy: {
+            mode: 'batch_boundary',
+            startedBatch: 'wait_for_completion',
+            nextBatch: 'stop_on_failure',
+        },
         batches,
         entries,
         notes: [
             'Batches explain resource compatibility for planning only.',
-            'mf run still writes the latest receipt to a single path, so execute copied commands serially.',
+            'Only entries backed by explicit effects are marked parallel eligible; writes fallback remains serial-only.',
+            ...uniqueSorted(latestUndeclaredWriteIntents).map((intent) => `Latest receipt for ${intent} reported undeclared writes; it is not parallel eligible.`),
+            'If a future parallel batch has already started, let it finish and stop before the next batch on failure.',
+            'mf verify still executes copied commands serially and writes the latest run summary after the batch completes.',
         ],
     };
 }

package/examples/README.md

@@ -4,10 +4,18 @@ This directory contains human-readable project examples.
 
 These examples are not test fixtures and are not copied by `mf init`. They illustrate the structure of a project before and after integrating mustflow, while excluding generated or template-owned files from the example content.
 
-Current examples:
+## Choose an Example
+
+If you are new to mustflow:
 
-- `docs-only/`: A documentation-focused repository with explicit checks for missing code.
-- `host-instruction-conflicts/`: A repository where host-specific instructions overlap with mustflow rules.
 - `minimal-js/`: A small JavaScript package before and after adding mustflow.
+
+If you are building or integrating an AI coding tool:
+
+- `host-instruction-conflicts/`: A repository where host-specific instructions overlap with mustflow rules.
 - `missing-command-contracts/`: A repository with package scripts that are not yet defined as mustflow command intents.
-- `nested-repos/`: Parent and child repositories with separate local contracts.
+
+If you are studying repository structure:
+
+- `docs-only/`: A documentation-focused repository with explicit checks for missing code.
+- `nested-repos/`: Parent and child repositories with separate local contracts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "1.30.0",
+  "version": "2.11.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/README.md

@@ -9,15 +9,24 @@ Current schemas:
 - `adapter-compatibility-report.schema.json`: output of `mf adapters status --json`
 - `context-report.schema.json`: output of `mf context --json`
 - `run-receipt.schema.json`: output of `mf run <intent> --json` and `.mustflow/state/runs/latest.json`,
-  including bounded declared-write drift metadata
+  including bounded declared-write drift metadata, a safe latest-run performance summary, and optional
+  structured phase timings and selection summaries
 - `commands.schema.json`: parsed `.mustflow/config/commands.toml`
+- `test-selection.schema.json`: parsed optional `.mustflow/config/test-selection.toml`
 - `contract-lint-report.schema.json`: output of `mf contract-lint --json`
+- `dashboard-export.schema.json`: bounded static export written by `mf dashboard --export-json <path>`,
+  including output policy, redaction and truncation metadata, the dashboard harness report, and
+  the evidence-based completion verdict, evidence model, and conservative coverage matrix for the
+  exported snapshot
 - `classify-report.schema.json`: output of `mf classify --changed --json` and  
   `mf classify <path...> --json`
 - `impact-report.schema.json`: output of `mf impact --changed --json` and  
   `mf impact <path...> --json`
 - `line-endings-report.schema.json`: output of `mf line-endings check --json` and  
   `mf line-endings normalize --json`
+- `latest-run-pointer.schema.json`: `.mustflow/state/runs/latest.json` when `mf verify` writes a
+  pointer to the latest verify run bundle, including the verify completion verdict, evidence model,
+  and coverage matrix
 - `handoff-validation-report.schema.json`: output of  
   `mf handoff validate <path> --json`
 - `version-sources-report.schema.json`: output of `mf version-sources --json`
@@ -25,10 +34,15 @@ Current schemas:
 - `explain-report.schema.json`: output of `mf explain authority --json`, `mf explain command --json`,  
   `mf explain verify --reason <event> --json`, `mf explain retention --json`, `mf explain skills --json`,
   and `mf explain surface --json`. Verify explanations include the shared `decisionGraph` evidence model.
-- `verify-report.schema.json`: output of `mf verify --reason <event> --json`
+- `verify-report.schema.json`: output of `mf verify --reason <event> --json`, including an
+  evidence-based completion verdict and evidence model with a conservative coverage matrix for the
+  selected receipts and skipped checks
+- `verify-run-manifest.schema.json`: `.mustflow/state/runs/verify-latest/manifest.json`, including
+  the same completion verdict, evidence model, and coverage matrix as the verify report
 - `change-verification-report.schema.json`: output of `mf verify --reason <event> --plan-only --json` and  
-  `mf verify --from-plan <classify-report.json> --plan-only --json`, including the `decision_graph` that links
-  changed surfaces, classification reasons, command candidates, eligibility, effects, and gaps.
+  `mf verify --from-classification <classify-report.json> --plan-only --json`, including the `decision_graph` that links
+  changed surfaces, classification reasons, command candidates, eligibility, selected or not-selected state,
+  effects, and gaps.
   Local-index command-effect graphs are explanation-only and cannot grant command authority.
 
 These schemas define stable, automation-facing fields. Human-readable command