mustflow 1.31.0 → 2.11.0

package/dist/core/skill-route-alignment.js

@@ -1,5 +1,6 @@
 const SKILL_ROUTE_SOURCE_FILES = [
     '.mustflow/skills/INDEX.md',
+    '.mustflow/skills/routes.toml',
     '.mustflow/skills/*/SKILL.md',
     '.mustflow/config/commands.toml',
     '.mustflow/docs/agent-workflow.md',
@@ -20,6 +21,18 @@ export const SKILL_INDEX_ROUTE_COLUMN_COUNT = 7;
 export const SKILL_INDEX_SKILL_PATH_COLUMN_INDEX = 1;
 export const SKILL_INDEX_VERIFICATION_INTENTS_COLUMN_INDEX = 5;
 export const SKILL_INDEX_ROUTE_COLUMNS = 'Trigger, Skill Document, Required Input, Edit Scope, Risk, Verification Intents, Expected Output';
+export const SKILL_ROUTE_CATEGORY_LABELS = {
+    bug_failure: 'Bug and Failure',
+    general_code: 'General Code Change',
+    tests: 'Tests and Regression',
+    docs_release: 'Documentation and Release',
+    security_privacy: 'Security and Privacy',
+    data_external: 'Data and External Systems',
+    ui_assets: 'UI and Assets',
+    architecture_patterns: 'Architecture Patterns',
+    workflow_contracts: 'Workflow and Contract Maintenance',
+};
+const SKILL_ROUTE_CATEGORY_BY_HEADING = new Map(Object.entries(SKILL_ROUTE_CATEGORY_LABELS).map(([category, label]) => [label, category]));
 function splitMarkdownTableRow(line) {
     return line
         .trim()
@@ -39,7 +52,13 @@ export function findSkillIndexRoutePathColumn(cells) {
 }
 export function parseSkillIndexRoutes(content) {
     const routes = [];
+    let currentCategory;
     for (const line of content.split(/\r?\n/u)) {
+        const categoryHeading = /^###\s+(.+?)\s*$/u.exec(line.trim())?.[1];
+        if (categoryHeading) {
+            currentCategory = SKILL_ROUTE_CATEGORY_BY_HEADING.get(categoryHeading);
+            continue;
+        }
         if (!line.trim().startsWith('|')) {
             continue;
         }
@@ -63,6 +82,7 @@ export function parseSkillIndexRoutes(content) {
             risk: cells[4] ?? '',
             commandIntents: readBacktickValues(cells[SKILL_INDEX_VERIFICATION_INTENTS_COLUMN_INDEX] ?? ''),
             expectedOutput: cells[6] ?? '',
+            category: currentCategory,
         });
     }
     return routes;

package/dist/core/source-anchor-status.js

@@ -19,6 +19,9 @@ const HIGH_RISK_SOURCE_ANCHOR_TAGS = new Set([
     'ssrf',
     'xss',
 ]);
+export function hasHighRiskSourceAnchorRiskTags(risk) {
+    return risk.some((tag) => HIGH_RISK_SOURCE_ANCHOR_TAGS.has(tag));
+}
 function sha256(value) {
     return `sha256:${createHash('sha256').update(value).digest('hex')}`;
 }
@@ -62,7 +65,7 @@ function currentAnchorSignals(risk) {
     };
 }
 function hasHighRisk(risk) {
-    return risk.some((tag) => HIGH_RISK_SOURCE_ANCHOR_TAGS.has(tag));
+    return hasHighRiskSourceAnchorRiskTags(risk);
 }
 function sameSymbolIdentity(left, right) {
     return left.kind === right.kind && left.name !== null && left.name === right.name;

package/dist/core/test-selection.js

@@ -3,6 +3,7 @@ import { isRecord, readStringArray, resolveMustflowConfigPath, } from './config-
 import { readTomlFile } from './toml.js';
 import { classifyVerificationCandidate, } from './verification-plan.js';
 export const TEST_SELECTION_CONFIG_RELATIVE_PATH = '.mustflow/config/test-selection.toml';
+const STALE_OR_MISSING_RULES_NOTE = 'Project-declared test selection rules did not cover the current changed files; review .mustflow/config/test-selection.toml for stale or missing rules.';
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
@@ -203,7 +204,9 @@ export function createProjectTestSelectionPlan(projectRoot, classificationReport
         matches.length > 0
             ? 'Matched project-declared test selection rules are treated as a minimum selected set.'
             : 'No project-declared test selection rules matched the current changed files.',
+        ...(matches.length > 0 ? [] : [STALE_OR_MISSING_RULES_NOTE]),
         'Local index data and performance history may add suggestions later, but must not remove manifest-selected tests.',
+        'Absence of historical failures is not evidence that a test can be omitted.',
         'Test targets are passed only when the selected command intent declares selection.accepts_test_targets = true.',
     ];
     return {

package/dist/core/validation-ratchet.js

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+const TEST_CHANGE_KINDS = new Set(['test', 'test_fixture']);
+const SKIP_OR_ONLY_MARKER = /\b(?:describe|it|test)\s*\.\s*(?:skip|only)\s*\(/u;
+function isTestClassification(classification) {
+    return classification.surface.category === 'test' || classification.changeKinds.some((kind) => TEST_CHANGE_KINDS.has(kind));
+}
+function resolveInsideRoot(projectRoot, relativePath) {
+    const resolvedPath = path.resolve(projectRoot, relativePath);
+    const relative = path.relative(projectRoot, resolvedPath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return null;
+    }
+    return resolvedPath;
+}
+function fileTextIfReadable(projectRoot, relativePath) {
+    const resolvedPath = resolveInsideRoot(projectRoot, relativePath);
+    if (resolvedPath === null || !existsSync(resolvedPath)) {
+        return null;
+    }
+    try {
+        return readFileSync(resolvedPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function createValidationRatchetRisks(report, projectRoot) {
+    const risks = [];
+    for (const classification of report.classifications.filter(isTestClassification)) {
+        const resolvedPath = resolveInsideRoot(projectRoot, classification.path);
+        if (report.source === 'changed' && (resolvedPath === null || !existsSync(resolvedPath))) {
+            risks.push({
+                code: 'related_test_deleted',
+                severity: 'high',
+                path: classification.path,
+                detail: `Changed test path ${classification.path} is absent; deleted related tests require review before marking the task verified.`,
+            });
+            continue;
+        }
+        const fileText = fileTextIfReadable(projectRoot, classification.path);
+        if (fileText !== null && SKIP_OR_ONLY_MARKER.test(fileText)) {
+            risks.push({
+                code: 'skip_or_only_marker_present',
+                severity: 'medium',
+                path: classification.path,
+                detail: `Changed test path ${classification.path} contains a .skip or .only marker; review whether validation was weakened before marking the task verified.`,
+            });
+        }
+    }
+    return risks;
+}

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.11.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

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,