@amityco/social-plus-vise 0.12.4 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,72 @@ 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.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,6 +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 |
 
 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).
 
@@ -278,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
@@ -334,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.
 
@@ -387,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";
@@ -7,7 +7,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, initCompliance, initComplianceTool, initEngagement, initEngagementTool, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
-import { designCheckTool, designExtractTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
+import { designCheckTool, designExtractTool, designInitTokensTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
 import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
 import { planHarnessTool } from "./tools/harness.js";
 import { planIntegrationTool } from "./tools/integration.js";
@@ -38,8 +38,13 @@ const tools = new Map([
     designCheckTool,
     designPreviewTool,
     designReferenceTool,
+    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;
@@ -305,7 +310,15 @@ async function handleCli(args) {
                 });
                 return "exit";
             }
-            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", "preview", or "reference".`);
+            if (sub === "init-tokens") {
+                assertOnlyKnownFlags(subArgs, ["force"], "design init-tokens");
+                await printToolResult(designInitTokensTool, {
+                    repoPath: positionalRepoPath(subArgs),
+                    force: hasFlag(subArgs, "force"),
+                });
+                return "exit";
+            }
+            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", "preview", "reference", or "init-tokens".`);
             process.exitCode = 1;
             return "exit";
         }
@@ -515,6 +528,7 @@ Usage:
   vise design check [repoPath]
   vise design preview [repoPath] [--reference <prototypePath>]
   vise design reference [repoPath] [--title "Streamly"] [--no-write]
+  vise design init-tokens [repoPath] [--force]
 
 extract    Build a graded design contract and write it to sp-vise/design-contract.json.
            Declared CSS custom properties become exact tokens; repeated literal values
@@ -535,7 +549,12 @@ preview    Write a self-contained sp-vise/design-preview.html: the contract's to
 reference  Write a self-contained sp-vise/design-reference.html: human/VLM-readable
            design-system spec (token swatches, type samples, component demos, growth-layer
            summary). Pairs with the machine-readable design-contract.json. Use --title to
-           set the design system name. Advisory — not an enforcement gate.`;
+           set the design system name. Advisory — not an enforcement gate.
+init-tokens Scaffold src/styles/social-plus-tokens.css in the customer's project —
+           the dedicated editable token file for social.plus features. Greenfield:
+           neutral defaults. Brownfield (existing tokens found): seeded from their
+           concrete values. Idempotent (never overwrites); use --force to overwrite.
+           After editing, run vise design extract --from-project to refresh the contract.`;
     }
     return `${packageName}
 
@@ -593,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",
@@ -601,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) {
@@ -619,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.",
             };
         }
@@ -636,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.",
     };
 }
@@ -876,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

@@ -157,7 +157,16 @@ export async function extractDesignContractFromProject(repoPath) {
         }
     }
     inputs.sort();
-    return buildDesignContract({ css, html: [], inputs }, { kind: "host-project", inputs, file_count: inputs.length }, moduleTokens);
+    // Hash each source file so design check can detect staleness without re-extracting.
+    const input_digests = {};
+    for (const rel of inputs) {
+        try {
+            const content = await readFile(path.join(root, rel), "utf8");
+            input_digests[rel] = `sha256:${createHash("sha256").update(content).digest("hex")}`;
+        }
+        catch { /* file read already succeeded above; defensive only */ }
+    }
+    return buildDesignContract({ css, html: [], inputs }, { kind: "host-project", inputs, input_digests, file_count: inputs.length }, moduleTokens);
 }
 export async function writeDesignContract(repoPath, contract) {
     const sidecarDir = path.join(path.resolve(repoPath), "sp-vise");
@@ -381,6 +390,215 @@ function safeCss(value) {
     return value.replace(/[<>"]/g, "").slice(0, 200);
 }
 // ---------------------------------------------------------------------------
+// Social-plus token scaffold (vise design init-tokens)
+// ---------------------------------------------------------------------------
+//
+// Creates a dedicated `src/styles/social-plus-tokens.css` in the customer's
+// project — the single editable source for social.plus feature styling.
+// The contract always points at this file; customers edit it freely without
+// needing an AI agent. Design check detects changes and prompts re-extract.
+//
+// Two cases:
+//   Greenfield (no existing design system): scaffold Option-B neutral defaults.
+//   Brownfield (existing tokens found):     seed from their concrete values.
+//   Already exists: leave it untouched (idempotent — never clobbers edits).
+/** Relative path within the customer's project where sp tokens live. */
+export const SP_TOKENS_PATH = "src/styles/social-plus-tokens.css";
+/** Option-B neutral default — a clean, adaptive light-mode system using system
+ *  fonts. All token names use `--sp-` prefix to avoid collision with the
+ *  customer's own design system. Will be replaced with the official social.plus
+ *  palette (Option A) once that palette is finalised. */
+export const NEUTRAL_SP_TOKENS_DEFAULT = `/* social-plus-tokens.css — social.plus feature design system.
+ * This file controls the look of all social.plus features in your app.
+ * Edit freely. Run: vise design extract --from-project . to refresh the contract.
+ * NOTE: design check scans the whole project; the main-app palette appearing as
+ *       "off-contract" is expected and advisory only — not a failure. */
+:root {
+  /* ── Brand / interactive ───────────────────────────────── */
+  --sp-color-brand:           #1054DE;
+  --sp-color-brand-hover:     #0D47C5;
+  --sp-color-brand-subtle:    #EEF3FF;
+  --sp-color-brand-text:      #FFFFFF;
+
+  /* ── Backgrounds ───────────────────────────────────────── */
+  --sp-color-bg:              #FFFFFF;
+  --sp-color-surface:         #F8F9FA;
+  --sp-color-surface-raised:  #FFFFFF;
+  --sp-color-surface-hover:   #F0F2F4;
+  --sp-color-overlay:         rgba(0, 0, 0, 0.5);
+
+  /* ── Text ──────────────────────────────────────────────── */
+  --sp-color-text:            #0D1017;
+  --sp-color-text-muted:      #5C6370;
+  --sp-color-text-faint:      #9AA0AD;
+  --sp-color-text-disabled:   #C1C7CE;
+  --sp-color-text-on-brand:   #FFFFFF;
+
+  /* ── Semantic ──────────────────────────────────────────── */
+  --sp-color-success:         #1FAF64;
+  --sp-color-warning:         #F59E0B;
+  --sp-color-error:           #EF4444;
+  --sp-color-info:            #3B82F6;
+
+  /* ── Border ────────────────────────────────────────────── */
+  --sp-color-border:          #E5E7EB;
+  --sp-color-border-strong:   #D1D5DB;
+
+  /* ── Typography ────────────────────────────────────────── */
+  --sp-font-body:    system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+  --sp-font-display: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+  --sp-fs-xs:   12px;
+  --sp-fs-sm:   14px;
+  --sp-fs-md:   16px;
+  --sp-fs-lg:   20px;
+  --sp-fs-xl:   24px;
+  --sp-fs-2xl:  32px;
+  --sp-fw-regular: 400;
+  --sp-fw-medium:  500;
+  --sp-fw-bold:    700;
+  --sp-lh-tight:   1.2;
+  --sp-lh-normal:  1.5;
+  --sp-lh-relaxed: 1.7;
+  --sp-ls-tight:  -0.01em;
+  --sp-ls-wide:    0.04em;
+
+  /* ── Spacing ───────────────────────────────────────────── */
+  --sp-space-1:   4px;
+  --sp-space-2:   8px;
+  --sp-space-3:   12px;
+  --sp-space-4:   16px;
+  --sp-space-5:   24px;
+  --sp-space-6:   32px;
+  --sp-space-8:   48px;
+  --sp-space-10:  64px;
+
+  /* ── Radius ────────────────────────────────────────────── */
+  --sp-radius-sm:   6px;
+  --sp-radius-md:   10px;
+  --sp-radius-lg:   16px;
+  --sp-radius-xl:   24px;
+  --sp-radius-pill: 999px;
+
+  /* ── Border width ──────────────────────────────────────── */
+  --sp-border-width-thin:  1px;
+  --sp-border-width-base:  2px;
+  --sp-border-width-thick: 4px;
+
+  /* ── Elevation ─────────────────────────────────────────── */
+  --sp-shadow-1: 0 1px 3px rgba(0, 0, 0, 0.08);
+  --sp-shadow-2: 0 4px 16px rgba(0, 0, 0, 0.10);
+  --sp-shadow-3: 0 16px 40px rgba(0, 0, 0, 0.14);
+
+  /* ── Opacity ───────────────────────────────────────────── */
+  --sp-opacity-disabled: 0.4;
+  --sp-opacity-muted:    0.7;
+
+  /* ── Motion ────────────────────────────────────────────── */
+  --sp-duration-fast:  120ms;
+  --sp-duration-base:  200ms;
+  --sp-duration-slow:  400ms;
+  --sp-ease-standard:  cubic-bezier(0.4, 0, 0.2, 1);
+  --sp-ease-emphasized:cubic-bezier(0.2, 0, 0, 1);
+
+  /* ── Sizing ────────────────────────────────────────────── */
+  --sp-size-icon-sm: 16px;
+  --sp-size-icon-md: 24px;
+  --sp-size-icon-lg: 32px;
+  --sp-control-height-sm: 32px;
+  --sp-control-height-md: 40px;
+  --sp-control-height-lg: 48px;
+
+  /* ── Z-index ───────────────────────────────────────────── */
+  --sp-z-nav:      10;
+  --sp-z-dropdown: 100;
+  --sp-z-modal:    1000;
+  --sp-z-toast:    2000;
+
+  /* ── Breakpoints ───────────────────────────────────────── */
+  --sp-bp-sm: 640px;
+  --sp-bp-md: 768px;
+  --sp-bp-lg: 1024px;
+  --sp-bp-xl: 1280px;
+}
+`;
+export const designInitTokensTool = {
+    name: "design_init_tokens",
+    description: "Scaffold src/styles/social-plus-tokens.css in the customer's project — the dedicated, customer-editable token file for social.plus features. Greenfield: neutral defaults. Brownfield (existing tokens found): seed from their concrete values. Idempotent: never overwrites an existing file.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string", description: "Project root. Defaults to the current directory." },
+            force: { type: "boolean", description: "Overwrite existing social-plus-tokens.css (default false — never clobbers)." },
+        },
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = optionalStringField(args, "repoPath") ?? ".";
+        const force = args.force === true;
+        return textResult(await initSpTokens(repoPath, force));
+    },
+};
+export async function initSpTokens(repoPath, force = false) {
+    const root = path.resolve(repoPath);
+    const target = path.join(root, SP_TOKENS_PATH);
+    // Idempotent: don't overwrite unless forced.
+    try {
+        await stat(target);
+        if (!force) {
+            return {
+                status: "exists",
+                file: target,
+                message: `${SP_TOKENS_PATH} already exists — skipping. Use --force to overwrite.`,
+            };
+        }
+    }
+    catch { /* file doesn't exist — proceed to scaffold */ }
+    // Try brownfield seeding: extract concrete token values from the existing project.
+    const existingContract = await extractDesignContractFromProject(root);
+    const hasBrownfieldTokens = existingContract.tokens.length > 0;
+    let css;
+    let seededFrom;
+    if (hasBrownfieldTokens) {
+        // Seed from their existing concrete values, namespaced as --sp-*.
+        const lines = [
+            `/* social-plus-tokens.css — social.plus feature design system.`,
+            ` * Seeded from your existing design tokens on ${new Date().toISOString().slice(0, 10)}.`,
+            ` * Edit freely to customize social.plus features independently from your main app.`,
+            ` * Run: vise design extract --from-project . to refresh the contract. */`,
+            `:root {`,
+        ];
+        const categories = [...new Set(existingContract.tokens.map((t) => t.category))];
+        for (const cat of categories) {
+            const tokensInCat = existingContract.tokens.filter((t) => t.category === cat && t.name);
+            if (tokensInCat.length === 0)
+                continue;
+            lines.push(``, `  /* ── ${cat} ──────────────────────────────────────────── */`);
+            for (const t of tokensInCat) {
+                const spName = `--sp-${t.name.replace(/^--/, "")}`;
+                lines.push(`  ${spName}: ${t.value};   /* seeded from ${t.name} */`);
+            }
+        }
+        lines.push(`}`);
+        css = lines.join("\n") + "\n";
+        seededFrom = existingContract.source.inputs;
+    }
+    else {
+        // Greenfield: neutral Option-B defaults.
+        css = NEUTRAL_SP_TOKENS_DEFAULT;
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, css, "utf8");
+    return {
+        status: hasBrownfieldTokens ? "seeded" : "scaffolded",
+        file: target,
+        ...(seededFrom ? { seeded_from: seededFrom } : {}),
+        message: hasBrownfieldTokens
+            ? `Seeded ${SP_TOKENS_PATH} from your existing design tokens. Edit it to customize social.plus features, then run vise design extract --from-project .`
+            : `Scaffolded ${SP_TOKENS_PATH} with neutral defaults. Fill in your colors, then run vise design extract --from-project .`,
+    };
+}
+// ---------------------------------------------------------------------------
 // Design-system reference document (human/VLM-readable, advisory)
 // ---------------------------------------------------------------------------
 //
@@ -927,6 +1145,9 @@ export async function runDesignCheck(repoPath) {
             note: ADVISORY_NOTE,
         };
     }
+    // Freshness check: compare source file content hashes to those recorded at extract time.
+    // Advisory only — never blocks, just surfaces a nudge to re-extract.
+    const staleContract = await checkContractFreshness(repoRoot, contract);
     const files = (await collectFiles(repoRoot, MAX_SCAN_FILES)).filter((file) => SCAN_EXTS.has(path.extname(file).toLowerCase()));
     if (files.length === 0) {
         return { status: "no-sources", message: "No UI source files found to check against the contract.", contract: contractSummary(contract), note: ADVISORY_NOTE };
@@ -1018,9 +1239,35 @@ export async function runDesignCheck(repoPath) {
             count: undefinedRefs.length,
             sample: undefinedRefs.slice(0, OFF_CONTRACT_SAMPLE),
         },
+        ...(staleContract ? { staleContract } : {}),
         note: ADVISORY_NOTE,
     };
 }
+/** Compare source.inputs file content against hashes recorded at extract time.
+ *  Returns null if the contract is fresh or has no recorded digests. */
+async function checkContractFreshness(repoRoot, contract) {
+    const recorded = contract.source?.input_digests;
+    if (!recorded || Object.keys(recorded).length === 0)
+        return undefined;
+    const changed = [];
+    for (const [rel, storedDigest] of Object.entries(recorded)) {
+        try {
+            const content = await readFile(path.join(repoRoot, rel), "utf8");
+            const currentDigest = `sha256:${createHash("sha256").update(content).digest("hex")}`;
+            if (currentDigest !== storedDigest)
+                changed.push(rel);
+        }
+        catch {
+            changed.push(rel); // file deleted or unreadable — also stale
+        }
+    }
+    if (changed.length === 0)
+        return undefined;
+    return {
+        changedFiles: changed,
+        hint: `Run \`vise design extract --from-project\` to refresh the contract against the updated file(s).`,
+    };
+}
 function dedupeByToken(refs) {
     const seen = new Set();
     const out = [];
@@ -1323,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: "",

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/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.4",
+  "version": "0.13.0",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",