@papi-ai/server 0.7.13 → 0.7.15

package/dist/index.js

@@ -10,7 +10,12 @@ var __export = (target, all) => {
 };
 
 // ../shared/dist/index.js
-var VALID_TRANSITIONS;
+function isLiveDecision(d) {
+  if (d.superseded === true) return false;
+  if (d.outcome != null && RETIRED_DECISION_OUTCOMES.includes(d.outcome)) return false;
+  return true;
+}
+var VALID_TRANSITIONS, RETIRED_DECISION_OUTCOMES;
 var init_dist = __esm({
   "../shared/dist/index.js"() {
     "use strict";
@@ -25,6 +30,7 @@ var init_dist = __esm({
       "Cancelled": [],
       "Deferred": ["Backlog", "Cancelled"]
     };
+    RETIRED_DECISION_OUTCOMES = ["resolved", "abandoned", "superseded"];
   }
 });
 
@@ -1441,12 +1447,13 @@ 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_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, isLiveDecision2, 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";
     init_dist();
     VALID_TRANSITIONS2 = VALID_TRANSITIONS;
+    isLiveDecision2 = isLiveDecision;
     TASK_TYPE_TIERS = {
       bug: 1,
       task: 1,
@@ -1557,11 +1564,18 @@ ${TABLE_SEPARATOR}
       async getCycleHealth() {
         return parseCycleHealth(await this.read("PLANNING_LOG.md"));
       }
-      /** Read all Active Decisions from ACTIVE_DECISIONS.md. */
-      async getActiveDecisions() {
+      /**
+       * Read Active Decisions from ACTIVE_DECISIONS.md.
+       *
+       * Default filters out retired ADs (outcome ∈ abandoned/superseded/resolved or superseded=true).
+       * Pass { includeRetired: true } for management/triage surfaces. See PapiAdapter docstring.
+       */
+      async getActiveDecisions(options) {
         const content = await this.readOptional("ACTIVE_DECISIONS.md");
         if (!content) return [];
-        return parseActiveDecisions(content);
+        const all = parseActiveDecisions(content);
+        if (options?.includeRetired) return all;
+        return all.filter(isLiveDecision2);
       }
       /** Read cycle log entries (newest first), optionally limited to {@link limit} entries. */
       async getCycleLog(limit) {
@@ -6352,11 +6366,31 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
           lastFullMode: 0
         };
       }
-      async getActiveDecisions() {
+      /**
+       * Read Active Decisions for this project.
+       *
+       * Default filters out retired ADs (outcome ∈ abandoned/superseded/resolved or superseded=true).
+       * Pass { includeRetired: true } for management/triage surfaces. See PapiAdapter docstring.
+       *
+       * task-1546 (C242 hot-fix): closes the bug where retired ADs leaked into context surfaces.
+       */
+      async getActiveDecisions(options) {
+        if (options?.includeRetired) {
+          const rows2 = await this.sql`
+        SELECT id, display_id, title, confidence, superseded, superseded_by, created_cycle, modified_cycle, body, outcome, revision_count
+        FROM active_decisions
+        WHERE project_id = ${this.projectId}
+        ORDER BY display_id
+        LIMIT 200
+      `;
+          return rows2.map(rowToActiveDecision);
+        }
         const rows = await this.sql`
       SELECT id, display_id, title, confidence, superseded, superseded_by, created_cycle, modified_cycle, body, outcome, revision_count
       FROM active_decisions
       WHERE project_id = ${this.projectId}
+        AND superseded = false
+        AND (outcome IS NULL OR outcome NOT IN ('abandoned', 'superseded', 'resolved'))
       ORDER BY display_id
       LIMIT 200 -- bounded: ADs are bounded by project lifecycle, 200 is a safe ceiling
     `;
@@ -6699,6 +6733,25 @@ ${newParts.join("\n")}` : newParts.join("\n");
           superseded_by = ${supersededBy ?? null},
           updated_at = now()
       WHERE id = ${id} AND project_id = ${this.projectId}
+    `;
+      }
+      async updateDocAction(docId, actionIndex, update) {
+        const doc = await this.getDoc(docId);
+        if (!doc) throw new Error(`Doc not found: ${docId}`);
+        const actions = [...doc.actions ?? []];
+        if (actionIndex < 0 || actionIndex >= actions.length) {
+          throw new Error(`Action index ${actionIndex} out of range (doc has ${actions.length} action(s))`);
+        }
+        actions[actionIndex] = {
+          ...actions[actionIndex],
+          ...update.status !== void 0 ? { status: update.status } : {},
+          ...update.linkedTaskId !== void 0 ? { linkedTaskId: update.linkedTaskId } : {}
+        };
+        await this.sql`
+      UPDATE doc_registry
+      SET actions = ${this.sql.json(actions)},
+          updated_at = now()
+      WHERE id = ${doc.id} AND project_id = ${this.projectId}
     `;
       }
       async writeDogfoodEntries(entries) {
@@ -7573,7 +7626,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
         const rows = await this.sql`
       SELECT id, slug, label, description, status, sort_order, horizon_id, project_id, exit_criteria, created_at, updated_at
       FROM stages
-      WHERE project_id = ${this.projectId} AND status = 'Active'
+      WHERE project_id = ${this.projectId} AND status = 'In Progress'
       ORDER BY sort_order
       LIMIT 1
     `;
@@ -8575,8 +8628,8 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       getCycleHealth() {
         return this.invoke("getCycleHealth");
       }
-      getActiveDecisions() {
-        return this.invoke("getActiveDecisions");
+      getActiveDecisions(options) {
+        return this.invoke("getActiveDecisions", [options ?? {}]);
       }
       getCycleLog(limit) {
         return this.invoke("getCycleLog", [limit]);
@@ -9452,9 +9505,9 @@ var init_git = __esm({
 });
 
 // src/index.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 import { createServer as createHttpServer } from "http";
-import { dirname as dirname2, join as join13 } from "path";
+import { dirname as dirname2, join as join14 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -9741,9 +9794,9 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
 }
 
 // src/server.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { access as access4, readdir as readdir2, readFile as readFile5 } from "fs/promises";
-import { join as join12, dirname } from "path";
+import { join as join13, dirname } from "path";
 import { fileURLToPath } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -10535,6 +10588,20 @@ async function sendSlackWebhook(webhookUrl, summary, header = "PAPI Strategy Rev
 }
 
 // src/prompts.ts
+var AD_REJECTION_RULES = `**AD Minting Guard \u2014 REJECT observations dressed as decisions.**
+
+An Active Decision expresses a *stance* the project is taking \u2014 a choice between alternatives that constrains future work. Reject any candidate AD whose body asserts:
+(a) the existence, identity, or status of a person, user, or external entity (e.g. "User X is building Y", "Customer Z is active");
+(b) a metric or measurement (e.g. "Signups grew 3x last cycle", "Latency dropped to 200ms");
+(c) a fact about the current state of the world that could be confirmed or denied by a query rather than challenged by argument (e.g. "External user feedback is now flowing", "The /admin route exists").
+
+If a candidate AD body could be invalidated by running a SQL query, refreshing a dashboard, or checking a log \u2014 it is an observation, not a decision. Capture it as a build report finding, a dogfood observation, a cycle log note, or a registered doc instead. Do NOT mint it as an AD.
+
+**Positive example (valid AD):** "Pricing tier strategy: free engine + paid intelligence. Decision: keep cycles free, charge for strategy reviews and analytics. Why: telemetry shows engagement clusters around intelligence surfaces, not engine surfaces." \u2014 this is a stance with alternatives.
+
+**Negative example (reject):** "External user feedback is now flowing. Stonebridge Systems is actively building." \u2014 this is a fact about the current state of the world. Capture as dogfood/signal observation; do not mint.
+
+This rule applies to: new ADs proposed during planning (Step 9), strategy review AD updates (section 5), and strategy_change AD updates. If you find an existing AD that violates this rule during housekeeping, propose deleting it (action: "delete") with a one-line rationale.`;
 var PLAN_SYSTEM = `You are the PAPI Cycle Planner \u2014 an autonomous planning engine for software projects.
 You receive project context and produce a planning cycle output with a BUILD HANDOFF.
 
@@ -10715,6 +10782,7 @@ Standard planning cycle with full board review.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
    **\u26A0\uFE0F PRIORITY RECALIBRATION \u2014 do NOT rubber-stamp the submitted priority.** The priority set at idea submission reflects the submitter's view at that time, which may be outdated by the time the planner runs. For EVERY unreviewed task, evaluate its priority FROM SCRATCH against: (a) current horizon/stage/phase goals, (b) recent Active Decision changes, (c) recently shipped functionality that makes this task more or less urgent. If your assessed priority differs from the submitted one, set the new priority in \`boardCorrections\` and include the change in a **Priority Recalibration** paragraph in your cycle log (Step 8): list each changed task by ID, old priority \u2192 new priority, and a 1-sentence rationale. This paragraph is how the user sees what the planner recalibrated and why. If no priorities changed during triage, omit the paragraph.
    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.
+   **Module classification for cross-cutting tasks:** When a task title contains "audit"/"unfiltered"/"scoping"/"leak" plus a database-entity name (e.g. "audit ... cycle_learnings reads", "unfiltered cycle_tasks queries"), classify the module by the actual code surface that reads/writes the entity \u2014 not by the tool names mentioned in the title. The reasoning surface (e.g. "health" or "strategy_review") is often unrelated to the data-access surface. Resolve this by treating the entity name as the routing signal: tasks touching dashboard read/write paths belong to the Dashboard module even if the title mentions an MCP tool. Misclassification routes the task to the wrong shared cycle branch and surfaces the wrong MODULE INSTRUCTIONS to the builder.
    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.
 
@@ -10760,6 +10828,9 @@ Standard planning cycle with full board review.
 
 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.
+
+${AD_REJECTION_RULES}
+
    **\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
@@ -10950,6 +11021,7 @@ Standard planning cycle with full board review.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
    **\u26A0\uFE0F PRIORITY RECALIBRATION \u2014 do NOT rubber-stamp the submitted priority.** The priority set at idea submission reflects the submitter's view at that time, which may be outdated by the time the planner runs. For EVERY unreviewed task, evaluate its priority FROM SCRATCH against: (a) current horizon/stage/phase goals, (b) recent Active Decision changes, (c) recently shipped functionality that makes this task more or less urgent. If your assessed priority differs from the submitted one, set the new priority in \`boardCorrections\` and include the change in a **Priority Recalibration** paragraph in your cycle log (Step 8): list each changed task by ID, old priority \u2192 new priority, and a 1-sentence rationale. This paragraph is how the user sees what the planner recalibrated and why. If no priorities changed during triage, omit the paragraph.
    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.
+   **Module classification for cross-cutting tasks:** When a task title contains "audit"/"unfiltered"/"scoping"/"leak" plus a database-entity name (e.g. "audit ... cycle_learnings reads", "unfiltered cycle_tasks queries"), classify the module by the actual code surface that reads/writes the entity \u2014 not by the tool names mentioned in the title. The reasoning surface (e.g. "health" or "strategy_review") is often unrelated to the data-access surface. Resolve this by treating the entity name as the routing signal: tasks touching dashboard read/write paths belong to the Dashboard module even if the title mentions an MCP tool. Misclassification routes the task to the wrong shared cycle branch and surfaces the wrong MODULE INSTRUCTIONS to the builder.
    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.
 
@@ -10997,6 +11069,9 @@ Standard planning cycle with full board review.
 
 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.
+
+${AD_REJECTION_RULES}
+
    **\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
@@ -11161,6 +11236,16 @@ function buildPlanUserMessage(ctx) {
     if (ctx.registeredDocs) {
       parts.push("### Relevant Research Docs", "", ctx.registeredDocs, "");
     }
+    if (ctx.unactionedDocs) {
+      parts.push(
+        "### Unactioned Research (soft-warn)",
+        "",
+        "These registered docs still have pending actions. Before adding net-new tasks, consider whether one of these unactioned items should be promoted into this cycle via `doc_action_promote`. Surface this in your plan output so the user can decide.",
+        "",
+        ctx.unactionedDocs,
+        ""
+      );
+    }
     if (ctx.carryForwardStaleness) {
       parts.push("### Carry-Forward Staleness", "", ctx.carryForwardStaleness, "");
     }
@@ -11369,8 +11454,17 @@ You MUST cover these 5 sections. Each is mandatory.
    - Note any hierarchy/phase issues worth correcting (1-2 bullets max)
    - Delete ADs that are legacy, process-level, or redundant without discussion
 
+${AD_REJECTION_RULES}
+
 **Registered Documents:** If a "### Registered Documents" section is present in context, scan it for: (a) research findings that contradict current ADs or strategy, (b) unactioned research that should influence the next plan. Reference relevant docs by title in your review. If unregistered docs are listed, flag 1-2 that look strategically relevant and suggest registering them.
 
+**Doc Action Staleness:** If a "### Doc Action Staleness" section is present, treat it as a research-to-action audit. For each entry:
+- **Stale** (no Done task, >20 cycles old): explicitly call it out in section 2 (Product Gaps) or 3 (Opportunities) \u2014 research that's been sitting unactioned this long is either (a) no longer relevant (recommend marking the doc archived) or (b) silently dropped (recommend promoting via \`doc_action_promote\` into the next plan).
+- **Completed but not closed** (linked task is Done): instruct in your review that the action should be marked resolved \u2014 it's done work the registry hasn't caught up to.
+- **Deferred** (<20 cycles, no matching Done task): only mention if it relates to a current strategic theme; otherwise leave it.
+
+For every stale or unresolved item you call out, propose a concrete next step (promote, archive, or supersede) \u2014 don't just observe.
+
 ## CONDITIONAL SECTIONS (include only when genuinely useful \u2014 most reviews should have 0-2 of these)
 
 6. **Security Posture Review** \u2014 Only if \`[SECURITY]\` tags exist in recent cycle logs.
@@ -11678,6 +11772,8 @@ The JSON must be valid. Only include ADs that need changes \u2014 omit unchanged
 For new ADs, use the next available AD number.
 The body field must be the COMPLETE replacement text for the AD block (including the ### heading line).
 
+${AD_REJECTION_RULES}
+
 ## PHASE UPDATES
 
 If the strategic change affects the project's phase structure, include a phaseUpdates array.
@@ -12050,6 +12146,7 @@ function applyContextTier(ctx, cycleCount) {
     ctx.reviewPatterns = void 0;
     ctx.horizonContext = void 0;
     ctx.registeredDocs = void 0;
+    ctx.unactionedDocs = void 0;
     ctx.recentReviews = void 0;
     ctx.strategyReviewCadence = void 0;
   }
@@ -12219,6 +12316,32 @@ function formatStrategyRecommendations(recs, currentCycle) {
   }
   return sections.join("\n");
 }
+function formatUnactionedDocs(docs) {
+  const withPending = docs.map((d) => ({
+    doc: d,
+    pending: (d.actions ?? []).filter((a) => a.status === "pending")
+  })).filter((entry) => entry.pending.length > 0);
+  if (withPending.length === 0) return void 0;
+  const MAX_DOCS = 3;
+  const MAX_ACTIONS_PER_DOC = 2;
+  const top = withPending.slice(0, MAX_DOCS);
+  const lines = [];
+  for (const { doc, pending } of top) {
+    const cycleLabel = `C${doc.cycleUpdated ?? doc.cycleCreated ?? "?"}`;
+    lines.push(`- **${doc.title}** (${doc.path}) [${cycleLabel}, ${pending.length} pending]`);
+    for (const action of pending.slice(0, MAX_ACTIONS_PER_DOC)) {
+      const desc = action.description.length > 100 ? `${action.description.slice(0, 97)}\u2026` : action.description;
+      lines.push(`  \u2192 ${desc}`);
+    }
+    if (pending.length > MAX_ACTIONS_PER_DOC) {
+      lines.push(`  \u2192 \u2026and ${pending.length - MAX_ACTIONS_PER_DOC} more`);
+    }
+  }
+  if (withPending.length > MAX_DOCS) {
+    lines.push(`_\u2026and ${withPending.length - MAX_DOCS} more doc(s) with pending actions._`);
+  }
+  return lines.join("\n");
+}
 function formatEstimationCalibration(rows) {
   const total = rows.reduce((sum, r) => sum + r.count, 0);
   const accurate = rows.filter((r) => r.accuracyLabel === "accurate").reduce((sum, r) => sum + r.count, 0);
@@ -12558,11 +12681,13 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
       }
     }
     let registeredDocsText;
+    let unactionedDocsTextLean;
     if (docsResult.status === "fulfilled" && docsResult.value && docsResult.value.length > 0) {
       const docs = docsResult.value;
       const lines = docs.map((d) => `- **${d.title}** (${d.type}) \u2014 ${d.summary}`);
       registeredDocsText = `${docs.length} active research doc(s):
 ${lines.join("\n")}`;
+      unactionedDocsTextLean = formatUnactionedDocs(docs);
     }
     const boardFlags = detectBoardFlagsFromText(leanSummary.board);
     let carryForwardStalenessLean;
@@ -12614,6 +12739,7 @@ ${lines.join("\n")}`;
       discoveryCanvas: discoveryCanvasText,
       estimationCalibration: estimationCalibrationText,
       registeredDocs: registeredDocsText,
+      unactionedDocs: unactionedDocsTextLean,
       focus,
       boardFlags,
       carryForwardStaleness: carryForwardStalenessLean,
@@ -12691,9 +12817,24 @@ ${lines.join("\n")}`;
   const metricsSnapshots = filteredRaw.length > 0 ? filteredRaw : computeSnapshotsFromBuildReports(allReportsForPatterns);
   const discoveryCanvasTextFull = discoveryCanvasResultFull.status === "fulfilled" ? discoveryCanvasResultFull.value : void 0;
   const taskCommentsTextFull = taskCommentsResultFull.status === "fulfilled" ? taskCommentsResultFull.value : void 0;
+  const strippedTasks = stripTasksForPlan(tasks);
+  const boardFlagsFull = detectBoardFlags(tasks);
+  const horizonCtx = buildHorizonContext(phases, tasks) ?? void 0;
+  const ACTIVE_STATUSES2 = /* @__PURE__ */ new Set(["In Progress", "In Review", "Blocked"]);
+  const p3Excluded = strippedTasks.filter(
+    (t2) => t2.priority === "P3 Low" && !ACTIVE_STATUSES2.has(t2.status)
+  );
+  const plannerTasks = strippedTasks.filter(
+    (t2) => t2.priority !== "P3 Low" || ACTIVE_STATUSES2.has(t2.status)
+  );
+  if (p3Excluded.length > 0) {
+    console.error(`[plan-perf] board tiering: excluded ${p3Excluded.length} P3 Low tasks from planner context`);
+  }
   let registeredDocsTextFull;
+  let unactionedDocsTextFull;
   if (docsResultFull.status === "fulfilled" && docsResultFull.value && docsResultFull.value.length > 0) {
     const allDocs = docsResultFull.value;
+    unactionedDocsTextFull = formatUnactionedDocs(allDocs);
     const taskModules = new Set(plannerTasks.map((t2) => t2.module?.toLowerCase()).filter(Boolean));
     const taskEpics = new Set(plannerTasks.map((t2) => t2.epic?.toLowerCase()).filter(Boolean));
     const HIGH_VALUE_TYPES = /* @__PURE__ */ new Set(["architecture", "guide", "research"]);
@@ -12739,19 +12880,6 @@ ${logLines}`);
     const filtered = reports.filter((r) => (r.cycle ?? 0) >= cutoff);
     return filtered.length > 0 ? filtered : reports.slice(0, 5);
   })() : reports;
-  const strippedTasks = stripTasksForPlan(tasks);
-  const boardFlagsFull = detectBoardFlags(tasks);
-  const horizonCtx = buildHorizonContext(phases, tasks) ?? void 0;
-  const ACTIVE_STATUSES2 = /* @__PURE__ */ new Set(["In Progress", "In Review", "Blocked"]);
-  const p3Excluded = strippedTasks.filter(
-    (t2) => t2.priority === "P3 Low" && !ACTIVE_STATUSES2.has(t2.status)
-  );
-  const plannerTasks = strippedTasks.filter(
-    (t2) => t2.priority !== "P3 Low" || ACTIVE_STATUSES2.has(t2.status)
-  );
-  if (p3Excluded.length > 0) {
-    console.error(`[plan-perf] board tiering: excluded ${p3Excluded.length} P3 Low tasks from planner context`);
-  }
   const targetCycle = health.totalCycles + 1;
   const preAssigned = plannerTasks.filter((t2) => t2.cycle === targetCycle);
   const preAssignedText = formatPreAssignedTasks(preAssigned, targetCycle);
@@ -12777,6 +12905,7 @@ ${logLines}`);
     taskComments: taskCommentsTextFull,
     discoveryCanvas: discoveryCanvasTextFull,
     registeredDocs: registeredDocsTextFull,
+    unactionedDocs: unactionedDocsTextFull,
     focus,
     boardFlags: boardFlagsFull,
     carryForwardStaleness: computeCarryForwardStaleness(log),
@@ -13736,17 +13865,19 @@ async function handlePlan(adapter2, config2, args) {
       const expectedCycleNumber = lastPrepareCycleNumber;
       const skipHandoffsCached = lastPrepareSkipHandoffs;
       const skipHandoffs = args.skip_handoffs === true || skipHandoffsCached === true;
-      const cycleNumber = !isNaN(rawCycleNumber) ? rawCycleNumber : expectedCycleNumber !== void 0 ? expectedCycleNumber : NaN;
-      if (isNaN(cycleNumber)) {
+      const expectedNewCycleNumber = expectedCycleNumber !== void 0 ? expectedCycleNumber + 1 : void 0;
+      const newCycleNumber = !isNaN(rawCycleNumber) ? rawCycleNumber : expectedNewCycleNumber !== void 0 ? expectedNewCycleNumber : NaN;
+      if (isNaN(newCycleNumber)) {
         return errorResponse(
           "cycle_number is required for apply mode. Pass the cycle_number from the prepare phase output."
         );
       }
-      if (expectedCycleNumber !== void 0 && cycleNumber !== expectedCycleNumber) {
+      if (expectedNewCycleNumber !== void 0 && newCycleNumber !== expectedNewCycleNumber) {
         return errorResponse(
-          `cycle_number mismatch: prepare phase returned cycle ${expectedCycleNumber} but apply received ${cycleNumber}. Pass cycle_number: ${expectedCycleNumber} to match the prepare output.`
+          `cycle_number mismatch: prepare phase is for cycle ${expectedNewCycleNumber} but apply received ${newCycleNumber}. Pass cycle_number: ${expectedNewCycleNumber} to match the prepare output.`
         );
       }
+      const cycleNumber = newCycleNumber - 1;
       lastPrepareContextHashes = void 0;
       lastPrepareUserMessage = void 0;
       lastPrepareContextBytes = void 0;
@@ -13800,7 +13931,7 @@ When done, call \`plan\` again with:
 - \`mode\`: "apply"
 - \`llm_response\`: your complete output (both parts)
 - \`plan_mode\`: "${result.mode}"
-- \`cycle_number\`: ${result.cycleNumber}
+- \`cycle_number\`: ${result.cycleNumber + 1}
 - \`strategy_review_warning\`: "${result.strategyReviewWarning.replace(/"/g, '\\"')}"
 
 ---
@@ -14140,7 +14271,8 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     docsWithPendingActions
   ] = await Promise.all([
     adapter2.readProductBrief(),
-    adapter2.getActiveDecisions(),
+    // Strategy review needs to see retired ADs to triage/restore them as needed.
+    adapter2.getActiveDecisions({ includeRetired: true }),
     adapter2.getBuildReportsSince(lastReviewCycleNum),
     adapter2.getCycleLogSince(lastReviewCycleNum),
     adapter2.queryBoard({
@@ -14642,7 +14774,7 @@ ${cleanContent}`;
   try {
     const recs = extractRecommendations(data, cycleNumber);
     if (recs.length > 0) {
-      const existingAds = await adapter2.getActiveDecisions().catch(() => []);
+      const existingAds = await adapter2.getActiveDecisions({ includeRetired: true }).catch(() => []);
       const existingAdIds = new Set(existingAds.map((ad) => ad.id));
       const filteredRecs = recs.filter((rec) => {
         if (rec.target && /^AD-\d+$/.test(rec.target)) {
@@ -15176,7 +15308,8 @@ async function prepareStrategyChange(adapter2, text) {
   try {
     const [brief, decisions, readPhases, boardTasks, reports, previousReviews] = await Promise.all([
       adapter2.readProductBrief(),
-      adapter2.getActiveDecisions(),
+      // Strategy review needs ALL ADs (live + retired) for housekeeping.
+      adapter2.getActiveDecisions({ includeRetired: true }),
       adapter2.readPhases(),
       adapter2.queryBoard().catch(() => []),
       adapter2.getRecentBuildReports(15).catch(() => []),
@@ -15221,7 +15354,7 @@ async function captureDecision(adapter2, input) {
     adId = input.adId;
     adAction = "updated";
   } else {
-    const existingAds = await adapter2.getActiveDecisions();
+    const existingAds = await adapter2.getActiveDecisions({ includeRetired: true });
     const maxNum = existingAds.reduce((max, ad) => {
       const match = ad.id.match(/^AD-(\d+)$/);
       return match ? Math.max(max, parseInt(match[1], 10)) : max;
@@ -17638,6 +17771,23 @@ function isNoHandoffError(err) {
 function isBlockedError(err) {
   return err instanceof Error && err.code === "BLOCKED";
 }
+function computeScopeDriftSignal(predicted, changed) {
+  if (!predicted || predicted.length === 0) return null;
+  if (changed.length === 0) return null;
+  const basename2 = (p) => {
+    const parts = p.split(/[\\/]/);
+    return parts[parts.length - 1] ?? p;
+  };
+  const predictedNames = new Set(predicted.map(basename2).filter(Boolean));
+  const unexpected = changed.filter((c) => !predictedNames.has(basename2(c)));
+  const fraction = unexpected.length / changed.length;
+  const triggered = fraction > 0.5 || unexpected.length > 5;
+  if (!triggered) return null;
+  const sample = unexpected.slice(0, 5).join(", ");
+  const more = unexpected.length > 5 ? ` (+${unexpected.length - 5} more)` : "";
+  const pct = Math.round(fraction * 100);
+  return `${unexpected.length}/${changed.length} changed files (${pct}%) outside FILES LIKELY TOUCHED: ${sample}${more}`;
+}
 function getUnresolvedDeps(task, allTasks) {
   if (!task.dependsOn) return [];
   const deps = task.dependsOn.split(",").map((d) => d.trim()).filter(Boolean);
@@ -17699,6 +17849,11 @@ async function startBuild(adapter2, config2, taskId, options = {}) {
   if (task.status === "Done" || task.status === "Archived") {
     throw new Error(`Task "${taskId}" (${task.title}) is already ${task.status}. Cannot execute a completed task.`);
   }
+  if (task.status === "In Review") {
+    throw new Error(
+      `Task "${taskId}" (${task.title}) is already In Review \u2014 it has been built and is awaiting sign-off. Run \`review_submit\` instead of re-building. If the build genuinely needs rework, use \`review_submit\` with verdict \`request-changes\` first.`
+    );
+  }
   if (!task.buildHandoff) {
     const err = new Error(`Task "${taskId}" (${task.title}) has no BUILD HANDOFF.`);
     err.code = "NO_HANDOFF";
@@ -18099,6 +18254,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     const baseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
     const changed = getFilesChangedFromBase(config2.projectRoot, baseBranch);
     if (changed.length > 0) report.filesChanged = changed;
+    const drift = computeScopeDriftSignal(task.buildHandoff?.filesLikelyTouched, changed);
+    if (drift) report.scopeDriftSignal = drift;
   }
   let prLines = [];
   if (options.light) {
@@ -18619,8 +18776,20 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
   const correctionsCount = args.corrections_count;
   const deadEnds = args.dead_ends;
   const rawBriefImplications = args.brief_implications;
-  if (!completed || !effort || !estimatedEffort || !surprises || !discoveredIssues || !architectureNotes) {
-    return errorResponse("build_execute with report data requires all fields \u2014 completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes.");
+  const reportFieldChecks = [
+    ["completed", completed],
+    ["effort", effort],
+    ["estimated_effort", estimatedEffort],
+    ["surprises", surprises],
+    ["discovered_issues", discoveredIssues],
+    ["architecture_notes", architectureNotes]
+  ];
+  const missing = reportFieldChecks.filter(([, v]) => !v).map(([k]) => k);
+  if (missing.length > 0) {
+    const sizes = reportFieldChecks.map(([k, v]) => `${k}=${v === void 0 ? "undefined" : v.length}`).join(", ");
+    return errorResponse(
+      `build_execute with report data is missing required field(s): ${missing.join(", ")}. If you sent values for these, the transport may have dropped them \u2014 re-send with shorter content for the affected field(s) or split the report. Field sizes (chars): ${sizes}.`
+    );
   }
   const parsedEffort = parseEffortSize(effort);
   const parsedEstimatedEffort = parseEffortSize(estimatedEffort);
@@ -18669,6 +18838,7 @@ function formatCompleteResult(result) {
     `**Discovered Issues:** ${result.report.discoveredIssues}`,
     `**Architecture Notes:** ${result.report.architectureNotes}`,
     ...result.report.deadEnds ? [`**Dead Ends:** ${result.report.deadEnds}`] : [],
+    ...result.report.scopeDriftSignal ? [`**Scope drift signal:** ${result.report.scopeDriftSignal}`] : [],
     `**Scope Accuracy:** ${result.scopeAccuracy}`,
     "",
     "---",
@@ -21365,7 +21535,7 @@ ${lines.join("\n")}`;
   }
   let decisionLifecycleSection = "";
   try {
-    const decisions = await adapter2.getActiveDecisions();
+    const decisions = await adapter2.getActiveDecisions({ includeRetired: true });
     const lifecycleSummary = formatDecisionLifecycleSummary(decisions);
     if (lifecycleSummary) {
       decisionLifecycleSection = `**Lifecycle:** ${lifecycleSummary}`;
@@ -21431,10 +21601,117 @@ ${lines.join("\n")}`;
 // src/tools/orient.ts
 init_git();
 
+// src/lib/skill-detection.ts
+import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync2, statSync as statSync3 } from "fs";
+import { join as join8 } from "path";
+function readPackageJson(projectRoot) {
+  const path5 = join8(projectRoot, "package.json");
+  if (!existsSync5(path5)) return null;
+  try {
+    const raw = readFileSync2(path5, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function allDeps(pkg) {
+  if (!pkg) return {};
+  return { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+}
+function hasDependencyMatching(deps, pattern) {
+  for (const name of Object.keys(deps)) {
+    if (pattern.test(name)) return true;
+  }
+  return false;
+}
+function hasGitHubWorkflows(projectRoot) {
+  const dir = join8(projectRoot, ".github", "workflows");
+  if (!existsSync5(dir)) return false;
+  try {
+    const entries = readdirSync4(dir);
+    return entries.some((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+  } catch {
+    return false;
+  }
+}
+function envExampleMentionsStaging(projectRoot) {
+  const path5 = join8(projectRoot, ".env.example");
+  if (!existsSync5(path5)) return false;
+  try {
+    const raw = readFileSync2(path5, "utf-8");
+    return /\b(STAGING_URL|STAGING_API|STAGING_HOST|NEXT_PUBLIC_STAGING)/i.test(raw);
+  } catch {
+    return false;
+  }
+}
+function hasVercelConfig(projectRoot) {
+  if (existsSync5(join8(projectRoot, "vercel.json"))) return true;
+  const vercelDir = join8(projectRoot, ".vercel");
+  if (!existsSync5(vercelDir)) return false;
+  try {
+    return statSync3(vercelDir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function scanForSkillSignals(projectRoot) {
+  const proposals = [];
+  const pkg = readPackageJson(projectRoot);
+  const deps = allDeps(pkg);
+  if (hasGitHubWorkflows(projectRoot)) {
+    proposals.push({
+      id: "gh-actions-debug",
+      name: "GitHub Actions debugger",
+      rationale: "Detected .github/workflows/ \u2014 a skill for inspecting CI failures and re-running jobs from Claude Code can shorten the debug loop.",
+      hint: 'Search Claude Code skill registry for "gh-actions" or install via `claude skills add gh-actions-debug`.'
+    });
+  }
+  if (hasDependencyMatching(deps, /^@sentry\//) || hasDependencyMatching(deps, /^@datadog\//)) {
+    proposals.push({
+      id: "error-tracking",
+      name: "Error tracking helper",
+      rationale: "Detected @sentry/* or @datadog/* in package.json \u2014 a skill that fetches recent error events into your context can speed up triage.",
+      hint: 'Search Claude Code skill registry for "sentry" or "datadog".'
+    });
+  }
+  if (hasVercelConfig(projectRoot)) {
+    proposals.push({
+      id: "read-vercel-logs",
+      name: "Vercel deploy logs",
+      rationale: "Detected vercel.json or .vercel/ \u2014 a skill for pulling deploy + runtime logs from Vercel directly into Claude Code helps when builds fail or runtime errors land.",
+      hint: 'Search Claude Code skill registry for "vercel" or install `vercel:logs`.'
+    });
+  }
+  if (envExampleMentionsStaging(projectRoot)) {
+    proposals.push({
+      id: "staging-environment",
+      name: "Staging-environment helper",
+      rationale: "Detected STAGING_* variables in .env.example \u2014 a skill for switching env contexts and seeding staging data can speed up pre-prod testing.",
+      hint: 'Search Claude Code skill registry for "staging" or define your own.'
+    });
+  }
+  return proposals;
+}
+function formatSkillProposals(proposals) {
+  if (proposals.length === 0) return "";
+  const lines = ["", "## Skill proposals", "_PAPI scanned your project once and noticed tooling that often pairs with a Claude Code skill. Each proposal is one-shot \u2014 they won't resurface._"];
+  for (const p of proposals) {
+    lines.push("");
+    lines.push(`### ${p.name}`);
+    lines.push(p.rationale);
+    if (p.hint) {
+      lines.push(`_${p.hint}_`);
+    }
+    lines.push("**[Yes]** install it now \xB7 **[Not now]** dismiss for this project");
+  }
+  return "\n" + lines.join("\n");
+}
+
 // src/tools/doc-registry.ts
-import { readdirSync as readdirSync4, existsSync as existsSync5, readFileSync as readFileSync2 } from "fs";
-import { join as join8, relative } from "path";
+import { readdirSync as readdirSync5, existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
+import { join as join9, relative } from "path";
 import { homedir as homedir2 } from "os";
+import { randomUUID as randomUUID15 } from "crypto";
 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.",
@@ -21577,12 +21854,12 @@ ${d.summary}
 ${lines.join("\n---\n\n")}`);
 }
 function scanMdFiles(dir, rootDir) {
-  if (!existsSync5(dir)) return [];
+  if (!existsSync6(dir)) return [];
   const files = [];
   try {
-    const entries = readdirSync4(dir, { withFileTypes: true });
+    const entries = readdirSync5(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const full = join8(dir, entry.name);
+      const full = join9(dir, entry.name);
       if (entry.isDirectory()) {
         files.push(...scanMdFiles(full, rootDir));
       } else if (entry.name.endsWith(".md")) {
@@ -21595,7 +21872,7 @@ function scanMdFiles(dir, rootDir) {
 }
 function extractTitle(filePath) {
   try {
-    const content = readFileSync2(filePath, "utf-8").slice(0, 1e3);
+    const content = readFileSync3(filePath, "utf-8").slice(0, 1e3);
     const fmMatch = content.match(/^---[\s\S]*?title:\s*(.+?)$/m);
     if (fmMatch) return fmMatch[1].trim().replace(/^["']|["']$/g, "");
     const headingMatch = content.match(/^#+\s+(.+)$/m);
@@ -21611,17 +21888,17 @@ async function handleDocScan(adapter2, config2, args) {
   const includePlans = args.include_plans ?? false;
   const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
   const registeredPaths = new Set(registered.map((d) => d.path));
-  const docsDir = join8(config2.projectRoot, "docs");
+  const docsDir = join9(config2.projectRoot, "docs");
   const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
   const unregisteredDocs = docsFiles.filter((f) => !registeredPaths.has(f));
   let unregisteredPlans = [];
   if (includePlans) {
-    const plansDir = join8(homedir2(), ".claude", "plans");
-    if (existsSync5(plansDir)) {
+    const plansDir = join9(homedir2(), ".claude", "plans");
+    if (existsSync6(plansDir)) {
       const planFiles = scanMdFiles(plansDir, plansDir);
       unregisteredPlans = planFiles.map((f) => `plans/${f}`).filter((f) => !registeredPaths.has(f)).map((f) => ({
         path: f,
-        title: extractTitle(join8(plansDir, f.replace("plans/", "")))
+        title: extractTitle(join9(plansDir, f.replace("plans/", "")))
       }));
     }
   }
@@ -21632,7 +21909,7 @@ async function handleDocScan(adapter2, config2, args) {
   if (unregisteredDocs.length > 0) {
     lines.push(`## Unregistered Docs (${unregisteredDocs.length})`);
     for (const f of unregisteredDocs) {
-      const title = extractTitle(join8(config2.projectRoot, f));
+      const title = extractTitle(join9(config2.projectRoot, f));
       lines.push(`- \`${f}\`${title ? ` \u2014 ${title}` : ""}`);
     }
   }
@@ -21645,10 +21922,106 @@ async function handleDocScan(adapter2, config2, args) {
   lines.push("", `Use \`doc_register\` to register these files.`);
   return textResponse(lines.join("\n"));
 }
+var docActionPromoteTool = {
+  name: "doc_action_promote",
+  description: "Promote a single pending action from a registered doc into a Backlog task. The new task gets a `Reference:` line pointing to the source doc, and the doc action is marked resolved with `linkedTaskId` set. Use to close the research-to-action loop \u2014 turn unactioned findings into trackable cycle work. Identify the doc by `doc_path` (preferred) or `doc_id`, and the action by 0-based `action_index` (as listed in `doc_search` output).",
+  annotations: { readOnlyHint: false, destructiveHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      doc_path: { type: "string", description: 'Path of the source doc (e.g. "docs/research/funding-landscape.md"). Either this or doc_id is required.' },
+      doc_id: { type: "string", description: "UUID of the source doc. Either this or doc_path is required." },
+      action_index: { type: "number", description: "0-based index of the action in the doc's actions array." },
+      title: { type: "string", description: "Optional task title override. Defaults to the action description (truncated)." },
+      priority: { type: "string", enum: ["P0 Critical", "P1 High", "P2 Medium", "P3 Low"], description: 'Task priority. Defaults to "P2 Medium".' },
+      complexity: { type: "string", enum: ["XS", "Small", "Medium", "Large", "XL"], description: 'Task complexity. Defaults to "Small".' },
+      module: { type: "string", description: 'Task module. Defaults to "Core".' },
+      epic: { type: "string", description: 'Task epic. Defaults to "Platform".' },
+      notes: { type: "string", description: "Additional notes. A `Reference:` line pointing at the source doc is always prepended." }
+    },
+    required: ["action_index"]
+  }
+};
+async function handleDocActionPromote(adapter2, args) {
+  if (!adapter2.searchDocs || !adapter2.getDoc || !adapter2.updateDocAction) {
+    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+  }
+  const docPath = args.doc_path;
+  const docId = args.doc_id;
+  const actionIndex = args.action_index;
+  if (!docPath && !docId) {
+    return errorResponse("Either doc_path or doc_id is required.");
+  }
+  if (typeof actionIndex !== "number" || actionIndex < 0) {
+    return errorResponse("action_index is required and must be a non-negative number.");
+  }
+  const doc = await adapter2.getDoc(docId ?? docPath);
+  if (!doc) {
+    return errorResponse(`Doc not found: ${docId ?? docPath}`);
+  }
+  const actions = doc.actions ?? [];
+  if (actionIndex >= actions.length) {
+    return errorResponse(`action_index ${actionIndex} out of range \u2014 doc "${doc.title}" has ${actions.length} action(s).`);
+  }
+  const action = actions[actionIndex];
+  if (action.status === "resolved") {
+    return errorResponse(`Action ${actionIndex} on "${doc.title}" is already resolved${action.linkedTaskId ? ` (linked to ${action.linkedTaskId})` : ""}.`);
+  }
+  const VALID_PRIORITIES3 = /* @__PURE__ */ new Set(["P0 Critical", "P1 High", "P2 Medium", "P3 Low"]);
+  const VALID_COMPLEXITIES2 = /* @__PURE__ */ new Set(["XS", "Small", "Medium", "Large", "XL"]);
+  const priority = args.priority && VALID_PRIORITIES3.has(args.priority) ? args.priority : "P2 Medium";
+  const complexity = args.complexity && VALID_COMPLEXITIES2.has(args.complexity) ? args.complexity : "Small";
+  const taskModule = args.module || "Core";
+  const taskEpic = args.epic || "Platform";
+  const titleOverride = args.title?.trim();
+  const fallbackTitle = action.description.length > 100 ? `${action.description.slice(0, 97)}\u2026` : action.description;
+  const taskTitle = titleOverride || fallbackTitle;
+  const referenceLine = `Reference: ${doc.path}`;
+  const userNotes = args.notes?.trim();
+  const notes = userNotes ? `${referenceLine}
+
+${userNotes}` : referenceLine;
+  const phases = await adapter2.readPhases();
+  const phase = resolveCurrentPhase(phases);
+  const health = await adapter2.getCycleHealth();
+  const task = await adapter2.createTask({
+    uuid: randomUUID15(),
+    displayId: "",
+    title: taskTitle,
+    status: "Backlog",
+    priority,
+    complexity,
+    module: taskModule,
+    epic: taskEpic,
+    phase,
+    owner: "TBD",
+    reviewed: false,
+    createdCycle: health.totalCycles,
+    notes,
+    taskType: "task",
+    maturity: "raw",
+    docRef: doc.path,
+    source: "llm"
+  });
+  await adapter2.updateDocAction(doc.id, actionIndex, {
+    status: "resolved",
+    linkedTaskId: task.displayId || task.id
+  });
+  const remaining = actions.filter((a, i) => i !== actionIndex && a.status === "pending").length;
+  const remainingNote = remaining > 0 ? `${remaining} pending action(s) still on this doc.` : "All actions on this doc are now resolved.";
+  return textResponse(
+    `**Promoted action \u2192 ${task.displayId || task.id}**
+- **Source doc:** ${doc.title} (${doc.path})
+- **Action:** ${action.description}
+- **Task:** ${taskTitle} [${priority} | ${complexity}]
+- **Module/Epic:** ${taskModule} / ${taskEpic}
+- ${remainingNote}`
+  );
+}
 
 // src/services/session-guidance.ts
-import { existsSync as existsSync6 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { join as join10 } from "path";
 var state = {
   toolCallCount: 0,
   lastOrientAt: null,
@@ -21669,8 +22042,8 @@ async function buildSessionGuidance(adapter2, projectRoot) {
   const signals = [];
   try {
     if (adapter2.searchDocs) {
-      const researchDir = join9(projectRoot, "docs", "research");
-      if (existsSync6(researchDir)) {
+      const researchDir = join10(projectRoot, "docs", "research");
+      if (existsSync7(researchDir)) {
         const files = scanMdFiles(researchDir, projectRoot);
         if (files.length > 0) {
           const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
@@ -21707,8 +22080,8 @@ async function buildSessionGuidance(adapter2, projectRoot) {
 
 // src/tools/orient.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync7 } from "fs";
-import { join as join10 } from "path";
+import { readFileSync as readFileSync4, writeFileSync, existsSync as existsSync8 } from "fs";
+import { join as join11 } from "path";
 var GIT_DEPENDENT_ENVS = /* @__PURE__ */ new Set(["cowork", "api"]);
 var VALID_ENVS = /* @__PURE__ */ new Set(["claude-code", "cowork", "api", "unknown"]);
 function normaliseEnvironment(raw) {
@@ -21864,10 +22237,10 @@ async function getHierarchyPosition(adapter2) {
       adapter2.queryBoard()
     ]);
     if (horizons.length === 0) return void 0;
-    const isActive = (s) => s.status.toLowerCase() === "active";
-    const activeHorizon = horizons.find(isActive) || horizons[0];
+    const isInProgress = (s) => s.status === "In Progress";
+    const activeHorizon = horizons.find(isInProgress) || horizons[0];
     const horizonStages = stages.filter((s) => s.horizonId === activeHorizon.id).sort((a, b2) => (a.sortOrder ?? 0) - (b2.sortOrder ?? 0));
-    const activeStage = horizonStages.find(isActive) || horizonStages[0];
+    const activeStage = horizonStages.find(isInProgress) || horizonStages.find((s) => s.status !== "Done") || horizonStages[0];
     if (!activeStage) return void 0;
     const stagePhases = phases.filter((p) => p.stageId === activeStage.id);
     const activePhases = stagePhases.filter((p) => p.status === "In Progress");
@@ -21908,8 +22281,8 @@ function getLatestGitTag(projectRoot) {
 }
 function checkNpmVersionDrift() {
   try {
-    const pkgPath = join10(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    const pkgPath = join11(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
     const localVersion = pkg.version;
     const packageName = pkg.name;
     const published = execFileSync3("npm", ["view", packageName, "version"], {
@@ -21925,6 +22298,44 @@ function checkNpmVersionDrift() {
     return null;
   }
 }
+var ALERT_CAP = 10;
+var UNACTIONED_CAP = 5;
+function formatDiscoveredIssuesBlocks(candidateLearnings, closedTaskIds) {
+  const byRecency = (a, b2) => (b2.createdAt ?? "").localeCompare(a.createdAt ?? "");
+  const unactionedAll = candidateLearnings.filter((l) => !closedTaskIds.has(l.taskId)).map((l) => ({ ...l, severity: l.severity ?? "P3" }));
+  const allAlerts = unactionedAll.filter((l) => l.severity === "P0" || l.severity === "P1").sort(byRecency);
+  const allLowSev = unactionedAll.filter((l) => l.severity === "P2" || l.severity === "P3").sort(byRecency);
+  const totalP2 = allLowSev.filter((l) => l.severity === "P2").length;
+  const totalP3 = allLowSev.filter((l) => l.severity === "P3").length;
+  const alerts = allAlerts.slice(0, ALERT_CAP);
+  const unactioned = allLowSev.slice(0, UNACTIONED_CAP);
+  let alertsNote = "";
+  let unactionedIssuesNote = "";
+  if (allAlerts.length > 0) {
+    const header = allAlerts.length > ALERT_CAP ? `${allAlerts.length} P0/P1 issues discovered during recent builds (showing ${ALERT_CAP} most recent). These are NOT pullable tasks \u2014 they're observations awaiting triage.` : `${allAlerts.length} P0/P1 issue${allAlerts.length !== 1 ? "s" : ""} discovered during recent builds. These are NOT pullable tasks \u2014 they're observations awaiting triage.`;
+    const lines = ["\n\n## \u{1F6A8} Alerts \u2014 Discovered Issues from Recent Builds (not tasks)", header];
+    for (const issue of alerts) {
+      const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
+      lines.push(`- **${issue.severity}**: ${desc}`);
+      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})`);
+    }
+    lines.push("_Escalate: run `idea` with P1 priority to log as a backlog task, or `board_edit` if already handled._");
+    alertsNote = lines.join("\n");
+  }
+  if (allLowSev.length > 0) {
+    const totalLow = totalP2 + totalP3;
+    const header = totalLow > UNACTIONED_CAP ? `${totalP2} P2 \xB7 ${totalP3} P3 issues discovered during recent builds (showing ${UNACTIONED_CAP} most recent). These are NOT pullable tasks \u2014 they're observations awaiting triage.` : `${totalP2} P2 \xB7 ${totalP3} P3 issues discovered during recent builds. These are NOT pullable tasks \u2014 they're observations awaiting triage.`;
+    const lines = ["\n\n## Discovered Issues from Recent Builds (not tasks)", header];
+    for (const issue of unactioned) {
+      const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
+      lines.push(`- **${issue.severity}**: ${desc}`);
+      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})`);
+    }
+    lines.push("_Run `idea` to log these as backlog tasks, or `board_edit` if already handled._");
+    unactionedIssuesNote = lines.join("\n");
+  }
+  return { alertsNote, unactionedIssuesNote };
+}
 async function handleOrient(adapter2, config2, args = {}) {
   const environment = normaliseEnvironment(args.environment);
   try {
@@ -22035,7 +22446,7 @@ ${versionDrift}` : "";
     let unregisteredDocsNote = "";
     try {
       if (adapter2.searchDocs) {
-        const docsDir = join10(config2.projectRoot, "docs");
+        const docsDir = join11(config2.projectRoot, "docs");
         const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
         if (docsFiles.length > 0) {
           const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
@@ -22086,7 +22497,7 @@ ${versionDrift}` : "";
               lines.push(`  \u2192 \u2026and ${pendingActions.length - 2} more`);
             }
           }
-          lines.push("_Factor into next `strategy_review` or run `doc_search` for details._");
+          lines.push("_Promote an actionable item now via `doc_action_promote`, or factor into next `strategy_review`. Run `doc_search` for full details._");
           researchSignalsNote = lines.join("\n");
         }
       }
@@ -22130,36 +22541,38 @@ ${versionDrift}` : "";
     try {
       const learnings = await adapter2.getCycleLearnings?.({ category: "issue", limit: 30 });
       if (learnings) {
-        const byRecency = (a, b2) => (b2.createdAt ?? "").localeCompare(a.createdAt ?? "");
-        const unactionedAll = learnings.filter((l) => !l.actionTaken).map((l) => ({ ...l, severity: l.severity ?? "P3" }));
-        const allAlerts = unactionedAll.filter((l) => l.severity === "P0" || l.severity === "P1").sort(byRecency);
-        const allLowSev = unactionedAll.filter((l) => l.severity === "P2" || l.severity === "P3").sort(byRecency);
-        const totalP2 = allLowSev.filter((l) => l.severity === "P2").length;
-        const totalP3 = allLowSev.filter((l) => l.severity === "P3").length;
-        const ALERT_CAP = 10;
-        const UNACTIONED_CAP = 5;
-        const alerts = allAlerts.slice(0, ALERT_CAP);
-        const unactioned = allLowSev.slice(0, UNACTIONED_CAP);
-        if (allAlerts.length > 0) {
-          const header = allAlerts.length > ALERT_CAP ? `${allAlerts.length} P0/P1 discovered issues awaiting action (showing ${ALERT_CAP} most recent).` : `${allAlerts.length} P0/P1 discovered issue${allAlerts.length !== 1 ? "s" : ""} awaiting action.`;
-          const lines = ["\n\n## \u{1F6A8} Alerts", header];
-          for (const issue of alerts) {
-            const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
-            lines.push(`- **${issue.severity}** (C${issue.cycleNumber} / ${issue.taskId}): ${desc}`);
+        const candidateLearnings = learnings.filter((l) => !l.actionTaken);
+        const referencedTaskIds = Array.from(new Set(candidateLearnings.map((l) => l.taskId).filter(Boolean)));
+        let closedTaskIds = /* @__PURE__ */ new Set();
+        if (referencedTaskIds.length > 0) {
+          try {
+            const tasks = await adapter2.getTasks(referencedTaskIds);
+            closedTaskIds = new Set(
+              tasks.filter((t) => t.status === "Done" || t.status === "Cancelled").map((t) => t.id)
+            );
+          } catch {
           }
-          lines.push("_Escalate: run `idea` with P1 priority, or `board_edit` if already handled._");
-          alertsNote = lines.join("\n");
         }
-        if (allLowSev.length > 0) {
-          const totalLow = totalP2 + totalP3;
-          const header = totalLow > UNACTIONED_CAP ? `${totalP2} P2 \xB7 ${totalP3} P3 (showing ${UNACTIONED_CAP} most recent)` : `${totalP2} P2 \xB7 ${totalP3} P3`;
-          const lines = ["\n\n## Unactioned Issues", header];
-          for (const issue of unactioned) {
-            const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
-            lines.push(`- **${issue.severity}** (C${issue.cycleNumber} / ${issue.taskId}): ${desc}`);
-          }
-          lines.push("_Run `idea` to log these as backlog tasks, or `board_edit` if already handled._");
-          unactionedIssuesNote = lines.join("\n");
+        const formatted = formatDiscoveredIssuesBlocks(candidateLearnings, closedTaskIds);
+        alertsNote = formatted.alertsNote;
+        unactionedIssuesNote = formatted.unactionedIssuesNote;
+      }
+    } catch {
+    }
+    let skillProposalsNote = "";
+    try {
+      const metrics = await adapter2.readToolMetrics();
+      const alreadyScanned = metrics.some((m) => m.tool === "milestone:skill_scan_completed");
+      if (!alreadyScanned) {
+        const proposals = scanForSkillSignals(config2.projectRoot);
+        skillProposalsNote = formatSkillProposals(proposals);
+        try {
+          await adapter2.appendToolMetric({
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            tool: "milestone:skill_scan_completed",
+            durationMs: 0
+          });
+        } catch {
         }
       }
     } catch {
@@ -22175,16 +22588,16 @@ ${versionDrift}` : "";
       markOrient();
     } catch {
     }
-    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment) + alertsNote + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + sessionGuidanceNote + versionNote + enrichmentNote);
+    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment) + alertsNote + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return errorResponse(`Orient failed: ${message}`);
   }
 }
 function enrichClaudeMd(projectRoot, cycleNumber) {
-  const claudeMdPath = join10(projectRoot, "CLAUDE.md");
-  if (!existsSync7(claudeMdPath)) return "";
-  const content = readFileSync3(claudeMdPath, "utf-8");
+  const claudeMdPath = join11(projectRoot, "CLAUDE.md");
+  if (!existsSync8(claudeMdPath)) return "";
+  const content = readFileSync4(claudeMdPath, "utf-8");
   const additions = [];
   if (cycleNumber >= 6 && !content.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1)) {
     additions.push(CLAUDE_MD_TIER_1);
@@ -22966,12 +23379,12 @@ ${result.userMessage}
 }
 
 // src/lib/install-id.ts
-import { randomUUID as randomUUID15 } from "crypto";
-import { mkdirSync, readFileSync as readFileSync4, writeFileSync as writeFileSync2, chmodSync } from "fs";
+import { randomUUID as randomUUID16 } from "crypto";
+import { mkdirSync, readFileSync as readFileSync5, writeFileSync as writeFileSync2, chmodSync } from "fs";
 import { homedir as homedir3 } from "os";
-import { join as join11 } from "path";
-var PAPI_HOME_DIR = join11(homedir3(), ".papi");
-var INSTALL_ID_FILE = join11(PAPI_HOME_DIR, "install-id.json");
+import { join as join12 } from "path";
+var PAPI_HOME_DIR = join12(homedir3(), ".papi");
+var INSTALL_ID_FILE = join12(PAPI_HOME_DIR, "install-id.json");
 var cachedInstallId = null;
 function isValidUuid(s) {
   return typeof s === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s);
@@ -22979,7 +23392,7 @@ function isValidUuid(s) {
 function getInstallId() {
   if (cachedInstallId) return cachedInstallId;
   try {
-    const raw = readFileSync4(INSTALL_ID_FILE, "utf-8");
+    const raw = readFileSync5(INSTALL_ID_FILE, "utf-8");
     const parsed = JSON.parse(raw);
     if (isValidUuid(parsed.install_id)) {
       cachedInstallId = parsed.install_id;
@@ -22989,7 +23402,7 @@ function getInstallId() {
   }
   try {
     mkdirSync(PAPI_HOME_DIR, { recursive: true, mode: 448 });
-    const id = randomUUID15();
+    const id = randomUUID16();
     const contents = {
       install_id: id,
       created_at: (/* @__PURE__ */ new Date()).toISOString()
@@ -23109,7 +23522,7 @@ function createServer(adapter2, config2) {
   const __pkgDir = dirname(__pkgFilename);
   let serverVersion = "unknown";
   try {
-    const pkg = JSON.parse(readFileSync5(join12(__pkgDir, "..", "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync6(join13(__pkgDir, "..", "package.json"), "utf-8"));
     serverVersion = pkg.version ?? "unknown";
   } catch {
   }
@@ -23124,7 +23537,7 @@ function createServer(adapter2, config2) {
   }
   const __filename = fileURLToPath(import.meta.url);
   const __dirname2 = dirname(__filename);
-  const skillsDir = join12(__dirname2, "..", "skills");
+  const skillsDir = join13(__dirname2, "..", "skills");
   function parseSkillFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match) return null;
@@ -23142,7 +23555,7 @@ function createServer(adapter2, config2) {
       const mdFiles = files.filter((f) => f.endsWith(".md"));
       const prompts = [];
       for (const file of mdFiles) {
-        const content = await readFile5(join12(skillsDir, file), "utf-8");
+        const content = await readFile5(join13(skillsDir, file), "utf-8");
         const meta = parseSkillFrontmatter(content);
         if (meta) {
           prompts.push({ name: meta.name, description: meta.description });
@@ -23158,7 +23571,7 @@ function createServer(adapter2, config2) {
     try {
       const files = await readdir2(skillsDir);
       for (const file of files.filter((f) => f.endsWith(".md"))) {
-        const content = await readFile5(join12(skillsDir, file), "utf-8");
+        const content = await readFile5(join13(skillsDir, file), "utf-8");
         const meta = parseSkillFrontmatter(content);
         if (meta?.name === name) {
           const body = content.replace(/^---\n[\s\S]*?\n---\n*/, "");
@@ -23201,6 +23614,7 @@ function createServer(adapter2, config2) {
       docRegisterTool,
       docSearchTool,
       docScanTool,
+      docActionPromoteTool,
       getSiblingAdsTool,
       handoffGenerateTool
     ]
@@ -23316,6 +23730,9 @@ function createServer(adapter2, config2) {
       case "doc_scan":
         result = await handleDocScan(adapter2, config2, safeArgs);
         break;
+      case "doc_action_promote":
+        result = await handleDocActionPromote(adapter2, safeArgs);
+        break;
       case "get_sibling_ads":
         result = await handleGetSiblingAds(adapter2, safeArgs);
         break;
@@ -23371,7 +23788,7 @@ function createServer(adapter2, config2) {
 var __dirname = dirname2(fileURLToPath2(import.meta.url));
 var pkgVersion = "unknown";
 try {
-  const pkg = JSON.parse(readFileSync6(join13(__dirname, "..", "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync7(join14(__dirname, "..", "package.json"), "utf-8"));
   pkgVersion = pkg.version;
 } catch {
 }

package/dist/prompts.js

@@ -1,4 +1,18 @@
 // src/prompts.ts
+var AD_REJECTION_RULES = `**AD Minting Guard \u2014 REJECT observations dressed as decisions.**
+
+An Active Decision expresses a *stance* the project is taking \u2014 a choice between alternatives that constrains future work. Reject any candidate AD whose body asserts:
+(a) the existence, identity, or status of a person, user, or external entity (e.g. "User X is building Y", "Customer Z is active");
+(b) a metric or measurement (e.g. "Signups grew 3x last cycle", "Latency dropped to 200ms");
+(c) a fact about the current state of the world that could be confirmed or denied by a query rather than challenged by argument (e.g. "External user feedback is now flowing", "The /admin route exists").
+
+If a candidate AD body could be invalidated by running a SQL query, refreshing a dashboard, or checking a log \u2014 it is an observation, not a decision. Capture it as a build report finding, a dogfood observation, a cycle log note, or a registered doc instead. Do NOT mint it as an AD.
+
+**Positive example (valid AD):** "Pricing tier strategy: free engine + paid intelligence. Decision: keep cycles free, charge for strategy reviews and analytics. Why: telemetry shows engagement clusters around intelligence surfaces, not engine surfaces." \u2014 this is a stance with alternatives.
+
+**Negative example (reject):** "External user feedback is now flowing. Stonebridge Systems is actively building." \u2014 this is a fact about the current state of the world. Capture as dogfood/signal observation; do not mint.
+
+This rule applies to: new ADs proposed during planning (Step 9), strategy review AD updates (section 5), and strategy_change AD updates. If you find an existing AD that violates this rule during housekeeping, propose deleting it (action: "delete") with a one-line rationale.`;
 var PLAN_SYSTEM = `You are the PAPI Cycle Planner \u2014 an autonomous planning engine for software projects.
 You receive project context and produce a planning cycle output with a BUILD HANDOFF.
 
@@ -179,6 +193,7 @@ Standard planning cycle with full board review.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
    **\u26A0\uFE0F PRIORITY RECALIBRATION \u2014 do NOT rubber-stamp the submitted priority.** The priority set at idea submission reflects the submitter's view at that time, which may be outdated by the time the planner runs. For EVERY unreviewed task, evaluate its priority FROM SCRATCH against: (a) current horizon/stage/phase goals, (b) recent Active Decision changes, (c) recently shipped functionality that makes this task more or less urgent. If your assessed priority differs from the submitted one, set the new priority in \`boardCorrections\` and include the change in a **Priority Recalibration** paragraph in your cycle log (Step 8): list each changed task by ID, old priority \u2192 new priority, and a 1-sentence rationale. This paragraph is how the user sees what the planner recalibrated and why. If no priorities changed during triage, omit the paragraph.
    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.
+   **Module classification for cross-cutting tasks:** When a task title contains "audit"/"unfiltered"/"scoping"/"leak" plus a database-entity name (e.g. "audit ... cycle_learnings reads", "unfiltered cycle_tasks queries"), classify the module by the actual code surface that reads/writes the entity \u2014 not by the tool names mentioned in the title. The reasoning surface (e.g. "health" or "strategy_review") is often unrelated to the data-access surface. Resolve this by treating the entity name as the routing signal: tasks touching dashboard read/write paths belong to the Dashboard module even if the title mentions an MCP tool. Misclassification routes the task to the wrong shared cycle branch and surfaces the wrong MODULE INSTRUCTIONS to the builder.
    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.
 
@@ -224,6 +239,9 @@ Standard planning cycle with full board review.
 
 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.
+
+${AD_REJECTION_RULES}
+
    **\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
@@ -414,6 +432,7 @@ Standard planning cycle with full board review.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
    **\u26A0\uFE0F PRIORITY RECALIBRATION \u2014 do NOT rubber-stamp the submitted priority.** The priority set at idea submission reflects the submitter's view at that time, which may be outdated by the time the planner runs. For EVERY unreviewed task, evaluate its priority FROM SCRATCH against: (a) current horizon/stage/phase goals, (b) recent Active Decision changes, (c) recently shipped functionality that makes this task more or less urgent. If your assessed priority differs from the submitted one, set the new priority in \`boardCorrections\` and include the change in a **Priority Recalibration** paragraph in your cycle log (Step 8): list each changed task by ID, old priority \u2192 new priority, and a 1-sentence rationale. This paragraph is how the user sees what the planner recalibrated and why. If no priorities changed during triage, omit the paragraph.
    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.
+   **Module classification for cross-cutting tasks:** When a task title contains "audit"/"unfiltered"/"scoping"/"leak" plus a database-entity name (e.g. "audit ... cycle_learnings reads", "unfiltered cycle_tasks queries"), classify the module by the actual code surface that reads/writes the entity \u2014 not by the tool names mentioned in the title. The reasoning surface (e.g. "health" or "strategy_review") is often unrelated to the data-access surface. Resolve this by treating the entity name as the routing signal: tasks touching dashboard read/write paths belong to the Dashboard module even if the title mentions an MCP tool. Misclassification routes the task to the wrong shared cycle branch and surfaces the wrong MODULE INSTRUCTIONS to the builder.
    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.
 
@@ -461,6 +480,9 @@ Standard planning cycle with full board review.
 
 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.
+
+${AD_REJECTION_RULES}
+
    **\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
@@ -625,6 +647,16 @@ function buildPlanUserMessage(ctx) {
     if (ctx.registeredDocs) {
       parts.push("### Relevant Research Docs", "", ctx.registeredDocs, "");
     }
+    if (ctx.unactionedDocs) {
+      parts.push(
+        "### Unactioned Research (soft-warn)",
+        "",
+        "These registered docs still have pending actions. Before adding net-new tasks, consider whether one of these unactioned items should be promoted into this cycle via `doc_action_promote`. Surface this in your plan output so the user can decide.",
+        "",
+        ctx.unactionedDocs,
+        ""
+      );
+    }
     if (ctx.carryForwardStaleness) {
       parts.push("### Carry-Forward Staleness", "", ctx.carryForwardStaleness, "");
     }
@@ -833,8 +865,17 @@ You MUST cover these 5 sections. Each is mandatory.
    - Note any hierarchy/phase issues worth correcting (1-2 bullets max)
    - Delete ADs that are legacy, process-level, or redundant without discussion
 
+${AD_REJECTION_RULES}
+
 **Registered Documents:** If a "### Registered Documents" section is present in context, scan it for: (a) research findings that contradict current ADs or strategy, (b) unactioned research that should influence the next plan. Reference relevant docs by title in your review. If unregistered docs are listed, flag 1-2 that look strategically relevant and suggest registering them.
 
+**Doc Action Staleness:** If a "### Doc Action Staleness" section is present, treat it as a research-to-action audit. For each entry:
+- **Stale** (no Done task, >20 cycles old): explicitly call it out in section 2 (Product Gaps) or 3 (Opportunities) \u2014 research that's been sitting unactioned this long is either (a) no longer relevant (recommend marking the doc archived) or (b) silently dropped (recommend promoting via \`doc_action_promote\` into the next plan).
+- **Completed but not closed** (linked task is Done): instruct in your review that the action should be marked resolved \u2014 it's done work the registry hasn't caught up to.
+- **Deferred** (<20 cycles, no matching Done task): only mention if it relates to a current strategic theme; otherwise leave it.
+
+For every stale or unresolved item you call out, propose a concrete next step (promote, archive, or supersede) \u2014 don't just observe.
+
 ## CONDITIONAL SECTIONS (include only when genuinely useful \u2014 most reviews should have 0-2 of these)
 
 6. **Security Posture Review** \u2014 Only if \`[SECURITY]\` tags exist in recent cycle logs.
@@ -1142,6 +1183,8 @@ The JSON must be valid. Only include ADs that need changes \u2014 omit unchanged
 For new ADs, use the next available AD number.
 The body field must be the COMPLETE replacement text for the AD block (including the ### heading line).
 
+${AD_REJECTION_RULES}
+
 ## PHASE UPDATES
 
 If the strategic change affects the project's phase structure, include a phaseUpdates array.
@@ -1438,6 +1481,7 @@ ${inputs.codebaseContext}
 Return a JSON array of 3-10 tasks based on gaps, improvements, and next steps visible from the codebase analysis above.`;
 }
 export {
+  AD_REJECTION_RULES,
   AD_SEED_SYSTEM,
   CONVENTIONS_SYSTEM,
   HANDOFF_REGEN_SYSTEM,

package/package.json

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