@brainervirus/workit-cursor 0.8.5 → 0.8.6

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "workit",
   "displayName": "Workit",
   "description": "OpenCode-style verify, PR, changelog, commit, and session handoff for Cursor",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "author": {
     "name": "Cristhofer Pincetti"
   },

package/README.md

@@ -23,7 +23,7 @@ npx @brainervirus/workit-cli init
       "command": "npx",
       "args": [
         "-y",
-        "--package=@brainervirus/workit-cursor@0.8.0",
+        "--package=@brainervirus/workit-cursor@0.8.5",
         "workit-cursor-mcp",
         "${workspaceFolder}"
       ]
@@ -35,7 +35,7 @@ npx @brainervirus/workit-cli init
 ### Requirements
 
 - **Node.js ≥ 22** — the MCP server and session-start hook are self-contained Node bundles invoked through `npx`.
-- **Network** — `npx -y …@0.8.0` resolves and downloads the package on first run in each environment; a machine that cannot reach the npm registry cannot start the MCP server or hook (see [Runtime](#runtime)).
+- **Network** — `npx -y …@0.8.5` resolves and downloads the package on first run in each environment; a machine that cannot reach the npm registry cannot start the MCP server or hook (see [Runtime](#runtime)).
 
 ## What it provides
 
@@ -59,11 +59,11 @@ Cursor adapts workit through policy-only confirmation: approvals and lifecycle t
 
 Cursor launches the MCP server and session-start hook through `npx`, so the shipped manifests contain no repository-relative `dist` paths:
 
-- **MCP server** — `npx -y --package=@brainervirus/workit-cursor@0.8.0 workit-cursor-mcp ${workspaceFolder}`. It speaks the MCP stdio protocol; `stdout` is reserved for protocol messages and diagnostics go to `stderr`.
-- **Session-start hook** — `npx -y --package=@brainervirus/workit-cursor@0.8.0 workit-cursor-session-start`. It emits valid hook output and a diagnostic on runtime failure, and remains fail-open where Cursor's hook contract requires startup continuity.
+- **MCP server** — `npx -y --package=@brainervirus/workit-cursor@0.8.5 workit-cursor-mcp ${workspaceFolder}`. It speaks the MCP stdio protocol; `stdout` is reserved for protocol messages and diagnostics go to `stderr`.
+- **Session-start hook** — `npx -y --package=@brainervirus/workit-cursor@0.8.5 workit-cursor-session-start`. It emits valid hook output and a diagnostic on runtime failure, and remains fail-open where Cursor's hook contract requires startup continuity.
 - `npx` startup or network failure is surfaced by Cursor as an MCP/hook startup failure; Workit never silently substitutes stale local runtime code.
 
-The runtime runs from the exact reviewed pin `@0.8.0`: Cursor reviews plugin metadata from Git, while npm serves the pinned runtime. Bumping the pin is a deliberate reviewed update, made only after the target npm version is public — never a mutable `latest` dist-tag. See [Update review](#update-review).
+The runtime runs from the exact reviewed pin `@0.8.5`: Cursor reviews plugin metadata from Git, while npm serves the pinned runtime. Bumping the pin is a deliberate reviewed update, made only after the target npm version is public — never a mutable `latest` dist-tag. See [Update review](#update-review).
 
 ## Security and data handling
 
@@ -96,7 +96,7 @@ The repository root carries `.cursor-plugin/marketplace.json`, indexing `package
 
 - **Installing from Marketplace** — a Marketplace admin adds the repository URL through Cursor's authenticated publisher flow; end users then install the plugin from the Cursor Marketplace UI, which reads `.cursor-plugin/plugin.json` and the tracked components directly from Git.
 - **Submission** — Marketplace submission is a separate, later authenticated action at `https://cursor.com/marketplace/publish`. It is **not** performed here and no publication or acceptance is claimed; the repository is kept validated and submission-ready.
-- **Update review** — Git plugin metadata (manifest, rules, skills, assets) is reviewed by Cursor on Marketplace updates, while the npm runtime is pinned to the exact reviewed `@0.8.0`. Bumping that pin in `mcp.json` / `hooks-cursor.json` is a deliberate reviewed change: only after the target npm version is public, never a mutable `latest` dist-tag.
+- **Update review** — Git plugin metadata (manifest, rules, skills, assets) is reviewed by Cursor on Marketplace updates, while the npm runtime is pinned to the exact reviewed `@0.8.5`. Bumping that pin in `mcp.json` / `hooks-cursor.json` is a deliberate reviewed change: only after the target npm version is public, never a mutable `latest` dist-tag.
 - **Troubleshooting** — `workit doctor` (or the `workflow_doctor` tool) reports installation health including runtime, token, VCS/YouTrack, and log-writability checks; it exits nonzero on failure. An MCP/hook startup failure with no network is an `npx`/registry reachability issue, not a Workit defect.
 
 ## Docs

package/assets/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/assets/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/dist/cursor-session-start.js

@@ -340,7 +340,7 @@ var logger = createLogger({
 });
 var hookDir = path3.dirname(fileURLToPath(import.meta.url));
 var pluginDir = path3.resolve(hookDir, "..");
-var marker = path3.join(pluginDir, ".workflow-toolkit-root");
+var marker = path3.join(pluginDir, ".workit-root");
 setDiagnosticLogger(logger);
 logger.info(EVENT.initialization, { host: "cursor-hook", hook_dir: hookDir });
 var resolveRepoRoot = () => {
@@ -409,35 +409,35 @@ var isDestination = (input) => {
 };
 var main = async () => {
   const reminder = reminderTextFor(isDestination(await readHookInput(HOOK_READ_TIMEOUT_MS)));
-  const context = `<workflow-toolkit-askquestion-hard-gate>
+  const context = `<workit-askquestion-hard-gate>
 HARD-GATE: Any user choice with options → call Cursor AskQuestion directly with workflow-specific copy. NEVER A/B/C in chat. Overrides Superpowers brainstorming conversational options.
-</workflow-toolkit-askquestion-hard-gate>
+</workit-askquestion-hard-gate>
 
-<workflow-toolkit-visual-companion>
+<workit-visual-companion>
 HARD-GATE: NEVER offer Superpowers visual companion or open a browser tab. For UI wireframes use workflow_present_ascii; for flows use workflow_present_flow. Overrides Superpowers brainstorming visual companion offer.
-</workflow-toolkit-visual-companion>
+</workit-visual-companion>
 
-<workflow-toolkit-no-worktrees>
+<workit-no-worktrees>
 HARD-GATE: NEVER using-git-worktrees or git worktree. In-place feature/* or bugfix/* checkout only via workflow_resolve_branch + workflow_branch_setup. Dirty tree → native AskQuestion before checkout.
-</workflow-toolkit-no-worktrees>
+</workit-no-worktrees>
 
-<workflow-toolkit-sdd-path>
+<workit-sdd-path>
 HARD-GATE: NEVER .superpowers/sdd. ALWAYS workflow_sdd_context with plan_path first — resolves canonical docs/<slug>/sdd/ and creates nothing (no empty ledger; progress.md appears only on the first confirmed append). workflow_sdd_task_brief, workflow_sdd_review_package, workflow_sdd_append_progress only.
-</workflow-toolkit-sdd-path>
+</workit-sdd-path>
 
-<workflow-toolkit-todowrite>
+<workit-todowrite>
 HARD-GATE: After workflow_sdd_context, call Cursor TodoWrite with returned todos (merge: false). SDD ledger is persistence — TodoWrite is the native task list UI. Keep in_progress/completed in sync each task.
-</workflow-toolkit-todowrite>
+</workit-todowrite>
 
-<workflow-toolkit-superpowers-doc-contract>
+<workit-superpowers-doc-contract>
 ${body}
-</workflow-toolkit-superpowers-doc-contract>
+</workit-superpowers-doc-contract>
 
-<workflow-toolkit-reminder>
+<workit-reminder>
 HARD-GATE: Bounded user choices → call Cursor AskQuestion directly (never A/B/C or 1/2/3 lists in prose).
 
 ${reminder}
-</workflow-toolkit-reminder>`;
+</workit-reminder>`;
   process.stdout.write(JSON.stringify({ additional_context: context }, null, 2) + `
 `);
   process.exit(0);

package/dist/mcp-server.js

@@ -21848,7 +21848,7 @@ function cursorHooksEntry(_packageDir) {
     args: []
   };
 }
-var named = (s, name) => s === name || s.startsWith(`${name}@`), CURSOR_RUNTIME_PACKAGE = "@brainervirus/workit-cursor@0.8.0";
+var named = (s, name) => s === name || s.startsWith(`${name}@`), CURSOR_RUNTIME_PACKAGE = "@brainervirus/workit-cursor@0.8.5";
 var init_registration = () => {};
 
 // packages/workit-core/src/core/skill-manifests.ts
@@ -22219,6 +22219,17 @@ var TOKEN_PLACEHOLDER2 = "YOUR_TOKEN_HERE", findDevFromCwd = (cwd) => {
   if (typeof entry !== "object" || entry === null || Array.isArray(entry))
     return "invalid";
   return typeof entry.command === "string" ? entry.command : "invalid";
+}, validLocalDistHook = (command, res) => {
+  const m = /^node\s+(.+)$/.exec(command.trim());
+  if (!m)
+    return false;
+  const entry = m[1].trim();
+  if (!path9.isAbsolute(entry))
+    return false;
+  if (path9.resolve(entry) !== path9.resolve(path9.join(res.cursorPluginDir, "dist", "cursor-session-start.js"))) {
+    return false;
+  }
+  return validNodeEntry(entry, "node", res.env);
 }, checkLauncher = (res) => {
   const dev = res.dev;
   const hosts = hostsFor(res.host);
@@ -22234,7 +22245,7 @@ var TOKEN_PLACEHOLDER2 = "YOUR_TOKEN_HERE", findDevFromCwd = (cwd) => {
     const hook = registeredCursorHook(res);
     if (hook === "invalid") {
       missing.push(`cursor: canonical session-start hook in ${path9.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 ${path9.join(res.cursorPluginDir, "hooks", "hooks-cursor.json")} (registered ${hook})`);
     }
   }
@@ -24041,8 +24052,13 @@ function sddReviewPackage({
   const contained = resolveDocsPath({ workspace_root, path: sdd_dir });
   if (!contained.ok)
     return { error: contained.error };
+  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;
-  mkdirSync6(dir, { recursive: true });
   const base7 = base_sha.slice(0, 7);
   const head7 = head_sha.slice(0, 7);
   const diffPath = path19.join(dir, `review-${base7}..${head7}.diff`);
@@ -24052,6 +24068,13 @@ function sddReviewPackage({
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"]
     });
+    if (diff.trim() === "") {
+      return {
+        error: `empty commit range (${base_sha}..${head_sha}): diff is empty, nothing to review`,
+        code: "empty_commit_range"
+      };
+    }
+    mkdirSync6(dir, { recursive: true });
     writeFileSync5(diffPath, diff, "utf8");
     const rel = posix2(path19.relative(contained.base, diffPath));
     return { diff_path: rel, base_sha, head_sha, base7, head7 };
@@ -24069,7 +24092,8 @@ function sddAppendProgress({
     return { error: contained.error };
   const path_ = contained.path;
   const trimmed = line.trim();
-  if (!PROGRESS_RE.test(trimmed)) {
+  const match = PROGRESS_RE.exec(trimmed);
+  if (!match || match[1].toLowerCase() === match[2].toLowerCase()) {
     return { error: "invalid progress line format" };
   }
   if (existsSync11(path_) && statSync6(path_).isDirectory()) {
@@ -24087,7 +24111,7 @@ var init_sdd = __esm(() => {
   init_docs_validate();
   init_flow_state();
   init_docs_layout();
-  PROGRESS_RE = /^Task\s+\d+:\s+complete\s+\(commits\s+[0-9a-f]{7,40}\.\.[0-9a-f]{7,40},/i;
+  PROGRESS_RE = /^Task\s+\d+:\s+complete\s+\(commits\s+([0-9a-f]{7,40})\.\.([0-9a-f]{7,40}),/i;
 });
 
 // packages/workit-core/src/core/menu.ts
@@ -26793,7 +26817,7 @@ function initStatusData(configDirPath = configDir()) {
     ok: fs5.existsSync(ytJson) && youtrackConfig !== null && !("error" in youtrackConfig),
     path: fs5.existsSync(ytJson) ? resolvePath(ytJson) : path28.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 ?? path28.join(configDirPath, "youtrack.token");
   const tokenText = fs5.existsSync(ytTokenPath) ? fs5.readFileSync(ytTokenPath, "utf8").trim() : "";
@@ -26856,7 +26880,7 @@ function initStatusData(configDirPath = configDir()) {
     ok: fs5.existsSync(vcsJson) && vcsCfg !== null && !("error" in vcsCfg),
     path: fs5.existsSync(vcsJson) ? resolvePath(vcsJson) : path28.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;
   const tokenItem = (tid, label, rawPath, providerKey) => {
@@ -27924,7 +27948,7 @@ var init_server3 = __esm(async () => {
     }
     return jsonResult(withWorkspace(workspace_root, payload));
   });
-  registerTool("workflow_toolkit_init_status", {
+  registerTool("workit_init_status", {
     description: "Check workit setup (MCP deps, YouTrack config, token)",
     inputSchema: {}
   }, async () => {
@@ -27933,7 +27957,7 @@ var init_server3 = __esm(async () => {
       return jsonResult({ error: data.error });
     return jsonResult(data);
   });
-  registerTool("workflow_toolkit_status", {
+  registerTool("workit_status", {
     description: "Full health check: MCP deps, config files, YouTrack API verify. Use after editing token file.",
     inputSchema: {}
   }, async () => {
@@ -27942,7 +27966,7 @@ var init_server3 = __esm(async () => {
       return jsonResult({ error: data.error });
     return jsonResult(data);
   });
-  registerTool("workflow_toolkit_init_apply", {
+  registerTool("workit_init_apply", {
     description: "Apply init action. Requires confirmed: true. Token is NOT accepted here — user edits token file locally.",
     inputSchema: {
       action: exports_external.enum([
@@ -28377,7 +28401,7 @@ import path29 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var mcpDir = path29.dirname(fileURLToPath2(import.meta.url));
 var pluginDir = path29.resolve(mcpDir, "..");
-var marker = path29.join(pluginDir, ".workflow-toolkit-root");
+var marker = path29.join(pluginDir, ".workit-root");
 var resolveRoot = () => {
   if (process.env.WORKFLOW_TOOLKIT_ROOT && existsSync19(path29.join(process.env.WORKFLOW_TOOLKIT_ROOT, "scripts"))) {
     return process.env.WORKFLOW_TOOLKIT_ROOT;

package/hooks/hooks-cursor.json

@@ -3,7 +3,7 @@
   "hooks": {
     "sessionStart": [
       {
-        "command": "npx -y --package=@brainervirus/workit-cursor@0.8.0 workit-cursor-session-start"
+        "command": "npx -y --package=@brainervirus/workit-cursor@0.8.5 workit-cursor-session-start"
       }
     ]
   }

package/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "workit": {
       "command": "npx",
-      "args": ["-y", "--package=@brainervirus/workit-cursor@0.8.0", "workit-cursor-mcp", "${workspaceFolder}"]
+      "args": ["-y", "--package=@brainervirus/workit-cursor@0.8.5", "workit-cursor-mcp", "${workspaceFolder}"]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-cursor",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "private": false,
   "description": "Workit Cursor plugin: MCP server, hooks, rules, marketplace manifest (thin over @brainervirus/workit-core)",
   "keywords": [
@@ -39,7 +39,7 @@
     "build": "bun scripts/build.ts"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^0.8.5",
+    "@brainervirus/workit-core": "^0.8.6",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"
   },

package/skills/wk-handoff/SKILL.md

@@ -23,6 +23,8 @@ The pasted prompt includes instructions to call `workflow_sdd_context`, **Cursor
 
 `workflow_handoff_prompt` also returns `tasks[]`, `branch`, `sdd_dir`, `completed_task_ids`, and `todos` for same-session MCP use — not copy-paste transport.
 
+A destination run that executes the plan must still end with `workflow_plan_complete` once the SDD ledger is complete and repository verification passes, and never finish the run while the plan is still `active`.
+
 ## Output (success)
 
 When the tool returns `{ prompt }`, output **only** one fenced code block containing `prompt` verbatim. No preamble, no explanation outside the fence.

package/skills/wk-implement/SKILL.md

@@ -37,4 +37,8 @@ Announce: "Using implement + inline."
 
 Follow the contract verbatim. Keep TodoWrite `in_progress`/`completed` in sync each task. At verify/commit phase use `workflow_verify` and `workflow_git_context` MCP tools.
 
+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.
+
 Do not emit a handoff fence — this is in-session execution.
+
+**Mandatory:** end the run by calling MCP `workflow_plan_complete` 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

@@ -12,7 +12,7 @@ Scaffold config via MCP. **Never paste API tokens in chat.**
 
 ## Step 1 — Status (required)
 
-Call MCP `workflow_toolkit_init_status`. Show `items[]` in English.
+Call MCP `workit_init_status`. Show `items[]` in English.
 
 ### YouTrack settings (when `youtrack_config` present)
 
@@ -42,11 +42,11 @@ Call MCP `workflow_toolkit_init_status`. Show `items[]` in English.
 
 ### mcp_deps
 
-Native `AskQuestion` asks whether to install MCP dependencies → on yes: `workflow_toolkit_init_apply` action=`npm_install` confirmed=`true`
+Native `AskQuestion` asks whether to install MCP dependencies → on yes: `workit_init_apply` action=`npm_install` confirmed=`true`
 
 ### YouTrack scaffold
 
-Native `AskQuestion` asks whether to create the YouTrack scaffold → on yes: `workflow_toolkit_init_apply` action=`youtrack_scaffold` confirmed=`true`
+Native `AskQuestion` asks whether to create the YouTrack scaffold → on yes: `workit_init_apply` action=`youtrack_scaffold` confirmed=`true`
 
 ### VCS scaffold (GitLab + GitHub token files)
 
@@ -54,7 +54,7 @@ Only when `items[vcs_json].ok` is **false**:
 
 1. Native `AskQuestion` asks for GitLab or GitHub → remember `provider` (`gitlab` | `github`).
 2. Native `AskQuestion` asks `Create vcs.json and token placeholders for <provider>?`
-   → on yes: `workflow_toolkit_init_apply` action=`vcs_scaffold` confirmed=`true` **`vcs_provider=<chosen provider>`**
+   → on yes: `workit_init_apply` action=`vcs_scaffold` confirmed=`true` **`vcs_provider=<chosen provider>`**
 
 Both `gitlab.token` and `github.token` are always created (switch later by editing `provider` in `vcs.json`). Tell the user which token file is **active** for `/wk-pr` based on the chosen provider.
 
@@ -103,5 +103,5 @@ For the **active** provider (`vcs_config.provider`), show from `vcs_config.token
 ## Rules
 
 - Never ask for or accept tokens in chat.
-- Mutations only via `workflow_toolkit_init_apply` with `confirmed: true`.
+- Mutations only via `workit_init_apply` with `confirmed: true`.
 - Verification is **`/wk-status`** only — not part of init.

package/skills/wk-issue-update/SKILL.md

@@ -18,7 +18,7 @@ Post a Spanish comment and log time on a **task** issue (not the meeting issue).
 
 ## Step 0 — Toolkit ready
 
-If unsure, call `workflow_toolkit_status`. Stop if `ready: false`.
+If unsure, call `workit_status`. Stop if `ready: false`.
 
 ## Step 1 — Issue (required)
 

package/skills/wk-meetings/SKILL.md

@@ -12,7 +12,7 @@ Log meeting time to a **meeting issue** from config. **Never post a comment.**
 
 ## Step 0 — Toolkit ready
 
-If unsure, call `workflow_toolkit_status`. Stop if `ready: false`.
+If unsure, call `workit_status`. Stop if `ready: false`.
 
 ## Step 1 — Context (required)
 

package/skills/wk-status/SKILL.md

@@ -12,7 +12,7 @@ Deterministic health check. **Tools only — no manual git/curl.**
 
 ## Step 1 — Full status (required)
 
-Call MCP `workflow_toolkit_status` once.
+Call MCP `workit_status` once.
 
 Use the return value as ground truth. Do not infer state yourself.
 
@@ -80,6 +80,6 @@ Use `items[youtrack_token].token_create_url` / `token_edit_path`, or top-level `
 
 ## Rules
 
-- Do not call YouTrack HTTP directly — `workflow_toolkit_status` includes verify.
+- Do not call YouTrack HTTP directly — `workit_status` includes verify.
 - Do not ask user to paste token — point them to edit the token file if `placeholder: true`.
 - Optional: `workflow_youtrack_verify_token` only if user asks to re-test API alone.

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.