@papi-ai/server 0.7.4-alpha.3 → 0.7.5

package/dist/index.js

@@ -10071,7 +10071,7 @@ Standard planning cycle with full board review.
    - **What to do with premature tasks:** Leave them in Backlog. Do NOT generate BUILD HANDOFFs for them. If a high-priority task fails the maturity gate due to phase prerequisites or dependencies, note it in the cycle log: "task-XXX deferred \u2014 Phase N prerequisites not met". Raw tasks are NOT premature \u2014 they just need scoping (see Task maturity above).
 
 7. **Recommendation** \u2014 Select tasks for this cycle:
-   **Pre-assigned tasks:** If a "Pre-Assigned Tasks" section is provided in the context below, those tasks are ALREADY committed to this cycle by the user. Include them automatically \u2014 do NOT re-evaluate whether they belong. Generate BUILD HANDOFFs for each. Count their effort toward the cycle budget. Then fill remaining slots (up to 5 total) from the backlog using the priority rules below.
+   **Pre-assigned tasks:** If a "Pre-Assigned Tasks" section is provided in the context below, those tasks are ALREADY committed to this cycle by the user. Include them automatically \u2014 do NOT re-evaluate whether they belong. Generate BUILD HANDOFFs for each. Count their effort toward the cycle budget. Then fill remaining slots from the backlog using the priority rules and cycle sizing rules below.
    **If USER DIRECTION is provided above:** Follow the user's stated focus. Pick the highest-impact task that aligns with their direction. The user knows what they need. Only deviate if a genuine P0 Critical fix exists (broken builds, data loss).
    **Otherwise, select by priority level then impact:**
    - **P0 Critical** \u2014 Broken, blocking, or data-loss risk. Always first.
@@ -10095,7 +10095,7 @@ Standard planning cycle with full board review.
 - **Backlog as steering wheel:** Task priority and notes in the backlog are the user's primary control mechanism over what gets planned. Respect the priority rankings and read task notes carefully \u2014 they contain user intent that shapes scope and scheduling.
 - **Planning quality is the bar:** Strategy review depth and plan quality set the standard for the product. Do not cut corners on analysis depth, triage thoroughness, or handoff specificity \u2014 these are what users experience as PAPI's value.
 
-10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for the recommended task and up to 4 additional high-priority unblocked tasks (5 total max). Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability. Remaining tasks will get handoffs in subsequent plans \u2014 do NOT try to cover the entire backlog.
+10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for every task selected for this cycle. Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability.
    **SKIP existing handoffs:** Tasks marked with "Has BUILD HANDOFF: yes" or "\u2713 handoff" on the board already have a valid handoff from a previous plan. Do NOT regenerate handoffs for these tasks \u2014 omit them from the \`cycleHandoffs\` array entirely. Only generate handoffs for tasks that do NOT have one yet. Exception: if a task's dependencies have been completed since its handoff was written, or a relevant Active Decision has changed, you MAY regenerate its handoff \u2014 but note this explicitly in the cycle log.
    **Scope pre-check:** Before writing the SCOPE section of each handoff, cross-reference the task against the "Recently Shipped Capabilities" section in the context below (if present). For each candidate task: (1) check if the task's title or scope overlaps with any recently shipped task, (2) check if the FILES LIKELY TOUCHED overlap with files already modified in recent builds, (3) check the architecture notes from recent builds for patterns that already cover this task's scope. If >80% of a task's scope appears in recently shipped capabilities, recommend cancellation via \`boardCorrections\` or reduce the handoff scope to only the missing pieces \u2014 explicitly note what already exists. C126 task-728 was over-scoped because the planner assumed Blocked status needed creating from scratch \u2014 it already existed in types, DB, orient, and build_list. Over-scoped handoffs waste builder time on verification and cause estimation mismatches.
    **Simplest Viable Path rule:** Before writing each BUILD HANDOFF, identify the simplest approach that satisfies the task's goal \u2014 the minimum change, fewest new abstractions, and smallest blast radius. Write the SCOPE (DO THIS) section for that simplest path FIRST. If you believe a more complex approach is warranted (new abstractions, multi-file refactors, framework changes), you MUST include a "WHY NOT SIMPLER" line in the handoff explaining why the simple path is insufficient. If you cannot articulate a concrete reason, use the simpler path. Pay special attention to tasks involving auth, data access, multi-user features, and infrastructure \u2014 these are the most common over-engineering targets.
@@ -10258,7 +10258,7 @@ Standard planning cycle with full board review.
    - **What to do with premature tasks:** Leave them in Backlog. Do NOT generate BUILD HANDOFFs for them. If a high-priority task fails the maturity gate due to phase prerequisites or dependencies, note it in the cycle log: "task-XXX deferred \u2014 Phase N prerequisites not met". Raw tasks are NOT premature \u2014 they just need scoping (see Task maturity above).
 
 7. **Recommendation** \u2014 Select tasks for this cycle:
-   **Pre-assigned tasks:** If a "Pre-Assigned Tasks" section is provided in the context below, those tasks are ALREADY committed to this cycle by the user. Include them automatically \u2014 do NOT re-evaluate whether they belong. Generate BUILD HANDOFFs for each. Count their effort toward the cycle budget. Then fill remaining slots (up to 5 total) from the backlog using the priority rules below.
+   **Pre-assigned tasks:** If a "Pre-Assigned Tasks" section is provided in the context below, those tasks are ALREADY committed to this cycle by the user. Include them automatically \u2014 do NOT re-evaluate whether they belong. Generate BUILD HANDOFFs for each. Count their effort toward the cycle budget. Then fill remaining slots from the backlog using the priority rules and cycle sizing rules below.
    **If USER DIRECTION is provided above:** Follow the user's stated focus. Pick the highest-impact task that aligns with their direction. The user knows what they need. Only deviate if a genuine P0 Critical fix exists (broken builds, data loss).
    **Otherwise, select by priority level then impact:**
    - **P0 Critical** \u2014 Broken, blocking, or data-loss risk. Always first.
@@ -10282,7 +10282,7 @@ Standard planning cycle with full board review.
 - **Backlog as steering wheel:** Task priority and notes in the backlog are the user's primary control mechanism over what gets planned. Respect the priority rankings and read task notes carefully \u2014 they contain user intent that shapes scope and scheduling.
 - **Planning quality is the bar:** Strategy review depth and plan quality set the standard for the product. Do not cut corners on analysis depth, triage thoroughness, or handoff specificity \u2014 these are what users experience as PAPI's value.
 
-10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for the recommended task and up to 4 additional high-priority unblocked tasks (5 total max). Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability. Remaining tasks will get handoffs in subsequent plans \u2014 do NOT try to cover the entire backlog.
+10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for every task selected for this cycle. Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability.
    **SKIP existing handoffs:** Tasks marked with "Has BUILD HANDOFF: yes" or "\u2713 handoff" on the board already have a valid handoff from a previous plan. Do NOT regenerate handoffs for these tasks \u2014 omit them from the \`cycleHandoffs\` array entirely. Only generate handoffs for tasks that do NOT have one yet. Exception: if a task's dependencies have been completed since its handoff was written, or a relevant Active Decision has changed, you MAY regenerate its handoff \u2014 but note this explicitly in the cycle log.
    **Scope pre-check:** Before writing the SCOPE section of each handoff, cross-reference the task against the "Recently Shipped Capabilities" section in the context below (if present). For each candidate task: (1) check if the task's title or scope overlaps with any recently shipped task, (2) check if the FILES LIKELY TOUCHED overlap with files already modified in recent builds, (3) check the architecture notes from recent builds for patterns that already cover this task's scope. If >80% of a task's scope appears in recently shipped capabilities, recommend cancellation via \`boardCorrections\` or reduce the handoff scope to only the missing pieces \u2014 explicitly note what already exists. C126 task-728 was over-scoped because the planner assumed Blocked status needed creating from scratch \u2014 it already existed in types, DB, orient, and build_list. Over-scoped handoffs waste builder time on verification and cause estimation mismatches.
    **Simplest Viable Path rule:** Before writing each BUILD HANDOFF, identify the simplest approach that satisfies the task's goal \u2014 the minimum change, fewest new abstractions, and smallest blast radius. Write the SCOPE (DO THIS) section for that simplest path FIRST. If you believe a more complex approach is warranted (new abstractions, multi-file refactors, framework changes), you MUST include a "WHY NOT SIMPLER" line in the handoff explaining why the simple path is insufficient. If you cannot articulate a concrete reason, use the simpler path. Pay special attention to tasks involving auth, data access, multi-user features, and infrastructure \u2014 these are the most common over-engineering targets.
@@ -10341,6 +10341,24 @@ function buildPlanUserMessage(ctx) {
     }) : PLAN_FULL_INSTRUCTIONS;
     parts.push(instructions);
   }
+  if (ctx.skipHandoffs) {
+    parts.push(
+      "",
+      "## SKIP HANDOFFS MODE",
+      "",
+      "**IMPORTANT OVERRIDE:** Do NOT generate BUILD HANDOFF blocks in this plan run.",
+      "Select tasks for the cycle using all the normal criteria (Steps 1-7), but SKIP Step 10 (BUILD HANDOFFs) entirely.",
+      "",
+      "In your Part 2 structured output:",
+      "- Set `cycleHandoffs` to an EMPTY array `[]`",
+      '- Add a `cycleTaskIds` array with the task IDs you selected for the cycle: `["task-123", "task-456", ...]`',
+      "- All other fields (cycleLogTitle, cycleLogContent, newTasks, boardCorrections, activeDecisions, etc.) work as normal.",
+      "",
+      "BUILD HANDOFFs will be generated separately via `handoff_generate` after this plan completes.",
+      "This reduces your cognitive load \u2014 focus on triage, selection, and board management only.",
+      ""
+    );
+  }
   parts.push("", "---", "", "## PROJECT CONTEXT", "");
   parts.push("### Product Brief", "", ctx.productBrief, "");
   if (ctx.northStar) {
@@ -10517,6 +10535,7 @@ function coerceStructuredOutput(parsed) {
     id: coerceToString(ad.id),
     body: coerceToString(ad.body)
   })) : [];
+  const cycleTaskIds = Array.isArray(parsed.cycleTaskIds) ? parsed.cycleTaskIds.map((id) => coerceToString(id)) : void 0;
   return {
     cycleLogTitle: coerceToString(parsed.cycleLogTitle),
     cycleLogContent: coerceToString(parsed.cycleLogContent),
@@ -10527,6 +10546,7 @@ function coerceStructuredOutput(parsed) {
     strategicDirection: coerceToString(parsed.strategicDirection),
     recommendedTaskId: parsed.recommendedTaskId === null ? null : coerceToString(parsed.recommendedTaskId),
     cycleHandoffs,
+    cycleTaskIds,
     newTasks,
     boardCorrections,
     productBrief: parsed.productBrief === null ? null : coerceToString(parsed.productBrief),
@@ -10824,6 +10844,9 @@ function buildReviewUserMessage(ctx) {
   if (ctx.taskComments) {
     parts.push("### Task Discussion (Recent Comments)", "", ctx.taskComments, "");
   }
+  if (ctx.docActionStaleness) {
+    parts.push("### Doc Action Staleness", "", ctx.docActionStaleness, "");
+  }
   return parts.join("\n");
 }
 function parseReviewStructuredOutput(raw) {
@@ -11268,6 +11291,8 @@ function buildPlanSlackSummary(cycleNumber, mode, data) {
       return `${h.taskId}: ${title}`;
     }).join(", ");
     parts.push(`*Recommended:* ${tasks}`);
+  } else if (data.cycleTaskIds && data.cycleTaskIds.length > 0) {
+    parts.push(`*Recommended:* ${data.cycleTaskIds.join(", ")} (handoffs pending)`);
   }
   if (data.strategicDirection) {
     parts.push(`*Direction:* ${data.strategicDirection}`);
@@ -11316,7 +11341,7 @@ function formatPreAssignedTasks(tasks, targetCycle) {
     "",
     ...lines,
     "",
-    "These tasks MUST be included in the cycle. Generate BUILD HANDOFFs for each. Fill remaining slots (up to 5 total) from the backlog."
+    "These tasks MUST be included in the cycle. Generate BUILD HANDOFFs for each. Fill remaining slots from the backlog based on cycle sizing rules."
   ].join("\n");
 }
 function pushAfterCommit(config2) {
@@ -11614,9 +11639,10 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
       adapter2.readCycleMetrics(),
       adapter2.getRecentReviews(5)
     ]);
+    let leanBuildReports = [];
     try {
-      const reports2 = await adapter2.getRecentBuildReports(50);
-      metricsSnapshots2 = computeSnapshotsFromBuildReports(reports2);
+      leanBuildReports = await adapter2.getRecentBuildReports(50);
+      metricsSnapshots2 = computeSnapshotsFromBuildReports(leanBuildReports);
     } catch {
     }
     timings["metricsAndReviews"] = t();
@@ -11645,7 +11671,7 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
       adapter2.searchDocs?.({ status: "active", limit: 5 }),
       adapter2.getCycleLog(5),
       adapter2.queryBoard({ status: ["Backlog", "In Cycle", "Ready"] }),
-      adapter2.getRecentBuildReports(10),
+      Promise.resolve(leanBuildReports.slice(0, 10)),
       adapter2.getContextHashes?.(health.totalCycles) ?? Promise.resolve(null)
     ]);
     timings["parallelReads"] = t();
@@ -11743,7 +11769,7 @@ ${lines.join("\n")}`;
     return { context: ctx2, contextHashes: newHashes2 };
   }
   t = startTimer();
-  const [decisions, reportsSinceCycle, log, tasks, rawMetricsSnapshots, reviews, phases, dogfoodEntries] = await Promise.all([
+  const [decisions, reportsSinceCycle, log, tasks, rawMetricsSnapshots, reviews, phases, dogfoodEntries, allBuildReports] = await Promise.all([
     adapter2.getActiveDecisions(),
     adapter2.getBuildReportsSince(health.totalCycles ?? 0),
     adapter2.getCycleLog(3),
@@ -11751,10 +11777,11 @@ ${lines.join("\n")}`;
     adapter2.readCycleMetrics(),
     adapter2.getRecentReviews(5),
     adapter2.readPhases(),
-    readDogfoodEntries(_config.projectRoot, 5, adapter2)
+    readDogfoodEntries(_config.projectRoot, 5, adapter2),
+    adapter2.getRecentBuildReports(50)
   ]);
   timings["fullQueries"] = t();
-  const reports = reportsSinceCycle.length > 0 ? reportsSinceCycle : await adapter2.getRecentBuildReports(5);
+  const reports = reportsSinceCycle.length > 0 ? reportsSinceCycle : allBuildReports.slice(0, 5);
   t = startTimer();
   const [
     allReportsResult,
@@ -11765,7 +11792,7 @@ ${lines.join("\n")}`;
     docsResultFull,
     contextHashesResultFull
   ] = await Promise.allSettled([
-    adapter2.getRecentBuildReports(50),
+    Promise.resolve(allBuildReports),
     detectReviewPatterns(reviews, health.totalCycles, 5),
     adapter2.getPendingRecommendations(),
     assembleDiscoveryCanvasText(adapter2),
@@ -11883,7 +11910,7 @@ ${cleanContent}`;
     }
     return { taskId: h.taskId, handoff: parsed };
   }).filter((h) => h.handoff != null);
-  const cycleTaskIds = (data.cycleHandoffs ?? []).map((h) => h.taskId);
+  const cycleTaskIds = data.cycleTaskIds?.length ? data.cycleTaskIds : (data.cycleHandoffs ?? []).map((h) => h.taskId);
   const cycle = {
     id: `cycle-${newCycleNumber}`,
     number: newCycleNumber,
@@ -11984,12 +12011,12 @@ ${cleanContent}`;
     if (!newCycle) {
       verifyWarnings.push(`Post-write verification FAILED: cycle ${newCycleNumber} entity not found after commit \u2014 data may not have persisted`);
     } else {
-      const expectedHandoffs = data.cycleHandoffs?.length ?? 0;
+      const expectedTaskCount = data.cycleTaskIds?.length ?? data.cycleHandoffs?.length ?? 0;
       const actualCycleTasks = boardTasks.filter((t) => t.cycle === newCycleNumber).length;
-      if (expectedHandoffs > 0 && actualCycleTasks === 0) {
-        verifyWarnings.push(`Post-write verification FAILED: cycle ${newCycleNumber} exists but has 0 tasks assigned (expected ${expectedHandoffs}) \u2014 task cycle assignment may have failed`);
-      } else if (expectedHandoffs > 0 && actualCycleTasks < expectedHandoffs) {
-        verifyWarnings.push(`Post-write verification WARNING: cycle ${newCycleNumber} has ${actualCycleTasks} tasks but expected ${expectedHandoffs} \u2014 some task assignments may have failed`);
+      if (expectedTaskCount > 0 && actualCycleTasks === 0) {
+        verifyWarnings.push(`Post-write verification FAILED: cycle ${newCycleNumber} exists but has 0 tasks assigned (expected ${expectedTaskCount}) \u2014 task cycle assignment may have failed`);
+      } else if (expectedTaskCount > 0 && actualCycleTasks < expectedTaskCount) {
+        verifyWarnings.push(`Post-write verification WARNING: cycle ${newCycleNumber} has ${actualCycleTasks} tasks but expected ${expectedTaskCount} \u2014 some task assignments may have failed`);
       }
     }
   } catch {
@@ -12000,7 +12027,7 @@ ${cleanContent}`;
   const correctionCount = data.boardCorrections?.length ?? 0;
   const newTaskCount = result.newTaskIdMap.size;
   const adCount = data.activeDecisions?.length ?? 0;
-  const taskIds = (data.cycleHandoffs ?? []).map((h) => result.newTaskIdMap.get(h.taskId) ?? h.taskId);
+  const taskIds = data.cycleTaskIds?.length ? data.cycleTaskIds.map((id) => result.newTaskIdMap.get(id) ?? id) : (data.cycleHandoffs ?? []).map((h) => result.newTaskIdMap.get(h.taskId) ?? h.taskId);
   return {
     priorityLockNotes: result.priorityLockNotes,
     newTaskIdMap: result.newTaskIdMap,
@@ -12042,15 +12069,7 @@ ${cleanContent}`;
     taskCount: cycleTaskCount > 0 ? cycleTaskCount : void 0,
     effortPoints: cycleEffortPoints > 0 ? cycleEffortPoints : void 0
   });
-  const healthPromise = adapter2.getCycleHealth().then(
-    (health) => adapter2.setCycleHealth({
-      totalCycles: newCycleNumber,
-      cyclesSinceLastStrategyReview: health.cyclesSinceLastStrategyReview + 1,
-      lastFullMode: newCycleNumber,
-      boardHealth: data.boardHealth,
-      strategicDirection: data.strategicDirection
-    })
-  );
+  const healthPromise = Promise.resolve();
   const newTaskIdMap = /* @__PURE__ */ new Map();
   const createTasksPromise = (async () => {
     if (!data.newTasks || data.newTasks.length === 0) return;
@@ -12241,7 +12260,7 @@ ${cleanContent}`;
   })();
   const cycleEntityPromise = (async () => {
     try {
-      const cycleTaskIds = (data.cycleHandoffs ?? []).map((h) => newTaskIdMap.get(h.taskId) ?? h.taskId);
+      const cycleTaskIds = data.cycleTaskIds?.length ? data.cycleTaskIds.map((id) => newTaskIdMap.get(id) ?? id) : (data.cycleHandoffs ?? []).map((h) => newTaskIdMap.get(h.taskId) ?? h.taskId);
       const cycle = {
         id: `cycle-${newCycleNumber}`,
         number: newCycleNumber,
@@ -12271,7 +12290,7 @@ ${cleanContent}`;
   const correctionCount = data.boardCorrections?.length ?? 0;
   const newTaskCount = newTaskIdMap.size;
   const adCount = data.activeDecisions?.length ?? 0;
-  const taskIds = (data.cycleHandoffs ?? []).map((h) => newTaskIdMap.get(h.taskId) ?? h.taskId);
+  const taskIds = data.cycleTaskIds?.length ? data.cycleTaskIds.map((id) => newTaskIdMap.get(id) ?? id) : (data.cycleHandoffs ?? []).map((h) => newTaskIdMap.get(h.taskId) ?? h.taskId);
   return {
     priorityLockNotes,
     newTaskIdMap,
@@ -12418,7 +12437,7 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
     writeSummary
   };
 }
-async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly) {
+async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs) {
   const prepareTimer = startTimer();
   let t = startTimer();
   const { mode, cycleNumber, strategyReviewWarning } = await validateAndPrepare(adapter2, force);
@@ -12468,6 +12487,7 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
   if (mode !== "bootstrap" && context.productBrief.includes(TEMPLATE_MARKER)) {
     throw new Error("TEMPLATE_BRIEF");
   }
+  if (skipHandoffs) context.skipHandoffs = true;
   t = startTimer();
   const userMessage = buildPlanUserMessage(context);
   const buildMessageMs = t();
@@ -12640,9 +12660,11 @@ async function propagatePhaseStatus(adapter2) {
 var lastPrepareContextHashes;
 var lastPrepareUserMessage;
 var lastPrepareContextBytes;
+var lastPrepareCycleNumber;
+var lastPrepareSkipHandoffs;
 var planTool = {
   name: "plan",
-  description: 'Run once per cycle to generate BUILD HANDOFFs for up to 5 tasks. Call after setup (first time) or after completing all builds AND running release for the previous cycle. Returns prioritised task recommendations with detailed implementation specs. NEVER call when unbuilt cycle tasks exist \u2014 build and release first. First call returns a planning prompt for you to execute (prepare phase). Then call again with mode "apply" and your output to write results.',
+  description: 'Run once per cycle to select tasks and generate BUILD HANDOFFs. Call after setup (first time) or after completing all builds AND running release for the previous cycle. Returns prioritised task recommendations with detailed implementation specs. NEVER call when unbuilt cycle tasks exist \u2014 build and release first. First call returns a planning prompt for you to execute (prepare phase). Then call again with mode "apply" and your output to write results. Use skip_handoffs=true for large backlogs \u2014 handoffs are then generated separately via `handoff_generate`.',
   inputSchema: {
     type: "object",
     properties: {
@@ -12695,6 +12717,10 @@ var planTool = {
       handoffs_only: {
         type: "boolean",
         description: "Skip backlog analysis and task selection. Only generate BUILD HANDOFFs for tasks already assigned to the target cycle. Requires pre-assigned tasks (set cycle number on tasks first). ~30% of normal plan cost."
+      },
+      skip_handoffs: {
+        type: "boolean",
+        description: "Run full planning (triage, task selection, board management) but skip BUILD HANDOFF generation. Selected tasks are assigned to the cycle without handoffs. Run `handoff_generate` after to create handoffs separately. Reduces planner cognitive load for large backlogs."
       }
     },
     required: []
@@ -12733,7 +12759,12 @@ function formatPlanResult(result) {
   if (result.priorityLockNote) lines.push(result.priorityLockNote.trim());
   if (result.slackWarning) lines.push(result.slackWarning);
   if (result.autoCommitNote) lines.push(result.autoCommitNote.trim());
-  lines.push("", `Next: run \`build_list\` to see your cycle tasks, then \`build_execute <task_id>\` to start building.`);
+  if (result.skipHandoffs) {
+    const taskCount = result.writeSummary?.taskIds.length ?? 0;
+    lines.push("", `Next: run \`handoff_generate\` to create BUILD HANDOFFs for your ${taskCount} cycle task(s), then \`build_list\` to start building.`);
+  } else {
+    lines.push("", `Next: run \`build_list\` to see your cycle tasks, then \`build_execute <task_id>\` to start building.`);
+  }
   if (result.contextBytes !== void 0) {
     const kb = (result.contextBytes / 1024).toFixed(1);
     lines.push(`---`, `Context: ${kb}KB`);
@@ -12766,10 +12797,20 @@ async function handlePlan(adapter2, config2, args) {
       const contextHashes = lastPrepareContextHashes;
       const inputContext = lastPrepareUserMessage;
       const contextBytes = lastPrepareContextBytes;
+      const expectedCycleNumber = lastPrepareCycleNumber;
+      const skipHandoffsCached = lastPrepareSkipHandoffs;
       lastPrepareContextHashes = void 0;
       lastPrepareUserMessage = void 0;
       lastPrepareContextBytes = void 0;
-      const result = await applyPlan(adapter2, config2, llmResponse, planMode, cycleNumber, strategyReviewWarning, contextHashes, { contextBytes: contextBytes ?? void 0 });
+      lastPrepareCycleNumber = void 0;
+      lastPrepareSkipHandoffs = void 0;
+      const skipHandoffs = args.skip_handoffs === true || skipHandoffsCached === true;
+      if (expectedCycleNumber !== void 0 && cycleNumber !== expectedCycleNumber) {
+        return errorResponse(
+          `cycle_number mismatch: prepare phase returned cycle ${expectedCycleNumber} but apply received ${cycleNumber}. Pass cycle_number: ${expectedCycleNumber} to match the prepare output.`
+        );
+      }
+      const result = await applyPlan(adapter2, config2, llmResponse, planMode, cycleNumber, strategyReviewWarning, contextHashes, { contextBytes: contextBytes ?? void 0, skipHandoffs: skipHandoffs || void 0 });
       let utilisation;
       if (inputContext) {
         try {
@@ -12777,7 +12818,7 @@ async function handlePlan(adapter2, config2, args) {
         } catch {
         }
       }
-      const response = formatPlanResult({ ...result, contextUtilisation: utilisation, contextBytes });
+      const response = formatPlanResult({ ...result, contextUtilisation: utilisation, contextBytes, skipHandoffs });
       return {
         ...response,
         ...contextBytes !== void 0 ? { _contextBytes: contextBytes } : {},
@@ -12789,10 +12830,13 @@ async function handlePlan(adapter2, config2, args) {
         await propagatePhaseStatus(adapter2);
       } catch {
       }
-      const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly);
+      const skipHandoffs = args.skip_handoffs === true;
+      const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs);
       lastPrepareContextHashes = result.contextHashes;
       lastPrepareUserMessage = result.userMessage;
       lastPrepareContextBytes = result.contextBytes;
+      lastPrepareCycleNumber = result.cycleNumber;
+      lastPrepareSkipHandoffs = skipHandoffs || void 0;
       const modeLabel = result.mode === "bootstrap" ? "Bootstrap" : "Full";
       const header = result.strategyReviewWarning ? `${result.strategyReviewWarning}
 ` : "";
@@ -13145,7 +13189,8 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     decisionUsage,
     recData,
     pendingRecs,
-    registeredDocs
+    registeredDocs,
+    docsWithPendingActions
   ] = await Promise.all([
     adapter2.readProductBrief(),
     adapter2.getActiveDecisions(),
@@ -13169,7 +13214,9 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     adapter2.getRecommendationEffectiveness?.()?.catch(() => []) ?? Promise.resolve([]),
     adapter2.getPendingRecommendations().catch(() => []),
     // Doc registry — summaries for strategy review context
-    adapter2.searchDocs?.({ status: "active", limit: 10 })?.catch(() => []) ?? Promise.resolve([])
+    adapter2.searchDocs?.({ status: "active", limit: 10 })?.catch(() => []) ?? Promise.resolve([]),
+    // Doc registry — docs with pending actions for staleness audit
+    adapter2.searchDocs?.({ hasPendingActions: true, limit: 20 })?.catch(() => []) ?? Promise.resolve([])
   ]);
   const tasks = [...activeTasks, ...recentDoneTasks];
   const existingAdIds = new Set(decisions.map((d) => d.id));
@@ -13371,6 +13418,44 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
     }
   } catch {
   }
+  let docActionStalenessText;
+  try {
+    if (docsWithPendingActions && docsWithPendingActions.length > 0) {
+      const STALE_THRESHOLD = 20;
+      const doneTaskIds = new Set(recentDoneTasks.map((t) => t.displayId ?? t.id));
+      const completed = [];
+      const deferred = [];
+      const stale = [];
+      for (const doc of docsWithPendingActions) {
+        const pendingActions = (doc.actions ?? []).filter((a) => a.status === "pending");
+        if (pendingActions.length === 0) continue;
+        const ageInCycles = cycleNumber - (doc.cycleCreated ?? cycleNumber);
+        for (const action of pendingActions) {
+          const line = `  - **${doc.title}** (C${doc.cycleCreated ?? "?"}): ${action.description}${action.linkedTaskId ? ` [\u2192${action.linkedTaskId}]` : ""}`;
+          if (action.linkedTaskId && doneTaskIds.has(action.linkedTaskId)) {
+            completed.push(line);
+          } else if (ageInCycles > STALE_THRESHOLD) {
+            stale.push(line);
+          } else {
+            deferred.push(line);
+          }
+        }
+      }
+      if (completed.length === 0 && deferred.length === 0 && stale.length === 0) {
+        docActionStalenessText = "Doc Actions: all clear \u2014 no pending actions.";
+      } else {
+        const sections = [];
+        if (stale.length > 0) sections.push(`**Stale (>${STALE_THRESHOLD} cycles, no matching Done task):**
+${stale.join("\n")}`);
+        if (completed.length > 0) sections.push(`**Completed but not closed (linked task is Done):**
+${completed.join("\n")}`);
+        if (deferred.length > 0) sections.push(`**Deferred (<${STALE_THRESHOLD} cycles, no matching Done task):**
+${deferred.join("\n")}`);
+        docActionStalenessText = sections.join("\n\n");
+      }
+    }
+  } catch {
+  }
   logDataSourceSummary("strategy_review_audit", [
     { label: "discoveryCanvas", hasData: discoveryCanvasText !== void 0 },
     { label: "briefImplications", hasData: briefImplicationsText !== void 0 },
@@ -13382,7 +13467,8 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
     { label: "registeredDocs", hasData: registeredDocsText !== void 0 },
     { label: "recentPlans", hasData: recentPlansText !== void 0 },
     { label: "unregisteredDocs", hasData: unregisteredDocsText !== void 0 },
-    { label: "taskComments", hasData: taskCommentsText !== void 0 }
+    { label: "taskComments", hasData: taskCommentsText !== void 0 },
+    { label: "docActionStaleness", hasData: docActionStalenessText !== void 0 }
   ]);
   const context = {
     sessionNumber: cycleNumber,
@@ -13408,7 +13494,8 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
     registeredDocs: registeredDocsText,
     recentPlans: recentPlansText,
     unregisteredDocs: unregisteredDocsText,
-    taskComments: taskCommentsText
+    taskComments: taskCommentsText,
+    docActionStaleness: docActionStalenessText
   };
   const BUDGET_SOFT2 = 5e4;
   const BUDGET_HARD2 = 6e4;
@@ -14514,8 +14601,8 @@ async function viewBoard(adapter2, phaseFilter, options) {
     const bi = PRIORITY_ORDER.indexOf(b2.priority);
     const priorityDiff = (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi);
     if (priorityDiff !== 0) return priorityDiff;
-    const aDate = a.createdAt ?? "";
-    const bDate = b2.createdAt ?? "";
+    const aDate = a.createdAt ? String(a.createdAt) : "";
+    const bDate = b2.createdAt ? String(b2.createdAt) : "";
     return bDate.localeCompare(aDate);
   });
   const total = allTasks.length;
@@ -15694,6 +15781,7 @@ async function ensurePapiPermission(projectRoot) {
   }
 }
 async function applySetupOutputs(adapter2, config2, input, briefText, adSeedText, conventionsText) {
+  const warnings = [];
   if (config2.adapterType !== "pg") {
     await writeFile2(join4(config2.papiDir, "PRODUCT_BRIEF.md"), briefText, "utf-8");
   }
@@ -15701,6 +15789,10 @@ async function applySetupOutputs(adapter2, config2, input, briefText, adSeedText
   const briefPhases = parsePhases(briefText);
   if (briefPhases.length > 0) {
     await adapter2.writePhases(briefPhases);
+  } else {
+    warnings.push(
+      "Phase parsing produced 0 phases \u2014 the brief may be missing a valid <!-- PHASES:START --> ... <!-- PHASES:END --> block. Run `plan` and the planner will infer phases from your description. To fix: re-run `setup` with a brief that includes a PHASES YAML block."
+    );
   }
   try {
     if (adapter2.createHorizon && adapter2.createStage && adapter2.linkPhasesToStage) {
@@ -15739,7 +15831,19 @@ async function applySetupOutputs(adapter2, config2, input, briefText, adSeedText
           }
         }
       }
-    } catch {
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warnings.push(
+        `AD seeding failed \u2014 active decisions were not created. Check that your ad_seed_response is valid JSON. Error: ${msg}`
+      );
+      seededAds = 0;
+    }
+    if (seededAds === 0 && adSeedText) {
+      if (!warnings.some((w) => w.startsWith("AD seeding failed"))) {
+        warnings.push(
+          "AD seeding produced 0 active decisions \u2014 the JSON may be valid but empty or missing required `id` and `body` fields."
+        );
+      }
     }
   }
   if (conventionsText?.trim()) {
@@ -15750,7 +15854,7 @@ async function applySetupOutputs(adapter2, config2, input, briefText, adSeedText
     } catch {
     }
   }
-  return { seededAds };
+  return { seededAds, warnings };
 }
 var SKIP_PATTERNS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -15988,7 +16092,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
   if (!briefText.trim()) {
     throw new Error("brief_response is required and cannot be empty.");
   }
-  const { seededAds } = await applySetupOutputs(adapter2, config2, input, briefText, adSeedText, conventionsText);
+  const { seededAds, warnings } = await applySetupOutputs(adapter2, config2, input, briefText, adSeedText, conventionsText);
   let createdTasks = 0;
   if (initialTasksText?.trim()) {
     try {
@@ -16073,7 +16177,8 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     projectName: input.projectName,
     seededAds,
     createdTasks,
-    cursorScaffolded
+    cursorScaffolded,
+    warnings: warnings.length > 0 ? warnings : void 0
   };
 }
 
@@ -16182,8 +16287,12 @@ ${result.seededAds} Active Decision${result.seededAds > 1 ? "s" : ""} seeded bas
 ${result.createdTasks} initial backlog task${result.createdTasks > 1 ? "s" : ""} created from codebase analysis.` : "";
   const constraintsHint = !constraints ? '\n\nTip: consider adding `constraints` (e.g. "must use PostgreSQL", "HIPAA compliant", "offline-first") to improve Active Decision seeding.' : "";
   const editorNote = result.cursorScaffolded ? "\n\nCursor detected \u2014 `.cursor/rules/papi.mdc` scaffolded alongside CLAUDE.md." : "";
+  const warningsNote = result.warnings && result.warnings.length > 0 ? `
+
+\u26A0\uFE0F **Setup warnings (non-blocking):**
+${result.warnings.map((w) => `- ${w}`).join("\n")}` : "";
   return textResponse(
-    `${prefix}Product Brief generated and saved.${adNote}${taskNote}${constraintsHint}${editorNote}
+    `${prefix}Product Brief generated and saved.${adNote}${taskNote}${constraintsHint}${editorNote}${warningsNote}
 
 **Important:** Setup created/modified files (CLAUDE.md, .claude/settings.json, docs/). Commit these changes before running \`build_execute\` \u2014 it requires a clean working directory.
 
@@ -20995,6 +21104,217 @@ Check that the project IDs are correct and exist in the same Supabase instance.`
   return textResponse(lines.join("\n"));
 }
 
+// src/services/handoff.ts
+init_dist2();
+async function prepareHandoffs(adapter2, _config, taskIds) {
+  const timer2 = startTimer();
+  const cycles = await adapter2.readCycles();
+  const activeCycle = cycles.find((c) => c.status === "active");
+  if (!activeCycle) {
+    throw new Error("No active cycle found. Run `plan` first to create a cycle.");
+  }
+  const cycleNumber = activeCycle.number;
+  const allTasks = await adapter2.queryBoard({ status: ["Backlog", "In Cycle", "Ready", "In Progress"] });
+  let cycleTasks = allTasks.filter((t) => t.cycle === cycleNumber);
+  if (taskIds?.length) {
+    const idSet = new Set(taskIds);
+    cycleTasks = cycleTasks.filter((t) => idSet.has(t.id));
+  }
+  const tasksNeedingHandoffs = cycleTasks.filter((t) => !t.buildHandoff);
+  if (tasksNeedingHandoffs.length === 0) {
+    throw new Error(
+      taskIds?.length ? `All specified tasks already have BUILD HANDOFFs. Nothing to generate.` : `All ${cycleTasks.length} cycle task(s) already have BUILD HANDOFFs. Nothing to generate.`
+    );
+  }
+  const [decisions, reports, brief] = await Promise.all([
+    adapter2.getActiveDecisions(),
+    adapter2.getRecentBuildReports(10),
+    adapter2.readProductBrief()
+  ]);
+  const northStar = await adapter2.getCurrentNorthStar?.() ?? "";
+  const userMessage = buildHandoffsOnlyUserMessage({
+    cycleNumber: cycleNumber - 1,
+    // buildHandoffsOnlyUserMessage adds +1 internally
+    preAssignedTasks: tasksNeedingHandoffs,
+    activeDecisions: formatActiveDecisionsForPlan(decisions),
+    recentBuildReports: formatBuildReports(reports),
+    productBrief: brief,
+    northStar
+  });
+  const contextBytes = Buffer.byteLength(userMessage, "utf-8");
+  const elapsed = timer2();
+  console.error(`[handoff-perf] prepareHandoffs: ${elapsed}ms, ${contextBytes} bytes, ${tasksNeedingHandoffs.length} task(s)`);
+  const systemPrompt = await getPrompt("plan-system");
+  return {
+    cycleNumber,
+    systemPrompt,
+    userMessage,
+    contextBytes,
+    taskCount: tasksNeedingHandoffs.length
+  };
+}
+async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber) {
+  const timer2 = startTimer();
+  const { data } = parseStructuredOutput(rawLlmOutput);
+  if (!data) {
+    throw new Error("Could not parse structured output. Ensure your output includes <!-- PAPI_STRUCTURED_OUTPUT --> with valid JSON.");
+  }
+  const handoffs = data.cycleHandoffs ?? [];
+  if (handoffs.length === 0) {
+    throw new Error("No cycleHandoffs found in structured output. Ensure your output includes handoffs in the cycleHandoffs array.");
+  }
+  const taskIdsToWrite = handoffs.map((h) => h.taskId);
+  const existingHandoffSet = /* @__PURE__ */ new Set();
+  try {
+    const tasks = await adapter2.getTasks(taskIdsToWrite);
+    for (const t of tasks) {
+      if (t.buildHandoff) existingHandoffSet.add(t.id);
+    }
+  } catch {
+  }
+  const written = [];
+  let skipped = 0;
+  const warnings = [];
+  for (const handoff of handoffs) {
+    try {
+      if (existingHandoffSet.has(handoff.taskId)) {
+        console.error(`[handoff] skipping ${handoff.taskId} \u2014 already has handoff`);
+        skipped++;
+        continue;
+      }
+      const parsed = parseBuildHandoff(handoff.buildHandoff);
+      if (!parsed) {
+        warnings.push(`Failed to parse handoff for ${handoff.taskId}`);
+        continue;
+      }
+      if (!parsed.createdAt) {
+        parsed.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+      }
+      await adapter2.updateTask(handoff.taskId, { buildHandoff: parsed });
+      written.push(handoff.taskId);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warnings.push(`Failed to write handoff for ${handoff.taskId}: ${msg}`);
+    }
+  }
+  const elapsed = timer2();
+  console.error(`[handoff-perf] applyHandoffs: ${elapsed}ms, ${written.length} written, ${skipped} skipped`);
+  return {
+    cycleNumber,
+    handoffsWritten: written.length,
+    skipped,
+    taskIds: written,
+    warnings
+  };
+}
+
+// src/tools/handoff.ts
+var lastPrepareCycleNumber2;
+var lastPrepareContextBytes2;
+var handoffGenerateTool = {
+  name: "handoff_generate",
+  description: "Generate BUILD HANDOFFs for cycle tasks that don't have one yet. Run after `plan` (with skip_handoffs=true) or to regenerate stale handoffs. Uses the prepare/apply pattern \u2014 first call returns a prompt, second call persists results.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      mode: {
+        type: "string",
+        enum: ["prepare", "apply"],
+        description: '"prepare" returns the handoff prompt for you to execute. "apply" accepts your generated output and persists handoffs. Defaults to "prepare" when omitted.'
+      },
+      task_ids: {
+        type: "array",
+        items: { type: "string" },
+        description: "Specific task IDs to generate handoffs for. If omitted, generates for all cycle tasks missing handoffs."
+      },
+      llm_response: {
+        type: "string",
+        description: 'Your raw output from executing the handoff prompt (mode "apply" only). Must include both Part 1 (markdown) and Part 2 (structured JSON after <!-- PAPI_STRUCTURED_OUTPUT -->).'
+      },
+      cycle_number: {
+        type: "number",
+        description: 'The cycle number returned from prepare phase (mode "apply" only).'
+      }
+    },
+    required: []
+  }
+};
+async function handleHandoffGenerate(adapter2, config2, args) {
+  const toolMode = args.mode;
+  try {
+    if (toolMode === "apply") {
+      const llmResponse = args.llm_response;
+      if (!llmResponse || !llmResponse.trim()) {
+        return errorResponse('llm_response is required for mode "apply". Pass your complete handoff output including the <!-- PAPI_STRUCTURED_OUTPUT --> block.');
+      }
+      const cycleNumber = typeof args.cycle_number === "number" ? args.cycle_number : lastPrepareCycleNumber2;
+      if (cycleNumber === void 0) {
+        return errorResponse('cycle_number is required for mode "apply". Pass the cycle number from the prepare phase.');
+      }
+      const expectedCycleNumber = lastPrepareCycleNumber2;
+      const contextBytes = lastPrepareContextBytes2;
+      lastPrepareCycleNumber2 = void 0;
+      lastPrepareContextBytes2 = void 0;
+      if (expectedCycleNumber !== void 0 && cycleNumber !== expectedCycleNumber) {
+        return errorResponse(
+          `cycle_number mismatch: prepare phase returned cycle ${expectedCycleNumber} but apply received ${cycleNumber}.`
+        );
+      }
+      const result = await applyHandoffs(adapter2, llmResponse, cycleNumber);
+      const lines = [];
+      lines.push(`**Handoff Generation \u2014 Cycle ${result.cycleNumber}**`);
+      lines.push(`${result.handoffsWritten} handoff(s) written: ${result.taskIds.join(", ")}`);
+      if (result.skipped > 0) lines.push(`${result.skipped} task(s) skipped (already had handoffs)`);
+      if (result.warnings.length > 0) lines.push("\u26A0\uFE0F Warnings: " + result.warnings.join("; "));
+      lines.push("", "Next: run `build_list` to see your cycle tasks, then `build_execute <task_id>` to start building.");
+      if (contextBytes !== void 0) {
+        const kb = (contextBytes / 1024).toFixed(1);
+        lines.push("---", `Context: ${kb}KB`);
+      }
+      return textResponse(lines.join("\n"));
+    }
+    {
+      const taskIds = Array.isArray(args.task_ids) ? args.task_ids.filter((id) => typeof id === "string") : void 0;
+      const result = await prepareHandoffs(adapter2, config2, taskIds);
+      lastPrepareCycleNumber2 = result.cycleNumber;
+      lastPrepareContextBytes2 = result.contextBytes;
+      return textResponse(
+        `## PAPI Handoff Generation \u2014 Prepare Phase (Cycle ${result.cycleNumber})
+
+Generate BUILD HANDOFFs for ${result.taskCount} task(s) that need them.
+
+**IMPORTANT:** Your output must have TWO parts:
+1. Natural language markdown with BUILD HANDOFF blocks
+2. After \`<!-- PAPI_STRUCTURED_OUTPUT -->\`, a JSON block with structured data
+
+When done, call \`handoff_generate\` again with:
+- \`mode\`: "apply"
+- \`llm_response\`: your complete output (both parts)
+- \`cycle_number\`: ${result.cycleNumber}
+
+---
+
+### System Prompt
+
+<system_prompt>
+${result.systemPrompt}
+</system_prompt>
+
+---
+
+### Context
+
+<context>
+${result.userMessage}
+</context>`
+      );
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return errorResponse(message);
+  }
+}
+
 // src/lib/telemetry.ts
 var TELEMETRY_SUPABASE_URL = "https://guewgygcpcmrcoppihzx.supabase.co";
 var TELEMETRY_API_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imd1ZXdneWdjcGNtcmNvcHBpaHp4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI2Njk2NTMsImV4cCI6MjA4ODI0NTY1M30.V5Jw7wJgiMpSQPa2mt0ftjyye5ynG1qLlam00yPVNJY";
@@ -21062,7 +21382,8 @@ var TOOLS_REQUIRING_PAPI = /* @__PURE__ */ new Set([
   "review_submit",
   "orient",
   "hierarchy_update",
-  "zoom_out"
+  "zoom_out",
+  "handoff_generate"
 ]);
 function createServer(adapter2, config2) {
   const server2 = new Server(
@@ -21148,7 +21469,8 @@ function createServer(adapter2, config2) {
       docRegisterTool,
       docSearchTool,
       docScanTool,
-      getSiblingAdsTool
+      getSiblingAdsTool,
+      handoffGenerateTool
     ]
   }));
   server2.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -21264,6 +21586,9 @@ function createServer(adapter2, config2) {
       case "get_sibling_ads":
         result = await handleGetSiblingAds(adapter2, safeArgs);
         break;
+      case "handoff_generate":
+        result = await handleHandoffGenerate(adapter2, config2, safeArgs);
+        break;
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
     }
@@ -21389,5 +21714,28 @@ If you already have an account, check that both **PAPI_PROJECT_ID** and **PAPI_D
     }]
   }));
 }
+if (pkgVersion !== "unknown") {
+  (async () => {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 3e3);
+      const res = await fetch("https://registry.npmjs.org/@papi-ai/server/latest", {
+        signal: controller.signal
+      });
+      clearTimeout(timeout);
+      if (res.ok) {
+        const data = await res.json();
+        const latest = data.version;
+        if (latest && latest !== pkgVersion) {
+          process.stderr.write(
+            `\u26A0 Update available: ${pkgVersion} \u2192 ${latest}. Run: npx @papi-ai/server@latest
+`
+          );
+        }
+      }
+    } catch {
+    }
+  })();
+}
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/prompts.js

@@ -201,7 +201,7 @@ Standard planning cycle with full board review.
    - **What to do with premature tasks:** Leave them in Backlog. Do NOT generate BUILD HANDOFFs for them. If a high-priority task fails the maturity gate due to phase prerequisites or dependencies, note it in the cycle log: "task-XXX deferred \u2014 Phase N prerequisites not met". Raw tasks are NOT premature \u2014 they just need scoping (see Task maturity above).
 
 7. **Recommendation** \u2014 Select tasks for this cycle:
-   **Pre-assigned tasks:** If a "Pre-Assigned Tasks" section is provided in the context below, those tasks are ALREADY committed to this cycle by the user. Include them automatically \u2014 do NOT re-evaluate whether they belong. Generate BUILD HANDOFFs for each. Count their effort toward the cycle budget. Then fill remaining slots (up to 5 total) from the backlog using the priority rules below.
+   **Pre-assigned tasks:** If a "Pre-Assigned Tasks" section is provided in the context below, those tasks are ALREADY committed to this cycle by the user. Include them automatically \u2014 do NOT re-evaluate whether they belong. Generate BUILD HANDOFFs for each. Count their effort toward the cycle budget. Then fill remaining slots from the backlog using the priority rules and cycle sizing rules below.
    **If USER DIRECTION is provided above:** Follow the user's stated focus. Pick the highest-impact task that aligns with their direction. The user knows what they need. Only deviate if a genuine P0 Critical fix exists (broken builds, data loss).
    **Otherwise, select by priority level then impact:**
    - **P0 Critical** \u2014 Broken, blocking, or data-loss risk. Always first.
@@ -225,7 +225,7 @@ Standard planning cycle with full board review.
 - **Backlog as steering wheel:** Task priority and notes in the backlog are the user's primary control mechanism over what gets planned. Respect the priority rankings and read task notes carefully \u2014 they contain user intent that shapes scope and scheduling.
 - **Planning quality is the bar:** Strategy review depth and plan quality set the standard for the product. Do not cut corners on analysis depth, triage thoroughness, or handoff specificity \u2014 these are what users experience as PAPI's value.
 
-10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for the recommended task and up to 4 additional high-priority unblocked tasks (5 total max). Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability. Remaining tasks will get handoffs in subsequent plans \u2014 do NOT try to cover the entire backlog.
+10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for every task selected for this cycle. Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability.
    **SKIP existing handoffs:** Tasks marked with "Has BUILD HANDOFF: yes" or "\u2713 handoff" on the board already have a valid handoff from a previous plan. Do NOT regenerate handoffs for these tasks \u2014 omit them from the \`cycleHandoffs\` array entirely. Only generate handoffs for tasks that do NOT have one yet. Exception: if a task's dependencies have been completed since its handoff was written, or a relevant Active Decision has changed, you MAY regenerate its handoff \u2014 but note this explicitly in the cycle log.
    **Scope pre-check:** Before writing the SCOPE section of each handoff, cross-reference the task against the "Recently Shipped Capabilities" section in the context below (if present). For each candidate task: (1) check if the task's title or scope overlaps with any recently shipped task, (2) check if the FILES LIKELY TOUCHED overlap with files already modified in recent builds, (3) check the architecture notes from recent builds for patterns that already cover this task's scope. If >80% of a task's scope appears in recently shipped capabilities, recommend cancellation via \`boardCorrections\` or reduce the handoff scope to only the missing pieces \u2014 explicitly note what already exists. C126 task-728 was over-scoped because the planner assumed Blocked status needed creating from scratch \u2014 it already existed in types, DB, orient, and build_list. Over-scoped handoffs waste builder time on verification and cause estimation mismatches.
    **Simplest Viable Path rule:** Before writing each BUILD HANDOFF, identify the simplest approach that satisfies the task's goal \u2014 the minimum change, fewest new abstractions, and smallest blast radius. Write the SCOPE (DO THIS) section for that simplest path FIRST. If you believe a more complex approach is warranted (new abstractions, multi-file refactors, framework changes), you MUST include a "WHY NOT SIMPLER" line in the handoff explaining why the simple path is insufficient. If you cannot articulate a concrete reason, use the simpler path. Pay special attention to tasks involving auth, data access, multi-user features, and infrastructure \u2014 these are the most common over-engineering targets.
@@ -388,7 +388,7 @@ Standard planning cycle with full board review.
    - **What to do with premature tasks:** Leave them in Backlog. Do NOT generate BUILD HANDOFFs for them. If a high-priority task fails the maturity gate due to phase prerequisites or dependencies, note it in the cycle log: "task-XXX deferred \u2014 Phase N prerequisites not met". Raw tasks are NOT premature \u2014 they just need scoping (see Task maturity above).
 
 7. **Recommendation** \u2014 Select tasks for this cycle:
-   **Pre-assigned tasks:** If a "Pre-Assigned Tasks" section is provided in the context below, those tasks are ALREADY committed to this cycle by the user. Include them automatically \u2014 do NOT re-evaluate whether they belong. Generate BUILD HANDOFFs for each. Count their effort toward the cycle budget. Then fill remaining slots (up to 5 total) from the backlog using the priority rules below.
+   **Pre-assigned tasks:** If a "Pre-Assigned Tasks" section is provided in the context below, those tasks are ALREADY committed to this cycle by the user. Include them automatically \u2014 do NOT re-evaluate whether they belong. Generate BUILD HANDOFFs for each. Count their effort toward the cycle budget. Then fill remaining slots from the backlog using the priority rules and cycle sizing rules below.
    **If USER DIRECTION is provided above:** Follow the user's stated focus. Pick the highest-impact task that aligns with their direction. The user knows what they need. Only deviate if a genuine P0 Critical fix exists (broken builds, data loss).
    **Otherwise, select by priority level then impact:**
    - **P0 Critical** \u2014 Broken, blocking, or data-loss risk. Always first.
@@ -412,7 +412,7 @@ Standard planning cycle with full board review.
 - **Backlog as steering wheel:** Task priority and notes in the backlog are the user's primary control mechanism over what gets planned. Respect the priority rankings and read task notes carefully \u2014 they contain user intent that shapes scope and scheduling.
 - **Planning quality is the bar:** Strategy review depth and plan quality set the standard for the product. Do not cut corners on analysis depth, triage thoroughness, or handoff specificity \u2014 these are what users experience as PAPI's value.
 
-10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for the recommended task and up to 4 additional high-priority unblocked tasks (5 total max). Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability. Remaining tasks will get handoffs in subsequent plans \u2014 do NOT try to cover the entire backlog.
+10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for every task selected for this cycle. Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability.
    **SKIP existing handoffs:** Tasks marked with "Has BUILD HANDOFF: yes" or "\u2713 handoff" on the board already have a valid handoff from a previous plan. Do NOT regenerate handoffs for these tasks \u2014 omit them from the \`cycleHandoffs\` array entirely. Only generate handoffs for tasks that do NOT have one yet. Exception: if a task's dependencies have been completed since its handoff was written, or a relevant Active Decision has changed, you MAY regenerate its handoff \u2014 but note this explicitly in the cycle log.
    **Scope pre-check:** Before writing the SCOPE section of each handoff, cross-reference the task against the "Recently Shipped Capabilities" section in the context below (if present). For each candidate task: (1) check if the task's title or scope overlaps with any recently shipped task, (2) check if the FILES LIKELY TOUCHED overlap with files already modified in recent builds, (3) check the architecture notes from recent builds for patterns that already cover this task's scope. If >80% of a task's scope appears in recently shipped capabilities, recommend cancellation via \`boardCorrections\` or reduce the handoff scope to only the missing pieces \u2014 explicitly note what already exists. C126 task-728 was over-scoped because the planner assumed Blocked status needed creating from scratch \u2014 it already existed in types, DB, orient, and build_list. Over-scoped handoffs waste builder time on verification and cause estimation mismatches.
    **Simplest Viable Path rule:** Before writing each BUILD HANDOFF, identify the simplest approach that satisfies the task's goal \u2014 the minimum change, fewest new abstractions, and smallest blast radius. Write the SCOPE (DO THIS) section for that simplest path FIRST. If you believe a more complex approach is warranted (new abstractions, multi-file refactors, framework changes), you MUST include a "WHY NOT SIMPLER" line in the handoff explaining why the simple path is insufficient. If you cannot articulate a concrete reason, use the simpler path. Pay special attention to tasks involving auth, data access, multi-user features, and infrastructure \u2014 these are the most common over-engineering targets.
@@ -471,6 +471,24 @@ function buildPlanUserMessage(ctx) {
     }) : PLAN_FULL_INSTRUCTIONS;
     parts.push(instructions);
   }
+  if (ctx.skipHandoffs) {
+    parts.push(
+      "",
+      "## SKIP HANDOFFS MODE",
+      "",
+      "**IMPORTANT OVERRIDE:** Do NOT generate BUILD HANDOFF blocks in this plan run.",
+      "Select tasks for the cycle using all the normal criteria (Steps 1-7), but SKIP Step 10 (BUILD HANDOFFs) entirely.",
+      "",
+      "In your Part 2 structured output:",
+      "- Set `cycleHandoffs` to an EMPTY array `[]`",
+      '- Add a `cycleTaskIds` array with the task IDs you selected for the cycle: `["task-123", "task-456", ...]`',
+      "- All other fields (cycleLogTitle, cycleLogContent, newTasks, boardCorrections, activeDecisions, etc.) work as normal.",
+      "",
+      "BUILD HANDOFFs will be generated separately via `handoff_generate` after this plan completes.",
+      "This reduces your cognitive load \u2014 focus on triage, selection, and board management only.",
+      ""
+    );
+  }
   parts.push("", "---", "", "## PROJECT CONTEXT", "");
   parts.push("### Product Brief", "", ctx.productBrief, "");
   if (ctx.northStar) {
@@ -647,6 +665,7 @@ function coerceStructuredOutput(parsed) {
     id: coerceToString(ad.id),
     body: coerceToString(ad.body)
   })) : [];
+  const cycleTaskIds = Array.isArray(parsed.cycleTaskIds) ? parsed.cycleTaskIds.map((id) => coerceToString(id)) : void 0;
   return {
     cycleLogTitle: coerceToString(parsed.cycleLogTitle),
     cycleLogContent: coerceToString(parsed.cycleLogContent),
@@ -657,6 +676,7 @@ function coerceStructuredOutput(parsed) {
     strategicDirection: coerceToString(parsed.strategicDirection),
     recommendedTaskId: parsed.recommendedTaskId === null ? null : coerceToString(parsed.recommendedTaskId),
     cycleHandoffs,
+    cycleTaskIds,
     newTasks,
     boardCorrections,
     productBrief: parsed.productBrief === null ? null : coerceToString(parsed.productBrief),
@@ -954,6 +974,9 @@ function buildReviewUserMessage(ctx) {
   if (ctx.taskComments) {
     parts.push("### Task Discussion (Recent Comments)", "", ctx.taskComments, "");
   }
+  if (ctx.docActionStaleness) {
+    parts.push("### Doc Action Staleness", "", ctx.docActionStaleness, "");
+  }
   return parts.join("\n");
 }
 function parseReviewStructuredOutput(raw) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.4-alpha.3",
+  "version": "0.7.5",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "type": "module",