@amityco/social-plus-vise 1.2.0 → 1.4.0

package/dist/tools/compliance.js

@@ -1,11 +1,17 @@
 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 { sidecarDir } from "../sidecar.js";
 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 { applyBlockProvidedCompleteness, assessProjectCompleteness, assessProjectSelectedOptionalCapabilities, availableOptionalCapabilityIds, platformCapabilityAvailability, selectedOptionalCapabilityIds, } from "../capabilities.js";
+import { CLASSIFY_ORDER, getOutcomeDefinition, planContextFor, resolveOutcome, } from "../outcomes.js";
 import { contractRuleCandidatesForPublicId, hasMultipleContractRuleCandidates, productExpectationBindingForSensor, productExpectationTitle, publicProductRuleId, } from "../productExpectations.js";
 import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
+import { assembleIntake } from "../intake.js";
+import { clarifyDimensions, clarifyGuidance } from "../requestReadiness.js";
+import { recommendSolutionPath } from "../solutionPath.js";
+import { recommendUIKitCustomization } from "../uikitCustomization.js";
 import { packageVersion } from "../version.js";
 import { DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID, buildDesignBrief, designContractConfirmationFromAnswers, designPreviewPath, readDesignContract, } from "./design.js";
 import { installedBlockProvidedCapabilities } from "./blocks.js";
@@ -210,7 +216,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 +295,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",
@@ -327,6 +340,26 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
     const creativeSelection = storedCreativeSelection && creativeSelectionAppliesToRequest(storedCreativeSelection, request)
         ? storedCreativeSelection
         : undefined;
+    if (options.allowUnresolvedIntake !== true) {
+        const platformDetected = inspection.platforms.length > 0;
+        const initSolutionPath = recommendSolutionPath(request, answers);
+        const initUikit = recommendUIKitCustomization({ request, answers, platform, solutionPath: initSolutionPath });
+        const clarify = clarifyGuidance(clarifyDimensions({
+            outcome,
+            platformDetected,
+            uikitGuidedUnknown: platformDetected && outcome === "unknown" && Boolean(initUikit),
+            creativeSelected: Boolean(creativeSelection),
+        }));
+        if (clarify) {
+            return {
+                status: "needs-clarification",
+                exitCode: 7,
+                outcome,
+                clarify,
+                nextStep: `${clarify.nextStep} (Or pass --allow-unresolved-intake for retrospective/harness initialization.)`,
+            };
+        }
+    }
     const uxHarness = creativeSelection
         ? await buildUxHarness({ repoPath: repoRoot, surfacePath, selection: creativeSelection, write: true })
         : undefined;
@@ -341,16 +374,39 @@ 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)
-            .map((question) => question.id);
+        const blockingQuestions = intake.questions.filter((question) => question.blocksImplementationWhenMissing);
+        const blockingIds = blockingQuestions.map((question) => question.id);
         const answerExample = blockingIds.map((id) => `${id}=<value>`).join(" --answer ");
         return {
             status: "needs-clarification",
             exitCode: 7,
             outcome,
             intake,
+            decisionChecklist: blockingQuestions.map((question) => ({
+                id: question.id,
+                question: question.question,
+                why: question.why,
+                options: question.options,
+            })),
+            unattended: {
+                status: "blocked",
+                mode: "handoff-required",
+                reason: "Blocking intake answers are required before this surface can be initialized.",
+                instruction: "If the user is not available, stop and return the blocking intake questions. Do not invent scope, route, identity, region, design, or capability answers.",
+                allowedActions: ["read-only inspect/plan output", "collect exact --answer values from the user"],
+                resumeWhen: [
+                    "every blocking intake id has an explicit user-provided answer",
+                    "init is re-run with one repeated --answer id=value flag per blocking id",
+                ],
+            },
+            ...(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). " +
@@ -393,6 +449,7 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
     });
     await writeJson(path.join(sidecarDir(repoRoot), "inspection.json"), inspection);
     await writeFile(path.join(sidecarDir(repoRoot), "README.md"), sidecarReadme(compliance), "utf8");
+    const runtimeSmokeTemplate = await writeRuntimeSmokeTemplateIfNeeded(repoRoot, platform, outcome);
     const checkSnapshot = await checkCompliance(repoPath);
     await writeJson(path.join(sidecarDir(repoRoot), "findings.json"), {
         snapshot_at: compliance.generated_at,
@@ -401,8 +458,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.`);
     }
@@ -417,6 +476,7 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         ...(uxHarness ? { ux_harness: uxHarnessSummary(uxHarness) } : {}),
         ...(compliance.design_contract && { design_contract: compliance.design_contract }),
         ...(selectedOptionalCapabilities.length > 0 && { selected_optional_capabilities: selectedOptionalCapabilities }),
+        ...(runtimeSmokeTemplate ? { runtime_smoke: runtimeSmokeTemplate } : {}),
         intake: {
             status: intake.status,
             remainingBlocking: intake.remainingBlocking,
@@ -425,7 +485,127 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
             answers: intake.answers,
         },
         ...(warnings.length > 0 && { warnings }),
-        nextStep: "Run vise check, then implement until rules pass deterministically or are attested.",
+        nextStep: runtimeSmokeTemplate
+            ? "Run vise check, implement until rules pass, then cold-launch the app, capture VISE_SMOKE logs, run vise smoke, and rerun vise check before completing the surface."
+            : "Run vise check, then implement until rules pass deterministically or are attested.",
+    };
+}
+function runtimeSmokeSurfaceForOutcome(outcome) {
+    switch (outcome) {
+        case "add-community":
+            return {
+                id: "community",
+                expect: "populated",
+                launch: "Cold-launch into the product route that lists/selects the current community target.",
+            };
+        case "add-feed":
+            return {
+                id: "feed",
+                expect: "populated",
+                launch: "Cold-launch into the product route that mounts the selected feed/post collection.",
+            };
+        case "add-comments":
+            return {
+                id: "comments",
+                expect: "populated",
+                launch: "Cold-launch into a product post/thread route with a visible parent post and comment collection.",
+            };
+        case "add-chat":
+            return {
+                id: "chat",
+                expect: "populated",
+                launch: "Cold-launch into the product inbox or selected channel route with readable messages.",
+            };
+        case "add-follow":
+            return {
+                id: "profile",
+                expect: "populated",
+                launch: "Cold-launch into a product profile/member route with relationship data visible.",
+            };
+        case "add-notifications":
+            return {
+                id: "notifications",
+                expect: "resolved",
+                launch: "Cold-launch into the product notification tray/settings route.",
+            };
+        default:
+            return null;
+    }
+}
+function runtimeSmokeCaptureRecipe(platform) {
+    const normalized = platform.toLowerCase();
+    if (normalized === "android") {
+        return {
+            log: "adb logcat",
+            steps: [
+                "adb logcat -c",
+                "Cold-launch the app into the social route and wait until the visible collection resolves.",
+                "adb logcat -d -v time | grep VISE_SMOKE > sp-vise/evidence/runtime-smoke.log",
+                "vise smoke . --log sp-vise/evidence/runtime-smoke.log",
+            ],
+        };
+    }
+    if (normalized === "ios") {
+        return {
+            log: "simctl unified log",
+            steps: [
+                "xcrun simctl launch --terminate-running-process <device> <bundle-id>",
+                "Wait until the visible collection resolves.",
+                "xcrun simctl spawn <device> log show --style compact --last 3m --predicate 'eventMessage CONTAINS \"VISE_SMOKE\"' > sp-vise/evidence/runtime-smoke.log",
+                "vise smoke . --log sp-vise/evidence/runtime-smoke.log",
+            ],
+        };
+    }
+    if (normalized === "flutter") {
+        return {
+            log: "flutter run logs or adb logcat",
+            steps: [
+                "Use an ignored define file such as .dart_tool/vise-runtime-defines.env for runtime values.",
+                "Cold-launch the app and wait until the collection resolves.",
+                "Capture debugPrint VISE_SMOKE lines from flutter run logs or adb logcat into sp-vise/evidence/runtime-smoke.log.",
+                "vise smoke . --log sp-vise/evidence/runtime-smoke.log",
+            ],
+        };
+    }
+    if (normalized === "react-native") {
+        return {
+            log: "Metro/device logs",
+            steps: [
+                "Cold-launch the app and wait until the collection resolves.",
+                "Capture console.info VISE_SMOKE lines from Metro or adb logcat into sp-vise/evidence/runtime-smoke.log.",
+                "vise smoke . --log sp-vise/evidence/runtime-smoke.log",
+            ],
+        };
+    }
+    return {
+        log: "browser or app runtime log",
+        steps: [
+            "Cold-load the route that mounts the collection surface.",
+            "Capture console.info VISE_SMOKE lines into sp-vise/evidence/runtime-smoke.log.",
+            "vise smoke . --log sp-vise/evidence/runtime-smoke.log",
+        ],
+    };
+}
+async function writeRuntimeSmokeTemplateIfNeeded(repoRoot, platform, outcome) {
+    const surface = runtimeSmokeSurfaceForOutcome(outcome);
+    if (!surface)
+        return null;
+    const smokePath = path.join(sidecarDir(repoRoot), "smoke.json");
+    if (existsSync(smokePath)) {
+        return { status: "existing", path: "sp-vise/smoke.json", surface: surface.id };
+    }
+    const platformName = platform || "unknown";
+    await writeJson(smokePath, {
+        platform: platformName,
+        surfaces: [surface],
+        capture: runtimeSmokeCaptureRecipe(platformName),
+    });
+    return {
+        status: "created",
+        path: "sp-vise/smoke.json",
+        surface: surface.id,
+        expect: surface.expect,
+        capture: runtimeSmokeCaptureRecipe(platformName),
     };
 }
 function intakeAuditFor(args) {
@@ -438,79 +618,61 @@ function intakeAuditFor(args) {
         designSignals: args.designSignals,
         answers: args.answers,
     });
-    const questions = [...getOutcomeDefinition(args.outcome).intakeQuestions(ctx)];
-    if (args.designReview?.status === "needs-confirmation" && !hasAnswer(ctx.answers, DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID)) {
-        questions.push({
-            id: DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID,
-            question: `Open ${args.designReview.previewPath} and confirm whether this design preview/contract should be used for the social UI.`,
-            why: "A design contract must be explicitly accepted before Vise can feed it forward or let the agent claim design conformance. If it is wrong, reject it and provide the correct design source.",
-            required: true,
-            blocksImplementationWhenMissing: true,
-            options: ["yes", "no"],
-        });
-    }
-    if (args.designReview?.status === "rejected" && !hasAnswer(ctx.answers, "design_source")) {
-        questions.push({
-            id: "design_source",
-            question: "What design source should replace the rejected preview/contract?",
-            why: "The current design preview was rejected, so Vise must not use it. Provide a prototype, screenshot, theme/token file, or explicitly say to proceed without a design-conformance claim.",
-            required: true,
-            blocksImplementationWhenMissing: true,
-        });
-    }
-    if (ctx.mentionsDesign && ctx.designSignals.length === 0 && !hasAnswer(ctx.answers, "design_source")) {
-        questions.push({
-            id: "design_source",
-            question: "Where are the app's design tokens, theme, or reusable UI components defined?",
-            why: "The user asked to match the existing design, and no local design source was detected.",
-            required: true,
-            blocksImplementationWhenMissing: true,
-        });
-    }
-    if (ctx.mentionsDesign && ctx.designSignals.length > 0 && !hasAnswer(ctx.answers, "confirm_design_source")) {
-        questions.push({
-            id: "confirm_design_source",
-            question: `Should the social UI use the detected design source(s): ${ctx.designSignals.map((signal) => signal.file).join(", ")}?`,
-            why: "Vise found likely design evidence, but the user or host agent should confirm it is the right source before UI edits.",
-            required: true,
-            blocksImplementationWhenMissing: false,
-            options: ["yes", "use another source"],
-        });
-    }
-    if (args.designBrief &&
-        args.designReview?.status === "accepted" &&
-        (args.outcome === "add-feed" || args.outcome === "add-chat") &&
-        !args.designBrief.roles.some((role) => role.role === "primaryAction") &&
-        !hasAnswer(ctx.answers, "primary_action_token")) {
-        questions.push({
-            id: "primary_action_token",
-            question: "Which design token (or color value) should be used as the primary action color? No primary-action token was confidently identified in the design contract.",
-            why: "A primary action colour is needed for interactive elements (composer button, own-message bubble). Without a confident token, the agent must guess or omit it.",
-            required: false,
-            blocksImplementationWhenMissing: false,
-        });
-    }
-    const availableOptionalIds = availableOptionalCapabilityIds(args.capabilityAvailability);
-    const optionalChoices = args.outcome === "add-feed" ? optionalCapabilityChecklist(args.outcome, availableOptionalIds) : [];
-    if (args.outcome === "add-feed" && optionalChoices.length > 0 && !hasAnswer(ctx.answers, "feed_optional_capabilities")) {
-        questions.push({
-            id: "feed_optional_capabilities",
-            question: `Which optional feed capabilities should be in scope on ${platform}: ${optionalChoices.map((capability) => capability.id).join(", ")}, or none?`,
-            why: "These capabilities are useful for full feeds, but should become enforceable only after the customer explicitly opts in. Vise only lists capabilities that appear available in the platform SDK surface; unsupported capabilities must be treated as out of scope or confirmed from docs.",
-            required: false,
-            blocksImplementationWhenMissing: false,
-            options: ["none", ...optionalChoices.map((capability) => capability.id)],
-        });
-    }
-    const remainingBlocking = questions.filter((question) => question.blocksImplementationWhenMissing).length;
+    const outcomeQuestions = getOutcomeDefinition(args.outcome).intakeQuestions(ctx);
+    const { questions, remainingBlocking, status } = assembleIntake({
+        ctx,
+        outcomeQuestions,
+        outcome: args.outcome,
+        designBrief: args.designBrief,
+        capabilityAvailability: args.capabilityAvailability,
+        designReview: args.designReview,
+    });
     return {
-        status: remainingBlocking > 0 ? "needs-clarification" : "ready",
+        status,
         questions,
         answers: args.answers,
         remainingBlocking,
         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 +842,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,16 +862,42 @@ 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"];
+    if (compliance.rules.length === 0) {
+        const expectedRules = await applicableRules(compliance.outcome, platforms);
+        if (expectedRules.length > 0) {
+            return {
+                status: "contract-drift",
+                exitCode: 4,
+                outcome: compliance.outcome,
+                surfacePath: compliance.surface?.path,
+                summary: { "contract-drift": 1 },
+                rules: [
+                    {
+                        ruleId: "contract.ruleset",
+                        title: "Compliance ruleset is empty but a social.plus integration was detected",
+                        severity: "error",
+                        status: "stale",
+                        reason: `sp-vise/compliance.json baked 0 compliance rules, but a social.plus integration was detected for platform(s) ${platforms.join(", ")} (${expectedRules.length} rule(s) apply). The sidecar was initialized before the platform was detectable (e.g. a CDN / no-package.json integration whose SDK usage is only in source) or is stale — a green here would certify unverified SDK code. Re-run \`vise init\` to bake the ruleset, then \`vise check\`.`,
+                    },
+                ],
+            };
+        }
+    }
+    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();
+    const findingsByIdAll = new Map();
     for (const finding of findings) {
         findingsById.set(finding.ruleId, finding);
+        appendFinding(findingsByIdAll, finding.ruleId, finding);
         if (finding.sensorId) {
             findingsById.set(finding.sensorId, finding);
+            appendFinding(findingsByIdAll, finding.sensorId, finding);
         }
     }
     const attestations = await readAttestations(repoRoot);
+    const attestationHygiene = await readAttestationHygiene(repoRoot, compliance);
     const results = [];
     for (const ref of compliance.rules) {
         const rule = rules.get(ref.rule_id);
@@ -738,14 +926,18 @@ export async function checkCompliance(repoPath) {
         }
         const hasDeterministicChecks = (rule.enforcement.deterministic ?? []).length > 0;
         const isInferential = !hasDeterministicChecks && !!rule.enforcement.inferential;
-        const finding = hasDeterministicChecks ? deterministicFinding(rule, findingsById) : undefined;
-        if (hasDeterministicChecks && !finding) {
+        const deterministic = hasDeterministicChecks
+            ? await assessDeterministicChecks(rule, findingsById, platforms, canonicalPlatform, repoRoot)
+            : undefined;
+        const finding = deterministic?.finding;
+        if (hasDeterministicChecks && deterministic?.passed) {
             results.push({
                 ...checkRuleIdentity(rule.id),
                 title: rule.title,
                 severity: rule.severity,
                 status: "deterministic-pass",
-                evidence: { source: "validate_setup", finding_absent: deterministicFindingIds(rule) },
+                pass_basis: deterministic.pass_basis,
+                evidence: deterministic.evidence,
             });
             continue;
         }
@@ -761,10 +953,10 @@ export async function checkCompliance(repoPath) {
                     reason: rule.advisory
                         ? "Advisory: informational only — does not affect compliance status."
                         : rule.enforcement.attestation.allowed
-                            ? "Current deterministic check failed; previously synced deterministic-pass evidence is stale."
-                            : "Current deterministic check failed; this rule does not allow attestation.",
+                            ? `Current deterministic check failed; previously synced deterministic-pass evidence is stale.${deterministic?.reason ? ` ${deterministic.reason}` : ""}`
+                            : (deterministic?.reason ?? "Current deterministic check failed; this rule does not allow attestation."),
                     finding,
-                    recommendation: finding?.recommendation,
+                    recommendation: finding?.recommendation ?? deterministic?.recommendation,
                     rationale: rule.rationale,
                     current_rule: ruleSummary(rule),
                     ...(failStatus === "attestation-needed" && rule.enforcement.attestation.allowed && attestHint(rule, compliance)),
@@ -795,6 +987,29 @@ export async function checkCompliance(repoPath) {
                     });
                     continue;
                 }
+                if (attestation.file_scoped === true && isFileScopableRule(rule)) {
+                    const coveredFiles = new Set((attestation.source_fingerprints ?? []).map((fp) => fp.path));
+                    const uncovered = await ruleUncoveredViolators(repoRoot, sourceRootForCompliance(repoRoot, compliance), rule, findingsByIdAll, coveredFiles);
+                    if (uncovered.length > 0) {
+                        const scopeStatus = rule.advisory ? "advisory" : rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail";
+                        const uncoveredPaths = uniqueStrings(uncovered.map((f) => f.file).filter((f) => !!f));
+                        results.push({
+                            ...checkRuleIdentity(rule.id),
+                            title: rule.title,
+                            severity: rule.severity,
+                            status: scopeStatus,
+                            reason: rule.advisory
+                                ? "Advisory: informational only — does not affect compliance status."
+                                : `Attestation covers ${[...coveredFiles].join(", ")}; the rule also fires in ${uncoveredPaths.join(", ")}, which this attestation does not cover. Review the new violation(s) and re-attest (or fix them).`,
+                            finding: uncovered[0],
+                            recommendation: uncovered[0].recommendation,
+                            rationale: rule.rationale,
+                            current_rule: ruleSummary(rule),
+                            ...(scopeStatus === "attestation-needed" && rule.enforcement.attestation.allowed && attestHint(rule, compliance)),
+                        });
+                        continue;
+                    }
+                }
                 const deprecated = grandfathered && (rule.deprecated_versions ?? []).includes(attestation.rule_version);
                 results.push({
                     ...checkRuleIdentity(rule.id),
@@ -824,6 +1039,9 @@ export async function checkCompliance(repoPath) {
         else if (isInferential) {
             fallbackReason = "Inferential check required. Please provide a host-agent attestation.";
         }
+        else if (deterministic?.reason) {
+            fallbackReason = deterministic.reason;
+        }
         else if (rule.enforcement.attestation.allowed) {
             fallbackReason = "Deterministic check failed and no valid attestation exists.";
         }
@@ -834,7 +1052,7 @@ export async function checkCompliance(repoPath) {
             status: baseStatus,
             reason: fallbackReason,
             finding,
-            recommendation: finding?.recommendation,
+            recommendation: finding?.recommendation ?? deterministic?.recommendation,
             current_rule: ruleSummary(rule),
             ...(isInferential && { inferential_prompt: rule.enforcement.inferential?.prompt }),
             ...(baseStatus === "attestation-needed" && rule.enforcement.attestation.allowed && attestHint(rule, compliance)),
@@ -858,49 +1076,99 @@ 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 runtimeSmokePasses = deterministicPasses.filter((result) => result.pass_basis === "runtime-smoke").length;
+    const undetectedPlatformPasses = deterministicPasses.filter((result) => result.pass_basis === "undetected-platform").length;
+    const absencePasses = deterministicPasses.length - runtimeSmokePasses - undetectedPlatformPasses;
+    const evidenceBasis = deterministicPasses.length > 0
+        ? {
+            absent: absencePasses,
+            undetected_platform: undetectedPlatformPasses,
+            ...(runtimeSmokePasses > 0 ? { runtime_smoke: runtimeSmokePasses } : {}),
+        }
+        : undefined;
+    const evidenceBasisNote = evidenceBasis
+        ? `${absencePasses + undetectedPlatformPasses} of the passing rules passed by ABSENCE (the sensor found no violation, which is not positive proof the feature was built).${undetectedPlatformPasses > 0
+            ? ` ${undetectedPlatformPasses} of those are vacuous — the rule's platform was not detected in this project, so no sensor ran.`
+            : ""}${runtimeSmokePasses > 0 ? ` ${runtimeSmokePasses} deterministic-pass rule(s) cleared with runtime-smoke evidence from a mounted app.` : ""} Treat absence-based passes 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({
-        checkStatus: status,
-        exitCode,
-        summary,
-        designContract: compliance.design_contract,
-        uxAssessment,
-        uxHarness,
-    });
+    const openReviewItems = await experienceOpenReviewItems(repoRoot, findings);
+    const experienceReport = {
+        ...buildExperienceReport({
+            checkStatus: status,
+            exitCode,
+            summary,
+            designContract: compliance.design_contract,
+            uxAssessment,
+            uxHarness,
+        }),
+        openReviewItems,
+    };
     return {
         status,
         exitCode,
@@ -908,10 +1176,14 @@ 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,
+        ...(attestationHygiene ? { attestation_hygiene: attestationHygiene } : {}),
     };
 }
 export async function generateExperienceReport(repoPath, options = {}) {
@@ -979,6 +1251,92 @@ function sensorReviewGaps(raw) {
     }
     return gaps.slice(0, 50);
 }
+async function experienceOpenReviewItems(repoRoot, findings) {
+    const intake = await readIntakeReviewItems(repoRoot);
+    const validateFindings = validateFindingReviewItems(findings);
+    const needsReview = intake.unresolvedNonblockingIntake.length > 0 ||
+        intake.acknowledgedBlockingIntake.length > 0 ||
+        validateFindings.length > 0;
+    return {
+        status: needsReview ? "needs-review" : "clear",
+        unresolvedNonblockingIntake: intake.unresolvedNonblockingIntake,
+        acknowledgedBlockingIntake: intake.acknowledgedBlockingIntake,
+        validateFindings,
+        nextStep: needsReview
+            ? "Surface these items in the final handoff. Answer or explicitly scope unresolved intake, and treat validate findings as remaining review work even when vise check is green."
+            : "No unresolved intake or validate findings were observed in the current report inputs.",
+    };
+}
+async function readIntakeReviewItems(repoRoot) {
+    const sidecar = await readJsonIfExists(path.join(sidecarDir(repoRoot), "intake.json"));
+    if (!sidecar) {
+        return { unresolvedNonblockingIntake: [], acknowledgedBlockingIntake: [] };
+    }
+    const answers = sidecar.answers && typeof sidecar.answers === "object" && !Array.isArray(sidecar.answers)
+        ? sidecar.answers
+        : {};
+    const questions = Array.isArray(sidecar.questions) ? sidecar.questions : [];
+    const unresolved = questions
+        .map(intakeQuestionReviewItem)
+        .filter((item) => Boolean(item))
+        .filter((item) => !hasNonEmptyAnswer(answers, item.id));
+    const acknowledgedBlocking = sidecar.acknowledged_unresolved_blocking === true
+        ? unresolved.filter((item) => item.blocking)
+        : [];
+    return {
+        unresolvedNonblockingIntake: unresolved.filter((item) => !item.blocking).map(stripBlockingFlag),
+        acknowledgedBlockingIntake: acknowledgedBlocking.map(stripBlockingFlag),
+    };
+}
+function intakeQuestionReviewItem(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return undefined;
+    }
+    const question = raw;
+    if (typeof question.id !== "string" || typeof question.question !== "string") {
+        return undefined;
+    }
+    return {
+        id: question.id,
+        question: question.question,
+        ...(typeof question.why === "string" ? { why: question.why } : {}),
+        ...(Array.isArray(question.options) ? { options: question.options.filter((option) => typeof option === "string") } : {}),
+        blocking: question.blocksImplementationWhenMissing === true,
+    };
+}
+function stripBlockingFlag(item) {
+    const { blocking: _blocking, ...rest } = item;
+    return rest;
+}
+function hasNonEmptyAnswer(answers, id) {
+    return Object.prototype.hasOwnProperty.call(answers, id) && String(answers[id] ?? "").trim() !== "";
+}
+function validateFindingReviewItems(findings) {
+    const items = [];
+    const seen = new Set();
+    for (const finding of findings) {
+        if (finding.severity !== "warning" && finding.severity !== "error") {
+            continue;
+        }
+        const key = `${finding.ruleId}|${finding.sensorId ?? ""}|${finding.file ?? ""}|${finding.message}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        items.push({
+            ruleId: finding.ruleId,
+            ...(finding.sensorId ? { sensorId: finding.sensorId } : {}),
+            severity: finding.severity,
+            message: finding.message,
+            ...(finding.file ? { file: finding.file } : {}),
+            ...(finding.recommendation ? { recommendation: finding.recommendation } : {}),
+        });
+        if (items.length >= 50) {
+            break;
+        }
+    }
+    return items;
+}
 function fallbackExperienceReport(check) {
     const uxAssessment = check.uxHarness ?? {
         status: "absent",
@@ -1028,7 +1386,14 @@ 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 === "runtime-smoke" ? "high" : passBasis === "undetected-platform" ? "low" : "medium";
+            const rationale = passBasis === "runtime-smoke"
+                ? "Deterministic check passed: runtime mount-smoke evidence shows the declared collection surface(s) resolved in the running app."
+                : 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);
         }
@@ -1047,6 +1412,7 @@ export async function syncCompliance(repoPath) {
         written,
         removed,
         last_synced_at: compliance.last_synced_at,
+        ...(check.attestation_hygiene ? { attestation_hygiene: check.attestation_hygiene } : {}),
     };
 }
 export async function attestRule(args) {
@@ -1090,9 +1456,16 @@ export async function attestRule(args) {
         throw new Error(`Rule does not allow local human attestations: ${args.ruleId}`);
     }
     validateEvidence(rule, args.evidence);
+    const { warning: sensorWarning, violatorFiles } = 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);
+    const sourceRoot = sourceRootForCompliance(repoRoot, compliance);
+    const evidenceFingerprints = await collectSourceFingerprints(repoRoot, sourceRoot, args.evidence);
+    const fileScoped = isFileScopableRule(rule);
+    const violatorFingerprints = fileScoped && violatorFiles.length > 0
+        ? await collectViolatorFingerprints(repoRoot, sourceRoot, violatorFiles, evidenceFingerprints)
+        : [];
+    const sourceFingerprints = [...evidenceFingerprints, ...violatorFingerprints];
+    const attestation = buildAttestation(compliance, rule, args.signer, args.confidence, args.identity, args.rationale, args.evidence, sourceFingerprints, fileScoped);
     const filePath = path.join(attestationsDir(repoRoot), attestationPathFor(contractRuleId));
     await writeJson(filePath, attestation);
     return {
@@ -1101,6 +1474,8 @@ export async function attestRule(args) {
         destination: filePath,
         signer_claim: attestation.signer_claim,
         source_fingerprints: sourceFingerprints,
+        ...(fileScoped ? { file_scoped: true, scoped_files: [...new Set(sourceFingerprints.map((fp) => fp.path))] } : {}),
+        ...(sensorWarning ? { sensor_warning: sensorWarning } : {}),
     };
 }
 export async function explainRule(ruleId) {
@@ -1124,6 +1499,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 +1520,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 +1532,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 +1578,11 @@ 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 } : {}),
+        ...(check.attestation_hygiene ? { attestation_hygiene: check.attestation_hygiene } : {}),
         ...(compliance?.design_contract && { design_contract: compliance.design_contract }),
         ...(engagement && {
             engagement: {
@@ -1331,6 +1752,187 @@ function contractDrift(compliance, rules) {
     }
     return results;
 }
+async function assessDeterministicChecks(rule, findingsById, platforms, canonicalPlatform, repoRoot) {
+    const checks = rule.enforcement.deterministic ?? [];
+    const passedEvidence = [];
+    let passBasis = "absent";
+    for (const check of checks) {
+        if (check.check === "validator-finding-absent") {
+            const finding = findingsById.get(check.finding_rule_id);
+            if (finding) {
+                return {
+                    passed: false,
+                    finding,
+                    reason: "Current deterministic validator check failed.",
+                    recommendation: finding.recommendation,
+                };
+            }
+            passedEvidence.push({ source: "validate_setup", finding_absent: [check.finding_rule_id] });
+            continue;
+        }
+        if (check.check === "runtime-smoke-evidence-passed") {
+            const smoke = await assessRuntimeSmokeEvidence(repoRoot, check);
+            if (!smoke.passed) {
+                return smoke;
+            }
+            if (smoke.evidence) {
+                passedEvidence.push(smoke.evidence);
+            }
+            passBasis = "runtime-smoke";
+            continue;
+        }
+        const unknown = check;
+        return {
+            passed: false,
+            reason: `Unsupported deterministic check kind: ${String(unknown.check ?? "(missing)")}.`,
+        };
+    }
+    if (passBasis !== "runtime-smoke") {
+        const identity = checkRuleIdentity(rule.id);
+        const rulePlatform = identity.validator?.platform;
+        passBasis =
+            rulePlatform && !platforms.some((p) => canonicalPlatform(p) === canonicalPlatform(rulePlatform))
+                ? "undetected-platform"
+                : "absent";
+    }
+    const validatorAbsent = deterministicFindingIds(rule);
+    const runtimeSmoke = passedEvidence.find((item) => item.source === "runtime_smoke");
+    let evidence;
+    if (runtimeSmoke && validatorAbsent.length > 0) {
+        evidence = {
+            source: "deterministic_checks",
+            validate_setup: { finding_absent: validatorAbsent },
+            runtime_smoke: runtimeSmoke,
+        };
+    }
+    else if (runtimeSmoke) {
+        evidence = runtimeSmoke;
+    }
+    else {
+        evidence = { source: "validate_setup", finding_absent: validatorAbsent };
+    }
+    return {
+        passed: true,
+        pass_basis: passBasis,
+        evidence,
+    };
+}
+async function assessRuntimeSmokeEvidence(repoRoot, check) {
+    const relativePath = check.path ?? "sp-vise/evidence/runtime-smoke.json";
+    const evidencePath = path.resolve(repoRoot, relativePath);
+    const displayPath = path.relative(repoRoot, evidencePath).split(path.sep).join(path.posix.sep);
+    const recommendation = runtimeSmokeCaptureRecommendationText();
+    if (!pathInside(repoRoot, evidencePath)) {
+        return {
+            passed: false,
+            reason: `Runtime smoke evidence path must stay inside the repository: ${relativePath}`,
+            recommendation,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(evidencePath, "utf8"));
+    }
+    catch {
+        return {
+            passed: false,
+            reason: `Missing or unreadable runtime smoke evidence at ${displayPath}.`,
+            recommendation,
+        };
+    }
+    const results = Array.isArray(parsed.results) ? parsed.results : [];
+    const surfaceResults = results.filter(isRuntimeSmokeSurfaceResult);
+    const failing = surfaceResults.filter((result) => result.verdict !== "pass");
+    const evidence = {
+        source: "runtime_smoke",
+        file: displayPath,
+        passed: parsed.passed === true,
+        ...(typeof parsed.platform === "string" ? { platform: parsed.platform } : {}),
+        results: surfaceResults,
+    };
+    if (parsed.passed !== true) {
+        const failedSurfaces = failing.map((result) => `${result.surface}:${result.state}`).join(", ");
+        return {
+            passed: false,
+            evidence,
+            reason: failedSurfaces
+                ? `Runtime smoke evidence at ${displayPath} did not pass (${failedSurfaces}).`
+                : `Runtime smoke evidence at ${displayPath} did not pass.`,
+            recommendation,
+        };
+    }
+    if (surfaceResults.length === 0) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence at ${displayPath} has passed=true but no surface results; rerun \`vise smoke\` so the gate can verify a mounted collection surface.`,
+            recommendation,
+        };
+    }
+    if (failing.length > 0) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence at ${displayPath} has passed=true but contains failing surface results (${failing.map((result) => result.surface).join(", ")}).`,
+            recommendation,
+        };
+    }
+    const smokeConfig = await readJsonIfExists(path.join(sidecarDir(repoRoot), "smoke.json"));
+    const expectedSurfaceIds = Array.isArray(smokeConfig?.surfaces)
+        ? smokeConfig.surfaces.map((surface) => surface.id).filter((id) => typeof id === "string" && id.length > 0)
+        : [];
+    if (expectedSurfaceIds.length > 0) {
+        const passedSurfaceIds = new Set(surfaceResults.filter((result) => result.verdict === "pass").map((result) => result.surface));
+        const missing = expectedSurfaceIds.filter((id) => !passedSurfaceIds.has(id));
+        if (missing.length > 0) {
+            return {
+                passed: false,
+                evidence,
+                reason: `Runtime smoke evidence at ${displayPath} does not include passing results for declared collection surface(s): ${missing.join(", ")}.`,
+                recommendation,
+            };
+        }
+        const expectedSurfacesById = new Map(smokeConfig?.surfaces
+            ?.filter((surface) => typeof surface.id === "string" && surface.id.length > 0)
+            .map((surface) => [surface.id, surface]) ?? []);
+        const underpopulated = surfaceResults.filter((result) => {
+            const expected = expectedSurfacesById.get(result.surface);
+            return expected?.expect === "populated" && result.verdict === "pass" && !runtimeSmokeStateHasPositiveCount(result.state);
+        });
+        if (underpopulated.length > 0) {
+            return {
+                passed: false,
+                evidence,
+                reason: `Runtime smoke evidence at ${displayPath} has passing populated surface result(s) without count > 0: ${underpopulated.map((result) => `${result.surface}:${result.state}`).join(", ")}.`,
+                recommendation,
+            };
+        }
+    }
+    return {
+        passed: true,
+        pass_basis: "runtime-smoke",
+        evidence,
+    };
+}
+function runtimeSmokeCaptureRecommendationText() {
+    return [
+        "Declare collection surfaces in `sp-vise/smoke.json` and emit `VISE_SMOKE surface=<id> state=loading|empty|loaded count=N|error:<message>` from the mounted app's real SDK query lifecycle; `expect: \"populated\"` requires loaded count=N with N > 0.",
+        "Cold-launch into the social route, wait for the visible collection to resolve, capture only the runtime log, run `vise smoke . --log <capture>`, then rerun `vise check`.",
+        "Android: `adb logcat -c` before launch, then `adb logcat -d -v time | grep VISE_SMOKE > sp-vise/evidence/runtime-smoke.log`.",
+        "iOS: after `simctl launch`, run `xcrun simctl spawn <device> log show --style compact --last 3m --predicate 'eventMessage CONTAINS \"VISE_SMOKE\"' > sp-vise/evidence/runtime-smoke.log`.",
+        "Web/React Native/Flutter: capture console/debugPrint VISE_SMOKE lines from the real mounted app, not a standalone SDK probe.",
+    ].join(" ");
+}
+function isRuntimeSmokeSurfaceResult(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const item = value;
+    return typeof item.surface === "string" && typeof item.state === "string" && typeof item.verdict === "string";
+}
+function runtimeSmokeStateHasPositiveCount(state) {
+    const match = state.match(/^loaded\b[\s\S]*?\bcount\s*=\s*(\d+)/i);
+    return Boolean(match && Number(match[1]) > 0);
+}
 function deterministicFinding(rule, findingsById) {
     for (const id of deterministicFindingIds(rule)) {
         const finding = findingsById.get(id);
@@ -1340,11 +1942,159 @@ function deterministicFinding(rule, findingsById) {
     }
     return undefined;
 }
+async function liveSensorContradiction(repoRoot, compliance, rule) {
+    if (deterministicFindingIds(rule).length === 0) {
+        return { violatorFiles: [] };
+    }
+    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 { violatorFiles: [] };
+    }
+    const allFindings = await Promise.all(platforms.map((platform) => validateSetup(inspection.effectiveRoot, platform)));
+    const findingsById = new Map();
+    const findingsByIdAll = new Map();
+    for (const finding of allFindings.flat()) {
+        findingsById.set(finding.ruleId, finding);
+        appendFinding(findingsByIdAll, finding.ruleId, finding);
+        if (finding.sensorId) {
+            findingsById.set(finding.sensorId, finding);
+            appendFinding(findingsByIdAll, finding.sensorId, finding);
+        }
+    }
+    const finding = deterministicFinding(rule, findingsById);
+    if (!finding) {
+        return { violatorFiles: [] };
+    }
+    const violatorFiles = await ruleViolatorFiles(repoRoot, sourceRootForCompliance(repoRoot, compliance), rule, findingsByIdAll);
+    return {
+        warning: {
+            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 } : {}),
+            },
+        },
+        violatorFiles,
+    };
+}
 function deterministicFindingIds(rule) {
     return (rule.enforcement.deterministic ?? [])
         .filter((check) => check.check === "validator-finding-absent")
         .map((check) => check.finding_rule_id);
 }
+function appendFinding(map, key, finding) {
+    const existing = map.get(key);
+    if (existing) {
+        existing.push(finding);
+    }
+    else {
+        map.set(key, [finding]);
+    }
+}
+const LIVE_SENSOR_VIOLATOR_FIELD = "live_sensor_violator";
+export const FILE_SCOPABLE_SENSOR_SUFFIXES = new Set([
+    "live-collection.api-mismatch",
+    "story.live-collection",
+    "search.live-collection",
+    "notification-tray.live-collection",
+    "event.live-collection",
+    "blocked-users.live-collection",
+    "invitation.live-collection",
+    "membership.use-live-collection",
+    "posts.status-filter-applied",
+    "posts.activity-tag-filter",
+    "posts.reaction-stale-post-ref",
+    "poll.vote-status-guard",
+    "pagination.cursor-opaque",
+    "posts.parent-child-rendered",
+    "comment.reference-type-enum",
+    "channel.type-matches-shape",
+    "reactions.configured-name-used",
+    "image-post.child-resolution-awaited",
+    "file-upload.via-amity-file-client",
+    "user.ban-state-respected",
+    "flag-count.not-leaked-to-non-mods",
+    "moderation.role-gated-action",
+    "custom-post-type.dataType-declared",
+    "feed.target-type-explicit",
+    "feed.post-datatype-handled",
+    "feed.ui-states-present",
+    "comments.target-resolved",
+    "chat.channel-type-dm",
+    "chat.deprecated-marker-sync",
+    "chat.deprecated-subchannel",
+    "livestream.deprecated-stream",
+    "follow.status-subscription",
+    "session-handler.retained",
+    "client.no-ssr-init",
+    "community.avatar-from-sdk",
+    "feed.poll-answer-data-shape",
+    "comments.query-has-limit",
+    "comments.thread-ui-states-present",
+    "chat.sort-explicit",
+    "profile.social-counts-from-sdk",
+    "community.display-name-from-sdk",
+    "feed.room-post-fetched",
+    "logging.no-secret-in-log",
+    "logging.no-pii-in-log",
+    "auth.no-literal-user-id",
+    "feed.target.literal",
+]);
+function isFileScopableRule(rule) {
+    return deterministicFindingIds(rule).some((id) => [...FILE_SCOPABLE_SENSOR_SUFFIXES].some((suffix) => id === suffix || id.endsWith(`.${suffix}`)));
+}
+async function ruleViolatorFiles(repoRoot, sourceRoot, rule, findingsByIdAll) {
+    const files = new Set();
+    for (const id of deterministicFindingIds(rule)) {
+        for (const finding of findingsByIdAll.get(id) ?? []) {
+            if (!finding.file)
+                continue;
+            const resolved = await resolveEvidenceSourcePath(repoRoot, sourceRoot, finding.file);
+            files.add(resolved ? resolved.relativePath : finding.file);
+        }
+    }
+    return [...files];
+}
+async function ruleUncoveredViolators(repoRoot, sourceRoot, rule, findingsByIdAll, coveredFiles) {
+    const uncovered = [];
+    const seen = new Set();
+    for (const id of deterministicFindingIds(rule)) {
+        for (const finding of findingsByIdAll.get(id) ?? []) {
+            if (!finding.file)
+                continue;
+            const resolved = await resolveEvidenceSourcePath(repoRoot, sourceRoot, finding.file);
+            const normalized = resolved ? resolved.relativePath : finding.file;
+            if (coveredFiles.has(normalized) || seen.has(normalized))
+                continue;
+            seen.add(normalized);
+            uncovered.push({ ...finding, file: normalized });
+        }
+    }
+    return uncovered;
+}
+async function collectViolatorFingerprints(repoRoot, sourceRoot, violatorFiles, evidenceFingerprints) {
+    const capturedAt = new Date().toISOString();
+    const alreadyFingerprinted = new Set(evidenceFingerprints.map((fp) => fp.path));
+    const fingerprints = [];
+    for (const file of violatorFiles) {
+        const resolved = await resolveEvidenceSourcePath(repoRoot, sourceRoot, file);
+        if (!resolved || alreadyFingerprinted.has(resolved.relativePath)) {
+            continue;
+        }
+        alreadyFingerprinted.add(resolved.relativePath);
+        const fileStat = await stat(resolved.absolutePath);
+        fingerprints.push({
+            evidence_field: LIVE_SENSOR_VIOLATOR_FIELD,
+            path: resolved.relativePath,
+            sha256: await digestFile(resolved.absolutePath),
+            size_bytes: fileStat.size,
+            captured_at: capturedAt,
+        });
+    }
+    return fingerprints;
+}
 function uniqueStrings(values) {
     const seen = new Set();
     const result = [];
@@ -1357,7 +2107,7 @@ function uniqueStrings(values) {
     }
     return result;
 }
-function buildAttestation(compliance, rule, signer, confidence, identity, rationale, evidence, sourceFingerprints = []) {
+function buildAttestation(compliance, rule, signer, confidence, identity, rationale, evidence, sourceFingerprints = [], fileScoped = false) {
     const ref = compliance.rules.find((item) => item.rule_id === rule.id);
     if (!ref) {
         throw new Error(`Rule is not in compliance contract: ${rule.id}`);
@@ -1379,6 +2129,7 @@ function buildAttestation(compliance, rule, signer, confidence, identity, ration
         signature: null,
         evidence,
         source_fingerprints: sourceFingerprints,
+        ...(fileScoped ? { file_scoped: true } : {}),
         rationale_for_attestation: rationale,
         attested_at: new Date().toISOString(),
     };
@@ -1527,13 +2278,19 @@ export function ruleSummary(rule) {
             pattern: "pattern" in blocker ? blocker.pattern : undefined,
             reason: blocker.reason,
         })),
-        deterministic_check_ids: (rule.enforcement.deterministic ?? []).map((check) => check.finding_rule_id),
+        deterministic_check_ids: (rule.enforcement.deterministic ?? []).map(deterministicCheckId),
         attestation_allowed: rule.enforcement.attestation.allowed,
         host_agent_min_confidence: rule.enforcement.attestation.host_agent_min_confidence,
         human_allowed: rule.enforcement.attestation.human_allowed !== false,
         evidence_field_names: (rule.enforcement.attestation.evidence_required ?? []).map((field) => field.field),
     };
 }
+function deterministicCheckId(check) {
+    if (check.check === "validator-finding-absent") {
+        return check.finding_rule_id;
+    }
+    return `${check.check}:${check.path ?? "sp-vise/evidence/runtime-smoke.json"}`;
+}
 export async function runBlockers(rule, root) {
     const fired = [];
     for (const blocker of rule.enforcement.blockers ?? []) {
@@ -1616,16 +2373,78 @@ async function readAttestations(repoRoot) {
         if (!entry.endsWith(".json")) {
             continue;
         }
-        const attestation = await readJsonIfExists(path.join(dir, entry));
-        if (attestation?.rule_id && attestation.payload_hash) {
-            const { payload_hash, ...withoutHash } = attestation;
-            if (digestJson(withoutHash) === payload_hash) {
-                result.set(attestation.rule_id, attestation);
-            }
+        const candidate = await readAttestationCandidate(path.join(dir, entry));
+        if (candidate.status === "valid") {
+            result.set(candidate.attestation.rule_id, candidate.attestation);
         }
     }
     return result;
 }
+async function readAttestationHygiene(repoRoot, compliance) {
+    const dir = attestationsDir(repoRoot);
+    const activeRuleIds = new Set(compliance.rules.map((rule) => rule.rule_id));
+    const ignored = [];
+    const invalid = [];
+    let entries = [];
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".json")) {
+            continue;
+        }
+        const rel = path.posix.join(complianceDirName, attestationsDirName, entry);
+        const candidate = await readAttestationCandidate(path.join(dir, entry));
+        if (candidate.status === "invalid") {
+            invalid.push({ file: rel, ...(candidate.rule_id ? { rule_id: candidate.rule_id } : {}), reason: candidate.reason });
+            continue;
+        }
+        if (!activeRuleIds.has(candidate.attestation.rule_id)) {
+            ignored.push({
+                file: rel,
+                rule_id: candidate.attestation.rule_id,
+                reason: "Attestation rule_id is not in the current compliance contract. It may be stale, off-platform, or from a previous sidecar scope; it is ignored by vise check.",
+            });
+        }
+    }
+    if (ignored.length === 0 && invalid.length === 0) {
+        return undefined;
+    }
+    return {
+        status: "needs-review",
+        ignored,
+        invalid,
+        nextStep: "Review ignored/invalid attestation files before using the evidence trail for handoff. Remove stale files only when you are sure they are unrelated, or re-run vise init/check/sync for the intended scope.",
+    };
+}
+async function readAttestationCandidate(filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return { status: "invalid", reason: "Attestation file is not valid JSON." };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { status: "invalid", reason: "Attestation file is not a JSON object." };
+    }
+    const attestation = parsed;
+    const ruleId = typeof attestation.rule_id === "string" ? attestation.rule_id : undefined;
+    if (!ruleId) {
+        return { status: "invalid", reason: "Attestation file is missing rule_id." };
+    }
+    if (typeof attestation.payload_hash !== "string" || attestation.payload_hash.length === 0) {
+        return { status: "invalid", rule_id: ruleId, reason: "Attestation file is missing payload_hash." };
+    }
+    const { payload_hash, ...withoutHash } = attestation;
+    if (digestJson(withoutHash) !== payload_hash) {
+        return { status: "invalid", rule_id: ruleId, reason: "Attestation payload_hash does not match the file contents." };
+    }
+    return { status: "valid", attestation };
+}
 async function readJsonIfExists(filePath) {
     try {
         if (!(await stat(filePath)).isFile()) {
@@ -1669,15 +2488,77 @@ function sidecarReadme(compliance) {
         "",
     ].join("\n");
 }
-function sidecarDir(repoRoot) {
-    return path.join(repoRoot, complianceDirName);
-}
 function attestationsDir(repoRoot) {
     return path.join(sidecarDir(repoRoot), attestationsDirName);
 }
 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);
 }