@papi-ai/server 0.7.103 → 0.7.105

package/dist/backfill-cycle-metrics.js

@@ -201,6 +201,7 @@ __export(git_exports, {
   ensureLatestDevelop: () => ensureLatestDevelop,
   ensureTagAtHead: () => ensureTagAtHead,
   fetchBaseBranch: () => fetchBaseBranch,
+  findCollidingWork: () => findCollidingWork,
   findContributorReleasePullRequests: () => findContributorReleasePullRequests,
   findTaskCommitsOnBase: () => findTaskCommitsOnBase,
   getBaseDivergence: () => getBaseDivergence,
@@ -1493,6 +1494,23 @@ function getRemoteBranchFiles(cwd, branch, baseBranch) {
     return [];
   }
 }
+function findCollidingWork(cwd, baseBranch, filesLikelyTouched) {
+  if (filesLikelyTouched.length === 0) return null;
+  const prs = listOpenPullRequests(cwd);
+  if (!prs || prs.length === 0) return null;
+  const wanted = new Set(filesLikelyTouched);
+  for (const pr of prs) {
+    const branchFiles = getRemoteBranchFiles(cwd, pr.headRefName, baseBranch);
+    const overlap = branchFiles.filter((f) => wanted.has(f));
+    if (overlap.length > 0) {
+      return {
+        label: `PR #${pr.number} "${pr.title}" (branch \`${pr.headRefName}\`, opened by ${pr.author})`,
+        files: overlap
+      };
+    }
+  }
+  return null;
+}
 var AUTO_WRITTEN_PATHS, GIT_NETWORK_TIMEOUT_MS, MERGE_RETRY_DELAY_MS, MERGE_MAX_RETRIES, GIT_FETCH_TIMEOUT_MS;
 var init_git = __esm({
   "src/lib/git.ts"() {
@@ -1684,7 +1702,6 @@ var init_proxy_adapter = __esm({
       "getBuildReportsSince",
       "getContextHashes",
       "getContextUtilisation",
-      "getCostSnapshots",
       "getCostSummary",
       "getCurrentNorthStar",
       "getCycleHealth",
@@ -2338,9 +2355,8 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       getCostSummary(cycleNumber) {
         return this.invoke("getCostSummary", [cycleNumber]);
       }
-      getCostSnapshots() {
-        return this.invoke("getCostSnapshots");
-      }
+      // task-3332: getCostSnapshots retired — see the removal note on CostSnapshot
+      // in packages/shared/src/entities.ts.
       appendCycleMetrics(snapshot) {
         return this.invoke("appendCycleMetrics", [snapshot]);
       }

package/dist/index.js

@@ -401,6 +401,7 @@ function parseBuildHandoff(markdown) {
     taskTitle,
     cycle,
     whyNow,
+    relevantDecisions: parseBulletsOnly(sections.get("RELEVANT ACTIVE DECISIONS") ?? ""),
     scope: parseBulletList(sections.get("SCOPE (DO THIS)") ?? ""),
     scopeBoundary: parseBulletList(sections.get("SCOPE BOUNDARY (DO NOT DO THIS)") ?? ""),
     acceptanceCriteria: parseChecklist(sections.get("ACCEPTANCE CRITERIA") ?? ""),
@@ -424,6 +425,7 @@ function coerceBuildHandoff(fields, taskId) {
     taskTitle: str(fields.taskTitle),
     cycle: typeof fields.cycle === "number" ? fields.cycle : 0,
     whyNow: str(fields.whyNow),
+    relevantDecisions: ensureArray(fields.relevantDecisions),
     scope,
     scopeBoundary,
     // task-3223: the structured path is where an object criterion (text + an
@@ -471,6 +473,14 @@ function serializeBuildHandoff(raw) {
   lines.push(`Task: ${handoff.taskTitle}`);
   lines.push(`Cycle: ${handoff.cycle}`);
   lines.push(`Why now: ${handoff.whyNow}`);
+  const relevantDecisions = ensureArray(handoff.relevantDecisions);
+  if (relevantDecisions.length > 0) {
+    lines.push("");
+    lines.push("RELEVANT ACTIVE DECISIONS");
+    for (const item of relevantDecisions) {
+      lines.push(`- ${item}`);
+    }
+  }
   lines.push("");
   lines.push("SCOPE (DO THIS)");
   for (const item of ensureArray(handoff.scope)) {
@@ -912,6 +922,7 @@ var init_dist = __esm({
     CHECK_VALUE_MAX = 200;
     VALID_EFFORT_SIZES = /* @__PURE__ */ new Set(["XS", "S", "M", "L", "XL"]);
     SECTION_HEADERS = [
+      "RELEVANT ACTIVE DECISIONS",
       "SCOPE (DO THIS)",
       "WHY NOT SIMPLER",
       "SCOPE BOUNDARY (DO NOT DO THIS)",
@@ -960,6 +971,7 @@ __export(git_exports, {
   ensureLatestDevelop: () => ensureLatestDevelop,
   ensureTagAtHead: () => ensureTagAtHead,
   fetchBaseBranch: () => fetchBaseBranch,
+  findCollidingWork: () => findCollidingWork,
   findContributorReleasePullRequests: () => findContributorReleasePullRequests,
   findTaskCommitsOnBase: () => findTaskCommitsOnBase,
   getBaseDivergence: () => getBaseDivergence,
@@ -2252,6 +2264,23 @@ function getRemoteBranchFiles(cwd, branch, baseBranch) {
     return [];
   }
 }
+function findCollidingWork(cwd, baseBranch, filesLikelyTouched) {
+  if (filesLikelyTouched.length === 0) return null;
+  const prs = listOpenPullRequests(cwd);
+  if (!prs || prs.length === 0) return null;
+  const wanted = new Set(filesLikelyTouched);
+  for (const pr of prs) {
+    const branchFiles = getRemoteBranchFiles(cwd, pr.headRefName, baseBranch);
+    const overlap = branchFiles.filter((f) => wanted.has(f));
+    if (overlap.length > 0) {
+      return {
+        label: `PR #${pr.number} "${pr.title}" (branch \`${pr.headRefName}\`, opened by ${pr.author})`,
+        files: overlap
+      };
+    }
+  }
+  return null;
+}
 var AUTO_WRITTEN_PATHS, GIT_NETWORK_TIMEOUT_MS, MERGE_RETRY_DELAY_MS, MERGE_MAX_RETRIES, GIT_FETCH_TIMEOUT_MS;
 var init_git = __esm({
   "src/lib/git.ts"() {
@@ -2509,7 +2538,6 @@ var init_proxy_adapter = __esm({
       "getBuildReportsSince",
       "getContextHashes",
       "getContextUtilisation",
-      "getCostSnapshots",
       "getCostSummary",
       "getCurrentNorthStar",
       "getCycleHealth",
@@ -3163,9 +3191,8 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       getCostSummary(cycleNumber) {
         return this.invoke("getCostSummary", [cycleNumber]);
       }
-      getCostSnapshots() {
-        return this.invoke("getCostSnapshots");
-      }
+      // task-3332: getCostSnapshots retired — see the removal note on CostSnapshot
+      // in packages/shared/src/entities.ts.
       appendCycleMetrics(snapshot) {
         return this.invoke("appendCycleMetrics", [snapshot]);
       }
@@ -7572,11 +7599,78 @@ init_dist();
 
 // src/lib/formatters.ts
 init_dist();
+var CONFIDENCE_RANK = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+function rankDecisionsForPlan(decisions) {
+  return [...decisions].sort((a, b2) => {
+    const confDiff = (CONFIDENCE_RANK[a.confidence] ?? 1) - (CONFIDENCE_RANK[b2.confidence] ?? 1);
+    if (confDiff !== 0) return confDiff;
+    return (b2.modifiedCycle ?? b2.createdCycle ?? 0) - (a.modifiedCycle ?? a.createdCycle ?? 0);
+  });
+}
 function formatActiveDecisionsForPlan(decisions) {
   if (decisions.length === 0) return "No active decisions.";
-  return decisions.filter((d) => !d.superseded).map((d) => `### ${d.id}: ${d.title} [Confidence: ${d.confidence}]
+  const active = decisions.filter((d) => !d.superseded);
+  if (active.length === 0) return "No active decisions.";
+  const softBudget = Number(process.env.PAPI_AD_CONTEXT_BUDGET) || 4e4;
+  const hardBudget = Math.round(softBudget * 1.3);
+  const ranked = rankDecisionsForPlan(active);
+  const fullBlocks = [];
+  const oneLiners = [];
+  let spent = 0;
+  let degradedFrom = -1;
+  for (let i = 0; i < ranked.length; i++) {
+    const d = ranked[i];
+    const fullBlock = `### ${d.id}: ${d.title} [Confidence: ${d.confidence}]
+
+${d.body}`;
+    const fullCost = Buffer.byteLength(`${fullBlock}
 
-${d.body}`).join("\n\n");
+`, "utf-8");
+    if (spent + fullCost <= softBudget) {
+      fullBlocks.push(fullBlock);
+      spent += fullCost;
+      continue;
+    }
+    degradedFrom = i;
+    break;
+  }
+  const compactedIds = [];
+  const omittedIds = [];
+  if (degradedFrom >= 0) {
+    for (let i = degradedFrom; i < ranked.length; i++) {
+      const d = ranked[i];
+      const line = `- ${d.id} (${d.title}) [${d.confidence}]`;
+      const cost = Buffer.byteLength(`${line}
+`, "utf-8");
+      if (spent + cost <= hardBudget) {
+        oneLiners.push(line);
+        compactedIds.push(d.id);
+        spent += cost;
+      } else {
+        omittedIds.push(d.id);
+      }
+    }
+  }
+  const parts = [...fullBlocks];
+  if (oneLiners.length > 0) {
+    parts.push(`### Other Active Decisions (compacted for budget)
+
+${oneLiners.join("\n")}`);
+  }
+  if (compactedIds.length > 0 || omittedIds.length > 0) {
+    const noteLines = [
+      `### Context Budget \u2014 Active Decisions trimmed`,
+      "",
+      `${compactedIds.length + omittedIds.length} of ${ranked.length} Active Decisions were compacted to one-liners to keep this plan payload under ~${Math.round(softBudget / 1024)} KB (lowest confidence/oldest first). Full bodies above are complete and untrimmed.`
+    ];
+    if (omittedIds.length > 0) {
+      noteLines.push(
+        `${omittedIds.length} AD one-liner(s) were additionally omitted from the list above for exceeding the hard budget, but are not forgotten: ${omittedIds.join(", ")}. Raise PAPI_AD_CONTEXT_BUDGET in the MCP server env to see their one-liners, or run ad_view for full detail on any specific one.`
+      );
+    }
+    parts.push(noteLines.join("\n"));
+  }
+  return parts.join("\n\n");
 }
 function formatActiveDecisionsForReview(decisions) {
   if (decisions.length === 0) return "No active decisions.";
@@ -8381,6 +8475,9 @@ Why now: [justification]
 DEPENDS ON
 [Optional \u2014 comma-separated task IDs this task depends on (e.g. "task-123, task-124"). Include only when another task in this same cycle must be built first because this task consumes artifacts it creates (e.g. new adapter method, new type, new migration). The builder will reuse the upstream task's branch so dependent commits stack on the same branch for a single PR. Omit this section entirely if there are no intra-cycle dependencies.]
 
+RELEVANT ACTIVE DECISIONS
+[Optional \u2014 self-check which Active Decisions actually bind the FILES LIKELY TOUCHED and module below, out of the full AD list already in your context. List the top 3-6 as "AD-N (title) \u2014 one-line reason this AD binds the files/approach". Rank by blast radius (an AD that would be VIOLATED by a naive implementation outranks one that's merely thematically adjacent). This is a judgement call \u2014 no server-side scoring feeds this. Omit this section entirely when nothing in the AD list is genuinely relevant to what this task touches; do not force a match.]
+
 SCOPE (DO THIS)
 [specific deliverables \u2014 write for the simplest viable path first]
 
@@ -9716,6 +9813,9 @@ Why now: [justification]
 DEPENDS ON
 [Optional \u2014 comma-separated task IDs this task depends on (e.g. "task-123, task-124"). Include only when another task in this same cycle must be built first because this task consumes artifacts it creates (e.g. new adapter method, new type, new migration). The builder will reuse the upstream task's branch so dependent commits stack on the same branch for a single PR. Omit this section entirely if there are no intra-cycle dependencies.]
 
+RELEVANT ACTIVE DECISIONS
+[Optional \u2014 self-check which Active Decisions actually bind the FILES LIKELY TOUCHED and module below, out of the full AD list already in your context. List the top 3-6 as "AD-N (title) \u2014 one-line reason this AD binds the files/approach". Rank by blast radius (an AD that would be VIOLATED by a naive implementation outranks one that's merely thematically adjacent). This is a judgement call \u2014 no server-side scoring feeds this. Omit this section entirely when nothing in the AD list is genuinely relevant to what this task touches; do not force a match.]
+
 SCOPE (DO THIS)
 [specific deliverables \u2014 write for the simplest viable path first]
 
@@ -10870,6 +10970,23 @@ function idMatches(candidate, ref) {
   if (!candidate) return false;
   return candidate.toLowerCase() === ref.toLowerCase();
 }
+function findDecision(ref, decisions) {
+  return decisions.find((d) => idMatches(d.displayId, ref) || idMatches(d.id, ref));
+}
+function resolveCurrentDecision(ref, decisions, maxDepth = 10) {
+  let current = findDecision(ref, decisions);
+  if (!current) return void 0;
+  const visited = /* @__PURE__ */ new Set([current.id]);
+  let depth = 0;
+  while (current?.superseded === true && current.supersededBy && depth < maxDepth) {
+    const next = findDecision(current.supersededBy, decisions);
+    if (!next || visited.has(next.id)) break;
+    visited.add(next.id);
+    current = next;
+    depth += 1;
+  }
+  return current;
+}
 function isBlockerResolved(blocker, ctx) {
   if (!blocker || !blocker.ref) return false;
   switch (blocker.type) {
@@ -10884,9 +11001,7 @@ function isBlockerResolved(blocker, ctx) {
       return action != null && action.completed_at != null;
     }
     case "decision-gate": {
-      const decision = ctx.decisions.find(
-        (d) => idMatches(d.displayId, blocker.ref) || idMatches(d.id, blocker.ref)
-      );
+      const decision = resolveCurrentDecision(blocker.ref, ctx.decisions);
       if (decision?.superseded === true) return true;
       const resolvedOutcomes = /* @__PURE__ */ new Set(["validated"]);
       if (decision?.outcome && resolvedOutcomes.has(decision.outcome)) return true;
@@ -10902,9 +11017,7 @@ function isBlockerResolved(blocker, ctx) {
 }
 function blockerNeedsRedecision(blocker, ctx) {
   if (!blocker || blocker.type !== "decision-gate" || !blocker.ref) return false;
-  const decision = ctx.decisions.find(
-    (d) => idMatches(d.displayId, blocker.ref) || idMatches(d.id, blocker.ref)
-  );
+  const decision = resolveCurrentDecision(blocker.ref, ctx.decisions);
   return decision?.resolutionState === "withdrawn";
 }
 function formatBlockerWaiting(blocker, refTitle) {
@@ -10927,9 +11040,7 @@ function resolveBlockerTitle(blocker, ctx) {
         (t) => idMatches(t.displayId, blocker.ref) || idMatches(t.id, blocker.ref)
       )?.title;
     case "decision-gate":
-      return ctx.decisions.find(
-        (d) => idMatches(d.displayId, blocker.ref) || idMatches(d.id, blocker.ref)
-      )?.title;
+      return resolveCurrentDecision(blocker.ref, ctx.decisions)?.title;
     default:
       return void 0;
   }
@@ -17761,7 +17872,11 @@ var boardDeprioritiseTool = {
       },
       blocker_ref: {
         type: "string",
-        description: "Required when blocker_type is set. The identifier being waited on: a task display-id (depends-on), an AD/decision id (decision-gate), or an owner_action id (owner-action)."
+        description: "Required when blocker_type is set, EXCEPT owner-action with owner_action_name (that mode creates the owner_action and derives the ref itself). The identifier being waited on: a task display-id (depends-on), an AD/decision id (decision-gate), or an existing owner_action id (owner-action, link mode)."
+      },
+      owner_action_name: {
+        type: "string",
+        description: 'Optional, blocker_type="owner-action" only. When set, CREATES a new owner action with this name and unlocks_task_id set to this task in the same insert, instead of linking to an existing one \u2014 collapses the old create-then-link two-step into one call. Omit blocker_ref in this mode; it is derived from the created row.'
       },
       defer: {
         type: "boolean",
@@ -17779,15 +17894,26 @@ var boardDeprioritiseTool = {
     required: ["task_id"],
     // task-2802: mirror the handler's guards so the agent sees the dependency up
     // front. handleBoardDeprioritise requires `reason` for both block and cancel,
-    // and requires `blocker_ref` whenever `blocker_type` is set. Keyed on explicit
-    // values — an omitted action defaults to "backlog" and triggers neither.
+    // and requires `blocker_ref` whenever `blocker_type` is set — EXCEPT the
+    // task-3451 owner-action create mode (blocker_type='owner-action' +
+    // owner_action_name), which derives its ref from the row it creates.
+    // Keyed on explicit values — an omitted action defaults to "backlog" and
+    // triggers neither.
     allOf: [
       {
         if: { properties: { action: { enum: ["block", "cancel"] } }, required: ["action"] },
         then: { required: ["reason"] }
       },
       {
-        if: { required: ["blocker_type"] },
+        if: {
+          required: ["blocker_type"],
+          not: {
+            allOf: [
+              { properties: { blocker_type: { const: "owner-action" } }, required: ["blocker_type"] },
+              { required: ["owner_action_name"] }
+            ]
+          }
+        },
         then: { required: ["blocker_ref"] }
       }
     ]
@@ -18092,13 +18218,18 @@ async function handleBoardDeprioritise(adapter2, args) {
       return errorResponse("reason is required when blocking a task \u2014 explain what external dependency or gate is blocking it.");
     }
     const blockerType = args.blocker_type;
-    const blockerRef = args.blocker_ref;
+    let blockerRef = args.blocker_ref;
+    const ownerActionName = args.owner_action_name;
+    const isOwnerActionCreateMode = blockerType === "owner-action" && Boolean(ownerActionName);
     const validTypes = /* @__PURE__ */ new Set(["depends-on", "decision-gate", "owner-action"]);
     if (blockerType !== void 0 && !validTypes.has(blockerType)) {
       return errorResponse(`blocker_type must be one of: depends-on, decision-gate, owner-action (got "${blockerType}").`);
     }
-    if (blockerType !== void 0 && !blockerRef) {
-      return errorResponse("blocker_ref is required when blocker_type is set \u2014 provide the task display-id, decision id, or owner_action id being waited on.");
+    if (blockerType !== void 0 && !blockerRef && !isOwnerActionCreateMode) {
+      return errorResponse("blocker_ref is required when blocker_type is set \u2014 provide the task display-id, decision id, or owner_action id being waited on (or owner_action_name to create a new owner action).");
+    }
+    if (ownerActionName && blockerType !== "owner-action") {
+      return errorResponse('owner_action_name only applies when blocker_type is "owner-action".');
     }
     try {
       const task = await adapter2.getTask(taskId);
@@ -18111,25 +18242,41 @@ async function handleBoardDeprioritise(adapter2, args) {
         notes: `${existingNotes}BLOCKED: ${reason}`
       };
       let typedSuffix = "";
-      if (blockerType !== void 0 && blockerRef) {
-        const health = await adapter2.getCycleHealth().catch(() => null);
-        const blockedCycle = health?.totalCycles ?? 0;
-        updates.blocker = {
-          type: blockerType,
-          ref: blockerRef,
-          reason,
-          blockedCycle
-        };
-        typedSuffix = `
-
-Blocker: **${blockerType}** \u2192 ${blockerRef} (auto-unblock scanned at plan/orient).`;
-        if (blockerType === "owner-action" && adapter2.linkOwnerActionToTask && adapter2.getProjectOwnerUserId) {
+      if (blockerType !== void 0 && (blockerRef || isOwnerActionCreateMode)) {
+        if (isOwnerActionCreateMode && adapter2.createOwnerAction && adapter2.getProjectOwnerUserId) {
           try {
             const ownerUserId = await adapter2.getProjectOwnerUserId();
-            if (ownerUserId) await adapter2.linkOwnerActionToTask(blockerRef, task.uuid, ownerUserId);
+            if (ownerUserId) {
+              const created = await adapter2.createOwnerAction(ownerUserId, {
+                name: ownerActionName,
+                dependency: reason,
+                unlocks_task_id: task.uuid
+              });
+              blockerRef = created.id;
+            }
           } catch {
           }
         }
+        if (blockerRef) {
+          const health = await adapter2.getCycleHealth().catch(() => null);
+          const blockedCycle = health?.totalCycles ?? 0;
+          updates.blocker = {
+            type: blockerType,
+            ref: blockerRef,
+            reason,
+            blockedCycle
+          };
+          typedSuffix = `
+
+Blocker: **${blockerType}** \u2192 ${blockerRef} (auto-unblock scanned at plan/orient).`;
+          if (blockerType === "owner-action" && !isOwnerActionCreateMode && adapter2.linkOwnerActionToTask && adapter2.getProjectOwnerUserId) {
+            try {
+              const ownerUserId = await adapter2.getProjectOwnerUserId();
+              if (ownerUserId) await adapter2.linkOwnerActionToTask(blockerRef, task.uuid, ownerUserId);
+            } catch {
+            }
+          }
+        }
       }
       await adapter2.updateTask(taskId, updates);
       return textResponse(`Blocked **${taskId}** (${task.title}).
@@ -24777,6 +24924,41 @@ The registry stores metadata and a summary \u2014 not the body. This doc has one
   return `
 - **Durability:** committed \`${path8}\` (was untracked)`;
 }
+var DOC_OVERLAP_COVERAGE_THRESHOLD = 0.6;
+async function findOverlappingDocs(target, type, title, summary) {
+  if (!target.searchDocs) return [];
+  const newKeywords = extractKeywords(`${title} ${summary}`);
+  if (newKeywords.size < 2) return [];
+  let candidates;
+  try {
+    candidates = await target.searchDocs({ type, status: "active" });
+  } catch {
+    return [];
+  }
+  const matches = [];
+  for (const doc of candidates) {
+    const docKeywords = extractKeywords(`${doc.title} ${doc.summary}`);
+    if (docKeywords.size < 2) continue;
+    let covered = 0;
+    for (const word of newKeywords) if (docKeywords.has(word)) covered++;
+    const coverage = covered / newKeywords.size;
+    if (coverage >= DOC_OVERLAP_COVERAGE_THRESHOLD) {
+      matches.push({ path: doc.path, title: doc.title, coverage });
+    }
+  }
+  return matches.sort((a, b2) => b2.coverage - a.coverage).slice(0, 3);
+}
+function overlapReconciliationNote(overlaps) {
+  if (overlaps.length === 0) return "";
+  const named = overlaps.map((o) => `\`${o.path}\` ("${o.title}")`).join(", ");
+  return `
+
+\u26A0\uFE0F **Possible overlap** with existing active doc(s): ${named} \u2014 verify it is real, then classify:
+- **AGREES** \u2014 restates the existing doc. Don't duplicate; nothing to register.
+- **EXTENDS** \u2014 new ground the existing doc doesn't cover. Fine to register as-is.
+- **CONTRADICTS** \u2014 cuts against the existing doc. Surface to the owner \u2014 never resolve silently (task-3219: a contradiction is not a veto).
+- **SUPERSEDES** \u2014 this doc should replace the existing one. Re-run doc_register with \`superseded_by_path\` pointing at the overlapping doc's path.`;
+}
 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.";
@@ -24835,6 +25017,7 @@ async function handleDocRegister(adapter2, args, config2) {
     );
   }
   try {
+    const overlaps = supersededByPath ? [] : await findOverlappingDocs(target, type, title, summary);
     let supersededBy;
     if (supersededByPath) {
       const existing = await target.getDoc?.(supersededByPath);
@@ -24910,7 +25093,7 @@ ${decision.message}`;
 - **Visibility:** ${visibilityLabel}
 - **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
 - **Actions:** ${actions?.length ?? 0} items
-- **ID:** ${entry.id}` + bodyNote + durability
+- **ID:** ${entry.id}` + bodyNote + durability + overlapReconciliationNote(overlaps)
     );
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -27595,7 +27778,7 @@ function resolveAdHocCycle(cycle, latest, latestComplete) {
   if (cycle === "current") return latest;
   return latestComplete ? latest + 1 : latest;
 }
-async function recordAdHoc(adapter2, input) {
+async function recordAdHoc(adapter2, config2, input) {
   const [health, phases] = await Promise.all([
     adapter2.getCycleHealth(),
     adapter2.readPhases()
@@ -27617,9 +27800,16 @@ async function recordAdHoc(adapter2, input) {
     if (!existing) {
       throw new Error(`Task "${input.taskId}" not found on the board. Check the task ID and try again.`);
     }
-    if (!existing.assigneeId) {
+    if (existing.assigneeId) {
+      const gate = await resolveOwnerGate(adapter2, config2);
+      if (gate.enforced && (!gate.callerUserId || gate.callerUserId !== existing.assigneeId)) {
+        throw new Error(
+          `Task "${input.taskId}" (${existing.title}) is claimed by another member \u2014 ad-hoc work cannot be recorded against it. Have the claimer record it, or run \`task_unclaim\` to release it first.`
+        );
+      }
+    } else {
       warnings.push(
-        `\u2139\uFE0F ${input.taskId} has no assignee \u2014 recording ad-hoc work against an unclaimed pool task. If someone else might be building it too, check for an open PR/branch on the same files before merging.`
+        `\u2139\uFE0F ${input.taskId} has no assignee \u2014 recording ad-hoc work against an unclaimed pool task. ` + (input.collidingWorkNote ?? `If someone else might be building it too, check for an open PR/branch on the same files before merging.`)
       );
     }
     const updatePayload = {
@@ -27876,7 +28066,22 @@ async function handleAdHoc(adapter2, config2, args) {
   const gitUsable = !overrideNote && isGitAvailable() && isGitRepo(config2.projectRoot);
   const currentBranch = gitUsable ? getCurrentBranch(config2.projectRoot) : null;
   const baseBranch = gitUsable ? resolveBaseBranch(config2.projectRoot, config2.baseBranch) : null;
-  const result = await recordAdHoc(target, {
+  let collidingWorkNote;
+  if (taskId && gitUsable && baseBranch) {
+    try {
+      const existingTask = await target.getTask(taskId);
+      const filesLikelyTouched = existingTask?.buildHandoff?.filesLikelyTouched ?? [];
+      if (existingTask && !existingTask.assigneeId && filesLikelyTouched.length > 0) {
+        const collision = findCollidingWork(config2.projectRoot, baseBranch, filesLikelyTouched);
+        if (collision) {
+          const fileList = collision.files.slice(0, 3).join(", ") + (collision.files.length > 3 ? ", \u2026" : "");
+          collidingWorkNote = `${collision.label} already touches ${collision.files.length === 1 ? "the same file" : `${collision.files.length} of the same files`} (${fileList}) \u2014 check it before merging.`;
+        }
+      }
+    } catch {
+    }
+  }
+  const result = await recordAdHoc(target, config2, {
     title: title || "",
     taskId,
     notes: rawNotes,
@@ -27891,7 +28096,8 @@ async function handleAdHoc(adapter2, config2, args) {
     stage: stageArg,
     hold: holdArg,
     currentBranch,
-    baseBranch
+    baseBranch,
+    collidingWorkNote
   });
   if (!holdArg && gitUsable) {
     try {
@@ -28923,6 +29129,27 @@ var reviewSubmitTool = {
           }
         },
         required: ["verdict", "summary", "findings"]
+      },
+      proposal: {
+        type: "object",
+        description: 'task-3388, OPTIONAL (build-acceptance + verdict:"accept" only): propose a Decision or a Convention the build or the review itself settled. Same mechanism as build_execute\u2019s `proposal` (task-3273) \u2014 PAPI never mints one for you. A proposal that passes all four admission tests is QUEUED for the owner behind a decision gate, and nothing is written as an Active Decision. YOU apply the four tests (they are stated in the planning prompts); the server routes on your answers and makes no judgement about the content. Fails "arguable today" only and it is recorded as a Convention instead, riding every future build. Fails "constrains future work" and it is returned to you with the reason, unrecorded.',
+        properties: {
+          title: { type: "string", description: "One line stating the stance or rule." },
+          body: { type: "string", description: "What was decided or settled, and why." },
+          module: { type: "string", description: "Optional module scope. Only used when this lands as a Convention." },
+          tests: {
+            type: "object",
+            description: "The four admission tests, each answered explicitly. An omitted test is NOT a failed test \u2014 the proposal is refused rather than routed.",
+            properties: {
+              alternativesWereReal: { type: "boolean", description: "(a) Something else could genuinely have been chosen." },
+              constrainsFutureWork: { type: "boolean", description: "(b) It changes what a task nobody has written yet will do." },
+              arguableToday: { type: "boolean", description: "(c) A competent person could argue the other side right now." },
+              reversalCostsMore: { type: "boolean", description: "(d) Reversing it costs more than making it did." }
+            },
+            required: ["alternativesWereReal", "constrainsFutureWork", "arguableToday", "reversalCostsMore"]
+          }
+        },
+        required: ["title", "body", "tests"]
       }
     },
     required: ["task_id", "stage", "verdict", "comments"],
@@ -29538,6 +29765,30 @@ Next: address the feedback, then run \`build_execute ${taskId}\` to resubmit.`;
       }
     } catch {
     }
+    let proposalNote = "";
+    if (args.proposal !== void 0) {
+      if (!(stage === "build-acceptance" && verdict === "accept")) {
+        proposalNote = "\n\n---\n\n**Proposal not recorded.** `proposal` is only accepted on a build-acceptance `accept` \u2014 nothing has settled on a handoff-review or a non-accept verdict.\n\nThe review itself is unaffected \u2014 only the proposal was skipped.";
+      } else {
+        const validated = validateProposal(args.proposal);
+        if ("error" in validated) {
+          proposalNote = `
+
+---
+
+**Proposal not recorded.** ${validated.error}
+
+The review itself is unaffected \u2014 only the proposal failed.`;
+        } else {
+          const routing = routeProposal(validated.proposal);
+          const applied = await applyProposal(adapter2, routing, validated.proposal, {
+            cycleNumber: result.currentCycle,
+            sourceTaskId: result.taskId
+          });
+          proposalNote = formatProposalOutcome(routing, validated.proposal, applied);
+        }
+      }
+    }
     tracker.mark("format-response");
     return textResponse(
       `**${result.stageLabel}** recorded for ${result.taskId}.
@@ -29545,7 +29796,7 @@ Next: address the feedback, then run \`build_execute ${taskId}\` to resubmit.`;
 - **Verdict:** ${result.verdict}
 - **Comments:** ${trimForEcho(result.comments)}
 
-${statusNote}${capabilityReviewSkippedNote}${autoReviewNote}${securityNote}${adConflictNote}${unblockNote}${docClosureNote}${regenNote}${mergeNote}${overlapNote}${batchSummaryNote}${autoReleaseNote}${nextStepNote}${phaseNote}`
+${statusNote}${capabilityReviewSkippedNote}${autoReviewNote}${securityNote}${adConflictNote}${unblockNote}${docClosureNote}${regenNote}${mergeNote}${overlapNote}${batchSummaryNote}${autoReleaseNote}${nextStepNote}${phaseNote}${proposalNote}`
     );
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -30579,6 +30830,41 @@ function formatUnblockSection(candidates) {
   return lines.join("\n");
 }
 
+// src/lib/decision-drafts.ts
+async function findPendingDecisionDrafts(adapter2) {
+  let blockedProbe;
+  try {
+    blockedProbe = await adapter2.queryBoard({ status: ["Blocked"], compact: true });
+  } catch {
+    return [];
+  }
+  if (blockedProbe.length === 0) return [];
+  const drafts = [];
+  for (const task of blockedProbe) {
+    const blocker = task.blocker;
+    if (!blocker || blocker.type !== "decision-gate" || blocker.ref !== PROPOSED_DECISION_REF) continue;
+    const evidence = (task.notes ?? "").split("\n")[0]?.trim() ?? "";
+    drafts.push({
+      taskId: task.displayId ?? task.id,
+      taskTitle: task.title,
+      evidence
+    });
+  }
+  return drafts;
+}
+function formatPendingDecisionDrafts(drafts) {
+  if (drafts.length === 0) return "";
+  const lines = ["## Decisions Awaiting Your Call"];
+  lines.push(
+    `${drafts.length} decision${drafts.length === 1 ? "" : "s"} proposed during a build, waiting on you \u2014 mint with \`strategy_change\` to make it a real Active Decision, or \`board_edit <task> status:Cancelled\` to dismiss it. Neither is automatic.`
+  );
+  lines.push("");
+  for (const d of drafts) {
+    lines.push(`- **${formatRef(d.taskId, d.taskTitle)}**${d.evidence ? ` \u2014 ${d.evidence}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
 // src/lib/deferred-gate.ts
 var GATE_PHRASES = [
   "depends on",
@@ -32121,7 +32407,8 @@ async function handleOrient(rawAdapter, config2, args = {}, clientName, serverVe
         }
         let unrecordedNote2 = "";
         try {
-          const unrecorded = detectUnrecordedCommits(config2.projectRoot, config2.baseBranch);
+          const { compareRef } = getBaseDivergence(config2.projectRoot, config2.baseBranch, { timeoutMs: ORIGIN_FETCH_TIMEOUT_MS });
+          const unrecorded = detectUnrecordedCommits(config2.projectRoot, compareRef);
           if (unrecorded.length > 0) {
             const doneTasks = await adapter2.queryBoard({ status: ["Done"] });
             const adHocDoneTasks = doneTasks.filter((t) => t.cycle == null);
@@ -32250,8 +32537,14 @@ ${versionDrift}` : "";
     }
     tracker.mark("parallel-tail");
     const sharedContributorsPromise = adapterSupports(adapter2, "listContributors") ? adapter2.listContributors().catch(() => []) : Promise.resolve([]);
-    const [unblockCandidates, subAgents, teamSummaryLine, releaseHistoryLine, cohortVisibilityLine, carryForwardRefs] = await Promise.all([
+    const [unblockCandidates, pendingDecisionDrafts, subAgents, teamSummaryLine, releaseHistoryLine, cohortVisibilityLine, carryForwardRefs] = await Promise.all([
       tracked("unblock-candidates", () => findUnblockCandidates(adapter2, currentCycle2))().catch(() => []),
+      // task-3388: pending decision-proposal drafts (build_execute/review_submit's
+      // `proposal` param, task-3273/3388) — mandatory reader, deliberately
+      // uncapped and separate from the housekeeping-suggestion unblock list above
+      // (see lib/decision-drafts.ts for why). Runs on every orient call, not
+      // gated behind deep_housekeeping — same posture as unblock-candidates.
+      tracked("pending-decision-drafts", () => findPendingDecisionDrafts(adapter2))().catch(() => []),
       // task-1866: discover project sub-agents for the orient surface (read-only, never throws).
       listAgents(config2.projectRoot),
       // task-2071 (MU-3) + task-2072 (MU-5): team summary + release-history — both
@@ -32270,6 +32563,10 @@ ${versionDrift}` : "";
     const unblockNote = unblockSection ? `
 
 ${unblockSection}` : "";
+    const decisionDraftsSection = formatPendingDecisionDrafts(pendingDecisionDrafts);
+    const decisionDraftsNote = decisionDraftsSection ? `
+
+${decisionDraftsSection}` : "";
     const teamSummary = [teamSummaryLine, releaseHistoryLine, cohortVisibilityLine].filter(Boolean).join("\n") || void 0;
     let deferredGateNote = "";
     if (deepHousekeeping) {
@@ -32300,7 +32597,42 @@ ${section}`;
     const runtimeIdentityNote = `
 
 ${formatRuntimeIdentity(getRuntimeIdentity(config2, serverVersion))}`;
-    return { ...textResponse(projectOverrideLine + projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName, carryForwardRefs) + runtimeIdentityNote + unblockNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + onboardingCoachingNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection), _cycleNumber: healthResult.cycleNumber };
+    let effDeepHint = deepHint;
+    let effOnboardingCoachingNote = onboardingCoachingNote;
+    let effStaleSkillsNote = staleSkillsNote;
+    let effResearchSignalsNote = researchSignalsNote;
+    const droppedNotes = [];
+    const assembleOrientOutput = () => projectOverrideLine + projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName, carryForwardRefs) + runtimeIdentityNote + unblockNote + decisionDraftsNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + effStaleSkillsNote + effResearchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + effOnboardingCoachingNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + effDeepHint + enrichmentFilesSection;
+    const orientBudgetSoft = Number(process.env.PAPI_ORIENT_CONTEXT_BUDGET) || 6e4;
+    let assembled = assembleOrientOutput();
+    if (Buffer.byteLength(assembled, "utf-8") > orientBudgetSoft && effDeepHint) {
+      effDeepHint = "";
+      droppedNotes.push("deep-housekeeping tip");
+      assembled = assembleOrientOutput();
+    }
+    if (Buffer.byteLength(assembled, "utf-8") > orientBudgetSoft && effOnboardingCoachingNote) {
+      effOnboardingCoachingNote = "";
+      droppedNotes.push("onboarding coaching");
+      assembled = assembleOrientOutput();
+    }
+    if (Buffer.byteLength(assembled, "utf-8") > orientBudgetSoft && effStaleSkillsNote) {
+      effStaleSkillsNote = "";
+      droppedNotes.push("stale skills");
+      assembled = assembleOrientOutput();
+    }
+    if (Buffer.byteLength(assembled, "utf-8") > orientBudgetSoft && effResearchSignalsNote) {
+      effResearchSignalsNote = "";
+      droppedNotes.push("research signals");
+      assembled = assembleOrientOutput();
+    }
+    if (droppedNotes.length > 0) {
+      assembled += `
+
+---
+
+*Context budget: ${droppedNotes.length} advisory note(s) omitted to keep this orient payload under ~${Math.round(orientBudgetSoft / 1024)} KB \u2014 ${droppedNotes.join(", ")}. Raise \`PAPI_ORIENT_CONTEXT_BUDGET\` in the MCP server env, or re-run without \`deep_housekeeping\`/\`full\` for a smaller payload by default.*`;
+    }
+    return { ...textResponse(assembled), _cycleNumber: healthResult.cycleNumber };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const isKnownFriendly = /^(Orient failed|Project not found|No project|Setup required)/i.test(message);
@@ -33561,7 +33893,7 @@ var decisionResolveTool = {
     required: ["ad_id", "action"]
   }
 };
-function findDecision(decisions, adId) {
+function findDecision2(decisions, adId) {
   const trimmed = adId.trim();
   return decisions.find((d) => d.id === trimmed || d.displayId === trimmed);
 }
@@ -33594,7 +33926,7 @@ async function handleDecisionResolve(adapter2, config2, args) {
   } catch (err) {
     return errorResponse(`Failed to read active decisions: ${err instanceof Error ? err.message : String(err)}`);
   }
-  const target = findDecision(decisions, adId);
+  const target = findDecision2(decisions, adId);
   if (!target) return errorResponse(`AD not found: ${adId}. Run ad_view to see available decisions.`);
   if (target.resolutionState !== "proposed") {
     return errorResponse(

package/dist/prompts.js

@@ -78,6 +78,9 @@ Why now: [justification]
 DEPENDS ON
 [Optional \u2014 comma-separated task IDs this task depends on (e.g. "task-123, task-124"). Include only when another task in this same cycle must be built first because this task consumes artifacts it creates (e.g. new adapter method, new type, new migration). The builder will reuse the upstream task's branch so dependent commits stack on the same branch for a single PR. Omit this section entirely if there are no intra-cycle dependencies.]
 
+RELEVANT ACTIVE DECISIONS
+[Optional \u2014 self-check which Active Decisions actually bind the FILES LIKELY TOUCHED and module below, out of the full AD list already in your context. List the top 3-6 as "AD-N (title) \u2014 one-line reason this AD binds the files/approach". Rank by blast radius (an AD that would be VIOLATED by a naive implementation outranks one that's merely thematically adjacent). This is a judgement call \u2014 no server-side scoring feeds this. Omit this section entirely when nothing in the AD list is genuinely relevant to what this task touches; do not force a match.]
+
 SCOPE (DO THIS)
 [specific deliverables \u2014 write for the simplest viable path first]
 
@@ -1413,6 +1416,9 @@ Why now: [justification]
 DEPENDS ON
 [Optional \u2014 comma-separated task IDs this task depends on (e.g. "task-123, task-124"). Include only when another task in this same cycle must be built first because this task consumes artifacts it creates (e.g. new adapter method, new type, new migration). The builder will reuse the upstream task's branch so dependent commits stack on the same branch for a single PR. Omit this section entirely if there are no intra-cycle dependencies.]
 
+RELEVANT ACTIVE DECISIONS
+[Optional \u2014 self-check which Active Decisions actually bind the FILES LIKELY TOUCHED and module below, out of the full AD list already in your context. List the top 3-6 as "AD-N (title) \u2014 one-line reason this AD binds the files/approach". Rank by blast radius (an AD that would be VIOLATED by a naive implementation outranks one that's merely thematically adjacent). This is a judgement call \u2014 no server-side scoring feeds this. Omit this section entirely when nothing in the AD list is genuinely relevant to what this task touches; do not force a match.]
+
 SCOPE (DO THIS)
 [specific deliverables \u2014 write for the simplest viable path first]
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.103",
-  "description": "PAPI MCP server \u2014 AI-powered sprint planning, build execution, and strategy review for software projects",
+  "version": "0.7.105",
+  "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",
   "type": "module",