@brainervirus/workit-core 0.8.5 → 0.8.6

package/package.json

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

package/scripts/install-cursor-plugin.sh

@@ -3,10 +3,11 @@
 set -euo pipefail
 
 REPO_SLUG="${WORKFLOW_TOOLKIT_REPO:-BrainerVirus/workit}"
-SHARE="${HOME}/.local/share/workflow-toolkit"
+SHARE="${HOME}/.local/share/workit"
 SKILLS_DIR="${HOME}/.cursor/skills"
 
 FROM_GITHUB=0
+LOCAL_DIST=0
 LOCAL_ROOT=""
 if [ -n "${BASH_SOURCE[0]:-}" ] && [ -f "${BASH_SOURCE[0]}" ]; then
   SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
@@ -19,6 +20,7 @@ fi
 for arg in "$@"; do
   case "$arg" in
     --github|--from-github) FROM_GITHUB=1 ;;
+    --local-dist) LOCAL_DIST=1 ;;
   esac
 done
 
@@ -53,10 +55,18 @@ fi
 
 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 '
+CURSOR_SETTINGS="$HOME/.cursor/settings.json" CURSOR_MCP="$HOME/.cursor/mcp.json" PLUGIN_DIR="$PLUGIN_DIR" REGISTRATION_TS="$REGISTRATION_TS" LOCAL_DIST="$LOCAL_DIST" bun -e '
 import fs from "node:fs";
-const { mergeCursorSettings, mergeCursorMcp, cursorMcpServerEntry } =
-  await import(process.env.REGISTRATION_TS!);
+import path from "node:path";
+const {
+  mergeCursorSettings,
+  mergeCursorMcp,
+  mergeCursorHooks,
+  cursorMcpServerEntry,
+  cursorHooksEntry,
+  cursorMcpLocalDistEntry,
+  cursorHookLocalDistEntry,
+} = await import(process.env.REGISTRATION_TS!);
 
 // RR-06: collapse current + legacy identities; never replace unrelated settings.
 const settingsPath = process.env.CURSOR_SETTINGS!;
@@ -66,15 +76,31 @@ 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/CA-17: one portable workit MCP registration via the published npx bin;
-// stale "workflow-toolkit" entries removed.
-const server = cursorMcpServerEntry(process.env.PLUGIN_DIR!);
+// RR-06/CA-17: one portable workit MCP registration. Default is the published
+// npx pin (Marketplace-safe); --local-dist runs the installed plugin'"'"'s own
+// built dist through node so a checkout install carries the current code.
+const pluginDir = process.env.PLUGIN_DIR!;
+const localDist = process.env.LOCAL_DIST === "1";
+const server = localDist
+  ? cursorMcpLocalDistEntry(pluginDir)
+  : cursorMcpServerEntry(pluginDir);
 const mcpPath = process.env.CURSOR_MCP!;
 const mcp = fs.existsSync(mcpPath)
   ? JSON.parse(fs.readFileSync(mcpPath, "utf8"))
   : { mcpServers: {} };
 const mergedMcp = mergeCursorMcp(mcp, "workit", server);
 fs.writeFileSync(mcpPath, JSON.stringify(mergedMcp.config, null, 2) + "\n");
+
+// The plugin'"'"'s own hooks-cursor.json ships the npx pin; the local-dist
+// install swaps its sessionStart entry to node against the installed dist.
+if (localDist) {
+  const hooksPath = path.join(pluginDir, "hooks", "hooks-cursor.json");
+  const hooks = fs.existsSync(hooksPath)
+    ? JSON.parse(fs.readFileSync(hooksPath, "utf8"))
+    : { version: 1, hooks: {} };
+  const mergedHooks = mergeCursorHooks(hooks, cursorHookLocalDistEntry(pluginDir));
+  fs.writeFileSync(hooksPath, JSON.stringify(mergedHooks.config, null, 2) + "\n");
+}
 '
 
 # DG-09: verify the just-written Cursor registration with the shared offline doctor.

package/scripts/install-opencode-plugin.sh

@@ -5,7 +5,7 @@ set -euo pipefail
 SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
 ROOT="$(CDPATH= cd -- "$SCRIPT_DIR/../../.." && pwd)"
 CORE_SCRIPTS="$ROOT/packages/workit-core/scripts"
-SHARE="${HOME}/.local/share/workflow-toolkit"
+SHARE="${HOME}/.local/share/workit"
 DEV="${WORKFLOW_TOOLKIT_DEV:-$ROOT}"
 CONFIG="${HOME}/.config/opencode/opencode.json"
 

package/scripts/run-cursor-mcp.sh

@@ -3,4 +3,4 @@
 # 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
-exec npx -y --package=@brainervirus/workit-cursor@0.8.0 workit-cursor-mcp "$@"
+exec npx -y --package=@brainervirus/workit-cursor@0.8.5 workit-cursor-mcp "$@"

package/scripts/sync-runtime.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 . "$SCRIPT_DIR/lib/config-dir.sh"
 
-SHARE="${HOME}/.local/share/workflow-toolkit"
+SHARE="${HOME}/.local/share/workit"
 PLUGIN_DIR="${HOME}/.cursor/plugins/local/workit"
 OPENCODE_PLUGINS="${HOME}/.config/opencode/plugins"
 DEV_DEFAULT="${HOME}/Documents/projects/personal/workflow-toolkit"
@@ -126,7 +126,7 @@ if [ -d "$CONFIG_RULES_DIR" ]; then
     });
   " >/dev/null 2>&1 || true
 fi
-printf '%s\n' "$SHARE/packages/workit-core" >"$PLUGIN_DIR/.workflow-toolkit-root"
+printf '%s\n' "$SHARE/packages/workit-core" >"$PLUGIN_DIR/.workit-root"
 
 # 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.

package/scripts/update-superpowers.sh

@@ -51,6 +51,32 @@ find "$VENDOR/skills" -type f \( -name '*.md' -o -name '*.ts' \) -print0 | while
     "$f"
 done
 
+# Re-apply the per-task commit-range rule (CA-02) to the vendored
+# subagent-driven-development skill after every re-sync: upstream does not
+# carry it, and the hand-edit is current truth. Idempotent — when the rule is
+# already present the block is a no-op, so re-running leaves one copy. The awk
+# temp file lives in $STAGE (already trap-cleaned), so a failed awk leaves no
+# .tmp behind in the vendor dir, and if the marker headings were renamed or
+# reordered upstream the rule is appended at end-of-file instead of silently
+# no-oping.
+SDD_SKILL="$VENDOR/skills/subagent-driven-development/SKILL.md"
+RULE="- Each task produces exactly one contiguous non-empty commit range: fix rounds append commits to it, never amend or rewrite an active review range, and the ledger progress line records the task's real base..head shas."
+if [ -f "$SDD_SKILL" ] && ! grep -qF "one contiguous non-empty commit range" "$SDD_SKILL"; then
+  TMP="$STAGE/sdd-skill.tmp"
+  awk -v rule="$RULE" '
+    /^## Durable Progress$/ { in_section=1 }
+    in_section && !inserted && /^## Prompt Templates$/ {
+      print rule;
+      inserted=1;
+    }
+    { print }
+  ' "$SDD_SKILL" > "$TMP"
+  if ! grep -qF "one contiguous non-empty commit range" "$TMP"; then
+    printf '%s\n' "$RULE" >> "$TMP"
+  fi
+  mv "$TMP" "$SDD_SKILL"
+fi
+
 printf '%s\n' "$VERSION" > "$VENDOR/VERSION"
 echo "Vendored superpowers $VERSION -> $VENDOR (patched to docs/<slug>/ layout)"
 echo "Review with: git status && git diff --stat"

package/skills/wk-handoff/SKILL.md

@@ -13,5 +13,6 @@ disable-model-invocation: true
 5. Pass only `message`; the tool itself recognizes an exact `--stay` flag and otherwise selects the new session.
 6. Report the structured success, failure stage, or partial result; never infer success.
 7. After any `workflow_handoff_session` result—success, partial, or failure—end the originating turn immediately after one status message. Never create todos, execute the plan inline, modify files, retry handoff, or call another tool.
+8. A destination run that executes the plan must still end with `workflow_plan_complete` (or the CLI `workit flow complete`) once the SDD ledger is complete and repository verification passes, and never finish the run while the plan is still `active`.
 
 Never emit a continuation prompt, use the clipboard, or ask the user to copy text. If selected, report the session ID only if the current session remains visible. If staying, report the seeded session ID. On failure, report `stage` and `error`; preserve any returned session for the session picker and never recreate it automatically. `todowrite` and `task` are unnecessary here.

package/skills/wk-implement/SKILL.md

@@ -34,8 +34,12 @@ For every plan task whose ID is absent from `completed_task_ids`:
 6. Dispatch separate `general` agents for spec-compliance review and code-quality review. **Blocking findings** (Critical, Important, or spec-compliance) may trigger at most **two** fix+re-review rounds per task. **Advisory** findings (Minor, style, YAGNI, taste) never pause the loop — append them to `<SDD_DIR>/advisories.md` with the task id.
 7. Append the validated ledger line with `workflow_sdd_append_progress` using `confirmed: true`, then mark the task completed with `todowrite`.
 
+Each task lands exactly one contiguous non-empty commit range (`base..head`): fix rounds append commits to that range and never rewrite/amend an active review range; each progress line records the task's real base..head shas.
+
 Never redispatch completed task IDs. Pass task briefs and review diffs to agents; do not make them reparse the plan. Keep commits on the in-place feature/bugfix branch.
 
 ## Final gate
 
 After all remaining tasks, dispatch a final full-branch code review, run `workflow_verify`, and report exact per-check results. Present the full `<SDD_DIR>/advisories.md` roll-up once, then use native `question` so the user can choose which advisory items to fix, discuss, or discard. Only then may advisory fixes run. Use `workflow_git_context` for the final commit preview and the `wk-commit` skill for any approved commit. If a tracked stash reference exists, preview reapplication with `question`, then call `workflow_branch_setup` with `confirmed: true` only after approval.
+
+**Mandatory:** end the run by calling `workflow_plan_complete` (OpenCode/Cursor) or the CLI `workit flow complete` (CLI host) after the final task once the SDD ledger is complete (all task IDs appended) and `workflow_verify` passes — a complete ledger and green verification are the tool's gates. Never finish the run while the plan is still `active`.

package/skills/wk-init/SKILL.md

@@ -7,10 +7,10 @@ disable-model-invocation: true
 # Init
 
 1. Load this skill explicitly through OpenCode's `skill` tool.
-2. Call the read-only `workflow_toolkit_init_status` context tool; its result is ground truth.
+2. Call the read-only `workit_init_status` context tool; its result is ground truth.
 3. Draft an exact preview of each missing scaffold and the active VCS provider.
 4. For each guarded mutation, use native `question` with concise choices and allow a custom answer.
-5. Call `workflow_toolkit_init_apply` only after approval with `confirmed: true` and the chosen action.
+5. Call `workit_init_apply` only after approval with `confirmed: true` and the chosen action.
 6. Report the structured success, failure stage, or partial result; never infer success.
 
 Never ask for or accept tokens in chat. For missing YouTrack configuration, preview `youtrack_scaffold`; for missing VCS configuration, ask GitLab or GitHub, preview `vcs_scaffold`, and pass `vcs_provider`. Both provider token placeholders may be created, but identify which one is active. Show the returned token-create URL and local edit path after apply. Verification remains a separate `wk-status` run. `todowrite` and `task` are unnecessary here.
@@ -24,8 +24,8 @@ When the user wants to personalize the toolkit (locale, timezone, branch policy)
 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`, …).
 
-Then call `workflow_toolkit_init_apply` with `action: "config"`, `confirmed: true`, and the answered values. Report the written `config.json` path and its contents.
+Then call `workit_init_apply` with `action: "config"`, `confirmed: true`, and the answered values. Report the written `config.json` path and its contents.
 
-After config, call `workflow_toolkit_init_apply` with `action: "gitignore"` and `confirmed: true` to ensure the project `.gitignore` covers `docs/*/sdd/` and common OS/editor entries (creates it if missing, preserves existing entries).
+After config, call `workit_init_apply` with `action: "gitignore"` and `confirmed: true` to ensure the project `.gitignore` covers `docs/*/sdd/` and common OS/editor entries (creates it if missing, preserves existing entries).
 
-After gitignore, call `workflow_toolkit_init_apply` with `action: "hygiene"`, `confirmed: true`, and `include_open_source: true` for open-source repos — creates CHANGELOG.md (Keep a Changelog), README.md, .editorconfig, .gitattributes, and optionally LICENSE + CONTRIBUTING.md. Never overwrites existing files.
+After gitignore, call `workit_init_apply` with `action: "hygiene"`, `confirmed: true`, and `include_open_source: true` for open-source repos — creates CHANGELOG.md (Keep a Changelog), README.md, .editorconfig, .gitattributes, and optionally LICENSE + CONTRIBUTING.md. Never overwrites existing files.

package/skills/wk-status/SKILL.md

@@ -7,10 +7,10 @@ disable-model-invocation: true
 # Status
 
 1. Load this skill explicitly through OpenCode's `skill` tool.
-2. Call the read-only `workflow_toolkit_status` context tool once; its result is ground truth.
+2. Call the read-only `workit_status` context tool once; its result is ground truth.
 3. Draft the health report from structured facts.
 4. This workflow has no guarded mutation and does not need `question`.
 5. Do not call any mutation tool.
 6. Report the structured success, failure stage, or partial result; never infer success.
 
-Show every `items[]` result, the resolved YouTrack settings and verification, the VCS provider and verification, and the exact `ready` verdict. For placeholders, point to the returned token creation and edit paths; never request tokens in chat. Use only `workflow_toolkit_status` and report its structured state. Do not run shell, Git, direct HTTP, isolated token verification, or any mutation. `todowrite` and `task` are unnecessary for this read-only workflow.
+Show every `items[]` result, the resolved YouTrack settings and verification, the VCS provider and verification, and the exact `ready` verdict. For placeholders, point to the returned token creation and edit paths; never request tokens in chat. Use only `workit_status` and report its structured state. Do not run shell, Git, direct HTTP, isolated token verification, or any mutation. `todowrite` and `task` are unnecessary for this read-only workflow.

package/src/core/doctor.ts

@@ -454,6 +454,24 @@ const registeredCursorHook = (res: Resolved): string | null | "invalid" => {
   return typeof entry.command === "string" ? entry.command : "invalid";
 };
 
+// The local-dist install points the session-start hook at the plugin's own
+// built dist (`node <pluginDir>/dist/cursor-session-start.js`) so Cursor runs
+// the checkout's code. Accept that form — validated against the real dist entry
+// — alongside the canonical npx pin, mirroring the MCP launcher's node form.
+const validLocalDistHook = (command: string, res: Resolved): boolean => {
+  const m = /^node\s+(.+)$/.exec(command.trim());
+  if (!m) return false;
+  const entry = m[1].trim();
+  if (!path.isAbsolute(entry)) return false;
+  if (
+    path.resolve(entry) !==
+    path.resolve(path.join(res.cursorPluginDir, "dist", "cursor-session-start.js"))
+  ) {
+    return false;
+  }
+  return validNodeEntry(entry, "node", res.env);
+};
+
 const checkLauncher = (res: Resolved): DoctorCheck => {
   const dev = res.dev;
   const hosts = hostsFor(res.host);
@@ -483,7 +501,7 @@ const checkLauncher = (res: Resolved): DoctorCheck => {
       missing.push(
         `cursor: canonical session-start hook in ${path.join(res.cursorPluginDir, "hooks", "hooks-cursor.json")}`,
       );
-    } else if (hook !== null && hook !== canonicalCursorHook) {
+    } else if (hook !== null && hook !== canonicalCursorHook && !validLocalDistHook(hook, res)) {
       missing.push(
         `cursor: canonical session-start hook in ${path.join(res.cursorPluginDir, "hooks", "hooks-cursor.json")} (registered ${hook})`,
       );

package/src/core/flow-state.ts

@@ -2032,7 +2032,7 @@ export const COORDINATOR_WRITE_TOOLS: readonly string[] = [
   "workflow_template_edit",
   "workflow_changelog_apply",
   "workflow_branch_setup",
-  "workflow_toolkit_init_apply",
+  "workit_init_apply",
   "workflow_docs_promote",
   "workflow_docs_layout",
   "workflow_docs_repo_link",

package/src/core/init.ts

@@ -122,7 +122,7 @@ export function initStatusData(configDirPath = configDir()): Record<string, any>
     ok: fs.existsSync(ytJson) && youtrackConfig !== null && !("error" in youtrackConfig),
     path: fs.existsSync(ytJson) ? resolvePath(ytJson) : path.resolve(ytJson),
     config_edit_path: resolvePath(ytJson),
-    fix: "workflow_toolkit_init_apply action=youtrack_scaffold",
+    fix: "workit_init_apply action=youtrack_scaffold",
   });
 
   const ytTokenPath = youtrackConfig?.tokenFile ?? path.join(configDirPath, "youtrack.token");
@@ -192,7 +192,7 @@ export function initStatusData(configDirPath = configDir()): Record<string, any>
     ok: fs.existsSync(vcsJson) && vcsCfg !== null && !("error" in vcsCfg),
     path: fs.existsSync(vcsJson) ? resolvePath(vcsJson) : path.resolve(vcsJson),
     config_edit_path: resolvePath(vcsJson),
-    fix: "workflow_toolkit_init_apply action=vcs_scaffold",
+    fix: "workit_init_apply action=vcs_scaffold",
   });
 
   const provActive = vcsCfg && !("error" in vcsCfg) ? vcsCfg.provider : null;

package/src/core/registration.ts

@@ -184,7 +184,7 @@ export function mergeCursorHooks(
  * The single source for every source-derived Cursor runtime selector; the
  * committed manifests keep the literal (static data cannot import TS).
  */
-export const CURSOR_RUNTIME_PACKAGE = "@brainervirus/workit-cursor@0.8.0";
+export const CURSOR_RUNTIME_PACKAGE = "@brainervirus/workit-cursor@0.8.5";
 
 /**
  * Portable Cursor MCP server entry (CA-16/CA-17): launch the published package
@@ -214,3 +214,34 @@ export function cursorHooksEntry(_packageDir: string): {
     args: [],
   };
 }
+
+/**
+ * Local-dev Cursor MCP server entry: run the installed plugin's own built dist
+ * through node instead of the published npx pin, so a checkout install runs the
+ * branch's code (rename included) without waiting for a release. The committed
+ * Marketplace manifests keep the reviewed pin; this form is written by the
+ * local install path only.
+ */
+export function cursorMcpLocalDistEntry(packageDir: string): {
+  command: string;
+  args: string[];
+} {
+  return {
+    command: "node",
+    args: [path.join(packageDir, "dist", "mcp-server.js"), "${workspaceFolder}"],
+  };
+}
+
+/**
+ * Local-dev Cursor sessionStart hook entry: node against the installed dist, in
+ * Cursor's documented single-command-string hook format (no args array).
+ */
+export function cursorHookLocalDistEntry(packageDir: string): {
+  command: string;
+  args: string[];
+} {
+  return {
+    command: `node ${path.join(packageDir, "dist", "cursor-session-start.js")}`,
+    args: [],
+  };
+}

package/src/core/sdd.ts

@@ -221,8 +221,17 @@ export function sddReviewPackage({
 }) {
   const contained = resolveDocsPath({ workspace_root, path: sdd_dir });
   if (!contained.ok) return { error: contained.error };
+  // Empty-range guard (Phase 2): a review package over `base..head` where the
+  // endpoints collapse to nothing is a contract error, not an artifact. Reject
+  // BEFORE any diff file is created or written (Task 1's RED evidence watches
+  // the guard, and the adapters only surface this core error — never a copy).
+  if (base_sha === head_sha) {
+    return {
+      error: `empty commit range (base_sha ${base_sha} === head_sha ${head_sha}): nothing to review`,
+      code: "empty_commit_range",
+    };
+  }
   const dir = contained.path;
-  mkdirSync(dir, { recursive: true });
   const base7 = base_sha.slice(0, 7);
   const head7 = head_sha.slice(0, 7);
   const diffPath = path.join(dir, `review-${base7}..${head7}.diff`);
@@ -234,6 +243,17 @@ export function sddReviewPackage({
       // captured error, never in the suite output.
       stdio: ["pipe", "pipe", "pipe"],
     });
+    // Distinct shas that still diff to nothing are an empty range too (the
+    // "or a diff that is empty" clause): no artifact is written for it, and
+    // the sdd/ dir is created only once a real diff survives (an empty-range
+    // rejection must leave no directory behind).
+    if (diff.trim() === "") {
+      return {
+        error: `empty commit range (${base_sha}..${head_sha}): diff is empty, nothing to review`,
+        code: "empty_commit_range",
+      };
+    }
+    mkdirSync(dir, { recursive: true });
     writeFileSync(diffPath, diff, "utf8");
     const rel = posix(path.relative(contained.base, diffPath));
     return { diff_path: rel, base_sha, head_sha, base7, head7 };
@@ -242,7 +262,7 @@ export function sddReviewPackage({
   }
 }
 
-const PROGRESS_RE = /^Task\s+\d+:\s+complete\s+\(commits\s+[0-9a-f]{7,40}\.\.[0-9a-f]{7,40},/i;
+const PROGRESS_RE = /^Task\s+\d+:\s+complete\s+\(commits\s+([0-9a-f]{7,40})\.\.([0-9a-f]{7,40}),/i;
 
 export function sddAppendProgress({
   progress_path,
@@ -257,7 +277,11 @@ export function sddAppendProgress({
   if (!contained.ok) return { error: contained.error };
   const path_ = contained.path;
   const trimmed = line.trim();
-  if (!PROGRESS_RE.test(trimmed)) {
+  const match = PROGRESS_RE.exec(trimmed);
+  // A regex alone cannot compare two groups: reject identical base/head shas
+  // after the format matches so `5db04ae..bd0a810` still passes while
+  // `abcdef0123456789..abcdef0123456789` is rejected (Phase 2).
+  if (!match || match[1].toLowerCase() === match[2].toLowerCase()) {
     return { error: "invalid progress line format" };
   }
   if (existsSync(path_) && statSync(path_).isDirectory()) {

package/src/core/setup.ts

@@ -710,7 +710,7 @@ function applyMutation(m: CoreMutation): SetupResultEntry {
 // Package-native adapter resolution: the packaged CLI/core resolve the adapter
 // packages from the same install (node_modules sibling), a dev checkout
 // (WORKFLOW_TOOLKIT_DEV / packages/workit-<host> walking up from cwd), or the
-// share clone (~/.local/share/workflow-toolkit) — mirroring the install scripts.
+// share clone (~/.local/share/workit) — mirroring the install scripts.
 const isAdapter = (root: string, platform: Platform): boolean => {
   try {
     const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")) as {
@@ -742,7 +742,7 @@ function adapterRoot(platform: Platform, res: ResolvedApply): string | null {
     }
   }
   candidates.push(
-    path.join(res.home, ".local", "share", "workflow-toolkit", "packages", `workit-${platform}`),
+    path.join(res.home, ".local", "share", "workit", "packages", `workit-${platform}`),
   );
   for (const candidate of candidates) {
     if (isAdapter(candidate, platform)) return candidate;
@@ -805,7 +805,7 @@ function applyOpenCode(root: string, res: ResolvedApply): SetupResultEntry {
 }
 
 // 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
+// and write the same `.workit-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 => {
@@ -827,7 +827,7 @@ const samePluginContent = (src: string, dest: string, relative = ""): boolean =>
     for (const entry of readdirSync(dest, { withFileTypes: true })) {
       if (existsSync(path.join(src, entry.name))) continue;
       const rel = path.join(relative, entry.name);
-      if (rel === ".workflow-toolkit-root") continue;
+      if (rel === ".workit-root") continue;
       if (relative === "rules" && entry.isFile() && entry.name.endsWith(".mdc")) continue;
       return false;
     }
@@ -854,7 +854,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 marker = path.join(dest, ".workit-root");
   const synced = readFileSafe(marker)?.trim() === src && samePluginContent(src, dest);
   if (synced) return "Skipped";
   const hadDir = existsSync(dest);
@@ -873,7 +873,7 @@ function copyPluginDir(src: string, dest: string): SetupResultStatus {
       mkdirSync(path.join(stage, "rules"), { recursive: true });
       writeFileSync(path.join(stage, "rules", name), content);
     }
-    writeFileSync(path.join(stage, ".workflow-toolkit-root"), src + "\n", "utf8");
+    writeFileSync(path.join(stage, ".workit-root"), src + "\n", "utf8");
     if (!samePluginContent(src, stage)) throw new Error("staged adapter content is incomplete");
     if (hadDir) renameSync(dest, backup);
     try {
@@ -892,7 +892,7 @@ function copyPluginDir(src: string, dest: string): SetupResultStatus {
 // 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
+// `.workit-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");

package/src/core/sync-runtime.ts

@@ -107,7 +107,7 @@ export async function syncRuntime(options: SyncRuntimeOptions = {}): Promise<Syn
     env.WORKFLOW_TOOLKIT_DEV ??
     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 share = path.join(home, ".local/share/workit");
   const pluginDir = path.join(home, ".cursor/plugins/local/workit");
   const opencodePlugins = path.join(home, ".config/opencode/plugins");
   const lock = path.join(
@@ -271,10 +271,7 @@ export async function syncRuntime(options: SyncRuntimeOptions = {}): Promise<Syn
         );
       }
     }
-    writeFileSync(
-      path.join(pluginDir, ".workflow-toolkit-root"),
-      `${share}/packages/workit-core\n`,
-    );
+    writeFileSync(path.join(pluginDir, ".workit-root"), `${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

package/templates/execution-contract.md

@@ -59,6 +59,8 @@ For each top-level task absent from `completed_task_ids`:
 
 Run a separate full-branch code review, then `workflow_verify`. Present the full `<SDD_DIR>/advisories.md` roll-up once, then use native `question` so the user can choose which advisory items to fix, discuss, or discard. Report exact check results and never infer success. Use `workflow_git_context` for a commit preview and load `wk-commit` through `skill` for an approved commit. If working state contains a stash reference, preview reapplication through `question`, then call `workflow_branch_setup` with `confirmed: true` after approval.
 
+**Mandatory:** end the run by calling `workflow_plan_complete` (OpenCode/Cursor) or the CLI `workit flow complete` (CLI host) after the final task once the SDD ledger is complete (all task IDs appended) and `workflow_verify` passes — a complete ledger and green verification are the tool's gates. Never finish the run while the plan is still `active`.
+
 ## Task order
 
 <TASK_LIST>

package/templates/plan-template.md

@@ -9,6 +9,8 @@
 
 ## Global Constraints
 
+- Each task lands exactly one contiguous non-empty commit range (`base..head`): fix rounds append commits to that range and never rewrite/amend an active review range; each progress line records the task's real base..head shas.
+- The final task ends execution with `workflow_plan_complete` (or the CLI `workit flow complete`) once the SDD ledger is complete and repository verification passes — a run never finishes while the plan is still `active`.
 - <project-wide requirements, one line each>
 
 ---

package/vendor/superpowers/skills/subagent-driven-development/SKILL.md

@@ -63,6 +63,7 @@ digraph process {
     "Read plan, note context and global constraints, create todos" [shape=box];
     "More tasks remain?" [shape=diamond];
     "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [shape=box];
+    "Run verification, then workflow_plan_complete once the ledger is complete and verification passes" [shape=box];
     "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
 
     "Read plan, note context and global constraints, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)";
@@ -78,10 +79,13 @@ digraph process {
     "Mark task complete in todo list and progress ledger" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
     "More tasks remain?" -> "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [label="no"];
-    "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Use superpowers:finishing-a-development-branch";
+    "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Run verification, then workflow_plan_complete once the ledger is complete and verification passes";
+    "Run verification, then workflow_plan_complete once the ledger is complete and verification passes" -> "Use superpowers:finishing-a-development-branch";
 }
 ```
 
+**Mandatory completion:** after the final whole-branch review, run repository verification. Once the SDD ledger is complete and verification passes, end the run by calling `workflow_plan_complete` (or the CLI `workit flow complete`) — a complete ledger and green verification are the tool's gates. Never finish while the plan is still `active`.
+
 ## Pre-Flight Plan Review
 
 Before dispatching Task 1, scan the plan once for conflicts:
@@ -257,6 +261,10 @@ a ledger file, not only in todos.
 - When a task's review comes back clean, append one line to the ledger in
   the same message as your other bookkeeping:
   `Task N: complete (commits <base7>..<head7>, review clean)`.
+- Each task produces exactly one contiguous non-empty commit range: fix
+  rounds append commits to it, never amend or rewrite an active review
+  range, and the ledger progress line records the task's real base..head
+  shas.
 - The ledger is your recovery map: the commits it names exist in git even
   when your context no longer remembers creating them. After compaction,
   trust the ledger and `git log` over your own recollection.