@papi-ai/server 0.7.69 → 0.7.70

package/dist/index.js

@@ -10729,6 +10729,14 @@ function validateHandoffScope(handoff) {
   if (!isMeaningful(handoff.scopeBoundary)) invalid.push("scopeBoundary");
   return invalid;
 }
+function assertHandoffApplyPayloadNonEmpty(data, cycleNumber) {
+  const handoffCount = data.cycleHandoffs?.length ?? 0;
+  if (handoffCount === 0) {
+    throw new Error(
+      `Handoff apply rejected: trimmed/empty apply payload \u2014 nothing persisted. The parsed output for Cycle ${cycleNumber} carries NO handoffs (cycleHandoffs is empty), but handoff prepare only runs when at least one task needs a handoff \u2014 so the handoffs were dropped. The most likely cause is a truncated apply JSON: the output overflowed the client tool-result ceiling (see task-2905/2906). Re-run handoff_generate and resend the COMPLETE structured output \u2014 ensure the JSON after the <!-- PAPI_STRUCTURED_OUTPUT --> marker includes the full cycleHandoffs array.`
+    );
+  }
+}
 async function prepareHandoffs(adapter2, _config, taskIds, force = false) {
   const timer2 = startTimer();
   const cycles = await adapter2.readCycles();
@@ -10785,10 +10793,8 @@ async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber, force = false)
   if (!data) {
     throw new Error("Could not parse structured output. Ensure your output includes <!-- PAPI_STRUCTURED_OUTPUT --> with valid JSON.");
   }
+  assertHandoffApplyPayloadNonEmpty(data, cycleNumber);
   const handoffs = data.cycleHandoffs ?? [];
-  if (handoffs.length === 0) {
-    throw new Error("No cycleHandoffs found in structured output. Ensure your output includes handoffs in the cycleHandoffs array.");
-  }
   const taskIdsToWrite = handoffs.map((h) => h.taskId);
   const existingHandoffSet = /* @__PURE__ */ new Set();
   try {
@@ -13662,6 +13668,58 @@ async function buildSessionGuidance(callerKey) {
   return signals.slice(0, 3);
 }
 
+// src/services/onboarding-coaching.ts
+var ONBOARDING_EARLY_CYCLE_MAX = 2;
+var MAX_COACHING_LINES = 4;
+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.";
+var COACH_OFF_CYCLE = 'When a request falls outside the current cycle, keep it in the loop: `idea "<what you want>"` parks it in the backlog, or promote it into the cycle and generate a build handoff before you build.';
+var COACH_SESSION_START = 'Start of a session: skim your Active Decisions (the AD summary from `orient`, or `strategy_review`) to reload your project direction, and capture anything new with `idea "<what you want>"`.';
+var COACH_NO_DECISIONS = 'No Active Decisions recorded yet. Capture your first with `idea "<a direction or constraint>"` so your project starts steering itself.';
+var COACH_BACKLOG_IMPORT = "Already tracking a backlog elsewhere (Linear, a CSV, a markdown checklist)? Bring it over in one pass with `backlog_import` instead of retyping it.";
+var ONBOARDING_COACHING_HEADING = "## Getting Started";
+function buildOnboardingCoaching(state) {
+  const lines = [];
+  const isEarly = state.cycleNumber <= ONBOARDING_EARLY_CYCLE_MAX;
+  const { surface } = state;
+  if (state.repoConnected === false && (surface === "orient" || surface === "plan")) {
+    lines.push(COACH_CONNECT_REPO);
+  }
+  if (state.hasLocalWorkspace && (surface === "setup" || surface === "orient" && isEarly)) {
+    lines.push(COACH_ROOT_DIR);
+  }
+  if ((surface === "orient" || surface === "setup") && isEarly) {
+    lines.push(COACH_CLICKABLE_TASKS);
+  }
+  if ((surface === "orient" || surface === "plan") && state.hasActiveCycle && isEarly) {
+    lines.push(COACH_OFF_CYCLE);
+  }
+  if (surface === "orient" && isEarly) {
+    lines.push(state.hasActiveDecisions === false ? COACH_NO_DECISIONS : COACH_SESSION_START);
+  }
+  if (surface === "plan" && state.bootstrapPlan === true) {
+    lines.push(COACH_BACKLOG_IMPORT);
+  }
+  return lines.slice(0, MAX_COACHING_LINES);
+}
+function formatOnboardingCoachingBlock(state) {
+  const lines = buildOnboardingCoaching(state);
+  if (lines.length === 0) return "";
+  return `
+
+${ONBOARDING_COACHING_HEADING}
+${lines.map((l) => `- ${l}`).join("\n")}`;
+}
+
+// src/lib/hosted-mode.ts
+function isHostedTransport() {
+  return Boolean(process.env.PORT || process.env.PAPI_HTTP_PORT);
+}
+function hasLocalWorkspace() {
+  return !isHostedTransport();
+}
+
 // src/lib/per-caller-cache.ts
 var DEFAULT_CALLER_KEY2 = "__default__";
 var MAX_PER_CALLER_ENTRIES = 1e3;
@@ -13905,6 +13963,10 @@ function formatPlanResult(result) {
   } else {
     lines.push("", `Next: run \`build_list\` to see your cycle tasks, then \`build_execute <task_id>\` to start building.`);
   }
+  if (result.onboardingCoaching && result.onboardingCoaching.length > 0) {
+    lines.push("", ONBOARDING_COACHING_HEADING);
+    for (const c of result.onboardingCoaching) lines.push(`- ${c}`);
+  }
   if (result.contextBytes !== void 0) {
     const kb = (result.contextBytes / 1024).toFixed(1);
     lines.push(`---`, `Context: ${kb}KB`);
@@ -13986,7 +14048,15 @@ async function handlePlan(adapter2, config2, args) {
       }, tracker);
       const planProjectInfo = adapter2.getProjectInfo ? await adapter2.getProjectInfo().catch(() => null) : null;
       const projectBanner = planProjectInfo ? getProjectConnectionBanner(planProjectInfo.name, planProjectInfo.slug) ?? void 0 : void 0;
-      const response = formatPlanResult({ ...result, contextUtilisation: utilisation, contextBytes, skipHandoffs, projectBanner });
+      const onboardingCoaching = buildOnboardingCoaching({
+        surface: "plan",
+        repoConnected: planProjectInfo ? !!planProjectInfo.repo_url : void 0,
+        hasLocalWorkspace: hasLocalWorkspace(),
+        cycleNumber: result.cycleNumber + 1,
+        hasActiveCycle: true,
+        bootstrapPlan: result.mode === "bootstrap"
+      });
+      const response = formatPlanResult({ ...result, contextUtilisation: utilisation, contextBytes, skipHandoffs, projectBanner, onboardingCoaching });
       return {
         ...response,
         ...contextBytes !== void 0 ? { _contextBytes: contextBytes } : {},
@@ -14138,14 +14208,6 @@ import { existsSync as existsSync2, readdirSync, statSync as statSync2 } from "f
 import { join as join4 } from "path";
 import { homedir as homedir2 } from "os";
 
-// src/lib/hosted-mode.ts
-function isHostedTransport() {
-  return Boolean(process.env.PORT || process.env.PAPI_HTTP_PORT);
-}
-function hasLocalWorkspace() {
-  return !isHostedTransport();
-}
-
 // src/services/idea.ts
 import { randomUUID as randomUUID9 } from "crypto";
 var OWNER_ACTION_PATTERNS = [
@@ -15602,6 +15664,13 @@ ${cleanContent}`;
     } catch {
     }
   }
+  if (data.hierarchyUpdates && data.hierarchyUpdates.length > 0) {
+    try {
+      await applyHierarchyUpdates(adapter2, data.hierarchyUpdates);
+    } catch (err) {
+      console.error("[strategy] applyHierarchyUpdates failed:", err instanceof Error ? err.message : String(err));
+    }
+  }
   const compressionThreshold = cycleNumber - 5;
   if (compressionThreshold > 0 && data.sessionLogCompressionSummary) {
     await adapter2.compressCycleLog(compressionThreshold, data.sessionLogCompressionSummary);
@@ -15879,6 +15948,79 @@ function buildPhaseLabel(phase) {
   if (!numMatch) return phase.label;
   return `Phase ${numMatch[1]}: ${phase.label}`;
 }
+function nextHierarchySort(existing) {
+  return existing.length === 0 ? 10 : Math.max(...existing.map((e) => e.sortOrder)) + 10;
+}
+async function applyHierarchyUpdates(adapter2, updates) {
+  if (!adapter2.readStages || !adapter2.readHorizons) return;
+  const findHorizon = async (ref) => (await adapter2.readHorizons()).find(
+    (h) => h.slug === ref || h.id === ref || h.label.toLowerCase() === ref.toLowerCase()
+  );
+  const findStage = async (ref) => (await adapter2.readStages()).find(
+    (s) => s.slug === ref || s.id === ref || s.label.toLowerCase() === ref.toLowerCase()
+  );
+  for (const u of updates) {
+    if (u.level === "horizon") {
+      if (u.action === "create") {
+        if (!await findHorizon(u.slug) && adapter2.createHorizon) {
+          const horizons = await adapter2.readHorizons();
+          await adapter2.createHorizon({
+            slug: u.slug,
+            label: u.label ?? u.slug,
+            status: u.status ?? "In Progress",
+            sortOrder: u.sortOrder ?? nextHierarchySort(horizons)
+          });
+        }
+      } else if (u.action === "update_status" && u.status && adapter2.updateHorizonStatus) {
+        const h = await findHorizon(u.slug);
+        if (h) await adapter2.updateHorizonStatus(h.id, u.status);
+      }
+      continue;
+    }
+    if (u.action === "update_criterion" && u.criterionId && typeof u.met === "boolean" && adapter2.setCriterionMet) {
+      const s = await findStage(u.slug);
+      if (s) await adapter2.setCriterionMet(s.id, u.criterionId, u.met, u.evidence ?? null);
+    } else if (u.action === "update_status" && u.status && adapter2.updateStageStatus) {
+      const s = await findStage(u.slug);
+      if (s) await adapter2.updateStageStatus(s.id, u.status);
+    } else if (u.action === "create") {
+      await createStageFromUpdate(adapter2, u, findStage, findHorizon);
+    } else if (u.action === "advance" && adapter2.updateStageStatus) {
+      const current = await findStage(u.slug);
+      if (current) await adapter2.updateStageStatus(current.id, "Done");
+      const newRef = u.newStageSlug ?? u.slug;
+      const existingNext = await findStage(newRef);
+      if (existingNext) {
+        await adapter2.updateStageStatus(existingNext.id, "In Progress");
+      } else if (u.newStageLabel) {
+        await createStageFromUpdate(
+          adapter2,
+          { ...u, slug: newRef, label: u.newStageLabel, status: "In Progress", horizon: u.horizon ?? current?.horizonId },
+          findStage,
+          findHorizon
+        );
+      }
+    }
+  }
+}
+async function createStageFromUpdate(adapter2, u, findStage, findHorizon) {
+  if (!adapter2.createStage || !adapter2.readStages || !adapter2.readHorizons) return;
+  if (await findStage(u.slug)) return;
+  const horizons = await adapter2.readHorizons();
+  const parent = u.horizon ? await findHorizon(u.horizon) : horizons.length === 1 ? horizons[0] : horizons.find((h) => h.status === "In Progress");
+  if (!parent) return;
+  const stagesInHorizon = (await adapter2.readStages()).filter((s) => s.horizonId === parent.id);
+  const id = await adapter2.createStage({
+    slug: u.slug,
+    label: u.label ?? u.slug,
+    status: u.status ?? "Not Started",
+    sortOrder: u.sortOrder ?? nextHierarchySort(stagesInHorizon),
+    horizonId: parent.id
+  });
+  if (id && u.exitCriteria?.length && adapter2.updateStageExitCriteria) {
+    await adapter2.updateStageExitCriteria(id, u.exitCriteria);
+  }
+}
 async function applyPhaseUpdates(adapter2, currentPhases, updates) {
   const phasesById = new Map(currentPhases.map((p) => [p.id, p]));
   const labelMigrations = [];
@@ -19111,8 +19253,14 @@ ${result.warnings.map((w) => `- ${w}`).join("\n")}` : "";
 **Important:** This is a remote PAPI connection, so the server could not write to your project directory. Setup prepared your files (${harnessFiles}, .claude/settings.json, docs/) and returned them in the scaffolding section below \u2014 **write each one to disk, then commit** before running \`build_execute\` (it requires a clean working directory).` : `
 
 **Important:** Setup created/modified files (${harnessFiles}, .claude/settings.json, docs/). Commit these changes before running \`build_execute\` \u2014 it requires a clean working directory.`;
+  const coachingNote = formatOnboardingCoachingBlock({
+    surface: "setup",
+    hasLocalWorkspace: hasLocalWorkspace(),
+    cycleNumber: 0,
+    hasActiveCycle: false
+  });
   return textResponse(
-    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${northStarNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}${filesNote}
+    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${northStarNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}${filesNote}${coachingNote}
 
 Tip: See \`docs/templates/example-project-brief.md\` for an example of a well-written brief.
 
@@ -19483,8 +19631,8 @@ function buildPapiMetaFramingDirective(caps, inner) {
 
 // src/services/build.ts
 import { randomUUID as randomUUID11 } from "crypto";
-import { readdirSync as readdirSync5, existsSync as existsSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync3, unlinkSync as unlinkSync2, mkdirSync as mkdirSync2 } from "fs";
-import { join as join11 } from "path";
+import { readdirSync as readdirSync5, existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync4, unlinkSync as unlinkSync3, mkdirSync as mkdirSync3 } from "fs";
+import { join as join12 } from "path";
 
 // src/lib/db-only-notices.ts
 var DB_ONLY_START_NOTICE = "No git repo detected \u2014 running this cycle in your project database only. Your work stays in the working tree; run `git init` (and add a remote) to enable branches, commits and PR review.";
@@ -20402,6 +20550,38 @@ async function postReleaseToX(version, cycleClosed) {
     return false;
   }
 }
+function buildHostedReleaseOutput(params) {
+  const { version, branch, cyclePart, warningsBlock, skipVersion } = params;
+  const tagAnnotation = `Release ${version}`;
+  const titleSuffix = skipVersion ? " (skip version)" : "";
+  const gitHalf = skipVersion ? "the git half of the release (the CHANGELOG.md commit and the branch push) must run on your own machine" : "the git half of the release (tag, push, CHANGELOG.md) must run on your own machine";
+  const commands = skipVersion ? `git checkout ${branch}
+git pull
+git push origin ${branch}
+` : `git checkout ${branch}
+git pull
+git tag -a ${version} -m "${tagAnnotation}"
+git push origin ${branch}
+git push origin ${version}
+`;
+  const identityBlock = skipVersion ? "" : `If git reports "Author identity unknown" or "Committer identity unknown" (no global git identity configured), pass your identity inline instead of writing global config:
+\`\`\`
+git -c user.name="Your Name" -c user.email="you@example.com" tag -a ${version} -m "${tagAnnotation}"
+\`\`\`
+
+`;
+  return `## Release ${version}${titleSuffix} \u2014 cycle closed in the DB
+
+${cyclePart} is now marked **complete** in PAPI's database, so \`orient\` will no longer flag "Release has not been run."
+` + warningsBlock + `
+The hosted remote MCP transport (mcp.getpapi.ai) has no checkout of your project and no git binary, so ${gitHalf}.
+
+Finish the release locally:
+\`\`\`
+` + commands + `\`\`\`
+
+` + identityBlock + `Next: cycle closed! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`;
+}
 var releaseTool = {
   name: "release",
   description: "Cut a versioned release \u2014 creates a git tag, generates CHANGELOG.md, and pushes to remote. Pass skipVersion=true to update CHANGELOG and close the cycle without creating a tag or bumping version numbers.",
@@ -20579,33 +20759,12 @@ Next: run \`plan\` to start your next cycle.`
         branchMerges: [],
         changelogEmitted: false
       });
-      const tagAnnotation = `Release ${version}`;
       const cyclePart = closed.resolvedCycleNum > 0 ? `Cycle ${closed.resolvedCycleNum}` : "The cycle";
       const warningsBlock = closed.warnings.length > 0 ? `
 \u26A0\uFE0F Warnings: ${closed.warnings.join("; ")}
 ` : "";
       return textResponse(
-        `## Release ${version} \u2014 cycle closed in the DB
-
-${cyclePart} is now marked **complete** in PAPI's database, so \`orient\` will no longer flag "Release has not been run."
-` + warningsBlock + `
-The hosted remote MCP transport (mcp.getpapi.ai) has no checkout of your project and no git binary, so the git half of the release (tag, push, CHANGELOG.md) must run on your own machine.
-
-Finish the release locally:
-\`\`\`
-git checkout ${branch}
-git pull
-git tag -a ${version} -m "${tagAnnotation}"
-git push origin ${branch}
-git push origin ${version}
-\`\`\`
-
-If git reports "Author identity unknown" or "Committer identity unknown" (no global git identity configured), pass your identity inline instead of writing global config:
-\`\`\`
-git -c user.name="Your Name" -c user.email="you@example.com" tag -a ${version} -m "${tagAnnotation}"
-\`\`\`
-
-Next: cycle closed! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`
+        buildHostedReleaseOutput({ version, branch, cyclePart, warningsBlock, skipVersion: skipVersion ?? false })
       );
     }
     tracker.mark("remote-project-guard");
@@ -20862,6 +21021,95 @@ function detectWorktreeCollision(input) {
 // src/services/build.ts
 init_git();
 
+// src/lib/build-checkpoint.ts
+import { createHash as createHash4 } from "crypto";
+import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync6, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
+import { join as join11 } from "path";
+var BUILD_CHECKPOINT_VERSION = 1;
+function cwdHash(cwd) {
+  return createHash4("sha256").update(realpathOrSelf(cwd)).digest("hex").slice(0, 12);
+}
+function safeTaskId(taskId) {
+  return taskId.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function checkpointDir(cwd) {
+  return join11(cwd, ".papi", "state");
+}
+function checkpointPath(cwd, taskId) {
+  return join11(checkpointDir(cwd), `build-${safeTaskId(taskId)}.${cwdHash(cwd)}.json`);
+}
+function writeBuildCheckpoint(input) {
+  try {
+    const dir = checkpointDir(input.cwd);
+    if (!existsSync7(dir)) {
+      mkdirSync2(dir, { recursive: true });
+    }
+    const checkpoint = {
+      version: BUILD_CHECKPOINT_VERSION,
+      taskId: input.taskId,
+      branch: input.branch,
+      step: input.step,
+      lastCommitSha: input.lastCommitSha,
+      modifiedFiles: input.modifiedFiles,
+      cwd: realpathOrSelf(input.cwd),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    writeFileSync3(checkpointPath(input.cwd, input.taskId), JSON.stringify(checkpoint, null, 2) + "\n", "utf-8");
+  } catch {
+  }
+}
+function readBuildCheckpoint(key) {
+  try {
+    const path7 = checkpointPath(key.cwd, key.taskId);
+    if (!existsSync7(path7)) return null;
+    const parsed = JSON.parse(readFileSync6(path7, "utf-8"));
+    if (!parsed || parsed.version !== BUILD_CHECKPOINT_VERSION || parsed.taskId !== key.taskId) {
+      return null;
+    }
+    return {
+      version: BUILD_CHECKPOINT_VERSION,
+      taskId: parsed.taskId,
+      branch: parsed.branch ?? null,
+      step: "branch_ready",
+      lastCommitSha: parsed.lastCommitSha ?? null,
+      modifiedFiles: Array.isArray(parsed.modifiedFiles) ? parsed.modifiedFiles : [],
+      cwd: typeof parsed.cwd === "string" ? parsed.cwd : realpathOrSelf(key.cwd),
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : ""
+    };
+  } catch {
+    return null;
+  }
+}
+function clearBuildCheckpoint(key) {
+  try {
+    const path7 = checkpointPath(key.cwd, key.taskId);
+    if (existsSync7(path7)) {
+      unlinkSync2(path7);
+    }
+  } catch {
+  }
+}
+function formatResumeNote(cp) {
+  const files = cp.modifiedFiles.filter((f) => f && f.trim());
+  const fileList = files.length > 0 ? files.slice(0, 12).map((f) => `  - ${f}`).join("\n") + (files.length > 12 ? `
+  - \u2026+${files.length - 12} more` : "") : "  _(none recorded)_";
+  const lines = [
+    "> **\u21BB Resuming from checkpoint** \u2014 this task is already In Progress; you are NOT starting clean.",
+    `> - Branch: \`${cp.branch ?? "unknown"}\``,
+    "> - Last step: branch ready",
+    `> - Last commit: ${cp.lastCommitSha ? cp.lastCommitSha.slice(0, 8) : "none"}`,
+    `> - Checkpoint saved: ${cp.updatedAt || "unknown"}`,
+    ">",
+    "> Modified files at last checkpoint:",
+    ...fileList.split("\n").map((l) => `> ${l}`),
+    ">",
+    "> Review the existing branch and changes above before writing new code \u2014 do not re-do work already committed.",
+    "",
+    ""
+  ];
+  return lines.join("\n");
+}
+
 // src/lib/diff-inspector.ts
 import { execFileSync as execFileSync5 } from "child_process";
 var TRIGGER_SURFACE_GLOBS = [
@@ -21097,51 +21345,22 @@ function autoCommit(config2, taskId, taskTitle, predictedFiles) {
   if (staged.length > 0) {
     return safeRun(() => commitStagedOnly(cwd, message)) + ` (selective staging respected: ${staged.length} file(s)).`;
   }
+  const modified = getModifiedFiles(cwd);
+  if (modified.length === 0) {
+    return "Auto-commit: skipped (no working-tree changes).";
+  }
+  const commitResult = safeRun(() => stageAllAndCommit(cwd, message));
   if (predictedFiles && predictedFiles.length > 0) {
-    const modified = getModifiedFiles(cwd);
-    if (modified.length === 0) {
-      return "Auto-commit: skipped (no working-tree changes).";
-    }
-    const dirname7 = (p) => {
-      const idx = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
-      return idx > 0 ? p.slice(0, idx) : "";
-    };
     const cleanedPredicted = sanitisePredictedFiles(predictedFiles);
-    const scoped = modified.filter((p) => isPathInPredictedScope(p, cleanedPredicted));
-    const untracked = getUntrackedFiles(cwd);
-    const scopedSet = new Set(scoped);
-    const untrackedInScope = untracked.filter(
-      (p) => !scopedSet.has(p) && isPathInPredictedScope(p, cleanedPredicted)
-    );
-    if (scoped.length === 0 && untrackedInScope.length === 0) {
-      const modSample = modified.slice(0, 5).join(", ");
-      const predSample = cleanedPredicted.slice(0, 5).join(", ");
-      return `Auto-commit: refused \u2014 none of the ${modified.length} modified file(s) intersect FILES LIKELY TOUCHED. Modified: ${modSample}. Expected: ${predSample}. Stage the intended files manually (\`git add <paths>\`) then re-run, or set PAPI_AUTO_COMMIT=false.`;
-    }
-    const scopedDirs = [...new Set(scoped.map(dirname7).filter((d) => d.length > 0))];
-    const isUnderScopedDir = (p) => scopedDirs.some((d) => p === d || p.startsWith(`${d}/`) || p.startsWith(`${d}\\`));
-    const inScopeSet = /* @__PURE__ */ new Set([...scoped, ...untrackedInScope]);
-    const adjacentUntracked = untracked.filter(
-      (p) => !inScopeSet.has(p) && isUnderScopedDir(p)
-    );
-    const toStage = [...scoped, ...untrackedInScope, ...adjacentUntracked];
-    const toStageSet = new Set(toStage);
-    const droppedUntracked = untracked.filter((p) => !toStageSet.has(p));
-    const droppedModified = modified.filter((p) => !scopedSet.has(p));
-    let line = safeRun(() => stagePathsAndCommit(cwd, toStage, message)) + ` (scoped to ${scoped.length}/${modified.length} files via FILES LIKELY TOUCHED` + (untrackedInScope.length > 0 ? ` + ${untrackedInScope.length} new file(s) named in the handoff` : "") + (adjacentUntracked.length > 0 ? ` + ${adjacentUntracked.length} untracked under scoped dir(s)` : "") + `).`;
-    if (droppedModified.length > 0) {
-      const sample = droppedModified.slice(0, 10).join(", ");
-      const more = droppedModified.length > 10 ? ` (+${droppedModified.length - 10} more)` : "";
-      line += ` \u26A0\uFE0F ${droppedModified.length} modified file(s) outside FILES LIKELY TOUCHED were NOT staged: ${sample}${more}. If they belong to this task, stage them manually (\`git add <paths>\`) and re-run, or set PAPI_AUTO_COMMIT=false.`;
-    }
-    if (droppedUntracked.length > 0) {
-      const sample = droppedUntracked.slice(0, 10).join(", ");
-      const more = droppedUntracked.length > 10 ? ` (+${droppedUntracked.length - 10} more)` : "";
-      line += ` \u26A0\uFE0F ${droppedUntracked.length} untracked file(s) were NOT committed: ${sample}${more}. If they belong to this task, run \`git add <paths> && git commit --amend --no-edit\` before pushing \u2014 otherwise the committed tree may not build on checkout/CI.`;
+    const outOfScope = modified.filter((p) => !isPathInPredictedScope(p, cleanedPredicted));
+    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;
+    return `${commitResult} (staged all ${modified.length} changed file(s), all within FILES LIKELY TOUCHED).`;
   }
-  return safeRun(() => stageAllAndCommit(cwd, message));
+  return `${commitResult} (staged all ${modified.length} changed file(s)).`;
 }
 function pushAndCreatePR(config2, taskId, taskTitle, clientName, module, cycleNumber) {
   const lines = [];
@@ -21618,8 +21837,9 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
     await persistBranchName(adapter2, taskId, startedBranch);
   }
   buildStartTimes.set(taskId, (/* @__PURE__ */ new Date()).toISOString());
+  let startSha = null;
   if (isGitAvailable() && isGitRepo(config2.projectRoot)) {
-    const startSha = getHeadCommitSha(config2.projectRoot);
+    startSha = getHeadCommitSha(config2.projectRoot);
     if (startSha) taskStartShaMap.set(taskId, startSha);
   }
   let phaseChanges = [];
@@ -21638,6 +21858,14 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
     );
   } catch {
   }
+  writeBuildCheckpoint({
+    cwd: config2.projectRoot,
+    taskId,
+    branch: getCurrentBranch(config2.projectRoot),
+    step: "branch_ready",
+    lastCommitSha: startSha,
+    modifiedFiles: getModifiedFiles(config2.projectRoot)
+  });
   return {
     task,
     branchLines,
@@ -21652,17 +21880,17 @@ function writeActiveTaskScope(projectRoot, taskId, filesLikelyTouched, adapterTy
     collector.add({ path: ".papi/active-task-scope.txt", content, mode: "overwrite" });
     return;
   }
-  const papiDir = join11(projectRoot, ".papi");
-  if (!existsSync7(papiDir)) {
-    mkdirSync2(papiDir, { recursive: true });
+  const papiDir = join12(projectRoot, ".papi");
+  if (!existsSync8(papiDir)) {
+    mkdirSync3(papiDir, { recursive: true });
   }
-  const scopePath = join11(papiDir, "active-task-scope.txt");
-  writeFileSync3(scopePath, content, "utf-8");
+  const scopePath = join12(papiDir, "active-task-scope.txt");
+  writeFileSync4(scopePath, content, "utf-8");
 }
 function clearActiveTaskScope(projectRoot) {
-  const scopePath = join11(projectRoot, ".papi", "active-task-scope.txt");
-  if (existsSync7(scopePath)) {
-    unlinkSync2(scopePath);
+  const scopePath = join12(projectRoot, ".papi", "active-task-scope.txt");
+  if (existsSync8(scopePath)) {
+    unlinkSync3(scopePath);
   }
 }
 function sanitiseResponseExcerpt(raw) {
@@ -21681,7 +21909,7 @@ function extractDocMeta(absolutePath, relativePath, cycleNumber) {
   else if (relativePath.startsWith("docs/architecture/")) type = "architecture";
   else if (relativePath.startsWith("docs/audits/")) type = "audit";
   try {
-    const content = readFileSync6(absolutePath, "utf-8").slice(0, 2e3);
+    const content = readFileSync7(absolutePath, "utf-8").slice(0, 2e3);
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (fmMatch) {
       const fm = fmMatch[1];
@@ -22078,14 +22306,14 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
   let docWarning;
   try {
     if (adapter2.searchDocs && hasLocalWorkspace() && await ownsLocalWorkspace(adapter2, config2.projectRoot)) {
-      const docsDir = join11(config2.projectRoot, "docs");
-      if (existsSync7(docsDir)) {
+      const docsDir = join12(config2.projectRoot, "docs");
+      if (existsSync8(docsDir)) {
         const scanDir = (dir, depth = 0) => {
           if (depth > 8) return [];
           const entries = readdirSync5(dir, { withFileTypes: true });
           const files = [];
           for (const e of entries) {
-            const full = join11(dir, e.name);
+            const full = join12(dir, e.name);
             if (e.isDirectory() && !e.isSymbolicLink()) files.push(...scanDir(full, depth + 1));
             else if (e.name.endsWith(".md")) files.push(full.replace(config2.projectRoot + "/", ""));
           }
@@ -22100,7 +22328,7 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
           const failed = [];
           for (const docPath of unregistered) {
             try {
-              const meta = extractDocMeta(join11(config2.projectRoot, docPath), docPath, cycleNumber);
+              const meta = extractDocMeta(join12(config2.projectRoot, docPath), docPath, cycleNumber);
               await adapter2.registerDoc({
                 title: meta.title,
                 type: meta.type,
@@ -22138,6 +22366,10 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
     clearActiveTaskScope(config2.projectRoot);
   } catch {
   }
+  try {
+    clearBuildCheckpoint({ cwd: config2.projectRoot, taskId });
+  } catch {
+  }
   return {
     task,
     report,
@@ -22252,8 +22484,8 @@ ${instructions}`;
 }
 
 // src/tools/doc-registry.ts
-import { readdirSync as readdirSync6, existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
-import { join as join12, relative } from "path";
+import { readdirSync as readdirSync6, existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
+import { join as join13, relative } from "path";
 import { homedir as homedir3 } from "os";
 import { randomUUID as randomUUID12 } from "crypto";
 import { docDeletionBlockMessage } from "@papi-ai/shared";
@@ -22451,7 +22683,7 @@ async function handleDocSearch(adapter2, args, config2) {
   const lines = docs.map((d) => {
     const actionCount = d.actions?.filter((a) => a.status === "pending").length ?? 0;
     const actionNote = actionCount > 0 ? ` | ${actionCount} pending action(s)` : "";
-    const missingNote = root && d.path && !existsSync8(join12(root, d.path)) ? `
+    const missingNote = root && d.path && !existsSync9(join13(root, d.path)) ? `
 > \u26A0\uFE0F **File missing on disk** \u2014 the registry points at \`${d.path}\` but nothing is there. Check \`git stash list\` for a papi-autostash entry, or re-create/deregister the doc.` : "";
     return `### ${d.title}
 **Type:** ${d.type} | **Status:** ${d.status} | **Cycle:** ${d.cycleCreated}${d.cycleUpdated ? `\u2192${d.cycleUpdated}` : ""}${actionNote}
@@ -22465,12 +22697,12 @@ ${d.summary}
 ${lines.join("\n---\n\n")}`);
 }
 function scanMdFiles(dir, rootDir) {
-  if (!existsSync8(dir)) return [];
+  if (!existsSync9(dir)) return [];
   const files = [];
   try {
     const entries = readdirSync6(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const full = join12(dir, entry.name);
+      const full = join13(dir, entry.name);
       if (entry.isDirectory()) {
         files.push(...scanMdFiles(full, rootDir));
       } else if (entry.name.endsWith(".md")) {
@@ -22483,7 +22715,7 @@ function scanMdFiles(dir, rootDir) {
 }
 function extractTitle(filePath) {
   try {
-    const content = readFileSync7(filePath, "utf-8").slice(0, 1e3);
+    const content = readFileSync8(filePath, "utf-8").slice(0, 1e3);
     const fmMatch = content.match(/^---[\s\S]*?title:\s*(.+?)$/m);
     if (fmMatch) return fmMatch[1].trim().replace(/^["']|["']$/g, "");
     const headingMatch = content.match(/^#+\s+(.+)$/m);
@@ -22495,7 +22727,7 @@ function extractTitle(filePath) {
 async function detectUnregisteredDocsNote(adapter2, config2) {
   try {
     if (!adapter2.searchDocs || !hasLocalWorkspace()) return "";
-    const docsDir = join12(config2.projectRoot, "docs");
+    const docsDir = join13(config2.projectRoot, "docs");
     const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
     if (docsFiles.length === 0) return "";
     const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
@@ -22521,17 +22753,17 @@ async function handleDocScan(adapter2, config2, args) {
   const includePlans = args.include_plans ?? false;
   const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
   const registeredPaths = new Set(registered.map((d) => d.path));
-  const docsDir = join12(config2.projectRoot, "docs");
+  const docsDir = join13(config2.projectRoot, "docs");
   const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
   const unregisteredDocs = docsFiles.filter((f) => !registeredPaths.has(f));
   let unregisteredPlans = [];
   if (includePlans) {
-    const plansDir = join12(homedir3(), ".claude", "plans");
-    if (existsSync8(plansDir)) {
+    const plansDir = join13(homedir3(), ".claude", "plans");
+    if (existsSync9(plansDir)) {
       const planFiles = scanMdFiles(plansDir, plansDir);
       unregisteredPlans = planFiles.map((f) => `plans/${f}`).filter((f) => !registeredPaths.has(f)).map((f) => ({
         path: f,
-        title: extractTitle(join12(plansDir, f.replace("plans/", "")))
+        title: extractTitle(join13(plansDir, f.replace("plans/", "")))
       }));
     }
   }
@@ -22542,7 +22774,7 @@ async function handleDocScan(adapter2, config2, args) {
   if (unregisteredDocs.length > 0) {
     lines.push(`## Unregistered Docs (${unregisteredDocs.length})`);
     for (const f of unregisteredDocs) {
-      const title = extractTitle(join12(config2.projectRoot, f));
+      const title = extractTitle(join13(config2.projectRoot, f));
       lines.push(`- \`${f}\`${title ? ` \u2014 ${title}` : ""}`);
     }
   }
@@ -22715,97 +22947,6 @@ async function handleDocReorder(adapter2, args) {
 
 // src/tools/build.ts
 init_git();
-
-// src/lib/build-checkpoint.ts
-import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync9, mkdirSync as mkdirSync3, readFileSync as readFileSync8, unlinkSync as unlinkSync3, writeFileSync as writeFileSync4 } from "fs";
-import { join as join13 } from "path";
-var BUILD_CHECKPOINT_VERSION = 1;
-function cwdHash(cwd) {
-  return createHash4("sha256").update(realpathOrSelf(cwd)).digest("hex").slice(0, 12);
-}
-function safeTaskId(taskId) {
-  return taskId.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
-function checkpointDir(cwd) {
-  return join13(cwd, ".papi", "state");
-}
-function checkpointPath(cwd, taskId) {
-  return join13(checkpointDir(cwd), `build-${safeTaskId(taskId)}.${cwdHash(cwd)}.json`);
-}
-function writeBuildCheckpoint(input) {
-  try {
-    const dir = checkpointDir(input.cwd);
-    if (!existsSync9(dir)) {
-      mkdirSync3(dir, { recursive: true });
-    }
-    const checkpoint = {
-      version: BUILD_CHECKPOINT_VERSION,
-      taskId: input.taskId,
-      branch: input.branch,
-      step: input.step,
-      lastCommitSha: input.lastCommitSha,
-      modifiedFiles: input.modifiedFiles,
-      cwd: realpathOrSelf(input.cwd),
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    writeFileSync4(checkpointPath(input.cwd, input.taskId), JSON.stringify(checkpoint, null, 2) + "\n", "utf-8");
-  } catch {
-  }
-}
-function readBuildCheckpoint(key) {
-  try {
-    const path7 = checkpointPath(key.cwd, key.taskId);
-    if (!existsSync9(path7)) return null;
-    const parsed = JSON.parse(readFileSync8(path7, "utf-8"));
-    if (!parsed || parsed.version !== BUILD_CHECKPOINT_VERSION || parsed.taskId !== key.taskId) {
-      return null;
-    }
-    return {
-      version: BUILD_CHECKPOINT_VERSION,
-      taskId: parsed.taskId,
-      branch: parsed.branch ?? null,
-      step: "branch_ready",
-      lastCommitSha: parsed.lastCommitSha ?? null,
-      modifiedFiles: Array.isArray(parsed.modifiedFiles) ? parsed.modifiedFiles : [],
-      cwd: typeof parsed.cwd === "string" ? parsed.cwd : realpathOrSelf(key.cwd),
-      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : ""
-    };
-  } catch {
-    return null;
-  }
-}
-function clearBuildCheckpoint(key) {
-  try {
-    const path7 = checkpointPath(key.cwd, key.taskId);
-    if (existsSync9(path7)) {
-      unlinkSync3(path7);
-    }
-  } catch {
-  }
-}
-function formatResumeNote(cp) {
-  const files = cp.modifiedFiles.filter((f) => f && f.trim());
-  const fileList = files.length > 0 ? files.slice(0, 12).map((f) => `  - ${f}`).join("\n") + (files.length > 12 ? `
-  - \u2026+${files.length - 12} more` : "") : "  _(none recorded)_";
-  const lines = [
-    "> **\u21BB Resuming from checkpoint** \u2014 this task is already In Progress; you are NOT starting clean.",
-    `> - Branch: \`${cp.branch ?? "unknown"}\``,
-    "> - Last step: branch ready",
-    `> - Last commit: ${cp.lastCommitSha ? cp.lastCommitSha.slice(0, 8) : "none"}`,
-    `> - Checkpoint saved: ${cp.updatedAt || "unknown"}`,
-    ">",
-    "> Modified files at last checkpoint:",
-    ...fileList.split("\n").map((l) => `> ${l}`),
-    ">",
-    "> Review the existing branch and changes above before writing new code \u2014 do not re-do work already committed.",
-    "",
-    ""
-  ];
-  return lines.join("\n");
-}
-
-// src/tools/build.ts
 var buildListTool = {
   name: "build_list",
   description: "List cycle tasks that have BUILD HANDOFFs ready for execution. Shows task ID, title, status, priority, and complexity. In Progress tasks appear first, then Backlog. Does not call the Anthropic API.",
@@ -23184,14 +23325,6 @@ async function handleBuildExecute(adapter2, config2, args, clientName) {
     const result = await startBuild(adapter2, config2, taskId, { light }, clientName);
     tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.task.cycle ?? null });
     await tracker.recordStep("branch_ready");
-    writeBuildCheckpoint({
-      cwd: config2.projectRoot,
-      taskId,
-      branch: getCurrentBranch(config2.projectRoot),
-      step: "branch_ready",
-      lastCommitSha: getHeadCommitSha(config2.projectRoot),
-      modifiedFiles: getModifiedFiles(config2.projectRoot)
-    });
     tracker.mark("start_decorate_handoff");
     const branchInfo = result.branchLines.length > 0 ? result.branchLines.map((l) => `> ${l}`).join("\n") + "\n\n" : "";
     const phaseNote = result.phaseChanges.length > 0 ? "\n\n" + result.phaseChanges.map((c) => `Phase auto-updated: ${c.phaseId} ${c.oldStatus} \u2192 ${c.newStatus}`).join("\n") : "";
@@ -23410,7 +23543,6 @@ Your report was NOT discarded and the task is NOT yet Done \u2014 re-send with \
       preview
     }, { light }, clientName);
     tracker.mark("complete_format");
-    clearBuildCheckpoint({ cwd: config2.projectRoot, taskId });
     tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.cycleNumber });
     await tracker.recordStep("report_written");
     if ((result.autoTriagedCount ?? 0) > 0) {
@@ -27133,9 +27265,15 @@ var TASK_REF = /\btask-\d+\b/gi;
 var RECENT_CYCLE_WINDOW = 5;
 var MAX_CANDIDATES = 5;
 async function findUnblockCandidates(adapter2, currentCycle) {
+  try {
+    const blockedProbe = await adapter2.queryBoard({ status: ["Blocked"], compact: true });
+    if (blockedProbe.length === 0) return [];
+  } catch {
+    return [];
+  }
   let allTasks = [];
   try {
-    allTasks = await adapter2.queryBoard();
+    allTasks = await adapter2.queryBoard({ compact: true });
   } catch {
     return [];
   }
@@ -27721,7 +27859,13 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
       lines.push(`**Nearing Closure:** ${hierarchy.phasesNearingClosure.join(", ")}`);
     }
     if (hierarchy.stageExitCriteria && hierarchy.stageExitCriteria.length > 0) {
-      lines.push(`**Stage Exit Criteria:** ${hierarchy.stageExitCriteria.map((c) => `[ ] ${c}`).join(" | ")}`);
+      const crit = hierarchy.stageExitCriteria;
+      const met = crit.filter((c) => c.met).length;
+      const total = crit.length;
+      lines.push(`**Stage Exit Criteria [${met}/${total} met]:** ${crit.map((c) => `${c.met ? "[x]" : "[ ]"} ${c.text}`).join(" | ")}`);
+      if (met === total) {
+        lines.push("  \u21B3 All exit criteria met \u2014 run `strategy_review` to propose advancing the stage.");
+      }
     }
     lines.push("");
   }
@@ -27926,9 +28070,9 @@ function formatDiscoveredIssuesBlocks(candidateLearnings, closedTaskIds) {
     for (const issue of alerts) {
       const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
       lines.push(`- **${issue.severity}**: ${desc}`);
-      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})`);
+      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})${issue.id ? ` \xB7 id \`${issue.id}\`` : ""}`);
     }
-    lines.push("_Escalate: run `idea` with P1 priority to log as a backlog task, or `board_edit` if already handled._");
+    lines.push("_Already fixed? `discovered_issue_resolve <id>` clears it for good (won't reappear). Not yet? `idea` with P1 priority to log it as a backlog task._");
     alertsNote = lines.join("\n");
   }
   if (allLowSev.length > 0) {
@@ -27938,18 +28082,18 @@ function formatDiscoveredIssuesBlocks(candidateLearnings, closedTaskIds) {
     for (const issue of unactioned) {
       const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
       lines.push(`- **${issue.severity}**: ${desc}`);
-      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})`);
+      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})${issue.id ? ` \xB7 id \`${issue.id}\`` : ""}`);
     }
-    lines.push("_Run `idea` to log these as backlog tasks, or `board_edit` if already handled._");
+    lines.push("_Already fixed? `discovered_issue_resolve <id>` clears it. Otherwise `idea` to log as a backlog task._");
     unactionedIssuesNote = lines.join("\n");
   }
   return { alertsNote, unactionedIssuesNote };
 }
-async function computeTeamSummary(adapter2) {
+async function computeTeamSummary(adapter2, contributorsInput) {
   if (typeof adapter2.listContributors !== "function") return void 0;
   let members;
   try {
-    members = (await adapter2.listContributors()).length;
+    members = (await (contributorsInput ?? adapter2.listContributors())).length;
   } catch {
     return void 0;
   }
@@ -27966,11 +28110,11 @@ async function computeTeamSummary(adapter2) {
   const reviewQueue = tasks.filter((t) => t.status === "In Review").length;
   return `**Team:** ${members} members \xB7 ${pool} in pool \xB7 ${inFlight} in flight \xB7 ${reviewQueue} in review`;
 }
-async function computeReleaseHistory(adapter2) {
+async function computeReleaseHistory(adapter2, contributorsInput) {
   if (typeof adapter2.listContributors !== "function") return void 0;
   let contributors;
   try {
-    contributors = await adapter2.listContributors();
+    contributors = await (contributorsInput ?? adapter2.listContributors());
   } catch {
     return void 0;
   }
@@ -28301,13 +28445,13 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
       // "writing to the wrong project" for multi-project users on a shared key / stateless
       // HTTP transport where a once-per-session gate can't work.
       tracked("project-banner", async () => {
-        if (!adapter2.getProjectInfo) return { banner: "", name: void 0 };
+        if (!adapter2.getProjectInfo) return { banner: "", name: void 0, repoConnected: void 0 };
         const projectInfo = await adapter2.getProjectInfo();
-        if (!projectInfo) return { banner: "", name: void 0 };
+        if (!projectInfo) return { banner: "", name: void 0, repoConnected: void 0 };
         const banner = getProjectConnectionBanner(projectInfo.name, projectInfo.slug);
         return { banner: banner ? `
 > ${banner}
-` : "", name: projectInfo.name };
+` : "", name: projectInfo.name, repoConnected: !!projectInfo.repo_url };
       }),
       // Session guidance — proactive nudges (doc_register, context bloat, mode switch)
       tracked("session-guidance", async () => {
@@ -28445,7 +28589,7 @@ ${versionDrift}` : "";
     const patternsNote = patternsOutcome.status === "fulfilled" ? patternsOutcome.value : "";
     const { alertsNote, unactionedIssuesNote } = discoveredIssuesOutcome.status === "fulfilled" ? discoveredIssuesOutcome.value : { alertsNote: "", unactionedIssuesNote: "" };
     const skillProposalsNote = skillScanOutcome.status === "fulfilled" ? skillScanOutcome.value : "";
-    const projectBannerResult = projectBannerOutcome.status === "fulfilled" ? projectBannerOutcome.value : { banner: "", name: void 0 };
+    const projectBannerResult = projectBannerOutcome.status === "fulfilled" ? projectBannerOutcome.value : { banner: "", name: void 0, repoConnected: void 0 };
     const projectBannerNote = projectBannerResult.banner;
     const projectName = projectBannerResult.name;
     const sessionGuidanceNote = sessionGuidanceOutcome.status === "fulfilled" ? sessionGuidanceOutcome.value : "";
@@ -28486,16 +28630,27 @@ ${versionDrift}` : "";
         preBuildCheckNote = lines.join("\n");
       }
     }
-    tracker.mark("unblock-candidates");
-    let unblockNote = "";
-    try {
-      const candidates = await tracked("unblock-candidates", () => findUnblockCandidates(adapter2, currentCycle))();
-      const section = formatUnblockSection(candidates);
-      if (section) unblockNote = `
+    tracker.mark("parallel-tail");
+    const sharedContributorsPromise = typeof adapter2.listContributors === "function" ? adapter2.listContributors().catch(() => []) : Promise.resolve([]);
+    const [unblockCandidates, subAgents, teamSummaryLine, releaseHistoryLine, carryForwardRefs] = await Promise.all([
+      tracked("unblock-candidates", () => findUnblockCandidates(adapter2, currentCycle))().catch(() => []),
+      // task-1866: discover project sub-agents for the orient surface (read-only, never throws).
+      listAgents(config2.projectRoot),
+      // task-2071 (MU-3) + task-2072 (MU-5): team summary + release-history — both
+      // multi-member only; solo projects get undefined from both, so orient stays
+      // byte-identical there.
+      tracked("team-summary", () => computeTeamSummary(adapter2, sharedContributorsPromise))().catch(() => void 0),
+      tracked("release-history", () => computeReleaseHistory(adapter2, sharedContributorsPromise))().catch(() => void 0),
+      // task-2751 (C332): resolve every task-NNNN mentioned in the Carry-Forward
+      // prose to its title so orient can name it inline. Built from the board
+      // already in hand — no extra query.
+      resolveCarryForwardRefs(healthResult.carryForward, allTasks, adapter2)
+    ]);
+    const unblockSection = formatUnblockSection(unblockCandidates);
+    const unblockNote = unblockSection ? `
 
-${section}`;
-    } catch {
-    }
+${unblockSection}` : "";
+    const teamSummary = [teamSummaryLine, releaseHistoryLine].filter(Boolean).join("\n") || void 0;
     let deferredGateNote = "";
     if (deepHousekeeping) {
       try {
@@ -28507,16 +28662,22 @@ ${section}`;
       } catch {
       }
     }
+    let onboardingCoachingNote = "";
+    try {
+      const adsForCoaching = await sharedActiveDecisionsPromise;
+      onboardingCoachingNote = formatOnboardingCoachingBlock({
+        surface: "orient",
+        repoConnected: projectBannerResult.repoConnected,
+        hasLocalWorkspace: hasLocalWorkspace(),
+        hasActiveDecisions: adsForCoaching.length > 0,
+        cycleNumber: currentCycle,
+        hasActiveCycle: currentCycle > 0 && !cycleIsComplete
+      });
+    } catch {
+    }
     tracker.mark("format-summary");
-    const subAgents = await listAgents(config2.projectRoot);
-    const [teamSummaryLine, releaseHistoryLine] = await Promise.all([
-      tracked("team-summary", () => computeTeamSummary(adapter2))().catch(() => void 0),
-      tracked("release-history", () => computeReleaseHistory(adapter2))().catch(() => void 0)
-    ]);
-    const teamSummary = [teamSummaryLine, releaseHistoryLine].filter(Boolean).join("\n") || void 0;
     const deepHint = deepHousekeeping ? "" : "\n\n*Tip: pass `full: true` for Research Signals + version-drift, or `deep_housekeeping: true` to also check orphaned branches, merged-but-In-Progress tasks, unrecorded commits, unregistered docs, and stale skill forks (implies `full`).*";
-    const carryForwardRefs = await resolveCarryForwardRefs(healthResult.carryForward, allTasks, adapter2);
-    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName, carryForwardRefs) + unblockNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
+    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName, carryForwardRefs) + unblockNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + onboardingCoachingNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const isKnownFriendly = /^(Orient failed|Project not found|No project|Setup required)/i.test(message);
@@ -28571,7 +28732,7 @@ function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, client
 // src/tools/hierarchy.ts
 var hierarchyUpdateTool = {
   name: "hierarchy_update",
-  description: "Update the status of a phase, stage, or horizon in the project hierarchy (AD-14). Accepts a level (phase, stage, or horizon), a name or ID, and a new status. For stages, optionally set exit_criteria \u2014 a checklist defining when the stage is considered done. Does not call the Anthropic API.",
+  description: "Create or update a horizon, stage, or phase in the project hierarchy (AD-14). For stages and horizons this UPSERTS: if the named entity exists it is updated, otherwise it is CREATED (pass a label). Phases are update-only (they evolve via plan/strategy). For stages you can set exit_criteria (a checklist), or flip a single criterion with set_criterion_met. NEVER auto-advances \u2014 progression is human-in-loop via strategy_review. Does not call the Anthropic API.",
   annotations: { title: "Update Hierarchy", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -28579,129 +28740,218 @@ var hierarchyUpdateTool = {
       level: {
         type: "string",
         enum: ["phase", "stage", "horizon"],
-        description: "Which hierarchy level to update."
+        description: "Which hierarchy level to create/update."
       },
       name: {
         type: "string",
-        description: "The label or ID of the stage/horizon to update."
+        description: "The label, slug, or ID of the entity. On create, becomes the label if `label` is omitted."
+      },
+      label: {
+        type: "string",
+        description: 'Display label. Required to CREATE a new stage/horizon when `name` does not match an existing one (e.g. "S2: Alpha Cohort").'
+      },
+      slug: {
+        type: "string",
+        description: "Explicit slug for a new entity (stage/horizon). Auto-derived from the label when omitted."
+      },
+      description: {
+        type: "string",
+        description: "Optional longer description (stage/horizon)."
       },
       status: {
         type: "string",
         enum: ["Not Started", "In Progress", "Done", "Deferred"],
-        description: "The new status to set."
+        description: 'The status to set. On create, defaults to "Not Started".'
+      },
+      sort_order: {
+        type: "number",
+        description: "Display order for a new entity. Auto-computed (max existing + 10) when omitted."
+      },
+      horizon: {
+        type: "string",
+        description: "Parent horizon (name/slug/id) when CREATING a stage. Defaults to the sole horizon if only one exists."
       },
       exit_criteria: {
         type: "array",
         items: { type: "string" },
-        description: 'Checklist defining when this stage is done (stages only). Each item is a completion condition, e.g. "All P0 tasks shipped". Replaces existing criteria.'
+        description: "Checklist defining when a STAGE is done. Each item is a completion condition. REPLACES existing criteria (resets met state \u2014 use set_criterion_met to flip one)."
+      },
+      set_criterion_met: {
+        type: "object",
+        description: "Flip a single stage exit criterion (task-1625). { criterion_id, met, evidence? }.",
+        properties: {
+          criterion_id: { type: "string", description: "The ExitCriterion id to flip." },
+          met: { type: "boolean", description: "true = met, false = unmet." },
+          evidence: { type: "string", description: 'Optional evidence for a met criterion (e.g. "task-1234 shipped").' }
+        },
+        required: ["criterion_id", "met"]
       }
     },
     required: ["level", "name"]
   }
 };
 var VALID_STATUSES3 = /* @__PURE__ */ new Set(["Not Started", "In Progress", "Done", "Deferred"]);
+function slugify(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "item";
+}
+function nextSortOrder(existing) {
+  if (existing.length === 0) return 10;
+  return Math.max(...existing.map((e) => e.sortOrder)) + 10;
+}
 async function handleHierarchyUpdate(adapter2, args) {
   const level = args.level;
   const name = args.name;
+  const label = args.label;
+  const slug = args.slug;
+  const description = args.description;
   const status = args.status;
+  const sortOrder = typeof args.sort_order === "number" ? args.sort_order : void 0;
+  const horizonRef = args.horizon;
   const exitCriteria = args.exit_criteria;
+  const setCriterion = args.set_criterion_met;
   if (!level || !name) {
     return errorResponse("Missing required parameters: level, name.");
   }
-  if (!status && !exitCriteria) {
-    return errorResponse("Nothing to update. Provide at least one of: status, exit_criteria.");
-  }
   if (level !== "phase" && level !== "stage" && level !== "horizon") {
     return errorResponse(`Invalid level "${level}". Must be "phase", "stage", or "horizon".`);
   }
   if (status && !VALID_STATUSES3.has(status)) {
     return errorResponse(`Invalid status "${status}". Must be one of: Not Started, In Progress, Done, Deferred.`);
   }
-  if (exitCriteria !== void 0 && level !== "stage") {
-    return errorResponse("exit_criteria can only be set on stages.");
+  if ((exitCriteria !== void 0 || setCriterion !== void 0) && level !== "stage") {
+    return errorResponse("exit_criteria and set_criterion_met can only be used on stages.");
+  }
+  if (!status && exitCriteria === void 0 && setCriterion === void 0 && !label) {
+    return errorResponse("Nothing to do. Provide at least one of: status, exit_criteria, set_criterion_met, or label (to create).");
   }
   try {
     if (level === "phase") {
-      if (!adapter2.readPhases || !adapter2.updatePhaseStatus) {
-        return errorResponse("Phase management is not supported by the current adapter.");
-      }
-      const phases = await adapter2.readPhases();
-      const phase = phases.find(
-        (p) => p.label.toLowerCase() === name.toLowerCase() || p.id === name || p.slug === name
-      );
-      if (!phase) {
-        const available = phases.map((p) => p.label).join(", ");
-        return errorResponse(`Phase "${name}" not found. Available phases: ${available || "none"}`);
-      }
-      if (!status) {
-        return errorResponse("status is required for phase updates.");
-      }
-      if (phase.status === status) {
-        return textResponse(`Phase "${phase.label}" is already "${status}". No change made.`);
-      }
-      const oldStatus2 = phase.status;
-      await adapter2.updatePhaseStatus(phase.id, status);
-      return textResponse(`Phase updated: **${phase.label}** ${oldStatus2} \u2192 ${status}`);
+      return await handlePhase(adapter2, name, status);
     }
     if (level === "stage") {
-      if (!adapter2.readStages) {
-        return errorResponse("Stage management is not supported by the current adapter.");
-      }
-      const stages = await adapter2.readStages();
-      const stage = stages.find(
-        (s) => s.label.toLowerCase() === name.toLowerCase() || s.id === name || s.slug === name
-      );
-      if (!stage) {
-        const available = stages.map((s) => s.label).join(", ");
-        return errorResponse(`Stage "${name}" not found. Available stages: ${available || "none"}`);
-      }
-      const resultLines = [];
-      if (status) {
-        if (!adapter2.updateStageStatus) {
-          return errorResponse("Stage status updates are not supported by the current adapter.");
-        }
-        if (stage.status === status) {
-          resultLines.push(`Stage "${stage.label}" is already "${status}".`);
-        } else {
-          const oldStatus2 = stage.status;
-          await adapter2.updateStageStatus(stage.id, status);
-          resultLines.push(`Stage updated: **${stage.label}** ${oldStatus2} \u2192 ${status}`);
-        }
-      }
-      if (exitCriteria !== void 0) {
-        if (!adapter2.updateStageExitCriteria) {
-          return errorResponse("Exit criteria updates are not supported by the current adapter.");
-        }
-        await adapter2.updateStageExitCriteria(stage.id, exitCriteria);
-        resultLines.push(`Exit criteria set (${exitCriteria.length} item${exitCriteria.length !== 1 ? "s" : ""}):`);
-        exitCriteria.forEach((c) => resultLines.push(`  - ${c}`));
-      }
-      return textResponse(resultLines.join("\n"));
+      return await handleStage(adapter2, { name, label, slug, description, status, sortOrder, horizonRef, exitCriteria, setCriterion });
     }
-    if (!adapter2.readHorizons || !adapter2.updateHorizonStatus) {
-      return errorResponse("Horizon management is not supported by the current adapter.");
-    }
-    const horizons = await adapter2.readHorizons();
-    const horizon = horizons.find(
-      (h) => h.label.toLowerCase() === name.toLowerCase() || h.id === name || h.slug === name
-    );
-    if (!horizon) {
-      const available = horizons.map((h) => h.label).join(", ");
-      return errorResponse(`Horizon "${name}" not found. Available horizons: ${available || "none"}`);
-    }
-    if (!status) {
-      return errorResponse("status is required for horizon updates.");
-    }
-    if (horizon.status === status) {
-      return textResponse(`Horizon "${horizon.label}" is already "${status}". No change made.`);
-    }
-    const oldStatus = horizon.status;
-    await adapter2.updateHorizonStatus(horizon.id, status);
-    return textResponse(`Horizon updated: **${horizon.label}** ${oldStatus} \u2192 ${status}`);
+    return await handleHorizon(adapter2, { name, label, slug, description, status, sortOrder });
   } catch (err) {
     return errorResponse(err instanceof Error ? err.message : String(err));
   }
 }
+async function handlePhase(adapter2, name, status) {
+  if (!adapter2.readPhases || !adapter2.updatePhaseStatus) {
+    return errorResponse("Phase management is not supported by the current adapter.");
+  }
+  if (!status) return errorResponse("status is required for phase updates.");
+  const phases = await adapter2.readPhases();
+  const phase = phases.find((p) => p.label.toLowerCase() === name.toLowerCase() || p.id === name || p.slug === name);
+  if (!phase) {
+    const available = phases.map((p) => p.label).join(", ");
+    return errorResponse(`Phase "${name}" not found. Available phases: ${available || "none"} (phases are update-only \u2014 create them via plan/setup).`);
+  }
+  if (phase.status === status) return textResponse(`Phase "${phase.label}" is already "${status}". No change made.`);
+  const oldStatus = phase.status;
+  await adapter2.updatePhaseStatus(phase.id, status);
+  return textResponse(`Phase updated: **${phase.label}** ${oldStatus} \u2192 ${status}`);
+}
+async function handleStage(adapter2, a) {
+  if (!adapter2.readStages) {
+    return errorResponse("Stage management is not supported by the current adapter.");
+  }
+  const stages = await adapter2.readStages();
+  let stage = stages.find(
+    (s) => s.label.toLowerCase() === a.name.toLowerCase() || s.id === a.name || s.slug === a.name
+  );
+  const resultLines = [];
+  let created = false;
+  if (!stage) {
+    if (!adapter2.createHorizon || !adapter2.createStage || !adapter2.readHorizons) {
+      return errorResponse("Stage creation is not supported by the current adapter.");
+    }
+    const createLabel = a.label ?? a.name;
+    const horizons = await adapter2.readHorizons();
+    let parent;
+    if (a.horizonRef) {
+      parent = horizons.find((h) => h.label.toLowerCase() === a.horizonRef.toLowerCase() || h.id === a.horizonRef || h.slug === a.horizonRef);
+      if (!parent) {
+        const available = horizons.map((h) => h.label).join(", ");
+        return errorResponse(`Parent horizon "${a.horizonRef}" not found. Available horizons: ${available || "none"}.`);
+      }
+    } else if (horizons.length === 1) {
+      parent = horizons[0];
+    } else if (horizons.length === 0) {
+      return errorResponse('No horizon exists to attach the stage to. Create a horizon first (level:"horizon", label:"H1: ...").');
+    } else {
+      return errorResponse(`Multiple horizons exist \u2014 pass \`horizon\` to say which one the stage belongs to: ${horizons.map((h) => h.label).join(", ")}.`);
+    }
+    const newId = await adapter2.createStage({
+      slug: a.slug ?? slugify(createLabel),
+      label: createLabel,
+      description: a.description,
+      status: a.status ?? "Not Started",
+      sortOrder: a.sortOrder ?? nextSortOrder(stages.filter((s) => s.horizonId === parent.id)),
+      horizonId: parent.id
+    });
+    const refreshed = await adapter2.readStages();
+    stage = refreshed.find((s) => s.id === newId);
+    if (!stage) return errorResponse("Stage was created but could not be re-read.");
+    created = true;
+    resultLines.push(`Stage created: **${stage.label}** (under ${parent.label}, status ${stage.status})`);
+  }
+  if (a.status && !created) {
+    if (!adapter2.updateStageStatus) return errorResponse("Stage status updates are not supported by the current adapter.");
+    if (stage.status === a.status) {
+      resultLines.push(`Stage "${stage.label}" is already "${a.status}".`);
+    } else {
+      const oldStatus = stage.status;
+      await adapter2.updateStageStatus(stage.id, a.status);
+      resultLines.push(`Stage updated: **${stage.label}** ${oldStatus} \u2192 ${a.status}`);
+    }
+  }
+  if (a.exitCriteria !== void 0) {
+    if (!adapter2.updateStageExitCriteria) return errorResponse("Exit criteria updates are not supported by the current adapter.");
+    await adapter2.updateStageExitCriteria(stage.id, a.exitCriteria);
+    resultLines.push(`Exit criteria set (${a.exitCriteria.length} item${a.exitCriteria.length !== 1 ? "s" : ""}, all unmet):`);
+    a.exitCriteria.forEach((c) => resultLines.push(`  - ${c}`));
+  }
+  if (a.setCriterion !== void 0) {
+    if (!adapter2.setCriterionMet) return errorResponse("set_criterion_met is not supported by the current adapter.");
+    await adapter2.setCriterionMet(stage.id, a.setCriterion.criterion_id, a.setCriterion.met, a.setCriterion.evidence ?? null);
+    const after = (await adapter2.readStages()).find((s) => s.id === stage.id);
+    const crit = after?.exitCriteria?.find((c) => c.id === a.setCriterion.criterion_id);
+    if (!crit) {
+      resultLines.push(`\u26A0\uFE0F Criterion id "${a.setCriterion.criterion_id}" not found on this stage \u2014 no change.`);
+    } else {
+      const met = after?.exitCriteria?.filter((c) => c.met).length ?? 0;
+      const total = after?.exitCriteria?.length ?? 0;
+      resultLines.push(`Criterion "${crit.text}" \u2192 ${crit.met ? "met" : "unmet"}. [${met}/${total} criteria met]`);
+    }
+  }
+  return textResponse(resultLines.join("\n"));
+}
+async function handleHorizon(adapter2, a) {
+  if (!adapter2.readHorizons) {
+    return errorResponse("Horizon management is not supported by the current adapter.");
+  }
+  const horizons = await adapter2.readHorizons();
+  const horizon = horizons.find((h) => h.label.toLowerCase() === a.name.toLowerCase() || h.id === a.name || h.slug === a.name);
+  if (!horizon) {
+    if (!adapter2.createHorizon) return errorResponse("Horizon creation is not supported by the current adapter.");
+    const createLabel = a.label ?? a.name;
+    const newId = await adapter2.createHorizon({
+      slug: a.slug ?? slugify(createLabel),
+      label: createLabel,
+      description: a.description,
+      status: a.status ?? "Not Started",
+      sortOrder: a.sortOrder ?? nextSortOrder(horizons)
+    });
+    return textResponse(`Horizon created: **${createLabel}** (id ${newId}, status ${a.status ?? "Not Started"})`);
+  }
+  if (!a.status) return errorResponse("status is required to update an existing horizon (or pass a new name to create one).");
+  if (horizon.status === a.status) return textResponse(`Horizon "${horizon.label}" is already "${a.status}". No change made.`);
+  if (!adapter2.updateHorizonStatus) return errorResponse("Horizon status updates are not supported by the current adapter.");
+  const oldStatus = horizon.status;
+  await adapter2.updateHorizonStatus(horizon.id, a.status);
+  return textResponse(`Horizon updated: **${horizon.label}** ${oldStatus} \u2192 ${a.status}`);
+}
 
 // src/services/zoom-out.ts
 var BUDGET_SOFT = 12e4;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.69",
+  "version": "0.7.70",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "mcpName": "io.github.getpapi/papi",