@bridge_gpt/mcp-server 0.2.21 → 0.2.23

package/build/index.js

@@ -19,7 +19,7 @@ var VERSION;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    VERSION = "0.2.21";
+    VERSION = "0.2.23";
   }
 });
 
@@ -523,6 +523,357 @@ function defaultTempSuffix() {
   tempSuffixCounter += 1;
   return `${process.pid}.${tempSuffixCounter}`;
 }
+function getCredentialStoreLockPath(deps) {
+  return `${getPrimaryCredentialStorePath(deps)}.lock`;
+}
+async function acquireCredentialStoreLock(deps) {
+  const open3 = deps.open;
+  if (!open3) return { ok: true, release: async () => {
+  } };
+  const lockPath = getCredentialStoreLockPath(deps);
+  const isPosix = deps.platform !== "win32";
+  const now = deps.now ?? (() => Date.now());
+  const sleep3 = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const release = async () => {
+    if (!deps.unlink) return;
+    try {
+      await deps.unlink(lockPath);
+    } catch {
+    }
+  };
+  const tryAcquire = async () => {
+    try {
+      const handle = await open3(lockPath, "wx", isPosix ? 384 : void 0);
+      await handle.close();
+      return { ok: true };
+    } catch (err) {
+      const code = err && typeof err === "object" ? err.code : void 0;
+      return { ok: false, contended: code === "EEXIST" };
+    }
+  };
+  try {
+    await deps.mkdir(path6.dirname(lockPath), { recursive: true });
+  } catch {
+    return { ok: false, error: `Unable to prepare the credentials directory for ${lockPath}.` };
+  }
+  const deadline = now() + LOCK_TIMEOUT_MS;
+  for (; ; ) {
+    const attempt = await tryAcquire();
+    if (attempt.ok) return { ok: true, release };
+    if (!attempt.contended) {
+      return { ok: false, error: `Unable to acquire the credentials lock at ${lockPath}.` };
+    }
+    if (now() >= deadline) break;
+    await sleep3(LOCK_POLL_INTERVAL_MS);
+  }
+  await release();
+  const stolen = await tryAcquire();
+  if (stolen.ok) return { ok: true, release };
+  return {
+    ok: false,
+    error: `Timed out waiting for the credentials lock at ${lockPath} (another install may be running).`
+  };
+}
+async function withCredentialStoreLock(deps, fn, onLockError) {
+  const lock = await acquireCredentialStoreLock(deps);
+  if (!lock.ok) return onLockError(lock.error);
+  try {
+    return await fn();
+  } finally {
+    await lock.release();
+  }
+}
+async function durablyReplaceCredentialStoreJson(primaryPath, value, deps) {
+  const open3 = deps.open;
+  if (!open3) {
+    return {
+      ok: false,
+      kind: "durable-unavailable",
+      error: `Cannot durably write ${primaryPath}: no file-handle primitive is available to fsync the write.`
+    };
+  }
+  const dir = path6.dirname(primaryPath);
+  const suffix = (deps.tempSuffix ?? defaultTempSuffix)();
+  const tempPath = path6.join(dir, `${path6.basename(primaryPath)}.${suffix}.tmp`);
+  const json = formatCredentialStoreJson(value);
+  const isPosix = deps.platform !== "win32";
+  let handle;
+  try {
+    await deps.mkdir(dir, { recursive: true });
+    handle = await open3(tempPath, "w", isPosix ? 384 : void 0);
+    await handle.writeFile(json, { encoding: "utf-8" });
+    await handle.sync();
+    await handle.close();
+    handle = void 0;
+    if (isPosix) await deps.chmod(tempPath, 384);
+    await deps.rename(tempPath, primaryPath);
+  } catch {
+    if (handle) {
+      try {
+        await handle.close();
+      } catch {
+      }
+    }
+    if (deps.unlink) {
+      try {
+        await deps.unlink(tempPath);
+      } catch {
+      }
+    }
+    return {
+      ok: false,
+      kind: "write-error",
+      error: `Failed to durably write the credentials file at ${primaryPath}.`
+    };
+  }
+  try {
+    const dirHandle = await open3(dir, "r");
+    try {
+      await dirHandle.sync();
+    } finally {
+      await dirHandle.close();
+    }
+  } catch {
+  }
+  return { ok: true };
+}
+function getBootstrapPendingTarget(repoName) {
+  return `${BOOTSTRAP_PENDING_TARGET_PREFIX}${(repoName ?? "").trim()}`;
+}
+function getBapiTarget(repoName) {
+  return `bapi:${(repoName ?? "").trim()}`;
+}
+async function loadStoreForMutation(deps) {
+  const primaryPath = getPrimaryCredentialStorePath(deps);
+  const primary = await readCredentialStoreJsonIfPresent(primaryPath, deps);
+  if (primary.state === "error") {
+    return { ok: false, kind: primary.kind, error: primary.error };
+  }
+  if (primary.state === "present") {
+    return { ok: true, base: { ...primary.value } };
+  }
+  const seeded = await mergeFallbackCredentialStoreOnFirstPrimaryWrite(deps);
+  return { ok: true, base: seeded.base };
+}
+function hasExistingBapiKey(store, repoName) {
+  const entry = store[getBapiTarget(repoName)];
+  return !!entry && typeof entry.BAPI_API_KEY === "string" && entry.BAPI_API_KEY.trim().length > 0;
+}
+function readMatchingPending(store, repoName, inviteFingerprint) {
+  const entry = store[getBootstrapPendingTarget(repoName)];
+  if (!entry) return null;
+  const secret = entry[BOOTSTRAP_PENDING_SECRET_FIELD];
+  const fingerprint = entry[BOOTSTRAP_PENDING_FINGERPRINT_FIELD];
+  if (typeof secret !== "string" || secret.trim().length === 0) return null;
+  if (fingerprint !== inviteFingerprint) return null;
+  return { keySecret: secret };
+}
+function hasConflictingPending(store, repoName, inviteFingerprint) {
+  const entry = store[getBootstrapPendingTarget(repoName)];
+  if (!entry) return false;
+  const secret = entry[BOOTSTRAP_PENDING_SECRET_FIELD];
+  if (typeof secret !== "string" || secret.trim().length === 0) return false;
+  return entry[BOOTSTRAP_PENDING_FINGERPRINT_FIELD] !== inviteFingerprint;
+}
+function pendingConflictError(target, primaryPath) {
+  return `A pending bootstrap-invite credential for a DIFFERENT invite already exists at ${target} in ${primaryPath}. It is the only proof that can replay that redemption, so it will not be overwritten. Complete that redemption first, or \u2014 only if you are certain its invite was never exchanged \u2014 remove the entry from the store by hand.`;
+}
+async function prepareBootstrapPendingCredential(params, deps) {
+  const primaryPath = getPrimaryCredentialStorePath(deps);
+  const repoName = (params.repoName ?? "").trim();
+  const fingerprint = (params.inviteFingerprint ?? "").trim();
+  const target = getBootstrapPendingTarget(repoName);
+  if (repoName.length === 0) {
+    return {
+      ok: false,
+      path: primaryPath,
+      target,
+      kind: "invalid-repo",
+      error: "Cannot prepare a bootstrap-invite credential: a non-empty repo name is required."
+    };
+  }
+  if (fingerprint.length === 0) {
+    return {
+      ok: false,
+      path: primaryPath,
+      target,
+      kind: "invalid-fingerprint",
+      error: "Cannot prepare a bootstrap-invite credential: the invite fingerprint was empty."
+    };
+  }
+  return withCredentialStoreLock(
+    deps,
+    async () => {
+      const loaded = await loadStoreForMutation(deps);
+      if (!loaded.ok) {
+        return { ok: false, path: primaryPath, target, kind: loaded.kind, error: loaded.error };
+      }
+      const base = loaded.base;
+      if (hasExistingBapiKey(base, repoName) && !params.allowOverwriteExistingCredential) {
+        return {
+          ok: false,
+          path: primaryPath,
+          target: getBapiTarget(repoName),
+          kind: "credential-conflict",
+          error: `A credential already exists for ${getBapiTarget(repoName)} in ${primaryPath}.`
+        };
+      }
+      const existing = readMatchingPending(base, repoName, fingerprint);
+      if (existing) {
+        return { ok: true, path: primaryPath, target, keySecret: existing.keySecret, reused: true };
+      }
+      if (hasConflictingPending(base, repoName, fingerprint)) {
+        return {
+          ok: false,
+          path: primaryPath,
+          target,
+          kind: "pending-conflict",
+          error: pendingConflictError(target, primaryPath)
+        };
+      }
+      const keySecret = params.generateKeySecret();
+      const next = {
+        ...base,
+        [target]: {
+          ...base[target] ?? {},
+          [BOOTSTRAP_PENDING_SECRET_FIELD]: keySecret,
+          [BOOTSTRAP_PENDING_FINGERPRINT_FIELD]: fingerprint
+        }
+      };
+      const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
+      if (!written.ok) {
+        return { ok: false, path: primaryPath, target, kind: written.kind, error: written.error };
+      }
+      return { ok: true, path: primaryPath, target, keySecret, reused: false };
+    },
+    (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error })
+  );
+}
+async function repointBootstrapPendingCredential(params, deps) {
+  const primaryPath = getPrimaryCredentialStorePath(deps);
+  const fromRepo = (params.fromRepoName ?? "").trim();
+  const toRepo = (params.toRepoName ?? "").trim();
+  const fingerprint = (params.inviteFingerprint ?? "").trim();
+  const target = getBootstrapPendingTarget(toRepo);
+  if (fromRepo.length === 0 || toRepo.length === 0) {
+    return {
+      ok: false,
+      path: primaryPath,
+      target,
+      kind: "invalid-repo",
+      error: "Cannot re-point a bootstrap-invite credential: a non-empty repo name is required."
+    };
+  }
+  return withCredentialStoreLock(
+    deps,
+    async () => {
+      const loaded = await loadStoreForMutation(deps);
+      if (!loaded.ok) {
+        return { ok: false, path: primaryPath, target, kind: loaded.kind, error: loaded.error };
+      }
+      const base = loaded.base;
+      const pending = readMatchingPending(base, fromRepo, fingerprint);
+      if (!pending) {
+        return {
+          ok: false,
+          path: primaryPath,
+          target,
+          kind: "pending-missing",
+          error: `No pending bootstrap-invite credential for ${getBootstrapPendingTarget(fromRepo)} in ${primaryPath}.`
+        };
+      }
+      if (toRepo === fromRepo) {
+        return { ok: true, path: primaryPath, target, keySecret: pending.keySecret };
+      }
+      if (hasExistingBapiKey(base, toRepo) && !params.allowOverwriteExistingCredential) {
+        return {
+          ok: false,
+          path: primaryPath,
+          target: getBapiTarget(toRepo),
+          kind: "credential-conflict",
+          error: `A credential already exists for ${getBapiTarget(toRepo)} in ${primaryPath}.`
+        };
+      }
+      const destination = base[getBootstrapPendingTarget(toRepo)];
+      if (hasConflictingPending(base, toRepo, fingerprint)) {
+        return {
+          ok: false,
+          path: primaryPath,
+          target,
+          kind: "pending-conflict",
+          error: pendingConflictError(target, primaryPath)
+        };
+      }
+      const next = { ...base };
+      delete next[getBootstrapPendingTarget(fromRepo)];
+      next[target] = {
+        ...destination ?? {},
+        [BOOTSTRAP_PENDING_SECRET_FIELD]: pending.keySecret,
+        [BOOTSTRAP_PENDING_FINGERPRINT_FIELD]: fingerprint
+      };
+      const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
+      if (!written.ok) {
+        return { ok: false, path: primaryPath, target, kind: written.kind, error: written.error };
+      }
+      return { ok: true, path: primaryPath, target, keySecret: pending.keySecret };
+    },
+    (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error })
+  );
+}
+async function promoteBootstrapPendingCredential(params, deps) {
+  const primaryPath = getPrimaryCredentialStorePath(deps);
+  const repoName = (params.repoName ?? "").trim();
+  const fingerprint = (params.inviteFingerprint ?? "").trim();
+  const target = getBapiTarget(repoName);
+  if (repoName.length === 0) {
+    return {
+      ok: false,
+      path: primaryPath,
+      target,
+      kind: "invalid-repo",
+      error: "Cannot promote a bootstrap-invite credential: a non-empty repo name is required."
+    };
+  }
+  return withCredentialStoreLock(
+    deps,
+    async () => {
+      const loaded = await loadStoreForMutation(deps);
+      if (!loaded.ok) {
+        return { ok: false, path: primaryPath, target, kind: loaded.kind, error: loaded.error };
+      }
+      const base = loaded.base;
+      const pending = readMatchingPending(base, repoName, fingerprint);
+      if (!pending) {
+        return {
+          ok: false,
+          path: primaryPath,
+          target,
+          kind: "pending-missing",
+          error: `No pending bootstrap-invite credential for ${getBootstrapPendingTarget(repoName)} in ${primaryPath}.`
+        };
+      }
+      const hadKey = hasExistingBapiKey(base, repoName);
+      if (hadKey && !params.allowOverwriteExistingCredential) {
+        return {
+          ok: false,
+          path: primaryPath,
+          target,
+          kind: "credential-conflict",
+          error: `A credential already exists for ${target} in ${primaryPath}.`
+        };
+      }
+      const next = { ...base };
+      delete next[getBootstrapPendingTarget(repoName)];
+      next[target] = { ...base[target] ?? {}, BAPI_API_KEY: pending.keySecret };
+      const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
+      if (!written.ok) {
+        return { ok: false, path: primaryPath, target, kind: written.kind, error: written.error };
+      }
+      return { ok: true, path: primaryPath, target, action: hadKey ? "updated" : "created" };
+    },
+    (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error })
+  );
+}
 async function upsertBapiCredential(repoName, apiKey, deps) {
   const primaryPath = getPrimaryCredentialStorePath(deps);
   const trimmedRepo = (repoName ?? "").trim();
@@ -546,59 +897,70 @@ async function upsertBapiCredential(repoName, apiKey, deps) {
       error: `Cannot store BAPI_API_KEY for ${target}: the provided key was empty.`
     };
   }
-  const primary = await readCredentialStoreJsonIfPresent(primaryPath, deps);
-  let base;
-  let migratedFallback = false;
-  if (primary.state === "error") {
-    return { ok: false, path: primaryPath, target, kind: primary.kind, error: primary.error };
-  }
-  if (primary.state === "present") {
-    base = { ...primary.value };
-  } else {
-    const seeded = await mergeFallbackCredentialStoreOnFirstPrimaryWrite(deps);
-    base = seeded.base;
-    migratedFallback = seeded.migratedFallback;
-  }
-  const existingEntry = base[target];
-  const hadKey = !!existingEntry && typeof existingEntry.BAPI_API_KEY === "string" && existingEntry.BAPI_API_KEY.length > 0;
-  const action = hadKey ? "updated" : "created";
-  const nextEntry = { ...existingEntry ?? {}, BAPI_API_KEY: trimmedKey };
-  const next = { ...base, [target]: nextEntry };
-  const dir = path6.dirname(primaryPath);
-  const suffix = (deps.tempSuffix ?? defaultTempSuffix)();
-  const tempPath = path6.join(dir, `${path6.basename(primaryPath)}.${suffix}.tmp`);
-  const json = formatCredentialStoreJson(next);
-  const isPosix = deps.platform !== "win32";
-  try {
-    await deps.mkdir(dir, { recursive: true });
-    const writeOptions = isPosix ? { encoding: "utf-8", mode: 384 } : { encoding: "utf-8" };
-    await deps.writeFile(tempPath, json, writeOptions);
-    if (isPosix) {
-      await deps.chmod(tempPath, 384);
-    }
-    await deps.rename(tempPath, primaryPath);
-  } catch {
-    if (deps.unlink) {
+  return withCredentialStoreLock(
+    deps,
+    async () => {
+      const primary = await readCredentialStoreJsonIfPresent(primaryPath, deps);
+      let base;
+      let migratedFallback = false;
+      if (primary.state === "error") {
+        return { ok: false, path: primaryPath, target, kind: primary.kind, error: primary.error };
+      }
+      if (primary.state === "present") {
+        base = { ...primary.value };
+      } else {
+        const seeded = await mergeFallbackCredentialStoreOnFirstPrimaryWrite(deps);
+        base = seeded.base;
+        migratedFallback = seeded.migratedFallback;
+      }
+      const existingEntry = base[target];
+      const hadKey = !!existingEntry && typeof existingEntry.BAPI_API_KEY === "string" && existingEntry.BAPI_API_KEY.length > 0;
+      const action = hadKey ? "updated" : "created";
+      const nextEntry = { ...existingEntry ?? {}, BAPI_API_KEY: trimmedKey };
+      const next = { ...base, [target]: nextEntry };
+      const dir = path6.dirname(primaryPath);
+      const suffix = (deps.tempSuffix ?? defaultTempSuffix)();
+      const tempPath = path6.join(dir, `${path6.basename(primaryPath)}.${suffix}.tmp`);
+      const json = formatCredentialStoreJson(next);
+      const isPosix = deps.platform !== "win32";
       try {
-        await deps.unlink(tempPath);
+        await deps.mkdir(dir, { recursive: true });
+        const writeOptions = isPosix ? { encoding: "utf-8", mode: 384 } : { encoding: "utf-8" };
+        await deps.writeFile(tempPath, json, writeOptions);
+        if (isPosix) {
+          await deps.chmod(tempPath, 384);
+        }
+        await deps.rename(tempPath, primaryPath);
       } catch {
+        if (deps.unlink) {
+          try {
+            await deps.unlink(tempPath);
+          } catch {
+          }
+        }
+        return {
+          ok: false,
+          path: primaryPath,
+          target,
+          kind: "write-error",
+          error: `Failed to write credentials file at ${primaryPath}.`
+        };
       }
-    }
-    return {
-      ok: false,
-      path: primaryPath,
-      target,
-      kind: "write-error",
-      error: `Failed to write credentials file at ${primaryPath}.`
-    };
-  }
-  return { ok: true, path: primaryPath, target, action, migratedFallback };
+      return { ok: true, path: primaryPath, target, action, migratedFallback };
+    },
+    (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error })
+  );
 }
-var tempSuffixCounter;
+var tempSuffixCounter, LOCK_POLL_INTERVAL_MS, LOCK_TIMEOUT_MS, BOOTSTRAP_PENDING_TARGET_PREFIX, BOOTSTRAP_PENDING_SECRET_FIELD, BOOTSTRAP_PENDING_FINGERPRINT_FIELD;
 var init_credential_store = __esm({
   "src/credential-store.ts"() {
     "use strict";
     tempSuffixCounter = 0;
+    LOCK_POLL_INTERVAL_MS = 50;
+    LOCK_TIMEOUT_MS = 5e3;
+    BOOTSTRAP_PENDING_TARGET_PREFIX = "bootstrap-pending:";
+    BOOTSTRAP_PENDING_SECRET_FIELD = "BAPI_API_KEY";
+    BOOTSTRAP_PENDING_FINGERPRINT_FIELD = "BOOTSTRAP_INVITE_FINGERPRINT";
   }
 });
 
@@ -3766,6 +4128,7 @@ __export(bridge_api_client_exports, {
   buildConductorVcsUrl: () => buildConductorVcsUrl,
   buildEpicDispatchKey: () => buildEpicDispatchKey,
   claimEpicSupervisionLease: () => claimEpicSupervisionLease,
+  createEpicRun: () => createEpicRun,
   createEpicTicketStatus: () => createEpicTicketStatus,
   deletePullRequestBranch: () => deletePullRequestBranch,
   extractSanitizedErrorDiagnostics: () => extractSanitizedErrorDiagnostics,
@@ -3802,7 +4165,7 @@ async function resolveConductorBridgeApiAccess(deps = {}) {
   const platform = deps.platform ?? process.platform;
   const readFileImpl = deps.readFile ?? ((p) => readFile4(p, "utf-8"));
   const statImpl = deps.stat ?? ((p) => stat2(p));
-  const repoName = await resolveStartTicketsRepoName({ env, cwd, readFile: readFileImpl });
+  const repoName = deps.repoName?.trim() || await resolveStartTicketsRepoName({ env, cwd, readFile: readFileImpl });
   if (!repoName) {
     return {
       ok: false,
@@ -4010,8 +4373,8 @@ async function fetchPrReviewStatus(access2, prNumber, fetchImpl = globalThis.fet
 }
 function buildConductorVcsUrl(baseUrl, apiPath) {
   const trimmed = baseUrl.replace(/\/+$/, "");
-  const path33 = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
-  return new URL(`${trimmed}${path33}`).toString();
+  const path34 = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
+  return new URL(`${trimmed}${path34}`).toString();
 }
 function conductorPostHeaders(access2) {
   return { "X-API-Key": access2.apiKey, "Content-Type": "application/json" };
@@ -4232,6 +4595,31 @@ async function fetchActiveEpicRuns(access2, fetchImpl = globalThis.fetch) {
   }
   return [];
 }
+async function createEpicRun(access2, request, fetchImpl = globalThis.fetch) {
+  requireNonEmptyString(request.epicKey);
+  const body = {
+    repo_name: access2.repoName,
+    epic_key: request.epicKey,
+    status: request.status ?? "planning",
+    current_plan_version: request.currentPlanVersion ?? 0
+  };
+  if (request.policyJson !== void 0) body.policy_json = request.policyJson;
+  if (request.budgetWallClockSeconds !== void 0) {
+    body.budget_wall_clock_seconds = request.budgetWallClockSeconds;
+  }
+  if (request.budgetCostCents !== void 0) {
+    body.budget_cost_cents = request.budgetCostCents;
+  }
+  const url = buildConductorJiraUrl(access2.baseUrl, `${EPIC_RUNS_API_PREFIX}/runs`);
+  const parsed = await fetchConductorJsonPostWithTimeout(
+    url,
+    conductorPostHeaders(access2),
+    JSON.stringify(body),
+    CONDUCTOR_FETCH_TIMEOUT_MS,
+    fetchImpl
+  );
+  return parsed;
+}
 async function updateEpicRunStatus(access2, request, fetchImpl = globalThis.fetch) {
   requireNonEmptyString(request.epicKey);
   const url = buildConductorJiraUrl(access2.baseUrl, epicRunApiPath(request.epicKey));
@@ -4392,8 +4780,8 @@ async function transitionEpicDispatch(access2, request, fetchImpl = globalThis.f
   if (request.nextStatus === "run_spawned") {
     requireNonEmptyString(request.runId);
   }
-  const path33 = epicDispatchTransitionApiPath(request.dispatchKey, request.nextStatus);
-  const url = buildConductorJiraUrl(access2.baseUrl, path33);
+  const path34 = epicDispatchTransitionApiPath(request.dispatchKey, request.nextStatus);
+  const url = buildConductorJiraUrl(access2.baseUrl, path34);
   const body = request.nextStatus === "run_spawned" ? JSON.stringify({ repo_name: access2.repoName, run_id: request.runId }) : JSON.stringify({ repo_name: access2.repoName });
   const parsed = await fetchConductorJsonPostWithTimeout(
     url,
@@ -4454,6 +4842,10 @@ async function approveEpicPlan(access2, request, fetchImpl = globalThis.fetch) {
     return parsed;
   } catch (error) {
     if (error instanceof ConductorBridgeApiError && error.status === 409) {
+      const preview = error.bodyPreview ?? "";
+      if (/multiple active runs/i.test(preview)) {
+        return { ok: false, kind: "conflict", reason: "multiple_active_runs" };
+      }
       return { ok: false, kind: "conflict", reason: "superseded" };
     }
     throw error;
@@ -4629,6 +5021,18 @@ var init_bridge_api_client = __esm({
   }
 });
 
+// src/pr-base-contract.ts
+function buildPrBaseContractLaunchInstruction() {
+  return 'PR base contract: when you open the pull request for this ticket you MUST run gh pr create --base "$BAPI_BASE_BRANCH" so the PR targets the run base branch. Do not infer the base from the current branch ancestry or from the repository default branch. If a pull request for this branch already exists, verify that its base equals $BAPI_BASE_BRANCH and report the mismatch rather than retargeting the PR or rebuilding the branch yourself.';
+}
+var PR_BASE_BRANCH_ENV_VAR;
+var init_pr_base_contract = __esm({
+  "src/pr-base-contract.ts"() {
+    "use strict";
+    PR_BASE_BRANCH_ENV_VAR = "BAPI_BASE_BRANCH";
+  }
+});
+
 // src/worktree-core.ts
 import path13 from "path";
 function resolveBranchForTicket(key, overrides) {
@@ -4702,6 +5106,39 @@ async function isExistingBranchSafeToReuse(deps, branch, baseStartPoint) {
     reason: `existing branch '${branch}' is not an ancestor of ${baseRef}; it carries commits not on the resolved base (likely a leftover from a prior run). Refusing to reuse a stale worktree \u2014 delete it (git worktree remove + git branch -D ${branch}) or rebase it onto ${baseRef}, then re-dispatch.`
   };
 }
+async function hardResetWorktree(deps, worktreePath, ref) {
+  const resetArgs = ["reset", "--hard", ref];
+  const reset = await deps.runCommand("git", resetArgs, { cwd: worktreePath });
+  if (!commandSucceeded(reset)) {
+    const reason = (reset.stderr || reset.stdout || "").trim();
+    return `git ${resetArgs.join(" ")} failed${reason ? `: ${reason}` : ""}`;
+  }
+  return null;
+}
+async function verifyWorktreeHead(deps, worktreePath, expected) {
+  const headRes = await deps.runCommand(
+    "git",
+    ["rev-parse", "--verify", "HEAD^{commit}"],
+    { cwd: worktreePath }
+  );
+  if (!commandSucceeded(headRes)) {
+    return "failed to resolve worktree HEAD after creation (git rev-parse HEAD^{commit} failed).";
+  }
+  const expectedRes = await deps.runCommand(
+    "git",
+    ["rev-parse", "--verify", `${expected}^{commit}`],
+    { cwd: worktreePath }
+  );
+  if (!commandSucceeded(expectedRes)) {
+    return "failed to resolve the expected base commit after creation (git rev-parse --verify failed).";
+  }
+  const head = headRes.stdout.trim();
+  const want = expectedRes.stdout.trim();
+  if (head !== want) {
+    return `worktree head ${head.slice(0, 12)} does not match the pinned base ${want.slice(0, 12)}; Worktrunk seeded the worktree from an unexpected start point. Refusing to hand a mis-seeded worktree to a worker.`;
+  }
+  return null;
+}
 async function createWorktreeForTicket(deps, key, branchOverrides, worktrunkBinary, baseStartPoint = "main", guardStaleWorktree = false, behavior = {}) {
   const branch = resolveBranchForTicket(key, branchOverrides);
   try {
@@ -4730,16 +5167,21 @@ async function createWorktreeForTicket(deps, key, branchOverrides, worktrunkBina
     }
     const worktreePath = extractWorktreePath(result.stdout, deps.cwd, deps.platform);
     if (exists && behavior.freshenFromOrigin) {
-      const resetArgs = ["reset", "--hard", behavior.freshenFromOrigin];
-      const reset = await deps.runCommand("git", resetArgs, { cwd: worktreePath });
-      if (!commandSucceeded(reset)) {
-        const reason = (reset.stderr || reset.stdout || "").trim();
-        return {
-          key,
-          branch,
-          status: "create-failed",
-          error: `git ${resetArgs.join(" ")} failed${reason ? `: ${reason}` : ""}`
-        };
+      const resetError = await hardResetWorktree(deps, worktreePath, behavior.freshenFromOrigin);
+      if (resetError) {
+        return { key, branch, status: "create-failed", error: resetError };
+      }
+    }
+    if (exists && behavior.alignExistingBranchTo) {
+      const resetError = await hardResetWorktree(deps, worktreePath, behavior.alignExistingBranchTo);
+      if (resetError) {
+        return { key, branch, status: "create-failed", error: resetError };
+      }
+    }
+    if (behavior.verifyHeadMatches) {
+      const verifyError = await verifyWorktreeHead(deps, worktreePath, behavior.verifyHeadMatches);
+      if (verifyError) {
+        return { key, branch, status: "create-failed", error: verifyError };
       }
     }
     return { key, branch, status: "created", path: worktreePath };
@@ -4755,11 +5197,88 @@ var init_worktree_core = __esm({
   }
 });
 
+// src/base-ref.ts
+import path14 from "path";
+function validateBranchName(branch) {
+  if (branch.trim().length === 0) return "branch name must not be empty.";
+  if (branch.length > 255) return "branch name must be 255 characters or fewer.";
+  if (branch.startsWith("-")) return "branch name must not start with '-'.";
+  if (branch.includes("..")) return "branch name must not contain '..'.";
+  if (branch.endsWith(".lock")) return "branch name must not end with '.lock'.";
+  for (let i = 0; i < branch.length; i++) {
+    const code = branch.charCodeAt(i);
+    if (code <= 31 || code === 127) {
+      return "branch name must not contain control characters.";
+    }
+  }
+  return null;
+}
+function normalizeRepoKey(cwd) {
+  return path14.resolve(cwd);
+}
+async function withRepoFetchLock(repoKey, fn) {
+  const previous = repoFetchLocks.get(repoKey) ?? Promise.resolve();
+  let releaseCurrent;
+  const current = new Promise((resolve2) => {
+    releaseCurrent = resolve2;
+  });
+  const chained = previous.then(() => current);
+  repoFetchLocks.set(repoKey, chained);
+  await previous.catch(() => {
+  });
+  try {
+    return await fn();
+  } finally {
+    releaseCurrent();
+    if (repoFetchLocks.get(repoKey) === chained) {
+      repoFetchLocks.delete(repoKey);
+    }
+  }
+}
+async function fetchAndResolveBaseSha(deps, baseBranch) {
+  const validationError = validateBranchName(baseBranch);
+  if (validationError) {
+    return { ok: false, error: `Invalid base branch '${baseBranch}': ${validationError}` };
+  }
+  const repoKey = normalizeRepoKey(deps.cwd);
+  return withRepoFetchLock(repoKey, async () => {
+    const fetch2 = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
+      cwd: deps.cwd
+    });
+    if (!commandSucceeded(fetch2)) {
+      return {
+        ok: false,
+        error: `git fetch origin ${baseBranch} failed. Check your network and 'git remote get-url origin', or pass --no-refresh-base to skip.`
+      };
+    }
+    const resolve2 = await deps.runCommand(
+      "git",
+      ["rev-parse", "--verify", `origin/${baseBranch}^{commit}`],
+      { cwd: deps.cwd }
+    );
+    if (!commandSucceeded(resolve2)) {
+      return {
+        ok: false,
+        error: `Failed to resolve origin/${baseBranch} to a commit SHA after fetch (git rev-parse --verify failed).`
+      };
+    }
+    return { ok: true, base_sha: resolve2.stdout.trim() };
+  });
+}
+var repoFetchLocks;
+var init_base_ref = __esm({
+  "src/base-ref.ts"() {
+    "use strict";
+    init_start_tickets_prereqs();
+    repoFetchLocks = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/start-tickets.ts
 import { execFile } from "child_process";
 import { readFile as readFile5, writeFile as writeFile3, mkdir as mkdir3, mkdtemp, stat as stat3, readdir as readdir2, rm } from "fs/promises";
 import os4 from "node:os";
-import path14 from "path";
+import path15 from "path";
 import { existsSync as existsSync2 } from "node:fs";
 function appendSummaryRowWarning(row, warning) {
   return { ...row, warnings: [...row.warnings ?? [], warning] };
@@ -4771,6 +5290,8 @@ function getStartTicketsUsage() {
     "",
     "Flags:",
     "  --agent claude|cursor-agent Agent command to launch in each worktree (default: claude)",
+    "  --workflow implement|review-and-implement  Slash command each spawned worktree runs (default: implement). review-and-implement runs /review-ticket then, after a per-ticket halt gate, /implement-ticket in the same session; --auto applies to the selected workflow.",
+    "  --rounds 1|2                Review round count forwarded to the review phase; review-only, valid only with --workflow review-and-implement",
     "  --terminal terminal|iterm   Override the macOS terminal app (default: auto-detect via $TERM_PROGRAM); honored on macOS only",
     "  --dry-run                   Print intended actions; creates no worktrees and opens no tabs, but DOES resolve model routing read-only (may compute+cache a ticket's difficulty) to preview the --model each tab would use",
     "  --branch KEY=BRANCH         Use BRANCH instead of feature/KEY for that ticket (repeatable)",
@@ -4816,11 +5337,13 @@ function parseStartTicketsArgs(argv) {
   let agentName = DEFAULT_AGENT_NAME;
   let baseBranch = "main";
   let conductorEnabled = false;
+  let workflow = "implement";
+  let reviewRoundsRaw;
   const branchEntries = [];
   const keys = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    const takeValue2 = () => {
+    const takeValue3 = () => {
       if (i + 1 >= argv.length) return void 0;
       i += 1;
       return argv[i];
@@ -4830,7 +5353,7 @@ function parseStartTicketsArgs(argv) {
       if (arg.startsWith("--agent=")) {
         value = arg.slice("--agent=".length);
       } else {
-        value = takeValue2();
+        value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--agent requires a value (an agent name)." };
         }
@@ -4844,12 +5367,53 @@ function parseStartTicketsArgs(argv) {
       agentName = value;
       continue;
     }
+    if (arg === "--workflow" || arg.startsWith("--workflow=")) {
+      let value;
+      if (arg.startsWith("--workflow=")) {
+        value = arg.slice("--workflow=".length);
+      } else {
+        value = takeValue3();
+        if (value === void 0) {
+          return {
+            status: "error",
+            message: "--workflow requires a value (allowed values: implement, review-and-implement)."
+          };
+        }
+      }
+      if (value !== "implement" && value !== "review-and-implement") {
+        return {
+          status: "error",
+          message: `Invalid --workflow value: '${value}' (allowed values: implement, review-and-implement).`
+        };
+      }
+      workflow = value;
+      continue;
+    }
+    if (arg === "--rounds" || arg.startsWith("--rounds=")) {
+      let value;
+      if (arg.startsWith("--rounds=")) {
+        value = arg.slice("--rounds=".length);
+      } else {
+        value = takeValue3();
+        if (value === void 0) {
+          return { status: "error", message: "--rounds requires a value (allowed values: 1, 2)." };
+        }
+      }
+      if (value !== "1" && value !== "2") {
+        return {
+          status: "error",
+          message: `Invalid --rounds value: '${value}' (allowed values: 1, 2).`
+        };
+      }
+      reviewRoundsRaw = value;
+      continue;
+    }
     if (arg === "--terminal" || arg.startsWith("--terminal=")) {
       let value;
       if (arg.startsWith("--terminal=")) {
         value = arg.slice("--terminal=".length);
       } else {
-        value = takeValue2();
+        value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--terminal requires a value (terminal or iterm)." };
         }
@@ -4867,7 +5431,7 @@ function parseStartTicketsArgs(argv) {
       if (arg.startsWith("--max-parallel=")) {
         maxParallelRaw = arg.slice("--max-parallel=".length);
       } else {
-        const value = takeValue2();
+        const value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--max-parallel requires a positive integer value." };
         }
@@ -4880,7 +5444,7 @@ function parseStartTicketsArgs(argv) {
       if (arg.startsWith("--branch=")) {
         value = arg.slice("--branch=".length);
       } else {
-        value = takeValue2();
+        value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--branch requires a KEY=BRANCH value." };
         }
@@ -4897,7 +5461,7 @@ function parseStartTicketsArgs(argv) {
         if (next === void 0 || next.startsWith("-")) {
           return { status: "error", message: "--base-branch requires a value (a branch name)." };
         }
-        value = takeValue2();
+        value = takeValue3();
       }
       const trimmed = (value ?? "").trim();
       const error = validateBranchName(trimmed);
@@ -4989,22 +5553,33 @@ function parseStartTicketsArgs(argv) {
     }
     branchOverrides[overrideKey] = branchName;
   }
+  let reviewRounds;
+  if (reviewRoundsRaw !== void 0) {
+    if (workflow !== "review-and-implement") {
+      return {
+        status: "error",
+        message: "--rounds is only valid with --workflow review-and-implement."
+      };
+    }
+    reviewRounds = reviewRoundsRaw === "1" ? 1 : 2;
+  }
   return {
     status: "ok",
-    options: { keys, terminal, dryRun, autoApprove, refreshMain, maxParallel, branchOverrides, agentName, baseBranch, conductorEnabled }
-  };
-}
-function validateBranchName(branch) {
-  if (branch.trim().length === 0) return "branch name must not be empty.";
-  if (branch.length > 255) return "branch name must be 255 characters or fewer.";
-  if (branch.startsWith("-")) return "branch name must not start with '-'.";
-  for (let i = 0; i < branch.length; i++) {
-    const code = branch.charCodeAt(i);
-    if (code <= 31 || code === 127) {
-      return "branch name must not contain control characters.";
+    options: {
+      keys,
+      terminal,
+      dryRun,
+      autoApprove,
+      refreshMain,
+      maxParallel,
+      branchOverrides,
+      agentName,
+      baseBranch,
+      conductorEnabled,
+      workflow,
+      reviewRounds
     }
-  }
-  return null;
+  };
 }
 function detectTerminal(explicit, env) {
   if (explicit) return explicit;
@@ -5024,21 +5599,27 @@ function getDefaultSpawnTerminalTabForPlatform(platform) {
       return spawnUnsupportedPlatformTerminalTab;
   }
 }
-function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = false, conductorEnabled = false, repoName = null, resumeMode = false) {
+function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = false, conductorEnabled = false, repoName = null, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
   if (!isSupportedStartTicketsPlatform(deps.platform)) {
     return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
   }
   const platform = deps.platform;
+  const prBaseBranch = conductorEnabled ? baseBranch : null;
   return {
     ok: true,
     config: {
       platform,
       worktrunkBinary: resolveWorktrunkBinary(platform, deps.env),
       // Inject the resolved repo identity so the spawned worktree session never
-      // falls back to the basename-derived repo name (the 403 root cause).
-      buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(
-        buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode),
-        repoName,
+      // falls back to the basename-derived repo name (the 403 root cause), and
+      // (BAPI-586) the run base so the conductor worker opens its PR against it.
+      buildAgentShellCommand: (key, worktreePath, modelAlias) => prependBaseBranchEnvAssignment(
+        prependRepoNameEnvAssignment(
+          buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch),
+          repoName,
+          platform
+        ),
+        prBaseBranch,
         platform
       ),
       spawnTerminalTab: deps.spawnTerminalTab
@@ -5052,6 +5633,13 @@ function prependRepoNameEnvAssignment(command, repoName, platform = "darwin") {
   }
   return `export BAPI_REPO_NAME='${shSquoteInner(repoName)}' && ${command}`;
 }
+function prependBaseBranchEnvAssignment(command, baseBranch, platform = "darwin") {
+  if (!baseBranch) return command;
+  if (platform === "win32") {
+    return `$env:${PR_BASE_BRANCH_ENV_VAR} = ${powershellSquote(baseBranch)}; ${command}`;
+  }
+  return `export ${PR_BASE_BRANCH_ENV_VAR}='${shSquoteInner(baseBranch)}' && ${command}`;
+}
 function shSquoteInner(value) {
   return value.replace(/'/g, "'\\''");
 }
@@ -5204,33 +5792,6 @@ async function refreshBaseBranch(deps, options) {
   }
   return { ok: true };
 }
-async function fetchAndResolveBaseSha(deps, baseBranch) {
-  const validationError = validateBranchName(baseBranch);
-  if (validationError) {
-    return { ok: false, error: `Invalid base branch '${baseBranch}': ${validationError}` };
-  }
-  const fetch2 = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
-    cwd: deps.cwd
-  });
-  if (!commandSucceeded(fetch2)) {
-    return {
-      ok: false,
-      error: `git fetch origin ${baseBranch} failed. Check your network and 'git remote get-url origin', or pass --no-refresh-base to skip.`
-    };
-  }
-  const resolve2 = await deps.runCommand(
-    "git",
-    ["rev-parse", "--verify", `origin/${baseBranch}^{commit}`],
-    { cwd: deps.cwd }
-  );
-  if (!commandSucceeded(resolve2)) {
-    return {
-      ok: false,
-      error: `Failed to resolve origin/${baseBranch} to a commit SHA after fetch (git rev-parse --verify failed).`
-    };
-  }
-  return { ok: true, base_sha: resolve2.stdout.trim() };
-}
 async function runWithConcurrency(items, limit, worker) {
   const results = new Array(items.length);
   const effectiveLimit = Math.max(1, Math.floor(limit));
@@ -5252,6 +5813,8 @@ async function runWithConcurrency(items, limit, worker) {
   return results;
 }
 async function createWorktrees(deps, options, worktrunkBinary, baseStartPoint = options.baseBranch) {
+  const exactBase = options.guardStaleWorktree === true && options.nonMutatingBase === true;
+  const behavior = exactBase ? { alignExistingBranchTo: baseStartPoint, verifyHeadMatches: baseStartPoint } : {};
   return runWithConcurrency(
     options.keys,
     options.maxParallel,
@@ -5261,7 +5824,8 @@ async function createWorktrees(deps, options, worktrunkBinary, baseStartPoint =
       options.branchOverrides,
       worktrunkBinary,
       baseStartPoint,
-      options.guardStaleWorktree === true
+      options.guardStaleWorktree === true,
+      behavior
     )
   );
 }
@@ -5303,9 +5867,22 @@ function buildResumeModeRemediationFinalizeInstruction() {
   return "Resume-mode remediation finalize: you were re-dispatched to fix a blocked ticket (a merge conflict, a CI failure, or requested review changes). First rebase against the current base branch and resolve the merge conflicts. A clean textual merge can still break behavior, so inspect for semantic conflicts even when there are no textual conflict markers. Before you push or mark the ticket complete, run the full test suite for the project (the full unit suite, the same gate enforced by the advisory pre-push hook described in CLAUDE.md under the CI cost model and advisory pre-push hook section) and do not rely on targeted subsets as your only verification. Push and mark the ticket complete only after the full suite is green. If you cannot make the full suite pass, report the ticket blocked and escalate rather than pushing a green-looking but broken merge.";
 }
 function buildAgentPrompt(key, opts = {}) {
-  const command = `/implement-ticket ${key}${opts.autoApprove ? " --auto" : ""}`;
+  const workflow = opts.workflow ?? "implement";
+  const head = workflow === "review-and-implement" ? "/review-and-implement" : "/implement-ticket";
+  let command = `${head} ${key}${opts.autoApprove ? " --auto" : ""}`;
+  if (workflow === "review-and-implement") {
+    if (opts.reviewRounds !== void 0) {
+      command += ` --rounds=${opts.reviewRounds}`;
+    }
+    if (opts.baseBranch !== void 0 && opts.baseBranch !== "main") {
+      command += ` --base-branch='${shSquoteInner(opts.baseBranch)}'`;
+    }
+  }
   const parts = [command];
-  if (opts.conductorEnabled) parts.push(buildConductorMessageRelayLaunchInstruction());
+  if (opts.conductorEnabled) {
+    parts.push(buildConductorMessageRelayLaunchInstruction());
+    parts.push(buildPrBaseContractLaunchInstruction());
+  }
   if (opts.resumeMode) parts.push(buildResumeModeRemediationFinalizeInstruction());
   return parts.join(" ");
 }
@@ -5330,27 +5907,27 @@ function buildAgentInvocation(agent, prompt, quote, modelAlias) {
     }
   }
 }
-function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
+function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
   const invocation = buildAgentInvocation(
     agent,
-    buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode }),
+    buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch }),
     (p) => `'${shSquoteInner(p)}'`,
     modelAlias
   );
   return `cd '${shSquoteInner(worktreePath)}' && ${invocation}`;
 }
-function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
+function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
   const invocation = buildAgentInvocation(
     agent,
-    buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode }),
+    buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch }),
     powershellSquote,
     modelAlias
   );
   return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${invocation}`;
 }
-function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
-  if (platform === "win32") return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode);
-  return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode);
+function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
+  if (platform === "win32") return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch);
+  return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch);
 }
 function buildGenericAgentShellCommand(agent, prompt, cwd, platform = "darwin", modelAlias) {
   if (platform === "win32") {
@@ -5559,7 +6136,7 @@ function buildLaunchScriptRunnerCommand(platform, scriptPath) {
 }
 async function pruneStaleLaunchScripts(deps = defaultPruneStaleLaunchScriptsDeps) {
   try {
-    const parent = path14.join(os4.tmpdir(), "bridge-start-tickets");
+    const parent = path15.join(os4.tmpdir(), "bridge-start-tickets");
     let entries;
     try {
       entries = await deps.readdir(parent);
@@ -5569,7 +6146,7 @@ async function pruneStaleLaunchScripts(deps = defaultPruneStaleLaunchScriptsDeps
     const cutoff = deps.now() - STALE_LAUNCH_SCRIPT_MAX_AGE_MS;
     for (const entry of entries) {
       if (!entry.startsWith("w-")) continue;
-      const full = path14.join(parent, entry);
+      const full = path15.join(parent, entry);
       try {
         const info = await deps.stat(full);
         if (info.mtimeMs < cutoff) {
@@ -5627,22 +6204,24 @@ function buildDryRunResults(keys, overrides) {
     status: "dry-run"
   }));
 }
-function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false, conductorEnabled = false, repoName = null) {
+function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false, conductorEnabled = false, repoName = null, workflow = "implement", reviewRounds, baseBranch) {
   return {
     worktrunkBinary: resolveWorktrunkBinary(platform, env),
     // The builder accepts an optional resolved modelAlias; the dry-run caller
     // now passes the previewed tier's alias so `--model` shows in the preview.
     // The resolved repo name (when known) is injected as a BAPI_REPO_NAME prefix
-    // so the dry-run preview matches the real spawn command exactly.
+    // so the dry-run preview matches the real spawn command exactly. Reuses the
+    // same buildAgentShellCommand/buildAgentPrompt path as a real spawn — dry-run
+    // is never special-cased — so the previewed workflow prompt is exact.
     buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(
-      buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled),
+      buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch),
       repoName,
       platform
     )
   };
 }
 function buildDryRunMcpProvisioningLines(worktreePath, platform = process.platform, mcpServerInvocation) {
-  const api = platform === "win32" ? path14.win32 : path14.posix;
+  const api = platform === "win32" ? path15.win32 : path15.posix;
   const mcpJson = api.join(worktreePath, ".mcp.json");
   const cursorJson = api.join(worktreePath, ".cursor", "mcp.json");
   const invocation = mcpServerInvocation ?? {
@@ -5661,14 +6240,17 @@ function buildDryRunMcpProvisioningLines(worktreePath, platform = process.platfo
     `DRY-RUN:     ${shim}`
   ];
 }
-function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null, mcpServerInvocation) {
+function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null, mcpServerInvocation, workflow = "implement", reviewRounds) {
   const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(
     agent,
     platform,
     env,
     autoApprove,
     conductorEnabled,
-    repoName
+    repoName,
+    workflow,
+    reviewRounds,
+    baseBranch
   );
   const wtArgs = buildWtSwitchArgs(branch, false, baseBranch);
   const agentInvocation = build(key, "<worktree-path>", modelAlias);
@@ -6348,7 +6930,12 @@ async function orchestrateStartTickets(deps, options, overrides = {}) {
     options.conductorEnabled ?? false,
     resolvedRepoName,
     // BAPI-494: resume-mode dispatches get the full-suite remediation finalize prompt.
-    options.resumeMode ?? false
+    options.resumeMode ?? false,
+    options.workflow,
+    options.reviewRounds,
+    // BAPI-586: the effective run base (already carries any epic.base_branch
+    // override applied above) so conductor workers get BAPI_BASE_BRANCH.
+    options.baseBranch
   );
   if (!platformConfig.ok) return { ok: false, error: platformConfig.error };
   let effectiveBaseStartPoint = options.baseBranch;
@@ -6489,7 +7076,9 @@ async function runStartTicketsCli(argv, overrides = {}) {
         modelAlias,
         options.conductorEnabled ?? false,
         dryRunRepoName,
-        dryRunMcpInvocation
+        dryRunMcpInvocation,
+        options.workflow,
+        options.reviewRounds
       )) {
         log(line);
       }
@@ -6555,7 +7144,9 @@ var init_start_tickets = __esm({
     init_agent_registry();
     init_start_tickets_conductor();
     init_bridge_api_client();
+    init_pr_base_contract();
     init_worktree_core();
+    init_base_ref();
     TICKET_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
     DEFAULT_MAX_PARALLEL = 3;
     DEFAULT_TMUX_SESSION_PREFIX = "bridge-start-tickets";
@@ -6572,11 +7163,11 @@ var init_start_tickets = __esm({
       key,
       content
     }) => {
-      const parent = path14.join(os4.tmpdir(), "bridge-start-tickets");
+      const parent = path15.join(os4.tmpdir(), "bridge-start-tickets");
       await mkdir3(parent, { recursive: true });
-      const dir = await mkdtemp(path14.join(parent, "w-"));
+      const dir = await mkdtemp(path15.join(parent, "w-"));
       const ext = platform === "win32" ? "ps1" : "sh";
-      const file = path14.join(dir, `launch-${sanitizeKeyForLaunchScript(key)}.${ext}`);
+      const file = path15.join(dir, `launch-${sanitizeKeyForLaunchScript(key)}.${ext}`);
       await writeFile3(file, content, { mode: 384 });
       return file;
     };
@@ -6742,7 +7333,7 @@ function parseReviewTicketsArgs(argv) {
   const rawReviewEntries = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    const takeValue2 = () => {
+    const takeValue3 = () => {
       if (i + 1 >= argv.length) return void 0;
       i += 1;
       return argv[i];
@@ -6768,7 +7359,7 @@ function parseReviewTicketsArgs(argv) {
         if (next === void 0 || next.startsWith("-")) {
           return { status: "error", message: "--base-branch requires a value (a branch name)." };
         }
-        value = takeValue2();
+        value = takeValue3();
       }
       const trimmed = (value ?? "").trim();
       const error = validateBranchName(trimmed);
@@ -6783,7 +7374,7 @@ function parseReviewTicketsArgs(argv) {
       if (arg.startsWith("--rounds=")) {
         value = arg.slice("--rounds=".length);
       } else {
-        value = takeValue2();
+        value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--rounds requires a value (1 or 2)." };
         }
@@ -6801,7 +7392,7 @@ function parseReviewTicketsArgs(argv) {
       if (arg.startsWith("--max-parallel=")) {
         maxParallelRaw = arg.slice("--max-parallel=".length);
       } else {
-        const value = takeValue2();
+        const value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--max-parallel requires a positive integer value." };
         }
@@ -6814,7 +7405,7 @@ function parseReviewTicketsArgs(argv) {
       if (arg.startsWith("--agent=")) {
         value = arg.slice("--agent=".length);
       } else {
-        value = takeValue2();
+        value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--agent requires a value (an agent name)." };
         }
@@ -6833,7 +7424,7 @@ function parseReviewTicketsArgs(argv) {
       if (arg.startsWith("--model=")) {
         value = arg.slice("--model=".length);
       } else {
-        value = takeValue2();
+        value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--model requires a value (a model alias)." };
         }
@@ -6852,7 +7443,7 @@ function parseReviewTicketsArgs(argv) {
       if (arg.startsWith("--review=")) {
         value = arg.slice("--review=".length);
       } else {
-        value = takeValue2();
+        value = takeValue3();
         if (value === void 0) {
           return { status: "error", message: "--review requires a value (KEY=auto,rounds=1)." };
         }
@@ -7265,9 +7856,9 @@ var init_review_tickets = __esm({
 });
 
 // src/scheduler-backends/types.ts
-import path17 from "node:path";
+import path18 from "node:path";
 function pathApiForPlatform2(platform) {
-  return platform === "win32" ? path17.win32 : path17.posix;
+  return platform === "win32" ? path18.win32 : path18.posix;
 }
 var init_types = __esm({
   "src/scheduler-backends/types.ts"() {
@@ -8233,7 +8824,7 @@ var init_schedule_store = __esm({
 
 // src/command-catalog.ts
 import { promises as nodeFs } from "node:fs";
-import path18 from "node:path";
+import path19 from "node:path";
 import { z } from "zod";
 function createDefaultCommandCatalogFsDeps() {
   return {
@@ -8313,11 +8904,11 @@ function parseFrontmatterText(text) {
   return { ok: true, frontmatter: { schedulable, interactive, argumentSchema } };
 }
 function commandsDirForRepo(repoPath, platform) {
-  const pathApi = platform === "win32" ? path18.win32 : path18.posix;
+  const pathApi = platform === "win32" ? path19.win32 : path19.posix;
   return pathApi.join(repoPath, ".claude", "commands");
 }
 async function discoverCommandCatalog(repoPath, platform, fsDeps = createDefaultCommandCatalogFsDeps()) {
-  const pathApi = platform === "win32" ? path18.win32 : path18.posix;
+  const pathApi = platform === "win32" ? path19.win32 : path19.posix;
   const dir = commandsDirForRepo(repoPath, platform);
   let entries;
   try {
@@ -11011,6 +11602,35 @@ var init_local_merge = __esm({
   }
 });
 
+// src/conductor/plan.ts
+function canonicalizePlanDAG(plan) {
+  const nodes = plan.nodes.map((node) => ({
+    ...node,
+    ticket_key: node.ticket_key.trim(),
+    depends_on: [...node.depends_on].map((k) => k.trim()).sort(),
+    ...node.touched_files ? { touched_files: [...node.touched_files].sort() } : {}
+  })).sort((a, b) => a.ticket_key.localeCompare(b.ticket_key));
+  const edges = [...plan.edges].map((e) => ({
+    from: e.from.trim(),
+    to: e.to.trim(),
+    ...e.kind ? { kind: e.kind } : {},
+    ...e.overlap_files ? { overlap_files: [...e.overlap_files].sort() } : {}
+  })).sort((a, b) => {
+    const cmp = a.from.localeCompare(b.from);
+    return cmp !== 0 ? cmp : a.to.localeCompare(b.to);
+  });
+  return { plan_version: plan.plan_version, nodes, edges };
+}
+function hashPlan(plan) {
+  return stableJsonHash(canonicalizePlanDAG(plan));
+}
+var init_plan = __esm({
+  "src/conductor/plan.ts"() {
+    "use strict";
+    init_git_ci_types();
+  }
+});
+
 // src/conductor/done-gate.ts
 function isPlainObject3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -11417,7 +12037,7 @@ var init_done_gate = __esm({
 });
 
 // src/conductor/producer-ledger.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 function makeProducerDedupeKey(dimensions) {
   const canonical = {};
   for (const [key, value] of Object.entries(dimensions)) {
@@ -11426,7 +12046,7 @@ function makeProducerDedupeKey(dimensions) {
   return stableJsonHash(canonical);
 }
 function makeStableProducerEventId(dedupeKey) {
-  const h = createHash3("sha256").update(`conductor-producer:${dedupeKey}`).digest("hex");
+  const h = createHash4("sha256").update(`conductor-producer:${dedupeKey}`).digest("hex");
   return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
 }
 function isDuplicateConstraintError2(error) {
@@ -11775,6 +12395,9 @@ function discoverPrWithGhCli(options = {}, deps = {}) {
   if (typeof record.headRefName === "string" && record.headRefName.trim().length > 0) {
     discovered.head_ref = record.headRefName.trim();
   }
+  if (typeof record.baseRefName === "string" && record.baseRefName.trim().length > 0) {
+    discovered.base_ref = record.baseRefName.trim();
+  }
   if (typeof record.url === "string" && record.url.trim().length > 0) {
     discovered.url = record.url.trim();
   }
@@ -11789,6 +12412,7 @@ function makeBinding(repo, prNumber, headSha, extra = {}) {
   };
   if (extra.url !== void 0) binding.url = extra.url;
   if (extra.head_ref !== void 0) binding.head_ref = extra.head_ref;
+  if (extra.base_ref !== void 0) binding.base_ref = extra.base_ref;
   return binding;
 }
 function resolvePrHeadBinding(input = {}, deps = {}) {
@@ -11831,7 +12455,11 @@ function resolvePrHeadBinding(input = {}, deps = {}) {
   }
   return {
     ok: true,
-    binding: makeBinding(repo, prNumber, localSha, { url: pr.url, head_ref: pr.head_ref })
+    binding: makeBinding(repo, prNumber, localSha, {
+      url: pr.url,
+      head_ref: pr.head_ref,
+      base_ref: pr.base_ref
+    })
   };
 }
 var GH_COMMAND_TIMEOUT_MS, GH_PR_VIEW_ARGS;
@@ -11847,7 +12475,8 @@ var init_pr_discovery = __esm({
       "view",
       "--json",
       // BAPI-494: mergeability fields added to the SAME one-shot call — no new gh process.
-      "number,headRefOid,headRefName,url,state,mergeable,mergeStateStatus"
+      // BAPI-586: baseRefName added to the same call so a wrong-base PR is detectable.
+      "number,headRefOid,headRefName,baseRefName,url,state,mergeable,mergeStateStatus"
     ];
   }
 });
@@ -11927,7 +12556,7 @@ function buildGateMetEventInput(binding, evaluation, runId = null, workerId = nu
 function defaultSleep2(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
-async function observeWithResolved(binding, access2, gateConfig, deps) {
+async function observeWithResolved(binding, access2, gateConfig, deps, expectedBaseBranch) {
   const emitConductorEventFn = deps.emitConductorEvent ?? emitConductorEvent;
   const emitIfNew = deps.emitIfNew ?? ((input, dimensions) => emitConductorEventIfNew(input, dimensions, {
     emitEvent: emitConductorEventFn
@@ -11959,6 +12588,16 @@ async function observeWithResolved(binding, access2, gateConfig, deps) {
     head_sha: binding.head_sha
   });
   result.pr_opened_emitted = prDecision.emitted;
+  const expectedBase = typeof expectedBaseBranch === "string" ? expectedBaseBranch.trim() : "";
+  if (expectedBase) {
+    const observedBase = typeof binding.base_ref === "string" ? binding.base_ref.trim() : "";
+    if (observedBase !== expectedBase) {
+      const actual = observedBase.length > 0 ? observedBase : "(unresolved)";
+      result.gate_met = false;
+      result.reason = `pr-base-mismatch: PR #${binding.pr_number} targets base '${actual}' but the run base is '${expectedBase}'. Rebuild the branch from fresh origin/${expectedBase} and cherry-pick only this ticket's commits; do not retarget the PR base in the GitHub UI.`;
+      return result;
+    }
+  }
   let rawPoll;
   try {
     rawPoll = await pollCi(access2, binding.head_sha);
@@ -12433,7 +13072,7 @@ var init_supervisor_config = __esm({
 });
 
 // src/conductor/supervisor-ledger.ts
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash5 } from "node:crypto";
 function normalizeDimension(value) {
   return (value ?? "").trim().toLowerCase();
 }
@@ -12448,7 +13087,7 @@ function makeSupervisorIdempotencyKey(meta) {
   return parts.join("|");
 }
 function makeSupervisorAssessmentEventId(idempotencyKey) {
-  const h = createHash4("sha256").update(`supervisor.assessment:${idempotencyKey}`).digest("hex");
+  const h = createHash5("sha256").update(`supervisor.assessment:${idempotencyKey}`).digest("hex");
   return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
 }
 function isDuplicateConstraintError3(error) {
@@ -13263,12 +13902,12 @@ var init_event_accessors = __esm({
 });
 
 // src/conductor/merge-ledger.ts
-import { createHash as createHash5 } from "node:crypto";
+import { createHash as createHash6 } from "node:crypto";
 function extractMergeActionIdentityFromGateEvent(event) {
   return getMergeIdentity(event);
 }
 function makeMergeEventId(eventType, actionKey) {
-  const h = createHash5("sha256").update(`${eventType}:${actionKey}`).digest("hex");
+  const h = createHash6("sha256").update(`${eventType}:${actionKey}`).digest("hex");
   return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
 }
 async function lookupMergeEventByActionKey(eventType, actionKey, deps) {
@@ -13751,9 +14390,9 @@ var init_supervisor_runtime = __esm({
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z as z15 } from "zod";
-import { writeFile as writeFile12, mkdir as mkdir12, readFile as readFile13, stat as stat9, rename as rename3, chmod as chmod3, unlink as unlink3, mkdtemp as mkdtemp3, rm as rm3, readdir as readdir3 } from "fs/promises";
-import path32 from "path";
-import os14 from "os";
+import { writeFile as writeFile12, mkdir as mkdir12, readFile as readFile13, stat as stat9, rename as rename3, chmod as chmod3, unlink as unlink3, mkdtemp as mkdtemp3, rm as rm3, readdir as readdir3, open as open2 } from "fs/promises";
+import path33 from "path";
+import os15 from "os";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/pipelines.generated.ts
@@ -14450,7 +15089,7 @@ var INSTRUCTIONS = {
   "duplicate-and-context-scan.md": 'Detect existing Jira tickets that duplicate or relate to this idea before any Jira mutation.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n- Research pack: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-pack.md` (if produced).\n- Pipeline variable `allow_duplicate` controls override behavior (for this run, `allow_duplicate` = `{allow_duplicate}`). Treat the literal string `"true"` as override; any other value (including `"false"`, missing, or empty) is non-override.\n\n## Instructions\n\n> **Orchestrator-directed step.** This agent task is part of the full-automation chain and is authorized to call `get_tickets` as directed below \u2014 performing an orchestrator-directed tool call is not "re-orchestrating".\n\n1. Build at least two Jira search queries from the manifest:\n   - **Title/keyword query**: use the most salient nouns from `idea` and `slug` as title/text keywords. Prefer 2-4 concrete terms over long natural-language sentences. Run via `get_tickets`.\n   - **Stable idea-hash query** (the reliable cross-run dedup): run `get_tickets` with its `labels` parameter set to `bapi-idea-hash-{idea_hash}`. This label is identical for every run of the same idea, so it catches a PRIOR run that already created a ticket for this idea \u2014 even one created days ago. A hit here is a strong `duplicate` signal.\n   - **Idempotency-label query**: run `get_tickets` with its `labels` parameter set to `bapi-idea-to-ticket-{run_id}` (the tool builds the `labels in (...)` JQL for you \u2014 do not pass a raw JQL string). This per-run label only matches a partial run of THIS same run, so it supports resume behavior.\n\n2. For each returned ticket, capture: ticket key, summary, status, and a short reason it matched (which query, which keyword).\n\n3. Classify the overall verdict as one of:\n   - `duplicate` \u2014 at least one returned ticket clearly describes the same work as `idea`.\n   - `related` \u2014 returned tickets are adjacent or partial overlaps but not the same work.\n   - `none_found` \u2014 no meaningful matches.\n   - `unable_to_check` \u2014 the Jira search itself failed (network error, auth error, JQL rejection). Record the failure and pick this verdict.\n\n4. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/duplicate-assessment.json` with at minimum:\n   - `verdict` \u2014 one of the four values above.\n   - `matches` \u2014 array of `{ticket_key, summary, status, reason}` objects (may be empty).\n   - `queries_used` \u2014 array of the actual JQL/search strings sent.\n   - `allow_duplicate` \u2014 the resolved value of `{allow_duplicate}` for this run.\n\n5. Halt behavior:\n   - If `verdict` is `duplicate` and `allow_duplicate` is not `"true"`, halt locally. Do not continue the pipeline. Tell the user that the duplicate halt is strict and that re-running with `--allow-duplicate` overrides it.\n   - If `verdict` is `duplicate` and `allow_duplicate` is `"true"`, continue the pipeline but keep the duplicate evidence in the assessment file so downstream steps can reference it (e.g., to add a "supersedes" note to the draft).\n   - For `related`, `none_found`, and `unable_to_check`, continue without halting.\n\n## Return\n\nConfirm `duplicate-assessment.json` was written, report `verdict`, and report whether the run is halting or continuing.\n',
   "evaluate-and-recommend.md": 'Evaluate the clarifying questions and ticket critiques generated for {ticket_key} against the actual codebase, then decorate every actionable item with the resolution guidance the reviewer will need on the decision page. The result is a single combined review-and-resolution document.\n\n## Phase 0 \u2014 Grounding & Audit Setup\n\nBefore gathering any source documents, extract the codebase-grounding context produced by the preceding `materialize_fresh_base` pipeline step:\n\n- Read the `materialize_fresh_base` tool result from earlier in this session. It returns JSON `{ base_sha, base_branch, fresh_base_root }` \u2014 or, when `no_refresh_base` was set, `{ base_sha: "local-stale", fresh_base_root: <original repo root> }`.\n- Retain `fresh_base_root` and `base_sha` for the rest of this procedure. Every codebase read in Phase 1 / Phase 2 below is grounded against `fresh_base_root`. `fresh_base_root` is also the exact value you must pass to the pipeline\'s later `cleanup_fresh_base` step \u2014 it is a *runtime* value returned by the tool call, not a static recipe variable, so pass the real path string you captured here, not any placeholder text shown in the step\'s params.\n- If the `materialize_fresh_base` step\'s result contains an `error` field and `no_refresh_base` was NOT set, this is the fail-loud condition the recipe\'s `on_error: "halt"` exists for: stop here, do not fall back to grounding against your own working directory, and report the failure (name the attempted base branch and the remediation \u2014 retry, or rerun with `--no-refresh-base`).\n\n**Metadata Audit Header** \u2014 the very first content of the generated review-and-resolution document, before any other section, must be:\n\n```\n**Base SHA**: <base_sha>\n**Base Branch**: <base_branch, or "(local, in-place)" when base_sha is "local-stale">\n**Grounding Status**: <Freshly Materialized | Stale/In-Place Fallback>\n```\n\n- `Grounding Status` is **Freshly Materialized** whenever `base_sha` is a real commit SHA (the normal path).\n- `Grounding Status` is **Stale/In-Place Fallback** whenever `base_sha` is exactly `local-stale` (the `--no-refresh-base` opt-out path). In this case, immediately follow the header with a prominent, bold, high-contrast warning block, for example:\n\n  > **\u26A0 STALE GROUNDING \u2014 `--no-refresh-base` was used.** This review evaluated the codebase as checked out locally, NOT a freshly-fetched `origin/<base>`. `file:line` citations may reflect uncommitted or unmerged local state.\n\n**Codebase grounding rule**: Ground ALL file reads and codebase searches exclusively against the `fresh_base_root` directory extracted above. Do NOT read codebase files from your default working directory or session cwd \u2014 `fresh_base_root` is the only trustworthy source of truth for `file:line` citations in this procedure.\n\n**Original-repo rule**: Ticket docs, `{docs_dir}` inputs, and ALL output paths stay in the ORIGINAL repository, never the `fresh_base_root` temp dir. This includes the ticket-fetch call below, the clarifying-questions / critique source documents, and the saved review-and-resolution output file (see the Save rule at the bottom). Do NOT redirect any of these into `fresh_base_root`.\n\n**Path hygiene rule**: Every `file:line` citation and Codebase Evidence entry in the output document MUST be repo-relative \u2014 strip the `fresh_base_root` absolute-path prefix before writing it down. A citation must never contain a temp-dir / `/tmp/...`-style absolute path (write `src/foo.ts:10`, never `/tmp/bridge-review-.../src/foo.ts:10`).\n\n1. Fetch the current ticket description using the `get_ticket` tool with ticket_number `{ticket_key}` exactly once at the top of this procedure.\n\n2. Gather the clarifying questions and critique documents from the preceding pipeline steps. The local files at `{docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md` and `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md` are the canonical source. After a second-opinion run, each document has this shape:\n\n   - A top-level H1 (`# Ticket Analysis` for clarifier docs, `# Ticket Quality Critique` for critique docs) followed by an italic provider-attribution line of the form `_This analysis was generated by GPT|Claude|Gemini._`. The attribution names the LLM family that produced the **first round**.\n   - The first-round questions / critique items, exactly as written by the first-round model.\n   - **Inline second-opinion blockquotes** nested directly under each prior item the second round addressed. Each blockquote starts with `> **Second opinion (<provider>) - <stance>.**` where `<provider>` is `GPT|Claude|Gemini` and `<stance>` is `concurrence|refinement|disagreement`. The blockquote is followed by `> *Citations: <comma-separated grounding refs>*`. Items the second round did **not** comment on have no blockquote \u2014 that is the "weak concurrence" signal. Use the provider name in the blockquote header to attribute the comment to the second-round LLM family in your evaluation prose where helpful.\n   - A **`## New in Second Opinion`** tail block listing items the second round added on top of the first round. Immediately under the H2 you will find a second italic attribution line of the form `_These additional points were raised by GPT|Claude|Gemini._` \u2014 this names the second-round LLM family. Sub-headings are agent-specific:\n     - Clarifier docs: `### New Requirements Questions` and `### New Technical Questions` \u2014 numbering continues from the prior section.\n     - Critique docs: `### New Requested Changes` and `### New Points to Consider` \u2014 numbering continues from the prior section.\n     Each new item has its own `*Citations: ...*` line.\n   - A final **`## Second Opinion Summary`** footer (1-3 sentences) capturing the second round\'s overall position. This always renders, even when the second round had no inline comments and no new items.\n\n   **Legacy fallback shape**: in rare cases (model lacks JSON-schema support, the JSON call failed, or the response could not be parsed), the document may instead end with `\\n\\n---\\n\\n` followed by a `## Second Opinion` section containing `### Response to Prior Items` and `### Additional Points` subsections. If you detect this fallback shape, treat it equivalently: subsection responses tagged `concurrence` map to weak/strong concurrence (use the body length to disambiguate \u2014 bare one-line concurrences are weak), `refinement`/`disagreement` map to the disagree buckets, and items under `### Additional Points` map to the gap-captured bucket below.\n\n   **Partial-source-doc tolerance**: if the clarifying-questions doc OR the ticket-critique doc is missing or unreadable, skip that document silently and produce items only for the surviving doc. Do not fail. If **both** documents are absent, still write the combined output file at `{docs_dir}/review/{ticket_key}-review-and-resolution.md` with the standard top-level sections (`Confirmed Improvements`, `Needs Scrutiny`, `Open Questions`, `Round Agreement Summary`) present but no emitted E-items in any section. This preserves downstream file-existence expectations for the capture-review-decisions step.\n\n3. Determine **Round Agreement** for every clarifying question and critique point using these rules:\n\n   - **Both rounds agree (weak concurrence)** \u2014 the prior item has NO inline blockquote AND is not in `## New in Second Opinion`. The second round did not object to the point and did not consider it important enough to comment on. Briefly validate the answer\'s groundedness against the codebase. If validation surfaces concerns, demote this item to **rounds disagree** (single round only depth) and treat as Needs Scrutiny.\n   - **Both rounds agree (strong concurrence)** \u2014 the prior item carries an inline `> **Second opinion (<provider>) - concurrence.** ...` blockquote. The second round explicitly reinforced the prior point. Reuse the blockquote\'s `*Citations:*` as starting evidence; verify briefly.\n   - **Rounds disagree (refinement)** \u2014 the prior item carries an inline `> **Second opinion (<provider>) - refinement.** ...` blockquote. The second round modified or added detail. Apply full disagreement-depth analysis; reuse blockquote citations.\n   - **Rounds disagree (disagreement)** \u2014 the prior item carries an inline `> **Second opinion (<provider>) - disagreement.** ...` blockquote. The second round contradicts the prior. Apply full disagreement-depth analysis; categorize the outcome based on which position the codebase supports.\n   - **Gap captured** \u2014 the item lives under `## New in Second Opinion > ### New <category>` (one of: New Requirements Questions, New Technical Questions, New Requested Changes, New Points to Consider). Apply the two-axis check below. Reuse the new item\'s `*Citations:*` as starting evidence.\n   - **Single round only** \u2014 the document has none of the above markers (no inline blockquotes, no `## New in Second Opinion` block, no `## Second Opinion Summary` footer). The pipeline ran only one round. Treat every item as a disagreement: cite 2+ codebase locations and give full analytical depth.\n\n   Apply these depth and categorization rules:\n\n   - **Both rounds agree (weak concurrence)**: 1 codebase citation, 1-2 sentence assessment confirming grounding. Categorize as Confirmed Improvement if grounded; demote to Needs Scrutiny if validation finds problems.\n   - **Both rounds agree (strong concurrence)**: 1 codebase citation (may reuse a blockquote citation), 1-2 sentence assessment. Categorize as Confirmed Improvement.\n   - **Rounds disagree (refinement or disagreement)**: 2+ codebase citations, 3-4 sentence assessment that explicitly weighs the prior-round position against the second-opinion position. Categorize based on which position the evidence supports. Always include both positions in the Assessment.\n   - **Gap captured \u2014 two-axis check** (for items in `## New in Second Opinion`):\n       - If both the question is grounded in the codebase/standards AND the best-guess answer is sensible \u2192 **Confirmed Improvement** with a 1-2 sentence assessment and 1 citation.\n       - If the question is genuine but the best-guess answer is flawed \u2192 **Needs Scrutiny**. Cite 2+ files. Use disagreement-depth.\n       - If the question itself does not hold up \u2192 **Needs Scrutiny** with evidence of what the code actually does. Disagreement-depth.\n       - If neither codebase nor standards can settle the question \u2192 **Open Questions**. Disagreement-depth.\n   - **Single round only**: Treat as a disagreement \u2014 cite 2+ codebase locations and give full analytical depth.\n\n   For critique points (Requested Changes and Points to Consider), apply the same Round Agreement rules. The signal locations are inline `> **Second opinion (<provider>) - ...**` blockquotes nested under items in `### Requested Changes` / `### Points to Consider`, and gap-captured items under `## New in Second Opinion > ### New Requested Changes` / `### New Points to Consider`.\n\n   **Depth calibration**:\n   - When Round Agreement is `both rounds agree (weak concurrence)`, `both rounds agree (strong concurrence)`, or `gap captured` (passes both axes), keep Assessment to 1-2 sentences and Codebase Evidence to 1 citation \u2014 the validation step or the consensus does the heavy lifting.\n   - When Round Agreement is `rounds disagree (refinement)`, `rounds disagree (disagreement)`, or `single round only`, Assessment should be 3-4 sentences and Codebase Evidence should cite 2+ files explaining the discrepancy.\n   - A `gap captured` item that FAILS the two-axis check uses the disagreement depth, not the gap-captured depth.\n   - A `weak concurrence` item that FAILS your validation gets demoted: change Round Agreement to `rounds disagree (single round only)`, expand Assessment to 3-4 sentences, and add a 2nd citation.\n\n   **Source field conventions** \u2014 the `**Source**` string disambiguates where in the source doc the item lives so the downstream `capture-review-decisions` step can route the rewrite correctly. Use these forms:\n\n   - **Weak concurrence (silent prior item)**: `Clarifying Q3 (prior round, weak concurrence)` or `Critique: Requested Change 2 (prior round, weak concurrence)`.\n   - **Strong concurrence (explicit blockquote)**: `Clarifying Q9 (prior round, concurrence inline)` or `Critique: Points to Consider 1 (prior round, concurrence inline)`.\n   - **Refinement (inline blockquote)**: `Clarifying Q3 (prior round, refinement inline)`.\n   - **Disagreement (inline blockquote)**: `Clarifying Q5 (prior round, disagreement inline)`.\n   - **Gap captured (tail-block item)**: `Clarifying Q11 (new in second opinion \u2192 New Requirements Questions)` or `Critique: Requested Change N+1 (new in second opinion \u2192 New Requested Changes)`. Always spell out the sub-section name after the arrow \u2014 capture-review-decisions uses it to find the rewrite target.\n   - **Single round only**: `Clarifying Q3 (single round)`.\n\n## Phase 1 \u2014 Evaluate and classify every item\n\nNumber every item sequentially across all sections (E-1, E-2, E-3, \u2026). When the same underlying issue is raised in BOTH the clarifying-questions doc and the critique doc, consolidate it into a SINGLE E-item rather than emitting one per source, and cite both origins in its `**Source**` field (e.g. `Clarifying Q3 + Critique: Requested Change 2`); keep the numbering sequential with no gaps. Classify every clarifying question and every critique point into exactly one of three buckets using the Round Agreement rules, codebase groundedness checks, and the `gap captured` two-axis check before producing any recommendation decoration:\n\n- **Confirmed Improvements**: Suggestions that are grounded and would genuinely improve the ticket by closing significant gaps or correcting design issues. Includes weak-concurrence items that passed validation, strong-concurrence items, and `gap captured` items that passed both axes.\n- **Needs Scrutiny**: Suggestions based on inaccurate codebase assumptions, with evidence of the actual code behavior. Includes `gap captured` items that failed either axis, weak-concurrence items demoted by validation, and the loser of any rounds-disagree pair.\n- **Open Questions**: Legitimate ambiguities that require human input to resolve.\n\nPhase 1 must complete before Phase 2 begins \u2014 do not start decorating an item with a decision tree, recommendation index, or clarity fields until classification is final.\n\n## Phase 2 \u2014 Decorate actionable items with resolution guidance\n\nPhase 2 applies **only** to items in the `Needs Scrutiny` and `Open Questions` buckets. Confirmed Improvements remain compact and undecorated (see "Confirmed Improvements output" below).\n\nFor every actionable (Needs Scrutiny / Open Questions) item, produce the following template using these stable labels:\n\n```\n### E-<sequential number>: <concise title>\n\n**Source**: <where this item lives in the source doc \u2014 see Source field conventions above>\n\n**Round Agreement**: <one of the six values> \u2014 <1 sentence on what the second round contributed>\n\n**Confidence**: <High|Medium|Low>\n\n**Resolution path**: <"resolve at your desk" or "needs a conversation">\n\n**Decision tree**:\n- If <condition 1>, then <action 1>. See `file:line`. <1-2 sentence rationale.>\n- If <condition 2>, then <action 2>. See `file:line`. <1-2 sentence rationale.>\n- If <condition 3>, then <action 3>. See `file:line`. <1-2 sentence rationale.>\n\n**Recommendation Index**: <0-based index of the recommended branch in the decision tree above>\n\n**Recommendation**: <which branch the evidence best supports and why, 1-2 sentences>\n\n**Original question**: <the clarifying-question or critique point as it was originally raised, sourced verbatim or near-verbatim from the original clarifying-questions / critique docs. Light rephrasing is allowed; do NOT introduce new technical content. Soft cap ~30 words.>\n\n**Option consequences**:\n- <consequence for branch 1 \u2014 describe the behavioral consequence of choosing this option, not its rationale. ~25 words.>\n- <consequence for branch 2 \u2014 same shape. ~25 words.>\n- <consequence for branch 3 \u2014 same shape. ~25 words.>\n\n**Why it matters**: <one concrete sentence on the impact this decision has on the ticket, the users, or the affected code paths. Soft cap ~40 words.>\n\n**Recommendation explanation**: <explain why the recommended branch is the best choice, tied to the codebase evidence and the consequences of each option. Soft cap ~60 words.>\n\n**Assessment**: <three-point structure>\n1. **State the original suggestion**: What did the clarifying question or critique point propose?\n2. **State the codebase evidence**: What does the actual code show about this suggestion?\n3. **State the implication**: Does the evidence confirm the suggestion, contradict it, or leave it unresolved?\n\n**Codebase Evidence**:\n- `path/to/file.ts:42` \u2014 <what this line/block demonstrates>\n- `path/to/other.ts:110-125` \u2014 <what this range demonstrates>\n\n<If no direct codebase evidence exists, state: "No direct codebase evidence found.">\n```\n\n**Writing quality**: Write each Assessment as if explaining to a colleague who has NOT read the original clarifying questions or critique documents. Each assessment should be self-contained and understandable without cross-referencing the source material. The three-point Assessment structure ensures every assessment tells a complete story rather than assuming the reader already knows what was suggested and why.\n\n**Decision tree rules**:\n- Each decision tree must have **2\u20134 branches**. Do not exceed 4 and do not produce only 1.\n- **Strict lower bound \u2014 reclassify on single-branch items**: If you can think of only one branch for a `Needs Scrutiny` or `Open Questions` item \u2014 that is, the resolution is effectively forced \u2014 you must reclassify the item as a **Confirmed Improvement** instead of emitting a single-branch decision tree. The 2-branch lower bound is a hard rule; do not work around it by stretching to a contrived second branch. If a single answer is genuinely the only path, the item belongs in Confirmed Improvements.\n- Each branch must end with a concrete, actionable step (not "investigate further").\n- Cite relevant code in `file:line` format where possible. If no code reference exists, omit the citation rather than fabricating one.\n- Cap each branch at 2-3 sentences total (including the action and rationale).\n- `**Recommendation Index**` must be the 0-based index of the recommended branch in the decision tree above. The first branch is index 0, the second is index 1, etc.\n- **Option consequences** must be a list parallel to the decision-tree branches: one entry per branch, in the same order. Describe the behavioral consequence of choosing that option, not its rationale.\n- **"resolve at your desk"**: The item can be resolved through technical investigation \u2014 reading code, running tests, or checking configuration. No stakeholder input needed.\n- **"needs a conversation"**: The item involves a product decision, scope question, or cross-team dependency that cannot be resolved from the codebase alone.\n\n**Confidence Tags** \u2014 assign confidence based on codebase evidence strength:\n- **High**: Cite specific `file:line` references that directly support the assessment.\n- **Medium**: Reference related code patterns or architectural conventions, but not the exact code in question.\n- **Low**: No direct codebase evidence. Assessment is based on general reasoning or domain knowledge.\n\n### Confirmed Improvements output\n\nRender each Confirmed Improvement as a single bullet in a compact list. No headings per item, no decision trees, no clarity-field decoration:\n\n- **E-<number>: <title>** \u2014 Source: <source string>; Round Agreement: <one of the six values>; Confidence: <High|Medium|Low>. <recommended action, 1 sentence.>\n\nThe compact bullet still includes `Source`, `Round Agreement`, `Confidence`, and the one-sentence recommended action so `capture-review-decisions.md` can map these items to its `clear_improvements` array.\n\n## Round Agreement Summary\n\nAfter all items are processed, produce a summary section that groups items by round agreement status:\n\n### Points of Disagreement\nFor items where the evaluation marked `rounds disagree (refinement)`, `rounds disagree (disagreement)`, or `single round only` \u2014 including `gap captured` items that failed the two-axis check and landed in Needs Scrutiny \u2014 list as bullets with the E-number, the nature of the disagreement, and a 1-sentence explanation of why this disagreement matters for the ticket (e.g., it indicates an architectural ambiguity, a scope question, or a standards gap).\n\nIf no items were marked as disagreements, write: "All reviewed points had round consensus. No disagreement-driven risks identified."\n\n### Points of Agreement\nSplit this section into two sub-bullets to surface the difference between the second round explicitly reinforcing a point versus tacitly accepting it:\n\n**Strong agreement** \u2014 items where the evaluation marked `both rounds agree (strong concurrence)`. The second round took the trouble to write an explicit `concurrence` blockquote; this is a soft signal that the point is important enough that the second round wanted to underline it. List as bullets with the E-number and a half-sentence noting the shared conclusion.\n\n**Weak agreement** \u2014 items where the evaluation marked `both rounds agree (weak concurrence)`. The second round did not object and did not consider the item important enough to comment on; the local agent\'s brief validation found no concerns. List as bullets with the E-number and a half-sentence noting the conclusion. Lower priority for human review than strong-agreement items.\n\nIf a sub-bullet has no items, omit it (rather than writing a "no items" note for each \u2014 keep the section tidy).\n\n### Gaps Captured by Second Round\nFor items where the evaluation marked `gap captured` (sound second-opinion Additional Points confirmed as Confirmed Improvements): list as bullets with the E-number and a half-sentence noting the gap the second round surfaced. These items did not require a decision \u2014 they are already in Confirmed Improvements \u2014 but are surfaced here so the reviewer sees what the second-round analysis added on top of the first round.\n\nIf no gaps were captured, write: "The second round did not surface any net-new confirmed improvements."\n\n## Edge Cases\n\n- If the evaluation contains zero items in Needs Scrutiny, write: "No items flagged for scrutiny. All reviewed suggestions were either confirmed or remain open questions."\n- If the evaluation contains zero items in Open Questions, write: "No open questions identified. All ambiguities were resolved through codebase analysis."\n- If both Needs Scrutiny and Open Questions are empty, include only the Confirmed Improvements section and add a summary: "All suggestions from the review were confirmed as grounded improvements. No decision trees are needed."\n- If both source documents are absent, still write the combined file with the standard top-level sections present but no emitted E-items rather than failing.\n\n## Example of a Well-Written E-Item (Weak Concurrence \u2014 Confirmed Improvement)\n\n### E-2: Caching of analysis-type lookups\n\n**Source**: Clarifying Q4 (prior round, weak concurrence)\n\n**Round Agreement**: both rounds agree (weak concurrence) \u2014 the second round did not comment on this item; brief validation confirms the answer is grounded.\n\n**Assessment**: The prior round suggested caching `ANALYSIS_TYPES` lookups in a module-level variable to avoid repeated DB round trips. The codebase already does this at `src/python/learn_repository/__init__.py:14`, so the suggestion is grounded and the second round\'s silence is consistent with tacit agreement.\n\n**Codebase Evidence**:\n- `src/python/learn_repository/__init__.py:14` \u2014 module-level constant pattern is the established convention\n\n(Confirmed Improvements compact bullet form: **E-2: Caching of analysis-type lookups** \u2014 Source: Clarifying Q4 (prior round, weak concurrence); Round Agreement: both rounds agree (weak concurrence); Confidence: High. Confirm the existing module-level cache and add a short comment naming the pattern.)\n\n## Example of a Well-Written E-Item (Strong Concurrence \u2014 Confirmed Improvement)\n\n### E-4: Sequential per-type review_repository fan-out\n\n**Source**: Clarifying Technical Q2 (prior round, concurrence inline)\n\n**Round Agreement**: both rounds agree (strong concurrence) \u2014 the second round explicitly reinforced the prior recommendation, citing per-type lock release simplicity as the deciding factor.\n\n**Assessment**: The prior round recommended sequential per-type execution; the second-opinion blockquote reinforced this, noting that the per-type lock release contract becomes trivial under sequential execution. `review_repository` already uses internal `asyncio.gather` for chunk-level concurrency, so wrapping it in another concurrency layer would not buy throughput and would complicate the abort/finally cleanup contract.\n\n**Codebase Evidence**:\n- `src/python/learn_repository/review_repository.py:369-387` \u2014 review_repository internally gathers chunks with return_exceptions=True\n\n## Example of a Well-Written E-Item (Rounds Disagree \u2014 Needs Scrutiny with full clarity fields)\n\n### E-5: Authentication middleware placement for new endpoint\n\n**Source**: Clarifying Q2 (prior round, disagreement inline)\n\n**Round Agreement**: rounds disagree (disagreement) \u2014 the prior round recommended adding auth at the router level; the second-opinion blockquote argued the existing middleware stack already covers it.\n\n**Confidence**: High\n\n**Resolution path**: resolve at your desk\n\n**Decision tree**:\n- If the global middleware stack already enforces auth on `/api/*` routes, then drop the explicit `Depends(require_api_key)` from the new endpoint. See `main.py:45-52`.\n- If routers each opt in to auth via dependencies, then add `Depends(require_api_key)` to the new endpoint. See `api/routes/__init__.py:18-30`.\n- If only certain `/api/*` sub-paths need auth, then carve out a sub-router with its own dependency. See `api/routes/__init__.py:18-30`.\n\n**Recommendation Index**: 1\n\n**Recommendation**: The existing routers each opt in to auth, so the new endpoint must do the same. Adding `Depends(require_api_key)` is the smallest correct change.\n\n**Original question**: Should the new `/api/exports` endpoint declare an explicit auth dependency, or is it covered by the global middleware?\n\n**Option consequences**:\n- Endpoint becomes publicly reachable; protected data leaks via the new path.\n- Endpoint requires a valid API key, matching every other `/api/*` route.\n- Adds a parallel router; doubles the auth surface that has to be kept consistent.\n\n**Why it matters**: Authentication on `/api/exports` directly determines whether protected data leaks; the wrong default is a security regression, not a stylistic choice.\n\n**Recommendation explanation**: The codebase pattern in `api/routes/__init__.py:18-30` shows each router declaring its own `Depends(require_api_key)`. Following that convention adds two lines, keeps auth uniform across endpoints, and avoids a parallel sub-router that future maintainers would have to keep in sync.\n\n**Assessment**: The prior round suggested that the new `/api/exports` endpoint needs an explicit `Depends(require_api_key)` guard because it is not covered by the global middleware. The second opinion disagreed, claiming the middleware stack in `main.py` handles authentication for all `/api/*` routes. Codebase analysis shows that `main.py:45-52` applies rate limiting globally but authentication is applied per-router in `api/routes/__init__.py:18-30` \u2014 each router must opt in via `Depends(require_api_key)`. This supports the prior round\'s position: the new endpoint needs an explicit auth dependency.\n\n**Codebase Evidence**:\n- `main.py:45-52` \u2014 global middleware applies rate limiting and CORS, but not authentication\n- `api/routes/__init__.py:18-30` \u2014 each router includes its own auth dependency; there is no catch-all auth middleware\n\n## Example of a Well-Written E-Item (Gap Captured \u2014 Confirmed Improvement)\n\n### E-7: Missing Alembic migration for new role-scope column\n\n**Source**: Critique: Requested Change N+1 (new in second opinion \u2192 New Requested Changes)\n\n**Round Agreement**: gap captured \u2014 the second opinion surfaced a missing migration that the prior round did not raise, and recommended adding an Alembic revision.\n\n**Assessment**: The ticket introduces a new `role_scope` column on the `users` table but does not mention a migration. The second opinion flagged this gap and recommended adding an Alembic revision; both the gap and the recommendation are grounded, since `db/alembic/versions/` is the established location for schema changes per the project\'s database guide.\n\n**Codebase Evidence**:\n- `db/alembic/versions/` \u2014 all schema changes land here as autogenerated revisions\n\n## Save rule\n\nSave the combined review-and-resolution document to `{docs_dir}/review/{ticket_key}-review-and-resolution.md`. Output only the combined review-and-resolution document \u2014 no meta-commentary.\n\n## Return\n\nConfirm "Review-and-resolution document written to `{docs_dir}/review/{ticket_key}-review-and-resolution.md`." and report the total count of E-items captured.\n',
   "execute-epic-research.md": 'Execute the research plan and write findings.\n\n## Instructions\n\n1. Read the research plan from `{docs_dir}/epic-plans/{epic_slug}/research-plan.md`.\n\n2. Execute the plan based on the Research Mode:\n\n   **If mode is `deep`**:\n   - Call the `request_deep_research` MCP tool with:\n     - `query`: the Deep Research Query from the plan\n     - `context`: "Bridge API is a Python/FastAPI application with PostgreSQL, LiteLLM, and Pinecone. This research supports epic planning for: {epic_description}"\n     - `wait_for_result`: true\n     - `save_locally`: true\n   - If deep research fails, log a warning and fall back to web searches using the Web Search Topics from the plan. Do NOT halt.\n\n   **If mode is `web`**:\n   - Perform web searches for each topic listed in the plan.\n   - Capture relevant findings from each search.\n\n   **If mode is `none`**:\n   - Write a brief note: "No external research needed. Proceeding with codebase exploration."\n\n3. Write all findings to `{docs_dir}/epic-plans/{epic_slug}/research-findings.md` with this structure:\n\n```markdown\n# Research Findings\n\n## Mode\n{deep | web | none}\n\n## Findings\n{Synthesized research results organized by topic. Include source references where applicable.}\n\n## Key Takeaways\n{Bullet points summarizing the most important findings that will inform the codebase exploration and epic decomposition.}\n```\n\n## Return\n\nConfirm research findings were written to `{docs_dir}/epic-plans/{epic_slug}/research-findings.md` and report the mode used (`deep`, `web`, or `none`) plus a one-line summary of the key takeaways.\n',
-  "execute-plan.md": 'Execute the AI-generated implementation plan for ticket {ticket_key}.\n\n---\n\n## Step 1 \u2014 Retrieve the Full Plan\n\n1. Call the `get_plan` tool for `{ticket_key}` to retrieve the full generated plan as a flat markdown step list.\n2. Derive the total number of implementation steps from the returned plan.\n3. Announce: **"Plan contains N steps."**\n\nThe local file at `{docs_dir}/plans/{ticket_key}-plan.md` is a saved copy of the same plan and may be used as a reference if needed.\n\n## Step 2 \u2014 Execute Each Step Sequentially\n\nFor each step in the plan:\n\n1. **Announce** before starting: **"Step X of N: <step title from plan>"**\n2. **Execute** the step, making code changes as directed.\n3. **Confirm** after completing: **"Step X complete \u2014 <brief summary of what was done>."**\n\n### Rules\n\n- Execute steps in strict sequential order. Do not skip, reorder, or combine steps.\n- Run any tests or checks specified in the plan\'s review steps.\n- Do NOT run `git commit` or `git push` \u2014 leave all changes uncommitted for developer review.\n- If a step is ambiguous or blocked, note the issue clearly (what is ambiguous and why) and continue with the next step.\n\n## Step 3 \u2014 Final Audit\n\nAfter all steps are executed:\n\n1. Review the full plan (already retrieved in Step 1, or the local saved copy at `{docs_dir}/plans/{ticket_key}-plan.md`) to re-enumerate every step.\n2. For any step you are unsure you fully addressed, compare it against the work completed.\n3. List any steps that were skipped or only partially completed, with reasons.\n4. Announce: **"Audit complete \u2014 N of N steps fully addressed."** (or note discrepancies).\n\n## Return\n\nConfirm "Audit complete \u2014 N of N steps fully addressed." (or list discrepancies \u2014 which steps were skipped/partial and why).\n',
+  "execute-plan.md": 'Execute the AI-generated implementation plan for ticket {ticket_key}.\n\n---\n\n## Step 1 \u2014 Retrieve the Full Plan\n\n1. Call the `get_plan` tool for `{ticket_key}` to retrieve the full generated plan as a flat markdown step list.\n2. Derive the total number of implementation steps from the returned plan.\n3. Announce: **"Plan contains N steps."**\n\nThe local file at `{docs_dir}/plans/{ticket_key}-plan.md` is a saved copy of the same plan and may be used as a reference if needed.\n\n## Step 2 \u2014 Execute Each Step Sequentially\n\nFor each step in the plan:\n\n1. **Announce** before starting: **"Step X of N: <step title from plan>"**\n2. **Execute** the step, making code changes as directed.\n3. **Confirm** after completing: **"Step X complete \u2014 <brief summary of what was done>."**\n\n### Rules\n\n- Execute steps in strict sequential order. Do not skip, reorder, or combine steps.\n- Run any tests or checks specified in the plan\'s review steps.\n- Do NOT run `git commit` or `git push` \u2014 leave all changes uncommitted for developer review.\n- If a step is ambiguous or blocked, note the issue clearly (what is ambiguous and why) and continue with the next step.\n- If the current step leaves a requirement ambiguous or blocked by missing ticket detail, call the `get_ticket` tool with `ticket_number` set to `{ticket_key}` to fetch the live Jira ticket details. Use only the returned fields relevant to the unresolved requirement, then continue the affected step. Do not call `get_ticket` unconditionally or as part of initial plan retrieval \u2014 `get_plan` in Step 1 remains the sole unconditional context retrieval.\n\n## Step 3 \u2014 Final Audit\n\nAfter all steps are executed:\n\n1. Review the full plan (already retrieved in Step 1, or the local saved copy at `{docs_dir}/plans/{ticket_key}-plan.md`) to re-enumerate every step.\n2. For any step you are unsure you fully addressed, compare it against the work completed.\n3. List any steps that were skipped or only partially completed, with reasons.\n4. Announce: **"Audit complete \u2014 N of N steps fully addressed."** (or note discrepancies).\n\n## Return\n\nConfirm "Audit complete \u2014 N of N steps fully addressed." (or list discrepancies \u2014 which steps were skipped/partial and why).\n',
   "execute-research.md": "Execute the research plan and produce a consolidated research pack.\n\n## Inputs\n\n- Research plan: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-plan.json`.\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n\n## Instructions\n\n1. Read `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-plan.json`. Execute only the tools listed in `selected_tools`. Do not invoke any tool that is not in that list.\n\n2. For each selected tool:\n   - **codebase_search**: search the local working tree using the listed `codebase_search_topics`. Capture file paths, function names, and short excerpts as evidence.\n   - **web_search**: run narrow, targeted searches for each item in `web_search_topics`. Capture the source URL and a short summary for each result.\n   - **deep_research**: run the deep research query exactly once with the planned `deep_research_query`. Capture the consolidated answer plus the cited URLs.\n\n3. Tool failures must be recorded, not silently dropped:\n   - If a tool returns an error, missing-credential message, or empty result, record the failure under `per_tool_failures` in the research pack and continue with the remaining tools.\n   - A partial research pack is preferable to no research pack. Do not halt the pipeline because one tool failed.\n\n4. Write two artifacts to the run directory:\n   - `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-pack.md` \u2014 a human-readable consolidated brief. It must include these sections:\n     - **Evidence table** \u2014 a structured list of evidence rows: claim, source (file path / URL), and tool that produced it. Render as a bulleted list, not a markdown table (BAPI-320 hygiene).\n     - **Codebase references** \u2014 file paths and function names worth citing in the ticket.\n     - **External references** \u2014 only present when web/deep search ran; URL + short summary per item.\n     - **Unresolved unknowns** \u2014 questions the research could not answer.\n     - **Per-tool failures** \u2014 any tool that failed, with the failure reason.\n   - `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-pack.json` \u2014 machine-readable counterpart with the same evidence rows, references, unresolved unknowns, and per-tool failures arrays.\n\n5. Mark research failures as warnings in `research-pack.json` so downstream steps can branch on them: include `partial: true` when any selected tool failed.\n\n## Return\n\nConfirm `research-pack.md` and `research-pack.json` were written, and list any tools that failed.\n",
   "explore-epic-codebase.md": 'Perform a holistic, epic-level codebase exploration.\n\n## Epic Description\n\n{epic_description}\n\n## Instructions\n\n1. Read the research findings from `{docs_dir}/epic-plans/{epic_slug}/research-findings.md` to establish context. If the file does not exist or is empty, proceed without it.\n\n2. Explore the codebase with a focus on breadth rather than depth. The goal is to build a "lay of the land" understanding for the entire epic, not to deeply analyze any single sub-task. Search by filename pattern, search file contents by text pattern, and read relevant files to find:\n   - Files, modules, and directories relevant to the epic\n   - Architectural patterns used in similar features\n   - Integration points and dependencies between modules\n   - Existing conventions for the type of work this epic involves\n   - Database models, API routes, agent flows, and utilities that may be affected\n\n3. Build a mental model of:\n   - What exists today that relates to the epic\n   - What patterns and conventions are used in similar features\n   - What dependencies, data flows, and integration points are involved\n   - What areas of the codebase will likely need changes\n\n4. Write the exploration findings to `{docs_dir}/epic-plans/{epic_slug}/codebase-exploration.md` with this structure:\n\n```markdown\n# Codebase Exploration\n\n## Architecture Overview\n{High-level description of how the relevant parts of the codebase are structured.}\n\n## Relevant Code Areas\n{List of key files, modules, and directories with brief descriptions of their relevance to the epic.}\n\n## Existing Patterns\n{Patterns and conventions discovered that should be followed when implementing the epic.}\n\n## Integration Points\n{Dependencies, data flows, and integration points that the epic will need to account for.}\n\n## Potential Challenges\n{Any architectural constraints, technical debt, or complexity that could affect implementation.}\n```\n\n## Return\n\nConfirm the codebase exploration was written to `{docs_dir}/epic-plans/{epic_slug}/codebase-exploration.md` and return a concise summary of the discovered codebase areas, naming the key files and patterns relevant to the epic.\n',
   "explore-epic-subtasks.md": "Perform focused code explorations for each approved sub-task.\n\n## Instructions\n\n1. Read the approved decomposition from `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md`.\n\n2. Create the explorations directory:\n   ```\n   mkdir -p {docs_dir}/epic-plans/{epic_slug}/explorations/\n   ```\n\n3. For each sub-task in the decomposition, perform a focused exploration:\n   - Search for specific files and patterns relevant to the sub-task\n   - Identify implementation options and tradeoffs\n   - Reference the holistic codebase exploration (`{docs_dir}/epic-plans/{epic_slug}/codebase-exploration.md`) and research findings (`{docs_dir}/epic-plans/{epic_slug}/research-findings.md`) for context\n   - Default to lightweight exploration \u2014 only go deeper when the holistic exploration left significant gaps for a specific sub-task\n\n4. Write an exploration document for each sub-task to `{docs_dir}/epic-plans/{epic_slug}/explorations/NN-{subtask-slug}.md` (using zero-padded numbering, e.g., `01-add-pipeline-json.md`, `02-create-instruction-files.md`).\n\n5. Each exploration document MUST include these exactly named sections:\n\n```markdown\n# {Sub-task title}\n\n## Context\n{Brief description of the sub-task scope and its role within the epic.}\n\n## Relevant Code\n{Specific files, functions, and patterns relevant to this sub-task. Reference with file_path:line_number format.}\n\n## Implementation Options\n{Viable approaches for implementing the sub-task. For each option: description, pros, cons.}\n\n## Recommendation\n{Which option to pursue and why. Include any caveats or risks.}\n```\n\n6. **Word count guidance**: Target 300-500 words per document. Keep the exploration lightweight. Only exceed this limit if the holistic codebase exploration left significant gaps for a specific sub-task.\n\n## Return\n\nConfirm one exploration document was written per sub-task under `{docs_dir}/epic-plans/{epic_slug}/explorations/` and return a concise summary of the discovered code areas and recommended approaches across the sub-tasks.\n",
@@ -14472,7 +15111,7 @@ var INSTRUCTIONS = {
   "request-prd.md": "# request_prd\n\nStart (or refresh) asynchronous generation of a **Product Requirements Document\n(PRD)** for a Jira ticket.\n\nA PRD is the most product/stakeholder-facing document in the design-document\nfamily. It frames product intent \u2014 the problem, goals, non-goals, target users,\nsuccess metrics, product requirements, scope, and risks \u2014 rather than the\ndetailed functional flows and acceptance behavior an FSD covers, or the\narchitecture/implementation guidance a TDD covers.\n\n## Async request/retrieve pattern\n\n`request_prd` only **starts** generation; it does not return the PRD directly\nunless you set `wait_for_result`. PRD generation typically takes **2\u20134 minutes**.\n\n1. Call `request_prd` with the `ticket_number`.\n2. Wait for processing to complete (2\u20134 minutes).\n3. Call `get_prd` with the same `ticket_number` to retrieve the result.\n\nSet `wait_for_result: true` to block and return the PRD content directly instead\nof polling separately.\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n| --- | --- | --- | --- |\n| `ticket_number` | string | \u2014 | Jira ticket key in `PROJECT-NUMBER` format (e.g. `BAPI-123`). |\n| `wait_for_result` | boolean | `false` | When `true`, block and poll until the PRD is ready, then return it directly. |\n| `save_locally` | boolean | `true` | When `wait_for_result` is `true`, save the PRD to `BAPI_DOCS_DIR/prd/{ticket}-prd-plan.md`. |\n| `second_opinion` | string | \u2014 | Provider routing override for **this** generation request (e.g. `anthropic`, `openai`, `gemini`). This is **not** the standalone `second_opinion` tool \u2014 it only changes which provider produces this request's artifact, and takes precedence over `provider`. |\n| `provider` | string | \u2014 | Pure provider switch without second-opinion semantics. If both `provider` and `second_opinion` are set, `second_opinion` wins. |\n\n## Return\n\n- `202` when the request is accepted (async dispatch).\n- `404` if the ticket does not exist in Jira.\n- `403` if the API key is unauthorized.\n",
   "research-decision.md": 'Decide which research tools to run for this idea, biased toward cheap local research first.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json` (must already exist from the preflight step).\n\n## Instructions\n\n1. Read `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`. This is the source of truth for `idea`, `readiness`, `scope`, and `run_id`. If the file does not exist, halt locally \u2014 the preflight step did not complete.\n\n2. Decide which research tools should run for this idea, in roughly this priority order:\n   - **Local codebase research first.** Inspect the working tree (search, grep, file reads) for prior art, related modules, and existing tests. Prefer this for anything that touches code you already own.\n   - **Narrow web search second.** Use targeted web search for short factual lookups: a specific library API, a known external standard, a public spec.\n   - **Deep research only when justified.** Deep research is expensive and slow; it must be earned by one of the rubric items below.\n\n3. Deep-research allowance rubric. Deep research is only allowed when at least one of these is true:\n   - **blast radius**: the change spans many systems or has high reversibility cost (e.g., schema migrations, auth, billing, public APIs).\n   - **unfamiliar external domain**: the idea depends on a third-party domain or specification the repository has no prior coverage of.\n   - **compliance/security uncertainty**: there is real compliance or security uncertainty (SOC2, PII, secret handling, access control).\n   - **cheaper research failed**: a cheaper round (local + narrow web search) already happened in this run and left blocking unknowns.\n   - **explicit user request**: the user explicitly asked for deep research.\n\n4. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-plan.json`. Required fields:\n   - `selected_tools` \u2014 array of tool identifiers to run, drawn from at least `["codebase_search", "web_search", "deep_research"]`. Empty array is allowed when no research is needed.\n   - `rationale` \u2014 short string explaining the choice in terms of the rubric above.\n   - `deep_research_query` \u2014 string. Required when `deep_research` is in `selected_tools`, otherwise empty string.\n   - `web_search_topics` \u2014 array of strings; may be empty.\n   - `codebase_search_topics` \u2014 array of strings; may be empty.\n   - `expected_unknowns` \u2014 array of strings describing what the research is expected to resolve.\n\n5. Do not invoke any research tool from this step \u2014 that happens in `execute-research.md`. This step only writes the plan.\n\n## Return\n\nConfirm `research-plan.json` was written, list `selected_tools`, and quote the rationale.\n',
   "screen-and-resolve.md": 'Apply project standards and the minimum-evidence gate before drafting.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n- Research pack: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-pack.md` / `.json` (may be partial or absent).\n- Duplicate assessment: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/duplicate-assessment.json`.\n- Project standards: the response from the earlier `get_project_standards` step in the same pipeline run. Treat the standards as unavailable when that response was an error envelope, a 404, or missing.\n\n## Instructions\n\n1. Produce three artifacts in the run directory:\n   - `{docs_dir}/idea-to-ticket/{slug}-{run_id}/standards-checklist.json`\n   - `{docs_dir}/idea-to-ticket/{slug}-{run_id}/open-questions.md`\n   - `{docs_dir}/idea-to-ticket/{slug}-{run_id}/resolved-uncertainties.md`\n\n2. Standards checklist:\n   - When `get_project_standards` returned a usable result, derive the checklist items from those standards. Each item is a `{requirement, satisfied, evidence}` triple where `evidence` either cites the research pack or notes "deferred to draft".\n   - When standards are unavailable (404, error envelope, missing), generate a fallback baseline checklist covering at least: requirements clarity, acceptance criteria presence, testability, security/PII consideration, and rollback/observability when scope warrants it. Mark each as `satisfied: false` with `evidence: "fallback baseline \u2014 no project standards available"`.\n\n3. Open questions:\n   - List every unresolved unknown that blocks drafting. Pull from the research pack\'s `unresolved_unknowns` and from your own reading of `idea`.\n   - Each question gets its own bullet (no markdown tables, no `- [ ]` checkboxes \u2014 BAPI-320 hygiene).\n   - If the question has a defensible best-guess answer, write it in `resolved-uncertainties.md` instead, with explicit assumption language ("Assuming X because Y...").\n\n4. Resolved uncertainties:\n   - Mirror open questions that have defensible best-guess answers. Each entry must include `assumption`, `basis` (research-pack reference or codebase reference), and `confidence` ("low", "medium", "high").\n\n5. Minimum-evidence gate. Halt locally if ALL of the following are true:\n   - The research pack contains no codebase references for the idea.\n   - The standards checklist has zero items (even the fallback baseline is missing).\n   - `resolved-uncertainties.md` records no explicit assumptions.\n   When the gate fires, do not continue to drafting. Report the halt and direct the user to either run a smaller idea, run `--allow-duplicate` semantics for replays, or supply more context manually.\n\n## Return\n\nConfirm the three artifacts were written and whether the minimum-evidence gate fired.\n',
-  "store-and-approve-epic-plan.md": 'Store the approved epic plan DAG in the backend and approve it.\n\nThis step runs after the user has approved the decomposition in the\n`decompose-epic` step. It reads the machine-readable sidecar written by that\nstep and wires it into the backend durable store.\n\n## Variables\n\n- `{epic_key}` \u2014 Jira epic key (e.g. BAPI-405)\n- `{epic_slug}` \u2014 lowercase-hyphen slug derived from the epic key\n- `{docs_dir}` \u2014 base docs directory (e.g. `docs/tmp`)\n\n## Step 1 \u2014 Read the DAG sidecar\n\nRead the structured JSON sidecar from\n`{docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json`.\n\nThe DAG must be serialized from this sidecar \u2014 **never by re-parsing the\nmarkdown** (`epic-plan.md`). If the sidecar is missing or unparseable, warn\nthe user with:\n\n> "The structured DAG sidecar (`epic-plan.dag.json`) is missing or invalid.\n> The plan cannot be stored automatically. To recover, you can reconstruct the\n> DAG manually by parsing the Jira dependency links for each sub-task\n> (deterministic Jira-link DAG builder \u2014 documented fallback, not built here)."\n\nThen stop this step with a warning (do not raise an error that aborts the\nentire pipeline).\n\n## Step 2 \u2014 Create the epic run\n\nCall `mcp__bridge-api__create_epic_run` (or equivalent) to create the epic run\nrecord for `{epic_key}`. If the run already exists (HTTP 409), read the\nexisting run ID and proceed with that run \u2014 do not fail.\n\nAlternatively, if a `create_epic_run` MCP tool is not available, make a direct\nAPI call to `POST /jira/epic-runs/runs` with `{ repo_name, epic_key, status: "planning" }`.\n\n## Step 3 \u2014 Compute the plan hash and store the plan\n\nUse the `storeEpicPlan` conductor client method (or equivalent) to POST the\nplan blob:\n\n- `plan_version`: the integer `plan_version` field from the DAG sidecar (must be \u2265 1).\n- `plan_blob`: the full parsed DAG object from the sidecar.\n- `plan_hash`: computed by `hashPlan(dag)` from `mcp_server/src/conductor/plan.ts`.\n  If the hash cannot be computed locally, pass the SHA-256 hex of the\n  canonical JSON string (keys sorted, no extra whitespace) as a fallback.\n\nIf the store call returns HTTP 409 with a hash mismatch, warn the user (substituting the actual version number from the sidecar):\n\n> "Plan version N is already stored with a different hash.\n> Increment `plan_version` in the sidecar and retry."\n\nThen stop this step.\n\n## Step 4 \u2014 Approve the plan\n\nCall `approveEpicPlan` for `plan_version` from the sidecar. On success, the\nbackend transitions the run to `active` status.\n\nIf HTTP 409 is returned (superseded), warn the user:\n\n> "A later plan version is already approved \u2014 approval skipped."\n\n## Return\n\nReport:\n- The epic run ID.\n- The stored `plan_version`.\n- The `plan_hash` returned by the approve call.\n- Whether the run transitioned to `active`.\n\nExample: "Plan v1 stored and approved for epic run `<epic_run_id>`. Run is now active."\n',
+  "store-and-approve-epic-plan.md": 'Store the approved epic plan DAG in the backend and approve it.\n\nThis step runs after the user has approved the decomposition in the\n`decompose-epic` step. It reads the machine-readable sidecar written by that\nstep and wires it into the backend durable store.\n\nThe whole step is a single deterministic command \u2014 `setup-epic`. Do **not**\nhand-roll the HTTP calls, and do **not** compute the plan hash yourself.\n\n## Variables\n\n- `{epic_key}` \u2014 Jira epic key (e.g. BAPI-405)\n- `{epic_slug}` \u2014 lowercase-hyphen slug derived from the epic key\n- `{docs_dir}` \u2014 base docs directory (e.g. `docs/tmp`)\n\n## Step 1 \u2014 Confirm the DAG sidecar exists\n\nThe sidecar written by `decompose-epic` lives at\n`{docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json`.\n\nIf it is missing, warn the user with:\n\n> "The structured DAG sidecar (`epic-plan.dag.json`) is missing or invalid.\n> The plan cannot be stored automatically. To recover, you can reconstruct the\n> DAG manually by parsing the Jira dependency links for each sub-task\n> (deterministic Jira-link DAG builder \u2014 documented fallback, not built here)."\n\nThen stop this step with a warning (do not raise an error that aborts the\nentire pipeline).\n\nThe DAG must always come from this sidecar \u2014 **never from re-parsing the\nmarkdown** (`epic-plan.md`).\n\n## Step 2 \u2014 Run `setup-epic`\n\n```bash\nnpx -y @bridge_gpt/mcp-server setup-epic \\\n  --epic-key {epic_key} \\\n  --plan-file {docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json \\\n  --json\n```\n\nThis creates the epic run, stores the plan blob, and approves it \u2014 in the one\norder that is safe. It is idempotent: re-running it on an epic that already has\na live run reuses that run rather than creating a second one.\n\n**Never work around a failure by POSTing to `/jira/epic-runs/runs` directly.**\nCreating a second active run for an epic wedges it permanently \u2014 every later\nplan call fails with "Multiple active runs" \u2014 and double-charges billing.\n\nPass `--dry-run` first if you want to validate the plan and preview the calls\nwithout changing anything.\n\n## Step 3 \u2014 Interpret the result\n\n`setup-epic` exits `0` on success and prints a JSON object with `epic_run_id`,\n`plan_version`, `plan_hash`, `status`, and any `warnings`.\n\nOn a non-zero exit, relay its error message verbatim \u2014 it is already actionable.\nThe three you are most likely to see:\n\n- **"already stored with a DIFFERENT hash"** \u2014 the plan blob changed after being\n  stored. Increment `plan_version` in the sidecar and re-run.\n- **"MULTIPLE active runs"** \u2014 the epic is wedged. It must be repaired by\n  abandoning the duplicate run before anything else can proceed.\n- **"no touched_files"** (a warning, not an error) \u2014 the plan cannot be protected\n  by file-overlap serialization. Mention it, but do not stop.\n\nA `plan_hash` that differs from the locally computed hash is **not** an error:\nthe server re-hashes after applying file-overlap serialization, and the server\'s\nhash is authoritative.\n\n## Return\n\nReport:\n- The epic run ID.\n- The stored `plan_version`.\n- The `plan_hash` returned by `setup-epic`.\n- Whether the run reached `active`.\n- Any warnings.\n\nExample: "Plan v1 stored and approved for epic run `<epic_run_id>`. Run is now\nactive \u2014 the server-side reconciler will pick it up within ~30s."\n',
   "update-ticket-rewrite.md": "Rewrite the Jira ticket description for {ticket_key} using the generated clarifying questions and critique documents.\n\n1. Fetch the current ticket description using the `get_ticket` tool with ticket_number `{ticket_key}`.\n2. Read the clarifying questions from the local file saved by the previous step (check `{docs_dir}/clarifying-questions/` for `{ticket_key}-clarifying-questions.md`). For each best-guess answer, verify it against the codebase using file search and code grep. Accept verified answers, correct inaccurate ones with evidence, and let ambiguous ones stand.\n3. Read the critique from the local file saved by the previous step (check `{docs_dir}/ticket-critiques/` for `{ticket_key}-ticket-quality-critique.md`). Address all Requested Changes. Apply Points to Consider selectively \u2014 accept genuine improvements, skip stylistic preferences.\n4. Write the rewritten ticket in standard markdown format (not Jira wiki markup). Preserve the Summary, Requirements, and Acceptance Criteria structure.\n5. Save the output to `{docs_dir}/tickets/{ticket_key}.md`. Output only the clean rewritten ticket \u2014 no meta-commentary.\n\n## Return\n\nConfirm the rewritten ticket was saved to `{docs_dir}/tickets/{ticket_key}.md` and briefly note which clarifying-question answers were corrected against the codebase and which critique Requested Changes were addressed.\n",
   "upload-and-track.md": 'Step-10 umbrella upload instruction. Idempotently create the Jira ticket(s) for this run, attach the full draft(s), and call `track_ticket`.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n- Draft metadata: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/draft-metadata.json`.\n- For epic runs, this instruction is also responsible for producing or refreshing `{docs_dir}/idea-to-ticket/{slug}-{run_id}/decomposition-plan.json` before any Jira mutation, by following `decompose-epic-candidate.md` (hard cap `{max_children}`).\n- Pipeline variable `auto_approve_external` controls whether the external-mutation pause is skipped (for this run, `auto_approve_external` = `{auto_approve_external}`). Treat the literal string `"true"` as skip; any other value (including `"false"`, missing, or empty) means pause and ask.\n\n## Instructions\n\n> **Orchestrator-directed step.** This agent task is part of the full-automation chain and is authorized to call `get_tickets`, `create_ticket`, `attachment` (operations: `upload`, `list`), `update_ticket_description`, `track_ticket`, and `add_comment`, and to execute the shared `gather-and-attach-materials.md` instruction, as directed below \u2014 performing orchestrator-directed tool calls is not "re-orchestrating".\n\n1. Read `run-manifest.json` and `draft-metadata.json`. Branch internally based on the manifest\'s `scope`:\n   - `task` or `spike` \u2192 follow the **Single-ticket path** below.\n   - `epic_candidate` \u2192 follow the **Epic path** below.\n   The orchestrator does not support conditional steps; this branching lives in agent logic.\n\n2. External approval gate, applied before any mutating MCP tool call:\n   - If `auto_approve_external` is `"false"` (or any non-`"true"` value), summarize the exact planned Jira mutations \u2014 list every `create_ticket`, `attachment` (operation: `"upload"`), and `track_ticket` call with its key arguments \u2014 and ask the user for explicit confirmation in this agent task before proceeding.\n   - If `auto_approve_external` is `"true"`, proceed without the confirmation pause.\n\n3. **Single-ticket path** (`scope` is `task` or `spike`):\n   1. Idempotency lookup. Call `get_tickets` with its `labels` parameter set to both the per-run label `<idempotency_label>` and the stable `bapi-idea-hash-{idea_hash}` label from `draft-metadata.json` (comma-separated). If a match is found by either label, reuse that ticket key and skip `create_ticket`.\n   2. If no match was found, call `create_ticket` with `summary`, `slim_description` as the description, `issue_type`, and `labels` exactly as written in the metadata. Capture the returned `ticket_key`.\n   3. Upload the full markdown draft via `attachment` (operation: `"upload"`) using `attachment_path`.\n   4. **Gather and attach referenced materials.** Execute the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the resolved ticket key, `draft_file_path` = `attachment_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value. It attaches reachable local text materials and records external/auth-gated and binary/image materials per its own warn-not-halt rules. Any attach failure it reports is recorded (via `update_ticket_description`) as `partial_success` and never halts this step.\n   5. Call `track_ticket` with the resolved ticket key so Bridge API picks the new ticket up.\n   6. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/upload-state.json` describing the final state.\n\n4. **Epic path** (`scope` is `epic_candidate`):\n   1. If `decomposition-plan.json` does not yet exist for this run, follow `decompose-epic-candidate.md` first to produce it (hard cap `{max_children}`).\n   2. Draft any surviving children that lack a draft on disk by calling `jira-ticket-writer` per child with the `draft_path` from the decomposition plan. After drafting, extend `draft-metadata.json` so `children[]` mirrors the final list from the decomposition plan.\n   3. Parent first. Look up the Epic parent by `bapi-idea-to-ticket-{run_id}-parent` via `get_tickets`. If found, reuse that key; otherwise call `create_ticket` with the parent\'s summary, slim description, issue type `Epic`, and parent labels. Attach the Epic draft via `attachment` (operation: `"upload"`) using `parent.attachment_path`. Then **gather and attach the Epic parent\'s referenced materials** by executing the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the Epic key, `draft_file_path` = `parent.attachment_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value. Then call `track_ticket` for the Epic key.\n   4. Children next. For each child in order:\n      - Look up by the child\'s `idempotency_label`. If found, reuse that key.\n      - Otherwise call `create_ticket(parent_key=<epic_key>)` with the child\'s `summary`, `slim_description`, `issue_type`, and `labels`. The `parent_key` is required so Jira\'s modern parent linkage is set.\n      - Upload the child draft via `attachment` (operation: `"upload"`) using `draft_path`.\n      - **Gather and attach this child\'s referenced materials** by executing the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the child key, `draft_file_path` = `draft_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value.\n      - Call `track_ticket` for the child key.\n   5. After every parent or child mutation, write partial progress to `{docs_dir}/idea-to-ticket/{slug}-{run_id}/upload-state.json` so a later resume can pick up exactly where the run stopped.\n   6. **Recommended implementation order comment.** Once the Epic parent and all surviving children exist (real keys known), post a single comment on the Epic via `add_comment` with `ticket_number` set to the Epic key. The comment carries (a) a short System Goals / Non-Functional Requirements summary from `goals-and-nfrs.md`, and (b) the **Recommended Implementation Order** \u2014 the children in order, each referenced by its real Jira key, derived from the `depends_on` / `recommended_after` / `order_rationale` fields in `decomposition-plan.json`. State that this is recommended sequencing only \u2014 do **not** create Jira dependency links and do **not** attach a separate markdown doc. Skip this only if the run reused a pre-existing comment for the same run (idempotency); do not post duplicate order comments on resume.\n\n5. Required child label set whenever any child is created: `ai-generated`, `idea-to-ticket`, `idea-to-ticket-child`, and `bapi-idea-to-ticket-{run_id}-child-<N>` (1-based index from the decomposition plan).\n\n6. Partial-failure recovery rules:\n   - If `create_ticket` succeeds but `attachment` (operation: `"upload"`) fails, record the outcome as `partial_success` in `upload-state.json` and continue with the next planned mutation; do not retry inside this step.\n   - If the Epic parent is created successfully but one or more children fail, preserve the parent key and any completed child keys in `upload-state.json` before raising the failure.\n   - On resume of any prior run, search by every relevant idempotency label first (`bapi-idea-to-ticket-{run_id}` for single tickets, `bapi-idea-to-ticket-{run_id}-parent`, and each `bapi-idea-to-ticket-{run_id}-child-<N>`) before considering any `create_ticket` call. Idempotency labels are how this pipeline avoids creating duplicate tickets across retries.\n\n## Return\n\nConfirm the run\'s final upload outcome: attachment results, `track_ticket` outcome, and any `partial_success` rows recorded in `upload-state.json`.\n\nThen, as the FINAL content of your reply, emit a fenced ```json block holding the authoritative payload for this run \u2014 and nothing else. The chain reads ONLY this final fenced JSON block to pick its review / start-tickets targets, so it must contain exactly the keys from `upload-state.json` and never any key you merely looked up during duplicate detection. Duplicate-detection / looked-up keys must not appear in this authoritative payload unless they are the final created/reused ticket for this run.\n\nThere are exactly two authoritative final payload shapes:\n\n- **Single-ticket path** (`scope` is `task` or `spike`): emit strictly `created_ticket_keys` containing **exactly one** implementable ticket key. `created_ticket_keys` is only for the single-ticket `task`/`spike` path and must contain exactly one implementable ticket key:\n\n  ```json\n  {"created_ticket_keys": ["BAPI-331"]}\n  ```\n\n- **Epic path** (`scope` is `epic_candidate`): emit the Epic parent key separately as `epic_parent_key`, and the implementable children as `child_ticket_keys`:\n\n  ```json\n  {"epic_parent_key": "BAPI-400", "child_ticket_keys": ["BAPI-401", "BAPI-402"]}\n  ```\n\n  `child_ticket_keys` contains **only** implementable child Task/Spike ticket keys, listed in final decomposition order. `child_ticket_keys` must **never** include the Epic parent key.\n',
   "upload-epic-hierarchy.md": 'Standalone Epic upload protocol. Use as the detailed reference for the Epic path triggered from `upload-and-track.md`.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json` with `scope == "epic_candidate"`.\n- Draft metadata: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/draft-metadata.json` with a populated `parent` and `children`.\n- Decomposition plan: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/decomposition-plan.json`.\n- Pipeline variable `auto_approve_external` governs the external-mutation pause as in `upload-and-track.md` (for this run, `auto_approve_external` = `{auto_approve_external}`).\n\n## Instructions\n\n1. Parent idempotency lookup. Search Jira via `get_tickets` for issues carrying the label `bapi-idea-to-ticket-{run_id}-parent`. If a match exists, reuse that ticket key as the Epic parent and skip `create_ticket` for the parent. Otherwise call `create_ticket` with the parent\'s summary, slim description, `issue_type = "Epic"`, and labels including `ai-generated`, `idea-to-ticket`, and `bapi-idea-to-ticket-{run_id}-parent`. After creation or reuse, upload the Epic draft via `attachment` (operation: `"upload"`) and call `track_ticket`.\n\n2. Capture the resolved Epic key into a local variable `epic_key`. Every subsequent child mutation must reference this exact key.\n\n3. Per-child idempotency lookup. For each child in `decomposition-plan.json` (in order), search Jira by the child\'s `idempotency_label` (`bapi-idea-to-ticket-{run_id}-child-<N>`). If a match exists, reuse that key and skip `create_ticket` for that child. Otherwise call `create_ticket(parent_key=<epic_key>)` with:\n   - `summary` \u2014 child summary.\n   - `slim_description` \u2014 child slim description.\n   - `issue_type` \u2014 typically `Task` (or `Spike` when the child is primarily discovery).\n   - `labels` \u2014 `ai-generated`, `idea-to-ticket`, `idea-to-ticket-child`, and the child\'s own `bapi-idea-to-ticket-{run_id}-child-<N>` label.\n   The `parent_key` argument is REQUIRED for every child `create_ticket` call so Jira sets the modern parent relationship; never omit it.\n\n4. After each child is created or reused, upload its draft via `attachment` (operation: `"upload"`) using the child\'s `draft_path`, then call `track_ticket` for that child key, then append the child outcome to `upload-state.json` in the run directory.\n\n5. On partial failure (e.g., parent succeeded, third child failed), preserve `epic_key` plus every completed child key in `upload-state.json`. The next run of this protocol must rediscover those keys via the idempotency-label lookups in steps 1 and 3 before considering any new `create_ticket` call.\n\n## Return\n\nConfirm the Epic key, the number of children created vs reused vs failed, and the path of the updated `upload-state.json`.\n',
@@ -14483,7 +15122,7 @@ var INSTRUCTIONS = {
 init_version_generated();
 
 // src/readme.generated.ts
-var README = '# @bridge_gpt/mcp-server\n\nThe Bridge MCP is an end-to-end accelerator for shipping code within SFCC, powered by [Bridge API](https://bridgegpt-api.com). Works with Claude Code, Github Copilot, Cursor, Windsurf, and OpenAI Codex.\n\n## Contents\n\n- [Getting Started](#getting-started)\n- [Usage Documentation](#usage-documentation)\n  - [Tier 1 \u2014 Regularly useful](#tier-1--regularly-useful)\n  - [Tier 2 \u2014 Occasionally useful](#tier-2--occasionally-useful)\n  - [Tier 3 \u2014 Now and then](#tier-3--now-and-then)\n  - [Operational commands](#operational-commands)\n  - [Extra Capabilities](#extra-capabilities)\n- [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)\n- [CLI Subcommands](#cli-subcommands)\n- [Custom Pipelines](#custom-pipelines)\n- [Environment Variables](#environment-variables)\n- [Worktree credentials and the `mcp-invoke` shim](#worktree-credentials-and-the-mcp-invoke-shim)\n- [Reference](#reference)\n\nFor advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./CONDUCTOR.md).\n\n## Getting Started\n\n### Quick start\n\nFrom your **project root**, install and connect in one command:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge\n```\n\n`install-bridge` scaffolds the project, writes your editor\'s MCP config with real\nvalues, verifies connectivity, persists your API key to the user-scoped credential\nstore, and opens a fresh agent session to finish setup (`/install-bridge` then\n`/learn-repository`). The only inputs are an **API key** (generate one on the Bridge\nAPI web UI **Security** page) and a **repo name** \u2014 everything else is derived. Add\n`--dry-run` to preview every step without writing, pinging, or spawning anything.\n\nTo upgrade later, run:\n\n```bash\nnpx -y @bridge_gpt/mcp-server upgrade\n```\n\n`upgrade` re-execs from `@latest`, refreshes all scaffolded artifacts (slash\ncommands, agents, pipelines), rewrites the version pin, and reconnects \u2014 also\navailable as the `/upgrade-bridge` slash command. (The legacy `--upgrade` flag still\nworks as a fallback.)\n\n<details>\n<summary><strong>Installation Instructions</strong></summary>\n\n#### What `install-bridge` does\n\n`install-bridge` collapses the whole setup into a single command. It:\n\n1. **Scaffolds** the project (the same artifacts `--init` writes: slash commands,\n   agents, `.bridge/pipelines/`, and secret-free MCP config placeholders).\n2. **Writes the per-host MCP config** (`.mcp.json` / `.cursor/mcp.json` /\n   `.vscode/mcp.json`) with your real `BAPI_REPO_NAME` / `BAPI_API_KEY` /\n   `BAPI_BASE_URL` / `BAPI_DOCS_DIR`, preserving any unrelated servers. The\n   launcher it writes is pinned to the exact installed version so `npx` never\n   silently reuses a stale local copy. (Windsurf and Codex are global configs it\n   can\'t safely write \u2014 it prints copy-paste instructions for those.)\n3. **Verifies connectivity** against the Bridge API before persisting anything.\n4. **Persists your key** to the user-scoped credential store\n   (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) so shell-spawned\n   tooling (e.g. `start-tickets`) can resolve it.\n5. **Opens a fresh agent session** that runs `/install-bridge` (to derive the\n   remaining config fields from your codebase) and then `/learn-repository`.\n\nThe only inputs are an **API key** and a **repo name** (everything else is\nderived). Resolution order:\n\n- **API key:** `--api-key <key>` \u2192 `BAPI_API_KEY` env \u2192 an interactive (no-echo)\n  prompt. Generate one first on the Bridge API web UI **Security** page (see\n  [Generate an API Key](#2-generate-an-api-key)); the command consumes a key, it\n  never mints one. The key is **never printed or logged**.\n- **Repo name:** `--repo <name>` \u2192 `BAPI_REPO_NAME` env \u2192 an inferred default you\n  confirm interactively. It MUST match the server-side repository registration.\n\nUseful flags:\n\n- `--dry-run` \u2014 preview every step (scaffold targets, config files and keys with\n  the key value **redacted**, the ping target, the credential store target, and\n  the exact agent spawn command) without writing, pinging, or spawning anything.\n- `--force` \u2014 overwrite an existing real `BAPI_API_KEY` in a host config without\n  prompting (re-running is otherwise non-destructive).\n- `--agent claude|cursor-agent` \u2014 which agent to launch for the agentic remainder\n  (default `claude`).\n\nThat\'s it \u2014 once `install-bridge` finishes you\'re connected. If you prefer to do\nit by hand (or just want to understand each step), the manual flow below does the\nsame thing.\n\n#### Manual Setup (Alternative)\n\n##### 1. Install the Package\n\nFrom your **project root**, install the MCP server and scaffold slash commands:\n\n```bash\nnpm i @bridge_gpt/mcp-server\nnpx -y @bridge_gpt/mcp-server --init\n```\n\n`--init` must be run from the directory containing your `package.json`. It:\n\n- Creates slash commands in `.claude/commands/` and `.cursor/commands/`\n- Detects existing MCP config files and sets `BAPI_PROJECT_ROOT` so local file output resolves correctly\n- Scaffolds `.bridge/pipelines/` for custom pipeline authoring\n\nRe-run `--init` after upgrading the package to get updated commands.\n\n##### 2. Generate an API Key\n\n1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project\'s **Security** page\n2. Click **Create New Key**\n3. Enter your email, an optional label (e.g., "MCP Server"), and select the **Admin** role\n4. Click **Create Key**\n5. **Copy the key immediately** \u2014 it will not be shown again\n\n##### 3. Configure the MCP Server\n\nAdd the following to your editor\'s MCP configuration file, pasting in the API key from step 2:\n\n<details>\n<summary><strong>Claude Code (.mcp.json)</strong></summary>\n\nThe `--init` command (step 1) detects Claude Code and creates a `.mcp.json` at your project root with placeholder values. Open it and replace `your-repo` and `your-api-key` with your actual values from step 2:\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code / Copilot (.vscode/mcp.json)</strong></summary>\n\n```json\n{\n  "servers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Cursor (.cursor/mcp.json)</strong></summary>\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n\n> If project-local config is not supported in your Cursor version, use `~/.cursor/config/mcp.json` instead.\n</details>\n\n<details>\n<summary><strong>Windsurf (~/.codeium/windsurf/mcp_config.json)</strong></summary>\n\nWindsurf only supports global MCP configuration.\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>OpenAI Codex (~/.codex/config.toml)</strong></summary>\n\n```toml\n[mcp_servers.bridge-api]\ncommand = "npx"\nargs = ["-y", "@bridge_gpt/mcp-server"]\n\n[mcp_servers.bridge-api.env]\nBAPI_BASE_URL = "https://bridgegpt-api.com"\nBAPI_REPO_NAME = "your-repo"\nBAPI_API_KEY = "your-api-key"\nBAPI_DOCS_DIR = "docs/tmp"\n```\n\n> Codex users: set `BAPI_PROJECT_ROOT` manually in your config (see Environment Variables below).\n</details>\n\nAfter saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the `ping` tool.\n\n##### 4. First-Time Setup: Teach Bridge Your Codebase\n\nIf you\'re the first person to install Bridge API on your project, run the `/learn-repository` slash command after completing setup. This analyzes your codebase\'s architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project\'s actual architecture and conventions.\n\nYou only need to do this once per project \u2014 the learned standards persist for all team members.\n\n##### Upgrading (details)\n\nThe one-command `npx -y @bridge_gpt/mcp-server upgrade` (shown above) is the\nrecommended path. The legacy flag `npx -y @bridge_gpt/mcp-server --upgrade` still\nworks: it runs `npm i @bridge_gpt/mcp-server@latest`, prints a before/after version\nsummary, then re-runs the full `--init` scaffolding flow to update your slash\ncommands, agents, and pipeline definitions.\n\nThe MCP server also checks for updates automatically on startup. If a newer version is available, you\'ll see a notice in your editor\'s MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.\n\n</details>\n\n## Usage Documentation\n\nThis is the Bridge API tooling worth knowing about as a software engineer \u2014 the things you\'d ask an agent to do \u2014 grouped by how often you would use them. Each entry covers **what it does**, **when it\'s useful** and **how to use it**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).\n\nWorking in a Salesforce B2C Commerce codebase? Bridge also ships read-only SFCC platform-introspection tools \u2014 see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools).\n\nFor invocation, prefer the slash command \u2014 it\'s deterministic. A free-text example is shown only where natural-language phrasing reliably maps to the right automation; high-consequence or easily-misread automations show only the slash command on purpose.\n\n### Tier 1 \u2014 Regularly useful\n\nThese features are useful for most tickets.\n\n**1. Review Ticket**\n- **What it does:** Runs a full quality review of a ticket: clarifying questions + critique plus an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The backend executor now owns all review round orchestration (including the second-opinion round) server-side; pass `--rounds=1` for a cheaper single-pass review, `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend\'s difficulty-adaptive review policy decide.\n- **When it\'s useful:** (Refinement) Right after a ticket is drafted, before anyone starts building \u2014 to surface gaps and tighten it.\n- **How to use it:** `/review-ticket BAPI-123` (command only \u2014 "review" as free text is easily mistaken for a freehand agent review).\n- **Flags:** `--auto` auto-accept findings / skip the approval gates \xB7 `--rounds=1` request a cheaper single-pass review (no second-opinion round) while preserving downstream evaluation and decision-capture work \xB7 `--rounds=2` force the full second-opinion review \xB7 omit `--rounds` to let the backend\'s difficulty-adaptive review policy decide (it falls back to a full second-opinion review when adaptive routing is disabled or the ticket\'s difficulty cannot be resolved).\n- **Multi-ticket fan-out:** `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket for parallel review with no worktrees (terminal launcher only \u2014 no `wt`/`git`). All `/review-ticket` flags apply; `--review KEY=auto,rounds=N` sets per-ticket overrides. Packaged CLI: `npx -y @bridge_gpt/mcp-server review-tickets KEY [KEY ...]`.\n\n**2. Start Tickets**\n- **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.\n- **When it\'s useful:** (Implementation | Automation) When you\'re ready to start building one or more refined tickets concurrently.\n- **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).\n- **Flags:** `--auto` skip the approval gates \xB7 `--base-branch <branch>` branch off something other than the default.\n\n**3. Brainstorm**\n- **What it does:** Fans your problem out to two different LLMs and returns their approaches directly. Runs in one of three modes, selected via `mode`: **`technical`** (default \u2014 implementation/architecture approaches), **`design`** (UI/UX and visual direction), or **`discovery`** (stakeholder discovery questions for early/vague tasks, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`). Discovery needs no extra configuration. The legacy boolean `design=true` still works and maps to `mode: "design"`.\n- **When it\'s useful:** (Architecture | Refinement) Early, when you want a spread of approaches \u2014 `technical` for *how to build it*, `design` for *how it should look*, `discovery` for *what we still need to figure out* before a real ticket exists.\n- **How to use it:** ask your agent to brainstorm \u2014 *"Brainstorm approaches for adding rate limiting to the LLM client; fan it out to multiple models."* For a design pass: *"Run a design brainstorm for the evidence-freshness dashboard UI."* For early discovery: *"Run a discovery brainstorm \u2014 `request_brainstorm` with `mode: "discovery"` \u2014 for this vague request so we can collect the questions stakeholders need to answer first."*\n\n**4. Deep Research**\n- **What it does:** Runs multi-source, fact-checked web research on a technical topic and returns a cited report.\n- **When it\'s useful:** (Architecture | Refinement) When a decision hinges on outside knowledge (libraries, best practices, standards) you don\'t already have.\n- **How to use it:** `/bridge-research <question>`\n\n**5. Jira Ticket Writer**\n- **What it does:** An agent that drafts a well-structured Jira ticket from a plain description, applying your project\'s standards.\n- **When it\'s useful:** (Refinement) When you have an idea in your head and want a properly-formatted ticket draft without writing it by hand.\n- **How to use it:** `/write-ticket <description>` (or ask your agent) \u2014 *"Use the jira ticket writer to turn our conversation into a ticket."*\n- **Flags:** `--standards <path>` apply a specific standards file when drafting.\n\n**6. Upload Ticket**\n- **What it does:** Pushes a drafted ticket up to Jira as a real issue (the `create_ticket` capability); handles markdown and child tickets under an Epic.\n- **When it\'s useful:** (Refinement) The final step after drafting \u2014 to get the ticket into Jira so it can be tracked and worked.\n- **How to use it:** Ask your agent to create the ticket, and it should confirm before creating the live Jira issue.\n- **Options:** Describe the issue type (Bug / Story / Task / Epic) and, for a child under an Epic, the parent key.\n\n### Tier 2 \u2014 Occasionally useful\n\nThese features are good to know, but you probably won\'t use them every day.\n\n**1. Plan Ticket**\n- **What it does:** Generates a step-by-step implementation plan for a ticket, with references to real code files, and saves it locally.\n- **When it\'s useful:** (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before (or instead of) auto-implementing.\n- **How to use it:** `/plan-ticket BAPI-123`\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check the plan with a second provider.\n\n**2. Clarify Ticket**\n- **What it does:** Generates clarifying questions for a ticket (or debugging guidance for bugs) and saves them locally.\n- **When it\'s useful:** (Refinement) When a ticket feels under-specified and you want the open questions made explicit.\n- **How to use it:** `/clarify-ticket BAPI-123` \u2014 *"Generate clarifying questions for BAPI-123"*\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**3. Critique Ticket**\n- **What it does:** Critiques a ticket\'s quality against your project standards and lists deviations + improvements.\n- **When it\'s useful:** (Refinement) When you want a quality gate on a ticket before it\'s worked.\n- **How to use it:** `/critique-ticket BAPI-123` \u2014 *"Critique BAPI-123 against our project standards and list what\'s missing or deviating."*\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**4. Create Doc**\n- **What it does:** Generates a design document for a ticket \u2014 a TDD (technical design, engineer audience), an FSD (functional spec, for product/design/QA), or a PRD (product requirements: problem, goals, success metrics) \u2014 and saves it locally.\n- **When it\'s useful:** (Architecture | Refinement) When a ticket needs a fuller design write-up before planning or implementation, in the shape that fits your audience.\n- **How to use it:** `/create-doc BAPI-123 --doc-type tdd` (or `fsd` / `prd`)\n- **Flags:** `--doc-type tdd|fsd|prd` which document to generate (required) \xB7 `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**5. Explore Ticket**\n- **What it does:** Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.\n- **When it\'s useful:** (Architecture | Refinement) Before writing a ticket or plan, when you\'re unsure how a change would fit the existing code.\n- **How to use it:** `/explore-ticket <task>` \u2014 *"Explore the codebase for how we\'d add a Mistral LLM provider and recommend 2\u20133 implementation options."*\n\n**6. Second Opinion**\n- **What it does:** Gets an immediate critique of any text from a different model family \u2014 no artifact saved, just the reply.\n- **When it\'s useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.\n- **How to use it:** ask your agent \u2014 *"Get a second opinion from Gemini on whether the BAPI-123 plan\'s migration step is safe to run against prod."*\n- **Options:** pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).\n\n**7. Generate Image**\n- **What it does:** Generates an image from a text prompt using a provider image model (OpenAI `gpt-image-2` by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.\n- **When it\'s useful:** (Architecture | Refinement) When you want a quick visual \u2014 a UI mockup, diagram, or illustration \u2014 to anchor a design discussion or attach to a ticket.\n- **How to use it:** ask your agent \u2014 *"Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."*\n- **Options:** `provider` openai (`gpt-image-2`) / gemini (Imagen \u2014 adds an invisible SynthID watermark) \xB7 `quality` low (default, cheapest) / medium / high \xB7 `size` 1024x1024 / 1024x1536 / 1536x1024. The image is always saved to `BAPI_DOCS_DIR/images/` and also returned inline.\n\n**8. Implement Ticket**\n- **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.\n- **When it\'s useful:** (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.\n- **How to use it:** `/implement-ticket BAPI-123` (command only \u2014 "implement X" as free text almost always triggers a freehand build instead of the Bridge plan\u2192code\u2192PR\u2192CI pipeline).\n- **Flags:** `--auto` skip the approval gates (e.g. auto-commit/push).\n\n**9. Full Automation**\n- **What it does:** Drives the whole chain end-to-end: idea \u2192 ticket(s) \u2192 review each \u2192 spawn worktrees to implement.\n- **When it\'s useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.\n- **How to use it:** `/full-automation <idea>` (command only \u2014 creates tickets, spawns worktrees, and carries scheduling/`--max-children` flags that free text can\'t).\n- **Flags:** `--require-approval` toggle the approval gates, full automation runs end to end by default.\n\n**10. Idea to Ticket**\n- **What it does:** Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.\n- **When it\'s useful:** (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.\n- **How to use it:** `/idea-to-ticket <idea>`\n\n### Tier 3 \u2014 Now and then\n\nThese features are useful once in a while, but you probably won\'t need them everyday.\n\n**1. Reimplement Ticket**\n- **What it does:** Pulls in new context/attachments since the last pass and implements small follow-up changes on an already-built ticket.\n- **When it\'s useful:** (Implementation) After review feedback or new screenshots, when you need a targeted second pass rather than a fresh build.\n- **How to use it:** `/reimplement-ticket BAPI-123`\n\n**2. Run Tests**\n- **What it does:** Runs the unit and E2E suites and autonomously triages/fixes failures (via the test-correction agent).\n- **When it\'s useful:** (Implementation) After making changes, to confirm everything passes and auto-fix straightforward breakages.\n- **How to use it:** `/run-tests` (`--unit-only`, `--skip-e2e`)\n\n**3. Plan Epic**\n- **What it does:** Decomposes a large epic into sub-tasks with a structured exploration doc for each.\n- **When it\'s useful:** (Architecture | Refinement) When a feature is too big for one ticket and you need it broken down and scoped.\n- **How to use it:** `/plan-epic <epic>` \u2014 *"Decompose the epic \'migrate PayPal token storage off Custom Objects\' into sub-tasks with an exploration doc for each."*\n\n**4. Update Ticket**\n- **What it does:** Synthesizes a ticket\'s clarifying answers and critique into a rewritten description and pushes it to Jira.\n- **When it\'s useful:** (Refinement) After review, to fold the resolved questions and fixes back into the ticket itself.\n- **How to use it:** `/update-ticket BAPI-123` (command only \u2014 does a full overwrite of the live Jira description; "update" as free text is both vague and hard to reverse).\n\n**5. Get Ticket**\n- **What it does:** Retrieves the full details of a Jira ticket (summary, status, description, etc.).\n- **When it\'s useful:** (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.\n- **How to use it:** ask your agent \u2014 *"Pull up BAPI-123 and show me its description, status, and acceptance criteria."*\n\n**6. Write Comment**\n- **What it does:** Posts a comment on a Jira ticket (markdown; long ones can attach as a file).\n- **When it\'s useful:** (Refinement | Implementation) To leave context, status, or a decision trail on the ticket.\n- **How to use it:** ask your agent \u2014 *"Post a comment on BAPI-123: blocked on the expired Atlassian token \u2014 will retry after it\'s rotated."*\n\n**7. Download / Upload Attachment**\n- **What it does:** Pulls files off a Jira ticket to disk, or attaches a local file to a ticket.\n- **When it\'s useful:** (Refinement | Implementation) When a ticket has design files/logs you need locally, or you want to attach output back to it.\n- **How to use it:** ask your agent \u2014 *"Download the design mockups attached to BAPI-123 into my docs folder."* / *"Attach build-log.txt to BAPI-123."*\n\n**8. Learn Repository**\n- **What it does:** Researches and documents the repo\'s architecture, testing, review, and correctness standards, then saves them to Bridge for future agents.\n- **When it\'s useful:** (Setup/Learning) When onboarding a new repo, or after big changes, so Bridge\'s agents follow your conventions.\n- **How to use it:** `/learn-repository`\n\n**9. Teach Bridge**\n- **What it does:** Takes a plain-English instruction, figures out which standards field it belongs to, and merges it in (admin only).\n- **When it\'s useful:** (Setup/Learning) When you notice the agents missing a convention and want to correct it in one sentence.\n- **How to use it:** `/teach-bridge <teaching>` \u2014 *"Teach Bridge: always use data-testid selectors in E2E tests."*\n\n### Operational commands\n\nWorkflow commands you\'ll reach for during implementation and CI, beyond the tiers above:\n\n| Command | What it does |\n|---|---|\n| `/code-ticket PROJ-123` | Download the implementation plan and questions, then execute the plan inline |\n| `/commit-ticket PROJ-123` | Stage, commit, and push changes; transition Jira status; post a smoke-test comment |\n| `/create-pr PROJ-123` | Commit staged changes and open a pull request |\n| `/check-ci [PROJ-123]` | Monitor CI checks for the current branch, triage failures, apply fixes, and report results |\n| `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |\n| `/check-parse-status` | Check whether a background repository parse job is still running |\n| `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |\n\n> Commands are designed for Claude Code. Other editors may support slash commands differently \u2014 check your editor\'s documentation for how to invoke prompt files.\n\n### Extra Capabilities\n\nBehind-the-scenes capabilities an agent gains from the MCP tools \u2014 mostly invoked automatically by the commands above, rarely requested by name:\n\n- **Ship a PR end-to-end:** commit & push, open a pull request, transition the Jira status, and discover/poll CI checks (powers `commit-ticket`, `create-pr`, `check-ci`, `implement-ticket`).\n- **Architecture plan** for a ticket (design-level guidance, separate from the implementation plan).\n- **Index the codebase** so Bridge\'s agents can reason about it: queue/parse the repo, check parse status, regenerate the directory map.\n- **Read & tune project config/standards:** list/read/update config fields, fetch project standards, and the per-topic `learn-*` commands that populate them.\n- **Ticket lifecycle bookkeeping:** track tickets and backfill workflow-state timestamps (`scan-tickets`), search across tickets, read comments, list attachments.\n- **Pipeline machinery:** list/inspect pipeline recipes and run/resume/list/delete pipeline runs (the engine under the orchestration commands).\n- **Decision page** generation for capturing human review decisions as structured data.\n- **Connectivity & identity checks:** ping Bridge, check your role, resolve the local docs directory.\n- **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, brainstorms, research, architecture) without regenerating it.\n- **Tiered-section execution telemetry** recording (internal measurement).\n\n## Salesforce B2C Commerce (SFCC) Tools\n\nSalesforce\'s official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks \u2014 cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform\'s object model, custom objects, or site configuration \u2014 exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge\'s SFCC tools install side-by-side with `b2c-dx-mcp` (they don\'t duplicate its surface) and close that gap with **read-only OCAPI Data API introspection** of system objects, custom object definitions, and site preferences.\n\n**v1 is read-only and developer-sandbox-only** \u2014 no writes, and non-sandbox instances are rejected. Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to Bridge.\n\n<details>\n<summary><strong>Setup</strong></summary>\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The seven read tools must be enabled with a profile (step 3).\n\n**Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).\n\n**1. Set the repo `version` config field** to your SFCC project type \u2014 one of `sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this; a non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your normal config path, the `config_field` MCP tool (operation `update`, field `version`), or the `/teach-bridge` skill.\n\n**2. Provide SFCC credentials.** Create a `dw.json` in your project root:\n\n```json\n{\n  "hostname": "zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com",\n  "client-id": "<account-manager-client-id>",\n  "client-secret": "<account-manager-client-secret>"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. Prefer a single config \u2014 a multi-entry `configs[]` array forces you to pass an explicit `instance` on every call. `dw.json` is auto-added to git exclude and must never be committed. Alternatively, export `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n**3. Enable the read tools.** Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated; `full` also works), then **restart the MCP client**:\n\n```json\n"env": { "BRIDGE_MCP_PROFILE": "sfcc" }\n```\n\nWithout this, only the diagnostic tools are registered.\n\n**4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks \u2713), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration \u2192 Site Development \u2192 Open Commerce API Settings \u2192 Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change \u2014 a running session does not pick them up.\n\n</details>\n\n### Tools\n\nAll SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.\n\n**Diagnostics** (always available, no profile needed)\n- `sfcc_setup_status` \u2014 report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, and AM token acquisition.\n- `check_permissions` \u2014 probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).\n\n**System object model** (needs the `sfcc` profile)\n- `system_object_list` \u2014 list system object types (Product, Order, Customer, \u2026).\n- `system_object_get` \u2014 fetch one type\'s definition, optionally with its full attribute definitions (`expand_attribute_definitions`).\n- `system_object_attribute_search` \u2014 search a type\'s attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.\n\n**Custom object definitions** (needs the `sfcc` profile)\n- `custom_object_definition_attributes_get` \u2014 fetch attribute definitions for a known custom object type. OCAPI cannot enumerate custom object types, so `object_type` must already be known.\n- `custom_object_definition_attribute_search` \u2014 search attribute definitions within a known custom object type. Read-only \u2014 creating a custom object *type* isn\'t possible via OCAPI; that\'s a future v2 metadata-import capability.\n- `custom_object_definition_attribute_create` \u2014 **write** (sandbox only): create an attribute definition on a known custom object type via `PUT /custom_object_definitions/{type}/attribute_definitions/{id}`. TYPE creation is never attempted (the type must pre-exist). Echoes paste-ready OCAPI grant JSON on 403.\n- `custom_object_definition_attribute_update` \u2014 **write** (sandbox only): update an attribute definition via an ETag-conditional `PATCH \u2026/attribute_definitions/{id}`; surfaces 409/412 conflicts and echoes grant JSON on 403.\n\n**Site preferences** (needs the `sfcc` profile; sandbox only)\n- `site_preference_get` \u2014 read a preference group\'s effective preferences.\n- `site_preference_search` \u2014 search/filter preferences within a group.\n- `site_preference_values_set` \u2014 **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.\n\n## CLI Subcommands\n\nBeyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) \u2014 so they travel with the package to every consumer. See [Usage Documentation \u2192 Start Tickets](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.\n\n### `start-tickets`\n\nSpawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the `/start-tickets` slash command. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`.\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--agent claude\\|cursor-agent` | `claude` | Agent command to launch in each worktree |\n| `--terminal terminal\\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |\n| `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |\n| `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |\n| `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |\n| `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility \u2014 despite the name, it now skips refresh of whatever `--base-branch` resolves to. |\n| `--max-parallel N` | `3` | Max worktrees created concurrently |\n| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, a supervisor peer tab, and the `check_messages` message-relay prompt). **Default off** \u2014 a plain run spawns `cd <worktree> && <agent> \'/implement-ticket <KEY>\'`. |\n| `-h`, `--help` | \u2014 | Show usage |\n\nEach `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent\'s `\'/implement-ticket <KEY>\'` \u2014 `claude \'/implement-ticket <KEY>\'` by default, or `cursor-agent \'/implement-ticket <KEY>\'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248\n```\n\n**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket\'s `difficulty` (1-2 \u2192 cheap, 3-5 \u2192 basic, 6+ \u2192 premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier \u2192 alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all omit `--model` (the agent uses its default) and surface a per-ticket warning rather than failing the spawn. `--dry-run` does **not** fetch tiers or inject `--model`.\n\n**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort \u2014 a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.\n\n**Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.\n\n- **macOS** \u2014 opens a Terminal.app or iTerm tab via `osascript`.\n- **Windows** \u2014 creates worktrees with **`git-wt`** (Worktrunk\'s winget alias) and opens a tab via **Windows Terminal (`wt.exe new-tab`)**, falling back to **`Start-Process powershell.exe`** when Windows Terminal is absent. Requires **Git for Windows / Git Bash** (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash). The Worktrunk binary (`git-wt`) and the tab launcher (`wt.exe`) are resolved independently and never conflated.\n- **Linux** \u2014 creates one detached **tmux** session per ticket (pane kept open after the agent exits); attach with `tmux attach -t <session>`. A missing `tmux` produces a clear, actionable error.\n\nPer-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` \u2014 Worktrunk\'s `pre-start` hook runs `uv`, but live preflight does not check it \u2014 and the selected agent\'s command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).\n\n### `doctor`\n\nThe package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:\n\n```\nnpx -y @bridge_gpt/mcp-server doctor [--agent <name>]\n```\n\nIt is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent\'s command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.\n\n### Conductor (epic & multi-agent orchestration)\n\nConductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference \u2014 `conductor install-git-hooks`, the `conductor_done_gate` and `conductor_auto_merge_enabled` config fields, and the observability stream \u2014 lives in **[CONDUCTOR.md](./CONDUCTOR.md)**.\n\n## Custom Pipelines\n\nYou can create your own pipelines by adding JSON files to `.bridge/pipelines/`. Running `--init` scaffolds this directory with a `README.md` and an example pipeline to get you started.\n\nThe easiest way to write a custom pipeline is to describe what you want to automate to your AI coding agent and have it draft the JSON for you. The schema is straightforward, and agents like Claude Code understand it well \u2014 just describe the steps you want, and the agent will produce a working pipeline file.\n\n**What you can build:**\n\n- Any sequence of Bridge MCP tool calls and free-form agent tasks\n- Parameterized workflows using variables (e.g., `{ticket_key}`)\n- Approval gates that pause for user confirmation before sensitive steps\n- Per-step error handling \u2014 halt immediately or warn and continue\n\n**Ideas for custom pipelines:**\n\n- A standup pipeline that fetches your open tickets and summarizes their status\n- A ticket triage pipeline that runs critiques on a batch of new tickets\n- A pre-merge checklist that runs tests, checks linting, and posts a summary comment\n\n**Step types:**\n\n| Type | What it does |\n|---|---|\n| `mcp_call` | Calls an MCP tool with the given params |\n| `agent_task` | Gives the AI a free-form instruction (inline or from a file in `.bridge/instructions/`) |\n\nVariables are declared in the `variables` array and referenced as `{variable_name}` in params and instructions. Each step supports `on_error: "halt"` (default) or `"warn_and_continue"`, and `requires_approval: true` to pause before execution.\n\n**System variables:**\n\nTwo variables are automatically available in every pipeline without declaring them:\n\n| Variable | What it does |\n|---|---|\n| `{provider}` | Routes AI generation to a specific LLM provider (`openai`, `anthropic`, or `gemini`). Pass it through to any `request_*` tool param to control which provider handles that step. Omit it (or leave it empty) to use the project default. |\n| `{second_opinion}` | Runs AI generation through a different provider than the default, acting as a cross-check. Set to `"auto"` to let Bridge pick the second provider automatically. When set, it takes precedence over `{provider}`. Use this when you want two independent AI perspectives on the same task \u2014 for example, running clarifying questions and a critique twice (once with each provider) produces better results than a single pass. |\n\nSee `.bridge/pipelines/README.md` for the full schema reference.\n\nIf a custom pipeline has the same key as a built-in pipeline, the custom version takes precedence (a warning is logged at startup).\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `BAPI_BASE_URL` | Yes | `https://bridgegpt-api.com` | Bridge API base URL |\n| `BAPI_REPO_NAME` | Yes | _(none)_ | Jira project/repository identifier configured in Bridge API |\n| `BAPI_API_KEY` | Yes | _(none)_ | API key obtained from the Bridge API setup UI |\n| `BAPI_PROJECT_ROOT` | No | _(auto-set by --init)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution |\n| `BAPI_DOCS_DIR` | No | `docs/tmp` | Local directory for saving plans, critiques, and research reports |\n| `BAPI_PIPELINES_DIR` | No | `.bridge/pipelines` | Directory for user-defined custom pipeline JSON files |\n| `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |\n| `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |\n| `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation \u2014 it only gates the recipe-preamble convention |\n| `CURSOR_API_KEY` | No | _(none)_ | API key used to authenticate `cursor-agent` when launching `start-tickets`/scheduled runs with `--agent cursor-agent`. Not needed for the default Claude Code agent |\n| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile \u2014 a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default \u2014 normal coding tools only), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools \u2014 `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 7 heavy SFCC read tools \u2014 see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), and `full` (shortcut that expands to every group). Example: `sfcc,conductor`. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported \u2014 groups are resolved once at process startup. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |\n\n## Worktree credentials and the `mcp-invoke` shim\n\nWhen `start-tickets` creates a git worktree, it provisions a Bridge API MCP\nregistration into that worktree so Claude Code (`.mcp.json`) and Cursor\n(`.cursor/mcp.json`) can reach the server immediately. These registrations are\n**secret-free**: they contain no `env` block and no API key. Instead they point\nat an internal subcommand of the published single CLI bin, `mcp-invoke`:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@<VERSION> mcp-invoke --target bapi --project-root <ABS_WORKTREE_PATH>\n```\n\n`mcp-invoke` is not a separate binary \u2014 it is a positional subcommand of\n`bridge-api-mcp-server`. It resolves the repo identity from the absolute\n`--project-root` (the committed `.bridge/config` manifest, falling back to the\ngit common dir), resolves credentials from the home-directory credential store,\nand then spawns the real MCP server with that environment.\n\n### Credential store\n\nCredentials live outside the repository, keyed by `bapi:<repo_name>`:\n\n```json\n{\n  "bapi:<repo_name>": {\n    "BAPI_API_KEY": "..."\n  }\n}\n```\n\nResolution order:\n\n1. `BAPI_API_KEY` in the parent environment (overrides the file entirely).\n2. `$XDG_CONFIG_HOME/bridge/credentials.json`, else `~/.config/bridge/credentials.json`.\n3. `~/.bridge/credentials.json` (only when the primary path is absent).\n\nOn POSIX systems, lock the file down so only you can read it:\n\n```bash\nchmod 600 ~/.config/bridge/credentials.json\n```\n\n`mcp-invoke` warns (but continues) if the file is group/world-readable, and it\nnever creates or initializes the credential file for you.\n\n### Populating the credential store\n\nThe same store also backs the shell-spawned `start-tickets` CLI (its\ndifficulty\u2192model routing runs in a Bash process that cannot see an `env` block in\n`.mcp.json` / `.cursor/mcp.json`), so the store must hold the key for routing to\nwork. Two supported paths write it for you:\n\n- **Install-time upsert.** `/install-bridge`\'s final stage persists the validated\n  routing credential into `~/.config/bridge/credentials.json` (target\n  `bapi:<repo>`) via the `persist_routing_credential` MCP tool \u2014 the tool resolves\n  the key inside the MCP process and writes the store, so no secret crosses the\n  wire.\n- **One-shot migration.** If a key currently lives only in `.mcp.json` /\n  `.cursor/mcp.json`, migrate it into the user-scoped store with the consent-gated\n  command (a compatibility aid, not a live fallback):\n\n  ```bash\n  npx -y @bridge_gpt/mcp-server credentials migrate-agent-config [--write-credentials]\n  ```\n\n  Run it without `--write-credentials` to preview; add the flag to write the store.\n\n## Reference\n\nThe full surface, for when you need the complete enumeration. Day-to-day, use [Usage Documentation](#usage-documentation) instead \u2014 you don\'t call MCP tools directly; you ask your AI assistant to perform a task, or compose tools into a pipeline.\n\n### MCP tools\n\nThe server exposes **59 documented tools** (enumerated below). What\'s actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).\n\n- **Connectivity & identity** \u2014 `ping`, `get_my_role`, `get_docs_dir`\n- **Jira tickets** \u2014 `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`\n- **Attachments** \u2014 `attachment` (operations: `upload`, `download`, `list`)\n- **AI generation (request/get)** \u2014 `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`\n- **Other AI** \u2014 `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)\n- **Ticket lifecycle** \u2014 `track_ticket`, `update_ticket_state`, `get_ticket_state`\n- **Jira status** \u2014 `get_jira_transitions`, `update_jira_status`, `resolve_target_status`\n- **Repository & CI** \u2014 `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`\n- **Pipelines & automation** \u2014 `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`\n- **Config** \u2014 `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)\n\n### Bundled pipelines\n\nPipelines are declarative, multi-step workflows your AI agent executes step-by-step \u2014 each a JSON recipe chaining MCP tool calls and free-form agent tasks, with variable substitution, per-step error handling, and optional approval gates. You can also write your own (see [Custom Pipelines](#custom-pipelines)).\n\n| Pipeline | Description | Invoke with |\n|---|---|---|\n| `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |\n| `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. | `/review-ticket PROJ-123` |\n| `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |\n| `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |\n| `full-automation` | Chain: idea \u2192 ticket(s) \u2192 review each \u2192 spawn worktrees to implement | `/full-automation "<idea>"` |\n| `pr-ticket` | Commit changes and open a pull request | `/create-pr PROJ-123` |\n| `check-ci-ticket` | Commit, open a PR, then monitor CI checks until they pass or fail | `/check-ci PROJ-123` |\n| `learn-repository` | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | `/learn-repository` |\n\n### Pipeline response envelope\n\n`run_pipeline`, `resume_pipeline`, and `list_pipeline_runs` share a unified envelope keyed on `status`:\n\n- `completed` \u2014 terminal success; `results` holds per-step output.\n- `needs_agent_task` \u2014 the orchestrator paused. Read `instruction`, perform the task, then call `resume_pipeline` with `pipeline_run_id` and a string `agent_result`.\n- `failed` \u2014 terminal failure. `error_code` is one of `VALIDATION`, `NOT_FOUND`, `EXPIRED`, `REPO_MISMATCH`, `TOOL_ERROR`.\n\nPaused runs auto-expire after an idle TTL (default 24 hours; override with `ttl_seconds`). The TTL is reset on every state transition. List output is metadata-only \u2014 it never includes resolved recipes, params, instructions, results, or agent outputs.\n';
+var README = '# @bridge_gpt/mcp-server\n\nThe Bridge MCP is an end-to-end accelerator for shipping code within SFCC, powered by [Bridge API](https://bridgegpt-api.com). Works with Claude Code, Github Copilot, Cursor, Windsurf, and OpenAI Codex.\n\n## Contents\n\n- [Getting Started](#getting-started)\n- [Usage Documentation](#usage-documentation)\n  - [Tier 1 \u2014 Regularly useful](#tier-1--regularly-useful)\n  - [Tier 2 \u2014 Occasionally useful](#tier-2--occasionally-useful)\n  - [Tier 3 \u2014 Now and then](#tier-3--now-and-then)\n  - [Operational commands](#operational-commands)\n  - [Extra Capabilities](#extra-capabilities)\n- [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)\n- [CLI Subcommands](#cli-subcommands)\n- [Custom Pipelines](#custom-pipelines)\n- [Environment Variables](#environment-variables)\n- [Worktree credentials and the `mcp-invoke` shim](#worktree-credentials-and-the-mcp-invoke-shim)\n- [Reference](#reference)\n\nFor advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./CONDUCTOR.md).\n\n## Getting Started\n\n### Quick start\n\nFrom your **project root**, install and connect in one command:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge\n```\n\n`install-bridge` scaffolds the project, writes your editor\'s MCP config with real\nvalues, verifies connectivity, persists your API key to the user-scoped credential\nstore, and opens a fresh agent session to finish setup (`/install-bridge` then\n`/learn-repository`). The only inputs are an **API key** (generate one on the Bridge\nAPI web UI **Security** page) and a **repo name** \u2014 everything else is derived. Add\n`--dry-run` to preview every step without writing, pinging, or spawning anything.\n\n**Were you sent a bootstrap invite?** Then you don\'t need an API key or the web UI\nat all \u2014 run the command your operator gave you:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge --invite\n```\n\nThat one-liner is deliberately **secret-free**: the CLI prompts for the bootstrap\ninvite token with **echo suppressed**, and sends it only in the request body. It\ncreates your project and mints your own admin API key in a single command.\n\nTo upgrade later, run:\n\n```bash\nnpx -y @bridge_gpt/mcp-server upgrade\n```\n\n`upgrade` re-execs from `@latest`, refreshes all scaffolded artifacts (slash\ncommands, agents, pipelines), rewrites the version pin, and reconnects \u2014 also\navailable as the `/upgrade-bridge` slash command. (The legacy `--upgrade` flag still\nworks as a fallback.)\n\n<details>\n<summary><strong>Installation Instructions</strong></summary>\n\n#### What `install-bridge` does\n\n`install-bridge` collapses the whole setup into a single command. It:\n\n1. **Scaffolds** the project (the same artifacts `--init` writes: slash commands,\n   agents, `.bridge/pipelines/`, and secret-free MCP config placeholders).\n2. **Writes the per-host MCP config** (`.mcp.json` / `.cursor/mcp.json` /\n   `.vscode/mcp.json`) with your real `BAPI_REPO_NAME` / `BAPI_API_KEY` /\n   `BAPI_BASE_URL` / `BAPI_DOCS_DIR`, preserving any unrelated servers. The\n   launcher it writes is pinned to the exact installed version so `npx` never\n   silently reuses a stale local copy. (Windsurf and Codex are global configs it\n   can\'t safely write \u2014 it prints copy-paste instructions for those.)\n3. **Verifies connectivity** against the Bridge API before persisting anything.\n4. **Persists your key** to the user-scoped credential store\n   (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) so shell-spawned\n   tooling (e.g. `start-tickets`) can resolve it.\n5. **Opens a fresh agent session** that runs `/install-bridge` (to derive the\n   remaining config fields from your codebase) and then `/learn-repository`.\n\nThe only inputs are an **API key** and a **repo name** (everything else is\nderived). Resolution order:\n\n- **API key:** `--api-key <key>` \u2192 `BAPI_API_KEY` env \u2192 an interactive (no-echo)\n  prompt. Generate one first on the Bridge API web UI **Security** page (see\n  [Generate an API Key](#2-generate-an-api-key)); the command consumes a key, it\n  never mints one \u2014 **`--invite` is the one exception** (below). The key is\n  **never printed or logged**.\n- **Repo name:** `--repo <name>` \u2192 `BAPI_REPO_NAME` env \u2192 an inferred default you\n  confirm interactively. It MUST match the server-side repository registration.\n\n#### Bootstrap-invite onboarding (`--invite`)\n\nWith a **bootstrap invite** there is no pre-existing key and no web UI: this is the\none mode where `install-bridge` **creates** the project and its first admin key\ninstead of consuming one. Run `install-bridge --invite` and it:\n\n1. **Prompts for the bootstrap invite token** with echo suppressed (the default \u2014\n   see below).\n2. **Generates your `key_secret`** (32 CSPRNG bytes) and **fsyncs it locally**\n   *before* contacting the server. If that write fails the run aborts and the\n   invite is **not** spent.\n3. **Redeems the invite** \u2014 `POST /setup/bootstrap` with the token, repo name, and\n   `key_secret` in the **body** \u2014 which creates the project and mints your admin\n   key. (This replaces the connectivity ping: there is no key to ping with yet.)\n4. **Verifies the newly-minted key**, then writes the per-host MCP config.\n5. **Promotes the credential** to `bapi:<repo>` and **opens the agent session** \u2014\n   the same Steps 3\u20135 as the normal flow.\n\nBecause the locally-saved `key_secret` is the only proof that can replay a\nredemption, a re-run after a network failure is safe: it re-sends the *same* secret\nand gets back the *same* project and key. If the repo name you chose is already\ntaken (names are globally unique) the server rolls back \u2014 your invite is untouched \u2014\nand the CLI asks for a different name and retries with the same token.\n\n**The delivered one-liner is secret-free, by design.** "A copy/paste one-liner" and\n"the token never touches shell history" are contradictory, so the token is *not* in\nthe command: the CLI asks for it, and it travels only in the request body.\n`--invite <token>`, `--invite=<token>`, and `BAPI_INVITE` still work for\n**scripting only** \u2014 and both forms **expose the token to your shell history and to\nthe process list**. Prefer the prompt.\n\nUseful flags:\n\n- `--dry-run` \u2014 preview every step (scaffold targets, config files and keys with\n  the key value **redacted**, the ping target, the credential store target, and\n  the exact agent spawn command) without writing, pinging, or spawning anything.\n  With `--invite` it also never calls the exchange endpoint and never generates or\n  stores a secret.\n- `--force` \u2014 overwrite an existing real `BAPI_API_KEY` in a host config, or in the\n  credential store, without prompting (re-running is otherwise non-destructive).\n- `--agent claude|cursor-agent` \u2014 which agent to launch for the agentic remainder\n  (default `claude`).\n- `--invite [token]` \u2014 redeem a bootstrap invite (mutually exclusive with\n  `--api-key`). Omit the value to get the hidden prompt.\n\nThat\'s it \u2014 once `install-bridge` finishes you\'re connected. If you prefer to do\nit by hand (or just want to understand each step), the manual flow below does the\nsame thing.\n\n#### Manual Setup (Alternative)\n\n##### 1. Install the Package\n\nFrom your **project root**, install the MCP server and scaffold slash commands:\n\n```bash\nnpm i @bridge_gpt/mcp-server\nnpx -y @bridge_gpt/mcp-server --init\n```\n\n`--init` must be run from the directory containing your `package.json`. It:\n\n- Creates slash commands in `.claude/commands/` and `.cursor/commands/`\n- Detects existing MCP config files and sets `BAPI_PROJECT_ROOT` so local file output resolves correctly\n- Scaffolds `.bridge/pipelines/` for custom pipeline authoring\n\nRe-run `--init` after upgrading the package to get updated commands.\n\n##### 2. Generate an API Key\n\n1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project\'s **Security** page\n2. Click **Create New Key**\n3. Enter your email, an optional label (e.g., "MCP Server"), and select the **Admin** role\n4. Click **Create Key**\n5. **Copy the key immediately** \u2014 it will not be shown again\n\n##### 3. Configure the MCP Server\n\nAdd the following to your editor\'s MCP configuration file, pasting in the API key from step 2:\n\n<details>\n<summary><strong>Claude Code (.mcp.json)</strong></summary>\n\nThe `--init` command (step 1) detects Claude Code and creates a `.mcp.json` at your project root with placeholder values. Open it and replace `your-repo` and `your-api-key` with your actual values from step 2:\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code / Copilot (.vscode/mcp.json)</strong></summary>\n\n```json\n{\n  "servers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Cursor (.cursor/mcp.json)</strong></summary>\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n\n> If project-local config is not supported in your Cursor version, use `~/.cursor/config/mcp.json` instead.\n</details>\n\n<details>\n<summary><strong>Windsurf (~/.codeium/windsurf/mcp_config.json)</strong></summary>\n\nWindsurf only supports global MCP configuration.\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>OpenAI Codex (~/.codex/config.toml)</strong></summary>\n\n```toml\n[mcp_servers.bridge-api]\ncommand = "npx"\nargs = ["-y", "@bridge_gpt/mcp-server"]\n\n[mcp_servers.bridge-api.env]\nBAPI_BASE_URL = "https://bridgegpt-api.com"\nBAPI_REPO_NAME = "your-repo"\nBAPI_API_KEY = "your-api-key"\nBAPI_DOCS_DIR = "docs/tmp"\n```\n\n> Codex users: set `BAPI_PROJECT_ROOT` manually in your config (see Environment Variables below).\n</details>\n\nAfter saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the `ping` tool.\n\n##### 4. First-Time Setup: Teach Bridge Your Codebase\n\nIf you\'re the first person to install Bridge API on your project, run the `/learn-repository` slash command after completing setup. This analyzes your codebase\'s architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project\'s actual architecture and conventions.\n\nYou only need to do this once per project \u2014 the learned standards persist for all team members.\n\n##### Upgrading (details)\n\nThe one-command `npx -y @bridge_gpt/mcp-server upgrade` (shown above) is the\nrecommended path. The legacy flag `npx -y @bridge_gpt/mcp-server --upgrade` still\nworks: it runs `npm i @bridge_gpt/mcp-server@latest`, prints a before/after version\nsummary, then re-runs the full `--init` scaffolding flow to update your slash\ncommands, agents, and pipeline definitions.\n\nThe MCP server also checks for updates automatically on startup. If a newer version is available, you\'ll see a notice in your editor\'s MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.\n\n</details>\n\n## Usage Documentation\n\nThis is the Bridge API tooling worth knowing about as a software engineer \u2014 the things you\'d ask an agent to do \u2014 grouped by how often you would use them. Each entry covers **what it does**, **when it\'s useful** and **how to use it**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).\n\nWorking in a Salesforce B2C Commerce codebase? Bridge also ships read-only SFCC platform-introspection tools \u2014 see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools).\n\nFor invocation, prefer the slash command \u2014 it\'s deterministic. A free-text example is shown only where natural-language phrasing reliably maps to the right automation; high-consequence or easily-misread automations show only the slash command on purpose.\n\n### Tier 1 \u2014 Regularly useful\n\nThese features are useful for most tickets.\n\n**1. Review Ticket**\n- **What it does:** Runs a full quality review of a ticket: clarifying questions + critique plus an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The backend executor now owns all review round orchestration (including the second-opinion round) server-side; pass `--rounds=1` for a cheaper single-pass review, `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend\'s difficulty-adaptive review policy decide.\n- **When it\'s useful:** (Refinement) Right after a ticket is drafted, before anyone starts building \u2014 to surface gaps and tighten it.\n- **How to use it:** `/review-ticket BAPI-123` (command only \u2014 "review" as free text is easily mistaken for a freehand agent review).\n- **Flags:** `--auto` auto-accept findings / skip the approval gates \xB7 `--rounds=1` request a cheaper single-pass review (no second-opinion round) while preserving downstream evaluation and decision-capture work \xB7 `--rounds=2` force the full second-opinion review \xB7 omit `--rounds` to let the backend\'s difficulty-adaptive review policy decide (it falls back to a full second-opinion review when adaptive routing is disabled or the ticket\'s difficulty cannot be resolved).\n- **Multi-ticket fan-out:** `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket for parallel review with no worktrees (terminal launcher only \u2014 no `wt`/`git`). All `/review-ticket` flags apply; `--review KEY=auto,rounds=N` sets per-ticket overrides. Packaged CLI: `npx -y @bridge_gpt/mcp-server review-tickets KEY [KEY ...]`.\n\n**2. Start Tickets**\n- **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.\n- **When it\'s useful:** (Implementation | Automation) When you\'re ready to start building one or more refined tickets concurrently.\n- **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).\n- **Flags:** `--auto` skip the approval gates \xB7 `--base-branch <branch>` branch off something other than the default \xB7 `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs (default `implement`, byte-identical to today; `review-and-implement` runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session) \xB7 `--rounds=1|2` review-only, forwarded to the review phase, valid only with `--workflow review-and-implement`.\n\n**2b. Review and Start**\n- **What it does:** Spawns one worktree per ticket, each running review then (after a per-ticket human proceed/halt gate) implementation \u2014 the chained `review \u2192 gate \u2192 implement` composition.\n- **When it\'s useful:** (Refinement | Implementation | Automation) The **recommended front door** for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike `/full-automation`, which only accepts an idea).\n- **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).\n- **Flags:** `--auto` a single chain-level flag that auto-approves both the review and the implementation phase of every spawned session \xB7 `--rounds=1|2` forwarded to the review phase \xB7 `--agent`, `--base-branch`, `--max-parallel`, `--dry-run` mirror `/start-tickets`.\n- Under the hood, this is a thin shim over `start-tickets --workflow review-and-implement <KEYS>` \u2014 the lower-level launcher seam documented above; the halt-gate decision logic lives in the spawned `/review-and-implement` session, never in this command or the CLI.\n\n**3. Brainstorm**\n- **What it does:** Fans your problem out to two different LLMs and returns their approaches directly. Runs in one of three modes, selected via `mode`: **`technical`** (default \u2014 implementation/architecture approaches), **`design`** (UI/UX and visual direction), or **`discovery`** (stakeholder discovery questions for early/vague tasks, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`). Discovery needs no extra configuration. The legacy boolean `design=true` still works and maps to `mode: "design"`.\n- **When it\'s useful:** (Architecture | Refinement) Early, when you want a spread of approaches \u2014 `technical` for *how to build it*, `design` for *how it should look*, `discovery` for *what we still need to figure out* before a real ticket exists.\n- **How to use it:** ask your agent to brainstorm \u2014 *"Brainstorm approaches for adding rate limiting to the LLM client; fan it out to multiple models."* For a design pass: *"Run a design brainstorm for the evidence-freshness dashboard UI."* For early discovery: *"Run a discovery brainstorm \u2014 `request_brainstorm` with `mode: "discovery"` \u2014 for this vague request so we can collect the questions stakeholders need to answer first."*\n\n**4. Deep Research**\n- **What it does:** Runs multi-source, fact-checked web research on a technical topic and returns a cited report.\n- **When it\'s useful:** (Architecture | Refinement) When a decision hinges on outside knowledge (libraries, best practices, standards) you don\'t already have.\n- **How to use it:** `/bridge-research <question>`\n\n**5. Jira Ticket Writer**\n- **What it does:** An agent that drafts a well-structured Jira ticket from a plain description, applying your project\'s standards.\n- **When it\'s useful:** (Refinement) When you have an idea in your head and want a properly-formatted ticket draft without writing it by hand.\n- **How to use it:** `/write-ticket <description>` (or ask your agent) \u2014 *"Use the jira ticket writer to turn our conversation into a ticket."*\n- **Flags:** `--standards <path>` apply a specific standards file when drafting.\n\n**6. Upload Ticket**\n- **What it does:** Pushes a drafted ticket up to Jira as a real issue (the `create_ticket` capability); handles markdown and child tickets under an Epic.\n- **When it\'s useful:** (Refinement) The final step after drafting \u2014 to get the ticket into Jira so it can be tracked and worked.\n- **How to use it:** Ask your agent to create the ticket, and it should confirm before creating the live Jira issue.\n- **Options:** Describe the issue type (Bug / Story / Task / Epic) and, for a child under an Epic, the parent key.\n\n### Tier 2 \u2014 Occasionally useful\n\nThese features are good to know, but you probably won\'t use them every day.\n\n**1. Plan Ticket**\n- **What it does:** Generates a step-by-step implementation plan for a ticket, with references to real code files, and saves it locally.\n- **When it\'s useful:** (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before (or instead of) auto-implementing.\n- **How to use it:** `/plan-ticket BAPI-123`\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check the plan with a second provider.\n\n**2. Clarify Ticket**\n- **What it does:** Generates clarifying questions for a ticket (or debugging guidance for bugs) and saves them locally.\n- **When it\'s useful:** (Refinement) When a ticket feels under-specified and you want the open questions made explicit.\n- **How to use it:** `/clarify-ticket BAPI-123` \u2014 *"Generate clarifying questions for BAPI-123"*\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**3. Critique Ticket**\n- **What it does:** Critiques a ticket\'s quality against your project standards and lists deviations + improvements.\n- **When it\'s useful:** (Refinement) When you want a quality gate on a ticket before it\'s worked.\n- **How to use it:** `/critique-ticket BAPI-123` \u2014 *"Critique BAPI-123 against our project standards and list what\'s missing or deviating."*\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**4. Create Doc**\n- **What it does:** Generates a design document for a ticket \u2014 a TDD (technical design, engineer audience), an FSD (functional spec, for product/design/QA), or a PRD (product requirements: problem, goals, success metrics) \u2014 and saves it locally.\n- **When it\'s useful:** (Architecture | Refinement) When a ticket needs a fuller design write-up before planning or implementation, in the shape that fits your audience.\n- **How to use it:** `/create-doc BAPI-123 --doc-type tdd` (or `fsd` / `prd`)\n- **Flags:** `--doc-type tdd|fsd|prd` which document to generate (required) \xB7 `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**5. Explore Ticket**\n- **What it does:** Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.\n- **When it\'s useful:** (Architecture | Refinement) Before writing a ticket or plan, when you\'re unsure how a change would fit the existing code.\n- **How to use it:** `/explore-ticket <task>` \u2014 *"Explore the codebase for how we\'d add a Mistral LLM provider and recommend 2\u20133 implementation options."*\n\n**6. Second Opinion**\n- **What it does:** Gets an immediate critique of any text from a different model family \u2014 no artifact saved, just the reply.\n- **When it\'s useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.\n- **How to use it:** ask your agent \u2014 *"Get a second opinion from Gemini on whether the BAPI-123 plan\'s migration step is safe to run against prod."*\n- **Options:** pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).\n\n**7. Generate Image**\n- **What it does:** Generates an image from a text prompt using a provider image model (OpenAI `gpt-image-2` by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.\n- **When it\'s useful:** (Architecture | Refinement) When you want a quick visual \u2014 a UI mockup, diagram, or illustration \u2014 to anchor a design discussion or attach to a ticket.\n- **How to use it:** ask your agent \u2014 *"Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."*\n- **Options:** `provider` openai (`gpt-image-2`) / gemini (Imagen \u2014 adds an invisible SynthID watermark) \xB7 `quality` low (default, cheapest) / medium / high \xB7 `size` 1024x1024 / 1024x1536 / 1536x1024. The image is always saved to `BAPI_DOCS_DIR/images/` and also returned inline.\n\n**8. Implement Ticket**\n- **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.\n- **When it\'s useful:** (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.\n- **How to use it:** `/implement-ticket BAPI-123` (command only \u2014 "implement X" as free text almost always triggers a freehand build instead of the Bridge plan\u2192code\u2192PR\u2192CI pipeline).\n- **Flags:** `--auto` skip the approval gates (e.g. auto-commit/push).\n\n**9. Full Automation**\n- **What it does:** Drives the whole chain end-to-end: idea \u2192 ticket(s) \u2192 review each \u2192 spawn worktrees to implement.\n- **When it\'s useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.\n- **How to use it:** `/full-automation <idea>` (command only \u2014 creates tickets, spawns worktrees, and carries scheduling/`--max-children` flags that free text can\'t).\n- **Flags:** `--require-approval` toggle the approval gates, full automation runs end to end by default.\n\n**10. Idea to Ticket**\n- **What it does:** Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.\n- **When it\'s useful:** (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.\n- **How to use it:** `/idea-to-ticket <idea>`\n\n### Tier 3 \u2014 Now and then\n\nThese features are useful once in a while, but you probably won\'t need them everyday.\n\n**1. Reimplement Ticket**\n- **What it does:** Pulls in new context/attachments since the last pass and implements small follow-up changes on an already-built ticket.\n- **When it\'s useful:** (Implementation) After review feedback or new screenshots, when you need a targeted second pass rather than a fresh build.\n- **How to use it:** `/reimplement-ticket BAPI-123`\n\n**2. Run Tests**\n- **What it does:** Runs the unit and E2E suites and autonomously triages/fixes failures (via the test-correction agent).\n- **When it\'s useful:** (Implementation) After making changes, to confirm everything passes and auto-fix straightforward breakages.\n- **How to use it:** `/run-tests` (`--unit-only`, `--skip-e2e`)\n\n**3. Plan Epic**\n- **What it does:** Decomposes a large epic into sub-tasks with a structured exploration doc for each.\n- **When it\'s useful:** (Architecture | Refinement) When a feature is too big for one ticket and you need it broken down and scoped.\n- **How to use it:** `/plan-epic <epic>` \u2014 *"Decompose the epic \'migrate PayPal token storage off Custom Objects\' into sub-tasks with an exploration doc for each."*\n\n**4. Update Ticket**\n- **What it does:** Synthesizes a ticket\'s clarifying answers and critique into a rewritten description and pushes it to Jira.\n- **When it\'s useful:** (Refinement) After review, to fold the resolved questions and fixes back into the ticket itself.\n- **How to use it:** `/update-ticket BAPI-123` (command only \u2014 does a full overwrite of the live Jira description; "update" as free text is both vague and hard to reverse).\n\n**5. Get Ticket**\n- **What it does:** Retrieves the full details of a Jira ticket (summary, status, description, etc.).\n- **When it\'s useful:** (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.\n- **How to use it:** ask your agent \u2014 *"Pull up BAPI-123 and show me its description, status, and acceptance criteria."*\n\n**6. Write Comment**\n- **What it does:** Posts a comment on a Jira ticket (markdown; long ones can attach as a file).\n- **When it\'s useful:** (Refinement | Implementation) To leave context, status, or a decision trail on the ticket.\n- **How to use it:** ask your agent \u2014 *"Post a comment on BAPI-123: blocked on the expired Atlassian token \u2014 will retry after it\'s rotated."*\n\n**7. Download / Upload Attachment**\n- **What it does:** Pulls files off a Jira ticket to disk, or attaches a local file to a ticket.\n- **When it\'s useful:** (Refinement | Implementation) When a ticket has design files/logs you need locally, or you want to attach output back to it.\n- **How to use it:** ask your agent \u2014 *"Download the design mockups attached to BAPI-123 into my docs folder."* / *"Attach build-log.txt to BAPI-123."*\n\n**8. Learn Repository**\n- **What it does:** Researches and documents the repo\'s architecture, testing, review, and correctness standards, then saves them to Bridge for future agents.\n- **When it\'s useful:** (Setup/Learning) When onboarding a new repo, or after big changes, so Bridge\'s agents follow your conventions.\n- **How to use it:** `/learn-repository`\n\n**9. Teach Bridge**\n- **What it does:** Takes a plain-English instruction, figures out which standards field it belongs to, and merges it in (admin only).\n- **When it\'s useful:** (Setup/Learning) When you notice the agents missing a convention and want to correct it in one sentence.\n- **How to use it:** `/teach-bridge <teaching>` \u2014 *"Teach Bridge: always use data-testid selectors in E2E tests."*\n\n### Operational commands\n\nWorkflow commands you\'ll reach for during implementation and CI, beyond the tiers above:\n\n| Command | What it does |\n|---|---|\n| `/code-ticket PROJ-123` | Download the implementation plan and questions, then execute the plan inline |\n| `/commit-ticket PROJ-123` | Stage, commit, and push changes; transition Jira status; post a smoke-test comment |\n| `/create-pr PROJ-123` | Commit staged changes and open a pull request |\n| `/check-ci [PROJ-123]` | Monitor CI checks for the current branch, triage failures, apply fixes, and report results |\n| `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |\n| `/check-parse-status` | Check whether a background repository parse job is still running |\n| `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |\n\n> Commands are designed for Claude Code. Other editors may support slash commands differently \u2014 check your editor\'s documentation for how to invoke prompt files.\n\n### Extra Capabilities\n\nBehind-the-scenes capabilities an agent gains from the MCP tools \u2014 mostly invoked automatically by the commands above, rarely requested by name:\n\n- **Ship a PR end-to-end:** commit & push, open a pull request, transition the Jira status, and discover/poll CI checks (powers `commit-ticket`, `create-pr`, `check-ci`, `implement-ticket`).\n- **Architecture plan** for a ticket (design-level guidance, separate from the implementation plan).\n- **Index the codebase** so Bridge\'s agents can reason about it: queue/parse the repo, check parse status, regenerate the directory map.\n- **Read & tune project config/standards:** list/read/update config fields, fetch project standards, and the per-topic `learn-*` commands that populate them.\n- **Ticket lifecycle bookkeeping:** track tickets and backfill workflow-state timestamps (`scan-tickets`), search across tickets, read comments, list attachments.\n- **Pipeline machinery:** list/inspect pipeline recipes and run/resume/list/delete pipeline runs (the engine under the orchestration commands).\n- **Decision page** generation for capturing human review decisions as structured data.\n- **Connectivity & identity checks:** ping Bridge, check your role, resolve the local docs directory.\n- **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, brainstorms, research, architecture) without regenerating it.\n- **Tiered-section execution telemetry** recording (internal measurement).\n\n## Salesforce B2C Commerce (SFCC) Tools\n\nSalesforce\'s official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks \u2014 cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform\'s object model, custom objects, or site configuration \u2014 exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge\'s SFCC tools install side-by-side with `b2c-dx-mcp` (they don\'t duplicate its surface) and close that gap with **read-only OCAPI Data API introspection** of system objects, custom object definitions, and site preferences.\n\n**v1 is read-only and developer-sandbox-only** \u2014 no writes, and non-sandbox instances are rejected. Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to Bridge.\n\n<details>\n<summary><strong>Setup</strong></summary>\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The seven read tools must be enabled with a profile (step 3).\n\n**Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).\n\n**1. Set the repo `version` config field** to your SFCC project type \u2014 one of `sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this; a non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your normal config path, the `config_field` MCP tool (operation `update`, field `version`), or the `/teach-bridge` skill.\n\n**2. Provide SFCC credentials.** Create a `dw.json` in your project root:\n\n```json\n{\n  "hostname": "zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com",\n  "client-id": "<account-manager-client-id>",\n  "client-secret": "<account-manager-client-secret>"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. Prefer a single config \u2014 a multi-entry `configs[]` array forces you to pass an explicit `instance` on every call. `dw.json` is auto-added to git exclude and must never be committed. Alternatively, export `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n**3. Enable the read tools.** Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated; `full` also works), then **restart the MCP client**:\n\n```json\n"env": { "BRIDGE_MCP_PROFILE": "sfcc" }\n```\n\nWithout this, only the diagnostic tools are registered.\n\n**4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks \u2713), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration \u2192 Site Development \u2192 Open Commerce API Settings \u2192 Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change \u2014 a running session does not pick them up.\n\n</details>\n\n### Tools\n\nAll SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.\n\n**Diagnostics** (always available, no profile needed)\n- `sfcc_setup_status` \u2014 report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, and AM token acquisition.\n- `check_permissions` \u2014 probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).\n\n**System object model** (needs the `sfcc` profile)\n- `system_object_list` \u2014 list system object types (Product, Order, Customer, \u2026).\n- `system_object_get` \u2014 fetch one type\'s definition, optionally with its full attribute definitions (`expand_attribute_definitions`).\n- `system_object_attribute_search` \u2014 search a type\'s attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.\n\n**Custom object definitions** (needs the `sfcc` profile)\n- `custom_object_definition_attributes_get` \u2014 fetch attribute definitions for a known custom object type. OCAPI cannot enumerate custom object types, so `object_type` must already be known.\n- `custom_object_definition_attribute_search` \u2014 search attribute definitions within a known custom object type. Read-only \u2014 creating a custom object *type* isn\'t possible via OCAPI; that\'s a future v2 metadata-import capability.\n- `custom_object_definition_attribute_create` \u2014 **write** (sandbox only): create an attribute definition on a known custom object type via `PUT /custom_object_definitions/{type}/attribute_definitions/{id}`. TYPE creation is never attempted (the type must pre-exist). Echoes paste-ready OCAPI grant JSON on 403.\n- `custom_object_definition_attribute_update` \u2014 **write** (sandbox only): update an attribute definition via an ETag-conditional `PATCH \u2026/attribute_definitions/{id}`; surfaces 409/412 conflicts and echoes grant JSON on 403.\n\n**Site preferences** (needs the `sfcc` profile; sandbox only)\n- `site_preference_get` \u2014 read a preference group\'s effective preferences.\n- `site_preference_search` \u2014 search/filter preferences within a group.\n- `site_preference_values_set` \u2014 **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.\n\n## CLI Subcommands\n\nBeyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) \u2014 so they travel with the package to every consumer. See [Usage Documentation \u2192 Start Tickets](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.\n\n### `start-tickets`\n\nSpawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the `/start-tickets` slash command. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`. For existing ticket keys, `/review-and-start` (see [Usage Documentation \u2192 Review and Start](#tier-1--regularly-useful)) is the recommended enriched front door over this CLI\'s `--workflow review-and-implement` seam; using the CLI directly (below) remains the advanced/lower-level path.\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--agent claude\\|cursor-agent` | `claude` | Agent command to launch in each worktree |\n| `--workflow implement\\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `implement` is byte-identical to today\'s `/implement-ticket <KEY> [--auto]`. `review-and-implement` spawns `/review-and-implement <KEY> [--auto] [--rounds=<n>]`, which runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session. `--auto` applies to the selected workflow as a whole. |\n| `--rounds 1\\|2` | unset | Review round count forwarded to the review phase. Review-only \u2014 valid only with `--workflow review-and-implement`. |\n| `--terminal terminal\\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |\n| `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |\n| `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |\n| `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |\n| `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility \u2014 despite the name, it now skips refresh of whatever `--base-branch` resolves to. |\n| `--max-parallel N` | `3` | Max worktrees created concurrently |\n| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, a supervisor peer tab, and the `check_messages` message-relay prompt). **Default off** \u2014 a plain run spawns `cd <worktree> && <agent> \'/implement-ticket <KEY>\'`. |\n| `-h`, `--help` | \u2014 | Show usage |\n\nEach `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent\'s `\'/implement-ticket <KEY>\'` \u2014 `claude \'/implement-ticket <KEY>\'` by default, or `cursor-agent \'/implement-ticket <KEY>\'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248\n```\n\n**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket\'s `difficulty` (1-2 \u2192 cheap, 3-5 \u2192 basic, 6+ \u2192 premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier \u2192 alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all omit `--model` (the agent uses its default) and surface a per-ticket warning rather than failing the spawn. `--dry-run` does **not** fetch tiers or inject `--model`.\n\n**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort \u2014 a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.\n\n**Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.\n\n- **macOS** \u2014 opens a Terminal.app or iTerm tab via `osascript`.\n- **Windows** \u2014 creates worktrees with **`git-wt`** (Worktrunk\'s winget alias) and opens a tab via **Windows Terminal (`wt.exe new-tab`)**, falling back to **`Start-Process powershell.exe`** when Windows Terminal is absent. Requires **Git for Windows / Git Bash** (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash). The Worktrunk binary (`git-wt`) and the tab launcher (`wt.exe`) are resolved independently and never conflated.\n- **Linux** \u2014 creates one detached **tmux** session per ticket (pane kept open after the agent exits); attach with `tmux attach -t <session>`. A missing `tmux` produces a clear, actionable error.\n\nPer-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` \u2014 Worktrunk\'s `pre-start` hook runs `uv`, but live preflight does not check it \u2014 and the selected agent\'s command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).\n\n### `doctor`\n\nThe package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:\n\n```\nnpx -y @bridge_gpt/mcp-server doctor [--agent <name>]\n```\n\nIt is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent\'s command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.\n\n### `setup-epic`\n\nBootstraps an Epic Conductor v2 run in one command \u2014 creates the epic run, stores the plan DAG, and approves it:\n\n```\nnpx -y @bridge_gpt/mcp-server setup-epic --epic-key <KEY> --plan-file <path-to-epic-plan.dag.json>\n```\n\nThe plan sidecar is produced by the `decompose-epic` pipeline step. `setup-epic` validates it locally (unique ticket keys, resolvable dependency references, acyclicity) before sending anything, so a malformed plan fails legibly instead of as a bare HTTP 400. It is **idempotent**: re-running it on an epic that already has a live run reuses that run rather than minting a second one. `--dry-run` validates and previews the calls without mutating anything; `--json` emits a single machine-readable result object.\n\nOnce the plan is approved, the **server-side reconciler** picks the run up within ~30s. To execute claimed jobs on your machine, run `executor`:\n\n```\nnpx -y @bridge_gpt/mcp-server executor --repo <name>\n```\n\n### Conductor (epic & multi-agent orchestration)\n\nConductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference \u2014 the v2 architecture (server-side reconciler + local executor), `setup-epic`, `conductor install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream \u2014 lives in **[CONDUCTOR.md](./CONDUCTOR.md)**.\n\n> The v1 `conductor epic-tick` command is **frozen** \u2014 it throws on every invocation. There is nothing to schedule locally, and `conductor doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.\n\n## Custom Pipelines\n\nYou can create your own pipelines by adding JSON files to `.bridge/pipelines/`. Running `--init` scaffolds this directory with a `README.md` and an example pipeline to get you started.\n\nThe easiest way to write a custom pipeline is to describe what you want to automate to your AI coding agent and have it draft the JSON for you. The schema is straightforward, and agents like Claude Code understand it well \u2014 just describe the steps you want, and the agent will produce a working pipeline file.\n\n**What you can build:**\n\n- Any sequence of Bridge MCP tool calls and free-form agent tasks\n- Parameterized workflows using variables (e.g., `{ticket_key}`)\n- Approval gates that pause for user confirmation before sensitive steps\n- Per-step error handling \u2014 halt immediately or warn and continue\n\n**Ideas for custom pipelines:**\n\n- A standup pipeline that fetches your open tickets and summarizes their status\n- A ticket triage pipeline that runs critiques on a batch of new tickets\n- A pre-merge checklist that runs tests, checks linting, and posts a summary comment\n\n**Step types:**\n\n| Type | What it does |\n|---|---|\n| `mcp_call` | Calls an MCP tool with the given params |\n| `agent_task` | Gives the AI a free-form instruction (inline or from a file in `.bridge/instructions/`) |\n\nVariables are declared in the `variables` array and referenced as `{variable_name}` in params and instructions. Each step supports `on_error: "halt"` (default) or `"warn_and_continue"`, and `requires_approval: true` to pause before execution.\n\n**System variables:**\n\nTwo variables are automatically available in every pipeline without declaring them:\n\n| Variable | What it does |\n|---|---|\n| `{provider}` | Routes AI generation to a specific LLM provider (`openai`, `anthropic`, or `gemini`). Pass it through to any `request_*` tool param to control which provider handles that step. Omit it (or leave it empty) to use the project default. |\n| `{second_opinion}` | Runs AI generation through a different provider than the default, acting as a cross-check. Set to `"auto"` to let Bridge pick the second provider automatically. When set, it takes precedence over `{provider}`. Use this when you want two independent AI perspectives on the same task \u2014 for example, running clarifying questions and a critique twice (once with each provider) produces better results than a single pass. |\n\nSee `.bridge/pipelines/README.md` for the full schema reference.\n\nIf a custom pipeline has the same key as a built-in pipeline, the custom version takes precedence (a warning is logged at startup).\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `BAPI_BASE_URL` | Yes | `https://bridgegpt-api.com` | Bridge API base URL |\n| `BAPI_REPO_NAME` | Yes | _(none)_ | Jira project/repository identifier configured in Bridge API |\n| `BAPI_API_KEY` | Yes | _(none)_ | API key obtained from the Bridge API setup UI |\n| `BAPI_PROJECT_ROOT` | No | _(auto-set by --init)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution |\n| `BAPI_DOCS_DIR` | No | `docs/tmp` | Local directory for saving plans, critiques, and research reports |\n| `BAPI_PIPELINES_DIR` | No | `.bridge/pipelines` | Directory for user-defined custom pipeline JSON files |\n| `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |\n| `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |\n| `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation \u2014 it only gates the recipe-preamble convention |\n| `CURSOR_API_KEY` | No | _(none)_ | API key used to authenticate `cursor-agent` when launching `start-tickets`/scheduled runs with `--agent cursor-agent`. Not needed for the default Claude Code agent |\n| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile \u2014 a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default \u2014 normal coding tools only), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools \u2014 `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 7 heavy SFCC read tools \u2014 see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), and `full` (shortcut that expands to every group). Example: `sfcc,conductor`. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported \u2014 groups are resolved once at process startup. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |\n\n## Worktree credentials and the `mcp-invoke` shim\n\nWhen `start-tickets` creates a git worktree, it provisions a Bridge API MCP\nregistration into that worktree so Claude Code (`.mcp.json`) and Cursor\n(`.cursor/mcp.json`) can reach the server immediately. These registrations are\n**secret-free**: they contain no `env` block and no API key. Instead they point\nat an internal subcommand of the published single CLI bin, `mcp-invoke`:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@<VERSION> mcp-invoke --target bapi --project-root <ABS_WORKTREE_PATH>\n```\n\n`mcp-invoke` is not a separate binary \u2014 it is a positional subcommand of\n`bridge-api-mcp-server`. It resolves the repo identity from the absolute\n`--project-root` (the committed `.bridge/config` manifest, falling back to the\ngit common dir), resolves credentials from the home-directory credential store,\nand then spawns the real MCP server with that environment.\n\n### Credential store\n\nCredentials live outside the repository, keyed by `bapi:<repo_name>`:\n\n```json\n{\n  "bapi:<repo_name>": {\n    "BAPI_API_KEY": "..."\n  }\n}\n```\n\nResolution order:\n\n1. `BAPI_API_KEY` in the parent environment (overrides the file entirely).\n2. `$XDG_CONFIG_HOME/bridge/credentials.json`, else `~/.config/bridge/credentials.json`.\n3. `~/.bridge/credentials.json` (only when the primary path is absent).\n\nOn POSIX systems, lock the file down so only you can read it:\n\n```bash\nchmod 600 ~/.config/bridge/credentials.json\n```\n\n`mcp-invoke` warns (but continues) if the file is group/world-readable, and it\nnever creates or initializes the credential file for you.\n\n### Populating the credential store\n\nThe same store also backs the shell-spawned `start-tickets` CLI (its\ndifficulty\u2192model routing runs in a Bash process that cannot see an `env` block in\n`.mcp.json` / `.cursor/mcp.json`), so the store must hold the key for routing to\nwork. Two supported paths write it for you:\n\n- **Install-time upsert.** `/install-bridge`\'s final stage persists the validated\n  routing credential into `~/.config/bridge/credentials.json` (target\n  `bapi:<repo>`) via the `persist_routing_credential` MCP tool \u2014 the tool resolves\n  the key inside the MCP process and writes the store, so no secret crosses the\n  wire.\n- **One-shot migration.** If a key currently lives only in `.mcp.json` /\n  `.cursor/mcp.json`, migrate it into the user-scoped store with the consent-gated\n  command (a compatibility aid, not a live fallback):\n\n  ```bash\n  npx -y @bridge_gpt/mcp-server credentials migrate-agent-config [--write-credentials]\n  ```\n\n  Run it without `--write-credentials` to preview; add the flag to write the store.\n\n## Reference\n\nThe full surface, for when you need the complete enumeration. Day-to-day, use [Usage Documentation](#usage-documentation) instead \u2014 you don\'t call MCP tools directly; you ask your AI assistant to perform a task, or compose tools into a pipeline.\n\n### MCP tools\n\nThe server exposes **59 documented tools** (enumerated below). What\'s actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).\n\n- **Connectivity & identity** \u2014 `ping`, `get_my_role`, `get_docs_dir`\n- **Jira tickets** \u2014 `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`\n- **Attachments** \u2014 `attachment` (operations: `upload`, `download`, `list`)\n- **AI generation (request/get)** \u2014 `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`\n- **Other AI** \u2014 `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)\n- **Ticket lifecycle** \u2014 `track_ticket`, `update_ticket_state`, `get_ticket_state`\n- **Jira status** \u2014 `get_jira_transitions`, `update_jira_status`, `resolve_target_status`\n- **Repository & CI** \u2014 `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`\n- **Pipelines & automation** \u2014 `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`\n- **Config** \u2014 `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)\n\n### Bundled pipelines\n\nPipelines are declarative, multi-step workflows your AI agent executes step-by-step \u2014 each a JSON recipe chaining MCP tool calls and free-form agent tasks, with variable substitution, per-step error handling, and optional approval gates. You can also write your own (see [Custom Pipelines](#custom-pipelines)).\n\n| Pipeline | Description | Invoke with |\n|---|---|---|\n| `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |\n| `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. | `/review-ticket PROJ-123` |\n| `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |\n| `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |\n| `full-automation` | Chain: idea \u2192 ticket(s) \u2192 review each \u2192 spawn worktrees to implement | `/full-automation "<idea>"` |\n| `pr-ticket` | Commit changes and open a pull request | `/create-pr PROJ-123` |\n| `check-ci-ticket` | Commit, open a PR, then monitor CI checks until they pass or fail | `/check-ci PROJ-123` |\n| `learn-repository` | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | `/learn-repository` |\n\n### Pipeline response envelope\n\n`run_pipeline`, `resume_pipeline`, and `list_pipeline_runs` share a unified envelope keyed on `status`:\n\n- `completed` \u2014 terminal success; `results` holds per-step output.\n- `needs_agent_task` \u2014 the orchestrator paused. Read `instruction`, perform the task, then call `resume_pipeline` with `pipeline_run_id` and a string `agent_result`.\n- `failed` \u2014 terminal failure. `error_code` is one of `VALIDATION`, `NOT_FOUND`, `EXPIRED`, `REPO_MISMATCH`, `TOOL_ERROR`.\n\nPaused runs auto-expire after an idle TTL (default 24 hours; override with `ttl_seconds`). The TTL is reset on every state transition. List output is metadata-only \u2014 it never includes resolved recipes, params, instructions, results, or agent outputs.\n';
 
 // src/update-check.ts
 init_version_generated();
@@ -14819,7 +15458,7 @@ var COMMANDS = {
   "bridge-research.md": 'Run multi-source, fact-checked web research via Bridge API and save a cited report locally.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nExecute all steps in this command as a simple linear sequence of MCP tool calls.\n\n## Step 1 \u2014 Parse Arguments\n\nParse `$ARGUMENTS`:\n- The required `query` is the full text of `$ARGUMENTS` after removing any recognized flags.\n- An optional `--ticket <KEY>` flag captures a Jira ticket key (e.g., `BAPI-123`) to associate the research with a specific ticket. If `--ticket` appears, treat the immediately following token as the ticket key and remove both from the query.\n- If `$ARGUMENTS` is empty, or the query (after flag removal) is blank, stop immediately and display:\n\n```\nUsage: /bridge-research <question> [--ticket PROJ-123]\nExample: /bridge-research "Best practices for rate limiting in FastAPI?"\n```\n\n## Step 2 \u2014 Resolve Docs Directory\n\nCall `get_docs_dir` (no parameters). Store the returned path as `docs_dir`.\n\n## Step 3 \u2014 Run Research\n\nCall `request_deep_research` with:\n- `query`: the parsed question\n- `wait_for_result`: `true`\n- `ticket_number`: the value from `--ticket` if provided; omit this parameter entirely if not present\n\nThis step polls until the research completes (up to 15 minutes) and returns the full cited report directly. The tool appends a literal `Saved to <path>` line to its result \u2014 extract that line and store the path as `saved_path`.\n\nIf the tool returns an error, stop immediately and display:\n\n```\nResearch failed: <error message from the tool>\n```\n\n## Step 4 \u2014 Confirm\n\nDisplay a confirmation message:\n\n```\nResearch complete.\nSaved to: {saved_path}\n```\n\n## Final Summary\n\nDisplay a summary block:\n\n```\n## Bridge Research Report\n\n- **Query**: <query>\n- **Status**: Completed\n- **Local File**: {saved_path}\n```\n\nOn failure at any step, stop immediately, display which step failed and the error details, and do not proceed.\n',
   "check-ci.md": '# Check CI: $ARGUMENTS\n\n$ARGUMENTS\n\n> **Warning**: Keep this file behaviorally in sync with `mcp_server/instructions/monitor-ci-checks.md` to prevent drift (BAPI-462).\n\nThis command takes a Jira ticket key (e.g., `BAPI-150`), discovers CI checks for the current commit, polls their status, and applies confidence-gated code corrections for failures. It is designed to run after `/create-pr` completes.\n\nIf any critical stage fails (Stage 0), stop immediately and report which stage failed and why. Non-critical stages (Stage 1, Stage 2, and Stage 3) should log a warning but not stop the pipeline.\n\n---\n\n# Instructions\n\nYou are executing a 4-stage pipeline to monitor and respond to CI checks for a Jira ticket. Execute all stages in sequence.\n\n## Stage 0 \u2014 Setup and Argument Parsing\n\n1. **Parse `$ARGUMENTS`**: Extract a single required `ticket_key` argument. The expected format is a Jira ticket key such as `BAPI-150` or `PROJ-123` \u2014 one or more uppercase letters, a hyphen, and one or more digits (regex: `[A-Z]+-\\d+`). If `$ARGUMENTS` is empty or the value does not match the expected format, stop immediately and display:\n\n   ```\n   Invalid ticket key format: \'<value>\'. Expected format: PROJ-123 (uppercase letters, hyphen, digits).\n   Usage: /check-ci <ticket_key> (e.g., /check-ci BAPI-150)\n   ```\n\n2. **Connectivity check**: Call the `ping` MCP tool (no parameters). If the ping fails or does not return `"status": "ok"`, stop immediately and display:\n\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor\'s MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\n3. **Get current commit SHA**: Run `git rev-parse HEAD` in the terminal. Store the result as `commit_sha`.\n\n4. **Get current branch**: Run `git branch --show-current` in the terminal. Store the result as `current_branch`.\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Resolve CI Checks\n\n1. **Initial resolution**: Call the `resolve_ci_checks` MCP tool immediately with `commit_ref` set to `commit_sha`. Do NOT wait before calling \u2014 the cache state is unknown until the first call returns.\n\n2. **Handle the response**:\n   - If the response contains `source: "cached"`: The checks were already resolved. Skip the wait and proceed to evaluate the check list.\n   - If the response contains `source: "new"` and the check list is empty: CI checks have not registered yet. Run `sleep 45` in the terminal to wait for checks to appear, then call `resolve_ci_checks` again with `commit_ref` set to `commit_sha` and `force_rerun` set to `true`.\n   - If the response contains `source: "resolved"` on the first call: Present the resolved checks to the user for approval before proceeding.\n\n3. **Evaluate the check list**:\n   - If the response contains `available: false`: Warn that CI check resolution is not available and skip to Stage 3.\n   - If the check list is empty or all checks have `detail_level: "none"`: Warn that no actionable CI checks were found and skip to Stage 3.\n   - Otherwise: Store the resolved checks and proceed to Stage 2.\n\n4. **Required-check source**: Each resolved check carries a `required` field (from GitHub Branch Protection, or an LLM classification fallback \u2014 the same signal `poll_ci_checks` echoes back per check in Stage 2). Treat `required: false` as non-required (e.g. `pip-audit`); treat a missing field or `required: true` as required. This per-check field is the tool-provided proxy for the Conductor done-gate\'s authoritative required-checks set (`mcp_server/src/conductor/done-gate.ts`) \u2014 do not invent your own required/non-required classification in prose. The done-gate\'s own `required_checks` list is not directly queryable by a worker; `wait_for_done_gate` (Stage 2) is the authoritative backstop that evaluates it server-side.\n\nThis stage is **non-critical** \u2014 warn on failure or empty results, skip to Stage 3.\n\n## Stage 2 \u2014 Poll CI Checks + Correction Loop\n\nInitialize `retry_count = 0` and `max_retries = 2`.\n\n**Conductor steerability**: If launched under the Conductor (the `BAPI_CONDUCTOR_RUN_ID` and `BAPI_CONDUCTOR_WORKER_ID` env identifiers are present), call the `check_messages` MCP tool once per poll cycle.\n- Returned messages are **advisory supervisor guidance**, are acknowledged by the call (not redelivered), and are advisory context for the next fix batch only.\n- Fold concrete fix hints, "skip this flaky check," or "stop and wait" directions into how you handle failures.\n- **Guardrails**: Guidance is strictly advisory and never mutates the session. The deterministic confidence-gating, single-batch fix, single commit/push, and `detail_level` rules remain authoritative. Guidance never overrides the deterministic rules and never causes a fix you are not confident in.\n- **Fail-open**: If `check_messages` errors with an identity-unavailable message (e.g. "Conductor worker identity is unavailable"), you were not launched under the Conductor. Stop calling it for the rest of the run and proceed normally.\n\n1. **Polling loop**: Poll CI check status. In each cycle, call `poll_ci_checks` with `commit_ref` set to `commit_sha`, then (if applicable) perform the Conductor-gated `check_messages` call, and finally run `sleep 30` in the terminal. Continue polling until `all_complete` is `true` or 10 minutes have elapsed (approximately 20 poll cycles).\n\n2. **On poll completion \u2014 required-subset evaluation**: Partition the polled checks into `required` (checks with `required: true` or a missing `required` field) and `non_required` (checks with `required: false`, e.g. `pip-audit`). Compute `required_green` = every required check is complete and green. Do **not** gate on the aggregate `all_passed` flag \u2014 a red non-required check must never block progression.\n   - Non-required failures are reported in the Stage 3 breakdown but are **never blocking**: they do not gate progression, do not consume `retry_count`, and are not sent through the fix loop in item 3.\n   - If `required_green` is `false` (a required check is still red), proceed to item 3 to attempt fixes for the failing **required** checks only.\n   - If `required_green` is `true`:\n     - **Review verdict gating**: if `claude-review` is one of the required checks, its GitHub check reaching a non-pending/"success" state means only that the review action *ran* \u2014 this is **transport completion, not approval**. Fetch the PR\'s comments (e.g. `gh pr view --json comments`) and look for the sticky comment\'s machine-readable verdict line. The review counts as approved only when that comment contains `claude-review-verdict: approved` on its own line **and** the accompanying `Reviewed-SHA:` line matches the current `commit_sha` \u2014 a verdict posted against an older head does not count.\n       - **Missing or stale verdict** (no `claude-review-verdict:` line at all, or a `Reviewed-SHA:` that does not match the current `commit_sha`): do not treat the review as approved. Report it in Stage 3 and do **not** call `wait_for_done_gate` this cycle \u2014 a missing or stale verdict is not approval.\n       - **`claude-review-verdict: changes_requested`** (the reviewer rejected the current head): do **not** call `wait_for_done_gate` for the rejected old head. When you are confident you can address the review, remediate it in-session \u2014 mirroring the confidence-gated commit+push already specified for CI-failure fixes \u2014 instead of merely reporting it:\n         - Read the review findings from the sticky comment and any inline review comments.\n         - Apply confidence gating: remediate only when you are confident you can address ALL findings; otherwise report in Stage 3 without committing.\n         - Address all review findings across all affected files in a single batch. Do not fix one at a time.\n         - After applying all fixes, perform a single `git commit` and `git push` so `origin/feature/<KEY>` advances to the new head and a fresh CI/review runs against it.\n         - Increment `retry_count`. If `retry_count` exceeds `max_retries`: if launched under the Conductor, call `check_messages` one final time; if the supervisor sent explicit "continue" guidance with a concrete hint, apply it for exactly **one additional batch** (the only way the ceiling is raised); otherwise stop the correction loop and proceed to Stage 3 with a warning.\n         - Otherwise, update `commit_sha` to the new HEAD (`git rev-parse HEAD`) and restart the polling loop against the new head.\n     - **Conductor done-gate**: once the required subset is green and (if `claude-review` is required) the verdict token confirms approval for the current head, and if launched under the Conductor (the `BAPI_CONDUCTOR_RUN_ID`/`BAPI_CONDUCTOR_WORKER_ID` identifiers are present), call the `wait_for_done_gate` MCP tool **once** from inside your worktree before proceeding (no arguments are required \u2014 it self-resolves the PR number and head commit SHA from the worktree, fetches the review snapshot, evaluates the composite done-gate against the Conductor\'s authoritative `required_checks` config, and emits a `gate.met` event correlated to your run/worker so the supervisor can fold and merge). This tool does **not** merge or mutate the repo. It applies its own bounded fast-path poll (a short internal cap, not a multi-minute wait) \u2014 if it times out or does not observe `gate_met`, **exit cleanly** to Stage 3 without treating the timeout as a failure: the Conductor\'s own reconciliation pass is the correctness backstop for reaching `gate.met`, not this call. Fail-open: if the tool errors with an identity-unavailable message, you were not launched under the Conductor \u2014 skip it. Then proceed to Stage 3.\n\n3. **On required-subset failures detected**: Examine each failed **required** check\'s `detail_level` (non-required failures such as `pip-audit` are never processed here \u2014 they were already reported and skipped in item 2, and never consume a retry):\n\n   - **`detail_level: "full"`** \u2014 Apply confidence gating:\n     - Read the full `failure_details` payload for all failed checks.\n     - If you are confident you can fix the errors, address ALL failures across all affected files in a single batch. Do not fix one at a time.\n     - After applying all fixes, perform a single `git commit` and `git push`.\n     - Increment `retry_count`.\n     - If `retry_count` exceeds `max_retries`: if launched under the Conductor, call `check_messages` one final time. If the supervisor sent explicit "continue" guidance with a concrete hint, apply it for exactly **one additional batch** (this is the only way the ceiling is raised). Otherwise, stop the correction loop and proceed to Stage 3 with a warning.\n     - Otherwise, update `commit_sha` to the new HEAD (`git rev-parse HEAD`) and restart the polling loop.\n   - **`detail_level: "url_only"`** \u2014 Report the check name and URL to the user. Do not attempt fixes. Do not consume a retry.\n   - **`detail_level: "none"`** \u2014 Report the check name only. Do not attempt fixes. Do not consume a retry.\n\n4. **Handle `unknown_checks`**: If the poll response contains `unknown_checks`, call `resolve_ci_checks` with `commit_ref` set to `commit_sha` and `force_rerun` set to `true` at most ONCE. If `unknown_checks` persist on the next poll, warn the user that the CI check configuration is unresolvable and skip to Stage 3.\n\n5. **Timeout**: If 10 minutes elapse without `all_complete` becoming `true`, warn that polling timed out and proceed to Stage 3.\n\nThis stage is **non-critical** \u2014 warn on failure or timeout, continue to Stage 3 regardless.\n\n## Stage 3 \u2014 Summary Report\n\nDisplay a structured completion report. The report **must** be presented as markdown, using exactly the structure below:\n\n```\n## CI Check Report\n\n**Ticket**: <ticket_key>\n**Branch**: <current_branch>\n**Commit SHA**: <commit_sha>\n**Status**: <Passed / Failed / Timed Out / Not Available>\n\n**Per-check breakdown**:\n| Check Name | Status | Required | Detail Level |\n|------------|--------|----------|--------------|\n| <name>     | <pass/fail> | <yes/no> | <full/url_only/none> |\n\n**Review verdict**: <approved / changes_requested / not yet posted / N/A \u2014 claude-review not required>\n**Fixes attempted**: <retry_count> of <max_retries>\n**Supervisor guidance applied**: <yes/no>\n\n**Warnings**:\n<If any non-critical stages had warnings (Stage 1: resolution unavailable,\nStage 2: timeout, unfixable required-check failures, unknown_checks,\nnon-required check failures reported for visibility),\nlist them here. If no warnings, omit this section.>\n```\n\nThis stage is **non-critical** \u2014 display the report regardless.\n\n## Final Report\n\nOn success, display the structured report from Stage 3 confirming the CI check status, including per-check breakdown, fixes attempted, and any warnings from earlier stages.\n\nOn failure at any critical stage (Stage 0), display which stage failed and the error details.\n',
   "clarify-ticket.md": 'Generate clarifying questions for a Jira ticket and save them locally.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\n`$ARGUMENTS` is a required Jira ticket key (e.g., `PROJ-123`). This command generates clarifying questions for the ticket and saves them locally.\n\nIf any step fails, stop immediately and report which step failed and why.\n\n## Step 1 \u2014 Parse Arguments\n\n1. **Parse `$ARGUMENTS`**: Extract a required `ticket_key`, an optional `--second-opinion` flag, and an optional `--provider` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--second-opinion` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `second_opinion_value`.\n   - If `--second-opinion` appears without a provider name following it (or is the last token), set `second_opinion_value = "auto"`.\n   - If `--second-opinion` is absent, set `second_opinion_value = null`.\n   - If `--provider` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `provider_value`.\n   - If `--provider` appears without a valid provider name following it (or is the last token), stop immediately and report: "Usage error: --provider requires a provider name (openai, anthropic, or gemini)."\n   - If `--provider` is absent, set `provider_value = null`.\n   - If both `--second-opinion` and `--provider` are present, `--second-opinion` takes precedence (set `provider_value = null`).\n   - The remaining token (after removing flags and their arguments) is the `ticket_key`.\n\n2. **Validate ticket key format**: Confirm the ticket key matches the Jira key pattern `[A-Z][A-Z0-9]+-\\d+`. If it does not match, stop immediately and report: "Invalid ticket key format. Expected a Jira key like PROJ-123."\n\n## Step 2 \u2014 Resolve Docs Directory\n\nCall the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n## Step 3 \u2014 Generate Clarifying Questions\n\nCall the `request_clarifying_questions` MCP tool with:\n- `ticket_number`: the validated `ticket_key`\n- `wait_for_result`: `true`\n- `save_locally`: `true`\n- `second_opinion`: set to `second_opinion_value` if non-null; omit entirely if null\n- `provider`: set to `provider_value` if non-null; omit entirely if null\n\nIf the tool returns an error, stop immediately and report: "Clarifying questions generation failed." Include the error details.\n\n## Final Report\n\nOn successful completion, display:\n\n> **Ticket Key**: {ticket_key}\n>\n> **Local File Path**: {docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md\n>\n> **Status**: The clarifying questions document has been saved locally. No changes were pushed to Jira.\n>\n> To incorporate these findings into the Jira ticket description, run: `/update-ticket {ticket_key}`\n',
-  "code-ticket.md": "# Code Ticket: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes a Jira ticket key (e.g., `BAPI-150`), downloads the AI-generated implementation plan and clarifying questions via MCP tools, then executes the plan step by step directly in the main conversation so all progress is visible.\n\nIf any critical stage fails (Stage 0, Stage 1, or Stage 3), stop immediately and report which stage failed and why. Non-critical stages (Stage 2) should log a warning but not stop the pipeline.\n\n---\n\n# Instructions\n\nYou are executing a 4-stage pipeline to implement a Jira ticket using an AI-generated plan. Execute all stages in sequence.\n\n## Stage 0 \u2014 Setup and Argument Parsing\n\n1. **Parse `$ARGUMENTS`**: Extract a single required `ticket_key` argument. The expected format is a Jira ticket key such as `BAPI-150` or `PROJ-123` \u2014 one or more uppercase letters, a hyphen, and one or more digits (regex: `[A-Z]+-\\d+`). If `$ARGUMENTS` is empty or the value does not match the expected format, stop immediately and display:\n\n   ```\n   Invalid ticket key format: '<value>'. Expected format: PROJ-123 (uppercase letters, hyphen, digits).\n   Usage: /code-ticket <ticket_key> (e.g., /code-ticket BAPI-150)\n   ```\n\n2. **Connectivity check**: Call the `ping` MCP tool (no parameters). If the ping fails or does not return `\"status\": \"ok\"`, stop immediately and display:\n\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor's MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Download Implementation Plan\n\nCall the `get_plan` MCP tool with:\n- `ticket_number`: the parsed `ticket_key` from Stage 0\n- `save_locally`: `true`\n\nInspect the response for errors. If the response text contains `NOT_FOUND` or `404` or indicates the plan was not found, stop immediately and display:\n\n```\nNo implementation plan found for <ticket_key>. Run `/plan-ticket <ticket_key>` first to generate one,\nor use the `request_plan_generation` MCP tool with `wait_for_result: true`.\n```\n\nOn success, read and internalize the full plan content. This is the plan you will execute in Stage 3.\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 2.\n\n## Stage 2 \u2014 Download Clarifying Questions\n\nCall the `get_clarifying_questions` MCP tool with:\n- `ticket_number`: the parsed `ticket_key` from Stage 0\n- `save_locally`: `false`\n\nIf the response contains `NOT_FOUND` or `404` or indicates no clarifying questions were found, log a warning note:\n\n```\nWarning: No clarifying questions found for <ticket_key>. Proceeding without supplementary context.\n```\n\nDo **NOT** stop the pipeline. Clarifying questions are supplementary context, not a hard prerequisite for implementation.\n\nOn success, internalize the clarifying questions content. Reference these for additional context where relevant to implementation steps \u2014 the answers provide supplementary guidance on requirements and technical decisions.\n\nThis stage is **non-critical** \u2014 warn on failure, continue to Stage 3 regardless.\n\n## Stage 3 \u2014 Execute Implementation Plan\n\nExecute the implementation plan step by step, directly in this conversation. Work inline so the user can see all progress and approve tool calls.\n\nFollow these rules:\n\n1. **Execute the plan in order.** Do not skip any steps, especially review steps involving test execution, lint checks, and architectural verification.\n2. **Make code changes** as directed by each step in the plan.\n3. **Run tests and checks** as specified in the plan's review steps.\n4. **Do NOT run `git commit` or `git push`.** Leave all changes uncommitted for developer review.\n5. **If a step is ambiguous or blocked**, note the issue clearly and continue with the next step rather than halting entirely.\n6. **Reference clarifying questions** (if retrieved in Stage 2) when they provide relevant context for a given step.\n\nThis stage is **critical** \u2014 if a blocking error prevents further progress, stop and report the failure.\n\n## Stage 4 \u2014 Final Summary Report\n\nDisplay a structured report after all stages complete:\n\n```\n## Implementation Complete\n\n**Ticket**: <ticket_key>\n\n**Developer Action Items**:\n- All changes are uncommitted. Review the changes with `git diff` before committing.\n- Run the project's test suite to verify nothing is broken before committing.\n\n**Warnings**:\n<If any non-critical stages had warnings (Stage 2: no clarifying questions),\nlist them here so the developer has full visibility. If no warnings, omit this section.>\n```\n\n## Final Report\n\nOn success, display the structured report from Stage 4 confirming that implementation of the ticket is complete.\n\nOn failure at any critical stage (Stage 0, Stage 1, or Stage 3), display which stage failed and the error details.\n",
+  "code-ticket.md": "# Code Ticket: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes a Jira ticket key (e.g., `BAPI-150`), downloads the AI-generated implementation plan and clarifying questions via MCP tools, then executes the plan step by step directly in the main conversation so all progress is visible.\n\nIf any critical stage fails (Stage 0, Stage 1, or Stage 3), stop immediately and report which stage failed and why. Non-critical stages (Stage 2) should log a warning but not stop the pipeline.\n\n---\n\n# Instructions\n\nYou are executing a 4-stage pipeline to implement a Jira ticket using an AI-generated plan. Execute all stages in sequence.\n\n## Stage 0 \u2014 Setup and Argument Parsing\n\n1. **Parse `$ARGUMENTS`**: Extract a single required `ticket_key` argument. The expected format is a Jira ticket key such as `BAPI-150` or `PROJ-123` \u2014 one or more uppercase letters, a hyphen, and one or more digits (regex: `[A-Z]+-\\d+`). If `$ARGUMENTS` is empty or the value does not match the expected format, stop immediately and display:\n\n   ```\n   Invalid ticket key format: '<value>'. Expected format: PROJ-123 (uppercase letters, hyphen, digits).\n   Usage: /code-ticket <ticket_key> (e.g., /code-ticket BAPI-150)\n   ```\n\n2. **Connectivity check**: Call the `ping` MCP tool (no parameters). If the ping fails or does not return `\"status\": \"ok\"`, stop immediately and display:\n\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor's MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Download Implementation Plan\n\nCall the `get_plan` MCP tool with:\n- `ticket_number`: the parsed `ticket_key` from Stage 0\n- `save_locally`: `true`\n\nInspect the response for errors. If the response text contains `NOT_FOUND` or `404` or indicates the plan was not found, stop immediately and display:\n\n```\nNo implementation plan found for <ticket_key>. Run `/plan-ticket <ticket_key>` first to generate one,\nor use the `request_plan_generation` MCP tool with `wait_for_result: true`.\n```\n\nOn success, read and internalize the full plan content. This is the plan you will execute in Stage 3.\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 2.\n\n## Stage 2 \u2014 Download Clarifying Questions\n\nCall the `get_clarifying_questions` MCP tool with:\n- `ticket_number`: the parsed `ticket_key` from Stage 0\n- `save_locally`: `false`\n\nIf the response contains `NOT_FOUND` or `404` or indicates no clarifying questions were found, log a warning note:\n\n```\nWarning: No clarifying questions found for <ticket_key>. Proceeding without supplementary context.\n```\n\nDo **NOT** stop the pipeline. Clarifying questions are supplementary context, not a hard prerequisite for implementation.\n\nOn success, internalize the clarifying questions content. Reference these for additional context where relevant to implementation steps \u2014 the answers provide supplementary guidance on requirements and technical decisions.\n\nThis stage is **non-critical** \u2014 warn on failure, continue to Stage 3 regardless.\n\n## Stage 3 \u2014 Execute Implementation Plan\n\nExecute the implementation plan step by step, directly in this conversation. Work inline so the user can see all progress and approve tool calls.\n\nFollow these rules:\n\n1. **Execute the plan in order.** Do not skip any steps, especially review steps involving test execution, lint checks, and architectural verification.\n2. **Make code changes** as directed by each step in the plan.\n3. **Run tests and checks** as specified in the plan's review steps.\n4. **Do NOT run `git commit` or `git push`.** Leave all changes uncommitted for developer review.\n5. **If a step is ambiguous or blocked**, note the issue clearly and continue with the next step rather than halting entirely.\n6. **Reference clarifying questions** (if retrieved in Stage 2) when they provide relevant context for a given step.\n7. **If a specific plan step or requirement remains ambiguous** after consulting the plan and any retrieved clarifying questions, call the `get_ticket` MCP tool with `ticket_number` set to the parsed `ticket_key` from Stage 0 to fetch the live Jira ticket details. Use only the fields relevant to resolving that ambiguity, then continue with the affected step. Do not call `get_ticket` unconditionally or as a prerequisite \u2014 only when a step's requirement is genuinely unclear.\n\nThis stage is **critical** \u2014 if a blocking error prevents further progress, stop and report the failure.\n\n## Stage 4 \u2014 Final Summary Report\n\nDisplay a structured report after all stages complete:\n\n```\n## Implementation Complete\n\n**Ticket**: <ticket_key>\n\n**Developer Action Items**:\n- All changes are uncommitted. Review the changes with `git diff` before committing.\n- Run the project's test suite to verify nothing is broken before committing.\n\n**Warnings**:\n<If any non-critical stages had warnings (Stage 2: no clarifying questions),\nlist them here so the developer has full visibility. If no warnings, omit this section.>\n```\n\n## Final Report\n\nOn success, display the structured report from Stage 4 confirming that implementation of the ticket is complete.\n\nOn failure at any critical stage (Stage 0, Stage 1, or Stage 3), display which stage failed and the error details.\n",
   "commit-ticket.md": '# Commit Ticket: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes a Jira ticket key (e.g., `BAPI-150`), verifies the current git branch matches the ticket, identifies implementation files by cross-referencing git changes against the saved implementation plan, and commits and pushes the work. It is designed to run after `/code-ticket` completes.\n\nIf any critical stage fails (Stage 0, Stage 1, or Stage 3), stop immediately and report which stage failed and why. Non-critical stages (Stage 2, Stage 4, Stage 5, and Stage 6) should log a warning but not stop the pipeline.\n\n---\n\n# Instructions\n\nYou are executing a 7-stage pipeline to commit and push implementation work for a Jira ticket. Execute all stages in sequence.\n\n## Stage 0 \u2014 Setup and Argument Parsing\n\n1. **Parse `$ARGUMENTS`**: Extract a single required `ticket_key` argument. The expected format is a Jira ticket key such as `BAPI-150` or `PROJ-123` \u2014 one or more uppercase letters, a hyphen, and one or more digits (regex: `[A-Z]+-\\d+`). If `$ARGUMENTS` is empty or the value does not match the expected format, stop immediately and display:\n\n   ```\n   Invalid ticket key format: \'<value>\'. Expected format: PROJ-123 (uppercase letters, hyphen, digits).\n   Usage: /commit-ticket <ticket_key> (e.g., /commit-ticket BAPI-150)\n   ```\n\n2. **Resolve docs directory**: Call the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n3. **Verify uncommitted changes exist**: Run `git status --porcelain` in the terminal. If the output is empty (no modified, added, or untracked files), stop immediately and display:\n\n   ```\n   No uncommitted changes found. Nothing to commit for <ticket_key>.\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Branch Verification and Creation\n\n1. **Get current branch**: Run `git branch --show-current` in the terminal. Store the result as `current_branch`.\n\n2. **Check branch match**: Determine if `current_branch` contains the `ticket_key` (case-insensitive comparison). For example, if the ticket key is `BAPI-150`, branch `feature/BAPI-150-add-caching` matches, as does `feature/BAPI-150` or `bugfix/bapi-150-fix`.\n\n3. **If the branch matches**: Log a confirmation message and proceed:\n\n   ```\n   Branch \'<current_branch>\' matches ticket <ticket_key>. Proceeding.\n   ```\n\n4. **If the branch does NOT match**: Create a new branch from the current HEAD in the format `feature/<ticket_key>` (e.g., `feature/BAPI-150`). Run `git checkout -b feature/<ticket_key>` in the terminal. If the branch creation fails (e.g., branch already exists), try `git checkout feature/<ticket_key>` instead. If both fail, stop immediately and display:\n\n   ```\n   Failed to create or switch to branch \'feature/<ticket_key>\'.\n   Please resolve the branch situation manually and re-run.\n   ```\n\n   On success, log:\n\n   ```\n   Created and switched to new branch \'feature/<ticket_key>\'.\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 2.\n\n## Stage 2 \u2014 Identify and Stage Implementation Files\n\n1. **Collect git changes**: Run `git status --porcelain` in the terminal. Parse the output to build two lists:\n   - `modified_files`: files with status `M`, `MM`, `AM`, or `A` (modified or staged)\n   - `untracked_files`: files with status `??` (new untracked files)\n\n   Combine into a single list `all_changed_files`.\n\n2. **Load the implementation plan**: Look for the implementation plan file at `{docs_dir}/plans/{ticket_key}-plan.md`. Read the file.\n\n   - **If the plan file exists**: Extract file paths mentioned in the plan. Look for patterns like backtick-quoted paths (e.g., `src/python/foo.py`), file references in step descriptions, and any explicit file listings. Build a list `plan_files` of all file paths referenced in the plan.\n\n   - **If the plan file does NOT exist**: Log a warning:\n\n     ```\n     Warning: No implementation plan found at {docs_dir}/plans/{ticket_key}-plan.md.\n     Cannot cross-reference changes against plan. Will present all changed files for review.\n     ```\n\n     Set `plan_files` to an empty list.\n\n3. **Classify changed files**: For each file in `all_changed_files`, classify it into one of three categories:\n\n   - **Plan-matched**: The file path appears in `plan_files` (exact match or the plan references a parent directory). These are high-confidence implementation files.\n   - **Likely related**: The file is not explicitly in the plan but is a test file for a plan-matched file, a migration file, an `__init__.py` in a directory with plan-matched files, or otherwise clearly related to the implementation (e.g., `requirements.txt` if the plan mentions adding a dependency).\n   - **Ambiguous**: The file does not appear related to the plan. These may be pre-existing uncommitted changes.\n\n4. **Present file list for user confirmation**: Display the classified file list to the user:\n\n   ```\n   ## Files to Commit for <ticket_key>\n\n   ### Plan-matched files (high confidence):\n   - path/to/file1.py\n   - path/to/file2.py\n\n   ### Likely related files:\n   - tests/pytest/routes/test_file1.py\n   - db/alembic/versions/xxxx_migration.py\n\n   ### Ambiguous files (not referenced in plan):\n   - some/other/file.py\n\n   Shall I proceed with committing all listed files?\n   If you want to exclude any files, please specify which ones to remove.\n   ```\n\n   If `plan_files` is empty (plan not found), display all files under a single "All changed files" heading instead.\n\n5. **Wait for user confirmation**: The user may:\n   - Approve all files (proceed)\n   - Specify files to exclude (remove those from the commit list)\n   - Cancel entirely (stop the pipeline)\n\n   If the user cancels, stop immediately and display:\n\n   ```\n   Commit cancelled by user. No files were staged or committed.\n   ```\n\n6. **Stage the approved files**: Run `git add <file1> <file2> ...` in the terminal, listing only the approved files explicitly. Do NOT use `git add -A` or `git add .`.\n\nThis stage is **non-critical** if the plan file is not found (warn and continue with all files). It is **critical** if the user cancels or if `git add` fails \u2014 stop immediately on those failures.\n\n## Stage 3 \u2014 Commit and Push\n\n1. **Generate commit message**: Based on the staged files and the implementation plan (if available), generate a concise commit message. The message must:\n   - Start with a brief summary line (under 72 characters) that references the ticket key\n   - Format: `<ticket_key>: <brief description of changes>`\n   - Example: `BAPI-150: Add rate limiting to LLM client`\n   - If the plan was available, derive the description from the plan\'s title or objective\n   - If the plan was not available, summarize based on the file names and `git diff --staged` output\n\n2. **Commit**: Run `git commit -m "<message>"` in the terminal. If the commit fails due to a pre-commit hook, report the hook output and stop:\n\n   ```\n   Commit failed due to pre-commit hook. Hook output:\n   <hook output>\n\n   Please fix the issues and re-run /commit-ticket <ticket_key>.\n   ```\n\n3. **Push to remote**: Run `git push -u origin <current_branch>` in the terminal. The `-u` flag sets up upstream tracking. If the push fails, stop immediately and display:\n\n   ```\n   Push failed. Error:\n   <error output>\n\n   The commit was created locally. You can push manually with:\n   git push -u origin <current_branch>\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure.\n\n## Stage 4 \u2014 Final Summary Report\n\nDisplay a structured report after all stages complete:\n\n```\n## Commit Complete\n\n**Ticket**: <ticket_key>\n**Branch**: <current_branch>\n**Commit**: <commit_hash> (from `git rev-parse --short HEAD`)\n**Files committed**: <count> files\n**Remote**: Pushed to origin/<current_branch>\n\n**Committed files**:\n- path/to/file1.py\n- path/to/file2.py\n- ...\n\n**Warnings**:\n<If any non-critical warnings occurred (Stage 2: plan not found),\nlist them here. If no warnings, omit this section.>\n```\n\nThis stage is **non-critical** \u2014 display the report regardless.\n\n## Stage 5 \u2014 Jira Status Transition\n\nThis stage attempts to transition the Jira ticket to the appropriate post-PR status.\n\n1. **Resolve target status**: Call the `resolve_target_status` MCP tool with `ticket_number` set to the `ticket_key`. This returns the cached or LLM-resolved target status for the project.\n\n2. **Attempt transition**: If `resolve_target_status` returned a non-null `target_status`, call the `update_jira_status` MCP tool with `ticket_number` set to the `ticket_key` and `target_status` set to the resolved value. If the ticket is already in the target status, this is a no-op.\n\n3. **On success**: Display `"Ticket status updated: <from_status> -> <to_status>"`.\n\n4. **On failure or not applicable**: Display a warning but do not stop the pipeline:\n   - If `resolve_target_status` returned null: `"Ticket status transition skipped: no target status configured for this project"`\n   - If `update_jira_status` failed: `"Ticket status transition skipped: <error message>"`\n\nThis stage is **non-critical** \u2014 log a warning on failure but do not stop the pipeline.\n\n## Stage 6 \u2014 Smoke Test Validation Comment\n\nThis stage reviews the implementation against the ticket requirements and posts a comment if manual validation is needed.\n\n1. **Fetch ticket description**: Call the `get_ticket` MCP tool with `ticket_number` set to the `ticket_key` to retrieve the current ticket requirements.\n\n2. **Review implementation**: Compare the implementation (from the plan loaded in Stage 2 and the files committed in Stage 3) against the ticket requirements. Identify any behavior or requirements that could NOT be validated through the automated tests written during implementation or through code review alone. Consider the limitations of any tests that were written: what functionality or behavior could not be validated by those tests? Examples include: requirements involving visual UI rendering or layout checks, third-party system integrations where mock tests are insufficient, or non-deterministic behaviors.\n\n3. **If untestable requirements exist**: Compose a structured comment describing specific manual validation steps stakeholders should perform. Then call the `add_comment` MCP tool with `ticket_number` set to the `ticket_key` and the comment text. Display: `"Smoke test validation comment posted to <ticket_key>"`.\n\n4. **If no untestable requirements exist**: Skip silently. Display: `"No untestable requirements identified \u2014 skipping smoke test comment"`.\n\nThis stage is **non-critical** \u2014 log a warning on failure but do not stop the pipeline.\n\n## Final Report\n\nOn success, display the structured report from Stage 4 confirming that the commit and push are complete, including the branch name, commit hash, file list, and any warnings from earlier stages.\n\nOn failure at any critical stage (Stage 0, Stage 1, or Stage 3), display which stage failed and the error details.\n',
   "create-doc.md": 'Generate a design document (TDD, FSD, or PRD) for a Jira ticket, wait for the result, and save it locally.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nExecute all steps in this command as a simple linear sequence of MCP tool calls.\n\n## Step 1 \u2014 Parse Arguments\n\n1. **Parse `$ARGUMENTS`**: Extract a required `ticket_key`, a required `--doc-type` flag, an optional `--second-opinion` flag, and an optional `--provider` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--doc-type` appears followed by one of `tdd`, `fsd`, or `prd`, capture that as `doc_type`.\n   - If `--doc-type` is absent, or is followed by anything other than `tdd`/`fsd`/`prd` (or is the last token), stop immediately and report: "Usage error: --doc-type requires a document type (tdd, fsd, or prd)."\n   - If `--second-opinion` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `second_opinion_value`.\n   - If `--second-opinion` appears without a provider name following it (or is the last token), set `second_opinion_value = "auto"`.\n   - If `--second-opinion` is absent, set `second_opinion_value = null`.\n   - If `--provider` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `provider_value`.\n   - If `--provider` appears without a valid provider name following it (or is the last token), stop immediately and report: "Usage error: --provider requires a provider name (openai, anthropic, or gemini)."\n   - If `--provider` is absent, set `provider_value = null`.\n   - If both `--second-opinion` and `--provider` are present, `--second-opinion` takes precedence (set `provider_value = null`).\n   - The remaining token (after removing flags and their arguments) is the `ticket_key`.\n\n2. **Validate ticket key format**: Confirm the ticket key matches the Jira key pattern `[A-Za-z][A-Za-z0-9]+-\\d+`. If it does not match (or `ticket_key` is empty or missing), stop immediately and display:\n\n   ```\n   Usage: /create-doc <ticket_key> --doc-type <tdd|fsd|prd> [--second-opinion [provider]] [--provider <name>] (e.g., /create-doc BAPI-150 --doc-type fsd)\n   ```\n\n## Step 2 \u2014 Resolve Docs Directory\n\nCall the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n## Step 3 \u2014 Generate Design Document\n\nCall the `create_doc` MCP tool with:\n- `ticket_number`: the validated `ticket_key`\n- `doc_type`: the parsed `doc_type` (`tdd`, `fsd`, or `prd`)\n- `wait_for_result`: `true`\n- `save_locally`: `true`\n- `second_opinion`: set to `second_opinion_value` if non-null; omit entirely if null\n- `provider`: set to `provider_value` if non-null; omit entirely if null\n\nThis step may take 2-4 minutes while the backend processes the document.\n\nIf the tool returns an error, stop immediately and display:\n\n```\nDesign document generation failed: <error message from the tool>\n```\n\nIf generation did not finish, the document can be retrieved later with the `get_doc` MCP tool using the same `ticket_number` and `doc_type`.\n\n## Step 4 \u2014 Confirm Success\n\nResolve the local file path from `doc_type`:\n- `tdd` \u2192 `{docs_dir}/architecture/<ticket_key>-architecture-plan.md`\n- `fsd` \u2192 `{docs_dir}/fsd/<ticket_key>-fsd-plan.md`\n- `prd` \u2192 `{docs_dir}/prd/<ticket_key>-prd-plan.md`\n\nDisplay a confirmation message:\n\n```\nDesign document generated successfully for <ticket_key>\nSaved to: <local file path>\n```\n\n## Final Summary\n\nDisplay a summary block:\n\n```\n## Design Document Report\n\n- **Ticket**: <ticket_key>\n- **Doc Type**: <doc_type>\n- **Status**: Generated successfully\n- **Local File**: <local file path>\n```\n\nOn failure at any step, stop immediately, display which step failed and the error details, and do not proceed.\n',
   "create-pr.md": '# Create PR: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes a Jira ticket key (e.g., `BAPI-150`), fetches the ticket summary, determines the base branch, and creates a pull request on the configured VCS provider. It is designed to run after `/commit-ticket` completes.\n\nIf any critical stage fails (Stage 0), stop immediately and report which stage failed and why. Non-critical stages (Stage 1 and Stage 2) should log a warning but not stop the pipeline.\n\n---\n\n# Instructions\n\nYou are executing a 3-stage pipeline to create a pull request for a Jira ticket. Execute all stages in sequence.\n\n## Stage 0 \u2014 Setup and Argument Parsing\n\n1. **Parse `$ARGUMENTS`**: Extract a single required `ticket_key` argument. The expected format is a Jira ticket key such as `BAPI-150` or `PROJ-123` \u2014 one or more uppercase letters, a hyphen, and one or more digits (regex: `[A-Z]+-\\d+`). If `$ARGUMENTS` is empty or the value does not match the expected format, stop immediately and display:\n\n   ```\n   Invalid ticket key format: \'<value>\'. Expected format: PROJ-123 (uppercase letters, hyphen, digits).\n   Usage: /create-pr <ticket_key> (e.g., /create-pr BAPI-150)\n   ```\n\n2. **Connectivity check**: Call the `ping` MCP tool (no parameters). If the ping fails or does not return `"status": "ok"`, stop immediately and display:\n\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor\'s MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\n3. **Get current branch**: Run `git branch --show-current` in the terminal. Store the result as `head_branch`. Verify that `head_branch` contains the `ticket_key` (case-insensitive comparison). If the branch does not contain the ticket key, stop immediately and display:\n\n   ```\n   Current branch \'<head_branch>\' does not contain ticket key <ticket_key>.\n   Please switch to the correct feature branch before running /create-pr.\n   ```\n\n4. **Resolve base branch**: Call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to `base_branch`. If the tool returns null, or an HTTP 400 Validation Error / Invalid field name, treat it as not set and fallback to `main`. Store the resolved value as `base_branch`.\n\n5. **Fetch ticket summary**: Call the `get_ticket` MCP tool with `ticket_number` set to the parsed `ticket_key`. Extract the ticket summary from the response. If the tool returns an error, log a warning and use a generic summary based on the ticket key.\n\n6. **Resolve docs directory**: Call the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Create Pull Request\n\n1. **Compose PR title**: Format the title as `<ticket_key>: <ticket_summary>`. Truncate to 72 characters if needed.\n\n2. **Compose PR body**: Build a PR body that includes:\n   - A brief description derived from the ticket summary\n   - A plain text reference to the local implementation plan: `Implementation Plan available locally at {docs_dir}/plans/{ticket_key}-plan.md` (do not use markdown hyperlink syntax \u2014 the local path is sufficient for team members pulling the branch)\n\n3. **Create the pull request**: Call the `create_pull_request` MCP tool with:\n   - `head_branch`: the current branch from Stage 0\n   - `base_branch`: the resolved base branch from Stage 0\n   - `title`: the composed PR title\n   - `body`: the composed PR body\n\n4. **Handle the response with graceful degradation**:\n   - If the response contains `available: false`: Report the reason to the user and skip to Stage 2. Do not halt the pipeline.\n   - If the response contains `created: false`: Log "PR already exists" and store the returned PR URL. Continue to Stage 2.\n   - If the response contains `created: true`: Store the PR URL. Continue to Stage 2.\n   - If an HTTP error occurs: Warn the user with the error details and continue to Stage 2. Do not halt the pipeline.\n\nThis stage is **non-critical** \u2014 warn on failure, continue to Stage 2 regardless.\n\n## Stage 2 \u2014 Summary Report\n\nDisplay a structured report after all stages complete:\n\n```\n## Pull Request Report\n\n**Ticket**: <ticket_key>\n**Branch**: <head_branch>\n**Base Branch**: <base_branch>\n**PR URL**: <pr_url or "N/A \u2014 see warnings">\n\n**Warnings**:\n<If any non-critical stages had warnings (Stage 1: PR creation failed or unavailable),\nlist them here. If no warnings, omit this section.>\n```\n\nThis stage is **non-critical** \u2014 display the report regardless.\n\n## Final Report\n\nOn success, display the structured report from Stage 2 confirming that the pull request was created (or already existed), including the branch name, base branch, PR URL, and any warnings from earlier stages.\n\nOn failure at any critical stage (Stage 0), display which stage failed and the error details.\n',
@@ -14836,12 +15475,14 @@ var COMMANDS = {
   "plan-ticket.md": 'Generate an implementation plan for a Jira ticket, wait for the result, and save it locally.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nExecute all steps in this command as a simple linear sequence of MCP tool calls.\n\n## Step 1 \u2014 Parse Arguments\n\n1. **Parse `$ARGUMENTS`**: Extract a required `ticket_key`, an optional `--second-opinion` flag, and an optional `--provider` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--second-opinion` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `second_opinion_value`.\n   - If `--second-opinion` appears without a provider name following it (or is the last token), set `second_opinion_value = "auto"`.\n   - If `--second-opinion` is absent, set `second_opinion_value = null`.\n   - If `--provider` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `provider_value`.\n   - If `--provider` appears without a valid provider name following it (or is the last token), stop immediately and report: "Usage error: --provider requires a provider name (openai, anthropic, or gemini)."\n   - If `--provider` is absent, set `provider_value = null`.\n   - If both `--second-opinion` and `--provider` are present, `--second-opinion` takes precedence (set `provider_value = null`).\n   - The remaining token (after removing flags and their arguments) is the `ticket_key`.\n   - If `ticket_key` is empty or missing, stop immediately and display:\n\n   ```\n   Usage: /plan-ticket <ticket_key> [--second-opinion [provider]] [--provider <name>] (e.g., /plan-ticket BAPI-150)\n   ```\n\n## Step 2 \u2014 Resolve Docs Directory\n\nCall the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n## Step 3 \u2014 Generate Plan\n\nCall the `request_plan_generation` MCP tool with:\n- `ticket_number`: the parsed `ticket_key`\n- `wait_for_result`: `true`\n- `save_locally`: `true`\n- `second_opinion`: set to `second_opinion_value` if non-null; omit entirely if null\n- `provider`: set to `provider_value` if non-null; omit entirely if null\n\nThis step may take 1-5 minutes while the backend processes the plan.\n\nIf the tool returns an error, stop immediately and display:\n\n```\nPlan generation failed: <error message from the tool>\n```\n\n## Step 4 \u2014 Confirm Success\n\nDisplay a confirmation message:\n\n```\nPlan generated successfully for <ticket_key>\nSaved to: {docs_dir}/plans/<ticket_key>-plan.md\n```\n\n## Final Summary\n\nDisplay a summary block:\n\n```\n## Plan Generation Report\n\n- **Ticket**: <ticket_key>\n- **Plan Status**: Generated successfully\n- **Local File**: {docs_dir}/plans/<ticket_key>-plan.md\n```\n\nOn failure at any step, stop immediately, display which step failed and the error details, and do not proceed.\n',
   "regression-check.md": 'Run the deterministic regression-reviewer (lightweight mode) against a proposed code change and report its blast radius \u2014 which real call-sites, tests, mocks, or config the change does and doesn\'t account for.\n\n$ARGUMENTS\n\n---\n\n<!-- Platform coverage: this command reaches Cursor + Claude Code (the commands\n     bundle is scaffolded to .claude/commands/ and .cursor/commands/ by --init).\n     The companion `regression-reviewer` agent (agents/src/regression-reviewer.md)\n     reaches Claude Code + GitHub Copilot. Union: Cursor, Copilot, and Claude\n     Code all get this review, either via the command or the agent. -->\n\n# Instructions\n\nThis is the standalone diff/PR (or ticket-description) review entry point for the regression-reviewer (BAPI-460). It mirrors the `regression-reviewer` agent\'s orchestration exactly \u2014 same subcommand, same parsing, same report \u2014 so the same logical review behaves identically whether invoked as a Cursor command or a Claude Code agent.\n\n## Step 1 \u2014 Determine the Input Shape\n\nParse `$ARGUMENTS`:\n\n- If it looks like a git diff range, a ref, a PR number, or is empty (defaulting to the working tree vs. `HEAD`), treat this as a **diff/PR invocation**. Resolve a `--diff <range>` value when one is given (e.g. `main...HEAD`, a commit SHA range); omit `--diff` to use the default working-tree-vs-HEAD diff.\n- If it names specific function/class/symbol names (e.g. `--symbols resolve_db_params,SomeClass`, or prose describing a not-yet-diffed planned change), treat this as a **ticket-description invocation**. Extract the symbol names and pass them via `--symbols a,b,c`.\n\nIf neither a diff nor any extractable symbol names are available, stop and ask the user to provide one.\n\n## Step 2 \u2014 Run the Deterministic Core\n\nExecute exactly:\n\n```bash\nnpx -y @bridge_gpt/mcp-server regression-check --mode lightweight --json [--diff <range> | --symbols a,b,c]\n```\n\nDo NOT hand-roll your own `ast-grep`/`ripgrep` invocations or re-discover call-sites yourself \u2014 the subcommand owns that structural analysis.\n\n## Step 3 \u2014 Parse the Findings (Fail-Open)\n\nParse the JSON: `summary.symbols_analyzed`, `summary.truncated`, `summary.tools_used`, `summary.degraded_flags`, and the `findings` array (`symbol`, `file`, `definition_location`, `call_sites` (`count`, `by_file`), `broad_mentions`).\n\nIf `summary.degraded_flags` is non-empty (e.g. `ast-grep` or `ripgrep` was unavailable), do NOT treat the run as a failure. Proceed with whatever data IS present and call out each degraded section explicitly \u2014 never silently drop a gap. If `summary.truncated` is `true`, state that the symbol set was capped.\n\n**Ripgrep degradation formatting**: if any entry in `summary.degraded_flags` mentions ripgrep, render it with an action-first visual hierarchy of three scannable segments rather than as a plain sentence:\n1. **Status/Problem** \u2014 a warning header with a semantic warning indicator (e.g. \u26A0\uFE0F).\n2. **Root Cause** \u2014 a brief note that `rg` must be a real binary on `PATH`; a shell function/alias is invisible to the spawned subcommand.\n3. **Remediation** \u2014 a standalone, copy-pasteable install command (e.g. `brew install ripgrep`) on its own line.\n\nApply monospace typography (backticks) to every reference to a system command, CLI tool (`rg`), environment term (`PATH`), or installation package, in this warning and throughout the report.\n\n## Step 4 \u2014 Synthesize Risk\n\nFor each symbol, compare `call_sites.count` against `broad_mentions.length`:\n- **Accounted for**: every real call-site and broad mention is either already touched by the change or clearly unaffected (e.g. a doc/comment mention).\n- **Not accounted for**: a real call-site, or an uninspected broad mention, sits in a file the proposed change does not touch. Name the specific file.\n\nRank "not accounted for" items by how directly they call the changed symbol (a real call-site outranks a textual mention).\n\n## Step 5 \u2014 Propose De-Risking (Diagnostic Synthesis, Not a Patch)\n\nFor each "not accounted for" item, name ONE of:\n- **Update the affected caller**: point to the exact `file:line` and describe what needs to change there.\n- **Add a compatibility/guard seam**: when updating every caller isn\'t right (e.g. a public API, a config key read elsewhere), describe the seam needed \u2014 not its full implementation.\n\nDo NOT implement the fix. State what needs to happen and where.\n\n## Final Output\n\nPrint this report to chat (no file write required):\n\n```markdown\n# Regression Review: [Symbol(s) / Change Description]\n\n**Mode**: lightweight\n**Input**: [--diff <range> | --symbols a,b,c]\n**Tools used**: [summary.tools_used, joined]\n**Degraded**: [list summary.degraded_flags, or "none"]\n**Symbols analyzed**: [summary.symbols_analyzed.length][ \u2014 TRUNCATED, capped at N if summary.truncated]\n\n## Summary\n\n[2-3 sentences: overall risk level, how many symbols are fully accounted for vs. not, and any degraded-tool caveats.]\n\n## Systems Accounted For / Not Accounted For\n\nRender as a `.data-table`-style markdown table (bold header row; left-aligned `Symbol` / `File` columns; tight \u2705/\u26A0\uFE0F status indicators):\n\n| Symbol | File | Real Call-Sites | Broad Mentions | Status |\n|---|---|---|---|---|\n| `helper` | `src/foo.py` | 3 | 4 | \u26A0\uFE0F Not accounted for |\n| `caller` | `src/foo.py` | 1 | 1 | \u2705 Accounted for |\n\nIf `definition_location` is `null` for a symbol, degrade gracefully \u2014 do not leave the `File` column blank. Render a muted `\u2014` placeholder there instead.\n\n## De-Risking Guidance\n\n### 1. [Symbol / File]\n- **Issue**: [what\'s not accounted for, with file:line]\n- **Recommendation**: Update the affected caller at `file:line` | Add a compatibility/guard seam \u2014 [describe]\n\n[Continue for each not-accounted-for item]\n\n---\n\n*Generated by regression-check (lightweight mode). Structural findings via ast-grep + ripgrep; Pinecone semantic search not available.*\n```\n',
   "reimplement-ticket.md": "# Reimplement Ticket: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command retrieves the reimplement context for a previously-implemented Jira ticket via MCP, then implements follow-up changes inline. Use this for small follow-up requests on tickets that have already been through the plan+implement cycle.\n\nIf any critical stage fails (Stage 0 or Stage 1), stop immediately and report which stage failed and why.\n\n---\n\n# Instructions\n\nYou are executing a 4-stage pipeline to implement follow-up changes on a Jira ticket using assembled reimplement context. Execute all stages in sequence.\n\n## Stage 0 \u2014 Setup and Argument Parsing\n\n1. **Parse `$ARGUMENTS`**: Extract a required `ticket_key`, an optional `--second-opinion` flag, and an optional `--provider` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--second-opinion` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `second_opinion_value`.\n   - If `--second-opinion` appears without a provider name following it (or is the last token), set `second_opinion_value = \"auto\"`.\n   - If `--second-opinion` is absent, set `second_opinion_value = null`.\n   - If `--provider` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `provider_value`.\n   - If `--provider` appears without a valid provider name following it (or is the last token), stop immediately and report: \"Usage error: --provider requires a provider name (openai, anthropic, or gemini).\"\n   - If `--provider` is absent, set `provider_value = null`.\n   - If both `--second-opinion` and `--provider` are present, `--second-opinion` takes precedence (set `provider_value = null`).\n   - The remaining token (after removing flags and their arguments) is the `ticket_key`.\n   - If `ticket_key` is empty or does not match the expected format (one or more uppercase letters, a hyphen, and one or more digits), stop immediately and display:\n\n   ```\n   Invalid ticket key format: '<value>'. Expected format: PROJ-123 (uppercase letters, hyphen, digits).\n   Usage: /reimplement-ticket <ticket_key> [--second-opinion [provider]] [--provider <name>] (e.g., /reimplement-ticket BAPI-150)\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Request and Retrieve Reimplement Context\n\nCall the `request_reimplement_context` MCP tool with:\n- `ticket_number`: the parsed `ticket_key` from Stage 0\n- `wait_for_result`: `true`\n- `save_locally`: `true`\n- `second_opinion`: set to `second_opinion_value` if it is non-null; omit the parameter entirely if `second_opinion_value` is null\n- `provider`: set to `provider_value` if it is non-null; omit the parameter entirely if `provider_value` is null\n\nIf the tool returns an error or 404 persists after polling, stop immediately and display:\n\n```\nFailed to retrieve reimplement context for <ticket_key>.\nThis may mean:\n- The ticket has not been previously processed by Bridge API\n- Background processing failed \u2014 check server logs\n- The ticket does not exist in Jira\n\nTry running /plan-ticket <ticket_key> first if this is a new ticket.\n```\n\nOn success, read and internalize the returned context markdown. This document contains:\n- A summary of changes (if applicable)\n- New/changed information since last processing (comments, description changes, attachments)\n- The original ticket description\n- The existing implementation plan (at the bottom, for reference only)\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 2.\n\n## Stage 2 \u2014 Implement Follow-Up Changes\n\nExecute changes inline in this conversation. Work directly so the user can see all progress and approve tool calls.\n\nFollow these rules:\n\n1. **Focus on the new information.** The context document identifies what has changed since the last implementation. Focus your changes on addressing the new/changed requirements.\n2. **Reference the existing plan as supplementary guidance only.** The plan at the bottom of the context describes the original implementation, not the follow-up. Use it to understand the existing code structure, not as a step-by-step guide.\n3. **Make code changes** as directed by the new information.\n4. **Run tests and checks** to verify your changes don't break existing functionality.\n5. **Do NOT run `git commit` or `git push`.** Leave all changes uncommitted for developer review.\n6. **Scope guard**: If the follow-up changes are too large in scope (e.g., fundamentally restructuring the original implementation, touching more than 5-6 files, or requiring new infrastructure), stop and ask the user for guidance rather than attempting everything. Follow-up reimplementations should be small and targeted.\n7. **If a change is ambiguous or blocked**, note the issue clearly and continue with the next change rather than halting entirely.\n\nThis stage is **critical** \u2014 if a blocking error prevents further progress, stop and report the failure.\n\n## Stage 3 \u2014 Final Summary Report\n\nDisplay a structured report after all stages complete:\n\n```\n## Reimplement Complete\n\n**Ticket**: <ticket_key>\n\n**Changes Made**:\n- <brief summary of each change>\n\n**Developer Action Items**:\n- All changes are uncommitted. Review the changes with `git diff` before committing.\n- Run the project's test suite to verify nothing is broken before committing.\n\n**Warnings**:\n<If any issues arose during implementation (scope concerns, ambiguous requirements,\nfiles that couldn't be modified), list them here. If no warnings, omit this section.>\n```\n\n## Final Report\n\nOn success, display the structured report from Stage 3 confirming that the follow-up changes are complete.\n\nOn failure at any critical stage (Stage 0 or Stage 1), display which stage failed and the error details.\n",
+  "review-and-implement.md": '---\nschedulable: true\ninteractive: true\narguments: {"positionals":[{"name":"ticketKey","type":"string","required":true}],"flags":[{"name":"auto","flag":"--auto","type":"boolean"},{"name":"rounds","flag":"--rounds","type":"string"},{"name":"baseBranch","flag":"--base-branch","type":"string"}]}\n---\n\n# Review and Implement: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command runs inside a single already-created worktree (typically spawned by `/start-tickets --workflow review-and-implement`, or its front door `/review-and-start`): it reviews the ticket via `/review-ticket`, pauses at a per-ticket human proceed/halt gate, and only then implements it via `/implement-ticket`. It creates no worktrees, refreshes no base branch, and does not monitor sibling sessions \u2014 those responsibilities stay in the launcher (`start-tickets`) and the parent front-door command.\n\n---\n\n# Instructions\n\n## Argument Parsing\n\nParse `$ARGUMENTS`:\n\n1. **Ticket key**: exactly one required token matching the Jira key pattern (`[A-Z][A-Z0-9]+-\\d+`). If zero tokens match, or more than one token matches, stop immediately and display:\n   ```\n   Invalid ticket key. Expected exactly one key, e.g. PROJ-123.\n   Usage: /review-and-implement <ticket_key> [--auto] [--rounds=1|2] [--base-branch=BRANCH]\n   ```\n2. **`--auto`**: an optional position-independent flag. When present, sets chain-level `auto_approve` to `true`. This single flag applies to BOTH the review phase and the implementation phase below \u2014 there is no separate review-auto or implementation-auto state.\n3. **`--rounds`**: an optional position-independent `--rounds <n>` / `--rounds=<n>` argument, `1` or `2`. Normalize either form to `--rounds=<n>`. Reject any other value:\n   ```\n   Invalid --rounds value. Expected: --rounds=1 or --rounds=2.\n   Usage: /review-and-implement <ticket_key> [--auto] [--rounds=1|2] [--base-branch=BRANCH]\n   ```\n   When omitted, forward no `--rounds` to `/review-ticket` (the backend\'s difficulty-adaptive review policy decides the shape).\n4. **`--base-branch`**: an optional position-independent `--base-branch <branch>` / `--base-branch=<branch>` argument. Validate it using the same rules `/start-tickets` Stage 0 uses: after trimming, non-empty, at most 255 characters, must not start with `-`, and must not contain ASCII control characters (`0x00`\u2013`0x1F` or `0x7F`). Reject a malformed value:\n   ```\n   Invalid --base-branch value: <reason>\n   Usage: /review-and-implement <ticket_key> [--auto] [--rounds=1|2] [--base-branch=BRANCH]\n   ```\n\n## Phase 1 \u2014 Review (inline)\n\nInvoke `/review-ticket <ticket_key>` **inline, in this same session**, forwarding:\n- `--auto` when chain-level `auto_approve` is `true`.\n- The normalized `--rounds=<n>` when `--rounds` was supplied.\n- `--base-branch=<branch>` when it was supplied.\n\n`/review-ticket` grounds its codebase evaluation against a **fresh `git archive` of `origin/<base>`**, materialized into an isolated temp directory via `materialize_fresh_base` (see `docs/BAPI-474-ground-review-against-fresh-base.md`) \u2014 NOT against this worktree\'s own working tree. Review therefore behaves identically whether run standalone or, as here, inside a worktree that `start-tickets` already created; the worktree\'s isolation exists for the implementation phase below, not for review\'s codebase grounding.\n\nIf the review pipeline itself fails (any step reports `Status: Failed at step N`), halt this ticket immediately \u2014 in **both** auto and non-auto mode \u2014 before Phase 2 or Phase 3 run. Report:\n```\nReview failed for <ticket_key> at step N. Implementation was not started.\n```\nDo not attempt any cleanup; the worktree/branch remains available for manual inspection or cleanup.\n\n## Phase 2 \u2014 Halt Gate\n\n`/review-ticket` produces **decisions that rewrite the ticket** \u2014 it does NOT emit a binary approve/decline verdict token. Do not parse, infer, or synthesize an approve/decline signal from its output; no such token exists to parse.\n\n- **When chain-level `auto_approve` is `true`** and Phase 1 completed successfully: skip this gate entirely and proceed straight to Phase 3.\n- **Otherwise** (non-auto, and Phase 1 completed successfully): after the ticket has been rewritten, ask the user exactly:\n  ```\n  Proceed to implementation for <ticket_key>? (y/N)\n  ```\n  Treat an empty response, any negative response (`n`, `no`, or similar), or any ambiguous/unrecognized response as **halt** \u2014 do not guess intent. On halt, report:\n  ```\n  Halted before implementation for <ticket_key> (declined). The worktree/branch remains available for manual cleanup.\n  ```\n  and stop. Do not perform Phase 3 or any cleanup.\n- On an explicit affirmative response (`y` or `yes`), proceed to Phase 3.\n\n## Phase 3 \u2014 Implement (inline)\n\nInvoke `/implement-ticket <ticket_key>` **inline, in this same session**, appending `--auto` when chain-level `auto_approve` is `true` (and omitting it on the manual-confirmation path). This is the same single chain-level `--auto` from Phase 1 \u2014 there is no separate implementation-only auto flag.\n\n## Scope\n\nThis command composes `/review-ticket` and `/implement-ticket`; it owns none of their internals and must not:\n- create, re-cut, or switch a Worktrunk worktree,\n- refresh or fetch the launcher\'s base branch,\n- monitor or coordinate with sibling `/review-and-implement` sessions spawned for other tickets,\n- orchestrate the parent `start-tickets` / `/review-and-start` session.\n\nA halt (review failure or a declined gate) affects **this ticket only** \u2014 sibling worktrees spawned for other keys are unaffected. Review and implementation share the single difficulty-derived model tier selected when this session was spawned by `start-tickets`; this command does not re-resolve or override model routing.\n',
+  "review-and-start.md": '---\nschedulable: true\narguments: {"positionals":[{"name":"ticketKeys","type":"string","required":true,"variadic":true}],"flags":[{"name":"auto","flag":"--auto","type":"boolean"},{"name":"rounds","flag":"--rounds","type":"string"},{"name":"agent","flag":"--agent","type":"string"},{"name":"baseBranch","flag":"--base-branch","type":"string"},{"name":"maxParallel","flag":"--max-parallel","type":"string"},{"name":"dryRun","flag":"--dry-run","type":"boolean"}]}\n---\n\n# Review and Start: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes one or more Jira ticket keys (e.g., `BAPI-248` or `BAPI-248 BAPI-250` \u2014 both flow through the identical ordered `keys: string[]` path) and spawns one refreshed, self-contained Worktrunk worktree per ticket, each running `/review-and-implement <KEY>` \u2014 review, then a per-ticket human proceed/halt gate, then implementation. It is the **recommended front door** for chaining "review these tickets, then implement the ones that pass" starting from *existing ticket keys* (the entry point `/full-automation` lacks, since its server orchestrator only accepts an idea).\n\nIt is a thin shim over the packaged `start-tickets` CLI, invoked with `--workflow review-and-implement`: this command performs the same connectivity check and branch enrichment as `/start-tickets`, then hands off to the identical worktree/base-refresh/model-routing/credential/cross-platform-spawn/`doctor` engine \u2014 reused verbatim. The review\u2192implement halt-gate decision logic lives entirely in the spawned `/review-and-implement` session, never here or in the CLI. Using `start-tickets --workflow review-and-implement` directly (documented in `commands/src/start-tickets.md`) remains available as the lower-level launcher seam this command drives.\n\n---\n\n# Instructions\n\nYou are executing a 4-stage pipeline that resolves connectivity and per-ticket branch names, then spawns N parallel Worktrunk worktrees via the packaged CLI\'s `--workflow review-and-implement` seam. Execute all stages in sequence directly in the main thread.\n\n## Stage 0 \u2014 Argument Parsing and Connectivity Check\n\n1. **Parse `$ARGUMENTS`** into ticket keys and pass-through flags:\n   - **Ticket keys**: every whitespace-separated token matching `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). A single key and multiple keys flow through the identical ordered `keys: string[]` path \u2014 there is no separate single-ticket code path. If zero keys are found, stop immediately and display:\n     ```\n     No ticket keys found in arguments. Expected one or more keys like BAPI-248.\n     Usage: /review-and-start [flags] <KEY> [KEY ...] (e.g., /review-and-start BAPI-248 BAPI-250)\n     ```\n   - **`--auto`**: a single chain-level flag. When present, it is forwarded to `start-tickets --auto`, which threads it into BOTH the review and implementation phases of every spawned `/review-and-implement <KEY>` session.\n   - **`--rounds`**: normalize `--rounds 1`/`--rounds=1` and `--rounds 2`/`--rounds=2` to `--rounds=<n>`; reject any other value. This value is forwarded to the review phase of every spawned session.\n   - **Selected agent**: validate `--agent <name>` / `--agent=<name>` against `claude`/`cursor-agent` using the same rule as `/start-tickets`; default `claude`.\n   - **User-supplied base branch**: validate `--base-branch <branch>` / `--base-branch=<branch>` using the same non-empty/\u2264255-character/no-leading-dash/no-control-character rules as `/start-tickets` Stage 0. A user-supplied value takes precedence over Stage 2a\'s `config_field` resolution below.\n   - **`--max-parallel N`**: a positive integer; the CLI\'s own default (3) applies when omitted.\n   - **`--dry-run`**: a boolean toggle.\n   - Reject malformed input before proceeding: an unsupported flag, a ticket key not matching `[A-Z]+-[0-9]+`, an unsupported `--agent`/`--rounds`/`--base-branch` value \u2014 stop and report the malformed argument.\n\n2. **Connectivity check**: Call the `ping` MCP tool (no parameters). If the ping fails or does not return `"status": "ok"`, stop immediately and display:\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor\'s MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Acknowledge CLI Pre-flight\n\nThe packaged `start-tickets` CLI (driven with `--workflow review-and-implement` in Stage 3) owns all platform pre-flight checks, refreshed worktree creation, secret-free credential provisioning, difficulty\u2192model-tier routing, and cross-platform terminal spawning \u2014 identical to `/start-tickets`. This command does not duplicate or re-verify any of that; see `commands/src/start-tickets.md` Stage 1 for the full prerequisite/provisioning description it drives. This command does not expose `--conductor`, `--terminal`, or `--no-refresh-main`/`--no-refresh-base` \u2014 it stays scoped to the front-door flags listed above. Proceed to Stage 2.\n\n## Stage 2 \u2014 Resolve Base Branch + Enrich Branch Names (best-effort)\n\n### Stage 2a \u2014 Resolve Base Branch\n\nIdentical to `/start-tickets` Stage 2a: if the user supplied `--base-branch`, use it and skip the `config_field` lookup entirely. Otherwise call `config_field` (`operation: "get"`, `field_name: "base_branch"`) and treat a non-empty string `value` as the configured base branch; treat `null`, an empty/whitespace-only string, an HTTP `400` response, or any other lookup failure as "unset" and omit `--base-branch` from Stage 3 (the CLI then defaults to `main`). When forwarding a resolved value into the Stage 3 Bash invocation, apply the same mandatory single-quote escaping rule as `/start-tickets` (`\'` \u2192 `\'\\\'\'`, then wrap the whole value in single quotes) before interpolating it into the command string \u2014 never expand it unquoted.\n\n### Stage 2b \u2014 Enrich Branch Names\n\nIdentical to `/start-tickets` Stage 2b: for each ticket key without a user-provided `--branch` override, call `get_ticket` (`ticket_number` set to the key, `save_locally: false`), slugify its `summary` (lowercase, collapse runs of `[^a-z0-9]+` to a single `-`, trim leading/trailing dashes, truncate to at most 40 characters preferring a dash boundary), and build `feature/<KEY>-<slug>`. On any per-key failure (404, network error, empty slug), emit a warning and let the CLI apply its default `feature/<KEY>` for that key only; never stop the pipeline. Credentials never reach the Bash-spawned CLI \u2014 this enrichment stays in the command, exactly as in `/start-tickets`.\n\nThis stage is **non-critical** \u2014 warnings are acceptable; the pipeline continues with the fallback branch for any key that fails enrichment.\n\n## Stage 3 \u2014 Invoke the Packaged CLI\n\nUse the **Bash tool** to invoke exactly **one** CLI invocation covering every requested key \u2014 never a per-key loop:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --workflow review-and-implement <pass-through-flags> <base-branch-flag> <branch-overrides> <ticket-keys>\n```\n\nWhere:\n- `<pass-through-flags>` forwards `--auto` (only if supplied), the normalized `--rounds=<n>` (only if supplied), `--agent <name>` (only if supplied), `--max-parallel N` (only if supplied), and `--dry-run` (only if supplied) verbatim.\n- `<base-branch-flag>` is `--base-branch \'<escaped-value>\'` only when a value was resolved in Stage 2a; otherwise omitted entirely.\n- `<branch-overrides>` is the list of `--branch KEY=BRANCH` flags assembled in Stage 2b.\n- `<ticket-keys>` is the original ordered list of keys parsed in Stage 0.\n\nCredentials are never placed in this shell command \u2014 the same secret-free provisioning path `/start-tickets` uses applies here unchanged.\n\nExample, single key, hands-off:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --workflow review-and-implement --auto --rounds=1 --branch BAPI-248=feature/BAPI-248-add-pr-rating-pre-evaluation-step BAPI-248\n```\n\nExample, multiple keys, manual per-ticket gate (no `--auto`):\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --workflow review-and-implement --branch BAPI-248=feature/BAPI-248-add-pr-rating-pre-evaluation-step --branch BAPI-250=feature/BAPI-250-deep-research-durability BAPI-248 BAPI-250\n```\n\nPass through the CLI\'s stdout and stderr to the user verbatim. If the CLI exits non-zero, treat that as a critical failure: report the exit code and the CLI\'s error output, and stop.\n\nThis stage is **critical** \u2014 propagate any non-zero exit from the packaged CLI.\n\n## Stage 4 \u2014 Final Report\n\nOnce the CLI exits 0, parse its `Summary` section (one stable line per ticket: `KEY  branch=BRANCH  status=STATUS`, optional trailing `path=PATH`) and reformat it as a markdown table, identical in shape to `/start-tickets` Stage 4 (`Ticket | Branch | Status`; statuses `dry-run`, `spawned`, `create-failed`, `spawn-failed`).\n\nThis report describes **worktree/spawn status only**. State explicitly in the report:\n- Each successfully spawned session independently continues through `/review-ticket`, its own per-ticket halt gate, and `/implement-ticket` \u2014 this parent session does not observe or report that later outcome. Never claim or imply that review or implementation has completed.\n- When `--dry-run` was passed, state explicitly that no worktrees were created and no tabs/sessions were opened.\n- As a fixed trade-off of this design: the difficulty-derived model tier selected at spawn time serves the **entire** chained review-and-implement session (both phases share one model), and a non-auto (including a non-auto scheduled) run pauses at each ticket\'s own gate rather than proceeding hands-off.\n\nIf the CLI reported any `create-failed`/`spawn-failed` statuses, or Stage 2b emitted enrichment warnings, list them under a `Warnings:` heading. If there were none, omit that section.\n\nSee `docs/claude/parallel-worktrees.md` for the underlying runbook this command builds on, and `commands/src/review-and-implement.md` for the per-ticket review\u2192gate\u2192implement composition each spawned session runs.\n',
   "review-ticket.md": '---\nschedulable: true\ninteractive: true\narguments: {"positionals":[{"name":"ticketKey","type":"string","required":true}],"flags":[{"name":"auto","flag":"--auto","type":"boolean"},{"name":"rounds","flag":"--rounds","type":"string"},{"name":"noRefreshBase","flag":"--no-refresh-base","type":"boolean"},{"name":"baseBranch","flag":"--base-branch","type":"string"},{"name":"baseSha","flag":"--base-sha","type":"string"}]}\n---\n\n# Review Ticket\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command is recipe-driven. Do not call MCP tools directly -- the recipe determines which tools to call and with what parameters.\n\n1. Parse `$ARGUMENTS` to extract:\n   - A required `ticket_key` matching the Jira key pattern (`[A-Z][A-Z0-9]+-\\d+`).\n   - An optional position-independent `--auto` flag.\n   - An optional position-independent `--rounds=<n>` argument, where `<n>` is `1` or `2`.\n   - An optional position-independent `--no-refresh-base` flag.\n   - An optional position-independent `--base-branch=<branch>` argument.\n   - An optional position-independent `--base-sha=<sha>` argument.\n\n   Tokenize `$ARGUMENTS` on whitespace. The first token matching the Jira key pattern is the `ticket_key`; ignore any additional ticket-key tokens. The presence of a `--auto` token (anywhere in `$ARGUMENTS`) sets `auto_approve` to `true`. A token matching `--rounds=1` sets `rounds` to `1`; a token matching `--rounds=2` sets `rounds` to `2`. If no `--rounds` token is present, leave `rounds` unset (omitted) so the backend\'s difficulty-adaptive review policy can decide the review shape when enabled for this repo; when adaptive routing is disabled, unavailable, or the ticket\'s difficulty cannot be resolved, the backend falls back to a full premium second-opinion review. The presence of a `--no-refresh-base` token sets `no_refresh_base` to `true`. A token matching `--base-branch=<branch>` sets `base_branch` to `<branch>`. A token matching `--base-sha=<sha>` sets `base_sha` to `<sha>`.\n\n   `--auto`, `--rounds`, `--no-refresh-base`, `--base-branch`, and `--base-sha` are all independent and may be supplied in any combination.\n\n   If `$ARGUMENTS` is empty or contains no token matching the Jira key pattern, stop immediately and display:\n   ```\n   Invalid ticket key format. Expected: PROJ-123 [--auto] [--rounds=1|2] [--no-refresh-base] [--base-branch=BRANCH] [--base-sha=SHA]\n   Usage: /review-ticket <ticket_key> [--auto] [--rounds=1|2] [--no-refresh-base] [--base-branch=BRANCH] [--base-sha=SHA]\n   ```\n\n   If a `--rounds` token is present but its value is not `1` or `2`, stop and display:\n   ```\n   Invalid --rounds value. Expected: --rounds=1 or --rounds=2 (omit to let the backend decide adaptively; default falls back to a full review)\n   Usage: /review-ticket <ticket_key> [--auto] [--rounds=1|2] [--no-refresh-base] [--base-branch=BRANCH] [--base-sha=SHA]\n   ```\n\n2. Call the `get_pipeline_recipe` MCP tool with:\n   - `pipeline`: `"review-ticket"`\n   - `variables`: `{ "ticket_key": "<ticket_key>", "base_branch": "<base_branch or "">", "base_sha": "<base_sha or "">", "no_refresh_base": "<"true" if --no-refresh-base was passed, else "">" }`\n   - `auto_approve`: `true` \u2014 only when `--auto` was passed; otherwise omit this field entirely.\n   - `rounds`: `1` \u2014 only when `--rounds=1` was explicitly passed on the command; `2` \u2014 only when `--rounds=2` was explicitly passed. When `--rounds` was NOT supplied, omit `rounds` entirely (do not pass `rounds: null`) so the backend\'s difficulty-adaptive review policy can choose the review shape when enabled for this repo. An explicit `rounds` value is forwarded to the backend and forces the review shape: `--rounds=1` requests a single-pass review, and `--rounds=2` forces the full second-opinion review even when adaptive routing is enabled. Do NOT translate `rounds` into `skip_steps` \u2014 the backend executor now owns all round orchestration (including any second-opinion rounds), so the recipe carries a single `request_ticket_review` step and you never pass `skip_steps` for round control.\n\n   Example combined-mode payload (`--rounds=1 --auto --base-branch=develop`):\n   ```json\n   {\n     "pipeline": "review-ticket",\n     "variables": { "ticket_key": "PROJ-123", "base_branch": "develop", "base_sha": "", "no_refresh_base": "" },\n     "auto_approve": true,\n     "rounds": 1\n   }\n   ```\n\n   Example explicit full-review payload (`--rounds=2`), which forces the full second-opinion review even if adaptive routing is enabled for this repo:\n   ```json\n   {\n     "pipeline": "review-ticket",\n     "variables": { "ticket_key": "PROJ-123", "base_branch": "", "base_sha": "", "no_refresh_base": "" },\n     "rounds": 2\n   }\n   ```\n\n   Example adaptive payload (no `--rounds`), which lets the backend policy executor decide the review shape (falling back to a full premium review when adaptive routing is disabled or the ticket\'s difficulty cannot be resolved):\n   ```json\n   {\n     "pipeline": "review-ticket",\n     "variables": { "ticket_key": "PROJ-123", "base_branch": "", "base_sha": "", "no_refresh_base": "" }\n   }\n   ```\n\n   If the tool returns an error, stop and report the failure.\n\n3. Read and strictly obey the `agent_instructions` field in the response. Execute each step in order, announcing each as **Step N of M: <description>**.\n\n4. After all steps complete, display a summary:\n   ```\n   ## Pipeline Complete\n\n   **Ticket**: <ticket_key>\n   **Steps executed**: N of M\n   **Status**: Success / Failed at step N\n   ```\n',
   "review-tickets.md": '---\nschedulable: true\ninteractive: true\narguments: {"positionals":[{"name":"ticketKeys","type":"string","required":true,"variadic":true}],"flags":[{"name":"auto","flag":"--auto","type":"boolean"},{"name":"rounds","flag":"--rounds","type":"string"},{"name":"review","flag":"--review","type":"string","repeatable":true},{"name":"agent","flag":"--agent","type":"string"},{"name":"model","flag":"--model","type":"string"},{"name":"maxParallel","flag":"--max-parallel","type":"string"},{"name":"dryRun","flag":"--dry-run","type":"boolean"},{"name":"noRefreshBase","flag":"--no-refresh-base","type":"boolean"},{"name":"baseBranch","flag":"--base-branch","type":"string"}]}\n---\n\n# Review Tickets: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes one or more Jira ticket keys and invokes the packaged `@bridge_gpt/mcp-server` CLI subcommand `review-tickets`, which opens one terminal tab per ticket running the selected agent with `/review-ticket <KEY> [--auto] [--rounds=<1|2>]`. By default `--rounds` is omitted so the backend routes each review by difficulty (difficulty-adaptive review); pass an explicit `--rounds=1|2` (globally or per ticket) to force the review shape. Unlike `/start-tickets`, it creates no Worktrunk worktrees \u2014 but it now requires `git` on PATH: the parent process fetches `origin/<base_branch>` once and pins a single `base_sha` for the whole batch before spawning tabs (BAPI-474), so every spawned review grounds its codebase evaluation against the same freshly-fetched base tree. Pass `--no-refresh-base` to skip this and restore the prior git-free, in-place-grounded behavior.\n\n---\n\n# Instructions\n\n## Stage 0 \u2014 Parse Arguments and Connectivity Check\n\n1. **Parse `$ARGUMENTS`** to extract ticket keys, review modes, and pass-through flags:\n\n   - **Ticket keys**: every whitespace-separated token matching `[A-Z]+-[0-9]+` (e.g., `BAPI-1`). If zero keys are found, stop immediately and display:\n     ```\n     No ticket keys found. Expected one or more keys like BAPI-1.\n     Usage: /review-tickets [flags] KEY [KEY ...]\n     ```\n\n   - **Review mode interpretation** (per ticket or global):\n     - `auto` or `--auto` \u2192 per-ticket or global auto-approve flag.\n     - `single-pass`, `one-pass`, `rounds=1`, or `--rounds=1` \u2192 `rounds=1` (single-pass review).\n     - `full`, `two-pass`, `rounds=2`, or `--rounds=2` \u2192 `rounds=2` (full second-opinion review).\n     - **omitted rounds \u2192 `adaptive`**: when no rounds mode is given for a ticket, do NOT choose a round count \u2014 leave it adaptive so the backend\'s difficulty-adaptive review policy decides the shape. `adaptive` is a distinct mode from `1` and `2`.\n     - `--auto` and `--rounds` are independent: both may apply to the same ticket.\n\n     The backend executor now owns all review round orchestration (including any second-opinion rounds) server-side \u2014 there is no client-side step to skip, so this command never sends `skip_steps` and never translates `--rounds=1` into skipping a second-opinion step. An explicit `--rounds` value forwarded to each spawned `/review-ticket` forces the review shape (`1` = single pass, `2` = full second-opinion review). A spawned `/review-ticket` invoked without any `--rounds` (the default) lets the backend\'s difficulty-adaptive review policy decide the shape (falling back to a full premium second-opinion review when adaptive routing is disabled, unavailable, or the ticket\'s difficulty cannot be resolved). This batch command therefore forwards **no** `--rounds` by default; it only forwards `--rounds` when the caller explicitly supplies a rounds mode (globally via `--rounds`, or per ticket via `--review`).\n\n   - **Homogeneous modes**: when all tickets share the same auto and rounds mode, translate into global `--auto` (if all auto) and, only when all tickets share the same *explicit* rounds value, global `--rounds=1|2`. When all tickets are adaptive (no rounds given), omit `--rounds` entirely \u2014 do not synthesize a default.\n\n   - **Heterogeneous modes**: when tickets differ in auto or rounds mode, translate into repeatable `--review KEY=auto,rounds=N` overrides. Only emit a `rounds=N` subtoken for tickets given an explicit `1`/`2`; adaptive tickets carry no `rounds` subtoken (a bare `--review KEY=auto` if they are auto, or no override at all). Do NOT set global `--auto` when only some tickets are auto-approved, and do NOT set global `--rounds` when only some tickets have an explicit rounds value.\n\n   - **Pass-through flags**: collect `--dry-run`, `--max-parallel N`, `--agent claude|cursor-agent`, `--model VALUE`, `--no-refresh-base`, and `--base-branch VALUE` if supplied, and forward verbatim to the CLI.\n\n2. **Connectivity check**: Call the `ping` MCP tool. If it fails or does not return `"status": "ok"`, stop immediately and display:\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor\'s MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\n## Stage 1 \u2014 Invoke the Packaged CLI\n\nUse the **Bash tool** to invoke exactly one CLI invocation:\n\n```\nnpx -y @bridge_gpt/mcp-server review-tickets [--auto] [--rounds=1|2] [--review KEY=auto,rounds=N ...] [--agent <name>] [--model <alias>] [--max-parallel N] [--dry-run] [--no-refresh-base] [--base-branch BRANCH] KEY [KEY ...]\n```\n\n- `review-tickets` runs all tabs from the current repository cwd \u2014 it creates no worktrees.\n- The command never runs `wt` or `git-wt` \u2014 but it now requires `git` on PATH (BAPI-474): before spawning any tabs, the parent process fetches `origin/<base_branch>` once and pins a single `base_sha` for the whole batch, so a mid-batch `origin` advance can never mix bases within one run. Pass `--no-refresh-base` to skip the fetch and restore the prior git-free, in-place-grounded behavior.\n- Prerequisites: macOS `osascript` + `git`, Windows `wt.exe` or PowerShell + `git`, Linux `tmux` + `git` (git is not required when `--no-refresh-base` is passed).\n\nPass through the CLI\'s stdout and stderr verbatim. If the CLI exits non-zero, treat it as a critical failure and report the exit code and error output.\n\n## Stage 2 \u2014 Final Report\n\nOnce the CLI exits 0, parse its `Summary:` lines (each shaped like `KEY  auto=<true|false>  rounds=<1|2|adaptive>  agent=<agent>  model=<alias|default>  status=<status>`) and render as a markdown table (`rounds=adaptive` means the backend chose the shape by difficulty):\n\n```\n| Ticket   | Auto  | Rounds   | Agent  | Model   | Status  |\n|----------|-------|----------|--------|---------|---------|\n| BAPI-1   | false | adaptive | claude | default | spawned |\n| BAPI-2   | true  | 1        | claude | default | spawned |\n```\n\nRender any CLI `Warnings:` lines below the table. If there were none, omit the warnings section.\n',
   "run-tests.md": 'Run the project\'s full test suite (unit and E2E) using the project-configured test stacks, triage failures, fix test-code issues, and produce a structured health-check report.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command discovers how to run tests by reading per-project configuration from the Bridge API, not from hardcoded paths. Stages run only when the project has the corresponding stack configured.\n\n## Stage 0 \u2014 Argument Parsing and Setup\n\n1. **Parse `$ARGUMENTS`** for optional flags. Supported flags:\n   - `--skip-e2e` \u2014 skip the E2E test stage even if an E2E stack is configured (e.g., when no local server is running)\n   - `--unit-only` \u2014 shorthand that implies `--skip-e2e`\n\n   Resolve flags to boolean variables:\n   - Start with: `run_unit = true`, `run_e2e = true`\n   - If `--unit-only` is present: set `run_e2e = false`\n   - If `--skip-e2e` is present: set `run_e2e = false`\n   - Unknown flags: note them in the final report as "Unrecognized flag ignored" but do not fail\n\n2. **Generate a run timestamp** using the current date and time in `YYYY-MM-DD-HH-MM` format (e.g., `2026-03-10-14-35`). Store this as `run_timestamp`. Both output documents will use this value.\n\nThis stage has no failure conditions \u2014 proceed to Stage 1.\n\n## Stage 1 \u2014 Resolve Project Config via MCP\n\nRead the per-project test setup from the Bridge database. Every subsequent stage is driven by what these calls return.\n\n1. **Resolve docs directory**: Call the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n2. **Read unit-test stack**: Call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to `unit_testing_stack`. Store the returned value as `unit_stack` (may be null/empty).\n\n3. **Read unit-test instructions**: Call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to `unit_testing_instructions`. Store the returned value as `unit_instructions` (may be null/empty).\n\n4. **Read E2E stack**: Call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to `e2e_testing_stack`. Store as `e2e_stack`.\n\n5. **Read E2E instructions**: Call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to `e2e_testing_instructions`. Store as `e2e_instructions`.\n\n6. **Compute configuration booleans**:\n   - `unit_configured` = `true` if either `unit_stack` or `unit_instructions` is a non-empty string; otherwise `false`\n   - `e2e_configured` = `true` if either `e2e_stack` or `e2e_instructions` is a non-empty string; otherwise `false`\n\n7. **Create the output directory**:\n   ```\n   mkdir -p {docs_dir}/testing/\n   ```\n   If this fails, stop immediately and report: `Cannot create output directory {docs_dir}/testing/ \u2014 check permissions.`\n\nIf any MCP call fails (e.g., the API is unreachable or returns 4xx/5xx), stop immediately and report which call failed. Do not fall back to hardcoded commands \u2014 the whole point of this command is that test setup lives in config.\n\n## Stage 2 \u2014 Unit / Standard Tests\n\nIf `run_unit` is `false`, skip this stage and record: `Unit tests: SKIPPED \u2014 run_unit was set to false (this should not happen in normal use; report as a bug).`\n\nIf `unit_configured` is `false`, skip and record:\n```\nUnit tests: SKIPPED \u2014 no unit_testing_stack or unit_testing_instructions configured for this repo. Configure via /learn-unit-testing or the project setup UI before running /run-tests.\n```\n\nOtherwise:\n\n1. Read `unit_instructions` carefully. It is the source of truth for **how to run unit tests in this repo** \u2014 runner binary, paths, environment activation, sub-suites (if the project distinguishes "unit" from "integration", both belong in this stage), and any flags. Pair it with `unit_stack` (a short label, e.g., `Pytest`, `Jest + React Testing Library`) for context.\n\n2. **Derive the test command(s)**: Extract the literal shell commands the instructions describe. If the instructions describe multiple sub-suites (e.g., a fast unit batch and a slower integration batch), plan to run each as a **separate batch** in the order described. Do not invent runners or paths that the instructions do not mention.\n\n3. **If the instructions do not specify any runnable command**, skip and record:\n   ```\n   Unit tests: SKIPPED \u2014 unit_testing_instructions does not describe how to invoke tests; please update via /learn-unit-testing.\n   ```\n\n4. **Run each batch sequentially** in the terminal. **Continue to the next batch even if the current one has failures.** Capture the full output of each batch, including the runner\'s summary line (e.g., `47 passed, 3 failed in 12.4s` or `Tests: 5 failed, 22 passed`).\n\n5. For each failing test, apply the **Triage Logic** (below), then record the result.\n\n## Stage 3 \u2014 E2E Tests\n\nIf `run_e2e` is `false`, skip this stage and record: `E2E tests: SKIPPED \u2014 --skip-e2e or --unit-only flag was set.`\n\nIf `e2e_configured` is `false`, skip and record:\n```\nE2E tests: SKIPPED \u2014 no e2e_testing_stack or e2e_testing_instructions configured (the project may not have an E2E suite).\n```\n\nOtherwise:\n\n1. Read `e2e_instructions`. It is the source of truth for the E2E runner, spec paths, browser config, and any prerequisites. Pair with `e2e_stack` for context.\n\n2. **Detect server prerequisites**: If `e2e_instructions` indicates that a local server must be running (look for explicit cues such as "server", "running", "localhost", "started", "dev server", a URL, or a port number) and describes a readiness check, perform that check exactly as described. If the instructions describe a server prerequisite but do not describe a check, attempt the check the instructions imply (e.g., curl the URL the instructions mention) and skip the stage if it fails:\n   ```\n   E2E tests: SKIPPED \u2014 e2e_testing_instructions describe a server prerequisite that wasn\'t met. Start the server per the instructions and re-run.\n   ```\n\n3. **Derive the test command(s)** from the instructions, including any spec-directory batching the instructions specify.\n\n4. **If the instructions do not specify any runnable command**, skip and record:\n   ```\n   E2E tests: SKIPPED \u2014 e2e_testing_instructions does not describe how to invoke tests; please update via /learn-e2e-testing.\n   ```\n\n5. **Run each batch sequentially** in the terminal. **Continue to the next batch even if the current one has failures.** Capture the full output and summary line of each batch.\n\n6. For each failing test, apply the **Triage Logic** (below), then record the result.\n\n## Triage Logic\n\nFor every failing test, examine the test file and the code it tests. Classify as ONE of the following:\n\n### TEST-CODE ISSUE \u2014 fix it directly\n\nClassify as a test-code issue if ANY of the following applies:\n- The test asserts against a hardcoded value that no longer matches current behavior (outdated mock data)\n- The test imports or calls a function that was renamed, moved, or removed\n- The test asserts on a response field that was restructured\n- The test expects a specific error message string that has since changed\n- A fixture references a removed table column, model field, or schema member\n\n**Action**: Apply a minimal, targeted fix to the test file only. Then re-run just that failing test, using the runner described in the relevant instructions field (`unit_instructions` for unit-test failures, `e2e_instructions` for E2E failures). Adapt the runner invocation that the instructions provide to target a single test, following whatever convention the instructions or stack idiomatically use.\n\nIf the re-run **still fails** after your fix, do not make further edits \u2014 escalate to implementation-code issue instead and revert your change.\n\n### IMPLEMENTATION-CODE ISSUE (or UNCERTAIN) \u2014 document, do not fix\n\nClassify as an implementation issue if ANY of the following applies:\n- The production function raises an unexpected exception\n- A handler returns the wrong status code or response shape for a documented behavior\n- Business logic produces incorrect output that the test correctly asserts against\n- You are not confident the test is wrong\n\n**Action**: Do NOT modify any file outside the test directories described in `unit_testing_instructions` / `e2e_testing_instructions`. When in doubt about whether a path is test-only, treat it as production code and escalate. Record the failure in the implementation-issues document for the user to triage.\n\n## Stage 4 \u2014 Write Output Documents\n\n### Document 1: Test Run Report (always write this)\n\nWrite to: `{docs_dir}/testing/test-run-{run_timestamp}.md`\n\n```markdown\n# Test Run: {run_timestamp}\n\n## Configuration\n- Unit stack: {unit_stack or "not configured"}\n- E2E stack: {e2e_stack or "not configured"}\n- Unit tests: RUN | SKIPPED \u2014 (reason)\n- E2E tests: RUN | SKIPPED \u2014 (reason)\n\n## Unit Tests\n**Stack**: {unit_stack or "not configured"}\n**Result**: X passed, Y failed (sum across batches)\n\n### Batch 1: `<command>`\n**Result**: X passed, Y failed\n**Fixes applied**:\n- `path/to/test_file`: brief description of what was fixed\n- (or "none" if no fixes were needed)\n\n### Batch 2: `<command>`\n...\n\n**Failures escalated as implementation issues**: N\n\n## E2E Tests\n**Stack**: {e2e_stack or "not configured"}\n**Result**: X passed, Y failed (sum across batches)\n\n### Batch 1: `<command>`\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### Batch 2: `<command>`\n...\n\n**Failures escalated as implementation issues**: N\n\n## Overall Summary\n- Total test fixes applied: N\n- Suspected implementation issues found: N\n- Implementation issues document: {docs_dir}/testing/implementation-issues-{run_timestamp}.md\n  (or "not created \u2014 no issues found")\n```\n\n### Document 2: Implementation Issues (only write if issues were found)\n\nIf at least one failure was escalated as an implementation-code issue, write to:\n`{docs_dir}/testing/implementation-issues-{run_timestamp}.md`\n\n```markdown\n# Suspected Implementation Issues: {run_timestamp}\n\nThese test failures were NOT fixed. They may indicate bugs in production code.\nA developer should investigate each item before merging.\n\n## Issue 1\n- **Test**: `path/to/test_file::test_function_name`\n- **Tier**: unit | e2e\n- **Failure message**: (paste the key assertion or exception line)\n- **Why not fixed**: (brief reasoning, e.g., "production function raises KeyError on valid input")\n\n## Issue 2\n...\n```\n\nIf no implementation issues were found, do NOT create this file.\n\n## Final Output\n\nAfter writing all documents, print this summary:\n\n```\nTest run complete: {run_timestamp}\nReport saved to: {docs_dir}/testing/test-run-{run_timestamp}.md\nImplementation issues: {docs_dir}/testing/implementation-issues-{run_timestamp}.md (if applicable)\nNo suspected implementation issues found. (if none)\n```\n',
-  "scan-test-coverage.md": 'Scan recently shipped tickets from git history and report which features have or could gain integration tests, and which can only be smoke tested.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nScan the git history for recently shipped tickets and, for each shipped feature, determine whether it already has an integration test, whether it *could* gain one (per this repo\'s conventions \u2014 a test that genuinely executes the system end-to-end via real database operations, real LLM calls, or real FastAPI routing), and \u2014 where integration testing is not possible \u2014 how it could be smoke tested so it still genuinely executes the system.\n\nThis is an **investigation and discovery** command. Describe features (citing code) and *how* they would be tested at a high level. Do **not** design tests in detail, build or edit any tests, or modify feature code. Orchestrate this run in the main thread, and **fan out one subagent per shipped feature** for the per-feature investigation.\n\nThe report is written to a **durable, committed** directory (`docs/test-coverage/`), and a marker file records when the analysis last ran so subsequent runs only inspect git history since the last run.\n\n## Stage 0 \u2014 Parse Arguments and Resolve Analysis Window\n\n1. Read `$ARGUMENTS`. All flags are optional and default-safe. If a flag is malformed, ignore it and add a warning:\n   - `--since=YYYY-MM-DD` \u2014 override the window start date.\n   - `--full` \u2014 ignore the marker and use a default lookback of 6 months.\n   - `--limit=N` \u2014 cap the number of features investigated (parse `N` as an integer; ignore if not a valid integer).\n   With no arguments, run **incrementally** from the marker.\n\n2. Set the durable directory to `docs/test-coverage/` (relative to the repo root) and the marker file to `docs/test-coverage/STATE.md`. This command deliberately does **not** use `get_docs_dir` \u2014 its default (`docs/tmp`) is ephemeral, and this report must be durable.\n\n3. Read `docs/test-coverage/STATE.md` if it exists. It records two values: `last_run_utc` (an ISO-8601 UTC timestamp) and `last_analyzed_commit` (a git commit SHA).\n\n4. Resolve the analysis window with this precedence:\n   - If `--since=YYYY-MM-DD` was given, use `git log --since=<date>`.\n   - Else if `STATE.md` provides `last_analyzed_commit`, use the commit range `<last_analyzed_commit>..HEAD`.\n   - Else (first run, no marker), default to `git log --since=<3 months ago>` (mirrors the `/scan-tickets` default of 3 months). Format the date as `YYYY-MM-DD`. Example: if today is 2026-07-07, the default `--since` is `2026-04-07`.\n   - `--full` overrides the above and uses a 6-month lookback (`--since=<6 months ago>`).\n\n5. Robustness of the marker: capture `head_sha` by running `git rev-parse HEAD`, and capture the current UTC timestamp now. These become the **new** marker values, but only write them after the report is successfully produced (Stage 4). If a stored `last_analyzed_commit` is not present in history (e.g. a rebase/rewrite), fall back to `git log --since=<the date part of last_run_utc>` and add a warning noting the fallback.\n\n6. Initialize tracking variables:\n   - `features` = [] (one entry per shipped feature)\n   - `warnings` = [] (per-item failures and fallbacks; the run never aborts on these)\n\n7. Display the resolved window, e.g. "Analyzing shipped features in `<range or --since date>` (HEAD = {head_sha})".\n\n## Stage 1 \u2014 Collect Shipped Features from Git History\n\n1. List merged commits in the resolved window with:\n   ```bash\n   git log <range> --first-parent --pretty=format:"%H|%h|%ad|%s" --date=short\n   ```\n   `--first-parent` yields roughly one entry per squashed PR merge.\n\n2. For each commit, extract the ticket key by matching `^BAPI-[0-9]+` against the subject. Group commits by ticket key. Commits with no ticket prefix (e.g. `Fix 500 on ...`) each become a standalone feature labeled as an "untracked change".\n\n3. For each group, collect the changed-file footprint across its commit(s) using `git show --stat <sha>` or `git diff --name-only`. This file footprint is the primary input to the per-feature investigation.\n\n4. Best-effort enrichment: for each ticket key, call the `get_ticket` MCP tool to fetch the ticket summary. This is **fail-open** \u2014 Jira tokens can be expired \u2014 so on any error, add a warning and continue without the summary. Do not abort.\n\n5. Build a `features` entry per group: `{ticket_key, subject, commit_shas, changed_files, jira_summary?}`. If `--limit=N` was given, keep only the first `N` features (most recent first).\n\n6. Display: "Found {count} shipped features to investigate."\n\n7. If `git log` returns no commits, skip to Stage 4 and write a report noting an empty window (and still refresh the marker).\n\n## Stage 2 \u2014 Investigate Each Feature (fan out subagents)\n\nFor each feature in `features`, launch an **Explore** subagent (batch several in parallel). Give each subagent the feature\'s `ticket_key`, `subject`, `changed_files`, and `jira_summary`, and instruct it to do read-only investigation only \u2014 no edits, no test design, no solutioning \u2014 and to return a structured finding.\n\nEach subagent must:\n\n1. Read the changed files and describe what the feature does in 2\u20134 sentences, with concrete `file:line` citations.\n\n2. Identify the feature\'s runtime surface \u2014 one or more of: real database operations (`postgres_client` / a DAL in `api/library/db/`), real LLM calls (`src/python/llms/ai_client.py`, `async_send_message_to_ai`), real FastAPI routing (a route handler under `api/routes/`), an MCP tool (`mcp_server/`), a shell-spawned / CLI flow, a frontend / Playwright surface, or pure logic / config / docs / tests.\n\n3. Check whether an **integration test already exists**: search `tests/integration/` for a mirror path or for references to the changed modules/functions. The reliable classifier is a path under `tests/integration/` plus `@pytest.mark.integration` or reliance on the `--run-integration` flag (conventions in `docs/claude/testing-integration.md`). Cite any test found.\n\n4. Classify the feature into exactly one `bucket`:\n   - **`has_integration_test`** \u2014 already covered end-to-end; cite the existing integration test file.\n   - **`integration_testable`** \u2014 no test yet, but the feature exercises real DB / LLM / routing and fits an existing `tests/integration/<area>/` pattern. Give a **high-level** approach only: which real entrypoint to call, which backend it would exercise, and the relevant cost/guard note (the gpt-5-nano override via `INTEGRATION_TEST_MODEL`; the local-DB `skipif` guard; `save_to_db=False`). Cite the entrypoint in code.\n   - **`smoke_only`** \u2014 genuine end-to-end execution is possible but not as an automated integration test (e.g. MCP tool behavior inside a host, cross-platform terminal spawning, a headless agent session, or browser E2E). Describe how to smoke test it so it **genuinely executes the system**, citing the relevant runbook: `mcp_server/smoke-test/SMOKE-TEST.md`, `tests/mcp/`, `docs/claude/self-install-smoke-test.md`, `docs/claude/start-tickets-smoke-test.md`, or Playwright (`tests/playwright/`, which needs a running server plus `npm run build`).\n   - **`not_testable`** \u2014 nothing to execute end-to-end (docs-only, a wording/comment change, pure config, or a test-only change); state why.\n\n5. Return a structured finding with these fields: `ticket_key`, `subject`, `description_with_cites`, `surface`, `bucket`, `existing_test`, `approach`, `why_not`.\n\nCollect all findings. If a per-feature subagent fails, add a warning and continue \u2014 never abort the whole run.\n\n## Stage 3 \u2014 Classify and Synthesize\n\n1. Deduplicate features that span multiple commits (merge by `ticket_key`).\n\n2. Sort each finding into the two required report sections:\n   - **Section 1 \u2014 Integration Testing (covered or addable):** findings with `bucket` `has_integration_test` (sub-group "Already covered") or `integration_testable` (sub-group "Could be added").\n   - **Section 2 \u2014 Not Integration-Testable:** findings with `bucket` `smoke_only` (sub-group "Smoke-testable \u2014 how") or `not_testable` (sub-group "Not testable \u2014 why").\n\n## Stage 4 \u2014 Write the Report and Update the Marker\n\n1. Create the `docs/test-coverage/` directory if it does not exist. Choose the report path `docs/test-coverage/REPORT-<YYYYMMDD>.md`; if a same-day file already exists, append `-<HHMMSS>` to avoid clobbering it.\n\n2. Write the report with this layout:\n   - A title and a metadata block: generated-at UTC timestamp; the analysis window (`<from sha or since-date>` \u2192 `HEAD <head_sha>`); the feature count; and per-bucket tallies.\n   - **Section 1 \u2014 Integration Testing: Covered or Addable.** One `### BAPI-NNN \u2014 <subject>` heading per feature, each with **What shipped** (with `file:line` citations), **Current coverage** (cite the existing integration test, or state "none"), and **How it could be integration tested (high level)**.\n   - **Section 2 \u2014 Not Integration-Testable.** One heading per feature with the same feature description, plus **Why not integration-testable**, and \u2014 for `smoke_only` features \u2014 **How to smoke test (genuinely execute the system)** with the runbook citation.\n   - A **Warnings** section listing each warning as a bullet \u2014 only if `warnings` is non-empty.\n\n3. **Only after** the report file is written successfully, update the marker `docs/test-coverage/STATE.md` with the new `last_run_utc` (the UTC timestamp captured in Stage 0) and `last_analyzed_commit` set to `head_sha`. This date/commit marker is what makes the next run incremental. If the report write fails, do not touch `STATE.md`.\n\n## Final Report\n\nPrint a short summary to chat:\n\n```\n**Test-coverage scan complete**\n\n* Features analyzed: {count}\n* Already covered by integration tests: {n_has}\n* Integration-testable (could be added): {n_addable}\n* Smoke-only: {n_smoke}\n* Not testable: {n_none}\n\nReport: docs/test-coverage/REPORT-<YYYYMMDD>.md\nMarker updated: last_analyzed_commit = {head_sha}\n```\n\nIf `warnings` is non-empty, add a "Warnings:" section listing each warning as a bullet. If there are no warnings, omit that section.\n',
+  "scan-test-coverage.md": 'Scan recently shipped tickets from git history and report which features have or could gain integration tests, and which can only be smoke tested.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nScan the git history for recently shipped tickets and, for each shipped feature, determine whether it already has an integration test, whether it *could* gain one (per this repo\'s conventions \u2014 a test that genuinely executes the system end-to-end via real database operations, real LLM calls, or real FastAPI routing), and \u2014 where integration testing is not possible \u2014 how it could be smoke tested so it still genuinely executes the system.\n\nThis is an **investigation and discovery** command. Describe features (citing code) and *how* they would be tested at a high level. Do **not** design tests in detail, build or edit any tests, or modify feature code. Orchestrate this run in the main thread, and **fan out one subagent per shipped feature** for the per-feature investigation.\n\nThe report is written to a **durable, committed** directory (`docs/test-coverage/`), and a marker file records when the analysis last ran so subsequent runs only inspect git history since the last run.\n\n## Stage 0 \u2014 Parse Arguments and Resolve Analysis Window\n\n1. Read `$ARGUMENTS`. All flags are optional and default-safe. If a flag is malformed, ignore it and add a warning:\n   - `--since=YYYY-MM-DD` \u2014 override the window start date.\n   - `--full` \u2014 ignore the marker and use a default lookback of 6 months.\n   - `--limit=N` \u2014 cap the number of features investigated (parse `N` as an integer; ignore if not a valid integer).\n   With no arguments, run **incrementally** from the marker.\n\n2. Set the durable directory to `docs/test-coverage/` (relative to the repo root) and the marker file to `docs/test-coverage/STATE.md`. This command deliberately does **not** use `get_docs_dir` \u2014 its default (`docs/tmp`) is ephemeral, and this report must be durable.\n\n3. Read `docs/test-coverage/STATE.md` if it exists. It records two values: `last_run_utc` (an ISO-8601 UTC timestamp) and `last_analyzed_commit` (a git commit SHA).\n\n4. Resolve the analysis window with this precedence:\n   - If `--since=YYYY-MM-DD` was given, use `git log --since=<date>`.\n   - Else if `STATE.md` provides `last_analyzed_commit`, use the commit range `<last_analyzed_commit>..HEAD`.\n   - Else (first run, no marker), default to `git log --since=<3 months ago>` (mirrors the `/scan-tickets` default of 3 months). Format the date as `YYYY-MM-DD`. Example: if today is 2026-07-07, the default `--since` is `2026-04-07`.\n   - `--full` overrides the above and uses a 6-month lookback (`--since=<6 months ago>`).\n\n5. Robustness of the marker: capture `head_sha` by running `git rev-parse HEAD`, and capture the current UTC timestamp now. These become the **new** marker values, but only write them after the report is successfully produced (Stage 4). If a stored `last_analyzed_commit` is not present in history (e.g. a rebase/rewrite), fall back to `git log --since=<the date part of last_run_utc>` and add a warning noting the fallback.\n\n6. Initialize tracking variables:\n   - `features` = [] (one entry per shipped feature)\n   - `warnings` = [] (per-item failures and fallbacks; the run never aborts on these)\n\n7. Display the resolved window, e.g. "Analyzing shipped features in `<range or --since date>` (HEAD = {head_sha})".\n\n## Stage 1 \u2014 Collect Shipped Features from Git History\n\n1. List merged commits in the resolved window with:\n   ```bash\n   git log <range> --first-parent --pretty=format:"%H|%h|%ad|%s" --date=short\n   ```\n   `--first-parent` yields roughly one entry per squashed PR merge.\n\n2. For each commit, extract the ticket key by matching `^BAPI-[0-9]+` against the subject. Group commits by ticket key. Commits with no ticket prefix (e.g. `Fix 500 on ...`) each become a standalone feature labeled as an "untracked change".\n\n3. For each group, collect the changed-file footprint across its commit(s) using `git show --stat <sha>` or `git diff --name-only`. This file footprint is the primary input to the per-feature investigation.\n\n4. Best-effort enrichment: for each ticket key, call the `get_ticket` MCP tool to fetch the ticket summary. This is **fail-open** \u2014 Jira tokens can be expired \u2014 so on any error, add a warning and continue without the summary. Do not abort.\n\n5. Build a `features` entry per group: `{ticket_key, subject, commit_shas, changed_files, jira_summary?}`. If `--limit=N` was given, keep only the first `N` features (most recent first).\n\n6. Display: "Found {count} shipped features to investigate."\n\n7. If `git log` returns no commits, skip to Stage 4 and write a report noting an empty window (and still refresh the marker).\n\n## Stage 2 \u2014 Investigate Each Feature (fan out subagents)\n\nFor each feature in `features`, launch an **Explore** subagent (batch several in parallel). Give each subagent the feature\'s `ticket_key`, `subject`, `changed_files`, and `jira_summary`, and instruct it to do read-only investigation only \u2014 no edits, no test design, no solutioning \u2014 and to return a structured finding.\n\nEach subagent must:\n\n1. Read the changed files and describe what the feature does in 2\u20134 sentences, with concrete `file:line` citations.\n\n2. Identify the feature\'s runtime surface \u2014 one or more of: real database operations (`postgres_client` / a DAL in `api/library/db/`), real LLM calls (`src/python/llms/ai_client.py`, `async_send_message_to_ai`), real FastAPI routing (a route handler under `api/routes/`), an MCP tool (`mcp_server/`), a shell-spawned / CLI flow, a frontend / Playwright surface, or pure logic / config / docs / tests.\n\n3. Check whether an **integration test already exists**: search `tests/integration/` for a mirror path or for references to the changed modules/functions. The reliable classifier is a path under `tests/integration/` plus `@pytest.mark.integration` or reliance on the `--run-integration` flag (conventions in `docs/claude/testing-integration.md`). Cite any test found.\n\n4. Classify the feature into exactly one `bucket`:\n   - **`has_integration_test`** \u2014 already covered end-to-end; cite the existing integration test file.\n   - **`integration_testable`** \u2014 no test yet, but the feature exercises real DB / LLM / routing and fits an existing `tests/integration/<area>/` pattern. Give a **high-level** approach only: which real entrypoint to call, which backend it would exercise, and the relevant cost/guard note (the gpt-5-nano override via `INTEGRATION_TEST_MODEL`; the local-DB `skipif` guard; `save_to_db=False`). Cite the entrypoint in code.\n   - **`smoke_only`** \u2014 genuine end-to-end execution is possible but not as an automated integration test (e.g. MCP tool behavior inside a host, cross-platform terminal spawning, a headless agent session, or browser E2E). Describe how to smoke test it so it **genuinely executes the system**, citing the relevant runbook: `mcp_server/smoke-test/SMOKE-TEST.md`, `tests/mcp/`, `docs/claude/runbooks/self-install-smoke-test.md`, `docs/claude/runbooks/start-tickets-smoke-test.md`, or Playwright (`tests/playwright/`, which needs a running server plus `npm run build`).\n   - **`not_testable`** \u2014 nothing to execute end-to-end (docs-only, a wording/comment change, pure config, or a test-only change); state why.\n\n5. Return a structured finding with these fields: `ticket_key`, `subject`, `description_with_cites`, `surface`, `bucket`, `existing_test`, `approach`, `why_not`.\n\nCollect all findings. If a per-feature subagent fails, add a warning and continue \u2014 never abort the whole run.\n\n## Stage 3 \u2014 Classify and Synthesize\n\n1. Deduplicate features that span multiple commits (merge by `ticket_key`).\n\n2. Sort each finding into the two required report sections:\n   - **Section 1 \u2014 Integration Testing (covered or addable):** findings with `bucket` `has_integration_test` (sub-group "Already covered") or `integration_testable` (sub-group "Could be added").\n   - **Section 2 \u2014 Not Integration-Testable:** findings with `bucket` `smoke_only` (sub-group "Smoke-testable \u2014 how") or `not_testable` (sub-group "Not testable \u2014 why").\n\n## Stage 4 \u2014 Write the Report and Update the Marker\n\n1. Create the `docs/test-coverage/` directory if it does not exist. Choose the report path `docs/test-coverage/REPORT-<YYYYMMDD>.md`; if a same-day file already exists, append `-<HHMMSS>` to avoid clobbering it.\n\n2. Write the report with this layout:\n   - A title and a metadata block: generated-at UTC timestamp; the analysis window (`<from sha or since-date>` \u2192 `HEAD <head_sha>`); the feature count; and per-bucket tallies.\n   - **Section 1 \u2014 Integration Testing: Covered or Addable.** One `### BAPI-NNN \u2014 <subject>` heading per feature, each with **What shipped** (with `file:line` citations), **Current coverage** (cite the existing integration test, or state "none"), and **How it could be integration tested (high level)**.\n   - **Section 2 \u2014 Not Integration-Testable.** One heading per feature with the same feature description, plus **Why not integration-testable**, and \u2014 for `smoke_only` features \u2014 **How to smoke test (genuinely execute the system)** with the runbook citation.\n   - A **Warnings** section listing each warning as a bullet \u2014 only if `warnings` is non-empty.\n\n3. **Only after** the report file is written successfully, update the marker `docs/test-coverage/STATE.md` with the new `last_run_utc` (the UTC timestamp captured in Stage 0) and `last_analyzed_commit` set to `head_sha`. This date/commit marker is what makes the next run incremental. If the report write fails, do not touch `STATE.md`.\n\n## Final Report\n\nPrint a short summary to chat:\n\n```\n**Test-coverage scan complete**\n\n* Features analyzed: {count}\n* Already covered by integration tests: {n_has}\n* Integration-testable (could be added): {n_addable}\n* Smoke-only: {n_smoke}\n* Not testable: {n_none}\n\nReport: docs/test-coverage/REPORT-<YYYYMMDD>.md\nMarker updated: last_analyzed_commit = {head_sha}\n```\n\nIf `warnings` is non-empty, add a "Warnings:" section listing each warning as a bullet. If there are no warnings, omit that section.\n',
   "scan-tickets.md": '$ARGUMENTS\n\n---\n\n# Instructions\n\nSynchronize recently-updated Jira tickets with the local `tickets` database table and backfill missing workflow state timestamps. Perform all work directly in the main thread.\n\n## Stage 0 \u2014 Parse Arguments and Calculate Date\n\n1. Read the value of `$ARGUMENTS`. If it is empty, whitespace-only, or not a valid integer, default `months_back` to `3`. If it contains multiple tokens, extract only the first token and attempt to parse it as an integer. If parsing fails, default to `3`.\n\n2. Calculate `updated_since` by subtracting `months_back` months from today\'s date. Format the result as `YYYY-MM-DD`. Example: if today is 2026-03-07 and `months_back` is 3, then `updated_since` is 2025-12-07.\n\n3. Display the parsed values: "Scanning tickets updated since {updated_since} (months_back = {months_back})"\n\n4. Initialize the following tracking variables:\n   - `tickets_scanned` = 0 (total tickets fetched from Jira)\n   - `newly_tracked` = 0 (tickets inserted into database for the first time)\n   - `state_updated_list` = [] (list of objects with ticket key and fields updated)\n   - `warnings` = [] (list of warning strings for any per-ticket failures)\n\n## Stage 1 \u2014 Fetch All Tickets from Jira\n\n1. Initialize an empty list `all_tickets` and set `offset` to `0`.\n\n2. Enter a pagination loop:\n   - Call the `get_tickets` MCP tool with: `updated_since` set to the calculated date, `limit` set to `100`, and `offset` set to the current offset value.\n   - Parse the JSON response. The response contains a `tickets` array of ticket objects. Each ticket object has a `ticket_number` field (the Jira key, e.g., `BAPI-42`), along with `summary`, `status`, `issue_type`, `assignee`, and `updated_at`.\n   - Append all tickets from the response\'s `tickets` array to `all_tickets`.\n   - If the number of tickets returned in this page equals `100`, increment `offset` by `100` and repeat the loop.\n   - If fewer than `100` tickets are returned, exit the loop.\n\n3. Set `tickets_scanned` to the length of `all_tickets`.\n\n4. Display: "Fetched {tickets_scanned} tickets from Jira. Processing..."\n\n5. If the `get_tickets` call fails at any point during pagination, **stop** and report the error. Do not proceed to Stage 2.\n\n## Stage 2 \u2014 Track Each Ticket\n\n1. Iterate over each ticket in `all_tickets`. For each ticket:\n   - Call the `track_ticket` MCP tool with `ticket_number` set to the ticket\'s `ticket_number` field. If the ticket object includes a `summary` field, pass it as the `description` parameter.\n   - Inspect the response message. If the response indicates the ticket was newly created/inserted (look for words like "created" or "inserted" in the message, as opposed to "already exists" or "updated"), increment `newly_tracked` by 1.\n   - If the `track_ticket` call fails for this ticket, add a warning to the `warnings` list (e.g., "Warning: Failed to track ticket {ticket_number}: {error}") and **continue** to the next ticket. Do not abort the scan.\n\n2. Display a brief progress indicator every 25 tickets, e.g., "Tracked {N} of {tickets_scanned} tickets..."\n\n## Stage 3 \u2014 Detect and Backfill Workflow State\n\nDisplay: "Checking workflow state for {tickets_scanned} tickets..."\n\nIterate over each ticket in `all_tickets`. For each ticket (referenced by its `ticket_number` field), perform the following sub-steps. Wrap the entire per-ticket block in error handling: if the `get_ticket_state` call or the subsequent `update_ticket_state` call fails for a ticket, add a warning to `warnings` and continue to the next ticket.\n\n**Sub-step 4a \u2014 Retrieve current state**: Call the `get_ticket_state` MCP tool with `ticket_number` set to the ticket\'s key. The response contains:\n\n- Five timestamp fields (each is a timestamp string or null): `clarify_called`, `clarify_answered`, `critique_called`, `critique_answered`, `plan_generated`\n- Three boolean artifact flags: `has_clarifying_questions`, `has_critique`, `has_plan`\n\nIf the call returns a 404 or any error, add a warning to `warnings` and continue to the next ticket.\n\n**Sub-step 4b \u2014 Build fields_to_update list**: Initialize an empty `fields_to_update` list, then apply the following rules:\n\n- If `has_clarifying_questions` is `true` AND `clarify_called` is null -> add `"clarify_called"` to `fields_to_update`\n- If `has_clarifying_questions` is `true` AND `clarify_answered` is null -> add `"clarify_answered"` to `fields_to_update`\n- If `has_critique` is `true` AND `critique_called` is null -> add `"critique_called"` to `fields_to_update`\n- If `has_critique` is `true` AND `critique_answered` is null -> add `"critique_answered"` to `fields_to_update`\n- If `has_plan` is `true` AND `plan_generated` is null -> add `"plan_generated"` to `fields_to_update`\n\n**Sub-step 4c \u2014 Call update_ticket_state if needed**: If `fields_to_update` is non-empty, call the `update_ticket_state` MCP tool with `ticket_number` set to the ticket\'s key and `fields` set to the `fields_to_update` array. If this succeeds, add an entry to `state_updated_list` recording the ticket key and the list of fields that were set. If `update_ticket_state` fails, add a warning to `warnings` and continue.\n\nDisplay a progress indicator every 25 tickets that includes the current ticket key, e.g., "Checked state for {TICKET-KEY} ({N} of {tickets_scanned} tickets)"\n\n## Stage 4 \u2014 Report Summary\n\n1. Calculate `state_updated_count` as the length of `state_updated_list`.\n\n2. Display the summary:\n\n   ```\n   **Scan complete**\n\n   * Tickets scanned: {tickets_scanned}\n   * Newly tracked: {newly_tracked}\n   * State updated: {state_updated_count}\n   ```\n\n3. If `state_updated_list` is non-empty, display a section titled "Updated tickets:" with one bullet per ticket showing the ticket key and the comma-separated list of fields that were set. Example:\n\n   ```\n   Updated tickets:\n   * BAPI-101: clarify_called, clarify_answered\n   * BAPI-105: critique_called, critique_answered, plan_generated\n   ```\n\n4. If the `warnings` list is non-empty, display a section titled "Warnings:" listing each warning string as a bullet. Example:\n\n   ```\n   Warnings:\n   * Warning: Failed to track ticket BAPI-99: Connection timeout\n   * Warning: State query failed for BAPI-112: SQL error\n   ```\n\n5. If there are no warnings, do not display the "Warnings:" section.\n',
-  "start-tickets.md": '---\nschedulable: true\narguments: {"positionals":[{"name":"ticketKeys","type":"string","required":true,"variadic":true}],"flags":[{"name":"auto","flag":"--auto","type":"boolean"},{"name":"agent","flag":"--agent","type":"string"},{"name":"baseBranch","flag":"--base-branch","type":"string"},{"name":"maxParallel","flag":"--max-parallel","type":"string"},{"name":"dryRun","flag":"--dry-run","type":"boolean"}]}\n---\n\n# Start Tickets: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes one or more Jira ticket keys (e.g., `BAPI-248 BAPI-250`) and invokes the packaged `@bridge_gpt/mcp-server` CLI subcommand `start-tickets`, which creates a Worktrunk worktree for each key and opens one tab/session per worktree running the **selected agent** \u2014 Claude Code (`claude`) by default, or Cursor Agent (`cursor-agent`) via `--agent` \u2014 in a macOS Terminal/iTerm tab, a Windows Terminal tab (or PowerShell fallback window), or a detached Linux tmux session, chosen automatically by platform. It replaces Parts 2\u20135 of `docs/claude/parallel-worktrees.md` with a single command.\n\nBecause the orchestration ships inside the `@bridge_gpt/mcp-server` npm package (not a repo-local script), this command works for every consumer \u2014 including projects that installed the package via `--init`.\n\nStage 0 and Stage 1 are critical (stop on failure). Stage 2 is non-critical (per-ticket enrichment failures fall back to the default branch and continue). Stage 3 is critical (propagate the packaged CLI\'s exit code).\n\n---\n\n# Instructions\n\nYou are executing a 4-stage pipeline that spawns N parallel Worktrunk worktrees and selected-agent sessions (Claude Code by default) via the packaged CLI. Execute all stages in sequence directly in the main thread.\n\n## Stage 0 \u2014 Argument Parsing and Connectivity Check\n\n1. **Parse `$ARGUMENTS`** into ticket keys, pass-through flags, and branch overrides:\n   - **Ticket keys**: every whitespace-separated token matching `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). If zero keys are found, stop immediately and display:\n\n     ```\n     No ticket keys found in arguments. Expected one or more keys like BAPI-248.\n     Usage: /start-tickets [flags] <KEY> [KEY ...] (e.g., /start-tickets BAPI-248 BAPI-250)\n     ```\n\n   - **Pass-through flags**: collect any of `--agent <name>` (and the equals form `--agent=<name>`), `--terminal terminal|iterm`, `--dry-run`, `--auto`, `--no-refresh-main`, `--base-branch <branch>` (and the equals form `--base-branch=<branch>`), and `--max-parallel N` that the user supplied. These are forwarded verbatim to the CLI in Stage 3. `--auto` makes each spawned agent run `/implement-ticket <KEY> --auto` (hands-off implementation); omit it to keep the implementation agents interactive.\n   - **Selected agent**: track a `selected_agent` variable that defaults to `claude`. If the user passed `--agent <name>` / `--agent=<name>`, validate the value against the supported agents `claude` and `cursor-agent`, set `selected_agent` to it, and reject any other (malformed/unsupported) `--agent` value before proceeding. The agent is not auto-detected from the host editor \u2014 the user selects it explicitly (default `claude`).\n   - **User-supplied base branch**: track a `user_supplied_base_branch` boolean that defaults to `false`. If the user passed `--base-branch <branch>` or `--base-branch=<branch>`, set the boolean to `true` and capture the value. A user-supplied `--base-branch` value **takes precedence** over any value resolved from Bridge API config in Stage 2. Validate the user-supplied value before proceeding: after trimming surrounding whitespace it must be non-empty, at most 255 characters, must not start with `-`, and must not contain ASCII control characters (`0x00`\u2013`0x1F` or `0x7F`); reject any malformed value with a clear error.\n   - **User branch overrides**: collect any user-supplied repeatable `--branch KEY=BRANCH` flags. A user-provided override always takes precedence over Stage 2 enrichment for that key.\n   - Reject malformed input before proceeding: if a token looks like a flag but is not one of the supported flags, or a ticket key does not match `[A-Z]+-[0-9]+`, or a `--branch` value is not `KEY=BRANCH`, or `--agent` names an agent other than `claude`/`cursor-agent`, or `--base-branch` fails the validation rules above, stop and report the malformed argument.\n\n2. **Connectivity check**: Call the `ping` MCP tool (no parameters). If the ping fails or does not return `"status": "ok"`, stop immediately and display:\n\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor\'s MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Acknowledge CLI Pre-flight\n\nThe packaged CLI runs its own per-platform pre-flight checks and then fetches `origin` and fast-forwards the local **configured base branch** (the value resolved in Stage 2 below, or `main` when none is configured) from `origin/<base>` so the new worktrees are based on an up-to-date base. The historical flag `--no-refresh-main` still controls this behavior \u2014 the flag name is preserved for backward compatibility, but it now skips refresh of whatever base branch resolves (default `main`). The required commands depend on the OS:\n\n- **macOS**: `wt`, `git`, `osascript`.\n- **Windows**: `git-wt`, `git`, Git for Windows / Git Bash (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash), and Windows Terminal **or** PowerShell.\n- **Linux**: `wt`, `git`, `tmux`.\n\nOn **Windows** the Worktrunk binary is `git-wt` (its winget alias), which is a different tool from Windows Terminal\'s `wt.exe`: the CLI uses `git-wt` to **create worktrees** and `wt.exe` to **open a tab**, and never conflates the two. On **Linux** the CLI opens one detached `tmux` session per ticket (a window is added if that ticket\'s session already exists); attach later with `tmux attach -t <session>`. An unsupported OS (not macOS/Windows/Linux) fails fast with a clear "unsupported platform" message.\n\nThis stage simply notes that the CLI will fail fast if any prerequisite is missing or if local `main` has diverged from `origin/main` \u2014 you do not need to verify anything separately here, and you must not run any pre-flight commands yourself. When the CLI\'s pre-flight fails it now hints the user to run the read-only diagnostics command `npx -y @bridge_gpt/mcp-server doctor`, which reports found/missing for every prerequisite on the current OS \u2014 the pre-flight set plus `uv` plus the selected agent\'s command \u2014 and prints the manual install command for each missing one. `doctor` is strictly read-only and never installs anything; never run install commands automatically on the user\'s behalf. The CLI does not call any Bridge API tools; all credential-bearing work (branch enrichment in Stage 2) stays in this command. Proceed to Stage 2.\n\nThe packaged CLI also performs **secret-free Bridge API MCP provisioning** inside each created worktree: synchronously after the worktree is created and **before the agent tab/session is opened**, it writes both `.mcp.json` (Claude Code) and `.cursor/mcp.json` (Cursor) pointing at the `mcp-invoke` shim. These registrations are **secret-free** \u2014 they contain no `env` block and no API key, because the shim resolves credentials at runtime. If a spawned agent (or difficulty\u2192model routing) reports missing Bridge API credentials, fix it by rerunning `/install-bridge` (its final stage persists the routing credential), by running `npx -y @bridge_gpt/mcp-server credentials migrate-agent-config --write-credentials` to migrate a key that lives only in `.mcp.json` / `.cursor/mcp.json`, or by adding a `bapi:<repo>` entry to the user-scoped credentials file (`~/.config/bridge/credentials.json`) \u2014 never by putting `BAPI_API_KEY` into the worktree `.mcp.json` or `.cursor/mcp.json` (that env is invisible to the Bash-spawned CLI).\n\nThis stage is **critical** in the sense that the CLI will abort if its pre-flight fails; you will see the error in Stage 3\'s output and must surface it.\n\n## Stage 2 \u2014 Resolve Base Branch + Enrich Branch Names (best-effort)\n\n### Stage 2a \u2014 Resolve configured `base_branch`\n\nThe CLI must be told which branch to cut new worktrees from. Resolution order:\n\n1. If `user_supplied_base_branch` from Stage 0 is `true`, **skip the config-field lookup entirely** and use the user-supplied value. The user\'s explicit `--base-branch` always wins; never call `config_field` for `base_branch` in that case.\n2. Otherwise, call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to `base_branch` (do not pass any other parameters; the tool resolves the repository from the MCP server\'s configured `BAPI_REPO_NAME`).\n3. Parse the response. Treat the result as the **configured base branch** only when the response is a JSON object whose `value` field is a non-empty string after trimming surrounding whitespace.\n4. Treat **all** of the following as "unset" \u2014 emit a single-line warning like `Warning: base_branch is unset; CLI will default to main` and **omit** the `--base-branch` flag entirely from the Stage 3 command (the CLI\'s own default is `main`):\n   - `value` is `null`.\n   - `value` is an empty string or a whitespace-only string.\n   - The endpoint returns HTTP `400` (invalid field \u2014 happens before the registry includes `base_branch`).\n   - The tool returns a network error, timeout, or non-JSON parse failure.\n   - Any other lookup failure.\n5. When the configured value is usable, capture it in a `resolved_base_branch` variable. **Do not** stop the pipeline on a lookup failure; fall through to the CLI default.\n\nWhen forwarding `resolved_base_branch` into the Bash invocation in Stage 3, **shell-escape it safely**: replace every literal single quote `\'` in the value with the four-character sequence `\'\\\'\'`, then wrap the entire resulting string in single quotes (so the final argument looks like `\'<escaped-value>\'`). This is the standard POSIX single-quote escaping rule and is **mandatory** because `base_branch` is admin-configurable data that gets interpolated into a Bash command string; any unescaped single quote would otherwise break out of the surrounding quotes. Pass `--base-branch \'<escaped-value>\'` to the CLI as a single argv element \u2014 never expand the value unquoted into the command line.\n\n### Stage 2b \u2014 Enrich Branch Names\n\nBranch enrichment happens here, in the command, **before** invoking the CLI \u2014 the `get_ticket` MCP tool runs inside the MCP server process, which holds the Bridge API credentials the shell-spawned CLI does not have. For each parsed ticket key that does **not** already have a user-provided `--branch` override:\n\n1. Call the `get_ticket` MCP tool with `ticket_number` set to the key and `save_locally` set to `false`.\n2. From the response, extract the `summary` field. Slugify it: lowercase the string, replace every run of non-alphanumeric characters (`[^a-z0-9]+`) with a single dash `-`, trim leading and trailing dashes, and truncate to at most `40` characters (cutting at a dash boundary if possible).\n3. The enriched branch name is `feature/<KEY>-<slug>`. Example: `BAPI-248` with summary `"Add PR rating pre-evaluation step"` becomes `feature/BAPI-248-add-pr-rating-pre-evaluation-step` (trimmed at 40 chars).\n4. If the `get_ticket` call fails for a particular key (404, network error, missing summary) or produces an empty slug, emit a single-line warning like `Warning: could not enrich BAPI-248, falling back to feature/BAPI-248` and let the CLI apply its default `feature/<KEY>` for that key only. Do NOT stop the pipeline.\n5. Build a list of `--branch <KEY>=<BRANCH>` arguments \u2014 one entry per key whose enrichment succeeded \u2014 and merge it with any user-provided overrides from Stage 0. **Do not** call `get_ticket` for keys that already have a user-provided override; those overrides win.\n\nThis stage is **non-critical** \u2014 warnings are acceptable, the pipeline continues with the fallback default for any key that fails. Do not call the Bridge API from the CLI itself; the CLI never has credentials.\n\n## Stage 3 \u2014 Invoke the Packaged CLI\n\nUse the **Bash tool** to invoke the packaged CLI. Build the command line as:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets <pass-through-flags> <base-branch-flag> <branch-overrides> <ticket-keys>\n```\n\nWhere:\n- `<pass-through-flags>` are the supported flags collected in Stage 0 (`--agent`, `--terminal`, `--dry-run`, `--auto`, `--no-refresh-main`, `--max-parallel`), forwarded verbatim. Forward `--agent <name>` only if the user supplied it; otherwise omit it and the CLI defaults to `claude`. Forward `--auto` only if the user supplied it.\n- `<base-branch-flag>` is `--base-branch \'<escaped-value>\'` (single-quoted using the Stage 2a escaping rule) **only when** the user supplied `--base-branch` in Stage 0 **or** Stage 2a\'s `config_field` lookup returned a non-empty configured value. When the configured value is unset / lookup fails / user did not supply one, **omit this flag entirely** so the CLI\'s own default (`main`) takes effect.\n- `<branch-overrides>` is the list of `--branch KEY=BRANCH` flags assembled in Stage 2 (enrichment results merged with user overrides; omit any key whose enrichment failed and had no user override).\n- `<ticket-keys>` is the original list of ticket keys parsed in Stage 0, space-separated and in the original order.\n\nExample for two tickets after successful enrichment, throttled to 2 concurrent worktrees:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets \\\n  --max-parallel 2 \\\n  --branch BAPI-248=feature/BAPI-248-add-pr-rating-pre-evaluation-step \\\n  --branch BAPI-250=feature/BAPI-250-deep-research-durability \\\n  BAPI-248 BAPI-250\n```\n\nExample launching Cursor Agent instead of the default Claude Code:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248\n```\n\nExample cutting worktrees from a non-`main` base (either user-supplied via `--base-branch develop` in Stage 0 or resolved from Bridge API config in Stage 2a):\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --base-branch develop BAPI-248\n```\n\nPass through the CLI\'s stdout and stderr to the user verbatim. If the CLI exits non-zero, treat that as a critical failure: report the exit code and the CLI\'s error output, and stop.\n\nThis stage is **critical** \u2014 propagate any non-zero exit from the packaged CLI.\n\n## Stage 4 \u2014 Final Report\n\nOnce the CLI exits 0, parse its `Summary` section (one stable line per ticket in the form `KEY  branch=BRANCH  status=STATUS`, with an optional trailing `path=PATH`) and reformat it as a markdown table:\n\n```\n| Ticket   | Branch                                              | Status   |\n|----------|-----------------------------------------------------|----------|\n| BAPI-248 | feature/BAPI-248-add-pr-rating-pre-evaluation-step  | spawned  |\n| BAPI-250 | feature/BAPI-250-deep-research-durability           | spawned  |\n```\n\nStatus values are `dry-run`, `spawned`, `create-failed`, and `spawn-failed`. End the report with the worktree-first explanation, rendered for the tracked `selected_agent`. When `selected_agent` is `claude` (the default):\n\n```\nThe CLI created/switched each Worktrunk worktree first (throttled by --max-parallel),\nthen opened one tab/session per successful worktree (macOS Terminal/iTerm tab, Windows\nTerminal tab or PowerShell window, or Linux tmux session). Each one runs\n`claude \'/implement-ticket <KEY>\'` inside its already-created worktree, which launches\nClaude Code with the starter prompt as its first message. Switch to each tab \u2014 or on\nLinux run `tmux attach -t <session>` \u2014 to monitor.\n```\n\nWhen `selected_agent` is `cursor-agent`, render the same explanation but with the Cursor handoff \u2014 do **not** claim it launches Claude Code:\n\n```\nThe CLI created/switched each Worktrunk worktree first (throttled by --max-parallel),\nthen opened one tab/session per successful worktree (macOS Terminal/iTerm tab, Windows\nTerminal tab or PowerShell window, or Linux tmux session). Each one runs\n`cursor-agent \'/implement-ticket <KEY>\'` inside its already-created worktree, which\nlaunches Cursor Agent with the starter prompt as its first message. Switch to each\ntab \u2014 or on Linux run `tmux attach -t <session>` \u2014 to monitor.\n```\n\nThe `/implement-ticket <KEY>` prompt is identical for both agents; only the launched command differs. When start-tickets was invoked with `--auto`, the spawned prompt is `/implement-ticket <KEY> --auto` (the implementation pipeline runs hands-off, without approval gates).\n\nIf the CLI reported any `create-failed` or `spawn-failed` statuses, or Stage 2 emitted any enrichment warnings, list them under a `Warnings:` heading at the bottom of the report. If there were none, omit that section.\n\nSee `docs/claude/parallel-worktrees.md` for the deep-dive runbook and the Worktrunk verification result behind this worktree-first model.\n\n## Difficulty-Based Implementation-Model Routing\n\nBefore launching the interactive agent for each ticket, the packaged CLI selects an\nimplementation **model tier** from the ticket\'s `difficulty` rating (1-10) and injects\nit as a `--model` flag at the agent spawn boundary. This happens entirely inside the\nCLI \u2014 it is **not** part of the server-side `/implement-ticket` recipe, because the\nmodel an interactive agent session uses is fixed at the moment the process is launched.\n\n- **Tier ladder (fixed):** `difficulty 1-2 \u2192 cheap`, `3-5 \u2192 basic`, `6+ \u2192 premium`.\n- **Separation of concerns:** the Python backend returns only the coarse tier\n  (`cheap`/`basic`/`premium`) via `GET /jira/tickets/{KEY}/model-tier`; difficulty is\n  computed on demand and cached when absent. The TypeScript CLI alone maps a tier to\n  the agent-specific model alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`:\n  version-suffixed strings validated against `cursor-agent --list-models`).\n- **Per-repo config:**\n  - `difficulty_model_routing_enabled` \u2014 boolean, **default ON**. Set to `false` to\n    disable routing for a repo (the CLI then omits `--model`).\n  - `difficulty_model_tier_overrides` \u2014 a JSON object mapping a tier name to a model\n    alias (e.g. `{"premium": "opus"}`), **not** raw CLI arguments. Only `cheap`,\n    `basic`, and `premium` keys are accepted; aliases must match `^[A-Za-z0-9._:-]+$`.\n- **Fail-open:** routing never aborts a spawn. Credential, network, config, or\n  no-tier routing failures **assume a hard ticket and default to the premium/Opus\n  tier** when the selected agent supports a valid premium alias; routing being\n  disabled (`difficulty_model_routing_enabled = false`) or an agent that does not\n  support `--model` instead omit `--model` so the agent runs on its own default\n  model. Each degraded case is surfaced as exactly one secret-free, per-ticket\n  routing-diagnostic line, never a hard failure.\n\n### Model routing credential\n\nDifficulty\u2192model routing needs Bridge API credentials, and the shell-spawned\n`start-tickets` CLI is a **different runtime surface** from the MCP server: a\n`BAPI_API_KEY` that lives only in `.mcp.json` / `.cursor/mcp.json` is visible to\nthe MCP server but **not** to the Bash-spawned CLI, so routing silently degrades.\nThe durable source of truth both runtimes can resolve is the user-scoped store\n`~/.config/bridge/credentials.json`, keyed `bapi:<repo>`. If a routing-diagnostic\nline reports the credential is missing (e.g. difficulty resolves as `?`), fix it\nby any one of:\n\n1. Rerun `/install-bridge` \u2014 its final stage now persists the validated routing\n   credential into `~/.config/bridge/credentials.json` via the\n   `persist_routing_credential` tool.\n2. Migrate a key that lives **only** in `.mcp.json` / `.cursor/mcp.json` into the\n   user-scoped store with the consent-gated, one-shot command:\n\n   ```\n   npx -y @bridge_gpt/mcp-server credentials migrate-agent-config --write-credentials\n   ```\n\n3. Manually add `BAPI_API_KEY` under the `bapi:<repo>` target in the user-scoped\n   store `~/.config/bridge/credentials.json`.\n\nNever put `BAPI_API_KEY` into a worktree `.mcp.json` / `.cursor/mcp.json` as a fix \u2014\nthat env is invisible to the spawned CLI.\n\n## Conductor observability (opt-in via `--conductor`, BAPI-394)\n\nConductor is **opt-in**. By default `start-tickets` spawns the plain\n`cd <worktree> && <agent> \'/implement-ticket <KEY> [--auto]\'` \u2014 no\n`BAPI_CONDUCTOR_*` env, no supervisor window, and no message-relay instruction.\nPass `--conductor` (e.g. `/start-tickets --conductor BAPI-123`) to enable the\nConductor system below.\n\nWith `--conductor`, a run mints a single conductor `run_id` and attributes each\nworker\'s lifecycle events by `worker_id`, ticket key, and worktree path, and a\nsupervisor peer tab is opened. When the selected agent is **Claude Code**, the CLI\ninjects a conductor lifecycle hook into each created worktree\'s\n`.claude/settings.local.json` so the spawned session emits local `run.started` /\n`run.stopped` / `agent.notification` (and, when\n`BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE=1`, `tool.intent`) events into the local\nconductor ledger. These hooks apply **only** when the selected agent is Claude\nCode; other agents (e.g. `cursor-agent`) still participate in the run-level\n`run.started` event but receive no per-worktree Claude hook. Inspect the ledger\nwith the `conductor` CLI (e.g. `conductor doctor`). Conductor observability is\nbest-effort and never blocks or aborts a spawn.\n\nAlso under `--conductor`, each worker is launched with an explicit instruction to\ncall the `check_messages` MCP tool at checkpoints, so the supervisor can pass it\ntyped guidance mid-run (BAPI-397). Delivery is **cooperative** \u2014 the worker polls\nand acknowledges messages and they are never injected into a running session.\n(Epic-tick dispatch always runs with conductor enabled, independent of this\nuser-facing flag.)\n',
+  "start-tickets.md": '---\nschedulable: true\narguments: {"positionals":[{"name":"ticketKeys","type":"string","required":true,"variadic":true}],"flags":[{"name":"auto","flag":"--auto","type":"boolean"},{"name":"agent","flag":"--agent","type":"string"},{"name":"workflow","flag":"--workflow","type":"string"},{"name":"rounds","flag":"--rounds","type":"string"},{"name":"baseBranch","flag":"--base-branch","type":"string"},{"name":"maxParallel","flag":"--max-parallel","type":"string"},{"name":"dryRun","flag":"--dry-run","type":"boolean"}]}\n---\n\n# Start Tickets: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes one or more Jira ticket keys (e.g., `BAPI-248 BAPI-250`) and invokes the packaged `@bridge_gpt/mcp-server` CLI subcommand `start-tickets`, which creates a Worktrunk worktree for each key and opens one tab/session per worktree running the **selected agent** \u2014 Claude Code (`claude`) by default, or Cursor Agent (`cursor-agent`) via `--agent` \u2014 in a macOS Terminal/iTerm tab, a Windows Terminal tab (or PowerShell fallback window), or a detached Linux tmux session, chosen automatically by platform. It replaces Parts 2\u20135 of `docs/claude/parallel-worktrees.md` with a single command.\n\nBecause the orchestration ships inside the `@bridge_gpt/mcp-server` npm package (not a repo-local script), this command works for every consumer \u2014 including projects that installed the package via `--init`.\n\nFor existing ticket keys, `/review-and-start <KEYS>` is the **recommended front door**: it supplies the same connectivity check and branch enrichment as this command, then drives this same packaged CLI with `--workflow review-and-implement` so each worktree reviews the ticket before implementing it. Using `start-tickets --workflow review-and-implement` directly (documented below) remains available as the lower-level launcher seam.\n\nStage 0 and Stage 1 are critical (stop on failure). Stage 2 is non-critical (per-ticket enrichment failures fall back to the default branch and continue). Stage 3 is critical (propagate the packaged CLI\'s exit code).\n\n---\n\n# Instructions\n\nYou are executing a 4-stage pipeline that spawns N parallel Worktrunk worktrees and selected-agent sessions (Claude Code by default) via the packaged CLI. Execute all stages in sequence directly in the main thread.\n\n## Stage 0 \u2014 Argument Parsing and Connectivity Check\n\n1. **Parse `$ARGUMENTS`** into ticket keys, pass-through flags, and branch overrides:\n   - **Ticket keys**: every whitespace-separated token matching `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). If zero keys are found, stop immediately and display:\n\n     ```\n     No ticket keys found in arguments. Expected one or more keys like BAPI-248.\n     Usage: /start-tickets [flags] <KEY> [KEY ...] (e.g., /start-tickets BAPI-248 BAPI-250)\n     ```\n\n   - **Pass-through flags**: collect any of `--agent <name>` (and the equals form `--agent=<name>`), `--terminal terminal|iterm`, `--dry-run`, `--auto`, `--no-refresh-main`, `--base-branch <branch>` (and the equals form `--base-branch=<branch>`), and `--max-parallel N` that the user supplied. These are forwarded verbatim to the CLI in Stage 3. `--auto` makes each spawned agent run the selected workflow\'s slash command with `--auto` (hands-off); omit it to keep the spawned agents interactive.\n   - **Selected agent**: track a `selected_agent` variable that defaults to `claude`. If the user passed `--agent <name>` / `--agent=<name>`, validate the value against the supported agents `claude` and `cursor-agent`, set `selected_agent` to it, and reject any other (malformed/unsupported) `--agent` value before proceeding. The agent is not auto-detected from the host editor \u2014 the user selects it explicitly (default `claude`).\n   - **Selected workflow**: track a `selected_workflow` variable that defaults to `implement`. If the user passed `--workflow <value>` or `--workflow=<value>`, validate it against the two allowed values `implement` and `review-and-implement`, set `selected_workflow`, and reject any other value with the allowlist in the error. `implement` (the default) preserves today\'s behavior byte-for-byte \u2014 each spawned worktree runs `/implement-ticket <KEY> [--auto]`. `review-and-implement` spawns `/review-and-implement <KEY> [--auto] [--rounds=<n>]` instead, which runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` inside the same session. A single chain-level `--auto` applies to the selected workflow as a whole \u2014 under `review-and-implement` it auto-approves both the review and the implementation phase.\n   - **Review rounds**: track a `review_rounds` value that defaults to unset. If the user passed `--rounds <n>` or `--rounds=<n>`, normalize it to `--rounds=1` or `--rounds=2` (reject any other value). `--rounds` is **review-only**: reject it (after parsing all flags, so flag order does not matter) if the final `selected_workflow` is not `review-and-implement`.\n   - **User-supplied base branch**: track a `user_supplied_base_branch` boolean that defaults to `false`. If the user passed `--base-branch <branch>` or `--base-branch=<branch>`, set the boolean to `true` and capture the value. A user-supplied `--base-branch` value **takes precedence** over any value resolved from Bridge API config in Stage 2. Validate the user-supplied value before proceeding: after trimming surrounding whitespace it must be non-empty, at most 255 characters, must not start with `-`, and must not contain ASCII control characters (`0x00`\u2013`0x1F` or `0x7F`); reject any malformed value with a clear error.\n   - **User branch overrides**: collect any user-supplied repeatable `--branch KEY=BRANCH` flags. A user-provided override always takes precedence over Stage 2 enrichment for that key.\n   - Reject malformed input before proceeding: if a token looks like a flag but is not one of the supported flags, or a ticket key does not match `[A-Z]+-[0-9]+`, or a `--branch` value is not `KEY=BRANCH`, or `--agent` names an agent other than `claude`/`cursor-agent`, or `--workflow` names anything other than `implement`/`review-and-implement`, or `--rounds` is used outside `review-and-implement` or names anything other than `1`/`2`, or `--base-branch` fails the validation rules above, stop and report the malformed argument.\n\n2. **Connectivity check**: Call the `ping` MCP tool (no parameters). If the ping fails or does not return `"status": "ok"`, stop immediately and display:\n\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor\'s MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Acknowledge CLI Pre-flight\n\nThe packaged CLI runs its own per-platform pre-flight checks and then fetches `origin` and fast-forwards the local **configured base branch** (the value resolved in Stage 2 below, or `main` when none is configured) from `origin/<base>` so the new worktrees are based on an up-to-date base. The historical flag `--no-refresh-main` still controls this behavior \u2014 the flag name is preserved for backward compatibility, but it now skips refresh of whatever base branch resolves (default `main`). The required commands depend on the OS:\n\n- **macOS**: `wt`, `git`, `osascript`.\n- **Windows**: `git-wt`, `git`, Git for Windows / Git Bash (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash), and Windows Terminal **or** PowerShell.\n- **Linux**: `wt`, `git`, `tmux`.\n\nOn **Windows** the Worktrunk binary is `git-wt` (its winget alias), which is a different tool from Windows Terminal\'s `wt.exe`: the CLI uses `git-wt` to **create worktrees** and `wt.exe` to **open a tab**, and never conflates the two. On **Linux** the CLI opens one detached `tmux` session per ticket (a window is added if that ticket\'s session already exists); attach later with `tmux attach -t <session>`. An unsupported OS (not macOS/Windows/Linux) fails fast with a clear "unsupported platform" message.\n\nThis stage simply notes that the CLI will fail fast if any prerequisite is missing or if local `main` has diverged from `origin/main` \u2014 you do not need to verify anything separately here, and you must not run any pre-flight commands yourself. When the CLI\'s pre-flight fails it now hints the user to run the read-only diagnostics command `npx -y @bridge_gpt/mcp-server doctor`, which reports found/missing for every prerequisite on the current OS \u2014 the pre-flight set plus `uv` plus the selected agent\'s command \u2014 and prints the manual install command for each missing one. `doctor` is strictly read-only and never installs anything; never run install commands automatically on the user\'s behalf. The CLI does not call any Bridge API tools; all credential-bearing work (branch enrichment in Stage 2) stays in this command. Proceed to Stage 2.\n\nThe packaged CLI also performs **secret-free Bridge API MCP provisioning** inside each created worktree: synchronously after the worktree is created and **before the agent tab/session is opened**, it writes both `.mcp.json` (Claude Code) and `.cursor/mcp.json` (Cursor) pointing at the `mcp-invoke` shim. These registrations are **secret-free** \u2014 they contain no `env` block and no API key, because the shim resolves credentials at runtime. If a spawned agent (or difficulty\u2192model routing) reports missing Bridge API credentials, fix it by rerunning `/install-bridge` (its final stage persists the routing credential), by running `npx -y @bridge_gpt/mcp-server credentials migrate-agent-config --write-credentials` to migrate a key that lives only in `.mcp.json` / `.cursor/mcp.json`, or by adding a `bapi:<repo>` entry to the user-scoped credentials file (`~/.config/bridge/credentials.json`) \u2014 never by putting `BAPI_API_KEY` into the worktree `.mcp.json` or `.cursor/mcp.json` (that env is invisible to the Bash-spawned CLI).\n\nThis stage is **critical** in the sense that the CLI will abort if its pre-flight fails; you will see the error in Stage 3\'s output and must surface it.\n\n## Stage 2 \u2014 Resolve Base Branch + Enrich Branch Names (best-effort)\n\n### Stage 2a \u2014 Resolve configured `base_branch`\n\nThe CLI must be told which branch to cut new worktrees from. Resolution order:\n\n1. If `user_supplied_base_branch` from Stage 0 is `true`, **skip the config-field lookup entirely** and use the user-supplied value. The user\'s explicit `--base-branch` always wins; never call `config_field` for `base_branch` in that case.\n2. Otherwise, call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to `base_branch` (do not pass any other parameters; the tool resolves the repository from the MCP server\'s configured `BAPI_REPO_NAME`).\n3. Parse the response. Treat the result as the **configured base branch** only when the response is a JSON object whose `value` field is a non-empty string after trimming surrounding whitespace.\n4. Treat **all** of the following as "unset" \u2014 emit a single-line warning like `Warning: base_branch is unset; CLI will default to main` and **omit** the `--base-branch` flag entirely from the Stage 3 command (the CLI\'s own default is `main`):\n   - `value` is `null`.\n   - `value` is an empty string or a whitespace-only string.\n   - The endpoint returns HTTP `400` (invalid field \u2014 happens before the registry includes `base_branch`).\n   - The tool returns a network error, timeout, or non-JSON parse failure.\n   - Any other lookup failure.\n5. When the configured value is usable, capture it in a `resolved_base_branch` variable. **Do not** stop the pipeline on a lookup failure; fall through to the CLI default.\n\nWhen forwarding `resolved_base_branch` into the Bash invocation in Stage 3, **shell-escape it safely**: replace every literal single quote `\'` in the value with the four-character sequence `\'\\\'\'`, then wrap the entire resulting string in single quotes (so the final argument looks like `\'<escaped-value>\'`). This is the standard POSIX single-quote escaping rule and is **mandatory** because `base_branch` is admin-configurable data that gets interpolated into a Bash command string; any unescaped single quote would otherwise break out of the surrounding quotes. Pass `--base-branch \'<escaped-value>\'` to the CLI as a single argv element \u2014 never expand the value unquoted into the command line.\n\n### Stage 2b \u2014 Enrich Branch Names\n\nBranch enrichment happens here, in the command, **before** invoking the CLI \u2014 the `get_ticket` MCP tool runs inside the MCP server process, which holds the Bridge API credentials the shell-spawned CLI does not have. For each parsed ticket key that does **not** already have a user-provided `--branch` override:\n\n1. Call the `get_ticket` MCP tool with `ticket_number` set to the key and `save_locally` set to `false`.\n2. From the response, extract the `summary` field. Slugify it: lowercase the string, replace every run of non-alphanumeric characters (`[^a-z0-9]+`) with a single dash `-`, trim leading and trailing dashes, and truncate to at most `40` characters (cutting at a dash boundary if possible).\n3. The enriched branch name is `feature/<KEY>-<slug>`. Example: `BAPI-248` with summary `"Add PR rating pre-evaluation step"` becomes `feature/BAPI-248-add-pr-rating-pre-evaluation-step` (trimmed at 40 chars).\n4. If the `get_ticket` call fails for a particular key (404, network error, missing summary) or produces an empty slug, emit a single-line warning like `Warning: could not enrich BAPI-248, falling back to feature/BAPI-248` and let the CLI apply its default `feature/<KEY>` for that key only. Do NOT stop the pipeline.\n5. Build a list of `--branch <KEY>=<BRANCH>` arguments \u2014 one entry per key whose enrichment succeeded \u2014 and merge it with any user-provided overrides from Stage 0. **Do not** call `get_ticket` for keys that already have a user-provided override; those overrides win.\n\nThis stage is **non-critical** \u2014 warnings are acceptable, the pipeline continues with the fallback default for any key that fails. Do not call the Bridge API from the CLI itself; the CLI never has credentials.\n\n## Stage 3 \u2014 Invoke the Packaged CLI\n\nUse the **Bash tool** to invoke the packaged CLI. Build the command line as:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets <pass-through-flags> <base-branch-flag> <branch-overrides> <ticket-keys>\n```\n\nWhere:\n- `<pass-through-flags>` are the supported flags collected in Stage 0 (`--agent`, `--terminal`, `--dry-run`, `--auto`, `--no-refresh-main`, `--max-parallel`), forwarded verbatim. Forward `--agent <name>` only if the user supplied it; otherwise omit it and the CLI defaults to `claude`. Forward `--auto` only if the user supplied it.\n- Forward `--workflow <selected_workflow>` only when the user explicitly passed `--workflow`; otherwise omit it and the CLI defaults to `implement`. Forward the normalized `--rounds=<n>` from Stage 0 only when the user supplied it (which Stage 0 already guarantees is only possible under `review-and-implement`).\n- `<base-branch-flag>` is `--base-branch \'<escaped-value>\'` (single-quoted using the Stage 2a escaping rule) **only when** the user supplied `--base-branch` in Stage 0 **or** Stage 2a\'s `config_field` lookup returned a non-empty configured value. When the configured value is unset / lookup fails / user did not supply one, **omit this flag entirely** so the CLI\'s own default (`main`) takes effect.\n- `<branch-overrides>` is the list of `--branch KEY=BRANCH` flags assembled in Stage 2 (enrichment results merged with user overrides; omit any key whose enrichment failed and had no user override).\n- `<ticket-keys>` is the original list of ticket keys parsed in Stage 0, space-separated and in the original order.\n\nExample for two tickets after successful enrichment, throttled to 2 concurrent worktrees:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets \\\n  --max-parallel 2 \\\n  --branch BAPI-248=feature/BAPI-248-add-pr-rating-pre-evaluation-step \\\n  --branch BAPI-250=feature/BAPI-250-deep-research-durability \\\n  BAPI-248 BAPI-250\n```\n\nExample launching Cursor Agent instead of the default Claude Code:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248\n```\n\nExample cutting worktrees from a non-`main` base (either user-supplied via `--base-branch develop` in Stage 0 or resolved from Bridge API config in Stage 2a):\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --base-branch develop BAPI-248\n```\n\nExample using the lower-level review-and-implement workflow directly (the `/review-and-start` command is the recommended front door for this; this form is documented here as the advanced launcher seam it drives):\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --workflow review-and-implement --auto --rounds=2 BAPI-248\n```\n\nPass through the CLI\'s stdout and stderr to the user verbatim. If the CLI exits non-zero, treat that as a critical failure: report the exit code and the CLI\'s error output, and stop.\n\nThis stage is **critical** \u2014 propagate any non-zero exit from the packaged CLI.\n\n## Stage 4 \u2014 Final Report\n\nOnce the CLI exits 0, parse its `Summary` section (one stable line per ticket in the form `KEY  branch=BRANCH  status=STATUS`, with an optional trailing `path=PATH`) and reformat it as a markdown table:\n\n```\n| Ticket   | Branch                                              | Status   |\n|----------|-----------------------------------------------------|----------|\n| BAPI-248 | feature/BAPI-248-add-pr-rating-pre-evaluation-step  | spawned  |\n| BAPI-250 | feature/BAPI-250-deep-research-durability           | spawned  |\n```\n\nStatus values are `dry-run`, `spawned`, `create-failed`, and `spawn-failed`. This table (and the report as a whole) describes **worktree/spawn status only** \u2014 it must never claim that review or implementation itself has completed; that work happens later, independently, inside each spawned session.\n\nCompute `spawned_command` from `selected_workflow`: `/implement-ticket <KEY>` when `implement` (the default), or `/review-and-implement <KEY>` when `review-and-implement`. Append `--auto` when the user passed it, and (workflow `review-and-implement` only) append the normalized `--rounds=<n>` when the user supplied `--rounds`. End the report with the worktree-first explanation, rendered for the tracked `selected_agent` and `spawned_command`. When `selected_agent` is `claude` (the default):\n\n```\nThe CLI created/switched each Worktrunk worktree first (throttled by --max-parallel),\nthen opened one tab/session per successful worktree (macOS Terminal/iTerm tab, Windows\nTerminal tab or PowerShell window, or Linux tmux session). Each one runs\n`claude \'<spawned_command>\'` inside its already-created worktree, which launches\nClaude Code with the starter prompt as its first message. Switch to each tab \u2014 or on\nLinux run `tmux attach -t <session>` \u2014 to monitor.\n```\n\nWhen `selected_agent` is `cursor-agent`, render the same explanation but with the Cursor handoff \u2014 do **not** claim it launches Claude Code:\n\n```\nThe CLI created/switched each Worktrunk worktree first (throttled by --max-parallel),\nthen opened one tab/session per successful worktree (macOS Terminal/iTerm tab, Windows\nTerminal tab or PowerShell window, or Linux tmux session). Each one runs\n`cursor-agent \'<spawned_command>\'` inside its already-created worktree, which\nlaunches Cursor Agent with the starter prompt as its first message. Switch to each\ntab \u2014 or on Linux run `tmux attach -t <session>` \u2014 to monitor.\n```\n\nThe spawned command is identical for both agents; only the launched agent binary differs. Under `review-and-implement`, each spawned session independently runs `/review-ticket`, pauses at its own per-ticket halt gate (unless chain-level `--auto` was passed), and only then runs `/implement-ticket` \u2014 do not report that review or implementation succeeded from this parent session.\n\nIf the CLI reported any `create-failed` or `spawn-failed` statuses, or Stage 2 emitted any enrichment warnings, list them under a `Warnings:` heading at the bottom of the report. If there were none, omit that section.\n\nSee `docs/claude/parallel-worktrees.md` for the deep-dive runbook and the Worktrunk verification result behind this worktree-first model.\n\n## Difficulty-Based Implementation-Model Routing\n\nBefore launching the interactive agent for each ticket, the packaged CLI selects an\nimplementation **model tier** from the ticket\'s `difficulty` rating (1-10) and injects\nit as a `--model` flag at the agent spawn boundary. This happens entirely inside the\nCLI \u2014 it is **not** part of the server-side `/implement-ticket` recipe, because the\nmodel an interactive agent session uses is fixed at the moment the process is launched.\n\n- **Tier ladder (fixed):** `difficulty 1-2 \u2192 cheap`, `3-5 \u2192 basic`, `6+ \u2192 premium`.\n- **Separation of concerns:** the Python backend returns only the coarse tier\n  (`cheap`/`basic`/`premium`) via `GET /jira/tickets/{KEY}/model-tier`; difficulty is\n  computed on demand and cached when absent. The TypeScript CLI alone maps a tier to\n  the agent-specific model alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`:\n  version-suffixed strings validated against `cursor-agent --list-models`).\n- **Per-repo config:**\n  - `difficulty_model_routing_enabled` \u2014 boolean, **default ON**. Set to `false` to\n    disable routing for a repo (the CLI then omits `--model`).\n  - `difficulty_model_tier_overrides` \u2014 a JSON object mapping a tier name to a model\n    alias (e.g. `{"premium": "opus"}`), **not** raw CLI arguments. Only `cheap`,\n    `basic`, and `premium` keys are accepted; aliases must match `^[A-Za-z0-9._:-]+$`.\n- **Fail-open:** routing never aborts a spawn. Credential, network, config, or\n  no-tier routing failures **assume a hard ticket and default to the premium/Opus\n  tier** when the selected agent supports a valid premium alias; routing being\n  disabled (`difficulty_model_routing_enabled = false`) or an agent that does not\n  support `--model` instead omit `--model` so the agent runs on its own default\n  model. Each degraded case is surfaced as exactly one secret-free, per-ticket\n  routing-diagnostic line, never a hard failure.\n\n### Model routing credential\n\nDifficulty\u2192model routing needs Bridge API credentials, and the shell-spawned\n`start-tickets` CLI is a **different runtime surface** from the MCP server: a\n`BAPI_API_KEY` that lives only in `.mcp.json` / `.cursor/mcp.json` is visible to\nthe MCP server but **not** to the Bash-spawned CLI, so routing silently degrades.\nThe durable source of truth both runtimes can resolve is the user-scoped store\n`~/.config/bridge/credentials.json`, keyed `bapi:<repo>`. If a routing-diagnostic\nline reports the credential is missing (e.g. difficulty resolves as `?`), fix it\nby any one of:\n\n1. Rerun `/install-bridge` \u2014 its final stage now persists the validated routing\n   credential into `~/.config/bridge/credentials.json` via the\n   `persist_routing_credential` tool.\n2. Migrate a key that lives **only** in `.mcp.json` / `.cursor/mcp.json` into the\n   user-scoped store with the consent-gated, one-shot command:\n\n   ```\n   npx -y @bridge_gpt/mcp-server credentials migrate-agent-config --write-credentials\n   ```\n\n3. Manually add `BAPI_API_KEY` under the `bapi:<repo>` target in the user-scoped\n   store `~/.config/bridge/credentials.json`.\n\nNever put `BAPI_API_KEY` into a worktree `.mcp.json` / `.cursor/mcp.json` as a fix \u2014\nthat env is invisible to the spawned CLI.\n\n## Conductor observability (opt-in via `--conductor`, BAPI-394)\n\nConductor is **opt-in**. By default `start-tickets` spawns the plain\n`cd <worktree> && <agent> \'/implement-ticket <KEY> [--auto]\'` \u2014 no\n`BAPI_CONDUCTOR_*` env, no supervisor window, and no message-relay instruction.\nPass `--conductor` (e.g. `/start-tickets --conductor BAPI-123`) to enable the\nConductor system below.\n\nWith `--conductor`, a run mints a single conductor `run_id` and attributes each\nworker\'s lifecycle events by `worker_id`, ticket key, and worktree path, and a\nsupervisor peer tab is opened. When the selected agent is **Claude Code**, the CLI\ninjects a conductor lifecycle hook into each created worktree\'s\n`.claude/settings.local.json` so the spawned session emits local `run.started` /\n`run.stopped` / `agent.notification` (and, when\n`BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE=1`, `tool.intent`) events into the local\nconductor ledger. These hooks apply **only** when the selected agent is Claude\nCode; other agents (e.g. `cursor-agent`) still participate in the run-level\n`run.started` event but receive no per-worktree Claude hook. Inspect the ledger\nwith the `conductor` CLI (e.g. `conductor doctor`). Conductor observability is\nbest-effort and never blocks or aborts a spawn.\n\nAlso under `--conductor`, each worker is launched with an explicit instruction to\ncall the `check_messages` MCP tool at checkpoints, so the supervisor can pass it\ntyped guidance mid-run (BAPI-397). Delivery is **cooperative** \u2014 the worker polls\nand acknowledges messages and they are never injected into a running session.\n(Epic-tick dispatch always runs with conductor enabled, independent of this\nuser-facing flag.)\n',
   "teach-bridge.md": 'Update a Bridge API configuration field via a natural-language teaching.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command takes a natural-language teaching (e.g., "use data-testid selectors in Playwright tests") and updates the appropriate Bridge API configuration field. The teaching is auto-classified to the correct field, merged with existing content as actionable AI instructions, and uploaded after user confirmation.\n\n`$ARGUMENTS` is required \u2014 it is the teaching text. If `$ARGUMENTS` is empty, show:\n\n```\nUsage: /teach-bridge <teaching>\n\nExamples:\n  /teach-bridge use data-testid selectors in Playwright tests\n  /teach-bridge always validate input DTOs with Pydantic before passing to service layer\n  /teach-bridge prefer composition over inheritance for service classes\n```\n\nIf any stage fails, stop immediately and report which stage failed and why.\n\n## Stage 0 \u2014 Preflight\n\n1. **Validate arguments**: If `$ARGUMENTS` is empty or contains only whitespace, display the usage instructions above and stop.\n\n2. **Admin check**: Call the `get_my_role` MCP tool (no parameters). Inspect the response:\n   - If `role` is `"admin"` OR `source` is `"legacy"`: proceed normally.\n   - Otherwise: stop immediately and display:\n     ```\n     Admin access required. Your API key has role "<role>" (source: <source>).\n     Only admin keys and legacy shared keys can update configuration fields.\n     Contact your project administrator to request admin access.\n     ```\n\nIf this stage fails, stop immediately and report the error. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Classify\n\n1. **List available fields**: Call the `config_field` MCP tool with `operation` set to `"list"` (no other parameters). This returns all available configuration field names with descriptions.\n\n2. **Evaluate the teaching**: Compare the user\'s teaching (`$ARGUMENTS`) against each field\'s description to determine which field it applies to.\n\n3. **Handle classification outcomes**:\n   - **Clear single match**: If one field is clearly the best target, proceed to Stage 2 with that field.\n   - **Multiple plausible matches**: If 2-3 fields are equally plausible, present them to the user with their descriptions and ask which one to update. Wait for user input before proceeding.\n   - **No confident match**: If you cannot confidently map the teaching to any field, ask the user to elaborate or specify which field they intend. Wait for user input before proceeding.\n\n## Stage 2 \u2014 Merge\n\n1. **Read current value**: Call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to the selected field from Stage 1. Capture the current value, description, and examples from the response.\n\n2. **Draft the update**:\n   - **If the field is currently null or empty**: Compose initial content from the teaching. Rephrase the user\'s input as imperative, agent-facing instructions (e.g., convert "I want you to use data-testid" to "Always use `data-testid` attributes for Playwright element locators"). Do not use the user\'s exact conversational text.\n   - **If the field has existing content**: Merge the teaching into the existing value at the most appropriate location. Rephrase as imperative, agent-facing instructions. Preserve the existing structure and formatting.\n\n3. **Handle contradictions**: If the teaching contradicts existing instructions in the field, present both the existing instruction and the new teaching side-by-side and ask the user which should take precedence. Wait for user input before proceeding.\n\n## Stage 3 \u2014 Confirm and Upload\n\n1. **Show the proposed update**: Display to the user:\n   - **Field**: The name of the field being updated\n   - **Change summary**: A brief description of what was added or changed\n   - **Full proposed value**: The complete new value for the field (not just the diff)\n\n2. **Wait for confirmation**: Ask the user to confirm, request edits, or abort.\n\n3. **On confirmation**: Call the `config_field` MCP tool with:\n   - `operation`: `"update"`\n   - `field_name`: the selected field name\n   - `value`: the full merged value (pass inline, do not use `file_path`)\n\n   Display a success message confirming the update.\n\n4. **On rejection**: Ask the user what they\'d like to change. If they provide edits, revise the proposed value and show it again. If they abort, stop without making any changes.\n',
   "upgrade-bridge.md": "# Upgrade Bridge\n\n$ARGUMENTS\n\nUse this command to upgrade (or update) the Bridge API MCP \u2014 the\n`@bridge_gpt/mcp-server` package, also called the bridge-api MCP \u2014 to the latest\npublished version. This is the action behind the ping tool's advice to \"tell\nyour local agent 'upgrade bridge'\".\n\n---\n\n# Instructions\n\nRun the existing packaged upgrade flow. Do not edit files, install anything by\nhand, or invent a new subcommand \u2014 just drive the upgrade CLI and report what it\ndid.\n\n## Step 1 \u2014 Run the upgrade command\n\nFrom the **project root**, run exactly:\n\n```\nnpx -y @bridge_gpt/mcp-server --upgrade\n```\n\nThis upgrades/updates the installed `@bridge_gpt/mcp-server` (the bridge-api MCP)\nand re-scaffolds the slash commands.\n\n## Step 2 \u2014 Report the result\n\n- If the CLI reports a version change, report it in the CLI's\n  `oldVersion -> newVersion` form (e.g. `0.1.17 -> 0.1.19`), mirroring the\n  `runUpgradeCli` output.\n- If the CLI reports that no upgrade was needed (the installed version is already\n  the latest), report `Already up-to-date.` exactly.\n\n## Step 3 \u2014 Handle failures\n\nIf the command fails (non-zero exit or an error in its output), **stop** and\nreport the CLI error verbatim. Do not retry blindly or attempt manual edits to\nwork around it.\n\n## Final Report\n\nReport whether the bridge-api MCP was upgraded (with the\n`oldVersion -> newVersion` transition), was already current (`Already up-to-date.`),\nor failed (with the CLI error).\n"
 };
@@ -15534,11 +16175,11 @@ init_version_generated();
 import { readFile as readFile6, stat as stat4 } from "fs/promises";
 import { spawn } from "child_process";
 import os5 from "os";
-import path16 from "path";
+import path17 from "path";
 
 // src/install-doctor.ts
 init_credential_store();
-import path15 from "path";
+import path16 from "path";
 var DEFAULT_BASE_URL = "https://bridgegpt-api.com";
 var MCP_CONFIG_ENV_TARGETS = [
   { relPath: ".mcp.json", topLevelKey: "mcpServers" },
@@ -15556,7 +16197,7 @@ async function resolveInstallDoctorTarget(deps) {
     for (const { relPath, topLevelKey } of MCP_CONFIG_ENV_TARGETS) {
       let raw;
       try {
-        raw = await deps.readFile(path15.join(deps.cwd, relPath));
+        raw = await deps.readFile(path16.join(deps.cwd, relPath));
       } catch {
         continue;
       }
@@ -16031,7 +16672,7 @@ function probeNpxNoInstallDefault(spec) {
 async function inspectLauncherCache(deps) {
   const inspections = [];
   for (const { relPath, topLevelKey } of LAUNCHER_CONFIG_TARGETS) {
-    const fullPath = path16.join(deps.cwd, relPath);
+    const fullPath = path17.join(deps.cwd, relPath);
     let raw;
     try {
       raw = await deps.readFile(fullPath);
@@ -16208,7 +16849,7 @@ init_credential_store();
 init_third_party_mcp_targets();
 import { spawn as spawn2, execFile as execFile3 } from "child_process";
 import { stat as stat5, readFile as readFile7 } from "fs/promises";
-import path19 from "path";
+import path20 from "path";
 import os6 from "os";
 function getMcpInvokeUsage() {
   return [
@@ -16283,7 +16924,7 @@ function parseMcpInvokeArgs(argv) {
   if (projectRoot === void 0) {
     return { status: "error", message: "Missing required --project-root flag" };
   }
-  if (!path19.isAbsolute(projectRoot)) {
+  if (!path20.isAbsolute(projectRoot)) {
     return { status: "error", message: "--project-root must be an absolute path" };
   }
   return { status: "ok", target: targetValidation.value, projectRoot };
@@ -16832,8 +17473,8 @@ function createDefaultExecutorDeps() {
     mkdir: (dirPath, opts) => mkdir5(dirPath, opts),
     stat: (filePath) => stat6(filePath).then((s) => ({ mode: s.mode })),
     statMtimeMs: (filePath) => stat6(filePath).then((s) => s.mtimeMs).catch(() => null),
-    statfs: async (path33) => {
-      const s = await statfs(path33);
+    statfs: async (path34) => {
+      const s = await statfs(path34);
       return { bavail: Number(s.bavail), bsize: Number(s.bsize) };
     },
     sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)),
@@ -17153,6 +17794,7 @@ function buildClaimManifest(report, options, freeSlots) {
 import os9 from "node:os";
 
 // src/executor/env.ts
+init_pr_base_contract();
 var ALLOWED_ENV_KEYS = [
   "PATH",
   "HOME",
@@ -17186,7 +17828,7 @@ function isExecutorEnvKeyAllowed(key) {
   if (SECRET_NAME_FRAGMENTS.some((fragment) => upper.includes(fragment))) return false;
   return true;
 }
-function buildExecutorWorkerEnv(parentEnv) {
+function buildExecutorWorkerEnv(parentEnv, effectiveBaseBranch) {
   const env = {};
   for (const key of ALLOWED_ENV_KEYS) {
     if (!isExecutorEnvKeyAllowed(key)) continue;
@@ -17196,6 +17838,9 @@ function buildExecutorWorkerEnv(parentEnv) {
     }
   }
   env.BRIDGE_SKIP_PREPUSH = "1";
+  if (typeof effectiveBaseBranch === "string" && effectiveBaseBranch.length > 0) {
+    env[PR_BASE_BRANCH_ENV_VAR] = effectiveBaseBranch;
+  }
   return env;
 }
 
@@ -17303,6 +17948,7 @@ var MissingVerdictArtifact = "MissingVerdictArtifact";
 var WorktreeLostBeforePush = "WorktreeLostBeforePush";
 var BranchMismatch = "BranchMismatch";
 var WorkerFinalizationMissingRemoteBranchAndPr = "WorkerFinalizationMissingRemoteBranchAndPr";
+var WorkerFinalizationPrBaseMismatch = "WorkerFinalizationPrBaseMismatch";
 var ERROR_MESSAGE_MAX_CHARS = 300;
 var ExecutorNamedError = class extends Error {
   errorKind;
@@ -17632,9 +18278,9 @@ async function provisionExecutorDenyLayer(worktreePath, options, deps) {
 init_worktree_core();
 
 // src/executor/worktree-inspection.ts
-import path20 from "node:path";
+import path21 from "node:path";
 function pathApiForExecutorPlatform(platform) {
-  return platform === "win32" ? path20.win32 : path20.posix;
+  return platform === "win32" ? path21.win32 : path21.posix;
 }
 function parseGitWorktreePorcelain(porcelain) {
   const entries = [];
@@ -17997,7 +18643,7 @@ ${userPrompt}`;
 }
 
 // src/executor/results.ts
-import path21 from "node:path";
+import path22 from "node:path";
 var SMOKE_EVIDENCE_MAX_BYTES = 8e3;
 var ARTIFACT_MAX_BYTES = 32e3;
 var SUMMARY_MAX_CHARS = 500;
@@ -18043,7 +18689,7 @@ function buildGenericSuccessResult(input) {
 }
 async function readCompletionArtifacts(worktreePath, deps) {
   if (!worktreePath) return void 0;
-  const critiquePath = path21.join(worktreePath, ".conductor", "critique.md");
+  const critiquePath = path22.join(worktreePath, ".conductor", "critique.md");
   let content;
   try {
     content = await deps.readFile(critiquePath);
@@ -18336,6 +18982,30 @@ function isImplementationStyleJobType(jobType) {
   return isSpawnJobType(jobType) && jobType !== "spec_review";
 }
 
+// src/executor/base-branch.ts
+init_base_ref();
+function resolveExecutorJobBaseBranch(job, fallbackBaseBranch) {
+  const payload = job.payload;
+  const raw = payload && typeof payload === "object" ? payload.base_branch : void 0;
+  if (raw === void 0) {
+    return { ok: true, baseBranch: fallbackBaseBranch };
+  }
+  if (typeof raw !== "string") {
+    return {
+      ok: false,
+      error: "job payload base_branch is present but is not a string branch name."
+    };
+  }
+  const validationError = validateBranchName(raw);
+  if (validationError) {
+    return {
+      ok: false,
+      error: `job payload base_branch is not a valid branch name: ${validationError}`
+    };
+  }
+  return { ok: true, baseBranch: raw };
+}
+
 // src/executor/worker-finalization.ts
 var DEFAULT_ORIGIN_FINALIZATION_ATTEMPTS = 3;
 var DEFAULT_ORIGIN_FINALIZATION_RETRY_DELAY_MS = 500;
@@ -18391,6 +19061,39 @@ async function resolveOriginBranchShaForFinalization(runCommand, worktreePath, b
   }
   return remoteSha;
 }
+async function resolvePrBaseRef(runCommand, worktreePath, branch) {
+  const args = ["pr", "view"];
+  if (branch) args.push(branch);
+  args.push("--json", "number,baseRefName");
+  let result;
+  try {
+    result = await runCommand("gh", args, { cwd: worktreePath });
+  } catch {
+    return { found: false, baseRef: null };
+  }
+  if (result.exitCode !== 0) return { found: false, baseRef: null };
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    return { found: false, baseRef: null };
+  }
+  if (!parsed || typeof parsed !== "object") return { found: false, baseRef: null };
+  const obj = parsed;
+  const prNumber = typeof obj.number === "number" ? obj.number : void 0;
+  const rawBase = obj.baseRefName;
+  const baseRef = typeof rawBase === "string" && rawBase.trim().length > 0 ? rawBase.trim() : null;
+  return { found: true, prNumber, baseRef };
+}
+function prBaseMismatchFailure(job, prNumber, expectedBase, actualBase) {
+  const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+  const prLabel = typeof prNumber === "number" ? `PR #${prNumber}` : "its PR";
+  return {
+    error_kind: WorkerFinalizationPrBaseMismatch,
+    error_message: `${label} opened ${prLabel} against base '${actualBase}', but the run base is '${expectedBase}'. A PR that does not target '${expectedBase}' never triggers code review and would strand the ticket. Recovery: rebuild the feature branch from a fresh origin/${expectedBase} and cherry-pick only this ticket's own commits, then force-push. Do NOT merely retarget the PR base in the GitHub UI \u2014 a branch built on a squash-merged dependency goes CONFLICTING when retargeted.`,
+    classification: "crashed"
+  };
+}
 function missingBranchAndPrFailure(job, detail) {
   const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
   return {
@@ -18404,6 +19107,25 @@ async function validateWorkerFinalization(input) {
   if (!isImplementationStyleJobType(job.job_type)) {
     return { ok: true };
   }
+  const expectedBase = typeof input.expectedBaseBranch === "string" ? input.expectedBaseBranch.trim() : "";
+  if (expectedBase) {
+    const branchForPr = typeof branch === "string" ? branch.trim() : "";
+    const prBase = await resolvePrBaseRef(runCommand, worktreePath, branchForPr);
+    if (prBase.found) {
+      if (prBase.baseRef === null) {
+        return {
+          ok: false,
+          failure: prBaseMismatchFailure(job, prBase.prNumber, expectedBase, "(unresolved)")
+        };
+      }
+      if (prBase.baseRef !== expectedBase) {
+        return {
+          ok: false,
+          failure: prBaseMismatchFailure(job, prBase.prNumber, expectedBase, prBase.baseRef)
+        };
+      }
+    }
+  }
   if (extractPrUrl(result)) {
     return { ok: true };
   }
@@ -18463,6 +19185,7 @@ async function validateWorkerFinalization(input) {
 }
 
 // src/executor/worktree.ts
+init_base_ref();
 init_start_tickets_prereqs();
 init_worktree_core();
 function resolveExecutorBranch(job) {
@@ -18515,13 +19238,22 @@ async function ensureExecutorWorktree(job, options, deps, policy = {}) {
     }
     return { ok: false, error: row2.error ?? `worktree creation failed for branch '${branch}'` };
   }
+  const resolvedBase = await fetchAndResolveBaseSha(deps, options.baseBranch);
+  if (!resolvedBase.ok) {
+    return {
+      ok: false,
+      error: `failed to resolve remote base '${options.baseBranch}' for a fresh worktree: ${resolvedBase.error}`
+    };
+  }
+  const baseSha = resolvedBase.base_sha;
   const row = await createWorktreeForTicket(
     toWorktreeCoreDeps(deps),
     key,
     { [key]: branch },
     options.worktrunkBinary,
-    baseStartPoint,
-    guardStaleWorktree
+    baseSha,
+    guardStaleWorktree,
+    { alignExistingBranchTo: baseSha, verifyHeadMatches: baseSha }
   );
   if (row.status === "created" && typeof row.path === "string") {
     return { ok: true, worktreePath: row.path, branch };
@@ -18529,6 +19261,9 @@ async function ensureExecutorWorktree(job, options, deps, policy = {}) {
   return { ok: false, error: row.error ?? `worktree creation failed for branch '${branch}'` };
 }
 
+// src/executor/job-runner.ts
+init_pr_base_contract();
+
 // src/executor/worker-command.ts
 init_agent_registry();
 function resolveExecutorModelAlias(payload) {
@@ -19013,9 +19748,21 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
   }
 }
 async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams) {
-  const prep = await prepareSpawn(job, httpClient, options, deps, seams);
+  const baseResolution = resolveExecutorJobBaseBranch(job, options.baseBranch);
+  if (!baseResolution.ok) {
+    await httpClient.fail(job, {
+      error_kind: "ContractError.BaseBranch",
+      error_message: baseResolution.error,
+      classification: "crashed"
+    });
+    return { status: "failed", reason: "base_branch_contract" };
+  }
+  const effectiveBaseBranch = baseResolution.baseBranch;
+  const jobOptions = { ...options, baseBranch: effectiveBaseBranch };
+  const prep = await prepareSpawn(job, httpClient, jobOptions, deps, seams);
   if (!prep.ok) return prep.result;
-  const { worktreePath, branch, prompt } = prep;
+  const { worktreePath, branch } = prep;
+  const prompt = isImplementationStyleJobType(job.job_type) ? `${prep.prompt} ${buildPrBaseContractLaunchInstruction()}` : prep.prompt;
   const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
   if (!timeout.ok) {
     await httpClient.fail(job, {
@@ -19027,7 +19774,7 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
   }
   const deny = await provisionExecutorDenyLayer(
     worktreePath,
-    { baseBranch: options.baseBranch },
+    { baseBranch: effectiveBaseBranch },
     {
       readFile: deps.readFile,
       writeFile: deps.writeFile,
@@ -19096,7 +19843,7 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
   };
   const alias = resolveExecutorModelAlias(job.payload);
   const argv = buildClaudeExecutorArgv(prompt, alias);
-  const env = buildExecutorWorkerEnv(deps.env);
+  const env = buildExecutorWorkerEnv(deps.env, effectiveBaseBranch);
   let proc;
   try {
     proc = deps.spawnProcess(CLAUDE_EXECUTABLE, argv, { cwd: worktreePath, env });
@@ -19115,11 +19862,11 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
     stdout: proc.stdout ? teeAsyncIterable(proc.stdout, tee, "stdout") : null,
     stderr: proc.stderr ? teeAsyncIterable(proc.stderr, tee, "stderr") : null
   } : proc;
-  const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, options.baseBranch);
+  const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, effectiveBaseBranch);
   const procResult = await superviseProcess({
     job,
     httpClient,
-    options,
+    options: jobOptions,
     deps,
     ownership,
     observation,
@@ -19191,7 +19938,8 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
       worktreePath,
       result,
       runCommand: deps.runCommand,
-      headSha: git.last_commit_sha
+      headSha: git.last_commit_sha,
+      expectedBaseBranch: effectiveBaseBranch
     });
     if (!finalization.ok) {
       await finalizeRegistry();
@@ -19668,25 +20416,452 @@ ${getExecutorUsage()}`);
       errorLog(`Error: ${access2.error}`);
       return 1;
     }
-    apiKeyByRepo[repo] = access2.apiKey;
-    baseUrl = access2.baseUrl;
+    apiKeyByRepo[repo] = access2.apiKey;
+    baseUrl = access2.baseUrl;
+  }
+  const createHttpClient = overrides.createHttpClient ?? createExecutorHttpClient;
+  const httpClient = createHttpClient({
+    baseUrl,
+    apiKey: apiKeyByRepo[options.repoName],
+    apiKeyByRepo,
+    mcpVersion: VERSION,
+    fetch: deps.fetch
+  });
+  const run = overrides.runExecutor ?? runExecutor;
+  try {
+    return await run(options, deps, httpClient);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    errorLog(`Error: executor exited unexpectedly: ${message.slice(0, 200)}`);
+    return 1;
+  }
+}
+
+// src/setup-epic.ts
+init_bridge_api_client();
+init_plan();
+import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import os12 from "node:os";
+function createDefaultSetupEpicDeps() {
+  return {
+    env: process.env,
+    cwd: process.cwd(),
+    platform: process.platform,
+    homedir: os12.homedir,
+    readFile: (p) => fsReadFile(p, "utf-8"),
+    stat: (p) => fsStat(p),
+    fetch: globalThis.fetch,
+    log: (m) => console.log(m),
+    errorLog: (m) => console.error(m)
+  };
+}
+function getSetupEpicUsage() {
+  return [
+    "Usage: mcp-server setup-epic --epic-key <KEY> --plan-file <path> [options]",
+    "",
+    "Bootstraps an Epic Conductor v2 run: creates the run, stores the plan DAG,",
+    "and approves it. Idempotent \u2014 re-running reuses an existing live run.",
+    "",
+    "Required:",
+    "  --epic-key <KEY>       Jira epic key (e.g. BAPI-405)",
+    "  --plan-file <path>     Path to epic-plan.dag.json (from decompose-epic)",
+    "",
+    "Options:",
+    "  --repo <name>          Repo name (default: BAPI_REPO_NAME or .bridge/config)",
+    "  --plan-version <n>     Assert the sidecar's plan_version equals <n>",
+    "  --dry-run              Validate and preview; make no mutating calls",
+    "  --json                 Emit a single JSON result object on stdout",
+    "  -h, --help             Show this help",
+    "",
+    "After setup, the server-side reconciler picks the run up within ~30s.",
+    "To execute claimed jobs on this machine, run:",
+    "  npx -y @bridge_gpt/mcp-server executor --repo <name>"
+  ].join("\n");
+}
+function takeValue2(argv, i, flag) {
+  const next = argv[i + 1];
+  if (next === void 0 || next.startsWith("-")) return null;
+  return next;
+}
+function parseSetupEpicArgs(argv) {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    return { status: "help", usage: getSetupEpicUsage() };
+  }
+  let epicKey;
+  let planFile;
+  let repo;
+  let planVersion;
+  let dryRun = false;
+  let json = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--epic-key": {
+        const v = takeValue2(argv, i, arg);
+        if (v === null) return { status: "error", message: "--epic-key requires a value." };
+        epicKey = v;
+        i++;
+        break;
+      }
+      case "--plan-file": {
+        const v = takeValue2(argv, i, arg);
+        if (v === null) return { status: "error", message: "--plan-file requires a value." };
+        planFile = v;
+        i++;
+        break;
+      }
+      case "--repo": {
+        const v = takeValue2(argv, i, arg);
+        if (v === null) return { status: "error", message: "--repo requires a value." };
+        repo = v;
+        i++;
+        break;
+      }
+      case "--plan-version": {
+        const v = takeValue2(argv, i, arg);
+        if (v === null) return { status: "error", message: "--plan-version requires a value." };
+        if (!/^\d+$/.test(v)) {
+          return { status: "error", message: `--plan-version must be a positive integer, got '${v}'.` };
+        }
+        planVersion = Number(v);
+        if (planVersion < 1) {
+          return { status: "error", message: "--plan-version must be >= 1." };
+        }
+        i++;
+        break;
+      }
+      case "--dry-run":
+        dryRun = true;
+        break;
+      case "--json":
+        json = true;
+        break;
+      default:
+        return {
+          status: "error",
+          message: `Unknown argument '${arg}'. Run "setup-epic --help" for usage.`
+        };
+    }
+  }
+  if (!epicKey) return { status: "error", message: "setup-epic requires --epic-key <KEY>." };
+  if (!planFile) return { status: "error", message: "setup-epic requires --plan-file <path>." };
+  return {
+    status: "ok",
+    options: { epicKey, planFile, repo, planVersion, dryRun, json }
+  };
+}
+function validateEpicPlanSidecar(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { ok: false, error: "Plan sidecar must be a JSON object." };
+  }
+  const plan = parsed;
+  const version = plan.plan_version;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    return {
+      ok: false,
+      error: `plan_version must be an integer >= 1, got ${JSON.stringify(version)}.`
+    };
+  }
+  if (!Array.isArray(plan.nodes) || plan.nodes.length === 0) {
+    return { ok: false, error: "plan.nodes must be a non-empty array." };
+  }
+  if (!Array.isArray(plan.edges)) {
+    return { ok: false, error: "plan.edges must be an array (use [] for none)." };
+  }
+  const keys = /* @__PURE__ */ new Set();
+  const warnings = [];
+  for (const node of plan.nodes) {
+    if (!node || typeof node !== "object") {
+      return { ok: false, error: "Every plan node must be an object." };
+    }
+    const key = typeof node.ticket_key === "string" ? node.ticket_key.trim() : "";
+    if (!key) return { ok: false, error: "Every plan node needs a non-empty ticket_key." };
+    if (keys.has(key)) return { ok: false, error: `Duplicate ticket_key in plan: ${key}.` };
+    keys.add(key);
+    if (node.touched_files === void 0) {
+      warnings.push(
+        `Node ${key} has no touched_files. File-overlap serialization cannot protect it; if the repo has that flag on, the server will reject this plan.`
+      );
+    }
+  }
+  const adjacency = /* @__PURE__ */ new Map();
+  const addEdge = (from, to) => {
+    const list = adjacency.get(from) ?? [];
+    list.push(to);
+    adjacency.set(from, list);
+  };
+  for (const node of plan.nodes) {
+    const deps = Array.isArray(node.depends_on) ? node.depends_on : [];
+    for (const dep of deps) {
+      if (!keys.has(dep)) {
+        return {
+          ok: false,
+          error: `Node ${node.ticket_key} depends_on unknown ticket '${dep}'.`
+        };
+      }
+      addEdge(dep, node.ticket_key);
+    }
+  }
+  for (const edge of plan.edges) {
+    if (!edge || typeof edge !== "object") {
+      return { ok: false, error: "Every plan edge must be an object." };
+    }
+    if (!keys.has(edge.from) || !keys.has(edge.to)) {
+      return {
+        ok: false,
+        error: `Edge ${JSON.stringify(edge.from)} -> ${JSON.stringify(edge.to)} references an unknown ticket.`
+      };
+    }
+    addEdge(edge.from, edge.to);
+  }
+  const cycle = findCycle(keys, adjacency);
+  if (cycle) {
+    return { ok: false, error: `Plan DAG has a cycle: ${cycle.join(" -> ")}.` };
+  }
+  return { ok: true, plan: parsed, warnings };
+}
+function findCycle(keys, adjacency) {
+  const WHITE = 0;
+  const GREY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  for (const k of keys) color.set(k, WHITE);
+  for (const start of keys) {
+    if (color.get(start) !== WHITE) continue;
+    const stack = [{ node: start, path: [start] }];
+    while (stack.length > 0) {
+      const { node, path: path34 } = stack[stack.length - 1];
+      if (color.get(node) === WHITE) {
+        color.set(node, GREY);
+        for (const next of adjacency.get(node) ?? []) {
+          if (color.get(next) === GREY) return [...path34, next];
+          if (color.get(next) === WHITE) {
+            stack.push({ node: next, path: [...path34, next] });
+          }
+        }
+      } else {
+        if (color.get(node) === GREY) color.set(node, BLACK);
+        stack.pop();
+      }
+    }
+  }
+  return null;
+}
+function errorDetail(err) {
+  if (err instanceof ConductorBridgeApiError) {
+    const status = err.status !== void 0 ? ` (HTTP ${err.status})` : "";
+    const preview = err.bodyPreview ? `: ${err.bodyPreview}` : "";
+    return `${err.message}${status}${preview}`;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+async function runSetupEpicCli(argv, overrides = {}) {
+  const deps = { ...createDefaultSetupEpicDeps(), ...overrides };
+  const parsed = parseSetupEpicArgs(argv);
+  if (parsed.status === "help") {
+    deps.log(parsed.usage);
+    return 0;
+  }
+  if (parsed.status === "error") {
+    deps.errorLog(parsed.message);
+    deps.errorLog("");
+    deps.errorLog(getSetupEpicUsage());
+    return 1;
+  }
+  const opts = parsed.options;
+  const say = opts.json ? deps.errorLog : deps.log;
+  let raw;
+  try {
+    raw = await deps.readFile(opts.planFile);
+  } catch (err) {
+    deps.errorLog(`Could not read plan file '${opts.planFile}': ${errorDetail(err)}`);
+    return 1;
+  }
+  let parsedJson;
+  try {
+    parsedJson = JSON.parse(raw);
+  } catch (err) {
+    deps.errorLog(`Plan file '${opts.planFile}' is not valid JSON: ${errorDetail(err)}`);
+    return 1;
+  }
+  const validation = validateEpicPlanSidecar(parsedJson);
+  if (!validation.ok) {
+    deps.errorLog(`Invalid plan DAG: ${validation.error}`);
+    return 1;
+  }
+  const plan = validation.plan;
+  const warnings = [...validation.warnings];
+  if (opts.planVersion !== void 0 && opts.planVersion !== plan.plan_version) {
+    deps.errorLog(
+      `--plan-version ${opts.planVersion} does not match the sidecar's plan_version ${plan.plan_version}. Fix the sidecar (or drop the flag) \u2014 setup-epic never rewrites the blob, because that would change its hash.`
+    );
+    return 1;
+  }
+  const localHash = hashPlan(plan);
+  const accessResult = await resolveConductorBridgeApiAccess({
+    env: deps.env,
+    cwd: deps.cwd,
+    homedir: deps.homedir,
+    platform: deps.platform,
+    readFile: deps.readFile,
+    stat: deps.stat,
+    repoName: opts.repo
+  });
+  if (!accessResult.ok) {
+    deps.errorLog(`Cannot reach the Bridge API: ${accessResult.error}`);
+    return 1;
+  }
+  const access2 = accessResult.access;
+  say(`Epic:       ${opts.epicKey}`);
+  say(`Repo:       ${access2.repoName}`);
+  say(`Plan:       v${plan.plan_version}, ${plan.nodes.length} node(s), ${plan.edges.length} edge(s)`);
+  say(`Local hash: ${localHash}`);
+  for (const w of warnings) say(`  [warn] ${w}`);
+  let existingRunId = null;
+  let existingStatus = null;
+  try {
+    const state = await fetchEpicRunState(access2, opts.epicKey, deps.fetch);
+    existingRunId = state.epic_run?.epic_run_id ?? null;
+    existingStatus = state.epic_run?.status ?? null;
+  } catch (err) {
+    if (err instanceof ConductorBridgeApiError && err.status === 404) {
+      existingRunId = null;
+    } else if (err instanceof ConductorBridgeApiError && err.status === 409) {
+      deps.errorLog(
+        `Epic ${opts.epicKey} has MULTIPLE active runs \u2014 it is wedged, and every plan call will keep failing. Abandon the duplicate before retrying:
+  PATCH /jira/epic-runs/runs/<epic_run_id> {"status": "abandoned"}
+Detail: ${errorDetail(err)}`
+      );
+      return 1;
+    } else {
+      deps.errorLog(
+        `Could not read the epic run state, so creating one would risk a duplicate (which wedges the epic permanently). Refusing to continue.
+Detail: ${errorDetail(err)}`
+      );
+      return 1;
+    }
+  }
+  if (opts.dryRun) {
+    say("");
+    say("[dry-run] No changes made. Would:");
+    if (existingRunId) {
+      say(`  - reuse existing run ${existingRunId} (status: ${existingStatus})`);
+    } else {
+      say(`  - POST /jira/epic-runs/runs  (create run for ${opts.epicKey})`);
+    }
+    say(`  - POST /jira/epic-runs/runs/${opts.epicKey}/plan          (v${plan.plan_version})`);
+    say(`  - POST /jira/epic-runs/runs/${opts.epicKey}/approve-plan  (v${plan.plan_version})`);
+    if (opts.json) {
+      deps.log(
+        JSON.stringify(
+          {
+            dry_run: true,
+            epic_key: opts.epicKey,
+            repo_name: access2.repoName,
+            plan_version: plan.plan_version,
+            local_plan_hash: localHash,
+            existing_run_id: existingRunId,
+            warnings
+          },
+          null,
+          2
+        )
+      );
+    }
+    return 0;
+  }
+  const result = {
+    epic_run_id: existingRunId ?? "",
+    epic_key: opts.epicKey,
+    repo_name: access2.repoName,
+    plan_version: plan.plan_version,
+    plan_hash: null,
+    local_plan_hash: localHash,
+    status: existingStatus,
+    run_created: false,
+    plan_stored: false,
+    plan_approved: false,
+    warnings
+  };
+  if (existingRunId) {
+    say(`Run:        reusing ${existingRunId} (status: ${existingStatus})`);
+  } else {
+    try {
+      const run = await createEpicRun(access2, { epicKey: opts.epicKey }, deps.fetch);
+      result.epic_run_id = run.epic_run_id;
+      result.status = run.status;
+      result.run_created = true;
+      say(`Run:        created ${run.epic_run_id}`);
+    } catch (err) {
+      deps.errorLog(`Failed to create the epic run: ${errorDetail(err)}`);
+      return 1;
+    }
+  }
+  try {
+    const stored = await storeEpicPlan(
+      access2,
+      {
+        epicKey: opts.epicKey,
+        planVersion: plan.plan_version,
+        planBlob: plan,
+        planHash: localHash
+      },
+      deps.fetch
+    );
+    result.plan_stored = true;
+    const serverHash = stored?.plan_hash;
+    if (typeof serverHash === "string") result.plan_hash = serverHash;
+    say(`Plan:       stored v${plan.plan_version}`);
+  } catch (err) {
+    if (err instanceof ConductorBridgeApiError && err.status === 409) {
+      deps.errorLog(
+        `Plan v${plan.plan_version} is already stored with a DIFFERENT hash. The stored blob is immutable \u2014 bump plan_version in the sidecar and re-run.
+Detail: ${errorDetail(err)}`
+      );
+      return 1;
+    }
+    deps.errorLog(`Failed to store the plan: ${errorDetail(err)}`);
+    return 1;
   }
-  const createHttpClient = overrides.createHttpClient ?? createExecutorHttpClient;
-  const httpClient = createHttpClient({
-    baseUrl,
-    apiKey: apiKeyByRepo[options.repoName],
-    apiKeyByRepo,
-    mcpVersion: VERSION,
-    fetch: deps.fetch
+  const approval = await approveEpicPlan(
+    access2,
+    { epicKey: opts.epicKey, planVersion: plan.plan_version },
+    deps.fetch
+  ).catch((err) => {
+    deps.errorLog(`Failed to approve the plan: ${errorDetail(err)}`);
+    return null;
   });
-  const run = overrides.runExecutor ?? runExecutor;
-  try {
-    return await run(options, deps, httpClient);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    errorLog(`Error: executor exited unexpectedly: ${message.slice(0, 200)}`);
+  if (approval === null) return 1;
+  if (approval.ok) {
+    result.plan_approved = true;
+    result.plan_hash = approval.plan_hash;
+    result.status = "active";
+    say(`Plan:       approved v${plan.plan_version}`);
+  } else if (approval.reason === "multiple_active_runs") {
+    deps.errorLog(
+      `Epic ${opts.epicKey} has MULTIPLE active runs \u2014 the plan could not be approved and the epic is wedged. Abandon the duplicate run, then re-run setup-epic.`
+    );
     return 1;
+  } else {
+    const msg = `A later plan version is already approved \u2014 approval skipped.`;
+    result.warnings.push(msg);
+    say(`Plan:       [warn] ${msg}`);
+  }
+  if (result.plan_hash && result.plan_hash !== localHash) {
+    result.warnings.push(
+      `Server plan hash differs from the local hash (the server re-hashes after applying file-overlap serialization). The server hash is authoritative.`
+    );
+  }
+  if (opts.json) {
+    deps.log(JSON.stringify(result, null, 2));
+  } else {
+    say("");
+    say(`Epic run ${result.epic_run_id} is ${result.status ?? "unknown"}.`);
+    say("The server-side reconciler will pick it up within ~30s.");
+    say("To execute claimed jobs on this machine, run:");
+    say(`  npx -y @bridge_gpt/mcp-server executor --repo ${access2.repoName}`);
   }
+  return 0;
 }
 
 // src/regression-check.ts
@@ -19836,8 +21011,8 @@ function extractChangedSymbolsFromDiff(diffText) {
   let newLineNo = 0;
   for (const rawLine of diffText.split("\n")) {
     if (rawLine.startsWith("+++ ")) {
-      const path33 = rawLine.slice(4).trim();
-      currentFile = path33 === "/dev/null" ? null : path33.replace(/^b\//, "");
+      const path34 = rawLine.slice(4).trim();
+      currentFile = path34 === "/dev/null" ? null : path34.replace(/^b\//, "");
       continue;
     }
     if (rawLine.startsWith("--- ") || rawLine.startsWith("diff --git") || rawLine.startsWith("index ")) {
@@ -20396,10 +21571,11 @@ async function runRegressionCheckCli(argv, overrides = {}) {
 }
 
 // src/install-bridge.ts
-import { readFile as readFile10, writeFile as writeFile7, mkdir as mkdir7, stat as stat7, rename, chmod, unlink } from "fs/promises";
+import { readFile as readFile10, writeFile as writeFile7, mkdir as mkdir7, stat as stat7, rename, chmod, unlink, open } from "fs/promises";
 import { spawn as spawn6 } from "child_process";
-import os12 from "os";
-import path22 from "path";
+import { randomBytes as cryptoRandomBytes, createHash as createHash3 } from "crypto";
+import os13 from "os";
+import path23 from "path";
 import readline from "readline";
 init_version_generated();
 init_bridge_config();
@@ -20432,26 +21608,52 @@ function getInstallBridgeUsage() {
     "  --api-key <key>   Bridge API key. Falls back to the BAPI_API_KEY env var,",
     "                    then an interactive (no-echo) prompt. Generate one in the",
     "                    Bridge API web UI Security page \u2014 this command consumes a",
-    "                    key, it does not create one. NEVER printed or logged.",
+    "                    key, it does not create one (--invite is the one exception:",
+    "                    it CREATES the project and its first admin key). NEVER",
+    "                    printed or logged.",
     "  --repo <name>     Repository name. Falls back to BAPI_REPO_NAME, then an",
     "                    inferred default you confirm interactively. MUST match the",
     "                    server-side repo registration (it keys the credential",
     "                    store as bapi:<repo>). Required (no inference) when stdin",
-    "                    is non-interactive.",
+    "                    is non-interactive. With --invite it is the name your NEW",
+    "                    project is created under (globally unique).",
+    "",
+    "Bootstrap-invite onboarding (no web UI, no pre-existing key):",
+    "  --invite [token]  Redeem a bootstrap invite: creates the project and mints",
+    "                    your own admin API key in one command. Mutually exclusive",
+    "                    with --api-key (in this mode the key is created, not",
+    "                    consumed).",
+    "",
+    "                    Run it WITHOUT a value \u2014 `install-bridge --invite` \u2014 and the",
+    "                    token is read from an interactive prompt with echo",
+    "                    suppressed, then sent only in the request body. This is the",
+    "                    default and the recommended path: 'a copy/paste one-liner'",
+    "                    and 'the token never touches shell history' are",
+    "                    contradictory, so the one-liner your operator sends you is",
+    "                    SECRET-FREE and the CLI asks for the token.",
+    "",
+    "                    Passing the token inline (--invite <token>, --invite=<token>)",
+    "                    or via BAPI_INVITE is for SCRIPTING ONLY: both forms EXPOSE",
+    "                    THE TOKEN to your shell history and to the process list.",
     "",
     "Flags:",
     "  --force                       Overwrite an existing real BAPI_API_KEY in a",
-    "                                host config without prompting.",
+    "                                host config (or in the credential store) without",
+    "                                prompting.",
     "  --dry-run                     Preview every step (scaffold targets, config",
     "                                files + keys with the key REDACTED, ping",
     "                                target, credential target, spawn command)",
     "                                without writing, pinging, or spawning anything.",
+    "                                With --invite it also never calls the exchange",
+    "                                endpoint and never generates or stores a secret.",
     "  --agent claude|cursor-agent   Agent to launch for the agentic remainder",
     "                                (default: claude).",
     "  -h, --help                    Show this help.",
     "",
     "Environment: BAPI_BASE_URL (default https://bridgegpt-api.com) and BAPI_DOCS_DIR",
-    "(default docs/tmp) are read from the environment with the shown fallbacks."
+    "(default docs/tmp) are read from the environment with the shown fallbacks.",
+    "BAPI_INVITE supplies the bootstrap-invite token non-interactively (scripting",
+    "only \u2014 it is exposed to shell history; prefer the prompt)."
   ].join("\n");
 }
 function parseInstallBridgeArgs(argv) {
@@ -20463,6 +21665,9 @@ function parseInstallBridgeArgs(argv) {
   let force = false;
   let dryRun = false;
   let agentName = DEFAULT_AGENT_NAME;
+  let invite;
+  let inviteSupplied = false;
+  let apiKeySupplied = false;
   const readValue = (arg, flag, i) => {
     if (arg.startsWith(`${flag}=`)) {
       return { value: arg.slice(flag.length + 1), nextIndex: i };
@@ -20486,9 +21691,23 @@ function parseInstallBridgeArgs(argv) {
       const r = readValue(arg, "--api-key", i);
       if ("error" in r) return { status: "error", message: r.error };
       apiKey = r.value;
+      apiKeySupplied = true;
       i = r.nextIndex;
       continue;
     }
+    if (arg === "--invite" || arg.startsWith("--invite=")) {
+      inviteSupplied = true;
+      if (arg.startsWith("--invite=")) {
+        invite = arg.slice("--invite=".length);
+      } else {
+        const next = argv[i + 1];
+        if (typeof next === "string" && !next.startsWith("-")) {
+          invite = next;
+          i += 1;
+        }
+      }
+      continue;
+    }
     if (arg === "--repo" || arg.startsWith("--repo=")) {
       const r = readValue(arg, "--repo", i);
       if ("error" in r) return { status: "error", message: r.error };
@@ -20517,33 +21736,55 @@ function parseInstallBridgeArgs(argv) {
       message: `Unexpected positional argument: '${arg}'. install-bridge does not accept positional arguments.`
     };
   }
-  return { status: "ok", options: { apiKey, repo, force, dryRun, agentName } };
+  if (inviteSupplied && apiKeySupplied) {
+    return {
+      status: "error",
+      message: "--invite and --api-key are mutually exclusive: a bootstrap invite creates your API key, it does not consume an existing one."
+    };
+  }
+  return {
+    status: "ok",
+    options: { apiKey, repo, force, dryRun, agentName, invite, inviteMode: inviteSupplied }
+  };
 }
-function promptSecretViaReadline(promptText) {
+function promptSecretViaReadline(promptText, input = process.stdin, output = process.stderr) {
   return new Promise((resolve2) => {
     const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stderr,
+      input,
+      output,
       terminal: true
     });
     const mutable = rl;
     let muted = false;
     mutable._writeToOutput = (s) => {
-      if (!muted) process.stderr.write(s);
+      if (!muted) {
+        output.write(s);
+      } else if (s.includes(promptText)) {
+        output.write(promptText);
+      }
     };
-    process.stderr.write(promptText);
-    muted = true;
-    rl.question("", (answer) => {
+    let answered = false;
+    rl.on("close", () => {
+      if (!answered) resolve2("");
+    });
+    rl.question(promptText, (answer) => {
+      answered = true;
       rl.close();
-      process.stderr.write("\n");
+      output.write("\n");
       resolve2(answer.trim());
     });
+    muted = true;
   });
 }
 function promptLineViaReadline(promptText) {
   return new Promise((resolve2) => {
     const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    let answered = false;
+    rl.on("close", () => {
+      if (!answered) resolve2("");
+    });
     rl.question(promptText, (answer) => {
+      answered = true;
       rl.close();
       resolve2(answer.trim());
     });
@@ -20553,6 +21794,7 @@ function spawnPrewarmDefault(command, args, env) {
   return new Promise((resolve2) => {
     const sanitizedEnv = { ...env };
     delete sanitizedEnv.BAPI_API_KEY;
+    delete sanitizedEnv.BAPI_INVITE;
     try {
       const child = spawn6(command, args, {
         shell: false,
@@ -20581,7 +21823,7 @@ function createDefaultInstallBridgeDeps() {
     env: process.env,
     cwd: process.cwd(),
     platform: process.platform,
-    homedir: os12.homedir,
+    homedir: os13.homedir,
     isTTY,
     readFile: (p) => readFile10(p, "utf-8"),
     writeFile: (p, data, options) => writeFile7(p, data, options),
@@ -20590,12 +21832,24 @@ function createDefaultInstallBridgeDeps() {
     rename: (a, b) => rename(a, b),
     chmod: (p, m) => chmod(p, m),
     unlink: (p) => unlink(p),
+    open: async (p, flags, mode) => {
+      const handle = await open(p, flags, mode);
+      return {
+        writeFile: (data) => handle.writeFile(data, { encoding: "utf-8" }),
+        sync: () => handle.sync(),
+        close: () => handle.close()
+      };
+    },
+    randomBytes: (size) => cryptoRandomBytes(size),
     promptSecret: isTTY ? promptSecretViaReadline : void 0,
     promptLine: isTTY ? promptLineViaReadline : void 0,
     fetch: (...args) => fetch(...args),
     spawnPrewarm: spawnPrewarmDefault,
     runInit,
     upsertCredential: upsertBapiCredential,
+    prepareBootstrapPending: prepareBootstrapPendingCredential,
+    repointBootstrapPending: repointBootstrapPendingCredential,
+    promoteBootstrapPending: promoteBootstrapPendingCredential,
     buildShellCommand: buildGenericAgentShellCommand,
     spawnTerminalTab: getDefaultSpawnTerminalTabForPlatform(process.platform),
     startTicketsDeps: createDefaultStartTicketsDeps(),
@@ -20623,6 +21877,26 @@ async function resolveApiKey(options, deps) {
     error: "An API key is required. Pass --api-key or set the BAPI_API_KEY environment variable (no interactive terminal is available to prompt for it)."
   };
 }
+async function resolveInviteToken(options, deps) {
+  if (typeof options.invite === "string" && options.invite.trim().length > 0) {
+    return { ok: true, value: options.invite.trim() };
+  }
+  const fromEnv = deps.env.BAPI_INVITE;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+    return { ok: true, value: fromEnv.trim() };
+  }
+  if (deps.isTTY && deps.promptSecret) {
+    const entered = (await deps.promptSecret("Bootstrap invite token (input hidden): ")).trim();
+    if (entered.length > 0) {
+      return { ok: true, value: entered };
+    }
+    return { ok: false, error: "No bootstrap invite token entered." };
+  }
+  return {
+    ok: false,
+    error: "A bootstrap invite token is required. Pass --invite <token> or set the BAPI_INVITE environment variable (no interactive terminal is available to prompt for it). Note that both forms expose the token to your shell history and process list \u2014 prefer running 'install-bridge --invite' interactively."
+  };
+}
 async function resolveRepoName(options, deps) {
   if (typeof options.repo === "string" && options.repo.trim().length > 0) {
     return { ok: true, value: options.repo.trim() };
@@ -20643,7 +21917,7 @@ async function resolveRepoName(options, deps) {
     readFile: deps.readFile
   });
   if (!inferred) {
-    const validated = validateRepoName(path22.basename(deps.cwd));
+    const validated = validateRepoName(path23.basename(deps.cwd));
     if (validated.ok) inferred = validated.value;
   }
   if (inferred) {
@@ -20662,7 +21936,7 @@ async function resolveHostConfigTargets(deps) {
   ];
   const dirExists = async (rel) => {
     try {
-      await deps.stat(path22.join(deps.cwd, rel));
+      await deps.stat(path23.join(deps.cwd, rel));
       return true;
     } catch {
       return false;
@@ -20709,7 +21983,7 @@ async function readHostConfig(deps, fullPath) {
 }
 async function detectExistingRealKey(deps, targets) {
   for (const target of targets) {
-    const parsed = await readHostConfig(deps, path22.join(deps.cwd, target.relPath));
+    const parsed = await readHostConfig(deps, path23.join(deps.cwd, target.relPath));
     const entry = parsed?.[target.topLevelKey]?.["bridge-api"];
     if (entry?.env && !isPlaceholderApiKey(entry.env.BAPI_API_KEY)) {
       return true;
@@ -20720,13 +21994,13 @@ async function detectExistingRealKey(deps, targets) {
 async function writeHostConfigs(deps, targets, entry) {
   const written = [];
   for (const target of targets) {
-    const fullPath = path22.join(deps.cwd, target.relPath);
+    const fullPath = path23.join(deps.cwd, target.relPath);
     const parsed = await readHostConfig(deps, fullPath) ?? {};
     if (!parsed[target.topLevelKey] || typeof parsed[target.topLevelKey] !== "object") {
       parsed[target.topLevelKey] = {};
     }
     parsed[target.topLevelKey]["bridge-api"] = entry;
-    await deps.mkdir(path22.dirname(fullPath), { recursive: true });
+    await deps.mkdir(path23.dirname(fullPath), { recursive: true });
     await deps.writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", {
       encoding: "utf-8"
     });
@@ -20772,7 +22046,91 @@ async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
     message: `Connectivity check failed (HTTP ${resp.status}). Verify your repo, API key, and BAPI_BASE_URL.`
   };
 }
+var BOOTSTRAP_KEY_SECRET_BYTES = 32;
+function generateBootstrapKeySecret(randomBytes3) {
+  return randomBytes3(BOOTSTRAP_KEY_SECRET_BYTES).toString("base64url");
+}
+function fingerprintBootstrapInvite(token) {
+  return createHash3("sha256").update(token, "utf-8").digest("hex");
+}
+function buildBootstrapExchangeUrl(baseUrl) {
+  return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap`;
+}
+async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, keySecret) {
+  const url = buildBootstrapExchangeUrl(baseUrl);
+  let resp;
+  try {
+    resp = await deps.fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token, repo_name: repoName, key_secret: keySecret }),
+      signal: AbortSignal.timeout(1e4)
+    });
+  } catch (err) {
+    void err;
+    return {
+      ok: false,
+      kind: "failed",
+      message: `Could not reach the Bridge API at ${baseUrl} to redeem the bootstrap invite. Check BAPI_BASE_URL and your network, then re-run \u2014 the invite has not been used, and the re-run will reuse the same locally-stored secret.`
+    };
+  }
+  if (resp.ok) {
+    let repo;
+    try {
+      const body = await resp.json();
+      repo = body?.repo_name;
+    } catch {
+      return {
+        ok: false,
+        kind: "failed",
+        message: "The Bridge API returned an unreadable response to the bootstrap exchange."
+      };
+    }
+    const validated = validateRepoName(repo);
+    if (!validated.ok) {
+      return {
+        ok: false,
+        kind: "failed",
+        message: "The Bridge API returned an unexpected repo name for the bootstrap exchange."
+      };
+    }
+    return { ok: true, repoName: validated.value };
+  }
+  if (resp.status === 409) {
+    return {
+      ok: false,
+      kind: "repo-name-taken",
+      message: `The repo name '${repoName}' is already taken (HTTP 409). Repo names are globally unique.`
+    };
+  }
+  if (resp.status === 401) {
+    return { ok: false, kind: "invalid-invite", message: `The Bridge API rejected the bootstrap invite (HTTP ${resp.status}).` };
+  }
+  return {
+    ok: false,
+    kind: "failed",
+    message: `The bootstrap exchange failed (HTTP ${resp.status}). Verify BAPI_BASE_URL and try again.`
+  };
+}
+var BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE = [
+  "The Bridge API rejected the bootstrap invite (HTTP 401).",
+  "",
+  "Either the invite is invalid, expired, or revoked \u2014 or it was ALREADY redeemed from this",
+  "machine and the local secret has since been lost (e.g. ~/.config/bridge was deleted).",
+  "",
+  "If it was already redeemed, you cannot recover it yourself:",
+  "  \u2022 Re-running will NOT work: each run without the original local secret sends a new one,",
+  "    which cannot match what the server stored, so it will keep returning 401.",
+  "  \u2022 A new bootstrap invite will NOT work either: your repo name is globally unique and is",
+  "    now taken by the project you already created, so it cannot be redeemed again.",
+  "",
+  "Ask your Bridge API operator to recover it for you: they revoke the orphaned key",
+  "(DELETE /setup/keys/{id}) and issue a replacement key for the EXISTING project",
+  "(POST /setup/keys), then send you that key. Run install-bridge with --api-key <that key>."
+].join("\n");
+var BOOTSTRAP_INVITE_REJECTED_MESSAGE = "The Bridge API rejected the bootstrap invite (HTTP 401). The invite is invalid, expired, or revoked \u2014 ask your Bridge API operator for a new one. (Your locally-stored secret was sent unchanged, so this is not a lost-secret problem.)";
 function buildDryRunPreview(plan) {
+  if (plan.bootstrapInvite) return buildBootstrapDryRunPreview(plan);
   return [
     "install-bridge --dry-run (no writes, no network, no spawns)",
     `Repo name:        ${plan.repoName}`,
@@ -20793,6 +22151,33 @@ function buildDryRunPreview(plan) {
     `Step 5 \u2014 spawn agent session: ${plan.spawnCommand}`
   ];
 }
+function buildBootstrapDryRunPreview(plan) {
+  const pendingTarget = `bootstrap-pending:${plan.repoName}`;
+  return [
+    "install-bridge --invite --dry-run (no writes, no network, no spawns, no secret generated)",
+    `Repo name:        ${plan.repoName} (created by the exchange; globally unique)`,
+    `Base URL:         ${plan.baseUrl}`,
+    `Docs dir:         ${plan.docsDir}`,
+    `Agent:            ${plan.agentName}`,
+    "",
+    "Step 1 \u2014 scaffold (runInit): commands, agents, pipelines, .bridge/config, secret-free MCP placeholders.",
+    `Step 2a \u2014 generate key_secret (32 CSPRNG bytes) and fsync it to ${pendingTarget} at ${plan.credentialStorePath}`,
+    "          BEFORE the exchange. If that write fails the run ABORTS and no invite is spent.",
+    `Step 2b \u2014 redeem the bootstrap invite (replaces the pre-flight ping \u2014 there is no key yet):`,
+    `          POST ${plan.exchangeUrl}`,
+    `          body: {"token": "${REDACTED_API_KEY}", "repo_name": "${plan.repoName}", "key_secret": "${REDACTED_API_KEY}"}`,
+    `Step 2c \u2014 connectivity ping with the newly-minted key (before any durable key write): GET ${plan.pingUrl} (X-API-Key: ${REDACTED_API_KEY})`,
+    "Step 3 \u2014 write per-host MCP config (read-merge-write, launcher version-pinned):",
+    ...plan.configTargets.map(
+      (t) => `  ${t}: BAPI_REPO_NAME=${plan.repoName}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${plan.baseUrl}, BAPI_DOCS_DIR=${plan.docsDir}`
+    ),
+    ...plan.manualEditors.length > 0 ? [`  ${plan.manualEditors.join(" + ")}: detected (global config) \u2014 manual setup instructions would be printed.`] : [],
+    `Step 3b \u2014 pre-warm the version-pinned launcher bucket (fail-open, env sanitized \u2014 BAPI_API_KEY / BAPI_INVITE removed): ${plan.prewarmCommand}`,
+    MCP_TIMEOUT_GUIDANCE,
+    `Step 4 \u2014 promote ${pendingTarget} \u2192 ${plan.credentialTarget} at ${plan.credentialStorePath} (only after the exchange succeeds)`,
+    `Step 5 \u2014 spawn agent session: ${plan.spawnCommand}`
+  ];
+}
 async function detectManualEditors(deps) {
   const exists = async (p) => {
     try {
@@ -20802,8 +22187,8 @@ async function detectManualEditors(deps) {
       return false;
     }
   };
-  const windsurf = await exists(path22.join(deps.cwd, ".windsurf")) || await exists(path22.join(deps.cwd, ".windsurfrules"));
-  const codex = await exists(path22.join(deps.homedir(), ".codex"));
+  const windsurf = await exists(path23.join(deps.cwd, ".windsurf")) || await exists(path23.join(deps.cwd, ".windsurfrules"));
+  const codex = await exists(path23.join(deps.homedir(), ".codex"));
   return { windsurf, codex };
 }
 function manualEditorNames(editors) {
@@ -20852,18 +22237,38 @@ async function runInstallBridgeCli(argv, overrides = {}) {
     return 1;
   }
   const options = parsed.options;
-  const keyResult = await resolveApiKey(options, deps);
-  if (!keyResult.ok) {
-    errorLog(`Error: ${keyResult.error}`);
-    return 1;
+  const bootstrapInviteMode = options.inviteMode === true || (deps.env.BAPI_INVITE ?? "").trim().length > 0;
+  let apiKey = "";
+  let inviteToken = "";
+  if (bootstrapInviteMode) {
+    const inviteResult = await resolveInviteToken(options, deps);
+    if (!inviteResult.ok) {
+      errorLog(`Error: ${inviteResult.error}`);
+      return 1;
+    }
+    inviteToken = inviteResult.value;
+  } else {
+    const keyResult = await resolveApiKey(options, deps);
+    if (!keyResult.ok) {
+      errorLog(`Error: ${keyResult.error}`);
+      return 1;
+    }
+    apiKey = keyResult.value;
   }
-  const apiKey = keyResult.value;
   const repoResult = await resolveRepoName(options, deps);
   if (!repoResult.ok) {
     errorLog(`Error: ${repoResult.error}`);
     return 1;
   }
-  const repoName = repoResult.value;
+  let repoName = repoResult.value;
+  if (bootstrapInviteMode) {
+    const validated = validateRepoName(repoName);
+    if (!validated.ok) {
+      errorLog(`Error: invalid repo name \u2014 ${validated.error}.`);
+      return 1;
+    }
+    repoName = validated.value;
+  }
   const baseUrl = deps.env.BAPI_BASE_URL ?? DEFAULT_BAPI_BASE_URL2;
   const docsDir = deps.env.BAPI_DOCS_DIR ?? DEFAULT_BAPI_DOCS_DIR;
   const agent = resolveAgentSpec(options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
@@ -20890,14 +22295,27 @@ async function runInstallBridgeCli(argv, overrides = {}) {
     credentialStorePath,
     pingUrl: buildPingUrl(baseUrl, repoName),
     prewarmCommand: buildPrewarmCommandPreview(),
-    spawnCommand
+    spawnCommand,
+    ...bootstrapInviteMode ? { bootstrapInvite: true, exchangeUrl: buildBootstrapExchangeUrl(baseUrl) } : {}
   };
   if (options.dryRun) {
     for (const line of buildDryRunPreview(plan)) log(line);
     return 0;
   }
-  const entry = buildInstallBridgeServerEntry(deps.cwd, repoName, apiKey, baseUrl, docsDir);
+  const credentialWriteDeps = {
+    env: deps.env,
+    homedir: deps.homedir,
+    platform: deps.platform,
+    readFile: deps.readFile,
+    mkdir: deps.mkdir,
+    writeFile: (p, d, o) => deps.writeFile(p, d, o),
+    rename: deps.rename,
+    chmod: deps.chmod,
+    unlink: deps.unlink,
+    open: deps.open
+  };
   const hasRealKey = await detectExistingRealKey(deps, targets);
+  let overwriteConsent = options.force;
   if (hasRealKey && !options.force) {
     if (deps.isTTY && deps.promptLine) {
       const answer = (await deps.promptLine(
@@ -20907,6 +22325,7 @@ async function runInstallBridgeCli(argv, overrides = {}) {
         errorLog("Aborted: existing API key left unchanged (re-run with --force to overwrite).");
         return 1;
       }
+      overwriteConsent = true;
     } else {
       errorLog(
         "Error: a host config already contains a BAPI_API_KEY. Re-run with --force to overwrite it (refusing to overwrite a credential non-interactively without consent)."
@@ -20916,13 +22335,133 @@ async function runInstallBridgeCli(argv, overrides = {}) {
   }
   log("Step 1/5 \u2014 scaffolding project (commands, agents, pipelines, config placeholders)\u2026");
   await deps.runInit(deps.cwd);
-  log("Step 2/5 \u2014 verifying connectivity\u2026");
+  let inviteFingerprint = "";
+  if (bootstrapInviteMode) {
+    inviteFingerprint = fingerprintBootstrapInvite(inviteToken);
+    log("Step 2/5 \u2014 redeeming the bootstrap invite\u2026");
+    let prepared = await deps.prepareBootstrapPending(
+      {
+        repoName,
+        inviteFingerprint,
+        generateKeySecret: () => generateBootstrapKeySecret(deps.randomBytes),
+        allowOverwriteExistingCredential: overwriteConsent
+      },
+      credentialWriteDeps
+    );
+    if (!prepared.ok && prepared.kind === "credential-conflict") {
+      if (deps.isTTY && deps.promptLine) {
+        const answer = (await deps.promptLine(
+          `The credential store already holds a key for ${prepared.target}. Overwrite it? [y/N]: `
+        )).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+          errorLog("Aborted: existing credential left unchanged (re-run with --force to overwrite).");
+          return 1;
+        }
+        overwriteConsent = true;
+        prepared = await deps.prepareBootstrapPending(
+          {
+            repoName,
+            inviteFingerprint,
+            generateKeySecret: () => generateBootstrapKeySecret(deps.randomBytes),
+            allowOverwriteExistingCredential: true
+          },
+          credentialWriteDeps
+        );
+      } else {
+        errorLog(
+          `Error: ${prepared.error} Re-run with --force to overwrite it (refusing to overwrite a credential non-interactively without consent).`
+        );
+        return 1;
+      }
+    }
+    if (!prepared.ok && prepared.kind === "pending-conflict") {
+      errorLog(
+        `Error: ${prepared.error} This invite has NOT been used, and re-running will not clear the conflict.`
+      );
+      return 1;
+    }
+    if (!prepared.ok) {
+      errorLog(
+        `Error: could not durably store the bootstrap credential (${prepared.kind}). ${prepared.error} The bootstrap invite has NOT been used \u2014 fix the problem and re-run.`
+      );
+      return 1;
+    }
+    const keySecret = prepared.keySecret;
+    const reusedPendingSecret = prepared.reused;
+    log(`  saved the pending credential for ${prepared.target} (fsynced before the exchange)`);
+    let exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+    while (!exchange.ok && exchange.kind === "repo-name-taken") {
+      if (!deps.isTTY || !deps.promptLine) {
+        errorLog(
+          `Error: ${exchange.message} Re-run with a different --repo (the bootstrap invite has NOT been used).`
+        );
+        return 1;
+      }
+      errorLog(exchange.message);
+      const answer = (await deps.promptLine("Choose a different repo name: ")).trim();
+      const validated = validateRepoName(answer);
+      if (!validated.ok) {
+        errorLog(`Error: invalid repo name \u2014 ${validated.error}.`);
+        return 1;
+      }
+      const nextRepo = validated.value;
+      const repointed = await deps.repointBootstrapPending(
+        {
+          fromRepoName: repoName,
+          toRepoName: nextRepo,
+          inviteFingerprint,
+          allowOverwriteExistingCredential: overwriteConsent
+        },
+        credentialWriteDeps
+      );
+      if (!repointed.ok) {
+        errorLog(
+          `Error: could not re-point the pending bootstrap credential to '${nextRepo}' (${repointed.kind}). ${repointed.error} The bootstrap invite has NOT been used.`
+        );
+        return 1;
+      }
+      repoName = nextRepo;
+      exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+    }
+    if (!exchange.ok) {
+      if (exchange.kind === "invalid-invite") {
+        errorLog(
+          reusedPendingSecret ? BOOTSTRAP_INVITE_REJECTED_MESSAGE : BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE
+        );
+      } else {
+        errorLog(`Error: ${exchange.message}`);
+      }
+      return 1;
+    }
+    if (exchange.repoName !== repoName) {
+      const repointed = await deps.repointBootstrapPending(
+        {
+          fromRepoName: repoName,
+          toRepoName: exchange.repoName,
+          inviteFingerprint,
+          allowOverwriteExistingCredential: overwriteConsent
+        },
+        credentialWriteDeps
+      );
+      if (!repointed.ok) {
+        errorLog(
+          `Error: the project was created as '${exchange.repoName}' but the pending credential could not be re-pointed to it (${repointed.kind}). ${repointed.error}`
+        );
+        return 1;
+      }
+      repoName = exchange.repoName;
+    }
+    log(`  bootstrap invite redeemed \u2014 project '${repoName}' is ready`);
+    apiKey = keySecret;
+  }
+  if (!bootstrapInviteMode) log("Step 2/5 \u2014 verifying connectivity\u2026");
   const ping = await verifyConnectivity(deps, baseUrl, repoName, apiKey);
   if (!ping.ok) {
     errorLog(`Error: ${ping.message}`);
     return 1;
   }
   log("  connectivity OK");
+  const entry = buildInstallBridgeServerEntry(deps.cwd, repoName, apiKey, baseUrl, docsDir);
   log("Step 3/5 \u2014 writing per-host MCP config\u2026");
   const written = await writeHostConfigs(deps, targets, entry);
   for (const relPath of written) log(`  wrote ${relPath}`);
@@ -20938,31 +22477,35 @@ async function runInstallBridgeCli(argv, overrides = {}) {
       `Warning: could not pre-warm the version-pinned launcher bucket${prewarm.warning ? ` (${prewarm.warning})` : ""}. The first MCP launch may pay a one-time cold install and could be slow. ${MCP_TIMEOUT_GUIDANCE}`
     );
   }
-  log("Step 4/5 \u2014 persisting routing credential\u2026");
-  try {
-    const writeDeps = {
-      env: deps.env,
-      homedir: deps.homedir,
-      platform: deps.platform,
-      readFile: deps.readFile,
-      mkdir: deps.mkdir,
-      writeFile: (p, d, o) => deps.writeFile(p, d, o),
-      rename: deps.rename,
-      chmod: deps.chmod,
-      unlink: deps.unlink
-    };
-    const result = await deps.upsertCredential(repoName, apiKey, writeDeps);
-    if (result.ok) {
-      log(`  stored routing credential for ${result.target} at ${result.path}`);
-    } else {
+  if (bootstrapInviteMode) {
+    log("Step 4/5 \u2014 promoting the bootstrap credential\u2026");
+    const promoted = await deps.promoteBootstrapPending(
+      { repoName, inviteFingerprint, allowOverwriteExistingCredential: overwriteConsent },
+      credentialWriteDeps
+    );
+    if (!promoted.ok) {
+      errorLog(
+        `Error: the project and API key were created, but the credential could not be stored (${promoted.kind}). ${promoted.error} Your key is still saved locally as a pending record \u2014 re-run install-bridge with the same bootstrap invite to finish (the redemption will replay and return the same key).`
+      );
+      return 1;
+    }
+    log(`  stored routing credential for ${promoted.target} at ${promoted.path}`);
+  } else {
+    log("Step 4/5 \u2014 persisting routing credential\u2026");
+    try {
+      const result = await deps.upsertCredential(repoName, apiKey, credentialWriteDeps);
+      if (result.ok) {
+        log(`  stored routing credential for ${result.target} at ${result.path}`);
+      } else {
+        log(
+          `  warning: could not persist the routing credential (${result.kind}). start-tickets model routing may not resolve the key for bapi:${repoName} and will fail open to the premium/Opus tier (the most expensive) \u2014 set BAPI_API_KEY in the shell or re-run install-bridge, then verify with 'npx -y @bridge_gpt/mcp-server doctor'.`
+        );
+      }
+    } catch {
       log(
-        `  warning: could not persist the routing credential (${result.kind}). start-tickets model routing may not resolve the key for ${plan.credentialTarget} and will fail open to the premium/Opus tier (the most expensive) \u2014 set BAPI_API_KEY in the shell or re-run install-bridge, then verify with 'npx -y @bridge_gpt/mcp-server doctor'.`
+        "  warning: could not persist the routing credential (unexpected error). start-tickets model routing may need BAPI_API_KEY in the shell and will fail open to the premium/Opus tier (the most expensive) until fixed \u2014 verify with 'npx -y @bridge_gpt/mcp-server doctor'."
       );
     }
-  } catch {
-    log(
-      "  warning: could not persist the routing credential (unexpected error). start-tickets model routing may need BAPI_API_KEY in the shell and will fail open to the premium/Opus tier (the most expensive) until fixed \u2014 verify with 'npx -y @bridge_gpt/mcp-server doctor'."
-    );
   }
   log(`Step 5/5 \u2014 opening a ${agent.name} session for /install-bridge + /learn-repository\u2026`);
   const terminal = detectTerminal(void 0, deps.env);
@@ -20990,7 +22533,7 @@ async function runInstallBridgeCli(argv, overrides = {}) {
 init_version_generated();
 import { spawn as spawn7 } from "child_process";
 import { stat as stat8 } from "fs/promises";
-import path23 from "path";
+import path24 from "path";
 init_start_tickets();
 init_agent_registry();
 async function fetchLatestVersion() {
@@ -21057,7 +22600,7 @@ async function runUpgradeCli(argv) {
     );
     for (const target of configTargets) {
       try {
-        await stat8(path23.join(cwd, target));
+        await stat8(path24.join(cwd, target));
         console.log(`    - ${target}`);
       } catch {
       }
@@ -21076,7 +22619,7 @@ async function runUpgradeCli(argv) {
     return 0;
   }
   try {
-    const localModulePath = path23.join(cwd, "node_modules", "@bridge_gpt", "mcp-server");
+    const localModulePath = path24.join(cwd, "node_modules", "@bridge_gpt", "mcp-server");
     await stat8(localModulePath);
     console.log(
       "Found stale local installation in node_modules. Removing to converge on pinned-npx..."
@@ -21144,13 +22687,13 @@ init_credential_store();
 
 // src/credentials-cli.ts
 import { readFile as readFile11, mkdir as mkdir8, writeFile as writeFile8, rename as rename2, chmod as chmod2, unlink as unlink2 } from "fs/promises";
-import os13 from "os";
+import os14 from "os";
 import readline2 from "readline";
 
 // src/agent-config-credential-migration.ts
 init_credential_store();
 init_start_tickets_repo();
-import path24 from "path";
+import path25 from "path";
 async function readAgentMcpConfigIfPresent(filePath, readFile14) {
   let raw;
   try {
@@ -21212,7 +22755,7 @@ function resolveAgentConfigScanTargets(cwd, sources) {
   const selected = sources && sources.length > 0 ? AGENT_CONFIG_SOURCE_NAMES.filter((name) => sources.includes(name)) : AGENT_CONFIG_SOURCE_NAMES;
   return selected.map((name) => ({
     name,
-    filePath: name === ".mcp.json" ? path24.join(cwd, ".mcp.json") : path24.join(cwd, ".cursor", "mcp.json")
+    filePath: name === ".mcp.json" ? path25.join(cwd, ".mcp.json") : path25.join(cwd, ".cursor", "mcp.json")
   }));
 }
 async function scanAgentMcpConfigsForBapiApiKey(deps) {
@@ -21431,7 +22974,7 @@ function createDefaultCredentialsDeps(writeCredentials) {
     env: process.env,
     cwd: process.cwd(),
     platform: process.platform,
-    homedir: os13.homedir,
+    homedir: os14.homedir,
     readFile: (p) => readFile11(p, "utf-8"),
     mkdir: (p, o) => mkdir8(p, o),
     writeFile: (p, d, o) => writeFile8(p, d, o),
@@ -21992,7 +23535,7 @@ async function getSfccVersionConfig(buildGetUrl2, getGetHeaders2, repoName) {
 
 // src/sfcc/credentials.ts
 import { readFile as readFile12, writeFile as writeFile9, mkdir as mkdir9 } from "fs/promises";
-import path25 from "path";
+import path26 from "path";
 var ENV_HOSTNAME = "SFCC_HOSTNAME";
 var ENV_CLIENT_ID = "SFCC_CLIENT_ID";
 var ENV_CLIENT_SECRET = "SFCC_CLIENT_SECRET";
@@ -22042,7 +23585,7 @@ async function resolveSfccCredentials(explicitHostname, env = process.env, deps
     await ensureGitInfoExcluded(cwd, DW_JSON, { readFile: rf, writeFile: wf, mkdir: mk });
   } catch {
   }
-  const dwJsonPath = path25.join(cwd, DW_JSON);
+  const dwJsonPath = path26.join(cwd, DW_JSON);
   let dwJson;
   try {
     const raw = await rf(dwJsonPath);
@@ -22115,11 +23658,11 @@ function mapOcapiWriteFault(status, body) {
     errorCode: known ? expected : "OCAPI_WRITE_FAULT"
   };
 }
-function buildSyntheticIfMatchRequiredBody(path33) {
+function buildSyntheticIfMatchRequiredBody(path34) {
   return {
     fault: {
       type: "IfMatchRequiredException",
-      message: `PATCH ${path33} requires an ETag (If-Match) captured from the GET round trip, but the GET response returned no ETag header. Cannot safely issue a conditional PATCH.`
+      message: `PATCH ${path34} requires an ETag (If-Match) captured from the GET round trip, but the GET response returned no ETag header. Cannot safely issue a conditional PATCH.`
     }
   };
 }
@@ -22169,9 +23712,9 @@ async function getAmToken(credentials) {
 function invalidateAmToken(credentials) {
   tokenCache.delete(credentials.hostname);
 }
-function buildOcapiUrl(hostname, ocapiVersion, path33) {
+function buildOcapiUrl(hostname, ocapiVersion, path34) {
   const baseUrl = `https://${hostname}/s/-/dw/data/${ocapiVersion}`;
-  return `${baseUrl}${path33.startsWith("/") ? path33 : "/" + path33}`;
+  return `${baseUrl}${path34.startsWith("/") ? path34 : "/" + path34}`;
 }
 async function parseOcapiResponse(resp) {
   try {
@@ -22222,10 +23765,10 @@ async function fetchWith429Backoff(url, init) {
   }
   return resp;
 }
-async function ocapiRequest(method, path33, body, credentials, ocapiVersion, extraHeaders) {
+async function ocapiRequest(method, path34, body, credentials, ocapiVersion, extraHeaders) {
   const doRequest = async () => {
     const token = await getAmToken(credentials);
-    const url = buildOcapiUrl(credentials.hostname, ocapiVersion, path33);
+    const url = buildOcapiUrl(credentials.hostname, ocapiVersion, path34);
     const init = {
       method,
       headers: {
@@ -22258,23 +23801,23 @@ async function ocapiRequest(method, path33, body, credentials, ocapiVersion, ext
   }
   return first;
 }
-async function ocapiGet(path33, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  return ocapiRequest("GET", path33, void 0, credentials, ocapiVersion);
+async function ocapiGet(path34, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  return ocapiRequest("GET", path34, void 0, credentials, ocapiVersion);
 }
-async function ocapiPost(path33, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  return ocapiRequest("POST", path33, body, credentials, ocapiVersion);
+async function ocapiPost(path34, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  return ocapiRequest("POST", path34, body, credentials, ocapiVersion);
 }
-async function ocapiPut(path33, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  return ocapiRequest("PUT", path33, body, credentials, ocapiVersion);
+async function ocapiPut(path34, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  return ocapiRequest("PUT", path34, body, credentials, ocapiVersion);
 }
-async function ocapiPatch(path33, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  const getResult = await ocapiGet(path33, credentials, ocapiVersion);
+async function ocapiPatch(path34, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  const getResult = await ocapiGet(path34, credentials, ocapiVersion);
   if (!getResult.ok) {
     return getResult;
   }
   const etag = getResult.etag;
   if (etag === null || etag === void 0 || etag.trim() === "") {
-    const syntheticBody = buildSyntheticIfMatchRequiredBody(path33);
+    const syntheticBody = buildSyntheticIfMatchRequiredBody(path34);
     return {
       ok: false,
       status: 409,
@@ -22282,10 +23825,10 @@ async function ocapiPatch(path33, body, credentials, ocapiVersion = DEFAULT_OCAP
       fault: mapOcapiWriteFault(409, syntheticBody)
     };
   }
-  return ocapiRequest("PATCH", path33, body, credentials, ocapiVersion, { "If-Match": etag });
+  return ocapiRequest("PATCH", path34, body, credentials, ocapiVersion, { "If-Match": etag });
 }
-async function ocapiPatchDirect(path33, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  return ocapiRequest("PATCH", path33, body, credentials, ocapiVersion);
+async function ocapiPatchDirect(path34, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  return ocapiRequest("PATCH", path34, body, credentials, ocapiVersion);
 }
 
 // src/sfcc/setup-status.ts
@@ -22473,12 +24016,12 @@ function formatOcapiWriteGrantJson(ocapiVersion, clientIdPlaceholder = "<YOUR_CL
   return JSON.stringify(buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder), null, 2);
 }
 function buildOcapiWriteGrant403Text(params) {
-  const { operation, path: path33, ocapiVersion, body } = params;
+  const { operation, path: path34, ocapiVersion, body } = params;
   const bodyLine = body === void 0 ? "" : `
 Response body:
 ${JSON.stringify(body, null, 2)}
 `;
-  return `HTTP 403: OCAPI write access denied for ${operation} ${path33}.
+  return `HTTP 403: OCAPI write access denied for ${operation} ${path34}.
 ` + bodyLine + `
 To grant write access, paste the JSON below in Business Manager:
   Administration > Site Development > Open Commerce API Settings \u2192 Data API tab
@@ -22601,11 +24144,11 @@ Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`;
 }
 
 // src/sfcc/reads-system-object.ts
-import path27 from "path";
+import path28 from "path";
 import { z as z3 } from "zod";
 
 // src/sfcc/output.ts
-import path26 from "path";
+import path27 from "path";
 import { mkdir as mkdir10, writeFile as writeFile10 } from "fs/promises";
 var SFCC_MAX_INLINE = 5e4;
 function truncationNote(savedPath) {
@@ -22619,7 +24162,7 @@ async function truncateAndSaveIfNeeded(text, dir, filename, deps = {}) {
   }
   const mk = deps.mkdir ?? mkdir10;
   const wf = deps.writeFile ?? writeFile10;
-  const filePath = path26.join(dir, filename);
+  const filePath = path27.join(dir, filename);
   try {
     await mk(dir, { recursive: true });
     await wf(filePath, text, "utf-8");
@@ -22687,7 +24230,7 @@ function buildSystemObjectListHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path27.join(await getDocsDir2(), "sfcc");
+      const dir = path28.join(await getDocsDir2(), "sfcc");
       return saveAndReturn(text, dir, `system-object-list-${safeTimestamp()}.json`);
     }
   );
@@ -22710,7 +24253,7 @@ function buildSystemObjectGetHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path27.join(await getDocsDir2(), "sfcc");
+      const dir = path28.join(await getDocsDir2(), "sfcc");
       return saveAndReturn(
         text,
         dir,
@@ -22742,7 +24285,7 @@ function buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path27.join(await getDocsDir2(), "sfcc");
+      const dir = path28.join(await getDocsDir2(), "sfcc");
       return saveAndReturn(
         text,
         dir,
@@ -22783,7 +24326,7 @@ function registerSystemObjectReadTools(registerTool2, deps) {
 }
 
 // src/sfcc/reads-custom-object-def.ts
-import path28 from "path";
+import path29 from "path";
 import { z as z4 } from "zod";
 var READ_ANNOTATIONS2 = {
   readOnlyHint: true,
@@ -22837,7 +24380,7 @@ function buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path28.join(await getDocsDir2(), "sfcc");
+      const dir = path29.join(await getDocsDir2(), "sfcc");
       return saveAndReturn2(
         text,
         dir,
@@ -22869,7 +24412,7 @@ function buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path28.join(await getDocsDir2(), "sfcc");
+      const dir = path29.join(await getDocsDir2(), "sfcc");
       return saveAndReturn2(
         text,
         dir,
@@ -22901,7 +24444,7 @@ function registerSfccCustomObjectDefReadTools(registerTool2, deps) {
 }
 
 // src/sfcc/reads-site-preference.ts
-import path29 from "path";
+import path30 from "path";
 import { z as z5 } from "zod";
 var READ_ANNOTATIONS3 = {
   readOnlyHint: true,
@@ -22981,7 +24524,7 @@ function buildSitePreferenceGetHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path29.join(await getDocsDir2(), "sfcc");
+      const dir = path30.join(await getDocsDir2(), "sfcc");
       return saveAndReturn3(
         text,
         dir,
@@ -23015,7 +24558,7 @@ function buildSitePreferenceSearchHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path29.join(await getDocsDir2(), "sfcc");
+      const dir = path30.join(await getDocsDir2(), "sfcc");
       return saveAndReturn3(
         text,
         dir,
@@ -23044,7 +24587,7 @@ function buildSitePreferenceGroupListHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path29.join(await getDocsDir2(), "sfcc");
+      const dir = path30.join(await getDocsDir2(), "sfcc");
       return saveAndReturn3(
         text,
         dir,
@@ -23107,11 +24650,11 @@ function rejectIfNotSandboxForWrite(instance) {
 function textResult5(text) {
   return { content: [{ type: "text", text }] };
 }
-function formatOcapiWriteToolResult(result, operation, path33, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+function formatOcapiWriteToolResult(result, operation, path34, ocapiVersion = DEFAULT_OCAPI_VERSION) {
   if (result.status === 403) {
     return writeGrantForbiddenResult({
       operation,
-      path: path33,
+      path: path34,
       ocapiVersion,
       body: result.body
     });
@@ -23369,20 +24912,20 @@ function buildCreateAttributeDefinitionHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path33;
+      let path34;
       let body;
       try {
         const parsed = createAttributeDefinitionInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path33 = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+        path34 = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
         body = buildObjectAttributeDefinitionCreatePayload(parsed.attribute_id, parsed.definition);
       } catch (err) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPut(path33, body, credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path33);
+        const result = await ocapiPut(path34, body, credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path34);
       } catch {
         return unexpectedEnvelope();
       }
@@ -23393,20 +24936,20 @@ function buildUpdateAttributeDefinitionHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path33;
+      let path34;
       let body;
       try {
         const parsed = updateAttributeDefinitionInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path33 = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+        path34 = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
         body = buildObjectAttributeDefinitionPatchPayload(parsed.attribute_id, parsed.patch);
       } catch (err) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPatch(path33, body, credentials);
-        return formatOcapiWriteToolResult(result, "PATCH", path33);
+        const result = await ocapiPatch(path34, body, credentials);
+        return formatOcapiWriteToolResult(result, "PATCH", path34);
       } catch {
         return unexpectedEnvelope();
       }
@@ -23417,13 +24960,13 @@ function buildCreateAttributeGroupHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path33;
+      let path34;
       let body;
       try {
         const parsed = createAttributeGroupInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path33 = attributeGroupPath(parsed.object_type, parsed.group_id);
+        path34 = attributeGroupPath(parsed.object_type, parsed.group_id);
         body = buildAttributeGroupPutPayload({
           display_name: parsed.display_name,
           internal: parsed.internal
@@ -23432,8 +24975,8 @@ function buildCreateAttributeGroupHandler(gateDeps) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPut(path33, body, credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path33);
+        const result = await ocapiPut(path34, body, credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path34);
       } catch {
         return unexpectedEnvelope();
       }
@@ -23444,20 +24987,20 @@ function buildUpdateAttributeGroupHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path33;
+      let path34;
       let body;
       try {
         const parsed = updateAttributeGroupInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path33 = attributeGroupPath(parsed.object_type, parsed.group_id);
+        path34 = attributeGroupPath(parsed.object_type, parsed.group_id);
         body = buildAttributeGroupPatchPayload(parsed.patch);
       } catch (err) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPatch(path33, body, credentials);
-        return formatOcapiWriteToolResult(result, "PATCH", path33);
+        const result = await ocapiPatch(path34, body, credentials);
+        return formatOcapiWriteToolResult(result, "PATCH", path34);
       } catch {
         return unexpectedEnvelope();
       }
@@ -23468,12 +25011,12 @@ function buildAssignAttributeToGroupHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path33;
+      let path34;
       try {
         const parsed = assignAttributeToGroupInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path33 = attributeGroupAssignmentPath(
+        path34 = attributeGroupAssignmentPath(
           parsed.object_type,
           parsed.group_id,
           parsed.attribute_id
@@ -23482,8 +25025,8 @@ function buildAssignAttributeToGroupHandler(gateDeps) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPut(path33, buildEmptyRelationPayload(), credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path33);
+        const result = await ocapiPut(path34, buildEmptyRelationPayload(), credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path34);
       } catch {
         return unexpectedEnvelope();
       }
@@ -23494,21 +25037,21 @@ function buildCreateCustomPreferenceDefinitionHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path33;
+      let path34;
       let body;
       try {
         const parsed = createCustomPreferenceDefinitionInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
         const objectType = preferenceObjectTypeForScope(parsed.preference_scope);
-        path33 = attributeDefinitionPath(objectType, parsed.preference_id);
+        path34 = attributeDefinitionPath(objectType, parsed.preference_id);
         body = buildObjectAttributeDefinitionCreatePayload(parsed.preference_id, parsed.definition);
       } catch (err) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPut(path33, body, credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path33);
+        const result = await ocapiPut(path34, body, credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path34);
       } catch {
         return unexpectedEnvelope();
       }
@@ -23723,11 +25266,11 @@ function buildCreateCustomObjectAttributeDefinitionHandler(gateDeps) {
           `Body id '${parsed.definition.id}' does not match URL attribute_id '${parsed.attribute_id}'.`
         );
       }
-      const path33 = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+      const path34 = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
       const body = buildObjectAttributeDefinitionCreatePayload2(parsed.attribute_id, parsed.definition);
       try {
-        const result = await ocapiPut(path33, body, credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path33);
+        const result = await ocapiPut(path34, body, credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path34);
       } catch {
         return unexpectedEnvelope2();
       }
@@ -23746,11 +25289,11 @@ function buildUpdateCustomObjectAttributeDefinitionHandler(gateDeps) {
       }
       const guard = rejectIfNotSandboxForWrite(parsed.instance);
       if (guard) return guard;
-      const path33 = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+      const path34 = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
       const body = buildObjectAttributeDefinitionPatchPayload2(parsed.patch);
       try {
-        const result = await ocapiPatch(path33, body, credentials);
-        return formatOcapiWriteToolResult(result, "PATCH", path33);
+        const result = await ocapiPatch(path34, body, credentials);
+        return formatOcapiWriteToolResult(result, "PATCH", path34);
       } catch {
         return unexpectedEnvelope2();
       }
@@ -23841,11 +25384,11 @@ function buildSitePreferenceValuesSetHandler(gateDeps) {
       }
       const guard = rejectIfNotSandboxForWrite(parsed.instance);
       if (guard) return guard;
-      const path33 = sitePreferenceGroupPath(parsed.group);
+      const path34 = sitePreferenceGroupPath(parsed.group);
       const body = buildSitePreferenceValuesPatchPayload(parsed.values);
       try {
-        const result = await ocapiPatchDirect(path33, body, credentials);
-        return formatOcapiWriteToolResult(result, "PATCH", path33);
+        const result = await ocapiPatchDirect(path34, body, credentials);
+        return formatOcapiWriteToolResult(result, "PATCH", path34);
       } catch {
         return unexpectedEnvelope2();
       }
@@ -24314,27 +25857,21 @@ async function inspectEpicTickSchedule(deps, orchestrateListOverride) {
         backend: null,
         next_fire_iso: null,
         latest_run_status: null,
-        degraded: true,
-        warnings: [
-          "No epic-tick schedule is registered. Run: npx -y @bridge_gpt/mcp-server schedule-run create --in 1m --command epic-tick -- --epic-key <EPIC-KEY>"
-        ]
+        degraded: false,
+        warnings: []
       };
     }
     const m = entry.metadata;
     const latest = runStatus(m);
-    const degraded = entry.status !== "active";
-    const warnings = [];
-    if (degraded) {
-      const msg = entry.status === "backend-unavailable" ? `epic-tick schedule status is "backend-unavailable": the OS scheduler backend is unreachable. Check that the scheduler daemon is running.` : `epic-tick schedule status is "${entry.status}" (expected "active"); re-register if stale.`;
-      warnings.push(msg);
-    }
     return {
       registered: true,
       backend: m.backend ?? null,
       next_fire_iso: m.run_at_iso ?? null,
       latest_run_status: latest || null,
-      degraded,
-      warnings
+      degraded: true,
+      warnings: [
+        `An epic-tick schedule is registered, but the v1 \`conductor epic-tick\` path is frozen (EPIC_TICK_V1_FROZEN) \u2014 it advances nothing. Cancel it: \`npx -y @bridge_gpt/mcp-server schedule-run cancel --id ${entry.metadata.id ?? "<id>"}\`. Epic Conductor v2 reconciles server-side; run jobs locally with \`npx -y @bridge_gpt/mcp-server executor --repo <name>\`.`
+      ]
     };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -24480,19 +26017,25 @@ function formatConductorDoctorReport(report) {
     for (const w of git_hooks.warnings) lines.push(`  - ${w}`);
   }
   lines.push("");
-  lines.push("Epic Supervisor Schedule (optional, local)");
-  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-  const registeredTag = epic_tick.registered ? "[SUCCESS] registered" : "[WARNING] not registered";
-  lines.push(`registered:            ${registeredTag}`);
-  lines.push(`backend:               ${epic_tick.backend ?? "n/a"}`);
-  lines.push(`next fire:             ${epic_tick.next_fire_iso ?? "n/a"}`);
-  lines.push(`latest run status:     ${epic_tick.latest_run_status ?? "n/a"}`);
+  lines.push("Epic Supervisor Schedule (v1 epic-tick \u2014 frozen)");
+  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  const registeredTag = epic_tick.registered ? "[WARNING] registered \u2014 dead timer, remove it" : "[SUCCESS] none registered (v1 is frozen)";
+  lines.push(`epic-tick schedule:    ${registeredTag}`);
+  if (epic_tick.registered) {
+    lines.push(`backend:               ${epic_tick.backend ?? "n/a"}`);
+    lines.push(`next fire:             ${epic_tick.next_fire_iso ?? "n/a"}`);
+    lines.push(`latest run status:     ${epic_tick.latest_run_status ?? "n/a"}`);
+  }
   lines.push(`degraded:              ${epic_tick.degraded}`);
   if (epic_tick.warnings.length > 0) {
     lines.push("epic-tick warnings:");
     for (const w of epic_tick.warnings) lines.push(`  - ${w}`);
   }
   lines.push("");
+  lines.push("Epic Conductor v2 reconciles epics server-side \u2014 nothing to schedule");
+  lines.push("locally. To execute claimed jobs on this machine, run:");
+  lines.push("  npx -y @bridge_gpt/mcp-server executor --repo <name>");
+  lines.push("");
   lines.push("MCP Profile (optional, local)");
   lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   const profileTag = mcp_profile.degraded ? "[WARNING] degraded" : "[OK]";
@@ -25513,7 +27056,7 @@ var DecisionPageLeanInputShape = {
 
 // src/brainstorm-files.ts
 import { writeFile as writeFile11, mkdir as mkdir11 } from "fs/promises";
-import path30 from "path";
+import path31 from "path";
 function slugify(text, maxLength = 60) {
   return text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-").slice(0, maxLength).replace(/-$/, "");
 }
@@ -25538,7 +27081,7 @@ async function saveBrainstormResultsToDir(envelope, dir, subject) {
       continue;
     }
     const filename = buildBrainstormResultFilename(envelope, row, subject);
-    const filePath = path30.join(dir, filename);
+    const filePath = path31.join(dir, filename);
     try {
       await mkdir11(dir, { recursive: true });
       await writeFile11(filePath, markdown, "utf-8");
@@ -25550,10 +27093,10 @@ async function saveBrainstormResultsToDir(envelope, dir, subject) {
 }
 
 // src/pipeline-orchestrator.ts
-import { createHash as createHash6 } from "node:crypto";
+import { createHash as createHash7 } from "node:crypto";
 function deriveIdeaHash(idea) {
   const normalized = String(idea ?? "").trim().toLowerCase().replace(/\s+/g, " ");
-  return createHash6("sha256").update(normalized).digest("hex").slice(0, 12);
+  return createHash7("sha256").update(normalized).digest("hex").slice(0, 12);
 }
 var PipelinePersistenceError = class extends Error {
   code;
@@ -27287,7 +28830,7 @@ async function resumeFullAutomation(deps, input) {
 }
 
 // src/visual-diff.ts
-import path31 from "path";
+import path32 from "path";
 import { Worker } from "worker_threads";
 
 // src/visual-diff-worker.ts
@@ -27659,12 +29202,12 @@ function toUint8(bytes) {
 }
 async function resolveCompRef(compRef, deps) {
   const candidates = [];
-  if (path31.isAbsolute(compRef)) {
+  if (path32.isAbsolute(compRef)) {
     candidates.push(compRef);
   } else {
     const root = await deps.getProjectRoot();
-    candidates.push(path31.resolve(root, compRef));
-    const cwdCandidate = path31.resolve(process.cwd(), compRef);
+    candidates.push(path32.resolve(root, compRef));
+    const cwdCandidate = path32.resolve(process.cwd(), compRef);
     if (!candidates.includes(cwdCandidate)) candidates.push(cwdCandidate);
   }
   for (const candidate of candidates) {
@@ -27688,9 +29231,9 @@ async function resolveCompRef(compRef, deps) {
   try {
     const dir = await deps.getDocsPath("visual-diffs");
     const rawName = fetched.filename || (lookup.kind === "attachment_id" ? `attachment-${lookup.attachment_id}` : lookup.filename);
-    const base = path31.basename(rawName);
-    const target = path31.resolve(dir, `comp-${deps.safeTimestampForFilename()}-${base}`);
-    if (!target.startsWith(path31.resolve(dir) + path31.sep)) {
+    const base = path32.basename(rawName);
+    const target = path32.resolve(dir, `comp-${deps.safeTimestampForFilename()}-${base}`);
+    if (!target.startsWith(path32.resolve(dir) + path32.sep)) {
       warnings.push("Skipped saving attachment comp copy: resolved path escaped the visual-diffs directory.");
     } else {
       await deps.mkdir(dir, { recursive: true });
@@ -27933,8 +29476,8 @@ function runInWorker(args) {
 async function saveHeatmap(heatmapBase64, deps) {
   try {
     const dir = await deps.getDocsPath("visual-diffs");
-    const target = path31.resolve(dir, `visual-diff-${deps.safeTimestampForFilename()}.png`);
-    if (!target.startsWith(path31.resolve(dir) + path31.sep)) {
+    const target = path32.resolve(dir, `visual-diff-${deps.safeTimestampForFilename()}.png`);
+    if (!target.startsWith(path32.resolve(dir) + path32.sep)) {
       return { ok: false, warning: "Heatmap not saved: resolved path escaped the visual-diffs directory." };
     }
     await deps.mkdir(dir, { recursive: true });
@@ -28135,7 +29678,7 @@ async function getResolvedApiKey() {
       try {
         const result = await resolveBapiCredentials(REPO_NAME, {
           env: process.env,
-          homedir: os14.homedir,
+          homedir: os15.homedir,
           platform: process.platform,
           readFile: (p) => readFile13(p, "utf-8"),
           stat: (p) => stat9(p)
@@ -28152,7 +29695,7 @@ async function getResolvedApiKeyForRepo(repoName) {
   try {
     const result = await resolveBapiCredentials(repoName, {
       env: process.env,
-      homedir: os14.homedir,
+      homedir: os15.homedir,
       platform: process.platform,
       readFile: (p) => readFile13(p, "utf-8"),
       stat: (p) => stat9(p)
@@ -28165,14 +29708,24 @@ async function getResolvedApiKeyForRepo(repoName) {
 function buildCredentialStoreWriteDeps() {
   return {
     env: process.env,
-    homedir: os14.homedir,
+    homedir: os15.homedir,
     platform: process.platform,
     readFile: (p) => readFile13(p, "utf-8"),
     mkdir: (p, options) => mkdir12(p, options),
     writeFile: (p, data, options) => writeFile12(p, data, options),
     rename: (oldPath, newPath) => rename3(oldPath, newPath),
     chmod: (p, mode) => chmod3(p, mode),
-    unlink: (p) => unlink3(p)
+    unlink: (p) => unlink3(p),
+    // Supplies fsync + the exclusive lock (BAPI-606), so an MCP-triggered write
+    // cannot last-writer-win against a concurrent install-bridge run.
+    open: async (p, flags, mode) => {
+      const handle = await open2(p, flags, mode);
+      return {
+        writeFile: (data) => handle.writeFile(data, { encoding: "utf-8" }),
+        sync: () => handle.sync(),
+        close: () => handle.close()
+      };
+    }
   };
 }
 async function getGetHeaders() {
@@ -28226,39 +29779,39 @@ async function getProjectRoot() {
 var docsDirPromise;
 async function getDocsDir() {
   if (!docsDirPromise) {
-    docsDirPromise = (async () => path32.resolve(await getProjectRoot(), process.env.BAPI_DOCS_DIR ?? "docs/tmp"))();
+    docsDirPromise = (async () => path33.resolve(await getProjectRoot(), process.env.BAPI_DOCS_DIR ?? "docs/tmp"))();
   }
   return docsDirPromise;
 }
 var pipelinesDirPromise;
 async function getPipelinesDir() {
   if (!pipelinesDirPromise) {
-    pipelinesDirPromise = (async () => path32.resolve(await getProjectRoot(), process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines"))();
+    pipelinesDirPromise = (async () => path33.resolve(await getProjectRoot(), process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines"))();
   }
   return pipelinesDirPromise;
 }
-function buildUrl(path33) {
-  return `${BASE_URL.replace(/\/+$/, "")}/jira${path33}`;
+function buildUrl(path34) {
+  return `${BASE_URL.replace(/\/+$/, "")}/jira${path34}`;
 }
-function buildApiUrl(path33) {
-  return `${BASE_URL.replace(/\/+$/, "")}${path33}`;
+function buildApiUrl(path34) {
+  return `${BASE_URL.replace(/\/+$/, "")}${path34}`;
 }
-function buildGetUrl(path33, params) {
-  const url = new URL(buildUrl(path33));
+function buildGetUrl(path34, params) {
+  const url = new URL(buildUrl(path34));
   for (const [key, value] of Object.entries(params)) {
     url.searchParams.set(key, value);
   }
   return url.toString();
 }
 async function getDocsPath(subdir) {
-  return path32.join(await getDocsDir(), subdir);
+  return path33.join(await getDocsDir(), subdir);
 }
 var customPipelinesPromise;
 async function ensureCustomPipelinesLoaded() {
   if (!customPipelinesPromise) {
     customPipelinesPromise = (async () => {
       const pipelinesDir = await getPipelinesDir();
-      const instructionsDir = path32.join(path32.dirname(pipelinesDir), "instructions");
+      const instructionsDir = path33.join(path33.dirname(pipelinesDir), "instructions");
       const customResult = await loadCustomPipelines(
         pipelinesDir,
         instructionsDir,
@@ -28343,7 +29896,7 @@ async function createTicketRequest(params) {
   return handleResponse(resp);
 }
 async function saveLocally(dir, filename, content) {
-  const filePath = path32.join(dir, filename);
+  const filePath = path33.join(dir, filename);
   try {
     await mkdir12(dir, { recursive: true });
     await writeFile12(filePath, content, "utf-8");
@@ -28363,14 +29916,14 @@ function safeTimestampForFilename() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 }
 function safeTicketFileSegment(ticketNumber) {
-  const base = path32.basename(ticketNumber.trim());
+  const base = path33.basename(ticketNumber.trim());
   const cleaned = base.replace(/[^A-Za-z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
   return cleaned || "ticket";
 }
 function isContainedSaveTarget(dir, filename) {
-  const resolvedDir = path32.resolve(dir);
-  const target = path32.resolve(resolvedDir, filename);
-  return target.startsWith(resolvedDir + path32.sep);
+  const resolvedDir = path33.resolve(dir);
+  const target = path33.resolve(resolvedDir, filename);
+  return target.startsWith(resolvedDir + path33.sep);
 }
 function saveLocallySucceeded(note) {
   return note.includes("Saved to ");
@@ -28479,7 +30032,7 @@ var ALLOWED_BINARY_UPLOAD_MIME_TYPES = Array.from(
   new Set(Object.values(ALLOWED_BINARY_UPLOAD_MIME_BY_EXTENSION))
 ).sort();
 function deriveAllowedBinaryUploadMimeType(effectiveFileName) {
-  const ext = path32.extname(effectiveFileName).toLowerCase();
+  const ext = path33.extname(effectiveFileName).toLowerCase();
   return ALLOWED_BINARY_UPLOAD_MIME_BY_EXTENSION[ext];
 }
 async function resolveUploadAttachment(textValue, filePath, textLabel, effectiveFileName) {
@@ -28510,7 +30063,7 @@ async function resolveUploadAttachment(textValue, filePath, textLabel, effective
         }
       };
     }
-    const ext = path32.extname(filePath).toLowerCase();
+    const ext = path33.extname(filePath).toLowerCase();
     const buf = await readFile13(filePath);
     let isBinary = BINARY_EXTENSIONS.has(ext);
     if (!isBinary) {
@@ -28885,7 +30438,7 @@ Raw body: ${result.text}`
 }
 async function ensurePackageJsonForCliCommand(flagName, cwd) {
   try {
-    await stat9(path32.join(cwd, "package.json"));
+    await stat9(path33.join(cwd, "package.json"));
     return null;
   } catch {
     return `Error: No package.json found in current directory.
@@ -28933,6 +30486,9 @@ async function dispatchCliSubcommand(argv) {
   if (argv[0] === "executor") {
     return runExecutorCli(argv.slice(1));
   }
+  if (argv[0] === "setup-epic") {
+    return runSetupEpicCli(argv.slice(1));
+  }
   if (argv[0] === "regression-check") {
     return runRegressionCheckCli(argv.slice(1));
   }
@@ -29846,7 +31402,7 @@ registerTool(
     switch (args.operation) {
       case "upload": {
         const { ticket_number, file_path, content, file_name, link_type, replace_existing } = args;
-        const derivedFileName = file_name || (file_path ? path32.basename(file_path) : `${ticket_number}-attachment.md`);
+        const derivedFileName = file_name || (file_path ? path33.basename(file_path) : `${ticket_number}-attachment.md`);
         const resolved = await resolveUploadAttachment(content, file_path, "content", derivedFileName);
         if (!resolved.ok) return resolved.errorResponse;
         const payload = {
@@ -29906,12 +31462,12 @@ registerTool(
         const isText = body.is_text;
         const mimeType = body.mime_type;
         const size = body.size;
-        const safeFileName = path32.basename(serverFilename);
-        const safeTicket = path32.basename(ticket_number);
-        const savePath = file_path ? file_path : path32.join(await getDocsDir(), "attachments", safeTicket, safeFileName);
-        const resolvedSave = path32.resolve(savePath);
-        const resolvedRoot = path32.resolve(await getProjectRoot());
-        if (!resolvedSave.startsWith(resolvedRoot + path32.sep) && resolvedSave !== resolvedRoot) {
+        const safeFileName = path33.basename(serverFilename);
+        const safeTicket = path33.basename(ticket_number);
+        const savePath = file_path ? file_path : path33.join(await getDocsDir(), "attachments", safeTicket, safeFileName);
+        const resolvedSave = path33.resolve(savePath);
+        const resolvedRoot = path33.resolve(await getProjectRoot());
+        if (!resolvedSave.startsWith(resolvedRoot + path33.sep) && resolvedSave !== resolvedRoot) {
           return {
             content: [{
               type: "text",
@@ -29922,7 +31478,7 @@ registerTool(
             }]
           };
         }
-        await mkdir12(path32.dirname(resolvedSave), { recursive: true });
+        await mkdir12(path33.dirname(resolvedSave), { recursive: true });
         if (isText) {
           await writeFile12(resolvedSave, content, "utf-8");
         } else {
@@ -31554,7 +33110,7 @@ registerTool(
 var REVIEW_WORKSPACE_PREFIX = "bridge-review-";
 var REVIEW_WORKSPACE_TTL_MS = 24 * 60 * 60 * 1e3;
 async function pruneStaleReviewWorkspaces() {
-  const tmpDir = os14.tmpdir();
+  const tmpDir = os15.tmpdir();
   let entries;
   try {
     entries = await readdir3(tmpDir);
@@ -31564,7 +33120,7 @@ async function pruneStaleReviewWorkspaces() {
   const now = Date.now();
   for (const entry of entries) {
     if (!entry.startsWith(REVIEW_WORKSPACE_PREFIX)) continue;
-    const fullPath = path32.join(tmpDir, entry);
+    const fullPath = path33.join(tmpDir, entry);
     try {
       const info = await stat9(fullPath);
       if (now - info.mtimeMs > REVIEW_WORKSPACE_TTL_MS) {
@@ -31669,7 +33225,7 @@ registerTool(
     }
     let tempDir;
     try {
-      tempDir = await mkdtemp3(path32.join(os14.tmpdir(), REVIEW_WORKSPACE_PREFIX));
+      tempDir = await mkdtemp3(path33.join(os15.tmpdir(), REVIEW_WORKSPACE_PREFIX));
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       return {
@@ -31683,7 +33239,7 @@ registerTool(
         }]
       };
     }
-    const archivePath = path32.join(tempDir, "archive.tar");
+    const archivePath = path33.join(tempDir, "archive.tar");
     const archiveResult = await startTicketsDeps.runCommand(
       "git",
       ["archive", "--format=tar", resolvedBaseSha, "-o", archivePath],
@@ -31755,11 +33311,11 @@ registerTool(
     }
   },
   async ({ fresh_base_root }) => {
-    const allowedPrefix = path32.join(os14.tmpdir(), REVIEW_WORKSPACE_PREFIX);
-    const resolvedTarget = path32.resolve(fresh_base_root);
-    const resolvedTmpDir = path32.resolve(os14.tmpdir());
-    const isDirectChildOfTmpDir = path32.dirname(resolvedTarget) === resolvedTmpDir;
-    const hasReviewPrefix = path32.basename(resolvedTarget).startsWith(REVIEW_WORKSPACE_PREFIX);
+    const allowedPrefix = path33.join(os15.tmpdir(), REVIEW_WORKSPACE_PREFIX);
+    const resolvedTarget = path33.resolve(fresh_base_root);
+    const resolvedTmpDir = path33.resolve(os15.tmpdir());
+    const isDirectChildOfTmpDir = path33.dirname(resolvedTarget) === resolvedTmpDir;
+    const hasReviewPrefix = path33.basename(resolvedTarget).startsWith(REVIEW_WORKSPACE_PREFIX);
     if (!isDirectChildOfTmpDir || !hasReviewPrefix) {
       return {
         content: [{
@@ -32007,7 +33563,7 @@ function containsUnsafeEncodedPathToken(value) {
   return /%2e/i.test(value) || /%2f/i.test(value) || /%5c/i.test(value);
 }
 function isPlatformAbsolutePath(value) {
-  return path32.posix.isAbsolute(value) || path32.win32.isAbsolute(value) || path32.isAbsolute(value);
+  return path33.posix.isAbsolute(value) || path33.win32.isAbsolute(value) || path33.isAbsolute(value);
 }
 function validateDecisionPageOutputSubdir(value) {
   if (value.trim().length === 0) {
@@ -32057,9 +33613,9 @@ async function resolveDecisionPageOutputTarget(outputSubdir, outputFilename) {
   if (subdirError) return { ok: false, message: subdirError };
   const filenameError = validateDecisionPageOutputFilename(outputFilename);
   if (filenameError) return { ok: false, message: filenameError };
-  const docsBase = path32.resolve(await getDocsDir());
-  const resolvedTarget = path32.resolve(docsBase, outputSubdir, outputFilename);
-  if (!resolvedTarget.startsWith(docsBase + path32.sep)) {
+  const docsBase = path33.resolve(await getDocsDir());
+  const resolvedTarget = path33.resolve(docsBase, outputSubdir, outputFilename);
+  if (!resolvedTarget.startsWith(docsBase + path33.sep)) {
     return {
       ok: false,
       message: `Invalid output target: the resolved output path must stay under the docs directory.`
@@ -32067,7 +33623,7 @@ async function resolveDecisionPageOutputTarget(outputSubdir, outputFilename) {
   }
   return {
     ok: true,
-    docsPath: path32.dirname(resolvedTarget),
+    docsPath: path33.dirname(resolvedTarget),
     filePath: resolvedTarget
   };
 }
@@ -32155,36 +33711,36 @@ registerTool(
       return validationError(outputTarget.message);
     }
     const projectRootForAssets = await getProjectRoot();
-    const pkgRoot = path32.resolve(path32.dirname(fileURLToPath3(import.meta.url)), "../");
+    const pkgRoot = path33.resolve(path33.dirname(fileURLToPath3(import.meta.url)), "../");
     let assetsDir;
     try {
-      await stat9(path32.join(projectRootForAssets, "design-assets"));
-      assetsDir = path32.join(projectRootForAssets, "design-assets");
+      await stat9(path33.join(projectRootForAssets, "design-assets"));
+      assetsDir = path33.join(projectRootForAssets, "design-assets");
     } catch {
-      assetsDir = path32.join(pkgRoot, "design-assets");
+      assetsDir = path33.join(pkgRoot, "design-assets");
     }
     let fontsDir;
     try {
-      await stat9(path32.join(projectRootForAssets, "public", "fonts"));
-      fontsDir = path32.join(projectRootForAssets, "public", "fonts");
+      await stat9(path33.join(projectRootForAssets, "public", "fonts"));
+      fontsDir = path33.join(projectRootForAssets, "public", "fonts");
     } catch {
-      fontsDir = path32.join(pkgRoot, "public", "fonts");
+      fontsDir = path33.join(pkgRoot, "public", "fonts");
     }
     let faviconBase64 = "";
     let logoBase64 = "";
     try {
-      const faviconBuf = await readFile13(path32.join(assetsDir, "favicon", "favicon-32x32.png"));
+      const faviconBuf = await readFile13(path33.join(assetsDir, "favicon", "favicon-32x32.png"));
       faviconBase64 = faviconBuf.toString("base64");
     } catch {
     }
     try {
-      const logoBuf = await readFile13(path32.join(assetsDir, "just-logo-rough-draft.png"));
+      const logoBuf = await readFile13(path33.join(assetsDir, "just-logo-rough-draft.png"));
       logoBase64 = logoBuf.toString("base64");
     } catch {
     }
     const docsPath = outputTarget.docsPath;
     const filePath = outputTarget.filePath;
-    const fontsRelPath = path32.relative(docsPath, fontsDir);
+    const fontsRelPath = path33.relative(docsPath, fontsDir);
     const html = generateDecisionPageHtml(parsed, {
       faviconBase64,
       logoBase64,