@amityco/social-plus-vise 0.14.5 → 0.14.6

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@amityco/social-plus-vise` are documented in this file.
 
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.14.6 — 2026-06-05
+
+**Theme:** Intake questions must reach the human before implementation.
+
+### Added
+- **`vise init` now enforces unresolved blocking intake:** normal init returns `status: "needs-clarification"` and exits 7 when required planning questions are still unanswered. This prevents host agents from skipping surfaced questions and writing a compliance sidecar as if scope were resolved.
+- **`sp-vise/intake.json`:** successful init records the request, outcome, answers, remaining blocking count, and whether unresolved intake was explicitly acknowledged.
+- **`--allow-unresolved-intake`:** explicit bypass for retrospective benchmark/harness initialization only. The acknowledgement is recorded in `sp-vise/intake.json`; customer implementations should answer the blocking questions instead.
+
+### Fixed
+- **Host-project `style.css` design extraction:** `vise design extract --from-project` now detects non-theme-named CSS files that declare custom properties, so common roots like `style.css` produce strong host-project design contracts instead of empty weak contracts.
+- **Design-source wording:** `vise plan` now labels host-project design contracts as the host app's design system, not the customer's prototype, and empty contracts tell the agent to ask for the correct design source instead of implying tokens exist.
+
+### Docs
+- **Skill and tool docs now require surfacing blocking intake questions** before implementation, and release smoke guidance uses `--allow-unresolved-intake` only where a disposable retrospective init is intended.
+
+---
+
 ## 0.14.5 — 2026-06-04
 
 **Theme:** Optional feed capabilities become explicit opt-in sensors.

package/README.md

@@ -86,9 +86,44 @@ Correctness is gated by deterministic rules or attestations. Baseline completene
 Vise has two deliberately separate roles:
 
 - **Customer integration helper:** runs inside customer projects to inspect, plan, validate, and sensor-check social.plus SDK integrations.
-- **Block Factory SDK facts provider:** planned internal mode for social.plus Block Factory to verify SDK capabilities, symbols, and model schemas before reusable blocks are generated or released.
+- **Block Factory SDK facts provider:** internal mode for social.plus Block Factory to verify SDK capabilities, symbols, and model schemas before reusable blocks are generated or released.
+- **Block installer governance:** customer-project workflow that consumes a Block Factory registry, plans safe package/source changes, writes `sp-vise/blocks.json`, and validates installed block state.
 
-Vise owns SDK truth and customer-project governance. social.plus Block Factory owns block contracts, package adapters, previews, conformance tests, and release readiness. See [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md) for the internal provider-side plan.
+Vise owns SDK truth and customer-project governance. social.plus Block Factory owns block contracts, package adapters, registry metadata, previews, conformance tests, and release readiness. See [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md) for the internal provider-side plan.
+
+### Block Factory user experience
+
+When Vise is used with social.plus Block Factory, the customer experience should feel like asking an AI agent for a social capability rather than manually assembling SDK calls and UI states:
+
+> "Add social.plus comments to this app and match my existing design system."
+
+The agent uses Vise to turn that request into a governed install workflow:
+
+```sh
+vise blocks list --registry ./registry/blocks.json --format json
+vise blocks plan . --block comments --registry ./registry/blocks.json --format json
+vise blocks add . --block comments --registry ./registry/blocks.json --package-source npm --dry-run
+vise blocks add . --block comments --registry ./registry/blocks.json --package-source npm --apply
+vise blocks validate . --block comments --registry ./registry/blocks.json --format json
+vise run-sensors --dry-run
+```
+
+What Vise does:
+
+- Inspects the customer project and detects the target platform.
+- Reads Block Factory registry metadata without owning block product data.
+- Plans package, source-anchor, sidecar, design-contract, and sensor requirements.
+- Applies changes only to package manifests, `sp-vise/blocks.json`, and source files with explicit install anchors.
+- Returns `needs-review` when a brownfield project has no safe install anchor.
+- Validates installed block state and detects drift after future code changes.
+
+Required customer or agent actions:
+
+- Choose the block id and package source.
+- Review the dry-run plan before using `--apply`.
+- Add explicit install anchors when Vise cannot safely edit the project.
+- Keep `sp-vise/blocks.json` committed so future validation has state to compare.
+- Run the target project's normal build, lint, test, and Vise sensors before shipping.
 
 ### Design-conformant UI
 
@@ -253,7 +288,7 @@ flowchart LR
     C --> D{Intake<br/>questions?}
     D -->|Yes| E[Agent asks user<br/>for feed target,<br/>design source, etc.]
     D -->|No| F
-    E --> F[Agent runs<br/>vise init]
+    E --> F[Agent runs<br/>vise init<br/>with answers]
     F --> G[Agent runs<br/>vise search-docs<br/>vise get-doc-page]
     G --> H[Agent edits<br/>your code]
     H --> I[Agent runs<br/>vise check]
@@ -266,7 +301,7 @@ flowchart LR
     M --> N[Done.<br/>sp-vise/ contract<br/>committed]
 ```
 
-The flow above is what the skill teaches your AI agent. You — the human — drive intent and approve edits; the agent runs Vise commands deterministically; Vise grounds the agent in real docs and real compliance rules.
+The flow above is what the skill teaches your AI agent. You — the human — drive intent and approve edits; the agent runs Vise commands deterministically; Vise grounds the agent in real docs and real compliance rules. If blocking intake is still unresolved, `vise init` refuses to initialize, returns `status: "needs-clarification"`, and exits 7 so the agent must surface the questions instead of guessing.
 
 ---
 
@@ -280,7 +315,11 @@ The flow above is what the skill teaches your AI agent. You — the human — dr
 | `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
 | `vise plan [path] --request "..."` | Produce a grounded implementation plan with intake questions and docs citations |
 | `vise plan-harness [path] --request "..."` | (Pre-planning step) Build the harness around the request |
-| `vise init [path] --request "..."` | Write the `sp-vise/` compliance contract for this project |
+| `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract after blocking intake is answered; returns `needs-clarification` and exits 7 if required answers are missing |
+| `vise blocks list --registry <path>` | Read a social.plus Block Factory registry |
+| `vise blocks plan [path] --block <id> --registry <path>` | Plan safe block package, source-anchor, sidecar, and sensor changes |
+| `vise blocks add [path] --block <id> --registry <path> [--dry-run\|--apply]` | Dry-run or apply safe block installation inside a customer project |
+| `vise blocks validate [path] [--block <id>] --registry <path>` | Validate installed block sidecar state, package presence, and source anchors |
 
 ### Design contract (UI generation)
 
@@ -423,11 +462,12 @@ jobs:
 
 ## Compliance Contract
 
-After `vise init`, your project gets a `sp-vise/` directory. These files become part of your repo and travel through code review:
+After a successful `vise init`, your project gets a `sp-vise/` directory. If init returns `needs-clarification`, no compliance sidecar is written; answer the blocking questions and run init again. These files become part of your repo and travel through code review:
 
 | File | Created by | What it contains |
 |---|---|---|
 | `sp-vise/compliance.json` | `vise init` | The rules selected for this integration, the Vise version, the ruleset digest, the target app surface, and an optional engagement link. |
+| `sp-vise/intake.json` | `vise init` | The request, outcome, intake answers, remaining blocking count, and any retrospective `--allow-unresolved-intake` acknowledgement. |
 | `sp-vise/attestations/*.json` | `vise sync` (deterministic) or `vise attest` (host-agent / human) | Per-rule evidence: signer, confidence, rationale, cited files (with source fingerprints for drift detection). |
 | `sp-vise/inspection.json` | `vise init` | The platform, monorepo surface, and design-token signals detected at init time. |
 | `sp-vise/design-contract.json` | `vise design extract` | The extracted design contract: declared tokens, breakpoints, advisory components, source file digests (for freshness detection), and a stable digest over design facts. |

package/dist/server.js

@@ -15,6 +15,7 @@ import { inspectProjectTool, validateSetupTool } from "./tools/project.js";
 import { resolveRequestTool, suggestPatchTool } from "./tools/resolve.js";
 import { runSensorsTool } from "./tools/sensors.js";
 import { getSdkFactsTool } from "./tools/sdkFacts.js";
+import { addBlockInstall, listRegistryBlocks, planBlockInstall, validateBlockInstall } from "./tools/blocks.js";
 import { debugIssueTool, debugIssue } from "./tools/debug.js";
 import { packageName, packageVersion } from "./version.js";
 const tools = new Map([
@@ -217,9 +218,62 @@ async function handleCli(args) {
             });
             return "exit";
         }
+        if (command === "blocks") {
+            const sub = args[1];
+            const subArgs = args.slice(2);
+            if (sub === "list") {
+                assertOnlyKnownFlags(subArgs, ["registry", "format"], "blocks list");
+                assertJsonFormat(subArgs, "blocks list");
+                console.log(JSON.stringify(await listRegistryBlocks(requiredFlagValue(subArgs, "registry", "blocks list requires --registry.")), null, 2));
+                return "exit";
+            }
+            if (sub === "plan") {
+                assertOnlyKnownFlags(subArgs, ["block", "surface", "surface-path", "registry", "format"], "blocks plan");
+                assertJsonFormat(subArgs, "blocks plan");
+                console.log(JSON.stringify(await planBlockInstall({
+                    repoPath: positionalRepoPath(subArgs),
+                    blockId: requiredFlagValue(subArgs, "block", "blocks plan requires --block."),
+                    registryPath: requiredFlagValue(subArgs, "registry", "blocks plan requires --registry."),
+                    surfacePath: flagValue(subArgs, "surface") ?? flagValue(subArgs, "surface-path"),
+                }), null, 2));
+                return "exit";
+            }
+            if (sub === "add") {
+                assertOnlyKnownFlags(subArgs, ["block", "surface", "surface-path", "registry", "package-source", "dry-run", "apply", "format"], "blocks add");
+                assertJsonFormat(subArgs, "blocks add");
+                console.log(JSON.stringify(await addBlockInstall({
+                    repoPath: positionalRepoPath(subArgs),
+                    blockId: requiredFlagValue(subArgs, "block", "blocks add requires --block."),
+                    registryPath: requiredFlagValue(subArgs, "registry", "blocks add requires --registry."),
+                    surfacePath: flagValue(subArgs, "surface") ?? flagValue(subArgs, "surface-path"),
+                    packageSource: flagValue(subArgs, "package-source"),
+                    dryRun: hasFlag(subArgs, "dry-run"),
+                    apply: hasFlag(subArgs, "apply"),
+                }), null, 2));
+                return "exit";
+            }
+            if (sub === "validate") {
+                assertOnlyKnownFlags(subArgs, ["block", "surface", "surface-path", "registry", "format"], "blocks validate");
+                assertJsonFormat(subArgs, "blocks validate");
+                console.log(JSON.stringify(await validateBlockInstall({
+                    repoPath: positionalRepoPath(subArgs),
+                    blockId: flagValue(subArgs, "block"),
+                    registryPath: requiredFlagValue(subArgs, "registry", "blocks validate requires --registry."),
+                    surfacePath: flagValue(subArgs, "surface") ?? flagValue(subArgs, "surface-path"),
+                }), null, 2));
+                return "exit";
+            }
+            console.error(`Unknown blocks subcommand: ${sub ?? "(none)"}. Expected "list", "plan", "add", or "validate".`);
+            process.exitCode = 1;
+            return "exit";
+        }
         if (command === "init") {
-            assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer"], "init");
-            console.log(JSON.stringify(await initCompliance(positionalRepoPath(args.slice(1)), requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer")), null, 2));
+            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") });
+            if (result.status === "needs-clarification" && typeof result.exitCode === "number") {
+                process.exitCode = result.exitCode;
+            }
+            console.log(JSON.stringify(result, null, 2));
             return "exit";
         }
         if (command === "check") {
@@ -494,6 +548,20 @@ Usage:
   vise sdk-facts --platform typescript --capability comments --format json
   vise sdk-facts --platform react-native --capability reactions --include-symbols
   vise sdk-facts --platform android --surface-dir ./sdk-surface --format json`;
+    }
+    if (command === "blocks") {
+        return `${packageName} blocks
+
+Install and validate social.plus Block Factory blocks inside customer projects.
+
+Usage:
+  vise blocks list --registry <path> --format json
+  vise blocks plan <repoPath> --block comments --registry <path> --format json
+  vise blocks add <repoPath> --block comments --registry <path> --package-source <npm|path|tarball> [--dry-run|--apply]
+  vise blocks validate <repoPath> [--block comments] --registry <path> --format json
+
+Safety:
+  Dry-run is the default. Apply mode only edits package manifests, explicit source anchors, and sp-vise/blocks.json.`;
     }
     if (command === "init") {
         return `${packageName} init
@@ -502,7 +570,9 @@ Initialize the local sp-vise compliance sidecar for one integration request.
 
 Usage:
   vise init [repoPath] --request "Add a social feed" [--surface apps/web]
-  vise init [repoPath] --request "Add a social feed" --answer feed_optional_capabilities=post-poll-creation`;
+  vise init [repoPath] --request "Add a social feed" --answer feed_target="existing app community picker"
+  vise init [repoPath] --request "Add a social feed" --answer feed_optional_capabilities=post-poll-creation
+  vise init [repoPath] --request "Add a social feed" --allow-unresolved-intake`;
     }
     if (command === "check") {
         return `${packageName} check
@@ -605,6 +675,7 @@ Usage:
   vise validate [repoPath]         Validate setup and common risks
   vise run-sensors [repoPath]      Run detected project sensors
   vise sdk-facts --platform ...    Internal SDK surface facts for Block Factory
+  vise blocks ...                  Install and validate Block Factory blocks
   vise design extract <prototype>  Extract a design contract from an HTML/CSS prototype
   vise design check [repoPath]     Advisory (non-blocking) UI-vs-contract conformance report
   vise design preview [repoPath]   Write an HTML visual review of the contract + conformance
@@ -858,7 +929,7 @@ function ciCheckResult(result) {
     };
 }
 function positionalRepoPath(args) {
-    const flagsWithValues = new Set(["request", "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"]);
+    const flagsWithValues = new Set(["request", "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"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -880,7 +951,7 @@ function positionalRepoPath(args) {
 }
 function requiredPositionalText(args, message) {
     const values = [];
-    const flagsWithValues = new Set(["request", "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"]);
+    const flagsWithValues = new Set(["request", "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"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -937,6 +1008,12 @@ function requiredFlagValue(args, name, message) {
     }
     return value;
 }
+function assertJsonFormat(args, commandName) {
+    const format = flagValue(args, "format") ?? "json";
+    if (format !== "json") {
+        throw new Error(`${commandName} currently supports --format json only.`);
+    }
+}
 function optionalNumberFlag(args, name) {
     const value = flagValue(args, name);
     if (!value) {

package/dist/tools/blocks.js

@@ -0,0 +1,385 @@
+import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { packageVersion } from "../version.js";
+import { inspectProject } from "./project.js";
+import { detectCommandSensors } from "./harness.js";
+import { readDesignContract } from "./design.js";
+const registryPlatformByVisePlatform = {
+    typescript: "react",
+    "react-native": "react-native",
+    flutter: "flutter",
+};
+export async function listRegistryBlocks(registryPath) {
+    const registry = await loadRegistry(registryPath);
+    return {
+        source: "social-plus-block-factory",
+        mode: "block-registry",
+        schemaVersion: registry.schemaVersion,
+        blocks: registry.blocks.map((block) => ({
+            blockId: block.blockId,
+            version: block.version,
+            status: block.status,
+            surfaces: block.surfaces,
+            requiredSdkCapabilities: block.requiredSdkCapabilities,
+            events: block.events,
+        })),
+    };
+}
+export async function planBlockInstall(options) {
+    return buildInstallPlan(options, "plan");
+}
+export async function addBlockInstall(options) {
+    const mode = options.apply ? "apply" : "dry-run";
+    const plan = await buildInstallPlan(options, mode);
+    if (!options.apply) {
+        return plan;
+    }
+    if (plan.status !== "ready") {
+        return {
+            ...plan,
+            applied: false,
+            reason: "Block install needs review before Vise can safely write files.",
+        };
+    }
+    const repoPath = requiredRepoPath(options);
+    const filesTouched = [];
+    filesTouched.push(...(await applyPackageChange(repoPath, plan)));
+    filesTouched.push(...(await applySourceChanges(repoPath, plan)));
+    filesTouched.push(await writeBlocksSidecar(repoPath, plan, options.packageSource ?? "npm", filesTouched));
+    return {
+        ...plan,
+        applied: true,
+        filesTouched,
+    };
+}
+export async function validateBlockInstall(options) {
+    if (!options.blockId) {
+        const repoPath = requiredRepoPath(options);
+        const registry = await loadRegistry(options.registryPath);
+        const sidecar = await readSidecar(repoPath);
+        const installed = sidecar?.installed ?? [];
+        const knownBlocks = new Set(registry.blocks.map((block) => block.blockId));
+        const findings = installed
+            .filter((entry) => !knownBlocks.has(entry.blockId))
+            .map((entry) => ({
+            ruleId: "blocks.registry.known",
+            severity: "warning",
+            message: `Installed sidecar entry references unknown registry block ${entry.blockId}.`,
+            recommendation: "Update the Block Factory registry or remove stale block sidecar state.",
+        }));
+        if (installed.length === 0) {
+            findings.push({
+                ruleId: "blocks.sidecar.installed",
+                severity: "warning",
+                message: "No installed block sidecar entries exist.",
+                recommendation: "Run `vise blocks add <repoPath> --block <id> --apply` after reviewing the dry-run plan.",
+            });
+        }
+        return {
+            status: findings.some((finding) => finding.severity === "error") ? "needs-review" : "ready",
+            mode: "validate",
+            registryBlocks: registry.blocks.map((block) => block.blockId),
+            sidecarPath: path.join("sp-vise", "blocks.json"),
+            sidecarInstalled: installed,
+            findings,
+        };
+    }
+    const plan = await buildInstallPlan(options, "validate");
+    const repoPath = requiredRepoPath(options);
+    const sidecar = await readSidecar(repoPath);
+    const installed = (sidecar?.installed ?? []).filter((entry) => !options.blockId || entry.blockId === options.blockId);
+    const findings = [];
+    if (installed.length === 0) {
+        findings.push({
+            ruleId: "blocks.sidecar.installed",
+            severity: "warning",
+            message: options.blockId ? `No sidecar entry exists for block ${options.blockId}.` : "No installed block sidecar entries exist.",
+            recommendation: "Run `vise blocks add <repoPath> --block <id> --apply` after reviewing the dry-run plan.",
+        });
+    }
+    if (plan.packageChange.alreadyPresent === false) {
+        findings.push({
+            ruleId: "blocks.package.present",
+            severity: "error",
+            message: `Required package dependency is missing: ${plan.packageChange.dependency}.`,
+            recommendation: `Install ${plan.packageChange.dependency} in ${plan.packageChange.file}.`,
+        });
+    }
+    for (const targetFile of plan.targetFiles) {
+        if (targetFile.operation === "needs-review") {
+            findings.push({
+                ruleId: "blocks.anchor.present",
+                severity: "error",
+                message: `Missing safe install anchor ${targetFile.anchor} in ${targetFile.path}.`,
+                recommendation: "Add an explicit social.plus block install anchor or install the block manually and re-run validation.",
+            });
+        }
+    }
+    const hasError = findings.some((finding) => finding.severity === "error");
+    return {
+        ...plan,
+        status: hasError ? "needs-review" : plan.status,
+        validationStatus: hasError ? "failed" : "passed",
+        sidecarInstalled: installed,
+        findings,
+    };
+}
+async function buildInstallPlan(options, mode) {
+    const repoPath = requiredRepoPath(options);
+    const registry = await loadRegistry(options.registryPath);
+    const block = findBlock(registry, options.blockId);
+    const inspection = await inspectProject(repoPath, options.surfacePath);
+    const platform = inspection.platforms[0] ?? "unknown";
+    const registryPlatform = registryPlatformByVisePlatform[platform];
+    const sensors = await detectCommandSensors(inspection.effectiveRoot, inspection.platforms);
+    const stopConditions = [];
+    if (!registryPlatform) {
+        stopConditions.push(`Unsupported Vise blocks installer platform: ${platform}. Supported installer platforms: react, react-native, flutter.`);
+    }
+    const packageInfo = registryPlatform ? block.packages[registryPlatform] : undefined;
+    if (!packageInfo || !registryPlatform) {
+        stopConditions.push(`Block ${block.blockId} does not provide installer metadata for detected platform ${platform}.`);
+    }
+    const safePackage = packageInfo ?? {
+        packageName: "",
+        dependencyName: "",
+        publicEntrypoint: "",
+        importName: "",
+        installAnchor: "",
+    };
+    const packageChange = await packageChangeFor(inspection.effectiveRoot, registryPlatform, safePackage, options.packageSource);
+    const targetFiles = await targetFilesFor(inspection.effectiveRoot, block.blockId, registryPlatform, safePackage);
+    for (const targetFile of targetFiles) {
+        if (targetFile.operation === "needs-review") {
+            stopConditions.push(`Missing safe install anchor ${targetFile.anchor} in ${targetFile.path}.`);
+        }
+    }
+    return {
+        status: stopConditions.length > 0 ? "needs-review" : "ready",
+        mode,
+        block: {
+            id: block.blockId,
+            version: block.version,
+            status: block.status,
+        },
+        platform,
+        registryPlatform: registryPlatform ?? "react",
+        package: safePackage,
+        packageSource: options.packageSource,
+        packageChange,
+        targetFiles,
+        sensors: sensors.map((sensor) => ({ name: sensor.name, command: sensor.command, source: sensor.source })),
+        stopConditions,
+        sidecarPath: path.join("sp-vise", "blocks.json"),
+    };
+}
+async function loadRegistry(registryPath) {
+    if (!registryPath) {
+        throw new Error("blocks command requires --registry <path>.");
+    }
+    const resolved = path.resolve(registryPath);
+    if (!(await exists(resolved))) {
+        throw new Error(`Block registry not found: ${registryPath}. Local registry paths are supported in this MVP.`);
+    }
+    const registryFile = (await stat(resolved)).isDirectory() ? path.join(resolved, "blocks.json") : resolved;
+    const registry = JSON.parse(await readFile(registryFile, "utf8"));
+    validateRegistry(registry, registryFile);
+    return registry;
+}
+function validateRegistry(registry, registryFile) {
+    if (registry.schemaVersion !== "2026-06-04.block-registry.v1") {
+        throw new Error(`${registryFile}: unsupported block registry schemaVersion ${registry.schemaVersion}`);
+    }
+    if (!Array.isArray(registry.blocks) || registry.blocks.length === 0) {
+        throw new Error(`${registryFile}: registry.blocks must be a non-empty array`);
+    }
+    for (const block of registry.blocks) {
+        if (!block.blockId || !block.version || !Array.isArray(block.surfaces)) {
+            throw new Error(`${registryFile}: every block requires blockId, version, and surfaces`);
+        }
+    }
+}
+function findBlock(registry, blockId) {
+    if (!blockId) {
+        throw new Error("blocks command requires --block <id> for plan/add/validate.");
+    }
+    const block = registry.blocks.find((entry) => entry.blockId === blockId);
+    if (!block) {
+        throw new Error(`Unknown block in registry: ${blockId}`);
+    }
+    return block;
+}
+async function packageChangeFor(root, platform, packageInfo, packageSource) {
+    if (platform === "flutter") {
+        const file = "pubspec.yaml";
+        const source = await readFile(path.join(root, file), "utf8").catch(() => "");
+        return {
+            file,
+            dependency: packageInfo.dependencyName,
+            value: dependencyValue(root, packageInfo, packageSource, platform),
+            alreadyPresent: new RegExp(`\\b${escapeRegExp(packageInfo.dependencyName)}\\s*:`).test(source),
+        };
+    }
+    const file = "package.json";
+    const packageJson = await readPackageJson(path.join(root, file));
+    return {
+        file,
+        dependency: packageInfo.dependencyName,
+        value: dependencyValue(root, packageInfo, packageSource, platform),
+        alreadyPresent: Boolean(packageJson.dependencies?.[packageInfo.dependencyName]),
+    };
+}
+async function targetFilesFor(root, blockId, platform, packageInfo) {
+    const sourceFile = sourceFileFor(platform);
+    if (!sourceFile) {
+        return [];
+    }
+    const absolutePath = path.join(root, sourceFile);
+    const source = await readFile(absolutePath, "utf8").catch(() => "");
+    const blockPresent = packageInfo.publicEntrypoint !== "" && source.includes(packageInfo.publicEntrypoint);
+    const anchorPresent = packageInfo.installAnchor !== "" && source.includes(packageInfo.installAnchor);
+    return [
+        {
+            path: sourceFile,
+            anchor: packageInfo.installAnchor,
+            operation: blockPresent ? "already-present" : anchorPresent ? "insert" : "needs-review",
+        },
+    ];
+}
+async function applyPackageChange(repoPath, plan) {
+    const filePath = path.join(repoPath, plan.packageChange.file);
+    if (plan.packageChange.alreadyPresent) {
+        return [];
+    }
+    if (plan.registryPlatform === "flutter") {
+        const source = await readFile(filePath, "utf8");
+        const next = addPubspecDependency(source, plan.packageChange.dependency, plan.packageChange.value);
+        await writeFile(filePath, next, "utf8");
+        return [plan.packageChange.file];
+    }
+    const packageJson = await readPackageJson(filePath);
+    packageJson.dependencies = {
+        ...(packageJson.dependencies ?? {}),
+        [plan.packageChange.dependency]: plan.packageChange.value,
+    };
+    await writeFile(filePath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+    return [plan.packageChange.file];
+}
+async function applySourceChanges(repoPath, plan) {
+    const touched = [];
+    for (const targetFile of plan.targetFiles) {
+        if (targetFile.operation !== "insert") {
+            continue;
+        }
+        const filePath = path.join(repoPath, targetFile.path);
+        const source = await readFile(filePath, "utf8");
+        const next = insertBlockSnippet(source, plan);
+        if (next !== source) {
+            await writeFile(filePath, next, "utf8");
+            touched.push(targetFile.path);
+        }
+    }
+    return touched;
+}
+async function writeBlocksSidecar(repoPath, plan, packageSource, filesTouched) {
+    const designContract = await readDesignContract(repoPath);
+    const sidecarPath = path.join(repoPath, "sp-vise", "blocks.json");
+    const existing = await readSidecar(repoPath);
+    const sidecar = existing ?? {
+        schemaVersion: "2026-06-04.vise-blocks-sidecar.v1",
+        viseVersion: packageVersion,
+        generatedAt: new Date().toISOString(),
+        installed: [],
+    };
+    const entry = {
+        blockId: plan.block.id,
+        blockVersion: plan.block.version,
+        platform: plan.registryPlatform,
+        packageSource,
+        filesTouched,
+        designContractDigest: designContract?.digest,
+        sdkFactsVersion: plan.block.version,
+        validationStatus: "installed",
+    };
+    sidecar.viseVersion = packageVersion;
+    sidecar.generatedAt = new Date().toISOString();
+    sidecar.installed = [...sidecar.installed.filter((item) => item.blockId !== plan.block.id), entry];
+    await mkdir(path.dirname(sidecarPath), { recursive: true });
+    await writeFile(sidecarPath, `${JSON.stringify(sidecar, null, 2)}\n`, "utf8");
+    return path.join("sp-vise", "blocks.json");
+}
+async function readSidecar(repoPath) {
+    const sidecarPath = path.join(repoPath, "sp-vise", "blocks.json");
+    try {
+        return JSON.parse(await readFile(sidecarPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function dependencyValue(root, packageInfo, packageSource, platform) {
+    if (!packageSource || packageSource === "npm") {
+        return platform === "flutter" ? "^0.1.0" : "^0.1.0";
+    }
+    if (packageSource.startsWith("file:")) {
+        return packageSource;
+    }
+    const resolved = path.resolve(root, packageSource);
+    return `file:${path.relative(root, resolved)}`;
+}
+function sourceFileFor(platform) {
+    if (platform === "react") {
+        return path.join("src", "render.mjs");
+    }
+    if (platform === "react-native") {
+        return path.join("src", "App.mjs");
+    }
+    if (platform === "flutter") {
+        return path.join("lib", "main.dart");
+    }
+    return null;
+}
+function insertBlockSnippet(source, plan) {
+    if (source.includes(plan.package.publicEntrypoint)) {
+        return source;
+    }
+    if (plan.registryPlatform === "react" || plan.registryPlatform === "react-native") {
+        const importSnippet = `import { ${plan.package.importName} } from "${plan.package.publicEntrypoint}";`;
+        return source.replace(plan.package.installAnchor, `${plan.package.installAnchor}\n${importSnippet}\n// social-plus-vise: ${plan.block.id} source mount requires human review in brownfield apps`);
+    }
+    if (plan.registryPlatform === "flutter") {
+        const importSnippet = `import '${plan.package.publicEntrypoint}';`;
+        return source.replace(plan.package.installAnchor, `${plan.package.installAnchor}\n${importSnippet}\n// social-plus-vise: ${plan.block.id} widget mount requires human review in brownfield apps`);
+    }
+    return source;
+}
+function addPubspecDependency(source, dependencyName, value) {
+    if (!source.includes("dependencies:")) {
+        return `${source.trimEnd()}\n\ndependencies:\n  ${dependencyName}:\n    path: ${value.replace(/^file:/, "")}\n`;
+    }
+    const lines = source.split(/\r?\n/);
+    const insertIndex = lines.findIndex((line) => line.trim() === "dependencies:") + 1;
+    lines.splice(insertIndex, 0, `  ${dependencyName}:`, `    path: ${value.replace(/^file:/, "")}`);
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+async function readPackageJson(filePath) {
+    return JSON.parse(await readFile(filePath, "utf8"));
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function requiredRepoPath(options) {
+    if (!options.repoPath) {
+        throw new Error("blocks command requires repoPath.");
+    }
+    return path.resolve(options.repoPath);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/tools/compliance.js

@@ -2,11 +2,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { assessProjectCompleteness, assessProjectSelectedOptionalCapabilities, selectedOptionalCapabilityIds, } from "../capabilities.js";
-import { classifyOutcome } from "../outcomes.js";
-import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { assessProjectCompleteness, assessProjectSelectedOptionalCapabilities, optionalCapabilityChecklist, selectedOptionalCapabilityIds, } from "../capabilities.js";
+import { classifyOutcome, getOutcomeDefinition, hasAnswer, planContextFor, } from "../outcomes.js";
+import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
-import { readDesignContract } from "./design.js";
+import { buildDesignBrief, readDesignContract } from "./design.js";
 import { inspectProject, validateSetup } from "./project.js";
 const complianceDirName = "sp-vise";
 const attestationsDirName = "attestations";
@@ -26,13 +26,17 @@ export const initComplianceTool = {
                 description: "Optional intake answers from vise plan, including feed_optional_capabilities.",
                 additionalProperties: { type: "string" },
             },
+            allowUnresolvedIntake: {
+                type: "boolean",
+                description: "Explicit acknowledgement for retrospective/harness initialization when blocking intake questions remain unresolved.",
+            },
         },
         required: ["repoPath", "request"],
         additionalProperties: false,
     },
     async call(input) {
         const args = objectInput(input);
-        return textResult(await initCompliance(stringField(args, "repoPath"), stringField(args, "request"), optionalStringField(args, "surfacePath"), answersFromInput(args.answers)));
+        return textResult(await initCompliance(stringField(args, "repoPath"), stringField(args, "request"), optionalStringField(args, "surfacePath"), answersFromInput(args.answers), { allowUnresolvedIntake: optionalBooleanField(args, "allowUnresolvedIntake") }));
     },
 };
 export const checkComplianceTool = {
@@ -242,7 +246,7 @@ async function readEngagement(repoRoot) {
 function engagementPath(repoRoot) {
     return path.join(sidecarDir(repoRoot), "engagement.json");
 }
-export async function initCompliance(repoPath, request, surfacePath, answers = {}) {
+export async function initCompliance(repoPath, request, surfacePath, answers = {}, options = {}) {
     const repoRoot = path.resolve(repoPath);
     const inspection = await inspectProject(repoRoot, surfacePath);
     const outcome = classifyOutcome(request);
@@ -252,6 +256,24 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
     const fileRefs = rules.map(ruleRefForFile); // adds title for human/agent readers
     const engagement = await readEngagement(repoRoot);
     const designContract = await readDesignContract(repoRoot);
+    const intake = intakeAuditFor({
+        request,
+        outcome,
+        platforms: inspection.platforms,
+        designSignals: inspection.designSignals,
+        answers,
+        designBrief: designContract ? buildDesignBrief(designContract) : undefined,
+        allowUnresolvedIntake: options.allowUnresolvedIntake === true,
+    });
+    if (intake.remainingBlocking > 0 && !intake.acknowledged_unresolved_blocking) {
+        return {
+            status: "needs-clarification",
+            exitCode: 7,
+            outcome,
+            intake,
+            nextStep: "Run `vise plan` and surface the blocking intake questions to the customer. Re-run `vise init` with --answer for each blocking question, or pass --allow-unresolved-intake only for retrospective/harness initialization.",
+        };
+    }
     const compliance = {
         schema_version: schemaVersion,
         vise_version: packageVersion,
@@ -276,6 +298,12 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
     };
     await mkdir(attestationsDir(repoRoot), { recursive: true });
     await writeJson(compliancePath(repoRoot), compliance);
+    await writeJson(path.join(sidecarDir(repoRoot), "intake.json"), {
+        generated_at: compliance.generated_at,
+        request,
+        outcome,
+        ...intake,
+    });
     await writeJson(path.join(sidecarDir(repoRoot), "inspection.json"), inspection);
     await writeFile(path.join(sidecarDir(repoRoot), "README.md"), sidecarReadme(compliance), "utf8");
     // Write a frozen check snapshot so agents can see current rule status immediately
@@ -302,10 +330,82 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         engagement_id: engagement?.engagement_id,
         ...(compliance.design_contract && { design_contract: compliance.design_contract }),
         ...(selectedOptionalCapabilities.length > 0 && { selected_optional_capabilities: selectedOptionalCapabilities }),
+        intake: {
+            status: intake.status,
+            remainingBlocking: intake.remainingBlocking,
+            acknowledged_unresolved_blocking: intake.acknowledged_unresolved_blocking,
+            questions: intake.questions,
+            answers: intake.answers,
+        },
         ...(warnings.length > 0 && { warnings }),
         nextStep: "Run vise check, then implement until rules pass deterministically or are attested.",
     };
 }
+function intakeAuditFor(args) {
+    const platform = preferredPlatform(args.platforms);
+    const ctx = planContextFor({
+        request: args.request,
+        outcome: args.outcome,
+        platform,
+        platforms: args.platforms,
+        designSignals: args.designSignals,
+        answers: args.answers,
+    });
+    const questions = [...getOutcomeDefinition(args.outcome).intakeQuestions(ctx)];
+    if (ctx.mentionsDesign && ctx.designSignals.length === 0 && !hasAnswer(ctx.answers, "design_source")) {
+        questions.push({
+            id: "design_source",
+            question: "Where are the app's design tokens, theme, or reusable UI components defined?",
+            why: "The user asked to match the existing design, and no local design source was detected.",
+            required: true,
+            blocksImplementationWhenMissing: true,
+        });
+    }
+    if (ctx.mentionsDesign && ctx.designSignals.length > 0 && !hasAnswer(ctx.answers, "confirm_design_source")) {
+        questions.push({
+            id: "confirm_design_source",
+            question: `Should the social UI use the detected design source(s): ${ctx.designSignals.map((signal) => signal.file).join(", ")}?`,
+            why: "Vise found likely design evidence, but the user or host agent should confirm it is the right source before UI edits.",
+            required: true,
+            blocksImplementationWhenMissing: false,
+            options: ["yes", "use another source"],
+        });
+    }
+    if (args.designBrief &&
+        (args.outcome === "add-feed" || args.outcome === "add-chat") &&
+        !args.designBrief.roles.some((role) => role.role === "primaryAction") &&
+        !hasAnswer(ctx.answers, "primary_action_token")) {
+        questions.push({
+            id: "primary_action_token",
+            question: "Which design token (or color value) should be used as the primary action color? No primary-action token was confidently identified in the design contract.",
+            why: "A primary action colour is needed for interactive elements (composer button, own-message bubble). Without a confident token, the agent must guess or omit it.",
+            required: false,
+            blocksImplementationWhenMissing: false,
+        });
+    }
+    if (args.outcome === "add-feed" && optionalCapabilityChecklist(args.outcome).length > 0 && !hasAnswer(ctx.answers, "feed_optional_capabilities")) {
+        questions.push({
+            id: "feed_optional_capabilities",
+            question: "Which optional feed capabilities should be in scope: post-image-upload, post-poll-creation, post-edit, or none?",
+            why: "These capabilities are useful for full feeds, but should become enforceable only after the customer explicitly opts in.",
+            required: false,
+            blocksImplementationWhenMissing: false,
+            options: ["none", ...optionalCapabilityChecklist(args.outcome).map((capability) => capability.id)],
+        });
+    }
+    const remainingBlocking = questions.filter((question) => question.blocksImplementationWhenMissing).length;
+    return {
+        status: remainingBlocking > 0 ? "needs-clarification" : "ready",
+        questions,
+        answers: args.answers,
+        remainingBlocking,
+        acknowledged_unresolved_blocking: args.allowUnresolvedIntake && remainingBlocking > 0,
+    };
+}
+function preferredPlatform(platforms) {
+    const order = ["flutter", "android", "typescript", "react-native", "ios"];
+    return order.find((platform) => platforms.includes(platform)) ?? platforms[0] ?? "unknown";
+}
 export async function applicableComplianceRuleSummaries(outcome, platforms) {
     return (await applicableRules(outcome, platforms)).map(ruleRefForFile);
 }

package/dist/tools/design.js

@@ -1449,14 +1449,14 @@ async function findProjectDesignFiles(root) {
                     stack.push(full);
                 }
             }
-            else if (entry.isFile() && isDesignFile(full)) {
+            else if (entry.isFile() && await isDesignFile(full)) {
                 out.push(full);
             }
         }
     }
     return out.sort();
 }
-function isDesignFile(full) {
+async function isDesignFile(full) {
     const lower = full.replace(/\\/g, "/").toLowerCase();
     const base = path.basename(lower);
     const ext = path.extname(lower);
@@ -1467,7 +1467,10 @@ function isDesignFile(full) {
         return /\/lib\//.test(lower) && /(theme|color|token|palette)/.test(base);
     }
     if (ext === ".css" || ext === ".scss") {
-        return base === "globals.css" || /(theme|token|design)/.test(base);
+        if (base === "globals.css" || /(theme|token|design)/.test(base)) {
+            return true;
+        }
+        return cssFileDeclaresDesignTokens(full);
     }
     if (ext === ".json") {
         return /\.colorset\//.test(lower) && base === "contents.json"; // iOS asset-catalog color
@@ -1486,6 +1489,19 @@ function isDesignFile(full) {
     }
     return false;
 }
+async function cssFileDeclaresDesignTokens(full) {
+    try {
+        const info = await stat(full);
+        if (info.size > MAX_FILE_BYTES) {
+            return false;
+        }
+        const content = await readFile(full, "utf8");
+        return /(^|[{\s;])--[a-zA-Z0-9_-]+\s*:\s*[^;{}]+[;}]/.test(stripCssComments(content));
+    }
+    catch {
+        return false;
+    }
+}
 // ---------------------------------------------------------------------------
 // Contract construction
 // ---------------------------------------------------------------------------

package/dist/tools/integration.js

@@ -147,7 +147,7 @@ function optionalCapabilitiesFor(outcome, answers, request) {
     }
     return {
         answerId: "feed_optional_capabilities",
-        note: "Optional feed capabilities are feed-forward choices, not baseline compliance. If the user opts in, pass the selected ids through `--answer feed_optional_capabilities=<id[,id]>` on `vise plan` and `vise init`; `vise check` will then run source sensors for those selected capabilities.",
+        note: "Optional feed capabilities are feed-forward choices, not baseline compliance. Before `vise init`, make an explicit answer: pass selected ids through `--answer feed_optional_capabilities=<id[,id]>` on `vise plan` and `vise init`, or pass `--answer feed_optional_capabilities=none`. `vise check` runs source sensors only for selected capabilities; explicitly unselected capabilities remain non-mandatory.",
         choices,
         selected: selectedOptionalCapabilityIds(outcome, answers, request),
     };
@@ -163,12 +163,21 @@ function designContractGuidance(contract) {
         .map((token) => token.provenance === "declared" && token.name
         ? `${token.name}: ${token.value}`
         : `${token.value} (inferred, ${token.uses}×)`);
+    const tokenCount = contract.stats.declared_tokens + contract.stats.inferred_tokens;
+    const sourceLabel = contract.source.kind === "host-project"
+        ? "the host project's design system"
+        : "the customer's prototype";
+    const sourceAction = contract.source.kind === "host-project"
+        ? "host app"
+        : "prototype";
+    const summary = tokenCount === 0
+        ? `A design contract was extracted from ${sourceLabel}, but no usable design tokens were found (strength: ${contract.stats.strength}). Ask the customer for the correct prototype, theme file, token source, or screenshots before inventing brand values.`
+        : `A design contract was extracted from ${sourceLabel} (${contract.stats.declared_tokens} declared + ${contract.stats.inferred_tokens} inferred tokens, strength: ${contract.stats.strength}). Build the social.plus UI using these tokens so it matches the ${sourceAction}'s aesthetic. Prefer the declared tokens; treat inferred tokens as advisory and confirm brand values with the customer when the contract is weak.`;
     return {
         digest: contract.digest,
         strength: contract.stats.strength,
         source: contract.source,
-        summary: `A design contract was extracted from the customer's prototype (${contract.stats.declared_tokens} declared + ${contract.stats.inferred_tokens} inferred tokens, strength: ${contract.stats.strength}). ` +
-            "Build the social.plus UI using these tokens so it matches the prototype's aesthetic. Prefer the declared tokens; treat inferred tokens as advisory and confirm brand values with the customer when the contract is weak.",
+        summary,
         tokens: {
             color: byCategory("color"),
             spacing: byCategory("space"),
@@ -180,7 +189,7 @@ function designContractGuidance(contract) {
         },
         components: contract.components.map((component) => ({ name: component.name, selector: component.selector })),
         breakpoints: contract.breakpoints.map((breakpoint) => breakpoint.raw),
-        attestation: `When you record a design attestation, cite this contract digest (${contract.digest}) so the generated feed can be claimed conformant to the customer's prototype.`,
+        attestation: `When you record a design attestation, cite this contract digest (${contract.digest}) so the generated feed can be claimed conformant to the ${sourceAction}'s design source.`,
         advisoryOnly: "This contract is advisory generation guidance — it adds no deterministic enforcement and never fails `vise check`.",
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.14.5",
+  "version": "0.14.6",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -65,9 +65,10 @@
     "test:sdk-version": "npm run build && node test/run-sdk-version.mjs",
     "test:sdk-surface": "node test/run-sdk-surface-snapshot.mjs",
     "test:sdk-facts": "npm run build && node test/run-sdk-facts.mjs",
+    "test:blocks-installer": "npm run build && node test/run-blocks-installer.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:e2e-package": "npm run build && node test/run-e2e-package.mjs",
-    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:design-brief && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:sdk-surface && npm run test:sdk-facts && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run bench:symbols-drift && npm run pack:check",
+    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:design-brief && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:sdk-surface && npm run test:sdk-facts && npm run test:blocks-installer && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run bench:symbols-drift && npm run pack:check",
     "test:ast": "node test/run-ast-helpers.mjs",
     "test:design-extract": "npm run build && node test/run-design-extract.mjs",
     "test:design-brief": "npm run build && node test/run-design-brief.mjs",

package/skills/social-plus-vise/SKILL.md

@@ -37,6 +37,10 @@ vise run-sensors .
 
 **`vise check .` is mandatory, not optional. You are not done until it passes or every finding is explicitly attested.** Running `vise plan` and `vise inspect` but skipping `vise check` is the most common failure mode — it means the deterministic catch-net never ran and known-bad patterns ship. When you read a `vise plan`, do not truncate it (`| head` drops the implementation steps); read the full `implementationSteps` array.
 
+**Feed-forward optional capabilities require an explicit answer.** When `vise plan` returns `optionalCapabilities` or the intake question `feed_optional_capabilities`, do not silently ignore it. Either pass the selected exact ids through both `vise plan` and `vise init`, for example `--answer feed_optional_capabilities=post-image-upload,post-poll-creation`, or pass `--answer feed_optional_capabilities=none` and state that the optional capabilities are out of scope. Selected optional capabilities become source sensors in `vise check`; unselected ones remain non-mandatory.
+
+**Blocking intake questions must be surfaced to the user.** If `vise plan` returns `intake.status: "needs-clarification"` with blocking questions, stop and ask those questions before implementation. Current Vise also enforces this at `vise init`: unresolved blocking intake returns `status: "needs-clarification"` and the CLI exits non-zero. Only retrospective benchmark/harness setup may pass `--allow-unresolved-intake`, and that acknowledgement is recorded in `sp-vise/intake.json`.
+
 **Baseline completeness is also a stop condition.** When `vise check .` exits with status `completeness-gap` (exit code 5), one or more baseline capabilities are neither implemented nor opted-out. For add-feed, the baseline capability is pagination. For each missing item: either implement it, or place `// vise: scope-omit <id> — <reason>` in the relevant source file and re-run `vise check .` to confirm it exits 0. A missing baseline capability that is neither built nor opted-out is a silent drop — the check will not pass green until every baseline capability is resolved.
 
 Treat Vise runtime smoke sensors as real validation. For TypeScript/React Native projects, `vise run-sensors` may include `TypeScript SDK import smoke`; if it fails, the SDK package does not resolve from the host project runtime and the integration is not done.