@papi-ai/server 0.7.84 → 0.7.85

package/dist/index.js

@@ -73,11 +73,20 @@ function resolveDeploymentProfile(env) {
     }
   };
 }
+function isNoneLeadProse(trimmed) {
+  const m = NONE_LEAD_RE.exec(trimmed);
+  if (!m) return false;
+  if (/\bP[0-3]\s*[:—–-]/.test(trimmed)) return false;
+  const rest = (m.groups?.rest ?? "").replace(/^[-•]\s*/, "").trim();
+  if (CONTRAST_LEAD_RE.test(rest)) return false;
+  return true;
+}
 function splitFindings(raw, kind) {
   if (!raw) return [];
   const trimmed = raw.trim();
   if (trimmed.length === 0 || NONE_RE.test(trimmed)) return [];
   if (kind !== "issue" && AD_HOC_PLACEHOLDER_RE.test(trimmed)) return [];
+  if (isNoneLeadProse(trimmed)) return [];
   const chunks = trimmed.split(/\n+/).flatMap((line) => line.split(/(?=\bP[0-3]\s*[:—-])/)).map((s) => s.trim()).filter((s) => s.length > 0 && !NONE_RE.test(s));
   const items = [];
   for (const chunk of chunks) {
@@ -760,7 +769,7 @@ function parsePhaseBlock(block) {
   if (isNaN(order)) return null;
   return { id, slug, label, description, status, order };
 }
-var CAPABILITY_REGISTRY, CAPABILITY_KEYS, ASSIGNABLE_CONTRIBUTOR_ROLES, SENSITIVE_CHANGELOG_PATTERNS, CONTRIBUTOR_PRICING_URL, HOSTED_APP_URL, HOSTED_MCP_URL, HOSTED_SUPABASE_URL, SEVERITY_ORDER, NONE_RE, AD_HOC_PLACEHOLDER_RE, MIN_REASON_LENGTH, LOW_SEVERITIES, WAB_WINDOW_DAYS, WAB_DEFAULT_WEEKS, WAB_WEEK_MS, PRODUCT_MARKER, MECHANICS_MARKER, CHECK_VALUE_MAX, VALID_EFFORT_SIZES, SECTION_HEADERS, VALID_EFFORT_SIZES2, EFFORT_SCALE, NONE_PATTERN, NONE_PATTERN2, VALID_STATUSES, PHASES_START, PHASES_END;
+var CAPABILITY_REGISTRY, CAPABILITY_KEYS, ASSIGNABLE_CONTRIBUTOR_ROLES, SENSITIVE_CHANGELOG_PATTERNS, CONTRIBUTOR_PRICING_URL, HOSTED_APP_URL, HOSTED_MCP_URL, HOSTED_SUPABASE_URL, SEVERITY_ORDER, NONE_RE, AD_HOC_PLACEHOLDER_RE, NONE_LEAD_RE, CONTRAST_LEAD_RE, MIN_REASON_LENGTH, LOW_SEVERITIES, WAB_WINDOW_DAYS, WAB_DEFAULT_WEEKS, WAB_WEEK_MS, PRODUCT_MARKER, MECHANICS_MARKER, CHECK_VALUE_MAX, VALID_EFFORT_SIZES, SECTION_HEADERS, VALID_EFFORT_SIZES2, EFFORT_SCALE, NONE_PATTERN, NONE_PATTERN2, VALID_STATUSES, PHASES_START, PHASES_END;
 var init_dist = __esm({
   "../shared/dist/index.js"() {
     "use strict";
@@ -800,7 +809,21 @@ var init_dist = __esm({
       { key: "autoBranch", label: "Auto branch", description: "Creates a feature branch per task/cycle at build start.", step: "build" },
       { key: "autoCommit", label: "Auto commit", description: "Commits your work automatically when a build completes.", step: "build" },
       { key: "autoPush", label: "Auto push & PR", description: "Pushes the branch and opens a pull request on build complete.", step: "build" },
-      { key: "papiMetaFraming", label: "PAPI self-referential framing", description: "Includes PAPI-meta build-discipline framing in handoff output.", step: "build" }
+      { key: "papiMetaFraming", label: "PAPI self-referential framing", description: "Includes PAPI-meta build-discipline framing in handoff output.", step: "build" },
+      // Editor-equal release. Two legitimate team shapes need opposite answers, so
+      // this is a PROJECT policy rather than a global rule:
+      //
+      //   OFF (default) — an editor's release opens a CONTRIBUTOR PR and PAPI records
+      //     the release when GitHub merges it. Right for an open//multi-contributor
+      //     product where the project owner is the last gate before production.
+      //   ON — an editor releases on exactly the owner's path. Right for a small team
+      //     of trusted peers who each run whole cycles end to end, where routing every
+      //     close back through one person is the bottleneck, not the safeguard.
+      //
+      // Defaults OFF so existing projects are byte-identical, and because widening who
+      // can ship to production must be a deliberate choice, never a silent upgrade.
+      // A VIEWER is denied either way — this moves the editor line only.
+      { 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"];
@@ -852,6 +875,8 @@ var init_dist = __esm({
     };
     NONE_RE = /^(none|n\/a|no(ne)? (found|discovered))\.?$/i;
     AD_HOC_PLACEHOLDER_RE = /^none\s*[—–-]\s*ad[-\s]?hoc work\.?$/i;
+    NONE_LEAD_RE = /^(none|n\/a|no(ne)? (found|discovered))\s*[.,:;—–-]\s*(?<rest>.*)$/is;
+    CONTRAST_LEAD_RE = /^(but|however|although|though|except|aside from|other than|besides)\b/i;
     MIN_REASON_LENGTH = 12;
     LOW_SEVERITIES = /* @__PURE__ */ new Set(["P2", "P3"]);
     WAB_WINDOW_DAYS = 7;
@@ -907,6 +932,7 @@ __export(git_exports, {
   detectUnrecordedCommits: () => detectUnrecordedCommits,
   ensureLatestDevelop: () => ensureLatestDevelop,
   ensureTagAtHead: () => ensureTagAtHead,
+  findContributorReleasePullRequests: () => findContributorReleasePullRequests,
   findTaskCommitsOnBase: () => findTaskCommitsOnBase,
   getBranchDiff: () => getBranchDiff,
   getCommitFiles: () => getCommitFiles,
@@ -924,6 +950,7 @@ __export(git_exports, {
   getOriginRepoSlug: () => getOriginRepoSlug,
   getOriginUrl: () => getOriginUrl,
   getPathsDifferingFrom: () => getPathsDifferingFrom,
+  getPullRequestState: () => getPullRequestState,
   getPullRequestUrl: () => getPullRequestUrl,
   getRemoteBranchFiles: () => getRemoteBranchFiles,
   getRootCommitHash: () => getRootCommitHash,
@@ -1887,6 +1914,56 @@ function getPullRequestUrl(cwd, branch) {
     return null;
   }
 }
+function getPullRequestState(cwd, prUrl) {
+  try {
+    const output = execFileSync(
+      "gh",
+      ["pr", "view", prUrl, "--json", "url,state,mergedAt"],
+      { cwd, encoding: "utf-8" }
+    ).trim();
+    if (!output) return null;
+    const parsed = JSON.parse(output);
+    if (!parsed.url || !["OPEN", "CLOSED", "MERGED"].includes(parsed.state ?? "")) return null;
+    return {
+      url: parsed.url,
+      state: parsed.state,
+      mergedAt: parsed.mergedAt ?? null
+    };
+  } catch {
+    return null;
+  }
+}
+function findContributorReleasePullRequests(cwd, cycle) {
+  if (!Number.isInteger(cycle) || cycle <= 0) return [];
+  try {
+    const output = execFileSync(
+      "gh",
+      [
+        "pr",
+        "list",
+        "--state",
+        "all",
+        "--limit",
+        "20",
+        "--search",
+        `"Contributor release PR for cycle ${cycle}" in:body`,
+        "--json",
+        "url,state,mergedAt,headRefName"
+      ],
+      { cwd, encoding: "utf-8" }
+    ).trim();
+    if (!output) return [];
+    const parsed = JSON.parse(output);
+    return parsed.flatMap((pr) => pr.url && pr.headRefName && ["OPEN", "CLOSED", "MERGED"].includes(pr.state ?? "") ? [{
+      url: pr.url,
+      state: pr.state,
+      mergedAt: pr.mergedAt ?? null,
+      branch: pr.headRefName
+    }] : []);
+  } catch {
+    return [];
+  }
+}
 function squashMergePullRequest(cwd, branch) {
   const repo = getOriginRepoSlug(cwd);
   const baseArgs = ["pr", "merge", branch, "--squash", "--delete-branch"];
@@ -2320,6 +2397,10 @@ var init_proxy_adapter = __esm({
       "dismissRecommendation",
       "findPendingDocActionsForTask",
       "getActiveDecisions",
+      "getContributorRole",
+      "listContributorReleasePrs",
+      "recordContributorReleasePr",
+      "setContributorReleasePrStatus",
       "getActiveStage",
       "getBuildReportCountForTask",
       "getBuildReportsSince",
@@ -2459,7 +2540,7 @@ var init_proxy_adapter = __esm({
       "applyActiveDecisionUpdates",
       // getToolCallCount + updatePhaseStatus are ABSENT: they now have edge handlers and
       // are served through the forwarder (getToolCallCount = SUP-2026-026 handler #1).
-      "getContributorRole",
+      // getContributorRole is edge-wired and binds identity from the bearer.
       // task-3018 (C356): storeDocBody + getDocBodyUsage are now WIRED — edge case
       // handlers + ALLOWED_METHODS/WRITE_METHODS entries exist, so they forward and
       // hosted callers get body storage. Removed from this list, as task-3017 required.
@@ -2467,9 +2548,6 @@ var init_proxy_adapter = __esm({
       // of the owner-action queue. Six readers were wired C329 (task-2412) but the
       // producer stayed here, so the hosted Owner Action Queue was structurally empty
       // (AD-74 inverted). Now forwards; the edge binds user_id to the bearer ([C]).
-      "recordContributorReleasePr",
-      "setContributorReleasePrStatus",
-      "listContributorReleasePrs",
       "claimReview",
       "getSiblingAds",
       "getSiblingRepoTasks",
@@ -3185,8 +3263,8 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       getCycleLearningPatterns() {
         return this.invoke("getCycleLearningPatterns", []);
       }
-      updateCycleLearningActionRef(learningId, taskDisplayId) {
-        return this.invoke("updateCycleLearningActionRef", [learningId, taskDisplayId]);
+      updateCycleLearningActionRef(learningId, taskDisplayId, opts) {
+        return this.invoke("updateCycleLearningActionRef", [learningId, taskDisplayId, opts ?? {}]);
       }
       // --- Strategy Review Drafts ---
       savePendingReviewResponse(cycleNumber, rawResponse) {
@@ -3292,7 +3370,11 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
        */
       async getMeteredUsage() {
         const body = await this.postRoute("metering", {});
-        return { tier: body.tier ?? "free", monthlyToolCalls: body.monthlyToolCalls ?? 0 };
+        return {
+          tier: body.tier ?? "free",
+          monthlyToolCalls: body.monthlyToolCalls ?? 0,
+          projectLimitOverride: body.projectLimitOverride ?? null
+        };
       }
       async listUserProjects() {
         const body = await this.postRoute("project-list", {});
@@ -6404,7 +6486,7 @@ async function runSetup() {
     log(`Project: ${result.project_slug}`);
   }
   log("");
-  log(`Done. Open Claude Code in this folder and say "run setup" to scaffold your first plan.`);
+  log(`Done. Open your AI client in this folder and say "run setup" to scaffold your first plan.`);
   return 0;
 }
 var DEFAULT_BASE_URL, MAX_POLL_SECONDS, NETWORK_RETRY_LIMIT;
@@ -6512,7 +6594,7 @@ function loadConfig() {
 ${conflicting} is set in your environment, but PAPI_DATA_API_KEY is also set \u2014
 you have a hosted PAPI account, so the database URL is being ignored anyway.
 
-Fix: \`unset ${conflicting}\` (and PAPI_ADAPTER if also set) before starting Claude Code,
+Fix: \`unset ${conflicting}\` (and PAPI_ADAPTER if also set) before starting your AI client,
 or remove it from your shell rc file (~/.zshrc, ~/.bashrc).
 
 If you intentionally self-host, set PAPI_SELF_HOST=1 in your environment to bypass this guard.`
@@ -6957,7 +7039,7 @@ Fix the PAPI_PROJECT_ID in your .mcp.json (or unset it and let PAPI resolve the
 Get started in 3 steps:
   1. Sign up at ${dashboardUrl ? `${dashboardUrl}/login` : "your configured PAPI dashboard"}
   2. Complete the onboarding wizard \u2014 it generates your .mcp.json config
-  3. Download the config, place it in your project root, and restart Claude Code
+  3. Download the config, place it in your project root, and restart your AI client
 
 Already have an account? Make sure PAPI_DATA_API_KEY is set in your .mcp.json env config.`
         );
@@ -7883,7 +7965,11 @@ The guard above says what to reject. This says what to propose. Rejecting is not
 
 **Copy variants are NEVER decisions.** A tagline, a headline, a value proposition, a piece of marketing or product wording: swapping one for another constrains no future work, so it fails test (b) outright. Wording changes as often as the market teaches you something, and routing every edit through decision ceremony is what buries the handful of decisions that genuinely constrain the project. Edit the wording where the wording lives. If two variants are being compared against a measurement, that is an experiment, not a decision.
 
-**A decision decaying into a convention is the healthy path, not a failure.** When a live AD stops being arguable \u2014 the alternatives are no longer on the table and nobody would re-litigate it \u2014 say so during housekeeping and propose retiring it into a convention. An AD registry where most entries are settled is one nobody reads.`;
+**A decision decaying into a convention is the healthy path, not a failure.** When a live AD stops being arguable \u2014 the alternatives are no longer on the table and nobody would re-litigate it \u2014 propose demoting it during housekeeping with \`action: "demote"\`. An AD registry where most entries are settled is one nobody reads.
+
+DEMOTION IS THE THIRD TRANSITION, and it is not either of the other two. \`supersede\` replaces a stance with a NEW one; \`delete\` removes something that was never a decision. \`demote\` is for a decision that was RIGHT and still holds \u2014 it keeps riding every build handoff as a convention and simply stops occupying decision surface. Apply test (c) to each live AD: could a competent person argue the other side TODAY, on current evidence? If no, propose \`demote\` and give the one-line reason it is no longer contested.
+
+PROPOSE, NEVER ASSUME. A demotion is a judgement about whether something is still arguable, and the owner is the one who knows. Surface candidates with reasoning and let the human confirm on apply, exactly as board corrections and cancellations are gated. Do not demote in bulk to tidy the registry.`;
 var AD_CONFLICT_SURFACING_RULES = `**A contradiction is NOT a veto \u2014 surface it, never silently shelve it.**
 
 Active Decisions are *active*: they can be superseded, modified, or abandoned. You do NOT have authority to kill a piece of work simply because it cuts against one. That is the user's call, and they can only make it if you show it to them.
@@ -8870,7 +8956,7 @@ After your natural language output, include this EXACT format on its own line:
   "activeDecisionUpdates": [
     {
       "id": "string \u2014 AD-N (existing) or new AD-N (for new decisions)",
-      "action": "confidence_change | modify | resolve | supersede | new | delete",
+      "action": "confidence_change | modify | resolve | supersede | new | delete | demote",
       "body": "string \u2014 full AD block including ### heading, confidence tag, and body text (empty string for delete)",
       "evidenceRef": "string (optional) \u2014 for DELIBERATE decisions (modify / resolve / delete = validate/modify/invalidate), a pointer to the evidence that justified the change: a doc path (docs/research/foo.md), a build-report id, or a metric name. Builds the decision->outcome ledger. Omit if no concrete evidence.",
       "metricDelta": "object (optional) \u2014 { "metric": string, "before": number, "after": number, "delta": number } \u2014 which metric moved and by how much. Use a REAL metric name from cycle_metrics_snapshots where possible (e.g. scope_accuracy, velocity, est_actual_drift). Omit if no metric moved."
@@ -9122,7 +9208,7 @@ After your natural language output, include this EXACT format on its own line:
   "activeDecisionUpdates": [
     {
       "id": "string \u2014 AD-N (existing) or new AD-N (for new decisions)",
-      "action": "confidence_change | modify | resolve | supersede | new | delete",
+      "action": "confidence_change | modify | resolve | supersede | new | delete | demote",
       "body": "string \u2014 full AD block including ### heading, confidence tag, and body text (empty string for delete)",
       "evidenceRef": "string (optional) \u2014 for DELIBERATE changes (modify / resolve / delete), a pointer to the justifying evidence: a doc path, a build-report id, or a metric name. Builds the decision->outcome ledger. Omit if none.",
       "metricDelta": "object (optional) \u2014 { "metric": string, "before": number, "after": number, "delta": number } \u2014 which metric moved. Prefer a real metric name from cycle_metrics_snapshots. Omit if none."
@@ -9633,13 +9719,20 @@ async function getPrompt(name) {
 }
 
 // src/lib/foundation.ts
-var cache2 = null;
+var cache2 = /* @__PURE__ */ new Map();
 var CACHE_TTL_MS2 = 5 * 60 * 1e3;
+var UNKNOWN_PROJECT_KEY = "\0unknown-project";
+function cacheKeyFor(adapter2) {
+  const id = adapter2.getProjectId?.();
+  return id && id.length > 0 ? id : UNKNOWN_PROJECT_KEY;
+}
 var MAX_TOKENS = 800;
 var MAX_CHARS = MAX_TOKENS * 4;
 async function buildProjectFoundation(adapter2) {
   const now = Date.now();
-  if (cache2 && cache2.expiresAt > now) return cache2.content;
+  const cacheKey = cacheKeyFor(adapter2);
+  const hit = cache2.get(cacheKey);
+  if (hit && hit.expiresAt > now) return hit.content;
   const [briefRaw, decisions, northStar, horizons, stages] = await Promise.all([
     safe(() => adapter2.readProductBrief(), ""),
     safe(() => adapter2.getActiveDecisions(), []),
@@ -9661,7 +9754,7 @@ async function buildProjectFoundation(adapter2) {
   const userType = extractUserType(briefRaw);
   if (userType) lines.push(`Primary user: ${userType}`);
   if (lines.length === 0) {
-    cache2 = { content: "", expiresAt: now + CACHE_TTL_MS2 };
+    cache2.set(cacheKey, { content: "", expiresAt: now + CACHE_TTL_MS2 });
     return "";
   }
   const body = lines.join("\n");
@@ -9674,7 +9767,7 @@ ${body}
 [/project_foundation]
 
 ` : block;
-  cache2 = { content: final, expiresAt: now + CACHE_TTL_MS2 };
+  cache2.set(cacheKey, { content: final, expiresAt: now + CACHE_TTL_MS2 });
   return final;
 }
 async function safe(fn, fallback) {
@@ -10191,7 +10284,7 @@ function titleMap(entities) {
   const map = /* @__PURE__ */ new Map();
   for (const e of entities) {
     if (!e.title) continue;
-    for (const key of [e.id, e.displayId]) {
+    for (const key of [e.id, e.displayId, e.uuid]) {
       if (!key) continue;
       map.set(key, e.title);
       map.set(key.toLowerCase(), e.title);
@@ -10199,6 +10292,14 @@ function titleMap(entities) {
   }
   return map;
 }
+function formatEntityRef(value, entities) {
+  const needle = value.toLowerCase();
+  const match = entities.find(
+    (e) => e.uuid?.toLowerCase() === needle || e.id?.toLowerCase() === needle || e.displayId?.toLowerCase() === needle
+  );
+  if (!match) return formatRef(value, lookupTitle(value, titleMap(entities)));
+  return formatRef(match.displayId || match.id || value, match.title);
+}
 
 // src/lib/blocker.ts
 function idMatches(candidate, ref) {
@@ -10363,6 +10464,31 @@ function isProjectOwner(callerUserId, ownerUserId) {
   if (caller.length === 0 || owner.length === 0) return false;
   return caller === owner;
 }
+var CYCLE_ROLES = ["owner", "editor"];
+async function resolveCycleGate(adapter2, gate) {
+  if (!gate.enforced) return { allowed: true, role: null };
+  if (gate.callerIsOwner) return { allowed: true, role: "owner" };
+  if (!gate.callerUserId) {
+    return {
+      allowed: false,
+      role: null,
+      resolutionError: gate.resolutionError ?? "no caller identity could be resolved"
+    };
+  }
+  if (!adapterSupports(adapter2, "getContributorRole")) {
+    return { allowed: false, role: null, resolutionError: "role lookup is unavailable on this transport" };
+  }
+  try {
+    const role = await adapter2.getContributorRole(gate.callerUserId);
+    return { allowed: role != null && CYCLE_ROLES.includes(role), role: role ?? null };
+  } catch (err) {
+    return {
+      allowed: false,
+      role: null,
+      resolutionError: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
 async function resolveOwnerGate(adapter2, config2) {
   if (adapterSupports(adapter2, "getOwnerIdentity")) {
     try {
@@ -10428,6 +10554,48 @@ function normalizeComplexity(value) {
   const key = (value ?? "").trim().toUpperCase();
   return COMPLEXITY_ALIASES[key] ?? "Small";
 }
+var PRIORITY_ALIASES = {
+  "P0": "P0 Critical",
+  "P1": "P1 High",
+  "P2": "P2 Medium",
+  "P3": "P3 Low",
+  "CRITICAL": "P0 Critical",
+  "URGENT": "P0 Critical",
+  "HIGH": "P1 High",
+  "MEDIUM": "P2 Medium",
+  "MED": "P2 Medium",
+  "LOW": "P3 Low",
+  "P0 CRITICAL": "P0 Critical",
+  "P1 HIGH": "P1 High",
+  "P2 MEDIUM": "P2 Medium",
+  "P3 LOW": "P3 Low"
+};
+function resolvePriority(value) {
+  const key = (value ?? "").trim().toUpperCase();
+  if (!key) return "P1 High";
+  return PRIORITY_ALIASES[key] ?? null;
+}
+function normalizePriority(value) {
+  return resolvePriority(value) ?? "P1 High";
+}
+function validateNewTaskVocab(tasks) {
+  const problems = [];
+  for (const t of tasks) {
+    const name = t.title?.trim() || "(untitled task)";
+    if (resolvePriority(t.priority) === null) {
+      problems.push(
+        `"${name}": priority "${t.priority}" is not one of P0 Critical / P1 High / P2 Medium / P3 Low`
+      );
+    }
+    const cx = (t.complexity ?? "").trim();
+    if (cx && !COMPLEXITY_ALIASES[cx.toUpperCase()]) {
+      problems.push(
+        `"${name}": complexity "${t.complexity}" is not one of XS / Small / Medium / Large / XL`
+      );
+    }
+  }
+  return problems;
+}
 var PLAN_BUILD_REPORT_BUDGET = { maxReports: 12, fieldBudget: 280 };
 function leadChainWithRecommended(chain, recommendedTaskId) {
   const rec = recommendedTaskId?.trim();
@@ -10444,10 +10612,7 @@ async function resolvePlanScope(adapter2, config2) {
 }
 function filterToPersonalBacklog(tasks, scope) {
   if (!scope.callerUserId) return tasks;
-  if (scope.callerIsOwner) {
-    return tasks.filter((t) => !t.assigneeId || t.assigneeId === scope.callerUserId);
-  }
-  return tasks.filter((t) => t.assigneeId === scope.callerUserId);
+  return tasks.filter((t) => !t.assigneeId || t.assigneeId === scope.callerUserId);
 }
 function determineContextTier(cycleCount) {
   if (cycleCount <= 5) return 1;
@@ -11411,6 +11576,14 @@ function applyCancellationGuard(corrections, confirmCancellations) {
 async function transactionalWriteBack(adapter2, cycleNumber, data, contextHashes, options = {}) {
   const writeBackTimer = startTimer();
   const newCycleNumber = cycleNumber + 1;
+  const vocabProblems = validateNewTaskVocab(data.newTasks ?? []);
+  if (vocabProblems.length > 0) {
+    throw new Error(
+      `plan apply refused before writing: ${vocabProblems.length} task(s) use values the board does not accept.
+` + vocabProblems.map((p) => `  - ${p}`).join("\n") + `
+Nothing was written \u2014 no cycle was created and no tasks were changed. Correct these values in the plan output and re-run apply.`
+    );
+  }
   const skippedCancellations = [];
   const cleanTitle = data.cycleLogTitle.replace(/^(?:Cycle|Session)\s+\d+\s*—\s*/i, "").trim();
   const cleanContent = data.cycleLogContent.replace(/^#{1,3}\s+(?:Cycle|Session)\s+\d+\s*—[^\n]*\n*/i, "").trim();
@@ -11517,7 +11690,7 @@ ${cleanContent}`;
       // task-2242: stable handoff join key
       title: t.title,
       status: t.status || "Backlog",
-      priority: t.priority || "P1 High",
+      priority: normalizePriority(t.priority),
       complexity: normalizeComplexity(t.complexity),
       module: t.module || "Core",
       epic: t.epic || "Platform",
@@ -11665,7 +11838,7 @@ ${cleanContent}`;
         displayId: "",
         title: task.title,
         status: task.status || "Backlog",
-        priority: task.priority || "P1 High",
+        priority: normalizePriority(task.priority),
         complexity: normalizeComplexity(task.complexity),
         module: task.module || "Core",
         epic: task.epic || "Platform",
@@ -11967,7 +12140,7 @@ async function validateAndPrepare(adapter2, force, callerUserId, adapterType) {
   try {
     const health = await adapter2.getCycleHealth();
     cycleNumber = health.totalCycles;
-    mode = determineMode(health.totalCycles);
+    mode = determineMode(health.projectCycleCount ?? health.totalCycles);
     const blockingCycle = callerUserId ? await resolveCallerLatestCycle(adapter2, callerUserId) : void 0;
     const latestStatus = callerUserId ? blockingCycle?.status : health.latestCycleStatus;
     const blockingNumber = blockingCycle?.number ?? cycleNumber;
@@ -14977,6 +15150,29 @@ function asDecisionBatchApplier(adapter2) {
   const candidate = adapter2;
   return typeof candidate.applyActiveDecisionUpdates === "function" ? candidate : void 0;
 }
+async function demoteDecisionToConvention(ad, adapter2, cycleNumber, warnings) {
+  if (!adapter2.createConvention) {
+    warnings.push(
+      `AD ${ad.id}: demotion skipped \u2014 this adapter cannot create conventions, and retiring the decision without writing the rule would lose the stance entirely. Left live.`
+    );
+    return false;
+  }
+  const rule = ad.body.trim();
+  if (!rule) {
+    warnings.push(`AD ${ad.id}: demotion skipped \u2014 empty body, nothing to carry into a convention. Left live.`);
+    return false;
+  }
+  try {
+    await adapter2.createConvention({ rule });
+  } catch (err) {
+    warnings.push(
+      `AD ${ad.id}: demotion skipped \u2014 writing the convention failed (${err instanceof Error ? err.message : String(err)}). The decision is left live rather than retired with nothing to replace it.`
+    );
+    return false;
+  }
+  await adapter2.updateActiveDecision(ad.id, ad.body, cycleNumber, "demote");
+  return true;
+}
 function routeDecisionUpdate(ad, adapter2, cycleNumber, warnings) {
   const action = ad.action;
   let route;
@@ -15723,7 +15919,10 @@ ${cleanContent}`;
       });
       if (data.activeDecisionUpdates && data.activeDecisionUpdates.length > 0) {
         for (const ad of data.activeDecisionUpdates) {
-          if (ad.action === "delete" && adapter2.deleteActiveDecision) {
+          if (ad.action === "demote") {
+            const demoted = await demoteDecisionToConvention(ad, adapter2, cycleNumber, evidenceWarnings);
+            if (!demoted) continue;
+          } else if (ad.action === "delete" && adapter2.deleteActiveDecision) {
             await adapter2.deleteActiveDecision(ad.id);
           } else if (ad.action === "new" && adapter2.upsertActiveDecision) {
             const titleMatch = ad.body.match(/^###\s+\S+:\s*([^\n[]+?)(?:\s*\[|$)/m);
@@ -17237,11 +17436,13 @@ async function handleBoardEdit(adapter2, args) {
         } else {
           const health = await target.getCycleHealth().catch(() => null);
           const activeCycle = health?.totalCycles ?? null;
-          const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-          const stamp = activeCycle != null ? `[C${activeCycle} ${date}]` : `[${date}]`;
+          const stampedAt = (/* @__PURE__ */ new Date()).toISOString().slice(0, 16).replace("T", " ");
+          const stamp = activeCycle != null ? `[C${activeCycle} ${stampedAt} UTC]` : `[${stampedAt} UTC]`;
           const entry = `${stamp} ${trimmed}`;
           updates.notes = existing.trim().length > 0 ? `${entry}
 
+---
+
 ${existing}` : entry;
         }
       }
@@ -20071,6 +20272,47 @@ To override, pass force=true (emits a telemetry warning).`
   }
   return { resolvedCycleNum, warnings, force, skipVersion };
 }
+async function reconcileContributorReleasePrs(config2, adapter2, callerUserId, cycle) {
+  if (!callerUserId || !adapter2?.listContributorReleasePrs || !adapter2.setContributorReleasePrStatus) {
+    return { merged: [], open: [] };
+  }
+  const records = await adapter2.listContributorReleasePrs();
+  let own = records.filter((record) => record.contributorUserId === callerUserId);
+  if (own.length === 0 && cycle && adapter2.recordContributorReleasePr) {
+    const discovered = findContributorReleasePullRequests(config2.projectRoot, cycle);
+    for (const pr of discovered) {
+      await adapter2.recordContributorReleasePr({
+        prUrl: pr.url,
+        branch: pr.branch,
+        cycle,
+        contributorUserId: callerUserId
+      });
+    }
+    own = discovered.map((pr, index) => ({
+      id: `discovered-${index}`,
+      contributorUserId: callerUserId,
+      prUrl: pr.url,
+      branch: pr.branch,
+      cycle,
+      status: "open",
+      createdAt: pr.mergedAt ?? "",
+      updatedAt: pr.mergedAt ?? ""
+    }));
+  }
+  const merged = [];
+  const open = [];
+  for (const record of own) {
+    const discoveredState = findContributorReleasePullRequests(config2.projectRoot, record.cycle ?? 0).find((pr) => pr.url === record.prUrl);
+    const state = discoveredState ?? getPullRequestState(config2.projectRoot, record.prUrl);
+    if (state?.state === "MERGED") {
+      await adapter2.setContributorReleasePrStatus(record.prUrl, "merged");
+      merged.push({ prUrl: record.prUrl, branch: record.branch, cycle: record.cycle });
+    } else if (state?.state === "OPEN") {
+      open.push({ prUrl: record.prUrl, branch: record.branch, cycle: record.cycle });
+    }
+  }
+  return { merged, open };
+}
 async function contributorAutoPrRelease(config2, adapter2, version, productionBaseBranch, options) {
   if (!isGhAvailable()) {
     throw new Error(
@@ -20589,8 +20831,18 @@ async function postReleaseToX(version, cycleClosed) {
 }
 function buildHostedReleaseOutput(params) {
   const { version, branch, cyclePart, warningsBlock, skipVersion } = params;
+  const handoff = buildHostedGitHandoff({ version, branch, skipVersion });
+  return `## Release ${version}${skipVersion ? " (skip version)" : ""} \u2014 cycle closed in the DB
+
+${cyclePart} is now marked **complete** in PAPI's database, so \`orient\` will no longer flag "Release has not been run."
+` + warningsBlock + `
+${handoff}
+
+Next: cycle closed! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`;
+}
+function buildHostedGitHandoff(params) {
+  const { version, branch, skipVersion } = params;
   const tagAnnotation = `Release ${version}`;
-  const titleSuffix = skipVersion ? " (skip version)" : "";
   const gitHalf = skipVersion ? "the git half of the release (the CHANGELOG.md commit and the branch push) must run on your own machine" : "the git half of the release (tag, push, CHANGELOG.md) must run on your own machine";
   const commands = skipVersion ? `git checkout ${branch}
 git pull
@@ -20607,17 +20859,13 @@ git -c user.name="Your Name" -c user.email="you@example.com" tag -a ${version} -
 \`\`\`
 
 `;
-  return `## Release ${version}${titleSuffix} \u2014 cycle closed in the DB
-
-${cyclePart} is now marked **complete** in PAPI's database, so \`orient\` will no longer flag "Release has not been run."
-` + warningsBlock + `
-The hosted remote MCP transport (mcp.getpapi.ai) has no checkout of your project and no git binary, so ${gitHalf}.
+  return `The hosted remote MCP transport (mcp.getpapi.ai) has no checkout of your project and no git binary, so ${gitHalf}.
 
 Finish the release locally:
 \`\`\`
 ` + commands + `\`\`\`
 
-` + identityBlock + `Next: cycle closed! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`;
+` + identityBlock.trimEnd();
 }
 var releaseTool = {
   name: "release",
@@ -20705,7 +20953,16 @@ async function handleRelease(adapter2, config2, args) {
     await beginRelease(tracker, cycleToClose);
     const productionBaseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
     if (branch === productionBaseBranch) {
-      if (gate.enforced && !gate.callerIsOwner) {
+      let releaseCaps = {};
+      try {
+        const info = adapter2.getProjectInfo ? await adapter2.getProjectInfo() : null;
+        releaseCaps = info?.capabilities ?? {};
+      } catch {
+        releaseCaps = {};
+      }
+      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 ? `
 
 Identity resolution failed (${gate.resolutionError}) \u2014 the gate fails closed. Retry once connectivity is restored.` : "";
@@ -20726,13 +20983,62 @@ Then reconnect your AI tool and run release again. (Direct/pg setups read identi
           const ownerHint = gate.transport === "pg" ? `If you ARE the owner, set PAPI_USER_ID to your account UUID in .mcp.json (getpapi.ai \u2192 Settings \u2192 Account).` : `If you ARE the owner, your identity comes from your API key \u2014 check you are using YOUR key for YOUR project.`;
           const roleNote = callerRole === "viewer" ? `Your role on this project is "viewer", which cannot release. Ask the owner (or an editor) to release, or ask for editor access.` : `Your identity does not match this project's owner, and you do not have an editor role to open a release PR. If you are a contributor, ask the owner for editor access (or push your branch and open a PR manually). ` + ownerHint;
           return errorResponse(
-            `Release to ${productionBaseBranch} is restricted to the project owner.
+            `Release to ${productionBaseBranch} needs an owner or editor role.
 
 ` + roleNote + `
 
 Releasing to a non-base branch (e.g. dev) is unaffected.` + resolutionNote
           );
         }
+        tracker.mark("contributor-pr-reconciliation");
+        try {
+          const reconciled = await reconcileContributorReleasePrs(config2, adapter2, gate.callerUserId, cycleToClose);
+          if (reconciled.merged.length > 0) {
+            const latest = reconciled.merged[0];
+            let caps2 = {};
+            try {
+              const info = adapter2.getProjectInfo ? await adapter2.getProjectInfo() : null;
+              caps2 = info?.capabilities ?? {};
+            } catch {
+              caps2 = {};
+            }
+            await recordReadinessVerified(tracker);
+            await recordQualityGate(tracker, evaluateReleaseGate(caps2, config2.gateCommand, gateResult), caps2);
+            await completeRelease(tracker, {
+              cycleClosed: latest.cycle,
+              version,
+              caps: caps2,
+              branchMerges: latest.branch ? [{ branch: latest.branch, prUrl: latest.prUrl }] : [],
+              changelogEmitted: false
+            });
+            const localHandoff = isHostedTransport() ? `
+
+${buildHostedGitHandoff({ version, branch, skipVersion: skipVersion ?? false })}` : "";
+            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.
+
+${latest.cycle ? `Cycle ${latest.cycle}` : "The contributor cycle"} remains **complete**, and the release is now recorded as **released** in PAPI.` + localHandoff + `
+
+Next: run \`plan\` to start your next cycle.`
+            );
+          }
+          if (reconciled.open.length > 0) {
+            const prLines = reconciled.open.map((p) => `- ${p.prUrl}`).join("\n");
+            return textResponse(
+              `## Release ${version} \u2014 contributor PR awaiting merge
+
+${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.
+
+After it is merged, run \`release\` again so PAPI can detect the merge and finish the release record.`
+            );
+          }
+        } catch (err) {
+          console.error(`[release] contributor PR reconciliation failed (non-blocking): ${err instanceof Error ? err.message : String(err)}`);
+        }
         tracker.mark("contributor-auto-pr");
         try {
           const cr = await contributorAutoPrRelease(config2, adapter2, version, productionBaseBranch, {
@@ -20748,9 +21054,9 @@ Releasing to a non-base branch (e.g. dev) is unaffected.` + resolutionNote
 \u26A0\uFE0F Warnings: ${cr.warnings.join("; ")}
 ` : "";
           return textResponse(
-            `## Release ${version} \u2014 PR opened for owner review
+            `## Release ${version} \u2014 contributor PR opened
 
-You released as an **editor**, so PAPI opened a pull request to \`${productionBaseBranch}\` instead of merging directly. The owner reviews and merges it.
+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.
 
 **Pull request(s):**
 ${prLines.join("\n")}
@@ -20760,7 +21066,7 @@ ${failLines.join("\n")}
 ` : "") + warnBlock + `
 ${cyclePart} is now marked **complete** in PAPI \u2014 your work is shipped from your side. Any changes the owner requests come forward as a fast-follow in your next cycle; your closed cycle is not rewound.
 
-Next: run \`plan\` to start your next cycle.`
+After the PR is merged, run \`release\` again so PAPI can reconcile it.`
           );
         } catch (err) {
           return errorResponse(err instanceof Error ? err.message : String(err));
@@ -23149,8 +23455,19 @@ function isPaidTier(tier) {
 }
 async function enforceProjectCap(adapter2, target) {
   if (isSelfHostedDeployment(process.env.PAPI_SELF_HOST)) return null;
-  const tier = await resolveTier(adapter2);
-  if (tier === null || isPaidTier(tier)) return null;
+  let entitlement = null;
+  if (adapterSupports(adapter2, "getMeteredUsage")) {
+    try {
+      entitlement = await adapter2.getMeteredUsage();
+    } catch {
+      return null;
+    }
+  }
+  if (!entitlement) return null;
+  const override = entitlement.projectLimitOverride;
+  if (override === 0) return null;
+  const effectiveLimit = typeof override === "number" && Number.isInteger(override) && override > 0 ? override : FREE_PROJECT_CAP;
+  if (override == null && isPaidTier(entitlement.tier)) return null;
   if (!adapterSupports(adapter2, "listUserProjects")) return null;
   let projects;
   try {
@@ -23162,17 +23479,20 @@ async function enforceProjectCap(adapter2, target) {
     (p) => target.papiDir && p.papi_dir && p.papi_dir === target.papiDir || target.name && p.name && p.name.trim().toLowerCase() === target.name.trim().toLowerCase()
   );
   if (matchesExisting) return null;
-  if (projects.length >= FREE_PROJECT_CAP) return projectCapMessage(projects.length);
+  if (projects.length >= effectiveLimit) {
+    return projectCapMessage(projects.length, effectiveLimit, entitlement.tier);
+  }
   return null;
 }
 async function resolveContributorUpsell(adapter2) {
   const tier = await resolveTier(adapter2);
   return evaluateContributorGate(tier).upsell ?? null;
 }
-function projectCapMessage(currentCount) {
-  return `**You're on the Free plan (${currentCount} of ${FREE_PROJECT_CAP} projects).**
+function projectCapMessage(currentCount, limit = FREE_PROJECT_CAP, tier = "free") {
+  const nextStep = isPaidTier(tier) ? "request more projects" : "upgrade to Pro or request more projects";
+  return `**You've reached your account project limit (${currentCount} of ${limit} projects).**
 
-Free covers up to ${FREE_PROJECT_CAP} projects. To run more, upgrade to Pro for unlimited projects at a flat monthly price (no usage bills): ${PRICING_URL}
+Your account currently covers up to ${limit} projects. To run more, ${nextStep} at a flat monthly price (no usage bills): ${PRICING_URL}
 
 Your existing projects are untouched, and you can keep working in any of them.`;
 }
@@ -23351,14 +23671,24 @@ Diagnostic JSON:
 ${JSON.stringify(payload, null, 2)}`
   );
 }
-function ensureDocDurable(path7, projectRoot) {
+function ensureDocDurable(path7, projectRoot, bodyStored = false) {
   if (!hasLocalWorkspace() || !projectRoot) return "";
-  const warn = (reason, fix) => `
+  const warn = (reason, fix) => {
+    if (bodyStored) {
+      return `
+- **Not in git:** ${reason} The body is stored in the registry, so it survives a branch switch or stash; the file on disk is not version-controlled.`;
+    }
+    return `
 
 \u26A0\uFE0F **Registered, but NOT durable.** ${reason}
 The registry stores metadata and a summary \u2014 not the body. This doc has one copy, on disk, and a branch switch or stash can take it.
 **Fix:** ${fix}`;
+  };
   if (!existsSync9(join13(projectRoot, path7))) {
+    if (bodyStored) {
+      return `
+- **No file at \`${path7}\`:** the body is stored in the registry, but nothing is on disk at the registered path. Write it there so readers resolve it.`;
+    }
     return warn(
       `No file exists at \`${path7}\`.`,
       `write the doc body to that path, then re-run doc_register.`
@@ -23375,7 +23705,11 @@ The registry stores metadata and a summary \u2014 not the body. This doc has one
   if (isPathIgnored(projectRoot, path7)) {
     return warn(
       `\`${path7}\` is excluded by .gitignore, so it cannot be committed (docs/private/ is ignored by design).`,
-      `keep a copy outside the working tree, or move the doc to a tracked folder if it is not owner-only.`
+      // task-3358: no longer suggests moving the doc to a tracked folder. For anything
+      // under docs/private/ that flips resolveDocVisibility off the private tier and
+      // fails the no-private-artifacts gate — advising a leak to fix a durability gap.
+      // Only reachable now when the body was NOT stored, where a copy is the real fix.
+      `pass \`body\` to doc_register so the registry stores the content, or keep a copy outside the working tree.`
     );
   }
   const result = commitSinglePath(projectRoot, path7, `docs: register ${path7}`);
@@ -23468,6 +23802,7 @@ async function handleDocRegister(adapter2, args, config2) {
       visibility
     });
     let bodyNote = "";
+    let bodyIsStored = false;
     try {
       const supplied = typeof args.body === "string" ? args.body : void 0;
       let body = supplied;
@@ -23498,6 +23833,7 @@ ${decision.message}`;
             visibility: entry.visibility ?? visibility,
             ownerUserId: entry.ownerUserId
           });
+          bodyIsStored = true;
           bodyNote = result.stored ? `
 - **Body stored:** ${result.byteSize.toLocaleString()} bytes` : "\n- **Body:** unchanged since last registration";
         }
@@ -23508,7 +23844,7 @@ ${decision.message}`;
     const visibilityLabel = entry.visibility === "contributors" ? "team member" : entry.visibility ?? "private";
     let durability = "";
     try {
-      durability = ensureDocDurable(entry.path, config2?.projectRoot);
+      durability = ensureDocDurable(entry.path, config2?.projectRoot, bodyIsStored);
     } catch {
       durability = "";
     }
@@ -24225,19 +24561,106 @@ function formatListItem(task) {
   }
   return base;
 }
+var AD_KEYWORD_STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "but",
+  "not",
+  "you",
+  "all",
+  "any",
+  "can",
+  "has",
+  "had",
+  "was",
+  "are",
+  "its",
+  "our",
+  "out",
+  "off",
+  "own",
+  "via",
+  "per",
+  "use",
+  "get",
+  "set",
+  "new",
+  "old",
+  "one",
+  "two",
+  "now",
+  "why",
+  "how",
+  "who",
+  "let",
+  "may",
+  "yet",
+  "too",
+  "from",
+  "that",
+  "this",
+  "with",
+  "into",
+  "when",
+  "then",
+  "than",
+  "them",
+  "they",
+  "their",
+  "there",
+  "here",
+  "have",
+  "been",
+  "were",
+  "will",
+  "would",
+  "should",
+  "could",
+  "make",
+  "made",
+  "more",
+  "most",
+  "less",
+  "only",
+  "also",
+  "just",
+  "like",
+  "over",
+  "some",
+  "such",
+  "each",
+  "both",
+  "does",
+  "done",
+  "stop",
+  "keep",
+  "take",
+  "give",
+  "work",
+  "thing",
+  "things",
+  "about",
+  "after",
+  "before"
+]);
 function filterRelevantADs(ads, task) {
+  const live = ads.filter((ad) => !ad.superseded);
   const keywords = [];
   if (task.module) keywords.push(task.module.toLowerCase());
   if (task.epic) keywords.push(task.epic.toLowerCase());
   if (task.phase) keywords.push(task.phase.toLowerCase());
-  const titleWords = (task.title ?? task.displayId ?? "").toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+  const titleWords = (task.title ?? task.displayId ?? "").toLowerCase().split(/[^a-z0-9-]+/).filter((w) => w.length > 2 && !AD_KEYWORD_STOPWORDS.has(w));
   keywords.push(...titleWords);
-  if (keywords.length === 0) return [];
-  return ads.filter((ad) => {
-    if (ad.superseded) return false;
+  const matches = keywords.length === 0 ? [] : live.filter((ad) => {
     const text = `${ad.title} ${ad.body}`.toLowerCase();
     return keywords.some((kw) => text.includes(kw));
   });
+  const selected = [...matches];
+  for (const ad of live) {
+    if (ad.confidence === "HIGH" && !selected.includes(ad)) selected.push(ad);
+  }
+  return { ads: selected, matched: matches.length, total: live.length };
 }
 async function getModuleContext(adapter2, task) {
   if (!task.module) return "";
@@ -24263,9 +24686,18 @@ async function getModuleContext(adapter2, task) {
     return "";
   }
 }
-function formatRelevantADs(ads) {
-  if (ads.length === 0) return "";
+function formatRelevantADs(ads, stats) {
+  if (ads.length === 0 && !stats) return "";
   const lines = ["\n\n---\n\n**ACTIVE DECISIONS (relevant):**"];
+  if (stats) {
+    lines.push(
+      `_${stats.matched} of ${stats.total} active decisions matched this task's keywords${ads.length > stats.matched ? `; HIGH-confidence decisions are always included` : ""}. Keyword matching is approximate \u2014 an absent decision has not been ruled out._`
+    );
+  }
+  if (ads.length === 0) {
+    lines.push("\n_No active decisions matched. This is a filter result, not a statement that none apply._");
+    return lines.join("\n");
+  }
   for (const ad of ads) {
     const bodyLines = ad.body.split("\n").filter((l) => l.trim() && !l.startsWith("#"));
     const summary = bodyLines[0]?.trim().slice(0, 120) ?? "";
@@ -24446,7 +24878,7 @@ If >80% of the scope is already implemented, call \`build_execute\` with complet
     try {
       const allADs = await adapter2.getActiveDecisions();
       const relevant = filterRelevantADs(allADs, result.task);
-      adSection = formatRelevantADs(relevant);
+      adSection = formatRelevantADs(relevant.ads, { matched: relevant.matched, total: relevant.total });
     } catch {
     }
     let dogfoodSection = "";
@@ -25990,6 +26422,21 @@ async function recordAdHoc(adapter2, input) {
 var VALID_EFFORTS = ["XS", "S", "M", "L", "XL"];
 var VALID_PRIORITIES = ["P0 Critical", "P1 High", "P2 Medium", "P3 Low"];
 var VALID_TYPES = ["task", "bug", "research", "discovery", "spike", "idea"];
+var AD_HOC_CONFLICT_GATE_INSTRUCTION = "\n**AD conflict gate:** This work is already done. If any of it cuts against a decision above, say so now \u2014 add a `task_comment` on this task, or pass `proposal` to record the boundary as its own Decision or Convention. A conflict noticed here and not written down is one nobody can find later. A contradiction is not a veto \u2014 surfacing it is the owner's call to make, not yours to skip.";
+async function adHocDecisionSection(adapter2, task) {
+  try {
+    const allADs = await adapter2.getActiveDecisions();
+    const relevant = filterRelevantADs(allADs, task);
+    if (relevant.total === 0) return "";
+    const section = formatRelevantADs(relevant.ads, {
+      matched: relevant.matched,
+      total: relevant.total
+    });
+    return section.replace(AD_CONFLICT_GATE_INSTRUCTION, AD_HOC_CONFLICT_GATE_INSTRUCTION);
+  } catch {
+    return "";
+  }
+}
 function inferTaskType(description) {
   const lower = description.toLowerCase();
   if (/\bfix\b|bug|error|crash|broken|regression|defect/.test(lower)) return "bug";
@@ -26216,12 +26663,12 @@ The task is recorded **In Review** and pinned to **Cycle ${result.task.cycle}**,
    \`\`\`
 2. Leave the branch **unmerged** \u2014 it is picked up by the next cycle's \`release\`.
 
-_To correct: board_edit ${result.task.id} with updated fields._` + await recordAdHocProposal(adapter2, args, { cycleNumber: result.task.cycle ?? 0, sourceTaskId: result.task.id })
+_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)
     );
   }
   return textResponse(
     `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule})${overrideNote}.${truncateWarning}${promoNote} Build report attached.
-_To correct: board_edit ${result.task.id} with updated fields._` + await recordAdHocProposal(adapter2, args, { cycleNumber: result.task.cycle ?? 0, sourceTaskId: result.task.id })
+_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)
   );
 }
 
@@ -27595,14 +28042,23 @@ ${overlap}`;
         const allTasks = await adapter2.queryBoard();
         const cycleTasks = allTasks.filter((t) => t.cycle === result.currentCycle);
         const gate = await resolveOwnerGate(adapter2, config2);
-        const callerIsOwner = !gate.enforced || gate.callerIsOwner;
-        if (cycleTasks.length > 0 && cycleTasks.every((t) => t.status === "Done") && !callerIsOwner) {
-          const resolutionNote = gate.resolutionError ? ` (Identity resolution failed: ${gate.resolutionError} \u2014 the gate fails closed; the owner can run \`release\` directly.)` : "";
+        let releaseCaps = {};
+        try {
+          const info = adapter2.getProjectInfo ? await adapter2.getProjectInfo() : null;
+          releaseCaps = info?.capabilities ?? {};
+        } catch {
+          releaseCaps = {};
+        }
+        const cycleGate = isCapabilityEnabled(releaseCaps, "editorRelease") ? await resolveCycleGate(adapter2, gate) : { allowed: !gate.enforced || gate.callerIsOwner, role: gate.callerIsOwner ? "owner" : null };
+        const callerMayRelease = cycleGate.allowed;
+        if (cycleTasks.length > 0 && cycleTasks.every((t) => t.status === "Done") && !callerMayRelease) {
+          const why = cycleGate.role === "viewer" ? `your role on this project is "viewer"` : `your role on this project could not be confirmed`;
+          const resolutionNote = cycleGate.resolutionError ? ` (Role resolution failed: ${cycleGate.resolutionError} \u2014 the gate fails closed.)` : "";
           autoReleaseNote = `
 
 ---
 
-\u2705 Verdict recorded. All cycle tasks are Done, but **auto-release is owner-only** \u2014 your identity does not match this project's owner, so no release was cut. Push your branch and open a PR for the owner to run \`release\`.${resolutionNote}`;
+\u2705 Verdict recorded. All cycle tasks are Done, but no release was cut \u2014 **auto-release needs an owner or editor role**, and ${why}. Push your branch and open a PR, or ask for editor access.${resolutionNote}`;
         } else if (cycleTasks.length > 0 && cycleTasks.every((t) => t.status === "Done")) {
           let planRunCount = null;
           if (adapterSupports(adapter2, "countPlanRunsForCycle")) {
@@ -27856,7 +28312,7 @@ import { access as access2, readFile as readFile5, writeFile as writeFile3 } fro
 import path5 from "path";
 var initTool = {
   name: "init",
-  description: "Write the MCP config file that connects this project to PAPI. Generates .mcp.json (Claude Code default) or the equivalent for Cursor, VS Code, Windsurf, OpenCode, Amazon Q, Kilo Code, Gemini CLI, Codex CLI, or Hermes Agent. Config-only \u2014 does not create any project data. Run this first, then run `setup` to create your PAPI project.",
+  description: "Write the MCP config file that connects this project to PAPI. Generates .mcp.json, or the equivalent for whichever MCP client you use \u2014 Claude Code, Cursor, VS Code, Windsurf, OpenCode, Amazon Q, Kilo Code, Gemini CLI, Codex CLI, or Hermes Agent. Config-only \u2014 does not create any project data. Run this first, then run `setup` to create your PAPI project.",
   annotations: { title: "Initialise Project", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -29300,6 +29756,13 @@ var orientTool = {
       full: {
         type: "boolean",
         description: "Run the heavy enrichment blocks that the lean default path skips: Research Signals (doc search) and npm version-drift. Default false \u2014 the lean path keeps the per-session query count down so orient stays well under the tool timeout on large projects. Implied automatically when deep_housekeeping is true."
+      },
+      // SUP-2026-027: orient stopped multi-project accounts asking which project
+      // to use, while declaring no way to answer — the caller could not pass one
+      // without the schema advertising it. Same contract as board_view / bug.
+      project: {
+        type: "string",
+        description: "Project id (UUID) or slug to orient on, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: []
@@ -29402,7 +29865,7 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
     lines.push(`**Connection:** ${statusIcon} ${statusLabel}`);
     lines.push("");
   }
-  if (projectRoot) {
+  if (projectRoot && hasLocalWorkspace()) {
     const modeLine = formatWorkspaceModeLine(resolveWorkspaceMode(projectRoot));
     if (modeLine) {
       lines.push(modeLine);
@@ -29768,7 +30231,8 @@ async function computeCohortVisibility(adapter2, config2, contributorsInput) {
   } catch {
     return void 0;
   }
-  if (gate.enforced && !gate.callerIsOwner) return void 0;
+  const cycleGate = await resolveCycleGate(adapter2, gate);
+  if (!cycleGate.allowed) return void 0;
   let tasks;
   try {
     tasks = await adapter2.queryBoard({ compact: true });
@@ -29851,7 +30315,21 @@ function withBoardMemo(adapter2) {
   });
 }
 async function handleOrient(rawAdapter, config2, args = {}, clientName, serverVersion = "unknown") {
-  const adapter2 = withBoardMemo(rawAdapter);
+  let resolvedAdapter = rawAdapter;
+  let projectOverrideNote = "";
+  try {
+    ({ adapter: resolvedAdapter, overrideNote: projectOverrideNote } = await resolvePerCallProjectAdapter(
+      rawAdapter,
+      args
+    ));
+  } catch (err) {
+    if (err instanceof ProjectResolutionError) return errorResponse(err.message);
+    throw err;
+  }
+  const projectOverrideLine = projectOverrideNote ? `_Project override${projectOverrideNote}_
+
+` : "";
+  const adapter2 = withBoardMemo(resolvedAdapter);
   const environment = normaliseEnvironment(args.environment);
   const deepHousekeeping = args.deep_housekeeping === true;
   const fullEnrichment = args.full === true || deepHousekeeping;
@@ -30398,7 +30876,7 @@ ${section}`;
     const runtimeIdentityNote = `
 
 ${formatRuntimeIdentity(getRuntimeIdentity(config2, serverVersion))}`;
-    return { ...textResponse(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 };
+    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 };
   } 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);
@@ -31501,7 +31979,6 @@ function readLlmResponse(args) {
 
 // src/tools/ad-view.ts
 function adColumns(all) {
-  const titles = titleMap(all);
   return [
     { name: "id", header: "AD", value: (d) => d.id },
     { name: "title", header: "Title", value: (d) => d.title },
@@ -31510,7 +31987,7 @@ function adColumns(all) {
     {
       name: "supersededBy",
       header: "Superseded By",
-      value: (d) => d.supersededBy ? formatRef(d.supersededBy, lookupTitle(d.supersededBy, titles)) : "-"
+      value: (d) => d.supersededBy ? formatEntityRef(d.supersededBy, all) : "-"
     },
     { name: "body", header: "Body", value: (d) => d.body.replace(/\s+/g, " ").trim() }
   ];
@@ -31520,7 +31997,7 @@ function supersededNote(d, all) {
   if (!d.superseded) return "";
   const by = d.supersededBy;
   if (!by) return " [SUPERSEDED by unknown]";
-  return ` [SUPERSEDED by ${formatRef(by, lookupTitle(by, titleMap(all)))}]`;
+  return ` [SUPERSEDED by ${formatEntityRef(by, all)}]`;
 }
 function formatAdBody(d, all) {
   return `## ${d.id}: ${d.title} [${d.confidence}]${supersededNote(d, all)}
@@ -31737,7 +32214,10 @@ async function handleLearningAction(adapter2, args) {
     if (!learningId?.trim()) return errorResponse('learning_id is required for mode "mark".');
     if (!actionTaken) return errorResponse('action_taken is required for mode "mark".');
     try {
-      await adapter2.updateCycleLearningActionRef(learningId.trim(), actionRef?.trim() ?? actionTaken);
+      await adapter2.updateCycleLearningActionRef(learningId.trim(), actionRef?.trim() ?? actionTaken, {
+        actionTaken,
+        force: true
+      });
       return textResponse(
         `Learning \`${learningId}\` marked as **${actionTaken}**${actionRef ? ` \u2192 \`${actionRef}\`` : ""}.`
       );
@@ -32693,7 +33173,7 @@ var inflightWork = /* @__PURE__ */ new Map();
 var ToolTimeoutError = class extends Error {
   constructor(toolName, expectedMs, actualMs, wedged, pendingNote) {
     super(
-      wedged ? `Tool '${toolName}' timed out after ${actualMs}ms (budget ${expectedMs}ms). A database operation ran the entire time without returning \u2014 the connection is likely wedged or contended (SUP-2026-012); a second PAPI session open against the same database is a common cause.${pendingNote} The MCP server is restarting; reconnect with /mcp in Claude Code (or restart your MCP host), and close any other open PAPI session, before the next call.` : `Tool '${toolName}' timed out after ${actualMs}ms (budget ${expectedMs}ms). No single operation was stuck \u2014 this is cumulative query load exceeding the budget, not a wedged pool, and the database is healthy.${pendingNote} Retry the call; \`orient\` runs a lean path by default (heavy enrichment is opt-in via \`full: true\`).`
+      wedged ? `Tool '${toolName}' timed out after ${actualMs}ms (budget ${expectedMs}ms). A database operation ran the entire time without returning \u2014 the connection is likely wedged or contended (SUP-2026-012); a second PAPI session open against the same database is a common cause.${pendingNote} The MCP server is restarting; reconnect to the PAPI server in your AI client (in some clients that is /mcp; otherwise restart the client), and close any other open PAPI session, before the next call.` : `Tool '${toolName}' timed out after ${actualMs}ms (budget ${expectedMs}ms). No single operation was stuck \u2014 this is cumulative query load exceeding the budget, not a wedged pool, and the database is healthy.${pendingNote} Retry the call; \`orient\` runs a lean path by default (heavy enrichment is opt-in via \`full: true\`).`
     );
     this.toolName = toolName;
     this.expectedMs = expectedMs;
@@ -33194,7 +33674,12 @@ var FRIENDLY_GET_HTML = `<!doctype html>
      <code>https://mcp.getpapi.ai/mcp</code>.</p>
   <a class="btn" href="https://getpapi.ai/docs/install">See the install guide \u2192</a>
 </div></body></html>`;
-var KNOWN_INSTALL_CLIENTS = /* @__PURE__ */ new Set(["claude-code-plugin"]);
+var KNOWN_INSTALL_CLIENTS = /* @__PURE__ */ new Set([
+  "claude-code-plugin",
+  "cursor-plugin",
+  "gemini-extension",
+  "codex-plugin"
+]);
 var MAX_BODY_BYTES = 1 * 1024 * 1024;
 var SLOW_REQUEST_MS = 5e3;
 var CRITICAL_REQUEST_MS = 3e4;
@@ -33807,7 +34292,7 @@ Options:
 Getting started:
   1. Run "npx @papi-ai/server setup" in any project folder
   2. Approve in the browser when it opens
-  3. Open Claude Code in the same folder and say "run setup"
+  3. Open your AI client in the same folder and say "run setup"
 
 Stuck?
   npx @papi-ai/server doctor    # diagnose your config