@brainervirus/workit-core 0.7.0 → 0.8.0

package/README.md

@@ -1,167 +1,39 @@
-# Workit
+# @brainervirus/workit-core
 
-Multi-platform Superpowers workflow plugin for **Cursor** and **OpenCode**: verify, PR, changelog, commits, SDD implementation, session handoff, YouTrack, and deterministic UI presentation.
+Shared core for the workit plugins — the single source of workflow logic that the OpenCode, Cursor, and CLI packages adapt to their native surfaces.
 
-| Platform | Path | Version |
-| --- | --- | --- |
-| **OpenCode** | `packages/workit-opencode/src/plugin.ts` | ![npm](https://img.shields.io/npm/v/@brainervirus/workit-opencode) |
-| **Cursor** | `packages/workit-cursor/` (MCP + hooks + rules + skills) | ![npm](https://img.shields.io/npm/v/@brainervirus/workit-cursor) |
-| **Shared core** | `packages/workit-core/` (src, skills, commands, scripts, templates) | ![npm](https://img.shields.io/npm/v/@brainervirus/workit-core) |
-| **CLI** | `packages/workit-cli/` (Ink wizard, bin `workit`) | ![npm](https://img.shields.io/npm/v/@brainervirus/workit-cli) |
+## When you need it directly
 
-Config directory (both platforms): `~/.config/workit/` — legacy `~/.config/workflow-toolkit/` is auto-migrated on first run and kept as a fallback.
+End users do **not** install this package directly — install `@brainervirus/workit-cli` (wizard) or the platform plugin (`@brainervirus/workit-opencode`, `@brainervirus/workit-cursor`). The adapters pull core in as a dependency and ship it with their bundles.
 
-[![npm version](https://img.shields.io/npm/v/@brainervirus/workit-opencode)](https://www.npmjs.com/package/@brainervirus/workit-opencode)
-[![CI](https://img.shields.io/github/actions/workflow/status/BrainerVirus/workit/ci.yml?branch=main&label=CI)](https://github.com/BrainerVirus/workit/actions)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+You consume `@brainervirus/workit-core` directly only when:
 
-## Install
+- Building a new host adapter (e.g. a future `codex/` adapter) that maps a host's native surfaces to the shared `src/core/` logic.
+- Reading the canonical source of workflow behavior: specs/plans, approval flow, commit/PR, changelog, YouTrack, presentation, doctor, and diagnostics.
 
-**Quick start (wizard)** — the interactive wizard picks OpenCode and/or Cursor and configures tokens and project files:
+## Layout and ownership
 
-Requires bun (`curl -fsSL https://bun.sh/install | bash`).
+| Path | Contents |
+| --- | --- |
+| `src/core/` | Shared TS logic (setup, registration, doctor, logger, branch, PR, changelog, YouTrack, presentation, docs, SDD, support matrix). |
+| `src/core.ts` | Package entry; adapters import `@brainervirus/workit-core/src/*`. |
+| `skills/` | 12 OpenCode-native `wk-*` skills. |
+| `commands/` | 12 OpenCode `wk-*` command prompts. |
+| `scripts/` | Shared shell installers/launchers and the release-time workspace-dep rewrite. |
+| `templates/` | Execution and Superpowers contract templates. |
+| `vendor/superpowers/skills/` | 14 vendored Superpowers skills. |
 
-```bash
-npm i @brainervirus/workit-core    # shared core (skills, commands, scripts)
-npm i @brainervirus/workit-opencode # OpenCode plugin (thin over the core)
-npm i @brainervirus/workit-cursor   # Cursor plugin (MCP + hooks + rules)
-npm i @brainervirus/workit-cli      # interactive wizard
-npx @brainervirus/workit-cli init
-```
-
-**Local development** — use the repo path instead; no package cache, disk is the source of truth:
-
-```bash
-bun i
-```
-
-**Manual setup (skip the wizard)** — configure each tool by hand; see [Usage](#usage) for the OpenCode plugin entry and Cursor MCP server.
-
-## Usage
-
-Manual setup for those who skipped the wizard (`npx @brainervirus/workit-cli init`):
-
-**OpenCode** — reference the plugin entry in `opencode.json` / `opencode.jsonc` (`~/.config/opencode/opencode.json`):
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@brainervirus/workit-opencode"]
-}
-```
-
-Local dev variant (absolute path to this repo):
+Adapters map host-native surfaces to `src/core/`; they never re-implement core logic. Keep shared behavior here and host-specific presentation in each adapter.
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["file:///path/to/workit/packages/workit-opencode/src/plugin.ts"]
-}
-```
-
-**Cursor** — the MCP server runs from the package's `cursor/` directory. Add to `.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "workit": {
-      "command": "bun",
-      "args": ["run", "node_modules/@brainervirus/workit-cursor/mcp/server.ts"]
-    }
-  }
-}
-```
+## Exports
 
-Local dev variant: point `WORKFLOW_TOOLKIT_ROOT` at this repo's `packages/workit-core` (the MCP launcher `packages/workit-core/scripts/run-cursor-mcp.sh` resolves it), or run the install script from the repo.
+- Main entry: `./src/core.ts`.
+- Subpath exports: `./src/*.ts` (e.g. `@brainervirus/workit-core/src/core/doctor`), plus `./package.json`.
 
-## Requirements
-
-- **Bun ≥ 1.0** — runtime for the shared `src/core` logic, the OpenCode plugin, and the Cursor MCP server (`bun server.ts`). Install once:
+## Package scripts
 
 ```bash
-curl -fsSL https://bun.sh/install | bash
-```
-
-Then add to your shell profile (or rely on the MCP launcher's `~/.bun/bin/bun` fallback):
-
-```bash
-export PATH="$HOME/.bun/bin:$PATH"
-```
-
-- **Git** — branch resolution, SDD review diffs, and verify gates.
-
-## Repo layout
-
+bun run typecheck   # tsc --noEmit
 ```
-workit/
-├── packages/
-│   ├── workit-core/        # @brainervirus/workit-core — shared core
-│   │   ├── src/            # core TS (src/core, src/tools, src/state)
-│   │   ├── skills/         # OpenCode-native skills (wk-*)
-│   │   ├── commands/       # OpenCode commands (wk-*)
-│   │   ├── scripts/        # shared shell + installers (all logic in src/, TS via bun)
-│   │   ├── templates/      # execution + superpowers contracts
-│   │   └── vendor/         # vendored superpowers skills
-│   ├── workit-opencode/    # @brainervirus/workit-opencode — OpenCode plugin (src/plugin.ts)
-│   ├── workit-cursor/      # @brainervirus/workit-cursor — Cursor plugin (MCP, hooks, rules, skills)
-│   └── workit-cli/         # @brainervirus/workit-cli — Ink setup wizard (bin: workit)
-├── .github/workflows/      # CI + release
-└── test/                   # bun tests (OpenCode plugin)
-```
-
-## CI / local checks
-
-```bash
-bun run check    # bun test + tsc + cursor MCP regressions
-```
-
-GitHub Actions:
-
-- **CI** — on push/PR to `main`: matrix of 3 OS (ubuntu, macos, windows) running `actions/checkout@v7` + `oven-sh/setup-bun@v2`, then `bun install --frozen-lockfile` + `bun run check`
-- **Release** — on push to `main`: [semantic-release](https://github.com/semantic-release/semantic-release) computes the next version from Conventional Commits, publishes the four workspaces to npm in dependency order — `workit-core`, `workit-opencode`, `workit-cursor`, `workit-cli` (with provenance), and creates the git tag + GitHub Release
-
-No manual tags — semantic-release owns the version/tag flow:
-
-```bash
-git push origin main
-```
-
-## Quality gates
-
-- **CI checks** — the per-package check jobs (workit-core/opencode/cursor/cli/shared) are required in branch protection; the PR cannot merge while any is red.
-- **Subagent review** — `wk-implement` runs a two-stage review (spec compliance + code quality) per task with fresh `general` agents.
-
-## Architecture
-
-| Concern | OpenCode | Cursor |
-| --- | --- | --- |
-| Tools | native plugin | MCP server |
-| Session contract | `messages.transform` | `sessionStart` hook |
-| Handoff | spawns OpenCode session | handoff prompt |
-| Shared logic | `scripts/` | `scripts/` via `WORKFLOW_TOOLKIT_ROOT` |
-| Install root | GitHub plugin pin | `~/.local/share/workflow-toolkit` + local plugin copy |
-
-## Future: Codex CLI
-
-Add `codex/` adapter; reuse `scripts/` and `templates/`.
-
-## Workflow docs layout
-
-Features live in `docs/<slug>/`:
-
-- `docs/<slug>/spec.md` and `docs/<slug>/plan.md` are **committed** (they travel with the branch).
-- `docs/<slug>/sdd/` (progress ledger, `flow.json` approval state, briefs, review diffs) is **gitignored** — working state for the current cycle.
-
-Consequences:
-
-- A fresh clone starts every workflow at `draft` — the flow gates (`workflow_spec_approve` / `workflow_plan_approve` / `workflow_plan_menu`) must be re-run after checkout.
-- The SDD state does not travel with the branch; spec/plan do.
-
-## Contributing
-
-Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-## Kudos
 
-- **Superpowers** — the vendored `vendor/superpowers/skills/` (brainstorming, writing-plans, executing-plans, TDD, …) is by [Adam Wiggins](https://github.com/obra), vendored with attribution.
-- **Ponytail mode** — the lazy-engineer skill (ponytail, ponytail-review, ponytail-audit, …) by [Dietrich Gebert](https://github.com/dietrichgebert), active in this project's OpenCode config and installed as a shared skill.
+Core has no build step — the adapters bundle it at build time. See the root [README](../../README.md) for the full development, CI, and versioning notes.

package/package.json

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

package/scripts/install-cursor-plugin.sh

@@ -51,12 +51,11 @@ if [ -d "$SKILLS_DIR" ]; then
   rm -f "$SKILLS_DIR"/wf-* "$SKILLS_DIR"/wk-*
 fi
 
-PLUGIN_DIR="$HOME/.cursor/plugins/local/workflow-toolkit"
+PLUGIN_DIR="$HOME/.cursor/plugins/local/workit"
 REGISTRATION_TS="$ROOT/packages/workit-core/src/core/registration.ts"
 CURSOR_SETTINGS="$HOME/.cursor/settings.json" CURSOR_MCP="$HOME/.cursor/mcp.json" PLUGIN_DIR="$PLUGIN_DIR" REGISTRATION_TS="$REGISTRATION_TS" bun -e '
 import fs from "node:fs";
-import path from "node:path";
-const { mergeCursorSettings, mergeCursorMcp, mergeCursorHooks, cursorMcpServerEntry } =
+const { mergeCursorSettings, mergeCursorMcp, cursorMcpServerEntry } =
   await import(process.env.REGISTRATION_TS!);
 
 // RR-06: collapse current + legacy identities; never replace unrelated settings.
@@ -67,8 +66,8 @@ const settings = fs.existsSync(settingsPath)
 const merged = mergeCursorSettings(settings, process.env.PLUGIN_DIR!);
 fs.writeFileSync(settingsPath, JSON.stringify(merged.config, null, 2) + "\n");
 
-// RR-06: one portable workit MCP registration (node dist when present, bash
-// shim in a dist-less dev checkout); stale "workflow-toolkit" entries removed.
+// RR-06/CA-17: one portable workit MCP registration via the published npx bin;
+// stale "workflow-toolkit" entries removed.
 const server = cursorMcpServerEntry(process.env.PLUGIN_DIR!);
 const mcpPath = process.env.CURSOR_MCP!;
 const mcp = fs.existsSync(mcpPath)
@@ -76,23 +75,6 @@ const mcp = fs.existsSync(mcpPath)
   : { mcpServers: {} };
 const mergedMcp = mergeCursorMcp(mcp, "workit", server);
 fs.writeFileSync(mcpPath, JSON.stringify(mergedMcp.config, null, 2) + "\n");
-
-// Keep the synced plugin manifests consistent with the current checkout state:
-// only in a dist-less dev checkout, point them at the shims so Cursor still
-// launches MCP/hooks (the shipped manifests already reference dist).
-const distMcp = path.join(process.env.PLUGIN_DIR!, "dist", "mcp-server.js");
-const pluginMcp = path.join(process.env.PLUGIN_DIR!, "mcp.json");
-if (!fs.existsSync(distMcp) && fs.existsSync(pluginMcp)) {
-  const inPkg = JSON.parse(fs.readFileSync(pluginMcp, "utf8"));
-  const patched = mergeCursorMcp(inPkg, "workit", server);
-  fs.writeFileSync(pluginMcp, JSON.stringify(patched.config, null, 2) + "\n");
-}
-const pluginHooks = path.join(process.env.PLUGIN_DIR!, "hooks", "hooks-cursor.json");
-if (!fs.existsSync(path.join(process.env.PLUGIN_DIR!, "dist", "cursor-session-start.js")) && fs.existsSync(pluginHooks)) {
-  const inPkg = JSON.parse(fs.readFileSync(pluginHooks, "utf8"));
-  const patched = mergeCursorHooks(inPkg, { command: "./hooks/session-start" });
-  fs.writeFileSync(pluginHooks, JSON.stringify(patched.config, null, 2) + "\n");
-}
 '
 
 # DG-09: verify the just-written Cursor registration with the shared offline doctor.
@@ -101,6 +83,20 @@ if ! bun "$ROOT/packages/workit-core/scripts/doctor-check.ts" cursor; then
   exit 1
 fi
 
+# CA-08/CA-09: migrate the legacy local plugin identity to `workit` only after
+# the canonical registration succeeded; carry the legacy user rules forward first.
+LEGACY_PLUGIN_DIR="${HOME}/.cursor/plugins/local/workflow-toolkit"
+if [ -d "$LEGACY_PLUGIN_DIR" ] && [ "$LEGACY_PLUGIN_DIR" != "$PLUGIN_DIR" ]; then
+  if [ -d "$LEGACY_PLUGIN_DIR/rules" ]; then
+    mkdir -p "$PLUGIN_DIR/rules"
+    for rule in "$LEGACY_PLUGIN_DIR"/rules/*.mdc; do
+      [ -e "$rule" ] || continue
+      [ -e "$PLUGIN_DIR/rules/$(basename "$rule")" ] || cp "$rule" "$PLUGIN_DIR/rules/"
+    done
+  fi
+  rm -rf "$LEGACY_PLUGIN_DIR"
+fi
+
 echo "Cursor plugin installed + auto-sync enabled (sessionStart)."
 echo "Share: $SHARE"
-ls "$HOME/.cursor/plugins/local/workflow-toolkit/skills" | grep '^wk-' || true
+ls "$HOME/.cursor/plugins/local/workit/skills" | grep '^wk-' || true

package/scripts/rewrite-workspace-deps.ts

@@ -24,9 +24,10 @@ for (const pkg of ["workit-opencode", "workit-cursor", "workit-cli"]) {
   }
   writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
 }
+// The root marketplace index carries no release version; only the package
+// plugin manifest is versioned at release time.
 for (const file of [
   resolve(root, "packages/workit-cursor/.cursor-plugin/plugin.json"),
-  resolve(root, "packages/workit-cursor/marketplace.json"),
 ]) {
   const data = JSON.parse(readFileSync(file, "utf8"));
   data.version = core.version;

package/scripts/run-cursor-mcp.sh

@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-# Stable entrypoint for Cursor MCP deeplink / ~/.cursor/mcp.json
-# Prefer the installed plugin copy (has node_modules); fall back to share.
+# Stable entrypoint for Cursor MCP deeplink / ~/.cursor/mcp.json (CA-17).
+# Launch the published package's MCP bin through npx, never a repo-relative
+# dist or share clone; a startup/network failure surfaces via npx's nonzero exit.
 set -euo pipefail
-PLUGIN_MCP="${HOME}/.cursor/plugins/local/workflow-toolkit/mcp/run-server.sh"
-SHARE_MCP="${HOME}/.local/share/workflow-toolkit/packages/workit-cursor/mcp/run-server.sh"
-if [ -x "$PLUGIN_MCP" ]; then
-  exec "$PLUGIN_MCP" "$@"
-fi
-exec "$SHARE_MCP" "$@"
+exec npx -y --package=@brainervirus/workit-cursor@latest workit-cursor-mcp "$@"

package/scripts/sync-runtime.sh

@@ -7,7 +7,7 @@ SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 . "$SCRIPT_DIR/lib/config-dir.sh"
 
 SHARE="${HOME}/.local/share/workflow-toolkit"
-PLUGIN_DIR="${HOME}/.cursor/plugins/local/workflow-toolkit"
+PLUGIN_DIR="${HOME}/.cursor/plugins/local/workit"
 OPENCODE_PLUGINS="${HOME}/.config/opencode/plugins"
 DEV_DEFAULT="${HOME}/Documents/projects/personal/workflow-toolkit"
 DEV="${WORKFLOW_TOOLKIT_DEV:-$DEV_DEFAULT}"
@@ -127,7 +127,20 @@ if [ -d "$CONFIG_RULES_DIR" ]; then
   " >/dev/null 2>&1 || true
 fi
 printf '%s\n' "$SHARE/packages/workit-core" >"$PLUGIN_DIR/.workflow-toolkit-root"
-chmod +x "$PLUGIN_DIR/hooks/session-start" "$PLUGIN_DIR/mcp/run-server.sh" 2>/dev/null || true
+
+# CA-08/CA-09: migrate the legacy local plugin identity to `workit` only after
+# the canonical sync succeeded; carry the legacy user rules forward first.
+LEGACY_DIR="${HOME}/.cursor/plugins/local/workflow-toolkit"
+if [ -d "$LEGACY_DIR" ] && [ "$LEGACY_DIR" != "$PLUGIN_DIR" ]; then
+  if [ -d "$LEGACY_DIR/rules" ]; then
+    mkdir -p "$PLUGIN_DIR/rules"
+    for rule in "$LEGACY_DIR"/rules/*.mdc; do
+      [ -e "$rule" ] || continue
+      [ -e "$PLUGIN_DIR/rules/$(basename "$rule")" ] || cp "$rule" "$PLUGIN_DIR/rules/"
+    done
+  fi
+  rm -rf "$LEGACY_DIR"
+fi
 
 # Remove broken TLA live-loader if present (OpenCode ignored it; /wk-* vanished)
 rm -f "${OPENCODE_PLUGINS}/workflow-toolkit.ts"

package/scripts/validate-cursor-marketplace.ts

@@ -0,0 +1,217 @@
+#!/usr/bin/env bun
+// Cursor Marketplace validator (Task 9, CA-13/CA-15/CA-17/CA-21): validates the
+// tracked Marketplace artifact against the official Cursor JSON schemas plus the
+// repository-specific invariants that a JSON Schema cannot express. Runs from a
+// clean `git ls-files` checkout — it never reads dist/ or other ignored build
+// output, so `bun run validate:cursor-marketplace` is a truthful clean-checkout
+// gate for CI.
+//
+// Official schema snapshots (test/fixtures/cursor-schemas/) are verbatim copies
+// of the current official schemas, retrieved 2026-08-13 from:
+//   - https://raw.githubusercontent.com/cursor/plugins/main/schemas/plugin.schema.json
+//   - https://raw.githubusercontent.com/cursor/plugins/main/schemas/marketplace.schema.json
+//
+// `source` path resolution (Task 7 carry-forward, RESOLVED): the official
+// marketplace.schema.json documents `plugins[].source` as "Path to the plugin
+// directory (relative to the marketplace root)". The marketplace root is the
+// directory that CONTAINS `.cursor-plugin/marketplace.json` — the repo root —
+// NOT `.cursor-plugin/` itself. Evidence: the official cursor/plugins repo keeps
+// `.cursor-plugin/marketplace.json` at the repo root and lists sources such as
+// `continual-learning` and `third_party/gmail` with no `../` prefix, even though
+// `.cursor-plugin/` is a sibling of those directories. Therefore
+// `source: "packages/workit-cursor"` is correct and kept verbatim.
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { CANONICAL_SKILLS, validateSkillManifests } from "../src/core/skill-manifests";
+import { copySanitizedVendor } from "./vendor-assets";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, "..", "..", "..");
+const root = process.argv[2] ? path.resolve(process.argv[2]) : repoRoot;
+
+const MARKETPLACE_REL = ".cursor-plugin/marketplace.json";
+
+const frontmatterKeys = (file: string): Set<string> => {
+  const head = readFileSync(file, "utf8").slice(0, 4096);
+  const keys = new Set<string>();
+  if (!head.startsWith("---")) return keys;
+  const end = head.indexOf("\n---", 3);
+  if (end === -1) return keys;
+  for (const line of head.slice(3, end).split("\n")) {
+    const m = /^([A-Za-z0-9_-]+):/.exec(line);
+    if (m) keys.add(m[1]);
+  }
+  return keys;
+};
+
+const treesEqual = (a: string, b: string): string[] => {
+  const diffs: string[] = [];
+  // Thread the tree root so each file is keyed by its ROOT-relative path —
+  // otherwise every `SKILL.md` collapses to one map entry and only the
+  // last-read (readdir-order-dependent) skill is actually compared.
+  const walk = (rootDir: string, dir: string, into: Map<string, string>): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(rootDir, p, into);
+      else into.set(path.relative(rootDir, p).split(path.sep).join("/"), readFileSync(p, "utf8"));
+    }
+  };
+  const left = new Map<string, string>();
+  const right = new Map<string, string>();
+  walk(a, a, left);
+  walk(b, b, right);
+  for (const [rel, content] of left) {
+    if (!right.has(rel)) diffs.push(`missing in rebuilt: ${rel}`);
+    else if (right.get(rel) !== content) diffs.push(`content drift: ${rel}`);
+  }
+  for (const rel of right.keys()) if (!left.has(rel)) diffs.push(`extra in rebuilt: ${rel}`);
+  return diffs;
+};
+
+export const validateMarketplace = (rootArg: string): string[] => {
+  const errors: string[] = [];
+
+  if (!existsSync(path.join(rootArg, MARKETPLACE_REL))) {
+    errors.push(`missing ${MARKETPLACE_REL}`);
+    return errors;
+  }
+
+  // 1. Official JSON Schema evaluation (AJV + ajv-formats), verbatim snapshots.
+  const validate = new Ajv({ strict: true, allErrors: true });
+  addFormats(validate);
+  const schemaDir = path.join(rootArg, "test/fixtures/cursor-schemas");
+  const pluginSchema = JSON.parse(
+    readFileSync(path.join(schemaDir, "plugin.schema.json"), "utf8"),
+  );
+  const marketSchema = JSON.parse(
+    readFileSync(path.join(schemaDir, "marketplace.schema.json"), "utf8"),
+  );
+  const market = JSON.parse(readFileSync(path.join(rootArg, MARKETPLACE_REL), "utf8"));
+  if (!validate.validate(marketSchema, market)) {
+    errors.push(
+      `marketplace.json invalid: ${(validate.errors ?? []).map((e) => e.message).join("; ")}`,
+    );
+  }
+
+  // 2. Resolve each plugin source relative to the repo root; name must match.
+  for (const entry of (market.plugins ?? []) as { name: string; source: string }[]) {
+    const pluginDir = path.join(rootArg, entry.source);
+    const manifestRel = path.join(entry.source, ".cursor-plugin/plugin.json");
+    if (!existsSync(path.join(pluginDir, ".cursor-plugin/plugin.json"))) {
+      errors.push(`plugin ${entry.name}: source ${entry.source} has no .cursor-plugin/plugin.json`);
+      continue;
+    }
+    const plugin = JSON.parse(readFileSync(path.join(pluginDir, ".cursor-plugin/plugin.json"), "utf8"));
+    if (!validate.validate(pluginSchema, plugin)) {
+      errors.push(
+        `plugin ${entry.name} plugin.json invalid: ${(validate.errors ?? []).map((e) => e.message).join("; ")}`,
+      );
+    }
+    if (plugin.name !== entry.name) {
+      errors.push(`plugin ${entry.name}: plugin.json name ${plugin.name} does not match index`);
+    }
+
+    // 3. Component paths resolve inside the plugin root (no `..`, no absolute).
+    // `skills`/`rules` are path-like (string or string[]). `mcpServers`/`hooks`
+    // may also be inline objects or arrays of objects, which the JSON-schema
+    // check already validates — only string/string[] values get the
+    // path-escape/existence check; non-string forms are skipped gracefully.
+    for (const field of ["skills", "rules", "mcpServers", "hooks"] as const) {
+      const value = plugin[field];
+      const rels: string[] =
+        typeof value === "string"
+          ? [value]
+          : Array.isArray(value)
+            ? value.filter((v): v is string => typeof v === "string")
+            : [];
+      for (const rel of rels) {
+        if (rel.includes("..") || rel.startsWith("/")) {
+          errors.push(`plugin ${entry.name}: ${field} path escapes root: ${rel}`);
+          continue;
+        }
+        if (!existsSync(path.join(pluginDir, rel))) {
+          errors.push(`plugin ${entry.name}: ${field} path missing: ${rel}`);
+        }
+      }
+    }
+
+    // 4. Logo resolves inside the plugin root and exists.
+    const logo = plugin.logo as string | undefined;
+    if (logo && (logo.includes("..") || logo.startsWith("/"))) {
+      errors.push(`plugin ${entry.name}: logo path escapes root: ${logo}`);
+    } else if (logo && !existsSync(path.join(pluginDir, logo))) {
+      errors.push(`plugin ${entry.name}: logo missing: ${logo}`);
+    }
+
+    // 5. Skills and rules carry valid frontmatter.
+    const skillRoots: [string, readonly string[]][] = [
+      [path.join(pluginDir, "skills"), CANONICAL_SKILLS.workit],
+      [path.join(pluginDir, "vendor/superpowers/skills"), CANONICAL_SKILLS.superpowers],
+    ];
+    for (const [dir, expected] of skillRoots) {
+      const mismatch = validateSkillManifests(dir, expected, "skills");
+      if (mismatch) errors.push(`plugin ${entry.name}: ${mismatch}`);
+      for (const skill of expected) {
+        const keys = frontmatterKeys(path.join(dir, skill, "SKILL.md"));
+        if (!keys.has("name")) errors.push(`plugin ${entry.name}: ${skill}/SKILL.md missing frontmatter name`);
+        if (!keys.has("description")) errors.push(`plugin ${entry.name}: ${skill}/SKILL.md missing frontmatter description`);
+      }
+    }
+    const rulesDir = path.join(pluginDir, "rules");
+    if (existsSync(rulesDir)) {
+      for (const rule of readdirSync(rulesDir).filter((f) => f.endsWith(".mdc"))) {
+        const keys = frontmatterKeys(path.join(rulesDir, rule));
+        if (!keys.has("description")) errors.push(`plugin ${entry.name}: ${rule} missing frontmatter description`);
+      }
+    }
+
+    // 6. No active runtime path targets an ignored dist file.
+    for (const rel of ["mcp.json", "hooks/hooks-cursor.json"]) {
+      const p = path.join(pluginDir, rel);
+      if (!existsSync(p)) continue;
+      const raw = readFileSync(p, "utf8");
+      if (raw.includes("dist/") || raw.includes("run-server") || raw.includes("session-start.js")) {
+        errors.push(`plugin ${entry.name}: ${rel} references ignored runtime output`);
+      }
+    }
+
+    // 7. Rebuilding the sanitized vendor tree yields no diff.
+    const sourceVendor = path.join(rootArg, "packages/workit-core/vendor/superpowers/skills");
+    const trackedVendor = path.join(pluginDir, "vendor/superpowers/skills");
+    if (existsSync(sourceVendor) && existsSync(trackedVendor)) {
+      const rebuilt = mkdtempSync(path.join(os.tmpdir(), "wk-vendor-rebuild-"));
+      try {
+        copySanitizedVendor(sourceVendor, rebuilt);
+        for (const diff of treesEqual(rebuilt, trackedVendor)) {
+          errors.push(`plugin ${entry.name}: vendor drift: ${diff}`);
+        }
+      } finally {
+        rmSync(rebuilt, { recursive: true, force: true });
+      }
+    } else {
+      errors.push(`plugin ${entry.name}: missing vendor source or tracked tree`);
+    }
+  }
+
+  return errors;
+};
+
+if (import.meta.main) {
+  const errors = validateMarketplace(root);
+  if (errors.length > 0) {
+    for (const e of errors) process.stderr.write(`${e}\n`);
+    process.stderr.write(`marketplace validation FAILED (${errors.length} error${errors.length === 1 ? "" : "s"})\n`);
+    process.exit(1);
+  }
+  console.log(`marketplace validation passed (root: ${root})`);
+}

package/src/core/doctor.ts

@@ -125,7 +125,7 @@ const resolve = (options: DoctorOptions): Resolved => {
     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", "workflow-toolkit"),
+      options.cursorPluginDir ?? path.join(home, ".cursor", "plugins", "local", "workit"),
     env,
     installer: options.installer ?? false,
   };
@@ -323,7 +323,6 @@ const assetPathsFor = (host: DoctorHost, dev: string): string[] => {
       return [
         path.join(pkg, "assets", "templates", "spec-template.md"),
         path.join(pkg, "mcp.json"),
-        path.join(pkg, "marketplace.json"),
         path.join(pkg, ".cursor-plugin"),
       ];
     case "cli":
@@ -377,12 +376,10 @@ const launcherSlotsFor = (host: DoctorHost, dev: string): string[][] => {
     case "opencode":
       return [[path.join(pkg, "src", "plugin.ts"), path.join(pkg, "dist", "plugin.js")]];
     case "cursor":
+      // The dist entries are the npm bin targets the npx launcher executes.
       return [
-        [path.join(pkg, "dist", "mcp-server.js"), path.join(pkg, "mcp", "run-server.sh")],
-        [
-          path.join(pkg, "dist", "cursor-session-start.js"),
-          path.join(pkg, "hooks", "session-start"),
-        ],
+        [path.join(pkg, "dist", "mcp-server.js")],
+        [path.join(pkg, "dist", "cursor-session-start.js")],
       ];
     case "cli":
       return [[path.join(pkg, "src", "index.tsx"), path.join(pkg, "dist", "index.js")]];
@@ -405,9 +402,9 @@ const validNodeEntry = (entry: string, runtime: string, env: NodeJS.ProcessEnv):
   }
 };
 
-const registeredCursorLauncher = (
-  res: Resolved,
-): { runtime: string; entry: string } | null | "invalid" => {
+type CursorLauncher = { kind: "node"; runtime: string; entry: string } | { kind: "npx" };
+
+const registeredCursorLauncher = (res: Resolved): CursorLauncher | null | "invalid" => {
   if (!existsSync(res.cursorMcp)) return "invalid";
   const config = readJson(res.cursorMcp);
   if (!config) return null; // malformed_config owns malformed JSON/object reporting
@@ -419,8 +416,19 @@ const registeredCursorLauncher = (
     return "invalid";
   }
   const executable = path.basename(command).toLowerCase();
+  // CA-17: the canonical launcher runs the published package through npx; the
+  // offline doctor validates its shape (never the registry reachability).
+  if (executable === "npx" || executable === "npx.exe" || executable === "npx.cmd") {
+    // CA-17: exact positional tokens — a substring match would accept
+    // `@latest-alpha` or `workit-cursor-mcp-foo`.
+    if (args[0] !== "-y") return "invalid";
+    if (args[1] !== "--package=@brainervirus/workit-cursor@latest") return "invalid";
+    if (args[2] !== "workit-cursor-mcp") return "invalid";
+    return { kind: "npx" };
+  }
   if (executable !== "node" && executable !== "node.exe") return "invalid";
   return {
+    kind: "node",
     runtime: command,
     entry: path.isAbsolute(args[0]) ? args[0] : path.resolve(path.dirname(res.cursorMcp), args[0]),
   };
@@ -430,7 +438,10 @@ const checkLauncher = (res: Resolved): DoctorCheck => {
   const dev = res.dev;
   const hosts = hostsFor(res.host);
   const registered = hosts.includes("cursor") ? registeredCursorLauncher(res) : null;
-  const runtime = registered && registered !== "invalid" ? registered.runtime : "node";
+  const runtime =
+    registered && registered !== "invalid" && registered.kind === "node"
+      ? registered.runtime
+      : "node";
   const missing = hosts.includes("cursor")
     ? ["dist/mcp-server.js", "dist/cursor-session-start.js"]
         .map((rel) => path.join(res.cursorPluginDir, rel))
@@ -440,7 +451,11 @@ const checkLauncher = (res: Resolved): DoctorCheck => {
   if (hosts.includes("cursor")) {
     if (registered === "invalid") {
       missing.push(`cursor: canonical workit MCP launcher in ${res.cursorMcp}`);
-    } else if (registered && !validNodeEntry(registered.entry, registered.runtime, res.env)) {
+    } else if (
+      registered &&
+      registered.kind === "node" &&
+      !validNodeEntry(registered.entry, registered.runtime, res.env)
+    ) {
       missing.push(`cursor: registered ${registered.entry}`);
     }
   }
@@ -569,9 +584,15 @@ const checkDuplicateRegistration = (res: Resolved): DoctorCheck => {
         );
     }
     const dirs = Array.isArray(settings?.plugin_dirs)
-      ? settings.plugin_dirs
-          .map(String)
-          .filter((d) => isWorkitPlugin(d) || d.includes("workflow-toolkit"))
+      ? settings.plugin_dirs.map(String).filter((d) => {
+          // Exact local plugin-dir identities only (CA-09): a similarly-named
+          // unrelated dir (e.g. `local/workflow-toolkit-extra`) is preserved
+          // and must never be counted as a Workit entry.
+          const n = d.replaceAll("\\", "/").replace(/\/+$/, "");
+          return (
+            isWorkitPlugin(d) || n.endsWith("local/workit") || n.endsWith("local/workflow-toolkit")
+          );
+        })
       : [];
     if (dirs.length > 1) problems.push(`cursor plugin_dirs has ${dirs.length} workit entries`);
   }

package/src/core/registration.ts

@@ -4,7 +4,6 @@
 // never rewritten — their values round-trip JSON-identical. The install
 // scripts (`packages/workit-core/scripts/install-*-plugin.sh`) import these so
 // there is exactly one source of truth for registration merging.
-import { existsSync } from "node:fs";
 import path from "node:path";
 
 export interface MergeResult<T> {
@@ -37,6 +36,8 @@ export function isWorkitPlugin(value: unknown): boolean {
     named(s, "workflow-toolkit") ||
     named(s, "workflow-toolkit-opencode") ||
     named(s, "local/workflow-toolkit") ||
+    named(s, "workit") ||
+    named(s, "local/workit") ||
     named(s, "@brainervirus/workit-opencode") ||
     named(s, "@brainervirus/workit-cursor") ||
     (url && pkgPath) ||
@@ -84,16 +85,17 @@ export function mergeOpenCodeConfig(
   return { config: base, changed };
 }
 
-/** Collapse current + legacy Cursor plugin identities to a single one. */
+/** Collapse current + legacy Cursor plugin identities to the canonical `workit`. */
 export function mergeCursorEnabledPlugins(enabled: unknown): MergeResult<Record<string, boolean>> {
   const prev = isRecord(enabled) ? { ...(enabled as Record<string, boolean>) } : {};
-  const next: Record<string, boolean> = { ...prev, "workflow-toolkit": true };
+  const next: Record<string, boolean> = { ...prev, workit: true };
+  delete next["workflow-toolkit"]; // legacy identity
   delete next["local/workflow-toolkit"]; // legacy duplicate identity
   const changed = JSON.stringify(next) !== JSON.stringify(prev) ? ["enabled_plugins"] : [];
   return { config: next, changed };
 }
 
-/** Append the plugin dir once, preserving any existing plugin directories. */
+/** Append the plugin dir once, dropping the exact legacy sibling directory. */
 export function mergeCursorPluginDirs(
   pluginDirs: unknown,
   pluginDir: string,
@@ -105,13 +107,17 @@ export function mergeCursorPluginDirs(
     return path.dirname(j) === j ? j : j.replace(/[\\/]+$/, "");
   };
   const normalized = strip(pluginDir);
+  // CA-08: the legacy local plugin dir is the exact sibling of the canonical
+  // dir; remove only that entry, never a similarly-named unrelated dir (D3).
+  const legacy = strip(path.join(path.dirname(pluginDir), "workflow-toolkit"));
   const prev = Array.isArray(pluginDirs) ? pluginDirs.map(String) : [];
+  const kept = prev.filter((d) => strip(d) !== legacy);
   // Normalize both sides for comparison so a trailing-slash variant of an
   // existing entry is not appended as a duplicate; existing entries are kept
   // verbatim.
-  const exists = prev.some((d) => strip(d) === normalized);
-  const next = exists ? prev : [...prev, normalized];
-  const changed = next.length !== prev.length ? ["plugin_dirs"] : [];
+  const exists = kept.some((d) => strip(d) === normalized);
+  const next = exists ? kept : [...kept, normalized];
+  const changed = JSON.stringify(next) !== JSON.stringify(prev) ? ["plugin_dirs"] : [];
   return { config: next, changed };
 }
 
@@ -174,42 +180,35 @@ export function mergeCursorHooks(
 }
 
 /**
- * Portable Cursor MCP server entry for an installed plugin dir: prefer the
- * self-contained node dist bundle (PT-10); fall back to the bash shim for a
- * dist-less dev checkout.
+ * Portable Cursor MCP server entry (CA-16/CA-17): launch the published package
+ * through npx against its npm bin, so the Marketplace plugin never depends on a
+ * repo-relative or untracked dist file.
  */
-export function cursorMcpServerEntry(packageDir: string): {
+export function cursorMcpServerEntry(_packageDir: string): {
   command: string;
   args: string[];
 } {
-  if (existsSync(path.join(packageDir, "dist", "mcp-server.js"))) {
-    return {
-      command: "node",
-      args: [path.join(packageDir, "dist", "mcp-server.js"), "${workspaceFolder}"],
-    };
-  }
   return {
-    command: "bash",
-    args: [path.join(packageDir, "mcp", "run-server.sh"), "${workspaceFolder}"],
+    command: "npx",
+    args: [
+      "-y",
+      "--package=@brainervirus/workit-cursor@latest",
+      "workit-cursor-mcp",
+      "${workspaceFolder}",
+    ],
   };
 }
 
 /**
- * Portable Cursor sessionStart hook entry: prefer the self-contained node dist
- * bundle; fall back to the bash shim for a dist-less dev checkout (AR-06).
+ * Portable Cursor sessionStart hook entry (CA-17): a single command string in
+ * Cursor's documented format (no args array).
  */
-export function cursorHooksEntry(packageDir: string): {
+export function cursorHooksEntry(_packageDir: string): {
   command: string;
   args: string[];
 } {
-  if (existsSync(path.join(packageDir, "dist", "cursor-session-start.js"))) {
-    return {
-      command: "node",
-      args: [path.join(packageDir, "dist", "cursor-session-start.js")],
-    };
-  }
   return {
-    command: "bash",
-    args: [path.join(packageDir, "hooks", "session-start")],
+    command: "npx -y --package=@brainervirus/workit-cursor@latest workit-cursor-session-start",
+    args: [],
   };
 }

package/src/core/setup.ts

@@ -1,5 +1,5 @@
 import {
-  chmodSync,
+  copyFileSync,
   cpSync,
   existsSync,
   mkdirSync,
@@ -505,7 +505,7 @@ const resolveSetupPaths = (
     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", "workflow-toolkit"),
+      options.cursorPluginDir ?? path.join(home, ".cursor", "plugins", "local", "workit"),
   };
 };
 
@@ -804,22 +804,14 @@ function applyOpenCode(root: string, res: ResolvedApply): SetupResultEntry {
       };
 }
 
-// Mirror the sync-runtime plugin mirror: copy the package (minus node_modules),
-// keep launchers executable, and write the same `.workflow-toolkit-root` marker
-// so a re-sync from the same source is a truthful Skipped.
-//
-// The installed plugin's mcp.json is a derived artifact: the shipped manifest
-// stays package-relative (PT-10), but Cursor spawns plugin MCP servers with
-// the workspace as cwd, so the installed copy must carry an absolute entry.
-const cursorMcpManifest = (dir: string): string =>
-  JSON.stringify({ mcpServers: { workit: cursorMcpServerEntry(dir) } }, null, 2) + "\n";
-
+// Mirror the sync-runtime plugin mirror: copy the package (minus node_modules)
+// and write the same `.workflow-toolkit-root` marker so a re-sync from the same
+// source is a truthful Skipped. The shipped mcp.json is the Marketplace-safe
+// npx command (CA-17), so it is copied verbatim — no absolute dist derivation.
 const samePluginContent = (src: string, dest: string, relative = ""): boolean => {
   try {
     for (const entry of readdirSync(src, { withFileTypes: true })) {
       if (entry.name === "node_modules") continue;
-      // mcp.json is derived at install time (cursorMcpManifest), not copied.
-      if (relative === "" && entry.name === "mcp.json") continue;
       const source = path.join(src, entry.name);
       const installed = path.join(dest, entry.name);
       if (entry.isDirectory()) {
@@ -837,7 +829,6 @@ const samePluginContent = (src: string, dest: string, relative = ""): boolean =>
       const rel = path.join(relative, entry.name);
       if (rel === ".workflow-toolkit-root") continue;
       if (relative === "rules" && entry.isFile() && entry.name.endsWith(".mdc")) continue;
-      if (relative === "" && entry.name === "mcp.json") continue;
       return false;
     }
     return true;
@@ -864,12 +855,7 @@ const preservedCursorRules = (src: string, dest: string): Map<string, Buffer> =>
 
 function copyPluginDir(src: string, dest: string): SetupResultStatus {
   const marker = path.join(dest, ".workflow-toolkit-root");
-  const synced =
-    readFileSafe(marker)?.trim() === src &&
-    samePluginContent(src, dest) &&
-    // The mcp.json equality makes the Skipped verdict truthful: the derived
-    // manifest on disk must be the one this install would write.
-    readFileSafe(path.join(dest, "mcp.json")) === cursorMcpManifest(dest);
+  const synced = readFileSafe(marker)?.trim() === src && samePluginContent(src, dest);
   if (synced) return "Skipped";
   const hadDir = existsSync(dest);
   const rules = preservedCursorRules(src, dest);
@@ -888,13 +874,6 @@ function copyPluginDir(src: string, dest: string): SetupResultStatus {
       writeFileSync(path.join(stage, "rules", name), content);
     }
     writeFileSync(path.join(stage, ".workflow-toolkit-root"), src + "\n", "utf8");
-    for (const rel of ["hooks/session-start", "mcp/run-server.sh"]) {
-      try {
-        chmodSync(path.join(stage, rel), 0o755);
-      } catch {
-        /* optional launcher */
-      }
-    }
     if (!samePluginContent(src, stage)) throw new Error("staged adapter content is incomplete");
     if (hadDir) renameSync(dest, backup);
     try {
@@ -903,10 +882,6 @@ function copyPluginDir(src: string, dest: string): SetupResultStatus {
       if (hadDir && !existsSync(dest)) renameSync(backup, dest);
       throw error;
     }
-    // Derive the installed manifest against the FINAL installed path: the
-    // stage path dies with the swap dir, and the entry's dist check needs the
-    // live plugin dir to exist.
-    writeFileSync(path.join(dest, "mcp.json"), cursorMcpManifest(dest), "utf8");
     rmSync(backup, { recursive: true, force: true });
   } finally {
     rmSync(swap, { recursive: true, force: true });
@@ -914,6 +889,30 @@ function copyPluginDir(src: string, dest: string): SetupResultStatus {
   return hadDir ? "Configured" : "Installed";
 }
 
+// CA-08/CA-09: remove the exact legacy local plugin identity only AFTER the
+// canonical `workit` copy and registration succeeded. The legacy dir's own
+// user-compiled rules are carried forward first so no user data is lost; the
+// `.workflow-toolkit-root` marker, share path, and unrelated sibling dirs are
+// left untouched.
+const removeLegacyCursorDir = (res: ResolvedApply): void => {
+  const legacy = path.join(res.home, ".cursor", "plugins", "local", "workflow-toolkit");
+  if (legacy === res.cursorPluginDir || !existsSync(legacy)) return;
+  const legacyRules = path.join(legacy, "rules");
+  if (existsSync(legacyRules)) {
+    try {
+      mkdirSync(path.join(res.cursorPluginDir, "rules"), { recursive: true });
+      for (const entry of readdirSync(legacyRules, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".mdc")) continue;
+        const target = path.join(res.cursorPluginDir, "rules", entry.name);
+        if (!existsSync(target)) copyFileSync(path.join(legacyRules, entry.name), target);
+      }
+    } catch {
+      /* best-effort rule carry-forward */
+    }
+  }
+  rmSync(legacy, { recursive: true, force: true });
+};
+
 // One reviewed mutation per Cursor write target (AR-09): the settings merge and
 // the mcp merge are dispatched independently, exactly like the adapter copy.
 function applyCursorSettings(root: string, res: ResolvedApply): SetupResultEntry {
@@ -1042,6 +1041,10 @@ export function applySetupPreview(
   // path (a caller that resolved the preview with different options) fails
   // fast — Failed, no write — instead of silently writing an unreviewed path.
   const rootFor = new Map<Platform, string | null>();
+  // CA-09: cursor registration and legacy cleanup only proceed after the
+  // canonical copy succeeded — a failed replacement must never remove the
+  // legacy identity or its registration.
+  let cursorCopyOk = false;
   for (const mutation of preview.mutations) {
     if (mutation.type !== "register-platform" && mutation.type !== "install-adapter") {
       entries.push(applyMutation(mutation));
@@ -1081,7 +1084,9 @@ export function applySetupPreview(
     }
     if (mutation.type === "install-adapter") {
       try {
-        entries.push({ platform, file: mutation.path, status: copyPluginDir(root, mutation.path) });
+        const status = copyPluginDir(root, mutation.path);
+        cursorCopyOk = true;
+        entries.push({ platform, file: mutation.path, status });
       } catch (error) {
         entries.push({
           platform,
@@ -1092,6 +1097,9 @@ export function applySetupPreview(
       }
     } else if (platform === "opencode") {
       entries.push(applyOpenCode(root, res));
+    } else if (!cursorCopyOk) {
+      // CA-09: the canonical copy failed — leave the legacy registration intact.
+      continue;
     } else {
       entries.push(
         mutation.path === res.cursorSettings
@@ -1100,6 +1108,15 @@ export function applySetupPreview(
       );
     }
   }
+  // CA-08/CA-09: migrate the legacy local identity only after the canonical
+  // copy AND registration both succeeded.
+  if (
+    preview.platforms.includes("cursor") &&
+    cursorCopyOk &&
+    !entries.some((e) => e.platform === "cursor" && e.status === "Failed")
+  ) {
+    removeLegacyCursorDir(res);
+  }
   for (const preserved of preview.preserved) {
     entries.push({
       platform: "core",

package/src/core/support-matrix.ts

@@ -6,7 +6,7 @@
 // host that has no executable artifact/test evidence.
 export const SUPPORT_MATRIX = {
   bun: "1.3.14",
-  node: { minimum: "20", current: "22" },
+  node: { minimum: "22", current: "22" },
   opencode: { minimum: "1.15.0", current: "1.17.7" },
   os: ["ubuntu-latest", "macos-latest", "windows-latest"],
 } as const;

package/src/core/sync-runtime.ts

@@ -2,6 +2,7 @@ import { spawn, spawnSync, type ChildProcess } from "node:child_process";
 import {
   accessSync,
   constants,
+  copyFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -107,7 +108,7 @@ export async function syncRuntime(options: SyncRuntimeOptions = {}): Promise<Syn
     path.join(home, "Documents/projects/personal/workflow-toolkit");
   const repoSlug = options.repoSlug ?? env.WORKFLOW_TOOLKIT_REPO ?? "BrainerVirus/workit";
   const share = path.join(home, ".local/share/workflow-toolkit");
-  const pluginDir = path.join(home, ".cursor/plugins/local/workflow-toolkit");
+  const pluginDir = path.join(home, ".cursor/plugins/local/workit");
   const opencodePlugins = path.join(home, ".config/opencode/plugins");
   const lock = path.join(
     options.lockDir ?? env.XDG_RUNTIME_DIR ?? "/tmp",
@@ -275,6 +276,23 @@ export async function syncRuntime(options: SyncRuntimeOptions = {}): Promise<Syn
       `${share}/packages/workit-core\n`,
     );
 
+    // CA-08/CA-09: migrate the legacy local plugin identity to `workit` only
+    // after the canonical sync succeeded; carry the legacy user rules forward
+    // first so no user data is lost.
+    const legacyDir = path.join(home, ".cursor", "plugins", "local", "workflow-toolkit");
+    if (legacyDir !== pluginDir && existsSync(legacyDir)) {
+      const legacyRules = path.join(legacyDir, "rules");
+      if (existsSync(legacyRules)) {
+        mkdirSync(path.join(pluginDir, "rules"), { recursive: true });
+        for (const entry of readdirSync(legacyRules, { withFileTypes: true })) {
+          if (!entry.isFile() || !entry.name.endsWith(".mdc")) continue;
+          const target = path.join(pluginDir, "rules", entry.name);
+          if (!existsSync(target)) copyFileSync(path.join(legacyRules, entry.name), target);
+        }
+      }
+      rmSync(legacyDir, { recursive: true, force: true });
+    }
+
     // Remove broken TLA live-loader if present (OpenCode ignored it; /wk-* vanished).
     rmSync(path.join(opencodePlugins, "workflow-toolkit.ts"), { force: true });