@papi-ai/server 0.7.45 → 0.7.47

package/dist/index.js

@@ -1280,6 +1280,10 @@ var init_proxy_adapter = __esm({
       "claimReview",
       "getSiblingAds",
       "getSiblingRepoTasks"
+      // task-2489 (C320): recordProgressStep is now wired to the edge data-proxy
+      // (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.
     ]);
     ProxyPapiAdapter = class _ProxyPapiAdapter {
       endpoint;
@@ -5061,6 +5065,9 @@ function loadConfig() {
   const projectOwner = process.env.PAPI_OWNER ?? "Cathal";
   const skipProjectSpecificRules = process.env.PAPI_SKIP_PROJECT_RULES === "true";
   const userId = process.env.PAPI_USER_ID || void 0;
+  const gateCommand = process.env.PAPI_GATE?.trim() || void 0;
+  const deployCommand = process.env.PAPI_DEPLOY?.trim() || void 0;
+  const verifyCommand = process.env.PAPI_VERIFY?.trim() || void 0;
   const telemetryEnabled = process.env.PAPI_TELEMETRY !== "off" && process.env.PAPI_TELEMETRY !== "false";
   const papiEndpoint = process.env.PAPI_ENDPOINT;
   const dataEndpoint = process.env.PAPI_DATA_ENDPOINT;
@@ -5135,7 +5142,10 @@ Already have an account? Make sure PAPI_USER_ID is set in your .mcp.json env con
     skipProjectSpecificRules,
     userId,
     telemetryEnabled,
-    resolutionMethod
+    resolutionMethod,
+    gateCommand,
+    deployCommand,
+    verifyCommand
   };
 }
 
@@ -5147,27 +5157,14 @@ import { execSync } from "child_process";
 import { readFile, writeFile, access } from "fs/promises";
 import { randomUUID as randomUUID6 } from "crypto";
 import { join } from "path";
-
-// ../shared/dist/index.js
-var VALID_TRANSITIONS = {
-  "Backlog": ["In Cycle", "Ready", "In Progress", "Blocked", "Cancelled", "Deferred", "Done"],
-  "In Cycle": ["In Progress", "Backlog", "Blocked", "Cancelled"],
-  "Ready": ["In Progress", "Backlog", "Blocked", "Cancelled"],
-  "In Progress": ["In Review", "Backlog", "Blocked", "Cancelled"],
-  "In Review": ["Done", "In Progress", "Blocked", "Cancelled"],
-  "Done": [],
-  "Blocked": ["Backlog", "Ready", "In Cycle", "In Progress", "Cancelled"],
-  "Cancelled": [],
-  "Deferred": ["Backlog", "Cancelled"]
-};
-var RETIRED_DECISION_OUTCOMES = ["resolved", "abandoned", "superseded"];
-function isLiveDecision(d) {
-  if (d.superseded === true) return false;
-  if (d.outcome != null && RETIRED_DECISION_OUTCOMES.includes(d.outcome)) return false;
-  return true;
-}
-
-// ../adapter-md/dist/index.js
+import {
+  VALID_TRANSITIONS as _VALID_TRANSITIONS,
+  isValidTransition as _isValidTransition,
+  validateTransition as _validateTransition,
+  isValidStatus as _isValidStatus,
+  isLiveDecision as _isLiveDecision,
+  RETIRED_DECISION_OUTCOMES as _RETIRED_DECISION_OUTCOMES
+} from "@papi-ai/shared";
 import { randomUUID } from "crypto";
 import { randomUUID as randomUUID3 } from "crypto";
 import yaml from "js-yaml";
@@ -5176,8 +5173,8 @@ import { randomUUID as randomUUID4 } from "crypto";
 import { randomUUID as randomUUID5 } from "crypto";
 import yaml2 from "js-yaml";
 import yaml3 from "js-yaml";
-var VALID_TRANSITIONS2 = VALID_TRANSITIONS;
-var isLiveDecision2 = isLiveDecision;
+var VALID_TRANSITIONS = _VALID_TRANSITIONS;
+var isLiveDecision = _isLiveDecision;
 function extractSection(content, heading) {
   const headingPattern = new RegExp(`^## ${heading}\\s*$`, "m");
   const start = content.search(headingPattern);
@@ -6478,6 +6475,7 @@ function toCycle(raw) {
   };
   if (raw.end_date) cycle.endDate = raw.end_date;
   if (raw.user_id) cycle.userId = raw.user_id;
+  if (raw.dependency_chain) cycle.dependencyChain = raw.dependency_chain;
   return cycle;
 }
 function fromCycle(cycle) {
@@ -6492,6 +6490,7 @@ function fromCycle(cycle) {
   };
   if (cycle.endDate) raw.end_date = cycle.endDate;
   if (cycle.userId) raw.user_id = cycle.userId;
+  if (cycle.dependencyChain) raw.dependency_chain = cycle.dependencyChain;
   return raw;
 }
 function extractYamlBlock2(content) {
@@ -6536,7 +6535,7 @@ function prependCycle(cycle, content) {
     const yamlStr = yaml2.dump({ cycles: [raw] }, { lineWidth: 120, quotingType: '"' });
     return header + YAML_START2 + "\n" + yamlStr + YAML_END2 + "\n";
   }
-  const existing = parseCycles(content);
+  const existing = parseCycles(content).filter((c) => c.number !== cycle.number);
   const merged = [cycle, ...existing];
   return serializeCycles(merged, content);
 }
@@ -6633,7 +6632,7 @@ var MdFileAdapter = class {
     if (!content) return [];
     const all = parseActiveDecisions(content);
     if (options?.includeRetired) return all;
-    return all.filter(isLiveDecision2);
+    return all.filter(isLiveDecision);
   }
   /** Read cycle log entries (newest first), optionally limited to {@link limit} entries. */
   async getCycleLog(limit) {
@@ -6801,7 +6800,7 @@ var MdFileAdapter = class {
     }
     if (updates.status && updates.status !== tasks[idx].status && !options?.force) {
       const from = tasks[idx].status;
-      const allowed = VALID_TRANSITIONS2[from];
+      const allowed = VALID_TRANSITIONS[from];
       if (!allowed.includes(updates.status)) {
         console.warn(`[papi] Warning: invalid status transition "${from}" \u2192 "${updates.status}" for task ${id}. Allowed from "${from}": ${allowed.length > 0 ? allowed.join(", ") : "none"}`);
       }
@@ -8307,31 +8306,66 @@ function formatBoardForReview(tasks) {
   Notes: ${t.notes}` : ""}`
   ).join("\n\n");
 }
-var EFFORT_MAP = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
-function computeSnapshotsFromBuildReports(reports) {
-  if (reports.length === 0) return [];
-  const byCycleMap = /* @__PURE__ */ new Map();
+function effortWeight(size2) {
+  switch ((size2 || "").toUpperCase()) {
+    case "XS":
+      return 1;
+    case "S":
+    case "SMALL":
+      return 2;
+    case "M":
+    case "MEDIUM":
+      return 3;
+    case "L":
+    case "LARGE":
+      return 5;
+    case "XL":
+      return 8;
+    default:
+      return 3;
+  }
+}
+function computeSnapshotsFromBuildReports(reports, tasks) {
+  const reportsByCycle = /* @__PURE__ */ new Map();
   for (const r of reports) {
-    const existing = byCycleMap.get(r.cycle) ?? [];
+    const existing = reportsByCycle.get(r.cycle) ?? [];
     existing.push(r);
-    byCycleMap.set(r.cycle, existing);
+    reportsByCycle.set(r.cycle, existing);
+  }
+  const tasksByCycle = /* @__PURE__ */ new Map();
+  for (const t of tasks ?? []) {
+    if (t.cycle == null) continue;
+    const existing = tasksByCycle.get(t.cycle) ?? [];
+    existing.push(t);
+    tasksByCycle.set(t.cycle, existing);
   }
+  const cycleNumbers = /* @__PURE__ */ new Set([...reportsByCycle.keys(), ...tasksByCycle.keys()]);
+  if (cycleNumbers.size === 0) return [];
   const snapshots = [];
-  for (const [sn, cycleReports] of byCycleMap) {
-    const completed = cycleReports.filter((r) => r.completed === "Yes").length;
-    const total = cycleReports.length;
+  for (const sn of cycleNumbers) {
+    const cycleReports = reportsByCycle.get(sn) ?? [];
+    const cycleTaskRows = tasksByCycle.get(sn);
     const withEffort = cycleReports.filter((r) => r.estimatedEffort && r.actualEffort);
     const accurate = withEffort.filter((r) => r.estimatedEffort === r.actualEffort).length;
     const matchRate = withEffort.length > 0 ? Math.round(accurate / withEffort.length * 100) : 0;
-    let effortPoints = 0;
-    for (const r of cycleReports) {
-      effortPoints += EFFORT_MAP[r.actualEffort] ?? 3;
+    let completed;
+    let total;
+    let effortPoints;
+    if (cycleTaskRows && cycleTaskRows.length > 0) {
+      const done = cycleTaskRows.filter((t) => t.status === "Done");
+      completed = done.length;
+      total = cycleTaskRows.length;
+      effortPoints = done.reduce((s, t) => s + effortWeight(t.complexity), 0);
+    } else {
+      completed = cycleReports.filter((r) => r.completed === "Yes").length;
+      total = cycleReports.length;
+      effortPoints = cycleReports.reduce((s, r) => s + effortWeight(r.actualEffort), 0);
     }
     snapshots.push({
       cycle: sn,
       date: (/* @__PURE__ */ new Date()).toISOString(),
-      accuracy: [{ cycle: sn, reports: total, matchRate, mae: 0, bias: 0 }],
-      velocity: [{ cycle: sn, completed, partial: 0, failed: total - completed, effortPoints }]
+      accuracy: [{ cycle: sn, reports: cycleReports.length, matchRate, mae: 0, bias: 0 }],
+      velocity: [{ cycle: sn, completed, partial: 0, failed: Math.max(0, total - completed), effortPoints }]
     });
   }
   snapshots.sort((a, b2) => a.cycle - b2.cycle);
@@ -9273,6 +9307,14 @@ function buildHandoffsOnlyUserMessage(inputs) {
   }
   return parts.join("\n");
 }
+function extractDependencyChain(displayText) {
+  const match = displayText.match(
+    /^##\s+Dependency Chain[^\n]*\n([\s\S]*?)(?=\n#{2,3}\s|\n-{3,}\s*(?:\n|$)|\n\s*BUILD HANDOFF\b|\n<!--\s*PAPI_STRUCTURED_OUTPUT|$(?![\s\S]))/m
+  );
+  if (!match) return void 0;
+  const body = match[1].trim();
+  return body.length > 0 ? body : void 0;
+}
 function parseStructuredOutput(raw) {
   const marker = "<!-- PAPI_STRUCTURED_OUTPUT -->";
   const markerIdx = raw.indexOf(marker);
@@ -9288,6 +9330,7 @@ function parseStructuredOutput(raw) {
   try {
     const parsed = JSON.parse(jsonMatch[1].trim());
     const data = coerceStructuredOutput(parsed);
+    data.dependencyChain = extractDependencyChain(displayText);
     return { displayText, data };
   } catch {
     return { displayText, data: null };
@@ -11746,8 +11789,27 @@ ${cleanContent}`;
     contextHashes,
     // task-2071 (MU-3): own the cycle by the planning member (pg defaults to the
     // project owner when unset, so owner-operated plans stay correct).
-    ...options.ownerUserId ? { userId: options.ownerUserId } : {}
+    ...options.ownerUserId ? { userId: options.ownerUserId } : {},
+    // task-2483 (C319): persist the plan's Dependency Chain build-order markdown.
+    ...data.dependencyChain ? { dependencyChain: data.dependencyChain } : {}
   };
+  const earlyCreateWarnings = [];
+  try {
+    await adapter2.createCycle({
+      id: `cycle-${newCycleNumber}`,
+      number: newCycleNumber,
+      status: "active",
+      startDate: cycle.startDate,
+      goals: cycle.goals,
+      boardHealth: "",
+      taskIds: [],
+      ...cycle.userId ? { userId: cycle.userId } : {}
+    });
+  } catch (err) {
+    const msg = `early createCycle failed for cycle ${newCycleNumber}: ${err instanceof Error ? err.message : String(err)}`;
+    console.error(`[plan] ${msg}`);
+    earlyCreateWarnings.push(msg);
+  }
   let dedupedNewTasks = data.newTasks ?? [];
   if (dedupedNewTasks.length > 0) {
     const existingTasks = await adapter2.queryBoard({ compact: true });
@@ -11840,7 +11902,7 @@ ${cleanContent}`;
       `Plan write-back created ${actualNewTasks} of ${expectedNewTasks} new tasks the transaction was asked to create \u2014 investigate the planWriteBack handler. (This count is returned by the committed transaction, not a board re-read, so it is not a hosted read-lag artifact.)`
     );
   }
-  const allWarnings = [...result.warnings, ...verifyWarnings];
+  const allWarnings = [...result.warnings, ...verifyWarnings, ...earlyCreateWarnings];
   const handoffCount = data.cycleHandoffs?.length ?? 0;
   const correctionCount = data.boardCorrections?.length ?? 0;
   const newTaskCount = result.newTaskIdMap.size;
@@ -11880,6 +11942,23 @@ ${cleanContent}`;
   });
   const cycleTaskCount = legacyHandoffs.length;
   const cycleEffortPoints = legacyHandoffs.reduce((sum, h) => sum + (effortMap[h.handoff.effort] ?? 3), 0);
+  try {
+    await adapter2.createCycle({
+      id: `cycle-${newCycleNumber}`,
+      number: newCycleNumber,
+      status: "active",
+      startDate: (/* @__PURE__ */ new Date()).toISOString(),
+      goals: data.cycleLogTitle ? [data.cycleLogTitle] : [],
+      boardHealth: "",
+      taskIds: [],
+      contextHashes,
+      ...options.ownerUserId ? { userId: options.ownerUserId } : {}
+    });
+  } catch (err) {
+    const msg = `early createCycle failed for cycle ${newCycleNumber}: ${err instanceof Error ? err.message : String(err)}`;
+    console.error(`[plan] ${msg}`);
+    warnings.push(msg);
+  }
   const cycleLogPromise = adapter2.writeCycleLogEntry({
     uuid: randomUUID8(),
     cycleNumber: newCycleNumber,
@@ -12142,7 +12221,10 @@ ${cleanContent}`;
         taskIds: cycleTaskIds,
         contextHashes,
         // task-2071 (MU-3): own the cycle by the planning member.
-        ...options.ownerUserId ? { userId: options.ownerUserId } : {}
+        ...options.ownerUserId ? { userId: options.ownerUserId } : {},
+        // task-2483 (C319): persist the plan's Dependency Chain build-order markdown.
+        // This full write patches the early minimal row created in Phase 1.
+        ...data.dependencyChain ? { dependencyChain: data.dependencyChain } : {}
       };
       await adapter2.createCycle(cycle);
     } catch (err) {
@@ -12468,6 +12550,13 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
     contextHashes
   };
 }
+var PLAN_STAGE_STEPS = ["health-check", "inbox-triage", "board-integrity", "maturity-gate", "recommendation", "dependency-chain"];
+async function streamPlanStageSteps(tracker, newCycleNumber) {
+  tracker.setStreamScope({ cycle: newCycleNumber });
+  for (const step of PLAN_STAGE_STEPS) {
+    await tracker.recordStep(step);
+  }
+}
 async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, strategyReviewWarning, contextHashes, planRunMeta, tracker) {
   const applyTimer = startTimer();
   console.error(`[plan-perf] applyPlan: start (llm_response=${rawLlmOutput.length} chars)`);
@@ -12480,6 +12569,7 @@ async function applyPlan(adapter2, config2, rawLlmOutput, mode, cycleNumber, str
     if (config2.adapterType === "pg") {
       tracker?.mark("process_llm_output_pg");
       const result = await processLlmOutput(adapter2, config2, rawLlmOutput, mode, cycleNumber, contextHashes, planRunMeta);
+      if (tracker) await streamPlanStageSteps(tracker, cycleNumber + 1);
       const applyMs2 = applyTimer();
       console.error(`[plan-perf] applyPlan: total=${applyMs2}ms (pg, no git sync)`);
       return { ...result, pullNote: "", strategyReviewWarning };
@@ -12622,12 +12712,58 @@ ${JSON.stringify(payload, null, 2)}`;
 }
 var ProgressTracker = class {
   lastStep;
+  persistAdapter;
+  streamCtx;
   constructor(initial = "start") {
     this.lastStep = initial;
   }
   mark(step) {
     this.lastStep = step;
   }
+  /**
+   * Arm progress-stream persistence for this tool call. Safe to call with any
+   * adapter — persistence stays disarmed unless the adapter exposes BOTH
+   * `getProjectId` and `recordProgressStep` (i.e. the pg/DB-backed path). Returns
+   * `this` for chaining at the tracker construction site.
+   */
+  bindStream(adapter2, ctx) {
+    if (adapter2?.getProjectId && adapter2.recordProgressStep) {
+      this.persistAdapter = adapter2;
+    }
+    this.streamCtx = ctx;
+    return this;
+  }
+  /** Update the bound scope mid-call (e.g. once the cycle number is resolved). */
+  setStreamScope(scope) {
+    if (!this.streamCtx) return;
+    if (scope.cycle !== void 0) this.streamCtx.cycle = scope.cycle;
+    if (scope.taskId !== void 0) this.streamCtx.taskId = scope.taskId;
+  }
+  /**
+   * Record one step of the progress stream. Also advances `lastStep` so the
+   * structured-error diagnostic still points at the most recent named step.
+   * Fire-and-forget and fully guarded — the returned promise always resolves.
+   */
+  recordStep(step, opts = {}) {
+    this.lastStep = step;
+    const adapter2 = this.persistAdapter;
+    const ctx = this.streamCtx;
+    if (!adapter2?.recordProgressStep || !ctx) return Promise.resolve();
+    const row = {
+      stage: opts.stage ?? ctx.stage,
+      step,
+      status: opts.status ?? "complete",
+      cycle: opts.cycle !== void 0 ? opts.cycle : ctx.cycle ?? null,
+      taskId: opts.taskId !== void 0 ? opts.taskId : ctx.taskId ?? null,
+      capabilityKey: opts.capabilityKey ?? null,
+      capabilityEnabled: opts.capabilityEnabled ?? null,
+      metadata: opts.metadata
+    };
+    return adapter2.recordProgressStep(row).catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[progress-stream] failed to persist ${ctx.stage}/${step} (${row.status}): ${message}`);
+    });
+  }
 };
 function defaultHint(tool) {
   const knownTools = /* @__PURE__ */ new Set([
@@ -13088,7 +13224,7 @@ async function handlePlan(adapter2, config2, args) {
   const focus = typeof args.focus === "string" ? args.focus : void 0;
   const force = args.force === true;
   const handoffsOnly = args.handoffs_only === true;
-  const tracker = new ProgressTracker(toolMode === "apply" ? "apply_validate" : "prepare_validate");
+  const tracker = new ProgressTracker(toolMode === "apply" ? "apply_validate" : "prepare_validate").bindStream(adapter2, { stage: "plan" });
   try {
     if (toolMode === "apply") {
       const resolved = await resolveLlmResponse(
@@ -18322,6 +18458,86 @@ Examples (use whichever provider you have): ${spec.examples}.
 _Recommendation only \u2014 PAPI never selects or runs a model. Policy: XS/S \u2192 cheap, M/L \u2192 capable, XL \u2192 frontier._`;
 }
 
+// src/lib/capabilities.ts
+import {
+  CAPABILITY_KEYS,
+  CAPABILITY_REGISTRY,
+  isCapabilityKey,
+  isCapabilityEnabled
+} from "@papi-ai/shared";
+
+// src/lib/directive-builders.ts
+function buildPrReviewerDirective(caps) {
+  if (!isCapabilityEnabled(caps, "prReviewer")) return null;
+  return `
+
+**Quality Gate:** no auto-review attached. PAPI's standard pre-accept step is a code review of the branch diff \u2014 run \`review_submit\` with \`dispatch:"subagent"\` to auto-review, or attach \`auto_review\` findings. Risk-tier work (auth, data, migrations, CI) should always carry one.`;
+}
+function buildChangelogDirective(caps, inner) {
+  if (!isCapabilityEnabled(caps, "changelog")) return null;
+  return inner;
+}
+function buildDiscoveredIssuesDirective(caps, issueLines) {
+  if (!isCapabilityEnabled(caps, "discoveredIssues")) return null;
+  if (issueLines.length === 0) return null;
+  return [
+    "",
+    "---",
+    "",
+    `## Discovered Issues (${issueLines.length})`,
+    "",
+    ...issueLines,
+    "",
+    "*These issues were logged during builds \u2014 triage them in the next plan.*"
+  ].join("\n");
+}
+function buildModelRecommendationDirective(caps, tierBlock) {
+  if (!isCapabilityEnabled(caps, "modelRecommendation")) return null;
+  return tierBlock;
+}
+function buildVerifyHealthCheckDirective(caps) {
+  if (!isCapabilityEnabled(caps, "verifyHealthCheck")) return null;
+  return `
+
+**Health check:** before you consider the cycle shipped, verify cycle state (plan validity, review coverage, branch hygiene) \u2014 run the \`papi-verify\` skill or a quick \`board_view\` pass.`;
+}
+function buildGestaltPreBuildDirective(caps) {
+  if (!isCapabilityEnabled(caps, "gestaltPreBuild")) return null;
+  return `
+
+**Gestalt pre-build:** on the first task of a multi-task cycle, read every task's BUILD HANDOFF together (shared files, sequencing, module split) before building \u2014 one-time check at cycle start.`;
+}
+function buildBatchBuildRollupDirective(caps) {
+  if (!isCapabilityEnabled(caps, "batchBuildRollup")) return null;
+  return `
+
+**Batch rollup:** after the final task of a batch, emit a cycle-level rollup \u2014 build summary table + discovered issues grouped by severity + next action.`;
+}
+function buildSecurityScanDirective(caps) {
+  if (!isCapabilityEnabled(caps, "securityScan")) return null;
+  return `
+
+**Security scan:** risk-tier changes (auth, data, migrations, secrets, endpoints) should carry a security pass \u2014 OWASP top-10 + secret-exposure check on the changed surface before merge.`;
+}
+function buildDeployHookDirective(caps, deployCommand) {
+  if (!isCapabilityEnabled(caps, "deployHook")) return null;
+  const command = deployCommand?.trim() || void 0;
+  if (!command) return null;
+  return `
+
+---
+
+## Deploy \u2014 run after this release
+
+The post-release deploy hook is on and a deploy command is configured, so ship the merged release now.
+
+Run your deploy command yourself:
+\`\`\`
+${command}
+\`\`\`
+PAPI never runs this command itself (AD-58) \u2014 you run it in your own environment. Turn the "Post-release deploy" capability off in the dashboard, or unset PAPI_DEPLOY, to stop this reminder.`;
+}
+
 // src/services/build.ts
 import { randomUUID as randomUUID11 } from "crypto";
 import { readdirSync as readdirSync5, existsSync as existsSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync2, unlinkSync, mkdirSync as mkdirSync2 } from "fs";
@@ -18658,7 +18874,8 @@ To override, pass force=true (emits a telemetry warning).`
       if (adapter2.getBuildReportsSince) {
         try {
           const cycleReports = (await adapter2.getBuildReportsSince(currentCycle)).filter((r) => r.cycle === currentCycle);
-          [snapshot] = computeSnapshotsFromBuildReports(cycleReports);
+          const cycleTasks = (await adapter2.queryBoard({ cycleSince: currentCycle, compact: true })).filter((t) => t.cycle === currentCycle);
+          [snapshot] = computeSnapshotsFromBuildReports(cycleReports, cycleTasks);
         } catch (err) {
           console.error(
             `[release] cycle-metrics snapshot compute failed for cycle ${currentCycle} (non-blocking): ${err instanceof Error ? err.message : String(err)}`
@@ -18998,6 +19215,65 @@ async function updatePluginMarketplaces(version) {
   return [cursor, vscode].filter((r) => r !== null);
 }
 
+// src/lib/release-gate.ts
+function evaluateReleaseGate(caps, gateCommand, gateResult) {
+  const command = gateCommand?.trim() || void 0;
+  if (!isCapabilityEnabled(caps, "releaseGate")) {
+    return {
+      action: "proceed",
+      stepStatus: "complete",
+      metadata: { skipped: true, reason: "capability_off" },
+      message: ""
+    };
+  }
+  if (!command) {
+    return {
+      action: "proceed",
+      stepStatus: "complete",
+      metadata: { note: "no gate configured" },
+      message: ""
+    };
+  }
+  if (gateResult === "fail") {
+    return {
+      action: "block",
+      stepStatus: "failed",
+      metadata: { command },
+      message: `Release blocked \u2014 quality gate failed.
+
+The gate command \`${command}\` reported a failure, so PAPI did NOT tag, merge, or close the cycle.
+
+Fix the failing tests/build, re-run \`${command}\`, and call \`release\` again with \`gate_result: "pass"\` once it is green. To ship past a failing gate anyway, turn the "Release quality gate" capability off in the dashboard, or unset PAPI_GATE.`
+    };
+  }
+  if (gateResult === "pass") {
+    return {
+      action: "proceed",
+      stepStatus: "complete",
+      metadata: { command },
+      message: ""
+    };
+  }
+  return {
+    action: "directive",
+    stepStatus: "active",
+    metadata: { command },
+    message: `## Quality gate \u2014 run before this release ships
+
+PAPI's release quality gate is on and a gate command is configured, so the release is HELD until the gate passes. Nothing has been tagged, merged, or closed yet.
+
+1. Run the gate command yourself:
+   \`\`\`
+   ${command}
+   \`\`\`
+2. Re-call \`release\` with the same \`branch\` and \`version\`, adding:
+   - \`gate_result: "pass"\` if it succeeded \u2014 the release then proceeds normally.
+   - \`gate_result: "fail"\` if it failed \u2014 the release stays blocked so you can fix it first.
+
+PAPI never runs this command itself (AD-58) \u2014 you run it in your own environment and report the result.`
+  };
+}
+
 // src/tools/release.ts
 function parseGithubOwner(input) {
   if (!input) return null;
@@ -19078,6 +19354,11 @@ var releaseTool = {
         type: "boolean",
         description: "Update CHANGELOG.md and mark the cycle complete, but skip creating a git tag and pushing it. Use when you want cycle closure and changelog tracking without burning a version number. The version parameter is still used for the CHANGELOG entry heading."
       },
+      gate_result: {
+        type: "string",
+        enum: ["pass", "fail"],
+        description: 'task-2482 (release quality gate): the result of running the configured gate command (papi.gate / PAPI_GATE). Set this on the SECOND release call AFTER you have run the gate command yourself \u2014 "pass" lets the release proceed, "fail" keeps it blocked. Leave it UNSET on the first call: if the release-quality-gate capability is on and a gate command is configured, release returns a directive telling you to run the command, then re-call with the result. PAPI never runs the command itself (AD-58).'
+      },
       observations: {
         type: "array",
         description: "Optional dogfood observations from this cycle to persist to the DB. Each entry records friction, methodology signals, or commercial insights.",
@@ -19108,6 +19389,7 @@ async function handleRelease(adapter2, config2, args) {
   let version = args.version;
   const force = args.force;
   const skipVersion = args.skipVersion;
+  const gateResult = args.gate_result;
   const rawObservations = args.observations;
   if (!branch || !version) {
     return errorResponse('both branch and version are required. Example: release branch="main" version="v0.1.0-alpha"');
@@ -19121,8 +19403,9 @@ async function handleRelease(adapter2, config2, args) {
       version = `${version}-${suffix}`;
     }
   }
-  const tracker = new ProgressTracker("validate-args");
+  const tracker = new ProgressTracker("validate-args").bindStream(adapter2, { stage: "release" });
   try {
+    await tracker.recordStep("release_starting");
     tracker.mark("owner-identity-guard");
     const gate = await resolveOwnerGate(adapter2, config2);
     const productionBaseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
@@ -19249,12 +19532,41 @@ Run \`project_switch <slug>\` to switch the active PAPI project, or verify your
         console.error(`[release] gh CLI not available \u2014 ${pendingGrouped.length} shared branch(es) will be squash-merged via git: ${pendingGrouped.join(", ")}`);
       }
     }
+    await tracker.recordStep("readiness_verified");
+    let caps = {};
+    try {
+      const info = adapter2.getProjectInfo ? await adapter2.getProjectInfo() : null;
+      caps = info?.capabilities ?? {};
+    } catch {
+      caps = {};
+    }
+    tracker.mark("quality-gate");
+    const gateDecision = evaluateReleaseGate(caps, config2.gateCommand, gateResult);
+    await tracker.recordStep("quality_gate", {
+      status: gateDecision.stepStatus,
+      capabilityKey: "releaseGate",
+      capabilityEnabled: isCapabilityEnabled(caps, "releaseGate"),
+      metadata: gateDecision.metadata
+    });
+    if (gateDecision.action === "directive") {
+      return textResponse(gateDecision.message);
+    }
+    if (gateDecision.action === "block") {
+      return errorResponse(gateDecision.message);
+    }
     tracker.mark("create-release");
     const result = await createRelease(config2, branch, version, adapter2, void 0, {
       force: force ?? false,
       skipVersion: skipVersion ?? false,
       callerUserId: gate.callerUserId
     });
+    tracker.setStreamScope({ cycle: result.cycleClosed ?? null });
+    await tracker.recordStep("cycle_complete", { metadata: { version: result.version } });
+    for (const m of result.groupedBranchMerges ?? []) {
+      await tracker.recordStep("branch_merged", {
+        metadata: { branch: m.branch, prUrl: m.prUrl ?? null }
+      });
+    }
     const lines = [
       `## Release ${result.version}${skipVersion ? " (skip version)" : ""}`,
       "",
@@ -19283,10 +19595,8 @@ Run \`project_switch <slug>\` to switch the active PAPI project, or verify your
         const reports = await adapter2.getBuildReportsSince(closedCycle);
         const EMPTY = /* @__PURE__ */ new Set(["None", "none", "N/A", "", "null"]);
         const issues = reports.filter((r) => r.discoveredIssues && !EMPTY.has(r.discoveredIssues.trim())).map((r) => `- **${r.taskId}** (${r.taskName}): ${r.discoveredIssues}`);
-        if (issues.length > 0) {
-          lines.push("", "---", "", `## Discovered Issues (${issues.length})`, "", ...issues);
-          lines.push("", "*These issues were logged during builds \u2014 triage them in the next plan.*");
-        }
+        const issuesDirective = buildDiscoveredIssuesDirective(caps, issues);
+        if (issuesDirective) lines.push(issuesDirective);
       }
     } catch {
     }
@@ -19306,28 +19616,54 @@ Run \`project_switch <slug>\` to switch the active PAPI project, or verify your
         lines.push("", "\u26A0\uFE0F Dogfood observations could not be saved to DB \u2014 log them manually in DOGFOOD_LOG.md.");
       }
     }
-    const cycleUpdateDirective = buildCycleUpdateCurationDirective(result.version, result.cycleClosed ?? 0);
+    const cycleUpdateDirective = buildChangelogDirective(
+      caps,
+      buildCycleUpdateCurationDirective(result.version, result.cycleClosed ?? 0)
+    );
     if (cycleUpdateDirective) lines.push(cycleUpdateDirective);
-    try {
-      const xPosted = await postReleaseToX(result.version, result.cycleClosed ?? 0);
-      if (xPosted) lines.push("", "Posted release announcement to X.");
-    } catch {
+    await tracker.recordStep("changelog", {
+      capabilityKey: "changelog",
+      capabilityEnabled: isCapabilityEnabled(caps, "changelog"),
+      status: cycleUpdateDirective ? "complete" : "active"
+    });
+    const deployDirective = buildDeployHookDirective(caps, config2.deployCommand);
+    if (deployDirective) {
+      lines.push(deployDirective);
+      await tracker.recordStep("deploy_hook", {
+        capabilityKey: "deployHook",
+        capabilityEnabled: isCapabilityEnabled(caps, "deployHook"),
+        status: "complete",
+        metadata: { configured: true }
+      });
     }
-    try {
-      const registryResults = await updateRegistryListings(result.version);
-      for (const r of registryResults) {
-        lines.push("", `Registry [${r.registry}]: ${r.message}`);
+    const publishEnabled = isCapabilityEnabled(caps, "publishDirective");
+    if (publishEnabled) {
+      try {
+        const xPosted = await postReleaseToX(result.version, result.cycleClosed ?? 0);
+        if (xPosted) lines.push("", "Posted release announcement to X.");
+      } catch {
       }
-    } catch {
     }
-    try {
-      const marketplaceResults = await updatePluginMarketplaces(result.version);
-      for (const r of marketplaceResults) {
-        lines.push("", `Marketplace [${r.registry}]: ${r.message}`);
+    if (publishEnabled) {
+      try {
+        const registryResults = await updateRegistryListings(result.version);
+        for (const r of registryResults) {
+          lines.push("", `Registry [${r.registry}]: ${r.message}`);
+        }
+      } catch {
+      }
+      try {
+        const marketplaceResults = await updatePluginMarketplaces(result.version);
+        for (const r of marketplaceResults) {
+          lines.push("", `Marketplace [${r.registry}]: ${r.message}`);
+        }
+      } catch {
       }
-    } catch {
     }
+    const verifyDirective = buildVerifyHealthCheckDirective(caps);
+    if (verifyDirective) lines.push(verifyDirective);
     lines.push("", `Next: cycle released! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`);
+    await tracker.recordStep("released", { metadata: { version: result.version } });
     const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
     return textResponse(lines.join("\n") + filesToWriteSection);
   } catch (err) {
@@ -19775,6 +20111,9 @@ async function describeTask(adapter2, taskId) {
   }
   return { task };
 }
+function shouldBlockDirtyBranchSwitch(opts) {
+  return opts.trackedDirtyCount > 0 && opts.currentBranch !== opts.baseBranch && opts.currentBranch !== opts.featureBranch;
+}
 async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   const task = await adapter2.getTask(taskId);
   if (!task) {
@@ -19896,11 +20235,11 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
         branchLines.push(`Base branch '${config2.baseBranch}' not found \u2014 using '${baseBranch}'.`);
       }
       const trackedDirty = getTrackedModifiedFiles(config2.projectRoot);
-      if (trackedDirty.length > 0 && currentBranch !== baseBranch) {
+      if (shouldBlockDirtyBranchSwitch({ trackedDirtyCount: trackedDirty.length, currentBranch, baseBranch, featureBranch })) {
         const shown = trackedDirty.slice(0, 5).join(", ");
         const more = trackedDirty.length > 5 ? ` (+${trackedDirty.length - 5} more)` : "";
         throw new Error(
-          `build_execute won't switch branches: the working tree has uncommitted changes on '${currentBranch}' (this task targets '${featureBranch}'). Another session may be working there, and switching would revert those files. Commit or stash them first, or run build_execute from '${baseBranch}'. Dirty: ${shown}${more}.`
+          `build_execute won't switch branches: the working tree has uncommitted changes on '${currentBranch}' (this task targets '${featureBranch}'). Another session may be working there, and switching would revert those files. Commit or stash them first, run build_execute from '${baseBranch}', or check out '${featureBranch}' if this is your own in-progress work. Dirty: ${shown}${more}.`
         );
       }
       if (hasUncommittedChanges(config2.projectRoot, AUTO_WRITTEN_PATHS)) {
@@ -20073,7 +20412,8 @@ function extractDocMeta(absolutePath, relativePath, cycleNumber) {
   }
   return { title, type, cycle, summary, tags: [] };
 }
-function assertDeployVerification(config2, input) {
+function assertDeployVerification(config2, input, opts = { deployingNow: true }) {
+  if (!opts.deployingNow) return;
   if (config2.adapterType !== "pg" && config2.adapterType !== "proxy") return;
   let triggerHits = [];
   try {
@@ -20082,32 +20422,43 @@ function assertDeployVerification(config2, input) {
     return;
   }
   if (triggerHits.length === 0) return;
+  const mergeDeployHits = triggerHits.filter((p) => !isDeployAtReleaseSurface(p));
+  if (mergeDeployHits.length === 0) return;
   const verification = input.productionVerification;
   if (!verification) {
-    throw new Error(
-      `Deploy-verification required: this branch's diff touches ${triggerHits.length} trigger-surface file(s):
-` + triggerHits.map((p) => `  - ${p}`).join("\n") + `
+    const targetLine = config2.verifyCommand ? `
 
-Run a curl against the live deploy and pass production_verification on build_execute complete:
+Verify against your configured target (papi.verify): \`${config2.verifyCommand}\`
+Run it yourself, then pass production_verification on build_execute complete:
   { urls, curl_command, http_status, response_excerpt, verified_at }
+` : `
 
-Trigger surface is enforced because changes here have historically shipped to prod undetected (C166, C264-C265, C271).`
+Run a curl against the live deploy and pass production_verification on build_execute complete:
+  { urls, curl_command, http_status, response_excerpt, verified_at }
+`;
+    throw new Error(
+      `Deploy-verification required: this branch's diff touches ${mergeDeployHits.length} deploy-on-merge trigger-surface file(s):
+` + mergeDeployHits.map((p) => `  - ${p}`).join("\n") + targetLine + `
+Trigger surface is enforced because changes here have historically shipped to prod undetected (C166, C264-C265, C271). Edge/data-proxy diffs (supabase/functions/**) are verified at release instead.`
     );
   }
   if (verification.http_status < 200 || verification.http_status >= 300) {
     throw new Error(
       `Deploy-verification failed: production_verification reports http_status=${verification.http_status} on a trigger-surface task.
-Trigger files touched: ${triggerHits.join(", ")}
+Trigger files touched: ${mergeDeployHits.join(", ")}
 Fix the deploy first, then re-run build_execute complete with a 2xx verification.`
     );
   }
 }
+function isDeployAtReleaseSurface(path7) {
+  return path7.startsWith("supabase/functions/");
+}
 async function completeBuild(adapter2, config2, taskId, input, options = {}, clientName) {
   const task = await adapter2.getTask(taskId);
   if (!task) {
     throw new Error(`Task "${taskId}" not found on the Cycle Board.`);
   }
-  assertDeployVerification(config2, input);
+  assertDeployVerification(config2, input, { deployingNow: options.light === true });
   const [healthResult, priorCount] = await Promise.all([
     adapter2.getCycleHealth().catch(() => ({ totalCycles: 0 })),
     typeof adapter2.getBuildReportCountForTask === "function" ? adapter2.getBuildReportCountForTask(taskId).catch(() => 0) : Promise.resolve(0)
@@ -21304,13 +21655,17 @@ async function handleBuildExecute(adapter2, config2, args, clientName) {
   if (hasReportFields(args)) {
     return handleExecuteComplete(adapter2, config2, taskId, args, light, clientName);
   }
-  const tracker = new ProgressTracker("start_build");
+  const tracker = new ProgressTracker("start_build").bindStream(adapter2, { stage: "build", taskId });
   try {
+    await tracker.recordStep("started");
     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");
     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") : "";
     const projectInfo = adapter2.getProjectInfo ? await adapter2.getProjectInfo().catch(() => null) : null;
+    const caps = projectInfo?.capabilities ?? {};
     const projectBanner = projectInfo ? getProjectConnectionBanner(projectInfo.name, projectInfo.slug) : null;
     const projectLine = projectBanner ? `> ${projectBanner}
 
@@ -21358,8 +21713,12 @@ ${entries}`;
     const moduleInstructions = getModuleInstructions(result.task.module);
     const moduleContext = await getModuleContext(adapter2, result.task);
     const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
-    const modelNote = formatModelRecommendation(result.task.buildHandoff?.effort ?? result.task.complexity);
-    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + modelNote + adSection + moduleInstructions + moduleContext + dogfoodSection + verificationNote + chainInstruction + phaseNote + filesToWriteSection);
+    const modelNote = buildModelRecommendationDirective(
+      caps,
+      formatModelRecommendation(result.task.buildHandoff?.effort ?? result.task.complexity)
+    ) ?? "";
+    const gestaltNote = buildGestaltPreBuildDirective(caps) ?? "";
+    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + modelNote + gestaltNote + adSection + moduleInstructions + moduleContext + dogfoodSection + verificationNote + chainInstruction + phaseNote + filesToWriteSection);
   } catch (err) {
     if (isNoHandoffError(err)) {
       const lines = [
@@ -21446,7 +21805,7 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
   if (!parsedEstimatedEffort) {
     return errorResponse(`Invalid estimated_effort value "${estimatedEffort}". Must be one of: XS, S, M, L, XL.`);
   }
-  const tracker = new ProgressTracker("complete_validate");
+  const tracker = new ProgressTracker("complete_validate").bindStream(adapter2, { stage: "build", taskId });
   try {
     tracker.mark("complete_build");
     const result = await completeBuild(adapter2, config2, taskId, {
@@ -21475,6 +21834,11 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
       preview
     }, { light }, clientName);
     tracker.mark("complete_format");
+    tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.cycleNumber });
+    await tracker.recordStep("report_written");
+    await tracker.recordStep("issues_triaged", {
+      metadata: { autoTriagedCount: result.autoTriagedCount ?? 0 }
+    });
     if (resolvesLearnings && resolvesLearnings.length > 0 && adapter2.updateCycleLearningActionRef) {
       for (const learningId of resolvesLearnings) {
         try {
@@ -21483,8 +21847,35 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
         }
       }
     }
+    await tracker.recordStep("learnings", {
+      metadata: { learningsLinkedCount: result.learningsLinkedCount ?? 0 }
+    });
+    await tracker.recordStep("moving-to-review", {
+      metadata: { status: result.task.status }
+    });
+    if (productionVerification) {
+      await tracker.recordStep("verify", {
+        stage: "release",
+        status: "complete",
+        metadata: {
+          httpStatus: productionVerification.http_status,
+          urlCount: productionVerification.urls.length,
+          targetConfigured: Boolean(config2.verifyCommand)
+        }
+      });
+    }
     const docsNote = await detectUnregisteredDocsNote(adapter2, config2);
-    return textResponse(formatCompleteResult(result) + docsNote);
+    let batchRollupNote = "";
+    if (result.cycleProgress && result.cycleProgress.completed >= result.cycleProgress.total) {
+      try {
+        const info = adapter2.getProjectInfo ? await adapter2.getProjectInfo() : null;
+        const caps = info?.capabilities ?? {};
+        batchRollupNote = buildBatchBuildRollupDirective(caps) ?? "";
+      } catch {
+        batchRollupNote = "";
+      }
+    }
+    return textResponse(formatCompleteResult(result) + docsNote + batchRollupNote);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (isBuildPushError(err)) {
@@ -21853,7 +22244,7 @@ function collectDiagnostics(config2) {
 }
 var bugTool = {
   name: "bug",
-  description: 'Report a bug OR submit an idea. Routing: a bug about PAPI itself (a PAPI tool/MCP error, the connector, a handoff/cycle problem) auto-submits UPSTREAM to PAPI maintainers with diagnostics \u2014 you do NOT need to set report=true for these. A bug in the user\'s OWN project auto-files as a Backlog task on their board. Override the routing explicitly: report=true forces upstream, report=false forces the user\'s own board. Set `type` ("bug"/"idea") and optional notify-when-fixed / contact-ok consent for upstream submissions. Does not call the Anthropic API.',
+  description: `Report a bug OR submit an idea. Routing: a bug about PAPI itself (a PAPI tool/MCP error, the connector, a handoff/cycle problem) auto-submits UPSTREAM to PAPI maintainers with diagnostics \u2014 you do NOT need to set report=true for these. A bug in the user's OWN project auto-files as a Backlog task on their board. IMPORTANT: report=true is ONLY for a genuine PAPI-product defect \u2014 it is NOT the catch-all for "not about my app". A bug in the user's harness/editor/OS/git/other tooling (e.g. Claude Code, Codex, VS Code, a shell command) is NOT a PAPI bug: file it on the user's own board (report=false / default) or that tool's own tracker, never upstream. Override the routing explicitly: report=true forces upstream (PAPI-product only), report=false forces the user's own board. Set \`type\` ("bug"/"idea") and optional notify-when-fixed / contact-ok consent for upstream submissions. Does not call the Anthropic API.`,
   annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
@@ -21885,7 +22276,7 @@ var bugTool = {
       },
       report: {
         type: "boolean",
-        description: "Routing override. Leave UNSET to auto-route: PAPI-product bugs go upstream to maintainers, project-domain bugs go to the user's board. Set true to force an upstream diagnostic submission; set false to force a task on the user's own board (use false when an auto-detected PAPI bug is actually about the user's project)."
+        description: "Routing override. Leave UNSET to auto-route: PAPI-product bugs go upstream to maintainers, project-domain bugs go to the user's board. Set true ONLY for a genuine PAPI-product defect (PAPI tool/MCP/connector/handoff) \u2014 a bug in the user's harness/editor/OS/other tooling is NOT a PAPI bug and must go to their own board (report=false or default), not upstream. Set false to force a task on the user's own board (use false when an auto-detected PAPI bug is actually about the user's project, harness, or environment)."
       },
       type: {
         type: "string",
@@ -21902,7 +22293,7 @@ var bugTool = {
       },
       project: {
         type: "string",
-        description: "Project id (UUID) or slug to file this bug under, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default."
+        description: "BOARD MODE ONLY. Project id (UUID) or slug to file this bug under, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. It CANNOT redirect an upstream (report=true) submission \u2014 those always go to PAPI maintainers. Use project_switch to change the session default."
       }
     },
     required: ["text"]
@@ -22020,6 +22411,12 @@ init_git();
 
 // src/services/ad-hoc.ts
 import { randomUUID as randomUUID14 } from "crypto";
+function resolveAdHocCycle(cycle, latest, latestComplete) {
+  if (cycle === void 0) return null;
+  if (typeof cycle === "number") return cycle;
+  if (cycle === "current") return latest;
+  return latestComplete ? latest + 1 : latest;
+}
 async function recordAdHoc(adapter2, input) {
   const [health, phases] = await Promise.all([
     adapter2.getCycleHealth(),
@@ -22027,6 +22424,14 @@ async function recordAdHoc(adapter2, input) {
   ]);
   const cycle = health.totalCycles;
   const now = /* @__PURE__ */ new Date();
+  const held = input.hold === true;
+  const targetCycle = held ? cycle + 1 : resolveAdHocCycle(
+    input.cycle,
+    health.totalCycles,
+    health.latestCycleStatus === "complete"
+  );
+  const promoted = targetCycle !== null;
+  const landInReview = held || promoted && input.stage === "release";
   let task;
   if (input.taskId) {
     const existing = await adapter2.getTask(input.taskId);
@@ -22048,18 +22453,19 @@ async function recordAdHoc(adapter2, input) {
       uuid: randomUUID14(),
       displayId: "",
       title: input.title,
-      status: "Done",
+      status: landInReview ? "In Review" : "Done",
       priority: input.priority || "P2 Medium",
       complexity: input.effort === "XS" || input.effort === "S" ? "Small" : "Medium",
       module: input.module || "Core",
       epic: input.epic || "Platform",
       phase,
       owner: input.owner || "Cathal",
-      reviewed: true,
+      reviewed: !landInReview,
       createdCycle: cycle,
+      ...targetCycle !== null ? { cycle: targetCycle } : {},
       notes: input.notes ? `[ad-hoc] ${input.notes}` : "[ad-hoc]",
       taskType: input.taskType || "task",
-      source: "owner"
+      source: "ad_hoc"
     });
   }
   const report = {
@@ -22134,6 +22540,22 @@ var adHocTool = {
         type: "string",
         enum: ["task", "bug", "research", "discovery", "spike", "idea"],
         description: 'Task type (default: inferred from description \u2014 "fix"/"bug" \u2192 bug, "research"/"investigate" \u2192 research, otherwise task).'
+      },
+      cycle: {
+        description: 'task-2352: promote this ad-hoc work into a cycle so it shows on the hub and is counted as INJECTED work (distinct from planned). Omit for the default behaviour (an immediate Done task with no cycle). "current" = the active cycle; "next-if-plan-not-run" = the next cycle if the latest already shipped (so between-cycle work is not lost), else current; or an explicit cycle number.',
+        oneOf: [
+          { type: "string", enum: ["current", "next-if-plan-not-run"] },
+          { type: "integer" }
+        ]
+      },
+      stage: {
+        type: "string",
+        enum: ["done", "release"],
+        description: 'task-2352: where promoted work lands. "done" (default) records it as Done + reviewed. "release" lands it In Review so it is reviewed and released WITH the cycle (fold-in) instead of being force-completed. Only meaningful with `cycle`.'
+      },
+      hold: {
+        type: "boolean",
+        description: "task-2477: held-adhoc. When true, do NOT force-complete or commit to main \u2014 record the task In Review pinned to the NEXT cycle (current + 1) so the planner won't re-plan it, and return a branch/PR directive (commit on feat/<task-id>, never main, leave unmerged) so it rides the next cycle's review \u2192 release bundled with planned work. One-call replacement for the two-call ad_hoc + board_edit stopgap. Takes precedence over `cycle`/`stage`."
       }
     },
     required: []
@@ -22164,6 +22586,12 @@ async function handleAdHoc(adapter2, config2, args) {
     rawNotes = rawNotes.slice(0, MAX_NOTES_LENGTH);
     notesTruncated = true;
   }
+  const rawCycle = args.cycle;
+  let cycleArg;
+  if (typeof rawCycle === "number") cycleArg = rawCycle;
+  else if (rawCycle === "current" || rawCycle === "next-if-plan-not-run") cycleArg = rawCycle;
+  const stageArg = args.stage === "release" ? "release" : void 0;
+  const holdArg = args.hold === true;
   const result = await recordAdHoc(adapter2, {
     title: title || "",
     taskId,
@@ -22174,9 +22602,12 @@ async function handleAdHoc(adapter2, config2, args) {
     priority: priorityRaw,
     taskType: typeRaw,
     // PROJECT-SPECIFIC: owner resolved from config (PAPI_OWNER env var, default 'Cathal')
-    owner: config2.projectOwner
+    owner: config2.projectOwner,
+    cycle: cycleArg,
+    stage: stageArg,
+    hold: holdArg
   });
-  if (isGitAvailable() && isGitRepo(config2.projectRoot)) {
+  if (!holdArg && isGitAvailable() && isGitRepo(config2.projectRoot)) {
     try {
       stageDirAndCommit(
         config2.projectRoot,
@@ -22189,8 +22620,29 @@ async function handleAdHoc(adapter2, config2, args) {
   const truncateWarning = notesTruncated ? ` (notes truncated to ${MAX_NOTES_LENGTH} chars)` : "";
   const taskModule = result.task.module || "Core";
   const typeLabel = result.task.taskType || typeRaw;
+  const promoNote = result.task.cycle != null ? ` Promoted into Cycle ${result.task.cycle} as injected work${result.task.status === "In Review" ? " (In Review \u2014 will release with the cycle)" : ""}.` : "";
+  if (holdArg) {
+    const branch = `feat/${result.task.id}`;
+    return textResponse(
+      `**${result.task.id}:** "${result.task.title}" held for review (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule}).${truncateWarning}${promoNote} Build report attached.
+
+## Held for the next cycle \u2014 branch + commit, do NOT merge
+The task is recorded **In Review** and pinned to **Cycle ${result.task.cycle}**, so the planner won't re-plan it and it rides that cycle's review \u2192 release bundled with planned work.
+
+1. Create a branch and commit your code there (never \`main\`):
+   \`\`\`
+   git switch -c ${branch}
+   git add -- <your changed files>
+   git commit -m "feat(${result.task.id}): ${result.task.title}"
+   git push -u origin ${branch}
+   \`\`\`
+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._`
+    );
+  }
   return textResponse(
-    `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule}).${truncateWarning} Build report attached.
+    `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule}).${truncateWarning}${promoNote} Build report attached.
 _To correct: board_edit ${result.task.id} with updated fields._`
   );
 }
@@ -23285,13 +23737,22 @@ async function handleReviewSubmit(adapter2, config2, args) {
   if (!stage) {
     return errorResponse('stage is required. Use "handoff-review" or "build-acceptance".');
   }
+  let caps = {};
+  try {
+    const info = adapter2.getProjectInfo ? await adapter2.getProjectInfo() : null;
+    caps = info?.capabilities ?? {};
+  } catch {
+    caps = {};
+  }
   const explicitDispatch = args.dispatch === "subagent";
-  const autoDispatchEligible = !verdict && args.dispatch !== "inline" && process.env.PAPI_AUTO_DISPATCH !== "false";
-  if ((explicitDispatch || autoDispatchEligible) && stage === "build-acceptance" && taskId) {
+  const autoDispatchOptIn = args.dispatch !== "inline" && process.env.PAPI_AUTO_DISPATCH !== "false" && isCapabilityEnabled(caps, "prReviewer");
+  const autoDispatchEligible = !verdict && autoDispatchOptIn;
+  const capabilityAutoReviewEligible = verdict === "accept" && !autoReview && autoDispatchOptIn;
+  if ((explicitDispatch || autoDispatchEligible || capabilityAutoReviewEligible) && stage === "build-acceptance" && taskId) {
     const dispatch = await buildReviewDispatch(adapter2, config2, taskId);
     if (!dispatch.ok) {
       if (explicitDispatch) return errorResponse(dispatch.error);
-    } else if (explicitDispatch || dispatch.contextBytes > REVIEW_DISPATCH_THRESHOLD) {
+    } else if (explicitDispatch || capabilityAutoReviewEligible || dispatch.contextBytes > REVIEW_DISPATCH_THRESHOLD) {
       return textResponse(dispatch.prompt);
     }
   }
@@ -23332,7 +23793,8 @@ async function handleReviewSubmit(adapter2, config2, args) {
       }
     }
   }
-  const tracker = new ProgressTracker("validate-args");
+  const tracker = new ProgressTracker("validate-args").bindStream(adapter2, { stage: "review", taskId });
+  await tracker.recordStep("reviewer_confirmed");
   const handoffRegenResponse = args.handoff_regen_response;
   if (handoffRegenResponse?.trim()) {
     tracker.mark("apply-handoff-regen");
@@ -23349,6 +23811,14 @@ async function handleReviewSubmit(adapter2, config2, args) {
       adapter2,
       { taskId, stage, verdict, comments, reviewer, autoReview }
     );
+    tracker.setStreamScope({ cycle: result.currentCycle > 0 ? result.currentCycle : null });
+    await tracker.recordStep("verdict_recorded", { metadata: { verdict, stage } });
+    if (result.unblockedTasks.length > 0) {
+      await tracker.recordStep("dependents_unblocked", { metadata: { count: result.unblockedTasks.length } });
+    }
+    if (result.closedDocActions.length > 0) {
+      await tracker.recordStep("docs_closed", { metadata: { count: result.closedDocActions.length } });
+    }
     const statusNote = result.newStatus ? ` Task status updated to **${result.newStatus}**.` : " Task status unchanged.";
     const unblockNote = result.unblockedTasks.length > 0 ? `
 
@@ -23388,6 +23858,7 @@ ${result.handoffRegenPrompt.userMessage}
 
 > ${mergeResult.message}`;
         }
+        await tracker.recordStep("deferred", { metadata: { reason: "merge-skipped" } });
       } else if (!mergeResult.merged) {
         mergeFailed = true;
         let revertNote = "";
@@ -23402,11 +23873,13 @@ ${result.handoffRegenPrompt.userMessage}
 \u26A0\uFE0F **PR merge failed \u2014 task NOT marked Done.**${revertNote}
 
 ${mergeResult.message}`;
+        await tracker.recordStep("deferred", { status: "failed", metadata: { reason: "merge-failed" } });
       } else {
         try {
           await adapter2.updateTask(taskId, { mergedAt: (/* @__PURE__ */ new Date()).toISOString() });
         } catch {
         }
+        await tracker.recordStep("merged");
         const detailLines = mergeResult.details.map((l) => `> ${l}`).join("\n");
         mergeNote = `
 
@@ -23482,6 +23955,7 @@ Merge or squash those PRs first, then run \`release\` manually.`;
             }
             const version = `v0.${result.currentCycle}.0`;
             const releaseResult = await createRelease(config2, baseBranch, version, adapter2, result.currentCycle);
+            await tracker.recordStep("auto_release_triggered", { metadata: { version: releaseResult.version } });
             const pushInfo = releaseResult.pushNotes.join(" ");
             const groupedMergeNote = releaseResult.groupedBranchMerges?.length ? "\n" + releaseResult.groupedBranchMerges.map((r) => `- Merged shared branch \`${r.branch}\` via PR: ${r.prUrl ?? "n/a"}`).join("\n") : "";
             autoReleaseNote = `
@@ -23537,9 +24011,7 @@ ${findingLines}${more}` : "");
 \u26A0\uFE0F **Override recorded:** ${reviewer} accepted past a ${autoReview.verdict} quality gate (${autoReview.findings.length} finding${autoReview.findings.length === 1 ? "" : "s"}). The verdict + findings are stored on this review for the audit trail.`;
       }
     } else if (stage === "build-acceptance" && verdict === "accept") {
-      autoReviewNote = `
-
-**Quality Gate:** no auto-review attached. PAPI's standard pre-accept step is a code review of the branch diff \u2014 run \`review_submit\` with \`dispatch:"subagent"\` to auto-review, or attach \`auto_review\` findings. Risk-tier work (auth, data, migrations, CI) should always carry one.`;
+      autoReviewNote = buildPrReviewerDirective(caps) ?? "";
     }
     let nextStepNote = "";
     if (!autoReleaseNote && stage === "build-acceptance") {
@@ -23551,6 +24023,7 @@ ${findingLines}${more}` : "");
 Next: address the feedback, then run \`build_execute ${taskId}\` to resubmit.`;
       }
     }
+    const securityNote = stage === "build-acceptance" && verdict === "accept" ? buildSecurityScanDirective(caps) ?? "" : "";
     tracker.mark("format-response");
     return textResponse(
       `**${result.stageLabel}** recorded for ${result.taskId}.
@@ -23558,7 +24031,7 @@ Next: address the feedback, then run \`build_execute ${taskId}\` to resubmit.`;
 - **Verdict:** ${result.verdict}
 - **Comments:** ${result.comments}
 
-${statusNote}${autoReviewNote}${unblockNote}${docClosureNote}${regenNote}${mergeNote}${overlapNote}${batchSummaryNote}${autoReleaseNote}${nextStepNote}${phaseNote}`
+${statusNote}${autoReviewNote}${securityNote}${unblockNote}${docClosureNote}${regenNote}${mergeNote}${overlapNote}${batchSummaryNote}${autoReleaseNote}${nextStepNote}${phaseNote}`
     );
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -24274,7 +24747,12 @@ async function getHealthSummary(adapter2) {
   try {
     try {
       buildReports = await adapter2.getRecentBuildReports(50);
-      snapshots = computeSnapshotsFromBuildReports(buildReports);
+      let metricsTasks = [];
+      try {
+        metricsTasks = await adapter2.queryBoard({ cycleSince: Math.max(1, cycleNumber - 6), compact: true });
+      } catch {
+      }
+      snapshots = computeSnapshotsFromBuildReports(buildReports, metricsTasks);
     } catch {
     }
     metricsSection = formatCycleMetrics(snapshots);