@amityco/social-plus-vise 1.0.0 → 1.1.0

package/dist/tools/compliance.js

@@ -157,7 +157,7 @@ export const explainRuleTool = {
 };
 export const initEngagementTool = {
     name: "init_engagement",
-    description: "Initialize sp-vise/engagement.json with customer, tier, and contracted outcome scope. Local-only metadata; v0.5 will route review-queue uploads using these fields.",
+    description: "Initialize sp-vise/engagement.json with customer, tier, and contracted outcome scope. Local-only metadata that never leaves your machine.",
     inputSchema: {
         type: "object",
         properties: {
@@ -255,7 +255,7 @@ export async function initEngagement(args) {
         scope: engagement.scope,
         customer_id: engagement.customer_id,
         file: engagementFile,
-        note: "Engagement metadata is local-only in v0.4.x. v0.5 review queue will route uploads using these fields.",
+        note: "Engagement metadata is recorded locally and never uploaded.",
     };
 }
 export async function showEngagement(repoPath) {
@@ -317,8 +317,8 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
     const supportedOptionalIds = availableOptionalCapabilityIds(capabilityAvailability);
     const selectedOptionalCapabilities = selectedOptionalCapabilityIds(outcome, answers, request, supportedOptionalIds);
     const rules = await applicableRules(outcome, inspection.platforms);
-    const refs = rules.map(ruleRef); // minimal shape — stable digest input
-    const fileRefs = rules.map(ruleRefForFile); // adds title for human/agent readers
+    const refs = rules.map(ruleRef);
+    const fileRefs = rules.map(ruleRefForFile);
     const engagement = await readEngagement(repoRoot);
     const designContract = await readDesignContract(repoRoot);
     const designReview = designReviewFor(repoRoot, designContract, answers);
@@ -342,25 +342,32 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         allowUnresolvedIntake: options.allowUnresolvedIntake === true,
     });
     if (intake.remainingBlocking > 0 && !intake.acknowledged_unresolved_blocking) {
+        const blockingIds = intake.questions
+            .filter((question) => question.blocksImplementationWhenMissing)
+            .map((question) => question.id);
+        const answerExample = blockingIds.map((id) => `${id}=<value>`).join(" --answer ");
         return {
             status: "needs-clarification",
             exitCode: 7,
             outcome,
             intake,
-            nextStep: "Run `vise plan` and surface the blocking intake questions to the customer. Re-run `vise init` with --answer for each blocking question, or pass --allow-unresolved-intake only for retrospective/harness initialization.",
+            nextStep: "Run `vise plan` and surface the blocking intake questions to the customer. " +
+                `Then re-run with their answers (one --answer per id): vise init --request <request> --answer ${answerExample}. ` +
+                "Each --answer takes a single id=value; repeat the flag per id (do not comma-join). " +
+                "The gate still blocks until every id above is answered; pass --allow-unresolved-intake only for retrospective/harness initialization.",
         };
     }
     const compliance = {
         schema_version: schemaVersion,
         vise_version: packageVersion,
         foundry_version: packageVersion,
-        ruleset_digest: digestJson(refs), // hash of minimal refs (no title)
+        ruleset_digest: digestJson(refs),
         generated_at: new Date().toISOString(),
         last_synced_at: null,
         outcome,
         engagement_id: engagement?.engagement_id,
         surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
-        rules: fileRefs, // file carries titles
+        rules: fileRefs,
         design_contract: acceptedDesignContract
             ? {
                 digest: acceptedDesignContract.digest,
@@ -371,6 +378,7 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
             }
             : undefined,
         selected_optional_capabilities: selectedOptionalCapabilities.length > 0 ? selectedOptionalCapabilities : undefined,
+        surface_anchor: await buildSurfaceAnchor(rules),
     };
     await mkdir(attestationsDir(repoRoot), { recursive: true });
     await writeJson(compliancePath(repoRoot), compliance);
@@ -385,8 +393,6 @@ 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");
-    // Write a frozen check snapshot so agents can see current rule status immediately
-    // without having to run vise check themselves.
     const checkSnapshot = await checkCompliance(repoPath);
     await writeJson(path.join(sidecarDir(repoRoot), "findings.json"), {
         snapshot_at: compliance.generated_at,
@@ -559,7 +565,120 @@ export async function applicableComplianceRuleSummaries(outcome, platforms) {
     return (await applicableRules(outcome, platforms)).map(ruleRefForFile);
 }
 export async function applicableCompliancePlanRuleSummaries(outcome, platforms) {
-    return (await applicableRules(outcome, platforms)).map(ruleRefForPlan);
+    return (await applicableRules(outcome, platforms)).map(ruleRefForPlan).map(planRuleRefSummary);
+}
+const SURFACE_ANCHOR_PLATFORMS = ["typescript", "android", "ios", "flutter"];
+async function loadSurfaceSymbolSets() {
+    const { getSdkFacts } = await import("./sdkFacts.js");
+    const out = {};
+    for (const platform of SURFACE_ANCHOR_PLATFORMS) {
+        try {
+            const facts = await getSdkFacts({ platform, includeSymbols: true });
+            out[platform] = {
+                types: new Set((facts.symbols?.types ?? []).map((symbol) => symbol.name)),
+                members: new Set((facts.symbols?.members ?? []).map((symbol) => symbol.name)),
+            };
+        }
+        catch {
+        }
+    }
+    return out;
+}
+function surfaceIdentityFrom(sets) {
+    const shape = {};
+    for (const platform of Object.keys(sets).sort()) {
+        shape[platform] = { types: [...sets[platform].types].sort(), members: [...sets[platform].members].sort() };
+    }
+    return digestJson(shape);
+}
+async function buildSurfaceAnchor(ruleDefs) {
+    const anchored = ruleDefs
+        .filter((rule) => {
+        const a = rule.symbol_anchored;
+        return !!a && a.basis === "names-only" && ((a.types?.length ?? 0) > 0 || (a.members?.length ?? 0) > 0);
+    })
+        .map((rule) => ({ rule_id: rule.id, platform: rule.symbol_anchored.platform, types: rule.symbol_anchored.types, members: rule.symbol_anchored.members }));
+    if (anchored.length === 0)
+        return undefined;
+    return { identity: surfaceIdentityFrom(await loadSurfaceSymbolSets()), rules: anchored };
+}
+export async function surfaceDriftStale(compliance) {
+    const drifted = new Map();
+    const anchor = compliance.surface_anchor;
+    if (!anchor || anchor.rules.length === 0)
+        return drifted;
+    const { canonicalPlatform } = await import("./sdkFacts.js");
+    const sets = await loadSurfaceSymbolSets();
+    if (surfaceIdentityFrom(sets) === anchor.identity)
+        return drifted;
+    for (const rec of anchor.rules) {
+        const key = canonicalPlatform(rec.platform);
+        const surf = key ? sets[key] : undefined;
+        if (!surf)
+            continue;
+        const missingTypes = (rec.types ?? []).filter((type) => !surf.types.has(type));
+        const missingMembers = (rec.members ?? []).filter((member) => !surf.members.has(member));
+        if (missingTypes.length > 0 || missingMembers.length > 0)
+            drifted.set(rec.rule_id, { types: missingTypes, members: missingMembers });
+    }
+    return drifted;
+}
+export function surfaceDriftReason(rule, missing) {
+    const what = [...missing.types.map((type) => `type ${type}`), ...missing.members.map((member) => `member ${member}`)].join(", ");
+    const humanReaudit = rule.enforcement.attestation.allowed === false;
+    return {
+        humanReaudit,
+        reason: humanReaudit
+            ? `SDK surface drifted: this gate's anchored symbol(s) (${what}) are no longer in the bundled SDK surface, and this rule cannot be attested. A maintainer must re-audit it against the current SDK before it can pass again.`
+            : `SDK surface drifted: this gate's anchored symbol(s) (${what}) are no longer in the bundled SDK surface. Re-verify the integration and record a fresh attestation.`,
+    };
+}
+async function ruleFreshness(rule) {
+    const anchor = rule.symbol_anchored;
+    if (!anchor) {
+        return { status: "not-anchored", note: "This rule does not declare an SDK-symbol anchor." };
+    }
+    const { getSdkFacts, canonicalPlatform } = await import("./sdkFacts.js");
+    const key = canonicalPlatform(anchor.platform);
+    let verifiedAgainst;
+    if (key) {
+        try {
+            const facts = await getSdkFacts({ platform: key });
+            const upstreamGit = facts.surfaceSource?.upstreamGit;
+            verifiedAgainst = {
+                platform: anchor.platform,
+                sdk_product: facts.sdkProduct ?? null,
+                sdk_version: facts.sdkVersion ?? null,
+                surface_commit: upstreamGit?.commit ?? null,
+                extracted_at: facts.extractedAt ?? null,
+            };
+        }
+        catch {
+        }
+    }
+    const hasSymbols = (anchor.types?.length ?? 0) > 0 || (anchor.members?.length ?? 0) > 0;
+    if (anchor.basis !== "names-only" || !hasSymbols) {
+        return {
+            status: "pattern-based",
+            note: "This gate keys on a code pattern/value, not a symbol's existence — not symbol-tracked for drift.",
+            anchor,
+            ...(verifiedAgainst && { verified_against: verifiedAgainst }),
+        };
+    }
+    const sets = await loadSurfaceSymbolSets();
+    const surf = key ? sets[key] : undefined;
+    if (!surf) {
+        return { status: "surface-unavailable", anchor, ...(verifiedAgainst && { verified_against: verifiedAgainst }) };
+    }
+    const missingTypes = (anchor.types ?? []).filter((type) => !surf.types.has(type));
+    const missingMembers = (anchor.members ?? []).filter((member) => !surf.members.has(member));
+    const drifted = missingTypes.length > 0 || missingMembers.length > 0;
+    return {
+        status: drifted ? "drifted" : "verified",
+        anchor,
+        ...(drifted && { missing: { types: missingTypes, members: missingMembers } }),
+        ...(verifiedAgainst && { verified_against: verifiedAgainst }),
+    };
 }
 export async function checkCompliance(repoPath) {
     const repoRoot = path.resolve(repoPath);
@@ -598,13 +717,10 @@ export async function checkCompliance(repoPath) {
             results.push({ ...checkRuleIdentity(ref.rule_id), title: ref.rule_id, severity: ref.severity, status: "stale", reason: "Rule is missing from installed Vise." });
             continue;
         }
-        // Blockers run first. If any external prerequisite is missing, the rule is
-        // "blocked" — the host agent cannot fix this alone, so we surface it and
-        // stop evaluating this rule. Customer-readable reasons are attached so the
-        // user knows what to provide.
         const blockersFired = await runBlockers(rule, inspection.effectiveRoot);
         if (blockersFired.length > 0) {
             const attestable = rule.enforcement.attestation.allowed;
+            const hint = attestable ? attestHint(rule, compliance) : undefined;
             results.push({
                 ...checkRuleIdentity(rule.id),
                 title: rule.title,
@@ -613,8 +729,9 @@ export async function checkCompliance(repoPath) {
                 reason: blockersFired.map((blocker) => blocker.reason).join(" "),
                 blockers_fired: blockersFired,
                 current_rule: ruleSummary(rule),
-                ...(attestable && {
-                    next_step: `Provide the file(s) listed in blockers_fired, then run \`vise attest . --rule ${rule.id}\` to record your review decision.`,
+                ...(hint && {
+                    next_step: `Provide the file(s) listed in blockers_fired, then run \`${hint.attest_command}\` to record your review decision.`,
+                    ...hint,
                 }),
             });
             continue;
@@ -634,9 +751,6 @@ export async function checkCompliance(repoPath) {
         }
         const attestation = attestations.get(rule.id);
         if (attestation) {
-            // Deterministic-pass records are historical sync evidence, not waivers.
-            // If the current source now produces a finding, the old sync record must
-            // not mask code drift; the next `vise sync` will remove it.
             if (attestation.status === "deterministic-pass") {
                 const failStatus = rule.advisory ? "advisory" : rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail";
                 results.push({
@@ -657,7 +771,6 @@ export async function checkCompliance(repoPath) {
                 });
                 continue;
             }
-            // ruleset_digest is audit metadata; contractDrift above already guarantees the installed ruleset matches compliance.json.
             const exactMatch = attestation.rule_digest === ref.rule_digest;
             const grandfathered = !exactMatch && isAttestationGrandfathered(rule, attestation);
             if (exactMatch || grandfathered) {
@@ -727,24 +840,28 @@ export async function checkCompliance(repoPath) {
             ...(baseStatus === "attestation-needed" && rule.enforcement.attestation.allowed && attestHint(rule, compliance)),
         });
     }
+    const driftStale = await surfaceDriftStale(compliance);
+    if (driftStale.size > 0) {
+        for (const result of results) {
+            const ruleId = result.contractRuleId ?? result.ruleId;
+            const missing = driftStale.get(ruleId);
+            if (!missing)
+                continue;
+            if (result.status !== "deterministic-pass" && result.status !== "attested")
+                continue;
+            const rule = rules.get(ruleId);
+            if (!rule)
+                continue;
+            result.status = "stale";
+            result.reason = surfaceDriftReason(rule, missing).reason;
+            result.surface_drift = missing;
+        }
+    }
     const summary = summarize(results);
     const hasBlocked = results.some((result) => result.status === "blocked");
     const hasDeterministicFailure = results.some((result) => result.status === "deterministic-fail");
-    // "advisory" status is intentionally excluded — advisory rules surface but never block.
     const needsAttestation = results.some((result) => result.status === "attestation-needed" || result.status === "stale");
-    // Precedence: blocked (3) > deterministic-failures (2) > needs-attestation (1) >
-    // completeness-gap (5) > selected-capability-failures (6) > green (0).
-    // Contract drift (exit 4) is handled earlier and short-circuits the loop.
-    // Completeness-gap: capabilities that are neither present nor validly opted-out require an explicit decision
-    // (build it, or place // vise: scope-omit <id> — <reason>). The scope-omit escape hatch keeps this
-    // FP-free because any capability can be excluded with a recorded reason. Failure to assess is silently ignored.
     const sourceCompleteness = (await assessProjectCompleteness(inspection.effectiveRoot, compliance.outcome).catch(() => null)) ?? undefined;
-    // Installed Block Factory blocks deliver capabilities inside their packages,
-    // which the customer-source scan cannot see. Overlay block evidence for
-    // still-missing checklist items, but only from sidecar entries that pass
-    // registry-free local validation (manifest dependency declared + every
-    // filesTouched path intact — see installedBlockProvidedCapabilities). On
-    // local drift the evidence is withheld and the normal gap returns.
     const blockProvided = sourceCompleteness && sourceCompleteness.missing.length > 0
         ? await installedBlockProvidedCapabilities(repoRoot).catch(() => [])
         : [];
@@ -752,8 +869,6 @@ export async function checkCompliance(repoPath) {
     const hasCompletenessGap = (completeness?.missing.length ?? 0) > 0;
     const selectedOptionalCapabilities = (await assessProjectSelectedOptionalCapabilities(inspection.effectiveRoot, compliance.outcome, compliance.selected_optional_capabilities ?? []).catch(() => null)) ?? undefined;
     const hasSelectedOptionalFailures = ((selectedOptionalCapabilities?.failed.length ?? 0) > 0) || ((selectedOptionalCapabilities?.unknown.length ?? 0) > 0);
-    // Blocked wins because the agent cannot proceed without customer input;
-    // surfacing a smaller failure first would distract from the real blocker.
     const status = hasBlocked
         ? "blocked"
         : hasDeterministicFailure
@@ -891,7 +1006,7 @@ function fallbackExperienceReport(check) {
             },
         },
         score: null,
-        nextStep: "Resolve any technical check issue first, then regenerate the report. Do not publish a single Experience Score until repeated dogfood and benchmark evidence calibrates it responsibly.",
+        nextStep: "Resolve any technical check issue first, then regenerate the report. Do not publish a single Experience Score until repeated benchmark evidence calibrates it responsibly.",
     };
 }
 export async function syncCompliance(repoPath) {
@@ -949,8 +1064,6 @@ export async function attestRule(args) {
             const ids = candidateIds.length > 0 ? candidateIds : ambiguousCandidates.slice(0, 8);
             throw new Error(`Rule is ambiguous in this compliance contract: ${args.ruleId}. Attest one contract rule at a time: ${ids.join(", ")}.`);
         }
-        // Collect up to 8 applicable attestable rule ids from this contract for the error hint. Prefer
-        // ids that share the bad id's non-wildcard prefix so the agent can narrow down quickly.
         const attestableIds = compliance.rules
             .map((ref) => rules.get(ref.rule_id))
             .filter((r) => r !== undefined && r.enforcement.attestation.allowed);
@@ -1035,6 +1148,7 @@ export async function explainRule(ruleId) {
         attestation: rule.enforcement.attestation,
         summary: ruleSummary(rule),
         rule_digest: digestRule(rule),
+        freshness: await ruleFreshness(rule),
     };
 }
 export async function statusCompliance(repoPath) {
@@ -1125,8 +1239,6 @@ function ruleRef(rule) {
         severity: rule.severity,
     };
 }
-// Extends ruleRef with the human-readable title for file output (compliance.json,
-// applicableRules in integration plans). Not used for digest computation.
 function ruleRefForFile(rule) {
     const publicRuleId = publicProductRuleId(rule.id);
     return {
@@ -1157,8 +1269,14 @@ function ruleRefForPlan(rule) {
             : undefined,
     };
 }
-// Benchmark-measured friction: agents looped on attest dialect for ~25 min/cell when docs and SDK
-// disagreed on exact invocation syntax (capability-matrix 2026-06, Row 5). Hand them the exact incantation.
+function planRuleRefSummary(ref) {
+    return {
+        rule_id: ref.rule_id,
+        ...(ref.title !== undefined ? { title: ref.title } : {}),
+        ...(ref.contract_rule_id !== undefined ? { contract_rule_id: ref.contract_rule_id } : {}),
+        ...(ref.validator !== undefined ? { validator: ref.validator } : {}),
+    };
+}
 function attestHint(rule, compliance) {
     const minConfidence = rule.enforcement.attestation.host_agent_min_confidence ?? "high";
     const fields = rule.enforcement.attestation.evidence_required ?? [];
@@ -1470,12 +1588,19 @@ function validateEvidence(rule, evidence) {
 }
 async function readCompliance(repoRoot) {
     const file = compliancePath(repoRoot);
+    let raw;
     try {
-        return JSON.parse(await readFile(file, "utf8"));
+        raw = await readFile(file, "utf8");
     }
     catch {
         throw new Error(`No compliance sidecar found. Run vise init first: ${file}`);
     }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`sp-vise/compliance.json is present but could not be parsed (corrupt or merge-conflicted). Re-run vise init to regenerate it: ${file}`);
+    }
 }
 async function readAttestations(repoRoot) {
     const dir = attestationsDir(repoRoot);

package/dist/tools/creative.js

@@ -9,7 +9,6 @@ import { inspectProject } from "./project.js";
 import { buildUxHarness } from "./uxHarness.js";
 import { groundSelection, NO_FIT } from "../intelligence/grounding.js";
 import { SOCIAL_PLUS_OBJECTS, outcomesForObjects, surfaceObjectIds, SURFACE_REGISTRY } from "../intelligence/placement.js";
-// Re-exported so existing importers (e.g. test/run-intelligence-catalog.mjs) keep their path.
 export { SOCIAL_PLUS_OBJECTS };
 const CREATIVE_SCHEMA_VERSION = "2026-06-06.vise-creative.v1";
 const CREATIVE_SELECTION_SCHEMA_VERSION = "2026-06-06.vise-creative-selection.v1";
@@ -68,7 +67,7 @@ export const creativeBriefTool = {
             },
             rankingPreview: {
                 type: "boolean",
-                description: "Explicit opt-in local preview of shadow-policy-v2-draft candidate ranking. Defaults to false and does not change the default candidate order.",
+                description: "Explicit opt-in local preview of the v2-draft candidate ranking. Defaults to false and does not change the default candidate order.",
             },
             write: {
                 type: "boolean",
@@ -133,8 +132,6 @@ export const creativeAcceptTool = {
         const args = objectInput(input);
         const variantId = stringField(args, "variantId");
         const closest = optionalStringField(args, "closest");
-        // Divert "none" to the no-fit recorder ABOVE acceptCreativeVariant's candidate lookup (which would
-        // otherwise throw "not found" before grounding runs). acceptCreativeVariant stays untouched.
         if (variantId.trim().toLowerCase() === NO_FIT) {
             return textResult(await recordCatalogGap({
                 repoPath: stringField(args, "repoPath"),
@@ -146,7 +143,6 @@ export const creativeAcceptTool = {
                 write: optionalBooleanField(args, "write", true),
             }));
         }
-        // `closest` only describes a no-fit's nearest variant; fail loud rather than silently ignore it.
         if (closest !== undefined) {
             throw new Error('`closest` only applies to a no-fit record (--variant none); omit it when accepting a variant.');
         }
@@ -199,7 +195,7 @@ export async function buildCreativeBrief(options) {
         candidateSolutions: candidates,
         selectionGuidance: {
             mode: "agent-grounded-selection",
-            instruction: "You (the driving agent) choose the best-fitting variant by reasoning over candidateSolutions and the request. Use each candidate's `description` and `whenToChoose` (self-describing selecting signals) to discriminate between close variants — match the signals present in the request to the variant whose `whenToChoose` they satisfy. The listed order and the `fallbackDefault` flag are advisory keyword-derived hints, not recommendations to follow — keyword matching can point at the wrong variant for off-keyword requests, so decide by semantic fit. The factory will validate (ground) your choice against the catalog; it does not infer the variant for you.",
+            instruction: "You (the driving agent) choose the best-fitting variant by reasoning over candidateSolutions and the request. Use each candidate's `description` and `whenToChoose` (self-describing selecting signals) to discriminate between close variants — match the signals present in the request to the variant whose `whenToChoose` they satisfy. The listed order and the `fallbackDefault` flag are advisory keyword-derived hints, not recommendations to follow — keyword matching can point at the wrong variant for off-keyword requests, so decide by semantic fit. Vise will validate (ground) your choice against the catalog; it does not infer the variant for you.",
             howToAccept: "vise creative accept <repoPath> --variant <candidate id> --rationale \"<one line, grounded in the request and catalog>\" --confidence high|medium|low",
             contract: {
                 variant: "A candidateSolutions id chosen by best fit to the request (not by listed order or the fallbackDefault flag).",
@@ -219,7 +215,7 @@ export async function buildCreativeBrief(options) {
                 options: candidates.map((candidate) => candidate.id),
             },
         ],
-        nextStep: "Choose the best-fitting variant for the request by reasoning over candidateSolutions (listed order is advisory), then accept it with a grounded rationale and confidence: `vise creative accept <repoPath> --variant <id> --rationale \"<why>\" --confidence high|medium|low`. The factory validates the selection against the catalog. If no candidate genuinely fits, record a no-fit instead of forcing a choice: `vise creative accept <repoPath> --variant none --rationale \"<what is missing>\"`.",
+        nextStep: "Choose the best-fitting variant for the request by reasoning over candidateSolutions (listed order is advisory), then accept it with a grounded rationale and confidence: `vise creative accept <repoPath> --variant <id> --rationale \"<why>\" --confidence high|medium|low`. Vise validates the selection against the catalog. If no candidate genuinely fits, record a no-fit instead of forcing a choice: `vise creative accept <repoPath> --variant none --rationale \"<what is missing>\"`.",
     };
     if (options.rankingPreview === true) {
         brief.candidateRankingPreview = buildCandidateRankingPreview(brief);
@@ -246,9 +242,6 @@ export async function acceptCreativeVariant(options) {
     if (!selected) {
         throw new Error(`Creative variant "${variantId}" was not found in ${repoRelativePath(repoRoot, briefPath)}. Available variants: ${brief.candidateSolutions.map((candidate) => candidate.id).join(", ") || "(none)"}.`);
     }
-    // Option A: if the driving agent supplied a grounded selection, deterministically validate it against
-    // the candidate set the brief presented. A rejected selection (hallucinated id, no rationale, invalid
-    // confidence) is refused; needs-review signals (low/missing confidence) are recorded, not blocked.
     let grounding;
     if (options.rationale !== undefined || options.confidence !== undefined) {
         grounding = groundSelection({ variantId, rationale: options.rationale, confidence: options.confidence }, brief.candidateSolutions.map((candidate) => candidate.id));
@@ -277,7 +270,7 @@ export async function acceptCreativeVariant(options) {
             designPatternIds: selected.uxPatternIds,
             capabilityNotes: selected.feasibility.notes,
         },
-        nextStep: "Run `vise plan . --request <original request>` or `vise workplan next . --request <original request>`; Vise will include this accepted creative selection as advisory implementation context.",
+        nextStep: "Run `vise experience compile .` to compile this accepted selection into an implementation plan (the next stage of the engagement-intelligence pipeline). Then run `vise plan . --request <original request>` or `vise workplan next . --request <original request>`; Vise will include this accepted creative selection as advisory implementation context.",
     };
     if (options.write !== false) {
         selection.artifacts = await writeCreativeSelection(repoRoot, selection);
@@ -286,27 +279,14 @@ export async function acceptCreativeVariant(options) {
     }
     return selection;
 }
-/**
- * Record a no-fit: the driving agent reported that NO catalog variant fits the request (the
- * grounding contract's honest "none" answer). This completes the no-fit path -- instead of the signal
- * being lost ("just tell the user"), it is grounded and persisted as a structured, HUMAN-reviewable
- * catalog-gap record. It does NOT accept a variant, write a selection, build a UX harness, change the
- * catalog, or upload anything (Calibration Boundary). A human reads the record and decides whether the
- * catalog needs a new variant. Separate from acceptCreativeVariant so a no-fit never produces a
- * variant-less CreativeSelection.
- */
 export async function recordCatalogGap(options) {
     const repoRoot = path.resolve(options.repoPath);
     const briefPath = creativeBriefPath(repoRoot, options.briefPath);
     const brief = await readCreativeBrief(repoRoot, options.briefPath);
-    // Ground the no-fit answer. groundSelection requires a rationale (what is missing) even for "none";
-    // a no-fit with no reason is useless, so it is rejected here just like a rationale-less accept.
     const grounding = groundSelection({ variantId: NO_FIT, rationale: options.rationale, confidence: options.confidence }, brief.candidateSolutions.map((candidate) => candidate.id));
     if (grounding.status === "rejected") {
         throw new Error(`No-fit record was rejected: ${grounding.signals.filter((signal) => signal.severity === "error").map((signal) => signal.message).join(" ")}`);
     }
-    // Optional nearest existing variant, validated against the FULL catalog (a gated variant is a valid
-    // "closest" -- e.g. the gap may be served by something still in development).
     let closestVariantId = null;
     let closestWhenToChoose = null;
     const closest = options.closest?.trim();
@@ -407,12 +387,19 @@ async function loadCatalog() {
 }
 async function readCreativeBrief(repoRoot, inputPath) {
     const filePath = creativeBriefPath(repoRoot, inputPath);
+    const rel = repoRelativePath(repoRoot, filePath);
+    let raw;
     try {
-        return JSON.parse(await readFile(filePath, "utf8"));
+        raw = await readFile(filePath, "utf8");
     }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new Error(`Unable to read creative brief at ${repoRelativePath(repoRoot, filePath)}. Run \`vise creative . --request "..."\` first. ${detail}`);
+    catch {
+        throw new Error(`Unable to read creative brief at ${rel}. Run \`vise creative . --request "..."\` first.`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Creative brief at ${rel} is present but could not be parsed (corrupt JSON). Re-run \`vise creative . --request "..."\` to regenerate it.`);
     }
 }
 function creativeBriefPath(repoRoot, inputPath) {
@@ -502,8 +489,6 @@ async function rankVariants(catalog, text, goals, archetypes, inspection, reques
     const archetypeScores = new Map(archetypes.map((archetype) => [archetype.id, archetype.score]));
     const patternById = new Map(catalog.solutionPatterns.map((pattern) => [pattern.id, pattern]));
     const uxById = new Map(catalog.uxPatterns.map((pattern) => [pattern.id, pattern]));
-    // Availability gate: in-development variants stay in the catalog but are never surfaced to
-    // agents/customers (the brief, and therefore accept, can only reach available variants).
     const availableVariants = catalog.variants.filter((variant) => variant.availability !== "in-development");
     const scored = availableVariants.map((variant) => {
         const goalScore = variant.businessGoalIds.reduce((sum, id) => sum + (goalScores.has(id) ? 4 + (goalScores.get(id) ?? 0) : 0), 0);
@@ -514,8 +499,6 @@ async function rankVariants(catalog, text, goals, archetypes, inspection, reques
         const uxScore = variant.uxPatternIds.reduce((sum, id) => sum + scoreKeywords(text, termsForUx(uxById.get(id))), 0);
         return { variant, score: goalScore + archetypeScore + labelScore + patternScore + objectScore + uxScore };
     });
-    // Surface the FULL catalog as the agent's choice space (Option A): the keyword score only orders the
-    // list (advisory) and flags the top as `recommended` — it must not gate which variants are reachable.
     const top = scored.sort((a, b) => b.score - a.score || a.variant.id.localeCompare(b.variant.id));
     const topOrFallback = top.length > 0 ? top : catalog.variants.map((variant) => ({ variant, score: 0 }));
     const candidates = [];
@@ -1004,7 +987,6 @@ function assumptionsFor(mode, requirements, prototype, inspection) {
 function reasonForVariant(variant, goals, archetypes, feasibility, isFallbackDefault) {
     const matchedGoals = variant.businessGoalIds.filter((id) => goals.some((goal) => goal.id === id));
     const matchedArchetypes = variant.archetypeIds.filter((id) => archetypes.some((archetype) => archetype.id === id));
-    // Non-authoritative framing: the keyword top is the fallback default, not a recommendation.
     const prefix = isFallbackDefault ? "Strongest keyword match because" : "Included because";
     const parts = [
         matchedGoals.length > 0 ? `it supports ${matchedGoals.join(", ")}` : "it provides a distinct engagement direction",
@@ -1108,8 +1090,6 @@ function shellQuote(value) {
 function repoRelativePath(repoRoot, filePath) {
     return path.relative(repoRoot, filePath).split(path.sep).join("/");
 }
-// Derived from the surface registry + per-object `surface` assignments (src/intelligence/placement.ts).
-// objectIds come straight from the catalog, so adding an object to a surface is a JSON edit.
 const CREATIVE_SURFACE_HINTS = SURFACE_REGISTRY.map((surface) => ({
     id: surface.id,
     outcome: surface.outcome,
@@ -1117,12 +1097,6 @@ const CREATIVE_SURFACE_HINTS = SURFACE_REGISTRY.map((surface) => ({
     objectIds: surfaceObjectIds(surface.id),
     reason: "",
 }));
-// GOAL_KEYWORDS / ARCHETYPE_KEYWORDS are the advisory keyword-ranker terms. They are
-// DERIVED from the catalog `matchTerms` field (business-goals.json / archetypes.json) so a
-// new goal/archetype is contributable in data alone — no code edit here. Read synchronously
-// at module load to preserve the synchronous Record<string, string[]> export contract. The
-// catalog↔map coverage guard (test/run-intelligence-catalog.mjs) and the schema (matchTerms
-// required, test/run-catalog-schema.mjs) both fail loud if an entry omits matchTerms.
 function keywordMapFromCatalog(fileName) {
     const filePath = path.join(catalogRoot(), fileName);
     const parsed = JSON.parse(readFileSync(filePath, "utf8"));

package/dist/tools/debug.js

@@ -2,18 +2,14 @@ import { objectInput, optionalBooleanField, stringField, textResult } from "../t
 import { checkCompliance, rulesById } from "./compliance.js";
 import { inspectProject } from "./project.js";
 function sanitizeError(errorMessage) {
-    // Strip out local absolute file paths (e.g., /Users/admin/..., /home/user/...)
     let sanitized = errorMessage.replace(/(?:\/(?:users|home)\/[^\s:]+)/gi, "[LOCAL_PATH]");
-    // Strip out thread IDs / Hex memory addresses
     sanitized = sanitized.replace(/0x[0-9a-fA-F]+/g, "[HEX_ADDR]");
     return sanitized;
 }
 function extractExceptionClass(errorMessage) {
-    // Try to find a Java/Kotlin exception (e.g. java.lang.NullPointerException or com.amity.AmityException)
     const javaMatch = errorMessage.match(/([a-zA-Z0-9_.]+[A-Z][a-zA-Z0-9_]*Exception)/);
     if (javaMatch)
         return javaMatch[1];
-    // Try to find a JS Error (e.g. TypeError, Error)
     const jsMatch = errorMessage.match(/([A-Z][a-zA-Z0-9]*Error):/);
     if (jsMatch)
         return jsMatch[1];
@@ -22,18 +18,11 @@ function extractExceptionClass(errorMessage) {
 export async function debugIssue(repoPath, errorMessage, options = {}) {
     const sanitizedError = sanitizeError(errorMessage);
     const exceptionClass = extractExceptionClass(errorMessage);
-    // 1. Inspect Context
     const inspection = await inspectProject(repoPath);
-    // 2. Version-mismatch heuristic (NOT used as benchmark evidence).
-    // This is a keyword-only heuristic, not real dependency inspection.
-    // Version-mismatch scenarios are excluded from the TypeScript pilot
-    // (see DEBUGGING_BENCHMARK_PLAN.md Section 5 "Explicitly excluded from the pilot").
-    // Do not use this branch as measured benchmark evidence.
     let likelyCause = "";
     if (errorMessage.includes("method not found") || errorMessage.includes("Unresolved reference")) {
         likelyCause = "Potential Version Mismatch: The codebase is using a newer API pattern against an older SDK version installed in the project.";
     }
-    // 3. Compliance History Correlation
     const correlatedRules = [];
     let checkResult = null;
     try {
@@ -41,7 +30,6 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
         const rulesMap = await rulesById();
         for (const rule of checkResult.rules) {
             if (rule.status === "deterministic-fail" || rule.status === "attestation-needed") {
-                // It failed. Check if symptoms match.
                 const contractRuleId = rule.contractRuleId ?? rule.ruleId;
                 const ruleDef = rulesMap.get(contractRuleId);
                 const symptoms = ruleDef?.symptoms || [];
@@ -54,7 +42,6 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
                 }
             }
             else if (rule.status === "attested") {
-                // Check for false-positive attestations
                 const contractRuleId = rule.contractRuleId ?? rule.ruleId;
                 const ruleDef = rulesMap.get(contractRuleId);
                 const symptoms = ruleDef?.symptoms || [];
@@ -70,7 +57,6 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
         }
     }
     catch (err) {
-        // Ignore error if compliance sidecar doesn't exist yet
     }
     if (!likelyCause && correlatedRules.length > 0) {
         likelyCause = `The crash is likely caused by the non-compliant implementation of ${correlatedRules.map(r => r.ruleId).join(", ")}.`;
@@ -78,7 +64,6 @@ export async function debugIssue(repoPath, errorMessage, options = {}) {
     else if (!likelyCause) {
         likelyCause = `An unknown ${exceptionClass || "runtime"} error occurred.`;
     }
-    // Build rule-specific remediation guidance from rule definitions and validator findings.
     const suggestedRemediation = buildRemediation(correlatedRules, checkResult);
     const repairBrief = buildRepairBrief(correlatedRules, checkResult, inspection.platforms, likelyCause);
     const payload = {
@@ -111,7 +96,6 @@ function buildRemediation(correlatedRules, checkResult) {
     }
     const rules = correlatedRules.map(cr => {
         const ruleResult = checkResult?.rules.find(r => r.ruleId === cr.ruleId);
-        // Prefer the validator's per-finding recommendation; fall back to a generic note.
         const guidance = ruleResult?.recommendation
             ?? "Review the rule implementation and ensure the SDK integration matches the required pattern.";
         return {