@amityco/social-plus-vise 0.12.5 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,85 @@ 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).
+
+### Fixed
+- **Boolean flags now accept `--flag=true/false`.** `--ci=true`, `--dry-run=true`, `--force=true`, etc. were parsed as known flags but never detected, so `vise check --ci=true` silently ran in non-CI mode without erroring. Boolean flags now parse `=true/1/yes` → on and `=false/0/no` → off, and reject other values loudly.
+- **`vise install-skill` supersedes pre-rebrand installs.** Installing removes a stale sibling `social-plus-foundry/` skill directory (and `social-plus-foundry.mdc` for `cursor-rules`) so hosts no longer serve old `spf`/foundry guidance alongside the current skill. Reported as `supersededLegacy` in the command output.
+- **CLI no longer crashes on a missing tree-sitter native binding** — the parser loads lazily and degrades to regex-only instead of taking down every command (including doc lookup) at startup; affects platforms without prebuilt binaries (linux-arm64, Alpine/musl, win32-arm64).
+- **Gating literal checks are comment-aware** — a commented-out or documented `channelId`/`apiKey` no longer trips a no-escape gate (a false positive that hard-failed CI with no attestation path). ts/tsx/kotlin use the tree-sitter stripper; Swift/Dart use a conservative string-aware scanner that only blanks comment spans.
+
+### Added
+- **`vise_version`** in `sp-vise/compliance.json`, attestations, `engagement.json`, and the design contract — written alongside the retained `foundry_version` (backward-compatible alias; excluded from all digests, so existing contracts do not drift).
+
+### Changed
+- **Docs/copy aligned to the `Vise` name:** README, skill, and the generated sidecar no longer reference a non-existent `sp-check` binary (use `vise check`); `run-sensors` safety wording corrected ("runs detected project scripts/wrappers; inspect with `--dry-run` before running in an untrusted project"); `RULES.md` gating semantics corrected — the exit code is driven by `advisory`/`attestation.allowed`, not `severity`.
+- **README benchmark section recalibrated** to match the Commune paper: N=1 caveat moved up front, the deterministic-grader/circularity disclosed, the speculative "rework sessions" table removed, and the null bug-fix-benchmark result noted.
+
+---
+
+## 0.12.5 — 2026-06-02
+
+**Theme:** Design token lifecycle — customers can maintain a dedicated social.plus token file independently from their main app, with no AI agent required for updates.
+
+### Added
+- **`vise design init-tokens [path] [--force]`** — scaffolds `src/styles/social-plus-tokens.css` in the customer's project, the single editable source for social.plus feature styling. **Greenfield:** full `--sp-*` neutral defaults (color, typography, spacing, radius, shadow, motion, sizing, z-index, breakpoints). **Brownfield:** seeded from the project's existing concrete token values, namespaced as `--sp-*` with origin comments. Idempotent — never clobbers an existing file; `--force` to override. The token file lives in `src/` (ships with the app); `sp-vise/` holds only the contract (never ships).
+- **Freshness check in `vise design check`** — hashes `source.inputs` files at extract time, stores as `source.input_digests` in the contract. On `design check`, current file hashes are compared; if any changed, an advisory `staleContract` field surfaces a nudge: *"Run `vise design extract --from-project` to refresh."* Never blocks; purely informational. Works identically across all platforms.
+
+---
+
+## 0.12.4 — 2026-06-02
+
+**Theme:** Advisory rule model + honest benchmark methodology.
+
+### Added
+- **Advisory rule flag** (`advisory: true` in rule YAML) — rules marked advisory surface in `vise check` output with `status: "advisory"` but never contribute to `exitCode` or `needs-attestation`. Use for checks where the right answer depends on tenant configuration Vise cannot observe.
+
+### Changed
+- **`reactions.configured-name-used`** (all 5 platforms) downgraded to advisory. Rule fires on ~100% of correct apps (every tenant defaults to `"like"`) and was only clearable by a ritual comment. Version bumped to 2; existing compliance.json files will show contract-drift — run `vise sync` to update.
+
+### Benchmark
+- Brand benchmark (Spotify Encore × social.plus community feed, Sonnet n=3): pure-mcp 0/3 behavioral compliance (avg 2.3 behavioral findings), vise-design 3/3 (0). Ban-state is the standout discriminator — missed by all pure-mcp agents, fixed by all vise-design agents through the iteration loop.
+- Ambiguous-brief design test: vise-design 0 hex literals (all 3 seeds), pure-mcp 0/2/15 (high variance). Design loop is a variance-reduction tool.
+- Grader now partitions findings into behavioral / file-presence / attestation-dialect; headline score is behavioral-only.
+
+---
+
+## 0.12.3 — 2026-06-02
+
+**Theme:** Design harness graduation — complete token extraction, Circles-inspired visual reference.
+
+### Added
+- **`vise design reference [path] [--title <name>]`** — generates a self-contained `sp-vise/design-reference.html` design-system spec: fixed sidebar with grouped nav (COLOR / TYPOGRAPHY / LAYOUT / SURFACE / EFFECTS), sticky topbar, section headers with display-font titles, monospace token-row lists for non-visual groups (motion, breakpoints, z-index), and component samples. Reads source CSS for live `var()` resolution; falls back to contract tokens for native projects (Android/Flutter/iOS correctly grouped by category with concrete values).
+- **6 new token categories** — `fontWeight`, `lineHeight`, `letterSpacing`, `borderWidth`, `breakpoint`, `zIndex`. All name-gated to prevent false positives (bare integers, unitless decimals are ambiguous without the name signal).
+
+### Fixed (silent miscategorizations)
+- `--fs-*` (e.g. `--fs-sm: 14px`) was categorized as "space" — now correctly "fontSize".
+- `--border-width-*` (e.g. `--border-width-thin: 1px`) was categorized as "color" (the color-name regex matched `/border/`) — now correctly "borderWidth". Fix requires the borderWidth check to precede the color branch.
+- `--bp-*` and `--ls-*` fell through to the LENGTH→space fallback — now correctly "breakpoint" and "letterSpacing".
+
+### Changed
+- `renderDesignPreview` now includes sections for all 6 new categories so they aren't silently omitted from `vise design preview` output.
+- `categorizeTokenModuleValue` explicitly excludes the new categories (CSS-only extraction — consistent with the existing opacity exclusion).
+- Streamly seed-ui reference: **69 → 80 tokens**, zero "not extracted" tags in the generated HTML.
+
+---
+
 ## 0.12.2 — 2026-06-02
 
 **Maintenance / hygiene release.** No functional change from `0.12.1` — identical rules, validators, and CLI. This release exists to scrub an anonymized customer name from the bundled `CHANGELOG`; `0.12.0` and `0.12.1` (which contained it) were unpublished from npm. Use `0.12.2`.

package/README.md

@@ -47,6 +47,22 @@ Instead of just providing a CLI or AI skills, Vise implements a technique called
 
 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.**
 
+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.
+
+```mermaid
+flowchart LR
+    Prompt["User prompt<br/>Add a social.plus feature"] --> Skill["AI skill<br/>drives the loop"]
+    Skill --> Inspect["Inspect project<br/>platform, app surface,<br/>design signals"]
+    Inspect --> Plan["Plan<br/>outcome, docs,<br/>intake questions"]
+    Plan --> Design["Design + completeness<br/>tokens, feature checklist,<br/>explicit opt-outs"]
+    Design --> Build["Agent builds<br/>edits customer code locally"]
+    Build --> Check["Vise check<br/>SDK compliance gate"]
+    Check -->|findings| Build
+    Check --> Sensors["Sensors<br/>typecheck, build,<br/>lint, SDK smoke"]
+    Sensors -->|failures| Build
+    Sensors --> Done["Done<br/>sp-vise contract<br/>and evidence"]
+```
+
 | Layer | Purpose |
 |---|---|
 | **Skill** (`SKILL.md`) | Tells your AI agent when to inspect, plan, fetch docs, edit, validate, and attest |
@@ -59,7 +75,7 @@ Vise validates on three layers, and the layer is set by the *kind of claim* —
 
 | Layer | Claim | How | Enforcement |
 |---|---|---|---|
-| **SDK compliance** | "this is **wrong**" | 300 deterministic rules (session renewal, live-collection vs one-shot, no secret in logs, parent-child rendering, ban-state gating…) | **Hard gate** — `vise check` blocks until green or attested |
+| **SDK compliance** | "this is **wrong**" | 300 deterministic rules (session renewal, live-collection vs one-shot, no secret in logs, parent-child rendering, ban-state gating…) | **Hard gate** — `vise check` blocks until green or attested. A small advisory subset surfaces as informational only and never blocks. |
 | **Design conformance** | "this **looks off**" | extract the customer's design system into a contract, then check token usage | **Advisory** — `vise design check`/`preview`; never fails a build |
 | **Feature completeness** | "this is **missing**" | Vise proposes the full SDK feature surface per outcome; the agent opts out of anything out of scope with a recorded reason | **Advisory** — surfaced in `vise plan`/`check`; never fails a build |
 
@@ -67,7 +83,9 @@ Only correctness is gated (it can be made FP-free); conformance and completeness
 
 ### 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. All advisory.
+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.
+
+**For social.plus-specific styling:** `vise design init-tokens` scaffolds `src/styles/social-plus-tokens.css` in your project — a dedicated token file for social.plus features that you can edit independently from your main app's design system. Greenfield projects get sensible `--sp-*` defaults; brownfield projects get their existing token values seeded in. Edit the file, run `vise design extract --from-project` to refresh the contract, and future agent builds inherit the updated palette — no AI agent needed in the update loop.
 
 ### Supported integrations (outcomes)
 
@@ -81,8 +99,8 @@ A bench vise holds the workpiece steady so the craftsman's hands are free to sha
 
 ## Benchmark: Phase 1 Results
 
-> **Every feature delivered correctly — confirmed independently with two different AI coding tools.**  
-> With Vise, both agents built all 9 social features with no production gaps. Without Vise, 3 out of 9 features had hidden problems that would only surface after users complained.
+> **The compliance gaps agents ship on their own, they close under Vise's check loop.**  
+> Across two capable coding agents (Cursor / Composer 2.5 and Claude Sonnet 4.6), the features with *secondary* compliance requirements — Chat, Moderation, Push — failed without Vise and passed with it; both agents reached 9/9 with Vise. This is a **strong directional signal at N=1 per cell, not a settled statistical finding.** The [Commune paper](docs/commune-paper-2026-05-30.md) is the full, honest version — methodology, per-cell results, threats to validity, and a complementary bug-fix benchmark where Vise showed *no* advantage.
 
 ### What "delivered correctly" means
 
@@ -93,7 +111,7 @@ A bench vise holds the workpiece steady so the craftsman's hands are free to sha
 - **Moderation actions** (report, flag, block) are surfaced in the UI so users can act on them, not buried in a hook
 - **Chat and feed queries** use live, reactive subscriptions — not one-time fetches that go stale
 
-Without Vise, AI agents frequently implement the primary feature correctly but miss these secondary requirements. They know about them in the abstract — but when building a chat screen, "ban state" feels out of scope and gets skipped. `sp-check` turns that vague awareness into a specific, actionable finding.
+Without Vise, AI agents frequently implement the primary feature correctly but miss these secondary requirements. They know about them in the abstract — but when building a chat screen, "ban state" feels out of scope and gets skipped. `vise check` turns that vague awareness into a specific, actionable finding.
 
 ### The experiment: three conditions, nine features
 
@@ -106,7 +124,7 @@ SDK setup · User presence · Social feed · Events · Chat & DMs · Push notifi
 |---|---|---|
 | **Pure MCP** | Access to social.plus docs only — no compliance guidance | Baseline: how well does the agent do on its own? |
 | **Rules-as-Markdown** | The full 1,013-line compliance rulebook pasted directly into the prompt | Is the problem just that the agent doesn't know the rules? |
-| **Vise + Skill** | Full Vise CLI — `sp-check` runs automatically, agent reads specific findings, fixes them, repeats until green | Does an active feedback loop change the outcome? |
+| **Vise + Skill** | Full Vise CLI — `vise check` runs automatically, agent reads specific findings, fixes them, repeats until green | Does an active feedback loop change the outcome? |
 
 The Rules-as-Markdown condition is the key isolation: if the agent already knows all the rules, does giving it the spec document fix the problem? The answer turned out to be **no** — knowing the rules and being forced to act on specific findings are different things.
 
@@ -117,38 +135,28 @@ The Rules-as-Markdown condition is the key isolation: if the agent already knows
 | **Cursor (Composer 2.5)** | 6 out of 9 ✗ | 5 out of 9 ✗ | **9 out of 9 ✅** |
 | **Claude Code (Sonnet 4.6)** | 6 out of 9 ✗ | 7 out of 9 ✗ | **9 out of 9 ✅** |
 
-The three features that consistently fail without Vise — **Chat**, **Moderation**, and **Push Notifications** — are exactly the ones with secondary compliance requirements (ban-state, report affordances, Amity preference API). Vise's `sp-check` catches these with a specific finding; the rules doc does not.
-
-Both agents reached a perfect score with Vise. Neither could reach it with the compliance spec pasted into the prompt. All 9 passes were independently verified by code inspection — no scoring shortcuts.
+The three features that consistently fail without Vise — **Chat**, **Moderation**, and **Push Notifications** — are exactly the ones with secondary compliance requirements (ban-state, report affordances, Amity preference API). `vise check` catches these with a specific finding; the rules doc does not.
 
-### Efficiency — rework sessions needed
+Both agents reached 9/9 with Vise. The Rules-as-Markdown arm did **not** reliably beat the plain-docs control — 5/9 on Cursor (*below* control) and 7/9 on Sonnet — and at N=1 per cell neither gap is distinguishable from noise. The robust, reproducible signal is narrower and mechanistic: **Chat and Moderation never pass under either control arm, and always pass under Vise.** Passes were scored by a deterministic grader, not by hand — see [Reproducibility & honest caveats](#reproducibility--honest-caveats) for what that grader does and doesn't establish.
 
-Vise delivers all 9 features correctly in a single session. The other conditions leave failing features that require additional sessions to diagnose (the gap isn't visible without `sp-check`) and fix.
-
-| Coding agent (model) | Condition | Features correct | Rework sessions needed |
-|---|---|---|---|
-| **Cursor (Composer 2.5)** | Pure MCP | 6 / 9 ✗ | +3 or more |
-| **Cursor (Composer 2.5)** | Rules-as-Markdown | 5 / 9 ✗ | +4 or more |
-| **Cursor (Composer 2.5)** | **Vise + Skill** | **9 / 9 ✅** | **0 ✅** |
-| **Claude Code (Sonnet 4.6)** | Pure MCP | 6 / 9 ✗ | +3 or more |
-| **Claude Code (Sonnet 4.6)** | Rules-as-Markdown | 7 / 9 ✗ | +2 or more |
-| **Claude Code (Sonnet 4.6)** | **Vise + Skill** | **9 / 9 ✅** | **0 ✅** |
+### Why it matters
 
-<sub>Rework sessions are additional developer-initiated prompts needed after the initial session to diagnose and fix the failing features. Each failing feature typically requires at least one session to identify the gap and one to fix it — and that's without the benefit of `sp-check` pointing directly at the problem.</sub>
+A failing feature without Vise is *invisible* until a user hits it: the code compiles, the demo works, and the ban-state gap surfaces only when a banned user posts. Vise turns that latent gap into a specific finding the agent fixes before you ship. (We did not separately measure remediation effort, so this makes no rework-cost claim — only that the gaps are real and silent without a checker.)
 
-### Reproducibility
+### Reproducibility & honest caveats
 
-- **Gate-checked:** Every pass was verified by code inspection — the Vise workspaces contain an actual UI-level ban gate; the pure-MCP workspaces do not. Zero attestation shortcuts.
-- **Built from scratch** (greenfield seed) — not patching existing code.
-- **Three arms run with separate tooling.** The Rules-as-Markdown arm has no `sp-check` tool available — it cannot "cheat" by running the checker.
-- **N=1 per cell (Phase 1).** Each agent ran each scenario once. Repeatability seeds on the three most discriminating slices (CM-CHAT, CM-MODERATE, CM-PUSH) are pending. These results should be treated as a strong initial signal, not a statistically settled finding.
-- Full per-feature scorecards, agent transcripts, and workspace diffs: [`benchmarks/FINDINGS.html`](benchmarks/FINDINGS.html) · [`benchmarks/RULES_AS_MARKDOWN.html`](benchmarks/RULES_AS_MARKDOWN.html)
+- **Scoring is deterministic — and it overlaps with what Vise enforces.** Each cell is graded on four dimensions: `vise check --ci` (the same compliance ruleset), the project's own sensors (build / typecheck / lint), and hand-authored string-inclusion acceptance patterns. Because the metric overlaps Vise's own rules — and only the Vise arm iterates against that checker — read the headline as "Vise's checks pass," not as a fully independent oracle. The acceptance patterns are literal string matching (not AST), so they involve authoring judgment.
+- **Vise-arm passes were deterministic-pass**, not attestation exceptions — agents fixed the code. (The grader applies a narrow, *symmetric* auto-attestation for absence / type-stub findings across **all** arms including the controls; it cannot satisfy the acceptance patterns, so it does not tilt the result toward Vise.)
+- **Three arms, separate tooling.** The Rules-as-Markdown arm has no Vise checker available — it cannot run `vise check`.
+- **Built from scratch** (greenfield seed), capable models with prior SDK familiarity. A complementary **bug-fix** benchmark showed **no Vise advantage** — the loop helps on greenfield integration, not local bug hunts.
+- **N=1 per cell.** A strong directional signal (the Chat/Moderation/Push mechanism reproduces across both models), **not** a statistically settled finding; repeatability seeds are pending.
+- **Full methodology, per-cell analysis, and threats to validity:** [the Commune paper](docs/commune-paper-2026-05-30.md). The [`benchmarks/FINDINGS.html`](benchmarks/FINDINGS.html) and [`benchmarks/RULES_AS_MARKDOWN.html`](benchmarks/RULES_AS_MARKDOWN.html) files are **summary report tables**, not raw transcripts or workspace diffs.
 
 ### Which mode should I use?
 
 | If you… | Use | Why |
 |---|---|---|
-| Building new social features with an AI agent | **Vise CLI + Skill** | The only mode that reliably delivers all features correctly |
+| Building new social features with an AI agent | **Vise CLI + Skill** | The mode that closed every secondary-compliance gap in our benchmark |
 | Auditing existing social.plus code | `vise check --ci` | Grades any codebase against the full ruleset |
 | Enforcing compliance in a CI pipeline | `vise check --ci` | Exits non-zero on failures; structured JSON output for logs |
 
@@ -162,7 +170,7 @@ Vise delivers all 9 features correctly in a single session. The other conditions
 | **React Native** | ✅ Full | `tsc`, `npm lint`, SDK import smoke |
 | **Flutter / Dart** | ✅ Full | `flutter analyze`, `flutter test` |
 | **Android (Kotlin)** | ✅ Full | Gradle assemble, unit tests |
-| **iOS (Swift)** | ✅ Full | (static rule checks; runtime sensors WIP) |
+| **iOS (Swift)** | ✅ Full | Static rule checks fully operational. Build sensor not wired (`xcodebuild` environment requirements make it fragile) — `vise run-sensors` returns no-sensors for iOS; compliance rules run regardless. |
 
 Each platform has 52–54 rules across 10 compliance domains (feed, comments, moderation, chat, secrets, session & auth, notifications, live objects, logging hygiene, design tokens).
 
@@ -251,7 +259,7 @@ The flow above is what the skill teaches your AI agent. You — the human — dr
 | `vise design check [path]` | Advisory, **non-blocking** report on how closely the UI code matches the contract (token coverage + on/off-contract color literals). Never fails a build and is **not** a `vise check` gate |
 | `vise design preview [path] [--reference <prototype>]` | Write a self-contained `sp-vise/design-preview.html`: the contract's tokens as visual swatches + the conformance report + the HTML reference embedded for side-by-side review. Vise renders the artifact; a human/VLM judges the visual match. Dependency-free — **not** an automated pixel diff |
 | `vise design reference [path] [--title <name>]` | Write a self-contained `sp-vise/design-reference.html`: human/VLM-readable design-system spec — token swatches, type samples, component demos, and a growth-layer summary. Pairs with `design-contract.json` (machine-readable). Use `--title` to name the design system (e.g. `--title Streamly`). Advisory — **not** an enforcement gate |
-| `vise design init-tokens [path] [--force]` | Scaffold `src/styles/social-plus-tokens.css` — the dedicated, customer-editable token file for social.plus features. **Greenfield:** neutral defaults (full `--sp-*` token set). **Brownfield:** seeded from your existing concrete tokens. Idempotent — never overwrites an existing file (use `--force` to override). After editing, run `vise design extract --from-project` to refresh the contract. `design_init_tokens` |
+| `vise design init-tokens [path] [--force]` | Scaffold `src/styles/social-plus-tokens.css` — the dedicated, customer-editable token file for social.plus features. **Greenfield:** neutral defaults (full `--sp-*` token set). **Brownfield:** seeded from your existing concrete tokens. Idempotent — never overwrites an existing file (use `--force` to override). After editing, run `vise design extract --from-project` to refresh the contract |
 
 The extracted contract is **advisory input for generation**, not an enforcement gate: a token-poor prototype yields a weaker — never wrong — contract, and absence of a prototype simply means no contract (the existing `*.design.reuse-detected-tokens` rules still cover reuse of a host project's own design system).
 
@@ -279,7 +287,7 @@ The extracted contract is **advisory input for generation**, not an enforcement
 
 | Command | Purpose |
 |---|---|
-| `vise run-sensors [path]` | Run detected project commands (npm scripts, Gradle, Flutter, lint, typecheck, SDK import smokes); never executes arbitrary shell |
+| `vise run-sensors [path]` | Run detected project scripts/wrappers (npm scripts, Gradle, Flutter, lint, typecheck, SDK import smokes); inspect with `--dry-run` before running in an untrusted project |
 | `vise run-sensors [path] --dry-run` | List what would run without executing |
 
 ### Troubleshooting quick loop
@@ -335,7 +343,7 @@ MCP-capable hosts can call Vise as structured tool calls instead of shell comman
 
 ### Tool names (snake_case per MCP convention)
 
-`inspect_project`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`.
+`inspect_project`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `resolve_request`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `suggest_patch`, `design_extract`, `design_check`, `design_preview`, `design_reference`, `design_init_tokens`.
 
 These are the same operations as the CLI commands above, exposed as MCP tools.
 
@@ -388,6 +396,8 @@ After `vise init`, your project gets a `sp-vise/` directory. These files become
 | `sp-vise/compliance.json` | `vise init` | The rules selected for this integration, the Vise version, the ruleset digest, the target app surface, and an optional engagement link. |
 | `sp-vise/attestations/*.json` | `vise sync` (deterministic) or `vise attest` (host-agent / human) | Per-rule evidence: signer, confidence, rationale, cited files (with source fingerprints for drift detection). |
 | `sp-vise/inspection.json` | `vise init` | The platform, monorepo surface, and design-token signals detected at init time. |
+| `sp-vise/design-contract.json` | `vise design extract` | The extracted design contract: declared tokens, breakpoints, advisory components, source file digests (for freshness detection), and a stable digest over design facts. |
+| `sp-vise/design-reference.html` | `vise design reference` | Self-contained HTML design-system spec (token swatches, type samples, components). Human/VLM-readable; open in a browser alongside the app. |
 | `sp-vise/engagement.json` | `vise engagement init` (optional) | Contractual scope: tier, customer ID, contracted outcomes, reviewer assignment. |
 
 **Commit `sp-vise/` to your repo.** `vise check` re-validates against the recorded contract on every run, comparing current code against the recorded attestations. If code changes and breaks a rule, the next `check` reports `deterministic-fail`, `attestation-needed`, or `blocked` — never a silent regression.

package/dist/server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -41,6 +41,10 @@ const tools = new Map([
     designInitTokensTool,
 ].map((tool) => [tool.name, tool]));
 const bundledSkillName = "social-plus-vise";
+// Pre-rebrand `install-skill` runs created skill dirs/files under this name. We
+// supersede (remove) them on install so a host doesn't keep serving stale
+// foundry/spf guidance alongside the current skill.
+const legacySkillName = "social-plus-foundry";
 const cliResult = await handleCli(process.argv.slice(2));
 if (cliResult === "exit") {
     process.exitCode = process.exitCode ?? 0;
@@ -608,6 +612,7 @@ async function installSkill(args) {
     }
     const destination = skillInstallDestination(args);
     const force = hasFlag(args, "force");
+    const supersededLegacy = await removeLegacySkillDir(destination);
     const installedFiles = await copyDirectory(source, destination, force);
     return {
         status: installedFiles.length > 0 ? "installed" : "already-current",
@@ -616,13 +621,36 @@ async function installSkill(args) {
         destination,
         force,
         installedFiles,
+        supersededLegacy,
         nextStep: "Restart or reload the host AI coding tool so it discovers the installed skill.",
     };
 }
+// Supersede a pre-rebrand skill install: a prior `install-skill` under the old
+// package name created a sibling `<skillsRoot>/social-plus-foundry/` directory. Left
+// in place, the host keeps offering stale spf/foundry guidance next to the current
+// skill. Remove it on install — but only when it actually looks like a skill dir
+// (contains SKILL.md) and is not the directory we're installing into.
+async function removeLegacySkillDir(destination) {
+    const legacyDir = path.join(path.dirname(destination), legacySkillName);
+    if (legacyDir === destination) {
+        return [];
+    }
+    if (!(await fileExists(path.join(legacyDir, "SKILL.md")))) {
+        return [];
+    }
+    await rm(legacyDir, { recursive: true, force: true });
+    return [legacyDir];
+}
 async function installInstructionFile(target, args) {
     const force = hasFlag(args, "force");
     const source = path.join(skillSourceDir(), "SKILL.md");
     const content = await readFile(source, "utf8");
+    const legacyRule = path.join(path.dirname(target.destination), `${legacySkillName}.mdc`);
+    const supersededLegacy = [];
+    if (legacyRule !== target.destination && (await fileExists(legacyRule))) {
+        await rm(legacyRule, { force: true });
+        supersededLegacy.push(legacyRule);
+    }
     if (await fileExists(target.destination)) {
         const existing = await readFile(target.destination, "utf8");
         if (existing === content) {
@@ -634,6 +662,7 @@ async function installInstructionFile(target, args) {
                 destination: target.destination,
                 force,
                 installedFiles: [],
+                supersededLegacy,
                 nextStep: "Restart or reload the host AI coding tool so it discovers the updated project instructions.",
             };
         }
@@ -651,6 +680,7 @@ async function installInstructionFile(target, args) {
         destination: target.destination,
         force,
         installedFiles: [target.destination],
+        supersededLegacy,
         nextStep: "Restart or reload the host AI coding tool so it discovers the updated project instructions.",
     };
 }
@@ -891,7 +921,24 @@ function optionalNumberFlag(args, name) {
     return number;
 }
 function hasFlag(args, name) {
-    return args.includes(`--${name}`);
+    const exact = `--${name}`;
+    const equalsPrefix = `${exact}=`;
+    for (const arg of args) {
+        if (arg === exact) {
+            return true;
+        }
+        if (arg.startsWith(equalsPrefix)) {
+            const raw = arg.slice(equalsPrefix.length).trim().toLowerCase();
+            if (raw === "" || raw === "true" || raw === "1" || raw === "yes") {
+                return true;
+            }
+            if (raw === "false" || raw === "0" || raw === "no") {
+                return false;
+            }
+            throw new Error(`--${name} must be a boolean when provided with "=".`);
+        }
+    }
+    return false;
 }
 function keyValueFlag(args, name) {
     const pairs = flagValues(args, name);

package/dist/tools/ast.js

@@ -10,10 +10,46 @@
  * Scope: Single-file, single-step identifier resolution only.
  * No cross-file imports, no type inference, no function boundary traversal.
  */
-import Parser from "tree-sitter";
-import TypeScriptGrammars from "tree-sitter-typescript";
-import KotlinGrammar from "tree-sitter-kotlin";
-const { typescript: tsGrammar, tsx: tsxGrammar } = TypeScriptGrammars;
+import { createRequire } from "node:module";
+const nodeRequire = createRequire(import.meta.url);
+// Lazily and defensively load the tree-sitter native bindings. tree-sitter ships
+// prebuilt binaries for common platforms (darwin, linux-x64, win32-x64); on others
+// (linux-arm64, Alpine/musl, win32-arm64) the binding can fail to load when no C++
+// toolchain is present. AST is an ADDITIVE layer over the regex validators, so a
+// load failure must degrade to regex-only — NOT take down the entire CLI (including
+// doc-search/compliance commands that never touch a parser) at import time. Static
+// top-level imports would throw at module load and brick every command; this loader
+// confines the failure to the AST path. `undefined` = not yet attempted; `null` =
+// attempted and unavailable.
+let nativeBindings;
+function loadNativeBindings() {
+    if (nativeBindings !== undefined)
+        return nativeBindings;
+    try {
+        const ParserCtor = nodeRequire("tree-sitter");
+        const tsGrammars = nodeRequire("tree-sitter-typescript");
+        const kotlinGrammar = nodeRequire("tree-sitter-kotlin");
+        nativeBindings = {
+            Parser: ParserCtor,
+            tsGrammar: tsGrammars.typescript,
+            tsxGrammar: tsGrammars.tsx,
+            kotlinGrammar,
+        };
+    }
+    catch {
+        nativeBindings = null;
+    }
+    return nativeBindings;
+}
+/**
+ * Whether tree-sitter native bindings are available in this environment. When
+ * false, every AST helper degrades gracefully: parse() throws (so tryParse()
+ * returns null and stripComments() returns the source unchanged), and validators
+ * fall back to their regex paths.
+ */
+export function astAvailable() {
+    return loadNativeBindings() !== null;
+}
 /**
  * Strip comments from source code using tree-sitter AST.
  * Replaces comment spans with whitespace (preserving line structure).
@@ -56,13 +92,17 @@ const parsers = new Map();
 function getParser(language) {
     let parser = parsers.get(language);
     if (!parser) {
-        parser = new Parser();
+        const native = loadNativeBindings();
+        if (!native) {
+            throw new Error("tree-sitter native bindings unavailable; AST analysis disabled (regex fallback in effect)");
+        }
+        parser = new native.Parser();
         if (language === "tsx")
-            parser.setLanguage(tsxGrammar);
+            parser.setLanguage(native.tsxGrammar);
         else if (language === "kotlin")
-            parser.setLanguage(KotlinGrammar);
+            parser.setLanguage(native.kotlinGrammar);
         else
-            parser.setLanguage(tsGrammar);
+            parser.setLanguage(native.tsGrammar);
         parsers.set(language, parser);
     }
     return parser;

package/dist/tools/compliance.js

@@ -188,6 +188,7 @@ export async function initEngagement(args) {
         : undefined;
     const engagement = {
         schema_version: schemaVersion,
+        vise_version: packageVersion,
         foundry_version: packageVersion,
         engagement_id: randomUUID(),
         customer_id: args.customerId,
@@ -235,6 +236,7 @@ export async function initCompliance(repoPath, request, surfacePath) {
     const designContract = await readDesignContract(repoRoot);
     const compliance = {
         schema_version: schemaVersion,
+        vise_version: packageVersion,
         foundry_version: packageVersion,
         ruleset_digest: digestJson(refs), // hash of minimal refs (no title)
         generated_at: new Date().toISOString(),
@@ -688,6 +690,7 @@ function buildAttestation(compliance, rule, signer, confidence, identity, ration
         rule_version: rule.version,
         rule_digest: ref.rule_digest,
         ruleset_digest: compliance.ruleset_digest,
+        vise_version: packageVersion,
         foundry_version: packageVersion,
         status: signer === "spf-deterministic" ? "deterministic-pass" : "attested",
         signer_claim: {
@@ -974,7 +977,7 @@ function sidecarReadme(compliance) {
         "## Quick start",
         "",
         "1. Read `findings.json` — it contains a snapshot of rule status taken at init time, including any violations found in the current code.",
-        "2. Fix the issues listed in `findings.json`, then run `npm run sp-check` (or `vise check .` if vise is on PATH) to verify.",
+        "2. Fix the issues listed in `findings.json`, then run `vise check .` to verify.",
         "3. Run `vise sync .` to persist deterministic-pass evidence once rules are green.",
         "4. Run `vise attest . --rule <rule-id> ...` to sign off on intentional implementation decisions.",
         "",

package/dist/tools/design.js

@@ -1570,6 +1570,7 @@ export function buildDesignContract(sources, sourceMeta, extraDeclaredTokens = [
     const inferredCount = tokens.filter((token) => token.provenance === "inferred").length;
     const contract = {
         schema_version: DESIGN_CONTRACT_SCHEMA_VERSION,
+        vise_version: packageVersion,
         foundry_version: packageVersion,
         source: sourceMeta,
         digest: "",
@@ -2322,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/harness.js

@@ -210,7 +210,7 @@ function assessHarnessability(platforms, commandSensors, designSignalCount) {
     else {
         gaps.push("No platform signals detected; ask the user for the app framework or repository root.");
     }
-    if (platforms.some((platform) => ["typescript", "react-native", "android", "flutter"].includes(platform))) {
+    if (platforms.some((platform) => ["typescript", "react-native", "android", "flutter", "ios"].includes(platform))) {
         affordances.push("Detected a platform with deterministic setup checks available in Vise.");
     }
     if (commandSensors.length > 0) {
@@ -223,7 +223,7 @@ function assessHarnessability(platforms, commandSensors, designSignalCount) {
         affordances.push(`Detected ${designSignalCount} design/theme signal(s) for UI integration grounding.`);
     }
     if (platforms.includes("ios")) {
-        gaps.push("iOS support is guided until deterministic validators are expanded.");
+        gaps.push("iOS: static compliance rules are fully operational. No build/compile sensor is wired yet (xcodebuild environment requirements make it fragile); run-sensors will return no-sensors for iOS projects.");
     }
     if (platforms.length === 0) {
         return { level: "weak", affordances, gaps };

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/dist/tools/project.js

@@ -74,7 +74,7 @@ async function inspectRoot(root) {
     }
     // When react-native is detected alongside generic typescript signals, prefer react-native
     // so that platform-specific rules (react-native.*) are used for init/check/run-sensors.
-    // Same for android: an agent may create package.json (e.g. to enable npm run sp-check) which
+    // Same for android: an agent may create package.json (e.g. to enable a local Vise check script) which
     // would normally trigger typescript detection — suppress it so only android rules apply.
     const rawPlatforms = Array.from(new Set(signals.map((signal) => signal.platform)));
     const hasRN = rawPlatforms.includes("react-native");
@@ -1118,9 +1118,11 @@ function validateChat(root, platform, sourceContent) {
             }
         }
     }
-    // channel-target-resolved: check for hardcoded channelId/conversationId
+    // channel-target-resolved: check for hardcoded channelId/conversationId.
+    // Comment-stripped so a commented-out or documented channelId can't trip this
+    // no-escape (exit-2) gate.
     for (const filePath of chatFiles) {
-        const content = sourceContent.get(filePath) ?? "";
+        const content = commentStripped(filePath, platform, sourceContent.get(filePath) ?? "");
         const hardcodedChannel = /(?:channelId|conversationId|channel_id)\b[^=\n]*=\s*["'`][a-z0-9-]+["'`]/i.exec(content);
         if (hardcodedChannel) {
             findings.push(finding(`${platform}.chat.channel-target-resolved`, "error", "Chat code references a hardcoded channelId or conversationId.", relativeFile(root, filePath), "Resolve the channel from user selection, SDK query, or app routing — never hardcode."));
@@ -1504,7 +1506,7 @@ function validateLiteralGuardrails(root, platform, sourceContent) {
         /\btargetId\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
         /\bfeedId\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
         /\bchannelId\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
-    ]);
+    ], platform);
     if (feedTarget && !isAllowedPlaceholder(feedTarget.value)) {
         findings.push(finding(`${platform}.feed.target.literal`, "warning", `A hardcoded feed target literal was found: ${feedTarget.name}.`, relativeFile(root, feedTarget.file), "Do not invent or hardcode communityId, targetId, feedId, or channelId. Ask the user for the target or use an existing app-owned selection/create flow."));
     }
@@ -1531,7 +1533,7 @@ function validateLiteralGuardrails(root, platform, sourceContent) {
         /\bapi[-_]?key\b\s*[:=][\s\S]{0,200}?(?:process\.env\.[A-Z0-9_]+|import\.meta\.env\.[A-Z0-9_]+)\s*(?:\?\?|\|\|)\s*["'`]([^"'`]+)["'`]/i,
         // Ternary fallback: `apiKey = X ? 'literal' : ...` captures the truthy branch.
         /\bapi[-_]?key\b\s*[:=][\s\S]{0,200}?\?\s*["'`]([^"'`]+)["'`]\s*:/i,
-    ]);
+    ], platform);
     if (inlineApiKey && !isAllowedPlaceholder(inlineApiKey.value)) {
         findings.push(finding(`${platform}.secret.inline-api-key`, "warning", "A social.plus API key appears to be hardcoded in source.", relativeFile(root, inlineApiKey.file), "Use the host app's environment/config pattern instead of committing API keys directly into source files. The literal is still committed even when wrapped in an env-fallback (e.g. `defaultValue:`, `??`, `||`, ternary)."));
     }
@@ -1543,7 +1545,7 @@ function validateLiteralGuardrails(root, platform, sourceContent) {
         /\buser_id\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
         /\.login\s*\(\s*["'`]([^"'`]+)["'`]/i,
         /\.login\s*\(\s*userId\s*:\s*["'`]([^"'`]+)["'`]/i,
-    ]);
+    ], platform);
     if (literalUserId && !isAllowedPlaceholder(literalUserId.value)) {
         findings.push(finding(`${platform}.auth.no-literal-user-id`, "warning", `A hardcoded user identity literal was found: ${literalUserId.name}.`, relativeFile(root, literalUserId.file), "Do not hardcode a userId in source. Read the authenticated user from the host app's auth state (current session, route param, user-store hook, etc.)."));
     }
@@ -1682,8 +1684,9 @@ function validateLiteralGuardrails(root, platform, sourceContent) {
     }
     return findings;
 }
-function firstLiteralAssignment(contents, patterns) {
-    for (const [file, content] of contents) {
+function firstLiteralAssignment(contents, patterns, platform) {
+    for (const [file, rawContent] of contents) {
+        const content = commentStripped(file, platform, rawContent);
         for (const pattern of patterns) {
             pattern.lastIndex = 0;
             const match = pattern.exec(content);
@@ -2162,6 +2165,87 @@ function astLanguageForFile(filePath, platform) {
     }
     return undefined;
 }
+// Comment-aware view of a source file for the presence-of-a-bad-literal regex
+// checks that GATE (channel-target-resolved, inline secrets, literal userId/feed
+// target). A pattern that appears only in a commented-out or documentation line
+// must not trip a gate — a hard CI failure on a comment is the worst false positive
+// a compliance gate can produce. ts/tsx/kotlin use the precise tree-sitter stripper;
+// Swift/Dart (no grammar wired) use the conservative scanner below. Anything else is
+// returned unchanged.
+function commentStripped(filePath, platform, content) {
+    const astLang = astLanguageForFile(filePath, platform);
+    if (astLang)
+        return stripComments(astLang, content);
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".swift" || ext === ".dart")
+        return stripLineAndBlockComments(content);
+    return content;
+}
+// Conservative comment stripper for languages without a wired tree-sitter grammar
+// (Swift, Dart). Blanks `//` line comments and `/* */` block comments with spaces,
+// preserving newlines so offsets/line numbers are unchanged. It tracks single-line
+// string state ("…" and '…') with escape handling so a `//` inside a string or a URL
+// ("https://…") is not mistaken for a comment. Critically, it only ever blanks
+// comment spans — never code or string text — so any mis-classification degrades
+// toward a residual false-positive (a comment left un-stripped), never a silent
+// false-negative on a gate. Multi-line/raw strings are not modeled precisely, but the
+// same fail-toward-firing property holds (worst case: a comment is not stripped).
+function stripLineAndBlockComments(source) {
+    const out = source.split("");
+    let inString = null;
+    let inBlock = false;
+    let i = 0;
+    while (i < source.length) {
+        const c = source[i];
+        const next = source[i + 1];
+        if (inBlock) {
+            if (c === "*" && next === "/") {
+                out[i] = " ";
+                out[i + 1] = " ";
+                i += 2;
+                inBlock = false;
+                continue;
+            }
+            if (c !== "\n")
+                out[i] = " ";
+            i += 1;
+            continue;
+        }
+        if (inString) {
+            // Escape: skip the next char — but never jump past a newline, so a stray
+            // trailing backslash can't swallow the following line of real code.
+            if (c === "\\" && next !== "\n") {
+                i += 2;
+                continue;
+            }
+            if (c === inString || c === "\n")
+                inString = null;
+            i += 1;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            inString = c;
+            i += 1;
+            continue;
+        }
+        if (c === "/" && next === "/") {
+            for (let j = i; j < source.length && source[j] !== "\n"; j += 1)
+                out[j] = " ";
+            while (i < source.length && source[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            out[i] = " ";
+            out[i + 1] = " ";
+            i += 2;
+            inBlock = true;
+            continue;
+        }
+        i += 1;
+    }
+    return out.join("");
+}
 function validateCommentReferenceTypeEnum(root, platform, sourceContent) {
     const findings = [];
     // TypeScript/React Native: the SDK types referenceType as the string-literal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.12.5",
+  "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",