@brainervirus/workit-core 0.8.8 → 0.8.10

package/src/core/menu.ts

@@ -16,14 +16,16 @@ export const SOURCE_MENU_LABELS = [
   "Handoff",
   "Review spec first",
   "Review plan first",
+  "Change model first",
 ] as const;
 
-/** Display labels a marked destination presents — exactly four, no Handoff (CA-08). */
+/** Display labels a marked destination presents — exactly five, no Handoff (CA-08). */
 export const DESTINATION_MENU_LABELS = [
   "Subagent-driven",
   "Inline",
   "Review spec first",
   "Review plan first",
+  "Change model first",
 ] as const;
 
 /**

package/src/core/reminder.ts

@@ -15,7 +15,7 @@ export const 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.
+- Before the first \`workit_spec_approve\`/\`workit_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>`;
 
@@ -29,7 +29,7 @@ export const 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.
+- Before the first \`workit_spec_approve\`/\`workit_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>`;
@@ -51,6 +51,17 @@ export const SDD_REMINDER_TEXT = `<workflow-sdd-reminder>
 An approved plan is subagent-driven — execute it via \`wk-implement\` / \`task\` delegation. Never implement the approved plan inline in the main session.
 </workflow-sdd-reminder>`;
 
+/**
+ * Worker-only context (CA-16): an authorized direct child of the activating
+ * coordinator receives ONLY this compact contract — never the coordinator
+ * bootstrap or SDD_REMINDER_TEXT. It carries the worker duties (brief, TDD,
+ * commit range, report) and no coordination instructions.
+ */
+export const SDD_WORKER_REMINDER_TEXT = `<workflow-sdd-worker>
+You are an authorized delegated worker for an active subagent-driven plan.
+Execute only the supplied task brief: follow TDD (failing test first), land exactly one contiguous non-empty commit range for your task, then report status, commits, and test results to the coordinator. Do not manage coordinator bookkeeping or launch another agent harness.
+</workflow-sdd-worker>`;
+
 export const DOC_RENDER_TEXT = `<workflow-doc-render>
 When delivering a spec or plan, by default render the full markdown content of the doc in chat (headings, tables, mermaid fences preserved) — NOT a backtick-wrapped raw block.
 If the doc exceeds the render threshold (more than 150 lines, over 8KB, or more than 3 mermaid diagrams), deliver only the clickable link \`[spec.md](docs/<slug>/spec.md)\` + a 3-5 bullet summary.
@@ -67,7 +78,7 @@ A tool failed with a config-gap error (\`workflow config missing\`). Never confi
 </workflow-config-guard>`;
 
 export const VERIFICATION_TEXT = `<workflow-verification-rail>
-Skill: verification-before-completion. NO completion claims without fresh verification evidence — run the check command (e.g. \`bun run check\` / \`workflow_verify\`) and show its output before claiming done/fixed/passing. If you haven't run the verification command in this message, you cannot claim it passes.
+Skill: verification-before-completion. NO completion claims without fresh verification evidence — run the check command (e.g. \`bun run check\` / \`workit_verify\`) and show its output before claiming done/fixed/passing. If you haven't run the verification command in this message, you cannot claim it passes.
 </workflow-verification-rail>`;
 
 export const TDD_TEXT = `<workflow-tdd-rail>

package/src/core/repo-context.ts

@@ -330,7 +330,7 @@ const CHANGELOG_RULES = `- Use an [Unreleased] section.
 - Entries should be human-readable and user-facing.
 - Do not use raw commit messages as changelog bullets.
 - MERGE into existing ### Category under [Unreleased] — never append a second ### Added / ### Fixed block.
-- Apply with the native workflow_changelog_apply tool only (not hand-edits under Unreleased).
+- Apply with the native workit_changelog_apply tool only (not hand-edits under Unreleased).
 - If Unreleased already has duplicate category headings, normalize_only first.`;
 
 /** Port of changelog-context.sh — changelog update context. */

package/src/core/sdd.ts

@@ -183,7 +183,7 @@ export function sddContext({
     flow: { spec: flow.spec, plan: flow.plan, menu: flow.menu },
     todowrite_required: true,
     todowrite_hint:
-      "REQUIRED: Call OpenCode todowrite with todos from this result so the native task list shows progress. Before each task set status in_progress; after workflow_sdd_append_progress set it completed.",
+      "REQUIRED: Call OpenCode todowrite with todos from this result so the native task list shows progress. Before each task set status in_progress; after workit_sdd_append_progress set it completed.",
   };
 }
 
@@ -292,3 +292,62 @@ export function sddAppendProgress({
   const rel = posix(path.relative(contained.base, path_));
   return { ok: true, line: trimmed, progress_path: rel };
 }
+
+export type AdvisoryResult =
+  | { ok: true; advisory: string; advisories_path: string }
+  | { error: string; code: string };
+
+export function sddAppendAdvisory({
+  advisories_path,
+  task_id,
+  text,
+  workspace_root,
+}: {
+  advisories_path: string;
+  task_id: unknown;
+  text: unknown;
+  workspace_root: string;
+}): AdvisoryResult {
+  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("\n")) {
+    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 (existsSync(abs) && statSync(abs).isDirectory()) {
+    return {
+      error: `advisory target is a directory: ${advisories_path}`,
+      code: "advisory_target_invalid",
+    };
+  }
+  mkdirSync(path.dirname(abs), { recursive: true });
+  const line = `- Task ${task_id}: ${collapsed}\n`;
+  appendFileSync(abs, line, "utf8");
+  const rel = posix(path.relative(contained.base, abs));
+  return { ok: true, advisory: collapsed, advisories_path: rel };
+}

package/src/core/youtrack-tools.ts

@@ -102,7 +102,7 @@ type PostData = {
   loggedMinutes: number;
   outcome?: "unknown" | "not_applied";
   instructions?: string;
-  retry?: "workflow_youtrack_post" | "workflow_youtrack_log_time";
+  retry?: "workit_youtrack_post" | "workit_youtrack_log_time";
 };
 
 const notApplied = (value: LegacyValue): value is NotApplied =>
@@ -129,7 +129,7 @@ export async function postUpdate(
         postedComment: false,
         loggedMinutes: 0,
         outcome: "not_applied",
-        retry: "workflow_youtrack_post",
+        retry: "workit_youtrack_post",
       });
     unwrap(comment);
   } catch (error) {
@@ -156,7 +156,7 @@ export async function postUpdate(
           postedComment: true,
           loggedMinutes: 0,
           outcome: "not_applied",
-          retry: "workflow_youtrack_log_time",
+          retry: "workit_youtrack_log_time",
         });
       unwrap(time);
     } catch (error) {
@@ -189,7 +189,7 @@ export async function logTimeUpdate(
         issueId: input.issueId,
         loggedMinutes: 0,
         outcome: "not_applied",
-        retry: "workflow_youtrack_log_time",
+        retry: "workit_youtrack_log_time",
       });
     return ok(unwrap(value));
   } catch (error) {

package/src/core/youtrack.ts

@@ -711,7 +711,7 @@ export async function postUpdate(
         postedComment: true,
         loggedMinutes: 0,
         error: time.error,
-        retry: "workflow_youtrack_log_time",
+        retry: "workit_youtrack_log_time",
       };
     }
     return { ok: true, issueId, postedComment: true, loggedMinutes: minutes };

package/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/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/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/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/vendor/superpowers/skills/subagent-driven-development/SKILL.md

@@ -63,7 +63,7 @@ digraph process {
     "Read plan, note context and global constraints, create todos" [shape=box];
     "More tasks remain?" [shape=diamond];
     "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [shape=box];
-    "Run verification, then workflow_plan_complete once the ledger is complete and verification passes" [shape=box];
+    "Run verification, then workit_plan_complete once the ledger is complete and verification passes" [shape=box];
     "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
 
     "Read plan, note context and global constraints, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)";
@@ -79,12 +79,12 @@ digraph process {
     "Mark task complete in todo list and progress ledger" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
     "More tasks remain?" -> "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [label="no"];
-    "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Run verification, then workflow_plan_complete once the ledger is complete and verification passes";
-    "Run verification, then workflow_plan_complete once the ledger is complete and verification passes" -> "Use superpowers:finishing-a-development-branch";
+    "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Run verification, then workit_plan_complete once the ledger is complete and verification passes";
+    "Run verification, then workit_plan_complete once the ledger is complete and verification passes" -> "Use superpowers:finishing-a-development-branch";
 }
 ```
 
-**Mandatory completion:** after the final whole-branch review, run repository verification. Once the SDD ledger is complete and verification passes, end the run by calling `workflow_plan_complete` (or the CLI `workit flow complete`) — a complete ledger and green verification are the tool's gates. Never finish while the plan is still `active`.
+**Mandatory completion:** after the final whole-branch review, run repository verification. Once the SDD ledger is complete and verification passes, end the run by calling `workit_plan_complete` (or the CLI `workit flow complete`) — a complete ledger and green verification are the tool's gates. Never finish while the plan is still `active`.
 
 ## Pre-Flight Plan Review