@amityco/social-plus-vise 0.14.23 → 0.14.24

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `@amityco/social-plus-vise` are documented in this file.
 
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.14.24 — 2026-06-06
+
+### Changed
+- **Evidence-backed workplan completion:** `vise workplan complete` now runs the current compliance check, refuses non-green results, records check evidence in `sp-vise/workplan.json`, and snapshots the active compliance sidecar under `sp-vise/workplan-snapshots/<surface>/`.
+- **Scoped comments/chat/profile completeness:** the `add-comments` baseline is now narrowed to the comment composer/write affordance, `add-chat` is narrowed to send plus read/unread state, and `add-follow` is narrowed to follower/following relationship data, so focused surfaces do not fail on unselected replies, mentions, media-message types, edit/delete, typing, follow-request, block-list, or deeper moderation scope.
+- **Bundled host-agent skill guidance:** `social-plus-vise` now teaches agents to drive broad social requests through `vise workplan next/status/complete`, implement one focused surface at a time, and show `sp-vise/design-preview.html` before answering `design_contract_confirmation=yes`.
+
+### Verified
+- CLI regression coverage now initializes a focused Android feed sidecar before marking a workplan surface complete, then verifies the green-check evidence and per-surface snapshot files.
+- Capability regression coverage now locks the narrow `add-comments`, `add-chat`, and `add-follow` baselines.
+
 ## 0.14.23 — 2026-06-06
 
 ### Added

package/README.md

@@ -77,7 +77,7 @@ Vise validates on three layers, and the layer is set by the *kind of claim* —
 |---|---|---|---|
 | **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, render a preview for confirmation, then check token usage | **Advisory** — `vise design check`/`preview`; never fails a build |
-| **Feature completeness** | "this is **missing**" | Vise proposes a narrow baseline per outcome; for add-feed, pagination is mandatory, while richer feed capabilities are opt-in choices from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline capability is built or validly opted out; selected optional capabilities run separate sensors |
+| **Feature completeness** | "this is **missing**" | Vise proposes a narrow baseline per outcome; for add-feed, pagination is mandatory, for add-comments, the composer/write affordance is mandatory, for add-chat, send plus read/unread state are mandatory, and for add-follow/profile, SDK-backed follower/following data is mandatory, while richer feed capabilities are opt-in choices from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline capability is built or validly opted out; selected optional capabilities run separate sensors |
 
 Correctness is gated by deterministic rules or attestations. Baseline completeness is gated by explicit scope decisions: if a baseline capability is legitimately out of scope, record `// vise: scope-omit <id> — <reason>` and it no longer blocks. Optional feed capabilities such as image upload, poll creation, and edit post are offered during planning and become checked only after the user opts in. Conformance remains advisory because "matches the brand" is legitimately subjective. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
@@ -161,15 +161,15 @@ Aggregate: **98/99 expected feed capabilities** and **27/27 selected optional ca
 
 ### Current Release Validation
 
-Version 0.14.23 carries current release proof around the full feed-forward, product-expectation, and validation flow:
+Version 0.14.24 carries current release proof around the full feed-forward, product-expectation, and validation flow:
 
 | Surface | What was validated |
 |---|---|
 | **Product flow** | Local end-to-end smoke covers design extraction, plan feed-forward, blocking intake, answered init, capability check, design conformance, and sensor discovery. |
-| **Multi-surface planning** | Broad social requests are decomposed into a `socialWorkplan` sequence for feed, comments, chat, and profile work instead of forcing a single top-level surface choice. `vise workplan next` tells the host agent which surface to implement next, and `vise workplan complete` records progress in `sp-vise/workplan.json`. |
+| **Multi-surface planning** | Broad social requests are decomposed into a `socialWorkplan` sequence for feed, comments, chat, and profile work instead of forcing a single top-level surface choice. `vise workplan next` tells the host agent which surface to implement next, and `vise workplan complete` records green-check progress in `sp-vise/workplan.json` with per-surface snapshots under `sp-vise/workplan-snapshots/<surface>/`. |
 | **Plan questions** | Plans surface blocking questions such as `design_contract_confirmation`, product-scope questions such as `feed_post_type_scope`, `feed_composer_type_scope`, `comment_tray_scope`, `chat_inbox_scope`, and `profile_identity_scope`, plus optional choices such as `feed_optional_capabilities`. Focused plans still accept `feature_surface` answers when the agent is ready to implement one surface. |
 | **Capability-to-sensor flow** | Vise checks platform support, matches the prompt to available capabilities, offers supported features as questions, records answers, and turns selected answers into sensors in `vise check`. |
-| **Android workplan dogfood** | A brownfield Android music-player app refreshed under `0.14.22` reached `vise check` green with **43/43 deterministic passes**, passed `vise validate`, and passed Gradle assemble/unit-test sensors. This is dogfood evidence, not a controlled multi-agent benchmark. |
+| **Android workplan dogfood** | A brownfield Android music-player app refreshed under `0.14.24` reached `vise check` green with **43/43 deterministic passes** on the focused feed surface and recorded a green-check workplan snapshot. This is dogfood evidence, not a controlled multi-agent benchmark. |
 | **Shared product expectations** | Public IDs such as `feed.target-resolved`, `feed.post-type-scope-explicit`, `comments.creation-affordance`, `chat.channel-list-order-explicit`, `community.avatar-from-sdk`, `moderation.role-gated-action`, `follow.relationship-live`, `profile.identity-from-sdk`, `profile.social-counts`, and `notifications.tray-live` stay platform-agnostic while check results retain concrete `contractRuleId` and `validator.sensorId` evidence when deterministic sensors exist. |
 | **Rule detection** | TP-track dashboard detects **321/321 seeded rule gaps (100.0%)** in the static corpus. |
 | **Packed-package smoke** | Packed-package and host-agent smokes exercise the release tarball path, surfaced plan questions, selected optional capability sensors, rejected design confirmation handling, and exact contract-rule evidence for shared product expectations. |
@@ -302,7 +302,7 @@ 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 workplan next [path] --request "..."` | For broad social requests, print the next uncompleted surface plus focused `plan` / `init` / verification commands |
 | `vise workplan status [path] --request "..."` | Show the broad social workplan sequence and which surfaces are already marked complete |
-| `vise workplan complete [path] --request "..." --surface <id>` | Record a completed workplan surface in `sp-vise/workplan.json` after `check`, `sync`, `validate`, and sensors pass |
+| `vise workplan complete [path] --request "..." --surface <id>` | Record a completed workplan surface after green `vise check`; writes progress to `sp-vise/workplan.json` and snapshots the active sidecar under `sp-vise/workplan-snapshots/<surface>/` |
 | `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract after blocking intake is answered; returns `needs-clarification` and exits 7 if required answers are missing |
 | `vise blocks list --registry <path>` | Read a social.plus Block Factory registry |
 | `vise blocks plan [path] --block <id> --registry <path>` | Plan safe block package, source-anchor, sidecar, and sensor changes |
@@ -458,7 +458,8 @@ After a successful `vise init`, your project gets a `sp-vise/` directory. If ini
 | `sp-vise/intake.json` | `vise init` | The request, outcome, intake answers, remaining blocking count, design-review status (`absent`, `needs-confirmation`, `accepted`, or `rejected`), and any retrospective `--allow-unresolved-intake` acknowledgement. |
 | `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/workplan.json` | `vise workplan complete` | Local progress for broad social workplans: request, completed surface IDs, outcomes, timestamps, and optional host-agent notes. |
+| `sp-vise/workplan.json` | `vise workplan complete` | Local progress for broad social workplans: request, completed surface IDs, outcomes, timestamps, green-check evidence, snapshot paths, and optional host-agent notes. |
+| `sp-vise/workplan-snapshots/<surface>/` | `vise workplan complete` | Per-surface compliance/check snapshots copied from the active sidecar so later focused surfaces can overwrite `sp-vise/compliance.json` without erasing earlier proof. |
 | `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-preview.html` | `vise design extract` or `vise design preview` | Self-contained visual review of the design contract, embedded prototype when available, token swatches, and design-check conformance summary. Open this before answering `design_contract_confirmation`. |
 | `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. |

package/dist/capabilities.js

@@ -13,7 +13,11 @@
  * agent subtracts with justification — it doesn't have to remember the set.
  *
  * Baseline capability gates must stay narrow. For add-feed, pagination is the
- * mandatory capability; richer composer affordances are selected optional sensors.
+ * mandatory capability. For add-comments, the comment composer is mandatory.
+ * For add-chat, sending plus read/unread state are mandatory. For add-follow,
+ * follower/following relationship data is mandatory. Replies, mentions,
+ * edit/delete, typing, media-message types, block lists, and deeper moderation
+ * scope are scoped separately. Richer composer affordances are selected optional sensors.
  */
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
@@ -325,10 +329,10 @@ export const CAPABILITIES = [
     },
     {
         id: "followers-following",
-        label: "Follower / following lists",
+        label: "Follower / following counts or 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)",
+        symbols: [/getFollowers/i, /getFollowings/i, /getFollowerList/i, /followRelationship/i, /getMyFollowInfo/i, /getFollowerCount/i, /getFollowingCount/i],
+        hint: "source follower/following counts or lists from SDK relationship APIs, not placeholders",
     },
     {
         id: "follow-status",
@@ -1166,6 +1170,9 @@ 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).";
 const BASELINE_CAPABILITY_IDS_BY_OUTCOME = {
     "add-feed": ["pagination"],
+    "add-comments": ["comment-composer"],
+    "add-chat": ["send-message", "read-state"],
+    "add-follow": ["followers-following"],
 };
 function baselineCapabilities(outcome) {
     const caps = CAPABILITIES.filter((c) => c.outcomes.includes(outcome));

package/dist/server.js

@@ -1015,11 +1015,13 @@ async function completeWorkplanSurface(args) {
         throw new Error(`Surface "${surfaceId}" is not in this social workplan. Available surfaces: ${sequence.map((item) => item.id).join(", ") || "(none)"}.`);
     }
     const now = new Date().toISOString();
+    const check = await greenWorkplanCheck(repoRoot, surfaceId);
+    const snapshot = await writeWorkplanSurfaceSnapshot(repoRoot, surfaceId, check, now);
     const existing = await readWorkplanProgress(repoRoot);
     const base = existing?.request === request
         ? existing
         : {
-            schema_version: 1,
+            schema_version: 2,
             vise_version: packageVersion,
             request,
             generated_at: now,
@@ -1029,6 +1031,7 @@ async function completeWorkplanSurface(args) {
     const withoutSurface = base.completed.filter((item) => item.surface !== surfaceId);
     const progress = {
         ...base,
+        schema_version: 2,
         vise_version: packageVersion,
         updated_at: now,
         completed: [
@@ -1038,6 +1041,17 @@ async function completeWorkplanSurface(args) {
                 outcome: surface.outcome,
                 completed_at: now,
                 ...(note ? { note } : {}),
+                evidence: {
+                    check: {
+                        checked_at: now,
+                        status: check.status,
+                        exit_code: check.exitCode,
+                        outcome: check.outcome,
+                        ...(check.surfacePath ? { surface_path: check.surfacePath } : {}),
+                        summary: check.summary,
+                    },
+                    snapshot,
+                },
             },
         ].sort((a, b) => sequenceIndex(sequence, a.surface) - sequenceIndex(sequence, b.surface)),
     };
@@ -1051,6 +1065,46 @@ async function completeWorkplanSurface(args) {
         nextStep: status.nextStep,
     };
 }
+async function greenWorkplanCheck(repoRoot, surfaceId) {
+    let check;
+    try {
+        check = await checkCompliance(repoRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Cannot mark "${surfaceId}" complete because the current compliance check could not run. Run the focused \`vise init\` command for this surface first, then \`vise check .\`. ${message}`);
+    }
+    if (check.status !== "green") {
+        throw new Error(`Cannot mark "${surfaceId}" complete because \`vise check\` returned "${check.status}" (exit ${check.exitCode}). Resolve the check result before recording workplan progress.`);
+    }
+    return check;
+}
+async function writeWorkplanSurfaceSnapshot(repoRoot, surfaceId, check, snapshotAt) {
+    const snapshotDir = workplanSurfaceSnapshotDir(repoRoot, surfaceId);
+    await mkdir(snapshotDir, { recursive: true });
+    const files = [];
+    const sidecarRoot = sidecarPath(repoRoot);
+    for (const fileName of ["compliance.json", "intake.json", "inspection.json", "findings.json"]) {
+        const sourcePath = path.join(sidecarRoot, fileName);
+        if (!(await fileExists(sourcePath))) {
+            continue;
+        }
+        const targetPath = path.join(snapshotDir, fileName);
+        await copyFile(sourcePath, targetPath);
+        files.push(repoRelativePath(repoRoot, targetPath));
+    }
+    const checkPath = path.join(snapshotDir, "check.json");
+    await writeFile(checkPath, `${JSON.stringify({
+        snapshot_at: snapshotAt,
+        surface: surfaceId,
+        check,
+    }, null, 2)}\n`, "utf8");
+    files.push(repoRelativePath(repoRoot, checkPath));
+    return {
+        directory: repoRelativePath(repoRoot, snapshotDir),
+        files: files.sort(),
+    };
+}
 async function workplanPlan(repoRoot, request, args) {
     const answers = keyValueFlag(args, "answer");
     delete answers.feature_surface;
@@ -1083,7 +1137,20 @@ async function writeWorkplanProgress(repoRoot, progress) {
     await writeFile(filePath, `${JSON.stringify(progress, null, 2)}\n`, "utf8");
 }
 function workplanProgressPath(repoRoot) {
-    return path.join(repoRoot, "sp-vise", "workplan.json");
+    return path.join(sidecarPath(repoRoot), "workplan.json");
+}
+function workplanSurfaceSnapshotDir(repoRoot, surfaceId) {
+    const safeSurfaceId = surfaceId.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (!safeSurfaceId) {
+        throw new Error(`Invalid workplan surface id: "${surfaceId}".`);
+    }
+    return path.join(sidecarPath(repoRoot), "workplan-snapshots", safeSurfaceId);
+}
+function sidecarPath(repoRoot) {
+    return path.join(repoRoot, "sp-vise");
+}
+function repoRelativePath(repoRoot, filePath) {
+    return path.relative(repoRoot, filePath).split(path.sep).join("/");
 }
 function sequenceIndex(sequence, surfaceId) {
     const index = sequence.findIndex((surface) => surface.id === surfaceId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.14.23",
+  "version": "0.14.24",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/skills/social-plus-vise/SKILL.md

@@ -19,6 +19,33 @@ vise plan . --request "<user intent>"
 vise init . --request "<user intent>"
 ```
 
+For broad social requests, `vise plan` may return `socialWorkplan.kind:
+"social-multi-surface"`. In that case, do not force the whole request into one
+sidecar. Drive the ordered workplan:
+
+```bash
+vise workplan next . --request "<user intent>"
+# Run the focused plan/init commands printed for the next surface.
+vise plan . --request "<user intent>" --answer feature_surface=<surface> ...
+vise init . --request "<user intent>" --answer feature_surface=<surface> ...
+```
+
+Implement one surface at a time. Surface that focused plan's intake questions to
+the user, including opt-in capability questions, then run the normal check loop.
+After `vise check`, `vise sync`, `vise validate`, and `vise run-sensors` pass,
+record the surface:
+
+```bash
+vise workplan complete . --request "<user intent>" --surface <surface>
+vise workplan status . --request "<user intent>"
+```
+
+`workplan complete` is evidence-backed: it refuses non-green `vise check`
+results and snapshots the surface's compliance/check sidecar under
+`sp-vise/workplan-snapshots/<surface>/`. Repeat until `workplan status` reports
+the broad request complete, then run one final `vise check`, `vise validate`,
+and `vise run-sensors` before handoff.
+
 Then fetch docs cited by the plan or relevant to the requested feature:
 
 ```bash
@@ -39,9 +66,18 @@ vise run-sensors .
 
 **Feed-forward optional capabilities require an explicit answer.** When `vise plan` returns `optionalCapabilities` or the intake question `feed_optional_capabilities`, do not silently ignore it. Either pass the selected exact ids through both `vise plan` and `vise init`, for example `--answer feed_optional_capabilities=post-image-upload,post-poll-creation`, or pass `--answer feed_optional_capabilities=none` and state that the optional capabilities are out of scope. Selected optional capabilities become source sensors in `vise check`; unselected ones remain non-mandatory.
 
+**Design confirmation must be shown, not assumed.** When `vise plan` or `vise init`
+asks `design_contract_confirmation`, open `sp-vise/design-preview.html` (or run
+`vise design extract --from-project` / `vise design preview` first if no preview
+exists) and show it to the user for approval. Pass
+`--answer design_contract_confirmation=yes` only after approval. If the user says
+no, do not pass `yes`; revise the design source and regenerate the preview, or
+continue only after the user explicitly scopes the work without design
+feed-forward.
+
 **Blocking intake questions must be surfaced to the user.** If `vise plan` returns `intake.status: "needs-clarification"` with blocking questions, stop and ask those questions before implementation. Current Vise also enforces this at `vise init`: unresolved blocking intake returns `status: "needs-clarification"` and the CLI exits non-zero. Only retrospective benchmark/harness setup may pass `--allow-unresolved-intake`, and that acknowledgement is recorded in `sp-vise/intake.json`.
 
-**Baseline completeness is also a stop condition.** When `vise check .` exits with status `completeness-gap` (exit code 5), one or more baseline capabilities are neither implemented nor opted-out. For add-feed, the baseline capability is pagination. For each missing item: either implement it, or place `// vise: scope-omit <id> — <reason>` in the relevant source file and re-run `vise check .` to confirm it exits 0. A missing baseline capability that is neither built nor opted-out is a silent drop — the check will not pass green until every baseline capability is resolved.
+**Baseline completeness is also a stop condition.** When `vise check .` exits with status `completeness-gap` (exit code 5), one or more baseline capabilities are neither implemented nor opted-out. For add-feed, the baseline capability is pagination. For add-comments, the baseline capability is the comment composer/write affordance. For add-chat, the baseline capabilities are message send plus read/unread state. For add-follow/profile, the baseline capability is SDK-backed follower/following relationship data. For each missing item: either implement it, or place `// vise: scope-omit <id> — <reason>` in the relevant source file and re-run `vise check .` to confirm it exits 0. A missing baseline capability that is neither built nor opted-out is a silent drop — the check will not pass green until every baseline capability is resolved.
 
 Treat Vise runtime smoke sensors as real validation. For TypeScript/React Native projects, `vise run-sensors` may include `TypeScript SDK import smoke`; if it fails, the SDK package does not resolve from the host project runtime and the integration is not done.
 
@@ -248,7 +284,7 @@ vise plan . --request "<feed or post request>"
 
 Require a concrete target from the app: current user feed, selected community, selected channel, or another user-provided domain object. Do not hardcode random target IDs.
 
-**Decide engagement scope explicitly — Vise authors the baseline checklist, and optional feed capabilities require user opt-in.** `vise plan` returns a `completenessChecklist` for baseline capabilities (for add-feed today: pagination) and an `optionalCapabilities` block for feed-forward choices such as image upload, poll creation, and edit post. `vise check` reports baseline capabilities as present / missing / opted-out. Missing baseline items that are neither built nor validly opted-out produce `completeness-gap` (exit code 5), because they are silent drops. For each baseline capability: build it, or explicitly opt out with a recorded marker in the code so the omission is reviewable, not accidental:
+**Decide engagement scope explicitly — Vise authors the baseline checklist, and optional feed capabilities require user opt-in.** `vise plan` returns a `completenessChecklist` for baseline capabilities (for add-feed today: pagination; for add-comments: comment composer/write affordance; for add-chat: send plus read/unread state; for add-follow/profile: follower/following relationship data) and an `optionalCapabilities` block for feed-forward choices such as image upload, poll creation, and edit post. `vise check` reports baseline capabilities as present / missing / opted-out. Missing baseline items that are neither built nor validly opted-out produce `completeness-gap` (exit code 5), because they are silent drops. For each baseline capability: build it, or explicitly opt out with a recorded marker in the code so the omission is reviewable, not accidental:
 
 ```
 // vise: scope-omit pagination — single-screen feed; no load-more affordance in this integration