@papi-ai/server 0.7.11 → 0.7.13

package/dist/index.js

@@ -1453,7 +1453,12 @@ var init_dist2 = __esm({
       research: 2,
       spike: 2,
       idea: 3,
-      discovery: 1
+      discovery: 1,
+      // Non-code brief types for non-technical Owners (AD-12)
+      "design-brief": 1,
+      "research-brief": 1,
+      "marketing-brief": 1,
+      "ops-brief": 1
     };
     VALID_EFFORT_SIZES = /* @__PURE__ */ new Set(["XS", "S", "M", "L", "XL"]);
     SECTION_HEADERS = [
@@ -1575,11 +1580,13 @@ ${TABLE_SEPARATOR}
       }
       /** Prepend a new cycle log entry at the top of the Cycle Log section. */
       async writeCycleLogEntry(entry) {
-        if (!entry.uuid) {
-          entry = { ...entry, uuid: randomUUID6() };
-        }
+        const patched = {
+          ...entry,
+          uuid: entry.uuid || randomUUID6(),
+          date: entry.date ?? (/* @__PURE__ */ new Date()).toISOString()
+        };
         const content = await this.read("SPRINT_LOG.md");
-        await this.write("SPRINT_LOG.md", prependCycleLogEntry(entry, content));
+        await this.write("SPRINT_LOG.md", prependCycleLogEntry(patched, content));
       }
       /** Write a strategy review — for md adapter, delegates to cycle log. */
       async writeStrategyReview(review) {
@@ -2061,6 +2068,102 @@ ${footer}`);
         await this.write("STRATEGY_RECOMMENDATIONS.md", updated);
       }
       // -------------------------------------------------------------------------
+      // Strategy Review Agenda (markdown persistence)
+      // -------------------------------------------------------------------------
+      async addAgendaTopic(input) {
+        const id = randomUUID6();
+        const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+        const full = {
+          id,
+          topic: input.topic,
+          source: input.source,
+          sourceCycle: input.sourceCycle,
+          status: "pending",
+          createdAt
+        };
+        const content = await this.readOptional("STRATEGY_REVIEW_AGENDA.md");
+        const header = "# Strategy Review Agenda\n\n<!-- PAPI-ADAPTER: parse the yaml block below -->\n\n<!-- PAPI-YAML-START -->\ntopics:\n";
+        const footer = "<!-- PAPI-YAML-END -->\n";
+        const entry = [
+          `  - id: ${full.id}`,
+          `    topic: ${JSON.stringify(full.topic)}`,
+          `    source: ${full.source}`,
+          full.sourceCycle != null ? `    source_cycle: ${full.sourceCycle}` : null,
+          `    status: ${full.status}`,
+          `    created_at: ${full.createdAt}`
+        ].filter(Boolean).join("\n");
+        if (!content) {
+          await this.write("STRATEGY_REVIEW_AGENDA.md", `${header}${entry}
+${footer}`);
+        } else {
+          const insertPoint = content.indexOf("<!-- PAPI-YAML-END -->");
+          if (insertPoint === -1) {
+            await this.write("STRATEGY_REVIEW_AGENDA.md", `${header}${entry}
+${footer}`);
+          } else {
+            const updated = content.slice(0, insertPoint) + entry + "\n" + content.slice(insertPoint);
+            await this.write("STRATEGY_REVIEW_AGENDA.md", updated);
+          }
+        }
+        return full;
+      }
+      async getPendingAgendaTopics() {
+        const content = await this.readOptional("STRATEGY_REVIEW_AGENDA.md");
+        if (!content) return [];
+        const yamlStart = content.indexOf("<!-- PAPI-YAML-START -->");
+        const yamlEnd = content.indexOf("<!-- PAPI-YAML-END -->");
+        if (yamlStart === -1 || yamlEnd === -1) return [];
+        const yamlBlock = content.slice(yamlStart + "<!-- PAPI-YAML-START -->".length, yamlEnd).trim();
+        const entries = yamlBlock.split(/(?=\s+-\s+id:)/);
+        const topics = [];
+        for (const block of entries) {
+          const idMatch = block.match(/id:\s+(.+)/);
+          const topicMatch = block.match(/topic:\s+(.+)/);
+          const sourceMatch = block.match(/source:\s+(\S+)/);
+          const statusMatch = block.match(/status:\s+(\S+)/);
+          const createdMatch = block.match(/created_at:\s+(.+)/);
+          const sourceCycleMatch = block.match(/source_cycle:\s+(\d+)/);
+          if (!idMatch || !topicMatch || !sourceMatch || !statusMatch || !createdMatch) continue;
+          if (statusMatch[1].trim() !== "pending") continue;
+          let parsedTopic = topicMatch[1].trim();
+          if (parsedTopic.startsWith('"') && parsedTopic.endsWith('"')) {
+            try {
+              parsedTopic = JSON.parse(parsedTopic);
+            } catch {
+            }
+          }
+          topics.push({
+            id: idMatch[1].trim(),
+            topic: parsedTopic,
+            source: sourceMatch[1].trim(),
+            sourceCycle: sourceCycleMatch ? parseInt(sourceCycleMatch[1], 10) : void 0,
+            status: "pending",
+            createdAt: createdMatch[1].trim()
+          });
+        }
+        return topics;
+      }
+      async markAgendaTopicsAddressed(ids, cycleNumber) {
+        if (ids.length === 0) return;
+        const content = await this.readOptional("STRATEGY_REVIEW_AGENDA.md");
+        if (!content) return;
+        let updated = content;
+        const addressedAt = (/* @__PURE__ */ new Date()).toISOString();
+        for (const id of ids) {
+          const statusPattern = new RegExp(`(\\s+-\\s+id:\\s+${id}\\n(?:.*\\n)*?\\s+status:\\s+)pending`);
+          updated = updated.replace(statusPattern, `$1addressed`);
+          const insertionAnchor = new RegExp(`(\\s+-\\s+id:\\s+${id}\\n(?:.*\\n)*?\\s+created_at:\\s+[^\\n]+)\\n`);
+          const match = updated.match(insertionAnchor);
+          if (match && !match[0].includes("addressed_at:")) {
+            updated = updated.replace(insertionAnchor, `$1
+    addressed_at: ${addressedAt}
+    addressed_in_review: ${cycleNumber}
+`);
+          }
+        }
+        await this.write("STRATEGY_REVIEW_AGENDA.md", updated);
+      }
+      // -------------------------------------------------------------------------
       // Decision Events & Scores (markdown persistence)
       // -------------------------------------------------------------------------
       async appendDecisionEvent(event) {
@@ -3708,7 +3811,7 @@ var init_connection = __esm({
 
 // ../../node_modules/postgres/src/subscribe.js
 function Subscribe(postgres2, options) {
-  const subscribers = /* @__PURE__ */ new Map(), slot = "postgresjs_" + Math.random().toString(36).slice(2), state = {};
+  const subscribers = /* @__PURE__ */ new Map(), slot = "postgresjs_" + Math.random().toString(36).slice(2), state2 = {};
   let connection2, stream, ended = false;
   const sql = subscribe.sql = postgres2({
     ...options,
@@ -3725,7 +3828,7 @@ function Subscribe(postgres2, options) {
       if (ended)
         return;
       stream = null;
-      state.pid = state.secret = void 0;
+      state2.pid = state2.secret = void 0;
       connected(await init(sql, slot, options.publications));
       subscribers.forEach((event) => event.forEach(({ onsubscribe }) => onsubscribe()));
     },
@@ -3756,13 +3859,13 @@ function Subscribe(postgres2, options) {
       connected(x);
       onsubscribe();
       stream && stream.on("error", onerror);
-      return { unsubscribe, state, sql };
+      return { unsubscribe, state: state2, sql };
     });
   }
   function connected(x) {
     stream = x.stream;
-    state.pid = x.state.pid;
-    state.secret = x.state.secret;
+    state2.pid = x.state.pid;
+    state2.secret = x.state.secret;
   }
   async function init(sql2, slot2, publications) {
     if (!publications)
@@ -3774,7 +3877,7 @@ function Subscribe(postgres2, options) {
     const stream2 = await sql2.unsafe(
       `START_REPLICATION SLOT ${slot2} LOGICAL ${x.consistent_point} (proto_version '1', publication_names '${publications}')`
     ).writable();
-    const state2 = {
+    const state3 = {
       lsn: Buffer.concat(x.consistent_point.split("/").map((x2) => Buffer.from(("00000000" + x2).slice(-8), "hex")))
     };
     stream2.on("data", data);
@@ -3786,9 +3889,9 @@ function Subscribe(postgres2, options) {
     }
     function data(x2) {
       if (x2[0] === 119) {
-        parse(x2.subarray(25), state2, sql2.options.parsers, handle, options.transform);
+        parse(x2.subarray(25), state3, sql2.options.parsers, handle, options.transform);
       } else if (x2[0] === 107 && x2[17]) {
-        state2.lsn = x2.subarray(1, 9);
+        state3.lsn = x2.subarray(1, 9);
         pong();
       }
     }
@@ -3804,7 +3907,7 @@ function Subscribe(postgres2, options) {
     function pong() {
       const x2 = Buffer.alloc(34);
       x2[0] = "r".charCodeAt(0);
-      x2.fill(state2.lsn, 1);
+      x2.fill(state3.lsn, 1);
       x2.writeBigInt64BE(BigInt(Date.now() - Date.UTC(2e3, 0, 1)) * BigInt(1e3), 25);
       stream2.write(x2);
     }
@@ -3816,12 +3919,12 @@ function Subscribe(postgres2, options) {
 function Time(x) {
   return new Date(Date.UTC(2e3, 0, 1) + Number(x / BigInt(1e3)));
 }
-function parse(x, state, parsers2, handle, transform) {
+function parse(x, state2, parsers2, handle, transform) {
   const char = (acc, [k, v]) => (acc[k.charCodeAt(0)] = v, acc);
   Object.entries({
     R: (x2) => {
       let i = 1;
-      const r = state[x2.readUInt32BE(i)] = {
+      const r = state2[x2.readUInt32BE(i)] = {
         schema: x2.toString("utf8", i += 4, i = x2.indexOf(0, i)) || "pg_catalog",
         table: x2.toString("utf8", i + 1, i = x2.indexOf(0, i + 1)),
         columns: Array(x2.readUInt16BE(i += 2)),
@@ -3848,12 +3951,12 @@ function parse(x, state, parsers2, handle, transform) {
     },
     // Origin
     B: (x2) => {
-      state.date = Time(x2.readBigInt64BE(9));
-      state.lsn = x2.subarray(1, 9);
+      state2.date = Time(x2.readBigInt64BE(9));
+      state2.lsn = x2.subarray(1, 9);
     },
     I: (x2) => {
       let i = 1;
-      const relation = state[x2.readUInt32BE(i)];
+      const relation = state2[x2.readUInt32BE(i)];
       const { row } = tuples(x2, relation.columns, i += 7, transform);
       handle(row, {
         command: "insert",
@@ -3862,7 +3965,7 @@ function parse(x, state, parsers2, handle, transform) {
     },
     D: (x2) => {
       let i = 1;
-      const relation = state[x2.readUInt32BE(i)];
+      const relation = state2[x2.readUInt32BE(i)];
       i += 4;
       const key = x2[i] === 75;
       handle(
@@ -3876,7 +3979,7 @@ function parse(x, state, parsers2, handle, transform) {
     },
     U: (x2) => {
       let i = 1;
-      const relation = state[x2.readUInt32BE(i)];
+      const relation = state2[x2.readUInt32BE(i)];
       i += 4;
       const key = x2[i] === 75;
       const xs = key || x2[i] === 79 ? tuples(x2, relation.columns, i += 3, transform) : null;
@@ -4612,6 +4715,7 @@ function rowToCycleLogEntry(row) {
   if (row.notes != null) entry.notes = row.notes;
   if (row.task_count != null) entry.taskCount = row.task_count;
   if (row.effort_points != null) entry.effortPoints = row.effort_points;
+  if (row.updated_at != null) entry.date = row.updated_at;
   return entry;
 }
 function rowToPhase(row) {
@@ -6276,7 +6380,7 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
       async getCycleLog(limit) {
         if (limit != null) {
           const rows2 = await this.sql`
-        SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points
+        SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points, updated_at
         FROM planning_log_entries
         WHERE project_id = ${this.projectId}
         ORDER BY cycle_number DESC
@@ -6285,7 +6389,7 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
           return rows2.map(rowToCycleLogEntry);
         }
         const rows = await this.sql`
-      SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points
+      SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points, updated_at
       FROM planning_log_entries
       WHERE project_id = ${this.projectId}
       ORDER BY cycle_number DESC
@@ -6295,7 +6399,7 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
       }
       async getCycleLogSince(cycleNumber) {
         const rows = await this.sql`
-      SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points
+      SELECT id, cycle_number, title, content, carry_forward, notes, task_count, effort_points, updated_at
       FROM planning_log_entries
       WHERE project_id = ${this.projectId}
         AND cycle_number >= ${cycleNumber}
@@ -6346,7 +6450,8 @@ ${newParts.join("\n")}` : newParts.join("\n");
         carry_forward = EXCLUDED.carry_forward,
         notes = EXCLUDED.notes,
         task_count = EXCLUDED.task_count,
-        effort_points = EXCLUDED.effort_points
+        effort_points = EXCLUDED.effort_points,
+        updated_at = now()
     `;
       }
       async writeStrategyReview(review) {
@@ -7560,6 +7665,50 @@ ${newParts.join("\n")}` : newParts.join("\n");
       UPDATE strategy_recommendations
       SET status = 'actioned', dismissal_reason = ${reason}, updated_at = now()
       WHERE id = ${id} AND project_id = ${this.projectId}
+    `;
+      }
+      // -------------------------------------------------------------------------
+      // Strategy Review Agenda
+      // -------------------------------------------------------------------------
+      async addAgendaTopic(input) {
+        const [row] = await this.sql`
+      INSERT INTO strategy_review_agenda (project_id, topic, source, source_cycle)
+      VALUES (${this.projectId}, ${input.topic}, ${input.source}, ${input.sourceCycle ?? null})
+      RETURNING id, topic, source, source_cycle, status, created_at
+    `;
+        return {
+          id: row.id,
+          topic: row.topic,
+          source: row.source,
+          sourceCycle: row.source_cycle ?? void 0,
+          status: row.status,
+          createdAt: row.created_at
+        };
+      }
+      async getPendingAgendaTopics() {
+        const rows = await this.sql`
+      SELECT id, topic, source, source_cycle, status, created_at, addressed_at, addressed_in_review
+      FROM strategy_review_agenda
+      WHERE project_id = ${this.projectId} AND status = 'pending'
+      ORDER BY created_at ASC
+    `;
+        return rows.map((r) => ({
+          id: r.id,
+          topic: r.topic,
+          source: r.source,
+          sourceCycle: r.source_cycle ?? void 0,
+          status: "pending",
+          createdAt: r.created_at,
+          addressedAt: r.addressed_at ?? void 0,
+          addressedInReview: r.addressed_in_review ?? void 0
+        }));
+      }
+      async markAgendaTopicsAddressed(ids, cycleNumber) {
+        if (ids.length === 0) return;
+        await this.sql`
+      UPDATE strategy_review_agenda
+      SET status = 'addressed', addressed_at = now(), addressed_in_review = ${cycleNumber}
+      WHERE project_id = ${this.projectId} AND id = ANY(${ids}::uuid[])
     `;
       }
       // -------------------------------------------------------------------------
@@ -7813,7 +7962,8 @@ ${r.content}` + (r.carry_forward ? `
         await this.sql`
       INSERT INTO plan_runs (
         project_id, cycle_number, context_bytes, duration_ms,
-        task_count_in, task_count_out, backlog_depth, notes
+        task_count_in, task_count_out, backlog_depth, notes,
+        token_usage, source
       ) VALUES (
         ${this.projectId},
         ${entry.cycleNumber},
@@ -7822,7 +7972,9 @@ ${r.content}` + (r.carry_forward ? `
         ${entry.taskCountIn ?? null},
         ${entry.taskCountOut ?? null},
         ${entry.backlogDepth ?? null},
-        ${entry.notes ?? null}
+        ${entry.notes ?? null},
+        ${entry.tokenUsage ? this.sql.json(entry.tokenUsage) : null},
+        ${entry.source ?? null}
       )
     `;
       }
@@ -7958,7 +8110,8 @@ ${r.content}` + (r.carry_forward ? `
           title = EXCLUDED.title,
           content = EXCLUDED.content,
           carry_forward = EXCLUDED.carry_forward,
-          notes = EXCLUDED.notes
+          notes = EXCLUDED.notes,
+          updated_at = now()
       `;
           if (payload.healthUpdates.boardHealth != null || payload.healthUpdates.strategicDirection != null) {
             const [latest] = await tx`
@@ -8748,6 +8901,7 @@ __export(git_exports, {
   getHeadCommitSha: () => getHeadCommitSha,
   getLatestTag: () => getLatestTag,
   getOriginRepoSlug: () => getOriginRepoSlug,
+  getPullRequestUrl: () => getPullRequestUrl,
   getUnmergedBranches: () => getUnmergedBranches,
   gitPull: () => gitPull,
   gitPush: () => gitPush,
@@ -8757,9 +8911,11 @@ __export(git_exports, {
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
   isGitRepo: () => isGitRepo,
+  listGroupedCycleBranches: () => listGroupedCycleBranches,
   mergePullRequest: () => mergePullRequest,
   resolveBaseBranch: () => resolveBaseBranch,
   runAutoCommit: () => runAutoCommit,
+  squashMergePullRequest: () => squashMergePullRequest,
   stageAllAndCommit: () => stageAllAndCommit,
   stageDirAndCommit: () => stageDirAndCommit,
   tagExists: () => tagExists,
@@ -9213,6 +9369,68 @@ function runAutoCommit(projectRoot, commitFn) {
     return `Auto-commit failed: ${err instanceof Error ? err.message : String(err)}`;
   }
 }
+function getPullRequestUrl(cwd, branch) {
+  try {
+    const output = execFileSync(
+      "gh",
+      ["pr", "view", branch, "--json", "url", "--jq", ".url"],
+      { cwd, encoding: "utf-8" }
+    ).trim();
+    return output || null;
+  } catch {
+    return null;
+  }
+}
+function squashMergePullRequest(cwd, branch) {
+  const repo = getOriginRepoSlug(cwd);
+  const baseArgs = ["pr", "merge", branch, "--squash", "--delete-branch"];
+  if (repo) baseArgs.push("--repo", repo);
+  for (let attempt = 1; attempt <= MERGE_MAX_RETRIES; attempt++) {
+    try {
+      execFileSync("gh", baseArgs, { cwd, encoding: "utf-8" });
+      return { success: true, message: `Squash-merged PR for '${branch}' and deleted branch.` };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("not mergeable") && attempt < MERGE_MAX_RETRIES) {
+        sleepSync(MERGE_RETRY_DELAY_MS);
+        continue;
+      }
+      return { success: false, message: `PR squash-merge failed: ${msg}` };
+    }
+  }
+  return { success: false, message: "PR squash-merge failed: max retries exceeded" };
+}
+function listGroupedCycleBranches(cwd, cycleNum, baseBranch) {
+  const prefix = `feat/cycle-${cycleNum}-`;
+  try {
+    const remoteOutput = execFileSync(
+      "git",
+      ["ls-remote", "--heads", "origin", `${prefix}*`],
+      { cwd, encoding: "utf-8" }
+    ).trim();
+    if (!remoteOutput) return [];
+    const remoteBranches = remoteOutput.split("\n").map((line) => line.split("	")[1]?.replace("refs/heads/", "").trim()).filter((b2) => !!b2 && b2.startsWith(prefix));
+    return remoteBranches.filter((branch) => {
+      try {
+        const branchTip = execFileSync(
+          "git",
+          ["rev-parse", `origin/${branch}`],
+          { cwd, encoding: "utf-8" }
+        ).trim();
+        execFileSync(
+          "git",
+          ["merge-base", "--is-ancestor", branchTip, baseBranch],
+          { cwd, stdio: "ignore" }
+        );
+        return false;
+      } catch {
+        return true;
+      }
+    });
+  } catch {
+    return getUnmergedBranches(cwd, baseBranch).filter((b2) => b2.startsWith(prefix));
+  }
+}
 function getFilesChangedFromBase(cwd, baseBranch) {
   try {
     const mergeBase = execFileSync("git", ["merge-base", baseBranch, "HEAD"], { cwd, encoding: "utf-8" }).trim();
@@ -9234,9 +9452,9 @@ var init_git = __esm({
 });
 
 // src/index.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { createServer as createHttpServer } from "http";
-import { dirname as dirname2, join as join11 } from "path";
+import { dirname as dirname2, join as join13 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -9264,11 +9482,32 @@ function loadConfig() {
   const lightMode = process.env.PAPI_LIGHT_MODE === "true";
   const projectOwner = process.env.PAPI_OWNER ?? "Cathal";
   const skipProjectSpecificRules = process.env.PAPI_SKIP_PROJECT_RULES === "true";
+  const userId = process.env.PAPI_USER_ID || void 0;
+  const telemetryEnabled = process.env.PAPI_TELEMETRY !== "off" && process.env.PAPI_TELEMETRY !== "false";
   const papiEndpoint = process.env.PAPI_ENDPOINT;
   const dataEndpoint = process.env.PAPI_DATA_ENDPOINT;
   const databaseUrl = process.env.DATABASE_URL;
   const explicitAdapter = process.env.PAPI_ADAPTER;
-  const adapterType = papiEndpoint ? "pg" : databaseUrl && explicitAdapter === "pg" ? "pg" : dataEndpoint ? "proxy" : explicitAdapter ? explicitAdapter : databaseUrl ? "pg" : "proxy";
+  const projectId = process.env.PAPI_PROJECT_ID;
+  let adapterType = papiEndpoint ? "pg" : databaseUrl && explicitAdapter === "pg" ? "pg" : dataEndpoint ? "proxy" : explicitAdapter ? explicitAdapter : databaseUrl ? "pg" : "proxy";
+  if (projectId && !databaseUrl && !papiEndpoint && adapterType === "md") {
+    adapterType = "proxy";
+    console.error("[papi] PAPI_PROJECT_ID detected \u2014 switching to proxy adapter (md adapter blocked for external users).");
+  }
+  if (adapterType === "md" && !userId) {
+    throw new Error(
+      `PAPI requires a free account to run in local mode.
+
+Create your account at https://getpapi.ai/setup \u2014 it takes under a minute.
+Your project data stays on your machine. The account lets PAPI identify you
+and unlocks dashboard features when you're ready.
+
+After signing up, add this to your .mcp.json env config:
+  "PAPI_USER_ID": "your-email@example.com"
+
+Already have an account? Make sure PAPI_USER_ID is set in your .mcp.json env config.`
+    );
+  }
   return {
     projectRoot,
     papiDir: path.join(projectRoot, ".papi"),
@@ -9280,7 +9519,9 @@ function loadConfig() {
     papiEndpoint,
     lightMode,
     projectOwner,
-    skipProjectSpecificRules
+    skipProjectSpecificRules,
+    userId,
+    telemetryEnabled
   };
 }
 
@@ -9373,7 +9614,25 @@ async function createAdapter(optionsOrType, maybePapiDir) {
               console.error("[papi]   Set PAPI_USER_ID in your .mcp.json env to fix this.");
             }
           }
-          await pgAdapter.createProject({ id: projectId, slug, name: slug, papi_dir: papiDir, user_id: userId });
+          let skipCreate = false;
+          if (userId) {
+            const bySlug = await pgAdapter.listProjects({ slug });
+            const userDup = bySlug.find((p) => p.user_id === userId);
+            if (userDup) {
+              console.error(`[papi] \u26A0 Project '${slug}' already exists for this user (id: ${userDup.id}).`);
+              console.error(`[papi]   Update PAPI_PROJECT_ID=${userDup.id} in .mcp.json to avoid a duplicate.`);
+              skipCreate = true;
+            }
+          }
+          if (!skipCreate) {
+            await pgAdapter.createProject({ id: projectId, slug, name: slug, papi_dir: papiDir, user_id: userId });
+          }
+        } else if (existing.user_id) {
+          const configuredUserId = process.env["PAPI_USER_ID"] ?? detectUserId();
+          if (configuredUserId && existing.user_id !== configuredUserId) {
+            console.error(`[papi] \u26A0 PAPI_PROJECT_ID=${projectId} belongs to a different user.`);
+            console.error("[papi]   Run papi setup or update PAPI_PROJECT_ID in .mcp.json.");
+          }
         }
         await pgAdapter.close();
       } catch {
@@ -9482,8 +9741,9 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
 }
 
 // src/server.ts
+import { readFileSync as readFileSync5 } from "fs";
 import { access as access4, readdir as readdir2, readFile as readFile5 } from "fs/promises";
-import { join as join10, dirname } from "path";
+import { join as join12, dirname } from "path";
 import { fileURLToPath } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -9689,6 +9949,17 @@ ${formatted}`;
   }
   return sections.join("\n\n");
 }
+function formatCandidateTaskFullNotes(tasks) {
+  const candidates = tasks.filter((t) => !PLAN_EXCLUDED_STATUSES.has(t.status)).filter((t) => (t.notes?.length ?? 0) > PLAN_NOTES_MAX_LENGTH);
+  if (candidates.length === 0) return void 0;
+  const lines = candidates.map((t) => `**${t.id}** \u2014 ${t.title}
+${t.notes}`);
+  return [
+    `${candidates.length} candidate task(s) have notes longer than ${PLAN_NOTES_MAX_LENGTH} chars. Full untruncated notes below \u2014 reference these when generating BUILD HANDOFFs so submitter context, constraints, and reasoning are preserved. The Board section above uses truncated notes for concise task selection; this section supplies the missing detail for tasks you choose to schedule.`,
+    "",
+    ...lines
+  ].join("\n\n");
+}
 function formatBoardForReview(tasks) {
   if (tasks.length === 0) return "No tasks on the board.";
   return tasks.map(
@@ -10510,6 +10781,7 @@ Standard planning cycle with full board review.
    **Security section guidance:** Each handoff includes a SECURITY CONSIDERATIONS section. Populate it when the task involves: data exposure risks (PII, secrets in logs/storage), secrets or credentials handling (API keys, tokens, env vars), auth/access control changes, or dependency security risks (new packages, version changes). For pure refactoring, documentation, prompt-text, or UI-only tasks, write "None \u2014 no security-relevant changes".
    **Estimation calibration:** Estimate **XS** for: copy/text-only changes, single string replacements, config tweaks, and any task where the scope is "change words in an existing file" with no logic changes. Estimate **S** for: wiring existing adapter methods, adding API routes following established patterns, modifying prompts, or documentation-only changes. Default to S for pattern-following work. Only use M when genuine new architecture, new DB tables, or multi-file architectural changes are needed. Historical data shows systematic over-estimation (198 over vs 8 under out of 528 tasks) \u2014 when in doubt, estimate smaller. If an "Estimation Calibration (Historical)" section is provided in the context below, use its data to adjust your estimates \u2014 it shows how often each estimated size matched the actual effort. Pay special attention to systematic over/under-estimation patterns (e.g. if M\u2192S happens frequently, estimate S instead of M for similar work).
    **Reference docs:** If a task's notes include a \`Reference:\` path (e.g. \`Reference: docs/architecture/papi-brain-v1.md\`), include a REFERENCE DOCS section in the BUILD HANDOFF with those paths. This tells the builder to read the referenced doc for background context before implementing. Do NOT omit or summarise the reference \u2014 pass it through so the builder can access the full document. Only tasks with explicit \`Reference:\` paths in their notes should have this section.
+   **Full notes lookup:** Notes in the Board section are truncated to 300 chars for concise task selection. When generating a BUILD HANDOFF for a task, check the "Full Notes for Candidate Tasks" section (if present in context) for that task's complete untruncated notes before writing SCOPE, SCOPE BOUNDARY, and PRE-MORTEM. Submitter context, constraints, and reasoning often live past the 300-char cutoff and must not be dropped from the handoff.
    **Pre-build verification:** EVERY handoff MUST include a PRE-BUILD VERIFICATION section listing 2-5 specific file paths the builder should read before implementing. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. This is the #1 prevention mechanism for wasted build slots (C120, C125, C126 all scheduled already-shipped work). If the builder finds >80% of the scope already implemented, they report "already built" instead of re-implementing.
    **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. Omit this section entirely for projects with fewer than 10 cycles.
    **Build order in cycle log:** If any intra-cycle dependencies were detected in this cycle, include a "Build Order" paragraph in \`cycleLogNotes\` showing the recommended build sequence as arrow chains (e.g. "Build order: task-123 \u2192 task-124; task-130 standalone"). Skip this paragraph when no dependencies exist.
@@ -10740,6 +11012,7 @@ Standard planning cycle with full board review.
    **Security section guidance:** Each handoff includes a SECURITY CONSIDERATIONS section. Populate it when the task involves: data exposure risks (PII, secrets in logs/storage), secrets or credentials handling (API keys, tokens, env vars), auth/access control changes, or dependency security risks (new packages, version changes). For pure refactoring, documentation, prompt-text, or UI-only tasks, write "None \u2014 no security-relevant changes".
    **Estimation calibration:** Estimate **XS** for: copy/text-only changes, single string replacements, config tweaks, and any task where the scope is "change words in an existing file" with no logic changes. Estimate **S** for: wiring existing adapter methods, adding API routes following established patterns, modifying prompts, or documentation-only changes. Default to S for pattern-following work. Only use M when genuine new architecture, new DB tables, or multi-file architectural changes are needed. Historical data shows systematic over-estimation (198 over vs 8 under out of 528 tasks) \u2014 when in doubt, estimate smaller. If an "Estimation Calibration (Historical)" section is provided in the context below, use its data to adjust your estimates \u2014 it shows how often each estimated size matched the actual effort. Pay special attention to systematic over/under-estimation patterns (e.g. if M\u2192S happens frequently, estimate S instead of M for similar work).
    **Reference docs:** If a task's notes include a \`Reference:\` path (e.g. \`Reference: docs/architecture/papi-brain-v1.md\`), include a REFERENCE DOCS section in the BUILD HANDOFF with those paths. This tells the builder to read the referenced doc for background context before implementing. Do NOT omit or summarise the reference \u2014 pass it through so the builder can access the full document. Only tasks with explicit \`Reference:\` paths in their notes should have this section.
+   **Full notes lookup:** Notes in the Board section are truncated to 300 chars for concise task selection. When generating a BUILD HANDOFF for a task, check the "Full Notes for Candidate Tasks" section (if present in context) for that task's complete untruncated notes before writing SCOPE, SCOPE BOUNDARY, and PRE-MORTEM. Submitter context, constraints, and reasoning often live past the 300-char cutoff and must not be dropped from the handoff.
    **Pre-build verification:** EVERY handoff MUST include a PRE-BUILD VERIFICATION section listing 2-5 specific file paths the builder should read before implementing. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. This is the #1 prevention mechanism for wasted build slots (C120, C125, C126 all scheduled already-shipped work). If the builder finds >80% of the scope already implemented, they report "already built" instead of re-implementing.
    **Pre-mortem:** For projects with 10+ cycles, include a PRE-MORTEM section in every BUILD HANDOFF with 1-3 bullet points: (a) most likely technical blocker based on module history, (b) integration risk with adjacent systems, (c) scope creep signal \u2014 what the builder might be tempted to expand beyond scope. Draw from \`dead_ends\` and \`surprises\` in recent build reports for the same module. Omit this section entirely for projects with fewer than 10 cycles.
    **Intra-cycle dependency detection:** After selecting cycle tasks, check every pair for build-order dependencies. Two tasks A and B have an intra-cycle dependency when A must be built before B because B consumes an artifact A creates \u2014 e.g. A adds a new adapter method that B calls, A creates a DB migration B depends on, A introduces a new shared type B imports, A refactors a utility B modifies. Signals: same module + adjacent scope (one is "add X", another is "use X"), or notes explicitly reference the other task. For each dependency detected: (a) populate the DEPENDS ON section in the dependent task's BUILD HANDOFF with the upstream task ID(s); (b) add a \`boardCorrections\` entry for the dependent task with \`updates.dependsOn\` set to the comma-separated upstream IDs \u2014 this persists the dependency so the builder's runtime can reuse the upstream branch; (c) keep SCOPE sections independent but note the ordering in "Why now". Do NOT invent dependencies where tasks merely share a module \u2014 only real build-order coupling counts. Linear chains only \u2014 no multi-level graph resolution. When in doubt, omit.
@@ -10798,6 +11071,9 @@ function buildPlanUserMessage(ctx) {
     }) : PLAN_FULL_INSTRUCTIONS;
     parts.push(instructions);
   }
+  if (ctx.foundationalTasksGuidance) {
+    parts.push("", ctx.foundationalTasksGuidance);
+  }
   if (ctx.skipHandoffs) {
     parts.push(
       "",
@@ -10843,6 +11119,9 @@ function buildPlanUserMessage(ctx) {
     if (ctx.board) {
       parts.push("### Board", "", ctx.board, "");
     }
+    if (ctx.candidateTaskFullNotes) {
+      parts.push("### Full Notes for Candidate Tasks", "", ctx.candidateTaskFullNotes, "");
+    }
     if (ctx.preAssignedTasks) {
       parts.push("### Pre-Assigned Tasks", "", ctx.preAssignedTasks, "");
     }
@@ -11316,6 +11595,9 @@ function buildReviewUserMessage(ctx) {
   if (ctx.docActionStaleness) {
     parts.push("### Doc Action Staleness", "", ctx.docActionStaleness, "");
   }
+  if (ctx.pendingAgendaTopics) {
+    parts.push("### Queued Agenda Topics", "", "_Topics queued via `strategy_agenda` since the last review. Address each one in this review \u2014 they will be auto-marked as addressed on apply._", "", ctx.pendingAgendaTopics, "");
+  }
   return parts.join("\n");
 }
 function parseReviewStructuredOutput(raw) {
@@ -12002,6 +12284,64 @@ function stripTasksForPlan(tasks) {
     hasHandoff: !!buildHandoff
   }));
 }
+var BRIEF_SECTIONS = [
+  { name: "title", pattern: /^#\s+\S/m },
+  {
+    name: "target audience",
+    pattern: /\b(target users?|audience|for whom|who (it'?s for|uses|it serves|we're building))/i
+  },
+  {
+    name: "problem statement",
+    pattern: /\b(problem|pain point|why it matters|what problem|solves?)/i
+  },
+  {
+    name: "solution / vision",
+    pattern: /\b(solution|approach|vision|what (it|we) do|how it works|value proposition)/i
+  },
+  {
+    name: "GTM / distribution",
+    pattern: /\b(GTM|go[- ]to[- ]market|distribution|channel|pricing|how (users?|people) (discover|find|reach))/i
+  }
+];
+function assessBriefThinness(brief) {
+  const TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
+  const briefWithoutTemplate = brief.replace(TEMPLATE_MARKER, "");
+  const populated = [];
+  const missing = [];
+  for (const section of BRIEF_SECTIONS) {
+    if (section.pattern.test(briefWithoutTemplate)) populated.push(section.name);
+    else missing.push(section.name);
+  }
+  return { populatedSections: populated, missingSections: missing };
+}
+function computeFoundationalTasksGuidance(cycleNumber, brief) {
+  if (cycleNumber > 1) return void 0;
+  const { populatedSections, missingSections } = assessBriefThinness(brief);
+  if (populatedSections.length >= 4) return void 0;
+  const populatedList = populatedSections.length > 0 ? populatedSections.join(", ") : "none";
+  const missingList = missingSections.join(", ");
+  return [
+    "## FOUNDATIONAL TASKS GUIDANCE",
+    "",
+    `The project brief is thin \u2014 only ${populatedSections.length} of 5 key sections are clearly populated (${populatedList}). Missing or weak sections: ${missingList}.`,
+    "",
+    "Generate 3-5 foundational research/discovery tasks targeting the MISSING sections. These help the Owner fill in their brief before the product gets built on top of shaky foundations.",
+    "",
+    "Rules for foundational tasks:",
+    "- **ADDITIONS, not replacements.** Include them ALONGSIDE the user's backlog items. If the user submitted 3 ideas, the cycle should have 3 user items + 3-5 foundational items (total 6-8 tasks).",
+    '- **Target specific missing sections.** Do NOT generate "refine audience" if audience is already populated. Each foundational task must close a specific gap above.',
+    "- **Task type: `research` or `discovery`** \u2014 deliverable is a findings doc, not shipped code.",
+    "- **Effort: S or M** \u2014 foundational work should be timeboxed, not open-ended.",
+    '- **WHY in the handoff must tie to the specific gap.** Example: "Brief is thin on GTM \u2014 knowing how users discover the product is a prerequisite for scoping distribution work." Not generic.',
+    "- **Cap at 5 foundational tasks** to avoid drowning the user.",
+    "- **Cycle 2+ will NOT receive this guidance** \u2014 even if the brief stays thin. Foundational work is a one-shot onboarding primitive, not a recurring pattern.",
+    "",
+    "In the structured output:",
+    "- Emit foundational tasks via the `newTasks` array (mark `reviewed: true`, type `research` or `discovery`).",
+    "- Generate full BUILD HANDOFFs for each in `cycleHandoffs` \u2014 use `new-N` IDs to reference them.",
+    "- User-submitted backlog tasks remain in `cycleHandoffs` as usual \u2014 do NOT drop them in favour of foundational tasks."
+  ].join("\n");
+}
 function detectBoardFlags(tasks) {
   let hasBugTasks = false;
   let hasResearchTasks = false;
@@ -12238,6 +12578,10 @@ ${lines.join("\n")}`;
     if (reportsForCapsResult.status === "fulfilled") {
       recentlyShippedLean = formatRecentlyShippedCapabilities(reportsForCapsResult.value);
     }
+    let candidateTaskFullNotesLean;
+    if (preAssignedResult.status === "fulfilled") {
+      candidateTaskFullNotesLean = formatCandidateTaskFullNotes(preAssignedResult.value);
+    }
     logDataSourceSummary("plan (lean)", [
       { label: "cycleHealth", hasData: !!health },
       { label: "productBrief", hasData: warnIfEmpty("productBrief", productBrief) },
@@ -12275,7 +12619,9 @@ ${lines.join("\n")}`;
       carryForwardStaleness: carryForwardStalenessLean,
       preAssignedTasks: preAssignedTextLean,
       recentlyShippedCapabilities: recentlyShippedLean,
-      strategyReviewCadence
+      strategyReviewCadence,
+      candidateTaskFullNotes: candidateTaskFullNotesLean,
+      foundationalTasksGuidance: computeFoundationalTasksGuidance(health.totalCycles, productBrief)
     };
     const { label: leanTierLabel } = applyContextTier(ctx2, health.totalCycles);
     ctx2.contextTier = leanTierLabel;
@@ -12436,7 +12782,9 @@ ${logLines}`);
     carryForwardStaleness: computeCarryForwardStaleness(log),
     preAssignedTasks: preAssignedText,
     recentlyShippedCapabilities: formatRecentlyShippedCapabilities(reports),
-    strategyReviewCadence: strategyReviewCadenceFull
+    strategyReviewCadence: strategyReviewCadenceFull,
+    candidateTaskFullNotes: formatCandidateTaskFullNotes(plannerTasks),
+    foundationalTasksGuidance: computeFoundationalTasksGuidance(health.totalCycles, productBrief)
   };
   const { label: fullTierLabel } = applyContextTier(ctx, health.totalCycles);
   ctx.contextTier = fullTierLabel;
@@ -13817,6 +14165,7 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     // Doc registry — docs with pending actions for staleness audit
     adapter2.searchDocs?.({ hasPendingActions: true, limit: 20 })?.catch(() => []) ?? Promise.resolve([])
   ]);
+  const pendingAgendaTopics = await (adapter2.getPendingAgendaTopics?.().catch(() => []) ?? Promise.resolve([]));
   const tasks = [...activeTasks, ...recentDoneTasks];
   const existingAdIds = new Set(decisions.map((d) => d.id));
   const survivingPendingRecs = [];
@@ -14054,6 +14403,15 @@ ${deferred.join("\n")}`);
       }
     }
   } catch {
+  }
+  let pendingAgendaText;
+  if (pendingAgendaTopics.length > 0) {
+    const lines = pendingAgendaTopics.map((t, i) => {
+      const cycleSuffix = t.sourceCycle != null ? ` (queued Cycle ${t.sourceCycle})` : "";
+      return `${i + 1}. ${t.topic} _[${t.source}${cycleSuffix}]_`;
+    });
+    pendingAgendaText = `${pendingAgendaTopics.length} topic(s) queued via strategy_agenda:
+${lines.join("\n")}`;
   }
   logDataSourceSummary("strategy_review_audit", [
     { label: "discoveryCanvas", hasData: discoveryCanvasText !== void 0 },
@@ -14094,7 +14452,8 @@ ${deferred.join("\n")}`);
     recentPlans: recentPlansText,
     unregisteredDocs: unregisteredDocsText,
     taskComments: taskCommentsText,
-    docActionStaleness: docActionStalenessText
+    docActionStaleness: docActionStalenessText,
+    pendingAgendaTopics: pendingAgendaText
   };
   const BUDGET_SOFT2 = 5e4;
   const BUDGET_HARD2 = 6e4;
@@ -14409,6 +14768,15 @@ async function processReviewOutput(adapter2, rawOutput, cycleNumber) {
         await adapter2.clearPendingReviewResponse?.();
       } catch {
       }
+      try {
+        if (adapter2.getPendingAgendaTopics && adapter2.markAgendaTopicsAddressed) {
+          const pending = await adapter2.getPendingAgendaTopics();
+          if (pending.length > 0) {
+            await adapter2.markAgendaTopicsAddressed(pending.map((t) => t.id), cycleNumber);
+          }
+        }
+      } catch {
+      }
       const webhookUrl = process.env.PAPI_SLACK_WEBHOOK_URL;
       slackWarning = await sendSlackWebhook(webhookUrl, buildSlackSummary(data));
     }
@@ -14929,6 +15297,34 @@ var strategyReviewTool = {
     required: []
   }
 };
+var strategyAgendaTool = {
+  name: "strategy_agenda",
+  description: 'Queue topics for the next strategy review. Topics surface as input in the next `strategy_review` prepare phase and are automatically marked as addressed after the review completes. Two modes: "add" to queue a topic, "list" to see pending topics. Use this when you spot a strategic question during a build \u2014 capture the topic now instead of losing it.',
+  annotations: { readOnlyHint: false, destructiveHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      mode: {
+        type: "string",
+        enum: ["add", "list"],
+        description: '"add" to queue a topic (requires `topic`). "list" returns all pending topics. Defaults to "list" when omitted.'
+      },
+      topic: {
+        type: "string",
+        description: 'The topic to queue (mode "add" only). One sentence describing what the next strategy review should consider.'
+      },
+      source: {
+        type: "string",
+        description: 'Optional origin label \u2014 e.g. "manual", "carry-forward", "idea". Defaults to "manual".'
+      },
+      source_cycle: {
+        type: "number",
+        description: 'Optional cycle number this topic originated from (mode "add" only).'
+      }
+    },
+    required: []
+  }
+};
 var strategyChangeTool = {
   name: "strategy_change",
   description: 'Apply a strategic shift to the project. Three modes: "capture" for lightweight mid-conversation decision capture (no LLM round-trip), "prepare" to get a change prompt for full analysis, "apply" to persist analysis output. Use "capture" when you detect a strategic decision in conversation and want to persist it quickly without disrupting the build flow.',
@@ -15085,6 +15481,49 @@ ${result.userMessage}
     return errorResponse(err instanceof Error ? err.message : String(err));
   }
 }
+async function handleStrategyAgenda(adapter2, _config, args) {
+  const mode = args.mode ?? "list";
+  if (!adapter2.addAgendaTopic || !adapter2.getPendingAgendaTopics) {
+    return errorResponse("strategy_agenda is not supported by the current adapter.");
+  }
+  try {
+    if (mode === "add") {
+      const topic = args.topic;
+      if (!topic || !topic.trim()) {
+        return errorResponse('topic is required for mode "add". Describe what the next strategy review should consider.');
+      }
+      const source = (args.source ?? "manual").trim() || "manual";
+      const sourceCycle = typeof args.source_cycle === "number" ? args.source_cycle : void 0;
+      const entry = await adapter2.addAgendaTopic({ topic: topic.trim(), source, sourceCycle });
+      return textResponse(
+        `**Agenda Topic Queued**
+
+${entry.topic}
+
+Source: ${entry.source}${entry.sourceCycle != null ? ` (Cycle ${entry.sourceCycle})` : ""}
+ID: ${entry.id}
+
+This topic will surface in the next \`strategy_review\`.`
+      );
+    }
+    const topics = await adapter2.getPendingAgendaTopics();
+    if (topics.length === 0) {
+      return textResponse('No pending agenda topics. Use `strategy_agenda` with `mode: "add"` to queue one.');
+    }
+    const lines = topics.map((t, i) => {
+      const cycleSuffix = t.sourceCycle != null ? ` (Cycle ${t.sourceCycle})` : "";
+      return `${i + 1}. ${t.topic}
+   _source: ${t.source}${cycleSuffix} \xB7 queued ${t.createdAt.slice(0, 10)}_`;
+    });
+    return textResponse(
+      `**Pending Agenda (${topics.length})** \u2014 surfaces at next strategy review
+
+${lines.join("\n\n")}`
+    );
+  } catch (err) {
+    return errorResponse(err instanceof Error ? err.message : String(err));
+  }
+}
 async function handleStrategyChange(adapter2, _config, args) {
   const toolMode = args.mode;
   try {
@@ -15356,7 +15795,7 @@ var boardArchiveTool = {
 };
 var boardEditTool = {
   name: "board_edit",
-  description: "Edit fields on an existing task. Supports title, priority, complexity, module, epic, phase, notes, status, and maturity. Pass task_id plus any fields to update. Does not call the Anthropic API.",
+  description: "Edit fields on an existing task. Supports title, priority, complexity, module, epic, phase, notes (with notes_mode for append/replace/clear), status, and maturity. Pass task_id plus any fields to update. Does not call the Anthropic API.",
   annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
@@ -15393,7 +15832,12 @@ var boardEditTool = {
       },
       notes: {
         type: "string",
-        description: "New notes (replaces existing notes)."
+        description: "Note content. Default behaviour is append \u2014 see notes_mode to control."
+      },
+      notes_mode: {
+        type: "string",
+        enum: ["append", "replace", "clear"],
+        description: "How to apply the notes value. append (default) = add a new dated entry above existing notes; replace = overwrite all existing notes; clear = empty the notes field (notes value ignored)."
       },
       status: {
         type: "string",
@@ -15596,6 +16040,10 @@ async function handleBoardEdit(adapter2, args) {
       changes.push(field);
     }
   }
+  const notesMode = args.notes_mode;
+  if (notesMode === "clear" && !changes.includes("notes")) {
+    changes.push("notes");
+  }
   if (changes.length === 0) {
     return errorResponse("No fields to update. Pass at least one field (title, priority, complexity, module, epic, phase, notes, status, maturity).");
   }
@@ -15604,6 +16052,35 @@ async function handleBoardEdit(adapter2, args) {
     if (!task) {
       return errorResponse(`Task ${taskId} not found.`);
     }
+    if (changes.includes("notes")) {
+      const incoming = args.notes ?? "";
+      const existing = task.notes ?? "";
+      const mode = notesMode ?? "append";
+      if (mode === "clear") {
+        updates.notes = "";
+      } else if (mode === "replace") {
+        updates.notes = incoming;
+      } else {
+        const trimmed = incoming.trim();
+        if (trimmed.length === 0) {
+          delete updates.notes;
+          const idx = changes.indexOf("notes");
+          if (idx >= 0) changes.splice(idx, 1);
+        } else {
+          const health = await adapter2.getCycleHealth().catch(() => null);
+          const activeCycle = health?.totalCycles ?? null;
+          const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+          const stamp = activeCycle != null ? `[C${activeCycle} ${date}]` : `[${date}]`;
+          const entry = `${stamp} ${trimmed}`;
+          updates.notes = existing.trim().length > 0 ? `${entry}
+
+${existing}` : entry;
+        }
+      }
+      if (changes.length === 0) {
+        return errorResponse("No fields to update. Pass at least one field (title, priority, complexity, module, epic, phase, notes, status, maturity).");
+      }
+    }
     if (updates.status === "Backlog" && task.cycle != null) {
       updates.cycle = void 0;
       updates.cycle = null;
@@ -16625,9 +17102,8 @@ async function prepareSetup(adapter2, config2, input) {
     );
   }
   const TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
-  if (existingBrief.trim() && !existingBrief.includes(TEMPLATE_MARKER) && !input.force) {
-    throw new Error("PRODUCT_BRIEF.md already contains a generated Product Brief. Running setup again would overwrite it.\n\nTo proceed anyway, run setup with force: true.");
-  }
+  const briefHasRealContent = existingBrief.trim().length > 0 && !existingBrief.includes(TEMPLATE_MARKER);
+  const briefAlreadyExists = briefHasRealContent && !input.force;
   const detectedCodebaseType = detectCodebaseType(config2.projectRoot);
   const autoDetected = input.existingProject === void 0 || input.existingProject === false;
   const isExistingProject = input.existingProject === true || autoDetected && detectedCodebaseType === "existing_codebase";
@@ -16640,7 +17116,7 @@ async function prepareSetup(adapter2, config2, input) {
     }
     codebaseSummary = formatCodebaseSummary(scan, sourceContents);
   }
-  const briefPrompt = {
+  const briefPrompt = briefAlreadyExists ? void 0 : {
     system: PRODUCT_BRIEF_SYSTEM,
     user: buildProductBriefPrompt({
       projectName: input.projectName,
@@ -16694,15 +17170,29 @@ async function prepareSetup(adapter2, config2, input) {
     initialTasksPrompt,
     codebaseSummary,
     detectedCodebaseType,
-    autoDetected: autoDetected && detectedCodebaseType !== "new_project"
+    autoDetected: autoDetected && detectedCodebaseType !== "new_project",
+    briefAlreadyExists
   };
 }
 async function applySetup(adapter2, config2, input, briefText, adSeedText, conventionsText, initialTasksText) {
   const createdProject = await scaffoldPapiDir(adapter2, config2, input);
-  if (!briefText.trim()) {
-    throw new Error("brief_response is required and cannot be empty.");
+  const TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
+  let effectiveBriefText = briefText;
+  if (!effectiveBriefText.trim()) {
+    let existingBrief = "";
+    try {
+      existingBrief = await adapter2.readProductBrief();
+    } catch {
+      existingBrief = "";
+    }
+    const existingIsReal = existingBrief.trim().length > 0 && !existingBrief.includes(TEMPLATE_MARKER);
+    if (existingIsReal && !input.force) {
+      effectiveBriefText = existingBrief;
+    } else {
+      throw new Error("brief_response is required and cannot be empty.");
+    }
   }
-  const { seededAds, warnings } = await applySetupOutputs(adapter2, config2, input, briefText, adSeedText, conventionsText);
+  const { seededAds, warnings } = await applySetupOutputs(adapter2, config2, input, effectiveBriefText, adSeedText, conventionsText);
   let createdTasks = 0;
   if (initialTasksText?.trim()) {
     try {
@@ -16928,10 +17418,7 @@ PAPI needs just 3 things: project name, what it does, and who it's for.`
   const input = extractInput(args);
   try {
     if (toolMode === "apply") {
-      const briefResponse = args.brief_response;
-      if (!briefResponse || !briefResponse.trim()) {
-        return errorResponse('brief_response is required for mode "apply".');
-      }
+      const briefResponse = args.brief_response ?? "";
       const adSeedResponse = args.ad_seed_response;
       const conventionsResponse = args.conventions_response;
       const initialTasksResponse = args.initial_tasks_response;
@@ -16964,6 +17451,12 @@ PAPI needs just 3 things: project name, what it does, and who it's for.`
           ""
         );
       }
+      if (result.briefAlreadyExists) {
+        sections.push(
+          `**Existing brief detected:** this project already has a Product Brief (e.g. from the web wizard). Setup will preserve it and skip brief generation \u2014 no \`brief_response\` needed in the apply step. To overwrite the brief instead, re-run setup with \`force: true\`.`,
+          ""
+        );
+      }
       if (inferredDefaults.length > 0) {
         sections.push(
           `**Defaults applied** (override by re-running setup with these fields):`,
@@ -16974,30 +17467,37 @@ PAPI needs just 3 things: project name, what it does, and who it's for.`
       sections.push(
         `Generate the outputs below, then call \`setup\` again with:`,
         `- \`mode\`: "apply"`,
-        `- \`brief_response\`: your Product Brief markdown`,
+        result.briefPrompt ? `- \`brief_response\`: your Product Brief markdown` : "",
         result.adSeedPrompt ? `- \`ad_seed_response\`: your AD seed JSON array` : "",
         result.conventionsPrompt ? `- \`conventions_response\`: your conventions markdown` : "",
         result.initialTasksPrompt ? `- \`initial_tasks_response\`: your initial tasks JSON array` : "",
         `- Plus all the original setup fields (project_name, description, target_users${isExisting ? ", existing_project: true" : ""})`,
         "",
-        `---`,
-        "",
-        `### 1. Product Brief`,
-        "",
-        `<system_prompt>
+        `---`
+      );
+      let sectionNum = 0;
+      if (result.briefPrompt) {
+        sectionNum++;
+        sections.push(
+          "",
+          `### ${sectionNum}. Product Brief`,
+          "",
+          `<system_prompt>
 ${result.briefPrompt.system}
 </system_prompt>`,
-        "",
-        `<context>
+          "",
+          `<context>
 ${result.briefPrompt.user}
 </context>`
-      );
+        );
+      }
       if (result.adSeedPrompt) {
+        sectionNum++;
         sections.push(
           "",
           `---`,
           "",
-          `### 2. Active Decision Seeds`,
+          `### ${sectionNum}. Active Decision Seeds`,
           "",
           `<system_prompt>
 ${result.adSeedPrompt.system}
@@ -17009,11 +17509,12 @@ ${result.adSeedPrompt.user}
         );
       }
       if (result.conventionsPrompt) {
+        sectionNum++;
         sections.push(
           "",
           `---`,
           "",
-          `### 3. Conventions`,
+          `### ${sectionNum}. Conventions`,
           "",
           `<system_prompt>
 ${result.conventionsPrompt.system}
@@ -17025,11 +17526,12 @@ ${result.conventionsPrompt.user}
         );
       }
       if (result.initialTasksPrompt) {
+        sectionNum++;
         sections.push(
           "",
           `---`,
           "",
-          `### 4. Initial Backlog Tasks`,
+          `### ${sectionNum}. Initial Backlog Tasks`,
           "",
           `<system_prompt>
 ${result.initialTasksPrompt.system}
@@ -17441,18 +17943,37 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     }
   }
   let autoTriagedCount = 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();
-      const priority = severityLabel === "P0" || severityLabel === "P1" ? "P1 High" : severityLabel === "P2" ? "P2 Medium" : "P3 Low";
+      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);
+        continue;
+      }
       try {
-        await adapter2.createTask({
+        const created = await adapter2.createTask({
           uuid: "",
           displayId: "",
           title: `[Auto-triaged] ${title}`,
@@ -17469,6 +17990,10 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
           createdCycle: cycleNumber
         });
         autoTriagedCount++;
+        if (created?.displayId) {
+          autoTriagedIds.push(created.displayId);
+          backlogTitleMap.set(normalized, created.displayId);
+        }
       } catch {
       }
     }
@@ -17665,6 +18190,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     dogfoodResolvedCount: dogfoodResolvedCount > 0 ? dogfoodResolvedCount : void 0,
     learningsLinkedCount: learningsLinkedCount > 0 ? learningsLinkedCount : void 0,
     autoTriagedCount: autoTriagedCount > 0 ? autoTriagedCount : void 0,
+    autoTriagedIds: autoTriagedIds.length > 0 ? autoTriagedIds : void 0,
+    autoTriagedDupes: autoTriagedDupes.length > 0 ? autoTriagedDupes : void 0,
     reportWriteVerified
   };
 }
@@ -18168,8 +18695,16 @@ function formatCompleteResult(result) {
   if (result.learningsLinkedCount) {
     lines.push("", `Linked ${result.learningsLinkedCount} unactioned learning(s) to this task.`);
   }
-  if (result.autoTriagedCount) {
-    lines.push("", `\u{1F516} Auto-triaged ${result.autoTriagedCount} discovered issue(s) to Backlog.`);
+  if (result.autoTriagedCount || result.autoTriagedDupes?.length) {
+    const parts = [];
+    if (result.autoTriagedCount) {
+      const ids = result.autoTriagedIds?.length ? ` (${result.autoTriagedIds.join(", ")})` : "";
+      parts.push(`\u{1F516} Auto-triaged ${result.autoTriagedCount} discovered issue(s) to Backlog${ids}.`);
+    }
+    if (result.autoTriagedDupes?.length) {
+      parts.push(`Skipped ${result.autoTriagedDupes.length} duplicate issue(s) already in Backlog: ${result.autoTriagedDupes.join(", ")}.`);
+    }
+    lines.push("", parts.join(" "));
   }
   if (result.reportWriteVerified === false) {
     lines.push("", "\u26A0\uFE0F Build report write could not be verified \u2014 the report may not have been persisted. Run `build_list` to check, and resubmit if missing.");
@@ -19784,7 +20319,41 @@ function generateChangelog(version, commits) {
 ${commitList}
 `;
 }
-async function createRelease(config2, branch, version, adapter2) {
+function mergeGroupedCycleBranches(config2, cycleNum, baseBranch) {
+  const branches = listGroupedCycleBranches(config2.projectRoot, cycleNum, baseBranch);
+  if (branches.length === 0) return [];
+  if (!isGhAvailable()) {
+    throw new Error(
+      `Release blocked: ${branches.length} unmerged grouped cycle branch(es) detected (${branches.join(", ")}) but \`gh\` CLI is not available. Install gh and re-run release.`
+    );
+  }
+  const results = [];
+  for (const branch of branches) {
+    let prUrl = getPullRequestUrl(config2.projectRoot, branch);
+    if (!prUrl) {
+      const moduleName = branch.replace(`feat/cycle-${cycleNum}-`, "");
+      const prCreate = createPullRequest(
+        config2.projectRoot,
+        branch,
+        baseBranch,
+        `feat(cycle-${cycleNum}): merge shared cycle branch \u2014 ${moduleName}`,
+        `Automated PR created at release time for shared cycle branch \`${branch}\` (Cycle ${cycleNum}).`
+      );
+      if (!prCreate.success) {
+        results.push({ branch, prUrl: null, status: "failed", message: prCreate.message });
+        continue;
+      }
+      prUrl = prCreate.message;
+    }
+    const merge = squashMergePullRequest(config2.projectRoot, branch);
+    if (merge.success) {
+      deleteLocalBranch(config2.projectRoot, branch);
+    }
+    results.push({ branch, prUrl, status: merge.success ? "merged" : "failed", message: merge.message });
+  }
+  return results;
+}
+async function createRelease(config2, branch, version, adapter2, cycleNum) {
   if (!isGitAvailable()) {
     throw new Error("git is not available.");
   }
@@ -19795,10 +20364,13 @@ async function createRelease(config2, branch, version, adapter2) {
     throw new Error("working directory has uncommitted changes. Commit or stash them before releasing.");
   }
   const warnings = [];
+  const resolvedCycleNum = cycleNum && cycleNum > 0 ? cycleNum : (() => {
+    const m = version.match(/^v0\.(\d+)\./);
+    return m ? parseInt(m[1], 10) : 0;
+  })();
   if (adapter2) {
     try {
-      const versionMatch = version.match(/^v0\.(\d+)\./);
-      const currentCycle = versionMatch ? parseInt(versionMatch[1], 10) : 0;
+      const currentCycle = resolvedCycleNum;
       if (currentCycle > 0) {
         await adapter2.createCycle({
           id: `cycle-${currentCycle}`,
@@ -19827,6 +20399,24 @@ async function createRelease(config2, branch, version, adapter2) {
       warnings.push(`git pull failed: ${pull.message}. Run manually.`);
     }
   }
+  let groupedBranchMerges;
+  if (resolvedCycleNum > 0) {
+    const mergeResults = mergeGroupedCycleBranches(config2, resolvedCycleNum, branch);
+    if (mergeResults.length > 0) {
+      groupedBranchMerges = mergeResults;
+      const failures = mergeResults.filter((r) => r.status === "failed");
+      if (failures.length > 0) {
+        const detail = failures.map((r) => `${r.branch}: ${r.message}`).join("; ");
+        throw new Error(`Release blocked: grouped cycle branch merge failed \u2014 ${detail}. Resolve conflicts and retry release.`);
+      }
+      if (hasRemote(config2.projectRoot)) {
+        const repull = gitPull(config2.projectRoot);
+        if (!repull.success) {
+          warnings.push(`Post-merge pull failed: ${repull.message}. Run manually.`);
+        }
+      }
+    }
+  }
   if (tagExists(config2.projectRoot, version)) {
     throw new Error(`tag "${version}" already exists. Use a different version.`);
   }
@@ -19863,7 +20453,8 @@ async function createRelease(config2, branch, version, adapter2) {
     commitNote,
     tagMessage: tagResult.message,
     pushNotes,
-    warnings: warnings.length > 0 ? warnings : void 0
+    warnings: warnings.length > 0 ? warnings : void 0,
+    ...groupedBranchMerges ? { groupedBranchMerges } : {}
   };
 }
 
@@ -19919,7 +20510,9 @@ async function handleRelease(adapter2, config2, args) {
     return errorResponse(`version must start with "v" (got "${version}"). Example: "v0.1.0-alpha"`);
   }
   try {
-    const result = await createRelease(config2, branch, version, adapter2);
+    const cycleMatch = version.match(/^v0\.(\d+)\./);
+    const cycleNum = cycleMatch ? parseInt(cycleMatch[1], 10) : void 0;
+    const result = await createRelease(config2, branch, version, adapter2, cycleNum);
     const lines = [
       `## Release ${result.version}`,
       "",
@@ -19932,13 +20525,17 @@ async function handleRelease(adapter2, config2, args) {
       lines.push("", "---", "");
       lines.push(...result.pushNotes);
     }
+    if (result.groupedBranchMerges?.length) {
+      lines.push("", "**Shared cycle branches merged:**");
+      for (const m of result.groupedBranchMerges) {
+        lines.push(`- \`${m.branch}\` \u2014 ${m.message}${m.prUrl ? ` (${m.prUrl})` : ""}`);
+      }
+    }
     if (result.warnings?.length) {
       lines.push("", "\u26A0\uFE0F Warnings: " + result.warnings.join("; "));
     }
     try {
-      const cycleMatch = version.match(/^v0\.(\d+)\./);
-      const cycleNum = cycleMatch ? parseInt(cycleMatch[1], 10) : 0;
-      if (cycleNum > 0) {
+      if (cycleNum && cycleNum > 0) {
         const reports = await adapter2.getBuildReportsSince(cycleNum);
         const EMPTY = /* @__PURE__ */ new Set(["None", "none", "N/A", "", "null"]);
         const issues = reports.filter((r) => r.discoveredIssues && !EMPTY.has(r.discoveredIssues.trim())).map((r) => `- **${r.taskId}** (${r.taskName}): ${r.discoveredIssues}`);
@@ -19951,10 +20548,10 @@ async function handleRelease(adapter2, config2, args) {
     }
     if (rawObservations && rawObservations.length > 0 && adapter2.writeDogfoodEntries) {
       try {
-        const cycleMatch = version.match(/^v0\.(\d+)\./);
-        const cycleNum = cycleMatch ? parseInt(cycleMatch[1], 10) : 0;
+        const cycleMatch2 = version.match(/^v0\.(\d+)\./);
+        const cycleNum2 = cycleMatch2 ? parseInt(cycleMatch2[1], 10) : 0;
         const entries = rawObservations.map((obs) => ({
-          cycleNumber: cycleNum,
+          cycleNumber: cycleNum2,
           category: obs.category,
           content: obs.content,
           sourceTool: "release",
@@ -20210,6 +20807,10 @@ function mergeAfterAccept(config2, taskId) {
   }
   const featureBranch = taskBranchName(taskId);
   const baseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
+  if (!branchExists(config2.projectRoot, featureBranch)) {
+    lines.push(`Task is on a shared cycle branch \u2014 will be merged at release time.`);
+    return lines;
+  }
   const papiDir = join7(config2.projectRoot, ".papi");
   if (existsSync4(papiDir)) {
     try {
@@ -20385,8 +20986,9 @@ ${result.handoffRegenPrompt.userMessage}
           }
           const version = `v0.${result.currentCycle}.0`;
           const baseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
-          const releaseResult = await createRelease(config2, baseBranch, version, adapter2);
+          const releaseResult = await createRelease(config2, baseBranch, version, adapter2, result.currentCycle);
           const pushInfo = releaseResult.pushNotes.join(" ");
+          const groupedMergeNote = releaseResult.groupedBranchMerges?.length ? "\n" + releaseResult.groupedBranchMerges.map((r) => `- Merged shared branch \`${r.branch}\` via PR: ${r.prUrl ?? "n/a"}`).join("\n") : "";
           autoReleaseNote = `
 
 ---
@@ -20396,7 +20998,7 @@ ${result.handoffRegenPrompt.userMessage}
 - Version: **${releaseResult.version}**
 - ${releaseResult.commitNote}
 - ${releaseResult.tagMessage}
-- ${pushInfo}` + (releaseResult.warnings?.length ? `
+- ${pushInfo}` + groupedMergeNote + (releaseResult.warnings?.length ? `
 - Warnings: ${releaseResult.warnings.join(", ")}` : "") + `
 
 Run \`plan\` to create Cycle ${result.currentCycle + 1}.`;
@@ -20643,7 +21245,7 @@ function countByStatus(tasks) {
 async function getHealthSummary(adapter2) {
   const health = await adapter2.getCycleHealth();
   const activeTasks = await adapter2.queryBoard({
-    status: ["Backlog", "In Cycle", "Ready", "In Progress", "In Review", "Blocked"]
+    status: ["Backlog", "In Cycle", "Ready", "In Progress", "In Review", "Blocked", "Deferred"]
   });
   const logEntries = await adapter2.getCycleLog(3);
   const cycleNumber = health.totalCycles;
@@ -21044,21 +21646,94 @@ async function handleDocScan(adapter2, config2, args) {
   return textResponse(lines.join("\n"));
 }
 
+// src/services/session-guidance.ts
+import { existsSync as existsSync6 } from "fs";
+import { join as join9 } from "path";
+var state = {
+  toolCallCount: 0,
+  lastOrientAt: null,
+  releaseSinceLastOrient: false,
+  sessionStartedAt: Date.now()
+};
+var CONTEXT_BLOAT_CALL_THRESHOLD = 40;
+var ORIENT_GAP_MS = 3 * 60 * 60 * 1e3;
+function recordToolCall(name) {
+  state.toolCallCount++;
+  if (name === "release") state.releaseSinceLastOrient = true;
+}
+function markOrient() {
+  state.lastOrientAt = Date.now();
+  state.releaseSinceLastOrient = false;
+}
+async function buildSessionGuidance(adapter2, projectRoot) {
+  const signals = [];
+  try {
+    if (adapter2.searchDocs) {
+      const researchDir = join9(projectRoot, "docs", "research");
+      if (existsSync6(researchDir)) {
+        const files = scanMdFiles(researchDir, projectRoot);
+        if (files.length > 0) {
+          const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
+          const registeredPaths = new Set(registered.map((d) => d.path));
+          const unregistered = files.filter((f) => !registeredPaths.has(f));
+          if (unregistered.length > 0) {
+            signals.push(
+              `${unregistered.length} research doc(s) in docs/research/ not registered \u2014 run \`doc_register\` so the planner can surface them.`
+            );
+          }
+        }
+      }
+    }
+  } catch {
+  }
+  if (state.toolCallCount > CONTEXT_BLOAT_CALL_THRESHOLD) {
+    signals.push(
+      `${state.toolCallCount} tool calls this session \u2014 context may be bloated. Consider starting a fresh window.`
+    );
+  }
+  if (state.lastOrientAt && Date.now() - state.lastOrientAt > ORIENT_GAP_MS) {
+    const hours = Math.round((Date.now() - state.lastOrientAt) / (60 * 60 * 1e3));
+    signals.push(
+      `${hours}h since last orient \u2014 session may be stale. Consider a fresh window for best results.`
+    );
+  }
+  if (state.releaseSinceLastOrient) {
+    signals.push(
+      "Release just ran \u2014 start a fresh session before the next `plan` to keep planning context clean."
+    );
+  }
+  return signals.slice(0, 3);
+}
+
 // src/tools/orient.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync6 } from "fs";
-import { join as join9 } from "path";
+import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync7 } from "fs";
+import { join as join10 } from "path";
+var GIT_DEPENDENT_ENVS = /* @__PURE__ */ new Set(["cowork", "api"]);
+var VALID_ENVS = /* @__PURE__ */ new Set(["claude-code", "cowork", "api", "unknown"]);
+function normaliseEnvironment(raw) {
+  if (typeof raw === "string" && VALID_ENVS.has(raw)) {
+    return raw;
+  }
+  return "unknown";
+}
 var orientTool = {
   name: "orient",
-  description: "Session orientation \u2014 run this FIRST at session start before any other tool. Single call that replaces build_list + health. Returns: cycle number, task counts by status, in-progress/in-review tasks, strategy review cadence, velocity snapshot, recommended next action, and a release reminder when all cycle tasks are Done but release has not run. Read-only, does not modify any files.",
+  description: "Session orientation \u2014 run this FIRST at session start before any other tool. Single call that replaces build_list + health. Returns: cycle number, task counts by status, in-progress/in-review tasks, strategy review cadence, velocity snapshot, recommended next action, and a release reminder when all cycle tasks are Done but release has not run. Read-only, does not modify any files. Pass `environment` to qualify git-dependent recommendations (build_execute, release, review_submit) for non-Claude-Code callers.",
   annotations: { readOnlyHint: true, destructiveHint: false },
   inputSchema: {
     type: "object",
-    properties: {},
+    properties: {
+      environment: {
+        type: "string",
+        enum: ["claude-code", "cowork", "api", "unknown"],
+        description: 'Caller environment. "claude-code" (local CLI with git) sees all recommendations unchanged. "cowork" or "api" (hosted/remote, no local git) suppresses/qualifies build_execute, release, and review_submit recommendations because those require a local Claude Code session to execute. Default "unknown" = show everything (safe default).'
+      }
+    },
     required: []
   }
 };
-function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoot) {
+function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoot, environment = "unknown") {
   const lines = [];
   const cycleIsComplete = health.latestCycleStatus === "complete";
   const tagSuffix = latestTag ? ` \u2014 ${latestTag}` : "";
@@ -21076,7 +21751,13 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
     }
     lines.push("");
   }
-  lines.push(`> **Next action:** ${health.recommendedMode}`);
+  const isGitDependentRec = /\*\*(Build|Review)\*\*/.test(health.recommendedMode);
+  if (GIT_DEPENDENT_ENVS.has(environment) && isGitDependentRec) {
+    lines.push(`> **Next action:** ${health.recommendedMode}`);
+    lines.push(`> _Note: \`build_execute\`, \`review_submit\`, and \`release\` require a local Claude Code session with git access. From \`${environment}\` you can view state, log ideas, and edit the board \u2014 but the build/review/release loop must run through Claude Code._`);
+  } else {
+    lines.push(`> **Next action:** ${health.recommendedMode}`);
+  }
   lines.push("");
   lines.push(`**Strategy Review:** ${health.reviewWarning}`);
   lines.push("");
@@ -21227,7 +21908,7 @@ function getLatestGitTag(projectRoot) {
 }
 function checkNpmVersionDrift() {
   try {
-    const pkgPath = join9(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
+    const pkgPath = join10(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
     const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
     const localVersion = pkg.version;
     const packageName = pkg.name;
@@ -21244,7 +21925,8 @@ function checkNpmVersionDrift() {
     return null;
   }
 }
-async function handleOrient(adapter2, config2) {
+async function handleOrient(adapter2, config2, args = {}) {
+  const environment = normaliseEnvironment(args.environment);
   try {
     try {
       await propagatePhaseStatus(adapter2);
@@ -21353,7 +22035,7 @@ ${versionDrift}` : "";
     let unregisteredDocsNote = "";
     try {
       if (adapter2.searchDocs) {
-        const docsDir = join9(config2.projectRoot, "docs");
+        const docsDir = join10(config2.projectRoot, "docs");
         const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
         if (docsFiles.length > 0) {
           const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
@@ -21443,13 +22125,35 @@ ${versionDrift}` : "";
       }
     } catch {
     }
+    let alertsNote = "";
     let unactionedIssuesNote = "";
     try {
-      const learnings = await adapter2.getCycleLearnings?.({ category: "issue", limit: 20 });
+      const learnings = await adapter2.getCycleLearnings?.({ category: "issue", limit: 30 });
       if (learnings) {
-        const unactioned = learnings.filter((l) => !l.actionTaken && l.severity && ["P0", "P1", "P2"].includes(l.severity)).slice(0, 5);
-        if (unactioned.length > 0) {
-          const lines = ["\n\n## Unactioned Issues"];
+        const byRecency = (a, b2) => (b2.createdAt ?? "").localeCompare(a.createdAt ?? "");
+        const unactionedAll = learnings.filter((l) => !l.actionTaken).map((l) => ({ ...l, severity: l.severity ?? "P3" }));
+        const allAlerts = unactionedAll.filter((l) => l.severity === "P0" || l.severity === "P1").sort(byRecency);
+        const allLowSev = unactionedAll.filter((l) => l.severity === "P2" || l.severity === "P3").sort(byRecency);
+        const totalP2 = allLowSev.filter((l) => l.severity === "P2").length;
+        const totalP3 = allLowSev.filter((l) => l.severity === "P3").length;
+        const ALERT_CAP = 10;
+        const UNACTIONED_CAP = 5;
+        const alerts = allAlerts.slice(0, ALERT_CAP);
+        const unactioned = allLowSev.slice(0, UNACTIONED_CAP);
+        if (allAlerts.length > 0) {
+          const header = allAlerts.length > ALERT_CAP ? `${allAlerts.length} P0/P1 discovered issues awaiting action (showing ${ALERT_CAP} most recent).` : `${allAlerts.length} P0/P1 discovered issue${allAlerts.length !== 1 ? "s" : ""} awaiting action.`;
+          const lines = ["\n\n## \u{1F6A8} Alerts", header];
+          for (const issue of alerts) {
+            const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
+            lines.push(`- **${issue.severity}** (C${issue.cycleNumber} / ${issue.taskId}): ${desc}`);
+          }
+          lines.push("_Escalate: run `idea` with P1 priority, or `board_edit` if already handled._");
+          alertsNote = lines.join("\n");
+        }
+        if (allLowSev.length > 0) {
+          const totalLow = totalP2 + totalP3;
+          const header = totalLow > UNACTIONED_CAP ? `${totalP2} P2 \xB7 ${totalP3} P3 (showing ${UNACTIONED_CAP} most recent)` : `${totalP2} P2 \xB7 ${totalP3} P3`;
+          const lines = ["\n\n## Unactioned Issues", header];
           for (const issue of unactioned) {
             const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
             lines.push(`- **${issue.severity}** (C${issue.cycleNumber} / ${issue.taskId}): ${desc}`);
@@ -21460,15 +22164,26 @@ ${versionDrift}` : "";
       }
     } catch {
     }
-    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot) + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + versionNote + enrichmentNote);
+    let sessionGuidanceNote = "";
+    try {
+      const signals = await buildSessionGuidance(adapter2, config2.projectRoot);
+      if (signals.length > 0) {
+        const lines = ["\n\n## Session Guidance"];
+        for (const s of signals) lines.push(`- ${s}`);
+        sessionGuidanceNote = lines.join("\n");
+      }
+      markOrient();
+    } catch {
+    }
+    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment) + alertsNote + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + sessionGuidanceNote + versionNote + enrichmentNote);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return errorResponse(`Orient failed: ${message}`);
   }
 }
 function enrichClaudeMd(projectRoot, cycleNumber) {
-  const claudeMdPath = join9(projectRoot, "CLAUDE.md");
-  if (!existsSync6(claudeMdPath)) return "";
+  const claudeMdPath = join10(projectRoot, "CLAUDE.md");
+  if (!existsSync7(claudeMdPath)) return "";
   const content = readFileSync3(claudeMdPath, "utf-8");
   const additions = [];
   if (cycleNumber >= 6 && !content.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1)) {
@@ -22250,6 +22965,47 @@ ${result.userMessage}
   }
 }
 
+// src/lib/install-id.ts
+import { randomUUID as randomUUID15 } from "crypto";
+import { mkdirSync, readFileSync as readFileSync4, writeFileSync as writeFileSync2, chmodSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join11 } from "path";
+var PAPI_HOME_DIR = join11(homedir3(), ".papi");
+var INSTALL_ID_FILE = join11(PAPI_HOME_DIR, "install-id.json");
+var cachedInstallId = null;
+function isValidUuid(s) {
+  return typeof s === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s);
+}
+function getInstallId() {
+  if (cachedInstallId) return cachedInstallId;
+  try {
+    const raw = readFileSync4(INSTALL_ID_FILE, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (isValidUuid(parsed.install_id)) {
+      cachedInstallId = parsed.install_id;
+      return cachedInstallId;
+    }
+  } catch {
+  }
+  try {
+    mkdirSync(PAPI_HOME_DIR, { recursive: true, mode: 448 });
+    const id = randomUUID15();
+    const contents = {
+      install_id: id,
+      created_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    writeFileSync2(INSTALL_ID_FILE, JSON.stringify(contents, null, 2), { mode: 384 });
+    try {
+      chmodSync(INSTALL_ID_FILE, 384);
+    } catch {
+    }
+    cachedInstallId = id;
+    return cachedInstallId;
+  } catch {
+    return null;
+  }
+}
+
 // src/lib/telemetry.ts
 var TELEMETRY_SUPABASE_URL = "https://guewgygcpcmrcoppihzx.supabase.co";
 var TELEMETRY_API_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imd1ZXdneWdjcGNtcmNvcHBpaHp4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI2Njk2NTMsImV4cCI6MjA4ODI0NTY1M30.V5Jw7wJgiMpSQPa2mt0ftjyye5ynG1qLlam00yPVNJY";
@@ -22288,6 +23044,32 @@ function emitToolCall(projectId, toolName, durationMs, extra) {
     metadata: { duration_ms: durationMs, ...extra }
   });
 }
+function emitMdAdapterPing(toolName, extra, userId, projectSlug) {
+  if (!isEnabled()) return;
+  const installId = getInstallId();
+  if (!installId) return;
+  const resolvedUserId = userId ?? process.env["PAPI_USER_ID"] ?? void 0;
+  const body = {
+    install_id: installId,
+    tool_name: toolName,
+    papi_version: process.env["npm_package_version"] ?? null,
+    metadata: extra ?? {}
+  };
+  if (resolvedUserId) body["user_id"] = resolvedUserId;
+  if (projectSlug) body["project_slug"] = projectSlug;
+  fetch(`${TELEMETRY_SUPABASE_URL}/rest/v1/md_adapter_pings`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "apikey": TELEMETRY_API_KEY,
+      "Authorization": `Bearer ${TELEMETRY_API_KEY}`,
+      "Prefer": "return=minimal"
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(5e3)
+  }).catch(() => {
+  });
+}
 function emitMilestone(projectId, milestone, extra) {
   emitTelemetryEvent({
     project_id: projectId,
@@ -22302,6 +23084,7 @@ var TOOLS_REQUIRING_PAPI = /* @__PURE__ */ new Set([
   "plan",
   "strategy_review",
   "strategy_change",
+  "strategy_agenda",
   "board_view",
   "board_deprioritise",
   "board_archive",
@@ -22322,13 +23105,26 @@ var TOOLS_REQUIRING_PAPI = /* @__PURE__ */ new Set([
   "handoff_generate"
 ]);
 function createServer(adapter2, config2) {
+  const __pkgFilename = fileURLToPath(import.meta.url);
+  const __pkgDir = dirname(__pkgFilename);
+  let serverVersion = "unknown";
+  try {
+    const pkg = JSON.parse(readFileSync5(join12(__pkgDir, "..", "package.json"), "utf-8"));
+    serverVersion = pkg.version ?? "unknown";
+  } catch {
+  }
   const server2 = new Server(
-    { name: "papi", version: "0.1.0" },
+    { name: "papi", version: serverVersion },
     { capabilities: { tools: {}, prompts: {} } }
   );
+  if (config2.adapterType === "md") {
+    process.stderr.write(
+      "\n\u26A0 PAPI is running in md mode \u2014 your cycles are not visible on the hosted dashboard.\n  Configure DATABASE_URL or sign up at https://getpapi.ai/setup to enable observability.\n\n"
+    );
+  }
   const __filename = fileURLToPath(import.meta.url);
   const __dirname2 = dirname(__filename);
-  const skillsDir = join10(__dirname2, "..", "skills");
+  const skillsDir = join12(__dirname2, "..", "skills");
   function parseSkillFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match) return null;
@@ -22346,7 +23142,7 @@ function createServer(adapter2, config2) {
       const mdFiles = files.filter((f) => f.endsWith(".md"));
       const prompts = [];
       for (const file of mdFiles) {
-        const content = await readFile5(join10(skillsDir, file), "utf-8");
+        const content = await readFile5(join12(skillsDir, file), "utf-8");
         const meta = parseSkillFrontmatter(content);
         if (meta) {
           prompts.push({ name: meta.name, description: meta.description });
@@ -22362,7 +23158,7 @@ function createServer(adapter2, config2) {
     try {
       const files = await readdir2(skillsDir);
       for (const file of files.filter((f) => f.endsWith(".md"))) {
-        const content = await readFile5(join10(skillsDir, file), "utf-8");
+        const content = await readFile5(join12(skillsDir, file), "utf-8");
         const meta = parseSkillFrontmatter(content);
         if (meta?.name === name) {
           const body = content.replace(/^---\n[\s\S]*?\n---\n*/, "");
@@ -22381,6 +23177,7 @@ function createServer(adapter2, config2) {
       planTool,
       strategyReviewTool,
       strategyChangeTool,
+      strategyAgendaTool,
       boardViewTool,
       boardDeprioritiseTool,
       boardArchiveTool,
@@ -22435,6 +23232,7 @@ function createServer(adapter2, config2) {
       }
     }
     const timer2 = startTimer();
+    recordToolCall(name);
     let result;
     switch (name) {
       case "plan":
@@ -22446,6 +23244,9 @@ function createServer(adapter2, config2) {
       case "strategy_change":
         result = await handleStrategyChange(adapter2, config2, safeArgs);
         break;
+      case "strategy_agenda":
+        result = await handleStrategyAgenda(adapter2, config2, safeArgs);
+        break;
       case "board_view":
         result = await handleBoardView(adapter2, safeArgs);
         break;
@@ -22498,7 +23299,7 @@ function createServer(adapter2, config2) {
         result = await handleInit(config2, safeArgs);
         break;
       case "orient":
-        result = await handleOrient(adapter2, config2);
+        result = await handleOrient(adapter2, config2, safeArgs);
         break;
       case "hierarchy_update":
         result = await handleHierarchyUpdate(adapter2, safeArgs);
@@ -22539,6 +23340,10 @@ function createServer(adapter2, config2) {
       });
     } catch {
     }
+    if (config2.adapterType === "md") {
+      const mdProjectSlug = config2.projectRoot ? config2.projectRoot.split("/").pop() : void 0;
+      emitMdAdapterPing(name, { duration_ms: elapsed, success: !isError }, config2.userId, mdProjectSlug);
+    }
     const telemetryProjectId = process.env["PAPI_PROJECT_ID"];
     if (telemetryProjectId) {
       emitToolCall(telemetryProjectId, name, elapsed, {
@@ -22566,7 +23371,7 @@ function createServer(adapter2, config2) {
 var __dirname = dirname2(fileURLToPath2(import.meta.url));
 var pkgVersion = "unknown";
 try {
-  const pkg = JSON.parse(readFileSync4(join11(__dirname, "..", "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync6(join13(__dirname, "..", "package.json"), "utf-8"));
   pkgVersion = pkg.version;
 } catch {
 }