@bridge_gpt/mcp-server 0.2.44 → 0.2.46

package/build/merge-pull-request.js

@@ -75,6 +75,7 @@
  * privileged write subtly wrong.
  */
 import { DEFAULT_GATE_NAME, REQUIRED_CI_CHECKS_GREEN, REVIEW_STATE, normalizeCheckName, } from "./conductor/git-ci-types.js";
+import { MERGE_REVIEW_WAIVED_BY_DEGRADATION_REASON, VERDICTLESS_DISPOSITION_FAIL_OPEN, VERDICTLESS_DISPOSITION_PARK, } from "./conductor/git-ci-types.js";
 import { evaluateReviewCondition, normalizeReviewSnapshot, parseDoneGateConfig, } from "./conductor/done-gate.js";
 import { buildGateIdentity, makeMergeActionKey } from "./conductor/merge-identity.js";
 import { resolveLocalMergeMethod, runApprovedLocalMerge, } from "./conductor/local-merge.js";
@@ -135,6 +136,10 @@ function envelope(merged, outcome, reason, retryHint, evaluatedHeadSha, prNumber
         result.http_status = diagnostics.http_status;
     if (diagnostics.completion !== undefined)
         result.completion = diagnostics.completion;
+    // BAPI-915: appended LAST, after every pre-existing optional diagnostic, so the
+    // serialized key order of every envelope that carries no waiver is unchanged.
+    if (diagnostics.review_waiver !== undefined)
+        result.review_waiver = diagnostics.review_waiver;
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -310,13 +315,94 @@ const SUPPORTED_REVIEW_SOURCES = new Set(["verdict_protocol", "native_review_dec
 const REVIEW_UNAVAILABLE_REASON = "review_unavailable";
 const REVIEW_SOURCE_UNSUPPORTED_REASON = "review_source_unsupported";
 const HEAD_SHA_DRIFT_REASON = "head_sha_drift";
+/** Wrap a refusal envelope as a pre-check decision. */
+function refuse(env) {
+    return { kind: "refused", envelope: env };
+}
+/**
+ * Append the waiver marker to an envelope produced AFTER a waived pre-check.
+ *
+ * Applied at the handler's return seam rather than threaded through
+ * `interpretMergeResponse` and `executeApprovedLocalMerge`, both of which build
+ * envelopes on many internal branches — one seam is auditable, a dozen threaded
+ * parameters are not. Every envelope downstream of a waiver carries it,
+ * including one that a LATER guard refused: the waiver really was applied, and
+ * hiding it on the refusal would leave the operator reading a `ci_not_green`
+ * with no idea the review had been waived to get there. This mirrors the server
+ * service, which folds the same marker into every post-review evidence bundle.
+ *
+ * Key order is preserved: the spread keeps the existing keys in place and the
+ * new one lands last, exactly where `envelope()` would have put it.
+ */
+function withReviewWaiver(env, waiver) {
+    if (waiver === undefined)
+        return env;
+    return { ...env, review_waiver: waiver };
+}
+/**
+ * True only when the review carries NO verdict AT ALL for the configured source.
+ *
+ * This is narrower than "the evaluation did not pass", and the gap between the two
+ * is a real hole. Under `verdict_protocol` the server resolves the sticky comment
+ * to `null` when no comment was ever posted, but to the string `"unknown"` for
+ * FOUR different ambiguities: two same-head comments that contradict each other
+ * (BAPI-733), a stale `Reviewed-SHA`, a malformed one, and an unresolvable head.
+ * `evaluateReviewCondition` flattens all five into
+ * `{passed: false, changesRequested: false}`, so waiving on that result alone
+ * would waive a CONTRADICTION — and a contradiction can contain a
+ * changes-requested comment that merely lost the tie-break. That is precisely the
+ * human-escalation case, and waiving it would contradict this feature's own claim
+ * that an objection is never waivable.
+ *
+ * So the waiver mirrors the Python seam field for field: `api/library/vcs/epic_observers.py`
+ * routes `sticky is None` to `PENDING` (waivable) and EVERY `"unknown"` to
+ * `UNKNOWN` (never waivable), and `conductor_merge_service` admits only `PENDING`.
+ * No new server field is needed to do this — `sticky_verdict` already carries the
+ * distinction on the wire, and `normalizeReviewSnapshot` already preserves it.
+ *
+ * The raw body is consulted too, because the normalizer maps an UNRECOGNIZED
+ * `sticky_verdict` to `null` as well. A value outside the server's own closed
+ * vocabulary is not evidence that no verdict exists, so it does not get waived.
+ *
+ * `native_review_decision` has no ambiguity channel of its own — GitHub returns a
+ * single authoritative decision, and a non-approving, non-rejecting one genuinely
+ * means no decision was given — so it needs no extra guard.
+ */
+function verdictIsGenuinelyAbsent(condition, snapshot, rawBody) {
+    if (condition.source !== "verdict_protocol")
+        return true;
+    // `"unknown"` (and anything else non-null) is an unresolved verdict, not a
+    // missing one.
+    if (snapshot.sticky_verdict !== null)
+        return false;
+    const detail = isPlainObject(rawBody) && isPlainObject(rawBody.detail) ? rawBody.detail : null;
+    if (detail === null)
+        return false;
+    const raw = detail.sticky_verdict;
+    return raw === null || raw === undefined;
+}
+/**
+ * The condition's disposition, with the effective default applied.
+ *
+ * ABSENT means `park`, and the default is resolved HERE rather than materialized
+ * onto the parsed condition, so a config that never carried the field keeps its
+ * byte-identical `config_hash` and therefore its merge action key.
+ */
+function effectiveDisposition(condition) {
+    return condition.verdictless_disposition ?? VERDICTLESS_DISPOSITION_PARK;
+}
 /**
  * Evaluate the configured `review_state` condition before the merge is sent.
  *
- * Returns a refusal envelope, or `null` meaning "nothing objected — continue".
- * Every failure direction is contained here and every one of them is a refusal:
- * a review this side cannot read, cannot parse, or cannot evaluate is not a
- * review that approved anything.
+ * Returns a {@link ReviewPrecheckDecision}: a refusal, an ordinary continuation,
+ * or a continuation carrying the bounded waiver diagnostic. Every failure
+ * direction is contained here and every one of them is a refusal: a review this
+ * side cannot read, cannot parse, or cannot evaluate is not a review that
+ * approved anything — and BAPI-915 changed none of that. The single direction it
+ * added is a review that WAS read, at this head, under an explicitly configured
+ * `fail_open`, carrying no objection and NO VERDICT AT ALL — not merely a verdict
+ * this side could not resolve. See {@link verdictIsGenuinelyAbsent} for why that
+ * distinction is load-bearing rather than pedantic.
  *
  * `min_approvals` and `combination` are refused OUTRIGHT rather than approximated
  * with a weaker rule. The server refuses them too, for the same reason: silently
@@ -325,9 +411,9 @@ const HEAD_SHA_DRIFT_REASON = "head_sha_drift";
  */
 async function precheckReviewCondition(deps, condition, prNumber, expectedHeadSha) {
     if (!SUPPORTED_REVIEW_SOURCES.has(condition.source)) {
-        return envelope(false, "review_source_unsupported", REVIEW_SOURCE_UNSUPPORTED_REASON, "needs_human", expectedHeadSha, prNumber);
+        return refuse(envelope(false, "review_source_unsupported", REVIEW_SOURCE_UNSUPPORTED_REASON, "needs_human", expectedHeadSha, prNumber));
     }
-    const unavailable = () => envelope(false, "review_unavailable", REVIEW_UNAVAILABLE_REASON, "needs_human", expectedHeadSha, prNumber);
+    const unavailable = () => refuse(envelope(false, "review_unavailable", REVIEW_UNAVAILABLE_REASON, "needs_human", expectedHeadSha, prNumber));
     // URL and header construction sit OUTSIDE the try, matching the required-check
     // resolver: a failure there is a broken dependency, not an unreadable review,
     // and it belongs to the handler's outer containment boundary. The repository
@@ -350,7 +436,12 @@ async function precheckReviewCondition(deps, condition, prNumber, expectedHeadSh
     // `normalizeReviewSnapshot` returns null for `available: false` and for any
     // body it cannot read as a review snapshot — the same answer, because both
     // mean the same thing here.
-    const snapshot = normalizeReviewSnapshot(await readJson(reviewResp));
+    //
+    // The raw body is kept as well: `verdictIsGenuinelyAbsent` below has to tell an
+    // ABSENT `sticky_verdict` from one the normalizer could not recognize, and the
+    // normalized snapshot maps both to `null`.
+    const reviewBody = await readJson(reviewResp);
+    const snapshot = normalizeReviewSnapshot(reviewBody);
     if (snapshot === null)
         return unavailable();
     // Head equality is checked BEFORE the evaluator, and takes precedence over an
@@ -362,16 +453,42 @@ async function precheckReviewCondition(deps, condition, prNumber, expectedHeadSh
         if (typeof snapshot.head_sha === "string" && snapshot.head_sha.length > 0) {
             diagnostics.actual_head_sha = snapshot.head_sha;
         }
-        return envelope(false, "refused", HEAD_SHA_DRIFT_REASON, "needs_human", expectedHeadSha, prNumber, diagnostics);
+        return refuse(envelope(false, "refused", HEAD_SHA_DRIFT_REASON, "needs_human", expectedHeadSha, prNumber, diagnostics));
     }
     const evaluation = evaluateReviewCondition(condition, snapshot);
     if (!evaluation.passed) {
+        // BAPI-915 — the ONE waivable direction, and every guard that narrows it has
+        // already run above: the source is supported, the response was readable, the
+        // envelope was not `available: false`, and the snapshot is bound to THIS
+        // head. What remains is a review that was read and carries NO VERDICT AT
+        // ALL — the shape `claude-review` leaves behind when it dies during
+        // synthesis, having posted nothing.
+        //
+        // `changesRequested` is excluded explicitly: a human objected to this exact
+        // head, and no configuration waives an objection. Head drift is excluded by
+        // construction, because the head check above returns before the evaluator
+        // ever runs — that ordering is load-bearing and must not be folded in.
+        //
+        // `verdictIsGenuinelyAbsent` is the third guard and it is NOT redundant with
+        // the evaluator: the evaluator reports the same
+        // `{passed: false, changesRequested: false}` for "nobody posted anything" and
+        // for "two same-head comments contradict each other", and only the first may
+        // ever be waived.
+        //
+        // The disposition is compared for EXACT equality with `fail_open`. An absent
+        // field and an explicit `park` both fall through to the byte-identical
+        // pre-BAPI-915 refusal below.
+        if (effectiveDisposition(condition) === VERDICTLESS_DISPOSITION_FAIL_OPEN &&
+            evaluation.changesRequested === false &&
+            verdictIsGenuinelyAbsent(condition, snapshot, reviewBody)) {
+            return { kind: "waived", waiver: MERGE_REVIEW_WAIVED_BY_DEGRADATION_REASON };
+        }
         // A wait, not a park: a verdict for THIS head may still be posted. The
         // evaluator's own reason is forwarded verbatim rather than flattened, so the
         // caller can tell "no verdict yet" from "changes requested".
-        return envelope(false, "review_not_approved", evaluation.reason, "retry_later", expectedHeadSha, prNumber);
+        return refuse(envelope(false, "review_not_approved", evaluation.reason, "retry_later", expectedHeadSha, prNumber));
     }
-    return null;
+    return { kind: "proceed" };
 }
 // ---------------------------------------------------------------------------
 // Server-response interpretation
@@ -691,10 +808,18 @@ export async function mergePullRequestHandler(deps, args) {
         // carries a `review_state` condition, and it returns BEFORE the pre-POST
         // section below — so a refusal here constructs no merge URL, no merge
         // headers, no action key, and sends no merge request.
+        //
+        // BAPI-915: the decision is now three-valued. A refusal still returns before
+        // anything below runs; a waiver continues into the identical merge path and
+        // is carried through to the reported envelope so the operator can see that
+        // the merge advanced on CI evidence alone.
+        let reviewWaiver;
         if (resolution.reviewCondition !== null) {
-            const refusal = await precheckReviewCondition(deps, resolution.reviewCondition, prNumber, expectedHeadSha);
-            if (refusal !== null)
-                return text(refusal);
+            const decision = await precheckReviewCondition(deps, resolution.reviewCondition, prNumber, expectedHeadSha);
+            if (decision.kind === "refused")
+                return text(decision.envelope);
+            if (decision.kind === "waived")
+                reviewWaiver = decision.waiver;
         }
         // --- pre-POST section ---------------------------------------------------
         const gateIdentity = buildGateIdentity(DEFAULT_GATE_NAME, resolution.configHash);
@@ -729,6 +854,7 @@ export async function mergePullRequestHandler(deps, args) {
         catch {
             return text(envelope(false, "unknown", "merge_request_not_observed", "retry_later", expectedHeadSha, prNumber, {
                 hint: UNKNOWN_HINT,
+                review_waiver: reviewWaiver,
             }));
         }
         if (!mergeResp.ok) {
@@ -736,10 +862,11 @@ export async function mergePullRequestHandler(deps, args) {
             // status only — raw upstream error text is never forwarded to the agent.
             await deps.handleResponse(mergeResp).catch(() => "");
             if (mergeResp.status === 409) {
-                return text(envelope(false, "action_key_mismatch", "action_key_mismatch", "needs_human", expectedHeadSha, prNumber));
+                return text(envelope(false, "action_key_mismatch", "action_key_mismatch", "needs_human", expectedHeadSha, prNumber, { review_waiver: reviewWaiver }));
             }
             return text(envelope(false, "error", "merge_request_failed", "needs_human", expectedHeadSha, prNumber, {
                 http_status: mergeResp.status,
+                review_waiver: reviewWaiver,
             }));
         }
         const mergeJson = await readJson(mergeResp);
@@ -749,9 +876,9 @@ export async function mergePullRequestHandler(deps, args) {
         if (executionMode === "local" &&
             isPlainObject(mergeJson) &&
             mergeJson.status === LOCAL_APPROVAL_STATUS) {
-            return text(await executeApprovedLocalMerge(deps, mergeJson, prNumber, expectedHeadSha, actionKey));
+            return text(withReviewWaiver(await executeApprovedLocalMerge(deps, mergeJson, prNumber, expectedHeadSha, actionKey), reviewWaiver));
         }
-        return text(interpretMergeResponse(mergeJson, expectedHeadSha, prNumber));
+        return text(withReviewWaiver(interpretMergeResponse(mergeJson, expectedHeadSha, prNumber), reviewWaiver));
     }
     catch {
         // Containment: never throw through the MCP transport, and never serialize the

package/build/pipelines.generated.js

@@ -1023,5 +1023,5 @@ export const INSTRUCTIONS = {
     "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 — 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` → follow the **Single-ticket path** below.\n   - `epic_candidate` → 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 — list every `create_ticket`, `attachment` (operation: `\"upload\"`), and `track_ticket` call with its key arguments — 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 phase-eligible local materials (Planning Assets, Downloadable Assets, and Planning & Downloadable Assets) 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}`). If it **does** already exist, it is the approved manifest and this step performs **no fresh decomposition** — read it and use it as written. Decomposition happens once; re-deriving the split immediately before upload is how children end up overlapping or contradicting the parent they are about to be created under.\n   2. Render bodies against the frozen manifest by following `render-ticket-manifest.md`: one `jira-ticket-writer` invocation per entry that lacks a draft on disk, each bound to its own entry's fixed boundary and size band, using the `draft_path` from the decomposition plan. A rendering invocation may not re-split, merge, reorder, renumber, or rescope. Its preflight is fail-closed — an unapproved manifest, a changed manifest identity, an XL epic child, or a missing writer draft stops the flow **before** any Jira mutation. After drafting, extend `draft-metadata.json` so `children[]` mirrors the final list from the decomposition plan.\n   3. Create only from writer-produced drafts. Every ticket body uploaded below came from `jira-ticket-writer`; nothing here composes a description inline.\n   4. 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   5. 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   6. 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   7. **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** — 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 — 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 — 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` — child summary.\n   - `slim_description` — child slim description.\n   - `issue_type` — typically `Task` (or `Spike` when the child is primarily discovery).\n   - `labels` — `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",
     "verify-plan.md": "Close the remaining plan gaps for ticket {ticket_key}, now that the pull request is open.\n\nThe plan's work has already been executed. The production phase authored the\nartifacts, the checkpoint pushed them, and the pre-PR verification phase ran the\nplan's review steps, test commands, and rendered-UI remediation — publishing each\nmaterial correction as it went. The pull request was then opened on top of all of it.\n\nThis phase exists for the narrow remainder: the plan obligations that genuinely could\n**not** be reached before a pull request existed, plus corrections attributable to this\nticket.\n\nTwo consequences follow, and both are deliberate:\n\n- **This phase does not re-run completed work.** A step the durable ledger records as\n  `executed` or `adapted` stays settled unless a later correction invalidated its\n  evidence. Re-running it duplicates work the pre-PR phase already did and burns the\n  budget this protocol was reordered to protect.\n- **This phase never issues a verdict.** You report what you observed. The\n  authoritative pass/fail belongs to the pipeline's `ci` and `code_review` gates,\n  which the reconciler observes independently. Worker self-verification has\n  demonstrably reported green while the full suite was red; that is exactly why the\n  gates, not this phase, decide.\n\n**Tool and scope boundary.** Use only the tools this recipe names, the repo's own tooling, and MCP\ncapabilities provisioned for this repository. Keep all work confined to this worktree unless\nexplicitly told to do otherwise.\n\n**Execution mode for this run: `{execution_mode}`.** Under `orchestrated`\n(`run_pipeline` / `resume_pipeline`) orchestration appends the routed phase context and\nparses the fenced result envelope you return. Under `inline` (`get_pipeline_recipe`)\nthere is no orchestrator: the ledger is read with a tool call and written with one.\nFollow the branch that matches wherever the two are named.\n\n---\n\n## Step 1 — Establish that the durable artifact exists\n\nBefore running any check:\n\n1. Run `git branch --show-current` and `git rev-parse HEAD`, then verify the branch\n   has been pushed and the local head is present on the remote (for example via\n   `git status -sb` showing no unpushed ahead-count, or `git ls-remote origin <branch>`).\n2. Verify that a usable pull request URL was obtained by the preceding PR step —\n   either a newly opened pull request or an already-open one on this head branch.\n\nIf the branch is not pushed, or no usable pull request URL exists, then\n**stop this phase** and report the missing prerequisite. This phase exists only to\nadd work on top of an open pull request.\n\n## Step 2 — Recover what remains from durable state\n\n1. Call the `get_plan` tool for `{ticket_key}`. The local copy at\n   `{docs_dir}/plans/{ticket_key}-plan.md` may be used as a reference.\n2. Recover the durable ledger, by mode:\n   - **orchestrated** — read the **Routed phase context** block appended to this\n     instruction: `ledger` carries every disposition earlier phases recorded, and\n     `ownedSteps` carries anything routed directly to this phase.\n   - **inline** — call `get_phase_context` with `ticket_key` `{ticket_key}` and\n     `phase` `post_pr_gap_close`. It returns the same `ownedSteps` plus the `ledger`\n     merged from every earlier phase's artifact, `terminalStepIds` for what is\n     already settled, and `unresolved` for the escalations that are this phase's\n     actual subject.\n\nRecover the remaining work from that durable record, not from conversation. A\ncompaction or a resumed session loses the conversation; the ledger survives both,\nwhich is why it replaced the conversational hand-off.\n\n## Step 3 — Select only genuine gaps\n\nRun only:\n\n- Steps the ledger records as `escalated` **because a capability was unavailable\n  before the pull request existed**, or **because the check genuinely requires an open pull request** — and\n  which are now satisfiable.\n- Corrections clearly attributable to this ticket's change.\n\nReport — do not attempt to fix — failures that are unrelated to this ticket, flaky,\nenvironmental, pre-existing on the base branch, or outside the declared file scope.\nSpeculative edits made under budget pressure are how a correction round turns into a\nregression.\n\nApply the same adaptation boundary the earlier phases use: **locator-correction**,\n**repository-command-correction**, and **equivalent-implementation-recognized** are\nmechanical and may be applied; anything touching design, schema, public API,\ndependencies, or security escalates instead.\n\nBefore beginning any correction, apply the **low-budget guard**: only start if enough\nsession budget clearly remains to make the edit, commit it, *and* push it. Starting a\nfix you cannot finish and publish is strictly worse than reporting the finding and\nletting the CI and review gates handle it — an unpushed correction is invisible to\nthose gates.\n\n## Step 4 — Report what you observed, honestly\n\nFor every check you run, record the exact command, its observed result, and — on\nfailure — the relevant failure detail (the failing test names, the error output, the\ndiagnostic lines).\n\nReport all of it, including failures you did not fix. Never soften or omit a failing\nresult.\n\nDescribe only what you observed. Do not write that CI passed, that the gate is met,\nthat the review is approved, or any equivalent claim about the pipeline's verdict —\nthose states are decided by the `ci` and `code_review` gates and observed by the\nreconciler, never asserted by this phase.\n\n## Step 5 — Correct only what is clearly yours, and push it immediately\n\nFor each accepted correction:\n\n1. Make the edit.\n2. Stage the specific files, commit, and **push immediately** — the commit and its\n   push are one consecutive sequence, never separated by another check. A local\n   commit that is never pushed is not visible to the pull request, to CI, or to the\n   reconciler.\n3. Run `git rev-parse HEAD` again and record the new pushed head as\n   `last_commit_sha`.\n\n## Step 6 — Final git-state audit\n\nBefore returning, run `git status --porcelain` and resolve the working tree:\n\n- Legitimate corrections still uncommitted → commit and push them (Step 5's\n  commit-then-push-immediately rule applies).\n- Accidental diagnostic edits — debug prints, scratch files, temporary config\n  tweaks made while investigating a failure → revert them when it is safe to do so.\n- Anything you cannot safely resolve → leave it and **report it explicitly**,\n  naming each remaining dirty path.\n\nNever return leaving unpushed commits unreported.\n\n## Step 7 — Hand unresolved findings forward\n\nAn unresolved local finding is normally **not** a reason to stop the pipeline. The\npull request is open and the authoritative gates will evaluate it. Report the\nfinding and let CI monitoring and code review take it from there.\n\nStop only when continuing would be unsafe or impossible — for example the durable\nartifact from Step 1 turned out to be missing, or the working tree is in a state you\ncannot resolve without risking the pushed branch.\n\n## Return\n\nReturn a summary containing:\n\n- the branch and the pull request URL,\n- the latest pushed `last_commit_sha`,\n- every gap-closing command run, with its observed outcome,\n- the correction commit, if one was made and pushed,\n- every unresolved finding and every unresolved dirty path.\n\nState these as worker observations. Do not include a pass/fail verdict for the `ci`\nor `code_review` gates.\n\nThen record the machine-readable phase result, by mode, so the durable ledger records\nhow the remaining gaps closed.\n\n### orchestrated\n\nEnd your result with the envelope in a fenced block tagged `bapi-phase-result`, which\norchestration parses, validates, and persists:\n\n```bapi-phase-result\n{\"version\":1,\"phase\":\"post_pr_gap_close\",\"lastCommitSha\":\"<sha>\",\"records\":[]}\n```\n\n### inline\n\nCall the `record_phase_result` tool with `ticket_key` `{ticket_key}` and\n`phase_result` set to that same envelope object; the tool validates and persists it.\n**Do not also emit a fenced `bapi-phase-result` block** — nothing parses one on this\npath.\n\nThe tool call is this phase's final action, **not the end of your turn.** When it\nreturns successfully, continue immediately with the next recipe step — the ticket\nstatus transition, the CI follow-up config, and CI monitoring. The pull request is\nopen and its gates are still pending; stopping here abandons the run before anything\nobserves them.\n\nIf the call fails, fix what it reports and call it again.\n",
-    "write-epic-summary.md": "Synthesize all sub-task explorations into a final overview document.\n\n## Instructions\n\n1. First, use a terminal command or glob pattern to list all files in `{docs_dir}/epic-plans/{epic_slug}/explorations/`. Then read each file. Do not guess filenames — discover them dynamically.\n\n2. Also read:\n   - `{docs_dir}/epic-plans/{epic_slug}/research-findings.md`\n   - `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md`\n   - `{docs_dir}/epic-plans/{epic_slug}/goals-and-nfrs.md` (the goals/NFR framing; carry its System Goals, NFRs, and any Recommended Implementation Order through to the overview).\n\n3. Synthesize the information into an overview and write it to `{docs_dir}/epic-plans/{epic_slug}/overview.md` with the following required sections:\n\n```markdown\n# Epic Overview: {epic title derived from description}\n\n## Epic Description and Goals\n{Summary of the epic's purpose, scope, and desired outcomes. Lead with the business goal and desired end-state from goals-and-nfrs.md.}\n\n## Non-Functional Requirements\n{The classified NFRs from goals-and-nfrs.md — each with its category, requirement, implication, and final status (confirmed/assumed). Any NFRs the user clarified should now read as confirmed/assumed, not open.}\n\n## Research Summary\n{Key external findings that informed the decomposition. If no research was performed, state \"No external research was needed.\"}\n\n## Sub-task List\n{Numbered list of all sub-tasks with relative markdown links to their exploration docs.}\n1. [Sub-task title](explorations/01-subtask-slug.md) — one-line summary\n2. [Sub-task title](explorations/02-subtask-slug.md) — one-line summary\n...\n\n## Dependency Graph\n{Textual list showing execution ordering and dependencies between sub-tasks.}\n- Sub-task 1: No dependencies (start here)\n- Sub-task 2: Depends on Sub-task 1\n- Sub-task 3: Depends on Sub-task 1\n- Sub-task 4: Depends on Sub-tasks 2, 3\n...\n\n## Recommended Implementation Order\n{The recommended order in which to implement the sub-tasks, reconciling the provisional order from goals-and-nfrs.md with the approved decomposition. For each sub-task give the position, its hard prerequisites (depends on), any soft sequencing preferences (recommended after), and a one-line rationale. This is recommended sequencing only — no Jira dependency links are created.}\n\n## Next Steps\n{One-line summaries for each sub-task, specifically formatted so they can be copy-pasted directly into the `/write-ticket` command. Each line should be a self-contained ticket description.}\n```\n\n4. After writing the overview, display the file path to the user and summarize the epic plan.\n\n5. **Push the goals/NFRs + recommended order into the Jira epic (only when `{epic_key}` is non-empty).** The `epic_key` is empty when this run was started from free-form text rather than an existing Epic; in that case skip this step. When `{epic_key}` is a real Jira key, post the System Goals, the final NFRs, and the Recommended Implementation Order as a **comment** on that epic by calling the `add_comment` MCP tool with `ticket_number` set to `{epic_key}` and a concise comment containing those three parts. Do not create Jira dependency links and do not attach a separate markdown doc — the comment is the delivery. Display: `\"Posted epic goals/NFRs and recommended implementation order to {epic_key}\"`.\n\n## Return\n\nConfirm the overview was written to `{docs_dir}/epic-plans/{epic_slug}/overview.md` and report the total sub-task count along with a one-line summary of the epic plan. State whether the goals/NFRs + recommended order were posted as a comment on `{epic_key}` or skipped because no epic key was provided.\n"
+    "write-epic-summary.md": "Synthesize all sub-task explorations into a final overview document.\n\n## Instructions\n\n1. First, use a terminal command or glob pattern to list all files in `{docs_dir}/epic-plans/{epic_slug}/explorations/`. Then read each file. Do not guess filenames — discover them dynamically.\n\n2. Also read:\n   - `{docs_dir}/epic-plans/{epic_slug}/research-findings.md`\n   - `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md`\n   - `{docs_dir}/epic-plans/{epic_slug}/goals-and-nfrs.md` (the goals/NFR framing; carry its System Goals, NFRs, and any Recommended Implementation Order through to the overview).\n\n3. Synthesize the information into an overview and write it to `{docs_dir}/epic-plans/{epic_slug}/overview.md` with the following required sections:\n\n```markdown\n# Epic Overview: {epic title derived from description}\n\n## Epic Description and Goals\n{Summary of the epic's purpose, scope, and desired outcomes. Lead with the business goal and desired end-state from goals-and-nfrs.md.}\n\n## Non-Functional Requirements\n{The classified NFRs from goals-and-nfrs.md — each with its category, requirement, implication, and final status (confirmed/assumed). Any NFRs the user clarified should now read as confirmed/assumed, not open.}\n\n## Research Summary\n{Key external findings that informed the decomposition. If no research was performed, state \"No external research was needed.\"}\n\n## Sub-task List\n{Numbered list of all sub-tasks with relative markdown links to their exploration docs.}\n1. [Sub-task title](explorations/01-subtask-slug.md) — one-line summary\n2. [Sub-task title](explorations/02-subtask-slug.md) — one-line summary\n...\n\n## Dependency Graph\n{Textual list showing execution ordering and dependencies between sub-tasks.}\n- Sub-task 1: No dependencies (start here)\n- Sub-task 2: Depends on Sub-task 1\n- Sub-task 3: Depends on Sub-task 1\n- Sub-task 4: Depends on Sub-tasks 2, 3\n...\n\n## Recommended Implementation Order\n{The recommended order in which to implement the sub-tasks, reconciling the provisional order from goals-and-nfrs.md with the approved decomposition. For each sub-task give the position, its hard prerequisites (depends on), any soft sequencing preferences (recommended after), and a one-line rationale. This is recommended sequencing only — no Jira dependency links are created.}\n\n## Next Steps\n{One-line summaries for each sub-task, specifically formatted so they can be handed directly to the Jira Ticket Writer / ticket-authoring workflow as input. Each line should be a self-contained ticket description.}\n```\n\n4. After writing the overview, display the file path to the user and summarize the epic plan.\n\n5. **Push the goals/NFRs + recommended order into the Jira epic (only when `{epic_key}` is non-empty).** The `epic_key` is empty when this run was started from free-form text rather than an existing Epic; in that case skip this step. When `{epic_key}` is a real Jira key, post the System Goals, the final NFRs, and the Recommended Implementation Order as a **comment** on that epic by calling the `add_comment` MCP tool with `ticket_number` set to `{epic_key}` and a concise comment containing those three parts. Do not create Jira dependency links and do not attach a separate markdown doc — the comment is the delivery. Display: `\"Posted epic goals/NFRs and recommended implementation order to {epic_key}\"`.\n\n## Return\n\nConfirm the overview was written to `{docs_dir}/epic-plans/{epic_slug}/overview.md` and report the total sub-task count along with a one-line summary of the epic plan. State whether the goals/NFRs + recommended order were posted as a comment on `{epic_key}` or skipped because no epic key was provided.\n"
 };