mancode 0.3.18 → 0.4.1

package/dist/{chunk-QIOMFU35.js → chunk-VV3MFVIG.js}

@@ -1,4 +1,5 @@
 // src/installers/v3-adapter.ts
+import { createHash } from "crypto";
 import {
   lstat,
   mkdir,
@@ -9,6 +10,7 @@ import {
   writeFile
 } from "fs/promises";
 import path from "path";
+import { TextDecoder } from "util";
 
 // src/installers/managed-block.ts
 var DEFAULT_MANCODE_START_MARKER = "<!-- mancode:start -->";
@@ -29,6 +31,20 @@ function hasManagedBlock(existing, startMarker = DEFAULT_MANCODE_START_MARKER, e
   const end = findMarkerLine(existing, endMarker);
   return start !== null && end !== null && end.start > start.start;
 }
+function extractManagedBlock(existing, startMarker = DEFAULT_MANCODE_START_MARKER, endMarker = DEFAULT_MANCODE_END_MARKER) {
+  const starts = findMarkerLines(existing, startMarker);
+  const ends = findMarkerLines(existing, endMarker);
+  if (starts.length === 0 && ends.length === 0) return null;
+  if (starts.length !== 1 || ends.length !== 1) {
+    throw new Error("managed block is malformed: marker count is invalid");
+  }
+  const start = starts[0];
+  const end = ends[0];
+  if (!start || !end || end.start < start.start) {
+    throw new Error("managed block is malformed: marker order is invalid");
+  }
+  return existing.slice(start.start, end.end);
+}
 function cleanUpOrphanedNewlines(content) {
   const trimmed = content.replace(/\n{3,}/gu, "\n\n").replace(/\n+$/u, "\n");
   return trimmed || "";
@@ -75,8 +91,12 @@ function trimTrailingNewlines(value) {
   return value.replace(/\n+$/u, "");
 }
 function findMarkerLine(content, marker) {
+  return findMarkerLines(content, marker)[0] ?? null;
+}
+function findMarkerLines(content, marker) {
   let offset = 0;
   let inFence = null;
+  const matches = [];
   for (const lineWithBreak of content.matchAll(/[^\n]*(?:\n|$)/gu)) {
     const rawLine = lineWithBreak[0];
     if (!rawLine) break;
@@ -90,20 +110,23 @@ function findMarkerLine(content, marker) {
         inFence = null;
       }
     } else if (!inFence && line === marker) {
-      return {
+      matches.push({
         start: offset,
         end: offset + marker.length
-      };
+      });
     }
     offset += rawLine.length;
   }
-  return null;
+  return matches;
 }
 
 // src/installers/v3-adapter.ts
 var V3_ADAPTER_VERSION = "3";
-var V3_ADAPTER_MANAGED_MARKER = "<!-- Managed by mancode:v3-adapter. Do not edit this marker. -->";
-var V3_MODE_ENTRY_MANAGED_MARKER = "<!-- Managed by mancode:v3-mode-entry. Do not edit this marker. -->";
+var V3_ADAPTER_MANAGED_MARKER = "<!-- Managed by mancode:continuity-adapter. Do not edit this marker. -->";
+var V3_MODE_ENTRY_MANAGED_MARKER = "<!-- Managed by mancode:continuity-mode-entry. Do not edit this marker. -->";
+var LEGACY_V3_ADAPTER_MANAGED_MARKER = "<!-- Managed by mancode:v3-adapter. Do not edit this marker. -->";
+var LEGACY_V3_MODE_ENTRY_MANAGED_MARKER = "<!-- Managed by mancode:v3-mode-entry. Do not edit this marker. -->";
+var V3_ADAPTER_DIGEST_DOMAIN = "mancode-adapter-digest-v1";
 var V3_MODE_NAMES = [
   "manba",
   "man",
@@ -112,6 +135,7 @@ var V3_MODE_NAMES = [
   "mansolo"
 ];
 var LEGACY_MODE_ENTRY_MANAGED_MARKERS = [
+  LEGACY_V3_MODE_ENTRY_MANAGED_MARKER,
   "<!-- Managed by mancode:claude-skill. Do not edit this marker. -->",
   "<!-- Managed by mancode:codex-skill. Do not edit this file manually. -->",
   "<!-- Managed by mancode:zcode-skill. Do not edit this file manually. -->",
@@ -134,12 +158,26 @@ var LEGACY_CLAUDE_SETTINGS_RAW_HINTS = [
   ".mancode/hooks/user-prompt-submit.",
   ...LEGACY_CLAUDE_SKILL_PATHS
 ];
-var V3_CODEX_START_MARKER = "<!-- mancode:v3:codex:start -->";
-var V3_CODEX_END_MARKER = "<!-- mancode:v3:codex:end -->";
-var V3_ZCODE_START_MARKER = "<!-- mancode:v3:zcode:start -->";
-var V3_ZCODE_END_MARKER = "<!-- mancode:v3:zcode:end -->";
-var V3_COPILOT_START_MARKER = "<!-- mancode:v3:copilot:start -->";
-var V3_COPILOT_END_MARKER = "<!-- mancode:v3:copilot:end -->";
+var CONTINUITY_CLAUDE_START_MARKER = "<!-- mancode:continuity:claude:start -->";
+var CONTINUITY_CLAUDE_END_MARKER = "<!-- mancode:continuity:claude:end -->";
+var V3_CODEX_START_MARKER = "<!-- mancode:continuity:codex:start -->";
+var V3_CODEX_END_MARKER = "<!-- mancode:continuity:codex:end -->";
+var V3_ZCODE_START_MARKER = "<!-- mancode:continuity:zcode:start -->";
+var V3_ZCODE_END_MARKER = "<!-- mancode:continuity:zcode:end -->";
+var V3_COPILOT_START_MARKER = "<!-- mancode:continuity:copilot:start -->";
+var V3_COPILOT_END_MARKER = "<!-- mancode:continuity:copilot:end -->";
+var LEGACY_V3_CODEX_MARKERS = [
+  "<!-- mancode:v3:codex:start -->",
+  "<!-- mancode:v3:codex:end -->"
+];
+var LEGACY_V3_ZCODE_MARKERS = [
+  "<!-- mancode:v3:zcode:start -->",
+  "<!-- mancode:v3:zcode:end -->"
+];
+var LEGACY_V3_COPILOT_MARKERS = [
+  "<!-- mancode:v3:copilot:start -->",
+  "<!-- mancode:v3:copilot:end -->"
+];
 var LEGACY_CODEX_START_MARKER = "<!-- mancode:start -->";
 var LEGACY_CODEX_END_MARKER = "<!-- mancode:end -->";
 var LEGACY_ZCODE_START_MARKER = "<!-- mancode:zcode:start -->";
@@ -147,6 +185,13 @@ var LEGACY_ZCODE_END_MARKER = "<!-- mancode:zcode:end -->";
 var RETRIABLE_ADAPTER_READ_CODES = /* @__PURE__ */ new Set(["EACCES", "EBUSY", "EPERM"]);
 var ADAPTER_READ_MAX_ATTEMPTS = 4;
 var ADAPTER_READ_RETRY_DELAY_MS = 25;
+var V3_ADAPTER_PLATFORMS = [
+  "claude-code",
+  "codex",
+  "cursor",
+  "copilot",
+  "zcode"
+];
 var V3_MODE_ENTRY_FILE_TARGETS = V3_MODE_NAMES.flatMap((mode) => [
   `claude-mode-${mode}`,
   `agents-mode-${mode}`,
@@ -180,13 +225,27 @@ var V3_ADAPTER_FILE_TARGETS = [
   ...V3_MODE_ENTRY_FILE_TARGETS,
   ...V3_LEGACY_ADAPTER_FILE_TARGETS
 ];
+function adapterManagedContentDigest(targetIdentity, managedContent) {
+  if (!targetIdentity.trim() || targetIdentity.includes("\0")) {
+    throw new Error("MANCODE_V3_ADAPTER_TARGET_IDENTITY_INVALID");
+  }
+  const content = typeof managedContent === "string" ? Buffer.from(managedContent, "utf8") : Buffer.from(managedContent);
+  const digest = createHash("sha256").update(Buffer.from(V3_ADAPTER_DIGEST_DOMAIN, "utf8")).update(Buffer.from([0])).update(Buffer.from(targetIdentity, "utf8")).update(Buffer.from([0])).update(content).digest("hex");
+  return `sha256:${digest}`;
+}
 async function planV3AdapterFiles(projectRoot) {
   const root = path.resolve(projectRoot);
   const existing = /* @__PURE__ */ new Map();
   for (const target of V3_ADAPTER_FILE_TARGETS) {
     existing.set(target, await readAdapterTarget(root, target));
   }
-  const agents = removeLegacyAgentsBlocks(existing.get("agents") ?? "");
+  const agents = removeLegacyV3Block(
+    removeLegacyV3Block(
+      removeLegacyAgentsBlocks(existing.get("agents") ?? ""),
+      LEGACY_V3_CODEX_MARKERS
+    ),
+    LEGACY_V3_ZCODE_MARKERS
+  );
   const nextAgents = replaceManagedV3BlockText(
     replaceManagedV3BlockText(
       agents,
@@ -200,11 +259,16 @@ async function planV3AdapterFiles(projectRoot) {
   );
   const legacyAdapterPlans = planLegacyAdapterRetirement(existing);
   const plans = [
-    managedFilePlan(
-      "claude-skill",
-      existing.get("claude-skill") ?? null,
-      renderClaudeSkill(renderV3Bootstrap("claude-code"))
-    ),
+    {
+      target: "claude-skill",
+      beforeContent: existing.get("claude-skill") ?? null,
+      targetContent: replaceManagedV3BlockText(
+        existing.get("claude-skill") ?? "",
+        CONTINUITY_CLAUDE_START_MARKER,
+        CONTINUITY_CLAUDE_END_MARKER,
+        renderV3Bootstrap("claude-code")
+      )
+    },
     managedFilePlan(
       "cursor-rule",
       existing.get("cursor-rule") ?? null,
@@ -219,7 +283,10 @@ async function planV3AdapterFiles(projectRoot) {
       target: "copilot-instructions",
       beforeContent: existing.get("copilot-instructions") ?? null,
       targetContent: replaceManagedV3BlockText(
-        removeManagedBlock(existing.get("copilot-instructions") ?? ""),
+        removeLegacyV3Block(
+          removeManagedBlock(existing.get("copilot-instructions") ?? ""),
+          LEGACY_V3_COPILOT_MARKERS
+        ),
         V3_COPILOT_START_MARKER,
         V3_COPILOT_END_MARKER,
         renderV3Bootstrap("copilot")
@@ -236,6 +303,73 @@ async function planV3AdapterFiles(projectRoot) {
   ];
   return plans;
 }
+async function planV3AdapterUpgradeFiles(projectRoot, platforms) {
+  const root = path.resolve(projectRoot);
+  const selected = normalizeUpgradePlatforms(platforms);
+  const targetSet = /* @__PURE__ */ new Set();
+  for (const platform of selected) {
+    targetSet.add(primaryFileTarget(platform));
+    for (const mode of V3_MODE_NAMES) {
+      targetSet.add(modeEntryFileTarget(platform, mode));
+    }
+    for (const target of legacyAdapterTargetsForPlatform(platform, true)) {
+      targetSet.add(target);
+    }
+  }
+  const existing = /* @__PURE__ */ new Map();
+  for (const target of targetSet) {
+    existing.set(target, await readAdapterTarget(root, target));
+  }
+  const desired = new Map(existing);
+  for (const platform of selected) {
+    planPlatformBootstrapUpgrade(desired, platform);
+    for (const mode of V3_MODE_NAMES) {
+      const target = modeEntryFileTarget(platform, mode);
+      const current = desired.get(target) ?? null;
+      desired.set(
+        target,
+        managedModeEntryPlan(target, current, renderV3ModeEntry(mode, platform)).targetContent
+      );
+    }
+  }
+  const plans = [...desired.entries()].filter(([target, targetContent]) => existing.get(target) !== targetContent).map(([target, targetContent]) => ({
+    target,
+    beforeContent: existing.get(target) ?? null,
+    targetContent: targetContent ?? ""
+  }));
+  const legacyPlans = planLegacyAdapterRetirement(existing).filter(
+    (legacyPlan) => !plans.some((candidate) => candidate.target === legacyPlan.target)
+  );
+  return [...plans, ...legacyPlans];
+}
+async function stageV3AdapterUpgradeFiles(projectRoot, operationId, plans) {
+  if (!/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/.test(operationId)) {
+    throw new Error("MANCODE_ADAPTER_UPGRADE_OPERATION_ID_INVALID");
+  }
+  const root = path.resolve(projectRoot);
+  const staged = [];
+  for (const plan of plans) {
+    const liveTarget = v3AdapterTargetPath(root, plan.target);
+    const relative = relativeAdapterPath(root, liveTarget);
+    const stagingTarget = path.join(
+      ".mancode",
+      "staging",
+      "adapters",
+      "upgrade",
+      operationId,
+      relative
+    );
+    const destination = path.join(root, stagingTarget);
+    await assertAdapterPathSafe(root, destination);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await atomicWrite(destination, plan.targetContent);
+    staged.push({
+      target: plan.target,
+      stagingTarget: relativeAdapterPath(root, destination)
+    });
+  }
+  return staged;
+}
 async function applyV3AdapterFilePlan(projectRoot, plan) {
   const root = path.resolve(projectRoot);
   if (!V3_ADAPTER_FILE_TARGETS.includes(plan.target)) {
@@ -246,8 +380,30 @@ async function applyV3AdapterFilePlan(projectRoot, plan) {
   }
   const target = v3AdapterTargetPath(root, plan.target);
   await assertAdapterPathSafe(root, target);
+  const retiredBootstrapPlatform = retiredBootstrapPlatformFor(plan.target);
+  if (retiredBootstrapPlatform !== null) {
+    for (const retired of retiredBootstrapSpecs(
+      root,
+      retiredBootstrapPlatform
+    )) {
+      await assertAdapterPathSafe(root, retired.filePath);
+    }
+  }
+  const current = await readAdapterTarget(root, plan.target);
+  if (current === plan.targetContent) {
+    if (retiredBootstrapPlatform !== null) {
+      await removeRetiredBootstrapFiles(root, retiredBootstrapPlatform);
+    }
+    return;
+  }
+  if (current !== plan.beforeContent) {
+    throw new Error("MANCODE_V3_ADAPTER_TARGET_CONFLICT");
+  }
   await mkdir(path.dirname(target), { recursive: true });
   await atomicWrite(target, plan.targetContent);
+  if (retiredBootstrapPlatform !== null) {
+    await removeRetiredBootstrapFiles(root, retiredBootstrapPlatform);
+  }
 }
 async function stageV3Adapter(projectRoot, platform) {
   const root = path.resolve(projectRoot);
@@ -258,7 +414,7 @@ async function stageV3Adapter(projectRoot, platform) {
     ".mancode",
     "staging",
     "adapters",
-    "v3",
+    "continuity",
     platform,
     target
   );
@@ -276,7 +432,7 @@ async function stageV3Adapter(projectRoot, platform) {
       ".mancode",
       "staging",
       "adapters",
-      "v3",
+      "continuity",
       platform,
       modeTarget
     );
@@ -302,9 +458,9 @@ function v3AdapterTargetPath(projectRoot, target) {
   if (legacyTarget !== null) return path.join(root, legacyTarget);
   switch (target) {
     case "claude-skill":
-      return path.join(root, ".claude", "skills", "mancode-v3", "SKILL.md");
+      return path.join(root, "CLAUDE.md");
     case "cursor-rule":
-      return path.join(root, ".cursor", "rules", "mancode-v3.mdc");
+      return path.join(root, ".cursor", "rules", "mancode-continuity.mdc");
     case "agents":
       return path.join(root, "AGENTS.md");
     case "copilot-instructions":
@@ -336,16 +492,20 @@ async function installV3Adapter(projectRoot, platform) {
   const content = renderV3Bootstrap(platform);
   switch (platform) {
     case "claude-code":
-      await writeManagedFile(
-        path.join(root, ".claude", "skills", "mancode-v3", "SKILL.md"),
-        renderClaudeSkill(content)
+      await replaceManagedV3Block(
+        path.join(root, "CLAUDE.md"),
+        CONTINUITY_CLAUDE_START_MARKER,
+        CONTINUITY_CLAUDE_END_MARKER,
+        content
       );
+      await removeRetiredBootstrapFiles(root, platform);
       break;
     case "cursor":
       await writeManagedFile(
-        path.join(root, ".cursor", "rules", "mancode-v3.mdc"),
+        path.join(root, ".cursor", "rules", "mancode-continuity.mdc"),
         renderCursorRule(content)
       );
+      await removeRetiredBootstrapFiles(root, platform);
       break;
     case "codex":
       await replaceManagedV3Block(
@@ -354,6 +514,7 @@ async function installV3Adapter(projectRoot, platform) {
         V3_CODEX_END_MARKER,
         content,
         [
+          LEGACY_V3_CODEX_MARKERS,
           [LEGACY_CODEX_START_MARKER, LEGACY_CODEX_END_MARKER],
           [LEGACY_ZCODE_START_MARKER, LEGACY_ZCODE_END_MARKER]
         ]
@@ -365,7 +526,10 @@ async function installV3Adapter(projectRoot, platform) {
         V3_COPILOT_START_MARKER,
         V3_COPILOT_END_MARKER,
         content,
-        [[LEGACY_CODEX_START_MARKER, LEGACY_CODEX_END_MARKER]]
+        [
+          LEGACY_V3_COPILOT_MARKERS,
+          [LEGACY_CODEX_START_MARKER, LEGACY_CODEX_END_MARKER]
+        ]
       );
       break;
     case "zcode":
@@ -375,6 +539,7 @@ async function installV3Adapter(projectRoot, platform) {
         V3_ZCODE_END_MARKER,
         content,
         [
+          LEGACY_V3_ZCODE_MARKERS,
           [LEGACY_CODEX_START_MARKER, LEGACY_CODEX_END_MARKER],
           [LEGACY_ZCODE_START_MARKER, LEGACY_ZCODE_END_MARKER]
         ]
@@ -403,25 +568,26 @@ async function assertV3AdapterInstallable(projectRoot, platform) {
 }
 async function inspectV3Adapter(projectRoot, platform) {
   const root = path.resolve(projectRoot);
-  await assertPlatformAdapterPathsSafe(root, platform);
   const target = targetFor(platform);
-  const bootstrapInstalled = await adapterTargetPresent(root, platform);
-  const modeEntriesInstalled = (await Promise.all(
-    V3_MODE_NAMES.map(
-      (mode) => v3ModeEntryPresent(v3ModeEntryPath(root, platform, mode))
-    )
-  )).every(Boolean);
-  const installed = bootstrapInstalled && modeEntriesInstalled;
+  const targets = [];
+  for (const spec of managedTargetSpecs(root, platform)) {
+    targets.push(await inspectManagedTarget(root, platform, spec));
+  }
+  const ready = targets.every((item) => item.status === "ready");
+  const installed = targets.every((item) => item.status !== "missing");
+  const status = aggregateAdapterStatus(targets);
   return {
     version: V3_ADAPTER_VERSION,
     installed,
-    ready: installed,
+    ready,
+    status,
     target,
-    detail: installed ? "mancode bootstrap and original mode entries are present; session identity is explicit-required." : "mancode bootstrap or one of its original mode entries is not installed.",
+    detail: status === "ready" ? "Managed adapter content matches the current renderer." : status === "missing" ? "One or more managed adapter targets are missing." : status === "stale" ? "Managed adapter content differs from the current renderer." : "One or more managed adapter targets cannot be read safely.",
+    targets,
     capabilities: capabilitiesFor(platform)
   };
 }
-async function inspectV3AdapterVersions(projectRoot) {
+async function inspectV3AdapterVersions(projectRoot, requiredPlatforms = []) {
   const platforms = [
     "claude-code",
     "codex",
@@ -429,13 +595,25 @@ async function inspectV3AdapterVersions(projectRoot) {
     "copilot",
     "zcode"
   ];
+  const required = new Set(requiredPlatforms);
   const entries = await Promise.all(
-    platforms.map(async (platform) => {
-      const status = await inspectV3Adapter(projectRoot, platform);
-      return [platform, status.ready ? status.version : "missing"];
-    })
+    platforms.map(
+      async (platform) => [platform, await inspectV3Adapter(projectRoot, platform)]
+    )
+  );
+  return v3AdapterVersionsFromStatuses(entries, required);
+}
+function v3AdapterVersionsFromStatuses(entries, requiredPlatforms = []) {
+  const required = requiredPlatforms instanceof Set ? requiredPlatforms : new Set(requiredPlatforms);
+  const versions = entries.map(([platform, status]) => {
+    const primaryPresent = status.targets[0]?.status !== "missing";
+    return required.has(platform) || primaryPresent ? [platform, status.ready ? status.version : status.status] : null;
+  });
+  return Object.fromEntries(
+    versions.filter(
+      (entry) => entry !== null
+    )
   );
-  return Object.fromEntries(entries);
 }
 async function removeV3Adapter(projectRoot, platform) {
   const root = path.resolve(projectRoot);
@@ -443,14 +621,18 @@ async function removeV3Adapter(projectRoot, platform) {
   let preserveSharedModeEntries = false;
   switch (platform) {
     case "claude-code":
-      await removeManagedFile(
-        path.join(root, ".claude", "skills", "mancode-v3", "SKILL.md")
+      await removeManagedV3Block(
+        path.join(root, "CLAUDE.md"),
+        CONTINUITY_CLAUDE_START_MARKER,
+        CONTINUITY_CLAUDE_END_MARKER
       );
+      await removeRetiredBootstrapFiles(root, platform);
       break;
     case "cursor":
       await removeManagedFile(
-        path.join(root, ".cursor", "rules", "mancode-v3.mdc")
+        path.join(root, ".cursor", "rules", "mancode-continuity.mdc")
       );
+      await removeRetiredBootstrapFiles(root, platform);
       break;
     case "codex":
       await removeManagedV3Block(
@@ -458,10 +640,13 @@ async function removeV3Adapter(projectRoot, platform) {
         V3_CODEX_START_MARKER,
         V3_CODEX_END_MARKER
       );
-      preserveSharedModeEntries = await managedBlockPresent(
+      await removeManagedV3Block(
+        path.join(root, "AGENTS.md"),
+        ...LEGACY_V3_CODEX_MARKERS
+      );
+      preserveSharedModeEntries = await anyManagedBlockPresent(
         path.join(root, "AGENTS.md"),
-        V3_ZCODE_START_MARKER,
-        V3_ZCODE_END_MARKER
+        [[V3_ZCODE_START_MARKER, V3_ZCODE_END_MARKER], LEGACY_V3_ZCODE_MARKERS]
       );
       break;
     case "copilot":
@@ -470,6 +655,10 @@ async function removeV3Adapter(projectRoot, platform) {
         V3_COPILOT_START_MARKER,
         V3_COPILOT_END_MARKER
       );
+      await removeManagedV3Block(
+        path.join(root, ".github", "copilot-instructions.md"),
+        ...LEGACY_V3_COPILOT_MARKERS
+      );
       break;
     case "zcode":
       await removeManagedV3Block(
@@ -477,10 +666,13 @@ async function removeV3Adapter(projectRoot, platform) {
         V3_ZCODE_START_MARKER,
         V3_ZCODE_END_MARKER
       );
-      preserveSharedModeEntries = await managedBlockPresent(
+      await removeManagedV3Block(
         path.join(root, "AGENTS.md"),
-        V3_CODEX_START_MARKER,
-        V3_CODEX_END_MARKER
+        ...LEGACY_V3_ZCODE_MARKERS
+      );
+      preserveSharedModeEntries = await anyManagedBlockPresent(
+        path.join(root, "AGENTS.md"),
+        [[V3_CODEX_START_MARKER, V3_CODEX_END_MARKER], LEGACY_V3_CODEX_MARKERS]
       );
       break;
   }
@@ -504,16 +696,25 @@ function renderV3Bootstrap(platform) {
     "",
     `- Platform: ${platformLabel}. This file is a non-authoritative bootstrap.`,
     "- Locate the project root before running mancode commands.",
+    "- Before the first command, choose one CLI binary for the entire task: use `./node_modules/.bin/mancode` when it exists, otherwise use `mancode`. Run that selected binary with `--version` once and never mix binaries or versions.",
+    "- In every command below, `mancode` means that selected binary; when the local binary exists, invoke the command as `./node_modules/.bin/mancode ...` rather than falling back to a global executable.",
     "- Reuse a `mancode status --brief --json` snapshot already obtained in this conversation. Only when no such snapshot exists, run it once from the project root.",
+    "- Inspect a session read-only with `mancode context session show --session <id> --client <client> --json`; do not invent other session subcommands.",
     "- The compact status is the public mancode Continuity runtime view. In operator-facing narration, say `mancode` or `mancode Continuity`; never prefix a mode or action with a version label.",
     "- An explicitly invoked original `man`, `manba`, `manteam`, `manps`, or `mansolo` entry supplies its authorized action. Its mode-specific steps override conflicting generic no-task or mutation guidance below.",
     "- In particular, `manps` may run local health scans without an actor, session, or TaskRef. `mansolo` needs them only for an explicit governed handoff.",
-    '- If status has no `identity.actorId`, ask for a display name and run `mancode team identity create --name "<display name>"` before creating a session.',
+    "- Outside an explicitly invoked mode entry, treat an ordinary requested coding task as default Solo work. Ordinary Solo work requires no actor identity, session, TaskRef, or workflow; do not ask for a display name or create Continuity authority for it.",
+    "- Before editing in default Solo, inspect only the relevant project facts, implementation, tests, and contracts. A supplied instruction is not automatically sound: verify its factual assumptions and proposed solution against the repository and the operator's goal.",
+    "- If the goal and decision-changing requirements are clear, consistent with project evidence, and low risk, proceed with the narrowest useful change without ceremonial questions. Resolve repository-answerable unknowns yourself.",
+    "- When the goal is clear but requirements are incomplete, classify each remaining unknown as blocking, recommendable, or defaultable. Ask and wait only for blocking decisions that can materially change behavior, scope, acceptance, architecture, data, security, compatibility, or semantic ownership. For recommendable decisions, give bounded options and a clear recommendation. Use a default only when it is low-impact, reversible, consistent with repository conventions, and stated explicitly.",
+    "- If an explicit request conflicts with repository evidence or introduces a hard-risk change involving authentication, payment, sensitive data, deletion, migration, public APIs, untrusted input, concurrency, infrastructure, or another irreversible effect, stop before editing. Show the concrete conflict or impact, recommend the safer path, ask a focused confirmation or choice, and wait. Clarity never overrides safety or the operator's actual goal.",
+    "- A natural-language request explicitly asking for research, a plan, architecture, migration design, or formal acceptance authorizes the `man` planning path without a separate mode-confirmation question. For an ordinary implementation request whose blocking decision crosses modules or requires architecture, migration, semantic owner/source-of-truth, team coordination, or formal acceptance, recommend `/man`, explain why, and wait; never switch authority silently.",
+    '- For governed task work only, if status has no `identity.actorId`, ask for a display name and run `mancode team identity create --name "<display name>"` before creating a session.',
     "- If status reports `session`, reuse it. `task: null` and `MANCODE_TASK_REQUIRED` do not make a session stale.",
     `- ${sessionCreationGuidance} Pass its returned \`sessionId\` and matching client as \`${sessionArguments}\` to every later session command; an \`export\` inside one command tool does not persist to later command tools.`,
-    '- Outside an invoked original mode entry, if no current task and no task is explicitly supplied, report "no task bound" and stop. Do not probe workflow subcommands to work around `MANCODE_TASK_REQUIRED`.',
+    '- Outside an invoked original mode entry, if no coding, planning, diagnostic, or review task was requested and no TaskRef is explicitly supplied, report "no task bound" and stop. Do not probe workflow subcommands to work around `MANCODE_TASK_REQUIRED`.',
     "- Bootstrap discovery is read-only: before the operator explicitly requests task work, do not run `mancode init`, `mancode migrate`, `mancode workflow`, or inspect mancode installed package/source.",
-    `- With an existing or supplied task, read its Context Pack with \`mancode context show --purpose orient ${sessionArguments}\`; for anonymous diagnosis, include an explicit \`--task <namespace:id>\`.`,
+    `- With an existing or explicitly supplied TaskRef, read its Context Pack with \`mancode context show --purpose orient ${sessionArguments}\`; for anonymous diagnosis, include an explicit \`--task <namespace:id>\`. A plain-language Solo request is not a TaskRef and needs no Context Pack.`,
     "- After an operator explicitly requests task work, perform mutations only through `mancode workflow`, `mancode team`, and `mancode context` commands with their required revision and session arguments.",
     "- For a mode entry, request the matching Context Pack purpose: `plan`, `implement`, `review`, `verify`, or `handoff`.",
     "- Do not persist task, mode, or session state in this adapter file or any legacy state file.",
@@ -526,6 +727,7 @@ function renderV3ModeEntry(mode, platform) {
   const sessionArguments = sessionArgumentsFor(platform);
   const sessionClientGuidance = sessionClientGuidanceFor(platform);
   const statusGuidance = "Reuse a `mancode status --brief --json` snapshot already obtained in this conversation. Only when none exists, run it once from the project root.";
+  const cliSelectionGuidance = "Before the first command, use `./node_modules/.bin/mancode` when it exists, otherwise `mancode`; check that selected binary with `--version` once and never mix binaries or versions. In every command below, replace the literal `mancode` with that selected binary path when the local binary exists.";
   const sessionCreationGuidance = platform === "codex" || platform === "zcode" ? "If status has no current session, reuse an explicit session ID already retained in this conversation. Only if neither exists, run `mancode context session new --client codex` in Codex or `mancode context session new --client zcode` in ZCode exactly once, then retain the returned session ID." : `If status has no current session, reuse an explicit session ID already retained in this conversation. Only if neither exists, run \`mancode context session new --client ${platform}\` exactly once and retain the returned session ID.`;
   let authoritySteps;
   if (mode === "manps") {
@@ -581,6 +783,7 @@ function renderV3ModeEntry(mode, platform) {
     "",
     "## Enter through mancode",
     "",
+    cliSelectionGuidance,
     ...authoritySteps,
     "",
     "## Mode action",
@@ -608,9 +811,22 @@ var V3_MODE_DEFINITIONS = {
     actions: [
       "- For a read-only project orientation, inspect and answer directly; do not create governance records.",
       '- For a new task, run `mancode workflow create man "<task>" --session <id>`.',
-      "- Write requirements as semantic JSON with `version: 1`, `goal`, `confirmedScope`, `excludedScope`, `technicalDecisions`, `defaults`, `blockingUnknowns`, all seven `coverage` dimensions, and `acceptanceCriteria`; mancode generates canonical internal IDs and digests.",
+      "- Before writing requirements, inspect the relevant project facts and implementation, then run a decision-readiness gate covering both clarity and soundness. Treat the request as ready only when the goal, in-scope/out-of-scope behavior, acceptance boundary, semantic owner/source of truth, and decision-changing constraints are supplied and consistent with evidence, verifiable from the repository, or explicitly recorded as safe defaults. A supplied instruction is not automatically correct. Do not ask ceremonial questions or manufacture alternatives when the request is already clear and sound.",
+      "- Classify unresolved decisions as blocking, recommendable, or defaultable. Ask and wait for blocking decisions; for recommendable decisions, present 2\u20133 bounded options with tradeoffs and one clear recommendation; use a default only when it is low-impact, reversible, consistent with repository conventions, and recorded with its reason.",
+      "- If any unresolved ambiguity could change the goal, scope, user-visible behavior, acceptance, architecture, data, security, compatibility, owner, or source of truth, stop before requirements finalization, explain the missing decision, ask focused questions, and wait for the user answer. Ask in as many batches as needed, do not repeat answered questions, and never turn an unverified assumption into confirmed scope or confirmed coverage.",
+      "- Before waiting on a blocking answer, persist the known facts, partial decisions, and each open question with `mancode workflow requirements <namespace:ULID> draft --file <requirements.json> --expected-revision <n> --session <id>`. A draft may leave scope, coverage, technical decisions, or acceptance incomplete only while `blockingUnknowns` names the open decisions. After every answer, update the draft or finalize it so another session can resume the exact clarification state.",
+      "- If an explicit direction conflicts with repository evidence or creates a hard-risk authentication, payment, sensitive-data, deletion, migration, public-API, untrusted-input, concurrency, infrastructure, or irreversible change, stop before requirements finalization. Show the evidence and impact, recommend a safer path, ask for a focused confirmation or choice, and wait; clarity does not waive risk.",
+      "- After the user answers, summarize the resolved requirements and any remaining defaults. Continue only when no decision-changing blocking unknown remains; otherwise keep the task in clarification and ask again.",
+      "- Write requirements as semantic JSON with `version: 1`, a non-empty `goal`, non-empty `confirmedScope`, and the arrays `excludedScope`, `technicalDecisions`, `defaults`, and `blockingUnknowns`. Every array item must be a non-empty string; an array may be empty except `confirmedScope`, and `technicalDecisions` must be non-empty whenever `technical_stack` applies.",
+      '- `coverage` must contain exactly one item for each dimension: `platform`, `core_scope`, `technical_stack`, `data_and_persistence`, `performance`, `compatibility`, and `security`. Each item has the shape `{ "dimension": "platform", "status": "confirmed", "rationale": "..." }`; `status` is exactly `confirmed`, `defaulted`, or `not_applicable`, and `rationale` is non-empty.',
+      '- `acceptanceCriteria` must contain at least one required item shaped as `{ "id": "AC-1", "description": "...", "required": true, "method": "automated" }`; `method` is exactly `automated`, `manual`, or `hybrid`.',
       "- Finalize requirements with `mancode workflow requirements <namespace:ULID> finalize --file <requirements.json> --expected-revision <n> --session <id>`.",
-      "- Revise or confirm the plan with `mancode workflow plan <namespace:ULID> revise|confirm --expected-revision <n> ... --session <id>`.",
+      "- Let mancode assign internal IDs and digests; do not invent canonical IDs or digests in the semantic input.",
+      "- Revise the plan with `mancode workflow plan <namespace:ULID> revise --expected-revision <n> --file <plan.md> --session <id>`.",
+      "- Confirm the current plan with `mancode workflow plan <namespace:ULID> confirm --expected-revision <n> --plan-decision <plan_only|governed_execution> --session <id>`.",
+      "- Confirming with `--plan-decision plan_only` keeps the plan as planned authority and clears this session's active workflow pointer. Resume the TaskRef explicitly before any later governed mutation.",
+      '- When new evidence materially invalidates confirmed requirements and the operator explicitly chooses to realign the same local task, resume its TaskRef if needed, generate a fresh canonical checkpoint ULID, and run `mancode workflow reframe <namespace:ULID> --expected-revision <n> --checkpoint-id <fresh-ULID> --summary "<reason>" --next-action "<step-2 action>" --session <id>`. Reframe archives the confirmed requirements and plan, clears the plan decision, and stops at Step 2 with draft requirements. Do not substitute plan revise, scope-change, or workflow update for reframe.',
+      "- Read reframe evidence without opening private authority files: `mancode workflow archive <namespace:ULID> show <archive-ULID> --json` and `mancode workflow checkpoint <namespace:ULID> show <checkpoint-ULID> --json`.",
       "- Apply verification and review ledgers with their mancode `apply --file` commands, then use `mancode workflow complete <namespace:ULID> --expected-revision <n> --session <id>`."
     ]
   },
@@ -620,6 +836,8 @@ var V3_MODE_DEFINITIONS = {
     contextPurpose: "implement",
     actions: [
       '- For a new diagnostic task, run `mancode workflow create manba "<task>" --session <id>`.',
+      "- Before changing code, establish the expected behavior from reproducible evidence, tests, documentation, history, or the current semantic owner. If the bug goal is clear but the correct behavior cannot be established, ask one focused question and wait instead of inventing product behavior.",
+      "- If the requested fix conflicts with repository evidence or crosses a hard-risk boundary, show the conflict and obtain a focused confirmation or route the decision through `/man`; do not treat an explicit but unsound fix instruction as sufficient evidence.",
       "- When this is a child investigation, add `--parent <namespace:ULID>`; report and merge the typed outcome through the mancode child commands.",
       "- Change lifecycle only with `mancode workflow update <namespace:ULID> --status <status> --expected-revision <n> --session <id>` and finish with `workflow complete` plus the typed `--outcome`."
     ]
@@ -631,8 +849,10 @@ var V3_MODE_DEFINITIONS = {
     actions: [
       "- Confirm team membership with `mancode team status`; join invited participants before assigning shared work.",
       '- For a new shared task, run `mancode workflow create manteam "<task>" --visibility shared --coordination team --confirm-shared --session <id>`.',
+      "- Apply the same decision-readiness gate as `man` before finalizing requirements: validate both clarity and soundness against project facts and team authority. If the goal, scope, acceptance, owner/source of truth, and constraints are clear and consistent, continue without ceremonial questions; if a decision-changing ambiguity, ownership conflict, or hard-risk direction remains, give evidence and a recommendation, ask focused questions, and wait before writing confirmed requirements.",
+      "- Persist unresolved team clarification through the same `workflow requirements <namespace:ULID> draft --file <requirements.json>` command as `man`; do not leave ownership questions or partial answers only in chat history.",
       "- Use claims, checkpoints, sync, and handoffs through `mancode team`; never infer ownership from an adapter prompt.",
-      "- Use the same mancode requirements, plan, verification, review, and completion commands as `man`, adding `--sync` whenever the active transport requires it."
+      "- With git-ref transport, workflow creation plus requirements, plan, review, and verification mutations use an explicit deferred publication boundary: run the workflow command without `--sync`, commit the resulting `.mancode/shared` authority changes together with the matching code head, then run `mancode team sync push <shared:ULID> --expected-task-revision <n>`. Never report cross-clone synchronization before the push returns a receipt. Use `--sync` only for a command whose contract performs an atomic git-ref mutation."
     ]
   },
   manps: {
@@ -650,6 +870,10 @@ var V3_MODE_DEFINITIONS = {
     contextPurpose: "implement",
     actions: [
       "- Do not create or persist a legacy solo mode. Ordinary focused work needs no TaskRef; if the operator expects a governed task, use its bound TaskRef or report that none is bound.",
+      "- Before editing, assess both clarity and soundness using the project facts. If the request is clear, consistent, and low risk, proceed without ceremonial questions. Resolve repository-answerable unknowns yourself; classify the rest as blocking, recommendable, or defaultable. Ask and wait only when a blocking unknown could materially change behavior, scope, acceptance, data, security, compatibility, or ownership.",
+      "- A supplied implementation direction is not automatically safe. If it conflicts with repository evidence or involves authentication, payment, sensitive data, deletion, migration, public APIs, untrusted input, concurrency, infrastructure, or another irreversible effect, show the evidence and impact, recommend the safer path, ask for focused confirmation, and wait before editing.",
+      "- If resolving the ambiguity requires architecture, semantic owner/source-of-truth, cross-module scope, migration, team coordination, or formal acceptance decisions, recommend `/man`, explain the trigger, and wait for the operator to choose; advice alone never changes mode or authority.",
+      "- Detect those governance triggers after the smallest fact check needed to establish them. Stop before exhaustive discovery or proposing a concrete topology, migration layout, or implementation plan that depends on unanswered decisions.",
       "- For a governed-to-solo transition, use `mancode workflow handoff <namespace:ULID> --to solo --expected-revision <n> --session <id>`."
     ]
   }
@@ -658,11 +882,12 @@ async function renderV3AdapterCandidate(root, platform) {
   switch (platform) {
     case "claude-code": {
       const existing = await readAdapterTarget(root, "claude-skill");
-      return managedFilePlan(
-        "claude-skill",
-        existing,
-        renderClaudeSkill(renderV3Bootstrap(platform))
-      ).targetContent;
+      return replaceManagedV3BlockText(
+        existing ?? "",
+        CONTINUITY_CLAUDE_START_MARKER,
+        CONTINUITY_CLAUDE_END_MARKER,
+        renderV3Bootstrap(platform)
+      );
     }
     case "cursor": {
       const existing = await readAdapterTarget(root, "cursor-rule");
@@ -675,7 +900,10 @@ async function renderV3AdapterCandidate(root, platform) {
     case "codex": {
       const existing = await readAdapterTarget(root, "agents") ?? "";
       return replaceManagedV3BlockText(
-        removeLegacyAgentsBlocks(existing),
+        removeLegacyV3Block(
+          removeLegacyAgentsBlocks(existing),
+          LEGACY_V3_CODEX_MARKERS
+        ),
         V3_CODEX_START_MARKER,
         V3_CODEX_END_MARKER,
         renderV3Bootstrap(platform)
@@ -684,7 +912,10 @@ async function renderV3AdapterCandidate(root, platform) {
     case "copilot": {
       const existing = await readAdapterTarget(root, "copilot-instructions") ?? "";
       return replaceManagedV3BlockText(
-        removeManagedBlock(existing),
+        removeLegacyV3Block(
+          removeManagedBlock(existing),
+          LEGACY_V3_COPILOT_MARKERS
+        ),
         V3_COPILOT_START_MARKER,
         V3_COPILOT_END_MARKER,
         renderV3Bootstrap(platform)
@@ -693,7 +924,10 @@ async function renderV3AdapterCandidate(root, platform) {
     case "zcode": {
       const existing = await readAdapterTarget(root, "agents") ?? "";
       return replaceManagedV3BlockText(
-        removeLegacyAgentsBlocks(existing),
+        removeLegacyV3Block(
+          removeLegacyAgentsBlocks(existing),
+          LEGACY_V3_ZCODE_MARKERS
+        ),
         V3_ZCODE_START_MARKER,
         V3_ZCODE_END_MARKER,
         renderV3Bootstrap(platform)
@@ -701,18 +935,6 @@ async function renderV3AdapterCandidate(root, platform) {
     }
   }
 }
-function renderClaudeSkill(content) {
-  return [
-    "---",
-    "name: mancode-v3",
-    'description: "Internal bootstrap for the original mancode mode entries."',
-    "user-invocable: false",
-    "---",
-    "",
-    content,
-    ""
-  ].join("\n");
-}
 function renderCursorRule(content) {
   return [
     "---",
@@ -725,39 +947,283 @@ function renderCursorRule(content) {
     ""
   ].join("\n");
 }
-async function adapterTargetPresent(root, platform) {
+function managedTargetSpecs(root, platform) {
+  const primary = primaryManagedTargetSpec(platform);
+  const modes = V3_MODE_NAMES.map((mode) => {
+    const fileTarget = modeEntryFileTarget(platform, mode);
+    return {
+      identity: fileTarget,
+      target: relativeAdapterPath(root, v3ModeEntryPath(root, platform, mode)),
+      fileTarget,
+      expectedManagedContent: renderV3ModeEntry(mode, platform),
+      blockMarkers: null
+    };
+  });
+  return [primary, ...modes];
+}
+function normalizeUpgradePlatforms(platforms) {
+  if (!Array.isArray(platforms) || platforms.length === 0) {
+    throw new Error("MANCODE_ADAPTER_UPGRADE_PLATFORM_REQUIRED");
+  }
+  const selected = /* @__PURE__ */ new Set();
+  for (const platform of platforms) {
+    if (!V3_ADAPTER_PLATFORMS.includes(platform)) {
+      throw new Error("MANCODE_ADAPTER_UPGRADE_PLATFORM_INVALID");
+    }
+    selected.add(platform);
+  }
+  return V3_ADAPTER_PLATFORMS.filter((platform) => selected.has(platform));
+}
+function primaryFileTarget(platform) {
+  switch (platform) {
+    case "claude-code":
+      return "claude-skill";
+    case "cursor":
+      return "cursor-rule";
+    case "codex":
+    case "zcode":
+      return "agents";
+    case "copilot":
+      return "copilot-instructions";
+  }
+}
+function planPlatformBootstrapUpgrade(desired, platform) {
+  const target = primaryFileTarget(platform);
+  const current = desired.get(target) ?? null;
   switch (platform) {
     case "claude-code":
-      return managedFilePresent(
-        path.join(root, ".claude", "skills", "mancode-v3", "SKILL.md")
+      desired.set(
+        target,
+        replaceManagedV3BlockText(
+          current ?? "",
+          CONTINUITY_CLAUDE_START_MARKER,
+          CONTINUITY_CLAUDE_END_MARKER,
+          renderV3Bootstrap(platform)
+        )
       );
+      return;
     case "cursor":
-      return managedFilePresent(
-        path.join(root, ".cursor", "rules", "mancode-v3.mdc")
+      desired.set(
+        target,
+        managedFilePlan(
+          target,
+          current,
+          renderCursorRule(renderV3Bootstrap(platform))
+        ).targetContent
       );
+      return;
     case "codex":
-      return managedBlockPresent(
-        path.join(root, "AGENTS.md"),
+      desired.set(
+        target,
+        replaceManagedV3BlockText(
+          removeLegacyV3Block(
+            removeLegacyAgentsBlocks(current ?? ""),
+            LEGACY_V3_CODEX_MARKERS
+          ),
+          V3_CODEX_START_MARKER,
+          V3_CODEX_END_MARKER,
+          renderV3Bootstrap(platform)
+        )
+      );
+      return;
+    case "zcode":
+      desired.set(
+        target,
+        replaceManagedV3BlockText(
+          removeLegacyV3Block(
+            removeLegacyAgentsBlocks(current ?? ""),
+            LEGACY_V3_ZCODE_MARKERS
+          ),
+          V3_ZCODE_START_MARKER,
+          V3_ZCODE_END_MARKER,
+          renderV3Bootstrap(platform)
+        )
+      );
+      return;
+    case "copilot":
+      desired.set(
+        target,
+        replaceManagedV3BlockText(
+          removeLegacyV3Block(
+            removeManagedBlock(current ?? ""),
+            LEGACY_V3_COPILOT_MARKERS
+          ),
+          V3_COPILOT_START_MARKER,
+          V3_COPILOT_END_MARKER,
+          renderV3Bootstrap(platform)
+        )
+      );
+  }
+}
+function primaryManagedTargetSpec(platform) {
+  const target = targetFor(platform);
+  switch (platform) {
+    case "claude-code":
+      return embeddedManagedTargetSpec(
+        target,
+        "claude-instructions#continuity",
+        "claude-skill",
+        CONTINUITY_CLAUDE_START_MARKER,
+        CONTINUITY_CLAUDE_END_MARKER,
+        renderV3Bootstrap(platform)
+      );
+    case "cursor":
+      return {
+        identity: "cursor-rule",
+        target,
+        fileTarget: "cursor-rule",
+        expectedManagedContent: renderCursorRule(renderV3Bootstrap(platform)),
+        blockMarkers: null
+      };
+    case "codex":
+      return embeddedManagedTargetSpec(
+        target,
+        "agents#codex",
+        "agents",
         V3_CODEX_START_MARKER,
-        V3_CODEX_END_MARKER
+        V3_CODEX_END_MARKER,
+        renderV3Bootstrap(platform)
       );
     case "copilot":
-      return managedBlockPresent(
-        path.join(root, ".github", "copilot-instructions.md"),
+      return embeddedManagedTargetSpec(
+        target,
+        "copilot-instructions#copilot",
+        "copilot-instructions",
         V3_COPILOT_START_MARKER,
-        V3_COPILOT_END_MARKER
+        V3_COPILOT_END_MARKER,
+        renderV3Bootstrap(platform)
       );
     case "zcode":
-      return managedBlockPresent(
-        path.join(root, "AGENTS.md"),
+      return embeddedManagedTargetSpec(
+        target,
+        "agents#zcode",
+        "agents",
         V3_ZCODE_START_MARKER,
-        V3_ZCODE_END_MARKER
+        V3_ZCODE_END_MARKER,
+        renderV3Bootstrap(platform)
       );
   }
 }
+function embeddedManagedTargetSpec(target, identity, fileTarget, startMarker, endMarker, content) {
+  return {
+    identity,
+    target,
+    fileTarget,
+    expectedManagedContent: [startMarker, content, endMarker].join("\n"),
+    blockMarkers: [startMarker, endMarker]
+  };
+}
+function modeEntryFileTarget(platform, mode) {
+  const family = platform === "claude-code" ? "claude" : platform === "codex" || platform === "zcode" ? "agents" : platform;
+  return `${family}-mode-${mode}`;
+}
+async function inspectManagedTarget(root, platform, spec) {
+  const expectedDigest = adapterManagedContentDigest(
+    spec.identity,
+    spec.expectedManagedContent
+  );
+  const repair = [
+    `Preview with \`mancode adapter upgrade --platform ${platform} --dry-run\`.`,
+    `Confirm that exact preview with \`mancode adapter upgrade --platform ${platform} --confirm --operation-id <operationId> --session <id>\`.`
+  ].join(" ");
+  try {
+    const bytes = await readAdapterBytesIfExists(
+      root,
+      v3AdapterTargetPath(root, spec.fileTarget)
+    );
+    if (bytes === null) {
+      return managedTargetStatus(
+        spec,
+        "missing",
+        null,
+        expectedDigest,
+        repair,
+        "Managed target does not exist."
+      );
+    }
+    const content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    let managedContent;
+    if (spec.blockMarkers === null) {
+      managedContent = content;
+    } else {
+      try {
+        const extracted = extractManagedBlock(
+          content,
+          spec.blockMarkers[0],
+          spec.blockMarkers[1]
+        );
+        if (extracted === null) {
+          return managedTargetStatus(
+            spec,
+            "missing",
+            null,
+            expectedDigest,
+            repair,
+            "Managed block is absent from the target file."
+          );
+        }
+        managedContent = extracted;
+      } catch (error) {
+        return managedTargetStatus(
+          spec,
+          "stale",
+          null,
+          expectedDigest,
+          repair,
+          error instanceof Error ? error.message : "Managed block is malformed."
+        );
+      }
+    }
+    const actualDigest = adapterManagedContentDigest(
+      spec.identity,
+      managedContent
+    );
+    const status = actualDigest === expectedDigest ? "ready" : "stale";
+    return managedTargetStatus(
+      spec,
+      status,
+      actualDigest,
+      expectedDigest,
+      status === "ready" ? "none" : repair,
+      status === "ready" ? "Managed content matches the current renderer." : "Managed content differs from the current renderer."
+    );
+  } catch (error) {
+    return managedTargetStatus(
+      spec,
+      "unreadable",
+      null,
+      expectedDigest,
+      `Resolve the filesystem or UTF-8 error, then ${repair}`,
+      error instanceof Error ? error.message : "Managed target is unreadable."
+    );
+  }
+}
+function managedTargetStatus(spec, status, actualDigest, expectedDigest, repair, detail) {
+  return {
+    identity: spec.identity,
+    target: spec.target,
+    status,
+    actualDigest,
+    expectedDigest,
+    rendererVersion: V3_ADAPTER_VERSION,
+    repair,
+    detail
+  };
+}
+function aggregateAdapterStatus(targets) {
+  if (targets.every((target) => target.status === "ready")) return "ready";
+  if (targets.some((target) => target.status === "unreadable")) {
+    return "unreadable";
+  }
+  if (targets.some((target) => target.status === "stale")) return "stale";
+  return "missing";
+}
+function relativeAdapterPath(root, target) {
+  return path.relative(root, target).split(path.sep).join("/");
+}
 async function writeManagedFile(filePath, content) {
   const existing = await readTextIfExists(filePath);
-  if (existing !== null && !existing.includes(V3_ADAPTER_MANAGED_MARKER)) {
+  if (existing !== null && !existing.includes(V3_ADAPTER_MANAGED_MARKER) && !existing.includes(LEGACY_V3_ADAPTER_MANAGED_MARKER)) {
     throw new Error("MANCODE_V3_ADAPTER_TARGET_USER_AUTHORED");
   }
   await mkdir(path.dirname(filePath), { recursive: true });
@@ -788,15 +1254,13 @@ async function assertV3ModeEntriesWritable(root, platform) {
 }
 async function removeV3ModeEntry(filePath) {
   const existing = await readTextIfExists(filePath);
-  if (existing?.includes(V3_MODE_ENTRY_MANAGED_MARKER)) {
+  if (existing?.includes(V3_MODE_ENTRY_MANAGED_MARKER) || LEGACY_MODE_ENTRY_MANAGED_MARKERS.some(
+    (marker) => existing?.includes(marker)
+  )) {
     await rm(filePath, { force: true });
     await removeDirectoryIfEmpty(path.dirname(filePath));
   }
 }
-async function v3ModeEntryPresent(filePath) {
-  const existing = await readTextIfExists(filePath);
-  return existing?.includes(V3_MODE_ENTRY_MANAGED_MARKER) ?? false;
-}
 async function removeDirectoryIfEmpty(directory) {
   try {
     await rmdir(directory);
@@ -813,6 +1277,18 @@ async function removeManagedFile(filePath) {
     await rm(filePath, { force: true });
   }
 }
+async function removeRetiredBootstrapFiles(root, platform) {
+  if (platform !== "claude-code" && platform !== "cursor") return;
+  for (const retired of retiredBootstrapSpecs(root, platform)) {
+    await assertAdapterPathSafe(root, retired.filePath);
+    const existing = await readTextIfExists(retired.filePath);
+    if (!retired.managedMarkers.some((marker) => existing?.includes(marker))) {
+      continue;
+    }
+    await rm(retired.filePath, { force: true });
+    await removeDirectoryIfEmpty(path.dirname(retired.filePath));
+  }
+}
 async function replaceManagedV3Block(filePath, startMarker, endMarker, content, legacyMarkers) {
   const current = await readTextIfExists(filePath) ?? "";
   const existing = (legacyMarkers ?? []).reduce(
@@ -837,6 +1313,9 @@ function removeLegacyAgentsBlocks(existing) {
     LEGACY_ZCODE_END_MARKER
   );
 }
+function removeLegacyV3Block(existing, markers) {
+  return removeManagedBlock(existing, markers[0], markers[1]);
+}
 function replaceManagedV3BlockText(existing, startMarker, endMarker, content) {
   return replaceManagedBlock(
     existing,
@@ -846,7 +1325,7 @@ function replaceManagedV3BlockText(existing, startMarker, endMarker, content) {
   );
 }
 function managedFilePlan(target, beforeContent, targetContent) {
-  if (beforeContent !== null && !beforeContent.includes(V3_ADAPTER_MANAGED_MARKER)) {
+  if (beforeContent !== null && !beforeContent.includes(V3_ADAPTER_MANAGED_MARKER) && !beforeContent.includes(LEGACY_V3_ADAPTER_MANAGED_MARKER)) {
     throw new Error("MANCODE_V3_ADAPTER_TARGET_USER_AUTHORED");
   }
   return { target, beforeContent, targetContent };
@@ -1175,6 +1654,11 @@ async function assertPlatformAdapterPathsSafe(root, platform) {
       (target) => v3AdapterTargetPath(root, target)
     )
   ]);
+  if (platform === "claude-code" || platform === "cursor") {
+    for (const retired of retiredBootstrapSpecs(root, platform)) {
+      targets.add(retired.filePath);
+    }
+  }
   for (const target of targets) {
     await assertAdapterPathSafe(root, target);
   }
@@ -1216,13 +1700,35 @@ async function removeManagedV3Block(filePath, startMarker, endMarker) {
     await rm(filePath, { force: true });
   }
 }
-async function managedFilePresent(filePath) {
+async function anyManagedBlockPresent(filePath, markerPairs) {
   const content = await readTextIfExists(filePath);
-  return content?.includes(V3_ADAPTER_MANAGED_MARKER) ?? false;
+  return content !== null && markerPairs.some(
+    ([startMarker, endMarker]) => hasManagedBlock(content, startMarker, endMarker)
+  );
 }
-async function managedBlockPresent(filePath, startMarker, endMarker) {
-  const content = await readTextIfExists(filePath);
-  return content !== null && hasManagedBlock(content, startMarker, endMarker);
+async function readAdapterBytesIfExists(root, filePath) {
+  await assertAdapterPathSafe(root, filePath);
+  try {
+    const entry = await lstat(filePath);
+    if (!entry.isFile() || entry.isSymbolicLink()) {
+      throw new Error("MANCODE_ARTIFACT_PATH_UNSAFE");
+    }
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return null;
+    throw error;
+  }
+  for (let attempt = 1; attempt <= ADAPTER_READ_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      return await readFile(filePath);
+    } catch (error) {
+      if (isNodeError(error) && error.code === "ENOENT") return null;
+      if (!isRetriableAdapterReadError(error) || attempt === ADAPTER_READ_MAX_ATTEMPTS) {
+        throw error;
+      }
+      await delay(ADAPTER_READ_RETRY_DELAY_MS * attempt);
+    }
+  }
+  throw new Error("MANCODE_V3_ADAPTER_READ_RETRY_EXHAUSTED");
 }
 async function readTextIfExists(filePath) {
   for (let attempt = 1; attempt <= ADAPTER_READ_MAX_ATTEMPTS; attempt += 1) {
@@ -1253,9 +1759,9 @@ async function atomicWrite(filePath, content) {
 function targetFor(platform) {
   switch (platform) {
     case "claude-code":
-      return ".claude/skills/mancode-v3/SKILL.md";
+      return "CLAUDE.md";
     case "cursor":
-      return ".cursor/rules/mancode-v3.mdc";
+      return ".cursor/rules/mancode-continuity.mdc";
     case "codex":
     case "zcode":
       return "AGENTS.md";
@@ -1263,6 +1769,47 @@ function targetFor(platform) {
       return ".github/copilot-instructions.md";
   }
 }
+function retiredBootstrapPlatformFor(target) {
+  if (target === "claude-skill") return "claude-code";
+  if (target === "cursor-rule") return "cursor";
+  return null;
+}
+function retiredBootstrapSpecs(root, platform) {
+  const managedMarkers = [
+    LEGACY_V3_ADAPTER_MANAGED_MARKER,
+    V3_ADAPTER_MANAGED_MARKER
+  ];
+  if (platform === "claude-code") {
+    return [
+      {
+        filePath: path.join(
+          root,
+          ".claude",
+          "skills",
+          "mancode-v3",
+          "SKILL.md"
+        ),
+        managedMarkers
+      },
+      {
+        filePath: path.join(
+          root,
+          ".claude",
+          "skills",
+          "mancode-continuity",
+          "SKILL.md"
+        ),
+        managedMarkers
+      }
+    ];
+  }
+  return [
+    {
+      filePath: path.join(root, ".cursor", "rules", "mancode-v3.mdc"),
+      managedMarkers
+    }
+  ];
+}
 function platformLabelFor(platform) {
   switch (platform) {
     case "claude-code":
@@ -1306,9 +1853,14 @@ export {
   V3_ADAPTER_VERSION,
   V3_ADAPTER_MANAGED_MARKER,
   V3_MODE_ENTRY_MANAGED_MARKER,
+  V3_ADAPTER_DIGEST_DOMAIN,
   V3_MODE_NAMES,
+  V3_ADAPTER_PLATFORMS,
   V3_ADAPTER_FILE_TARGETS,
+  adapterManagedContentDigest,
   planV3AdapterFiles,
+  planV3AdapterUpgradeFiles,
+  stageV3AdapterUpgradeFiles,
   applyV3AdapterFilePlan,
   stageV3Adapter,
   v3AdapterTargetPath,
@@ -1318,8 +1870,9 @@ export {
   assertV3AdapterInstallable,
   inspectV3Adapter,
   inspectV3AdapterVersions,
+  v3AdapterVersionsFromStatuses,
   removeV3Adapter,
   renderV3Bootstrap,
   renderV3ModeEntry
 };
-//# sourceMappingURL=chunk-QIOMFU35.js.map
+//# sourceMappingURL=chunk-VV3MFVIG.js.map