@amityco/social-plus-vise 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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).
 
+## 1.7.0 — 2026-07-09
+
+### Added
+- **Day-2 governance: adding features to an app that already uses social.plus is now a first-class, governed flow.**
+  - **Brownfield adoption honesty.** `vise init` on a repo with pre-existing non-green findings surfaces a `brownfield` hint: record `vise baseline .` before writing code, then gate with `vise check --new-only`. A baseline excludes pre-existing *rule findings only* — the requested outcome's completeness checklist and selected capabilities are never baselined, so a baselined repo can't go green without the feature actually built. Baseline files recorded by older versions that carried deliverable entries are ignored and disclosed (`ignored_legacy_deliverable_entries`).
+  - **Engagement ledger.** Initializing a different outcome records the outgoing engagement's final check, contract, and intake to `sp-vise/engagements/<outcome>/` (latest per outcome) and discloses the switch in the init result. `vise status` lists superseded engagements under `previousEngagements`. Replacing a **green** engagement asks for an explicit `--supersede-engagement`.
+  - **Re-verification of finished work.** `vise check --engagement <outcome>` re-verdicts one recorded engagement against the current rules and code (exit `11` on drift, `0` when it holds; `ruleset_upgraded` disclosed). `vise check --all-engagements` runs the normal gate plus re-verdicts of every recorded engagement — active gate non-green keeps its own exit code; active green with a drifted recorded engagement exits `11` (`engagement-drift`). Findings already gating the active engagement are counted once there (`shared_with_active`).
+  - **Attestations are bound to their engagement.** `vise attest` stamps the active outcome; after an outcome switch, a rule-global attestation re-gates (`stale_engagement_attestation`) until re-verified — file-scoped attestations survive the switch because new files re-gate them anyway. Attestations recorded by older versions keep their historical behavior.
+  - **Completed journeys don't dead-end new requests.** After a finished multi-surface journey, `vise init` for a genuinely new outcome now proceeds (recording the completed journey to the ledger) instead of stopping at `workplan-complete`; re-initializing a surface the journey already completed still gets the honest stop.
+  - New skill section — "Adding Features To An App That Already Uses social.plus" — teaches agents both variants (hand-rolled integration and prior governed engagement).
+- **SDK facts: broader capability coverage and deeper model grounding.** `vise sdk-facts` (now listed in the public `vise --help`) gains capability anchors for `community`, `chat`, `livestream` (Room API only), `notification-tray`, and `events` on TypeScript, plus per-platform anchor sets with Flutter coverage for six families (`comments`, `reactions`, `posts`, `users`, `community`, `chat`) — a partially anchored platform's result names its coverage explicitly. Field-level model schemas grew from 6 to 14 TypeScript models (`Amity.Community`, `Amity.Channel`, `Amity.Message`, `Amity.SubChannel`, `Amity.Room`, `Amity.NotificationTrayItem`, `Amity.NotificationTraySeen`, `Amity.Event`), all extraction-grounded with real field names and types.
+- **Development-workspace guard.** Customer-integration commands now recognize the Vise / social.plus blocks development workspace itself: `vise init` refuses with `status: "internal-workspace"` (exit `10`, `--allow-internal-workspace` to override for harness runs), and `inspect`/`plan` attach an advisory warning — so the projectless `vise sdk-facts` persona and the customer persona can't be mixed up silently.
+
+### Fixed
+- **Blocks installer on native projects.** `vise blocks plan`/`add`/`validate` pointed at a project without a package manifest (an iOS or Android app) now return the graceful `needs-review` plan with unsupported-platform stop conditions instead of crashing on a missing `package.json`.
+
+### Compatibility
+- **Additive exit codes.** `10` (`internal-workspace`, init-only) and `11` (`engagement-drift`, only under the new `--engagement`/`--all-engagements` flags). The existing 0–9 exit surface and precedence are unchanged; default `vise check` behavior is unchanged, so pipelines gating on `--ci` or `exitCode === 0` are unaffected.
+- **One intentional init behavior change.** `vise init` replacing a **green** engagement with a different outcome now requires `--supersede-engagement` (exit `7` otherwise); red or in-progress engagements switch as before, and the outgoing engagement's final state is recorded to the ledger either way.
+- **Sidecar additions are additive.** `sp-vise/engagements/` and the new result fields (`brownfield`, `engagement_switch`, `previousEngagements`, `stale_engagement_attestation`) are new; no existing file changes shape. Legacy baselines and attestations continue to parse — with the honesty adjustments disclosed above.
+
 ## 1.6.0 — 2026-07-06
 
 ### Added

package/README.md

@@ -206,7 +206,7 @@ Run `vise <command> --help` for full flags. JSON output is the default for agent
 | `vise plan [path] --request "..." [--summary]` | Grounded implementation plan with intake questions and docs citations; `--summary` prints a compact route/intake view |
 | `vise plan --summary "..."` | Shortcut for quick routing or discovery when the current directory is the repo |
 | `vise plan-harness [path] --request "..."` | Pre-planning step: build the harness around the request |
-| `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract once blocking intake is answered; exits 7 (`needs-clarification`) otherwise |
+| `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract once blocking intake is answered; exits 7 (`needs-clarification`) otherwise. Refuses to initialize the Vise / social.plus blocks development workspace itself (`status: "internal-workspace"`, exit 10 — use `vise sdk-facts` there, or `--allow-internal-workspace` for an intentional harness run). Replacing a **green** engagement with a different outcome requires `--supersede-engagement` (exit 7 otherwise); the outgoing engagement's final state is recorded to `sp-vise/engagements/` either way |
 | `vise workplan next [path] --request "..."` | For broad social requests: print the next uncompleted surface and its focused commands |
 | `vise workplan status [path] --request "..."` | Show the workplan sequence and completed surfaces; ignores unverifiable or drifted snapshot evidence. If the in-scope surface's live `vise check` is already green, auto-records that one surface (same evidence bar as `workplan complete`) so a working, check-green surface isn't left uncounted |
 | `vise workplan complete [path] --request "..." --surface <id>` | Record a green-checked surface; snapshots evidence plus an integrity manifest under `sp-vise/workplan-snapshots/<surface>/` |
@@ -255,11 +255,13 @@ Everything in this group is local and advisory: no uploads, no `vise check` exit
 | `vise check [path]` | Re-validate against the recorded contract: `green`, `needs-attestation`, `deterministic-failures`, `blocked`, `contract-drift`, `completeness-gap`, `selected-capability-failures`, `no-platform` (no SDK platform detected — reported as a failure, not a vacuous green), or `runtime-proof-waived` |
 | `vise check [path] --ci` | Read-only variant that exits non-zero unless green (for CI) |
 | `vise check [path] --allow-proof-waiver` | Accept an honest `runtime-proof-waived` result (from `vise smoke waive`) as passing (exit 0) instead of blocking; without it a waiver blocks CI by default |
-| `vise check [path] --new-only` | **Brownfield gate.** With a recorded baseline, gate only on findings introduced *since* the baseline (pre-existing ones are reported but excluded). Default `check` always gates on everything |
-| `vise baseline [path]` | Snapshot the current pre-existing findings to `sp-vise/baseline.json` so `check --new-only` can separate legacy debt from new gaps. `vise init --baseline` records it at init time |
+| `vise check [path] --new-only` | **Brownfield gate.** With a recorded baseline, gate only on rule findings introduced *since* the baseline (pre-existing ones are reported but excluded). The outcome's completeness checklist and selected optional capabilities are **never** excluded — they are the engagement's deliverables and gate like a default check. Default `check` always gates on everything |
+| `vise check [path] --engagement <outcome>` | **Re-verdict one recorded engagement** (from `sp-vise/engagements/`) against the current ruleset and code. Exit `11` on drift, `0` when it still holds; never the active engagement's codes. `ruleset_upgraded` discloses when the installed ruleset moved since it was recorded |
+| `vise check [path] --all-engagements` | Run the normal active gate **plus** re-verdicts of every recorded engagement. Active gate non-green → its normal exit code; active green but a recorded engagement drifted → exit `11` (`engagement-drift`). Findings already gating the active engagement are counted once there (`shared_with_active`) |
+| `vise baseline [path]` | Snapshot the current pre-existing rule findings to `sp-vise/baseline.json` so `check --new-only` can separate legacy debt from new gaps. Deliverables (completeness/selected capabilities) are never baselined. Record it right after `vise init`, before writing code — a mid-build baseline would swallow your own findings. `vise init --baseline` records it at init time |
 | `vise validate [path]` | Run the deterministic validators only (no attestation comparison) |
 | `vise sync [path]` | Persist deterministic-pass evidence to `sp-vise/attestations/` |
-| `vise attest [path] --rule <id> --signer host-agent --confidence high --evidence-file evidence.json --rationale "..."` | Record an attestation when a rule passes through architecture the deterministic check can't see |
+| `vise attest [path] --rule <id> --signer host-agent --confidence high --evidence-file evidence.json --rationale "..."` | Record an attestation when a rule passes through architecture the deterministic check can't see. Attestations are bound to the engagement outcome they were reviewed under: after `vise init` switches the sidecar to a different outcome, a rule-global attestation re-gates (`stale_engagement_attestation`) until re-attested — file-scoped attestations survive the switch because new files re-gate them anyway |
 | `vise explain <ruleId>` | Print a rule's rationale, evidence requirements, and remediation |
 | `vise status [path]` | Summarize the current compliance state |
 
@@ -330,6 +332,9 @@ jobs:
 | `4` | Contract drift — recorded rules no longer match the current ruleset |
 | `5` | Baseline capability neither implemented nor opted-out (add it or place `// vise: scope-omit <id> — <reason>`) |
 | `6` | An explicitly selected optional capability failed its source sensors |
+| `8` | No SDK platform detected (`no-platform`) — reported as a failure, never a vacuous green |
+| `9` | Runtime proof waived (`runtime-proof-waived`) — accept explicitly with `--allow-proof-waiver` |
+| `11` | Engagement drift (`--engagement` / `--all-engagements` only): the active gate is green but a recorded engagement re-verdicts non-green — a previously finished surface no longer holds |
 
 ## Compliance Contract
 
@@ -341,6 +346,7 @@ Vise writes local planning, compliance, design, and evidence artifacts under `sp
 | `sp-vise/intake.json` | `vise init` | Request, outcome, intake answers, design-review status |
 | `sp-vise/inspection.json` | `vise init` | Platform, surface, and design signals detected at init |
 | `sp-vise/attestations/*.json` | `vise sync` / `vise attest` | Per-rule evidence: signer, confidence, rationale, source fingerprints for drift detection |
+| `sp-vise/engagements/<outcome>/*.json` | `vise init` (on an outcome switch) | Engagement ledger: the superseded engagement's final check, contract, and intake (latest per outcome) — surfaced by `vise status` as `previousEngagements` |
 | `sp-vise/creative-brief.json` + `creative-brief.md` | `vise creative` | Advisory brief: goals, archetypes, candidate variants (JSON + human-readable) |
 | `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local ranking preview for review context; `experience_score: null`, no uploads, no default-order change, no top-1 confidence claim |
 | `sp-vise/creative-selection.json` | `vise creative accept` | Accepted variant and plan/workplan feed-forward context |

package/dist/flow.js

@@ -2,6 +2,12 @@ import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { sidecarDir } from "./sidecar.js";
+export function completedWorkplanBlocksOutcome(stages, requestedOutcome) {
+    if (!requestedOutcome || requestedOutcome === "unknown") {
+        return true;
+    }
+    return stages.some((stage) => stage.outcome === requestedOutcome);
+}
 export function blueprintDigest(input) {
     const canonical = JSON.stringify({
         path: input.path ?? null,

package/dist/server.js

@@ -5,18 +5,19 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { sidecarDir as sidecarPath } from "./sidecar.js";
-import { blueprintDigest, readFlowState, readOmittedSurfaces, renderFlowBlueprint, runtimeReadinessForStages, writeFlowBlueprintHtml, writeFlowState, } from "./flow.js";
+import { blueprintDigest, completedWorkplanBlocksOutcome, readFlowState, readOmittedSurfaces, renderFlowBlueprint, runtimeReadinessForStages, writeFlowBlueprintHtml, writeFlowState, } from "./flow.js";
 import { normalizeSolutionPathAnswer } from "./solutionPath.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, experienceReportTool, initCompliance, initComplianceTool, recordBaseline, initEngagement, initEngagementTool, listRules, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
+import { attestRule, attestRuleTool, checkAllEngagements, checkCompliance, checkEngagementReVerdict, checkComplianceTool, explainRule, explainRuleTool, experienceReportTool, initCompliance, initComplianceTool, recordBaseline, initEngagement, initEngagementTool, listRules, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
 import { designCheckTool, designContrastTool, designExtractTool, designInitTokensTool, designPreviewTool, designReferenceTool } from "./tools/design.js";
 import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
 import { compileExperienceTool } from "./tools/experienceCompiler.js";
 import { experienceSensorsTool } from "./tools/experienceSensors.js";
 import { planHarnessTool } from "./tools/harness.js";
 import { planIntegrationTool } from "./tools/integration.js";
+import { detectInternalWorkspace, internalWorkspaceWarning } from "./tools/internalWorkspace.js";
 import { recordLearningTool, showLearningTool } from "./tools/learning.js";
 import { inspectProjectTool, validateSetupTool } from "./tools/project.js";
 import { resolveRequestTool, suggestPatchTool } from "./tools/resolve.js";
@@ -153,10 +154,17 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "inspect") {
-            await printToolResult(inspectProjectTool, {
-                repoPath: positionalRepoPath(args.slice(1)),
+            const inspectRepo = positionalRepoPath(args.slice(1));
+            const inspectResult = await inspectProjectTool.call({
+                repoPath: inspectRepo,
                 surfacePath: flagValue(args, "surface") ?? flagValue(args, "surface-path"),
             });
+            const inspectPayload = JSON.parse(inspectResult.content.map((item) => item.text).join("\n"));
+            const inspectWorkspace = await detectInternalWorkspace(inspectRepo);
+            if (inspectWorkspace.isInternalWorkspace) {
+                inspectPayload.internalWorkspaceWarning = internalWorkspaceWarning(inspectWorkspace);
+            }
+            console.log(JSON.stringify(inspectPayload, null, 2));
             return "exit";
         }
         if (command === "creative") {
@@ -300,6 +308,10 @@ async function handleCli(args) {
             const result = await planIntegrationTool.call(input);
             const text = result.content.map((item) => item.text).join("\n");
             const payload = JSON.parse(text);
+            const planWorkspace = await detectInternalWorkspace(positionalRepoPath(args.slice(1)));
+            if (planWorkspace.isInternalWorkspace) {
+                payload.internalWorkspaceWarning = internalWorkspaceWarning(planWorkspace);
+            }
             emitResult("plan", hasFlag(args, "summary") ? planSummary(payload) : payload, args);
             return "exit";
         }
@@ -462,9 +474,19 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "init") {
-            assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer", "allow-unresolved-intake", "baseline"], "init");
+            assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer", "allow-unresolved-intake", "baseline", "allow-internal-workspace", "supersede-engagement"], "init");
             const initRepo = positionalRepoPath(args.slice(1));
             const initRequest = requiredFlagValue(args, "request", "init requires --request.");
+            const initWorkspace = await detectInternalWorkspace(initRepo);
+            if (initWorkspace.isInternalWorkspace && !hasFlag(args, "allow-internal-workspace")) {
+                console.log(JSON.stringify({
+                    status: "internal-workspace",
+                    ...internalWorkspaceWarning(initWorkspace),
+                    instruction: "Refusing to initialize the compliance sidecar here. If this really is intentional (e.g. a harness run at the workspace root), re-run with --allow-internal-workspace.",
+                }, null, 2));
+                process.exitCode = 10;
+                return "exit";
+            }
             const initWorkplanPlan = await workplanPlan(initRepo, initRequest, args);
             const { sequence: initSequence, omitted: initOmitted, canonicalRequest: initCanonicalRequest } = await activeBlueprint(initRepo, initRequest, initWorkplanPlan);
             if (initSequence.length >= 2 && initWorkplanPlan.platform !== "unknown") {
@@ -474,15 +496,16 @@ async function handleCli(args) {
                     process.exitCode = 7;
                     return "exit";
                 }
-                const workplanInitGate = await requireNextWorkplanSurfaceInit(initRepo, initCanonicalRequest, initSequence, keyValueFlag(args, "answer"), initOmitted, initRequest);
+                const workplanInitGate = await requireNextWorkplanSurfaceInit(initRepo, initCanonicalRequest, initSequence, keyValueFlag(args, "answer"), initOmitted, initRequest, initWorkplanPlan.outcome);
                 if (workplanInitGate) {
                     console.log(JSON.stringify(workplanInitGate, null, 2));
                     process.exitCode = 7;
                     return "exit";
                 }
             }
-            const result = await initCompliance(initRepo, initRequest, flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer"), { allowUnresolvedIntake: hasFlag(args, "allow-unresolved-intake") });
-            if (result.status === "needs-clarification" && typeof result.exitCode === "number") {
+            const result = await initCompliance(initRepo, initRequest, flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer"), { allowUnresolvedIntake: hasFlag(args, "allow-unresolved-intake"), baselinePlanned: hasFlag(args, "baseline"), supersedeEngagement: hasFlag(args, "supersede-engagement") });
+            if ((result.status === "needs-clarification" || result.status === "needs-engagement-supersede-confirmation") &&
+                typeof result.exitCode === "number") {
                 process.exitCode = result.exitCode;
             }
             if (hasFlag(args, "baseline") && result.status === "initialized") {
@@ -492,7 +515,26 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "check") {
-            assertOnlyKnownFlags(args, ["ci", "format", "new-only", "allow-proof-waiver"], "check");
+            assertOnlyKnownFlags(args, ["ci", "format", "new-only", "allow-proof-waiver", "engagement", "all-engagements"], "check");
+            const engagementOutcome = flagValue(args, "engagement");
+            if (engagementOutcome) {
+                if (hasFlag(args, "new-only") || hasFlag(args, "ci") || hasFlag(args, "all-engagements")) {
+                    throw new Error("--engagement re-verdicts one recorded engagement and cannot combine with --new-only, --ci, or --all-engagements.");
+                }
+                const reVerdict = await checkEngagementReVerdict(positionalRepoPath(args.slice(1)), engagementOutcome);
+                emitResult("check", reVerdict, args);
+                process.exitCode = typeof reVerdict.exitCode === "number" ? reVerdict.exitCode : 0;
+                return "exit";
+            }
+            if (hasFlag(args, "all-engagements")) {
+                if (hasFlag(args, "ci")) {
+                    throw new Error("--all-engagements cannot combine with --ci (the CI shape covers the active engagement only).");
+                }
+                const combined = await checkAllEngagements(positionalRepoPath(args.slice(1)), { newOnly: hasFlag(args, "new-only"), allowProofWaiver: hasFlag(args, "allow-proof-waiver") });
+                emitResult("check", combined, args);
+                process.exitCode = typeof combined.exitCode === "number" ? combined.exitCode : 0;
+                return "exit";
+            }
             const result = await checkCompliance(positionalRepoPath(args.slice(1)), { newOnly: hasFlag(args, "new-only"), allowProofWaiver: hasFlag(args, "allow-proof-waiver") });
             emitResult("check", hasFlag(args, "ci") ? ciCheckResult(result) : result, args);
             process.exitCode = result.exitCode;
@@ -657,7 +699,6 @@ function internalCommandsSection() {
     return `
 
 Internal commands (not part of the public surface — see docs/TOOLS.md):
-  vise sdk-facts --platform <p> [--capability <c>]  Read bundled SDK surface facts. Projectless, read-only.
   vise blocks <list|plan|add> ...                   Install and validate social.plus blocks in customer projects.
   vise resolve --request "..."                      Resolve a request into the closest supported Vise outcome.
   vise skill-path                                   Print the bundled skill source path and install targets.
@@ -1105,6 +1146,7 @@ Usage:
   vise learning show [repoPath]    Show local learning summary
   vise debug [repoPath] --error ... Debug an SDK-specific runtime error and emit a repair brief
   vise explore "<request>"         Discover what social.plus offers for a request (no project/credentials needed)
+  vise sdk-facts --platform <p>    Read proven SDK surface facts (symbols, capabilities, model schemas). Projectless, read-only
   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 (add --baseline on a brownfield app)
@@ -2186,13 +2228,16 @@ function socialWorkplanSequence(plan) {
     }
     return workplan.sequence;
 }
-async function requireNextWorkplanSurfaceInit(repoRoot, request, sequence, answers, omitted = [], requestedAs) {
+async function requireNextWorkplanSurfaceInit(repoRoot, request, sequence, answers, omitted = [], requestedAs, requestedOutcome) {
     const progress = await verifiedWorkplanProgress(repoRoot, request, sequence);
     const completedIds = new Set(progress.completed.map((item) => item.surface));
     const nextSurface = sequence.find((surface) => !completedIds.has(surface.id));
     const selectedSurface = resolveWorkplanSurfaceAnswer(sequence, answers.feature_surface);
     const selectedOmittedSurface = resolveOmittedSurfaceAnswer(omitted, answers.feature_surface);
     if (!nextSurface) {
+        if (!completedWorkplanBlocksOutcome(sequence, requestedOutcome)) {
+            return null;
+        }
         return {
             status: "workplan-complete",
             exitCode: 7,

package/dist/tools/blocks.js

@@ -242,7 +242,7 @@ async function packageChangeFor(root, platform, packageInfo, packageSource) {
         };
     }
     const file = "package.json";
-    const packageJson = await readPackageJson(path.join(root, file));
+    const packageJson = await readPackageJson(path.join(root, file)).catch(() => ({}));
     return {
         file,
         dependency: packageInfo.dependencyName,

package/dist/tools/compliance.js

@@ -416,6 +416,22 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
                 "The gate still blocks until every id above is answered; pass --allow-unresolved-intake only for retrospective/harness initialization.",
         };
     }
+    const previousCompliance = await readJsonIfExists(compliancePath(repoRoot));
+    let engagementSwitch;
+    if (previousCompliance && previousCompliance.outcome !== outcome) {
+        const finalCheck = await checkCompliance(repoPath).catch(() => undefined);
+        if (finalCheck?.status === "green" && !options.supersedeEngagement) {
+            return {
+                status: "needs-engagement-supersede-confirmation",
+                exitCode: 7,
+                from: previousCompliance.outcome,
+                to: outcome,
+                reason: `The current engagement (outcome "${previousCompliance.outcome}") is green — finished, verified work. Initializing "${outcome}" replaces its contract, and its completeness will no longer be checked (it moves to the engagement ledger; see \`vise status\` previousEngagements and \`vise check --all-engagements\`).`,
+                instruction: `Re-run with --supersede-engagement to proceed. The green final state will be recorded in sp-vise/engagements/${previousCompliance.outcome}/ first.`,
+            };
+        }
+        engagementSwitch = await recordEngagementOnSwitch(repoRoot, previousCompliance, outcome, finalCheck);
+    }
     const compliance = {
         schema_version: schemaVersion,
         vise_version: packageVersion,
@@ -468,6 +484,17 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
     if (engagement && engagement.scope.outcomes.length > 0 && !engagement.scope.outcomes.includes(outcome)) {
         warnings.push(`Outcome "${outcome}" is not in the engagement scope (${engagement.scope.outcomes.join(", ")}). Compliance was still initialized; extend the scope in engagement.json or re-run vise engagement init.`);
     }
+    const preExistingFindingFiles = [
+        ...new Set(checkSnapshot.rules
+            .filter((rule) => BASELINE_NON_GREEN.has(rule.status) && rule.finding?.file)
+            .map((rule) => rule.finding?.file)),
+    ];
+    const brownfieldHint = !options.baselinePlanned && preExistingFindingFiles.length > 0 && !(await readBaseline(repoRoot))
+        ? {
+            pre_existing_finding_files: preExistingFindingFiles.slice(0, 5),
+            hint: "This repo already contains social.plus integration with non-green findings that predate this engagement. Record `vise baseline .` NOW (before writing any code) so `vise check --new-only` gates only findings you introduce. The outcome's completeness checklist is never baselined — the requested feature still has to be built. Never record a baseline mid-build: it would swallow your own findings.",
+        }
+        : undefined;
     return {
         status: "initialized",
         sidecar: complianceDirName,
@@ -480,6 +507,8 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         ...(compliance.design_contract && { design_contract: compliance.design_contract }),
         ...(selectedOptionalCapabilities.length > 0 && { selected_optional_capabilities: selectedOptionalCapabilities }),
         ...(runtimeSmokeTemplate ? { runtime_smoke: runtimeSmokeTemplate } : {}),
+        ...(brownfieldHint ? { brownfield: brownfieldHint } : {}),
+        ...(engagementSwitch ? { engagement_switch: engagementSwitch } : {}),
         intake: {
             status: intake.status,
             remainingBlocking: intake.remainingBlocking,
@@ -862,7 +891,7 @@ async function ruleFreshness(rule) {
 }
 export async function checkCompliance(repoPath, options = {}) {
     const repoRoot = path.resolve(repoPath);
-    const compliance = await readCompliance(repoRoot);
+    const compliance = options.contract ?? (await readCompliance(repoRoot));
     const rules = await rulesById();
     const drift = contractDrift(compliance, rules);
     if (drift.length > 0) {
@@ -996,6 +1025,27 @@ export async function checkCompliance(repoPath, options = {}) {
             const exactMatch = attestation.rule_digest === ref.rule_digest;
             const grandfathered = !exactMatch && isAttestationGrandfathered(rule, attestation);
             if (exactMatch || grandfathered) {
+                if (attestation.outcome !== undefined &&
+                    attestation.outcome !== compliance.outcome &&
+                    !(attestation.file_scoped === true && isFileScopableRule(rule))) {
+                    const crossEngagementStatus = rule.advisory ? "advisory" : rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail";
+                    results.push({
+                        ...checkRuleIdentity(rule.id),
+                        title: rule.title,
+                        severity: rule.severity,
+                        status: crossEngagementStatus,
+                        reason: rule.advisory
+                            ? "Advisory: informational only — does not affect compliance status."
+                            : `Attestation was recorded during a different engagement (outcome "${attestation.outcome}", attested ${attestation.attested_at}); the current engagement is "${compliance.outcome}". Re-verify the claim still holds for the code this engagement adds, then re-attest.`,
+                        finding,
+                        recommendation: finding?.recommendation,
+                        rationale: rule.rationale,
+                        current_rule: ruleSummary(rule),
+                        stale_engagement_attestation: { outcome: attestation.outcome, attested_at: attestation.attested_at },
+                        ...(crossEngagementStatus === "attestation-needed" && rule.enforcement.attestation.allowed && attestHint(rule, compliance)),
+                    });
+                    continue;
+                }
                 const sourceFingerprintStatus = await checkSourceFingerprints(repoRoot, inspection.effectiveRoot, attestation.source_fingerprints ?? []);
                 const staleFingerprints = sourceFingerprintStatus.filter((item) => item.status !== "match");
                 if (staleFingerprints.length > 0) {
@@ -1153,22 +1203,23 @@ export async function checkCompliance(repoPath, options = {}) {
                     result.baselined = true;
                 }
             }
-            const baselinedMissing = new Set(baselineFile.completeness_missing);
-            const baselinedSelected = new Set(baselineFile.selected_optional);
+            const legacyDeliverableEntries = (baselineFile.completeness_missing?.length ?? 0) + (baselineFile.selected_optional?.length ?? 0);
             gatedResults = results.filter((result) => !result.baselined);
-            gatedMissing = (completeness?.missing ?? []).filter((item) => !baselinedMissing.has(item.id));
-            gatedSelectedFailed = (selectedOptionalCapabilities?.failed ?? []).filter((item) => !baselinedSelected.has(item.id));
-            gatedSelectedUnknown = (selectedOptionalCapabilities?.unknown ?? []).filter((id) => !baselinedSelected.has(id));
             baselineReport = {
                 present: true,
                 applied: true,
                 baselined_at: baselineFile.baselined_at,
                 excluded: {
                     rules: results.filter((result) => result.baselined).length,
-                    completeness: (completeness?.missing.length ?? 0) - gatedMissing.length,
-                    selected_optional: ((selectedOptionalCapabilities?.failed.length ?? 0) - gatedSelectedFailed.length) +
-                        ((selectedOptionalCapabilities?.unknown.length ?? 0) - gatedSelectedUnknown.length),
+                    completeness: 0,
+                    selected_optional: 0,
                 },
+                ...(legacyDeliverableEntries > 0
+                    ? {
+                        ignored_legacy_deliverable_entries: legacyDeliverableEntries,
+                        ignored_legacy_note: "This baseline predates the deliverables fix and recorded completeness/selected-capability entries; they are ignored — the engagement's deliverables always gate. Re-run `vise baseline` to refresh the file.",
+                    }
+                    : {}),
                 residual_caveat: "Baseline excludes pre-existing findings keyed by rule+file (count-based). A NEW violation of an already-baselined rule in the SAME file can be masked at this granularity — review the touched files directly for a precise per-change gate.",
             };
         }
@@ -1668,6 +1719,29 @@ export async function statusCompliance(repoPath, options = {}) {
                 reviewer_assignment: engagement.reviewer_assignment,
             },
         }),
+        ...(await previousEngagementsSection(repoRoot, check.outcome)),
+    };
+}
+async function previousEngagementsSection(repoRoot, activeOutcome) {
+    const dir = engagementsDir(repoRoot);
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const previous = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === activeOutcome) {
+            continue;
+        }
+        const record = await readJsonIfExists(path.join(dir, entry.name, "record.json"));
+        if (record) {
+            previous.push(record);
+        }
+    }
+    if (previous.length === 0) {
+        return {};
+    }
+    previous.sort((a, b) => String(a.outcome).localeCompare(String(b.outcome)));
+    return {
+        previousEngagements: previous,
+        previousEngagements_note: "Superseded engagements' last recorded state (latest per outcome; snapshots, not live verdicts). Their completeness is NOT checked by the active contract — to re-verify one today, re-run `vise init` with its original request and `vise check`. On-demand re-verification lands with `vise check --all-engagements` (docs/ENGAGEMENTS_DESIGN.md, B2).",
     };
 }
 async function applicableRules(outcome, platforms) {
@@ -2435,6 +2509,7 @@ function buildAttestation(compliance, rule, signer, confidence, identity, ration
         evidence,
         source_fingerprints: sourceFingerprints,
         ...(fileScoped ? { file_scoped: true } : {}),
+        outcome: compliance.outcome,
         rationale_for_attestation: rationale,
         attested_at: new Date().toISOString(),
     };
@@ -2791,6 +2866,8 @@ function sidecarReadme(compliance) {
         "",
         "Attestations include source fingerprints; `vise check` marks them stale if the cited files change.",
         "",
+        "`engagements/<outcome>/` (when present) is the engagement ledger: each superseded engagement's final check, contract, and intake, recorded when a `vise init` switched to a different outcome. `vise status` lists them under `previousEngagements`; re-verify with `vise check --engagement <outcome>` or `--all-engagements`.",
+        "",
     ].join("\n");
 }
 function attestationsDir(repoRoot) {
@@ -2827,6 +2904,129 @@ function deriveGate(flags) {
         return { status: "runtime-proof-waived", exitCode: flags.allowProofWaiver ? 0 : 9 };
     return { status: "green", exitCode: 0 };
 }
+async function recordEngagementOnSwitch(repoRoot, previous, nextOutcome, finalCheck) {
+    const previousIntake = await readJsonIfExists(path.join(sidecarDir(repoRoot), "intake.json"));
+    const dir = path.join(engagementsDir(repoRoot), String(previous.outcome));
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    const verdict = finalCheck
+        ? { status: finalCheck.status, exitCode: finalCheck.exitCode }
+        : { status: "unrecorded", exitCode: null, note: "The final check could not run at switch time; contract and intake are still recorded." };
+    const record = {
+        outcome: previous.outcome,
+        ...(typeof previousIntake?.request === "string" ? { request: previousIntake.request } : {}),
+        recorded_at: new Date().toISOString(),
+        reason: `superseded by ${nextOutcome} init`,
+        ruleset_digest: previous.ruleset_digest,
+        verdict,
+    };
+    await writeJson(path.join(dir, "record.json"), record);
+    if (finalCheck) {
+        await writeJson(path.join(dir, "final-check.json"), finalCheck);
+    }
+    await writeJson(path.join(dir, "contract.json"), previous);
+    if (previousIntake) {
+        await writeJson(path.join(dir, "intake.json"), previousIntake);
+    }
+    return {
+        from: previous.outcome,
+        to: nextOutcome,
+        recorded: path.join(complianceDirName, "engagements", String(previous.outcome)),
+        last_verdict: verdict,
+        note: "The previous engagement's final state is recorded in the ledger; its completeness is no longer checked by this contract. `vise status` lists it under previousEngagements. On-demand re-verification (`vise check --all-engagements`) lands with B2 (docs/ENGAGEMENTS_DESIGN.md).",
+    };
+}
+function engagementsDir(repoRoot) {
+    return path.join(sidecarDir(repoRoot), "engagements");
+}
+async function reVerdictOne(repoPath, repoRoot, outcome) {
+    const dir = path.join(engagementsDir(repoRoot), outcome);
+    const record = await readJsonIfExists(path.join(dir, "record.json"));
+    const recorded = await readJsonIfExists(path.join(dir, "contract.json"));
+    if (!record || !recorded) {
+        const available = (await readdir(engagementsDir(repoRoot), { withFileTypes: true }).catch(() => []))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+        throw new Error(`No recorded engagement for outcome "${outcome}".${available.length > 0 ? ` Recorded engagements: ${available.join(", ")}.` : " The engagement ledger is empty (it is written when an init switches away from an outcome)."}`);
+    }
+    const inspection = await inspectProject(repoRoot, recorded.surface?.path === "." ? undefined : recorded.surface?.path);
+    const platforms = Array.from(new Set([...inspection.platforms, ...(recorded.surface?.platforms ?? [])]));
+    const rules = await applicableRules(recorded.outcome, platforms.length > 0 ? platforms : ["unknown"]);
+    const synthetic = {
+        ...recorded,
+        ruleset_digest: digestJson(rules.map(ruleRef)),
+        rules: rules.map(ruleRefForFile),
+        generated_at: new Date().toISOString(),
+    };
+    const check = await checkCompliance(repoPath, { contract: synthetic });
+    return { record, check, ruleset_upgraded: recorded.ruleset_digest !== synthetic.ruleset_digest };
+}
+export async function checkEngagementReVerdict(repoPath, outcome) {
+    const repoRoot = path.resolve(repoPath);
+    const { record, check, ruleset_upgraded } = await reVerdictOne(repoPath, repoRoot, outcome);
+    const drifted = check.status !== "green";
+    return {
+        mode: "re-verdict",
+        engagement: outcome,
+        ...(typeof record.request === "string" ? { request: record.request } : {}),
+        recorded_at: record.recorded_at,
+        recorded_verdict: record.verdict,
+        ruleset_upgraded,
+        status: check.status,
+        exitCode: drifted ? 11 : 0,
+        summary: check.summary,
+        ...(check.completeness ? { completeness: check.completeness } : {}),
+        rules: check.rules.filter((rule) => BASELINE_NON_GREEN.has(rule.status)),
+        note: "Re-verdict of a recorded engagement against the current ruleset and code. It does not change the active engagement's gate; exit 11 signals engagement drift.",
+    };
+}
+export async function checkAllEngagements(repoPath, options = {}) {
+    const repoRoot = path.resolve(repoPath);
+    const active = await checkCompliance(repoPath, options);
+    const activeNonGreenKeys = new Set(active.rules.filter((rule) => BASELINE_NON_GREEN.has(rule.status)).map((rule) => baselineKeyFor(rule)));
+    const entries = await readdir(engagementsDir(repoRoot), { withFileTypes: true }).catch(() => []);
+    const engagements = [];
+    let anyDrift = false;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === active.outcome) {
+            continue;
+        }
+        const { record, check, ruleset_upgraded } = await reVerdictOne(repoPath, repoRoot, entry.name);
+        const nonGreen = check.rules.filter((rule) => BASELINE_NON_GREEN.has(rule.status));
+        const gating = nonGreen.filter((rule) => !activeNonGreenKeys.has(baselineKeyFor(rule)));
+        const shared = nonGreen.length - gating.length;
+        const completenessMissing = check.completeness?.missing ?? [];
+        const drifted = gating.length > 0 || completenessMissing.length > 0 || check.status === "contract-drift";
+        anyDrift = anyDrift || drifted;
+        engagements.push({
+            outcome: entry.name,
+            ...(typeof record.request === "string" ? { request: record.request } : {}),
+            recorded_at: record.recorded_at,
+            recorded_verdict: record.verdict,
+            ruleset_upgraded,
+            status: drifted ? check.status : "green",
+            drift: drifted,
+            ...(shared > 0 ? { shared_with_active: shared } : {}),
+            ...(gating.length > 0 ? { gating } : {}),
+            ...(completenessMissing.length > 0 ? { completeness_missing: completenessMissing.map((item) => item.id) } : {}),
+        });
+    }
+    engagements.sort((a, b) => String(a.outcome).localeCompare(String(b.outcome)));
+    const activeGreen = active.exitCode === 0;
+    return {
+        ...active,
+        ...(activeGreen && anyDrift
+            ? {
+                status: "engagement-drift",
+                exitCode: 11,
+                active_status: active.status,
+                active_exitCode: active.exitCode,
+            }
+            : {}),
+        engagements,
+        engagements_note: "Re-verdicts of recorded engagements against the current ruleset and code. Findings already gating the active engagement are counted once there (shared_with_active). Exit 11 = active engagement green but a recorded engagement drifted.",
+    };
+}
 export async function recordBaseline(repoPath) {
     const repoRoot = path.resolve(repoPath);
     const compliance = await readCompliance(repoRoot);
@@ -2841,19 +3041,18 @@ export async function recordBaseline(repoPath) {
         const key = baselineKeyFor(result);
         findings[key] = (findings[key] ?? 0) + 1;
     }
-    const completeness_missing = (check.completeness?.missing ?? []).map((item) => item.id);
-    const selected_optional = [
-        ...(check.selectedOptionalCapabilities?.failed ?? []).map((item) => item.id),
-        ...(check.selectedOptionalCapabilities?.unknown ?? []),
-    ];
+    const deliverables_not_baselined = {
+        completeness_missing: (check.completeness?.missing ?? []).length,
+        selected_optional: (check.selectedOptionalCapabilities?.failed ?? []).length + (check.selectedOptionalCapabilities?.unknown ?? []).length,
+    };
     const baseline = {
         baselined_at: new Date().toISOString(),
         vise_version: packageVersion,
         outcome: compliance.outcome,
         ruleset_digest: compliance.ruleset_digest,
         findings,
-        completeness_missing,
-        selected_optional,
+        completeness_missing: [],
+        selected_optional: [],
     };
     await writeJson(baselinePath(repoRoot), baseline);
     return {
@@ -2862,9 +3061,15 @@ export async function recordBaseline(repoPath) {
         outcome: baseline.outcome,
         recorded: {
             findings: Object.values(findings).reduce((a, b) => a + b, 0),
-            completeness_missing: completeness_missing.length,
-            selected_optional: selected_optional.length,
         },
+        ...(deliverables_not_baselined.completeness_missing + deliverables_not_baselined.selected_optional > 0
+            ? {
+                deliverables_not_baselined: {
+                    ...deliverables_not_baselined,
+                    note: "The outcome's completeness checklist and selected optional capabilities are this engagement's deliverables — they are never baselined and still gate `vise check --new-only`. Use a completeness opt-out for capabilities the product genuinely does not want.",
+                },
+            }
+            : {}),
         nextStep: "Implement your change, then run `vise check --new-only` to gate only on findings introduced since this baseline. Re-run `vise baseline` after the contract or outcome changes.",
     };
 }