@papi-ai/server 0.7.14 → 0.7.15

package/dist/index.js

@@ -6733,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) {
@@ -7607,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
     `;
@@ -9486,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";
@@ -9775,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 {
@@ -10763,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.
 
@@ -11001,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.
 
@@ -11215,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, "");
     }
@@ -11427,6 +11458,13 @@ ${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.
@@ -12108,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;
   }
@@ -12277,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);
@@ -12616,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;
@@ -12672,6 +12739,7 @@ ${lines.join("\n")}`;
       discoveryCanvas: discoveryCanvasText,
       estimationCalibration: estimationCalibrationText,
       registeredDocs: registeredDocsText,
+      unactionedDocs: unactionedDocsTextLean,
       focus,
       boardFlags,
       carryForwardStaleness: carryForwardStalenessLean,
@@ -12749,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"]);
@@ -12797,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);
@@ -12835,6 +12905,7 @@ ${logLines}`);
     taskComments: taskCommentsTextFull,
     discoveryCanvas: discoveryCanvasTextFull,
     registeredDocs: registeredDocsTextFull,
+    unactionedDocs: unactionedDocsTextFull,
     focus,
     boardFlags: boardFlagsFull,
     carryForwardStaleness: computeCarryForwardStaleness(log),
@@ -13794,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;
@@ -13858,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, '\\"')}"
 
 ---
@@ -18703,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);
@@ -21516,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.",
@@ -21662,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")) {
@@ -21680,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);
@@ -21696,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/", "")))
       }));
     }
   }
@@ -21717,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}` : ""}`);
     }
   }
@@ -21730,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,
@@ -21754,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" });
@@ -21792,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) {
@@ -21949,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");
@@ -21993,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"], {
@@ -22010,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 {
@@ -22120,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" });
@@ -22171,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");
         }
       }
@@ -22215,7 +22541,6 @@ ${versionDrift}` : "";
     try {
       const learnings = await adapter2.getCycleLearnings?.({ category: "issue", limit: 30 });
       if (learnings) {
-        const byRecency = (a, b2) => (b2.createdAt ?? "").localeCompare(a.createdAt ?? "");
         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();
@@ -22228,35 +22553,26 @@ ${versionDrift}` : "";
           } catch {
           }
         }
-        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 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}`);
-          }
-          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 {
@@ -22272,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);
@@ -23063,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);
@@ -23076,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;
@@ -23086,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()
@@ -23206,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 {
   }
@@ -23221,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;
@@ -23239,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 });
@@ -23255,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*/, "");
@@ -23298,6 +23614,7 @@ function createServer(adapter2, config2) {
       docRegisterTool,
       docSearchTool,
       docScanTool,
+      docActionPromoteTool,
       getSiblingAdsTool,
       handoffGenerateTool
     ]
@@ -23413,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;
@@ -23468,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

@@ -193,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.
 
@@ -431,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.
 
@@ -645,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, "");
     }
@@ -857,6 +869,13 @@ ${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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.14",
+  "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",