@amityco/social-plus-vise 0.14.25 → 0.14.27

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.27 — 2026-06-10
+
+**Theme:** social-plus-forge monorepo move. No runtime behavior changes.
+
+### Changed
+- **Repository metadata:** the package now lives in the `vise/` module of the [social-plus-forge monorepo](https://github.com/AmityCo/social-plus-forge); `repository` (with `directory: vise`), `homepage`, and `bugs` URLs updated from the retired `social-plus-foundry`/`social-plus-vise` repos.
+- **Tarball slimmed 1.9 MB → ~0.5 MB:** `social.plus-vise.png` is no longer shipped in the npm package (it was 79% of the install and never referenced by the README).
+
+### Fixed
+- **`ajv` declared as a devDependency:** it was imported by the catalog-schema gate and `scripts/catalog-sheets.mjs` but rode in transitively under npm's flat hoisting; pnpm's strict layout surfaced the gap.
+
+### Docs
+- Backfilled the `vise blocks` installer namespace into the `0.14.5` changelog entry (shipped there, never recorded).
+- `RELEASE.md` no longer hardcodes the current npm version; `RULES.md`/`ARCHITECTURE.md` defer exact rule counts to the rule-coverage gate.
+
+## 0.14.26 — 2026-06-06
+
+### Added
+- **Creative selection bridge:** `vise creative accept --variant <id>` / MCP `creative_accept` now persists `sp-vise/creative-selection.json` from a chosen creative brief candidate.
+- **Plan/init/workplan feed-forward:** matching `vise plan`, `vise init`, and `vise workplan next/status` runs now read accepted creative selections, add a `creativeContext` block, prepend a selected-variant implementation step, mirror the selection into `sp-vise/intake.json`, and derive multi-surface workplan order from selected experience objects.
+
+### Verified
+- Expanded `test:creative` to cover creative accept, selection sidecar writes, plan feed-forward, creative-derived workplan ordering, init sidecar mirroring, and MCP `creative_accept` smoke coverage.
+
 ## 0.14.25 — 2026-06-06
 
 ### Added
@@ -208,6 +232,9 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/
 
 **Theme:** Optional feed capabilities become explicit opt-in sensors.
 
+### Added
+- *(backfilled 2026-06-10 — shipped in this release but was never recorded)* **Block installer namespace:** `vise blocks list / plan / add / validate` (PR #143). Reads a social.plus Block Factory registry, plans safe package/source-anchor/sidecar changes, applies them behind `--dry-run`/`--apply`, writes `sp-vise/blocks.json`, and validates installed block state and drift.
+
 ### Changed
 - **Add-feed completeness baseline narrowed to pagination:** image upload, poll creation, and edit post are no longer baseline completeness requirements. The add-feed `completenessChecklist` now gates pagination / load-more only.
 - **Optional feed capabilities require explicit opt-in:** `vise plan` now offers image upload, poll creation, and edit post as `optionalCapabilities`. When the user selects one and the agent carries it into `vise init --answer feed_optional_capabilities=...`, `vise check` runs selected source sensors and exits `selected-capability-failures` (exit code 6) until the selected capability is implemented.

package/README.md

@@ -83,7 +83,9 @@ Correctness is gated by deterministic rules or attestations. Baseline completene
 
 ### Engagement Intelligence roadmap
 
-Vise's next architecture track is the social.plus **Engagement Intelligence System**: an outcome-to-experience layer that maps customer goals, archetypes, solution patterns, experience objects, UX patterns, and variants before normal implementation planning. The first advisory runtime slice is `vise creative`: it consumes a request plus optional requirements/prototype inputs, or runs in exploratory mode when requirements are absent, then writes a local creative brief for user variant selection. See [docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md](docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md), [docs/MONOREPO_ARCHITECTURE.md](docs/MONOREPO_ARCHITECTURE.md), and [packages/intelligence](packages/intelligence).
+Vise's next architecture track is the social.plus **Engagement Intelligence System**: an outcome-to-experience layer that maps customer goals, archetypes, solution patterns, experience objects, UX patterns, and variants before normal implementation planning. The first advisory runtime slice is `vise creative`: it consumes a request plus optional requirements/prototype inputs, or runs in exploratory mode when requirements are absent, writes a local creative brief for user variant selection, and records the accepted variant so `vise plan`, `vise init`, and `vise workplan` can carry that product/UX direction forward. See [docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md](docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md), [docs/MONOREPO_ARCHITECTURE.md](docs/MONOREPO_ARCHITECTURE.md), and [packages/intelligence](packages/intelligence).
+
+The current milestone is the **Learning Engine sensor bridge with score calibration guardrails**. After creative selection, experience compilation, and sensor review, Vise can keep local learning events that snapshot the selected variant, outcome, Experience Report, and Experience Sensor Framework, then summarize recurring review gaps by variant, outcome, and dimension. The shadow calibration track now has 70 measured cells, including a v2 independent candidate-ranking matrix that ranked the expected variant first in 21/21 registered cells while preserving visible review gaps. The v2 human gate has named product FP/FN and privacy sign-off recorded, including approval that `event-first` beats `creator-first` in the five thin-margin cross-platform cells. Gate 2 exposes this evidence only as an explicit `vise creative --ranking-preview` local advisory preview; the current local dogfood pass covers 18 synthetic prompts spanning ten archetypes and all ten catalog variants (seven available, three gamification variants gated as in-development). Of the 14 available-variant cases, 13 align and 1 is a declared near-miss — in the opt-in preview only, the shadow-policy-v2-draft ranking ranks `live-commerce` just above `discovery-first` for an ecommerce social-discovery prompt, while the brief's keyword default and the agent both pick the human-correct `discovery-first` — with 0 undeclared ranking concerns and 0 candidate-surfacing gaps; the other 4 gamification cases are correctly gated. The paired `live-shopping-stream` control (a clear live-selling prompt) shows the preview correctly elevating `live-commerce` over the keyword default. There are still no uploads, no changed `vise check` exit codes, no calibrated single score, no auto-acceptance, and no default recommendation ranking. See [docs/UX_HARNESS_MVP.md](docs/UX_HARNESS_MVP.md), [docs/LEARNING_ENGINE_MVP.md](docs/LEARNING_ENGINE_MVP.md), [docs/EXPERIENCE_SCORE_CALIBRATION.md](docs/EXPERIENCE_SCORE_CALIBRATION.md), and [docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md](docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md).
 
 ### Relationship to social.plus Block Factory
 
@@ -165,15 +167,17 @@ Aggregate: **98/99 expected feed capabilities** and **27/27 selected optional ca
 
 ### Current Release Validation
 
-Version 0.14.25 carries current release proof around the full feed-forward, product-expectation, creative pre-planning, and validation flow:
+Version 0.14.26 carries current release proof around the full feed-forward, product-expectation, creative pre-planning, and validation flow:
 
 | Surface | What was validated |
 |---|---|
 | **Creative pre-planning** | `vise creative` produces requirements-driven or exploratory Engagement Intelligence briefs, writes `sp-vise/creative-brief.json` / `.md`, asks for `preferred_solution`, and survives packed-package installation with the intelligence catalog bundled. |
+| **Creative selection bridge** | `vise creative accept --variant <id>` writes `sp-vise/creative-selection.json` and `sp-vise/ux-harness.json`; matching `vise plan`, `vise init`, and `vise workplan next` runs surface the accepted variant, UX expectations, derive workplan surfaces from its experience objects, and mirror the selection into `sp-vise/intake.json`. |
 | **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 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`. |
+| **Experience Score calibration guard** | Experience Report, Experience Sensors, and Learning Engine snapshots keep `score: null`, while `learning-summary.json` keeps `recommendationOptimization.status: "not-active"`. The shadow benchmark has 70 measured cells; `shadow-policy-v2-draft` independently ranked expected variants first in 21/21 registered ranking/cross-platform cells, its human gate package has named product FP/FN and privacy sign-off recorded, and runtime exposure is limited to the opt-in local `vise creative --ranking-preview` artifact. |
 | **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. |
@@ -186,6 +190,7 @@ Version 0.14.25 carries current release proof around the full feed-forward, prod
 | **Feature completeness** | Vise helps agents build more of the expected SDK capability surface. | Latest comparison: **21-30% without Vise vs 97-100% with Vise**, with **98/99** expected feed capabilities implemented in aggregate. Earlier Capability Matrix work also showed silently dropped items falling from 7.67/11 to 4.0/11. |
 | **SDK compliance** | Vise checks catch greenfield SDK compliance gaps that docs or static guidance can miss. | Commune benchmark: Vise averaged **100% greenfield SDK compliance** where docs/RAG-style controls averaged **67%** across the reported slices. |
 | **Design conformance** | Vise design checks reduce design drift under ambiguous briefs. | Ambiguous Spotify-style design test: Vise design runs produced **0 / 0 / 0 hex literals** across three seeds; without Vise, runs varied **0 / 2 / 15**. This supports variance reduction, not pixel-perfect visual quality. |
+| **Candidate ranking calibration** | Vise can optionally preview `shadow-policy-v2-draft` ranking for surfaced creative variants, without changing default runtime recommendations. | Experience calibration track: **70 measured cells**. `shadow-policy-v2-draft` ranked the expected variant first in **21/21** cells, produced **14** improvement opportunities, has named product approval for **5** thin-margin event-first-over-creator-first cells plus named privacy approval for the benchmark evidence boundary, and is exposed only through explicit `--ranking-preview`. Current local dogfood has **18** prompts (ten archetypes, all **ten** variants — seven available, three gamification gated): of the **14** available-variant cases, **13** aligned and **1** declared near-miss (in the opt-in preview only; the keyword default and the agent both pick the human-correct variant), **0** undeclared ranking concerns, **0** candidate-surfacing gaps; the other **4** gamification cases are gated, and the paired positive control shows the preview correctly elevating the human-correct variant over the keyword default; default activation remains disabled. |
 
 ### Why the workflow works
 
@@ -303,7 +308,14 @@ The flow above is what the skill teaches your AI agent. You — the human — dr
 |---|---|
 | `vise doctor` | Verify install; print version, install path, docs source |
 | `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
-| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>]` | Produce an advisory Engagement Intelligence brief with 2-3 solution variants before normal implementation planning; writes `sp-vise/creative-brief.json` and `.md` unless `--no-write` is set |
+| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview]` | Produce an advisory Engagement Intelligence brief with 2-3 solution variants before normal implementation planning; `--ranking-preview` also writes an opt-in local candidate-ranking preview without changing the candidate order |
+| `vise creative accept [path] --variant <id>` | Accept a creative variant and write `sp-vise/creative-selection.json` so subsequent `plan`, `init`, and `workplan` runs include the selected product/UX direction. Use `--variant none --rationale "<what is missing>"` to instead record a local `sp-vise/catalog-gap.json` no-fit signal for human catalog review |
+| `vise ux-harness [path]` | Generate or refresh `sp-vise/ux-harness.json` from the accepted creative selection; advisory UX expectations only |
+| `vise experience compile [path]` | Compile the accepted creative variant into `sp-vise/experience-compiler.json`: install guidance, navigation placement, surface plans, UX expectations, Block Factory bridge candidates, design adaptation, and validation commands |
+| `vise experience sensors [path]` | Write `sp-vise/experience-sensors.json`, an advisory sensor framework across technical, design, UX, accessibility, and business-alignment dimensions; no calibrated score yet |
+| `vise experience-report [path]` | Write `sp-vise/experience-report.json`, an advisory dimensioned report for technical compliance, design, UX Harness evidence, and business alignment; no calibrated single score yet |
+| `vise learning record [path]` | Append a local-only learning event for explicit feedback, outcome metrics, or report review; refreshes `sp-vise/learning-summary.json` |
+| `vise learning show [path]` | Read the local learning summary; recommendation ranking is not changed by these events yet |
 | `vise plan [path] --request "..."` | Produce a grounded implementation plan with intake questions and docs citations |
 | `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 |
@@ -408,7 +420,7 @@ MCP-capable hosts can call Vise as structured tool calls instead of shell comman
 
 ### Tool names (snake_case per MCP convention)
 
-`inspect_project`, `creative_brief`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `resolve_request`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `suggest_patch`, `design_extract`, `design_check`, `design_preview`, `design_reference`, `design_init_tokens`.
+`inspect_project`, `creative_brief`, `creative_accept`, `ux_harness`, `compile_experience`, `experience_sensors`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `experience_report`, `record_learning`, `show_learning`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `resolve_request`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `suggest_patch`, `design_extract`, `design_check`, `design_preview`, `design_reference`, `design_init_tokens`.
 
 These are the same operations as the CLI commands above, exposed as MCP tools.
 
@@ -461,9 +473,18 @@ Vise writes local planning, compliance, design, and evidence artifacts under `sp
 | File | Created by | What it contains |
 |---|---|---|
 | `sp-vise/compliance.json` | `vise init` | The rules selected for this integration, the Vise version, the ruleset digest, the target app surface, selected optional capabilities, optional engagement link, and an accepted design-contract digest when confirmed. |
-| `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/intake.json` | `vise init` | The request, outcome, intake answers, remaining blocking count, optional creative-selection mirror, design-review status (`absent`, `needs-confirmation`, `accepted`, or `rejected`), and any retrospective `--allow-unresolved-intake` acknowledgement. |
 | `sp-vise/creative-brief.json` | `vise creative` | Advisory Engagement Intelligence brief: mode, objective, inferred goals/archetypes, candidate solution variants, feasibility summary, preferred-solution question, and next plan/workplan commands. |
 | `sp-vise/creative-brief.md` | `vise creative` | Human-readable version of the creative brief for review with the user before selecting a variant. |
+| `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local advisory ranking preview for the surfaced creative candidates using `shadow-policy-v2-draft`; preserves the original candidate order and writes `experience_score: null` with runtime boundary fields confirming no uploads, no auto-acceptance, and no default ranking change. |
+| `sp-vise/creative-selection.json` | `vise creative accept` | Accepted creative variant: source brief, selected goals/archetypes/patterns/objects/UX patterns, surface hints, feasibility notes, and plan/workplan feed-forward context. |
+| `sp-vise/catalog-gap.json` | `vise creative accept --variant none` | Recorded no-fit: the request the agent found no fitting variant for, what the catalog is missing, the nearest existing variant, and the grounding signal. A local-only signal for human catalog review — it does not accept a variant, change the catalog, or upload anything. |
+| `sp-vise/ux-harness.json` | `vise creative accept` or `vise ux-harness` | Advisory UX Harness: selected UX pattern expectations, tradeoffs, anti-patterns, surface expectations, and capability-feed-forward boundary notes. |
+| `sp-vise/experience-compiler.json` | `vise experience compile` | Advisory implementation artifact plan: install guidance, navigation placement, focused surface plans, UX expectations, optional Block Factory bridge candidates, design adaptation, and validation commands. |
+| `sp-vise/experience-sensors.json` | `vise experience sensors` | Advisory sensor framework: technical, design, UX, accessibility, and business-alignment evidence summary, review gaps, commands, and `score: null` until calibrated. |
+| `sp-vise/experience-report.json` | `vise experience-report` | Advisory dimensioned review artifact: technical compliance status, design contract presence, UX Harness evidence, business alignment, optional Experience Sensor snapshot, and `score: null` until calibrated by benchmark/dogfood evidence. |
+| `sp-vise/learning-events.jsonl` | `vise learning record` | Append-only local learning event log for explicit customer/reviewer feedback, outcome metrics, selected variant snapshots, outcome snapshots, Experience Report snapshots, and Experience Sensor snapshots. |
+| `sp-vise/learning-summary.json` | `vise learning record` | Derived local learning summary: feedback counts, variant feedback, metric keys, report/sensor snapshots, recurring review gaps by variant/outcome/dimension, and `recommendationOptimization.status: "not-active"`. |
 | `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, green-check evidence, snapshot paths, and optional host-agent notes. |

package/dist/capabilities.js

@@ -1168,7 +1168,7 @@ function symbolHaystack(symbols) {
     return [...new Set(values)];
 }
 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 = {
+export const BASELINE_CAPABILITY_IDS_BY_OUTCOME = {
     "add-feed": ["pagination"],
     "add-comments": ["comment-composer"],
     "add-chat": ["send-message", "read-state"],

package/dist/intelligence/grounding.js

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// Deterministic grounding contract for agent-driven variant selection (experience-factory rebuild,
+// Option A). The factory does NOT call a model: the driving coding agent performs the semantic
+// understanding (customer request -> variant) and hands the factory a selection. This module is the
+// factory's deterministic half — it enforces that the agent's selection is GROUNDED in the catalog
+// and surfaces honest review signals. It performs no inference and no IO in its core function, so it
+// is fully reproducible (the determinism lives here; the non-determinism lives in the visible driver).
+//
+// Contract, by evidence from the spike + stress test (benchmarks/experience-calibration/
+// semantic-understanding-spike.mjs and -stresstest.mjs):
+//   - variantId MUST be a catalog id, or the literal "none" (the agent's honest no-fit answer).
+//     Anything else is a hallucination and is REJECTED.
+//   - rationale is REQUIRED (explainability is a core principle of the factory).
+//   - confidence is expected (high|medium|low); low confidence and "none" are not failures — they are
+//     honest signals that the human/agent should reconsider or that the catalog may need a new variant.
+export const GROUNDING_SCHEMA_VERSION = "2026-06-07.vise-grounding.v1";
+export const NO_FIT = "none";
+const CONFIDENCE_VALUES = ["high", "medium", "low"];
+/**
+ * Validate an agent-provided variant selection against the catalog. Pure and deterministic: given the
+ * same selection and the same catalog id set it always returns the same result.
+ */
+export function groundSelection(selection, catalogVariantIds) {
+    const ids = [...catalogVariantIds];
+    const idSet = new Set(ids);
+    const signals = [];
+    const rawVariant = typeof selection?.variantId === "string" ? selection.variantId.trim() : "";
+    const rationale = typeof selection?.rationale === "string" ? selection.rationale.trim() : "";
+    const rawConfidence = typeof selection?.confidence === "string" ? selection.confidence.trim().toLowerCase() : "";
+    const isNoFit = rawVariant.toLowerCase() === NO_FIT;
+    const isKnownVariant = idSet.has(rawVariant);
+    // 1. Grounding: variant must be a catalog id or the explicit no-fit answer.
+    if (!isNoFit && !isKnownVariant) {
+        signals.push({
+            code: "hallucinated-variant",
+            severity: "error",
+            message: rawVariant
+                ? `Selected variant "${rawVariant}" is not in the catalog. The agent must choose a catalog id or "${NO_FIT}".`
+                : `No variant was provided. The agent must choose a catalog id or "${NO_FIT}".`,
+        });
+    }
+    else if (isNoFit) {
+        signals.push({
+            code: "no-fit",
+            severity: "warn",
+            message: `The agent reported no catalog variant fits this request. Reconsider the request, or treat this as a candidate for a new catalog variant.`,
+        });
+    }
+    // 2. Rationale is required for explainability (applies to a real variant and to "none").
+    if (!rationale) {
+        signals.push({
+            code: "missing-rationale",
+            severity: "error",
+            message: `A rationale is required: the selection must explain, grounded in the request and catalog, why this variant (or "${NO_FIT}") was chosen.`,
+        });
+    }
+    // 3. Confidence (advisory but expected). Invalid value is a contract violation; absence/low are signals.
+    let confidence = null;
+    if (!rawConfidence) {
+        signals.push({ code: "missing-confidence", severity: "warn", message: `No confidence was provided; expected one of ${CONFIDENCE_VALUES.join(", ")}.` });
+    }
+    else if (CONFIDENCE_VALUES.includes(rawConfidence)) {
+        confidence = rawConfidence;
+        if (confidence === "low" && isKnownVariant) {
+            signals.push({ code: "low-confidence", severity: "warn", message: `The agent was not confident in this selection; review before accepting.` });
+        }
+    }
+    else {
+        signals.push({ code: "invalid-confidence", severity: "error", message: `Confidence "${rawConfidence}" is invalid; expected one of ${CONFIDENCE_VALUES.join(", ")}.` });
+    }
+    const hasError = signals.some((s) => s.severity === "error");
+    const status = hasError ? "rejected" : signals.length > 0 ? "needs-review" : "grounded";
+    const variantId = hasError || isNoFit ? null : rawVariant;
+    return {
+        schemaVersion: GROUNDING_SCHEMA_VERSION,
+        status,
+        variantId,
+        confidence,
+        rationale: rationale || null,
+        signals,
+        catalogVariantIds: ids,
+        reason: summarize(status, variantId, signals),
+    };
+}
+function summarize(status, variantId, signals) {
+    if (status === "grounded")
+        return `Selection "${variantId}" is grounded in the catalog with a rationale.`;
+    if (status === "rejected")
+        return `Selection rejected: ${signals.filter((s) => s.severity === "error").map((s) => s.code).join(", ")}.`;
+    return `Selection accepted with review signals: ${signals.map((s) => s.code).join(", ")}.`;
+}
+/** Resolve the catalog directory shipped in the package (packages/intelligence/catalog). */
+export function catalogDir() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(moduleDir, "..", "..", "packages", "intelligence", "catalog");
+}
+/** Load the set of valid variant ids from the declarative catalog. */
+export async function loadCatalogVariantIds(dir = catalogDir()) {
+    const raw = await readFile(path.join(dir, "variants.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    const ids = (parsed.items ?? []).map((item) => item.id).filter((id) => typeof id === "string" && id.length > 0);
+    if (ids.length === 0)
+        throw new Error("No variant ids found in catalog variants.json");
+    return ids;
+}

package/dist/intelligence/placement.js

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// Display order — drives CREATIVE_SURFACE_HINTS and, downstream, surfaceSequence.
+export const SURFACE_REGISTRY = [
+    { id: "feed", outcome: "add-feed", label: "Feed and content surface" },
+    { id: "comments", outcome: "add-comments", label: "Comments and replies" },
+    { id: "chat", outcome: "add-chat", label: "Chat inbox and threads" },
+    { id: "profile", outcome: "add-follow", label: "Profile and relationship graph" },
+    { id: "community", outcome: "add-community", label: "Community management and identity" },
+    { id: "notifications", outcome: "add-notifications", label: "Notifications and activation" },
+];
+// Scan order for reducing an object list to its surfaces/outcomes. Kept distinct from the display
+// order above to reproduce the pre-derivation if-chain output byte-for-byte (community was scanned
+// before profile). Faithful-reproduction only; could be unified if order is proven immaterial.
+const SURFACE_SCAN_ORDER = ["feed", "comments", "chat", "community", "profile", "notifications"];
+const outcomeBySurface = new Map(SURFACE_REGISTRY.map((s) => [s.id, s.outcome]));
+const VALID_SURFACES = new Set(SURFACE_REGISTRY.map((s) => s.id));
+function catalogRoot() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(moduleDir, "..", "..", "packages", "intelligence", "catalog");
+}
+// object id -> surface / block, in catalog declaration order. Read synchronously at module load so
+// the SOCIAL_PLUS_OBJECTS export and the lookup functions stay synchronous (matches prior contract).
+const objectSurface = new Map();
+const objectBlock = new Map();
+{
+    const filePath = path.join(catalogRoot(), "experience-objects.json");
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    for (const item of parsed.items ?? []) {
+        if (typeof item.id !== "string")
+            continue;
+        if (typeof item.surface === "string") {
+            if (!VALID_SURFACES.has(item.surface)) {
+                throw new Error(`experience object "${item.id}" declares unknown surface "${item.surface}" (expected one of: ${[...VALID_SURFACES].join(", ")})`);
+            }
+            objectSurface.set(item.id, item.surface);
+        }
+        if (typeof item.block === "string") {
+            objectBlock.set(item.id, item.block);
+        }
+    }
+}
+// SDK-backed objects are exactly those placed on a surface; app-layer (knowledge/prediction) and
+// in-development objects declare no surface and are excluded.
+export const SOCIAL_PLUS_OBJECTS = new Set(objectSurface.keys());
+export function surfaceIdsForObjects(objectIds) {
+    const present = new Set(objectIds);
+    const surfacesPresent = new Set();
+    for (const id of present) {
+        const surface = objectSurface.get(id);
+        if (surface)
+            surfacesPresent.add(surface);
+    }
+    return SURFACE_SCAN_ORDER.filter((sid) => surfacesPresent.has(sid));
+}
+export function outcomesForObjects(objectIds) {
+    return surfaceIdsForObjects(objectIds).map((sid) => outcomeBySurface.get(sid));
+}
+export function blockIdForObject(objectId) {
+    return objectBlock.get(objectId);
+}
+// Object ids bound to a surface, in catalog declaration order (used to build CREATIVE_SURFACE_HINTS).
+export function surfaceObjectIds(surfaceId) {
+    const ids = [];
+    for (const [id, surface] of objectSurface) {
+        if (surface === surfaceId)
+            ids.push(id);
+    }
+    return ids;
+}

package/dist/outcomes.js

@@ -2,7 +2,7 @@ export function hasAnswer(answers, id) {
     const value = answers[id];
     return typeof value === "string" && value.trim() !== "";
 }
-const CLASSIFY_ORDER = [
+export const CLASSIFY_ORDER = [
     "setup-push",
     "setup-live-data",
     "add-comments",
@@ -1531,7 +1531,7 @@ const unknown = {
     resolveVerification: () => [],
     resolveNotes: () => [],
 };
-const outcomeRegistry = {
+export const outcomeRegistry = {
     "setup-sdk": setupSdk,
     "setup-push": setupPush,
     "setup-live-data": setupLiveData,