@papi-ai/server 0.7.35 → 0.7.36

package/dist/index.js

@@ -4639,13 +4639,35 @@ import {
 
 // src/config.ts
 import path from "path";
+
+// src/lib/help-text.ts
+var PAPI_DISCORD = "https://discord.gg/papi";
+var PAPI_DOCS = "https://getpapi.ai/docs/install";
+var HELP_FOOTER = `
+Need a hand?
+  \u2022 Make sure you're in your project's root folder (where your code lives), then say "run setup".
+  \u2022 Diagnose your setup:  npx @papi-ai/server doctor
+  \u2022 Hit a PAPI bug or have an idea? Say "report a bug to PAPI" \u2014 it goes straight to the
+    PAPI team (not your project backlog), with diagnostics attached.
+  \u2022 Get help: ${PAPI_DISCORD}   \u2022   Docs: ${PAPI_DOCS}
+`;
+var HELP_FOOTER_MD = `
+
+## Need a hand?
+- Make sure you're in your project's **root folder** (where your code lives), then say "run setup".
+- Diagnose your setup: \`npx @papi-ai/server doctor\`
+- Hit a PAPI bug or have an idea? Say **"report a bug to PAPI"** \u2014 it goes straight to the PAPI team (not your project backlog), with diagnostics attached.
+- Get help: [Discord](${PAPI_DISCORD}) \xB7 [Docs](${PAPI_DOCS})
+`;
+
+// src/config.ts
 function loadConfig() {
   const projectArgIdx = process.argv.indexOf("--project");
   const configuredRoot = projectArgIdx !== -1 ? process.argv[projectArgIdx + 1] : process.env.PAPI_PROJECT_DIR;
   const projectRoot = configuredRoot ?? process.cwd();
   if (!configuredRoot) {
     process.stderr.write(
-      '\nPAPI is running but no project is configured.\nSay "run setup" to get started.\n\n'
+      "\nPAPI is running, but no project is configured here.\n" + HELP_FOOTER + "\n"
     );
   }
   const anthropicApiKey = process.env.PAPI_API_KEY ?? "";
@@ -4693,7 +4715,7 @@ If you intentionally self-host, set PAPI_SELF_HOST=1 in your environment to bypa
   }
   if (databaseUrl && !papiEndpoint && !explicitAdapter && !selfHostOptIn && !dataApiKey) {
     throw new Error(
-      'DATABASE_URL is set but PAPI_ADAPTER is not specified.\n\nIf you want to self-host PAPI against your own database, add to your .mcp.json env:\n  "PAPI_ADAPTER": "pg"\n\nIf you are an external user with a PAPI account, remove DATABASE_URL from your config.\nExternal users authenticate via PAPI_DATA_API_KEY \u2014 no DATABASE_URL needed.\n\nInstall guide: https://getpapi.ai/docs/install'
+      'DATABASE_URL is set but PAPI_ADAPTER is not specified.\n\nIf you want to self-host PAPI against your own database, add to your .mcp.json env:\n  "PAPI_ADAPTER": "pg"\n\nIf you are an external user with a PAPI account, remove DATABASE_URL from your config.\nExternal users authenticate via PAPI_DATA_API_KEY \u2014 no DATABASE_URL needed.\n' + HELP_FOOTER
     );
   }
   let adapterType = papiEndpoint ? "pg" : databaseUrl && (explicitAdapter === "pg" || selfHostOptIn) ? "pg" : dataEndpoint ? "proxy" : explicitAdapter ? explicitAdapter : "proxy";
@@ -4712,7 +4734,8 @@ and unlocks dashboard features when you're ready.
 After signing up, add this to your .mcp.json env config:
   "PAPI_USER_ID": "your-email@example.com"
 
-Already have an account? Make sure PAPI_USER_ID is set in your .mcp.json env config.`
+Already have an account? Make sure PAPI_USER_ID is set in your .mcp.json env config.
+` + HELP_FOOTER
     );
   }
   return {
@@ -8484,7 +8507,8 @@ Standard planning cycle with full board review.
    - **P1 High** \u2014 Strategically aligned: directly advances the current horizon, phase, or Active Decision goals.
    - **P2 Medium** \u2014 Valuable but not strategically urgent: quality improvements, efficiency, polish, infra.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
-   Within the same priority level, prefer tasks with the highest **impact-to-effort ratio**. Impact is measured by: (a) strategic alignment \u2014 does it advance the current horizon/phase? (b) unlocks other work \u2014 are tasks blocked by this? (c) user-facing \u2014 does it change what users see? (d) compounds over time \u2014 does it make future cycles faster? A high-impact Medium task beats a low-impact Small task at the same priority level. Justify in 2-3 sentences.
+   Within the same priority level, prefer tasks with the highest **impact-to-effort ratio**. Impact is measured by: (a) strategic alignment \u2014 does it advance the current horizon/phase? (b) unlocks other work \u2014 are tasks blocked by this? (c) user-facing \u2014 does it change what users see? (d) compounds over time \u2014 does it make future cycles faster? A high-impact Medium task beats a low-impact Small task at the same priority level. **Capacity-fit (smaller effort) breaks ties between comparable-impact tasks \u2014 it does NOT outrank impact.** Do NOT let a task's smaller size be the deciding factor that repeatedly defers a higher-impact larger task; that is the exact failure mode this step guards against. Justify in 2-3 sentences.
+   **\u26A0\uFE0F Large-task inclusion guarantee (task-2227, structural rule \u2014 not advisory):** Impact weighting alone has historically lost to capacity-fit \u2014 the planner repeatedly filled cycles with XS/S work and deferred high-impact L/XL P1s (9 P1s stalled 6-21 cycles as of C299; C297 named this the "sequencing inversion"). Enforce a HARD rule: **every cycle MUST contain at least one Large or XL strategically-aligned P1 task, UNLESS no unblocked L/XL P1 exists on the board.** Before finalising the selection, scan the candidate pool: if the selected cycle contains zero L/XL tasks AND \u22651 unblocked L/XL P1 exists in the backlog, you MUST force-include the highest-impact such task \u2014 displacing the lowest-impact small task if the budget requires it (respect the single-theme vs mixed-theme budget from the Cycle-sizing rule below rather than always adding on top of an already-full cycle). Record the outcome in a "Large-task guarantee:" line in \`cycleLogNotes\`: name the task the guarantee pulled in, OR "satisfied \u2014 cycle already contains an L/XL task", OR "no unblocked L/XL P1 on the board". Do NOT skip this because the small tasks look individually attractive \u2014 that attractiveness IS the bias.
    **Blocked tasks:** Tasks with status "Blocked" MUST be skipped during task selection \u2014 they are waiting on external dependencies or gates and cannot be built. Do NOT generate BUILD HANDOFFs for blocked tasks. Do NOT recommend blocked tasks. If a blocked task's gate has been resolved (check the notes and recent build reports), emit a \`boardCorrections\` entry to move it back to Backlog. Report blocked task count in the cycle log.
    **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 6-10 tasks. Cycles with fewer than 5 tasks require explicit justification in the cycle log \u2014 explain why more tasks could not be included. When the backlog has 10+ tasks, the cycle SHOULD have 6+ tasks \u2014 undersized cycles waste planning overhead relative to the available work. If fewer than 5 tasks qualify after filtering (blocked, deferred, raw), check Deferred tasks \u2014 some may be ready to un-defer via a \`boardCorrections\` entry. A 1-task cycle is almost never correct. Prefer grouping tasks by module or similarity \u2014 reduces context switching and enables shared branches during the build phase.
    **Theme-driven sizing:** Single-theme cycles (all tasks in the same module or epic) can absorb 25-30 effort points because builders maintain context across tasks. Mixed-theme cycles should stay at 15-20 effort points to limit context switching. Use the theme to determine the budget, not a fixed number.
@@ -12016,6 +12040,7 @@ function defaultHint(tool) {
     "plan",
     "strategy_review",
     "orient",
+    "papi",
     "build_execute",
     "review_list",
     "review_submit",
@@ -20239,6 +20264,20 @@ async function captureBug(adapter2, input) {
 }
 
 // src/tools/bug.ts
+var PAPI_SIGNAL_PATTERNS = [
+  /\bpapi\b/i,
+  /\bmcp\b/i,
+  // Distinctive PAPI MCP tool names (whole-word) — these don't appear in an
+  // everyday project-domain bug report.
+  /\b(orient|build_execute|build_list|build_describe|build_cancel|review_submit|review_list|strategy_review|strategy_change|board_view|board_edit|board_deprioritise|board_reconcile|handoff_generate|doc_register|doc_search|ad_hoc|inventory_sync|scope_brief)\b/i,
+  /\bbuild handoff\b/i,
+  /\bremote connector\b/i
+];
+function looksLikePapiBug(text, notes) {
+  const haystack = `${text}
+${notes ?? ""}`;
+  return PAPI_SIGNAL_PATTERNS.some((re) => re.test(haystack));
+}
 function collectDiagnostics(config2) {
   return {
     nodeVersion: process.version,
@@ -20252,7 +20291,7 @@ function collectDiagnostics(config2) {
 }
 var bugTool = {
   name: "bug",
-  description: "Report a bug OR submit an idea to PAPI. Two modes: (1) Default \u2014 creates a Backlog task with severity-based priority for the project board. (2) With report=true \u2014 submits a bug or idea (set `type`) upstream to PAPI maintainers with diagnostics, optionally recording notify-when-fixed and contact-ok consent. Use report=true at a friction moment \u2014 e.g. when a PAPI tool returns a workflow-blocking error. Does not call the Anthropic API.",
+  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. Override the routing explicitly: report=true forces upstream, 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 },
   inputSchema: {
     type: "object",
@@ -20284,7 +20323,7 @@ var bugTool = {
       },
       report: {
         type: "boolean",
-        description: "When true, submits a diagnostic bug report with system info instead of creating a board task. Use this to report issues to PAPI maintainers."
+        description: "Routing override. Leave UNSET to auto-route: PAPI-product bugs go upstream to maintainers, project-domain bugs go to the user's board. Set true to force an upstream diagnostic submission; set false to force a task on the user's own board (use false when an auto-detected PAPI bug is actually about the user's project)."
       },
       type: {
         type: "string",
@@ -20312,8 +20351,18 @@ async function handleBug(adapter2, config2, args) {
   if (!text) {
     return errorResponse("text is required \u2014 describe the bug you want to report.");
   }
-  if (args.report === true) {
+  const notesArg = args.notes;
+  const explicitReport = typeof args.report === "boolean" ? args.report : void 0;
+  const papiBug = looksLikePapiBug(text, notesArg);
+  const autoRoutedUpstream = explicitReport === void 0 && papiBug;
+  const shouldReportUpstream = explicitReport === true || autoRoutedUpstream;
+  if (shouldReportUpstream) {
     if (!adapter2.submitBugReport) {
+      if (autoRoutedUpstream) {
+        return errorResponse(
+          `This looks like a PAPI bug, which belongs upstream with the PAPI maintainers \u2014 but upstream reporting needs a database adapter (pg or proxy) and this session uses the md adapter, which can't submit it. Two options: (1) switch to the hosted/pg setup to report it upstream, or (2) re-run with report=false to file it on your own project board instead.`
+        );
+      }
       return errorResponse("Bug reports require a database adapter (pg or proxy). The md adapter does not support bug reports.");
     }
     const type = args.type === "idea" ? "idea" : "bug";
@@ -20348,13 +20397,16 @@ async function handleBug(adapter2, config2, args) {
     const followUpLine = followUps.length ? `
 
 Noted: ${followUps.join("; ")}.` : "";
+    const autoRouteLine = autoRoutedUpstream ? `
+
+_Detected this as a PAPI bug and sent it upstream rather than adding it to your own board. If it's actually about your project, re-run with \`report=false\` to file it on your board instead._` : "";
     return textResponse(
       `**${kindLabel} submitted** \u2014 ID: \`${report.id}\`
 
 ${type === "idea" ? "Idea" : "Description"}: ${text}
 Diagnostics collected: Node ${diagnostics.nodeVersion}, ${diagnostics.platform}/${diagnostics.arch}, adapter=${diagnostics.adapterType}
 
-This ${type} is visible to PAPI maintainers.${followUpLine}`
+This ${type} is visible to PAPI maintainers.${followUpLine}${autoRouteLine}`
     );
   }
   let target = adapter2;
@@ -22745,7 +22797,7 @@ ${lines.join("\n")}`;
 
 // src/lib/version-handshake.ts
 var MIN_PROXY_VERSION = "1.0.0";
-var SERVER_VERSION = "0.7.35";
+var SERVER_VERSION = "0.7.36";
 function meetsMinVersion(actual, required) {
   const actualParts = actual.split(".").map((n) => parseInt(n, 10));
   const requiredParts = required.split(".").map((n) => parseInt(n, 10));
@@ -23564,6 +23616,11 @@ var orientTool = {
     required: []
   }
 };
+var papiTool = {
+  ...orientTool,
+  name: "papi",
+  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) {
   const stallLine = warnings.find((w) => w.includes("P1 tasks stalled"));
   if (!stallLine) return 0;
@@ -26093,6 +26150,8 @@ var ABUSE_CEILINGS = {
 var DEFAULT_CEILING = ABUSE_CEILINGS.free;
 var ALWAYS_FREE_TOOLS = /* @__PURE__ */ new Set([
   "orient",
+  "papi",
+  // alias for orient (task-2223) — must share its free treatment
   "board_view",
   "build_list",
   "build_describe",
@@ -26242,6 +26301,7 @@ var TOOLS_REQUIRING_PAPI = /* @__PURE__ */ new Set([
   "review_list",
   "review_submit",
   "orient",
+  "papi",
   "hierarchy_update",
   "zoom_out",
   "handoff_generate",
@@ -26273,6 +26333,7 @@ var PAPI_TOOLS = [
   reviewClaimTool,
   initTool,
   orientTool,
+  papiTool,
   hierarchyUpdateTool,
   zoomOutTool,
   docRegisterTool,
@@ -26447,6 +26508,9 @@ function createServer(adapter2, config2) {
           return handleInit(config2, safeArgs);
         case "orient":
           return handleOrient(adapter2, config2, safeArgs);
+        case "papi":
+          return handleOrient(adapter2, config2, safeArgs);
+        // alias (task-2223)
         case "hierarchy_update":
           return handleHierarchyUpdate(adapter2, safeArgs);
         case "zoom_out":
@@ -26518,7 +26582,7 @@ function createServer(adapter2, config2) {
       }
       throw err;
     }
-    if (name === "orient" && adapter2.getMeteredUsage && !result.content.some((c) => c.text.startsWith("Error:"))) {
+    if ((name === "orient" || name === "papi") && adapter2.getMeteredUsage && !result.content.some((c) => c.text.startsWith("Error:"))) {
       try {
         const decision = await checkMeter(adapter2, "plan", config2.projectId ?? "session");
         if (decision.usage) {
@@ -27108,7 +27172,7 @@ If you haven't set up PAPI yet:
 2. Complete the onboarding wizard \u2014 it generates your config
 3. Copy the config to your project and restart your AI tool
 
-If you already have an account, check that both **PAPI_PROJECT_ID** and **PAPI_DATA_API_KEY** are set in your .mcp.json env config.`
+If you already have an account, check that both **PAPI_PROJECT_ID** and **PAPI_DATA_API_KEY** are set in your .mcp.json env config.` + HELP_FOOTER_MD
       }]
     }));
   }

package/dist/prompts.js

@@ -343,7 +343,8 @@ Standard planning cycle with full board review.
    - **P1 High** \u2014 Strategically aligned: directly advances the current horizon, phase, or Active Decision goals.
    - **P2 Medium** \u2014 Valuable but not strategically urgent: quality improvements, efficiency, polish, infra.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
-   Within the same priority level, prefer tasks with the highest **impact-to-effort ratio**. Impact is measured by: (a) strategic alignment \u2014 does it advance the current horizon/phase? (b) unlocks other work \u2014 are tasks blocked by this? (c) user-facing \u2014 does it change what users see? (d) compounds over time \u2014 does it make future cycles faster? A high-impact Medium task beats a low-impact Small task at the same priority level. Justify in 2-3 sentences.
+   Within the same priority level, prefer tasks with the highest **impact-to-effort ratio**. Impact is measured by: (a) strategic alignment \u2014 does it advance the current horizon/phase? (b) unlocks other work \u2014 are tasks blocked by this? (c) user-facing \u2014 does it change what users see? (d) compounds over time \u2014 does it make future cycles faster? A high-impact Medium task beats a low-impact Small task at the same priority level. **Capacity-fit (smaller effort) breaks ties between comparable-impact tasks \u2014 it does NOT outrank impact.** Do NOT let a task's smaller size be the deciding factor that repeatedly defers a higher-impact larger task; that is the exact failure mode this step guards against. Justify in 2-3 sentences.
+   **\u26A0\uFE0F Large-task inclusion guarantee (task-2227, structural rule \u2014 not advisory):** Impact weighting alone has historically lost to capacity-fit \u2014 the planner repeatedly filled cycles with XS/S work and deferred high-impact L/XL P1s (9 P1s stalled 6-21 cycles as of C299; C297 named this the "sequencing inversion"). Enforce a HARD rule: **every cycle MUST contain at least one Large or XL strategically-aligned P1 task, UNLESS no unblocked L/XL P1 exists on the board.** Before finalising the selection, scan the candidate pool: if the selected cycle contains zero L/XL tasks AND \u22651 unblocked L/XL P1 exists in the backlog, you MUST force-include the highest-impact such task \u2014 displacing the lowest-impact small task if the budget requires it (respect the single-theme vs mixed-theme budget from the Cycle-sizing rule below rather than always adding on top of an already-full cycle). Record the outcome in a "Large-task guarantee:" line in \`cycleLogNotes\`: name the task the guarantee pulled in, OR "satisfied \u2014 cycle already contains an L/XL task", OR "no unblocked L/XL P1 on the board". Do NOT skip this because the small tasks look individually attractive \u2014 that attractiveness IS the bias.
    **Blocked tasks:** Tasks with status "Blocked" MUST be skipped during task selection \u2014 they are waiting on external dependencies or gates and cannot be built. Do NOT generate BUILD HANDOFFs for blocked tasks. Do NOT recommend blocked tasks. If a blocked task's gate has been resolved (check the notes and recent build reports), emit a \`boardCorrections\` entry to move it back to Backlog. Report blocked task count in the cycle log.
    **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 6-10 tasks. Cycles with fewer than 5 tasks require explicit justification in the cycle log \u2014 explain why more tasks could not be included. When the backlog has 10+ tasks, the cycle SHOULD have 6+ tasks \u2014 undersized cycles waste planning overhead relative to the available work. If fewer than 5 tasks qualify after filtering (blocked, deferred, raw), check Deferred tasks \u2014 some may be ready to un-defer via a \`boardCorrections\` entry. A 1-task cycle is almost never correct. Prefer grouping tasks by module or similarity \u2014 reduces context switching and enables shared branches during the build phase.
    **Theme-driven sizing:** Single-theme cycles (all tasks in the same module or epic) can absorb 25-30 effort points because builders maintain context across tasks. Mixed-theme cycles should stay at 15-20 effort points to limit context switching. Use the theme to determine the budget, not a fixed number.

package/package.json

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