@papi-ai/server 0.7.46 → 0.7.48

package/dist/backfill-cycle-metrics.js

@@ -4519,31 +4519,66 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
 }
 
 // src/lib/formatters.ts
-var EFFORT_MAP = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
-function computeSnapshotsFromBuildReports(reports) {
-  if (reports.length === 0) return [];
-  const byCycleMap = /* @__PURE__ */ new Map();
+function effortWeight(size) {
+  switch ((size || "").toUpperCase()) {
+    case "XS":
+      return 1;
+    case "S":
+    case "SMALL":
+      return 2;
+    case "M":
+    case "MEDIUM":
+      return 3;
+    case "L":
+    case "LARGE":
+      return 5;
+    case "XL":
+      return 8;
+    default:
+      return 3;
+  }
+}
+function computeSnapshotsFromBuildReports(reports, tasks) {
+  const reportsByCycle = /* @__PURE__ */ new Map();
   for (const r of reports) {
-    const existing = byCycleMap.get(r.cycle) ?? [];
+    const existing = reportsByCycle.get(r.cycle) ?? [];
     existing.push(r);
-    byCycleMap.set(r.cycle, existing);
+    reportsByCycle.set(r.cycle, existing);
   }
+  const tasksByCycle = /* @__PURE__ */ new Map();
+  for (const t of tasks ?? []) {
+    if (t.cycle == null) continue;
+    const existing = tasksByCycle.get(t.cycle) ?? [];
+    existing.push(t);
+    tasksByCycle.set(t.cycle, existing);
+  }
+  const cycleNumbers = /* @__PURE__ */ new Set([...reportsByCycle.keys(), ...tasksByCycle.keys()]);
+  if (cycleNumbers.size === 0) return [];
   const snapshots = [];
-  for (const [sn, cycleReports] of byCycleMap) {
-    const completed = cycleReports.filter((r) => r.completed === "Yes").length;
-    const total = cycleReports.length;
+  for (const sn of cycleNumbers) {
+    const cycleReports = reportsByCycle.get(sn) ?? [];
+    const cycleTaskRows = tasksByCycle.get(sn);
     const withEffort = cycleReports.filter((r) => r.estimatedEffort && r.actualEffort);
     const accurate = withEffort.filter((r) => r.estimatedEffort === r.actualEffort).length;
     const matchRate = withEffort.length > 0 ? Math.round(accurate / withEffort.length * 100) : 0;
-    let effortPoints = 0;
-    for (const r of cycleReports) {
-      effortPoints += EFFORT_MAP[r.actualEffort] ?? 3;
+    let completed;
+    let total;
+    let effortPoints;
+    if (cycleTaskRows && cycleTaskRows.length > 0) {
+      const done = cycleTaskRows.filter((t) => t.status === "Done");
+      completed = done.length;
+      total = cycleTaskRows.length;
+      effortPoints = done.reduce((s, t) => s + effortWeight(t.complexity), 0);
+    } else {
+      completed = cycleReports.filter((r) => r.completed === "Yes").length;
+      total = cycleReports.length;
+      effortPoints = cycleReports.reduce((s, r) => s + effortWeight(r.actualEffort), 0);
     }
     snapshots.push({
       cycle: sn,
       date: (/* @__PURE__ */ new Date()).toISOString(),
-      accuracy: [{ cycle: sn, reports: total, matchRate, mae: 0, bias: 0 }],
-      velocity: [{ cycle: sn, completed, partial: 0, failed: total - completed, effortPoints }]
+      accuracy: [{ cycle: sn, reports: cycleReports.length, matchRate, mae: 0, bias: 0 }],
+      velocity: [{ cycle: sn, completed, partial: 0, failed: Math.max(0, total - completed), effortPoints }]
     });
   }
   snapshots.sort((a, b) => a.cycle - b.cycle);

package/dist/index.js

@@ -8306,31 +8306,66 @@ function formatBoardForReview(tasks) {
   Notes: ${t.notes}` : ""}`
   ).join("\n\n");
 }
-var EFFORT_MAP = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
-function computeSnapshotsFromBuildReports(reports) {
-  if (reports.length === 0) return [];
-  const byCycleMap = /* @__PURE__ */ new Map();
+function effortWeight(size2) {
+  switch ((size2 || "").toUpperCase()) {
+    case "XS":
+      return 1;
+    case "S":
+    case "SMALL":
+      return 2;
+    case "M":
+    case "MEDIUM":
+      return 3;
+    case "L":
+    case "LARGE":
+      return 5;
+    case "XL":
+      return 8;
+    default:
+      return 3;
+  }
+}
+function computeSnapshotsFromBuildReports(reports, tasks) {
+  const reportsByCycle = /* @__PURE__ */ new Map();
   for (const r of reports) {
-    const existing = byCycleMap.get(r.cycle) ?? [];
+    const existing = reportsByCycle.get(r.cycle) ?? [];
     existing.push(r);
-    byCycleMap.set(r.cycle, existing);
+    reportsByCycle.set(r.cycle, existing);
   }
+  const tasksByCycle = /* @__PURE__ */ new Map();
+  for (const t of tasks ?? []) {
+    if (t.cycle == null) continue;
+    const existing = tasksByCycle.get(t.cycle) ?? [];
+    existing.push(t);
+    tasksByCycle.set(t.cycle, existing);
+  }
+  const cycleNumbers = /* @__PURE__ */ new Set([...reportsByCycle.keys(), ...tasksByCycle.keys()]);
+  if (cycleNumbers.size === 0) return [];
   const snapshots = [];
-  for (const [sn, cycleReports] of byCycleMap) {
-    const completed = cycleReports.filter((r) => r.completed === "Yes").length;
-    const total = cycleReports.length;
+  for (const sn of cycleNumbers) {
+    const cycleReports = reportsByCycle.get(sn) ?? [];
+    const cycleTaskRows = tasksByCycle.get(sn);
     const withEffort = cycleReports.filter((r) => r.estimatedEffort && r.actualEffort);
     const accurate = withEffort.filter((r) => r.estimatedEffort === r.actualEffort).length;
     const matchRate = withEffort.length > 0 ? Math.round(accurate / withEffort.length * 100) : 0;
-    let effortPoints = 0;
-    for (const r of cycleReports) {
-      effortPoints += EFFORT_MAP[r.actualEffort] ?? 3;
+    let completed;
+    let total;
+    let effortPoints;
+    if (cycleTaskRows && cycleTaskRows.length > 0) {
+      const done = cycleTaskRows.filter((t) => t.status === "Done");
+      completed = done.length;
+      total = cycleTaskRows.length;
+      effortPoints = done.reduce((s, t) => s + effortWeight(t.complexity), 0);
+    } else {
+      completed = cycleReports.filter((r) => r.completed === "Yes").length;
+      total = cycleReports.length;
+      effortPoints = cycleReports.reduce((s, r) => s + effortWeight(r.actualEffort), 0);
     }
     snapshots.push({
       cycle: sn,
       date: (/* @__PURE__ */ new Date()).toISOString(),
-      accuracy: [{ cycle: sn, reports: total, matchRate, mae: 0, bias: 0 }],
-      velocity: [{ cycle: sn, completed, partial: 0, failed: total - completed, effortPoints }]
+      accuracy: [{ cycle: sn, reports: cycleReports.length, matchRate, mae: 0, bias: 0 }],
+      velocity: [{ cycle: sn, completed, partial: 0, failed: Math.max(0, total - completed), effortPoints }]
     });
   }
   snapshots.sort((a, b2) => a.cycle - b2.cycle);
@@ -8679,7 +8714,7 @@ REFERENCE DOCS
 [Optional \u2014 paths to docs/ files that provide background context for this task. Include only when the task originated from research or scoping work and the doc contains context the builder will need beyond what is in this handoff. Omit this section entirely for tasks that don't need supplementary context.]
 
 PRE-BUILD VERIFICATION
-[List 2-5 specific file paths the builder should read BEFORE implementing to check if the functionality already exists. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. If >80% of the scope is already implemented, the builder should report "already built" instead of re-implementing. Include this section for EVERY task \u2014 it prevents wasted build slots on already-shipped code.]
+[List 2-5 specific file paths the builder should read BEFORE implementing to check if the functionality already exists. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. ALSO mandate a docs sweep, not just file-existence (task-2161): name any docs the builder should check via doc_search or the docs index \u2014 a design/research/status:final doc or a prior task may already cover the work. If >80% of the scope is already implemented, the builder should report "already built" instead of re-implementing. Include this section for EVERY task \u2014 it prevents wasted build slots on already-shipped code.]
 
 FILES LIKELY TOUCHED
 [files]
@@ -9274,7 +9309,7 @@ function buildHandoffsOnlyUserMessage(inputs) {
 }
 function extractDependencyChain(displayText) {
   const match = displayText.match(
-    /^##\s+Dependency Chain[^\n]*\n([\s\S]*?)(?=\n#{2,3}\s|$(?![\s\S]))/m
+    /^##\s+Dependency Chain[^\n]*\n([\s\S]*?)(?=\n#{2,3}\s|\n-{3,}\s*(?:\n|$)|\n\s*BUILD HANDOFF\b|\n<!--\s*PAPI_STRUCTURED_OUTPUT|$(?![\s\S]))/m
   );
   if (!match) return void 0;
   const body = match[1].trim();
@@ -10770,7 +10805,8 @@ async function resolveOwnerGate(adapter2, config2) {
         enforced: true,
         callerIsOwner: isProjectOwner(callerUserId, identity.ownerUserId),
         callerUserId,
-        ownerUserId: identity.ownerUserId
+        ownerUserId: identity.ownerUserId,
+        transport: "proxy"
       };
     } catch (err) {
       return {
@@ -10778,7 +10814,8 @@ async function resolveOwnerGate(adapter2, config2) {
         callerIsOwner: false,
         callerUserId: config2.userId ?? null,
         ownerUserId: null,
-        resolutionError: err instanceof Error ? err.message : String(err)
+        resolutionError: err instanceof Error ? err.message : String(err),
+        transport: "proxy"
       };
     }
   }
@@ -10796,14 +10833,16 @@ async function resolveOwnerGate(adapter2, config2) {
       callerIsOwner: isProjectOwner(callerUserId, ownerUserId),
       callerUserId,
       ownerUserId,
-      ...resolutionError !== void 0 ? { resolutionError } : {}
+      ...resolutionError !== void 0 ? { resolutionError } : {},
+      transport: "pg"
     };
   }
   return {
     enforced: false,
     callerIsOwner: true,
     callerUserId: config2.userId ?? null,
-    ownerUserId: null
+    ownerUserId: null,
+    transport: "md"
   };
 }
 
@@ -12515,6 +12554,13 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
     contextHashes
   };
 }
+var PLAN_STAGE_STEPS = ["health-check", "inbox-triage", "board-integrity", "maturity-gate", "recommendation", "dependency-chain"];
+async function streamPlanStageSteps(tracker, newCycleNumber) {
+  tracker.setStreamScope({ cycle: newCycleNumber });
+  for (const step of PLAN_STAGE_STEPS) {
+    await tracker.recordStep(step);
+  }
+}
 async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, strategyReviewWarning, contextHashes, planRunMeta, tracker) {
   const applyTimer = startTimer();
   console.error(`[plan-perf] applyPlan: start (llm_response=${rawLlmOutput.length} chars)`);
@@ -12527,6 +12573,7 @@ async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, str
     if (config2.adapterType === "pg") {
       tracker?.mark("process_llm_output_pg");
       const result = await processLlmOutput(adapter2, config2, rawLlmOutput, mode, cycleNumber, contextHashes, planRunMeta);
+      if (tracker) await streamPlanStageSteps(tracker, cycleNumber + 1);
       const applyMs2 = applyTimer();
       console.error(`[plan-perf] applyPlan: total=${applyMs2}ms (pg, no git sync)`);
       return { ...result, pullNote: "", strategyReviewWarning };
@@ -13253,10 +13300,6 @@ async function handlePlan(adapter2, config2, args) {
       }
       const skipHandoffs = args.skip_handoffs === true;
       const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker);
-      tracker.setStreamScope({ cycle: result.cycleNumber + 1 });
-      for (const step of ["health-check", "inbox-triage", "board-integrity", "maturity-gate", "recommendation", "dependency-chain"]) {
-        await tracker.recordStep(step);
-      }
       planPrepareCache.set(callerKey, {
         contextHashes: result.contextHashes,
         userMessage: result.userMessage,
@@ -18835,7 +18878,8 @@ To override, pass force=true (emits a telemetry warning).`
       if (adapter2.getBuildReportsSince) {
         try {
           const cycleReports = (await adapter2.getBuildReportsSince(currentCycle)).filter((r) => r.cycle === currentCycle);
-          [snapshot] = computeSnapshotsFromBuildReports(cycleReports);
+          const cycleTasks = (await adapter2.queryBoard({ cycleSince: currentCycle, compact: true })).filter((t) => t.cycle === currentCycle);
+          [snapshot] = computeSnapshotsFromBuildReports(cycleReports, cycleTasks);
         } catch (err) {
           console.error(
             `[release] cycle-metrics snapshot compute failed for cycle ${currentCycle} (non-blocking): ${err instanceof Error ? err.message : String(err)}`
@@ -19374,10 +19418,22 @@ async function handleRelease(adapter2, config2, args) {
         const resolutionNote = gate.resolutionError ? `
 
 Identity resolution failed (${gate.resolutionError}) \u2014 the gate fails closed. Retry once connectivity is restored.` : "";
+        if (gate.transport === "pg" && gate.callerUserId === null) {
+          return errorResponse(
+            `Release needs to know who you are, and this setup has no PAPI_USER_ID yet.
+
+Add it to the papi server's env block in .mcp.json \u2014 the value is your account UUID (getpapi.ai \u2192 Settings \u2192 Account):
+
+  "env": { "PAPI_USER_ID": "<your-account-uuid>", ... }
+
+Then reconnect your AI tool and run release again. (Direct/pg setups read identity from this variable; hosted setups resolve it from the API key automatically.)`
+          );
+        }
         tracker.mark("contributor-role-gate");
         const callerRole = adapter2.getContributorRole && gate.callerUserId ? await adapter2.getContributorRole(gate.callerUserId).catch(() => null) : null;
         if (callerRole !== "editor") {
-          const roleNote = callerRole === "viewer" ? `Your role on this project is "viewer", which cannot release. Ask the owner (or an editor) to release, or ask for editor access.` : `Your identity does not match this project's owner, and you do not have an editor role to open a release PR. If you are a contributor, ask the owner for editor access (or push your branch and open a PR manually). If you ARE the owner on a local (pg) setup, set PAPI_USER_ID to your account UUID in .mcp.json; on the hosted/proxy setup your identity comes from your API key \u2014 check you are using YOUR key for YOUR project.`;
+          const ownerHint = gate.transport === "pg" ? `If you ARE the owner, set PAPI_USER_ID to your account UUID in .mcp.json (getpapi.ai \u2192 Settings \u2192 Account).` : `If you ARE the owner, your identity comes from your API key \u2014 check you are using YOUR key for YOUR project.`;
+          const roleNote = callerRole === "viewer" ? `Your role on this project is "viewer", which cannot release. Ask the owner (or an editor) to release, or ask for editor access.` : `Your identity does not match this project's owner, and you do not have an editor role to open a release PR. If you are a contributor, ask the owner for editor access (or push your branch and open a PR manually). ` + ownerHint;
           return errorResponse(
             `Release to ${productionBaseBranch} is restricted to the project owner.
 
@@ -19754,7 +19810,10 @@ function triggerSurfaceHitsOnBranch(projectRoot, baseRef = "origin/main") {
 function selectAutostashPaths(modified, untracked) {
   const untrackedSet = new Set(untracked);
   const isDocsPath = (p) => p === "docs" || p.startsWith("docs/");
-  const trackedDirty = modified.filter((p) => !untrackedSet.has(p));
+  const isUntrackedDirEntry = (p) => p.endsWith("/") && untracked.some((u) => u.startsWith(p));
+  const trackedDirty = modified.filter(
+    (p) => !untrackedSet.has(p) && !isUntrackedDirEntry(p)
+  );
   const preservedDocs = untracked.filter(isDocsPath);
   const stashableUntracked = untracked.filter((p) => !isDocsPath(p));
   return { toStash: [...trackedDirty, ...stashableUntracked], preservedDocs };
@@ -20071,6 +20130,20 @@ async function describeTask(adapter2, taskId) {
   }
   return { task };
 }
+function shouldBlockDirtyBranchSwitch(opts) {
+  return opts.trackedDirtyCount > 0 && opts.currentBranch !== opts.baseBranch && opts.currentBranch !== opts.featureBranch;
+}
+async function persistBranchName(adapter2, taskId, branch) {
+  try {
+    await adapter2.updateTask(taskId, { branchName: branch });
+    return true;
+  } catch (err) {
+    console.error(
+      `[build] branch_name persist skipped for ${taskId} (non-fatal): ` + (err instanceof Error ? err.message : String(err))
+    );
+    return false;
+  }
+}
 async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   const task = await adapter2.getTask(taskId);
   if (!task) {
@@ -20192,11 +20265,11 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
         branchLines.push(`Base branch '${config2.baseBranch}' not found \u2014 using '${baseBranch}'.`);
       }
       const trackedDirty = getTrackedModifiedFiles(config2.projectRoot);
-      if (trackedDirty.length > 0 && currentBranch !== baseBranch) {
+      if (shouldBlockDirtyBranchSwitch({ trackedDirtyCount: trackedDirty.length, currentBranch, baseBranch, featureBranch })) {
         const shown = trackedDirty.slice(0, 5).join(", ");
         const more = trackedDirty.length > 5 ? ` (+${trackedDirty.length - 5} more)` : "";
         throw new Error(
-          `build_execute won't switch branches: the working tree has uncommitted changes on '${currentBranch}' (this task targets '${featureBranch}'). Another session may be working there, and switching would revert those files. Commit or stash them first, or run build_execute from '${baseBranch}'. Dirty: ${shown}${more}.`
+          `build_execute won't switch branches: the working tree has uncommitted changes on '${currentBranch}' (this task targets '${featureBranch}'). Another session may be working there, and switching would revert those files. Commit or stash them first, run build_execute from '${baseBranch}', or check out '${featureBranch}' if this is your own in-progress work. Dirty: ${shown}${more}.`
         );
       }
       if (hasUncommittedChanges(config2.projectRoot, AUTO_WRITTEN_PATHS)) {
@@ -20287,6 +20360,10 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   if (task.status !== "In Progress") {
     await adapter2.updateTaskStatus(taskId, "In Progress");
   }
+  const startedBranch = taskBranchMap.get(taskId);
+  if (startedBranch) {
+    await persistBranchName(adapter2, taskId, startedBranch);
+  }
   buildStartTimes.set(taskId, (/* @__PURE__ */ new Date()).toISOString());
   if (isGitAvailable() && isGitRepo(config2.projectRoot)) {
     const startSha = getHeadCommitSha(config2.projectRoot);
@@ -20369,7 +20446,8 @@ function extractDocMeta(absolutePath, relativePath, cycleNumber) {
   }
   return { title, type, cycle, summary, tags: [] };
 }
-function assertDeployVerification(config2, input) {
+function assertDeployVerification(config2, input, opts = { deployingNow: true }) {
+  if (!opts.deployingNow) return;
   if (config2.adapterType !== "pg" && config2.adapterType !== "proxy") return;
   let triggerHits = [];
   try {
@@ -20378,6 +20456,8 @@ function assertDeployVerification(config2, input) {
     return;
   }
   if (triggerHits.length === 0) return;
+  const mergeDeployHits = triggerHits.filter((p) => !isDeployAtReleaseSurface(p));
+  if (mergeDeployHits.length === 0) return;
   const verification = input.productionVerification;
   if (!verification) {
     const targetLine = config2.verifyCommand ? `
@@ -20391,25 +20471,28 @@ Run a curl against the live deploy and pass production_verification on build_exe
   { urls, curl_command, http_status, response_excerpt, verified_at }
 `;
     throw new Error(
-      `Deploy-verification required: this branch's diff touches ${triggerHits.length} trigger-surface file(s):
-` + triggerHits.map((p) => `  - ${p}`).join("\n") + targetLine + `
-Trigger surface is enforced because changes here have historically shipped to prod undetected (C166, C264-C265, C271).`
+      `Deploy-verification required: this branch's diff touches ${mergeDeployHits.length} deploy-on-merge trigger-surface file(s):
+` + mergeDeployHits.map((p) => `  - ${p}`).join("\n") + targetLine + `
+Trigger surface is enforced because changes here have historically shipped to prod undetected (C166, C264-C265, C271). Edge/data-proxy diffs (supabase/functions/**) are verified at release instead.`
     );
   }
   if (verification.http_status < 200 || verification.http_status >= 300) {
     throw new Error(
       `Deploy-verification failed: production_verification reports http_status=${verification.http_status} on a trigger-surface task.
-Trigger files touched: ${triggerHits.join(", ")}
+Trigger files touched: ${mergeDeployHits.join(", ")}
 Fix the deploy first, then re-run build_execute complete with a 2xx verification.`
     );
   }
 }
+function isDeployAtReleaseSurface(path7) {
+  return path7.startsWith("supabase/functions/");
+}
 async function completeBuild(adapter2, config2, taskId, input, options = {}, clientName) {
   const task = await adapter2.getTask(taskId);
   if (!task) {
     throw new Error(`Task "${taskId}" not found on the Cycle Board.`);
   }
-  assertDeployVerification(config2, input);
+  assertDeployVerification(config2, input, { deployingNow: options.light === true });
   const [healthResult, priorCount] = await Promise.all([
     adapter2.getCycleHealth().catch(() => ({ totalCycles: 0 })),
     typeof adapter2.getBuildReportCountForTask === "function" ? adapter2.getBuildReportCountForTask(taskId).catch(() => 0) : Promise.resolve(0)
@@ -21389,7 +21472,7 @@ var buildExecuteTool = {
       },
       dead_ends: {
         type: "string",
-        description: `Approaches tried and rejected during the build, with WHY they failed. Example: "Tried using Supabase realtime subscriptions but Edge Functions can't hold persistent connections \u2014 switched to polling." Include whenever you abandoned an approach. Future builds and plans reference this to avoid repeating blind alleys.`
+        description: `CONTRACT: send this on every complete. List approaches you tried and RULED OUT during this build, with why each failed. Example: "Tried Supabase realtime but Edge Functions can't hold persistent connections \u2014 switched to polling." Send "None" ONLY if you genuinely tried nothing that failed. Ruled-out paths are first-class intelligence \u2014 future builds and plans read them to avoid repeating blind alleys.`
       },
       brief_implications: {
         type: "array",
@@ -21634,7 +21717,8 @@ async function handleBuildExecute(adapter2, config2, args, clientName) {
 **PRE-BUILD VERIFICATION:** Before writing any code, read these files and check if the functionality already exists:
 ${verificationFiles.map((f) => `- ${f}`).join("\n")}
 If >80% of the scope is already implemented, call \`build_execute\` with completed="yes" and note "already built" in surprises instead of re-implementing.` : "";
-    const chainInstruction = '\n\n---\n\n**IMPORTANT:** After implementing this task, immediately call `build_execute` again with report fields (`completed`, `effort`, `estimated_effort`, `surprises`, `discovered_issues`, `architecture_notes`) to complete the build. Do not wait for user confirmation.\n\n**Build Report Quality Bar:**\n- **surprises**: What was DIFFERENT from expected \u2014 wrong assumptions, scope changes, missing infrastructure. NOT implementation mechanics ("used X library").\n- **discovered_issues**: Bugs/gaps OUTSIDE this task\'s scope, with severity (P0-P3). NOT "had to install a dependency".\n- **architecture_notes**: Patterns/decisions that AFFECT FUTURE WORK. NOT "used React hooks".\n- If nothing meaningful to report for a field, use "None" \u2014 empty signal is better than noise.';
+    const chainInstruction = '\n\n---\n\n**IMPORTANT:** After implementing this task, immediately call `build_execute` again with report fields (`completed`, `effort`, `estimated_effort`, `surprises`, `discovered_issues`, `architecture_notes`) to complete the build. Do not wait for user confirmation.\n\n**Build Report Quality Bar:**\n- **surprises**: What was DIFFERENT from expected \u2014 wrong assumptions, scope changes, missing infrastructure. NOT implementation mechanics ("used X library").\n- **discovered_issues**: Bugs/gaps OUTSIDE this task\'s scope, with severity (P0-P3). NOT "had to install a dependency".\n- **architecture_notes**: Patterns/decisions that AFFECT FUTURE WORK. NOT "used React hooks".\n- If nothing meaningful to report for a field, use "None" \u2014 empty signal is better than noise.\n- **dead_ends**: approaches you tried and RULED OUT (with why). Ruled-out paths are first-class intelligence \u2014 send "None" only if nothing you tried failed.';
+    const buildDisciplineNote = "\n\n---\n\n**BUILD DISCIPLINE:**\n- **Read before you claim.** Before asserting how something works \u2014 or that it is already done \u2014 read the actual code/state. Don't rely on memory or earlier context.\n- **Sweep existing material first.** Check the docs (`doc_search` or your docs index) and prior tasks, not just whether a file exists \u2014 the work may already be covered.\n- **Ranged reads.** For large or unfamiliar files, read the relevant range rather than the whole file.";
     let adSection = "";
     try {
       const allADs = await adapter2.getActiveDecisions();
@@ -21669,7 +21753,7 @@ ${entries}`;
       formatModelRecommendation(result.task.buildHandoff?.effort ?? result.task.complexity)
     ) ?? "";
     const gestaltNote = buildGestaltPreBuildDirective(caps) ?? "";
-    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + modelNote + gestaltNote + adSection + moduleInstructions + moduleContext + dogfoodSection + verificationNote + chainInstruction + phaseNote + filesToWriteSection);
+    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + modelNote + gestaltNote + adSection + moduleInstructions + moduleContext + dogfoodSection + verificationNote + buildDisciplineNote + chainInstruction + phaseNote + filesToWriteSection);
   } catch (err) {
     if (isNoHandoffError(err)) {
       const lines = [
@@ -21787,9 +21871,11 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
     tracker.mark("complete_format");
     tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.cycleNumber });
     await tracker.recordStep("report_written");
-    await tracker.recordStep("issues_triaged", {
-      metadata: { autoTriagedCount: result.autoTriagedCount ?? 0 }
-    });
+    if ((result.autoTriagedCount ?? 0) > 0) {
+      await tracker.recordStep("issues_triaged", {
+        metadata: { autoTriagedCount: result.autoTriagedCount }
+      });
+    }
     if (resolvesLearnings && resolvesLearnings.length > 0 && adapter2.updateCycleLearningActionRef) {
       for (const learningId of resolvesLearnings) {
         try {
@@ -21798,9 +21884,11 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
         }
       }
     }
-    await tracker.recordStep("learnings", {
-      metadata: { learningsLinkedCount: result.learningsLinkedCount ?? 0 }
-    });
+    if ((result.learningsLinkedCount ?? 0) > 0) {
+      await tracker.recordStep("learnings", {
+        metadata: { learningsLinkedCount: result.learningsLinkedCount }
+      });
+    }
     await tracker.recordStep("moving-to-review", {
       metadata: { status: result.task.status }
     });
@@ -22195,7 +22283,7 @@ function collectDiagnostics(config2) {
 }
 var bugTool = {
   name: "bug",
-  description: 'Report a bug OR submit an idea. Routing: a bug about PAPI itself (a PAPI tool/MCP error, the connector, a handoff/cycle problem) auto-submits UPSTREAM to PAPI maintainers with diagnostics \u2014 you do NOT need to set report=true for these. A bug in the user\'s OWN project auto-files as a Backlog task on their board. 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.',
+  description: `Report a bug OR submit an idea. Routing: a bug about PAPI itself (a PAPI tool/MCP error, the connector, a handoff/cycle problem) auto-submits UPSTREAM to PAPI maintainers with diagnostics \u2014 you do NOT need to set report=true for these. A bug in the user's OWN project auto-files as a Backlog task on their board. IMPORTANT: report=true is ONLY for a genuine PAPI-product defect \u2014 it is NOT the catch-all for "not about my app". A bug in the user's harness/editor/OS/git/other tooling (e.g. Claude Code, Codex, VS Code, a shell command) is NOT a PAPI bug: file it on the user's own board (report=false / default) or that tool's own tracker, never upstream. Override the routing explicitly: report=true forces upstream (PAPI-product only), report=false forces the user's own board. Set \`type\` ("bug"/"idea") and optional notify-when-fixed / contact-ok consent for upstream submissions. Does not call the Anthropic API.`,
   annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
@@ -22227,7 +22315,7 @@ var bugTool = {
       },
       report: {
         type: "boolean",
-        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)."
+        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 ONLY for a genuine PAPI-product defect (PAPI tool/MCP/connector/handoff) \u2014 a bug in the user's harness/editor/OS/other tooling is NOT a PAPI bug and must go to their own board (report=false or default), not upstream. 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, harness, or environment)."
       },
       type: {
         type: "string",
@@ -22244,7 +22332,7 @@ var bugTool = {
       },
       project: {
         type: "string",
-        description: "Project id (UUID) or slug to file this bug under, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default."
+        description: "BOARD MODE ONLY. Project id (UUID) or slug to file this bug under, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. It CANNOT redirect an upstream (report=true) submission \u2014 those always go to PAPI maintainers. Use project_switch to change the session default."
       }
     },
     required: ["text"]
@@ -24499,7 +24587,12 @@ ${writeNote}
     const envVars = {
       PAPI_PROJECT_DIR: projectRoot,
       PAPI_ADAPTER: "pg",
-      DATABASE_URL: process.env.DATABASE_URL || "<YOUR_DATABASE_URL>"
+      DATABASE_URL: process.env.DATABASE_URL || "<YOUR_DATABASE_URL>",
+      // task-2508: pg/direct setups resolve caller identity from this var (the
+      // hosted path uses the bearer token instead). Without it the FIRST
+      // release hits the owner-gate with a null caller — ship it in the
+      // template so fresh pg projects are owner-resolvable out of the box.
+      PAPI_USER_ID: process.env.PAPI_USER_ID || "<YOUR_ACCOUNT_UUID>"
     };
     if (rootHash) {
       envVars.PAPI_RESOLUTION_METHOD = "root_hash";
@@ -24528,7 +24621,8 @@ ${writeNote}
       "## Next Steps",
       "",
       ...process.env.DATABASE_URL ? ["1. **Restart your MCP client** to pick up the new config."] : [`1. **Set your DATABASE_URL** \u2014 replace \`<YOUR_DATABASE_URL>\` in \`${target.displayPath}\` with your Supabase **session pooler** connection string (port **5432**, not 6543 \u2014 the transaction pooler wedges on interrupted calls).`],
-      "2. **Run `setup`** \u2014 this scaffolds your project with a Product Brief, Active Decisions, and CLAUDE.md."
+      ...process.env.PAPI_USER_ID ? [] : ["2. **Set your PAPI_USER_ID** \u2014 replace `<YOUR_ACCOUNT_UUID>` with your account UUID (getpapi.ai \u2192 Settings \u2192 Account). Release and reviews use it to recognise you as the owner."],
+      `${process.env.PAPI_USER_ID ? "2" : "3"}. **Run \`setup\`** \u2014 this scaffolds your project with a Product Brief, Active Decisions, and CLAUDE.md.`
     ].join("\n");
     return textResponse(output2 + formatFilesToWriteSection(collector));
   }
@@ -24698,7 +24792,12 @@ async function getHealthSummary(adapter2) {
   try {
     try {
       buildReports = await adapter2.getRecentBuildReports(50);
-      snapshots = computeSnapshotsFromBuildReports(buildReports);
+      let metricsTasks = [];
+      try {
+        metricsTasks = await adapter2.queryBoard({ cycleSince: Math.max(1, cycleNumber - 6), compact: true });
+      } catch {
+      }
+      snapshots = computeSnapshotsFromBuildReports(buildReports, metricsTasks);
     } catch {
     }
     metricsSection = formatCycleMetrics(snapshots);
@@ -26039,7 +26138,7 @@ ${versionDrift}` : "";
     let enrichmentNote = "";
     const enrichmentCollector = new FileWriteCollector();
     try {
-      enrichmentNote = enrichClaudeMd(config2.projectRoot, healthResult.cycleNumber, config2.adapterType, enrichmentCollector);
+      enrichmentNote = enrichClaudeMd(config2.projectRoot, healthResult.cycleNumber, config2.adapterType, enrichmentCollector, clientName);
     } catch {
     }
     const enrichmentFilesSection = enrichmentCollector.isEmpty() ? "" : formatFilesToWriteSection(enrichmentCollector);
@@ -26100,7 +26199,8 @@ ${section}`;
     }));
   }
 }
-function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector) {
+function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, clientName) {
+  if (!shouldWriteClaudeMd(clientName)) return "";
   if (adapterType === "proxy") {
     const additions2 = [];
     if (cycleNumber >= 6) additions2.push(CLAUDE_MD_TIER_1);

package/dist/prompts.js

@@ -66,7 +66,7 @@ REFERENCE DOCS
 [Optional \u2014 paths to docs/ files that provide background context for this task. Include only when the task originated from research or scoping work and the doc contains context the builder will need beyond what is in this handoff. Omit this section entirely for tasks that don't need supplementary context.]
 
 PRE-BUILD VERIFICATION
-[List 2-5 specific file paths the builder should read BEFORE implementing to check if the functionality already exists. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. If >80% of the scope is already implemented, the builder should report "already built" instead of re-implementing. Include this section for EVERY task \u2014 it prevents wasted build slots on already-shipped code.]
+[List 2-5 specific file paths the builder should read BEFORE implementing to check if the functionality already exists. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. ALSO mandate a docs sweep, not just file-existence (task-2161): name any docs the builder should check via doc_search or the docs index \u2014 a design/research/status:final doc or a prior task may already cover the work. If >80% of the scope is already implemented, the builder should report "already built" instead of re-implementing. Include this section for EVERY task \u2014 it prevents wasted build slots on already-shipped code.]
 
 FILES LIKELY TOUCHED
 [files]
@@ -661,7 +661,7 @@ function buildHandoffsOnlyUserMessage(inputs) {
 }
 function extractDependencyChain(displayText) {
   const match = displayText.match(
-    /^##\s+Dependency Chain[^\n]*\n([\s\S]*?)(?=\n#{2,3}\s|$(?![\s\S]))/m
+    /^##\s+Dependency Chain[^\n]*\n([\s\S]*?)(?=\n#{2,3}\s|\n-{3,}\s*(?:\n|$)|\n\s*BUILD HANDOFF\b|\n<!--\s*PAPI_STRUCTURED_OUTPUT|$(?![\s\S]))/m
   );
   if (!match) return void 0;
   const body = match[1].trim();

package/package.json

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