@amityco/social-plus-vise 1.3.0 → 1.4.1

package/dist/server.js

@@ -3,11 +3,14 @@ import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { sidecarDir as sidecarPath } from "./sidecar.js";
+import { blueprintDigest, readFlowState, readOmittedSurfaces, renderFlowBlueprint, runtimeReadinessForStages, writeFlowBlueprintHtml, writeFlowState, } from "./flow.js";
+import { normalizeSolutionPathAnswer } from "./solutionPath.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, experienceReportTool, initCompliance, initComplianceTool, recordBaseline, initEngagement, initEngagementTool, listRules, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
-import { designCheckTool, designExtractTool, designInitTokensTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
+import { designCheckTool, designContrastTool, designExtractTool, designInitTokensTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
 import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
 import { compileExperienceTool } from "./tools/experienceCompiler.js";
 import { experienceSensorsTool } from "./tools/experienceSensors.js";
@@ -17,6 +20,7 @@ import { recordLearningTool, showLearningTool } from "./tools/learning.js";
 import { inspectProjectTool, validateSetupTool } from "./tools/project.js";
 import { resolveRequestTool, suggestPatchTool } from "./tools/resolve.js";
 import { runSensorsTool } from "./tools/sensors.js";
+import { smokeTool } from "./tools/smoke.js";
 import { getSdkFactsTool } from "./tools/sdkFacts.js";
 import { addBlockInstall, listRegistryBlocks, planBlockInstall, validateBlockInstall } from "./tools/blocks.js";
 import { debugIssueTool, debugIssue } from "./tools/debug.js";
@@ -24,7 +28,7 @@ import { creativeAcceptTool, creativeBriefTool } from "./tools/creative.js";
 import { uxHarnessTool } from "./tools/uxHarness.js";
 import { exploreRequest } from "./explore.js";
 import { renderHuman, wantsHumanFormat } from "./humanFormat.js";
-import { packageName, packageVersion } from "./version.js";
+import { buildSource, packageName, packageRoot, packageVersion } from "./version.js";
 const SUPPORT_URL = "mailto:support@social.plus";
 const tools = new Map([
     searchDocsTool,
@@ -49,11 +53,13 @@ const tools = new Map([
     showEngagementTool,
     resolveRequestTool,
     runSensorsTool,
+    smokeTool,
     validateSetupTool,
     suggestPatchTool,
     debugIssueTool,
     designExtractTool,
     designCheckTool,
+    designContrastTool,
     designPreviewTool,
     designReferenceTool,
     designInitTokensTool,
@@ -316,7 +322,14 @@ async function handleCli(args) {
                 console.log(JSON.stringify(await completeWorkplanSurface(subArgs), null, 2));
                 return "exit";
             }
-            console.error(`Unknown workplan subcommand: ${sub ?? "(none)"}. Expected "next", "status", or "complete".`);
+            if (sub === "trim") {
+                assertOnlyKnownFlags(subArgs, ["request", "surface", "surface-path", "answer", "reason"], "workplan trim");
+                const trim = await trimWorkplanSurface(subArgs);
+                console.log(JSON.stringify(trim.payload, null, 2));
+                process.exitCode = trim.exitCode;
+                return "exit";
+            }
+            console.error(`Unknown workplan subcommand: ${sub ?? "(none)"}. Expected "next", "status", "complete", or "trim".`);
             process.exitCode = 1;
             return "exit";
         }
@@ -343,6 +356,21 @@ async function handleCli(args) {
             }
             return "exit";
         }
+        if (command === "smoke") {
+            const printed = await printToolResult(smokeTool, {
+                repoPath: positionalRepoPath(args.slice(1)),
+                logPath: flagValue(args, "log") ?? flagValue(args, "log-path"),
+                surface: flagValue(args, "surface"),
+            });
+            const status = toolResultStatus(printed);
+            if (status === "failed") {
+                process.exitCode = 1;
+            }
+            else if (status === "no-config" || status === "no-log" || status === "no-surfaces") {
+                process.exitCode = 2;
+            }
+            return "exit";
+        }
         if (command === "resolve") {
             await printToolResult(resolveRequestTool, {
                 repoPath: positionalRepoPath(args.slice(1)),
@@ -418,7 +446,24 @@ async function handleCli(args) {
         if (command === "init") {
             assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer", "allow-unresolved-intake", "baseline"], "init");
             const initRepo = positionalRepoPath(args.slice(1));
-            const result = await initCompliance(initRepo, requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer"), { allowUnresolvedIntake: hasFlag(args, "allow-unresolved-intake") });
+            const initRequest = requiredFlagValue(args, "request", "init requires --request.");
+            const initWorkplanPlan = await workplanPlan(initRepo, initRequest, args);
+            const { sequence: initSequence, omitted: initOmitted } = await activeBlueprint(initRepo, initRequest, initWorkplanPlan);
+            if (initSequence.length >= 2 && initWorkplanPlan.platform !== "unknown") {
+                const blueprintGate = await requireBlueprintConfirmation(initRepo, initRequest, initWorkplanPlan, initSequence, args, new Date().toISOString(), initOmitted);
+                if (blueprintGate) {
+                    console.log(JSON.stringify(blueprintGate, null, 2));
+                    process.exitCode = 7;
+                    return "exit";
+                }
+                const workplanInitGate = await requireNextWorkplanSurfaceInit(initRepo, initRequest, initSequence, keyValueFlag(args, "answer"));
+                if (workplanInitGate) {
+                    console.log(JSON.stringify(workplanInitGate, null, 2));
+                    process.exitCode = 7;
+                    return "exit";
+                }
+            }
+            const result = await initCompliance(initRepo, initRequest, flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer"), { allowUnresolvedIntake: hasFlag(args, "allow-unresolved-intake") });
             if (result.status === "needs-clarification" && typeof result.exitCode === "number") {
                 process.exitCode = result.exitCode;
             }
@@ -532,6 +577,17 @@ async function handleCli(args) {
                 await printToolResult(designCheckTool, { repoPath: positionalRepoPath(subArgs) });
                 return "exit";
             }
+            if (sub === "contrast") {
+                assertOnlyKnownFlags(subArgs, [], "design contrast");
+                const colors = subArgs.filter((arg) => !arg.startsWith("-"));
+                if (colors.length < 2) {
+                    console.error("design contrast requires two colours: vise design contrast <foreground> <background> (e.g. vise design contrast '#5a6477' '#0e1726').");
+                    process.exitCode = 1;
+                    return "exit";
+                }
+                await printToolResult(designContrastTool, { foreground: colors[0], background: colors[1] });
+                return "exit";
+            }
             if (sub === "preview") {
                 assertOnlyKnownFlags(subArgs, ["reference", "no-write"], "design preview");
                 await printToolResult(designPreviewTool, {
@@ -558,7 +614,7 @@ async function handleCli(args) {
                 });
                 return "exit";
             }
-            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", "preview", "reference", or "init-tokens".`);
+            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", "contrast", "preview", "reference", or "init-tokens".`);
             process.exitCode = 1;
             return "exit";
         }
@@ -632,8 +688,8 @@ Usage:
   vise creative [repoPath] --request "Add engagement" --prototype ./prototype.html
   vise creative [repoPath] --request "Add engagement" --ranking-preview
   vise creative [repoPath] --request "Add engagement" --no-write
-  vise creative accept [repoPath] --variant community-first
-  vise creative accept [repoPath] --variant none --rationale "No variant fits X; closest is Y" --closest discovery-first
+  vise creative accept [repoPath] --variant community-first --rationale "Always-on community participation is the primary destination." --confidence high
+  vise creative accept [repoPath] --variant none --rationale "No variant fits X; closest is Y" --confidence high --closest discovery-first
 
 Output:
   Writes sp-vise/creative-brief.json and sp-vise/creative-brief.md unless --no-write is set.
@@ -717,12 +773,17 @@ Usage:
   vise workplan next [repoPath] --request "Add feed, comments, chat, and profile"
   vise workplan status [repoPath] --request "Add feed, comments, chat, and profile"
   vise workplan complete [repoPath] --request "Add feed, comments, chat, and profile" --surface feed
+  vise workplan trim [repoPath] --request "..." --surface chat --reason "goal never asked for messaging"
 
 Notes:
   next/status re-run the broad plan, ignore any feature_surface answer, and combine it
   with sp-vise/workplan.json progress. complete records a host-agent progress marker;
   run vise check, vise sync, vise validate, and vise run-sensors before marking a
-  surface complete.`;
+  surface complete.
+  trim deliberately omits a companion surface (surface-level scope-omit): --reason is
+  required, the surface must not already be built, and at least two surfaces must remain.
+  A trim changes the blueprint, so the sign-off gate re-fires — the human re-confirms the
+  trimmed blueprint (which names what was dropped) before any surface proceeds.`;
     }
     if (command === "search-docs" || command === "search_docs") {
         return `${packageName} search-docs
@@ -811,6 +872,23 @@ Run detected project command sensors such as typecheck, test, build, Flutter, or
 
 Usage:
   vise run-sensors [repoPath] [--dry-run] [--include "npm test"] [--timeout-ms 120000]`;
+    }
+    if (command === "smoke") {
+        return `${packageName} smoke
+
+Assess a captured runtime mount-smoke log into a pass/fail verdict and record runtime-smoke
+evidence. Catches the session-establish race (a live-data query fired before the SDK session is
+established) that static \`vise check\` cannot see. Declare collection surfaces in sp-vise/smoke.json,
+emit VISE_SMOKE markers from the mounted SDK query lifecycle, cold-launch into the social route,
+wait for the collection to resolve, capture the runtime log, then:
+
+Usage:
+  vise smoke [repoPath] --log <captured-log> [--surface <id>]
+
+Android: adb logcat -c before launch, then adb logcat -d -v time | grep VISE_SMOKE > sp-vise/evidence/runtime-smoke.log
+iOS: xcrun simctl spawn <device> log show --style compact --last 3m --predicate 'eventMessage CONTAINS "VISE_SMOKE"' > sp-vise/evidence/runtime-smoke.log
+
+See docs/RUNTIME_SMOKE.md.`;
     }
     if (command === "resolve") {
         return `${packageName} resolve
@@ -943,7 +1021,8 @@ extract    Build a graded design contract and write it to sp-vise/design-contrac
            With --from-project (no external prototype), derive the contract from the host
            project's OWN design system: CSS custom properties (incl. shadcn :root and
            Tailwind v4 @theme), TS/JS token modules, inline tailwind configs, Android
-           colors.xml/dimens.xml, Flutter Color(0x..), and iOS .xcassets/.colorset +
+           colors.xml/dimens.xml, Jetpack Compose Kotlin themes (Color(0xFF..) in
+           Theme.kt/Color.kt), Flutter Color(0x..), and iOS .xcassets/.colorset +
            Swift colors. Reference values (var()/theme()/calc()) are skipped, so a
            var-mapped config contributes nothing rather than wrong tokens.
 check      Advisory, non-blocking report on how closely the project's UI code
@@ -999,7 +1078,7 @@ Usage:
   vise print-skill                 Print bundled skill markdown
   vise inspect [repoPath]          Inspect platform and design signals
   vise creative [repoPath] --request "..." Create an Engagement Intelligence brief
-  vise creative accept [repoPath] --variant <id|none> Accept a creative variant, or record a no-fit catalog gap with --variant none
+  vise creative accept [repoPath] --variant <id|none> --rationale "..." --confidence high
   vise ux-harness [repoPath]      Generate UX Harness expectations from creative selection
   vise experience-report [repoPath] Write the advisory dimensioned Experience Report
   vise experience compile [repoPath] Compile selected variant into implementation artifacts
@@ -1426,11 +1505,263 @@ function assertOnlyKnownFlags(args, allowed, commandName) {
     const allowedList = allowed.length > 0 ? `Allowed flags: ${allowed.map((flag) => `--${flag}`).join(", ")}.` : "This command takes no flags.";
     throw new Error(`${commandName} does not accept ${unknown.join(", ")}. ${allowedList} Run \`vise ${commandName} --help\` for usage.`);
 }
+function blueprintStagesForSequence(sequence) {
+    return sequence.map((surface) => ({ id: surface.id, outcome: surface.outcome, label: surface.label }));
+}
+async function activeBlueprint(repoRoot, request, plan) {
+    const planSequence = socialWorkplanSequence(plan);
+    const full = planSequence.length
+        ? planSequence
+        : await socialWorkplanSequenceFromSignedFlow(repoRoot, request);
+    const omitted = await readOmittedSurfaces(repoRoot, request);
+    const omittedIds = new Set(omitted.map((item) => item.id));
+    return { sequence: full.filter((surface) => !omittedIds.has(surface.id)), omitted };
+}
+async function socialWorkplanSequenceFromSignedFlow(repoRoot, request) {
+    const state = await readFlowState(repoRoot);
+    if (state?.request !== request) {
+        return [];
+    }
+    const stages = state.blueprint?.stages ?? [];
+    if (stages.length <= 1) {
+        return [];
+    }
+    return stages.map((stage, index) => {
+        const id = stage.id || stage.outcome;
+        const commonArgs = `. --request ${shellQuoteForCommand(request)} --answer feature_surface=${id}`;
+        return {
+            id,
+            order: index + 1,
+            outcome: stage.outcome,
+            label: stage.label ?? id,
+            planCommand: `vise plan ${commonArgs}`,
+            initCommand: `vise init ${commonArgs}`,
+            intake: {
+                status: "from-signed-blueprint",
+                questions: [],
+                remainingBlocking: 0,
+            },
+            validation: ["validate_setup", "run_sensors"],
+        };
+    });
+}
+async function requireBlueprintConfirmation(repoRoot, request, plan, sequence, args, now, omitted = []) {
+    if (sequence.length === 0) {
+        return null;
+    }
+    const stages = blueprintStagesForSequence(sequence);
+    const runtimeReadiness = runtimeReadinessForStages(stages);
+    const existing = await readFlowState(repoRoot);
+    const answers = keyValueFlag(args, "answer");
+    const existingBlueprint = existing?.request === request ? existing.blueprint : undefined;
+    const existingPath = existingBlueprint?.path ?? null;
+    const existingPathDecisionConfirmed = Boolean(existingBlueprint?.path_decision_confirmed === true || existingBlueprint?.confirmed_digest);
+    const persistedPath = existingPathDecisionConfirmed ? existingPath : null;
+    const explicitPathAnswer = normalizeSolutionPathAnswer(answers.solution_path);
+    const pathDecidedness = plan.entryState?.pathDecidedness ?? null;
+    const pathNeedsDecision = (pathDecidedness === "undecided" || pathDecidedness === "conflict") && !persistedPath && !explicitPathAnswer;
+    const pathForDigest = explicitPathAnswer ?? persistedPath ?? plan.solutionPath?.recommendation ?? null;
+    const design = plan.designReview?.digest ?? plan.designContract?.digest ?? null;
+    const digest = blueprintDigest({ path: pathForDigest, stages, design });
+    const confirmedByAnswer = answers.blueprint_confirmation === digest;
+    const alreadyConfirmed = existing?.request === request && existing?.blueprint?.confirmed_digest === digest;
+    const persist = (confirmed) => {
+        const pathDecisionConfirmed = confirmed || Boolean(existingPathDecisionConfirmed && existingPath && existingPath === pathForDigest);
+        return {
+            schema_version: 1,
+            vise_version: packageVersion,
+            generated_at: existing?.generated_at ?? now,
+            updated_at: now,
+            request,
+            blueprint: {
+                digest,
+                confirmed_digest: confirmed ? digest : null,
+                ...(confirmed ? { confirmed_at: alreadyConfirmed ? existing?.blueprint?.confirmed_at ?? now : now } : {}),
+                stages,
+                ...(pathForDigest ? { path: pathForDigest, path_decision_confirmed: pathDecisionConfirmed } : {}),
+                ...(omitted.length ? { omitted } : {}),
+                runtime_readiness: runtimeReadiness,
+            },
+        };
+    };
+    if (alreadyConfirmed) {
+        await writeFlowState(repoRoot, persist(true));
+        return null;
+    }
+    const experience = await blueprintExperience(repoRoot);
+    const blueprintRel = (fsPath) => repoRelativePath(repoRoot, fsPath);
+    const approvalChecklist = (pathDecision) => [
+        {
+            id: "solution_path",
+            label: "Solution path",
+            status: pathDecision ? "choose-one-before-signoff" : "confirm",
+            value: pathForDigest ?? null,
+            ...(pathDecision ? { question: pathDecision.question, options: pathDecision.options } : {}),
+        },
+        {
+            id: "experience",
+            label: "EI experience",
+            status: experience?.selected ? "confirm-or-switch" : "not-provided",
+            value: experience?.selected ?? null,
+            alternatives: experience?.alternatives ?? [],
+        },
+        {
+            id: "surfaces",
+            label: "Journey surfaces",
+            status: "confirm-in-scope",
+            value: stages,
+        },
+        {
+            id: "design",
+            label: "Design source",
+            status: design ? "confirm-contract" : "no-accepted-design-contract",
+            value: design,
+        },
+        {
+            id: "runtime_readiness",
+            label: "Runtime readiness",
+            status: "review-and-ask-runtime-proof-consent",
+            value: runtimeReadiness,
+        },
+        ...(omitted.length
+            ? [{
+                    id: "omitted_surfaces",
+                    label: "Trimmed surfaces",
+                    status: "confirm-out-of-scope",
+                    value: omitted.map((item) => ({ id: item.id, outcome: item.outcome, reason: item.reason })),
+                }]
+            : []),
+    ];
+    const unattendedBlueprintStop = (pathDecision) => ({
+        status: "blocked",
+        mode: "handoff-required",
+        reason: "Blueprint sign-off is an alignment decision about what to build.",
+        instruction: "If the user is not available, stop and return the blueprint path, approvalChecklist, and required answers. Do not choose the solution path, sign the digest, initialize a surface, or record completion on the user's behalf.",
+        allowedActions: [
+            "open or summarize sp-vise/flow-blueprint.html",
+            "collect an explicit solution_path choice when required",
+            "collect explicit approval or requested trims/switches",
+        ],
+        resumeWhen: [
+            ...(pathDecision ? ["the user chooses solution_path=sdk|uikit|hybrid"] : []),
+            "the user approves the experience and journey, or asks for a trim/switch",
+            "the command is re-run with the required --answer values",
+        ],
+    });
+    if (pathNeedsDecision) {
+        const decision = plan.solutionPath?.decision;
+        const pathDecision = {
+            question: decision?.question ?? "Should this build use social.plus UIKit components, a direct SDK implementation, or a hybrid path?",
+            options: decision?.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",
+            ],
+        };
+        const fsPath = await writeFlowBlueprintHtml(repoRoot, renderFlowBlueprint({
+            request,
+            path: null,
+            stages,
+            design,
+            digest,
+            omitted,
+            experience: experience ?? undefined,
+            pathDecision,
+            runtimeReadiness,
+        }));
+        await writeFlowState(repoRoot, persist(false));
+        return {
+            status: "needs-blueprint-confirmation",
+            request,
+            blueprintDigest: digest,
+            blueprintPath: blueprintRel(fsPath),
+            blueprint: { path: null, stages },
+            pathDecision: { ...pathDecision, required: true },
+            approvalChecklist: approvalChecklist(pathDecision),
+            unattended: unattendedBlueprintStop(pathDecision),
+            runtimeReadiness,
+            ...(experience ? { experience } : {}),
+            ...(omitted.length ? { omitted: omitted.map((item) => ({ id: item.id, outcome: item.outcome, reason: item.reason })) } : {}),
+            nextStep: `A multi-surface build blueprint was produced, but the solution path is undecided. Open ${blueprintRel(fsPath)} and review the journey, scope, design, and runtime readiness with the customer, and present the path options (${pathDecision.options.map((o) => o.split(":")[0]).join(" / ")}). ` +
+                `First re-run with --answer solution_path=<sdk|uikit|hybrid>, then sign off the resulting blueprint. ` +
+                (experience?.selected ? `The recommended experience is "${experience.selected.title}"${experience.alternatives.length ? ` (alternatives: ${experience.alternatives.map((a) => a.title).join(", ")} — switch with \`vise creative accept . --variant <id> --rationale "<why>" --confidence high\`)` : ""}. ` : "") +
+                "Surfaces cannot be started or recorded until the blueprint is signed off; prepare identity, natural target discovery, tenant data, and Console prerequisites before feeding the workplan to a dogfood agent. Ask the user before running runtime proof because browser/simulator/emulator proof can consume local resources and agent tokens.",
+        };
+    }
+    if (confirmedByAnswer) {
+        await writeFlowState(repoRoot, persist(true));
+        return null;
+    }
+    const fsPath = await writeFlowBlueprintHtml(repoRoot, renderFlowBlueprint({
+        request,
+        path: pathForDigest,
+        stages,
+        design,
+        digest,
+        omitted,
+        experience: experience ?? undefined,
+        runtimeReadiness,
+    }));
+    await writeFlowState(repoRoot, persist(false));
+    return {
+        status: "needs-blueprint-confirmation",
+        request,
+        blueprintDigest: digest,
+        blueprintPath: blueprintRel(fsPath),
+        blueprint: { path: pathForDigest, stages },
+        approvalChecklist: approvalChecklist(),
+        unattended: unattendedBlueprintStop(),
+        runtimeReadiness,
+        ...(experience ? { experience } : {}),
+        ...(omitted.length
+            ? { omitted: omitted.map((item) => ({ id: item.id, outcome: item.outcome, reason: item.reason })) }
+            : {}),
+        nextStep: `A multi-surface build blueprint was produced. Open ${blueprintRel(fsPath)} and review the path, journey, scope, design, and runtime readiness with the customer. ` +
+            (experience?.selected && experience.alternatives.length
+                ? `The recommended experience is "${experience.selected.title}" (alternatives: ${experience.alternatives.map((a) => a.title).join(", ")} — to build a different one, re-run \`vise creative accept . --variant <id> --rationale "<why>" --confidence high\` and re-confirm). `
+                : "") +
+            (omitted.length
+                ? `This blueprint has ${omitted.length} deliberately trimmed surface(s): ${omitted.map((item) => `${item.id} (${item.reason})`).join("; ")}. Confirm the human approved dropping them. `
+                : "") +
+            `After they approve, re-run this command with --answer blueprint_confirmation=${digest}. ` +
+            "Surfaces cannot be started or recorded until the blueprint is signed off; prepare identity, natural target discovery, tenant data, and Console prerequisites before feeding the workplan to a dogfood agent. Ask the user before running runtime proof because browser/simulator/emulator proof can consume local resources and agent tokens.",
+    };
+}
+async function blueprintExperience(repoRoot) {
+    const dir = sidecarPath(repoRoot);
+    let candidates = [];
+    try {
+        const brief = JSON.parse(await readFile(path.join(dir, "creative-brief.json"), "utf8"));
+        candidates = Array.isArray(brief.candidateSolutions) ? brief.candidateSolutions : [];
+    }
+    catch {
+        return null;
+    }
+    if (candidates.length === 0)
+        return null;
+    let selected = null;
+    try {
+        const sel = JSON.parse(await readFile(path.join(dir, "creative-selection.json"), "utf8"));
+        const id = sel.selectedVariant?.id;
+        if (typeof id === "string") {
+            selected = { id, title: typeof sel.selectedVariant?.title === "string" ? sel.selectedVariant.title : id };
+        }
+    }
+    catch {
+    }
+    const alternatives = candidates
+        .filter((c) => c != null && typeof c.id === "string" && c.id !== selected?.id)
+        .slice(0, 4)
+        .map((c) => ({ id: c.id, title: typeof c.title === "string" ? c.title : c.id }));
+    if (!selected && alternatives.length === 0)
+        return null;
+    return { selected, alternatives };
+}
 async function workplanStatus(args) {
     const repoRoot = path.resolve(positionalRepoPath(args));
     const request = requiredFlagValue(args, "request", "workplan next/status requires --request.");
     const plan = await workplanPlan(repoRoot, request, args);
-    const sequence = socialWorkplanSequence(plan);
+    const { sequence, omitted } = await activeBlueprint(repoRoot, request, plan);
     const progress = await readWorkplanProgress(repoRoot);
     const completed = progress?.request === request ? progress.completed : [];
     const completedIds = new Set(completed.map((item) => item.surface));
@@ -1443,12 +1774,19 @@ async function workplanStatus(args) {
             progressPath: workplanProgressPath(repoRoot),
         };
     }
+    const blueprintGate = await requireBlueprintConfirmation(repoRoot, request, plan, sequence, args, new Date().toISOString(), omitted);
+    if (blueprintGate) {
+        return blueprintGate;
+    }
+    const runtimeReadiness = runtimeReadinessForStages(blueprintStagesForSequence(sequence));
+    const nextSurfaceReadiness = nextSurface ? runtimeReadiness.surfaces.find((surface) => surface.id === nextSurface.id) : undefined;
     return {
         status: nextSurface ? "next-surface" : "complete",
         request,
         progressPath: workplanProgressPath(repoRoot),
         creativeContext: plan.socialWorkplan?.creativeContext ?? plan.creativeContext,
         uxHarness: plan.socialWorkplan?.uxHarness ?? plan.uxHarness,
+        runtimeReadiness,
         completed,
         sequence: sequence.map((surface) => ({
             id: surface.id,
@@ -1457,6 +1795,9 @@ async function workplanStatus(args) {
             label: surface.label,
             completed: completedIds.has(surface.id),
         })),
+        ...(omitted.length
+            ? { omitted: omitted.map((item) => ({ id: item.id, outcome: item.outcome, reason: item.reason })) }
+            : {}),
         nextSurface: nextSurface
             ? {
                 id: nextSurface.id,
@@ -1466,9 +1807,12 @@ async function workplanStatus(args) {
                 intake: nextSurface.intake,
                 validation: nextSurface.validation,
                 uxHarness: nextSurface.uxHarness,
+                runtimeReadiness: nextSurfaceReadiness,
                 commands: {
                     plan: nextSurface.planCommand,
-                    init: nextSurface.initCommand,
+                    init: plan.designReview?.status === "needs-confirmation"
+                        ? `${nextSurface.initCommand} --answer design_contract_confirmation=yes`
+                        : nextSurface.initCommand,
                     check: "vise check .",
                     sync: "vise sync .",
                     validate: "vise validate .",
@@ -1478,22 +1822,100 @@ async function workplanStatus(args) {
             }
             : undefined,
         nextStep: nextSurface
-            ? `Resolve the ${nextSurface.id} surface intake, run its focused plan/init command, implement it, then run check/sync/validate/sensors before marking it complete.`
+            ? `Resolve the ${nextSurface.id} surface intake, confirm runtime readiness and natural target discovery for that next pending surface, run only its focused plan/init command, implement it, then run check/sync/validate/sensors and workplan complete before moving to any later surface. Before runtime proof, ask the user whether to spend browser/simulator/emulator resources; if they decline, record the expected unproven runtime risks instead of claiming product proof.`
             : "All workplan surfaces are marked complete. Run one final `vise check .`, `vise validate .`, and `vise run-sensors .` before handoff.",
     };
 }
+async function trimWorkplanSurface(args) {
+    const repoRoot = path.resolve(positionalRepoPath(args));
+    const request = requiredFlagValue(args, "request", "workplan trim requires --request.");
+    const surfaceId = requiredFlagValue(args, "surface", "workplan trim requires --surface <surface-id>.");
+    const reason = (flagValue(args, "reason") ?? "").trim();
+    if (!reason) {
+        throw new Error('workplan trim requires --reason "<why this companion is out of scope>". An omission without a recorded reason is invalid.');
+    }
+    const plan = await workplanPlan(repoRoot, request, args);
+    const full = socialWorkplanSequence(plan);
+    if (full.length < 2) {
+        throw new Error("This request did not produce a multi-surface blueprint, so there is nothing to trim. Use `vise plan` for the single-outcome flow.");
+    }
+    const surface = full.find((item) => item.id === surfaceId);
+    if (!surface) {
+        throw new Error(`Surface "${surfaceId}" is not in this blueprint. Trimmable surfaces: ${full.map((item) => item.id).join(", ")}.`);
+    }
+    const existingOmitted = await readOmittedSurfaces(repoRoot, request);
+    if (existingOmitted.some((item) => item.id === surfaceId)) {
+        return {
+            payload: {
+                status: "already-trimmed",
+                request,
+                surface: surfaceId,
+                omitted: existingOmitted.map((item) => ({ id: item.id, outcome: item.outcome, reason: item.reason })),
+                nextStep: `Surface "${surfaceId}" is already trimmed; no change. Run \`vise workplan status\` to see the active blueprint.`,
+            },
+            exitCode: 0,
+        };
+    }
+    const progress = await readWorkplanProgress(repoRoot);
+    const completedIds = new Set(progress?.request === request ? progress.completed.map((item) => item.surface) : []);
+    if (completedIds.has(surfaceId)) {
+        throw new Error(`Surface "${surfaceId}" has already been built and recorded; it cannot be trimmed. Trim applies only to not-yet-built companion surfaces.`);
+    }
+    const newOmitted = [
+        ...existingOmitted,
+        { id: surface.id, outcome: surface.outcome, ...(surface.label ? { label: surface.label } : {}), reason, omitted_at: new Date().toISOString() },
+    ];
+    const newOmittedIds = new Set(newOmitted.map((item) => item.id));
+    const activeAfter = full.filter((item) => !newOmittedIds.has(item.id));
+    if (activeAfter.length < 2) {
+        throw new Error(`Trimming "${surfaceId}" would leave ${activeAfter.length} active surface(s). The alignment gate covers multi-surface journeys; at least 2 must remain. To build a single surface, re-select that experience via \`vise creative\` instead of trimming a journey down to one.`);
+    }
+    const gateArgs = stripAnswerKey(args, "blueprint_confirmation");
+    const gate = await requireBlueprintConfirmation(repoRoot, request, plan, activeAfter, gateArgs, new Date().toISOString(), newOmitted);
+    if (!gate) {
+        return {
+            payload: {
+                status: "trimmed",
+                request,
+                surface: surfaceId,
+                reason,
+                note: "Omission recorded; the blueprint is already in a confirmed state for the resulting digest.",
+                omitted: newOmitted.map((item) => ({ id: item.id, outcome: item.outcome, reason: item.reason })),
+            },
+            exitCode: 0,
+        };
+    }
+    return {
+        payload: {
+            status: "trimmed",
+            request,
+            trimmed: { id: surface.id, outcome: surface.outcome, reason },
+            ...gate,
+            nextStep: `Recorded the deliberate omission of "${surfaceId}" (${reason}). The blueprint changed and must be re-signed before any surface proceeds. ` +
+                (typeof gate.nextStep === "string" ? gate.nextStep : ""),
+        },
+        exitCode: 7,
+    };
+}
 async function completeWorkplanSurface(args) {
     const repoRoot = path.resolve(positionalRepoPath(args));
     const request = requiredFlagValue(args, "request", "workplan complete requires --request.");
     const surfaceId = requiredFlagValue(args, "surface", "workplan complete requires --surface <surface-id>.");
     const note = flagValue(args, "note");
     const plan = await workplanPlan(repoRoot, request, args);
-    const sequence = socialWorkplanSequence(plan);
+    const { sequence, omitted } = await activeBlueprint(repoRoot, request, plan);
     const surface = sequence.find((item) => item.id === surfaceId);
     if (!surface) {
+        if (omitted.some((item) => item.id === surfaceId)) {
+            throw new Error(`Surface "${surfaceId}" was deliberately trimmed from this blueprint and is not built (recorded omission). Un-trim is not yet supported; to build it, re-select an experience that includes it via \`vise creative\`.`);
+        }
         throw new Error(`Surface "${surfaceId}" is not in this social workplan. Available surfaces: ${sequence.map((item) => item.id).join(", ") || "(none)"}.`);
     }
     const now = new Date().toISOString();
+    const blueprintGate = await requireBlueprintConfirmation(repoRoot, request, plan, sequence, args, now, omitted);
+    if (blueprintGate) {
+        return blueprintGate;
+    }
     const check = await greenWorkplanCheck(repoRoot, surfaceId, surface.outcome);
     const snapshot = await writeWorkplanSurfaceSnapshot(repoRoot, surfaceId, check, now);
     const existing = await readWorkplanProgress(repoRoot);
@@ -1536,14 +1958,44 @@ async function completeWorkplanSurface(args) {
     };
     await writeWorkplanProgress(repoRoot, progress);
     const status = await workplanStatus(args);
+    const sequenceStatus = workplanSequenceStatus(status);
+    const completedSurfaces = sequenceStatus.filter((item) => item.completed);
+    const pendingSurfaces = sequenceStatus.filter((item) => !item.completed);
+    const finalHandoffAllowed = pendingSurfaces.length === 0;
+    const nextSurface = status.nextSurface;
+    const pendingSummary = pendingSurfaces.map((item) => item.id).join(", ");
     return {
         status: "recorded",
         progressPath: workplanProgressPath(repoRoot),
         recorded: progress.completed.find((item) => item.surface === surfaceId),
-        nextSurface: status.nextSurface,
-        nextStep: status.nextStep,
+        completedSurfaces,
+        pendingSurfaces,
+        workplanComplete: finalHandoffAllowed,
+        finalHandoffAllowed,
+        ...(pendingSurfaces.length
+            ? {
+                blockedHandoffReason: `The broad social request is not complete. Pending surfaces remain: ${pendingSummary}.`,
+            }
+            : {}),
+        nextSurface,
+        nextStep: pendingSurfaces.length
+            ? `Recorded "${surfaceId}" only. Do not hand off the broad request as complete: pending surfaces remain (${pendingSummary}). Continue with the next pending surface using the focused init/check/complete commands from \`nextSurface.commands\`, then rerun \`vise workplan status\` until \`workplanComplete\` is true.`
+            : status.nextStep,
     };
 }
+function workplanSequenceStatus(status) {
+    const sequence = Array.isArray(status.sequence) ? status.sequence : [];
+    return sequence
+        .filter((item) => item != null && typeof item === "object")
+        .map((item) => ({
+        id: typeof item.id === "string" ? item.id : "",
+        outcome: typeof item.outcome === "string" ? item.outcome : undefined,
+        label: typeof item.label === "string" ? item.label : undefined,
+        order: typeof item.order === "number" ? item.order : undefined,
+        completed: item.completed === true,
+    }))
+        .filter((item) => item.id.length > 0);
+}
 async function greenWorkplanCheck(repoRoot, surfaceId, expectedOutcome) {
     let check;
     try {
@@ -1605,6 +2057,86 @@ function socialWorkplanSequence(plan) {
     }
     return workplan.sequence;
 }
+async function requireNextWorkplanSurfaceInit(repoRoot, request, sequence, answers) {
+    const progress = await readWorkplanProgress(repoRoot);
+    const completedIds = new Set(progress?.request === request ? progress.completed.map((item) => item.surface) : []);
+    const nextSurface = sequence.find((surface) => !completedIds.has(surface.id));
+    const selectedSurface = resolveWorkplanSurfaceAnswer(sequence, answers.feature_surface);
+    if (!nextSurface) {
+        return {
+            status: "workplan-complete",
+            exitCode: 7,
+            request,
+            sequence: sequence.map((surface) => ({
+                id: surface.id,
+                order: surface.order,
+                outcome: surface.outcome,
+                label: surface.label,
+                completed: completedIds.has(surface.id),
+            })),
+            nextStep: "All active blueprint surfaces are already recorded complete. Run one final `vise check .`, `vise validate .`, and `vise run-sensors .` instead of initializing another surface.",
+        };
+    }
+    if (!answers.feature_surface || !selectedSurface) {
+        return {
+            status: "needs-workplan-surface",
+            exitCode: 7,
+            request,
+            expectedSurface: {
+                id: nextSurface.id,
+                order: nextSurface.order,
+                outcome: nextSurface.outcome,
+                label: nextSurface.label,
+            },
+            sequence: sequence.map((surface) => ({
+                id: surface.id,
+                order: surface.order,
+                outcome: surface.outcome,
+                label: surface.label,
+                completed: completedIds.has(surface.id),
+            })),
+            nextStep: `This request has a signed multi-surface blueprint. Initialize the next pending surface with: ${nextSurface.initCommand}. ` +
+                "After implementing it and getting `vise check .` green, run the matching `vise workplan complete` command before moving to the next surface.",
+        };
+    }
+    if (selectedSurface.id !== nextSurface.id) {
+        return {
+            status: "needs-workplan-order",
+            exitCode: 7,
+            request,
+            attemptedSurface: {
+                id: selectedSurface.id,
+                order: selectedSurface.order,
+                outcome: selectedSurface.outcome,
+                label: selectedSurface.label,
+            },
+            expectedSurface: {
+                id: nextSurface.id,
+                order: nextSurface.order,
+                outcome: nextSurface.outcome,
+                label: nextSurface.label,
+            },
+            sequence: sequence.map((surface) => ({
+                id: surface.id,
+                order: surface.order,
+                outcome: surface.outcome,
+                label: surface.label,
+                completed: completedIds.has(surface.id),
+            })),
+            nextStep: `Do not jump to "${selectedSurface.id}" before "${nextSurface.id}" is complete. Run: ${nextSurface.initCommand}. ` +
+                "Each active blueprint surface must be implemented, checked, synced, and recorded in order so the final app does not collapse to one narrow social surface.",
+        };
+    }
+    return null;
+}
+function resolveWorkplanSurfaceAnswer(sequence, answer) {
+    const normalized = (answer ?? "").trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    return sequence.find((surface) => surface.id.toLowerCase() === normalized)
+        ?? sequence.find((surface) => surface.label.toLowerCase() === normalized)
+        ?? sequence.find((surface) => surface.label.toLowerCase().includes(normalized));
+}
 async function readWorkplanProgress(repoRoot) {
     try {
         return JSON.parse(await readFile(workplanProgressPath(repoRoot), "utf8"));
@@ -1628,9 +2160,6 @@ function workplanSurfaceSnapshotDir(repoRoot, surfaceId) {
     }
     return path.join(sidecarPath(repoRoot), "workplan-snapshots", safeSurfaceId);
 }
-function sidecarPath(repoRoot) {
-    return path.join(repoRoot, "sp-vise");
-}
 function repoRelativePath(repoRoot, filePath) {
     return path.relative(repoRoot, filePath).split(path.sep).join("/");
 }
@@ -1791,6 +2320,22 @@ function hasFlag(args, name) {
     }
     return false;
 }
+function stripAnswerKey(args, key) {
+    const out = [];
+    const valuePrefix = `${key}=`;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--answer" && typeof args[index + 1] === "string" && args[index + 1].startsWith(valuePrefix)) {
+            index += 1;
+            continue;
+        }
+        if (arg?.startsWith("--answer=") && arg.slice("--answer=".length).startsWith(valuePrefix)) {
+            continue;
+        }
+        out.push(arg);
+    }
+    return out;
+}
 function keyValueFlag(args, name) {
     const pairs = flagValues(args, name);
     const result = {};
@@ -1838,6 +2383,8 @@ function doctorResult() {
     return {
         package: packageName,
         version: packageVersion,
+        buildSource,
+        packageRoot,
         status: nodeMajor >= 18 ? "ok" : "unsupported-node",
         node: process.versions.node,
         requiredNodeMajor: ">=18",