@papi-ai/server 0.7.51 → 0.7.52

package/dist/index.js

@@ -13096,7 +13096,7 @@ var planPrepareCache = new PerCallerCache();
 var planTool = {
   name: "plan",
   description: 'Run once per cycle to select tasks and generate BUILD HANDOFFs. Call after setup (first time) or after completing all builds AND running release for the previous cycle. Returns prioritised task recommendations with detailed implementation specs. NEVER call when unbuilt cycle tasks exist \u2014 build and release first. First call returns a planning prompt for you to execute (prepare phase). Then call again with mode "apply" and your output to write results. Use skip_handoffs=true for large backlogs \u2014 handoffs are then generated separately via `handoff_generate`.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Plan Cycle", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -13641,15 +13641,34 @@ async function findSimilarTasks(adapter2, ideaTitle) {
   return matches.sort((a, b2) => b2.coverage - a.coverage).slice(0, 3);
 }
 var AD_ALIGNMENT_OVERLAP_THRESHOLD = 3;
+var DOC_FREQ_CEILING = 0.35;
+function findUbiquitousWords(ads) {
+  const live = ads.filter((a) => !a.superseded);
+  const ubiquitous = /* @__PURE__ */ new Set();
+  if (live.length < 5) return ubiquitous;
+  const docFreq = /* @__PURE__ */ new Map();
+  for (const ad of live) {
+    for (const w of extractKeywords(`${ad.title} ${ad.body}`)) {
+      docFreq.set(w, (docFreq.get(w) ?? 0) + 1);
+    }
+  }
+  const ceiling = live.length * DOC_FREQ_CEILING;
+  for (const [w, df] of docFreq) {
+    if (df > ceiling) ubiquitous.add(w);
+  }
+  return ubiquitous;
+}
 function findAdAlignmentMatches(ideaText, ads) {
   const ideaKeywords = extractKeywords(ideaText);
   if (ideaKeywords.size < AD_ALIGNMENT_OVERLAP_THRESHOLD) return [];
+  const ubiquitous = findUbiquitousWords(ads);
   const matches = [];
   for (const ad of ads) {
     if (ad.superseded) continue;
     const adKeywords = extractKeywords(`${ad.title} ${ad.body}`);
     let overlap = 0;
     for (const w of ideaKeywords) {
+      if (ubiquitous.has(w)) continue;
       if (adKeywords.has(w)) overlap++;
     }
     if (overlap >= AD_ALIGNMENT_OVERLAP_THRESHOLD) {
@@ -15494,7 +15513,7 @@ var reviewPrepareCache = new PerCallerCache();
 var strategyReviewTool = {
   name: "strategy_review",
   description: 'Run a Strategy Review \u2014 assesses project direction, velocity, and Active Decisions. Produces recommendations and potential AD updates that feed into the next plan. Offered every 5 cycles; hard-blocked at 7+ overdue cycles. Run it in your current conversation \u2014 only start a fresh one if you are genuinely under context pressure (your host just compacted, you are near the context limit, or the session is heavy with build context), not just because a review is next. First call returns a review prompt for you to execute (prepare phase). Then call again with mode "apply" and your output. Pass `force: true` to run before the cadence gate.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Run Strategy Review", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -15531,7 +15550,7 @@ var strategyReviewTool = {
 var strategyAgendaTool = {
   name: "strategy_agenda",
   description: 'Queue topics for the next strategy review. Topics surface as input in the next `strategy_review` prepare phase and are automatically marked as addressed after the review completes. Two modes: "add" to queue a topic, "list" to see pending topics. Use this when you spot a strategic question during a build \u2014 capture the topic now instead of losing it.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Strategy Agenda", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -15559,7 +15578,7 @@ var strategyAgendaTool = {
 var strategyChangeTool = {
   name: "strategy_change",
   description: 'Apply a strategic shift to the project. Three modes: "capture" for lightweight mid-conversation decision capture (no LLM round-trip), "prepare" to get a change prompt for full analysis, "apply" to persist analysis output. Use "capture" when you detect a strategic decision in conversation and want to persist it quickly without disrupting the build flow. In "capture" mode, pass north_star to directly set/update the project North Star (no decision text needed).',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Change Strategy", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -16018,7 +16037,7 @@ async function archiveTasks(adapter2, phases, statuses) {
 var boardViewTool = {
   name: "board_view",
   description: 'View the Board. To find a SPECIFIC task or subset, FILTER FIRST \u2014 do not dump the whole board: pass task_id for one task (full detail), query="<text>" for a title/notes substring match, or cycle=<n> for one cycle. Combine with status/phase. By default shows active tasks only (excludes Done/Cancelled), sorted by priority, limited to 50; titles are truncated in the table (single-task lookup shows the full title). Use status="all" to see everything, mode="summary" for counts only. Does not call the Anthropic API.',
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "View Board", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -16062,7 +16081,7 @@ var boardViewTool = {
 var boardDeprioritiseTool = {
   name: "board_deprioritise",
   description: `Remove a task from the current cycle. Four actions: "backlog" (not now, maybe later \u2014 preserves handoff), "defer" (valid but premature \u2014 hidden from planner), "block" (waiting on external dependency \u2014 visible on board but skipped by planner), "cancel" (don't want this \u2014 permanently closed with reason). When a user rejects a task, ALWAYS ask which action they want. Does not call the Anthropic API.`,
-  annotations: { readOnlyHint: false, destructiveHint: true },
+  annotations: { title: "Deprioritise Task", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -16107,7 +16126,7 @@ var boardDeprioritiseTool = {
 var boardArchiveTool = {
   name: "board_archive",
   description: "Archive tasks from the Board to the archive file. When both phase and status are provided, only tasks matching BOTH are archived (AND logic). When only one is provided, all matching tasks are archived. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: true },
+  annotations: { title: "Archive Task", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -16126,7 +16145,7 @@ var boardArchiveTool = {
 var boardEditTool = {
   name: "board_edit",
   description: "Edit fields on an existing task. Supports title, priority, complexity, module, epic, phase, notes (with notes_mode for append/replace/clear), status, maturity, and cycle (number or null). Pass task_id plus any fields to update. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Edit Task", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -18069,7 +18088,7 @@ async function ensureMcpJsonGitignored(projectRoot) {
 var setupTool = {
   name: "setup",
   description: 'Create a new PAPI-tracked project \u2014 generates your Product Brief, Active Decisions, and CLAUDE.md workflow instructions. Run after configuring your MCP credentials (via `init` or manually from getpapi.ai). Only project_name is required \u2014 description and target_users are derived from README, package.json, and commit history when omitted. Set existing_project: true to adopt an existing codebase. ADOPTING AN EXISTING PROJECT OVER A REMOTE/HOSTED CONNECTOR (no local stdio install): PAPI cannot read your filesystem, so YOU (the client) must gather a `codebase_scan` and pass it in \u2014 list top-level dirs/files, the package manifest, the README (first ~3000 chars), and recent commit subjects. Without it, adoption falls back to asking for description/target_users. On a local stdio install PAPI scans the tree itself, so `codebase_scan` is optional there. First call returns prompts (prepare phase), then call again with mode "apply" and your outputs. After setup, run `plan` to start your first cycle.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Set Up Project", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -19354,7 +19373,7 @@ async function postReleaseToX(version, cycleClosed) {
 var releaseTool = {
   name: "release",
   description: "Cut a versioned release \u2014 creates a git tag, generates CHANGELOG.md, and pushes to remote. Pass skipVersion=true to update CHANGELOG and close the cycle without creating a tag or bumping version numbers.",
-  annotations: { readOnlyHint: false, destructiveHint: true },
+  annotations: { title: "Cut Release", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -20591,15 +20610,16 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
     const adIds = report.relatedDecisions ?? [];
     const extractLearning = (text, category) => {
       if (!text || text === "None" || text.trim().length === 0) return;
-      const dotIdx = text.indexOf(". ");
-      const summary = dotIdx > 0 && dotIdx < 120 ? text.slice(0, dotIdx + 1) : text.slice(0, 120);
-      const tags = [];
-      if (taskModule) tags.push(taskModule.toLowerCase());
       let severity;
       if (category === "issue") {
         const sevMatch = text.match(/^(P[0-3])[\s:]/);
         if (sevMatch) severity = sevMatch[1];
       }
+      const body = severity ? text.replace(/^P[0-3][\s:]+/, "").trim() : text.trim();
+      const dotIdx = body.indexOf(". ");
+      const summary = dotIdx > 0 ? body.slice(0, dotIdx + 1) : body;
+      const tags = [];
+      if (taskModule) tags.push(taskModule.toLowerCase());
       learnings.push({
         taskId: task.id,
         cycleNumber,
@@ -21000,7 +21020,7 @@ import { randomUUID as randomUUID12 } from "crypto";
 var docRegisterTool = {
   name: "doc_register",
   description: "Register or update 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. Re-registering an existing doc updates its summary, tags, actions, type, and status (upsert). Visibility and owner are not changed on re-register.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Register Doc", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21033,7 +21053,7 @@ var docRegisterTool = {
 var docSearchTool = {
   name: "doc_search",
   description: "Search the doc registry for documents by type, tags, keyword, or pending actions. Returns summaries, not full content. Use for context gathering in plan, strategy review, and idea dedup.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "Search Docs", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21051,7 +21071,7 @@ var docSearchTool = {
 var docScanTool = {
   name: "doc_scan",
   description: "Scan docs/ and plans directories for unregistered .md files. Returns a list of files not yet in the doc registry. Use this to find docs that need registration.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "Scan Docs", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21298,7 +21318,7 @@ async function handleDocScan(adapter2, config2, args) {
 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 },
+  annotations: { title: "Promote Doc Action", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21397,7 +21417,7 @@ init_git();
 var buildListTool = {
   name: "build_list",
   description: "List cycle tasks that have BUILD HANDOFFs ready for execution. Shows task ID, title, status, priority, and complexity. In Progress tasks appear first, then Backlog. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "List Builds", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21412,7 +21432,7 @@ var buildListTool = {
 var buildDescribeTool = {
   name: "build_describe",
   description: "Show the full BUILD HANDOFF for a specific task, including scope, acceptance criteria, and implementation guidance. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "Describe Build", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21427,7 +21447,7 @@ var buildDescribeTool = {
 var buildExecuteTool = {
   name: "build_execute",
   description: "Start or complete a build task. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Never call on tasks that are already In Review or Done. Does not call the Anthropic API. Set light=true to skip branch/PR creation (commits to current branch). Set PAPI_LIGHT_MODE=true in env to default all builds to light mode.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Run Build", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -21541,7 +21561,7 @@ var buildExecuteTool = {
 var buildCancelTool = {
   name: "build_cancel",
   description: "Cancel a build task with a reason. Sets the task status to Cancelled and records the closure reason. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: true },
+  annotations: { title: "Cancel Build", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -22089,7 +22109,7 @@ Reason: ${result.reason}`);
 init_git();
 var ideaTool = {
   name: "idea",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Capture Idea", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description: "Capture an idea as a Backlog task. The next plan run will triage and scope it. Use anytime to log bugs, feature requests, or improvements without interrupting the current cycle. IMPORTANT: If this idea originates from a research or planning session, you MUST include a Reference: line in notes pointing to the source doc. Without it, the planner has no context and will misinterpret the intent. Does not call the Anthropic API.",
   inputSchema: {
     type: "object",
@@ -22306,7 +22326,7 @@ function collectDiagnostics(config2) {
 var bugTool = {
   name: "bug",
   description: `Report a bug OR submit an idea. Routing: a bug about PAPI itself (a PAPI tool/MCP error, the connector, a handoff/cycle problem) auto-submits UPSTREAM to PAPI maintainers with diagnostics \u2014 you do NOT need to set report=true for these. A bug in the user's OWN project auto-files as a Backlog task on their board. IMPORTANT: report=true is ONLY for a genuine PAPI-product defect \u2014 it is NOT the catch-all for "not about my app". A bug in the user's harness/editor/OS/git/other tooling (e.g. Claude Code, Codex, VS Code, a shell command) is NOT a PAPI bug: file it on the user's own board (report=false / default) or that tool's own tracker, never upstream. Override the routing explicitly: report=true forces upstream (PAPI-product only), report=false forces the user's own board. Set \`type\` ("bug"/"idea") and optional notify-when-fixed / contact-ok consent for upstream submissions. Does not call the Anthropic API.`,
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Report Bug", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -22563,7 +22583,7 @@ function inferTaskType(description) {
 var adHocTool = {
   name: "ad_hoc",
   description: "Record work done outside the normal cycle. Creates a Done task with a lightweight build report, or associates work with an existing task if task_id is provided (without changing task status \u2014 use build_execute for status transitions). Use for quick fixes, bug patches, or ad-hoc changes. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Record Ad-Hoc Work", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -23053,7 +23073,7 @@ async function applyReconcile(adapter2, corrections) {
 var boardReconcileTool = {
   name: "board_reconcile",
   description: 'Holistic board review \u2014 backlog + deferred tasks in one pass. Surfaces strategic context (ADs, phases, docs), grouping signals, merge candidates, priority drift, and stale tasks. "prepare" assembles context for you to analyse; "apply" commits your decisions after user confirmation. Does not call the Anthropic API.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Reconcile Board", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -23546,7 +23566,7 @@ ${diffBlock}`;
 var reviewListTool = {
   name: "review_list",
   description: "List tasks ready for your sign-off \u2014 shows completed builds waiting for approval or feedback. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "List Reviews", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -23561,7 +23581,7 @@ var reviewListTool = {
 var reviewSubmitTool = {
   name: "review_submit",
   description: "Record a review verdict on a completed build (build-acceptance) or task plan (handoff-review). ALWAYS ask the human for their verdict before calling \u2014 never auto-submit without human input. Accept moves the task to Done, request-changes sends it back for rework, reject discards the build. Updates task status based on the verdict. On handoff-review with suggested changes, returns a prompt to revise the BUILD HANDOFF.\n\nDO NOT use this tool as a substitute for review_list. If you need to see what is pending review, call review_list first. If review_list is unavailable in your tool set, STOP and tell the human their MCP integration is incomplete rather than guessing at the next pending task. (SUP-2026-010.)",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Submit Review", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -24113,7 +24133,7 @@ ${statusNote}${autoReviewNote}${securityNote}${unblockNote}${docClosureNote}${re
 var reviewClaimTool = {
   name: "review_claim",
   description: "Claim a Pending Review from the shared cross-user review queue so you are the one reviewing it. Atomic first-claim-wins \u2014 two reviewers cannot grab the same build. After claiming, run review_submit to record your verdict. Owner-or-active-member only. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Claim Review", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -24178,7 +24198,7 @@ import path5 from "path";
 var initTool = {
   name: "init",
   description: "Write the MCP config file that connects this project to PAPI. Generates .mcp.json (Claude Code default) or the equivalent for Cursor, VS Code, Windsurf, OpenCode, Amazon Q, Kilo Code, Gemini CLI, Codex CLI, or Hermes Agent. Config-only \u2014 does not create any project data. Run this first, then run `setup` to create your PAPI project.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Initialise Project", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -25087,6 +25107,104 @@ function formatUnblockSection(candidates) {
   return lines.join("\n");
 }
 
+// src/lib/deferred-gate.ts
+var GATE_PHRASES = [
+  "depends on",
+  "depends upon",
+  "gated on",
+  "gated behind",
+  "blocked on",
+  "blocked by",
+  "waiting on",
+  "waiting for",
+  "pending",
+  "once",
+  "after",
+  "until",
+  "requires",
+  "needs",
+  "pull condition",
+  "unblocked by"
+];
+var CONTEXT_WINDOW = 60;
+var TASK_REF2 = /\btask-\d+\b/gi;
+var MAX_PER_BUCKET = 8;
+function extractGatedTaskRefs(notes) {
+  if (!notes) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of notes.matchAll(TASK_REF2)) {
+    const ref = m[0].toLowerCase();
+    if (seen.has(ref)) continue;
+    const start = Math.max(0, (m.index ?? 0) - CONTEXT_WINDOW);
+    const before = notes.slice(start, m.index).toLowerCase();
+    const hit = GATE_PHRASES.find((p) => before.includes(p));
+    if (!hit) continue;
+    seen.add(ref);
+    const evidence = notes.slice(start, (m.index ?? 0) + m[0].length).trim();
+    out.push({ ref, evidence: evidence.length > 90 ? `\u2026${evidence.slice(-90)}` : evidence });
+  }
+  return out;
+}
+async function findDeferredGates(adapter2) {
+  const empty = { unblock: [], zombie: [] };
+  let allTasks = [];
+  try {
+    allTasks = await adapter2.queryBoard();
+  } catch {
+    return empty;
+  }
+  const deferred = allTasks.filter((t) => t.status === "Deferred");
+  if (deferred.length === 0) return empty;
+  const byId = /* @__PURE__ */ new Map();
+  for (const t of allTasks) {
+    if (t.displayId) byId.set(t.displayId.toLowerCase(), t);
+  }
+  const sweep = { unblock: [], zombie: [] };
+  for (const task of deferred) {
+    for (const { ref, evidence } of extractGatedTaskRefs(task.notes ?? "")) {
+      const self = task.displayId?.toLowerCase();
+      if (self && ref === self) continue;
+      const upstream = byId.get(ref);
+      if (!upstream) continue;
+      if (upstream.status !== "Done" && upstream.status !== "Cancelled") continue;
+      const gate = {
+        taskId: task.displayId ?? task.id,
+        taskTitle: task.title,
+        upstreamId: upstream.displayId ?? upstream.id,
+        upstreamTitle: upstream.title,
+        upstreamStatus: upstream.status,
+        evidence
+      };
+      const bucket = upstream.status === "Done" ? sweep.unblock : sweep.zombie;
+      if (bucket.length < MAX_PER_BUCKET) bucket.push(gate);
+      break;
+    }
+  }
+  return sweep;
+}
+function formatDeferredGateSection(sweep) {
+  if (sweep.unblock.length === 0 && sweep.zombie.length === 0) return "";
+  const lines = ["## Deferred-Gate Sweep"];
+  if (sweep.unblock.length > 0) {
+    lines.push("");
+    lines.push(`**Unblock candidates (${sweep.unblock.length})** \u2014 the upstream task is Done, so the gate has cleared. Promote with \`board_edit\` \u2192 Backlog.`);
+    for (const g of sweep.unblock) {
+      lines.push(`- **${g.taskId}** (${g.taskTitle}) \u2014 gated on **${g.upstreamId}** which is now Done \u2705`);
+    }
+  }
+  if (sweep.zombie.length > 0) {
+    lines.push("");
+    lines.push(`**Zombie candidates (${sweep.zombie.length})** \u2014 the upstream task was CANCELLED, so this gate can never clear. Cancel or re-scope.`);
+    for (const g of sweep.zombie) {
+      lines.push(`- **${g.taskId}** (${g.taskTitle}) \u2014 gated on **${g.upstreamId}** which was Cancelled \u274C`);
+    }
+  }
+  lines.push("");
+  lines.push("_Advisory only \u2014 nothing was changed. Gates are read from freetext notes, so check the reference before acting._");
+  return lines.join("\n");
+}
+
 // src/tools/agent-list.ts
 import { readdir as readdir2, readFile as readFile7 } from "fs/promises";
 import { join as join14 } from "path";
@@ -25129,7 +25247,7 @@ async function listAgents(projectRoot) {
 var agentListTool = {
   name: "agent_list",
   description: "List the sub-agents discovered in the project's `.claude/agents/*.md` files (read-only). Returns each agent's name and description so you can see which specialised sub-agents are available before dispatching one via the Task/Agent tool. Discovery only \u2014 does not invoke or manage agents.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "List Agents", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -25308,7 +25426,7 @@ async function runWithLimit(concurrency, tasks) {
 var orientTool = {
   name: "orient",
   description: "Session orientation \u2014 run this FIRST at session start before any other tool. Single call that replaces build_list + health. Returns: cycle number, task counts by status, in-progress/in-review tasks, strategy review cadence, velocity snapshot, recommended next action, and a release reminder when all cycle tasks are Done but release has not run. Read-only, does not modify any files. PAPI detects build capability from the connecting harness (clientInfo); pass `environment` only to override that detection for git-dependent recommendations (build_execute, release, review_submit).",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "Orient Session", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -25332,6 +25450,7 @@ var orientTool = {
 var papiTool = {
   ...orientTool,
   name: "papi",
+  annotations: { title: "PAPI Status", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description: 'Say "papi" to check in with Papi \u2014 an alias for `orient`. Run this FIRST at session start: it returns your cycle number, task counts, in-progress/in-review work, strategy-review cadence, a velocity snapshot, and the recommended next action. Identical to `orient` (same inputs, same output); use whichever name you prefer. Read-only.'
 };
 function countStalledP1(warnings) {
@@ -26196,6 +26315,17 @@ ${versionDrift}` : "";
 ${section}`;
     } catch {
     }
+    let deferredGateNote = "";
+    if (deepHousekeeping) {
+      try {
+        const sweep = await tracked("deferred-gates", () => findDeferredGates(adapter2))();
+        const section = formatDeferredGateSection(sweep);
+        if (section) deferredGateNote = `
+
+${section}`;
+      } catch {
+      }
+    }
     tracker.mark("format-summary");
     const subAgents = await listAgents(config2.projectRoot);
     const [teamSummaryLine, releaseHistoryLine] = await Promise.all([
@@ -26204,7 +26334,7 @@ ${section}`;
     ]);
     const teamSummary = [teamSummaryLine, releaseHistoryLine].filter(Boolean).join("\n") || void 0;
     const deepHint = deepHousekeeping ? "" : "\n\n*Tip: pass `full: true` for Research Signals + version-drift, or `deep_housekeeping: true` to also check orphaned branches, merged-but-In-Progress tasks, unrecorded commits, unregistered docs, and stale skill forks (implies `full`).*";
-    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName) + unblockNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
+    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName) + unblockNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const isKnownFriendly = /^(Orient failed|Project not found|No project|Setup required)/i.test(message);
@@ -26260,7 +26390,7 @@ function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, client
 var hierarchyUpdateTool = {
   name: "hierarchy_update",
   description: "Update the status of a phase, stage, or horizon in the project hierarchy (AD-14). Accepts a level (phase, stage, or horizon), a name or ID, and a new status. For stages, optionally set exit_criteria \u2014 a checklist defining when the stage is considered done. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Update Hierarchy", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -26671,7 +26801,7 @@ async function applyZoomOut(adapter2, llmResponse, cycleNumber) {
 var zoomOutTool = {
   name: "zoom_out",
   description: 'Run a Zoom-Out Retrospective \u2014 a higher-level meta-retrospective that sits above strategy reviews. Analyses the full project arc: every cycle, decision, and pivot. Use when you want to step back and see the big picture after many cycles. First call returns a prompt (prepare phase). Then call again with mode "apply" and your output.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Zoom Out", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -26775,7 +26905,7 @@ ${result.userMessage}
 var getSiblingAdsTool = {
   name: "get_sibling_ads",
   description: "Read Active Decisions from sibling PAPI projects that share the same Supabase instance. Requires PAPI_SIBLING_PROJECT_IDS env var (comma-separated project UUIDs). Returns ADs labelled by source project \u2014 useful for cross-project architectural alignment. pg adapter only \u2014 returns an error if using md or proxy adapter.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "Sibling Decisions", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -26852,7 +26982,7 @@ var handoffPrepareCache = new PerCallerCache();
 var handoffGenerateTool = {
   name: "handoff_generate",
   description: "Generate BUILD HANDOFFs for cycle tasks that don't have one yet. Run after `plan` (with skip_handoffs=true) or to regenerate stale handoffs. Uses the prepare/apply pattern \u2014 first call returns a prompt, second call persists results.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Generate Handoff", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27108,7 +27238,7 @@ function buildSummary(task, taskCount) {
 var scopeBriefTool = {
   name: "scope_brief",
   description: "Decompose a brief-class task (Large/XL, too large to build directly) into a structured scope document. Runs an LLM pass to produce sub-tasks, writes docs/scopes/<task-id>.md, registers it in the doc registry, and marks the source task as decomposed. Use before planning a cycle that includes brief-class tasks.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Scope Brief", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27157,7 +27287,7 @@ async function handleScopeBrief(adapter2, config2, args) {
 var adViewTool = {
   name: "ad_view",
   description: "View one or all Active Decisions with full bodies. Use when you need to read the complete reasoning and evidence behind a specific AD before running strategy_change.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "View Decisions", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27214,7 +27344,7 @@ ${formatted}`);
 var learningActionTool = {
   name: "learning_action",
   description: `Mark a cycle learning as actioned (linking it to a task or idea) or list unactioned learnings. Use "mark" to close out a learning after you've submitted an idea or created a task for it. Use "list" to see which learnings from recent cycles still need follow-up.`,
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Action Learning", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27300,7 +27430,7 @@ Use \`learning_action mark\` or submit via \`idea\` to close these out.`
 var discoveredIssueResolveTool = {
   name: "discovered_issue_resolve",
   description: 'Mark a discovered_issue (cycle_learnings row, category="issue") as resolved. Pass the learning_id you saw in orient / learning_action list output. The row stays in the database for history, but default reads exclude it. Use this when the underlying fix has actually landed \u2014 NOT when you just created a follow-up task (that is `learning_action mark` with action_taken="task_created"). Optional `note` is recorded as resolved_by.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Resolve Issue", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27399,7 +27529,7 @@ var NO_SUPPORT = "Project lifecycle tools require a hosted (proxy) or PostgreSQL
 var projectCreateTool = {
   name: "project_create",
   description: 'Create an EMPTY PAPI project for the current workspace (no plan, no seeded backlog) and return its id. Idempotent: re-running in the same folder (or with the same name) returns the EXISTING project instead of creating a duplicate. Use when "set up papi here" / "create a project" and none matches this folder. No Anthropic API.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Create Project", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27445,7 +27575,7 @@ Run \`plan\` when you're ready to start a cycle.`
 var projectListTool = {
   name: "project_list",
   description: "List the PAPI projects on your account (id, name, slug, mapped folder). Use to see which project you are about to write to, or to find the id/slug to pass to project_switch or the per-call `project` arg. No Anthropic API.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "List Projects", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27476,7 +27606,7 @@ ${lines.join("\n")}`);
 var projectSwitchTool = {
   name: "project_switch",
   description: 'Select a project you own by id or slug and map the current folder to it (sets papi_dir on local stdio). Use when "switch to golf" / "point papi at <project>". Fails closed if the project is not on your account. No Anthropic API.',
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Switch Project", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27511,7 +27641,7 @@ On hosted/remote sessions this is now your DEFAULT project \u2014 calls without
 var contributorAddTool = {
   name: "contributor_add",
   description: "Add a contributor to the current project by email (owner-only). The person must already have a PAPI account. Grants cohort membership on project_contributors \u2014 contributors-tier visibility, no roles yet.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Add Contributor", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27523,7 +27653,7 @@ var contributorAddTool = {
 var contributorRemoveTool = {
   name: "contributor_remove",
   description: "Remove a contributor from the current project by email (owner-only). Deletes their project_contributors row \u2014 they lose contributors-tier visibility.",
-  annotations: { readOnlyHint: false, destructiveHint: true },
+  annotations: { title: "Remove Contributor", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27535,7 +27665,7 @@ var contributorRemoveTool = {
 var contributorListTool = {
   name: "contributor_list",
   description: "List the current project's contributors (any project member). Shows each member's email, display name, role, and join date. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: true, destructiveHint: false },
+  annotations: { title: "List Contributors", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27641,7 +27771,7 @@ async function handleContributorList(adapter2, config2, _args) {
 var taskClaimTool = {
   name: "task_claim",
   description: "Claim a task from the shared org Pool into your personal backlog (assignee = you). Atomic first-claim-wins \u2014 a concurrent double-claim is impossible. Cascades the DEPENDS ON chain: claiming a task also claims its not-Done prerequisites; if any prerequisite is already claimed by another member the whole claim is refused (a build unit is never split across owners). Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Claim Task", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27653,7 +27783,7 @@ var taskClaimTool = {
 var taskUnclaimTool = {
   name: "task_unclaim",
   description: "Release a task you claimed back to the shared Pool (clears assignee). Claimer-only and pre-review \u2014 you cannot unclaim another member's task or one that has reached In Review/Done. Does not cascade. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: true },
+  annotations: { title: "Unclaim Task", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27790,7 +27920,7 @@ async function handleTaskUnclaim(adapter2, config2, args) {
 var taskMoveTool = {
   name: "task_move",
   description: "Move a task from the current project to another project you own. Reassigns the task a fresh id in the target (collision-free) and carries its build reports, comments, and history with it; the cycle assignment is cleared so it lands in the target project's backlog. You must own (or have write access to) BOTH projects. Destructive-ish and cross-project, so it requires confirm=true \u2014 without it you get a preview only. Does not call the Anthropic API.",
-  annotations: { readOnlyHint: false, destructiveHint: true },
+  annotations: { title: "Move Task", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -27977,7 +28107,7 @@ async function syncHarnessInventory(adapter2, config2, opts) {
 var inventorySyncTool = {
   name: "inventory_sync",
   description: "Sync this project's harness inventory \u2014 skills, sub-agents, hooks, and MCP tools \u2014 to the database so the dashboard can surface it. Gated by a cheap change-fingerprint: a no-op when the harness hasn't changed since the last sync. Set force=true to re-scan and write regardless. Runs automatically at setup and release; use this for an explicit refresh after editing your harness.",
-  annotations: { readOnlyHint: false, destructiveHint: false },
+  annotations: { title: "Sync Inventory", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.51",
+  "version": "0.7.52",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "mcpName": "io.github.getpapi/papi",