@papi-ai/server 0.7.4-alpha.4 → 0.7.6

package/dist/index.js

@@ -4747,18 +4747,20 @@ var init_dist3 = __esm({
       }
       async getProject(id) {
         const [row] = await this.sql`
-      SELECT * FROM projects WHERE id = ${id}
+      SELECT id, slug, name, repo_url, papi_dir, user_id, created_at, updated_at FROM projects WHERE id = ${id}
     `;
         return row ?? null;
       }
       async listProjects(filter) {
         if (filter?.slug) {
           return this.sql`
-        SELECT * FROM projects WHERE slug = ${filter.slug} ORDER BY created_at
+        SELECT id, slug, name, repo_url, papi_dir, user_id, created_at, updated_at FROM projects WHERE slug = ${filter.slug} ORDER BY created_at
+        LIMIT 200 -- bounded: project list per user
       `;
         }
         return this.sql`
-      SELECT * FROM projects ORDER BY created_at
+      SELECT id, slug, name, repo_url, papi_dir, user_id, created_at, updated_at FROM projects ORDER BY created_at
+      LIMIT 200 -- bounded: project list per user
     `;
       }
       async updateProject(id, updates) {
@@ -4818,7 +4820,7 @@ var init_dist3 = __esm({
       }
       async getSharedDecision(id) {
         const [row] = await this.sql`
-      SELECT * FROM shared_decisions WHERE id = ${id}
+      SELECT id, display_id, title, decision, confidence, status, origin_project_id, evidence, superseded_by_id, created_at, updated_at, archived_at FROM shared_decisions WHERE id = ${id}
     `;
         return row ?? null;
       }
@@ -4838,7 +4840,8 @@ var init_dist3 = __esm({
         }
         if (conditions.length === 0) {
           return this.sql`
-        SELECT * FROM shared_decisions WHERE archived_at IS NULL ORDER BY created_at
+        SELECT id, display_id, title, decision, confidence, status, origin_project_id, evidence, superseded_by_id, created_at, updated_at, archived_at FROM shared_decisions WHERE archived_at IS NULL ORDER BY created_at
+        LIMIT 200 -- cross-project shared decisions; 200 is ample
       `;
         }
         let where = conditions[0];
@@ -4846,7 +4849,8 @@ var init_dist3 = __esm({
           where = this.sql`${where} AND ${conditions[i]}`;
         }
         return this.sql`
-      SELECT * FROM shared_decisions WHERE ${where} ORDER BY created_at
+      SELECT id, display_id, title, decision, confidence, status, origin_project_id, evidence, superseded_by_id, created_at, updated_at, archived_at FROM shared_decisions WHERE ${where} ORDER BY created_at
+      LIMIT 200
     `;
       }
       async updateSharedDecision(id, updates) {
@@ -4915,7 +4919,7 @@ var init_dist3 = __esm({
       }
       async getAcknowledgement(id) {
         const [row] = await this.sql`
-      SELECT * FROM acknowledgements WHERE id = ${id}
+      SELECT id, decision_id, project_id, status, comments, responded_at, created_at, updated_at FROM acknowledgements WHERE id = ${id}
     `;
         return row ?? null;
       }
@@ -4932,7 +4936,8 @@ var init_dist3 = __esm({
         }
         if (conditions.length === 0) {
           return this.sql`
-        SELECT * FROM acknowledgements ORDER BY created_at
+        SELECT id, decision_id, project_id, status, comments, responded_at, created_at, updated_at FROM acknowledgements ORDER BY created_at
+        LIMIT 500 -- acknowledgements grow with decisions × projects
       `;
         }
         let where = conditions[0];
@@ -4940,7 +4945,8 @@ var init_dist3 = __esm({
           where = this.sql`${where} AND ${conditions[i]}`;
         }
         return this.sql`
-      SELECT * FROM acknowledgements WHERE ${where} ORDER BY created_at
+      SELECT id, decision_id, project_id, status, comments, responded_at, created_at, updated_at FROM acknowledgements WHERE ${where} ORDER BY created_at
+      LIMIT 500
     `;
       }
       // -------------------------------------------------------------------------
@@ -4956,7 +4962,7 @@ var init_dist3 = __esm({
       }
       async getSharedMilestone(id) {
         const [row] = await this.sql`
-      SELECT * FROM shared_milestones WHERE id = ${id}
+      SELECT id, title, description, status, target_date, completed_at, created_at, updated_at, archived_at FROM shared_milestones WHERE id = ${id}
     `;
         return row ?? null;
       }
@@ -4970,7 +4976,8 @@ var init_dist3 = __esm({
         }
         if (conditions.length === 0) {
           return this.sql`
-        SELECT * FROM shared_milestones WHERE archived_at IS NULL ORDER BY created_at
+        SELECT id, title, description, status, target_date, completed_at, created_at, updated_at, archived_at FROM shared_milestones WHERE archived_at IS NULL ORDER BY created_at
+        LIMIT 200
       `;
         }
         let where = conditions[0];
@@ -4978,7 +4985,8 @@ var init_dist3 = __esm({
           where = this.sql`${where} AND ${conditions[i]}`;
         }
         return this.sql`
-      SELECT * FROM shared_milestones WHERE ${where} ORDER BY created_at
+      SELECT id, title, description, status, target_date, completed_at, created_at, updated_at, archived_at FROM shared_milestones WHERE ${where} ORDER BY created_at
+      LIMIT 200
     `;
       }
       async updateSharedMilestone(id, updates) {
@@ -5016,7 +5024,7 @@ var init_dist3 = __esm({
       }
       async listMilestoneDependencies(milestoneId) {
         return this.sql`
-      SELECT * FROM milestone_dependencies WHERE milestone_id = ${milestoneId}
+      SELECT id, milestone_id, depends_on_id FROM milestone_dependencies WHERE milestone_id = ${milestoneId}
     `;
       }
       async deleteMilestoneDependency(id) {
@@ -5045,7 +5053,7 @@ var init_dist3 = __esm({
       }
       async getProjectContribution(id) {
         const [row] = await this.sql`
-      SELECT * FROM project_contributions WHERE id = ${id}
+      SELECT id, milestone_id, project_id, status, required_phases, notes, delivered_at, created_at, updated_at FROM project_contributions WHERE id = ${id}
     `;
         return row ?? null;
       }
@@ -5062,7 +5070,8 @@ var init_dist3 = __esm({
         }
         if (conditions.length === 0) {
           return this.sql`
-        SELECT * FROM project_contributions ORDER BY created_at
+        SELECT id, milestone_id, project_id, status, required_phases, notes, delivered_at, created_at, updated_at FROM project_contributions ORDER BY created_at
+        LIMIT 500
       `;
         }
         let where = conditions[0];
@@ -5070,7 +5079,8 @@ var init_dist3 = __esm({
           where = this.sql`${where} AND ${conditions[i]}`;
         }
         return this.sql`
-      SELECT * FROM project_contributions WHERE ${where} ORDER BY created_at
+      SELECT id, milestone_id, project_id, status, required_phases, notes, delivered_at, created_at, updated_at FROM project_contributions WHERE ${where} ORDER BY created_at
+      LIMIT 500
     `;
       }
       async updateProjectContribution(id, updates) {
@@ -5108,7 +5118,7 @@ var init_dist3 = __esm({
       }
       async getActiveNorthStar(projectId) {
         const [row] = await this.sql`
-      SELECT * FROM north_stars
+      SELECT id, project_id, statement, set_at, superseded_by_id, superseded_at, created_at FROM north_stars
       WHERE project_id = ${projectId}
         AND superseded_by_id IS NULL
       ORDER BY created_at DESC
@@ -5126,7 +5136,8 @@ var init_dist3 = __esm({
         }
         if (conditions.length === 0) {
           return this.sql`
-        SELECT * FROM north_stars ORDER BY created_at
+        SELECT id, project_id, statement, set_at, superseded_by_id, superseded_at, created_at FROM north_stars ORDER BY created_at
+        LIMIT 200
       `;
         }
         let where = conditions[0];
@@ -5134,7 +5145,8 @@ var init_dist3 = __esm({
           where = this.sql`${where} AND ${conditions[i]}`;
         }
         return this.sql`
-      SELECT * FROM north_stars WHERE ${where} ORDER BY created_at
+      SELECT id, project_id, statement, set_at, superseded_by_id, superseded_at, created_at FROM north_stars WHERE ${where} ORDER BY created_at
+      LIMIT 200
     `;
       }
       /**
@@ -5148,7 +5160,7 @@ var init_dist3 = __esm({
         return this.sql.begin(async (_tx) => {
           const tx = _tx;
           const [old] = await tx`
-        SELECT * FROM north_stars WHERE id = ${id}
+        SELECT id, project_id, statement, set_at, superseded_by_id, superseded_at, created_at FROM north_stars WHERE id = ${id}
       `;
           if (!old) {
             throw new Error(`NorthStar not found: ${id}`);
@@ -5191,7 +5203,7 @@ var init_dist3 = __esm({
       }
       async getConflictAlert(id) {
         const [row] = await this.sql`
-      SELECT * FROM conflict_alerts WHERE id = ${id}
+      SELECT id, conflict_type, title, description, status, decision_a_id, decision_b_id, north_star_id, resolution_decision_id, raised_by, created_at, updated_at, resolved_at FROM conflict_alerts WHERE id = ${id}
     `;
         return row ?? null;
       }
@@ -5205,7 +5217,8 @@ var init_dist3 = __esm({
         }
         if (conditions.length === 0) {
           return this.sql`
-        SELECT * FROM conflict_alerts ORDER BY created_at
+        SELECT id, conflict_type, title, description, status, decision_a_id, decision_b_id, north_star_id, resolution_decision_id, raised_by, created_at, updated_at, resolved_at FROM conflict_alerts ORDER BY created_at
+        LIMIT 200
       `;
         }
         let where = conditions[0];
@@ -5213,7 +5226,8 @@ var init_dist3 = __esm({
           where = this.sql`${where} AND ${conditions[i]}`;
         }
         return this.sql`
-      SELECT * FROM conflict_alerts WHERE ${where} ORDER BY created_at
+      SELECT id, conflict_type, title, description, status, decision_a_id, decision_b_id, north_star_id, resolution_decision_id, raised_by, created_at, updated_at, resolved_at FROM conflict_alerts WHERE ${where} ORDER BY created_at
+      LIMIT 200
     `;
       }
       async updateConflictAlert(id, updates) {
@@ -6176,19 +6190,23 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
       }
       async getActiveDecisions() {
         const rows = await this.sql`
-      SELECT * FROM active_decisions
+      SELECT id, display_id, title, confidence, superseded, superseded_by, created_cycle, modified_cycle, body, outcome, revision_count
+      FROM active_decisions
       WHERE project_id = ${this.projectId}
       ORDER BY display_id
+      LIMIT 200 -- bounded: ADs are bounded by project lifecycle, 200 is a safe ceiling
     `;
         return rows.map(rowToActiveDecision);
       }
       async getSiblingAds(projectIds) {
         if (projectIds.length === 0) return [];
         const rows = await this.sql`
-      SELECT *, project_id FROM active_decisions
+      SELECT id, display_id, title, confidence, superseded, superseded_by, created_cycle, modified_cycle, body, outcome, revision_count, project_id
+      FROM active_decisions
       WHERE project_id = ANY(${projectIds}::uuid[])
         AND superseded = false
       ORDER BY project_id, display_id
+      LIMIT 500 -- cross-project query: 500 covers up to 10 projects × 50 ADs each
     `;
         return rows.map((row) => ({
           ...rowToActiveDecision(row),
@@ -6198,7 +6216,8 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
       async getCycleLog(limit) {
         if (limit != null) {
           const rows2 = await this.sql`
-        SELECT * FROM planning_log_entries
+        SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points
+        FROM planning_log_entries
         WHERE project_id = ${this.projectId}
         ORDER BY cycle_number DESC
         LIMIT ${limit}
@@ -6206,18 +6225,22 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
           return rows2.map(rowToCycleLogEntry);
         }
         const rows = await this.sql`
-      SELECT * FROM planning_log_entries
+      SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points
+      FROM planning_log_entries
       WHERE project_id = ${this.projectId}
       ORDER BY cycle_number DESC
+      LIMIT 500 -- 500 cycles is ~years of history, sufficient ceiling
     `;
         return rows.map(rowToCycleLogEntry);
       }
       async getCycleLogSince(cycleNumber) {
         const rows = await this.sql`
-      SELECT * FROM planning_log_entries
+      SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points
+      FROM planning_log_entries
       WHERE project_id = ${this.projectId}
         AND cycle_number >= ${cycleNumber}
       ORDER BY cycle_number DESC
+      LIMIT 500 -- bounded by cycle range, 500 is a safe ceiling
     `;
         return rows.map(rowToCycleLogEntry);
       }
@@ -6449,7 +6472,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
         const sinceCycle = input.sinceCycle ?? 0;
         const hasPending = input.hasPendingActions ?? false;
         const rows = await this.sql`
-      SELECT * FROM doc_registry
+      SELECT id, title, type, path, status, summary, tags, cycle_created, cycle_updated, superseded_by, actions, created_at, updated_at
+      FROM doc_registry
       WHERE project_id = ${this.projectId}
         AND (${matchAllStatuses} OR status = ${status})
         AND (${input.type ?? null}::text IS NULL OR type = ${input.type ?? null})
@@ -6479,9 +6503,11 @@ ${newParts.join("\n")}` : newParts.join("\n");
       async getDoc(idOrPath) {
         const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(idOrPath);
         const rows = isUuid ? await this.sql`
-          SELECT * FROM doc_registry WHERE id = ${idOrPath} AND project_id = ${this.projectId}
+          SELECT id, title, type, path, status, summary, tags, cycle_created, cycle_updated, superseded_by, actions, created_at, updated_at
+          FROM doc_registry WHERE id = ${idOrPath} AND project_id = ${this.projectId}
         ` : await this.sql`
-          SELECT * FROM doc_registry WHERE path = ${idOrPath} AND project_id = ${this.projectId}
+          SELECT id, title, type, path, status, summary, tags, cycle_created, cycle_updated, superseded_by, actions, created_at, updated_at
+          FROM doc_registry WHERE path = ${idOrPath} AND project_id = ${this.projectId}
         `;
         if (rows.length === 0) return null;
         const r = rows[0];
@@ -6640,9 +6666,11 @@ ${newParts.join("\n")}` : newParts.join("\n");
       async queryBoard(options) {
         if (!options) {
           const rows2 = await this.sql`
-        SELECT * FROM cycle_tasks
+        SELECT id, project_id, display_id, title, status, priority, complexity, module, epic, phase, owner, reviewed, cycle, created_cycle, created_at, why, depends_on, notes, closure_reason, state_history, build_handoff, build_report, task_type, maturity, stage_id, doc_ref, source, updated_at
+        FROM cycle_tasks
         WHERE project_id = ${this.projectId}
         ORDER BY display_id
+        LIMIT 2000 -- hard ceiling; single project task count won't approach this
       `;
           return rows2.map(rowToTask);
         }
@@ -6679,22 +6707,28 @@ ${newParts.join("\n")}` : newParts.join("\n");
           where = this.sql`${where} AND ${conditions[i]}`;
         }
         const rows = await this.sql`
-      SELECT * FROM cycle_tasks WHERE ${where} ORDER BY display_id
+      SELECT id, project_id, display_id, title, status, priority, complexity, module, epic, phase, owner, reviewed, cycle, created_cycle, created_at, why, depends_on, notes, closure_reason, state_history, build_handoff, build_report, task_type, maturity, stage_id, doc_ref, source, updated_at
+      FROM cycle_tasks WHERE ${where} ORDER BY display_id
+      LIMIT 2000 -- matches no-options path ceiling
     `;
         return rows.map(rowToTask);
       }
       async getTask(id) {
         const [row] = await this.sql`
-      SELECT * FROM cycle_tasks
+      SELECT id, project_id, display_id, title, status, priority, complexity, module, epic, phase, owner, reviewed, cycle, created_cycle, created_at, why, depends_on, notes, closure_reason, state_history, build_handoff, build_report, task_type, maturity, stage_id, doc_ref, source, updated_at
+      FROM cycle_tasks
       WHERE project_id = ${this.projectId} AND display_id = ${id}
+      LIMIT 1
     `;
         return row ? rowToTask(row) : null;
       }
       async getTasks(ids) {
         if (ids.length === 0) return [];
         const rows = await this.sql`
-      SELECT * FROM cycle_tasks
+      SELECT id, project_id, display_id, title, status, priority, complexity, module, epic, phase, owner, reviewed, cycle, created_cycle, created_at, why, depends_on, notes, closure_reason, state_history, build_handoff, build_report, task_type, maturity, stage_id, doc_ref, source, updated_at
+      FROM cycle_tasks
       WHERE project_id = ${this.projectId} AND display_id = ANY(${ids})
+      LIMIT 2000 -- matches board ceiling; ids[] won't exceed this in practice
     `;
         return rows.map(rowToTask);
       }
@@ -6804,7 +6838,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
         completed, actual_effort, estimated_effort, scope_accuracy,
         surprises, discovered_issues, architecture_notes,
         commit_sha, files_changed, related_decisions, handoff_accuracy,
-        corrections_count, brief_implications, dead_ends
+        corrections_count, brief_implications, dead_ends,
+        started_at, completed_at, tool_call_count
       ) VALUES (
         ${this.projectId}, ${displayId}, ${report.taskId}, ${report.taskName},
         ${report.date}, ${report.cycle}, ${report.completed},
@@ -6814,13 +6849,15 @@ ${newParts.join("\n")}` : newParts.join("\n");
         ${report.handoffAccuracy ? this.sql.json(report.handoffAccuracy) : null},
         ${report.correctionsCount ?? 0},
         ${report.briefImplications ? this.sql.json(report.briefImplications) : null},
-        ${report.deadEnds ?? null}
+        ${report.deadEnds ?? null},
+        ${report.startedAt ?? null}, ${report.completedAt ?? null}, ${report.toolCallCount ?? 0}
       )
     `;
       }
       async getRecentBuildReports(count) {
         const rows = await this.sql`
-      SELECT * FROM build_reports
+      SELECT id, display_id, task_id, task_name, date, cycle, completed, actual_effort, estimated_effort, scope_accuracy, surprises, discovered_issues, architecture_notes, commit_sha, files_changed, related_decisions, corrections_count, handoff_accuracy, brief_implications, dead_ends, created_at
+      FROM build_reports
       WHERE project_id = ${this.projectId}
       ORDER BY created_at DESC
       LIMIT ${count}
@@ -6836,9 +6873,11 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async getBuildReportsSince(cycleNumber) {
         const rows = await this.sql`
-      SELECT * FROM build_reports
+      SELECT id, display_id, task_id, task_name, date, cycle, completed, actual_effort, estimated_effort, scope_accuracy, surprises, discovered_issues, architecture_notes, commit_sha, files_changed, related_decisions, corrections_count, handoff_accuracy, brief_implications, dead_ends, created_at
+      FROM build_reports
       WHERE project_id = ${this.projectId} AND cycle >= ${cycleNumber}
       ORDER BY created_at
+      LIMIT 1000 -- bounded by cycle range; 1000 covers ~200 cycles × 5 tasks
     `;
         return rows.map(rowToBuildReport);
       }
@@ -6865,25 +6904,29 @@ ${newParts.join("\n")}` : newParts.join("\n");
         let rows;
         if (opts?.cycleNumber && opts?.category) {
           rows = await this.sql`
-        SELECT * FROM cycle_learnings
+        SELECT id, project_id, task_id, cycle_number, category, severity, summary, detail, tags, related_decision, action_taken, action_ref, created_at
+        FROM cycle_learnings
         WHERE project_id = ${this.projectId} AND cycle_number = ${opts.cycleNumber} AND category = ${opts.category}
         ORDER BY created_at DESC LIMIT ${limit}
       `;
         } else if (opts?.cycleNumber) {
           rows = await this.sql`
-        SELECT * FROM cycle_learnings
+        SELECT id, project_id, task_id, cycle_number, category, severity, summary, detail, tags, related_decision, action_taken, action_ref, created_at
+        FROM cycle_learnings
         WHERE project_id = ${this.projectId} AND cycle_number = ${opts.cycleNumber}
         ORDER BY created_at DESC LIMIT ${limit}
       `;
         } else if (opts?.category) {
           rows = await this.sql`
-        SELECT * FROM cycle_learnings
+        SELECT id, project_id, task_id, cycle_number, category, severity, summary, detail, tags, related_decision, action_taken, action_ref, created_at
+        FROM cycle_learnings
         WHERE project_id = ${this.projectId} AND category = ${opts.category}
         ORDER BY created_at DESC LIMIT ${limit}
       `;
         } else {
           rows = await this.sql`
-        SELECT * FROM cycle_learnings
+        SELECT id, project_id, task_id, cycle_number, category, severity, summary, detail, tags, related_decision, action_taken, action_ref, created_at
+        FROM cycle_learnings
         WHERE project_id = ${this.projectId}
         ORDER BY created_at DESC LIMIT ${limit}
       `;
@@ -6937,7 +6980,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
       async getRecentReviews(count) {
         const limit = count ?? 20;
         const rows = await this.sql`
-      SELECT * FROM reviews
+      SELECT id, display_id, task_id, stage, reviewer, verdict, cycle, date, comments, handoff_revision, build_commit_sha, auto_review
+      FROM reviews
       WHERE project_id = ${this.projectId}
       ORDER BY created_at DESC
       LIMIT ${limit}
@@ -7071,9 +7115,11 @@ ${newParts.join("\n")}` : newParts.join("\n");
       // -------------------------------------------------------------------------
       async readPhases() {
         const rows = await this.sql`
-      SELECT * FROM phases
+      SELECT id, slug, label, description, status, sort_order, stage_id
+      FROM phases
       WHERE project_id = ${this.projectId}
       ORDER BY sort_order
+      LIMIT 200 -- phases are bounded by project structure
     `;
         return rows.map(rowToPhase);
       }
@@ -7123,21 +7169,24 @@ ${newParts.join("\n")}` : newParts.join("\n");
       INSERT INTO tool_call_metrics (
         project_id, timestamp, tool, duration_ms,
         input_tokens, output_tokens, estimated_cost_usd, model, cycle_number,
-        context_bytes, context_utilisation
+        context_bytes, context_utilisation, success
       ) VALUES (
         ${this.projectId}, ${metric.timestamp}, ${metric.tool}, ${metric.durationMs},
         ${metric.inputTokens ?? null}, ${metric.outputTokens ?? null},
         ${metric.estimatedCostUsd ?? null}, ${metric.model ?? null},
         ${metric.cycleNumber ?? null},
-        ${metric.contextBytes ?? null}, ${metric.contextUtilisation ?? null}
+        ${metric.contextBytes ?? null}, ${metric.contextUtilisation ?? null},
+        ${metric.success ?? true}
       )
     `;
       }
       async readToolMetrics() {
         const rows = await this.sql`
-      SELECT * FROM tool_call_metrics
+      SELECT timestamp, tool, duration_ms, input_tokens, output_tokens, estimated_cost_usd, model, cycle_number, context_bytes, context_utilisation
+      FROM tool_call_metrics
       WHERE project_id = ${this.projectId}
       ORDER BY timestamp
+      LIMIT 5000 -- metrics are high-volume; task-1189 adds pagination for dashboard
     `;
         return rows.map(rowToToolCallMetric);
       }
@@ -7146,10 +7195,12 @@ ${newParts.join("\n")}` : newParts.join("\n");
       // -------------------------------------------------------------------------
       async getCostSummary(cycleNumber) {
         const metrics = cycleNumber != null ? await this.sql`
-          SELECT * FROM tool_call_metrics
+          SELECT timestamp, tool, duration_ms, input_tokens, output_tokens, estimated_cost_usd, model, cycle_number, context_bytes, context_utilisation
+          FROM tool_call_metrics
           WHERE project_id = ${this.projectId} AND cycle_number = ${cycleNumber}
         ` : await this.sql`
-          SELECT * FROM tool_call_metrics
+          SELECT timestamp, tool, duration_ms, input_tokens, output_tokens, estimated_cost_usd, model, cycle_number, context_bytes, context_utilisation
+          FROM tool_call_metrics
           WHERE project_id = ${this.projectId}
         `;
         let totalCostUsd = 0;
@@ -7186,7 +7237,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async getCostSnapshots() {
         const rows = await this.sql`
-      SELECT * FROM cost_snapshots
+      SELECT cycle, date, total_cost_usd, total_input_tokens, total_output_tokens, total_calls
+      FROM cost_snapshots
       WHERE project_id = ${this.projectId}
       ORDER BY cycle
     `;
@@ -7213,9 +7265,11 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async readCycleMetrics() {
         const rows = await this.sql`
-      SELECT * FROM cycle_metrics_snapshots
+      SELECT cycle, date, accuracy, velocity
+      FROM cycle_metrics_snapshots
       WHERE project_id = ${this.projectId}
       ORDER BY cycle
+      LIMIT 500 -- one row per cycle; 500 is ~years of history
     `;
         return rows.map(rowToCycleMetrics);
       }
@@ -7224,9 +7278,11 @@ ${newParts.join("\n")}` : newParts.join("\n");
       // -------------------------------------------------------------------------
       async readCycles() {
         const rows = await this.sql`
-      SELECT * FROM cycles
+      SELECT id, number, status, start_date, end_date, goals, board_health, task_ids
+      FROM cycles
       WHERE project_id = ${this.projectId}
       ORDER BY number
+      LIMIT 500 -- one row per cycle; 500 is years of history
     `;
         return rows.map(rowToCycle);
       }
@@ -7273,25 +7329,31 @@ ${newParts.join("\n")}` : newParts.join("\n");
       // -------------------------------------------------------------------------
       async readHorizons() {
         const rows = await this.sql`
-      SELECT * FROM horizons
+      SELECT id, slug, label, description, status, sort_order, project_id, created_at, updated_at
+      FROM horizons
       WHERE project_id = ${this.projectId}
       ORDER BY sort_order, created_at
+      LIMIT 50 -- horizons are high-level; 50 is an ample ceiling
     `;
         return rows.map(rowToHorizon);
       }
       async readStages(horizonId) {
         if (horizonId) {
           const rows2 = await this.sql`
-        SELECT * FROM stages
+        SELECT id, slug, label, description, status, sort_order, horizon_id, project_id, exit_criteria, created_at, updated_at
+        FROM stages
         WHERE project_id = ${this.projectId} AND horizon_id = ${horizonId}
         ORDER BY sort_order, created_at
+        LIMIT 100 -- stages per horizon are bounded; 100 is ample
       `;
           return rows2.map(rowToStage);
         }
         const rows = await this.sql`
-      SELECT * FROM stages
+      SELECT id, slug, label, description, status, sort_order, horizon_id, project_id, exit_criteria, created_at, updated_at
+      FROM stages
       WHERE project_id = ${this.projectId}
       ORDER BY sort_order, created_at
+      LIMIT 200 -- all stages across horizons; 200 is a safe ceiling
     `;
         return rows.map(rowToStage);
       }
@@ -7321,7 +7383,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async getActiveStage() {
         const rows = await this.sql`
-      SELECT * FROM stages
+      SELECT id, slug, label, description, status, sort_order, horizon_id, project_id, exit_criteria, created_at, updated_at
+      FROM stages
       WHERE project_id = ${this.projectId} AND status = 'Active'
       ORDER BY sort_order
       LIMIT 1
@@ -7433,7 +7496,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async getDecisionEvents(decisionId, limit) {
         const rows = await this.sql`
-      SELECT * FROM decision_events
+      SELECT id, decision_id, event_type, cycle, source, source_ref, detail, created_at
+      FROM decision_events
       WHERE project_id = ${this.projectId} AND decision_id = ${decisionId}
       ORDER BY created_at DESC
       LIMIT ${limit ?? 50}
@@ -7442,9 +7506,11 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async getDecisionEventsSince(cycle) {
         const rows = await this.sql`
-      SELECT * FROM decision_events
+      SELECT id, decision_id, event_type, cycle, source, source_ref, detail, created_at
+      FROM decision_events
       WHERE project_id = ${this.projectId} AND cycle >= ${cycle}
       ORDER BY created_at
+      LIMIT 1000 -- bounded by cycle range; 1000 is ample
     `;
         return rows.map(rowToDecisionEvent);
       }
@@ -7471,7 +7537,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async getDecisionScores(decisionId) {
         const rows = await this.sql`
-      SELECT * FROM decision_scores
+      SELECT id, decision_id, cycle, effort, risk, reversibility, scale_cost, lock_in, total_score, rationale, created_at
+      FROM decision_scores
       WHERE project_id = ${this.projectId} AND decision_id = ${decisionId}
       ORDER BY cycle
     `;
@@ -7479,7 +7546,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async getLatestDecisionScores() {
         const rows = await this.sql`
-      SELECT DISTINCT ON (decision_id) *
+      SELECT DISTINCT ON (decision_id) id, decision_id, cycle, effort, risk, reversibility, scale_cost, lock_in, total_score, rationale, created_at
       FROM decision_scores
       WHERE project_id = ${this.projectId}
       ORDER BY decision_id, cycle DESC
@@ -8394,6 +8461,9 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       readToolMetrics() {
         return this.invoke("readToolMetrics");
       }
+      insertPlanRun(entry) {
+        return this.invoke("insertPlanRun", [entry]);
+      }
       getCostSummary(cycleNumber) {
         return this.invoke("getCostSummary", [cycleNumber]);
       }
@@ -8520,6 +8590,46 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       submitBugReport(report) {
         return this.invoke("submitBugReport", [report]);
       }
+      // --- Doc Registry ---
+      registerDoc(entry) {
+        return this.invoke("registerDoc", [entry]);
+      }
+      searchDocs(input) {
+        return this.invoke("searchDocs", [input]);
+      }
+      getDoc(idOrPath) {
+        return this.invoke("getDoc", [idOrPath]);
+      }
+      updateDocStatus(id, status, supersededBy) {
+        return this.invoke("updateDocStatus", [id, status, supersededBy]);
+      }
+      // --- Cycle Learnings ---
+      appendCycleLearnings(learnings) {
+        return this.invoke("appendCycleLearnings", [learnings]);
+      }
+      getCycleLearnings(opts) {
+        return this.invoke("getCycleLearnings", [opts]);
+      }
+      getCycleLearningPatterns() {
+        return this.invoke("getCycleLearningPatterns", []);
+      }
+      updateCycleLearningActionRef(learningId, taskDisplayId) {
+        return this.invoke("updateCycleLearningActionRef", [learningId, taskDisplayId]);
+      }
+      // --- Strategy Review Drafts ---
+      savePendingReviewResponse(cycleNumber, rawResponse) {
+        return this.invoke("savePendingReviewResponse", [cycleNumber, rawResponse]);
+      }
+      getPendingReviewResponse() {
+        return this.invoke("getPendingReviewResponse", []);
+      }
+      clearPendingReviewResponse() {
+        return this.invoke("clearPendingReviewResponse", []);
+      }
+      // --- Active Decisions ---
+      confirmPendingActiveDecisions(cycleNumber) {
+        return this.invoke("confirmPendingActiveDecisions", [cycleNumber]);
+      }
       // --- Atomic plan write-back ---
       async planWriteBack(payload) {
         const raw = await this.invoke("planWriteBack", [payload]);
@@ -8975,8 +9085,10 @@ function detectUnrecordedCommits(cwd, baseBranch) {
       // release commits
       /^[a-f0-9]+ Merge /,
       // merge commits from PRs
-      /chore\(task-/
+      /chore\(task-/,
       // task-related housekeeping
+      /chore: dogfood log/
+      // automated dogfood log entries post-release
     ];
     return output.split("\n").filter((line) => line.trim() && !CYCLE_PATTERNS.some((p) => p.test(line))).map((line) => {
       const spaceIdx = line.indexOf(" ");
@@ -10071,7 +10183,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 +10207,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 +10370,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 +10394,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 +10453,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 +10647,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 +10658,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),
@@ -10604,6 +10736,8 @@ You MUST cover these 5 sections. Each is mandatory.
    - Note any hierarchy/phase issues worth correcting (1-2 bullets max)
    - Delete ADs that are legacy, process-level, or redundant without discussion
 
+**Registered Documents:** If a "### Registered Documents" section is present in context, scan it for: (a) research findings that contradict current ADs or strategy, (b) unactioned research that should influence the next plan. Reference relevant docs by title in your review. If unregistered docs are listed, flag 1-2 that look strategically relevant and suggest registering them.
+
 ## CONDITIONAL SECTIONS (include only when genuinely useful \u2014 most reviews should have 0-2 of these)
 
 6. **Security Posture Review** \u2014 Only if \`[SECURITY]\` tags exist in recent cycle logs.
@@ -10824,6 +10958,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 +11405,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 +11455,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 +11753,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 +11785,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 +11883,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 +11891,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 +11906,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 +12024,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 +12125,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 +12141,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 +12183,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 +12374,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 +12404,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 +12551,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 +12601,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 +12774,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 +12831,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 +12873,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 +12911,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 +12932,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 +12944,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 +13303,8 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     decisionUsage,
     recData,
     pendingRecs,
-    registeredDocs
+    registeredDocs,
+    docsWithPendingActions
   ] = await Promise.all([
     adapter2.readProductBrief(),
     adapter2.getActiveDecisions(),
@@ -13169,7 +13328,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 +13532,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 +13581,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 +13608,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;
@@ -13523,21 +13724,6 @@ ${cleanContent}`;
     });
   } catch {
   }
-  try {
-    const cycleLog = await adapter2.getCycleLogSince(cycleNumber);
-    const currentEntry = cycleLog.find((e) => e.cycleNumber === cycleNumber);
-    if (currentEntry) {
-      const reviewCompleteText = `Strategy review completed Cycle ${cycleNumber}. Next due ~Cycle ${cycleNumber + 5}.`;
-      const existingCf = currentEntry.carryForward ?? "";
-      const updatedCf = existingCf ? existingCf.replace(/strategy review (?:due|available|overdue)[^.]*\.[^.]*/gi, reviewCompleteText).trim() : reviewCompleteText;
-      const finalCf = updatedCf === existingCf ? `${existingCf} ${reviewCompleteText}`.trim() : updatedCf;
-      await adapter2.writeCycleLogEntry({
-        ...currentEntry,
-        carryForward: finalCf
-      });
-    }
-  } catch {
-  }
   if (data.activeDecisionUpdates && data.activeDecisionUpdates.length > 0) {
     await Promise.all(data.activeDecisionUpdates.map(async (ad) => {
       if (ad.action === "delete" && adapter2.deleteActiveDecision) {
@@ -14514,8 +14700,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 +15880,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 +15888,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 +15930,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 +15953,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 +16191,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 +16276,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 +16386,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.
 
@@ -16345,6 +16553,7 @@ init_git();
 import { randomUUID as randomUUID9 } from "crypto";
 import { readdirSync as readdirSync3, existsSync as existsSync3, readFileSync } from "fs";
 import { join as join5 } from "path";
+var buildStartTimes = /* @__PURE__ */ new Map();
 function capitalizeCompleted(value) {
   const map = {
     yes: "Yes",
@@ -16550,6 +16759,7 @@ async function startBuild(adapter2, config2, taskId, options = {}) {
   if (task.status !== "In Progress") {
     await adapter2.updateTaskStatus(taskId, "In Progress");
   }
+  buildStartTimes.set(taskId, (/* @__PURE__ */ new Date()).toISOString());
   let phaseChanges = [];
   try {
     phaseChanges = await propagatePhaseStatus(adapter2);
@@ -16615,8 +16825,11 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     correctionsCount: input.correctionsCount,
     briefImplications: input.briefImplications,
     deadEnds: input.deadEnds,
-    iterationCount
+    iterationCount,
+    startedAt: buildStartTimes.get(taskId) ?? void 0,
+    completedAt: now.toISOString()
   };
+  buildStartTimes.delete(taskId);
   if (input.relatedDecisions) {
     const adIds = input.relatedDecisions.split(",").map((s) => s.trim()).filter(Boolean);
     if (adIds.length > 0) report.relatedDecisions = adIds;
@@ -20253,7 +20466,7 @@ var hierarchyUpdateTool = {
       },
       status: {
         type: "string",
-        enum: ["active", "completed", "deferred"],
+        enum: ["Not Started", "In Progress", "Done", "Deferred"],
         description: "The new status to set."
       },
       exit_criteria: {
@@ -20265,7 +20478,7 @@ var hierarchyUpdateTool = {
     required: ["level", "name"]
   }
 };
-var VALID_STATUSES3 = /* @__PURE__ */ new Set(["active", "completed", "deferred"]);
+var VALID_STATUSES3 = /* @__PURE__ */ new Set(["Not Started", "In Progress", "Done", "Deferred"]);
 async function handleHierarchyUpdate(adapter2, args) {
   const level = args.level;
   const name = args.name;
@@ -20281,7 +20494,7 @@ async function handleHierarchyUpdate(adapter2, args) {
     return errorResponse(`Invalid level "${level}". Must be "phase", "stage", or "horizon".`);
   }
   if (status && !VALID_STATUSES3.has(status)) {
-    return errorResponse(`Invalid status "${status}". Must be one of: active, completed, deferred.`);
+    return errorResponse(`Invalid status "${status}". Must be one of: Not Started, In Progress, Done, Deferred.`);
   }
   if (exitCriteria !== void 0 && level !== "stage") {
     return errorResponse("exit_criteria can only be set on stages.");
@@ -20880,7 +21093,7 @@ function extractTitle(filePath) {
 }
 async function handleDocScan(adapter2, config2, args) {
   if (!adapter2.searchDocs) {
-    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+    return errorResponse("Doc registry not available on this adapter.");
   }
   const includePlans = args.include_plans ?? false;
   const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
@@ -20995,6 +21208,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 +21486,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 +21573,8 @@ function createServer(adapter2, config2) {
       docRegisterTool,
       docSearchTool,
       docScanTool,
-      getSiblingAdsTool
+      getSiblingAdsTool,
+      handoffGenerateTool
     ]
   }));
   server2.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -21264,6 +21690,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}` }] };
     }
@@ -21274,12 +21703,13 @@ function createServer(adapter2, config2) {
     delete result._usage;
     delete result._contextBytes;
     delete result._contextUtilisation;
-    if (contextBytes !== void 0 || contextUtilisation !== void 0) {
-      try {
-        const metric = buildMetric(name, elapsed, usage, void 0, contextBytes, contextUtilisation);
-        await adapter2.appendToolMetric(metric);
-      } catch {
-      }
+    const isError = result.content.some((c) => c.text.startsWith("Error:") || c.text.startsWith("\u274C"));
+    try {
+      const metric = buildMetric(name, elapsed, usage, void 0, contextBytes, contextUtilisation);
+      metric.success = !isError;
+      adapter2.appendToolMetric(metric).catch(() => {
+      });
+    } catch {
     }
     const telemetryProjectId = process.env["PAPI_PROJECT_ID"];
     if (telemetryProjectId) {
@@ -21287,7 +21717,6 @@ function createServer(adapter2, config2) {
         adapter_type: config2.adapterType
       });
       const isApplyMode = safeArgs.mode === "apply";
-      const isError = result.content.some((c) => c.text.startsWith("Error:") || c.text.startsWith("\u274C"));
       if (!isError) {
         if (name === "setup" && isApplyMode) {
           emitMilestone(telemetryProjectId, "setup_completed");
@@ -21389,5 +21818,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);