@amityco/social-plus-vise 1.2.0 → 1.4.0

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, initEngagement, initEngagementTool, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
-import { designCheckTool, designExtractTool, designInitTokensTool, designPreviewTool, designReferenceTool } from "./tools/design.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, 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,12 +20,16 @@ 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";
 import { creativeAcceptTool, creativeBriefTool } from "./tools/creative.js";
 import { uxHarnessTool } from "./tools/uxHarness.js";
-import { packageName, packageVersion } from "./version.js";
+import { exploreRequest } from "./explore.js";
+import { renderHuman, wantsHumanFormat } from "./humanFormat.js";
+import { buildSource, packageName, packageRoot, packageVersion } from "./version.js";
+const SUPPORT_URL = "mailto:support@social.plus";
 const tools = new Map([
     searchDocsTool,
     getDocPageTool,
@@ -46,11 +53,13 @@ const tools = new Map([
     showEngagementTool,
     resolveRequestTool,
     runSensorsTool,
+    smokeTool,
     validateSetupTool,
     suggestPatchTool,
     debugIssueTool,
     designExtractTool,
     designCheckTool,
+    designContrastTool,
     designPreviewTool,
     designReferenceTool,
     designInitTokensTool,
@@ -107,14 +116,14 @@ async function handleCli(args) {
         console.log(helpText(args[1]));
         return "exit";
     }
-    if (command === "doctor" || command === "--doctor") {
-        console.log(JSON.stringify(doctorResult(), null, 2));
-        return "exit";
-    }
     if (isHelpRequest(args)) {
         console.log(helpText(command));
         return "exit";
     }
+    if (command === "doctor" || command === "--doctor") {
+        emitResult("doctor", doctorResult(), args);
+        return "exit";
+    }
     try {
         if (command === "install-skill" || command === "install_skill") {
             console.log(JSON.stringify(await installSkill(args.slice(1)), null, 2));
@@ -286,15 +295,10 @@ async function handleCli(args) {
         }
         if (command === "plan" || command === "plan-integration") {
             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);
-            }
+            const result = await planIntegrationTool.call(input);
+            const text = result.content.map((item) => item.text).join("\n");
+            const payload = JSON.parse(text);
+            emitResult("plan", hasFlag(args, "summary") ? planSummary(payload) : payload, args);
             return "exit";
         }
         if (command === "plan-harness") {
@@ -318,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";
         }
@@ -345,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,21 +444,47 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "init") {
-            assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer", "allow-unresolved-intake"], "init");
-            const result = await initCompliance(positionalRepoPath(args.slice(1)), requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer"), { allowUnresolvedIntake: hasFlag(args, "allow-unresolved-intake") });
+            assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer", "allow-unresolved-intake", "baseline"], "init");
+            const initRepo = positionalRepoPath(args.slice(1));
+            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;
             }
+            if (hasFlag(args, "baseline") && result.status === "initialized") {
+                result.baseline_recorded = await recordBaseline(initRepo);
+            }
             console.log(JSON.stringify(result, null, 2));
             return "exit";
         }
         if (command === "check") {
-            assertOnlyKnownFlags(args, ["ci"], "check");
-            const result = await checkCompliance(positionalRepoPath(args.slice(1)));
-            console.log(JSON.stringify(hasFlag(args, "ci") ? ciCheckResult(result) : result, null, 2));
+            assertOnlyKnownFlags(args, ["ci", "format", "new-only"], "check");
+            const result = await checkCompliance(positionalRepoPath(args.slice(1)), { newOnly: hasFlag(args, "new-only") });
+            emitResult("check", hasFlag(args, "ci") ? ciCheckResult(result) : result, args);
             process.exitCode = result.exitCode;
             return "exit";
         }
+        if (command === "baseline") {
+            assertOnlyKnownFlags(args, [], "baseline");
+            console.log(JSON.stringify(await recordBaseline(positionalRepoPath(args.slice(1))), null, 2));
+            return "exit";
+        }
         if (command === "sync") {
             assertOnlyKnownFlags(args, [], "sync");
             console.log(JSON.stringify(await syncCompliance(positionalRepoPath(args.slice(1))), null, 2));
@@ -452,13 +504,26 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "explain") {
-            assertOnlyKnownFlags(args, [], "explain");
-            console.log(JSON.stringify(await explainRule(requiredPositionalText(args.slice(1), "explain requires a rule id.")), null, 2));
+            assertOnlyKnownFlags(args, ["format"], "explain");
+            const explainRuleId = positionalValues(args.slice(1))[0];
+            const payload = explainRuleId ? await explainRule(explainRuleId) : await listRules();
+            emitResult("explain", payload, args);
+            return "exit";
+        }
+        if (command === "explore") {
+            assertOnlyKnownFlags(args, ["request", "platform", "format"], "explore");
+            const request = flagValue(args, "request") ??
+                requiredPositionalText(args.slice(1), 'explore requires a request, e.g. `vise explore "add a social feed"`.');
+            emitResult("explore", exploreRequest(request, flagValue(args, "platform")), args);
             return "exit";
         }
         if (command === "status") {
-            assertOnlyKnownFlags(args, [], "status");
-            console.log(JSON.stringify(await statusCompliance(positionalRepoPath(args.slice(1))), null, 2));
+            assertOnlyKnownFlags(args, ["format", "new-only"], "status");
+            const result = await statusCompliance(positionalRepoPath(args.slice(1)), { newOnly: hasFlag(args, "new-only") });
+            emitResult("status", result, args);
+            if (typeof result.exitCode === "number") {
+                process.exitCode = result.exitCode;
+            }
             return "exit";
         }
         if (command === "engagement") {
@@ -512,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, {
@@ -538,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";
         }
@@ -595,7 +671,9 @@ Re-plan with collected answers (repeat --answer for each intake question):
   vise plan . --request "Add a social feed" \\
     --answer feed_scope=community \\
     --answer feed_target=existing\\ communityId \\
-    --answer target_screen_or_route=app/feed/page.tsx`;
+    --answer target_screen_or_route=app/feed/page.tsx
+
+Output is JSON by default (for agents/CI). Add --format human for a readable plan summary.`;
     }
     if (command === "creative") {
         return `${packageName} creative
@@ -610,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.
@@ -695,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
@@ -789,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
@@ -844,7 +944,9 @@ Usage:
 Check the current source and recorded attestations against the compliance contract. Read-only.
 
 Usage:
-  vise check [repoPath] [--ci]`;
+  vise check [repoPath] [--ci] [--format human]
+
+Output is JSON by default (for agents/CI). Add --format human for a readable verdict summary.`;
     }
     if (command === "sync") {
         return `${packageName} sync
@@ -860,23 +962,45 @@ Usage:
 Record a host-agent or local-human attestation for one compliance rule.
 
 Usage:
-  vise attest [repoPath] --rule sdk.init.at-startup --confidence high --signer host-agent --evidence-file evidence.json --rationale "Why this rule is satisfied."`;
+  vise attest [repoPath] --rule typescript.client.region --confidence high --signer host-agent --evidence-file evidence.json --rationale "Why this rule is satisfied."`;
     }
     if (command === "explain") {
         return `${packageName} explain
 
-Explain one compliance rule.
+Explain one compliance rule, or list every valid rule id when run with no id.
+
+Usage:
+  vise explain [--format human]      List all rule ids (public + contract) with where each applies
+  vise explain typescript.client.region [--format human]`;
+    }
+    if (command === "explore") {
+        return `${packageName} explore
+
+Discover what social.plus offers for a request — before any project or credentials exist. Read-only:
+maps the request to a candidate outcome (or lists the full menu when it can't), and for each shows the
+capabilities involved, the canonical docs, and the command to start. No project, no API key, no writes.
 
 Usage:
-  vise explain sdk.init.at-startup`;
+  vise explore "add a social feed" [--platform typescript] [--format human]`;
+    }
+    if (command === "doctor") {
+        return `${packageName} doctor
+
+Print install diagnostics (Node version, transport, docs source, registered tools).
+Read-only. JSON by default; --format human for a readable summary.
+
+Usage:
+  vise doctor [--format human]
+
+If diagnostics report a problem, see ${SUPPORT_URL}`;
     }
     if (command === "status") {
         return `${packageName} status
 
-Print a compact compliance summary.
+Print a compact compliance summary. JSON by default; --format human for a readable verdict.
 
 Usage:
-  vise status [repoPath]`;
+  vise status [repoPath] [--format human]`;
     }
     if (command === "design") {
         return `${packageName} design
@@ -897,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
@@ -925,14 +1050,17 @@ contractual record of which broad-social outcomes are in scope for this project.
 
 Usage:
   vise engagement init [repoPath] --tier <free|pro|partner> --customer-id <id> --scope <outcome,...>
-  vise engagement init [repoPath] --scope feed,communities --target-completion 2026-12-31 \\
+  vise engagement init [repoPath] --scope add-feed,add-community --target-completion 2026-12-31 \\
     --reviewer-name "Jane Doe" --reviewer-email jane@example.com --evidence-upload-consent
   vise engagement show [repoPath]
 
 Flags (init):
   --tier <free|pro|partner>   Engagement tier (validated).
   --customer-id <id>          Customer identifier recorded in the artifact.
-  --scope <outcome,...>       In-scope broad-social outcomes (repeatable; comma-separated).
+  --scope <outcome,...>       In-scope outcomes, comma-separated. One or more of: setup-sdk,
+                              setup-push, setup-live-data, add-feed, add-comments, add-chat,
+                              add-community, add-follow, add-moderation, add-notifications,
+                              troubleshoot, validate-setup.
   --target-completion <date>  Target completion date, YYYY-MM-DD.
   --reviewer-name <name>      Human reviewer recorded on the engagement.
   --reviewer-email <email>    Human reviewer contact.
@@ -950,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
@@ -958,10 +1086,12 @@ Usage:
   vise learning record [repoPath] Record a local-only learning event
   vise learning show [repoPath]    Show local learning summary
   vise debug [repoPath] --error ... Debug an SDK-specific runtime error and emit a repair brief
+  vise explore "<request>"         Discover what social.plus offers for a request (no project/credentials needed)
   vise plan [repoPath] --request "..." Create an implementation plan
   vise workplan next [repoPath] --request "..." Get the next broad-social surface to implement
-  vise init [repoPath] --request "..." Initialize compliance sidecar
-  vise check [repoPath]            Check compliance contract
+  vise init [repoPath] --request "..." Initialize compliance sidecar (add --baseline on a brownfield app)
+  vise check [repoPath]            Check compliance contract (add --new-only to gate on findings since the baseline)
+  vise baseline [repoPath]         Snapshot pre-existing findings so check --new-only gates only new ones
   vise sync [repoPath]             Persist deterministic-pass evidence
   vise attest [repoPath] --rule ... Record a compliance attestation
   vise explain <ruleId>            Explain one compliance rule
@@ -999,6 +1129,16 @@ async function printToolResult(tool, input) {
     console.log(text);
     return { result, text };
 }
+function emitResult(command, payload, args) {
+    if (wantsHumanFormat(flagValue(args, "format"))) {
+        const human = renderHuman(command, payload);
+        if (human !== null) {
+            console.log(human);
+            return;
+        }
+    }
+    console.log(JSON.stringify(payload, null, 2));
+}
 async function planCliInput(args) {
     const subArgs = args.slice(1);
     const requestFromFlag = flagValue(args, "request");
@@ -1365,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));
@@ -1382,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,
@@ -1396,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,
@@ -1405,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 .",
@@ -1417,23 +1822,101 @@ 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 check = await greenWorkplanCheck(repoRoot, surfaceId);
+    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);
     const base = existing?.request === request
@@ -1475,15 +1958,45 @@ 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,
     };
 }
-async function greenWorkplanCheck(repoRoot, surfaceId) {
+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 {
         check = await checkCompliance(repoRoot);
@@ -1492,6 +2005,9 @@ async function greenWorkplanCheck(repoRoot, surfaceId) {
         const message = error instanceof Error ? error.message : String(error);
         throw new Error(`Cannot mark "${surfaceId}" complete because the current compliance check could not run. Run the focused \`vise init\` command for this surface first, then \`vise check .\`. ${message}`);
     }
+    if (expectedOutcome && check.outcome !== expectedOutcome) {
+        throw new Error(`Cannot mark "${surfaceId}" complete: the sp-vise sidecar is currently scoped to outcome "${check.outcome}", not this surface's outcome "${expectedOutcome}". Each workplan surface has its own sidecar scope — run this surface's focused \`vise init\` command (it sets \`--answer feature_surface=${surfaceId}\`) and \`vise check .\` before recording it. (The check reported "${check.status}" only because it ran against the other surface's contract.)`);
+    }
     if (check.status !== "green") {
         throw new Error(`Cannot mark "${surfaceId}" complete because \`vise check\` returned "${check.status}" (exit ${check.exitCode}). Resolve the check result before recording workplan progress.`);
     }
@@ -1541,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"));
@@ -1564,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("/");
 }
@@ -1584,7 +2177,14 @@ function ciCheckResult(result) {
             enabled: true,
             passed: result.exitCode === 0,
             exitCode: result.exitCode,
-            blockingResultStatuses: ["contract-drift", "blocked", "deterministic-failures", "needs-attestation"],
+            blockingResultStatuses: [
+                "contract-drift",
+                "blocked",
+                "deterministic-failures",
+                "needs-attestation",
+                "completeness-gap",
+                "selected-capability-failures",
+            ],
             message: result.exitCode === 0 ? "Compliance green for CI." : `Compliance failed for CI with status: ${result.status}.`,
         },
     };
@@ -1594,7 +2194,7 @@ function positionalRepoPath(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 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", "tier", "customer-id", "scope", "target-completion", "reviewer-name", "reviewer-email"]);
     const values = [];
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
@@ -1720,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 = {};
@@ -1767,6 +2383,8 @@ function doctorResult() {
     return {
         package: packageName,
         version: packageVersion,
+        buildSource,
+        packageRoot,
         status: nodeMajor >= 18 ? "ok" : "unsupported-node",
         node: process.versions.node,
         requiredNodeMajor: ">=18",
@@ -1775,5 +2393,6 @@ function doctorResult() {
         docsBaseUrl: process.env.SOCIAL_PLUS_DOCS_BASE_URL ?? "https://learn.social.plus",
         transport: "stdio",
         tools: Array.from(tools.keys()),
+        support: SUPPORT_URL,
     };
 }