@bridge_gpt/mcp-server 0.1.10 → 0.1.12

package/build/index.js

@@ -1493,6 +1493,113 @@ server.registerTool("request_ticket_critique", {
     return { content: [{ type: "text", text: confirmationText }] };
 });
 // ---------------------------------------------------------------------------
+// Combined Ticket Review (clarify + critique)
+// ---------------------------------------------------------------------------
+server.registerTool("request_ticket_review", {
+    description: "Request a combined ticket review that generates BOTH clarifying questions (or debugging guidance for bug tickets) " +
+        "AND a ticket quality critique in parallel on the server, halving wall-clock latency vs. running the two " +
+        "requests sequentially. This triggers an asynchronous background job — results are NOT immediate. " +
+        "Processing typically takes 2-6 minutes. " +
+        "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
+        "or 403 if the API key is unauthorized. " +
+        "Set wait_for_result to true to block until both documents are ready and receive them concatenated.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a combined review for"),
+        wait_for_result: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, the tool blocks and polls until both documents are ready (typically 2-6 minutes), " +
+            "then returns the concatenated markdown directly. When false (default), returns immediately " +
+            "with a confirmation message — use get_clarifying_questions and get_ticket_critique later to retrieve results."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When wait_for_result is true, whether to save each generated document to its canonical local path under " +
+            "BAPI_DOCS_DIR (clarifying-questions/ or ticket-critiques/). Defaults to true. Ignored when wait_for_result is false."),
+        second_opinion: z.string().optional(),
+        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
+            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
+            "second_opinion takes precedence."),
+    },
+}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
+    const body = { repo_name: REPO_NAME };
+    const trimmedSecondOpinion = second_opinion?.trim();
+    if (trimmedSecondOpinion) {
+        body.provider_override = trimmedSecondOpinion;
+    }
+    const trimmedProvider = provider?.trim();
+    if (trimmedProvider && !trimmedSecondOpinion) {
+        body.provider = trimmedProvider;
+    }
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-ticket-review`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const errorText = await handleResponse(resp);
+        return {
+            content: [{ type: "text", text: `Failed to request ticket review: ${errorText}` }],
+        };
+    }
+    if (wait_for_result) {
+        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/ticket-review`, { repo_name: REPO_NAME });
+        const result = await pollForResult(getUrl, 900_000, `Ticket review for ${ticket_number}`);
+        if (!result.ok) {
+            return { content: [{ type: "text", text: result.text }] };
+        }
+        // The combined GET endpoint returns JSON. Parse and fan out into markdown.
+        let envelope;
+        try {
+            envelope = JSON.parse(result.text);
+        }
+        catch (parseErr) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to parse ticket review response: ${parseErr}\nRaw body: ${result.text}`,
+                    }],
+            };
+        }
+        const clarify = envelope.clarify ?? {};
+        const critique = envelope.critique ?? {};
+        const parts = [];
+        let notes = "";
+        if (clarify.status === "success" && typeof clarify.content === "string" && clarify.content) {
+            parts.push(clarify.content);
+            if (save_locally && clarify.doc_type) {
+                const filename = `${ticket_number}-${clarify.doc_type}`;
+                const note = await saveLocally(getDocsPath("clarifying-questions"), filename, clarify.content);
+                notes += note;
+            }
+        }
+        else {
+            parts.push(`> **Note:** Clarifying questions sub-flow ${clarify.status ?? "unavailable"} (no content returned).`);
+        }
+        if (critique.status === "success" && typeof critique.content === "string" && critique.content) {
+            parts.push(critique.content);
+            if (save_locally && critique.doc_type) {
+                const filename = `${ticket_number}-${critique.doc_type}`;
+                const note = await saveLocally(getDocsPath("ticket-critiques"), filename, critique.content);
+                notes += note;
+            }
+        }
+        else {
+            parts.push(`> **Note:** Ticket critique sub-flow ${critique.status ?? "unavailable"} (no content returned).`);
+        }
+        const text = parts.join("\n\n---\n\n") + notes;
+        return { content: [{ type: "text", text }] };
+    }
+    const confirmationText = `Combined ticket review requested for ${ticket_number}. ` +
+        `Processing typically takes 2-6 minutes. ` +
+        `Use get_clarifying_questions and get_ticket_critique with ticket_number "${ticket_number}" to retrieve the two documents once processing completes.`;
+    return { content: [{ type: "text", text: confirmationText }] };
+});
+// ---------------------------------------------------------------------------
 // Reimplement Context
 // ---------------------------------------------------------------------------
 server.registerTool("request_reimplement_context", {

package/build/pipelines.generated.js

@@ -458,44 +458,19 @@ export const PIPELINES = {
             },
             {
                 "type": "mcp_call",
-                "tool": "request_clarifying_questions",
+                "tool": "request_ticket_review",
                 "params": {
                     "ticket_number": "{ticket_key}",
                     "wait_for_result": true,
                     "save_locally": true,
                     "provider": "{provider}"
                 },
-                "description": "Generate clarifying questions (initial)",
+                "description": "Generate combined clarify+critique review (initial)",
                 "on_error": "warn_and_continue"
             },
             {
                 "type": "mcp_call",
-                "tool": "request_ticket_critique",
-                "params": {
-                    "ticket_number": "{ticket_key}",
-                    "wait_for_result": true,
-                    "save_locally": true,
-                    "provider": "{provider}"
-                },
-                "description": "Generate ticket quality critique (initial)",
-                "on_error": "warn_and_continue"
-            },
-            {
-                "type": "mcp_call",
-                "tool": "request_clarifying_questions",
-                "params": {
-                    "ticket_number": "{ticket_key}",
-                    "second_opinion": "auto",
-                    "wait_for_result": true,
-                    "save_locally": true,
-                    "provider": "{provider}"
-                },
-                "description": "Generate clarifying questions (second opinion)",
-                "on_error": "warn_and_continue"
-            },
-            {
-                "type": "mcp_call",
-                "tool": "request_ticket_critique",
+                "tool": "request_ticket_review",
                 "params": {
                     "ticket_number": "{ticket_key}",
                     "second_opinion": "auto",
@@ -503,7 +478,7 @@ export const PIPELINES = {
                     "save_locally": true,
                     "provider": "{provider}"
                 },
-                "description": "Generate ticket quality critique (second opinion)",
+                "description": "Generate combined clarify+critique review (second opinion)",
                 "on_error": "warn_and_continue"
             },
             {
@@ -526,10 +501,10 @@ export const PIPELINES = {
 };
 export const INSTRUCTIONS = {
     "assess-epic-research-needs.md": "Analyze the epic description and build a structured research plan.\n\n## Epic Description\n\n{epic_description}\n\n## Instructions\n\n1. Create the directory structure for this epic's artifacts:\n   ```\n   mkdir -p {docs_dir}/epic-plans/{epic_slug}\n   ```\n\n2. Analyze the epic description above. Determine what external knowledge is required to plan this epic effectively. Consider:\n   - Unfamiliar technologies, libraries, or frameworks mentioned\n   - API documentation or integration specs that need to be consulted\n   - Best practices or architectural patterns that require research\n   - Domain-specific knowledge gaps\n\n3. Decide on a **Research Mode**:\n   - **deep**: Use when the epic involves large, multi-faceted unknowns requiring synthesis from multiple sources (e.g., \"best practices for implementing WebSocket connection pooling in Python asyncio\").\n   - **web**: Use for quick factual lookups — library API signatures, configuration syntax, small \"how to\" questions.\n   - **none**: Use when the codebase exploration alone will provide sufficient context and no external knowledge is needed.\n\n4. Write a structured research plan to `{docs_dir}/epic-plans/{epic_slug}/research-plan.md` with these sections:\n\n```markdown\n# Research Plan\n\n## Research Mode\n{deep | web | none}\n\n## Deep Research Query\n{If mode is \"deep\": a single, well-crafted query for the deep research tool. Otherwise: \"N/A\"}\n\n## Web Search Topics\n{If mode is \"web\" or as fallback topics for \"deep\": a numbered list of specific search topics. Otherwise: \"N/A\"}\n\n## Rationale\n{Brief explanation of why this research mode was chosen and what knowledge gaps it addresses.}\n```\n",
-    "capture-review-decisions.md": "Capture user decisions on review findings for {ticket_key} using the HTML decision page, then interpretively rewrite the clarifying questions and critique docs and upload both to Jira.\n\n## Step 1: Read source documents\n\nRead both files:\n- Evaluation: `{docs_dir}/review/{ticket_key}-review-evaluation.md`\n- Resolution guide: `{docs_dir}/review/{ticket_key}-resolution-guide.md`\n\nIf either file does not exist or is empty, stop and report: \"Review evaluation or resolution guide not found. Run the earlier pipeline steps first.\"\n\n## Step 2: Map evaluation items to decision page input\n\nTransform the evaluation into `generate_decision_page` JSON input using these mapping rules:\n\n| Evaluation Section | JSON Field | Mapping Rule |\n|---|---|---|\n| Open Questions | `actionable_items` | E-item title → `question`, full **Assessment** text → `context`, `**Source**` from the evaluation → `source`, decision tree branch texts from the resolution guide → `options` (string array, labels only), `**Recommendation Index**` from the resolution guide → `recommendation_index` |\n| Needs Scrutiny | `actionable_items` | E-item title → `question`, full **Assessment** text → `context`, `**Source**` from the evaluation → `source`, decision tree branch texts from the resolution guide → `options` (string array, labels only), `**Recommendation Index**` from the resolution guide → `recommendation_index` |\n| Confirmed Improvements | `clear_improvements` | E-item title → `title`, confidence tag → `confidence`, recommended action → `action`, `**Source**` from the evaluation → `source` |\n\n**Important**: The `context` field guides the user's decision, therefore, it is important to present all relevant information to the the user in clear and straightforward terms. Your goal is to make it easy for the user to make a decision. Do not assume the user is familiar with the underlying documents. \n\nFor each actionable item, the `options` array is a list of plain label strings extracted from the resolution guide's decision tree branches. The tool auto-generates value keys (`opt-0`, `opt-1`, etc.) and auto-appends a \"None of these\" option. Do not generate value keys yourself.\n\n## Step 3: Call the MCP tool\n\nCall `generate_decision_page` with:\n- `ticket_key`: `{ticket_key}`\n- `actionable_items`: combined mapped array from Step 2 (each item has `id`, `question`, `context`, `source`, `recommendation_index`, `options`)\n- `clear_improvements`: mapped array from Step 2 (each item has `id`, `title`, `action`, `confidence`, `source`)\n\n## Step 4: Check tool response\n\nThe tool returns a JSON response with a `status` field:\n- If `status` is `\"no_decisions_needed\"`: skip Steps 5, 6, 7, and 8 entirely. Output a success message: \"All suggestions were confirmed as improvements. No decisions needed — skipping doc rewrite and upload.\"\n- If `status` is `\"decision_page_generated\"`: continue to Step 5. The response includes `file_path`.\n\n## Step 5: Direct user to the decision page\n\nTell the user to open the generated HTML file in their browser. Provide the `file_path` from the tool response.\n\n## Step 6: Wait for user input\n\nStop and wait for the user to paste the JSON output from the decision page. Do NOT assume responses. Do NOT proceed until the user provides the JSON.\n\n## Step 7: Interpretively rewrite source documents\n\nThe pasted JSON contains a `decisions` object keyed by item ID. Each decision includes `source`, `choice`, `chosen_label`, and `comment`. Use these fields to locate and rewrite the corresponding sections in:\n- `{docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md`\n- `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md`\n\nFor each decision, use the `source` field (e.g., \"Clarifying Q3 (initial round)\") to find the original section in the appropriate document. Then apply the decision:\n\n### Actionable item decisions\n\n- **Selected option** (`choice` is `opt-N`): Add `**Review Decision**: Accepted. <chosen_label>.` to the corresponding section. Integrate the selected direction into the section text so it reads as a final recommendation or resolved answer.\n- **None of these** (`choice` is `none`): Add `**Review Decision**: Rejected — none of the proposed options accepted.` Include the user's `comment` explaining why. Rewrite the section to reflect this decision.\n\nFor actionable items sourced from clarifying questions, rewrite the question's best-guess answer so it reads as the final resolved direction chosen by the reviewer. Do not leave the item framed as an unresolved accept/reject/modify prompt.\n\n### General comment handling\n\nTreat `general_comment` as overarching guidance that informs the tone and direction of both document rewrites. If it contains specific actionable feedback, weave it into the relevant sections. If it is broad or general, use it as context for how the rewrites should read. Do not create a separate \"General Comment\" or \"Reviewer Notes\" section — the goal is \"final draft\" form.\n\n### Rewrite principles\n\nThe goal is a **final draft** — the documents should read as if they were written with the decisions already made. Do not mechanically append decisions. Instead, lightly rewrite affected sections so they reflect the decisions naturally. Preserve all non-affected sections unchanged.\n\n## Step 8: Upload to Jira\n\nUpload both updated documents to Jira using `upload_attachment`:\n\n1. Upload clarifying questions:\n   - `ticket_number`: `{ticket_key}`\n   - `file_path`: `{docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md`\n   - `link_type`: `clarifying-questions.md`\n\n2. Upload ticket quality critique:\n   - `ticket_number`: `{ticket_key}`\n   - `file_path`: `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md`\n   - `link_type`: `ticket-quality-critique.md`\n\n## Step 9: Complete\n\nConfirm: \"Review decisions captured and uploaded to {ticket_key}.\"\n\nThis is a single-round process. Do not iterate or ask for additional feedback rounds.\n",
+    "capture-review-decisions.md": "Capture user decisions on review findings for {ticket_key} using the HTML decision page, then interpretively rewrite the clarifying questions and critique docs and upload both to Jira.\n\n## Step 1: Read source documents\n\nRead both files:\n- Evaluation: `{docs_dir}/review/{ticket_key}-review-evaluation.md`\n- Resolution guide: `{docs_dir}/review/{ticket_key}-resolution-guide.md`\n\nIf either file does not exist or is empty, stop and report: \"Review evaluation or resolution guide not found. Run the earlier pipeline steps first.\"\n\n## Step 2: Map evaluation items to decision page input\n\nTransform the evaluation into `generate_decision_page` JSON input using these mapping rules:\n\n| Evaluation Section | JSON Field | Mapping Rule |\n|---|---|---|\n| Open Questions | `actionable_items` | E-item title → `question`, full **Assessment** text → `context`, `**Source**` from the evaluation → `source`, decision tree branch texts from the resolution guide → `options` (string array, labels only), `**Recommendation Index**` from the resolution guide → `recommendation_index` |\n| Needs Scrutiny | `actionable_items` | E-item title → `question`, full **Assessment** text → `context`, `**Source**` from the evaluation → `source`, decision tree branch texts from the resolution guide → `options` (string array, labels only), `**Recommendation Index**` from the resolution guide → `recommendation_index` |\n| Confirmed Improvements | `clear_improvements` | E-item title → `title`, confidence tag → `confidence`, recommended action → `action`, `**Source**` from the evaluation → `source` |\n\n**Important**: The `context` field guides the user's decision, therefore, it is important to present all relevant information to the the user in clear and straightforward terms. Your goal is to make it easy for the user to make a decision. Do not assume the user is familiar with the underlying documents. \n\nFor each actionable item, the `options` array is a list of plain label strings extracted from the resolution guide's decision tree branches. The tool auto-generates value keys (`opt-0`, `opt-1`, etc.) and auto-appends a \"None of these\" option. Do not generate value keys yourself.\n\n## Step 3: Call the MCP tool\n\nCall `generate_decision_page` with:\n- `ticket_key`: `{ticket_key}`\n- `actionable_items`: combined mapped array from Step 2 (each item has `id`, `question`, `context`, `source`, `recommendation_index`, `options`)\n- `clear_improvements`: mapped array from Step 2 (each item has `id`, `title`, `action`, `confidence`, `source`)\n\n## Step 4: Check tool response\n\nThe tool returns a JSON response with a `status` field:\n- If `status` is `\"no_decisions_needed\"`: skip Steps 5, 6, 7, and 8 entirely. Output a success message: \"All suggestions were confirmed as improvements. No decisions needed — skipping doc rewrite and upload.\"\n- If `status` is `\"decision_page_generated\"`: continue to Step 5. The response includes `file_path`.\n\n## Step 5: Direct user to the decision page\n\nTell the user to open the generated HTML file in their browser. Provide the `file_path` from the tool response.\n\n## Step 6: Wait for user input\n\nStop and wait for the user to paste the JSON output from the decision page. Do NOT assume responses. Do NOT proceed until the user provides the JSON.\n\n## Step 7: Interpretively rewrite source documents\n\nThe pasted JSON contains a `decisions` object keyed by item ID. Each decision includes `source`, `choice`, `chosen_label`, and `comment`. Use these fields to locate and rewrite the corresponding sections in:\n- `{docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md`\n- `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md`\n\nAfter a second-opinion run, each document contains two parts: the prior (first-round) analysis at the top, a `\\n\\n---\\n\\n` separator, and a `## Second Opinion` section below. The `source` field tells you where each decided item lives:\n\n- `Clarifying Q3 (prior round)` → the prior analysis section\n- `Clarifying Q2 (prior round, disputed by second opinion > Response to Prior Items)` → the prior analysis section; the decision reconciles the disagreement\n- `Clarifying Q7 (second opinion > Additional Points)` → the `## Second Opinion > ### Additional Points` section\n\nApply the decision to the item in its home section (prior or second-opinion). Then apply the decision:\n\n### Actionable item decisions\n\n- **Selected option** (`choice` is `opt-N`): Add `**Review Decision**: Accepted. <chosen_label>.` to the corresponding section. Integrate the selected direction into the section text so it reads as a final recommendation or resolved answer.\n- **None of these** (`choice` is `none`): Add `**Review Decision**: Rejected — none of the proposed options accepted.` Include the user's `comment` explaining why. Rewrite the section to reflect this decision.\n\nFor actionable items sourced from clarifying questions, rewrite the question's best-guess answer so it reads as the final resolved direction chosen by the reviewer. Do not leave the item framed as an unresolved accept/reject/modify prompt.\n\nFor items sourced from `second opinion > Response to Prior Items` (disputes of a prior-round item), write the decision onto the PRIOR-ROUND item — that is the canonical home for the question — and mark the dispute in the `## Second Opinion` section as resolved (1-sentence note referencing the prior-round decision).\n\n### General comment handling\n\nTreat `general_comment` as overarching guidance that informs the tone and direction of both document rewrites. If it contains specific actionable feedback, weave it into the relevant sections. If it is broad or general, use it as context for how the rewrites should read. Do not create a separate \"General Comment\" or \"Reviewer Notes\" section — the goal is \"final draft\" form.\n\n### Rewrite principles\n\nThe goal is a **final draft** — the documents should read as if they were written with the decisions already made. Do not mechanically append decisions. Instead, lightly rewrite affected sections so they reflect the decisions naturally. Preserve all non-affected sections unchanged. The prior-round section should still read as coherent standalone analysis after integration; the `## Second Opinion` section should remain intact for any items that weren't decided.\n\n## Step 8: Upload to Jira\n\nUpload both updated documents to Jira using `upload_attachment`:\n\n1. Upload clarifying questions:\n   - `ticket_number`: `{ticket_key}`\n   - `file_path`: `{docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md`\n   - `link_type`: `clarifying-questions.md`\n\n2. Upload ticket quality critique:\n   - `ticket_number`: `{ticket_key}`\n   - `file_path`: `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md`\n   - `link_type`: `ticket-quality-critique.md`\n\n## Step 9: Complete\n\nConfirm: \"Review decisions captured and uploaded to {ticket_key}.\"\n\nThis is a single-round process. Do not iterate or ask for additional feedback rounds.\n",
     "commit-and-push.md": "Stage, commit, and push implementation changes for ticket {ticket_key}.\n\nBefore executing, assess the git state and present a clear plan for user approval.\n\n## Step 1 — Assess Git State\n\nRun these commands and note the results:\n- `git branch --show-current` — record the current branch name\n- `git status --porcelain` — identify all modified, added, and untracked files\n\n## Step 2 — Determine Branch\n\nDecide the branching strategy and be prepared to state it explicitly. Cover:\n\n- Whether you will commit on the current branch, or create a new branch.\n- If creating a new branch: the exact new branch name, and which branch it will be created from (current branch vs. `main`).\n- If branching from `main`: whether `main` needs to be pulled/updated first, and the command you will run.\n- Whether the target branch already exists remotely (and if so, whether you will push to the existing remote branch).\n\nDefault rules:\n\n- If the current branch already contains `{ticket_key}` (case-insensitive), plan to commit on the current branch.\n- Otherwise, plan to create a new branch named `feature/{ticket_key}` from the current branch.\n\n## Step 3 — Prepare Commit Details\n\n- Separate implementation files from unrelated changes. Only stage files related to the ticket.\n- Compose a commit message: `{ticket_key}: <brief description of what was implemented>`\n\n## Step 4 — Present Plan for Approval\n\nPresent your plan in this format before proceeding:\n\n```\nCommit Plan for {ticket_key}\n─────────────────────────────\nCurrent branch: <current branch name>\nBranching:      - <\"Commit on current branch\" | \"Create new branch `<name>` from `<source branch>`\">\n                - <if branching from main: \"Pull latest main first via `git checkout main && git pull`\" | omit if N/A>\n                - <\"Remote branch already exists — will push to existing\" | \"New remote branch — will push with -u\" | omit if N/A>\nFiles to stage: <count> files\n                - path/to/file1.py\n                - path/to/file2.py\nExcluded:       <any unrelated changed files, or \"None\">\nCommit message: {ticket_key}: <description>\nPush to:        origin/<target branch>\n```\n\nWait for the user to approve, request changes, or reject. The user may adjust the branch name, exclude files, change the commit message, or give other instructions.\n\nDo not proceed until the user explicitly approves.\n\n## Step 5 — Execute\n\n1. If creating a new branch, run `git checkout -b <branch name>`.\n2. Stage approved files with `git add <file1> <file2> ...` — do not use `git add -A` or `git add .`.\n3. Commit with the approved message.\n4. Push with `git push -u origin <branch>`.\n",
     "decompose-epic.md": "Decompose the epic into manageable sub-tasks and get user approval.\n\n## Epic Description\n\n{epic_description}\n\n## Instructions\n\n1. Read the following artifacts to establish full context. If a file does not exist or is empty, proceed without it:\n   - `{docs_dir}/epic-plans/{epic_slug}/research-findings.md`\n   - `{docs_dir}/epic-plans/{epic_slug}/codebase-exploration.md`\n\n2. Reason about the epic and produce a decomposition. Consider:\n   - Logical groupings of work that can be implemented and tested independently\n   - Dependencies between sub-tasks (what must be built first)\n   - A reasonable scope for each sub-task (each should be achievable in a single implementation session)\n\n3. Write the decomposition to `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md` with this format:\n\n```markdown\n# Epic Decomposition\n\n## Sub-tasks\n\n### 1. {Sub-task title}\n- **Scope**: {What this sub-task covers}\n- **Key files/areas**: {Files and code areas involved}\n- **Dependencies**: {Other sub-task numbers this depends on, or \"None\"}\n\n### 2. {Sub-task title}\n...\n```\n\n4. **Soft limit check**: If the decomposition results in more than 8 sub-tasks, you must verbally warn the user: \"This decomposition has N sub-tasks, which exceeds the recommended limit of 8. Consider splitting this feature into multiple epics.\" Then proceed with the approval flow.\n\n5. Present the decomposition to the user and ask for their feedback. Explain the reasoning behind the breakdown and the dependency ordering.\n\n6. You MUST stop and wait for the user to respond. Do NOT assume approval. Do NOT proceed to the next step.\n\n7. If the user provides feedback or rejects the decomposition:\n   - Incorporate their feedback\n   - Rewrite `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md` with the revised version\n   - Present the revised decomposition and ask for approval again\n   - Repeat until the user explicitly approves\n\n8. Only after explicit user approval, confirm: \"Decomposition approved. Proceeding to sub-task exploration.\"\n",
-    "evaluate-ticket-review.md": "Evaluate the clarifying questions and ticket critiques generated for {ticket_key}, assessing their accuracy and value against the actual codebase.\n\n1. Fetch the current ticket description using the `get_ticket` tool with ticket_number `{ticket_key}`.\n2. Gather all clarifying questions and critiques from the preceding pipeline steps. Both initial and second-opinion rounds may be present — use the MCP call results from the conversation context, since the files on disk at `{docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md` and `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md` only reflect the most recent round.\n3. For each clarifying question and its best-guess answer, verify groundedness against the codebase using file search and code grep. First, determine round agreement by scanning the second-opinion documents for inline `**Prior Round**` tags on each item:\n   - **Both rounds agree**: The item appears in the second-opinion document tagged as `**Prior Round**: Kept` (kept substantially unchanged from the first round).\n   - **Rounds disagree**: The item appears in the second-opinion document tagged as `**Prior Round**: Modified (...)` (materially changed from the first round), OR the item appears in the `### Removed Items` section tagged as `**Prior Round**: Removed (...)`.\n   - **Single round only**: No second opinion exists for this item — either the pipeline ran only one round, or the item is tagged as `**Prior Round**: Added` in the second-opinion document (meaning only the second round produced it).\n   Apply the following depth rules based on round agreement:\n   - **Both rounds agree**: Briefly confirm or refute with a single codebase citation. Keep the assessment to 1-2 sentences.\n   - **Rounds disagree**: Perform deeper analysis — cite 2+ codebase locations, explain the discrepancy, and state which round's position the evidence supports.\n   - **Single round only**: Treat as a disagreement — give full analytical depth.\n   Then categorize:\n   - If the question/answer accurately reflects the codebase, confirm it as grounded with evidence.\n   - If the question/answer misunderstands the codebase (wrong assumptions about architecture, incorrect file references, etc.), call it out with evidence of what the code actually does.\n   - If the question raises a genuine gap that cannot be resolved from the codebase alone, note it as a legitimate open question.\n4. For each critique point (Requested Changes and Points to Consider), determine round agreement using the same `**Prior Round**` tag scanning method from step 3, then apply the same depth rules and assess:\n   - Does it identify a genuine gap or design issue in the ticket? Confirm with codebase evidence.\n   - Is it based on an inaccurate understanding of the existing code? Flag with corrections.\n   - Is it a stylistic preference rather than a substantive improvement? Note as low-priority.\n5. Produce a structured evaluation with three sections, following the formatting rules below. Number each item sequentially across all sections (E-1, E-2, E-3, ...).\n\n## Writing Quality\n\nWrite 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.\n\nStructure each **Assessment** using this three-point approach:\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\nThis structure ensures every assessment tells a complete story rather than assuming the reader already knows what was suggested and why.\n\n## Formatting Rules\n\nEach item must follow this template:\n\n```\n### E-<sequential number>: <concise title>\n\n**Source**: <which clarifying question or critique point this originated from, e.g. \"Clarifying Q3 (initial round)\" or \"Critique: Requested Change 2 (second opinion)\">\n\n**Round Agreement**: <\"both rounds agree\" | \"rounds disagree\" | \"single round only\"> — <if disagreeing, 1 sentence on what the disagreement is>\n\n**Assessment**: <see depth calibration and writing quality rules>\n\n**Codebase Evidence**:\n- `path/to/file.ts:42` — <what this line/block demonstrates>\n- `path/to/other.ts:110-125` — <what this range demonstrates>\n\n<If no direct codebase evidence exists, state: \"No direct codebase evidence found.\">\n```\n\n**Depth calibration**: When Round Agreement is \"both rounds agree\", keep Assessment to 1-2 sentences and Codebase Evidence to 1 citation. When Round Agreement is \"rounds disagree\" or \"single round only\", Assessment should be 3-4 sentences and Codebase Evidence should cite 2+ files explaining the discrepancy.\n\n## Example of a Well-Written E-Item\n\n### E-3: Missing retry logic for webhook delivery\n\n**Source**: Critique: Requested Change 1 (second opinion)\n\n**Round Agreement**: both rounds agree\n\n**Assessment**: Both rounds flagged that the ticket does not specify retry behavior when webhook delivery fails. The codebase already implements exponential backoff in the notification service (`src/services/notifications.py:87-102`), confirming that retry logic is an established pattern and the ticket should explicitly require it for consistency.\n\n**Codebase Evidence**:\n- `src/services/notifications.py:87-102` — existing `retry_with_backoff()` helper uses exponential backoff with a base of 2 seconds and max 3 retries for outbound HTTP calls\n\n## Example of a Well-Written E-Item (Rounds Disagree)\n\n### E-5: Authentication middleware placement for new endpoint\n\n**Source**: Clarifying Q2 (initial round)\n\n**Round Agreement**: rounds disagree — Round 1 recommended adding auth at the router level; Round 2 argued the existing middleware stack already covers it.\n\n**Assessment**: The initial 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 round disagreed, claiming the existing 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` — each router must opt in via `Depends(require_api_key)`. This supports the first round's position: the new endpoint needs an explicit auth dependency.\n\n**Codebase Evidence**:\n- `main.py:45-52` — global middleware applies rate limiting and CORS, but not authentication\n- `api/routes/__init__.py:18-30` — each router includes its own auth dependency; there is no catch-all auth middleware\n\n## Output Sections\n\n- **Confirmed Improvements**: Suggestions that are grounded and would genuinely improve the ticket by closing significant gaps or correcting design issues.\n- **Needs Scrutiny**: Suggestions based on inaccurate codebase assumptions, with evidence of the actual code behavior.\n- **Open Questions**: Legitimate ambiguities that require human input to resolve.\n\n6. Save the evaluation to `{docs_dir}/review/{ticket_key}-review-evaluation.md`. Output only the structured evaluation — no meta-commentary.\n",
+    "evaluate-ticket-review.md": "Evaluate the clarifying questions and ticket critiques generated for {ticket_key}, assessing their accuracy and value against the actual codebase.\n\n1. Fetch the current ticket description using the `get_ticket` tool with ticket_number `{ticket_key}`.\n2. Gather the clarifying questions and critique documents from the preceding pipeline steps. Prefer the concatenated output captured in the conversation by the `request_ticket_review` calls. If the second-opinion round ran, each saved document is structured as:\n   - The prior (first-round) analysis verbatim\n   - A `\\n\\n---\\n\\n` separator\n   - A `## Second Opinion` section produced by the second-round model\n\n   Parse each document accordingly before applying the rules below. The local files at `{docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md` and `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md` will also hold this concatenated form after a second-opinion run.\n3. For each clarifying question and its best-guess answer, verify groundedness against the codebase using file search and code grep. First, determine **Round Agreement** using these rules:\n\n   - **Single round only** — the document has no `## Second Opinion` section (pipeline ran only one round).\n   - **Both rounds agree** — the item is in the prior (first-round) section AND the `## Second Opinion > ### Response to Prior Items` list does NOT reference it. Silence in the response list means the second round concurred.\n   - **Rounds disagree** — the item is in the prior section AND the `## Second Opinion > ### Response to Prior Items` list references it with a `refinement` or `disagreement` tag (not a bare `concurrence`).\n   - **Gap captured** — the item is NOT in the prior section; it appears inside `## Second Opinion > ### Additional Points` (a new item the second round surfaced). Apply the two-axis check below.\n\n   Apply these depth and categorization rules:\n\n   - **Both rounds agree**: Briefly confirm or refute with a single codebase citation. Keep the assessment to 1-2 sentences. Categorize as Confirmed Improvement if grounded, otherwise Needs Scrutiny.\n   - **Rounds disagree**: Cite 2+ codebase locations, explain which position the evidence supports, and categorize based on which round prevails. Include both positions (prior-round and second-opinion) in the Assessment.\n   - **Gap captured — two-axis check** (for items in `### Additional Points`):\n       - If both the question is grounded in the codebase/standards AND the best-guess answer is sensible → **Confirmed Improvement** with a 1-2 sentence assessment and 1 citation. Round Agreement value: `gap captured`.\n       - If the question is genuine but the best-guess answer is flawed → **Needs Scrutiny**. Cite 2+ files. Round Agreement value: `rounds disagree`.\n       - If the question itself does not hold up → **Needs Scrutiny** with evidence of what the code actually does. Round Agreement value: `rounds disagree`.\n       - If neither codebase nor standards can settle the question → **Open Questions**. Round Agreement value: `rounds disagree`.\n   - **Single round only**: Treat as a disagreement — cite 2+ codebase locations and give full analytical depth.\n\n   Then categorize per normal rules:\n   - Question/answer accurately reflects the codebase → grounded, confirm.\n   - Question/answer misunderstands the codebase → call out with corrective evidence.\n   - Question raises a genuine gap unresolvable from the codebase alone → Open Question.\n\n4. For each critique point (Requested Changes and Points to Consider), apply the same Round Agreement rules from step 3. Items in the prior section's `### Requested Changes` / `### Points to Consider` are \"kept\" unless the `## Second Opinion > ### Response to Prior Items` list addresses them with refinement/disagreement. Items in `## Second Opinion > ### Additional Points > New Requested Changes` and `New Points to Consider` are \"gap captured\" (apply the two-axis check). Assess each:\n   - Does it identify a genuine gap or design issue in the ticket? Confirm with codebase evidence.\n   - Is it based on an inaccurate understanding of the existing code? Flag with corrections.\n   - Is it a stylistic preference rather than a substantive improvement? Note as low-priority.\n\n5. Produce a structured evaluation with three sections, following the formatting rules below. Number each item sequentially across all sections (E-1, E-2, E-3, ...).\n\n## Writing Quality\n\nWrite 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.\n\nStructure each **Assessment** using this three-point approach:\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\nThis structure ensures every assessment tells a complete story rather than assuming the reader already knows what was suggested and why.\n\n## Formatting Rules\n\nEach item must follow this template:\n\n```\n### E-<sequential number>: <concise title>\n\n**Source**: <which clarifying question or critique point this originated from, e.g. \"Clarifying Q3 (prior round)\", \"Critique: Requested Change 2 (second opinion > Response to Prior Items)\", or \"Clarifying Q7 (second opinion > Additional Points)\">\n\n**Round Agreement**: <\"both rounds agree\" | \"rounds disagree\" | \"gap captured\" | \"single round only\"> — <if disagreeing, 1 sentence on what the disagreement is; if \"gap captured\", 1 sentence noting what the second round surfaced>\n\n**Assessment**: <see depth calibration and writing quality rules>\n\n**Codebase Evidence**:\n- `path/to/file.ts:42` — <what this line/block demonstrates>\n- `path/to/other.ts:110-125` — <what this range demonstrates>\n\n<If no direct codebase evidence exists, state: \"No direct codebase evidence found.\">\n```\n\n**Depth calibration**:\n- When Round Agreement is `both rounds agree` or `gap captured`, keep Assessment to 1-2 sentences and Codebase Evidence to 1 citation — the second round (or consensus) already did the heavy lifting.\n- When Round Agreement is `rounds disagree` 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 `rounds disagree` depth, not the `gap captured` depth, because the reviewer needs full evidence of where the issue or recommendation misses.\n\n## Example of a Well-Written E-Item\n\n### E-3: Missing retry logic for webhook delivery\n\n**Source**: Critique: Requested Change 1 (prior round)\n\n**Round Agreement**: both rounds agree\n\n**Assessment**: The prior round flagged that the ticket does not specify retry behavior when webhook delivery fails; the second round did not dispute it. The codebase already implements exponential backoff in the notification service (`src/services/notifications.py:87-102`), confirming retry logic is an established pattern and the ticket should explicitly require it for consistency.\n\n**Codebase Evidence**:\n- `src/services/notifications.py:87-102` — existing `retry_with_backoff()` helper uses exponential backoff with a base of 2 seconds and max 3 retries for outbound HTTP calls\n\n## Example of a Well-Written E-Item (Rounds Disagree)\n\n### E-5: Authentication middleware placement for new endpoint\n\n**Source**: Clarifying Q2 (prior round, disputed by second opinion > Response to Prior Items)\n\n**Round Agreement**: rounds disagree — the prior round recommended adding auth at the router level; the second opinion argued the existing middleware stack already covers it.\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` — 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` — global middleware applies rate limiting and CORS, but not authentication\n- `api/routes/__init__.py:18-30` — 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)\n\n### E-7: Missing Alembic migration for new role-scope column\n\n**Source**: Critique: Requested Change N+1 (second opinion > Additional Points > New Requested Changes)\n\n**Round Agreement**: gap captured — 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/` — all schema changes land here as autogenerated revisions\n\n## Output Sections\n\n- **Confirmed Improvements**: Suggestions that are grounded and would genuinely improve the ticket by closing significant gaps or correcting design issues. Includes `gap captured` items (sound second-opinion additions with sound recommendations).\n- **Needs Scrutiny**: Suggestions based on inaccurate codebase assumptions, with evidence of the actual code behavior. Includes `gap captured` items that failed either axis of the two-axis check.\n- **Open Questions**: Legitimate ambiguities that require human input to resolve.\n\n6. Save the evaluation to `{docs_dir}/review/{ticket_key}-review-evaluation.md`. Output only the structured evaluation — no meta-commentary.\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",
     "execute-plan.md": "Execute the AI-generated implementation plan for ticket {ticket_key}.\n\n---\n\n## Step 1 — Load and Enumerate the Plan\n\n1. Read the plan from `{docs_dir}/plans/{ticket_key}-plan.md`.\n2. Count the total number of implementation steps in the plan.\n3. Announce: **\"Plan contains N steps.\"**\n\n## Step 2 — 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 — <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` — 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 — Final Audit\n\nAfter all steps are executed:\n\n1. Re-read the plan file at `{docs_dir}/plans/{ticket_key}-plan.md`.\n2. Compare the plan against the work completed. Verify every step was addressed.\n3. List any steps that were skipped or only partially completed, with reasons.\n4. Announce: **\"Audit complete — N of N steps fully addressed.\"** (or note discrepancies).\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. Use `Glob`, `Grep`, and `Read` tools to search for:\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",
@@ -545,7 +520,7 @@ export const INSTRUCTIONS = {
     "learn-template-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for template files, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `template_correctness`\n- **Field name**: `template_correctness_standards`\n- **Scope**: Template files: HTML, Jinja2, Handlebars, EJS, ERB, Blade, Pug, Twig.\n\n## Instructions\n\n### Phase 1 — Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Use Glob to find files matching `**/*.html`, `**/*.jinja2`, `**/*.j2` in `templates/` and similar directories (excluding `node_modules/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative template files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 — Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/template_correctness_standards.md`.\n",
     "learn-unit-testing.md": "## Objective\n\nExplore the codebase to identify the test runner, assertion library, mocking framework, and testing patterns, then draft `unit_testing_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 — Explore Testing Infrastructure\n\n1. **Test Runner and Framework Detection**: Search for test runner configs (`pytest.ini`, `pyproject.toml` `[tool.pytest]` section, `jest.config.*`) and read `package.json` test scripts. Read the `tests/` directory structure.\n\n2. **Testing Patterns**: Read 3-5 representative test files in `tests/pytest/` to identify:\n   - Assertion library and style (`assert`, `expect`, custom matchers)\n   - Mocking framework (`unittest.mock`, `jest.mock`, `sinon`, etc.)\n   - Fixture patterns (setup/teardown)\n   - Test organization (by module, feature, layer)\n   - Exemplary tests vs. weak tests\n\n3. **How to Run Tests**: Read `pyproject.toml`, `package.json`, and `Makefile` (if present) to determine exact commands for: full suite, single file, by name pattern, with verbose output.\n\n4. **Mocking vs. Fidelity**: Read test helper files in `tests/pytest/helpers/` to document how external APIs are mocked, whether integration tests exist alongside unit tests, and patterns for avoiding third-party calls in tests.\n\n### Phase 2 — Draft\n\nDraft `unit_testing_instructions` as clear, actionable instructions for an AI agent writing unit tests. Cover:\n- How to run tests (exact commands)\n- Which test framework and assertion library to use\n- How to mock external dependencies without calling third parties\n- How to structure test files and test functions\n- What constitutes a thorough test (not just happy path)\n- How to avoid shallow tests that pass but don't verify meaningful behavior\n- Guards against common AI weaknesses: tests that mock the thing being tested, trivially passing assertions, overly complex setup\n\nWrite the draft to `{docs_dir}/standards/unit_testing_instructions.md`.\n",
     "monitor-ci-checks.md": "Monitor CI checks for the most recent commit.\n\n1. Run `git rev-parse HEAD` to get the current commit SHA.\n2. Call the `resolve_ci_checks` tool with the commit SHA as `commit_ref`. This discovers and classifies the CI checks for the repository.\n3. Poll CI status by calling `poll_ci_checks` with the same `commit_ref`. Check the response for `all_complete` and `all_passed`.\n4. If checks are not yet complete, wait 30 seconds and poll again. Repeat until all checks are complete or 10 minutes have elapsed.\n5. If all checks pass, report success.\n6. If any checks fail, report which checks failed and include any available annotations or log details from the poll response. Do NOT attempt to fix failures — just report them clearly.\n\n## Polling Directive\n\nDuring the polling loop, execute `sleep 30` silently. Do NOT output any inline commentary, reasoning, or partial status updates between polls. Only output a status message when:\n- All checks are complete (pass or fail), OR\n- The 10-minute timeout is reached.\n\nThis minimizes context window consumption during long-running CI waits.\n",
-    "recommend-ticket-resolutions.md": "Read the evaluation produced by the previous pipeline step and generate a resolution guide for {ticket_key}.\n\n1. Read the evaluation from `{docs_dir}/review/{ticket_key}-review-evaluation.md`.\n2. Fetch the current ticket description using the `get_ticket` tool with ticket_number `{ticket_key}` for context.\n3. Before processing individual items, produce the following executive summary at the top of the output file:\n\n## TL;DR: Items Needing Your Decision\n\nList every item from the Needs Scrutiny and Open Questions sections of the evaluation, one bullet each:\n\n- **E-<number>: <title>** — <1-sentence summary of what decision is needed>\n\nIf both sections are empty, write: \"No decisions needed — all suggestions were confirmed as improvements.\"\n\n4. Process each item from the evaluation according to its section, following the rules below.\n\n## Needs Scrutiny\n\nFor each item in the Needs Scrutiny section, produce:\n\n```\n### E-<number>: <title from evaluation>\n\n**Confidence**: <High/Medium/Low>\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**Recommendation**: <which branch the evidence best supports and why, 1-2 sentences>\n```\n\n## Open Questions\n\nFor each item in the Open Questions section, produce:\n\n```\n### E-<number>: <title from evaluation>\n\n**Confidence**: <High/Medium/Low>\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` (if available). <1-2 sentence rationale.>\n- If <condition 2>, then <action 2>. See `file:line` (if available). <1-2 sentence rationale.>\n\n**Recommendation Index**: <0-based index of the recommended branch in the decision tree above>\n**Recommendation**: <best guess at resolution path and why, or \"Insufficient evidence — escalate to <suggested stakeholder role>\", 1-2 sentences>\n```\n\n## Confirmed Improvements\n\nRender each Confirmed Improvement as a single bullet in a compact list. No headings per item, no decision trees, no rationale paragraphs.\n\n- **E-<number>: <title>** (Confidence: <High/Medium/Low>) — <recommended action, 1 sentence>\n\n## Round Agreement Summary\n\nAfter all items are processed, produce a summary section that groups items by round agreement status from the evaluation:\n\n### Points of Disagreement\nFor items where the evaluation marked \"rounds disagree\" or \"single round only\": 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\nFor items where the evaluation marked \"both rounds agree\": list as bullets with the E-number and a half-sentence noting the shared conclusion. These items required minimal analysis and are lower risk.\n\n## Decision Tree Rules\n\n- Each decision tree must have 2-4 branches. Do not exceed 4.\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- **\"resolve at your desk\"**: The item can be resolved through technical investigation — 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\n\nAssign confidence based on codebase evidence strength from the evaluation:\n- **High**: The evaluation cites specific `file:line` references that directly support the assessment.\n- **Medium**: The evaluation references 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## 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 the evaluation does not contain Round Agreement fields (e.g., it was generated before this format), infer agreement status from the Source field: if both rounds are cited with the same conclusion, treat as agreement; if only one round is cited or they conflict, treat as disagreement.\n\n5. Save the resolution guide to `{docs_dir}/review/{ticket_key}-resolution-guide.md`. Output only the resolution guide — no meta-commentary.\n",
+    "recommend-ticket-resolutions.md": "Read the evaluation produced by the previous pipeline step and generate a resolution guide for {ticket_key}.\n\n1. Read the evaluation from `{docs_dir}/review/{ticket_key}-review-evaluation.md`.\n2. Fetch the current ticket description using the `get_ticket` tool with ticket_number `{ticket_key}` for context.\n3. Before processing individual items, produce the following executive summary at the top of the output file:\n\n## TL;DR: Items Needing Your Decision\n\nList every item from the Needs Scrutiny and Open Questions sections of the evaluation, one bullet each:\n\n- **E-<number>: <title>** — <1-sentence summary of what decision is needed>\n\nIf both sections are empty, write: \"No decisions needed — all suggestions were confirmed as improvements.\"\n\n4. Process each item from the evaluation according to its section, following the rules below.\n\n## Needs Scrutiny\n\nFor each item in the Needs Scrutiny section, produce:\n\n```\n### E-<number>: <title from evaluation>\n\n**Confidence**: <High/Medium/Low>\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**Recommendation**: <which branch the evidence best supports and why, 1-2 sentences>\n```\n\n## Open Questions\n\nFor each item in the Open Questions section, produce:\n\n```\n### E-<number>: <title from evaluation>\n\n**Confidence**: <High/Medium/Low>\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` (if available). <1-2 sentence rationale.>\n- If <condition 2>, then <action 2>. See `file:line` (if available). <1-2 sentence rationale.>\n\n**Recommendation Index**: <0-based index of the recommended branch in the decision tree above>\n**Recommendation**: <best guess at resolution path and why, or \"Insufficient evidence — escalate to <suggested stakeholder role>\", 1-2 sentences>\n```\n\n## Confirmed Improvements\n\nRender each Confirmed Improvement as a single bullet in a compact list. No headings per item, no decision trees, no rationale paragraphs.\n\n- **E-<number>: <title>** (Confidence: <High/Medium/Low>) — <recommended action, 1 sentence>\n\n## Round Agreement Summary\n\nAfter all items are processed, produce a summary section that groups items by round agreement status from the evaluation:\n\n### Points of Disagreement\nFor items where the evaluation marked `rounds disagree` or `single round only` — including `gap captured` items that failed the two-axis check and landed in Needs Scrutiny — 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\nFor items where the evaluation marked `both rounds agree`: list as bullets with the E-number and a half-sentence noting the shared conclusion. These items required minimal analysis and are lower risk.\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 — they are already in Confirmed Improvements — 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## Decision Tree Rules\n\n- Each decision tree must have 2-4 branches. Do not exceed 4.\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- **\"resolve at your desk\"**: The item can be resolved through technical investigation — 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\n\nAssign confidence based on codebase evidence strength from the evaluation:\n- **High**: The evaluation cites specific `file:line` references that directly support the assessment.\n- **Medium**: The evaluation references 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## 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 the evaluation does not contain Round Agreement fields (e.g., it was generated before this format), infer agreement status from the Source field: if both prior and second-opinion sections contain the item with the same conclusion, treat as agreement; if only one section is cited or the two conflict, treat as disagreement.\n\n5. Save the resolution guide to `{docs_dir}/review/{ticket_key}-resolution-guide.md`. Output only the resolution guide — no meta-commentary.\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 — 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 — no meta-commentary.\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\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.}\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## 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"
 };

package/build/version.generated.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.1.10";
+export const VERSION = "0.1.12";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",

package/pipelines/review-ticket.json

@@ -11,44 +11,19 @@
     },
     {
       "type": "mcp_call",
-      "tool": "request_clarifying_questions",
+      "tool": "request_ticket_review",
       "params": {
         "ticket_number": "{ticket_key}",
         "wait_for_result": true,
         "save_locally": true,
         "provider": "{provider}"
       },
-      "description": "Generate clarifying questions (initial)",
+      "description": "Generate combined clarify+critique review (initial)",
       "on_error": "warn_and_continue"
     },
     {
       "type": "mcp_call",
-      "tool": "request_ticket_critique",
-      "params": {
-        "ticket_number": "{ticket_key}",
-        "wait_for_result": true,
-        "save_locally": true,
-        "provider": "{provider}"
-      },
-      "description": "Generate ticket quality critique (initial)",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "tool": "request_clarifying_questions",
-      "params": {
-        "ticket_number": "{ticket_key}",
-        "second_opinion": "auto",
-        "wait_for_result": true,
-        "save_locally": true,
-        "provider": "{provider}"
-      },
-      "description": "Generate clarifying questions (second opinion)",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "tool": "request_ticket_critique",
+      "tool": "request_ticket_review",
       "params": {
         "ticket_number": "{ticket_key}",
         "second_opinion": "auto",
@@ -56,7 +31,7 @@
         "save_locally": true,
         "provider": "{provider}"
       },
-      "description": "Generate ticket quality critique (second opinion)",
+      "description": "Generate combined clarify+critique review (second opinion)",
       "on_error": "warn_and_continue"
     },
     {