@papi-ai/server 0.7.75 → 0.7.77

package/dist/index.js

@@ -1353,10 +1353,21 @@ var init_proxy_adapter = __esm({
       // (1) local-only
       "close",
       "initRls",
+      // task-3207 (C357): commitBuildComplete, commitReviewSubmit, commitRelease have no
+      // edge case handler and no ALLOWED_METHODS entry — forwarding them 403s at the edge
+      // with no try/catch at the call site, crashing build_execute/review_submit/release
+      // completion for every hosted user. Restores the intended graceful degradation
+      // (separate appendBuildReport + updateTaskStatus calls) until they're atomically wired.
+      "commitBuildComplete",
+      "commitReviewSubmit",
+      "commitRelease",
       // (2) not-yet-wired hosted gaps — shrink as data-proxy handlers land (task-2390).
       // 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 +1395,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 +1979,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 +2228,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 +2241,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 +2289,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 +2892,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 +3914,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 +3940,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 +4105,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 +4143,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 +4202,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 +4222,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 +4410,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 +4430,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 +4708,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 +4718,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 +4789,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 +4819,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 +4840,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 +4896,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 +5062,7 @@ var setup_exports = {};
 __export(setup_exports, {
   runSetup: () => runSetup
 });
-import { existsSync as existsSync15, readFileSync as readFileSync17, writeFileSync as writeFileSync8, chmodSync as chmodSync2, statSync as statSync9 } 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 +5092,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,7 +5120,7 @@ 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 = statSync9(path7).mode & 511;
     if (mode !== 384) chmodSync2(path7, 384);
@@ -5209,8 +5230,8 @@ 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 { 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";
@@ -5246,6 +5267,15 @@ var HELP_FOOTER_MD = `
 var STRATEGY_REVIEW_OFFER_GAP = 5;
 var STRATEGY_REVIEW_BLOCK_GAP = 7;
 var ZOOM_OUT_OFFER_GAP = 25;
+function isDatabaseBackedAdapter(known) {
+  if (known) return known === "pg" || known === "proxy";
+  try {
+    const { adapterType } = loadConfig();
+    return adapterType === "pg" || adapterType === "proxy";
+  } catch {
+    return process.env.PAPI_ADAPTER !== "md";
+  }
+}
 function loadConfig() {
   const projectArgIdx = process.argv.indexOf("--project");
   const configuredRoot = projectArgIdx !== -1 ? process.argv[projectArgIdx + 1] : process.env.PAPI_PROJECT_DIR;
@@ -6311,6 +6341,48 @@ function effortOrdinal(effort) {
   const normalized = effort.trim().toUpperCase();
   return EFFORT_SCALE[normalized];
 }
+function calculateCycleMetrics(reports, currentCycle, window = 5) {
+  const recentReports = reports.filter(
+    (r) => r.cycle > currentCycle - window && r.cycle <= currentCycle
+  );
+  const perCycle = /* @__PURE__ */ new Map();
+  for (const r of recentReports) {
+    const group = perCycle.get(r.cycle) ?? [];
+    group.push(r);
+    perCycle.set(r.cycle, group);
+  }
+  const accuracy = [];
+  const velocity = [];
+  const sortedCycles = [...perCycle.keys()].sort((a, b2) => a - b2);
+  for (const cycle of sortedCycles) {
+    const reps = perCycle.get(cycle);
+    const deltas = [];
+    for (const r of reps) {
+      const actual = effortOrdinal(r.actualEffort);
+      const estimated = effortOrdinal(r.estimatedEffort);
+      if (actual !== void 0 && estimated !== void 0) {
+        deltas.push(actual - estimated);
+      }
+    }
+    if (deltas.length > 0) {
+      accuracy.push({
+        cycle,
+        reports: deltas.length,
+        matchRate: Math.round(deltas.filter((d) => d === 0).length / deltas.length * 100),
+        mae: Math.round(deltas.reduce((s, d) => s + Math.abs(d), 0) / deltas.length * 10) / 10,
+        bias: Math.round(deltas.reduce((s, d) => s + d, 0) / deltas.length * 10) / 10
+      });
+    }
+    velocity.push({
+      cycle,
+      completed: reps.filter((r) => r.completed === "Yes").length,
+      partial: reps.filter((r) => r.completed === "Partial").length,
+      failed: reps.filter((r) => r.completed === "No").length,
+      effortPoints: reps.reduce((s, r) => s + (effortOrdinal(r.actualEffort) ?? 0), 0)
+    });
+  }
+  return { accuracy, velocity };
+}
 function serializeAccuracyRow(a) {
   return `| ${a.cycle} | ${a.reports} | ${a.matchRate}% | ${a.mae} | ${a.bias >= 0 ? "+" : ""}${a.bias} |`;
 }
@@ -8254,9 +8326,9 @@ 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 { join as join20, dirname as dirname6 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -8389,6 +8461,16 @@ function formatBuildReports(reports, opts) {
 _\u2026and ${reports.length - capped.length} older build report(s) omitted to bound context size._` : "";
   return body + omitted;
 }
+function extractReferencedTaskIds(report) {
+  const prose = [report.surprises, report.architectureNotes, report.deadEnds, report.discoveredIssues].filter((s) => typeof s === "string" && s.length > 0).join("\n");
+  const own = report.taskId?.toLowerCase();
+  const found = /* @__PURE__ */ new Set();
+  for (const m of prose.matchAll(/\btask-\d+\b/gi)) {
+    const id = m[0].toLowerCase();
+    if (id !== own) found.add(id);
+  }
+  return [...found].sort();
+}
 function formatRecentlyShippedCapabilities(reports) {
   const completed = reports.filter((r) => r.completed === "Yes" || r.completed === "Partial");
   if (completed.length === 0) return void 0;
@@ -8403,13 +8485,39 @@ function formatRecentlyShippedCapabilities(reports) {
     }
     return parts.join("\n");
   });
-  return [
+  const namedBy = /* @__PURE__ */ new Map();
+  const completedIds = new Set(completed.map((r) => r.taskId?.toLowerCase()).filter(Boolean));
+  for (const r of completed) {
+    for (const ref of extractReferencedTaskIds(r)) {
+      if (completedIds.has(ref)) continue;
+      const namers = namedBy.get(ref) ?? [];
+      namers.push(r.taskId);
+      namedBy.set(ref, namers);
+    }
+  }
+  const out = [
     `${completed.length} task(s) completed in recent cycles:`,
     "",
     ...lines,
     "",
     "Cross-reference candidate tasks against this list. If >80% of a candidate task's scope appears here, recommend cancellation or scope reduction instead of scheduling."
-  ].join("\n");
+  ];
+  if (namedBy.size > 0) {
+    out.push(
+      "",
+      "### \u26A0 Named by a shipped task \u2014 VERIFY BEFORE SCHEDULING",
+      "",
+      "These task IDs are referenced in the build reports above but are NOT themselves",
+      "completed. A discovery is often fixed as a side effect of a sibling task's diff and",
+      "never marked done, so it survives into this plan carrying notes that are no longer",
+      "true (C357 gave task-3043 a P1 slot this way \u2014 task-2998 had already fixed it).",
+      "For each one below: check the naming report and the live code BEFORE scheduling it.",
+      "If it is already fixed, close it with a boardCorrection instead of spending a slot.",
+      "",
+      ...[...namedBy.entries()].sort(([a], [b2]) => a.localeCompare(b2)).map(([ref, namers]) => `- **${ref}** \u2014 named by ${namers.join(", ")}`)
+    );
+  }
+  return out.join("\n");
 }
 function formatCycleLog(entries) {
   if (entries.length === 0) return "No cycle log entries yet.";
@@ -8656,13 +8764,14 @@ function computeSnapshotsFromBuildReports(reports, tasks) {
     const cycleReports = reportsByCycle.get(sn) ?? [];
     const cycleTaskRows = tasksByCycle.get(sn);
     const withEffort = cycleReports.filter((r) => r.estimatedEffort && r.actualEffort);
-    const accurate = withEffort.filter((r) => r.estimatedEffort === r.actualEffort).length;
-    const matchRate = withEffort.length > 0 ? Math.round(accurate / withEffort.length * 100) : 0;
+    const [computedAccuracy] = calculateCycleMetrics(withEffort, sn, 1).accuracy;
     const { completed, total, plannedPoints, deliveredPoints } = computeCycleEffort(cycleTaskRows, cycleReports);
     snapshots.push({
       cycle: sn,
       date: (/* @__PURE__ */ new Date()).toISOString(),
-      accuracy: [{ cycle: sn, reports: cycleReports.length, matchRate, mae: 0, bias: 0 }],
+      // No report in this cycle carried BOTH an estimate and an actual, so there
+      // is genuinely nothing to measure. Zeros here mean "no data", not "no bias".
+      accuracy: [computedAccuracy ?? { cycle: sn, reports: 0, matchRate: 0, mae: 0, bias: 0 }],
       velocity: [{
         cycle: sn,
         completed,
@@ -9183,7 +9292,7 @@ var PLAN_FRAGMENT_RESEARCH = `
 var PLAN_FRAGMENT_BUG = `
    **Bug task detection:** When a task's task type is "bug" or the title starts with "Bug:" or "Fix:", apply these rules:
    - **Auto-P1:** If the task's current priority is P2 or lower, upgrade it to "P1 High" via a boardCorrections entry in Part 2. Note the upgrade in Part 1 analysis.
-   - Replace the standard SCOPE (DO THIS) section with bug-specific sections:
+   - Inside SCOPE (DO THIS), use these bug-specific subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
      - **REPRODUCE:** Exact steps to reproduce the bug before touching any code. If the task notes describe the symptoms, include them. If not, the first build step is "confirm the bug reproduces."
      - **ROOT CAUSE:** One-sentence hypothesis for the root cause (what is wrong, not what the user sees). The builder must confirm or correct this before implementing a fix.
      - **MINIMAL FIX:** The smallest code change that resolves the root cause. "Bug fix \u2014 minimal blast radius. Change only what is necessary. Do not refactor surrounding code or expand scope."
@@ -9208,7 +9317,7 @@ var PLAN_FRAGMENT_SPIKE = `
    - Keep SCOPE BOUNDARY, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION as normal.
    - Spikes should be estimated conservatively: XS or S. If a spike needs M+ effort, it's not a spike \u2014 reclassify as a research task.`;
 var PLAN_FRAGMENT_DESIGN_BRIEF = `
-   **Design brief task detection:** When a task's task type is "design-brief", generate a DESIGN BRIEF handoff. Replace the standard SCOPE (DO THIS) section with these type-specific sections:
+   **Design brief task detection:** When a task's task type is "design-brief", generate a DESIGN BRIEF handoff. Inside SCOPE (DO THIS), use these type-specific subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - AUDIENCE: Who this design is for \u2014 persona and context of use (e.g. "non-technical Owner, first dashboard visit")
    - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`.impeccable.md\` (dev patterns, anti-patterns, component rules) AND \`docs/branding/brand-book.html\` (brand identity, positioning, voice canon) if present. If neither exists, state "No brand doc \u2014 Owner should define constraints before starting."
    - DELIVERABLE FORMAT: What the output looks like \u2014 design handoff package / annotated mockup / style spec. Be specific so the person doing the work knows what "done" means.
@@ -9216,7 +9325,7 @@ var PLAN_FRAGMENT_DESIGN_BRIEF = `
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION sections as normal.
    Add to ACCEPTANCE CRITERIA: "[ ] Deliverable format confirmed with Owner before starting" and "[ ] Design output is self-contained \u2014 includes enough context for a developer to implement without further clarification."`;
 var PLAN_FRAGMENT_RESEARCH_BRIEF = `
-   **Research brief task detection:** When a task's task type is "research-brief", generate a RESEARCH BRIEF handoff. Replace the standard SCOPE (DO THIS) section with:
+   **Research brief task detection:** When a task's task type is "research-brief", generate a RESEARCH BRIEF handoff. Inside SCOPE (DO THIS), use these subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - GOAL: The specific question this research answers \u2014 one sentence, phrased as a question (e.g. "What onboarding patterns do our top 3 competitors use?")
    - TIME-BOX: Maximum effort allowed \u2014 XS or S. Stop when the time-box is hit and report what was found, even if incomplete.
    - OUTPUT: Where findings land \u2014 a doc at \`docs/research/[topic]-findings.md\` or inline in the build report. State the path.
@@ -9224,7 +9333,7 @@ var PLAN_FRAGMENT_RESEARCH_BRIEF = `
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION as normal.
    Add to ACCEPTANCE CRITERIA: "[ ] Question answered OR time-box hit \u2014 whichever comes first" and "[ ] Findings doc saved before any follow-up tasks are submitted."`;
 var PLAN_FRAGMENT_MARKETING_BRIEF = `
-   **Marketing brief task detection:** When a task's task type is "marketing-brief", generate a MARKETING BRIEF handoff. Replace the standard SCOPE (DO THIS) section with:
+   **Marketing brief task detection:** When a task's task type is "marketing-brief", generate a MARKETING BRIEF handoff. Inside SCOPE (DO THIS), use these subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - AUDIENCE: Who this marketing content targets \u2014 persona, awareness level, channel context (e.g. "cold Discord visitor, zero PAPI context")
    - CHANNEL: Where this content lives \u2014 Discord, landing page, email, social, etc.
    - MESSAGE FRAME: The core message to land \u2014 one sentence. What does the reader need to believe after seeing this? (e.g. "PAPI makes AI-assisted building systematic, not chaotic.")
@@ -9232,7 +9341,7 @@ var PLAN_FRAGMENT_MARKETING_BRIEF = `
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION as normal.
    Add to ACCEPTANCE CRITERIA: "[ ] Message Frame confirmed with Owner before drafting" and "[ ] Final content reviewed by Owner before publishing."`;
 var PLAN_FRAGMENT_OPS_BRIEF = `
-   **Ops brief task detection:** When a task's task type is "ops-brief", generate an OPS BRIEF handoff. Replace the standard SCOPE (DO THIS) section with:
+   **Ops brief task detection:** When a task's task type is "ops-brief", generate an OPS BRIEF handoff. Inside SCOPE (DO THIS), use these subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - SYSTEM: Which system or service this ops task touches \u2014 Vercel, Railway, Supabase, GitHub Actions, DNS, etc.
    - RISK: What could go wrong \u2014 data loss, downtime, broken deployments. Include estimated blast radius (e.g. "affects all authenticated users").
    - ROLLBACK PLAN: Exact steps to undo the change if something breaks. Must be specific enough to execute under pressure.
@@ -10875,8 +10984,9 @@ async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber, force = false)
       }
       const invalidFields = validateHandoffScope(parsed);
       if (invalidFields.length > 0) {
+        const scopeMissing = invalidFields.includes("scope");
         warnings.push(
-          `Rejected handoff for ${handoff.taskId}: missing or empty ${invalidFields.join(", ")}. Handoffs without explicit scope produce ambiguous builds.`
+          `Rejected handoff for ${handoff.taskId}: missing or empty ${invalidFields.join(", ")}. Handoffs without explicit scope produce ambiguous builds.` + (scopeMissing ? ` If this is a bug/design-brief/research-brief/marketing-brief/ops-brief task, KEEP the "SCOPE (DO THIS)" header and nest the type-specific sections (REPRODUCE / ROOT CAUSE / MINIMAL FIX / \u2026) inside it \u2014 the parser only recognises the standard headers, so replacing SCOPE outright drops it entirely.` : "")
         );
         continue;
       }
@@ -12881,7 +12991,7 @@ async function assertSingleActiveCycle(adapter2, opts = {}) {
   }
   return notes;
 }
-async function validateAndPrepare(adapter2, force, callerUserId) {
+async function validateAndPrepare(adapter2, force, callerUserId, adapterType) {
   let mode;
   let cycleNumber;
   let strategyReviewWarning = "";
@@ -12943,7 +13053,7 @@ Run \`strategy_review\` first, or pass \`force: true\` to bypass this gate.`
     if (err instanceof Error && (err.message.startsWith("Strategy Review") || err.message.startsWith("Cycle ") || err.message.startsWith("Stale reviews"))) {
       throw err;
     }
-    const isPg = process.env.PAPI_ADAPTER === "pg" || process.env.PAPI_ADAPTER === "proxy";
+    const isPg = isDatabaseBackedAdapter(adapterType);
     throw new Error(
       isPg ? "Could not read cycle health from the database. Check your DATABASE_URL and verify the project exists." : "Could not read cycle health from PLANNING_LOG.md. Run setup first to initialise your PAPI project."
     );
@@ -13061,7 +13171,7 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
   tracker?.mark("validate_and_prepare");
   let t = startTimer();
   const prepareScope = await resolvePlanScope(adapter2, config2);
-  const { mode, cycleNumber, strategyReviewWarning } = await validateAndPrepare(adapter2, force, prepareScope.callerUserId);
+  const { mode, cycleNumber, strategyReviewWarning } = await validateAndPrepare(adapter2, force, prepareScope.callerUserId, config2.adapterType);
   const validateMs = t();
   const incomingCycle = cycleNumber + 1;
   tracker?.setStreamScope({ cycle: incomingCycle });
@@ -15281,6 +15391,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) },
@@ -15512,7 +15639,7 @@ ${lines.join("\n")}`;
     lastReviewCycle: lastReviewCycleNum,
     productBrief: cappedBrief,
     activeDecisions: formatActiveDecisionsForReview(decisions),
-    allBuildReports: buildReportsText,
+    allBuildReports: buildReportsWithDigest,
     sessionLog: formatCycleLog(recentLog),
     board: smartBoard,
     earnedPushback,
@@ -15977,7 +16104,7 @@ async function prepareStrategyReview(adapter2, force, projectRoot, adapterType,
       };
     }
   } catch {
-    const isPg = process.env.PAPI_ADAPTER === "pg" || process.env.PAPI_ADAPTER === "proxy";
+    const isPg = isDatabaseBackedAdapter(adapterType);
     throw new Error(
       isPg ? "Could not read cycle health from the database. Check your DATABASE_URL and verify the project exists." : "Could not read cycle health from PLANNING_LOG.md. Run setup first to initialise your PAPI project."
     );
@@ -16200,9 +16327,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 = [];
@@ -16399,13 +16548,13 @@ ${cleanContent}`;
 ${evidenceWarnings.map((w) => `- ${w}`).join("\n")}` : displayText;
   return { cycleNumber, displayText: fullText, writeBackFailed };
 }
-async function prepareStrategyChange(adapter2, text) {
+async function prepareStrategyChange(adapter2, text, adapterType) {
   let cycleNumber;
   try {
     const health = await adapter2.getCycleHealth();
     cycleNumber = health.totalCycles;
   } catch {
-    const isPg = process.env.PAPI_ADAPTER === "pg" || process.env.PAPI_ADAPTER === "proxy";
+    const isPg = isDatabaseBackedAdapter(adapterType);
     throw new Error(
       isPg ? "Could not read cycle health from the database. Check your DATABASE_URL and verify the project exists." : "Could not read cycle health from PLANNING_LOG.md. Run setup first to initialise your PAPI project."
     );
@@ -16924,7 +17073,7 @@ Decision event logged.`
       return errorResponse("text is required for strategy_change. Describe the strategic shift to apply.");
     }
     {
-      const result = await prepareStrategyChange(adapter2, text);
+      const result = await prepareStrategyChange(adapter2, text, _config.adapterType);
       return textResponse(
         `## PAPI Strategy Change \u2014 Prepare Phase (Cycle ${result.cycleNumber})
 
@@ -19752,6 +19901,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;
@@ -19832,6 +19984,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.";
@@ -22390,6 +22543,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
     } catch {
     }
   }
+  let appendedRows = [];
+  const findingRows = [];
   if (adapter2.appendCycleLearnings) {
     const learnings = [];
     const taskModule = task.module ?? "";
@@ -22417,10 +22572,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,
@@ -22432,47 +22629,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: "",
@@ -22481,20 +22679,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 {
       }
     }
@@ -22834,15 +23029,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",
@@ -22854,6 +23152,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",
@@ -22891,6 +23193,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.",
@@ -22922,8 +23237,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()}/`)) {
@@ -23012,6 +23327,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) {
@@ -23034,6 +23357,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 {
@@ -23048,7 +23409,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);
@@ -23077,7 +23438,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}
@@ -23089,6 +23450,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 = [];
@@ -23531,6 +23982,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.`,
@@ -23861,6 +24330,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) : "";
@@ -23870,7 +24357,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 = [
@@ -23959,6 +24446,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;
@@ -24005,7 +24506,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 });
@@ -24030,9 +24533,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 {
         }
@@ -27258,8 +27762,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);
       }
@@ -27330,8 +27834,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);
     }
@@ -27374,8 +27878,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);
     }
@@ -28159,8 +28663,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"]);
@@ -28369,9 +28959,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.");
       }
@@ -28487,7 +29083,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?.() ?? [],
@@ -28520,7 +29116,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;
@@ -28689,7 +29292,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";
@@ -28944,10 +29547,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);
@@ -29256,7 +29855,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)");
@@ -30071,8 +30670,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:
@@ -30135,8 +30734,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);
@@ -30422,34 +31021,75 @@ ${formatted}`, meta));
 }
 
 // src/lib/dist-staleness.ts
-import { statSync as statSync8 } from "fs";
+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;
-function isDistStale({ bootMs, distMtimeMs, skewMs = DEFAULT_SKEW_MS }) {
+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;
-function checkDistStaleness(now = Date.now()) {
-  if (cached && now - cached.at < STAT_TTL_MS) return cached.stale;
+var currentHash = BOOT_HASH;
+var announcedHash = null;
+function computeStale() {
+  if (!SELF_PATH || !BOOT_HASH) return false;
   let distMtimeMs = null;
   try {
-    distMtimeMs = statSync8(fileURLToPath3(import.meta.url)).mtimeMs;
+    distMtimeMs = statSync8(SELF_PATH).mtimeMs;
   } catch {
-    distMtimeMs = null;
+    return false;
   }
-  const stale = isDistStale({ bootMs: BOOT_MS, distMtimeMs });
+  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 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.
+  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 = {
@@ -30578,54 +31218,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;
@@ -31095,7 +31687,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 = [];
@@ -31121,7 +31713,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 {
@@ -31591,6 +32183,7 @@ var PAPI_TOOLS = [
   docActionPromoteTool,
   docDeleteTool,
   docReorderTool,
+  docReadTool,
   getSiblingAdsTool,
   handoffGenerateTool,
   scopeBriefTool,
@@ -31614,10 +32207,10 @@ function getToolMetadata() {
 }
 function createServer(adapter2, config2) {
   const __pkgFilename = fileURLToPath4(import.meta.url);
-  const __pkgDir = dirname5(__pkgFilename);
+  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 {
   }
@@ -31634,7 +32227,7 @@ function createServer(adapter2, config2) {
     );
   }
   const __filename = fileURLToPath4(import.meta.url);
-  const __dirname2 = dirname5(__filename);
+  const __dirname2 = dirname6(__filename);
   const skillsDir = join20(__dirname2, "..", "skills");
   function parseSkillFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
@@ -31795,6 +32388,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":
@@ -31936,10 +32531,11 @@ ${usageLine(decision.usage)}`;
     const footer = formatMetricsFooter(elapsed, usage, contextBytes);
     result.content.push({ type: "text", text: footer });
     try {
-      if (checkDistStaleness() && result.content.length > 0) {
+      const warning = consumeStalenessWarning();
+      if (warning && result.content.length > 0) {
         const first = result.content[0];
         if (first && typeof first.text === "string") {
-          first.text = stalenessWarning() + first.text;
+          first.text = warning + first.text;
         }
       }
     } catch {
@@ -32389,10 +32985,10 @@ async function dispatchRequest(args) {
 }
 
 // src/index.ts
-var __dirname = dirname6(fileURLToPath5(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 {
 }