@amityco/social-plus-vise 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.1 — 2026-06-03
+
+**Theme:** Retract the enumerative DesignBuildBrief from plan output — our own benchmark said so.
+
+### Changed
+- **`vise plan` no longer emits `designContract.brief`** (the 0.14.0 roles / component hints / outcome recipes). The pre-registered ablation we shipped 0.14.0 with came back negative — twice: agents given the enumerative brief produced LESS on-contract UI than agents given the design contract alone (by-name token usage ~75% vs ~89–92%; two runs, n=6 per arm, Cursor/Composer 2.5; full evidence in `benchmarks/brief-ablation/`). The mechanism: enumerative guidance narrows what capable agents build and style, while the contract + `design check` loop drives wholesale token adoption. We measure before we claim — and this one measured against us, so it's out.
+- **Kept:** the non-blocking `primary_action_token` intake question (the brief is still computed internally to detect a missing primary-action token — it asks instead of steering). The brief generator and its 17-scenario test suite remain in-tree for future redesign.
+
+---
+
+## 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,514 @@ 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
+    // EXCLUSION: action roles bind interactive-family names only.
+    // A token whose name contains a text-family noun (text/foreground/fg) MUST
+    // NEVER bind primaryAction or secondaryAction — it represents a text colour,
+    // not an interactive accent (e.g. --text-bright-accent is a text accent, while
+    // --essential-bright-accent is the real interactive accent).
+    {
+        test: (n) => /\bprimary\b/.test(n) && !/brand|accent/.test(n) && !/\btext\b|foreground|\bfg\b/.test(n),
+        role: "primaryAction",
+        confidence: "high",
+        reason: "name contains 'primary' (and is not a text-family name)",
+    },
+    {
+        test: (n) => /\bbrand\b|\baccent\b/.test(n) && !/\btext\b|foreground|\bfg\b/.test(n),
+        role: "primaryAction",
+        confidence: "medium",
+        reason: "name contains 'brand' or 'accent' (and is not a text-family name)",
+    },
+    {
+        test: (n) => /\bsecondary\b/.test(n) && !/\btext\b|foreground|\bfg\b/.test(n),
+        role: "secondaryAction",
+        confidence: "high",
+        reason: "name contains 'secondary' (and is not a text-family name)",
+    },
+    {
+        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));
+    // String-typed version for use in contexts where we compare arbitrary strings against role names.
+    const roleNameStrings = new Set(roles.map((r) => r.role));
+    // ── Component hints ─────────────────────────────────────────────────────────
+    // Reference ONLY tokens that actually exist in the contract.
+    /**
+     * Representative token selector: among a category's declared tokens, prefer
+     * (in order) a name containing "base", then "default", then "md"/"medium",
+     * then the SHORTEST name, then first-in-order.
+     *
+     * Using first-in-contract-order (old behaviour) selected unrepresentative tokens
+     * like --encore-corner-radius-smaller over --encore-corner-radius-base, causing
+     * agents to anchor on non-base variants and miss the authoritative base token.
+     */
+    function representativeToken(cat) {
+        const candidates = contract.tokens.filter((t) => t.category === cat && t.name !== null && t.provenance === "declared");
+        if (candidates.length === 0)
+            return undefined;
+        // Scoring: lower is better. 0 = base, 1 = default, 2 = md/medium, 3 = shortest, 4 = first.
+        const score = (name) => {
+            const n = name.toLowerCase();
+            if (/\bbase\b/.test(n))
+                return 0;
+            if (/\bdefault\b/.test(n))
+                return 1;
+            if (/\bmd\b|\bmedium\b/.test(n))
+                return 2;
+            return 3;
+        };
+        return candidates.reduce((best, t) => {
+            const bs = score(best.name);
+            const ts = score(t.name);
+            if (ts < bs)
+                return t;
+            if (ts > bs)
+                return best;
+            // Same bucket: prefer shorter name, then first-in-order (best wins ties).
+            return t.name.length < best.name.length ? t : best;
+        });
+    }
+    const radiusToken = representativeToken("radius");
+    const spaceToken = representativeToken("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 = representativeToken("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]));
+    }
+    // ── Breadth instruction (Fix 3 — anti-anchoring) ─────────────────────────────
+    //
+    // The roles and hints above are a starting lens — a minimal named anchor set.
+    // Without an explicit instruction, agents anchor on the named tokens and stop
+    // reading the full token file. This breadth line counters that by directing the
+    // agent to the FULL declared token set, grounded in one representative token
+    // per category so the grounding itself spans the system's breadth.
+    //
+    // Grounding rule: up to one representative declared token per category present,
+    // using the representativeToken() selector (Fix 2). Only emitted when ≥1
+    // declared token exists — weak/empty contracts do NOT get an invented breadth line.
+    const ALL_TOKEN_CATEGORIES = ["color", "space", "radius", "shadow", "fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "borderWidth", "breakpoint", "motion", "opacity", "zIndex"];
+    // Collect one representative declared token per category that has any declared tokens.
+    const breadthGroundingTokens = [];
+    for (const cat of ALL_TOKEN_CATEGORIES) {
+        const rep = representativeToken(cat);
+        if (rep)
+            breadthGroundingTokens.push(rep);
+    }
+    const totalDeclaredTokens = contract.tokens.filter((t) => t.provenance === "declared" && t.name !== null).length;
+    if (breadthGroundingTokens.length > 0) {
+        // Build the grounding set (names of the representative tokens).
+        const breadthGrounding = breadthGroundingTokens.map((t) => t.name);
+        doLines.push(line(`The roles and hints above are a starting lens, not the full design system — reference the FULL declared token set (${totalDeclaredTokens} declared tokens) and prefer an existing token over any new value.`, breadthGrounding));
+    }
+    // ── 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.");
+    }
+    // Conservative-inference reviewNote (Fix 3):
+    // When roles bind fewer than half the declared COLOR tokens, the role inference
+    // was conservative on this vocabulary (e.g. Encore's essential-/decorative-
+    // prefixed names are correct restraint but result in thin role coverage).
+    // Alert the agent that it MUST read the full token file rather than relying on roles alone.
+    const declaredColorCount = declaredColorTokens.length;
+    const colorTokensBoundToRoles = roles.filter((r) => declaredColorTokens.some((t) => t.name === r.token)).length;
+    if (declaredColorCount > 0 && colorTokensBoundToRoles < declaredColorCount / 2) {
+        reviewNotes.push(`Role inference was conservative on this vocabulary — only ${colorTokensBoundToRoles} of ${declaredColorCount} declared colour token(s) are bound to roles. The full token file must be read to discover the complete colour system.`);
+    }
+    // ── Summary ──────────────────────────────────────────────────────────────────
+    const tokenCount = contract.tokens.filter((t) => t.name !== null).length;
+    // Count how many distinct declared token names are referenced by roles + hints.
+    const briefReferencedTokenNames = new Set();
+    for (const r of roles)
+        briefReferencedTokenNames.add(r.token);
+    for (const h of componentHints) {
+        if (!("absent" in h)) {
+            for (const l of h.guidance) {
+                for (const g of l.groundedIn) {
+                    // Only add entries that are actual declared token names (not role names).
+                    if (!roleNameStrings.has(g))
+                        briefReferencedTokenNames.add(g);
+                }
+            }
+        }
+    }
+    const briefCoveredCount = [...briefReferencedTokenNames].filter((n) => contract.tokens.some((t) => t.name === n && t.provenance === "declared")).length;
+    const summary = roles.length > 0
+        ? `Brief grounded in ${tokenCount} named token(s) and ${roles.length} inferred role(s). Contract strength: ${strength}. roles/hints cover ${briefCoveredCount} of ${totalDeclaredTokens} declared tokens — consult the full set.`
+        : tokenCount > 0
+            ? `Brief grounded in ${tokenCount} named token(s); no colour roles could be inferred from token names. Contract strength: ${strength}. roles/hints cover ${briefCoveredCount} of ${totalDeclaredTokens} declared tokens — consult the full set.`
+            : `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"]));
+        }
+    }
+    // Breadth audit item (Fix 3 — anti-anchoring):
+    // Append a final item instructing the agent to audit against the FULL token set.
+    // Grounded the same way as the brief's breadth do-line: reuse the groundedIn of
+    // the "starting lens" do-line if it exists in the brief (spans the breadth of
+    // the system's categories). Only emitted when the brief has declared tokens
+    // (the breadth do-line only exists when there are declared tokens).
+    const breadthDoLine = brief.do.find((l) => l.text.includes("starting lens"));
+    if (breadthDoLine) {
+        items.push(line("Before finishing, audit the UI against the full declared token set and replace any near-miss values with the matching token.", breadthDoLine.groundedIn));
+    }
+    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, readDesignContract } from "./design.js";
 import { sdkVersionGuidance } from "./sdkVersion.js";
 import { detectCommandSensors } from "./harness.js";
 import { inspectProject } from "./project.js";
@@ -71,8 +71,15 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
         answers,
     });
     const definition = getOutcomeDefinition(outcome);
-    const intake = intakeFor(ctx, definition.intakeQuestions(ctx));
+    // The design brief is computed INTERNALLY only, to drive the missing-primary-action
+    // intake fallback. It is deliberately NOT emitted in plan output: a pre-registered
+    // ablation (benchmarks/brief-ablation/RESULTS.md, two runs, n=6/arm) showed that
+    // enumerative plan-time design guidance NARROWS what capable agents build and style —
+    // the contract + design-check loop alone scored higher on by-name token conformance.
+    // Retracted in 0.14.1; the generator stays in design.ts for future redesign.
     const designContract = await readDesignContract(repoRoot);
+    const designBrief = designContract ? buildDesignBrief(designContract) : 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.
@@ -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.1",
   "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",