@amityco/social-plus-vise 0.14.22 → 0.14.23

package/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.23 — 2026-06-06
+
+### Added
+- **Workplan orchestration CLI:** `vise workplan next`, `vise workplan status`, and `vise workplan complete` coordinate broad social requests across feed, comments, chat, and profile surfaces while recording local progress in `sp-vise/workplan.json`.
+
+### Verified
+- CLI regression coverage now locks next-surface selection, completion recording, and feed-to-comments progression for broad Android social workplans.
+- Dogfooded `0.14.22` on `/Users/admin/Documents/music-player-android`: refreshed the feed contract, reached `vise check` green with 43/43 deterministic passes, synced attestations, and passed Gradle assemble/unit-test sensors.
+
 ## 0.14.22 — 2026-06-05
 
 ### Added

package/README.md

@@ -161,14 +161,15 @@ Aggregate: **98/99 expected feed capabilities** and **27/27 selected optional ca
 
 ### Current Release Validation
 
-Version 0.14.22 carries current release proof around the full feed-forward, product-expectation, and validation flow:
+Version 0.14.23 carries current release proof around the full feed-forward, product-expectation, and validation flow:
 
 | Surface | What was validated |
 |---|---|
 | **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. Each surface includes focused `vise plan` / `vise init` commands for the host agent to run when implementing that slice. |
+| **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`. |
 | **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. |
 | **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. |
@@ -299,6 +300,9 @@ 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 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 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 |
@@ -454,6 +458,7 @@ After a successful `vise init`, your project gets a `sp-vise/` directory. If ini
 | `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/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/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/server.js

@@ -177,6 +177,23 @@ async function handleCli(args) {
             });
             return "exit";
         }
+        if (command === "workplan") {
+            const sub = args[1];
+            const subArgs = args.slice(2);
+            if (sub === "next" || sub === "status") {
+                assertOnlyKnownFlags(subArgs, ["request", "surface", "surface-path", "answer"], `workplan ${sub}`);
+                console.log(JSON.stringify(await workplanStatus(subArgs), null, 2));
+                return "exit";
+            }
+            if (sub === "complete") {
+                assertOnlyKnownFlags(subArgs, ["request", "surface", "surface-path", "answer", "note"], "workplan complete");
+                console.log(JSON.stringify(await completeWorkplanSurface(subArgs), null, 2));
+                return "exit";
+            }
+            console.error(`Unknown workplan subcommand: ${sub ?? "(none)"}. Expected "next", "status", or "complete".`);
+            process.exitCode = 1;
+            return "exit";
+        }
         if (command === "validate" || command === "validate-setup") {
             await printToolResult(validateSetupTool, {
                 repoPath: positionalRepoPath(args.slice(1)),
@@ -442,6 +459,22 @@ Create a harness guide/sensor plan for the requested SDK integration.
 Usage:
   vise plan-harness [repoPath] --request "Add a social feed"
   vise plan-harness apps/web --request "Set up notifications" --surface apps/web`;
+    }
+    if (command === "workplan") {
+        return `${packageName} workplan
+
+Coordinate broad social requests across the ordered per-surface plan.
+
+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
+
+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.`;
     }
     if (command === "search-docs" || command === "search_docs") {
         return `${packageName} search-docs
@@ -666,6 +699,7 @@ Usage:
   vise inspect [repoPath]          Inspect platform and design signals
   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
   vise init [repoPath] --request "..." Initialize compliance sidecar
   vise check [repoPath]            Check compliance contract
   vise sync [repoPath]             Persist deterministic-pass evidence
@@ -916,6 +950,148 @@ 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.`);
 }
+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 progress = await readWorkplanProgress(repoRoot);
+    const completed = progress?.request === request ? progress.completed : [];
+    const completedIds = new Set(completed.map((item) => item.surface));
+    const nextSurface = sequence.find((surface) => !completedIds.has(surface.id));
+    if (sequence.length === 0) {
+        return {
+            status: "not-applicable",
+            reason: "The request did not produce a multi-surface social workplan. Use `vise plan` for the single-outcome flow.",
+            request,
+            progressPath: workplanProgressPath(repoRoot),
+        };
+    }
+    return {
+        status: nextSurface ? "next-surface" : "complete",
+        request,
+        progressPath: workplanProgressPath(repoRoot),
+        completed,
+        sequence: sequence.map((surface) => ({
+            id: surface.id,
+            order: surface.order,
+            outcome: surface.outcome,
+            label: surface.label,
+            completed: completedIds.has(surface.id),
+        })),
+        nextSurface: nextSurface
+            ? {
+                id: nextSurface.id,
+                order: nextSurface.order,
+                outcome: nextSurface.outcome,
+                label: nextSurface.label,
+                intake: nextSurface.intake,
+                validation: nextSurface.validation,
+                commands: {
+                    plan: nextSurface.planCommand,
+                    init: nextSurface.initCommand,
+                    check: "vise check .",
+                    sync: "vise sync .",
+                    validate: "vise validate .",
+                    sensors: "vise run-sensors .",
+                    complete: `vise workplan complete . --request ${shellQuoteForCommand(request)} --surface ${nextSurface.id}`,
+                },
+            }
+            : 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.`
+            : "All workplan surfaces are marked complete. Run one final `vise check .`, `vise validate .`, and `vise run-sensors .` before handoff.",
+    };
+}
+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 surface = sequence.find((item) => item.id === surfaceId);
+    if (!surface) {
+        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 existing = await readWorkplanProgress(repoRoot);
+    const base = existing?.request === request
+        ? existing
+        : {
+            schema_version: 1,
+            vise_version: packageVersion,
+            request,
+            generated_at: now,
+            updated_at: now,
+            completed: [],
+        };
+    const withoutSurface = base.completed.filter((item) => item.surface !== surfaceId);
+    const progress = {
+        ...base,
+        vise_version: packageVersion,
+        updated_at: now,
+        completed: [
+            ...withoutSurface,
+            {
+                surface: surfaceId,
+                outcome: surface.outcome,
+                completed_at: now,
+                ...(note ? { note } : {}),
+            },
+        ].sort((a, b) => sequenceIndex(sequence, a.surface) - sequenceIndex(sequence, b.surface)),
+    };
+    await writeWorkplanProgress(repoRoot, progress);
+    const status = await workplanStatus(args);
+    return {
+        status: "recorded",
+        progressPath: workplanProgressPath(repoRoot),
+        recorded: progress.completed.find((item) => item.surface === surfaceId),
+        nextSurface: status.nextSurface,
+        nextStep: status.nextStep,
+    };
+}
+async function workplanPlan(repoRoot, request, args) {
+    const answers = keyValueFlag(args, "answer");
+    delete answers.feature_surface;
+    const result = await planIntegrationTool.call({
+        repoPath: repoRoot,
+        request,
+        surfacePath: flagValue(args, "surface-path"),
+        answers,
+    });
+    return JSON.parse(result.content.map((item) => item.text).join("\n"));
+}
+function socialWorkplanSequence(plan) {
+    const workplan = plan.socialWorkplan;
+    if (!workplan || workplan.kind !== "social-multi-surface" || !Array.isArray(workplan.sequence)) {
+        return [];
+    }
+    return workplan.sequence;
+}
+async function readWorkplanProgress(repoRoot) {
+    try {
+        return JSON.parse(await readFile(workplanProgressPath(repoRoot), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function writeWorkplanProgress(repoRoot, progress) {
+    const filePath = workplanProgressPath(repoRoot);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(progress, null, 2)}\n`, "utf8");
+}
+function workplanProgressPath(repoRoot) {
+    return path.join(repoRoot, "sp-vise", "workplan.json");
+}
+function sequenceIndex(sequence, surfaceId) {
+    const index = sequence.findIndex((surface) => surface.id === surfaceId);
+    return index >= 0 ? index : Number.MAX_SAFE_INTEGER;
+}
+function shellQuoteForCommand(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
 function ciCheckResult(result) {
     return {
         ...result,
@@ -929,7 +1105,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"]);
+    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"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -951,7 +1127,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"]);
+    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"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.14.22",
+  "version": "0.14.23",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",