@bridge_gpt/mcp-server 0.2.49 → 0.2.50

package/build/stale-worktree-doctor.js

@@ -0,0 +1,120 @@
+/**
+ * Read-only stale-branch diagnostic (BAPI-948).
+ *
+ * `start-tickets --guard-stale-branch` (and `--conductor`, which implies it) refuses
+ * to reuse a pre-existing `feature/<KEY>` branch whose tip is not an ancestor of the
+ * resolved base. That refusal is correct but it only tells you AFTER you tried to cut
+ * the worktree. This module answers the same question BEFORE the cut, and without
+ * touching a single ref.
+ *
+ * It owns no ancestry logic of its own. `branchExists` and
+ * `isExistingBranchSafeToReuse` from `./worktree-core.js` are the exact predicates the
+ * guard itself runs, so a `would-refuse` finding here and a `create-failed` row there
+ * can never disagree — and the operator sentence is the same sentence in both places.
+ * Deliberately NOT a second ahead-count / diff / merge-base implementation: a
+ * diagnostic that re-derives the condition is a diagnostic that can be wrong about it.
+ *
+ * Strictly read-only. The only commands it can reach are the two the predicates issue
+ * — `git show-ref --verify --quiet`, `git rev-parse --verify --quiet`, and
+ * `git merge-base --is-ancestor` — none of which mutate anything. There is no fetch,
+ * reset, switch, checkout, branch deletion, or worktree creation on any path here, and
+ * nothing in this module writes a file.
+ */
+import { branchExists, isExistingBranchSafeToReuse } from "./worktree-core.js";
+/**
+ * The one sentence an `indeterminate` finding renders. Fixed text: the underlying
+ * throw is swallowed rather than formatted, so no probe failure can smuggle command
+ * output into a report.
+ */
+export const STALE_WORKTREE_INDETERMINATE_REASON = "the read-only branch check could not complete (git was unavailable or failed to run); " +
+    "re-run the diagnostic, or inspect the branch by hand with " +
+    "`git merge-base --is-ancestor <branch> <base>`.";
+/**
+ * Diagnose each target independently, read-only.
+ *
+ * Independence is the point: one unreadable branch must not blank out its siblings'
+ * findings, which is why every target is wrapped on its own rather than the loop as a
+ * whole. Targets are evaluated in the order given so the rendered report is stable.
+ */
+export async function diagnoseStaleWorktreeBranches(deps, targets) {
+    const findings = [];
+    for (const target of targets) {
+        const { key, branch, baseStartPoint } = target;
+        try {
+            // No local branch → nothing pre-existing for the guard to act on. Return before
+            // the ancestry probe: running it would be a wasted command AND would produce a
+            // "not an ancestor" reason about a branch that is not there.
+            if (!(await branchExists(deps, branch))) {
+                findings.push({ key, branch, baseStartPoint, status: "branch-absent" });
+                continue;
+            }
+            // The SAME predicate `createWorktreeForTicket` runs, with the same branch and
+            // the same base start point, so the verdict and its remedy are identical to the
+            // refusal the guarded cut would emit.
+            const safety = await isExistingBranchSafeToReuse(deps, branch, baseStartPoint);
+            if (safety.safe) {
+                findings.push({ key, branch, baseStartPoint, status: "safe" });
+                continue;
+            }
+            findings.push({
+                key,
+                branch,
+                baseStartPoint,
+                status: "would-refuse",
+                reason: safety.reason,
+            });
+        }
+        catch {
+            findings.push({
+                key,
+                branch,
+                baseStartPoint,
+                status: "indeterminate",
+                reason: STALE_WORKTREE_INDETERMINATE_REASON,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Render the advisory section. Advisory in the strict doctor sense: the caller never
+ * derives an exit code from it.
+ *
+ * One row per target, each naming the ticket, the resolved branch, and the base it was
+ * measured against — an operator diagnosing an epic cut needs all three to act. A
+ * `WOULD REFUSE` row is followed by the predicate's remedy on its own indented line
+ * rather than being folded into the row, because that sentence is the thing the
+ * operator has to read.
+ */
+export function formatStaleWorktreeDiagnosticReport(findings) {
+    const lines = ["", "Stale ticket branches (advisory)"];
+    if (findings.length === 0) {
+        lines.push("  SKIP     No --stale-branch targets supplied; nothing was checked.");
+        return lines.join("\n");
+    }
+    for (const finding of findings) {
+        const where = `${finding.key}: ${finding.branch} vs ${finding.baseStartPoint}`;
+        switch (finding.status) {
+            case "branch-absent":
+                lines.push(`  OK       ${where} — no local branch; a fresh one is cut from the base.`);
+                break;
+            case "safe":
+                lines.push(`  OK       ${where} — branch is an ancestor of the base; safe to reuse.`);
+                break;
+            case "would-refuse":
+                lines.push(`  WARN     ${where} — WOULD REFUSE.`);
+                if (finding.reason)
+                    lines.push(`           ${finding.reason}`);
+                break;
+            case "indeterminate":
+                lines.push(`  WARN     ${where} — indeterminate.`);
+                if (finding.reason)
+                    lines.push(`           ${finding.reason}`);
+                break;
+        }
+    }
+    lines.push("           Read-only: this section reads current local refs only. It never fetches,");
+    lines.push("           resets, switches, deletes, or repairs any git state, and never changes the");
+    lines.push("           exit code.");
+    return lines.join("\n");
+}

package/build/start-tickets-prereqs.js

@@ -19,6 +19,11 @@ import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
 import { probeWorktreeCommandAssets } from "./command-assets-doctor.js";
 import { MCP_SERVER_NAME, MCP_PACKAGE_NAME } from "./mcp-identity.js";
+// BAPI-941: both are LEAF modules (the pure classifier and its git-backed
+// acquisition), so importing them here cannot close a cycle with `base-ref.ts`,
+// which imports `commandSucceeded` from this module.
+import { CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION, CLAUDE_REVIEW_WORKFLOW_RELPATH, summarizeClaudeReviewWorkflowDrift, } from "./claude-review-workflow-drift.js";
+import { probeClaudeReviewWorkflowDrift, resolveCurrentBranch, resolveRepositoryDefaultBranch, } from "./claude-review-workflow-drift-probe.js";
 import { CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND, claudeMcpShadowingRemediationCommand, formatClaudeMcpShadowFinding, formatClaudeUserConfigDiagnostic, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "./claude-user-config-doctor.js";
 // ---------------------------------------------------------------------------
 // Constants (moved here from start-tickets.ts so both consumers share them)
@@ -717,6 +722,67 @@ export function liveSourceGuardDescriptor() {
         },
     };
 }
+/** Secret-free remediation hint for the workflow-drift diagnostic. */
+const CLAUDE_REVIEW_WORKFLOW_DRIFT_INSTALL_HINTS = {
+    darwin: CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION,
+    linux: CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION,
+    win32: CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION,
+};
+/**
+ * BAPI-941 doctor-only, strictly read-only probe: does the current branch's copy
+ * of the reviewed workflow match the repository default branch's copy?
+ *
+ * Answers, without spawning a worker or creating a worktree, the question that
+ * otherwise only surfaces an hour into a conductor run: has this branch gone
+ * blind to automated code review? `anthropics/claude-code-action` refuses to run
+ * when the invoking workflow differs from the default branch's copy, and a
+ * long-lived `epic/**` branch inherits that staleness into every pull request
+ * based on it — while the pull requests themselves change no workflow file at
+ * all, so no path-based guard fires.
+ *
+ * **Read-only, and network-free.** It runs `git symbolic-ref`, `git rev-parse`,
+ * and two `git show` invocations against the local object database. It never
+ * fetches, checks out, installs, migrates, creates a worktree, or writes a
+ * credential.
+ *
+ * **Never blocking.** `doctor`'s exit code is
+ * `results.some((r) => !r.found) ? 1 : 0`, so this probe reports `found: true`
+ * for ALL THREE outcomes and carries the state in `detail`. Confirmed drift is an
+ * advisory an operator should act on, not a missing prerequisite that fails the
+ * command — and an unavailable comparison is uncertainty, which is even less of
+ * a fault. Registered in `getDoctorOnlyPrereqDescriptors`, never in
+ * `getPreflightPrereqDescriptors`.
+ *
+ * **Bounded output.** Every rendered string comes from the shared classifier's
+ * closed vocabulary plus refs and the workflow path. Subprocess stderr, GitHub
+ * exception text, and file content never reach the report.
+ */
+export function claudeReviewWorkflowDriftDescriptor() {
+    return {
+        id: "claude-review-workflow-drift",
+        label: "claude-review workflow lineage",
+        installHint: CLAUDE_REVIEW_WORKFLOW_DRIFT_INSTALL_HINTS,
+        probe: async (deps) => {
+            const probeDeps = { runCommand: deps.runCommand, cwd: deps.cwd };
+            const baseRef = await resolveCurrentBranch(probeDeps);
+            if (!baseRef) {
+                // A detached HEAD has no branch whose lineage to report. Inconclusive,
+                // not a fault.
+                return {
+                    found: true,
+                    detail: `comparison unavailable (base_ref_unresolved) — advisory check failed open, ` +
+                        `${CLAUDE_REVIEW_WORKFLOW_RELPATH} lineage unknown`,
+                };
+            }
+            const defaultRef = await resolveRepositoryDefaultBranch(probeDeps);
+            const classification = await probeClaudeReviewWorkflowDrift(probeDeps, {
+                baseRef,
+                defaultRef,
+            });
+            return { found: true, detail: summarizeClaudeReviewWorkflowDrift(classification) };
+        },
+    };
+}
 /**
  * The exact existing live-preflight requirement set per platform, plus the git
  * work-tree custom check appended after the command checks. This is the ONLY
@@ -765,6 +831,10 @@ export function getDoctorOnlyPrereqDescriptors(_platform, _env, agent) {
         reviewTicketsGitDescriptor(),
         liveSourceGuardDescriptor(),
         claudeMcpShadowingDescriptor(),
+        // BAPI-941: advisory workflow-lineage diagnostic. Doctor-only by design —
+        // adding it to `getPreflightPrereqDescriptors` would make a stale base
+        // branch block worktree creation, which is the opposite of fail-open.
+        claudeReviewWorkflowDriftDescriptor(),
     ];
 }
 /**

package/build/start-tickets.js

@@ -60,6 +60,9 @@ import path from "path";
 import { VERSION } from "./version.generated.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+// BAPI-941: the shared drift diagnostic formatter. The leaf drift module imports
+// nothing from here, so this direction stays acyclic.
+import { formatClaudeReviewWorkflowDriftDiagnostic } from "./claude-review-workflow-drift.js";
 import { resolveStartTicketsRepoName as resolveSharedStartTicketsRepoName, resolveRequiredStartTicketsRepoName, } from "./start-tickets-repo.js";
 import { provisionMcpRegistrationsForCreatedWorktrees, } from "./mcp-provisioning.js";
 import { provisionCommandsForCreatedWorktrees, } from "./command-provisioning.js";
@@ -132,7 +135,8 @@ export function getStartTicketsUsage() {
         "  --base-branch BRANCH        Cut new worktrees from BRANCH and refresh origin/BRANCH (default: main)",
         "  --no-refresh-main           Skip refresh of the configured base branch (default main); historical name retained for backward compatibility",
         "  --max-parallel N            Max worktrees to create concurrently (default: 3)",
-        "  --conductor                 Enable the Conductor system: per-worker hook injection + BAPI_CONDUCTOR_* env, lifecycle ledger events, and a supervisor peer tab (default: off — a plain run just spawns cd <worktree> && <agent> '/implement-ticket <KEY>')",
+        "  --conductor                 Enable the Conductor system: per-worker hook injection + BAPI_CONDUCTOR_* env, lifecycle ledger events, and a supervisor peer tab (default: off — a plain run just spawns cd <worktree> && <agent> '/implement-ticket <KEY>'). Implies --guard-stale-branch: a pre-existing ticket branch carrying commits beyond the resolved base is refused, not silently reused.",
+        "  --guard-stale-branch        Refuse to reuse a pre-existing feature/KEY branch whose tip is NOT an ancestor of the resolved base (it carries commits the base does not). The ticket is reported create-failed with the stale-worktree remedy instead of spawning a worker on leftover code. Implied by --conductor; pass it explicitly on the LLM-conductor pilot cut path. Off by default, so a plain interactive run keeps reusing a same-named branch.",
         "  -h, --help                  Show this help",
         "",
         "Environment:",
@@ -176,6 +180,11 @@ export function parseStartTicketsArgs(argv) {
     let agentName = DEFAULT_AGENT_NAME;
     let baseBranch = "main";
     let conductorEnabled = false;
+    // BAPI-948: `--guard-stale-branch` (and `--conductor`, which implies it) opt the
+    // packaged CLI into the F7 stale-branch guard. Tracked separately from
+    // `conductorEnabled` so the pilot can take the safety check WITHOUT taking the
+    // v2 conductor context that `--conductor` also switches on.
+    let guardStaleBranch = false;
     let workflow = "implement";
     let reviewRoundsRaw;
     // BAPI-642 `--tier` override. `undefined` = flag absent (property omitted from
@@ -358,6 +367,10 @@ export function parseStartTicketsArgs(argv) {
             conductorEnabled = true;
             continue;
         }
+        if (arg === "--guard-stale-branch") {
+            guardStaleBranch = true;
+            continue;
+        }
         if (arg === "--no-refresh-main") {
             refreshMain = false;
             continue;
@@ -454,6 +467,11 @@ export function parseStartTicketsArgs(argv) {
             conductorEnabled,
             workflow,
             reviewRounds,
+            // BAPI-948: include `guardStaleWorktree` ONLY when the run asked for the F7
+            // guard — `--guard-stale-branch`, or `--conductor` which implies it. A plain
+            // interactive invocation leaves the property entirely absent (not `false`),
+            // so the reuse-friendly human option shape is byte-identical to before.
+            ...(guardStaleBranch || conductorEnabled ? { guardStaleWorktree: true } : {}),
             // BAPI-642: include the injected-tier property ONLY when `--tier` was
             // supplied, so an omitted flag leaves the legacy option shape untouched
             // (no own `injectedTier` key, not even `undefined`).
@@ -834,9 +852,23 @@ export async function refreshBaseBranch(deps, options) {
         return { ok: true };
     const baseBranch = options.baseBranch;
     const originRef = `origin/${baseBranch}`;
-    const fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
+    // BAPI-941: refresh the DEFAULT branch alongside the base in ONE invocation so
+    // the caller's workflow-drift advisory reads an up-to-date `origin/<default>`
+    // without a second network round trip. Deduplicated when they are the same
+    // branch, and retried without the extra refspec on failure so this enrichment
+    // can never convert a working refresh into an error.
+    const defaultBranch = await resolveRepositoryDefaultBranch(deps);
+    const extraRefs = defaultBranch && defaultBranch !== baseBranch && validateBranchName(defaultBranch) === null
+        ? [defaultBranch]
+        : [];
+    let fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch, ...extraRefs], {
         cwd: deps.cwd,
     });
+    if (!commandSucceeded(fetch) && extraRefs.length > 0) {
+        fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
+            cwd: deps.cwd,
+        });
+    }
     if (!commandSucceeded(fetch)) {
         return {
             ok: false,
@@ -934,12 +966,49 @@ export async function runWithConcurrency(items, limit, worker) {
 // same function references.
 import { resolveBranchForTicket, branchExists, buildWtSwitchArgs, pathApiForPlatform, extractWorktreePath, isExistingBranchSafeToReuse, createWorktreeForTicket, } from "./worktree-core.js";
 export { resolveBranchForTicket, branchExists, buildWtSwitchArgs, pathApiForPlatform, extractWorktreePath, isExistingBranchSafeToReuse, createWorktreeForTicket, };
+/**
+ * BAPI-941: emit the per-spawn `claude-review` workflow-drift advisory.
+ *
+ * Called once at the shared post-base-resolution, pre-worktree choke point. It
+ * returns `void` and swallows everything: this diagnostic exists to tell an
+ * operator that their epic branch has gone blind to code review, and a
+ * diagnostic that can abort the run it is describing would be strictly worse
+ * than no diagnostic at all.
+ *
+ * All three outcomes continue to worktree creation:
+ *
+ *   - `drifted` — a WARNING naming the stale base and the remedy, and saying
+ *     plainly that work continues.
+ *   - `unverified` — an INFO line naming which comparison was unavailable
+ *     (missing ref, unreadable workflow, unresolved default branch).
+ *   - `aligned` — silence. A clean spawn prints nothing and performs no
+ *     additional network work beyond the fetch that already happened.
+ */
+async function emitClaudeReviewWorkflowDriftAdvisory(deps, baseBranch, overrides) {
+    const warn = overrides.workflowDriftWarningLog ?? ((m) => console.error(m));
+    try {
+        const probe = overrides.probeWorkflowDrift ?? probeClaudeReviewWorkflowDrift;
+        const defaultRef = await resolveRepositoryDefaultBranch(deps);
+        const classification = await probe(deps, { baseRef: baseBranch, defaultRef });
+        if (classification.state === "aligned")
+            return;
+        warn(formatClaudeReviewWorkflowDriftDiagnostic(classification));
+    }
+    catch {
+        // A thrown probe is itself an unavailable comparison. Stay silent about the
+        // exception (it can echo absolute paths and provider text) and never let it
+        // reach the caller.
+    }
+}
 // BAPI-586: base-ref resolution now lives in the focused `base-ref.ts` module so
 // the executor can depend on it without pulling in this large CLI module. We
 // import the VALUES here (so internal uses keep working) and re-export the same
 // references so existing importers of `./start-tickets.js` (index.ts,
 // review-tickets.ts) and the pinned start-tickets tests are unaffected.
-import { validateBranchName, fetchAndResolveBaseSha } from "./base-ref.js";
+import { validateBranchName, fetchAndResolveBaseSha, 
+// BAPI-941: both live in the same leaf module so the interactive refresh path
+// and the non-mutating conductor path share one drift implementation.
+resolveRepositoryDefaultBranch, probeClaudeReviewWorkflowDrift, } from "./base-ref.js";
 export { validateBranchName, fetchAndResolveBaseSha };
 /**
  * Create / switch worktrees for every ticket, throttled to `maxParallel`, using
@@ -2898,6 +2967,22 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
         if (!refresh.ok)
             return { ok: false, error: refresh.error };
     }
+    // BAPI-941: the `claude-review` workflow-drift advisory, emitted ONCE per
+    // worker spawn at the one choke point both dispatch paths pass through, after
+    // the base is resolved and before any worktree exists.
+    //
+    // Per-spawn timing is the whole point. `epic/BAPI-902` was cut clean and was
+    // blinded 24 hours later by an unrelated commit on `main`, so a check that ran
+    // only at `init`/`setup-epic` time would have passed and still let every
+    // subsequent PR go unreviewed. Both refs were just refreshed by the fetch
+    // above, so the comparison is local and costs no extra round trip.
+    //
+    // ADVISORY ONLY, and fail-open in every degraded case (unreachable remote,
+    // missing ref, unresolvable default branch): it prints to stderr and the run
+    // continues to worktree creation. It is not a `RunPolicy` key and not a
+    // worker-emitted control signal — R14 rules 2 and 3 are about the conductor's
+    // decision surface, and a spawner's warning is neither.
+    await emitClaudeReviewWorkflowDriftAdvisory(deps, options.baseBranch, overrides);
     const createWorktreesFn = overrides.createWorktrees ?? createWorktrees;
     const provisionCommandsFn = overrides.provisionCommands ??
         ((rows, d) => provisionCommandsForCreatedWorktrees(rows, buildCommandProvisioningDeps(d)));
@@ -3113,6 +3198,9 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         modelRoutingLog: log,
         modelRoutingWarningLog: errorLog,
         repoNameWarningLog: errorLog,
+        // BAPI-941: the workflow-drift advisory goes to stderr like every other
+        // spawner diagnostic, so it never contaminates the summary on stdout.
+        workflowDriftWarningLog: errorLog,
         // Conductor is OPT-IN (BAPI-394): the three seams are supplied ONLY when the
         // user passes `--conductor`. Supplying `createConductorContext` activates the
         // conductor stage inside orchestrate (env injection + supervisor tab); the

package/build/version.generated.js

@@ -1,3 +1,4 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.49";
-export const BUILD_COMMIT = "ccff42dd5212";
+export const VERSION = "0.2.50";
+export const BUILD_COMMIT = "4b5d3e65b2a3";
+export const LAUNCHER_ARGS = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.50", "serve"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.2.49",
+  "version": "0.2.50",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",
@@ -21,8 +21,10 @@
     "LICENSE"
   ],
   "//test": "The `test` script delegates to the bounded launcher (scripts/run-unit-tests.js → src/run-unit-tests-launcher.ts, BAPI-683), which discovers build/*.test.js at runtime and spawns them in size-bounded batches so the argv never exceeds Windows' ~8191-char command-line limit. Two determinism rules from the pre-launcher script are preserved INSIDE the launcher: (1) multi-file batches run WITHOUT --test-force-exit, because that flag makes node:test exit before aggregating per-subprocess summaries and the tally becomes nondeterministic (failures still surface and still set exit 1, but the count cannot be trusted as a completeness signal); (2) build/secret-safety.test.js leaks a handle that holds the event loop ~60s after its tests finish (they run in ~147ms), so the launcher quarantines it into its own single-file --test-force-exit invocation (FORCE_EXIT_QUARANTINE in src/run-unit-tests-launcher.ts) where the tally stays exact. Do NOT add --test-force-exit to batched invocations, and do NOT remove the quarantine, until the underlying handle leak is fixed.",
+  "//version": "BAPI-930: fired by `npm version <level>` AFTER npm rewrites package.json's version field, so the bumped version and the repinned README land in the SAME commit. A bump performed by hand-editing package.json instead of running `npm version` bypasses this hook entirely and must repin manually via `node scripts/sync-readme-host-examples.js` — the `--check` wired into `build` below is the backstop that catches that case.",
   "scripts": {
-    "build": "node scripts/bundle-version.js && node scripts/validate-packaged-command-references.js && node scripts/bundle-readme.js && node scripts/bundle-pipelines.js && node scripts/bundle-commands.js && node scripts/bundle-agents.js && node scripts/bundle-docs.js && tsc && node scripts/sync-agent-mirrors.js && node scripts/bundle-esbuild.js",
+    "build": "node scripts/bundle-version.js && node scripts/sync-readme-host-examples.js --check && node scripts/validate-packaged-command-references.js && node scripts/bundle-readme.js && node scripts/bundle-pipelines.js && node scripts/bundle-commands.js && node scripts/bundle-agents.js && node scripts/bundle-docs.js && tsc && node scripts/sync-agent-mirrors.js && node scripts/bundle-esbuild.js",
+    "version": "node scripts/sync-readme-host-examples.js --write && git add -- README.md package.json package-lock.json && git commit -m \"chore(mcp-server): release $npm_package_version\" && git tag \"mcp-server/v$npm_package_version\"",
     "check:version-generated": "node scripts/bundle-version.js && node scripts/check-version-generated.js",
     "postbuild": "node scripts/prepend-shebang.cjs",
     "start": "node build/index.js",