mustflow 2.11.0 → 2.16.0

package/dist/core/validation-ratchet.js

@@ -1,10 +1,33 @@
+import { spawnSync } from 'node:child_process';
 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;
+const TODO_OR_PENDING_MARKER = /\b(?:describe|it|test)\s*\.\s*(?:todo|pending)\s*\(/u;
+const ASSERTION_CALL = /\b(?:assert(?:\.\w+)?|expect)\s*\(/u;
+const STRONG_ASSERTION = /\b(?:assert\.(?:equal|deepEqual|strictEqual|throws|rejects)|to(?:Equal|StrictEqual|Be|Throw)|throws|rejects)\b/u;
+const WEAK_ASSERTION = /\b(?:assert\.ok|toBeDefined|toBeTruthy|toBeFalsy)\b/u;
+const NEGATIVE_ASSERTION = /\b(?:notEqual|notDeepEqual|doesNotMatch|doesNotThrow|\.not\.)\b/u;
+const EXCEPTION_ASSERTION = /\b(?:assert\.(?:throws|rejects|doesNotThrow|doesNotReject)|toThrow|rejects|throws)\b/u;
+const SNAPSHOT_PATH = /(?:^|\/)(?:__snapshots__\/|snapshots\/)|\.snap$/u;
+const GOLDEN_PATH = /(?:^|\/)(?:golden|fixtures|expected)(?:\/|-)|(?:\.golden\.|\.expected\.)/u;
+const JAVASCRIPT_TEST_PATH = /(?:^|\/)[^/]+\.(?:test|spec)\.[cm]?[jt]sx?$/u;
+const COMMAND_CONTRACT_PATH = '.mustflow/config/commands.toml';
+const TEST_SELECTION_PATTERN = /(?:--(?:grep|testNamePattern|testPathPattern|runTestsByPath|test-name-pattern)|\bgrep\s*=|\btestNamePattern\b|\btestPathPattern\b)/u;
+const COMMAND_ALLOWS_NO_TESTS_PATTERN = /(?:passWithNoTests|--pass-with-no-tests|--passWithNoTests)/u;
+const COMMAND_FORCES_SNAPSHOT_UPDATE_PATTERN = /(?:updateSnapshot|--update-snapshot|--updateSnapshot|\s-u(?:\s|"))/u;
+const COMMAND_HIDES_FAILURE_PATTERN = /(?:\|\|\s*true|;\s*true\b|&&\s*true\b|\bexit\s+0\b)/u;
+const CRITICAL_RATCHET_CODES = new Set([
+    'success_exit_codes_widened',
+    'command_allows_no_tests',
+    'command_hides_failure',
+]);
 function isTestClassification(classification) {
     return classification.surface.category === 'test' || classification.changeKinds.some((kind) => TEST_CHANGE_KINDS.has(kind));
 }
+function isJavaScriptTestPath(relativePath) {
+    return JAVASCRIPT_TEST_PATH.test(relativePath);
+}
 function resolveInsideRoot(projectRoot, relativePath) {
     const resolvedPath = path.resolve(projectRoot, relativePath);
     const relative = path.relative(projectRoot, resolvedPath);
@@ -25,27 +48,148 @@ function fileTextIfReadable(projectRoot, relativePath) {
         return null;
     }
 }
+function gitDiffLines(projectRoot, relativePath) {
+    const result = spawnSync('git', ['diff', '--no-ext-diff', '--unified=0', '--', relativePath], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        windowsHide: true,
+    });
+    if (result.status !== 0 || typeof result.stdout !== 'string' || result.stdout.length === 0) {
+        return { added: [], removed: [] };
+    }
+    const added = [];
+    const removed = [];
+    for (const line of result.stdout.split(/\r?\n/u)) {
+        if (line.startsWith('+++') || line.startsWith('---')) {
+            continue;
+        }
+        if (line.startsWith('+')) {
+            added.push(line.slice(1));
+        }
+        else if (line.startsWith('-')) {
+            removed.push(line.slice(1));
+        }
+    }
+    return { added, removed };
+}
+function countMatching(lines, pattern) {
+    return lines.filter((line) => pattern.test(line)).length;
+}
+function hasAny(lines, pattern) {
+    return lines.some((line) => pattern.test(line));
+}
+function extractCoverageNumbers(lines) {
+    return lines
+        .filter((line) => /\b(?:coverage|threshold|branches|functions|lines|statements)\b/iu.test(line))
+        .flatMap((line) => [...line.matchAll(/\b\d+(?:\.\d+)?\b/gu)].map((match) => Number(match[0])))
+        .filter((value) => Number.isFinite(value));
+}
+function isCommandContractPath(relativePath) {
+    return relativePath === COMMAND_CONTRACT_PATH;
+}
+function isValidationConfigPath(relativePath) {
+    return (isCommandContractPath(relativePath) ||
+        /(?:^|\/)(?:package\.json|jest\.config\.[cm]?[jt]s|vitest\.config\.[cm]?[jt]s|nyc\.config\.[cm]?[jt]s)$/u.test(relativePath) ||
+        /\bcoverage\b/u.test(relativePath));
+}
+function riskDetail(pathText, message) {
+    return `Changed validation path ${pathText} ${message}`;
+}
+export function countValidationRatchetVerdictEffects(risks) {
+    return {
+        contradicted: risks.filter((risk) => risk.severity === 'critical' && CRITICAL_RATCHET_CODES.has(risk.code)).length,
+    };
+}
 export function createValidationRatchetRisks(report, projectRoot) {
     const risks = [];
-    for (const classification of report.classifications.filter(isTestClassification)) {
+    const seenRisks = new Set();
+    function addRisk(code, severity, pathText, detail) {
+        const key = `${pathText}\0${code}`;
+        if (seenRisks.has(key)) {
+            return;
+        }
+        seenRisks.add(key);
+        risks.push({ code, severity, path: pathText, detail });
+    }
+    for (const classification of report.classifications) {
         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 diff = report.source === 'changed' ? gitDiffLines(projectRoot, classification.path) : { added: [], removed: [] };
+        const addedText = diff.added.join('\n');
+        if (isTestClassification(classification)) {
+            if (report.source === 'changed' && (resolvedPath === null || !existsSync(resolvedPath))) {
+                addRisk('related_test_deleted', 'high', classification.path, `Changed test path ${classification.path} is absent; deleted related tests require review before marking the task verified.`);
+                continue;
+            }
+            if (isJavaScriptTestPath(classification.path)) {
+                const fileText = fileTextIfReadable(projectRoot, classification.path);
+                if (fileText !== null && SKIP_OR_ONLY_MARKER.test(fileText)) {
+                    addRisk('skip_or_only_marker_present', 'medium', classification.path, `Changed test path ${classification.path} contains a .skip or .only marker; review whether validation was weakened before marking the task verified.`);
+                }
+                if ((fileText !== null && TODO_OR_PENDING_MARKER.test(fileText)) || TODO_OR_PENDING_MARKER.test(addedText)) {
+                    addRisk('todo_or_pending_marker_added', 'medium', classification.path, `Changed test path ${classification.path} contains a todo or pending marker; review whether validation was deferred before marking the task verified.`);
+                }
+                const removedAssertionCount = countMatching(diff.removed, ASSERTION_CALL);
+                const addedAssertionCount = countMatching(diff.added, ASSERTION_CALL);
+                if (removedAssertionCount > addedAssertionCount) {
+                    addRisk('assertion_count_decreased', 'high', classification.path, riskDetail(classification.path, `removes ${removedAssertionCount} assertion line(s) and adds ${addedAssertionCount}; review whether validation strength decreased.`));
+                }
+                if (hasAny(diff.removed, STRONG_ASSERTION) && hasAny(diff.added, WEAK_ASSERTION)) {
+                    addRisk('assertion_matcher_weakened', 'high', classification.path, riskDetail(classification.path, 'replaces a stronger assertion with a weaker presence or truthiness assertion.'));
+                }
+                if (hasAny(diff.removed, NEGATIVE_ASSERTION)) {
+                    addRisk('negative_assertion_removed', 'high', classification.path, riskDetail(classification.path, 'removes a negative assertion; confirm the denied behavior is still covered.'));
+                }
+                if (hasAny(diff.removed, EXCEPTION_ASSERTION)) {
+                    addRisk('exception_assertion_removed', 'high', classification.path, riskDetail(classification.path, 'removes an exception assertion; confirm failure behavior is still covered.'));
+                }
+            }
+            if (SNAPSHOT_PATH.test(classification.path) && diff.added.length + diff.removed.length >= 20) {
+                addRisk('snapshot_mass_updated', 'medium', classification.path, riskDetail(classification.path, 'changes a large snapshot region; review that the update does not hide a regression.'));
+            }
+            if (GOLDEN_PATH.test(`${classification.path} `) && diff.added.length + diff.removed.length >= 20) {
+                addRisk('golden_output_replaced', 'medium', classification.path, riskDetail(classification.path, 'replaces a broad golden or expected-output region; review the behavioral reason.'));
+            }
+        }
+        if (isCommandContractPath(classification.path)) {
+            if (hasAny(diff.added, /\bstatus\s*=\s*"(?:manual_only|disabled|unknown)"/u)) {
+                addRisk('verification_intent_disabled', 'high', classification.path, riskDetail(classification.path, 'adds a non-runnable verification intent status.'));
+            }
+            if (hasAny(diff.removed, /\brequired_after\s*=/u) && !hasAny(diff.added, /\brequired_after\s*=/u)) {
+                addRisk('verification_required_after_removed', 'high', classification.path, riskDetail(classification.path, 'removes a required_after mapping from the command contract.'));
+            }
+            if (hasAny(diff.added, /\bsuccess_exit_codes\s*=\s*\[[^\]]*(?:[1-9]\d*|true)[^\]]*\]/u)) {
+                addRisk('success_exit_codes_widened', 'critical', classification.path, riskDetail(classification.path, 'widens success exit codes beyond the normal zero-exit contract.'));
+            }
+            if (hasAny(diff.added, COMMAND_ALLOWS_NO_TESTS_PATTERN)) {
+                addRisk('command_allows_no_tests', 'critical', classification.path, riskDetail(classification.path, 'allows a test command to pass when no tests run.'));
+            }
+            if (hasAny(diff.added, COMMAND_FORCES_SNAPSHOT_UPDATE_PATTERN)) {
+                addRisk('command_forces_snapshot_update', 'medium', classification.path, riskDetail(classification.path, 'adds snapshot update behavior to a verification command.'));
+            }
+            if (hasAny(diff.added, COMMAND_HIDES_FAILURE_PATTERN)) {
+                addRisk('command_hides_failure', 'critical', classification.path, riskDetail(classification.path, 'adds shell behavior that can hide command failure.'));
+            }
         }
-        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.`,
-            });
+        if (isValidationConfigPath(classification.path)) {
+            const removedCoverageNumbers = extractCoverageNumbers(diff.removed);
+            const addedCoverageNumbers = extractCoverageNumbers(diff.added);
+            if (removedCoverageNumbers.length > 0 &&
+                addedCoverageNumbers.length > 0 &&
+                Math.min(...addedCoverageNumbers) < Math.max(...removedCoverageNumbers)) {
+                addRisk('coverage_threshold_lowered', 'medium', classification.path, riskDetail(classification.path, 'lowers a coverage-related numeric threshold.'));
+            }
+            if (hasAny(diff.added, COMMAND_ALLOWS_NO_TESTS_PATTERN)) {
+                addRisk('command_allows_no_tests', 'critical', classification.path, riskDetail(classification.path, 'allows a validation script to pass when no tests run.'));
+            }
+            if (hasAny(diff.added, COMMAND_FORCES_SNAPSHOT_UPDATE_PATTERN)) {
+                addRisk('command_forces_snapshot_update', 'medium', classification.path, riskDetail(classification.path, 'adds snapshot update behavior to a validation script.'));
+            }
+            if (hasAny(diff.added, COMMAND_HIDES_FAILURE_PATTERN)) {
+                addRisk('command_hides_failure', 'critical', classification.path, riskDetail(classification.path, 'adds shell behavior that can hide validation failure.'));
+            }
+            if (hasAny(diff.added, TEST_SELECTION_PATTERN)) {
+                addRisk('test_selection_narrowed', 'medium', classification.path, riskDetail(classification.path, 'adds a test-selection filter; confirm coverage still matches the change.'));
+            }
         }
     }
     return risks;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.11.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/dashboard-export.schema.json

@@ -326,6 +326,7 @@
             "source",
             "verification_plan_id",
             "changed_file_count",
+            "criteria",
             "matched_intents",
             "ran_intents",
             "passed_intents",
@@ -337,6 +338,14 @@
             "scope_diff_risk_count",
             "repeated_failure_count",
             "validation_ratchet_risk_count",
+            "repro_evidence_risk_count",
+            "external_evidence_risk_count",
+            "write_drift_risk_count",
+            "receipt_binding_risk_count",
+            "stale_receipt_count",
+            "plan_mismatch_count",
+            "risks",
+            "receipt_binding",
             "latest_run_status"
           ],
           "properties": {
@@ -346,6 +355,7 @@
               "pattern": "^sha256:[0-9a-f]{64}$"
             },
             "changed_file_count": { "type": ["integer", "null"] },
+            "criteria": { "$ref": "#/$defs/completionVerdictCriteria" },
             "matched_intents": { "type": "integer" },
             "ran_intents": { "type": "integer" },
             "passed_intents": { "type": "integer" },
@@ -357,6 +367,14 @@
             "scope_diff_risk_count": { "type": "integer" },
             "repeated_failure_count": { "type": "integer" },
             "validation_ratchet_risk_count": { "type": "integer" },
+            "repro_evidence_risk_count": { "type": "integer" },
+            "external_evidence_risk_count": { "type": "integer" },
+            "write_drift_risk_count": { "type": "integer" },
+            "receipt_binding_risk_count": { "type": "integer" },
+            "stale_receipt_count": { "type": "integer" },
+            "plan_mismatch_count": { "type": "integer" },
+            "risks": { "$ref": "#/$defs/completionVerdictRisks" },
+            "receipt_binding": { "$ref": "#/$defs/completionVerdictReceiptBinding" },
             "latest_run_status": { "type": ["string", "null"] }
           }
         },
@@ -374,6 +392,71 @@
         }
       }
     },
+    "completionVerdictCriteria": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "covered", "partially_covered", "uncovered", "blocked", "contradicted"],
+      "properties": {
+        "total": { "type": "integer" },
+        "covered": { "type": "integer" },
+        "partially_covered": { "type": "integer" },
+        "uncovered": { "type": "integer" },
+        "blocked": { "type": "integer" },
+        "contradicted": { "type": "integer" }
+      }
+    },
+    "completionVerdictRisks": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_anchor",
+        "scope_diff",
+        "repeated_failure",
+        "validation_ratchet",
+        "repro_evidence",
+        "external_evidence",
+        "write_drift",
+        "receipt_binding",
+        "stale_receipt",
+        "plan_mismatch"
+      ],
+      "properties": {
+        "source_anchor": { "type": "integer" },
+        "scope_diff": { "type": "integer" },
+        "repeated_failure": { "type": "integer" },
+        "validation_ratchet": { "type": "integer" },
+        "repro_evidence": { "type": "integer" },
+        "external_evidence": { "type": "integer" },
+        "write_drift": { "type": "integer" },
+        "receipt_binding": { "type": "integer" },
+        "stale_receipt": { "type": "integer" },
+        "plan_mismatch": { "type": "integer" }
+      }
+    },
+    "completionVerdictReceiptBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "plan_bound_count",
+        "plan_unbound_count",
+        "fingerprint_bound_count",
+        "fingerprint_unbound_count",
+        "current_state_bound_count",
+        "current_state_unavailable_count",
+        "stale_count",
+        "plan_mismatch_count"
+      ],
+      "properties": {
+        "plan_bound_count": { "type": "integer" },
+        "plan_unbound_count": { "type": "integer" },
+        "fingerprint_bound_count": { "type": "integer" },
+        "fingerprint_unbound_count": { "type": "integer" },
+        "current_state_bound_count": { "type": "integer" },
+        "current_state_unavailable_count": { "type": "integer" },
+        "stale_count": { "type": "integer" },
+        "plan_mismatch_count": { "type": "integer" }
+      }
+    },
     "harnessReport": {
       "type": "object",
       "additionalProperties": false,

package/schemas/explain-report.schema.json

@@ -506,7 +506,8 @@
             "runnableCount",
             "skippedCount",
             "requirements",
-            "decisionGraph"
+            "decisionGraph",
+            "readModel"
           ],
           "properties": {
             "planSource": { "type": ["string", "null"] },
@@ -523,11 +524,182 @@
             },
             "decisionGraph": {
               "$ref": "#/$defs/verificationDecisionGraph"
+            },
+            "readModel": {
+              "$ref": "#/$defs/localVerificationReadModel"
             }
           }
         }
       }
     },
+    "localVerificationReadModel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "authority",
+        "commandAuthority",
+        "grantsCommandAuthority",
+        "status",
+        "databasePath",
+        "indexFresh",
+        "stalePaths",
+        "planId",
+        "uncoveredCriteria",
+        "severeRisks",
+        "nonPassingReceipts",
+        "repeatedFailureFingerprints",
+        "validationWeakeningSignals",
+        "refreshHint"
+      ],
+      "properties": {
+        "source": { "const": "local_index" },
+        "authority": { "const": "evidence_only" },
+        "commandAuthority": { "const": ".mustflow/config/commands.toml" },
+        "grantsCommandAuthority": { "const": false },
+        "status": { "enum": ["fresh", "missing", "stale", "unreadable"] },
+        "databasePath": { "type": "string" },
+        "indexFresh": { "type": "boolean" },
+        "stalePaths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "planId": {
+          "type": ["string", "null"],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "uncoveredCriteria": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/localUncoveredCriterion" }
+        },
+        "severeRisks": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/localSevereVerificationRisk" }
+        },
+        "nonPassingReceipts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/localNonPassingVerificationReceipt" }
+        },
+        "repeatedFailureFingerprints": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/localRepeatedFailureFingerprint" }
+        },
+        "validationWeakeningSignals": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/localValidationWeakeningSignal" }
+        },
+        "refreshHint": { "type": ["string", "null"] }
+      }
+    },
+    "localUncoveredCriterion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "criterionId",
+        "source",
+        "reason",
+        "surface",
+        "pathHash",
+        "coverageStatus",
+        "receiptCount",
+        "gapCount",
+        "riskCount"
+      ],
+      "properties": {
+        "criterionId": { "type": "string" },
+        "source": { "type": "string" },
+        "reason": { "type": ["string", "null"] },
+        "surface": { "type": ["string", "null"] },
+        "pathHash": { "type": ["string", "null"] },
+        "coverageStatus": { "type": ["string", "null"] },
+        "receiptCount": { "type": "integer" },
+        "gapCount": { "type": "integer" },
+        "riskCount": { "type": "integer" }
+      }
+    },
+    "localSevereVerificationRisk": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourcePath", "ordinal", "code", "severity", "detailHash"],
+      "properties": {
+        "sourcePath": { "type": "string" },
+        "ordinal": { "type": "integer" },
+        "code": { "type": "string" },
+        "severity": { "type": "string" },
+        "detailHash": { "type": "string" }
+      }
+    },
+    "localNonPassingVerificationReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "receiptHash",
+        "planId",
+        "intent",
+        "status",
+        "commandFingerprint",
+        "contractFingerprint",
+        "currentStateHash",
+        "writeDriftStatus"
+      ],
+      "properties": {
+        "receiptHash": { "type": "string" },
+        "planId": { "type": "string" },
+        "intent": { "type": ["string", "null"] },
+        "status": { "type": "string" },
+        "commandFingerprint": { "type": ["string", "null"] },
+        "contractFingerprint": { "type": ["string", "null"] },
+        "currentStateHash": { "type": ["string", "null"] },
+        "writeDriftStatus": { "type": ["string", "null"] }
+      }
+    },
+    "localRepeatedFailureFingerprint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sourcePath",
+        "fingerprint",
+        "verificationPlanId",
+        "status",
+        "failedIntents",
+        "primaryReason",
+        "failedIntentsHash",
+        "riskCodesHash",
+        "affectedSurfacesHash",
+        "seenCount",
+        "requiresNewEvidence"
+      ],
+      "properties": {
+        "sourcePath": { "type": "string" },
+        "fingerprint": { "type": "string" },
+        "verificationPlanId": { "type": ["string", "null"] },
+        "status": { "type": "string" },
+        "failedIntents": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "primaryReason": { "type": ["string", "null"] },
+        "failedIntentsHash": { "type": ["string", "null"] },
+        "riskCodesHash": { "type": ["string", "null"] },
+        "affectedSurfacesHash": { "type": ["string", "null"] },
+        "seenCount": { "type": "integer" },
+        "requiresNewEvidence": { "type": "boolean" }
+      }
+    },
+    "localValidationWeakeningSignal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["signalId", "planId", "code", "severity", "pathHash", "beforeHash", "afterHash"],
+      "properties": {
+        "signalId": { "type": "string" },
+        "planId": { "type": ["string", "null"] },
+        "code": { "type": "string" },
+        "severity": { "type": "string" },
+        "pathHash": { "type": "string" },
+        "beforeHash": { "type": ["string", "null"] },
+        "afterHash": { "type": ["string", "null"] }
+      }
+    },
     "verificationDecisionGraph": {
       "type": "object",
       "additionalProperties": false,