@amityco/social-plus-vise 0.11.0 → 0.12.3

package/CHANGELOG.md

@@ -4,6 +4,64 @@ 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.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`.
+
+## 0.12.1 — 2026-06-02
+
+**Theme:** False-positive-frontier sweep — cross-platform FP hardening driven by the benchmark factory, plus compiler/surface ground-truth for grading. Patch release: all changes are false-positive corrections to existing rules (no new rules, no new features, no breaking changes). TP detection held at **290/290** across all of the below; every fix is locked with a both-direction regression fixture (`test/run-native-idioms.mjs`).
+
+### Fixed
+- **iOS/Android/Flutter push rules** no longer fire on a host app's own generic push (APNs/FCM). `push.unregister.present` and `push.payload-contract-respected` now require a social.plus push **registration nexus** (`registerPushNotification`), not the OS primitive (`didRegisterForRemoteNotifications` / a bare `onMessageReceived`). *(brownfield-iOS cell)*
+- **Ban-state** recognizes a `currentUserIsBanned` prop guard — the ban state fetched in a parent and passed down as a prop (a camelCase boolean form the marker missed). *(brownfield-Flutter cell)*
+- **`custom-post-type.dataType-declared`** no longer flags a plain text post (`createPost({ data: { text } })`) as a custom-data post. *(weak-model-feed cell)*
+- **Android brownfield cluster** — `dependency.sdk` scans feature-module Gradle files (not just `app/`); `setup.lifecycle` no longer flags application-scoped setup in a Hilt `@Module`; `auth.no-anonymous-write` recognizes a write gated on `getCurrentUserId()`. *(brownfield-Android cell)*
+- **React Native** — `client.region` recognizes a positionally-passed region arg (`createClient(KEY, AMITY_REGION)`); `logout-on-user-switch` no longer treats a React `setCurrentUser` useState setter as an SDK user-switch (now keys on the real `setActiveUser`). *(react-native-feed cell)*
+
+### Benchmark & quality infrastructure (`bench/`)
+- **Grading ground truth** (`bench/ground-truth.mjs`) — runs the real toolchain (`flutter analyze`, `tsc --noEmit`) where available; on compiler-less Android, flags `AmityType.member` calls whose member isn't a real surface member. Internal grading aid, **not** a shipped rule (Vise deliberately does not type-check).
+- **Scope-aware finding collection** — `bench/collect.mjs` takes an outcome and excludes out-of-scope rules (the same filter `vise check` uses), so a scoped build isn't graded against the validate-setup everything-sweep.
+- **Marker-boundary audit** (`bench/audit-marker-boundaries.mjs`) — surfaces `\bIDENT\b` markers that would miss a longer camelCase SDK symbol. An occasional eyeball aid, deliberately **not** a CI gate.
+
+### Docs
+- **ARCHITECTURE.md** — new "Sources of Truth" section (facts vs. opinion, across the SDK / docs / Vise repos), with a pointer from the docs repo's `.docs-ops/README`.
+
+---
+
+## 0.12.0 — 2026-06-01
+
+**Theme:** Beyond correctness — design conformance, feature completeness, and a self-improving false-positive loop. This release folds in everything since `0.11.0` (which shipped without notes): a full design-contract system, an advisory completeness catalog, three new integration outcomes, SDK-version currency, a large cross-platform false-positive hardening pass (corpus **265 → 300 rules**), and the benchmark factory that now drives FP reduction. All changes are backward-compatible additions or corrections — no breaking CLI changes.
+
+### Added
+- **Design-contract system** — `vise design check` (advisory, non-blocking) verifies a build against a design contract, and `vise design preview` renders a visual conformance report. The contract can be **extracted from an HTML/CSS prototype** (graded extractor) or **derived from the host project's own design system** via `--from-project` (CSS custom properties, Android XML, Flutter named-params, iOS `.colorset` + Swift color extensions). The contract is fed forward into the plan and skill, its digest is recorded in the compliance flow, and undefined CSS-var references are flagged as token-hygiene issues.
+- **Advisory completeness catalog** — feature-completeness nudges with recorded scope opt-outs (the agent can decline a capability with a logged reason; completeness never gates). The capability catalog was deepened to the full social.plus SDK surface, adding stories, events, livestream rooms, pinned posts, post impressions, and message edit/delete.
+- **Three new outcomes** — `add-community` (first-class outcome and the template for future outcomes), `add-follow` (social graph), and `add-notifications` (in-app notification tray).
+- **SDK-version currency** — `vise plan` now surfaces advisory guidance when a project pins an older SDK than the latest published, resolved from the npm registry (TS `@amityco/ts-sdk`, React Native `@amityco/ts-sdk-react-native`; native platforms version-agnostic). Bounded by a tight registry timeout with a graceful offline fallback.
+- **Acme-derived rules** — comment-creation rule + routing fix, mention-rendering guidance, parent/child post-type handling, and several new `add-feed` plan steps, all from real-world gap analysis.
+
+### Changed
+- **Large cross-platform false-positive hardening pass** across iOS (v8), Android, Flutter, and TypeScript/React Native — the markers now recognize the idiomatic native forms agents actually write: ban-state via `isGlobalBanned`/`isGlobalBan` and agent-derived ban booleans; service/repository (non-UI) layers skipped for ban-state/role-gated/flag-count rules; region via idiomatic TS (`API_REGIONS`) and Flutter (`httpEndpoint`/`AmityRegion`) forms; live collections via Android `LiveData`, Jetpack Compose, and Paging3 (`collectAsLazyPagingItems`); Kotlin sealed-class discriminators; one-shot `await queryX()` no longer mistaken for a subscription.
+- **Session-handler guidance corrected** — rules and findings named `AmitySessionHandler`, a type that exists in no SDK. Corrected to the real symbols: `SessionHandler` (Android/iOS) and a `(AccessTokenRenewal renewal)` callback (Flutter). Detection was unaffected; guidance only.
+- **Corpus grew from 265 → 300 rules.**
+
+### Fixed
+- iOS live-collection crash on files larger than 32 KB.
+- Flutter region marker keyed on a nonexistent `socketEndpoint`; replaced with the real `httpEndpoint`/`mqttEndpoint`/`uploadEndpoint` + `AmityRegional{Http,Mqtt}Endpoint` variants.
+- Several moderation false positives (flag is a user-level action; delete/edit are owner-or-mod) and post-datatype scoping (a comment renderer is not a post renderer).
+
+### Benchmark & quality infrastructure (`bench/`)
+- **Benchmark factory** — a synthetic two-track loop. A change counts as an improvement only if **FP↓ AND TP held** (coupled metric). The true-positive detection rate is a static seeded corpus (`bench/tp-dashboard.mjs`, currently 290/290); the false-positive *rate* is measured on fresh blind builds, never a static corpus. An LLM grader classifies findings FP-vs-real and is validated against labeled ground truth before being trusted. A `bench:gate` CI gate enforces the coupled metric on every change.
+- **FP-grader grounded in the authoritative SDK symbol surface** — the grader's symbol-existence judgments are now deterministic lookups against vendored snapshots distilled from the docs repo's machine-extracted surfaces (DocC ABI / Dokka GFM / TypeDoc / dartdoc), not model recall. `bench:symbols-drift` diffs the live surface against the vendored snapshot — the seam for a future SDK-release drift trigger.
+
+### Docs
+- README + ARCHITECTURE/RULES/TESTING refreshed for the design, completeness, and outcomes capabilities.
+
+### Honest scope
+The design, completeness, and SDK-version layers are **advisory** — they inform and attest, they do not gate (only correctness gates; 7 hard gates across 300 rules). The benchmark factory measures and narrows the false-positive frontier for the idioms it has seen; it does not close it in general. Symbol-surface grounding settles whether an API exists — not whether it is used idiomatically, which remains the hand-authored opinion layer that is the product.
+
+---
+
 ## 0.10.0 — 2026-05-29
 
 **Theme:** Benchmark-driven sensor expansion. The Commune benchmark (9 new SDK domains: chat, push, social graph, moderation, comments) produced the first measured, defensible advantage for vise+skill over pure MCP: **7/9 working features vs 3/9** with the same agent on the same prompts. This release ships the sensors, rules, and findings.json improvements that produced that result.

package/README.md

@@ -45,7 +45,7 @@ See [Usage Flow](#usage-flow) for the full step-by-step diagram.
 
 Instead of just providing a CLI or AI skills, Vise implements a technique called **Agentic Workflow Governance**. Think of it as building a software factory directly on top of the customer's project. 
 
-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 262 platform-specific compliance rules, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
+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.**
 
 | Layer | Purpose |
 |---|---|
@@ -53,6 +53,26 @@ Vise acts as the foreman of this factory, wrapping your local coding agents in c
 | **CLI** (`vise`) | Deterministic engine: inspects repos, searches docs, validates setup, runs sensors, manages attestations |
 | **MCP adapter** | Optional stdio server for MCP-capable tools (Claude Code, Cursor, Codex, VS Code, Copilot) |
 
+### What Vise validates: three layers
+
+Vise validates on three layers, and the layer is set by the *kind of claim* — which keeps it false-positive-free where it gates:
+
+| 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 |
+| **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 |
+
+Only correctness is gated (it can be made FP-free); conformance and completeness are surfaced, because "all post types" and "matches the brand" are legitimately scope-dependent. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+### 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.
+
+### Supported integrations (outcomes)
+
+`vise plan`/`init` classify the request into an outcome and tailor the plan, rules, and feature checklist: **feed** · **comments** · **chat** · **moderation** · **community** · **social graph (follow)** · **in-app notifications** · plus setup (SDK, push, live data).
+
 ### Why "Vise"
 
 A bench vise holds the workpiece steady so the craftsman's hands are free to shape it. Without one, the workpiece drifts and cuts wander. Vise does the same for AI agents integrating SDKs: it clamps the integration to a known-good position (the real docs, the real project structure, the real compliance rules) so the agent can focus on creative work instead of guessing.
@@ -222,6 +242,18 @@ The flow above is what the skill teaches your AI agent. You — the human — dr
 | `vise plan-harness [path] --request "..."` | (Pre-planning step) Build the harness around the request |
 | `vise init [path] --request "..."` | Write the `sp-vise/` compliance contract for this project |
 
+### Design contract (UI generation)
+
+| Command | Purpose |
+|---|---|
+| `vise design extract <prototypePath> [--repo .] [--no-write]` | Read an HTML/CSS prototype and write a graded `sp-vise/design-contract.json` (declared CSS custom properties become exact tokens; repeated literals become inferred/advisory tokens; single-use literals are dropped) so generated social.plus UI can match the customer's aesthetic |
+| `vise design extract --from-project [path] [--no-write]` | No external prototype? Derive the contract from the host project's **own** design system — CSS custom properties (incl. shadcn `:root` and Tailwind v4 `@theme`), TS/JS token modules, inline tailwind configs, **Android** `colors.xml`/`dimens.xml`, **Flutter** `Color(0x…)`, and **iOS** `.xcassets/*.colorset` + Swift `Color(hex:)`/`Color(red:g:b:)`. Reference values (`var()`/`theme()`/`calc()`) are skipped, so a var-mapped config contributes nothing rather than wrong tokens |
+| `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 |
+
+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).
+
 ### Documentation grounding & Troubleshooting
 
 | Command | Purpose |

package/dist/capabilities.js

@@ -0,0 +1,447 @@
+/**
+ * Feature-completeness assessment — ADVISORY ONLY.
+ *
+ * Boundary (see the validation-boundaries principle): completeness is a "this is
+ * missing" claim — a universal-negative over open-ended correct implementations.
+ * It is structurally false-positive-prone and therefore NEVER a hard gate. This
+ * module only surfaces nudges; `vise check`'s status/exit code are untouched.
+ *
+ * Memory-independence comes from inversion: VISE authors the canonical capability
+ * set per outcome; the agent must OPT OUT of a capability with a recorded reason
+ * (`// vise: scope-omit <id> <reason>`), which `check` reads and reports. The
+ * agent subtracts with justification — it doesn't have to remember the set.
+ *
+ * Gate-eligibility (not used here — these stay advisory): a capability could only
+ * ever graduate to a gate if it has a named SDK-call anchor AND a no-fire fixture.
+ * Every capability below is anchored on SDK symbols for exactly that reason, but
+ * the output is advisory regardless.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+// Canonical, Vise-authored capability set — the SDK feature surface (grounded in
+// rules/*.yaml + SKILL.md, not guessed). Anchored on SDK symbol names (consistent
+// enough across TS/Flutter/Android/iOS to match cross-platform). All advisory.
+export const CAPABILITIES = [
+    // ── add-feed: post dataTypes (a feed parent is usually 'text'; rich content
+    //    rides on child posts — render each type the feed can return) ──────────
+    {
+        id: "post-image",
+        label: "Image posts",
+        outcomes: ["add-feed"],
+        symbols: [/\bgetImageInfo\b/, /AmityImage/i, /['"]image['"]/, /childrenPosts/i, /getChildren/i],
+        hint: "resolve image posts via getImageInfo from the parent or a child post (parent is usually dataType 'text')",
+    },
+    {
+        id: "post-video",
+        label: "Video posts",
+        outcomes: ["add-feed"],
+        // Native idioms differ from TS: Android matches a sealed-class case
+        // `AmityPost.Data.VIDEO`, Flutter an enum `AmityDataType.VIDEO`, both expose
+        // getVideo()/videoData. Without these the catalog false-reports video as missing
+        // on Kotlin/Dart even when the agent handles it (found on Netflix native builds).
+        symbols: [/\bgetVideo\w*/, /AmityVideo/i, /['"]video['"]/, /Data(?:Type)?\.VIDEO\b/, /\bvideoData\b/],
+        hint: "resolve video posts via getVideo / the VIDEO dataType from the parent or a child post",
+    },
+    {
+        id: "post-file",
+        label: "File posts",
+        outcomes: ["add-feed"],
+        symbols: [/\bgetFileInfo\b/, /AmityFile(?:Info|Data)?/i, /['"]file['"]/],
+        hint: "render file posts (getFileInfo); upload via AmityFileRepository to get a fileId, never an external URL",
+    },
+    {
+        id: "post-poll",
+        label: "Poll posts",
+        outcomes: ["add-feed"],
+        symbols: [/\bgetPollInfo\b/, /\bvotePoll\b/, /\bunvotePoll\b/, /AmityPoll/i, /PollRepository/i],
+        hint: "resolve polls via getPollInfo; read answer.text + answer.image, support votePoll/unvotePoll, show closedAt",
+    },
+    {
+        id: "post-livestream",
+        label: "Livestream / room posts",
+        outcomes: ["add-feed"],
+        symbols: [/livestream/i, /liveStream/, /getLiveStream/i, /AmityStream/i, /['"](?:liveStream|room)['"]/, /getRoomInfo/i],
+        hint: "render livestream/room posts by title/status — never the raw roomId",
+    },
+    {
+        id: "post-custom",
+        label: "Custom post types",
+        outcomes: ["add-feed"],
+        symbols: [/dataType\s*[:=]\s*['"]custom/i, /['"]custom\.[\w-]+['"]/, /customDataType/i],
+        hint: "render custom-dataType posts (declare dataType on create so the SDK routes them, not a JSON blob)",
+    },
+    {
+        id: "mentions",
+        label: "@mention rendering",
+        outcomes: ["add-feed", "add-comments", "add-chat"],
+        symbols: [/\bmentionees\b/, /\bmentionedUsers\b/, /metadata.*mention/i, /['"]mention['"]/],
+        hint: "wrap @mention spans from metadata offsets and resolve userId→name; pass mentionees on create to notify",
+    },
+    // ── add-feed: broader social.plus content surfaces (advisory — opt out if a
+    //    plain post feed; these are distinct social.plus features) ─────────────
+    {
+        id: "story",
+        label: "Stories (ephemeral image/video)",
+        outcomes: ["add-feed"],
+        symbols: [/AmityStoryRepository/i, /createImageStory/i, /createVideoStory/i, /getActiveStories/i, /AmityStoryTarget/i, /\bAmityStory\b/],
+        hint: "stories via AmityStoryRepository (createImageStory/createVideoStory) — render the story tray, support reactions/comments, and mark stories seen for impression analytics",
+    },
+    {
+        id: "event",
+        label: "Community events",
+        outcomes: ["add-feed"],
+        symbols: [/AmityEventRepository/i, /\bgetEvents\b/, /\bcreateEvent\b/, /AmityEvent(?:Type|Status|QueryBuilder)?\b/],
+        hint: "community events via AmityEventRepository (getEvents/createEvent) — render an events list/detail",
+    },
+    {
+        id: "livestream-broadcast",
+        label: "Livestream rooms / broadcasting",
+        outcomes: ["add-feed"],
+        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)",
+    },
+    // ── add-feed: engagement surfaces ─────────────────────────────────────────
+    {
+        id: "comments",
+        label: "Comment thread (list + composer)",
+        outcomes: ["add-feed"],
+        symbols: [/\bgetComments\b/, /\bcreateComment\b/, /CommentRepository/i],
+        hint: "pair getComments (list) with createComment (composer), gated by the user's ban state",
+    },
+    {
+        id: "reactions",
+        label: "Reactions",
+        outcomes: ["add-feed", "add-comments"],
+        symbols: [/\baddReaction\b/, /\bremoveReaction\b/, /ReactionRepository/i, /\bmyReactions\b/],
+        hint: "addReaction/removeReaction with a tenant-configured reaction name (not a hardcoded literal)",
+    },
+    {
+        id: "pagination",
+        label: "Pagination / load-more",
+        outcomes: ["add-feed", "add-comments", "add-chat"],
+        symbols: [/\bloadMore\b/, /\bonNextPage\b/, /\bnextPage\b/, /\bhasNextPage\b/, /\bloadNext\b/],
+        hint: "drive the collection's loadMore/nextPage (opaque cursors); never numeric page math",
+    },
+    {
+        id: "composer",
+        label: "Post composer (create)",
+        outcomes: ["add-feed"],
+        symbols: [/\bcreatePost\b/, /PostRepository[\s\S]{0,20}create/i],
+        hint: "createPost with a dynamic targetType (not a hardcoded literal)",
+    },
+    {
+        id: "pinned-posts",
+        label: "Pinned / announcement posts",
+        outcomes: ["add-feed"],
+        symbols: [/getPinnedPosts/i, /AmityPinnedPost/i, /\bpinnedPost/i, /\bpinPost\b/i, /\bisPinned\b/i, /AmityPinPlacement/i],
+        hint: "surface pinned/announcement posts (getPinnedPosts) above the feed",
+    },
+    {
+        id: "post-impressions",
+        label: "Post impressions / reach analytics",
+        outcomes: ["add-feed"],
+        symbols: [/markAsViewed/i, /markPostAsViewed/i, /\bimpression/i, /\breach\b/i, /AmityViewedType/i],
+        hint: "mark posts viewed (markAsViewed) so reach/impression analytics are recorded",
+    },
+    {
+        id: "moderation",
+        label: "Moderation affordance (report/flag)",
+        outcomes: ["add-feed", "add-comments", "add-chat"],
+        symbols: [/\bflagPost\b/, /\bflagComment\b/, /\bflagMessage\b/, /\.report\(\)/, /\bflaggedByMe\b/, /\bisFlagged/i],
+        hint: "show report/flag for non-authors; gate moderator-only actions by role",
+    },
+    // ── add-comments: depth ───────────────────────────────────────────────────
+    {
+        id: "comment-composer",
+        label: "Comment composer (write)",
+        outcomes: ["add-comments"],
+        symbols: [/\bcreateComment\b/],
+        hint: "a comment surface needs a composer (createComment), not just a read-only list",
+    },
+    {
+        id: "replies",
+        label: "Comment replies (threads)",
+        outcomes: ["add-comments"],
+        symbols: [/parentId/i, /\bchildrenNumber\b/],
+        hint: "render replies via getComments({ parentId }) when childrenNumber > 0",
+    },
+    {
+        id: "comment-edit-delete",
+        label: "Comment edit / delete (author)",
+        outcomes: ["add-comments"],
+        symbols: [/\bupdateComment\b/, /\beditComment\b/, /\bdeleteComment\b/],
+        hint: "show edit (updateComment) / delete (deleteComment) for the author of a comment",
+    },
+    {
+        id: "comment-moderation",
+        label: "Comment moderation (flag)",
+        outcomes: ["add-comments"],
+        symbols: [/\bflagComment\b/, /\.report\(\)/, /\bflaggedByMe\b/],
+        hint: "show flag/report on comments for non-authors",
+    },
+    // ── add-chat: depth ───────────────────────────────────────────────────────
+    {
+        id: "send-message",
+        label: "Send message",
+        outcomes: ["add-chat"],
+        symbols: [/\bcreateMessage\b/, /\bsendMessage\b/, /MessageRepository/i],
+        hint: "createMessage; observe each message's syncState for failed sends",
+    },
+    {
+        id: "message-types",
+        label: "Message types (image / video / file / custom)",
+        outcomes: ["add-chat"],
+        symbols: [/createImageMessage/i, /createVideoMessage/i, /createFileMessage/i, /createCustomMessage/i, /messageType/i, /AmityMessageType/i],
+        hint: "support non-text message types (image/video/file/custom), not just text",
+    },
+    {
+        id: "message-sync-state",
+        label: "Message delivery state",
+        outcomes: ["add-chat"],
+        symbols: [/\bsyncState\b/, /\bdeleteFailedMessages\b/],
+        hint: "surface failed (error) syncState with a retry/delete affordance",
+    },
+    {
+        id: "message-edit-delete",
+        label: "Message edit / delete (author)",
+        outcomes: ["add-chat"],
+        symbols: [/\bupdateMessage\b/, /\beditMessage\b/, /\bdeleteMessage\b/, /\bsoftDeleteMessage\b/],
+        hint: "let the author edit (updateMessage) and delete (softDeleteMessage) their messages",
+    },
+    {
+        id: "read-state",
+        label: "Read state / unread count",
+        outcomes: ["add-chat"],
+        symbols: [/\bmarkRead\b/, /\bmarkAsRead\b/, /startMessageReceiptSync/i, /\bunreadCount\b/],
+        hint: "mark channel/messages read so the server's unread count decrements",
+    },
+    {
+        id: "typing-indicator",
+        label: "Typing indicator",
+        outcomes: ["add-chat"],
+        symbols: [/startTyping/i, /stopTyping/i, /\bisTyping\b/, /typingPreview/i],
+        hint: "start/stop typing and render others' typing state",
+    },
+    {
+        id: "channel-members",
+        label: "Channel membership",
+        outcomes: ["add-chat"],
+        symbols: [/getMembers/i, /ChannelMember/i, /\bmembership\b/i, /\bgetChannelMembers\b/i],
+        hint: "list/observe channel members; handle join/leave",
+    },
+    // ── add-community ─────────────────────────────────────────────────────────
+    {
+        id: "community-create",
+        label: "Create community",
+        outcomes: ["add-community"],
+        symbols: [/\bcreateCommunity\b/, /AmityCommunityRepository[\s\S]{0,20}create/i, /AmityCommunityCreateOptions/i],
+        hint: "create communities via AmityCommunityRepository (createCommunity) with a chosen privacy model",
+    },
+    {
+        id: "community-join-leave",
+        label: "Join / leave community",
+        outcomes: ["add-community"],
+        symbols: [/\bjoinCommunity\b/, /\bleaveCommunity\b/, /AmityCommunityRepository/i],
+        hint: "joinCommunity/leaveCommunity for public communities",
+    },
+    {
+        id: "community-join-requests",
+        label: "Join requests (private communities)",
+        outcomes: ["add-community"],
+        symbols: [/\bjoinRequest/i, /AmityJoinRequest/i, /joinRequestStatus/i],
+        hint: "private communities use the join-request approval flow (AmityJoinRequest) — handle pending/approve/decline",
+    },
+    {
+        id: "community-members",
+        label: "Member list",
+        outcomes: ["add-community"],
+        symbols: [/\bgetMembers\b/, /AmityCommunityMembership/i, /AmityCommunityMembershipFilter/i],
+        hint: "list/observe members via getMembers (a Live Collection), with membership filters",
+    },
+    {
+        id: "community-roles",
+        label: "Member roles / moderation",
+        outcomes: ["add-community"],
+        symbols: [/\baddRole/i, /\bremoveRole/i, /\bbanMember\b/i, /\bremoveMember\b/i, /\.roles?\b/],
+        hint: "manage moderator roles / ban-remove members, gated by a role check",
+    },
+    {
+        id: "community-invitation",
+        label: "Invitations",
+        outcomes: ["add-community"],
+        symbols: [/createInvitation/i, /AmityInvitation/i, /AmityMembershipAcceptanceType/i],
+        hint: "invite members via createInvitation; handle accept/decline (AmityInvitationStatus)",
+    },
+    {
+        id: "community-categories",
+        label: "Categories",
+        outcomes: ["add-community"],
+        symbols: [/AmityCommunityCategory/i, /getCategories/i, /categoryIds?/i],
+        hint: "organize communities by category (AmityCommunityCategory)",
+    },
+    // ── add-moderation: depth ─────────────────────────────────────────────────
+    {
+        id: "report-flow",
+        label: "Report / flag flow",
+        outcomes: ["add-moderation"],
+        symbols: [/\bflagPost\b/, /\bflagComment\b/, /\bflagMessage\b/, /\.report\(\)/, /\bunflag\b/],
+        hint: "flag/unflag with a confirmation affordance",
+    },
+    {
+        id: "ban-mute",
+        label: "Ban / mute members",
+        outcomes: ["add-moderation"],
+        symbols: [/\bbanUser\b/, /\bunbanUser\b/, /\bmuteChannel\b/, /\bmuteMember\b/, /\bglobalBan\b/i],
+        hint: "ban/unban or mute members (gated by moderator role)",
+    },
+    {
+        id: "review-queue",
+        label: "Post review queue (ADMIN_REVIEW)",
+        outcomes: ["add-moderation"],
+        symbols: [/\bapprovePost\b/, /\bdeclinePost\b/, /reviewing/i, /REVIEW_COMMUNITY_POST/i],
+        hint: "for a moderator surface with review enabled, query feedType 'reviewing' and wire approve/decline (gated on REVIEW_COMMUNITY_POST)",
+    },
+    {
+        id: "hidden-content",
+        label: "Hidden / flagged content rendering",
+        outcomes: ["add-moderation"],
+        symbols: [/isDeleted/i, /\bisFlagged/i, /hasFlaggedComment/i, /blockedContent/i, /\bhidden\b/i],
+        hint: "render a placeholder for deleted/flagged content rather than hiding it silently",
+    },
+    // ── add-follow (social graph) ─────────────────────────────────────────────
+    {
+        id: "follow-unfollow",
+        label: "Follow / unfollow",
+        outcomes: ["add-follow"],
+        symbols: [/\bfollow\b/i, /\bunfollow\b/i, /AmityUserRepository/i],
+        hint: "follow/unfollow via AmityUserRepository; reflect the live follow state on the button",
+    },
+    {
+        id: "followers-following",
+        label: "Follower / following lists",
+        outcomes: ["add-follow"],
+        symbols: [/getFollowers/i, /getFollowings/i, /getFollowerList/i, /followRelationship/i],
+        hint: "list/observe followers and following as a Live Collection (getFollowers/getFollowings)",
+    },
+    {
+        id: "follow-status",
+        label: "Follow-request status",
+        outcomes: ["add-follow"],
+        symbols: [/AmityFollowStatusFilter/i, /followStatus/i, /\bpending\b/i, /acceptFollow/i, /declineFollow/i],
+        hint: "handle the follow-request pending/accept/decline flow when following is not automatic",
+    },
+    {
+        id: "block-unblock",
+        label: "Block / unblock user",
+        outcomes: ["add-follow"],
+        symbols: [/\bblockUser\b/i, /\bunblockUser\b/i, /\bunBlockUser\b/i],
+        hint: "block/unblock a user (blockUser/unblockUser)",
+    },
+    {
+        id: "blocked-users",
+        label: "Blocked-users list",
+        outcomes: ["add-follow"],
+        symbols: [/getBlockedUsers/i, /blockedUsers/i],
+        hint: "surface a managed blocked-users list (getBlockedUsers)",
+    },
+    // ── add-notifications (in-app tray) ───────────────────────────────────────
+    {
+        id: "notification-tray",
+        label: "Notification tray / inbox",
+        outcomes: ["add-notifications"],
+        symbols: [/notificationTray/i, /getNotificationTraySeen/i, /NotificationTrayManager/i, /NotificationTray/],
+        hint: "observe the notification tray (getNotificationTraySeen / tray Live Object) and render the inbox",
+    },
+    {
+        id: "notification-seen",
+        label: "Mark tray seen (unseen badge)",
+        outcomes: ["add-notifications"],
+        symbols: [/markAsSeen/i, /\bmarkSeen\b/i, /\bisSeen\b/i, /unseenCount/i],
+        hint: "mark the tray/items seen (markAsSeen) so the unseen badge clears server-side",
+    },
+    {
+        id: "notification-settings",
+        label: "Notification settings / preferences",
+        outcomes: ["add-notifications"],
+        symbols: [/getSettings/i, /notificationSettings?/i, /notificationPreference/i, /notifications\(\)/],
+        hint: "respect Amity's server-side notification settings/preferences (getSettings)",
+    },
+];
+const ADVISORY_NOTE = "Advisory completeness — NEVER fails `vise check`. Build each missing capability, or opt out with a recorded reason: `// vise: scope-omit <id> <reason>`.";
+/** The Vise-authored capability checklist for an outcome (for `vise plan` feed-forward). */
+export function capabilityChecklist(outcome) {
+    return CAPABILITIES.filter((c) => c.outcomes.includes(outcome)).map((c) => ({ id: c.id, label: c.label, hint: c.hint }));
+}
+/** Pure assessment over already-read source text. */
+export function assessCompleteness(source, outcome) {
+    const caps = CAPABILITIES.filter((c) => c.outcomes.includes(outcome));
+    const optOuts = new Map();
+    const omitPattern = /vise:\s*scope-omit\s+([a-z][\w-]*)\s*(?:[—:|-]+\s*(.*))?/gi;
+    let match;
+    while ((match = omitPattern.exec(source)) !== null) {
+        optOuts.set(match[1].toLowerCase(), (match[2] ?? "").trim() || "no reason given");
+    }
+    const present = [];
+    const missing = [];
+    const optedOut = [];
+    for (const cap of caps) {
+        if (optOuts.has(cap.id)) {
+            optedOut.push({ id: cap.id, reason: optOuts.get(cap.id) });
+        }
+        else if (cap.symbols.some((symbol) => symbol.test(source))) {
+            present.push({ id: cap.id, label: cap.label });
+        }
+        else {
+            missing.push({ id: cap.id, label: cap.label, hint: cap.hint });
+        }
+    }
+    return { outcome, present, missing, optedOut, note: ADVISORY_NOTE };
+}
+// ── Bounded source read (advisory; perf-bounded like the design check scan) ──
+const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".dart", ".kt", ".java", ".swift", ".vue"]);
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "coverage", "vendor", ".dart_tool", "pods", "macos", "windows", "linux"]);
+const MAX_FILES = 1500;
+const MAX_FILE_BYTES = 1_000_000;
+export async function assessProjectCompleteness(root, outcome) {
+    if (CAPABILITIES.every((c) => !c.outcomes.includes(outcome))) {
+        return null; // outcome has no completeness checklist
+    }
+    const resolved = path.resolve(root);
+    const parts = [];
+    const stack = [resolved];
+    let count = 0;
+    while (stack.length > 0 && count < MAX_FILES) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (count >= MAX_FILES) {
+                break;
+            }
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".") && entry.name !== "sp-vise") {
+                    stack.push(full);
+                }
+            }
+            else if (entry.isFile() && SCAN_EXTS.has(path.extname(entry.name).toLowerCase())) {
+                count += 1;
+                try {
+                    const info = await stat(full);
+                    if (info.size <= MAX_FILE_BYTES) {
+                        parts.push(await readFile(full, "utf8"));
+                    }
+                }
+                catch {
+                    // skip unreadable
+                }
+            }
+        }
+    }
+    return assessCompleteness(parts.join("\n"), outcome);
+}