@amityco/social-plus-vise 1.4.6 → 1.6.0

package/dist/tools/compliance.js

@@ -13,10 +13,12 @@ import { clarifyDimensions, clarifyGuidance } from "../requestReadiness.js";
 import { recommendSolutionPath } from "../solutionPath.js";
 import { recommendUIKitCustomization } from "../uikitCustomization.js";
 import { packageVersion } from "../version.js";
+import { readFlowState } from "../flow.js";
 import { DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID, buildDesignBrief, designContractConfirmationFromAnswers, designPreviewPath, readDesignContract, } from "./design.js";
 import { installedBlockProvidedCapabilities } from "./blocks.js";
 import { inspectProject, validateSetup } from "./project.js";
 import { readCreativeSelection } from "./creative.js";
+import { readRuntimeProofWaiver, hasExecutableSmokeMarker } from "./smoke.js";
 import { assessUxHarness, buildExperienceReport, buildUxHarness, readUxHarness, } from "./uxHarness.js";
 const complianceDirName = "sp-vise";
 const attestationsDirName = "attestations";
@@ -337,7 +339,8 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
     const designReview = designReviewFor(repoRoot, designContract, answers);
     const acceptedDesignContract = designReview.status === "accepted" ? designContract : null;
     const storedCreativeSelection = await readCreativeSelection(repoRoot);
-    const creativeSelection = storedCreativeSelection && creativeSelectionAppliesToRequest(storedCreativeSelection, request)
+    const flow = await readFlowState(repoRoot);
+    const creativeSelection = storedCreativeSelection && creativeSelectionAppliesToRequest(storedCreativeSelection, request, flow)
         ? storedCreativeSelection
         : undefined;
     if (options.allowUnresolvedIntake !== true) {
@@ -704,17 +707,32 @@ function uxHarnessSummary(harness) {
         advisory_only: "UX Harness guidance does not change deterministic compliance rules or exit codes in the MVP.",
     };
 }
-function creativeSelectionAppliesToRequest(selection, request) {
+function creativeSelectionAppliesToRequest(selection, request, flow) {
     const normalizedRequest = normalizeCreativeRequest(request);
     const original = normalizeCreativeRequest(selection.source.request);
     const planRequest = normalizeCreativeRequest(selection.implementationContext.planRequest);
     if (!normalizedRequest || !original) {
         return false;
     }
+    const requestedOutcome = resolveOutcome(request, {});
+    if (omittedCreativeOutcomeSet(flow).has(requestedOutcome)) {
+        return false;
+    }
     return (normalizedRequest === original ||
         normalizedRequest === planRequest ||
         normalizedRequest.includes(original) ||
-        original.includes(normalizedRequest));
+        original.includes(normalizedRequest) ||
+        (Boolean(selection.selectedVariant?.id) && creativeSelectionOutcomeSet(selection).has(requestedOutcome)));
+}
+function omittedCreativeOutcomeSet(flow) {
+    return new Set((flow?.blueprint?.omitted ?? []).map((item) => item.outcome).filter((outcome) => typeof outcome === "string"));
+}
+function creativeSelectionOutcomeSet(selection) {
+    const outcomes = new Set();
+    for (const hint of selection.implementationContext.surfaceHints ?? []) {
+        outcomes.add(hint.outcome);
+    }
+    return outcomes;
 }
 function normalizeCreativeRequest(value) {
     return value.toLowerCase().replace(/[^a-z0-9\s]+/g, " ").replace(/\s+/g, " ").trim();
@@ -941,6 +959,18 @@ export async function checkCompliance(repoPath, options = {}) {
             });
             continue;
         }
+        if (hasDeterministicChecks && deterministic?.waived) {
+            results.push({
+                ...checkRuleIdentity(rule.id),
+                title: rule.title,
+                severity: rule.severity,
+                status: "proof-waived",
+                reason: deterministic.reason,
+                evidence: deterministic.evidence,
+                rationale: rule.rationale,
+            });
+            continue;
+        }
         const attestation = attestations.get(rule.id);
         if (attestation) {
             if (attestation.status === "deterministic-pass") {
@@ -1149,15 +1179,22 @@ export async function checkCompliance(repoPath, options = {}) {
     const hasCompletenessGap = gatedMissing.length > 0;
     const hasSelectedOptionalFailures = gatedSelectedFailed.length > 0 || gatedSelectedUnknown.length > 0;
     const { status, exitCode } = deriveGate({
+        hasNoPlatform: detectedPlatforms.length === 0,
         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,
+        hasProofWaived: gatedResults.some((result) => result.status === "proof-waived"),
+        allowProofWaiver: options.allowProofWaiver === true,
     });
     const uxHarness = await readUxHarness(repoRoot);
     const uxAssessment = await assessUxHarness(inspection.effectiveRoot, uxHarness, compliance.outcome);
-    const openReviewItems = await experienceOpenReviewItems(repoRoot, findings);
+    const openReviewItems = await experienceOpenReviewItems(repoRoot, findings, {
+        results,
+        completeness,
+        outcome: compliance.outcome,
+    });
     const experienceReport = {
         ...buildExperienceReport({
             checkStatus: status,
@@ -1251,20 +1288,56 @@ function sensorReviewGaps(raw) {
     }
     return gaps.slice(0, 50);
 }
-async function experienceOpenReviewItems(repoRoot, findings) {
+async function experienceOpenReviewItems(repoRoot, findings, context) {
     const intake = await readIntakeReviewItems(repoRoot);
     const validateFindings = validateFindingReviewItems(findings);
+    const advisoryFindings = context.results
+        .filter((result) => result.status === "advisory")
+        .map((result) => ({ ruleId: result.ruleId, title: result.title, severity: result.severity }));
+    const scopeReductions = (context.completeness?.optedOut ?? []).map((item) => ({
+        id: item.id,
+        kind: "scope-omit",
+        reason: item.reason,
+    }));
+    const runtimeProof = await runtimeProofReviewItem(repoRoot, context.outcome);
     const needsReview = intake.unresolvedNonblockingIntake.length > 0 ||
         intake.acknowledgedBlockingIntake.length > 0 ||
-        validateFindings.length > 0;
+        validateFindings.length > 0 ||
+        scopeReductions.length > 0 ||
+        runtimeProof.status === "not-proven";
+    const nextStepParts = [];
+    if (needsReview)
+        nextStepParts.push("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.");
+    if (scopeReductions.length > 0)
+        nextStepParts.push(`Confirm the scope-omit decision(s) were intended: ${scopeReductions.map((item) => item.id).join(", ")}.`);
+    if (runtimeProof.status === "not-proven")
+        nextStepParts.push(runtimeProof.note);
+    if (advisoryFindings.length > 0)
+        nextStepParts.push(`Advisory findings do not gate but are still review debt: ${advisoryFindings.map((item) => item.ruleId).join(", ")}.`);
     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.",
+        ...(advisoryFindings.length > 0 ? { advisoryFindings } : {}),
+        ...(scopeReductions.length > 0 ? { scopeReductions } : {}),
+        runtimeProof,
+        nextStep: nextStepParts.length > 0
+            ? nextStepParts.join(" ")
+            : "No unresolved intake, validate findings, scope-omits, or runtime-proof gaps were observed in the current report inputs.",
+    };
+}
+async function runtimeProofReviewItem(repoRoot, outcome) {
+    if (runtimeSmokeSurfaceForOutcome(outcome) === null) {
+        return { status: "not-applicable", note: "This outcome does not back a live-data collection surface." };
+    }
+    const evidence = await readJsonIfExists(path.join(sidecarDir(repoRoot), "evidence", "runtime-smoke.json"));
+    if (evidence?.passed === true) {
+        return { status: "proven", note: "Runtime-smoke evidence recorded a passing mounted-app capture for the declared surface(s)." };
+    }
+    return {
+        status: "not-proven",
+        note: "This surface renders live SDK collections but has no passing runtime-smoke evidence — a green `vise check` does not prove the screen actually populated at runtime. Capture runtime proof (`vise smoke`) or state in the handoff that only static checks are claimed.",
     };
 }
 async function readIntakeReviewItems(repoRoot) {
@@ -1771,8 +1844,18 @@ async function assessDeterministicChecks(rule, findingsById, platforms, canonica
             continue;
         }
         if (check.check === "runtime-smoke-evidence-passed") {
-            const smoke = await assessRuntimeSmokeEvidence(repoRoot, check);
+            const smoke = await assessRuntimeSmokeEvidence(repoRoot, check, rule);
             if (!smoke.passed) {
+                const waiver = await readRuntimeProofWaiver(repoRoot);
+                if (waiver) {
+                    return {
+                        passed: false,
+                        waived: true,
+                        evidence: { source: "runtime_proof_waiver", mode: waiver.mode, reason: waiver.reason, recorded_at: waiver.recorded_at },
+                        reason: `Runtime proof waived (${waiver.mode}): ${waiver.reason}. This surface is NOT runtime-proven — only static checks are claimed.`,
+                        recommendation: smoke.recommendation,
+                    };
+                }
                 return smoke;
             }
             if (smoke.evidence) {
@@ -1817,7 +1900,7 @@ async function assessDeterministicChecks(rule, findingsById, platforms, canonica
         evidence,
     };
 }
-async function assessRuntimeSmokeEvidence(repoRoot, check) {
+async function assessRuntimeSmokeEvidence(repoRoot, check, rule) {
     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);
@@ -1843,11 +1926,21 @@ async function assessRuntimeSmokeEvidence(repoRoot, check) {
     const results = Array.isArray(parsed.results) ? parsed.results : [];
     const surfaceResults = results.filter(isRuntimeSmokeSurfaceResult);
     const failing = surfaceResults.filter((result) => result.verdict !== "pass");
+    const generatedAt = typeof parsed.generated_at === "string" ? parsed.generated_at : undefined;
+    const logBinding = runtimeSmokeBinding(parsed.log);
+    const smokeConfigBinding = runtimeSmokeBinding(parsed.smoke_config);
+    const sourceFingerprints = runtimeSmokeSourceFingerprints(parsed.source_fingerprints);
     const evidence = {
         source: "runtime_smoke",
         file: displayPath,
         passed: parsed.passed === true,
         ...(typeof parsed.platform === "string" ? { platform: parsed.platform } : {}),
+        ...(generatedAt ? { generated_at: generatedAt } : {}),
+        ...(logBinding ? { log: logBinding } : {}),
+        ...(smokeConfigBinding ? { smoke_config: smokeConfigBinding } : {}),
+        ...(sourceFingerprints.length > 0
+            ? { source_fingerprints: sourceFingerprints.map((item) => ({ path: item.path, sha256: item.sha256, surfaces: item.surfaces })) }
+            : {}),
         results: surfaceResults,
     };
     if (parsed.passed !== true) {
@@ -1877,7 +1970,121 @@ async function assessRuntimeSmokeEvidence(repoRoot, check) {
             recommendation,
         };
     }
-    const smokeConfig = await readJsonIfExists(path.join(sidecarDir(repoRoot), "smoke.json"));
+    if (!generatedAt || Number.isNaN(Date.parse(generatedAt))) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence at ${displayPath} is missing a valid generated_at capture timestamp; rerun \`vise smoke\` from a captured mounted-app log.`,
+            recommendation,
+        };
+    }
+    if (!logBinding) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence at ${displayPath} is missing the captured log digest; rerun \`vise smoke\` so the proof binds to a log artifact.`,
+            recommendation,
+        };
+    }
+    const logPath = path.resolve(repoRoot, logBinding.path);
+    if (!pathInside(repoRoot, logPath)) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke log path must stay inside the repository: ${logBinding.path}`,
+            recommendation,
+        };
+    }
+    let currentLogDigest;
+    try {
+        currentLogDigest = await digestFile(logPath);
+    }
+    catch {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence at ${displayPath} references a missing captured log: ${logBinding.path}.`,
+            recommendation,
+        };
+    }
+    if (currentLogDigest !== logBinding.sha256) {
+        return {
+            passed: false,
+            evidence: { ...evidence, log_status: { path: logBinding.path, expected_sha256: logBinding.sha256, actual_sha256: currentLogDigest } },
+            reason: `Runtime smoke captured log changed since evidence was recorded: ${logBinding.path}. Rerun the mounted-app capture and \`vise smoke\`.`,
+            recommendation,
+        };
+    }
+    const smokeConfigPath = path.join(sidecarDir(repoRoot), "smoke.json");
+    let smokeConfigText;
+    let smokeConfig;
+    try {
+        smokeConfigText = await readFile(smokeConfigPath, "utf8");
+        smokeConfig = JSON.parse(smokeConfigText);
+    }
+    catch {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence at ${displayPath} cannot be checked because sp-vise/smoke.json is missing or unreadable.`,
+            recommendation,
+        };
+    }
+    if (!smokeConfigBinding) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence at ${displayPath} is missing the smoke.json digest; rerun \`vise smoke\` so the proof binds to the declared surfaces.`,
+            recommendation,
+        };
+    }
+    const smokeConfigBindingPath = path.resolve(repoRoot, smokeConfigBinding.path);
+    if (!pathInside(repoRoot, smokeConfigBindingPath) || smokeConfigBindingPath !== smokeConfigPath) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence must bind to sp-vise/smoke.json, not ${smokeConfigBinding.path}.`,
+            recommendation,
+        };
+    }
+    const currentSmokeConfigDigest = `sha256:${createHash("sha256").update(smokeConfigText).digest("hex")}`;
+    if (currentSmokeConfigDigest !== smokeConfigBinding.sha256) {
+        return {
+            passed: false,
+            evidence: {
+                ...evidence,
+                smoke_config_status: { path: smokeConfigBinding.path, expected_sha256: smokeConfigBinding.sha256, actual_sha256: currentSmokeConfigDigest },
+            },
+            reason: `sp-vise/smoke.json changed since runtime smoke evidence was recorded. Rerun \`vise smoke\` for the current declared surfaces.`,
+            recommendation,
+        };
+    }
+    const expectedRulePlatform = platformFromRuleId(rule.id);
+    const configPlatform = typeof smokeConfig.platform === "string" ? smokeConfig.platform : undefined;
+    if (expectedRulePlatform && parsed.platform !== expectedRulePlatform) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence platform "${String(parsed.platform ?? "(missing)")}" does not match rule platform "${expectedRulePlatform}". Capture runtime proof on the platform being checked.`,
+            recommendation,
+        };
+    }
+    if (expectedRulePlatform && configPlatform !== expectedRulePlatform) {
+        return {
+            passed: false,
+            evidence,
+            reason: `sp-vise/smoke.json platform "${String(configPlatform ?? "(missing)")}" does not match rule platform "${expectedRulePlatform}". Declare and capture smoke evidence for the platform being checked.`,
+            recommendation,
+        };
+    }
+    if (!expectedRulePlatform && configPlatform && parsed.platform !== configPlatform) {
+        return {
+            passed: false,
+            evidence,
+            reason: `Runtime smoke evidence platform "${String(parsed.platform ?? "(missing)")}" does not match sp-vise/smoke.json platform "${configPlatform}".`,
+            recommendation,
+        };
+    }
     const expectedSurfaceIds = Array.isArray(smokeConfig?.surfaces)
         ? smokeConfig.surfaces.map((surface) => surface.id).filter((id) => typeof id === "string" && id.length > 0)
         : [];
@@ -1892,6 +2099,15 @@ async function assessRuntimeSmokeEvidence(repoRoot, check) {
                 recommendation,
             };
         }
+        const provenance = await verifyRuntimeSmokeSourceProvenance(repoRoot, sourceFingerprints, expectedSurfaceIds);
+        if (!provenance.passed) {
+            return {
+                passed: false,
+                evidence: { ...evidence, source_fingerprint_status: provenance.status },
+                reason: provenance.reason,
+                recommendation,
+            };
+        }
         const expectedSurfacesById = new Map(smokeConfig?.surfaces
             ?.filter((surface) => typeof surface.id === "string" && surface.id.length > 0)
             .map((surface) => [surface.id, surface]) ?? []);
@@ -1914,6 +2130,92 @@ async function assessRuntimeSmokeEvidence(repoRoot, check) {
         evidence,
     };
 }
+function runtimeSmokeBinding(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const item = value;
+    if (typeof item.path !== "string" || typeof item.sha256 !== "string")
+        return null;
+    if (!item.sha256.startsWith("sha256:"))
+        return null;
+    return { path: item.path, sha256: item.sha256 };
+}
+function runtimeSmokeSourceFingerprints(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        const binding = runtimeSmokeBinding(entry);
+        if (!binding || !entry || typeof entry !== "object")
+            return [];
+        const surfaces = entry.surfaces;
+        if (!Array.isArray(surfaces))
+            return [];
+        const normalizedSurfaces = surfaces.filter((surface) => typeof surface === "string" && surface.length > 0).sort();
+        return normalizedSurfaces.length > 0 ? [{ ...binding, surfaces: normalizedSurfaces }] : [];
+    });
+}
+async function verifyRuntimeSmokeSourceProvenance(repoRoot, fingerprints, expectedSurfaceIds) {
+    if (fingerprints.length === 0) {
+        return {
+            passed: false,
+            reason: "Runtime smoke evidence is missing source fingerprints for VISE_SMOKE emitters; rerun `vise smoke` after wiring markers into product source.",
+            status: [],
+        };
+    }
+    const surfacesWithEmitter = new Set();
+    const status = [];
+    for (const fingerprint of fingerprints) {
+        const absolutePath = path.resolve(repoRoot, fingerprint.path);
+        if (!pathInside(repoRoot, absolutePath)) {
+            status.push({ path: fingerprint.path, expected_sha256: fingerprint.sha256, status: "outside-repo" });
+            continue;
+        }
+        let content;
+        let actualSha256;
+        try {
+            content = await readFile(absolutePath, "utf8");
+            actualSha256 = `sha256:${createHash("sha256").update(content).digest("hex")}`;
+        }
+        catch {
+            status.push({ path: fingerprint.path, expected_sha256: fingerprint.sha256, status: "missing" });
+            continue;
+        }
+        const hasMarker = hasExecutableSmokeMarker(content);
+        const declaredSurfaces = fingerprint.surfaces.filter((surface) => content.includes(surface));
+        for (const surface of declaredSurfaces) {
+            surfacesWithEmitter.add(surface);
+        }
+        status.push({
+            path: fingerprint.path,
+            expected_sha256: fingerprint.sha256,
+            actual_sha256: actualSha256,
+            status: actualSha256 === fingerprint.sha256 && hasMarker && declaredSurfaces.length === fingerprint.surfaces.length ? "match" : "changed",
+            has_marker: hasMarker,
+            surfaces: declaredSurfaces,
+        });
+    }
+    const stale = status.filter((item) => item.status !== "match");
+    if (stale.length > 0) {
+        return {
+            passed: false,
+            reason: "Runtime smoke source emitters changed or disappeared since evidence was recorded. Rerun the mounted-app capture and `vise smoke`.",
+            status,
+        };
+    }
+    const missingSurfaces = expectedSurfaceIds.filter((surface) => !surfacesWithEmitter.has(surface));
+    if (missingSurfaces.length > 0) {
+        return {
+            passed: false,
+            reason: `Runtime smoke evidence is missing VISE_SMOKE source emitter fingerprints for declared surface(s): ${missingSurfaces.join(", ")}.`,
+            status,
+        };
+    }
+    return { passed: true, status };
+}
+function platformFromRuleId(ruleId) {
+    const platform = ruleId.split(".")[0];
+    return ["typescript", "react-native", "android", "ios", "flutter"].includes(platform) ? platform : null;
+}
 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.",
@@ -1998,6 +2300,9 @@ export const FILE_SCOPABLE_SENSOR_SUFFIXES = new Set([
     "live-collection.api-mismatch",
     "story.live-collection",
     "search.live-collection",
+    "message-search.live-collection",
+    "channel-archive.live-collection",
+    "for-you-feed.live-collection",
     "notification-tray.live-collection",
     "event.live-collection",
     "blocked-users.live-collection",
@@ -2506,6 +2811,8 @@ async function readBaseline(repoRoot) {
     return readJsonIfExists(baselinePath(repoRoot));
 }
 function deriveGate(flags) {
+    if (flags.hasNoPlatform)
+        return { status: "no-platform", exitCode: 8 };
     if (flags.hasBlocked)
         return { status: "blocked", exitCode: 3 };
     if (flags.hasDeterministicFailure)
@@ -2516,6 +2823,8 @@ function deriveGate(flags) {
         return { status: "completeness-gap", exitCode: 5 };
     if (flags.hasSelectedOptionalFailures)
         return { status: "selected-capability-failures", exitCode: 6 };
+    if (flags.hasProofWaived)
+        return { status: "runtime-proof-waived", exitCode: flags.allowProofWaiver ? 0 : 9 };
     return { status: "green", exitCode: 0 };
 }
 export async function recordBaseline(repoPath) {

package/dist/tools/debug.js

@@ -32,6 +32,7 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
         : undefined;
     const correlatedRules = [];
     let checkResult = null;
+    let correlationNote;
     try {
         checkResult = await checkCompliance(repoPath);
         const rulesMap = await rulesById();
@@ -39,7 +40,15 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
             const contractRuleId = rule.contractRuleId ?? rule.ruleId;
             const ruleDef = rulesMap.get(contractRuleId);
             const symptoms = ruleDef?.symptoms || [];
-            if (symptoms.length === 0 || !symptoms.some((s) => errorMessage.includes(s))) {
+            const symptomMatches = symptoms.some((s) => {
+                if (!errorMessage.includes(s))
+                    return false;
+                if (/^\d{3}$/.test(s.trim())) {
+                    return /amity|social[.\s]?plus|@amityco|live[-\s]?collection|session|AmityClient|AccessToken/i.test(errorMessage);
+                }
+                return true;
+            });
+            if (symptoms.length === 0 || !symptomMatches) {
                 continue;
             }
             if (rule.status === "deterministic-fail" || rule.status === "attestation-needed") {
@@ -67,6 +76,10 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
         }
     }
     catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        correlationNote = /compliance sidecar/i.test(reason)
+            ? "Compliance correlation was skipped: no sp-vise sidecar found. Run `vise init .` so `vise debug` can cross-reference this crash against the SDK rule signatures — until then this diagnosis is based only on the error text, not the project's compliance state."
+            : `Compliance correlation could not run (${sanitizeError(reason)}); this diagnosis is based only on the error text, not the project's compliance state.`;
     }
     const failingCorrelated = correlatedRules.filter((r) => r.status === "failed" || r.status === "attested");
     const moduleDiagnosis = missingModulePkg
@@ -121,6 +134,7 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
         extractedException: exceptionClass,
         suggestedRemediation,
         repairBrief,
+        ...(correlationNote ? { correlationNote } : {}),
         ...(secondaryModuleNote ? { secondaryNotes: [secondaryModuleNote] } : {}),
         relevantDocs: [
             {
@@ -134,6 +148,7 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
             likelyCause: payload.likelyCause,
             correlatedRules: payload.correlatedRules,
             repairBrief: payload.repairBrief,
+            ...(correlationNote ? { correlationNote } : {}),
             ...(secondaryModuleNote ? { secondaryNotes: [secondaryModuleNote] } : {}),
             relevantDocs: payload.relevantDocs,
         };

package/dist/tools/design.js

@@ -231,34 +231,40 @@ export const BRAND_PROFILE_PROTOCOL = [
     "Advisory — it grounds generation; it never gates `vise check`.",
 ].join("\n");
 const REQUIRED_PROFILE_STRINGS = ["essence", "voice", "density", "elevation", "motion", "imagery"];
-export function validateDesignProfile(raw) {
+export function diagnoseDesignProfile(raw) {
     if (!raw || typeof raw !== "object") {
-        return null;
+        return "not a JSON object";
     }
     const p = raw;
     if (typeof p.schemaVersion !== "string") {
-        return null;
+        return "`schemaVersion` is missing or not a string";
     }
     for (const f of REQUIRED_PROFILE_STRINGS) {
         if (typeof p[f] !== "string" || p[f].trim().length === 0) {
-            return null;
+            return `\`${f}\` is missing or empty (all of ${REQUIRED_PROFILE_STRINGS.join(", ")} must be non-empty strings)`;
         }
     }
     const isStrArr = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
-    if (!isStrArr(p.personality) || !isStrArr(p.do) || !isStrArr(p.avoid)) {
-        return null;
-    }
+    if (!isStrArr(p.personality))
+        return "`personality` must be an array of strings";
+    if (!isStrArr(p.do))
+        return "`do` must be an array of strings";
+    if (!isStrArr(p.avoid))
+        return "`avoid` must be an array of strings";
     if (!Array.isArray(p.palette) ||
         !p.palette.every((e) => e &&
             typeof e === "object" &&
             typeof e.role === "string" &&
             typeof e.hex === "string")) {
-        return null;
+        return "`palette` must be an array of { role, hex } entries";
     }
     if (!p.typography || typeof p.typography !== "object") {
-        return null;
+        return "`typography` must be an object";
     }
-    return raw;
+    return null;
+}
+export function validateDesignProfile(raw) {
+    return diagnoseDesignProfile(raw) === null ? raw : null;
 }
 export async function readDesignProfile(repoPath) {
     const target = path.join(path.resolve(repoPath), "sp-vise", DESIGN_PROFILE_FILENAME);
@@ -269,6 +275,25 @@ export async function readDesignProfile(repoPath) {
         return null;
     }
 }
+export async function readDesignProfileDiagnostic(repoPath) {
+    const target = path.join(path.resolve(repoPath), "sp-vise", DESIGN_PROFILE_FILENAME);
+    let text;
+    try {
+        text = await readFile(target, "utf8");
+    }
+    catch {
+        return { present: false };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { present: true, reason: "the file is not valid JSON" };
+    }
+    const reason = diagnoseDesignProfile(parsed);
+    return reason === null ? { present: true } : { present: true, reason };
+}
 export async function writeDesignProfile(repoPath, profile) {
     const sidecarDir = path.join(path.resolve(repoPath), "sp-vise");
     await mkdir(sidecarDir, { recursive: true });
@@ -409,7 +434,7 @@ export const designPreviewTool = {
                 }
                 : "no UI code scanned",
             ...(contract.source.self_referential
-                ? { self_referential_note: "Contract derived from this project's own files (--from-project): conformance is circular and is NOT a design-quality signal. For a real design target, extract from an external prototype/theme." }
+                ? { self_referential_note: "Contract derived from this project's own files (--from-project). Vise cannot verify whether that design system PRE-EXISTED your work, so its strength is capped below \"strong\" as a guardrail: if you just wrote the feature's styling and then graded it against itself, high token coverage is circular, not a design-quality signal. If the design system genuinely pre-existed (a real host theme), the contract IS a legitimate grounding source — the cap is only a can't-verify precaution, not a verdict that your system is bad. For an unambiguous external target, extract from a customer prototype/theme." }
                 : {}),
             note: "Open the HTML to visually compare the contract (and embedded reference, if HTML) against your app. A human or VLM judges the visual match — this is not an automated pixel diff.",
             where: written ? `Open ${written} in a browser.` : "Not written (write=false).",
@@ -2589,7 +2614,7 @@ function bestCandidate(a, b) {
         return b;
     return a.token.length <= b.token.length ? a : b;
 }
-export function buildDesignBrief(contract, profile) {
+export function buildDesignBrief(contract, profile, profileProblem) {
     const strength = contract.stats.strength;
     const colorTokens = contract.tokens.filter((t) => t.category === "color" && t.name !== null);
     const roleMap = new Map();
@@ -2783,10 +2808,16 @@ export function buildDesignBrief(contract, profile) {
             avoid: profile.avoid,
             source: profile.capturedFrom ?? "sp-vise/design-profile.json",
         }
-        : {
-            status: "absent",
-            howTo: "These are tokens only. For richer brand grounding (personality, type system, density, voice, do/avoid), author sp-vise/design-profile.json from the host's real screens, then honor it per surface. See the 'Brand profile' subsection of the social.plus design skill for the schema.",
-        };
+        : profileProblem
+            ? {
+                status: "invalid",
+                reason: profileProblem,
+                howTo: `sp-vise/design-profile.json EXISTS but was rejected: ${profileProblem}. FIX that one field in the existing file and re-run — do not re-author it from scratch. (A malformed profile is ignored, so it silently read as absent before this.) See the 'Brand profile' subsection of the social.plus design skill for the schema.`,
+            }
+            : {
+                status: "absent",
+                howTo: "These are tokens only. For richer brand grounding (personality, type system, density, voice, do/avoid), author sp-vise/design-profile.json from the host's real screens, then honor it per surface. See the 'Brand profile' subsection of the social.plus design skill for the schema.",
+            };
     return {
         summary,
         strength,