@brainervirus/workit-core 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "private": false,
   "description": "Workit — workflow rails for agentic coding: specs, plans, YouTrack, CI-gated commits (shared core)",
   "keywords": [

package/skills/wk-init/SKILL.md

@@ -19,7 +19,7 @@ Never ask for or accept tokens in chat. For missing YouTrack configuration, prev
 
 When the user wants to personalize the toolkit (locale, timezone, branch policy), ask native questions one at a time:
 
-1. **Locale** — present a combobox of `localeOptions` (en, es-CL, es-MX, es-AR, pt-BR) + custom answer; validate the answer against BCP-47 (`^[a-z]{2,3}(-[A-Z]{2})?$`) before passing it.
+1. **Locale** — present a combobox of `localeOptions` (en, es-CL, es-MX, es-AR, pt-BR) + custom answer; validate the answer against BCP-47 (`^[a-z]{2,3}(-(?:[A-Z]{2}|[0-9]{3}))?$`, so `es-419` is valid) before passing it.
 2. **Timezone** — e.g. `America/Santiago`, custom allowed.
 3. **Branch policy preset** — gitflow / github-flow / trunk-based / custom.
 4. **Custom branch lists** (only when preset = custom): allowed patterns (`feature/*`, `codex/*`, …) and protected names (`main`, …).

package/src/core/branch.ts

@@ -35,6 +35,10 @@ const baseBranch = (cwd: string): { base: string } | { error: string } => {
 };
 const DECLARE_RE = /^\s*\*+Branch:\*+\s*`?([^`\s|]+)`?\s*$/gim;
 const USE_CURRENT_RE = /^\s*\*+Branch:\*+\s*use-current\s*$/im;
+// Windows portability: journal lines and stash-coverage sets carry
+// repo-relative paths, which must match git's POSIX separator output even
+// though path.join emits platform separators.
+const toPosix = (p: string) => p.split(path.sep).join("/");
 const readSafe = (p: string): string | null => {
   try {
     return readFileSync(p, "utf8");
@@ -274,14 +278,39 @@ export const ensureBaseBranch = (cwd: string, base: string): { ok: boolean; erro
   return fastForwardBase(cwd, base);
 };
 
-// CA-05: flow-state snapshots live under the OS tempdir scoped by a hash of
-// the workspace path — never inside the repository or docs/.
+// CA-05: crash-orphaned guard roots are garbage-collected at snapshot time.
+// Fresh roots (any live invocation) and non-workit entries are never touched.
+export const purgeStaleFlowGuardRoots = (now: number): void => {
+  const cutoff = now - 24 * 3600_000;
+  let entries: string[];
+  try {
+    entries = readdirSync(tmpdir());
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.startsWith("workit-flow-guard-")) continue;
+    try {
+      if (statSync(path.join(tmpdir(), entry)).mtimeMs < cutoff)
+        rmSync(path.join(tmpdir(), entry), { recursive: true, force: true });
+    } catch {
+      /* raced removal or unreadable entry: skip */
+    }
+  }
+};
+
+// CA-04: flow-state snapshots live under the OS tempdir scoped by a hash of
+// the workspace path — never inside the repository or docs/. The pid+hrtime
+// suffix makes every invocation unique, so two concurrent setups never share
+// (and never clobber) a root; CA-05 GC reclaims anything a crash orphaned.
 export const snapshotFlowState = (cwd: string): string => {
+  purgeStaleFlowGuardRoots(Date.now());
   const root = path.join(
     tmpdir(),
-    `workit-flow-guard-${createHash("sha256").update(path.resolve(cwd)).digest("hex").slice(0, 16)}`,
+    `workit-flow-guard-${createHash("sha256").update(path.resolve(cwd)).digest("hex").slice(0, 16)}.${
+      process.pid
+    }.${process.hrtime.bigint()}`,
   );
-  rmSync(root, { recursive: true, force: true }); // drop a stale guard from a crashed run
   mkdirSync(root, { recursive: true });
   const docsDir = path.join(path.resolve(cwd), "docs");
   let slugs: string[] = [];
@@ -291,15 +320,21 @@ export const snapshotFlowState = (cwd: string): string => {
     return root; // no docs/ yet — zero-file snapshot
   }
   for (const slug of slugs) {
-    const src = path.join(docsDir, slug, "sdd", "flow.json");
-    try {
-      if (!statSync(src).isFile()) continue;
-    } catch {
-      continue;
+    // The approval gate digests docs/<slug>/spec.md and docs/<slug>/plan.md,
+    // so those bytes must survive the stash window too: a stash push -u takes
+    // untracked spec/plan away and any concurrent effective flow read would
+    // classify document_missing drift and persist an approval-chain wipe.
+    for (const rel of [["sdd", "flow.json"], ["spec.md"], ["plan.md"]]) {
+      const src = path.join(docsDir, slug, ...rel);
+      try {
+        if (!statSync(src).isFile()) continue;
+      } catch {
+        continue;
+      }
+      const dest = path.join(root, "docs", slug, ...rel);
+      mkdirSync(path.dirname(dest), { recursive: true });
+      cpSync(src, dest);
     }
-    const dest = path.join(root, "docs", slug, "sdd", "flow.json");
-    mkdirSync(path.dirname(dest), { recursive: true });
-    cpSync(src, dest);
   }
   return root;
 };
@@ -307,14 +342,20 @@ export const snapshotFlowState = (cwd: string): string => {
 // CA-04: restore-if-missing keeps the newest working-tree bytes; the snapshot
 // root is removed only after every file is handled and retained on failure.
 // A caught failure must not vanish: the message is returned so callers can
-// surface it to operators as a warning.
-export const restoreFlowSnapshot = (snapDir: string, cwd: string): string | undefined => {
+// surface it to operators as a warning. `restored` lists ONLY the files this
+// call actually wrote — present-at-restore files are skipped and excluded,
+// which is what makes the redundant-stash coverage check honest.
+export const restoreFlowSnapshot = (
+  snapDir: string,
+  cwd: string,
+): { restored: string[]; warning?: string } => {
   const walk = (dir: string, rel: string): string[] =>
     readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
       entry.isDirectory()
         ? walk(path.join(dir, entry.name), path.join(rel, entry.name))
         : [path.join(rel, entry.name)],
     );
+  const restored: string[] = [];
   try {
     const workspace = path.resolve(cwd);
     for (const rel of walk(snapDir, "")) {
@@ -331,13 +372,17 @@ export const restoreFlowSnapshot = (snapDir: string, cwd: string): string | unde
         rmSync(tmpDest, { force: true });
         throw error;
       }
+      restored.push(toPosix(rel));
     }
     rmSync(snapDir, { recursive: true, force: true });
-    return undefined;
+    return { restored };
   } catch (error) {
-    return `flow state snapshot restore failed: ${
-      error instanceof Error ? error.message : String(error)
-    }`;
+    return {
+      restored,
+      warning: `flow state snapshot restore failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    };
   }
 };
 
@@ -348,12 +393,14 @@ export const branchSetup = ({
   target_branch,
   stash,
   workspace_root,
+  log,
 }: {
   action?: string;
   sdd_dir?: string;
   target_branch?: string;
   stash?: string;
   workspace_root: string;
+  log?: (message: string) => void;
 }) => {
   const cwd = path.resolve(workspace_root);
   const exec = (args: string[]): string =>
@@ -376,9 +423,60 @@ export const branchSetup = ({
     writeFileSync(manifestPath, JSON.stringify(data, null, 2) + "\n", "utf8");
 
   let snapDir: string | null = null;
-  const restoreWithWarning = (dir: string | null): string[] => {
-    const warning = dir ? restoreFlowSnapshot(dir, cwd) : undefined;
-    return warning ? [warning] : [];
+  // CA-01: flow-guard journal brackets the stash/checkout mutation window so a
+  // mid-window wipe is pinpointable between adjacent checkpoint lines. With no
+  // logger injected every call below is a no-op and nothing extra runs —
+  // behaviorally identical to the pre-journal code.
+  const journal = (message: string) => log?.(`flow-guard: ${message}`);
+  const snapshotRelPaths = (): string[] => {
+    const dir = snapDir;
+    // Not gated on log: the redundant-stash coverage check below needs this
+    // walk even without a logger (the walk is read-only over the tmpdir
+    // snapshot).
+    if (!dir) return [];
+    try {
+      const walk = (from: string, rel: string): string[] =>
+        readdirSync(from, { withFileTypes: true }).flatMap((entry) =>
+          entry.isDirectory()
+            ? walk(path.join(from, entry.name), path.join(rel, entry.name))
+            : [path.join(rel, entry.name)],
+        );
+      return walk(dir, "").map(toPosix);
+    } catch {
+      return [];
+    }
+  };
+  const journalSnapshot = () => {
+    const dir = snapDir;
+    if (!dir || !log) return;
+    const rels = snapshotRelPaths();
+    journal(`snapshot: ${rels.length} file(s)`);
+    for (const rel of rels) {
+      let shortHash = "";
+      try {
+        shortHash = createHash("sha256")
+          .update(readFileSync(path.join(dir, rel)))
+          .digest("hex")
+          .slice(0, 8);
+      } catch {}
+      journal(`snapshot: ${rel} sha=${shortHash}`);
+    }
+  };
+  const journalPresence = (phase: string) => {
+    for (const rel of snapshotRelPaths()) {
+      journal(`${phase}: ${rel} ${existsSync(path.join(cwd, rel)) ? "present" : "MISSING"}`);
+    }
+  };
+  const restoreWithWarning = (dir: string | null): { restored: string[]; warnings: string[] } => {
+    if (!dir) return { restored: [], warnings: [] };
+    const total = log ? snapshotRelPaths().length : 0;
+    const { restored, warning } = restoreFlowSnapshot(dir, cwd);
+    if (log)
+      journal(
+        `restore: restored=${restored.length} skipped=${total - restored.length}${warning ? ` warning: ${warning}` : ""}`,
+      );
+    else if (warning) journal(`restore warning: ${warning}`);
+    return { restored, warnings: warning ? [warning] : [] };
   };
 
   if (action === "reapply_stash") {
@@ -387,22 +485,28 @@ export const branchSetup = ({
     if (!ref) return { error: "no stash_ref in manifest" };
     // D-03: guard flow.json across the stash pop window.
     snapDir = snapshotFlowState(cwd);
+    journalSnapshot();
+    journal(`pre-pop: ${String(ref)}`);
     try {
       exec(["stash", "pop", String(ref)]);
     } catch (error) {
       // CA-03: the snapshot ran before the pop — a failing pop must still
       // restore a mid-window-wiped flow.json before returning.
-      const [warning] = restoreWithWarning(snapDir);
+      journal("pop: failed");
+      const {
+        warnings: [warning],
+      } = restoreWithWarning(snapDir);
       return {
         error: `${error instanceof Error ? error.message : "stash pop failed"}${
           warning ? `; ${warning}` : ""
         }`,
       };
     }
+    journal("pop: ok");
     delete manifest.stash_ref;
     delete manifest.stash_created_at;
     writeManifest(manifest);
-    const warnings = restoreWithWarning(snapDir);
+    const { warnings } = restoreWithWarning(snapDir);
     return { action: "reapply_stash", ok: true, ...(warnings.length > 0 ? { warnings } : {}) };
   }
 
@@ -427,6 +531,7 @@ export const branchSetup = ({
     if ("error" in baseResolved) return { error: baseResolved.error };
     base = baseResolved.base;
   }
+  journal(`entry: current=${current} target=${target} base=${base ?? "-"}`);
 
   let stash_ref: string | undefined;
   // Best-effort restore; if the pop itself fails, the caller's error gains a
@@ -434,18 +539,23 @@ export const branchSetup = ({
   const failAfterStash = (message: string): { error: string } => {
     let suffix = "";
     if (stash_ref) {
+      journal(`pre-pop: ${stash_ref}`);
       try {
         exec(["stash", "pop", stash_ref]);
         stash_ref = undefined;
+        journal("pop: ok");
       } catch {
+        journal("pop: failed");
         suffix = " (changes preserved in stash)";
       }
     }
     // CA-03: the snapshot ran before the stash push, so every error return
     // here must still restore a mid-window-wiped flow.json and drop the
-    // guard root (a retained root is destroyed by the next run's
-    // stale-root rmSync). Never masks the original error.
-    const [warning] = restoreWithWarning(snapDir);
+    // guard root (a retained root is purged by the next run's 24h GC).
+    // Never masks the original error.
+    const {
+      warnings: [warning],
+    } = restoreWithWarning(snapDir);
     return { error: `${message}${suffix}${warning ? `; ${warning}` : ""}` };
   };
   if (current !== target) {
@@ -471,14 +581,17 @@ export const branchSetup = ({
         // CA-03: snapshot before the stash push so flow.json survives the
         // stash/checkout window even if the pathspec exclusion misses.
         snapDir = snapshotFlowState(cwd);
+        journalSnapshot();
         exec(["stash", "push", "-u", "-m", `workit: pre-checkout ${target}`, "--", ":!docs/*/sdd"]);
       } catch (error) {
         return { error: error instanceof Error ? error.message : "stash push failed" };
       }
       stash_ref = "stash@{0}";
+      journal(`stash push: ${stash_ref}`);
     }
     try {
       exec(["checkout", target]);
+      journalPresence("post-checkout");
     } catch (error) {
       const message = error instanceof Error ? error.message : "checkout failed";
       if (/worktree/i.test(message)) {
@@ -501,6 +614,7 @@ export const branchSetup = ({
             : ensureBaseBranch(cwd, effectiveBase);
         if (!baseResult.ok) return failAfterStash(baseResult.error ?? "ensure-base-branch failed");
         exec(["checkout", "-b", target]);
+        journalPresence("post-create");
       } catch (createError) {
         return failAfterStash(
           createError instanceof Error ? createError.message : "branch create failed",
@@ -534,7 +648,47 @@ export const branchSetup = ({
     }
     return result;
   }
-  const warnings = restoreWithWarning(snapDir);
+  // Files the guard actually wrote back, straight from the restore itself.
+  const { restored: restoredRels, warnings } = restoreWithWarning(snapDir);
+  // Round-1 fallout: the guard restores untracked spec/plan right after
+  // checkout, but the stash pushed the same files — a later reapply_stash pop
+  // refuses ("untracked working tree files would be overwritten"), stranding
+  // a stash_ref on every successful setup. When every stashed path was just
+  // restored byte-identical from the pre-stash snapshot, the stash is
+  // redundant: drop it and clear the manifest ref. Coverage counts ONLY
+  // actually-restored paths: a tracked-and-modified file survives its stash
+  // (reverted to HEAD bytes, still present), so restore skips it — counting
+  // it as covered would drop the only copy of the user's edit. Any stashed
+  // path not restored keeps the ref so reapply_stash stays available.
+  // Best-effort: any failure keeps today's keep-the-ref behavior.
+  if (stash_ref && snapDir && warnings.length === 0) {
+    const covered = new Set(restoredRels.map(toPosix));
+    try {
+      const stashed = exec([
+        "stash",
+        "show",
+        "--include-untracked",
+        "--name-only",
+        String(stash_ref),
+      ])
+        .split("\n")
+        .map((line) => toPosix(line.trim()))
+        .filter(Boolean);
+      if (stashed.length > 0 && stashed.every((p) => covered.has(p))) {
+        exec(["stash", "drop", String(stash_ref)]);
+        stash_ref = undefined;
+        journal("dropped redundant stash (fully covered by snapshot restore)");
+        const manifest = readManifest();
+        delete manifest.stash_ref;
+        delete manifest.stash_created_at;
+        writeManifest(manifest);
+      } else {
+        journal(`kept stash ref ${stash_ref} (not fully covered by actual restores)`);
+      }
+    } catch {
+      /* keep the stash ref — reapply_stash stays available */
+    }
+  }
   return {
     action: "setup",
     ok: true,

package/src/core/config.ts

@@ -122,7 +122,9 @@ export const ensureConfigDir = (dir: string = resolveConfigDir()): string => {
 
 export const configDir = (): string => ensureConfigDir();
 
-export const LOCALE_RE = /^[a-z]{2,3}(-[A-Z]{2})?$/;
+// Region subtags: 2-letter ISO 3166 alpha-2 or 3-digit UN M.49 (es-419 =
+// Latinoamérica), per BCP-47 well-formedness for the tags this toolkit stores.
+export const LOCALE_RE = /^[a-z]{2,3}(-(?:[A-Z]{2}|[0-9]{3}))?$/;
 
 const DEFAULTS: ToolkitConfig = {
   locale: "en",

package/src/core/uninstall.ts

@@ -0,0 +1,377 @@
+// Uninstall planning + apply (Task 8): the exact inverse of the setup/registration
+// write set. planUninstall is a pure reader — it classifies the installed state
+// and returns the actions apply WOULD perform; applyUninstall dispatches only
+// reviewed plan actions, preserves unrelated user config byte-for-byte
+// (write-only-if-changed), and never touches ~/.config/workit
+// (CA-11, CA-12, CA-13, CA-14). Homes are injectable exactly like setup/doctor
+// path options (D-07): tests pass explicit paths and no default ever resolves
+// to a real user directory in tests.
+import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isWorkitPlugin } from "./registration";
+
+export type UninstallHost = "opencode" | "cursor";
+
+export type UninstallAction =
+  | { kind: "edit-json-remove"; path: string; detail: string }
+  | { kind: "remove-dir"; path: string; detail: string };
+
+export type UninstallHostPlan = {
+  host: UninstallHost;
+  installed: boolean;
+  actions: UninstallAction[];
+};
+
+export type UninstallPlan = {
+  hosts: UninstallHostPlan[];
+};
+
+export type UninstallResultStatus = "removed" | "skipped" | "failed";
+
+export type UninstallResultEntry = {
+  host: UninstallHost;
+  path: string;
+  status: UninstallResultStatus;
+  detail?: string;
+};
+
+export type UninstallResult = {
+  ok: boolean;
+  entries: UninstallResultEntry[];
+};
+
+/** Injectable homes mirroring setup's ApplySetupOptions subset (D-07). */
+export type UninstallPaths = {
+  home?: string;
+  env?: NodeJS.ProcessEnv;
+  opencodeConfig?: string;
+  cursorSettings?: string;
+  cursorMcp?: string;
+  cursorPluginDir?: string;
+};
+
+type ResolvedUninstall = {
+  opencodeConfig: string;
+  cursorSettings: string;
+  cursorMcp: string;
+  cursorPluginDir: string;
+};
+
+const resolveUninstallPaths = (options: UninstallPaths = {}): ResolvedUninstall => {
+  // Same chain as setup.ts (parity advisory): explicit option > env.HOME >
+  // homedir. No process.env tier — an ambient HOME must never leak past an
+  // explicitly empty injected env.
+  const home = options.home ?? options.env?.HOME ?? os.homedir();
+  return {
+    opencodeConfig:
+      options.opencodeConfig ?? path.join(home, ".config", "opencode", "opencode.json"),
+    cursorSettings: options.cursorSettings ?? path.join(home, ".cursor", "settings.json"),
+    cursorMcp: options.cursorMcp ?? path.join(home, ".cursor", "mcp.json"),
+    cursorPluginDir:
+      options.cursorPluginDir ?? path.join(home, ".cursor", "plugins", "local", "workit"),
+  };
+};
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+
+type Existing =
+  | { kind: "missing" }
+  | { kind: "malformed"; error: string }
+  | { kind: "record"; value: Record<string, unknown> };
+
+const readJsonRecord = (file: string): Existing => {
+  let raw: string;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch {
+    // A read-permission error (EACCES) must not look like a missing file (same
+    // disambiguation as setup.ts readExisting): classify it malformed so plan
+    // keeps the host installed and apply reports Failed with the path untouched.
+    if (existsSync(file)) return { kind: "malformed", error: `${file} is not readable` };
+    return { kind: "missing" };
+  }
+  try {
+    const value = JSON.parse(raw);
+    return isRecord(value)
+      ? { kind: "record", value }
+      : { kind: "malformed", error: `${file} is not a JSON object` };
+  } catch {
+    return { kind: "malformed", error: `${file} is not valid JSON` };
+  }
+};
+
+// Mirror of mergeCursorEnabledPlugins' strip(): trailing-separator-insensitive
+// comparison that guards the filesystem root.
+const stripTrailingSep = (p: string): string => {
+  const j = path.join(p);
+  return path.dirname(j) === j ? j : j.replace(/[\\/]+$/, "");
+};
+
+const CURSOR_LEGACY_IDENTITIES = ["workflow-toolkit", "local/workflow-toolkit"];
+
+// Inverse of mergeCursorSettings: drop workit identities from enabled_plugins,
+// drop the canonical plugin dir entry from plugin_dirs. Returns the next record
+// plus whether anything changed (plan/apply share this so outcomes match).
+function cleanCursorSettings(
+  settings: Record<string, unknown>,
+  pluginDir: string,
+): { next: Record<string, unknown>; changed: boolean } {
+  const next = { ...settings };
+  let changed = false;
+  if (isRecord(next.enabled_plugins)) {
+    const enabled = { ...(next.enabled_plugins as Record<string, unknown>) };
+    for (const identity of ["workit", ...CURSOR_LEGACY_IDENTITIES]) {
+      if (identity in enabled) {
+        delete enabled[identity];
+        changed = true;
+      }
+    }
+    next.enabled_plugins = enabled;
+  }
+  if (Array.isArray(next.plugin_dirs)) {
+    const canonical = stripTrailingSep(pluginDir);
+    const kept = (next.plugin_dirs as unknown[])
+      .map(String)
+      .filter((d) => stripTrailingSep(d) !== canonical);
+    if (kept.length !== (next.plugin_dirs as unknown[]).length) {
+      next.plugin_dirs = kept;
+      changed = true;
+    }
+  }
+  return { next, changed };
+}
+
+// Inverse of mergeOpenCodeConfig's plugin registration: remove every workit
+// identity from the plugin list.
+function cleanOpenCodeConfig(config: Record<string, unknown>): {
+  next: Record<string, unknown>;
+  changed: boolean;
+} {
+  const next = { ...config };
+  let changed = false;
+  if (Array.isArray(next.plugin)) {
+    const plugins = (next.plugin as unknown[]).map(String);
+    const kept = plugins.filter((p) => !isWorkitPlugin(p));
+    if (kept.length !== plugins.length) {
+      next.plugin = kept;
+      changed = true;
+    }
+  } else if (typeof next.plugin === "string" && isWorkitPlugin(next.plugin)) {
+    delete next.plugin;
+    changed = true;
+  }
+  return { next, changed };
+}
+
+// Inverse of mergeCursorMcp: drop the canonical server name and its legacy twin.
+function cleanCursorMcp(mcp: Record<string, unknown>): {
+  next: Record<string, unknown>;
+  changed: boolean;
+} {
+  const next = { ...mcp };
+  let changed = false;
+  if (isRecord(next.mcpServers)) {
+    const servers = { ...(next.mcpServers as Record<string, unknown>) };
+    for (const name of ["workit", "workflow-toolkit"]) {
+      if (name in servers) {
+        delete servers[name];
+        changed = true;
+      }
+    }
+    next.mcpServers = servers;
+  }
+  return { next, changed };
+}
+
+// Shared edit-json-remove executor for plan parity: parse → clean by target →
+// report change without writing.
+type JsonCleaner = (record: Record<string, unknown>) => {
+  next: Record<string, unknown>;
+  changed: boolean;
+};
+
+const jsonCleanerFor = (target: string, res: ResolvedUninstall): JsonCleaner | null => {
+  if (target === res.opencodeConfig) return cleanOpenCodeConfig;
+  if (target === res.cursorSettings) return (r) => cleanCursorSettings(r, res.cursorPluginDir);
+  if (target === res.cursorMcp) return cleanCursorMcp;
+  return null;
+};
+
+/** Pure planner: reports the uninstall actions Apply would perform. Reads host
+ *  config files but never writes; ~/.config/workit is never an action target. */
+export function planUninstall(paths: UninstallPaths = {}): UninstallPlan {
+  const res = resolveUninstallPaths(paths);
+
+  const ocExisting = readJsonRecord(res.opencodeConfig);
+  const ocDirty =
+    ocExisting.kind === "malformed" ||
+    (ocExisting.kind === "record" && cleanOpenCodeConfig(ocExisting.value).changed);
+  const opencode: UninstallHostPlan = {
+    host: "opencode",
+    installed: ocDirty,
+    actions: ocDirty
+      ? [
+          {
+            kind: "edit-json-remove",
+            path: res.opencodeConfig,
+            detail: "remove workit plugin entries from opencode.json",
+          },
+        ]
+      : [],
+  };
+
+  const settingsExisting = readJsonRecord(res.cursorSettings);
+  const mcpExisting = readJsonRecord(res.cursorMcp);
+  // A malformed host file is still planned: apply must surface the failure
+  // (file untouched) instead of silently pretending the host is clean.
+  const settingsDirty =
+    settingsExisting.kind === "malformed" ||
+    (settingsExisting.kind === "record" &&
+      cleanCursorSettings(settingsExisting.value, res.cursorPluginDir).changed);
+  const mcpDirty =
+    mcpExisting.kind === "malformed" ||
+    (mcpExisting.kind === "record" && cleanCursorMcp(mcpExisting.value).changed);
+  const dirExists = existsSync(res.cursorPluginDir);
+  const actions: UninstallAction[] = [];
+  if (settingsDirty) {
+    actions.push({
+      kind: "edit-json-remove",
+      path: res.cursorSettings,
+      detail: "remove workit enabled_plugins/plugin_dirs entries from settings.json",
+    });
+  }
+  if (mcpDirty) {
+    actions.push({
+      kind: "edit-json-remove",
+      path: res.cursorMcp,
+      detail: "remove the workit MCP server registration from mcp.json",
+    });
+  }
+  if (dirExists) {
+    actions.push({
+      kind: "remove-dir",
+      path: res.cursorPluginDir,
+      detail: "delete the local workit plugin directory",
+    });
+  }
+  const cursor: UninstallHostPlan = {
+    host: "cursor",
+    installed: settingsDirty || mcpDirty || dirExists,
+    actions,
+  };
+
+  return { hosts: [opencode, cursor] };
+}
+
+// CA-14 traversal guard: rm -rf is permitted ONLY on the exact resolved
+// canonical <home>/.cursor/plugins/local/workit directory. Any other resolved
+// path (symlinked alias, sibling, traversal) fails closed without touching disk.
+// Belt-and-braces (Task 8 advisory): when both sides resolve, their real paths
+// must agree too — an ancestor symlink swapped in between plan and apply cannot
+// widen the rm target. An unresolvable path falls through to the lexical
+// verdict (apply then reports skipped/failed downstream).
+const canonicalRemoveDirAllowed = (actionPath: string, res: ResolvedUninstall): boolean => {
+  const expected = path.resolve(res.cursorPluginDir);
+  if (
+    !(
+      actionPath === expected &&
+      path.basename(expected) === "workit" &&
+      path.basename(path.dirname(expected)) === "local" &&
+      path.basename(path.dirname(path.dirname(expected))) === "plugins"
+    )
+  ) {
+    return false;
+  }
+  try {
+    return realpathSync(actionPath) === realpathSync(expected);
+  } catch {
+    return true;
+  }
+};
+
+const applyEditJsonRemove = (
+  target: string,
+  cleaner: JsonCleaner,
+): { status: UninstallResultStatus; detail?: string } => {
+  const existing = readJsonRecord(target);
+  if (existing.kind === "malformed") {
+    return { status: "failed", detail: `${existing.error} — file untouched` };
+  }
+  if (existing.kind === "missing") {
+    return { status: "skipped", detail: "file already absent" };
+  }
+  const { next, changed } = cleaner(existing.value);
+  // Only-if-changed: byte-preserving when there is nothing to remove.
+  if (!changed) return { status: "skipped", detail: "no workit entries present" };
+  const serialized = JSON.stringify(next, null, 2) + "\n";
+  // The byte-compare re-read races any external writer; a vanished/unreadable
+  // file between the two reads must fail THIS action, not abort the rest.
+  let current: string;
+  try {
+    current = readFileSync(target, "utf8");
+  } catch (error) {
+    return {
+      status: "failed",
+      detail: `read failed before write: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  if (current === serialized) {
+    return { status: "skipped", detail: "already clean" };
+  }
+  try {
+    writeFileSync(target, serialized, "utf8");
+  } catch (error) {
+    return {
+      status: "failed",
+      detail: `write failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  return { status: "removed" };
+};
+
+/** Applies ONLY the reviewed plan actions with the given path options. Each
+ *  planned action yields exactly one result entry; malformed host JSON fails
+ *  its own action untouched while the remaining actions proceed (CA-13). */
+export function applyUninstall(plan: UninstallPlan, paths: UninstallPaths = {}): UninstallResult {
+  const res = resolveUninstallPaths(paths);
+  const entries: UninstallResultEntry[] = [];
+  for (const hostPlan of plan.hosts) {
+    for (const action of hostPlan.actions) {
+      let status: UninstallResultStatus;
+      let detail: string | undefined;
+      if (action.kind === "remove-dir") {
+        // Resolve before comparing so ".."/symlink tricks can never widen the rm.
+        const resolved = path.resolve(action.path);
+        if (!canonicalRemoveDirAllowed(resolved, res)) {
+          status = "failed";
+          detail = `refusing to remove non-canonical plugin directory: ${resolved}`;
+        } else if (!existsSync(resolved)) {
+          status = "skipped";
+          detail = "directory already absent";
+        } else {
+          try {
+            rmSync(resolved, { recursive: true, force: true });
+            status = "removed";
+          } catch (error) {
+            status = "failed";
+            detail = error instanceof Error ? error.message : String(error);
+          }
+        }
+      } else {
+        const cleaner = jsonCleanerFor(action.path, res);
+        if (cleaner === null) {
+          status = "failed";
+          detail = `${action.path} is not a recognized uninstall target for this host`;
+        } else {
+          const outcome = applyEditJsonRemove(action.path, cleaner);
+          status = outcome.status;
+          detail = outcome.detail;
+        }
+      }
+      entries.push({ host: hostPlan.host, path: action.path, status, detail });
+    }
+  }
+  return { ok: entries.every((e) => e.status !== "failed"), entries };
+}