@amityco/social-plus-vise 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@amityco/social-plus-vise` are documented in this file.
 
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.14.0 — 2026-06-03
+
+**Theme:** DesignBuildBrief — plan-time, grounded UI-building guidance for coding agents (advisory).
+
+### Added
+- **DesignBuildBrief in `vise plan`** (`designContract.brief`): conservative semantic token roles inferred from token NAMES only (noun-first compounds — `--text-primary` binds `textPrimary`, never `primaryAction`; value-based inference is forbidden), token-derived component hints (card/button/input) with explicit absent variants, and grounded do/avoid lines — every line cites the declared tokens/roles it derives from, and an ungrounded line is structurally impossible. For `add-feed` / `add-chat` outcomes the brief carries a conditional **outcome recipe** whose items only reference roles that were actually inferred. Generated at plan time — never persisted to `sp-vise/`, never part of any digest.
+- **Non-blocking `primary_action_token` intake question** when a design contract exists for a feed/chat outcome but no primary-action token was confidently identified — the agent asks instead of guessing.
+
+### Notes
+- Advisory only; never gates `vise check`. **No design-conformance improvement is claimed for the brief yet** — a pre-registered ablation (`benchmarks/brief-ablation/PROTOCOL.md`: 0.13.0 vs 0.14.0, same contract, n=3, Cursor/Composer 2.5) measures its effect; documentation claims will follow the measurement.
+
+---
+
 ## 0.13.0 — 2026-06-03
 
 **Theme:** Deterministic-gate soundness, CLI reliability, and post-rebrand coherence (driven by two repo reviews).

package/dist/tools/design.js

@@ -2323,3 +2323,412 @@ function stableStringify(value) {
     }
     return JSON.stringify(value);
 }
+/**
+ * Structural grounding helper: builds a BriefLine and throws a TypeError at
+ * construction time if groundedIn is empty. This makes the grounding invariant
+ * structural — an ungrounded line is impossible rather than a runtime surprise.
+ */
+function line(text, groundedIn, confidence = "high") {
+    if (groundedIn.length === 0) {
+        throw new TypeError(`BriefLine created with empty groundedIn: "${text}"`);
+    }
+    return { text, groundedIn, confidence };
+}
+/**
+ * Per-role keyword rules in spec-defined order.
+ * Each entry: [pattern, role, confidence].
+ * Rules are applied with first-match-wins semantics.
+ * Compound rules (muted+text, muted+bg/surface) must precede their plain
+ * counterparts so "--color-text-muted" resolves to textSecondary, not textPrimary.
+ */
+const ROLE_RULES = [
+    // Compound rules — must precede their plain counterparts
+    {
+        test: (n) => /muted/.test(n) && /\btext\b|foreground|fg/.test(n),
+        role: "textSecondary",
+        confidence: "medium",
+        reason: "name contains 'muted' and 'text'/'foreground'/'fg'",
+    },
+    {
+        test: (n) => /muted/.test(n) && /\bbg\b|surface|background/.test(n),
+        role: "surfaceMuted",
+        confidence: "medium",
+        reason: "name contains 'muted' and 'bg'/'surface'/'background'",
+    },
+    // Noun-first compounds — in real design systems the NOUN keyword (text/surface/
+    // bg/border) sets the role family and primary/secondary act as modifiers within
+    // it: "--text-primary" is the primary BODY-TEXT color, not the action color.
+    // These must precede the plain primary/secondary rules below, or first-match-wins
+    // would misbind some of the most common token names in the wild.
+    {
+        test: (n) => /\btext\b|foreground|\bfg\b/.test(n) && /\bprimary\b/.test(n),
+        role: "textPrimary",
+        confidence: "high",
+        reason: "name contains 'text'/'foreground'/'fg' with 'primary' — the noun keyword sets the role family",
+    },
+    {
+        test: (n) => /\btext\b|foreground|\bfg\b/.test(n) && /\bsecondary\b/.test(n),
+        role: "textSecondary",
+        confidence: "high",
+        reason: "name contains 'text'/'foreground'/'fg' with 'secondary' — the noun keyword sets the role family",
+    },
+    {
+        test: (n) => /surface|background|\bbg\b/.test(n) && /\bprimary\b/.test(n),
+        role: "surface",
+        confidence: "high",
+        reason: "name contains 'surface'/'background'/'bg' with 'primary' — a primary surface, not an action color",
+    },
+    {
+        test: (n) => /surface|background|\bbg\b/.test(n) && /\bsecondary\b/.test(n),
+        role: "surfaceMuted",
+        confidence: "medium",
+        reason: "name contains 'surface'/'background'/'bg' with 'secondary' — a secondary surface",
+    },
+    {
+        test: (n) => /\bborder\b|\boutline\b|\bdivider\b/.test(n) && (/\bprimary\b/.test(n) || /\bsecondary\b/.test(n)),
+        role: "border",
+        confidence: "medium",
+        reason: "name contains a border keyword with a primary/secondary modifier — the noun keyword sets the role family",
+    },
+    // Primary: plain "primary" → high; "brand"/"accent" → medium
+    {
+        test: (n) => /\bprimary\b/.test(n) && !/brand|accent/.test(n),
+        role: "primaryAction",
+        confidence: "high",
+        reason: "name contains 'primary'",
+    },
+    {
+        test: (n) => /\bbrand\b|\baccent\b/.test(n),
+        role: "primaryAction",
+        confidence: "medium",
+        reason: "name contains 'brand' or 'accent'",
+    },
+    {
+        test: (n) => /\bsecondary\b/.test(n),
+        role: "secondaryAction",
+        confidence: "high",
+        reason: "name contains 'secondary'",
+    },
+    {
+        test: (n) => /\bdanger\b|\berror\b|\bdestructive\b/.test(n),
+        role: "danger",
+        confidence: "high",
+        reason: "name contains 'danger', 'error', or 'destructive'",
+    },
+    {
+        test: (n) => /\bsuccess\b|\bpositive\b/.test(n),
+        role: "success",
+        confidence: "high",
+        reason: "name contains 'success' or 'positive'",
+    },
+    {
+        test: (n) => /surface|background|\bbg\b/.test(n),
+        role: "surface",
+        confidence: "high",
+        reason: "name contains 'surface', 'background', or 'bg'",
+    },
+    {
+        test: (n) => /\btext\b|foreground|\bfg\b/.test(n),
+        role: "textPrimary",
+        confidence: "high",
+        reason: "name contains 'text', 'foreground', or 'fg'",
+    },
+    {
+        test: (n) => /\bborder\b|\boutline\b|\bdivider\b/.test(n),
+        role: "border",
+        confidence: "high",
+        reason: "name contains 'border', 'outline', or 'divider'",
+    },
+    {
+        test: (n) => /\bfocus\b|\bring\b/.test(n),
+        role: "focus",
+        confidence: "high",
+        reason: "name contains 'focus' or 'ring'",
+    },
+    {
+        test: (n) => /\bavatar\b/.test(n),
+        role: "avatarFallback",
+        confidence: "high",
+        reason: "name contains 'avatar'",
+    },
+];
+/** Infer a (role, confidence, reason) from a token name, or null if no rule matches. */
+function inferRole(tokenName) {
+    const n = tokenName.toLowerCase();
+    for (const rule of ROLE_RULES) {
+        if (rule.test(n)) {
+            return { role: rule.role, confidence: rule.confidence, reason: rule.reason };
+        }
+    }
+    return null;
+}
+/**
+ * Among multiple candidates for the same role, prefer:
+ * 1. high confidence over medium
+ * 2. shorter name (e.g. "--color-primary" beats "--color-primary-hover")
+ */
+function bestCandidate(a, b) {
+    if (a.confidence === "high" && b.confidence !== "high")
+        return a;
+    if (b.confidence === "high" && a.confidence !== "high")
+        return b;
+    return a.token.length <= b.token.length ? a : b;
+}
+/**
+ * Build a DesignBuildBrief from a DesignContract.
+ *
+ * - Pure: no I/O, no side effects.
+ * - Never persisted or digested.
+ * - Every BriefLine has non-empty groundedIn citing actual contract tokens/roles.
+ * - Roles inferred from NAME only (never from value).
+ * - Inferred tokens (name: null) are never cited by name; they may be cited only
+ *   as a count for do/avoid prose, but only if the contract has declared color
+ *   tokens with recognizable names to ground the line instead.
+ */
+export function buildDesignBrief(contract) {
+    const strength = contract.stats.strength;
+    // ── Role inference ──────────────────────────────────────────────────────────
+    // Walk only declared color tokens (provenance=declared, category=color, name != null).
+    // Inferred tokens always have name: null; value-only matching is forbidden.
+    const colorTokens = contract.tokens.filter((t) => t.category === "color" && t.name !== null);
+    const roleMap = new Map();
+    for (const token of colorTokens) {
+        const inferred = inferRole(token.name);
+        if (!inferred) {
+            continue;
+        }
+        const candidate = {
+            role: inferred.role,
+            token: token.name,
+            value: token.value,
+            confidence: inferred.confidence,
+            reason: inferred.reason,
+        };
+        const existing = roleMap.get(inferred.role);
+        roleMap.set(inferred.role, existing ? bestCandidate(existing, candidate) : candidate);
+    }
+    const roles = [...roleMap.values()];
+    // Helper: is a role name in this brief?
+    const roleNames = new Set(roles.map((r) => r.role));
+    // ── Component hints ─────────────────────────────────────────────────────────
+    // Reference ONLY tokens that actually exist in the contract.
+    const firstToken = (cat) => contract.tokens.find((t) => t.category === cat && t.name !== null);
+    const radiusToken = firstToken("radius");
+    const spaceToken = firstToken("space");
+    // Border colour: sourced from the inferred border role (a color token named *border*/*outline*/*divider*).
+    // There is no "border" TokenCategory — border colours live in the "color" category.
+    const borderRoleColor = roleMap.get("border");
+    const shadowToken = firstToken("shadow");
+    const primaryRole = roleMap.get("primaryAction");
+    // card hint
+    const cardGuidanceLines = [];
+    if (radiusToken) {
+        cardGuidanceLines.push(line(`Use ${radiusToken.name} (${radiusToken.value}) for card corner radius.`, [radiusToken.name]));
+    }
+    if (spaceToken) {
+        cardGuidanceLines.push(line(`Use ${spaceToken.name} (${spaceToken.value}) for card internal padding.`, [spaceToken.name]));
+    }
+    if (borderRoleColor) {
+        cardGuidanceLines.push(line(`Apply ${borderRoleColor.token} for card border colour.`, [borderRoleColor.role]));
+    }
+    else if (shadowToken) {
+        cardGuidanceLines.push(line(`Apply ${shadowToken.name} for card shadow/elevation.`, [shadowToken.name]));
+    }
+    const cardHint = cardGuidanceLines.length > 0
+        ? { kind: "card", guidance: cardGuidanceLines, confidence: radiusToken && spaceToken ? "high" : "medium" }
+        : { kind: "card", absent: true, note: "No card pattern confidently identified — reuse the host app's existing card styles." };
+    // button hint
+    const buttonGuidanceLines = [];
+    if (primaryRole) {
+        buttonGuidanceLines.push(line(`Use ${primaryRole.token} (${primaryRole.value}) as the primary button background.`, [primaryRole.role]));
+    }
+    if (radiusToken) {
+        buttonGuidanceLines.push(line(`Apply ${radiusToken.name} (${radiusToken.value}) for button corner radius.`, [radiusToken.name]));
+    }
+    if (spaceToken) {
+        buttonGuidanceLines.push(line(`Apply ${spaceToken.name} (${spaceToken.value}) for button horizontal padding.`, [spaceToken.name]));
+    }
+    const buttonHint = buttonGuidanceLines.length > 0
+        ? { kind: "button", guidance: buttonGuidanceLines, confidence: primaryRole ? "high" : "medium" }
+        : { kind: "button", absent: true, note: "No button pattern confidently identified — reuse the host app's existing button styles." };
+    // input hint
+    const inputGuidanceLines = [];
+    if (borderRoleColor) {
+        inputGuidanceLines.push(line(`Use ${borderRoleColor.token} for input border colour.`, [borderRoleColor.role]));
+    }
+    if (radiusToken) {
+        inputGuidanceLines.push(line(`Apply ${radiusToken.name} (${radiusToken.value}) for input corner radius.`, [radiusToken.name]));
+    }
+    if (spaceToken) {
+        inputGuidanceLines.push(line(`Apply ${spaceToken.name} (${spaceToken.value}) for input internal padding.`, [spaceToken.name]));
+    }
+    const inputHint = inputGuidanceLines.length > 0
+        ? { kind: "input", guidance: inputGuidanceLines, confidence: borderRoleColor ? "high" : "medium" }
+        : { kind: "input", absent: true, note: "No input pattern confidently identified — reuse the host app's existing input styles." };
+    const componentHints = [cardHint, buttonHint, inputHint];
+    // ── Do/Avoid lines ──────────────────────────────────────────────────────────
+    // Every line MUST be grounded in tokens/roles that actually exist in this brief.
+    const doLines = [];
+    const avoidLines = [];
+    // Only emit do/avoid lines that are grounded in actually-present tokens.
+    const declaredColorTokens = colorTokens.filter((t) => t.provenance === "declared");
+    const declaredSpaceTokens = contract.tokens.filter((t) => t.category === "space" && t.name !== null && t.provenance === "declared");
+    const declaredRadiusTokens = contract.tokens.filter((t) => t.category === "radius" && t.name !== null && t.provenance === "declared");
+    // Do: use declared color tokens
+    if (declaredColorTokens.length > 0) {
+        const tokenNames = declaredColorTokens.slice(0, 3).map((t) => t.name);
+        doLines.push(line(`Reference declared color tokens (e.g. ${tokenNames.join(", ")}) — never introduce new hex literals.`, tokenNames));
+    }
+    // Do: use declared space tokens
+    if (declaredSpaceTokens.length > 0) {
+        const tokenNames = declaredSpaceTokens.slice(0, 3).map((t) => t.name);
+        doLines.push(line(`Reference declared spacing tokens (e.g. ${tokenNames.join(", ")}) for margins, padding, and gaps.`, tokenNames));
+    }
+    // Do: use declared radius tokens
+    if (declaredRadiusTokens.length > 0) {
+        const tokenNames = declaredRadiusTokens.slice(0, 2).map((t) => t.name);
+        doLines.push(line(`Use declared radius tokens (e.g. ${tokenNames.join(", ")}) for corner rounding.`, tokenNames));
+    }
+    // Do: use primary-role token for interactive elements
+    if (primaryRole) {
+        doLines.push(line(`Use the primary colour token (${primaryRole.token}) for primary interactive elements (buttons, CTAs).`, [primaryRole.role]));
+    }
+    // Avoid: hex literals (grounded in declared color tokens)
+    if (declaredColorTokens.length > 0) {
+        const tokenNames = declaredColorTokens.slice(0, 3).map((t) => t.name);
+        avoidLines.push(line(`Do not introduce new hex or colour literals — use the ${declaredColorTokens.length} declared colour token(s) (e.g. ${tokenNames.join(", ")}).`, tokenNames));
+    }
+    // Avoid: raw spacing literals (grounded in declared space tokens)
+    if (declaredSpaceTokens.length > 0) {
+        const tokenNames = declaredSpaceTokens.slice(0, 2).map((t) => t.name);
+        avoidLines.push(line(`Do not hardcode raw spacing values — use declared spacing tokens (e.g. ${tokenNames.join(", ")}).`, tokenNames));
+    }
+    // Avoid: overriding the primary colour token on interactive elements
+    if (primaryRole) {
+        avoidLines.push(line(`Do not override the primary colour token (${primaryRole.token}) with ad-hoc colours on interactive elements.`, [primaryRole.role]));
+    }
+    // ── Review notes ─────────────────────────────────────────────────────────────
+    const reviewNotes = [];
+    if (strength === "weak") {
+        reviewNotes.push("Contract is weak — very few named tokens were found. Guidance above is minimal. Run `vise design extract --from-project` to derive a richer contract from the host project's design system, or provide a prototype.");
+    }
+    if (roles.length === 0) {
+        reviewNotes.push("No colour roles could be inferred from token names. Role-based guidance is unavailable. Ensure tokens use recognisable names (e.g. --color-primary, --color-surface) and run `vise design extract --from-project` again.");
+    }
+    // Suggest missing roles using name examples, not camelCase role identifiers
+    // (camelCase role names must not appear in prose to keep the weak/neutral brief JSON clean).
+    if (!roleNames.has("primaryAction") && contract.stats.declared_tokens > 0) {
+        reviewNotes.push("No primary action colour found — consider naming a token --color-primary (or --color-brand / --color-accent) for primary interactive elements.");
+    }
+    if (!roleNames.has("surface") && contract.stats.declared_tokens > 0) {
+        reviewNotes.push("No surface colour found — consider naming a token --color-surface or --color-background.");
+    }
+    if (!roleNames.has("border") && contract.stats.declared_tokens > 0) {
+        reviewNotes.push("No border colour found — consider naming a token --color-border or --color-outline.");
+    }
+    // ── Summary ──────────────────────────────────────────────────────────────────
+    const tokenCount = contract.tokens.filter((t) => t.name !== null).length;
+    const summary = roles.length > 0
+        ? `Brief grounded in ${tokenCount} named token(s) and ${roles.length} inferred role(s). Contract strength: ${strength}.`
+        : tokenCount > 0
+            ? `Brief grounded in ${tokenCount} named token(s); no colour roles could be inferred from token names. Contract strength: ${strength}.`
+            : `Contract has no named tokens — guidance is unavailable. Contract strength: ${strength}. Run \`vise design extract --from-project\` to derive tokens from the host project.`;
+    return {
+        summary,
+        strength,
+        roles,
+        componentHints,
+        do: doLines,
+        avoid: avoidLines,
+        reviewNotes,
+    };
+}
+/**
+ * Build outcome-specific design recipe items grounded in an existing brief.
+ *
+ * HARD INVARIANT: every item is grounded ONLY in roles/tokens already in the brief.
+ * Items for absent roles are silently omitted. Returns `undefined` when zero items
+ * can be grounded (e.g. empty brief).
+ *
+ * Pure — no I/O, no side effects. Generated at plan time; never persisted.
+ */
+export function buildOutcomeDesignRecipe(brief, outcome) {
+    const roleMap = new Map(brief.roles.map((r) => [r.role, r]));
+    // Collect groundedIn entries from a given component hint (absent hints contribute nothing).
+    const hintGrounding = (kind) => {
+        const hint = brief.componentHints.find((h) => h.kind === kind);
+        if (!hint || "absent" in hint)
+            return [];
+        return hint.guidance.flatMap((l) => l.groundedIn);
+    };
+    // Collect radius-specific grounding from the card hint by looking for guidance
+    // lines that mention "corner radius" — avoids mis-citing a space token as radius.
+    const cardRadiusGrounding = () => {
+        const hint = brief.componentHints.find((h) => h.kind === "card");
+        if (!hint || "absent" in hint)
+            return [];
+        return hint.guidance
+            .filter((l) => l.text.includes("corner radius"))
+            .flatMap((l) => l.groundedIn);
+    };
+    const items = [];
+    if (outcome === "add-feed") {
+        // Composer / action button — only when primaryAction exists.
+        const primaryAction = roleMap.get("primaryAction");
+        if (primaryAction) {
+            items.push(line(`The post composer action button uses the primary action colour token (${primaryAction.token}).`, ["primaryAction"]));
+        }
+        // Post cards — only when the card hint has grounding tokens.
+        const cardGrounding = hintGrounding("card");
+        if (cardGrounding.length > 0) {
+            items.push(line("Post cards follow the card component hint: apply the card hint tokens for corner radius, padding, and border/shadow.", cardGrounding));
+        }
+        // Post metadata and timestamps.
+        const textSecondary = roleMap.get("textSecondary");
+        if (textSecondary) {
+            items.push(line(`Post metadata and timestamps use the secondary text colour token (${textSecondary.token}).`, ["textSecondary"]));
+        }
+        // Report / delete affordances.
+        const danger = roleMap.get("danger");
+        if (danger) {
+            items.push(line(`Report and delete affordances use the danger colour token (${danger.token}).`, ["danger"]));
+        }
+    }
+    else {
+        // add-chat
+        // Message bubbles use surface.
+        const surface = roleMap.get("surface");
+        if (surface) {
+            const radiusGrounding = cardRadiusGrounding();
+            if (radiusGrounding.length > 0) {
+                items.push(line(`Message bubbles use the surface colour token (${surface.token}) with the card corner radius token applied.`, ["surface", ...radiusGrounding]));
+            }
+            else {
+                items.push(line(`Message bubbles use the surface colour token (${surface.token}).`, ["surface"]));
+            }
+        }
+        // Own-message vs other-message contrast — ONLY when BOTH primaryAction AND surface exist.
+        const primaryAction = roleMap.get("primaryAction");
+        if (primaryAction && surface) {
+            items.push(line(`Own messages use the primary action colour (${primaryAction.token}) as background; other messages use the surface colour (${surface.token}).`, ["primaryAction", "surface"]));
+        }
+        // Timestamps.
+        const textSecondary = roleMap.get("textSecondary");
+        if (textSecondary) {
+            items.push(line(`Message timestamps use the secondary text colour token (${textSecondary.token}).`, ["textSecondary"]));
+        }
+        // Composer follows the input hint tokens.
+        const inputGrounding = hintGrounding("input");
+        if (inputGrounding.length > 0) {
+            items.push(line("The message composer follows the input component hint: apply the input hint tokens for border colour, corner radius, and padding.", inputGrounding));
+        }
+        // Moderation actions.
+        const danger = roleMap.get("danger");
+        if (danger) {
+            items.push(line(`Moderation actions (report, block, mute) use the danger colour token (${danger.token}).`, ["danger"]));
+        }
+    }
+    if (items.length === 0)
+        return undefined;
+    return { outcome, items };
+}

package/dist/tools/integration.js

@@ -4,7 +4,7 @@ import { BROAD_SOCIAL_REGEX, DESIGN_REGEX, classifyOutcome, getOutcomeDefinition
 import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
 import { capabilityChecklist } from "../capabilities.js";
 import { applicableComplianceRuleSummaries } from "./compliance.js";
-import { readDesignContract } from "./design.js";
+import { buildDesignBrief, buildOutcomeDesignRecipe, readDesignContract } from "./design.js";
 import { sdkVersionGuidance } from "./sdkVersion.js";
 import { detectCommandSensors } from "./harness.js";
 import { inspectProject } from "./project.js";
@@ -71,8 +71,14 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
         answers,
     });
     const definition = getOutcomeDefinition(outcome);
-    const intake = intakeFor(ctx, definition.intakeQuestions(ctx));
+    // Design contract is loaded before intake so the brief can inform the fallback
+    // intake question (missing primary-action token) at assembly time.
     const designContract = await readDesignContract(repoRoot);
+    const designBrief = designContract ? buildDesignBrief(designContract) : undefined;
+    if (designBrief && (outcome === "add-feed" || outcome === "add-chat")) {
+        designBrief.outcomeRecipe = buildOutcomeDesignRecipe(designBrief, outcome) ?? undefined;
+    }
+    const intake = intakeFor(ctx, definition.intakeQuestions(ctx), outcome, designBrief);
     // Advisory SDK-version currency guidance (npm registry for TS/RN; version-agnostic
     // for native). Best-effort — degrades to greenfield "install latest + pin" if the
     // registry is unreachable. Never gates.
@@ -113,7 +119,7 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
         sensors: sensors.map((sensor) => ({ name: sensor.name, command: sensor.command, source: sensor.source })),
         stopConditions: composeStopConditions(ctx, definition.stopConditions(ctx), inspection.surfaces, surfacePath),
         evidencePolicy: "Every implementation step must cite at least one detected file, docs page, validator rule, or required user input. If evidence is missing, stop and ask the user instead of inventing details.",
-        designContract: designContract ? designContractGuidance(designContract) : undefined,
+        designContract: designContract && designBrief ? designContractGuidance(designContract, designBrief) : undefined,
         completenessChecklist: completenessChecklistFor(outcome),
         sdkVersion,
     };
@@ -137,7 +143,7 @@ function completenessChecklistFor(outcome) {
 // references `var(--x)` / maps it per platform); inferred tokens carry their
 // raw value plus a usage count and an explicit "inferred" marker so they are
 // never mistaken for authoritative brand values.
-function designContractGuidance(contract) {
+function designContractGuidance(contract, brief) {
     const byCategory = (category) => contract.tokens
         .filter((token) => token.category === category)
         .map((token) => token.provenance === "declared" && token.name
@@ -162,6 +168,7 @@ function designContractGuidance(contract) {
         breakpoints: contract.breakpoints.map((breakpoint) => breakpoint.raw),
         attestation: `When you record a design attestation, cite this contract digest (${contract.digest}) so the generated feed can be claimed conformant to the customer's prototype.`,
         advisoryOnly: "This contract is advisory generation guidance — it adds no deterministic enforcement and never fails `vise check`.",
+        brief,
     };
 }
 function intentFor(request, interpretation) {
@@ -173,7 +180,7 @@ function intentFor(request, interpretation) {
         ambiguity: broadSocialRequest || designRequest ? "high" : "medium",
     };
 }
-function intakeFor(ctx, outcomeQuestions) {
+function intakeFor(ctx, outcomeQuestions, outcome, brief) {
     const questions = [...outcomeQuestions];
     if (ctx.mentionsDesign && ctx.designSignals.length === 0 && !hasAnswer(ctx.answers, "design_source")) {
         questions.push({
@@ -194,6 +201,21 @@ function intakeFor(ctx, outcomeQuestions) {
             options: ["yes", "use another source"],
         });
     }
+    // Graceful-degradation fallback: when a design contract exists for a feed or chat
+    // outcome but no primary-action token was confidently inferred, ask the developer
+    // to name the correct token. Non-blocking so it doesn't stall implementation.
+    if (brief &&
+        (outcome === "add-feed" || outcome === "add-chat") &&
+        !brief.roles.some((r) => r.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 remainingBlocking = questions.filter((question) => question.blocksImplementationWhenMissing).length;
     return {
         status: remainingBlocking > 0 ? "needs-clarification" : "ready",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -62,9 +62,10 @@
     "test:sdk-version": "npm run build && node test/run-sdk-version.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:e2e-package": "npm run build && node test/run-e2e-package.mjs",
-    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run pack:check",
+    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:design-brief && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run pack:check",
     "test:ast": "node test/run-ast-helpers.mjs",
     "test:design-extract": "npm run build && node test/run-design-extract.mjs",
+    "test:design-brief": "npm run build && node test/run-design-brief.mjs",
     "test:capabilities": "npm run build && node test/run-capabilities.mjs",
     "test:classify": "npm run build && node test/run-classify.mjs",
     "test:debug": "npm run build && node test/run-debug.mjs",