mustflow 2.11.0 → 2.17.0

package/dist/cli/lib/npm-version-check.js

@@ -1,5 +1,42 @@
 const DEFAULT_NPM_REGISTRY_URL = 'https://registry.npmjs.org';
 const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 3_000;
+const PACKAGE_MANAGER_COMMANDS = [
+    {
+        id: 'npm',
+        label: 'npm',
+        command(packageName) {
+            return `npm install -g ${packageName}@latest`;
+        },
+    },
+    {
+        id: 'bun',
+        label: 'bun',
+        command(packageName) {
+            return `bun add -g ${packageName}@latest`;
+        },
+    },
+    {
+        id: 'pnpm',
+        label: 'pnpm',
+        command(packageName) {
+            return `pnpm add -g ${packageName}@latest`;
+        },
+    },
+    {
+        id: 'yarn',
+        label: 'yarn',
+        command(packageName) {
+            return `yarn global add ${packageName}@latest`;
+        },
+    },
+    {
+        id: 'deno',
+        label: 'deno',
+        command(packageName) {
+            return `deno install -g -A -n mf npm:${packageName}@latest`;
+        },
+    },
+];
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -65,6 +102,37 @@ function getTimeoutMs() {
     const parsed = rawValue ? Number(rawValue) : DEFAULT_VERSION_CHECK_TIMEOUT_MS;
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : DEFAULT_VERSION_CHECK_TIMEOUT_MS;
 }
+function detectPackageManagerId() {
+    const signals = [
+        process.env.npm_config_user_agent,
+        process.env.npm_execpath,
+        process.execPath,
+        process.argv[1],
+        import.meta.url,
+    ]
+        .filter((signal) => typeof signal === 'string' && signal.length > 0)
+        .map((signal) => signal.toLowerCase());
+    for (const id of ['bun', 'pnpm', 'yarn', 'deno', 'npm']) {
+        if (signals.some((signal) => signal.includes(id))) {
+            return id;
+        }
+    }
+    return null;
+}
+function getPackageInstallCommands(packageName) {
+    const detectedId = detectPackageManagerId();
+    const commands = [...PACKAGE_MANAGER_COMMANDS];
+    const recommendedIndex = detectedId ? commands.findIndex((entry) => entry.id === detectedId) : -1;
+    if (recommendedIndex > 0) {
+        const [recommended] = commands.splice(recommendedIndex, 1);
+        commands.unshift(recommended);
+    }
+    return commands.map((entry, index) => ({
+        manager: entry.label,
+        command: entry.command(packageName),
+        recommended: index === 0 && detectedId === entry.id,
+    }));
+}
 function buildLatestPackageUrl(registryUrl, packageName) {
     const trimmedRegistryUrl = registryUrl.replace(/\/+$/u, '');
     const encodedPackageName = packageName.startsWith('@')
@@ -86,12 +154,14 @@ export async function checkNpmLatestVersion(metadata) {
     if (!latestVersion) {
         throw new Error('npm registry response did not include a version');
     }
+    const updateCommands = getPackageInstallCommands(metadata.name);
     return {
         packageName: metadata.name,
         currentVersion: metadata.version,
         latestVersion,
         updateAvailable: comparePackageVersions(metadata.version, latestVersion) < 0,
         registryUrl,
-        updateCommand: `npm install -g ${metadata.name}@latest`,
+        updateCommand: updateCommands[0]?.command ?? `npm install -g ${metadata.name}@latest`,
+        updateCommands,
     };
 }

package/dist/core/completion-verdict.js

@@ -1,17 +1,90 @@
+function createRiskEvidence(input) {
+    return {
+        source_anchor: input.sourceAnchorRiskCount ?? 0,
+        scope_diff: input.scopeDiffRiskCount ?? 0,
+        repeated_failure: input.repeatedFailureCount ?? 0,
+        validation_ratchet: input.validationRatchetRiskCount ?? 0,
+        repro_evidence: input.reproEvidenceRiskCount ?? 0,
+        external_evidence: input.externalEvidenceRiskCount ?? 0,
+        write_drift: input.writeDriftRiskCount ?? 0,
+        receipt_binding: input.receiptBindingRiskCount ?? 0,
+        stale_receipt: input.staleReceiptCount ?? 0,
+        plan_mismatch: input.planMismatchCount ?? 0,
+    };
+}
+function emptyReceiptBindingEvidence() {
+    return {
+        plan_bound_count: 0,
+        plan_unbound_count: 0,
+        fingerprint_bound_count: 0,
+        fingerprint_unbound_count: 0,
+        current_state_bound_count: 0,
+        current_state_unavailable_count: 0,
+        stale_count: 0,
+        plan_mismatch_count: 0,
+    };
+}
+function emptyCriteriaEvidence() {
+    return {
+        total: 0,
+        covered: 0,
+        partially_covered: 0,
+        uncovered: 0,
+        blocked: 0,
+        contradicted: 0,
+    };
+}
+function normalizeVerifyCompletionInput(input) {
+    const missingReceiptCount = Math.max(0, input.ranIntents - input.receiptCount);
+    if (missingReceiptCount === 0) {
+        return input;
+    }
+    return {
+        ...input,
+        receiptBindingRiskCount: (input.receiptBindingRiskCount ?? 0) + missingReceiptCount,
+    };
+}
 function verifyStatus(input) {
+    const contradictions = [];
     if (input.failedIntents > 0) {
-        const contradictions = ['one_or_more_selected_verification_intents_failed'];
-        if ((input.repeatedFailureCount ?? 0) > 0) {
+        contradictions.push('one_or_more_selected_verification_intents_failed');
+    }
+    if ((input.planMismatchCount ?? 0) > 0) {
+        contradictions.push('plan_receipt_mismatch');
+    }
+    if ((input.reproEvidenceContradictionCount ?? 0) > 0) {
+        contradictions.push('repro_evidence_contradicted');
+    }
+    if ((input.validationRatchetContradictionCount ?? 0) > 0) {
+        contradictions.push('validation_ratchet_contradicted');
+    }
+    if (contradictions.length > 0) {
+        if (input.failedIntents > 0 && (input.repeatedFailureCount ?? 0) > 0) {
             contradictions.push('repeated_verification_failure');
         }
         return {
             status: 'contradicted',
-            primaryReason: 'verification_failed',
+            primaryReason: input.failedIntents > 0
+                ? 'verification_failed'
+                : (input.planMismatchCount ?? 0) > 0
+                    ? 'plan_receipt_mismatch'
+                    : (input.reproEvidenceContradictionCount ?? 0) > 0
+                        ? 'repro_evidence_contradicted'
+                        : 'validation_ratchet_contradicted',
             blockers: [],
             contradictions,
             limitations: [],
         };
     }
+    if ((input.repeatedFailureBlockerCount ?? 0) > 0) {
+        return {
+            status: 'blocked',
+            primaryReason: 'repeated_failure_requires_new_evidence',
+            blockers: ['repeated_failure_requires_new_evidence'],
+            contradictions: [],
+            limitations: [],
+        };
+    }
     if (input.ranIntents === 0 && input.skippedIntents > 0) {
         const blockers = ['all_matching_verification_intents_were_skipped'];
         if ((input.repeatedFailureCount ?? 0) > 0) {
@@ -51,6 +124,15 @@ function verifyStatus(input) {
             limitations,
         };
     }
+    if ((input.reproEvidenceUnverifiedCount ?? 0) > 0) {
+        return {
+            status: 'unverified',
+            primaryReason: 'repro_evidence_unverified',
+            blockers: [],
+            contradictions: [],
+            limitations: ['repro_evidence_missing'],
+        };
+    }
     const downgradeLimitations = [];
     if ((input.sourceAnchorRiskCount ?? 0) > 0) {
         downgradeLimitations.push('high_risk_source_anchor_requires_review');
@@ -61,6 +143,15 @@ function verifyStatus(input) {
     if ((input.validationRatchetRiskCount ?? 0) > 0) {
         downgradeLimitations.push('validation_ratchet_risk_requires_review');
     }
+    if ((input.writeDriftRiskCount ?? 0) > 0) {
+        downgradeLimitations.push('write_drift_requires_review');
+    }
+    if ((input.receiptBindingRiskCount ?? 0) > 0) {
+        downgradeLimitations.push('receipt_binding_requires_review');
+    }
+    if ((input.staleReceiptCount ?? 0) > 0) {
+        downgradeLimitations.push('stale_receipt_requires_review');
+    }
     if ((input.reproEvidenceRiskCount ?? 0) > 0) {
         downgradeLimitations.push('repro_evidence_missing');
     }
@@ -76,9 +167,15 @@ function verifyStatus(input) {
                     ? 'scope_diff_review_required'
                     : (input.validationRatchetRiskCount ?? 0) > 0
                         ? 'validation_ratchet_review_required'
-                        : (input.reproEvidenceRiskCount ?? 0) > 0
-                            ? 'repro_evidence_missing'
-                            : 'external_evidence_review_required',
+                        : (input.writeDriftRiskCount ?? 0) > 0
+                            ? 'write_drift_review_required'
+                            : (input.receiptBindingRiskCount ?? 0) > 0
+                                ? 'receipt_binding_review_required'
+                                : (input.staleReceiptCount ?? 0) > 0
+                                    ? 'stale_receipt_review_required'
+                                    : (input.reproEvidenceRiskCount ?? 0) > 0
+                                        ? 'repro_evidence_missing'
+                                        : 'external_evidence_review_required',
             blockers: [],
             contradictions: [],
             limitations: downgradeLimitations,
@@ -102,26 +199,39 @@ function verifyStatus(input) {
     };
 }
 export function createVerifyCompletionVerdict(input) {
-    const result = verifyStatus(input);
+    const normalizedInput = normalizeVerifyCompletionInput(input);
+    const result = verifyStatus(normalizedInput);
+    const risks = createRiskEvidence(normalizedInput);
+    const receiptBinding = normalizedInput.receiptBinding ?? emptyReceiptBindingEvidence();
+    const criteria = normalizedInput.criteria ?? emptyCriteriaEvidence();
     return {
         schema_version: '1',
         status: result.status,
         primary_reason: result.primaryReason,
         evidence: {
             source: 'mf_verify',
-            verification_plan_id: input.verificationPlanId,
+            verification_plan_id: normalizedInput.verificationPlanId,
             changed_file_count: null,
-            matched_intents: input.matchedIntents,
-            ran_intents: input.ranIntents,
-            passed_intents: input.passedIntents,
-            failed_intents: input.failedIntents,
-            skipped_intents: input.skippedIntents,
-            receipt_count: input.receiptCount,
-            gap_count: input.skippedIntents,
-            source_anchor_risk_count: input.sourceAnchorRiskCount ?? 0,
-            scope_diff_risk_count: input.scopeDiffRiskCount ?? 0,
-            repeated_failure_count: input.repeatedFailureCount ?? 0,
-            validation_ratchet_risk_count: input.validationRatchetRiskCount ?? 0,
+            criteria,
+            matched_intents: normalizedInput.matchedIntents,
+            ran_intents: normalizedInput.ranIntents,
+            passed_intents: normalizedInput.passedIntents,
+            failed_intents: normalizedInput.failedIntents,
+            skipped_intents: normalizedInput.skippedIntents,
+            receipt_count: normalizedInput.receiptCount,
+            gap_count: normalizedInput.skippedIntents,
+            source_anchor_risk_count: normalizedInput.sourceAnchorRiskCount ?? 0,
+            scope_diff_risk_count: normalizedInput.scopeDiffRiskCount ?? 0,
+            repeated_failure_count: normalizedInput.repeatedFailureCount ?? 0,
+            validation_ratchet_risk_count: normalizedInput.validationRatchetRiskCount ?? 0,
+            repro_evidence_risk_count: normalizedInput.reproEvidenceRiskCount ?? 0,
+            external_evidence_risk_count: normalizedInput.externalEvidenceRiskCount ?? 0,
+            write_drift_risk_count: normalizedInput.writeDriftRiskCount ?? 0,
+            receipt_binding_risk_count: normalizedInput.receiptBindingRiskCount ?? 0,
+            stale_receipt_count: normalizedInput.staleReceiptCount ?? 0,
+            plan_mismatch_count: normalizedInput.planMismatchCount ?? 0,
+            risks,
+            receipt_binding: receiptBinding,
             latest_run_status: null,
         },
         blockers: result.blockers,
@@ -130,6 +240,8 @@ export function createVerifyCompletionVerdict(input) {
     };
 }
 export function createDashboardCompletionVerdict(input) {
+    const risks = createRiskEvidence(input);
+    const receiptBinding = input.receiptBinding ?? emptyReceiptBindingEvidence();
     const latestRunFailed = input.latestRunStatus === 'failed' ||
         input.latestRunStatus === 'timed_out' ||
         input.latestRunStatus === 'start_failed';
@@ -181,6 +293,17 @@ export function createDashboardCompletionVerdict(input) {
         primaryReason = 'latest_run_passed_without_current_claim_binding';
         limitations.push('latest_run_is_not_bound_to_a_current_completion_claim');
     }
+    const criteria = input.criteria ??
+        (input.changedFileCount > 0 || input.runnableIntentCount > 0 || input.skippedIntentCount > 0 || input.gapCount > 0
+            ? {
+                total: 1,
+                covered: 0,
+                partially_covered: status === 'partially_verified' ? 1 : 0,
+                uncovered: status === 'unverified' ? 1 : 0,
+                blocked: status === 'blocked' ? 1 : 0,
+                contradicted: status === 'contradicted' ? 1 : 0,
+            }
+            : emptyCriteriaEvidence());
     return {
         schema_version: '1',
         status,
@@ -189,6 +312,7 @@ export function createDashboardCompletionVerdict(input) {
             source: 'dashboard_export',
             verification_plan_id: null,
             changed_file_count: input.changedFileCount,
+            criteria,
             matched_intents: input.runnableIntentCount + input.skippedIntentCount,
             ran_intents: 0,
             passed_intents: 0,
@@ -200,6 +324,14 @@ export function createDashboardCompletionVerdict(input) {
             scope_diff_risk_count: input.scopeDiffRiskCount ?? 0,
             repeated_failure_count: input.repeatedFailureCount ?? 0,
             validation_ratchet_risk_count: input.validationRatchetRiskCount ?? 0,
+            repro_evidence_risk_count: input.reproEvidenceRiskCount ?? 0,
+            external_evidence_risk_count: input.externalEvidenceRiskCount ?? 0,
+            write_drift_risk_count: input.writeDriftRiskCount ?? 0,
+            receipt_binding_risk_count: input.receiptBindingRiskCount ?? 0,
+            stale_receipt_count: input.staleReceiptCount ?? 0,
+            plan_mismatch_count: input.planMismatchCount ?? 0,
+            risks,
+            receipt_binding: receiptBinding,
             latest_run_status: input.latestRunStatus,
         },
         blockers,

package/dist/core/repeated-failure.js

@@ -1,17 +1,179 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export const REPEATED_FAILURE_STATE_PATH = '.mustflow/state/repeated-failures.json';
+export const REPEATED_FAILURE_STATE_LIMIT = 50;
 const UNRESOLVED_VERIFY_STATUSES = new Set(['failed', 'blocked', 'partial']);
-export function createRepeatedFailureRisk(input) {
-    if (input.previousVerificationPlanId === null ||
-        input.previousStatus === null ||
-        input.previousVerificationPlanId !== input.currentVerificationPlanId ||
-        !UNRESOLVED_VERIFY_STATUSES.has(input.previousStatus) ||
-        !UNRESOLVED_VERIFY_STATUSES.has(input.currentStatus)) {
+function sha256Json(value) {
+    return `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
+}
+function normalizeStrings(values) {
+    return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort((left, right) => left.localeCompare(right));
+}
+function hashStrings(values) {
+    return sha256Json(normalizeStrings(values));
+}
+function hashBooleans(values) {
+    return sha256Json([...new Set(values)].sort((left, right) => Number(left) - Number(right)));
+}
+function isString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isRepeatedFailureSummary(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return (record.schema_version === '1' &&
+        isString(record.fingerprint) &&
+        isString(record.verification_plan_id) &&
+        isString(record.status) &&
+        isString(record.failed_intents_hash) &&
+        isString(record.risk_codes_hash) &&
+        isString(record.affected_surfaces_hash) &&
+        isString(record.first_seen_at) &&
+        isString(record.last_seen_at) &&
+        typeof record.seen_count === 'number' &&
+        Number.isInteger(record.seen_count) &&
+        record.seen_count > 0 &&
+        typeof record.requires_new_evidence === 'boolean');
+}
+function repeatedFailureStatePath(projectRoot) {
+    return path.join(projectRoot, ...REPEATED_FAILURE_STATE_PATH.split('/'));
+}
+function readRepeatedFailureState(projectRoot) {
+    const statePath = repeatedFailureStatePath(projectRoot);
+    if (!existsSync(statePath)) {
+        return { schema_version: '1', fingerprints: [] };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(statePath, 'utf8'));
+        const fingerprints = Array.isArray(parsed.fingerprints)
+            ? parsed.fingerprints.filter(isRepeatedFailureSummary)
+            : [];
+        return { schema_version: '1', fingerprints };
+    }
+    catch {
+        return { schema_version: '1', fingerprints: [] };
+    }
+}
+function writeRepeatedFailureState(projectRoot, state) {
+    const statePath = repeatedFailureStatePath(projectRoot);
+    mkdirSync(path.dirname(statePath), { recursive: true });
+    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+export function createVerificationFailureFingerprint(input) {
+    const failedIntents = normalizeStrings(input.failedIntents);
+    const riskCodes = normalizeStrings(input.riskCodes);
+    if (failedIntents.length === 0 && riskCodes.length === 0) {
         return null;
     }
+    const exitCodeClasses = normalizeStrings(input.exitCodeClasses);
+    const timeoutFlags = [...new Set(input.timeoutFlags)].sort((left, right) => Number(left) - Number(right));
+    const errorKinds = normalizeStrings(input.errorKinds);
+    const affectedSurfaces = normalizeStrings(input.affectedSurfaces);
+    const commandFingerprints = normalizeStrings(input.commandFingerprints);
+    const diagnosticSignals = {
+        exit_code_classes: exitCodeClasses,
+        timeout_flags: timeoutFlags,
+        error_kinds: errorKinds,
+    };
+    const fingerprintSource = {
+        schema_version: '1',
+        verification_plan_id: input.verificationPlanId,
+        failed_intents: failedIntents,
+        diagnostic_signals: diagnosticSignals,
+        risk_codes: riskCodes,
+        affected_surfaces: affectedSurfaces,
+        command_fingerprints: commandFingerprints,
+    };
+    return {
+        schema_version: '1',
+        fingerprint: sha256Json(fingerprintSource),
+        verification_plan_id: input.verificationPlanId,
+        failed_intents_hash: hashStrings(failedIntents),
+        exit_code_classes_hash: hashStrings(exitCodeClasses),
+        timeout_flags_hash: hashBooleans(timeoutFlags),
+        error_kinds_hash: hashStrings(errorKinds),
+        diagnostic_hash: sha256Json(diagnosticSignals),
+        risk_codes_hash: hashStrings(riskCodes),
+        affected_surfaces_hash: hashStrings(affectedSurfaces),
+        command_fingerprints_hash: hashStrings(commandFingerprints),
+    };
+}
+export function updateRepeatedFailureState(input) {
+    const failureFingerprint = input.failureFingerprint;
+    if (!failureFingerprint) {
+        return null;
+    }
+    const state = readRepeatedFailureState(input.projectRoot);
+    const observedAt = (input.observedAt ?? new Date()).toISOString();
+    const existing = state.fingerprints.find((entry) => entry.fingerprint === failureFingerprint.fingerprint);
+    const seenCount = (existing?.seen_count ?? 0) + 1;
+    const summary = {
+        schema_version: '1',
+        fingerprint: failureFingerprint.fingerprint,
+        verification_plan_id: failureFingerprint.verification_plan_id,
+        status: input.status,
+        failed_intents_hash: failureFingerprint.failed_intents_hash,
+        risk_codes_hash: failureFingerprint.risk_codes_hash,
+        affected_surfaces_hash: failureFingerprint.affected_surfaces_hash,
+        first_seen_at: existing?.first_seen_at ?? observedAt,
+        last_seen_at: observedAt,
+        seen_count: seenCount,
+        requires_new_evidence: UNRESOLVED_VERIFY_STATUSES.has(input.status) && seenCount >= 2,
+    };
+    const nextFingerprints = [summary, ...state.fingerprints.filter((entry) => entry.fingerprint !== summary.fingerprint)]
+        .sort((left, right) => right.last_seen_at.localeCompare(left.last_seen_at))
+        .slice(0, REPEATED_FAILURE_STATE_LIMIT);
+    writeRepeatedFailureState(input.projectRoot, {
+        schema_version: '1',
+        fingerprints: nextFingerprints,
+    });
+    return summary;
+}
+function createRepeatedFailureRisk(code, currentFingerprint, previousStatus) {
+    const detail = code === 'repeated_verification_failure'
+        ? 'The previous verify summary has the same failure fingerprint and an unresolved status; provide new evidence or a narrower hypothesis before marking the task complete.'
+        : code === 'no_new_evidence_since_previous_failure'
+            ? 'The previous verify summary has the same plan, failed-intent hash, and affected-surface hash; provide new source or reproduction evidence before treating the next completion claim as verifiable.'
+            : 'The same unresolved failure fingerprint has repeated three or more times; new evidence is required before another completion claim can be treated as verifiable.';
     return {
-        code: 'repeated_verification_failure',
+        code,
         severity: 'high',
-        previous_status: input.previousStatus,
-        verification_plan_id: input.currentVerificationPlanId,
-        detail: 'The previous verify summary has the same verification_plan_id and an unresolved status; provide new evidence or a narrower hypothesis before marking the task complete.',
+        verdict_effect: code === 'repeated_verification_failure' ? 'contradiction' : 'blocker',
+        previous_status: previousStatus,
+        verification_plan_id: currentFingerprint.verification_plan_id,
+        failure_fingerprint: currentFingerprint.fingerprint,
+        failed_intents_hash: currentFingerprint.failed_intents_hash,
+        risk_codes_hash: currentFingerprint.risk_codes_hash,
+        affected_surfaces_hash: currentFingerprint.affected_surfaces_hash,
+        detail,
     };
 }
+export function createRepeatedFailureRisks(input) {
+    const currentFingerprint = input.currentFailureFingerprint;
+    if (input.previousFailureFingerprint === null ||
+        input.previousStatus === null ||
+        currentFingerprint === null ||
+        !UNRESOLVED_VERIFY_STATUSES.has(input.previousStatus) ||
+        !UNRESOLVED_VERIFY_STATUSES.has(input.currentStatus)) {
+        return [];
+    }
+    const risks = [];
+    const previousFingerprint = input.previousFailureFingerprint;
+    const sameFingerprint = previousFingerprint.fingerprint === currentFingerprint.fingerprint;
+    const samePlanAndNoNewSourceEvidence = previousFingerprint.verification_plan_id === currentFingerprint.verification_plan_id &&
+        previousFingerprint.failed_intents_hash === currentFingerprint.failed_intents_hash &&
+        previousFingerprint.affected_surfaces_hash === currentFingerprint.affected_surfaces_hash;
+    if (sameFingerprint) {
+        risks.push(createRepeatedFailureRisk('repeated_verification_failure', currentFingerprint, input.previousStatus));
+    }
+    if (samePlanAndNoNewSourceEvidence && !sameFingerprint) {
+        risks.push(createRepeatedFailureRisk('no_new_evidence_since_previous_failure', currentFingerprint, input.previousStatus));
+    }
+    if ((input.currentSummary?.seen_count ?? 0) >= 3 && input.currentSummary?.requires_new_evidence === true) {
+        risks.push(createRepeatedFailureRisk('repeated_failure_requires_new_evidence', currentFingerprint, input.previousStatus));
+    }
+    return risks;
+}