@papi-ai/server 0.7.74 → 0.7.76

package/dist/index.js

@@ -1357,6 +1357,9 @@ var init_proxy_adapter = __esm({
       // getToolCallCount + updatePhaseStatus are ABSENT: they now have edge handlers and
       // are served through the forwarder (getToolCallCount = SUP-2026-026 handler #1).
       "getContributorRole",
+      // 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.
       // task-2728 (C331): createOwnerAction REMOVED from NO_FORWARD — the PRODUCER half
       // 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
@@ -1384,7 +1387,7 @@ var init_proxy_adapter = __esm({
       // now works for hosted users without exposing one member's owner actions to another.
       // task-2393 (C329) — Batch B wired: markCycleLearningResolved (the P1 — hosted
       // discovered_issue_resolve hard-errored), correctLatestBuildReportEffort,
-      // updateStageExitCriteria, updateDocAction, resolveLearningsForDoneTasks all have
+      // updateStageExitCriteria, updateDocAction all have
       // edge case handlers + ALLOWED_METHODS/WRITE_METHODS entries now, so they forward.
       // task-2489 (C320): recordProgressStep is now wired to the edge data-proxy
       // (case handler + ALLOWED_METHODS/WRITE_METHODS entries), so it forwards for
@@ -1968,9 +1971,19 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
         return this.invoke("updateDocStatus", [id, status, supersededBy]);
       }
       // --- Cycle Learnings ---
-      appendCycleLearnings(learnings) {
-        return this.invoke("appendCycleLearnings", [learnings]);
+      /**
+       * task-2999 / task-2998 (C356): the edge handler now calls append_cycle_learnings
+       * and returns { id, findingKey, inserted } per row, so hosted callers get the same
+       * per-row signal the pg path does. The [] normalisation stays as a floor for an
+       * edge deployed BEFORE that change — callers must read [] as "no signal
+       * available", never as "nothing was new".
+       */
+      async appendCycleLearnings(learnings) {
+        const result = await this.invoke("appendCycleLearnings", [learnings]);
+        return Array.isArray(result) ? result : [];
       }
+      // task-2998: includeResolved was missing here, so the flag could not even be SENT
+      // to the edge — the hosted caught->fixed ledger had no way to ask for history.
       getCycleLearnings(opts) {
         return this.invoke("getCycleLearnings", [opts]);
       }
@@ -2207,9 +2220,9 @@ var init_query = __esm({
     CLOSE = {};
     Query = class extends Promise {
       constructor(strings, args, handler, canceller, options = {}) {
-        let resolve3, reject;
+        let resolve4, reject;
         super((a, b2) => {
-          resolve3 = a;
+          resolve4 = a;
           reject = b2;
         });
         this.tagged = Array.isArray(strings.raw);
@@ -2220,7 +2233,7 @@ var init_query = __esm({
         this.options = options;
         this.state = null;
         this.statement = null;
-        this.resolve = (x) => (this.active = false, resolve3(x));
+        this.resolve = (x) => (this.active = false, resolve4(x));
         this.reject = (x) => (this.active = false, reject(x));
         this.active = false;
         this.cancelled = null;
@@ -2268,12 +2281,12 @@ var init_query = __esm({
               if (this.executed && !this.active)
                 return { done: true };
               prev && prev();
-              const promise = new Promise((resolve3, reject) => {
+              const promise = new Promise((resolve4, reject) => {
                 this.cursorFn = (value) => {
-                  resolve3({ value, done: false });
+                  resolve4({ value, done: false });
                   return new Promise((r) => prev = r);
                 };
-                this.resolve = () => (this.active = false, resolve3({ done: true }));
+                this.resolve = () => (this.active = false, resolve4({ done: true }));
                 this.reject = (x) => (this.active = false, reject(x));
               });
               this.execute();
@@ -2871,12 +2884,12 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     x.on("drain", drain);
     return x;
   }
-  async function cancel({ pid, secret }, resolve3, reject) {
+  async function cancel({ pid, secret }, resolve4, reject) {
     try {
       cancelMessage = bytes_default().i32(16).i32(80877102).i32(pid).i32(secret).end(16);
       await connect();
       socket.once("error", reject);
-      socket.once("close", resolve3);
+      socket.once("close", resolve4);
     } catch (error2) {
       reject(error2);
     }
@@ -3893,7 +3906,7 @@ var init_subscribe = __esm({
 // ../../node_modules/postgres/src/large.js
 import Stream2 from "stream";
 function largeObject(sql, oid, mode = 131072 | 262144) {
-  return new Promise(async (resolve3, reject) => {
+  return new Promise(async (resolve4, reject) => {
     await sql.begin(async (sql2) => {
       let finish;
       !oid && ([{ oid }] = await sql2`select lo_creat(-1) as oid`);
@@ -3919,7 +3932,7 @@ function largeObject(sql, oid, mode = 131072 | 262144) {
           ) seek
         `
       };
-      resolve3(lo);
+      resolve4(lo);
       return new Promise(async (r) => finish = r);
       async function readable({
         highWaterMark = 2048 * 8,
@@ -4084,8 +4097,8 @@ function Postgres(a, b2) {
   }
   async function reserve() {
     const queue = queue_default();
-    const c = open.length ? open.shift() : await new Promise((resolve3, reject) => {
-      const query = { reserve: resolve3, reject };
+    const c = open.length ? open.shift() : await new Promise((resolve4, reject) => {
+      const query = { reserve: resolve4, reject };
       queries.push(query);
       closed.length && connect(closed.shift(), query);
     });
@@ -4122,9 +4135,9 @@ function Postgres(a, b2) {
       let uncaughtError, result;
       name && await sql2`savepoint ${sql2(name)}`;
       try {
-        result = await new Promise((resolve3, reject) => {
+        result = await new Promise((resolve4, reject) => {
           const x = fn2(sql2);
-          Promise.resolve(Array.isArray(x) ? Promise.all(x) : x).then(resolve3, reject);
+          Promise.resolve(Array.isArray(x) ? Promise.all(x) : x).then(resolve4, reject);
         });
         if (uncaughtError)
           throw uncaughtError;
@@ -4181,8 +4194,8 @@ function Postgres(a, b2) {
     return c.execute(query) ? move(c, busy) : move(c, full);
   }
   function cancel(query) {
-    return new Promise((resolve3, reject) => {
-      query.state ? query.active ? connection_default(options).cancel(query.state, resolve3, reject) : query.cancelled = { resolve: resolve3, reject } : (queries.remove(query), query.cancelled = true, query.reject(Errors.generic("57014", "canceling statement due to user request")), resolve3());
+    return new Promise((resolve4, reject) => {
+      query.state ? query.active ? connection_default(options).cancel(query.state, resolve4, reject) : query.cancelled = { resolve: resolve4, reject } : (queries.remove(query), query.cancelled = true, query.reject(Errors.generic("57014", "canceling statement due to user request")), resolve4());
     });
   }
   async function end({ timeout = null } = {}) {
@@ -4201,11 +4214,11 @@ function Postgres(a, b2) {
   async function close() {
     await Promise.all(connections.map((c) => c.end()));
   }
-  async function destroy(resolve3) {
+  async function destroy(resolve4) {
     await Promise.all(connections.map((c) => c.terminate()));
     while (queries.length)
       queries.shift().reject(Errors.connection("CONNECTION_DESTROYED", options));
-    resolve3();
+    resolve4();
   }
   function connect(c, query) {
     move(c, connecting);
@@ -4389,7 +4402,7 @@ __export(doctor_exports, {
   __testing: () => __testing,
   runDoctor: () => runDoctor
 });
-import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync15 } from "fs";
 import { homedir as homedir4 } from "os";
 import { join as join21 } from "path";
 function redact(name, value) {
@@ -4409,7 +4422,7 @@ function findMcpJson() {
   for (const path7 of candidates) {
     if (!existsSync12(path7)) continue;
     try {
-      const raw = readFileSync14(path7, "utf-8");
+      const raw = readFileSync15(path7, "utf-8");
       const parsed = JSON.parse(raw);
       const papiEntry = parsed.papi ?? parsed.mcpServers?.papi;
       if (!papiEntry) continue;
@@ -4687,7 +4700,7 @@ __export(reset_exports, {
   removePapiEntry: () => removePapiEntry,
   runReset: () => runReset
 });
-import { existsSync as existsSync13, readFileSync as readFileSync15, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync16, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join22 } from "path";
 import { createInterface } from "readline/promises";
@@ -4697,7 +4710,7 @@ function findResetTarget() {
     let raw;
     let parsed;
     try {
-      raw = readFileSync15(path7, "utf-8");
+      raw = readFileSync16(path7, "utf-8");
       parsed = JSON.parse(raw);
     } catch {
       continue;
@@ -4768,7 +4781,7 @@ async function runReset(args = []) {
     }
   }
   try {
-    writeFileSync7(target.path, removePapiEntry(target), "utf-8");
+    writeFileSync8(target.path, removePapiEntry(target), "utf-8");
     process.stdout.write(`
 \u2713 Removed papi entry from ${target.path}
 `);
@@ -4798,7 +4811,7 @@ __export(audit_exports, {
   __testing: () => __testing2,
   runAudit: () => runAudit
 });
-import { existsSync as existsSync14, readFileSync as readFileSync16, readdirSync as readdirSync7 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync17, readdirSync as readdirSync7 } from "fs";
 import { homedir as homedir6 } from "os";
 import { join as join23 } from "path";
 function safeListDirs(dir) {
@@ -4819,7 +4832,7 @@ function readMcp(projectPath) {
   const path7 = join23(projectPath, ".mcp.json");
   if (!existsSync14(path7)) return { servers: [] };
   try {
-    const parsed = JSON.parse(readFileSync16(path7, "utf-8"));
+    const parsed = JSON.parse(readFileSync17(path7, "utf-8"));
     const mcpServers = parsed.mcpServers ?? {};
     const servers = Object.keys(mcpServers);
     if (parsed.papi && !servers.includes("papi")) servers.push("papi");
@@ -4875,7 +4888,7 @@ function readGlobalSkills() {
 function readGlobalMcpServers() {
   if (!existsSync14(GLOBAL_CLAUDE_JSON)) return [];
   try {
-    const parsed = JSON.parse(readFileSync16(GLOBAL_CLAUDE_JSON, "utf-8"));
+    const parsed = JSON.parse(readFileSync17(GLOBAL_CLAUDE_JSON, "utf-8"));
     const servers = parsed.mcpServers ?? {};
     return Object.keys(servers).sort((a, b2) => a.localeCompare(b2));
   } catch {
@@ -5041,7 +5054,7 @@ var setup_exports = {};
 __export(setup_exports, {
   runSetup: () => runSetup
 });
-import { existsSync as existsSync15, readFileSync as readFileSync17, writeFileSync as writeFileSync8, chmodSync as chmodSync2, statSync as statSync8 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync18, writeFileSync as writeFileSync9, chmodSync as chmodSync2, statSync as statSync9 } from "fs";
 import { join as join24 } from "path";
 function baseUrl() {
   const fromEnv = process.env["PAPI_HOST"] ?? process.env["PAPI_BASE_URL"];
@@ -5071,14 +5084,14 @@ async function postJson(url, body) {
   return { status: res.status, data };
 }
 function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 function writeMcpJson(opts) {
   const path7 = join24(process.cwd(), ".mcp.json");
   let parsed = {};
   if (existsSync15(path7)) {
     try {
-      parsed = JSON.parse(readFileSync17(path7, "utf-8"));
+      parsed = JSON.parse(readFileSync18(path7, "utf-8"));
     } catch {
       throw new Error(`.mcp.json at ${path7} is not valid JSON. Fix it or remove it before re-running setup.`);
     }
@@ -5099,9 +5112,9 @@ function writeMcpJson(opts) {
   }
   mcpServers.papi = papiEntry;
   parsed.mcpServers = mcpServers;
-  writeFileSync8(path7, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+  writeFileSync9(path7, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
   try {
-    const mode = statSync8(path7).mode & 511;
+    const mode = statSync9(path7).mode & 511;
     if (mode !== 384) chmodSync2(path7, 384);
   } catch {
   }
@@ -5209,9 +5222,9 @@ var init_setup = __esm({
 });
 
 // src/index.ts
-import { readFileSync as readFileSync18 } from "fs";
-import { dirname as dirname6, join as join25, basename as basename2 } from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import { readFileSync as readFileSync19 } from "fs";
+import { dirname as dirname7, join as join25, basename as basename2 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { Server as Server2 } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -8254,10 +8267,10 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
 }
 
 // src/server.ts
-import { readFileSync as readFileSync13 } from "fs";
+import { readFileSync as readFileSync14 } from "fs";
 import { access as access4, readdir as readdir4, readFile as readFile9 } from "fs/promises";
-import { join as join20, dirname as dirname5 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { join as join20, dirname as dirname6 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
@@ -8284,6 +8297,8 @@ var UNIVERSAL_FRAME = `PAPI gives this project a structured plan \u2192 build \u
 
 5. VERIFY BEFORE DONE. Test the change and confirm it works before reporting a task complete. Report failures honestly, with the output.
 
+6. NAME THE PROJECT WHEN YOU KNOW IT. If you know which repo this session is working in, pass \`project="<slug>"\` on the call rather than relying on whatever the connection defaults to. An account with more than one project cannot be resolved from a connection with no project bound \u2014 PAPI will stop and ask which one rather than guess, and answering costs a round trip. If PAPI asks, put the list to the user, then re-call with their choice; run \`project_switch\` to make it stick.
+
 PAPI reads and writes all project state through these tools \u2014 they are the source of truth, not local files.`;
 
 // src/lib/response.ts
@@ -9034,7 +9049,7 @@ PRE-BUILD VERIFICATION
 [List 2-5 specific file paths the builder should read BEFORE implementing to check if the functionality already exists. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. ALSO mandate a docs sweep, not just file-existence (task-2161): name any docs the builder should check via doc_search or the docs index \u2014 a design/research/status:final doc or a prior task may already cover the work. If >80% of the scope is already implemented, the builder should report "already built" instead of re-implementing. Include this section for EVERY task \u2014 it prevents wasted build slots on already-shipped code.]
 
 FILES LIKELY TOUCHED
-[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist.]
+[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist. MCP RESTART RULE (task-2978): whenever FILES LIKELY TOUCHED includes any \`packages/server/**\` path, append this line verbatim to the handoff \u2014 "MCP RESTART REQUIRED: a mid-session \`npm run mcp-build\` writes a dist the already-booted MCP process never loads, so verifying this change through PAPI's own tools before an explicit MCP reconnect is INVALID. Implement \u2192 mcp-build \u2192 reconnect \u2192 only then verify." This is one line inside this section, not a new section.]
 
 EFFORT
 [XS/S/M/L/XL]
@@ -9048,7 +9063,7 @@ After your natural language output, include this EXACT format on its own line:
 {
   "cycleLogTitle": "string \u2014 short descriptive title WITHOUT 'Cycle N' prefix. Should capture the cycle theme in 3-5 words (e.g. 'MCP Quality + Product Readiness' not 'Cycle 5 \u2014 Board Triage \u2014 Bug Fix'). This is the canonical theme label for the cycle.",
   "cycleLogContent": "string \u2014 5-10 line cycle log body in markdown, NO heading (the ### heading is generated automatically)",
-  "cycleLogCarryForward": "string or null \u2014 carry-forward items for next cycle",
+  "cycleLogCarryForward": "string or null \u2014 carry-forward for the next cycle, in TWO NAMED SECTIONS, product signal FIRST. Section 1 begins with the literal label 'WHAT SHIPS FOR USERS:' and names, concretely, what a person using this project can now see or do, and how to check it \u2014 never a deploy step. Section 2 begins with the literal label 'RELEASE MECHANICS:' and carries everything operational: deploy, publish, migrations, gate order, branch counts, spot-checks. The mechanics are load-bearing and must NOT be dropped or shortened \u2014 they go second, not away. orient parses these two labels and renders the product half first, so the labels are a contract, not decoration. If a cycle genuinely ships nothing user-visible, say so in one line under section 1 rather than omitting the label.",
   "cycleLogNotes": "string or null \u2014 1-3 lines of cycle-level observations: estimation accuracy, recurring blockers, velocity trends, dependency signals. Omit if no noteworthy observations.",
   "nextMode": "Full",
   "boardHealth": "string \u2014 e.g. 5 tasks (3 backlog, 2 done)",
@@ -9912,7 +9927,7 @@ After your natural language output, include this EXACT format on its own line:
 \`\`\`json
 {
   "sessionLogTitle": "string \u2014 Strategy Review title WITHOUT 'Cycle N' prefix (e.g. 'Strategy Review' not 'Cycle 5 \u2014 Strategy Review')",
-  "sessionLogContent": "string \u2014 5-10 line cycle log body summarizing the review, NO heading (the ### heading is generated automatically)",
+  "sessionLogContent": "string \u2014 5-10 line cycle log body summarizing the review, NO heading (the ### heading is generated automatically). LEAD WITH TANGIBLE PRODUCT INSIGHT: open with what was learned about the product, its users, or the market \u2014 a specific finding a reader can act on. Board hygiene, cadence, cycle counts, branch state and other housekeeping are legitimate content but they TRAIL; they must never be the opening line. If the review's most important finding genuinely is an operational one, say why it matters to the product in the same breath rather than reporting it as admin.",
   "velocityAssessment": "string \u2014 2-3 sentence velocity summary",
   "strategicRecommendations": "string \u2014 key recommendations in markdown",
   "activeDecisionUpdates": [
@@ -10276,7 +10291,7 @@ REFERENCE DOCS
 [Optional \u2014 paths to docs/ files with background context. Omit if not needed.]
 
 FILES LIKELY TOUCHED
-[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist.]
+[files \u2014 real paths only. TEST FILE LOCATIONS (task-2606): PAPI tests are NOT co-located next to source in a src/**/__tests__/ folder. Use the actual layout: server tests \u2192 packages/server/tests/<name>.test.ts; adapter-pg tests \u2192 packages/adapter-pg/src/__tests__/<name>.test.ts; dashboard/root tests \u2192 tests/<area>/<name>.test.ts. Do NOT invent packages/server/src/**/__tests__/ paths \u2014 they do not exist. MCP RESTART RULE (task-2978): whenever FILES LIKELY TOUCHED includes any \`packages/server/**\` path, append this line verbatim to the handoff \u2014 "MCP RESTART REQUIRED: a mid-session \`npm run mcp-build\` writes a dist the already-booted MCP process never loads, so verifying this change through PAPI's own tools before an explicit MCP reconnect is INVALID. Implement \u2192 mcp-build \u2192 reconnect \u2192 only then verify." This is one line inside this section, not a new section.]
 
 EFFORT
 [XS/S/M/L/XL]`;
@@ -10641,9 +10656,9 @@ async function getPrompt(name) {
   if (!endpoint) {
     return LOCAL_PROMPTS[name];
   }
-  const cached = cache.get(name);
-  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
-    return cached.content;
+  const cached2 = cache.get(name);
+  if (cached2 && Date.now() - cached2.fetchedAt < CACHE_TTL_MS) {
+    return cached2.content;
   }
   try {
     const url = endpoint.endsWith("/") ? `${endpoint}${name}` : `${endpoint}/${name}`;
@@ -10656,19 +10671,19 @@ async function getPrompt(name) {
     }
     const response = await fetch(url, { headers, signal: AbortSignal.timeout(1e4) });
     if (!response.ok) {
-      if (cached) return cached.content;
+      if (cached2) return cached2.content;
       return LOCAL_PROMPTS[name];
     }
     const data = await response.json();
     const content = data.content;
     if (typeof content !== "string" || content.length === 0) {
-      if (cached) return cached.content;
+      if (cached2) return cached2.content;
       return LOCAL_PROMPTS[name];
     }
     cache.set(name, { content, fetchedAt: Date.now() });
     return content;
   } catch {
-    if (cached) return cached.content;
+    if (cached2) return cached2.content;
     return LOCAL_PROMPTS[name];
   }
 }
@@ -15279,6 +15294,23 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
   const cappedBrief = capProductBrief2(productBrief);
   const smartBoard = formatBoardForReviewSmart(tasks, lastReviewCycleNum);
   const buildReportsText = formatRecentReportsSummary(reports, 10);
+  let surpriseDigestText = "";
+  try {
+    if (adapter2.getCycleLearnings) {
+      const surpriseRows = await adapter2.getCycleLearnings({ category: "surprise", limit: 40 });
+      surpriseDigestText = formatSurpriseDigest(surpriseRows.map((s) => ({
+        summary: s.summary,
+        module: s.module,
+        occurrences: s.occurrences,
+        lastSeenCycle: s.lastSeenCycle,
+        cycleNumber: s.cycleNumber
+      })));
+    }
+  } catch {
+  }
+  const buildReportsWithDigest = surpriseDigestText ? `${buildReportsText}
+
+${surpriseDigestText}` : buildReportsText;
   logDataSourceSummary("strategy_review", [
     { label: "productBrief", hasData: warnIfEmpty("readProductBrief", productBrief) },
     { label: "activeDecisions", hasData: warnIfEmpty("getActiveDecisions", decisions) },
@@ -15510,7 +15542,7 @@ ${lines.join("\n")}`;
     lastReviewCycle: lastReviewCycleNum,
     productBrief: cappedBrief,
     activeDecisions: formatActiveDecisionsForReview(decisions),
-    allBuildReports: buildReportsText,
+    allBuildReports: buildReportsWithDigest,
     sessionLog: formatCycleLog(recentLog),
     board: smartBoard,
     earnedPushback,
@@ -16198,9 +16230,31 @@ function formatRecentReportsSummary(reports, count) {
     if (issues) lines.push(`  _Issues:_ ${issues}`);
     const arch = trunc(r.architectureNotes, 200);
     if (arch) lines.push(`  _Architecture:_ ${arch}`);
+    const dead = trunc(r.deadEnds, 200);
+    if (dead) lines.push(`  _Dead ends:_ ${dead}`);
     return lines.join("\n");
   }).join("\n");
 }
+function formatSurpriseDigest(surprises) {
+  if (surprises.length === 0) return "";
+  const top = [...surprises].sort((a, b2) => (b2.occurrences ?? 1) - (a.occurrences ?? 1) || (b2.lastSeenCycle ?? b2.cycleNumber) - (a.lastSeenCycle ?? a.cycleNumber)).slice(0, 8);
+  const byModule = /* @__PURE__ */ new Map();
+  for (const s of top) {
+    const key = s.module?.trim() || "Unattributed";
+    if (!byModule.has(key)) byModule.set(key, []);
+    byModule.get(key).push(s);
+  }
+  const lines = ["**Assumption failures across cycles (surprises):**"];
+  for (const [module, items] of byModule) {
+    lines.push(`- **${module}**`);
+    for (const s of items) {
+      const summary = s.summary.length > 140 ? `${s.summary.slice(0, 140)}...` : s.summary;
+      const seen = (s.occurrences ?? 1) > 1 ? ` (seen ${s.occurrences}\xD7)` : "";
+      lines.push(`  - ${summary} \u2014 C${s.lastSeenCycle ?? s.cycleNumber}${seen}`);
+    }
+  }
+  return lines.join("\n");
+}
 function formatPhasesForReview(phases, currentCycle) {
   if (phases.length === 0) return void 0;
   const lines = [];
@@ -19750,6 +19804,9 @@ import {
   isCapabilityEnabled
 } from "@papi-ai/shared";
 
+// src/tools/build.ts
+import { validateFindings, MIN_REASON_LENGTH } from "@papi-ai/shared";
+
 // src/lib/directive-builders.ts
 function buildPrReviewerDirective(caps) {
   if (!isCapabilityEnabled(caps, "prReviewer")) return null;
@@ -19830,6 +19887,7 @@ function buildPapiMetaFramingDirective(caps, inner) {
 import { randomUUID as randomUUID11 } from "crypto";
 import { readdirSync as readdirSync5, existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync4, unlinkSync as unlinkSync3, mkdirSync as mkdirSync3 } from "fs";
 import { join as join12 } from "path";
+import { splitFindings, findingKey } from "@papi-ai/shared";
 
 // src/lib/db-only-notices.ts
 var DB_ONLY_START_NOTICE = "No git repo detected \u2014 running this cycle in your project database only. Your work stays in the working tree; run `git init` (and add a remote) to enable branches, commits and PR review.";
@@ -22388,6 +22446,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
     } catch {
     }
   }
+  let appendedRows = [];
+  const findingRows = [];
   if (adapter2.appendCycleLearnings) {
     const learnings = [];
     const taskModule = task.module ?? "";
@@ -22415,10 +22475,52 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
         relatedDecision: adIds[0]
       });
     };
-    extractLearning(input.surprises, "surprise");
-    extractLearning(input.discoveredIssues, "issue");
+    const structured = input.findings ?? [];
+    const pushFinding = (f) => {
+      const kind = f.kind ?? "issue";
+      const summary = (f.summary ?? "").trim();
+      if (!summary) return;
+      const severity = ["P0", "P1", "P2", "P3"].includes(String(f.severity)) ? f.severity : void 0;
+      const learning = {
+        taskId: task.id,
+        cycleNumber,
+        category: kind,
+        severity,
+        summary,
+        detail: f.detail,
+        tags: taskModule ? [taskModule.toLowerCase()] : [],
+        relatedDecision: adIds[0],
+        module: f.module ?? taskModule ?? void 0,
+        disposition: f.disposition,
+        dispositionReason: f.reason
+      };
+      findingRows.push({ finding: f, learning });
+      learnings.push(learning);
+    };
+    if (structured.length > 0) {
+      for (const f of structured) pushFinding(f);
+    } else {
+      const blobs = [
+        [input.discoveredIssues, "issue"],
+        [input.surprises, "surprise"],
+        [input.deadEnds, "dead_end"]
+      ];
+      for (const [text, kind] of blobs) {
+        for (const parsed of splitFindings(text, kind)) {
+          pushFinding({
+            kind,
+            // splitFindings yields 'note' for unprefixed content; that is not a
+            // severity the column accepts, so it becomes undefined rather than
+            // being coerced into a P-level it never claimed.
+            severity: parsed.severity === "note" ? void 0 : parsed.severity,
+            summary: parsed.summary,
+            detail: parsed.summary,
+            module: taskModule || void 0
+          });
+        }
+      }
+    }
     extractLearning(input.architectureNotes, "architecture");
-    extractLearning(input.deadEnds, "dead_end");
     if (input.scopeAccuracy && input.scopeAccuracy !== "accurate") {
       learnings.push({
         taskId: task.id,
@@ -22430,47 +22532,48 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
     }
     if (learnings.length > 0) {
       try {
-        await adapter2.appendCycleLearnings(learnings);
-      } catch {
+        appendedRows = await adapter2.appendCycleLearnings(learnings) ?? [];
+      } catch (err) {
+        console.error(
+          `[papi] appendCycleLearnings failed for ${task.displayId} (${learnings.length} finding(s) NOT recorded): ${err instanceof Error ? err.message : String(err)}`
+        );
       }
     }
   }
-  const AUTO_TRIAGE_MIN_SEVERITY = /* @__PURE__ */ new Set(["P0", "P1", "P2"]);
+  const AUTO_TRIAGE_MIN_SEVERITY = /* @__PURE__ */ new Set(["P0", "P1"]);
   let autoTriagedCount = 0;
   let autoTriagedSoftSkipped = 0;
   const autoTriagedIds = [];
   const autoTriagedDupes = [];
-  if (input.discoveredIssues && input.discoveredIssues !== "None" && typeof adapter2.createTask === "function") {
-    const issueLines = input.discoveredIssues.split(/\n|;/).map((s) => s.trim()).filter((s) => s.length > 0);
-    const backlogTitleMap = /* @__PURE__ */ new Map();
-    try {
-      const backlog = await adapter2.queryBoard({ status: ["Backlog"] });
-      for (const t of backlog) {
-        const normalized = t.title.replace(/^\[Auto-triaged\]\s*/i, "").trim().toLowerCase();
-        if (normalized && !backlogTitleMap.has(normalized)) {
-          backlogTitleMap.set(normalized, t.displayId);
-        }
-      }
-    } catch {
-    }
-    for (const line of issueLines) {
-      const sevMatch = line.match(/^(P[0-3])[\s:]+/i);
-      if (!sevMatch) continue;
-      const severityLabel = sevMatch[1].toUpperCase();
-      if (!AUTO_TRIAGE_MIN_SEVERITY.has(severityLabel)) {
+  const insertedByKey = /* @__PURE__ */ new Map();
+  for (const row of appendedRows) {
+    if (row.findingKey) insertedByKey.set(row.findingKey, row.inserted);
+  }
+  const haveInsertSignal = appendedRows.length > 0;
+  if (findingRows.length > 0 && typeof adapter2.createTask === "function") {
+    for (const { finding, learning } of findingRows) {
+      if (learning.category !== "issue") continue;
+      if (finding.disposition !== "filed") continue;
+      const severityLabel = learning.severity;
+      if (!severityLabel || !AUTO_TRIAGE_MIN_SEVERITY.has(severityLabel)) {
         autoTriagedSoftSkipped++;
         continue;
       }
-      const priority = severityLabel === "P0" ? "P0 Critical" : severityLabel === "P1" ? "P1 High" : severityLabel === "P2" ? "P2 Medium" : "P3 Low";
-      const titleRaw = line.replace(/^P[0-3][\s:]+/i, "").trim();
-      const title = titleRaw.length > 120 ? titleRaw.slice(0, 120) : titleRaw;
-      if (!title) continue;
-      const normalized = title.toLowerCase();
-      const dupId = backlogTitleMap.get(normalized);
-      if (dupId) {
-        autoTriagedDupes.push(dupId);
+      const key = findingKey(learning.summary);
+      if (haveInsertSignal && key && insertedByKey.get(key) === false) {
+        autoTriagedDupes.push(learning.summary.slice(0, 60));
         continue;
       }
+      if (!haveInsertSignal) {
+        autoTriagedSoftSkipped++;
+        console.error(
+          `[papi] auto-triage skipped for "${learning.summary.slice(0, 60)}" \u2014 the adapter returned no per-row inserted signal, so recurrence cannot be distinguished from a new finding.`
+        );
+        continue;
+      }
+      const priority = severityLabel === "P0" ? "P0 Critical" : "P1 High";
+      const title = learning.summary.length > 120 ? learning.summary.slice(0, 120) : learning.summary;
+      if (!title) continue;
       try {
         const created = await adapter2.createTask({
           uuid: "",
@@ -22479,20 +22582,17 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
           status: "Backlog",
           priority,
           complexity: "Small",
-          module: task.module ?? "",
+          module: finding.module ?? task.module ?? "",
           phase: task.phase ?? "",
           owner: "papi",
           reviewed: false,
           taskType: "discovery",
           source: "build_complete",
-          notes: `Origin: ${task.displayId} (${task.title}), cycle ${cycleNumber}. Original issue: ${line}`,
+          notes: `Origin: ${task.displayId} (${task.title}), cycle ${cycleNumber}. Filed rather than fixed${finding.reason ? `: ${finding.reason}` : ""}. Original issue: ${learning.detail ?? learning.summary}`,
           createdCycle: cycleNumber
         });
         autoTriagedCount++;
-        if (created?.displayId) {
-          autoTriagedIds.push(created.displayId);
-          backlogTitleMap.set(normalized, created.displayId);
-        }
+        if (created?.displayId) autoTriagedIds.push(created.displayId);
       } catch {
       }
     }
@@ -22832,15 +22932,118 @@ ${instructions}`;
 }
 
 // src/tools/doc-registry.ts
-import { readdirSync as readdirSync6, existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
-import { join as join13, relative } from "path";
+import { readdirSync as readdirSync6, existsSync as existsSync9, readFileSync as readFileSync8, writeFileSync as writeFileSync5, mkdirSync as mkdirSync4 } from "fs";
+import { join as join13, relative, isAbsolute as isAbsolute2, dirname as dirname4, resolve as resolve3, sep } from "path";
 import { homedir as homedir3 } from "os";
 import { randomUUID as randomUUID12 } from "crypto";
 import { docDeletionBlockMessage } from "@papi-ai/shared";
 init_git();
+
+// src/services/entitlements.ts
+import { evaluateContributorGate } from "@papi-ai/shared";
+var FREE_PROJECT_CAP = 3;
+var DOC_STORAGE_CEILING_BY_TIER = {
+  free: { bytes: 25 * 1024 * 1024, docs: 200 },
+  pro: { bytes: 250 * 1024 * 1024, docs: 2e3 },
+  team: { bytes: 1024 * 1024 * 1024, docs: 1e4 }
+};
+var MAX_DOC_BODY_BYTES = 2 * 1024 * 1024;
+var PAID_TIERS = /* @__PURE__ */ new Set(["pro", "team"]);
+var PRICING_URL = "https://getpapi.ai/pricing";
+async function resolveTier(adapter2) {
+  if (typeof adapter2.getMeteredUsage !== "function") return null;
+  try {
+    const usage = await adapter2.getMeteredUsage();
+    return usage?.tier ?? null;
+  } catch {
+    return null;
+  }
+}
+function isPaidTier(tier) {
+  return tier !== null && PAID_TIERS.has(tier);
+}
+async function enforceProjectCap(adapter2, target) {
+  const tier = await resolveTier(adapter2);
+  if (tier === null || isPaidTier(tier)) return null;
+  if (typeof adapter2.listUserProjects !== "function") return null;
+  let projects;
+  try {
+    projects = await adapter2.listUserProjects();
+  } catch {
+    return null;
+  }
+  const matchesExisting = projects.some(
+    (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);
+  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).**
+
+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 existing projects are untouched, and you can keep working in any of them.`;
+}
+function humanBytes(n) {
+  if (n >= 1024 * 1024 * 1024) return `${(n / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+  if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${n} bytes`;
+}
+async function checkDocStorageCap(adapter2, incomingBytes) {
+  if (incomingBytes > MAX_DOC_BODY_BYTES) {
+    return {
+      storeBody: false,
+      message: `**Body not stored \u2014 this document is ${humanBytes(incomingBytes)}, above the ${humanBytes(MAX_DOC_BODY_BYTES)} per-document limit.**
+
+The registry entry was saved and everything else is unaffected. Split the document, or keep it as a file in your repo.`
+    };
+  }
+  const tier = await resolveTier(adapter2);
+  if (tier === null) return { storeBody: true };
+  const ceiling = DOC_STORAGE_CEILING_BY_TIER[tier] ?? DOC_STORAGE_CEILING_BY_TIER.free;
+  if (typeof adapter2.getDocBodyUsage !== "function") return { storeBody: true };
+  let usage;
+  try {
+    usage = await adapter2.getDocBodyUsage();
+  } catch {
+    return { storeBody: true };
+  }
+  if (!usage) return { storeBody: true };
+  const upgrade = tier === "free" ? `Upgrade to Pro for ${humanBytes(DOC_STORAGE_CEILING_BY_TIER.pro.bytes)} at a flat monthly price: ${PRICING_URL}` : `See plan limits: ${PRICING_URL}`;
+  if (usage.totalBytes + incomingBytes > ceiling.bytes) {
+    return {
+      storeBody: false,
+      message: `**Body not stored \u2014 you are at your ${tier} plan's document storage ceiling.**
+
+Using ${humanBytes(usage.totalBytes)} of ${humanBytes(ceiling.bytes)} across ${usage.docCount} stored documents. The registry entry WAS saved, so the doc is still tracked, searchable and linkable \u2014 only the stored copy of its body was skipped.
+
+${upgrade}`
+    };
+  }
+  if (usage.docCount >= ceiling.docs) {
+    return {
+      storeBody: false,
+      message: `**Body not stored \u2014 you are at your ${tier} plan's stored-document limit.**
+
+${usage.docCount} of ${ceiling.docs} documents stored (${humanBytes(usage.totalBytes)}). The registry entry WAS saved, so the doc is still tracked, searchable and linkable \u2014 only the stored copy of its body was skipped.
+
+${upgrade}`
+    };
+  }
+  return { storeBody: true };
+}
+
+// src/tools/doc-registry.ts
 var docRegisterTool = {
   name: "doc_register",
-  description: "Register or update a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content; the body stays a file, so an untracked doc is committed at registration to make it durable (or you get a loud warning if it cannot be). Re-registering an existing doc updates its summary, tags, actions, type, and status (upsert). Visibility and owner are not changed on re-register.",
+  description: "Register or update a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata, a structured summary, AND the document body (task-3017) so a doc survives a branch switch, an autostash, or a gitignored docs/private/ folder \u2014 pass `body`, or omit it and the file is read from disk when a local workspace is available. Bodies are stored per-user against a plan ceiling; at the ceiling the registration still succeeds and only the body is skipped. Only .md paths are accepted. An untracked doc is still committed at registration to make it durable (or you get a loud warning if it cannot be). Re-registering an existing doc updates its summary, tags, actions, type, and status (upsert). Visibility and owner are not changed on re-register.",
   annotations: { title: "Register Doc", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -22852,6 +23055,10 @@ var docRegisterTool = {
       summary: { type: "string", description: 'Structured 2-4 sentence summary. Format: "Conclusions: ... Open questions: ... Unactioned: ..."' },
       tags: { type: "array", items: { type: "string" }, description: "Tags from project vocabulary." },
       cycle: { type: "number", description: "Current cycle number." },
+      body: {
+        type: "string",
+        description: "OPTIONAL full markdown body. Omit it and the file is read from disk when a local workspace is available; on a hosted-only session with no body supplied, metadata is registered and the tool says the body was not stored. Stored so the doc survives a branch switch, an autostash, or living in a gitignored folder."
+      },
       visibility: { type: "string", enum: ["public", "contributors", "private"], description: 'Visibility tier. Defaults to "private" (owner-only). "public" = shipped with PAPI (anyone can read); "contributors" = team-member tier (shared with the project cohort). Choose private unless you have explicit intent to share. FOLDER CONVENTION: place the doc body to match \u2014 docs/private/ (owner-only, gitignored), docs/contributors/ (team), docs/public/ (everyone). If you omit this param, the tier is inferred from the folder; anything else defaults to private.' },
       actions: {
         type: "array",
@@ -22889,6 +23096,19 @@ var docSearchTool = {
     required: []
   }
 };
+var docReadTool = {
+  name: "doc_read",
+  description: "Read a registered document's stored BODY back out of the database, and optionally restore it to disk. This is the recovery path: when a doc is gone from the working tree \u2014 a branch switch, a stash, a gitignored docs/private/ folder that never made it into git \u2014 doc_read is how the content comes back. Identify the doc by path or UUID via `id_or_path`. Pass `write_to_disk: true` to write the body back to its registered path; an existing file with DIFFERENT content is never overwritten (the conflict is reported and nothing is written). Bodies are stored by doc_register from C356 onward, so a doc registered before that, or one whose body was skipped at a storage ceiling, has metadata but no body \u2014 doc_read says so plainly rather than returning an empty document.",
+  annotations: { title: "Read Doc", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      id_or_path: { type: "string", description: 'Registered path (e.g. "docs/private/notes.md") or the doc UUID.' },
+      write_to_disk: { type: "boolean", description: "Write the body back to its registered path (default false \u2014 read only). Refuses to overwrite a file whose content differs." }
+    },
+    required: ["id_or_path"]
+  }
+};
 var docScanTool = {
   name: "doc_scan",
   description: "Scan docs/ and plans directories for unregistered .md files. Returns a list of files not yet in the doc registry. Use this to find docs that need registration.",
@@ -22920,8 +23140,8 @@ function normalizeDocPath(rawPath, projectRoot) {
   const isWindowsDrive = /^[A-Za-z]:\//.test(fwd);
   const isUnc = /^\/\//.test(fwd);
   const isPosixAbs = fwd.startsWith("/");
-  const isAbsolute2 = isWindowsDrive || isUnc || isPosixAbs;
-  if (!isAbsolute2) return { path: fwd };
+  const isAbsolute3 = isWindowsDrive || isUnc || isPosixAbs;
+  if (!isAbsolute3) return { path: fwd };
   if (projectRoot) {
     const root = projectRoot.replace(/\\/g, "/").replace(/\/+$/, "");
     if (fwd.toLowerCase().startsWith(`${root.toLowerCase()}/`)) {
@@ -23010,6 +23230,14 @@ async function handleDocRegister(adapter2, args, config2) {
       continueHint
     );
   }
+  if (!path7.toLowerCase().endsWith(".md")) {
+    return docRegisterSoftFail(
+      adapterType,
+      "path-validation",
+      `Only .md documents can be registered \u2014 "${path7}" is not markdown.`,
+      "The doc registry indexes markdown notes and research docs. Nothing is blocked: continue your flow, and register the .md version if there is one."
+    );
+  }
   try {
     let supersededBy;
     if (supersededByPath) {
@@ -23032,6 +23260,44 @@ async function handleDocRegister(adapter2, args, config2) {
       actions,
       visibility
     });
+    let bodyNote = "";
+    try {
+      const supplied = typeof args.body === "string" ? args.body : void 0;
+      let body = supplied;
+      if (body === void 0 && hasLocalWorkspace()) {
+        try {
+          const abs = isAbsolute2(entry.path) ? entry.path : join13(config2?.projectRoot ?? process.cwd(), entry.path);
+          if (existsSync9(abs)) body = readFileSync8(abs, "utf8");
+        } catch {
+        }
+      }
+      if (body === void 0) {
+        bodyNote = hasLocalWorkspace() ? "\n\n_Body not stored \u2014 the file could not be read from disk. Pass `body` to store it._" : "\n\n_Body not stored \u2014 no local workspace on this session. Pass `body` to store it._";
+      } else if (typeof adapter2.storeDocBody !== "function") {
+        bodyNote = "\n\n_Body not stored \u2014 this adapter does not support body storage._";
+      } else {
+        const decision = await checkDocStorageCap(adapter2, Buffer.byteLength(body, "utf8"));
+        if (!decision.storeBody) {
+          bodyNote = `
+
+${decision.message}`;
+        } else {
+          const result = await adapter2.storeDocBody({
+            docId: entry.id,
+            body,
+            // Resolved by resolveDocVisibility above — the SAME resolution the
+            // registry row used, so doc_bodies' denormalised copy cannot disagree
+            // with doc_registry on the very first write.
+            visibility: entry.visibility ?? visibility,
+            ownerUserId: entry.ownerUserId
+          });
+          bodyNote = result.stored ? `
+- **Body stored:** ${result.byteSize.toLocaleString()} bytes` : "\n- **Body:** unchanged since last registration";
+        }
+      }
+    } catch {
+      bodyNote = "\n\n_Body not stored \u2014 storage was unavailable. The registry entry was saved._";
+    }
     const visibilityLabel = entry.visibility === "contributors" ? "team member" : entry.visibility ?? "private";
     let durability = "";
     try {
@@ -23046,7 +23312,7 @@ async function handleDocRegister(adapter2, args, config2) {
 - **Visibility:** ${visibilityLabel}
 - **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
 - **Actions:** ${actions?.length ?? 0} items
-- **ID:** ${entry.id}` + durability
+- **ID:** ${entry.id}` + bodyNote + durability
     );
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -23075,7 +23341,7 @@ async function handleDocSearch(adapter2, args, config2) {
     const actionCount = d.actions?.filter((a) => a.status === "pending").length ?? 0;
     const actionNote = actionCount > 0 ? ` | ${actionCount} pending action(s)` : "";
     const missingNote = root && d.path && !existsSync9(join13(root, d.path)) ? `
-> \u26A0\uFE0F **File missing on disk** \u2014 the registry points at \`${d.path}\` but nothing is there. Check \`git stash list\` for a papi-autostash entry, or re-create/deregister the doc.` : "";
+> \u26A0\uFE0F **File missing on disk** \u2014 the registry points at \`${d.path}\` but nothing is there. Recover it with \`doc_read\` (\`id_or_path: "${d.path}", write_to_disk: true\`) if its body was stored, or check \`git stash list\` for a papi-autostash entry.` : "";
     return `### ${d.title}
 **Type:** ${d.type} | **Status:** ${d.status} | **Cycle:** ${d.cycleCreated}${d.cycleUpdated ? `\u2192${d.cycleUpdated}` : ""}${actionNote}
 **Path:** ${d.path}${missingNote}
@@ -23087,6 +23353,96 @@ ${d.summary}
 
 ${lines.join("\n---\n\n")}`);
 }
+function resolveRestoreTarget(projectRoot, docPath) {
+  const normalized = normalizeDocPath(docPath, projectRoot);
+  if ("error" in normalized) return { error: normalized.error };
+  const root = resolve3(projectRoot);
+  const abs = resolve3(root, normalized.path);
+  if (abs !== root && !abs.startsWith(root + sep)) {
+    return {
+      error: `Refusing to write outside the project root. The registered path \`${docPath}\` resolves to \`${abs}\`, which is not under \`${root}\`.`
+    };
+  }
+  return { abs };
+}
+async function handleDocRead(adapter2, config2, args) {
+  if (!adapter2.getDoc || typeof adapter2.getDocBody !== "function") {
+    return errorResponse(
+      "Doc bodies are not available on this adapter \u2014 requires the pg/proxy adapter. Nothing is blocked; the file on disk (if any) is still the copy you have."
+    );
+  }
+  const idOrPath = args.id_or_path?.trim();
+  if (!idOrPath) {
+    return errorResponse("id_or_path is required \u2014 pass the doc's registered path or its UUID.");
+  }
+  const writeToDisk = args.write_to_disk === true;
+  const doc = await adapter2.getDoc(idOrPath);
+  if (!doc) {
+    return errorResponse(
+      `No registered doc matches \`${idOrPath}\` in this project. Check \`doc_search\` for the exact path, or \`doc_scan\` for unregistered files.`
+    );
+  }
+  const gate = await resolveOwnerGate(adapter2, config2);
+  const requesterUserId = gate.enforced ? gate.callerUserId : gate.ownerUserId ?? gate.callerUserId;
+  const stored = await adapter2.getDocBody(doc.id, requesterUserId);
+  const header = `**${doc.title}**
+- **Path:** ${doc.path}
+- **Type:** ${doc.type} | **Status:** ${doc.status} | **Visibility:** ${doc.visibility ?? "private"}
+`;
+  if (!stored) {
+    return textResponse(
+      header + `- **Body:** not stored
+
+No body is stored for this doc. That happens for three reasons: it was registered before body storage landed (C356); the body was skipped because the account was at its plan storage ceiling; or it was registered from a hosted session with no \`body\` argument and no local file to read.
+
+**Fix:** re-run \`doc_register\` for \`${doc.path}\` with the file present, or pass \`body\` explicitly.`
+    );
+  }
+  if (!stored.permitted) {
+    return errorResponse(
+      `\`${doc.path}\` has a stored body, but its **${doc.visibility ?? "private"}** tier does not let you read it. ` + (doc.visibility === "private" ? "Private bodies are readable by the doc owner alone \u2014 project membership is not enough, by design (task-3016)." : "Contributor-tier bodies are readable by project members only.")
+    );
+  }
+  const body = stored.body ?? "";
+  let restoreNote = "";
+  if (writeToDisk) {
+    restoreNote = restoreBodyToDisk(config2.projectRoot, doc.path, body);
+  }
+  return textResponse(
+    header + `- **Stored:** ${stored.byteSize.toLocaleString()} bytes, updated ${stored.updatedAt}
+` + restoreNote + `
+---
+
+${body}`
+  );
+}
+function restoreBodyToDisk(projectRoot, docPath, body) {
+  if (!hasLocalWorkspace()) {
+    return "- **Not restored:** this session has no local workspace (hosted transport). The body is above \u2014 write it yourself.\n";
+  }
+  const target = resolveRestoreTarget(projectRoot, docPath);
+  if ("error" in target) return `- **Not restored:** ${target.error}
+`;
+  try {
+    if (existsSync9(target.abs)) {
+      const onDisk = readFileSync8(target.abs, "utf8");
+      if (onDisk === body) {
+        return `- **Already on disk:** \`${docPath}\` is byte-identical to the stored body. Nothing written.
+`;
+      }
+      return `- \u26A0\uFE0F **Conflict \u2014 nothing written.** A DIFFERENT file already exists at \`${docPath}\` (${Buffer.byteLength(onDisk, "utf8").toLocaleString()} bytes on disk vs ${Buffer.byteLength(body, "utf8").toLocaleString()} stored). Move or delete it first, then re-run with \`write_to_disk: true\`. The stored body is printed below either way.
+`;
+    }
+    mkdirSync4(dirname4(target.abs), { recursive: true });
+    writeFileSync5(target.abs, body, "utf8");
+    return `- **Restored:** wrote ${Buffer.byteLength(body, "utf8").toLocaleString()} bytes to \`${docPath}\`
+`;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return `- **Not restored:** writing \`${docPath}\` failed \u2014 ${message}. The body is printed below.
+`;
+  }
+}
 function scanMdFiles(dir, rootDir) {
   if (!existsSync9(dir)) return [];
   const files = [];
@@ -23529,6 +23885,24 @@ var buildExecuteTool = {
         },
         required: ["urls", "curl_command", "http_status", "response_excerpt", "verified_at"]
       },
+      findings: {
+        type: "array",
+        maxItems: 12,
+        description: 'OPTIONAL, and the highest-leverage field here. One entry per DISCRETE thing you found, instead of (or alongside) the prose blobs. The point is `disposition`: PAPI has never had a verb for "found it, fixed it, moving on", so the only way to record a finding was to file it \u2014 which costs more than fixing it and grows the board faster than the fixes. Use fixed_now when you already fixed it (the row is recorded as caught AND fixed, and is never auto-triaged), filed when it genuinely needs its own task, wont_fix when it is not worth fixing. A P2/P3 you are filing rather than fixing, and any wont_fix, needs a `reason` of at least 12 characters. Omit this array entirely and nothing changes \u2014 the prose blobs are still parsed.',
+        items: {
+          type: "object",
+          properties: {
+            kind: { type: "string", enum: ["issue", "dead_end", "surprise"], description: "What kind of finding. Only `issue` carries a disposition." },
+            severity: { type: "string", enum: ["P0", "P1", "P2", "P3"], description: "Severity, for issues." },
+            summary: { type: "string", maxLength: 200, description: 'One line. No "Pn:" prefix \u2014 severity has its own field.' },
+            detail: { type: "string", maxLength: 600, description: "The verbatim context: what breaks, where, and how it reproduces." },
+            disposition: { type: "string", enum: ["fixed_now", "filed", "wont_fix"], description: "Required for kind=issue. fixed_now = already fixed in this build. filed = needs its own task. wont_fix = not worth fixing." },
+            reason: { type: "string", maxLength: 200, description: "Why you filed rather than fixed, or why it will not be fixed. Required (>= 12 chars) for a filed P2/P3 and for any wont_fix." },
+            module: { type: "string", description: "Module the finding belongs to. Defaults to the task's module." }
+          },
+          required: ["kind", "summary"]
+        }
+      },
       preview: {
         type: "object",
         description: `Optional. For a build that touched USER-FACING UI: tell the owner how to SEE the result locally so reviewing it doesn't mean reading code or asking "show me". urls = the localhost route(s) to open (e.g. ["http://localhost:3000/hub"]); notes = what to look at; screenshot_path = a path to an image you captured. Surfaced verbatim in the completion output. When the diff touched UI and you omit this, the output nudges you to provide it.`,
@@ -23859,6 +24233,24 @@ If this build fixes any of these, pass their UUIDs in \`fixed_issues\` on comple
       }
     } catch {
     }
+    let ruledOutSection = "";
+    try {
+      const moduleTag = result.task.module?.trim();
+      if (moduleTag && adapter2.getCycleLearnings) {
+        const deadEnds = (await adapter2.getCycleLearnings({ category: "dead_end", limit: 25 })).filter((l) => !l.resolvedAt).filter((l) => (l.module ?? "").toLowerCase() === moduleTag.toLowerCase() || l.tags.some((t) => t.toLowerCase() === moduleTag.toLowerCase())).slice(0, 4);
+        if (deadEnds.length > 0) {
+          const rows = deadEnds.map((l) => `- ${l.summary.length > 180 ? `${l.summary.slice(0, 180)}...` : l.summary}`).join("\n");
+          ruledOutSection = `
+
+---
+
+**RULED OUT IN ${moduleTag} \u2014 do not re-walk these:**
+${rows}
+These approaches were tried in this module and failed. If one looks right, read why it was ruled out before spending time on it.`;
+        }
+      }
+    } catch {
+    }
     const moduleInstructions = getModuleInstructions(result.task.module);
     const moduleContext = await getModuleContext(adapter2, result.task);
     const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
@@ -23868,7 +24260,7 @@ If this build fixes any of these, pass their UUIDs in \`fixed_issues\` on comple
     ) ?? "";
     const gestaltNote = buildGestaltPreBuildDirective(caps) ?? "";
     const buildDisciplineSection = buildPapiMetaFramingDirective(caps, buildDisciplineNote) ?? "";
-    return textResponse(resumeNote + header + serializeBuildHandoff(result.task.buildHandoff) + modelNote + gestaltNote + adSection + moduleInstructions + moduleContext + dogfoodSection + openIssuesSection + verificationNote + buildDisciplineSection + chainInstruction + phaseNote + filesToWriteSection);
+    return textResponse(resumeNote + header + serializeBuildHandoff(result.task.buildHandoff) + modelNote + gestaltNote + adSection + moduleInstructions + moduleContext + dogfoodSection + openIssuesSection + ruledOutSection + verificationNote + buildDisciplineSection + chainInstruction + phaseNote + filesToWriteSection);
   } catch (err) {
     if (isNoHandoffError(err)) {
       const lines = [
@@ -23957,6 +24349,20 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
   if (!parsedEstimatedEffort) {
     return errorResponse(`Invalid estimated_effort value "${estimatedEffort}". Must be one of: XS, S, M, L, XL.`);
   }
+  const rawFindings = Array.isArray(args.findings) ? args.findings : void 0;
+  const findingsCheck = validateFindings(rawFindings);
+  if (!findingsCheck.ok) {
+    const offenders = findingsCheck.violations.map((v, i) => `${i + 1}. ${v.message}`).join("\n\n");
+    return textResponse(
+      `**${findingsCheck.violations.length} finding${findingsCheck.violations.length === 1 ? "" : "s"} need a disposition or a reason before ${taskId} can complete.**
+
+You already have the file open and the context loaded \u2014 fixing costs less than filing, triaging, planning and re-contexting it three cycles from now. A P2 or P3 you are filing rather than fixing needs a reason of at least ${MIN_REASON_LENGTH} characters; so does anything marked wont_fix. P0 and P1 file freely.
+
+${offenders}
+
+Your report was NOT discarded and the task is NOT yet Done \u2014 fix what you can, set a disposition on the rest, and re-send \`build_execute\` complete with the SAME report fields.`
+    );
+  }
   const acceptanceConfirmed = args.acceptance_confirmed === true;
   if (completed === "yes" && !acceptanceConfirmed) {
     const gateInfo = adapter2.getProjectInfo ? await adapter2.getProjectInfo().catch(() => null) : null;
@@ -24003,7 +24409,9 @@ Your report was NOT discarded and the task is NOT yet Done \u2014 re-send with \
         detail: bi.detail ?? ""
       })),
       productionVerification,
-      preview
+      preview,
+      // task-3001: already gate-validated above, so the service can trust it.
+      findings: rawFindings
     }, { light }, clientName);
     tracker.mark("complete_format");
     tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.cycleNumber });
@@ -24028,9 +24436,10 @@ Your report was NOT discarded and the task is NOT yet Done \u2014 re-send with \
     }
     let fixedResolvedCount = 0;
     if (fixedIssues && fixedIssues.length > 0 && typeof adapter2.markCycleLearningResolved === "function") {
+      const resolvedBy = `build:${result.task.displayId ?? taskId}`;
       for (const learningId of fixedIssues) {
         try {
-          await adapter2.markCycleLearningResolved(learningId, clientName);
+          await adapter2.markCycleLearningResolved(learningId, resolvedBy);
           fixedResolvedCount++;
         } catch {
         }
@@ -24283,7 +24692,7 @@ var ideaTool = {
       },
       project: {
         type: "string",
-        description: "Project id (UUID) or slug to write this idea to, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default."
+        description: "Project id (UUID) or slug to write this idea to, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: ["text"]
@@ -24730,7 +25139,7 @@ var backlogImportTool = {
       },
       project: {
         type: "string",
-        description: "Project id (UUID) or slug to import into, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise."
+        description: "Project id (UUID) or slug to import into, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: ["source"]
@@ -24938,7 +25347,7 @@ var bugTool = {
       },
       project: {
         type: "string",
-        description: "BOARD MODE ONLY. Project id (UUID) or slug to file this bug under, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. It CANNOT redirect an upstream (report=true) submission \u2014 those always go to PAPI maintainers. Use project_switch to change the session default."
+        description: "BOARD MODE ONLY. Project id (UUID) or slug to file this bug under, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. It CANNOT redirect an upstream (report=true) submission \u2014 those always go to PAPI maintainers. Use project_switch to change the session default. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: ["text"]
@@ -27256,8 +27665,8 @@ Path: ${mcpJsonPath}`
       const fileBody = target.render(envVars);
       const wroteToShared = !target.isProjectScoped && !!existingConfig;
       if (wroteToShared) {
-        const sep = existingConfig.endsWith("\n") ? "\n" : "\n\n";
-        await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep + fileBody, target.isProjectScoped, config2.adapterType, collector);
+        const sep2 = existingConfig.endsWith("\n") ? "\n" : "\n\n";
+        await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep2 + fileBody, target.isProjectScoped, config2.adapterType, collector);
       } else {
         await writeMcpConfig(mcpJsonPath, target.configPath, fileBody, target.isProjectScoped, config2.adapterType, collector);
       }
@@ -27328,8 +27737,8 @@ ${writeNote}
     const fileBody = target.render(envVars);
     const wroteToShared = !target.isProjectScoped && !!existingConfig;
     if (wroteToShared) {
-      const sep = existingConfig.endsWith("\n") ? "\n" : "\n\n";
-      await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep + fileBody, target.isProjectScoped, config2.adapterType, collector);
+      const sep2 = existingConfig.endsWith("\n") ? "\n" : "\n\n";
+      await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep2 + fileBody, target.isProjectScoped, config2.adapterType, collector);
     } else {
       await writeMcpConfig(mcpJsonPath, target.configPath, fileBody, target.isProjectScoped, config2.adapterType, collector);
     }
@@ -27372,8 +27781,8 @@ ${writeNote}
     const fileBody = target.render(envVars);
     const wroteToShared = !target.isProjectScoped && !!existingConfig;
     if (wroteToShared) {
-      const sep = existingConfig.endsWith("\n") ? "\n" : "\n\n";
-      await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep + fileBody, target.isProjectScoped, config2.adapterType, collector);
+      const sep2 = existingConfig.endsWith("\n") ? "\n" : "\n\n";
+      await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep2 + fileBody, target.isProjectScoped, config2.adapterType, collector);
     } else {
       await writeMcpConfig(mcpJsonPath, target.configPath, fileBody, target.isProjectScoped, config2.adapterType, collector);
     }
@@ -27841,6 +28250,50 @@ function formatUnblockSection(candidates) {
   return lines.join("\n");
 }
 
+// src/lib/carry-forward-shape.ts
+var PRODUCT_MARKER = /WHAT SHIPS FOR USERS\b[^\n:]*:/i;
+var MECHANICS_MARKER = /RELEASE MECHANICS\b[^\n:]*:/i;
+function splitCarryForward(raw) {
+  const productMatch = PRODUCT_MARKER.exec(raw);
+  const mechanicsMatch = MECHANICS_MARKER.exec(raw);
+  if (!productMatch && !mechanicsMatch) {
+    return { product: raw.trim(), mechanics: "", split: false };
+  }
+  if (!productMatch && mechanicsMatch) {
+    const head = raw.slice(0, mechanicsMatch.index).trim();
+    const tail = raw.slice(mechanicsMatch.index + mechanicsMatch[0].length).trim();
+    return { product: head, mechanics: tail, split: true };
+  }
+  const productStart = productMatch.index + productMatch[0].length;
+  if (!mechanicsMatch) {
+    return { product: raw.slice(productStart).trim(), mechanics: "", split: true };
+  }
+  if (mechanicsMatch.index < productMatch.index) {
+    return {
+      product: raw.slice(productStart).trim(),
+      mechanics: raw.slice(mechanicsMatch.index + mechanicsMatch[0].length, productMatch.index).trim(),
+      split: true
+    };
+  }
+  return {
+    product: raw.slice(productStart, mechanicsMatch.index).trim(),
+    mechanics: raw.slice(mechanicsMatch.index + mechanicsMatch[0].length).trim(),
+    split: true
+  };
+}
+function renderCarryForward(raw, decorate = (t) => t) {
+  const { product, mechanics, split } = splitCarryForward(raw);
+  if (!split) return [decorate(product)];
+  const lines = [];
+  if (product) lines.push(decorate(product));
+  if (mechanics) {
+    if (product) lines.push("");
+    lines.push("**Release mechanics** \u2014 needed at release, not now:");
+    lines.push(decorate(mechanics));
+  }
+  return lines;
+}
+
 // src/lib/deferred-gate.ts
 var GATE_PHRASES = [
   "depends on",
@@ -28113,8 +28566,94 @@ async function verifyProject(adapter2) {
 // src/tools/orient.ts
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
-import { readFileSync as readFileSync11, writeFileSync as writeFileSync5, existsSync as existsSync11 } from "fs";
+import { readFileSync as readFileSync11, writeFileSync as writeFileSync6, existsSync as existsSync11 } from "fs";
 import { join as join17 } from "path";
+
+// src/lib/exit-criteria-evaluators.ts
+var TEST_ACCOUNT_PATTERN = "ftue-%@test.papi.dev";
+function sqlOf(adapter2) {
+  const candidate = adapter2.sql;
+  return typeof candidate === "function" ? candidate : void 0;
+}
+var evaluateUnaidedFullLoop = async (adapter2, projectId) => {
+  const sql = sqlOf(adapter2);
+  if (!sql) return { met: null, unevaluatedReason: "no direct SQL access on this adapter (hosted path)" };
+  const rows = await sql`
+    SELECT count(DISTINCT p.user_id)::text AS builders, count(*)::text AS cycles
+    FROM cycles c
+    JOIN projects p ON p.id = c.project_id
+    JOIN auth.users u ON u.id = p.user_id
+    WHERE c.status = 'complete'
+      AND p.user_id IS DISTINCT FROM (SELECT user_id FROM projects WHERE id = ${projectId})
+      AND u.email NOT LIKE ${TEST_ACCOUNT_PATTERN}
+  `;
+  const builders2 = Number(rows[0]?.builders ?? 0);
+  const cycles = Number(rows[0]?.cycles ?? 0);
+  return builders2 >= 1 ? {
+    met: null,
+    evidence: `${builders2} non-owner account(s) completed ${cycles} cycle(s) in their own projects; owner and ${TEST_ACCOUNT_PATTERN} excluded. Counted ${(/* @__PURE__ */ new Date()).toISOString()}.`,
+    unevaluatedReason: `mechanically satisfied (${builders2} non-owner builders, ${cycles} completed cycles) \u2014 but "without owner assistance" is a human judgement, so this needs an owner tick via set_criterion_met`
+  } : { met: false, evidence: `0 completed cycles on non-owner projects. Counted ${(/* @__PURE__ */ new Date()).toISOString()}.` };
+};
+var evaluateSelfServeActivation = async (adapter2, projectId) => {
+  const sql = sqlOf(adapter2);
+  if (!sql) return { met: null, unevaluatedReason: "no direct SQL access on this adapter (hosted path)" };
+  const rows = await sql`
+    SELECT count(DISTINCT p.user_id)::text AS users
+    FROM cycles c
+    JOIN projects p ON p.id = c.project_id
+    JOIN auth.users u ON u.id = p.user_id
+    WHERE p.user_id IS DISTINCT FROM (SELECT user_id FROM projects WHERE id = ${projectId})
+      AND u.email NOT LIKE ${TEST_ACCOUNT_PATTERN}
+      AND EXISTS (SELECT 1 FROM cycle_tasks t WHERE t.cycle = c.number AND t.project_id = c.project_id)
+  `;
+  const users = Number(rows[0]?.users ?? 0);
+  return users >= 1 ? {
+    met: null,
+    evidence: `${users} non-owner account(s) produced a planned cycle with tasks in their own project; owner and ${TEST_ACCOUNT_PATTERN} excluded. Counted ${(/* @__PURE__ */ new Date()).toISOString()}.`,
+    unevaluatedReason: `mechanically satisfied (${users} non-owner accounts planned in their own project) \u2014 but "ZERO owner intervention" is a human judgement, so this needs an owner tick via set_criterion_met`
+  } : { met: false, evidence: `0 non-owner accounts with a planned cycle. Counted ${(/* @__PURE__ */ new Date()).toISOString()}.` };
+};
+var EVALUATORS = {
+  "c4a11d42-b222-45af-a470-08970e1bd6a9": evaluateSelfServeActivation,
+  "59751bcb-f719-4cf6-a4d4-608770999a22": evaluateUnaidedFullLoop
+};
+var UNEVALUATABLE = {
+  "e9d984f4-1e75-4486-8605-5dfd07412915": "no evaluator here \u2014 the canonical completion-keyed definition lives in lib/weekly-active-builders.ts (Next app) and must not be re-derived in the server",
+  "c596a082-9ad3-4089-b497-46cd189e892b": "threshold is provisional pending an owner ruling \u2014 no settled bar to evaluate against"
+};
+async function evaluateExitCriteria(adapter2, projectId, criteria) {
+  return Promise.all(criteria.map(async (c) => {
+    const evaluator = EVALUATORS[c.id];
+    if (!evaluator) {
+      const reason = UNEVALUATABLE[c.id];
+      if (!reason) return { ...c, met: c.met, autoEvaluated: false };
+      return c.met ? { ...c, met: true, autoEvaluated: false } : { ...c, met: null, unevaluatedReason: reason, autoEvaluated: false };
+    }
+    try {
+      const result = await evaluator(adapter2, projectId);
+      return {
+        ...c,
+        met: result.met,
+        evidence: result.evidence ?? c.evidence,
+        unevaluatedReason: result.unevaluatedReason,
+        autoEvaluated: result.met !== null
+      };
+    } catch (err) {
+      return {
+        ...c,
+        met: c.met ? true : null,
+        unevaluatedReason: `evaluator failed: ${err instanceof Error ? err.message : String(err)}`,
+        autoEvaluated: false
+      };
+    }
+  }));
+}
+function criterionMarker(met) {
+  return met === true ? "[x]" : met === false ? "[ ]" : "[?]";
+}
+
+// src/tools/orient.ts
 var execFileAsync2 = promisify2(execFile2);
 var GIT_DEPENDENT_ENVS = /* @__PURE__ */ new Set(["hosted", "api"]);
 var VALID_ENVS = /* @__PURE__ */ new Set(["local-cli", "hosted", "api", "unknown"]);
@@ -28323,9 +28862,15 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
     }
     if (hierarchy.stageExitCriteria && hierarchy.stageExitCriteria.length > 0) {
       const crit = hierarchy.stageExitCriteria;
-      const met = crit.filter((c) => c.met).length;
       const total = crit.length;
-      lines.push(`**Stage Exit Criteria [${met}/${total} met]:** ${crit.map((c) => `${c.met ? "[x]" : "[ ]"} ${c.text}`).join(" | ")}`);
+      const met = crit.filter((c) => c.met === true).length;
+      const unevaluated = crit.filter((c) => c.met === null || c.met === void 0).length;
+      const countLabel = unevaluated > 0 ? `${met}/${total} met, ${unevaluated} unevaluated` : `${met}/${total} met`;
+      lines.push(`**Stage Exit Criteria [${countLabel}]:** ${crit.map((c) => `${criterionMarker(c.met ?? null)} ${c.text}`).join(" | ")}`);
+      for (const c of crit) {
+        const reason = c.unevaluatedReason;
+        if (reason) lines.push(`  \u21B3 UNEVALUATED \u2014 ${reason}`);
+      }
       if (met === total) {
         lines.push("  \u21B3 All exit criteria met \u2014 run `strategy_review` to propose advancing the stage.");
       }
@@ -28420,7 +28965,7 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
   const hasCarryForward = health.carryForward !== "None found" && !health.carryForward.startsWith("No carry-forward");
   if (hasCarryForward) {
     lines.push("## Carry-Forward");
-    lines.push(annotateTaskRefs(health.carryForward, taskRefs));
+    lines.push(...renderCarryForward(health.carryForward, (t) => annotateTaskRefs(t, taskRefs)));
     lines.push("");
   }
   const hasMetrics = health.metricsSection !== "Could not read methodology metrics." && !health.metricsSection.includes("undefined");
@@ -28441,7 +28986,7 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
   }
   return lines.join("\n").trimEnd();
 }
-async function getHierarchyPosition(adapter2) {
+async function getHierarchyPosition(adapter2, projectId) {
   try {
     const [horizons, stages, phases, allTasks] = await Promise.all([
       adapter2.readHorizons?.() ?? [],
@@ -28474,7 +29019,14 @@ async function getHierarchyPosition(adapter2) {
       stage: activeStage.label,
       activePhases: activePhases.map((p) => p.label),
       phasesNearingClosure: nearingClosure.map((p) => p.label),
-      stageExitCriteria: activeStage.exitCriteria
+      // task-3008: EVALUATE rather than read the hand-ticked boolean. Best-effort —
+      // a failing evaluator degrades that criterion to unevaluated and leaves the
+      // rest intact, because orient is the first call of every session.
+      stageExitCriteria: await evaluateExitCriteria(
+        adapter2,
+        projectId ?? "",
+        activeStage.exitCriteria ?? []
+      ).catch(() => (activeStage.exitCriteria ?? []).map((c) => ({ ...c, autoEvaluated: false })))
     };
   } catch {
     return void 0;
@@ -28643,7 +29195,7 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
     const [buildResult, healthResult, hierarchy] = await Promise.all([
       tracked("listBuilds", () => listBuilds(adapter2, config2))(),
       tracked("getHealthSummary", () => getHealthSummary(adapter2))(),
-      tracked("getHierarchyPosition", () => getHierarchyPosition(adapter2))()
+      tracked("getHierarchyPosition", () => getHierarchyPosition(adapter2, config2.projectId))()
     ]);
     const currentCycle = buildResult.currentCycle;
     const cycleIsComplete = healthResult.latestCycleStatus === "complete";
@@ -28898,10 +29450,6 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
       // Discovered issues — split into Alerts (P0/P1) and Unactioned (P2/P3).
       // Older records without a severity field are treated as P3.
       tracked("discovered-issues", async () => {
-        try {
-          await adapter2.resolveLearningsForDoneTasks?.();
-        } catch {
-        }
         const learnings = await adapter2.getCycleLearnings?.({ category: "issue", limit: 30 });
         if (!learnings) return { alertsNote: "", unactionedIssuesNote: "" };
         const candidateLearnings = learnings.filter((l) => !l.actionTaken);
@@ -29210,7 +29758,7 @@ function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, client
     additions.push(dedupeEnrichmentBlob(content, CLAUDE_MD_TIER_2));
   }
   if (additions.length === 0) return "";
-  writeFileSync5(claudeMdPath, content + additions.join(""), "utf-8");
+  writeFileSync6(claudeMdPath, content + additions.join(""), "utf-8");
   const tierNames = [];
   if (additions.some((a) => a.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1))) tierNames.push("Established (batch building, strategy reviews, AD lifecycle)");
   if (additions.some((a) => a.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T2))) tierNames.push("Mature (idea pipeline, doc registry, advanced patterns)");
@@ -30025,8 +30573,8 @@ ${result.userMessage}
 import { readFileSync as readFileSync12, statSync as statSync7 } from "fs";
 
 // src/services/scope-brief.ts
-import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync4 } from "fs";
-import { join as join18, dirname as dirname4 } from "path";
+import { writeFileSync as writeFileSync7, mkdirSync as mkdirSync5 } from "fs";
+import { join as join18, dirname as dirname5 } from "path";
 var SCOPE_BRIEF_SYSTEM = `You are a technical scoping tool. You receive a brief-class task (too large to build directly) and decompose it into a structured scope document.
 
 A scope document must:
@@ -30089,8 +30637,8 @@ async function applyScopeBrief(adapter2, input) {
   if (input.adapterType === "proxy") {
     collector.add({ path: relPath, content: docBody, mode: "overwrite" });
   } else {
-    mkdirSync4(dirname4(absPath), { recursive: true });
-    writeFileSync6(absPath, docBody, "utf-8");
+    mkdirSync5(dirname5(absPath), { recursive: true });
+    writeFileSync7(absPath, docBody, "utf-8");
   }
   const taskCount = countSubTasks(docContent);
   const summary = buildSummary(task, taskCount);
@@ -30375,6 +30923,77 @@ ${d.body}`;
 ${formatted}`, meta));
 }
 
+// src/lib/dist-staleness.ts
+import { readFileSync as readFileSync13, statSync as statSync8 } from "fs";
+import { createHash as createHash5 } from "crypto";
+import { fileURLToPath as fileURLToPath3 } from "url";
+var BOOT_MS = Date.now();
+var DEFAULT_SKEW_MS = 2e3;
+var STAT_TTL_MS = 1e4;
+var SELF_PATH = (() => {
+  try {
+    return fileURLToPath3(import.meta.url);
+  } catch {
+    return null;
+  }
+})();
+function hashFile(path7) {
+  try {
+    return createHash5("sha256").update(readFileSync13(path7)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+var BOOT_HASH = SELF_PATH ? hashFile(SELF_PATH) : null;
+function bundleRewritten({ bootMs, distMtimeMs, skewMs = DEFAULT_SKEW_MS }) {
+  if (distMtimeMs === null || !Number.isFinite(distMtimeMs)) return false;
+  return distMtimeMs > bootMs + skewMs;
+}
+function isDistStale({ bootHash, distHash }) {
+  if (!bootHash || !distHash) return false;
+  return bootHash !== distHash;
+}
+function shouldAnnounce(currentHash2, alreadyAnnouncedHash) {
+  if (!currentHash2) return false;
+  return currentHash2 !== alreadyAnnouncedHash;
+}
+var cached = null;
+var currentHash = BOOT_HASH;
+var announcedHash = null;
+function computeStale() {
+  if (!SELF_PATH || !BOOT_HASH) return false;
+  let distMtimeMs = null;
+  try {
+    distMtimeMs = statSync8(SELF_PATH).mtimeMs;
+  } catch {
+    return false;
+  }
+  if (!bundleRewritten({ bootMs: BOOT_MS, distMtimeMs })) {
+    currentHash = BOOT_HASH;
+    return false;
+  }
+  currentHash = hashFile(SELF_PATH);
+  return isDistStale({ bootHash: BOOT_HASH, distHash: currentHash });
+}
+function checkDistStaleness(now = Date.now()) {
+  if (cached && now - cached.at < STAT_TTL_MS) return cached.stale;
+  const stale = computeStale();
+  cached = { at: now, stale };
+  return stale;
+}
+function stalenessWarning(now = Date.now()) {
+  const age = Math.round((now - BOOT_MS) / 1e3);
+  return `\u26A0\uFE0F This PAPI MCP server process booted ${age}s ago and packages/server has been REBUILT with DIFFERENT code since. It is still running the code it booted with, so anything you verify through these tools right now reflects the OLD bundle. Reconnect / restart the PAPI MCP server before trusting this output. (Shown once per rebuild \u2014 the condition persists until you restart.)
+
+`;
+}
+function consumeStalenessWarning(now = Date.now()) {
+  if (!checkDistStaleness(now)) return null;
+  if (!shouldAnnounce(currentHash, announcedHash)) return null;
+  announcedHash = currentHash;
+  return stalenessWarning(now);
+}
+
 // src/tools/learning-action.ts
 var learningActionTool = {
   name: "learning_action",
@@ -30502,54 +31121,6 @@ async function handleDiscoveredIssueResolve(adapter2, args) {
 
 // src/tools/project.ts
 import path6 from "path";
-
-// src/services/entitlements.ts
-import { evaluateContributorGate } from "@papi-ai/shared";
-var FREE_PROJECT_CAP = 3;
-var PAID_TIERS = /* @__PURE__ */ new Set(["pro", "team"]);
-var PRICING_URL = "https://getpapi.ai/pricing";
-async function resolveTier(adapter2) {
-  if (typeof adapter2.getMeteredUsage !== "function") return null;
-  try {
-    const usage = await adapter2.getMeteredUsage();
-    return usage?.tier ?? null;
-  } catch {
-    return null;
-  }
-}
-function isPaidTier(tier) {
-  return tier !== null && PAID_TIERS.has(tier);
-}
-async function enforceProjectCap(adapter2, target) {
-  const tier = await resolveTier(adapter2);
-  if (tier === null || isPaidTier(tier)) return null;
-  if (typeof adapter2.listUserProjects !== "function") return null;
-  let projects;
-  try {
-    projects = await adapter2.listUserProjects();
-  } catch {
-    return null;
-  }
-  const matchesExisting = projects.some(
-    (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);
-  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).**
-
-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 existing projects are untouched, and you can keep working in any of them.`;
-}
-
-// src/tools/project.ts
 function workspacePapiDir(config2) {
   if (!hasLocalWorkspace()) return void 0;
   return config2.papiDir;
@@ -31019,7 +31590,7 @@ Its build reports, comments, and history moved with it; the cycle assignment was
 // src/services/harness-inventory.ts
 import { readdir as readdir3, readFile as readFile8, stat as stat3 } from "fs/promises";
 import { join as join19 } from "path";
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 var RECOMMENDED_HOOKS = ["stop-release-check.sh", "claude-md-size-guard.sh"];
 async function computeFingerprint(root) {
   const parts = [];
@@ -31045,7 +31616,7 @@ async function computeFingerprint(root) {
   } catch {
     parts.push("manifest:none");
   }
-  return createHash5("sha256").update(parts.join("|")).digest("hex").slice(0, 16);
+  return createHash6("sha256").update(parts.join("|")).digest("hex").slice(0, 16);
 }
 async function readSkillDescription(skillDir) {
   try {
@@ -31346,9 +31917,9 @@ async function checkMeter(adapter2, toolName, cacheKey) {
   if (!adapter2.getMeteredUsage) return { blocked: false };
   try {
     let usage;
-    const cached = usageCache.get(cacheKey);
-    if (cached && Date.now() - cached.at < CACHE_TTL_MS3) {
-      usage = cached.usage;
+    const cached2 = usageCache.get(cacheKey);
+    if (cached2 && Date.now() - cached2.at < CACHE_TTL_MS3) {
+      usage = cached2.usage;
     } else {
       usage = await adapter2.getMeteredUsage();
       usageCache.set(cacheKey, { usage, at: Date.now() });
@@ -31515,6 +32086,7 @@ var PAPI_TOOLS = [
   docActionPromoteTool,
   docDeleteTool,
   docReorderTool,
+  docReadTool,
   getSiblingAdsTool,
   handoffGenerateTool,
   scopeBriefTool,
@@ -31537,11 +32109,11 @@ function getToolMetadata() {
   return PAPI_TOOLS.map((t) => ({ name: t.name, description: t.description }));
 }
 function createServer(adapter2, config2) {
-  const __pkgFilename = fileURLToPath3(import.meta.url);
-  const __pkgDir = dirname5(__pkgFilename);
+  const __pkgFilename = fileURLToPath4(import.meta.url);
+  const __pkgDir = dirname6(__pkgFilename);
   let serverVersion = "unknown";
   try {
-    const pkg = JSON.parse(readFileSync13(join20(__pkgDir, "..", "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync14(join20(__pkgDir, "..", "package.json"), "utf-8"));
     serverVersion = pkg.version ?? "unknown";
   } catch {
   }
@@ -31557,8 +32129,8 @@ function createServer(adapter2, config2) {
       "\n\u26A0 PAPI is running in md mode \u2014 your cycles are not visible on the hosted dashboard.\n  Configure DATABASE_URL or sign up at https://getpapi.ai/setup to enable observability.\n\n"
     );
   }
-  const __filename = fileURLToPath3(import.meta.url);
-  const __dirname2 = dirname5(__filename);
+  const __filename = fileURLToPath4(import.meta.url);
+  const __dirname2 = dirname6(__filename);
   const skillsDir = join20(__dirname2, "..", "skills");
   function parseSkillFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
@@ -31719,6 +32291,8 @@ function createServer(adapter2, config2) {
           return handleDocDelete(adapter2, config2, safeArgs);
         case "doc_reorder":
           return handleDocReorder(adapter2, safeArgs);
+        case "doc_read":
+          return handleDocRead(adapter2, config2, safeArgs);
         case "get_sibling_ads":
           return handleGetSiblingAds(adapter2, safeArgs);
         case "handoff_generate":
@@ -31859,6 +32433,16 @@ ${usageLine(decision.usage)}`;
     }
     const footer = formatMetricsFooter(elapsed, usage, contextBytes);
     result.content.push({ type: "text", text: footer });
+    try {
+      const warning = consumeStalenessWarning();
+      if (warning && result.content.length > 0) {
+        const first = result.content[0];
+        if (first && typeof first.text === "string") {
+          first.text = warning + first.text;
+        }
+      }
+    } catch {
+    }
     return result;
   });
   return server2;
@@ -32304,10 +32888,10 @@ async function dispatchRequest(args) {
 }
 
 // src/index.ts
-var __dirname = dirname6(fileURLToPath4(import.meta.url));
+var __dirname = dirname7(fileURLToPath5(import.meta.url));
 var pkgVersion = "unknown";
 try {
-  const pkg = JSON.parse(readFileSync18(join25(__dirname, "..", "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync19(join25(__dirname, "..", "package.json"), "utf-8"));
   pkgVersion = pkg.version;
 } catch {
 }