@amityco/social-plus-vise 0.14.2 → 0.14.4

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.4 — 2026-06-04
+
+**Theme:** Completeness-gap enforcement and add-feed guidance hardening (image upload + poll creation + pagination build step).
+
+### Added
+- **`completeness-gap` exit code 5:** `vise check` now exits 5 when capabilities from the completeness checklist are neither built nor explicitly opted-out. Precedence: `blocked(3) > deterministic-failures(2) > needs-attestation(1) > completeness-gap(5) > green(0)`. Agents that silently skip capabilities now see exit 5 rather than 0, making the gap visible in the loop's stop condition. The existing `// vise: scope-omit <id> — <reason>` marker remains the correct opt-out path; a recorded reason moves the capability to `opted-out` and does not trigger the exit.
+- **Image upload build step in `add-feed`:** implementation guidance now covers the two-step upload chain — `FileRepository.uploadImage(file)` followed by `PostRepository.createPost({ …, attachments: [{ fileId, fileType: 'image' }] })` — and explicitly flags the common failure mode (calling `uploadImage` but discarding the `fileId` or omitting `attachments`).
+- **Poll creation build step in `add-feed`:** guidance now covers the `PollRepository.createPoll` → `PostRepository.createPost({ data: { pollId } })` creation chain, distinct from the existing poll-rendering (voting) step. Both halves must be present for a working poll composer.
+- **Pagination build step in `add-feed`:** explicit greenfield build step for wiring `onNextPage` / `hasNextPage`, including the ref-capture pattern (`loadMoreRef.current = onNextPage`). Separate from the existing repair/refactor guard, which continues to protect brownfield edits.
+- **`bench:symbols-drift` wired into `npm run validate`:** the SDK symbol drift check now runs as part of the standard gate, surfacing silent SDK renames before they darken rules.
+### 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.
+- **`rules/feed.yaml` — `symbol_anchored` annotations:** 4 rules whose validators key on specific SDK symbol or parameter names (`targetType`, `dataType`, `addReaction`/`removeReaction`, `.dataType` field access) are annotated with `symbol_anchored: true` to mark them for review after SDK major releases. Described in `docs/ARCHITECTURE.md` under "SDK-Version Coupling."
+
+---
+
 ## 0.14.2 — 2026-06-03
 
 **Theme:** SDK facts bridge for social.plus Block Factory.

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
 
@@ -158,7 +158,8 @@ A failing feature without Vise is *invisible* until a user hits it: the code com
 - **Vise-arm passes were deterministic-pass**, not attestation exceptions — agents fixed the code. (The grader applies a narrow, *symmetric* auto-attestation for absence / type-stub findings across **all** arms including the controls; it cannot satisfy the acceptance patterns, so it does not tilt the result toward Vise.)
 - **Three arms, separate tooling.** The Rules-as-Markdown arm has no Vise checker available — it cannot run `vise check`.
 - **Built from scratch** (greenfield seed), capable models with prior SDK familiarity. A complementary **bug-fix** benchmark showed **no Vise advantage** — the loop helps on greenfield integration, not local bug hunts.
-- **N=1 per cell.** A strong directional signal (the Chat/Moderation/Push mechanism reproduces across both models), **not** a statistically settled finding; repeatability seeds are pending.
+- **N=1 per cell.** A strong directional signal (the Chat/Moderation/Push mechanism reproduces across both models), **not** a statistically settled finding.
+- **Follow-up evidence cuts both ways.** The pre-registered [Capability Matrix](#benchmark-capability-matrix-v1-pre-registered) (n=3, arm-independent grading, different briefs) found **no Row 1 claim** on chat/moderation/push — chat and moderation tied, push +1, below the registered margin — and a new, registered win on feature completeness instead. Read the two together, not Phase 1 alone.
 - **Full methodology, per-cell analysis, and threats to validity:** [the Commune paper](docs/commune-paper-2026-05-30.md). The [`benchmarks/FINDINGS.html`](benchmarks/FINDINGS.html) and [`benchmarks/RULES_AS_MARKDOWN.html`](benchmarks/RULES_AS_MARKDOWN.html) files are **summary report tables**, not raw transcripts or workspace diffs.
 
 ### Which mode should I use?
@@ -171,6 +172,28 @@ A failing feature without Vise is *invisible* until a user hits it: the code com
 
 ---
 
+## Benchmark: Capability Matrix v1 (pre-registered)
+
+> One row won, one tied, one was withheld on a technicality. The registered protocol requires all three to be reported with equal prominence — so here they are.
+
+Phase 1 measured one thing (secondary-compliance gaps) under a harness that overlaps Vise's own ruleset. The **Capability Matrix** is the stricter follow-up: a [pre-registered protocol](benchmarks/capability-matrix/PROTOCOL.md) frozen before any cell ran (7 dated amendments, each committed before the data it governs), **firewalled grading instruments** (authors barred from Vise's rules and config — [authorship record](benchmarks/capability-matrix/AUTHORSHIP.md)), **blind structural judges**, and 27 fresh isolated cells: n=3 seeds per cell, Cursor / Composer 2.5, docs-only control vs Vise loop, identical offline docs bundle in both arms. Full numbers, per-behavior provenance, and the rig-integrity record: [RESULTS.md](benchmarks/capability-matrix/RESULTS.md).
+
+| Capability claim | Registered outcome | What the data says |
+|---|---|---|
+| **Feature completeness** — open feed request scored against an 11-item firewalled ground truth | ✅ **Claim ships** (won 3/3 seed pairs and the mean) | The Vise loop roughly **halved silently-dropped SDK capabilities: 4.0 vs 7.67 of 11** — by *building more of the SDK surface*, not by surfacing trade-offs. Mechanism not isolated: plan-time capability enumeration, persistence against the check gate, and ~1.8× time-on-task are all live candidates. |
+| **SDK compliance** — chat / moderation / push slices | ➖ **No claim** (7/9 vs 6/9; push +1, below the registered ≥+2 margin) | Brief-explicit behaviors tie, as pre-registered. One level down the defects are *symmetric*: 2/3 control cells shipped ban gates reading a field that doesn't exist on the real SDK (compiles, never fires; 0/3 Vise cells) — while 2/3 Vise cells over-parameterized `targetType` and never bound the brief's value, plausibly steered by Vise's own rule. |
+| **Design conformance** — ambiguous brief, brand-token usage | ⚠️ **Withheld on a technicality** | By-name token usage **+18.1 points** for the contract+check loop (90.3 vs 72.2 mean) ✓ — but the second registered condition (hex literals strictly *lower*) tied at 0–0, so the claim is withheld and reported descriptively. Vise controls are reused from an earlier round (cross-temporal). |
+
+**Registered negative results** (the protocol requires these in any publication of the matrix):
+
+- **Push stop-condition non-convergence.** Where docs and SDK disagree (push registration — the docs themselves carry a gap warning), "iterate until `vise check` is green" did not converge within the 30-minute cap in *any* Vise cell: agents looped on attestation dialect. Shipped behavior still passed 3/3 — the cost is wall-clock, not correctness. (2/3 control cells also hit the cap doing SDK archaeology.)
+- **Scope-omit affordance unused.** No agent in any cell used the `// vise: scope-omit` surfacing marker or wrote a qualifying scope note. The advisory surfacing mechanism, as shipped in 0.14.1, influenced zero cells.
+- Unchanged from prior rounds: **no Vise advantage on day-2 bug fixes**; **enumerative plan-time design guidance** measured negative twice and was retracted in 0.14.1.
+
+All Capability Matrix findings are directional at n=3 under one model and one executor — not settled statistics.
+
+---
+
 ## Supported Platforms
 
 | Platform | Coverage | Sensors |
@@ -386,11 +409,12 @@ jobs:
 
 | Code | Meaning |
 |---|---|
-| `0` | All rules pass (deterministic or attested) |
+| `0` | All rules pass and all expected capabilities are either present or opted-out |
 | `1` | One or more rules need attestation |
 | `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 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 = "Advisory completeness — NEVER fails `vise check`. Build each missing capability, or opt out with a recorded reason: `// vise: scope-omit <id> <reason>`.";
+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/outcomes.js

@@ -517,6 +517,13 @@ const addFeed = {
                     "requiredInputs.target screen or route",
                 ],
             },
+            {
+                step: "Bind targetType and targetId in createPost (and query) calls to the intake-resolved feed target — e.g. communityId from route params, userId from auth context, or a prop passed from the screen's caller. A variable or prop that is declared but never wired to the actual target is the same intent gap as a hardcoded literal: the validator fires on literals; the correctness gap fires on unbound variables.",
+                evidence: [
+                    "requiredInputs.concrete feed target",
+                    "requiredInputs.feed scope",
+                ],
+            },
             {
                 step: "Fetch the canonical social/feed docs and use platform-appropriate live collection patterns.",
                 evidence: [
@@ -524,6 +531,13 @@ const addFeed = {
                     "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview",
                 ],
             },
+            {
+                step: "Wire feed pagination: after the initial page loads, expose a 'Load more' action (button, scroll trigger, or infinite-query) that calls the collection's next-page method (loadMore() / nextPage() / onNextPage()). Check hasMore / hasNextPage before showing the control so it disappears when the list is exhausted. Use only opaque cursor tokens returned by the SDK — never construct numeric page offsets. On React/TypeScript, useAmityElement with an infinite-query hook is the idiomatic pattern; on Flutter, a ScrollController + loadMore callback; on Android, PagingData with a LazyColumn scroll trigger.",
+                evidence: [
+                    "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview",
+                    "requiredInputs.feed scope",
+                ],
+            },
             {
                 step: "When repairing or refactoring a feed query, preserve existing pagination inputs and state (for example pageToken, nextPage, hasMore/loadMore, or infinite-query wiring) unless the customer explicitly changes feed behavior.",
                 evidence: [
@@ -531,6 +545,13 @@ const addFeed = {
                     "implementationRules.file-specific edits",
                 ],
             },
+            {
+                step: "If the feed includes a post composer, support image/file attachments: (1) let the user pick a file, (2) upload it with FileRepository.uploadImage(file) — returns a File object with a fileId, (3) pass the fileId in the attachments array of createPost: `PostRepository.createPost({ ..., attachments: [{ fileId, fileType: 'image' }] })`. Display the uploaded image in the new post using the returned fileUrl. A composer that shows an image picker but never calls uploadImage, or calls uploadImage but discards the fileId and omits attachments, produces a broken upload flow — both halves must be present.",
+                evidence: [
+                    "social-plus-sdk/social/content-management/posts/creation/image-post",
+                    "social-plus-sdk/core-concepts/file-handling/upload",
+                ],
+            },
             { step: "Reuse the host app's existing visual system for the social surface.", evidence: designEvidence },
             { step: "Implement loading, empty, error, and data states.", evidence: ["implementationRules.file-specific edits"] },
             {
@@ -569,6 +590,13 @@ const addFeed = {
                 step: "If the feed includes poll posts, render each answer by branching on answer.dataType: for 'text' use answer.data directly as a string (PollAnswer.data is the text, not an object); for 'image' render answer.image?.fileUrl. Support voting via PollRepository.votePoll(pollId, [answerId]) and PollRepository.unvotePoll(pollId). When poll.status === 'closed' or poll.isVoted is true, display voteCount percentage bars instead of vote buttons. Show the poll's time status from poll.closedAt (when it ended) or poll.closedIn (when it will end) so users know if voting is open.",
                 evidence: ["social-plus-sdk/social/content-management/posts/creation/poll-post"],
             },
+            {
+                step: "If the post composer supports poll creation, implement the two-step creation chain: (1) `PollRepository.createPoll({ question, answers: [{ data: text }], answerType: 'single'|'multiple', closedIn? })` — returns a Poll with a pollId; (2) `PostRepository.createPost({ targetType, targetId, data: { text: '', pollId } })` — links the poll to the feed post. Rendering poll answers (votePoll/unvotePoll) is the read-side; without both creation steps the poll composer silently does nothing. Offer a dedicated poll-builder UI (question input + dynamic answer list) so users can author polls inline.",
+                evidence: [
+                    "social-plus-sdk/social/content-management/posts/creation/poll-post",
+                    "social-plus-sdk/social/posts",
+                ],
+            },
             {
                 step: "In post card headers, show the post's target context when post.targetType === 'community': display 'Author.displayName › Community.displayName' by subscribing to CommunityRepository.getCommunity(post.targetId, cb) for the live community name.",
                 evidence: ["social-plus-sdk/social/communities", "social-plus-sdk/social/posts"],

package/dist/tools/compliance.js

@@ -375,6 +375,7 @@ export async function checkCompliance(repoPath) {
                     recommendation: finding?.recommendation,
                     rationale: rule.rationale,
                     current_rule: ruleSummary(rule),
+                    ...(failStatus === "attestation-needed" && rule.enforcement.attestation.allowed && attestHint(rule)),
                 });
                 continue;
             }
@@ -385,11 +386,12 @@ export async function checkCompliance(repoPath) {
                 const sourceFingerprintStatus = await checkSourceFingerprints(repoRoot, inspection.effectiveRoot, attestation.source_fingerprints ?? []);
                 const staleFingerprints = sourceFingerprintStatus.filter((item) => item.status !== "match");
                 if (staleFingerprints.length > 0) {
+                    const fingerprintStatus = rule.advisory ? "advisory" : rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail";
                     results.push({
                         ruleId: rule.id,
                         title: rule.title,
                         severity: rule.severity,
-                        status: rule.advisory ? "advisory" : rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail",
+                        status: fingerprintStatus,
                         reason: rule.advisory
                             ? "Advisory: informational only — does not affect compliance status."
                             : "Recorded attestation source fingerprints changed. Re-check the evidence and record a fresh attestation.",
@@ -398,6 +400,7 @@ export async function checkCompliance(repoPath) {
                         rationale: rule.rationale,
                         current_rule: ruleSummary(rule),
                         source_fingerprint_status: sourceFingerprintStatus,
+                        ...(fingerprintStatus === "attestation-needed" && rule.enforcement.attestation.allowed && attestHint(rule)),
                     });
                     continue;
                 }
@@ -442,7 +445,8 @@ export async function checkCompliance(repoPath) {
             finding,
             recommendation: finding?.recommendation,
             current_rule: ruleSummary(rule),
-            ...(isInferential && { inferential_prompt: rule.enforcement.inferential?.prompt })
+            ...(isInferential && { inferential_prompt: rule.enforcement.inferential?.prompt }),
+            ...(baseStatus === "attestation-needed" && rule.enforcement.attestation.allowed && attestHint(rule)),
         });
     }
     const summary = summarize(results);
@@ -450,12 +454,13 @@ export async function checkCompliance(repoPath) {
     const hasDeterministicFailure = results.some((result) => result.status === "deterministic-fail");
     // "advisory" status is intentionally excluded — advisory rules surface but never block.
     const needsAttestation = results.some((result) => result.status === "attestation-needed" || result.status === "stale");
-    // Precedence: blocked (exit 3) > deterministic-failures (2) > needs-attestation (1) > green (0).
+    // 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.
-    // Advisory feature-completeness — surfaced but NEVER part of status/exitCode
-    // (completeness is a "this is missing" claim, structurally FP-prone; see the
-    // validation-boundaries principle). Failure to assess is silently ignored.
+    // 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 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;
     // surfacing a smaller failure first would distract from the real blocker.
     return {
@@ -465,8 +470,10 @@ export async function checkCompliance(repoPath) {
                 ? "deterministic-failures"
                 : needsAttestation
                     ? "needs-attestation"
-                    : "green",
-        exitCode: hasBlocked ? 3 : hasDeterministicFailure ? 2 : needsAttestation ? 1 : 0,
+                    : hasCompletenessGap
+                        ? "completeness-gap"
+                        : "green",
+        exitCode: hasBlocked ? 3 : hasDeterministicFailure ? 2 : needsAttestation ? 1 : hasCompletenessGap ? 5 : 0,
         outcome: compliance.outcome,
         surfacePath: compliance.surface?.path,
         summary,
@@ -519,7 +526,20 @@ export async function attestRule(args) {
     const rules = await rulesById();
     const rule = rules.get(args.ruleId);
     if (!rule || !compliance.rules.some((ref) => ref.rule_id === args.ruleId)) {
-        throw new Error(`Rule is not applicable in this compliance contract: ${args.ruleId}`);
+        // Collect up to 8 applicable attestable rule ids from this contract for the error hint. Prefer
+        // ids that share the bad id's non-wildcard prefix so the agent can narrow down quickly.
+        const attestableIds = compliance.rules
+            .map((ref) => rules.get(ref.rule_id))
+            .filter((r) => r !== undefined && r.enforcement.attestation.allowed);
+        const prefix = args.ruleId.replace(/\.\*$|\*$/, "");
+        const prefixed = prefix !== args.ruleId ? attestableIds.filter((r) => r.id.startsWith(prefix) || r.id.includes(prefix)) : [];
+        const candidates = prefixed.length > 0 ? prefixed : attestableIds;
+        const hintIds = candidates.slice(0, 8).map((r) => r.id);
+        const hintSuffix = hintIds.length > 0 ? ` Applicable attestable rules: ${hintIds.join(", ")}.` : " Applicable attestable rules: none.";
+        const preamble = args.ruleId.includes("*")
+            ? `Wildcards are not supported — attest one rule at a time.`
+            : `Rule is not applicable in this compliance contract: ${args.ruleId}.`;
+        throw new Error(`${preamble}${hintSuffix}`);
     }
     if (!rule.enforcement.attestation.allowed) {
         throw new Error(`Rule does not allow attestation: ${args.ruleId}`);
@@ -626,6 +646,16 @@ function ruleRef(rule) {
 function ruleRefForFile(rule) {
     return { ...ruleRef(rule), title: rule.title };
 }
+// Benchmark-measured friction: agents looped on attest dialect for ~25 min/cell when docs and SDK
+// disagreed on exact invocation syntax (capability-matrix 2026-06, Row 5). Hand them the exact incantation.
+function attestHint(rule) {
+    const minConfidence = rule.enforcement.attestation.host_agent_min_confidence ?? "high";
+    const fields = rule.enforcement.attestation.evidence_required ?? [];
+    return {
+        attest_command: `vise attest --rule ${rule.id} --confidence ${minConfidence} --signer host-agent --evidence-file sp-vise/evidence/${rule.id}.json --rationale "<why this rule is satisfied (or cannot apply) in this codebase>"`,
+        evidence_template: Object.fromEntries(fields.map((f) => [f.field, `<${f.description}>`])),
+    };
+}
 function contractDrift(compliance, rules) {
     const results = [];
     const refs = compliance.rules.map((ref) => {
@@ -661,6 +691,7 @@ function contractDrift(compliance, rules) {
                 status: "stale",
                 reason,
                 current_rule: ruleSummary(rule),
+                ...(rule.enforcement.attestation.allowed && attestHint(rule)),
             });
         }
     }

package/dist/tools/integration.js

@@ -135,7 +135,7 @@ function completenessChecklistFor(outcome) {
         return undefined;
     }
     return {
-        note: "Build each capability, or opt out with `// vise: scope-omit <id> <reason>`. `vise check` reports present/missing/opted-out (advisory — never fails the check).",
+        note: "Build each capability, or opt out with `// vise: scope-omit <id> <reason>`. Missing items that are neither built nor opted-out cause `vise check` to exit `completeness-gap` (exit code 5) — treat them as a stop condition.",
         capabilities: items,
     };
 }

package/dist/tools/project.js

@@ -2993,7 +2993,7 @@ function validateFeedTargetTypeExplicit(root, platform, sourceContent) {
                 }
             }
             if (flagged) {
-                findings.push(finding(ruleId, "warning", `A createPost call appears to hardcode targetType to a literal community or user.`, rel, "Feed targets should be passed dynamically (e.g. from props or intent extras) so the composer component is reusable. If this is intentional, add comment // vise: target-type rationale — <reason>."));
+                findings.push(finding(ruleId, "warning", `A createPost call appears to hardcode targetType to a literal community or user.`, rel, "Feed targets must be bound to the intake-resolved target — the community ID from route params, the user ID from auth context, or a prop passed from the caller. Do not leave targetType as a free variable or default enum value: the intent is to wire it to 'requiredInputs.concrete feed target', not simply to avoid a literal. If this is intentional, add comment // vise: target-type rationale — <reason>."));
                 break;
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -67,7 +67,7 @@
     "test:sdk-facts": "npm run build && node test/run-sdk-facts.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:e2e-package": "npm run build && node test/run-e2e-package.mjs",
-    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:design-brief && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:sdk-surface && npm run test:sdk-facts && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run pack:check",
+    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:design-brief && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:sdk-surface && npm run test:sdk-facts && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run bench:symbols-drift && npm run pack:check",
     "test:ast": "node test/run-ast-helpers.mjs",
     "test:design-extract": "npm run build && node test/run-design-extract.mjs",
     "test:design-brief": "npm run build && node test/run-design-brief.mjs",

package/rules/feed.yaml

@@ -1110,6 +1110,7 @@
     {
       "id": "typescript.posts.parent-child-rendered",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Post rendering for TypeScript must account for child posts (images/videos)",
       "severity": "warning",
       "rationale": "TypeScript UI components for Posts must recursively render or inspect post.children. If a component only renders the parent post's data.text, it will silently drop attached images and videos.",
@@ -1146,6 +1147,7 @@
     {
       "id": "react-native.posts.parent-child-rendered",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Post rendering for React Native must account for child posts (images/videos)",
       "severity": "warning",
       "rationale": "React Native components for Posts must recursively render or inspect post.children. If a component only renders the parent post's data.text, it will silently drop attached images and videos.",
@@ -1182,6 +1184,7 @@
     {
       "id": "android.posts.parent-child-rendered",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Post rendering for Android must account for child posts (images/videos)",
       "severity": "warning",
       "rationale": "Android Compose/RecyclerView components for Posts must render or inspect the child items (post.children). If a component only renders the parent post's text, it will silently drop attached images and videos.",
@@ -1218,6 +1221,7 @@
     {
       "id": "flutter.posts.parent-child-rendered",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Post rendering for Flutter must account for child posts (images/videos)",
       "severity": "warning",
       "rationale": "Flutter Widgets for Posts must render or inspect the child posts (post.children). If a widget only renders the parent post's data.text, it will silently drop attached images and videos.",
@@ -1254,6 +1258,7 @@
     {
       "id": "ios.posts.parent-child-rendered",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Post rendering for iOS must account for child posts (images/videos)",
       "severity": "warning",
       "rationale": "iOS SwiftUI/UIKit views for Posts must inspect the child posts (post.children). If a view only renders the parent post's text, it will silently drop attached images and videos.",
@@ -1290,6 +1295,7 @@
     {
       "id": "typescript.feed.target-type-explicit",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Explicit targetType for TypeScript createPost calls must not be hardcoded to COMMUNITY",
       "severity": "warning",
       "rationale": "TypeScript feed targets must be passed dynamically (e.g. from props or state), not hardcoded as AmityPostTargetType.COMMUNITY.",
@@ -1326,6 +1332,7 @@
     {
       "id": "react-native.feed.target-type-explicit",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Explicit targetType for React Native createPost calls must not be hardcoded to COMMUNITY",
       "severity": "warning",
       "rationale": "React Native feed targets must be passed dynamically (e.g. from props or state), not hardcoded as AmityPostTargetType.COMMUNITY.",
@@ -1362,6 +1369,7 @@
     {
       "id": "android.feed.target-type-explicit",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Explicit targetType for Android createPost calls must not be hardcoded to COMMUNITY",
       "severity": "warning",
       "rationale": "Android feed targets must be passed dynamically (e.g. from Intent extras or ViewModel state), not hardcoded as AmityPostTargetType.COMMUNITY.",
@@ -1398,6 +1406,7 @@
     {
       "id": "flutter.feed.target-type-explicit",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Explicit targetType for Flutter createPost calls must not be hardcoded to COMMUNITY",
       "severity": "warning",
       "rationale": "Flutter feed targets must be passed dynamically (e.g. from Widget properties), not hardcoded as AmityPostTargetType.COMMUNITY.",
@@ -1434,6 +1443,7 @@
     {
       "id": "ios.feed.target-type-explicit",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Explicit targetType for iOS createPost calls must not be hardcoded to COMMUNITY",
       "severity": "warning",
       "rationale": "iOS feed targets must be passed dynamically (e.g. from View state or initializer), not hardcoded as AmityPostTargetType.community.",
@@ -1470,6 +1480,7 @@
     {
       "id": "typescript.reactions.configured-name-used",
       "version": 2,
+      "symbol_anchored": true,
       "title": "TypeScript reaction name matches console config",
       "severity": "warning",
       "advisory": true,
@@ -1508,6 +1519,7 @@
     {
       "id": "react-native.reactions.configured-name-used",
       "version": 2,
+      "symbol_anchored": true,
       "advisory": true,
       "title": "React Native reaction name matches console config",
       "severity": "warning",
@@ -1546,6 +1558,7 @@
     {
       "id": "android.reactions.configured-name-used",
       "version": 2,
+      "symbol_anchored": true,
       "advisory": true,
       "title": "Android reaction name matches console config",
       "severity": "warning",
@@ -1584,6 +1597,7 @@
     {
       "id": "flutter.reactions.configured-name-used",
       "version": 2,
+      "symbol_anchored": true,
       "advisory": true,
       "title": "Flutter reaction name matches console config",
       "severity": "warning",
@@ -1622,6 +1636,7 @@
     {
       "id": "ios.reactions.configured-name-used",
       "version": 2,
+      "symbol_anchored": true,
       "advisory": true,
       "title": "iOS reaction name matches console config",
       "severity": "warning",
@@ -1660,6 +1675,7 @@
     {
       "id": "typescript.custom-post-type.dataType-declared",
       "version": 1,
+      "symbol_anchored": true,
       "title": "TypeScript custom post must declare dataType",
       "severity": "warning",
       "rationale": "When creating a post with a custom data payload, the 'dataType' tag must be explicitly provided so the SDK can route it correctly. If missing, it defaults to a text post, which stringifies the payload.",
@@ -1696,6 +1712,7 @@
     {
       "id": "react-native.custom-post-type.dataType-declared",
       "version": 1,
+      "symbol_anchored": true,
       "title": "React Native custom post must declare dataType",
       "severity": "warning",
       "rationale": "When creating a post with a custom data payload, the 'dataType' tag must be explicitly provided so the SDK can route it correctly. If missing, it defaults to a text post, which stringifies the payload.",
@@ -1732,6 +1749,7 @@
     {
       "id": "android.custom-post-type.dataType-declared",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Android custom post must declare dataType",
       "severity": "warning",
       "rationale": "When creating a post with a custom data payload, the 'dataType' tag must be explicitly provided so the SDK can route it correctly. If missing, it defaults to a text post, which stringifies the payload.",
@@ -1768,6 +1786,7 @@
     {
       "id": "flutter.custom-post-type.dataType-declared",
       "version": 1,
+      "symbol_anchored": true,
       "title": "Flutter custom post must declare dataType",
       "severity": "warning",
       "rationale": "When creating a post with a custom data payload, the 'dataType' tag must be explicitly provided so the SDK can route it correctly. If missing, it defaults to a text post, which stringifies the payload.",
@@ -1804,6 +1823,7 @@
     {
       "id": "ios.custom-post-type.dataType-declared",
       "version": 1,
+      "symbol_anchored": true,
       "title": "iOS custom post must declare dataType",
       "severity": "warning",
       "rationale": "When creating a post with a custom data payload, the 'dataType' tag must be explicitly provided so the SDK can route it correctly. If missing, it defaults to a text post, which stringifies the payload.",

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

@@ -37,6 +37,8 @@ vise run-sensors .
 
 **`vise check .` is mandatory, not optional. You are not done until it passes or every finding is explicitly attested.** Running `vise plan` and `vise inspect` but skipping `vise check` is the most common failure mode — it means the deterministic catch-net never ran and known-bad patterns ship. When you read a `vise plan`, do not truncate it (`| head` drops the implementation steps); read the full `implementationSteps` array.
 
+**Completeness is also a stop condition.** When `vise check .` exits with status `completeness-gap` (exit code 5), one or more expected capabilities are neither implemented nor opted-out. 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 capability that is neither built nor opted-out is a silent drop — the check will not pass green until every 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.
 
 In CI or pull-request pipelines, use `vise check . --ci`. It is read-only, exits non-zero unless compliance is green, and never writes deterministic-pass records; use `vise sync` only during the implementation loop after a local green check.
@@ -242,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. This is **advisory — it never fails the check**; it exists so completeness doesn't depend on your memory. 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 silently drop a capability. `vise check`'s `completeness` section will keep nudging on anything that's neither built nor 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: