@papi-ai/server 0.7.98 → 0.7.104

package/dist/backfill-cycle-metrics.js

@@ -189,6 +189,7 @@ __export(git_exports, {
   checkoutBranch: () => checkoutBranch,
   commitSinglePath: () => commitSinglePath,
   commitStagedOnly: () => commitStagedOnly,
+  computeAheadBehind: () => computeAheadBehind,
   createAndCheckoutBranch: () => createAndCheckoutBranch,
   createPullRequest: () => createPullRequest,
   createTag: () => createTag,
@@ -199,8 +200,10 @@ __export(git_exports, {
   detectUnrecordedCommits: () => detectUnrecordedCommits,
   ensureLatestDevelop: () => ensureLatestDevelop,
   ensureTagAtHead: () => ensureTagAtHead,
+  fetchBaseBranch: () => fetchBaseBranch,
   findContributorReleasePullRequests: () => findContributorReleasePullRequests,
   findTaskCommitsOnBase: () => findTaskCommitsOnBase,
+  getBaseDivergence: () => getBaseDivergence,
   getBranchDiff: () => getBranchDiff,
   getCommitFiles: () => getCommitFiles,
   getCommitsSinceTag: () => getCommitsSinceTag,
@@ -235,6 +238,7 @@ __export(git_exports, {
   hasUnpushedCommits: () => hasUnpushedCommits,
   isBranchContentAlreadyInBase: () => isBranchContentAlreadyInBase,
   isBranchMergedInto: () => isBranchMergedInto,
+  isCommitReachable: () => isCommitReachable,
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
   isGitRepo: () => isGitRepo,
@@ -1297,6 +1301,19 @@ function isBranchMergedInto(cwd, branch, baseBranch) {
     return false;
   }
 }
+function isCommitReachable(cwd, commit, baseBranch) {
+  const recordedCommit = commit.trim();
+  if (!recordedCommit) return false;
+  try {
+    execFileSync("git", ["merge-base", "--is-ancestor", recordedCommit, baseBranch], {
+      cwd,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isBranchContentAlreadyInBase(cwd, branch, baseBranch) {
   const resolveCommit = (ref) => {
     try {
@@ -1323,6 +1340,55 @@ function isBranchContentAlreadyInBase(cwd, branch, baseBranch) {
     return false;
   }
 }
+function fetchBaseBranch(cwd, baseBranch, timeoutMs = GIT_FETCH_TIMEOUT_MS) {
+  if (!isGitAvailable() || !isGitRepo(cwd) || !hasRemote(cwd)) {
+    return { fetched: false, compareRef: baseBranch };
+  }
+  const result = spawnSync("git", ["fetch", "--quiet", "origin", baseBranch], {
+    cwd,
+    encoding: "utf-8",
+    timeout: timeoutMs
+  });
+  if (result.error || result.status !== 0) {
+    const raw = result.error?.message ?? ((result.stderr || "").trim() || `git exited ${result.status}`);
+    const isTimeout = result.signal === "SIGTERM" || /ETIMEDOUT/.test(raw);
+    return {
+      fetched: false,
+      compareRef: baseBranch,
+      warning: isTimeout ? `Fetch from origin timed out after ${Math.round(timeoutMs / 1e3)}s \u2014 comparing against the local '${baseBranch}' ref, which may be stale.` : `Fetch from origin failed \u2014 comparing against the local '${baseBranch}' ref, which may be stale. (${raw})`
+    };
+  }
+  return { fetched: true, compareRef: `origin/${baseBranch}` };
+}
+function computeAheadBehind(cwd, compareRef, ref = "HEAD") {
+  try {
+    const out = execFileSync(
+      "git",
+      ["rev-list", "--left-right", "--count", `${compareRef}...${ref}`],
+      { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
+    ).trim();
+    const [behindStr, aheadStr] = out.split(/\s+/);
+    const behind = parseInt(behindStr, 10);
+    const ahead = parseInt(aheadStr, 10);
+    if (Number.isNaN(behind) || Number.isNaN(ahead)) return null;
+    return { ahead, behind };
+  } catch {
+    return null;
+  }
+}
+function getBaseDivergence(cwd, preferredBase, opts) {
+  const baseBranch = resolveBaseBranch(cwd, preferredBase);
+  const fetch2 = fetchBaseBranch(cwd, baseBranch, opts?.timeoutMs);
+  const divergence = computeAheadBehind(cwd, fetch2.compareRef, opts?.ref ?? "HEAD");
+  return {
+    baseBranch,
+    compareRef: fetch2.compareRef,
+    fetched: fetch2.fetched,
+    ahead: divergence?.ahead ?? null,
+    behind: divergence?.behind ?? null,
+    warning: fetch2.warning
+  };
+}
 function pickModuleCycleBranch(candidates, cycleNumber, module, memberSlug) {
   if (candidates.length === 0) return void 0;
   const expected = cycleBranchName(cycleNumber, module, memberSlug);
@@ -1427,7 +1493,7 @@ function getRemoteBranchFiles(cwd, branch, baseBranch) {
     return [];
   }
 }
-var AUTO_WRITTEN_PATHS, GIT_NETWORK_TIMEOUT_MS, MERGE_RETRY_DELAY_MS, MERGE_MAX_RETRIES;
+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"() {
     "use strict";
@@ -1435,6 +1501,7 @@ var init_git = __esm({
     GIT_NETWORK_TIMEOUT_MS = 6e4;
     MERGE_RETRY_DELAY_MS = 2e3;
     MERGE_MAX_RETRIES = 3;
+    GIT_FETCH_TIMEOUT_MS = 5e3;
   }
 });
 

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)) {
@@ -850,7 +860,7 @@ var init_dist = __esm({
       { key: "editorRelease", label: "Editors release like the owner", description: "Lets editors run a full release instead of opening a contributor PR.", step: "release", defaultEnabled: false }
     ];
     CAPABILITY_KEYS = CAPABILITY_REGISTRY.map((c) => c.key);
-    ASSIGNABLE_CONTRIBUTOR_ROLES = ["editor", "viewer"];
+    ASSIGNABLE_CONTRIBUTOR_ROLES = ["release_manager", "editor", "viewer"];
     SENSITIVE_CHANGELOG_PATTERNS = [
       // ── Test-user machinery ────────────────────────────────────────────────
       /@test\.papi\.dev/i,
@@ -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)",
@@ -948,6 +959,7 @@ __export(git_exports, {
   checkoutBranch: () => checkoutBranch,
   commitSinglePath: () => commitSinglePath,
   commitStagedOnly: () => commitStagedOnly,
+  computeAheadBehind: () => computeAheadBehind,
   createAndCheckoutBranch: () => createAndCheckoutBranch,
   createPullRequest: () => createPullRequest,
   createTag: () => createTag,
@@ -958,8 +970,10 @@ __export(git_exports, {
   detectUnrecordedCommits: () => detectUnrecordedCommits,
   ensureLatestDevelop: () => ensureLatestDevelop,
   ensureTagAtHead: () => ensureTagAtHead,
+  fetchBaseBranch: () => fetchBaseBranch,
   findContributorReleasePullRequests: () => findContributorReleasePullRequests,
   findTaskCommitsOnBase: () => findTaskCommitsOnBase,
+  getBaseDivergence: () => getBaseDivergence,
   getBranchDiff: () => getBranchDiff,
   getCommitFiles: () => getCommitFiles,
   getCommitsSinceTag: () => getCommitsSinceTag,
@@ -994,6 +1008,7 @@ __export(git_exports, {
   hasUnpushedCommits: () => hasUnpushedCommits,
   isBranchContentAlreadyInBase: () => isBranchContentAlreadyInBase,
   isBranchMergedInto: () => isBranchMergedInto,
+  isCommitReachable: () => isCommitReachable,
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
   isGitRepo: () => isGitRepo,
@@ -2056,6 +2071,19 @@ function isBranchMergedInto(cwd, branch, baseBranch) {
     return false;
   }
 }
+function isCommitReachable(cwd, commit, baseBranch) {
+  const recordedCommit = commit.trim();
+  if (!recordedCommit) return false;
+  try {
+    execFileSync("git", ["merge-base", "--is-ancestor", recordedCommit, baseBranch], {
+      cwd,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isBranchContentAlreadyInBase(cwd, branch, baseBranch) {
   const resolveCommit = (ref) => {
     try {
@@ -2082,6 +2110,55 @@ function isBranchContentAlreadyInBase(cwd, branch, baseBranch) {
     return false;
   }
 }
+function fetchBaseBranch(cwd, baseBranch, timeoutMs = GIT_FETCH_TIMEOUT_MS) {
+  if (!isGitAvailable() || !isGitRepo(cwd) || !hasRemote(cwd)) {
+    return { fetched: false, compareRef: baseBranch };
+  }
+  const result = spawnSync("git", ["fetch", "--quiet", "origin", baseBranch], {
+    cwd,
+    encoding: "utf-8",
+    timeout: timeoutMs
+  });
+  if (result.error || result.status !== 0) {
+    const raw = result.error?.message ?? ((result.stderr || "").trim() || `git exited ${result.status}`);
+    const isTimeout = result.signal === "SIGTERM" || /ETIMEDOUT/.test(raw);
+    return {
+      fetched: false,
+      compareRef: baseBranch,
+      warning: isTimeout ? `Fetch from origin timed out after ${Math.round(timeoutMs / 1e3)}s \u2014 comparing against the local '${baseBranch}' ref, which may be stale.` : `Fetch from origin failed \u2014 comparing against the local '${baseBranch}' ref, which may be stale. (${raw})`
+    };
+  }
+  return { fetched: true, compareRef: `origin/${baseBranch}` };
+}
+function computeAheadBehind(cwd, compareRef, ref = "HEAD") {
+  try {
+    const out = execFileSync(
+      "git",
+      ["rev-list", "--left-right", "--count", `${compareRef}...${ref}`],
+      { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
+    ).trim();
+    const [behindStr, aheadStr] = out.split(/\s+/);
+    const behind = parseInt(behindStr, 10);
+    const ahead = parseInt(aheadStr, 10);
+    if (Number.isNaN(behind) || Number.isNaN(ahead)) return null;
+    return { ahead, behind };
+  } catch {
+    return null;
+  }
+}
+function getBaseDivergence(cwd, preferredBase, opts) {
+  const baseBranch = resolveBaseBranch(cwd, preferredBase);
+  const fetch2 = fetchBaseBranch(cwd, baseBranch, opts?.timeoutMs);
+  const divergence = computeAheadBehind(cwd, fetch2.compareRef, opts?.ref ?? "HEAD");
+  return {
+    baseBranch,
+    compareRef: fetch2.compareRef,
+    fetched: fetch2.fetched,
+    ahead: divergence?.ahead ?? null,
+    behind: divergence?.behind ?? null,
+    warning: fetch2.warning
+  };
+}
 function pickModuleCycleBranch(candidates, cycleNumber, module, memberSlug) {
   if (candidates.length === 0) return void 0;
   const expected = cycleBranchName(cycleNumber, module, memberSlug);
@@ -2186,7 +2263,7 @@ function getRemoteBranchFiles(cwd, branch, baseBranch) {
     return [];
   }
 }
-var AUTO_WRITTEN_PATHS, GIT_NETWORK_TIMEOUT_MS, MERGE_RETRY_DELAY_MS, MERGE_MAX_RETRIES;
+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"() {
     "use strict";
@@ -2194,6 +2271,7 @@ var init_git = __esm({
     GIT_NETWORK_TIMEOUT_MS = 6e4;
     MERGE_RETRY_DELAY_MS = 2e3;
     MERGE_MAX_RETRIES = 3;
+    GIT_FETCH_TIMEOUT_MS = 5e3;
   }
 });
 
@@ -7505,11 +7583,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}
+
+`, "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)
 
-${d.body}`).join("\n\n");
+${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.";
@@ -8314,6 +8459,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]
 
@@ -9649,6 +9797,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]
 
@@ -10193,7 +10344,7 @@ function isProjectOwner(callerUserId, ownerUserId) {
   if (caller.length === 0 || owner.length === 0) return false;
   return caller === owner;
 }
-var CYCLE_ROLES = ["owner", "editor"];
+var CYCLE_ROLES = ["owner", "release_manager", "editor"];
 async function resolveCycleGate(adapter2, gate) {
   if (!gate.enforced) return { allowed: true, role: null };
   if (gate.callerIsOwner) return { allowed: true, role: "owner" };
@@ -10218,6 +10369,13 @@ async function resolveCycleGate(adapter2, gate) {
     };
   }
 }
+function formatOwnerGateResolutionError(gate) {
+  if (!gate.resolutionError) return null;
+  if (gate.transport === "proxy") {
+    return "Hosted bearer identity could not be verified. Retry once connectivity is restored.";
+  }
+  return `Identity resolution failed (${gate.resolutionError}) \u2014 the gate fails closed. Retry once connectivity is restored.`;
+}
 async function resolveCallerUserId(adapter2, config2) {
   const gate = await resolveOwnerGate(adapter2, config2);
   if (gate.enforced && !gate.callerUserId) {
@@ -10229,7 +10387,7 @@ async function resolveOwnerGate(adapter2, config2) {
   if (adapterSupports(adapter2, "getOwnerIdentity")) {
     try {
       const identity = await adapter2.getOwnerIdentity();
-      const callerUserId = identity.callerUserId ?? config2.userId ?? null;
+      const callerUserId = identity.callerUserId ?? null;
       return {
         enforced: true,
         callerIsOwner: isProjectOwner(callerUserId, identity.ownerUserId),
@@ -10241,7 +10399,7 @@ async function resolveOwnerGate(adapter2, config2) {
       return {
         enforced: true,
         callerIsOwner: false,
-        callerUserId: config2.userId ?? null,
+        callerUserId: null,
         ownerUserId: null,
         resolutionError: err instanceof Error ? err.message : String(err),
         transport: "proxy"
@@ -10796,6 +10954,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) {
@@ -10810,9 +10985,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;
@@ -10828,9 +11001,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) {
@@ -10853,9 +11024,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;
   }
@@ -12193,11 +12362,11 @@ ${cleanContent}`;
       if (!task.buildHandoff) {
         await adapter2.updateTask?.(taskId, {
           buildHandoff: h.buildHandoff,
-          cycle: cycleNumber
+          cycle: newCycleNumber
         });
         repairedHandoffs.push(taskId);
-      } else if (task.cycle !== cycleNumber) {
-        await adapter2.updateTask?.(taskId, { cycle: cycleNumber });
+      } else if (task.cycle !== newCycleNumber) {
+        await adapter2.updateTask?.(taskId, { cycle: newCycleNumber });
         repairedCycles.push(taskId);
       }
     } catch {
@@ -17687,7 +17856,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",
@@ -17705,15 +17878,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"] }
       }
     ]
@@ -18018,13 +18202,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);
@@ -18037,25 +18226,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}).
@@ -20948,6 +21153,27 @@ async function resolveCycleToClose(adapter2, version, callerUserId) {
   }
   return inferCycleFromVersion(version);
 }
+async function findUnreachableDoneTaskCommits(config2, adapter2, cycleNumber, baseBranch) {
+  if (cycleNumber <= 0 || !adapter2.getBuildReportsSince) return { unreachable: [] };
+  const [tasks, reports] = await Promise.all([
+    adapter2.queryBoard({ cycleSince: cycleNumber, compact: true }),
+    adapter2.getBuildReportsSince(cycleNumber)
+  ]);
+  const doneTasks = tasks.filter((task) => task.cycle === cycleNumber && task.status === "Done");
+  const cycleReports = reports.filter((report) => report.cycle === cycleNumber && report.completed === "Yes");
+  const fetch2 = fetchBaseBranch(config2.projectRoot, baseBranch);
+  const unreachable = doneTasks.flatMap((task) => {
+    const report = cycleReports.filter((candidate) => candidate.taskId === task.id || candidate.taskId === task.displayId || candidate.displayId === task.displayId).filter((candidate) => Boolean(candidate.commitSha?.trim())).sort((a, b2) => {
+      const aDate = a.createdAt ?? a.date;
+      const bDate = b2.createdAt ?? b2.date;
+      return aDate.localeCompare(bDate);
+    }).at(-1);
+    const commitSha = report?.commitSha?.trim();
+    if (!commitSha || isCommitReachable(config2.projectRoot, commitSha, fetch2.compareRef)) return [];
+    return [{ taskId: task.displayId, commitSha }];
+  });
+  return { unreachable, fetchWarning: fetch2.warning };
+}
 async function closeCycleState(config2, adapter2, version, cycleNum, options) {
   const warnings = [];
   const force = options?.force ?? false;
@@ -21143,7 +21369,7 @@ async function contributorAutoPrRelease(config2, adapter2, version, productionBa
     const title = `Release ${version}: ${branch}`;
     const body = `Contributor release PR for cycle ${cycleNum || "?"} (\`${branch}\`).
 
-Opened by a non-owner editor via \`release\` (task-2244). The project owner reviews and merges this into \`${productionBaseBranch}\`; the contributor's own cycle is already marked complete in PAPI.`;
+Opened by a non-owner release-capable member via \`release\` (task-2244). The project owner reviews and merges this into \`${productionBaseBranch}\`; the contributor's own cycle is already marked complete in PAPI.`;
     const created = createPullRequest(config2.projectRoot, branch, productionBaseBranch, title, body);
     prs.push(
       created.success ? { branch, url: created.message.trim() || getPullRequestUrl(config2.projectRoot, branch) } : { branch, url: null, error: created.message }
@@ -21244,6 +21470,25 @@ async function createRelease(config2, branch, version, adapter2, cycleNum, optio
       }
     }
   }
+  if (adapter2 && resolvedCycleNum > 0) {
+    const resolvedBase = resolveBaseBranch(config2.projectRoot, branch);
+    const { unreachable, fetchWarning } = await findUnreachableDoneTaskCommits(
+      config2,
+      adapter2,
+      resolvedCycleNum,
+      resolvedBase
+    );
+    if (fetchWarning) warnings.push(fetchWarning);
+    if (unreachable.length > 0) {
+      const details = unreachable.map(({ taskId, commitSha }) => `  - ${taskId}: ${commitSha}`).join("\n");
+      throw new Error(
+        `Release blocked \u2014 ${unreachable.length} Done task implementation commit(s) are not reachable from ${resolvedBase}:
+${details}
+
+Merge the recorded commit into the release branch, or correct the build receipt before retrying release.`
+      );
+    }
+  }
   if (adapter2 && resolvedCycleNum > 0) {
     try {
       const stampedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -21589,6 +21834,7 @@ function sanitiseBranchSuffix(branch) {
   return branch.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 var CYCLE_UPDATES_CHANNEL_ENV = "DISCORD_CYCLE_UPDATES_CHANNEL_ID";
+var RELEASE_CAPABLE_ROLES = /* @__PURE__ */ new Set(["editor", "release_manager"]);
 function buildCycleUpdateCurationDirective(version, cycleClosed, projectChannelId) {
   const channelId = projectChannelId?.trim() || process.env[CYCLE_UPDATES_CHANNEL_ENV]?.trim();
   if (!channelId) return null;
@@ -21772,9 +22018,10 @@ async function handleRelease(adapter2, config2, args, clientName) {
       const editorsReleaseLikeOwner = isCapabilityEnabled(releaseCaps, "editorRelease");
       const cycleGate = editorsReleaseLikeOwner ? await resolveCycleGate(adapter2, gate) : { allowed: gate.callerIsOwner, role: gate.callerIsOwner ? "owner" : null };
       if (gate.enforced && !cycleGate.allowed) {
-        const resolutionNote = gate.resolutionError ? `
+        const resolutionMessage = formatOwnerGateResolutionError(gate);
+        const resolutionNote = resolutionMessage ? `
 
-Identity resolution failed (${gate.resolutionError}) \u2014 the gate fails closed. Retry once connectivity is restored.` : "";
+${resolutionMessage}` : "";
         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.
@@ -21788,17 +22035,18 @@ Then reconnect your AI tool and run release again. (Direct/pg setups read identi
         }
         tracker.mark("contributor-role-gate");
         const callerRole = adapter2.getContributorRole && gate.callerUserId ? await adapter2.getContributorRole(gate.callerUserId).catch(() => null) : null;
-        if (callerRole !== "editor") {
+        if (!RELEASE_CAPABLE_ROLES.has(callerRole ?? "")) {
           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;
+          const roleNote = callerRole === "viewer" ? `Your role on this project is "viewer", which cannot release. Ask the owner (or an editor or release manager) to release, or ask for release access.` : `Your identity does not match this project's owner, and you do not have an editor or release_manager role to open a release PR. If you are a contributor, ask the owner for editor or release_manager access (or push your branch and open a PR manually). ` + ownerHint;
           return errorResponse(
-            `Release to ${productionBaseBranch} needs an owner or editor role.
+            `Release to ${productionBaseBranch} needs an owner, editor, or release_manager role.
 
 ` + roleNote + `
 
 Releasing to a non-base branch (e.g. dev) is unaffected.` + resolutionNote
           );
         }
+        const releaseRole = callerRole === "release_manager" ? "release manager" : "editor";
         tracker.mark("contributor-pr-reconciliation");
         try {
           const reconciled = await reconcileContributorReleasePrs(config2, adapter2, gate.callerUserId, cycleToClose);
@@ -21833,7 +22081,7 @@ ${buildHostedGitDirective({
             return textResponse(
               `## Release ${version} \u2014 contributor PR merged
 
-PAPI detected that ${latest.prUrl} was merged on GitHub and reconciled the contributor release. GitHub granted the merge permission; your PAPI **editor** role granted the release workflow.
+PAPI detected that ${latest.prUrl} was merged on GitHub and reconciled the contributor release. GitHub granted the merge permission; your PAPI **${releaseRole}** role granted the release workflow.
 
 ${latest.cycle ? `Cycle ${latest.cycle}` : "The contributor cycle"} remains **complete**, and the release is now recorded as **released** in PAPI.` + localHandoff + `
 
@@ -21847,7 +22095,7 @@ Next: run \`plan\` to start your next cycle.`
 
 ${prLines}
 
-Your PAPI **editor** role allowed this release PR. Merge permission is controlled separately by GitHub: if GitHub lets you merge, review and merge it there; otherwise a repository maintainer must merge it.
+Your PAPI **${releaseRole}** role allowed this release PR. Merge permission is controlled separately by GitHub: if GitHub lets you merge, review and merge it there; otherwise a repository maintainer must merge it.
 
 After it is merged, run \`release\` again so PAPI can detect the merge and finish the release record.`
             );
@@ -21857,7 +22105,7 @@ After it is merged, run \`release\` again so PAPI can detect the merge and finis
         }
         if (isHostedTransport()) {
           return errorResponse(
-            `Release blocked \u2014 your PAPI editor role is valid, but this hosted connection cannot access your local checkout or GitHub CLI to open the release PR. Run release from a workspace-connected MCP client for this repository, or ask the project owner to release it.`
+            `Release blocked \u2014 your PAPI ${releaseRole} role is valid, but this hosted connection cannot access your local checkout or GitHub CLI to open the release PR. Run release from a workspace-connected MCP client for this repository, or ask the project owner to release it.`
           );
         }
         tracker.mark("contributor-auto-pr");
@@ -21877,7 +22125,7 @@ After it is merged, run \`release\` again so PAPI can detect the merge and finis
           return textResponse(
             `## Release ${version} \u2014 contributor PR opened
 
-You released as an **editor**, so PAPI opened a pull request to \`${productionBaseBranch}\` instead of merging directly. GitHub merge permission is separate from your PAPI role: merge it yourself if GitHub allows, otherwise a repository maintainer must merge it.
+You released as a **${releaseRole}**, so PAPI opened a pull request to \`${productionBaseBranch}\` instead of merging directly. GitHub merge permission is separate from your PAPI role: merge it yourself if GitHub allows, otherwise a repository maintainer must merge it.
 
 **Pull request(s):**
 ${prLines.join("\n")}
@@ -22929,13 +23177,18 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   if (!task) {
     throw new Error(`Task "${taskId}" not found on the Cycle Board.`);
   }
+  const branchLines = [];
+  const gate = await resolveOwnerGate(adapter2, config2);
   if (task.assigneeId) {
-    const gate = await resolveOwnerGate(adapter2, config2);
     if (!gate.callerUserId || gate.callerUserId !== task.assigneeId) {
       throw new Error(
         `Task "${taskId}" (${task.title}) is claimed by another member \u2014 only its assignee can build it. Have the claimer build it, or run \`task_unclaim\` to release it first.`
       );
     }
+  } else if (gate.enforced) {
+    branchLines.push(
+      `\u2139\uFE0F **${taskId}** has no assignee \u2014 this is an unclaimed pool task, buildable by anyone. Run \`task_claim\` first for exclusive ownership while you build it. (Not blocking.)`
+    );
   }
   if (task.status === "Done" || task.status === "Archived") {
     throw new Error(`Task "${taskId}" (${task.title}) is already ${task.status}. Cannot execute a completed task.`);
@@ -22973,7 +23226,6 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
     err.unresolvedDeps = unresolvedDeps;
     throw err;
   }
-  const branchLines = [];
   const startCaps = adapter2.getProjectInfo ? (await adapter2.getProjectInfo().catch(() => null))?.capabilities ?? {} : {};
   const autoBranchEnabled = isCapabilityEnabled(startCaps, "autoBranch");
   if (options.light) {
@@ -24656,6 +24908,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.";
@@ -24714,6 +25001,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);
@@ -24789,7 +25077,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);
@@ -27490,11 +27778,17 @@ async function recordAdHoc(adapter2, input) {
   const promoted = targetCycle !== null;
   const landInReview = held || promoted && input.stage === "release";
   let task;
+  const warnings = [];
   if (input.taskId) {
     const existing = await adapter2.getTask(input.taskId);
     if (!existing) {
       throw new Error(`Task "${input.taskId}" not found on the board. Check the task ID and try again.`);
     }
+    if (!existing.assigneeId) {
+      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.`
+      );
+    }
     const updatePayload = {
       notes: existing.notes ? `${existing.notes}
 [ad-hoc] ${input.notes || "Work recorded via ad_hoc"}` : `[ad-hoc] ${input.notes || "Work recorded via ad_hoc"}`
@@ -27565,7 +27859,7 @@ async function recordAdHoc(adapter2, input) {
     scopeAccuracy: "accurate"
   };
   await adapter2.appendBuildReport(report);
-  return { task, report };
+  return { task, report, warnings: warnings.length > 0 ? warnings : void 0 };
 }
 
 // src/tools/ad-hoc.ts
@@ -27776,6 +28070,7 @@ async function handleAdHoc(adapter2, config2, args) {
     } catch {
     }
   }
+  const warningsNote = result.warnings?.length ? "\n\n" + result.warnings.map((w) => `> ${w}`).join("\n") : "";
   const truncateWarning = notesTruncated ? ` (notes truncated to ${MAX_NOTES_LENGTH} chars)` : "";
   const taskModule = result.task.module || "Core";
   const typeLabel = result.task.taskType || typeRaw;
@@ -27808,7 +28103,7 @@ async function handleAdHoc(adapter2, config2, args) {
     } catch {
     }
     return textResponse(
-      `**${result.task.id}:** "${result.task.title}" held for review (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule})${overrideNote}.${truncateWarning}${promoNote} Build report attached.
+      `**${result.task.id}:** "${result.task.title}" held for review (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule})${overrideNote}.${truncateWarning}${promoNote} Build report attached.` + warningsNote + `
 
 ## Held for the next cycle \u2014 branch + commit, do NOT merge
 The task is recorded **In Review** and pinned to **Cycle ${result.task.cycle}**, so the planner won't re-plan it and it rides that cycle's review \u2192 release bundled with planned work.
@@ -27826,7 +28121,7 @@ _To correct: board_edit ${result.task.id} with updated fields._` + await recordA
     );
   }
   return textResponse(
-    `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule})${overrideNote}.${truncateWarning}${promoNote} Build report attached.
+    `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule})${overrideNote}.${truncateWarning}${promoNote} Build report attached.` + warningsNote + `
 _To correct: board_edit ${result.task.id} with updated fields._` + await recordAdHocProposal(adapter2, args, { cycleNumber: result.task.cycle ?? 0, sourceTaskId: result.task.id }) + await adHocDecisionSection(target, result.task)
   );
 }
@@ -29226,14 +29521,14 @@ ${overlap}`;
         const roleGate = await resolveCycleGate(adapter2, gate);
         const callerMayRelease = editorReleaseEnabled ? roleGate.allowed : !gate.enforced || gate.callerIsOwner;
         if (cycleTasks.length > 0 && cycleTasks.every((t) => t.status === "Done") && !callerMayRelease) {
-          const why = roleGate.role === "viewer" ? `your role on this project is "viewer"` : roleGate.role === "editor" && !editorReleaseEnabled ? `your "editor" role is valid, but this project keeps auto-release owner-only because "Editors release like the owner" is off` : `your role on this project could not be confirmed`;
+          const why = roleGate.role === "viewer" ? `your role on this project is "viewer"` : (roleGate.role === "editor" || roleGate.role === "release_manager") && !editorReleaseEnabled ? `your "${roleGate.role}" role is valid, but this project keeps auto-release owner-only because "Editors release like the owner" is off` : `your role on this project could not be confirmed`;
           const resolutionNote = roleGate.resolutionError ? ` (Role resolution failed: ${roleGate.resolutionError} \u2014 the gate fails closed.)` : "";
-          const nextStep = roleGate.role === "editor" && !editorReleaseEnabled ? `Run \`release\` explicitly to open your contributor PR.` : `Push your branch and open a PR, or ask for editor access.`;
+          const nextStep = (roleGate.role === "editor" || roleGate.role === "release_manager") && !editorReleaseEnabled ? `Run \`release\` explicitly to open your contributor PR.` : `Push your branch and open a PR, or ask for editor or release manager access.`;
           autoReleaseNote = `
 
 ---
 
-\u2705 Verdict recorded. All cycle tasks are Done, but no release was cut \u2014 **auto-release needs an owner or editor role**, and ${why}. ${nextStep}${resolutionNote}`;
+\u2705 Verdict recorded. All cycle tasks are Done, but no release was cut \u2014 **auto-release needs an owner, editor, or release manager role**, and ${why}. ${nextStep}${resolutionNote}`;
         } else if (cycleTasks.length > 0 && cycleTasks.every((t) => t.status === "Done")) {
           let planRunCount = null;
           if (adapterSupports(adapter2, "countPlanRunsForCycle")) {
@@ -31347,6 +31642,7 @@ async function getHierarchyPosition(adapter2, projectId) {
   }
 }
 var GIT_TAG_TIMEOUT_MS = 2e3;
+var ORIGIN_FETCH_TIMEOUT_MS = 3e3;
 async function checkNpmVersionDrift() {
   try {
     const pkgPath = join18(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
@@ -31563,6 +31859,17 @@ async function computePendingDecisionsWarning(adapter2, callerUserId, decisions)
   if (awaiting === 0) return void 0;
   return `\u{1F4CB} ${awaiting} decision${awaiting === 1 ? "" : "s"} awaiting your position \u2014 run \`ad_view\` then \`decision_resolve\` to agree/object/abstain.`;
 }
+function formatOriginDivergenceWarning(d) {
+  if (d.behind != null && d.behind > 0) {
+    const aheadNote = d.ahead && d.ahead > 0 ? ` (and ${d.ahead} ahead)` : "";
+    return `\u26A0\uFE0F This checkout is ${d.behind} commit${d.behind === 1 ? "" : "s"} behind \`origin/${d.baseBranch}\`${aheadNote} \u2014 pull before trusting "Done"/merged state here.`;
+  }
+  if (d.warning) return `\u2139\uFE0F ${d.warning}`;
+  if (d.fetched && d.behind == null) {
+    return `\u2139\uFE0F Could not determine how far this checkout is behind \`origin/${d.baseBranch}\` (e.g. a shallow clone) \u2014 treat "Done"/merged state here as unverified.`;
+  }
+  return void 0;
+}
 async function handleOrient(rawAdapter, config2, args = {}, clientName, serverVersion = "unknown") {
   let resolvedAdapter = rawAdapter;
   let projectOverrideNote = "";
@@ -31659,6 +31966,7 @@ async function handleOrient(rawAdapter, config2, args = {}, clientName, serverVe
       ttfvOutcome,
       latestTagOutcome,
       versionDriftOutcome,
+      originDivergenceOutcome,
       researchSignalsOutcome,
       recsOutcome,
       pendingReviewOutcome,
@@ -31813,6 +32121,18 @@ async function handleOrient(rawAdapter, config2, args = {}, clientName, serverVe
       // version-drift is enrichment, gated behind `full`/deep_housekeeping.
       tracked("git-tag", async () => getLatestTag(config2.projectRoot, GIT_TAG_TIMEOUT_MS)),
       tracked("npm-version-drift", async () => fullEnrichment ? checkNpmVersionDrift() : void 0),
+      // Nova/vibe-tycoon feedback (task-XXXX): how far is this checkout
+      // actually behind origin/<base>? Deliberately UNGATED by full/
+      // deep_housekeeping — runs on every orient call by default, because the
+      // fetch is bounded (ORIGIN_FETCH_TIMEOUT_MS) and fails soft. No remote
+      // configured is the common no-op case: zero network I/O, zero latency.
+      // Escape hatch mirrors PAPI_ORIENT_FANOUT_CONCURRENCY's env-var pattern,
+      // default ON (opposite polarity from deep_housekeeping's opt-in — this
+      // one must not require opting in).
+      tracked("origin-divergence", async () => {
+        if (!hasLocalWorkspace() || process.env.PAPI_ORIENT_ORIGIN_CHECK === "false") return void 0;
+        return getBaseDivergence(config2.projectRoot, config2.baseBranch, { timeoutMs: ORIGIN_FETCH_TIMEOUT_MS });
+      }),
       // Research Signals — research docs with pending actions since last strategy review.
       // task-2172: heavy (doc search + AD cross-reference) and rarely actioned
       // mid-session — gated behind `full`/deep_housekeeping to keep the default lean.
@@ -32010,6 +32330,9 @@ async function handleOrient(rawAdapter, config2, args = {}, clientName, serverVe
     if (proxyWarning) buildResult.warnings.push(proxyWarning);
     const p1Warning = p1BacklogOutcome.status === "fulfilled" ? p1BacklogOutcome.value : void 0;
     if (p1Warning) buildResult.warnings.push(p1Warning);
+    const originDivergence = originDivergenceOutcome.status === "fulfilled" ? originDivergenceOutcome.value : void 0;
+    const originDivergenceWarning = originDivergence ? formatOriginDivergenceWarning(originDivergence) : void 0;
+    if (originDivergenceWarning) buildResult.warnings.push(originDivergenceWarning);
     const pendingDecisionsWarning = pendingDecisionsOutcome.status === "fulfilled" ? pendingDecisionsOutcome.value : void 0;
     if (pendingDecisionsWarning) buildResult.warnings.push(pendingDecisionsWarning);
     const ownerActionsWarning = ownerActionsOutcome.status === "fulfilled" ? ownerActionsOutcome.value : void 0;
@@ -32144,7 +32467,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 + 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);
@@ -33350,7 +33708,7 @@ async function resolveDecisionAuthority(adapter2, gate, decisionType) {
     allowed: isQuorumEligible,
     role,
     isOwnerOverride: false,
-    ...isQuorumEligible ? {} : { resolutionError: "only owner/editor members participate in group resolution" }
+    ...isQuorumEligible ? {} : { resolutionError: "only owner/release_manager/editor members participate in group resolution" }
   };
 }
 function normaliseMode(value) {
@@ -33398,14 +33756,14 @@ var decisionResolveTool = {
       action: {
         type: "string",
         enum: ["agree", "object", "abstain", "resolve", "withdraw"],
-        description: 'agree/object/abstain cast your own position on a proposed decision. resolve/withdraw transition the decision itself and require authority \u2014 owner-only in "owner" mode, the configured resolver (or owner override) in "per_type" mode, or full owner/editor quorum (or an owner force-resolve) in "group" mode.'
+        description: 'agree/object/abstain cast your own position on a proposed decision. resolve/withdraw transition the decision itself and require authority \u2014 owner-only in "owner" mode, the configured resolver (or owner override) in "per_type" mode, or full owner/release_manager/editor quorum (or an owner force-resolve) in "group" mode.'
       },
       comment: { type: "string", description: "Optional note recorded alongside your position or transition." }
     },
     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);
 }
@@ -33438,7 +33796,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(
@@ -33475,7 +33833,7 @@ async function handleDecisionResolve(adapter2, config2, args) {
           positions.map((p) => ({ userId: p.userId, status: p.status })),
           quorumMembersFrom(contributors)
         );
-        quorumNote = quorum.met ? '\n\nEvery owner/editor member has now agreed or abstained \u2014 this decision is ready to `decision_resolve action="resolve"`.' : `
+        quorumNote = quorum.met ? '\n\nEvery owner/release_manager/editor member has now agreed or abstained \u2014 this decision is ready to `decision_resolve action="resolve"`.' : `
 
 Still waiting on: ${quorum.missing.length > 0 ? quorum.missing.join(", ") : "nobody"}${quorum.objected.length > 0 ? `; objected: ${quorum.objected.join(", ")}` : ""}.`;
       } catch {
@@ -34027,7 +34385,7 @@ Mapping after: ${mappingAfter}`
 init_dist();
 var contributorAddTool = {
   name: "contributor_add",
-  description: `Add a contributor to a project by email, or change an existing member's role (owner-only). The person must already have a PAPI account. Grants membership on project_contributors. Pass role="editor" for a working teammate who needs to run the full cycle \u2014 the default, "viewer", cannot release. Calling it again with a different role promotes or demotes that member.`,
+  description: `Add a contributor to a project by email, or change an existing member's role (owner-only). The person must already have a PAPI account. Grants membership on project_contributors. Pass role="release_manager" for a teammate who owns approved releases, or role="editor" for a working teammate who needs to run the full cycle \u2014 the default, "viewer", is read-only. Calling it again with a different role promotes or demotes that member.`,
   annotations: { title: "Add Contributor", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -34036,7 +34394,7 @@ var contributorAddTool = {
       role: {
         type: "string",
         enum: [...ASSIGNABLE_CONTRIBUTOR_ROLES],
-        description: `Membership role. "editor" can run the full build/review/release cycle; "viewer" has read-only visibility and is REFUSED by the release gate. Defaults to "viewer" for a new member; omit it when changing nothing to leave an existing member's role untouched. Project ownership cannot be granted here.`
+        description: `Membership role. "release_manager" can run the build/review cycle and carry approved releases through the release path; "editor" can run the full build/review/release cycle; "viewer" has read-only visibility. Defaults to "viewer" for a new member; omit it when changing nothing to leave an existing member's role untouched. Project ownership cannot be granted here.`
       },
       project: {
         type: "string",
@@ -34084,7 +34442,8 @@ async function denyUnlessOwner(adapter2, config2) {
   if (capDenied) return capDenied;
   const gate = await resolveOwnerGate(adapter2, config2);
   if (gate.enforced && !gate.callerIsOwner) {
-    const note = gate.resolutionError ? ` (Identity resolution failed: ${gate.resolutionError} \u2014 the gate fails closed; retry once connectivity is restored.)` : "";
+    const resolutionMessage = formatOwnerGateResolutionError(gate);
+    const note = resolutionMessage ? ` (${resolutionMessage})` : "";
     return `Contributor management is restricted to the project owner. Your identity does not match this project's owner.${note}`;
   }
   return null;
@@ -34097,7 +34456,8 @@ async function denyUnlessMember(adapter2, config2) {
   if (gate.callerIsOwner) return null;
   const callerRole = gate.callerUserId && adapterSupports(adapter2, "getContributorRole") ? await adapter2.getContributorRole(gate.callerUserId).catch(() => null) : null;
   if (callerRole) return null;
-  const note = gate.resolutionError ? ` (Identity resolution failed: ${gate.resolutionError} \u2014 the gate fails closed; retry once connectivity is restored.)` : "";
+  const resolutionMessage = formatOwnerGateResolutionError(gate);
+  const note = resolutionMessage ? ` (${resolutionMessage})` : "";
   return `Listing contributors is restricted to project members. Your identity does not match this project's owner or any contributor.${note}`;
 }
 var EMAIL_SHAPE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -34132,7 +34492,7 @@ async function handleContributorAdd(adapter2, config2, args) {
 
 ${upsell}` : "";
     const where = overrideNote ? ` ${overrideNote}` : " on this project";
-    const roleLine = entry.role === "editor" ? `They can run the full cycle \u2014 plan, build, review and release.` : `**They are a "${entry.role}" and cannot run \`release\`.** Re-run with role="editor" if they are a working teammate rather than an observer.`;
+    const roleLine = entry.role === "release_manager" ? `They can run the build/review cycle and carry approved releases through the release path.` : entry.role === "editor" ? `They can run the full cycle \u2014 plan, build, review and release.` : `**They are a "${entry.role}" and cannot run \`release\`.** Re-run with role="editor" or role="release_manager" if they need to work on the project.`;
     return textResponse(
       `\u2705 **${entry.email ?? email}**${name} is now a **${entry.role}**${where}.
 

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.98",
-  "description": "PAPI MCP server \u2014 AI-powered sprint planning, build execution, and strategy review for software projects",
+  "version": "0.7.104",
+  "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",