@amityco/social-plus-vise 1.2.0 → 1.3.0

package/dist/tools/compliance.js

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { applyBlockProvidedCompleteness, assessProjectCompleteness, assessProjectSelectedOptionalCapabilities, availableOptionalCapabilityIds, optionalCapabilityChecklist, platformCapabilityAvailability, selectedOptionalCapabilityIds, } from "../capabilities.js";
-import { getOutcomeDefinition, hasAnswer, planContextFor, resolveOutcome, } from "../outcomes.js";
+import { CLASSIFY_ORDER, getOutcomeDefinition, hasAnswer, planContextFor, resolveOutcome, } from "../outcomes.js";
 import { contractRuleCandidatesForPublicId, hasMultipleContractRuleCandidates, productExpectationBindingForSensor, productExpectationTitle, publicProductRuleId, } from "../productExpectations.js";
 import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
@@ -210,7 +211,7 @@ function stringArray(value) {
     return value.filter((item) => typeof item === "string" && item.trim() !== "");
 }
 const validTiers = new Set(["free", "pro", "partner"]);
-const validOutcomes = new Set(["setup-sdk", "setup-push", "setup-live-data", "add-feed", "add-comments", "add-moderation", "add-chat", "troubleshoot", "validate-setup", "unknown"]);
+const validOutcomes = new Set([...CLASSIFY_ORDER, "unknown"]);
 export async function initEngagement(args) {
     const repoRoot = path.resolve(args.repoPath);
     const engagementFile = engagementPath(repoRoot);
@@ -289,6 +290,13 @@ function designReviewFor(repoRoot, contract, answers) {
         requiredForDesignConformance: true,
     };
     if (confirmation === "accepted") {
+        if (base.previewPath && !existsSync(base.previewPath)) {
+            return {
+                ...base,
+                status: "needs-confirmation",
+                nextStep: `Cannot accept the design contract: its preview (${base.previewPath}) does not exist, so it could not have been reviewed. Run \`vise design preview\` to regenerate it, review it, then re-confirm with --answer ${DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID}=yes.`,
+            };
+        }
         return {
             ...base,
             status: "accepted",
@@ -341,6 +349,12 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         capabilityAvailability,
         allowUnresolvedIntake: options.allowUnresolvedIntake === true,
     });
+    const intakeWarnings = validateIntakeAnswers(answers, {
+        request,
+        outcome,
+        platforms: inspection.platforms,
+        designSignals: inspection.designSignals,
+    });
     if (intake.remainingBlocking > 0 && !intake.acknowledged_unresolved_blocking) {
         const blockingIds = intake.questions
             .filter((question) => question.blocksImplementationWhenMissing)
@@ -351,6 +365,7 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
             exitCode: 7,
             outcome,
             intake,
+            ...(intakeWarnings.length > 0 && { warnings: intakeWarnings }),
             nextStep: "Run `vise plan` and surface the blocking intake questions to the customer. " +
                 `Then re-run with their answers (one --answer per id): vise init --request <request> --answer ${answerExample}. ` +
                 "Each --answer takes a single id=value; repeat the flag per id (do not comma-join). " +
@@ -401,8 +416,10 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         status: checkSnapshot.status,
         summary: checkSnapshot.summary,
         rules: checkSnapshot.rules,
+        ...(checkSnapshot.completeness ? { completeness: checkSnapshot.completeness } : {}),
+        ...(checkSnapshot.selectedOptionalCapabilities ? { selectedOptionalCapabilities: checkSnapshot.selectedOptionalCapabilities } : {}),
     });
-    const warnings = [];
+    const warnings = [...intakeWarnings];
     if (engagement && engagement.scope.outcomes.length > 0 && !engagement.scope.outcomes.includes(outcome)) {
         warnings.push(`Outcome "${outcome}" is not in the engagement scope (${engagement.scope.outcomes.join(", ")}). Compliance was still initialized; extend the scope in engagement.json or re-run vise engagement init.`);
     }
@@ -511,6 +528,44 @@ function intakeAuditFor(args) {
         acknowledged_unresolved_blocking: args.allowUnresolvedIntake && remainingBlocking > 0,
     };
 }
+const APPENDED_INTAKE_QUESTION_IDS = new Set([
+    DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID,
+    "design_source",
+    "confirm_design_source",
+    "primary_action_token",
+    "feed_optional_capabilities",
+]);
+function validateIntakeAnswers(answers, ctx) {
+    const warnings = [];
+    const catalogCtx = planContextFor({
+        request: ctx.request,
+        outcome: ctx.outcome,
+        platform: preferredPlatform(ctx.platforms),
+        platforms: ctx.platforms,
+        designSignals: ctx.designSignals,
+        answers: {},
+    });
+    const catalog = getOutcomeDefinition(ctx.outcome).intakeQuestions(catalogCtx);
+    const byId = new Map(catalog.map((question) => [question.id, question]));
+    for (const [key, value] of Object.entries(answers)) {
+        const question = byId.get(key);
+        if (!question && !APPENDED_INTAKE_QUESTION_IDS.has(key)) {
+            warnings.push(`Intake answer "${key}" was ignored — it does not match any intake question for outcome "${ctx.outcome}". Run \`vise plan\` to see the valid question ids.`);
+            continue;
+        }
+        const optionsAreTokens = Array.isArray(question?.options) &&
+            question.options.length > 0 &&
+            question.options.every((option) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(option));
+        if (question && optionsAreTokens) {
+            const tokens = String(value).split(",").map((token) => token.trim()).filter(Boolean);
+            const invalid = tokens.filter((token) => !question.options.includes(token));
+            if (invalid.length > 0) {
+                warnings.push(`Intake answer "${key}=${value}" includes value(s) outside the allowed options for "${key}" (${question.options.join(", ")}). The unexpected value(s) [${invalid.join(", ")}] may be ignored; re-run with a valid option.`);
+            }
+        }
+    }
+    return warnings;
+}
 function creativeSelectionSummary(selection) {
     return {
         status: selection.status,
@@ -680,7 +735,7 @@ async function ruleFreshness(rule) {
         ...(verifiedAgainst && { verified_against: verifiedAgainst }),
     };
 }
-export async function checkCompliance(repoPath) {
+export async function checkCompliance(repoPath, options = {}) {
     const repoRoot = path.resolve(repoPath);
     const compliance = await readCompliance(repoRoot);
     const rules = await rulesById();
@@ -700,6 +755,7 @@ export async function checkCompliance(repoPath) {
     const recordedPlatforms = compliance.surface?.platforms || [];
     const platformsToValidate = Array.from(new Set([...detectedPlatforms, ...recordedPlatforms]));
     const platforms = platformsToValidate.length > 0 ? platformsToValidate : ["unknown"];
+    const { canonicalPlatform } = await import("./sdkFacts.js");
     const allFindings = await Promise.all(platforms.map((p) => validateSetup(inspection.effectiveRoot, p)));
     const findings = allFindings.flat();
     const findingsById = new Map();
@@ -740,11 +796,17 @@ export async function checkCompliance(repoPath) {
         const isInferential = !hasDeterministicChecks && !!rule.enforcement.inferential;
         const finding = hasDeterministicChecks ? deterministicFinding(rule, findingsById) : undefined;
         if (hasDeterministicChecks && !finding) {
+            const identity = checkRuleIdentity(rule.id);
+            const rulePlatform = identity.validator?.platform;
+            const passBasis = rulePlatform && !platforms.some((p) => canonicalPlatform(p) === canonicalPlatform(rulePlatform))
+                ? "undetected-platform"
+                : "absent";
             results.push({
-                ...checkRuleIdentity(rule.id),
+                ...identity,
                 title: rule.title,
                 severity: rule.severity,
                 status: "deterministic-pass",
+                pass_basis: passBasis,
                 evidence: { source: "validate_setup", finding_absent: deterministicFindingIds(rule) },
             });
             continue;
@@ -858,39 +920,81 @@ export async function checkCompliance(repoPath) {
         }
     }
     const summary = summarize(results);
-    const hasBlocked = results.some((result) => result.status === "blocked");
-    const hasDeterministicFailure = results.some((result) => result.status === "deterministic-fail");
-    const needsAttestation = results.some((result) => result.status === "attestation-needed" || result.status === "stale");
+    const deterministicPasses = results.filter((result) => result.status === "deterministic-pass");
+    const evidenceBasis = deterministicPasses.length > 0
+        ? {
+            absent: deterministicPasses.filter((result) => result.pass_basis !== "undetected-platform").length,
+            undetected_platform: deterministicPasses.filter((result) => result.pass_basis === "undetected-platform").length,
+        }
+        : undefined;
+    const evidenceBasisNote = evidenceBasis
+        ? `${deterministicPasses.length} of the passing rules passed by ABSENCE (the sensor found no violation, which is not positive proof the feature was built).${evidenceBasis.undetected_platform > 0
+            ? ` ${evidenceBasis.undetected_platform} of those are vacuous — the rule's platform was not detected in this project, so no sensor ran.`
+            : ""} Treat these as "no problem found", not "built and validated".`
+        : undefined;
     const sourceCompleteness = (await assessProjectCompleteness(inspection.effectiveRoot, compliance.outcome).catch(() => null)) ?? undefined;
     const blockProvided = sourceCompleteness && sourceCompleteness.missing.length > 0
         ? await installedBlockProvidedCapabilities(repoRoot).catch(() => [])
         : [];
     const completeness = sourceCompleteness ? applyBlockProvidedCompleteness(sourceCompleteness, blockProvided) : undefined;
-    const hasCompletenessGap = (completeness?.missing.length ?? 0) > 0;
     const selectedOptionalCapabilities = (await assessProjectSelectedOptionalCapabilities(inspection.effectiveRoot, compliance.outcome, compliance.selected_optional_capabilities ?? []).catch(() => null)) ?? undefined;
-    const hasSelectedOptionalFailures = ((selectedOptionalCapabilities?.failed.length ?? 0) > 0) || ((selectedOptionalCapabilities?.unknown.length ?? 0) > 0);
-    const status = hasBlocked
-        ? "blocked"
-        : hasDeterministicFailure
-            ? "deterministic-failures"
-            : needsAttestation
-                ? "needs-attestation"
-                : hasCompletenessGap
-                    ? "completeness-gap"
-                    : hasSelectedOptionalFailures
-                        ? "selected-capability-failures"
-                        : "green";
-    const exitCode = hasBlocked
-        ? 3
-        : hasDeterministicFailure
-            ? 2
-            : needsAttestation
-                ? 1
-                : hasCompletenessGap
-                    ? 5
-                    : hasSelectedOptionalFailures
-                        ? 6
-                        : 0;
+    const baselineFile = await readBaseline(repoRoot);
+    let baselineReport;
+    let gatedResults = results;
+    let gatedMissing = completeness?.missing ?? [];
+    let gatedSelectedFailed = selectedOptionalCapabilities?.failed ?? [];
+    let gatedSelectedUnknown = selectedOptionalCapabilities?.unknown ?? [];
+    if (options.newOnly) {
+        if (!baselineFile) {
+            baselineReport = { present: false, applied: false, reason: "No baseline recorded — `--new-only` gated on everything. Run `vise init --baseline` (or `vise baseline`) on the pre-existing codebase first." };
+        }
+        else if (baselineFile.ruleset_digest !== compliance.ruleset_digest) {
+            baselineReport = { present: true, applied: false, stale: true, baselined_at: baselineFile.baselined_at, reason: "Baseline is stale: the ruleset changed since it was recorded, so it was NOT applied (gating on everything). Re-run `vise baseline` to refresh it against the current contract." };
+        }
+        else {
+            const budget = new Map(Object.entries(baselineFile.findings));
+            for (const result of results) {
+                if (!BASELINE_NON_GREEN.has(result.status))
+                    continue;
+                const key = baselineKeyFor(result);
+                const remaining = budget.get(key) ?? 0;
+                if (remaining > 0) {
+                    budget.set(key, remaining - 1);
+                    result.baselined = true;
+                }
+            }
+            const baselinedMissing = new Set(baselineFile.completeness_missing);
+            const baselinedSelected = new Set(baselineFile.selected_optional);
+            gatedResults = results.filter((result) => !result.baselined);
+            gatedMissing = (completeness?.missing ?? []).filter((item) => !baselinedMissing.has(item.id));
+            gatedSelectedFailed = (selectedOptionalCapabilities?.failed ?? []).filter((item) => !baselinedSelected.has(item.id));
+            gatedSelectedUnknown = (selectedOptionalCapabilities?.unknown ?? []).filter((id) => !baselinedSelected.has(id));
+            baselineReport = {
+                present: true,
+                applied: true,
+                baselined_at: baselineFile.baselined_at,
+                excluded: {
+                    rules: results.filter((result) => result.baselined).length,
+                    completeness: (completeness?.missing.length ?? 0) - gatedMissing.length,
+                    selected_optional: ((selectedOptionalCapabilities?.failed.length ?? 0) - gatedSelectedFailed.length) +
+                        ((selectedOptionalCapabilities?.unknown.length ?? 0) - gatedSelectedUnknown.length),
+                },
+                residual_caveat: "Baseline excludes pre-existing findings keyed by rule+file (count-based). A NEW violation of an already-baselined rule in the SAME file can be masked at this granularity — review the touched files directly for a precise per-change gate.",
+            };
+        }
+    }
+    else if (baselineFile) {
+        baselineReport = { present: true, applied: false, baselined_at: baselineFile.baselined_at, hint: "A brownfield baseline exists. Run `vise check --new-only` to gate only on findings introduced since the baseline (pre-existing findings are excluded)." };
+    }
+    const hasCompletenessGap = gatedMissing.length > 0;
+    const hasSelectedOptionalFailures = gatedSelectedFailed.length > 0 || gatedSelectedUnknown.length > 0;
+    const { status, exitCode } = deriveGate({
+        hasBlocked: gatedResults.some((result) => result.status === "blocked"),
+        hasDeterministicFailure: gatedResults.some((result) => result.status === "deterministic-fail"),
+        needsAttestation: gatedResults.some((result) => result.status === "attestation-needed" || result.status === "stale"),
+        hasCompletenessGap,
+        hasSelectedOptionalFailures,
+    });
     const uxHarness = await readUxHarness(repoRoot);
     const uxAssessment = await assessUxHarness(inspection.effectiveRoot, uxHarness, compliance.outcome);
     const experienceReport = buildExperienceReport({
@@ -908,8 +1012,11 @@ export async function checkCompliance(repoPath) {
         surfacePath: compliance.surface?.path,
         summary,
         rules: results,
+        ...(evidenceBasis ? { evidence_basis: evidenceBasis } : {}),
+        ...(evidenceBasisNote ? { evidence_basis_note: evidenceBasisNote } : {}),
         ...(completeness && (completeness.missing.length > 0 || completeness.optedOut.length > 0 || completeness.present.length > 0) ? { completeness } : {}),
         ...(selectedOptionalCapabilities ? { selectedOptionalCapabilities } : {}),
+        ...(baselineReport ? { baseline: baselineReport } : {}),
         uxHarness: uxAssessment,
         experienceReport,
     };
@@ -1028,7 +1135,12 @@ export async function syncCompliance(repoPath) {
             if (existing?.status === "attested") {
                 continue;
             }
-            const attestation = buildAttestation(compliance, rule, "spf-deterministic", "high", undefined, "Deterministic check passed.", result.evidence ?? {});
+            const passBasis = result.pass_basis ?? "absent";
+            const confidence = passBasis === "undetected-platform" ? "low" : "medium";
+            const rationale = passBasis === "undetected-platform"
+                ? "Deterministic check passed by absence, but this rule targets a platform not detected in this project, so no sensor exercised it — treat as not-yet-validated."
+                : "Deterministic check passed: the sensor ran and found no violation. Absence of a finding is not positive proof the feature was built.";
+            const attestation = buildAttestation(compliance, rule, "spf-deterministic", confidence, undefined, rationale, { ...(result.evidence ?? {}), pass_basis: passBasis });
             await writeJson(filePath, attestation);
             written.push(filePath);
         }
@@ -1090,6 +1202,7 @@ export async function attestRule(args) {
         throw new Error(`Rule does not allow local human attestations: ${args.ruleId}`);
     }
     validateEvidence(rule, args.evidence);
+    const sensorWarning = await liveSensorContradiction(repoRoot, compliance, rule);
     await mkdir(attestationsDir(repoRoot), { recursive: true });
     const sourceFingerprints = await collectSourceFingerprints(repoRoot, sourceRootForCompliance(repoRoot, compliance), args.evidence);
     const attestation = buildAttestation(compliance, rule, args.signer, args.confidence, args.identity, args.rationale, args.evidence, sourceFingerprints);
@@ -1101,6 +1214,7 @@ export async function attestRule(args) {
         destination: filePath,
         signer_claim: attestation.signer_claim,
         source_fingerprints: sourceFingerprints,
+        ...(sensorWarning ? { sensor_warning: sensorWarning } : {}),
     };
 }
 export async function explainRule(ruleId) {
@@ -1124,6 +1238,9 @@ export async function explainRule(ruleId) {
                     title: candidate.title,
                     severity: candidate.severity,
                     rationale: candidate.rationale,
+                    ...(candidate.feedforward ? { feedforward: candidate.feedforward } : {}),
+                    ...(candidate.symptoms && candidate.symptoms.length > 0 ? { symptoms: candidate.symptoms } : {}),
+                    ...(candidate.enforcement.inferential ? { inferential: candidate.enforcement.inferential } : {}),
                     applies_when: candidate.applies_when,
                     attestation: candidate.enforcement.attestation,
                     summary: ruleSummary(candidate),
@@ -1142,6 +1259,9 @@ export async function explainRule(ruleId) {
         title: rule.title,
         severity: rule.severity,
         rationale: rule.rationale,
+        ...(rule.feedforward ? { feedforward: rule.feedforward } : {}),
+        ...(rule.symptoms && rule.symptoms.length > 0 ? { symptoms: rule.symptoms } : {}),
+        ...(rule.enforcement.inferential ? { inferential: rule.enforcement.inferential } : {}),
         applies_when: rule.applies_when,
         compatible_with: rule.compatible_with,
         deterministic: rule.enforcement.deterministic ?? [],
@@ -1151,9 +1271,44 @@ export async function explainRule(ruleId) {
         freshness: await ruleFreshness(rule),
     };
 }
-export async function statusCompliance(repoPath) {
+export async function listRules() {
+    const rules = await rulesById();
+    const byPublic = new Map();
+    for (const rule of rules.values()) {
+        const publicId = publicProductRuleId(rule.id);
+        let entry = byPublic.get(publicId);
+        if (!entry) {
+            entry = { id: publicId, contract_rule_ids: new Set(), titles: new Set(), severities: new Set(), outcomes: new Set(), platforms: new Set() };
+            byPublic.set(publicId, entry);
+        }
+        entry.contract_rule_ids.add(rule.id);
+        entry.titles.add(rule.title);
+        entry.severities.add(rule.severity);
+        for (const outcome of rule.applies_when.outcomes ?? [])
+            entry.outcomes.add(outcome);
+        for (const platform of rule.applies_when.platforms ?? [])
+            entry.platforms.add(platform);
+    }
+    const entries = [...byPublic.values()]
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((entry) => ({
+        id: entry.id,
+        contract_rule_ids: [...entry.contract_rule_ids].sort(),
+        title: [...entry.titles][0],
+        severity: [...entry.severities].sort()[0],
+        outcomes: [...entry.outcomes].sort(),
+        platforms: [...entry.platforms].sort(),
+    }));
+    return {
+        kind: "rule-index",
+        count: entries.length,
+        hint: "Run `vise explain <id>` with any id below (a public product id or a contract_rule_id) for the full rule, evidence, and attestation policy.",
+        rules: entries,
+    };
+}
+export async function statusCompliance(repoPath, options = {}) {
     const repoRoot = path.resolve(repoPath);
-    const check = await checkCompliance(repoPath);
+    const check = await checkCompliance(repoPath, options);
     const engagement = await readEngagement(repoRoot);
     const compliance = await readCompliance(repoRoot).catch(() => null);
     return {
@@ -1162,6 +1317,10 @@ export async function statusCompliance(repoPath) {
         outcome: check.outcome,
         surfacePath: check.surfacePath,
         summary: check.summary,
+        ...(check.evidence_basis ? { evidence_basis: check.evidence_basis } : {}),
+        ...(check.evidence_basis_note ? { evidence_basis_note: check.evidence_basis_note } : {}),
+        ...(check.completeness ? { completeness: check.completeness } : {}),
+        ...(check.selectedOptionalCapabilities ? { selectedOptionalCapabilities: check.selectedOptionalCapabilities } : {}),
         ...(compliance?.design_contract && { design_contract: compliance.design_contract }),
         ...(engagement && {
             engagement: {
@@ -1340,6 +1499,36 @@ function deterministicFinding(rule, findingsById) {
     }
     return undefined;
 }
+async function liveSensorContradiction(repoRoot, compliance, rule) {
+    if (deterministicFindingIds(rule).length === 0) {
+        return undefined;
+    }
+    const inspection = await inspectProject(repoRoot, compliance.surface?.path === "." ? undefined : compliance.surface?.path);
+    const platforms = Array.from(new Set([...inspection.platforms, ...(compliance.surface?.platforms ?? [])]));
+    if (platforms.length === 0) {
+        return undefined;
+    }
+    const allFindings = await Promise.all(platforms.map((platform) => validateSetup(inspection.effectiveRoot, platform)));
+    const findingsById = new Map();
+    for (const finding of allFindings.flat()) {
+        findingsById.set(finding.ruleId, finding);
+        if (finding.sensorId) {
+            findingsById.set(finding.sensorId, finding);
+        }
+    }
+    const finding = deterministicFinding(rule, findingsById);
+    if (!finding) {
+        return undefined;
+    }
+    return {
+        message: "The live deterministic sensor STILL reports a violation for this rule. This attestation records your override; verify the source actually satisfies the rule before relying on it.",
+        sensor_finding: {
+            ruleId: finding.ruleId,
+            ...(finding.sensorId ? { sensorId: finding.sensorId } : {}),
+            ...(finding.recommendation ? { recommendation: finding.recommendation } : {}),
+        },
+    };
+}
 function deterministicFindingIds(rule) {
     return (rule.enforcement.deterministic ?? [])
         .filter((check) => check.check === "validator-finding-absent")
@@ -1678,6 +1867,71 @@ function attestationsDir(repoRoot) {
 function compliancePath(repoRoot) {
     return path.join(sidecarDir(repoRoot), "compliance.json");
 }
+const BASELINE_NON_GREEN = new Set(["deterministic-fail", "attestation-needed", "stale", "blocked"]);
+function baselineKeyFor(result) {
+    const ruleId = result.contractRuleId ?? result.ruleId;
+    return `${ruleId}@${result.finding?.file ?? "*"}`;
+}
+function baselinePath(repoRoot) {
+    return path.join(sidecarDir(repoRoot), "baseline.json");
+}
+async function readBaseline(repoRoot) {
+    return readJsonIfExists(baselinePath(repoRoot));
+}
+function deriveGate(flags) {
+    if (flags.hasBlocked)
+        return { status: "blocked", exitCode: 3 };
+    if (flags.hasDeterministicFailure)
+        return { status: "deterministic-failures", exitCode: 2 };
+    if (flags.needsAttestation)
+        return { status: "needs-attestation", exitCode: 1 };
+    if (flags.hasCompletenessGap)
+        return { status: "completeness-gap", exitCode: 5 };
+    if (flags.hasSelectedOptionalFailures)
+        return { status: "selected-capability-failures", exitCode: 6 };
+    return { status: "green", exitCode: 0 };
+}
+export async function recordBaseline(repoPath) {
+    const repoRoot = path.resolve(repoPath);
+    const compliance = await readCompliance(repoRoot);
+    const check = await checkCompliance(repoPath);
+    if (check.status === "contract-drift") {
+        throw new Error("Cannot record a baseline while the contract is drifted (run `vise init` to refresh the sidecar first).");
+    }
+    const findings = {};
+    for (const result of check.rules) {
+        if (!BASELINE_NON_GREEN.has(result.status))
+            continue;
+        const key = baselineKeyFor(result);
+        findings[key] = (findings[key] ?? 0) + 1;
+    }
+    const completeness_missing = (check.completeness?.missing ?? []).map((item) => item.id);
+    const selected_optional = [
+        ...(check.selectedOptionalCapabilities?.failed ?? []).map((item) => item.id),
+        ...(check.selectedOptionalCapabilities?.unknown ?? []),
+    ];
+    const baseline = {
+        baselined_at: new Date().toISOString(),
+        vise_version: packageVersion,
+        outcome: compliance.outcome,
+        ruleset_digest: compliance.ruleset_digest,
+        findings,
+        completeness_missing,
+        selected_optional,
+    };
+    await writeJson(baselinePath(repoRoot), baseline);
+    return {
+        status: "baselined",
+        baseline: complianceDirName + "/baseline.json",
+        outcome: baseline.outcome,
+        recorded: {
+            findings: Object.values(findings).reduce((a, b) => a + b, 0),
+            completeness_missing: completeness_missing.length,
+            selected_optional: selected_optional.length,
+        },
+        nextStep: "Implement your change, then run `vise check --new-only` to gate only on findings introduced since this baseline. Re-run `vise baseline` after the contract or outcome changes.",
+    };
+}
 function experienceReportPath(repoRoot) {
     return path.join(sidecarDir(repoRoot), experienceReportFileName);
 }

package/dist/tools/debug.js

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
 import { objectInput, optionalBooleanField, stringField, textResult } from "../types.js";
 import { checkCompliance, rulesById } from "./compliance.js";
 import { inspectProject } from "./project.js";
@@ -23,48 +25,94 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
     if (errorMessage.includes("method not found") || errorMessage.includes("Unresolved reference")) {
         likelyCause = "Potential Version Mismatch: The codebase is using a newer API pattern against an older SDK version installed in the project.";
     }
+    const missingModuleMatch = /Cannot find module ['"]([^'"]+)['"]/.exec(errorMessage)
+        ?? (/\bMODULE_NOT_FOUND\b/.test(errorMessage) ? /['"]([^'"]+)['"]/.exec(errorMessage) : null);
+    const missingModulePkg = missingModuleMatch && missingModuleMatch[1] && !/^[./]/.test(missingModuleMatch[1])
+        ? missingModuleMatch[1]
+        : undefined;
     const correlatedRules = [];
     let checkResult = null;
     try {
         checkResult = await checkCompliance(repoPath);
         const rulesMap = await rulesById();
         for (const rule of checkResult.rules) {
+            const contractRuleId = rule.contractRuleId ?? rule.ruleId;
+            const ruleDef = rulesMap.get(contractRuleId);
+            const symptoms = ruleDef?.symptoms || [];
+            if (symptoms.length === 0 || !symptoms.some((s) => errorMessage.includes(s))) {
+                continue;
+            }
             if (rule.status === "deterministic-fail" || rule.status === "attestation-needed") {
-                const contractRuleId = rule.contractRuleId ?? rule.ruleId;
-                const ruleDef = rulesMap.get(contractRuleId);
-                const symptoms = ruleDef?.symptoms || [];
-                if (symptoms.some(s => errorMessage.includes(s))) {
-                    correlatedRules.push({
-                        ruleId: rule.ruleId,
-                        status: "failed",
-                        impact: `This rule is currently failing and its known symptoms match the crash log.`,
-                    });
-                }
+                correlatedRules.push({
+                    ruleId: rule.ruleId,
+                    status: "failed",
+                    impact: `This rule is currently failing and its known symptoms match the crash log.`,
+                });
             }
             else if (rule.status === "attested") {
-                const contractRuleId = rule.contractRuleId ?? rule.ruleId;
-                const ruleDef = rulesMap.get(contractRuleId);
-                const symptoms = ruleDef?.symptoms || [];
-                if (symptoms.some(s => errorMessage.includes(s))) {
-                    correlatedRules.push({
-                        ruleId: rule.ruleId,
-                        status: "attested",
-                        attestation: rule.attestation,
-                        impact: `Warning: This rule was attested as passing, but a matching runtime exception was detected. The custom implementation may be flawed.`,
-                    });
-                }
+                correlatedRules.push({
+                    ruleId: rule.ruleId,
+                    status: "attested",
+                    attestation: rule.attestation,
+                    impact: `Warning: This rule was attested as passing, but a matching runtime exception was detected. The custom implementation may be flawed.`,
+                });
+            }
+            else {
+                correlatedRules.push({
+                    ruleId: rule.ruleId,
+                    status: rule.status,
+                    impact: `This rule's known symptoms match the crash log even though its compliance status is "${rule.status}". The deterministic check did not catch this, so the failure is likely runtime-only or outside the sensor's reach — review the implementation.`,
+                });
             }
         }
     }
     catch (err) {
     }
-    if (!likelyCause && correlatedRules.length > 0) {
-        likelyCause = `The crash is likely caused by the non-compliant implementation of ${correlatedRules.map(r => r.ruleId).join(", ")}.`;
+    const failingCorrelated = correlatedRules.filter((r) => r.status === "failed" || r.status === "attested");
+    const moduleDiagnosis = missingModulePkg
+        ? (() => {
+            const projectRoot = path.resolve(repoPath);
+            const pkg = missingModulePkg;
+            if (!existsSync(path.join(projectRoot, "node_modules"))) {
+                return {
+                    cause: `Dependencies are not installed — node_modules is absent at ${projectRoot}, so "${pkg}" cannot be resolved. This is a setup/environment issue, not a code defect.`,
+                    hint: `Run \`npm install\` at the project root to install declared dependencies, then retry. If "${pkg}" is not yet a dependency, add it: \`npm install ${pkg}\`.`,
+                };
+            }
+            if (!existsSync(path.join(projectRoot, "node_modules", ...pkg.split("/")))) {
+                return {
+                    cause: `The module "${pkg}" is not present in node_modules, so it cannot be resolved. This is a missing-dependency issue, not a code defect.`,
+                    hint: `Install it at the project root: \`npm install ${pkg}\`, then retry. (If it should already be installed, delete node_modules and re-run \`npm install\`.)`,
+                };
+            }
+            return {
+                cause: `The module "${pkg}" could not be resolved at runtime even though it appears installed. Confirm it is declared in package.json and the install is intact.`,
+                hint: `Re-run \`npm install\` to repair the dependency tree; if "${pkg}" is missing from package.json, add it with \`npm install ${pkg}\`.`,
+            };
+        })()
+        : undefined;
+    let missingModuleHint;
+    let secondaryModuleNote;
+    if (!likelyCause && failingCorrelated.length > 0) {
+        likelyCause = `The crash is likely caused by the non-compliant implementation of ${failingCorrelated.map(r => r.ruleId).join(", ")}.`;
+        if (moduleDiagnosis)
+            secondaryModuleNote = moduleDiagnosis.hint;
+    }
+    else if (!likelyCause && moduleDiagnosis) {
+        likelyCause = moduleDiagnosis.cause;
+        missingModuleHint = moduleDiagnosis.hint;
+    }
+    else if (!likelyCause && correlatedRules.length > 0) {
+        likelyCause = `The crash symptoms match the known signatures of ${correlatedRules.map(r => r.ruleId).join(", ")}, but ${correlatedRules.length === 1 ? "that rule passes its" : "those rules pass their"} compliance check — the cause is likely runtime-only or outside the deterministic sensor's reach.`;
     }
     else if (!likelyCause) {
         likelyCause = `An unknown ${exceptionClass || "runtime"} error occurred.`;
+        if (moduleDiagnosis)
+            secondaryModuleNote = moduleDiagnosis.hint;
     }
-    const suggestedRemediation = buildRemediation(correlatedRules, checkResult);
+    const suggestedRemediation = missingModuleHint
+        ? { action: missingModuleHint }
+        : buildRemediation(correlatedRules, checkResult);
     const repairBrief = buildRepairBrief(correlatedRules, checkResult, inspection.platforms, likelyCause);
     const payload = {
         correlatedRules,
@@ -73,6 +121,7 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
         extractedException: exceptionClass,
         suggestedRemediation,
         repairBrief,
+        ...(secondaryModuleNote ? { secondaryNotes: [secondaryModuleNote] } : {}),
         relevantDocs: [
             {
                 title: "Troubleshooting",
@@ -85,6 +134,7 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
             likelyCause: payload.likelyCause,
             correlatedRules: payload.correlatedRules,
             repairBrief: payload.repairBrief,
+            ...(secondaryModuleNote ? { secondaryNotes: [secondaryModuleNote] } : {}),
             relevantDocs: payload.relevantDocs,
         };
     }
@@ -106,8 +156,12 @@ function buildRemediation(correlatedRules, checkResult) {
             docRef: `vise explain ${cr.ruleId}`,
         };
     });
+    const failing = correlatedRules.filter((cr) => cr.status === "failed" || cr.status === "attested");
+    const action = failing.length > 0
+        ? "Repair the compliance failure(s) identified above."
+        : "The correlated rule(s) pass their deterministic compliance checks; investigate the runtime behavior of the listed rule(s). The failure is likely runtime-only or outside the sensor's reach — do not change the compliant code paths.";
     return {
-        action: "Repair the compliance failure(s) identified above.",
+        action,
         rules,
     };
 }
@@ -143,7 +197,10 @@ function buildRepairBrief(correlatedRules, checkResult, platforms, likelyCause)
 }
 function pickPrimaryRuleId(correlatedRules) {
     const failed = correlatedRules.find((rule) => rule.status === "failed");
-    return failed?.ruleId ?? correlatedRules[0]?.ruleId ?? null;
+    if (failed)
+        return failed.ruleId;
+    const attested = correlatedRules.find((rule) => rule.status === "attested");
+    return attested?.ruleId ?? null;
 }
 function candidateFilesForRule(ruleId, checkResult) {
     if (!checkResult) {