@brainervirus/workit-cli 0.8.8 → 0.8.10

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,59 +7,61 @@ 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>
 
 ## Hard gates
 
 - The parent is coordinator-only: it does not edit product code or perform delegated exploration.
-- Never use a worktree. Branch changes are in-place through `workflow_branch_setup` on `feature/*` or `bugfix/*`; never commit on protected branches.
-- Working state, briefs, ledgers, and review diffs live only under gitignored `<SDD_DIR>` in `docs/<slug>/sdd/` and use `workflow_sdd_*` tools.
+- Never use a worktree. Branch changes are in-place through `workit_branch_setup` on `feature/*` or `bugfix/*`; never commit on protected branches.
+- Working state, briefs, ledgers, and review diffs live only under gitignored `<SDD_DIR>` in `docs/<slug>/sdd/` and use `workit_sdd_*` tools.
 - 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.
-- On Cursor, for every repository-scoped `workflow_*` call, pass the active Cursor workspace as `workspace_root`; never rely on the MCP process default.
+- 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 `workit_spec_approve` / `workit_plan_approve` / `workit_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 `workit_sdd_*` stays with the coordinator session.
+- On Cursor, for every repository-scoped `workit_*` 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.
 
 ## Flow gates (HARD)
 
 - `wk-implement` refuses to run unless the plan is `approved` (flow.json) and the post-plan menu was presented.
 - `wk-handoff` refuses to run unless both spec and plan are `approved`.
-- Sequence is enforced by tools: `workflow_spec_approve`, `workflow_plan_approve`, `workflow_plan_menu` — never skip a step (the spec/plan self-review runs automatically inside the transition; only the final approval asks for your confirmation).
+- Sequence is enforced by tools: `workit_spec_approve`, `workit_plan_approve`, `workit_plan_menu` — never skip a step (the spec/plan self-review runs automatically inside the transition; only the final approval asks for your confirmation).
 
 ## Setup
 
-0. Call `workflow_docs_validate` with the linked spec/plan paths. Hard-fail on any error before todos or branch setup.
-1. Call `workflow_sdd_context` with `<PLAN_PATH>` and initialize `todowrite` from returned tasks.
-2. Call `workflow_plan_tasks`; cache each top-level task's `section_text`.
+0. Call `workit_docs_validate` with the linked spec/plan paths. Hard-fail on any error before todos or branch setup.
+1. Call `workit_sdd_context` with `<PLAN_PATH>` and initialize `todowrite` from returned tasks.
+2. Call `workit_plan_tasks`; cache each top-level task's `section_text`.
 3. Mark IDs in `completed_task_ids` completed and never redispatch them.
-4. Call `workflow_resolve_branch`, then show the current branch, target branch, and stash behavior before any in-place checkout/setup mutation.
+4. Call `workit_resolve_branch`, then show the current branch, target branch, and stash behavior before any in-place checkout/setup mutation.
 5. Always use `question`: for a clean tree ask whether to proceed or cancel; for a dirty tree add the stash choice and describe what will be stashed.
-6. Call `workflow_branch_setup` with `confirmed: true` only after approval.
+6. Call `workit_branch_setup` with `confirmed: true` only after approval.
 
 ## Remaining-task loop
 
 For each top-level task absent from `completed_task_ids`:
 
 1. Mark it `in_progress` with `todowrite`.
-2. Create a working-state brief with `workflow_sdd_task_brief` and `confirmed: true`.
+2. Create a working-state brief with `workit_sdd_task_brief` and `confirmed: true`.
 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`.
+4. Create a working-state diff with `workit_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`.
-7. Append the validated ledger entry with `workflow_sdd_append_progress` and `confirmed: true`; mark the todo completed.
+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 `workit_sdd_append_advisory` (`--task <id> --text <text>`, `confirmed: true`) instead of an unrestricted file edit.
+7. Append the validated ledger entry with `workit_sdd_append_progress` and `confirmed: true`; mark the todo completed.
 
 ## Final gate
 
-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.
+Run a separate full-branch code review, then `workit_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 `workit_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 `workit_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`.
+**Mandatory:** end the run by calling `workit_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 `workit_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
 
@@ -68,4 +70,4 @@ Run a separate full-branch code review, then `workflow_verify`. Present the full
 ## Quality gate (HARD)
 
 - Specs/plans are written from `templates/spec-template.md` / `templates/plan-template.md`.
-- After `workflow_docs_validate`, surface `quality` findings (spec scan). Hard findings (missing required section, missing CA-XX) block task start unless the user explicitly waives them. Warnings are advisory.
+- After `workit_docs_validate`, surface `quality` findings (spec scan). Hard findings (missing required section, missing CA-XX) block task start unless the user explicitly waives them. Warnings are advisory.

package/assets/templates/plan-template.md

@@ -10,7 +10,7 @@
 ## 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`.
+- The final task ends execution with `workit_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/assets/templates/spec-template.md

@@ -16,13 +16,13 @@
 
 ## Architecture
 
-<!-- REQUIRED if this spec has flows or architecture: render a mermaid diagram (workflow_present_flow). -->
+<!-- REQUIRED if this spec has flows or architecture: render a mermaid diagram (workit_present_flow). -->
 ```mermaid
 flowchart TD
   A[Start] --> B[Step]
 ```
 
-<!-- REQUIRED if this spec touches UI: render an ASCII wireframe (workflow_present_ascii). -->
+<!-- REQUIRED if this spec touches UI: render an ASCII wireframe (workit_present_ascii). -->
 ```text
 ┌──────────────┐
 │ Header       │

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

@@ -27,31 +27,31 @@ Plans require:
 
 `bugfix/<slug>` is also valid. Never use `main`, `develop`, `master`, or `prod`. Use plain backtick paths. Top-level headings are exactly `### Task N: Title`; steps use `- [ ] **Step N:** ...`; task headings never appear inside fences.
 
-Before writing **Branch:** into a new spec or plan, call `workflow_docs_branch` and write the returned `branch` verbatim. When `action` is `keep`, use the current feature/bugfix branch. When `action` is `create_from_develop` or `create_from_base`, create the branch only through `workflow_branch_setup`; it uses the configured workspace/global target branch.
+Before writing **Branch:** into a new spec or plan, call `workit_docs_branch` and write the returned `branch` verbatim. When `action` is `keep`, use the current feature/bugfix branch. When `action` is `create_from_develop` or `create_from_base`, create the branch only through `workit_branch_setup`; it uses the configured workspace/global target branch.
 
 ## Execution and handoff
 
 - Implementation uses `wk-implement` and subagent-driven development, with native `todowrite` and `task`.
 - Commits use `wk-commit` after its native `question` confirmation.
-- Continuation uses `wk-handoff`, whose `workflow_handoff_session` creates and seeds the OpenCode session automatically.
-- Never use worktrees. Resolve the declared branch with `workflow_resolve_branch`, preview dirty-tree stash choices with `question`, and apply an approved in-place checkout through `workflow_branch_setup` 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.
-- Keep all SDD state under the gitignored `docs/<slug>/sdd/`; use `workflow_sdd_context` and the registered `workflow_sdd_*` tools.
-- After implementation, use `question` before an approved stash reapply through `workflow_branch_setup` with `confirmed: true`.
+- Continuation uses `wk-handoff`, whose `workit_handoff_session` creates and seeds the OpenCode session automatically.
+- Never use worktrees. Resolve the declared branch with `workit_resolve_branch`, preview dirty-tree stash choices with `question`, and apply an approved in-place checkout through `workit_branch_setup` 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 `workit_spec_approve` / `workit_plan_approve` / `workit_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.
+- Keep all SDD state under the gitignored `docs/<slug>/sdd/`; use `workit_sdd_context` and the registered `workit_sdd_*` tools.
+- After implementation, use `question` before an approved stash reapply through `workit_branch_setup` with `confirmed: true`.
 
 ## YouTrack content
 
-Chat follows the user's language. YouTrack task comments are Spanish (`es-CL`) and use `workflow_youtrack_draft` followed by reviewed `workflow_youtrack_post` with `confirmed: true`. Preserve the user's paragraph voice; do not inject commits, file paths, or robotic bullet reports.
+Chat follows the user's language. YouTrack task comments are Spanish (`es-CL`) and use `workit_youtrack_draft` followed by reviewed `workit_youtrack_post` with `confirmed: true`. Preserve the user's paragraph voice; do not inject commits, file paths, or robotic bullet reports.
 
 ## Final self-check
 
-Before handoff, call `workflow_docs_validate` on the linked spec/plan pair. Hard-fail on any error; never offer execution when validation fails.
+Before handoff, call `workit_docs_validate` on the linked spec/plan pair. Hard-fail on any error; never offer execution when validation fails.
 
 Before handoff, verify the saved spec path, plan path, declared branch, top-level task numbering, and workflow-managed SDD directory through the registered read-only workflow tools. Report structured failures; never infer success.
 
 ## Post-plan execution choice
 
-After saving a plan, call `workflow_docs_validate` on the spec/plan pair. On failure, stop and fix docs — do not offer execution.
+After saving a plan, call `workit_docs_validate` on the spec/plan pair. On failure, stop and fix docs — do not offer execution.
 
 On success, use native `question` / Cursor `AskQuestion` with exactly these options (no stay, no A/B/C prose duplicate):
 
@@ -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 `workit_plan_menu` and re-presents the menu on the next turn. Every other choice must call `workit_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

@@ -46436,6 +46436,7 @@ import {
   fsyncSync,
   mkdirSync as mkdirSync8,
   openSync,
+  readdirSync as readdirSync5,
   readFileSync as readFileSync13,
   renameSync as renameSync2,
   rmSync as rmSync2,
@@ -46982,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";
@@ -47370,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",
@@ -47503,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: {
@@ -47518,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()
@@ -47529,7 +47589,7 @@ var readFlowStrict = (root, slug) => {
   const file = flowPath(root, slug);
   const rel = path18.posix.join("docs", slug, "sdd", "flow.json");
   if (!existsSync14(file)) {
-    return err2("flow_not_activated", `flow not activated for ${slug} — run workflow_flow_status first`);
+    return err2("flow_not_activated", `flow not activated for ${slug} — run workit_flow_status first`);
   }
   let text;
   try {
@@ -47655,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()
 });
@@ -47698,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)) {
@@ -47709,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 };
 };
@@ -47871,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) {
@@ -47900,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)) {
@@ -48095,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()
     };
@@ -48155,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 workit_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 workit_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 workit_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",
@@ -48282,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 [];
   }
@@ -48313,7 +48475,7 @@ var resolveActivePair = (root) => {
   let best = null;
   let entries = [];
   try {
-    entries = readdirSync5(docsDir);
+    entries = readdirSync6(docsDir);
   } catch {
     return { error: "no pair" };
   }
@@ -48405,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 = {
@@ -48419,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" };
@@ -48452,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 };
       }
@@ -48473,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 };
@@ -48482,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") {
@@ -48514,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)
@@ -48590,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);
@@ -48611,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 = {}) {
@@ -48649,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;

package/package.json

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