@amityco/social-plus-vise 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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).

package/dist/tools/design.js

@@ -2391,23 +2391,28 @@ const ROLE_RULES = [
         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),
+        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'",
+        reason: "name contains 'primary' (and is not a text-family name)",
     },
     {
-        test: (n) => /\bbrand\b|\baccent\b/.test(n),
+        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'",
+        reason: "name contains 'brand' or 'accent' (and is not a text-family name)",
     },
     {
-        test: (n) => /\bsecondary\b/.test(n),
+        test: (n) => /\bsecondary\b/.test(n) && !/\btext\b|foreground|\bfg\b/.test(n),
         role: "secondaryAction",
         confidence: "high",
-        reason: "name contains 'secondary'",
+        reason: "name contains 'secondary' (and is not a text-family name)",
     },
     {
         test: (n) => /\bdanger\b|\berror\b|\bdestructive\b/.test(n),
@@ -2510,15 +2515,51 @@ export function buildDesignBrief(contract) {
     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.
-    const firstToken = (cat) => contract.tokens.find((t) => t.category === cat && t.name !== null);
-    const radiusToken = firstToken("radius");
-    const spaceToken = firstToken("space");
+    /**
+     * 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 = firstToken("shadow");
+    const shadowToken = representativeToken("shadow");
     const primaryRole = roleMap.get("primaryAction");
     // card hint
     const cardGuidanceLines = [];
@@ -2607,6 +2648,31 @@ export function buildDesignBrief(contract) {
     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") {
@@ -2626,12 +2692,38 @@ export function buildDesignBrief(contract) {
     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}.`
+        ? `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}.`
+            ? `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,
@@ -2728,6 +2820,16 @@ export function buildOutcomeDesignRecipe(brief, outcome) {
             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 { buildDesignBrief, buildOutcomeDesignRecipe, 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,13 +71,14 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
         answers,
     });
     const definition = getOutcomeDefinition(outcome);
-    // Design contract is loaded before intake so the brief can inform the fallback
-    // intake question (missing primary-action token) at assembly time.
+    // 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;
-    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
@@ -119,7 +120,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 && designBrief ? designContractGuidance(designContract, designBrief) : undefined,
+        designContract: designContract ? designContractGuidance(designContract) : undefined,
         completenessChecklist: completenessChecklistFor(outcome),
         sdkVersion,
     };
@@ -143,7 +144,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, brief) {
+function designContractGuidance(contract) {
     const byCategory = (category) => contract.tokens
         .filter((token) => token.category === category)
         .map((token) => token.provenance === "declared" && token.name
@@ -168,7 +169,6 @@ function designContractGuidance(contract, brief) {
         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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",