@papi-ai/server 0.7.35 → 0.7.37

package/dist/backfill-cycle-metrics.js

@@ -50,6 +50,7 @@ __export(git_exports, {
   hasRemote: () => hasRemote,
   hasUncommittedChanges: () => hasUncommittedChanges,
   hasUnpushedCommits: () => hasUnpushedCommits,
+  isBranchContentAlreadyInBase: () => isBranchContentAlreadyInBase,
   isBranchMergedInto: () => isBranchMergedInto,
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
@@ -807,6 +808,32 @@ function isBranchMergedInto(cwd, branch, baseBranch) {
     return false;
   }
 }
+function isBranchContentAlreadyInBase(cwd, branch, baseBranch) {
+  const resolveCommit = (ref) => {
+    try {
+      return execFileSync("git", ["rev-parse", "--verify", `${ref}^{commit}`], { cwd, encoding: "utf-8" }).trim();
+    } catch {
+      return null;
+    }
+  };
+  const branchRef = resolveCommit(branch) ? branch : resolveCommit(`origin/${branch}`) ? `origin/${branch}` : null;
+  if (!branchRef) return false;
+  try {
+    const out = execFileSync("git", ["merge-tree", "--write-tree", baseBranch, branchRef], {
+      cwd,
+      encoding: "utf-8"
+    }).trim();
+    const mergedTree = out.split("\n")[0]?.trim();
+    if (!mergedTree) return false;
+    const baseTree = execFileSync("git", ["rev-parse", `${baseBranch}^{tree}`], {
+      cwd,
+      encoding: "utf-8"
+    }).trim();
+    return mergedTree === baseTree;
+  } catch {
+    return false;
+  }
+}
 function pickModuleCycleBranch(candidates, cycleNumber, module) {
   if (candidates.length === 0) return void 0;
   const expected = cycleBranchName(cycleNumber, module);

package/dist/index.js

@@ -51,6 +51,7 @@ __export(git_exports, {
   hasRemote: () => hasRemote,
   hasUncommittedChanges: () => hasUncommittedChanges,
   hasUnpushedCommits: () => hasUnpushedCommits,
+  isBranchContentAlreadyInBase: () => isBranchContentAlreadyInBase,
   isBranchMergedInto: () => isBranchMergedInto,
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
@@ -808,6 +809,32 @@ function isBranchMergedInto(cwd, branch, baseBranch) {
     return false;
   }
 }
+function isBranchContentAlreadyInBase(cwd, branch, baseBranch) {
+  const resolveCommit = (ref) => {
+    try {
+      return execFileSync("git", ["rev-parse", "--verify", `${ref}^{commit}`], { cwd, encoding: "utf-8" }).trim();
+    } catch {
+      return null;
+    }
+  };
+  const branchRef = resolveCommit(branch) ? branch : resolveCommit(`origin/${branch}`) ? `origin/${branch}` : null;
+  if (!branchRef) return false;
+  try {
+    const out = execFileSync("git", ["merge-tree", "--write-tree", baseBranch, branchRef], {
+      cwd,
+      encoding: "utf-8"
+    }).trim();
+    const mergedTree = out.split("\n")[0]?.trim();
+    if (!mergedTree) return false;
+    const baseTree = execFileSync("git", ["rev-parse", `${baseBranch}^{tree}`], {
+      cwd,
+      encoding: "utf-8"
+    }).trim();
+    return mergedTree === baseTree;
+  } catch {
+    return false;
+  }
+}
 function pickModuleCycleBranch(candidates, cycleNumber, module) {
   if (candidates.length === 0) return void 0;
   const expected = cycleBranchName(cycleNumber, module);
@@ -4639,13 +4666,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 +4742,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 +4761,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 {
@@ -7064,6 +7114,9 @@ ${footer}`);
     await this.write("PLANNING_LOG.md", updated);
   }
 };
+function newTaskJoinKey(task, index) {
+  return task.tempId ?? `new-${index + 1}`;
+}
 var NONE_PATTERN2 = /^none\b/i;
 function normalizeText2(text) {
   return text.trim().toLowerCase().replace(/[.,;:!]+$/, "").replace(/\s+/g, " ");
@@ -7958,6 +8011,39 @@ function formatDerivedMetrics(snapshots, backlogTasks) {
   }
   return lines.join("\n");
 }
+function formatLearningPatterns(patterns) {
+  if (!patterns || patterns.length === 0) return void 0;
+  const ranked = [...patterns].sort(
+    (a, b2) => b2.cycles.length - a.cycles.length || b2.frequency - a.frequency
+  );
+  const strong = ranked.filter((p) => p.cycles.length >= 3);
+  const shown = (strong.length > 0 ? strong : ranked).slice(0, 12);
+  if (shown.length === 0) return void 0;
+  const lines = shown.map(
+    (p) => `- \`${p.tag}\` \u2014 recurred in ${p.cycles.length} cycles (${p.frequency}\xD7), most recent C${Math.max(...p.cycles)}`
+  );
+  return lines.join("\n");
+}
+function formatDecisionScorePatterns(patterns) {
+  if (!patterns || patterns.length === 0) return void 0;
+  const HIGH_RISK = 15;
+  const moved = (p) => p.previousScore != null && p.previousScore !== p.totalScore;
+  const relevant = patterns.filter((p) => p.totalScore > HIGH_RISK || moved(p));
+  if (relevant.length === 0) return void 0;
+  const ranked = [...relevant].sort(
+    (a, b2) => b2.totalScore - a.totalScore || Math.abs((b2.previousScore ?? b2.totalScore) - b2.totalScore) - Math.abs((a.previousScore ?? a.totalScore) - a.totalScore)
+  );
+  const lines = ranked.slice(0, 10).map((p) => {
+    let line = `- ${p.decisionId}: ${p.title} [${p.confidence}] \u2014 score ${p.totalScore}/25`;
+    if (p.previousScore != null && p.previousScore !== p.totalScore) {
+      const arrow = p.totalScore > p.previousScore ? "\u2191 riskier" : "\u2193 safer";
+      line += ` (${arrow} from ${p.previousScore}/25${p.previousCycle != null ? ` at C${p.previousCycle}` : ""})`;
+    }
+    if (p.totalScore > HIGH_RISK) line += " \u26A0 high-risk";
+    return line;
+  });
+  return lines.join("\n");
+}
 function formatBuildPatterns(patterns) {
   const sections = [];
   if (patterns.recurringSurprises.length > 0) {
@@ -8230,7 +8316,7 @@ After your natural language output, include this EXACT format on its own line:
   "boardHealth": "string \u2014 e.g. 5 tasks (3 backlog, 2 done)",
   "strategicDirection": "string \u2014 one sentence about current phase/direction",
   "recommendedTaskId": "string or null \u2014 task ID to set In Progress",
-  "cycleHandoffs": [{"taskId": "string \u2014 existing task ID or new-N for new tasks", "buildHandoff": "string \u2014 full BUILD HANDOFF text"}],
+  "cycleHandoffs": [{"taskId": "string \u2014 an existing task ID, or the EXACT tempId of a newTasks entry (e.g. "new-1") it provides the handoff for", "buildHandoff": "string \u2014 full BUILD HANDOFF text"}],
   "newTasks": [],
   "boardCorrections": [],
   "productBrief": null,
@@ -8275,7 +8361,7 @@ Everything in Part 1 (natural language) is **display-only**. Part 2 (structured
 **Example with populated fields (DO NOT copy literally \u2014 adapt to your actual analysis):**
 \`\`\`json
 {
-  "newTasks": [{"title": "Example task", "status": "Backlog", "priority": "P2 Medium", "complexity": "Small", "module": "Core", "epic": "Platform", "phase": "Phase 1", "owner": "TBD", "notes": "Created during triage"}],
+  "newTasks": [{"tempId": "new-1", "title": "Example task", "status": "Backlog", "priority": "P2 Medium", "complexity": "Small", "module": "Core", "epic": "Platform", "phase": "Phase 1", "owner": "TBD", "notes": "Created during triage"}],
   "activeDecisions": [{"id": "AD-3", "body": "### AD-3: Use REST over GraphQL [Confidence: HIGH]\\n\\n- **Decision:** REST API for v1.\\n- **Evidence:** Simpler for current scope."}],
   "boardCorrections": [{"taskId": "task-005", "updates": {"priority": "P1 High", "reviewed": true}}, {"taskId": "task-009", "updates": {"status": "Cancelled", "closureReason": "Duplicates task-003"}}],
   "cycleHandoffs": [{"taskId": "task-002", "buildHandoff": "BUILD HANDOFF \u2014 task-002\\nTask: ..."}]
@@ -8313,7 +8399,7 @@ This is Cycle 0 \u2014 the first planning cycle for a brand-new project.
 
 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. Use \`new-N\` IDs to reference them (matching the \`newTasks\` array). The builder needs handoffs to run \`build_execute\` \u2014 without them, tasks must be completed via \`ad_hoc\`, which breaks the normal flow.
+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:
@@ -8484,7 +8570,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.
@@ -8520,7 +8607,7 @@ ${AD_REJECTION_RULES}
    **Reference docs:** If a task's notes include a \`Reference:\` path (e.g. \`Reference: docs/architecture/papi-brain-v1.md\`), include a REFERENCE DOCS section in the BUILD HANDOFF with those paths. This tells the builder to read the referenced doc for background context before implementing. Do NOT omit or summarise the reference \u2014 pass it through so the builder can access the full document. Only tasks with explicit \`Reference:\` paths in their notes should have this section.
    **Full notes lookup:** Notes in the Board section are truncated to 300 chars for concise task selection. When generating a BUILD HANDOFF for a task, check the "Full Notes for Candidate Tasks" section (if present in context) for that task's complete untruncated notes before writing SCOPE, SCOPE BOUNDARY, and PRE-MORTEM. Submitter context, constraints, and reasoning often live past the 300-char cutoff and must not be dropped from the handoff.
    **Pre-build verification:** EVERY handoff MUST include a PRE-BUILD VERIFICATION section listing 2-5 specific file paths the builder should read before implementing. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. This is the #1 prevention mechanism for wasted build slots (C120, C125, C126 all scheduled already-shipped work). If the builder finds >80% of the scope already implemented, they report "already built" instead of re-implementing.
-   **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. Omit this section entirely for projects with fewer than 10 cycles.
+   **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. **If a "Recurring Learning Patterns (cross-cycle)" section is provided in the context, treat a module or theme that recurs across many cycles as a strong signal \u2014 size such tasks up (lean toward the larger estimate) and name the recurring failure mode explicitly in the pre-mortem.** Omit this section entirely for projects with fewer than 10 cycles.
    **Intra-cycle dependency detection:** After selecting cycle tasks, check every pair for build-order dependencies. Two tasks A and B have an intra-cycle dependency when A must be built before B because B consumes an artifact A creates \u2014 e.g. A adds a new adapter method that B calls, A creates a DB migration B depends on, A introduces a new shared type B imports, A refactors a utility B modifies. Signals: same module + adjacent scope (one is "add X", another is "use X"), or notes explicitly reference the other task. For each dependency detected: (a) populate the DEPENDS ON section in the dependent task's BUILD HANDOFF with the upstream task ID(s); (b) add a \`boardCorrections\` entry for the dependent task with \`updates.dependsOn\` set to the comma-separated upstream IDs \u2014 this persists the dependency so the builder's runtime can reuse the upstream branch; (c) keep SCOPE sections independent but note the ordering in "Why now". Do NOT invent dependencies where tasks merely share a module \u2014 only real build-order coupling counts. Linear chains only \u2014 no multi-level graph resolution. When in doubt, omit.
    **Dependency Chain section (Part 1 markdown):** When intra-cycle dependencies are detected, include a visible **## Dependency Chain** section in Part 1 markdown immediately before the first BUILD HANDOFF block. List each dependency as an arrow chain with a brief reason: \`task-A \u2192 task-B (B calls the adapter method A creates)\`. Then show the full recommended build sequence for all cycle tasks, including standalone tasks: e.g. \`Build order: task-A \u2192 task-B; task-C standalone; task-D standalone\`. Flag circular dependencies with \u26A0\uFE0F and a note. Omit this section entirely when no intra-cycle dependencies exist \u2014 do not include an empty section.
    **Build order in cycle log:** If intra-cycle dependencies were detected, include a "Build order:" line in \`cycleLogNotes\` showing the recommended sequence as arrow chains (e.g. "Build order: task-123 \u2192 task-124; task-130 standalone"). Skip when no dependencies exist.
@@ -8544,7 +8631,7 @@ ${AD_REJECTION_RULES}
    - **Architecture Notes:** If a pattern was established that needs follow-up (e.g. "shared service layer created, MCP migration needed"), propose the follow-up.
    - **Strategy gaps:** If an Active Decision has no board tasks supporting it, propose one.
    - **Dogfood observations:** Unactioned dogfood entries span FOUR categories (friction, methodology, signal, commercial) \u2014 consider ALL of them, not just friction. If an entry (with ID) maps to no existing task, propose one, matching task type to category: friction/signal \u2192 fix or improvement; methodology \u2192 process/tooling change; commercial \u2192 GTM/positioning. **CRITICAL: Include \`dogfood:<uuid>\` in the new task's \`notes\` field** (e.g. \`"notes": "dogfood:abc12345-..."\`). This links the task to the observation so the pipeline can track what was actioned. Without this annotation, the observation stays unactioned forever.
-   Create new tasks via the \`newTasks\` array in Part 2. Use \`new-N\` IDs in \`cycleHandoffs\` to reference them. **New-task cap \u2014 scale it to backlog depth, do NOT hard-cap at 3:** when 5+ unblocked backlog candidates already exist, limit new tasks to 3 (there is plenty to select from, so prevent backlog bloat). When the backlog is thin (fewer than 5 unblocked candidates), create as many as needed to bring the cycle into the healthy 5-8 range \u2014 roughly \`6 \u2212 unblocked_candidates\` additional new tasks, derived from the brief, roadmap phases, and recent build reports \u2014 up to an absolute ceiling of **8 new tasks**. This removes the contradiction with the Cycle-sizing rule above (a healthy cycle is 6-10 tasks; <5 needs justification), which the old flat cap of 3 violated whenever the backlog was thin. Never invent filler to hit a number: every new task must trace to a real discovered issue, dogfood entry, roadmap phase, or brief item.
+   Create new tasks via the \`newTasks\` array in Part 2. Give each a unique \`tempId\` (\`"new-1"\`, \`"new-2"\`, \u2026) and set the matching \`cycleHandoffs\` \`taskId\` to that exact tempId (the apply step joins on tempId \u2014 array order is NOT used). **New-task cap \u2014 scale it to backlog depth, do NOT hard-cap at 3:** when 5+ unblocked backlog candidates already exist, limit new tasks to 3 (there is plenty to select from, so prevent backlog bloat). When the backlog is thin (fewer than 5 unblocked candidates), create as many as needed to bring the cycle into the healthy 5-8 range \u2014 roughly \`6 \u2212 unblocked_candidates\` additional new tasks, derived from the brief, roadmap phases, and recent build reports \u2014 up to an absolute ceiling of **8 new tasks**. This removes the contradiction with the Cycle-sizing rule above (a healthy cycle is 6-10 tasks; <5 needs justification), which the old flat cap of 3 violated whenever the backlog was thin. Never invent filler to hit a number: every new task must trace to a real discovered issue, dogfood entry, roadmap phase, or brief item.
    **\u26A0\uFE0F DUPLICATE CHECK:** Before adding a task to \`newTasks\`, scan the Cycle Board above for any existing task with the same or very similar title/scope. If a matching task already exists (even with slightly different wording), do NOT create a duplicate \u2014 reference the existing task ID instead. The board already contains all active tasks; re-creating them wastes IDs and bloats the board.
    **\u26A0\uFE0F ALREADY-BUILT CHECK:** Before creating a task, check the recent build reports and cycle log for evidence that this capability was already shipped. If a recent build report shows this feature was completed (even under a different task name), do NOT create a new task for it. This is especially important for UI features, data models, and integrations that may already exist.`);
   parts.push(PLAN_FRAGMENT_PRODUCT_BRIEF);
@@ -8664,6 +8751,26 @@ function buildPlanUserMessage(ctx) {
     if (ctx.buildPatterns) {
       parts.push("### Build Patterns", "", ctx.buildPatterns, "");
     }
+    if (ctx.learningPatterns) {
+      parts.push(
+        "### Recurring Learning Patterns (cross-cycle)",
+        "",
+        "Tags from cycle learnings (surprises, issues, dead-ends, estimation misses) that keep recurring. Treat a module/theme that recurs across many cycles as a signal: size its tasks up and write a sharper pre-mortem.",
+        "",
+        ctx.learningPatterns,
+        ""
+      );
+    }
+    if (ctx.decisionScorePatterns) {
+      parts.push(
+        "### Decision Risk Scores (high-risk + movement)",
+        "",
+        "Per-decision risk scores (effort+risk+reversibility+scaleCost+lockIn, /25; lower = safer). Decisions flagged \u26A0 high-risk (>15/25) or whose score moved since the last scoring. When a task depends on or advances a \u26A0 high-risk or \u2191 riskier decision, name that decision in the BUILD HANDOFF pre-mortem and lean toward the larger estimate. Do NOT re-score decisions here \u2014 this is read-only input.",
+        "",
+        ctx.decisionScorePatterns,
+        ""
+      );
+    }
     if (ctx.reviewPatterns) {
       parts.push("### Review Patterns", "", ctx.reviewPatterns, "");
     }
@@ -8800,6 +8907,8 @@ function coerceStructuredOutput(parsed) {
     buildHandoff: coerceToString(h.buildHandoff)
   })) : [];
   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,
     title: coerceToString(t.title),
     status: coerceToString(t.status),
     priority: coerceToString(t.priority),
@@ -9128,6 +9237,16 @@ function buildReviewUserMessage(ctx) {
   if (ctx.decisionUsage) {
     parts.push("### Decision Usage (Reference Frequency)", "", ctx.decisionUsage, "");
   }
+  if (ctx.decisionScoreTrajectory) {
+    parts.push(
+      "### Decision Risk Trajectory (score movement)",
+      "",
+      "Decision risk scores (/25, lower = safer) that are high-risk (>15) or have moved since they were last scored. Call out which decisions got riskier (\u2191) and whether their confidence still holds; consider re-scoring or revisiting a decision whose risk is rising.",
+      "",
+      ctx.decisionScoreTrajectory,
+      ""
+    );
+  }
   if (ctx.recommendationEffectiveness) {
     parts.push("### Recommendation Follow-Through", "", ctx.recommendationEffectiveness, "");
   }
@@ -10266,6 +10385,8 @@ function applyContextTier(ctx, cycleCount) {
     ctx.discoveryCanvas = void 0;
     ctx.estimationCalibration = void 0;
     ctx.buildPatterns = void 0;
+    ctx.learningPatterns = void 0;
+    ctx.decisionScorePatterns = void 0;
     ctx.reviewPatterns = void 0;
     ctx.horizonContext = void 0;
     ctx.registeredDocs = void 0;
@@ -10768,7 +10889,9 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
       preAssignedResult,
       reportsForCapsResult,
       contextHashesResult,
-      doneTasksResult
+      doneTasksResult,
+      learningPatternsResult,
+      decisionScoresResult
     ] = await Promise.allSettled([
       detectReviewPatterns(reviews2, health.totalCycles, 5),
       adapter2.getPendingRecommendations(),
@@ -10783,7 +10906,11 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
       adapter2.queryBoard({ status: ["Backlog", "In Cycle", "Ready"], compact: true }),
       Promise.resolve(leanBuildReports.slice(0, 10)),
       adapter2.getContextHashes?.(health.totalCycles) ?? Promise.resolve(null),
-      adapter2.queryBoard({ status: ["Done", "Cancelled"], compact: true })
+      adapter2.queryBoard({ status: ["Done", "Cancelled"], compact: true }),
+      // task-2241: cross-cycle recurring learning patterns (the compounding-intelligence loop).
+      adapter2.getCycleLearningPatterns?.() ?? Promise.resolve([]),
+      // task-2264: per-decision risk scores + movement (second compounding-intelligence signal).
+      adapter2.getDecisionScorePatterns?.() ?? Promise.resolve([])
     ]);
     timings["parallelReads"] = t();
     let reviewPatternsText2;
@@ -10813,6 +10940,8 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
         estimationCalibrationText = (estimationCalibrationText ?? "") + moduleLines;
       }
     }
+    const learningPatternsText = learningPatternsResult.status === "fulfilled" ? formatLearningPatterns(learningPatternsResult.value) : void 0;
+    const decisionScorePatternsText = decisionScoresResult.status === "fulfilled" ? formatDecisionScorePatterns(decisionScoresResult.value) : void 0;
     let registeredDocsText;
     let unactionedDocsTextLean;
     if (docsResult.status === "fulfilled" && docsResult.value && docsResult.value.length > 0) {
@@ -10873,6 +11002,8 @@ ${lines.join("\n")}`;
       taskComments: taskCommentsText,
       discoveryCanvas: discoveryCanvasText,
       estimationCalibration: estimationCalibrationText,
+      learningPatterns: learningPatternsText,
+      decisionScorePatterns: decisionScorePatternsText,
       registeredDocs: registeredDocsText,
       unactionedDocs: unactionedDocsTextLean,
       focus,
@@ -10924,7 +11055,9 @@ ${lines.join("\n")}`;
     taskCommentsResultFull,
     docsResultFull,
     contextHashesResultFull,
-    doneTasksResultFull
+    doneTasksResultFull,
+    learningPatternsResultFull,
+    decisionScoresResultFull
   ] = await Promise.allSettled([
     Promise.resolve(allBuildReports),
     detectReviewPatterns(reviews, health.totalCycles, 5),
@@ -10933,7 +11066,11 @@ ${lines.join("\n")}`;
     assembleTaskComments(adapter2),
     adapter2.searchDocs?.({ status: "active", limit: 15 }),
     adapter2.getContextHashes?.(health.totalCycles) ?? Promise.resolve(null),
-    adapter2.queryBoard({ status: ["Done", "Cancelled"], compact: true })
+    adapter2.queryBoard({ status: ["Done", "Cancelled"], compact: true }),
+    // task-2241: cross-cycle recurring learning patterns (the compounding-intelligence loop).
+    adapter2.getCycleLearningPatterns?.() ?? Promise.resolve([]),
+    // task-2264: per-decision risk scores + movement (second compounding-intelligence signal).
+    adapter2.getDecisionScorePatterns?.() ?? Promise.resolve([])
   ]);
   timings["parallelAdvisory"] = t();
   let buildPatternsText;
@@ -10946,6 +11083,8 @@ ${lines.join("\n")}`;
     } catch {
     }
   }
+  const learningPatternsTextFull = learningPatternsResultFull.status === "fulfilled" ? formatLearningPatterns(learningPatternsResultFull.value) : void 0;
+  const decisionScorePatternsTextFull = decisionScoresResultFull.status === "fulfilled" ? formatDecisionScorePatterns(decisionScoresResultFull.value) : void 0;
   let reviewPatternsText;
   if (reviewPatternsResultFull.status === "fulfilled") {
     reviewPatternsText = hasReviewPatterns(reviewPatternsResultFull.value) ? formatReviewPatterns(reviewPatternsResultFull.value) : void 0;
@@ -11049,6 +11188,8 @@ ${logLines}`);
     methodologyMetrics: formatCycleMetrics(metricsSnapshots),
     recentReviews: formatReviews(reviews),
     buildPatterns: buildPatternsText,
+    learningPatterns: learningPatternsTextFull,
+    decisionScorePatterns: decisionScorePatternsTextFull,
     reviewPatterns: reviewPatternsText,
     horizonContext: horizonCtx,
     strategyRecommendations: strategyRecommendationsText,
@@ -11180,6 +11321,8 @@ ${cleanContent}`;
       strategicDirection: data.strategicDirection
     },
     newTasks: dedupedNewTasks.map((t) => ({
+      tempId: t.tempId,
+      // task-2242: stable handoff join key
       title: t.title,
       status: t.status || "Backlog",
       priority: t.priority || "P1 High",
@@ -11329,7 +11472,7 @@ ${cleanContent}`;
         visibility,
         ownerUserId: inheritedVis.ownerUserId
       });
-      newTaskIdMap.set(`new-${i + 1}`, created.id);
+      newTaskIdMap.set(newTaskJoinKey(task, i), created.id);
       if (adapter2.updateCycleLearningActionRef && task.notes) {
         const learningRefs = task.notes.match(/learning:([a-f0-9-]+)/gi);
         if (learningRefs) {
@@ -11488,6 +11631,13 @@ ${cleanContent}`;
     }
     for (const handoff of data.cycleHandoffs) {
       const resolvedId = newTaskIdMap.get(handoff.taskId) ?? handoff.taskId;
+      if (resolvedId === handoff.taskId && /^new-\d+$/i.test(handoff.taskId)) {
+        const titleLine = handoff.buildHandoff.match(/^Task:\s*(.+)/m)?.[1] ?? "(unknown)";
+        console.error(
+          `[plan] UNRESOLVED handoff reference "${handoff.taskId}" (task: ${titleLine.slice(0, 80)}) \u2014 no newTask carries this tempId/index. Handoff NOT written. Ensure each newTasks entry has a tempId matching its cycleHandoffs taskId (task-2242).`
+        );
+        continue;
+      }
       try {
         if (existingHandoffSet.has(resolvedId)) {
           console.error(`[plan] skipping handoff write for ${resolvedId} \u2014 already has one`);
@@ -12016,6 +12166,7 @@ function defaultHint(tool) {
     "plan",
     "strategy_review",
     "orient",
+    "papi",
     "build_execute",
     "review_list",
     "review_submit",
@@ -13444,7 +13595,8 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     recData,
     pendingRecs,
     registeredDocs,
-    docsWithPendingActions
+    docsWithPendingActions,
+    decisionScores
   ] = await Promise.all([
     adapter2.readProductBrief(),
     // Strategy review needs to see retired ADs to triage/restore them as needed.
@@ -13471,7 +13623,9 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     // Doc registry — summaries for strategy review context
     adapter2.searchDocs?.({ status: "active", limit: 10 })?.catch(() => []) ?? Promise.resolve([]),
     // Doc registry — docs with pending actions for staleness audit
-    adapter2.searchDocs?.({ hasPendingActions: true, limit: 20 })?.catch(() => []) ?? Promise.resolve([])
+    adapter2.searchDocs?.({ hasPendingActions: true, limit: 20 })?.catch(() => []) ?? Promise.resolve([]),
+    // task-2264: decision risk scores + movement, so the review can show trajectory.
+    adapter2.getDecisionScorePatterns?.()?.catch(() => []) ?? Promise.resolve([])
   ]);
   const pendingAgendaTopics = await (adapter2.getPendingAgendaTopics?.().catch(() => []) ?? Promise.resolve([]));
   const tasks = [...activeTasks, ...recentDoneTasks];
@@ -13752,6 +13906,7 @@ ${lines.join("\n")}`;
     previousReviews: previousReviewsText,
     phases: phasesText,
     decisionUsage: decisionUsageText,
+    decisionScoreTrajectory: formatDecisionScorePatterns(decisionScores),
     northStar: currentNorthStar ?? void 0,
     recommendationEffectiveness: recEffectivenessText,
     adHocCommits: adHocCommitsText,
@@ -17541,12 +17696,60 @@ ${existing}`;
   }
   await writeFile3(changelogPath, body, "utf-8");
 }
-function mergeGroupedCycleBranches(config2, cycleNum, baseBranch) {
+async function allCancelledBranches(adapter2, cycleNum) {
+  const skip = /* @__PURE__ */ new Set();
+  try {
+    const ALL_STATUSES = [
+      "Backlog",
+      "In Cycle",
+      "Ready",
+      "In Progress",
+      "In Review",
+      "Done",
+      "Blocked",
+      "Cancelled",
+      "Deferred"
+    ];
+    const tasks = await adapter2.queryBoard({ cycleSince: cycleNum, status: ALL_STATUSES, compact: true });
+    const byModule = /* @__PURE__ */ new Map();
+    for (const t of tasks) {
+      if (t.cycle !== cycleNum) continue;
+      const moduleName = (t.module ?? "").trim();
+      if (!moduleName) continue;
+      const entry = byModule.get(moduleName) ?? { total: 0, cancelled: 0 };
+      entry.total++;
+      if (t.status === "Cancelled") entry.cancelled++;
+      byModule.set(moduleName, entry);
+    }
+    for (const [moduleName, entry] of byModule) {
+      if (entry.total > 0 && entry.cancelled === entry.total) {
+        skip.add(cycleBranchName(cycleNum, moduleName));
+      }
+    }
+  } catch {
+  }
+  return skip;
+}
+function mergeGroupedCycleBranches(config2, cycleNum, baseBranch, skipBranches = /* @__PURE__ */ new Set()) {
   const branches = listGroupedCycleBranches(config2.projectRoot, cycleNum, baseBranch);
   if (branches.length === 0) return [];
   const ghAvailable = isGhAvailable();
   const results = [];
   for (const branch of branches) {
+    if (skipBranches.has(branch)) {
+      results.push({ branch, prUrl: null, status: "skipped", message: "all cycle tasks Cancelled \u2014 branch not merged (task-2253)" });
+      continue;
+    }
+    if (isBranchContentAlreadyInBase(config2.projectRoot, branch, baseBranch)) {
+      deleteLocalBranch(config2.projectRoot, branch);
+      results.push({
+        branch,
+        prUrl: null,
+        status: "skipped",
+        message: `content already on '${baseBranch}' (tree-equal \u2014 squash-merged); lingering branch cleaned, no re-merge`
+      });
+      continue;
+    }
     if (branchExists(config2.projectRoot, branch) && hasRemote(config2.projectRoot)) {
       const push = gitPush(config2.projectRoot, branch);
       if (!push.success) {
@@ -17769,7 +17972,8 @@ async function createRelease(config2, branch, version, adapter2, cycleNum, optio
   }
   let groupedBranchMerges;
   if (resolvedCycleNum > 0) {
-    const mergeResults = mergeGroupedCycleBranches(config2, resolvedCycleNum, branch);
+    const skipBranches = adapter2 ? await allCancelledBranches(adapter2, resolvedCycleNum) : /* @__PURE__ */ new Set();
+    const mergeResults = mergeGroupedCycleBranches(config2, resolvedCycleNum, branch, skipBranches);
     if (mergeResults.length > 0) {
       groupedBranchMerges = mergeResults;
       const failures = mergeResults.filter((r) => r.status === "failed");
@@ -18573,6 +18777,23 @@ If you intend to discard the work, run build_cancel instead.`
   err.gitStderr = scrubbed;
   return err;
 }
+var UI_FILE_RE = /^(app\/.+\.(tsx|css)|components\/.+\.tsx)$/;
+var NON_UI_RE = /(^app\/api\/|\.test\.|\.spec\.|\/__tests__\/)/;
+function inferRouteFromPage(file) {
+  const m = file.match(/^app\/(.*)\/page\.tsx$/);
+  if (!m) return null;
+  const segments = m[1].split("/").filter((s) => s.length > 0 && !(s.startsWith("(") && s.endsWith(")")));
+  return "/" + segments.join("/");
+}
+function computeLocalPreview(filesChanged, provided) {
+  const uiFiles = (filesChanged ?? []).filter((f) => UI_FILE_RE.test(f) && !NON_UI_RE.test(f));
+  const hasProvided = !!(provided && (provided.urls?.length || provided.screenshotPath || provided.notes));
+  if (uiFiles.length === 0 && !hasProvided) return void 0;
+  const routes = Array.from(
+    new Set(uiFiles.map(inferRouteFromPage).filter((r) => r !== null))
+  );
+  return { uiFiles, routes, provided: hasProvided ? provided : void 0 };
+}
 var AMBIENT_DRIFT_PATTERNS = [
   /^\.next\//,
   /^\.next$/,
@@ -19249,6 +19470,7 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     const drift = computeScopeDriftSignal(task.buildHandoff?.filesLikelyTouched, driftChanged);
     if (drift) report.scopeDriftSignal = drift;
   }
+  const localPreview = computeLocalPreview(report.filesChanged, input.preview);
   let prLines = [];
   if (options.light) {
     prLines.push("Light mode: skipping push and PR creation.");
@@ -19351,7 +19573,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     autoTriagedCount: autoTriagedCount > 0 ? autoTriagedCount : void 0,
     autoTriagedIds: autoTriagedIds.length > 0 ? autoTriagedIds : void 0,
     autoTriagedDupes: autoTriagedDupes.length > 0 ? autoTriagedDupes : void 0,
-    reportWriteVerified
+    reportWriteVerified,
+    localPreview
   };
 }
 async function cancelBuild(adapter2, taskId, reason) {
@@ -19571,6 +19794,15 @@ var buildExecuteTool = {
           verified_at: { type: "string", description: "ISO 8601 timestamp." }
         },
         required: ["urls", "curl_command", "http_status", "response_excerpt", "verified_at"]
+      },
+      preview: {
+        type: "object",
+        description: `Optional. For a build that touched USER-FACING UI: tell the owner how to SEE the result locally so reviewing it doesn't mean reading code or asking "show me". urls = the localhost route(s) to open (e.g. ["http://localhost:3000/hub"]); notes = what to look at; screenshot_path = a path to an image you captured. Surfaced verbatim in the completion output. When the diff touched UI and you omit this, the output nudges you to provide it.`,
+        properties: {
+          urls: { type: "array", items: { type: "string" }, description: "Localhost route(s) to open to view the work." },
+          notes: { type: "string", description: "What the owner should look at / verify." },
+          screenshot_path: { type: "string", description: "Path to a captured screenshot of the rendered result." }
+        }
       }
     },
     required: ["task_id"]
@@ -19848,6 +20080,12 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
   const deadEnds = args.dead_ends;
   const rawBriefImplications = args.brief_implications;
   const resolvesLearnings = Array.isArray(args.resolves_learnings) ? args.resolves_learnings : void 0;
+  const rawPreview = args.preview;
+  const preview = rawPreview ? {
+    urls: Array.isArray(rawPreview.urls) ? rawPreview.urls.filter((u) => typeof u === "string") : void 0,
+    notes: typeof rawPreview.notes === "string" ? rawPreview.notes : void 0,
+    screenshotPath: typeof rawPreview.screenshot_path === "string" ? rawPreview.screenshot_path : void 0
+  } : void 0;
   const rawProductionVerification = args.production_verification;
   const productionVerification = rawProductionVerification ? {
     urls: Array.isArray(rawProductionVerification.urls) ? rawProductionVerification.urls.filter((u) => typeof u === "string") : [],
@@ -19904,7 +20142,8 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
         type: bi.type ?? "new",
         detail: bi.detail ?? ""
       })),
-      productionVerification
+      productionVerification,
+      preview
     }, { light });
     tracker.mark("complete_format");
     if (resolvesLearnings && resolvesLearnings.length > 0 && adapter2.updateCycleLearningActionRef) {
@@ -19961,6 +20200,26 @@ function formatCompleteResult(result) {
   if (result.cycleProgress.total > 0) {
     lines.push("", `Cycle progress: ${result.cycleProgress.completed} of ${result.cycleProgress.total} cycle tasks complete.`);
   }
+  if (result.localPreview) {
+    const { routes, provided, uiFiles } = result.localPreview;
+    const previewLines = ["", "### \u{1F441} Preview the work"];
+    if (provided?.urls?.length) {
+      previewLines.push(`Open: ${provided.urls.join(" \xB7 ")}`);
+    } else if (routes.length > 0) {
+      const urls = routes.map((r) => `http://localhost:3000${r}`);
+      previewLines.push(`Run \`npm run dev\` and open: ${urls.join(" \xB7 ")}`);
+    } else {
+      previewLines.push(
+        `This build changed UI (${uiFiles.slice(0, 4).join(", ")}${uiFiles.length > 4 ? `, +${uiFiles.length - 4} more` : ""}). Run \`npm run dev\` and open the page that renders it.`
+      );
+    }
+    if (provided?.screenshotPath) previewLines.push(`Screenshot: ${provided.screenshotPath}`);
+    if (provided?.notes) previewLines.push(`Look at: ${provided.notes}`);
+    if (!provided) {
+      previewLines.push("_Tip: pass `preview` (the route you viewed / a screenshot) on complete so the result travels with the build._");
+    }
+    lines.push(...previewLines);
+  }
   if (result.phaseChanges.length > 0) {
     for (const c of result.phaseChanges) {
       lines.push(`Phase auto-updated: ${c.phaseId} ${c.oldStatus} \u2192 ${c.newStatus}`);
@@ -20239,6 +20498,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 +20525,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 +20557,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 +20585,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 +20631,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 +23031,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 +23850,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 +26384,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 +26535,7 @@ var TOOLS_REQUIRING_PAPI = /* @__PURE__ */ new Set([
   "review_list",
   "review_submit",
   "orient",
+  "papi",
   "hierarchy_update",
   "zoom_out",
   "handoff_generate",
@@ -26273,6 +26567,7 @@ var PAPI_TOOLS = [
   reviewClaimTool,
   initTool,
   orientTool,
+  papiTool,
   hierarchyUpdateTool,
   zoomOutTool,
   docRegisterTool,
@@ -26447,6 +26742,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 +26816,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) {
@@ -26588,6 +26886,8 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 var BEARER_PREFIX = "papi_";
 var BEARER_REGEX = /^(papi_|papi_oauth_)[a-f0-9]{64}$/;
 var RESOURCE_METADATA_URL = process.env["PAPI_RESOURCE_METADATA_URL"] ?? "https://getpapi.ai/.well-known/oauth-protected-resource";
+var DASHBOARD_ORIGIN = process.env["PAPI_DASHBOARD_URL"] ?? "https://getpapi.ai";
+var MCP_RESOURCE_URL = process.env["NEXT_PUBLIC_MCP_URL"] ?? "https://mcp.getpapi.ai";
 var FRIENDLY_GET_HTML = `<!doctype html>
 <html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -26715,6 +27015,31 @@ function startHttpTransport(opts) {
       res.end("ok");
       return;
     }
+    if (req.method === "GET" && req.url === "/.well-known/oauth-protected-resource") {
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Cache-Control": "public, max-age=3600",
+        ...cors
+      });
+      res.end(
+        JSON.stringify({
+          resource: MCP_RESOURCE_URL,
+          authorization_servers: [DASHBOARD_ORIGIN],
+          scopes_supported: ["mcp:full"],
+          bearer_methods_supported: ["header"]
+        })
+      );
+      return;
+    }
+    if (req.method === "GET" && req.url === "/.well-known/oauth-authorization-server") {
+      res.writeHead(302, {
+        Location: `${DASHBOARD_ORIGIN}/.well-known/oauth-authorization-server`,
+        "Cache-Control": "public, max-age=3600",
+        ...cors
+      });
+      res.end();
+      return;
+    }
     if (req.url !== "/mcp" && req.url !== "/sse") {
       sendError(res, { status: 404, body: { error: "Not found" } }, cors);
       return;
@@ -27108,7 +27433,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

@@ -89,7 +89,7 @@ After your natural language output, include this EXACT format on its own line:
   "boardHealth": "string \u2014 e.g. 5 tasks (3 backlog, 2 done)",
   "strategicDirection": "string \u2014 one sentence about current phase/direction",
   "recommendedTaskId": "string or null \u2014 task ID to set In Progress",
-  "cycleHandoffs": [{"taskId": "string \u2014 existing task ID or new-N for new tasks", "buildHandoff": "string \u2014 full BUILD HANDOFF text"}],
+  "cycleHandoffs": [{"taskId": "string \u2014 an existing task ID, or the EXACT tempId of a newTasks entry (e.g. "new-1") it provides the handoff for", "buildHandoff": "string \u2014 full BUILD HANDOFF text"}],
   "newTasks": [],
   "boardCorrections": [],
   "productBrief": null,
@@ -134,7 +134,7 @@ Everything in Part 1 (natural language) is **display-only**. Part 2 (structured
 **Example with populated fields (DO NOT copy literally \u2014 adapt to your actual analysis):**
 \`\`\`json
 {
-  "newTasks": [{"title": "Example task", "status": "Backlog", "priority": "P2 Medium", "complexity": "Small", "module": "Core", "epic": "Platform", "phase": "Phase 1", "owner": "TBD", "notes": "Created during triage"}],
+  "newTasks": [{"tempId": "new-1", "title": "Example task", "status": "Backlog", "priority": "P2 Medium", "complexity": "Small", "module": "Core", "epic": "Platform", "phase": "Phase 1", "owner": "TBD", "notes": "Created during triage"}],
   "activeDecisions": [{"id": "AD-3", "body": "### AD-3: Use REST over GraphQL [Confidence: HIGH]\\n\\n- **Decision:** REST API for v1.\\n- **Evidence:** Simpler for current scope."}],
   "boardCorrections": [{"taskId": "task-005", "updates": {"priority": "P1 High", "reviewed": true}}, {"taskId": "task-009", "updates": {"status": "Cancelled", "closureReason": "Duplicates task-003"}}],
   "cycleHandoffs": [{"taskId": "task-002", "buildHandoff": "BUILD HANDOFF \u2014 task-002\\nTask: ..."}]
@@ -172,7 +172,7 @@ This is Cycle 0 \u2014 the first planning cycle for a brand-new project.
 
 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. Use \`new-N\` IDs to reference them (matching the \`newTasks\` array). The builder needs handoffs to run \`build_execute\` \u2014 without them, tasks must be completed via \`ad_hoc\`, which breaks the normal flow.
+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:
@@ -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.
@@ -379,7 +380,7 @@ ${AD_REJECTION_RULES}
    **Reference docs:** If a task's notes include a \`Reference:\` path (e.g. \`Reference: docs/architecture/papi-brain-v1.md\`), include a REFERENCE DOCS section in the BUILD HANDOFF with those paths. This tells the builder to read the referenced doc for background context before implementing. Do NOT omit or summarise the reference \u2014 pass it through so the builder can access the full document. Only tasks with explicit \`Reference:\` paths in their notes should have this section.
    **Full notes lookup:** Notes in the Board section are truncated to 300 chars for concise task selection. When generating a BUILD HANDOFF for a task, check the "Full Notes for Candidate Tasks" section (if present in context) for that task's complete untruncated notes before writing SCOPE, SCOPE BOUNDARY, and PRE-MORTEM. Submitter context, constraints, and reasoning often live past the 300-char cutoff and must not be dropped from the handoff.
    **Pre-build verification:** EVERY handoff MUST include a PRE-BUILD VERIFICATION section listing 2-5 specific file paths the builder should read before implementing. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. This is the #1 prevention mechanism for wasted build slots (C120, C125, C126 all scheduled already-shipped work). If the builder finds >80% of the scope already implemented, they report "already built" instead of re-implementing.
-   **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. Omit this section entirely for projects with fewer than 10 cycles.
+   **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. **If a "Recurring Learning Patterns (cross-cycle)" section is provided in the context, treat a module or theme that recurs across many cycles as a strong signal \u2014 size such tasks up (lean toward the larger estimate) and name the recurring failure mode explicitly in the pre-mortem.** Omit this section entirely for projects with fewer than 10 cycles.
    **Intra-cycle dependency detection:** After selecting cycle tasks, check every pair for build-order dependencies. Two tasks A and B have an intra-cycle dependency when A must be built before B because B consumes an artifact A creates \u2014 e.g. A adds a new adapter method that B calls, A creates a DB migration B depends on, A introduces a new shared type B imports, A refactors a utility B modifies. Signals: same module + adjacent scope (one is "add X", another is "use X"), or notes explicitly reference the other task. For each dependency detected: (a) populate the DEPENDS ON section in the dependent task's BUILD HANDOFF with the upstream task ID(s); (b) add a \`boardCorrections\` entry for the dependent task with \`updates.dependsOn\` set to the comma-separated upstream IDs \u2014 this persists the dependency so the builder's runtime can reuse the upstream branch; (c) keep SCOPE sections independent but note the ordering in "Why now". Do NOT invent dependencies where tasks merely share a module \u2014 only real build-order coupling counts. Linear chains only \u2014 no multi-level graph resolution. When in doubt, omit.
    **Dependency Chain section (Part 1 markdown):** When intra-cycle dependencies are detected, include a visible **## Dependency Chain** section in Part 1 markdown immediately before the first BUILD HANDOFF block. List each dependency as an arrow chain with a brief reason: \`task-A \u2192 task-B (B calls the adapter method A creates)\`. Then show the full recommended build sequence for all cycle tasks, including standalone tasks: e.g. \`Build order: task-A \u2192 task-B; task-C standalone; task-D standalone\`. Flag circular dependencies with \u26A0\uFE0F and a note. Omit this section entirely when no intra-cycle dependencies exist \u2014 do not include an empty section.
    **Build order in cycle log:** If intra-cycle dependencies were detected, include a "Build order:" line in \`cycleLogNotes\` showing the recommended sequence as arrow chains (e.g. "Build order: task-123 \u2192 task-124; task-130 standalone"). Skip when no dependencies exist.
@@ -403,7 +404,7 @@ ${AD_REJECTION_RULES}
    - **Architecture Notes:** If a pattern was established that needs follow-up (e.g. "shared service layer created, MCP migration needed"), propose the follow-up.
    - **Strategy gaps:** If an Active Decision has no board tasks supporting it, propose one.
    - **Dogfood observations:** Unactioned dogfood entries span FOUR categories (friction, methodology, signal, commercial) \u2014 consider ALL of them, not just friction. If an entry (with ID) maps to no existing task, propose one, matching task type to category: friction/signal \u2192 fix or improvement; methodology \u2192 process/tooling change; commercial \u2192 GTM/positioning. **CRITICAL: Include \`dogfood:<uuid>\` in the new task's \`notes\` field** (e.g. \`"notes": "dogfood:abc12345-..."\`). This links the task to the observation so the pipeline can track what was actioned. Without this annotation, the observation stays unactioned forever.
-   Create new tasks via the \`newTasks\` array in Part 2. Use \`new-N\` IDs in \`cycleHandoffs\` to reference them. **New-task cap \u2014 scale it to backlog depth, do NOT hard-cap at 3:** when 5+ unblocked backlog candidates already exist, limit new tasks to 3 (there is plenty to select from, so prevent backlog bloat). When the backlog is thin (fewer than 5 unblocked candidates), create as many as needed to bring the cycle into the healthy 5-8 range \u2014 roughly \`6 \u2212 unblocked_candidates\` additional new tasks, derived from the brief, roadmap phases, and recent build reports \u2014 up to an absolute ceiling of **8 new tasks**. This removes the contradiction with the Cycle-sizing rule above (a healthy cycle is 6-10 tasks; <5 needs justification), which the old flat cap of 3 violated whenever the backlog was thin. Never invent filler to hit a number: every new task must trace to a real discovered issue, dogfood entry, roadmap phase, or brief item.
+   Create new tasks via the \`newTasks\` array in Part 2. Give each a unique \`tempId\` (\`"new-1"\`, \`"new-2"\`, \u2026) and set the matching \`cycleHandoffs\` \`taskId\` to that exact tempId (the apply step joins on tempId \u2014 array order is NOT used). **New-task cap \u2014 scale it to backlog depth, do NOT hard-cap at 3:** when 5+ unblocked backlog candidates already exist, limit new tasks to 3 (there is plenty to select from, so prevent backlog bloat). When the backlog is thin (fewer than 5 unblocked candidates), create as many as needed to bring the cycle into the healthy 5-8 range \u2014 roughly \`6 \u2212 unblocked_candidates\` additional new tasks, derived from the brief, roadmap phases, and recent build reports \u2014 up to an absolute ceiling of **8 new tasks**. This removes the contradiction with the Cycle-sizing rule above (a healthy cycle is 6-10 tasks; <5 needs justification), which the old flat cap of 3 violated whenever the backlog was thin. Never invent filler to hit a number: every new task must trace to a real discovered issue, dogfood entry, roadmap phase, or brief item.
    **\u26A0\uFE0F DUPLICATE CHECK:** Before adding a task to \`newTasks\`, scan the Cycle Board above for any existing task with the same or very similar title/scope. If a matching task already exists (even with slightly different wording), do NOT create a duplicate \u2014 reference the existing task ID instead. The board already contains all active tasks; re-creating them wastes IDs and bloats the board.
    **\u26A0\uFE0F ALREADY-BUILT CHECK:** Before creating a task, check the recent build reports and cycle log for evidence that this capability was already shipped. If a recent build report shows this feature was completed (even under a different task name), do NOT create a new task for it. This is especially important for UI features, data models, and integrations that may already exist.`);
   parts.push(PLAN_FRAGMENT_PRODUCT_BRIEF);
@@ -523,6 +524,26 @@ function buildPlanUserMessage(ctx) {
     if (ctx.buildPatterns) {
       parts.push("### Build Patterns", "", ctx.buildPatterns, "");
     }
+    if (ctx.learningPatterns) {
+      parts.push(
+        "### Recurring Learning Patterns (cross-cycle)",
+        "",
+        "Tags from cycle learnings (surprises, issues, dead-ends, estimation misses) that keep recurring. Treat a module/theme that recurs across many cycles as a signal: size its tasks up and write a sharper pre-mortem.",
+        "",
+        ctx.learningPatterns,
+        ""
+      );
+    }
+    if (ctx.decisionScorePatterns) {
+      parts.push(
+        "### Decision Risk Scores (high-risk + movement)",
+        "",
+        "Per-decision risk scores (effort+risk+reversibility+scaleCost+lockIn, /25; lower = safer). Decisions flagged \u26A0 high-risk (>15/25) or whose score moved since the last scoring. When a task depends on or advances a \u26A0 high-risk or \u2191 riskier decision, name that decision in the BUILD HANDOFF pre-mortem and lean toward the larger estimate. Do NOT re-score decisions here \u2014 this is read-only input.",
+        "",
+        ctx.decisionScorePatterns,
+        ""
+      );
+    }
     if (ctx.reviewPatterns) {
       parts.push("### Review Patterns", "", ctx.reviewPatterns, "");
     }
@@ -659,6 +680,8 @@ function coerceStructuredOutput(parsed) {
     buildHandoff: coerceToString(h.buildHandoff)
   })) : [];
   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,
     title: coerceToString(t.title),
     status: coerceToString(t.status),
     priority: coerceToString(t.priority),
@@ -987,6 +1010,16 @@ function buildReviewUserMessage(ctx) {
   if (ctx.decisionUsage) {
     parts.push("### Decision Usage (Reference Frequency)", "", ctx.decisionUsage, "");
   }
+  if (ctx.decisionScoreTrajectory) {
+    parts.push(
+      "### Decision Risk Trajectory (score movement)",
+      "",
+      "Decision risk scores (/25, lower = safer) that are high-risk (>15) or have moved since they were last scored. Call out which decisions got riskier (\u2191) and whether their confidence still holds; consider re-scoring or revisiting a decision whose risk is rising.",
+      "",
+      ctx.decisionScoreTrajectory,
+      ""
+    );
+  }
   if (ctx.recommendationEffectiveness) {
     parts.push("### Recommendation Follow-Through", "", ctx.recommendationEffectiveness, "");
   }

package/package.json

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