@amityco/social-plus-vise 1.1.0 → 1.2.0

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;
+}

package/dist/tools/harness.js

@@ -160,10 +160,38 @@ export async function detectCommandSensors(repoPath, platforms) {
         });
     }
     if (platforms.includes("ios")) {
+        sensors.push(...(await swiftPackageSensors(root)));
         sensors.push(...(await iosBuildSensors(root)));
     }
     return sensors;
 }
+async function swiftPackageSensors(root) {
+    if (!(await exists(path.join(root, "Package.swift")))) {
+        return [];
+    }
+    if (!(await commandOnPath("swift"))) {
+        return [
+            {
+                name: "iOS SwiftPM manifest",
+                command: ["swift"],
+                timing: "after-change",
+                purpose: "Parse the SwiftPM manifest after iOS SDK setup changes.",
+                source: "Package.swift",
+                skip: "Package.swift was detected, but swift is not on PATH in this environment. Install Xcode or Swift toolchain support to enable the SwiftPM manifest sensor; static iOS rule checks run regardless.",
+            },
+        ];
+    }
+    return [
+        {
+            name: "iOS SwiftPM manifest",
+            command: ["swift", "package", "describe", "--type", "json"],
+            timing: "after-change",
+            purpose: "Parse the SwiftPM manifest after iOS SDK setup changes without compiling or requiring simulator/signing assets.",
+            source: "Package.swift",
+            timeoutReason: "SwiftPM manifest parsing (`swift package describe`) did not finish before the sensor timeout. This is reported as a timeout (NOT a clean pass): a stall can be a slow toolchain OR an unresolvable/circular dependency. Static iOS rule checks still run; rerun with a longer `--timeout-ms` if the toolchain is just slow.",
+        },
+    ];
+}
 const XCODEBUILD_ENVIRONMENT_SKIPS = [
     {
         pattern: "requires Xcode|command line tools instance",
@@ -330,8 +358,8 @@ function assessHarnessability(platforms, commandSensors, designSignalCount) {
     if (designSignalCount > 0) {
         affordances.push(`Detected ${designSignalCount} design/theme signal(s) for UI integration grounding.`);
     }
-    if (platforms.includes("ios")) {
-        gaps.push("iOS: static compliance rules are fully operational. No build/compile sensor is wired yet (xcodebuild environment requirements make it fragile); run-sensors will return no-sensors for iOS projects.");
+    if (platforms.includes("ios") && commandSensors.length === 0) {
+        gaps.push("iOS: static compliance rules are fully operational, but no SwiftPM or Xcode command sensor was detected for this project root.");
     }
     if (platforms.length === 0) {
         return { level: "weak", affordances, gaps };

package/dist/tools/integration.js

@@ -10,6 +10,8 @@ import { detectCommandSensors } from "./harness.js";
 import { inspectProject } from "./project.js";
 import { creativeSurfaceHints, readCreativeSelection } from "./creative.js";
 import { buildUxHarness, uxHarnessPlanContext } from "./uxHarness.js";
+import { recommendSolutionPath } from "../solutionPath.js";
+import { recommendUIKitCustomization } from "../uikitCustomization.js";
 export const planIntegrationTool = {
     name: "plan_integration",
     description: "Create a grounded, evidence-backed implementation packet before an AI coding agent edits a customer project.",
@@ -72,7 +74,7 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
     const uxHarnessOutcome = BROAD_SOCIAL_REGEX.test(request) && !hasAnswer(answers, "feature_surface") ? undefined : outcome;
     const uxHarnessContext = uxHarness ? uxHarnessPlanContext(uxHarness, uxHarnessOutcome) : undefined;
     const platform = preferredPlatform(inspection.platforms);
-    const supportLevel = supportFor(outcome, platform);
+    const baseSupportLevel = supportFor(outcome, platform);
     const sensors = await detectCommandSensors(root, inspection.platforms);
     const ctx = planContextFor({
         request,
@@ -84,6 +86,9 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
     });
     const definition = getOutcomeDefinition(outcome);
     const capabilityAvailability = await platformCapabilityAvailability(outcome, platform);
+    const solutionPath = recommendSolutionPath(request, answers);
+    const uikitCustomization = recommendUIKitCustomization({ request, answers, platform, solutionPath });
+    const supportLevel = supportLevelForPlan(outcome, platform, baseSupportLevel, uikitCustomization);
     const designContract = await readDesignContract(repoRoot);
     const designReview = designReviewGuidance(repoRoot, designContract, answers);
     const acceptedDesignContract = designReview.status === "accepted" ? designContract : null;
@@ -108,6 +113,8 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
     const packageJsonText = await readFile(path.join(root, "package.json"), "utf8").catch(() => undefined);
     const sdkVersion = await sdkVersionGuidance(platform, packageJsonText);
     const decisionsRequired = [
+        ...solutionPathDecisions(solutionPath, answers),
+        ...uikitCustomizationDecisions(uikitCustomization, answers),
         ...(creativeContext
             ? [
                 `[selected creative variant] Carry "${creativeContext.selectedVariant.title}" into the implementation plan. If any selected experience object is intentionally deferred, state that scope decision explicitly.`,
@@ -125,8 +132,10 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
     return {
         outcome,
         platform,
+        solutionPath,
+        uikitCustomization,
         supportLevel,
-        intent: intentFor(request, definition.interpretation),
+        intent: intentFor(request, definition.interpretation, uikitCustomization),
         creativeContext,
         uxHarness: uxHarnessContext,
         socialWorkplan,
@@ -136,24 +145,28 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
         implementationSteps: [
             ...creativeImplementationSteps(creativeSelection),
             ...uxHarnessImplementationSteps(uxHarnessContext),
+            ...solutionPathImplementationSteps(solutionPath),
+            ...uikitCustomizationImplementationSteps(uikitCustomization),
             ...definition.implementationSteps(ctx),
         ],
         validation: ["validate_setup", "run_sensors", ...definition.validation(platform)],
-        nextStep: "After implementing every step above, run `vise check .` and fix findings until green. You are not done until the check passes or each finding is explicitly attested.",
+        nextStep: nextStepForPlan(outcome, uikitCustomization, solutionPath),
         requiredInputs: composeRequiredInputs(ctx, definition.requiredInputs(ctx)),
         targetFiles: await targetFilesFor(root, outcome, platform, inspection.designSignals),
         implementationRules: [
             ...composeImplementationRules(ctx, definition.implementationRules(ctx)),
             ...creativeImplementationRules(creativeSelection),
             ...uxHarnessImplementationRules(uxHarnessContext),
+            ...solutionPathImplementationRules(solutionPath),
+            ...uikitCustomizationImplementationRules(uikitCustomization),
         ],
         intake,
-        docs: definition.docs(platform).filter((doc) => doc.path !== "unknown"),
+        docs: docsForPlan(definition.docs(platform), uikitCustomization),
         surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
         availableSurfaces: inspection.surfaces,
         applicableRules: await applicableCompliancePlanRuleSummaries(outcome, inspection.platforms),
         sensors: sensors.map((sensor) => ({ name: sensor.name, command: sensor.command, source: sensor.source })),
-        stopConditions: composeStopConditions(ctx, definition.stopConditions(ctx), inspection.surfaces, surfacePath, Boolean(socialWorkplan)),
+        stopConditions: composeStopConditions(ctx, definition.stopConditions(ctx), inspection.surfaces, surfacePath, Boolean(socialWorkplan), uikitCustomization),
         evidencePolicy: "Every implementation step must cite at least one detected file, docs page, validator rule, or required user input. If evidence is missing, stop and ask the user instead of inventing details.",
         designContract: acceptedDesignContract ? designContractGuidance(acceptedDesignContract) : undefined,
         completenessChecklist: completenessChecklistFor(outcome),
@@ -188,6 +201,137 @@ function optionalCapabilitiesFor(outcome, answers, request, availability) {
         selected: selectedOptionalCapabilityIds(outcome, answers, request, availableIds),
     };
 }
+function solutionPathDecisions(solutionPath, answers) {
+    if (hasAnswer(answers, solutionPath.answerId)) {
+        return [];
+    }
+    if (!solutionPath.decision.requiredBeforeHandRolledUi) {
+        return [];
+    }
+    return [
+        `[solution path] ${solutionPath.summary} Answer with --answer ${solutionPath.answerId}=uikit, =sdk, or =hybrid before hand-rolling standard social UI.`,
+    ];
+}
+function solutionPathImplementationSteps(solutionPath) {
+    if (!solutionPath.decision.requiredBeforeHandRolledUi) {
+        return [];
+    }
+    return [
+        {
+            step: solutionPath.recommendation === "uikit"
+                ? "Confirm the social.plus UIKit path before building standard social UI from SDK primitives; use UIKit install/auth/customization docs as the primary implementation source. The SDK feed/chat/profile steps that follow apply ONLY to the direct-SDK (or hybrid SDK-side) route — do not hand-roll the standard surface from them when the customer is using UIKit."
+                : "Resolve whether this is a UIKit, SDK, or hybrid build before starting UI implementation; the SDK implementation steps that follow apply to the SDK/hybrid route, not to a UIKit build. Do not let mixed speed/customization signals collapse into a hand-rolled SDK UI by default.",
+            evidence: ["solutionPath", ...solutionPath.evidence],
+        },
+    ];
+}
+function solutionPathImplementationRules(solutionPath) {
+    if (solutionPath.recommendation === "sdk" && !solutionPath.decision.requiredBeforeHandRolledUi) {
+        return [];
+    }
+    return [
+        solutionPath.advisoryOnly,
+        ...solutionPath.implementationGuidance,
+    ];
+}
+function uikitCustomizationDecisions(uikitCustomization, answers) {
+    if (!uikitCustomization) {
+        return [];
+    }
+    if (hasAnswer(answers, uikitCustomization.answerId)) {
+        return [];
+    }
+    if (uikitCustomization.decision.requiredBeforeCustomization) {
+        return [
+            `[UIKit customization] ${uikitCustomization.summary} Answer with --answer ${uikitCustomization.answerId}=dynamic-ui, =component-styling, =localization, =behavior-overrides, =fork-and-extend, =sdk-custom-ui, or =hybrid before editing UIKit UI/customization code.`,
+        ];
+    }
+    return [
+        `[UIKit customization] ${uikitCustomization.summary} State this chosen route in the implementation summary, or re-plan with --answer ${uikitCustomization.answerId}=<route> if the customer chooses a different level.`,
+    ];
+}
+function uikitCustomizationImplementationSteps(uikitCustomization) {
+    if (!uikitCustomization) {
+        return [];
+    }
+    return [
+        {
+            step: `Apply the UIKit customization ladder before writing custom UI: start with ${uikitCustomization.recommendedLevel}, then escalate only if the customer goal cannot be expressed there.`,
+            evidence: ["uikitCustomization", ...uikitCustomization.evidence],
+        },
+    ];
+}
+function uikitCustomizationImplementationRules(uikitCustomization) {
+    if (!uikitCustomization) {
+        return [];
+    }
+    return [
+        uikitCustomization.advisoryOnly,
+        ...uikitCustomization.implementationGuidance,
+        ...uikitCustomization.platformGuidance,
+    ];
+}
+function docsForPlan(outcomeDocs, uikitCustomization) {
+    const docs = outcomeDocs.filter((doc) => doc.path !== "unknown");
+    if (!uikitCustomization) {
+        return docs;
+    }
+    const customizationLabel = labelForUIKitCustomizationLevel(uikitCustomization.recommendedLevel);
+    for (const docPath of uikitCustomization.docs) {
+        docs.push({
+            path: docPath,
+            reason: `UIKit ${customizationLabel} customization guidance for this solution path.`,
+        });
+    }
+    return dedupeDocsByPath(docs);
+}
+function supportLevelForPlan(outcome, platform, baseSupportLevel, uikitCustomization) {
+    if (platform !== "unknown" && outcome === "unknown" && uikitCustomization) {
+        return "guided";
+    }
+    return baseSupportLevel;
+}
+function nextStepForPlan(outcome, uikitCustomization, solutionPath) {
+    if (outcome === "unknown" && uikitCustomization) {
+        return "Treat this as UIKit customization guidance first: resolve the UIKit route and concrete app/platform target, then implement customer-owned config, localization, behavior, fork, or SDK custom UI changes with local build evidence. Do not claim `vise check` deterministically validates hidden UIKit internals.";
+    }
+    if (solutionPath.decision.requiredBeforeHandRolledUi) {
+        return "First resolve the solution-path decision (UIKit vs SDK vs hybrid). The SDK implementation steps above apply only if you build this surface directly with the SDK (or the SDK side of a hybrid); if the customer uses social.plus UIKit for the standard surface, follow the UIKit guidance instead of hand-rolling those steps. Once the route is settled, implement the applicable steps, then run `vise check .` and fix findings until green — you are not done until the check passes or each finding is explicitly attested.";
+    }
+    return "After implementing every step above, run `vise check .` and fix findings until green. You are not done until the check passes or each finding is explicitly attested.";
+}
+function dedupeDocsByPath(docs) {
+    const seen = new Set();
+    const out = [];
+    for (const doc of docs) {
+        if (seen.has(doc.path)) {
+            continue;
+        }
+        seen.add(doc.path);
+        out.push(doc);
+    }
+    return out;
+}
+function labelForUIKitCustomizationLevel(level) {
+    switch (level) {
+        case "dynamic-ui":
+            return "Dynamic UI";
+        case "component-styling":
+            return "Component Styling";
+        case "localization":
+            return "Localization";
+        case "behavior-overrides":
+            return "Behavior Overrides";
+        case "fork-and-extend":
+            return "Fork and Extend";
+        case "sdk-custom-ui":
+            return "SDK Custom UI";
+        case "hybrid":
+            return "Hybrid";
+        case "needs-decision":
+            return "decision";
+    }
+}
 function creativeContextForPlan(selection) {
     const selectedVariant = selection.selectedVariant;
     const surfaceHints = creativeSurfaceHints(selection);
@@ -484,13 +628,17 @@ function designContractGuidance(contract) {
         advisoryOnly: "This contract is advisory generation guidance — it adds no deterministic enforcement and never fails `vise check`.",
     };
 }
-function intentFor(request, interpretation) {
+function intentFor(request, interpretation, uikitCustomization) {
     const broadSocialRequest = BROAD_SOCIAL_REGEX.test(request);
     const designRequest = DESIGN_REGEX.test(request);
+    const uikitOnlyCustomization = interpretation === "Implement unknown." && uikitCustomization;
+    const uikitInterpretation = uikitOnlyCustomization
+        ? `${uikitCustomization.summary} No deterministic SDK outcome was selected, so keep this as guided UIKit customization until the customer names the concrete social surface or app-owned customization target.`
+        : interpretation;
     return {
         rawRequest: request,
-        interpretation,
-        ambiguity: broadSocialRequest || designRequest ? "high" : "medium",
+        interpretation: uikitInterpretation,
+        ambiguity: broadSocialRequest || designRequest || uikitCustomization?.status === "needs-decision" || uikitOnlyCustomization ? "high" : "medium",
     };
 }
 function intakeFor(ctx, outcomeQuestions, outcome, brief, availability, designReview) {
@@ -611,15 +759,18 @@ function composeImplementationRules(ctx, outcomeRules) {
     }
     return rules;
 }
-function composeStopConditions(ctx, outcomeStops, surfaces, surfacePath, hasSocialWorkplan = false) {
+function composeStopConditions(ctx, outcomeStops, surfaces, surfacePath, hasSocialWorkplan = false, uikitCustomization) {
     const stops = [
         "A required secret is missing and no safe ignored local env file or non-secret template path is clear.",
         "The target file is ambiguous or missing and no safe conventional location is detected.",
         "Docs lookup does not return the canonical page named in this plan.",
     ];
-    if (ctx.platform === "unknown" || ctx.outcome === "unknown") {
+    if (ctx.platform === "unknown" || (ctx.outcome === "unknown" && !uikitCustomization)) {
         stops.push("The request or platform is unsupported; do not implement until clarified.");
     }
+    if (ctx.outcome === "unknown" && uikitCustomization) {
+        stops.push("No deterministic SDK outcome was selected; do not run `vise init` or claim compliance coverage until a concrete social surface or app-owned UIKit customization target is confirmed.");
+    }
     if (ctx.platforms.length > 1 && !surfacePath) {
         stops.push(`Multiple platform signals detected (${ctx.platforms.join(", ")}); confirm which app surface should be modified.`);
     }

package/dist/tools/project.js

@@ -204,7 +204,7 @@ async function validateAndroid(root) {
     const loginFiles = filesMatching(sourceContent, [/AmityCoreClient\s*\.\s*login/, /AmityClient\s*\.\s*login/]);
     const pushRegistrationFiles = filesMatching(sourceContent, [/registerPushNotification/, /enablePushNotification/, /PushNotification/]);
     const pushUnregisterFiles = filesMatching(sourceContent, [/unregisterPushNotification/, /disablePushNotification/, /unregister.*DeviceToken/i]);
-    const liveDataFiles = filesMatching(sourceContent, [/LiveCollection/, /LiveObject/, /\.observe\s*\(/, /\.subscribe\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/]);
+    const liveDataFiles = filesMatching(sourceContent, [/LiveCollection/, /LiveObject/, /\.observe\s*\(/, /AmitySocialClient\s*\.\s*newPostRepository/, /\bgetPosts\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/]);
     if (!manifest) {
         findings.push(finding("android.manifest.present", "warning", "No AndroidManifest.xml found at the default app path.", manifestPath, "Confirm the Android app module path, then validate permissions and Application wiring."));
     }
@@ -317,8 +317,8 @@ async function validateFlutter(root) {
     const dartContent = await readMany(dartFiles);
     const setupFiles = filesMatching(dartContent, [/AmityCoreClient\s*\.\s*setup/]);
     const loginFiles = filesMatching(dartContent, [/AmityCoreClient\s*\.\s*login/]);
-    const pushRegistrationFiles = filesMatching(dartContent, [/registerPushNotification/, /enablePushNotification/, /PushNotification/]);
-    const pushUnregisterFiles = filesMatching(dartContent, [/unregisterPushNotification/, /disablePushNotification/]);
+    const pushRegistrationFiles = filesMatching(dartContent, [/registerPushNotification/, /registerDeviceNotification/, /enablePushNotification/, /PushNotification/]);
+    const pushUnregisterFiles = filesMatching(dartContent, [/unregisterPushNotification/, /unregisterDeviceNotification/, /disablePushNotification/]);
     const liveDataFiles = filesMatching(dartContent, [/LiveCollection/, /LiveObject/, /\.listen\s*\(/, /\.observe\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/]);
     if (!pubspec) {
         findings.push(finding("flutter.pubspec.present", "warning", "No pubspec.yaml file was found.", "pubspec.yaml", "Point repoPath at the Flutter project root."));
@@ -715,6 +715,9 @@ function validateFeedUiStates(root, platform, sourceContent) {
         if (isNonUiSourceFile(file)) {
             continue;
         }
+        if (platform === "android" && /\bclass\s+\w+\s*:\s*Application\s*\(/.test(content)) {
+            continue;
+        }
         const observes = observationPatterns.some((pattern) => pattern.test(content));
         if (!observes) {
             continue;
@@ -741,7 +744,7 @@ const UI_STATE_PATTERNS_BY_PLATFORM = {
     typescript: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /\.length\s*===?\s*0/, /\busestate\b/i],
     "react-native": [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /\.length\s*===?\s*0/, /ActivityIndicator/],
     flutter: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bisEmpty\b/, /CircularProgressIndicator/, /AsyncSnapshot/, /ConnectionState/],
-    android: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /CircularProgressIndicator/, /LoadingState/, /\.collectAsState\b/],
+    android: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /CircularProgressIndicator/, /LoadingState/, /FeedUiState\.(?:Loading|Empty|Error)\b/, /\.collectAsState\b/],
     ios: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /ProgressView/, /LoadingState/, /AsyncImage/],
 };
 const FEED_LIST_OBSERVATION_PATTERNS_BY_PLATFORM = {
@@ -1434,7 +1437,9 @@ function validatePostsStatusFilter(root, platform, sourceContent) {
     ];
     const FILTER_MARKERS = [
         /\bfeedTypes?\s*[:(]/,
+        /\breviewStatus\s*[:(]/,
         /\bincludeDeleted\s*\(\s*false\s*\)/,
+        /\bdeletedOption\s*:\s*\.notDeleted\b/,
         /\bisDeleted\s*:\s*false\b/,
         /\bisFlagged\s*:\s*false\b/,
         /\bstatuses\s*[:(]/,
@@ -2296,6 +2301,9 @@ async function validateIos(root) {
     else if (!containsAny(manifestContent, [/Amity/i, /AmitySDK/i])) {
         findings.push(finding("ios.dependency.sdk", "warning", "No obvious social.plus/Amity dependency was found in Podfile or Package.swift.", relativeFile(root, manifestFiles[0]), "Add the iOS SDK dependency from the iOS quick-start docs."));
     }
+    else if (containsAny(manifestContent, [/Amity-Social-Cloud-SDK-iOS-IPA/i])) {
+        findings.push(finding("ios.dependency.swiftpm-repo", "warning", "The iOS SwiftPM dependency points at the obsolete Amity-Social-Cloud-SDK-iOS-IPA package repository.", relativeFile(root, manifestFiles[0]), "Use https://github.com/AmityCo/Amity-Social-Cloud-SDK-iOS-SwiftPM.git with product AmitySDK so SwiftPM can resolve the social.plus iOS SDK."));
+    }
     else if (containsAny(manifestContent, [/\.package\s*\([^)]*\bbranch\s*:/s, /pod\s+['"][^'"]*Amity[^'"]*['"]\s*$/m])) {
         findings.push(finding("ios.sdk.version.pinned", "warning", "The iOS SDK dependency appears to use a floating branch or unspecified CocoaPods version.", relativeFile(root, manifestFiles[0]), "Pin the social.plus iOS SDK to an explicit version or reviewed semver range so CI does not pick up unreviewed SDK APIs."));
     }
@@ -2944,7 +2952,7 @@ function validateNotificationsPreferencesConfigured(root, platform, sourceConten
     let hasPreferences = false;
     let firstPushRegistrationFile = '';
     for (const [filename, text] of sourceContent) {
-        if (/\b(registerPushNotification|enablePushNotification)\b/.test(text)) {
+        if (/\b(registerPushNotification|registerDeviceNotification|enablePushNotification)\b/.test(text)) {
             hasPushRegistration = true;
             if (!firstPushRegistrationFile) {
                 firstPushRegistrationFile = (typeof filename === 'string' && root) ? (filename.startsWith(root) ? filename.slice(root.length).replace(/^\//, '') : filename) : filename;