mustflow 1.31.0 → 2.16.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/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.31.0",
+  "version": "2.16.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",
@@ -70,9 +70,9 @@
     "workflow"
   ],
   "devDependencies": {
-    "@types/node": "^25.6.2",
+    "@types/node": "^25.8.0",
     "@types/sql.js": "^1.4.11",
-    "fast-check": "^4.7.0",
+    "fast-check": "^4.8.0",
     "typescript": "^6.0.3"
   },
   "dependencies": {

package/schemas/README.md

@@ -12,15 +12,21 @@ Current schemas:
   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, and the dashboard harness report
+  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`
@@ -28,9 +34,13 @@ 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
+  `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.

package/schemas/change-verification-report.schema.json

@@ -13,7 +13,8 @@
     "candidates",
     "gaps",
     "schedule",
-    "decision_graph"
+    "decision_graph",
+    "test_selection"
   ],
   "properties": {
     "schema_version": {
@@ -28,6 +29,10 @@
     "classification_summary": {
       "$ref": "#/$defs/classificationSummary"
     },
+    "verification_plan_id": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
     "requirements": {
       "type": "array",
       "items": {
@@ -252,7 +257,16 @@
     "verificationCandidate": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["reason", "intent", "status", "skipReason", "detail"],
+      "required": [
+        "reason",
+        "intent",
+        "status",
+        "skipReason",
+        "detail",
+        "candidateState",
+        "eligibilityState",
+        "selectionState"
+      ],
       "properties": {
         "reason": {
           "type": "string"

package/schemas/commands.schema.json

@@ -147,6 +147,10 @@
         },
         "env_policy": { "$ref": "#/$defs/envPolicy" },
         "env_allowlist": { "$ref": "#/$defs/stringArray" },
+        "manual_start_hint": { "type": "string" },
+        "health_check_url": { "type": "string" },
+        "stop_instruction": { "type": "string" },
+        "related_oneshot_checks": { "$ref": "#/$defs/stringArray" },
         "effects": {
           "type": "array",
           "items": { "$ref": "#/$defs/effect" }

package/schemas/contract-lint-report.schema.json

@@ -55,6 +55,35 @@
           "type": "array",
           "items": { "type": "string" }
         },
+        "suggestions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "sourceFile",
+              "sourceKind",
+              "sourceName",
+              "commandHint",
+              "suggestedIntent",
+              "status",
+              "reason",
+              "snippet"
+            ],
+            "properties": {
+              "sourceFile": { "type": "string" },
+              "sourceKind": {
+                "enum": ["package_script", "make_target", "just_recipe"]
+              },
+              "sourceName": { "type": "string" },
+              "commandHint": { "type": "string" },
+              "suggestedIntent": { "type": "string" },
+              "status": { "const": "unknown" },
+              "reason": { "type": "string" },
+              "snippet": { "type": "string" }
+            }
+          }
+        },
         "coverage": {
           "type": "object",
           "additionalProperties": false,