@amityco/social-plus-vise 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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).
 
+## 1.2.0 — 2026-06-18
+
+Adds advisory **solution-path / UIKit routing** and a fail-closed fix to the SwiftPM manifest sensor. No change to `vise check` exit codes, compliance rules, or sidecar **formats**; the one behavior change is the SwiftPM-timeout outcome noted under Changed.
+
+### Added
+- **Solution-path & UIKit routing (advisory).** `vise plan` emits `solutionPath` (`sdk` · `uikit` · `hybrid` · `needs-decision`) so an agent pauses for `--answer solution_path=…` before building the wrong layer, cleanly separating the two integrator postures (SDK/custom-UI vs UIKit/prebuilt-UI). When UIKit is in play it also emits `uikitCustomization`, recommending the lowest-effort tier that meets the goal (Dynamic UI → Component Styling → Localization → Behavior Overrides → Fork and Extend → SDK Custom UI). Both are **advisory only** — they never change outcome classification, compliance rules, the sidecar schema, or `vise check` exit codes. Documented under "Solution path & UIKit routing" in the README; the two postures are described in `docs/PERSONAS.md`.
+- **Real-build readiness checks** surfaced alongside the routing signals.
+
+### Changed
+- **SwiftPM manifest sensor: timeout is now RED (fail-closed), not a skip.** A manifest-parse timeout previously read as a clean green; for a pure-SwiftPM iOS project the manifest sensor is the only sensor, so a stall masqueraded as success. It now reports `timed-out` and the CLI exits non-zero. **Behavior note for consumers:** a network-restricted CI runner that cannot resolve a remote SwiftPM dependency will now go RED on this sensor rather than silently passing — intended fail-closed behavior, not a regression.
+- **Advisory routing engines hardened (two adversarial-verification batches, 28 fixes, every fix mutation-verified).** `recommendSolutionPath` / `recommendUIKitCustomization` precision: UIKit-rejection coverage now spans modal/contracted negators (won't/can't/cannot), intervening verbs ("don't want to use UIKit", "without using UIKit"), and "anything but UIKit" — an explicit rejection routes SDK-first instead of (previously) recommending UIKit; prebuilt idioms are anchored to a UI/social noun; `off-the-shelf` is anchored (so "off-the-shelf analytics" stays SDK-first); localization no longer fires on a programming/design "language"; backend feature capabilities (e.g. livestreaming) surface as a decision rather than a Dynamic-UI default. Advisory-only quality improvements; no gate behavior changes.
+- **Personas split into two integrator postures** (AI-Assisted SDK/Custom-UI Integrator and AI-Assisted UIKit/Prebuilt-UI Adopter), tied to a deterministic behavior contract in the test suite.
+
 ## 1.1.1 — 2026-06-16
 
 Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.

package/README.md

@@ -47,7 +47,7 @@ It turns the request into a grounded plan, records a local contract under `sp-vi
 
 > 🔒 **Your source code never leaves your machine.** Vise fetches only the public social.plus docs and the SDK's published version on npm — never your code, file contents, or search queries. `VISE_DOCS_OFFLINE=1` runs fully offline.
 
-Vise can also run **ahead** of that loop: an advisory [Engagement Intelligence](#engagement-intelligence) layer turns a product goal into a candidate engagement design — *what to build*, not only *whether you built it right*.
+Vise can also run **ahead** of that loop: an advisory [Engagement Intelligence](#engagement-intelligence) layer turns a product goal into multiple candidate engagement strategies — *what you might build*, not only *whether you built it right*.
 
 > **Why "Vise"?** A bench vise holds the workpiece steady so the craftsman's hands are free to shape it. Vise clamps the integration to the real docs, the real project structure, and the real compliance rules so the agent can focus on building instead of guessing.
 
@@ -98,12 +98,18 @@ Prefer a per-project install? `npm install -D @amityco/social-plus-vise`, then c
 ## How it works
 
 1. **Inspect** — `vise inspect` detects the platform, app surfaces, available sensors, and design signals from the local repo.
-2. **Plan** — `vise plan --request "..."` classifies the outcome, cites docs, and raises blocking intake and design-preview questions. The agent surfaces them; you answer.
+2. **Plan** — `vise plan --request "..."` classifies the outcome, cites docs, and raises blocking intake and design-preview questions. Use `--summary` when you only need the route/intake readout before implementation. The agent surfaces questions; you answer.
 3. **Initialize** — `vise init` writes the `sp-vise/` compliance contract. While blocking questions are unanswered it refuses, returns `status: "needs-clarification"`, and exits 7 — the agent must ask instead of guessing.
 4. **Build** — the agent edits your code, grounded by `vise search-docs` and `vise get-doc-page`.
 5. **Check & repair** — `vise check` reports deterministic findings, completeness gaps, and attestation needs. The agent fixes findings or records attestations with evidence, looping until green.
 6. **Sense** — `vise run-sensors` runs your project's own typecheck/build/lint/SDK smokes. Done means the contract and evidence are committed, not just that the agent stopped.
 
+### Solution path & UIKit routing (advisory)
+
+Some requests are better served by **social.plus UIKit** (prebuilt social surfaces) than by hand-rolling standard UI directly from SDK primitives. `vise plan` emits an advisory **`solutionPath`** — `sdk`, `uikit`, `hybrid`, or `needs-decision` — so an agent can pause for `--answer solution_path=uikit|sdk|hybrid` before it builds the wrong layer. This separates the two integrator postures cleanly: an **SDK / custom-UI** build (differentiated, direct-SDK) stays SDK-first, a **UIKit / prebuilt-UI** adoption (standard surfaces, fast launch) routes to UIKit, and a genuinely mixed request resolves to `needs-decision` rather than silently picking one. A request that *rejects* UIKit ("don't use UIKit", "we can't use UIKit") routes SDK-first, and a request that names a backend feature capability (e.g. livestreaming) is surfaced as a decision rather than a UIKit-customization default.
+
+When UIKit is in play, `vise plan` can also emit **`uikitCustomization`**, recommending the lowest-effort customization tier that meets the goal — Dynamic UI → Component Styling → Localization → Behavior Overrides → Fork and Extend → SDK Custom UI. Both signals are **advisory only**: they never change outcome classification, compliance rules, the sidecar schema, or `vise check` exit codes.
+
 ### Three validation layers
 
 The layer is set by the *kind of claim*, which is how Vise is designed to avoid false positives where it gates:
@@ -120,9 +126,9 @@ Correctness is gated by deterministic rules or attestations; completeness is gat
 
 ### Engagement Intelligence
 
-**Advisory, in preview.** The three layers above answer *whether you built it right*. Ahead of the build, Vise can also help decide *what to build*: an **Engagement Intelligence** layer turns a product goal into a candidate **engagement design** — archetypes, UX patterns, and solution variants drawn from a social.plus experience catalog — then compiles the chosen variant into an implementation plan (`vise creative` → `vise creative accept` → `vise experience compile`), optionally bridging to installable social.plus blocks, plus advisory UX expectations and a multi-dimension experience review.
+**Advisory, in preview.** The three layers above answer *whether you built it right*. Ahead of the build, Vise can also help reason about *what to build*: an **Engagement Intelligence** layer turns a product goal into multiple candidate **engagement strategies** — archetypes, UX patterns, and solution variants drawn from a social.plus experience catalog — with rationale, tradeoffs, no-fit guidance, availability boundaries, and review gaps. The human or driving agent still chooses the direction, then Vise compiles that selected variant into an implementation plan (`vise creative` → `vise creative accept` → `vise experience compile`), optionally bridging to installable social.plus blocks, plus advisory UX expectations and a multi-dimension experience review.
 
-It is **local-only, never uploads, carries no calibrated score** (a calibration program is in progress), and **never changes `vise check`'s exit codes**. Use it to shape the work; the validation layers still decide when it's done.
+It is **local-only, never uploads, carries no calibrated score**, and **never changes `vise check`'s exit codes**. The opt-in ranking preview is review context, not a top-1 confidence claim or autonomous product-strategy selector. Use it to shape the work; the validation layers still decide when it's done.
 
 ### Design contracts
 
@@ -143,6 +149,8 @@ The mechanism is the durable claim: a checked loop beats the same rules in the p
 
 **Feed completeness (capabilities selected):** when the optional capabilities — image, poll, edit — are selected up front, the Vise arm completed **97–100%** of an 11-item feed checklist across three agents (Cursor/Composer, Claude/Sonnet, Codex/GPT). This is *absolute* completeness from answering Vise's capability questions — **not** a lift over a baseline.
 
+**Engagement Intelligence advisory quality:** a 24-case held-out dogfood set supports the advisory positioning: expected available strategies surfaced in **17/17** cases, multiple strategy options were visible in **20/20** strategy-offer cases, rationale/tradeoff evidence was visible in **24/24**, and no-fit plus availability-gated cases preserved their boundaries. The same run retained **4 ranking-calibration concerns**, so this is **not** a claim of top-1 ranking confidence, autonomous strategy selection, business-outcome lift, or a calibrated score.
+
 **Boundaries:** these are social.plus's own measurements on greenfield work — self-reported, no third-party audit, measured on earlier builds, and not universal claims. Negative results travel with them: no measured advantage on day-2 bug fixing, and the design-conformance arms were measured at different times (the figure is the robust by-name-token signal, not pixel perfection).
 
 <sub>Cursor, Claude, Codex, GitHub Copilot, VS Code, and other product names are trademarks of their respective owners; social.plus is not affiliated with or endorsed by them. Benchmark figures are from social.plus's own measurements.</sub>
@@ -155,7 +163,7 @@ The mechanism is the durable claim: a checked loop beats the same rules in the p
 | **React Native** | ✅ Full | `tsc`, `npm lint`, SDK import smoke |
 | **Flutter / Dart** | ✅ Full | `flutter analyze`, `flutter test` |
 | **Android (Kotlin)** | ✅ Full | Gradle assemble, unit tests |
-| **iOS (Swift)** | ✅ Full | Static rules fully operational (tree-sitter AST for highest-risk rules); build sensor is guarded best-effort — runs only when `xcodebuild` is available, reports environment issues as skipped-with-reason, and still fails on real build errors |
+| **iOS (Swift)** | ✅ Full | Static rules fully operational (tree-sitter AST for highest-risk rules); `Package.swift` enables a SwiftPM manifest sensor, and `.xcodeproj`/`.xcworkspace` enables a guarded `xcodebuild` sensor when available |
 
 Each platform has dozens of rules across 10 compliance domains (feed, comments, moderation, chat, secrets, session & auth, notifications, live objects, logging hygiene, design tokens).
 
@@ -169,7 +177,8 @@ Run `vise <command> --help` for full flags. JSON output is the default for agent
 |---|---|
 | `vise doctor` | Verify install; print version, install path, docs source |
 | `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
-| `vise plan [path] --request "..."` | Grounded implementation plan with intake questions and docs citations |
+| `vise plan [path] --request "..." [--summary]` | Grounded implementation plan with intake questions and docs citations; `--summary` prints a compact route/intake view |
+| `vise plan --summary "..."` | Shortcut for quick routing dogfood or discovery when the current directory is the repo |
 | `vise plan-harness [path] --request "..."` | Pre-planning step: build the harness around the request |
 | `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract once blocking intake is answered; exits 7 (`needs-clarification`) otherwise |
 | `vise workplan next [path] --request "..."` | For broad social requests: print the next uncompleted surface and its focused commands |
@@ -180,7 +189,7 @@ Run `vise <command> --help` for full flags. JSON output is the default for agent
 
 | Command | Purpose |
 |---|---|
-| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview]` | Write an advisory Engagement Intelligence brief with candidate solution variants; `--ranking-preview` adds an opt-in, local-only ranking preview that never reorders the default candidates |
+| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview]` | Write an advisory Engagement Intelligence brief with multiple candidate solution variants, rationale, tradeoffs, and review gaps; `--ranking-preview` adds opt-in, local-only review context that never reorders the default candidates |
 | `vise creative accept [path] --variant <id>` | Record the selected variant so `plan`/`init`/`workplan` carry it forward; `--variant none --rationale "..."` records a catalog-gap signal instead |
 | `vise ux-harness [path]` | Generate advisory UX expectations from the accepted selection |
 | `vise experience compile [path]` | Compile the accepted variant into an implementation artifact plan |
@@ -189,7 +198,7 @@ Run `vise <command> --help` for full flags. JSON output is the default for agent
 | `vise learning record [path]` | Append a local-only learning event; refreshes the learning summary |
 | `vise learning show [path]` | Read the local learning summary (never changes recommendations) |
 
-Everything in this group is local and advisory: no uploads, no `vise check` exit-code changes, no auto-accepted variants, and no calibrated score until the calibration program graduates one.
+Everything in this group is local and advisory: no uploads, no `vise check` exit-code changes, no auto-accepted variants, no top-1 confidence claim, and no calibrated score.
 
 ### Design contract
 
@@ -299,7 +308,7 @@ Vise writes local planning, compliance, design, and evidence artifacts under `sp
 | `sp-vise/inspection.json` | `vise init` | Platform, surface, and design signals detected at init |
 | `sp-vise/attestations/*.json` | `vise sync` / `vise attest` | Per-rule evidence: signer, confidence, rationale, source fingerprints for drift detection |
 | `sp-vise/creative-brief.json` + `creative-brief.md` | `vise creative` | Advisory brief: goals, archetypes, candidate variants (JSON + human-readable) |
-| `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local ranking preview; `experience_score: null`, no uploads, no default-order change |
+| `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local ranking preview for review context; `experience_score: null`, no uploads, no default-order change, no top-1 confidence claim |
 | `sp-vise/creative-selection.json` | `vise creative accept` | Accepted variant and plan/workplan feed-forward context |
 | `sp-vise/catalog-gap.json` | `vise creative accept --variant none` | Local-only no-fit signal for human catalog review |
 | `sp-vise/ux-harness.json` | `vise creative accept` or `vise ux-harness` | Advisory UX pattern expectations and anti-patterns |

package/dist/server.js

@@ -285,12 +285,16 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "plan" || command === "plan-integration") {
-            await printToolResult(planIntegrationTool, {
-                repoPath: positionalRepoPath(args.slice(1)),
-                request: requiredFlagValue(args, "request", "plan requires --request."),
-                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
-                answers: keyValueFlag(args, "answer"),
-            });
+            const input = await planCliInput(args);
+            if (hasFlag(args, "summary")) {
+                const result = await planIntegrationTool.call(input);
+                const text = result.content.map((item) => item.text).join("\n");
+                const payload = JSON.parse(text);
+                console.log(JSON.stringify(planSummary(payload), null, 2));
+            }
+            else {
+                await printToolResult(planIntegrationTool, input);
+            }
             return "exit";
         }
         if (command === "plan-harness") {
@@ -583,7 +587,9 @@ Create the evidence-backed implementation packet before editing code.
 
 Usage:
   vise plan [repoPath] --request "Add a social feed"
+  vise plan --summary "Use UIKit for a standard feed"
   vise plan apps/web --request "Create posts" --surface apps/web
+  vise plan . --request "Use UIKit for a standard feed" --summary
 
 Re-plan with collected answers (repeat --answer for each intake question):
   vise plan . --request "Add a social feed" \\
@@ -993,6 +999,33 @@ async function printToolResult(tool, input) {
     console.log(text);
     return { result, text };
 }
+async function planCliInput(args) {
+    const subArgs = args.slice(1);
+    const requestFromFlag = flagValue(args, "request");
+    if (requestFromFlag) {
+        return {
+            repoPath: positionalRepoPath(subArgs),
+            request: requestFromFlag,
+            surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+            answers: keyValueFlag(args, "answer"),
+        };
+    }
+    const positional = positionalValues(subArgs);
+    const [first, ...rest] = positional;
+    if (!first) {
+        throw new Error("plan requires --request or a quoted request argument.");
+    }
+    const firstLooksLikePath = await pathExists(first);
+    if (firstLooksLikePath && rest.length === 0) {
+        throw new Error("plan requires --request when the only positional argument is a repository path.");
+    }
+    return {
+        repoPath: firstLooksLikePath ? first : ".",
+        request: firstLooksLikePath ? rest.join(" ").trim() : positional.join(" ").trim(),
+        surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+        answers: keyValueFlag(args, "answer"),
+    };
+}
 function toolResultStatus(printed) {
     try {
         const payload = JSON.parse(printed.text);
@@ -1002,6 +1035,125 @@ function toolResultStatus(printed) {
         return undefined;
     }
 }
+function planSummary(payload) {
+    const solutionPath = objectProp(payload, "solutionPath");
+    const uikitCustomization = objectProp(payload, "uikitCustomization");
+    const intake = objectProp(payload, "intake");
+    const answers = objectProp(intake, "answers") ?? {};
+    const workplan = objectProp(payload, "socialWorkplan");
+    const questions = arrayProp(intake, "questions").map(questionSummary);
+    const decisionsRequired = stringArrayProp(payload, "decisionsRequired");
+    const solutionPathAnswerId = stringProp(solutionPath, "answerId");
+    const uikitCustomizationAnswerId = stringProp(uikitCustomization, "answerId");
+    return stripUndefined({
+        kind: "plan-summary",
+        outcome: stringProp(payload, "outcome"),
+        platform: stringProp(payload, "platform"),
+        supportLevel: stringProp(payload, "supportLevel"),
+        solutionPath: solutionPath
+            ? {
+                recommendation: stringProp(solutionPath, "recommendation"),
+                confidence: stringProp(solutionPath, "confidence"),
+                summary: stringProp(solutionPath, "summary"),
+                answerId: solutionPathAnswerId,
+                decisionRequired: booleanProp(objectProp(solutionPath, "decision"), "requiredBeforeHandRolledUi") === true
+                    && !hasAnswerValue(answers, solutionPathAnswerId),
+            }
+            : undefined,
+        uikitCustomization: uikitCustomization
+            ? {
+                status: stringProp(uikitCustomization, "status"),
+                recommendedLevel: stringProp(uikitCustomization, "recommendedLevel"),
+                confidence: stringProp(uikitCustomization, "confidence"),
+                summary: stringProp(uikitCustomization, "summary"),
+                answerId: uikitCustomizationAnswerId,
+                decisionRequired: booleanProp(objectProp(uikitCustomization, "decision"), "requiredBeforeCustomization") === true
+                    && !hasAnswerValue(answers, uikitCustomizationAnswerId),
+            }
+            : undefined,
+        intake: intake
+            ? {
+                status: stringProp(intake, "status"),
+                remainingBlocking: numberProp(intake, "remainingBlocking"),
+                blockingQuestions: questions.filter((question) => question.blocksImplementationWhenMissing),
+                openQuestions: questions,
+                answers,
+            }
+            : undefined,
+        decisionsRequired,
+        workplan: workplan ? workplanSummary(workplan) : undefined,
+        nextStep: stringProp(payload, "nextStep"),
+    });
+}
+function hasAnswerValue(answers, answerId) {
+    if (!answerId) {
+        return false;
+    }
+    const answer = answers[answerId];
+    return typeof answer === "string" && answer.trim() !== "";
+}
+function workplanSummary(workplan) {
+    return stripUndefined({
+        kind: stringProp(workplan, "kind"),
+        status: stringProp(workplan, "status"),
+        nextStep: stringProp(workplan, "nextStep"),
+        surfaces: arrayProp(workplan, "sequence").map((surface) => {
+            const surfaceObject = asObject(surface);
+            const intake = objectProp(surfaceObject, "intake");
+            return stripUndefined({
+                id: stringProp(surfaceObject, "id"),
+                order: numberProp(surfaceObject, "order"),
+                outcome: stringProp(surfaceObject, "outcome"),
+                label: stringProp(surfaceObject, "label"),
+                remainingBlocking: numberProp(intake, "remainingBlocking"),
+                intakeStatus: stringProp(intake, "status"),
+            });
+        }),
+    });
+}
+function questionSummary(value) {
+    const question = asObject(value);
+    return {
+        id: stringProp(question, "id"),
+        question: stringProp(question, "question"),
+        required: booleanProp(question, "required"),
+        blocksImplementationWhenMissing: booleanProp(question, "blocksImplementationWhenMissing"),
+    };
+}
+function objectProp(value, key) {
+    if (!value) {
+        return undefined;
+    }
+    return asObject(value[key]);
+}
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function arrayProp(value, key) {
+    if (!value) {
+        return [];
+    }
+    const item = value[key];
+    return Array.isArray(item) ? item : [];
+}
+function stringArrayProp(value, key) {
+    return arrayProp(value, key).filter((item) => typeof item === "string");
+}
+function stringProp(value, key) {
+    const item = value?.[key];
+    return typeof item === "string" ? item : undefined;
+}
+function numberProp(value, key) {
+    const item = value?.[key];
+    return typeof item === "number" ? item : undefined;
+}
+function booleanProp(value, key) {
+    const item = value?.[key];
+    return typeof item === "boolean" ? item : undefined;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
 async function installSkill(args) {
     const source = skillSourceDir();
     const instructionInstall = instructionInstallDestination(args);
@@ -1438,7 +1590,12 @@ function ciCheckResult(result) {
     };
 }
 function positionalRepoPath(args) {
+    const values = positionalValues(args);
+    return values[0] ?? ".";
+}
+function positionalValues(args) {
     const flagsWithValues = new Set(["request", "requirements", "prototype", "variant", "variant-id", "brief", "brief-path", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference", "registry", "block", "package-source", "note", "kind", "sentiment", "metric"]);
+    const values = [];
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -1454,9 +1611,18 @@ function positionalRepoPath(args) {
         if (arg.startsWith("-")) {
             continue;
         }
-        return arg;
+        values.push(arg);
+    }
+    return values;
+}
+async function pathExists(input) {
+    try {
+        await stat(path.resolve(expandHome(input)));
+        return true;
+    }
+    catch {
+        return false;
     }
-    return ".";
 }
 function requiredPositionalText(args, message) {
     const values = [];

package/dist/solutionPath.js

@@ -0,0 +1,274 @@
+const UIKIT_SIGNALS = [
+    {
+        id: "explicit-uikit",
+        label: "Explicit social.plus UIKit / UI Kit mention",
+        strength: "strong",
+        pattern: /\b(?:social\.plus\s+)?(?:ui\s?kit|uikit)\b(?!\s+(?:experience|expertise|knowledge|background|familiarity))/i,
+    },
+    {
+        id: "prebuilt-components",
+        label: "Prebuilt or ready-made social UI components",
+        strength: "strong",
+        pattern: /\b(pre[-\s]?built|ready[-\s]?made)\b|\b(?:ready[-\s]?to[-\s]?use|out[-\s]?of[-\s]?the[-\s]?box|plug[-\s]?and[-\s]?play|drop[-\s]?in|off[-\s]?the[-\s]?shelf)\b(?:\s+(?:social\.plus|social|messaging|message|notifications?|community|communities|chat|feeds?|profiles?|stor(?:y|ies)|comments?|users?|groups?|channels?|posts?|prebuilt|standard|ui\s?kit|uikit))?\s+(?:ui|ui\s?kit|uikit|components?|widgets?|screens?|views?|feed|chat|profile|comments?|communit(?:y|ies)|stor(?:y|ies)|surfaces?)\b/i,
+    },
+    {
+        id: "speed-to-launch",
+        label: "Launch speed / MVP pressure",
+        strength: "medium",
+        pattern: /\b(quick launch|launch quickly|ship quickly|ship fast|mvp|build (?:a |an |the )?prototype|prototype (?:quickly|fast|first)|rapid prototyp\w*|weeks not months|days not months|save (?:development|dev|build|engineering) time|reduce development time)\b/i,
+    },
+    {
+        id: "standard-layout",
+        label: "Standard social app layout or white-label surface",
+        strength: "medium",
+        pattern: /\b(standard social|standard layout|standard feed|standard chat|standard profile|white[-\s]?label|basic styling|minimal customization|moderate customization|brand colors only)\b/i,
+    },
+    {
+        id: "uikit-customization-ladder",
+        label: "UIKit customization mode",
+        strength: "medium",
+        pattern: /\b(dynamic ui|component styling|fork and extend|forked ui\s?kit|fork the ui\s?kit|customi[sz]e the ui\s?kit)\b/i,
+    },
+];
+const REJECT_NEGATOR = "do not|don't|dont|won't|wont|can't|cant|cannot|avoid|skip|no|without|not|never";
+const REJECT_CONNECTOR = "to|use|uses|using|used|want|wants|wanting|adopt|adopts|adopting|leverage|leveraging|rely|relying|touch|build|building|go|going|be|been|with|on";
+const REJECT_UIKIT_NOUN = "(?:the\\s+)?(?:social\\.plus\\s+)?(?:ui\\s?kit|uikit)\\b";
+const REJECT_SKILL_LOOKAHEAD = "(?!\\s+(?:experience|expertise|knowledge|background|familiarity))";
+const REJECT_UIKIT_SOURCE = `\\b(?:${REJECT_NEGATOR})(?:\\s+(?:${REJECT_CONNECTOR}))*\\s+${REJECT_UIKIT_NOUN}${REJECT_SKILL_LOOKAHEAD}` +
+    `|\\b(?:instead of|rather than)(?:\\s+(?:${REJECT_CONNECTOR}))*\\s+${REJECT_UIKIT_NOUN}` +
+    `|\\b(?:anything|everything)\\s+but\\s+${REJECT_UIKIT_NOUN}`;
+const NEGATED_FROM_SCRATCH = /\b(?:not|never|avoid|don't|dont|do not|rather than|instead of)\b[\s\w,]{0,16}?\bfrom scratch\b/i;
+const NEGATED_STANDARD = /\b(?:not|never|avoid|don't|dont|do not|rather than|instead of)\b[\s\w,]{0,12}?\b(?:standard social|standard layout|standard feed|standard chat|standard profile|white[-\s]?label|basic styling|minimal customization|moderate customization)\b/i;
+const SDK_SIGNALS = [
+    {
+        id: "direct-sdk",
+        label: "Direct SDK implementation",
+        strength: "strong",
+        pattern: /\b(?:directly|direct|using|use|with|via|embed|embedding|integrate|integrating)\s+(?:the\s+)?(?:social\.plus\s+)?SDK\b|\b(?:the\s+)?(?:social\.plus\s+)?SDK\s+for\b|\bSDK[-\s]?owned\b|\bSDK[-\s]?custom\b/i,
+    },
+    {
+        id: "reject-uikit",
+        label: "Explicitly rejects UIKit or chooses SDK instead of UIKit",
+        strength: "strong",
+        pattern: new RegExp(REJECT_UIKIT_SOURCE, "i"),
+    },
+    {
+        id: "custom-ui",
+        label: "Custom UI or non-standard experience",
+        strength: "strong",
+        pattern: /\b(?:custom|bespoke|unique|fully[-\s]?custom|completely[-\s]?custom|totally[-\s]?(?:different|custom)|brand[-\s]?new|differentiated)\s+(?:(?:social|messaging|notification|community|chat|feed|profile|story|stories|comment|comments|user|group|channel|post|navigation|onboarding|discovery)\s+)?(?:ui|interface|experience)\b|\bnon[-\s]?standard (?:ui|layout|flow|experience)\b|\bpixel[-\s]?perfect\b/i,
+    },
+    {
+        id: "custom-flows",
+        label: "Custom user flows or interactions",
+        strength: "strong",
+        pattern: /\b(custom flows?|custom user flows?|custom interactions?|custom workflows?|unique flows?|bespoke flows?|special interaction)\b/i,
+    },
+    {
+        id: "full-control",
+        label: "Full control / design freedom",
+        strength: "strong",
+        pattern: /\b(full control|complete control|maximum flexibility|complete design freedom|full design freedom|build from scratch|hand[-\s]?rolled|from scratch)\b/i,
+    },
+    {
+        id: "deep-app-integration",
+        label: "Deep existing-app integration",
+        strength: "medium",
+        pattern: /\b(deeply integrate|existing app flow|existing navigation|custom backend|server[-\s]?to[-\s]?server|non[-\s]?standard platform|advanced technical requirements)\b/i,
+    },
+];
+const SOURCE_EVIDENCE = [
+    "social.plus UIKit docs: prebuilt UI components, quick launch, and minimal/moderate customization paths.",
+    "social.plus SDK docs: custom experiences, unique user flows, complete design freedom, and existing-app integration.",
+];
+export function recommendSolutionPath(request, answers = {}) {
+    const text = typeof request === "string" ? request : "";
+    const explicitAnswer = normalizeSolutionPathAnswer(answers?.solution_path);
+    const sdkSignals = collectSignals(text, SDK_SIGNALS).filter((signal) => {
+        if (signal.id !== "full-control" || !/scratch/i.test(signal.matched)) {
+            return true;
+        }
+        return !NEGATED_FROM_SCRATCH.test(text);
+    });
+    const negativeUIKitSignals = sdkSignals.filter((signal) => signal.id === "reject-uikit");
+    let uikitScanText = text;
+    if (negativeUIKitSignals.length > 0) {
+        uikitScanText = text.replace(new RegExp(REJECT_UIKIT_SOURCE, "gi"), " ");
+    }
+    let uikitSignals = collectSignals(uikitScanText, UIKIT_SIGNALS).filter((signal) => {
+        if (signal.id !== "standard-layout") {
+            return true;
+        }
+        return !NEGATED_STANDARD.test(text);
+    });
+    if (negativeUIKitSignals.length > 0 && !uikitSignals.some((signal) => signal.strength === "strong")) {
+        uikitSignals = [];
+    }
+    if (explicitAnswer) {
+        return guidanceFor({
+            recommendation: explicitAnswer,
+            confidence: "high",
+            uikitSignals,
+            sdkSignals,
+            answered: explicitAnswer,
+        });
+    }
+    const hasStrongUIKit = uikitSignals.some((signal) => signal.strength === "strong");
+    const hasStrongSdk = sdkSignals.some((signal) => signal.strength === "strong");
+    if (uikitSignals.length > 0 && sdkSignals.length > 0) {
+        return guidanceFor({
+            recommendation: "needs-decision",
+            confidence: hasStrongUIKit || hasStrongSdk ? "medium" : "low",
+            uikitSignals,
+            sdkSignals,
+        });
+    }
+    if (uikitSignals.length > 0) {
+        return guidanceFor({
+            recommendation: "uikit",
+            confidence: hasStrongUIKit ? "high" : "medium",
+            uikitSignals,
+            sdkSignals,
+        });
+    }
+    if (sdkSignals.length > 0) {
+        return guidanceFor({
+            recommendation: "sdk",
+            confidence: hasStrongSdk ? "high" : "medium",
+            uikitSignals,
+            sdkSignals,
+        });
+    }
+    return guidanceFor({
+        recommendation: "sdk",
+        confidence: "medium",
+        uikitSignals,
+        sdkSignals,
+    });
+}
+function guidanceFor(args) {
+    const decision = {
+        requiredBeforeHandRolledUi: !args.answered && (args.recommendation === "uikit" || args.recommendation === "hybrid" || args.recommendation === "needs-decision"),
+        question: "Should this build use social.plus UIKit components, a direct SDK implementation, or a hybrid path?",
+        options: [
+            "uikit: use social.plus UIKit for standard social surfaces and theme/customize it",
+            "sdk: build the experience directly with the social.plus SDK",
+            "hybrid: use UIKit for standard surfaces and SDK/custom code for differentiated app-layer behavior",
+        ],
+    };
+    if (args.recommendation === "uikit") {
+        return {
+            recommendation: "uikit",
+            confidence: args.confidence,
+            summary: args.answered === "uikit"
+                ? "The customer explicitly selected the UIKit path. Confirm scope, then use social.plus UIKit as the primary implementation artifact instead of hand-rolling standard social UI."
+                : "The request sounds UIKit-shaped: favor social.plus UIKit for the standard social surface, then customize within the UIKit theming/component model before considering direct SDK UI.",
+            answerId: "solution_path",
+            signals: { uikit: args.uikitSignals, sdk: args.sdkSignals },
+            decision,
+            implementationGuidance: [
+                "Confirm `solution_path=uikit` before the host agent hand-rolls standard feed, chat, profile, comments, community, or story UI.",
+                "Use UIKit installation, authentication, customization, and platform build guidance as the implementation source of truth.",
+                "Keep Vise's existing SDK setup, secrets, region, auth, build, and project-sensor guidance around the UIKit integration.",
+                "Do not claim deterministic compliance for UIKit internals hidden outside the customer repo; validate customer wiring, configuration, custom code, and local build evidence.",
+                "Keep design conformance advisory: use Dynamic UI, component styling, or fork-and-extend based on the customer's customization need.",
+            ],
+            evidence: SOURCE_EVIDENCE,
+            advisoryOnly: "This is an advisory solution-path recommendation. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+        };
+    }
+    if (args.recommendation === "needs-decision") {
+        return {
+            recommendation: "needs-decision",
+            confidence: args.confidence,
+            summary: args.answered === "hybrid"
+                ? "The customer selected a hybrid path. Treat UIKit as the default for standard surfaces and use direct SDK/custom code only for the differentiated behavior."
+                : "The request contains both UIKit-shaped speed/prebuilt signals and SDK-shaped custom-control signals. Ask for the solution path before the agent starts UI implementation.",
+            answerId: "solution_path",
+            signals: { uikit: args.uikitSignals, sdk: args.sdkSignals },
+            decision,
+            implementationGuidance: [
+                "Resolve `solution_path` before hand-rolling standard social UI.",
+                "Choose UIKit when the standard social surface can be themed or lightly customized.",
+                "Choose SDK when the requested workflow, layout, or interaction model is materially different from UIKit's component model.",
+                "Choose hybrid when UIKit can cover baseline social surfaces and SDK/custom code is needed for app-specific extensions.",
+                "Do not claim deterministic compliance for UIKit internals hidden outside the customer repo; validate customer wiring, configuration, custom code, and local build evidence.",
+            ],
+            evidence: SOURCE_EVIDENCE,
+            advisoryOnly: "This is an advisory solution-path recommendation. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+        };
+    }
+    if (args.recommendation === "hybrid") {
+        return {
+            recommendation: "hybrid",
+            confidence: args.confidence,
+            summary: "The customer selected a hybrid path. Treat UIKit as the default for standard surfaces and use direct SDK/custom code only for the differentiated behavior.",
+            answerId: "solution_path",
+            signals: { uikit: args.uikitSignals, sdk: args.sdkSignals },
+            decision,
+            implementationGuidance: [
+                "Use UIKit for standard social surfaces that fit its component and customization model.",
+                "Use direct SDK/custom code only for differentiated app-layer behavior, custom profile/discovery surfaces, or non-standard flows.",
+                "Keep the handoff explicit in the implementation summary: name which surfaces are UIKit-owned and which are SDK/customer-owned.",
+                "Do not claim deterministic compliance for UIKit internals hidden outside the customer repo; validate customer wiring, configuration, custom code, and local build evidence.",
+            ],
+            evidence: SOURCE_EVIDENCE,
+            advisoryOnly: "This is an advisory solution-path recommendation. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+        };
+    }
+    return {
+        recommendation: "sdk",
+        confidence: args.confidence,
+        summary: args.answered === "sdk"
+            ? "The customer explicitly selected the direct SDK path. Continue with the normal Vise SDK integration harness."
+            : args.sdkSignals.some((signal) => signal.id === "reject-uikit")
+                ? "The request explicitly rejects UIKit or chooses the SDK instead of UIKit, so the normal SDK-first Vise harness is the safer fit."
+                : args.sdkSignals.length > 0
+                    ? "The request asks for custom control, unique flows, or deep app integration, so the normal SDK-first Vise harness is the safer fit."
+                    : "No strong UIKit fast-launch/prebuilt-surface signal was detected, so Vise keeps the existing SDK-first integration flow.",
+        answerId: "solution_path",
+        signals: { uikit: args.uikitSignals, sdk: args.sdkSignals },
+        decision,
+        implementationGuidance: [
+            "Use the normal Vise SDK integration flow: plan, answer intake, initialize the compliance contract, implement, check, and run sensors.",
+            "If the customer later asks for a standard prebuilt social surface or quick-launch MVP, re-plan with `--answer solution_path=uikit` or a UIKit-specific request.",
+        ],
+        evidence: SOURCE_EVIDENCE,
+        advisoryOnly: "This is an advisory solution-path recommendation. It does not change outcome classification, compliance rules, sidecar schema, or `vise check` exit codes.",
+    };
+}
+function collectSignals(request, signals) {
+    return signals.flatMap((signal) => {
+        const match = request.match(signal.pattern);
+        if (!match?.[0]) {
+            return [];
+        }
+        return [{
+                id: signal.id,
+                label: signal.label,
+                strength: signal.strength,
+                matched: match[0],
+            }];
+    });
+}
+const REJECT_UIKIT_IN_ANSWER = new RegExp(REJECT_UIKIT_SOURCE, "i");
+const REJECT_HYBRID_IN_ANSWER = /\b(?:not|no|without|avoid|don't|dont|do not|never|rather than|instead of)\b[\s\w,]{0,12}?\bhybrid\b/;
+function normalizeSolutionPathAnswer(answer) {
+    const normalized = (typeof answer === "string" ? answer : "").trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (/\bhybrid\b/.test(normalized) && !REJECT_HYBRID_IN_ANSWER.test(normalized)) {
+        return "hybrid";
+    }
+    if (REJECT_UIKIT_IN_ANSWER.test(normalized)) {
+        return "sdk";
+    }
+    if (/\b(ui\s?kit|uikit)\b/.test(normalized)) {
+        return "uikit";
+    }
+    if (/\bsdk\b/.test(normalized)) {
+        return "sdk";
+    }
+    return undefined;
+}