@brainervirus/workit-cursor 0.8.0 → 0.8.2

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.0",
+  "version": "0.8.2",
   "author": {
     "name": "Cristhofer Pincetti"
   },

package/README.md

@@ -23,7 +23,7 @@ npx @brainervirus/workit-cli init
       "command": "npx",
       "args": [
         "-y",
-        "--package=@brainervirus/workit-cursor@latest",
+        "--package=@brainervirus/workit-cursor@0.8.0",
         "workit-cursor-mcp",
         "${workspaceFolder}"
       ]
@@ -35,17 +35,17 @@ 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 …@latest` 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.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)).
 
 ## What it provides
 
-- MCP server exposing the `workflow_*` tools (branch setup, PR create/context, docs validate/promote, YouTrack post/log/time, templates, rules, presentation, doctor, handoff).
+- MCP server exposing the `workflow_*` tools (branch setup, PR create/context, docs validate/promote, YouTrack post/log/time, templates, rules, presentation, doctor, handoff, and plan lifecycle `workflow_plan_pause`/`resume`/`complete`).
 - Session-start contract hook.
 - 4 rules and 12 `wk-*` skills (plus 14 sanitized Superpowers skills).
 
 ## Host limitations
 
-Cursor adapts workit through policy-only confirmation: approvals and commits are recorded as policy decisions (`attested: false`) rather than fabricated delegated identity, and subagent-driven plan execution is not supported on this host. OpenCode records native `question` receipts and runs delegated tasks; see the root [README](../../README.md#host-capabilities) for the full host-capability matrix.
+Cursor adapts workit through policy-only confirmation: approvals and lifecycle transitions are recorded as policy decisions (`attested: false`) rather than fabricated delegated identity, and subagent-driven plan execution is not supported on this host. Approvals bind to the document's exact SHA-256 digest — editing an approved spec/plan invalidates the approval and forces a fresh reapproval. OpenCode records native `question` receipts and runs delegated tasks; see the root [README](../../README.md#host-capabilities) for the full host-capability matrix.
 
 ## Configuration
 
@@ -59,11 +59,11 @@ Cursor adapts workit through policy-only confirmation: approvals and commits are
 
 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@latest 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@latest 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.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.
 - `npx` startup or network failure is surfaced by Cursor as an MCP/hook startup failure; Workit never silently substitutes stale local runtime code.
 
-The `@latest` tag means the runtime updates independently of the Marketplace metadata: Cursor reviews plugin metadata from Git, while npm serves the runtime. See [Update review](#update-review).
+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).
 
 ## 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 tagged `@latest` updates independently. Reviewing an npm runtime change is a manual step: pin `--package=@brainervirus/workit-cursor@<version>` in `mcp.json` / `hooks-cursor.json` if you need immutable reviewed code instead of `@latest`.
+- **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.
 - **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

@@ -5,6 +5,17 @@ Load `using-superpowers`, `subagent-driven-development`, `test-driven-developmen
 **Branch:** <BRANCH>
 **SDD:** `<SDD_DIR>`
 
+## Handoff destination
+
+This session is a handoff destination for a continued plan. The originating session already recorded the post-plan menu choice; present exactly these four choices and never re-offer the originating handoff option:
+
+- Subagent-driven
+- Inline
+- Review spec first
+- Review plan first
+
+<workflow-handoff-destination>true</workflow-handoff-destination>
+
 ## Hard gates
 
 - The parent is coordinator-only: it does not edit product code or perform delegated exploration.

package/assets/templates/superpowers-doc-contract.md

@@ -63,6 +63,8 @@ On success, use native `question` / Cursor `AskQuestion` with exactly these opti
 
 Never emit Superpowers text beginning “Two execution options”.
 
+A handoff destination session (the seeded contract carries `<workflow-handoff-destination>true</workflow-handoff-destination>`) presents exactly four choices — Subagent-driven, Inline, Review spec first, Review plan first — and never re-offers the originating handoff option.
+
 - Specs/plans must follow `templates/spec-template.md` / `templates/plan-template.md` (mandated diagrams, tables, CA-XX).
 
 ## Doc delivery

package/dist/cursor-session-start.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // packages/workit-cursor/hooks/session-start.ts
-import { existsSync, readFileSync } from "node:fs";
-import path2 from "node:path";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import path3 from "node:path";
 import { fileURLToPath } from "node:url";
 
 // packages/workit-core/src/core/logger.ts
@@ -277,35 +277,91 @@ var DEFAULTS = {
   }
 };
 
+// packages/workit-core/src/core/menu.ts
+import { existsSync, readFileSync, readdirSync as readdirSync2 } from "node:fs";
+import path2 from "node:path";
+var SOURCE_MENU_LABELS = [
+  "Subagent-driven",
+  "Inline",
+  "Handoff",
+  "Review spec first",
+  "Review plan first"
+];
+var DESTINATION_MENU_LABELS = [
+  "Subagent-driven",
+  "Inline",
+  "Review spec first",
+  "Review plan first"
+];
+var HANDOFF_DESTINATION_MARKER = "<workflow-handoff-destination>true</workflow-handoff-destination>";
+var findMarkedDestinations = (root) => {
+  const docsDir = path2.join(root, "docs");
+  if (!existsSync(docsDir))
+    return [];
+  const slugs = [];
+  for (const slug of readdirSync2(docsDir)) {
+    const file = path2.join(docsDir, slug, "sdd", "flow.json");
+    if (!existsSync(file))
+      continue;
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8"));
+      if (parsed.handoff_destination === true)
+        slugs.push(slug);
+    } catch {
+      continue;
+    }
+  }
+  return slugs;
+};
+
+// packages/workit-core/src/core/reminder.ts
+var SOURCE_MENU_LABELS_DISPLAY = SOURCE_MENU_LABELS.map((label) => label === "Handoff" ? "Handoff (new session only)" : label);
+var REMINDER_TEXT = `<workflow-contract-reminder>
+- Bounded user choices → call the native \`question\` tool (never A/B/C or 1/2/3 lists in prose).
+- After a plan is approved → native \`question\` menu with exactly: ${SOURCE_MENU_LABELS_DISPLAY.join(", ")}.
+- Tools with \`confirmed\` → call them; never fabricate their result.
+- Before the first \`workflow_spec_approve\`/\`workflow_plan_approve\` (self-review) run the superpowers writing-plans Self-Review checklist: spec coverage (every spec requirement maps to a task), placeholder scan, type consistency; fix findings inline.
+- Delivering docs → clickable markdown link \`[spec.md](docs/<slug>/spec.md)\` + 3-5 bullet summary.
+</workflow-contract-reminder>`;
+var DESTINATION_REMINDER_TEXT = `<workflow-contract-reminder>
+- Bounded user choices → call the native \`question\` tool (never A/B/C or 1/2/3 lists in prose).
+- This session is a handoff destination: present the post-plan menu with exactly: ${DESTINATION_MENU_LABELS.join(", ")}.
+- Tools with \`confirmed\` → call them; never fabricate their result.
+- Before the first \`workflow_spec_approve\`/\`workflow_plan_approve\` (self-review) run the superpowers writing-plans Self-Review checklist: spec coverage (every spec requirement maps to a task), placeholder scan, type consistency; fix findings inline.
+- Delivering docs → clickable markdown link \`[spec.md](docs/<slug>/spec.md)\` + 3-5 bullet summary.
+${HANDOFF_DESTINATION_MARKER}
+</workflow-contract-reminder>`;
+var reminderTextFor = (destination) => destination ? DESTINATION_REMINDER_TEXT : REMINDER_TEXT;
+
 // packages/workit-cursor/hooks/session-start.ts
 var logger = createLogger({
   stderr: (event) => process.stderr.write(`${JSON.stringify(event)}
 `)
 });
-var hookDir = path2.dirname(fileURLToPath(import.meta.url));
-var pluginDir = path2.resolve(hookDir, "..");
-var marker = path2.join(pluginDir, ".workflow-toolkit-root");
+var hookDir = path3.dirname(fileURLToPath(import.meta.url));
+var pluginDir = path3.resolve(hookDir, "..");
+var marker = path3.join(pluginDir, ".workflow-toolkit-root");
 setDiagnosticLogger(logger);
 logger.info(EVENT.initialization, { host: "cursor-hook", hook_dir: hookDir });
 var resolveRepoRoot = () => {
-  if (process.env.WORKFLOW_TOOLKIT_ROOT && existsSync(path2.join(process.env.WORKFLOW_TOOLKIT_ROOT, "templates"))) {
+  if (process.env.WORKFLOW_TOOLKIT_ROOT && existsSync2(path3.join(process.env.WORKFLOW_TOOLKIT_ROOT, "templates"))) {
     return process.env.WORKFLOW_TOOLKIT_ROOT;
   }
-  if (existsSync(marker)) {
-    return readFileSync(marker, "utf8").replace(/\n+$/, "");
+  if (existsSync2(marker)) {
+    return readFileSync2(marker, "utf8").replace(/\n+$/, "");
   }
-  const ownAssets = path2.join(pluginDir, "assets");
-  if (existsSync(path2.join(ownAssets, "templates"))) {
+  const ownAssets = path3.join(pluginDir, "assets");
+  if (existsSync2(path3.join(ownAssets, "templates"))) {
     return ownAssets;
   }
-  return path2.resolve(hookDir, "../../workit-core");
+  return path3.resolve(hookDir, "../../workit-core");
 };
 var body = null;
 var repoRoot = resolveRepoRoot();
 try {
-  const contract = path2.join(repoRoot, "templates", "superpowers-doc-contract.md");
-  if (existsSync(contract))
-    body = readFileSync(contract, "utf8");
+  const contract = path3.join(repoRoot, "templates", "superpowers-doc-contract.md");
+  if (existsSync2(contract))
+    body = readFileSync2(contract, "utf8");
 } catch (err) {
   logger.error(EVENT.hooks, { boundary: "session-start", root: repoRoot, ...errorDetail(err) });
   body = null;
@@ -315,7 +371,45 @@ if (body === null) {
 `);
   process.exit(0);
 }
-var context = `<workflow-toolkit-askquestion-hard-gate>
+var HOOK_READ_TIMEOUT_MS = Number(process.env.WORKFLOW_HOOK_READ_TIMEOUT_MS ?? "2000");
+var readHookInput = (timeoutMs) => {
+  if (process.stdin.isTTY)
+    return Promise.resolve({});
+  return new Promise((resolve) => {
+    let buffer = "";
+    let settled = false;
+    const timer = setTimeout(() => settle({}), timeoutMs);
+    const onData = (chunk) => {
+      buffer += String(chunk);
+      const text = buffer.trim();
+      if (!text)
+        return;
+      try {
+        const parsed = JSON.parse(text);
+        settle(typeof parsed === "object" && parsed !== null ? parsed : {});
+      } catch {}
+    };
+    const onEnd = () => settle({});
+    function settle(value) {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      process.stdin.off("data", onData);
+      process.stdin.off("end", onEnd);
+      resolve(value);
+    }
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+  });
+};
+var isDestination = (input) => {
+  const roots = Array.isArray(input.workspace_roots) ? input.workspace_roots : [];
+  return roots.some((root) => typeof root === "string" && findMarkedDestinations(root).length > 0);
+};
+var main = async () => {
+  const reminder = reminderTextFor(isDestination(await readHookInput(HOOK_READ_TIMEOUT_MS)));
+  const context = `<workflow-toolkit-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>
 
@@ -340,12 +434,20 @@ ${body}
 </workflow-toolkit-superpowers-doc-contract>
 
 <workflow-toolkit-reminder>
-HARD-GATE: Bounded user choices → call Cursor AskQuestion directly (never A/B/C or 1/2/3 lists in prose). After a plan is approved → AskQuestion menu with: Subagent-driven, Inline, Handoff (new session only), Review spec first, Review plan first. Tools with confirmed → call them; never fabricate results.
-Delivering docs → clickable markdown link (docs/<slug>/spec.md) + 3-5 bullet summary.
+HARD-GATE: Bounded user choices → call Cursor AskQuestion directly (never A/B/C or 1/2/3 lists in prose).
+
+${reminder}
 </workflow-toolkit-reminder>`;
-process.stdout.write(JSON.stringify({ additional_context: context }, null, 2) + `
+  process.stdout.write(JSON.stringify({ additional_context: context }, null, 2) + `
 `);
-process.exit(0);
+  process.exit(0);
+};
+main().catch((err) => {
+  logger.error(EVENT.hooks, { boundary: "session-start", ...errorDetail(err) });
+  process.stdout.write(`{}
+`);
+  process.exit(0);
+});
 export {
   logger
 };