@bridge_gpt/mcp-server 0.1.12 → 0.1.13

package/build/pipelines.generated.js

@@ -21,14 +21,9 @@ export const PIPELINES = {
                 "requires_approval": true
             },
             {
-                "type": "mcp_call",
-                "tool": "create_pull_request",
-                "params": {
-                    "head_branch": "feature/{ticket_key}",
-                    "base_branch": "main",
-                    "title": "{ticket_key}: Implementation"
-                },
-                "description": "Create a pull request",
+                "type": "agent_task",
+                "instruction_file": "create-pr.md",
+                "description": "Create a pull request with a title derived from the commit subject",
                 "requires_approval": true
             },
             {
@@ -75,14 +70,9 @@ export const PIPELINES = {
                 "requires_approval": true
             },
             {
-                "type": "mcp_call",
-                "tool": "create_pull_request",
-                "params": {
-                    "head_branch": "feature/{ticket_key}",
-                    "base_branch": "main",
-                    "title": "{ticket_key}: Implementation"
-                },
-                "description": "Create a pull request",
+                "type": "agent_task",
+                "instruction_file": "create-pr.md",
+                "description": "Create a pull request with a title derived from the commit subject",
                 "requires_approval": true
             },
             {
@@ -430,21 +420,16 @@ export const PIPELINES = {
                 "requires_approval": true
             },
             {
-                "type": "mcp_call",
-                "tool": "create_pull_request",
-                "params": {
-                    "head_branch": "feature/{ticket_key}",
-                    "base_branch": "main",
-                    "title": "{ticket_key}: Implementation"
-                },
-                "description": "Create a pull request",
+                "type": "agent_task",
+                "instruction_file": "create-pr.md",
+                "description": "Create a pull request with a title derived from the commit subject",
                 "requires_approval": true
             }
         ]
     },
     "review-ticket": {
         "name": "review-ticket",
-        "description": "Review a ticket with two rounds of analysis (initial + second opinion), evaluate suggestions for accuracy, and produce a resolution guide with decision trees.",
+        "description": "Review a ticket with two rounds of analysis (initial + second opinion), evaluate suggestions for accuracy, and produce a combined review-and-resolution document with decision trees.",
         "variables": [
             "ticket_key",
             "docs_dir"
@@ -483,13 +468,8 @@ export const PIPELINES = {
             },
             {
                 "type": "agent_task",
-                "instruction_file": "evaluate-ticket-review.md",
-                "description": "Evaluate review suggestions against the codebase for groundedness and value"
-            },
-            {
-                "type": "agent_task",
-                "instruction_file": "recommend-ticket-resolutions.md",
-                "description": "Produce a resolution guide with decision trees and confidence-tagged recommendations"
+                "instruction_file": "evaluate-and-recommend.md",
+                "description": "Evaluate ticket-review findings against the codebase and produce the combined review-and-resolution document at {docs_dir}/review/{ticket_key}-review-and-resolution.md"
             },
             {
                 "type": "agent_task",
@@ -501,10 +481,11 @@ 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\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",
+    "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 the combined review-and-resolution file:\n- `{docs_dir}/review/{ticket_key}-review-and-resolution.md`\n\nIf the file does not exist or is unreadable, stop and report: \"Combined review-and-resolution file not found or unreadable. Run the earlier pipeline steps first.\"\n\nThe combined file existing but containing no actionable items (empty `Needs Scrutiny` and `Open Questions` sections) is **not** a failure condition — Step 4 handles the no-decisions-needed flow gracefully when `generate_decision_page` is called with empty `actionable_items`.\n\n## Step 2: Map evaluation items to decision page input\n\nTransform the combined review-and-resolution document 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`, `**Source**` → `source`, `**Original question**` → `original_question`, `**Why it matters**` → `why_it_matters`, decision tree branch labels → `options` (string array, labels only), `**Option consequences**` (parallel to branches) → `option_consequences`, `**Recommendation explanation**` → `recommendation_explanation`, combined `**Assessment**` paragraph and `**Codebase Evidence**` bullet list → `codebase_evidence`, `**Recommendation Index**` → `recommendation_index` |\n| Needs Scrutiny | `actionable_items` | E-item title → `question`, `**Source**` → `source`, `**Original question**` → `original_question`, `**Why it matters**` → `why_it_matters`, decision tree branch labels → `options` (string array, labels only), `**Option consequences**` (parallel to branches) → `option_consequences`, `**Recommendation explanation**` → `recommendation_explanation`, combined `**Assessment**` paragraph and `**Codebase Evidence**` bullet list → `codebase_evidence`, `**Recommendation Index**` → `recommendation_index` |\n| Confirmed Improvements | `clear_improvements` | E-item title → `title`, confidence tag → `confidence`, recommended action → `action`, `**Source**` from the combined file → `source` |\n\n**Important**: The `original_question`, `why_it_matters`, `option_consequences`, `recommendation_explanation`, and the collapsed `codebase_evidence` block together replace the old single `context` blob. Each clarity field guides a different facet of the user's decision: `original_question` reminds the reviewer what was asked, `why_it_matters` frames the impact, `option_consequences` describe the behavioral outcome of each branch, `recommendation_explanation` motivates the recommended branch, and the closed-by-default `codebase_evidence` block surfaces the Assessment + file:line citations on demand without overwhelming the card.\n\nFor each actionable item, the `options` array is a list of plain label strings extracted from the combined file'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`, `original_question`, `why_it_matters`, `options`, `option_consequences`, `recommendation_explanation`, `codebase_evidence`, `source`, and `recommendation_index`)\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: \"No actionable review decisions needed — skipping doc rewrite and upload.\" This covers both the case where every item was confirmed as a Confirmed Improvement and the case where no items were emitted (e.g., both upstream source documents were absent).\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. Then say to the user, verbatim: `Open the page. For any item you're unsure about, choose \"Ask about this\" — when you submit, I'll talk through those before we proceed. You can also ask me questions in chat before submitting if you prefer.`\n\nThis step only directs the user to the page and explains the two allowed next actions (submit selections, or ask questions first). Do not describe Step 7's rewrite semantics here; that belongs to the rewrite step.\n\n## Step 6: Q&A loop and commit signal\n\nEnter an open-ended Q&A loop. There is no turn cap — the user may ask any number of questions in any number of turns. Do not stop and wait silently; engage with each user message as either a commit signal or a discussion turn.\n\n### Proceed signal (commit)\n\nTrim the full user message and attempt to parse the entire trimmed message as JSON. The message is a commit only when the parsed value is an object with all three of these top-level fields:\n\n- `ticket_key` — must be a string\n- `decisions` — must be an object\n- `general_comment` — must be a string\n\nThe first valid commit-shaped JSON paste commits immediately. Proceed to Step 7 without prompting for additional confirmation. Any combination of `decisions` keys is accepted (the page may submit a partial set if the user only resolved some items conversationally). Do not over-validate the per-card fields beyond the top-level commit-shape check — the page guarantees the per-card schema, and over-validating risks rejecting valid pastes if the page schema evolves.\n\n### Discussion signal (Q&A turn)\n\nAnything that is not commit-shaped JSON is a discussion turn. This includes:\n\n- Freeform questions (with or without other text).\n- Questions pasted alongside other text or alongside JSON.\n- Malformed JSON (parse failure).\n- Well-formed JSON missing one or more of the required top-level keys (`ticket_key`, `decisions`, `general_comment`).\n\nFor JSON-shaped input that is missing required top-level fields, call this out in the reply — explain which fields are missing and ask whether the user intended to submit or share partial state — rather than silently treating it as a freeform question.\n\nAnswer discussion turns using these sources, in priority order:\n\n1. The combined `{ticket_key}-review-and-resolution.md` file already read in Step 1.\n2. The original `{ticket_key}-clarifying-questions.md` and `{ticket_key}-ticket-quality-critique.md` documents.\n3. Codebase lookups when the question requires verifying current code state.\n\nFallback: if running on a pre-PR1 branch where the combined review-and-resolution document does not exist, use the pre-PR1 `{ticket_key}-review-evaluation.md` and `{ticket_key}-resolution-guide.md` pair in its place.\n\nFor plain freeform questions, infer the item from chat context when possible.\n\n### In-flight decision state\n\nDuring the Q&A loop, maintain in-flight JSON state — agent-owned working memory representing the user's current intent for `decisions` and `general_comment`. This in-flight JSON state lives only in the agent's working memory for the duration of the loop; do not persist it server-side.\n\n- When the user clearly changes their mind about an item, chooses an option conversationally with reasonably explicit decision language (\"choose option B for E-3\", \"go with the configurable timeout\", \"change E-7 to None of these\"), or gives new overarching guidance, record that as an in-flight override.\n- Ambiguous preference language (\"I'm leaning toward...\", \"maybe option B is fine\") should be discussed but not recorded as an override unless the user gives reasonably explicit decision language.\n- `general_comment` may be updated in the in-flight state when the user gives overarching guidance during Q&A.\n- The page's general-comment textarea is preserved unchanged. Do not modify the page DOM during Q&A; the user can still fill the textarea before submitting if they prefer.\n\nOn the eventual JSON commit, the user-submitted JSON is the baseline and the recorded in-flight overrides take precedence over it. Before proceeding to Step 7, post a brief one-line acknowledgement in chat naming each overridden item ID and/or `general_comment`. The acknowledgement is mandatory (not optional) — it is the user's last chance to object before Step 7's document rewrite. The user does not need to re-open, edit, or re-submit the decision page after changing their mind in chat; they can submit the page as-is to provide the commit signal, and the in-flight state remains the source of truth for overrides.\n\n### Ask-about-this resolution\n\nAfter accepting a commit, scan `decisions` for any item where `choice === \"ask\"`. The user has signaled that they need more information before deciding on those items. For each such item:\n\n- If `comment` is non-empty, treat it as the user's specific question or stated uncertainty and answer that directly.\n- If `comment` is empty, proactively present the most relevant missing context — the item's `codebase_evidence`, related code lookups, prior-round answers — and lay out the trade-offs the user appears to need help weighing.\n- Continue the Q&A turn-by-turn until the user gives an explicit decision in chat for that item (\"go with option B\", \"none of these, because …\"). Record that decision as an in-flight override using the same override mechanism described above.\n\n**Hard rule.** Step 7 must not run while any `decisions[*].choice === \"ask\"` remains unresolved by an in-flight override. Do not honor \"just proceed\", \"skip those\", or any other instruction to defer resolution — every `ask` item must end with a recorded `opt-N` or `none` override before the rewrite step. The pre-Step-7 acknowledgement line lists every overridden item, including the ones resolved out of `ask`.\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 has this shape:\n\n- A top-level H1 (`# Ticket Analysis` or `# Ticket Quality Critique`) followed by an italic provider-attribution line `_This analysis was generated by GPT|Claude|Gemini._` naming the first-round LLM family. **Preserve this attribution line verbatim** — do not move, edit, or remove it during the rewrite step.\n- The first-round questions / critique items, exactly as written by the first-round model.\n- **Inline second-opinion blockquotes** (`> **Second opinion (<provider>) - concurrence|refinement|disagreement.** ... > *Citations: ...*`) nested directly under each prior item the second round addressed. The `(<provider>)` parenthetical is the second-round LLM family (`GPT|Claude|Gemini`). Items the second round did not comment on have no blockquote — that is the \"weak concurrence\" signal.\n- A **`## New in Second Opinion`** tail block listing items the second round added on top of the first round. Immediately under the H2 there is a second italic attribution line `_These additional points were raised by GPT|Claude|Gemini._` naming the second-round family — **also preserve this verbatim**. Then agent-specific sub-headings:\n  - Clarifier docs: `### New Requirements Questions` / `### New Technical Questions` (numbering continues from the prior section).\n  - Critique docs: `### New Requested Changes` / `### New Points to Consider` (numbering continues from the prior section).\n- A final **`## Second Opinion Summary`** footer (1-3 sentences). **This footer must be preserved verbatim** — it is the canonical record of the second round's overall position and should not be edited.\n\nThe `source` field on each decision tells you where the item lives:\n\n- `Clarifying Q3 (prior round, weak concurrence)` → the prior section, no inline blockquote. Rewrite the prior item's answer.\n- `Clarifying Q9 (prior round, concurrence inline)` → the prior section, prior item carries an explicit `concurrence` blockquote. Rewrite the prior answer; the blockquote can be removed once the answer absorbs the resolution.\n- `Clarifying Q3 (prior round, refinement inline)` / `(prior round, disagreement inline)` → the prior section, prior item carries an explicit `refinement` or `disagreement` blockquote. Rewrite the prior answer to reconcile the dispute, then handle the blockquote per the rule below.\n- `Clarifying Q11 (new in second opinion → New Requirements Questions)` → the `## New in Second Opinion > ### New Requirements Questions` sub-section. Rewrite the item in place inside that sub-section, not at the top of the prior analysis.\n- Equivalent forms for critique items: `Critique: Requested Change 2 (prior round, refinement inline)`, `Critique: Points to Consider N+1 (new in second opinion → New Points to Consider)`, etc.\n\n**Legacy fallback shape**: if the document instead ends with `\\n\\n---\\n\\n` followed by a `## Second Opinion` section (because the JSON pipeline fell back), apply decisions to the equivalent location: `### Response to Prior Items` for inline-style responses, `### Additional Points > New X` for tail-style new items. Preserve the `\\n\\n---\\n\\n` separator and the `## Second Opinion` heading verbatim.\n\nApply the decision to the item in its home location. 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 `(prior round, refinement inline)` or `(prior round, disagreement inline)` — disputes of a prior-round item carried in an inline blockquote — the prior-round item is the canonical home: rewrite its answer to absorb the resolution. Then handle the blockquote in one of two ways: (a) remove the blockquote outright if the rewritten answer fully absorbs the second-opinion content, or (b) shorten the blockquote to a single sentence noting the resolution while preserving the `(<provider>)` attribution (e.g. `> **Second opinion (Claude) - refinement.** Resolved by reviewer decision E-N.`). Citations from the original blockquote may be promoted into the rewritten prior-item answer if useful — keep the strongest 1-2 grounding refs.\n\nFor items sourced from `(new in second opinion → ...)` — gap-captured items that received a decision — rewrite the item in place inside its tail-block sub-section (`## New in Second Opinion > ### New X`), not at the top of the prior analysis. Preserve the sub-section heading and continued numbering.\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 content should still read as coherent standalone analysis after integration. Preserve the `## New in Second Opinion` tail block intact for any items that weren't decided. **Always preserve the `## Second Opinion Summary` footer verbatim** — it is the canonical record of the second round's overall position and should not be edited even when individual items it references have been resolved.\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",
     "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",
+    "create-pr.md": "# Create a pull request for the just-pushed branch\n\nThe implementation has been committed and pushed. Open a PR against `main` for the current branch, with a descriptive title derived from the commit you just made.\n\n## Step 1 — Read the commit subject line\n\nRun `git log -1 --pretty=%s` to get the most recent commit subject. The implement-ticket pipeline asks the commit step to use the form `{ticket_key}: <description>`, so this line is normally already a good PR title.\n\n## Step 2 — Compose the PR title\n\n- Default to the verbatim commit subject as the PR title.\n- If the commit subject is generic (e.g. ends in just \"Implementation\" or \"implement {ticket_key}\") and the diff has a clearer story, you may write a more descriptive title that still starts with `{ticket_key}: `.\n- Keep the title under 70 characters when reasonable. Trim trailing punctuation.\n\n## Step 3 — Determine the head branch\n\nUse `git branch --show-current`. This is the head branch.\n\n## Step 4 — Present the PR plan and call create_pull_request\n\nShow the user a brief plan in this form:\n\n```\nPR Plan for {ticket_key}\n─────────────────────────\nHead branch: <current branch>\nBase branch: main\nTitle:       <proposed title>\n```\n\nAfter approval, call the `create_pull_request` MCP tool with `head_branch`, `base_branch: \"main\"`, and the approved `title`. Do not pass a `body` — the project's `.github/PULL_REQUEST_TEMPLATE.md` will populate the description.\n\nReport the returned `pr_url` to the user.\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 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",
+    "evaluate-and-recommend.md": "Evaluate the clarifying questions and ticket critiques generated for {ticket_key} against the actual codebase, then decorate every actionable item with the resolution guidance the reviewer will need on the decision page. The result is a single combined review-and-resolution document.\n\n1. Fetch the current ticket description using the `get_ticket` tool with ticket_number `{ticket_key}` exactly once at the top of this procedure.\n\n2. Gather the clarifying questions and critique documents from the preceding pipeline steps. The local files at `{docs_dir}/clarifying-questions/{ticket_key}-clarifying-questions.md` and `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md` are the canonical source. After a second-opinion run, each document has this shape:\n\n   - A top-level H1 (`# Ticket Analysis` for clarifier docs, `# Ticket Quality Critique` for critique docs) followed by an italic provider-attribution line of the form `_This analysis was generated by GPT|Claude|Gemini._`. The attribution names the LLM family that produced the **first round**.\n   - The first-round questions / critique items, exactly as written by the first-round model.\n   - **Inline second-opinion blockquotes** nested directly under each prior item the second round addressed. Each blockquote starts with `> **Second opinion (<provider>) - <stance>.**` where `<provider>` is `GPT|Claude|Gemini` and `<stance>` is `concurrence|refinement|disagreement`. The blockquote is followed by `> *Citations: <comma-separated grounding refs>*`. Items the second round did **not** comment on have no blockquote — that is the \"weak concurrence\" signal. Use the provider name in the blockquote header to attribute the comment to the second-round LLM family in your evaluation prose where helpful.\n   - A **`## New in Second Opinion`** tail block listing items the second round added on top of the first round. Immediately under the H2 you will find a second italic attribution line of the form `_These additional points were raised by GPT|Claude|Gemini._` — this names the second-round LLM family. Sub-headings are agent-specific:\n     - Clarifier docs: `### New Requirements Questions` and `### New Technical Questions` — numbering continues from the prior section.\n     - Critique docs: `### New Requested Changes` and `### New Points to Consider` — numbering continues from the prior section.\n     Each new item has its own `*Citations: ...*` line.\n   - A final **`## Second Opinion Summary`** footer (1-3 sentences) capturing the second round's overall position. This always renders, even when the second round had no inline comments and no new items.\n\n   **Legacy fallback shape**: in rare cases (model lacks JSON-schema support, the JSON call failed, or the response could not be parsed), the document may instead end with `\\n\\n---\\n\\n` followed by a `## Second Opinion` section containing `### Response to Prior Items` and `### Additional Points` subsections. If you detect this fallback shape, treat it equivalently: subsection responses tagged `concurrence` map to weak/strong concurrence (use the body length to disambiguate — bare one-line concurrences are weak), `refinement`/`disagreement` map to the disagree buckets, and items under `### Additional Points` map to the gap-captured bucket below.\n\n   **Partial-source-doc tolerance**: if the clarifying-questions doc OR the ticket-critique doc is missing or unreadable, skip that document silently and produce items only for the surviving doc. Do not fail. If **both** documents are absent, still write the combined output file at `{docs_dir}/review/{ticket_key}-review-and-resolution.md` with the standard top-level sections (`Confirmed Improvements`, `Needs Scrutiny`, `Open Questions`, `Round Agreement Summary`) present but no emitted E-items in any section. This preserves downstream file-existence expectations for the capture-review-decisions step.\n\n3. Determine **Round Agreement** for every clarifying question and critique point using these rules:\n\n   - **Both rounds agree (weak concurrence)** — the prior item has NO inline blockquote AND is not in `## New in Second Opinion`. The second round did not object to the point and did not consider it important enough to comment on. Briefly validate the answer's groundedness against the codebase. If validation surfaces concerns, demote this item to **rounds disagree** (single round only depth) and treat as Needs Scrutiny.\n   - **Both rounds agree (strong concurrence)** — the prior item carries an inline `> **Second opinion (<provider>) - concurrence.** ...` blockquote. The second round explicitly reinforced the prior point. Reuse the blockquote's `*Citations:*` as starting evidence; verify briefly.\n   - **Rounds disagree (refinement)** — the prior item carries an inline `> **Second opinion (<provider>) - refinement.** ...` blockquote. The second round modified or added detail. Apply full disagreement-depth analysis; reuse blockquote citations.\n   - **Rounds disagree (disagreement)** — the prior item carries an inline `> **Second opinion (<provider>) - disagreement.** ...` blockquote. The second round contradicts the prior. Apply full disagreement-depth analysis; categorize the outcome based on which position the codebase supports.\n   - **Gap captured** — the item lives under `## New in Second Opinion > ### New <category>` (one of: New Requirements Questions, New Technical Questions, New Requested Changes, New Points to Consider). Apply the two-axis check below. Reuse the new item's `*Citations:*` as starting evidence.\n   - **Single round only** — the document has none of the above markers (no inline blockquotes, no `## New in Second Opinion` block, no `## Second Opinion Summary` footer). The pipeline ran only one round. Treat every item as a disagreement: cite 2+ codebase locations and give full analytical depth.\n\n   Apply these depth and categorization rules:\n\n   - **Both rounds agree (weak concurrence)**: 1 codebase citation, 1-2 sentence assessment confirming grounding. Categorize as Confirmed Improvement if grounded; demote to Needs Scrutiny if validation finds problems.\n   - **Both rounds agree (strong concurrence)**: 1 codebase citation (may reuse a blockquote citation), 1-2 sentence assessment. Categorize as Confirmed Improvement.\n   - **Rounds disagree (refinement or disagreement)**: 2+ codebase citations, 3-4 sentence assessment that explicitly weighs the prior-round position against the second-opinion position. Categorize based on which position the evidence supports. Always include both positions in the Assessment.\n   - **Gap captured — two-axis check** (for items in `## New in Second Opinion`):\n       - If both the question is grounded in the codebase/standards AND the best-guess answer is sensible → **Confirmed Improvement** with a 1-2 sentence assessment and 1 citation.\n       - If the question is genuine but the best-guess answer is flawed → **Needs Scrutiny**. Cite 2+ files. Use disagreement-depth.\n       - If the question itself does not hold up → **Needs Scrutiny** with evidence of what the code actually does. Disagreement-depth.\n       - If neither codebase nor standards can settle the question → **Open Questions**. Disagreement-depth.\n   - **Single round only**: Treat as a disagreement — cite 2+ codebase locations and give full analytical depth.\n\n   For critique points (Requested Changes and Points to Consider), apply the same Round Agreement rules. The signal locations are inline `> **Second opinion (<provider>) - ...**` blockquotes nested under items in `### Requested Changes` / `### Points to Consider`, and gap-captured items under `## New in Second Opinion > ### New Requested Changes` / `### New Points to Consider`.\n\n   **Depth calibration**:\n   - When Round Agreement is `both rounds agree (weak concurrence)`, `both rounds agree (strong concurrence)`, or `gap captured` (passes both axes), keep Assessment to 1-2 sentences and Codebase Evidence to 1 citation — the validation step or the consensus does the heavy lifting.\n   - When Round Agreement is `rounds disagree (refinement)`, `rounds disagree (disagreement)`, or `single round only`, Assessment should be 3-4 sentences and Codebase Evidence should cite 2+ files explaining the discrepancy.\n   - A `gap captured` item that FAILS the two-axis check uses the disagreement depth, not the gap-captured depth.\n   - A `weak concurrence` item that FAILS your validation gets demoted: change Round Agreement to `rounds disagree (single round only)`, expand Assessment to 3-4 sentences, and add a 2nd citation.\n\n   **Source field conventions** — the `**Source**` string disambiguates where in the source doc the item lives so the downstream `capture-review-decisions` step can route the rewrite correctly. Use these forms:\n\n   - **Weak concurrence (silent prior item)**: `Clarifying Q3 (prior round, weak concurrence)` or `Critique: Requested Change 2 (prior round, weak concurrence)`.\n   - **Strong concurrence (explicit blockquote)**: `Clarifying Q9 (prior round, concurrence inline)` or `Critique: Points to Consider 1 (prior round, concurrence inline)`.\n   - **Refinement (inline blockquote)**: `Clarifying Q3 (prior round, refinement inline)`.\n   - **Disagreement (inline blockquote)**: `Clarifying Q5 (prior round, disagreement inline)`.\n   - **Gap captured (tail-block item)**: `Clarifying Q11 (new in second opinion → New Requirements Questions)` or `Critique: Requested Change N+1 (new in second opinion → New Requested Changes)`. Always spell out the sub-section name after the arrow — capture-review-decisions uses it to find the rewrite target.\n   - **Single round only**: `Clarifying Q3 (single round)`.\n\n## Phase 1 — Evaluate and classify every item\n\nNumber every item sequentially across all sections (E-1, E-2, E-3, …). Classify every clarifying question and every critique point into exactly one of three buckets using the Round Agreement rules, codebase groundedness checks, and the `gap captured` two-axis check before producing any recommendation decoration:\n\n- **Confirmed Improvements**: Suggestions that are grounded and would genuinely improve the ticket by closing significant gaps or correcting design issues. Includes weak-concurrence items that passed validation, strong-concurrence items, and `gap captured` items that passed both axes.\n- **Needs Scrutiny**: Suggestions based on inaccurate codebase assumptions, with evidence of the actual code behavior. Includes `gap captured` items that failed either axis, weak-concurrence items demoted by validation, and the loser of any rounds-disagree pair.\n- **Open Questions**: Legitimate ambiguities that require human input to resolve.\n\nPhase 1 must complete before Phase 2 begins — do not start decorating an item with a decision tree, recommendation index, or clarity fields until classification is final.\n\n## Phase 2 — Decorate actionable items with resolution guidance\n\nPhase 2 applies **only** to items in the `Needs Scrutiny` and `Open Questions` buckets. Confirmed Improvements remain compact and undecorated (see \"Confirmed Improvements output\" below).\n\nFor every actionable (Needs Scrutiny / Open Questions) item, produce the following template using these stable labels:\n\n```\n### E-<sequential number>: <concise title>\n\n**Source**: <where this item lives in the source doc — see Source field conventions above>\n\n**Round Agreement**: <one of the six values> — <1 sentence on what the second round contributed>\n\n**Confidence**: <High|Medium|Low>\n\n**Resolution path**: <\"resolve at your desk\" or \"needs a conversation\">\n\n**Decision tree**:\n- If <condition 1>, then <action 1>. See `file:line`. <1-2 sentence rationale.>\n- If <condition 2>, then <action 2>. See `file:line`. <1-2 sentence rationale.>\n- If <condition 3>, then <action 3>. See `file:line`. <1-2 sentence rationale.>\n\n**Recommendation Index**: <0-based index of the recommended branch in the decision tree above>\n\n**Recommendation**: <which branch the evidence best supports and why, 1-2 sentences>\n\n**Original question**: <the clarifying-question or critique point as it was originally raised, sourced verbatim or near-verbatim from the original clarifying-questions / critique docs. Light rephrasing is allowed; do NOT introduce new technical content. Soft cap ~30 words.>\n\n**Option consequences**:\n- <consequence for branch 1 — describe the behavioral consequence of choosing this option, not its rationale. ~25 words.>\n- <consequence for branch 2 — same shape. ~25 words.>\n- <consequence for branch 3 — same shape. ~25 words.>\n\n**Why it matters**: <one concrete sentence on the impact this decision has on the ticket, the users, or the affected code paths. Soft cap ~40 words.>\n\n**Recommendation explanation**: <explain why the recommended branch is the best choice, tied to the codebase evidence and the consequences of each option. Soft cap ~60 words.>\n\n**Assessment**: <three-point structure>\n1. **State the original suggestion**: What did the clarifying question or critique point propose?\n2. **State the codebase evidence**: What does the actual code show about this suggestion?\n3. **State the implication**: Does the evidence confirm the suggestion, contradict it, or leave it unresolved?\n\n**Codebase Evidence**:\n- `path/to/file.ts:42` — <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**Writing quality**: Write each Assessment as if explaining to a colleague who has NOT read the original clarifying questions or critique documents. Each assessment should be self-contained and understandable without cross-referencing the source material. The three-point Assessment structure ensures every assessment tells a complete story rather than assuming the reader already knows what was suggested and why.\n\n**Decision tree rules**:\n- Each decision tree must have **2–4 branches**. Do not exceed 4 and do not produce only 1.\n- **Strict lower bound — reclassify on single-branch items**: If you can think of only one branch for a `Needs Scrutiny` or `Open Questions` item — that is, the resolution is effectively forced — you must reclassify the item as a **Confirmed Improvement** instead of emitting a single-branch decision tree. The 2-branch lower bound is a hard rule; do not work around it by stretching to a contrived second branch. If a single answer is genuinely the only path, the item belongs in Confirmed Improvements.\n- Each branch must end with a concrete, actionable step (not \"investigate further\").\n- Cite relevant code in `file:line` format where possible. If no code reference exists, omit the citation rather than fabricating one.\n- Cap each branch at 2-3 sentences total (including the action and rationale).\n- `**Recommendation Index**` must be the 0-based index of the recommended branch in the decision tree above. The first branch is index 0, the second is index 1, etc.\n- **Option consequences** must be a list parallel to the decision-tree branches: one entry per branch, in the same order. Describe the behavioral consequence of choosing that option, not its rationale.\n- **\"resolve at your desk\"**: The item can be resolved through technical investigation — 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** — assign confidence based on codebase evidence strength:\n- **High**: Cite specific `file:line` references that directly support the assessment.\n- **Medium**: Reference related code patterns or architectural conventions, but not the exact code in question.\n- **Low**: No direct codebase evidence. Assessment is based on general reasoning or domain knowledge.\n\n### Confirmed Improvements output\n\nRender each Confirmed Improvement as a single bullet in a compact list. No headings per item, no decision trees, no clarity-field decoration:\n\n- **E-<number>: <title>** — Source: <source string>; Round Agreement: <one of the six values>; Confidence: <High|Medium|Low>. <recommended action, 1 sentence.>\n\nThe compact bullet still includes `Source`, `Round Agreement`, `Confidence`, and the one-sentence recommended action so `capture-review-decisions.md` can map these items to its `clear_improvements` array.\n\n## Round Agreement Summary\n\nAfter all items are processed, produce a summary section that groups items by round agreement status:\n\n### Points of Disagreement\nFor items where the evaluation marked `rounds disagree (refinement)`, `rounds disagree (disagreement)`, or `single round only` — 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\nSplit this section into two sub-bullets to surface the difference between the second round explicitly reinforcing a point versus tacitly accepting it:\n\n**Strong agreement** — items where the evaluation marked `both rounds agree (strong concurrence)`. The second round took the trouble to write an explicit `concurrence` blockquote; this is a soft signal that the point is important enough that the second round wanted to underline it. List as bullets with the E-number and a half-sentence noting the shared conclusion.\n\n**Weak agreement** — items where the evaluation marked `both rounds agree (weak concurrence)`. The second round did not object and did not consider the item important enough to comment on; the local agent's brief validation found no concerns. List as bullets with the E-number and a half-sentence noting the conclusion. Lower priority for human review than strong-agreement items.\n\nIf a sub-bullet has no items, omit it (rather than writing a \"no items\" note for each — keep the section tidy).\n\n### Gaps Captured by Second Round\nFor items where the evaluation marked `gap captured` (sound second-opinion Additional Points confirmed as Confirmed Improvements): list as bullets with the E-number and a half-sentence noting the gap the second round surfaced. These items did not require a decision — 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## Edge Cases\n\n- If the evaluation contains zero items in Needs Scrutiny, write: \"No items flagged for scrutiny. All reviewed suggestions were either confirmed or remain open questions.\"\n- If the evaluation contains zero items in Open Questions, write: \"No open questions identified. All ambiguities were resolved through codebase analysis.\"\n- If both Needs Scrutiny and Open Questions are empty, include only the Confirmed Improvements section and add a summary: \"All suggestions from the review were confirmed as grounded improvements. No decision trees are needed.\"\n- If both source documents are absent, still write the combined file with the standard top-level sections present but no emitted E-items rather than failing.\n\n## Example of a Well-Written E-Item (Weak Concurrence — Confirmed Improvement)\n\n### E-2: Caching of analysis-type lookups\n\n**Source**: Clarifying Q4 (prior round, weak concurrence)\n\n**Round Agreement**: both rounds agree (weak concurrence) — the second round did not comment on this item; brief validation confirms the answer is grounded.\n\n**Assessment**: The prior round suggested caching `ANALYSIS_TYPES` lookups in a module-level variable to avoid repeated DB round trips. The codebase already does this at `src/python/learn_repository/__init__.py:14`, so the suggestion is grounded and the second round's silence is consistent with tacit agreement.\n\n**Codebase Evidence**:\n- `src/python/learn_repository/__init__.py:14` — module-level constant pattern is the established convention\n\n(Confirmed Improvements compact bullet form: **E-2: Caching of analysis-type lookups** — Source: Clarifying Q4 (prior round, weak concurrence); Round Agreement: both rounds agree (weak concurrence); Confidence: High. Confirm the existing module-level cache and add a short comment naming the pattern.)\n\n## Example of a Well-Written E-Item (Strong Concurrence — Confirmed Improvement)\n\n### E-4: Sequential per-type review_repository fan-out\n\n**Source**: Clarifying Technical Q2 (prior round, concurrence inline)\n\n**Round Agreement**: both rounds agree (strong concurrence) — the second round explicitly reinforced the prior recommendation, citing per-type lock release simplicity as the deciding factor.\n\n**Assessment**: The prior round recommended sequential per-type execution; the second-opinion blockquote reinforced this, noting that the per-type lock release contract becomes trivial under sequential execution. `review_repository` already uses internal `asyncio.gather` for chunk-level concurrency, so wrapping it in another concurrency layer would not buy throughput and would complicate the abort/finally cleanup contract.\n\n**Codebase Evidence**:\n- `src/python/learn_repository/review_repository.py:369-387` — review_repository internally gathers chunks with return_exceptions=True\n\n## Example of a Well-Written E-Item (Rounds Disagree — Needs Scrutiny with full clarity fields)\n\n### E-5: Authentication middleware placement for new endpoint\n\n**Source**: Clarifying Q2 (prior round, disagreement inline)\n\n**Round Agreement**: rounds disagree (disagreement) — the prior round recommended adding auth at the router level; the second-opinion blockquote argued the existing middleware stack already covers it.\n\n**Confidence**: High\n\n**Resolution path**: resolve at your desk\n\n**Decision tree**:\n- If the global middleware stack already enforces auth on `/api/*` routes, then drop the explicit `Depends(require_api_key)` from the new endpoint. See `main.py:45-52`.\n- If routers each opt in to auth via dependencies, then add `Depends(require_api_key)` to the new endpoint. See `api/routes/__init__.py:18-30`.\n- If only certain `/api/*` sub-paths need auth, then carve out a sub-router with its own dependency. See `api/routes/__init__.py:18-30`.\n\n**Recommendation Index**: 1\n\n**Recommendation**: The existing routers each opt in to auth, so the new endpoint must do the same. Adding `Depends(require_api_key)` is the smallest correct change.\n\n**Original question**: Should the new `/api/exports` endpoint declare an explicit auth dependency, or is it covered by the global middleware?\n\n**Option consequences**:\n- Endpoint becomes publicly reachable; protected data leaks via the new path.\n- Endpoint requires a valid API key, matching every other `/api/*` route.\n- Adds a parallel router; doubles the auth surface that has to be kept consistent.\n\n**Why it matters**: Authentication on `/api/exports` directly determines whether protected data leaks; the wrong default is a security regression, not a stylistic choice.\n\n**Recommendation explanation**: The codebase pattern in `api/routes/__init__.py:18-30` shows each router declaring its own `Depends(require_api_key)`. Following that convention adds two lines, keeps auth uniform across endpoints, and avoids a parallel sub-router that future maintainers would have to keep in sync.\n\n**Assessment**: The prior round suggested that the new `/api/exports` endpoint needs an explicit `Depends(require_api_key)` guard because it is not covered by the global middleware. The second opinion disagreed, claiming the middleware stack in `main.py` handles authentication for all `/api/*` routes. Codebase analysis shows that `main.py:45-52` applies rate limiting globally but authentication is applied per-router in `api/routes/__init__.py:18-30` — 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 — Confirmed Improvement)\n\n### E-7: Missing Alembic migration for new role-scope column\n\n**Source**: Critique: Requested Change N+1 (new in second opinion → 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## Save rule\n\nSave the combined review-and-resolution document to `{docs_dir}/review/{ticket_key}-review-and-resolution.md`. Output only the combined review-and-resolution document — 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",
@@ -520,7 +501,6 @@ 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` — 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.12";
+export const VERSION = "0.1.13";

package/package.json

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

package/pipelines/check-ci-ticket.json

@@ -16,14 +16,9 @@
       "requires_approval": true
     },
     {
-      "type": "mcp_call",
-      "tool": "create_pull_request",
-      "params": {
-        "head_branch": "feature/{ticket_key}",
-        "base_branch": "main",
-        "title": "{ticket_key}: Implementation"
-      },
-      "description": "Create a pull request",
+      "type": "agent_task",
+      "instruction_file": "create-pr.md",
+      "description": "Create a pull request with a title derived from the commit subject",
       "requires_approval": true
     },
     {

package/pipelines/implement-ticket.json

@@ -32,14 +32,9 @@
       "requires_approval": true
     },
     {
-      "type": "mcp_call",
-      "tool": "create_pull_request",
-      "params": {
-        "head_branch": "feature/{ticket_key}",
-        "base_branch": "main",
-        "title": "{ticket_key}: Implementation"
-      },
-      "description": "Create a pull request",
+      "type": "agent_task",
+      "instruction_file": "create-pr.md",
+      "description": "Create a pull request with a title derived from the commit subject",
       "requires_approval": true
     },
     {

package/pipelines/pr-ticket.json

@@ -16,14 +16,9 @@
       "requires_approval": true
     },
     {
-      "type": "mcp_call",
-      "tool": "create_pull_request",
-      "params": {
-        "head_branch": "feature/{ticket_key}",
-        "base_branch": "main",
-        "title": "{ticket_key}: Implementation"
-      },
-      "description": "Create a pull request",
+      "type": "agent_task",
+      "instruction_file": "create-pr.md",
+      "description": "Create a pull request with a title derived from the commit subject",
       "requires_approval": true
     }
   ]

package/pipelines/review-ticket.json

@@ -1,6 +1,6 @@
 {
   "name": "review-ticket",
-  "description": "Review a ticket with two rounds of analysis (initial + second opinion), evaluate suggestions for accuracy, and produce a resolution guide with decision trees.",
+  "description": "Review a ticket with two rounds of analysis (initial + second opinion), evaluate suggestions for accuracy, and produce a combined review-and-resolution document with decision trees.",
   "variables": ["ticket_key", "docs_dir"],
   "steps": [
     {
@@ -36,13 +36,8 @@
     },
     {
       "type": "agent_task",
-      "instruction_file": "evaluate-ticket-review.md",
-      "description": "Evaluate review suggestions against the codebase for groundedness and value"
-    },
-    {
-      "type": "agent_task",
-      "instruction_file": "recommend-ticket-resolutions.md",
-      "description": "Produce a resolution guide with decision trees and confidence-tagged recommendations"
+      "instruction_file": "evaluate-and-recommend.md",
+      "description": "Evaluate ticket-review findings against the codebase and produce the combined review-and-resolution document at {docs_dir}/review/{ticket_key}-review-and-resolution.md"
     },
     {
       "type": "agent_task",