@amityco/social-plus-vise 0.14.23 → 0.14.25

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.25 — 2026-06-06
+
+### Added
+- **Engagement Intelligence creative brief:** `vise creative` / MCP `creative_brief` now produces an advisory pre-planning brief from a customer request plus optional requirements document and optional prototype HTML. If requirements are absent or explicitly set to `none`, Vise enters exploratory mode instead of blocking.
+- **Creative sidecars:** `vise creative` writes `sp-vise/creative-brief.json` and `sp-vise/creative-brief.md` with inferred goals, archetypes, candidate variants, feasibility summaries, a blocking `preferred_solution` question, and next `vise plan` / `vise workplan` commands.
+- **Runtime intelligence catalog packaging:** the shipped npm tarball now includes `packages/intelligence` so installed CLIs can load the seeded goals, archetypes, objects, relationships, patterns, UX patterns, and variants catalog.
+
+### Verified
+- Added `test:creative` for requirements-driven mode, exploratory mode, sidecar writes, conflicting flag handling, and MCP smoke coverage.
+- Packed-package E2E now runs `vise creative --no-requirements --no-write` after installing the npm tarball, proving the runtime catalog is present in the package.
+
+## 0.14.24 — 2026-06-06
+
+### Changed
+- **Evidence-backed workplan completion:** `vise workplan complete` now runs the current compliance check, refuses non-green results, records check evidence in `sp-vise/workplan.json`, and snapshots the active compliance sidecar under `sp-vise/workplan-snapshots/<surface>/`.
+- **Scoped comments/chat/profile completeness:** the `add-comments` baseline is now narrowed to the comment composer/write affordance, `add-chat` is narrowed to send plus read/unread state, and `add-follow` is narrowed to follower/following relationship data, so focused surfaces do not fail on unselected replies, mentions, media-message types, edit/delete, typing, follow-request, block-list, or deeper moderation scope.
+- **Bundled host-agent skill guidance:** `social-plus-vise` now teaches agents to drive broad social requests through `vise workplan next/status/complete`, implement one focused surface at a time, and show `sp-vise/design-preview.html` before answering `design_contract_confirmation=yes`.
+
+### Verified
+- CLI regression coverage now initializes a focused Android feed sidecar before marking a workplan surface complete, then verifies the green-check evidence and per-surface snapshot files.
+- Capability regression coverage now locks the narrow `add-comments`, `add-chat`, and `add-follow` baselines.
+
 ## 0.14.23 — 2026-06-06
 
 ### Added

package/README.md

@@ -77,10 +77,14 @@ Vise validates on three layers, and the layer is set by the *kind of claim* —
 |---|---|---|---|
 | **SDK compliance** | "this is **wrong**" | 300+ deterministic rules (session renewal, live-collection vs one-shot, no secret in logs, parent-child rendering, ban-state gating…) | **Hard gate** — `vise check` blocks until green or attested. A small advisory subset surfaces as informational only and never blocks. |
 | **Design conformance** | "this **looks off**" | extract the customer's design system into a contract, render a preview for confirmation, then check token usage | **Advisory** — `vise design check`/`preview`; never fails a build |
-| **Feature completeness** | "this is **missing**" | Vise proposes a narrow baseline per outcome; for add-feed, pagination is mandatory, while richer feed capabilities are opt-in choices from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline capability is built or validly opted out; selected optional capabilities run separate sensors |
+| **Feature completeness** | "this is **missing**" | Vise proposes a narrow baseline per outcome; for add-feed, pagination is mandatory, for add-comments, the composer/write affordance is mandatory, for add-chat, send plus read/unread state are mandatory, and for add-follow/profile, SDK-backed follower/following data is mandatory, while richer feed capabilities are opt-in choices from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline capability is built or validly opted out; selected optional capabilities run separate sensors |
 
 Correctness is gated by deterministic rules or attestations. Baseline completeness is gated by explicit scope decisions: if a baseline capability is legitimately out of scope, record `// vise: scope-omit <id> — <reason>` and it no longer blocks. Optional feed capabilities such as image upload, poll creation, and edit post are offered during planning and become checked only after the user opts in. Conformance remains advisory because "matches the brand" is legitimately subjective. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
+### Engagement Intelligence roadmap
+
+Vise's next architecture track is the social.plus **Engagement Intelligence System**: an outcome-to-experience layer that maps customer goals, archetypes, solution patterns, experience objects, UX patterns, and variants before normal implementation planning. The first advisory runtime slice is `vise creative`: it consumes a request plus optional requirements/prototype inputs, or runs in exploratory mode when requirements are absent, then writes a local creative brief for user variant selection. See [docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md](docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md), [docs/MONOREPO_ARCHITECTURE.md](docs/MONOREPO_ARCHITECTURE.md), and [packages/intelligence](packages/intelligence).
+
 ### Relationship to social.plus Block Factory
 
 Vise has two deliberately separate roles:
@@ -161,15 +165,16 @@ Aggregate: **98/99 expected feed capabilities** and **27/27 selected optional ca
 
 ### Current Release Validation
 
-Version 0.14.23 carries current release proof around the full feed-forward, product-expectation, and validation flow:
+Version 0.14.25 carries current release proof around the full feed-forward, product-expectation, creative pre-planning, and validation flow:
 
 | Surface | What was validated |
 |---|---|
+| **Creative pre-planning** | `vise creative` produces requirements-driven or exploratory Engagement Intelligence briefs, writes `sp-vise/creative-brief.json` / `.md`, asks for `preferred_solution`, and survives packed-package installation with the intelligence catalog bundled. |
 | **Product flow** | Local end-to-end smoke covers design extraction, plan feed-forward, blocking intake, answered init, capability check, design conformance, and sensor discovery. |
-| **Multi-surface planning** | Broad social requests are decomposed into a `socialWorkplan` sequence for feed, comments, chat, and profile work instead of forcing a single top-level surface choice. `vise workplan next` tells the host agent which surface to implement next, and `vise workplan complete` records progress in `sp-vise/workplan.json`. |
+| **Multi-surface planning** | Broad social requests are decomposed into a `socialWorkplan` sequence for feed, comments, chat, and profile work instead of forcing a single top-level surface choice. `vise workplan next` tells the host agent which surface to implement next, and `vise workplan complete` records green-check progress in `sp-vise/workplan.json` with per-surface snapshots under `sp-vise/workplan-snapshots/<surface>/`. |
 | **Plan questions** | Plans surface blocking questions such as `design_contract_confirmation`, product-scope questions such as `feed_post_type_scope`, `feed_composer_type_scope`, `comment_tray_scope`, `chat_inbox_scope`, and `profile_identity_scope`, plus optional choices such as `feed_optional_capabilities`. Focused plans still accept `feature_surface` answers when the agent is ready to implement one surface. |
 | **Capability-to-sensor flow** | Vise checks platform support, matches the prompt to available capabilities, offers supported features as questions, records answers, and turns selected answers into sensors in `vise check`. |
-| **Android workplan dogfood** | A brownfield Android music-player app refreshed under `0.14.22` reached `vise check` green with **43/43 deterministic passes**, passed `vise validate`, and passed Gradle assemble/unit-test sensors. This is dogfood evidence, not a controlled multi-agent benchmark. |
+| **Android workplan dogfood** | A brownfield Android music-player app refreshed under `0.14.24` reached `vise check` green with **43/43 deterministic passes** on the focused feed surface and recorded a green-check workplan snapshot. This is dogfood evidence, not a controlled multi-agent benchmark. |
 | **Shared product expectations** | Public IDs such as `feed.target-resolved`, `feed.post-type-scope-explicit`, `comments.creation-affordance`, `chat.channel-list-order-explicit`, `community.avatar-from-sdk`, `moderation.role-gated-action`, `follow.relationship-live`, `profile.identity-from-sdk`, `profile.social-counts`, and `notifications.tray-live` stay platform-agnostic while check results retain concrete `contractRuleId` and `validator.sensorId` evidence when deterministic sensors exist. |
 | **Rule detection** | TP-track dashboard detects **321/321 seeded rule gaps (100.0%)** in the static corpus. |
 | **Packed-package smoke** | Packed-package and host-agent smokes exercise the release tarball path, surfaced plan questions, selected optional capability sensors, rejected design confirmation handling, and exact contract-rule evidence for shared product expectations. |
@@ -298,11 +303,12 @@ The flow above is what the skill teaches your AI agent. You — the human — dr
 |---|---|
 | `vise doctor` | Verify install; print version, install path, docs source |
 | `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
+| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>]` | Produce an advisory Engagement Intelligence brief with 2-3 solution variants before normal implementation planning; writes `sp-vise/creative-brief.json` and `.md` unless `--no-write` is set |
 | `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 workplan next [path] --request "..."` | For broad social requests, print the next uncompleted surface plus focused `plan` / `init` / verification commands |
 | `vise workplan status [path] --request "..."` | Show the broad social workplan sequence and which surfaces are already marked complete |
-| `vise workplan complete [path] --request "..." --surface <id>` | Record a completed workplan surface in `sp-vise/workplan.json` after `check`, `sync`, `validate`, and sensors pass |
+| `vise workplan complete [path] --request "..." --surface <id>` | Record a completed workplan surface after green `vise check`; writes progress to `sp-vise/workplan.json` and snapshots the active sidecar under `sp-vise/workplan-snapshots/<surface>/` |
 | `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 |
@@ -402,7 +408,7 @@ MCP-capable hosts can call Vise as structured tool calls instead of shell comman
 
 ### Tool names (snake_case per MCP convention)
 
-`inspect_project`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `resolve_request`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `suggest_patch`, `design_extract`, `design_check`, `design_preview`, `design_reference`, `design_init_tokens`.
+`inspect_project`, `creative_brief`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `resolve_request`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `suggest_patch`, `design_extract`, `design_check`, `design_preview`, `design_reference`, `design_init_tokens`.
 
 These are the same operations as the CLI commands above, exposed as MCP tools.
 
@@ -450,15 +456,18 @@ jobs:
 
 ## Compliance Contract
 
-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:
+Vise writes local planning, compliance, design, and evidence artifacts under `sp-vise/`. `vise creative` can create advisory creative-brief files before implementation; after a successful `vise init`, the compliance contract files are added. 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, selected optional capabilities, optional engagement link, and an accepted design-contract digest when confirmed. |
 | `sp-vise/intake.json` | `vise init` | The request, outcome, intake answers, remaining blocking count, design-review status (`absent`, `needs-confirmation`, `accepted`, or `rejected`), and any retrospective `--allow-unresolved-intake` acknowledgement. |
+| `sp-vise/creative-brief.json` | `vise creative` | Advisory Engagement Intelligence brief: mode, objective, inferred goals/archetypes, candidate solution variants, feasibility summary, preferred-solution question, and next plan/workplan commands. |
+| `sp-vise/creative-brief.md` | `vise creative` | Human-readable version of the creative brief for review with the user before selecting a variant. |
 | `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/workplan.json` | `vise workplan complete` | Local progress for broad social workplans: request, completed surface IDs, outcomes, timestamps, and optional host-agent notes. |
+| `sp-vise/workplan.json` | `vise workplan complete` | Local progress for broad social workplans: request, completed surface IDs, outcomes, timestamps, green-check evidence, snapshot paths, and optional host-agent notes. |
+| `sp-vise/workplan-snapshots/<surface>/` | `vise workplan complete` | Per-surface compliance/check snapshots copied from the active sidecar so later focused surfaces can overwrite `sp-vise/compliance.json` without erasing earlier proof. |
 | `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. |
 | `sp-vise/design-preview.html` | `vise design extract` or `vise design preview` | Self-contained visual review of the design contract, embedded prototype when available, token swatches, and design-check conformance summary. Open this before answering `design_contract_confirmation`. |
 | `sp-vise/design-reference.html` | `vise design reference` | Self-contained HTML design-system spec (token swatches, type samples, components). Human/VLM-readable; open in a browser alongside the app. |

package/dist/capabilities.js

@@ -13,7 +13,11 @@
  * agent subtracts with justification — it doesn't have to remember the set.
  *
  * Baseline capability gates must stay narrow. For add-feed, pagination is the
- * mandatory capability; richer composer affordances are selected optional sensors.
+ * mandatory capability. For add-comments, the comment composer is mandatory.
+ * For add-chat, sending plus read/unread state are mandatory. For add-follow,
+ * follower/following relationship data is mandatory. Replies, mentions,
+ * edit/delete, typing, media-message types, block lists, and deeper moderation
+ * scope are scoped separately. Richer composer affordances are selected optional sensors.
  */
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
@@ -325,10 +329,10 @@ export const CAPABILITIES = [
     },
     {
         id: "followers-following",
-        label: "Follower / following lists",
+        label: "Follower / following counts or lists",
         outcomes: ["add-follow"],
-        symbols: [/getFollowers/i, /getFollowings/i, /getFollowerList/i, /followRelationship/i],
-        hint: "list/observe followers and following as a Live Collection (getFollowers/getFollowings)",
+        symbols: [/getFollowers/i, /getFollowings/i, /getFollowerList/i, /followRelationship/i, /getMyFollowInfo/i, /getFollowerCount/i, /getFollowingCount/i],
+        hint: "source follower/following counts or lists from SDK relationship APIs, not placeholders",
     },
     {
         id: "follow-status",
@@ -1166,6 +1170,9 @@ function symbolHaystack(symbols) {
 const ADVISORY_NOTE = "Build each missing capability, or opt out with a recorded reason: `// vise: scope-omit <id> — <reason>`. A scope-omit marker without a reason is invalid and still counts as missing. Missing capabilities that are neither built nor validly opted-out cause `vise check` to exit with status `completeness-gap` (exit code 5).";
 const BASELINE_CAPABILITY_IDS_BY_OUTCOME = {
     "add-feed": ["pagination"],
+    "add-comments": ["comment-composer"],
+    "add-chat": ["send-message", "read-state"],
+    "add-follow": ["followers-following"],
 };
 function baselineCapabilities(outcome) {
     const caps = CAPABILITIES.filter((c) => c.outcomes.includes(outcome));

package/dist/server.js

@@ -17,11 +17,13 @@ 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 { creativeBriefTool } from "./tools/creative.js";
 import { packageName, packageVersion } from "./version.js";
 const tools = new Map([
     searchDocsTool,
     getDocPageTool,
     inspectProjectTool,
+    creativeBriefTool,
     planHarnessTool,
     planIntegrationTool,
     initComplianceTool,
@@ -134,6 +136,21 @@ async function handleCli(args) {
             });
             return "exit";
         }
+        if (command === "creative") {
+            assertOnlyKnownFlags(args, ["request", "requirements", "prototype", "surface", "surface-path", "no-requirements", "no-write"], "creative");
+            if (hasFlag(args, "no-requirements") && flagValue(args, "requirements")) {
+                throw new Error("creative accepts either --requirements <path> or --no-requirements, not both.");
+            }
+            await printToolResult(creativeBriefTool, {
+                repoPath: positionalRepoPath(args.slice(1)),
+                request: requiredFlagValue(args, "request", "creative requires --request."),
+                surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
+                requirementsPath: hasFlag(args, "no-requirements") ? "none" : flagValue(args, "requirements"),
+                prototypePath: flagValue(args, "prototype"),
+                write: !hasFlag(args, "no-write"),
+            });
+            return "exit";
+        }
         if (command === "debug") {
             assertOnlyKnownFlags(args, ["error", "error-file", "brief"], "debug");
             let errorMessage = flagValue(args, "error");
@@ -450,6 +467,23 @@ Re-plan with collected answers (repeat --answer for each intake question):
     --answer feed_scope=community \\
     --answer feed_target=existing\\ communityId \\
     --answer target_screen_or_route=app/feed/page.tsx`;
+    }
+    if (command === "creative") {
+        return `${packageName} creative
+
+Create an advisory Engagement Intelligence brief before normal Vise planning.
+
+Usage:
+  vise creative [repoPath] --request "Make this app more social"
+  vise creative [repoPath] --request "Add retention loops" --requirements ./requirements.md
+  vise creative [repoPath] --request "Add engagement" --requirements none
+  vise creative [repoPath] --request "Add engagement" --no-requirements
+  vise creative [repoPath] --request "Add engagement" --prototype ./prototype.html
+  vise creative [repoPath] --request "Add engagement" --no-write
+
+Output:
+  Writes sp-vise/creative-brief.json and sp-vise/creative-brief.md unless --no-write is set.
+  Requirements are optional; absence or explicit none switches creative mode to exploratory.`;
     }
     if (command === "plan-harness") {
         return `${packageName} plan-harness
@@ -697,6 +731,7 @@ Usage:
   vise install-skill --target codex Install bundled skill guidance
   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 debug [repoPath] --error ... Debug an SDK-specific runtime error and emit a repair brief
   vise plan [repoPath] --request "..." Create an implementation plan
   vise workplan next [repoPath] --request "..." Get the next broad-social surface to implement
@@ -1015,11 +1050,13 @@ async function completeWorkplanSurface(args) {
         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 snapshot = await writeWorkplanSurfaceSnapshot(repoRoot, surfaceId, check, now);
     const existing = await readWorkplanProgress(repoRoot);
     const base = existing?.request === request
         ? existing
         : {
-            schema_version: 1,
+            schema_version: 2,
             vise_version: packageVersion,
             request,
             generated_at: now,
@@ -1029,6 +1066,7 @@ async function completeWorkplanSurface(args) {
     const withoutSurface = base.completed.filter((item) => item.surface !== surfaceId);
     const progress = {
         ...base,
+        schema_version: 2,
         vise_version: packageVersion,
         updated_at: now,
         completed: [
@@ -1038,6 +1076,17 @@ async function completeWorkplanSurface(args) {
                 outcome: surface.outcome,
                 completed_at: now,
                 ...(note ? { note } : {}),
+                evidence: {
+                    check: {
+                        checked_at: now,
+                        status: check.status,
+                        exit_code: check.exitCode,
+                        outcome: check.outcome,
+                        ...(check.surfacePath ? { surface_path: check.surfacePath } : {}),
+                        summary: check.summary,
+                    },
+                    snapshot,
+                },
             },
         ].sort((a, b) => sequenceIndex(sequence, a.surface) - sequenceIndex(sequence, b.surface)),
     };
@@ -1051,6 +1100,46 @@ async function completeWorkplanSurface(args) {
         nextStep: status.nextStep,
     };
 }
+async function greenWorkplanCheck(repoRoot, surfaceId) {
+    let check;
+    try {
+        check = await checkCompliance(repoRoot);
+    }
+    catch (error) {
+        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 (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.`);
+    }
+    return check;
+}
+async function writeWorkplanSurfaceSnapshot(repoRoot, surfaceId, check, snapshotAt) {
+    const snapshotDir = workplanSurfaceSnapshotDir(repoRoot, surfaceId);
+    await mkdir(snapshotDir, { recursive: true });
+    const files = [];
+    const sidecarRoot = sidecarPath(repoRoot);
+    for (const fileName of ["compliance.json", "intake.json", "inspection.json", "findings.json"]) {
+        const sourcePath = path.join(sidecarRoot, fileName);
+        if (!(await fileExists(sourcePath))) {
+            continue;
+        }
+        const targetPath = path.join(snapshotDir, fileName);
+        await copyFile(sourcePath, targetPath);
+        files.push(repoRelativePath(repoRoot, targetPath));
+    }
+    const checkPath = path.join(snapshotDir, "check.json");
+    await writeFile(checkPath, `${JSON.stringify({
+        snapshot_at: snapshotAt,
+        surface: surfaceId,
+        check,
+    }, null, 2)}\n`, "utf8");
+    files.push(repoRelativePath(repoRoot, checkPath));
+    return {
+        directory: repoRelativePath(repoRoot, snapshotDir),
+        files: files.sort(),
+    };
+}
 async function workplanPlan(repoRoot, request, args) {
     const answers = keyValueFlag(args, "answer");
     delete answers.feature_surface;
@@ -1083,7 +1172,20 @@ async function writeWorkplanProgress(repoRoot, progress) {
     await writeFile(filePath, `${JSON.stringify(progress, null, 2)}\n`, "utf8");
 }
 function workplanProgressPath(repoRoot) {
-    return path.join(repoRoot, "sp-vise", "workplan.json");
+    return path.join(sidecarPath(repoRoot), "workplan.json");
+}
+function workplanSurfaceSnapshotDir(repoRoot, surfaceId) {
+    const safeSurfaceId = surfaceId.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (!safeSurfaceId) {
+        throw new Error(`Invalid workplan surface id: "${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("/");
 }
 function sequenceIndex(sequence, surfaceId) {
     const index = sequence.findIndex((surface) => surface.id === surfaceId);
@@ -1105,7 +1207,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", "registry", "block", "package-source", "note"]);
+    const flagsWithValues = new Set(["request", "requirements", "prototype", "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"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -1127,7 +1229,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", "registry", "block", "package-source", "note"]);
+    const flagsWithValues = new Set(["request", "requirements", "prototype", "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"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {