@papi-ai/server 0.7.80 → 0.7.81

package/dist/index.js

@@ -29,6 +29,7 @@ __export(git_exports, {
   ensureTagAtHead: () => ensureTagAtHead,
   findTaskCommitsOnBase: () => findTaskCommitsOnBase,
   getBranchDiff: () => getBranchDiff,
+  getCommitFiles: () => getCommitFiles,
   getCommitsSinceTag: () => getCommitsSinceTag,
   getCurrentBranch: () => getCurrentBranch,
   getDocPathsTouchedOnBranch: () => getDocPathsTouchedOnBranch,
@@ -42,11 +43,13 @@ __export(git_exports, {
   getModifiedFiles: () => getModifiedFiles,
   getOriginRepoSlug: () => getOriginRepoSlug,
   getOriginUrl: () => getOriginUrl,
+  getPathsDifferingFrom: () => getPathsDifferingFrom,
   getPullRequestUrl: () => getPullRequestUrl,
   getRemoteBranchFiles: () => getRemoteBranchFiles,
   getRootCommitHash: () => getRootCommitHash,
   getStagedFiles: () => getStagedFiles,
   getTagTarget: () => getTagTarget,
+  getTaskDiff: () => getTaskDiff,
   getTaskIdsOnBranch: () => getTaskIdsOnBranch,
   getTrackedModifiedFiles: () => getTrackedModifiedFiles,
   getUnmergedBranches: () => getUnmergedBranches,
@@ -272,6 +275,50 @@ function getBranchDiff(cwd, base = "origin/main", maxBytes = 2e5) {
   }
   return "";
 }
+function getTaskDiff(cwd, taskId, base = "origin/main", maxBytes = 2e5) {
+  const truncate2 = (out) => out.length > maxBytes ? `${out.slice(0, maxBytes)}
+
+... [diff truncated at ${Math.round(maxBytes / 1024)} KB]` : out;
+  try {
+    const shas = execFileSync(
+      "git",
+      ["log", "--all", "--format=%H", `--grep=${taskId})`, "--fixed-strings"],
+      { cwd, encoding: "utf-8", maxBuffer: 8 * 1024 * 1024 }
+    ).split("\n").map((s) => s.trim()).filter(Boolean);
+    if (shas.length > 0) {
+      const parts = [];
+      for (const sha of [...shas].reverse()) {
+        try {
+          const one = execFileSync("git", ["diff", `${sha}^..${sha}`], {
+            cwd,
+            encoding: "utf-8",
+            maxBuffer: 32 * 1024 * 1024
+          });
+          if (one) parts.push(one);
+        } catch {
+        }
+      }
+      const out = parts.join("\n");
+      if (out) {
+        const range = shas.length === 1 ? shas[0].slice(0, 8) : `${shas[shas.length - 1].slice(0, 8)}\u2026${shas[0].slice(0, 8)}`;
+        return {
+          diff: truncate2(out),
+          scope: "task-commits",
+          detail: `${shas.length} commit(s) for ${taskId} (${range}), each against its own parent`
+        };
+      }
+    }
+  } catch {
+  }
+  const branch = getCurrentBranch(cwd);
+  const diff = getBranchDiff(cwd, base, maxBytes);
+  if (!diff) return { diff: "", scope: "none", detail: "no diff resolved" };
+  return {
+    diff,
+    scope: "whole-branch",
+    detail: `no commit naming ${taskId} was found, so this is the ENTIRE diff of ${branch ?? "the current branch"} vs ${base} \u2014 it may include other tasks' work, and may not include this task's`
+  };
+}
 function getHeadCommitSubject(cwd) {
   try {
     const out = execFileSync("git", ["log", "-1", "--format=%s"], {
@@ -319,6 +366,28 @@ function branchExists(cwd, branch) {
     return false;
   }
 }
+function getPathsDifferingFrom(cwd, target) {
+  try {
+    const out = execFileSync("git", ["diff", "--name-only", "HEAD", target], {
+      cwd,
+      encoding: "utf-8"
+    });
+    return out.split("\n").map((l) => l.trim()).filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+function getCommitFiles(cwd, ref = "HEAD") {
+  try {
+    const out = execFileSync("git", ["show", "--name-only", "--pretty=format:", ref], {
+      cwd,
+      encoding: "utf-8"
+    });
+    return out.split("\n").map((l) => l.trim()).filter(Boolean);
+  } catch {
+    return null;
+  }
+}
 function checkoutBranch(cwd, branch) {
   try {
     execFileSync("git", ["checkout", branch], { cwd, encoding: "utf-8" });
@@ -1329,7 +1398,7 @@ var init_proxy_adapter = __esm({
       "listContributorReleasePrs",
       "claimReview",
       "getSiblingAds",
-      "getSiblingRepoTasks"
+      "getSiblingRepoTasks",
       // task-2828 (C339): attributed-intelligence analytics reader — pg-only that cycle.
       // task-2864 (C343): WIRED. getModelOutcomeStats now has an edge case handler (raw
       // SQL via postgres.js mirroring the pg query + inlined computeModelOutcomes bucketing)
@@ -1353,6 +1422,28 @@ var init_proxy_adapter = __esm({
       // (case handler + ALLOWED_METHODS/WRITE_METHODS entries), so it forwards for
       // hosted callers and persists a project-scoped cycle_progress_steps row. Removed
       // from NO_FORWARD (was the task-2484 pg-only gap) — hosted parity restored.
+      //
+      // (3) pg-only optimisations probed STRUCTURALLY with a local fallback beside them.
+      // These are the dangerous class: the caller asks `typeof adapter.X === 'function'`
+      // to decide whether the fast path exists, and the get-trap answers "yes" for any
+      // name absent from this set. The probe then passes, the call forwards, and the
+      // edge 403s — while a working fallback sits a few lines below, unreachable.
+      // A method belongs here when BOTH are true: it is probed by `typeof` rather than
+      // called unconditionally, and the probe's else-branch is a real fallback.
+      //
+      // task-3290 (C361): allocateActiveDecision + applyActiveDecisionUpdates are pg-only
+      // (atomic id allocation; transactional batch apply). Both are probed in
+      // services/strategy.ts — asDecisionIdAllocator and asDecisionBatchApplier — and both
+      // have read-then-write / sequential fallbacks. Hosted users hit a 403 minting ANY
+      // Active Decision via setup's AD seed or strategy_change until these were listed.
+      "allocateActiveDecision",
+      "applyActiveDecisionUpdates",
+      // task-3290 (C361), same sweep: getLastZoomOutCycle was documented in the parity
+      // ledger as "proxy NO_FORWARD → safe no-op" while NOT being in this set. It is
+      // optional-chain probed in services/health.ts and wrapped in try/catch, so it
+      // degraded rather than crashed — but every hosted `orient` paid a round-trip to
+      // earn a silent 403. Listing it makes the ledger's claim true and skips the trip.
+      "getLastZoomOutCycle"
     ]);
     ProxyPapiAdapter = class _ProxyPapiAdapter {
       endpoint;
@@ -1884,6 +1975,21 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       updateDogfoodEntryStatus(id, status, linkedTaskId) {
         return this.invoke("updateDogfoodEntryStatus", [id, status, linkedTaskId]);
       }
+      // --- Project conventions (task-3271) ---
+      //
+      // Wired to the edge handler from the start rather than parked in NO_FORWARD.
+      // The hosted remote connector is the only install path an external user has,
+      // so a local-only conventions store would be a feature nobody in the actual
+      // user base can reach.
+      listConventions() {
+        return this.invoke("listConventions");
+      }
+      createConvention(convention) {
+        return this.invoke("createConvention", [convention]);
+      }
+      deleteConvention(id) {
+        return this.invoke("deleteConvention", [id]);
+      }
       // --- Harness inventory (task-1896) ---
       getHarnessInventory() {
         return this.invoke("getHarnessInventory");
@@ -7407,6 +7513,24 @@ If a candidate AD body could be invalidated by running a SQL query, refreshing a
 **Negative example (reject):** "External user feedback is now flowing. Stonebridge Systems is actively building." \u2014 this is a fact about the current state of the world. Capture as dogfood/signal observation; do not mint.
 
 This rule applies to: new ADs proposed during planning (Step 9), strategy review AD updates (section 5), and strategy_change AD updates. If you find an existing AD that violates this rule during housekeeping, propose deleting it (action: "delete") with a one-line rationale.`;
+var AD_ADMISSION_RULES = `**AD Admission Rule \u2014 PROPOSE a decision when the project takes a real stance.**
+
+The guard above says what to reject. This says what to propose. Rejecting is not the safe default: a stance that never gets minted is a stance the next cycle cannot see, and re-deciding it every session is the exact cost this project is paying you to remove. When a candidate passes all four tests below, propose it \u2014 do not wait for the next strategy review.
+
+**The four tests. All four must pass.**
+(a) **Alternatives were real.** Something else could genuinely have been chosen. If there was only ever one way to do it, it is not a decision.
+(b) **It constrains future work not yet scoped.** It changes what a task nobody has written yet will do. Not "it describes work we did" \u2014 "it binds work we have not planned".
+(c) **It is arguable today.** A competent person could argue the other side right now, with the evidence currently available. Not "was once debated" \u2014 live.
+(d) **Reversing it costs more than making it did.** If undoing it is as cheap as doing it, nothing is being constrained.
+
+**Routing for a near-miss \u2014 a candidate that fails one test still goes somewhere.**
+- **Fails (c) only** \u2014 real alternatives, binds future work, expensive to reverse, but nobody is arguing the other side any more: it is a **Convention**, not a Decision. A Convention is a settled answer to a recurring question; it does not need adjudicating, it needs to be *known* by whoever builds next. Record it as a project convention so it rides future build handoffs. Do not mint it as an AD, and do not drop it.
+- **Fails (b)** \u2014 it does not constrain any future work: it is not durable at all, it is just work. Capture it as a task, a build report note, or a doc. Do not mint it.
+- **Fails (a) or (d)** \u2014 not a stance. Same routing as (b): capture it, do not mint it.
+
+**Copy variants are NEVER decisions.** A tagline, a headline, a value proposition, a piece of marketing or product wording: swapping one for another constrains no future work, so it fails test (b) outright. Wording changes as often as the market teaches you something, and routing every edit through decision ceremony is what buries the handful of decisions that genuinely constrain the project. Edit the wording where the wording lives. If two variants are being compared against a measurement, that is an experiment, not a decision.
+
+**A decision decaying into a convention is the healthy path, not a failure.** When a live AD stops being arguable \u2014 the alternatives are no longer on the table and nobody would re-litigate it \u2014 say so during housekeeping and propose retiring it into a convention. An AD registry where most entries are settled is one nobody reads.`;
 var AD_CONFLICT_SURFACING_RULES = `**A contradiction is NOT a veto \u2014 surface it, never silently shelve it.**
 
 Active Decisions are *active*: they can be superseded, modified, or abandoned. You do NOT have authority to kill a piece of work simply because it cuts against one. That is the user's call, and they can only make it if you show it to them.
@@ -7653,7 +7777,7 @@ var PLAN_FRAGMENT_SPIKE = `
 var PLAN_FRAGMENT_DESIGN_BRIEF = `
    **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."
+   - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`PRODUCT.md\` (strategic: brand, users, product purpose, design principles) AND \`DESIGN.md\` (visual tokens: palette, typography, elevation, components) 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.
    - REVIEW POINTS: What the Owner must approve before the design is considered done (e.g. layout, copy, colour, imagery).
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION sections as normal.
@@ -7685,11 +7809,11 @@ var PLAN_FRAGMENT_OPS_BRIEF = `
 var PLAN_FRAGMENT_UI = `
    **UI/visual task detection:** Apply these additions ONLY to tasks whose PRIMARY scope is frontend visual work \u2014 the task's main deliverable must be a UI change, new component, visual design, or page. Do NOT apply to backend tasks, DB migrations, or prompt/config changes that merely mention a dashboard or page in passing. Signal: the task would fail if no .tsx/.css files were changed. If uncertain, skip the UI additions.
    When a task IS a UI task (primary scope is visual/frontend):
-   - Add to SCOPE: "Read \`.impeccable.md\` for component patterns, anti-patterns, and dev-loop design rules. Read \`docs/branding/brand-book.html\` for brand identity (positioning, voice, palette as final canon). Use the \`frontend-design\` skill for implementation."
+   - Add to SCOPE: "Read \`PRODUCT.md\` for product purpose, users and design principles, and \`DESIGN.md\` for the visual tokens (palette, typography, elevation, components) \u2014 these are the two files the \`impeccable\` skill reads, and every visual decision must align with them. Run \`impeccable init\` to create them if they do not exist. Use the \`frontend-design\` skill for implementation."
    - For M/L UI tasks, add to SCOPE: "Use the full impeccable workflow: shape (direction approval) \u2192 craft (design+build via \`impeccable craft\` / frontend-design) \u2192 live (in-browser HMR iteration via \`impeccable live\`) \u2192 detect (slop check). The approved direction is the quality bar; expect 2-3 iterations. Playground is for pre-build direction approval of shareable/static artifacts or non-dashboard explorers; Playwright is for post-build verification, not mid-design iteration."
    - Add to ACCEPTANCE CRITERIA: "[ ] Visually verify rendered output in browser \u2014 provide localhost URL or screenshot to user for review." and "[ ] No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips."
-   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection \u2014 pull from \`docs/branding/brand-book.html\` for canonical brand identity."
-   The planner's job is scoping, not design direction. Design decisions happen at build time via \`.impeccable.md\` (dev patterns) + \`docs/branding/brand-book.html\` (brand identity) and the frontend-design skill \u2014 don't try to write design specs in the handoff.`;
+   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection \u2014 pull from \`PRODUCT.md\` and \`DESIGN.md\` for canonical brand identity."
+   The planner's job is scoping, not design direction. Design decisions happen at build time via \`PRODUCT.md\` (product purpose, users, design principles) + \`DESIGN.md\` (visual tokens) and the frontend-design skill \u2014 don't try to write design specs in the handoff.`;
 var PLAN_FRAGMENT_PRODUCT_BRIEF = `
 12. **Product Brief** \u2014 Check whether the product brief still reflects reality. Update the brief when ANY of these apply:
    - A new AD was created or an existing AD was superseded that changes product scope, target user, or positioning
@@ -7783,6 +7907,8 @@ ${AD_CONFLICT_SURFACING_RULES}
 
 ${AD_REJECTION_RULES}
 
+${AD_ADMISSION_RULES}
+
    **\u2192 PERSIST:** EVERY AD you created, updated, or confirmed with changes MUST appear in \`activeDecisions\` array in Part 2. Include the full replacement body with ### heading.
 
 ### Operational Quality Rules
@@ -8325,6 +8451,8 @@ You MUST cover these 5 sections. Each is mandatory.
 
 ${AD_REJECTION_RULES}
 
+${AD_ADMISSION_RULES}
+
 **Registered Documents:** If a "### Registered Documents" section is present in context, scan it for: (a) research findings that contradict current ADs or strategy, (b) unactioned research that should influence the next plan. Reference relevant docs by title in your review. If unregistered docs are listed, flag 1-2 that look strategically relevant and suggest registering them.
 
 **Doc Action Staleness:** If a "### Doc Action Staleness" section is present, treat it as a research-to-action audit. For each entry:
@@ -8673,6 +8801,8 @@ The body field must be the COMPLETE replacement text for the AD block (including
 
 ${AD_REJECTION_RULES}
 
+${AD_ADMISSION_RULES}
+
 ## PHASE UPDATES
 
 If the strategic change affects the project's phase structure, include a phaseUpdates array.
@@ -8845,10 +8975,15 @@ function buildPreScanInstruction(opts) {
   const docRouting = opts.hosted ? "paste the relevant content (decision records, roadmap, spec excerpts) directly into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "pass local doc file paths as `sources` (comma-separated), or paste content into `description`.";
   return [
     `**\u{1F50E} Before you generate anything \u2014 scan the project and gather real context.**`,
-    `A brief and Active Decisions built from the real code and docs are far sharper than ones guessed from a project name. You (the agent running this) have local access that PAPI does not \u2014 do the gathering, then pass it back.`,
+    // task-3293: state the division of labour ONCE, up front. A user watching this
+    // session sees PAPI say it cannot read their files and then sees their agent
+    // read their files. That reads as a contradiction, or worse, unless it is named
+    // first: PAPI never touches the filesystem, YOU do, and you send back a summary.
+    `**How this works:** PAPI has no access to your machine and never reads your files. You (the agent running this) do the reading locally and send back a short summary. Nothing is uploaded except what you pass in that summary.`,
+    `A brief and Active Decisions built from the real code and docs are far sharper than ones guessed from a project name.`,
     ``,
     `1. **Confirm the environment.** Check that you are running from the root of this project's dev environment \u2014 the folder that holds its source, git history, and docs. If you are not there, or you are connected over a remote connector with no access to the user's files, say so and ask the user where the project lives before continuing.`,
-    `2. **Scan the code.** List the top-level directories and files, read the package/build manifest and the README (first ~3000 chars), and collect recent commit subjects. Pass this back as \`codebase_scan\` on the next \`setup\` call.`,
+    `2. **Scan the code.** List the top-level directories and files, read the package/build manifest and the README (first ~3000 chars), and collect recent commit subjects. Pass this back as \`codebase_scan\` on the next \`setup\` call. **Never include secrets** \u2014 skip \`.env\` and any credential, key or certificate file, and do not paste tokens, passwords or connection strings into the summary. PAPI also strips secret-shaped values server-side, but do not rely on that: leave them out.`,
     `3. **Scan the docs.** Look through \`docs/\`, design notes, ADRs/decision records, and any roadmap or planning files \u2014 not just code.`,
     `4. **Check for sibling / separate repos.** Many projects span more than one repo (a separate frontend, backend, infra, or mobile repo, or other packages in a monorepo). Ask the user whether any related repos or directories exist, and scan those too.`,
     `5. **Ask the user to point you at extra context.** Prompt them: "Is there anything else I should read before setting this up \u2014 a PRD or spec, decision records, a roadmap, or links to related repos or docs?" Fold whatever they share into the scan.`,
@@ -12345,7 +12480,9 @@ async function buildSessionGuidance(callerKey) {
 
 // src/services/onboarding-coaching.ts
 var ONBOARDING_EARLY_CYCLE_MAX = 2;
+var ONBOARDING_FIRST_CYCLE_MAX = 1;
 var MAX_COACHING_LINES = 4;
+var COACH_EXPLAIN_VALUE = "First cycle: before you run each step, tell the user in one line what it produces and why it is worth the wait, then run it. Say what it means for their project, not what the tool does.";
 var COACH_CONNECT_REPO = "No repository is linked to this project yet. Link your repo from the dashboard Settings (or capture it during `setup`) so builds, reviews, and releases attach to the right codebase.";
 var COACH_ROOT_DIR = "Before building, confirm this session is running from your project root directory, so commits and builds land against the right files.";
 var COACH_CLICKABLE_TASKS = "Task cards on your dashboard expand on click. Open one to read its full build handoff, comments, and history.";
@@ -12357,10 +12494,14 @@ var ONBOARDING_COACHING_HEADING = "## Getting Started";
 function buildOnboardingCoaching(state) {
   const lines = [];
   const isEarly = state.cycleNumber <= ONBOARDING_EARLY_CYCLE_MAX;
+  const isFirstRun = state.cycleNumber <= ONBOARDING_FIRST_CYCLE_MAX;
   const { surface } = state;
   if (state.repoConnected === false && (surface === "orient" || surface === "plan")) {
     lines.push(COACH_CONNECT_REPO);
   }
+  if (isFirstRun) {
+    lines.push(COACH_EXPLAIN_VALUE);
+  }
   if (state.hasLocalWorkspace && (surface === "setup" || surface === "orient" && isEarly)) {
     lines.push(COACH_ROOT_DIR);
   }
@@ -12500,7 +12641,7 @@ function savePrepareContextFile(projectId, callerKey, content) {
 var planPrepareCache = new PerCallerCache();
 var planTool = {
   name: "plan",
-  description: 'Run once per cycle to select tasks and generate BUILD HANDOFFs. Call after setup (first time) or after completing all builds AND running release for the previous cycle. Returns prioritised task recommendations with detailed implementation specs. NEVER call when unbuilt cycle tasks exist \u2014 build and release first. First call returns a planning prompt for you to execute (prepare phase). Then call again with mode "apply" and your output to write results. Use skip_handoffs=true for large backlogs \u2014 handoffs are then generated separately via `handoff_generate`.',
+  description: 'Turn a backlog into one scoped cycle of work, with a written spec for every task in it. plan reads the whole board, the decisions this project has already taken, and how much it actually delivered in recent cycles, then prioritises what to do next and writes a per-task BUILD HANDOFF: scope, what is deliberately out of scope, acceptance criteria, files likely touched, security notes, and the shared branch each task belongs on. It also reports board health, so stale, blocked and drifting work is visible instead of accumulating. This is not the same as planning inside one session: the cycle, the specs and the reasoning are stored, so the next session, the next tool, or the next person picks up where this one stopped. Run once per cycle, after setup the first time, or after completing all builds AND running release for the previous cycle. NEVER call when unbuilt cycle tasks exist: build and release first. First call returns a planning prompt for you to execute (prepare phase). Then call again with mode "apply" and your output to write results. Use skip_handoffs=true for large backlogs, and generate handoffs separately via `handoff_generate`.',
   annotations: { title: "Plan Cycle", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -17395,6 +17536,33 @@ async function ensureDesignHookRegistered(projectRoot) {
 var TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
 var CONVENTIONS_SENTINEL = "<!-- PAPI_CONVENTIONS -->";
 var CONVENTIONS_HEADING = "## Code Style Conventions";
+function describeSeedWriteFailure(err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  const CLASSES = [
+    [
+      /\b(?:401|403)\b|permission|unauthor|forbidden/i,
+      "the storage backend refused the write (permission denied)."
+    ],
+    [
+      /\b(?:5\d\d)\b|internal server error|bad gateway|unavailable/i,
+      "the storage backend returned a server error."
+    ],
+    [
+      /timeout|timed out|ETIMEDOUT|ECONNRESET|ECONNREFUSED|fetch failed|network/i,
+      "PAPI could not reach the storage backend."
+    ],
+    [
+      /duplicate key|unique constraint|23505/i,
+      "a decision with that id already exists."
+    ],
+    [
+      /violates|constraint|invalid input syntax|22P02|23\d{3}/i,
+      "the storage backend rejected the decision record."
+    ]
+  ];
+  const matched = CLASSES.find(([pattern]) => pattern.test(raw));
+  return matched ? `could not be saved \u2014 ${matched[1]}` : "could not be saved \u2014 the write to the storage backend failed.";
+}
 async function applySetupOutputs(adapter2, config2, input, collector, briefText, adSeedText, conventionsText) {
   const warnings = [];
   await adapter2.updateProductBrief(briefText);
@@ -17434,9 +17602,19 @@ async function applySetupOutputs(adapter2, config2, input, collector, briefText,
   let seededAds = 0;
   let skippedAds = 0;
   if (adSeedText) {
+    let ads;
+    let adSeedFailed = false;
     try {
       const cleaned = adSeedText.replace(/^```(?:json)?\s*/m, "").replace(/\s*```\s*$/m, "").trim();
-      const ads = JSON.parse(cleaned);
+      ads = JSON.parse(cleaned);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warnings.push(
+        `AD seeding failed \u2014 active decisions were not created. Check that your ad_seed_response is valid JSON. Error: ${msg}`
+      );
+      adSeedFailed = true;
+    }
+    try {
       if (Array.isArray(ads)) {
         const existingAdIds = adapter2.getActiveDecisions ? new Set(
           (await adapter2.getActiveDecisions({ includeRetired: true }).catch(() => [])).map((a) => a.displayId)
@@ -17460,18 +17638,17 @@ async function applySetupOutputs(adapter2, config2, input, collector, briefText,
         }
       }
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
       warnings.push(
-        `AD seeding failed \u2014 active decisions were not created. Check that your ad_seed_response is valid JSON. Error: ${msg}`
+        `Active Decisions: ${describeSeedWriteFailure(err)}` + (seededAds > 0 ? ` ${seededAds} decision(s) were created before this and are saved \u2014 re-running \`setup\` will not duplicate them.` : " No decisions were created.") + " This is a PAPI-side failure, not a problem with your response."
       );
-      seededAds = 0;
+      adSeedFailed = true;
     }
     if (skippedAds > 0) {
       warnings.push(
         `Active Decisions: detected ${skippedAds} existing AD(s) and left them untouched${seededAds > 0 ? `; created ${seededAds} new one(s)` : " (none new to create)"}.`
       );
     } else if (seededAds === 0 && adSeedText) {
-      if (!warnings.some((w) => w.startsWith("AD seeding failed"))) {
+      if (!adSeedFailed) {
         warnings.push(
           "AD seeding produced 0 active decisions \u2014 the JSON may be valid but empty or missing required `id` and `body` fields."
         );
@@ -17532,6 +17709,61 @@ function isSecretFile(name) {
   const lower = name.toLowerCase();
   return SECRET_PATTERNS.some((p) => lower.includes(p));
 }
+var SECRET_VALUE_PATTERNS = [
+  // KEY=value / KEY: value where the KEY names a credential. Value must be
+  // non-trivial so `API_KEY=` or `TOKEN=changeme` placeholders in docs are hit too.
+  /\b([A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|PRIVATE_KEY|ACCESS_KEY|API_KEY|APIKEY|AUTH)[A-Z0-9_]*)\s*[:=]\s*\S+/gi,
+  // Provider-issued key formats.
+  /\bsk-[A-Za-z0-9_-]{16,}/g,
+  // OpenAI / Anthropic style
+  /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g,
+  // GitHub tokens
+  /\bgithub_pat_[A-Za-z0-9_]{20,}/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  // AWS access key id
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/g,
+  // Slack
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+  // JWT
+  // Credentials embedded in a connection string.
+  /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s@]+@/gi,
+  // Whole PEM blocks.
+  /-----BEGIN[^-]*PRIVATE KEY-----[\s\S]*?-----END[^-]*PRIVATE KEY-----/g,
+  /\bBearer\s+[A-Za-z0-9._-]{20,}/g
+];
+var REDACTED = "[redacted by PAPI]";
+function redactPackageJson(pkg) {
+  if (!pkg) return pkg;
+  const out = { ...pkg };
+  for (const field of ["description", "name"]) {
+    if (typeof out[field] === "string") out[field] = redactSecretValues(out[field]);
+  }
+  return out;
+}
+function normaliseClientScan(raw) {
+  return {
+    topLevelDirs: raw.topLevelDirs ?? [],
+    topLevelFiles: (raw.topLevelFiles ?? []).filter((f) => !isSecretFile(f)),
+    packageJson: redactPackageJson(raw.packageJson),
+    readme: redactSecretValues(raw.readme),
+    configFiles: (raw.configFiles ?? []).filter((f) => !isSecretFile(f)),
+    sourceFiles: raw.sourceFiles ?? [],
+    totalFiles: raw.totalFiles ?? 0,
+    sourcePaths: (raw.sourcePaths ?? []).filter((p) => !isSecretFile(p)),
+    commitHistory: raw.commitHistory?.map((c) => redactSecretValues(c))
+  };
+}
+function redactSecretValues(text) {
+  if (!text) return text;
+  let out = text;
+  for (const pattern of SECRET_VALUE_PATTERNS) {
+    out = out.replace(pattern, (match) => {
+      const kv = match.match(/^([A-Z0-9_]+)\s*[:=]/i);
+      return kv ? `${kv[1]}=${REDACTED}` : REDACTED;
+    });
+  }
+  return out;
+}
 async function safeReadFile(filePath, maxBytes = 1e4) {
   if (isSecretFile(basename(filePath))) return null;
   try {
@@ -17721,18 +17953,7 @@ async function prepareSetup(adapter2, config2, input) {
   const hasUserSignalForScan = Boolean(input.description?.trim()) || Boolean(input.targetUsers?.trim());
   const shouldScan = isExistingProject || !hasUserSignalForScan;
   if (input.codebaseScan) {
-    const raw = input.codebaseScan;
-    const clientScan = {
-      topLevelDirs: raw.topLevelDirs ?? [],
-      topLevelFiles: raw.topLevelFiles ?? [],
-      packageJson: raw.packageJson,
-      readme: raw.readme,
-      configFiles: raw.configFiles ?? [],
-      sourceFiles: raw.sourceFiles ?? [],
-      totalFiles: raw.totalFiles ?? 0,
-      sourcePaths: raw.sourcePaths ?? [],
-      commitHistory: raw.commitHistory
-    };
+    const clientScan = normaliseClientScan(input.codebaseScan);
     const hasScanSignal = Boolean(clientScan.readme) || Boolean(clientScan.packageJson) || Boolean(clientScan.commitHistory && clientScan.commitHistory.length > 0) || clientScan.topLevelDirs.length > 0 || clientScan.topLevelFiles.length > 0;
     if (hasScanSignal) {
       codebaseSummary = formatCodebaseSummary(clientScan, sourceContents);
@@ -17747,7 +17968,10 @@ async function prepareSetup(adapter2, config2, input) {
     }
   } else if (shouldScan && !canScanFilesystem && input.existingProject === true) {
     warnings.push(
-      "Codebase scan skipped \u2014 PAPI is connected over hosted transport and cannot read your local files. To adopt an existing project, provide `description` and `target_users` directly (the brief generator will use them), or run `setup` from a local stdio install (`npx @papi-ai/server`) where PAPI can scan the tree."
+      // task-3293: this used to end at "cannot read your local files", which read as
+      // a flat contradiction to the very next thing the user saw — their own agent
+      // reading those files. Name the division of labour instead of just the limit.
+      "Codebase scan skipped \u2014 PAPI has no access to your machine and never reads your files directly. Your AI client can: ask it to scan the project and pass the summary back as `codebase_scan` (leaving out `.env` and anything holding keys, tokens or passwords). Or provide `description` and `target_users` directly and the brief generator will use those instead."
     );
   }
   const hasCodebaseSignal = Boolean(codebaseSummary && codebaseSummary.trim().length > 0);
@@ -18077,7 +18301,7 @@ async function ensureMcpJsonGitignored(projectRoot) {
 // src/tools/setup.ts
 var setupTool = {
   name: "setup",
-  description: 'Create a new PAPI-tracked project \u2014 generates your Product Brief, Active Decisions, and CLAUDE.md workflow instructions. Run after configuring your MCP credentials (via `init` or manually from getpapi.ai). Only project_name is required \u2014 description and target_users are derived from README, package.json, and commit history when omitted. Set existing_project: true to adopt an existing codebase. ADOPTING AN EXISTING PROJECT OVER A REMOTE/HOSTED CONNECTOR (no local stdio install): PAPI cannot read your filesystem, so YOU (the client) must gather a `codebase_scan` and pass it in \u2014 list top-level dirs/files, the package manifest, the README (first ~3000 chars), and recent commit subjects. Without it, adoption falls back to asking for description/target_users. On a local stdio install PAPI scans the tree itself, so `codebase_scan` is optional there. First call returns prompts (prepare phase), then call again with mode "apply" and your outputs. After setup, run `plan` to start your first cycle.',
+  description: 'Give a project a memory, so every later session starts with its context instead of a blank slate. Setup reads the project, writes a Product Brief that says what it is for and who it serves, records the first Active Decisions and build conventions so settled answers outlive the session that found them, and installs the workflow instructions the coding assistant follows from then on. Everything after this (planning, building, reviewing) reads from what setup writes. It takes a few minutes and runs in two passes: the first returns prompts for you to execute, the second saves the results. Tell the user what each pass is doing while it runs. Run after configuring your MCP credentials (via `init` or manually from getpapi.ai). Only project_name is required \u2014 description and target_users are derived from README, package.json, and commit history when omitted. Set existing_project: true to adopt an existing codebase. ADOPTING AN EXISTING PROJECT OVER A REMOTE/HOSTED CONNECTOR (no local stdio install): PAPI cannot read your filesystem, so YOU (the client) must gather a `codebase_scan` and pass it in \u2014 list top-level dirs/files, the package manifest, the README (first ~3000 chars), and recent commit subjects. Without it, adoption falls back to asking for description/target_users. On a local stdio install PAPI scans the tree itself, so `codebase_scan` is optional there. First call returns prompts (prepare phase), then call again with mode "apply" and your outputs. After setup, run `plan` to start your first cycle.',
   annotations: { title: "Set Up Project", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -18261,6 +18485,36 @@ Tip: See \`docs/templates/example-project-brief.md\` for an example of a well-wr
 Next step: run \`plan\` to start your first planning cycle.${filesToWriteSection}`
   );
 }
+var SETUP_NARRATION_HEADING = "**What happens now, and how long it takes**";
+function formatSetupNarration(result) {
+  const steps = [];
+  if (result.preScanInstruction || result.newProjectInstruction) {
+    steps.push("Gather the context below, so what follows describes this project rather than a generic one.");
+  }
+  if (result.briefPrompt) {
+    steps.push("Write the Product Brief: what this project is, who it is for, and what it has to get right. Every later plan reads it.");
+  }
+  if (result.adSeedPrompt) {
+    steps.push("Record the first Active Decisions, so the choices already made stop being re-argued in later sessions.");
+  }
+  if (result.conventionsPrompt) {
+    steps.push("Capture the build conventions this project expects, so they reach every future build without being restated.");
+  }
+  if (result.northStarPrompt) {
+    steps.push("Agree a North Star with the user, so progress can be judged against something.");
+  }
+  if (result.initialTasksPrompt) {
+    steps.push("Seed the backlog, so the first planning cycle has real work to choose from.");
+  }
+  steps.push('Call `setup` again with `mode: "apply"` to save all of it.');
+  return [
+    SETUP_NARRATION_HEADING,
+    "",
+    "Expect a few minutes end to end. Nothing is saved until the final step, so do not stop partway.",
+    "Say what you are doing as you go, in one line per step, so the wait is visible to the user:",
+    ...steps.map((s, i) => `${i + 1}. ${s}`)
+  ];
+}
 async function handleSetup(adapter2, config2, args, clientName) {
   const toolMode = args.mode;
   const REQUIRED_FIELDS = ["project_name"];
@@ -18304,6 +18558,7 @@ PAPI needs the project name. Description and target users are optional \u2014 th
         result.createdProject ? `Project "${result.projectName}" scaffolded \u2014 database tables created.
 ` : ""
       ];
+      sections.push(...formatSetupNarration(result), "");
       if (result.autoDetected) {
         sections.push(
           `**Codebase detected:** Existing codebase found \u2014 running in adoption mode. If this is wrong, re-run setup with \`existing_project: false\`.`,
@@ -20260,16 +20515,20 @@ function triggerSurfaceHitsOnBranch(projectRoot, baseRef = "origin/main") {
 }
 
 // src/services/build.ts
-function selectAutostashPaths(modified, untracked) {
+function selectAutostashPaths(modified, untracked, conflictingPaths) {
   const untrackedSet = new Set(untracked);
-  const isDocsPath = (p) => p === "docs" || p.startsWith("docs/");
   const isUntrackedDirEntry = (p) => p.endsWith("/") && untracked.some((u) => u.startsWith(p));
   const trackedDirty = modified.filter(
     (p) => !untrackedSet.has(p) && !isUntrackedDirEntry(p)
   );
-  const preservedDocs = untracked.filter(isDocsPath);
-  const stashableUntracked = untracked.filter((p) => !isDocsPath(p));
-  return { toStash: [...trackedDirty, ...stashableUntracked], preservedDocs };
+  if (conflictingPaths == null) {
+    return { toStash: trackedDirty, preservedDocs: untracked };
+  }
+  const conflicting = new Set(conflictingPaths);
+  return {
+    toStash: trackedDirty.filter((p) => conflicting.has(p)),
+    preservedDocs: untracked
+  };
 }
 function resolveRelatedDecisions(provided, buildHandoff) {
   const fromInput = (provided ?? "").split(",").map((s) => s.trim()).filter(Boolean);
@@ -20391,11 +20650,18 @@ function matchedPredictedEntry(changedPath, predicted) {
 function isPathInPredictedScope(changedPath, predicted) {
   return matchedPredictedEntry(changedPath, predicted) !== null;
 }
+function verifyCommitContents(cwd, intended) {
+  if (intended.length === 0) return [];
+  const actual = getCommitFiles(cwd);
+  if (actual === null) return [];
+  const actualSet = new Set(actual);
+  return intended.filter((p) => !actualSet.has(p));
+}
 function autoCommit(config2, taskId, taskTitle, predictedFiles) {
   const cwd = config2.projectRoot;
   const message = `feat(${taskId}): ${taskTitle}`;
-  if (!isGitAvailable()) return "Auto-commit: skipped (git not found).";
-  if (!isGitRepo(cwd)) return "Auto-commit: skipped (not a git repository).";
+  if (!isGitAvailable()) return { line: "Auto-commit: skipped (git not found).", missing: [] };
+  if (!isGitRepo(cwd)) return { line: "Auto-commit: skipped (not a git repository).", missing: [] };
   const safeRun = (fn) => {
     try {
       const r = fn();
@@ -20409,26 +20675,27 @@ function autoCommit(config2, taskId, taskTitle, predictedFiles) {
     `^(feat|fix|chore|refactor|docs|test|style|build|perf|ci)\\(${taskId}\\):`
   );
   if (headSubject && taskCommitRe.test(headSubject)) {
-    return `Auto-commit: skipped \u2014 HEAD already has a fresh ${taskId} commit (${headSubject}).`;
+    return { line: `Auto-commit: skipped \u2014 HEAD already has a fresh ${taskId} commit (${headSubject}).`, missing: [] };
   }
   const staged = getStagedFiles(cwd);
   if (staged.length > 0) {
-    return safeRun(() => commitStagedOnly(cwd, message)) + ` (selective staging respected: ${staged.length} file(s)).`;
+    const line = safeRun(() => commitStagedOnly(cwd, message)) + ` (selective staging respected: ${staged.length} file(s)).`;
+    return { line, missing: verifyCommitContents(cwd, staged) };
   }
   const checkpoint = readBuildCheckpointIfLocal({ cwd, taskId });
   const headSha = getHeadCommitSha(cwd);
   if (checkpoint?.lastCommitSha && headSha && checkpoint.lastCommitSha !== headSha) {
     const leftover = getModifiedFiles(cwd);
     if (leftover.length === 0) {
-      return "Auto-commit: skipped (builder already committed; working tree clean).";
+      return { line: "Auto-commit: skipped (builder already committed; working tree clean).", missing: [] };
     }
     const sample = leftover.slice(0, 10).join(", ");
     const more = leftover.length > 10 ? ` (+${leftover.length - 10} more)` : "";
-    return `Auto-commit: skipped \u2014 you already committed during this build, and ${leftover.length} file(s) are still modified. They were NOT committed, because at this point PAPI cannot tell your deliberately-excluded work from a concurrent session's files (task-3054). Left uncommitted: ${sample}${more}. If any belong to ${taskId}, \`git add\` them and re-run build_execute complete.`;
+    return { line: `Auto-commit: skipped \u2014 you already committed during this build, and ${leftover.length} file(s) are still modified. They were NOT committed, because at this point PAPI cannot tell your deliberately-excluded work from a concurrent session's files (task-3054). Left uncommitted: ${sample}${more}. If any belong to ${taskId}, \`git add\` them and re-run build_execute complete.`, missing: [] };
   }
   const modified = getModifiedFiles(cwd);
   if (modified.length === 0) {
-    return "Auto-commit: skipped (no working-tree changes).";
+    return { line: "Auto-commit: skipped (no working-tree changes).", missing: [] };
   }
   const commitResult = safeRun(() => stageAllAndCommit(cwd, message));
   if (predictedFiles && predictedFiles.length > 0) {
@@ -20437,13 +20704,22 @@ function autoCommit(config2, taskId, taskTitle, predictedFiles) {
     if (outOfScope.length > 0) {
       const sample = outOfScope.slice(0, 10).join(", ");
       const more = outOfScope.length > 10 ? ` (+${outOfScope.length - 10} more)` : "";
-      return `${commitResult} (staged all ${modified.length} changed file(s)). \u2139\uFE0F Scope drift: ${outOfScope.length} committed file(s) were outside the handoff's FILES LIKELY TOUCHED \u2014 handoff under-predicted: ${sample}${more}.`;
+      return {
+        line: `${commitResult} (staged all ${modified.length} changed file(s)). \u2139\uFE0F Scope drift: ${outOfScope.length} committed file(s) were outside the handoff's FILES LIKELY TOUCHED \u2014 handoff under-predicted: ${sample}${more}.`,
+        missing: verifyCommitContents(cwd, modified)
+      };
     }
     const matches = modified.slice(0, 5).map((p) => `${p} \u2190 ${matchedPredictedEntry(p, cleanedPredicted) ?? "?"}`).join(", ");
     const extra = modified.length > 5 ? ` (+${modified.length - 5} more)` : "";
-    return `${commitResult} (staged all ${modified.length} changed file(s), each matched to FILES LIKELY TOUCHED: ${matches}${extra}).`;
+    return {
+      line: `${commitResult} (staged all ${modified.length} changed file(s), each matched to FILES LIKELY TOUCHED: ${matches}${extra}).`,
+      missing: verifyCommitContents(cwd, modified)
+    };
   }
-  return `${commitResult} (staged all ${modified.length} changed file(s)).`;
+  return {
+    line: `${commitResult} (staged all ${modified.length} changed file(s)).`,
+    missing: verifyCommitContents(cwd, modified)
+  };
 }
 function pushAndCreatePR(config2, taskId, taskTitle, clientName, module, cycleNumber) {
   const lines = [];
@@ -20859,20 +21135,23 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
         );
       }
       if (hasUncommittedChanges(config2.projectRoot, AUTO_WRITTEN_PATHS)) {
+        const stashTarget = branchExists(config2.projectRoot, featureBranch) ? featureBranch : resolveBaseBranch(config2.projectRoot, config2.baseBranch);
+        const conflictingPaths = getPathsDifferingFrom(config2.projectRoot, stashTarget);
         const { toStash, preservedDocs } = selectAutostashPaths(
           getModifiedFiles(config2.projectRoot),
-          getUntrackedFiles(config2.projectRoot)
+          getUntrackedFiles(config2.projectRoot),
+          conflictingPaths
         );
-        const preservedNote = preservedDocs.length > 0 ? ` ${preservedDocs.length} untracked docs/ file(s) left in place (task-2092 \u2014 registered docs must never be swept).` : "";
+        const preservedNote = preservedDocs.length > 0 ? ` ${preservedDocs.length} untracked file(s) left in place, not stashed (task-3282 \u2014 an untracked file never blocks a branch switch, and a sub-agent's brand-new file is untracked by definition).` : "";
         if (toStash.length === 0) {
           if (preservedDocs.length > 0) {
-            branchLines.push(`Auto-stash skipped \u2014 only untracked docs/ files present.${preservedNote}`);
+            branchLines.push(`Auto-stash skipped \u2014 nothing tracked is dirty.${preservedNote}`);
           }
         } else {
           const stashLabel = `papi-autostash/${taskId}-${Math.floor(Date.now() / 1e3)}`;
           try {
             const { execFileSync: execFileSync7 } = await import("child_process");
-            execFileSync7("git", ["stash", "push", "-u", "-m", stashLabel, "--", ...toStash], {
+            execFileSync7("git", ["stash", "push", "-m", stashLabel, "--", ...toStash], {
               cwd: config2.projectRoot,
               encoding: "utf-8"
             });
@@ -21433,7 +21712,20 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
   } else if (dbOnlyMode) {
     commitLine = DB_ONLY_COMPLETE_NOTICE;
   } else {
-    commitLine = autoCommit(config2, taskId, task.title, task.buildHandoff?.filesLikelyTouched);
+    const outcome = autoCommit(config2, taskId, task.title, task.buildHandoff?.filesLikelyTouched);
+    commitLine = outcome.line;
+    if (outcome.missing.length > 0) {
+      const sample = outcome.missing.slice(0, 10).join(", ");
+      const more = outcome.missing.length > 10 ? ` (+${outcome.missing.length - 10} more)` : "";
+      if (input.completed === "yes" && !atomicCommitDone) {
+        try {
+          await adapter2.updateTaskStatus(taskId, task.status);
+        } catch {
+        }
+      }
+      commitLine = `\u26A0\uFE0F AUTO-COMMIT VERIFICATION FAILED \u2014 the commit does NOT contain ${outcome.missing.length} file(s) that were staged for it. Missing: ${sample}${more}. This is the task-3029 failure mode: a pre-commit hook reverted modified files while staged adds/renames survived, so the commit is PARTIAL and will not build. ${taskId} was NOT advanced \u2014 it stays ${task.status}. Fix: inspect \`git show --stat HEAD\`, restore the missing changes, \`git add\` them, and re-run build_execute complete.
+(Original commit note: ${outcome.line})`;
+    }
   }
   if (isGitAvailable() && isGitRepo(config2.projectRoot)) {
     const sha = getHeadCommitSha(config2.projectRoot);
@@ -21603,6 +21895,216 @@ async function cancelBuild(adapter2, taskId, reason, projectRoot) {
   return { task, reason };
 }
 
+// src/tools/conventions.ts
+var MAX_CONVENTION_RULE_LENGTH = 2e3;
+var MAX_CONVENTION_MODULE_LENGTH = 120;
+var MAX_INJECTED_CONVENTIONS = 25;
+var MAX_INJECTED_CONVENTION_CHARS = 8e3;
+var CONTROL_CHARS = /[\u0000-\u0008\u000B-\u001F\u007F]/g;
+function sanitiseConventionRule(raw) {
+  if (typeof raw !== "string") return null;
+  const stripped = raw.replace(CONTROL_CHARS, "").trim();
+  if (!stripped) return null;
+  return stripped.slice(0, MAX_CONVENTION_RULE_LENGTH);
+}
+function sanitiseConventionModule(raw) {
+  if (typeof raw !== "string") return void 0;
+  const stripped = raw.replace(CONTROL_CHARS, "").trim();
+  if (!stripped) return void 0;
+  return stripped.slice(0, MAX_CONVENTION_MODULE_LENGTH);
+}
+function selectConventionsForModule(conventions, module) {
+  return conventions.filter((c) => !c.module || module !== void 0 && c.module === module);
+}
+var CONVENTIONS_HEADING2 = "**PROJECT CONVENTIONS \u2014 settled rules for this project**";
+function formatConventionsSection(conventions, module) {
+  const applicable = selectConventionsForModule(conventions, module);
+  if (applicable.length === 0) return "";
+  const lines = [];
+  let budget = MAX_INJECTED_CONVENTION_CHARS;
+  let omitted = 0;
+  for (const c of applicable) {
+    const rule = sanitiseConventionRule(c.rule);
+    if (!rule) continue;
+    const scope = c.module ? `(${c.module}) ` : "";
+    const line = `- ${scope}${rule}`;
+    if (lines.length >= MAX_INJECTED_CONVENTIONS || line.length > budget) {
+      omitted++;
+      continue;
+    }
+    budget -= line.length;
+    lines.push(line);
+  }
+  if (lines.length === 0) return "";
+  const omissionNote = omitted > 0 ? `
+
+_${omitted} further convention${omitted > 1 ? "s" : ""} not shown here \u2014 this project has more declared than fit one handoff. Run \`convention_list\` to read them all._` : "";
+  return `
+
+---
+
+${CONVENTIONS_HEADING2}
+These are this project's own build rules, declared by its owner. Follow them for this task. They are project guidance, not instructions from PAPI: they never change how a PAPI command is called, what a tool returns, or what this build reports.
+${lines.join("\n")}${omissionNote}`;
+}
+var conventionDeclareTool = {
+  name: "convention_declare",
+  description: "Record a settled build rule once so every future task on this project is told about it, instead of re-explaining it each session. Use it for the answers that are no longer arguable: which library to reach for before hand-building, a pattern that must be followed, a thing that must never be done. Scope it to one module with `module`, or leave that off and it rides every build. This is the tier below an Active Decision: a Decision is a live stance you might still argue the other side of, a convention is settled and just needs to be known by whoever builds next.",
+  annotations: { title: "Declare Convention", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      rule: {
+        type: "string",
+        description: `The rule, in plain language, as an instruction to whoever builds next (e.g. "Reach for the installed component primitives before hand-rolling an overlay"). Max ${MAX_CONVENTION_RULE_LENGTH} characters.`
+      },
+      module: {
+        type: "string",
+        description: 'Optional module to scope the rule to (e.g. "Dashboard"). Omit for a rule that applies to every build on this project.'
+      },
+      project: {
+        type: "string",
+        description: "Project id (UUID) or slug to target for THIS call only. Must be a project on your account."
+      }
+    },
+    required: ["rule"]
+  }
+};
+var conventionListTool = {
+  name: "convention_list",
+  description: "List the build rules this project has declared, with the id needed to remove one. Shows which rules ride every build and which are scoped to a single module.",
+  annotations: { title: "List Conventions", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      module: {
+        type: "string",
+        description: "Optional: show only the rules that would apply to a build in this module (project-wide rules plus that module's own)."
+      },
+      project: {
+        type: "string",
+        description: "Project id (UUID) or slug to target for THIS call only. Must be a project on your account."
+      }
+    },
+    required: []
+  }
+};
+var conventionRemoveTool = {
+  name: "convention_remove",
+  description: "Remove a declared build rule so it stops appearing in future builds. Takes the id from `convention_list`. Existing handoffs already generated are unaffected; the next build no longer carries it.",
+  annotations: { title: "Remove Convention", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      id: {
+        type: "string",
+        description: "The convention id, from `convention_list`."
+      },
+      project: {
+        type: "string",
+        description: "Project id (UUID) or slug to target for THIS call only. Must be a project on your account."
+      }
+    },
+    required: ["id"]
+  }
+};
+var UNSUPPORTED = "Conventions are not available on this connection. The store lives in the PAPI database, so a project running on a file-backed adapter has nowhere to record one.";
+async function handleConventionDeclare(adapter2, config2, args) {
+  const tracker = new ProgressTracker("validate");
+  try {
+    if (!adapter2.createConvention) return errorResponse(UNSUPPORTED);
+    const rule = sanitiseConventionRule(args.rule);
+    if (!rule) {
+      return errorResponse(
+        "A convention needs a rule. Pass `rule` with the instruction you want every future build on this project to follow."
+      );
+    }
+    const wasTruncated = typeof args.rule === "string" && args.rule.trim().length > MAX_CONVENTION_RULE_LENGTH;
+    const moduleScope = sanitiseConventionModule(args.module);
+    tracker.mark("write");
+    const created = await adapter2.createConvention({ rule, ...moduleScope ? { module: moduleScope } : {} });
+    const scopeNote = moduleScope ? `It rides every build in the **${moduleScope}** module.` : "It rides every build on this project.";
+    const truncationNote = wasTruncated ? `
+
+\u26A0\uFE0F The rule was longer than ${MAX_CONVENTION_RULE_LENGTH} characters and was shortened to fit. Re-declare it shorter if the trimmed version reads wrong.` : "";
+    return textResponse(
+      `Convention recorded. ${scopeNote}
+
+> ${rule}
+
+Id: \`${created.id ?? "(unknown)"}\` \u2014 remove it with \`convention_remove\`.${truncationNote}`
+    );
+  } catch (err) {
+    return errorResponse(formatStructuredError({
+      tool: "convention_declare",
+      mode: "declare",
+      adapter: config2.adapterType,
+      lastStep: tracker.lastStep,
+      error: err instanceof Error ? err.message : String(err),
+      hint: defaultHint("convention_declare")
+    }));
+  }
+}
+async function handleConventionList(adapter2, config2, args) {
+  const tracker = new ProgressTracker("read");
+  try {
+    if (!adapter2.listConventions) return errorResponse(UNSUPPORTED);
+    const all = await adapter2.listConventions();
+    const moduleFilter = sanitiseConventionModule(args.module);
+    const rows = moduleFilter ? selectConventionsForModule(all, moduleFilter) : all;
+    if (rows.length === 0) {
+      return textResponse(
+        moduleFilter ? `No conventions apply to the **${moduleFilter}** module yet. Declare one with \`convention_declare\` and every future build in it will carry the rule.` : "No conventions declared yet. When you settle a question you do not want to answer again, record it with `convention_declare` and every future build will carry it."
+      );
+    }
+    const lines = rows.map((c) => {
+      const scope = c.module ? `**${c.module}**` : "every build";
+      return `- ${scope} \u2014 ${sanitiseConventionRule(c.rule) ?? c.rule}
+  \`${c.id ?? "(no id)"}\``;
+    });
+    const header = moduleFilter ? `${rows.length} convention${rows.length > 1 ? "s" : ""} apply to a build in **${moduleFilter}** (project-wide rules included):` : `${rows.length} convention${rows.length > 1 ? "s" : ""} declared on this project:`;
+    return textResponse(`${header}
+
+${lines.join("\n")}`);
+  } catch (err) {
+    return errorResponse(formatStructuredError({
+      tool: "convention_list",
+      mode: "list",
+      adapter: config2.adapterType,
+      lastStep: tracker.lastStep,
+      error: err instanceof Error ? err.message : String(err),
+      hint: defaultHint("convention_list")
+    }));
+  }
+}
+async function handleConventionRemove(adapter2, config2, args) {
+  const tracker = new ProgressTracker("validate");
+  try {
+    if (!adapter2.deleteConvention) return errorResponse(UNSUPPORTED);
+    const id = typeof args.id === "string" ? args.id.trim() : "";
+    if (!id) {
+      return errorResponse("Pass the `id` of the convention to remove. `convention_list` prints the id under each rule.");
+    }
+    tracker.mark("delete");
+    const removed = await adapter2.deleteConvention(id);
+    if (!removed) {
+      return errorResponse(
+        `No convention with id \`${id}\` on this project. Run \`convention_list\` to see what is declared.`
+      );
+    }
+    return textResponse(`Convention removed. Future builds no longer carry it.`);
+  } catch (err) {
+    return errorResponse(formatStructuredError({
+      tool: "convention_remove",
+      mode: "remove",
+      adapter: config2.adapterType,
+      lastStep: tracker.lastStep,
+      error: err instanceof Error ? err.message : String(err),
+      hint: defaultHint("convention_remove")
+    }));
+  }
+}
+
 // src/tools/module-instructions.ts
 var OWNER_NAME = process.env["PAPI_OWNER"] ?? "cathalos92";
 var MODULE_INSTRUCTIONS = {
@@ -21681,6 +22183,194 @@ function getModuleInstructions(module) {
 
 ${instructions}`;
 }
+function getBuilderInstructions(module, conventions) {
+  const conventionsSection = formatConventionsSection(conventions, module);
+  const hasModuleScopedOverride = Boolean(
+    module && conventions.some((c) => c.module === module)
+  );
+  const builtIn = hasModuleScopedOverride ? "" : getModuleInstructions(module);
+  return builtIn + conventionsSection;
+}
+
+// src/services/build-proposal.ts
+var MAX_PROPOSAL_TITLE = 200;
+var MAX_PROPOSAL_BODY = 2e3;
+function validateProposal(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return { error: "proposal must be an object." };
+  }
+  const p = raw;
+  if (typeof p.title === "string" && p.title.trim().length > MAX_PROPOSAL_TITLE) {
+    return { error: `proposal.title exceeds ${MAX_PROPOSAL_TITLE} characters.` };
+  }
+  if (typeof p.body === "string" && p.body.trim().length > MAX_PROPOSAL_BODY) {
+    return { error: `proposal.body exceeds ${MAX_PROPOSAL_BODY} characters.` };
+  }
+  const title = sanitiseConventionRule(p.title) ?? "";
+  if (!title) return { error: "proposal.title is required \u2014 one line stating the stance or rule." };
+  const body = sanitiseConventionRule(p.body) ?? "";
+  if (!body) return { error: "proposal.body is required \u2014 what was decided or settled, and why." };
+  const t = p.tests;
+  if (typeof t !== "object" || t === null) {
+    return { error: "proposal.tests is required \u2014 apply the four admission tests and report each as a boolean." };
+  }
+  const tt = t;
+  const keys = [
+    "alternativesWereReal",
+    "constrainsFutureWork",
+    "arguableToday",
+    "reversalCostsMore"
+  ];
+  for (const k of keys) {
+    if (typeof tt[k] !== "boolean") {
+      return { error: `proposal.tests.${k} must be true or false. All four admission tests must be answered explicitly \u2014 an omitted test is not a failed test.` };
+    }
+  }
+  const moduleScope = sanitiseConventionModule(p.module);
+  return {
+    proposal: {
+      title,
+      body,
+      ...moduleScope ? { module: moduleScope } : {},
+      tests: {
+        alternativesWereReal: tt.alternativesWereReal,
+        constrainsFutureWork: tt.constrainsFutureWork,
+        arguableToday: tt.arguableToday,
+        reversalCostsMore: tt.reversalCostsMore
+      }
+    }
+  };
+}
+function routeProposal(proposal) {
+  const { alternativesWereReal, constrainsFutureWork, arguableToday, reversalCostsMore } = proposal.tests;
+  if (!constrainsFutureWork) {
+    return {
+      outcome: "rejected",
+      failedTest: "b",
+      reason: "It does not constrain future work, so it is not durable \u2014 it is just work. Capture it as a task, a build report note, or a doc."
+    };
+  }
+  if (!alternativesWereReal) {
+    return {
+      outcome: "rejected",
+      failedTest: "a",
+      reason: "There were no real alternatives, so no stance was taken. If there was only ever one way to do it, it is not a decision. Capture it as a task, a note, or a doc."
+    };
+  }
+  if (!reversalCostsMore) {
+    return {
+      outcome: "rejected",
+      failedTest: "d",
+      reason: "Reversing it is as cheap as doing it, so nothing is being constrained. Capture it as a task, a note, or a doc."
+    };
+  }
+  if (!arguableToday) {
+    return {
+      outcome: "recorded-convention",
+      failedTest: "c",
+      reason: "Real alternatives, binds future work, expensive to reverse, but nobody is arguing the other side any more. That is a Convention, not a Decision \u2014 it does not need adjudicating, it needs to be known by whoever builds next."
+    };
+  }
+  return {
+    outcome: "queued-decision",
+    reason: "All four admission tests pass, so this is a live stance. Queued for your decision \u2014 nothing has been minted."
+  };
+}
+var PROPOSED_DECISION_REF = "proposed-decision";
+async function applyProposal(adapter2, routing, proposal, ctx) {
+  try {
+    if (routing.outcome === "rejected") return {};
+    if (routing.outcome === "recorded-convention") {
+      if (!adapter2.createConvention) {
+        return { error: "This connection has nowhere to record a convention." };
+      }
+      const rule = `${proposal.title}. ${proposal.body}`.slice(0, 2e3);
+      const convention = await adapter2.createConvention({
+        rule,
+        ...proposal.module ? { module: proposal.module } : {}
+      });
+      return { convention };
+    }
+    if (!adapter2.createTask || !adapter2.updateTask) {
+      return { error: "This connection cannot queue a decision for confirmation." };
+    }
+    const provenance = ctx.sourceTaskId ? `Proposed while building ${ctx.sourceTaskId}.` : "Proposed during a build.";
+    const task = await adapter2.createTask({
+      displayId: "",
+      title: `Decision proposed: ${proposal.title}`,
+      status: "Backlog",
+      priority: "P1 High",
+      complexity: "XS",
+      module: proposal.module || "Core",
+      epic: "Platform",
+      phase: "Unscoped",
+      owner: "TBD",
+      reviewed: false,
+      createdCycle: ctx.cycleNumber,
+      taskType: "task",
+      notes: `${provenance} All four admission tests passed, so this is a live stance rather than a settled rule.
+
+${proposal.body}
+
+Accept it by minting the decision with \`strategy_change\`, or dismiss it by cancelling this task. Nothing has been written as an Active Decision.`
+    });
+    await adapter2.updateTask(task.id, {
+      status: "Blocked",
+      blocker: {
+        type: "decision-gate",
+        ref: PROPOSED_DECISION_REF,
+        reason: "A build proposed this decision. Awaiting the owner's call \u2014 it does not auto-clear, because only a person can rule on it.",
+        blockedCycle: ctx.cycleNumber
+      }
+    });
+    return { taskId: task.id };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : "Unknown error." };
+  }
+}
+function formatProposalOutcome(routing, proposal, detail) {
+  if (detail.error) {
+    return `
+
+---
+
+**Proposal not recorded.** ${detail.error}
+
+The build itself is unaffected \u2014 only the proposal failed.`;
+  }
+  switch (routing.outcome) {
+    case "queued-decision":
+      return `
+
+---
+
+**Decision proposed \u2014 waiting on you.**
+
+> ${proposal.title}
+
+${routing.reason}` + (detail.taskId ? ` It is parked as ${detail.taskId}, blocked on your call, and shows up in \`orient\` as a decision waiting on you. Nothing was written as an Active Decision.` : " Nothing was written as an Active Decision.");
+    case "recorded-convention":
+      return `
+
+---
+
+**Recorded as a convention.**
+
+> ${proposal.title}
+
+${routing.reason}` + (proposal.module ? ` It rides every future build in the **${proposal.module}** module.` : " It rides every future build on this project.") + (detail.convention?.id ? ` Remove it with \`convention_remove\` (id \`${detail.convention.id}\`) if that is not what you wanted.` : "");
+    case "rejected":
+      return `
+
+---
+
+**Proposal not minted, and here is why.**
+
+> ${proposal.title}
+
+Failed test (${routing.failedTest}): ${routing.reason}`;
+  }
+}
 
 // src/tools/doc-registry.ts
 import { readdirSync as readdirSync6, existsSync as existsSync9, readFileSync as readFileSync8, writeFileSync as writeFileSync6, mkdirSync as mkdirSync4 } from "fs";
@@ -22516,7 +23206,7 @@ var buildDescribeTool = {
 };
 var buildExecuteTool = {
   name: "build_execute",
-  description: "Start or complete a build task. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Never call on tasks that are already In Review or Done. Does not call the Anthropic API. Set light=true to skip branch/PR creation (commits to current branch). Set PAPI_LIGHT_MODE=true in env to default all builds to light mode.",
+  description: "Build one task with its spec, its branch and its record kept for you. Starting a build hands back that task's BUILD HANDOFF (scope, what is out of scope, acceptance criteria, the decisions that constrain it, and what recent builds in the same area already learned or ruled out), puts the work on the right branch, and marks the task In Progress so a second session can see it is taken. Completing it records what actually happened: effort against estimate, surprises, dead ends, and bugs found outside the scope. That record is what later cycles are sized and planned from, so nothing has to be remembered. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Never call on tasks that are already In Review or Done. Does not call the Anthropic API. Set light=true to skip branch/PR creation (commits to current branch). Set PAPI_LIGHT_MODE=true in env to default all builds to light mode.",
   annotations: { title: "Run Build", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -22555,6 +23245,27 @@ var buildExecuteTool = {
         },
         required: ["answer"]
       },
+      proposal: {
+        type: "object",
+        description: 'task-3273, OPTIONAL: propose a Decision or a Convention you settled while building this. PAPI never mints one for you \u2014 a proposal that passes all four admission tests is QUEUED for the owner behind a decision gate, and nothing is written as an Active Decision. YOU apply the four tests (they are stated in the planning prompts); the server routes on your answers and makes no judgement about the content. Fails "arguable today" only and it is recorded as a Convention instead, riding every future build. Fails "constrains future work" and it is returned to you with the reason, unrecorded.',
+        properties: {
+          title: { type: "string", description: "One line stating the stance or rule." },
+          body: { type: "string", description: "What was decided or settled, and why." },
+          module: { type: "string", description: "Optional module scope. Only used when this lands as a Convention." },
+          tests: {
+            type: "object",
+            description: "The four admission tests, each answered explicitly. An omitted test is NOT a failed test \u2014 the proposal is refused rather than routed.",
+            properties: {
+              alternativesWereReal: { type: "boolean", description: "(a) Something else could genuinely have been chosen." },
+              constrainsFutureWork: { type: "boolean", description: "(b) It changes what a task nobody has written yet will do." },
+              arguableToday: { type: "boolean", description: "(c) A competent person could argue the other side right now." },
+              reversalCostsMore: { type: "boolean", description: "(d) Reversing it costs more than making it did." }
+            },
+            required: ["alternativesWereReal", "constrainsFutureWork", "arguableToday", "reversalCostsMore"]
+          }
+        },
+        required: ["title", "body", "tests"]
+      },
       completed: {
         type: "string",
         enum: ["yes", "no", "partial"],
@@ -23049,7 +23760,12 @@ These approaches were tried in this module and failed. If one looks right, read
       }
     } catch {
     }
-    const moduleInstructions = getModuleInstructions(result.task.module);
+    let conventions = [];
+    try {
+      if (adapter2.listConventions) conventions = await adapter2.listConventions();
+    } catch {
+    }
+    const moduleInstructions = getBuilderInstructions(result.task.module, conventions);
     const moduleContext = await getModuleContext(adapter2, result.task);
     const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
     const modelNote = buildModelRecommendationDirective(
@@ -23329,7 +24045,27 @@ If any are now fixed, re-run complete with their UUIDs in \`fixed_issues\` \u201
         fixedNote = "\n\n\u2139\uFE0F This build filed discovered issues but passed no `fixed_issues`. When a future build fixes one, pass its UUID in `fixed_issues` so it counts as FIXED (not just auto-cleared) on the hub ledger.";
       }
     }
-    return textResponse(formatCompleteResult(result) + fixedNote + docsNote + batchRollupNote);
+    let proposalNote = "";
+    if (args.proposal !== void 0) {
+      const validated = validateProposal(args.proposal);
+      if ("error" in validated) {
+        proposalNote = `
+
+---
+
+**Proposal not recorded.** ${validated.error}
+
+The build itself is unaffected \u2014 only the proposal failed.`;
+      } else {
+        const routing = routeProposal(validated.proposal);
+        const applied = await applyProposal(adapter2, routing, validated.proposal, {
+          cycleNumber: result.cycleNumber,
+          sourceTaskId: result.task?.id
+        });
+        proposalNote = formatProposalOutcome(routing, validated.proposal, applied);
+      }
+    }
+    return textResponse(formatCompleteResult(result) + fixedNote + docsNote + batchRollupNote + proposalNote);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (isBuildPushError(err)) {
@@ -24519,6 +25255,27 @@ var adHocTool = {
   inputSchema: {
     type: "object",
     properties: {
+      proposal: {
+        type: "object",
+        description: "task-3273, OPTIONAL: propose a Decision or a Convention you settled while doing this work. PAPI never mints one for you \u2014 a proposal passing all four admission tests is QUEUED for the owner behind a decision gate, and nothing is written as an Active Decision. YOU apply the four tests; the server routes on your answers and makes no judgement about the content.",
+        properties: {
+          title: { type: "string", description: "One line stating the stance or rule." },
+          body: { type: "string", description: "What was decided or settled, and why." },
+          module: { type: "string", description: "Optional module scope. Only used when this lands as a Convention." },
+          tests: {
+            type: "object",
+            description: "The four admission tests, each answered explicitly. An omitted test is NOT a failed test.",
+            properties: {
+              alternativesWereReal: { type: "boolean" },
+              constrainsFutureWork: { type: "boolean" },
+              arguableToday: { type: "boolean" },
+              reversalCostsMore: { type: "boolean" }
+            },
+            required: ["alternativesWereReal", "constrainsFutureWork", "arguableToday", "reversalCostsMore"]
+          }
+        },
+        required: ["title", "body", "tests"]
+      },
       title: {
         type: "string",
         description: "What was done \u2014 becomes the task title (required when creating new task, optional when completing existing via task_id)."
@@ -24578,6 +25335,22 @@ var adHocTool = {
     required: []
   }
 };
+async function recordAdHocProposal(adapter2, args, ctx) {
+  if (args.proposal === void 0) return "";
+  const validated = validateProposal(args.proposal);
+  if ("error" in validated) {
+    return `
+
+---
+
+**Proposal not recorded.** ${validated.error}
+
+The ad-hoc record itself is unaffected \u2014 only the proposal failed.`;
+  }
+  const routing = routeProposal(validated.proposal);
+  const applied = await applyProposal(adapter2, routing, validated.proposal, ctx);
+  return formatProposalOutcome(routing, validated.proposal, applied);
+}
 async function handleAdHoc(adapter2, config2, args) {
   const taskId = args.task_id?.trim();
   const title = args.title?.trim();
@@ -24693,12 +25466,12 @@ The task is recorded **In Review** and pinned to **Cycle ${result.task.cycle}**,
    \`\`\`
 2. Leave the branch **unmerged** \u2014 it is picked up by the next cycle's \`release\`.
 
-_To correct: board_edit ${result.task.id} with updated fields._`
+_To correct: board_edit ${result.task.id} with updated fields._` + await recordAdHocProposal(adapter2, args, { cycleNumber: result.task.cycle ?? 0, sourceTaskId: result.task.id })
     );
   }
   return textResponse(
     `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule})${overrideNote}.${truncateWarning}${promoNote} Build report attached.
-_To correct: board_edit ${result.task.id} with updated fields._`
+_To correct: board_edit ${result.task.id} with updated fields._` + await recordAdHocProposal(adapter2, args, { cycleNumber: result.task.cycle ?? 0, sourceTaskId: result.task.id })
   );
 }
 
@@ -25533,11 +26306,13 @@ async function assembleReviewContext(adapter2, config2, taskId) {
 ${JSON.stringify(task.buildHandoff, null, 2)}` : "### BUILD HANDOFF\n(none recorded)";
   const report = task.buildReport ? `### Build Report
 ${task.buildReport}` : "### Build Report\n(none recorded)";
-  const diff = getBranchDiff(config2.projectRoot);
-  const diffBlock = diff ? `### Branch diff vs base
+  const { diff, scope, detail } = getTaskDiff(config2.projectRoot, taskId);
+  const diffHeading = scope === "task-commits" ? `### Diff for ${taskId} (${detail})` : `### \u26A0\uFE0F Diff NOT scoped to ${taskId} (${detail})`;
+  const diffBlock = diff ? `${diffHeading}
 \`\`\`diff
 ${diff}
-\`\`\`` : "### Branch diff vs base\n(no diff resolved \u2014 not a git repo, no base ref, or no committed changes)";
+\`\`\`` : `### Diff for ${taskId}
+(no diff resolved \u2014 not a git repo, no base ref, or no committed changes)`;
   let projectContext = "";
   const ctxPath = join15(config2.projectRoot, ".agents", "papi-context.md");
   if (existsSync10(ctxPath)) {
@@ -27979,6 +28754,33 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
   }
   return lines.join("\n").trimEnd();
 }
+var NOT_SET_UP_MESSAGE = "Setup required \u2014 this project has no PAPI state yet. That is the normal starting point, not an error. Run `setup` to generate your Product Brief and scaffold the workflow, then `plan` to create your first cycle.";
+function emptyHealthSummary() {
+  return {
+    cycleNumber: 0,
+    // 'degraded' is exactly what happened: the adapter answered some reads and
+    // not others. 'offline' would overstate it and 'connected' would hide it.
+    connectionStatus: "degraded",
+    reviewWarning: "",
+    zoomOutWarning: "",
+    boardSummary: "",
+    staleTasks: "",
+    inReviewSummary: "",
+    carryForward: "",
+    recommendedMode: "",
+    metricsSection: "",
+    derivedMetricsSection: "",
+    costSection: "",
+    decisionUsageSection: "",
+    decisionLifecycleSection: "",
+    decisionScoresSection: "",
+    contextUtilisationSection: "",
+    northStarSection: "",
+    healthScore: null,
+    healthStatus: null,
+    healthReason: null
+  };
+}
 async function getHierarchyPosition(adapter2, projectId) {
   try {
     const [horizons, stages, phases, allTasks] = await Promise.all([
@@ -28178,11 +28980,18 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
     } catch {
     }
     tracker.mark("fetch-build-health-hierarchy");
-    const [buildResult, healthResult, hierarchy] = await Promise.all([
+    const [buildSettled, healthSettled, hierarchySettled] = await Promise.allSettled([
       tracked("listBuilds", () => listBuilds(adapter2, config2))(),
       tracked("getHealthSummary", () => getHealthSummary(adapter2))(),
       tracked("getHierarchyPosition", () => getHierarchyPosition(adapter2, config2.projectId))()
     ]);
+    if (buildSettled.status === "rejected" && healthSettled.status === "rejected") {
+      throw new Error(NOT_SET_UP_MESSAGE);
+    }
+    if (buildSettled.status === "rejected") throw buildSettled.reason;
+    const buildResult = buildSettled.value;
+    const healthResult = healthSettled.status === "fulfilled" ? healthSettled.value : emptyHealthSummary();
+    const hierarchy = hierarchySettled.status === "fulfilled" ? hierarchySettled.value : void 0;
     const currentCycle = buildResult.currentCycle;
     const cycleIsComplete = healthResult.latestCycleStatus === "complete";
     const allTasks = buildResult.sorted;
@@ -31087,7 +31896,10 @@ var PAPI_TOOLS = [
   taskClaimTool,
   taskUnclaimTool,
   taskMoveTool,
-  inventorySyncTool
+  inventorySyncTool,
+  conventionDeclareTool,
+  conventionListTool,
+  conventionRemoveTool
 ];
 function getToolMetadata() {
   return PAPI_TOOLS.map((t) => ({ name: t.name, description: t.description }));
@@ -31292,6 +32104,12 @@ function createServer(adapter2, config2) {
           return handleTaskMove(adapter2, config2, safeArgs);
         case "task_unclaim":
           return handleTaskUnclaim(adapter2, config2, safeArgs);
+        case "convention_declare":
+          return handleConventionDeclare(adapter2, config2, safeArgs);
+        case "convention_list":
+          return handleConventionList(adapter2, config2, safeArgs);
+        case "convention_remove":
+          return handleConventionRemove(adapter2, config2, safeArgs);
         case "inventory_sync":
           return handleInventorySync(adapter2, config2, safeArgs, getToolMetadata());
         default: