@papi-ai/server 0.5.3 → 0.6.0-alpha.1

package/dist/index.js

@@ -1556,7 +1556,8 @@ ${TABLE_SEPARATOR}
         return [];
       }
       /** Update or insert an Active Decision block by ID. */
-      async updateActiveDecision(id, body, cycleNumber) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      async updateActiveDecision(id, body, cycleNumber, _action) {
         const content = await this.readOptional("ACTIVE_DECISIONS.md") || "## Active Decisions\n\n";
         await this.write("ACTIVE_DECISIONS.md", updateActiveDecisionInContent(id, body, content, cycleNumber));
       }
@@ -4442,6 +4443,7 @@ function rowToTask(row) {
   if (row.task_type != null) task.taskType = row.task_type;
   if (row.maturity != null) task.maturity = row.maturity;
   if (row.stage_id != null) task.stageId = row.stage_id;
+  if (row.doc_ref != null) task.docRef = row.doc_ref;
   return task;
 }
 function rowToBuildReport(row) {
@@ -4540,6 +4542,8 @@ function rowToCycleLogEntry(row) {
   };
   if (row.carry_forward != null) entry.carryForward = row.carry_forward;
   if (row.notes != null) entry.notes = row.notes;
+  if (row.task_count != null) entry.taskCount = row.task_count;
+  if (row.effort_points != null) entry.effortPoints = row.effort_points;
   return entry;
 }
 function rowToPhase(row) {
@@ -4670,6 +4674,7 @@ function rowToStage(row) {
     sortOrder: row.sort_order,
     horizonId: row.horizon_id,
     projectId: row.project_id,
+    exitCriteria: row.exit_criteria ?? void 0,
     createdAt: row.created_at,
     updatedAt: row.updated_at
   };
@@ -5366,6 +5371,7 @@ CREATE TABLE IF NOT EXISTS cycle_tasks (
   task_type TEXT,
   maturity TEXT,
   stage_id UUID REFERENCES stages(id),
+  doc_ref TEXT,
   PRIMARY KEY (id),
   UNIQUE (project_id, display_id)
 );
@@ -5411,6 +5417,8 @@ CREATE TABLE IF NOT EXISTS planning_log_entries (
   content TEXT DEFAULT ''::text NOT NULL,
   carry_forward TEXT,
   notes TEXT,
+  task_count INTEGER,
+  effort_points INTEGER,
   created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
   updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
   user_id UUID,
@@ -6118,6 +6126,19 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
     `;
         return rows.map(rowToActiveDecision);
       }
+      async getSiblingAds(projectIds) {
+        if (projectIds.length === 0) return [];
+        const rows = await this.sql`
+      SELECT *, project_id FROM active_decisions
+      WHERE project_id = ANY(${projectIds}::uuid[])
+        AND superseded = false
+      ORDER BY project_id, display_id
+    `;
+        return rows.map((row) => ({
+          ...rowToActiveDecision(row),
+          sourceProjectId: row.project_id
+        }));
+      }
       async getCycleLog(limit) {
         if (limit != null) {
           const rows2 = await this.sql`
@@ -6168,21 +6189,25 @@ ${newParts.join("\n")}` : newParts.join("\n");
       }
       async writeCycleLogEntry(entry) {
         await this.sql`
-      INSERT INTO planning_log_entries (project_id, cycle_number, title, content, carry_forward, notes)
+      INSERT INTO planning_log_entries (project_id, cycle_number, title, content, carry_forward, notes, task_count, effort_points)
       VALUES (
         ${this.projectId},
         ${entry.cycleNumber},
         ${entry.title},
         ${entry.content},
         ${entry.carryForward ?? null},
-        ${entry.notes ?? null}
+        ${entry.notes ?? null},
+        ${entry.taskCount ?? null},
+        ${entry.effortPoints ?? null}
       )
       ON CONFLICT (project_id, cycle_number)
       DO UPDATE SET
         title = EXCLUDED.title,
         content = EXCLUDED.content,
         carry_forward = EXCLUDED.carry_forward,
-        notes = EXCLUDED.notes
+        notes = EXCLUDED.notes,
+        task_count = EXCLUDED.task_count,
+        effort_points = EXCLUDED.effort_points
     `;
       }
       async writeStrategyReview(review) {
@@ -6487,19 +6512,44 @@ ${newParts.join("\n")}` : newParts.join("\n");
       WHERE id = ${id} AND project_id = ${this.projectId}
     `;
       }
-      async updateActiveDecision(id, body, cycleNumber) {
+      async updateActiveDecision(id, body, cycleNumber, action) {
+        const newOutcome = action === "supersede" ? "superseded" : action === "resolve" ? "resolved" : void 0;
         if (cycleNumber != null) {
-          await this.sql`
-        UPDATE active_decisions
-        SET body = ${body}, modified_cycle = ${cycleNumber}
-        WHERE project_id = ${this.projectId} AND display_id = ${id}
-      `;
+          if (newOutcome != null) {
+            await this.sql`
+          UPDATE active_decisions
+          SET body = ${body}, modified_cycle = ${cycleNumber},
+            revision_count = revision_count + 1,
+            outcome = ${newOutcome}
+          WHERE project_id = ${this.projectId} AND display_id = ${id}
+        `;
+          } else {
+            await this.sql`
+          UPDATE active_decisions
+          SET body = ${body}, modified_cycle = ${cycleNumber},
+            revision_count = revision_count + 1,
+            outcome = CASE WHEN outcome = 'pending' THEN 'revised' ELSE outcome END
+          WHERE project_id = ${this.projectId} AND display_id = ${id}
+        `;
+          }
         } else {
-          await this.sql`
-        UPDATE active_decisions
-        SET body = ${body}
-        WHERE project_id = ${this.projectId} AND display_id = ${id}
-      `;
+          if (newOutcome != null) {
+            await this.sql`
+          UPDATE active_decisions
+          SET body = ${body},
+            revision_count = revision_count + 1,
+            outcome = ${newOutcome}
+          WHERE project_id = ${this.projectId} AND display_id = ${id}
+        `;
+          } else {
+            await this.sql`
+          UPDATE active_decisions
+          SET body = ${body},
+            revision_count = revision_count + 1,
+            outcome = CASE WHEN outcome = 'pending' THEN 'revised' ELSE outcome END
+          WHERE project_id = ${this.projectId} AND display_id = ${id}
+        `;
+          }
         }
       }
       async upsertActiveDecision(id, body, title, confidence, cycleNumber) {
@@ -6596,7 +6646,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
+        build_handoff, build_report, task_type, maturity, stage_id, doc_ref
       ) VALUES (
         ${this.projectId}, ${displayId}, ${task.title}, ${task.status}, ${task.priority},
         ${normaliseComplexity(task.complexity)}, ${task.module}, ${task.epic ?? null}, ${task.phase}, ${task.owner},
@@ -6608,7 +6658,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
         ${task.buildReport ?? null},
         ${task.taskType ?? null},
         ${task.maturity ?? null},
-        ${task.stageId ?? null}
+        ${task.stageId ?? null},
+        ${task.docRef ?? null}
       )
       RETURNING *
     `;
@@ -6638,6 +6689,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
         if (updates.taskType !== void 0) columnMap["task_type"] = updates.taskType;
         if (updates.maturity !== void 0) columnMap["maturity"] = updates.maturity;
         if (updates.stageId !== void 0) columnMap["stage_id"] = updates.stageId;
+        if (updates.docRef !== void 0) columnMap["doc_ref"] = updates.docRef;
         const keys = Object.keys(columnMap);
         if (keys.length === 0) return;
         await this.sql`
@@ -6724,6 +6776,86 @@ ${newParts.join("\n")}` : newParts.join("\n");
         return rows.map(rowToBuildReport);
       }
       // -------------------------------------------------------------------------
+      // Cycle Learnings
+      // -------------------------------------------------------------------------
+      async appendCycleLearnings(learnings) {
+        if (learnings.length === 0) return;
+        for (const l of learnings) {
+          await this.sql`
+        INSERT INTO cycle_learnings (
+          project_id, task_id, cycle_number, category, severity,
+          summary, detail, tags, related_decision, action_taken, action_ref
+        ) VALUES (
+          ${this.projectId}, ${l.taskId}, ${l.cycleNumber}, ${l.category}, ${l.severity ?? null},
+          ${l.summary}, ${l.detail ?? null}, ${l.tags}, ${l.relatedDecision ?? null},
+          ${l.actionTaken ?? null}, ${l.actionRef ?? null}
+        )
+      `;
+        }
+      }
+      async getCycleLearnings(opts) {
+        const limit = opts?.limit ?? 50;
+        let rows;
+        if (opts?.cycleNumber && opts?.category) {
+          rows = await this.sql`
+        SELECT * FROM cycle_learnings
+        WHERE project_id = ${this.projectId} AND cycle_number = ${opts.cycleNumber} AND category = ${opts.category}
+        ORDER BY created_at DESC LIMIT ${limit}
+      `;
+        } else if (opts?.cycleNumber) {
+          rows = await this.sql`
+        SELECT * FROM cycle_learnings
+        WHERE project_id = ${this.projectId} AND cycle_number = ${opts.cycleNumber}
+        ORDER BY created_at DESC LIMIT ${limit}
+      `;
+        } else if (opts?.category) {
+          rows = await this.sql`
+        SELECT * FROM cycle_learnings
+        WHERE project_id = ${this.projectId} AND category = ${opts.category}
+        ORDER BY created_at DESC LIMIT ${limit}
+      `;
+        } else {
+          rows = await this.sql`
+        SELECT * FROM cycle_learnings
+        WHERE project_id = ${this.projectId}
+        ORDER BY created_at DESC LIMIT ${limit}
+      `;
+        }
+        return rows.map((r) => ({
+          id: r.id,
+          projectId: r.project_id,
+          taskId: r.task_id,
+          cycleNumber: r.cycle_number,
+          category: r.category,
+          severity: r.severity ?? void 0,
+          summary: r.summary,
+          detail: r.detail ?? void 0,
+          tags: r.tags ?? [],
+          relatedDecision: r.related_decision ?? void 0,
+          actionTaken: r.action_taken ?? void 0,
+          actionRef: r.action_ref ?? void 0,
+          createdAt: r.created_at ? r.created_at.toISOString() : void 0
+        }));
+      }
+      async getCycleLearningPatterns() {
+        const rows = await this.sql`
+      SELECT tag,
+             array_agg(DISTINCT cycle_number ORDER BY cycle_number) as cycles,
+             count(DISTINCT cycle_number)::text as frequency
+      FROM cycle_learnings, unnest(tags) AS tag
+      WHERE project_id = ${this.projectId}
+      GROUP BY tag
+      HAVING count(DISTINCT cycle_number) >= 2
+      ORDER BY count(DISTINCT cycle_number) DESC
+      LIMIT 10
+    `;
+        return rows.map((r) => ({
+          tag: r.tag,
+          cycles: r.cycles,
+          frequency: parseInt(r.frequency, 10)
+        }));
+      }
+      // -------------------------------------------------------------------------
       // Reviews
       // -------------------------------------------------------------------------
       async getRecentReviews(count) {
@@ -7091,6 +7223,12 @@ ${newParts.join("\n")}` : newParts.join("\n");
         await this.sql`
       UPDATE stages SET status = ${status}, updated_at = NOW()
       WHERE id = ${stageId} AND project_id = ${this.projectId}
+    `;
+      }
+      async updateStageExitCriteria(stageId, exitCriteria) {
+        await this.sql`
+      UPDATE stages SET exit_criteria = ${exitCriteria}, updated_at = NOW()
+      WHERE id = ${stageId} AND project_id = ${this.projectId}
     `;
       }
       async updateHorizonStatus(horizonId, status) {
@@ -7436,6 +7574,26 @@ ${r.content}` + (r.carry_forward ? `
         return row?.exists ?? false;
       }
       // -------------------------------------------------------------------------
+      // Plan Runs (telemetry)
+      // -------------------------------------------------------------------------
+      async insertPlanRun(entry) {
+        await this.sql`
+      INSERT INTO plan_runs (
+        project_id, cycle_number, context_bytes, duration_ms,
+        task_count_in, task_count_out, backlog_depth, notes
+      ) VALUES (
+        ${this.projectId},
+        ${entry.cycleNumber},
+        ${entry.contextBytes ?? null},
+        ${entry.durationMs ?? null},
+        ${entry.taskCountIn ?? null},
+        ${entry.taskCountOut ?? null},
+        ${entry.backlogDepth ?? null},
+        ${entry.notes ?? null}
+      )
+    `;
+      }
+      // -------------------------------------------------------------------------
       // Task Comments (for plan context)
       // -------------------------------------------------------------------------
       async getRecentTaskComments(limit = 20) {
@@ -7469,6 +7627,20 @@ ${r.content}` + (r.carry_forward ? `
           cycle_number: ref.cycleNumber
         }));
         await this.sql`INSERT INTO entity_references ${this.sql(values2)}`;
+        const adRefs = refs.filter((r) => r.entityType === "active_decision");
+        if (adRefs.length > 0) {
+          const cycleNumber = adRefs.reduce((max, r) => Math.max(max, r.cycleNumber ?? 0), 0);
+          if (cycleNumber > 0) {
+            const adIds = adRefs.map((r) => r.entityId);
+            await this.sql`
+          UPDATE active_decisions
+          SET last_referenced_cycle = ${cycleNumber}
+          WHERE project_id = ${this.projectId}
+            AND display_id = ANY(${adIds})
+            AND (last_referenced_cycle IS NULL OR last_referenced_cycle < ${cycleNumber})
+        `;
+          }
+        }
       }
       async getDecisionUsage(currentCycle) {
         const rows = await this.sql`
@@ -8068,6 +8240,9 @@ var init_proxy_adapter = __esm({
       actionRecommendation(id, cycleNumber) {
         return this.invoke("actionRecommendation", [id, cycleNumber]);
       }
+      dismissRecommendation(id, reason) {
+        return this.invoke("dismissRecommendation", [id, reason]);
+      }
       // --- Decision Events & Scores ---
       appendDecisionEvent(event) {
         return this.invoke("appendDecisionEvent", [event]);
@@ -8301,19 +8476,33 @@ async function createAdapter(optionsOrType, maybePapiDir) {
     }
     case "proxy": {
       const { ProxyPapiAdapter: ProxyPapiAdapter2 } = await Promise.resolve().then(() => (init_proxy_adapter(), proxy_adapter_exports));
+      const dashboardUrl = process.env["PAPI_DASHBOARD_URL"] || "https://papi-web-three.vercel.app";
       const projectId = process.env["PAPI_PROJECT_ID"];
+      const dataApiKey = process.env["PAPI_DATA_API_KEY"];
+      if (!projectId && !dataApiKey) {
+        throw new Error(
+          `PAPI needs an account to store your project data.
+
+Get started in 3 steps:
+  1. Sign up at ${dashboardUrl}/login
+  2. Complete the onboarding wizard \u2014 it generates your .mcp.json config
+  3. Download the config, place it in your project root, and restart Claude Code
+
+Already have an account? Make sure PAPI_DATA_API_KEY and PAPI_PROJECT_ID are set in your .mcp.json env config.`
+        );
+      }
       if (!projectId) {
         throw new Error(
-          "PAPI_PROJECT_ID is required. Generate a UUID (run `uuidgen` in terminal) and set it in your .mcp.json env config."
+          `PAPI_PROJECT_ID is required.
+Visit ${dashboardUrl}/onboard to generate your config, or add PAPI_PROJECT_ID to your .mcp.json env config.`
         );
       }
       const dataEndpoint = process.env["PAPI_DATA_ENDPOINT"] || HOSTED_PROXY_ENDPOINT;
-      const dataApiKey = process.env["PAPI_DATA_API_KEY"];
       if (!dataApiKey) {
         throw new Error(
           `PAPI_DATA_API_KEY is required for proxy mode.
 To get your API key:
-  1. Sign in at ${process.env["PAPI_DASHBOARD_URL"] || "https://papi-web-three.vercel.app"} with GitHub
+  1. Sign up or sign in at ${dashboardUrl}/login
   2. Your API key is shown on the onboarding page (save it \u2014 shown only once)
   3. Add PAPI_DATA_API_KEY to your .mcp.json env config
 If you already have a key, set it in your MCP configuration.`
@@ -8345,11 +8534,15 @@ If you already have a key, set it in your MCP configuration.`
 }
 
 // src/server.ts
-import { access as access4 } from "fs/promises";
+import { access as access4, readdir as readdir2, readFile as readFile5 } from "fs/promises";
+import { join as join9, dirname } from "path";
+import { fileURLToPath } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 
 // src/lib/response.ts
@@ -8473,7 +8666,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" : ""}${notes ? `
+  Reviewed: ${t.reviewed}${t.dependsOn ? ` | Depends on: ${t.dependsOn}` : ""}${hasHandoff ? " | Has BUILD HANDOFF: yes" : ""}${t.docRef ? ` | Doc ref: ${t.docRef}` : ""}${notes ? `
   Notes: ${notes}` : ""}`;
 }
 function formatBoardForPlan(tasks, filters, currentCycle) {
@@ -8542,6 +8735,36 @@ function trendArrow(current, previous, higherIsBetter) {
   const improving = higherIsBetter ? current > previous : current < previous;
   return improving ? " \u2191" : " \u2193";
 }
+var EFFORT_MAP2 = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
+function computeSnapshotsFromBuildReports(reports) {
+  if (reports.length === 0) return [];
+  const byCycleMap = /* @__PURE__ */ new Map();
+  for (const r of reports) {
+    const existing = byCycleMap.get(r.cycle) ?? [];
+    existing.push(r);
+    byCycleMap.set(r.cycle, existing);
+  }
+  const snapshots = [];
+  for (const [sn, cycleReports] of byCycleMap) {
+    const completed = cycleReports.filter((r) => r.completed === "Yes").length;
+    const total = cycleReports.length;
+    const withEffort = cycleReports.filter((r) => r.estimatedEffort && r.actualEffort);
+    const accurate = withEffort.filter((r) => r.estimatedEffort === r.actualEffort).length;
+    const matchRate = withEffort.length > 0 ? Math.round(accurate / withEffort.length * 100) : 0;
+    let effortPoints = 0;
+    for (const r of cycleReports) {
+      effortPoints += EFFORT_MAP2[r.actualEffort] ?? 3;
+    }
+    snapshots.push({
+      cycle: sn,
+      date: (/* @__PURE__ */ new Date()).toISOString(),
+      accuracy: [{ cycle: sn, reports: total, matchRate, mae: 0, bias: 0 }],
+      velocity: [{ cycle: sn, completed, partial: 0, failed: total - completed, effortPoints }]
+    });
+  }
+  snapshots.sort((a, b2) => a.cycle - b2.cycle);
+  return snapshots;
+}
 function formatCycleMetrics(snapshots) {
   if (snapshots.length === 0) return "No methodology metrics yet.";
   const latest = snapshots[snapshots.length - 1];
@@ -9298,7 +9521,7 @@ After your natural language output, include this EXACT format on its own line:
 <!-- PAPI_STRUCTURED_OUTPUT -->
 \`\`\`json
 {
-  "cycleLogTitle": "string \u2014 short descriptive title WITHOUT 'Cycle N' prefix (e.g. 'Board Triage \u2014 Bug Fix' not 'Cycle 5 \u2014 Board Triage \u2014 Bug Fix')",
+  "cycleLogTitle": "string \u2014 short descriptive title WITHOUT 'Cycle N' prefix. Should capture the cycle theme in 3-5 words (e.g. 'MCP Quality + Product Readiness' not 'Cycle 5 \u2014 Board Triage \u2014 Bug Fix'). This is the canonical theme label for the cycle.",
   "cycleLogContent": "string \u2014 5-10 line cycle log body in markdown, NO heading (the ### heading is generated automatically)",
   "cycleLogCarryForward": "string or null \u2014 carry-forward items for next cycle",
   "cycleLogNotes": "string or null \u2014 1-3 lines of cycle-level observations: estimation accuracy, recurring blockers, velocity trends, dependency signals. Omit if no noteworthy observations.",
@@ -9439,6 +9662,7 @@ Standard planning cycle with full board review.
    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.
+   **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\`.
 
 8. **Cycle Log** \u2014 Write 5-10 line entry: what was triaged, what was recommended and why, observations, AD updates.
    **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.
@@ -9461,10 +9685,29 @@ 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.
-   **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"), apply these handoff additions:
-   - Add to SCOPE: "Use the \`frontend-design\` skill for implementation \u2014 it produces higher-quality visual output than manual styling."
-   - Add to ACCEPTANCE CRITERIA: "[ ] Visually verify rendered output in browser before reporting done \u2014 provide localhost URL or screenshot to the user for review."
-   - If the task involves image selection (carousels, hero sections, galleries), add to SCOPE: "Include brand/theme direction constraints for image selection \u2014 specify the visual mood, style references, and what to avoid (e.g. no generic stock portraits)."
+   **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
+   Deliverable: docs/research/[topic]-findings.md (draft path)
+   Review status: pending owner approval
+   Follow-up tasks: DO NOT submit to backlog until owner confirms findings are actionable
+
+   Also add to ACCEPTANCE CRITERIA: "[ ] Findings doc drafted and saved to docs/research/ before submitting any follow-up ideas"
+
+   **Bug task detection:** When a task's task type is "bug" or the title starts with "Bug:" or "Fix:", apply these rules:
+   - **Auto-P1:** If the task's current priority is P2 or lower, upgrade it to "P1 High" via a boardCorrections entry in Part 2. Note the upgrade in Part 1 analysis.
+   - Add a BLAST RADIUS note to the BUILD HANDOFF SCOPE section: "Bug fix \u2014 minimal blast radius. Change only what is necessary to fix the reported behaviour. Do not refactor surrounding code or expand scope."
+   - Add to ACCEPTANCE CRITERIA: "[ ] Fix is targeted \u2014 no unrelated code changed"
+
+   **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:
+   - 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."
+   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection."
+   The planner's job is scoping, not design direction. Design decisions happen at build time via \`.impeccable.md\` and the frontend-design skill \u2014 don't try to write design specs in the handoff.
 
 11. **New Tasks (max 3 per cycle)** \u2014 Actively mine the Recent Build Reports for task candidates. For each report, check:
    - **Discovered Issues:** If a build report lists a discovered issue and no existing board task covers it, propose a new task.
@@ -9659,115 +9902,84 @@ IMPORTANT: You are running as a non-interactive API call. Do NOT ask the user qu
 
 ## OUTPUT PRINCIPLES
 
-- **Full depth, not thin summaries.** Each mandatory section must be substantive \u2014 multiple paragraphs with specific evidence, not compressed bullet points. The reader should understand cross-cycle patterns, not just individual cycle events. If a section would be under 3 sentences, you haven't gone deep enough.
+- **Product impact first, process second.** The reader wants to know: what got better for users, what's broken, what opportunities exist. Internal machinery (AD wording, taxonomy labels, hierarchy status) is secondary \u2014 handle it in a compact appendix, not the main review.
 - **Lead with insight, not data recitation.** Open each section with the strategic takeaway or pattern, THEN support it with cycle data and task references. Bad: "C131 built task-700, C132 built task-710." Good: "The last 5 cycles show a clear shift from infrastructure to user-facing work \u2014 80% of tasks were dashboard or onboarding, up from 30% in the prior review window."
 - **Cycle data first, conversation context second.** Base your review on build reports, cycle logs, board state, and ADs \u2014 not on whatever was discussed earlier in the conversation. If recent conversation context conflicts with the data, flag it but trust the data.
-- **Every conditional section earns its place.** If a conditional section has nothing meaningful to say, skip it entirely. Do not write "No issues found" or "No concerns" \u2014 just omit the section. But the 6 mandatory sections MUST appear with full depth regardless.
+- **Be concise and scannable.** Use short paragraphs, bullet points, and clear headings. Avoid walls of text. The review should be readable in 3 minutes, not 15. Format cycle summaries as compact bullet points, not multi-paragraph narratives.
+- **Every conditional section earns its place.** If a conditional section has nothing meaningful to say, skip it entirely. Do not write "No issues found" or "No concerns" \u2014 just omit the section.
+- **AD housekeeping is an appendix, not the centerpiece.** Just list changes and make them. Don't score every AD individually. Don't ask for approval on wording tweaks \u2014 small changes (confidence bumps, deleting stale ADs, fixing wording) should just happen. Only flag ADs that represent a genuine strategic question.
 
 ## TWO-PHASE DELIVERY
 
-This review is delivered in two phases:
-1. **Phase 1 (this output):** Present the full review \u2014 all 6 mandatory sections with complete analysis, plus any relevant conditional sections. Do NOT compress, summarise, or abbreviate. The user needs to read and discuss the full review before actions are taken.
-2. **Phase 2 (after user discussion):** The structured action breakdown in Part 2 captures concrete next steps. But the user may refine, reject, or add to these after reading Phase 1. The structured output represents your best autonomous assessment \u2014 the user's feedback in conversation refines it.
+1. **Phase 1 (this output):** Present the review \u2014 all 5 mandatory sections plus relevant conditional sections. Be thorough on product gaps and opportunities, compact on housekeeping. The user will discuss and refine before the structured output is applied.
+2. **Phase 2 (after user discussion):** The structured data in Part 2 captures actions. The user may modify these after reading Phase 1.
 
-Present the full review first. Let the analysis breathe. The user will discuss, push back, and refine before acting on the structured output.
+The review should be readable in one sitting. Don't pad sections for depth \u2014 earn every paragraph with a specific insight or actionable finding.
 
 ## YOUR JOB \u2014 STRUCTURED COVERAGE
 
-You MUST cover these 6 sections. Each is mandatory unless explicitly noted as conditional.
+You MUST cover these 5 sections. Each is mandatory.
 
-1. **Cycle-by-Cycle Impact Summary** \u2014 For each cycle since the last review, summarise what was strategically significant \u2014 not just velocity numbers. What capability was added? What blocker was removed? What direction shifted? Reference task IDs. This is the most important section \u2014 it tells the reader what actually happened and why it mattered.
+1. **What Got Built & Why It Matters** \u2014 Compact summary of each cycle since last review. For each cycle: 1-2 bullet points on what shipped and the strategic significance. Reference task IDs. Don't write multi-paragraph narratives per cycle \u2014 keep it scannable. End with the cross-cycle pattern or theme.
 
-2. **Horizon & Phase Progress** \u2014 Is the current horizon/phase plan on track? What phase are we in? What's been completed? What's blocked? If a phase prerequisite is unmet or a decision is pending that blocks the next phase, flag it here. Reference the Forward Horizon if available.
+2. **Product Gaps & User Experience** \u2014 This is the MOST IMPORTANT section. Answer these questions with specifics:
+   - If a new user tried this product tomorrow, what would confuse or break for them?
+   - What features are broken, half-built, or misleading on the dashboard/UI?
+   - What's missing that would make the product noticeably better?
+   - What user experience friction has been reported or observed in dogfood/build reports?
+   Surface real problems, not theoretical ones. Reference specific pages, components, or flows that need attention.
 
-3. **New Tasks & Ideas Since Last Review** \u2014 Count new backlog tasks added since the last review. Assess alignment: are they supporting the current phase/horizon, or drifting toward unrelated work? Flag any clustering patterns (e.g. "5 of 7 new tasks are MCP Server improvements \u2014 this is on-strategy" or "3 new tasks are commercial features with no alpha testers \u2014 premature").
+3. **Opportunities & Growth** \u2014 What's not being built or explored that could move the needle?
+   - Marketing, distribution, community, content opportunities
+   - Methodology improvements that would make cycles more efficient
+   - Features or improvements that would differentiate from competitors
+   - Things the project owner mentioned wanting but that haven't been prioritised
 
-4. **What Changed Strategically** \u2014 Decisions made, direction shifts, carry-forward items resolved or created since last review. Did any strategy_change calls happen? Were any ADs created, modified, or superseded? This section answers: "If I missed the last N cycles, what changed about where this project is going?"
+4. **Strategic Direction Check** \u2014 Brief assessment (not a deep dive):
+   - Is the North Star still accurate? (1-2 sentences, not a multi-paragraph analysis)
+   - Has the target user or problem statement changed?
+   - What carry-forward items are stuck and why?
+   - If the product brief needs updating, include the update in Part 2.
 
-5. **North Star & Product Direction** \u2014 Go beyond "is the North Star still accurate?" and challenge the product direction:
-   - Is the product brief still an accurate description of what this product IS and WHERE it's going? If ADs have been created or superseded since the brief was last updated, the brief may be wrong.
-   - Has the target user changed? Has the scope expanded or contracted in ways the brief doesn't capture?
-   - Are we building for the right problem? Has evidence emerged (from builds, feedback, or market) that the core problem statement needs revision?
-   - Assess North Star drift: Does the North Star's key metric and success definition still align with the current phase, active ADs, and recent build directions? A North Star is drifted when: the metric it tracks is no longer the team's focus, the success criteria reference capabilities that have been deprioritised, or ADs have shifted the product direction away from what the North Star describes. Cycle count since last update is a secondary signal \u2014 a stable, accurate North Star is not stale regardless of age.
-   If this analysis reveals the brief needs updating, you MUST include updated content in \`productBriefUpdates\` in Part 2. Don't just note "the brief is stale" \u2014 write the update.
+5. **AD & Hierarchy Housekeeping** \u2014 Compact appendix. NOT the focus of the review.
+   - List ADs being deleted, modified, or created \u2014 with the change, not a per-AD essay
+   - Just make small changes (confidence bumps, stale AD deletion, wording fixes) \u2014 don't ask for approval
+   - Only flag ADs that represent a genuine strategic question requiring owner input
+   - Note any hierarchy/phase issues worth correcting (1-2 bullets max)
+   - Delete ADs that are legacy, process-level, or redundant without discussion
 
-6. **Active Decision Review + Scoring** \u2014 For each non-superseded AD: is the confidence level still correct? Has evidence emerged that changes anything? Score on 5 dimensions (1-5, lower = better):
-   - **effort** \u2014 Implementation cost (1=trivial, 5=major project)
-   - **risk** \u2014 Likelihood of failure or rework (1=safe, 5=unproven)
-   - **reversibility** \u2014 How hard to undo (1=trivial rollback, 5=permanent)
-   - **scale_cost** \u2014 What this costs at 10x/100x users or data (1=negligible, 5=bottleneck)
-   - **lock_in** \u2014 Dependency on a specific vendor/tool (1=swappable, 5=deeply coupled)
-   Only score ADs where you have enough context to evaluate meaningfully \u2014 skip ADs where scoring would be guesswork.
-   **AD Quality Bar:** ADs are for product and architecture choices that constrain future work \u2014 technology selections, data model designs, UX principles, strategic positioning. They are NOT for: process preferences (commit style, PR size), configuration choices (linter rules, tab width), or temporary workarounds. If a decision doesn't affect what gets built or how it's architected, it's not an AD. Flag any existing ADs that fail this bar for deletion via \`activeDecisionUpdates\` with action \`delete\`.
-   **IMPORTANT:** If your analysis recommends changing an AD's confidence, modifying its body, or creating a new AD, you MUST include it in \`activeDecisionUpdates\` in Part 2. Analysis without persistence is waste \u2014 the next plan won't see your recommendation unless it's in the structured output.
+## CONDITIONAL SECTIONS (include only when genuinely useful \u2014 most reviews should have 0-2 of these)
 
-## CONDITIONAL SECTIONS (include only when relevant)
+6. **Security Posture Review** \u2014 Only if \`[SECURITY]\` tags exist in recent cycle logs.
 
-7. **Security Posture Review** \u2014 Only if \`[SECURITY]\` tags exist in recent cycle logs. List flagged concerns, resolution status, trend, and recommendations.
+7. **Dogfood Friction \u2192 Task Conversion** \u2014 Scan dogfood observations for recurring friction (2+ occurrences without a board task). Convert up to 3 to task proposals via \`actionItems\` in Part 2. Skip if nothing recurring.
 
-8. **Dogfood Friction \u2192 Task Conversion** \u2014 Scan dogfood log entries (if provided in context) for recurring friction points. For each friction entry, decide: convert to task (yes/no). Convert when a friction point has appeared 2+ times without a corresponding board task. Cap at 3 task proposals per review.
-   **How to convert friction to tasks:**
-   - In Part 1, write a "Dogfood Friction \u2192 Tasks" subsection listing each friction entry and your decision (convert or skip with reason).
-   - For each converted friction, add an entry to \`actionItems\` in Part 2 with \`type: "submit"\` and a descriptive \`description\` that includes the task title and scope. Example: \`{"description": "Submit task: Fix deprioritise clearing handoffs unnecessarily \u2014 add flag to preserve handoff on deprioritise", "type": "submit", "target": null}\`
-   - If friction points have been addressed by recent builds, note the resolution and skip them.
-   - This closes the loop between "we noticed a problem" and "we created a task to fix it."
+8. **Architecture Health** \u2014 Only flag genuine broken data paths, config drift, or dead code. Keep it brief \u2014 bullet points, not paragraphs. Skip entirely if nothing found.
 ${compressionJob}
-9. **Architecture Health Check** \u2014 Scan the project context for structural issues that silently degrade quality. Only flag genuine findings \u2014 do not add boilerplate. Check for:
-   - **Broken data paths** \u2014 DB tables that exist but aren't being read by the dashboard, file reads returning empty, API routes with no consumers. Cycle 42 showed an empty product brief going undetected for multiple cycles \u2014 this check catches that class of problem.
-   - **Adapter parity gaps** \u2014 Features implemented in the pg adapter but missing from md (or vice versa). Both adapters must implement the same PapiAdapter interface, but runtime behavior can diverge.
-   - **Config drift** \u2014 Environment variables referenced in code but not documented, stale .env.example entries, MCP config mismatches between what the server expects and what setup/init generates.
-   - **Dead dependencies** \u2014 Packages in package.json that are no longer imported anywhere. These add install time and attack surface.
-   - **Stale prompts or instructions** \u2014 Cycle numbers, AD references, or project-state assumptions in prompts.ts or CLAUDE.md that no longer match reality.
-   - **Stage readiness gaps** \u2014 If the project is approaching or entering an access-widening stage (e.g. Alpha Distribution, Alpha Cohort, Public Launch), check that auth/security phases are complete. Stages that widen who can access the product must have auth hardening and security review as prerequisites \u2014 not post-hoc discoveries.
-   Report findings in a brief "Architecture Health" section in Part 1. If no issues found, skip the section entirely \u2014 do not write "No issues found".
-
-10. **Discovery Canvas Audit** \u2014 If a Discovery Canvas section is provided in context, audit it for completeness and staleness. For each of the 5 canvas sections (Landscape & References, User Journeys, MVP Boundary, Assumptions & Open Questions, Success Signals):
-   - If the section is **empty** and the project has run 5+ cycles, flag it as a gap and suggest a specific enrichment prompt (e.g. "Consider defining your MVP boundary \u2014 what's in v1 and what's deferred?").
-   - If the section has content, assess whether it's still accurate given recent builds and decisions. Flag stale assumptions or outdated references.
-   - If no Discovery Canvas is provided in context, note that the canvas hasn't been initialized and recommend starting with the highest-value section for the project's maturity.
-   Report findings in a "Discovery Canvas Audit" section in Part 1. Persist findings in the \`discoveryGaps\` array in Part 2. If no gaps found, omit the section and use an empty array.
-
-11. **Hierarchy Assessment** \u2014 If hierarchy data (Horizons \u2192 Stages \u2192 Phases with task counts) is provided in context, assess the full project structure:
-   **Phase-level:**
-   - A phase marked "In Progress" with all tasks Done \u2192 flag as ready to close.
-   - A phase marked "Done" with active Backlog/In Progress tasks \u2192 flag as incorrectly closed.
-   - A phase marked "Not Started" while later-ordered phases are active \u2192 flag as out-of-sequence.
-   - If builds in this review window created tasks that don't fit existing phases \u2192 suggest a new phase.
-   **Stage-level:**
-   - If all phases in a stage are Done \u2192 flag the stage as ready to complete. This is a significant milestone.
-   - If the current stage has been active for 15+ cycles \u2192 assess whether it should be split or whether progress is genuinely slow.
-   - If work is happening in phases that belong to a future stage while the current stage has incomplete phases \u2192 flag as scope leak.
-   **Horizon-level:**
-   - If all stages in the active horizon are complete \u2192 flag for Horizon Review (biggest-picture reflection).
-   - If no phase data is provided, skip this section.
-   Report findings in a "Hierarchy Assessment" section in Part 1. Persist findings in the \`stalePhases\` array in Part 2 (include stage/horizon observations too). If no issues found, omit the section and use an empty array.
-
-12. **Structural Drift Detection** \u2014 If decision usage data is provided in context, identify structural decay using drift-based criteria (not pure cycle counts):
-   - **AD drift:** An AD is drifted when its content contradicts recent build evidence, references architecture/capabilities that no longer exist, or has been made redundant by newer ADs. Reference frequency is a secondary signal \u2014 an unreferenced AD that is still accurate is not necessarily stale; an AD referenced last cycle that contradicts shipped code IS drifted.
-   - **Carry-forward drift:** Carry-forward items that have persisted across **3+ cycles** without resolution \u2192 flag as stuck.
-   - **Confidence drift:** ADs with LOW confidence that have not gained supporting evidence within 5 cycles \u2192 flag as unvalidated. ADs where build reports contradict the decision \u2192 flag as confidence should decrease.
-   Use decision usage data as a secondary signal (unreferenced ADs are more likely to be drifted, but verify by checking content alignment). Report findings in a "Structural Drift" section in Part 1. Persist findings in the \`staleDecisions\` array in Part 2. If no issues found, omit the section and use an empty array.
+Note: Hierarchy assessment and structural drift detection are handled within section 5 (AD & Hierarchy Housekeeping). They do not need their own sections.
 
 ## OUTPUT FORMAT
 
 Your output has TWO parts:
 
 ### Part 1: Natural Language Output
-Write your full Strategy Review in markdown. Cover the 6 mandatory sections in order:
-1. **Cycle-by-Cycle Impact Summary** \u2014 what was built and why it mattered
-2. **Horizon & Phase Progress** \u2014 current phase status, blockers, next phase readiness
-3. **New Tasks & Ideas** \u2014 count, alignment assessment, clustering patterns
-4. **What Changed Strategically** \u2014 decisions, direction shifts, carry-forward resolutions
-5. **North Star Validation** \u2014 still accurate? validated or stale?
-6. **Active Decision Review + Scoring** \u2014 per-AD assessment with scores
-
-Then include conditional sections only if relevant:
+Write your Strategy Review in markdown. Cover the 5 mandatory sections in order:
+1. **What Got Built & Why It Matters** \u2014 compact cycle summaries (bullets, not essays)
+2. **Product Gaps & User Experience** \u2014 THE MAIN EVENT. What's broken, confusing, or missing for users.
+3. **Opportunities & Growth** \u2014 what could move the needle that we're not doing
+4. **Strategic Direction Check** \u2014 brief North Star + carry-forward + brief update check
+5. **AD & Hierarchy Housekeeping** \u2014 compact appendix of changes being made
+
+Then include conditional sections only if genuinely useful:
 - **Security Posture Review** \u2014 only if [SECURITY] tags exist
-- **Dogfood Friction \u2192 Tasks** \u2014 only if dogfood entries show recurring unaddressed friction
-- **Architecture Health** \u2014 only if issues found
-- **Discovery Canvas Audit** \u2014 only if gaps or staleness found
-- **Hierarchy Assessment** \u2014 only if hierarchy staleness, phase closure, or stage progression signals detected
-- **Structural Drift** \u2014 only if drifted ADs or stuck carry-forwards found${compressionPart1}
+- **Dogfood Friction \u2192 Tasks** \u2014 only if recurring unaddressed friction
+- **Architecture Health** \u2014 only if broken data paths or config drift found${compressionPart1}
+
+**FORMAT GUIDELINES:**
+- The entire review should be readable in 3-5 minutes
+- Use bullet points and short paragraphs, not walls of text
+- Section 2 (Product Gaps) should be the longest section
+- Section 5 (AD Housekeeping) should be the shortest \u2014 just a change list
 
 ### Part 2: Structured Data Block
 After your natural language output, include this EXACT format on its own line:
@@ -9848,9 +10060,9 @@ Everything in Part 1 (natural language) is **display-only**. Part 2 (structured
 
 **If you analysed it in Part 1, it MUST appear in Part 2 to persist. Empty arrays/null = nothing saved.**
 
-- Recommended AD changes in Part 1? \u2192 Put them in \`activeDecisionUpdates\` with full body including ### heading. Use \`delete\` action (with empty body) to permanently remove non-strategic ADs (implementation details, resolved decisions, library choices). Use \`supersede\` when a decision is replaced by a new one.
-- Scored ADs in Part 1? \u2192 Put scores in \`decisionScores\` array with id, dimensions, and rationale
-- Identified proven insights, direction changes, or deprecated approaches? \u2192 Put the full updated product brief in \`productBriefUpdates\`. This is how strategic learnings get locked into the project's institutional memory. Common triggers: a phase completing, a hypothesis being validated/invalidated, a new constraint emerging, or the North Star evolving.${compressionPersistence}
+- AD changes listed in section 5? \u2192 Put them in \`activeDecisionUpdates\` with full body including ### heading. Use \`delete\` action (with empty body) to permanently remove non-strategic ADs. Small changes (confidence bumps, stale deletions) don't need justification essays \u2014 just make them.
+- Only score ADs in \`decisionScores\` if the review surfaced a genuine strategic question about that AD. Do NOT score every AD \u2014 most reviews should have 0-3 scores at most.
+- Product brief needs updating? \u2192 Put the full updated brief in \`productBriefUpdates\`.${compressionPersistence}
 - Wrote a strategy review in Part 1? \u2192 \`sessionLogTitle\`, \`sessionLogContent\`, \`velocityAssessment\`, \`strategicRecommendations\` must all be populated
 - Made recommendations in Part 1? \u2192 Extract each into \`actionItems\` with a specific type (resolve/submit/close/investigate/defer) and target (AD-N, task-NNN, phase name, or null). Every recommendation must have an action item \u2014 this is how they get tracked and surfaced to the next plan
 - Converted dogfood friction to tasks in Part 1? \u2192 Each converted friction must appear as an \`actionItem\` with \`type: "submit"\`. If it's not in \`actionItems\`, it won't be tracked \u2014 the next plan will never see it
@@ -9944,6 +10156,9 @@ function buildReviewUserMessage(ctx) {
   if (ctx.unregisteredDocs) {
     parts.push("### Unregistered Docs", "", ctx.unregisteredDocs, "");
   }
+  if (ctx.taskComments) {
+    parts.push("### Task Discussion (Recent Comments)", "", ctx.taskComments, "");
+  }
   return parts.join("\n");
 }
 function parseReviewStructuredOutput(raw) {
@@ -10657,10 +10872,15 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
   timings["getPlanContextSummary"] = t();
   if (leanSummary) {
     t = startTimer();
-    const [metricsSnapshots2, reviews2] = await Promise.all([
+    let [metricsSnapshots2, reviews2] = await Promise.all([
       adapter2.readCycleMetrics(),
       adapter2.getRecentReviews(5)
     ]);
+    try {
+      const reports2 = await adapter2.getRecentBuildReports(50);
+      metricsSnapshots2 = computeSnapshotsFromBuildReports(reports2);
+    } catch {
+    }
     timings["metricsAndReviews"] = t();
     t = startTimer();
     let reviewPatternsText2;
@@ -10729,7 +10949,7 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
     return { context: ctx2, contextHashes: newHashes2 };
   }
   t = startTimer();
-  const [decisions, reportsSinceCycle, log, tasks, metricsSnapshots, reviews, phases, dogfoodEntries] = await Promise.all([
+  const [decisions, reportsSinceCycle, log, tasks, rawMetricsSnapshots, reviews, phases, dogfoodEntries] = await Promise.all([
     adapter2.getActiveDecisions(),
     adapter2.getBuildReportsSince(health.totalCycles),
     adapter2.getCycleLog(3),
@@ -10743,8 +10963,9 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
   const reports = reportsSinceCycle.length > 0 ? reportsSinceCycle : await adapter2.getRecentBuildReports(5);
   t = startTimer();
   let buildPatternsText;
+  let allReportsForPatterns = [];
   try {
-    const allReportsForPatterns = await adapter2.getRecentBuildReports(50);
+    allReportsForPatterns = await adapter2.getRecentBuildReports(50);
     const patterns = await detectBuildPatterns(allReportsForPatterns, health.totalCycles, 5);
     buildPatternsText = hasBuildPatterns(patterns) ? formatBuildPatterns(patterns) : void 0;
   } catch {
@@ -10764,6 +10985,7 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
   } catch {
   }
   timings["advisory"] = t();
+  const metricsSnapshots = allReportsForPatterns.length > 0 ? computeSnapshotsFromBuildReports(allReportsForPatterns) : rawMetricsSnapshots.filter((s) => s.accuracy.length > 0 || s.velocity.length > 0);
   logDataSourceSummary("plan (full)", [
     { label: "cycleHealth", hasData: !!health },
     { label: "productBrief", hasData: warnIfEmpty("productBrief", productBrief) },
@@ -10822,7 +11044,7 @@ ${cleanContent}`;
     pendingRecIds = pending.map((r) => r.id);
   } catch {
   }
-  const handoffs = (data.cycleHandoffs ?? []).map((h) => {
+  const handoffs2 = (data.cycleHandoffs ?? []).map((h) => {
     const parsed = parseBuildHandoff(h.buildHandoff);
     if (parsed && !parsed.createdAt) {
       parsed.createdAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -10854,6 +11076,15 @@ ${cleanContent}`;
     });
   }
   const reviewedTaskIds = (data.boardCorrections ?? []).filter((c) => "priority" in c.updates).map((c) => c.taskId);
+  let activeStageId;
+  try {
+    const activeStage = await adapter2.getActiveStage?.();
+    activeStageId = activeStage?.id;
+  } catch {
+  }
+  const effortMapLegacy = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
+  const legacyTaskCount = handoffs2.length;
+  const legacyEffortPoints = handoffs2.reduce((sum, h) => sum + (effortMapLegacy[h.handoff.effort] ?? 3), 0);
   const payload = {
     cycleNumber: newCycleNumber,
     cycleLog: {
@@ -10862,7 +11093,9 @@ ${cleanContent}`;
       title: cleanTitle,
       content: logBlock,
       carryForward: data.cycleLogCarryForward ?? void 0,
-      notes: data.cycleLogNotes ?? void 0
+      notes: data.cycleLogNotes ?? void 0,
+      taskCount: legacyTaskCount > 0 ? legacyTaskCount : void 0,
+      effortPoints: legacyEffortPoints > 0 ? legacyEffortPoints : void 0
     },
     healthUpdates: {
       totalCycles: newCycleNumber,
@@ -10882,19 +11115,26 @@ ${cleanContent}`;
       cycle: newCycleNumber,
       createdCycle: newCycleNumber,
       why: t.why || "",
-      notes: t.notes || ""
-    })),
-    boardCorrections: (data.boardCorrections ?? []).map((c) => ({
-      taskId: c.taskId,
-      updates: c.updates
+      notes: t.notes || "",
+      stageId: activeStageId
     })),
+    boardCorrections: (data.boardCorrections ?? []).map((c) => {
+      const updates = c.updates;
+      if ((updates.status === "Deferred" || updates.status === "Cancelled") && !updates.closureReason) {
+        updates.closureReason = "No reason provided";
+      }
+      return {
+        taskId: c.taskId,
+        updates
+      };
+    }),
     phases,
     activeDecisions: (data.activeDecisions ?? []).map((ad) => ({
       id: ad.id,
       body: ad.body
     })),
     pendingRecommendationIds: pendingRecIds,
-    handoffs,
+    handoffs: handoffs2,
     cycle,
     reviewedTaskIds
   };
@@ -10942,13 +11182,18 @@ async function writeBack(adapter2, _mode, cycleNumber, data, contextHashes) {
   const logBlock = `### Cycle ${newCycleNumber} \u2014 ${cleanTitle}
 
 ${cleanContent}`;
+  const effortMap = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
+  const cycleTaskCount = handoffs.length;
+  const cycleEffortPoints = handoffs.reduce((sum, h) => sum + (effortMap[h.handoff.effort] ?? 3), 0);
   const cycleLogPromise = adapter2.writeCycleLogEntry({
     uuid: randomUUID7(),
     cycleNumber: newCycleNumber,
     title: cleanTitle,
     content: logBlock,
     carryForward: data.cycleLogCarryForward ?? void 0,
-    notes: data.cycleLogNotes ?? void 0
+    notes: data.cycleLogNotes ?? void 0,
+    taskCount: cycleTaskCount > 0 ? cycleTaskCount : void 0,
+    effortPoints: cycleEffortPoints > 0 ? cycleEffortPoints : void 0
   });
   const healthPromise = adapter2.getCycleHealth().then(
     (health) => adapter2.setCycleHealth({
@@ -11024,6 +11269,9 @@ ${cleanContent}`;
             `${correction.taskId}: planner suggested priority change to ${_stripped} \u2014 blocked (reviewed task)`
           );
         }
+        if ((updates.status === "Deferred" || updates.status === "Cancelled") && !updates.closureReason) {
+          updates.closureReason = "No reason provided";
+        }
         if (Object.keys(updates).length > 0) {
           await adapter2.updateTask(correction.taskId, updates);
         }
@@ -11213,7 +11461,8 @@ Run \`strategy_review\` first, or pass \`force: true\` to bypass this gate.`
   }
   return { mode, cycleNumber, strategyReviewWarning };
 }
-async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber, contextHashes) {
+async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber, contextHashes, planRunMeta) {
+  const applyStartMs = Date.now();
   const { displayText, data } = parseStructuredOutput(rawOutput);
   let resolvedDisplayText = displayText;
   let autoCommitNote = "";
@@ -11236,6 +11485,18 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
       for (const [placeholder, realId] of newTaskIdMap) {
         resolvedDisplayText = resolvedDisplayText.replaceAll(placeholder, realId);
       }
+      if (adapter2.insertPlanRun) {
+        const durationMs = Date.now() - applyStartMs + (planRunMeta?.prepareStartMs !== void 0 ? Date.now() - planRunMeta.prepareStartMs : 0);
+        adapter2.insertPlanRun({
+          cycleNumber: cycleNumber + 1,
+          contextBytes: planRunMeta?.contextBytes,
+          durationMs,
+          taskCountIn: planRunMeta?.taskCountIn,
+          taskCountOut: (writeSummary?.handoffs ?? 0) + (writeSummary?.newTasks ?? 0),
+          backlogDepth: planRunMeta?.backlogDepth
+        }).catch(() => {
+        });
+      }
       if (mode === "bootstrap") {
         try {
           await adapter2.appendToolMetric({
@@ -11321,7 +11582,7 @@ async function preparePlan(adapter2, config2, filters, focus, force) {
     contextHashes
   };
 }
-async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, strategyReviewWarning, contextHashes) {
+async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, strategyReviewWarning, contextHashes, planRunMeta) {
   const applyTimer = startTimer();
   console.error(`[plan-perf] applyPlan: start (llm_response=${rawLlmOutput.length} chars)`);
   const APPLY_TIMEOUT_MS = 12e4;
@@ -11330,7 +11591,7 @@ async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, str
   );
   const workPromise = (async () => {
     if (config2.adapterType === "pg") {
-      const result = await processLlmOutput(adapter2, config2, rawLlmOutput, mode, cycleNumber, contextHashes);
+      const result = await processLlmOutput(adapter2, config2, rawLlmOutput, mode, cycleNumber, contextHashes, planRunMeta);
       const applyMs2 = applyTimer();
       console.error(`[plan-perf] applyPlan: total=${applyMs2}ms (pg, no git sync)`);
       return { ...result, pullNote: "", strategyReviewWarning };
@@ -11338,7 +11599,7 @@ async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, str
     const syncResult = await withBaseBranchSync(
       { projectRoot: config2.projectRoot, baseBranch: config2.baseBranch, abortOnConflict: true },
       async () => {
-        return processLlmOutput(adapter2, config2, rawLlmOutput, mode, cycleNumber, contextHashes);
+        return processLlmOutput(adapter2, config2, rawLlmOutput, mode, cycleNumber, contextHashes, planRunMeta);
       }
     );
     if (syncResult.abort) {
@@ -11549,6 +11810,7 @@ function formatPlanResult(result) {
   if (result.priorityLockNote) lines.push(result.priorityLockNote.trim());
   if (result.slackWarning) lines.push(result.slackWarning);
   if (result.autoCommitNote) lines.push(result.autoCommitNote.trim());
+  lines.push("", `Next: run \`build_list\` to see your cycle tasks, then \`build_execute <task_id>\` to start building.`);
   const response = textResponse(lines.join("\n"));
   if (result.contextUtilisation !== void 0) {
     return { ...response, _contextUtilisation: result.contextUtilisation };
@@ -11579,7 +11841,7 @@ async function handlePlan(adapter2, config2, args) {
       lastPrepareContextHashes = void 0;
       lastPrepareUserMessage = void 0;
       lastPrepareContextBytes = void 0;
-      const result = await applyPlan(adapter2, config2, llmResponse, planMode, cycleNumber, strategyReviewWarning, contextHashes);
+      const result = await applyPlan(adapter2, config2, llmResponse, planMode, cycleNumber, strategyReviewWarning, contextHashes, { contextBytes: contextBytes ?? void 0 });
       let utilisation;
       if (inputContext) {
         try {
@@ -11890,7 +12152,7 @@ ${phaseSummary}`);
   return parts.join("\n");
 }
 function formatTaskCompact(t) {
-  const notesSnippet = t.notes ? t.notes.slice(0, 200) + (t.notes.length > 200 ? "..." : "") : "";
+  const notesSnippet = t.notes ?? "";
   return `- **${t.id}:** ${t.title}
   Status: ${t.status} | Priority: ${t.priority} | Complexity: ${t.complexity}
   Module: ${t.module} | Epic: ${t.epic} | Phase: ${t.phase} | Owner: ${t.owner}
@@ -12125,6 +12387,39 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
     }
   } catch {
   }
+  let taskCommentsText;
+  try {
+    const comments = await adapter2.getRecentTaskComments?.(50);
+    if (comments && comments.length > 0) {
+      const doneTaskIds = new Set(recentDoneTasks.map((t) => t.id));
+      const inReviewTasks = activeTasks.filter((t) => t.status === "In Review");
+      const reviewWindowTaskIds = /* @__PURE__ */ new Set([
+        ...doneTaskIds,
+        ...inReviewTasks.map((t) => t.id)
+      ]);
+      const filtered = comments.filter((c) => reviewWindowTaskIds.has(c.taskId));
+      if (filtered.length > 0) {
+        const lines = [];
+        const byTask = /* @__PURE__ */ new Map();
+        for (const c of filtered) {
+          const group = byTask.get(c.taskId) ?? [];
+          group.push(c);
+          byTask.set(c.taskId, group);
+        }
+        for (const [taskId, taskComments] of byTask) {
+          lines.push(`**${taskId}:**`);
+          for (const c of taskComments) {
+            const date = c.createdAt ? c.createdAt.slice(0, 10) : "";
+            lines.push(`  - [${c.author}${date ? `, ${date}` : ""}] ${c.content}`);
+          }
+        }
+        const raw = lines.join("\n");
+        const MAX_CHARS = 8e3;
+        taskCommentsText = raw.length > MAX_CHARS ? "(older comments truncated)\n" + raw.slice(raw.length - MAX_CHARS) : raw;
+      }
+    }
+  } catch {
+  }
   logDataSourceSummary("strategy_review_audit", [
     { label: "discoveryCanvas", hasData: discoveryCanvasText !== void 0 },
     { label: "briefImplications", hasData: briefImplicationsText !== void 0 },
@@ -12135,7 +12430,8 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
     { label: "adHocCommits", hasData: adHocCommitsText !== void 0 },
     { label: "registeredDocs", hasData: registeredDocsText !== void 0 },
     { label: "recentPlans", hasData: recentPlansText !== void 0 },
-    { label: "unregisteredDocs", hasData: unregisteredDocsText !== void 0 }
+    { label: "unregisteredDocs", hasData: unregisteredDocsText !== void 0 },
+    { label: "taskComments", hasData: taskCommentsText !== void 0 }
   ]);
   const context = {
     sessionNumber: cycleNumber,
@@ -12160,7 +12456,8 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
     pendingRecommendations: pendingRecsText,
     registeredDocs: registeredDocsText,
     recentPlans: recentPlansText,
-    unregisteredDocs: unregisteredDocsText
+    unregisteredDocs: unregisteredDocsText,
+    taskComments: taskCommentsText
   };
   const BUDGET_SOFT2 = 5e4;
   const BUDGET_HARD2 = 6e4;
@@ -12292,7 +12589,7 @@ ${cleanContent}`;
       if (ad.action === "delete" && adapter2.deleteActiveDecision) {
         await adapter2.deleteActiveDecision(ad.id);
       } else {
-        await adapter2.updateActiveDecision(ad.id, ad.body, cycleNumber);
+        await adapter2.updateActiveDecision(ad.id, ad.body, cycleNumber, ad.action);
       }
       const eventType = ad.action === "delete" ? "deleted" : ad.action === "confidence_change" ? "confidence_changed" : ad.action === "supersede" ? "superseded" : ad.action === "new" ? "created" : "modified";
       try {
@@ -12366,6 +12663,41 @@ ${cleanContent}`;
     } catch {
     }
   }
+  try {
+    const canvas = await adapter2.readDiscoveryCanvas();
+    const updates = {};
+    let 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) }));
+        if (entries.length > 0) {
+          updates.landscapeReferences = entries;
+          populatedSections.push("Landscape & References");
+        }
+      }
+    }
+    if (!canvas.mvpBoundary && data.strategicDirection) {
+      updates.mvpBoundary = `Auto-inferred from strategy review: ${data.strategicDirection}`;
+      populatedSections.push("MVP Boundary");
+    }
+    if ((!canvas.assumptionsOpenQuestions || canvas.assumptionsOpenQuestions.length === 0) && data.discoveryGaps?.length) {
+      updates.assumptionsOpenQuestions = data.discoveryGaps.map((gap) => ({
+        text: gap.suggestion,
+        status: "open",
+        evidence: `Auto-inferred: ${gap.section} was ${gap.status}`
+      }));
+      populatedSections.push("Assumptions & Open Questions");
+    }
+    if ((!canvas.successSignals || canvas.successSignals.length === 0) && data.velocityAssessment) {
+      updates.successSignals = [{ signal: "Velocity trend", metric: "tasks/cycle", target: data.velocityAssessment.slice(0, 200) }];
+      populatedSections.push("Success Signals");
+    }
+    if (populatedSections.length > 0) {
+      await adapter2.updateDiscoveryCanvas(updates);
+    }
+    data._canvasPopulated = populatedSections;
+  } catch {
+  }
   try {
     const [phases, boardTasks] = await Promise.all([
       adapter2.readPhases(),
@@ -12417,9 +12749,18 @@ ${report}`;
     }
   } catch {
   }
+  let canvasSection = "";
+  if (data) {
+    const populated = data._canvasPopulated;
+    if (populated && populated.length > 0) {
+      canvasSection = `
+
+**Discovery Canvas Auto-Populated:** ${populated.join(", ")}`;
+    }
+  }
   const fullText = phaseChanges?.length ? `${displayText}
 
-${formatPhaseChanges(phaseChanges)}${valueReportSection}` : `${displayText}${valueReportSection}`;
+${formatPhaseChanges(phaseChanges)}${valueReportSection}${canvasSection}` : `${displayText}${valueReportSection}${canvasSection}`;
   return {
     cycleNumber,
     displayText: fullText,
@@ -12731,7 +13072,7 @@ ${cleanContent}`;
           if (ad.action === "delete" && adapter2.deleteActiveDecision) {
             await adapter2.deleteActiveDecision(ad.id);
           } else {
-            await adapter2.updateActiveDecision(ad.id, ad.body, cycleNumber);
+            await adapter2.updateActiveDecision(ad.id, ad.body, cycleNumber, ad.action);
           }
           const eventType = ad.action === "delete" ? "deleted" : ad.action === "confidence_change" ? "confidence_changed" : ad.action === "supersede" ? "superseded" : ad.action === "new" ? "created" : "modified";
           try {
@@ -13532,12 +13873,34 @@ async function handleBoardEdit(adapter2, args) {
       updates.cycle = null;
       if (!changes.includes("cycle")) changes.push("cycle \u2192 cleared");
     }
+    let autoAssignedCycle = null;
+    if (updates.status === "In Cycle") {
+      const health = await adapter2.getCycleHealth().catch(() => null);
+      const activeCycle = health?.totalCycles ?? null;
+      if (activeCycle != null && activeCycle > 0) {
+        updates.cycle = activeCycle;
+        autoAssignedCycle = activeCycle;
+        if (!changes.includes("cycle")) changes.push(`cycle \u2192 ${activeCycle}`);
+      }
+    }
     await adapter2.updateTask(taskId, updates);
+    if ((updates.status === "Done" || updates.status === "Cancelled") && adapter2.updateDogfoodEntryStatus) {
+      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";
+        await Promise.all(linked.map((e) => adapter2.updateDogfoodEntryStatus(e.id, newStatus)));
+      } catch {
+      }
+    }
     const lines = [
       `Updated **${taskId}** (${updates.title ?? task.title})`,
       "",
       `**Changes:** ${changes.map((f) => `${f} \u2192 ${String(updates[f])}`).join(", ")}`
     ];
+    if (autoAssignedCycle != null) {
+      lines.push("", `Auto-assigned to Cycle ${autoAssignedCycle}.`);
+    }
     return textResponse(lines.join("\n"));
   } catch (err) {
     return errorResponse(err instanceof Error ? err.message : String(err));
@@ -13878,6 +14241,7 @@ These rules come from 80+ cycles of dogfooding. They prevent the most common sou
 - **Audit before widening access.** Before any build that adds endpoints, modifies auth/RLS, introduces new user types, or changes access controls \u2014 review the security implications first. Fix findings before shipping.
 - **Flag access-widening changes.** If a build touches auth, RLS policies, API keys, or user-facing access, note "Security surface reviewed" in the build report's \`discovered_issues\` or \`architecture_notes\`.
 - **Never ship secrets.** Do not commit .env files, API keys, or credentials. Check \`.gitignore\` covers sensitive files before pushing.
+- **Telemetry opt-out.** PAPI collects anonymous usage data (tool name, duration, project ID). To disable, add \`"PAPI_TELEMETRY": "off"\` to the \`env\` block in your \`.mcp.json\`.
 
 ### Planning & Scope
 - **Don't ask premature questions.** If the project is in early cycles, don't ask about deployment accounts, hosting providers, OAuth setup, or commercial features. Focus on building core functionality first.
@@ -14031,6 +14395,44 @@ var DOCS_INDEX_TEMPLATE = `# {{project_name}} \u2014 Document Index
 ### Consumer column
 Who or what reads this doc: \`planner\`, \`builder\`, \`strategy-review\`, \`user\`, \`onboarding\`.
 `;
+var CURSOR_RULES_TEMPLATE = `---
+description: PAPI \u2014 Persistent Agentic Planning Intelligence
+globs:
+alwaysApply: true
+---
+
+# {{project_name}} \u2014 PAPI Workflow
+
+PAPI gives your project structured planning, building, and reviewing. The agent manages the cycle workflow automatically.
+
+## Session Start
+
+Run \`orient\` at the start of every session to get cycle state, in-progress tasks, and recommended next action.
+
+## The Cycle
+
+\`plan\` \u2192 \`build_list\` \u2192 \`build_execute\` (start) \u2192 implement \u2192 \`build_execute\` (complete) \u2192 \`review_list\` \u2192 \`review_submit\` \u2192 \`release\`
+
+- **plan** \u2014 Generate BUILD HANDOFFs for the next cycle. Run once per cycle.
+- **build_execute \\<task-id\\>** (start) \u2014 Create feature branch, return BUILD HANDOFF.
+- **build_execute \\<task-id\\>** (complete) \u2014 Submit build report after implementing.
+- **review_submit** \u2014 Accept, request changes, or reject completed builds.
+- **release** \u2014 Merge all done tasks when the cycle is complete.
+
+## Quick Commands
+
+- \`orient\` \u2014 Current cycle state and recommended next action
+- \`idea\` \u2014 Add a task or bug to the backlog
+- \`board_view\` \u2014 See all active tasks
+- \`health\` \u2014 Deep project metrics
+
+## Rules
+
+- Run tools automatically \u2014 don't ask the user to invoke MCP tools manually
+- Stay within BUILD HANDOFF scope \u2014 don't add unrequested features
+- Commit per task \u2014 traceable git history
+- After build_execute completes: run \`review_submit\` with the verdict before presenting for human review
+`;
 
 // src/services/setup.ts
 var FILE_TEMPLATES = {
@@ -14112,6 +14514,23 @@ async function scaffoldPapiDir(adapter2, config2, input) {
     } catch {
     }
   }
+  const cursorDir = join3(config2.projectRoot, ".cursor");
+  let cursorDetected = false;
+  try {
+    await access2(cursorDir);
+    cursorDetected = true;
+  } catch {
+  }
+  if (cursorDetected) {
+    const cursorRulesDir = join3(cursorDir, "rules");
+    const cursorRulesPath = join3(cursorRulesDir, "papi.mdc");
+    await mkdir(cursorRulesDir, { recursive: true });
+    try {
+      await access2(cursorRulesPath);
+    } catch {
+      scaffoldFiles[cursorRulesPath] = substitute(CURSOR_RULES_TEMPLATE, vars);
+    }
+  }
   for (const [filepath, content] of Object.entries(scaffoldFiles)) {
     await writeFile2(filepath, content, "utf-8");
   }
@@ -14512,11 +14931,18 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     });
   } catch {
   }
+  let cursorScaffolded = false;
+  try {
+    await access2(join3(config2.projectRoot, ".cursor", "rules", "papi.mdc"));
+    cursorScaffolded = true;
+  } catch {
+  }
   return {
     createdProject,
     projectName: input.projectName,
     seededAds,
-    createdTasks
+    createdTasks,
+    cursorScaffolded
   };
 }
 
@@ -14624,13 +15050,16 @@ ${result.seededAds} Active Decision${result.seededAds > 1 ? "s" : ""} seeded bas
 
 ${result.createdTasks} initial backlog task${result.createdTasks > 1 ? "s" : ""} created from codebase analysis.` : "";
   const constraintsHint = !constraints ? '\n\nTip: consider adding `constraints` (e.g. "must use PostgreSQL", "HIPAA compliant", "offline-first") to improve Active Decision seeding.' : "";
+  const editorNote = result.cursorScaffolded ? "\n\nCursor detected \u2014 `.cursor/rules/papi.mdc` scaffolded alongside CLAUDE.md." : "";
   return textResponse(
-    `${prefix}Product Brief generated and saved.${adNote}${taskNote}${constraintsHint}
+    `${prefix}Product Brief generated and saved.${adNote}${taskNote}${constraintsHint}${editorNote}
 
 **Important:** Setup created/modified files (CLAUDE.md, .claude/settings.json, docs/). Commit these changes before running \`build_execute\` \u2014 it requires a clean working directory.
 
 Tip: See \`docs/templates/example-project-brief.md\` for an example of a well-written brief.
 
+**Telemetry notice:** PAPI collects anonymous usage data (tool name, duration, project ID) to improve the product. No code, file contents, or personal data is collected. To opt out, add \`"PAPI_TELEMETRY": "off"\` to the \`env\` block in your \`.mcp.json\`.
+
 Next step: run \`plan\` to start your first planning cycle.`
   );
 }
@@ -15022,6 +15451,52 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     if (adIds.length > 0) report.relatedDecisions = adIds;
   }
   await adapter2.appendBuildReport(report);
+  if (adapter2.appendCycleLearnings) {
+    const learnings = [];
+    const taskModule = task.module ?? "";
+    const adIds = report.relatedDecisions ?? [];
+    const extractLearning = (text, category) => {
+      if (!text || text === "None" || text.trim().length === 0) return;
+      const dotIdx = text.indexOf(". ");
+      const summary = dotIdx > 0 && dotIdx < 120 ? text.slice(0, dotIdx + 1) : text.slice(0, 120);
+      const tags = [];
+      if (taskModule) tags.push(taskModule.toLowerCase());
+      let severity;
+      if (category === "issue") {
+        const sevMatch = text.match(/^(P[0-3])[\s:]/);
+        if (sevMatch) severity = sevMatch[1];
+      }
+      learnings.push({
+        taskId: task.id,
+        cycleNumber,
+        category,
+        severity,
+        summary,
+        detail: text,
+        tags,
+        relatedDecision: adIds[0]
+      });
+    };
+    extractLearning(input.surprises, "surprise");
+    extractLearning(input.discoveredIssues, "issue");
+    extractLearning(input.architectureNotes, "architecture");
+    extractLearning(input.deadEnds, "dead_end");
+    if (input.scopeAccuracy && input.scopeAccuracy !== "accurate") {
+      learnings.push({
+        taskId: task.id,
+        cycleNumber,
+        category: "estimation_miss",
+        summary: `${input.scopeAccuracy}: effort was ${input.effort} vs estimated ${input.estimatedEffort}`,
+        tags: taskModule ? [taskModule.toLowerCase()] : []
+      });
+    }
+    if (learnings.length > 0) {
+      try {
+        await adapter2.appendCycleLearnings(learnings);
+      } catch {
+      }
+    }
+  }
   if (report.relatedDecisions && report.relatedDecisions.length > 0) {
     for (const adId of report.relatedDecisions) {
       try {
@@ -15137,6 +15612,80 @@ async function cancelBuild(adapter2, taskId, reason) {
   return { task, reason };
 }
 
+// src/tools/module-instructions.ts
+var MODULE_INSTRUCTIONS = {
+  Dashboard: `**\u26A0\uFE0F MANDATORY \u2014 Dashboard Module Rules (skip = rework)**
+
+**STEP 1 \u2014 BEFORE writing any code:**
+Read \`.impeccable.md\` in full. It contains the palette, typography system, audience definitions, brand personality, and design principles. Every visual decision must reference this file. If your output contradicts .impeccable.md, it is wrong.
+
+Typography rule: **Mono font is for task IDs and code only.** All labels, titles, column headers, status text, and body copy use sans-serif. Four-role type system: Display (40\u201356px, gradient) / Heading (18\u201322px, semibold) / Body (14\u201316px, sans) / Mono (12\u201313px, IDs and code only).
+
+**STEP 2 \u2014 Use the \`frontend-design\` skill for ALL visual implementation.**
+DO NOT write CSS, Tailwind classes, or component markup manually. Run the frontend-design skill and let it generate the visual layer. Manual styling produces generic output that fails review every time. This is non-negotiable.
+For M/L tasks: use the full toolchain \u2014 Playground (design preview) \u2192 Frontend-design (build) \u2192 Playwright (verify). The playground output is the quality bar. If the build looks worse than the playground, the build is wrong.
+
+**STEP 3 \u2014 Visual quality checklist (verify before committing):**
+- [ ] Font sizes match the page context \u2014 don't use tiny text (xs/2xs) when surrounding components use sm/base
+- [ ] Alignment and spacing are consistent \u2014 no orphaned margins, no elements floating off-grid
+- [ ] Color usage follows .impeccable.md \u2014 stat values use primary/accent colors, NOT gray. Status colors are applied to status indicators.
+- [ ] Content has hierarchy \u2014 primary info is large and colored, secondary is smaller and muted, tertiary is behind interaction
+- [ ] No raw task IDs without names, no abbreviations without tooltips, no jargon a non-dev wouldn't understand
+- [ ] Percentages and numbers have context \u2014 "96%" means nothing without "96% of what" and "is that good?"
+- [ ] Empty states guide the user with next actions, not just "No data"
+- [ ] Text doesn't truncate unless there's a clear expand/tooltip interaction
+- [ ] The component looks intentional next to its siblings \u2014 same surface levels, border treatment, spacing rhythm
+- [ ] Provide localhost URL or screenshot to user for visual review
+
+**STEP 4 \u2014 Production concerns:**
+- New API fetches need cache headers \u2014 check existing pattern in route.ts
+- Collapsed/hidden sections must lazy-load data, not fetch on page mount
+- No duplicate data fetching \u2014 check if polling, Realtime, or page load already covers this data
+- Consider Vercel free tier limits before adding polling or subscriptions`,
+  "MCP Server": `**MODULE INSTRUCTIONS \u2014 MCP Server**
+- Test changes locally before shipping \u2014 run the tool you modified against a real project.
+- For tools with prepare\u2192apply flows (plan, strategy_review), verify the full round-trip works.
+- Don't break existing tool input signatures \u2014 external users depend on them.
+- Build the server after changes: \`npm run build --workspace=@papi-ai/server\`
+- Check that tool descriptions are clear \u2014 LLMs read these to decide when and how to call the tool.
+- If modifying prompts.ts, verify the planner LLM output still matches the expected structured format.
+- Service logic goes in services/, tool handler + formatting goes in tools/ \u2014 keep the separation clean.`,
+  Core: `**MODULE INSTRUCTIONS \u2014 Core**
+- 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.
+- Test with both authenticated and unauthenticated requests.
+- Check RLS policies \u2014 service role key bypasses all RLS, so app-layer checks are critical.
+- /admin and /api/telemetry MUST be owner-only (cathalos92), never any authenticated user.
+- Multi-provider OAuth: GitHub + Email active, Google in backlog. Test all active providers.`,
+  Architecture: `**MODULE INSTRUCTIONS \u2014 Architecture**
+- Research tasks produce docs, not code. Deliverable is a findings document.
+- Save docs to docs/research/ or docs/architecture/ with frontmatter (title, type, created, cycle, status).
+- Register docs via \`doc_register\` after finalization \u2014 not during drafting.
+- Do NOT submit follow-up ideas to backlog until the owner confirms findings are actionable.
+- Include absolute dates and cycle numbers in all documents for future LLM context.`,
+  Data: `**MODULE INSTRUCTIONS \u2014 Data**
+- SQL views and functions run in Supabase \u2014 test via \`execute_sql\` before deploying.
+- Verify query performance on real data volumes, not just test data.
+- Cross-project queries must filter by project_id to prevent data leakage.
+- When creating views, ensure they respect the same access patterns as the underlying tables.`
+};
+function getModuleInstructions(module) {
+  if (!module) return "";
+  const instructions = MODULE_INSTRUCTIONS[module];
+  if (!instructions) return "";
+  return `
+
+---
+
+${instructions}`;
+}
+
 // src/tools/build.ts
 var buildListTool = {
   name: "build_list",
@@ -15192,15 +15741,15 @@ var buildExecuteTool = {
       },
       surprises: {
         type: "string",
-        description: 'Unexpected complexity or findings. Use "None" if none. Required for complete.'
+        description: 'What was DIFFERENT from what you expected? Scope changes, wrong assumptions, unexpected complexity, or missing infrastructure. NOT implementation details. Good: "Assumed table had status column but it uses state \u2014 required migration." Bad: "Used CSS keyframes instead of library." If your surprise is about implementation mechanics (which library, which pattern), it is not a surprise \u2014 use "None". Required for complete.'
       },
       discovered_issues: {
         type: "string",
-        description: 'New bugs or tasks found during the build. 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.`
       },
       architecture_notes: {
         type: "string",
-        description: 'Changes that should update Active Decisions or Product Brief. Use "None" if none. Required for complete.'
+        description: 'Patterns established or decisions made during this build that AFFECT FUTURE WORK. Good: "Created shared service layer for cockpit data \u2014 all cockpit components should use it." Bad: "Used React hooks." Only include if future builders need to know this to avoid rework or follow the established pattern. Use "None" if none. Required for complete.'
       },
       scope_accuracy: {
         type: "string",
@@ -15281,6 +15830,30 @@ function filterRelevantADs(ads, task) {
     return keywords.some((kw) => text.includes(kw));
   });
 }
+async function getModuleContext(adapter2, task) {
+  if (!task.module) return "";
+  try {
+    const [reports, allTasks] = await Promise.all([
+      adapter2.getRecentBuildReports(30),
+      adapter2.queryBoard()
+    ]);
+    const taskModuleMap = new Map(allTasks.map((t) => [t.id, t.module]));
+    const moduleReports = reports.filter((r) => taskModuleMap.get(r.taskId) === task.module).slice(0, 5);
+    if (moduleReports.length === 0) return "";
+    const lines = ["\n\n---\n\n**RECENT MODULE CONTEXT** (last builds in " + task.module + "):"];
+    for (const r of moduleReports) {
+      const parts = [`- **${r.taskId}:** ${r.taskName} (Cycle ${r.cycle})`];
+      if (r.surprises && r.surprises !== "None") parts.push(`  Surprises: ${r.surprises}`);
+      if (r.discoveredIssues && r.discoveredIssues !== "None") parts.push(`  Issues: ${r.discoveredIssues}`);
+      if (r.architectureNotes && r.architectureNotes !== "None") parts.push(`  Architecture: ${r.architectureNotes}`);
+      if (parts.length > 1) lines.push(parts.join("\n"));
+    }
+    if (lines.length <= 1) return "";
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
 function formatRelevantADs(ads) {
   if (ads.length === 0) return "";
   const lines = ["\n\n---\n\n**ACTIVE DECISIONS (relevant):**"];
@@ -15383,7 +15956,7 @@ async function handleBuildExecute(adapter2, config2, args) {
 **PRE-BUILD VERIFICATION:** Before writing any code, read these files and check if the functionality already exists:
 ${verificationFiles.map((f) => `- ${f}`).join("\n")}
 If >80% of the scope is already implemented, call \`build_execute\` with completed="yes" and note "already built" in surprises instead of re-implementing.` : "";
-    const chainInstruction = "\n\n---\n\n**IMPORTANT:** After implementing this task, immediately call `build_execute` again with report fields (`completed`, `effort`, `estimated_effort`, `surprises`, `discovered_issues`, `architecture_notes`) to complete the build. Do not wait for user confirmation.";
+    const chainInstruction = '\n\n---\n\n**IMPORTANT:** After implementing this task, immediately call `build_execute` again with report fields (`completed`, `effort`, `estimated_effort`, `surprises`, `discovered_issues`, `architecture_notes`) to complete the build. Do not wait for user confirmation.\n\n**Build Report Quality Bar:**\n- **surprises**: What was DIFFERENT from expected \u2014 wrong assumptions, scope changes, missing infrastructure. NOT implementation mechanics ("used X library").\n- **discovered_issues**: Bugs/gaps OUTSIDE this task\'s scope, with severity (P0-P3). NOT "had to install a dependency".\n- **architecture_notes**: Patterns/decisions that AFFECT FUTURE WORK. NOT "used React hooks".\n- If nothing meaningful to report for a field, use "None" \u2014 empty signal is better than noise.';
     let adSection = "";
     try {
       const allADs = await adapter2.getActiveDecisions();
@@ -15391,7 +15964,9 @@ If >80% of the scope is already implemented, call \`build_execute\` with complet
       adSection = formatRelevantADs(relevant);
     } catch {
     }
-    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + adSection + verificationNote + chainInstruction + phaseNote);
+    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);
   } catch (err) {
     if (isNoHandoffError(err)) {
       const lines = [
@@ -15501,22 +16076,39 @@ function formatCompleteResult(result) {
   if (result.docWarning) {
     lines.push("", `\u{1F4C4} ${result.docWarning}`);
   }
+  const isResearchTask = result.task.title.toLowerCase().startsWith("research:") || result.task.taskType === "research" || result.task.complexity === "Research";
+  if (result.completed === "yes" && isResearchTask) {
+    lines.push(
+      "",
+      "---",
+      "",
+      "## \u26A0\uFE0F Research Task Complete \u2014 Review Gate",
+      "",
+      "Before submitting follow-up ideas to the backlog:",
+      "",
+      "1. **Draft a findings doc** and save it to `docs/` (e.g. `docs/research/[topic]-findings.md`)",
+      "2. **Surface it to the owner** \u2014 share the doc path and key takeaways for review",
+      "3. **Only submit backlog ideas after the owner confirms** the findings are actionable",
+      "",
+      "Do NOT call `idea` for follow-up tasks until step 3 is complete."
+    );
+  }
   const hasDiscoveredIssues = result.discoveredIssues !== "None" && result.discoveredIssues.trim() !== "";
   const remaining = result.cycleProgress.total - result.cycleProgress.completed;
   if (result.completed !== "yes") {
     lines.push("", `Next: run \`build_execute ${result.task.id}\` again with updated report fields to complete this task.`);
   } else if (remaining > 0) {
     if (hasDiscoveredIssues) {
-      lines.push("", `Next: discovered issues logged \u2014 next \`plan\` will triage them. Run \`build_list\` to see ${remaining} remaining cycle task${remaining === 1 ? "" : "s"}, or \`plan\` to replan.`);
+      lines.push("", `Next: discovered issues logged \u2014 next \`plan\` will triage them. Run \`build_list\` to see ${remaining} remaining cycle task${remaining === 1 ? "" : "s"}, then \`build_execute <task_id>\` to start the next one.`);
     } else {
       lines.push("", `Next: run \`build_list\` to see ${remaining} remaining cycle task${remaining === 1 ? "" : "s"}, then \`build_execute <task_id>\` to start the next one.`);
     }
     lines.push("", "*Tip: Start a new chat for your next build to keep context fresh and avoid hitting context window limits.*");
   } else {
     if (hasDiscoveredIssues) {
-      lines.push("", "All cycle tasks complete. Discovered issues logged \u2014 run `plan` to start the next cycle and triage them.");
+      lines.push("", "All cycle tasks complete. Discovered issues logged \u2014 run `review_list` then `review_submit` to review builds, then `release` to close the cycle.");
     } else {
-      lines.push("", "All cycle tasks complete. Run `plan` to start the next planning cycle.");
+      lines.push("", "All cycle tasks complete. Run `review_list` then `review_submit` to review builds, then `release` to close the cycle.");
     }
     lines.push("", "*Tip: Start a new chat for your next session to keep context fresh.*");
   }
@@ -15797,8 +16389,21 @@ ${lines.join("\n")}
     createdCycle: health.totalCycles,
     notes: input.notes || "",
     taskType: "idea",
-    maturity: "raw"
+    maturity: "raw",
+    docRef: input.docRef
   });
+  if (input.notes && adapter2.updateDogfoodEntryStatus) {
+    const dogfoodRefs = input.notes.match(/dogfood:([a-f0-9-]+)/gi);
+    if (dogfoodRefs) {
+      for (const ref of dogfoodRefs) {
+        const entryId = ref.split(":")[1];
+        try {
+          await adapter2.updateDogfoodEntryStatus(entryId, "backlog-created", task.id);
+        } catch {
+        }
+      }
+    }
+  }
   return { routing: "task", task, message: `${task.id}: "${task.title}" \u2014 added to backlog` };
 }
 var CANVAS_SECTION_LABELS = {
@@ -15880,6 +16485,10 @@ var ideaTool = {
       force: {
         type: "boolean",
         description: "Force creation even if a high-overlap duplicate or already-done task is detected. Default: false."
+      },
+      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.'
       }
     },
     required: ["text"]
@@ -15906,7 +16515,8 @@ async function handleIdea(adapter2, config2, args) {
     complexity: args.complexity,
     notes: rawNotes,
     discovery: args.discovery === true,
-    force: args.force === true
+    force: args.force === true,
+    docRef: args.doc_ref?.trim()
   };
   const useGit = isGitAvailable() && isGitRepo(config2.projectRoot);
   const currentBranch = useGit ? getCurrentBranch(config2.projectRoot) : null;
@@ -16827,42 +17437,11 @@ async function getHealthSummary(adapter2) {
   let metricsSection;
   let derivedMetricsSection = "";
   try {
-    let snapshots = await adapter2.readCycleMetrics();
-    snapshots = snapshots.filter(
-      (s) => s.accuracy.length > 0 || s.velocity.length > 0
-    );
-    if (snapshots.length === 0) {
-      try {
-        const reports = await adapter2.getRecentBuildReports(50);
-        if (reports.length > 0) {
-          const byCycleMap = /* @__PURE__ */ new Map();
-          for (const r of reports) {
-            const existing = byCycleMap.get(r.cycle) ?? [];
-            existing.push(r);
-            byCycleMap.set(r.cycle, existing);
-          }
-          const effortMap = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
-          for (const [sn, cycleReports] of byCycleMap) {
-            const completed = cycleReports.filter((r) => r.completed === "Yes").length;
-            const total = cycleReports.length;
-            const withEffort = cycleReports.filter((r) => r.estimatedEffort && r.actualEffort);
-            const accurate = withEffort.filter((r) => r.estimatedEffort === r.actualEffort).length;
-            const matchRate = withEffort.length > 0 ? Math.round(accurate / withEffort.length * 100) : 0;
-            let effortPoints = 0;
-            for (const r of cycleReports) {
-              effortPoints += effortMap[r.actualEffort] ?? 3;
-            }
-            snapshots.push({
-              cycle: sn,
-              date: (/* @__PURE__ */ new Date()).toISOString(),
-              accuracy: [{ cycle: sn, reports: total, matchRate, mae: 0, bias: 0 }],
-              velocity: [{ cycle: sn, completed, partial: 0, failed: total - completed, effortPoints }]
-            });
-          }
-          snapshots.sort((a, b2) => a.cycle - b2.cycle);
-        }
-      } catch {
-      }
+    let snapshots = [];
+    try {
+      const reports = await adapter2.getRecentBuildReports(50);
+      snapshots = computeSnapshotsFromBuildReports(reports);
+    } catch {
     }
     metricsSection = formatCycleMetrics(snapshots);
     derivedMetricsSection = formatDerivedMetrics(snapshots, activeTasks);
@@ -17240,6 +17819,7 @@ async function handleRelease(adapter2, config2, args) {
       }
     } catch {
     }
+    lines.push("", `Next: cycle released! Run \`plan\` to start your next planning cycle.`);
     return textResponse(lines.join("\n"));
   } catch (err) {
     return errorResponse(err instanceof Error ? err.message : String(err));
@@ -17661,13 +18241,23 @@ Run \`plan\` to create Cycle ${result.currentCycle + 1}.`;
     const autoReviewNote = autoReview ? `
 
 **Auto-Review:** ${autoReview.verdict} \u2014 ${autoReview.summary}` + (autoReview.findings.length > 0 ? ` (${autoReview.findings.length} finding${autoReview.findings.length === 1 ? "" : "s"})` : "") : "";
+    let nextStepNote = "";
+    if (!autoReleaseNote && stage === "build-acceptance") {
+      if (verdict === "accept") {
+        nextStepNote = "\n\nNext: run `review_list` to check for more pending reviews, or `release` when all reviews are done.";
+      } else {
+        nextStepNote = `
+
+Next: address the feedback, then run \`build_execute ${taskId}\` to resubmit.`;
+      }
+    }
     return textResponse(
       `**${result.stageLabel}** recorded for ${result.taskId}.
 
 - **Verdict:** ${result.verdict}
 - **Comments:** ${result.comments}
 
-${statusNote}${autoReviewNote}${unblockNote}${regenNote}${mergeNote}${slackNote}${autoReleaseNote}${phaseNote}`
+${statusNote}${autoReviewNote}${unblockNote}${regenNote}${mergeNote}${slackNote}${autoReleaseNote}${nextStepNote}${phaseNote}`
     );
   } catch (err) {
     return errorResponse(err instanceof Error ? err.message : String(err));
@@ -17817,6 +18407,9 @@ function formatOrientSummary(health, buildInfo, hierarchy) {
     if (hierarchy.phasesNearingClosure.length > 0) {
       lines.push(`**Nearing Closure:** ${hierarchy.phasesNearingClosure.join(", ")}`);
     }
+    if (hierarchy.stageExitCriteria && hierarchy.stageExitCriteria.length > 0) {
+      lines.push(`**Stage Exit Criteria:** ${hierarchy.stageExitCriteria.map((c) => `[ ] ${c}`).join(" | ")}`);
+    }
     lines.push("");
   }
   if (health.northStarSection) {
@@ -17917,7 +18510,8 @@ async function getHierarchyPosition(adapter2) {
       horizon: activeHorizon.label,
       stage: activeStage.label,
       activePhases: activePhases.map((p) => p.label),
-      phasesNearingClosure: nearingClosure.map((p) => p.label)
+      phasesNearingClosure: nearingClosure.map((p) => p.label),
+      stageExitCriteria: activeStage.exitCriteria
     };
   } catch {
     return void 0;
@@ -18020,7 +18614,17 @@ ${versionDrift}` : "";
       enrichmentNote = enrichClaudeMd(config2.projectRoot, healthResult.cycleNumber);
     } catch {
     }
-    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy) + ttfvNote + recsNote + pendingReviewNote + versionNote + enrichmentNote);
+    let patternsNote = "";
+    try {
+      const patterns = await adapter2.getCycleLearningPatterns?.();
+      if (patterns && patterns.length > 0) {
+        const top = patterns.slice(0, 3).map((p) => `${p.tag} (${p.frequency} cycles)`).join(", ");
+        patternsNote = `
+**Recurring patterns:** ${top}`;
+      }
+    } catch {
+    }
+    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy) + ttfvNote + recsNote + pendingReviewNote + patternsNote + versionNote + enrichmentNote);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return errorResponse(`Orient failed: ${message}`);
@@ -18050,7 +18654,7 @@ function enrichClaudeMd(projectRoot, cycleNumber) {
 // src/tools/hierarchy.ts
 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. Does not call the Anthropic API.",
+  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.",
   inputSchema: {
     type: "object",
     properties: {
@@ -18067,9 +18671,14 @@ var hierarchyUpdateTool = {
         type: "string",
         enum: ["active", "completed", "deferred"],
         description: "The new status to set."
+      },
+      exit_criteria: {
+        type: "array",
+        items: { type: "string" },
+        description: 'Checklist defining when this stage is done (stages only). Each item is a completion condition, e.g. "All P0 tasks shipped". Replaces existing criteria.'
       }
     },
-    required: ["level", "name", "status"]
+    required: ["level", "name"]
   }
 };
 var VALID_STATUSES3 = /* @__PURE__ */ new Set(["active", "completed", "deferred"]);
@@ -18077,15 +18686,22 @@ async function handleHierarchyUpdate(adapter2, args) {
   const level = args.level;
   const name = args.name;
   const status = args.status;
-  if (!level || !name || !status) {
-    return errorResponse("Missing required parameters: level, name, status.");
+  const exitCriteria = args.exit_criteria;
+  if (!level || !name) {
+    return errorResponse("Missing required parameters: level, name.");
+  }
+  if (!status && !exitCriteria) {
+    return errorResponse("Nothing to update. Provide at least one of: status, exit_criteria.");
   }
   if (level !== "phase" && level !== "stage" && level !== "horizon") {
     return errorResponse(`Invalid level "${level}". Must be "phase", "stage", or "horizon".`);
   }
-  if (!VALID_STATUSES3.has(status)) {
+  if (status && !VALID_STATUSES3.has(status)) {
     return errorResponse(`Invalid status "${status}". Must be one of: active, completed, deferred.`);
   }
+  if (exitCriteria !== void 0 && level !== "stage") {
+    return errorResponse("exit_criteria can only be set on stages.");
+  }
   try {
     if (level === "phase") {
       if (!adapter2.readPhases || !adapter2.updatePhaseStatus) {
@@ -18107,7 +18723,7 @@ async function handleHierarchyUpdate(adapter2, args) {
       return textResponse(`Phase updated: **${phase.label}** ${oldStatus2} \u2192 ${status}`);
     }
     if (level === "stage") {
-      if (!adapter2.readStages || !adapter2.updateStageStatus) {
+      if (!adapter2.readStages) {
         return errorResponse("Stage management is not supported by the current adapter.");
       }
       const stages = await adapter2.readStages();
@@ -18118,12 +18734,28 @@ async function handleHierarchyUpdate(adapter2, args) {
         const available = stages.map((s) => s.label).join(", ");
         return errorResponse(`Stage "${name}" not found. Available stages: ${available || "none"}`);
       }
-      if (stage.status === status) {
-        return textResponse(`Stage "${stage.label}" is already "${status}". No change made.`);
+      const resultLines = [];
+      if (status) {
+        if (!adapter2.updateStageStatus) {
+          return errorResponse("Stage status updates are not supported by the current adapter.");
+        }
+        if (stage.status === status) {
+          resultLines.push(`Stage "${stage.label}" is already "${status}".`);
+        } else {
+          const oldStatus2 = stage.status;
+          await adapter2.updateStageStatus(stage.id, status);
+          resultLines.push(`Stage updated: **${stage.label}** ${oldStatus2} \u2192 ${status}`);
+        }
+      }
+      if (exitCriteria !== void 0) {
+        if (!adapter2.updateStageExitCriteria) {
+          return errorResponse("Exit criteria updates are not supported by the current adapter.");
+        }
+        await adapter2.updateStageExitCriteria(stage.id, exitCriteria);
+        resultLines.push(`Exit criteria set (${exitCriteria.length} item${exitCriteria.length !== 1 ? "s" : ""}):`);
+        exitCriteria.forEach((c) => resultLines.push(`  - ${c}`));
       }
-      const oldStatus2 = stage.status;
-      await adapter2.updateStageStatus(stage.id, status);
-      return textResponse(`Stage updated: **${stage.label}** ${oldStatus2} \u2192 ${status}`);
+      return textResponse(resultLines.join("\n"));
     }
     if (!adapter2.readHorizons || !adapter2.updateHorizonStatus) {
       return errorResponse("Horizon management is not supported by the current adapter.");
@@ -18698,11 +19330,87 @@ async function handleDocScan(adapter2, config2, args) {
   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.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project_ids: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional explicit list of sibling project UUIDs to query. If omitted, falls back to PAPI_SIBLING_PROJECT_IDS env var."
+      }
+    },
+    required: []
+  }
+};
+async function handleGetSiblingAds(adapter2, args) {
+  if (!adapter2.getSiblingAds) {
+    return errorResponse(
+      "get_sibling_ads is only available with the pg adapter (direct Supabase connection). Set PAPI_ENDPOINT or DATABASE_URL to enable."
+    );
+  }
+  let projectIds = [];
+  const argIds = args["project_ids"];
+  if (Array.isArray(argIds) && argIds.length > 0) {
+    projectIds = argIds.filter((id) => typeof id === "string");
+  } else {
+    const envIds = process.env["PAPI_SIBLING_PROJECT_IDS"];
+    if (envIds) {
+      projectIds = envIds.split(",").map((id) => id.trim()).filter(Boolean);
+    }
+  }
+  if (projectIds.length === 0) {
+    return errorResponse(
+      "No sibling project IDs provided. Pass project_ids in the tool call, or set PAPI_SIBLING_PROJECT_IDS=<uuid1>,<uuid2> in your .mcp.json env."
+    );
+  }
+  const ads = await adapter2.getSiblingAds(projectIds);
+  if (ads.length === 0) {
+    return textResponse(
+      `No active decisions found for sibling projects: ${projectIds.join(", ")}
+
+Check that the project IDs are correct and exist in the same Supabase instance.`
+    );
+  }
+  const byProject = /* @__PURE__ */ new Map();
+  for (const ad of ads) {
+    const group = byProject.get(ad.sourceProjectId) ?? [];
+    group.push(ad);
+    byProject.set(ad.sourceProjectId, group);
+  }
+  const lines = ["# Sibling Project Active Decisions", ""];
+  lines.push(`**Source projects:** ${projectIds.join(", ")}`);
+  lines.push(`**Total ADs:** ${ads.length}`);
+  lines.push("");
+  for (const [projectId, projectAds] of byProject) {
+    lines.push(`## Project: \`${projectId}\``);
+    lines.push(`*${projectAds.length} active decision${projectAds.length !== 1 ? "s" : ""}*`);
+    lines.push("");
+    for (const ad of projectAds) {
+      lines.push(`### ${ad.displayId}: ${ad.title} [Confidence: ${ad.confidence.toUpperCase()}]`);
+      if (ad.body) {
+        const excerpt = ad.body.length > 300 ? ad.body.slice(0, 300) + "\u2026" : ad.body;
+        lines.push(excerpt);
+      }
+      lines.push("");
+    }
+  }
+  lines.push("---");
+  lines.push(
+    "_These ADs are from sibling projects and are read-only. To share learnings, reference relevant ADs in your task notes or update your own ADs accordingly._"
+  );
+  return textResponse(lines.join("\n"));
+}
+
 // src/lib/telemetry.ts
 var TELEMETRY_SUPABASE_URL = "https://guewgygcpcmrcoppihzx.supabase.co";
 var TELEMETRY_API_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imd1ZXdneWdjcGNtcmNvcHBpaHp4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI2Njk2NTMsImV4cCI6MjA4ODI0NTY1M30.V5Jw7wJgiMpSQPa2mt0ftjyye5ynG1qLlam00yPVNJY";
 function isEnabled() {
-  return process.env["PAPI_TELEMETRY"] !== "false";
+  const val = process.env["PAPI_TELEMETRY"];
+  return val !== "false" && val !== "off";
 }
 function emitTelemetryEvent(event) {
   if (!isEnabled()) return;
@@ -18769,8 +19477,58 @@ var TOOLS_REQUIRING_PAPI = /* @__PURE__ */ new Set([
 function createServer(adapter2, config2) {
   const server2 = new Server(
     { name: "papi", version: "0.1.0" },
-    { capabilities: { tools: {} } }
+    { capabilities: { tools: {}, prompts: {} } }
   );
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  const skillsDir = join9(__dirname, "..", "skills");
+  function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    const fm = match[1];
+    const nameMatch = fm.match(/^name:\s*(.+)$/m);
+    const descMatch = fm.match(/^description:\s*[>|]?\n?([\s\S]*?)(?=\n\w|\n---)/m);
+    if (!nameMatch) return null;
+    const name = nameMatch[1].trim();
+    const description = descMatch ? descMatch[1].replace(/^\s{2}/gm, "").replace(/\n+$/, "").replace(/\n/g, " ").trim() : "";
+    return { name, description };
+  }
+  server2.setRequestHandler(ListPromptsRequestSchema, async () => {
+    try {
+      const files = await readdir2(skillsDir);
+      const mdFiles = files.filter((f) => f.endsWith(".md"));
+      const prompts = [];
+      for (const file of mdFiles) {
+        const content = await readFile5(join9(skillsDir, file), "utf-8");
+        const meta = parseSkillFrontmatter(content);
+        if (meta) {
+          prompts.push({ name: meta.name, description: meta.description });
+        }
+      }
+      return { prompts };
+    } catch {
+      return { prompts: [] };
+    }
+  });
+  server2.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name } = request.params;
+    try {
+      const files = await readdir2(skillsDir);
+      for (const file of files.filter((f) => f.endsWith(".md"))) {
+        const content = await readFile5(join9(skillsDir, file), "utf-8");
+        const meta = parseSkillFrontmatter(content);
+        if (meta?.name === name) {
+          const body = content.replace(/^---\n[\s\S]*?\n---\n*/, "");
+          return {
+            description: meta.description,
+            messages: [{ role: "user", content: { type: "text", text: body } }]
+          };
+        }
+      }
+    } catch {
+    }
+    throw new Error(`Prompt not found: ${name}`);
+  });
   server2.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
       planTool,
@@ -18799,7 +19557,8 @@ function createServer(adapter2, config2) {
       zoomOutTool,
       docRegisterTool,
       docSearchTool,
-      docScanTool
+      docScanTool,
+      getSiblingAdsTool
     ]
   }));
   server2.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -18912,6 +19671,9 @@ function createServer(adapter2, config2) {
       case "doc_scan":
         result = await handleDocScan(adapter2, config2, safeArgs);
         break;
+      case "get_sibling_ads":
+        result = await handleGetSiblingAds(adapter2, safeArgs);
+        break;
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
     }