@brainervirus/workit-cli 0.8.4 → 0.8.6

package/README.md

@@ -24,6 +24,7 @@ workit flow status --plan docs/<slug>/plan.md        # read the effective flow s
 workit flow pause --plan docs/<slug>/plan.md [--confirm]     # active -> paused
 workit flow resume --plan docs/<slug>/plan.md [--confirm]    # paused -> active
 workit flow complete --plan docs/<slug>/plan.md [--confirm]  # complete (ledger + verification gated)
+workit flow review-package --plan docs/<slug>/plan.md --base <sha> --head <sha> [--confirm]  # write a review diff
 workit handoff --message "docs/<slug>/plan.md"      # print the destination handoff prompt
 workit                   # help
 ```
@@ -32,7 +33,7 @@ workit                   # help
 
 `workit doctor` checks the offline installation health and exits nonzero when problems are found; `--json` prints the full report as JSON instead of the human-readable table.
 
-`workit flow` maps the shared-core execution lifecycle (`pending`/`active`/`paused`/`completed`) to the CLI: `status` reads the effective flow state (approval digests, drift, execution, handoff-destination flag); `pause`/`resume`/`complete` mutate it with `--confirm` (or a TTY prompt when stdin is a TTY, exit 2 when neither applies). `workit handoff` prints the core destination handoff prompt (four-choice menu, never the originating Handoff option) and marks the flow as a handoff destination; a second handoff on an already-marked destination is rejected. Domain/verification failures exit 1 with structured JSON on stderr; usage errors exit 2.
+`workit flow` maps the shared-core execution lifecycle (`pending`/`active`/`paused`/`completed`) to the CLI: `status` reads the effective flow state (approval digests, drift, execution, handoff-destination flag); `pause`/`resume`/`complete` mutate it with `--confirm` (or a TTY prompt when stdin is a TTY, exit 2 when neither applies); `review-package` writes the review diff for a `--base..--head` range through the shared core guard, which rejects empty ranges. `workit handoff` prints the core destination handoff prompt (four-choice menu, never the originating Handoff option) and marks the flow as a handoff destination; a second handoff on an already-marked destination is rejected. Domain/verification failures exit 1 with structured JSON on stderr; usage errors exit 2.
 
 ## Behavior
 

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/index.js

@@ -43026,7 +43026,7 @@ function mergeCursorMcp(mcp, serverName, server) {
   base2.mcpServers = servers;
   return { config: base2, changed };
 }
-var CURSOR_RUNTIME_PACKAGE = "@brainervirus/workit-cursor@0.8.0";
+var CURSOR_RUNTIME_PACKAGE = "@brainervirus/workit-cursor@0.8.5";
 function cursorMcpServerEntry(_packageDir) {
   return {
     command: "npx",
@@ -43438,6 +43438,18 @@ var registeredCursorHook = (res) => {
     return "invalid";
   return typeof entry.command === "string" ? entry.command : "invalid";
 };
+var 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);
+};
 var checkLauncher = (res) => {
   const dev = res.dev;
   const hosts = hostsFor(res.host);
@@ -43453,7 +43465,7 @@ var checkLauncher = (res) => {
     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})`);
     }
   }
@@ -44213,7 +44225,7 @@ function adapterRoot(platform2, res) {
       dir = parent;
     }
   }
-  candidates.push(path10.join(res.home, ".local", "share", "workflow-toolkit", "packages", `workit-${platform2}`));
+  candidates.push(path10.join(res.home, ".local", "share", "workit", "packages", `workit-${platform2}`));
   for (const candidate of candidates) {
     if (isAdapter(candidate, platform2))
       return candidate;
@@ -44289,7 +44301,7 @@ var samePluginContent = (src, dest, relative = "") => {
       if (existsSync8(path10.join(src, entry.name)))
         continue;
       const rel = path10.join(relative, entry.name);
-      if (rel === ".workflow-toolkit-root")
+      if (rel === ".workit-root")
         continue;
       if (relative === "rules" && entry.isFile() && entry.name.endsWith(".mdc"))
         continue;
@@ -44316,7 +44328,7 @@ var preservedCursorRules = (src, dest) => {
   return preserved;
 };
 function copyPluginDir(src, dest) {
-  const marker = path10.join(dest, ".workflow-toolkit-root");
+  const marker = path10.join(dest, ".workit-root");
   const synced = readFileSafe(marker)?.trim() === src && samePluginContent(src, dest);
   if (synced)
     return "Skipped";
@@ -44336,7 +44348,7 @@ function copyPluginDir(src, dest) {
       mkdirSync3(path10.join(stage, "rules"), { recursive: true });
       writeFileSync5(path10.join(stage, "rules", name), content);
     }
-    writeFileSync5(path10.join(stage, ".workflow-toolkit-root"), src + `
+    writeFileSync5(path10.join(stage, ".workit-root"), src + `
 `, "utf8");
     if (!samePluginContent(src, stage))
       throw new Error("staged adapter content is incomplete");
@@ -46735,7 +46747,9 @@ import {
   statSync as statSync5,
   writeFileSync as writeFileSync6
 } from "node:fs";
+import { execFileSync as execFileSync3 } from "node:child_process";
 import path15 from "node:path";
+var posix2 = (p) => p.split(path15.sep).join("/");
 function ledgerCompletion(root, slug) {
   let started = false;
   const completed = [];
@@ -46771,6 +46785,45 @@ function ledgerCompletion(root, slug) {
     missing
   };
 }
+function sddReviewPackage({
+  sdd_dir,
+  base_sha,
+  head_sha,
+  workspace_root
+}) {
+  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;
+  const base7 = base_sha.slice(0, 7);
+  const head7 = head_sha.slice(0, 7);
+  const diffPath = path15.join(dir, `review-${base7}..${head7}.diff`);
+  try {
+    const diff2 = execFileSync3("git", ["diff", base_sha, head_sha], {
+      cwd: contained.base,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (diff2.trim() === "") {
+      return {
+        error: `empty commit range (${base_sha}..${head_sha}): diff is empty, nothing to review`,
+        code: "empty_commit_range"
+      };
+    }
+    mkdirSync6(dir, { recursive: true });
+    writeFileSync6(diffPath, diff2, "utf8");
+    const rel = posix2(path15.relative(contained.base, diffPath));
+    return { diff_path: rel, base_sha, head_sha, base7, head7 };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "git diff failed" };
+  }
+}
 
 // packages/workit-core/src/core/verify-project.ts
 import { spawnSync as spawnSync4 } from "node:child_process";
@@ -46785,10 +46838,10 @@ import { readFileSync as readFileSync11, mkdirSync as mkdirSync7, writeFileSync
 import path16 from "node:path";
 
 // packages/workit-core/src/core/git.ts
-import { execFileSync as execFileSync3 } from "node:child_process";
+import { execFileSync as execFileSync4 } from "node:child_process";
 var run = (cwd2, args) => {
   try {
-    const stdout = execFileSync3("git", args, {
+    const stdout = execFileSync4("git", args, {
       cwd: cwd2,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -48197,19 +48250,21 @@ var buildHandoffPrompt = (root, message) => {
 };
 
 // packages/workit-cli/src/flow.ts
-var FLOW_ACTIONS = ["status", "pause", "resume", "complete"];
+var FLOW_ACTIONS = ["status", "pause", "resume", "complete", "review-package"];
 var COMMANDS = {
   status: "workit flow status --plan <path>",
   pause: "workit flow pause --plan <path> [--confirm]",
   resume: "workit flow resume --plan <path> [--confirm]",
   complete: "workit flow complete --plan <path> [--confirm]",
+  "review-package": "workit flow review-package --plan <path> --base <sha> --head <sha> [--confirm]",
   handoff: "workit handoff --message <text>"
 };
 var FLOW_COMMANDS = {
   status: COMMANDS.status,
   pause: COMMANDS.pause,
   resume: COMMANDS.resume,
-  complete: COMMANDS.complete
+  complete: COMMANDS.complete,
+  "review-package": COMMANDS["review-package"]
 };
 var CLI_FLAG_EVIDENCE = { host: "cli", attested: false, confirmation: "flag" };
 var CLI_TTY_EVIDENCE = { host: "cli", attested: false, confirmation: "tty" };
@@ -48242,26 +48297,38 @@ var usage = (err3, text) => {
   write(err3, text);
   return 2;
 };
+var VALUE_FLAGS = ["--plan", "--base", "--head"];
 function parseFlowFlags(action, argv, err3) {
-  let plan;
+  const parsed = {};
   let confirm = false;
   for (let i = 0;i < argv.length; i++) {
     const token = argv[i];
-    if (token === "--plan") {
-      if (plan !== undefined) {
-        usage(err3, `usage: ${FLOW_COMMANDS[action]} — duplicate --plan flag`);
+    if (VALUE_FLAGS.includes(token)) {
+      if (token !== "--plan" && action !== "review-package") {
+        usage(err3, `usage: ${FLOW_COMMANDS[action]} — unknown flag: ${token}`);
         return { ok: false };
       }
       const value = argv[i + 1];
       if (value === undefined || value.trim() === "") {
-        usage(err3, `usage: ${FLOW_COMMANDS[action]} — --plan requires a non-empty path`);
+        const label = token === "--plan" ? "path" : "value";
+        usage(err3, `usage: ${FLOW_COMMANDS[action]} — ${token} requires a non-empty ${label}`);
         return { ok: false };
       }
       if (value.startsWith("--")) {
         usage(err3, `usage: ${FLOW_COMMANDS[action]} — unknown flag: ${value}`);
         return { ok: false };
       }
-      plan = value;
+      const existing = token === "--plan" ? parsed.plan : token === "--base" ? parsed.base : parsed.head;
+      if (existing !== undefined) {
+        usage(err3, `usage: ${FLOW_COMMANDS[action]} — duplicate ${token} flag`);
+        return { ok: false };
+      }
+      if (token === "--plan")
+        parsed.plan = value;
+      else if (token === "--base")
+        parsed.base = value;
+      else
+        parsed.head = value;
       i += 1;
     } else if (token === "--confirm") {
       if (action === "status") {
@@ -48278,11 +48345,21 @@ function parseFlowFlags(action, argv, err3) {
       return { ok: false };
     }
   }
-  if (plan === undefined) {
+  if (parsed.plan === undefined) {
     usage(err3, `usage: ${FLOW_COMMANDS[action]} — --plan <path> required`);
     return { ok: false };
   }
-  return { ok: true, parsed: { plan, confirm } };
+  if (action === "review-package") {
+    if (parsed.base === undefined) {
+      usage(err3, `usage: ${FLOW_COMMANDS[action]} — --base <sha> required`);
+      return { ok: false };
+    }
+    if (parsed.head === undefined) {
+      usage(err3, `usage: ${FLOW_COMMANDS[action]} — --head <sha> required`);
+      return { ok: false };
+    }
+  }
+  return { ok: true, parsed: { plan: parsed.plan, confirm, base: parsed.base, head: parsed.head } };
 }
 async function resolveConfirmation(deps, confirmFlag, out, err3) {
   if (confirmFlag)
@@ -48337,12 +48414,33 @@ function mutateCommand(root, plan, action, evidence, deps, out, err3) {
   });
   return 0;
 }
+function reviewPackageCommand(root, parsed, out, err3) {
+  const resolved = resolveCanonicalLayout({ workspace_root: root, plan_path: parsed.plan });
+  if (!resolved.ok)
+    return domainFail(err3, "path_invalid", resolved.error);
+  const result2 = sddReviewPackage({
+    sdd_dir: path21.posix.join("docs", resolved.layout.slug, "sdd"),
+    base_sha: parsed.base,
+    head_sha: parsed.head,
+    workspace_root: root
+  });
+  if ("diff_path" in result2) {
+    writeJSON(out, {
+      ok: true,
+      diff_path: result2.diff_path,
+      base_sha: result2.base_sha,
+      head_sha: result2.head_sha
+    });
+    return 0;
+  }
+  return domainFail(err3, result2.code ?? "review_package_failed", result2.error);
+}
 async function runFlowCommand(argv, deps = {}) {
   const out = outStream(deps);
   const err3 = errStream(deps);
   const [action, ...rest2] = argv;
   if (!action || !FLOW_ACTIONS.includes(action)) {
-    return usage(err3, "usage: workit flow <status|pause|resume|complete> --plan <path> [--confirm]");
+    return usage(err3, "usage: workit flow <status|pause|resume|complete|review-package> --plan <path> [--confirm]");
   }
   const flowAction = action;
   const parsed = parseFlowFlags(flowAction, rest2, err3);
@@ -48355,6 +48453,9 @@ async function runFlowCommand(argv, deps = {}) {
   const evidence = await resolveConfirmation(deps, parsed.parsed.confirm, out, err3);
   if (evidence === null)
     return 2;
+  if (flowAction === "review-package") {
+    return reviewPackageCommand(root, parsed.parsed, out, err3);
+  }
   return mutateCommand(root, parsed.parsed.plan, flowAction, evidence, deps, out, err3);
 }
 async function runHandoffCommand(argv, deps = {}) {
@@ -48392,14 +48493,16 @@ var COMMAND_DESCRIPTIONS = [
   [COMMANDS.pause, "Pause an active plan"],
   [COMMANDS.resume, "Resume a paused plan"],
   [COMMANDS.complete, "Complete a plan (ledger and verification gated)"],
+  [COMMANDS["review-package"], "Write a review diff for a base..head range"],
   [COMMANDS.handoff, "Emit the destination handoff prompt for a plan"]
 ];
+var helpColumn = Math.max(...COMMAND_DESCRIPTIONS.map(([cmd]) => cmd.length)) + 2;
 var HELP = `workit — workflow rails for agentic coding
 
 Usage:
   workit init      Run the interactive setup wizard
   workit doctor    Verify the offline installation health (add --json for a machine-readable report)
-${COMMAND_DESCRIPTIONS.map(([cmd, desc]) => `  ${cmd.padEnd(49)}${desc}`).join(`
+${COMMAND_DESCRIPTIONS.map(([cmd, desc]) => `  ${cmd.padEnd(helpColumn)}${desc}`).join(`
 `)}
   workit           Show this help
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-cli",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "private": false,
   "description": "Workit interactive setup wizard (Ink TUI)",
   "keywords": [
@@ -34,9 +34,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^0.8.4",
-    "@brainervirus/workit-cursor": "^0.8.4",
-    "@brainervirus/workit-opencode": "^0.8.4",
+    "@brainervirus/workit-core": "^0.8.6",
+    "@brainervirus/workit-cursor": "^0.8.6",
+    "@brainervirus/workit-opencode": "^0.8.6",
     "@inkjs/ui": "2.0.0",
     "ink": "7.1.1",
     "react": "19.2.8"