@amityco/social-plus-vise 1.3.0 → 1.4.0

package/dist/tools/compliance.js

@@ -2,11 +2,16 @@ 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 { CLASSIFY_ORDER, 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";
@@ -335,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;
@@ -356,15 +381,31 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         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}. ` +
@@ -408,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,
@@ -434,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,
@@ -442,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) {
@@ -455,73 +618,17 @@ 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,
@@ -755,17 +862,42 @@ export async function checkCompliance(repoPath, options = {}) {
     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);
@@ -794,20 +926,18 @@ export async function checkCompliance(repoPath, options = {}) {
         }
         const hasDeterministicChecks = (rule.enforcement.deterministic ?? []).length > 0;
         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";
+        const deterministic = hasDeterministicChecks
+            ? await assessDeterministicChecks(rule, findingsById, platforms, canonicalPlatform, repoRoot)
+            : undefined;
+        const finding = deterministic?.finding;
+        if (hasDeterministicChecks && deterministic?.passed) {
             results.push({
-                ...identity,
+                ...checkRuleIdentity(rule.id),
                 title: rule.title,
                 severity: rule.severity,
                 status: "deterministic-pass",
-                pass_basis: passBasis,
-                evidence: { source: "validate_setup", finding_absent: deterministicFindingIds(rule) },
+                pass_basis: deterministic.pass_basis,
+                evidence: deterministic.evidence,
             });
             continue;
         }
@@ -823,10 +953,10 @@ export async function checkCompliance(repoPath, options = {}) {
                     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)),
@@ -857,6 +987,29 @@ export async function checkCompliance(repoPath, options = {}) {
                     });
                     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),
@@ -886,6 +1039,9 @@ export async function checkCompliance(repoPath, options = {}) {
         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.";
         }
@@ -896,7 +1052,7 @@ export async function checkCompliance(repoPath, options = {}) {
             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)),
@@ -921,16 +1077,20 @@ export async function checkCompliance(repoPath, options = {}) {
     }
     const summary = summarize(results);
     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: deterministicPasses.filter((result) => result.pass_basis !== "undetected-platform").length,
-            undetected_platform: deterministicPasses.filter((result) => result.pass_basis === "undetected-platform").length,
+            absent: absencePasses,
+            undetected_platform: undetectedPlatformPasses,
+            ...(runtimeSmokePasses > 0 ? { runtime_smoke: runtimeSmokePasses } : {}),
         }
         : 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".`
+        ? `${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
@@ -997,14 +1157,18 @@ export async function checkCompliance(repoPath, options = {}) {
     });
     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,
@@ -1019,6 +1183,7 @@ export async function checkCompliance(repoPath, options = {}) {
         ...(baselineReport ? { baseline: baselineReport } : {}),
         uxHarness: uxAssessment,
         experienceReport,
+        ...(attestationHygiene ? { attestation_hygiene: attestationHygiene } : {}),
     };
 }
 export async function generateExperienceReport(repoPath, options = {}) {
@@ -1086,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",
@@ -1136,10 +1387,12 @@ export async function syncCompliance(repoPath) {
                 continue;
             }
             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 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);
@@ -1159,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) {
@@ -1202,10 +1456,16 @@ 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);
+    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 {
@@ -1214,6 +1474,7 @@ 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 } : {}),
     };
 }
@@ -1321,6 +1582,7 @@ export async function statusCompliance(repoPath, options = {}) {
         ...(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: {
@@ -1490,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);
@@ -1501,32 +1944,39 @@ function deterministicFinding(rule, findingsById) {
 }
 async function liveSensorContradiction(repoRoot, compliance, rule) {
     if (deterministicFindingIds(rule).length === 0) {
-        return undefined;
+        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 undefined;
+        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 undefined;
+        return { violatorFiles: [] };
     }
+    const violatorFiles = await ruleViolatorFiles(repoRoot, sourceRootForCompliance(repoRoot, compliance), rule, findingsByIdAll);
     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 } : {}),
+        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) {
@@ -1534,6 +1984,117 @@ function deterministicFindingIds(rule) {
         .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 = [];
@@ -1546,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}`);
@@ -1568,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(),
     };
@@ -1716,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 ?? []) {
@@ -1805,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()) {
@@ -1858,9 +2488,6 @@ function sidecarReadme(compliance) {
         "",
     ].join("\n");
 }
-function sidecarDir(repoRoot) {
-    return path.join(repoRoot, complianceDirName);
-}
 function attestationsDir(repoRoot) {
     return path.join(sidecarDir(repoRoot), attestationsDirName);
 }