@amityco/social-plus-vise 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.2 — 2026-06-03
+
+**Theme:** SDK facts bridge for social.plus Block Factory.
+
+### Added
+- **Bundled SDK surface snapshot** in `sdk-surface/` for offline/npm use across TypeScript, Android, iOS, and Flutter.
+- **Internal `vise sdk-facts` CLI command and `get_sdk_facts` MCP tool** for Block Factory. The tool is projectless and read-only: it proves SDK symbol/capability/model-symbol facts from the normalized SDK surface without inspecting customer code.
+- **TypeScript Comments/Reactions capability facts** for the first Block Factory validation slice, including React Native aliasing to the TypeScript SDK surface.
+
+---
+
+## 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/README.md

@@ -43,9 +43,9 @@ See [Usage Flow](#usage-flow) for the full step-by-step diagram.
 
 ## What Vise Does: Agentic Workflow Governance
 
-Instead of just providing a CLI or AI skills, Vise implements a technique called **Agentic Workflow Governance**. Think of it as building a software factory directly on top of the customer's project. 
+Instead of just providing a CLI or AI skills, Vise implements a technique called **Agentic Workflow Governance**. Think of it as a customer-project integration harness: the governed build loop runs inside the target repo, grounded in the real project, real docs, and real validation signals.
 
-Vise acts as the foreman of this factory, wrapping your local coding agents in compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 300 platform-specific compliance rules, checks the generated UI against the customer's design system, surfaces the full SDK feature surface so nothing is silently dropped, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
+Vise wraps your local coding agents in compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 300 platform-specific compliance rules, checks the generated UI against the customer's design system, surfaces the full SDK feature surface so nothing is silently dropped, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
 
 At a glance, Vise sits between the user's prompt and the agent's code changes. The agent still edits the app; Vise turns the request into a grounded plan, records the local contract, and keeps checking until the integration is ready to ship.
 
@@ -81,6 +81,15 @@ Vise validates on three layers, and the layer is set by the *kind of claim* —
 
 Only correctness is gated (it can be made FP-free); conformance and completeness are surfaced, because "all post types" and "matches the brand" are legitimately scope-dependent. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
+### Relationship to social.plus Block Factory
+
+Vise has two deliberately separate roles:
+
+- **Customer integration helper:** runs inside customer projects to inspect, plan, validate, and sensor-check social.plus SDK integrations.
+- **Block Factory SDK facts provider:** planned internal mode for social.plus Block Factory to verify SDK capabilities, symbols, and model schemas before reusable blocks are generated or released.
+
+Vise owns SDK truth and customer-project governance. social.plus Block Factory owns block contracts, package adapters, previews, conformance tests, and release readiness. See [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md) for the internal provider-side plan.
+
 ### Design-conformant UI
 
 Vise can ingest the customer's aesthetic into a **design contract** and guide generation to match it — from an HTML/CSS prototype (`vise design extract`) or from the host app's own design system across web + Android + Flutter + iOS (`vise design extract --from-project`: CSS vars/Tailwind/token modules, `colors.xml`, Flutter `Color(0x…)`, iOS `.colorset`/Swift). `vise design check` reports token conformance; `vise design preview` writes a visual review; `vise design reference` generates a full visual design-system spec (swatches, type samples, component demos). All advisory.

package/dist/server.js

@@ -14,6 +14,7 @@ import { planIntegrationTool } from "./tools/integration.js";
 import { inspectProjectTool, validateSetupTool } from "./tools/project.js";
 import { resolveRequestTool, suggestPatchTool } from "./tools/resolve.js";
 import { runSensorsTool } from "./tools/sensors.js";
+import { getSdkFactsTool } from "./tools/sdkFacts.js";
 import { debugIssueTool, debugIssue } from "./tools/debug.js";
 import { packageName, packageVersion } from "./version.js";
 const tools = new Map([
@@ -39,6 +40,7 @@ const tools = new Map([
     designPreviewTool,
     designReferenceTool,
     designInitTokensTool,
+    getSdkFactsTool,
 ].map((tool) => [tool.name, tool]));
 const bundledSkillName = "social-plus-vise";
 // Pre-rebrand `install-skill` runs created skill dirs/files under this name. We
@@ -201,6 +203,20 @@ async function handleCli(args) {
             });
             return "exit";
         }
+        if (command === "sdk-facts" || command === "sdk_facts") {
+            assertOnlyKnownFlags(args, ["platform", "capability", "surface-dir", "format", "include-symbols"], "sdk-facts");
+            const format = flagValue(args, "format") ?? "json";
+            if (format !== "json") {
+                throw new Error("sdk-facts currently supports --format json only.");
+            }
+            await printToolResult(getSdkFactsTool, {
+                platform: requiredFlagValue(args, "platform", "sdk-facts requires --platform."),
+                capability: flagValue(args, "capability"),
+                surfaceDir: flagValue(args, "surface-dir"),
+                includeSymbols: hasFlag(args, "include-symbols"),
+            });
+            return "exit";
+        }
         if (command === "init") {
             assertOnlyKnownFlags(args, ["request", "surface", "surface-path"], "init");
             console.log(JSON.stringify(await initCompliance(positionalRepoPath(args.slice(1)), requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path")), null, 2));
@@ -468,6 +484,16 @@ Resolve a natural-language request into the closest supported Vise outcome.
 
 Usage:
   vise resolve [repoPath] --request "Add a social feed"`;
+    }
+    if (command === "sdk-facts" || command === "sdk_facts") {
+        return `${packageName} sdk-facts
+
+Read bundled SDK surface facts for social.plus Block Factory planning. Internal, projectless, and read-only.
+
+Usage:
+  vise sdk-facts --platform typescript --capability comments --format json
+  vise sdk-facts --platform react-native --capability reactions --include-symbols
+  vise sdk-facts --platform android --surface-dir ./sdk-surface --format json`;
     }
     if (command === "init") {
         return `${packageName} init
@@ -577,6 +603,7 @@ Usage:
   vise status [repoPath]           Print compliance summary
   vise validate [repoPath]         Validate setup and common risks
   vise run-sensors [repoPath]      Run detected project sensors
+  vise sdk-facts --platform ...    Internal SDK surface facts for Block Factory
   vise design extract <prototype>  Extract a design contract from an HTML/CSS prototype
   vise design check [repoPath]     Advisory (non-blocking) UI-vs-contract conformance report
   vise design preview [repoPath]   Write an HTML visual review of the contract + conformance
@@ -830,7 +857,7 @@ function ciCheckResult(result) {
     };
 }
 function positionalRepoPath(args) {
-    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
+    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -852,7 +879,7 @@ function positionalRepoPath(args) {
 }
 function requiredPositionalText(args, message) {
     const values = [];
-    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
+    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {

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) {