@amityco/social-plus-vise 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,80 @@ 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).
 
+## Unreleased
+
+No changes yet.
+
+## 1.4.0 — 2026-07-02
+
+**Entry-state flow + alignment gate.** `vise plan`/`init` now run a persona-free entry-state flow ahead of the build. A broad, multi-surface goal expands into a **blueprint** — the surfaces and experience to build — and for that journey `vise init` requires a human **blueprint sign-off** before it scaffolds anything: the *alignment gate* ("are we building the right thing?"), distinct from and complementary to the deterministic compliance gate ("did we build it the right way?"). The sign-off is a SELECT, not a rubber stamp — when the solution path is undecided it hard-picks `sdk` / `uikit` / `hybrid` first and surfaces candidate experiences, persists the choice, re-arms if the path/journey/design source changes, and cannot be bypassed. (A single-surface init is gated by intake/clarify, not the blueprint sign-off.)
+
+### Added
+- **Clarify-to-classify.** When a request is too vague to classify or names a capability the SDK doesn't support, `vise plan` returns a structured `clarify` block instead of silently scaffolding, and `vise init` blocks (exit 7) rather than guessing.
+- **Runtime-readiness consent + no-data gate.** The blueprint runtime-readiness packet now makes natural target discovery explicit, tells agents what to do when tenant data is absent (Console prep or safe SDK seed data before populated proof), and requires asking the user before expensive browser/simulator/emulator runtime proof. If proof or data setup is declined, agents must report the remaining runtime risks instead of claiming product proof.
+- **All-platform dogfood evidence packet.** Recorded the 2026-06-28 TypeScript, React Native, Android, Flutter, and iOS improvement loop with matrix results, runtime screenshots, validation commands, cleanup notes, and the explicit native caveat that RN/Flutter currently have starter launch proof but not archived completed-output proof.
+- **SDK field-shape correctness advisories (TS/JS).** Advisory detectors (`warning`, never gate `vise check`) that catch *wrong-shape* use of correctly-named SDK symbols — a reaction count read as an object off a `number`, a follow `status` compared to a value absent from the SDK enum — grounded in the extracted SDK type model. The wrong-field class an exact-name presence check can't see.
+- **Loading-state UX advisory (TS/JS).** Advisory detector that flags an SDK live-data binding rendered with no loading state nearby (the empty/blank-flash class), independent of the empty/error completeness baseline. Recognizes loaders by stem-matching the rendered component (skeleton/shimmer/spinner/progress families, library-agnostic) rather than an exact-name allowlist.
+- **First-class `livestream` surface** and curated **messaging / discussion / creator experience bundles** in the Engagement Intelligence catalog.
+- **`vise workplan trim`** — deliberately omit a companion surface on a multi-surface blueprint; requires a `--reason` and re-arms the blueprint sign-off (the trimmed blueprint must be re-signed before proceeding).
+
+### Changed
+- **Experience-calibration dogfood harness honors current governance.** The harness now accepts EI variants with grounded rationale/confidence, performs the multi-surface blueprint sign-off with a digest before `init`, and preserves the runtime-boundary checks for score/ranking/upload/customer-data behavior.
+- **ID-free target defaults.** Feed, follow, community, and chat intakes default to their ID-free / self / discovery sources rather than a hardcoded community or target id, so the agent never invents an id it wasn't given (advisory; gates unchanged).
+- **React Native dogfood starter launchability.** The RN native starter now uses `expo run:ios` / `expo run:android` for runtime proof and pins `react-native-screens` to the Expo SDK 53-compatible range that builds on the local iOS simulator.
+- **One design sign-off per journey.** On a multi-surface blueprint the per-surface design-preview confirmation is folded into the single blueprint sign-off — you approve the design once for the whole journey rather than per surface.
+
+---
+
+**File-scoped attestation** — closes a false-negative in the merge gate found while verifying the brownfield baseline (pf-053 follow-up). Previously `vise attest` greened a rule **globally**: a session could attest a rule once over a legacy violation and then ship NEW code violating the *same* rule undetected — and `vise check --new-only` could **not** catch it, because the attested rule was green before baseline subtraction ran. An attestation is now **scoped to the violator files present at attest time**; a live violation in any file the attestation never covered re-gates the rule (`attestation-needed` / `deterministic-fail`, naming the uncovered file).
+
+### Changed
+- **`vise check` re-gates new co-located violators of an attested rule.** For rules on the file-scopable allowlist, the attested green now covers only the reviewed files. This is intentionally stricter than before — a previously-masked new violation now gates. Rules **not** on the allowlist (project-aggregate rules such as `client.region`, whose finding points at a representative file rather than a located violation) keep the historical rule-global behavior, so this never false-gates. The allowlist (`FILE_SCOPABLE_SENSOR_SUFFIXES` in `compliance.ts`) covers **all 44** verified loop-file-scoped attestable per-file rules — the complete set of located-misuse detectors (e.g. `posts.status-filter-applied`, `feed.post-datatype-handled`, `live-collection.api-mismatch`, `comments.target-resolved`, `chat.sort-explicit`, `comments.query-has-limit`, `livestream.deprecated-stream`, `session-handler.retained`, `logging.no-secret-in-log`, the per-surface `*.live-collection` rules). Each entry is guarded by a test that fails if it stops resolving to a real attestable rule.
+- **~19 per-file sensors converted to enumerate every violator** (they previously stopped at the first via an outer-loop `break` / `return findings` / per-rule dedup), so a file-scoped attestation over one violator can't mask a co-located new violation of the same rule. Covers `feed.post-datatype-handled`, `comments.target-resolved`, `chat.channel-type-dm`, the deprecated-chat/livestream detectors, `community.avatar-from-sdk`, `feed.poll-answer-data-shape`, `comments.query-has-limit`, `chat.sort-explicit`, `profile.social-counts-from-sdk`, `community.display-name-from-sdk`, `feed.room-post-fetched`, `feed.ui-states-present`, `session-handler.retained`, `client.no-ssr-init`, `follow.status-subscription`, and the `logging.no-secret-in-log` / `logging.no-pii-in-log` line scanner. (Non-attestable deterministic-fail rules like `chat.channel-target-resolved` are unaffected — they can't be attested, so there is nothing to scope.)
+
+### Changed (cont.)
+- **Attest-while-clean bypass — closed.** A file-scopable rule is now **always** marked `file_scoped`, even when attested while its sensor is *not* firing. The covered set is then just the attester's evidence files (often empty), so a violation introduced **later** is uncovered and re-gates (`attestation-needed`), instead of being masked rule-globally by an unscoped attestation. Guarded by a mutation-verified CLI test: a clean attest with prose-only evidence (empty covered set) → a new violator re-gates under `--new-only`. Old (pre-marker) attestations remain grandfathered to rule-global, so `test:sidecar-compat` stays green.
+
+### Known residuals (disclosed)
+- **Non-`"."` surface paths** are believed correct (attest and check both resolve via `sourceRootForCompliance` / `resolveEvidenceSourcePath`, which coincide with `inspection.effectiveRoot` when the surface root is set) but are **not yet covered by a test** — all current tests use surface `"."`.
+
+### Added
+- **`attest` records `file_scoped: true` + `source_fingerprints` for the live-violator files** (tagged `live_sensor_violator`) when a file-scopable rule is attested; the CLI response echoes `file_scoped` and `scoped_files`. The check-time pf-068 contradiction disclosure is unchanged; this adds the *check-time* enforcement it could only warn about at attest time.
+
+### Compatibility
+- **Additive sidecar field.** Attestation files gain an optional `file_scoped` flag and `live_sensor_violator` `source_fingerprints`; old attestations lack the flag and keep rule-global behavior (the frozen 1.1.0 `test:sidecar-compat` baseline stays green). The rule corpus and contract digest are unchanged, so existing attestations are not invalidated. **Behavior note:** a file-scoped rule that was attested over a legacy violation will now re-gate if the *same* rule is violated in a new/uncovered file — re-attest (covering the new file) or fix it. A bare `vise check` and `--new-only` both honor the new scope.
+- **Re-run `vise baseline` after upgrading.** The converted sensors now emit one finding per violating file; for a rule with multiple violators in the SAME file, the single displayed `finding.file` can shift (first→last violator), which changes that rule's `rule@file` baseline key. A `baseline.json` recorded before this change may therefore not match the new key for such a rule, causing a pre-existing finding to re-gate under `--new-only`. The ruleset digest is unchanged so the staleness guard does not flag it — re-run `vise baseline` once after upgrading to refresh the keys.
+
+## 1.3.0 — 2026-06-19
+
+Discovery + readability surface, CLI/report honesty, and a batch of detector-precision fixes from two real-agent persona-dogfood sweeps (Sonnet 4.6), each fix mutation-verified and the whole batch adversarially reviewed. **No change to `vise check` exit codes, compliance rules, or sidecar *formats*** — the sidecar gains only **additive** fields (see Compatibility). The rule corpus is unchanged, so the contract digest is stable and no re-attestation is triggered.
+
+### Added
+- **`vise explore "<request>"`** — a pre-credentials, read-only discovery command. It maps a free-text request to a candidate feature/setup outcome (and lists the full menu when it can't, instead of dead-ending on `outcome:unknown`); each route carries the capabilities involved, the canonical docs, and the `vise plan` command to start. No project or API key required.
+- **`--format human`** on the read commands (`check` · `status` · `plan` · `doctor` · `explain` · `explore`). **JSON stays the default** — agents, CI, and sidecar-consuming flows parse stdout, so the default is unchanged; `--format human` is opt-in.
+- **`vise explain`** with no id now **enumerates the valid rule ids** (grouped by public id → contract ids) instead of erroring.
+- **`completeness` / selected-capability detail** is now surfaced by **`vise status`** and the init-time `findings.json` snapshot, mirroring `vise check`. Previously a `needs-attestation` / `deterministic-failures` headline (status precedence) hid a co-existing completeness-gap from anything reading those two surfaces.
+- **Brownfield baseline gate.** `vise baseline` (and `vise init --baseline`) snapshots the current pre-existing findings to `sp-vise/baseline.json`, and **`vise check --new-only`** (also `status --new-only`) gates only on findings introduced *since* the baseline — legacy findings are reported (`baselined: true`) but excluded. This makes `check` usable as a per-PR merge gate on an existing codebase. **Gate integrity:** subtraction is an explicit per-invocation flag, *never* the default — a bare `vise check` always gates on everything, so a green exit can never silently mean "no *new* gaps." A stale baseline (ruleset digest moved since it was recorded) is **not** applied (fail-safe: gate on everything and disclose `baseline.stale`). The artifact is additive — absent ⇒ unchanged behavior; the frozen sidecar-compat baseline is unaffected. Known v1 limitation, surfaced in the check output as `baseline.residual_caveat`: the rule+file key can mask a new violation of an already-baselined rule in the same file.
+
+### Changed
+- **Honesty of reports.** `attest` re-runs the deterministic sensor and **discloses** a live violation (without refusing — attestation is the override path); `check`/`status` carry an `evidence_basis_note` (plain-language "passed by absence" caveat); `vise status` propagates the body exit code to the process exit; `--ci` `blockingResultStatuses` enumerates every non-green status (incl. completeness-gap, selected-capability-failures); `explain` surfaces the feedforward/symptoms/inferential corpus fields; `doctor` surfaces the support channel.
+- **`vise debug`** correlates runtime-only symptom matches regardless of compliance status (a passing rule is framed as a runtime/out-of-sensor-reach signal, never a compliance failure), and maps `Cannot find module` / `MODULE_NOT_FOUND` for a **bare package** to a concrete `npm install` remediation — a failing correlated rule still wins the headline (the module hint rides as a secondary note).
+- **`vise init` intake validation.** Out-of-enum values (on closed-enum questions) and unrecognized `--answer` keys now produce advisory **warnings** instead of being silently accepted/dropped. Warnings only — never a rejection — so multi-select and free-form answers are unaffected.
+- **`engagement --scope`** accepts the full planner outcome vocabulary (derived from the classifier order), including `add-follow` / `add-community` / `add-notifications`, which were previously rejected.
+- **Classifier routing.** "community profile" → `add-community`, "user/member profile" (with a social qualifier) → `add-follow`, "notifications tray" → `add-notifications`; a non-social "company/performance/memory profile" stays `unknown`.
+- **`design check` coverage** splits `referenced_in_app` vs `seeded_only_tokens` — tokens that appear only in the Vise-scaffolded token file no longer inflate a false 100% (the raw `referenced` count is unchanged for back-compat).
+
+### Fixed
+- **Advisory routing precision** (advisory-only; no gate change): an explicit "build it with our own component" / "replace the UIKit surface" ask now routes SDK/custom-UI instead of Dynamic-UI; Console/theming phrasing corrected.
+- **Detector false positives.** `posts.status-filtered` no longer mis-attributes to `.d.ts` type stubs; `chat.send-error-handling` requires a real message *send* call (a read-only `markRead` view no longer fires); Android `comments.observer-cleanup` recognizes structured-concurrency cleanup (`stateIn(viewModelScope)` / `collectAsStateWithLifecycle` / `repeatOnLifecycle` / `DisposableEffect`), anchored to the observer's own chain; a negated "no custom code" no longer trips behavior-overrides; `scope-omit` reasons must be auditable (≥ 8 chars).
+- **`*.sdk.version.pinned` messages** now name each platform's real uncontrolled tokens (Android `+`/`:latest`, Flutter `any`, iOS moving branch / unspecified CocoaPods, TypeScript `latest`/`*`/`x` with `^`/`~` accepted). The rule **rationale is unchanged** (it is part of the contract digest; rewording it would force re-attestation — see the digest note in maintainer docs).
+- **`sdk-facts`**: the "names-only grounding" caveat now prints only when grounding is actually names-only; native platforms note that an empty `capabilities` list reflects TypeScript-first capability authoring, not lack of SDK support.
+- **Design contract** confirmation re-routes to `needs-confirmation` when the preview is absent; the design reference inlines only sanitized `:root` token declarations, never raw source.
+- Concrete CLI bugs from the first sweep (broken docs path, `engagement` show/init path mismatch, `workplan.json` persistence, and related discovery/intake edges).
+
+### Compatibility
+- **No exit-code or sidecar-*format* breaking changes.** The `completeness` / `selectedOptionalCapabilities` fields added to `vise status` / the init `findings.json` snapshot, and the new `sp-vise/baseline.json` artifact, are all **additive**; the `test:sidecar-compat` baseline (frozen 1.1.0 sidecar, no baseline.json) stays green. The rule corpus and contract digest are unchanged, so existing attestations are not invalidated. `vise check` with no flags is unchanged — the brownfield baseline only applies under the explicit `--new-only` flag.
+
 ## 1.2.0 — 2026-06-18
 
 Adds advisory **solution-path / UIKit routing** and a fail-closed fix to the SwiftPM manifest sensor. No change to `vise check` exit codes, compliance rules, or sidecar **formats**; the one behavior change is the SwiftPM-timeout outcome noted under Changed.
@@ -594,8 +668,7 @@ The design, completeness, and SDK-version layers are **advisory** — they infor
 - **agy + codex runners** (`run-agy-cells.sh`, `run-codex-cells.sh`) — production-quality scripts with TTY-detection fixes and workspace isolation.
 
 ### Findings & reports
-- `benchmarks/FINDINGS.html` — engineering-facing summary of the benchmark methodology, results, and what was/wasn't proven.
-- `benchmarks/MARKETING.html` — three-tier marketing-claim framework (safe / concrete / honest / aspirational) with supporting wallclock data and a list of metrics to instrument next.
+- Historical generated HTML reports captured the benchmark methodology, results, and marketing-claim framework for this round. They were later removed from source control during the 1.4.0 benchmark cleanup; retained summaries now live in Markdown result files.
 
 ### Honest claim
 On 9 new SDK domain implementations with codex gpt-5.4, vise+skill produced 7 working features vs 3 for pure MCP — same agent, same prompts. The cost: +28% wallclock per session. The net: −52% wallclock per *working* feature, because more features ship on the first try. Vise consistently catches five bug classes that capable models otherwise miss: wrong DM channel type, missing push register/unregister lifecycle, one-shot queries where live subscriptions are required, missing ban checks before write operations, and missing flag affordances on user-generated content.

package/README.md

@@ -77,7 +77,7 @@ vise install-skill --target copilot .     # GitHub Copilot / VS Code
 #    "Add a social feed to this app using the social.plus SDK."
 ```
 
-The skill drives the loop automatically — `vise inspect` → `vise plan` → `vise init` → edit code → `vise check` → `vise run-sensors`. You drive intent, answer scope questions, and approve the design preview; Vise keeps the agent honest. See [How it works](#how-it-works).
+The skill drives the loop automatically — `vise inspect` → `vise plan` → `vise init` → edit code → `vise check` → `vise run-sensors`. You drive intent, answer scope questions, and **sign off the blueprint** (what gets built) before the agent writes a line; Vise keeps the agent honest. For dogfood or release proof, also launch the app and capture runtime evidence; static checks do not replace seeing the surface run. See [How it works](#how-it-works).
 
 All skill targets:
 
@@ -98,11 +98,12 @@ Prefer a per-project install? `npm install -D @amityco/social-plus-vise`, then c
 ## How it works
 
 1. **Inspect** — `vise inspect` detects the platform, app surfaces, available sensors, and design signals from the local repo.
-2. **Plan** — `vise plan --request "..."` classifies the outcome, cites docs, and raises blocking intake and design-preview questions. Use `--summary` when you only need the route/intake readout before implementation. The agent surfaces questions; you answer.
-3. **Initialize** — `vise init` writes the `sp-vise/` compliance contract. While blocking questions are unanswered it refuses, returns `status: "needs-clarification"`, and exits 7 — the agent must ask instead of guessing.
+2. **Plan** — `vise plan --request "..."` classifies the outcome, cites docs, and raises blocking intake and design-preview questions. If the request is too vague to classify or names a capability the SDK doesn't support, it returns a structured **clarify** block instead of guessing; for a broad goal it expands the outcome into a **blueprint** — the surfaces and experience it proposes to build. Use `--summary` when you only need the route/intake readout before implementation. The agent surfaces questions; you answer.
+3. **Initialize** — `vise init` writes the `sp-vise/` compliance contract. For a **multi-surface build** (a journey spanning more than one surface), it first makes you **sign off the blueprint**: the *what* — the solution path (`sdk` / `uikit` / `hybrid`) and the experience/surfaces to build. This is the **alignment gate** — *"are we building the right thing?"* — the human-judgment counterpart to the deterministic compliance gate (*"did we build it the right way?"*) in step 5. `init` refuses and exits 7 until the request is resolved: `status: "needs-clarification"` when intake is unanswered or the request can't be classified, and `status: "needs-blueprint-confirmation"` until the blueprint is signed (`--answer blueprint_confirmation=<digest>`). The sign-off can't be bypassed, and it re-arms if the path, journey, or design source later changes.
 4. **Build** — the agent edits your code, grounded by `vise search-docs` and `vise get-doc-page`.
 5. **Check & repair** — `vise check` reports deterministic findings, completeness gaps, and attestation needs. The agent fixes findings or records attestations with evidence, looping until green.
 6. **Sense** — `vise run-sensors` runs your project's own typecheck/build/lint/SDK smokes. Done means the contract and evidence are committed, not just that the agent stopped.
+7. **Prove runtime readiness** — for dogfood, release, or any user-visible handoff, ask before spending browser/simulator/emulator/device resources. If approved, boot the actual target, capture screenshots/logs, and record what data was discovered or created at runtime. Discover targets naturally from host app state, SDK queries, user selection, or SDK create-flow return values; if the tenant has no data, ask whether to prepare Console data or seed safe dogfood data before claiming populated proof. When a `sp-vise/smoke.json` contract exists, run `vise smoke` against captured logs; `expect: "populated"` requires `loaded count=N` with `N > 0`. If runtime proof is declined or a completed native output cannot be archived, say so explicitly; starter launch proof is useful, but it is not proof that the completed social.plus surface ran.
 
 ### Solution path & UIKit routing (advisory)
 
@@ -122,17 +123,19 @@ The layer is set by the *kind of claim*, which is how Vise is designed to avoid
 
 Correctness is gated by deterministic rules or attestations; completeness is gated by explicit scope decisions; conformance stays advisory because "matches the brand" is legitimately subjective. Each gating rule is itself mutation-verified — its fix is reverted to confirm the check actually fails without it, so a rule that can't fail is removed rather than shipped as theater. `vise explain <ruleId>` prints any rule's rationale, evidence requirements, and remediation.
 
+Runtime proof is a separate evidence layer. `vise check` and `vise run-sensors` can prove structure, completeness, and local build commands, but they cannot prove that the selected community/feed/chat route renders on a cold launch. Ask before running browser or native runtime proof because it can consume local resources and agent tokens. If the user declines, state the expected limitation: cold-launch session races, empty tenant data, route wiring, permissions, and native packaging remain unproven. Use `vise smoke` where the app declares a runtime-smoke contract.
+
 **Supported outcomes:** feed · comments · chat · moderation · community · social graph (follow) · in-app notifications · plus setup (SDK, push, live data). `vise plan`/`init` classify the request and tailor the plan, rules, and feature checklist.
 
 ### Engagement Intelligence
 
-**Advisory, in preview.** The three layers above answer *whether you built it right*. Ahead of the build, Vise can also help reason about *what to build*: an **Engagement Intelligence** layer turns a product goal into multiple candidate **engagement strategies** — archetypes, UX patterns, and solution variants drawn from a social.plus experience catalog — with rationale, tradeoffs, no-fit guidance, availability boundaries, and review gaps. The human or driving agent still chooses the direction, then Vise compiles that selected variant into an implementation plan (`vise creative` → `vise creative accept` → `vise experience compile`), optionally bridging to installable social.plus blocks, plus advisory UX expectations and a multi-dimension experience review.
+**Advisory, in preview.** The three layers above answer *whether you built it right*. Ahead of the build, Vise can also help reason about *what to build*: an **Engagement Intelligence** layer turns a product goal into multiple candidate **engagement strategies** — archetypes, UX patterns, and solution variants drawn from a social.plus experience catalog — with rationale, tradeoffs, no-fit guidance, availability boundaries, and review gaps. The driving agent presents the EI choice as a visible decision — recommended experience, concrete fit signals, credible alternatives, tradeoffs, expected blueprint surfaces, and no-fit option — before it accepts a variant. The human or driving agent still chooses the direction, then Vise compiles that selected variant into an implementation plan (`vise creative` → `vise creative accept` → `vise experience compile`), optionally bridging to installable social.plus blocks, plus advisory UX expectations and a multi-dimension experience review.
 
 It is **local-only, never uploads, carries no calibrated score**, and **never changes `vise check`'s exit codes**. The opt-in ranking preview is review context, not a top-1 confidence claim or autonomous product-strategy selector. Use it to shape the work; the validation layers still decide when it's done.
 
 ### Design contracts
 
-Vise can ingest your aesthetic from an HTML/CSS prototype (`vise design extract`) or from the host app's own design system across web, Android, Flutter, and iOS (`vise design extract --from-project`). The contract is **advisory input for generation**, never an enforcement gate, and it feeds forward into plans only after you confirm the generated preview with `--answer design_contract_confirmation=yes`. For social.plus-specific styling, `vise design init-tokens` scaffolds a dedicated, customer-editable token file (`src/styles/social-plus-tokens.css`) — edit it, re-extract, and future builds inherit the palette with no agent in the loop.
+Vise can ingest your aesthetic from an HTML/CSS prototype (`vise design extract`) or from the host app's own design system across web, Android, Flutter, and iOS (`vise design extract --from-project`). The contract is **advisory input for generation**, never an enforcement gate, and it feeds forward into plans only after you confirm the generated preview with `--answer design_contract_confirmation=yes` — and on a multi-surface blueprint that confirmation is folded into the single blueprint sign-off, so you approve the design once for the whole journey rather than per surface. For social.plus-specific styling, `vise design init-tokens` scaffolds a dedicated, customer-editable token file (`src/styles/social-plus-tokens.css`) — edit it, re-extract, and future builds inherit the palette with no agent in the loop.
 
 ## Evidence
 
@@ -169,12 +172,13 @@ Each platform has dozens of rules across 10 compliance domains (feed, comments,
 
 ## CLI Reference
 
-Run `vise <command> --help` for full flags. JSON output is the default for agent-facing commands.
+Run `vise <command> --help` for full flags. JSON output is the default for agent-facing commands; the read commands (`check`, `status`, `plan`, `doctor`, `explain`, `explore`) also accept `--format human` for a readable summary.
 
 ### Inspect, plan, initialize
 
 | Command | Purpose |
 |---|---|
+| `vise explore "<request>"` | Pre-credentials discovery: map a request to what social.plus offers (candidate outcome, capabilities, docs, next command). No project or API key needed |
 | `vise doctor` | Verify install; print version, install path, docs source |
 | `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
 | `vise plan [path] --request "..." [--summary]` | Grounded implementation plan with intake questions and docs citations; `--summary` prints a compact route/intake view |
@@ -184,13 +188,14 @@ Run `vise <command> --help` for full flags. JSON output is the default for agent
 | `vise workplan next [path] --request "..."` | For broad social requests: print the next uncompleted surface and its focused commands |
 | `vise workplan status [path] --request "..."` | Show the workplan sequence and completed surfaces |
 | `vise workplan complete [path] --request "..." --surface <id>` | Record a green-checked surface; snapshots evidence under `sp-vise/workplan-snapshots/<surface>/` |
+| `vise workplan trim [path] --request "..." --surface <id> --reason "..."` | Deliberately omit a companion surface (surface-level scope-omit). `--reason` required; re-arms the blueprint sign-off gate (re-sign the trimmed blueprint before proceeding) |
 
 ### Creative pre-planning (advisory)
 
 | Command | Purpose |
 |---|---|
 | `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview]` | Write an advisory Engagement Intelligence brief with multiple candidate solution variants, rationale, tradeoffs, and review gaps; `--ranking-preview` adds opt-in, local-only review context that never reorders the default candidates |
-| `vise creative accept [path] --variant <id>` | Record the selected variant so `plan`/`init`/`workplan` carry it forward; `--variant none --rationale "..."` records a catalog-gap signal instead |
+| `vise creative accept [path] --variant <id> --rationale "..." --confidence high\|medium\|low` | Record the grounded selected variant so `plan`/`init`/`workplan` carry it forward; `--variant none --rationale "..." --confidence high\|medium\|low` records a catalog-gap signal instead |
 | `vise ux-harness [path]` | Generate advisory UX expectations from the accepted selection |
 | `vise experience compile [path]` | Compile the accepted variant into an implementation artifact plan |
 | `vise experience sensors [path]` | Write an advisory multi-dimension sensor framework (no calibrated score) |
@@ -206,7 +211,8 @@ Everything in this group is local and advisory: no uploads, no `vise check` exit
 |---|---|
 | `vise design extract <prototypePath> [--repo .] [--no-write]` | Extract a graded design contract + visual preview from an HTML/CSS prototype |
 | `vise design extract --from-project [path] [--no-write]` | Derive the contract from the project's own design system: CSS custom properties (incl. shadcn/Tailwind v4 `@theme`), TS/JS token modules, Android `colors.xml`/`dimens.xml`, Flutter `Color(0x…)`, iOS `.colorset`/Swift colors |
-| `vise design check [path]` | Advisory token-conformance report; never fails a build |
+| `vise design check [path]` | Advisory token-conformance report (incl. computed WCAG for the brand palette's role pairs when a profile exists); never fails a build |
+| `vise design contrast <foreground> <background>` | Compute the WCAG 2.x contrast ratio between two colours (advisory) — check any text/icon colour that isn't a palette role instead of eyeballing it |
 | `vise design preview [path] [--reference <prototype>]` | Write a self-contained visual review (`sp-vise/design-preview.html`) for human/VLM judgment |
 | `vise design reference [path] [--title <name>]` | Write a self-contained design-system spec: swatches, type samples, component demos |
 | `vise design init-tokens [path] [--force]` | Scaffold `src/styles/social-plus-tokens.css` (greenfield defaults or seeded from existing tokens); idempotent |
@@ -225,6 +231,8 @@ Everything in this group is local and advisory: no uploads, no `vise check` exit
 |---|---|
 | `vise check [path]` | Re-validate against the recorded contract: `green`, `needs-attestation`, `deterministic-failures`, `blocked`, or `contract-drift` |
 | `vise check [path] --ci` | Read-only variant that exits non-zero unless green (for CI) |
+| `vise check [path] --new-only` | **Brownfield gate.** With a recorded baseline, gate only on findings introduced *since* the baseline (pre-existing ones are reported but excluded). Default `check` always gates on everything |
+| `vise baseline [path]` | Snapshot the current pre-existing findings to `sp-vise/baseline.json` so `check --new-only` can separate legacy debt from new gaps. `vise init --baseline` records it at init time |
 | `vise validate [path]` | Run the deterministic validators only (no attestation comparison) |
 | `vise sync [path]` | Persist deterministic-pass evidence to `sp-vise/attestations/` |
 | `vise attest [path] --rule <id> --signer host-agent --confidence high --evidence-file evidence.json --rationale "..."` | Record an attestation when a rule passes through architecture the deterministic check can't see |
@@ -236,6 +244,7 @@ Everything in this group is local and advisory: no uploads, no `vise check` exit
 | Command | Purpose |
 |---|---|
 | `vise run-sensors [path] [--dry-run]` | Run detected project scripts (npm, Gradle, Flutter, lint, typecheck, SDK smokes); `--dry-run` lists without executing |
+| `vise smoke [path] --log <file>` | Assess a captured runtime mount-smoke log into a pass/fail verdict + record evidence. `expect: "populated"` requires `loaded count=N` with `N > 0`; this catches the session-establish and empty-data gaps `vise check` can't see (see [docs/RUNTIME_SMOKE.md](docs/RUNTIME_SMOKE.md)) |
 | `vise install-skill --target <host>` | Install the bundled skill into a coding host (see [Quick Start](#quick-start)) |
 | `vise print-skill` | Print the skill markdown to stdout |
 | `vise engagement init [path] [--tier ...] [--customer-id ...] [--scope ...]` | Record optional contractual scope metadata |
@@ -257,7 +266,7 @@ MCP-capable hosts can call Vise as structured tool calls instead of shell comman
 }
 ```
 
-Tool names (snake_case per MCP convention): `inspect_project`, `creative_brief`, `creative_accept`, `ux_harness`, `compile_experience`, `experience_sensors`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `experience_report`, `record_learning`, `show_learning`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `design_extract`, `design_check`, `design_preview`, `design_reference`, `design_init_tokens`.
+Tool names (snake_case per MCP convention): `inspect_project`, `creative_brief`, `creative_accept`, `ux_harness`, `compile_experience`, `experience_sensors`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `experience_report`, `record_learning`, `show_learning`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `design_extract`, `design_check`, `design_contrast`, `design_preview`, `design_reference`, `design_init_tokens`.
 
 These mirror the CLI commands above. The adapter still answers the legacy `resolve_request` and `suggest_patch` names, but they are deprecated in favour of `plan_integration` plus host-tool edits.
 
@@ -310,15 +319,19 @@ Vise writes local planning, compliance, design, and evidence artifacts under `sp
 | `sp-vise/creative-brief.json` + `creative-brief.md` | `vise creative` | Advisory brief: goals, archetypes, candidate variants (JSON + human-readable) |
 | `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local ranking preview for review context; `experience_score: null`, no uploads, no default-order change, no top-1 confidence claim |
 | `sp-vise/creative-selection.json` | `vise creative accept` | Accepted variant and plan/workplan feed-forward context |
-| `sp-vise/catalog-gap.json` | `vise creative accept --variant none` | Local-only no-fit signal for human catalog review |
+| `sp-vise/catalog-gap.json` | `vise creative accept --variant none --rationale "..." --confidence high\|medium\|low` | Local-only no-fit signal for human catalog review |
 | `sp-vise/ux-harness.json` | `vise creative accept` or `vise ux-harness` | Advisory UX pattern expectations and anti-patterns |
 | `sp-vise/experience-compiler.json` | `vise experience compile` | Advisory implementation plan: install guidance, surfaces, validation commands |
 | `sp-vise/experience-sensors.json` | `vise experience sensors` | Advisory sensor framework; `score: null` until calibrated |
 | `sp-vise/experience-report.json` | `vise experience-report` | Advisory dimensioned review; `score: null` until calibrated |
 | `sp-vise/learning-events.jsonl` | `vise learning record` | Append-only, local-only learning event log |
 | `sp-vise/learning-summary.json` | `vise learning record` | Derived summary; `recommendationOptimization.status: "not-active"` |
+| `sp-vise/flow.json` | `vise workplan next` / `trim` | Entry-state, selected solution path, active blueprint digest, sign-off state, and omitted companion surfaces |
+| `sp-vise/flow-blueprint.html` | `vise workplan next` | Human-readable blueprint preview for the alignment gate; review before passing `blueprint_confirmation=<digest>` |
 | `sp-vise/workplan.json` | `vise workplan complete` | Broad-request progress: completed surfaces, green-check evidence |
 | `sp-vise/workplan-snapshots/<surface>/` | `vise workplan complete` | Per-surface snapshots so later focused surfaces don't erase earlier proof |
+| `sp-vise/smoke.json` | project/runtime harness | Declared runtime-smoke surfaces and expected resolution states |
+| `sp-vise/evidence/runtime-smoke.json` | `vise smoke` | Captured runtime-smoke verdicts used by evidence-citing runtime rules |
 | `sp-vise/design-contract.json` | `vise design extract` | Extracted tokens, breakpoints, source digests, stable design digest |
 | `sp-vise/design-preview.html` | `vise design extract` / `preview` | Self-contained visual review; open before answering `design_contract_confirmation` |
 | `sp-vise/design-reference.html` | `vise design reference` | Self-contained design-system spec (swatches, type, components) |

package/dist/capabilities.js

@@ -96,6 +96,17 @@ export const CAPABILITIES = [
         symbols: [/AmityRoomRepository/i, /\bcreateRoom\b/, /createRoomAndStartStreaming/i, /getBroadcastData/i, /createLiveStreamPost/i, /\bgoLive\b/i, /startPublish/i],
         hint: "live rooms/broadcasting via AmityRoomRepository (createRoom, go-live, live-viewing); post the stream with createLiveStreamPost (distinct from rendering a livestream post in the feed)",
     },
+    {
+        id: "comment-preview",
+        label: "Comment preview on posts",
+        outcomes: ["add-feed"],
+        symbols: [
+            /\bgetComments\b/, /\bqueryComments\b/, /CommentRepository/i, /AmityCommentQueryBuilder/,
+            /\bgetCommentCount\b/, /\bgetLocalCommentCount\b/, /\bgetLatestComments\b/,
+            /\bcomments?Count\b/, /\blocalCommentCount\b/, /\blatestComments?(?:Ids?)?\b/,
+        ],
+        hint: "Present a comment preview on each post: the comment count + a top-comment snippet + a tap-through to the thread. Read it off the post (commentsCount / latestComments) or query via getComments / CommentRepository. (The full thread + composer is the deeper add-comments work.) A genuinely comment-less feed (broadcast / announcement / a profile post-grid) opts out: `// vise: scope-omit comment-preview — <reason>`.",
+    },
     {
         id: "comments",
         label: "Comment thread (list + composer)",
@@ -504,6 +515,23 @@ export const SHARED_PRODUCT_EXPECTATIONS = [
         deterministicPlatforms: ["android", "flutter", "ios", "typescript"],
         hint: "source unread badges from the SDK stream instead of counting stale local arrays",
     },
+    {
+        id: "feed.post-body-rendering",
+        label: "Post body rendering",
+        outcomes: ["add-feed"],
+        kind: "shared-expectation",
+        availability: [
+            {
+                label: "SDK text post/body accessors",
+                symbols: [
+                    /\b(?:text|description|caption)\b/i,
+                    /\b(?:getData|getText|AmityTextPost|AmityPostData)\b/i,
+                ],
+            },
+        ],
+        deterministicPlatforms: ["android", "flutter", "ios", "typescript"],
+        hint: "render the post body/description/caption when present; a title field is optional and postId should not be the primary card content",
+    },
     {
         id: "feed.rich-post-rendering",
         label: "Rich post rendering",
@@ -1144,7 +1172,7 @@ function symbolHaystack(symbols) {
 }
 const ADVISORY_NOTE = "Build each missing capability, or opt out with a recorded reason: `// vise: scope-omit <id> — <reason>`. A scope-omit marker without a reason is invalid and still counts as missing. Missing capabilities that are neither built nor validly opted-out cause `vise check` to exit with status `completeness-gap` (exit code 5).";
 export const BASELINE_CAPABILITY_IDS_BY_OUTCOME = {
-    "add-feed": ["pagination"],
+    "add-feed": ["pagination", "comment-preview"],
     "add-comments": ["comment-composer"],
     "add-chat": ["send-message", "read-state"],
     "add-follow": ["followers-following"],
@@ -1256,6 +1284,7 @@ export function assessSelectedOptionalCapabilities(source, outcome, selectedIds
         note: "Selected optional capabilities are enforced only after the user or host agent opts in through `feed_optional_capabilities`. They are source sensors, not baseline compliance rules.",
     };
 }
+const MIN_SCOPE_OMIT_REASON_CHARS = 8;
 export function assessCompleteness(source, outcome) {
     const caps = baselineCapabilities(outcome);
     const optOuts = new Map();
@@ -1265,12 +1294,14 @@ export function assessCompleteness(source, outcome) {
     while ((match = omitPattern.exec(source)) !== null) {
         const id = match[1].toLowerCase();
         const reason = (match[2] ?? "").trim();
-        if (reason) {
+        if (reason.length >= MIN_SCOPE_OMIT_REASON_CHARS) {
             optOuts.set(id, reason);
             invalidOptOuts.delete(id);
         }
         else if (!optOuts.has(id)) {
-            invalidOptOuts.set(id, "scope-omit marker must include a reason");
+            invalidOptOuts.set(id, reason.length === 0
+                ? "scope-omit marker must include a reason"
+                : `scope-omit reason is too short ("${reason}") — give an auditable reason of at least ${MIN_SCOPE_OMIT_REASON_CHARS} characters`);
         }
     }
     const present = [];
@@ -1292,7 +1323,7 @@ export function assessCompleteness(source, outcome) {
             missing.push({
                 id: cap.id,
                 label: cap.label,
-                hint: invalidReason ? `${cap.hint}; found scope-omit marker without a reason, so add a reason or implement it` : cap.hint,
+                hint: invalidReason ? `${cap.hint}; ${invalidReason}` : cap.hint,
             });
         }
     }

package/dist/entryState.js

@@ -0,0 +1,71 @@
+export const ENTRY_STATE_ADVISORY = "This is an advisory entry-state classification. It does not change outcome classification, compliance rules, the sidecar schema, or `vise check` exit codes.";
+export function classifyPathDecidedness(input) {
+    const { solutionPath, hasExplicitPathAnswer } = input;
+    const rec = solutionPath.recommendation;
+    if (hasExplicitPathAnswer) {
+        if (rec === "uikit")
+            return "uikit";
+        if (rec === "hybrid")
+            return "hybrid";
+        return "sdk";
+    }
+    if (rec === "hybrid")
+        return "hybrid";
+    if (rec === "needs-decision")
+        return "conflict";
+    if (rec === "uikit")
+        return solutionPath.signals.uikit.length > 0 ? "uikit" : "undecided";
+    return solutionPath.signals.sdk.length > 0 ? "sdk" : "undecided";
+}
+export function classifyFeatureCompleteness(input) {
+    const { outcome, broadSocialRequest, multiSurface, creativeSelected } = input;
+    if (creativeSelected)
+        return "has-feature-ref";
+    if (outcome !== "unknown" && !broadSocialRequest)
+        return "has-feature-ref";
+    if (broadSocialRequest || multiSurface)
+        return "goal-only-broad";
+    return "exploring";
+}
+export function classifyDesignCompleteness(input) {
+    if (!input.mentionsDesign)
+        return "none";
+    return input.designSignalCount > 0 ? "has-design-ref" : "mentions-no-ref";
+}
+export function entryStageFor(d) {
+    if (d.feature === "exploring")
+        return "explore";
+    if (d.path === "undecided" || d.path === "conflict")
+        return "decide-path";
+    if (d.feature === "goal-only-broad")
+        return "clarify";
+    if (d.design === "mentions-no-ref")
+        return "clarify";
+    return "confirm";
+}
+export function classifyEntryState(input) {
+    const pathDecidedness = classifyPathDecidedness(input);
+    const featureCompleteness = classifyFeatureCompleteness(input);
+    const designCompleteness = classifyDesignCompleteness(input);
+    const entryStage = entryStageFor({
+        path: pathDecidedness,
+        feature: featureCompleteness,
+        design: designCompleteness,
+    });
+    const sdkCount = input.solutionPath.signals.sdk.length;
+    const uikitCount = input.solutionPath.signals.uikit.length;
+    const rationale = [
+        `path-decidedness: ${pathDecidedness} (solution-path ${input.solutionPath.recommendation}; ${sdkCount} sdk / ${uikitCount} uikit signal(s)${input.hasExplicitPathAnswer ? "; explicit answer" : ""}).`,
+        `feature-completeness: ${featureCompleteness} (outcome ${input.outcome}${input.broadSocialRequest ? "; broad" : ""}${input.multiSurface ? "; multi-surface" : ""}${input.creativeSelected ? "; creative variant accepted" : ""}).`,
+        `design-completeness: ${designCompleteness} (${input.mentionsDesign ? "design mentioned" : "no design mention"}; ${input.designSignalCount} in-repo design signal(s)).`,
+        `enters the flow at the "${entryStage}" stage.`,
+    ];
+    return {
+        entryStage,
+        pathDecidedness,
+        featureCompleteness,
+        designCompleteness,
+        rationale,
+        advisoryOnly: ENTRY_STATE_ADVISORY,
+    };
+}

package/dist/experience.js

@@ -0,0 +1,70 @@
+const COMMUNITY_TOKEN = /\bcommunit(?:y|ies)\b/i;
+const COMMUNITY_CONTENT_TOKEN = /\b(?:feed|posts?|timeline|wall|content|share|discuss(?:ion)?|stories)\b/i;
+const COMMUNITY_EXPERIENCE_PHRASE = /\bcommunity\s+(?:experience|space|hub|home|page)\b/i;
+const COMMUNITY_EXPERIENCE = {
+    id: "community",
+    variantId: "community-first",
+    matches: (request) => COMMUNITY_EXPERIENCE_PHRASE.test(request) || (COMMUNITY_TOKEN.test(request) && COMMUNITY_CONTENT_TOKEN.test(request)),
+    surfaces: [
+        { id: "feed", tier: "required-for-coherence" },
+        { id: "comments", tier: "recommended" },
+        { id: "community", tier: "required-for-coherence" },
+    ],
+};
+const MESSAGING_SIGNALS = [
+    /\b(?:direct|private|instant|encrypted|secure|one[\s-]?on[\s-]?one|one[\s-]?to[\s-]?one|1\s?[-:]\s?1|peer[\s-]?to[\s-]?peer)[\s-]+messag\w+\b/i,
+    /\b(?:messaging|messenger)\s+(?:experience|app|application|feature|inbox)\b/i,
+    /\b(?:dms?|direct[\s-]?messages?)\s+(?:feature|inbox|experience|system|thread|cent(?:er|re))\b/i,
+];
+const MESSAGING_EXPERIENCE = {
+    id: "messaging",
+    variantId: "messaging-first",
+    matches: (request) => MESSAGING_SIGNALS.some((re) => re.test(request)),
+    surfaces: [
+        { id: "chat", tier: "required-for-coherence" },
+        { id: "profile", tier: "recommended" },
+        { id: "notifications", tier: "recommended" },
+    ],
+};
+const DISCUSSION_SIGNALS = [
+    /\b(?:discussion|community|online|message|q\s?&\s?a|q&a|qanda)\s+(?:forums?|boards?)\b/i,
+    /\b(?:forums?|message\s+boards?|bulletin\s+boards?)\s+(?:feature|experience|for\b)/i,
+    /\bthreaded\s+discussions?\b/i,
+    /\bq\s?&\s?a\s+(?:community|forum|board|experience|platform)\b/i,
+];
+const DISCUSSION_EXPERIENCE = {
+    id: "discussion",
+    variantId: "knowledge-network",
+    surfaces: [
+        { id: "feed", tier: "required-for-coherence" },
+        { id: "comments", tier: "required-for-coherence" },
+        { id: "community", tier: "recommended" },
+    ],
+    matches: (request) => DISCUSSION_SIGNALS.some((re) => re.test(request)),
+};
+const CREATOR_SIGNALS = [
+    /\b(?:creator|influencer|content[\s-]?creators?)\s+(?:platform|econom\w+|hub|program|tools?|studio|community|app|application|experience|marketplace|network|portal|space)\b/i,
+    /\bcreator[\s-]?monetization\b/i,
+    /\bmonetiz\w+\s+(?:creators?|content|audiences?|fans?|subscribers?|followers?)\b/i,
+];
+const CREATOR_EXPERIENCE = {
+    id: "creator",
+    variantId: "creator-first",
+    surfaces: [
+        { id: "feed", tier: "required-for-coherence" },
+        { id: "profile", tier: "required-for-coherence" },
+        { id: "comments", tier: "recommended" },
+        { id: "livestream", tier: "recommended" },
+    ],
+    matches: (request) => CREATOR_SIGNALS.some((re) => re.test(request)),
+};
+export const EXPERIENCE_BUNDLES = [
+    COMMUNITY_EXPERIENCE,
+    MESSAGING_EXPERIENCE,
+    DISCUSSION_EXPERIENCE,
+    CREATOR_EXPERIENCE,
+];
+export function experienceBundleFor(request) {
+    const text = typeof request === "string" ? request : "";
+    return EXPERIENCE_BUNDLES.find((bundle) => bundle.matches(text));
+}

package/dist/explore.js

@@ -0,0 +1,51 @@
+import { capabilityChecklist } from "./capabilities.js";
+import { classifyOutcome, getOutcomeDefinition } from "./outcomes.js";
+const DISCOVERY_MENU = [
+    "setup-sdk",
+    "add-feed",
+    "add-comments",
+    "add-chat",
+    "add-community",
+    "add-follow",
+    "add-moderation",
+    "add-notifications",
+    "setup-push",
+    "setup-live-data",
+];
+function outcomeBrief(outcome, platform, request) {
+    const def = getOutcomeDefinition(outcome);
+    return {
+        outcome,
+        summary: def.interpretation,
+        capabilities: capabilityChecklist(outcome).map((capability) => ({ id: capability.id, label: capability.label })),
+        docs: def.docs(platform).slice(0, 4).map((doc) => ({ path: doc.path, reason: doc.reason })),
+        start: `vise plan . --request ${JSON.stringify(request)}`,
+    };
+}
+export function exploreRequest(request, platform = "typescript") {
+    const matched = classifyOutcome(request);
+    const isKnown = matched !== "unknown" && DISCOVERY_MENU.includes(matched);
+    if (isKnown) {
+        return {
+            kind: "exploration",
+            request,
+            platform,
+            matched_outcome: matched,
+            routes: [outcomeBrief(matched, platform, request)],
+            also_available: DISCOVERY_MENU.filter((outcome) => outcome !== matched).map((outcome) => ({
+                outcome,
+                summary: getOutcomeDefinition(outcome).interpretation,
+            })),
+            note: "Discovery is pre-credentials and read-only — no project or API key needed. When you're ready to build, `vise plan`/`vise init` starts a tracked integration.",
+        };
+    }
+    return {
+        kind: "exploration",
+        request,
+        platform,
+        matched_outcome: null,
+        unmatched_note: "This request didn't map to a single social.plus outcome. Below is everything Vise can guide you through — pick one and run its `start` command.",
+        routes: DISCOVERY_MENU.map((outcome) => outcomeBrief(outcome, platform, request)),
+        note: "Discovery is pre-credentials and read-only — no project or API key needed. When you're ready to build, `vise plan`/`vise init` starts a tracked integration. If this is a broad social *product* (you're still shaping WHICH surfaces fit), run `vise creative <project> --request \"...\"` for an experience brief (ranked surface journeys) before committing to a single outcome.",
+    };
+}