@papi-ai/server 0.7.73 → 0.7.75

package/dist/backfill-cycle-metrics.js

@@ -14,6 +14,7 @@ __export(git_exports, {
   AUTO_WRITTEN_PATHS: () => AUTO_WRITTEN_PATHS,
   branchExists: () => branchExists,
   checkoutBranch: () => checkoutBranch,
+  commitSinglePath: () => commitSinglePath,
   commitStagedOnly: () => commitStagedOnly,
   createAndCheckoutBranch: () => createAndCheckoutBranch,
   createPullRequest: () => createPullRequest,
@@ -59,6 +60,8 @@ __export(git_exports, {
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
   isGitRepo: () => isGitRepo,
+  isPathIgnored: () => isPathIgnored,
+  isPathTracked: () => isPathTracked,
   listGroupedCycleBranches: () => listGroupedCycleBranches,
   listOpenPullRequests: () => listOpenPullRequests,
   listOrphanFeatBranches: () => listOrphanFeatBranches,
@@ -96,6 +99,42 @@ function isGitRepo(cwd) {
     return false;
   }
 }
+function isPathTracked(cwd, path3) {
+  try {
+    execFileSync("git", ["ls-files", "--error-unmatch", "--", path3], {
+      cwd,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isPathIgnored(cwd, path3) {
+  const r = spawnSync("git", ["check-ignore", "-q", "--", path3], { cwd, stdio: "ignore" });
+  return r.status === 0;
+}
+function commitSinglePath(cwd, path3, message) {
+  const add = spawnSync("git", ["add", "--", path3], { cwd, encoding: "utf-8" });
+  if (add.status !== 0) {
+    return { committed: false, message: (add.stderr || "git add failed").trim() };
+  }
+  const pending = spawnSync("git", ["diff", "--cached", "--name-only", "--", path3], {
+    cwd,
+    encoding: "utf-8"
+  });
+  if (pending.status !== 0 || !(pending.stdout ?? "").trim()) {
+    return { committed: false, message: "No changes to commit." };
+  }
+  const commit = spawnSync("git", ["commit", "-m", message, "--", path3], {
+    cwd,
+    encoding: "utf-8"
+  });
+  if (commit.status !== 0) {
+    return { committed: false, message: (commit.stderr || "git commit failed").trim() };
+  }
+  return { committed: true, message };
+}
 function stageDirAndCommit(cwd, dir, message) {
   try {
     execFileSync("git", ["check-ignore", "-q", dir], { cwd });

package/dist/index.js

@@ -15,6 +15,7 @@ __export(git_exports, {
   AUTO_WRITTEN_PATHS: () => AUTO_WRITTEN_PATHS,
   branchExists: () => branchExists,
   checkoutBranch: () => checkoutBranch,
+  commitSinglePath: () => commitSinglePath,
   commitStagedOnly: () => commitStagedOnly,
   createAndCheckoutBranch: () => createAndCheckoutBranch,
   createPullRequest: () => createPullRequest,
@@ -60,6 +61,8 @@ __export(git_exports, {
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
   isGitRepo: () => isGitRepo,
+  isPathIgnored: () => isPathIgnored,
+  isPathTracked: () => isPathTracked,
   listGroupedCycleBranches: () => listGroupedCycleBranches,
   listOpenPullRequests: () => listOpenPullRequests,
   listOrphanFeatBranches: () => listOrphanFeatBranches,
@@ -97,6 +100,42 @@ function isGitRepo(cwd) {
     return false;
   }
 }
+function isPathTracked(cwd, path7) {
+  try {
+    execFileSync("git", ["ls-files", "--error-unmatch", "--", path7], {
+      cwd,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isPathIgnored(cwd, path7) {
+  const r = spawnSync("git", ["check-ignore", "-q", "--", path7], { cwd, stdio: "ignore" });
+  return r.status === 0;
+}
+function commitSinglePath(cwd, path7, message) {
+  const add = spawnSync("git", ["add", "--", path7], { cwd, encoding: "utf-8" });
+  if (add.status !== 0) {
+    return { committed: false, message: (add.stderr || "git add failed").trim() };
+  }
+  const pending = spawnSync("git", ["diff", "--cached", "--name-only", "--", path7], {
+    cwd,
+    encoding: "utf-8"
+  });
+  if (pending.status !== 0 || !(pending.stdout ?? "").trim()) {
+    return { committed: false, message: "No changes to commit." };
+  }
+  const commit = spawnSync("git", ["commit", "-m", message, "--", path7], {
+    cwd,
+    encoding: "utf-8"
+  });
+  if (commit.status !== 0) {
+    return { committed: false, message: (commit.stderr || "git commit failed").trim() };
+  }
+  return { committed: true, message };
+}
 function stageDirAndCommit(cwd, dir, message) {
   try {
     execFileSync("git", ["check-ignore", "-q", dir], { cwd });
@@ -5002,7 +5041,7 @@ var setup_exports = {};
 __export(setup_exports, {
   runSetup: () => runSetup
 });
-import { existsSync as existsSync15, readFileSync as readFileSync17, writeFileSync as writeFileSync8, chmodSync as chmodSync2, statSync as statSync8 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync17, writeFileSync as writeFileSync8, chmodSync as chmodSync2, statSync as statSync9 } from "fs";
 import { join as join24 } from "path";
 function baseUrl() {
   const fromEnv = process.env["PAPI_HOST"] ?? process.env["PAPI_BASE_URL"];
@@ -5062,7 +5101,7 @@ function writeMcpJson(opts) {
   parsed.mcpServers = mcpServers;
   writeFileSync8(path7, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
   try {
-    const mode = statSync8(path7).mode & 511;
+    const mode = statSync9(path7).mode & 511;
     if (mode !== 384) chmodSync2(path7, 384);
   } catch {
   }
@@ -5172,7 +5211,7 @@ var init_setup = __esm({
 // src/index.ts
 import { readFileSync as readFileSync18 } from "fs";
 import { dirname as dirname6, join as join25, basename as basename2 } from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import { fileURLToPath as fileURLToPath5 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { Server as Server2 } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -8218,7 +8257,7 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
 import { readFileSync as readFileSync13 } from "fs";
 import { access as access4, readdir as readdir4, readFile as readFile9 } from "fs/promises";
 import { join as join20, dirname as dirname5 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { fileURLToPath as fileURLToPath4 } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
@@ -8245,6 +8284,8 @@ var UNIVERSAL_FRAME = `PAPI gives this project a structured plan \u2192 build \u
 
 5. VERIFY BEFORE DONE. Test the change and confirm it works before reporting a task complete. Report failures honestly, with the output.
 
+6. NAME THE PROJECT WHEN YOU KNOW IT. If you know which repo this session is working in, pass \`project="<slug>"\` on the call rather than relying on whatever the connection defaults to. An account with more than one project cannot be resolved from a connection with no project bound \u2014 PAPI will stop and ask which one rather than guess, and answering costs a round trip. If PAPI asks, put the list to the user, then re-call with their choice; run \`project_switch\` to make it stick.
+
 PAPI reads and writes all project state through these tools \u2014 they are the source of truth, not local files.`;
 
 // src/lib/response.ts
@@ -8995,7 +9036,7 @@ 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. 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 \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist.]
+[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist. MCP RESTART RULE (task-2978): whenever FILES LIKELY TOUCHED includes any \`packages/server/**\` path, append this line verbatim to the handoff \u2014 "MCP RESTART REQUIRED: a mid-session \`npm run mcp-build\` writes a dist the already-booted MCP process never loads, so verifying this change through PAPI's own tools before an explicit MCP reconnect is INVALID. Implement \u2192 mcp-build \u2192 reconnect \u2192 only then verify." This is one line inside this section, not a new section.]
 
 EFFORT
 [XS/S/M/L/XL]
@@ -9009,7 +9050,7 @@ After your natural language output, include this EXACT format on its own line:
 {
   "cycleLogTitle": "string \u2014 short descriptive title WITHOUT 'Cycle N' prefix. Should capture the cycle theme in 3-5 words (e.g. 'MCP Quality + Product Readiness' not 'Cycle 5 \u2014 Board Triage \u2014 Bug Fix'). This is the canonical theme label for the cycle.",
   "cycleLogContent": "string \u2014 5-10 line cycle log body in markdown, NO heading (the ### heading is generated automatically)",
-  "cycleLogCarryForward": "string or null \u2014 carry-forward items for next cycle",
+  "cycleLogCarryForward": "string or null \u2014 carry-forward for the next cycle, in TWO NAMED SECTIONS, product signal FIRST. Section 1 begins with the literal label 'WHAT SHIPS FOR USERS:' and names, concretely, what a person using this project can now see or do, and how to check it \u2014 never a deploy step. Section 2 begins with the literal label 'RELEASE MECHANICS:' and carries everything operational: deploy, publish, migrations, gate order, branch counts, spot-checks. The mechanics are load-bearing and must NOT be dropped or shortened \u2014 they go second, not away. orient parses these two labels and renders the product half first, so the labels are a contract, not decoration. If a cycle genuinely ships nothing user-visible, say so in one line under section 1 rather than omitting the label.",
   "cycleLogNotes": "string or null \u2014 1-3 lines of cycle-level observations: estimation accuracy, recurring blockers, velocity trends, dependency signals. Omit if no noteworthy observations.",
   "nextMode": "Full",
   "boardHealth": "string \u2014 e.g. 5 tasks (3 backlog, 2 done)",
@@ -9873,7 +9914,7 @@ After your natural language output, include this EXACT format on its own line:
 \`\`\`json
 {
   "sessionLogTitle": "string \u2014 Strategy Review title WITHOUT 'Cycle N' prefix (e.g. 'Strategy Review' not 'Cycle 5 \u2014 Strategy Review')",
-  "sessionLogContent": "string \u2014 5-10 line cycle log body summarizing the review, NO heading (the ### heading is generated automatically)",
+  "sessionLogContent": "string \u2014 5-10 line cycle log body summarizing the review, NO heading (the ### heading is generated automatically). LEAD WITH TANGIBLE PRODUCT INSIGHT: open with what was learned about the product, its users, or the market \u2014 a specific finding a reader can act on. Board hygiene, cadence, cycle counts, branch state and other housekeeping are legitimate content but they TRAIL; they must never be the opening line. If the review's most important finding genuinely is an operational one, say why it matters to the product in the same breath rather than reporting it as admin.",
   "velocityAssessment": "string \u2014 2-3 sentence velocity summary",
   "strategicRecommendations": "string \u2014 key recommendations in markdown",
   "activeDecisionUpdates": [
@@ -10237,7 +10278,7 @@ REFERENCE DOCS
 [Optional \u2014 paths to docs/ files with background context. Omit if not needed.]
 
 FILES LIKELY TOUCHED
-[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist.]
+[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist. MCP RESTART RULE (task-2978): whenever FILES LIKELY TOUCHED includes any \`packages/server/**\` path, append this line verbatim to the handoff \u2014 "MCP RESTART REQUIRED: a mid-session \`npm run mcp-build\` writes a dist the already-booted MCP process never loads, so verifying this change through PAPI's own tools before an explicit MCP reconnect is INVALID. Implement \u2192 mcp-build \u2192 reconnect \u2192 only then verify." This is one line inside this section, not a new section.]
 
 EFFORT
 [XS/S/M/L/XL]`;
@@ -10602,9 +10643,9 @@ async function getPrompt(name) {
   if (!endpoint) {
     return LOCAL_PROMPTS[name];
   }
-  const cached = cache.get(name);
-  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
-    return cached.content;
+  const cached2 = cache.get(name);
+  if (cached2 && Date.now() - cached2.fetchedAt < CACHE_TTL_MS) {
+    return cached2.content;
   }
   try {
     const url = endpoint.endsWith("/") ? `${endpoint}${name}` : `${endpoint}/${name}`;
@@ -10617,19 +10658,19 @@ async function getPrompt(name) {
     }
     const response = await fetch(url, { headers, signal: AbortSignal.timeout(1e4) });
     if (!response.ok) {
-      if (cached) return cached.content;
+      if (cached2) return cached2.content;
       return LOCAL_PROMPTS[name];
     }
     const data = await response.json();
     const content = data.content;
     if (typeof content !== "string" || content.length === 0) {
-      if (cached) return cached.content;
+      if (cached2) return cached2.content;
       return LOCAL_PROMPTS[name];
     }
     cache.set(name, { content, fetchedAt: Date.now() });
     return content;
   } catch {
-    if (cached) return cached.content;
+    if (cached2) return cached2.content;
     return LOCAL_PROMPTS[name];
   }
 }
@@ -19797,6 +19838,91 @@ var DB_ONLY_START_NOTICE = "No git repo detected \u2014 running this cycle in yo
 var DB_ONLY_COMPLETE_NOTICE = "No git repo \u2014 build recorded in your project database only (no commit or PR). Run `git init` (and add a remote) to enable git-backed commits and PR review.";
 var DB_ONLY_RELEASE_NOTICE = "No git repo detected \u2014 this release closed the cycle in your project database only. No tag, branch merge, or CHANGELOG was created. Run `git init` (and add a remote) to enable git-backed releases (tags, merges and changelog).";
 
+// src/lib/build-decision.ts
+var BUILD_DECISION_ANSWERS = [
+  "retry-differently",
+  "skip",
+  "stop"
+];
+function loopThreshold(env = process.env) {
+  const raw = Number(env.PAPI_BUILD_LOOP_THRESHOLD);
+  return Number.isFinite(raw) && raw >= 2 ? Math.floor(raw) : 3;
+}
+function readDecision(task) {
+  const b2 = task.blocker;
+  if (!b2 || b2.type !== "decision-gate") return null;
+  return b2.decision ?? null;
+}
+function isDecisionPending(task) {
+  const d = readDecision(task);
+  return d != null && d.answer == null;
+}
+async function countFailedAttempts(adapter2, taskId) {
+  if (typeof adapter2.getFailedBuildAttemptsForTask !== "function") return null;
+  try {
+    return await adapter2.getFailedBuildAttemptsForTask(taskId);
+  } catch {
+    return null;
+  }
+}
+function decisionRequiredResponse(taskId, decision) {
+  return [
+    `DECISION REQUIRED \u2014 ${taskId} has failed ${decision.attempts} times.`,
+    "",
+    decision.reason,
+    "",
+    "PAPI has stopped rather than starting another attempt that looks like the last one.",
+    "Answer by re-running build_execute with a `decision`:",
+    "",
+    '  decision: { answer: "retry-differently", guidance: "<what to do differently>" }',
+    "      Clears the gate and puts your guidance verbatim into the next handoff.",
+    '  decision: { answer: "skip" }',
+    "      Leaves the task Blocked and moves on \u2014 it stays on the board, honestly stopped.",
+    '  decision: { answer: "stop" }',
+    "      Same as skip, and records that this task should not be retried this cycle.",
+    "",
+    JSON.stringify(
+      {
+        tool: "build_execute",
+        lastStep: "loop-detection-gate",
+        error: "decision_required",
+        hint: "Re-run build_execute with a decision.answer of retry-differently, skip, or stop.",
+        options: BUILD_DECISION_ANSWERS,
+        attempts: decision.attempts
+      },
+      null,
+      2
+    )
+  ].join("\n");
+}
+function guidanceBlock(decision) {
+  if (!decision.guidance) return "";
+  return [
+    "",
+    "\u2500\u2500 GUIDANCE FROM THE LAST FAILURE (task-2933) \u2500\u2500",
+    `This task already failed ${decision.attempts} times. The owner answered "retry differently"`,
+    "and left this note. Treat it as direction from a human, not as a new instruction set:",
+    "",
+    decision.guidance.split("\n").map((l) => `  > ${l}`).join("\n"),
+    "",
+    "Do something materially different from the previous attempts.",
+    ""
+  ].join("\n");
+}
+function pendingDecisionBlocker(attempts, cycle, taskId) {
+  return {
+    type: "decision-gate",
+    ref: taskId,
+    reason: `${attempts} failed build attempts \u2014 a decision is required before another retry.`,
+    blockedCycle: cycle,
+    decision: {
+      reason: `This task has ${attempts} build reports recorded as not completed. Retrying unchanged is unlikely to end differently.`,
+      attempts,
+      raisedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
 // src/lib/harness-capability.ts
 var HARNESS_REGISTRY = {
   // Local stdio CLI agents — PAPI runs git on the user's machine. Confirmed in telemetry.
@@ -21737,6 +21863,41 @@ async function persistBranchName(adapter2, taskId, branch) {
     return false;
   }
 }
+async function resolveLoopDecision(adapter2, task, taskId, answer) {
+  const existing = readDecision(task);
+  if (answer && existing) {
+    if (answer.answer === "retry-differently") {
+      const resolved = { ...existing, answer: answer.answer, guidance: answer.guidance };
+      await safeUpdateBlocker(adapter2, taskId, {
+        ...pendingDecisionBlocker(existing.attempts, task.cycle ?? 0, taskId),
+        decision: resolved
+      });
+      return { guidance: guidanceBlock(resolved) };
+    }
+    await safeUpdateBlocker(adapter2, taskId, {
+      ...pendingDecisionBlocker(existing.attempts, task.cycle ?? 0, taskId),
+      decision: { ...existing, answer: answer.answer }
+    });
+    throw new Error(
+      `Task "${taskId}" recorded as "${answer.answer}" after ${existing.attempts} failed attempts. It stays Blocked on the board rather than pretending to be in flight. Re-run build_execute with decision.answer "retry-differently" and guidance when you want it picked back up.`
+    );
+  }
+  if (isDecisionPending(task)) {
+    throw new Error(decisionRequiredResponse(taskId, readDecision(task)));
+  }
+  const attempts = await countFailedAttempts(adapter2, taskId);
+  if (attempts == null) return {};
+  if (attempts < loopThreshold()) return {};
+  const blocker = pendingDecisionBlocker(attempts, task.cycle ?? 0, taskId);
+  await safeUpdateBlocker(adapter2, taskId, blocker);
+  throw new Error(decisionRequiredResponse(taskId, blocker.decision));
+}
+async function safeUpdateBlocker(adapter2, taskId, blocker) {
+  try {
+    await adapter2.updateTask(taskId, { blocker });
+  } catch {
+  }
+}
 async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   const task = await adapter2.getTask(taskId);
   if (!task) {
@@ -21753,6 +21914,8 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   if (task.status === "Done" || task.status === "Archived") {
     throw new Error(`Task "${taskId}" (${task.title}) is already ${task.status}. Cannot execute a completed task.`);
   }
+  const loopDecision = await resolveLoopDecision(adapter2, task, taskId, options.decision);
+  const injectedGuidance = loopDecision.guidance;
   if (task.status === "In Review") {
     throw new Error(
       `Task "${taskId}" (${task.title}) is already In Review \u2014 it has been built and is awaiting sign-off. Run \`review_submit\` instead of re-building. If the build genuinely needs rework, use \`review_submit\` with verdict \`request-changes\` first.`
@@ -22038,7 +22201,10 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   });
   return {
     task,
-    branchLines,
+    // task-2933: a `retry-differently` answer prepends its guidance here, so it
+    // sits ABOVE the BUILD HANDOFF in the start output — the builder reads the
+    // reason the last attempts failed before it reads what to build.
+    branchLines: injectedGuidance ? [injectedGuidance, ...branchLines] : branchLines,
     phaseChanges,
     filesToWrite: collector.isEmpty() ? void 0 : collector
   };
@@ -22673,9 +22839,10 @@ import { join as join13, relative } from "path";
 import { homedir as homedir3 } from "os";
 import { randomUUID as randomUUID12 } from "crypto";
 import { docDeletionBlockMessage } from "@papi-ai/shared";
+init_git();
 var docRegisterTool = {
   name: "doc_register",
-  description: "Register or update a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content. Re-registering an existing doc updates its summary, tags, actions, type, and status (upsert). Visibility and owner are not changed on re-register.",
+  description: "Register or update a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content; the body stays a file, so an untracked doc is committed at registration to make it durable (or you get a loud warning if it cannot be). Re-registering an existing doc updates its summary, tags, actions, type, and status (upsert). Visibility and owner are not changed on re-register.",
   annotations: { title: "Register Doc", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -22776,6 +22943,42 @@ Diagnostic JSON:
 ${JSON.stringify(payload, null, 2)}`
   );
 }
+function ensureDocDurable(path7, projectRoot) {
+  if (!hasLocalWorkspace() || !projectRoot) return "";
+  const warn = (reason, fix) => `
+
+\u26A0\uFE0F **Registered, but NOT durable.** ${reason}
+The registry stores metadata and a summary \u2014 not the body. This doc has one copy, on disk, and a branch switch or stash can take it.
+**Fix:** ${fix}`;
+  if (!existsSync9(join13(projectRoot, path7))) {
+    return warn(
+      `No file exists at \`${path7}\`.`,
+      `write the doc body to that path, then re-run doc_register.`
+    );
+  }
+  if (!isGitAvailable() || !isGitRepo(projectRoot)) {
+    return warn(
+      "This project is not a git repository (or git is unavailable), so the body cannot be committed.",
+      `back the file up outside the working tree, or run \`git init\` and commit \`${path7}\`.`
+    );
+  }
+  if (isPathTracked(projectRoot, path7)) return "";
+  if (isPathIgnored(projectRoot, path7)) {
+    return warn(
+      `\`${path7}\` is excluded by .gitignore, so it cannot be committed (docs/private/ is ignored by design).`,
+      `keep a copy outside the working tree, or move the doc to a tracked folder if it is not owner-only.`
+    );
+  }
+  const result = commitSinglePath(projectRoot, path7, `docs: register ${path7}`);
+  if (!result.committed) {
+    return warn(
+      `Committing \`${path7}\` failed: ${result.message}`,
+      `run \`git add ${path7} && git commit -m "docs: register ${path7}"\` yourself.`
+    );
+  }
+  return `
+- **Durability:** committed \`${path7}\` (was untracked)`;
+}
 async function handleDocRegister(adapter2, args, config2) {
   const adapterType = config2?.adapterType ?? "unknown";
   const continueHint = "doc_register is advisory \u2014 your build/plan/review flow is unaffected. Fix the input (or wait for the registry to recover) and re-run doc_register; or just continue without it.";
@@ -22832,6 +23035,12 @@ async function handleDocRegister(adapter2, args, config2) {
       visibility
     });
     const visibilityLabel = entry.visibility === "contributors" ? "team member" : entry.visibility ?? "private";
+    let durability = "";
+    try {
+      durability = ensureDocDurable(entry.path, config2?.projectRoot);
+    } catch {
+      durability = "";
+    }
     return textResponse(
       `**Registered:** ${entry.title}
 - **Path:** ${entry.path}
@@ -22839,7 +23048,7 @@ async function handleDocRegister(adapter2, args, config2) {
 - **Visibility:** ${visibilityLabel}
 - **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
 - **Actions:** ${actions?.length ?? 0} items
-- **ID:** ${entry.id}`
+- **ID:** ${entry.id}` + durability
     );
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -23206,6 +23415,22 @@ var buildExecuteTool = {
         type: "boolean",
         description: "Light-ceremony mode for XS/S tasks. Skips feature branch creation and PR. Work stays on current branch. Build report is still captured. Default false."
       },
+      decision: {
+        type: "object",
+        description: "task-2933: answer a loop-detection gate. After N failed build attempts (default 3, PAPI_BUILD_LOOP_THRESHOLD) build_execute REFUSES to start and asks for a decision. Re-run with this to answer. Only meaningful on a gated task.",
+        properties: {
+          answer: {
+            type: "string",
+            enum: ["retry-differently", "skip", "stop"],
+            description: '"retry-differently" clears the gate and injects `guidance` verbatim into the next handoff. "skip"/"stop" leave the task Blocked on the board rather than pretending it is in flight.'
+          },
+          guidance: {
+            type: "string",
+            description: 'What to do differently. Required in spirit for "retry-differently" \u2014 it is the whole point of the retry. Rendered to the next builder as quoted human direction.'
+          }
+        },
+        required: ["answer"]
+      },
       completed: {
         type: "string",
         enum: ["yes", "no", "partial"],
@@ -23550,7 +23775,19 @@ async function handleBuildExecute(adapter2, config2, args, clientName) {
       if (existing) resumeNote = formatResumeNote(existing);
     }
     await tracker.recordStep("started");
-    const result = await startBuild(adapter2, config2, taskId, { light }, clientName);
+    const decision = args.decision;
+    const result = await startBuild(
+      adapter2,
+      config2,
+      taskId,
+      {
+        light,
+        // Only pass a decision the schema recognises — an unknown answer must not
+        // reach the resolver and silently clear a gate.
+        decision: decision?.answer && BUILD_DECISION_ANSWERS.includes(decision.answer) ? { answer: decision.answer, guidance: decision.guidance } : void 0
+      },
+      clientName
+    );
     tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.task.cycle ?? null });
     await tracker.recordStep("branch_ready");
     tracker.mark("start_decorate_handoff");
@@ -24048,7 +24285,7 @@ var ideaTool = {
       },
       project: {
         type: "string",
-        description: "Project id (UUID) or slug to write this idea to, 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: "Project id (UUID) or slug to write this idea to, 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. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: ["text"]
@@ -24495,7 +24732,7 @@ var backlogImportTool = {
       },
       project: {
         type: "string",
-        description: "Project id (UUID) or slug to import into, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise."
+        description: "Project id (UUID) or slug to import into, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: ["source"]
@@ -24703,7 +24940,7 @@ var bugTool = {
       },
       project: {
         type: "string",
-        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."
+        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. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: ["text"]
@@ -27606,6 +27843,50 @@ function formatUnblockSection(candidates) {
   return lines.join("\n");
 }
 
+// src/lib/carry-forward-shape.ts
+var PRODUCT_MARKER = /WHAT SHIPS FOR USERS\b[^\n:]*:/i;
+var MECHANICS_MARKER = /RELEASE MECHANICS\b[^\n:]*:/i;
+function splitCarryForward(raw) {
+  const productMatch = PRODUCT_MARKER.exec(raw);
+  const mechanicsMatch = MECHANICS_MARKER.exec(raw);
+  if (!productMatch && !mechanicsMatch) {
+    return { product: raw.trim(), mechanics: "", split: false };
+  }
+  if (!productMatch && mechanicsMatch) {
+    const head = raw.slice(0, mechanicsMatch.index).trim();
+    const tail = raw.slice(mechanicsMatch.index + mechanicsMatch[0].length).trim();
+    return { product: head, mechanics: tail, split: true };
+  }
+  const productStart = productMatch.index + productMatch[0].length;
+  if (!mechanicsMatch) {
+    return { product: raw.slice(productStart).trim(), mechanics: "", split: true };
+  }
+  if (mechanicsMatch.index < productMatch.index) {
+    return {
+      product: raw.slice(productStart).trim(),
+      mechanics: raw.slice(mechanicsMatch.index + mechanicsMatch[0].length, productMatch.index).trim(),
+      split: true
+    };
+  }
+  return {
+    product: raw.slice(productStart, mechanicsMatch.index).trim(),
+    mechanics: raw.slice(mechanicsMatch.index + mechanicsMatch[0].length).trim(),
+    split: true
+  };
+}
+function renderCarryForward(raw, decorate = (t) => t) {
+  const { product, mechanics, split } = splitCarryForward(raw);
+  if (!split) return [decorate(product)];
+  const lines = [];
+  if (product) lines.push(decorate(product));
+  if (mechanics) {
+    if (product) lines.push("");
+    lines.push("**Release mechanics** \u2014 needed at release, not now:");
+    lines.push(decorate(mechanics));
+  }
+  return lines;
+}
+
 // src/lib/deferred-gate.ts
 var GATE_PHRASES = [
   "depends on",
@@ -28146,6 +28427,20 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
     lines.push(`**In Review:** ${health.inReviewSummary}`);
     lines.push("");
   }
+  if (buildInfo.pendingDecisions.length > 0) {
+    const n = buildInfo.pendingDecisions.length;
+    lines.push("## Decision required");
+    lines.push(
+      `${n} task${n === 1 ? " has" : "s have"} stopped after repeated failed builds. PAPI will not retry until you answer.`
+    );
+    for (const d of buildInfo.pendingDecisions) {
+      lines.push(`- **${d.id}:** ${d.title} \u2014 ${d.attempts} failed attempts`);
+    }
+    lines.push(
+      'Answer with `build_execute <task> decision:{answer:"retry-differently", guidance:"\u2026"}` to pick it back up, or `"skip"` / `"stop"` to leave it parked.'
+    );
+    lines.push("");
+  }
   if (buildInfo.isEmpty) {
     lines.push("## Tasks");
     if (buildInfo.currentCycle === 0) {
@@ -28171,7 +28466,7 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
   const hasCarryForward = health.carryForward !== "None found" && !health.carryForward.startsWith("No carry-forward");
   if (hasCarryForward) {
     lines.push("## Carry-Forward");
-    lines.push(annotateTaskRefs(health.carryForward, taskRefs));
+    lines.push(...renderCarryForward(health.carryForward, (t) => annotateTaskRefs(t, taskRefs)));
     lines.push("");
   }
   const hasMetrics = health.metricsSection !== "Could not read methodology metrics." && !health.metricsSection.includes("undefined");
@@ -28414,6 +28709,19 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
       inReview: healthResult.inReviewSummary,
       backlogCount: buildResult.backlog.length,
       blockedCount: buildResult.blocked.length,
+      // task-2933: computed here where the raw tasks are in scope. Best-effort —
+      // a malformed blocker must never break orient.
+      pendingDecisions: allTasks.filter((t) => {
+        try {
+          return isDecisionPending(t);
+        } catch {
+          return false;
+        }
+      }).map((t) => ({
+        id: t.displayId ?? t.id,
+        title: t.title,
+        attempts: readDecision(t)?.attempts ?? 0
+      })),
       totalHandoffs: buildResult.sorted.length + buildResult.blocked.length,
       currentCycle,
       isEmpty: buildResult.isEmpty,
@@ -30113,6 +30421,36 @@ ${d.body}`;
 ${formatted}`, meta));
 }
 
+// src/lib/dist-staleness.ts
+import { statSync as statSync8 } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+var BOOT_MS = Date.now();
+var DEFAULT_SKEW_MS = 2e3;
+var STAT_TTL_MS = 1e4;
+function isDistStale({ bootMs, distMtimeMs, skewMs = DEFAULT_SKEW_MS }) {
+  if (distMtimeMs === null || !Number.isFinite(distMtimeMs)) return false;
+  return distMtimeMs > bootMs + skewMs;
+}
+var cached = null;
+function checkDistStaleness(now = Date.now()) {
+  if (cached && now - cached.at < STAT_TTL_MS) return cached.stale;
+  let distMtimeMs = null;
+  try {
+    distMtimeMs = statSync8(fileURLToPath3(import.meta.url)).mtimeMs;
+  } catch {
+    distMtimeMs = null;
+  }
+  const stale = isDistStale({ bootMs: BOOT_MS, distMtimeMs });
+  cached = { at: now, stale };
+  return stale;
+}
+function stalenessWarning(now = Date.now()) {
+  const age = Math.round((now - BOOT_MS) / 1e3);
+  return `\u26A0\uFE0F This PAPI MCP server process booted ${age}s ago and packages/server has been REBUILT since. It is still running the code it booted with, so anything you verify through these tools right now reflects the OLD bundle. Reconnect / restart the PAPI MCP server before trusting this output.
+
+`;
+}
+
 // src/tools/learning-action.ts
 var learningActionTool = {
   name: "learning_action",
@@ -31084,9 +31422,9 @@ async function checkMeter(adapter2, toolName, cacheKey) {
   if (!adapter2.getMeteredUsage) return { blocked: false };
   try {
     let usage;
-    const cached = usageCache.get(cacheKey);
-    if (cached && Date.now() - cached.at < CACHE_TTL_MS3) {
-      usage = cached.usage;
+    const cached2 = usageCache.get(cacheKey);
+    if (cached2 && Date.now() - cached2.at < CACHE_TTL_MS3) {
+      usage = cached2.usage;
     } else {
       usage = await adapter2.getMeteredUsage();
       usageCache.set(cacheKey, { usage, at: Date.now() });
@@ -31275,7 +31613,7 @@ function getToolMetadata() {
   return PAPI_TOOLS.map((t) => ({ name: t.name, description: t.description }));
 }
 function createServer(adapter2, config2) {
-  const __pkgFilename = fileURLToPath3(import.meta.url);
+  const __pkgFilename = fileURLToPath4(import.meta.url);
   const __pkgDir = dirname5(__pkgFilename);
   let serverVersion = "unknown";
   try {
@@ -31295,7 +31633,7 @@ function createServer(adapter2, config2) {
       "\n\u26A0 PAPI is running in md mode \u2014 your cycles are not visible on the hosted dashboard.\n  Configure DATABASE_URL or sign up at https://getpapi.ai/setup to enable observability.\n\n"
     );
   }
-  const __filename = fileURLToPath3(import.meta.url);
+  const __filename = fileURLToPath4(import.meta.url);
   const __dirname2 = dirname5(__filename);
   const skillsDir = join20(__dirname2, "..", "skills");
   function parseSkillFrontmatter(content) {
@@ -31597,6 +31935,15 @@ ${usageLine(decision.usage)}`;
     }
     const footer = formatMetricsFooter(elapsed, usage, contextBytes);
     result.content.push({ type: "text", text: footer });
+    try {
+      if (checkDistStaleness() && result.content.length > 0) {
+        const first = result.content[0];
+        if (first && typeof first.text === "string") {
+          first.text = stalenessWarning() + first.text;
+        }
+      }
+    } catch {
+    }
     return result;
   });
   return server2;
@@ -32042,7 +32389,7 @@ async function dispatchRequest(args) {
 }
 
 // src/index.ts
-var __dirname = dirname6(fileURLToPath4(import.meta.url));
+var __dirname = dirname6(fileURLToPath5(import.meta.url));
 var pkgVersion = "unknown";
 try {
   const pkg = JSON.parse(readFileSync18(join25(__dirname, "..", "package.json"), "utf-8"));

package/dist/prompts.js

@@ -69,7 +69,7 @@ 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. 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 \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist.]
+[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist. MCP RESTART RULE (task-2978): whenever FILES LIKELY TOUCHED includes any \`packages/server/**\` path, append this line verbatim to the handoff \u2014 "MCP RESTART REQUIRED: a mid-session \`npm run mcp-build\` writes a dist the already-booted MCP process never loads, so verifying this change through PAPI's own tools before an explicit MCP reconnect is INVALID. Implement \u2192 mcp-build \u2192 reconnect \u2192 only then verify." This is one line inside this section, not a new section.]
 
 EFFORT
 [XS/S/M/L/XL]
@@ -83,7 +83,7 @@ After your natural language output, include this EXACT format on its own line:
 {
   "cycleLogTitle": "string \u2014 short descriptive title WITHOUT 'Cycle N' prefix. Should capture the cycle theme in 3-5 words (e.g. 'MCP Quality + Product Readiness' not 'Cycle 5 \u2014 Board Triage \u2014 Bug Fix'). This is the canonical theme label for the cycle.",
   "cycleLogContent": "string \u2014 5-10 line cycle log body in markdown, NO heading (the ### heading is generated automatically)",
-  "cycleLogCarryForward": "string or null \u2014 carry-forward items for next cycle",
+  "cycleLogCarryForward": "string or null \u2014 carry-forward for the next cycle, in TWO NAMED SECTIONS, product signal FIRST. Section 1 begins with the literal label 'WHAT SHIPS FOR USERS:' and names, concretely, what a person using this project can now see or do, and how to check it \u2014 never a deploy step. Section 2 begins with the literal label 'RELEASE MECHANICS:' and carries everything operational: deploy, publish, migrations, gate order, branch counts, spot-checks. The mechanics are load-bearing and must NOT be dropped or shortened \u2014 they go second, not away. orient parses these two labels and renders the product half first, so the labels are a contract, not decoration. If a cycle genuinely ships nothing user-visible, say so in one line under section 1 rather than omitting the label.",
   "cycleLogNotes": "string or null \u2014 1-3 lines of cycle-level observations: estimation accuracy, recurring blockers, velocity trends, dependency signals. Omit if no noteworthy observations.",
   "nextMode": "Full",
   "boardHealth": "string \u2014 e.g. 5 tasks (3 backlog, 2 done)",
@@ -947,7 +947,7 @@ After your natural language output, include this EXACT format on its own line:
 \`\`\`json
 {
   "sessionLogTitle": "string \u2014 Strategy Review title WITHOUT 'Cycle N' prefix (e.g. 'Strategy Review' not 'Cycle 5 \u2014 Strategy Review')",
-  "sessionLogContent": "string \u2014 5-10 line cycle log body summarizing the review, NO heading (the ### heading is generated automatically)",
+  "sessionLogContent": "string \u2014 5-10 line cycle log body summarizing the review, NO heading (the ### heading is generated automatically). LEAD WITH TANGIBLE PRODUCT INSIGHT: open with what was learned about the product, its users, or the market \u2014 a specific finding a reader can act on. Board hygiene, cadence, cycle counts, branch state and other housekeeping are legitimate content but they TRAIL; they must never be the opening line. If the review's most important finding genuinely is an operational one, say why it matters to the product in the same breath rather than reporting it as admin.",
   "velocityAssessment": "string \u2014 2-3 sentence velocity summary",
   "strategicRecommendations": "string \u2014 key recommendations in markdown",
   "activeDecisionUpdates": [
@@ -1311,7 +1311,7 @@ REFERENCE DOCS
 [Optional \u2014 paths to docs/ files with background context. Omit if not needed.]
 
 FILES LIKELY TOUCHED
-[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist.]
+[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist. MCP RESTART RULE (task-2978): whenever FILES LIKELY TOUCHED includes any \`packages/server/**\` path, append this line verbatim to the handoff \u2014 "MCP RESTART REQUIRED: a mid-session \`npm run mcp-build\` writes a dist the already-booted MCP process never loads, so verifying this change through PAPI's own tools before an explicit MCP reconnect is INVALID. Implement \u2192 mcp-build \u2192 reconnect \u2192 only then verify." This is one line inside this section, not a new section.]
 
 EFFORT
 [XS/S/M/L/XL]`;

package/package.json

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