@papi-ai/server 0.7.63 → 0.7.64

package/dist/backfill-cycle-metrics.js

@@ -1210,12 +1210,12 @@ var init_proxy_adapter = __esm({
       "listContributorReleasePrs",
       "claimReview",
       "getSiblingAds",
-      "getSiblingRepoTasks",
-      // task-2828 (C339): attributed-intelligence analytics reader — pg-only this cycle.
-      // Hosted forwarding needs a SECURITY DEFINER RPC + edge handler (like task-2394 did
-      // for getModuleEstimationStats); until then keep it here so hosted degrades to a
-      // safe `undefined` rather than forwarding into a 403. Wire under task-2390.
-      "getModelOutcomeStats"
+      "getSiblingRepoTasks"
+      // task-2828 (C339): attributed-intelligence analytics reader — pg-only that cycle.
+      // task-2864 (C343): WIRED. getModelOutcomeStats now has an edge case handler (raw
+      // SQL via postgres.js mirroring the pg query + inlined computeModelOutcomes bucketing)
+      // + an ALLOWED_METHODS entry, so it forwards. countPlanRunsForCycle wired alongside it
+      // (task-2860's auto-release guard reader). Both REMOVED from NO_FORWARD.
       // task-2394 (C329) — Batch A wired: findPendingDocActionsForTask,
       // getModuleEstimationStats and getDecisionScorePatterns now have edge case handlers
       // (each backed by a SECURITY DEFINER RPC, migration 20260714140000) plus
@@ -1348,7 +1348,8 @@ var init_proxy_adapter = __esm({
           if (response.status === 401) {
             throw new Error(
               `Auth: Invalid API key \u2014 PAPI_DATA_API_KEY was rejected by the proxy.
-Check PAPI_DATA_API_KEY in your .mcp.json config. You can regenerate it from the PAPI dashboard.
+This usually means the key was revoked or replaced. Mint a fresh key in the Connect panel on your PAPI dashboard (https://getpapi.ai/hub), then update PAPI_DATA_API_KEY in your .mcp.json.
+Moving off a local install? Switch to the remote MCP: https://getpapi.ai/docs/install
 (${response.status} on ${method}: ${message})`
             );
           }
@@ -2220,6 +2221,9 @@ var SECTION_HEADERS = [
   "FILES LIKELY TOUCHED",
   "EFFORT"
 ];
+function normaliseHeaderLine(line) {
+  return line.trim().replace(/^#{1,6}\s*/, "").replace(/^-\s+/, "").replace(/^\*\*(.*?)\*\*$/, "$1").replace(/:\s*$/, "").trim();
+}
 function splitSections(text) {
   const sections = /* @__PURE__ */ new Map();
   const lines = text.split("\n");
@@ -2232,8 +2236,8 @@ function splitSections(text) {
     }
   };
   for (const line of lines) {
-    const trimmed = line.trim();
-    const matched = SECTION_HEADERS.find((h) => trimmed === h);
+    const normalised = normaliseHeaderLine(line);
+    const matched = SECTION_HEADERS.find((h) => normalised === h);
     if (matched) {
       flush();
       currentSection = matched;
@@ -2254,7 +2258,10 @@ function parseChecklist(text) {
   return text.split("\n").map((l) => l.replace(/^\s*\[[ x]]\s*/, "").trim()).filter((l) => l.length > 0);
 }
 function parseBuildHandoff(markdown) {
-  if (!markdown.includes("BUILD HANDOFF")) return null;
+  if (typeof markdown !== "string" || !markdown.trim()) return null;
+  if (!markdown.includes("BUILD HANDOFF") && splitSections(markdown).size === 0) {
+    return null;
+  }
   const taskIdMatch = markdown.match(/BUILD HANDOFF\s*—\s*(task-\d+)/);
   const taskTitleMatch = markdown.match(/^Task:\s*(.+)$/m);
   const cycleMatch = markdown.match(/^Cycle:\s*(\d+)$/m);

package/dist/index.js

@@ -1327,12 +1327,12 @@ var init_proxy_adapter = __esm({
       "listContributorReleasePrs",
       "claimReview",
       "getSiblingAds",
-      "getSiblingRepoTasks",
-      // task-2828 (C339): attributed-intelligence analytics reader — pg-only this cycle.
-      // Hosted forwarding needs a SECURITY DEFINER RPC + edge handler (like task-2394 did
-      // for getModuleEstimationStats); until then keep it here so hosted degrades to a
-      // safe `undefined` rather than forwarding into a 403. Wire under task-2390.
-      "getModelOutcomeStats"
+      "getSiblingRepoTasks"
+      // task-2828 (C339): attributed-intelligence analytics reader — pg-only that cycle.
+      // task-2864 (C343): WIRED. getModelOutcomeStats now has an edge case handler (raw
+      // SQL via postgres.js mirroring the pg query + inlined computeModelOutcomes bucketing)
+      // + an ALLOWED_METHODS entry, so it forwards. countPlanRunsForCycle wired alongside it
+      // (task-2860's auto-release guard reader). Both REMOVED from NO_FORWARD.
       // task-2394 (C329) — Batch A wired: findPendingDocActionsForTask,
       // getModuleEstimationStats and getDecisionScorePatterns now have edge case handlers
       // (each backed by a SECURITY DEFINER RPC, migration 20260714140000) plus
@@ -1465,7 +1465,8 @@ var init_proxy_adapter = __esm({
           if (response.status === 401) {
             throw new Error(
               `Auth: Invalid API key \u2014 PAPI_DATA_API_KEY was rejected by the proxy.
-Check PAPI_DATA_API_KEY in your .mcp.json config. You can regenerate it from the PAPI dashboard.
+This usually means the key was revoked or replaced. Mint a fresh key in the Connect panel on your PAPI dashboard (https://getpapi.ai/hub), then update PAPI_DATA_API_KEY in your .mcp.json.
+Moving off a local install? Switch to the remote MCP: https://getpapi.ai/docs/install
 (${response.status} on ${method}: ${message})`
             );
           }
@@ -4333,7 +4334,7 @@ __export(doctor_exports, {
   __testing: () => __testing,
   runDoctor: () => runDoctor
 });
-import { existsSync as existsSync11, readFileSync as readFileSync12 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync13 } from "fs";
 import { homedir as homedir4 } from "os";
 import { join as join20 } from "path";
 function redact(name, value) {
@@ -4353,7 +4354,7 @@ function findMcpJson() {
   for (const path7 of candidates) {
     if (!existsSync11(path7)) continue;
     try {
-      const raw = readFileSync12(path7, "utf-8");
+      const raw = readFileSync13(path7, "utf-8");
       const parsed = JSON.parse(raw);
       const papiEntry = parsed.papi ?? parsed.mcpServers?.papi;
       if (!papiEntry) continue;
@@ -4631,7 +4632,7 @@ __export(reset_exports, {
   removePapiEntry: () => removePapiEntry,
   runReset: () => runReset
 });
-import { existsSync as existsSync12, readFileSync as readFileSync13, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync14, writeFileSync as writeFileSync6 } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join21 } from "path";
 import { createInterface } from "readline/promises";
@@ -4641,7 +4642,7 @@ function findResetTarget() {
     let raw;
     let parsed;
     try {
-      raw = readFileSync13(path7, "utf-8");
+      raw = readFileSync14(path7, "utf-8");
       parsed = JSON.parse(raw);
     } catch {
       continue;
@@ -4742,7 +4743,7 @@ __export(audit_exports, {
   __testing: () => __testing2,
   runAudit: () => runAudit
 });
-import { existsSync as existsSync13, readFileSync as readFileSync14, readdirSync as readdirSync7 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync15, readdirSync as readdirSync7 } from "fs";
 import { homedir as homedir6 } from "os";
 import { join as join22 } from "path";
 function safeListDirs(dir) {
@@ -4763,7 +4764,7 @@ function readMcp(projectPath) {
   const path7 = join22(projectPath, ".mcp.json");
   if (!existsSync13(path7)) return { servers: [] };
   try {
-    const parsed = JSON.parse(readFileSync14(path7, "utf-8"));
+    const parsed = JSON.parse(readFileSync15(path7, "utf-8"));
     const mcpServers = parsed.mcpServers ?? {};
     const servers = Object.keys(mcpServers);
     if (parsed.papi && !servers.includes("papi")) servers.push("papi");
@@ -4819,7 +4820,7 @@ function readGlobalSkills() {
 function readGlobalMcpServers() {
   if (!existsSync13(GLOBAL_CLAUDE_JSON)) return [];
   try {
-    const parsed = JSON.parse(readFileSync14(GLOBAL_CLAUDE_JSON, "utf-8"));
+    const parsed = JSON.parse(readFileSync15(GLOBAL_CLAUDE_JSON, "utf-8"));
     const servers = parsed.mcpServers ?? {};
     return Object.keys(servers).sort((a, b2) => a.localeCompare(b2));
   } catch {
@@ -4985,7 +4986,7 @@ var setup_exports = {};
 __export(setup_exports, {
   runSetup: () => runSetup
 });
-import { existsSync as existsSync14, readFileSync as readFileSync15, writeFileSync as writeFileSync7, chmodSync as chmodSync2, statSync as statSync7 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync16, writeFileSync as writeFileSync7, chmodSync as chmodSync2, statSync as statSync8 } from "fs";
 import { join as join23 } from "path";
 function baseUrl() {
   const fromEnv = process.env["PAPI_HOST"] ?? process.env["PAPI_BASE_URL"];
@@ -5022,7 +5023,7 @@ function writeMcpJson(opts) {
   let parsed = {};
   if (existsSync14(path7)) {
     try {
-      parsed = JSON.parse(readFileSync15(path7, "utf-8"));
+      parsed = JSON.parse(readFileSync16(path7, "utf-8"));
     } catch {
       throw new Error(`.mcp.json at ${path7} is not valid JSON. Fix it or remove it before re-running setup.`);
     }
@@ -5045,7 +5046,7 @@ function writeMcpJson(opts) {
   parsed.mcpServers = mcpServers;
   writeFileSync7(path7, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
   try {
-    const mode = statSync7(path7).mode & 511;
+    const mode = statSync8(path7).mode & 511;
     if (mode !== 384) chmodSync2(path7, 384);
   } catch {
   }
@@ -5153,7 +5154,7 @@ var init_setup = __esm({
 });
 
 // src/index.ts
-import { readFileSync as readFileSync16 } from "fs";
+import { readFileSync as readFileSync17 } from "fs";
 import { dirname as dirname6, join as join24, basename as basename2 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -5199,7 +5200,6 @@ function loadConfig() {
       "\nPAPI is running, but no project is configured here.\n" + HELP_FOOTER + "\n"
     );
   }
-  const anthropicApiKey = process.env.PAPI_API_KEY ?? "";
   const autoCommit2 = process.env.PAPI_AUTO_COMMIT !== "false";
   const baseBranch = process.env.PAPI_BASE_BRANCH ?? "main";
   const autoPR = process.env.PAPI_AUTO_PR !== "false";
@@ -5273,7 +5273,6 @@ Already have an account? Make sure PAPI_USER_ID is set in your .mcp.json env con
   return {
     projectRoot,
     papiDir: path.join(projectRoot, ".papi"),
-    anthropicApiKey,
     autoCommit: autoCommit2,
     baseBranch,
     autoPR,
@@ -5564,6 +5563,9 @@ var SECTION_HEADERS = [
   "FILES LIKELY TOUCHED",
   "EFFORT"
 ];
+function normaliseHeaderLine(line) {
+  return line.trim().replace(/^#{1,6}\s*/, "").replace(/^-\s+/, "").replace(/^\*\*(.*?)\*\*$/, "$1").replace(/:\s*$/, "").trim();
+}
 function splitSections(text) {
   const sections = /* @__PURE__ */ new Map();
   const lines = text.split("\n");
@@ -5576,8 +5578,8 @@ function splitSections(text) {
     }
   };
   for (const line of lines) {
-    const trimmed = line.trim();
-    const matched = SECTION_HEADERS.find((h) => trimmed === h);
+    const normalised = normaliseHeaderLine(line);
+    const matched = SECTION_HEADERS.find((h) => normalised === h);
     if (matched) {
       flush();
       currentSection = matched;
@@ -5598,7 +5600,10 @@ function parseChecklist(text) {
   return text.split("\n").map((l) => l.replace(/^\s*\[[ x]]\s*/, "").trim()).filter((l) => l.length > 0);
 }
 function parseBuildHandoff(markdown) {
-  if (!markdown.includes("BUILD HANDOFF")) return null;
+  if (typeof markdown !== "string" || !markdown.trim()) return null;
+  if (!markdown.includes("BUILD HANDOFF") && splitSections(markdown).size === 0) {
+    return null;
+  }
   const taskIdMatch = markdown.match(/BUILD HANDOFF\s*—\s*(task-\d+)/);
   const taskTitleMatch = markdown.match(/^Task:\s*(.+)$/m);
   const cycleMatch = markdown.match(/^Cycle:\s*(\d+)$/m);
@@ -5633,6 +5638,28 @@ function parseBuildHandoff(markdown) {
     effort
   };
 }
+function coerceBuildHandoff(fields, taskId) {
+  const scope = ensureArray(fields.scope);
+  const scopeBoundary = ensureArray(fields.scopeBoundary);
+  if (scope.length === 0 && scopeBoundary.length === 0) return null;
+  const effortRaw = typeof fields.effort === "string" ? fields.effort.trim().toUpperCase() : "";
+  const effort = VALID_EFFORT_SIZES.has(effortRaw) ? effortRaw : "M";
+  const str = (v) => typeof v === "string" ? v.trim() : "";
+  return {
+    uuid: str(fields.uuid) || randomUUID2(),
+    taskId: str(fields.taskId) || taskId || "",
+    taskTitle: str(fields.taskTitle),
+    cycle: typeof fields.cycle === "number" ? fields.cycle : 0,
+    whyNow: str(fields.whyNow),
+    scope,
+    scopeBoundary,
+    acceptanceCriteria: ensureArray(fields.acceptanceCriteria),
+    securityConsiderations: str(fields.securityConsiderations),
+    verificationFiles: ensureArray(fields.verificationFiles),
+    filesLikelyTouched: ensureArray(fields.filesLikelyTouched),
+    effort
+  };
+}
 function ensureArray(value) {
   if (Array.isArray(value)) return value;
   if (typeof value === "string") {
@@ -8166,7 +8193,7 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
 }
 
 // src/server.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync12 } from "fs";
 import { access as access4, readdir as readdir4, readFile as readFile9 } from "fs/promises";
 import { join as join19, dirname as dirname5 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -9007,6 +9034,7 @@ Everything in Part 1 (natural language) is **display-only**. Part 2 (structured
 - Updated or created Active Decisions in Part 1? \u2192 Put them in \`activeDecisions\` array (with id and full body including ### heading)
 - Found board corrections (wrong priority, missing fields, stale status) in Part 1? \u2192 Put them in \`boardCorrections\` array
 - Generated BUILD HANDOFFs in Part 1? \u2192 Put them in \`cycleHandoffs\` array
+- **\`complexity\` uses the LONG forms only** \u2014 "XS", "Small", "Medium", "Large", "XL". Do NOT reuse the handoff EFFORT short-forms (S/M/L) for task complexity.
 
 **Example with populated fields (DO NOT copy literally \u2014 adapt to your actual analysis):**
 \`\`\`json
@@ -9047,13 +9075,20 @@ This is Cycle 0 \u2014 the first planning cycle for a brand-new project.
    - Do NOT assume web-app patterns (routes, pages, components) unless the brief explicitly describes a web application
    - All tasks: status Backlog, priority P1-P2, reviewed true, phase "Phase 1"
 
+   **REASONING LINE (task-2868 \u2014 the first cycle must SHOW PAPI's intelligence, not read as a generic list).** For EVERY task, the \`notes\` field MUST OPEN with a single line in the exact form:
+   \`Why: <one plain-language sentence, \u2264160 chars, on why THIS task earns its place in the first cycle>\`
+   Then a blank line, then any other notes. Rules:
+   - Task 1's \`Why:\` must also justify its POSITION \u2014 say why it is the opening slice (the thinnest thing that puts the core loop in front of the user). This one line is the cycle's sequencing rationale; the dashboard surfaces it above the first task.
+   - Plain language for a semi-technical builder \u2014 no jargon, no raw IDs, not a restatement of the title.
+   - This is a hard requirement: the dashboard's first-cycle experience reads and renders this \`Why:\` line per task.
+
 4. **First Active Decision** \u2014 If the description implies a clear architectural choice, create AD-1 with Confidence: MEDIUM. If no clear choice, skip this.
 
 5. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for EVERY task created in step 3 (all 3-5 tasks). Include each in the \`cycleHandoffs\` array. **tempId join (REQUIRED \u2014 mismatches silently scramble handoffs):** give EVERY \`newTasks\` entry a unique \`tempId\` (\`"new-1"\`, \`"new-2"\`, \u2026), and set each \`cycleHandoffs\` \`taskId\` to the EXACT \`tempId\` of the newTask it belongs to. Do NOT rely on array order, and do NOT reuse a tempId. The builder needs handoffs to run \`build_execute\` \u2014 without them, tasks must be completed via \`ad_hoc\`, which breaks the normal flow.
 
 ### Structured output for Bootstrap:
 In the JSON block, you MUST include:
-- "newTasks": array of task objects with ALL fields: title, status, priority, complexity, module, epic, phase, owner, notes. **This is how tasks get created on the board. If this array is empty, NO tasks will exist.**
+- "newTasks": array of task objects with ALL fields: title, status, priority, complexity, module, epic, phase, owner, notes. **This is how tasks get created on the board. If this array is empty, NO tasks will exist.** Every \`notes\` value MUST open with the \`Why: <sentence>\` reasoning line described in step 3 (the dashboard's first-cycle experience renders it).
 - "productBrief": the full Product Brief markdown content. **If null, the brief stays as the template.**
 - "activeDecisions": array of {id, body} objects. **If you created AD-1 in Part 1 but this array is empty, the AD will NOT be saved.**
 - "recommendedTaskId": null (the handler will use the first new task)
@@ -9597,10 +9632,17 @@ function coerceToString(value) {
   return JSON.stringify(value, null, 2);
 }
 function coerceStructuredOutput(parsed) {
-  const cycleHandoffs = Array.isArray(parsed.cycleHandoffs) ? parsed.cycleHandoffs.map((h) => ({
-    taskId: coerceToString(h.taskId),
-    buildHandoff: coerceToString(h.buildHandoff)
-  })) : [];
+  const cycleHandoffs = Array.isArray(parsed.cycleHandoffs) ? parsed.cycleHandoffs.map((h) => {
+    const { taskId: _t, buildHandoff: _b, ...rest } = h;
+    if (typeof h.buildHandoff === "object" && h.buildHandoff !== null && !Array.isArray(h.buildHandoff)) {
+      Object.assign(rest, h.buildHandoff);
+    }
+    return {
+      taskId: coerceToString(h.taskId),
+      buildHandoff: typeof h.buildHandoff === "string" ? h.buildHandoff : "",
+      ...Object.keys(rest).length > 0 ? { structuredFields: rest } : {}
+    };
+  }) : [];
   const newTasks = Array.isArray(parsed.newTasks) ? parsed.newTasks.map((t) => ({
     // task-2242: stable join key (optional — undefined falls back to index).
     tempId: t.tempId !== void 0 && t.tempId !== null ? coerceToString(t.tempId) : void 0,
@@ -10710,9 +10752,12 @@ async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber, force = false)
         skipped++;
         continue;
       }
-      const parsed = parseBuildHandoff(handoff.buildHandoff);
+      const parsed = parseBuildHandoff(handoff.buildHandoff) ?? (handoff.structuredFields ? coerceBuildHandoff(handoff.structuredFields, handoff.taskId) : null);
       if (!parsed) {
-        warnings.push(`Failed to parse handoff for ${handoff.taskId}`);
+        const received = (handoff.buildHandoff ?? "").slice(0, 80);
+        warnings.push(
+          `Failed to parse handoff for ${handoff.taskId}. Received: "${received}${(handoff.buildHandoff ?? "").length > 80 ? "\u2026" : ""}". Send EITHER the BUILD HANDOFF markdown template in \`buildHandoff\` (section headers on their own lines: SCOPE (DO THIS) / SCOPE BOUNDARY (DO NOT DO THIS) / ACCEPTANCE CRITERIA / EFFORT, bullets as "- item") OR structured fields alongside taskId: {scope: string[], scopeBoundary: string[], acceptanceCriteria: string[], effort: "XS|S|M|L|XL"}.`
+        );
         continue;
       }
       const invalidFields = validateHandoffScope(parsed);
@@ -10720,7 +10765,6 @@ async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber, force = false)
         warnings.push(
           `Rejected handoff for ${handoff.taskId}: missing or empty ${invalidFields.join(", ")}. Handoffs without explicit scope produce ambiguous builds.`
         );
-        skipped++;
         continue;
       }
       if (!parsed.createdAt) {
@@ -11195,6 +11239,20 @@ async function resolveOwnerGate(adapter2, config2) {
 }
 
 // src/services/plan.ts
+var COMPLEXITY_ALIASES = {
+  "XS": "XS",
+  "S": "Small",
+  "SMALL": "Small",
+  "M": "Medium",
+  "MEDIUM": "Medium",
+  "L": "Large",
+  "LARGE": "Large",
+  "XL": "XL"
+};
+function normalizeComplexity(value) {
+  const key = (value ?? "").trim().toUpperCase();
+  return COMPLEXITY_ALIASES[key] ?? "Small";
+}
 var PLAN_BUILD_REPORT_BUDGET = { maxReports: 12, fieldBudget: 280 };
 function leadChainWithRecommended(chain, recommendedTaskId) {
   const rec = recommendedTaskId?.trim();
@@ -12133,10 +12191,13 @@ ${cleanContent}`;
   } catch {
   }
   const handoffs = (data.cycleHandoffs ?? []).map((h) => {
-    const parsed = parseBuildHandoff(h.buildHandoff);
+    const parsed = parseBuildHandoff(h.buildHandoff) ?? (h.structuredFields ? coerceBuildHandoff(h.structuredFields, h.taskId) : null);
     if (parsed && !parsed.createdAt) {
       parsed.createdAt = (/* @__PURE__ */ new Date()).toISOString();
     }
+    if (!parsed) {
+      console.error(`[plan] dropping unparseable handoff for ${h.taskId} (not the BUILD HANDOFF template and no structured scope fields)`);
+    }
     return { taskId: h.taskId, handoff: parsed };
   }).filter((h) => h.handoff != null);
   const cycleTaskIds = data.cycleTaskIds?.length ? data.cycleTaskIds : (data.cycleHandoffs ?? []).map((h) => h.taskId);
@@ -12223,7 +12284,7 @@ ${cleanContent}`;
       title: t.title,
       status: t.status || "Backlog",
       priority: t.priority || "P1 High",
-      complexity: t.complexity || "Small",
+      complexity: normalizeComplexity(t.complexity),
       module: t.module || "Core",
       epic: t.epic || "Platform",
       phase: t.phase || "Phase 1",
@@ -12371,7 +12432,7 @@ ${cleanContent}`;
         title: task.title,
         status: task.status || "Backlog",
         priority: task.priority || "P1 High",
-        complexity: task.complexity || "Small",
+        complexity: normalizeComplexity(task.complexity),
         module: task.module || "Core",
         epic: task.epic || "Platform",
         phase: task.phase || "Phase 1",
@@ -13383,6 +13444,13 @@ async function resolveLlmResponse(inlineResponse, filePath) {
   }
   const resolvedPath = filePath.trim();
   if (!isAbsolute(resolvedPath)) {
+    const looksWindows = /^[A-Za-z]:[\\/]/.test(resolvedPath) || resolvedPath.startsWith("\\\\");
+    if (looksWindows && process.platform !== "win32") {
+      return {
+        ok: false,
+        error: `llm_response_file points at a path on YOUR machine (${resolvedPath}), but this PAPI server runs remotely and cannot read your filesystem. llm_response_file only works with a locally installed (stdio) server. On the hosted connection, pass the content inline via llm_response.`
+      };
+    }
     return {
       ok: false,
       error: `llm_response_file must be an absolute path, got: ${resolvedPath}`
@@ -13629,7 +13697,7 @@ var planTool = {
       },
       llm_response_file: {
         type: "string",
-        description: 'Absolute path to a file containing the plan output (mode "apply" only). Use this when the response is too large to pass as a string parameter (some hosts cap inputs around 50KB). The file must be absolute, exist, and be \u2264500KB. Mutually exclusive with llm_response.'
+        description: 'Absolute path to a file containing the plan output (mode "apply" only). LOCAL stdio servers only \u2014 on the hosted connection the server cannot read files on your machine; pass llm_response inline instead. Use this when the response is too large to pass as a string parameter (some hosts cap inputs around 50KB). The file must be absolute, exist, and be \u2264500KB. Mutually exclusive with llm_response.'
       },
       cycle_number: {
         type: "number",
@@ -13704,7 +13772,7 @@ function formatPlanResult(result) {
     return textResponse(
       `${pullLine}**${modeLabel} Mode \u2014 ${cycleLabel}**
 
-\u26A0\uFE0F **Persistence failed:** Structured output could not be parsed. Cycle log, board corrections, handoffs, and Active Decisions were NOT saved. Try running \`plan\` again.`
+\u26A0\uFE0F **Persistence failed:** Structured output could not be parsed. Cycle log, board corrections, handoffs, and Active Decisions were NOT saved. Your llm_response must contain the literal marker \`<!-- PAPI_STRUCTURED_OUTPUT -->\` followed by the JSON inside a \`\`\`json code fence \u2014 resend with that exact envelope (do not strip the marker or the fence).`
     );
   }
   const lines = [];
@@ -16059,7 +16127,7 @@ var strategyReviewTool = {
       },
       llm_response_file: {
         type: "string",
-        description: 'Absolute path to a file containing the review output (mode "apply" only). Use this when the response is too large to pass as a string parameter (some hosts cap inputs around 50KB). The file must be absolute, exist, and be \u2264500KB. Mutually exclusive with llm_response.'
+        description: 'Absolute path to a file containing the review output (mode "apply" only). LOCAL stdio servers only \u2014 on the hosted connection the server cannot read files on your machine; pass llm_response inline instead. Use this when the response is too large to pass as a string parameter (some hosts cap inputs around 50KB). The file must be absolute, exist, and be \u2264500KB. Mutually exclusive with llm_response.'
       },
       cycle_number: {
         type: "number",
@@ -18034,7 +18102,9 @@ async function applySetupOutputs(adapter2, config2, input, collector, briefText,
             }
             if (adapter2.upsertActiveDecision) {
               const title = ad.title || ad.body.split("\n")[0].replace(/^#+\s*/, "").slice(0, 120);
-              await adapter2.upsertActiveDecision(ad.id, ad.body, title, ad.confidence || "MEDIUM", 0);
+              const confidenceMatch = ad.body.match(/\[Confidence:\s*(HIGH|MEDIUM|LOW)\]/i);
+              const confidence = confidenceMatch ? confidenceMatch[1].toUpperCase() : ad.confidence || "MEDIUM";
+              await adapter2.upsertActiveDecision(ad.id, ad.body, title, confidence, 0);
             } else {
               await adapter2.updateActiveDecision(ad.id, ad.body, 0);
             }
@@ -18814,10 +18884,14 @@ ${[created, skipped].filter(Boolean).join(", ")}.${idea}`;
 \u26A0\uFE0F **Setup warnings (non-blocking):**
 ${result.warnings.map((w) => `- ${w}`).join("\n")}` : "";
   const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
-  return textResponse(
-    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${northStarNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}
+  const isHosted = !!result.filesToWrite && !result.filesToWrite.isEmpty();
+  const filesNote = isHosted ? `
+
+**Important:** This is a remote PAPI connection, so the server could not write to your project directory. Setup prepared your files (${harnessFiles}, .claude/settings.json, docs/) and returned them in the scaffolding section below \u2014 **write each one to disk, then commit** before running \`build_execute\` (it requires a clean working directory).` : `
 
-**Important:** Setup created/modified files (${harnessFiles}, .claude/settings.json, docs/). Commit these changes before running \`build_execute\` \u2014 it requires a clean working directory.
+**Important:** Setup created/modified files (${harnessFiles}, .claude/settings.json, docs/). Commit these changes before running \`build_execute\` \u2014 it requires a clean working directory.`;
+  return textResponse(
+    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${northStarNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}${filesNote}
 
 Tip: See \`docs/templates/example-project-brief.md\` for an example of a well-written brief.
 
@@ -23234,7 +23308,7 @@ var bugTool = {
       severity: {
         type: "string",
         enum: ["critical", "major", "minor"],
-        description: 'Bug severity (default: "major"). Critical = P1, Major/Minor = P2.'
+        description: 'Bug severity (default: "major"). Critical = P0, Major = P1, Minor = P2.'
       },
       notes: {
         type: "string",
@@ -27135,6 +27209,7 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
       // Skill proposals — one-time codebase scan on first orient per project.
       // PERF: hasToolMilestone (LIMIT 1 EXISTS) replaces readToolMetrics (5000-row pull).
       tracked("skill-scan", async () => {
+        if (!hasLocalWorkspace()) return "";
         const alreadyScanned = adapter2.hasToolMilestone ? await adapter2.hasToolMilestone("milestone:skill_scan_completed") : (await adapter2.readToolMetrics()).some((m) => m.tool === "milestone:skill_scan_completed");
         if (alreadyScanned) return "";
         const proposals = scanForSkillSignals(config2.projectRoot);
@@ -28029,11 +28104,11 @@ var handoffGenerateTool = {
       },
       llm_response: {
         type: "string",
-        description: 'Your raw output from executing the handoff prompt (mode "apply" only). Must include both Part 1 (markdown) and Part 2 (structured JSON after <!-- PAPI_STRUCTURED_OUTPUT -->). Mutually exclusive with llm_response_file.'
+        description: 'Your raw output from executing the handoff prompt (mode "apply" only). Must include both Part 1 (markdown) and Part 2 (structured JSON after <!-- PAPI_STRUCTURED_OUTPUT -->, inside a ```json fence). Each cycleHandoffs entry needs EITHER a buildHandoff string in the BUILD HANDOFF markdown template (section headers on their own lines: SCOPE (DO THIS) / SCOPE BOUNDARY (DO NOT DO THIS) / ACCEPTANCE CRITERIA / EFFORT) OR structured fields alongside taskId: {scope: string[], scopeBoundary: string[], acceptanceCriteria: string[], effort: "XS|S|M|L|XL"}. Mutually exclusive with llm_response_file.'
       },
       llm_response_file: {
         type: "string",
-        description: 'Absolute path to a file containing the handoff output (mode "apply" only). Use instead of llm_response when the output exceeds tool parameter size limits. Mutually exclusive with llm_response.'
+        description: 'Absolute path to a file containing the handoff output (mode "apply" only). LOCAL stdio servers only \u2014 on the hosted connection the server cannot read files on your machine; pass llm_response inline instead. Use instead of llm_response when the output exceeds tool parameter size limits. Mutually exclusive with llm_response.'
       },
       cycle_number: {
         type: "number",
@@ -28130,10 +28205,12 @@ ${result.userMessage}
   }
 }
 
+// src/tools/scope-brief.ts
+import { readFileSync as readFileSync11, statSync as statSync7 } from "fs";
+
 // src/services/scope-brief.ts
 import { writeFileSync as writeFileSync5, mkdirSync as mkdirSync3 } from "fs";
 import { join as join17, dirname as dirname4 } from "path";
-import Anthropic from "@anthropic-ai/sdk";
 var SCOPE_BRIEF_SYSTEM = `You are a technical scoping tool. You receive a brief-class task (too large to build directly) and decompose it into a structured scope document.
 
 A scope document must:
@@ -28164,7 +28241,18 @@ Return the scope document in Markdown. Use this exact structure:
 <Any unknowns that affect scope, or "None">
 
 Return ONLY the markdown document. No preamble, no commentary.`;
-async function runScopeBrief(adapter2, input) {
+async function buildScopeBriefPrompt(adapter2, taskId) {
+  const tasks = await adapter2.queryBoard({});
+  const task = tasks.find((t) => t.id === taskId || t.displayId === taskId);
+  if (!task) {
+    throw new Error(`Task not found: ${taskId}`);
+  }
+  if (task.scopeClass !== "brief") {
+    throw new Error(`Task ${taskId} is not brief-class (scopeClass=${task.scopeClass ?? "task"}). Only brief-class tasks can be scoped.`);
+  }
+  return { task, systemPrompt: SCOPE_BRIEF_SYSTEM, userContext: buildTaskContext(task) };
+}
+async function applyScopeBrief(adapter2, input) {
   const tasks = await adapter2.queryBoard({});
   const task = tasks.find((t) => t.id === input.taskId || t.displayId === input.taskId);
   if (!task) {
@@ -28173,17 +28261,9 @@ async function runScopeBrief(adapter2, input) {
   if (task.scopeClass !== "brief") {
     throw new Error(`Task ${input.taskId} is not brief-class (scopeClass=${task.scopeClass ?? "task"}). Only brief-class tasks can be scoped.`);
   }
-  const taskContext = buildTaskContext(task);
-  const client = new Anthropic({ apiKey: input.apiKey });
-  const response = await client.messages.create({
-    model: "claude-sonnet-4-6",
-    max_tokens: 2048,
-    system: SCOPE_BRIEF_SYSTEM,
-    messages: [{ role: "user", content: taskContext }]
-  });
-  const docContent = response.content[0].type === "text" ? response.content[0].text.trim() : "";
+  const docContent = input.llmMarkdown.trim();
   if (!docContent) {
-    throw new Error("LLM returned empty scope document");
+    throw new Error("Scope document is empty \u2014 pass the markdown you produced from the scope prompt as llm_response.");
   }
   const slug = input.taskId.replace(/[^a-z0-9-]/g, "-").toLowerCase();
   const relPath = `docs/scopes/${slug}.md`;
@@ -28268,7 +28348,7 @@ function buildSummary(task, taskCount) {
 // src/tools/scope-brief.ts
 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.",
+  description: 'Decompose a brief-class task (Large/XL, too large to build directly) into a structured scope document. Two phases, like plan/strategy \u2014 PAPI never calls a model itself (AD-58): first call (mode "prepare") returns a scoping prompt for YOU to run in your own AI workspace; then call again (mode "apply") with your markdown output in llm_response to write docs/scopes/<task-id>.md, register it, and mark the source task decomposed. Use before planning a cycle that includes brief-class tasks.',
   annotations: { title: "Scope Brief", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -28276,42 +28356,102 @@ var scopeBriefTool = {
       task_id: {
         type: "string",
         description: 'ID of the brief-class task to decompose (e.g. "task-042").'
+      },
+      mode: {
+        type: "string",
+        enum: ["prepare", "apply"],
+        description: '"prepare" (default) returns the scoping prompt for you to run. "apply" persists the scope document you produced.'
+      },
+      llm_response: {
+        type: "string",
+        description: 'Your markdown scope document from running the prepare prompt (mode "apply" only).'
+      },
+      llm_response_file: {
+        type: "string",
+        description: 'Absolute path to a file holding your markdown scope document (mode "apply" only). LOCAL stdio servers only \u2014 the hosted server cannot read your machine. Mutually exclusive with llm_response; must be absolute, exist, and be \u2264500KB.'
       }
     },
     required: ["task_id"]
   }
 };
+var MAX_RESPONSE_FILE_BYTES = 500 * 1024;
 async function handleScopeBrief(adapter2, config2, args) {
   const taskId = args.task_id;
   if (!taskId) {
     return errorResponse("task_id is required.");
   }
-  const apiKey = process.env["ANTHROPIC_API_KEY"];
-  if (!apiKey) {
-    return errorResponse("ANTHROPIC_API_KEY is not set \u2014 scope_brief requires LLM access.");
-  }
+  const mode = args.mode ?? "prepare";
   const health = await adapter2.getCycleHealth().catch(() => ({ totalCycles: 0 }));
-  try {
-    const result = await runScopeBrief(adapter2, {
-      taskId,
-      apiKey,
-      projectRoot: config2.projectRoot,
-      cycleNumber: health.totalCycles,
-      adapterType: config2.adapterType
-    });
-    const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
-    return textResponse(
-      `**Scope document created:** \`${result.docPath}\`
+  if (mode === "prepare") {
+    try {
+      const { task, systemPrompt, userContext } = await buildScopeBriefPrompt(adapter2, taskId);
+      return textResponse(
+        `**Scope Brief \u2014 prepare** for ${task.id}: ${task.title}
+
+Run the scoping pass below in YOUR AI workspace (PAPI does not call a model \u2014 AD-58), then call \`scope_brief\` again with \`mode: "apply"\`, the same \`task_id\`, and your markdown document in \`llm_response\`.
+
+---
+
+## Scoping instructions
+
+${systemPrompt}
+
+---
+
+## Task to decompose
+
+${userContext}`
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return errorResponse(`scope_brief prepare failed: ${message}`);
+    }
+  }
+  if (mode === "apply") {
+    const llmMarkdown = readLlmResponse(args);
+    if (!llmMarkdown) {
+      return errorResponse('mode "apply" requires your scope document \u2014 pass it in llm_response (or llm_response_file on a local server).');
+    }
+    try {
+      const result = await applyScopeBrief(adapter2, {
+        taskId,
+        llmMarkdown,
+        projectRoot: config2.projectRoot,
+        cycleNumber: health.totalCycles,
+        adapterType: config2.adapterType
+      });
+      const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
+      return textResponse(
+        `**Scope document created:** \`${result.docPath}\`
 - **Sub-tasks defined:** ${result.taskCount}
 - **Doc registry ID:** ${result.docId}
 - **Source task:** ${taskId} marked as decomposed
 
 **Next step:** Review \`${result.docPath}\` and submit each sub-task via \`idea\` with \`Reference: ${result.docPath}\` in notes. The planner will pick them up in the next cycle.` + filesToWriteSection
-    );
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return errorResponse(`scope_brief failed: ${message}`);
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return errorResponse(`scope_brief apply failed: ${message}`);
+    }
   }
+  return errorResponse(`Unknown mode "${mode}" \u2014 use "prepare" or "apply".`);
+}
+function readLlmResponse(args) {
+  const inline = args.llm_response;
+  if (inline && inline.trim()) return inline;
+  const filePath = args.llm_response_file;
+  if (filePath && filePath.trim()) {
+    try {
+      if (statSync7(filePath).size > MAX_RESPONSE_FILE_BYTES) {
+        throw new Error(`llm_response_file exceeds ${MAX_RESPONSE_FILE_BYTES} bytes`);
+      }
+      const body = readFileSync11(filePath, "utf-8");
+      return body.trim() ? body : null;
+    } catch (err) {
+      throw new Error(`could not read llm_response_file: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return null;
 }
 
 // src/tools/ad-view.ts
@@ -29537,7 +29677,7 @@ function createServer(adapter2, config2) {
   const __pkgDir = dirname5(__pkgFilename);
   let serverVersion = "unknown";
   try {
-    const pkg = JSON.parse(readFileSync11(join19(__pkgDir, "..", "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync12(join19(__pkgDir, "..", "package.json"), "utf-8"));
     serverVersion = pkg.version ?? "unknown";
   } catch {
   }
@@ -30283,7 +30423,7 @@ async function dispatchRequest(args) {
 var __dirname = dirname6(fileURLToPath4(import.meta.url));
 var pkgVersion = "unknown";
 try {
-  const pkg = JSON.parse(readFileSync16(join24(__dirname, "..", "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync17(join24(__dirname, "..", "package.json"), "utf-8"));
   pkgVersion = pkg.version;
 } catch {
 }

package/dist/prompts.js

@@ -130,6 +130,7 @@ Everything in Part 1 (natural language) is **display-only**. Part 2 (structured
 - Updated or created Active Decisions in Part 1? \u2192 Put them in \`activeDecisions\` array (with id and full body including ### heading)
 - Found board corrections (wrong priority, missing fields, stale status) in Part 1? \u2192 Put them in \`boardCorrections\` array
 - Generated BUILD HANDOFFs in Part 1? \u2192 Put them in \`cycleHandoffs\` array
+- **\`complexity\` uses the LONG forms only** \u2014 "XS", "Small", "Medium", "Large", "XL". Do NOT reuse the handoff EFFORT short-forms (S/M/L) for task complexity.
 
 **Example with populated fields (DO NOT copy literally \u2014 adapt to your actual analysis):**
 \`\`\`json
@@ -170,13 +171,20 @@ This is Cycle 0 \u2014 the first planning cycle for a brand-new project.
    - Do NOT assume web-app patterns (routes, pages, components) unless the brief explicitly describes a web application
    - All tasks: status Backlog, priority P1-P2, reviewed true, phase "Phase 1"
 
+   **REASONING LINE (task-2868 \u2014 the first cycle must SHOW PAPI's intelligence, not read as a generic list).** For EVERY task, the \`notes\` field MUST OPEN with a single line in the exact form:
+   \`Why: <one plain-language sentence, \u2264160 chars, on why THIS task earns its place in the first cycle>\`
+   Then a blank line, then any other notes. Rules:
+   - Task 1's \`Why:\` must also justify its POSITION \u2014 say why it is the opening slice (the thinnest thing that puts the core loop in front of the user). This one line is the cycle's sequencing rationale; the dashboard surfaces it above the first task.
+   - Plain language for a semi-technical builder \u2014 no jargon, no raw IDs, not a restatement of the title.
+   - This is a hard requirement: the dashboard's first-cycle experience reads and renders this \`Why:\` line per task.
+
 4. **First Active Decision** \u2014 If the description implies a clear architectural choice, create AD-1 with Confidence: MEDIUM. If no clear choice, skip this.
 
 5. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for EVERY task created in step 3 (all 3-5 tasks). Include each in the \`cycleHandoffs\` array. **tempId join (REQUIRED \u2014 mismatches silently scramble handoffs):** give EVERY \`newTasks\` entry a unique \`tempId\` (\`"new-1"\`, \`"new-2"\`, \u2026), and set each \`cycleHandoffs\` \`taskId\` to the EXACT \`tempId\` of the newTask it belongs to. Do NOT rely on array order, and do NOT reuse a tempId. The builder needs handoffs to run \`build_execute\` \u2014 without them, tasks must be completed via \`ad_hoc\`, which breaks the normal flow.
 
 ### Structured output for Bootstrap:
 In the JSON block, you MUST include:
-- "newTasks": array of task objects with ALL fields: title, status, priority, complexity, module, epic, phase, owner, notes. **This is how tasks get created on the board. If this array is empty, NO tasks will exist.**
+- "newTasks": array of task objects with ALL fields: title, status, priority, complexity, module, epic, phase, owner, notes. **This is how tasks get created on the board. If this array is empty, NO tasks will exist.** Every \`notes\` value MUST open with the \`Why: <sentence>\` reasoning line described in step 3 (the dashboard's first-cycle experience renders it).
 - "productBrief": the full Product Brief markdown content. **If null, the brief stays as the template.**
 - "activeDecisions": array of {id, body} objects. **If you created AD-1 in Part 1 but this array is empty, the AD will NOT be saved.**
 - "recommendedTaskId": null (the handler will use the first new task)
@@ -720,10 +728,17 @@ function coerceToString(value) {
   return JSON.stringify(value, null, 2);
 }
 function coerceStructuredOutput(parsed) {
-  const cycleHandoffs = Array.isArray(parsed.cycleHandoffs) ? parsed.cycleHandoffs.map((h) => ({
-    taskId: coerceToString(h.taskId),
-    buildHandoff: coerceToString(h.buildHandoff)
-  })) : [];
+  const cycleHandoffs = Array.isArray(parsed.cycleHandoffs) ? parsed.cycleHandoffs.map((h) => {
+    const { taskId: _t, buildHandoff: _b, ...rest } = h;
+    if (typeof h.buildHandoff === "object" && h.buildHandoff !== null && !Array.isArray(h.buildHandoff)) {
+      Object.assign(rest, h.buildHandoff);
+    }
+    return {
+      taskId: coerceToString(h.taskId),
+      buildHandoff: typeof h.buildHandoff === "string" ? h.buildHandoff : "",
+      ...Object.keys(rest).length > 0 ? { structuredFields: rest } : {}
+    };
+  }) : [];
   const newTasks = Array.isArray(parsed.newTasks) ? parsed.newTasks.map((t) => ({
     // task-2242: stable join key (optional — undefined falls back to index).
     tempId: t.tempId !== void 0 && t.tempId !== null ? coerceToString(t.tempId) : void 0,

package/package.json

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