@papi-ai/server 0.5.0 → 0.5.2

package/dist/index.js

@@ -280,6 +280,9 @@ function splitSections(text) {
 function parseBulletList(text) {
   return text.split("\n").map((l) => l.replace(/^\s*-\s*/, "").trim()).filter((l) => l.length > 0);
 }
+function parseBulletsOnly(text) {
+  return text.split("\n").filter((l) => /^\s*-\s/.test(l)).map((l) => l.replace(/^\s*-\s*/, "").trim()).filter((l) => l.length > 0);
+}
 function parseChecklist(text) {
   return text.split("\n").map((l) => l.replace(/^\s*\[[ x]]\s*/, "").trim()).filter((l) => l.length > 0);
 }
@@ -314,6 +317,7 @@ function parseBuildHandoff(markdown) {
     scopeBoundary: parseBulletList(sections.get("SCOPE BOUNDARY (DO NOT DO THIS)") ?? ""),
     acceptanceCriteria: parseChecklist(sections.get("ACCEPTANCE CRITERIA") ?? ""),
     securityConsiderations: (sections.get("SECURITY CONSIDERATIONS") ?? "").trim(),
+    verificationFiles: parseBulletsOnly(sections.get("PRE-BUILD VERIFICATION") ?? ""),
     filesLikelyTouched: parseBulletList(sections.get("FILES LIKELY TOUCHED") ?? ""),
     effort
   };
@@ -345,6 +349,15 @@ function serializeBuildHandoff(handoff) {
   lines.push("");
   lines.push("SECURITY CONSIDERATIONS");
   lines.push(handoff.securityConsiderations);
+  if (handoff.verificationFiles && handoff.verificationFiles.length > 0) {
+    lines.push("");
+    lines.push("PRE-BUILD VERIFICATION");
+    lines.push("Before implementing, read these files and check if the functionality already exists:");
+    for (const item of handoff.verificationFiles) {
+      lines.push(`- ${item}`);
+    }
+    lines.push('If >80% of the scope is already implemented, call build_execute with completed="yes" and note "already built" in surprises instead of re-implementing.');
+  }
   lines.push("");
   lines.push("FILES LIKELY TOUCHED");
   for (const item of handoff.filesLikelyTouched) {
@@ -832,28 +845,6 @@ function parseCostSnapshots(content) {
   }
   return snapshots;
 }
-function serializeCostSnapshot(snapshot) {
-  return `| ${snapshot.cycle} | ${snapshot.date} | ${snapshot.totalCostUsd.toFixed(4)} | ${formatNumber(snapshot.totalInputTokens)} | ${formatNumber(snapshot.totalOutputTokens)} | ${formatNumber(snapshot.totalCalls)} |`;
-}
-function writeCostSnapshotToContent(snapshot, content) {
-  if (!content.includes(COST_SECTION_HEADING)) {
-    return content.trimEnd() + "\n\n" + COST_SECTION_HEADING + "\n\n" + COST_TABLE_HEADER + "\n" + COST_TABLE_SEPARATOR + "\n" + serializeCostSnapshot(snapshot) + "\n";
-  }
-  const lines = content.split("\n");
-  const cyclePrefix = `| ${snapshot.cycle} |`;
-  let replaced = false;
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].startsWith(cyclePrefix)) {
-      lines[i] = serializeCostSnapshot(snapshot);
-      replaced = true;
-      break;
-    }
-  }
-  if (replaced) {
-    return lines.join("\n");
-  }
-  return content.trimEnd() + "\n" + serializeCostSnapshot(snapshot) + "\n";
-}
 function effortOrdinal(effort) {
   const normalized = effort.trim().toUpperCase();
   return EFFORT_SCALE[normalized];
@@ -1403,7 +1394,7 @@ async function detectReviewPatterns(reviews, currentCycle, window = 5, clusterer
 function hasReviewPatterns(patterns) {
   return patterns.recurringFeedback.length > 0 || patterns.requestChangesRate >= 50;
 }
-var VALID_TRANSITIONS2, TASK_TYPE_TIERS, VALID_EFFORT_SIZES, SECTION_HEADERS, YAML_MARKER, YAML_START, YAML_END, VALID_EFFORT_SIZES2, HEADER_SENTINEL, TABLE_HEADER, TABLE_SEPARATOR, PREV_TABLE_HEADER, LEGACY_TABLE_HEADER, SECTION_HEADING, FILE_TEMPLATE, COST_SECTION_HEADING, COST_TABLE_HEADER, COST_TABLE_SEPARATOR, FILE_HEADING, ACCURACY_HEADER, ACCURACY_SEPARATOR, VELOCITY_HEADER, VELOCITY_SEPARATOR, EFFORT_SCALE, NONE_PATTERN, HEADER_SENTINEL2, VALID_STAGES, VALID_VERDICTS, STAGE_DISPLAY, VALID_STATUSES, PHASES_START, PHASES_END, YAML_MARKER2, YAML_START2, YAML_END2, VALID_STATUSES2, YAML_MARKER3, YAML_START3, YAML_END3, MdFileAdapter, NONE_PATTERN2;
+var VALID_TRANSITIONS2, TASK_TYPE_TIERS, VALID_EFFORT_SIZES, SECTION_HEADERS, YAML_MARKER, YAML_START, YAML_END, VALID_EFFORT_SIZES2, HEADER_SENTINEL, TABLE_HEADER, TABLE_SEPARATOR, PREV_TABLE_HEADER, LEGACY_TABLE_HEADER, SECTION_HEADING, FILE_TEMPLATE, COST_SECTION_HEADING, COST_TABLE_SEPARATOR, FILE_HEADING, ACCURACY_HEADER, ACCURACY_SEPARATOR, VELOCITY_HEADER, VELOCITY_SEPARATOR, EFFORT_SCALE, NONE_PATTERN, HEADER_SENTINEL2, VALID_STAGES, VALID_VERDICTS, STAGE_DISPLAY, VALID_STATUSES, PHASES_START, PHASES_END, YAML_MARKER2, YAML_START2, YAML_END2, VALID_STATUSES2, YAML_MARKER3, YAML_START3, YAML_END3, MdFileAdapter, NONE_PATTERN2;
 var init_dist2 = __esm({
   "../adapter-md/dist/index.js"() {
     "use strict";
@@ -1422,6 +1413,7 @@ var init_dist2 = __esm({
       "SCOPE BOUNDARY (DO NOT DO THIS)",
       "ACCEPTANCE CRITERIA",
       "SECURITY CONSIDERATIONS",
+      "PRE-BUILD VERIFICATION",
       "FILES LIKELY TOUCHED",
       "EFFORT"
     ];
@@ -1443,7 +1435,6 @@ ${TABLE_HEADER}
 ${TABLE_SEPARATOR}
 `;
     COST_SECTION_HEADING = "## Cost Summary";
-    COST_TABLE_HEADER = "| Cycle | Date | Total Cost ($) | Input Tokens | Output Tokens | Calls |";
     COST_TABLE_SEPARATOR = "|--------|------|----------------|--------------|---------------|-------|";
     FILE_HEADING = "# Cycle Methodology Metrics";
     ACCURACY_HEADER = "| Cycle | Reports | Match Rate | MAE | Bias |";
@@ -1724,6 +1715,11 @@ ${TABLE_SEPARATOR}
         const reports = parseBuildReports(await this.read("BUILD_REPORTS.md"));
         return reports.slice(0, count);
       }
+      /** Return the number of build reports for a specific task. */
+      async getBuildReportCountForTask(taskId) {
+        const reports = parseBuildReports(await this.read("BUILD_REPORTS.md"));
+        return reports.filter((r) => r.taskId === taskId).length;
+      }
       /** Return all build reports from cycles >= {@link cycleNumber}. */
       async getBuildReportsSince(cycleNumber) {
         const reports = parseBuildReports(await this.read("BUILD_REPORTS.md"));
@@ -1884,11 +1880,6 @@ ${newSection}
         const metrics = await this.readToolMetrics();
         return aggregateCostSummary(metrics, cycleNumber);
       }
-      /** Write a cost snapshot to the Cost Summary section of METRICS.md. */
-      async writeCostSnapshot(snapshot) {
-        const content = await this.readOptional("METRICS.md");
-        await this.write("METRICS.md", writeCostSnapshotToContent(snapshot, content));
-      }
       /** Read all cost snapshots from the Cost Summary section of METRICS.md. */
       async getCostSnapshots() {
         const content = await this.readOptional("METRICS.md");
@@ -4540,7 +4531,7 @@ function rowToDecisionScore(row) {
     createdAt: row.created_at
   };
 }
-function rowToSprintLogEntry(row) {
+function rowToCycleLogEntry(row) {
   const entry = {
     uuid: row.id,
     cycleNumber: row.cycle_number,
@@ -5571,6 +5562,8 @@ CREATE TABLE IF NOT EXISTS strategy_reviews (
   full_analysis TEXT,
   velocity_assessment TEXT,
   structured_data JSONB,
+  review_number INTEGER,
+  review_type TEXT,
   PRIMARY KEY (id)
 );
 
@@ -6133,14 +6126,14 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
         ORDER BY cycle_number DESC
         LIMIT ${limit}
       `;
-          return rows2.map(rowToSprintLogEntry);
+          return rows2.map(rowToCycleLogEntry);
         }
         const rows = await this.sql`
       SELECT * FROM planning_log_entries
       WHERE project_id = ${this.projectId}
       ORDER BY cycle_number DESC
     `;
-        return rows.map(rowToSprintLogEntry);
+        return rows.map(rowToCycleLogEntry);
       }
       async getCycleLogSince(cycleNumber) {
         const rows = await this.sql`
@@ -6149,7 +6142,7 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
         AND cycle_number >= ${cycleNumber}
       ORDER BY cycle_number DESC
     `;
-        return rows.map(rowToSprintLogEntry);
+        return rows.map(rowToCycleLogEntry);
       }
       async setCycleHealth(updates) {
         if (updates.boardHealth != null || updates.strategicDirection != null) {
@@ -6193,11 +6186,21 @@ ${newParts.join("\n")}` : newParts.join("\n");
     `;
       }
       async writeStrategyReview(review) {
+        let reviewNumber = review.reviewNumber ?? null;
+        if (reviewNumber == null && review.cycleNumber > 0) {
+          const [row] = await this.sql`
+        SELECT MAX(review_number) as max_num FROM strategy_reviews
+        WHERE project_id = ${this.projectId} AND cycle_number > 0
+      `;
+          reviewNumber = (row?.max_num ?? 0) + 1;
+        }
+        const reviewType = review.reviewType ?? "scheduled";
         await this.sql`
       INSERT INTO strategy_reviews (
         project_id, cycle_number, cycle_range, title, content, notes,
         board_health, strategic_direction, recommendations,
-        full_analysis, velocity_assessment, structured_data
+        full_analysis, velocity_assessment, structured_data,
+        review_number, review_type
       )
       VALUES (
         ${this.projectId},
@@ -6208,10 +6211,12 @@ ${newParts.join("\n")}` : newParts.join("\n");
         ${review.notes ?? null},
         ${review.boardHealth ?? null},
         ${review.strategicDirection ?? null},
-        ${review.recommendations ? JSON.stringify(review.recommendations) : null},
+        ${review.recommendations ? this.sql.json(review.recommendations) : null},
         ${review.fullAnalysis ?? null},
         ${review.velocityAssessment ?? null},
-        ${review.structuredData ? JSON.stringify(review.structuredData) : null}
+        ${review.structuredData ? this.sql.json(review.structuredData) : null},
+        ${reviewNumber},
+        ${reviewType}
       )
       ON CONFLICT (project_id, cycle_number)
       DO UPDATE SET
@@ -6224,7 +6229,9 @@ ${newParts.join("\n")}` : newParts.join("\n");
         recommendations = EXCLUDED.recommendations,
         full_analysis = EXCLUDED.full_analysis,
         velocity_assessment = EXCLUDED.velocity_assessment,
-        structured_data = EXCLUDED.structured_data
+        structured_data = EXCLUDED.structured_data,
+        review_number = EXCLUDED.review_number,
+        review_type = EXCLUDED.review_type
     `;
       }
       async getLastStrategyReviewCycle() {
@@ -6241,9 +6248,10 @@ ${newParts.join("\n")}` : newParts.join("\n");
           const rows2 = await this.sql`
         SELECT cycle_number, cycle_range, title, content, notes,
                board_health, strategic_direction, full_analysis,
-               velocity_assessment, structured_data, created_at
+               velocity_assessment, structured_data, created_at,
+               review_number, review_type
         FROM strategy_reviews
-        WHERE project_id = ${this.projectId}
+        WHERE project_id = ${this.projectId} AND cycle_number > 0
         ORDER BY cycle_number DESC
         LIMIT ${limit}
       `;
@@ -6258,13 +6266,15 @@ ${newParts.join("\n")}` : newParts.join("\n");
             fullAnalysis: r.full_analysis ?? void 0,
             velocityAssessment: r.velocity_assessment ?? void 0,
             structuredData: r.structured_data ?? void 0,
-            createdAt: r.created_at ?? void 0
+            createdAt: r.created_at ?? void 0,
+            reviewNumber: r.review_number ?? void 0,
+            reviewType: r.review_type ?? void 0
           }));
         }
         const rows = await this.sql`
       SELECT cycle_number, cycle_range, title, content, notes,
              board_health, strategic_direction, velocity_assessment,
-             structured_data, created_at
+             structured_data, created_at, review_number, review_type
       FROM strategy_reviews
       WHERE project_id = ${this.projectId}
       ORDER BY cycle_number DESC
@@ -6280,9 +6290,144 @@ ${newParts.join("\n")}` : newParts.join("\n");
           strategicDirection: r.strategic_direction ?? void 0,
           velocityAssessment: r.velocity_assessment ?? void 0,
           structuredData: r.structured_data ?? void 0,
-          createdAt: r.created_at ?? void 0
+          createdAt: r.created_at ?? void 0,
+          reviewNumber: r.review_number ?? void 0,
+          reviewType: r.review_type ?? void 0
+        }));
+      }
+      async savePendingReviewResponse(cycleNumber, rawResponse) {
+        await this.sql`
+      INSERT INTO strategy_reviews (
+        project_id, cycle_number, title, content, full_analysis
+      ) VALUES (
+        ${this.projectId}, ${0}, ${"[PENDING] Strategy Review"}, ${"Pending write-back retry"}, ${rawResponse}
+      )
+      ON CONFLICT (project_id, cycle_number)
+      DO UPDATE SET
+        full_analysis = ${rawResponse},
+        notes = ${`original_cycle:${cycleNumber}`}
+    `;
+      }
+      async getPendingReviewResponse() {
+        const rows = await this.sql`
+      SELECT full_analysis, notes FROM strategy_reviews
+      WHERE project_id = ${this.projectId} AND cycle_number = 0
+      LIMIT 1
+    `;
+        if (rows.length === 0 || !rows[0].full_analysis) return null;
+        const cycleMatch = rows[0].notes?.match(/original_cycle:(\d+)/);
+        const cycleNumber = cycleMatch ? parseInt(cycleMatch[1], 10) : 0;
+        return { cycleNumber, rawResponse: rows[0].full_analysis };
+      }
+      async clearPendingReviewResponse() {
+        await this.sql`
+      DELETE FROM strategy_reviews
+      WHERE project_id = ${this.projectId} AND cycle_number = 0
+    `;
+      }
+      // -------------------------------------------------------------------------
+      // Doc Registry
+      // -------------------------------------------------------------------------
+      async registerDoc(entry) {
+        const [row] = await this.sql`
+      INSERT INTO doc_registry (
+        project_id, title, type, path, status, summary, tags,
+        cycle_created, cycle_updated, superseded_by, actions
+      ) VALUES (
+        ${this.projectId}, ${entry.title}, ${entry.type}, ${entry.path},
+        ${entry.status}, ${entry.summary}, ${entry.tags},
+        ${entry.cycleCreated}, ${entry.cycleUpdated ?? null},
+        ${entry.supersededBy ?? null},
+        ${entry.actions ? this.sql.json(entry.actions) : this.sql.json([])}
+      )
+      ON CONFLICT (project_id, path)
+      DO UPDATE SET
+        title = EXCLUDED.title,
+        type = EXCLUDED.type,
+        status = EXCLUDED.status,
+        summary = EXCLUDED.summary,
+        tags = EXCLUDED.tags,
+        cycle_updated = EXCLUDED.cycle_updated,
+        superseded_by = EXCLUDED.superseded_by,
+        actions = EXCLUDED.actions,
+        updated_at = now()
+      RETURNING id, created_at, updated_at
+    `;
+        return {
+          ...entry,
+          id: row.id,
+          createdAt: row.created_at,
+          updatedAt: row.updated_at
+        };
+      }
+      async searchDocs(input) {
+        const status = input.status ?? "active";
+        const limit = input.limit ?? 10;
+        const keyword = input.keyword ? `%${input.keyword}%` : null;
+        const sinceCycle = input.sinceCycle ?? 0;
+        const hasPending = input.hasPendingActions ?? false;
+        const rows = await this.sql`
+      SELECT * FROM doc_registry
+      WHERE project_id = ${this.projectId}
+        AND status = ${status}
+        AND (${input.type ?? null}::text IS NULL OR type = ${input.type ?? null})
+        AND (${keyword}::text IS NULL OR (title ILIKE ${keyword} OR summary ILIKE ${keyword}))
+        AND (${sinceCycle} = 0 OR COALESCE(cycle_updated, cycle_created) >= ${sinceCycle})
+        AND (${hasPending} = false OR actions::text LIKE '%"pending"%')
+        AND (${input.tags ?? []}::text[] = '{}' OR tags && ${input.tags ?? []})
+      ORDER BY COALESCE(cycle_updated, cycle_created) DESC
+      LIMIT ${limit}
+    `;
+        return rows.map((r) => ({
+          id: r.id,
+          title: r.title,
+          type: r.type,
+          path: r.path,
+          status: r.status,
+          summary: r.summary,
+          tags: r.tags ?? [],
+          cycleCreated: r.cycle_created,
+          cycleUpdated: r.cycle_updated ?? void 0,
+          supersededBy: r.superseded_by ?? void 0,
+          actions: r.actions,
+          createdAt: r.created_at,
+          updatedAt: r.updated_at
         }));
       }
+      async getDoc(idOrPath) {
+        const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(idOrPath);
+        const rows = isUuid ? await this.sql`
+          SELECT * FROM doc_registry WHERE id = ${idOrPath} AND project_id = ${this.projectId}
+        ` : await this.sql`
+          SELECT * FROM doc_registry WHERE path = ${idOrPath} AND project_id = ${this.projectId}
+        `;
+        if (rows.length === 0) return null;
+        const r = rows[0];
+        return {
+          id: r.id,
+          title: r.title,
+          type: r.type,
+          path: r.path,
+          status: r.status,
+          summary: r.summary,
+          tags: r.tags ?? [],
+          cycleCreated: r.cycle_created,
+          cycleUpdated: r.cycle_updated ?? void 0,
+          supersededBy: r.superseded_by ?? void 0,
+          actions: r.actions,
+          createdAt: r.created_at,
+          updatedAt: r.updated_at
+        };
+      }
+      async updateDocStatus(id, status, supersededBy) {
+        await this.sql`
+      UPDATE doc_registry
+      SET status = ${status},
+          superseded_by = ${supersededBy ?? null},
+          updated_at = now()
+      WHERE id = ${id} AND project_id = ${this.projectId}
+    `;
+      }
       async writeDogfoodEntries(entries) {
         if (entries.length === 0) return;
         const values2 = entries.map((entry) => ({
@@ -6458,8 +6603,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
         ${task.reviewed}, ${task.cycle ?? null}, ${task.createdCycle ?? null},
         ${task.why ?? null}, ${task.dependsOn ?? null}, ${task.notes ?? null},
         ${task.closureReason ?? null},
-        ${JSON.stringify(task.stateHistory ?? [])},
-        ${task.buildHandoff ? JSON.stringify(task.buildHandoff) : null},
+        ${this.sql.json(task.stateHistory ?? [])},
+        ${task.buildHandoff ? this.sql.json(task.buildHandoff) : null},
         ${task.buildReport ?? null},
         ${task.taskType ?? null},
         ${task.maturity ?? null},
@@ -6547,9 +6692,9 @@ ${newParts.join("\n")}` : newParts.join("\n");
         ${normaliseEffort(report.actualEffort)}, ${normaliseEffort(report.estimatedEffort)}, ${report.scopeAccuracy},
         ${report.surprises}, ${report.discoveredIssues}, ${report.architectureNotes},
         ${report.commitSha ?? null}, ${report.filesChanged ?? []}, ${report.relatedDecisions ?? []},
-        ${report.handoffAccuracy ? JSON.stringify(report.handoffAccuracy) : null},
+        ${report.handoffAccuracy ? this.sql.json(report.handoffAccuracy) : null},
         ${report.correctionsCount ?? 0},
-        ${report.briefImplications ? JSON.stringify(report.briefImplications) : null},
+        ${report.briefImplications ? this.sql.json(report.briefImplications) : null},
         ${report.deadEnds ?? null}
       )
     `;
@@ -6563,6 +6708,13 @@ ${newParts.join("\n")}` : newParts.join("\n");
     `;
         return rows.map(rowToBuildReport);
       }
+      async getBuildReportCountForTask(taskId) {
+        const rows = await this.sql`
+      SELECT COUNT(*)::text AS count FROM build_reports
+      WHERE project_id = ${this.projectId} AND task_id = ${taskId}
+    `;
+        return parseInt(rows[0]?.count ?? "0", 10);
+      }
       async getBuildReportsSince(cycleNumber) {
         const rows = await this.sql`
       SELECT * FROM build_reports
@@ -6601,7 +6753,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
         ${review.reviewer}, ${review.verdict}, ${review.cycle},
         ${review.date}, ${review.comments},
         ${review.handoffRevision ?? null}, ${review.buildCommitSha ?? null},
-        ${review.autoReview ? JSON.stringify(review.autoReview) : null}
+        ${review.autoReview ? this.sql.json(review.autoReview) : null}
       )
     `;
       }
@@ -6824,25 +6976,6 @@ ${newParts.join("\n")}` : newParts.join("\n");
           avgCostPerCall: metrics.length > 0 ? totalCostUsd / metrics.length : 0
         };
       }
-      async writeCostSnapshot(snapshot) {
-        await this.sql`
-      INSERT INTO cost_snapshots (
-        project_id, cycle, date, total_cost_usd,
-        total_input_tokens, total_output_tokens, total_calls
-      ) VALUES (
-        ${this.projectId}, ${snapshot.cycle}, ${snapshot.date},
-        ${snapshot.totalCostUsd}, ${snapshot.totalInputTokens},
-        ${snapshot.totalOutputTokens}, ${snapshot.totalCalls}
-      )
-      ON CONFLICT (project_id, cycle)
-      DO UPDATE SET
-        date = EXCLUDED.date,
-        total_cost_usd = EXCLUDED.total_cost_usd,
-        total_input_tokens = EXCLUDED.total_input_tokens,
-        total_output_tokens = EXCLUDED.total_output_tokens,
-        total_calls = EXCLUDED.total_calls
-    `;
-      }
       async getCostSnapshots() {
         const rows = await this.sql`
       SELECT * FROM cost_snapshots
@@ -6907,7 +7040,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
         ${this.projectId}, ${cycle.number}, ${cycle.status},
         ${cycle.startDate}, ${cycle.endDate ?? null},
         ${cycle.goals}, ${cycle.boardHealth}, ${resolvedTaskIds},
-        ${cycle.contextHashes ? JSON.stringify(cycle.contextHashes) : null}
+        ${cycle.contextHashes ? this.sql.json(cycle.contextHashes) : null}
       )
       ON CONFLICT (project_id, number)
       DO UPDATE SET
@@ -6964,6 +7097,12 @@ ${newParts.join("\n")}` : newParts.join("\n");
         await this.sql`
       UPDATE horizons SET status = ${status}, updated_at = NOW()
       WHERE id = ${horizonId} AND project_id = ${this.projectId}
+    `;
+      }
+      async updatePhaseStatus(phaseId, status) {
+        await this.sql`
+      UPDATE phases SET status = ${status}, updated_at = NOW()
+      WHERE id = ${phaseId} AND project_id = ${this.projectId}
     `;
       }
       async getActiveStage() {
@@ -7045,7 +7184,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
           status: "pending",
           content: r.content,
           createdCycle: r.created_cycle,
-          actionedSprint: r.actioned_cycle ?? void 0,
+          actionedCycle: r.actioned_cycle ?? void 0,
           target: r.target ?? void 0
         }));
       }
@@ -7148,11 +7287,14 @@ ${newParts.join("\n")}` : newParts.join("\n");
         const over = acc?.over ?? "0";
         const matchRate = total > 0 ? Math.round(parseInt(matches, 10) / total * 100) : 0;
         const velocityStr = raw.velocity.map((r) => `Cycle ${r.cycle}: ${r.count} tasks`).join(", ");
-        const topSurprises = raw.surprises.slice(0, 3).map((s) => `- ${s.length > 150 ? s.slice(0, 150) + "..." : s}`).join("\n");
+        const topSurprises = raw.surprises.filter((s) => s.text && !["None", "none", "N/A", ""].includes(s.text)).slice(0, 3).map((s) => `- ${s.text.length > 150 ? s.text.slice(0, 150) + "..." : s.text}`).join("\n");
+        const topDeadEnds = raw.surprises.filter((s) => s.deadEnds && !["None", "none", "N/A", ""].includes(s.deadEnds)).slice(0, 3).map((s) => `- ${s.deadEnds.length > 150 ? s.deadEnds.slice(0, 150) + "..." : s.deadEnds}`).join("\n");
         const buildIntelligence = `**Estimation:** ${matchRate}% match rate (${matches}/${total}), ${under} under-estimated, ${over} over-estimated.
 **Velocity (last 5 cycles):** ${velocityStr || "No data"}
 ` + (topSurprises ? `**Recent surprises:**
-${topSurprises}` : "");
+${topSurprises}
+` : "") + (topDeadEnds ? `**Recent dead ends:**
+${topDeadEnds}` : "");
         const cycleLog = raw.cycleLog.length === 0 ? "No cycle log entries yet." : raw.cycleLog.map(
           (r) => `### Cycle ${r.cycle_number} \u2014 ${r.title}
 ${r.content}` + (r.carry_forward ? `
@@ -7237,12 +7379,12 @@ ${r.content}` + (r.carry_forward ? `
         ORDER BY cycle DESC
         LIMIT 5
       `,
-          // Build intelligence: recent surprises
+          // Build intelligence: recent surprises + dead ends
           this.sql`
-        SELECT surprises
+        SELECT surprises, dead_ends
         FROM build_reports
         WHERE project_id = ${this.projectId}
-          AND surprises NOT IN ('None', 'none', 'N/A', '')
+          AND (surprises NOT IN ('None', 'none', 'N/A', '') OR dead_ends IS NOT NULL)
         ORDER BY cycle DESC
         LIMIT 10
       `,
@@ -7276,7 +7418,7 @@ ${r.content}` + (r.carry_forward ? `
           board: [...boardRows],
           accuracy: accuracyRows[0] ?? { total: "0", matches: "0", over: "0", under: "0" },
           velocity: [...velocityRows],
-          surprises: surpriseRows.map((r) => r.surprises),
+          surprises: surpriseRows.map((r) => ({ text: r.surprises, deadEnds: r.dead_ends })),
           cycleLog: [...logRows],
           activeDecisions: [...adRows]
         });
@@ -7328,7 +7470,7 @@ ${r.content}` + (r.carry_forward ? `
         }));
         await this.sql`INSERT INTO entity_references ${this.sql(values2)}`;
       }
-      async getDecisionUsage(currentSprint) {
+      async getDecisionUsage(currentCycle) {
         const rows = await this.sql`
       SELECT decision_id, reference_count, last_referenced_cycle
       FROM v_decision_usage
@@ -7338,7 +7480,7 @@ ${r.content}` + (r.carry_forward ? `
           decisionId: r.decision_id,
           referenceCount: parseInt(r.reference_count, 10),
           lastReferencedCycle: r.last_referenced_cycle,
-          cyclesSinceLastReference: currentSprint - r.last_referenced_cycle
+          cyclesSinceLastReference: currentCycle - r.last_referenced_cycle
         }));
       }
       async getContextUtilisation() {
@@ -7435,8 +7577,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
                 depends_on: task.dependsOn ?? null,
                 notes: task.notes ?? null,
                 closure_reason: task.closureReason ?? null,
-                state_history: JSON.stringify(task.stateHistory ?? []),
-                build_handoff: task.buildHandoff ? JSON.stringify(task.buildHandoff) : null,
+                state_history: this.sql.json(task.stateHistory ?? []),
+                build_handoff: task.buildHandoff ? this.sql.json(task.buildHandoff) : null,
                 build_report: task.buildReport ?? null,
                 task_type: task.taskType ?? null,
                 maturity: task.maturity ?? null,
@@ -7615,7 +7757,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
           ${projectId}, ${payload.cycle.number}, ${payload.cycle.status},
           ${payload.cycle.startDate}, ${payload.cycle.endDate ?? null},
           ${payload.cycle.goals}, ${payload.cycle.boardHealth}, ${sprintTaskIds},
-          ${payload.cycle.contextHashes ? JSON.stringify(payload.cycle.contextHashes) : null}
+          ${payload.cycle.contextHashes ? this.sql.json(payload.cycle.contextHashes) : null}
         )
         ON CONFLICT (project_id, number)
         DO UPDATE SET
@@ -7645,10 +7787,57 @@ var proxy_adapter_exports = {};
 __export(proxy_adapter_exports, {
   ProxyPapiAdapter: () => ProxyPapiAdapter
 });
-var ProxyPapiAdapter;
+function snakeToCamel(str) {
+  return str.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function transformKeys(obj) {
+  if (obj === null || obj === void 0) return obj;
+  if (Array.isArray(obj)) return obj.map(transformKeys);
+  if (typeof obj === "object" && obj !== null) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      const camelKey = snakeToCamel(key);
+      result[camelKey] = JSONB_PASSTHROUGH_KEYS.has(camelKey) ? value : transformKeys(value);
+    }
+    return result;
+  }
+  return obj;
+}
+function fixDisplayIdEntity(obj) {
+  if (obj.displayId !== void 0) {
+    obj.uuid = obj.id;
+    obj.id = obj.displayId;
+  }
+  return obj;
+}
+function fixDisplayIdEntities(data) {
+  if (Array.isArray(data)) return data.map((item) => fixDisplayIdEntity(item));
+  if (data && typeof data === "object") return fixDisplayIdEntity(data);
+  return data;
+}
+var JSONB_PASSTHROUGH_KEYS, DISPLAY_ID_METHODS, ProxyPapiAdapter;
 var init_proxy_adapter = __esm({
   "src/proxy-adapter.ts"() {
     "use strict";
+    JSONB_PASSTHROUGH_KEYS = /* @__PURE__ */ new Set([
+      "buildHandoff",
+      "stateHistory",
+      "handoffAccuracy",
+      "briefImplications",
+      "autoReview",
+      "structuredData",
+      "data"
+    ]);
+    DISPLAY_ID_METHODS = /* @__PURE__ */ new Set([
+      "queryBoard",
+      "getTask",
+      "getTasks",
+      "createTask",
+      "getRecentBuildReports",
+      "getBuildReportsSince",
+      "getRecentReviews",
+      "getActiveDecisions"
+    ]);
     ProxyPapiAdapter = class {
       endpoint;
       apiKey;
@@ -7661,6 +7850,7 @@ var init_proxy_adapter = __esm({
       /**
        * Send an adapter method call to the proxy Edge Function.
        * Serializes { projectId, method, args } and deserializes the response.
+       * Results are transformed from snake_case to camelCase to match pg adapter output.
        */
       async invoke(method, args = []) {
         const url = `${this.endpoint}/invoke`;
@@ -7691,7 +7881,11 @@ var init_proxy_adapter = __esm({
         if (!body.ok && body.error) {
           throw new Error(`Proxy error on ${method}: ${body.error}`);
         }
-        return body.result;
+        let result = transformKeys(body.result);
+        if (DISPLAY_ID_METHODS.has(method)) {
+          result = fixDisplayIdEntities(result);
+        }
+        return result;
       }
       /** Check if the proxy is reachable. */
       async probeConnection() {
@@ -7838,9 +8032,6 @@ var init_proxy_adapter = __esm({
       getCostSummary(cycleNumber) {
         return this.invoke("getCostSummary", [cycleNumber]);
       }
-      writeCostSnapshot(snapshot) {
-        return this.invoke("writeCostSnapshot", [snapshot]);
-      }
       getCostSnapshots() {
         return this.invoke("getCostSnapshots");
       }
@@ -7979,6 +8170,7 @@ function loadConfig() {
   const autoCommit2 = process.env.PAPI_AUTO_COMMIT !== "false";
   const baseBranch = process.env.PAPI_BASE_BRANCH ?? "main";
   const autoPR = process.env.PAPI_AUTO_PR !== "false";
+  const lightMode = process.env.PAPI_LIGHT_MODE === "true";
   const papiEndpoint = process.env.PAPI_ENDPOINT;
   const dataEndpoint = process.env.PAPI_DATA_ENDPOINT;
   const databaseUrl = process.env.DATABASE_URL;
@@ -7992,15 +8184,29 @@ function loadConfig() {
     baseBranch,
     autoPR,
     adapterType,
-    papiEndpoint
+    papiEndpoint,
+    lightMode
   };
 }
 
 // src/adapter-factory.ts
 init_dist2();
 import path2 from "path";
+import { execSync } from "child_process";
+function detectUserId() {
+  try {
+    const email = execSync("git config user.email", { encoding: "utf8", timeout: 5e3 }).trim();
+    if (email) return email;
+  } catch {
+  }
+  try {
+    const ghUser = execSync("gh api user --jq .email", { encoding: "utf8", timeout: 1e4 }).trim();
+    if (ghUser && ghUser !== "null") return ghUser;
+  } catch {
+  }
+  return void 0;
+}
 var HOSTED_PROXY_ENDPOINT = "https://guewgygcpcmrcoppihzx.supabase.co/functions/v1/data-proxy";
-var HOSTED_PROXY_KEY = "e9891a0a2225ac376f88ebdad78b4814b52ce0a39a41c5ec";
 var PLACEHOLDER_PATTERNS = [
   "<YOUR_DATABASE_URL>",
   "your-database-url",
@@ -8060,7 +8266,18 @@ async function createAdapter(optionsOrType, maybePapiDir) {
         if (!existing) {
           const projectRoot = options.projectRoot ?? process.env["PAPI_PROJECT_DIR"] ?? "";
           const slug = path2.basename(projectRoot) || "unnamed";
-          const userId = process.env["PAPI_USER_ID"] ?? void 0;
+          let userId = process.env["PAPI_USER_ID"] ?? void 0;
+          if (!userId) {
+            userId = detectUserId();
+            if (userId) {
+              console.error(`[papi] Auto-detected user identity: ${userId}`);
+              console.error("[papi] Set PAPI_USER_ID in .mcp.json to make this explicit.");
+            } else {
+              console.error("[papi] \u26A0 No PAPI_USER_ID set and auto-detection failed.");
+              console.error("[papi]   Project will have no user scope \u2014 it may be visible to all dashboard users.");
+              console.error("[papi]   Set PAPI_USER_ID in your .mcp.json env to fix this.");
+            }
+          }
           await pgAdapter.createProject({ id: projectId, slug, name: slug, papi_dir: papiDir, user_id: userId });
         }
         await pgAdapter.close();
@@ -8091,7 +8308,17 @@ async function createAdapter(optionsOrType, maybePapiDir) {
         );
       }
       const dataEndpoint = process.env["PAPI_DATA_ENDPOINT"] || HOSTED_PROXY_ENDPOINT;
-      const dataApiKey = process.env["PAPI_DATA_API_KEY"] || HOSTED_PROXY_KEY;
+      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
+  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.`
+        );
+      }
       const adapter2 = new ProxyPapiAdapter2({
         endpoint: dataEndpoint,
         apiKey: dataApiKey,
@@ -8446,6 +8673,61 @@ function formatReviews(reviews) {
 - **Comments:** ${r.comments}`
   ).join("\n\n---\n\n");
 }
+function formatTaskComments(comments, taskIds, heading = "## Task Comments") {
+  const relevant = comments.filter((c) => taskIds.has(c.taskId));
+  if (relevant.length === 0) return "";
+  const byTask = /* @__PURE__ */ new Map();
+  for (const c of relevant) {
+    const list = byTask.get(c.taskId) ?? [];
+    list.push(c);
+    byTask.set(c.taskId, list);
+  }
+  const lines = ["", heading];
+  for (const [taskId, taskComments] of byTask) {
+    for (const c of taskComments.slice(0, 3)) {
+      const date = c.createdAt.split("T")[0];
+      const text = c.content.length > 200 ? c.content.slice(0, 200) + "..." : c.content;
+      lines.push(`- **${taskId}** \u2014 ${c.author} (${date}): "${text}"`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatDiscoveryCanvas(canvas) {
+  const sections = [];
+  if (canvas.landscapeReferences && canvas.landscapeReferences.length > 0) {
+    sections.push("**Landscape & References:**");
+    for (const ref of canvas.landscapeReferences) {
+      const url = ref.url ? ` (${ref.url})` : "";
+      const notes = ref.notes ? ` \u2014 ${ref.notes}` : "";
+      sections.push(`- ${ref.name}${url}${notes}`);
+    }
+  }
+  if (canvas.userJourneys && canvas.userJourneys.length > 0) {
+    sections.push("**User Journeys:**");
+    for (const j of canvas.userJourneys) {
+      const priority = j.priority ? ` [${j.priority}]` : "";
+      sections.push(`- **${j.persona}:** ${j.journey}${priority}`);
+    }
+  }
+  if (canvas.mvpBoundary) {
+    sections.push("**MVP Boundary:**", canvas.mvpBoundary);
+  }
+  if (canvas.assumptionsOpenQuestions && canvas.assumptionsOpenQuestions.length > 0) {
+    sections.push("**Assumptions & Open Questions:**");
+    for (const a of canvas.assumptionsOpenQuestions) {
+      const evidence = a.evidence ? ` Evidence: ${a.evidence}` : "";
+      sections.push(`- [${a.status}] ${a.text}${evidence}`);
+    }
+  }
+  if (canvas.successSignals && canvas.successSignals.length > 0) {
+    sections.push("**Success Signals:**");
+    for (const s of canvas.successSignals) {
+      const metric = s.metric ? ` (${s.metric}` + (s.target ? `, target: ${s.target})` : ")") : "";
+      sections.push(`- ${s.signal}${metric}`);
+    }
+  }
+  return sections.length > 0 ? sections.join("\n") : void 0;
+}
 
 // src/lib/git.ts
 import { execFileSync } from "child_process";
@@ -8470,6 +8752,11 @@ function isGitRepo(cwd) {
   }
 }
 function stageDirAndCommit(cwd, dir, message) {
+  try {
+    execFileSync("git", ["check-ignore", "-q", dir], { cwd });
+    return { committed: false, message: `Skipped commit \u2014 '${dir}' is gitignored.` };
+  } catch {
+  }
   execFileSync("git", ["add", dir], { cwd });
   const staged = execFileSync("git", ["diff", "--cached", "--name-only"], {
     cwd,
@@ -8779,6 +9066,16 @@ function getHeadCommitSha(cwd) {
     return null;
   }
 }
+function runAutoCommit(projectRoot, commitFn) {
+  if (!isGitAvailable()) return "Auto-commit: skipped (git not found).";
+  if (!isGitRepo(projectRoot)) return "Auto-commit: skipped (not a git repository).";
+  try {
+    const result = commitFn();
+    return result.committed ? `Auto-committed: ${result.message}` : `Auto-commit: ${result.message}`;
+  } catch (err) {
+    return `Auto-commit failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}
 function getFilesChangedFromBase(cwd, baseBranch) {
   try {
     const mergeBase = execFileSync("git", ["merge-base", baseBranch, "HEAD"], { cwd, encoding: "utf-8" }).trim();
@@ -8985,6 +9282,9 @@ SECURITY CONSIDERATIONS
 REFERENCE DOCS
 [Optional \u2014 paths to docs/ files that provide background context for this task. Include only when the task originated from research or scoping work and the doc contains context the builder will need beyond what is in this handoff. Omit this section entirely for tasks that don't need supplementary context.]
 
+PRE-BUILD VERIFICATION
+[List 2-5 specific file paths the builder should read BEFORE implementing to check if the functionality already exists. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. If >80% of the scope is already implemented, the builder should report "already built" instead of re-implementing. Include this section for EVERY task \u2014 it prevents wasted build slots on already-shipped code.]
+
 FILES LIKELY TOUCHED
 [files]
 
@@ -9016,6 +9316,27 @@ After your natural language output, include this EXACT format on its own line:
 
 The JSON must be valid. Use null for optional fields that don't apply.
 
+## GUIDING PRINCIPLES
+
+These principles come from 150+ cycles of dogfooding. They shape how the planner should think about planning:
+
+- **Validate before advancing.** Don't push forward when things aren't proven.
+- **Every artifact needs a consumer.** If not consumed by the next cycle, it's waste.
+- **Upstream learning.** Every build informs the next plan.
+- **Commands surfaced, not memorized.** Always show what's next.
+- **Tough advisor, not cheerleader.** Push back on scope creep and bad ideas.
+- **BUILD HANDOFFs are the differentiator.** A third LLM executed tasks from handoffs alone.
+- **The methodology works.** Plan/build/review cycle produces compounding velocity.
+
+## DETECT STRATEGIC DECISIONS
+
+Watch for direction changes, architecture shifts, deprioritisation with reasoning, new principles, or competitive positioning decisions in the project context.
+
+When detected:
+1. Flag it in the cycle log: "Strategic direction change detected \u2014 [description]."
+2. If confirmed by evidence (build reports, AD changes, carry-forward), propose an AD update or new AD in the structured output.
+3. If mid-cycle context suggests a pivot, note it for the next strategy review rather than over-reacting in the plan.
+
 ## PERSISTENCE RULES \u2014 READ THIS CAREFULLY
 
 Everything in Part 1 (natural language) is **display-only**. Part 2 (structured JSON) is what gets written to files.
@@ -9079,12 +9400,18 @@ Standard planning cycle with full board review.
 1. **Cycle Health Check** \u2014 Flag issues: >7 day gaps, unprocessed discovered issues, AD conflicts, stale In Progress tasks (3+ cycles).
    **\u26A0\uFE0F CARRY-FORWARD STALENESS:** Check the latest carry-forward text for items containing "stale", "already exists", "already implemented", or "already built". For each such item that references a specific task ID, check whether the task is still in Backlog. If a carry-forward says a task's deliverables already exist but the task is still Backlog, emit a \`boardCorrections\` entry setting it to Done with \`closureReason: "Auto-closed \u2014 carry-forward indicates deliverables already exist"\`. Log in the cycle log: "Auto-closed task-XXX \u2014 carry-forward confirmed deliverables exist." This prevents scheduling already-shipped tasks.
 
-2. **Inbox Triage** \u2014 Find unreviewed tasks (reviewed = false). For each: clean title, fill all fields, check for duplicates, verify alignment with Active Decisions. You MAY set priority on unreviewed tasks during triage. If a task is clearly obsolete, duplicated, or rejected, set its status to "Cancelled" with a \`closureReason\` explaining why.
+2. **Inbox Triage** \u2014 Find unreviewed tasks (reviewed = false). For each: clean title, fill all fields, check for duplicates, verify alignment with Active Decisions. You MUST set priority on unreviewed tasks during triage using these criteria:
+   - **P0 Critical** \u2014 Broken, blocking, or data-loss risk. Fix now.
+   - **P1 High** \u2014 Strategically aligned: directly advances the current horizon/phase goals or Active Decisions.
+   - **P2 Medium** \u2014 Valuable but not strategically urgent: quality improvements, efficiency, polish, infrastructure.
+   - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
+   Also set complexity using the full range \u2014 **XS, Small, Medium, Large, XL** \u2014 based on actual scope, not conservatively. XS = single-line or config change. Small = one file, < 50 lines. Medium = 2-5 files. Large = cross-module, multiple components. XL = architectural, multi-day.
+   If a task is clearly obsolete, duplicated, or rejected, set its status to "Cancelled" with a \`closureReason\` explaining why.
    **\u2192 PERSIST:** For each task you set reviewed: true, corrected fields on, or marked "Cancelled", include it in \`boardCorrections\` in Part 2.
 
 3. **Board Integrity** \u2014 All tasks have complete fields? Priority still accurate? Duplicates? Stale In Progress tasks?
    **\u2192 PERSIST:** Include any field corrections (status updates, field fixes) in \`boardCorrections\` in Part 2.
-   **\u26A0\uFE0F PRIORITY LOCK RULE:** Do NOT change the priority of any task that has \`reviewed: true\`. Reviewed tasks have had their priority confirmed by a human. If you believe a reviewed task's priority should change, note your recommendation in the cycle log but do NOT include a priority change in \`boardCorrections\`. You may only set priority on unreviewed tasks (during triage) or on newly created tasks (\`newTasks\` array).
+   **\u26A0\uFE0F PRIORITY LOCK RULE:** Do NOT change the priority of any task that has \`reviewed: true\`. Reviewed tasks have had their priority confirmed by a human. If you believe a reviewed task's priority should change, note your recommendation in the cycle log but do NOT include a priority change in \`boardCorrections\`. You may only set priority on unreviewed tasks (during triage) or on newly created tasks (\`newTasks\` array). Priority values: P0 Critical, P1 High, P2 Medium, P3 Low.
 
 4. **Security Posture Check** \u2014 Review recently completed tasks and current board state for security concerns. Only flag genuine issues \u2014 do not add boilerplate security notes every cycle. Look for:
    - Data exposure risks introduced by recent builds (PII in logs, secrets in storage/config)
@@ -9099,34 +9426,41 @@ Standard planning cycle with full board review.
    - **Cycle number as signal:** A Cycle 3 project should not be scheduling OAuth, billing, or analytics tasks. Early cycles focus on core functionality and proving the concept works.
    - **Phase prerequisites:** If the board has phases, tasks from later phases should only be scheduled when earlier phases have completed tasks (check Done count per phase). A task in "Phase 4: Monetisation" is premature if Phase 2 tasks are still in Backlog.
    - **Dependency chain:** If a task's \`dependsOn\` references incomplete tasks, it cannot be scheduled regardless of priority.
-   - **Task maturity:** Tasks with \`maturity: "raw"\` are unscoped ideas \u2014 they lack clear acceptance criteria and scope. Do NOT schedule raw tasks or generate BUILD HANDOFFs for them. Instead, either: (a) upgrade them to \`maturity: "investigated"\` via a \`boardCorrections\` entry if you can derive clear scope from the title and context, or (b) leave them in Backlog and note in the cycle log that they need investigation. Tasks with \`maturity: "ready"\` or no maturity field are considered cycle-ready. Tasks with \`maturity: "investigated"\` have been scoped but may still need refinement \u2014 schedule them if priority warrants it.
-   - **What to do with premature tasks:** Leave them in Backlog. Do NOT generate BUILD HANDOFFs for them. If a high-priority task fails the maturity gate, note it in the cycle log: "task-XXX deferred \u2014 Phase N prerequisites not met" or "task-XXX deferred \u2014 raw idea, needs investigation."
+   - **Task maturity:** Tasks with \`maturity: "raw"\` are unscoped ideas from the idea tool. The planner IS the scoping mechanism \u2014 scope them as part of planning. For raw tasks selected for a cycle: (a) derive clear scope, acceptance criteria, and effort from the title, notes, and project context, (b) upgrade them to \`maturity: "investigated"\` via a \`boardCorrections\` entry, and (c) generate a BUILD HANDOFF as normal. For research-type raw tasks, scope the handoff as an investigation task \u2014 the deliverable is findings + follow-up backlog tasks, not code. Only leave a raw task unscheduled if you genuinely cannot derive scope from the available context \u2014 note why in the cycle log. Tasks with \`maturity: "ready"\` or no maturity field are considered cycle-ready. Tasks with \`maturity: "investigated"\` have been scoped but may still need refinement \u2014 schedule them if priority warrants it.
+   - **What to do with premature tasks:** Leave them in Backlog. Do NOT generate BUILD HANDOFFs for them. If a high-priority task fails the maturity gate due to phase prerequisites or dependencies, note it in the cycle log: "task-XXX deferred \u2014 Phase N prerequisites not met". Raw tasks are NOT premature \u2014 they just need scoping (see Task maturity above).
 
 7. **Recommendation** \u2014 Pick ONE task to recommend:
-   **If USER DIRECTION is provided above:** Follow the user's stated focus. Pick the highest-impact task that aligns with their direction. The user knows what they need \u2014 do not override their direction with the tier system. Only deviate if a genuine Tier 0 critical fix exists (broken builds, data loss).
-   **Otherwise, use priority tiers:**
-   - Tier 0: Critical fixes from Build Reports
-   - Tier 1: User feedback aligned with Active Decisions
-   - Tier 2: Activation blockers
-   - Tier 3: Usage multipliers (infra/UX improvements)
-   - Tier 4: Data visualization
-   - Tier 5: New capability
-   Within a tier: smaller effort wins. Justify in 2-3 sentences.
-   **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 3-5 tasks. A 1-task cycle is almost never correct \u2014 if only 1 task qualifies, check if lower-priority tasks could also ship.
+   **If USER DIRECTION is provided above:** Follow the user's stated focus. Pick the highest-impact task that aligns with their direction. The user knows what they need. Only deviate if a genuine P0 Critical fix exists (broken builds, data loss).
+   **Otherwise, select by priority level then impact:**
+   - **P0 Critical** \u2014 Broken, blocking, or data-loss risk. Always first.
+   - **P1 High** \u2014 Strategically aligned: directly advances the current horizon, phase, or Active Decision goals.
+   - **P2 Medium** \u2014 Valuable but not strategically urgent: quality improvements, efficiency, polish, infra.
+   - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
+   Within the same priority level, prefer tasks with the highest **impact-to-effort ratio**. Impact is measured by: (a) strategic alignment \u2014 does it advance the current horizon/phase? (b) unlocks other work \u2014 are tasks blocked by this? (c) user-facing \u2014 does it change what users see? (d) compounds over time \u2014 does it make future cycles faster? A high-impact Medium task beats a low-impact Small task at the same priority level. Justify in 2-3 sentences.
+   **Blocked tasks:** Tasks with status "Blocked" MUST be skipped during task selection \u2014 they are waiting on external dependencies or gates and cannot be built. Do NOT generate BUILD HANDOFFs for blocked tasks. Do NOT recommend blocked tasks. If a blocked task's gate has been resolved (check the notes and recent build reports), emit a \`boardCorrections\` entry to move it back to Backlog. Report blocked task count in the cycle log.
+   **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge from the tasks themselves. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 4-6 tasks. Cycles with fewer than 4 tasks require explicit justification in the cycle log \u2014 explain why more tasks could not be included. When the backlog has 10+ tasks, the cycle SHOULD have 5+ tasks \u2014 undersized cycles waste planning overhead relative to the available work. If fewer than 4 tasks qualify after filtering (blocked, deferred, raw), check Deferred tasks \u2014 some may be ready to un-defer via a \`boardCorrections\` entry. A 1-task cycle is almost never correct.
 
 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.
 
 9. **Active Decisions** \u2014 If any AD needs updating: Type A (confidence change), Type B (modification), or Type C (reversal/supersede).
+   **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. Apply this bar when proposing new ADs and when triaging existing ones.
    **\u2192 PERSIST:** EVERY AD you created, updated, or confirmed with changes MUST appear in \`activeDecisions\` array in Part 2. Include the full replacement body with ### heading.
 
+### Operational Quality Rules
+- **Idea similarity pause:** When the idea tool finds similar tasks during planning, stop and explain the overlap \u2014 do not silently ignore the similarity warning. Duplicates bloat the board and waste build slots.
+- **Backlog as steering wheel:** Task priority and notes in the backlog are the user's primary control mechanism over what gets planned. Respect the priority rankings and read task notes carefully \u2014 they contain user intent that shapes scope and scheduling.
+- **Planning quality is the bar:** Strategy review depth and plan quality set the standard for the product. Do not cut corners on analysis depth, triage thoroughness, or handoff specificity \u2014 these are what users experience as PAPI's value.
+
 10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for the recommended task and up to 4 additional high-priority unblocked tasks (5 total max). Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability. Remaining tasks will get handoffs in subsequent plans \u2014 do NOT try to cover the entire backlog.
    **SKIP existing handoffs:** Tasks marked with "Has BUILD HANDOFF: yes" or "\u2713 handoff" on the board already have a valid handoff from a previous plan. Do NOT regenerate handoffs for these tasks \u2014 omit them from the \`cycleHandoffs\` array entirely. Only generate handoffs for tasks that do NOT have one yet. Exception: if a task's dependencies have been completed since its handoff was written, or a relevant Active Decision has changed, you MAY regenerate its handoff \u2014 but note this explicitly in the cycle log.
+   **Scope pre-check:** Before writing the SCOPE section of each handoff, check whether the described functionality already exists based on the task's context, recent build reports, and the FILES LIKELY TOUCHED. If the infrastructure likely exists (e.g. a status type, a DB constraint, an API route), reduce the scope to only the missing pieces and explicitly note what already exists. C126 task-728 was over-scoped because the planner assumed Blocked status needed creating from scratch \u2014 it already existed in types, DB, orient, and build_list. Over-scoped handoffs waste builder time on verification and cause estimation mismatches.
    **Simplest Viable Path rule:** Before writing each BUILD HANDOFF, identify the simplest approach that satisfies the task's goal \u2014 the minimum change, fewest new abstractions, and smallest blast radius. Write the SCOPE (DO THIS) section for that simplest path FIRST. If you believe a more complex approach is warranted (new abstractions, multi-file refactors, framework changes), you MUST include a "WHY NOT SIMPLER" line in the handoff explaining why the simple path is insufficient. If you cannot articulate a concrete reason, use the simpler path. Pay special attention to tasks involving auth, data access, multi-user features, and infrastructure \u2014 these are the most common over-engineering targets.
-   **Maturity gate applies here:** Do NOT generate BUILD HANDOFFs for tasks that failed the maturity gate in step 6. This includes raw tasks (\`maturity: "raw"\`) and tasks whose phase prerequisites are not met. Only cycle-ready tasks should receive handoffs.
+   **Maturity gate applies here:** Do NOT generate BUILD HANDOFFs for tasks that failed the maturity gate in step 6 (phase prerequisites not met, dependency chain incomplete). Raw tasks that the planner has scoped and upgraded to "investigated" in step 6 ARE eligible for handoffs.
    **Security section guidance:** Each handoff includes a SECURITY CONSIDERATIONS section. Populate it when the task involves: data exposure risks (PII, secrets in logs/storage), secrets or credentials handling (API keys, tokens, env vars), auth/access control changes, or dependency security risks (new packages, version changes). For pure refactoring, documentation, prompt-text, or UI-only tasks, write "None \u2014 no security-relevant changes".
-   **Estimation calibration:** Tasks that wire existing adapter methods, add API routes following established patterns, modify prompts, or make documentation-only changes should be estimated **S** unless they require new abstractions, new DB tables, or multi-file architectural changes. Default to S for pattern-following work. Only use M when genuine new architecture is needed. 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).
+   **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."
@@ -9147,7 +9481,7 @@ Standard planning cycle with full board review.
    - The North Star changed or was validated in a way that the brief doesn't reflect
    - A phase completed that shifts what the product IS (not just what was built)
    - The brief describes capabilities, architecture, or direction that are no longer accurate
-   - **STALENESS CHECK:** Look at the "Last updated" line in the brief. If it references a cycle number more than 10 cycles behind the current cycle, the brief is stale and MUST be updated \u2014 even if no single trajectory-changing event occurred, cumulative drift over 10+ cycles means the brief no longer represents the product. This is the #1 source of planner drift.
+   - **DRIFT CHECK:** Compare the brief's content against current reality. The brief is drifted if: (a) it describes capabilities that don't exist or have been removed, (b) it references user types, architecture, or positioning that ADs have since changed, (c) the current phase/stage has shifted from what the brief describes, or (d) key metrics or success criteria no longer match the project's direction. Cycle count since last update is a secondary signal only \u2014 a brief updated 15 cycles ago that still accurately describes the product is NOT stale. A brief updated 3 cycles ago that contradicts a recent AD IS drifted.
    If any of these apply, include an updated \`productBrief\` in the structured output. Include the FULL updated brief (not a diff). Preserve all existing sections and user-added content; update facts, numbers, and status to reflect current reality. Do not regenerate the brief every cycle \u2014 but do not let it go stale either.
 
 13. **Forward Horizon** \u2014 If a Forward Horizon section is provided in the context below, write a "## Forward Horizon" section in Part 1. Surface 2-3 decisions the team should make before the next phase starts. Each item must be:
@@ -9168,7 +9502,7 @@ function buildPlanUserMessage(ctx) {
     parts.push(
       `## USER DIRECTION`,
       "",
-      `The user has provided the following direction for this cycle. This OVERRIDES the autonomous priority tier system in Step 5. Prioritise tasks that align with this direction, even if lower-priority tasks exist on the board.`,
+      `The user has provided the following direction for this cycle. This OVERRIDES the autonomous priority-based selection in Step 7. Prioritise tasks that align with this direction, even if lower-priority tasks exist on the board.`,
       "",
       `> ${ctx.focus}`,
       ""
@@ -9325,9 +9659,18 @@ IMPORTANT: You are running as a non-interactive API call. Do NOT ask the user qu
 
 ## OUTPUT PRINCIPLES
 
-- **Concise and actionable.** Lead with findings, not data recitation. Each recommendation must include a specific action, not a vague suggestion.
+- **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.
+- **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 section earns its place.** If a section has nothing meaningful to say, skip it entirely. Do not write "No issues found" or "No concerns" \u2014 just omit the section.
+- **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.
+
+## 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.
+
+Present the full review first. Let the analysis breathe. The user will discuss, push back, and refine before acting on the structured output.
 
 ## YOUR JOB \u2014 STRUCTURED COVERAGE
 
@@ -9345,7 +9688,7 @@ You MUST cover these 6 sections. Each is mandatory unless explicitly noted as co
    - 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?
-   - If the North Star hasn't been referenced in 10+ cycles, flag it as potentially stale.
+   - 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.
 
 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):
@@ -9355,6 +9698,7 @@ You MUST cover these 6 sections. Each is mandatory unless explicitly noted as co
    - **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 relevant)
@@ -9374,6 +9718,7 @@ ${compressionJob}
    - **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):
@@ -9397,11 +9742,11 @@ ${compressionJob}
    - 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 Staleness Detection** \u2014 If decision usage data is provided in context, identify structural decay:
-   - ADs that haven't been **referenced in 10+ cycles** \u2192 flag as potentially obsolete, recommend review or resolution.
-   - Carry-forward items that have persisted across **3+ cycles** without resolution \u2192 flag as stuck.
-   - ADs with LOW confidence that have persisted for 5+ cycles without evidence \u2192 flag as unvalidated.
-   Reference the decision usage data for quantitative staleness signals rather than guessing. Report findings in a "Structural Staleness" 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.
+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.
 
 ## OUTPUT FORMAT
 
@@ -9422,7 +9767,7 @@ Then include conditional sections only if relevant:
 - **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 Staleness** \u2014 only if unreferenced ADs or stuck carry-forwards found${compressionPart1}
+- **Structural Drift** \u2014 only if drifted ADs or stuck carry-forwards found${compressionPart1}
 
 ### Part 2: Structured Data Block
 After your natural language output, include this EXACT format on its own line:
@@ -9584,6 +9929,21 @@ function buildReviewUserMessage(ctx) {
   if (ctx.recommendationEffectiveness) {
     parts.push("### Recommendation Follow-Through", "", ctx.recommendationEffectiveness, "");
   }
+  if (ctx.adHocCommits) {
+    parts.push("### Ad-hoc Work (Non-Task Commits)", "", ctx.adHocCommits, "");
+  }
+  if (ctx.pendingRecommendations) {
+    parts.push("### Pending Strategy Recommendations", "", ctx.pendingRecommendations, "");
+  }
+  if (ctx.registeredDocs) {
+    parts.push("### Registered Documents", "", ctx.registeredDocs, "");
+  }
+  if (ctx.recentPlans) {
+    parts.push("### Recent Plans (since last review)", "", ctx.recentPlans, "");
+  }
+  if (ctx.unregisteredDocs) {
+    parts.push("### Unregistered Docs", "", ctx.unregisteredDocs, "");
+  }
   return parts.join("\n");
 }
 function parseReviewStructuredOutput(raw) {
@@ -9848,6 +10208,7 @@ The body format for each AD:
 - Each AD should be actionable and falsifiable (something the team could decide differently)
 - Cover different concerns: architecture, data, deployment, testing strategy, API design, etc.
 - Keep each AD body to 4-6 lines \u2014 concise and scannable
+- **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, configuration choices, or temporary workarounds.
 
 Return ONLY valid JSON \u2014 no preamble, no code fences, no explanation.`;
 function buildAdSeedPrompt(ctx) {
@@ -9925,8 +10286,8 @@ IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions.
 
 Return a JSON array of 3-10 tasks. Each task must have:
 - "title": Clear, actionable task title (start with a verb)
-- "priority": "P1 High", "P2 Medium", or "P3 Low"
-- "complexity": "XS", "Small", "Medium", or "Large"
+- "priority": "P0 Critical", "P1 High", "P2 Medium", or "P3 Low"
+- "complexity": "XS", "Small", "Medium", "Large", or "XL"
 - "module": A module name inferred from the codebase (e.g. "Core", "API", "Frontend", "Infra", "Tests")
 - "phase": A phase name (e.g. "Phase 1", "Phase 2")
 - "notes": 1-2 sentences of context about why this task matters
@@ -9936,8 +10297,8 @@ Return a JSON array of 3-10 tasks. Each task must have:
 - Focus on gaps and improvements visible from the codebase structure \u2014 not features the user hasn't asked for
 - Common gap categories: missing tests, missing documentation, config improvements, dependency updates, code quality, security hardening
 - Do NOT suggest adding PAPI itself or PAPI-specific tasks \u2014 those are handled by the setup flow
-- Prioritise tasks that reduce risk or unblock future work (P1) over nice-to-haves (P3)
-- Keep complexity estimates conservative \u2014 Small for most tasks, Medium for multi-file changes
+- Prioritise tasks that reduce risk or unblock future work (P0/P1) over nice-to-haves (P3)
+- Use the full complexity range: XS (config/one-liner), Small (one file), Medium (2-5 files), Large (cross-module), XL (architectural)
 - Tasks should be specific enough to execute without further investigation
 - Maximum 10 tasks \u2014 fewer is better if the codebase is well-maintained`;
 function buildInitialTasksPrompt(inputs) {
@@ -10051,27 +10412,58 @@ function pushAfterCommit(config2) {
   return push.success ? `> ${push.message}` : `> Warning: ${push.message}`;
 }
 function autoCommitPapi(config2, cycleNumber, mode) {
-  if (!isGitAvailable()) {
-    return "Auto-commit: skipped (git not found).";
-  }
-  if (!isGitRepo(config2.projectRoot)) {
-    return "Auto-commit: skipped (not a git repository).";
+  const modeLabel = mode === "bootstrap" ? "Bootstrap" : "Full";
+  return runAutoCommit(
+    config2.projectRoot,
+    () => stageDirAndCommit(config2.projectRoot, ".papi", `papi: Cycle ${cycleNumber} plan \u2014 ${modeLabel}`)
+  );
+}
+async function assembleTaskComments(adapter2) {
+  try {
+    const comments = await adapter2.getRecentTaskComments?.(20);
+    if (comments && comments.length > 0) {
+      const byTask = /* @__PURE__ */ new Map();
+      for (const c of comments) {
+        const list = byTask.get(c.taskId) ?? [];
+        list.push(c);
+        byTask.set(c.taskId, list);
+      }
+      const lines = [];
+      for (const [taskId, taskComments] of byTask) {
+        const limited = taskComments.slice(0, 5);
+        for (const c of limited) {
+          const truncated = c.content.length > 200 ? c.content.slice(0, 200) + "..." : c.content;
+          const date = c.createdAt.split("T")[0];
+          lines.push(`- **${taskId}** \u2014 ${c.author} (${date}): "${truncated}"`);
+        }
+      }
+      return lines.join("\n");
+    }
+  } catch {
   }
+  return void 0;
+}
+async function assembleDiscoveryCanvasText(adapter2) {
   try {
-    const modeLabel = mode === "bootstrap" ? "Bootstrap" : "Full";
-    const result = stageDirAndCommit(
-      config2.projectRoot,
-      ".papi",
-      `papi: Cycle ${cycleNumber} plan \u2014 ${modeLabel}`
-    );
-    return result.committed ? `Auto-committed: ${result.message}` : `Auto-commit: ${result.message}`;
-  } catch (err) {
-    return `Auto-commit failed: ${err instanceof Error ? err.message : String(err)}`;
+    const canvas = await adapter2.readDiscoveryCanvas();
+    return formatDiscoveryCanvas(canvas);
+  } catch {
   }
+  return void 0;
 }
-function formatStrategyRecommendations(recs) {
-  const byType = /* @__PURE__ */ new Map();
+var REC_EXPIRY_CYCLES = 3;
+function formatStrategyRecommendations(recs, currentCycle) {
+  const active = [];
+  const expired = [];
   for (const rec of recs) {
+    if (currentCycle !== void 0 && rec.createdCycle && currentCycle - rec.createdCycle > REC_EXPIRY_CYCLES) {
+      expired.push(rec);
+    } else {
+      active.push(rec);
+    }
+  }
+  const byType = /* @__PURE__ */ new Map();
+  for (const rec of active) {
     const list = byType.get(rec.type) ?? [];
     list.push(rec);
     byType.set(rec.type, list);
@@ -10091,43 +10483,13 @@ function formatStrategyRecommendations(recs) {
       sections.push(`- (Cycle ${item.createdCycle}) ${item.content}${targetSuffix}`);
     }
   }
-  return sections.join("\n");
-}
-function formatDiscoveryCanvas(canvas) {
-  const sections = [];
-  if (canvas.landscapeReferences && canvas.landscapeReferences.length > 0) {
-    sections.push("**Landscape & References:**");
-    for (const ref of canvas.landscapeReferences) {
-      const url = ref.url ? ` (${ref.url})` : "";
-      const notes = ref.notes ? ` \u2014 ${ref.notes}` : "";
-      sections.push(`- ${ref.name}${url}${notes}`);
-    }
-  }
-  if (canvas.userJourneys && canvas.userJourneys.length > 0) {
-    sections.push("**User Journeys:**");
-    for (const j of canvas.userJourneys) {
-      const priority = j.priority ? ` [${j.priority}]` : "";
-      sections.push(`- **${j.persona}:** ${j.journey}${priority}`);
-    }
-  }
-  if (canvas.mvpBoundary) {
-    sections.push("**MVP Boundary:**", canvas.mvpBoundary);
-  }
-  if (canvas.assumptionsOpenQuestions && canvas.assumptionsOpenQuestions.length > 0) {
-    sections.push("**Assumptions & Open Questions:**");
-    for (const a of canvas.assumptionsOpenQuestions) {
-      const evidence = a.evidence ? ` Evidence: ${a.evidence}` : "";
-      sections.push(`- [${a.status}] ${a.text}${evidence}`);
-    }
-  }
-  if (canvas.successSignals && canvas.successSignals.length > 0) {
-    sections.push("**Success Signals:**");
-    for (const s of canvas.successSignals) {
-      const metric = s.metric ? ` (${s.metric}` + (s.target ? `, target: ${s.target})` : ")") : "";
-      sections.push(`- ${s.signal}${metric}`);
+  if (expired.length > 0) {
+    sections.push(`**Expired (${expired.length} recs skipped \u2014 older than ${REC_EXPIRY_CYCLES} cycles):**`);
+    for (const item of expired) {
+      sections.push(`- (Cycle ${item.createdCycle}) ${item.content.slice(0, 80)}...`);
     }
   }
-  return sections.length > 0 ? sections.join("\n") : void 0;
+  return sections.join("\n");
 }
 function formatEstimationCalibration(rows) {
   const total = rows.reduce((sum, r) => sum + r.count, 0);
@@ -10311,7 +10673,7 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
     try {
       const pendingRecs = await adapter2.getPendingRecommendations();
       if (pendingRecs.length > 0) {
-        strategyRecommendationsText2 = formatStrategyRecommendations(pendingRecs);
+        strategyRecommendationsText2 = formatStrategyRecommendations(pendingRecs, health.totalCycles);
       }
     } catch {
     }
@@ -10328,36 +10690,9 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
     ]);
     timings["total"] = totalTimer();
     console.error(`[plan-perf] assembleContext (lean): ${JSON.stringify(timings)}ms`);
-    let taskCommentsText;
-    try {
-      const comments = await adapter2.getRecentTaskComments?.(20);
-      if (comments && comments.length > 0) {
-        const byTask = /* @__PURE__ */ new Map();
-        for (const c of comments) {
-          const list = byTask.get(c.taskId) ?? [];
-          list.push(c);
-          byTask.set(c.taskId, list);
-        }
-        const lines = [];
-        for (const [taskId, taskComments] of byTask) {
-          const limited = taskComments.slice(0, 5);
-          for (const c of limited) {
-            const truncated = c.content.length > 200 ? c.content.slice(0, 200) + "..." : c.content;
-            const date = c.createdAt.split("T")[0];
-            lines.push(`- **${taskId}** \u2014 ${c.author} (${date}): "${truncated}"`);
-          }
-        }
-        taskCommentsText = lines.join("\n");
-      }
-    } catch {
-    }
-    let discoveryCanvasText;
-    try {
-      const canvas = await adapter2.readDiscoveryCanvas();
-      discoveryCanvasText = formatDiscoveryCanvas(canvas);
-    } catch {
-    }
-    let estimationCalibrationText;
+    const taskCommentsText = await assembleTaskComments(adapter2);
+    const discoveryCanvasText = await assembleDiscoveryCanvasText(adapter2);
+    let estimationCalibrationText;
     try {
       const calibrationRows = await adapter2.getEstimationCalibration?.();
       if (calibrationRows && calibrationRows.length > 0) {
@@ -10442,35 +10777,8 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
   ]);
   timings["total"] = totalTimer();
   console.error(`[plan-perf] assembleContext (full): ${JSON.stringify(timings)}ms`);
-  let discoveryCanvasTextFull;
-  try {
-    const canvas = await adapter2.readDiscoveryCanvas();
-    discoveryCanvasTextFull = formatDiscoveryCanvas(canvas);
-  } catch {
-  }
-  let taskCommentsTextFull;
-  try {
-    const comments = await adapter2.getRecentTaskComments?.(20);
-    if (comments && comments.length > 0) {
-      const byTask = /* @__PURE__ */ new Map();
-      for (const c of comments) {
-        const list = byTask.get(c.taskId) ?? [];
-        list.push(c);
-        byTask.set(c.taskId, list);
-      }
-      const lines = [];
-      for (const [taskId, taskComments] of byTask) {
-        const limited = taskComments.slice(0, 5);
-        for (const c of limited) {
-          const truncated = c.content.length > 200 ? c.content.slice(0, 200) + "..." : c.content;
-          const date = c.createdAt.split("T")[0];
-          lines.push(`- **${taskId}** \u2014 ${c.author} (${date}): "${truncated}"`);
-        }
-      }
-      taskCommentsTextFull = lines.join("\n");
-    }
-  } catch {
-  }
+  const discoveryCanvasTextFull = await assembleDiscoveryCanvasText(adapter2);
+  const taskCommentsTextFull = await assembleTaskComments(adapter2);
   let ctx = {
     mode,
     cycleNumber: health.totalCycles,
@@ -10565,7 +10873,7 @@ ${cleanContent}`;
       title: t.title,
       status: t.status || "Backlog",
       priority: t.priority || "P1 High",
-      complexity: t.complexity || "Medium",
+      complexity: t.complexity || "Small",
       module: t.module || "Core",
       epic: t.epic || "Platform",
       phase: t.phase || "Phase 1",
@@ -10671,7 +10979,7 @@ ${cleanContent}`;
         title: task.title,
         status: task.status || "Backlog",
         priority: task.priority || "P1 High",
-        complexity: task.complexity || "Medium",
+        complexity: task.complexity || "Small",
         module: task.module || "Core",
         epic: task.epic || "Platform",
         phase: task.phase || "Phase 1",
@@ -11048,6 +11356,106 @@ async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, str
   return Promise.race([workPromise, timeoutPromise]);
 }
 
+// src/lib/phase-realign.ts
+function extractPhaseNumber(phaseField) {
+  const match = phaseField.match(/Phase\s+(\d+)/i);
+  return match ? parseInt(match[1], 10) : null;
+}
+var STATUS_ORDER = {
+  "Not Started": 0,
+  "In Progress": 1,
+  "Done": 2,
+  "Deferred": 3
+  // Manual override — protected from auto-propagation
+};
+function isForwardTransition(currentStatus, newStatus) {
+  const currentOrder = STATUS_ORDER[currentStatus] ?? 99;
+  const newOrder = STATUS_ORDER[newStatus] ?? 99;
+  return newOrder >= currentOrder;
+}
+function derivePhaseStatus(tasks) {
+  if (tasks.length === 0) return null;
+  const terminal = /* @__PURE__ */ new Set(["Done", "Cancelled"]);
+  const active = /* @__PURE__ */ new Set(["In Progress", "In Review"]);
+  const allTerminal = tasks.every((t) => terminal.has(t.status));
+  if (allTerminal) return "Done";
+  const hasActive = tasks.some((t) => active.has(t.status));
+  if (hasActive) return "In Progress";
+  const hasDone = tasks.some((t) => terminal.has(t.status));
+  if (hasDone) return "In Progress";
+  return "Not Started";
+}
+function realignPhases(phases, tasks) {
+  if (phases.length === 0) {
+    return { changes: [], updatedPhases: phases };
+  }
+  const tasksByLabel = /* @__PURE__ */ new Map();
+  const tasksByOrder = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    if (task.phase) {
+      const existing = tasksByLabel.get(task.phase) ?? [];
+      existing.push(task);
+      tasksByLabel.set(task.phase, existing);
+    }
+    const num = extractPhaseNumber(task.phase);
+    if (num !== null) {
+      const existing = tasksByOrder.get(num) ?? [];
+      existing.push(task);
+      tasksByOrder.set(num, existing);
+    }
+  }
+  const changes = [];
+  const result = [];
+  for (const phase of phases) {
+    const phaseTasks = tasksByLabel.get(phase.label) ?? tasksByOrder.get(phase.order) ?? [];
+    const derivedStatus = derivePhaseStatus(phaseTasks);
+    if (derivedStatus !== null && derivedStatus !== phase.status && isForwardTransition(phase.status, derivedStatus)) {
+      changes.push({
+        phaseId: phase.id,
+        oldStatus: phase.status,
+        newStatus: derivedStatus
+      });
+      result.push({ ...phase, status: derivedStatus });
+    } else {
+      result.push(phase);
+    }
+  }
+  return { changes, updatedPhases: result };
+}
+function formatPhaseChanges(changes) {
+  if (changes.length === 0) return "";
+  const lines = ["**Phase Realignment:**"];
+  for (const c of changes) {
+    lines.push(`- ${c.phaseId}: ${c.oldStatus} \u2192 ${c.newStatus}`);
+  }
+  return lines.join("\n");
+}
+async function propagatePhaseStatus(adapter2) {
+  const [phases, tasks] = await Promise.all([
+    adapter2.readPhases(),
+    adapter2.queryBoard()
+  ]);
+  if (phases.length === 0) return [];
+  const horizons = await adapter2.readHorizons?.() ?? [];
+  const stages = await adapter2.readStages?.() ?? [];
+  let eligiblePhases = phases;
+  if (horizons.length > 1 && stages.length > 0) {
+    const h1 = horizons.reduce((min, h) => h.sortOrder < min.sortOrder ? h : min, horizons[0]);
+    const h1StageIds = new Set(stages.filter((s) => s.horizonId === h1.id).map((s) => s.id));
+    eligiblePhases = phases.filter((p) => !p.stageId || h1StageIds.has(p.stageId));
+  }
+  const { changes, updatedPhases } = realignPhases(eligiblePhases, tasks);
+  if (changes.length > 0) {
+    const updatedIds = new Set(updatedPhases.map((p) => p.id));
+    const mergedPhases = [
+      ...updatedPhases,
+      ...phases.filter((p) => !updatedIds.has(p.id))
+    ];
+    await adapter2.writePhases(mergedPhases);
+  }
+  return changes;
+}
+
 // src/tools/plan.ts
 var lastPrepareContextHashes;
 var lastPrepareUserMessage;
@@ -11187,6 +11595,10 @@ async function handlePlan(adapter2, config2, args) {
       };
     }
     {
+      try {
+        await propagatePhaseStatus(adapter2);
+      } catch {
+      }
       const result = await preparePlan(adapter2, config2, filters, focus, force);
       lastPrepareContextHashes = result.contextHashes;
       lastPrepareUserMessage = result.userMessage;
@@ -11240,81 +11652,10 @@ ${result.userMessage}
 // src/services/strategy.ts
 init_dist2();
 import { randomUUID as randomUUID8, createHash as createHash2 } from "crypto";
-
-// src/lib/phase-realign.ts
-function extractPhaseNumber(phaseField) {
-  const match = phaseField.match(/Phase\s+(\d+)/i);
-  return match ? parseInt(match[1], 10) : null;
-}
-function derivePhaseStatus(tasks) {
-  if (tasks.length === 0) return null;
-  const terminal = /* @__PURE__ */ new Set(["Done", "Cancelled"]);
-  const active = /* @__PURE__ */ new Set(["In Progress", "In Review"]);
-  const allTerminal = tasks.every((t) => terminal.has(t.status));
-  if (allTerminal) return "Done";
-  const hasActive = tasks.some((t) => active.has(t.status));
-  if (hasActive) return "In Progress";
-  const hasDone = tasks.some((t) => terminal.has(t.status));
-  if (hasDone) return "In Progress";
-  return "Not Started";
-}
-function realignPhases(phases, tasks) {
-  if (phases.length === 0) {
-    return { changes: [], updatedPhases: phases };
-  }
-  const tasksByLabel = /* @__PURE__ */ new Map();
-  const tasksByOrder = /* @__PURE__ */ new Map();
-  for (const task of tasks) {
-    if (task.phase) {
-      const existing = tasksByLabel.get(task.phase) ?? [];
-      existing.push(task);
-      tasksByLabel.set(task.phase, existing);
-    }
-    const num = extractPhaseNumber(task.phase);
-    if (num !== null) {
-      const existing = tasksByOrder.get(num) ?? [];
-      existing.push(task);
-      tasksByOrder.set(num, existing);
-    }
-  }
-  const changes = [];
-  const result = [];
-  for (const phase of phases) {
-    const phaseTasks = tasksByLabel.get(phase.label) ?? tasksByOrder.get(phase.order) ?? [];
-    const derivedStatus = derivePhaseStatus(phaseTasks);
-    if (derivedStatus !== null && derivedStatus !== phase.status) {
-      changes.push({
-        phaseId: phase.id,
-        oldStatus: phase.status,
-        newStatus: derivedStatus
-      });
-      result.push({ ...phase, status: derivedStatus });
-    } else {
-      result.push(phase);
-    }
-  }
-  return { changes, updatedPhases: result };
-}
-function formatPhaseChanges(changes) {
-  if (changes.length === 0) return "";
-  const lines = ["**Phase Realignment:**"];
-  for (const c of changes) {
-    lines.push(`- ${c.phaseId}: ${c.oldStatus} \u2192 ${c.newStatus}`);
-  }
-  return lines.join("\n");
-}
-async function propagatePhaseStatus(adapter2) {
-  const [phases, tasks] = await Promise.all([
-    adapter2.readPhases(),
-    adapter2.queryBoard()
-  ]);
-  if (phases.length === 0) return [];
-  const { changes, updatedPhases } = realignPhases(phases, tasks);
-  if (changes.length > 0) {
-    await adapter2.writePhases(updatedPhases);
-  }
-  return changes;
-}
+import { execFileSync as execFileSync2 } from "child_process";
+import { existsSync, readdirSync, statSync } from "fs";
+import { join as join2 } from "path";
+import { homedir } from "os";
 
 // src/lib/value-report.ts
 var MIN_SNAPSHOTS = 5;
@@ -11556,6 +11897,45 @@ function formatTaskCompact(t) {
   Reviewed: ${t.reviewed}${t.dependsOn ? ` | Depends on: ${t.dependsOn}` : ""}` + (notesSnippet ? `
   Notes: ${notesSnippet}` : "") + "\n";
 }
+function getAdHocCommits(projectRoot, sinceTag) {
+  try {
+    const logArgs = ["log", "--oneline", "--no-merges", "-100"];
+    if (sinceTag) {
+      logArgs.splice(1, 0, `${sinceTag}..HEAD`);
+    }
+    const output = execFileSync2("git", logArgs, {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      timeout: 5e3
+    }).trim();
+    if (!output) return void 0;
+    const allCommits = output.split("\n");
+    const taskPattern = /task-\d+/i;
+    const nonTaskCommits = allCommits.filter((line) => !taskPattern.test(line));
+    if (nonTaskCommits.length === 0) return void 0;
+    const capped = nonTaskCommits.slice(0, 20);
+    const groups = {};
+    const typePattern = /^[a-f0-9]+ (feat|fix|chore|refactor|docs|style|test|ci|perf|build|release)[\s(:]/i;
+    for (const line of capped) {
+      const match = line.match(typePattern);
+      const type = match ? match[1].toLowerCase() : "other";
+      (groups[type] ??= []).push(line);
+    }
+    const lines = [];
+    lines.push(`${nonTaskCommits.length} non-task commits found${nonTaskCommits.length > 20 ? " (showing 20 most recent)" : ""}:
+`);
+    for (const [type, commits] of Object.entries(groups).sort((a, b2) => b2[1].length - a[1].length)) {
+      lines.push(`**${type}** (${commits.length}):`);
+      for (const c of commits) {
+        lines.push(`- ${c}`);
+      }
+      lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+  } catch {
+    return void 0;
+  }
+}
 async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, projectRoot) {
   const lastReviewCycleNum = cycleNumber - cyclesSinceLastReview;
   const [
@@ -11571,7 +11951,9 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     currentNorthStar,
     canvas,
     decisionUsage,
-    recData
+    recData,
+    pendingRecs,
+    registeredDocs
   ] = await Promise.all([
     adapter2.readProductBrief(),
     adapter2.getActiveDecisions(),
@@ -11592,7 +11974,10 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     // Previously sequential — now parallel
     adapter2.readDiscoveryCanvas().catch(() => ({})),
     adapter2.getDecisionUsage(cycleNumber).catch(() => []),
-    adapter2.getRecommendationEffectiveness?.()?.catch(() => []) ?? Promise.resolve([])
+    adapter2.getRecommendationEffectiveness?.()?.catch(() => []) ?? Promise.resolve([]),
+    adapter2.getPendingRecommendations().catch(() => []),
+    // Doc registry — summaries for strategy review context
+    adapter2.searchDocs?.({ status: "active", limit: 10 })?.catch(() => []) ?? Promise.resolve([])
   ]);
   const tasks = [...activeTasks, ...recentDoneTasks];
   const recentLog = log;
@@ -11611,7 +11996,7 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
   const previousReviewsText = formatPreviousReviews(previousStrategyReviews);
   const cappedBrief = capProductBrief2(productBrief);
   const smartBoard = formatBoardForReviewSmart(tasks, lastReviewCycleNum);
-  const buildReportsText = buildPatternsText ? formatRecentReportsSummary(reports, 10) : formatBuildReports(reports);
+  const buildReportsText = formatRecentReportsSummary(reports, 10);
   logDataSourceSummary("strategy_review", [
     { label: "productBrief", hasData: warnIfEmpty("readProductBrief", productBrief) },
     { label: "activeDecisions", hasData: warnIfEmpty("getActiveDecisions", decisions) },
@@ -11626,7 +12011,7 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
   ]);
   let discoveryCanvasText;
   try {
-    const fullCanvasText = formatDiscoveryCanvasForReview(canvas);
+    const fullCanvasText = formatDiscoveryCanvas(canvas);
     if (fullCanvasText) {
       const canvasHash = createHash2("md5").update(fullCanvasText).digest("hex");
       const lastReview = previousStrategyReviews?.[0];
@@ -11642,7 +12027,7 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
   const briefImplicationsFromBuilds = reports.filter((r) => Array.isArray(r.briefImplications) && r.briefImplications.length > 0).flatMap((r) => r.briefImplications.map((bi) => ({ ...bi, taskName: r.taskName, cycle: r.cycle })));
   let briefImplicationsText;
   if (briefImplicationsFromBuilds.length > 0) {
-    briefImplicationsText = "**Build-Discovered Evidence:**\n" + briefImplicationsFromBuilds.map((bi) => `- [S${bi.cycle} ${bi.taskName}] [${bi.canvasSection}/${bi.type}] ${bi.detail}`).join("\n");
+    briefImplicationsText = "**Build-Discovered Evidence:**\n" + briefImplicationsFromBuilds.map((bi) => `- [C${bi.cycle} ${bi.taskName}] [${bi.canvasSection}/${bi.type}] ${bi.detail}`).join("\n");
   }
   let phasesText;
   try {
@@ -11667,12 +12052,90 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     }
   } catch {
   }
+  let pendingRecsText;
+  try {
+    if (pendingRecs.length > 0) {
+      const lines = pendingRecs.map((r) => {
+        const targetSuffix = r.target ? ` \u2192 ${r.target}` : "";
+        return `- [${r.status}] (Cycle ${r.createdCycle}, ${r.type}) ${r.content}${targetSuffix}`;
+      });
+      pendingRecsText = `${pendingRecs.length} pending recommendation(s) from prior reviews:
+${lines.join("\n")}`;
+    }
+  } catch {
+  }
+  let adHocCommitsText;
+  try {
+    const sinceTag = `v0.${lastReviewCycleNum}.0`;
+    adHocCommitsText = getAdHocCommits(projectRoot, sinceTag);
+  } catch {
+  }
+  let registeredDocsText;
+  try {
+    if (registeredDocs && registeredDocs.length > 0) {
+      const lines = registeredDocs.map(
+        (d) => `- **${d.title}** (${d.type}, ${d.status}) \u2014 ${d.summary}`
+      );
+      registeredDocsText = `${registeredDocs.length} registered doc(s):
+${lines.join("\n")}`;
+    }
+  } catch {
+  }
+  let recentPlansText;
+  try {
+    const plansDir = join2(homedir(), ".claude", "plans");
+    if (existsSync(plansDir)) {
+      const lastReviewDate = previousStrategyReviews?.[0]?.date ? new Date(previousStrategyReviews[0].date) : /* @__PURE__ */ new Date(0);
+      const planFiles = readdirSync(plansDir).filter((f) => f.endsWith(".md")).map((f) => {
+        const fullPath = join2(plansDir, f);
+        const stat2 = statSync(fullPath);
+        return { name: f, modified: stat2.mtime, size: stat2.size };
+      }).filter((f) => f.modified > lastReviewDate).sort((a, b2) => b2.modified.getTime() - a.modified.getTime()).slice(0, 15);
+      if (planFiles.length > 0) {
+        const lines = planFiles.map((f) => {
+          const kb = (f.size / 1024).toFixed(1);
+          return `- ${f.name} (${kb}KB, ${f.modified.toISOString().slice(0, 10)})`;
+        });
+        recentPlansText = `${planFiles.length} plan file(s) modified since last review:
+${lines.join("\n")}`;
+      }
+    }
+  } catch {
+  }
+  let unregisteredDocsText;
+  try {
+    const docsDir = join2(projectRoot, "docs");
+    if (existsSync(docsDir)) {
+      const registeredPaths = new Set(
+        (registeredDocs ?? []).map((d) => d.path).filter(Boolean)
+      );
+      const allDocFiles = [];
+      const scanDir = (dir, prefix) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory()) scanDir(join2(dir, entry.name), `${prefix}${entry.name}/`);
+          else if (entry.name.endsWith(".md")) allDocFiles.push(`${prefix}${entry.name}`);
+        }
+      };
+      scanDir(docsDir, "docs/");
+      const unregistered = allDocFiles.filter((f) => !registeredPaths.has(f));
+      if (unregistered.length > 0) {
+        unregisteredDocsText = `${unregistered.length} unregistered doc(s) in docs/:
+${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
+      }
+    }
+  } catch {
+  }
   logDataSourceSummary("strategy_review_audit", [
     { label: "discoveryCanvas", hasData: discoveryCanvasText !== void 0 },
     { label: "briefImplications", hasData: briefImplicationsText !== void 0 },
     { label: "phases", hasData: phasesText !== void 0 },
     { label: "decisionUsage", hasData: decisionUsageText !== void 0 },
-    { label: "recEffectiveness", hasData: recEffectivenessText !== void 0 }
+    { label: "recEffectiveness", hasData: recEffectivenessText !== void 0 },
+    { label: "pendingRecs", hasData: pendingRecsText !== void 0 },
+    { label: "adHocCommits", hasData: adHocCommitsText !== void 0 },
+    { label: "registeredDocs", hasData: registeredDocsText !== void 0 },
+    { label: "recentPlans", hasData: recentPlansText !== void 0 },
+    { label: "unregisteredDocs", hasData: unregisteredDocsText !== void 0 }
   ]);
   const context = {
     sessionNumber: cycleNumber,
@@ -11692,10 +12155,15 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     phases: phasesText,
     decisionUsage: decisionUsageText,
     northStar: currentNorthStar ?? void 0,
-    recommendationEffectiveness: recEffectivenessText
+    recommendationEffectiveness: recEffectivenessText,
+    adHocCommits: adHocCommitsText,
+    pendingRecommendations: pendingRecsText,
+    registeredDocs: registeredDocsText,
+    recentPlans: recentPlansText,
+    unregisteredDocs: unregisteredDocsText
   };
-  const BUDGET_SOFT2 = 8e4;
-  const BUDGET_HARD2 = 1e5;
+  const BUDGET_SOFT2 = 5e4;
+  const BUDGET_HARD2 = 6e4;
   const compressionSteps = [];
   function measureContext(ctx) {
     return Object.values(ctx).filter((v) => typeof v === "string").reduce((sum, s) => sum + s.length, 0);
@@ -11724,13 +12192,31 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     }
   }
   if (contextSize > BUDGET_SOFT2 && context.allBuildReports) {
-    const summary = formatRecentReportsSummary(reports, 10);
+    const summary = formatRecentReportsSummary(reports, 5);
     if (summary.length < context.allBuildReports.length) {
       context.allBuildReports = summary;
       contextSize = measureContext(context);
-      compressionSteps.push("Step 3: build reports summarized");
+      compressionSteps.push("Step 3: build reports capped to 5");
+    }
+  }
+  if (contextSize > BUDGET_SOFT2 && context.sessionLog) {
+    const logLines = context.sessionLog.split("\n---\n");
+    if (logLines.length > 5) {
+      context.sessionLog = logLines.slice(0, 5).join("\n---\n") + `
+
+*(${logLines.length - 5} older cycle log entries omitted for context budget)*`;
+      contextSize = measureContext(context);
+      compressionSteps.push(`Step 4: cycle log capped to 5 (was ${logLines.length})`);
     }
   }
+  if (contextSize > BUDGET_SOFT2 && context.board) {
+    context.board = context.board.replace(
+      /  Notes: .{100,}/g,
+      (match) => match.slice(0, match.indexOf("Notes: ") + 107) + "..."
+    );
+    contextSize = measureContext(context);
+    compressionSteps.push("Step 5: board task notes truncated to 100 chars");
+  }
   if (contextSize > BUDGET_HARD2) {
     const entries = Object.entries(context).filter((e) => typeof e[1] === "string").sort((a, b2) => b2[1].length - a[1].length);
     if (entries.length > 0) {
@@ -11739,7 +12225,7 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
       const newLength = Math.max(value.length - excess, 1e3);
       context[key] = value.slice(0, newLength) + "\n\n[truncated \u2014 context budget exceeded]";
       contextSize = measureContext(context);
-      compressionSteps.push(`Step 4: truncated ${key} (was ${value.length} chars)`);
+      compressionSteps.push(`Step 6: truncated ${key} (was ${value.length} chars)`);
     }
   }
   const estimatedTokens = Math.ceil(contextSize / 4);
@@ -11771,7 +12257,7 @@ ${cleanContent}`;
       const sd = data;
       try {
         const currentCanvas = await adapter2.readDiscoveryCanvas();
-        const canvasText = formatDiscoveryCanvasForReview(currentCanvas);
+        const canvasText = formatDiscoveryCanvas(currentCanvas);
         if (canvasText) {
           return { ...sd, canvasHash: createHash2("md5").update(canvasText).digest("hex") };
         }
@@ -11904,8 +12390,16 @@ async function processReviewOutput(adapter2, rawOutput, cycleNumber) {
       phaseChanges = await writeBack2(adapter2, cycleNumber, data, displayText);
     } catch (err) {
       writeBackFailed = err instanceof Error ? err.message : String(err);
+      try {
+        await adapter2.savePendingReviewResponse?.(cycleNumber, rawOutput);
+      } catch {
+      }
     }
     if (!writeBackFailed) {
+      try {
+        await adapter2.clearPendingReviewResponse?.();
+      } catch {
+      }
       const webhookUrl = process.env.PAPI_SLACK_WEBHOOK_URL;
       slackWarning = await sendSlackWebhook(webhookUrl, buildSlackSummary(data));
     }
@@ -11953,6 +12447,28 @@ async function prepareStrategyReview(adapter2, force, projectRoot, adapterType)
       isPg ? "Could not read cycle health from the database. Check your DATABASE_URL and verify the project exists." : "Could not read cycle health from PLANNING_LOG.md. Run setup first to initialise your PAPI project."
     );
   }
+  try {
+    const pending = await adapter2.getPendingReviewResponse?.();
+    if (pending) {
+      return {
+        cycleNumber: pending.cycleNumber || cycleNumber,
+        systemPrompt: "",
+        userMessage: `\u26A0\uFE0F **Pending Strategy Review Found**
+
+A previous strategy review (Cycle ${pending.cycleNumber || cycleNumber}) failed to write back. The raw LLM response has been preserved.
+
+To retry, call \`strategy_review\` with:
+- \`mode\`: "apply"
+- \`llm_response\`: (the response below)
+- \`cycle_number\`: ${pending.cycleNumber || cycleNumber}
+
+---
+
+${pending.rawResponse}`
+      };
+    }
+  } catch {
+  }
   let context;
   try {
     context = await assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, projectRoot);
@@ -11982,7 +12498,8 @@ async function prepareStrategyReview(adapter2, force, projectRoot, adapterType)
   return {
     cycleNumber,
     systemPrompt,
-    userMessage
+    userMessage,
+    contextSizeChars: userMessage.length
   };
 }
 async function applyStrategyReviewOutput(adapter2, rawLlmOutput, cycleNumber) {
@@ -12066,42 +12583,6 @@ function formatRecentReportsSummary(reports, count) {
     return `- S${r.cycle} ${r.taskName}: ${effort}${surprises}`;
   }).join("\n");
 }
-function formatDiscoveryCanvasForReview(canvas) {
-  const sections = [];
-  if (canvas.landscapeReferences && canvas.landscapeReferences.length > 0) {
-    sections.push("**Landscape & References:**");
-    for (const ref of canvas.landscapeReferences) {
-      const url = ref.url ? ` (${ref.url})` : "";
-      const notes = ref.notes ? ` \u2014 ${ref.notes}` : "";
-      sections.push(`- ${ref.name}${url}${notes}`);
-    }
-  }
-  if (canvas.userJourneys && canvas.userJourneys.length > 0) {
-    sections.push("**User Journeys:**");
-    for (const j of canvas.userJourneys) {
-      const priority = j.priority ? ` [${j.priority}]` : "";
-      sections.push(`- **${j.persona}:** ${j.journey}${priority}`);
-    }
-  }
-  if (canvas.mvpBoundary) {
-    sections.push("**MVP Boundary:**", canvas.mvpBoundary);
-  }
-  if (canvas.assumptionsOpenQuestions && canvas.assumptionsOpenQuestions.length > 0) {
-    sections.push("**Assumptions & Open Questions:**");
-    for (const a of canvas.assumptionsOpenQuestions) {
-      const evidence = a.evidence ? ` Evidence: ${a.evidence}` : "";
-      sections.push(`- [${a.status}] ${a.text}${evidence}`);
-    }
-  }
-  if (canvas.successSignals && canvas.successSignals.length > 0) {
-    sections.push("**Success Signals:**");
-    for (const s of canvas.successSignals) {
-      const metric = s.metric ? ` (${s.metric}` + (s.target ? `, target: ${s.target})` : ")") : "";
-      sections.push(`- ${s.signal}${metric}`);
-    }
-  }
-  return sections.length > 0 ? sections.join("\n") : void 0;
-}
 function formatPhasesForReview(phases, currentCycle) {
   if (phases.length === 0) return void 0;
   const lines = [];
@@ -12147,9 +12628,6 @@ async function formatHierarchyForReview(adapter2, currentCycle, prefetchedTasks)
       existing.push(s);
       stagesByHorizon.set(s.horizonId, existing);
     }
-    const phasesByStage = /* @__PURE__ */ new Map();
-    for (const p of phases) {
-    }
     for (const h of horizons) {
       lines.push(`### ${h.label} \u2014 ${h.status}`);
       if (h.description) lines.push(`> ${h.description}`);
@@ -12221,6 +12699,11 @@ function buildStrategyChangeUserMessage(cycleNumber, text, productBrief, activeD
   if (buildReports && buildReports.length > 0) {
     parts.push("### Recent Velocity (last 3 cycles)", "", formatVelocitySummary(buildReports, 3), "");
     parts.push("### Recent Build Reports", "", formatRecentReportsSummary(buildReports, 5), "");
+    const briefImplicationsFromBuilds = buildReports.filter((r) => Array.isArray(r.briefImplications) && r.briefImplications.length > 0).flatMap((r) => r.briefImplications.map((bi) => ({ ...bi, taskName: r.taskName, cycle: r.cycle })));
+    if (briefImplicationsFromBuilds.length > 0) {
+      const briefImplicationsText = "**Build-Discovered Evidence:**\n" + briefImplicationsFromBuilds.map((bi) => `- [C${bi.cycle} ${bi.taskName}] [${bi.canvasSection}/${bi.type}] ${bi.detail}`).join("\n");
+      parts.push("### Brief Implications (from builds)", "", briefImplicationsText, "");
+    }
   }
   if (previousReviews) {
     parts.push("### Previous Strategy Reviews", "", previousReviews, "");
@@ -12306,12 +12789,14 @@ async function prepareStrategyChange(adapter2, text) {
     tasks = boardTasks;
     buildReports = reports;
     previousReviewsText = formatPreviousReviews(previousReviews);
+    const hasBriefImplications = reports.some((r) => Array.isArray(r.briefImplications) && r.briefImplications.length > 0);
     logDataSourceSummary("strategy_change", [
       { label: "productBrief", hasData: warnIfEmpty("readProductBrief", brief) },
       { label: "activeDecisions", hasData: warnIfEmpty("getActiveDecisions", decisions) },
       { label: "phases", hasData: warnIfEmpty("readPhases", readPhases) },
       { label: "boardTasks", hasData: warnIfEmpty("queryBoard", boardTasks) },
       { label: "buildReports", hasData: warnIfEmpty("getRecentBuildReports", reports) },
+      { label: "briefImplications", hasData: hasBriefImplications },
       { label: "previousReviews", hasData: previousReviewsText !== void 0 }
     ]);
   } catch (err) {
@@ -12513,11 +12998,14 @@ ${result.slackWarning}` : "";
       }
       lastReviewUserMessage = result.userMessage;
       lastReviewContextBytes = Buffer.byteLength(result.userMessage, "utf-8");
+      const sizeNote = result.contextSizeChars ? `
+**Context size:** ${result.contextSizeChars.toLocaleString()} chars (~${Math.ceil(result.contextSizeChars / 4).toLocaleString()} tokens)
+` : "";
       return textResponse(
         `## PAPI Strategy Review \u2014 Prepare Phase (Cycle ${result.cycleNumber})
 
 Follow the system prompt and context below to generate a strategy review.
-
+` + sizeNote + `
 When done, call \`strategy_review\` again with:
 - \`mode\`: "apply"
 - \`llm_response\`: your complete output
@@ -12740,7 +13228,7 @@ var boardViewTool = {
 };
 var boardDeprioritiseTool = {
   name: "board_deprioritise",
-  description: `Remove a task from the current cycle. Three actions: "backlog" (not now, maybe later \u2014 preserves handoff), "defer" (valid but premature \u2014 hidden from planner), "cancel" (don't want this \u2014 permanently closed with reason). When a user rejects a task, ALWAYS ask which action they want. Does not call the Anthropic API.`,
+  description: `Remove a task from the current cycle. Four actions: "backlog" (not now, maybe later \u2014 preserves handoff), "defer" (valid but premature \u2014 hidden from planner), "block" (waiting on external dependency \u2014 visible on board but skipped by planner), "cancel" (don't want this \u2014 permanently closed with reason). When a user rejects a task, ALWAYS ask which action they want. Does not call the Anthropic API.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -12750,8 +13238,8 @@ var boardDeprioritiseTool = {
       },
       action: {
         type: "string",
-        enum: ["backlog", "defer", "cancel"],
-        description: `"backlog" = not now, maybe later (preserves handoff). "defer" = valid but premature (hidden from planner). "cancel" = don't want this at all (permanently closed). If omitted, defaults to "backlog" for backwards compatibility.`
+        enum: ["backlog", "defer", "block", "cancel"],
+        description: `"backlog" = not now, maybe later (preserves handoff). "defer" = valid but premature (hidden from planner). "block" = waiting on external dependency (visible but skipped by planner \u2014 reason required). "cancel" = don't want this at all (permanently closed). If omitted, defaults to "backlog" for backwards compatibility.`
       },
       reason: {
         type: "string",
@@ -12791,6 +13279,60 @@ var boardArchiveTool = {
     required: []
   }
 };
+var boardEditTool = {
+  name: "board_edit",
+  description: "Edit fields on an existing task. Supports title, priority, complexity, module, epic, phase, notes, status, and maturity. Pass task_id plus any fields to update. Does not call the Anthropic API.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      task_id: {
+        type: "string",
+        description: 'The task ID to edit (e.g. "task-42").'
+      },
+      title: {
+        type: "string",
+        description: "New task title."
+      },
+      priority: {
+        type: "string",
+        enum: ["P0 Critical", "P1 High", "P2 Medium", "P3 Low"],
+        description: "New priority level."
+      },
+      complexity: {
+        type: "string",
+        enum: ["XS", "Small", "Medium", "Large", "XL"],
+        description: "New complexity/effort estimate."
+      },
+      module: {
+        type: "string",
+        description: "New module assignment."
+      },
+      epic: {
+        type: "string",
+        description: "New epic assignment."
+      },
+      phase: {
+        type: "string",
+        description: "New phase assignment."
+      },
+      notes: {
+        type: "string",
+        description: "New notes (replaces existing notes)."
+      },
+      status: {
+        type: "string",
+        enum: ["Backlog", "In Cycle", "Ready", "In Progress", "In Review", "Done", "Blocked", "Cancelled", "Deferred"],
+        description: "New status. Must be a valid transition from the current status."
+      },
+      maturity: {
+        type: "string",
+        enum: ["raw", "investigated", "ready"],
+        description: "New maturity level."
+      }
+    },
+    required: ["task_id"]
+  }
+};
 function pad(value, width) {
   return value.length >= width ? value : value + " ".repeat(width - value.length);
 }
@@ -12859,7 +13401,17 @@ async function handleBoardView(adapter2, args) {
     limit: args.limit,
     offset: args.offset
   });
-  return textResponse(formatBoard(result));
+  let output = formatBoard(result);
+  try {
+    const comments = await adapter2.getRecentTaskComments?.(30);
+    if (comments && comments.length > 0) {
+      const taskIds = new Set(result.tasks.map((t) => t.id));
+      const section = formatTaskComments(comments, taskIds, "**Task Comments:**");
+      if (section) output += "\n" + section;
+    }
+  } catch {
+  }
+  return textResponse(output);
 }
 async function handleBoardDeprioritise(adapter2, args) {
   const taskId = args.task_id;
@@ -12872,6 +13424,29 @@ async function handleBoardDeprioritise(adapter2, args) {
   const reason = args.reason;
   const newPriority = args.priority;
   const newPhase = args.phase;
+  if (action === "block") {
+    if (!reason) {
+      return errorResponse("reason is required when blocking a task \u2014 explain what external dependency or gate is blocking it.");
+    }
+    try {
+      const task = await adapter2.getTask(taskId);
+      if (!task) return errorResponse(`Task ${taskId} not found.`);
+      const existingNotes = task.notes ? `${task.notes}
+
+` : "";
+      await adapter2.updateTask(taskId, {
+        status: "Blocked",
+        notes: `${existingNotes}BLOCKED: ${reason}`
+      });
+      return textResponse(`Blocked **${taskId}** (${task.title}).
+
+Reason: ${reason}
+
+Task remains visible on the board but will be skipped by the planner and build_list.`);
+    } catch (err) {
+      return errorResponse(err instanceof Error ? err.message : String(err));
+    }
+  }
   if (action === "cancel") {
     if (!reason) {
       return errorResponse("reason is required when cancelling a task.");
@@ -12930,11 +13505,49 @@ async function handleBoardArchive(adapter2, args) {
   ];
   return textResponse(lines.join("\n"));
 }
+var EDITABLE_FIELDS = ["title", "priority", "complexity", "module", "epic", "phase", "notes", "status", "maturity"];
+async function handleBoardEdit(adapter2, args) {
+  const taskId = args.task_id;
+  if (!taskId) {
+    return errorResponse("task_id is required.");
+  }
+  const updates = {};
+  const changes = [];
+  for (const field of EDITABLE_FIELDS) {
+    if (args[field] !== void 0 && args[field] !== null) {
+      updates[field] = args[field];
+      changes.push(field);
+    }
+  }
+  if (changes.length === 0) {
+    return errorResponse("No fields to update. Pass at least one field (title, priority, complexity, module, epic, phase, notes, status, maturity).");
+  }
+  try {
+    const task = await adapter2.getTask(taskId);
+    if (!task) {
+      return errorResponse(`Task ${taskId} not found.`);
+    }
+    if (updates.status === "Backlog" && task.cycle != null) {
+      updates.cycle = void 0;
+      updates.cycle = null;
+      if (!changes.includes("cycle")) changes.push("cycle \u2192 cleared");
+    }
+    await adapter2.updateTask(taskId, updates);
+    const lines = [
+      `Updated **${taskId}** (${updates.title ?? task.title})`,
+      "",
+      `**Changes:** ${changes.map((f) => `${f} \u2192 ${String(updates[f])}`).join(", ")}`
+    ];
+    return textResponse(lines.join("\n"));
+  } catch (err) {
+    return errorResponse(err instanceof Error ? err.message : String(err));
+  }
+}
 
 // src/services/setup.ts
 init_dist2();
 import { mkdir, writeFile as writeFile2, readFile as readFile3, readdir, access as access2, stat } from "fs/promises";
-import { join as join2, basename, extname } from "path";
+import { join as join3, basename, extname } from "path";
 
 // src/templates.ts
 var PLANNING_LOG_TEMPLATE = `# PAPI Planning Log
@@ -13088,15 +13701,15 @@ PAPI tools follow structured flows. The agent manages the cycle workflow automat
 - **Run tools automatically** \u2014 don't ask the user to invoke MCP tools manually
 - Before implementing: silently run \`build_execute <task_id>\` (start phase)
 - After implementing: run \`build_execute <task_id>\` (complete phase) with report fields
-- After build_execute completes: run \`/papi-audit\` to check for bugs, convention violations, and doc drift
-- After \`/papi-audit\` with findings: *MUST* automatically run \`review_submit\` with verdict \`request-changes\` and a concise summary of the audit findings as the changes requested \u2014 the builder fixes these before the task goes to human review
-- After \`/papi-audit\` clean: present for human review \u2014 "Ready for your review \u2014 approve or request changes?"
+- After build_execute completes: audit the branch changes for bugs, convention violations, and doc drift (see Post-Build Audit below)
+- After audit with findings: *MUST* automatically run \`review_submit\` with verdict \`request-changes\` and a concise summary of the audit findings as the changes requested \u2014 the builder fixes these before the task goes to human review
+- After audit clean: present for human review \u2014 "Ready for your review \u2014 approve or request changes?"
 - User approves/requests changes \u2192 run \`review_submit\` behind the scenes
 
 ### The Cycle (main flow)
 
 \`\`\`
-plan \u2192 build_list \u2192 build_execute \u2192 /papi-audit \u2192 review_list \u2192 review_submit \u2192 build_list
+plan \u2192 build_list \u2192 build_execute \u2192 audit \u2192 review_list \u2192 review_submit \u2192 build_list
 \`\`\`
 
 1. **plan** \u2014 Run at the start of each cycle to generate the cycle plan and populate the board.
@@ -13106,8 +13719,8 @@ plan \u2192 build_list \u2192 build_execute \u2192 /papi-audit \u2192 review_lis
 3. **build_execute** (start) \u2014 Creates a feature branch and marks the task In Progress. Returns the build handoff.
    Next: Implement the task, then \`build_execute <task_id>\` again with report fields to complete.
 4. **build_execute** (complete) \u2014 Submits the build report, commits, and marks the task In Review.
-   Next: Run \`/papi-audit\` automatically.
-5. **/papi-audit** \u2014 Audits the branch for bugs, convention violations, and doc drift.
+   Next: Run the post-build audit automatically.
+5. **Post-build audit** \u2014 Review branch changes for bugs, convention violations, and doc drift (see Post-Build Audit section below).
    Next: If findings exist, run \`review_submit\` with \`request-changes\` and the audit findings. If clean, proceed to \`review_list\`.
 6. **review_list** \u2014 Shows tasks pending human review (handoff-review or build-acceptance).
    Next: \`review_submit\` to approve, accept, or request changes.
@@ -13156,15 +13769,99 @@ setup \u2192 plan
 | \`plan\` | \`build_list\` |
 | \`build_list\` | \`build_execute <task_id>\` |
 | \`build_execute\` (start) | Implement, then \`build_execute\` (complete) |
-| \`build_execute\` (complete) | \`/papi-audit\` (automatic) |
-| \`/papi-audit\` (findings) | \`review_submit\` with \`request-changes\` |
-| \`/papi-audit\` (clean) | \`review_list\` |
+| \`build_execute\` (complete) | Post-build audit (automatic) |
+| Audit (findings) | \`review_submit\` with \`request-changes\` |
+| Audit (clean) | \`review_list\` |
 | \`review_list\` | \`review_submit\` |
 | \`review_submit\` (approve/accept) | \`build_list\` |
 | \`review_submit\` (request-changes) | \`build_execute\` (redo) or \`build_list\` |
 | \`strategy_review\` | \`strategy_change\` (if needed) |
 | \`idea\` | Next \`plan\` picks it up |
 
+## Post-Build Audit
+
+After every \`build_execute\` (complete), audit the branch before presenting for human review. This catches bugs and convention violations early.
+
+1. **Identify changed files:** Run \`git diff origin/main --name-only\` to find modified files. If no changes, report "No changes to audit" and skip.
+2. **Review each changed file** for:
+   - Logic errors, off-by-one mistakes, incorrect conditions
+   - Unhandled edge cases (null, undefined, empty inputs)
+   - Convention violations defined in this CLAUDE.md
+   - Incorrect type narrowing or unsafe casts
+3. **Documentation check:** If any \`docs/\` files describe behaviour that the change modified, flag as "Doc drift".
+4. **Report:** For each issue: file path, severity (Bug/Convention/Doc drift), what's wrong, how to fix.
+5. **If findings exist:** Run \`review_submit\` with \`request-changes\` and the findings. Fix before human review.
+6. **If clean:** Present for human review \u2014 "Ready for your review \u2014 approve or request changes?"
+
+## When to Start a New Conversation
+
+Start a fresh window when:
+- **After a release** \u2014 cycle is done, context is heavy. New window orients in seconds via \`orient\`.
+- **After 3+ tasks built** \u2014 accumulated file reads, diffs, and discussions bloat context. Quality degrades.
+- **Switching modes** \u2014 going from building to planning, or from strategy review to building. Each mode benefits from clean context.
+- **After context compression fires** \u2014 if you notice earlier messages are missing, the window is getting stale. Open fresh.
+
+Stay in the same window when:
+- Building sequential tasks in a batch (especially XS/S tasks)
+- Mid-task and not yet complete
+- Having a strategic discussion that informs the next action
+
+**Rule of thumb:** If you've been in the same window for 30+ minutes or 3+ tasks, it's time for a fresh one.
+
+## Housekeeping \u2014 Fix Orphaned Tasks
+
+On session start, silently check for and fix:
+1. **Orphaned branches:** \`git branch | grep feat/task\` \u2014 cross-reference with board status. Fix by merging or flagging.
+2. **In Review tasks with no PR:** If branch is already merged to main, the review_submit step was missed.
+3. **Stale In Progress:** Branch has no recent commits \u2014 flag it.
+4. **Config mismatches:** \`.mcp.json\` has DATABASE_URL but PAPI_ADAPTER is still \`md\` \u2014 flag it.
+
+**Do this automatically and silently.** Report what you found and fixed.
+
+## Plumbing Is Autonomous
+
+Board status updates, branch cleanup, orphaned task fixes, commit/PR/merge for housekeeping \u2014 these are mechanical plumbing. **Do them end-to-end without stopping to ask.** Report after the fact.
+
+## Context Compression Recovery
+
+When the system compresses prior messages, immediately:
+1. **Run \`orient\`** \u2014 single call for cycle state
+2. Check your todo list for in-progress work
+3. Run housekeeping checks
+4. **NEVER re-build a task that is already In Review or Done.**
+5. Continue where you left off \u2014 don't restart or re-plan
+
+## Branching & PR Convention
+
+- **XS/S tasks in the same cycle and module:** Group on shared branch. One PR, one merge.
+- **M/L tasks or different modules:** Own branch per task. Isolated PRs.
+- **Commit per task within grouped branches** \u2014 traceable git history.
+
+## Quick Work vs PAPI Work
+
+PAPI is for planned work. Quick fixes \u2014 just do them. No need for plan or build_execute.
+
+**After completing quick/ad-hoc work** (bug fixes, config changes, small improvements done outside the cycle), call \`ad_hoc\` to record it. This creates a Done task + build report so the work appears in cycle history and metrics. Don't skip this \u2014 unrecorded work is invisible work.
+
+## Data Integrity
+
+- **Use MCP tools for all project data operations.** DB is the source of truth when using the pg adapter.
+- Do NOT read \`.papi/\` files for context \u2014 use MCP tools.
+- \`.papi/\` files may be stale when using pg adapter. This is expected.
+
+## Code Before Claims \u2014 No Assumptions
+
+**Before making any claim about how the codebase works, read the relevant file first.**
+
+This includes:
+- How a feature is implemented ("it works like X") \u2192 read the source
+- Whether something exists ("there's no baseline migration") \u2192 check the directory
+- Whether a flow is broken or working \u2192 trace it in code
+- What a user would experience \u2192 check the actual page/component
+
+Do NOT rely on memory, prior conversation, or inference. Read first, then answer.
+If the answer requires checking 2-3 files, check them all before responding.
+
 ## Process Rules
 
 These rules come from 80+ cycles of dogfooding. They prevent the most common sources of wasted time and rework.
@@ -13177,6 +13874,11 @@ These rules come from 80+ cycles of dogfooding. They prevent the most common sou
 - **Test after every build.** Run the project's test suite after implementing. Suggest follow-up tasks from learnings when meaningful.
 - **Build patiently.** Validate each phase against the last. Don't rush through implementation \u2014 test through the UI, not just the API.
 
+### Security
+- **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.
+
 ### 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.
 - **Split large ideas.** If an idea has 3+ concerns, submit it as 2-3 separate ideas so the planner creates properly scoped tasks \u2014 not kitchen-sink handoffs.
@@ -13185,12 +13887,73 @@ These rules come from 80+ cycles of dogfooding. They prevent the most common sou
 ### Communication
 - **Show task names, not just IDs.** When summarising board state or reconciliation, include task names \u2014 e.g. "task-42: Add supplier form" not just "task-42".
 - **Surface the next command.** After each step, tell the user what comes next. Commands should be surfaced, not memorised.
+
+### Stage Readiness
+- **Access-widening stages require auth/security phases.** Before declaring a stage complete, check if it widens who can access the product (e.g. Alpha Distribution, Alpha Cohort). If so, auth hardening and security review must be completed first \u2014 not discovered after the fact.
+- **Pattern:** Audit access surface \u2192 fix vulnerabilities \u2192 then widen access. Never ship access-widening without a security phase.
+`;
+var CLAUDE_MD_ENRICHMENT_SENTINEL_T1 = "<!-- PAPI_ENRICHMENT_TIER_1 -->";
+var CLAUDE_MD_ENRICHMENT_SENTINEL_T2 = "<!-- PAPI_ENRICHMENT_TIER_2 -->";
+var CLAUDE_MD_TIER_1 = `
+${CLAUDE_MD_ENRICHMENT_SENTINEL_T1}
+
+## Batch Building (unlocked at cycle 6)
+
+For cycles with multiple XS/S tasks, batch build them without stopping between each:
+- Build all XS/S tasks first, then M/L tasks
+- Group tasks touching the same module onto a shared branch where possible
+- One commit per task for traceable history, even on shared branches
+- After all tasks built, batch review them together
+
+## Strategy Reviews
+
+Every 5 cycles, PAPI offers a strategy review \u2014 a deep analysis of velocity, estimation accuracy, active decisions, and project direction.
+
+- **Don't skip them.** They're where compounding value comes from.
+- Strategy reviews run in their own session \u2014 don't mix with building.
+- Reviews produce recommendations that feed into the next plan.
+- If the review recommends AD changes, use \`strategy_change\` to apply them.
+
+## Active Decision Lifecycle
+
+Active Decisions (ADs) track architectural and product choices with confidence levels (LOW \u2192 MEDIUM \u2192 HIGH).
+
+- Check ADs before making architectural choices \u2014 run \`health\` for the AD summary.
+- ADs are for product/architecture choices only, not process preferences.
+- When new evidence appears, update AD confidence via \`strategy_change\`.
+- Supersede rather than overwrite \u2014 old decisions stay as history.
+`;
+var CLAUDE_MD_TIER_2 = `
+${CLAUDE_MD_ENRICHMENT_SENTINEL_T2}
+
+## Idea Pipeline (unlocked at cycle 21)
+
+The \`idea\` tool is your backlog intake \u2014 not just for features, but bugs, research, and big ideas.
+
+- When you discover something during a build, submit it via \`idea\` rather than stopping to fix it.
+- Include a \`Reference:\` line pointing to relevant docs so the planner has context.
+- Split large ideas into 2-3 focused submissions for better planner scoping.
+- The backlog is the steering wheel \u2014 priority + notes shape what gets planned next.
+
+## Doc Registry
+
+Docs are first-class entities. When research or planning produces a stable document:
+- Register it with \`doc_register\` after it's finalised.
+- Doc summaries travel with tool context \u2014 the planner and strategy review can find relevant docs.
+- Keep docs current \u2014 update the review header after any change.
+
+## Advanced Patterns
+
+- **Cross-project awareness:** If running multiple PAPI projects, learnings transfer across them via shared patterns and the doc registry.
+- **Dogfood friction:** When something feels painful in the workflow, note it \u2014 the \`idea\` tool turns friction into improvements.
+- **Deferred tasks are intentional:** Tasks moved to Deferred aren't forgotten \u2014 they're parked for the right time.
+- **Carry-forward items:** Each plan notes carry-forward from the previous cycle. Check them before planning.
 `;
 var PAPI_AUDIT_COMMAND_TEMPLATE = `Audit the latest changes in this branch for bugs and compliance with the project's conventions defined in CLAUDE.md.
 
 ## Steps
 
-1. **Identify changed files**: Run \`git diff develop --name-only\` to find all files modified on this branch.
+1. **Identify changed files**: Run \`git diff main --name-only\` to find all files modified on this branch.
 
 2. **Read each changed file** and review it for:
 
@@ -13307,22 +14070,22 @@ async function scaffoldPapiDir(adapter2, config2, input) {
       await mkdir(config2.papiDir, { recursive: true });
       for (const [filename, template] of Object.entries(FILE_TEMPLATES)) {
         const content = substitute(template, vars);
-        await writeFile2(join2(config2.papiDir, filename), content, "utf-8");
+        await writeFile2(join3(config2.papiDir, filename), content, "utf-8");
       }
     }
   }
-  const commandsDir = join2(config2.projectRoot, ".claude", "commands");
-  const docsDir = join2(config2.projectRoot, "docs");
+  const commandsDir = join3(config2.projectRoot, ".claude", "commands");
+  const docsDir = join3(config2.projectRoot, "docs");
   await mkdir(commandsDir, { recursive: true });
   await mkdir(docsDir, { recursive: true });
-  const claudeMdPath = join2(config2.projectRoot, "CLAUDE.md");
+  const claudeMdPath = join3(config2.projectRoot, "CLAUDE.md");
   let claudeMdExists = false;
   try {
     await access2(claudeMdPath);
     claudeMdExists = true;
   } catch {
   }
-  const docsIndexPath = join2(docsDir, "INDEX.md");
+  const docsIndexPath = join3(docsDir, "INDEX.md");
   let docsIndexExists = false;
   try {
     await access2(docsIndexPath);
@@ -13330,9 +14093,9 @@ async function scaffoldPapiDir(adapter2, config2, input) {
   } catch {
   }
   const scaffoldFiles = {
-    [join2(commandsDir, "papi-audit.md")]: PAPI_AUDIT_COMMAND_TEMPLATE,
-    [join2(commandsDir, "test.md")]: TEST_COMMAND_TEMPLATE,
-    [join2(docsDir, "README.md")]: substitute(DOCS_README_TEMPLATE, vars)
+    [join3(commandsDir, "papi-audit.md")]: PAPI_AUDIT_COMMAND_TEMPLATE,
+    [join3(commandsDir, "test.md")]: TEST_COMMAND_TEMPLATE,
+    [join3(docsDir, "README.md")]: substitute(DOCS_README_TEMPLATE, vars)
   };
   if (!docsIndexExists) {
     scaffoldFiles[docsIndexPath] = substitute(DOCS_INDEX_TEMPLATE, vars);
@@ -13367,7 +14130,7 @@ async function scaffoldPapiDir(adapter2, config2, input) {
 }
 var PAPI_PERMISSION = "mcp__papi__*";
 async function ensurePapiPermission(projectRoot) {
-  const settingsPath = join2(projectRoot, ".claude", "settings.json");
+  const settingsPath = join3(projectRoot, ".claude", "settings.json");
   try {
     let settings = {};
     try {
@@ -13386,14 +14149,14 @@ async function ensurePapiPermission(projectRoot) {
     if (!allow.includes(PAPI_PERMISSION)) {
       allow.push(PAPI_PERMISSION);
     }
-    await mkdir(join2(projectRoot, ".claude"), { recursive: true });
+    await mkdir(join3(projectRoot, ".claude"), { recursive: true });
     await writeFile2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
   } catch {
   }
 }
 async function applySetupOutputs(adapter2, config2, input, briefText, adSeedText, conventionsText) {
   if (config2.adapterType !== "pg") {
-    await writeFile2(join2(config2.papiDir, "PRODUCT_BRIEF.md"), briefText, "utf-8");
+    await writeFile2(join3(config2.papiDir, "PRODUCT_BRIEF.md"), briefText, "utf-8");
   }
   await adapter2.updateProductBrief(briefText);
   const briefPhases = parsePhases(briefText);
@@ -13437,7 +14200,7 @@ async function applySetupOutputs(adapter2, config2, input, briefText, adSeedText
   }
   if (conventionsText?.trim()) {
     try {
-      const claudeMdPath = join2(config2.projectRoot, "CLAUDE.md");
+      const claudeMdPath = join3(config2.projectRoot, "CLAUDE.md");
       const existing = await readFile3(claudeMdPath, "utf-8");
       await writeFile2(claudeMdPath, existing + "\n" + conventionsText.trim() + "\n", "utf-8");
     } catch {
@@ -13505,13 +14268,13 @@ async function scanCodebase(projectRoot) {
   }
   let packageJson;
   try {
-    const content = await readFile3(join2(projectRoot, "package.json"), "utf-8");
+    const content = await readFile3(join3(projectRoot, "package.json"), "utf-8");
     packageJson = JSON.parse(content);
   } catch {
   }
   let readme;
   for (const name of ["README.md", "readme.md", "README.txt", "README"]) {
-    const content = await safeReadFile(join2(projectRoot, name), 5e3);
+    const content = await safeReadFile(join3(projectRoot, name), 5e3);
     if (content) {
       readme = content;
       break;
@@ -13521,7 +14284,7 @@ async function scanCodebase(projectRoot) {
   let totalFiles = topLevelFiles.length;
   for (const dir of topLevelDirs) {
     try {
-      const entries = await readdir(join2(projectRoot, dir), { withFileTypes: true });
+      const entries = await readdir(join3(projectRoot, dir), { withFileTypes: true });
       const files = entries.filter((e) => e.isFile());
       const extensions = [...new Set(files.map((f) => extname(f.name).toLowerCase()).filter(Boolean))];
       totalFiles += files.length;
@@ -13707,7 +14470,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     }
   }
   try {
-    const claudeMdPath = join2(config2.projectRoot, "CLAUDE.md");
+    const claudeMdPath = join3(config2.projectRoot, "CLAUDE.md");
     const existing = await readFile3(claudeMdPath, "utf-8");
     if (!existing.includes("Dogfood Logging")) {
       const dogfoodSection = [
@@ -14008,6 +14771,8 @@ init_dist2();
 
 // src/services/build.ts
 import { randomUUID as randomUUID9 } from "crypto";
+import { readdirSync as readdirSync2, existsSync as existsSync2 } from "fs";
+import { join as join4 } from "path";
 function capitalizeCompleted(value) {
   const map = {
     yes: "Yes",
@@ -14016,25 +14781,11 @@ function capitalizeCompleted(value) {
   };
   return map[value] ?? "No";
 }
-function formatDate(date) {
-  return date.toISOString();
-}
 function autoCommit(config2, taskId, taskTitle) {
-  if (!isGitAvailable()) {
-    return "Auto-commit: skipped (git not found).";
-  }
-  if (!isGitRepo(config2.projectRoot)) {
-    return "Auto-commit: skipped (not a git repository).";
-  }
-  try {
-    const result = stageAllAndCommit(
-      config2.projectRoot,
-      `feat(${taskId}): ${taskTitle}`
-    );
-    return result.committed ? `Auto-committed: ${result.message}` : `Auto-commit: ${result.message}`;
-  } catch (err) {
-    return `Auto-commit failed: ${err instanceof Error ? err.message : String(err)}`;
-  }
+  return runAutoCommit(
+    config2.projectRoot,
+    () => stageAllAndCommit(config2.projectRoot, `feat(${taskId}): ${taskTitle}`)
+  );
 }
 function pushAndCreatePR(config2, taskId, taskTitle) {
   const lines = [];
@@ -14239,20 +14990,19 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
   if (!task) {
     throw new Error(`Task "${taskId}" not found on the Cycle Board.`);
   }
-  let cycleNumber;
-  try {
-    const health = await adapter2.getCycleHealth();
-    cycleNumber = health.totalCycles;
-  } catch {
-    cycleNumber = 0;
-  }
+  const [healthResult, priorCount] = await Promise.all([
+    adapter2.getCycleHealth().catch(() => ({ totalCycles: 0 })),
+    adapter2.getBuildReportCountForTask(taskId).catch(() => 0)
+  ]);
+  const cycleNumber = healthResult.totalCycles;
+  const iterationCount = priorCount + 1;
   const now = /* @__PURE__ */ new Date();
   const report = {
     uuid: randomUUID9(),
     createdAt: now.toISOString(),
     taskId: task.id,
     taskName: task.title,
-    date: formatDate(now),
+    date: now.toISOString(),
     cycle: cycleNumber,
     completed: capitalizeCompleted(input.completed),
     actualEffort: input.effort,
@@ -14264,7 +15014,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     handoffAccuracy: input.handoffAccuracy,
     correctionsCount: input.correctionsCount,
     briefImplications: input.briefImplications,
-    deadEnds: input.deadEnds
+    deadEnds: input.deadEnds,
+    iterationCount
   };
   if (input.relatedDecisions) {
     const adIds = input.relatedDecisions.split(",").map((s) => s.trim()).filter(Boolean);
@@ -14291,7 +15042,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
   }
   const surpriseNote = input.surprises === "None" ? "" : ` Surprises: ${input.surprises}.`;
   const issueNote = input.discoveredIssues === "None" ? "" : ` Issues: ${input.discoveredIssues}.`;
-  const buildReportSummary = `${capitalizeCompleted(input.completed)}. Effort ${input.effort} vs estimated ${input.estimatedEffort}.${surpriseNote}${issueNote}`;
+  const iterNote = iterationCount > 1 ? ` Iterations: ${iterationCount} (${iterationCount - 1} pushback${iterationCount > 2 ? "s" : ""}).` : "";
+  const buildReportSummary = `${capitalizeCompleted(input.completed)}. Effort ${input.effort} vs estimated ${input.estimatedEffort}.${iterNote}${surpriseNote}${issueNote}`;
   await adapter2.updateTask(taskId, { buildReport: buildReportSummary });
   if (input.completed === "yes") {
     if (options.light) {
@@ -14332,6 +15084,32 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     phaseChanges = await propagatePhaseStatus(adapter2);
   } catch {
   }
+  let docWarning;
+  try {
+    if (adapter2.searchDocs) {
+      const docsDir = join4(config2.projectRoot, "docs");
+      if (existsSync2(docsDir)) {
+        const scanDir = (dir) => {
+          const entries = readdirSync2(dir, { withFileTypes: true });
+          const files = [];
+          for (const e of entries) {
+            const full = join4(dir, e.name);
+            if (e.isDirectory()) files.push(...scanDir(full));
+            else if (e.name.endsWith(".md")) files.push(full.replace(config2.projectRoot + "/", ""));
+          }
+          return files;
+        };
+        const mdFiles = scanDir(docsDir);
+        const registered = await adapter2.searchDocs({ status: "active", limit: 500 });
+        const registeredPaths = new Set(registered.map((d) => d.path));
+        const unregistered = mdFiles.filter((f) => !registeredPaths.has(f));
+        if (unregistered.length > 0) {
+          docWarning = `${unregistered.length} unregistered doc(s) in docs/ \u2014 consider running \`doc_register\` for: ${unregistered.slice(0, 5).join(", ")}${unregistered.length > 5 ? ` (+${unregistered.length - 5} more)` : ""}`;
+        }
+      }
+    }
+  } catch {
+  }
   return {
     task,
     report,
@@ -14343,7 +15121,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     discoveredIssues: input.discoveredIssues,
     completed: input.completed,
     scopeAccuracy: input.scopeAccuracy,
-    phaseChanges
+    phaseChanges,
+    docWarning
   };
 }
 async function cancelBuild(adapter2, taskId, reason) {
@@ -14384,7 +15163,7 @@ var buildDescribeTool = {
 };
 var buildExecuteTool = {
   name: "build_execute",
-  description: "Start or complete a build task. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Does not call the Anthropic API.",
+  description: "Start or complete a build task. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Does not call the Anthropic API. Set light=true to skip branch/PR creation (commits to current branch). Set PAPI_LIGHT_MODE=true in env to default all builds to light mode.",
   inputSchema: {
     type: "object",
     properties: {
@@ -14448,11 +15227,11 @@ var buildExecuteTool = {
       },
       dead_ends: {
         type: "string",
-        description: "Failed approaches tried during the build and why they failed. Helps future builders avoid repeating blind alleys. Optional."
+        description: `Approaches tried and rejected during the build, with WHY they failed. Example: "Tried using Supabase realtime subscriptions but Edge Functions can't hold persistent connections \u2014 switched to polling." Include whenever you abandoned an approach. Future builds and plans reference this to avoid repeating blind alleys.`
       },
       brief_implications: {
         type: "array",
-        description: "Discovery learnings from this build that feed back into planning. Each entry targets a discovery canvas section. Optional \u2014 only include when a build reveals something about assumptions, user journeys, MVP boundary, or competitive landscape.",
+        description: "Strategic learnings discovered during this build that the planner and strategy review should know about. Include when a build reveals: (1) something about assumptions that were wrong, (2) competitive/landscape insights, (3) user journey friction discovered during implementation, (4) MVP boundary implications (something that must/must-not be in v1), or (5) new success signal data. Each entry feeds into the Discovery Canvas and informs future planning.",
         items: {
           type: "object",
           properties: {
@@ -14488,6 +15267,30 @@ function formatListItem(task) {
   return `- **${task.id}:** ${task.title}
   Status: ${task.status} | Priority: ${task.priority} | Complexity: ${task.complexity}`;
 }
+function filterRelevantADs(ads, task) {
+  const keywords = [];
+  if (task.module) keywords.push(task.module.toLowerCase());
+  if (task.epic) keywords.push(task.epic.toLowerCase());
+  if (task.phase) keywords.push(task.phase.toLowerCase());
+  const titleWords = task.title.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+  keywords.push(...titleWords);
+  if (keywords.length === 0) return [];
+  return ads.filter((ad) => {
+    if (ad.superseded) return false;
+    const text = `${ad.title} ${ad.body}`.toLowerCase();
+    return keywords.some((kw) => text.includes(kw));
+  });
+}
+function formatRelevantADs(ads) {
+  if (ads.length === 0) return "";
+  const lines = ["\n\n---\n\n**ACTIVE DECISIONS (relevant):**"];
+  for (const ad of ads) {
+    const bodyLines = ad.body.split("\n").filter((l) => l.trim() && !l.startsWith("#"));
+    const summary = bodyLines[0]?.trim().slice(0, 120) ?? "";
+    lines.push(`- **${ad.displayId}: ${ad.title}** [${ad.confidence}] \u2014 ${summary}`);
+  }
+  return lines.join("\n");
+}
 function hasReportFields(args) {
   return !!(args.completed || args.effort || args.estimated_effort || args.surprises || args.discovered_issues || args.architecture_notes);
 }
@@ -14525,6 +15328,15 @@ async function handleBuildList(adapter2, config2) {
   Waiting on: ${unresolvedDeps.join(", ")}`);
     }
   }
+  try {
+    const comments = await adapter2.getRecentTaskComments?.(30);
+    if (comments && comments.length > 0) {
+      const taskIds = new Set([...result.sorted, ...result.blocked.map((b2) => b2.task)].map((t) => t.id));
+      const section = formatTaskComments(comments, taskIds);
+      if (section) lines.push(section);
+    }
+  } catch {
+  }
   return textResponse(lines.join("\n"));
 }
 async function handleBuildDescribe(adapter2, args) {
@@ -14550,7 +15362,7 @@ async function handleBuildExecute(adapter2, config2, args) {
   if (!taskId) {
     return errorResponse("task_id is required.");
   }
-  const light = args.light === true;
+  const light = args.light === true || config2.lightMode;
   if (hasReportFields(args)) {
     return handleExecuteComplete(adapter2, config2, taskId, args, light);
   }
@@ -14563,8 +15375,23 @@ async function handleBuildExecute(adapter2, config2, args) {
 ---
 
 `;
+    const verificationFiles = result.task.buildHandoff.verificationFiles ?? [];
+    const verificationNote = verificationFiles.length > 0 ? `
+
+---
+
+**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.";
-    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + chainInstruction + phaseNote);
+    let adSection = "";
+    try {
+      const allADs = await adapter2.getActiveDecisions();
+      const relevant = filterRelevantADs(allADs, result.task);
+      adSection = formatRelevantADs(relevant);
+    } catch {
+    }
+    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + adSection + verificationNote + chainInstruction + phaseNote);
   } catch (err) {
     if (isNoHandoffError(err)) {
       const lines = [
@@ -14671,6 +15498,9 @@ function formatCompleteResult(result) {
       lines.push(`Phase auto-updated: ${c.phaseId} ${c.oldStatus} \u2192 ${c.newStatus}`);
     }
   }
+  if (result.docWarning) {
+    lines.push("", `\u{1F4C4} ${result.docWarning}`);
+  }
   const hasDiscoveredIssues = result.discoveredIssues !== "None" && result.discoveredIssues.trim() !== "";
   const remaining = result.cycleProgress.total - result.cycleProgress.completed;
   if (result.completed !== "yes") {
@@ -14919,36 +15749,28 @@ async function captureIdea(adapter2, input) {
       return routeToDiscovery(adapter2, routing, input);
     }
   }
-  let similarWarning = "";
-  try {
-    const similar = await findSimilarTasks(adapter2, input.text);
-    if (similar.length > 0) {
-      const highOverlap = similar.filter((s) => s.coverage >= 0.7);
-      if (highOverlap.length > 0 && !input.force) {
-        const lines = highOverlap.map(
+  if (!input.force) {
+    try {
+      const similar = await findSimilarTasks(adapter2, input.text);
+      if (similar.length > 0) {
+        const lines = similar.map(
           (s) => `  - **${s.id}** [${s.status}]: "${s.title}" (${Math.round(s.coverage * 100)}% keyword overlap)`
         );
-        const doneMatch = highOverlap.find((s) => s.status === "Done");
-        const reason = doneMatch ? `This looks like it was **already done** as ${doneMatch.id}.` : `This looks like a **duplicate** of ${highOverlap[0].id}.`;
+        const highOverlap = similar.filter((s) => s.coverage >= 0.7);
+        const doneMatch = similar.find((s) => s.status === "Done");
+        const reason = doneMatch ? `This looks like it was **already done** as ${doneMatch.id}.` : highOverlap.length > 0 ? `This looks like a **duplicate** of ${highOverlap[0].id}.` : `Similar tasks already exist on the board.`;
         return {
           routing: "task",
-          message: `\u26D4 **Blocked \u2014 ${reason}**
+          message: `\u26A0\uFE0F **Paused \u2014 ${reason}**
 
-High-overlap tasks:
+Similar tasks found:
 ${lines.join("\n")}
 
-If this is genuinely different, re-run with \`force: true\`.`
+**STOP: Ask the user whether to proceed.** Explain the overlap and let them decide. If the user confirms this is genuinely different, re-run with \`force: true\`. Do NOT proceed without user confirmation.`
         };
       }
-      const warnLines = similar.map(
-        (s) => `  - **${s.id}** [${s.status}]: "${s.title}" (${Math.round(s.coverage * 100)}% keyword overlap)`
-      );
-      similarWarning = `
-
-\u26A0\uFE0F **Similar tasks found** \u2014 check before scheduling:
-${warnLines.join("\n")}`;
+    } catch {
     }
-  } catch {
   }
   const [health, phases] = await Promise.all([
     adapter2.getCycleHealth(),
@@ -14956,13 +15778,17 @@ ${warnLines.join("\n")}`;
   ]);
   warnIfEmpty("getCycleHealth (idea)", health);
   const phase = input.phase || resolveCurrentPhase(phases);
+  const VALID_PRIORITIES2 = /* @__PURE__ */ new Set(["P0 Critical", "P1 High", "P2 Medium", "P3 Low"]);
+  const VALID_COMPLEXITIES2 = /* @__PURE__ */ new Set(["XS", "Small", "Medium", "Large", "XL"]);
+  const priority = input.priority && VALID_PRIORITIES2.has(input.priority) ? input.priority : "P2 Medium";
+  const complexity = input.complexity && VALID_COMPLEXITIES2.has(input.complexity) ? input.complexity : "Small";
   const task = await adapter2.createTask({
     uuid: randomUUID10(),
     displayId: "",
     title: input.text,
     status: "Backlog",
-    priority: "P3 Low",
-    complexity: "Medium",
+    priority,
+    complexity,
     module: input.module || "Core",
     epic: input.epic || "Platform",
     phase,
@@ -14973,7 +15799,7 @@ ${warnLines.join("\n")}`;
     taskType: "idea",
     maturity: "raw"
   });
-  return { routing: "task", task, message: `${task.id}: "${task.title}" \u2014 added to backlog${similarWarning}` };
+  return { routing: "task", task, message: `${task.id}: "${task.title}" \u2014 added to backlog` };
 }
 var CANVAS_SECTION_LABELS = {
   landscape: "Landscape References",
@@ -15013,7 +15839,7 @@ async function routeToDiscovery(adapter2, section, input) {
 // src/tools/idea.ts
 var ideaTool = {
   name: "idea",
-  description: "Capture an idea as a Backlog task. The next plan run will triage and scope it. Use anytime to log bugs, feature requests, or improvements without interrupting the current cycle. Does not call the Anthropic API.",
+  description: "Capture an idea as a Backlog task. The next plan run will triage and scope it. Use anytime to log bugs, feature requests, or improvements without interrupting the current cycle. IMPORTANT: If this idea originates from a research or planning session, you MUST include a Reference: line in notes pointing to the source doc. Without it, the planner has no context and will misinterpret the intent. Does not call the Anthropic API.",
   inputSchema: {
     type: "object",
     properties: {
@@ -15023,7 +15849,7 @@ var ideaTool = {
       },
       notes: {
         type: "string",
-        description: 'Additional context, constraints, or reasoning. For M/L ideas that originated from research or scoping sessions, include a Reference: line (e.g. "Reference: docs/architecture/papi-brain-v1.md") so the planner can pass it through to the BUILD HANDOFF for the builder to read.'
+        description: 'Additional context, constraints, or reasoning. MANDATORY: If this idea comes from a research or planning session, include a "Reference: <path>" line pointing to the source doc. Tasks submitted without references get misinterpreted by the planner \u2014 this is the #1 cause of wasted build slots (C146: task-807 was scoped as landing page copy when it was actually a dashboard UX task, because the source research doc was missing). Use doc_search to find relevant docs before submitting.'
       },
       module: {
         type: "string",
@@ -15037,6 +15863,16 @@ var ideaTool = {
         type: "string",
         description: 'Target phase (default: "Unscoped").'
       },
+      priority: {
+        type: "string",
+        enum: ["P0 Critical", "P1 High", "P2 Medium", "P3 Low"],
+        description: 'Priority level. P0 = broken/blocking. P1 = strategically aligned with current goals. P2 = valuable but not urgent. P3 = nice-to-have/speculative. Default: "P2 Medium". Assess based on strategic alignment and impact, not just effort.'
+      },
+      complexity: {
+        type: "string",
+        enum: ["XS", "Small", "Medium", "Large", "XL"],
+        description: 'Estimated complexity. XS = config/one-liner. Small = one file. Medium = 2-5 files. Large = cross-module. XL = architectural. Default: "Small".'
+      },
       discovery: {
         type: "boolean",
         description: "When true, classify the idea and route to Discovery Canvas instead of backlog. Default: false (always creates a backlog task)."
@@ -15066,6 +15902,8 @@ async function handleIdea(adapter2, config2, args) {
     module: args.module,
     epic: args.epic,
     phase: args.phase,
+    priority: args.priority,
+    complexity: args.complexity,
     notes: rawNotes,
     discovery: args.discovery === true,
     force: args.force === true
@@ -15088,7 +15926,24 @@ async function handleIdea(adapter2, config2, args) {
   if (result.routing === "task") {
     const branchNote = onFeatureBranch ? ` on ${currentBranch} for next cycle planning.` : " for next cycle planning.";
     const truncateWarning = notesTruncated ? ` (notes truncated to ${MAX_NOTES_LENGTH} chars)` : "";
-    return textResponse(`${result.message}${branchNote}${truncateWarning}`);
+    const hasReference = rawNotes?.toLowerCase().includes("reference:") ?? false;
+    let refNudge = "";
+    if (!hasReference && result.task && adapter2.searchDocs) {
+      try {
+        const keywords = text.split(/\s+/).filter((w) => w.length > 3).slice(0, 3).join(" ");
+        const relatedDocs = await adapter2.searchDocs({ keyword: keywords, limit: 3 });
+        if (relatedDocs.length > 0) {
+          const docList = relatedDocs.map((d) => `  - ${d.path} \u2014 ${d.title}`).join("\n");
+          refNudge = `
+
+\u26A0\uFE0F **No Reference: line in notes.** The planner generates better handoffs when ideas link to source docs. Potentially relevant docs:
+${docList}
+Re-submit with \`notes: "... Reference: <path>"\` to link one, or ignore if none are relevant.`;
+        }
+      } catch {
+      }
+    }
+    return textResponse(`${result.message}${branchNote}${truncateWarning}${refNudge}`);
   }
   return textResponse(result.message);
 }
@@ -15105,9 +15960,9 @@ function resolveCurrentPhase2(phases) {
 function severityToPriority(severity) {
   switch (severity) {
     case "critical":
-      return "P1 Critical";
+      return "P0 Critical";
     case "major":
-      return "P2 Medium";
+      return "P1 High";
     default:
       return "P2 Medium";
   }
@@ -15567,18 +16422,110 @@ async function applyReconcile(adapter2, corrections) {
   }
   return { applied, skipped, details, phaseChanges };
 }
+var VALID_PRIORITIES = /* @__PURE__ */ new Set(["P0 Critical", "P1 High", "P2 Medium", "P3 Low"]);
+var VALID_COMPLEXITIES = /* @__PURE__ */ new Set(["XS", "Small", "Medium", "Large", "XL"]);
+async function prepareRetriage(adapter2) {
+  const health = await adapter2.getCycleHealth();
+  const currentCycle = health.totalCycles;
+  const allTasks = await adapter2.queryBoard({
+    status: ["Backlog", "In Cycle", "Ready", "Blocked"]
+  });
+  if (allTasks.length === 0) {
+    return "No backlog tasks to retriage.";
+  }
+  const lines = [];
+  lines.push(`## Board Retriage \u2014 Cycle ${currentCycle}`);
+  lines.push("");
+  lines.push(`**${allTasks.length} tasks** to reassess priority and complexity.`);
+  lines.push("");
+  try {
+    const ads = await adapter2.readActiveDecisions();
+    if (ads.length > 0) {
+      lines.push("### Active Decisions (strategic context)");
+      for (const ad of ads.slice(0, 10)) {
+        lines.push(`- **${ad.id}:** ${ad.title} [${ad.confidence}]`);
+      }
+      lines.push("");
+    }
+  } catch {
+  }
+  try {
+    const phases = await adapter2.readPhases();
+    const inProgress = phases.filter((p) => p.status === "In Progress");
+    if (inProgress.length > 0) {
+      lines.push("### Active Phases");
+      for (const p of inProgress) {
+        lines.push(`- ${p.label} (${p.status})`);
+      }
+      lines.push("");
+    }
+  } catch {
+  }
+  lines.push("### All Tasks to Retriage");
+  lines.push("");
+  for (const t of allTasks) {
+    const age = currentCycle - (t.createdCycle ?? 0);
+    const notes = t.notes ? ` \u2014 ${t.notes.slice(0, 120)}` : "";
+    lines.push(`- **${t.id}:** ${t.title} [current: ${t.priority} | ${t.complexity} | ${t.module} | ${t.phase}] (${age} cycles old)${notes}`);
+  }
+  return lines.join("\n");
+}
+async function applyRetriage(adapter2, retriages) {
+  const details = [];
+  let applied = 0;
+  let skipped = 0;
+  let unchanged = 0;
+  for (const r of retriages) {
+    try {
+      const task = await adapter2.getTask(r.taskId);
+      if (!task) {
+        details.push(`${r.taskId}: skipped \u2014 not found`);
+        skipped++;
+        continue;
+      }
+      if (!VALID_PRIORITIES.has(r.priority)) {
+        details.push(`${r.taskId}: skipped \u2014 invalid priority "${r.priority}"`);
+        skipped++;
+        continue;
+      }
+      if (!VALID_COMPLEXITIES.has(r.complexity)) {
+        details.push(`${r.taskId}: skipped \u2014 invalid complexity "${r.complexity}"`);
+        skipped++;
+        continue;
+      }
+      if (task.priority === r.priority && task.complexity === r.complexity) {
+        details.push(`${r.taskId}: unchanged \u2014 already ${r.priority} / ${r.complexity}`);
+        unchanged++;
+        continue;
+      }
+      const changes = [];
+      if (task.priority !== r.priority) changes.push(`priority ${task.priority} \u2192 ${r.priority}`);
+      if (task.complexity !== r.complexity) changes.push(`complexity ${task.complexity} \u2192 ${r.complexity}`);
+      await adapter2.updateTask(r.taskId, {
+        priority: r.priority,
+        complexity: r.complexity
+      });
+      details.push(`${r.taskId}: ${changes.join(", ")} \u2014 ${r.reason}`);
+      applied++;
+    } catch (err) {
+      details.push(`${r.taskId}: error \u2014 ${err instanceof Error ? err.message : String(err)}`);
+      skipped++;
+    }
+  }
+  return { applied, skipped, unchanged, details };
+}
 
 // src/tools/board-reconcile.ts
 var boardReconcileTool = {
   name: "board_reconcile",
-  description: "Holistic backlog review to group, merge, cancel, or defer stale tasks. Prepare phase returns backlog context for analysis. Apply phase accepts corrections. Does not call the Anthropic API.",
+  description: 'Holistic backlog review to group, merge, cancel, defer, or retriage tasks. "prepare"/"apply" for cleanup. "retriage-prepare"/"retriage-apply" to reassess priority and complexity on existing backlog tasks. Does not call the Anthropic API.',
   inputSchema: {
     type: "object",
     properties: {
       mode: {
         type: "string",
-        enum: ["prepare", "apply"],
-        description: '"prepare" returns backlog context for analysis. "apply" accepts corrections. Defaults to "prepare".'
+        enum: ["prepare", "apply", "retriage-prepare", "retriage-apply"],
+        description: '"prepare"/"apply" for cleanup. "retriage-prepare"/"retriage-apply" to reassess priority and complexity on backlog tasks. Defaults to "prepare".'
       },
       llm_response: {
         type: "string",
@@ -15629,6 +16576,47 @@ When done, call \`board_reconcile\` again with:
 - \`mode\`: "apply"
 - \`llm_response\`: your complete output (both parts)
 `;
+var RETRIAGE_PROMPT = `You are the PAPI Board Retriager. Reassess the priority and complexity of every backlog task below using these criteria:
+
+## Priority Levels
+- **P0 Critical** \u2014 Broken, blocking, or data-loss risk. Fix now.
+- **P1 High** \u2014 Strategically aligned: directly advances the current horizon/phase goals or Active Decisions.
+- **P2 Medium** \u2014 Valuable but not strategically urgent: quality improvements, efficiency, polish, infrastructure.
+- **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
+
+## Complexity Levels
+- **XS** \u2014 Config change, one-liner, toggle.
+- **Small** \u2014 One file, < 50 lines changed.
+- **Medium** \u2014 2-5 files, moderate scope.
+- **Large** \u2014 Cross-module, multiple components.
+- **XL** \u2014 Architectural, multi-day effort.
+
+## Rules
+- Assess priority based on **strategic alignment** (does it advance current goals?), **unlocks other work** (are tasks blocked by this?), **user-facing impact**, and **compounding value** (does it make future work faster?).
+- Assess complexity based on the **actual scope of the change**, not conservatively. Use the full range.
+- If a task's current priority and complexity are already correct, still include it with the same values \u2014 this confirms the assessment.
+
+Your output must have TWO parts:
+
+### Part 1: Analysis
+Brief markdown analysis of how priorities should shift and why.
+
+### Part 2: Structured Output
+After \`<!-- PAPI_RETRIAGE_OUTPUT -->\`, a JSON block:
+
+\`\`\`json
+{
+  "retriages": [
+    {"taskId": "task-123", "priority": "P1 High", "complexity": "Medium", "reason": "Directly advances Phase 2 goals"},
+    {"taskId": "task-124", "priority": "P3 Low", "complexity": "Small", "reason": "Nice-to-have, no strategic urgency"}
+  ]
+}
+\`\`\`
+
+When done, call \`board_reconcile\` again with:
+- \`mode\`: "retriage-apply"
+- \`llm_response\`: your complete output (both parts)
+`;
 async function handleBoardReconcile(adapter2, config2, args) {
   const mode = args.mode ?? "prepare";
   if (mode === "prepare") {
@@ -15694,7 +16682,70 @@ Analyze the backlog above and produce your reconciliation output. Then call \`bo
     }
     return textResponse(lines.join("\n"));
   }
-  return errorResponse(`Unknown mode: ${mode}. Use "prepare" or "apply".`);
+  if (mode === "retriage-prepare") {
+    const context = await prepareRetriage(adapter2);
+    if (context === "No backlog tasks to retriage.") {
+      return textResponse(context);
+    }
+    return textResponse(
+      `${RETRIAGE_PROMPT}
+---
+
+### Backlog Context
+
+${context}
+---
+
+Assess each task above and produce your retriage output. Then call \`board_reconcile\` with mode "retriage-apply".`
+    );
+  }
+  if (mode === "retriage-apply") {
+    const llmResponse = args.llm_response;
+    if (!llmResponse?.trim()) {
+      return errorResponse("llm_response is required for retriage-apply mode.");
+    }
+    const marker = "<!-- PAPI_RETRIAGE_OUTPUT -->";
+    const markerIdx = llmResponse.indexOf(marker);
+    if (markerIdx === -1) {
+      return errorResponse("Missing <!-- PAPI_RETRIAGE_OUTPUT --> marker in response.");
+    }
+    const jsonPart = llmResponse.slice(markerIdx + marker.length);
+    const jsonMatch = jsonPart.match(/```json\s*([\s\S]*?)\s*```/);
+    if (!jsonMatch) {
+      return errorResponse("No JSON block found after <!-- PAPI_RETRIAGE_OUTPUT --> marker.");
+    }
+    let retriages;
+    try {
+      const parsed = JSON.parse(jsonMatch[1]);
+      retriages = parsed.retriages;
+      if (!Array.isArray(retriages)) {
+        return errorResponse("retriages must be an array.");
+      }
+    } catch (err) {
+      return errorResponse(`Invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const result = await applyRetriage(adapter2, retriages);
+    if (isGitAvailable() && isGitRepo(config2.projectRoot)) {
+      try {
+        stageDirAndCommit(
+          config2.projectRoot,
+          config2.papiDir,
+          `chore: board retriage \u2014 ${result.applied} tasks updated`
+        );
+      } catch {
+      }
+    }
+    const lines = [];
+    lines.push(`## Board Retriage Complete`);
+    lines.push("");
+    lines.push(`**${result.applied} tasks updated**, ${result.skipped} skipped, ${result.unchanged} unchanged.`);
+    lines.push("");
+    for (const d of result.details) {
+      lines.push(`- ${d}`);
+    }
+    return textResponse(lines.join("\n"));
+  }
+  return errorResponse(`Unknown mode: ${mode}. Use "prepare", "apply", "retriage-prepare", or "retriage-apply".`);
 }
 
 // src/services/health.ts
@@ -15818,6 +16869,25 @@ async function getHealthSummary(adapter2) {
   } catch (_err) {
     metricsSection = "Could not read methodology metrics.";
   }
+  try {
+    const recentReports = await adapter2.getRecentBuildReports(50);
+    if (recentReports.length > 0) {
+      const taskCounts = /* @__PURE__ */ new Map();
+      for (const r of recentReports) {
+        taskCounts.set(r.taskId, (taskCounts.get(r.taskId) ?? 0) + 1);
+      }
+      const iterCounts = [...taskCounts.values()];
+      const avgIter = iterCounts.reduce((s, c) => s + c, 0) / iterCounts.length;
+      const multiIterTasks = iterCounts.filter((c) => c > 1).length;
+      if (avgIter > 1 || multiIterTasks > 0) {
+        derivedMetricsSection += `
+
+**Rework**
+- Average iterations: ${avgIter.toFixed(1)} (${multiIterTasks} task${multiIterTasks !== 1 ? "s" : ""} with pushbacks)`;
+      }
+    }
+  } catch {
+  }
   const costSection = "Disabled \u2014 local MCP, no API costs.";
   let decisionUsageSection = "";
   try {
@@ -15991,7 +17061,7 @@ async function handleHealth(adapter2) {
 
 // src/services/release.ts
 import { writeFile as writeFile3 } from "fs/promises";
-import { join as join3 } from "path";
+import { join as join5 } from "path";
 var INITIAL_RELEASE_NOTES = `# Changelog
 
 ## v0.1.0-alpha \u2014 Initial Release
@@ -16082,7 +17152,7 @@ async function createRelease(config2, branch, version, adapter2) {
     const commits = getCommitsSinceTag(config2.projectRoot, latestTag);
     changelogContent = generateChangelog(version, commits);
   }
-  const changelogPath = join3(config2.projectRoot, "CHANGELOG.md");
+  const changelogPath = join5(config2.projectRoot, "CHANGELOG.md");
   await writeFile3(changelogPath, changelogContent, "utf-8");
   const commitResult = stageAllAndCommit(config2.projectRoot, `release: ${version}`);
   const commitNote = commitResult.committed ? `Committed CHANGELOG.md.` : `CHANGELOG.md: ${commitResult.message}`;
@@ -16156,6 +17226,20 @@ async function handleRelease(adapter2, config2, args) {
     if (result.warnings?.length) {
       lines.push("", "\u26A0\uFE0F Warnings: " + result.warnings.join("; "));
     }
+    try {
+      const cycleMatch = version.match(/^v0\.(\d+)\./);
+      const cycleNum = cycleMatch ? parseInt(cycleMatch[1], 10) : 0;
+      if (cycleNum > 0) {
+        const reports = await adapter2.getBuildReportsSince(cycleNum);
+        const EMPTY = /* @__PURE__ */ new Set(["None", "none", "N/A", "", "null"]);
+        const issues = reports.filter((r) => r.discoveredIssues && !EMPTY.has(r.discoveredIssues.trim())).map((r) => `- **${r.taskId}** (${r.taskName}): ${r.discoveredIssues}`);
+        if (issues.length > 0) {
+          lines.push("", "---", "", `## Discovered Issues (${issues.length})`, "", ...issues);
+          lines.push("", "*These issues were logged during builds \u2014 triage them in the next plan.*");
+        }
+      }
+    } catch {
+    }
     return textResponse(lines.join("\n"));
   } catch (err) {
     return errorResponse(err instanceof Error ? err.message : String(err));
@@ -16163,8 +17247,8 @@ async function handleRelease(adapter2, config2, args) {
 }
 
 // src/tools/review.ts
-import { existsSync } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { join as join6 } from "path";
 
 // src/services/review.ts
 init_dist2();
@@ -16402,8 +17486,8 @@ function mergeAfterAccept(config2, taskId) {
   }
   const featureBranch = taskBranchName(taskId);
   const baseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
-  const papiDir = join4(config2.projectRoot, ".papi");
-  if (existsSync(papiDir)) {
+  const papiDir = join6(config2.projectRoot, ".papi");
+  if (existsSync3(papiDir)) {
     try {
       const commitResult = stageDirAndCommit(
         config2.projectRoot,
@@ -16692,6 +17776,9 @@ Path: ${mcpJsonPath}`
 }
 
 // src/tools/orient.ts
+import { execFileSync as execFileSync3 } from "child_process";
+import { readFileSync, writeFileSync, existsSync as existsSync4 } from "fs";
+import { join as join7 } from "path";
 var orientTool = {
   name: "orient",
   description: "Session orientation \u2014 single call that replaces build_list + health. Returns: cycle number, task counts by status, in-progress/in-review tasks, strategy review cadence, velocity snapshot, and recommended next action. Read-only, does not modify any files.",
@@ -16836,8 +17923,31 @@ async function getHierarchyPosition(adapter2) {
     return void 0;
   }
 }
+function checkNpmVersionDrift() {
+  try {
+    const pkgPath = join7(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const localVersion = pkg.version;
+    const packageName = pkg.name;
+    const published = execFileSync3("npm", ["view", packageName, "version"], {
+      encoding: "utf-8",
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (published && published !== localVersion) {
+      return `\u26A0\uFE0F npm version drift: local v${localVersion} vs published v${published}`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 async function handleOrient(adapter2, config2) {
   try {
+    try {
+      await propagatePhaseStatus(adapter2);
+    } catch {
+    }
     const [buildResult, healthResult, hierarchy] = await Promise.all([
       listBuilds(adapter2, config2),
       getHealthSummary(adapter2),
@@ -16884,23 +17994,69 @@ async function handleOrient(adapter2, config2) {
       } catch {
       }
     }
-    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy) + ttfvNote);
+    const versionDrift = checkNpmVersionDrift();
+    const versionNote = versionDrift ? `
+${versionDrift}` : "";
+    let recsNote = "";
+    try {
+      const pendingRecs = await adapter2.getPendingRecommendations();
+      if (pendingRecs.length > 0) {
+        recsNote = `
+**Strategy Recommendations:** ${pendingRecs.length} pending action`;
+      }
+    } catch {
+    }
+    let pendingReviewNote = "";
+    try {
+      const pending = await adapter2.getPendingReviewResponse?.();
+      if (pending) {
+        pendingReviewNote = `
+\u26A0\uFE0F **Pending Strategy Review:** 1 review failed write-back (Cycle ${pending.cycleNumber}) \u2014 run \`strategy_review\` to retry.`;
+      }
+    } catch {
+    }
+    let enrichmentNote = "";
+    try {
+      enrichmentNote = enrichClaudeMd(config2.projectRoot, healthResult.cycleNumber);
+    } catch {
+    }
+    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy) + ttfvNote + recsNote + pendingReviewNote + versionNote + enrichmentNote);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return errorResponse(`Orient failed: ${message}`);
   }
 }
+function enrichClaudeMd(projectRoot, cycleNumber) {
+  const claudeMdPath = join7(projectRoot, "CLAUDE.md");
+  if (!existsSync4(claudeMdPath)) return "";
+  const content = readFileSync(claudeMdPath, "utf-8");
+  const additions = [];
+  if (cycleNumber >= 6 && !content.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1)) {
+    additions.push(CLAUDE_MD_TIER_1);
+  }
+  if (cycleNumber >= 21 && !content.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T2)) {
+    additions.push(CLAUDE_MD_TIER_2);
+  }
+  if (additions.length === 0) return "";
+  writeFileSync(claudeMdPath, content + additions.join(""), "utf-8");
+  const tierNames = [];
+  if (additions.some((a) => a.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1))) tierNames.push("Established (batch building, strategy reviews, AD lifecycle)");
+  if (additions.some((a) => a.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T2))) tierNames.push("Mature (idea pipeline, doc registry, advanced patterns)");
+  return `
+
+\u{1F4DD} **CLAUDE.md enriched** \u2014 added ${tierNames.join(" + ")} guidance for cycle ${cycleNumber}+ projects.`;
+}
 
 // src/tools/hierarchy.ts
 var hierarchyUpdateTool = {
   name: "hierarchy_update",
-  description: "Update the status of a stage or horizon in the project hierarchy (AD-14). Accepts a level (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. Does not call the Anthropic API.",
   inputSchema: {
     type: "object",
     properties: {
       level: {
         type: "string",
-        enum: ["stage", "horizon"],
+        enum: ["phase", "stage", "horizon"],
         description: "Which hierarchy level to update."
       },
       name: {
@@ -16924,13 +18080,32 @@ async function handleHierarchyUpdate(adapter2, args) {
   if (!level || !name || !status) {
     return errorResponse("Missing required parameters: level, name, status.");
   }
-  if (level !== "stage" && level !== "horizon") {
-    return errorResponse(`Invalid level "${level}". Must be "stage" or "horizon".`);
+  if (level !== "phase" && level !== "stage" && level !== "horizon") {
+    return errorResponse(`Invalid level "${level}". Must be "phase", "stage", or "horizon".`);
   }
   if (!VALID_STATUSES3.has(status)) {
     return errorResponse(`Invalid status "${status}". Must be one of: active, completed, deferred.`);
   }
   try {
+    if (level === "phase") {
+      if (!adapter2.readPhases || !adapter2.updatePhaseStatus) {
+        return errorResponse("Phase management is not supported by the current adapter.");
+      }
+      const phases = await adapter2.readPhases();
+      const phase = phases.find(
+        (p) => p.label.toLowerCase() === name.toLowerCase() || p.id === name || p.slug === name
+      );
+      if (!phase) {
+        const available = phases.map((p) => p.label).join(", ");
+        return errorResponse(`Phase "${name}" not found. Available phases: ${available || "none"}`);
+      }
+      if (phase.status === status) {
+        return textResponse(`Phase "${phase.label}" is already "${status}". No change made.`);
+      }
+      const oldStatus2 = phase.status;
+      await adapter2.updatePhaseStatus(phase.id, status);
+      return textResponse(`Phase updated: **${phase.label}** ${oldStatus2} \u2192 ${status}`);
+    }
     if (level === "stage") {
       if (!adapter2.readStages || !adapter2.updateStageStatus) {
         return errorResponse("Stage management is not supported by the current adapter.");
@@ -17311,6 +18486,218 @@ ${result.userMessage}
   }
 }
 
+// src/tools/doc-registry.ts
+import { readdirSync as readdirSync3, existsSync as existsSync5, readFileSync as readFileSync2 } from "fs";
+import { join as join8, relative } from "path";
+import { homedir as homedir2 } from "os";
+var docRegisterTool = {
+  name: "doc_register",
+  description: "Register a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: 'Relative path from project root (e.g. "docs/research/funding-landscape.md").' },
+      title: { type: "string", description: "Document title." },
+      type: { type: "string", enum: ["research", "audit", "spec", "guide", "architecture", "positioning", "framework", "reference"], description: "Document type." },
+      status: { type: "string", enum: ["active", "draft", "superseded", "actioned", "legacy", "archived"], description: 'Document status. Defaults to "active".' },
+      summary: { type: "string", description: 'Structured 2-4 sentence summary. Format: "Conclusions: ... Open questions: ... Unactioned: ..."' },
+      tags: { type: "array", items: { type: "string" }, description: "Tags from project vocabulary." },
+      cycle: { type: "number", description: "Current cycle number." },
+      actions: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            description: { type: "string" },
+            status: { type: "string", enum: ["pending", "resolved"] },
+            linkedTaskId: { type: "string" }
+          },
+          required: ["description", "status"]
+        },
+        description: "Actionable findings from the document."
+      },
+      superseded_by_path: { type: "string", description: "Path of the doc that supersedes this one (sets status to superseded)." }
+    },
+    required: ["path", "title", "type", "summary", "cycle"]
+  }
+};
+var docSearchTool = {
+  name: "doc_search",
+  description: "Search the doc registry for documents by type, tags, keyword, or pending actions. Returns summaries, not full content. Use for context gathering in plan, strategy review, and idea dedup.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      type: { type: "string", description: 'Filter by doc type (e.g. "research", "architecture").' },
+      status: { type: "string", description: 'Filter by status. Defaults to "active".' },
+      tags: { type: "array", items: { type: "string" }, description: "Filter by tags (OR match)." },
+      keyword: { type: "string", description: "Search title and summary text." },
+      has_pending_actions: { type: "boolean", description: "Only docs with unresolved action items." },
+      since_cycle: { type: "number", description: "Docs updated since this cycle." },
+      limit: { type: "number", description: "Max results (default: 10)." }
+    },
+    required: []
+  }
+};
+var docScanTool = {
+  name: "doc_scan",
+  description: "Scan docs/ and plans directories for unregistered .md files. Returns a list of files not yet in the doc registry. Use this to find docs that need registration.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      include_plans: {
+        type: "boolean",
+        description: "Also scan ~/.claude/plans/ for plan files (default: false)."
+      }
+    },
+    required: []
+  }
+};
+async function handleDocRegister(adapter2, args) {
+  if (!adapter2.registerDoc) {
+    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+  }
+  const path5 = args.path;
+  const title = args.title;
+  const type = args.type;
+  const status = args.status ?? "active";
+  const summary = args.summary;
+  const tags = args.tags ?? [];
+  const cycle = args.cycle;
+  const actions = args.actions;
+  const supersededByPath = args.superseded_by_path;
+  if (!path5 || !title || !type || !summary || !cycle) {
+    return errorResponse("Required fields: path, title, type, summary, cycle.");
+  }
+  let supersededBy;
+  if (supersededByPath) {
+    const existing = await adapter2.getDoc?.(supersededByPath);
+    if (existing) {
+      supersededBy = existing.id;
+      await adapter2.updateDocStatus?.(existing.id, "superseded", void 0);
+    }
+  }
+  const entry = await adapter2.registerDoc({
+    title,
+    type,
+    path: path5,
+    status: supersededByPath ? "superseded" : status,
+    summary,
+    tags,
+    cycleCreated: cycle,
+    cycleUpdated: cycle,
+    supersededBy,
+    actions
+  });
+  return textResponse(
+    `**Registered:** ${entry.title}
+- **Path:** ${entry.path}
+- **Type:** ${entry.type} | **Status:** ${entry.status}
+- **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
+- **Actions:** ${actions?.length ?? 0} items
+- **ID:** ${entry.id}`
+  );
+}
+async function handleDocSearch(adapter2, args) {
+  if (!adapter2.searchDocs) {
+    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+  }
+  const input = {
+    type: args.type,
+    status: args.status,
+    tags: args.tags,
+    keyword: args.keyword,
+    hasPendingActions: args.has_pending_actions,
+    sinceCycle: args.since_cycle,
+    limit: args.limit
+  };
+  const docs = await adapter2.searchDocs(input);
+  if (docs.length === 0) {
+    return textResponse("No documents found matching the search criteria.");
+  }
+  const lines = docs.map((d) => {
+    const actionCount = d.actions?.filter((a) => a.status === "pending").length ?? 0;
+    const actionNote = actionCount > 0 ? ` | ${actionCount} pending action(s)` : "";
+    return `### ${d.title}
+**Type:** ${d.type} | **Status:** ${d.status} | **Cycle:** ${d.cycleCreated}${d.cycleUpdated ? `\u2192${d.cycleUpdated}` : ""}${actionNote}
+**Path:** ${d.path}
+**Tags:** ${d.tags.length > 0 ? d.tags.join(", ") : "none"}
+${d.summary}
+`;
+  });
+  return textResponse(`**${docs.length} document(s) found:**
+
+${lines.join("\n---\n\n")}`);
+}
+function scanMdFiles(dir, rootDir) {
+  if (!existsSync5(dir)) return [];
+  const files = [];
+  try {
+    const entries = readdirSync3(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join8(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...scanMdFiles(full, rootDir));
+      } else if (entry.name.endsWith(".md")) {
+        files.push(relative(rootDir, full));
+      }
+    }
+  } catch {
+  }
+  return files;
+}
+function extractTitle(filePath) {
+  try {
+    const content = readFileSync2(filePath, "utf-8").slice(0, 1e3);
+    const fmMatch = content.match(/^---[\s\S]*?title:\s*(.+?)$/m);
+    if (fmMatch) return fmMatch[1].trim().replace(/^["']|["']$/g, "");
+    const headingMatch = content.match(/^#+\s+(.+)$/m);
+    if (headingMatch) return headingMatch[1].trim();
+  } catch {
+  }
+  return void 0;
+}
+async function handleDocScan(adapter2, config2, args) {
+  if (!adapter2.searchDocs) {
+    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+  }
+  const includePlans = args.include_plans ?? false;
+  const registered = await adapter2.searchDocs({ limit: 500 });
+  const registeredPaths = new Set(registered.map((d) => d.path));
+  const docsDir = join8(config2.projectRoot, "docs");
+  const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
+  const unregisteredDocs = docsFiles.filter((f) => !registeredPaths.has(f));
+  let unregisteredPlans = [];
+  if (includePlans) {
+    const plansDir = join8(homedir2(), ".claude", "plans");
+    if (existsSync5(plansDir)) {
+      const planFiles = scanMdFiles(plansDir, plansDir);
+      unregisteredPlans = planFiles.map((f) => `plans/${f}`).filter((f) => !registeredPaths.has(f)).map((f) => ({
+        path: f,
+        title: extractTitle(join8(plansDir, f.replace("plans/", "")))
+      }));
+    }
+  }
+  const lines = [];
+  if (unregisteredDocs.length === 0 && unregisteredPlans.length === 0) {
+    return textResponse("All docs are registered. No unregistered files found.");
+  }
+  if (unregisteredDocs.length > 0) {
+    lines.push(`## Unregistered Docs (${unregisteredDocs.length})`);
+    for (const f of unregisteredDocs) {
+      const title = extractTitle(join8(config2.projectRoot, f));
+      lines.push(`- \`${f}\`${title ? ` \u2014 ${title}` : ""}`);
+    }
+  }
+  if (unregisteredPlans.length > 0) {
+    lines.push("", `## Unregistered Plans (${unregisteredPlans.length})`);
+    for (const p of unregisteredPlans) {
+      lines.push(`- \`${p.path}\`${p.title ? ` \u2014 ${p.title}` : ""}`);
+    }
+  }
+  lines.push("", `Use \`doc_register\` to register these files.`);
+  return textResponse(lines.join("\n"));
+}
+
 // src/lib/telemetry.ts
 var TELEMETRY_SUPABASE_URL = "https://guewgygcpcmrcoppihzx.supabase.co";
 var TELEMETRY_API_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imd1ZXdneWdjcGNtcmNvcHBpaHp4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI2Njk2NTMsImV4cCI6MjA4ODI0NTY1M30.V5Jw7wJgiMpSQPa2mt0ftjyye5ynG1qLlam00yPVNJY";
@@ -17363,6 +18750,7 @@ var TOOLS_REQUIRING_PAPI = /* @__PURE__ */ new Set([
   "board_view",
   "board_deprioritise",
   "board_archive",
+  "board_edit",
   "build_list",
   "build_describe",
   "build_execute",
@@ -17391,6 +18779,7 @@ function createServer(adapter2, config2) {
       boardViewTool,
       boardDeprioritiseTool,
       boardArchiveTool,
+      boardEditTool,
       setupTool,
       buildListTool,
       buildDescribeTool,
@@ -17407,7 +18796,10 @@ function createServer(adapter2, config2) {
       initTool,
       orientTool,
       hierarchyUpdateTool,
-      zoomOutTool
+      zoomOutTool,
+      docRegisterTool,
+      docSearchTool,
+      docScanTool
     ]
   }));
   server2.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -17457,6 +18849,9 @@ function createServer(adapter2, config2) {
       case "board_archive":
         result = await handleBoardArchive(adapter2, safeArgs);
         break;
+      case "board_edit":
+        result = await handleBoardEdit(adapter2, safeArgs);
+        break;
       case "setup":
         result = await handleSetup(adapter2, config2, safeArgs);
         break;
@@ -17508,6 +18903,15 @@ function createServer(adapter2, config2) {
       case "zoom_out":
         result = await handleZoomOut(adapter2, config2, safeArgs);
         break;
+      case "doc_register":
+        result = await handleDocRegister(adapter2, safeArgs);
+        break;
+      case "doc_search":
+        result = await handleDocSearch(adapter2, safeArgs);
+        break;
+      case "doc_scan":
+        result = await handleDocScan(adapter2, config2, safeArgs);
+        break;
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
     }