@amityco/social-plus-vise 0.14.3 → 0.14.4

package/CHANGELOG.md

@@ -4,7 +4,7 @@ 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.3 — 2026-06-04
+## 0.14.4 — 2026-06-04
 
 **Theme:** Completeness-gap enforcement and add-feed guidance hardening (image upload + poll creation + pagination build step).
 
@@ -17,6 +17,7 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/
 ### Fixed
 - **`targetType` rule recommendation tightened:** the `validateFeedTargetTypeExplicit` validator recommendation now explicitly calls for binding `targetType` to the intake-resolved feed target (e.g. `communityId` from route params, `userId` from auth context) rather than simply avoiding a literal. Prevents agents from introducing an unbound variable that satisfies the literal check while leaving the same intent gap.
 - **Completeness assessment note language corrected:** `vise plan` completeness note and `assessCompleteness` output no longer say "advisory — never fails the check". They now accurately state that missing items cause `vise check` to exit `completeness-gap` (exit code 5).
+- **Scope-omit markers now require a reason:** `// vise: scope-omit <id>` no longer clears a completeness gap by itself. The marker must include a reason (for example `// vise: scope-omit post-poll — polls disabled for this tenant`) or the capability remains `missing`.
 
 ### Changed
 - **`SKILL.md` scope-omit enforcement:** the Required Loop section now treats missing completeness items as a stop condition, not a suggestion. Agents must either implement or `// vise: scope-omit <id> — <reason>` each missing capability before reporting done.

package/README.md

@@ -77,9 +77,9 @@ 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, 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 |
+| **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 | **Decision gate** — `vise check` exits `completeness-gap` until each missing capability is built or validly opted out |
 
-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).
+Correctness is gated by deterministic rules or attestations. Completeness is gated by explicit scope decisions: if a capability is legitimately out of scope, record `// vise: scope-omit <id> — <reason>` and it no longer blocks. Conformance remains advisory because "matches the brand" is legitimately subjective. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### Relationship to social.plus Block Factory
 
@@ -414,7 +414,7 @@ jobs:
 | `2` | One or more rules have deterministic failures |
 | `3` | One or more blockers fired (missing prerequisite, e.g. `google-services.json`) |
 | `4` | Contract drift — rules in `sp-vise/compliance.json` no longer match the current ruleset |
-| `5` | One or more expected capabilities are neither implemented nor opted-out — add the capability or place `// vise: scope-omit <id> — <reason>` |
+| `5` | One or more expected capabilities are neither implemented nor validly opted-out — add the capability or place `// vise: scope-omit <id> — <reason>` |
 
 `vise check --ci` is read-only. It never updates `sp-vise/`. The JSON output includes a `ci` block with structured details for pipeline logs.
 

package/dist/capabilities.js

@@ -1,10 +1,11 @@
 /**
- * Feature-completeness assessment — ADVISORY ONLY.
+ * Feature-completeness assessment.
  *
  * 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.
+ * missing" claim — a universal-negative over open-ended correct implementations
+ * unless the customer/agent explicitly removes it from scope. Missing capabilities
+ * now produce `completeness-gap` in `vise check`; a recorded scope-omit reason is
+ * the false-positive escape hatch.
  *
  * 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
@@ -367,7 +368,7 @@ export const CAPABILITIES = [
         hint: "respect Amity's server-side notification settings/preferences (getSettings)",
     },
 ];
-const ADVISORY_NOTE = "Build each missing capability, or opt out with a recorded reason: `// vise: scope-omit <id> <reason>`. Missing capabilities that are neither built nor opted-out cause `vise check` to exit with status `completeness-gap` (exit code 5).";
+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).";
 /** 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 }));
@@ -376,14 +377,24 @@ export function capabilityChecklist(outcome) {
 export function assessCompleteness(source, outcome) {
     const caps = CAPABILITIES.filter((c) => c.outcomes.includes(outcome));
     const optOuts = new Map();
+    const invalidOptOuts = 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 id = match[1].toLowerCase();
+        const reason = (match[2] ?? "").trim();
+        if (reason) {
+            optOuts.set(id, reason);
+            invalidOptOuts.delete(id);
+        }
+        else if (!optOuts.has(id)) {
+            invalidOptOuts.set(id, "scope-omit marker must include a reason");
+        }
     }
     const present = [];
     const missing = [];
     const optedOut = [];
+    const invalid = [];
     for (const cap of caps) {
         if (optOuts.has(cap.id)) {
             optedOut.push({ id: cap.id, reason: optOuts.get(cap.id) });
@@ -392,10 +403,18 @@ export function assessCompleteness(source, outcome) {
             present.push({ id: cap.id, label: cap.label });
         }
         else {
-            missing.push({ id: cap.id, label: cap.label, hint: cap.hint });
+            const invalidReason = invalidOptOuts.get(cap.id);
+            if (invalidReason) {
+                invalid.push({ id: cap.id, reason: invalidReason });
+            }
+            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,
+            });
         }
     }
-    return { outcome, present, missing, optedOut, note: ADVISORY_NOTE };
+    return { outcome, present, missing, optedOut, invalidOptOuts: invalid, 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"]);

package/dist/tools/compliance.js

@@ -456,9 +456,9 @@ export async function checkCompliance(repoPath) {
     const needsAttestation = results.some((result) => result.status === "attestation-needed" || result.status === "stale");
     // Precedence: blocked (3) > deterministic-failures (2) > needs-attestation (1) > completeness-gap (5) > green (0).
     // Contract drift (exit 4) is handled earlier and short-circuits the loop.
-    // Completeness-gap: capabilities that are neither present nor opted-out require an explicit decision
+    // Completeness-gap: capabilities that are neither present nor validly opted-out require an explicit decision
     // (build it, or place // vise: scope-omit <id> — <reason>). The scope-omit escape hatch keeps this
-    // FP-free — any capability can be excluded with a recorded reason. Failure to assess is silently ignored.
+    // FP-free because any capability can be excluded with a recorded reason. Failure to assess is silently ignored.
     const completeness = (await assessProjectCompleteness(inspection.effectiveRoot, compliance.outcome).catch(() => null)) ?? undefined;
     const hasCompletenessGap = (completeness?.missing.length ?? 0) > 0;
     // Blocked wins because the agent cannot proceed without customer input;

package/package.json

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

@@ -244,13 +244,13 @@ 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 checklist, you subtract with a reason.** `vise plan` returns a `completenessChecklist` (the canonical capabilities for the outcome, e.g. comments, reactions, pagination, polls, media, moderation) and `vise check` reports each as present / missing / opted-out. The check gate never blocks on completeness (to avoid false positives from legitimately scope-limited integrations), but **missing items that are neither built nor opted-out are silent drops — treat them as a stop condition, not a suggestion.** For each 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 checklist, you subtract with a reason.** `vise plan` returns a `completenessChecklist` (the canonical capabilities for the outcome, e.g. comments, reactions, pagination, polls, media, moderation) and `vise check` reports each as present / missing / opted-out. Missing items that are neither built nor validly opted-out produce `completeness-gap` (exit code 5), because they are silent drops. For each capability: build it, or explicitly opt out with a recorded marker in the code so the omission is reviewable, not accidental:
 
 ```
 // vise: scope-omit poll — text + image feed only; polls disabled for this tenant
 ```
 
-Do not report the integration complete while any capability is `missing`. Re-run `vise check .` after placing a scope-omit marker to confirm it moves from `missing` to `opted-out`.
+Do not report the integration complete while any capability is `missing`. A scope-omit marker must include a reason after the capability id; otherwise it remains invalid and the capability still counts as missing. Re-run `vise check .` after placing a scope-omit marker to confirm it moves from `missing` to `opted-out`.
 
 **Demo wiring (when the app needs to compile before the real target source exists):** even at the top-level `App` / `MaterialApp` / `_app.tsx` / `AppDelegate` wiring site, do not pass a literal string. Use the host platform's compile-time env channel so the rule sees no string literal at the call site: