@brainervirus/workit-cli 0.8.7 → 0.8.9

package/README.md

@@ -25,6 +25,7 @@ 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 flow append-advisory --plan docs/<slug>/plan.md --task <id> --text <text> [--confirm]  # record an advisory review finding
 workit handoff --message "docs/<slug>/plan.md"      # print the destination handoff prompt
 workit                   # help
 ```

package/assets/templates/execution-contract.md

@@ -7,12 +7,13 @@ Load `using-superpowers`, `subagent-driven-development`, `test-driven-developmen
 
 ## 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:
+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 plus model deferral and never re-offer the originating handoff option:
 
 - Subagent-driven
 - Inline
 - Review spec first
 - Review plan first
+- Change model first
 
 <workflow-handoff-destination>true</workflow-handoff-destination>
 
@@ -24,6 +25,7 @@ This session is a handoff destination for a continued plan. The originating sess
 - Use native `todowrite` for visible task state as well as the gitignored ledger.
 - Use native `question` for branch/stash choices and guarded external mutations; call mutation tools only after approval with `confirmed: true` (grounded in the recorded NativeChoiceEvidence).
 - Flow-tool confirmations are never agent-typed booleans and never caller-supplied evidence objects: on OpenCode the plugin records the user's native-`question` answer as a host-observed one-use receipt (`attested: true`, `callID`, `selectedLabel`, `recordedAt`) consumed by `workflow_spec_approve` / `workflow_plan_approve` / `workflow_plan_menu` — no evidence argument exists, and delegated worker status comes from host session parentage (`parentID`), never a caller `role` field. On Cursor, confirmations are policy-only (`attested: false`) and subagent-driven execution is rejected as unsupported.
+- Delegated authority is direct-child-only: a worker is the session whose host `parentID` exactly equals the activating coordinator's recorded `coordinator_session_id`; missing, mismatched, or multi-owner lineage fails closed with `delegation_lineage_denied`, and nested `opencode` launches are denied during active delegated work. An authorized child receives only the compact worker contract (execute the supplied brief, follow TDD, land one contiguous non-empty commit range, report results) — never coordinator guidance, `wk-implement`, or ledger management; coordinator bookkeeping via `workflow_sdd_*` stays with the coordinator session.
 - On Cursor, for every repository-scoped `workflow_*` call, pass the active Cursor workspace as `workspace_root`; never rely on the MCP process default.
 - Use native `task` with only the built-in `explore` and `general` agents.
 
@@ -52,7 +54,7 @@ For each top-level task absent from `completed_task_ids`:
 3. Delegate read-only discovery, when needed, to an `explore` agent. Delegate implementation to a fresh `general` agent. Product changes follow TDD.
 4. Create a working-state diff with `workflow_sdd_review_package` and `confirmed: true`.
 5. Delegate spec-compliance review and code-quality review to separate `general` agents.
-6. **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`.
+6. **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 with `workflow_sdd_append_advisory` (`--task <id> --text <text>`, `confirmed: true`) instead of an unrestricted file edit.
 7. Append the validated ledger entry with `workflow_sdd_append_progress` and `confirmed: true`; mark the todo completed.
 
 ## Final gate

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

@@ -60,10 +60,13 @@ On success, use native `question` / Cursor `AskQuestion` with exactly these opti
 3. Handoff → load `wk-handoff` (new session only)
 4. Review spec first
 5. Review plan first
+6. Change model first
+
+`Change model first` is display-only deferral: it ends the turn without calling `workflow_plan_menu` and re-presents the menu on the next turn. Every other choice must call `workflow_plan_menu` immediately after the answer and before any skill, branch question, mutation, or handoff.
 
 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.
+A handoff destination session (the seeded contract carries `<workflow-handoff-destination>true</workflow-handoff-destination>`) presents exactly five choices — Subagent-driven, Inline, Review spec first, Review plan first, Change model 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).
 

package/dist/index.js

@@ -43490,7 +43490,11 @@ var checkLauncher = (res) => {
       detail: "no dev checkout found (WORKFLOW_TOOLKIT_DEV) — skipping non-Cursor launcher checks"
     };
   }
-  return { id: "launcher", status: "pass", detail: `${res.host} launcher/hook entries present` };
+  return {
+    id: "launcher",
+    status: "pass",
+    detail: `${res.host} launcher/hook entries present`
+  };
 };
 var checkUtility = (res) => {
   const git = commandOnPath("git", res.env);
@@ -43510,7 +43514,11 @@ var checkUtility = (res) => {
       fix: "Install util-linux (flock)"
     };
   }
-  return { id: "utility", status: "pass", detail: "git (and flock where required) on PATH" };
+  return {
+    id: "utility",
+    status: "pass",
+    detail: "git (and flock where required) on PATH"
+  };
 };
 var staleEntry = (entry) => {
   if (!entry)
@@ -43532,7 +43540,11 @@ var checkStalePin = (res) => {
     };
   }
   if (!existsSync7(res.opencodeConfig)) {
-    return { id: "stale_pin", status: "pass", detail: "no opencode config — not registered" };
+    return {
+      id: "stale_pin",
+      status: "pass",
+      detail: "no opencode config — not registered"
+    };
   }
   const cfg = readJson(res.opencodeConfig);
   const entries = pluginEntries(cfg);
@@ -43563,6 +43575,118 @@ var checkStalePin = (res) => {
   }
   return { id: "stale_pin", status: "pass", detail: "opencode pin resolves" };
 };
+var pluginMcpSelectors = (res) => {
+  const p = path9.join(res.cursorPluginDir, "mcp.json");
+  if (!existsSync7(p))
+    return null;
+  const cfg = readJson(p);
+  const server = cfg?.mcpServers?.workit;
+  if (!server || typeof server !== "object" || Array.isArray(server))
+    return null;
+  const args = server.args;
+  if (!Array.isArray(args))
+    return null;
+  return args.map(String).filter((a) => a.startsWith("--package="));
+};
+var registryLatestVersion = (res) => {
+  const seam = res.env.WORKIT_DOCTOR_STALE_REGISTRY_VERSION;
+  if (typeof seam === "string" && seam) {
+    return /^\d+(?:\.\d+){1,2}$/.test(seam) ? seam : null;
+  }
+  const cmd = res.env.WORKIT_DOCTOR_STALE_REGISTRY_CMD ?? (commandOnPath("npm", res.env) ? "npm" : null);
+  if (!cmd)
+    return null;
+  try {
+    const r = spawnSync2(cmd, ["view", CURSOR_RUNTIME_PACKAGE, "version"], {
+      encoding: "utf8",
+      timeout: 20000,
+      env: res.env
+    });
+    const v = (r.stdout ?? "").trim().split(/\s+/)[0];
+    return r.status === 0 && /^\d+(?:\.\d+){1,2}$/.test(v) ? v : null;
+  } catch {
+    return null;
+  }
+};
+var installedPluginVersion = (res) => {
+  const pkg = readJson(path9.join(res.cursorPluginDir, "package.json"));
+  return typeof pkg?.version === "string" && pkg.version ? pkg.version : null;
+};
+var checkStaleInstall = (res) => {
+  if (res.host !== "cursor" && res.host !== "cli") {
+    return {
+      id: "stale_install",
+      status: "pass",
+      detail: "cursor plugin not inspected on the opencode host"
+    };
+  }
+  const canonicalMcp = cursorMcpServerEntry("").args.find((a) => a.startsWith("--package="));
+  const mcpSelectors = pluginMcpSelectors(res);
+  const legacyPin = (mcpSelectors ?? []).find((s) => s !== canonicalMcp && s.includes("@brainervirus/workit-cursor@"));
+  if (legacyPin) {
+    return {
+      id: "stale_install",
+      status: "fail",
+      detail: `stale_install: plugin mcp.json pins a legacy selector ${legacyPin} (canonical: ${canonicalMcp})`,
+      fix: "Re-run install-cursor-plugin.sh — it rewrites the workit MCP entry to the canonical @latest selector"
+    };
+  }
+  const hooksFile = path9.join(res.cursorPluginDir, "hooks", "hooks-cursor.json");
+  const hookCmd = readJson(hooksFile)?.hooks?.sessionStart?.[0]?.command ?? null;
+  const canonicalHook = canonicalCursorHook;
+  const staleHook = hookCmd !== null && hookCmd !== canonicalHook && !hookCmd.startsWith("node ") && hookCmd.includes("@brainervirus/workit-cursor@");
+  if (staleHook) {
+    return {
+      id: "stale_install",
+      status: "fail",
+      detail: `stale_install: sessionStart hook runs a legacy selector (canonical: ${canonicalHook})`,
+      fix: "Re-run install-cursor-plugin.sh — it rewrites the sessionStart hook to the canonical @latest selector"
+    };
+  }
+  const installed = installedPluginVersion(res);
+  const source = res.dev ? readJson(path9.join(res.dev, "packages/workit-cursor/package.json"))?.version ?? null : readJson(path9.join(packageRoot(), "package.json"))?.version ?? null;
+  const localDist = mcpSelectors === null && hookCmd !== null && hookCmd.startsWith("node ");
+  if (localDist && installed !== null && source !== null && !semverAtLeast(installed, source)) {
+    return {
+      id: "stale_install",
+      status: "fail",
+      detail: `stale_install: installed workit-cursor ${installed} is behind the current runtime ${source}`,
+      fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory and rewrites the workit MCP/hook entries"
+    };
+  }
+  if (installed !== null && localDist) {
+    const expected = registryLatestVersion(res);
+    if (expected === null) {
+      return {
+        id: "registry_unreachable",
+        status: "warn",
+        registryProbed: true,
+        detail: "registry_unreachable: cannot compare installed workit-cursor against the published runtime",
+        fix: "Retry when the npm registry is reachable, or re-run install-cursor-plugin.sh to refresh the install"
+      };
+    }
+    if (!semverAtLeast(installed, expected)) {
+      return {
+        id: "stale_install",
+        status: "fail",
+        registryProbed: true,
+        detail: `stale_install: local-dist workit-cursor ${installed} is behind the published runtime ${expected}`,
+        fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory with the current build"
+      };
+    }
+    return {
+      id: "stale_install",
+      status: "pass",
+      registryProbed: true,
+      detail: `installed local-dist workit-cursor ${installed} matches the published runtime ${expected}`
+    };
+  }
+  return {
+    id: "stale_install",
+    status: "pass",
+    detail: installed === null ? "installed workit-cursor selectors are canonical" : `installed workit-cursor ${installed} is metadata on the canonical @latest install (fresh at launch)`
+  };
+};
 var checkDuplicateRegistration = (res) => {
   const problems = [];
   const opencodeHost = res.host !== "cursor";
@@ -43598,7 +43722,11 @@ var checkDuplicateRegistration = (res) => {
     }
   }
   if (problems.length === 0) {
-    return { id: "duplicate_registration", status: "pass", detail: "no duplicate registrations" };
+    return {
+      id: "duplicate_registration",
+      status: "pass",
+      detail: "no duplicate registrations"
+    };
   }
   return {
     id: "duplicate_registration",
@@ -43624,7 +43752,11 @@ var checkMalformedConfig = (res) => {
     files.push(res.cursorMcp);
   const bad = files.filter((p) => !parsesAsConfigObject(p));
   if (bad.length === 0)
-    return { id: "malformed_config", status: "pass", detail: "config files parse" };
+    return {
+      id: "malformed_config",
+      status: "pass",
+      detail: "config files parse"
+    };
   return {
     id: "malformed_config",
     status: "fail",
@@ -43635,10 +43767,18 @@ var checkMalformedConfig = (res) => {
 var checkWorkspaceMismatch = (res) => {
   const file = path9.join(res.configDir, "workspaces.json");
   if (!existsSync7(file))
-    return { id: "workspace_mismatch", status: "pass", detail: "no workspaces configured" };
+    return {
+      id: "workspace_mismatch",
+      status: "pass",
+      detail: "no workspaces configured"
+    };
   const ws = readJson(file);
   if (!Array.isArray(ws?.workspaces)) {
-    return { id: "workspace_mismatch", status: "pass", detail: "no workspaces configured" };
+    return {
+      id: "workspace_mismatch",
+      status: "pass",
+      detail: "no workspaces configured"
+    };
   }
   const match = resolveWorkspaceFrom(res.cwd, res.configDir);
   if (match)
@@ -43680,7 +43820,11 @@ var checkCredentialMetadata = (res) => {
     }
   }
   if (tokenPaths.length === 0) {
-    return { id: "credential_metadata", status: "pass", detail: "no credentials configured" };
+    return {
+      id: "credential_metadata",
+      status: "pass",
+      detail: "no credentials configured"
+    };
   }
   const problems = [];
   for (const raw of tokenPaths) {
@@ -43718,7 +43862,11 @@ var checkLogWritable = (res) => {
     mkdirSync2(logsDir, { recursive: true, mode: 448 });
     writeFileSync4(probe, `{"probe":true}
 `, { mode: 384 });
-    return { id: "log_writable", status: "pass", detail: "log directory writable" };
+    return {
+      id: "log_writable",
+      status: "pass",
+      detail: "log directory writable"
+    };
   } catch (err) {
     return {
       id: "log_writable",
@@ -43739,6 +43887,7 @@ var RUN_CHECKS = [
   checkLauncher,
   checkUtility,
   checkStalePin,
+  checkStaleInstall,
   checkDuplicateRegistration,
   checkMalformedConfig,
   checkWorkspaceMismatch,
@@ -43751,21 +43900,27 @@ var INSTALLER_REQUIRED = new Set([
   "launcher",
   "utility",
   "stale_pin",
+  "stale_install",
   "duplicate_registration",
   "malformed_config"
 ]);
 var runDoctor = (options = {}) => {
   const res = resolve(options);
   const raw = RUN_CHECKS.map((fn) => fn(res));
-  const checks = res.installer ? raw.map((c) => c.status === "fail" && !INSTALLER_REQUIRED.has(c.id) ? { ...c, status: "warn", detail: `${c.detail} (not enforced by installer)` } : c) : raw;
+  const checks = res.installer ? raw.map((c) => c.status === "fail" && !INSTALLER_REQUIRED.has(c.id) ? {
+    ...c,
+    status: "warn",
+    detail: `${c.detail} (not enforced by installer)`
+  } : c) : raw;
   const failed = checks.filter((c) => c.status === "fail").length;
   const warned = checks.filter((c) => c.status === "warn").length;
   const passed = checks.filter((c) => c.status === "pass").length;
   const exitCode = failed > 0 ? 1 : 0;
+  const offline = !raw.some((c) => ("registryProbed" in c) && c.registryProbed);
   const report = {
     ok: failed === 0,
     exitCode,
-    offline: true,
+    offline,
     host: res.host,
     checked_at: new Date().toISOString(),
     summary: { passed, warned, failed, total: checks.length },
@@ -43775,7 +43930,7 @@ var runDoctor = (options = {}) => {
   getDiagnosticLogger()?.info(EVENT.doctor, {
     host: res.host,
     exit_code: exitCode,
-    offline: true,
+    offline,
     failed: checks.filter((c) => c.status === "fail").map((c) => c.id),
     total: checks.length
   });
@@ -46281,6 +46436,7 @@ import {
   fsyncSync,
   mkdirSync as mkdirSync8,
   openSync,
+  readdirSync as readdirSync5,
   readFileSync as readFileSync13,
   renameSync as renameSync2,
   rmSync as rmSync2,
@@ -46827,6 +46983,58 @@ function sddReviewPackage({
     return { error: error instanceof Error ? error.message : "git diff failed" };
   }
 }
+function sddAppendAdvisory({
+  advisories_path,
+  task_id,
+  text,
+  workspace_root
+}) {
+  if (typeof task_id !== "number" || !Number.isSafeInteger(task_id) || task_id <= 0) {
+    return { error: "task_id must be a positive safe integer", code: "advisory_task_invalid" };
+  }
+  if (typeof text !== "string") {
+    return {
+      error: "advisory text must be a string of 1-1000 characters after normalization",
+      code: "advisory_text_invalid"
+    };
+  }
+  if (text.includes("\r") || text.includes(`
+`)) {
+    return {
+      error: "advisory text must be a single line (no CR/LF)",
+      code: "advisory_text_invalid"
+    };
+  }
+  const collapsed = text.trim().replace(/[ \t]+/g, " ");
+  if (collapsed.length === 0 || collapsed.length > 1000) {
+    return {
+      error: "advisory text must be 1-1000 characters after trim and horizontal-space collapse",
+      code: "advisory_text_invalid"
+    };
+  }
+  if (!/^docs\/[^/]+\/sdd\/advisories\.md$/.test(advisories_path)) {
+    return {
+      error: `advisories_path must be docs/<slug>/sdd/advisories.md: ${advisories_path}`,
+      code: "advisory_path_invalid"
+    };
+  }
+  const contained = resolveDocsPath({ workspace_root, path: advisories_path });
+  if (!contained.ok)
+    return { error: contained.error, code: "advisory_path_invalid" };
+  const abs = contained.path;
+  if (existsSync12(abs) && statSync5(abs).isDirectory()) {
+    return {
+      error: `advisory target is a directory: ${advisories_path}`,
+      code: "advisory_target_invalid"
+    };
+  }
+  mkdirSync6(path15.dirname(abs), { recursive: true });
+  const line = `- Task ${task_id}: ${collapsed}
+`;
+  appendFileSync2(abs, line, "utf8");
+  const rel = posix2(path15.relative(contained.base, abs));
+  return { ok: true, advisory: collapsed, advisories_path: rel };
+}
 
 // packages/workit-core/src/core/verify-project.ts
 import { spawnSync as spawnSync4 } from "node:child_process";
@@ -47215,7 +47423,7 @@ root: ${cwd2}
 }
 
 // packages/workit-core/src/core/flow-state.ts
-var COORDINATOR_RECOVERY_TEXT = "A subagent-driven plan is active: coordinator product edits are blocked. " + "Delegate product mutations (task briefs, progress, review packages) to an " + "authenticated delegated worker via `task` / `wk-implement` instead of " + "editing in the coordinator session.";
+var COORDINATOR_RECOVERY_TEXT = "A subagent-driven plan is active: coordinator product edits are blocked. " + "Delegate product mutations to an authenticated delegated worker via `task` / `wk-implement` instead of " + "editing in the coordinator session.";
 var CURSOR_SUBAGENT_UNSUPPORTED_TEXT = "Cursor cannot execute subagent-driven plans: the MCP has no child-session " + "support. Choose Inline, Handoff, or a review option in this session, or " + "run the plan in OpenCode with `wk-implement`.";
 var MENU_CHOICES = [
   "subagent-driven",
@@ -47348,6 +47556,12 @@ var validateState = (parsed, slug) => {
   if (execRaw?.evidence !== undefined && !validateEvidenceValue(execRaw.evidence, true)) {
     return { ok: false, error: "flow state execution.evidence has an unsupported shape" };
   }
+  if (execRaw?.coordinator_session_id !== undefined && execRaw.coordinator_session_id !== null && typeof execRaw.coordinator_session_id !== "string") {
+    return {
+      ok: false,
+      error: "flow state execution.coordinator_session_id must be a string or null"
+    };
+  }
   return {
     ok: true,
     state: {
@@ -47363,7 +47577,8 @@ var validateState = (parsed, slug) => {
       execution: {
         status: execRaw?.status ?? "pending",
         mode: execRaw?.mode ?? null,
-        evidence: execRaw?.evidence ?? null
+        evidence: execRaw?.evidence ?? null,
+        coordinator_session_id: execRaw?.coordinator_session_id ?? null
       },
       handoff_destination: parsed.handoff_destination ?? false,
       updated_at: parsed.updated_at ?? Date.now()
@@ -47500,7 +47715,7 @@ var resetForSpecDrift = (state) => ({
   spec: { ...state.spec, status: "draft", evidence: null, approved_digest: null },
   plan: { ...state.plan, status: "draft", evidence: null, approved_digest: null },
   menu: { presented: false, chosen: "", evidence: null },
-  execution: { status: "pending", mode: null, evidence: null },
+  execution: { status: "pending", mode: null, evidence: null, coordinator_session_id: null },
   handoff_destination: false,
   updated_at: Date.now()
 });
@@ -47543,9 +47758,14 @@ var reconcileState = (root, slug, state) => {
 var deriveLegacyExecution = (root, slug, state) => {
   const ledger = ledgerCompletion(root, slug);
   if (state.plan.status === "approved" && state.menu.chosen === "subagent-driven" && ledger.started && !ledger.complete) {
-    return { status: "active", mode: "subagent-driven", evidence: null };
+    return {
+      status: "active",
+      mode: "subagent-driven",
+      evidence: null,
+      coordinator_session_id: null
+    };
   }
-  return { status: "pending", mode: null, evidence: null };
+  return { status: "pending", mode: null, evidence: null, coordinator_session_id: null };
 };
 var normalizeCompatibility = (root, slug, parsed, state) => {
   if (!isRecord3(parsed) || !("execution" in parsed)) {
@@ -47554,6 +47774,11 @@ var normalizeCompatibility = (root, slug, parsed, state) => {
     if (derived.status !== current.status || derived.mode !== current.mode) {
       return { state: { ...state, execution: derived, updated_at: Date.now() }, changed: true };
     }
+    return { state, changed: false };
+  }
+  const execRaw = isRecord3(parsed.execution) ? parsed.execution : undefined;
+  if (execRaw && !("coordinator_session_id" in execRaw)) {
+    return { state: { ...state, updated_at: Date.now() }, changed: true };
   }
   return { state, changed: false };
 };
@@ -47716,19 +47941,49 @@ var isNegativeLabel = (label) => {
     return firstWord.replace(/[^a-z]/g, "") === entry;
   });
 };
+var receiptPurposeForLabel = (label) => {
+  const n = normalizeLabel(label);
+  if (n === "approve spec" || n === "approve spec recommended")
+    return "spec-approval";
+  if (n === "approve plan" || n === "approve plan recommended")
+    return "plan-approval";
+  if (n === "approve")
+    return;
+  if (n === "pause plan")
+    return "plan-pause";
+  if (n === "resume plan")
+    return "plan-resume";
+  if (n === "complete plan")
+    return "plan-complete";
+  const exec3 = new Set([
+    "subagent driven",
+    "inline",
+    "handoff",
+    "review spec",
+    "review plan",
+    "change model"
+  ]);
+  if (exec3.has(n))
+    return "execution-menu";
+  return;
+};
 
 class HostReceiptStore {
   #bySession = new Map;
-  record(sessionId, callID, selectedLabel, recordedAt = Date.now(), question) {
-    const label = selectedLabel.trim();
-    if (!label)
+  record(sessionId, callID, selectedLabel, recordedAt = Date.now(), question = "", purpose) {
+    const trimmed = selectedLabel.trim();
+    if (!trimmed)
       return;
     if (recordedAt > Date.now() + MAX_CLOCK_SKEW_MS)
       return;
+    const derived = purpose ?? receiptPurposeForLabel(selectedLabel);
+    if (derived === undefined)
+      return;
+    const q = question ?? "";
     const queue = this.#bySession.get(sessionId) ?? [];
     if (queue.length >= MAX_RECEIPTS_PER_SESSION)
       queue.shift();
-    queue.push({ sessionId, callID, selectedLabel: label, recordedAt, question });
+    queue.push({ sessionId, callID, selectedLabel, recordedAt, question: q, purpose: derived });
     this.#bySession.set(sessionId, queue);
   }
   count(sessionId) {
@@ -47745,10 +48000,40 @@ class HostReceiptStore {
     if (!queue || queue.length === 0) {
       return err2("receipt_missing", "no host-observed native-question receipt for this session — ask the native " + "`question` tool and have the user answer before calling this tool");
     }
-    const index = queue.length - 1;
+    let index = -1;
+    if (opts.purpose !== undefined) {
+      const top = queue[queue.length - 1];
+      if (top && top.purpose === opts.purpose && isNegativeLabel(top.selectedLabel)) {
+        const filtered = queue.filter((r) => r.purpose !== opts.purpose);
+        if (filtered.length === 0)
+          this.#bySession.delete(sessionId);
+        else
+          this.#bySession.set(sessionId, filtered);
+        return err2("receipt_rejected", `the user's most recent answer (${JSON.stringify(top.selectedLabel)}) is a ` + "negative answer — it cannot authorize an approval; ask the native question again");
+      }
+      for (let i = queue.length - 1;i >= 0; i--) {
+        if (queue[i].purpose === opts.purpose) {
+          index = i;
+          break;
+        }
+      }
+      if (index === -1) {
+        return err2("receipt_missing", `no host-observed receipt for purpose ${JSON.stringify(opts.purpose)} — ask the native question for that purpose`);
+      }
+    } else {
+      index = queue.length - 1;
+    }
     const receipt = queue[index];
     if (isNegativeLabel(receipt.selectedLabel)) {
-      this.#bySession.delete(sessionId);
+      if (opts.purpose !== undefined) {
+        const filtered = queue.filter((r) => r.purpose !== opts.purpose);
+        if (filtered.length === 0)
+          this.#bySession.delete(sessionId);
+        else
+          this.#bySession.set(sessionId, filtered);
+      } else {
+        this.#bySession.delete(sessionId);
+      }
       return err2("receipt_rejected", `the user's most recent answer (${JSON.stringify(receipt.selectedLabel)}) is a ` + "negative answer — it cannot authorize an approval; ask the native question again");
     }
     if (opts.label !== undefined && !sameChoiceLabel(receipt.selectedLabel, opts.label)) {
@@ -47940,7 +48225,7 @@ var completeExecution = (root, slug, deps) => {
     }
     const next = {
       ...reconciled.state,
-      execution: { ...exec3, status: "completed" },
+      execution: { ...exec3, status: "completed", coordinator_session_id: null },
       handoff_destination: false,
       updated_at: Date.now()
     };
@@ -48000,6 +48285,38 @@ var slugFromPath = (p) => {
   const dirName = path18.basename(path18.dirname(p));
   return dirName === "." || dirName === "/" || dirName === "" ? "" : dirName;
 };
+var assertSddControlGates = (root, slug, opts = {}, ctx) => {
+  const bound = assertMutationWorkspace(root, ctx);
+  if (!bound.ok)
+    return bound;
+  const effective = readEffectiveFlowState(root, slug);
+  if (!effective.ok)
+    return effective;
+  const state = effective.state;
+  if (state.spec.status !== "approved") {
+    return err2("spec_not_approved", `spec not approved (status: ${state.spec.status}). Run workflow_spec_approve after the user's approval.`);
+  }
+  if (state.plan.status !== "approved") {
+    return err2("plan_not_approved", `plan not approved (status: ${state.plan.status}). Run workflow_plan_approve after the user's approval.`);
+  }
+  if (opts.requireMenu && !state.menu.presented) {
+    return err2("menu_not_presented", "post-plan menu not presented. Record the native question answer with workflow_plan_menu.");
+  }
+  if (opts.requireDocs) {
+    const validated = docsValidate({
+      spec_path: path18.posix.join("docs", slug, "spec.md"),
+      plan_path: path18.posix.join("docs", slug, "plan.md"),
+      workspace_root: root
+    });
+    if (validated.ok === false)
+      return err2("docs_invalid", validated.error);
+  }
+  if (state.execution.status === "active" && state.execution.mode === "subagent-driven" && roleFromParentage(ctx?.parentSessionId, state.execution.coordinator_session_id) === "delegated") {
+    return err2("sdd_control_denied", "SDD control metadata is coordinator-owned while a subagent-driven plan is active — delegated workers cannot mutate task briefs, review packages, progress, or advisories");
+  }
+  return { ok: true };
+};
+var roleFromParentage = (parentID, coordinatorSessionId) => typeof parentID === "string" && parentID !== "" && parentID === coordinatorSessionId ? "delegated" : "coordinator";
 var BASH_READ_TOKENS = new Set([
   "cat",
   "head",
@@ -48127,12 +48444,12 @@ var COORDINATOR_SHELL_DENIED_TEXT = "Coordinator shell commands are restricted w
 import path20 from "node:path";
 
 // packages/workit-core/src/core/handoff-context.ts
-import { existsSync as existsSync15, readFileSync as readFileSync14, readdirSync as readdirSync5, statSync as statSync8 } from "node:fs";
+import { existsSync as existsSync15, readFileSync as readFileSync14, readdirSync as readdirSync6, statSync as statSync8 } from "node:fs";
 import path19 from "node:path";
 var DOC_RE = /docs\/([A-Za-z0-9][A-Za-z0-9._-]*)\/(spec|plan)\.md/g;
 var listMd = (dir) => {
   try {
-    return readdirSync5(dir).filter((f) => f.endsWith(".md")).sort();
+    return readdirSync6(dir).filter((f) => f.endsWith(".md")).sort();
   } catch {
     return [];
   }
@@ -48158,7 +48475,7 @@ var resolveActivePair = (root) => {
   let best = null;
   let entries = [];
   try {
-    entries = readdirSync5(docsDir);
+    entries = readdirSync6(docsDir);
   } catch {
     return { error: "no pair" };
   }
@@ -48250,13 +48567,21 @@ var buildHandoffPrompt = (root, message) => {
 };
 
 // packages/workit-cli/src/flow.ts
-var FLOW_ACTIONS = ["status", "pause", "resume", "complete", "review-package"];
+var FLOW_ACTIONS = [
+  "status",
+  "pause",
+  "resume",
+  "complete",
+  "review-package",
+  "append-advisory"
+];
 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]",
+  "append-advisory": "workit flow append-advisory --plan <path> --task <id> --text <text> [--confirm]",
   handoff: "workit handoff --message <text>"
 };
 var FLOW_COMMANDS = {
@@ -48264,7 +48589,8 @@ var FLOW_COMMANDS = {
   pause: COMMANDS.pause,
   resume: COMMANDS.resume,
   complete: COMMANDS.complete,
-  "review-package": COMMANDS["review-package"]
+  "review-package": COMMANDS["review-package"],
+  "append-advisory": COMMANDS["append-advisory"]
 };
 var CLI_FLAG_EVIDENCE = { host: "cli", attested: false, confirmation: "flag" };
 var CLI_TTY_EVIDENCE = { host: "cli", attested: false, confirmation: "tty" };
@@ -48297,14 +48623,22 @@ var usage = (err3, text) => {
   write(err3, text);
   return 2;
 };
-var VALUE_FLAGS = ["--plan", "--base", "--head"];
+var VALUE_FLAGS = ["--plan", "--base", "--head", "--task", "--text"];
 function parseFlowFlags(action, argv, err3) {
   const parsed = {};
   let confirm = false;
   for (let i = 0;i < argv.length; i++) {
     const token = argv[i];
     if (VALUE_FLAGS.includes(token)) {
-      if (token !== "--plan" && action !== "review-package") {
+      if (token !== "--plan" && action !== "review-package" && action !== "append-advisory") {
+        usage(err3, `usage: ${FLOW_COMMANDS[action]} — unknown flag: ${token}`);
+        return { ok: false };
+      }
+      if ((token === "--base" || token === "--head") && action !== "review-package") {
+        usage(err3, `usage: ${FLOW_COMMANDS[action]} — unknown flag: ${token}`);
+        return { ok: false };
+      }
+      if ((token === "--task" || token === "--text") && action !== "append-advisory") {
         usage(err3, `usage: ${FLOW_COMMANDS[action]} — unknown flag: ${token}`);
         return { ok: false };
       }
@@ -48318,7 +48652,7 @@ function parseFlowFlags(action, argv, err3) {
         usage(err3, `usage: ${FLOW_COMMANDS[action]} — unknown flag: ${value}`);
         return { ok: false };
       }
-      const existing = token === "--plan" ? parsed.plan : token === "--base" ? parsed.base : parsed.head;
+      const existing = token === "--plan" ? parsed.plan : token === "--base" ? parsed.base : token === "--head" ? parsed.head : token === "--task" ? parsed.task : parsed.text;
       if (existing !== undefined) {
         usage(err3, `usage: ${FLOW_COMMANDS[action]} — duplicate ${token} flag`);
         return { ok: false };
@@ -48327,8 +48661,12 @@ function parseFlowFlags(action, argv, err3) {
         parsed.plan = value;
       else if (token === "--base")
         parsed.base = value;
-      else
+      else if (token === "--head")
         parsed.head = value;
+      else if (token === "--task")
+        parsed.task = value;
+      else
+        parsed.text = value;
       i += 1;
     } else if (token === "--confirm") {
       if (action === "status") {
@@ -48359,7 +48697,27 @@ function parseFlowFlags(action, argv, err3) {
       return { ok: false };
     }
   }
-  return { ok: true, parsed: { plan: parsed.plan, confirm, base: parsed.base, head: parsed.head } };
+  if (action === "append-advisory") {
+    if (parsed.task === undefined) {
+      usage(err3, `usage: ${FLOW_COMMANDS[action]} — --task <id> required`);
+      return { ok: false };
+    }
+    if (parsed.text === undefined) {
+      usage(err3, `usage: ${FLOW_COMMANDS[action]} — --text <text> required`);
+      return { ok: false };
+    }
+  }
+  return {
+    ok: true,
+    parsed: {
+      plan: parsed.plan,
+      confirm,
+      base: parsed.base,
+      head: parsed.head,
+      task: parsed.task,
+      text: parsed.text
+    }
+  };
 }
 async function resolveConfirmation(deps, confirmFlag, out, err3) {
   if (confirmFlag)
@@ -48435,12 +48793,34 @@ function reviewPackageCommand(root, parsed, out, err3) {
   }
   return domainFail(err3, result2.code ?? "review_package_failed", result2.error);
 }
+function appendAdvisoryCommand(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 slug = resolved.layout.slug;
+  const controlGate = assertSddControlGates(root, slug, { requireMenu: true, requireDocs: true });
+  if (!controlGate.ok)
+    return domainFail(err3, controlGate.code, controlGate.error);
+  const trimmed = parsed.task.trim();
+  const taskId = /^-?\d+(\.\d+)?$/.test(trimmed) ? Number(trimmed) : trimmed;
+  const result2 = sddAppendAdvisory({
+    advisories_path: path21.posix.join("docs", slug, "sdd", "advisories.md"),
+    task_id: taskId,
+    text: parsed.text,
+    workspace_root: root
+  });
+  if ("error" in result2) {
+    return domainFail(err3, result2.code ?? "advisory_failed", result2.error);
+  }
+  writeJSON(out, { ok: true, advisories_path: result2.advisories_path, advisory: result2.advisory });
+  return 0;
+}
 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|review-package> --plan <path> [--confirm]");
+    return usage(err3, "usage: workit flow <status|pause|resume|complete|review-package|append-advisory> --plan <path> [--confirm]");
   }
   const flowAction = action;
   const parsed = parseFlowFlags(flowAction, rest2, err3);
@@ -48456,6 +48836,9 @@ async function runFlowCommand(argv, deps = {}) {
   if (flowAction === "review-package") {
     return reviewPackageCommand(root, parsed.parsed, out, err3);
   }
+  if (flowAction === "append-advisory") {
+    return appendAdvisoryCommand(root, parsed.parsed, out, err3);
+  }
   return mutateCommand(root, parsed.parsed.plan, flowAction, evidence, deps, out, err3);
 }
 async function runHandoffCommand(argv, deps = {}) {
@@ -48494,6 +48877,7 @@ var COMMAND_DESCRIPTIONS = [
   [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["append-advisory"], "Append an advisory line to docs/<slug>/sdd/advisories.md"],
   [COMMANDS.handoff, "Emit the destination handoff prompt for a plan"]
 ];
 var helpColumn = Math.max(...COMMAND_DESCRIPTIONS.map(([cmd]) => cmd.length)) + 2;
@@ -48582,7 +48966,7 @@ function runDoctorCommand(args) {
   if (args.includes("--json")) {
     console.log(JSON.stringify(report, null, 2));
   } else {
-    console.log(`workit doctor — ${report.ok ? "healthy" : "problems found"} (offline)`);
+    console.log(`workit doctor — ${report.ok ? "healthy" : "problems found"} (${report.offline ? "offline" : "online"})`);
     for (const check2 of report.checks) {
       const mark = check2.status === "fail" ? "FAIL" : check2.status === "warn" ? "WARN" : "ok  ";
       console.log(`${mark} ${check2.id} — ${check2.detail}`);

package/package.json

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