chore: update version to 2.0.31 and enhance prompt templates

- Bump package version to 2.0.31 in package.json and package-lock.json.
- Refine the needs-bot-review prompt template for clearer instructions.
- Improve the ready prompt template to provide better guidance for implementation.
- Add normalization for todo comment body input to handle escaped newline sequences.
- Enhance error handling in release-utils.js for file removal.
- Implement SQLite workspace hydration logic in cockpitManager.ts to ensure proper task and board hydration.
- Introduce tests for new functionality, including SQLite hydration and comment normalization.

Co-authored-by: Copilot <copilot@github.com>

Author: goodguy1963

.github/skills/cockpit-scheduler-router/SKILL.md

@@ -5,7 +5,7 @@ copilotCockpitSkillType: operational
 copilotCockpitToolNamespaces: [cockpit, scheduler]
 copilotCockpitWorkflowIntents: [needs-bot-review, ready]
 copilotCockpitApprovalSensitive: true
-copilotCockpitPromptSummary: "Route through canonical workflow flags, preserve approval checkpoints, and verify linked scheduler state before changing live scheduled cards."
+copilotCockpitPromptSummary: "Route through canonical workflow flags, preserve approval checkpoints, verify linked scheduler state before changing live scheduled cards, and for needs-bot-review return plain text with short titled sections, bullets, and a compact recommendation."
 copilotCockpitReadyWorkflowFlags: [ready, ON-SCHEDULE-LIST]
 copilotCockpitCloseoutWorkflowFlags: [needs-user-review, FINAL-USER-CHECK]
 ---
@@ -58,6 +58,11 @@ This router skill is MCP-dependent. It must not attempt live routing or schedule
 - `ON-SCHEDULE-LIST` → manage the linked scheduler job lifecycle for live scheduled cards.
 - `needs-user-review` or `new` → keep the card active and route it for follow-up instead of scheduling immediately.
 
+For `needs-bot-review` comments intended for direct Todo writeback:
+
+- Return plain text with real line breaks, short titled sections, compact bullets, and a final `Recommendation:` block.
+- Do not emit JSON payloads or literal escaped newline sequences such as `\n`.
+
 ## Example Set Requests
 
 When the user asks for a demo/example set across surfaces, route it as separate artifacts instead of collapsing everything into scheduled tasks.
@@ -125,7 +130,8 @@ The current live dispatcher source contains two different `needs-bot-review` beh
 - If `scheduler_remove_task` or `scheduler_get_task` shows that the linked task is already gone, clear the Cockpit card's `taskId` instead of leaving a stale link behind.
 - Use flags for routing and review-state handoff. Keep the built-in `ON-SCHEDULE-LIST` flag when the card still represents a live scheduled item.
 - When implementation is complete but the user still needs to review the result, prefer an existing review-state flag such as `needs-user-review`, and move the card only if the requested review section actually exists.
-- Add one compact Cockpit comment that covers changes, validation, and remaining follow-up instead of scattering multiple status comments.
+- For ready-path execution closeout, always write back exactly one compact Todo comment covering implementation changes, validation, and remaining follow-up before or together with the workflow-state update.
+- Do not scatter multiple status comments for the same ready execution closeout.
 
 ## Suggested Update Format
 
@@ -155,4 +161,8 @@ Avoid output such as `Add flags: on-schedule-list, scheduled-task` because it mi
 
 ## Output Expectations
 
-Return only the compact execution summary requested by the dispatcher flow. Avoid board dumps and avoid re-deriving routing state from the full board payload when `cockpit_list_routing_cards` already gives the candidate set.
+Return only the compact execution summary requested by the dispatcher flow. Avoid board dumps and avoid re-deriving routing state from the full board payload when `cockpit_list_routing_cards` already gives the candidate set.
+
+When the flow asks for a direct Todo review comment, keep the output readable as pasted text: short titled sections, concise bullets, and one compact closing recommendation.
+
+When the flow is a ready execution closeout, include the single compact Todo comment needed for direct writeback so the Todo does not move state without a comment trail.

README.md

@@ -181,7 +181,9 @@ Start with one recurring loop that produces useful work instead of toy output.
 - `Delivery Risk and Security Watch (Daily)` looks for shipping, trust, and operational blind spots.
 - `Knowledge and Shipping Packager (Daily)` stages reusable docs, memory candidates, and release material for later curation.
 - `Project Intelligence and Delivery Prep` runs those steps in sequence and stops at a review checkpoint before anything turns into real execution.
-- `Onboarding Example Coverage Research` benchmarks whether the docs still explain Cockpit, Tasks, Jobs, and Research with explicit review checkpoints.
+- `Onboarding Example Coverage Research` starts with a Todo Cockpit intake item, uses Research to gather or benchmark onboarding evidence, and then promotes approved follow-up into Tasks or Jobs.
+
+Use that onboarding example when you want one concrete loop to demonstrate the product: start in Todo Cockpit, gather context with Research, promote approved work into Tasks or Jobs, and stop at a review checkpoint before autonomy expands.
 
 This is a good fit for a solo product, an internal tool, a small SaaS, or an actively maintained extension like this repo.
 

docs/feature-tour.md

@@ -94,6 +94,8 @@ Caption: Improve against a benchmark, not by guesswork.
 
 Research can also act as a collaborative discovery phase before implementation: gather web knowledge, review the findings with the user, refine the direction, and only then turn the result into scheduled execution.
 
+For onboarding, `Onboarding Example Coverage Research` shows the full loop in one pass: capture the gap in Todo Cockpit, use Research to benchmark the docs, promote approved fixes into Tasks or Jobs, and pause at a review checkpoint before broader autonomy.
+
 Best for: prompt or workflow improvement that should be measured, not guessed.
 
 ## Model And Agent Choice

docs/getting-started.md

@@ -39,6 +39,8 @@ Skip toy prompts. Start with one recurring loop that would still be worth keepin
 - For a company team, use the same pattern for product signals, security and release readiness, support queues, or operations follow-up.
 - If you also want to show the Research surface, add one benchmarked profile that scores onboarding or prompt quality against a simple command before you promote anything into execution.
 
+`Onboarding Example Coverage Research` is the simplest version of that pattern: log the onboarding gap in Todo Cockpit, use Research to gather examples or benchmark the docs, then turn the approved next step into Tasks for a direct doc pass or Jobs for a staged follow-up. Use it when you want a real onboarding loop that still stops at a review checkpoint before autonomy expands.
+
 That keeps the demo honest: the proof is useful output plus explicit review, not a claim that the system should run unchecked.
 
 ## Installation From Release

media/cockpitWebview.js

@@ -249,9 +249,11 @@ import { createSchedulerWebviewTransientState } from "./cockpitWebviewTransientS
   var editingTaskId = null;
   var selectedTodoId = null;
   var TODO_COMPLETION_CONFIRM_TIMEOUT_MS = 30000;
+  var READY_TODO_CREATE_PENDING_TIMEOUT_MS = 10000;
   var todoCompletionConfirmState = null;
   var todoCompletionConfirmTimer = null;
   var pendingGridTodoCompletions = {};
+  var pendingReadyTodoDraftCreates = {};
   var EDITOR_CREATE_SYMBOL = "+";
   var EDITOR_EDIT_SYMBOL = "\u2699";
   var boardRenderState = createBoardRenderState();
@@ -1816,16 +1818,132 @@ import { createSchedulerWebviewTransientState } from "./cockpitWebviewTransientS
     }) || null;
   }
 
+  function isOneTimeTask(task) {
+    return !!(
+      task && (task.oneTime === true || String(task.id || "").indexOf("exec-") === 0)
+    );
+  }
+
+  function normalizeTodoDraftMatchText(value) {
+    return String(value || "").trim().toLowerCase();
+  }
+
   function isTodoTaskDraft(task) {
     return !!(
       task &&
+      isOneTimeTask(task) &&
       Array.isArray(task.labels) &&
       task.labels.some(function (label) {
         return normalizeTodoLabelKey(label) === "from-todo-cockpit";
       })
     );
   }
 
+  function findTodoDraftTaskForTodo(todo) {
+    if (!todo || !Array.isArray(tasks)) {
+      return null;
+    }
+
+    var todoId = normalizeTodoDraftMatchText(todo.id);
+    var todoTitle = normalizeTodoDraftMatchText(todo.title);
+    var todoDescription = normalizeTodoDraftMatchText(todo.description);
+    var todoLabels = Array.isArray(todo.labels)
+      ? todo.labels.map(function (label) {
+        return normalizeTodoDraftMatchText(label);
+      }).filter(function (label) {
+        return label.length > 0;
+      })
+      : [];
+
+    return tasks.find(function (task) {
+      if (!isTodoTaskDraft(task)) {
+        return false;
+      }
+
+      var taskPrompt = normalizeTodoDraftMatchText(task.prompt);
+      if (todoId && taskPrompt.indexOf("todo id: " + todoId) >= 0) {
+        return true;
+      }
+
+      var taskName = normalizeTodoDraftMatchText(task.name);
+      if (!todoTitle || taskName !== todoTitle) {
+        return false;
+      }
+
+      var taskDescription = normalizeTodoDraftMatchText(task.description);
+      if (todoDescription && taskDescription !== todoDescription) {
+        return false;
+      }
+
+      return todoLabels.every(function (label) {
+        return Array.isArray(task.labels) && task.labels.some(function (entry) {
+          return normalizeTodoDraftMatchText(entry) === label;
+        });
+      });
+    }) || null;
+  }
+
+  function hasPendingReadyTodoDraftCreate(todoId) {
+    return !!(
+      todoId
+      && Object.prototype.hasOwnProperty.call(pendingReadyTodoDraftCreates, todoId)
+    );
+  }
+
+  function clearPendingReadyTodoDraftCreate(todoId, skipRender) {
+    if (!hasPendingReadyTodoDraftCreate(todoId)) {
+      return;
+    }
+    window.clearTimeout(pendingReadyTodoDraftCreates[todoId]);
+    delete pendingReadyTodoDraftCreates[todoId];
+    if (!skipRender) {
+      renderTaskList(tasks);
+    }
+  }
+
+  function startPendingReadyTodoDraftCreate(todoId) {
+    if (!todoId) {
+      return;
+    }
+    clearPendingReadyTodoDraftCreate(todoId, true);
+    pendingReadyTodoDraftCreates[todoId] = window.setTimeout(function () {
+      clearPendingReadyTodoDraftCreate(todoId);
+    }, READY_TODO_CREATE_PENDING_TIMEOUT_MS);
+    renderTaskList(tasks);
+  }
+
+  function reconcilePendingReadyTodoDraftCreates() {
+    var cardsById = {};
+    getAllTodoCards().forEach(function (todo) {
+      if (todo && todo.id) {
+        cardsById[todo.id] = todo;
+      }
+    });
+
+    Object.keys(pendingReadyTodoDraftCreates).forEach(function (todoId) {
+      var todo = cardsById[todoId];
+      if (!todo) {
+        clearPendingReadyTodoDraftCreate(todoId, true);
+        return;
+      }
+      if (todo.archived || isRecurringTodoSectionId(todo.sectionId)) {
+        clearPendingReadyTodoDraftCreate(todoId, true);
+        return;
+      }
+      if (getTodoWorkflowFlag(todo) !== "ready") {
+        clearPendingReadyTodoDraftCreate(todoId, true);
+        return;
+      }
+      if (todo.taskId && isTodoTaskDraft(getTaskById(todo.taskId))) {
+        clearPendingReadyTodoDraftCreate(todoId, true);
+        return;
+      }
+      if (findTodoDraftTaskForTodo(todo)) {
+        clearPendingReadyTodoDraftCreate(todoId, true);
+      }
+    });
+  }
+
   function getReadyTodoDraftCandidates() {
     var effectiveLabelFilter = activeLabelFilter;
     if (arguments.length > 0 && typeof arguments[0] === "string") {
@@ -1838,10 +1956,16 @@ import { createSchedulerWebviewTransientState } from "./cockpitWebviewTransientS
       if (getTodoWorkflowFlag(todo) !== "ready") {
         return false;
       }
+      if (hasPendingReadyTodoDraftCreate(todo.id || "")) {
+        return false;
+      }
       var linkedTask = todo.taskId ? getTaskById(todo.taskId) : null;
       if (linkedTask && isTodoTaskDraft(linkedTask)) {
         return false;
       }
+      if (findTodoDraftTaskForTodo(todo)) {
+        return false;
+      }
       if (effectiveLabelFilter) {
         return Array.isArray(todo.labels) && todo.labels.indexOf(effectiveLabelFilter) >= 0;
       }
@@ -3455,7 +3579,11 @@ syncTodoLabelSuggestions();
     return !!(
       card
       && !card.archived
-      && (workflowFlag === "ready" || workflowFlag === "final-user-check")
+      && (
+        workflowFlag === "ready"
+        || workflowFlag === "final-user-check"
+        || String(card.status || "").toLowerCase() === "ready"
+      )
     );
   }
 
@@ -6634,7 +6762,8 @@ syncTodoLabelSuggestions();
       if (taskList && taskList.contains(readyTodoCreateTarget)) {
         e.preventDefault();
         var readyTodoId = readyTodoCreateTarget.getAttribute("data-ready-todo-create");
-        if (readyTodoId) {
+        if (readyTodoId && !hasPendingReadyTodoDraftCreate(readyTodoId)) {
+          startPendingReadyTodoDraftCreate(readyTodoId);
           vscode.postMessage({ type: "createTaskFromTodo", todoId: readyTodoId });
         }
         return;
@@ -6846,26 +6975,26 @@ syncTodoLabelSuggestions();
 
     var manualSessionTasks = taskItems.filter(function (task) {
       if (!task) return false;
-      var isOneTime = task.oneTime === true || (task.id && task.id.indexOf("exec-") === 0);
+      var isOneTime = isOneTimeTask(task);
       return !isOneTime && !isJobTask(task) && task.manualSession === true;
     });
     var jobTasks = taskItems.filter(function (task) {
       return !!task && isJobTask(task);
     });
     var recurringTasks = taskItems.filter(function (task) {
       if (!task) return false;
-      var isOneTime = task.oneTime === true || (task.id && task.id.indexOf("exec-") === 0);
+      var isOneTime = isOneTimeTask(task);
       return !isOneTime && !isJobTask(task) && task.manualSession !== true;
     });
     var todoDraftTasks = taskItems.filter(function (task) {
       if (!task) return false;
-      var isOneTime = task.oneTime === true || (task.id && task.id.indexOf("exec-") === 0);
+      var isOneTime = isOneTimeTask(task);
       return isOneTime && !isJobTask(task) && isTodoTaskDraft(task) && task.enabled === false;
     });
     var readyTodoDraftCandidates = getReadyTodoDraftCandidates();
     var oneTimeTasks = taskItems.filter(function (task) {
       if (!task) return false;
-      var isOneTime = task.oneTime === true || (task.id && task.id.indexOf("exec-") === 0);
+      var isOneTime = isOneTimeTask(task);
       return isOneTime && !isJobTask(task) && (!isTodoTaskDraft(task) || task.enabled !== false);
     });
 
@@ -8860,6 +8989,7 @@ syncTodoLabelSuggestions();
       switch (messageType) {
         case "updateTasks":
           tasks = Array.isArray(message.tasks) ? message.tasks : [];
+          reconcilePendingReadyTodoDraftCreates();
           emitWebviewDebug("updateTasks", {
             taskCount: tasks.length,
             selectedTodoId: selectedTodoId || "",
@@ -8902,6 +9032,7 @@ syncTodoLabelSuggestions();
             }
           }
           reconcilePendingGridTodoCompletions(cockpitBoard.cards);
+          reconcilePendingReadyTodoDraftCreates();
           emitWebviewDebug("updateCockpitBoard", {
             sectionCount: Array.isArray(cockpitBoard.sections) ? cockpitBoard.sections.length : 0,
             cardCount: Array.isArray(cockpitBoard.cards) ? cockpitBoard.cards.length : 0,

media/cockpitWebviewBoardInteractions.js

@@ -149,7 +149,8 @@ export function handleBoardTodoCompletion(completeToggle, options) {
       }
     });
   }
-  var isReadyTodo = workflowFlag === "ready" || workflowFlag === "final-user-check";
+  var legacyReadyStatus = String((todoCard && todoCard.status) || "").trim().toLowerCase() === "ready";
+  var isReadyTodo = workflowFlag === "ready" || workflowFlag === "final-user-check" || legacyReadyStatus;
   var completionActionType = isReadyTodo ? "finalizeTodo" : "approveTodo";
 
   if (!todoId) {

media/generated/cockpitWebview.js

@@ -2,7 +2,7 @@
   "name": "copilot-cockpit",
   "displayName": "Copilot Cockpit",
   "description": "One VS Code system for AI planning and triage, execution and scheduling, and optional control-plane integration",
-  "version": "2.0.29",
+  "version": "2.0.31",
   "publisher": "local-dev",
   "license": "SEE LICENSE IN LICENSE",
   "icon": "images/icon.png",
@@ -248,7 +248,7 @@
         },
         "copilotCockpit.needsBotReviewPromptTemplate": {
           "type": "string",
-          "default": "You are handling a Todo that just entered needs-bot-review.\n\n{{todo_context}}\n\n{{mcp_skill_guidance}}\n\nResearch what is needed to review this item, identify missing context and risks, and return a plan-only response. If the request is clear, provide two concrete implementation options or one blocking clarification when the ambiguity is material.",
+          "default": "You are handling a Todo that just entered needs-bot-review.\n\n{{todo_context}}\n\n{{mcp_skill_guidance}}\n\nResearch what is needed to review this item using available tools and web search.\nReturn a plain-text review comment ready for direct Todo writeback with short titled sections and bullets:\nReview Summary:\n- 1-2 bullets on the request and current repo state\nRisks / Gaps:\n- bullets for missing context, risks, or unclear assumptions\nRecommendation:\n- one compact next step or blocking clarification; if the request is already clear, give two implementation options instead\nUse real line breaks. Do not emit JSON or escaped newline sequences such as \\n.\nWhen the review is complete, add that comment to this Todo using the cockpit MCP tools and set the flag to needs-user-review.",
           "scope": "resource",
           "description": "%config.needsBotReviewPromptTemplate%"
         },
@@ -280,7 +280,7 @@
         },
         "copilotCockpit.readyPromptTemplate": {
           "type": "string",
-          "default": "You are preparing the execution artifact for a Todo that is now ready.\n\n{{todo_context}}\n\n{{mcp_skill_guidance}}\n\nCreate or refine the execution-ready handoff for this Todo. Preserve the user's actual requested work, keep unresolved questions explicit, and prefer existing repo-local skills and MCP tools over ad-hoc file edits when those tools are available.",
+          "default": "You are handling a Todo that is now ready for implementation.\n\n{{todo_context}}\n\n{{mcp_skill_guidance}}\n\nAnalyze this Todo using the Todo Cockpit skill and implement what the user decided in the last comment or the latest bot recommendation.\nIf there is no recent user comment, proceed with the bot's recommendation.\nAdd one compact Todo comment covering implementation changes, validation, and any remaining follow-up before or as you update the Todo to the correct workflow state.\nCheck the cockpit-todo-agent and cockpit-scheduler-router skills to determine the correct post-implementation state, and tell the user whether that guidance was found.\nIf the expected post-implementation state is not documented in the skills, add it there so the next editable default flag in settings has clear guidance.",
           "scope": "resource",
           "description": "%config.readyPromptTemplate%"
         },