@papi-ai/server 0.7.6 → 0.7.8

package/dist/index.js

@@ -215,6 +215,30 @@ ${after}`;
 function parseNorthStar(content) {
   return extractSection(content, "North Star").replace(/^## North Star\s*/m, "").trim();
 }
+function upsertNorthStarInContent(content, statement) {
+  const headingPattern = /^## North Star\s*$/m;
+  const start = content.search(headingPattern);
+  if (start === -1) {
+    const cycleLogIdx = content.search(/^## (?:Cycle Log|Sprint Log)/m);
+    const newSection = `## North Star
+
+${statement}
+
+`;
+    if (cycleLogIdx === -1) {
+      return content.trimEnd() + "\n\n" + newSection;
+    }
+    return content.slice(0, cycleLogIdx) + newSection + content.slice(cycleLogIdx);
+  }
+  const afterHeading = content.slice(start);
+  const nextSection = afterHeading.slice(1).search(/^## /m);
+  const sectionEnd = nextSection === -1 ? content.length : start + nextSection + 1;
+  return content.slice(0, start) + `## North Star
+
+${statement}
+
+` + content.slice(sectionEnd);
+}
 function parseDeferred(content) {
   const section = extractSection(content, "Deferred / Parking Lot");
   return section.split("\n").filter((line) => line.match(/^-\s+/)).map((line) => line.replace(/^-\s+/, "").trim());
@@ -1428,7 +1452,8 @@ var init_dist2 = __esm({
       task: 1,
       research: 2,
       spike: 2,
-      idea: 3
+      idea: 3,
+      discovery: 1
     };
     VALID_EFFORT_SIZES = /* @__PURE__ */ new Set(["XS", "S", "M", "L", "XL"]);
     SECTION_HEADERS = [
@@ -2174,6 +2199,23 @@ ${footer}`);
       async getDecisionUsage(_currentCycle) {
         return [];
       }
+      // --- North Star ---
+      async getCurrentNorthStar() {
+        const content = await this.read("PLANNING_LOG.md");
+        const ns = parseNorthStar(content);
+        return ns || null;
+      }
+      async getNorthStarSetCycle() {
+        return null;
+      }
+      async getNorthStarStaleness() {
+        return null;
+      }
+      async upsertNorthStar(statement, _cycleNumber) {
+        const content = await this.read("PLANNING_LOG.md");
+        const updated = upsertNorthStarInContent(content, statement);
+        await this.write("PLANNING_LOG.md", updated);
+      }
     };
     NONE_PATTERN2 = /^none\b/i;
   }
@@ -4468,6 +4510,7 @@ function rowToTask(row) {
   if (row.stage_id != null) task.stageId = row.stage_id;
   if (row.doc_ref != null) task.docRef = row.doc_ref;
   if (row.source != null) task.source = row.source;
+  if (row.opportunity != null) task.opportunity = row.opportunity;
   return task;
 }
 function rowToBuildReport(row) {
@@ -4494,6 +4537,7 @@ function rowToBuildReport(row) {
   if (row.handoff_accuracy != null) report.handoffAccuracy = row.handoff_accuracy;
   if (row.brief_implications != null) report.briefImplications = row.brief_implications;
   if (row.dead_ends != null) report.deadEnds = row.dead_ends;
+  if (row.tool_call_count != null) report.toolCallCount = row.tool_call_count;
   return report;
 }
 function rowToReview(row) {
@@ -6094,6 +6138,22 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
     `;
         return rows.length > 0 ? { setCycle: rows[0].set_cycle, setAt: rows[0].set_at } : null;
       }
+      async upsertNorthStar(statement, _cycleNumber) {
+        const [newRow] = await this.sql`
+      INSERT INTO north_stars (project_id, statement, set_at)
+      VALUES (${this.projectId}, ${statement}, now())
+      RETURNING id
+    `;
+        if (newRow) {
+          await this.sql`
+        UPDATE north_stars
+        SET superseded_by_id = ${newRow.id}, superseded_at = now()
+        WHERE project_id = ${this.projectId}
+          AND superseded_by_id IS NULL
+          AND id != ${newRow.id}
+      `;
+        }
+      }
       async getEstimationCalibration() {
         const rows = await this.sql`
       SELECT estimated_effort, actual_effort, accuracy_label, COUNT(*)::text AS count
@@ -6666,7 +6726,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
       async queryBoard(options) {
         if (!options) {
           const rows2 = await this.sql`
-        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
+        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, opportunity, updated_at
         FROM cycle_tasks
         WHERE project_id = ${this.projectId}
         ORDER BY display_id
@@ -6707,7 +6767,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
           where = this.sql`${where} AND ${conditions[i]}`;
         }
         const rows = await this.sql`
-      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
+      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, opportunity, updated_at
       FROM cycle_tasks WHERE ${where} ORDER BY display_id
       LIMIT 2000 -- matches no-options path ceiling
     `;
@@ -6715,7 +6775,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async getTask(id) {
         const [row] = await this.sql`
-      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
+      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, opportunity, updated_at
       FROM cycle_tasks
       WHERE project_id = ${this.projectId} AND display_id = ${id}
       LIMIT 1
@@ -6725,7 +6785,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
       async getTasks(ids) {
         if (ids.length === 0) return [];
         const rows = await this.sql`
-      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
+      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, opportunity, 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
@@ -6745,7 +6805,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
         project_id, display_id, title, status, priority, complexity,
         module, epic, phase, owner, reviewed, cycle, created_cycle,
         why, depends_on, notes, closure_reason, state_history,
-        build_handoff, build_report, task_type, maturity, stage_id, doc_ref, source
+        build_handoff, build_report, task_type, maturity, stage_id, doc_ref, source, opportunity
       ) VALUES (
         ${this.projectId}, ${displayId}, ${task.title}, ${task.status}, ${task.priority},
         ${normaliseComplexity(task.complexity)}, ${task.module}, ${task.epic ?? null}, ${task.phase}, ${task.owner},
@@ -6759,7 +6819,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
         ${task.maturity ?? null},
         ${task.stageId ?? null},
         ${task.docRef ?? null},
-        ${task.source ?? null}
+        ${task.source ?? null},
+        ${task.opportunity ?? null}
       )
       RETURNING *
     `;
@@ -6791,6 +6852,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
         if (updates.stageId !== void 0) columnMap["stage_id"] = updates.stageId;
         if (updates.docRef !== void 0) columnMap["doc_ref"] = updates.docRef;
         if (updates.source !== void 0) columnMap["source"] = updates.source;
+        if (updates.opportunity !== void 0) columnMap["opportunity"] = updates.opportunity;
         const keys = Object.keys(columnMap);
         if (keys.length === 0) return;
         await this.sql`
@@ -7190,6 +7252,16 @@ ${newParts.join("\n")}` : newParts.join("\n");
     `;
         return rows.map(rowToToolCallMetric);
       }
+      async getToolCallCount(startedAt, completedAt) {
+        const rows = await this.sql`
+      SELECT COUNT(*)::text AS count
+      FROM tool_call_metrics
+      WHERE project_id = ${this.projectId}
+        AND timestamp >= ${startedAt}
+        AND timestamp <= ${completedAt}
+    `;
+        return parseInt(rows[0]?.count ?? "0", 10);
+      }
       // -------------------------------------------------------------------------
       // Cost Summary
       // -------------------------------------------------------------------------
@@ -7631,7 +7703,7 @@ ${r.content}` + (r.carry_forward ? `
         FROM cycle_tasks
         WHERE project_id = ${this.projectId}
           AND status NOT IN ('Done', 'Cancelled', 'Archived', 'Deferred')
-          AND (task_type IN ('task', 'bug', 'research') OR task_type IS NULL)
+          AND (task_type IN ('task', 'bug', 'research', 'discovery', 'spike') OR task_type IS NULL)
         ORDER BY
           CASE priority
             WHEN 'P0 Critical' THEN 0
@@ -7929,7 +8001,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
                 build_report: task.buildReport ?? null,
                 task_type: task.taskType ?? null,
                 maturity: task.maturity ?? null,
-                stage_id: task.stageId ?? null
+                stage_id: task.stageId ?? null,
+                opportunity: task.opportunity ?? null
               };
             });
             const taskCols = [
@@ -7955,7 +8028,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
               "build_report",
               "task_type",
               "maturity",
-              "stage_id"
+              "stage_id",
+              "opportunity"
             ];
             const insertedRows = await tx`
           INSERT INTO cycle_tasks ${tx(taskRows, ...taskCols)}
@@ -8567,6 +8641,9 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       getNorthStarStaleness() {
         return this.invoke("getNorthStarStaleness");
       }
+      upsertNorthStar(statement, cycleNumber) {
+        return this.invoke("upsertNorthStar", [statement, cycleNumber]);
+      }
       // --- Optional pg-only methods ---
       getEstimationCalibration() {
         return this.invoke("getEstimationCalibration");
@@ -8649,6 +8726,7 @@ __export(git_exports, {
   createAndCheckoutBranch: () => createAndCheckoutBranch,
   createPullRequest: () => createPullRequest,
   createTag: () => createTag,
+  cycleBranchName: () => cycleBranchName,
   deleteLocalBranch: () => deleteLocalBranch,
   detectBoardMismatches: () => detectBoardMismatches,
   detectUnrecordedCommits: () => detectUnrecordedCommits,
@@ -9104,6 +9182,9 @@ function detectUnrecordedCommits(cwd, baseBranch) {
 function taskBranchName(taskId) {
   return `feat/${taskId}`;
 }
+function cycleBranchName(cycleNumber, module) {
+  return `feat/cycle-${cycleNumber}-${module.toLowerCase().replace(/\s+/g, "-")}`;
+}
 function getHeadCommitSha(cwd) {
   try {
     return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim() || null;
@@ -9143,9 +9224,11 @@ var init_git = __esm({
 
 // src/index.ts
 import { readFileSync as readFileSync4 } from "fs";
+import { createServer as createHttpServer } from "http";
 import { dirname as dirname2, join as join11 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Server as Server2 } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema as CallToolRequestSchema2,
@@ -9168,6 +9251,8 @@ function loadConfig() {
   const baseBranch = process.env.PAPI_BASE_BRANCH ?? "main";
   const autoPR = process.env.PAPI_AUTO_PR !== "false";
   const lightMode = process.env.PAPI_LIGHT_MODE === "true";
+  const projectOwner = process.env.PAPI_OWNER ?? "Cathal";
+  const skipProjectSpecificRules = process.env.PAPI_SKIP_PROJECT_RULES === "true";
   const papiEndpoint = process.env.PAPI_ENDPOINT;
   const dataEndpoint = process.env.PAPI_DATA_ENDPOINT;
   const databaseUrl = process.env.DATABASE_URL;
@@ -9182,7 +9267,9 @@ function loadConfig() {
     autoPR,
     adapterType,
     papiEndpoint,
-    lightMode
+    lightMode,
+    projectOwner,
+    skipProjectSpecificRules
   };
 }
 
@@ -9538,7 +9625,7 @@ function formatDetailedTask(t) {
   return `- **${t.id}:** ${t.title}
   Status: ${t.status} | Priority: ${t.priority} | Complexity: ${t.complexity}${typeTag}
   Module: ${t.module} | Epic: ${t.epic} | Phase: ${t.phase} | Owner: ${t.owner}
-  Reviewed: ${t.reviewed}${t.dependsOn ? ` | Depends on: ${t.dependsOn}` : ""}${hasHandoff ? " | Has BUILD HANDOFF: yes" : ""}${t.docRef ? ` | Doc ref: ${t.docRef}` : ""}${notes ? `
+  Reviewed: ${t.reviewed}${t.dependsOn ? ` | Depends on: ${t.dependsOn}` : ""}${hasHandoff ? " | Has BUILD HANDOFF: yes" : ""}${t.docRef ? ` | Doc ref: ${t.docRef}` : ""}${t.opportunity ? ` | Opportunity: ${t.opportunity}` : ""}${notes ? `
   Notes: ${notes}` : ""}`;
 }
 function formatBoardForPlan(tasks, filters, currentCycle) {
@@ -9945,6 +10032,191 @@ function logDataSourceSummary(service, sources) {
   console.error(`[data-sources] ${service}: ${populated.length}/${sources.length} sources have data \u2014 empty: ${emptyLabels}`);
 }
 
+// src/lib/codebase-scan.ts
+import { execSync as execSync2 } from "child_process";
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "from",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "has",
+  "have",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "can",
+  "not",
+  "no",
+  "if",
+  "then",
+  "than",
+  "that",
+  "this",
+  "it",
+  "its",
+  "all",
+  "each",
+  "every",
+  "both",
+  "as",
+  "so",
+  "up",
+  "out",
+  "about",
+  "into",
+  "over",
+  "after",
+  "before",
+  "between",
+  "under",
+  "above",
+  "such",
+  "only",
+  "also",
+  "just",
+  "more",
+  "most",
+  "other",
+  "some",
+  "any",
+  "new",
+  "when",
+  "how",
+  "what",
+  "which",
+  "who",
+  "add",
+  "create",
+  "build",
+  "implement",
+  "make",
+  "update",
+  "fix",
+  "use",
+  "via",
+  "show",
+  "display",
+  "view",
+  "page",
+  "data",
+  "based",
+  "using",
+  "task",
+  "feature",
+  "system",
+  "tool",
+  "mode",
+  "field",
+  "type",
+  "status",
+  "current",
+  "default",
+  "existing",
+  "need",
+  "instead",
+  "allow",
+  "change"
+]);
+function extractSearchTerms(title, notes) {
+  const combined = `${title} ${notes ?? ""}`;
+  const camelCase = combined.match(/[a-z][a-zA-Z]{5,}/g) ?? [];
+  const snakeCase = combined.match(/[a-z]+_[a-z_]+/g) ?? [];
+  const hyphenated = combined.match(/[a-z]+-[a-z]+-?[a-z]*/g) ?? [];
+  const filePaths = combined.match(/[\w/.-]+\.(ts|tsx|js|jsx|sql|md)/g) ?? [];
+  const words = combined.toLowerCase().replace(/[^a-z0-9\s_-]/g, " ").split(/\s+/).filter((w) => w.length >= 4 && !STOP_WORDS.has(w));
+  const seen = /* @__PURE__ */ new Set();
+  const terms = [];
+  for (const group of [filePaths, camelCase, snakeCase, hyphenated, words]) {
+    for (const term of group) {
+      const normalized = term.toLowerCase();
+      if (!seen.has(normalized) && normalized.length >= 4) {
+        seen.add(normalized);
+        terms.push(term);
+      }
+    }
+  }
+  return terms.slice(0, 8);
+}
+function grepForTerm(projectRoot, term) {
+  try {
+    const result = execSync2(
+      `grep -rl --include='*.ts' --include='*.tsx' --include='*.js' --include='*.sql' --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.git --exclude-dir=.next ${JSON.stringify(term)} ${JSON.stringify(projectRoot)} 2>/dev/null | head -5`,
+      { encoding: "utf-8", timeout: 3e3 }
+    );
+    return result.trim().split("\n").filter(Boolean).map(
+      (p) => p.replace(projectRoot + "/", "")
+    );
+  } catch {
+    return [];
+  }
+}
+function scanCodebaseForTasks(projectRoot, tasks) {
+  if (tasks.length === 0) return "";
+  const startTime = Date.now();
+  const results = [];
+  for (const task of tasks) {
+    const terms = extractSearchTerms(task.title, task.notes);
+    if (terms.length === 0) continue;
+    const matches = [];
+    for (const term of terms) {
+      if (term.length < 4) continue;
+      const files = grepForTerm(projectRoot, term);
+      if (files.length > 0) {
+        matches.push({ term, files });
+      }
+      if (Date.now() - startTime > 5e3) {
+        console.error(`[codebase-scan] timeout after ${Date.now() - startTime}ms \u2014 partial results returned`);
+        break;
+      }
+    }
+    if (matches.length > 0) {
+      results.push({ taskId: task.id, terms, matches });
+    }
+    if (Date.now() - startTime > 5e3) break;
+  }
+  if (results.length === 0) return "";
+  const elapsed = Date.now() - startTime;
+  console.error(`[codebase-scan] scanned ${tasks.length} tasks in ${elapsed}ms \u2014 ${results.length} with matches`);
+  const lines = [
+    `Codebase scan found existing implementations for ${results.length}/${tasks.length} candidate tasks (${elapsed}ms):`,
+    ""
+  ];
+  for (const result of results) {
+    lines.push(`**${result.taskId}:**`);
+    for (const match of result.matches.slice(0, 3)) {
+      const fileList = match.files.slice(0, 3).join(", ");
+      const moreCount = match.files.length > 3 ? ` (+${match.files.length - 3} more)` : "";
+      lines.push(`  - "${match.term}" \u2192 ${fileList}${moreCount}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trim();
+}
+
 // src/lib/slack.ts
 async function sendSlackWebhook(webhookUrl, summary, header = "PAPI Strategy Review") {
   if (!webhookUrl) return void 0;
@@ -10004,6 +10276,9 @@ Task: [title]
 Cycle: [N]
 Why now: [justification]
 
+DEPENDS ON
+[Optional \u2014 comma-separated task IDs this task depends on (e.g. "task-123, task-124"). Include only when another task in this same cycle must be built first because this task consumes artifacts it creates (e.g. new adapter method, new type, new migration). The builder will reuse the upstream task's branch so dependent commits stack on the same branch for a single PR. Omit this section entirely if there are no intra-cycle dependencies.]
+
 SCOPE (DO THIS)
 [specific deliverables \u2014 write for the simplest viable path first]
 
@@ -10192,8 +10467,11 @@ Standard planning cycle with full board review.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
    Within the same priority level, prefer tasks with the highest **impact-to-effort ratio**. Impact is measured by: (a) strategic alignment \u2014 does it advance the current horizon/phase? (b) unlocks other work \u2014 are tasks blocked by this? (c) user-facing \u2014 does it change what users see? (d) compounds over time \u2014 does it make future cycles faster? A high-impact Medium task beats a low-impact Small task at the same priority level. Justify in 2-3 sentences.
    **Blocked tasks:** Tasks with status "Blocked" MUST be skipped during task selection \u2014 they are waiting on external dependencies or gates and cannot be built. Do NOT generate BUILD HANDOFFs for blocked tasks. Do NOT recommend blocked tasks. If a blocked task's gate has been resolved (check the notes and recent build reports), emit a \`boardCorrections\` entry to move it back to Backlog. Report blocked task count in the cycle log.
-   **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge from the tasks themselves. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 4-6 tasks. Cycles with fewer than 4 tasks require explicit justification in the cycle log \u2014 explain why more tasks could not be included. When the backlog has 10+ tasks, the cycle SHOULD have 5+ tasks \u2014 undersized cycles waste planning overhead relative to the available work. If fewer than 4 tasks qualify after filtering (blocked, deferred, raw), check Deferred tasks \u2014 some may be ready to un-defer via a \`boardCorrections\` entry. A 1-task cycle is almost never correct.
+   **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 6-10 tasks. Cycles with fewer than 5 tasks require explicit justification in the cycle log \u2014 explain why more tasks could not be included. When the backlog has 10+ tasks, the cycle SHOULD have 6+ tasks \u2014 undersized cycles waste planning overhead relative to the available work. If fewer than 5 tasks qualify after filtering (blocked, deferred, raw), check Deferred tasks \u2014 some may be ready to un-defer via a \`boardCorrections\` entry. A 1-task cycle is almost never correct. Prefer grouping tasks by module or similarity \u2014 reduces context switching and enables shared branches during the build phase.
+   **Theme-driven sizing:** Single-theme cycles (all tasks in the same module or epic) can absorb 25-30 effort points because builders maintain context across tasks. Mixed-theme cycles should stay at 15-20 effort points to limit context switching. Use the theme to determine the budget, not a fixed number.
    **Theme coherence:** After selecting candidate tasks, check whether they form a coherent theme \u2014 all serving one goal, phase, or module. Single-theme cycles produce better build quality and less context switching. If the top candidates touch 3+ unrelated modules or epics, prefer regrouping around the highest-priority theme and deferring the outliers. Mixed-theme cycles are acceptable when justified (e.g. a P0 fix alongside P1 feature work), but the justification must appear in the cycle log. Name the theme in 3-5 words \u2014 it becomes the \`cycleLogTitle\`.
+   **Epic-aware batching:** Epic is the primary grouping signal for theme coherence. When multiple candidate tasks share the same epic (e.g. "Onboarding Redesign", "Dashboard Polish"), prefer co-scheduling them \u2014 they solve connected problems and benefit from shared context during the build. Steps: (1) After filtering by priority, group eligible tasks by epic. (2) If an epic has 3+ eligible tasks, prefer scheduling 2-4 of them together over cherry-picking across epics. (3) Report the epic distribution in the cycle log (e.g. "4 tasks from Onboarding epic, 1 from Platform"). Priority still overrides: a P0 fix from a different epic always takes precedence.
+   **Opportunity clustering:** If backlog tasks have an \`opportunity\` field populated, group them by opportunity before selecting. Tasks sharing the same opportunity solve the same user problem \u2014 co-scheduling them produces more coherent cycles. Report opportunity clusters in the cycle log when present (e.g. "3 tasks clustered under 'planner accuracy' opportunity").
 
 8. **Cycle Log** \u2014 Write 5-10 line entry: what was triaged, what was recommended and why, observations, AD updates. Include a **Priority Recalibration** paragraph if any unreviewed task priorities were changed during triage (Step 2) \u2014 list each by ID with old \u2192 new priority and rationale. Include a **Priority Drift Suggestions** paragraph if reviewed task drift was detected (Step 3).
    **Cycle Notes** \u2014 Optionally include 1-3 lines of cycle-level observations in \`cycleLogNotes\`: estimation accuracy patterns, recurring blockers, velocity trends, or dependency signals. These notes persist across cycles so future planning runs can learn from them. Use null if there are no noteworthy observations this cycle.
@@ -10212,11 +10490,17 @@ Standard planning cycle with full board review.
    **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.
    **Maturity gate applies here:** Do NOT generate BUILD HANDOFFs for tasks that failed the maturity gate in step 6 (phase prerequisites not met, dependency chain incomplete). Raw tasks that the planner has scoped and upgraded to "investigated" in step 6 ARE eligible for handoffs.
+   **Intra-cycle dependency detection:** After selecting cycle tasks, check every pair for build-order dependencies. Two tasks A and B have an intra-cycle dependency when A must be built before B because B consumes an artifact A creates \u2014 e.g. A adds a new adapter method that B calls, A creates a DB migration B depends on, A introduces a new shared type B imports, A refactors a utility B modifies. Signals: same module + adjacent scope (one is "add X", another is "use X"), or notes explicitly reference the other task. For each dependency detected:
+   - Populate the DEPENDS ON section in the dependent task's BUILD HANDOFF with the upstream task ID(s).
+   - Add a \`boardCorrections\` entry for the dependent task with \`updates.dependsOn\` set to the comma-separated upstream IDs \u2014 this persists the dependency so the builder's runtime can reuse the upstream branch.
+   - Keep the SCOPE sections independent (each task still has its own deliverable) but note the ordering in "Why now" \u2014 e.g. "depends on task-123 completing the adapter method".
+   Do NOT invent dependencies where tasks merely share a module \u2014 only real build-order coupling counts. Linear chains only \u2014 do not attempt to resolve multi-level graphs. When in doubt, omit the dependency and let the builder discover it.
    **Security section guidance:** Each handoff includes a SECURITY CONSIDERATIONS section. Populate it when the task involves: data exposure risks (PII, secrets in logs/storage), secrets or credentials handling (API keys, tokens, env vars), auth/access control changes, or dependency security risks (new packages, version changes). For pure refactoring, documentation, prompt-text, or UI-only tasks, write "None \u2014 no security-relevant changes".
    **Estimation calibration:** Estimate **XS** for: copy/text-only changes, single string replacements, config tweaks, and any task where the scope is "change words in an existing file" with no logic changes. Estimate **S** for: wiring existing adapter methods, adding API routes following established patterns, modifying prompts, or documentation-only changes. Default to S for pattern-following work. Only use M when genuine new architecture, new DB tables, or multi-file architectural changes are needed. Historical data shows systematic over-estimation (198 over vs 8 under out of 528 tasks) \u2014 when in doubt, estimate smaller. If an "Estimation Calibration (Historical)" section is provided in the context below, use its data to adjust your estimates \u2014 it shows how often each estimated size matched the actual effort. Pay special attention to systematic over/under-estimation patterns (e.g. if M\u2192S happens frequently, estimate S instead of M for similar work).
    **Reference docs:** If a task's notes include a \`Reference:\` path (e.g. \`Reference: docs/architecture/papi-brain-v1.md\`), include a REFERENCE DOCS section in the BUILD HANDOFF with those paths. This tells the builder to read the referenced doc for background context before implementing. Do NOT omit or summarise the reference \u2014 pass it through so the builder can access the full document. Only tasks with explicit \`Reference:\` paths in their notes should have this section.
    **Pre-build verification:** EVERY handoff MUST include a PRE-BUILD VERIFICATION section listing 2-5 specific file paths the builder should read before implementing. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. This is the #1 prevention mechanism for wasted build slots (C120, C125, C126 all scheduled already-shipped work). If the builder finds >80% of the scope already implemented, they report "already built" instead of re-implementing.
    **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. Omit this section entirely for projects with fewer than 10 cycles.
+   **Build order in cycle log:** If any intra-cycle dependencies were detected in this cycle, include a "Build Order" paragraph in \`cycleLogNotes\` showing the recommended build sequence as arrow chains (e.g. "Build order: task-123 \u2192 task-124; task-130 standalone"). Skip this paragraph when no dependencies exist.
    **Research task detection:** When a task's title starts with "Research:" or the task type is "research", add a RESEARCH OUTPUT section to the BUILD HANDOFF after ACCEPTANCE CRITERIA:
 
    RESEARCH OUTPUT
@@ -10234,7 +10518,8 @@ Standard planning cycle with full board review.
    **Idea task detection:** When a task's task type is "idea", add a scope clarification note to the BUILD HANDOFF:
    - Add to SCOPE (DO THIS): "This task originated as an idea. Confirm the exact deliverable before implementing \u2014 check task notes and any referenced docs for intent. If scope is unclear, flag it in the build report surprises."
 
-   **UI/visual task detection:** When a task's title or notes contain keywords suggesting frontend visual work (e.g. "visual", "design", "UI", "styling", "refresh", "frontend", "landing page", "hero", "carousel", "theme", "layout", "cockpit", "dashboard", "page"), apply these handoff additions:
+   **UI/visual task detection:** Apply these additions ONLY to tasks whose PRIMARY scope is frontend visual work \u2014 the task's main deliverable must be a UI change, new component, visual design, or page. Do NOT apply to backend tasks, DB migrations, or prompt/config changes that merely mention a dashboard or page in passing. Signal: the task would fail if no .tsx/.css files were changed. If uncertain, skip the UI additions.
+   When a task IS a UI task (primary scope is visual/frontend):
    - Add to SCOPE: "Read \`.impeccable.md\` for brand palette, design principles, and audience context before writing any code. Use the \`frontend-design\` skill for implementation."
    - For M/L UI tasks, add to SCOPE: "Use the full UI toolchain: Playground (design preview) \u2192 Frontend-design (build) \u2192 Playwright (verify). The playground is the quality bar. Expect 2-3 iterations."
    - Add to ACCEPTANCE CRITERIA: "[ ] Visually verify rendered output in browser \u2014 provide localhost URL or screenshot to user for review." and "[ ] No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips."
@@ -10289,6 +10574,11 @@ var PLAN_FRAGMENT_BUG = `
 var PLAN_FRAGMENT_IDEA = `
    **Idea task detection:** When a task's task type is "idea", add a scope clarification note to the BUILD HANDOFF:
    - Add to SCOPE (DO THIS): "This task originated as an idea. Confirm the exact deliverable before implementing \u2014 check task notes and any referenced docs for intent. If scope is unclear, flag it in the build report surprises."`;
+var PLAN_FRAGMENT_TASK = `
+   **Task type detection:** When a task's task type is "task" (generic implementation task), add these handoff sections:
+   - SCOPE (DO THIS) must include: a clear deliverable statement and what "done" looks like (e.g. "User can X", "Function returns Y", "Page renders Z").
+   - Add to ACCEPTANCE CRITERIA: "[ ] Scope matches handoff \u2014 no unrelated code changed" and "[ ] Out-of-scope items documented if discovered during implementation."
+   - Add a SCOPE BOUNDARY (DO NOT DO THIS) section with at least one explicit exclusion \u2014 state what this task is NOT responsible for.`;
 var PLAN_FRAGMENT_SPIKE = `
    **Spike task detection:** When a task's task type is "spike" or the title starts with "Spike:", apply these rules:
    - Spikes are time-boxed investigations, not implementation tasks. The deliverable is a FINDING, not code.
@@ -10300,7 +10590,8 @@ var PLAN_FRAGMENT_SPIKE = `
    - Keep SCOPE BOUNDARY, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION as normal.
    - Spikes should be estimated conservatively: XS or S. If a spike needs M+ effort, it's not a spike \u2014 reclassify as a research task.`;
 var PLAN_FRAGMENT_UI = `
-   **UI/visual task detection:** When a task's title or notes contain keywords suggesting frontend visual work (e.g. "visual", "design", "UI", "styling", "refresh", "frontend", "landing page", "hero", "carousel", "theme", "layout", "cockpit", "dashboard", "page"), apply these handoff additions:
+   **UI/visual task detection:** Apply these additions ONLY to tasks whose PRIMARY scope is frontend visual work \u2014 the task's main deliverable must be a UI change, new component, visual design, or page. Do NOT apply to backend tasks, DB migrations, or prompt/config changes that merely mention a dashboard or page in passing. Signal: the task would fail if no .tsx/.css files were changed. If uncertain, skip the UI additions.
+   When a task IS a UI task (primary scope is visual/frontend):
    - Add to SCOPE: "Read \`.impeccable.md\` for brand palette, design principles, and audience context before writing any code. Use the \`frontend-design\` skill for implementation."
    - For M/L UI tasks, add to SCOPE: "Use the full UI toolchain: Playground (design preview) \u2192 Frontend-design (build) \u2192 Playwright (verify). The playground is the quality bar. Expect 2-3 iterations."
    - Add to ACCEPTANCE CRITERIA: "[ ] Visually verify rendered output in browser \u2014 provide localhost URL or screenshot to user for review." and "[ ] No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips."
@@ -10379,8 +10670,11 @@ Standard planning cycle with full board review.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
    Within the same priority level, prefer tasks with the highest **impact-to-effort ratio**. Impact is measured by: (a) strategic alignment \u2014 does it advance the current horizon/phase? (b) unlocks other work \u2014 are tasks blocked by this? (c) user-facing \u2014 does it change what users see? (d) compounds over time \u2014 does it make future cycles faster? A high-impact Medium task beats a low-impact Small task at the same priority level. Justify in 2-3 sentences.
    **Blocked tasks:** Tasks with status "Blocked" MUST be skipped during task selection \u2014 they are waiting on external dependencies or gates and cannot be built. Do NOT generate BUILD HANDOFFs for blocked tasks. Do NOT recommend blocked tasks. If a blocked task's gate has been resolved (check the notes and recent build reports), emit a \`boardCorrections\` entry to move it back to Backlog. Report blocked task count in the cycle log.
-   **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge from the tasks themselves. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 4-6 tasks. Cycles with fewer than 4 tasks require explicit justification in the cycle log \u2014 explain why more tasks could not be included. When the backlog has 10+ tasks, the cycle SHOULD have 5+ tasks \u2014 undersized cycles waste planning overhead relative to the available work. If fewer than 4 tasks qualify after filtering (blocked, deferred, raw), check Deferred tasks \u2014 some may be ready to un-defer via a \`boardCorrections\` entry. A 1-task cycle is almost never correct.
+   **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 6-10 tasks. Cycles with fewer than 5 tasks require explicit justification in the cycle log \u2014 explain why more tasks could not be included. When the backlog has 10+ tasks, the cycle SHOULD have 6+ tasks \u2014 undersized cycles waste planning overhead relative to the available work. If fewer than 5 tasks qualify after filtering (blocked, deferred, raw), check Deferred tasks \u2014 some may be ready to un-defer via a \`boardCorrections\` entry. A 1-task cycle is almost never correct. Prefer grouping tasks by module or similarity \u2014 reduces context switching and enables shared branches during the build phase.
+   **Theme-driven sizing:** Single-theme cycles (all tasks in the same module or epic) can absorb 25-30 effort points because builders maintain context across tasks. Mixed-theme cycles should stay at 15-20 effort points to limit context switching. Use the theme to determine the budget, not a fixed number.
    **Theme coherence:** After selecting candidate tasks, check whether they form a coherent theme \u2014 all serving one goal, phase, or module. Single-theme cycles produce better build quality and less context switching. If the top candidates touch 3+ unrelated modules or epics, prefer regrouping around the highest-priority theme and deferring the outliers. Mixed-theme cycles are acceptable when justified (e.g. a P0 fix alongside P1 feature work), but the justification must appear in the cycle log. Name the theme in 3-5 words \u2014 it becomes the \`cycleLogTitle\`.
+   **Epic-aware batching:** Epic is the primary grouping signal for theme coherence. When multiple candidate tasks share the same epic (e.g. "Onboarding Redesign", "Dashboard Polish"), prefer co-scheduling them \u2014 they solve connected problems and benefit from shared context during the build. Steps: (1) After filtering by priority, group eligible tasks by epic. (2) If an epic has 3+ eligible tasks, prefer scheduling 2-4 of them together over cherry-picking across epics. (3) Report the epic distribution in the cycle log (e.g. "4 tasks from Onboarding epic, 1 from Platform"). Priority still overrides: a P0 fix from a different epic always takes precedence.
+   **Opportunity clustering:** If backlog tasks have an \`opportunity\` field populated, group them by opportunity before selecting. Tasks sharing the same opportunity solve the same user problem \u2014 co-scheduling them produces more coherent cycles. Report opportunity clusters in the cycle log when present (e.g. "3 tasks clustered under 'planner accuracy' opportunity").
 
 8. **Cycle Log** \u2014 Write 5-10 line entry: what was triaged, what was recommended and why, observations, AD updates. Include a **Priority Recalibration** paragraph if any unreviewed task priorities were changed during triage (Step 2) \u2014 list each by ID with old \u2192 new priority and rationale. Include a **Priority Drift Suggestions** paragraph if reviewed task drift was detected (Step 3).
    **Cycle Notes** \u2014 Optionally include 1-3 lines of cycle-level observations in \`cycleLogNotes\`: estimation accuracy patterns, recurring blockers, velocity trends, or dependency signals. These notes persist across cycles so future planning runs can learn from them. Use null if there are no noteworthy observations this cycle.
@@ -10403,11 +10697,14 @@ Standard planning cycle with full board review.
    **Estimation calibration:** Estimate **XS** for: copy/text-only changes, single string replacements, config tweaks, and any task where the scope is "change words in an existing file" with no logic changes. Estimate **S** for: wiring existing adapter methods, adding API routes following established patterns, modifying prompts, or documentation-only changes. Default to S for pattern-following work. Only use M when genuine new architecture, new DB tables, or multi-file architectural changes are needed. Historical data shows systematic over-estimation (198 over vs 8 under out of 528 tasks) \u2014 when in doubt, estimate smaller. If an "Estimation Calibration (Historical)" section is provided in the context below, use its data to adjust your estimates \u2014 it shows how often each estimated size matched the actual effort. Pay special attention to systematic over/under-estimation patterns (e.g. if M\u2192S happens frequently, estimate S instead of M for similar work).
    **Reference docs:** If a task's notes include a \`Reference:\` path (e.g. \`Reference: docs/architecture/papi-brain-v1.md\`), include a REFERENCE DOCS section in the BUILD HANDOFF with those paths. This tells the builder to read the referenced doc for background context before implementing. Do NOT omit or summarise the reference \u2014 pass it through so the builder can access the full document. Only tasks with explicit \`Reference:\` paths in their notes should have this section.
    **Pre-build verification:** EVERY handoff MUST include a PRE-BUILD VERIFICATION section listing 2-5 specific file paths the builder should read before implementing. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. This is the #1 prevention mechanism for wasted build slots (C120, C125, C126 all scheduled already-shipped work). If the builder finds >80% of the scope already implemented, they report "already built" instead of re-implementing.
-   **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. Omit this section entirely for projects with fewer than 10 cycles.`);
+   **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. Omit this section entirely for projects with fewer than 10 cycles.
+   **Intra-cycle dependency detection:** After selecting cycle tasks, check every pair for build-order dependencies. Two tasks A and B have an intra-cycle dependency when A must be built before B because B consumes an artifact A creates \u2014 e.g. A adds a new adapter method that B calls, A creates a DB migration B depends on, A introduces a new shared type B imports, A refactors a utility B modifies. Signals: same module + adjacent scope (one is "add X", another is "use X"), or notes explicitly reference the other task. For each dependency detected: (a) populate the DEPENDS ON section in the dependent task's BUILD HANDOFF with the upstream task ID(s); (b) add a \`boardCorrections\` entry for the dependent task with \`updates.dependsOn\` set to the comma-separated upstream IDs \u2014 this persists the dependency so the builder's runtime can reuse the upstream branch; (c) keep SCOPE sections independent but note the ordering in "Why now". Do NOT invent dependencies where tasks merely share a module \u2014 only real build-order coupling counts. Linear chains only \u2014 no multi-level graph resolution. When in doubt, omit.
+   **Build order in cycle log:** If intra-cycle dependencies were detected, include a "Build order:" line in \`cycleLogNotes\` showing the recommended sequence as arrow chains (e.g. "Build order: task-123 \u2192 task-124; task-130 standalone"). Skip when no dependencies exist.`);
   if (flags.hasResearchTasks) parts.push(PLAN_FRAGMENT_RESEARCH);
   if (flags.hasBugTasks) parts.push(PLAN_FRAGMENT_BUG);
   if (flags.hasIdeaTasks) parts.push(PLAN_FRAGMENT_IDEA);
   if (flags.hasSpikeTasks) parts.push(PLAN_FRAGMENT_SPIKE);
+  if (flags.hasTaskTasks) parts.push(PLAN_FRAGMENT_TASK);
   if (flags.hasUITasks) parts.push(PLAN_FRAGMENT_UI);
   parts.push(`
 11. **New Tasks (max 3 per cycle)** \u2014 Actively mine the Recent Build Reports for task candidates. For each report, check:
@@ -10472,6 +10769,9 @@ function buildPlanUserMessage(ctx) {
     );
   }
   parts.push("", "---", "", "## PROJECT CONTEXT", "");
+  if (ctx.contextTier) {
+    parts.push(`**Context tier:** ${ctx.contextTier}`, "");
+  }
   parts.push("### Product Brief", "", ctx.productBrief, "");
   if (ctx.northStar) {
     parts.push("### North Star (current)", "", ctx.northStar, "");
@@ -10489,12 +10789,18 @@ function buildPlanUserMessage(ctx) {
     if (ctx.cycleLog) {
       parts.push("### Cycle Log", "", ctx.cycleLog, "");
     }
+    if (ctx.strategyReviewCadence) {
+      parts.push("### Strategy Review Cadence (computed from DB)", "", ctx.strategyReviewCadence, "");
+    }
     if (ctx.board) {
       parts.push("### Board", "", ctx.board, "");
     }
     if (ctx.preAssignedTasks) {
       parts.push("### Pre-Assigned Tasks", "", ctx.preAssignedTasks, "");
     }
+    if (ctx.codebaseScan) {
+      parts.push("### Codebase Scan (existing implementations)", "", ctx.codebaseScan, "");
+    }
     if (ctx.buildPatterns) {
       parts.push("### Build Patterns", "", ctx.buildPatterns, "");
     }
@@ -10845,7 +11151,8 @@ After your natural language output, include this EXACT format on its own line:
       "category": "friction | methodology | signal | commercial",
       "content": "string \u2014 specific observation from using PAPI on this project (e.g. 'deprioritise clears handoffs unnecessarily, wasting planner tokens')"
     }
-  ]
+  ],
+  "northStar": "string or null \u2014 the current North Star statement. Include if you assessed it in section 4 and it is still accurate (copy the current statement verbatim). Include the updated version if you revised it. Use null ONLY if no North Star has ever been set for this project."
 }
 \`\`\`
 
@@ -11032,7 +11339,8 @@ After your natural language output, include this EXACT format on its own line:
       },
       "oldLabel": "string \u2014 only for modify/remove: the previous phase label so tasks can be migrated"
     }
-  ]
+  ],
+  "northStar": "string or null \u2014 include the North Star statement if this strategic change defines or revises the project North Star. Use null if the change does not affect the North Star."
 }
 \`\`\`
 
@@ -11088,6 +11396,9 @@ Task: [title]
 Cycle: [N]
 Why now: [justification]
 
+DEPENDS ON
+[Optional \u2014 comma-separated task IDs this task depends on (e.g. "task-123, task-124"). Include only when another task in this same cycle must be built first because this task consumes artifacts it creates (e.g. new adapter method, new type, new migration). The builder will reuse the upstream task's branch so dependent commits stack on the same branch for a single PR. Omit this section entirely if there are no intra-cycle dependencies.]
+
 SCOPE (DO THIS)
 [specific deliverables \u2014 write for the simplest viable path first]
 
@@ -11388,6 +11699,32 @@ async function getPrompt(name) {
 }
 
 // src/services/plan.ts
+function determineContextTier(cycleCount) {
+  if (cycleCount <= 5) return 1;
+  if (cycleCount <= 20) return 2;
+  return 3;
+}
+function applyContextTier(ctx, cycleCount) {
+  const tier = determineContextTier(cycleCount);
+  const label = tier === 1 ? "Tier 1 (cycles 1-5)" : tier === 2 ? "Tier 2 (cycles 6-20)" : "Tier 3 (cycles 21+)";
+  if (tier <= 2) {
+    ctx.strategyRecommendations = void 0;
+    ctx.dogfoodEntries = void 0;
+  }
+  if (tier === 1) {
+    ctx.methodologyMetrics = void 0;
+    ctx.carryForwardStaleness = void 0;
+    ctx.discoveryCanvas = void 0;
+    ctx.estimationCalibration = void 0;
+    ctx.buildPatterns = void 0;
+    ctx.reviewPatterns = void 0;
+    ctx.horizonContext = void 0;
+    ctx.registeredDocs = void 0;
+    ctx.recentReviews = void 0;
+    ctx.strategyReviewCadence = void 0;
+  }
+  return { tier, label };
+}
 function determineMode(totalCycles) {
   if (totalCycles === 0) return "bootstrap";
   return "full";
@@ -11622,6 +11959,7 @@ function detectBoardFlags(tasks) {
   let hasResearchTasks = false;
   let hasIdeaTasks = false;
   let hasSpikeTasks = false;
+  let hasTaskTasks = false;
   let hasUITasks = false;
   const uiKeywords = /\b(visual|design|UI|styling|refresh|frontend|landing page|hero|carousel|theme|layout|cockpit|dashboard|page)\b/i;
   for (const t of tasks) {
@@ -11629,9 +11967,10 @@ function detectBoardFlags(tasks) {
     if (t.taskType === "research" || /^Research:/i.test(t.title)) hasResearchTasks = true;
     if (t.taskType === "idea") hasIdeaTasks = true;
     if (t.taskType === "spike" || /^Spike:/i.test(t.title)) hasSpikeTasks = true;
+    if (t.taskType === "task") hasTaskTasks = true;
     if (uiKeywords.test(t.title) || uiKeywords.test(t.notes ?? "")) hasUITasks = true;
   }
-  return { hasBugTasks, hasResearchTasks, hasIdeaTasks, hasSpikeTasks, hasUITasks };
+  return { hasBugTasks, hasResearchTasks, hasIdeaTasks, hasSpikeTasks, hasTaskTasks, hasUITasks };
 }
 function detectBoardFlagsFromText(boardText) {
   return {
@@ -11639,6 +11978,7 @@ function detectBoardFlagsFromText(boardText) {
     hasResearchTasks: /\b(research|Research:)\b/i.test(boardText),
     hasIdeaTasks: /\bidea\b/i.test(boardText),
     hasSpikeTasks: /\b(spike|Spike:)\b/i.test(boardText),
+    hasTaskTasks: /\btask\b/i.test(boardText),
     hasUITasks: /\b(visual|design|UI|styling|refresh|frontend|landing page|hero|carousel|theme|layout|cockpit|dashboard|page)\b/i.test(boardText)
   };
 }
@@ -11749,10 +12089,11 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
   timings["getPlanContextSummary"] = t();
   if (leanSummary) {
     t = startTimer();
-    let [metricsSnapshots2, reviews2] = await Promise.all([
+    const [metricsSnapshotsRaw, reviews2] = await Promise.all([
       adapter2.readCycleMetrics(),
       adapter2.getRecentReviews(5)
     ]);
+    let metricsSnapshots2 = metricsSnapshotsRaw;
     let leanBuildReports = [];
     try {
       leanBuildReports = await adapter2.getRecentBuildReports(50);
@@ -11849,6 +12190,9 @@ ${lines.join("\n")}`;
     ]);
     timings["total"] = totalTimer();
     console.error(`[plan-perf] assembleContext (lean): ${JSON.stringify(timings)}ms`);
+    const gap = health.cyclesSinceLastStrategyReview;
+    const lastReviewCycle = health.totalCycles - gap;
+    const strategyReviewCadence = gap <= 0 ? `\u2713 Strategy review completed this cycle (C${health.totalCycles}). No carry-forward needed.` : gap < 5 ? `\u2713 Strategy review on track \u2014 last review was C${lastReviewCycle} (${gap} cycle(s) ago). Next due: C${lastReviewCycle + 5}.` : `\u26A0\uFE0F Strategy review overdue \u2014 last review was C${lastReviewCycle} (${gap} cycles ago). Due now.`;
     let ctx2 = {
       mode,
       cycleNumber: health.totalCycles,
@@ -11870,8 +12214,12 @@ ${lines.join("\n")}`;
       boardFlags,
       carryForwardStaleness: carryForwardStalenessLean,
       preAssignedTasks: preAssignedTextLean,
-      recentlyShippedCapabilities: recentlyShippedLean
+      recentlyShippedCapabilities: recentlyShippedLean,
+      strategyReviewCadence
     };
+    const { label: leanTierLabel } = applyContextTier(ctx2, health.totalCycles);
+    ctx2.contextTier = leanTierLabel;
+    console.error(`[plan-perf] context tier: ${leanTierLabel} (cycle ${health.totalCycles})`);
     t = startTimer();
     const prevHashes2 = contextHashesResult.status === "fulfilled" ? contextHashesResult.value : null;
     const { ctx: diffedCtx2, newHashes: newHashes2, savedBytes: savedBytes2 } = applyContextDiff(ctx2, prevHashes2);
@@ -11933,7 +12281,8 @@ ${lines.join("\n")}`;
   if (pendingRecsResultFull.status === "fulfilled" && pendingRecsResultFull.value.length > 0) {
     strategyRecommendationsText = formatStrategyRecommendations(pendingRecsResultFull.value);
   }
-  const metricsSnapshots = allReportsForPatterns.length > 0 ? computeSnapshotsFromBuildReports(allReportsForPatterns) : rawMetricsSnapshots.filter((s) => s.accuracy.length > 0 || s.velocity.length > 0);
+  const filteredRaw = rawMetricsSnapshots.filter((s) => s.accuracy.length > 0 || s.velocity.length > 0);
+  const metricsSnapshots = filteredRaw.length > 0 ? filteredRaw : computeSnapshotsFromBuildReports(allReportsForPatterns);
   const discoveryCanvasTextFull = discoveryCanvasResultFull.status === "fulfilled" ? discoveryCanvasResultFull.value : void 0;
   const taskCommentsTextFull = taskCommentsResultFull.status === "fulfilled" ? taskCommentsResultFull.value : void 0;
   let registeredDocsTextFull;
@@ -11969,6 +12318,9 @@ ${lines.join("\n")}`;
   const targetCycle = health.totalCycles + 1;
   const preAssigned = strippedTasks.filter((t2) => t2.cycle === targetCycle);
   const preAssignedText = formatPreAssignedTasks(preAssigned, targetCycle);
+  const gapFull = health.cyclesSinceLastStrategyReview;
+  const lastReviewCycleFull = health.totalCycles - gapFull;
+  const strategyReviewCadenceFull = gapFull <= 0 ? `\u2713 Strategy review completed this cycle (C${health.totalCycles}). No carry-forward needed.` : gapFull < 5 ? `\u2713 Strategy review on track \u2014 last review was C${lastReviewCycleFull} (${gapFull} cycle(s) ago). Next due: C${lastReviewCycleFull + 5}.` : `\u26A0\uFE0F Strategy review overdue \u2014 last review was C${lastReviewCycleFull} (${gapFull} cycles ago). Due now.`;
   let ctx = {
     mode,
     cycleNumber: health.totalCycles,
@@ -11992,8 +12344,12 @@ ${lines.join("\n")}`;
     boardFlags: boardFlagsFull,
     carryForwardStaleness: computeCarryForwardStaleness(log),
     preAssignedTasks: preAssignedText,
-    recentlyShippedCapabilities: formatRecentlyShippedCapabilities(allReportsForPatterns)
+    recentlyShippedCapabilities: formatRecentlyShippedCapabilities(reports),
+    strategyReviewCadence: strategyReviewCadenceFull
   };
+  const { label: fullTierLabel } = applyContextTier(ctx, health.totalCycles);
+  ctx.contextTier = fullTierLabel;
+  console.error(`[plan-perf] context tier: ${fullTierLabel} (cycle ${health.totalCycles})`);
   const prevHashes = contextHashesResultFull.status === "fulfilled" ? contextHashesResultFull.value : null;
   const { ctx: diffedCtx, newHashes, savedBytes } = applyContextDiff(ctx, prevHashes);
   ctx = diffedCtx;
@@ -12183,7 +12539,15 @@ ${cleanContent}`;
     taskCount: cycleTaskCount > 0 ? cycleTaskCount : void 0,
     effortPoints: cycleEffortPoints > 0 ? cycleEffortPoints : void 0
   });
-  const healthPromise = Promise.resolve();
+  const healthUpdates = {
+    totalCycles: newCycleNumber,
+    boardHealth: data.boardHealth,
+    strategicDirection: data.strategicDirection
+  };
+  if (data.nextMode === "Full") {
+    healthUpdates.lastFullMode = newCycleNumber;
+  }
+  const healthPromise = adapter2.setCycleHealth(healthUpdates);
   const newTaskIdMap = /* @__PURE__ */ new Map();
   const createTasksPromise = (async () => {
     if (!data.newTasks || data.newTasks.length === 0) return;
@@ -12603,6 +12967,17 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
   }
   if (skipHandoffs) context.skipHandoffs = true;
   t = startTimer();
+  try {
+    const scanTasks = await adapter2.queryBoard({ status: ["Backlog", "In Cycle", "Ready"] });
+    const candidates = scanTasks.filter((task) => task.priority !== "P3 Low").slice(0, 15).map((task) => ({ id: task.id, title: task.title, notes: task.notes }));
+    const scanResult = scanCodebaseForTasks(config2.projectRoot, candidates);
+    if (scanResult) context.codebaseScan = scanResult;
+  } catch (err) {
+    console.error(`[plan] codebase scan failed (non-critical): ${err instanceof Error ? err.message : err}`);
+  }
+  const scanMs = t();
+  console.error(`[plan-perf] codebaseScan: ${scanMs}ms`);
+  t = startTimer();
   const userMessage = buildPlanUserMessage(context);
   const buildMessageMs = t();
   const totalMs = prepareTimer();
@@ -12779,6 +13154,7 @@ var lastPrepareSkipHandoffs;
 var planTool = {
   name: "plan",
   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`.',
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -12906,24 +13282,30 @@ async function handlePlan(adapter2, config2, args) {
         return errorResponse('llm_response is required for mode "apply". Pass your complete plan output including the <!-- PAPI_STRUCTURED_OUTPUT --> block.');
       }
       const planMode = args.plan_mode || "full";
-      const cycleNumber = typeof args.cycle_number === "number" ? args.cycle_number : 0;
+      const rawCycleNumber = args.cycle_number != null ? Number(args.cycle_number) : NaN;
       const strategyReviewWarning = args.strategy_review_warning || "";
       const contextHashes = lastPrepareContextHashes;
       const inputContext = lastPrepareUserMessage;
       const contextBytes = lastPrepareContextBytes;
       const expectedCycleNumber = lastPrepareCycleNumber;
       const skipHandoffsCached = lastPrepareSkipHandoffs;
-      lastPrepareContextHashes = void 0;
-      lastPrepareUserMessage = void 0;
-      lastPrepareContextBytes = void 0;
-      lastPrepareCycleNumber = void 0;
-      lastPrepareSkipHandoffs = void 0;
       const skipHandoffs = args.skip_handoffs === true || skipHandoffsCached === true;
+      const cycleNumber = !isNaN(rawCycleNumber) ? rawCycleNumber : expectedCycleNumber !== void 0 ? expectedCycleNumber : NaN;
+      if (isNaN(cycleNumber)) {
+        return errorResponse(
+          "cycle_number is required for apply mode. Pass the cycle_number from the prepare phase output."
+        );
+      }
       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.`
         );
       }
+      lastPrepareContextHashes = void 0;
+      lastPrepareUserMessage = void 0;
+      lastPrepareContextBytes = void 0;
+      lastPrepareCycleNumber = void 0;
+      lastPrepareSkipHandoffs = void 0;
       const result = await applyPlan(adapter2, config2, llmResponse, planMode, cycleNumber, strategyReviewWarning, contextHashes, { contextBytes: contextBytes ?? void 0, skipHandoffs: skipHandoffs || void 0 });
       let utilisation;
       if (inputContext) {
@@ -13122,7 +13504,7 @@ function classifyRecommendation(text) {
   if (lower.includes("new task") || lower.includes("create task") || lower.includes("add task") || lower.includes("spike")) {
     return "new_task";
   }
-  if (lower.includes("process") || lower.includes("workflow") || lower.includes("methodology") || lower.includes("retrospective") || lower.includes("dogfood")) {
+  if (lower.includes("process") || lower.includes("workflow") || lower.includes("methodology") || lower.includes("retrospective") || lower.includes("dogfood") || lower.includes("refine")) {
     return "process_improvement";
   }
   if (lower.includes("infrastructure") || lower.includes("deploy") || lower.includes("ci/cd") || lower.includes("pipeline") || lower.includes("hosting") || lower.includes("database") || lower.includes("migration")) {
@@ -13782,6 +14164,12 @@ ${cleanContent}`;
     } catch {
     }
   }
+  if (data.northStar && adapter2.upsertNorthStar) {
+    try {
+      await adapter2.upsertNorthStar(data.northStar, cycleNumber);
+    } catch {
+    }
+  }
   const compressionThreshold = cycleNumber - 5;
   if (compressionThreshold > 0 && data.sessionLogCompressionSummary) {
     await adapter2.compressCycleLog(compressionThreshold, data.sessionLogCompressionSummary);
@@ -13841,7 +14229,7 @@ ${cleanContent}`;
   try {
     const canvas = await adapter2.readDiscoveryCanvas();
     const updates = {};
-    let populatedSections = [];
+    const populatedSections = [];
     if (!canvas.landscapeReferences || canvas.landscapeReferences.length === 0) {
       if (data.activeDecisionUpdates?.length) {
         const entries = data.activeDecisionUpdates.filter((ad) => ad.body && ad.action !== "delete").slice(0, 3).map((ad) => ({ name: ad.id, notes: ad.body.slice(0, 200) }));
@@ -14104,10 +14492,17 @@ function formatVelocitySummary(reports, cycleCount) {
 function formatRecentReportsSummary(reports, count) {
   const recent = reports.sort((a, b2) => b2.cycle - a.cycle || b2.date.localeCompare(a.date)).slice(0, count);
   if (recent.length === 0) return "No recent build reports.";
+  const trunc = (s, max) => s && s !== "None" ? s.length > max ? s.slice(0, max) + "..." : s : null;
   return recent.map((r) => {
     const effort = `${r.actualEffort} vs ${r.estimatedEffort}`;
-    const surprises = r.surprises && r.surprises !== "None" ? ` \u2014 ${r.surprises.slice(0, 80)}${r.surprises.length > 80 ? "..." : ""}` : "";
-    return `- S${r.cycle} ${r.taskName}: ${effort}${surprises}`;
+    const lines = [`- C${r.cycle} ${r.taskName}: ${effort}`];
+    const surprises = trunc(r.surprises, 200);
+    if (surprises) lines.push(`  _Surprises:_ ${surprises}`);
+    const issues = trunc(r.discoveredIssues, 200);
+    if (issues) lines.push(`  _Issues:_ ${issues}`);
+    const arch = trunc(r.architectureNotes, 200);
+    if (arch) lines.push(`  _Architecture:_ ${arch}`);
+    return lines.join("\n");
   }).join("\n");
 }
 function formatPhasesForReview(phases, currentCycle) {
@@ -14133,7 +14528,7 @@ async function formatHierarchyForReview(adapter2, currentCycle, prefetchedTasks)
   } catch {
   }
   if (horizons.length === 0 && phases.length === 0) return void 0;
-  let tasksByPhase = /* @__PURE__ */ new Map();
+  const tasksByPhase = /* @__PURE__ */ new Map();
   try {
     const allTasks = prefetchedTasks ?? await adapter2.queryBoard();
     for (const t of allTasks) {
@@ -14278,6 +14673,12 @@ ${cleanContent}`;
         const currentPhases = await adapter2.readPhases();
         await applyPhaseUpdates(adapter2, currentPhases, data.phaseUpdates);
       }
+      if (data.northStar && adapter2.upsertNorthStar) {
+        try {
+          await adapter2.upsertNorthStar(data.northStar, cycleNumber);
+        } catch {
+        }
+      }
     } catch (err) {
       writeBackFailed = err instanceof Error ? err.message : String(err);
     }
@@ -14400,6 +14801,7 @@ var lastReviewContextBytes;
 var strategyReviewTool = {
   name: "strategy_review",
   description: 'Run a Strategy Review \u2014 assesses project direction, velocity, and Active Decisions. Produces recommendations and potential AD updates that feed into the next plan. Offered every 5 cycles; hard-blocked at 7+ overdue cycles. Run in its own dedicated session \u2014 do not mix with building. First call returns a review prompt for you to execute (prepare phase). Then call again with mode "apply" and your output. Pass `force: true` to run before the cadence gate.',
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -14427,6 +14829,7 @@ var strategyReviewTool = {
 var strategyChangeTool = {
   name: "strategy_change",
   description: 'Apply a strategic shift to the project. Three modes: "capture" for lightweight mid-conversation decision capture (no LLM round-trip), "prepare" to get a change prompt for full analysis, "apply" to persist analysis output. Use "capture" when you detect a strategic decision in conversation and want to persist it quickly without disrupting the build flow.',
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -14764,6 +15167,7 @@ async function archiveTasks(adapter2, phases, statuses) {
 var boardViewTool = {
   name: "board_view",
   description: 'View the Board. By default shows active tasks only (excludes Done/Cancelled), sorted by priority, limited to 50. Use status="all" to see everything. Use mode="summary" for counts only (no task details). Does not call the Anthropic API.',
+  annotations: { readOnlyHint: true, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -14795,6 +15199,7 @@ var boardViewTool = {
 var boardDeprioritiseTool = {
   name: "board_deprioritise",
   description: `Remove a task from the current cycle. Four actions: "backlog" (not now, maybe later \u2014 preserves handoff), "defer" (valid but premature \u2014 hidden from planner), "block" (waiting on external dependency \u2014 visible on board but skipped by planner), "cancel" (don't want this \u2014 permanently closed with reason). When a user rejects a task, ALWAYS ask which action they want. Does not call the Anthropic API.`,
+  annotations: { readOnlyHint: false, destructiveHint: true },
   inputSchema: {
     type: "object",
     properties: {
@@ -14830,6 +15235,7 @@ var boardDeprioritiseTool = {
 var boardArchiveTool = {
   name: "board_archive",
   description: "Archive tasks from the Board to the archive file. When both phase and status are provided, only tasks matching BOTH are archived (AND logic). When only one is provided, all matching tasks are archived. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: true },
   inputSchema: {
     type: "object",
     properties: {
@@ -14848,6 +15254,7 @@ var boardArchiveTool = {
 var boardEditTool = {
   name: "board_edit",
   description: "Edit fields on an existing task. Supports title, priority, complexity, module, epic, phase, notes, status, and maturity. Pass task_id plus any fields to update. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -15114,7 +15521,7 @@ async function handleBoardEdit(adapter2, args) {
       try {
         const dogfoodLog = await adapter2.getDogfoodLog?.(50) ?? [];
         const linked = dogfoodLog.filter((e) => e.linkedTaskId === taskId || e.linkedTaskId === task.id);
-        const newStatus = updates.status === "Done" ? "actioned" : "dismissed";
+        const newStatus = "resolved";
         await Promise.all(linked.map((e) => adapter2.updateDogfoodEntryStatus(e.id, newStatus)));
       } catch {
       }
@@ -15486,6 +15893,7 @@ When the system compresses prior messages, immediately:
 
 - **XS/S tasks in the same cycle and module:** Group on shared branch. One PR, one merge.
 - **M/L tasks or different modules:** Own branch per task. Isolated PRs.
+- **Dependent tasks (any size):** When a task's BUILD HANDOFF lists a \`DEPENDS ON\` task from the same cycle, \`build_execute\` automatically reuses the upstream task's branch so commits stack for a single PR. Do not create a separate branch manually.
 - **Commit per task within grouped branches** \u2014 traceable git history.
 - **Never use \`build_execute\` with \`light=true\` on shared branches.** Light mode commits directly to the current branch without creating a PR. When a shared branch is squash-merged, those commits are collapsed \u2014 any CLAUDE.md or documentation changes are stripped. Use light mode only on isolated single-task branches where no squash-merge will occur.
 
@@ -16285,6 +16693,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
 var setupTool = {
   name: "setup",
   description: `Initialise a new PAPI project or adopt an existing codebase. Only 3 inputs needed: project name, what it does, and who it's for. Set existing_project: true to adopt an existing codebase \u2014 PAPI scans the project structure and generates a context-aware brief, hierarchy, and initial backlog tasks. First call returns prompts (prepare phase), then call again with mode "apply" and your outputs. After setup, run plan to start your first cycle.`,
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -16554,6 +16963,8 @@ 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();
+var taskBranchMap = /* @__PURE__ */ new Map();
+var SHARED_BRANCH_COMPLEXITIES = /* @__PURE__ */ new Set(["XS", "Small"]);
 function capitalizeCompleted(value) {
   const map = {
     yes: "Yes",
@@ -16573,7 +16984,7 @@ function pushAndCreatePR(config2, taskId, taskTitle) {
   if (!isGitAvailable() || !isGitRepo(config2.projectRoot)) {
     return lines;
   }
-  const featureBranch = taskBranchName(taskId);
+  const featureBranch = taskBranchMap.get(taskId) ?? taskBranchName(taskId);
   const currentBranch = getCurrentBranch(config2.projectRoot);
   if (currentBranch !== featureBranch) {
     return lines;
@@ -16705,10 +17116,38 @@ async function startBuild(adapter2, config2, taskId, options = {}) {
   if (options.light) {
     branchLines.push("Light mode: skipping branch creation \u2014 working on current branch.");
   } else if (config2.autoCommit && isGitAvailable() && isGitRepo(config2.projectRoot)) {
-    const featureBranch = taskBranchName(taskId);
+    const cycleHealth = await adapter2.getCycleHealth().catch(() => null);
+    const cycleNumber = cycleHealth?.totalCycles ?? 0;
+    let depBranchReuse = null;
+    if (task.dependsOn) {
+      const depIds = task.dependsOn.split(",").map((d) => d.trim()).filter(Boolean);
+      for (const depId of depIds) {
+        const mappedBranch = taskBranchMap.get(depId);
+        if (mappedBranch && branchExists(config2.projectRoot, mappedBranch)) {
+          depBranchReuse = { branch: mappedBranch, upstreamId: depId };
+          break;
+        }
+        const fallbackBranch = taskBranchName(depId);
+        if (branchExists(config2.projectRoot, fallbackBranch)) {
+          depBranchReuse = { branch: fallbackBranch, upstreamId: depId };
+          break;
+        }
+      }
+    }
+    const useSharedBranch = !depBranchReuse && SHARED_BRANCH_COMPLEXITIES.has(task.complexity) && !!task.module && cycleNumber > 0;
+    const featureBranch = depBranchReuse ? depBranchReuse.branch : useSharedBranch ? cycleBranchName(cycleNumber, task.module) : taskBranchName(taskId);
+    if (depBranchReuse) {
+      branchLines.push(
+        `Reusing branch '${depBranchReuse.branch}' from dependency ${depBranchReuse.upstreamId} \u2014 commits will stack for a single PR.`
+      );
+    }
+    taskBranchMap.set(taskId, featureBranch);
     const currentBranch = getCurrentBranch(config2.projectRoot);
     if (currentBranch === featureBranch) {
       branchLines.push(`Already on branch '${featureBranch}'.`);
+      if (useSharedBranch) {
+        branchLines.push(`Reusing shared cycle branch for ${task.complexity} ${task.module} task.`);
+      }
     } else {
       if (hasUncommittedChanges(config2.projectRoot, AUTO_WRITTEN_PATHS)) {
         throw new Error("Working directory has uncommitted changes. Please commit or stash them before running `build_execute`.");
@@ -16717,13 +17156,14 @@ async function startBuild(adapter2, config2, taskId, options = {}) {
       if (baseBranch !== config2.baseBranch) {
         branchLines.push(`Base branch '${config2.baseBranch}' not found \u2014 using '${baseBranch}'.`);
       }
-      if (currentBranch !== baseBranch) {
+      const featureBranchExists = branchExists(config2.projectRoot, featureBranch);
+      if (currentBranch !== baseBranch && !featureBranchExists) {
         const checkout = checkoutBranch(config2.projectRoot, baseBranch);
         if (!checkout.success) {
           branchLines.push(`Warning: ${checkout.message} Proceeding on current branch '${currentBranch}'.`);
         }
       }
-      if (hasRemote(config2.projectRoot)) {
+      if (hasRemote(config2.projectRoot) && !featureBranchExists) {
         const pull = gitPull(config2.projectRoot);
         branchLines.push(pull.success ? pull.message : `Warning: ${pull.message}`);
       }
@@ -16733,10 +17173,10 @@ async function startBuild(adapter2, config2, taskId, options = {}) {
           `Warning: ${unmerged.length} unmerged feature branch${unmerged.length === 1 ? "" : "es"}: ${unmerged.join(", ")}. New branch may diverge if these contain changes needed here.`
         );
       }
-      if (branchExists(config2.projectRoot, featureBranch)) {
+      if (featureBranchExists) {
         const checkout = checkoutBranch(config2.projectRoot, featureBranch);
         branchLines.push(
-          checkout.success ? `Checked out existing branch '${featureBranch}'.` : `Warning: ${checkout.message}`
+          checkout.success ? useSharedBranch ? `Checked out shared cycle branch '${featureBranch}' \u2014 reusing for ${task.complexity} ${task.module} task.` : `Checked out existing branch '${featureBranch}'.` : `Warning: ${checkout.message}`
         );
         if (checkout.success) {
           branchLines.push(
@@ -16746,7 +17186,7 @@ async function startBuild(adapter2, config2, taskId, options = {}) {
       } else {
         const create = createAndCheckoutBranch(config2.projectRoot, featureBranch);
         branchLines.push(
-          create.success ? `Created branch '${featureBranch}'.` : `Warning: ${create.message}`
+          create.success ? useSharedBranch ? `Created shared cycle branch '${featureBranch}' for ${task.module} XS/S tasks.` : `Created branch '${featureBranch}'.` : `Warning: ${create.message}`
         );
         if (create.success) {
           branchLines.push(
@@ -16772,7 +17212,7 @@ function extractDocMeta(absolutePath, relativePath, cycleNumber) {
   let title = relativePath.split("/").pop()?.replace(".md", "") ?? relativePath;
   let type = "reference";
   let cycle = cycleNumber;
-  let summary = "Auto-registered \u2014 no summary available. Update via doc_register.";
+  const summary = "Auto-registered \u2014 no summary available. Update via doc_register.";
   if (relativePath.startsWith("docs/research/")) type = "research";
   else if (relativePath.startsWith("docs/architecture/")) type = "architecture";
   else if (relativePath.startsWith("docs/audits/")) type = "audit";
@@ -16830,11 +17270,27 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     completedAt: now.toISOString()
   };
   buildStartTimes.delete(taskId);
+  taskBranchMap.delete(taskId);
   if (input.relatedDecisions) {
     const adIds = input.relatedDecisions.split(",").map((s) => s.trim()).filter(Boolean);
     if (adIds.length > 0) report.relatedDecisions = adIds;
   }
+  if (report.startedAt && report.completedAt && typeof adapter2.getToolCallCount === "function") {
+    try {
+      const count = await adapter2.getToolCallCount(report.startedAt, report.completedAt);
+      if (count > 0) report.toolCallCount = count;
+    } catch {
+    }
+  }
   await adapter2.appendBuildReport(report);
+  let reportWriteVerified;
+  if (typeof adapter2.getBuildReportCountForTask === "function") {
+    try {
+      const postWriteCount = await adapter2.getBuildReportCountForTask(taskId);
+      reportWriteVerified = postWriteCount >= iterationCount;
+    } catch {
+    }
+  }
   if (adapter2.appendCycleLearnings) {
     const learnings = [];
     const taskModule = task.module ?? "";
@@ -16881,6 +17337,39 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
       }
     }
   }
+  let autoTriagedCount = 0;
+  if (input.discoveredIssues && input.discoveredIssues !== "None" && typeof adapter2.createTask === "function") {
+    const issueLines = input.discoveredIssues.split(/\n|;/).map((s) => s.trim()).filter((s) => s.length > 0);
+    for (const line of issueLines) {
+      const sevMatch = line.match(/^(P[0-3])[\s:]+/i);
+      if (!sevMatch) continue;
+      const severityLabel = sevMatch[1].toUpperCase();
+      const priority = severityLabel === "P0" || severityLabel === "P1" ? "P1 High" : severityLabel === "P2" ? "P2 Medium" : "P3 Low";
+      const titleRaw = line.replace(/^P[0-3][\s:]+/i, "").trim();
+      const title = titleRaw.length > 120 ? titleRaw.slice(0, 120) : titleRaw;
+      if (!title) continue;
+      try {
+        await adapter2.createTask({
+          uuid: "",
+          displayId: "",
+          title: `[Auto-triaged] ${title}`,
+          status: "Backlog",
+          priority,
+          complexity: "Small",
+          module: task.module ?? "",
+          phase: task.phase ?? "",
+          owner: "papi",
+          reviewed: false,
+          taskType: "discovery",
+          source: "build_complete",
+          notes: `Origin: ${task.displayId} (${task.title}), cycle ${cycleNumber}. Original issue: ${line}`,
+          createdCycle: cycleNumber
+        });
+        autoTriagedCount++;
+      } catch {
+      }
+    }
+  }
   if (adapter2.updateCycleLearningActionRef && task.notes) {
     const learningRefs = task.notes.match(/learning:([a-f0-9-]+)/gi);
     if (learningRefs) {
@@ -16923,6 +17412,52 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
       await adapter2.updateTaskStatus(taskId, "In Review");
     }
   }
+  let dogfoodResolvedCount = 0;
+  if (input.completed === "yes" && adapter2.getDogfoodLog && adapter2.updateDogfoodEntryStatus) {
+    try {
+      const dogfoodLog = await adapter2.getDogfoodLog(50);
+      const linked = dogfoodLog.filter(
+        (e) => (e.linkedTaskId === taskId || e.linkedTaskId === task.id) && e.status !== "resolved"
+      );
+      if (linked.length > 0) {
+        await Promise.all(linked.map((e) => adapter2.updateDogfoodEntryStatus(e.id, "resolved")));
+        dogfoodResolvedCount = linked.length;
+      }
+    } catch {
+    }
+  }
+  let learningsLinkedCount = 0;
+  if (input.completed === "yes" && adapter2.getCycleLearnings && adapter2.updateCycleLearningActionRef) {
+    try {
+      const recentLearnings = await adapter2.getCycleLearnings({ limit: 30 });
+      const unactioned = recentLearnings.filter(
+        (l) => !l.actionRef && l.cycleNumber >= cycleNumber - 5
+      );
+      if (unactioned.length > 0) {
+        const taskText = `${task.title} ${task.notes ?? ""}`.toLowerCase();
+        const taskWords = new Set(
+          taskText.match(/\b[a-z]{4,}\b/g) ?? []
+        );
+        const taskModule = (task.module ?? "").toLowerCase();
+        for (const learning of unactioned) {
+          const learningModule = (learning.tags[0] ?? "").toLowerCase();
+          if (!taskModule || !learningModule || taskModule !== learningModule) continue;
+          const learningText = `${learning.summary} ${learning.detail ?? ""}`.toLowerCase();
+          const learningWords = learningText.match(/\b[a-z]{4,}\b/g) ?? [];
+          const hasKeywordOverlap = learningWords.some((w) => taskWords.has(w));
+          if (!hasKeywordOverlap) continue;
+          if (learning.id) {
+            try {
+              await adapter2.updateCycleLearningActionRef(learning.id, task.id);
+              learningsLinkedCount++;
+            } catch {
+            }
+          }
+        }
+      }
+    } catch {
+    }
+  }
   const statusNote = input.completed === "yes" ? options.light ? `Task "${task.title}" (${taskId}) marked Done (light mode \u2014 no review needed).` : `Task "${task.title}" (${taskId}) marked In Review \u2014 ready for your sign-off via \`review_submit\`.` : `Task "${task.title}" (${taskId}) status unchanged (completed: ${input.completed}).`;
   let commitLine;
   if (config2.autoCommit) {
@@ -17023,7 +17558,11 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     completed: input.completed,
     scopeAccuracy: input.scopeAccuracy,
     phaseChanges,
-    docWarning
+    docWarning,
+    dogfoodResolvedCount: dogfoodResolvedCount > 0 ? dogfoodResolvedCount : void 0,
+    learningsLinkedCount: learningsLinkedCount > 0 ? learningsLinkedCount : void 0,
+    autoTriagedCount: autoTriagedCount > 0 ? autoTriagedCount : void 0,
+    reportWriteVerified
   };
 }
 async function cancelBuild(adapter2, taskId, reason) {
@@ -17080,8 +17619,6 @@ For M/L tasks: use the full toolchain \u2014 Playground (design preview) \u2192
 - Check adapter-pg implementation, not adapter-md. adapter-md is legacy.
 - Verify the full write\u2192DB\u2192read\u2192consumer path for any data changes.
 - Run migrations on dev before prod. Test with \`execute_sql\` via Supabase MCP.
-- When adding adapter interface methods, implement in BOTH adapter-md and adapter-pg.
-- Build order matters: adapter-md \u2192 adapter-pg \u2192 server.
 - .papi/ files may be stale \u2014 DB via MCP tools is the source of truth.`,
   Auth: `**MODULE INSTRUCTIONS \u2014 Auth**
 - NEVER expose the Supabase service role key in client-side code or API responses.
@@ -17116,6 +17653,7 @@ ${instructions}`;
 var buildListTool = {
   name: "build_list",
   description: "List cycle tasks that have BUILD HANDOFFs ready for execution. Shows task ID, title, status, priority, and complexity. In Progress tasks appear first, then Backlog. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {},
@@ -17125,6 +17663,7 @@ var buildListTool = {
 var buildDescribeTool = {
   name: "build_describe",
   description: "Show the full BUILD HANDOFF for a specific task, including scope, acceptance criteria, and implementation guidance. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -17139,6 +17678,7 @@ var buildDescribeTool = {
 var buildExecuteTool = {
   name: "build_execute",
   description: "Start or complete a build task. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Never call on tasks that are already In Review or Done. Does not call the Anthropic API. Set light=true to skip branch/PR creation (commits to current branch). Set PAPI_LIGHT_MODE=true in env to default all builds to light mode.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -17171,7 +17711,7 @@ var buildExecuteTool = {
       },
       discovered_issues: {
         type: "string",
-        description: `Problems found DURING this build that are OUTSIDE this task's scope. Include severity (P0-P3). Good: "P2: Auth middleware doesn't validate token expiry \u2014 affects all protected routes." Bad: "Had to install a dependency." Only real bugs or gaps that need their own task. Use "None" if none. Required for complete.`
+        description: `Problems found DURING this build that are OUTSIDE this task's scope. Include severity (P0-P3). Good: "P2: Auth middleware doesn't validate token expiry \u2014 affects all protected routes." Bad: "Had to install a dependency." Only real bugs or gaps that need their own task. Use "None" if none. Required for complete. TIP: When submitting a follow-up idea for a discovered issue, include "learning:<uuid>" in the idea notes to link it to this cycle learning entry \u2014 use the UUID returned in the build completion output.`
       },
       architecture_notes: {
         type: "string",
@@ -17223,6 +17763,7 @@ var buildExecuteTool = {
 var buildCancelTool = {
   name: "build_cancel",
   description: "Cancel a build task with a reason. Sets the task status to Cancelled and records the closure reason. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: true },
   inputSchema: {
     type: "object",
     properties: {
@@ -17390,9 +17931,28 @@ If >80% of the scope is already implemented, call \`build_execute\` with complet
       adSection = formatRelevantADs(relevant);
     } catch {
     }
+    let dogfoodSection = "";
+    try {
+      if (adapter2.getDogfoodLog) {
+        const dogfoodLog = await adapter2.getDogfoodLog(50);
+        const linked = dogfoodLog.filter(
+          (e) => e.linkedTaskId === result.task.id || e.linkedTaskId === result.task.displayId
+        );
+        if (linked.length > 0) {
+          const entries = linked.map((e) => `- [${e.category}] ${e.content}`).join("\n");
+          dogfoodSection = `
+
+---
+
+**DOGFOOD CONTEXT** \u2014 This task was linked to ${linked.length} observation(s):
+${entries}`;
+        }
+      }
+    } catch {
+    }
     const moduleInstructions = getModuleInstructions(result.task.module);
     const moduleContext = await getModuleContext(adapter2, result.task);
-    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + adSection + moduleInstructions + moduleContext + verificationNote + chainInstruction + phaseNote);
+    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + adSection + moduleInstructions + moduleContext + dogfoodSection + verificationNote + chainInstruction + phaseNote);
   } catch (err) {
     if (isNoHandoffError(err)) {
       const lines = [
@@ -17499,6 +18059,18 @@ function formatCompleteResult(result) {
       lines.push(`Phase auto-updated: ${c.phaseId} ${c.oldStatus} \u2192 ${c.newStatus}`);
     }
   }
+  if (result.dogfoodResolvedCount) {
+    lines.push("", `Resolved ${result.dogfoodResolvedCount} dogfood observation(s) linked to this task.`);
+  }
+  if (result.learningsLinkedCount) {
+    lines.push("", `Linked ${result.learningsLinkedCount} unactioned learning(s) to this task.`);
+  }
+  if (result.autoTriagedCount) {
+    lines.push("", `\u{1F516} Auto-triaged ${result.autoTriagedCount} discovered issue(s) to Backlog.`);
+  }
+  if (result.reportWriteVerified === false) {
+    lines.push("", "\u26A0\uFE0F Build report write could not be verified \u2014 the report may not have been persisted. Run `build_list` to check, and resubmit if missing.");
+  }
   if (result.docWarning) {
     lines.push("", `\u{1F4C4} ${result.docWarning}`);
   }
@@ -17638,7 +18210,7 @@ function resolveCurrentPhase(phases) {
   const sorted = [...phases].sort((a, b2) => a.order - b2.order);
   return sorted[0].label;
 }
-var STOP_WORDS = /* @__PURE__ */ new Set([
+var STOP_WORDS2 = /* @__PURE__ */ new Set([
   "a",
   "an",
   "the",
@@ -17732,7 +18304,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
 ]);
 function extractKeywords(text) {
   return new Set(
-    text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !STOP_WORDS.has(w))
+    text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !STOP_WORDS2.has(w))
   );
 }
 async function findSimilarTasks(adapter2, ideaTitle) {
@@ -17799,14 +18371,15 @@ ${lines.join("\n")}
   ]);
   warnIfEmpty("getCycleHealth (idea)", health);
   const phase = input.phase || resolveCurrentPhase(phases);
-  const VALID_PRIORITIES2 = /* @__PURE__ */ new Set(["P0 Critical", "P1 High", "P2 Medium", "P3 Low"]);
+  const VALID_PRIORITIES3 = /* @__PURE__ */ new Set(["P0 Critical", "P1 High", "P2 Medium", "P3 Low"]);
   const VALID_COMPLEXITIES2 = /* @__PURE__ */ new Set(["XS", "Small", "Medium", "Large", "XL"]);
-  const priority = input.priority && VALID_PRIORITIES2.has(input.priority) ? input.priority : "P2 Medium";
+  const priority = input.priority && VALID_PRIORITIES3.has(input.priority) ? input.priority : "P2 Medium";
   const complexity = input.complexity && VALID_COMPLEXITIES2.has(input.complexity) ? input.complexity : "Small";
-  const VALID_TYPES = /* @__PURE__ */ new Set(["task", "bug", "research", "idea", "spike"]);
+  const VALID_TYPES2 = /* @__PURE__ */ new Set(["task", "bug", "research", "idea", "spike", "discovery"]);
   let taskTitle = input.text;
   let taskType = "idea";
-  if (input.type && VALID_TYPES.has(input.type)) {
+  let typeInferred = false;
+  if (input.type && VALID_TYPES2.has(input.type)) {
     taskType = input.type;
   } else {
     const PREFIX_MAP = {
@@ -17820,6 +18393,20 @@ ${lines.join("\n")}
         taskType = PREFIX_MAP[key];
         taskTitle = input.text.slice(prefixMatch[0].length);
       }
+    } else {
+      const searchText = `${input.text} ${input.notes ?? ""}`.toLowerCase();
+      if (/\b(bug|fix|broken|crash|error)\b/.test(searchText)) {
+        taskType = "bug";
+      } else if (/\b(research|investigate|explore|spike)\b/.test(searchText)) {
+        taskType = "research";
+      } else if (/\b(performance|optimize|speed|latency)\b/.test(searchText)) {
+        taskType = "task";
+      } else if (/\b(verify|confirm)\b/.test(searchText)) {
+        taskType = "spike";
+      } else {
+        taskType = "task";
+      }
+      typeInferred = true;
     }
   }
   const task = await adapter2.createTask({
@@ -17839,7 +18426,8 @@ ${lines.join("\n")}
     taskType,
     maturity: "raw",
     docRef: input.docRef,
-    source: "llm"
+    source: "llm",
+    opportunity: input.opportunity
   });
   if (input.notes && adapter2.updateCycleLearningActionRef) {
     const learningRefs = input.notes.match(/learning:([a-f0-9-]+)/gi);
@@ -17865,7 +18453,27 @@ ${lines.join("\n")}
       }
     }
   }
-  return { routing: "task", task, message: `${task.id}: "${task.title}" \u2014 added to backlog` };
+  if (adapter2.getDogfoodLog && adapter2.updateDogfoodEntryStatus) {
+    try {
+      const dogfoodLog = await adapter2.getDogfoodLog(50);
+      const unlinked = dogfoodLog.filter((e) => e.status === "observed" && !e.linkedTaskId);
+      if (unlinked.length > 0) {
+        const taskText = `${task.title} ${input.notes ?? ""}`.toLowerCase();
+        const taskKeywords = taskText.match(/\b[a-z]{4,}\b/g) ?? [];
+        const taskKeywordSet = new Set(taskKeywords);
+        for (const entry of unlinked) {
+          const entryKeywords = entry.content.toLowerCase().match(/\b[a-z]{4,}\b/g) ?? [];
+          const overlap = entryKeywords.filter((w) => taskKeywordSet.has(w));
+          if (overlap.length >= 2) {
+            await adapter2.updateDogfoodEntryStatus(entry.id, "backlog-created", task.id);
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  const typeNote = typeInferred ? ` [type: ${taskType} \u2014 inferred from text]` : "";
+  return { routing: "task", task, message: `${task.id}: "${task.title}" \u2014 added to backlog${typeNote}` };
 }
 var CANVAS_SECTION_LABELS = {
   landscape: "Landscape References",
@@ -17905,6 +18513,7 @@ async function routeToDiscovery(adapter2, section, input) {
 // src/tools/idea.ts
 var ideaTool = {
   name: "idea",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   description: "Capture an idea as a Backlog task. The next plan run will triage and scope it. Use anytime to log bugs, feature requests, or improvements without interrupting the current cycle. IMPORTANT: If this idea originates from a research or planning session, you MUST include a Reference: line in notes pointing to the source doc. Without it, the planner has no context and will misinterpret the intent. Does not call the Anthropic API.",
   inputSchema: {
     type: "object",
@@ -17915,7 +18524,7 @@ var ideaTool = {
       },
       notes: {
         type: "string",
-        description: 'Additional context, constraints, or reasoning. MANDATORY: If this idea comes from a research or planning session, include a "Reference: <path>" line pointing to the source doc. Tasks submitted without references get misinterpreted by the planner \u2014 this is the #1 cause of wasted build slots (C146: task-807 was scoped as landing page copy when it was actually a dashboard UX task, because the source research doc was missing). Use doc_search to find relevant docs before submitting.'
+        description: 'Additional context, constraints, or reasoning. MANDATORY: If this idea comes from a research or planning session, include a "Reference: <path>" line pointing to the source doc. Tasks submitted without references get misinterpreted by the planner \u2014 this is the #1 cause of wasted build slots (C146: task-807 was scoped as landing page copy when it was actually a dashboard UX task, because the source research doc was missing). Use doc_search to find relevant docs before submitting. TIP: If this idea addresses a known cycle learning, include "learning:<uuid>" in the notes (e.g. "learning:abc12345-..."). This links the idea to the learning entry and marks it actioned in the pipeline. Example: "Addresses recurring friction. learning:3f9a1c2e-..."'
       },
       module: {
         type: "string",
@@ -17949,12 +18558,16 @@ var ideaTool = {
       },
       type: {
         type: "string",
-        enum: ["task", "bug", "research", "spike"],
-        description: 'Task type. Defaults to "task". Use "bug" for defects, "research" for investigation tasks, "spike" for time-boxed experiments. The planner uses this to generate type-specific BUILD HANDOFFs.'
+        enum: ["task", "bug", "research", "spike", "discovery"],
+        description: 'Task type. Defaults to "task". Use "bug" for defects, "research" for investigation tasks, "spike" for time-boxed experiments, "discovery" for issues found during a build that need their own task. The planner uses this to generate type-specific BUILD HANDOFFs.'
       },
       doc_ref: {
         type: "string",
         description: 'Path to a reference document (e.g. "docs/research/foo.md"). Stored as a structured field \u2014 replaces the fragile "Reference:" line in notes.'
+      },
+      opportunity: {
+        type: "string",
+        description: "What user problem does this solve? Auto-fill from problem context in notes when submitting ideas that describe a user pain point. The planner uses this to cluster backlog tasks by opportunity."
       }
     },
     required: ["text"]
@@ -17983,7 +18596,8 @@ async function handleIdea(adapter2, config2, args) {
     discovery: args.discovery === true,
     force: args.force === true,
     docRef: args.doc_ref?.trim(),
-    type: args.type
+    type: args.type,
+    opportunity: args.opportunity?.trim()
   };
   const useGit = isGitAvailable() && isGitRepo(config2.projectRoot);
   const currentBranch = useGit ? getCurrentBranch(config2.projectRoot) : null;
@@ -18090,6 +18704,7 @@ function collectDiagnostics(config2) {
 var bugTool = {
   name: "bug",
   description: "Report a bug. Two modes: (1) Default \u2014 creates a Backlog task with severity-based priority for the project board. (2) With report=true \u2014 submits a diagnostic bug report with system info for cross-project visibility (external user issue reporting). Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -18233,16 +18848,16 @@ async function recordAdHoc(adapter2, input) {
       displayId: "",
       title: input.title,
       status: "Done",
-      priority: "P3 Low",
+      priority: input.priority || "P2 Medium",
       complexity: input.effort === "XS" || input.effort === "S" ? "Small" : "Medium",
       module: input.module || "Core",
       epic: input.epic || "Platform",
       phase,
-      owner: "Cathal",
+      owner: input.owner || "Cathal",
       reviewed: true,
       createdCycle: cycle,
       notes: input.notes ? `[ad-hoc] ${input.notes}` : "[ad-hoc]",
-      taskType: "task",
+      taskType: input.taskType || "task",
       source: "owner"
     });
   }
@@ -18267,9 +18882,20 @@ async function recordAdHoc(adapter2, input) {
 
 // src/tools/ad-hoc.ts
 var VALID_EFFORTS = ["XS", "S", "M", "L", "XL"];
+var VALID_PRIORITIES = ["P0 Critical", "P1 High", "P2 Medium", "P3 Low"];
+var VALID_TYPES = ["task", "bug", "research", "discovery", "spike", "idea"];
+function inferTaskType(description) {
+  const lower = description.toLowerCase();
+  if (/\bfix\b|bug|error|crash|broken|regression|defect/.test(lower)) return "bug";
+  if (/research|investigate|explore|analysis|audit|review|assess/.test(lower)) return "research";
+  if (/discover|discovery|found|uncovered/.test(lower)) return "discovery";
+  if (/spike|poc|proof.of.concept|prototype|experiment/.test(lower)) return "spike";
+  return "task";
+}
 var adHocTool = {
   name: "ad_hoc",
   description: "Record work done outside the normal cycle. Creates a Done task with a lightweight build report, or associates work with an existing task if task_id is provided (without changing task status \u2014 use build_execute for status transitions). Use for quick fixes, bug patches, or ad-hoc changes. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -18297,6 +18923,16 @@ var adHocTool = {
       epic: {
         type: "string",
         description: 'Epic this relates to (default: "Platform").'
+      },
+      priority: {
+        type: "string",
+        enum: ["P0 Critical", "P1 High", "P2 Medium", "P3 Low"],
+        description: "Task priority (default: P2 Medium). Use P1 for important fixes, P0 for critical incidents."
+      },
+      type: {
+        type: "string",
+        enum: ["task", "bug", "research", "discovery", "spike", "idea"],
+        description: 'Task type (default: inferred from description \u2014 "fix"/"bug" \u2192 bug, "research"/"investigate" \u2192 research, otherwise task).'
       }
     },
     required: []
@@ -18312,6 +18948,14 @@ async function handleAdHoc(adapter2, config2, args) {
   if (!VALID_EFFORTS.includes(effortRaw)) {
     return errorResponse(`effort must be one of: ${VALID_EFFORTS.join(", ")}`);
   }
+  const priorityRaw = args.priority || "P2 Medium";
+  if (!VALID_PRIORITIES.includes(priorityRaw)) {
+    return errorResponse(`priority must be one of: ${VALID_PRIORITIES.join(", ")}`);
+  }
+  const typeRaw = args.type || inferTaskType(title || (args.notes ?? ""));
+  if (!VALID_TYPES.includes(typeRaw)) {
+    return errorResponse(`type must be one of: ${VALID_TYPES.join(", ")}`);
+  }
   const MAX_NOTES_LENGTH = 2e3;
   let rawNotes = args.notes?.trim();
   let notesTruncated = false;
@@ -18325,7 +18969,11 @@ async function handleAdHoc(adapter2, config2, args) {
     notes: rawNotes,
     effort: effortRaw,
     module: args.module,
-    epic: args.epic
+    epic: args.epic,
+    priority: priorityRaw,
+    taskType: typeRaw,
+    // PROJECT-SPECIFIC: owner resolved from config (PAPI_OWNER env var, default 'Cathal')
+    owner: config2.projectOwner
   });
   if (isGitAvailable() && isGitRepo(config2.projectRoot)) {
     try {
@@ -18338,8 +18986,11 @@ async function handleAdHoc(adapter2, config2, args) {
     }
   }
   const truncateWarning = notesTruncated ? ` (notes truncated to ${MAX_NOTES_LENGTH} chars)` : "";
+  const taskModule = result.task.module || "Core";
+  const typeLabel = result.task.taskType || typeRaw;
   return textResponse(
-    `**${result.task.id}:** "${result.task.title}" \u2014 recorded as ad-hoc (${effortRaw}). Build report attached.${truncateWarning}`
+    `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule}).${truncateWarning} Build report attached.
+_To correct: board_edit ${result.task.id} with updated fields._`
   );
 }
 
@@ -18480,9 +19131,9 @@ async function prepareReconcile(adapter2) {
   }
   return lines.join("\n");
 }
-var STOP_WORDS2 = /* @__PURE__ */ new Set(["the", "a", "an", "and", "or", "for", "in", "on", "to", "of", "is", "with", "from", "by", "vs", "not", "no", "do"]);
+var STOP_WORDS3 = /* @__PURE__ */ new Set(["the", "a", "an", "and", "or", "for", "in", "on", "to", "of", "is", "with", "from", "by", "vs", "not", "no", "do"]);
 function tokenize(s) {
-  return s.toLowerCase().replace(/[^a-z0-9\s-]/g, "").split(/\s+/).filter((w) => w.length > 2 && !STOP_WORDS2.has(w));
+  return s.toLowerCase().replace(/[^a-z0-9\s-]/g, "").split(/\s+/).filter((w) => w.length > 2 && !STOP_WORDS3.has(w));
 }
 function titleKeywords(title) {
   return new Set(tokenize(title));
@@ -18562,7 +19213,7 @@ async function applyReconcile(adapter2, corrections) {
   }
   return { applied, skipped, details, phaseChanges };
 }
-var VALID_PRIORITIES = /* @__PURE__ */ new Set(["P0 Critical", "P1 High", "P2 Medium", "P3 Low"]);
+var VALID_PRIORITIES2 = /* @__PURE__ */ new Set(["P0 Critical", "P1 High", "P2 Medium", "P3 Low"]);
 var VALID_COMPLEXITIES = /* @__PURE__ */ new Set(["XS", "Small", "Medium", "Large", "XL"]);
 async function prepareRetriage(adapter2) {
   const health = await adapter2.getCycleHealth();
@@ -18623,7 +19274,7 @@ async function applyRetriage(adapter2, retriages) {
         skipped++;
         continue;
       }
-      if (!VALID_PRIORITIES.has(r.priority)) {
+      if (!VALID_PRIORITIES2.has(r.priority)) {
         details.push(`${r.taskId}: skipped \u2014 invalid priority "${r.priority}"`);
         skipped++;
         continue;
@@ -18659,6 +19310,7 @@ async function applyRetriage(adapter2, retriages) {
 var boardReconcileTool = {
   name: "board_reconcile",
   description: 'Holistic backlog review to group, merge, cancel, defer, or retriage tasks. "prepare"/"apply" for cleanup. "retriage-prepare"/"retriage-apply" to reassess priority and complexity on existing backlog tasks. Does not call the Anthropic API.',
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -18989,451 +19641,118 @@ Assess each task above and produce your retriage output. Then call \`board_recon
   return errorResponse(`Unknown mode: ${mode}. Use "prepare", "apply", "retriage-prepare", or "retriage-apply".`);
 }
 
-// src/services/health.ts
-function computeHealthScore(cycleNumber, snapshots, activeTasks, decisionUsage) {
-  if (cycleNumber < 3) return null;
-  const scores = [];
-  const recentSnaps = snapshots.slice(-3);
-  const baselineSnaps = snapshots.slice(-10);
-  if (recentSnaps.length > 0 && baselineSnaps.length > 0) {
-    const avg = (snaps) => snaps.reduce((s, sn) => s + (sn.velocity[0]?.effortPoints ?? 0), 0) / snaps.length;
-    const recentAvg = avg(recentSnaps);
-    const baselineAvg = avg(baselineSnaps);
-    const velocityScore = baselineAvg > 0 ? Math.min(100, Math.round(recentAvg / baselineAvg * 100)) : 50;
-    scores.push({ name: "Velocity", score: velocityScore, weight: 0.25 });
-  } else {
-    scores.push({ name: "Velocity", score: 50, weight: 0.25 });
+// src/services/release.ts
+init_git();
+import { writeFile as writeFile3 } from "fs/promises";
+import { join as join6 } from "path";
+var INITIAL_RELEASE_NOTES = `# Changelog
+
+## v0.1.0-alpha \u2014 Initial Release
+
+PAPI MCP Server \u2014 the AI-powered project planning framework.
+
+### Commands
+- **setup** \u2014 Initialise a new PAPI project with Product Brief generation
+- **plan** \u2014 Run cycle planning with embedded BUILD HANDOFFs (Bootstrap + Full modes)
+- **build_list / build_describe / build_execute / build_cancel** \u2014 Manage build tasks
+- **board_view / board_deprioritise / board_archive** \u2014 View and manage the Board
+- **strategy_review / strategy_change** \u2014 Run Strategy Reviews and apply strategic changes
+- **review_list / review_submit** \u2014 Human review loop for handoffs and builds
+- **idea** \u2014 Capture ideas as backlog tasks for future triage
+- **health** \u2014 Cycle Health Summary dashboard
+- **release** \u2014 Cut versioned releases with git tags and changelogs
+
+### Features
+- .md file persistence in .papi/ directory
+- Bootstrap + Full planning modes with Anthropic API integration
+- Embedded BUILD HANDOFFs with dual write-back build reports
+- Auto-commit and auto-PR after builds
+- Board corrections and Active Decision persistence
+- Single-purpose MCP tools for optimal LLM tool selection
+- Consistent error handling across all tools
+`;
+function generateChangelog(version, commits) {
+  const date = (/* @__PURE__ */ new Date()).toISOString();
+  const commitList = commits.map((c) => `- ${c}`).join("\n");
+  return `# Changelog
+
+## ${version} \u2014 ${date}
+
+${commitList}
+`;
+}
+async function createRelease(config2, branch, version, adapter2) {
+  if (!isGitAvailable()) {
+    throw new Error("git is not available.");
   }
-  if (recentSnaps.length > 0) {
-    const avgMatchRate = recentSnaps.reduce((s, sn) => s + (sn.accuracy[0]?.matchRate ?? 0), 0) / recentSnaps.length;
-    scores.push({ name: "Estimation accuracy", score: Math.round(avgMatchRate), weight: 0.25 });
-  } else {
-    scores.push({ name: "Estimation accuracy", score: 50, weight: 0.25 });
+  if (!isGitRepo(config2.projectRoot)) {
+    throw new Error("not a git repository.");
   }
-  const inReviewCount = activeTasks.filter((t) => t.status === "In Review").length;
-  const reviewScore = inReviewCount === 0 ? 100 : inReviewCount <= 2 ? 60 : 20;
-  scores.push({ name: "Review throughput", score: reviewScore, weight: 0.2 });
-  const backlogTasks = activeTasks.filter((t) => t.status === "Backlog");
-  if (backlogTasks.length > 0) {
-    const criticalCount = backlogTasks.filter(
-      (t) => t.priority === "P0 Critical" || t.priority === "P1 High"
-    ).length;
-    const criticalRatio = criticalCount / backlogTasks.length;
-    const backlogScore = criticalRatio > 0.5 ? 40 : criticalRatio > 0.3 ? 70 : 90;
-    scores.push({ name: "Backlog health", score: backlogScore, weight: 0.15 });
-  } else {
-    scores.push({ name: "Backlog health", score: 80, weight: 0.15 });
+  if (hasUncommittedChanges(config2.projectRoot, AUTO_WRITTEN_PATHS)) {
+    throw new Error("working directory has uncommitted changes. Commit or stash them before releasing.");
   }
-  if (decisionUsage.length > 0) {
-    const staleCount = decisionUsage.filter((u) => u.cyclesSinceLastReference >= 10).length;
-    const freshRatio = (decisionUsage.length - staleCount) / decisionUsage.length;
-    scores.push({ name: "AD freshness", score: Math.round(freshRatio * 100), weight: 0.15 });
-  } else {
-    scores.push({ name: "AD freshness", score: 70, weight: 0.15 });
+  const warnings = [];
+  if (adapter2) {
+    try {
+      const versionMatch = version.match(/^v0\.(\d+)\./);
+      const currentCycle = versionMatch ? parseInt(versionMatch[1], 10) : 0;
+      if (currentCycle > 0) {
+        await adapter2.createCycle({
+          id: `cycle-${currentCycle}`,
+          number: currentCycle,
+          status: "complete",
+          startDate: (/* @__PURE__ */ new Date()).toISOString(),
+          endDate: (/* @__PURE__ */ new Date()).toISOString(),
+          goals: [],
+          boardHealth: "",
+          taskIds: []
+        });
+      }
+    } catch (err) {
+      const msg = `createCycle (mark complete) failed: ${err instanceof Error ? err.message : String(err)}`;
+      console.error(`[release] ${msg}`);
+      warnings.push(msg);
+    }
   }
-  const totalScore = Math.round(scores.reduce((sum, s) => sum + s.score * s.weight, 0));
-  const status = totalScore >= 70 ? "GREEN" : totalScore >= 50 ? "AMBER" : "RED";
-  const worst = scores.reduce((min, s) => s.score < min.score ? s : min, scores[0]);
-  const reason = status === "GREEN" ? "All components healthy" : `${worst.name} below target (${worst.score}/100)`;
-  return { score: totalScore, status, reason };
-}
-function countByStatus(tasks) {
-  const counts = /* @__PURE__ */ new Map();
-  for (const task of tasks) {
-    counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+  const checkout = checkoutBranch(config2.projectRoot, branch);
+  if (!checkout.success) {
+    throw new Error(checkout.message);
   }
-  return counts;
-}
-async function getHealthSummary(adapter2) {
-  const health = await adapter2.getCycleHealth();
-  const activeTasks = await adapter2.queryBoard({
-    status: ["Backlog", "In Cycle", "Ready", "In Progress", "In Review", "Blocked"]
-  });
-  const logEntries = await adapter2.getCycleLog(3);
-  const cycleNumber = health.totalCycles;
-  const cyclesSinceReview = health.cyclesSinceLastStrategyReview;
-  const reviewDue = health.strategyReviewDue;
-  const reviewGateBlocking = cyclesSinceReview >= 5;
-  const reviewWarning = reviewGateBlocking ? `\u26A0\uFE0F  GATE \u2014 ${cyclesSinceReview} cycles since last Strategy Review. \`plan\` is blocked until \`strategy_review\` runs (or \`force: true\`).` : `\u2713 On track \u2014 ${cyclesSinceReview} cycle(s) since last review. Next due: ${reviewDue}`;
-  const deferredCount = activeTasks.filter((t) => t.status === "Deferred").length;
-  const nonDeferredTasks = activeTasks.filter((t) => t.status !== "Deferred");
-  const statusCounts = countByStatus(nonDeferredTasks);
-  let boardSummary;
-  if (nonDeferredTasks.length === 0 && deferredCount === 0) {
-    boardSummary = "0 tasks \u2014 board may need reloading";
-  } else {
-    const parts = [];
-    for (const [status, count] of statusCounts) {
-      parts.push(`${count} ${status}`);
-    }
-    boardSummary = `${nonDeferredTasks.length} active tasks \u2014 ${parts.join(", ")}`;
-    if (deferredCount > 0) {
-      boardSummary += ` + ${deferredCount} deferred`;
+  if (hasRemote(config2.projectRoot)) {
+    const pull = gitPull(config2.projectRoot);
+    if (!pull.success) {
+      warnings.push(`git pull failed: ${pull.message}. Run manually.`);
     }
   }
-  const inProgressTasks = activeTasks.filter((t) => t.status === "In Progress");
-  const staleTasks = inProgressTasks.length > 0 ? `${inProgressTasks.length} task(s) In Progress: ${inProgressTasks.map((t) => t.id).join(", ")}` : "No tasks currently In Progress";
-  const inReviewTasks = activeTasks.filter((t) => t.status === "In Review");
-  const inReviewSummary = inReviewTasks.length > 0 ? `${inReviewTasks.length} task(s) ready for sign-off: ${inReviewTasks.map((t) => t.id).join(", ")}` : "No tasks waiting for sign-off";
-  let carryForward = "None found";
-  if (logEntries.length > 0) {
-    const latest = logEntries[0];
-    if (latest.carryForward) {
-      carryForward = latest.carryForward;
-    } else {
-      carryForward = `No carry-forward in Cycle ${latest.cycleNumber}`;
-    }
+  if (tagExists(config2.projectRoot, version)) {
+    throw new Error(`tag "${version}" already exists. Use a different version.`);
   }
-  let recommendedMode;
-  const reasons = [];
-  if (reviewGateBlocking) {
-    reasons.push(`Strategy Review overdue (${cyclesSinceReview} cycles)`);
+  const latestTag = getLatestTag(config2.projectRoot);
+  let changelogContent;
+  if (!latestTag) {
+    changelogContent = INITIAL_RELEASE_NOTES.replace("v0.1.0-alpha", version);
+  } else {
+    const commits = getCommitsSinceTag(config2.projectRoot, latestTag);
+    changelogContent = generateChangelog(version, commits);
   }
-  if (activeTasks.length === 0) {
-    reasons.push("Board is empty \u2014 needs task reload/triage");
+  const changelogPath = join6(config2.projectRoot, "CHANGELOG.md");
+  await writeFile3(changelogPath, changelogContent, "utf-8");
+  const commitResult = stageAllAndCommit(config2.projectRoot, `release: ${version}`);
+  const commitNote = commitResult.committed ? `Committed CHANGELOG.md.` : `CHANGELOG.md: ${commitResult.message}`;
+  const tagResult = createTag(config2.projectRoot, version, `Release ${version}`);
+  if (!tagResult.success) {
+    throw new Error(tagResult.message);
   }
-  const unbuiltCycleTasks = activeTasks.filter(
-    (t) => t.cycle === cycleNumber && (t.status === "In Cycle" || t.status === "Ready")
-  );
-  const inProgressCycleTasks = activeTasks.filter(
-    (t) => t.cycle === cycleNumber && t.status === "In Progress"
-  );
-  const inReviewCycleTasks = activeTasks.filter(
-    (t) => t.cycle === cycleNumber && t.status === "In Review"
-  );
-  if (reasons.length > 0) {
-    recommendedMode = `**Full** \u2014 ${reasons.join("; ")}`;
-  } else if (unbuiltCycleTasks.length > 0) {
-    recommendedMode = `**Build** \u2014 ${unbuiltCycleTasks.length} cycle task(s) not yet started`;
-  } else if (inProgressCycleTasks.length > 0) {
-    recommendedMode = `**Build** \u2014 ${inProgressCycleTasks.length} task(s) in progress`;
-  } else if (inReviewCycleTasks.length > 0) {
-    recommendedMode = `**Review** \u2014 ${inReviewCycleTasks.length} task(s) awaiting review`;
+  const pushNotes = [];
+  if (hasRemote(config2.projectRoot)) {
+    const branchPush = gitPush(config2.projectRoot, branch);
+    pushNotes.push(branchPush.success ? `Pushed '${branch}' to origin.` : `Push branch failed: ${branchPush.message}`);
+    if (!branchPush.success) warnings.push(branchPush.message);
+    const tagPush = gitPush(config2.projectRoot, version);
+    pushNotes.push(tagPush.success ? `Pushed tag '${version}' to origin.` : `Push tag failed: ${tagPush.message}`);
+    if (!tagPush.success) warnings.push(tagPush.message);
   } else {
-    recommendedMode = `**Full** \u2014 ready for next cycle`;
-  }
-  let metricsSection;
-  let derivedMetricsSection = "";
-  let snapshots = [];
-  try {
-    try {
-      const reports = await adapter2.getRecentBuildReports(50);
-      snapshots = computeSnapshotsFromBuildReports(reports);
-    } catch {
-    }
-    metricsSection = formatCycleMetrics(snapshots);
-    derivedMetricsSection = formatDerivedMetrics(snapshots, activeTasks);
-  } catch (_err) {
-    metricsSection = "Could not read methodology metrics.";
-  }
-  try {
-    const recentReports = await adapter2.getRecentBuildReports(50);
-    if (recentReports.length > 0) {
-      const taskCounts = /* @__PURE__ */ new Map();
-      for (const r of recentReports) {
-        taskCounts.set(r.taskId, (taskCounts.get(r.taskId) ?? 0) + 1);
-      }
-      const iterCounts = [...taskCounts.values()];
-      const avgIter = iterCounts.reduce((s, c) => s + c, 0) / iterCounts.length;
-      const multiIterTasks = iterCounts.filter((c) => c > 1).length;
-      if (avgIter > 1 || multiIterTasks > 0) {
-        derivedMetricsSection += `
-
-**Rework**
-- Average iterations: ${avgIter.toFixed(1)} (${multiIterTasks} task${multiIterTasks !== 1 ? "s" : ""} with pushbacks)`;
-      }
-    }
-  } catch {
-  }
-  const costSection = "Disabled \u2014 local MCP, no API costs.";
-  let decisionUsageSection = "";
-  let decisionUsageEntries = [];
-  try {
-    const usage = await adapter2.getDecisionUsage(cycleNumber);
-    decisionUsageEntries = usage;
-    if (usage.length > 0) {
-      const stale = usage.filter((u) => u.cyclesSinceLastReference >= 5);
-      if (stale.length > 0) {
-        const lines = stale.map(
-          (u) => `- ${u.decisionId}: last referenced Cycle ${u.lastReferencedCycle} (${u.cyclesSinceLastReference} cycles ago)`
-        );
-        decisionUsageSection = `**Stale ADs (5+ cycles unreferenced):**
-${lines.join("\n")}`;
-      } else {
-        decisionUsageSection = `All ${usage.length} tracked ADs referenced within last 5 cycles.`;
-      }
-    }
-  } catch {
-  }
-  let decisionLifecycleSection = "";
-  try {
-    const decisions = await adapter2.getActiveDecisions();
-    const lifecycleSummary = formatDecisionLifecycleSummary(decisions);
-    if (lifecycleSummary) {
-      decisionLifecycleSection = `**Lifecycle:** ${lifecycleSummary}`;
-    }
-  } catch {
-  }
-  const decisionScoresSection = "";
-  let contextUtilisationSection = "";
-  try {
-    const utilData = await adapter2.getContextUtilisation?.();
-    if (utilData && utilData.length > 0) {
-      const lines = utilData.filter((u) => u.cycleNumber === cycleNumber).map((u) => `- ${u.tool}: ${(u.avgUtilisation * 100).toFixed(0)}% utilisation (${(u.avgContextBytes / 1024).toFixed(1)}KB avg context)`);
-      if (lines.length > 0) {
-        contextUtilisationSection = `**Current cycle:**
-${lines.join("\n")}`;
-      }
-    }
-  } catch {
-  }
-  let northStarSection = "";
-  try {
-    const staleness = await adapter2.getNorthStarStaleness?.();
-    if (staleness) {
-      const cycleGap = cycleNumber - staleness.setCycle;
-      const daysSinceSet = Math.floor((Date.now() - new Date(staleness.setAt).getTime()) / (1e3 * 60 * 60 * 24));
-      northStarSection = `\u2713 North Star set Cycle ${staleness.setCycle} (${cycleGap} cycles, ${daysSinceSet} days ago)`;
-    } else {
-      const setAtCycle = await adapter2.getNorthStarSetCycle?.();
-      if (setAtCycle != null) {
-        northStarSection = `\u2713 North Star set Cycle ${setAtCycle}`;
-      } else if (adapter2.getCurrentNorthStar) {
-        const ns = await adapter2.getCurrentNorthStar();
-        northStarSection = ns ? "" : "\u26A0\uFE0F No North Star set \u2014 consider defining one";
-      }
-    }
-  } catch {
-  }
-  const healthResult = computeHealthScore(cycleNumber, snapshots, activeTasks, decisionUsageEntries);
-  return {
-    cycleNumber,
-    latestCycleStatus: health.latestCycleStatus,
-    connectionStatus: getConnectionStatus(),
-    reviewWarning,
-    boardSummary,
-    staleTasks,
-    inReviewSummary,
-    carryForward,
-    recommendedMode,
-    metricsSection,
-    derivedMetricsSection,
-    costSection,
-    decisionUsageSection,
-    decisionLifecycleSection,
-    decisionScoresSection,
-    contextUtilisationSection,
-    northStarSection,
-    healthScore: healthResult?.score ?? null,
-    healthStatus: healthResult?.status ?? null,
-    healthReason: healthResult?.reason ?? null
-  };
-}
-
-// src/tools/health.ts
-var healthTool = {
-  name: "health",
-  description: "Cycle Health Summary \u2014 shows current cycle number, Strategy Review cadence status (AD-5), board health (task counts by status, stale tasks), last carry-forward items, and recommended next mode. Read-only, does not modify any files.",
-  inputSchema: {
-    type: "object",
-    properties: {},
-    required: []
-  }
-};
-function formatHealthSummary(summary) {
-  const lines = [];
-  lines.push(`# Cycle ${summary.cycleNumber} \u2014 Health`);
-  lines.push("");
-  if (summary.connectionStatus !== "offline") {
-    const statusIcon = summary.connectionStatus === "connected" ? "\u2713" : "\u26A0\uFE0F";
-    const statusLabel = summary.connectionStatus === "connected" ? "Supabase connected" : "Supabase degraded \u2014 data may be stale. Check DATABASE_URL in .mcp.json";
-    lines.push(`**Connection:** ${statusIcon} ${statusLabel}`);
-    lines.push("");
-  }
-  lines.push(`> **Next action:** ${summary.recommendedMode}`);
-  lines.push("");
-  lines.push(`**Strategy Review:** ${summary.reviewWarning}`);
-  lines.push("");
-  lines.push(`## Board`);
-  lines.push(summary.boardSummary);
-  const hasInProgress = !summary.staleTasks.startsWith("No tasks");
-  const hasInReview = !summary.inReviewSummary.startsWith("No tasks");
-  if (hasInProgress || hasInReview) {
-    lines.push("");
-    if (hasInProgress) lines.push(`- **In Progress:** ${summary.staleTasks}`);
-    if (hasInReview) lines.push(`- **In Review:** ${summary.inReviewSummary}`);
-  }
-  lines.push("");
-  const hasCarryForward = summary.carryForward !== "None found" && !summary.carryForward.startsWith("No carry-forward");
-  if (hasCarryForward) {
-    lines.push(`## Carry-Forward`);
-    lines.push(summary.carryForward);
-    lines.push("");
-  }
-  const hasMetrics = summary.metricsSection !== "Could not read methodology metrics." && !summary.metricsSection.includes("undefined");
-  if (hasMetrics) {
-    lines.push(`## Trends`);
-    lines.push(summary.metricsSection);
-    lines.push("");
-  }
-  if (summary.derivedMetricsSection) {
-    lines.push(`## Insights`);
-    lines.push(summary.derivedMetricsSection);
-    lines.push("");
-  }
-  const hasCost = summary.costSection !== "No metrics data yet." && summary.costSection !== "Could not read metrics data.";
-  if (hasCost) {
-    lines.push(`## Cost`);
-    lines.push(summary.costSection);
-    lines.push("");
-  }
-  if (summary.northStarSection) {
-    lines.push(`## North Star`);
-    lines.push(summary.northStarSection);
-    lines.push("");
-  }
-  if (summary.decisionUsageSection) {
-    lines.push(`## Decision Usage`);
-    lines.push(summary.decisionUsageSection);
-    if (summary.decisionLifecycleSection) {
-      lines.push(summary.decisionLifecycleSection);
-    }
-    lines.push("");
-  }
-  if (summary.contextUtilisationSection) {
-    lines.push(`## Context Utilisation`);
-    lines.push(summary.contextUtilisationSection);
-    lines.push("");
-  }
-  if (summary.decisionScoresSection) {
-    lines.push(`## Decision Scores`);
-    lines.push(summary.decisionScoresSection);
-    lines.push("");
-  }
-  return lines.join("\n").trimEnd();
-}
-async function handleHealth(adapter2) {
-  try {
-    const summary = await getHealthSummary(adapter2);
-    return textResponse(formatHealthSummary(summary));
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return errorResponse(`Could not read cycle health. Run \`setup\` first to initialise your project. (${message})`);
-  }
-}
-
-// src/services/release.ts
-init_git();
-import { writeFile as writeFile3 } from "fs/promises";
-import { join as join6 } from "path";
-var INITIAL_RELEASE_NOTES = `# Changelog
-
-## v0.1.0-alpha \u2014 Initial Release
-
-PAPI MCP Server \u2014 the AI-powered project planning framework.
-
-### Commands
-- **setup** \u2014 Initialise a new PAPI project with Product Brief generation
-- **plan** \u2014 Run cycle planning with embedded BUILD HANDOFFs (Bootstrap + Full modes)
-- **build_list / build_describe / build_execute / build_cancel** \u2014 Manage build tasks
-- **board_view / board_deprioritise / board_archive** \u2014 View and manage the Board
-- **strategy_review / strategy_change** \u2014 Run Strategy Reviews and apply strategic changes
-- **review_list / review_submit** \u2014 Human review loop for handoffs and builds
-- **idea** \u2014 Capture ideas as backlog tasks for future triage
-- **health** \u2014 Cycle Health Summary dashboard
-- **release** \u2014 Cut versioned releases with git tags and changelogs
-
-### Features
-- .md file persistence in .papi/ directory
-- Bootstrap + Full planning modes with Anthropic API integration
-- Embedded BUILD HANDOFFs with dual write-back build reports
-- Auto-commit and auto-PR after builds
-- Board corrections and Active Decision persistence
-- Single-purpose MCP tools for optimal LLM tool selection
-- Consistent error handling across all tools
-`;
-function generateChangelog(version, commits) {
-  const date = (/* @__PURE__ */ new Date()).toISOString();
-  const commitList = commits.map((c) => `- ${c}`).join("\n");
-  return `# Changelog
-
-## ${version} \u2014 ${date}
-
-${commitList}
-`;
-}
-async function createRelease(config2, branch, version, adapter2) {
-  if (!isGitAvailable()) {
-    throw new Error("git is not available.");
-  }
-  if (!isGitRepo(config2.projectRoot)) {
-    throw new Error("not a git repository.");
-  }
-  if (hasUncommittedChanges(config2.projectRoot, AUTO_WRITTEN_PATHS)) {
-    throw new Error("working directory has uncommitted changes. Commit or stash them before releasing.");
-  }
-  const warnings = [];
-  if (adapter2) {
-    try {
-      const versionMatch = version.match(/^v0\.(\d+)\./);
-      const currentCycle = versionMatch ? parseInt(versionMatch[1], 10) : 0;
-      if (currentCycle > 0) {
-        await adapter2.createCycle({
-          id: `cycle-${currentCycle}`,
-          number: currentCycle,
-          status: "complete",
-          startDate: (/* @__PURE__ */ new Date()).toISOString(),
-          endDate: (/* @__PURE__ */ new Date()).toISOString(),
-          goals: [],
-          boardHealth: "",
-          taskIds: []
-        });
-      }
-    } catch (err) {
-      const msg = `createCycle (mark complete) failed: ${err instanceof Error ? err.message : String(err)}`;
-      console.error(`[release] ${msg}`);
-      warnings.push(msg);
-    }
-  }
-  const checkout = checkoutBranch(config2.projectRoot, branch);
-  if (!checkout.success) {
-    throw new Error(checkout.message);
-  }
-  if (hasRemote(config2.projectRoot)) {
-    const pull = gitPull(config2.projectRoot);
-    if (!pull.success) {
-      warnings.push(`git pull failed: ${pull.message}. Run manually.`);
-    }
-  }
-  if (tagExists(config2.projectRoot, version)) {
-    throw new Error(`tag "${version}" already exists. Use a different version.`);
-  }
-  const latestTag = getLatestTag(config2.projectRoot);
-  let changelogContent;
-  if (!latestTag) {
-    changelogContent = INITIAL_RELEASE_NOTES.replace("v0.1.0-alpha", version);
-  } else {
-    const commits = getCommitsSinceTag(config2.projectRoot, latestTag);
-    changelogContent = generateChangelog(version, commits);
-  }
-  const changelogPath = join6(config2.projectRoot, "CHANGELOG.md");
-  await writeFile3(changelogPath, changelogContent, "utf-8");
-  const commitResult = stageAllAndCommit(config2.projectRoot, `release: ${version}`);
-  const commitNote = commitResult.committed ? `Committed CHANGELOG.md.` : `CHANGELOG.md: ${commitResult.message}`;
-  const tagResult = createTag(config2.projectRoot, version, `Release ${version}`);
-  if (!tagResult.success) {
-    throw new Error(tagResult.message);
-  }
-  const pushNotes = [];
-  if (hasRemote(config2.projectRoot)) {
-    const branchPush = gitPush(config2.projectRoot, branch);
-    pushNotes.push(branchPush.success ? `Pushed '${branch}' to origin.` : `Push branch failed: ${branchPush.message}`);
-    if (!branchPush.success) warnings.push(branchPush.message);
-    const tagPush = gitPush(config2.projectRoot, version);
-    pushNotes.push(tagPush.success ? `Pushed tag '${version}' to origin.` : `Push tag failed: ${tagPush.message}`);
-    if (!tagPush.success) warnings.push(tagPush.message);
-  } else {
-    pushNotes.push("Push: skipped (no remote).");
+    pushNotes.push("Push: skipped (no remote).");
   }
   return {
     version,
@@ -19449,6 +19768,7 @@ async function createRelease(config2, branch, version, adapter2) {
 var releaseTool = {
   name: "release",
   description: "Cut a versioned release \u2014 creates a git tag, generates CHANGELOG.md, and pushes to remote.",
+  annotations: { readOnlyHint: false, destructiveHint: true },
   inputSchema: {
     type: "object",
     properties: {
@@ -19459,14 +19779,36 @@ var releaseTool = {
       version: {
         type: "string",
         description: 'The version tag to create (e.g. "v0.1.0-alpha"). Must start with "v".'
-      }
-    },
-    required: ["branch", "version"]
-  }
+      },
+      observations: {
+        type: "array",
+        description: "Optional dogfood observations from this cycle to persist to the DB. Each entry records friction, methodology signals, or commercial insights.",
+        items: {
+          type: "object",
+          properties: {
+            content: { type: "string", description: "The observation text." },
+            category: {
+              type: "string",
+              enum: ["friction", "methodology", "signal", "commercial"],
+              description: "Observation category."
+            },
+            severity: {
+              type: "string",
+              enum: ["P0", "P1", "P2", "P3"],
+              description: "Optional severity for friction/signal observations."
+            }
+          },
+          required: ["content", "category"]
+        }
+      }
+    },
+    required: ["branch", "version"]
+  }
 };
 async function handleRelease(adapter2, config2, args) {
   const branch = args.branch;
   const version = args.version;
+  const rawObservations = args.observations;
   if (!branch || !version) {
     return errorResponse('both branch and version are required. Example: release branch="main" version="v0.1.0-alpha"');
   }
@@ -19504,6 +19846,23 @@ async function handleRelease(adapter2, config2, args) {
       }
     } catch {
     }
+    if (rawObservations && rawObservations.length > 0 && adapter2.writeDogfoodEntries) {
+      try {
+        const cycleMatch = version.match(/^v0\.(\d+)\./);
+        const cycleNum = cycleMatch ? parseInt(cycleMatch[1], 10) : 0;
+        const entries = rawObservations.map((obs) => ({
+          cycleNumber: cycleNum,
+          category: obs.category,
+          content: obs.content,
+          sourceTool: "release",
+          status: "observed"
+        }));
+        await adapter2.writeDogfoodEntries(entries);
+        lines.push("", `Dogfood: ${entries.length} observation(s) saved to DB.`);
+      } catch {
+        lines.push("", "\u26A0\uFE0F Dogfood observations could not be saved to DB \u2014 log them manually in DOGFOOD_LOG.md.");
+      }
+    }
     lines.push("", `Next: cycle released! Run \`plan\` to start your next planning cycle.`);
     return textResponse(lines.join("\n"));
   } catch (err) {
@@ -19629,7 +19988,6 @@ async function submitReview(adapter2, input) {
     handoffRegenPrompt = await prepareHandoffRegen(task, input.comments);
   }
   const stageLabel = input.stage === "handoff-review" ? "Handoff Review" : "Build Acceptance";
-  const slackWarning = void 0;
   let phaseChanges = [];
   if (newStatus) {
     try {
@@ -19645,7 +20003,6 @@ async function submitReview(adapter2, input) {
     newStatus,
     unblockedTasks,
     handoffRegenerated,
-    slackWarning,
     handoffRegenPrompt,
     currentCycle: cycle,
     phaseChanges
@@ -19656,6 +20013,7 @@ async function submitReview(adapter2, input) {
 var reviewListTool = {
   name: "review_list",
   description: "List tasks ready for your sign-off \u2014 shows completed builds waiting for approval or feedback. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {},
@@ -19665,6 +20023,7 @@ var reviewListTool = {
 var reviewSubmitTool = {
   name: "review_submit",
   description: "Record a review verdict on a completed build (build-acceptance) or task plan (handoff-review). ALWAYS ask the human for their verdict before calling \u2014 never auto-submit without human input. Accept moves the task to Done, request-changes sends it back for rework, reject discards the build. Updates task status based on the verdict. On handoff-review with suggested changes, returns a prompt to revise the BUILD HANDOFF.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -19694,10 +20053,6 @@ var reviewSubmitTool = {
         type: "string",
         description: "Your locally-generated BUILD HANDOFF regen output. Pass this to save a handoff that was regenerated in local mode (no API key)."
       },
-      notify: {
-        type: "boolean",
-        description: "Send Slack notification. Default true. Set false for batch middle reviews to avoid spam."
-      },
       auto_review: {
         type: "object",
         description: "Optional automated code review results to attach to this review. Run PR analysis first, then pass findings here.",
@@ -19814,7 +20169,6 @@ async function handleReviewSubmit(adapter2, config2, args) {
   const verdict = args.verdict;
   const comments = args.comments;
   const reviewer = args.reviewer ?? "human";
-  const notify = args.notify !== false;
   const rawAutoReview = args.auto_review;
   let autoReview;
   if (rawAutoReview?.verdict && rawAutoReview?.summary && Array.isArray(rawAutoReview?.findings)) {
@@ -19857,7 +20211,7 @@ async function handleReviewSubmit(adapter2, config2, args) {
   try {
     const result = await submitReview(
       adapter2,
-      { taskId, stage, verdict, comments, reviewer, notify, autoReview }
+      { taskId, stage, verdict, comments, reviewer, autoReview }
     );
     const statusNote = result.newStatus ? ` Task status updated to **${result.newStatus}**.` : " Task status unchanged.";
     const unblockNote = result.unblockedTasks.length > 0 ? `
@@ -19890,15 +20244,42 @@ ${result.handoffRegenPrompt.userMessage}
         mergeNote = "\n\n" + mergeLines.map((l) => `> ${l}`).join("\n");
       }
     }
-    const slackNote = result.slackWarning ? `
-
-${result.slackWarning}` : "";
     let autoReleaseNote = "";
+    let batchSummaryNote = "";
     if (stage === "build-acceptance" && verdict === "accept" && result.newStatus === "Done" && result.currentCycle > 0) {
       try {
         const allTasks = await adapter2.queryBoard();
         const cycleTasks = allTasks.filter((t) => t.cycle === result.currentCycle);
         if (cycleTasks.length > 0 && cycleTasks.every((t) => t.status === "Done")) {
+          try {
+            const allReviews = await adapter2.getRecentReviews(200);
+            const cycleReviews = allReviews.filter(
+              (r) => r.cycle === result.currentCycle && r.stage === "build-acceptance"
+            );
+            const reviewsWithAutoReview = cycleReviews.filter((r) => r.autoReview);
+            if (reviewsWithAutoReview.length > 0) {
+              const verdictCounts = { pass: 0, warn: 0, fail: 0 };
+              const findingsBySeverity = { error: 0, warning: 0, info: 0 };
+              for (const r of reviewsWithAutoReview) {
+                if (r.autoReview) {
+                  verdictCounts[r.autoReview.verdict] = (verdictCounts[r.autoReview.verdict] ?? 0) + 1;
+                  for (const f of r.autoReview.findings) {
+                    findingsBySeverity[f.severity] = (findingsBySeverity[f.severity] ?? 0) + 1;
+                  }
+                }
+              }
+              const totalFindings = findingsBySeverity.error + findingsBySeverity.warning + findingsBySeverity.info;
+              batchSummaryNote = `
+
+---
+
+**Cycle ${result.currentCycle} Auto-Review Summary** (${reviewsWithAutoReview.length}/${cycleReviews.length} reviews had auto-review)
+
+- Verdicts: ${verdictCounts.pass} pass, ${verdictCounts.warn} warn, ${verdictCounts.fail} fail
+` + (totalFindings > 0 ? `- Findings: ${findingsBySeverity.error} error${findingsBySeverity.error !== 1 ? "s" : ""}, ${findingsBySeverity.warning} warning${findingsBySeverity.warning !== 1 ? "s" : ""}, ${findingsBySeverity.info} info` : "- No findings logged");
+            }
+          } catch {
+          }
           const version = `v0.${result.currentCycle}.0`;
           const baseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
           const releaseResult = await createRelease(config2, baseBranch, version, adapter2);
@@ -19943,7 +20324,7 @@ Next: address the feedback, then run \`build_execute ${taskId}\` to resubmit.`;
 - **Verdict:** ${result.verdict}
 - **Comments:** ${result.comments}
 
-${statusNote}${autoReviewNote}${unblockNote}${regenNote}${mergeNote}${slackNote}${autoReleaseNote}${nextStepNote}${phaseNote}`
+${statusNote}${autoReviewNote}${unblockNote}${regenNote}${mergeNote}${batchSummaryNote}${autoReleaseNote}${nextStepNote}${phaseNote}`
     );
   } catch (err) {
     return errorResponse(err instanceof Error ? err.message : String(err));
@@ -19957,6 +20338,7 @@ import path4 from "path";
 var initTool = {
   name: "init",
   description: "Initialise PAPI in the current project. Generates a .mcp.json config file with pg adapter settings pointed at the hosted Supabase instance. Run once per project to get started.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -19966,148 +20348,607 @@ var initTool = {
       },
       force: {
         type: "boolean",
-        description: "Overwrite existing .mcp.json if it already exists. Default: false."
+        description: "Overwrite existing .mcp.json if it already exists. Default: false."
+      }
+    },
+    required: []
+  }
+};
+async function ensureGitignoreEntry(projectRoot, entry) {
+  const gitignorePath = path4.join(projectRoot, ".gitignore");
+  let content = "";
+  try {
+    content = await readFile4(gitignorePath, "utf-8");
+  } catch {
+  }
+  const lines = content.split("\n");
+  if (lines.some((line) => line.trim() === entry)) {
+    return;
+  }
+  const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+  await writeFile4(gitignorePath, content + separator + entry + "\n", "utf-8");
+}
+async function handleInit(config2, args) {
+  const projectRoot = config2.projectRoot;
+  const mcpJsonPath = path4.join(projectRoot, ".mcp.json");
+  const force = args.force === true;
+  const projectName = args.project_name?.trim() || path4.basename(projectRoot);
+  const usingCwdDefault = !process.env.PAPI_PROJECT_DIR && process.argv.indexOf("--project") === -1;
+  let existingConfig = null;
+  try {
+    await access3(mcpJsonPath);
+    existingConfig = await readFile4(mcpJsonPath, "utf-8");
+  } catch {
+  }
+  if (existingConfig && !force) {
+    try {
+      const parsed = JSON.parse(existingConfig);
+      if (parsed.mcpServers?.papi) {
+        return errorResponse(
+          `.mcp.json already exists with a PAPI server configured.
+Use \`init\` with \`force: true\` to overwrite, or edit the file manually.
+Path: ${mcpJsonPath}`
+        );
+      }
+    } catch {
+      if (!force) {
+        return errorResponse(
+          `.mcp.json exists but contains invalid JSON.
+Use \`init\` with \`force: true\` to overwrite.
+Path: ${mcpJsonPath}`
+        );
+      }
+    }
+  }
+  const existingApiKey = process.env.PAPI_DATA_API_KEY;
+  const existingProjectId = process.env.PAPI_PROJECT_ID;
+  const isProxyUser = Boolean(existingApiKey) || config2.adapterType === "proxy";
+  const isDatabaseUser = Boolean(process.env.DATABASE_URL) || config2.adapterType === "pg";
+  if (isProxyUser && existingApiKey && existingProjectId) {
+    const mcpConfig = {
+      mcpServers: {
+        papi: {
+          command: "npx",
+          args: ["-y", "@papi-ai/server"],
+          env: {
+            PAPI_PROJECT_ID: existingProjectId,
+            PAPI_DATA_API_KEY: existingApiKey
+          }
+        }
+      }
+    };
+    await writeFile4(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
+    await ensureGitignoreEntry(projectRoot, ".mcp.json");
+    return textResponse(
+      `# PAPI Initialised \u2014 ${projectName}
+
+**Config:** \`${mcpJsonPath}\`
+
+Your existing API key and project ID have been saved to .mcp.json.
+
+## Next Steps
+
+1. **Restart your MCP client** to pick up the new config.
+2. **Run \`setup\`** \u2014 this scaffolds your project with a Product Brief and CLAUDE.md.
+`
+    );
+  }
+  if (isDatabaseUser) {
+    const projectId = randomUUID14();
+    const mcpConfig = {
+      mcpServers: {
+        papi: {
+          command: "npx",
+          args: ["-y", "@papi-ai/server"],
+          env: {
+            PAPI_PROJECT_DIR: projectRoot,
+            PAPI_ADAPTER: "pg",
+            DATABASE_URL: process.env.DATABASE_URL || "<YOUR_DATABASE_URL>",
+            PAPI_PROJECT_ID: projectId
+          }
+        }
+      }
+    };
+    await writeFile4(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
+    await ensureGitignoreEntry(projectRoot, ".mcp.json");
+    const output2 = [
+      `# PAPI Initialised \u2014 ${projectName}`,
+      "",
+      `**Project ID:** \`${projectId}\``,
+      `**Config:** \`${mcpJsonPath}\``,
+      "",
+      "## Next Steps",
+      "",
+      ...process.env.DATABASE_URL ? ["1. **Restart your MCP client** to pick up the new config."] : ["1. **Set your DATABASE_URL** \u2014 replace `<YOUR_DATABASE_URL>` in `.mcp.json` with your Supabase connection string."],
+      "2. **Run `setup`** \u2014 this scaffolds your project with a Product Brief, Active Decisions, and CLAUDE.md."
+    ].join("\n");
+    return textResponse(output2);
+  }
+  const output = [
+    `# PAPI \u2014 Account Required`,
+    "",
+    `PAPI needs an account to store your project data.`,
+    "",
+    "## Get Started in 3 Steps",
+    "",
+    "1. **Sign up** at https://getpapi.ai/login",
+    "2. **Complete the onboarding wizard** \u2014 it generates your `.mcp.json` config with your API key and project ID",
+    "3. **Download the config**, place it in your project root, and restart your MCP client",
+    "",
+    "The onboarding wizard generates everything you need \u2014 no manual configuration required.",
+    "",
+    `> Already have an account? Make sure both \`PAPI_PROJECT_ID\` and \`PAPI_DATA_API_KEY\` are set in your .mcp.json.`
+  ].join("\n");
+  return textResponse(output);
+}
+
+// src/services/health.ts
+function computeHealthScore(cycleNumber, snapshots, activeTasks, decisionUsage) {
+  if (cycleNumber < 3) return null;
+  const scores = [];
+  const recentSnaps = snapshots.slice(-3);
+  const baselineSnaps = snapshots.slice(-10);
+  if (recentSnaps.length > 0 && baselineSnaps.length > 0) {
+    const avg = (snaps) => snaps.reduce((s, sn) => s + (sn.velocity[0]?.effortPoints ?? 0), 0) / snaps.length;
+    const recentAvg = avg(recentSnaps);
+    const baselineAvg = avg(baselineSnaps);
+    const velocityScore = baselineAvg > 0 ? Math.min(100, Math.round(recentAvg / baselineAvg * 100)) : 50;
+    scores.push({ name: "Velocity", score: velocityScore, weight: 0.25 });
+  } else {
+    scores.push({ name: "Velocity", score: 50, weight: 0.25 });
+  }
+  if (recentSnaps.length > 0) {
+    const avgMatchRate = recentSnaps.reduce((s, sn) => s + (sn.accuracy[0]?.matchRate ?? 0), 0) / recentSnaps.length;
+    scores.push({ name: "Estimation accuracy", score: Math.round(avgMatchRate), weight: 0.25 });
+  } else {
+    scores.push({ name: "Estimation accuracy", score: 50, weight: 0.25 });
+  }
+  const inReviewCount = activeTasks.filter((t) => t.status === "In Review").length;
+  const reviewScore = inReviewCount === 0 ? 100 : inReviewCount <= 2 ? 60 : 20;
+  scores.push({ name: "Review throughput", score: reviewScore, weight: 0.2 });
+  const backlogTasks = activeTasks.filter((t) => t.status === "Backlog");
+  if (backlogTasks.length > 0) {
+    const criticalCount = backlogTasks.filter(
+      (t) => t.priority === "P0 Critical" || t.priority === "P1 High"
+    ).length;
+    const criticalRatio = criticalCount / backlogTasks.length;
+    const backlogScore = criticalRatio > 0.5 ? 40 : criticalRatio > 0.3 ? 70 : 90;
+    scores.push({ name: "Backlog health", score: backlogScore, weight: 0.15 });
+  } else {
+    scores.push({ name: "Backlog health", score: 80, weight: 0.15 });
+  }
+  if (decisionUsage.length > 0) {
+    const staleCount = decisionUsage.filter((u) => u.cyclesSinceLastReference >= 10).length;
+    const freshRatio = (decisionUsage.length - staleCount) / decisionUsage.length;
+    scores.push({ name: "AD freshness", score: Math.round(freshRatio * 100), weight: 0.15 });
+  } else {
+    scores.push({ name: "AD freshness", score: 70, weight: 0.15 });
+  }
+  const totalScore = Math.round(scores.reduce((sum, s) => sum + s.score * s.weight, 0));
+  const status = totalScore >= 70 ? "GREEN" : totalScore >= 50 ? "AMBER" : "RED";
+  const worst = scores.reduce((min, s) => s.score < min.score ? s : min, scores[0]);
+  const reason = status === "GREEN" ? "All components healthy" : `${worst.name} below target (${worst.score}/100)`;
+  return { score: totalScore, status, reason };
+}
+function countByStatus(tasks) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+  }
+  return counts;
+}
+async function getHealthSummary(adapter2) {
+  const health = await adapter2.getCycleHealth();
+  const activeTasks = await adapter2.queryBoard({
+    status: ["Backlog", "In Cycle", "Ready", "In Progress", "In Review", "Blocked"]
+  });
+  const logEntries = await adapter2.getCycleLog(3);
+  const cycleNumber = health.totalCycles;
+  const cyclesSinceReview = health.cyclesSinceLastStrategyReview;
+  const reviewDue = health.strategyReviewDue;
+  const reviewGateBlocking = cyclesSinceReview >= 5;
+  const reviewWarning = reviewGateBlocking ? `\u26A0\uFE0F  GATE \u2014 ${cyclesSinceReview} cycles since last Strategy Review. \`plan\` is blocked until \`strategy_review\` runs (or \`force: true\`).` : `\u2713 On track \u2014 ${cyclesSinceReview} cycle(s) since last review. Next due: ${reviewDue}`;
+  const deferredCount = activeTasks.filter((t) => t.status === "Deferred").length;
+  const nonDeferredTasks = activeTasks.filter((t) => t.status !== "Deferred");
+  const statusCounts = countByStatus(nonDeferredTasks);
+  let boardSummary;
+  if (nonDeferredTasks.length === 0 && deferredCount === 0) {
+    boardSummary = "0 tasks \u2014 board may need reloading";
+  } else {
+    const parts = [];
+    for (const [status, count] of statusCounts) {
+      parts.push(`${count} ${status}`);
+    }
+    boardSummary = `${nonDeferredTasks.length} active tasks \u2014 ${parts.join(", ")}`;
+    if (deferredCount > 0) {
+      boardSummary += ` + ${deferredCount} deferred`;
+    }
+  }
+  const inProgressTasks = activeTasks.filter((t) => t.status === "In Progress");
+  const staleTasks = inProgressTasks.length > 0 ? `${inProgressTasks.length} task(s) In Progress: ${inProgressTasks.map((t) => t.id).join(", ")}` : "No tasks currently In Progress";
+  const inReviewTasks = activeTasks.filter((t) => t.status === "In Review");
+  const inReviewSummary = inReviewTasks.length > 0 ? `${inReviewTasks.length} task(s) ready for sign-off: ${inReviewTasks.map((t) => t.id).join(", ")}` : "No tasks waiting for sign-off";
+  let carryForward = "None found";
+  if (logEntries.length > 0) {
+    const latest = logEntries[0];
+    if (latest.carryForward) {
+      carryForward = latest.carryForward;
+    } else {
+      carryForward = `No carry-forward in Cycle ${latest.cycleNumber}`;
+    }
+  }
+  let recommendedMode;
+  const reasons = [];
+  if (reviewGateBlocking) {
+    reasons.push(`Strategy Review overdue (${cyclesSinceReview} cycles)`);
+  }
+  if (activeTasks.length === 0) {
+    reasons.push("Board is empty \u2014 needs task reload/triage");
+  }
+  const unbuiltCycleTasks = activeTasks.filter(
+    (t) => t.cycle === cycleNumber && (t.status === "In Cycle" || t.status === "Ready")
+  );
+  const inProgressCycleTasks = activeTasks.filter(
+    (t) => t.cycle === cycleNumber && t.status === "In Progress"
+  );
+  const inReviewCycleTasks = activeTasks.filter(
+    (t) => t.cycle === cycleNumber && t.status === "In Review"
+  );
+  if (reasons.length > 0) {
+    recommendedMode = `**Full** \u2014 ${reasons.join("; ")}`;
+  } else if (unbuiltCycleTasks.length > 0) {
+    recommendedMode = `**Build** \u2014 ${unbuiltCycleTasks.length} cycle task(s) not yet started`;
+  } else if (inProgressCycleTasks.length > 0) {
+    recommendedMode = `**Build** \u2014 ${inProgressCycleTasks.length} task(s) in progress`;
+  } else if (inReviewCycleTasks.length > 0) {
+    recommendedMode = `**Review** \u2014 ${inReviewCycleTasks.length} task(s) awaiting review`;
+  } else {
+    recommendedMode = `**Full** \u2014 ready for next cycle`;
+  }
+  let metricsSection;
+  let derivedMetricsSection = "";
+  let snapshots = [];
+  try {
+    try {
+      const reports = await adapter2.getRecentBuildReports(50);
+      snapshots = computeSnapshotsFromBuildReports(reports);
+    } catch {
+    }
+    metricsSection = formatCycleMetrics(snapshots);
+    derivedMetricsSection = formatDerivedMetrics(snapshots, activeTasks);
+  } catch (_err) {
+    metricsSection = "Could not read methodology metrics.";
+  }
+  try {
+    const recentReports = await adapter2.getRecentBuildReports(50);
+    if (recentReports.length > 0) {
+      const taskCounts = /* @__PURE__ */ new Map();
+      for (const r of recentReports) {
+        taskCounts.set(r.taskId, (taskCounts.get(r.taskId) ?? 0) + 1);
+      }
+      const iterCounts = [...taskCounts.values()];
+      const avgIter = iterCounts.reduce((s, c) => s + c, 0) / iterCounts.length;
+      const multiIterTasks = iterCounts.filter((c) => c > 1).length;
+      if (avgIter > 1 || multiIterTasks > 0) {
+        derivedMetricsSection += `
+
+**Rework**
+- Average iterations: ${avgIter.toFixed(1)} (${multiIterTasks} task${multiIterTasks !== 1 ? "s" : ""} with pushbacks)`;
+      }
+    }
+  } catch {
+  }
+  const costSection = "Disabled \u2014 local MCP, no API costs.";
+  let decisionUsageSection = "";
+  let decisionUsageEntries = [];
+  try {
+    const usage = await adapter2.getDecisionUsage(cycleNumber);
+    decisionUsageEntries = usage;
+    if (usage.length > 0) {
+      const stale = usage.filter((u) => u.cyclesSinceLastReference >= 5);
+      if (stale.length > 0) {
+        const lines = stale.map(
+          (u) => `- ${u.decisionId}: last referenced Cycle ${u.lastReferencedCycle} (${u.cyclesSinceLastReference} cycles ago)`
+        );
+        decisionUsageSection = `**Stale ADs (5+ cycles unreferenced):**
+${lines.join("\n")}`;
+      } else {
+        decisionUsageSection = `All ${usage.length} tracked ADs referenced within last 5 cycles.`;
+      }
+    }
+  } catch {
+  }
+  let decisionLifecycleSection = "";
+  try {
+    const decisions = await adapter2.getActiveDecisions();
+    const lifecycleSummary = formatDecisionLifecycleSummary(decisions);
+    if (lifecycleSummary) {
+      decisionLifecycleSection = `**Lifecycle:** ${lifecycleSummary}`;
+    }
+  } catch {
+  }
+  const decisionScoresSection = "";
+  let contextUtilisationSection = "";
+  try {
+    const utilData = await adapter2.getContextUtilisation?.();
+    if (utilData && utilData.length > 0) {
+      const lines = utilData.filter((u) => u.cycleNumber === cycleNumber).map((u) => `- ${u.tool}: ${(u.avgUtilisation * 100).toFixed(0)}% utilisation (${(u.avgContextBytes / 1024).toFixed(1)}KB avg context)`);
+      if (lines.length > 0) {
+        contextUtilisationSection = `**Current cycle:**
+${lines.join("\n")}`;
+      }
+    }
+  } catch {
+  }
+  let northStarSection = "";
+  try {
+    const staleness = await adapter2.getNorthStarStaleness?.();
+    if (staleness) {
+      const cycleGap = cycleNumber - staleness.setCycle;
+      const daysSinceSet = Math.floor((Date.now() - new Date(staleness.setAt).getTime()) / (1e3 * 60 * 60 * 24));
+      northStarSection = `\u2713 North Star set Cycle ${staleness.setCycle} (${cycleGap} cycles, ${daysSinceSet} days ago)`;
+    } else {
+      const setAtCycle = await adapter2.getNorthStarSetCycle?.();
+      if (setAtCycle != null) {
+        northStarSection = `\u2713 North Star set Cycle ${setAtCycle}`;
+      } else if (adapter2.getCurrentNorthStar) {
+        const ns = await adapter2.getCurrentNorthStar();
+        northStarSection = ns ? "" : "\u26A0\uFE0F No North Star set \u2014 consider defining one";
+      }
+    }
+  } catch {
+  }
+  const healthResult = computeHealthScore(cycleNumber, snapshots, activeTasks, decisionUsageEntries);
+  return {
+    cycleNumber,
+    latestCycleStatus: health.latestCycleStatus,
+    connectionStatus: getConnectionStatus(),
+    reviewWarning,
+    boardSummary,
+    staleTasks,
+    inReviewSummary,
+    carryForward,
+    recommendedMode,
+    metricsSection,
+    derivedMetricsSection,
+    costSection,
+    decisionUsageSection,
+    decisionLifecycleSection,
+    decisionScoresSection,
+    contextUtilisationSection,
+    northStarSection,
+    healthScore: healthResult?.score ?? null,
+    healthStatus: healthResult?.status ?? null,
+    healthReason: healthResult?.reason ?? null
+  };
+}
+
+// src/tools/orient.ts
+init_git();
+
+// src/tools/doc-registry.ts
+import { readdirSync as readdirSync4, existsSync as existsSync5, readFileSync as readFileSync2 } from "fs";
+import { join as join8, relative } from "path";
+import { homedir as homedir2 } from "os";
+var docRegisterTool = {
+  name: "doc_register",
+  description: "Register a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: 'Relative path from project root (e.g. "docs/research/funding-landscape.md").' },
+      title: { type: "string", description: "Document title." },
+      type: { type: "string", enum: ["research", "audit", "spec", "guide", "architecture", "positioning", "framework", "reference"], description: "Document type." },
+      status: { type: "string", enum: ["active", "draft", "superseded", "actioned", "legacy", "archived"], description: 'Document status. Defaults to "active".' },
+      summary: { type: "string", description: 'Structured 2-4 sentence summary. Format: "Conclusions: ... Open questions: ... Unactioned: ..."' },
+      tags: { type: "array", items: { type: "string" }, description: "Tags from project vocabulary." },
+      cycle: { type: "number", description: "Current cycle number." },
+      actions: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            description: { type: "string" },
+            status: { type: "string", enum: ["pending", "resolved"] },
+            linkedTaskId: { type: "string" }
+          },
+          required: ["description", "status"]
+        },
+        description: "Actionable findings from the document."
+      },
+      superseded_by_path: { type: "string", description: "Path of the doc that supersedes this one (sets status to superseded)." }
+    },
+    required: ["path", "title", "type", "summary", "cycle"]
+  }
+};
+var docSearchTool = {
+  name: "doc_search",
+  description: "Search the doc registry for documents by type, tags, keyword, or pending actions. Returns summaries, not full content. Use for context gathering in plan, strategy review, and idea dedup.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      type: { type: "string", description: 'Filter by doc type (e.g. "research", "architecture").' },
+      status: { type: "string", description: 'Filter by status. Defaults to "active".' },
+      tags: { type: "array", items: { type: "string" }, description: "Filter by tags (OR match)." },
+      keyword: { type: "string", description: "Search title and summary text." },
+      has_pending_actions: { type: "boolean", description: "Only docs with unresolved action items." },
+      since_cycle: { type: "number", description: "Docs updated since this cycle." },
+      limit: { type: "number", description: "Max results (default: 10)." }
+    },
+    required: []
+  }
+};
+var docScanTool = {
+  name: "doc_scan",
+  description: "Scan docs/ and plans directories for unregistered .md files. Returns a list of files not yet in the doc registry. Use this to find docs that need registration.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      include_plans: {
+        type: "boolean",
+        description: "Also scan ~/.claude/plans/ for plan files (default: false)."
       }
     },
     required: []
   }
 };
-async function ensureGitignoreEntry(projectRoot, entry) {
-  const gitignorePath = path4.join(projectRoot, ".gitignore");
-  let content = "";
+async function handleDocRegister(adapter2, args) {
+  if (!adapter2.registerDoc) {
+    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+  }
+  const path5 = args.path;
+  const title = args.title;
+  const type = args.type;
+  const status = args.status ?? "active";
+  const summary = args.summary;
+  const tags = args.tags ?? [];
+  const cycle = args.cycle;
+  const actions = args.actions;
+  const supersededByPath = args.superseded_by_path;
+  if (!path5 || !title || !type || !summary || !cycle) {
+    return errorResponse("Required fields: path, title, type, summary, cycle.");
+  }
+  let supersededBy;
+  if (supersededByPath) {
+    const existing = await adapter2.getDoc?.(supersededByPath);
+    if (existing) {
+      supersededBy = existing.id;
+      await adapter2.updateDocStatus?.(existing.id, "superseded", void 0);
+    }
+  }
+  const entry = await adapter2.registerDoc({
+    title,
+    type,
+    path: path5,
+    status: supersededByPath ? "superseded" : status,
+    summary,
+    tags,
+    cycleCreated: cycle,
+    cycleUpdated: cycle,
+    supersededBy,
+    actions
+  });
+  return textResponse(
+    `**Registered:** ${entry.title}
+- **Path:** ${entry.path}
+- **Type:** ${entry.type} | **Status:** ${entry.status}
+- **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
+- **Actions:** ${actions?.length ?? 0} items
+- **ID:** ${entry.id}`
+  );
+}
+async function handleDocSearch(adapter2, args) {
+  if (!adapter2.searchDocs) {
+    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+  }
+  const input = {
+    type: args.type,
+    status: args.status,
+    tags: args.tags,
+    keyword: args.keyword,
+    hasPendingActions: args.has_pending_actions,
+    sinceCycle: args.since_cycle,
+    limit: args.limit
+  };
+  const docs = await adapter2.searchDocs(input);
+  if (docs.length === 0) {
+    return textResponse("No documents found matching the search criteria.");
+  }
+  const lines = docs.map((d) => {
+    const actionCount = d.actions?.filter((a) => a.status === "pending").length ?? 0;
+    const actionNote = actionCount > 0 ? ` | ${actionCount} pending action(s)` : "";
+    return `### ${d.title}
+**Type:** ${d.type} | **Status:** ${d.status} | **Cycle:** ${d.cycleCreated}${d.cycleUpdated ? `\u2192${d.cycleUpdated}` : ""}${actionNote}
+**Path:** ${d.path}
+**Tags:** ${d.tags.length > 0 ? d.tags.join(", ") : "none"}
+${d.summary}
+`;
+  });
+  return textResponse(`**${docs.length} document(s) found:**
+
+${lines.join("\n---\n\n")}`);
+}
+function scanMdFiles(dir, rootDir) {
+  if (!existsSync5(dir)) return [];
+  const files = [];
   try {
-    content = await readFile4(gitignorePath, "utf-8");
+    const entries = readdirSync4(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join8(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...scanMdFiles(full, rootDir));
+      } else if (entry.name.endsWith(".md")) {
+        files.push(relative(rootDir, full));
+      }
+    }
   } catch {
   }
-  const lines = content.split("\n");
-  if (lines.some((line) => line.trim() === entry)) {
-    return;
-  }
-  const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
-  await writeFile4(gitignorePath, content + separator + entry + "\n", "utf-8");
+  return files;
 }
-async function handleInit(config2, args) {
-  const projectRoot = config2.projectRoot;
-  const mcpJsonPath = path4.join(projectRoot, ".mcp.json");
-  const force = args.force === true;
-  const projectName = args.project_name?.trim() || path4.basename(projectRoot);
-  const usingCwdDefault = !process.env.PAPI_PROJECT_DIR && process.argv.indexOf("--project") === -1;
-  let existingConfig = null;
+function extractTitle(filePath) {
   try {
-    await access3(mcpJsonPath);
-    existingConfig = await readFile4(mcpJsonPath, "utf-8");
+    const content = readFileSync2(filePath, "utf-8").slice(0, 1e3);
+    const fmMatch = content.match(/^---[\s\S]*?title:\s*(.+?)$/m);
+    if (fmMatch) return fmMatch[1].trim().replace(/^["']|["']$/g, "");
+    const headingMatch = content.match(/^#+\s+(.+)$/m);
+    if (headingMatch) return headingMatch[1].trim();
   } catch {
   }
-  if (existingConfig && !force) {
-    try {
-      const parsed = JSON.parse(existingConfig);
-      if (parsed.mcpServers?.papi) {
-        return errorResponse(
-          `.mcp.json already exists with a PAPI server configured.
-Use \`init\` with \`force: true\` to overwrite, or edit the file manually.
-Path: ${mcpJsonPath}`
-        );
-      }
-    } catch {
-      if (!force) {
-        return errorResponse(
-          `.mcp.json exists but contains invalid JSON.
-Use \`init\` with \`force: true\` to overwrite.
-Path: ${mcpJsonPath}`
-        );
-      }
+  return void 0;
+}
+async function handleDocScan(adapter2, config2, args) {
+  if (!adapter2.searchDocs) {
+    return errorResponse("Doc registry not available on this adapter.");
+  }
+  const includePlans = args.include_plans ?? false;
+  const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
+  const registeredPaths = new Set(registered.map((d) => d.path));
+  const docsDir = join8(config2.projectRoot, "docs");
+  const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
+  const unregisteredDocs = docsFiles.filter((f) => !registeredPaths.has(f));
+  let unregisteredPlans = [];
+  if (includePlans) {
+    const plansDir = join8(homedir2(), ".claude", "plans");
+    if (existsSync5(plansDir)) {
+      const planFiles = scanMdFiles(plansDir, plansDir);
+      unregisteredPlans = planFiles.map((f) => `plans/${f}`).filter((f) => !registeredPaths.has(f)).map((f) => ({
+        path: f,
+        title: extractTitle(join8(plansDir, f.replace("plans/", "")))
+      }));
     }
   }
-  const existingApiKey = process.env.PAPI_DATA_API_KEY;
-  const existingProjectId = process.env.PAPI_PROJECT_ID;
-  const isProxyUser = Boolean(existingApiKey) || config2.adapterType === "proxy";
-  const isDatabaseUser = Boolean(process.env.DATABASE_URL) || config2.adapterType === "pg";
-  if (isProxyUser && existingApiKey && existingProjectId) {
-    const mcpConfig = {
-      mcpServers: {
-        papi: {
-          command: "npx",
-          args: ["-y", "@papi-ai/server"],
-          env: {
-            PAPI_PROJECT_ID: existingProjectId,
-            PAPI_DATA_API_KEY: existingApiKey
-          }
-        }
-      }
-    };
-    await writeFile4(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
-    await ensureGitignoreEntry(projectRoot, ".mcp.json");
-    return textResponse(
-      `# PAPI Initialised \u2014 ${projectName}
-
-**Config:** \`${mcpJsonPath}\`
-
-Your existing API key and project ID have been saved to .mcp.json.
-
-## Next Steps
-
-1. **Restart your MCP client** to pick up the new config.
-2. **Run \`setup\`** \u2014 this scaffolds your project with a Product Brief and CLAUDE.md.
-`
-    );
+  const lines = [];
+  if (unregisteredDocs.length === 0 && unregisteredPlans.length === 0) {
+    return textResponse("All docs are registered. No unregistered files found.");
   }
-  if (isDatabaseUser) {
-    const projectId = randomUUID14();
-    const mcpConfig = {
-      mcpServers: {
-        papi: {
-          command: "npx",
-          args: ["-y", "@papi-ai/server"],
-          env: {
-            PAPI_PROJECT_DIR: projectRoot,
-            PAPI_ADAPTER: "pg",
-            DATABASE_URL: process.env.DATABASE_URL || "<YOUR_DATABASE_URL>",
-            PAPI_PROJECT_ID: projectId
-          }
-        }
-      }
-    };
-    await writeFile4(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
-    await ensureGitignoreEntry(projectRoot, ".mcp.json");
-    const output2 = [
-      `# PAPI Initialised \u2014 ${projectName}`,
-      "",
-      `**Project ID:** \`${projectId}\``,
-      `**Config:** \`${mcpJsonPath}\``,
-      "",
-      "## Next Steps",
-      "",
-      ...process.env.DATABASE_URL ? ["1. **Restart your MCP client** to pick up the new config."] : ["1. **Set your DATABASE_URL** \u2014 replace `<YOUR_DATABASE_URL>` in `.mcp.json` with your Supabase connection string."],
-      "2. **Run `setup`** \u2014 this scaffolds your project with a Product Brief, Active Decisions, and CLAUDE.md."
-    ].join("\n");
-    return textResponse(output2);
+  if (unregisteredDocs.length > 0) {
+    lines.push(`## Unregistered Docs (${unregisteredDocs.length})`);
+    for (const f of unregisteredDocs) {
+      const title = extractTitle(join8(config2.projectRoot, f));
+      lines.push(`- \`${f}\`${title ? ` \u2014 ${title}` : ""}`);
+    }
   }
-  const output = [
-    `# PAPI \u2014 Account Required`,
-    "",
-    `PAPI needs an account to store your project data.`,
-    "",
-    "## Get Started in 3 Steps",
-    "",
-    "1. **Sign up** at https://getpapi.ai/login",
-    "2. **Complete the onboarding wizard** \u2014 it generates your `.mcp.json` config with your API key and project ID",
-    "3. **Download the config**, place it in your project root, and restart your MCP client",
-    "",
-    "The onboarding wizard generates everything you need \u2014 no manual configuration required.",
-    "",
-    `> Already have an account? Make sure both \`PAPI_PROJECT_ID\` and \`PAPI_DATA_API_KEY\` are set in your .mcp.json.`
-  ].join("\n");
-  return textResponse(output);
+  if (unregisteredPlans.length > 0) {
+    lines.push("", `## Unregistered Plans (${unregisteredPlans.length})`);
+    for (const p of unregisteredPlans) {
+      lines.push(`- \`${p.path}\`${p.title ? ` \u2014 ${p.title}` : ""}`);
+    }
+  }
+  lines.push("", `Use \`doc_register\` to register these files.`);
+  return textResponse(lines.join("\n"));
 }
 
 // src/tools/orient.ts
-init_git();
 import { execFileSync as execFileSync3 } from "child_process";
-import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync5 } from "fs";
-import { join as join8 } from "path";
+import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync6 } from "fs";
+import { join as join9 } from "path";
 var orientTool = {
   name: "orient",
   description: "Session orientation \u2014 run this FIRST at session start before any other tool. Single call that replaces build_list + health. Returns: cycle number, task counts by status, in-progress/in-review tasks, strategy review cadence, velocity snapshot, recommended next action, and a release reminder when all cycle tasks are Done but release has not run. Read-only, does not modify any files.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {},
@@ -20283,8 +21124,8 @@ function getLatestGitTag(projectRoot) {
 }
 function checkNpmVersionDrift() {
   try {
-    const pkgPath = join8(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+    const pkgPath = join9(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
     const localVersion = pkg.version;
     const packageName = pkg.name;
     const published = execFileSync3("npm", ["view", packageName, "version"], {
@@ -20324,6 +21165,17 @@ async function handleOrient(adapter2, config2) {
     if (!cycleIsComplete && cycleTotal === 0 && cycleDone > 0) {
       buildResult.warnings.unshift(`\u26A0\uFE0F Cycle ${currentCycle} is complete \u2014 all ${cycleDone} task${cycleDone !== 1 ? "s" : ""} Done. Release has not been run. Run \`release\` now.`);
     }
+    try {
+      const p1BacklogTasks = await adapter2.queryBoard({ status: ["Backlog"], priority: ["P1 High"] });
+      const stalledP1 = p1BacklogTasks.filter(
+        (t) => t.createdCycle != null && currentCycle - t.createdCycle >= 3
+      );
+      if (stalledP1.length > 0) {
+        const ids = stalledP1.map((t) => `${t.displayId} (${currentCycle - (t.createdCycle ?? currentCycle)}+ cycles)`).join(", ");
+        buildResult.warnings.push(`\u26A0\uFE0F P1 tasks stalled 3+ cycles: ${ids}`);
+      }
+    } catch {
+    }
     const inProgressItems = buildResult.inProgress.map(
       (t) => `- **${t.id}:** ${t.title} (${t.priority} | ${t.complexity})`
     );
@@ -20379,12 +21231,36 @@ ${versionDrift}` : "";
     try {
       const unrecorded = detectUnrecordedCommits(config2.projectRoot, config2.baseBranch);
       if (unrecorded.length > 0) {
+        const doneTasks = await adapter2.queryBoard({ status: ["Done"] });
+        const adHocDoneTasks = doneTasks.filter((t) => t.cycle == null);
+        const alreadyRecorded = adHocDoneTasks.length >= unrecorded.length;
         const lines = ["\n\n## Unrecorded Work"];
-        lines.push(`${unrecorded.length} commit(s) on ${config2.baseBranch} since last release not captured by \`build_execute\`. Run \`ad_hoc\` to record them.`);
+        if (alreadyRecorded) {
+          lines.push(`${unrecorded.length} commit(s) on ${config2.baseBranch} since last release not matched to \`build_execute\` commits. ${adHocDoneTasks.length} ad_hoc task(s) already recorded \u2014 this work may already be captured. Verify before running \`ad_hoc\` again.`);
+        } else {
+          lines.push(`${unrecorded.length} commit(s) on ${config2.baseBranch} since last release not captured by \`build_execute\`. Run \`ad_hoc\` to record them.`);
+        }
         for (const c of unrecorded) {
           lines.push(`- \`${c.hash}\` ${c.message}`);
         }
-        unrecordedNote = lines.join("\n");
+        unrecordedNote = lines.join("\n");
+      }
+    } catch {
+    }
+    let unregisteredDocsNote = "";
+    try {
+      if (adapter2.searchDocs) {
+        const docsDir = join9(config2.projectRoot, "docs");
+        const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
+        if (docsFiles.length > 0) {
+          const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
+          const registeredPaths = new Set(registered.map((d) => d.path));
+          const unregisteredCount = docsFiles.filter((f) => !registeredPaths.has(f)).length;
+          if (unregisteredCount > 0) {
+            unregisteredDocsNote = `
+\u26A0\uFE0F **${unregisteredCount} unregistered doc(s) in docs/** \u2014 run \`doc_scan\` to review, then \`doc_register\` to index them.`;
+          }
+        }
       }
     } catch {
     }
@@ -20421,16 +21297,33 @@ ${versionDrift}` : "";
       }
     } catch {
     }
-    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot) + ttfvNote + reconciliationNote + unrecordedNote + recsNote + pendingReviewNote + patternsNote + versionNote + enrichmentNote);
+    let unactionedIssuesNote = "";
+    try {
+      const learnings = await adapter2.getCycleLearnings?.({ category: "issue", limit: 20 });
+      if (learnings) {
+        const unactioned = learnings.filter((l) => !l.actionTaken && l.severity && ["P0", "P1", "P2"].includes(l.severity)).slice(0, 5);
+        if (unactioned.length > 0) {
+          const lines = ["\n\n## Unactioned Issues"];
+          for (const issue of unactioned) {
+            const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
+            lines.push(`- **${issue.severity}** (C${issue.cycleNumber} / ${issue.taskId}): ${desc}`);
+          }
+          lines.push("_Run `idea` to log these as backlog tasks, or `board_edit` if already handled._");
+          unactionedIssuesNote = lines.join("\n");
+        }
+      }
+    } catch {
+    }
+    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot) + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + versionNote + enrichmentNote);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return errorResponse(`Orient failed: ${message}`);
   }
 }
 function enrichClaudeMd(projectRoot, cycleNumber) {
-  const claudeMdPath = join8(projectRoot, "CLAUDE.md");
-  if (!existsSync5(claudeMdPath)) return "";
-  const content = readFileSync2(claudeMdPath, "utf-8");
+  const claudeMdPath = join9(projectRoot, "CLAUDE.md");
+  if (!existsSync6(claudeMdPath)) return "";
+  const content = readFileSync3(claudeMdPath, "utf-8");
   const additions = [];
   if (cycleNumber >= 6 && !content.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1)) {
     additions.push(CLAUDE_MD_TIER_1);
@@ -20452,6 +21345,7 @@ function enrichClaudeMd(projectRoot, cycleNumber) {
 var hierarchyUpdateTool = {
   name: "hierarchy_update",
   description: "Update the status of a phase, stage, or horizon in the project hierarchy (AD-14). Accepts a level (phase, stage, or horizon), a name or ID, and a new status. For stages, optionally set exit_criteria \u2014 a checklist defining when the stage is considered done. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -20847,6 +21741,7 @@ async function applyZoomOut(adapter2, llmResponse, cycleNumber) {
 var zoomOutTool = {
   name: "zoom_out",
   description: 'Run a Zoom-Out Retrospective \u2014 a higher-level meta-retrospective that sits above strategy reviews. Analyses the full project arc: every cycle, decision, and pivot. Use when you want to step back and see the big picture after many cycles. First call returns a prompt (prepare phase). Then call again with mode "apply" and your output.',
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -20921,222 +21816,11 @@ ${result.userMessage}
   }
 }
 
-// src/tools/doc-registry.ts
-import { readdirSync as readdirSync4, existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
-import { join as join9, relative } from "path";
-import { homedir as homedir2 } from "os";
-var docRegisterTool = {
-  name: "doc_register",
-  description: "Register a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: 'Relative path from project root (e.g. "docs/research/funding-landscape.md").' },
-      title: { type: "string", description: "Document title." },
-      type: { type: "string", enum: ["research", "audit", "spec", "guide", "architecture", "positioning", "framework", "reference"], description: "Document type." },
-      status: { type: "string", enum: ["active", "draft", "superseded", "actioned", "legacy", "archived"], description: 'Document status. Defaults to "active".' },
-      summary: { type: "string", description: 'Structured 2-4 sentence summary. Format: "Conclusions: ... Open questions: ... Unactioned: ..."' },
-      tags: { type: "array", items: { type: "string" }, description: "Tags from project vocabulary." },
-      cycle: { type: "number", description: "Current cycle number." },
-      actions: {
-        type: "array",
-        items: {
-          type: "object",
-          properties: {
-            description: { type: "string" },
-            status: { type: "string", enum: ["pending", "resolved"] },
-            linkedTaskId: { type: "string" }
-          },
-          required: ["description", "status"]
-        },
-        description: "Actionable findings from the document."
-      },
-      superseded_by_path: { type: "string", description: "Path of the doc that supersedes this one (sets status to superseded)." }
-    },
-    required: ["path", "title", "type", "summary", "cycle"]
-  }
-};
-var docSearchTool = {
-  name: "doc_search",
-  description: "Search the doc registry for documents by type, tags, keyword, or pending actions. Returns summaries, not full content. Use for context gathering in plan, strategy review, and idea dedup.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      type: { type: "string", description: 'Filter by doc type (e.g. "research", "architecture").' },
-      status: { type: "string", description: 'Filter by status. Defaults to "active".' },
-      tags: { type: "array", items: { type: "string" }, description: "Filter by tags (OR match)." },
-      keyword: { type: "string", description: "Search title and summary text." },
-      has_pending_actions: { type: "boolean", description: "Only docs with unresolved action items." },
-      since_cycle: { type: "number", description: "Docs updated since this cycle." },
-      limit: { type: "number", description: "Max results (default: 10)." }
-    },
-    required: []
-  }
-};
-var docScanTool = {
-  name: "doc_scan",
-  description: "Scan docs/ and plans directories for unregistered .md files. Returns a list of files not yet in the doc registry. Use this to find docs that need registration.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      include_plans: {
-        type: "boolean",
-        description: "Also scan ~/.claude/plans/ for plan files (default: false)."
-      }
-    },
-    required: []
-  }
-};
-async function handleDocRegister(adapter2, args) {
-  if (!adapter2.registerDoc) {
-    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
-  }
-  const path5 = args.path;
-  const title = args.title;
-  const type = args.type;
-  const status = args.status ?? "active";
-  const summary = args.summary;
-  const tags = args.tags ?? [];
-  const cycle = args.cycle;
-  const actions = args.actions;
-  const supersededByPath = args.superseded_by_path;
-  if (!path5 || !title || !type || !summary || !cycle) {
-    return errorResponse("Required fields: path, title, type, summary, cycle.");
-  }
-  let supersededBy;
-  if (supersededByPath) {
-    const existing = await adapter2.getDoc?.(supersededByPath);
-    if (existing) {
-      supersededBy = existing.id;
-      await adapter2.updateDocStatus?.(existing.id, "superseded", void 0);
-    }
-  }
-  const entry = await adapter2.registerDoc({
-    title,
-    type,
-    path: path5,
-    status: supersededByPath ? "superseded" : status,
-    summary,
-    tags,
-    cycleCreated: cycle,
-    cycleUpdated: cycle,
-    supersededBy,
-    actions
-  });
-  return textResponse(
-    `**Registered:** ${entry.title}
-- **Path:** ${entry.path}
-- **Type:** ${entry.type} | **Status:** ${entry.status}
-- **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
-- **Actions:** ${actions?.length ?? 0} items
-- **ID:** ${entry.id}`
-  );
-}
-async function handleDocSearch(adapter2, args) {
-  if (!adapter2.searchDocs) {
-    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
-  }
-  const input = {
-    type: args.type,
-    status: args.status,
-    tags: args.tags,
-    keyword: args.keyword,
-    hasPendingActions: args.has_pending_actions,
-    sinceCycle: args.since_cycle,
-    limit: args.limit
-  };
-  const docs = await adapter2.searchDocs(input);
-  if (docs.length === 0) {
-    return textResponse("No documents found matching the search criteria.");
-  }
-  const lines = docs.map((d) => {
-    const actionCount = d.actions?.filter((a) => a.status === "pending").length ?? 0;
-    const actionNote = actionCount > 0 ? ` | ${actionCount} pending action(s)` : "";
-    return `### ${d.title}
-**Type:** ${d.type} | **Status:** ${d.status} | **Cycle:** ${d.cycleCreated}${d.cycleUpdated ? `\u2192${d.cycleUpdated}` : ""}${actionNote}
-**Path:** ${d.path}
-**Tags:** ${d.tags.length > 0 ? d.tags.join(", ") : "none"}
-${d.summary}
-`;
-  });
-  return textResponse(`**${docs.length} document(s) found:**
-
-${lines.join("\n---\n\n")}`);
-}
-function scanMdFiles(dir, rootDir) {
-  if (!existsSync6(dir)) return [];
-  const files = [];
-  try {
-    const entries = readdirSync4(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const full = join9(dir, entry.name);
-      if (entry.isDirectory()) {
-        files.push(...scanMdFiles(full, rootDir));
-      } else if (entry.name.endsWith(".md")) {
-        files.push(relative(rootDir, full));
-      }
-    }
-  } catch {
-  }
-  return files;
-}
-function extractTitle(filePath) {
-  try {
-    const content = readFileSync3(filePath, "utf-8").slice(0, 1e3);
-    const fmMatch = content.match(/^---[\s\S]*?title:\s*(.+?)$/m);
-    if (fmMatch) return fmMatch[1].trim().replace(/^["']|["']$/g, "");
-    const headingMatch = content.match(/^#+\s+(.+)$/m);
-    if (headingMatch) return headingMatch[1].trim();
-  } catch {
-  }
-  return void 0;
-}
-async function handleDocScan(adapter2, config2, args) {
-  if (!adapter2.searchDocs) {
-    return errorResponse("Doc registry not available on this adapter.");
-  }
-  const includePlans = args.include_plans ?? false;
-  const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
-  const registeredPaths = new Set(registered.map((d) => d.path));
-  const docsDir = join9(config2.projectRoot, "docs");
-  const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
-  const unregisteredDocs = docsFiles.filter((f) => !registeredPaths.has(f));
-  let unregisteredPlans = [];
-  if (includePlans) {
-    const plansDir = join9(homedir2(), ".claude", "plans");
-    if (existsSync6(plansDir)) {
-      const planFiles = scanMdFiles(plansDir, plansDir);
-      unregisteredPlans = planFiles.map((f) => `plans/${f}`).filter((f) => !registeredPaths.has(f)).map((f) => ({
-        path: f,
-        title: extractTitle(join9(plansDir, f.replace("plans/", "")))
-      }));
-    }
-  }
-  const lines = [];
-  if (unregisteredDocs.length === 0 && unregisteredPlans.length === 0) {
-    return textResponse("All docs are registered. No unregistered files found.");
-  }
-  if (unregisteredDocs.length > 0) {
-    lines.push(`## Unregistered Docs (${unregisteredDocs.length})`);
-    for (const f of unregisteredDocs) {
-      const title = extractTitle(join9(config2.projectRoot, f));
-      lines.push(`- \`${f}\`${title ? ` \u2014 ${title}` : ""}`);
-    }
-  }
-  if (unregisteredPlans.length > 0) {
-    lines.push("", `## Unregistered Plans (${unregisteredPlans.length})`);
-    for (const p of unregisteredPlans) {
-      lines.push(`- \`${p.path}\`${p.title ? ` \u2014 ${p.title}` : ""}`);
-    }
-  }
-  lines.push("", `Use \`doc_register\` to register these files.`);
-  return textResponse(lines.join("\n"));
-}
-
 // src/tools/sibling-ads.ts
 var getSiblingAdsTool = {
   name: "get_sibling_ads",
   description: "Read Active Decisions from sibling PAPI projects that share the same Supabase instance. Requires PAPI_SIBLING_PROJECT_IDS env var (comma-separated project UUIDs). Returns ADs labelled by source project \u2014 useful for cross-project architectural alignment. pg adapter only \u2014 returns an error if using md or proxy adapter.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21318,6 +22002,7 @@ 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.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21428,12 +22113,14 @@ function isEnabled() {
 }
 function emitTelemetryEvent(event) {
   if (!isEnabled()) return;
+  const userId = event.user_id ?? process.env["PAPI_USER_ID"] ?? void 0;
   const body = {
     project_id: event.project_id,
     tool_name: event.tool_name,
     event_type: event.event_type,
     metadata: event.metadata ?? {}
   };
+  if (userId) body["user_id"] = userId;
   fetch(`${TELEMETRY_SUPABASE_URL}/rest/v1/telemetry_events`, {
     method: "POST",
     headers: {
@@ -21480,7 +22167,6 @@ var TOOLS_REQUIRING_PAPI = /* @__PURE__ */ new Set([
   "idea",
   "bug",
   "ad_hoc",
-  "health",
   "board_reconcile",
   "review_list",
   "review_submit",
@@ -21562,7 +22248,6 @@ function createServer(adapter2, config2) {
       bugTool,
       adHocTool,
       boardReconcileTool,
-      healthTool,
       releaseTool,
       reviewListTool,
       reviewSubmitTool,
@@ -21654,9 +22339,6 @@ function createServer(adapter2, config2) {
       case "board_reconcile":
         result = await handleBoardReconcile(adapter2, config2, safeArgs);
         break;
-      case "health":
-        result = await handleHealth(adapter2);
-        break;
       case "release":
         result = await handleRelease(adapter2, config2, safeArgs);
         break;
@@ -21841,5 +22523,123 @@ if (pkgVersion !== "unknown") {
     }
   })();
 }
-var transport = new StdioServerTransport();
-await server.connect(transport);
+var httpPortRaw = process.env["PAPI_HTTP_PORT"] ?? process.env["PORT"];
+var httpPort = httpPortRaw ? parseInt(httpPortRaw, 10) : void 0;
+var httpHost = process.env["PORT"] ? "0.0.0.0" : "127.0.0.1";
+if (httpPort) {
+  if (isNaN(httpPort) || httpPort < 1 || httpPort > 65535) {
+    process.stderr.write(`[papi] Invalid PAPI_HTTP_PORT: "${process.env.PAPI_HTTP_PORT}". Must be a number between 1 and 65535.
+`);
+    process.exit(1);
+  }
+  const httpToken = process.env.PAPI_HTTP_TOKEN;
+  if (!httpToken) {
+    process.stderr.write("[papi] WARNING: PAPI_HTTP_TOKEN is not set. HTTP transport is unauthenticated \u2014 anyone with the URL can call your PAPI tools. Set PAPI_HTTP_TOKEN to a secret string.\n");
+  }
+  const createServerForRequest = () => {
+    if (adapter && !setupError) {
+      return createServer(adapter, config);
+    }
+    const errorServer = new Server2(
+      { name: "papi", version: pkgVersion },
+      { capabilities: { tools: {} } }
+    );
+    const errorMessage = setupError || "Unknown startup error";
+    errorServer.setRequestHandler(ListToolsRequestSchema2, async () => ({
+      tools: [{
+        name: "setup",
+        description: "PAPI is not connected \u2014 run this tool for setup instructions.",
+        inputSchema: { type: "object", properties: {}, required: [] }
+      }]
+    }));
+    errorServer.setRequestHandler(CallToolRequestSchema2, async () => ({
+      content: [{
+        type: "text",
+        text: `# PAPI Connection Error
+
+${errorMessage}
+
+## Quick Fix
+
+If you haven't set up PAPI yet:
+1. Go to https://getpapi.ai/login and sign up
+2. Complete the onboarding wizard \u2014 it generates your config
+3. Copy the config to your project and restart your AI tool
+
+If you already have an account, check that both **PAPI_PROJECT_ID** and **PAPI_DATA_API_KEY** are set in your .mcp.json env config.`
+      }]
+    }));
+    return errorServer;
+  };
+  const httpServer = createHttpServer((req, res) => {
+    if (req.method === "GET" && req.url === "/healthz") {
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.end("ok");
+      return;
+    }
+    if (httpToken) {
+      const authHeader = req.headers["authorization"] ?? "";
+      const provided = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+      if (provided !== httpToken) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Unauthorized" }));
+        return;
+      }
+    }
+    if (req.url === "/mcp" || req.url === "/sse") {
+      if (req.method === "POST") {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => {
+          let parsedBody;
+          try {
+            parsedBody = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+          } catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid JSON body" }));
+            return;
+          }
+          (async () => {
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+            const reqServer = createServerForRequest();
+            await reqServer.connect(transport);
+            await transport.handleRequest(req, res, parsedBody);
+            await reqServer.close();
+          })().catch((err) => {
+            process.stderr.write(`[papi] HTTP transport error: ${err instanceof Error ? err.message : String(err)}
+`);
+            if (!res.headersSent) {
+              res.writeHead(500, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Internal server error" }));
+            }
+          });
+        });
+        return;
+      }
+      (async () => {
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+        const reqServer = createServerForRequest();
+        await reqServer.connect(transport);
+        await transport.handleRequest(req, res);
+        await reqServer.close();
+      })().catch((err) => {
+        process.stderr.write(`[papi] HTTP transport error: ${err instanceof Error ? err.message : String(err)}
+`);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Internal server error" }));
+        }
+      });
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+  });
+  httpServer.listen(httpPort, httpHost, () => {
+    process.stderr.write(`[papi] HTTP transport listening on http://${httpHost}:${httpPort}/mcp
+`);
+  });
+} else {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}