@bridge_gpt/mcp-server 0.2.68 → 0.2.69

package/build/pipelines.generated.js

@@ -751,7 +751,7 @@ export const INSTRUCTIONS = {
     "comp-analysis.md": "Perceive any attached/referenced design comp with your OWN vision and map it to the existing codebase BEFORE the `jira-ticket-writer` drafts. This is the pre-writer perception step: the orchestrating recipe agent (already a frontier vision model) opens the comp, classifies it against the shared fidelity taxonomy, researches the code, and writes a structured comp→codebase map the writer consumes. The writer stays text-only and never opens images — it only reads the map you produce here.\n\nThis step is gated and backend-safe. It runs the perception with the ORCHESTRATING agent's own vision — a local image via the Read tool, or an already-attached Jira comp fetched as raw bytes via the BAPI-562 binary-safe `attachment` download (operation `download`) into a worktree `file_path`. It does NOT call `describe_image()`, does NOT depend on `src/python/llms/vision.py`, and does NOT require the `CHEAP_MODEL` vision path or any vision-model upgrade or procurement. The heavy visual reasoning is done for free by the agent that already runs the recipe.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json` (source of truth for `idea`, `scope`, `readiness`). Read whichever prior artifacts exist under `{docs_dir}/idea-to-ticket/{slug}-{run_id}/` (research pack, resolved uncertainties, goals-and-nfrs, standards checklist) and proceed without the ones that do not.\n- Output artifact (this step writes it): `{docs_dir}/idea-to-ticket/{slug}-{run_id}/comp-analysis.json` — the structured comp→codebase map the drafting step reads.\n\n## Callers\n\nThe steps below are the **recipe path** and are unchanged for the `idea-to-ticket` recipe.\n\n**Define-tickets path.** When `/define-tickets --auto` runs this procedure, the command names an exploration-adjacent artifact directory. Read the exploration document and any materials the task references instead of run-manifest artifacts, and write `comp-analysis.json` in that named directory. Assume no run manifest and no label. Apply the same gate, classification, and mapping rules. If the analysis is degraded for any reason, write `applicable: false`, a degradation `reason`, and `warnings` that identify the material needing manual review. When no qualifying comp exists, write the clean not-applicable artifact with no degradation warning. Degraded analysis never blocks the command.\n\n## Instructions\n\n1. **Gate first — evaluate only text/material metadata, never open an image yet.** Proceed to any image work ONLY when BOTH conditions hold:\n   - a design comp is **referenced or attached** (a local image path in the idea/materials, or an already-attached Jira comp with an `attachment_id`), AND\n   - the requested work is **design/UI work** (a frontend/fullstack change with a visual surface).\n\n   This gate is deliberately conservative. A **backend-only** request, a **no-comp** request, or a **non-design** request fails the gate.\n\n2. **Not-applicable branch (gate fails) — short-circuit immediately.** When either gate condition is not met, write `comp-analysis.json` with `applicable: false`, a short `reason`, and the `gate` evidence fields, then **return immediately** — do NOT open any image, do NOT download any attachment, do NOT inject any fidelity/comp/visual language, and add no measurable latency. A backend-only or no-comp authoring input must be byte-for-byte unaffected downstream. Concretely, the not-applicable artifact is:\n\n   ```json\n   { \"applicable\": false, \"reason\": \"backend-only work; no design comp referenced\", \"gate\": { \"comp_referenced\": false, \"design_ui_work\": false }, \"warnings\": [] }\n   ```\n\n3. **Applicable branch — obtain and OPEN the comp with your own vision.** When the gate passes:\n   - **Local image path** → open it directly with the Read tool.\n   - **Already-attached Jira comp** → fetch it as raw bytes using the BAPI-562 binary-safe `attachment` capability with operation `download`, passing the comp's `attachment_id` and a worktree `file_path`; the download saves the PNG/JPEG bytes to that `file_path` inside the project root, then open the saved file with the Read tool.\n   - You are the orchestrating vision model — reason over the actual pixels yourself. Do NOT call `describe_image()`, do NOT use `src/python/llms/vision.py` / `CHEAP_MODEL`, and do NOT delegate perception to the text-only `jira-ticket-writer` subagent.\n\n4. **Degraded paths are skip-clean and warn-not-halt.** If the comp is missing, unreadable, an unsupported format, external-only (an `http(s)` URL you cannot fetch into a worktree `file_path`), or turns out not to be a usable design comp, write a valid `comp-analysis.json` with `applicable: false`, a `reason`, and a populated `warnings` array describing what failed, then return. A missing, unreadable, or non-comp image NEVER blocks downstream drafting and NEVER requires further image work after the failure.\n\n5. **Classify the opened comp using the shared fidelity taxonomy (do not fork it).** Using your own vision, classify the comp as exactly one of these four classes — the same labels the downstream final plan reviewer uses (`src/python/llms/agents/planner_agent/final_plan_review_agent.py`, `_get_runtime_verification_instructions`), so authoring, planning, and implementation all agree:\n   - `full comp`\n   - `wireframe`\n   - `annotated-screenshot-of-existing-UI`\n   - `unknown`\n\n   Record `fidelity_classification` with a `class` (one of the four), a `confidence` value, and a short `reasoning` string.\n\n6. **Apply class-appropriate mapping depth — no over-specification.** Match the per-class rules exactly:\n   - **full comp** (confident) → map exact existing components, Jinja2 templates, SCSS/CSS tokens, and routes; strict/exact component + token depth is used ONLY here.\n   - **wireframe** → map layout and structure only (regions, order, rough proportions, responsive behavior); defer color, type, spacing, and component polish to the repo design system, NOT to the wireframe.\n   - **annotated-screenshot-of-existing-UI** → map ONLY the delta against the current UI; preserve everything outside the annotated region and do not reproduce the screenshot wholesale.\n   - **unknown / low confidence** → fall back to the design-system floor rather than mapping pixels.\n\n   **Hard rule:** strict/exact mapping depth is enabled ONLY for a confidently-classified full comp. Fail toward the design system, never toward reproducing an ambiguous image.\n\n7. **Research the codebase and map each region/element to concrete existing code.** Inspect the working tree (search, grep, file reads) for the existing UI implementation surfaces: reusable components, Jinja2 templates, plain CSS/SCSS tokens and design-system styles, routes, and reusable frontend patterns. Only cite files you actually inspected — do not invent file paths, component names, tokens, or routes. For each region/element of the comp, produce a `mappings[]` entry containing:\n   - `region` — the comp region or element name.\n   - `visual_description` — a short description of what it looks like.\n   - `components` — mapped existing component file(s).\n   - `templates` — mapped existing Jinja2 template(s).\n   - `tokens` — style/token references (SCSS/CSS tokens or design-system styles).\n   - `routes` — route reference(s) where the element lives or should wire.\n   - `confidence` — confidence for this mapping.\n   - `implementation_guidance` — concrete guidance (e.g. \"reuse component X\", \"extend template Y\", \"use token Z\", \"wire route R\").\n\n8. **Write the structured map to a stable schema.** Write `comp-analysis.json` at `{docs_dir}/idea-to-ticket/{slug}-{run_id}/comp-analysis.json` with these fields:\n   - `applicable` — boolean; `true` only after a comp was both detected AND successfully opened.\n   - `reason` — short string explaining the applicability decision.\n   - `gate` — the two-condition gate evidence (`comp_referenced`, `design_ui_work`).\n   - `comp` — provenance of the opened comp (source kind, path or `attachment_id`, filename, MIME type when known).\n   - `fidelity_classification` — `{ class, confidence, reasoning }`, present only when `applicable` is true.\n   - `mappings` — array of the per-region entries defined in step 7 (present only when `applicable` is true).\n   - `design_system_floor` — the design-system fallback guidance to use for wireframe/unknown/low-confidence regions.\n   - `warnings` — array of degraded-path notes (may be empty).\n   - `writer_guidance` — instructions for the downstream drafting step: when `applicable` is `true`, Requirements must cite the mapped components/templates/tokens/routes as concrete implementation guidance; when `applicable` is `false` or the map is missing, the writer must ignore this artifact and mention no comp analysis, design comp, or visual-fidelity language unless the original request independently requires it.\n\n9. **Never over-write.** Write the artifact exactly once at the path above. Downstream steps (`draft-and-critique.md`) read it; do not move it.\n\n## Return\n\nConfirm the path written (`{docs_dir}/idea-to-ticket/{slug}-{run_id}/comp-analysis.json`), whether the analysis was `applicable`, the fidelity `class` when applicable, and any `warnings`.\n",
     "create-pr.md": "# Create a pull request for the just-pushed branch\n\nThe implementation has been committed and pushed. Open a PR for the current branch against the PR base resolved in Step 3 — which is `main` only when nothing higher in that order of precedence supplies a base — 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 — Determine the head branch\n\nUse `git branch --show-current`. This is the head branch.\n\n## Step 2.5 — Run the file-scope guard (warn-only, before opening the PR)\n\nBefore opening or updating the PR, run the Epic Implementer file-scope guard so\nan out-of-scope diff is surfaced in the PR-creation context:\n\n```bash\nnode \"$BAPI_EPIC_IMPLEMENTER_CLI_FILE\" file-scope-guard\n```\n\nOnly the `start-tickets --conductor` launch sets `BAPI_EPIC_IMPLEMENTER_CLI_FILE`.\nA v2 Epic Implementer worker does not have it. When it is unset, run\n`epic-implementer file-scope-guard` if the packaged binary is on PATH, or\n`npx -y -p @bridge_gpt/mcp-server epic-implementer file-scope-guard`. If no form\nof the command can start, note that the guard did not run and continue to Step 3.\n\nThis guard is **warn-only and fail-open** — it **always exits 0 and never blocks\nPR creation**. Behavior:\n\n- If `BAPI_EPIC_IMPLEMENTER_DECLARED_TOUCHED_FILES_JSON` is **absent, empty, or invalid**,\n  the guard is a **no-op** — it prints nothing and you **continue** to Step 3\n  normally. Do not treat a missing declaration as an error.\n- If the guard prints a warning that your branch diff touched files **outside** the\n  ticket's declared touched-file set, **surface that warning in the PR-creation\n  context** (include it in your summary to the user / PR notes) but **do not block**\n  — proceed to open the PR. The warning is advisory: it flags a possible\n  sibling-scope over-reach for human review, it does not stop the workflow.\n\n## Step 3 — Resolve the base, compose the body, and call create_pull_request\n\n### Resolve the PR base\n\nResolve `base_branch` through this ordered precedence, taking the first tier that yields a usable value:\n\n1. **`BAPI_BASE_BRANCH` from the environment, when set and non-empty.** Read it explicitly with Bash — never infer the base from branch ancestry or from the repository default branch:\n\n   ```bash\n   echo \"${BAPI_BASE_BRANCH:-}\"\n   ```\n\n   The non-failing `:-` form returns an empty line when the variable is unset, so the read never errors. `start-tickets` exports this variable into **every** worker's shell for the run's resolved base — always, including the ordinary `main` case, not only an epic branch (BAPI-847). Treating it as an epic-only signal is what let the config-field tier below become the effective resolver and opened an unrelated ticket's PR against an epic branch. It is the run's own answer, so it is the highest-priority tier.\n2. **A PR base the user supplied at the commit step.** The commit step advertises PR base as an adjustable field, so an override given there carries forward into this call rather than being silently replaced by a lower tier.\n3. **The repository's configured base branch.** Call `config_field` with `operation: \"get\"` and `field_name: \"base_branch\"`. Tiers 2-4 are compatibility paths for a legacy or independently invoked run: a packaged worker always arrives with tier 1 set, so reaching this tier in a `start-tickets` run means the export did not happen.\n4. **`main`** — the normal fallback default when no tier above supplied a base.\n\nTreat a null, empty, or whitespace-only configured value, an HTTP `400`, or any lookup error as **unset** and continue quietly to the `main` fallback. Missing configuration is an ordinary outcome here, not a failure of this step.\n\n### Compose the PR body\n\nBuild `body` in this reading order:\n\n1. A concise summary line for the ticket — what this pull request changes.\n2. A plainly labeled reference to the local implementation plan, as plain text rather than a markdown hyperlink (the path is local to whoever pulls the branch): `Implementation plan available locally at <docs_dir>/plans/{ticket_key}-plan.md`. Use the plan location this recipe already knows when it has one; otherwise resolve `<docs_dir>` by calling the `ping` MCP tool and reading `docs_dir` from its first (JSON) content item.\n3. The checklist text of `.github/PULL_REQUEST_TEMPLATE.md`, read from the current worktree when that file exists, appended after the plan reference without rewriting its markdown structure. Omit this part when the file is absent.\n\nGitHub's REST API does not automatically apply the repository pull request template — that template is a web-UI affordance only. A pull request opened through this tool therefore carries an empty description unless the recipe inlines the checklist into `body` itself, which is exactly why the checklist is read from the worktree and appended here.\n\n**This is enforced, not advisory (BAPI-824).** The server rejects a missing, empty, or whitespace-only `body` with a `422` and creates no pull request. Composing the body is a hard prerequisite of this step, not a courtesy: skipping it fails the call outright rather than opening a pull request with a blank description — which is what happened twice before the check existed. The response reports the length actually sent as `detail.body_len`.\n\n### Call the tool and report the PR URL\n\nCall the `create_pull_request` MCP tool directly with:\n\n- `head_branch`: value from `git branch --show-current`\n- `base_branch`: the base resolved above\n- `title`: the commit subject from Step 1 (the derived PR title) — unless the user supplied a different PR title at the commit step, in which case use that value instead.\n- `body`: the body composed above\n\nHonor any PR title / PR base overrides the user gave at the commit step's plan; the commit step advertises those fields as adjustable, so any override the user gave there must carry forward into this tool call rather than being silently replaced by a lower-precedence value.\n\n`create_pull_request` is the only mechanism this recipe uses to open a pull request. Do not shell out to a VCS command-line client to create it.\n\nReport the returned `pr_url` to the user.\n\n### The PR URL is a hard prerequisite for everything downstream\n\nThis step completes the durable artifact that the rest of the pipeline — and, under\nthe Epic Implementer, the reconciler — binds to. It therefore has a strict success\ncondition: the call must yield a **non-empty PR URL**, either for a pull request it\nnewly opened or for an already-open pull request on this head branch that the\nresponse identifies.\n\nIf the tool is unavailable, errors, or returns neither a usable new PR URL nor an\nexisting one, **stop here and report the failure**. Do not advance to the\npost-finalization verification phase, which exists only to add work on top of an\nopen pull request.\n\nThen run `git rev-parse HEAD` and record the current pushed head SHA, so the\ndownstream phases report the same durable head this pull request points at.\n\n## Return\n\nReturn the head branch, the base branch that was used, the pull request URL, and\nthe current pushed HEAD SHA. If no usable pull request URL was obtained, return\nthat failure instead — the pipeline stops rather than proceeding to verification.\n",
     "decompose-epic-candidate.md": "Decompose an Epic parent draft into ordered child tickets with idempotency and per-child duplicate checks.\n\n## Inputs\n\n- Epic parent draft: `{docs_dir}/tickets/EPIC-{slug}.md`.\n- Research pack: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-pack.md` / `.json`.\n- Standards checklist: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/standards-checklist.json`.\n- Resolved uncertainties: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/resolved-uncertainties.md`.\n- Goals & NFR framing: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/goals-and-nfrs.md` (its System Goals/NFRs and any provisional Recommended Implementation Order should inform the child breakdown and ordering).\n- Hard cap variable `{max_children}` (string integer; default `\"10\"` when not set by the caller). The default `\"10\"` is a **hard ceiling / upper bound, not a target** child count — it caps how many children are allowed, and is **not a goal to fill**. The normal target child count is smaller (fewer, larger M/L slices); see the sizing heuristics in step 2.\n\n## Instructions\n\n1. Read the Epic parent draft, research pack, standards checklist, and resolved uncertainties. Use only this context plus optional narrow web search; do not call deep research from this step.\n\n2. Propose ordered child tickets that, together, fully implement the Epic.\n\n   **Sizing.** The canonical ladder is the posture block at the end of this file. Size each proposed child by its expected **file-touch breadth and depth plus rough lines of code (LOC) changed**, and apply the posture's target priority: **L (target) -> XL (when the work does not fit in L) -> M (third choice) -> S (only when unavoidable)**. An XL child is allowed and preferred over splitting a coherent slice to fit `L`. Only a child running past roughly 40 files / ~3000 LOC is rejected before output, and it is rejected rather than shipped with a note.\n\n   Bias the decomposition toward **fewer, larger, independently implementable vertical slices** rather than many tiny one-feature children. The Bridge implementation tooling works better on large vertical slices, and a swarm of tiny S children magnifies sibling merge risk under parallel execution while spending the run's budget on coordination. Each child should be an independently implementable vertical slice; if a proposed child outgrows L, emit it as one XL child rather than halving it.\n\n   Each proposed child must include:\n   - `summary` — Jira title.\n   - `issue_type` — typically `Task`; use `Spike` only for primarily discovery children.\n   - `rationale` — short explanation of why this child exists and what it produces. Include a brief size estimate inside this existing field (do **not** add a new `size` field), e.g. `Estimated size: M (~4 files / ~150 LOC)`.\n   - `labels` — must include `ai-generated`, `idea-to-ticket`, `idea-to-ticket-child`, and the unique child idempotency label `bapi-idea-to-ticket-{run_id}-child-<N>` where `<N>` is the 1-based child index in the final ordered list.\n   - `idempotency_label` — the same `bapi-idea-to-ticket-{run_id}-child-<N>` string.\n   - `draft_path` — `{docs_dir}/tickets/TICKET-{slug}-child-<N>.md` (drafts written by `jira-ticket-writer` later).\n   - `depends_on` — array of the 1-based child indexes that are **hard prerequisites** (must land first), or empty. Keep this list minimal and real.\n   - `recommended_after` — array of child indexes that are **soft sequencing** preferences (nicer to do after, but not blockers), or empty.\n   - `order_rationale` — one line explaining why this child sits at this point in the order.\n   - `owns_verifications` — array of `{epic_ac, obligation}` entries, exactly as `review-epic-coherence.md` defines the field. `epic_ac` is the id of one of the Epic parent draft's acceptance criteria. `obligation` is the concrete part of that criterion's **verification** sentence this child will carry out, in words a reviewer can hold against the verification sentence. Fill it in during this pass, the same pass that freezes the split — never as a later step. Together, the children's entries should give every epic acceptance criterion an owner. The claim is checked by the epic coherence review; it is never proof by itself.\n   - `acceptance_criteria` — the planned acceptance criteria for this child: the epic criteria text it helps satisfy, plus each of its `owns_verifications` obligations word for word. This is the child evidence the coherence review reads; the writer later renders the same obligations verbatim.\n\n   **Non-child owners.** When the Epic parent draft's design names an **owner-run** step — for example a step in a release checklist that a person runs outside the Epic Implementer — and that step is what proves an epic acceptance criterion, do **not** force a child to own it. Record it instead in a plan-level `non_child_owners` array beside `children`, exactly as `review-epic-coherence.md` defines the field. Each entry carries `id` (for example `OR-1`, never equal to a child index), `kind` (`owner_run`), `who` (the named person or role), `step_ref` (for example \"Release checklist step 6\"), `step_text` (the step's text copied **verbatim** from the parent draft's design), `records_result_in` (where the result is recorded), and `owns_verifications` (`{epic_ac, obligation}` entries). A child's `owns_verifications` holds only that child's own obligations; an owner-run obligation never appears in a child's `owns_verifications` or `acceptance_criteria`.\n\n   Keep hard prerequisites (`depends_on`) strictly separate from soft sequencing (`recommended_after`). These fields drive the recommended implementation order posted to the epic later; they do **not** create Jira dependency links.\n\n3. Hard cap enforcement. First attempt a normal, smaller M/L-biased decomposition per the step 2 sizing heuristics. Then count proposed children: `{max_children}` is a hard ceiling that **halts on exceed**, not a target to fill. If the count exceeds `{max_children}` (parsed as an integer), halt locally with a clear \"split first\" message: ask the user to split the idea into multiple smaller Epics or to raise `--max-children` deliberately. Do not silently truncate.\n\n4. Per-child duplicate lookup. For each proposed child (in order), call `get_tickets` once with a title/keyword search built from the child's summary. If a clear duplicate exists, drop that child from the plan and record the drop reason; never halt the whole run because a child has a duplicate. Re-number `<N>` only after all drops are finalized so child indexes are contiguous.\n\n5. Per-child research is restricted to the parent research pack plus optional narrow web search. Do not call deep research per child.\n\n6. **This ordered plan is the frozen manifest.** Once written it is the sole source of child summaries, rationale, size bands, `depends_on`, `recommended_after`, order rationale, `owns_verifications`, the plan-level `non_child_owners`, idempotency labels, and `draft_path`. Body rendering fans out against it (`render-ticket-manifest.md`) and must not re-decide any of those fields. Do not decompose a second time anywhere downstream: two independent decisions about one split disagree, and the disagreement surfaces as children that overlap or contradict their parent.\n\n   **Amendments replace the frozen decomposition; rendering never re-splits it.** When the epic coherence review asks for an amendment (a child added or rescoped, or an obligation reassigned), the caller repeats this pass with the finding's `smallest_amendment` as extra input and writes a **new** `decomposition-plan.json` that replaces the old one. The new file has a new manifest identity, so a coherence record written for the old one can never clear it. The coherence review's `manifest` array is normalized from the ordered `children` array of the file on disk and from nothing else, so the manifest that was reviewed is exactly the manifest that renders.\n\n7. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/decomposition-plan.json` with at minimum:\n   - `parent_summary` — copy from the parent draft.\n   - `max_children` — the resolved integer value used for the cap.\n   - `children` — ordered array of surviving children with all fields from step 2 (including `depends_on`, `recommended_after`, `order_rationale`, `owns_verifications`, and `acceptance_criteria`). After re-numbering in step 4, fix up the `depends_on`/`recommended_after` indexes so they still point at the correct surviving children.\n   - `dropped_children` — array of `{proposed_summary, reason}` for children removed by duplicate lookup.\n   - `non_child_owners` — the plan-level owner-run entries from step 2, when any exist. Omit the field when there are none. The coherence input copies it unchanged.\n\n\n<!-- BEGIN BRIDGE TICKET-AUTHORING POSTURE -->\n<!-- Canonical source: docs/bridge-ticket-authoring.md.\n     This block is duplicated byte-identically onto every carrier. Never edit a\n     copy: edit the canonical source and re-copy it verbatim. A cross-surface\n     byte-equality test fails the build if any copy drifts by a single byte. -->\n\n## Ticket-authoring posture\n\nDeep reference: `docs/bridge-ticket-authoring.md`.\n\n**Draft through the writer.** Every ticket body — an epic parent, an epic child,\nand an ordinary sibling alike — is drafted by the `jira-ticket-writer` agent\nbefore `create_ticket` is called. Do not compose a ticket description inline.\n\n**Size the work.** Size each ticket by file-touch breadth and depth plus rough\nlines of code (LOC) changed:\n\n- `S = 1-2 files / <~80 LOC`\n- `M = ~3-8 files / ~80-400 LOC`\n- `L = ~8-15 files / ~400-900 LOC`\n- `XL = >15 files / >~900 LOC`\n\nTarget size priority: **L (target) -> XL (when the work does not fit in L) -> M\n(third choice) -> S (only when unavoidable)**. This applies equally to a\nstandalone ticket and to an epic child.\n\nAim each slice at L. When one will not fit, grow it to XL rather than splitting\nit — split only when the slice is genuinely two independent pieces of work,\nnever merely to land inside a band. Bridge's grooming and implementation process\nhandles a large vertical slice well and is overkill on small ones: every extra\nticket is another worktree, another PR, another rebase, and another chance for\ntwo workers to touch the same file. Reach for M because the work genuinely is\nthat size, not to avoid an XL.\n\nBeyond roughly 40 files or ~3000 LOC, split anyway. Past that point review\nturnaround and rebase cost dominate the run's budget, and a review that wedges\nholds the gate to its full retry ceiling before anyone notices.\n\n**Group at three.** Three or more implementable tickets is an epic: propose an\nepic parent plus an ordered child manifest, and resolve this surface's own\napproval gate before anything is created. One or two tickets are ordinary\nsiblings — no epic parent, no manifest. The threshold is exactly three.\n\n**Hand off once.** An epic handoff names exactly one conductor entry point,\n`drive-epic`, which selects the runnable path itself. Never present a choice\nbetween conductors.\n\n**Departure is closed-list only.** These three exceptions, and no others, permit\ndeparting from the rules above. Invoking one requires no announcement.\n\n- **E1 External-tracker mirroring** — a recorded upstream identifier exists and\n  its granularity is contractual. Bypasses sizing and the epic threshold.\n- **E2 Discovery-only spike** — no committed production-code deliverable.\n  Bypasses sizing only; does not bypass drafting through the writer.\n- **E3 Authorized incident containment** — tied to an active incident record,\n  not to schedule pressure. Bypasses sizing and the epic threshold.\n\nThe list is closed. Anything outside it is an escalation to the operator, not a\njudgement call. Explicitly refused as grounds for departure: a single-file\ntrivial fix (that is `S` reached through the normal path, not an exception),\ngeneric time pressure, \"already well specified\", \"faster without the writer\",\ndeveloper discretion, minor refactor, unattended mode, context limits, and \"hard\nto decompose\" (XL is the normal overflow, so that is the ordinary path and not a\ndeparture). Writer unavailability escalates; it never silently authorizes inline\ndrafting.\n\n<!-- END BRIDGE TICKET-AUTHORING POSTURE -->\n\n## Return\n\nConfirm `decomposition-plan.json` was written, report the final child count and the number of children dropped for duplicate reasons.\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\n   **Size every sub-task with the canonical ladder** in the posture block at the end of this file, by file-touch breadth and depth plus rough LOC changed. Apply its target priority: **L (target) -> XL (when the work does not fit in L) -> M (third choice) -> S (only when unavoidable)**. **A sub-task may be XL.** When one will not fit in `L`, grow it to `XL` rather than splitting it; split only when it is genuinely two independent pieces of work, or when it runs past roughly 40 files / ~3000 LOC. Bias toward fewer, larger, independently implementable vertical slices: a swarm of tiny children magnifies sibling merge risk under parallel Epic Implementer execution and spends the run's budget on coordination.\n\n   **Decompose once.** This pass freezes the split. Emit the same ordered-manifest shape the `idea-to-ticket` path uses (`decompose-epic-candidate.md`), so that per sub-task you record: title, scope boundary, **size band**, `depends_on` (hard prerequisites that must land first), `recommended_after` (soft sequencing preferences that are not blockers), a one-line order rationale, `owns_verifications`, and planned acceptance criteria. `owns_verifications` is a list of `{epic_ac, obligation}` entries, exactly as `review-epic-coherence.md` defines the field: `epic_ac` is the id of one of the epic's acceptance criteria, and `obligation` is the concrete part of that criterion's **verification** sentence this sub-task will carry out. Fill it in during this pass, the same pass that freezes the split — never as a later step. The planned acceptance criteria are the epic criteria text the sub-task helps satisfy plus each of its obligations word for word. Keep hard prerequisites strictly separate from soft sequencing — the recommended implementation order is derived from them, and conflating the two serializes work that could have run in parallel. No later stage re-derives a sub-task's scope while rendering its body.\n\n   **Three or more sub-tasks is an epic; one or two would ordinarily be siblings.** The threshold is exactly three. This surface is the one place that threshold does *not* decide the shape: `/plan-epic` runs against an epic ticket that already exists, so the grouping decision was made upstream and is not yours to reverse here. If the epic genuinely decomposes into only one or two sub-tasks, **say so plainly to the user** — that is a signal the epic was over-scoped and may be better as ordinary sibling tickets — and then continue with the steps below as written. Do not manufacture filler sub-tasks to reach three, and do not skip the artifacts step 3 requires; the `plan-epic` step sequence is fixed and every later step reads them. The epic coherence check in step 3 also still runs for one or two sub-tasks.\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- **Size**: {S | M | L | XL}\n- **Key files/areas**: {Files and code areas involved}\n- **Dependencies**: {Other sub-task numbers this depends on, or \"None\"}\n- **Recommended after**: {Soft sequencing preferences that are not blockers, or \"None\"}\n- **Order rationale**: {One line on why this sub-task sits at this point in the order}\n- **Owns verifications**: {One entry per owned epic AC: the AC id, then the obligation, word for word as in the JSON authoring manifest}\n\n### 2. {Sub-task title}\n...\n\n## Epic coherence\n\nSee `epic-coherence.json` (authoritative) and `epic-coherence.md` (human summary) in this directory.\n```\n\n   Keep the `## Epic coherence` section to that pointer. The coverage map lives in the record; do not keep a second, editable copy of it here.\n\n   Also write the **JSON authoring manifest** to `{docs_dir}/epic-plans/{epic_slug}/epic-manifest.json`, from the same structured decomposition data (never by re-parsing the markdown). It is the frozen manifest the epic coherence review checks, and it uses the input field names `review-epic-coherence.md` defines:\n\n```json\n{\n  \"manifest\": [\n    {\n      \"id\": \"1\",\n      \"title\": \"Sub-task title\",\n      \"scope\": \"What this sub-task covers\",\n      \"size_band\": \"L\",\n      \"depends_on\": [],\n      \"recommended_after\": [],\n      \"touched_files\": [\"api/routes/example.py\"],\n      \"read_files\": [\"api/library/example_reader.py\"],\n      \"owns_verifications\": [\n        { \"epic_ac\": \"AC-1\", \"obligation\": \"The concrete part of AC-1's verification this sub-task carries out\" }\n      ]\n    }\n  ],\n  \"child_evidence\": [\n    { \"id\": \"1\", \"acceptance_criteria\": [\"Each planned acceptance criterion of the sub-task, verbatim\"] }\n  ],\n  \"non_child_owners\": [\n    {\n      \"id\": \"OR-1\",\n      \"kind\": \"owner_run\",\n      \"who\": \"Release owner\",\n      \"step_ref\": \"Release checklist step 6\",\n      \"step_text\": \"The step's text, copied verbatim from the epic's design\",\n      \"records_result_in\": \"a comment on the epic\",\n      \"owns_verifications\": [\n        { \"epic_ac\": \"AC-2\", \"obligation\": \"The concrete part of AC-2's verification the owner-run step carries out\" }\n      ]\n    }\n  ]\n}\n```\n\n   - `manifest` is the complete, ordered sub-task list. `id` is the 1-based position as a string. `depends_on` and `recommended_after` hold those ids.\n   - `child_evidence` has one entry per sub-task, keyed by the same `id`. Its `acceptance_criteria` are the sub-task's planned acceptance criteria: the ratified epic criteria text it satisfies, plus every `owns_verifications` obligation word for word.\n   - `touched_files` lists the files a sub-task edits or creates. `read_files` is optional and lists files it only reads, when known; reads never count as an edit overlap or toward the high-risk path check.\n   - `non_child_owners` is optional. When the ratified design assigns an epic acceptance criterion's verification to a concrete **owner-run** step (for example a release-checklist step a person runs outside the Epic Implementer), declare it here, with every field `review-epic-coherence.md` defines, instead of forcing a sub-task to own it. Copy `step_text` verbatim from the design. An owner-run obligation never appears in a sub-task's `owns_verifications` or planned acceptance criteria.\n   - `owns_verifications` and the planned acceptance criteria are **authoring-only** fields. They live in `epic-manifest.json` and in the coherence input. **Never** add them, or any other field not listed in the sidecar rules below, to `epic-plan.dag.json`: that file is server-consumed and its schema does not change.\n\n   In addition, you MUST also write a structured JSON sidecar at\n   `{docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json`. This is unconditional —\n   it applies to a one- or two-sub-task decomposition exactly as it does to a larger\n   one. `plan-epic.json`'s step sequence is fixed (the orchestrator supports no\n   conditional steps), so every later step reads these artifacts regardless of the\n   sub-task count, and omitting them strands the run rather than simplifying it.\n   This file is the machine-readable intermediate that the later, separate launch\n   workflow stores and approves in the backend — `/plan-epic` itself does neither.\n   It must be written from your structured decomposition data, NEVER by\n   re-parsing the markdown.\n\n   The sidecar format is:\n\n```json\n{\n  \"plan_version\": 1,\n  \"nodes\": [\n    {\n      \"ticket_key\": \"TBD-1\",\n      \"status\": \"planned\",\n      \"depends_on\": [],\n      \"touched_files\": [\"api/routes/example.py\", \"src/python/llms/ai_client.py\"],\n      \"automations\": [\n        { \"kind\": \"start-tickets\" }\n      ]\n    }\n  ],\n  \"edges\": [\n    { \"from\": \"TBD-1\", \"to\": \"TBD-2\" }\n  ]\n}\n```\n\n   Rules for the sidecar:\n   - `plan_version` must be 1 for a new plan (an integer, never a float).\n   - Each node `ticket_key` is the placeholder `TBD-1`, `TBD-2`, and so on, in\n     node order. Keep every key as `TBD-N` until the child tickets exist. Never\n     guess a Jira key for a ticket that has not been created.\n   - `ticket_key` values must be unique and non-empty after trimming.\n   - `depends_on` lists the `ticket_key` values this node depends on (mirrors\n     the markdown Dependencies field). `depends_on` is the **canonical**\n     dependency declaration.\n   - `status` must be `\"planned\"` for newly-created sub-tasks.\n   - `touched_files` is **required on every node** — the sorted, deduplicated,\n     repository-relative POSIX paths this sub-task is predicted to change.\n     Populate it from your current code research and the sub-task's ownership,\n     the same analysis that tells you which sub-tasks collide.\n     - Include **anticipated tests, fixtures, golden files, guard allowlists,\n       and policy files** — not only the production modules. Every observed\n       overlap failure was this class: two children shared a production module\n       *and its test*, or a pair of golden files, and because nobody predicted\n       the shared file no ordering edge was synthesized.\n     - No leading `./`, no absolute paths, no `..` traversal segments, no\n       temporary-worktree paths, and no prose. Declare **concrete files**: the\n       backend intersects these paths as exact strings, so a directory or glob\n       entry matches nothing and protects nothing.\n     - `[]` is permitted **only** when the decomposition explicitly establishes\n       that the sub-task changes no repository files. Unknown file ownership is\n       **blocking** — resolve it or flag it; never represent it as an empty\n       array, which silently disables file-overlap protection.\n   - `automations` lists automation kinds to run on the ticket — valid values\n     are `\"start-tickets\"` and `\"review-tickets\"`. Use an empty array if none.\n   - `edges` is an explicit list of directed dependency edges (from → to, where\n     `from` is the predecessor). It may be empty if all dependencies are captured\n     in `depends_on`, but any edge you do write must encode the same graph as\n     `depends_on` — a contradictory graph blocks readiness.\n   - Do **not** set `base_lineage` on any node. It affects the plan hash but has\n     no consumer in the Epic Implementer, so setting it invalidates the approved hash\n     for no behavioral gain.\n   - The DAG must be acyclic (no circular dependencies).\n   - The deterministic Jira-dependency-link DAG builder is the documented\n     fallback/recovery path if this sidecar is lost or corrupted (not built here).\n\n   **Placeholders are finalized later, not here.** `TBD-N` remains the correct\n   node identity for the window before the epic's Jira tickets exist. The\n   standalone `emit-conductor-bundle.md` task replaces every placeholder with the\n   real ticket key and finalizes `touched_files` after the tickets are created and\n   before the plan is stored or approved. Write your best `touched_files`\n   prediction here anyway — that task reconciles it against the whole epic.\n\n   `/plan-epic` ends before storage: it never stores or approves this sidecar.\n   Finalization replaces every `TBD-N` placeholder before the plan is stored or\n   approved, and both `setup-epic` and the server refuse a plan whose node keys\n   are still `TBD-N`.\n\n   **Run the epic coherence check.** After `epic-plan.md`, `epic-manifest.json`, and `epic-plan.dag.json` are all written, and before anything is presented for approval in step 5, check the sub-tasks as a set against the epic's acceptance criteria. **This check runs on every `/plan-epic` decomposition, including one or two sub-tasks.** Elsewhere, a one- or two-ticket outcome is an ordinary sibling pair and skips the check. This surface is different: the epic already exists, so its children must still cover it however few there are.\n\n   1. **Source the epic acceptance criteria.** When `{epic_key}` is non-empty, read that epic with `get_ticket` and take its acceptance criteria and their verification sentences. When it is empty (this run started from free-form text), take them from the Epic Description above and from `{docs_dir}/epic-plans/{epic_slug}/goals-and-nfrs.md`. Give each an id (`AC-1`, `AC-2`, and so on) in the order found. If no acceptance criteria can be found, do not invent them: the check cannot run, the verdict is `not_checked`, and step 5 offers the attended retry-or-reasoned-bypass decision.\n   2. **Write the normalized input** to `{docs_dir}/epic-plans/{epic_slug}/epic-coherence-input.json`, in the input document shape `review-epic-coherence.md` defines. `epic` carries `key` (the epic key when there is one) or `slug` (the epic slug otherwise), plus `title` and `acceptance_criteria`. `design_text` holds the epic description plus the goals and design text from `goals-and-nfrs.md` and `codebase-exploration.md`. `manifest` and `child_evidence` are copied **unchanged** from `epic-manifest.json`, so `child_evidence` carries each sub-task's planned acceptance criteria and its verbatim `owns_verifications` obligations. When `epic-manifest.json` has `non_child_owners`, copy that array **unchanged** into the input too; include the design text each `step_text` was copied from in `design_text`.\n   3. **Bind all three identities.** Compute `manifest_sha256` over the `manifest` array, `child_evidence_sha256` over the `child_evidence` array, and `non_child_owners_sha256` over the `non_child_owners` array (an absent array hashes as an empty array), with the canonical JSON encoding `review-epic-coherence.md` specifies. The record must carry all three.\n   4. **Run the shared procedure.** Follow `review-epic-coherence.md` in `drafting` mode. Its input document path is `{docs_dir}/epic-plans/{epic_slug}/epic-coherence-input.json`, its output directory is `{docs_dir}/epic-plans/{epic_slug}/`, and the run is attended. It writes `epic-coherence.json` and `epic-coherence.md` beside the plan. When it asks for an amendment, amend the decomposition (add or rescope a sub-task, or reassign an obligation), rewrite `epic-plan.md`, `epic-manifest.json`, `epic-plan.dag.json`, and the input, and let the procedure re-check. Its bound is the procedure's risk-scaled round limit: maximum ordinary rounds (two low-risk and three high-risk), ending earlier after a round with zero foundation blockers. An amendment after the last allowed round gets one confirmation pass, never an older round's clearance. Read the procedure at `docs/install/review-epic-coherence-procedure.md` in this project, where the Bridge installer scaffolds it; if it is not there but `mcp_server/instructions/review-epic-coherence.md` exists in this checkout, read that instead. If neither exists, stop: the shared procedure is not installed, so re-run the Bridge installer or upgrade the Bridge package. Never improvise a substitute review.\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\n   Lead with the coherence result, in this order, before asking for approval:\n   - **Verdict** — the exact verdict from `epic-coherence.json`: `pass`, `accepted_with_gaps`, `blocked`, or `not_checked`. Never describe `not_checked` as a pass.\n   - **Independent: no**, shown prominently, when the record says `independent: false`. Offer a fresh-context rerun of the check.\n   - **Remaining blocking findings**, each with its id and smallest amendment — or, when the review could not run, the reviewer failure.\n   - **Coverage map** — one plain bullet per epic AC: the AC id, the owning sub-task (or, for an owner-run owner, the words \"owner-run\" with the person or role and the step reference), and the obligation that proves it.\n   - **Recorded reasons** — every accepted finding and every bypass, with its typed reason.\n\n   Each remaining **foundation** blocking finding must be either **fixed** (amend the decomposition, which rewrites the artifacts and re-runs the check) or **accepted** with a typed reason. Ticket-local blockers are carried to their child ticket and do not require acceptance at this epic approval gate. Record an accepted foundation finding in `epic-coherence.json` as an override of kind `accept` with its `finding_id`, `reason`, `accepted_by`, and `round`. When every remaining foundation blocking finding is accepted, the verdict becomes `accepted_with_gaps`. When the verdict is `not_checked`, offer a retry, or a bypass with a typed reason recorded as an override of kind `bypass`; the verdict stays `not_checked`.\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, and rewrite `epic-manifest.json`, `epic-plan.dag.json`, and `epic-coherence-input.json` from the same revised data\n   - Re-run the epic coherence check from step 3 on the new manifest. A changed manifest, changed child evidence, or changed non-child owners has a new digest, so never reuse the old record for it\n   - Present the revised decomposition and the new coherence result, 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\n   That confirmation is allowed only when `epic-coherence.json` matches **all three** current digests, its top-level digests equal its last round's digests (the only exception is the attended `amended_after_final_round: true` bypass the procedure defines, whose verdict is `not_checked`), no required council is left unresolved without a typed acceptance, and its verdict is one of:\n   - `pass`;\n   - `accepted_with_gaps`, with every remaining foundation blocking finding accepted and recorded with its finding id and a non-empty reason;\n   - `not_checked`, with a recorded `bypass` override carrying a non-empty reason typed by the user.\n\n   A `blocked` verdict, or a `not_checked` verdict without a recorded bypass, **cannot** be confirmed as approved, even if the user says yes. Say which finding or failure still blocks, and return to step 5. There is no unattended bypass on this surface.\n\n\n<!-- BEGIN BRIDGE TICKET-AUTHORING POSTURE -->\n<!-- Canonical source: docs/bridge-ticket-authoring.md.\n     This block is duplicated byte-identically onto every carrier. Never edit a\n     copy: edit the canonical source and re-copy it verbatim. A cross-surface\n     byte-equality test fails the build if any copy drifts by a single byte. -->\n\n## Ticket-authoring posture\n\nDeep reference: `docs/bridge-ticket-authoring.md`.\n\n**Draft through the writer.** Every ticket body — an epic parent, an epic child,\nand an ordinary sibling alike — is drafted by the `jira-ticket-writer` agent\nbefore `create_ticket` is called. Do not compose a ticket description inline.\n\n**Size the work.** Size each ticket by file-touch breadth and depth plus rough\nlines of code (LOC) changed:\n\n- `S = 1-2 files / <~80 LOC`\n- `M = ~3-8 files / ~80-400 LOC`\n- `L = ~8-15 files / ~400-900 LOC`\n- `XL = >15 files / >~900 LOC`\n\nTarget size priority: **L (target) -> XL (when the work does not fit in L) -> M\n(third choice) -> S (only when unavoidable)**. This applies equally to a\nstandalone ticket and to an epic child.\n\nAim each slice at L. When one will not fit, grow it to XL rather than splitting\nit — split only when the slice is genuinely two independent pieces of work,\nnever merely to land inside a band. Bridge's grooming and implementation process\nhandles a large vertical slice well and is overkill on small ones: every extra\nticket is another worktree, another PR, another rebase, and another chance for\ntwo workers to touch the same file. Reach for M because the work genuinely is\nthat size, not to avoid an XL.\n\nBeyond roughly 40 files or ~3000 LOC, split anyway. Past that point review\nturnaround and rebase cost dominate the run's budget, and a review that wedges\nholds the gate to its full retry ceiling before anyone notices.\n\n**Group at three.** Three or more implementable tickets is an epic: propose an\nepic parent plus an ordered child manifest, and resolve this surface's own\napproval gate before anything is created. One or two tickets are ordinary\nsiblings — no epic parent, no manifest. The threshold is exactly three.\n\n**Hand off once.** An epic handoff names exactly one conductor entry point,\n`drive-epic`, which selects the runnable path itself. Never present a choice\nbetween conductors.\n\n**Departure is closed-list only.** These three exceptions, and no others, permit\ndeparting from the rules above. Invoking one requires no announcement.\n\n- **E1 External-tracker mirroring** — a recorded upstream identifier exists and\n  its granularity is contractual. Bypasses sizing and the epic threshold.\n- **E2 Discovery-only spike** — no committed production-code deliverable.\n  Bypasses sizing only; does not bypass drafting through the writer.\n- **E3 Authorized incident containment** — tied to an active incident record,\n  not to schedule pressure. Bypasses sizing and the epic threshold.\n\nThe list is closed. Anything outside it is an escalation to the operator, not a\njudgement call. Explicitly refused as grounds for departure: a single-file\ntrivial fix (that is `S` reached through the normal path, not an exception),\ngeneric time pressure, \"already well specified\", \"faster without the writer\",\ndeveloper discretion, minor refactor, unattended mode, context limits, and \"hard\nto decompose\" (XL is the normal overflow, so that is the ordinary path and not a\ndeparture). Writer unavailability escalates; it never silently authorizes inline\ndrafting.\n\n<!-- END BRIDGE TICKET-AUTHORING POSTURE -->\n\n## Return\n\nConfirm \"Decomposition approved.\" and report the final sub-task count plus the path to `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md`. Flag if the count exceeded the recommended limit of 8.\n\nAlso report the epic coherence verdict, whether the check was independent, and the record path `{docs_dir}/epic-plans/{epic_slug}/epic-coherence.json`.\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\n   **Size every sub-task with the canonical ladder** in the posture block at the end of this file, by file-touch breadth and depth plus rough LOC changed. Apply its target priority: **L (target) -> XL (when the work does not fit in L) -> M (third choice) -> S (only when unavoidable)**. **A sub-task may be XL.** When one will not fit in `L`, grow it to `XL` rather than splitting it; split only when it is genuinely two independent pieces of work, or when it runs past roughly 40 files / ~3000 LOC. Bias toward fewer, larger, independently implementable vertical slices: a swarm of tiny children magnifies sibling merge risk under parallel Epic Implementer execution and spends the run's budget on coordination.\n\n   **Decompose once.** This pass freezes the split. Emit the same ordered-manifest shape the `idea-to-ticket` path uses (`decompose-epic-candidate.md`), so that per sub-task you record: title, scope boundary, **size band**, `depends_on` (hard prerequisites that must land first), `recommended_after` (soft sequencing preferences that are not blockers), a one-line order rationale, `owns_verifications`, and planned acceptance criteria. `owns_verifications` is a list of `{epic_ac, obligation}` entries, exactly as `review-epic-coherence.md` defines the field: `epic_ac` is the id of one of the epic's acceptance criteria, and `obligation` is the concrete part of that criterion's **verification** sentence this sub-task will carry out. Fill it in during this pass, the same pass that freezes the split — never as a later step. The planned acceptance criteria are the epic criteria text the sub-task helps satisfy plus each of its obligations word for word. Keep hard prerequisites strictly separate from soft sequencing — the recommended implementation order is derived from them, and conflating the two serializes work that could have run in parallel. No later stage re-derives a sub-task's scope while rendering its body.\n\n   **Three or more sub-tasks is an epic; one or two would ordinarily be siblings.** The threshold is exactly three. This surface is the one place that threshold does *not* decide the shape: `/plan-epic` runs against an epic ticket that already exists, so the grouping decision was made upstream and is not yours to reverse here. If the epic genuinely decomposes into only one or two sub-tasks, **say so plainly to the user** — that is a signal the epic was over-scoped and may be better as ordinary sibling tickets — and then continue with the steps below as written. Do not manufacture filler sub-tasks to reach three, and do not skip the artifacts step 3 requires; the `plan-epic` step sequence is fixed and every later step reads them. The epic coherence check in step 3 also still runs for one or two sub-tasks.\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- **Size**: {S | M | L | XL}\n- **Key files/areas**: {Files and code areas involved}\n- **Dependencies**: {Other sub-task numbers this depends on, or \"None\"}\n- **Recommended after**: {Soft sequencing preferences that are not blockers, or \"None\"}\n- **Order rationale**: {One line on why this sub-task sits at this point in the order}\n- **Owns verifications**: {One entry per owned epic AC: the AC id, then the obligation, word for word as in the JSON authoring manifest}\n\n### 2. {Sub-task title}\n...\n\n## Epic coherence\n\nSee `epic-coherence.json` (authoritative) and `epic-coherence.md` (human summary) in this directory.\n```\n\n   Keep the `## Epic coherence` section to that pointer. The coverage map lives in the record; do not keep a second, editable copy of it here.\n\n   Also write the **JSON authoring manifest** to `{docs_dir}/epic-plans/{epic_slug}/epic-manifest.json`, from the same structured decomposition data (never by re-parsing the markdown). It is the frozen manifest the epic coherence review checks, and it uses the input field names `review-epic-coherence.md` defines:\n\n```json\n{\n  \"manifest\": [\n    {\n      \"id\": \"1\",\n      \"title\": \"Sub-task title\",\n      \"scope\": \"What this sub-task covers\",\n      \"size_band\": \"L\",\n      \"depends_on\": [],\n      \"recommended_after\": [],\n      \"touched_files\": [\"api/routes/example.py\"],\n      \"read_files\": [\"api/library/example_reader.py\"],\n      \"owns_verifications\": [\n        { \"epic_ac\": \"AC-1\", \"obligation\": \"The concrete part of AC-1's verification this sub-task carries out\" }\n      ]\n    }\n  ],\n  \"child_evidence\": [\n    { \"id\": \"1\", \"acceptance_criteria\": [\"Each planned acceptance criterion of the sub-task, verbatim\"] }\n  ],\n  \"non_child_owners\": [\n    {\n      \"id\": \"OR-1\",\n      \"kind\": \"owner_run\",\n      \"who\": \"Release owner\",\n      \"step_ref\": \"Release checklist step 6\",\n      \"step_text\": \"The step's text, copied verbatim from the epic's design\",\n      \"records_result_in\": \"a comment on the epic\",\n      \"owns_verifications\": [\n        { \"epic_ac\": \"AC-2\", \"obligation\": \"The concrete part of AC-2's verification the owner-run step carries out\" }\n      ]\n    }\n  ]\n}\n```\n\n   - `manifest` is the complete, ordered sub-task list. `id` is the 1-based position as a string. `depends_on` and `recommended_after` hold those ids.\n   - `child_evidence` has one entry per sub-task, keyed by the same `id`. Its `acceptance_criteria` are the sub-task's planned acceptance criteria: the ratified epic criteria text it satisfies, plus every `owns_verifications` obligation word for word.\n   - `touched_files` lists the files a sub-task edits or creates. `read_files` is optional and lists files it only reads, when known; reads never count as an edit overlap or toward the high-risk path check.\n   - `non_child_owners` is optional. When the ratified design assigns an epic acceptance criterion's verification to a concrete **owner-run** step (for example a release-checklist step a person runs outside the Epic Implementer), declare it here, with every field `review-epic-coherence.md` defines, instead of forcing a sub-task to own it. Copy `step_text` verbatim from the design. An owner-run obligation never appears in a sub-task's `owns_verifications` or planned acceptance criteria.\n   - `owns_verifications` and the planned acceptance criteria are **authoring-only** fields. They live in `epic-manifest.json` and in the coherence input. **Never** add them, or any other field not listed in the sidecar rules below, to `epic-plan.dag.json`: that file is server-consumed and its schema does not change.\n\n   In addition, you MUST also write a structured JSON sidecar at\n   `{docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json`. This is unconditional —\n   it applies to a one- or two-sub-task decomposition exactly as it does to a larger\n   one. `plan-epic.json`'s step sequence is fixed (the orchestrator supports no\n   conditional steps), so every later step reads these artifacts regardless of the\n   sub-task count, and omitting them strands the run rather than simplifying it.\n   This file is the machine-readable intermediate that the later, separate launch\n   workflow stores and approves in the backend — `/plan-epic` itself does neither.\n   It must be written from your structured decomposition data, NEVER by\n   re-parsing the markdown.\n\n   The sidecar format is:\n\n```json\n{\n  \"plan_version\": 1,\n  \"nodes\": [\n    {\n      \"ticket_key\": \"TBD-1\",\n      \"status\": \"planned\",\n      \"depends_on\": [],\n      \"touched_files\": [\"api/routes/example.py\", \"src/python/llms/ai_client.py\"],\n      \"automations\": [\n        { \"kind\": \"start-tickets\" }\n      ]\n    }\n  ],\n  \"edges\": [\n    { \"from\": \"TBD-1\", \"to\": \"TBD-2\" }\n  ]\n}\n```\n\n   Rules for the sidecar:\n   - `plan_version` must be 1 for a new plan (an integer, never a float).\n   - Each node `ticket_key` is the placeholder `TBD-1`, `TBD-2`, and so on, in\n     node order. Keep every key as `TBD-N` until the child tickets exist. Never\n     guess a Jira key for a ticket that has not been created.\n   - `ticket_key` values must be unique and non-empty after trimming.\n   - `depends_on` lists the `ticket_key` values this node depends on (mirrors\n     the markdown Dependencies field). `depends_on` is the **canonical**\n     dependency declaration.\n   - `status` must be `\"planned\"` for newly-created sub-tasks.\n   - `touched_files` is **required on every node** — the sorted, deduplicated,\n     repository-relative POSIX paths this sub-task is predicted to change.\n     Populate it from your current code research and the sub-task's ownership,\n     the same analysis that tells you which sub-tasks collide.\n     - Include **anticipated tests, fixtures, golden files, guard allowlists,\n       and policy files** — not only the production modules. Every observed\n       overlap failure was this class: two children shared a production module\n       *and its test*, or a pair of golden files, and because nobody predicted\n       the shared file no ordering edge was synthesized.\n     - No leading `./`, no absolute paths, no `..` traversal segments, no\n       temporary-worktree paths, and no prose. Declare **concrete files**: the\n       backend intersects these paths as exact strings, so a directory or glob\n       entry matches nothing and protects nothing.\n     - `[]` is permitted **only** when the decomposition explicitly establishes\n       that the sub-task changes no repository files. Unknown file ownership is\n       **blocking** — resolve it or flag it; never represent it as an empty\n       array, which silently disables file-overlap protection.\n   - `automations` lists automation kinds to run on the ticket — valid values\n     are `\"start-tickets\"` and `\"review-tickets\"`. Use an empty array if none.\n   - `edges` is an explicit list of directed dependency edges (from → to, where\n     `from` is the predecessor). It may be empty if all dependencies are captured\n     in `depends_on`, but any edge you do write must encode the same graph as\n     `depends_on` — a contradictory graph blocks readiness.\n   - Do **not** set `base_lineage` on any node. It affects the plan hash but has\n     no consumer in the Epic Implementer, so setting it invalidates the approved hash\n     for no behavioral gain.\n   - The DAG must be acyclic (no circular dependencies).\n   - The deterministic Jira-dependency-link DAG builder is the documented\n     fallback/recovery path if this sidecar is lost or corrupted (not built here).\n\n   **Placeholders are finalized later, not here.** `TBD-N` remains the correct\n   node identity for the window before the epic's Jira tickets exist. The\n   standalone `emit-conductor-bundle.md` task replaces every placeholder with the\n   real ticket key and finalizes `touched_files` after the tickets are created and\n   before the plan is stored or approved. Write your best `touched_files`\n   prediction here anyway — that task reconciles it against the whole epic.\n\n   `/plan-epic` ends before storage: it never stores or approves this sidecar.\n   Finalization replaces every `TBD-N` placeholder before the plan is stored or\n   approved, and both `setup-epic` and the server refuse a plan whose node keys\n   are still `TBD-N`.\n\n   **Run the epic coherence check.** After `epic-plan.md`, `epic-manifest.json`, and `epic-plan.dag.json` are all written, and before anything is presented for approval in step 5, check the sub-tasks as a set against the epic's acceptance criteria. **This check runs on every `/plan-epic` decomposition, including one or two sub-tasks.** Elsewhere, a one- or two-ticket outcome is an ordinary sibling pair and skips the check. This surface is different: the epic already exists, so its children must still cover it however few there are.\n\n   1. **Source the epic acceptance criteria.** When `{epic_key}` is non-empty, read that epic with `get_ticket` and take its acceptance criteria and their verification sentences. When it is empty (this run started from free-form text), take them from the Epic Description above and from `{docs_dir}/epic-plans/{epic_slug}/goals-and-nfrs.md`. Give each an id (`AC-1`, `AC-2`, and so on) in the order found. If no acceptance criteria can be found, do not invent them: the check cannot run, the verdict is `not_checked`, and step 5 offers the attended retry-or-reasoned-bypass decision.\n   2. **Write the normalized input** to `{docs_dir}/epic-plans/{epic_slug}/epic-coherence-input.json`, in the input document shape `review-epic-coherence.md` defines. `epic` carries `key` (the epic key when there is one) or `slug` (the epic slug otherwise), plus `title` and `acceptance_criteria`. `design_text` holds the epic description plus the goals and design text from `goals-and-nfrs.md` and `codebase-exploration.md`. `manifest` and `child_evidence` are copied **unchanged** from `epic-manifest.json`, so `child_evidence` carries each sub-task's planned acceptance criteria and its verbatim `owns_verifications` obligations. When `epic-manifest.json` has `non_child_owners`, copy that array **unchanged** into the input too; include the design text each `step_text` was copied from in `design_text`.\n   3. **Bind all three identities.** Compute `manifest_sha256` over the `manifest` array, `child_evidence_sha256` over the `child_evidence` array, and `non_child_owners_sha256` over the `non_child_owners` array (an absent array hashes as an empty array), with the canonical JSON encoding `review-epic-coherence.md` specifies. The record must carry all three.\n   4. **Run the shared procedure.** Follow `review-epic-coherence.md` in `drafting` mode. Its input document path is `{docs_dir}/epic-plans/{epic_slug}/epic-coherence-input.json`, its output directory is `{docs_dir}/epic-plans/{epic_slug}/`, and the run is attended. It writes `epic-coherence.json` and `epic-coherence.md` beside the plan. When it asks for an amendment, amend the decomposition (add or rescope a sub-task, or reassign an obligation), rewrite `epic-plan.md`, `epic-manifest.json`, `epic-plan.dag.json`, and the input, and let the procedure re-check. Its bound is the procedure's risk-scaled round limit: maximum ordinary rounds (two low-risk and three high-risk), ending earlier after a round with zero foundation blockers. An amendment after the last allowed round gets one confirmation pass, never an older round's clearance. Read the procedure at `docs/install/review-epic-coherence-procedure.md` in this project, where the Bridge installer scaffolds it; if it is not there but `mcp_server/instructions/review-epic-coherence.md` exists in this checkout, read that instead. If neither exists, stop: the shared procedure is not installed, so re-run the Bridge installer or upgrade the Bridge package. Never improvise a substitute review.\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\n   Lead with the gap-check result, in this order, before asking for approval. Use the plain words in \"What the user sees\" in `review-epic-coherence.md`; the record keeps its technical values.\n   - **Result** — the verdict from `epic-coherence.json`, shown as `No gaps found`, `Accepted with known gaps`, `Needs your decision`, or `Couldn't check`. When a passing record carries ticket-local findings, show `No gaps found (N notes added to tickets)`. Never describe `Couldn't check` as a pass.\n   - **Less independent**, shown prominently, when the record says `independent: false`: \"this check ran in my own session, not by a separate reviewer, so it's less independent.\" Offer a fresh-context rerun of the check.\n   - **Remaining blocking findings**, each with its id and smallest amendment — or, when the review could not run, the reviewer failure. A carried ticket-local finding is shown as a note added to ticket N.\n   - **Who covers each requirement** — one plain bullet per epic AC: the AC id, the owning sub-task (or, for an owner-run owner, the words \"owner-run\" with the person or role and the step reference), and the obligation that proves it.\n   - **Recorded reasons** — every accepted finding and every bypass, with its typed reason.\n\n   Each remaining **foundation** blocking finding must be either **fixed** (amend the decomposition, which rewrites the artifacts and re-runs the check) or **accepted** with a typed reason. Ticket-local blockers are carried to their child ticket and do not require acceptance at this epic approval gate. Record an accepted foundation finding in `epic-coherence.json` as an override of kind `accept` with its `finding_id`, `reason`, `accepted_by`, and `round`. When every remaining foundation blocking finding is accepted, the verdict becomes `accepted_with_gaps`. When the verdict is `not_checked`, offer a retry, or a bypass with a typed reason recorded as an override of kind `bypass`; the verdict stays `not_checked`.\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, and rewrite `epic-manifest.json`, `epic-plan.dag.json`, and `epic-coherence-input.json` from the same revised data\n   - Re-run the epic coherence check from step 3 on the new manifest. A changed manifest, changed child evidence, or changed non-child owners has a new digest, so never reuse the old record for it\n   - Present the revised decomposition and the new coherence result, 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\n   That confirmation is allowed only when `epic-coherence.json` matches **all three** current digests, its top-level digests equal its last round's digests (the only exception is the attended `amended_after_final_round: true` bypass the procedure defines, whose verdict is `not_checked`), no required council is left unresolved without a typed acceptance (a `declined_by_operator` council is resolved and needs no override), and its verdict is one of:\n   - `pass`;\n   - `accepted_with_gaps`, with every remaining foundation blocking finding accepted and recorded with its finding id and a non-empty reason;\n   - `not_checked`, with a recorded `bypass` override carrying a non-empty reason typed by the user.\n\n   A `blocked` verdict, or a `not_checked` verdict without a recorded bypass, **cannot** be confirmed as approved, even if the user says yes. Say which finding or failure still blocks, and return to step 5. There is no unattended bypass on this surface.\n\n\n<!-- BEGIN BRIDGE TICKET-AUTHORING POSTURE -->\n<!-- Canonical source: docs/bridge-ticket-authoring.md.\n     This block is duplicated byte-identically onto every carrier. Never edit a\n     copy: edit the canonical source and re-copy it verbatim. A cross-surface\n     byte-equality test fails the build if any copy drifts by a single byte. -->\n\n## Ticket-authoring posture\n\nDeep reference: `docs/bridge-ticket-authoring.md`.\n\n**Draft through the writer.** Every ticket body — an epic parent, an epic child,\nand an ordinary sibling alike — is drafted by the `jira-ticket-writer` agent\nbefore `create_ticket` is called. Do not compose a ticket description inline.\n\n**Size the work.** Size each ticket by file-touch breadth and depth plus rough\nlines of code (LOC) changed:\n\n- `S = 1-2 files / <~80 LOC`\n- `M = ~3-8 files / ~80-400 LOC`\n- `L = ~8-15 files / ~400-900 LOC`\n- `XL = >15 files / >~900 LOC`\n\nTarget size priority: **L (target) -> XL (when the work does not fit in L) -> M\n(third choice) -> S (only when unavoidable)**. This applies equally to a\nstandalone ticket and to an epic child.\n\nAim each slice at L. When one will not fit, grow it to XL rather than splitting\nit — split only when the slice is genuinely two independent pieces of work,\nnever merely to land inside a band. Bridge's grooming and implementation process\nhandles a large vertical slice well and is overkill on small ones: every extra\nticket is another worktree, another PR, another rebase, and another chance for\ntwo workers to touch the same file. Reach for M because the work genuinely is\nthat size, not to avoid an XL.\n\nBeyond roughly 40 files or ~3000 LOC, split anyway. Past that point review\nturnaround and rebase cost dominate the run's budget, and a review that wedges\nholds the gate to its full retry ceiling before anyone notices.\n\n**Group at three.** Three or more implementable tickets is an epic: propose an\nepic parent plus an ordered child manifest, and resolve this surface's own\napproval gate before anything is created. One or two tickets are ordinary\nsiblings — no epic parent, no manifest. The threshold is exactly three.\n\n**Hand off once.** An epic handoff names exactly one conductor entry point,\n`drive-epic`, which selects the runnable path itself. Never present a choice\nbetween conductors.\n\n**Departure is closed-list only.** These three exceptions, and no others, permit\ndeparting from the rules above. Invoking one requires no announcement.\n\n- **E1 External-tracker mirroring** — a recorded upstream identifier exists and\n  its granularity is contractual. Bypasses sizing and the epic threshold.\n- **E2 Discovery-only spike** — no committed production-code deliverable.\n  Bypasses sizing only; does not bypass drafting through the writer.\n- **E3 Authorized incident containment** — tied to an active incident record,\n  not to schedule pressure. Bypasses sizing and the epic threshold.\n\nThe list is closed. Anything outside it is an escalation to the operator, not a\njudgement call. Explicitly refused as grounds for departure: a single-file\ntrivial fix (that is `S` reached through the normal path, not an exception),\ngeneric time pressure, \"already well specified\", \"faster without the writer\",\ndeveloper discretion, minor refactor, unattended mode, context limits, and \"hard\nto decompose\" (XL is the normal overflow, so that is the ordinary path and not a\ndeparture). Writer unavailability escalates; it never silently authorizes inline\ndrafting.\n\n<!-- END BRIDGE TICKET-AUTHORING POSTURE -->\n\n## Return\n\nConfirm \"Decomposition approved.\" and report the final sub-task count plus the path to `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md`. Flag if the count exceeded the recommended limit of 8.\n\nAlso report the gap-check result in the plain words from `review-epic-coherence.md` (`No gaps found`, `Accepted with known gaps`, `Needs your decision`, or `Couldn't check`), whether the check was independent (if not, say it is less independent), and the record path `{docs_dir}/epic-plans/{epic_slug}/epic-coherence.json`.\n",
     "draft-and-critique.md": "Draft the ticket(s) for this idea, run a BAPI-320 hygiene pass, and emit structured draft metadata.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n- Research pack: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-pack.md` / `.json`.\n- Duplicate assessment: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/duplicate-assessment.json`.\n- Standards checklist: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/standards-checklist.json`.\n- Resolved uncertainties: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/resolved-uncertainties.md`.\n- Goals & NFR framing: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/goals-and-nfrs.md`.\n- Comp→codebase map (optional): `{docs_dir}/idea-to-ticket/{slug}-{run_id}/comp-analysis.json`. Produced upstream by the gated `comp-analysis.md` perception step. A missing, unreadable, or `applicable: false` map is treated exactly like `applicable: false` — a no-op: it never halts drafting and this step injects no visual-fidelity/comp language on its own.\n\n## Instructions\n\n1. **Resolve the regression-completeness gate once, before drafting.** Call the `config_field` MCP tool with `operation` set to `\"get\"` and `field_name` set to `enable_regression_checks`. Normalize the response: only the exact value `true` (a JSON boolean `true`, or the case-insensitive string `\"true\"`) counts as enabled. Treat a missing tool, a tool error, `null`, `false`, or any other/malformed value as disabled — this lookup is fail-open and defaults OFF. Store the normalized boolean as `enable_regression_checks` and reuse the same stored value for every `jira-ticket-writer` invocation this flow makes (including any later critique/revision call) — do not re-resolve it per call. The `jira-ticket-writer` sub-agent must not call `config_field` itself.\n\n2. Read the six required input artifacts in full before drafting, plus the comp-analysis map when it is present. The manifest's `scope` (`task`, `spike`, or `epic_candidate`) determines the drafting path.\n\n   The goals-and-nfrs.md framing must shape every draft. Lead each draft with the **business goal** and **desired end-state**, and include an explicit **Non-Functional Requirements** section (and, where it clarifies behavior, the required **system behavior**). For the **epic_candidate** parent, these belong in the Epic description itself (the parent's `slim_description` should at least name the business goal + end-state, and the attached full draft must carry the Goals / Desired End-State / Non-Functional Requirements sections). Any NFR still marked `open` in the framing must be written into the draft as an explicit assumption plus an open-risk note — never silently dropped. This flow is documentary: do not generate a decision page and do not pause for clarification here.\n\n3. Drafting path by scope:\n   - **task** or **spike**:\n     - Call the `jira-ticket-writer` sub-agent with an explicit output path of `{docs_dir}/tickets/TICKET-{slug}.md`. The sub-agent must write the full markdown draft to that exact file. Pass the comp-analysis map path (`{docs_dir}/idea-to-ticket/{slug}-{run_id}/comp-analysis.json`) into the sub-agent prompt alongside the six existing input artifacts (run manifest, research pack, duplicate assessment, standards checklist, resolved uncertainties, goals-and-nfrs) and the stored `enable_regression_checks` value from step 1.\n     - **Pass the manifest's already-resolved `scope` explicitly into the sub-agent prompt**, stated as `scope: task` or `scope: spike`. The writer selects the spike ticket format on `scope: spike` alone, and on nothing else — never ask it to judge whether the work \"feels\" investigative or is primarily discovery/research, and never leave the value unstated for it to infer. The objective decision was already made once, at `preflight-and-readiness.md`, against the E2 condition \"no committed production-code deliverable\"; a missing, malformed, or unrecognized value means the writer produces the ordinary code-ticket format.\n   - **epic_candidate**:\n     - Call `jira-ticket-writer` to draft only the Epic parent. Use the explicit output path `{docs_dir}/tickets/EPIC-{slug}.md`. Pass the same comp-analysis map path into the sub-agent prompt alongside the six existing input artifacts and the stored `enable_regression_checks` value from step 1. Child tickets are produced later by `decompose-epic-candidate.md`; do not draft them here.\n\n   Comp-analysis map consumption (both paths): when `comp-analysis.json` has `applicable: true`, tell the writer its Requirements MUST use the mapped components/templates/tokens/routes as concrete implementation guidance (e.g. \"reuse component X\", \"use token Z\", \"extend template Y\", \"wire route R\"). When the map has `applicable: false` or is missing/unreadable, tell the writer to ignore the artifact entirely and avoid mentioning comp analysis, design comps, or visual fidelity unless the original request independently requires those materials. This step only feeds the text JSON map to the writer — it never opens images, calls `describe_image()`, or performs vision analysis itself.\n\n   Regression-gate consumption (both paths): state `enable_regression_checks: {stored value from step 1}` explicitly in the sub-agent prompt, and tell the writer this value was already resolved by the caller and must not be looked up again. The writer only runs its Regression Completeness Pass when this value is exactly `true`.\n\n4. **Every body goes through the writer, and the split is not yours to change.** The ticket-authoring posture (`docs/bridge-ticket-authoring.md`, carried verbatim by `decompose-epic-candidate.md` in this same flow) requires that every Jira body — Epic parent, child, and ordinary sibling alike — is drafted by `jira-ticket-writer`. State that posture explicitly in each sub-agent prompt, together with the approved manifest entry the invocation is bound to when one exists, so the writer knows it is rendering a frozen entry rather than deciding one.\n\n   This applies identically to the **initial draft** and to any **revision** the hygiene/critique pass triggers. A revision re-invokes `jira-ticket-writer` with the *same* manifest entry and the *same* posture. Critique may improve a body's prose, evidence, and precision. It may not change the approved ticket count, the ordering, the parent relationship, an entry's dependency lists, its scope boundary, or its sizing classification — those were settled by the decomposition pass, and a critique pass sees one body at a time, so a split re-decided here is re-decided on strictly less information. A critique that believes the split is wrong reports that to the caller; it does not act on it.\n\n5. Issue type policy:\n   - Default ambiguous ideas to `Task`.\n   - Choose `Spike` only when the work is primarily discovery/research/learning with no clear acceptance criteria yet.\n   - The Epic parent uses Jira issue type `Epic`.\n\n6. Hygiene pass (BAPI-320 forbidden tokens). After the sub-agent writes the draft, read it back and ensure none of these tokens are present:\n   - markdown tables (any `|`-separated header row).\n   - escaped pipe-table patterns (e.g. `\\|`).\n   - task-list checkboxes such as `- [ ]` or `- [x]`.\n   - angle-bracket placeholder tokens (any `<placeholder>` form, even inside backticks).\n   - raw HTML blocks (`<div>`, `<br>`, `<table>`, etc.).\n   When a forbidden token is found, rewrite the surrounding paragraph in plain prose or bullet form and save the cleaned draft over the same path.\n\n   **One exemption, and only one:** on a `spike` draft, the canonical execution-class marker line `<!-- bridge:execution-class=investigation -->` is NOT a forbidden raw-HTML token. Leave it exactly as the writer wrote it — same spelling, same single occurrence, same position immediately after the title. Cleaning it away would silently strip the ticket's only machine-readable class signal. This exemption covers that one literal on a spike draft and nothing else; every other angle-bracket construct stays forbidden, and a `task` draft has no exemption because it carries no marker.\n\n7. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/draft-metadata.json` describing what Jira should later create.\n\n   For **task** / **spike** scope, the metadata shape is:\n   - `summary` — Jira ticket title.\n   - `issue_type` — `Task` or `Spike`.\n   - `labels` — array of Jira labels. Must include `ai-generated`, `idea-to-ticket`, the per-run label `bapi-idea-to-ticket-{run_id}`, and the stable idea-hash label `bapi-idea-hash-{idea_hash}` (so a future run of the same idea is caught by label).\n   - `idempotency_label` — `bapi-idea-to-ticket-{run_id}` (matches the label used by the duplicate-and-context-scan step).\n   - `slim_description` — short Jira-safe description (no forbidden tokens). The full draft is uploaded as an attachment. It must include a CONCISE, high-level summary of the draft's `## Materials & Access` inventory (Planning Assets, Downloadable Assets, Planning & Downloadable Assets vs. unphased record-only material), noting that the exhaustive list lives in the attached full draft. This keeps the missing-materials record visible to human reviewers and to description-reading review/critique flows.\n\n     **Marker preservation (`spike` scope).** The Jira issue is created from `slim_description`, not from the full draft — the draft only becomes an attachment. So a marker that survives only in the attachment leaves the persisted ticket record with no machine-readable signal at all, which defeats the marker's entire purpose. When slimming a `spike` draft, carry the draft's title line and the canonical `<!-- bridge:execution-class=investigation -->` line into `slim_description` first, in that original order, before the summarized body — exactly one occurrence, byte-for-byte, alone on its own line. Do not rewrite it, reformat it, translate it into a label, move it below the body, or leave it behind in the attachment.\n\n     **No marker synthesis (`task` scope).** A `task` draft carries no marker, and slimming must not invent one. Writing a marker here would fabricate an execution-class signal the author never declared.\n   - `attachment_path` — `{docs_dir}/tickets/TICKET-{slug}.md` (or the equivalent path used above).\n\n   For **epic_candidate** scope, the metadata shape is:\n   - `parent.summary` — Epic title.\n   - `parent.issue_type` — `Epic`.\n   - `parent.labels` — must include `ai-generated`, `idea-to-ticket`, `bapi-idea-to-ticket-{run_id}-parent`, and the stable idea-hash label `bapi-idea-hash-{idea_hash}`.\n   - `parent.idempotency_label` — `bapi-idea-to-ticket-{run_id}-parent`.\n   - `parent.slim_description` — short Epic description. It must include a CONCISE, high-level summary of the Epic draft's `## Materials & Access` inventory (Planning Assets, Downloadable Assets, Planning & Downloadable Assets vs. unphased record-only material), noting that the exhaustive list lives in the attached full draft.\n   - `parent.attachment_path` — `{docs_dir}/tickets/EPIC-{slug}.md`.\n   - `children` — placeholder array. Populated later by `decompose-epic-candidate.md`; leave as an empty array here.\n\n8. Save the metadata exactly once. Downstream steps read this file; do not move it.\n\n## Return\n\nConfirm the draft path, the metadata path, and the chosen scope (`task`, `spike`, or `epic_candidate`).\n",
     "duplicate-and-context-scan.md": "Detect existing Jira tickets that duplicate or relate to this idea before any Jira mutation.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n- Research pack: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-pack.md` (if produced).\n- Pipeline variable `allow_duplicate` controls override behavior (for this run, `allow_duplicate` = `{allow_duplicate}`). Treat the literal string `\"true\"` as override; any other value (including `\"false\"`, missing, or empty) is non-override.\n\n## Callers\n\nTwo callers use this procedure. The **recipe path** is everything under Instructions below and is unchanged. The **define-tickets path** is the separate branch at the end of that section; it is used only by `/define-tickets --auto`, and none of the recipe's label queries apply to it.\n\n## Instructions\n\n> **Orchestrator-directed step.** This agent task is part of the full-automation chain and is authorized to call `get_tickets` as directed below — performing an orchestrator-directed tool call is not \"re-orchestrating\".\n\n1. Build at least two Jira search queries from the manifest:\n   - **Title/keyword query**: use the most salient nouns from `idea` and `slug` as title/text keywords. Prefer 2-4 concrete terms over long natural-language sentences. Run via `get_tickets`.\n   - **Stable idea-hash query** (the reliable cross-run dedup): run `get_tickets` with its `labels` parameter set to `bapi-idea-hash-{idea_hash}`. This label is identical for every run of the same idea, so it catches a PRIOR run that already created a ticket for this idea — even one created days ago. A hit here is a strong `duplicate` signal.\n   - **Idempotency-label query**: run `get_tickets` with its `labels` parameter set to `bapi-idea-to-ticket-{run_id}` (the tool builds the `labels in (...)` JQL for you — do not pass a raw JQL string). This per-run label only matches a partial run of THIS same run, so it supports resume behavior.\n\n2. For each returned ticket, capture: ticket key, summary, status, and a short reason it matched (which query, which keyword).\n\n3. Classify the overall verdict as one of:\n   - `duplicate` — at least one returned ticket clearly describes the same work as `idea`.\n   - `related` — returned tickets are adjacent or partial overlaps but not the same work.\n   - `none_found` — no meaningful matches.\n   - `unable_to_check` — the Jira search itself failed (network error, auth error, JQL rejection). Record the failure and pick this verdict.\n\n4. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/duplicate-assessment.json` with at minimum:\n   - `verdict` — one of the four values above.\n   - `matches` — array of `{ticket_key, summary, status, reason}` objects (may be empty).\n   - `queries_used` — array of the actual JQL/search strings sent.\n   - `allow_duplicate` — the resolved value of `{allow_duplicate}` for this run.\n\n5. Halt behavior:\n   - If `verdict` is `duplicate` and `allow_duplicate` is not `\"true\"`, halt locally. Do not continue the pipeline. Tell the user that the duplicate halt is strict and that re-running with `--allow-duplicate` overrides it.\n   - If `verdict` is `duplicate` and `allow_duplicate` is `\"true\"`, continue the pipeline but keep the duplicate evidence in the assessment file so downstream steps can reference it (e.g., to add a \"supersedes\" note to the draft).\n   - For `related`, `none_found`, and `unable_to_check`, continue without halting.\n\n### Define-tickets path\n\nUsed only when `/define-tickets --auto` runs this procedure. The command names the artifact directory, a unique local run id, and the resolved `allow_duplicate` literal in its invocation. There is no run manifest and no label.\n\n1. Run at least two `get_tickets` searches using its `query` parameter: one keyword search built from the salient nouns of the task, and one search on the candidate ticket title. Never pass `labels`; the label queries above belong to the recipe path only.\n2. Capture each returned ticket's key, summary, status, and a short reason it matched. Classify the verdict as `duplicate`, `related`, `none_found`, or `unable_to_check`, using the same definitions as above.\n3. Write `duplicate-assessment.json` to the named artifact directory with `verdict`, `matches`, `queries_used`, and the resolved `allow_duplicate` value.\n4. Halt behavior for this path: a `duplicate` verdict halts the command unless `allow_duplicate` is the literal string `\"true\"`. That override applies only to a known `duplicate` verdict. An `unable_to_check` verdict is never overridden. The command halts as `stage_failed` and names the duplicate scan. Matches found here were not created by this run.\n\n## Return\n\nConfirm `duplicate-assessment.json` was written, report `verdict`, and report whether the run is halting or continuing.\n",
     "emit-conductor-bundle.md": "Harmonize an epic's sibling tickets against each other and emit the artifacts the Epic Implementer needs, after the tickets exist and before the plan is approved.\n\nEach sibling ticket was drafted by a separate writer session that could not see\nits siblings. Each independently re-researched the codebase and re-derived\ninterfaces, names, and file ownership, so siblings routinely disagree exactly at\nthe seams where they must agree — the dependency edges. The decomposition itself\nwas coherent (one agent, one context, wrote `epic-plan.md` and every exploration\ndocument); that coherence is discarded at the handoff. This task reads every\nsibling in one context and restores it.\n\nThe window is forced. Real ticket keys exist only after creation, and description\nrewrites are free before approval but trip `spec_stale` after it.\n\n**This is a standalone task, deliberately not a step in `plan-epic.json`.**\n`plan-epic` creates no tickets, so wiring this in there would guarantee it runs\nbefore any sibling exists. The local agent invokes it directly, immediately after\ncreating the epic's tickets, passing the ordered node→key mapping it already\nholds.\n\n## Inputs\n\n- `epic_key` — the Jira key of the epic (e.g. `BAPI-634`). **Required.**\n  `setup-epic --dry-run` needs it, it cannot be derived safely from the slug, and\n  it cannot be recovered from Jira: `get_tickets` filters only by free-text\n  `search` and `labels`, with no `parent_key` filter.\n- `epic_slug` — the sanitized slug naming the epic-plan directory.\n- An **ordered array of mapping entries**, one per sidecar node, each with:\n  - `plan_node_id` — the node's identity in `epic-plan.dag.json` (a `TBD-N`\n    placeholder on the initial run, or the real key on a rerun).\n  - `ticket_key` — the real Jira key created for that node.\n  - `exploration_path` — that sub-task's exploration document, relative to the\n    epic-plan directory.\n  - `draft_path` — that sub-task's draft, relative to the epic-plan directory.\n\n**Node identity comes only from `plan_node_id`.** Never infer which node a ticket\nbelongs to from mapping order, ticket titles, description text, or a Jira search.\nA key list plus `epic_slug` cannot determine which real key replaces which\n`TBD-N`, and guessing attaches one ticket's dependencies to another.\n\n## Instructions\n\nResolve `docs_dir` by calling the `ping` MCP tool (no parameters) and reading\n`docs_dir` from its first (JSON) content item. The\nsole workspace for this task is `{docs_dir}/epic-plans/{epic_slug}`. Never read or\nwrite outside it.\n\nExecute the following phases **in this order**. The ordering is the safety\nproperty: every external write is gated behind local validation, so a failure\nleaves Jira untouched rather than half-mutated. Pipeline ordering cannot protect a\nmanual or recovery run, so this task owns it.\n\n### Phase 1 — Non-mutating run-state precheck\n\nBefore reading artifacts, confirm the epic is still in the pre-approval window:\n\n```bash\nnpx -y -p @bridge_gpt/mcp-server epic-implementer epic-status --epic-key <epic_key> --json\n```\n\nThis is read-only. Interpret the result:\n\n- `{\"status\": \"unknown\", \"state\": null}` — no run exists yet. **Proceed**; the\n  dry-run does not create one. A run is created later, only through\n  `/drive-epic-run <epic_key>` (which launches via `drive-epic`).\n- `epic_run.status` is `planning` **and** its plan version is not yet stored —\n  a single unapproved planning run. **Proceed**; it may be reused.\n- `epic_run.status` is `active`, `blocked`, `done`, or `abandoned` — **halt.**\n- `epic_run.approved_plan_hash` is non-null (the plan is approved) — **halt.**\n- The sidecar's `plan_version` is already stored — **halt.** Plan blobs are\n  immutable and post-approval description rewrites are forbidden; this needs an\n  explicit re-plan.\n- Multiple runs, or any ambiguous/unreadable state — **halt.** Never guess.\n\nHalting here means reporting the state and stopping. Do not attempt a repair.\n\n### Phase 2 — Validate inputs and source artifacts\n\nAssemble the mapping into a JSON input document. Both the ordered mapping and\nthe `decomposition_fingerprint` are derived from the **approved ordered manifest**\n— the split the decomposition pass froze and the approval gate accepted — and\nnever from a fresh decomposition performed here. This task harmonizes bodies\nagainst each other; it does not re-decide the split, and a fingerprint computed\nover a newly derived decomposition would silently detach the bundle from the plan\nthat was actually approved.\n\n```json\n{\n  \"epic_key\": \"<epic_key>\",\n  \"epic_slug\": \"<epic_slug>\",\n  \"decomposition_fingerprint\": \"<stable fingerprint of this decomposition>\",\n  \"mappings\": [\n    {\n      \"plan_node_id\": \"TBD-1\",\n      \"ticket_key\": \"BAPI-635\",\n      \"exploration_path\": \"explorations/01-<subtask-slug>.md\",\n      \"draft_path\": \"drafts/01-<subtask-slug>.md\"\n    }\n  ]\n}\n```\n\nThen run the deterministic entry validation **before reading any mapped file,\nfetching any ticket, or writing any artifact**:\n\n```bash\nnpx -y @bridge_gpt/mcp-server emit-epic-implementer-bundle validate \\\n  --input <path to the input document> \\\n  --json\n```\n\nThis writes nothing. A non-zero exit halts the task; relay its error verbatim.\nThese are entry-point checks, not agent judgment. It enforces:\n\n- `epic_key` and every `ticket_key` match the project's Jira key pattern, are\n  non-empty and unique, and no child key equals `epic_key`.\n- `epic_slug` matches the sanitized slug grammar.\n- The mapping is **complete and one-to-one**: every sidecar node has exactly one\n  entry, and every entry matches exactly one node — by `plan_node_id` on the\n  initial run, or by its already-mapped `ticket_key` on a rerun.\n- An existing `sibling-ticket-manifest.json` agrees with the supplied mapping on\n  epic identity, slug, plan version, decomposition fingerprint, and every\n  node→key pair. **On disagreement, halt** — never silently prefer either source.\n- Every mapped path resolves beneath `{docs_dir}/epic-plans/{epic_slug}`.\n  Absolute paths, `..` traversal, paths into another epic's directory, unknown\n  mapping paths, and symlink escapes are all rejected before their content is read.\n\nThen load these **authoritative artifacts** into one working context:\n\n- `{docs_dir}/epic-plans/{epic_slug}/goals-and-nfrs.md`\n- `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md`\n- `{docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json`\n- every mapped exploration document\n- every mapped draft\n\n**Halt** if any of them is missing, malformed, or unmatched. These are\nauthoritative inputs; proceeding without one voids the reconciliation guarantee.\n\nRe-fetch every mapped child ticket by its supplied key (`get_ticket`) and keep\nthe complete sibling set in one context. Reading them one at a time defeats the\nentire purpose of this task.\n\nDelimit every dynamically inserted Jira, plan, draft, or exploration excerpt with\ntriple quotes before analyzing it, and strip secret-like content before it can\nreach a prompt, a rendered description, decision material, a report, or an\nattachment.\n\n### Phase 3 — Harmonize the whole epic (in memory)\n\n**Authority order when sources conflict:**\n\n1. Exploration documents and current code research — primary evidence.\n2. Intended scope in `epic-plan.md` — what the decomposition meant to build.\n3. Current ticket descriptions — **outputs to be corrected, never authoritative\n   inputs.**\n\nReview the complete sibling set once against this taxonomy, rather than a vague\n\"look for problems\" pass:\n\n- **interface drift** — the same function, endpoint, table, or field described\n  differently across siblings.\n- **ownership collision** — two tickets both claiming to create the same file,\n  symbol, or migration.\n- **orphan consumer** — a ticket consuming a seam no sibling produces.\n- **order violation** — a ticket assuming work a later sibling does.\n- **scope overlap** — two tickets covering the same work.\n- **vocabulary drift** — the same concept named inconsistently.\n- **NFR conflict** — a ticket contradicting `goals-and-nfrs.md`.\n\nEvery dependency edge must end up with an explicit producer, an explicit\nconsumer, an owned seam, an exact interface or artifact name, and a required\nordering.\n\n#### Canonical contract blocks\n\nRender each shared seam **once**, and insert byte-identical text into both the\nproducer's and the consumer's description. This is what makes \"described\nidentically at the edge\" checkable rather than a matter of opinion.\n\nUse stable delimiters and a stable seam identifier:\n\n```\n<!-- BEGIN CONTRACT: {seam_id} -->\n**Contract: {seam_id}**\n\n- **Producer**: {producer_ticket_key}\n- **Consumer(s)**: {consumer_ticket_keys}\n- **Interface**: {exact name and signature/shape}\n- **Ordering**: {what must exist before what}\n<!-- END CONTRACT: {seam_id} -->\n```\n\n`{seam_id}` is derived deterministically from the seam's identity (the interface\nor artifact name), so the same seam keeps the same id across runs. Everything\noutside a contract block stays ticket-specific: each ticket keeps its own\nsummary, scope, requirements, acceptance criteria, constraints, and risks.\n\n#### Fold in the exploration document\n\nThe description is the **only** channel an Epic Implementer worker can see. The\nreconciler resolves the spec and ships it in the job payload; the worker reads the\nticket, not the repo. `docs/tmp/epic-plans/` is gitignored and worker worktrees\nare cut from a pinned `origin/<base>` SHA, so exploration documents are never on\ndisk for the implementing agent.\n\nFold each sub-task's exploration document into its ticket under a deterministic\ndelimited section:\n\n```\n<!-- BEGIN EXPLORATION: {ticket_key} -->\n...\n<!-- END EXPLORATION: {ticket_key} -->\n```\n\nPreserve every implementation-relevant file, symbol, interface, constraint,\ndecision, and open risk. Resolve every mapped `TBD-N` token to its real key in\nticket prose, exploration content, drafts, and contract blocks — not only in the\nsidecar. Drafts authored before the tickets existed refer to siblings as `TBD-N`;\na worker receiving that text has no actionable dependency reference.\n\n#### The spec length bound — fail loud\n\nValidate every complete rendered description against the bound. The Epic Implementer's\npayload bound is **64,000 characters** (the reconciler no longer truncates\nsilently — overflow beyond its own bound is visibly marked). For Jira-backed\ntickets the **practical** limit binds far earlier: Jira caps a description at\n**32,767 characters**, so treat that as the real-world ceiling there.\n\nCount **Unicode code points**, not UTF-16 code units — the server's bound is a\nPython `len()`, so an astral character (an emoji, say) counts once there but\ntwice under a naive JavaScript `.length`, which would reject a description that\nactually fits.\n\n- Compact repetition and non-actionable prose **first**, without dropping\n  actionable content.\n- If the required content still will not fit, **fail loud and escalate** as a\n  decomposition/scope finding.\n- An attachment is **not** a workaround — the worker cannot see it.\n- Raising the server-side bound is out of scope.\n\n#### Auto-resolve vs escalate\n\n**Auto-resolve only** when the authoritative artifacts make the intended contract\nunambiguous: normalizing vocabulary, or copying a producer's already-defined\ninterface name to its consumer.\n\n**Escalate** any proposed change to scope, decomposition, ownership boundaries,\ndependencies, public contracts, migrations, NFRs, or acceptance criteria. A\ncontradiction implying a scope or decomposition change is not a wording fix;\nauto-resolving one silently is worse than the contradiction, because it launders a\nreal decision into prose nobody reviewed.\n\n#### Build `touched_files`\n\nThe file-ownership map you built to detect **ownership collision** *is*\n`touched_files`. This step is the only place with a whole-epic view, and nothing\nelse emits the field today.\n\n- Sorted, deduplicated, repository-relative POSIX paths — no leading `./`, no\n  absolute paths, no `..` traversal, no temporary-worktree paths, no prose. The\n  `finalize` step rejects anything else rather than dropping it. Concrete files\n  only: the backend intersects these as exact strings, so a directory or glob\n  entry protects nothing.\n- Every node carries the field. `[]` is valid **only** where the ticket genuinely\n  touches no repository files and that is explicit.\n- **Unknown ownership is escalated, never encoded as `[]`** — an empty array\n  silently disables overlap protection.\n- When two tickets legitimately touch the same file, **both** keep it. If one\n  consumes an interface the other produces, add the semantic dependency\n  explicitly rather than relying on overlap serialization for ordering.\n\n##### What `touched_files` can and cannot prove (BAPI-848)\n\n`touched_files` is a **pre-implementation prediction**, written before the work\nexists. Overlap serialization intersects those declared lists as exact strings,\nso it proves ordering **only for paths both nodes actually declared**. Its\ncoverage scope is `declared_files_only`, and the server now reports that scope\nalongside the counts.\n\nTwo consequences, both load-bearing:\n\n- **A passing dry run and `inserted_edges: 0` prove nothing about the\n  implementation.** Zero edges means \"no two nodes declared the same path\". It\n  does not mean the implementations will avoid each other. In epic BAPI-776 the\n  plan reported `inserted_edges: 0` and all three tickets converged on one line\n  of one undeclared file.\n- **An undeclared file is invisible to serialization**, whatever the work ends\n  up touching. This is a **deliberately accepted limitation**: an implementation\n  that touches a genuinely undeclared, non-discoverable file is not\n  automatically serialized against its siblings. Merge-conflict detection plus\n  `JOB_TYPE_REBASE` remains the reactive backstop.\n\nThe obvious \"fix\" — attaching a blanket set of hotspot paths to every node — is\n**wrong and must not be done.** It would serialize unrelated siblings and\neffectively disable the parallelism the Epic Implementer exists to provide.\n\n**Prefer removing a hotspot structurally over scheduling around it.** A test\nrunner, build manifest, or route table that enumerates its members by hand is a\nrepository-wide serialization point: every ticket that adds a member must edit\nthat one shared line, so any two such tickets conflict by construction, and a\nmember left off it silently runs nowhere. Replacing the enumeration with\ndiscovery removes the conflict class outright. Where that has been done, adding a\nmember no longer implies touching the shared file — so do not declare it as\nthough it does. Check the current state of the repository you are planning for\nrather than assuming either shape.\n\n### Phase 4 — Escalate and halt, if there are escalations\n\nAssign this invocation a local `harmonization_run_id`, and give each finding a\nstable id derived deterministically from its normalized class, its sorted\naffected ticket keys, and its seam or file identity — so the same contradiction\nkeeps the same id across runs and a resumed decision still applies.\n\nIf any finding is escalated, build **one consolidated decision page** using the\ninteraction established in `clarify-open-nfrs.md` — call `generate_decision_page`\nwith `artifact_type: \"pre_ticket_planning\"`, `ticket_key: {epic_slug}`,\n`output_subdir: \"epic-plans/{epic_slug}\"`, and\n`output_filename: \"{epic_slug}-harmonization-decisions.html\"`. Give each item its\ntaxonomy class, affected tickets, bounded conflicting evidence, options, and a\nrecommended resolution.\n\nBefore halting, atomically persist the validated manifest, the provisional report,\nand the decision-page reference. Then **halt without changing the sidecar or\nJira**. Stop and wait for the user; do not assume a resolution.\n\n**On resume**: read the manifest, re-fetch all tickets, re-evaluate the complete\nsibling set, apply the recorded decision, and continue from this phase. Do not\nrestart `plan-epic` — that risks recreating tickets or losing the key mapping. Do\nnot post a duplicate decision page or order comments.\n\n### Phase 5 — Stage the local bundle\n\nAdd the whole-epic ownership map to the input document as\n`touched_files_by_key` (real Jira key → its predicted files), then finalize:\n\n```bash\nnpx -y @bridge_gpt/mcp-server emit-epic-implementer-bundle finalize \\\n  --input <path to the input document> \\\n  --json\n```\n\nThis atomically writes, in one deterministic step:\n\n1. The finalized `{docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json` — the\n   validated node→key map applied across `nodes[].ticket_key`,\n   `nodes[].depends_on`, and `edges[].from`/`to`, with each node's normalized\n   `touched_files` attached and nothing else mutated. It rejects residual `TBD-`,\n   duplicate keys, unknown references, self-dependencies, cycles, and ordinary\n   edges that contradict the canonical `depends_on` graph.\n2. `{docs_dir}/epic-plans/{epic_slug}/sibling-ticket-manifest.json` — versioned\n   schema, epic identity, sidecar plan version, decomposition fingerprint, the\n   ordered mapping, run phase, decisions, and completed-mutation markers. It\n   records both the validated source-sidecar identity and the finalized-sidecar\n   identity, so a rerun can tell a legitimate finalized sidecar from a different\n   decomposition, and it excludes descriptions, credentials, exploration bodies,\n   and raw Jira responses.\n3. `{docs_dir}/epic-plans/{epic_slug}/epic-plan.meta.json` — the epic-key\n   identity `drive-epic` uses to find this plan.\n\nEvery write is a temp file in the destination directory followed by a rename, so\nan interrupted run cannot leave a partial recovery source. A non-zero exit halts\nthe task; relay its error verbatim.\n\nThen write the report artifacts:\n\n4. `{docs_dir}/epic-plans/{epic_slug}/harmonization-report.json` — versioned\n   schema, run metadata, and bounded findings.\n5. A run-scoped archive beside it\n   (`harmonization-report.{harmonization_run_id}.json`), **without replacing\n   earlier archives**. The fixed path holds only the latest run, so without the\n   archive one idempotent rerun would erase the only measurement of what this gate\n   ever caught.\n\n- **Preserve `plan_version`.** Do not bump it: these changes finalize version 1\n  *before* it is stored.\n- **Never set `base_lineage`.** It affects the plan hash but has no consumer in\n  the Epic Implementer, so setting it invalidates the approved hash for no gain.\n\n### Phase 6 — The dry-run gate\n\n```bash\nnpx -y @bridge_gpt/mcp-server setup-epic \\\n  --epic-key <epic_key> \\\n  --plan-file <docs_dir>/epic-plans/<epic_slug>/epic-plan.dag.json \\\n  --dry-run \\\n  --json\n```\n\n`validateEpicPlanSidecar()` is a pure local function over the parsed sidecar —\nplan version, key uniqueness, `touched_files`, acyclicity — with no Jira\ndependency. Running it first costs nothing and removes the partial-mutation\nfailure mode entirely.\n\n- **Any non-zero exit halts.** Relay the command's failure text verbatim; it is\n  already actionable.\n- **Any `touched_files` warning halts**, even on a successful exit. That warning\n  means a node's ownership is undeclared, which is the exact gap this task exists\n  to close: an undeclared node is never pre-serialized against an overlapping\n  sibling, so it relies entirely on reactive conflict detection at the merge gate.\n  Go back and declare it before proceeding.\n\n  This halt is **this task's own planning-quality bar, not a server rejection.**\n  Plan storage *accepts* an omitted `touched_files` as an explicit opt-out\n  (BAPI-722), so nothing downstream will stop you — which is precisely why the\n  standard has to be held here. A successful dry run reports\n  `undeclared_nodes` and `undeclared_pairs_skipped` next to `inserted_edges`\n  (BAPI-848); read those before treating a clean exit as coverage. (A *malformed* `touched_files` is different: the\n  server does reject that outright with `VALIDATION`.)\n- **Never fall back** to POSTing `/jira/epic-runs/runs` directly, storing the\n  plan, or approving it. A duplicate active run wedges the epic permanently.\n\nIf staging or the dry-run fails, leave Jira descriptions and attachments\nuntouched.\n\n### Phase 7 — Apply the external mutations\n\nOnly on a passing dry-run. Repeat the **Phase 1 run-state precheck immediately\nbefore the first Jira write**, and halt if it now shows approval, activation,\nblocking, plan storage, multiple runs, or an ambiguous state. On a resume,\nre-fetch all sibling tickets and re-evaluate the complete set before applying any\nrecorded decision.\n\n**Descriptions.** Compare each complete proposed description against the ticket's\ncurrent Jira description using the same normalization as\n`normalize_ticket_spec()`: collapse every run of whitespace to a single space and\ntrim, so cosmetic diffs never trigger a rewrite. A pure reflow or indentation\nedit is deliberately **not** a material change — the server treats it the same\nway, and diverging here would false-freeze tickets via `spec_stale`. Call\n`update_ticket_description` **only when the normalized descriptions differ\nmaterially**, and pass the **complete rendered description** — this is a full\nrewrite, not an append. Record each successful description mutation in the\nmanifest before moving to the next one, so a retry converges without duplicating\nwork.\n\n**Drafts and attachments.** Refresh the local draft with the reconciled complete\ndocument, then upload it with the `attachment` tool\n(`operation: \"upload\"`, `replace_existing: true`), which replaces any existing\nattachment of the same filename. Note it is delete-then-create rather than an\natomic revision, so the attachment id changes. If replacement is unavailable,\nmark the superseded local draft prominently and upload one deterministically named\nreconciled document instead. Skip the upload when an equivalent revision is\nalready present. **Do not add a Jira comment solely to refresh or supersede an\nattachment.** Record each draft/attachment mutation in the manifest so a retry\nskips completed equivalent work.\n\n**Finalize the reports.** After the required mutations converge, atomically\nrewrite the fixed and run-scoped reports with the actual mutation outcomes.\n\n### Updating one approved node's `ticket_spec` mid-run\n\nA specification larger than Jira's 32,767-character description cap does **not**\nhave to be cut down. An operator can store it on the approved plan node instead.\nNo CLI verb or MCP tool exposes this route, so this task never calls it by hand;\nreport the need to the user instead:\n\n```\nPATCH /jira/epic-runs/runs/<epic_run_id>/plan/nodes/<ticket_key>/ticket-spec\nbody: repo_name, expected_plan_hash, ticket_spec\n```\n\n- Bounded at **64,000 characters**, stored verbatim — never truncated. The\n  reconciler consults the plan node **first** when building a spec-review prompt,\n  so the reviewer sees the complete text on the next tick.\n- **Safe mid-run.** It changes only that node's `ticket_spec` (plus the plan hash),\n  and never the plan version, the approval pointers, or any `epic_ticket_status`\n  row. No ticket is re-seeded and no in-flight gate state is disturbed.\n- **`expected_plan_hash` is required** and must match the currently approved hash.\n  A stale hash on a real content change returns **409**; re-read the approved plan\n  and retry. Re-sending content that already matches is an idempotent no-op\n  (`updated: false`) and succeeds even with a stale hash, because nothing would be\n  overwritten.\n- This is **not** the same as re-storing the full plan at a new version and\n  re-approving it. That path re-seeds ticket rows and moves approval pointers, and\n  remains unsafe for casual mid-run spec edits.\n\n### Clean reruns\n\nA rerun over an already-harmonized epic is a **clean no-op**. It must not call\n`update_ticket_description`, upload a duplicate attachment, add a comment, alter\nplan semantics, bump `plan_version`, approve anything, or create status rows. It\nstill runs the final dry-run validation, still emits the fixed report (with an\nempty `findings` array), and still preserves every prior archive. It may rewrite\nidentical local JSON whose bytes differ only by normalization.\n\n### Never do these\n\n- Never create or seed `epic_ticket_status` rows, and never add a fallback\n  seeding path. Seeding is owned by `approve_epic_plan`, which seeds one\n  `planned` row per plan node idempotently before flipping the run to `active`.\n- Never approve a plan, activate a run, or POST to `/jira/epic-runs/runs`.\n- Never set `base_lineage`.\n- Never rewrite a description after the run reaches `active` — that trips\n  `spec_stale`.\n\n## Return\n\nReport:\n\n- The manifest path.\n- The fixed report path and the run-scoped archive path.\n- The ticket keys whose descriptions **changed**, and those left **unchanged**.\n- Attachment outcomes per ticket.\n- The dry-run result.\n- Exactly one status: **`ready_for_approval`** or **`decision_required`**.\n\nState explicitly that **approval remains a separate subsequent action** — this\ntask never approves the plan. On `ready_for_approval`, the operator's next\naction is `/drive-epic-run <epic_key>` (or `drive-epic <epic_key>` in Codex or\nCopilot), which asks for confirmation before it creates a run.\n",
@@ -783,12 +783,12 @@ export const INSTRUCTIONS = {
     "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\nIf there is nothing repository-specific to cite, say that no repository evidence was found and write a short conservative standard; do not invent files, commands, or conventions.\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\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``unit_testing_instructions`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** — not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about the project's unit testing setup (test runner, assertion library, mocking framework, run commands), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/unit_testing_instructions.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and — when it was\ncondensed — the reason it needed condensing.\n",
     "monitor-ci-checks.md": "Monitor CI checks for the most recent commit. The behavior is dispatched on the repo-specific `ci_followup_config` JSON value: `poll_only`, `fix_and_iterate`, or `custom`. Read this entire file once before doing anything, then follow only the matching branch.\n\n\n**Required-check source**: Both the `poll_only` (Step 5) and `fix_and_iterate` (Step 6) branches gate progression on the *required* check subset, not the aggregate `all_passed` flag. Each check returned by `resolve_ci_checks`/`poll_ci_checks` carries a `required` field (from GitHub Branch Protection, or an LLM classification fallback) — treat `required: false` as non-required (e.g. `pip-audit`) and a missing field or `required: true` as required. This is the tool-provided proxy for the Epic Implementer done-gate's authoritative required-checks set (`mcp_server/src/conductor/done-gate.ts`); do not re-derive required/non-required status in prose.\n\n## How to wait (BAPI-1104)\n\n**Never wait with a shell `sleep`, and never poll in an unbounded foreground loop.** The\nClaude Code harness refuses a foreground `sleep` outright, so an instruction to sleep does\nnot slow a worker down — it kills the step. Wait with `wait_for_ci_checks` instead.\n\n`wait_for_ci_checks` takes `commit_ref` (and an optional `budget_ms`, default and maximum\n240000). One call occupies at most 240 seconds — comfortably inside the MCP client\ndeadline — and returns a JSON body with a `state` field:\n\n- `state: \"pending\"` — NORMAL. Some check is still running and the window closed. Call the\n  tool again. This is the replacement for every \"wait N seconds and poll again\" instruction:\n  each repeated call is one bounded window, and repeating is how you wait for longer.\n- `state: \"ready\"` — every reported check is **terminal**. **Terminal is not passing.** This\n  tool never decides pass or fail; it reports each check's `name`, `required`, `status`,\n  `conclusion` and `complete`, and the branches below decide `required_green` from them.\n- `state: \"unavailable\"` — CI check configuration is not resolved for this repository, so\n  there is nothing to wait on. Do not keep calling. Call `resolve_ci_checks` for the current\n  SHA and retry once; if it is still unavailable, stop and report unavailable status through\n  the branch's existing unavailable-CI path.\n- `state: \"error\"` — terminal. Report the `reason` and stop waiting; further windows\n  reproduce it.\n\nEach returned window counts toward the branch's own wall-clock budget (`max_minutes` where\nthe branch has one). Track elapsed time across repeated windows and escalate through the\nbranch's existing exit when the budget is spent — the budget is enforced here, in the\nrecipe, not by the tool.\n\n## Entry state and ownership boundary\n\n**Re-resolve the git context before anything else.** Run `git branch --show-current`\nand `git rev-parse HEAD` when this step begins. In the implement pipeline the pull\nrequest is opened *before* the bounded post-finalization verification phase, and\nthat phase may have pushed a correction on top of the commit the PR was originally\nopened at. The head you monitor must be the branch's current pushed head, not a SHA\ncarried over from PR creation.\n\n**Ownership is split, and the split matters.** The bounded verification phase\n(`verify-plan.md`) owns findings produced by its own local, touched-area commands.\nThis step owns everything subsequently reported by the authoritative `ci` and\n`code_review` gates — failing required checks and requested review changes. Do not\nre-adjudicate the other phase's findings, and do not assume a finding it reported\nhas been fixed unless a pushed commit shows it.\n\n**Do not substitute a broad local run for the authoritative checks.** Running the\nfull local suite here does not establish that CI passed; it duplicates the work the\n`epic-implementer-ci / gate` check already performs on the pull request, and it is exactly the\nbudget sink this protocol was reordered to avoid. Use the structured CI failure\ndetail from `poll_ci_checks` to target a fix, and scope any local reproduction to\nthe failing area.\n\n**Keep every correction on the existing pull request branch**, and commit *and push*\neach correction before polling resumes. Polling always restarts against the new\npushed head — an unpushed correction is invisible to CI, to review, and to the\nreconciler.\n\nThroughout, report the check and review states you **observed**. Observing that a\ncheck is green is not the same as issuing a verdict: the done-gate evaluation is\nserver-side and the reconciler decides. This step never emits a control signal of\nits own.\n\n## Step 3 — Parse `ci_followup_config`\n\nLook at the response from the immediately preceding `config_field` call (the pipeline step that ran right before this one). The response envelope's `value` field is itself a JSON string and must be parsed again with `JSON.parse` (i.e., the `value` is double-encoded — the outer envelope is JSON, and the inner `value` is a JSON-encoded string of the actual config object).\n\nIf ANY of the following hold, log a warning and use the defaults `{\"strategy\":\"poll_only\",\"max_iterations\":1,\"max_minutes\":10}`:\n\n- The `config_field` response is missing or unavailable (e.g., the step warned-and-continued).\n- The response `value` is `null`.\n- Parsing `value` with `JSON.parse` fails (the persisted text is not valid JSON).\n- The parsed result is not a JSON object.\n- One or more of the required keys (`strategy`, `max_iterations`, `max_minutes`, `instructions`) is missing.\n- `strategy` is not one of `poll_only`, `fix_and_iterate`, or `custom`.\n\n## Step 4 — Dispatch on `strategy`\n\nRead this whole file once and then follow only the matching branch:\n\n- `poll_only` → follow Step 5.\n- `fix_and_iterate` → follow Step 6.\n- `custom` → follow Step 7.\n\nIf `strategy` is unrecognized, log a warning and fall through to Step 5 (`poll_only`).\n\n## Step 5 — `poll_only`\n\nPreserve the baseline polling behavior. The configured `max_minutes` is IGNORED in this branch — `poll_only` always uses the existing 10-minute baseline.\n\n1. Run `git rev-parse HEAD` to get the current commit SHA.\n2. Call the `resolve_ci_checks` tool with `commit_ref` set to that SHA. This discovers and classifies the CI checks for the repository, including each check's `required` field. It resolves the required-check **configuration** only and **never re-runs a workflow** — including with `force_rerun: true`, which bypasses the cache and nothing more.\n3. Poll CI status by calling `poll_ci_checks` with `commit_ref` set to the same SHA. Check the response for `all_complete`, and note each check's own `required`/green status — do not use the aggregate `all_passed` flag to decide pass/fail (see step 6 below).\n4. **Conflicting-head escalation**: if the poll shows zero check-runs for the current head after roughly two minutes of polling, call `gh pr view --json mergeable,mergeStateStatus` for the current branch's pull request. A `mergeable` value of `CONFLICTING` or a `mergeStateStatus` of `DIRTY` means GitHub will not start `pull_request` workflows for that head, so continuing to poll the same SHA is futile — dispatch to the Posture-Specific Conflict Handler (below) rather than merging, resolving, or pushing directly here; `poll_only` never merges, edits, commits, or pushes on its own authority. When the mergeability response is not `CONFLICTING`/`DIRTY`, zero checks alone is not a CI failure — continue with the ordinary wait behavior below.\n5. If checks are not yet complete, call `wait_for_ci_checks` with `commit_ref` set to the same SHA and repeat that call while it returns `state: \"pending\"`. Each call is one bounded 240-second window; repeat until it returns `state: \"ready\"` (every check terminal) or 10 minutes of accumulated windows have elapsed. On `state: \"unavailable\"` follow step 9 rather than continuing to wait.\n6. Compute `required_green` = every check with `required: true` (or a missing `required` field) is complete and green. If `required_green` is `true`, continue to review verdict gating (below) and then the Mergeability Gate (item 11) — `required_green` alone is not sufficient to report success. Non-required failures (e.g. `pip-audit` with `required: false`) are reported for visibility only and never flip the Passed/Failed classification.\n7. **Review verdict gating**: if `claude-review` is one of the required checks, its GitHub check reaching a non-pending/\"success\" state means only that the review action *ran* — this is transport completion, not approval. Fetch the PR's comments and confirm the sticky comment contains `claude-review-verdict: approved` on its own line with a `Reviewed-SHA:` line matching the current commit SHA before treating the review as approved; `claude-review-verdict: changes_requested`, a missing verdict, or a stale `Reviewed-SHA:` all mean the review is not yet approved and success is not yet reached. `docs/claude/claude-review-verdict-contract.md` is the authoritative definition of this grammar, of which comment wins when several carry a verdict, and of every fail-closed outcome; consult it rather than re-deriving the rules, and do not restate a different version of them here. A verdict can also be *temporarily* absent because a running review rewrote the sticky comment in place (the vanishing window, contract §7): while a `claude-review` run is still pending, treat absence as transient and keep polling; once it has completed, absence is final and fails closed. Once the verdict is confirmed approved (or `claude-review` is not required), continue to the Mergeability Gate (item 11) before reporting success.\n7a. **A `claude-review` failure blocked by the preflight is TERMINAL — never retry it.** When `claude-review` fails within about twelve seconds and no verdict comment was ever posted, read the run's `Preflight the review action` step. The review action refuses to run whenever this workflow differs from the repository's default-branch copy, and the preflight names which of the two causes it found:\n   - `status=workflow_modified` — the pull request's own commits changed `.github/workflows/claude-review.yml`. Such a pull request must be reviewed and merged by hand; it can never be merged by the Epic Implementer.\n   - `status=base_workflow_stale` — the pull request changed no workflow file and **inherited** a stale copy from its base branch. The stale ref is the **base branch**, not the pull request.\n\n   Both aggregate to `reason=review_action_blocked_by_workflow_modification`. In both cases the preflight is a deterministic blob-SHA comparison over unchanged inputs, so **retrying, re-running, or continuing to poll reproduces byte-identical evidence and can never succeed** — stop the retry loop and report it rather than spending the remaining budget. For the stale-base case the only remedy is to reconcile the base branch with the default branch; see `docs/claude/runbooks/claude-review-base-branch-drift.md` for detection, diagnosis, and both remediation paths.\n\n8. If any required checks fail, report which required checks failed (and any non-required failures for visibility) and include any available annotations or log details from the poll response. Do NOT attempt to fix failures — just report them clearly.\n9. If CI status is unavailable (`wait_for_ci_checks` returns `state: \"unavailable\"`, or the resolver/poll returns `available: false`), call `resolve_ci_checks` once for the current SHA and retry the wait; if it is still unavailable, report unavailable status and exit. Do not attempt fixes and do not keep waiting. Note that this call re-resolves the required-check **configuration** and actuates no CI run, so it cannot make a missing run appear.\n10. If the 10-minute timeout is reached, report timeout and exit.\n11. **Mergeability Gate — final ready-decision.** Reached only after `required_green` is true and, when `claude-review` is required, its verdict is confirmed approved for the current head. Run the shared Mergeability Gate described below under \"Mergeability Gate (Shared, Final Ready-Decision)\".\n    - If the gate reports the current head is not a confirmed conflict (including a recognized non-conflicting state such as `BLOCKED` or `BEHIND`), report success — a green PR with a recognized non-conflicting result continues without a prompt or a conflict report.\n    - If the gate reports a confirmed conflict (`mergeable == \"CONFLICTING\"` or `mergeStateStatus == \"DIRTY\"`), dispatch to the Posture-Specific Conflict Handler (below), which routes `poll_only` to Attended Investigation and Approval; `poll_only` never merges, edits, commits, or pushes on its own authority. Report `awaiting conflict-resolution approval` while a proposal is pending, or `blocked: unresolved conflict` / `blocked: full-suite failure after resolution` if the attended flow reaches one of those blocked outcomes.\n    - If the gate reports mergeability could not be confirmed after its own additional read, report `mergeability could not be confirmed` and exit — this is not an ordinary CI failure.\n    - This gate runs once, at this final ready-decision point — never on every poll.\n\n### Polling Directive\n\nWait only through repeated `wait_for_ci_checks` calls — never a shell `sleep`, and never an\nunbounded foreground poll. Do NOT output any inline commentary, reasoning, or partial status\nupdates between windows. Only output a status message when:\n- All checks are terminal (`state: \"ready\"`), OR\n- CI is unavailable or the wait returns a terminal error, OR\n- The 10-minute accumulated budget is reached.\n\nThis minimizes context window consumption during long-running CI waits.\n\n## Step 6 — `fix_and_iterate`\n\nThis is a self-contained loop where `iteration` is the number of correction rounds already pushed and `start_time` is captured before the first iteration. `max_minutes` is the TOTAL wall-clock cap across all iterations, not an additional per-iteration budget. The 10-minute per-iteration CI-wait cap is INSIDE that total budget, and it is counted from the accumulated `wait_for_ci_checks` windows this iteration has already spent.\n\nInitialize:\n\n- `iteration = 0`\n- `start_time = now()`\n\nBefore starting each iteration AND before applying corrections, check the total wall-clock budget. If `now() - start_time >= max_minutes`, warn and exit.\n\nPer iteration:\n\n1. Run `git rev-parse HEAD` to get the current commit SHA. The previous push may have changed it; always read fresh.\n2. Run `git branch --show-current` to get the current branch. Always read fresh.\n3. Call `resolve_ci_checks` with `commit_ref` set to the current SHA (once per new SHA — the server caches per project but the agent should still call it for each new SHA). Each returned check carries a `required` field — this is the tool-provided proxy for the done-gate's authoritative required-checks set. The call resolves **configuration** only and re-runs nothing; to re-run a failed lane by hand use `gh run rerun --failed <run_id> --repo <owner/repo>`.\n4. Wait for terminality by calling `wait_for_ci_checks` with `commit_ref` set to the current SHA, repeating while it returns `state: \"pending\"`. Each call is one bounded 240-second window and every window counts against both budgets below. Stop when it returns `state: \"ready\"` (every check terminal), OR `state: \"unavailable\"` (go to step 6), OR `state: \"error\"`, OR the per-iteration 10-minute accumulated cap is reached, OR the remaining total wall-clock budget is exhausted. Use `poll_ci_checks` for the failure detail of a terminal check; it is the detail source, not the waiting mechanism.\n5. **Conflicting-head escalation**: if the poll shows zero check-runs for the current head after roughly two minutes of polling, call `gh pr view --json mergeable,mergeStateStatus` for the current branch's pull request. A `mergeable` value of `CONFLICTING` or a `mergeStateStatus` of `DIRTY` means GitHub will not start `pull_request` workflows for that head, so continuing to poll the same SHA is futile — dispatch to the Posture-Specific Conflict Handler (below), which resolves the conflict autonomously through the Autonomous Verified Merge Resolution path and restarts polling from step 1 of this per-iteration block against the new head SHA once it pushes. When the mergeability response is not `CONFLICTING`/`DIRTY`, zero checks alone is not a CI failure — continue with the ordinary per-iteration behavior below.\n6. If CI status is unavailable (`wait_for_ci_checks` returns `state: \"unavailable\"`, or `poll_ci_checks` returns `available: false`), call `resolve_ci_checks` once for the current SHA and retry the wait. If it is still unavailable, warn and exit the loop — automated remediation cannot make reliable progress without CI signals, and further waiting cannot produce one. `resolve_ci_checks` re-resolves the required-check **configuration** and never actuates a run, so repeating it cannot create the missing signal.\n7. Compute `required_green` = every check with `required: true` (or a missing `required` field) is complete and green; non-required failures (e.g. `pip-audit` with `required: false`) are reported for visibility but never gate exit condition 1 below. If `claude-review` is a required check, its GitHub check reaching a non-pending/\"success\" state is transport completion only, not approval — fetch the PR's comments and confirm the sticky comment contains `claude-review-verdict: approved` on its own line with a `Reviewed-SHA:` line matching the current commit SHA before treating the review as approved; `claude-review-verdict: changes_requested`, a missing verdict, or a stale `Reviewed-SHA:` mean the review is not yet approved. `docs/claude/claude-review-verdict-contract.md` is the authoritative definition of this grammar, of which comment wins when several carry a verdict, and of every fail-closed outcome; consult it rather than re-deriving the rules, and do not restate a different version of them here. A verdict can also be *temporarily* absent because a running review rewrote the sticky comment in place (the vanishing window, contract §7): while a `claude-review` run is still pending, treat absence as transient and keep polling; once it has completed, absence is final and fails closed.\n7a. **A `claude-review` failure blocked by the preflight is TERMINAL — never spend a correction or a retry on it.** When `claude-review` fails within about twelve seconds and no verdict comment was ever posted, read the run's `Preflight the review action` step. The review action refuses to run whenever this workflow differs from the repository's default-branch copy, and the preflight names which of the two causes it found:\n   - `status=workflow_modified` — the pull request's own commits changed `.github/workflows/claude-review.yml`. It must be reviewed and merged by hand; it can never be merged by the Epic Implementer.\n   - `status=base_workflow_stale` — the pull request changed no workflow file and **inherited** a stale copy from its base branch. The stale ref is the **base branch**, not the pull request, so no correction you can make on this branch will clear it.\n\n   Both aggregate to `reason=review_action_blocked_by_workflow_modification`, and the preflight is a deterministic blob-SHA comparison over unchanged inputs — every iteration reproduces byte-identical evidence. Treat it as non-actionable, exit the loop with that reason reported, and do not consume the remaining iteration or wall-clock budget. Remedy for the stale-base case: reconcile the base branch with the default branch. See `docs/claude/runbooks/claude-review-base-branch-drift.md`.\n\n   Once `required_green` is true and (if required) the review verdict is confirmed approved, continue to the Mergeability Gate inside exit condition 1 below before returning success.\n\n8. Apply repo-specific `instructions` ONLY when the `instructions` field is non-empty. If the repo `instructions` reference templated placeholder tokens for the GitHub owner, repo, or PR number — e.g., the literal tokens written as a left brace, the word `owner`/`repo`/`pr`, then a right brace — resolve them from the local git/VCS context. Use `gh pr list --head <branch> --json number` to get the PR number; parse the remote URL (`git config --get remote.origin.url`) for owner/repo. If `instructions` is empty, skip repo-specific signal gathering and use only structured CI failure information.\n\n9. Evaluate exit conditions in this order:\n   1. `required_green` is true AND (if `claude-review` is required) the verdict token confirms approval for the current head AND any repo-specific exit criteria from `instructions` are met AND the Mergeability Gate (described below under \"Mergeability Gate (Shared, Final Ready-Decision)\") confirms the current head is not a confirmed conflict → success. If there are no repo-specific exit criteria, `required_green` (plus verdict-token approval when `claude-review` is required, plus the Mergeability Gate) alone satisfies the success condition. A confirmed conflict from the gate does not exit the loop — it routes to the Autonomous Verified Merge Resolution path (below), which may push a new head. Any newly pushed head, whether from an ordinary correction or from conflict resolution, must re-enter CI/review monitoring at step 1 of this per-iteration block and receive its own final Mergeability Gate evaluation before success. If the gate instead reports mergeability could not be confirmed, that outcome is terminal for this gate invocation, exactly as the gate itself states — do **not** loop back to per-iteration step 1 hoping a repeat read resolves it: every check is already terminal, so `wait_for_ci_checks` would return instantly and `iteration` cannot advance without a commit to push, meaning nothing about looping changes an already-exhausted read. Report `mergeability could not be confirmed` and stop this loop now.\n   2. `iteration >= max_iterations` → warn and exit (iteration cap reached).\n   3. Total elapsed wall-clock time `>= max_minutes` → warn and exit (total wall-clock cap reached).\n   4. After attempting corrections, `git status --porcelain` is empty → warn and exit (nothing to commit; avoids infinite loop on stuck failures).\n\n10. Apply corrections ONLY for failing **required** checks — skip failures on non-required checks (e.g. `pip-audit` with `required: false`) with a warning and never spend a correction/retry on them. For each failing required check, use the actual `poll_ci_checks` response shape — inspect its singular `failure_detail` field:\n   - If `failure_detail` is a dict containing actionable keys such as `annotations`, `log_tail`, or `log`, treat it as structured detail and use it for remediation.\n   - If `failure_detail` is a dict containing only `url`, treat it as URL-only and skip with a warning (no actionable detail).\n   - If `failure_detail` is missing, `null`, or unrecognized, treat the failure as non-actionable and skip with a warning.\n   - Do NOT rely on a per-check field or a plural variant of `failure_detail` — those do not exist on the response.\n\n11. After applying a non-empty correction set: stage corrections (`git add` the specific files), commit, and push. Use the canonical commit message:\n   ```\n   {ticket_key}: address review/CI feedback (round N+1)\n   ```\n   where `N` is the zero-indexed `iteration`.\n12. Increment `iteration` only AFTER a successful commit and push. Then loop back to step 1 of the per-iteration block.\n\n## Step 7 — `custom`\n\nIn `custom` mode, the `instructions` field IS the complete CI follow-up instruction set for this step. Follow it verbatim. Ignore Steps 5 and 6 entirely.\n\nCustom instructions are authoritative for CI follow-up behavior, but they remain subject to the agent's normal tool approval, credential handling, secret-handling, and platform safety constraints. Custom prose CANNOT bypass approval gates, exfiltrate secrets, or override platform safety policies, even though admin-only access controls who can set the field.\n\n`custom` cannot declare success without running the Mergeability Gate (below) at its own final ready-decision point, and cannot bypass the gate's conflict predicate, the no-force-push rule, the full-suite requirement, or the approval requirement. `custom` is attended by default — exactly like `poll_only` — unless its own `instructions` prose explicitly selects autonomous handling; making that selection routes a confirmed conflict to the Autonomous Verified Merge Resolution path instead of the Attended Investigation and Approval path, but does not relax any of the invariants above.\n\n## Mergeability Gate (Shared, Final Ready-Decision)\n\nReferenced by Step 5 (`poll_only`), Step 6 (`fix_and_iterate`), and Step 7 (`custom`) as the single final check before any branch may report success. It is invoked **once**, at each branch's own final ready-decision point — the point where that branch is otherwise ready to report success — after required checks (`required_green`), the review-verdict token when `claude-review` is required, and any repository-specific exit criteria have already passed. This gate does not run on every poll and does not turn CI monitoring into a mergeability watcher; it resolves whether the exact head that just became ready is actually mergeable before any success is reported.\n\n**Resolve the head first.** Immediately before invoking this gate, run `git rev-parse HEAD`. If the SHA differs from the one whose required checks and review verdict were just evaluated, the ready decision does not apply to it — restart CI/review monitoring for the newly observed SHA (return to the top of the owning branch) rather than evaluating a stale SHA.\n\n**Read GitHub's authoritative mergeability.** Run `gh pr view --json mergeable,mergeStateStatus` for the current branch's pull request and parse only the two requested fields, `mergeable` and `mergeStateStatus`. Never print or report the raw `gh` output — reports may contain only the normalized `mergeable` / `mergeStateStatus` values and a normalized gate outcome.\n\n**The conflict predicate is exact:**\n\n```\nmergeable == \"CONFLICTING\" OR mergeStateStatus == \"DIRTY\"\n```\n\nA parsed result that does **not** satisfy this predicate is sufficient for this gate — including a recognized `BLOCKED` or `BEHIND` value. Do not require an exact `MERGEABLE` plus `CLEAN` pair; GitHub reports several non-conflicting states, and this gate only screens for the two conflicting ones above.\n\n**Fail closed on ambiguity.** `null`, `UNKNOWN`, a malformed response, an unrecognized value, or an unreadable/failed `gh pr view` call are all **\"mergeability not confirmed\"** — never treated as ready. On an ambiguous or failed read, re-read `gh pr view --json mergeable,mergeStateStatus` exactly one more time before giving up. `wait_for_ci_checks` is **not** a pause here and must not be used as one: it blocks only while some CI check is still non-terminal, and by the time this gate runs every check is already terminal by construction, so it would return on its very first round-trip and add no actual delay. No mechanism available to this instruction produces a genuine timed pause at this point, and a shell `sleep` is refused outright by the harness — never reach for one, and never spin in a tight foreground retry loop hoping the value changes on its own. Treat the second read as an independent observation, not a timed retry: `mergeable: null` is GitHub's own transient background-computation state, and a fresh API call sometimes catches it resolved even without an artificial wait. If the second read is still ambiguous, report **`mergeability could not be confirmed`** and stop — this is a terminal outcome for this gate invocation, not a condition to keep looping on. Never let an exception from a failed `gh` call escape this gate uncaught.\n\n**Outcome:**\n\n- **Not a confirmed conflict** (including recognized `BLOCKED` / `BEHIND` states) → the gate is satisfied. A green PR with a recognized non-conflicting result continues without a prompt or a conflict report.\n- **Confirmed conflict** (`mergeable == \"CONFLICTING\"` or `mergeStateStatus == \"DIRTY\"`) → dispatch to the Posture-Specific Conflict Handler below.\n- **Mergeability not confirmed** after the one bounded re-read → report `mergeability could not be confirmed` and stop.\n\n### Posture-Specific Conflict Handler\n\nA confirmed conflict is dispatched by the current `ci_followup_config.strategy` — never by any additional flag, environment variable, or configuration field:\n\n- **`fix_and_iterate`** is the autonomous posture: it resolves a confirmed conflict itself, through the Autonomous Verified Merge Resolution path below, without asking.\n- **`poll_only`** is the attended posture: it cannot mutate any conflict-resolution state before explicit human approval, through the Attended Investigation and Approval path below.\n- **`custom`** is attended by default — the same as `poll_only` — unless the repository's own `instructions` prose explicitly selects autonomous handling. Custom prose can change *how* a conflict is investigated or resolved, but it cannot bypass this gate, the no-force-push rule, the full-suite requirement, the approval requirement (when attended), credential handling, or platform-safety constraints. `custom` cannot report success without this gate.\n\n**Base resolution.** Both paths resolve `<base>` through this precedence, taking the first tier with a usable value:\n\n1. Non-empty `BAPI_BASE_BRANCH` from the environment.\n2. A PR base the user supplied at the commit step, when that value is still available in this session.\n3. `gh pr view --json baseRefName -q .baseRefName` — the durable fallback for the user-supplied-base tier when same-session memory of it is unavailable.\n4. `config_field` with `operation: \"get\"` and `field_name: \"base_branch\"`.\n5. `main`.\n\nRun `git fetch` before inspecting or integrating the selected base. Record the current head SHA and the fetched `origin/<base>` SHA as the specific pair being investigated or resolved — every report below is scoped to that exact pair.\n\n#### Attended Investigation and Approval (`poll_only`, attended `custom`)\n\nRuns after `git fetch` and base resolution above. From this point the investigation is strictly read-only — nothing here may touch the worktree, the index, `HEAD`, a ref, or the remote.\n\n1. Compute the merge base between `HEAD` and `origin/<base>`.\n2. Run `git merge-tree --write-tree -z --name-only --messages HEAD origin/<base>` (current head first, fetched base second). `git merge-tree` performs the investigation entirely in the object database — it does not authorize any worktree, index, `HEAD`, ref, commit-history, or remote mutation.\n3. Classify the result as clean, conflicted, or operationally unavailable, and list the conflicting files.\n4. Run `git log --oneline <merge-base>..origin/<base>` to summarize the commits that advanced the base.\n5. Write a concise prose proposal describing how each conflict or conflict group should be resolved.\n6. Report the investigated head SHA, the fetched base SHA, the conflicting-file classification, the base delta, and the proposed resolution — **before** asking for approval.\n\nA locally clean `git merge-tree` result does **not** override GitHub's authoritative `CONFLICTING` or `DIRTY` result. Report that discrepancy as-is, without mutating anything.\n\nIf `git fetch`, the merge-base calculation, or `git merge-tree` fails, report which component was unavailable and whatever context is safely known, and stop — do not fall through into any mutation.\n\n**Approval.** Require explicit human approval for that exact head SHA, base SHA, and proposal before any merge, conflict edit, commit, or push. A pending approval request is a **resumable state**, exempt from the branch's existing ten-minute CI-poll baseline — report it as `awaiting conflict-resolution approval` and stop, rather than counting the wait as CI-poll time.\n\nOn resumption, re-read `HEAD`, re-fetch the base, and re-run this gate's authoritative mergeability read — never assume the previously approved state is still current. If either the head or the base SHA changed before the approved resolution was pushed, the approval is **invalidated**: run a fresh investigation-and-approval cycle before proceeding.\n\nAn approved, still-current proposal is routed into the same Autonomous Verified Merge Resolution path used by `fix_and_iterate`, below.\n\n#### Autonomous Verified Merge Resolution (`fix_and_iterate`, approved attended proposals)\n\n1. Run `git status --porcelain` immediately before merging. Require a clean worktree before `git merge origin/<base>`; if the worktree is not clean, preserve the owned changes through the repository's established safe stash workflow, or escalate without discarding them.\n2. Merge in the worker's own worktree with `git merge origin/<base>`. **Never** `git rebase`, a force-push option, or any equivalent history rewrite.\n3. Resolve the merge semantically — read the conflicting hunks and confirm the resolved code is behaviorally correct, not just that the textual markers are gone.\n4. After resolving conflicts, check for an unresolved index and run `git diff --check`. Residual conflict markers or unresolved index entries are an **incomplete resolution** — escalate without pushing.\n5. Run the full local test suite: every unit test suite the project defines — the same suites its pull-request CI runs — and never a targeted subset alone. This is the same definition of \"the full suite\" that the resume-mode remediation precedent (`buildResumeModeRemediationFinalizeInstruction` in `mcp_server/src/start-tickets.ts`) uses. Run it after the merge resolves and **before** any resolution push.\n6. If the merge cannot be resolved, or the full-suite gate is not green, report a **blocked** outcome (`blocked: unresolved conflict` or `blocked: full-suite failure after resolution`) and do **not** push.\n7. Only after the full-suite gate succeeds: commit and push the resolved merge normally. Increment the owning branch's `iteration` counter (Step 6) only after both the commit and the push succeed.\n8. Run `git rev-parse HEAD` after the push and restart CI resolution and waiting against that new SHA. The new head must become required-green, satisfy any review/repository criteria, and pass this Mergeability Gate again before success.\n9. Repeated conflicts and resolution attempts are bound by the owning branch's existing `max_iterations` and `max_minutes` limits. Escalate — do not spin — when a conflict repeats, a budget expires, or no safe resolution can be produced.\n\n## Worker finalization — clean session exit (Epic Implementer auto mode)\n\nThis section applies ONLY when you were launched under the Epic Implementer in auto mode (the `BAPI_EPIC_IMPLEMENTER_RUN_ID`/`BAPI_EPIC_IMPLEMENTER_WORKER_ID` env identifiers are present). Only the `start-tickets --conductor` launch sets them; the v2 executor keeps every `BAPI_EPIC_IMPLEMENTER_*` identity key out of its workers' environment, so a v2 worker does not see them. Any other worker ignores this section entirely.\n\nBefore doing anything here, distinguish two states:\n\n- **CI/review follow-up still owned by this worker** — the `fix_and_iterate` loop is still correcting failures, review changes were requested and are unaddressed, a merge conflict on your PR is unresolved, the Mergeability Gate's Autonomous Verified Merge Resolution reported `blocked: unresolved conflict` or `blocked: full-suite failure after resolution`, an attended conflict-resolution proposal is `awaiting conflict-resolution approval`, or you have unpushed local commits. In this state you are **not** finished: keep working the CI-monitoring / correction loop and do **not** exit.\n- **Final PR state reached; no further worker action pending** — your final branch state is pushed, the PR has been created/updated, the done-gate / CI-monitoring workflow required by the recipe has completed (required checks green and, when `claude-review` is required, the verdict token confirms approval for the current head), the Mergeability Gate confirms the current head is not a confirmed conflict, and no CI/review follow-up remains that you own.\n\nOnly in the second state — that is, **only after the final push, PR creation/update, done-gate confirmation, CI/review monitoring, and the Mergeability Gate have all completed** and no follow-up remains — cleanly end your worker session (for example by issuing the `/exit` command) so the worktree is released and no idle process lingers. Do **not** exit immediately after opening a PR while CI or review is still pending, and do not exit while there are unresolved CI failures, requested review changes, a merge conflict you own, a blocked or pending mergeability-gate conflict resolution, or unpushed local commits. A clean `SessionEnd` is both the correct terminal lifecycle signal (the Epic Implementer folds it) and the point at which the worker should exit.\n\n## Return\n\nReport one of: **passed**, **failed** (list the failing checks with their failure summaries), **timed out**, **unavailable**, **`mergeability could not be confirmed`** (the Mergeability Gate's read stayed ambiguous or unavailable after its one additional read — terminal for this gate invocation, not a condition the loop kept retrying), **`blocked: unresolved conflict`** (the Autonomous Verified Merge Resolution path could not produce a safe, complete merge), **`blocked: full-suite failure after resolution`** (the merge resolved but the full test suite did not pass), or the resumable **`awaiting conflict-resolution approval`** (an attended investigation produced a proposal for a specific head/base pair that is still pending explicit approval — report the approved-scope candidate; this wait does not count as CI-poll time). Blocked and uncertain outcomes report only normalized context — never raw `gh` output. For `fix_and_iterate`, also report the iteration count and whether iteration/wall-clock caps were hit. If you finalized (cleanly exited) as an Epic Implementer worker, note that the session ended after all follow-up completed.\n\nNo post-green watcher is introduced by this gate: it runs once, at each branch's own final ready-decision point, for the head that was actually evaluated. A conflict that first appears after this monitoring loop has already exited is outside this mechanism entirely — it is owned by the epic-implementer reconciler's own authoritative, uncached mergeability check performed at merge/completion admission.\n",
     "preflight-and-readiness.md": "Initialize the idea-to-ticket run directory and classify the idea's readiness and scope.\n\n## Inputs\n\n- Idea: `{idea}`\n- Slug: `{slug}`\n- Run ID: `{run_id}`\n- Docs directory: `{docs_dir}`\n- Project standards: response from the immediately preceding `get_project_standards` step. If that step returned an error envelope or a 404, treat the project standards as unavailable and proceed; do not halt.\n\n## Callers\n\nTwo callers use this procedure. Everything below is the **recipe path** and applies unchanged when the `idea-to-ticket` recipe runs it.\n\n**Define-tickets path.** When `/define-tickets --auto` runs this procedure, the command names the artifact directory and a unique local run id in its invocation. Use that directory in place of the recipe run directory, and write the readiness artifact there. Do not write `run-manifest.json`, do not compute or look up any label, and do not query Jira. Classify readiness and scope exactly as below and report both axes to the command. Scope is recorded only; it does not choose the eventual ticket shape. A `too_vague_to_ticket` result is reported to the command, which halts before it explores the codebase.\n\n## Instructions\n\n1. Create the run directory:\n   ```\n   mkdir -p {docs_dir}/idea-to-ticket/{slug}-{run_id}\n   ```\n   Every artifact produced by this pipeline run lives under this run directory. No Jira mutation may occur in any later step until `run-manifest.json` has been written to this directory.\n\n2. Classify the idea on two independent axes:\n\n   **Readiness** (one of):\n   - `ready_to_draft` — the idea is concrete enough that a clear ticket draft can be produced.\n   - `needs_clarification` — the idea is reasonable but missing key answers; clarifying questions must be raised in `open-questions.md` later.\n   - `research_first` — drafting is blocked on external/codebase research; deep or narrow research must come first.\n   - `too_vague_to_ticket` — the idea is not actionable yet; do not produce a ticket.\n\n   **Scope** (one of):\n   - `task` — a single Jira Task (default when ambiguous).\n   - `spike` — a single Jira Spike. Resolve `spike` only on the objective\n     condition that the idea has **no committed production-code deliverable** —\n     the same trigger as exception E2 in `docs/bridge-ticket-authoring.md`. This\n     is a deliverable that is absent, not a judgement about whether the work\n     feels investigative. **Any uncertainty resolves to `task`.** This decision\n     is made HERE and only here: the `scope` you write into the manifest is what\n     selects the spike ticket format downstream, and `jira-ticket-writer` is\n     explicitly forbidden from deciding it for itself.\n   - `epic_candidate` — the idea decomposes into a Jira Epic plus multiple child tickets.\n\n3. Halt locally if readiness is `too_vague_to_ticket`. Write the manifest anyway (see step 4) so the local artifacts record the halt; then stop without continuing the rest of the pipeline. Do not attempt any Jira mutation.\n\n4. Write `run-manifest.json` to `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`. Required fields:\n   - `idea` — the original `{idea}` text.\n   - `slug` — `{slug}`.\n   - `run_id` — `{run_id}`.\n   - `run_dir` — `{docs_dir}/idea-to-ticket/{slug}-{run_id}/`.\n   - `readiness` — one of the four readiness values above.\n   - `scope` — one of the three scope values above.\n   - `project_standards_available` — `true` if `get_project_standards` returned a usable result, `false` otherwise.\n   - `idempotency_label` — `bapi-idea-to-ticket-{run_id}` (per-run label; lets downstream steps resume THIS run by label).\n   - `stable_label` — `bapi-idea-hash-{idea_hash}` (stable across runs of the same idea; lets the duplicate-detection step catch a PRIOR run of the same idea by label, not just fuzzy text).\n   - `created_at` — ISO 8601 timestamp.\n\n5. The manifest is the resumability artifact for the whole run. Do not include secrets or raw credentials. Keep the file under a few KB.\n\n## Return\n\nConfirm the run directory and `run-manifest.json` were created, and report the classified `readiness` and `scope`. If readiness is `too_vague_to_ticket`, also report that the pipeline must stop without Jira mutation.\n",
-    "render-ticket-manifest.md": "Render every entry of an approved ticket manifest into a drafted body, one `jira-ticket-writer` invocation per entry, without re-deciding the split.\n\nThis stage sits between **decomposition** (which decided the split once and froze\nit) and **creation** (`upload-epic-hierarchy.md` for an epic, ordinary\n`create_ticket` calls for siblings). It owns exactly one job: turning frozen\nmanifest entries into drafted bodies. It decides nothing.\n\n## Inputs\n\n- **The approved manifest** — the ordered plan the decomposition pass froze.\n  On the `idea-to-ticket` path this is `decomposition-plan.json` in the run\n  directory, produced by `decompose-epic-candidate.md`. On the `plan-epic` path\n  it is the sub-task list in `epic-plan.md`, produced by `decompose-epic.md`. On\n  a client-driven path (`/define-tickets` Stage 9) it is the approved outline\n  shown at the gate.\n- **For an epic, the frozen manifest JSON and its coherence record.** The\n  record `epic-coherence.json` and its input `epic-coherence-input.json` sit in\n  the same directory as the frozen manifest JSON: the run directory beside\n  `decomposition-plan.json` on the `idea-to-ticket` path, and the epic plan\n  directory beside `epic-manifest.json` on the `plan-epic` and\n  `/define-tickets` paths. Take the normalized `manifest` array, the current\n  `child_evidence` array, and the `non_child_owners` array (absent when the\n  epic has none) from the caller's frozen JSON artifacts — the same\n  normalization the caller used to build `epic-coherence-input.json`.\n- **The approval state** for that manifest. Whether approval is an explicit\n  affirmative or a pipeline auto-approval variable is the calling surface's own\n  rule; this stage only needs to know it resolved.\n- **The research and framing artifacts** each entry's writer invocation needs —\n  the same set the standalone drafting path passes.\n\n## Preflight — fail closed, before any body is rendered\n\nCheck all of the following first. Each one is a **hard failure** that stops the\nflow before a single writer invocation and long before any Jira mutation. None\nof them degrades to a partial run:\n\n1. **Approval unresolved.** The manifest's approval gate has not resolved, or\n   resolved as declined. Nothing renders and nothing is created.\n2. **Manifest identity changed.** The manifest presented here is not the one that\n   was approved — a different entry count, different ordering, renumbered\n   entries, or an altered scope boundary. A substituted split never silently\n   replaces the approved one.\n3. **An entry past the size ceiling.** An entry whose stated scope runs beyond\n   roughly 40 files or ~3000 LOC is over the bound wherever it sits — a\n   standalone ticket and an epic child alike. Fail and name the entry; do not\n   draft it, do not split it here, and do not shrink its stated scope to fit. An\n   `XL` entry below that ceiling is not a violation and needs no supporting\n   evidence: `XL` is the preferred shape for work that does not fit in `L`.\n4. **An entry with no writer draft after rendering.** Every entry must have\n   produced a body. A missing draft is a failure, not an entry to skip.\n5. **Epic coherence not cleared (epic manifests only).** An epic manifest renders\n   only when all of the following hold. Check them before any writer invocation\n   and before any Jira mutation:\n   - `epic-coherence.json`, written by `review-epic-coherence.md`, exists beside\n     the manifest (in the same directory) and is readable, well-formed JSON.\n   - Its `schema_version` is a recognized value: `1`, `2`, or `3`. Legacy blocking findings are foundation findings. For version 3, validate scope, child ownership, carry completeness, confirmation budget, and foundation-based clearance before rendering. Any other value\n     fails.\n   - Its top-level `manifest_sha256` matches the manifest being rendered, its\n     `child_evidence_sha256` matches the child evidence being rendered, **and**\n     its `non_child_owners_sha256` matches the non-child owners being rendered.\n     Compute all three with the canonical JSON encoding\n     `review-epic-coherence.md` specifies, over the normalized `manifest` array,\n     the `child_evidence` array, and the `non_child_owners` array (an absent\n     array hashes as an empty array) — never over a whole file's bytes. A\n     version `1` record has no `non_child_owners_sha256`. Treat that absent\n     digest as the empty-array digest **only when** the input being rendered has\n     no `non_child_owners`; otherwise it is a mismatch.\n   - Its `rounds` array is non-empty, and its last round carries\n     `manifest_sha256` and `child_evidence_sha256` — for version `1` too. A\n     version `2` last round also carries `non_child_owners_sha256`. The\n     top-level digests **equal the last round's digests**. A version `1` record\n     is read as having no confirmation rounds. A record whose top-level digests\n     no reviewer round saw is a hard failure: that is the BAPI-1316 case, where\n     the manifest was amended after the final round.\n   - The **only** exception to last-round equality is an **attended** record\n     with `amended_after_final_round: true`, an override of kind `bypass` with a\n     non-empty typed reason, and verdict `not_checked`. Its top-level digests\n     must still match the input being rendered. An unattended run never accepts\n     this exception.\n   - Its `verdict` is `pass`, including a version 3 record with carried ticket-local blockers; or\n     `accepted_with_gaps`, with an override of kind `accept` and a non-empty reason for every\n     remaining foundation blocking finding; or\n     `not_checked`, with a recorded override of kind `bypass` carrying a\n     non-empty reason (the attended bypass of an unavailable reviewer).\n   - **No unresolved required council.** A required council whose outcome is\n     `still_running`, `failed`, or `timed_out` fails the check unless an\n     attended override of kind `accept` with a non-empty reason names that\n     council's `council_id`. This applies to every council the record lists,\n     including a second one in `councils`. A council outcome of\n     `declined_by_operator` is unresolved too. It clears only through an\n     attended override of kind `accept` with the exact target\n     `council: \"declined_by_operator\"` and a non-empty reason, typed by the\n     operator or drafted by the agent and shown at the create gate where that\n     gate applies. A `finding_id` accept never clears it, and its null\n     `council_id` is never a substitute target. The displayed reason and target\n     must be unchanged between approval and creation; otherwise show the\n     approval gate again.\n   - **Unattended runs** (`auto_approve_external` is the literal `\"true\"`) need\n     independent clearance. A record with `independent: false` fails even when\n     its verdict is `pass`. An attended-only bypass never clears an unattended\n     run, so an unattended `not_checked` fails.\n   - Unknown record fields, such as a historical `council_note`, are ignored.\n     They are never treated as an authorization.\n\n   A missing record, an unreadable or malformed record, an unrecognized\n   `schema_version`, a digest mismatch, top-level digests that differ from the\n   last round's, an unresolved required council, a `blocked` verdict, and an\n   un-bypassed `not_checked` are all hard failures.\n   **A siblings manifest skips this check entirely**: siblings get no coherence\n   review and need no record. Item 2's identity check is separate and unchanged.\n   A changed manifest identity fails item 2 whatever the coherence record says.\n\nFail-open applies **only** to enrichment and context gathering — an optional\nresearch artifact that is missing may degrade the context a body is written\nfrom. Approval, manifest identity, sizing validity, writer-output completeness,\nand epic coherence all fail closed. The coherence record is **not** an\nenrichment artifact: a missing or failing record never degrades to a partial or\nfail-open run.\n\n## Instructions\n\n1. Read the approved manifest in full. Record its entry count, its order, and\n   each entry's identity, so the identity check above has something to compare\n   against.\n\n2. **Fan out one `jira-ticket-writer` invocation per entry**, in manifest order —\n   the epic parent, then each child; or each ordinary sibling. Each invocation\n   is bound to exactly one entry and receives, verbatim:\n   - the entry's identity, position in the order, scope boundary, **size band**,\n     parent relationship, `depends_on`, and `recommended_after`;\n   - the acceptance criteria and design material for that entry's slice;\n   - the shared research, materials, and framing artifacts;\n   - for an **epic child**, its `owns_verifications` entries and carried ticket-local finding id, evidence, and smallest amendment, word for word. The\n     writer copies each obligation verbatim into the child's acceptance criteria;\n   - for an **epic parent**, the record's coverage map, its exact verdict, and\n     every override with its recorded reason, for the parent's\n     `## Epic coverage map` section. Take the coverage map **from the record**,\n     including its owner-run owners (`owner_kind: owner_run`, with `who` and\n     `step_ref`). Owner-run obligations are never passed to a child invocation;\n     they stay the owner's;\n   - an explicit output path for the drafted body.\n\n   State in every prompt that the decomposition is **frozen**: the invocation\n   renders its entry and may not add, remove, merge, reorder, renumber, or\n   rescope anything, and may not write about sibling entries as though it were\n   deciding them.\n\n3. **Do not batch.** One invocation per entry, never one invocation asked to emit\n   every body. Two failure modes are both real and this shape avoids both: N\n   fully independent decisions overlap, omit dependencies, and contradict the\n   parent — which is why the decomposition is frozen upstream rather than\n   re-derived per child; and one invocation emitting the whole set produces\n   unreliable output as the manifest grows. Separating the decision from the\n   rendering is what lets the rendering fan out safely, so a large manifest is\n   handled by *more* invocations, never by collapsing back to one.\n\n4. Every entry type gets the same treatment — the same research protocol,\n   materials inventory, secret-redaction rules, required sections, and Jira\n   description bounds. An epic parent is not a thinner document than a\n   standalone ticket, and an epic child is not a thinner document than either.\n\n5. When every entry has a draft, re-run the preflight checks — including the\n   epic coherence check — against the rendered set. For an epic, also compare\n   each child draft's acceptance criteria with that child's reviewed\n   `child_evidence`: every `owns_verifications` obligation and every supplied carried finding's id, evidence, and smallest amendment must appear verbatim in its conditional carried section.\n   A draft that dropped, reworded, or merged an obligation or carry fails closed. Then\n   hand off to creation:\n   - **Epic** — `upload-epic-hierarchy.md`, unchanged. It creates the parent with\n     `issue_type = \"Epic\"`, captures the resolved epic key, then calls\n     `create_ticket(parent_key=<epic_key>)` per child in manifest order with\n     `track_ticket` after each, and carries idempotency labels throughout so a\n     partial failure resumes rather than duplicating. Nothing new is required to\n     *create* an epic — only to propose one.\n   - **Siblings** — ordinary `create_ticket` calls in manifest order, unparented,\n     with no epic parent synthesized.\n\n6. This stage emits **no Epic Implementer launch**. The handoff belongs to the\n   calling surface and names exactly one launch, by host: `/drive-epic-run <EPIC>`\n   on Claude Code or Cursor, or `drive-epic <EPIC>` on Codex or Copilot. Both\n   launch through `drive-epic`, the single Epic Implementer entry point.\n\n## Return\n\nReport the manifest's shape (`epic` or `siblings`), the entry count, each entry's\ndrafted body path in manifest order, and the preflight verdict. On a preflight\nfailure, name the violated prerequisite and the offending entry, and confirm that\nno ticket was created. When the epic coherence check fails, name the specific\nfailure — missing record, unreadable record, unrecognized schema version,\ndigest mismatch, top-level digests that differ from the last round's,\nunresolved required council, `blocked`, un-bypassed `not_checked`, or\n`independent: false` on an unattended run — and\nconfirm that no ticket was created.\n",
+    "render-ticket-manifest.md": "Render every entry of an approved ticket manifest into a drafted body, one `jira-ticket-writer` invocation per entry, without re-deciding the split.\n\nThis stage sits between **decomposition** (which decided the split once and froze\nit) and **creation** (`upload-epic-hierarchy.md` for an epic, ordinary\n`create_ticket` calls for siblings). It owns exactly one job: turning frozen\nmanifest entries into drafted bodies. It decides nothing.\n\n## Inputs\n\n- **The approved manifest** — the ordered plan the decomposition pass froze.\n  On the `idea-to-ticket` path this is `decomposition-plan.json` in the run\n  directory, produced by `decompose-epic-candidate.md`. On the `plan-epic` path\n  it is the sub-task list in `epic-plan.md`, produced by `decompose-epic.md`. On\n  a client-driven path (`/define-tickets` Stage 9) it is the approved outline\n  shown at the gate.\n- **For an epic, the frozen manifest JSON and its coherence record.** The\n  record `epic-coherence.json` and its input `epic-coherence-input.json` sit in\n  the same directory as the frozen manifest JSON: the run directory beside\n  `decomposition-plan.json` on the `idea-to-ticket` path, and the epic plan\n  directory beside `epic-manifest.json` on the `plan-epic` and\n  `/define-tickets` paths. Take the normalized `manifest` array, the current\n  `child_evidence` array, and the `non_child_owners` array (absent when the\n  epic has none) from the caller's frozen JSON artifacts — the same\n  normalization the caller used to build `epic-coherence-input.json`.\n- **The approval state** for that manifest. Whether approval is an explicit\n  affirmative or a pipeline auto-approval variable is the calling surface's own\n  rule; this stage only needs to know it resolved.\n- **The research and framing artifacts** each entry's writer invocation needs —\n  the same set the standalone drafting path passes.\n\n## Preflight — fail closed, before any body is rendered\n\nCheck all of the following first. Each one is a **hard failure** that stops the\nflow before a single writer invocation and long before any Jira mutation. None\nof them degrades to a partial run:\n\n1. **Approval unresolved.** The manifest's approval gate has not resolved, or\n   resolved as declined. Nothing renders and nothing is created.\n2. **Manifest identity changed.** The manifest presented here is not the one that\n   was approved — a different entry count, different ordering, renumbered\n   entries, or an altered scope boundary. A substituted split never silently\n   replaces the approved one.\n3. **An entry past the size ceiling.** An entry whose stated scope runs beyond\n   roughly 40 files or ~3000 LOC is over the bound wherever it sits — a\n   standalone ticket and an epic child alike. Fail and name the entry; do not\n   draft it, do not split it here, and do not shrink its stated scope to fit. An\n   `XL` entry below that ceiling is not a violation and needs no supporting\n   evidence: `XL` is the preferred shape for work that does not fit in `L`.\n4. **An entry with no writer draft after rendering.** Every entry must have\n   produced a body. A missing draft is a failure, not an entry to skip.\n5. **Epic coherence not cleared (epic manifests only).** An epic manifest renders\n   only when all of the following hold. Check them before any writer invocation\n   and before any Jira mutation:\n   - `epic-coherence.json`, written by `review-epic-coherence.md`, exists beside\n     the manifest (in the same directory) and is readable, well-formed JSON.\n   - Its `schema_version` is a recognized value: `1`, `2`, or `3`. Legacy blocking findings are foundation findings. For version 3, validate scope, child ownership, carry completeness, confirmation budget, and foundation-based clearance before rendering. Any other value\n     fails.\n   - Its top-level `manifest_sha256` matches the manifest being rendered, its\n     `child_evidence_sha256` matches the child evidence being rendered, **and**\n     its `non_child_owners_sha256` matches the non-child owners being rendered.\n     Compute all three with the canonical JSON encoding\n     `review-epic-coherence.md` specifies, over the normalized `manifest` array,\n     the `child_evidence` array, and the `non_child_owners` array (an absent\n     array hashes as an empty array) — never over a whole file's bytes. A\n     version `1` record has no `non_child_owners_sha256`. Treat that absent\n     digest as the empty-array digest **only when** the input being rendered has\n     no `non_child_owners`; otherwise it is a mismatch.\n   - Its `rounds` array is non-empty, and its last round carries\n     `manifest_sha256` and `child_evidence_sha256` — for version `1` too. A\n     version `2` last round also carries `non_child_owners_sha256`. The\n     top-level digests **equal the last round's digests**. A version `1` record\n     is read as having no confirmation rounds. A record whose top-level digests\n     no reviewer round saw is a hard failure: that is the BAPI-1316 case, where\n     the manifest was amended after the final round.\n   - The **only** exception to last-round equality is an **attended** record\n     with `amended_after_final_round: true`, an override of kind `bypass` with a\n     non-empty typed reason, and verdict `not_checked`. Its top-level digests\n     must still match the input being rendered. An unattended run never accepts\n     this exception.\n   - Its `verdict` is `pass`, including a version 3 record with carried ticket-local blockers; or\n     `accepted_with_gaps`, with an override of kind `accept` and a non-empty reason for every\n     remaining foundation blocking finding; or\n     `not_checked`, with a recorded override of kind `bypass` carrying a\n     non-empty reason (the attended bypass of an unavailable reviewer).\n   - **No unresolved required council.** A required council whose outcome is\n     `still_running`, `failed`, or `timed_out` fails the check unless an\n     attended override of kind `accept` with a non-empty reason names that\n     council's `council_id`. This applies to every council the record lists,\n     including a second one in `councils`. A council outcome of `declined_by_operator` is resolved and needs no `accept` override, whether it was declined at the pre-round-1 ask or through legacy `council_preapproval: declined`. A legacy `accept` override targeting `council: \"declined_by_operator\"` remains valid but is ignored for clearance.\n     Displayed reasons and override targets for any other item must be\n     unchanged between approval and creation; otherwise show the approval gate\n     again.\n   - **Unattended runs** (`auto_approve_external` is the literal `\"true\"`) need\n     independent clearance. A record with `independent: false` fails even when\n     its verdict is `pass`. An attended-only bypass never clears an unattended\n     run, so an unattended `not_checked` fails.\n   - Unknown record fields, such as a historical `council_note`, are ignored.\n     They are never treated as an authorization.\n\n   A missing record, an unreadable or malformed record, an unrecognized\n   `schema_version`, a digest mismatch, top-level digests that differ from the\n   last round's, an unresolved required council, a `blocked` verdict, and an\n   un-bypassed `not_checked` are all hard failures.\n   **A siblings manifest skips this check entirely**: siblings get no coherence\n   review and need no record. Item 2's identity check is separate and unchanged.\n   A changed manifest identity fails item 2 whatever the coherence record says.\n\nFail-open applies **only** to enrichment and context gathering — an optional\nresearch artifact that is missing may degrade the context a body is written\nfrom. Approval, manifest identity, sizing validity, writer-output completeness,\nand epic coherence all fail closed. The coherence record is **not** an\nenrichment artifact: a missing or failing record never degrades to a partial or\nfail-open run.\n\n## Instructions\n\n1. Read the approved manifest in full. Record its entry count, its order, and\n   each entry's identity, so the identity check above has something to compare\n   against.\n\n2. **Fan out one `jira-ticket-writer` invocation per entry**, in manifest order —\n   the epic parent, then each child; or each ordinary sibling. Each invocation\n   is bound to exactly one entry and receives, verbatim:\n   - the entry's identity, position in the order, scope boundary, **size band**,\n     parent relationship, `depends_on`, and `recommended_after`;\n   - the acceptance criteria and design material for that entry's slice;\n   - the shared research, materials, and framing artifacts;\n   - for an **epic child**, its `owns_verifications` entries and carried ticket-local finding id, evidence, and smallest amendment, word for word. The\n     writer copies each obligation verbatim into the child's acceptance criteria;\n   - for an **epic parent**, the record's coverage map, its exact verdict, and\n     every override with its recorded reason, for the parent's\n     `## Epic coverage map` section. Take the coverage map **from the record**,\n     including its owner-run owners (`owner_kind: owner_run`, with `who` and\n     `step_ref`). Owner-run obligations are never passed to a child invocation;\n     they stay the owner's;\n   - an explicit output path for the drafted body.\n\n   State in every prompt that the decomposition is **frozen**: the invocation\n   renders its entry and may not add, remove, merge, reorder, renumber, or\n   rescope anything, and may not write about sibling entries as though it were\n   deciding them.\n\n3. **Do not batch.** One invocation per entry, never one invocation asked to emit\n   every body. Two failure modes are both real and this shape avoids both: N\n   fully independent decisions overlap, omit dependencies, and contradict the\n   parent — which is why the decomposition is frozen upstream rather than\n   re-derived per child; and one invocation emitting the whole set produces\n   unreliable output as the manifest grows. Separating the decision from the\n   rendering is what lets the rendering fan out safely, so a large manifest is\n   handled by *more* invocations, never by collapsing back to one.\n\n4. Every entry type gets the same treatment — the same research protocol,\n   materials inventory, secret-redaction rules, required sections, and Jira\n   description bounds. An epic parent is not a thinner document than a\n   standalone ticket, and an epic child is not a thinner document than either.\n\n5. When every entry has a draft, re-run the preflight checks — including the\n   epic coherence check — against the rendered set. For an epic, also compare\n   each child draft's acceptance criteria with that child's reviewed\n   `child_evidence`: every `owns_verifications` obligation and every supplied carried finding's id, evidence, and smallest amendment must appear verbatim in its conditional carried section.\n   A draft that dropped, reworded, or merged an obligation or carry fails closed. Then\n   hand off to creation:\n   - **Epic** — `upload-epic-hierarchy.md`, unchanged. It creates the parent with\n     `issue_type = \"Epic\"`, captures the resolved epic key, then calls\n     `create_ticket(parent_key=<epic_key>)` per child in manifest order with\n     `track_ticket` after each, and carries idempotency labels throughout so a\n     partial failure resumes rather than duplicating. Nothing new is required to\n     *create* an epic — only to propose one.\n   - **Siblings** — ordinary `create_ticket` calls in manifest order, unparented,\n     with no epic parent synthesized.\n\n6. This stage emits **no Epic Implementer launch**. The handoff belongs to the\n   calling surface and names exactly one launch, by host: `/drive-epic-run <EPIC>`\n   on Claude Code or Cursor, or `drive-epic <EPIC>` on Codex or Copilot. Both\n   launch through `drive-epic`, the single Epic Implementer entry point.\n\n## Return\n\nReport the manifest's shape (`epic` or `siblings`), the entry count, each entry's\ndrafted body path in manifest order, and the preflight verdict. On a preflight\nfailure, name the violated prerequisite and the offending entry, and confirm that\nno ticket was created. When the epic coherence check fails, name the specific\nfailure — missing record, unreadable record, unrecognized schema version,\ndigest mismatch, top-level digests that differ from the last round's,\nunresolved required council, `blocked`, un-bypassed `not_checked`, or\n`independent: false` on an unattended run — and\nconfirm that no ticket was created. The failure identifiers stay as written. When\nthe explanation is shown to a person in attended chat, put it in the plain words of\n\"What the user sees\" in `review-epic-coherence.md` (for example, \"Needs your decision\"\nand \"Couldn't check\").\n",
     "research-decision.md": "Decide which research tools to run for this idea, biased toward cheap local research first.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json` (must already exist from the preflight step).\n\n## Instructions\n\n1. Read `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`. This is the source of truth for `idea`, `readiness`, `scope`, and `run_id`. If the file does not exist, halt locally — the preflight step did not complete.\n\n2. Decide which research tools should run for this idea, in roughly this priority order:\n   - **Local codebase research first.** Inspect the working tree (search, grep, file reads) for prior art, related modules, and existing tests. Prefer this for anything that touches code you already own.\n   - **Narrow web search second.** Use targeted web search for short factual lookups: a specific library API, a known external standard, a public spec.\n   - **Deep research only when justified.** Deep research is expensive and slow; it must be earned by one of the rubric items below.\n\n3. Deep-research allowance rubric. Deep research is only allowed when at least one of these is true:\n   - **blast radius**: the change spans many systems or has high reversibility cost (e.g., schema migrations, auth, billing, public APIs).\n   - **unfamiliar external domain**: the idea depends on a third-party domain or specification the repository has no prior coverage of.\n   - **compliance/security uncertainty**: there is real compliance or security uncertainty (SOC2, PII, secret handling, access control).\n   - **cheaper research failed**: a cheaper round (local + narrow web search) already happened in this run and left blocking unknowns.\n   - **explicit user request**: the user explicitly asked for deep research.\n\n4. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-plan.json`. Required fields:\n   - `selected_tools` — array of tool identifiers to run, drawn from at least `[\"codebase_search\", \"web_search\", \"deep_research\"]`. Empty array is allowed when no research is needed.\n   - `rationale` — short string explaining the choice in terms of the rubric above.\n   - `deep_research_query` — string. Required when `deep_research` is in `selected_tools`, otherwise empty string.\n   - `web_search_topics` — array of strings; may be empty.\n   - `codebase_search_topics` — array of strings; may be empty.\n   - `expected_unknowns` — array of strings describing what the research is expected to resolve.\n\n5. Do not invoke any research tool from this step — that happens in `execute-research.md`. This step only writes the plan.\n\n## Return\n\nConfirm `research-plan.json` was written, list `selected_tools`, and quote the rationale.\n",
-    "review-epic-coherence.md": "# Review Epic Coherence\n\nThis is the shared procedure for checking an epic's children **as a set**. It answers two\nquestions no per-ticket review asks: does every epic acceptance criterion have a child that\ncarries out its verification, and is everything one child produces wired to whatever consumes\nit? Drafting surfaces and the on-demand `/review-epic-coherence` command run this same text.\n\nThe check fails **visibly**. A run that cannot finish is `not_checked`. It is never `pass`.\n\n**Enforcement status.** The three drafting surfaces — `define-tickets`, `plan-epic`, and\n`idea-to-ticket` — call this procedure in drafting mode before creation or approval, and\n`render-ticket-manifest.md` refuses to render an epic without a clearing record. A\nreport-mode result from the on-demand command is a diagnostic, not a gate: it clears nothing.\n\n## Inputs\n\nState these four values before starting:\n\n1. **Input document path** — the path to `epic-coherence-input.json`.\n2. **Output directory** — a directory beneath the `docs_dir` that the `ping` tool returned.\n3. **Mode** — `drafting` or `report`.\n4. **Unattended** — true only when `auto_approve_external == \"true\"`. Otherwise the run is\n   attended.\n\nIf any of the four is missing, stop and report which one. Do not guess a default.\n\nAn optional fifth input, **`council_preapproval`**, may accompany them. It carries a `value`\n(`approved` or `declined`) and its `source` (for example, the operator's Stage 6 reply in\n`define-tickets`). It records the operator's prior consent for the **initial** high-risk\ncouncil only; see \"Council call\". It is not one of the required inputs, so its absence never\nstops the run. When it is absent, the attended pre-round-1 ask stays exactly as written below.\n\n## The input document\n\nThe document carries artifacts only. It never carries the drafting conversation.\n\n```json\n{\n  \"epic\": {\n    \"key\": \"EPIC-1\",\n    \"title\": \"Short epic title\",\n    \"acceptance_criteria\": [\n      { \"id\": \"AC-1\", \"text\": \"What must be true\", \"verification\": \"How it is proven\" }\n    ]\n  },\n  \"design_text\": \"Goals and design text: the exploration's Proposed Design, the epic parent body, or equivalent.\",\n  \"manifest\": [\n    {\n      \"id\": \"1\",\n      \"title\": \"Child title\",\n      \"scope\": \"What the child does\",\n      \"size_band\": \"L\",\n      \"depends_on\": [],\n      \"recommended_after\": [],\n      \"touched_files\": [\"path/relative/to/repo.py\"],\n      \"read_files\": [\"path/the/child/only/reads.py\"],\n      \"owns_verifications\": [\n        { \"epic_ac\": \"AC-1\", \"obligation\": \"The concrete part of AC-1's verification this child carries out\" }\n      ]\n    }\n  ],\n  \"child_evidence\": [\n    {\n      \"id\": \"1\",\n      \"acceptance_criteria\": [\"Each acceptance criterion of the child, verbatim\"],\n      \"body\": \"The child ticket body, if available\"\n    }\n  ],\n  \"non_child_owners\": [\n    {\n      \"id\": \"OR-1\",\n      \"kind\": \"owner_run\",\n      \"who\": \"Release owner\",\n      \"step_ref\": \"Release checklist step 6\",\n      \"step_text\": \"Release checklist step 6: the release owner runs the smoke test against production and posts the output as a comment on the epic.\",\n      \"records_result_in\": \"a comment on the epic\",\n      \"owns_verifications\": [\n        { \"epic_ac\": \"AC-2\", \"obligation\": \"Run the production smoke test and post its output on the epic\" }\n      ]\n    }\n  ]\n}\n```\n\nField rules:\n\n- `epic` carries either `key` or `slug` (one is enough), plus `title` and\n  `acceptance_criteria`. Each acceptance criterion has `id`, `text`, and `verification`. When\n  an epic AC has no verification sentence, coverage is judged against its text, the basis is\n  `text_only`, and the reviewer raises an advisory input finding naming the missing sentence.\n- `design_text` is the goals and design text.\n- `manifest` is the **complete, ordered** child list. Each entry carries `id` (a placeholder\n  index or a real ticket key), `title`, `scope`, `size_band`, `depends_on`, and\n  `recommended_after`. These are the same field names `decompose-epic.md` and\n  `decompose-epic-candidate.md` already use.\n- `touched_files` is optional. It lists the files the child **edits or creates**. When absent,\n  the fit check uses the file paths the child's scope and body name. A `touched_files` path that\n  does not exist yet can be a planned creation; that alone is not a problem.\n- `read_files` is optional. It lists files the child **only reads**. It lives in the manifest,\n  so it is hashed. Reads inform the fit check. Only edits (`touched_files`) count toward edit\n  overlap between children and toward the high-risk path check in \"Escalation rule\". A path\n  must not appear in both lists. A `read_files` path that does not exist is an `input` problem,\n  because a child cannot read a file that is not there. When `read_files` is absent, behavior is\n  unchanged.\n- `owns_verifications` is optional. It is a list of entries with `epic_ac` (an epic AC id) and\n  `obligation` (the concrete part of that AC's *verification* this child will carry out, in\n  words a reviewer can hold against the verification sentence). It is a **claim** the reviewer\n  checks. It is never proof by itself. When it is absent (older epics, the on-demand path), the\n  reviewer derives candidate owners from each child's own acceptance criteria, and the record\n  says `owns_verifications_source: derived`. When it is present, the record says `declared`.\n- `child_evidence` is a **separate top-level array**, keyed by child `id`. Each entry may carry\n  `acceptance_criteria` and `body`. It lives **outside** the hashed manifest, so evidence can be\n  refreshed without changing manifest identity. Derived ownership counts only when a child's\n  acceptance criteria contain a concrete commitment to the obligation. When the material needed\n  to establish ownership is absent, that is an explicit `input` gap, not coverage.\n- `non_child_owners` is an optional **top-level array** beside `child_evidence`. It names the\n  owners of epic AC verifications that no child carries out, such as a step in an owner-run\n  release checklist. Each entry has:\n  - `id` — for example `OR-1`. It is unique across the array and never equal to any child `id`.\n  - `kind` — a closed vocabulary with one value: `owner_run`.\n  - `who` — a named person or role, for example \"Release owner\".\n  - `step_ref` — the step it points at, for example \"Release checklist step 6\".\n  - `step_text` — the step's text, copied **verbatim** from `design_text`.\n  - `records_result_in` — where the result is recorded, for example \"a comment on the epic\".\n  - `owns_verifications` — a list of `epic_ac` plus `obligation` entries, the same shape\n    children use.\n\n  `step_text` is copied into the entry on purpose. `design_text` is not hashed, so a step that\n  lived only there could change without changing the review's identity. The copied, hashed\n  `step_text` is the reviewed commitment. An owner-run owner owns **coverage only**: it never\n  fills a hand-off grid cell. When the array is absent, no AC has a non-child owner.\n\n**Local markdown drafts.** When an epic is drafted as local markdown files outside a drafting\nsurface, build this document with the packaged `epic-coherence-input build` subcommand of the\nBridge MCP package: `epic-coherence-input build --outline <outline-path> --out <output-path>`.\nDo not assemble it by hand. The outline names the epic draft, each child's draft, its\ndependencies, size band, `edits` (which become `touched_files`), `reads` (which become\n`read_files`), and `owns_verifications`, plus any `non_child_owners`. Every epic AC bullet in the\nepic draft must start with an explicit id such as `AC-3:`; the builder never numbers ACs by\nposition or matches them by keyword. `epic-coherence-input check <input-path>` validates an\nexisting document against the structural rules in \"Validation\" and prints the three digests. It\nnever judges coverage; that stays the reviewer's job. The three drafting surfaces keep their\nstructured normalization, and the on-demand `/review-epic-coherence` command keeps building its\ninput from ticket data.\n\n## Identities\n\nThree digests identify what was reviewed. All three use the same canonical JSON encoding.\n\n- `manifest_sha256` is the SHA-256 hex digest of\n  `json.dumps(manifest, sort_keys=True, separators=(\",\", \":\"), ensure_ascii=False).encode(\"utf-8\")`,\n  computed over the `manifest` array only. Compute it locally with this one line:\n\n  ```bash\n  python3 -c 'import hashlib,json,sys; manifest=json.load(open(sys.argv[1], encoding=\"utf-8\"))[\"manifest\"]; print(hashlib.sha256(json.dumps(manifest, sort_keys=True, separators=(\",\", \":\"), ensure_ascii=False).encode(\"utf-8\")).hexdigest())' <input-path>\n  ```\n\n- `child_evidence_sha256` is the SHA-256 hex digest of the same encoding applied to the\n  `child_evidence` array (an absent array hashes as an empty array).\n- `non_child_owners_sha256` is the SHA-256 hex digest of the same encoding applied to the\n  `non_child_owners` array. An absent array hashes as an empty array, as `child_evidence`\n  does. Compute it locally with this one line:\n\n  ```bash\n  python3 -c 'import hashlib,json,sys; owners=json.load(open(sys.argv[1], encoding=\"utf-8\")).get(\"non_child_owners\", []); print(hashlib.sha256(json.dumps(owners, sort_keys=True, separators=(\",\", \":\"), ensure_ascii=False).encode(\"utf-8\")).hexdigest())' <input-path>\n  ```\n\nRecord **all three** digests, at the top level and in every round. A caller that wants to\nreuse a prior review must compare **all three** identities against the manifest, evidence,\nand non-child owners it is about to use. A matching manifest with changed evidence or changed\nowners is not the same review. The sibling integration's preflight must compare all three.\n\n`design_text` deliberately stays **outside** identity. The copied and hashed `step_text` is\nthe reviewed commitment of an owner-run step. There is no fourth digest, and no render-time\ncheck that `design_text` still contains the step.\n\n## Validation\n\nBefore any reviewer run, validate the input document. Every problem becomes a visible `input`\nfinding. Nothing is silently dropped.\n\n- Child ids are unique. Epic AC ids are unique. Every `owns_verifications.epic_ac` names a real\n  epic AC, and every `child_evidence.id` names a real manifest child.\n- The document shapes and the key or slug syntax are valid.\n- Every `non_child_owners` entry is well formed. Its `id` is unique across the array and never\n  collides with a child id. Its `kind` is `owner_run`. Its `who`, `step_ref`, `step_text`, and\n  `records_result_in` are non-empty. Every one of its `owns_verifications.epic_ac` values names\n  a real epic AC. A malformed entry, a colliding id, an invalid AC reference, and a missing\n  required field are each a visible `input` finding.\n- Every named file path is repository-relative. Reject absolute paths and any path that\n  traverses upward. A path listed in both `touched_files` and `read_files` of the same child is\n  an `input` finding.\n- The output directory is beneath the `docs_dir` that `ping` resolved. Refuse to write anywhere\n  else.\n- A missing, invalid, or unreadable named file is an `input` finding. So is inaccessible child\n  material and a missing set of epic acceptance criteria. A nonexistent `touched_files` path can\n  be a planned creation and is not, by itself, a finding. A nonexistent `read_files` path is an\n  `input` finding.\n- A missing verification sentence alone is **advisory**. Any problem that prevents a meaningful\n  review (no epic acceptance criteria, an empty manifest, an unreadable input document) makes\n  the verdict `not_checked`. It never produces a complete-looking coverage map.\n\nDescribe variable paths in words or angle brackets, such as `<output-directory>`. Do not write\nany literal brace-wrapped identifier other than `docs_dir`, including in examples.\n\n## Reviewer run\n\nInvoke the `epic-coherence-reviewer` agent in a **fresh context**. Pass it only the input\ndocument path. Run it **once per round over the whole frozen manifest** — never per child and\nnever over a subset. The reviewer must not receive the drafting conversation.\n\nResolve the agent the way `draft-ticket.md` resolves `jira-ticket-writer`: through the Task tool\nor a host equivalent you have confirmed can resolve it. Cursor has no agent mirror for this\nagent, so on Cursor resolution normally fails.\n\n**Fresh-context fallback.** If no fresh context can be obtained, read the agent file\n`agents/src/epic-coherence-reviewer.md` (or its installed mirror) and execute its methodology\ninline. Set `independent: false` in the record and say so in the report. An inline run is never\na silent independent pass.\n\n- In an **attended** run, offer a fresh-context rerun when one becomes available.\n- In an **unattended drafting** run, an inline `pass` is not the independent gate. Halt.\n\n## Escalation rule\n\nEscalate to a council **only** when at least one of these is true:\n\n1. Any blocking finding has `confidence: uncertain`.\n2. The caller **disputes** a blocking finding instead of amending it. The caller is the drafting\n   agent in drafting mode and the operator in report mode.\n3. The epic is **high risk**.\n\nHigh risk means one of the following. Count **children**, never edited files: a single child\nthat edits ten files under one prefix is still one child.\n\n- The epic has **six or more children**.\n- **One** child's `touched_files` falls under one of these paths. A single editing child is\n  enough:\n  - `db/migrations/` and `db/alembic/` (the design says `db/migrations/`; this repository's\n    migrations live in `db/alembic/`, so match both)\n  - `api/library/billing/`\n  - `api/routes/setup/auth.py`\n  - `api/library/auth/`\n- **Two or more distinct** children each edit under the same kind of path from the list below.\n  One editing child alone does **not** make the epic high risk. This list is every remaining\n  prefix in `_CONTAINMENT_HAZARD_PATHS` in `api/library/github/workflow_planning_prediction.py`\n  (the list also carries `db/alembic/`, which is already a single-trigger path above):\n  `mcp_server/src/executor/`, `mcp_server/src/agent-launchers/`,\n  `mcp_server/src/claude-settings.ts`, `.github/workflows/`,\n  `tests/integration/conductor_harness/`, and `api/library/db/`\n\n| Edits under the path | Risk tier |\n| --- | --- |\n| One child edits `api/library/db/` | low |\n| Two children each edit `api/library/db/` | high |\n| One child edits an executor prefix such as `mcp_server/src/executor/` | low |\n| Two children each edit executor-prefix paths | high |\n| One child edits `db/alembic/`, `api/library/billing/`, or auth paths | high |\n| Six or more children, whatever they edit | high |\n\nOnly edits count. A path a child lists in `read_files` never makes the epic high risk, even\nunder one of these prefixes, so a child that only reads `api/library/db/` does not trigger\nthis rule. Reads do not count toward the two-child threshold either.\n\nA low-risk epic with one child editing `api/library/db/` or an executor prefix still receives\nthe low-risk reviewer rounds in \"Drafting mode\". If a round raises a blocking finding with\n`confidence: uncertain`, the epic is promoted to high risk and the council flow starts. Any\nblocking findings that remain go to the operator at the create gate. This adds no other\nmitigation.\n\nWhen `touched_files` is absent for a child, apply the same path check to the concrete paths its\nscope and body name. When a child's file ownership is unknown, record **uncertainty**. Do not\ndeclare the epic low risk.\n\n**Classify the risk before round 1.** Decide the initial risk tier from the input alone,\nbefore the first reviewer run, using the child count and the edit paths. The tier is `high`\nwhen this rule matches, and also when unknown file ownership leaves the question open. It is\n`low` otherwise. Record it as `risk_tier` with its `risk_reasons`, for example \"Children 1 and 3\nboth edit `api/library/db/`\". Trigger 3 therefore fires **before round 1**. Triggers 1 and 2 still fire\nafter any later round.\n\nAn uncompleted required escalation leaves the result unresolved. It is never a quiet pass.\n\n## Council call\n\nBefore **every** billable council request, state:\n\n- the cost: **26–65 credits and about 15 minutes** (26 credits for standard models, 65 credits\n  for frontier models; state the applicable tier if providers are pinned). The source is\n  `api/library/billing/pricing.py`;\n- the escalation reason (which of the three triggers fired);\n- that council output cannot itself clear a blocker.\n\nAn **attended** run asks the operator to approve before proceeding. An **unattended** run states\nthe cost in its output and proceeds. This holds for every request, including a `mode: general`\nretry.\n\n**When the council starts.**\n\n- **High-risk trigger.** For an epic classified high risk before round 1, state the cost and,\n  when attended, get the operator's approval **before** round 1 starts. Then request the\n  council and start the round-1 reviewer run **in parallel**. Do not wait for a later round.\n  How the approval is obtained depends on `council_preapproval`:\n  - `approved`: state the cost, then start the initial council alongside round 1 without\n    another ask.\n  - **No value supplied:** keep the attended pre-round-1 ask above, unchanged.\n  - `declined`: do not request that council. Record `council_id: null` and\n    `council_outcome: \"declined_by_operator\"`.\n\n  `council_preapproval` covers the **initial** high-risk council only. If its technical request\n  needs the `mode: general` retry, state the cost again without asking again. A later uncertain\n  or disputed council keeps its own cost statement and attended approval; the pre-approval never\n  covers it.\n- **Uncertain or disputed trigger.** Request the council after the round that raised the\n  finding.\n- **How many.** One council per drafting run for the initial high-risk trigger. A later\n  qualifying trigger (an uncertain or disputed blocking finding) may start **at most one more**\n  council, with its own cost statement and approval.\n\nCall `request_council` with:\n\n- `mode`: `technical`\n- `wait_for_result`: `false`\n- no `repo_name`\n- task text containing **only** the input document's artifacts and the contested findings.\n  The early high-risk council has no reviewer findings yet, so its task text holds **only** the\n  input document's artifacts. Never invent findings for it. Ask it to look for cross-child and\n  release-level risks, such as concurrent writers, migration and rollback order, and rollout\n  that runs ahead of the code.\n\nThen poll `get_council` for a bounded period. If technical mode cannot run because the\nrepository is not indexed, repeat the request with `mode: general`, and state the cost again\nbefore that request too.\n\n**The amendment freeze.** The round-1 amendment freezes at the moment the caller begins writing\nthe amended input document after collecting the round-1 findings. Poll `get_council` while the\nround-1 reviewer runs. Council conclusions received before the freeze join that **same**\namendment pass. Conclusions received after it join the next pass. A frozen round is never\nchanged after the fact.\n\nCouncil conclusions join the finding list as **separate** findings with `source: council`. The\noriginal reviewer finding is kept unchanged. It is never edited, downgraded, or removed because\na council failed, timed out, is still running, left the dispute unresolved, or concluded.\nRecord the `council_id` and the council outcome. Record still-running and failed outcomes as\nunresolved.\n\n**An unfinished required council.** A required council that is `still_running`, `failed`, or\n`timed_out` when the last round or confirmation pass ends is unresolved. The verdict is never\n`pass`. An **attended** operator, after being shown the council's id, cost, and elapsed time,\nmay accept it with a typed override of kind `accept` that names its `council_id`. An\n**unattended** run records `blocked` and halts before any ticket is created.\n\nA council declined through `council_preapproval: declined` is also unresolved. It has no\n`council_id`, so a null `council_id` is never a substitute target. Only an **attended**\noverride of kind `accept` with a non-empty reason and the exact target\n`council: \"declined_by_operator\"` clears it. Accepting a finding by `finding_id` never clears\nit. The reason may be typed by the operator or drafted by the agent and shown at the create\ngate where that gate applies. An **unattended** run records `blocked` and halts.\n\n## Drafting mode\n\nDrafting mode is for a drafting surface that can still change the manifest.\n\n- **Amend and recheck.** The reviewer only describes amendments. The **caller** amends the\n  manifest (adds or rescopes children), re-freezes it, and writes a **new** input document. The\n  procedure then reruns the reviewer in a fresh context. Record each round with its own\n  `manifest_sha256`, `child_evidence_sha256`, and `non_child_owners_sha256`, blocking and\n  advisory counts, whether a council ran, and whether it was a confirmation pass.\n- **Foundation readiness and carry.** A round with zero foundation blockers is ready and exits the ordinary loop immediately. Carry unresolved ticket-local blockers without amending or rechecking merely because they remain. `pass` requires zero unresolved foundation blockers and may retain carried ticket-local findings; `accepted_with_gaps` is reserved for accepted remaining foundation blockers.\n- **Risk-scaled round limit.** The number of ordinary reviewer runs, `round_limit`, depends on\n  the risk tier from \"Escalation rule\":\n  - **Low risk** (the epic is not high risk and no blocking finding is `uncertain`):\n    `round_limit` is **2**. These are maximum ordinary rounds; exit earlier when a round has zero foundation blockers.\n    That is at most **2 reviewer runs**.\n  - **High risk**: `round_limit` is **3**. Allow at most **2 re-checks**, which is\n    **3 reviewer runs in total**, with the same zero-foundation early exit.\n  - **Promotion.** A low-risk epic whose round produces a blocking finding with\n    `confidence: uncertain` becomes high risk from that point. It gets the high-risk limit, and\n    trigger 1 fires. Promotion raises the ceiling to three total ordinary rounds, including rounds already completed.\n\n  If a round with foundation blockers has a foundation count greater than or equal to the preceding round's count, stop automatic looping with `non_convergence`; route attended findings to the create gate or halt unattended as `blocked`.\n\n  Record the final `risk_tier`, `risk_reasons`, and `round_limit`. A confirmation pass is not an\n  ordinary run and does not count toward `round_limit`.\n- **Confirmation pass.** Run a confirmation only after a caller amendment targeting foundation findings and when the ordinary-round rule calls for it. Derive `confirmation_passes_used` from `rounds[].confirmation`; the budget is two attended passes or one unattended pass, and refuse another at the budget.\n\n  When the caller changes the input after the last allowed ordinary\n  round, run **one confirmation pass**. It is a fresh-context reviewer run over the **whole**\n  amended manifest, never a subset. Its requested focus is narrower: the amended children, the\n  hand-offs they touch, and whether the findings the amendment targeted are closed. It must\n  still report **any** blocking finding it observes anywhere in the manifest; the narrower\n  focus never suppresses one. When it cannot establish where an amendment's impact ends, it\n  raises that as a blocking finding with `confidence: uncertain` instead of calling the\n  amendment confirmed. Record it in `rounds[]` with `\"confirmation\": true`.\n  - A confirmation pass **never** starts another automatic amendment loop. A new blocking\n    finding goes to attended fix-or-accept, or to the unattended halt.\n  - In an **attended** run, after the first confirmation pass, the operator may direct **at\n    most one** fix of a confirmation blocker. Then run **one** further whole-manifest\n    confirmation pass, so the last round bears the final digests. That is the whole budget\n    across re-runs in the same attended `define-tickets` run.\n  - Once that budget is spent, a remaining blocker is accepted with a non-empty reason or stays\n    `blocked`. Do not add an \"unconfirmed fixed\" state, and do not start another automatic\n    amendment loop. A typed acceptance stays available instead of the fix at any point.\n- **Final identity.** The top-level `manifest_sha256`, `child_evidence_sha256`, and\n  `non_child_owners_sha256` equal the digests of the **last** entry in `rounds[]`. A record\n  whose top-level digests no round saw does not clear. The sole exception is a confirmation\n  pass that cannot run: an **attended** operator may record `amended_after_final_round: true`\n  with an override of kind `bypass` carrying a typed reason. The verdict is then\n  `not_checked`, never `pass` or `accepted_with_gaps`, and the top-level digests still describe\n  the amended input. An **unattended** run halts instead.\n- **Attended resolution.** After the bound, each remaining **foundation** blocking finding must be\n  fixed within the same one-fix, one-further-confirmation-pass budget, or accepted with a non-empty reason.\n  Ticket-local blockers are carried to their child ticket; they do not require a foundation amendment\n  or acceptance to clear the epic record.\n  The reason may be typed by the operator or drafted by the agent and shown at the create gate\n  where that gate applies. An accepted finding is an override with `kind: accept`, plus\n  `finding_id`, `reason`, `accepted_by`, and `round`. Declining a foundation finding keeps the verdict `blocked`.\n  When **every** remaining foundation blocking finding is accepted, the verdict is `accepted_with_gaps`.\n- **Unattended halt.** If any foundation blocking finding remains after the bound, the verdict is\n  `blocked`. Return an explicit halt signal: **do not call `create_ticket`**. The caller must\n  stop.\n\n## When the review cannot run\n\nIf the reviewer cannot run (a tool error, a timeout, or a host that lacks the capability while\ninline execution also fails), or the material prevents a meaningful review, the verdict is\n`not_checked`. It is never `pass`.\n\n- **Attended:** offer a retry, or a bypass with a typed reason. A bypass is recorded as an\n  override with `kind: bypass`. The verdict stays `not_checked`.\n- **Unattended:** halt.\n\n## Report mode\n\nReport mode is diagnostic. It runs the reviewer **once**. There is no amendment loop and no halt\nsignal. Escalation still applies, with the cost stated and confirmation asked. It splits blocking counts and the verdict by scope: ticket-local blockers are labelled “would be carried into child N”, are not carried, and edit no ticket. The verdict is `pass`, `blocked`, or `not_checked` from foundation blockers only.\n\nA `blocked` or `not_checked` report is **diagnostic and not a clearance**.\n\n## The record: epic-coherence.json\n\nWrite `epic-coherence.json` into the output directory:\n\n```json\n{\n  \"schema_version\": 3,\n  \"checked_at\": \"2026-01-01T00:00:00Z\",\n  \"mode\": \"drafting\",\n  \"unattended\": false,\n  \"manifest_sha256\": \"<64 hex characters, or null>\",\n  \"child_evidence_sha256\": \"<64 hex characters, or null>\",\n  \"non_child_owners_sha256\": \"<64 hex characters, or null>\",\n  \"owns_verifications_source\": \"declared\",\n  \"verdict\": \"pass\",\n  \"independent\": true,\n  \"risk_tier\": \"low\",\n  \"risk_reasons\": [\"Three children; no child edits a high-risk path\"],\n  \"round_limit\": 2,\n  \"confirmation_passes_used\": 0,\n  \"confirmation_budget\": 2,\n  \"stop_reason\": \"ready\",\n  \"carried_ticket_local\": [],\n  \"amended_after_final_round\": false,\n  \"rounds\": [\n    {\n      \"manifest_sha256\": \"<64 hex characters>\",\n      \"child_evidence_sha256\": \"<64 hex characters>\",\n      \"non_child_owners_sha256\": \"<64 hex characters>\",\n      \"blocking_count\": 0,\n      \"foundation_blocking_count\": 0,\n      \"ticket_local_blocking_count\": 0,\n      \"findings_snapshot\": [],\n      \"advisory_count\": 0,\n      \"council_ran\": false,\n      \"confirmation\": false\n    }\n  ],\n  \"owner_run_acs\": [\"AC-2\"],\n  \"coverage_map\": [\n    {\n      \"epic_ac\": \"AC-1\",\n      \"judgment_basis\": \"verification\",\n      \"status\": \"covered\",\n      \"owners\": [\n        {\n          \"owner_kind\": \"child\",\n          \"child\": \"1\",\n          \"obligation\": \"Concrete obligation\",\n          \"child_ac\": \"The child AC id or a quoted child AC\",\n          \"source\": \"declared\"\n        }\n      ]\n    },\n    {\n      \"epic_ac\": \"AC-2\",\n      \"judgment_basis\": \"verification\",\n      \"status\": \"covered\",\n      \"owners\": [\n        {\n          \"owner_kind\": \"owner_run\",\n          \"child\": null,\n          \"owner\": \"OR-1\",\n          \"who\": \"Release owner\",\n          \"step_ref\": \"Release checklist step 6\",\n          \"records_result_in\": \"a comment on the epic\",\n          \"obligation\": \"Run the production smoke test and post its output on the epic\",\n          \"source\": \"declared\"\n        }\n      ]\n    }\n  ],\n  \"handoff_grid\": [\n    {\n      \"thing\": \"The stored field, endpoint, flag, event, job payload, or scope\",\n      \"consumer\": \"The consuming piece\",\n      \"write_path\": \"child id or null\",\n      \"read_path\": \"child id or null\",\n      \"caller\": \"child id or null\",\n      \"start\": \"child id or null\",\n      \"steady_state\": \"child id or null\",\n      \"wind_down\": \"child id or null\"\n    }\n  ],\n  \"findings\": [\n    {\n      \"id\": \"F-1\",\n      \"kind\": \"coverage\",\n      \"severity\": \"blocking\",\n      \"confidence\": \"certain\",\n      \"concerns\": \"AC-1\",\n      \"evidence\": \"What was observed, with file and line where code was read\",\n      \"smallest_amendment\": \"The smallest change that would close it\",\n      \"source\": \"reviewer\", \"scope\": \"foundation\"\n    }\n  ],\n  \"overrides\": [\n    { \"kind\": \"accept\", \"finding_id\": \"F-1\", \"reason\": \"Typed reason\", \"accepted_by\": \"Operator\", \"round\": 3 }\n  ],\n  \"council_preapproval\": { \"value\": \"approved\", \"source\": \"define-tickets Stage 6 reply\" },\n  \"council_id\": null,\n  \"council_outcome\": \"not_run\",\n  \"councils\": []\n}\n```\n\nRules:\n\n- `schema_version` is `3`. Readers also accept versions `1` and `2`; interpret every legacy blocking finding as `foundation`.\n- In version 3, validate every blocking finding's closed `scope` and every `ticket_local` child against the final manifest before counting, clearing, or carrying. Invalid or orphaned ownership fails closed; reclassify an ambiguously owned former carry as foundation explicitly.\n- `blocking_count` is the sum of `foundation_blocking_count` and `ticket_local_blocking_count`; count every blocking finding regardless of confidence.\n- `pass` requires zero unresolved foundation blockers.\n- `carried_ticket_local` holds one unresolved entry per stable identity with its finding id, child id, evidence, and smallest amendment. Preserve the latest snapshot and close an identity only when a later review explicitly establishes correction or supersession.\n- `stop_reason` is one of `ready`, `round_limit`, `non_convergence`, or `confirmation_budget_spent`.\n- `verdict` is one of `pass`, `accepted_with_gaps`, `blocked`, `not_checked`.\n- A `pass` with `independent: false` is allowed but flagged prominently in both files.\n- An `accept` override accepts a known gap. A `bypass` override skips a review that could not\n  run. Keep the two distinct.\n- `kind` on a finding is one of `coverage`, `handoff`, `fit`, `e2e_proof`, `input`.\n  `severity` is `blocking` or `advisory`. `confidence` is `certain` or `uncertain`. `source`\n  is `reviewer` or `council`.\n- Digests may be `null` **only** when unreadable input makes computing them impossible. Then\n  add an explicit `input` finding and set the verdict to `not_checked`.\n- The top-level digests equal the last round's digests. The only record allowed to differ is\n  an attended one with `amended_after_final_round: true`, a `bypass` override with a typed\n  reason, and verdict `not_checked` (see \"Drafting mode\").\n- `rounds[].confirmation` is `true` only for a confirmation pass. `risk_tier` is `low` or\n  `high`, `risk_reasons` lists why, and `round_limit` is the ordinary-run limit that applied\n  (`2` or `3`; report mode runs once).\n- Each coverage owner carries `owner_kind`, which is `child` or `owner_run`. A child owner\n  carries `child`, `obligation`, `child_ac`, and `source`. An owner-run owner carries\n  `child: null`, `owner` (its `non_child_owners` id), `who`, `step_ref`, `records_result_in`,\n  `obligation`, and `source: declared`.\n- `owner_run_acs` lists the id of every epic AC with at least one owner-run owner. It is empty\n  when there are none. Owner-run coverage is always visible, never silently passed.\n- `council_id` is `null` when no council ran. `council_outcome` is one of `not_run`,\n  `concluded`, `failed`, `timed_out`, `still_running`, or `declined_by_operator`. These two fields describe the first\n  council. When a second council runs, `councils` lists **every** council in order, each with\n  `council_id`, `trigger` (`uncertain`, `disputed`, or `high_risk`), and `outcome`. An override\n  that accepts an unfinished council carries `council_id` in place of `finding_id`.\n  An initial council declined through `council_preapproval` stays in `council_outcome` as\n  `declined_by_operator` with `council_id: null`, and is retained there when a later council\n  also needs an entry in `councils`. The override that accepts it carries\n  `council: \"declined_by_operator\"` in place of `finding_id` or `council_id`.\n- `council_preapproval` is present only when the caller supplied it. It persists its `value`\n  and `source`, and the record omits the field otherwise.\n- Unknown fields, such as a historical `council_note`, are outside this schema. Readers ignore\n  them. They never authorize clearance.\n- A `not_checked` record must **never** carry a coverage map that looks complete. Leave the map\n  empty, or mark every entry as not assessed.\n- Keep this schema in this file. Do not copy it into the ticket-authoring posture block.\n\n## The record: epic-coherence.md\n\nWrite `epic-coherence.md` into the same directory as a short human summary. Use **no tables**.\nIn this order:\n\n1. The **verdict**, as the very first line of the file (after the title heading). Nothing else comes\n   before it.\n2. **Independent: yes** or **Independent: no**, prominently, on the line directly after the\n   verdict, then the **next action**.\n3. The round count, the risk tier, and the round limit. Say which round, if any, was a\n   confirmation pass.\n4. Directly after the round count, one line: \"Owner-run coverage: N of M epic ACs depend on\n   steps a person runs outside the Epic Implementer.\"\n5. One **bullet per epic AC**: its id, the judgment basis (`verification` or `text only`), the\n   status, the owning child or the absence of one, the obligation, and the cited child AC\n   evidence. Mark derived ownership as derived. For an owner-run owner, say \"owner-run\" in\n   words, with the person or role, the step reference, and where the result is recorded, for\n   example: AC-4: covered, owner-run (Release owner, checklist step 5; result recorded in an\n   epic comment).\n6. **Blocking findings**, each labelled `blocking` with its `certain` or `uncertain` label.\n   Write each hand-off gap as a sentence naming the shared thing, the affected consumer, the\n   missing lifecycle end, and the smallest amendment.\n7. **Advisory and input findings.**\n8. **Council state.**\n9. **Overrides**, each with its typed reason.\n\nState every meaning in words, never by color alone.\n\nIn both files:\n\n- Label a report-mode `blocked` or `not_checked` result as **diagnostic and not a clearance**.\n- In report mode, state that the result gates no drafting surface: each drafting surface runs\n  its own drafting-mode check before creation.\n- Put `independent: false` at the top, directly after the verdict line, and offer an attended\n  fresh-context rerun.\n\n## Writing the records safely\n\n- Render both files to temporary files first. Replace the real files from the temporary files\n  where the host supports it. Both files must carry the same run identity (`checked_at` and\n  all three final digests), and both describe the same final round.\n- Report a write failure explicitly. A write failure is an **incomplete review**.\n- When a newer attempt fails or is incomplete, **invalidate or remove** any older successful\n  artifact in the output directory. Never leave an older `pass` beside a newer failed outcome.\n  An incomplete newer attempt must not leave an older clearing record in place.\n\n## Return\n\nReport to the caller:\n\n- the verdict and whether the run was independent;\n- the next action;\n- the paths of `epic-coherence.json` and `epic-coherence.md`;\n- for drafting mode, the halt signal (`do not call create_ticket`) when one applies, and the\n  amendments the caller must make before the next round.\n\nDo not describe a `blocked` or `not_checked` report-mode result as a clearance.\n",
+    "review-epic-coherence.md": "# Review Epic Coherence\n\nThis is the shared procedure for checking an epic's children **as a set**. It answers two\nquestions no per-ticket review asks: does every epic acceptance criterion have a child that\ncarries out its verification, and is everything one child produces wired to whatever consumes\nit? Drafting surfaces and the on-demand `/review-epic-coherence` command run this same text.\n\nThe check fails **visibly**. A run that cannot finish is `not_checked`. It is never `pass`.\n\n**Enforcement status.** The three drafting surfaces — `define-tickets`, `plan-epic`, and\n`idea-to-ticket` — call this procedure in drafting mode before creation or approval, and\n`render-ticket-manifest.md` refuses to render an epic without a clearing record. A\nreport-mode result from the on-demand command is a diagnostic, not a gate: it clears nothing.\n\n## What the user sees\n\nEverything this procedure says to a person in attended chat, progress messages, and screens\nuses the plain words in this table, never the internal term. Callers that show a result to a\nperson use the same words.\n\n| Internal concept | User-facing wording |\n|---|---|\n| coherence check | gap check |\n| coverage | a requirement no ticket owns |\n| handoff | a broken hand-off between tickets |\n| fit | a plan that doesn't match the code |\n| e2e_proof | no end-to-end test |\n| `pass` | No gaps found |\n| `accepted_with_gaps` | Accepted with known gaps |\n| `blocked` | Needs your decision |\n| `not_checked` | Couldn't check |\n| foundation blocker | a gap in how the work is split |\n| ticket-local carried finding | a note added to ticket N |\n| `independent: false` | this check ran in my own session, not by a separate reviewer, so it's less independent |\n| coverage map | Who covers each requirement |\n| accept override | Create anyway, and record the gap on the epic |\n| fix | Change how the tickets are split |\n\n- **Qualified pass.** In drafting mode, a passing record that carries ticket-local findings is\n  shown as `No gaps found (N notes added to tickets)`.\n- **Report mode.** A ticket-local finding is described prospectively, as `a note that would be\n  added to ticket N`, and the report says the check changed no ticket.\n- **Scope of the vocabulary.** It covers attended chat, progress messages, and screens only.\n  `epic-coherence.md`, the JSON fields and verdict values in `epic-coherence.json`, the agent\n  name, and the parent ticket's `## Epic coverage map` section keep their technical wording.\n- Write new passages with words such as `ticket N` and angle-bracket paths. Do not add any\n  new brace-wrapped identifier token.\n\n## Inputs\n\nState these four values before starting:\n\n1. **Input document path** — the path to `epic-coherence-input.json`.\n2. **Output directory** — a directory beneath the `docs_dir` that the `ping` tool returned.\n3. **Mode** — `drafting` or `report`.\n4. **Unattended** — true only when `auto_approve_external == \"true\"`. Otherwise the run is\n   attended.\n\nIf any of the four is missing, stop and report which one. Do not guess a default.\n\nAn optional fifth input, **`council_preapproval`**, is kept for backward compatibility. It\ncarries a `value` (`approved` or `declined`) and its `source`. It records a prior decision for\nthe **initial** high-risk council only; see \"Council call\". No current caller supplies it. It\nis not one of the required inputs, so its absence never stops the run. When it is absent, the\nattended high-risk ask in \"Council call\" applies.\n\n## The input document\n\nThe document carries artifacts only. It never carries the drafting conversation.\n\n```json\n{\n  \"epic\": {\n    \"key\": \"EPIC-1\",\n    \"title\": \"Short epic title\",\n    \"acceptance_criteria\": [\n      { \"id\": \"AC-1\", \"text\": \"What must be true\", \"verification\": \"How it is proven\" }\n    ]\n  },\n  \"design_text\": \"Goals and design text: the exploration's Proposed Design, the epic parent body, or equivalent.\",\n  \"manifest\": [\n    {\n      \"id\": \"1\",\n      \"title\": \"Child title\",\n      \"scope\": \"What the child does\",\n      \"size_band\": \"L\",\n      \"depends_on\": [],\n      \"recommended_after\": [],\n      \"touched_files\": [\"path/relative/to/repo.py\"],\n      \"read_files\": [\"path/the/child/only/reads.py\"],\n      \"owns_verifications\": [\n        { \"epic_ac\": \"AC-1\", \"obligation\": \"The concrete part of AC-1's verification this child carries out\" }\n      ]\n    }\n  ],\n  \"child_evidence\": [\n    {\n      \"id\": \"1\",\n      \"acceptance_criteria\": [\"Each acceptance criterion of the child, verbatim\"],\n      \"body\": \"The child ticket body, if available\"\n    }\n  ],\n  \"non_child_owners\": [\n    {\n      \"id\": \"OR-1\",\n      \"kind\": \"owner_run\",\n      \"who\": \"Release owner\",\n      \"step_ref\": \"Release checklist step 6\",\n      \"step_text\": \"Release checklist step 6: the release owner runs the smoke test against production and posts the output as a comment on the epic.\",\n      \"records_result_in\": \"a comment on the epic\",\n      \"owns_verifications\": [\n        { \"epic_ac\": \"AC-2\", \"obligation\": \"Run the production smoke test and post its output on the epic\" }\n      ]\n    }\n  ]\n}\n```\n\nField rules:\n\n- `epic` carries either `key` or `slug` (one is enough), plus `title` and\n  `acceptance_criteria`. Each acceptance criterion has `id`, `text`, and `verification`. When\n  an epic AC has no verification sentence, coverage is judged against its text, the basis is\n  `text_only`, and the reviewer raises an advisory input finding naming the missing sentence.\n- `design_text` is the goals and design text.\n- `manifest` is the **complete, ordered** child list. Each entry carries `id` (a placeholder\n  index or a real ticket key), `title`, `scope`, `size_band`, `depends_on`, and\n  `recommended_after`. These are the same field names `decompose-epic.md` and\n  `decompose-epic-candidate.md` already use.\n- `touched_files` is optional. It lists the files the child **edits or creates**. When absent,\n  the fit check uses the file paths the child's scope and body name. A `touched_files` path that\n  does not exist yet can be a planned creation; that alone is not a problem.\n- `read_files` is optional. It lists files the child **only reads**. It lives in the manifest,\n  so it is hashed. Reads inform the fit check. Only edits (`touched_files`) count toward edit\n  overlap between children and toward the high-risk path check in \"Escalation rule\". A path\n  must not appear in both lists. A `read_files` path that does not exist is an `input` problem,\n  because a child cannot read a file that is not there. When `read_files` is absent, behavior is\n  unchanged.\n- `owns_verifications` is optional. It is a list of entries with `epic_ac` (an epic AC id) and\n  `obligation` (the concrete part of that AC's *verification* this child will carry out, in\n  words a reviewer can hold against the verification sentence). It is a **claim** the reviewer\n  checks. It is never proof by itself. When it is absent (older epics, the on-demand path), the\n  reviewer derives candidate owners from each child's own acceptance criteria, and the record\n  says `owns_verifications_source: derived`. When it is present, the record says `declared`.\n- `child_evidence` is a **separate top-level array**, keyed by child `id`. Each entry may carry\n  `acceptance_criteria` and `body`. It lives **outside** the hashed manifest, so evidence can be\n  refreshed without changing manifest identity. Derived ownership counts only when a child's\n  acceptance criteria contain a concrete commitment to the obligation. When the material needed\n  to establish ownership is absent, that is an explicit `input` gap, not coverage.\n- `non_child_owners` is an optional **top-level array** beside `child_evidence`. It names the\n  owners of epic AC verifications that no child carries out, such as a step in an owner-run\n  release checklist. Each entry has:\n  - `id` — for example `OR-1`. It is unique across the array and never equal to any child `id`.\n  - `kind` — a closed vocabulary with one value: `owner_run`.\n  - `who` — a named person or role, for example \"Release owner\".\n  - `step_ref` — the step it points at, for example \"Release checklist step 6\".\n  - `step_text` — the step's text, copied **verbatim** from `design_text`.\n  - `records_result_in` — where the result is recorded, for example \"a comment on the epic\".\n  - `owns_verifications` — a list of `epic_ac` plus `obligation` entries, the same shape\n    children use.\n\n  `step_text` is copied into the entry on purpose. `design_text` is not hashed, so a step that\n  lived only there could change without changing the review's identity. The copied, hashed\n  `step_text` is the reviewed commitment. An owner-run owner owns **coverage only**: it never\n  fills a hand-off grid cell. When the array is absent, no AC has a non-child owner.\n\n**Local markdown drafts.** When an epic is drafted as local markdown files outside a drafting\nsurface, build this document with the packaged `epic-coherence-input build` subcommand of the\nBridge MCP package: `epic-coherence-input build --outline <outline-path> --out <output-path>`.\nDo not assemble it by hand. The outline names the epic draft, each child's draft, its\ndependencies, size band, `edits` (which become `touched_files`), `reads` (which become\n`read_files`), and `owns_verifications`, plus any `non_child_owners`. Every epic AC bullet in the\nepic draft must start with an explicit id such as `AC-3:`; the builder never numbers ACs by\nposition or matches them by keyword. `epic-coherence-input check <input-path>` validates an\nexisting document against the structural rules in \"Validation\" and prints the three digests. It\nnever judges coverage; that stays the reviewer's job. The three drafting surfaces keep their\nstructured normalization, and the on-demand `/review-epic-coherence` command keeps building its\ninput from ticket data.\n\n## Identities\n\nThree digests identify what was reviewed. All three use the same canonical JSON encoding.\n\n- `manifest_sha256` is the SHA-256 hex digest of\n  `json.dumps(manifest, sort_keys=True, separators=(\",\", \":\"), ensure_ascii=False).encode(\"utf-8\")`,\n  computed over the `manifest` array only. Compute it locally with this one line:\n\n  ```bash\n  python3 -c 'import hashlib,json,sys; manifest=json.load(open(sys.argv[1], encoding=\"utf-8\"))[\"manifest\"]; print(hashlib.sha256(json.dumps(manifest, sort_keys=True, separators=(\",\", \":\"), ensure_ascii=False).encode(\"utf-8\")).hexdigest())' <input-path>\n  ```\n\n- `child_evidence_sha256` is the SHA-256 hex digest of the same encoding applied to the\n  `child_evidence` array (an absent array hashes as an empty array).\n- `non_child_owners_sha256` is the SHA-256 hex digest of the same encoding applied to the\n  `non_child_owners` array. An absent array hashes as an empty array, as `child_evidence`\n  does. Compute it locally with this one line:\n\n  ```bash\n  python3 -c 'import hashlib,json,sys; owners=json.load(open(sys.argv[1], encoding=\"utf-8\")).get(\"non_child_owners\", []); print(hashlib.sha256(json.dumps(owners, sort_keys=True, separators=(\",\", \":\"), ensure_ascii=False).encode(\"utf-8\")).hexdigest())' <input-path>\n  ```\n\nRecord **all three** digests, at the top level and in every round. A caller that wants to\nreuse a prior review must compare **all three** identities against the manifest, evidence,\nand non-child owners it is about to use. A matching manifest with changed evidence or changed\nowners is not the same review. The sibling integration's preflight must compare all three.\n\n`design_text` deliberately stays **outside** identity. The copied and hashed `step_text` is\nthe reviewed commitment of an owner-run step. There is no fourth digest, and no render-time\ncheck that `design_text` still contains the step.\n\n## Validation\n\nBefore any reviewer run, validate the input document. Every problem becomes a visible `input`\nfinding. Nothing is silently dropped.\n\n- Child ids are unique. Epic AC ids are unique. Every `owns_verifications.epic_ac` names a real\n  epic AC, and every `child_evidence.id` names a real manifest child.\n- The document shapes and the key or slug syntax are valid.\n- Every `non_child_owners` entry is well formed. Its `id` is unique across the array and never\n  collides with a child id. Its `kind` is `owner_run`. Its `who`, `step_ref`, `step_text`, and\n  `records_result_in` are non-empty. Every one of its `owns_verifications.epic_ac` values names\n  a real epic AC. A malformed entry, a colliding id, an invalid AC reference, and a missing\n  required field are each a visible `input` finding.\n- Every named file path is repository-relative. Reject absolute paths and any path that\n  traverses upward. A path listed in both `touched_files` and `read_files` of the same child is\n  an `input` finding.\n- The output directory is beneath the `docs_dir` that `ping` resolved. Refuse to write anywhere\n  else.\n- A missing, invalid, or unreadable named file is an `input` finding. So is inaccessible child\n  material and a missing set of epic acceptance criteria. A nonexistent `touched_files` path can\n  be a planned creation and is not, by itself, a finding. A nonexistent `read_files` path is an\n  `input` finding.\n- A missing verification sentence alone is **advisory**. Any problem that prevents a meaningful\n  review (no epic acceptance criteria, an empty manifest, an unreadable input document) makes\n  the verdict `not_checked`. It never produces a complete-looking coverage map.\n\nDescribe variable paths in words or angle brackets, such as `<output-directory>`. Do not write\nany literal brace-wrapped identifier other than `docs_dir`, including in examples.\n\n## Reviewer run\n\nInvoke the `epic-coherence-reviewer` agent in a **fresh context**. Pass it only the input\ndocument path. Run it **once per round over the whole frozen manifest** — never per child and\nnever over a subset. The reviewer must not receive the drafting conversation.\n\nResolve the agent the way `draft-ticket.md` resolves `jira-ticket-writer`: through the Task tool\nor a host equivalent you have confirmed can resolve it. Cursor has no agent mirror for this\nagent, so on Cursor resolution normally fails.\n\n**Fresh-context fallback.** If no fresh context can be obtained, read the agent file\n`agents/src/epic-coherence-reviewer.md` (or its installed mirror) and execute its methodology\ninline. Set `independent: false` in the record and say so in the report. An inline run is never\na silent independent pass.\n\n- In an **attended** run, tell the person in plain words: \"this check ran in my own session, not\n  by a separate reviewer, so it's less independent.\" Offer a fresh-context rerun when one\n  becomes available.\n- In an **unattended drafting** run, an inline `pass` is not the independent gate. Halt.\n\n## Escalation rule\n\nEscalate to a council **only** when at least one of these is true:\n\n1. Any blocking finding has `confidence: uncertain`.\n2. The caller **disputes** a blocking finding instead of amending it. The caller is the drafting\n   agent in drafting mode and the operator in report mode.\n3. The epic is **high risk**.\n\nHigh risk means one of the following. Count **children**, never edited files: a single child\nthat edits ten files under one prefix is still one child.\n\n- The epic has **six or more children**.\n- **One** child's `touched_files` falls under one of these paths. A single editing child is\n  enough:\n  - `db/migrations/` and `db/alembic/` (the design says `db/migrations/`; this repository's\n    migrations live in `db/alembic/`, so match both)\n  - `api/library/billing/`\n  - `api/routes/setup/auth.py`\n  - `api/library/auth/`\n- **Two or more distinct** children each edit under the same kind of path from the list below.\n  One editing child alone does **not** make the epic high risk. This list is every remaining\n  prefix in `_CONTAINMENT_HAZARD_PATHS` in `api/library/github/workflow_planning_prediction.py`\n  (the list also carries `db/alembic/`, which is already a single-trigger path above):\n  `mcp_server/src/executor/`, `mcp_server/src/agent-launchers/`,\n  `mcp_server/src/claude-settings.ts`, `.github/workflows/`,\n  `tests/integration/conductor_harness/`, and `api/library/db/`\n\n| Edits under the path | Risk tier |\n| --- | --- |\n| One child edits `api/library/db/` | low |\n| Two children each edit `api/library/db/` | high |\n| One child edits an executor prefix such as `mcp_server/src/executor/` | low |\n| Two children each edit executor-prefix paths | high |\n| One child edits `db/alembic/`, `api/library/billing/`, or auth paths | high |\n| Six or more children, whatever they edit | high |\n\nOnly edits count. A path a child lists in `read_files` never makes the epic high risk, even\nunder one of these prefixes, so a child that only reads `api/library/db/` does not trigger\nthis rule. Reads do not count toward the two-child threshold either.\n\nA low-risk epic with one child editing `api/library/db/` or an executor prefix still receives\nthe low-risk reviewer rounds in \"Drafting mode\". If a round raises a blocking finding with\n`confidence: uncertain`, the epic is promoted to high risk and the council flow starts. Any\nblocking findings that remain go to the operator at the create gate. This adds no other\nmitigation.\n\nWhen `touched_files` is absent for a child, apply the same path check to the concrete paths its\nscope and body name. When a child's file ownership is unknown, record **uncertainty**. Do not\ndeclare the epic low risk.\n\n**Classify the risk before round 1.** Decide the initial risk tier from the input alone,\nbefore the first reviewer run, using the child count and the edit paths. The tier is `high`\nwhen this rule matches, and also when unknown file ownership leaves the question open. It is\n`low` otherwise. Record it as `risk_tier` with its `risk_reasons`, for example \"Children 1 and 3\nboth edit `api/library/db/`\". Trigger 3 therefore fires **before round 1**. Triggers 1 and 2 still fire\nafter any later round.\n\nAn uncompleted required escalation leaves the result unresolved. It is never a quiet pass.\n\n## Council call\n\nBefore **every** billable council request, state:\n\n- the cost: **26–65 credits and about 15 minutes** (26 credits for standard models, 65 credits\n  for frontier models; state the applicable tier if providers are pinned). The source is\n  `api/library/billing/pricing.py`;\n- the escalation reason (which of the three triggers fired);\n- that council output cannot itself clear a blocker.\n\nAn **attended** run asks the operator to approve before proceeding, using the decision card\nbelow. An **unattended** run states the cost in its output and proceeds. This holds for every\nrequest, including a `mode: general` retry.\n\n**The decision card.** Every attended council offer is one card, shown in this order:\n\n1. A plain-language question ending in `?`, such as \"Would you like several other AI models to\n   review how the work is split before I create the tickets?\"\n2. One sentence saying what a council is: \"a panel of several AI models that each review the\n   plan separately.\" It carries the cost (`26–65 credits`) and `about 15 minutes`, and says\n   the gap check runs either way.\n3. A recommendation, with a reason of one or two sentences grounded in what is uncertain.\n4. Bulleted concrete questions the council would check, each followed by the AI's current\n   answer, or an explicit statement that it is not sure.\n5. Exactly these three options, with `(as recommended)` on the recommended one only:\n\n   ```text\n   1. Yes, run the council\n   2. No, continue without it\n   3. Yes, but change what it checks, or ask me something first\n   ```\n\n**Reading the reply.** Judge the reply by intent, not by exact words. A clear number or a clear\nverbal choice selects that option. An unclear reply authorizes nothing: say what you could not\ntell and show the card again.\n\n- **Option 3 with a new focus.** Echo the revised checklist back in one or two lines, run the\n  council with it, and do not ask again.\n- **Option 3 with a question.** Answer the question first, then show the three options again in\n  a compact form.\n- **A reply that picks an option and also asks to change the split.** The change comes first:\n  amend the manifest, re-freeze it, and start no council from that reply.\n- Added focus never removes a mandatory check, never waives the gap check, and never changes\n  how a record clears.\n\n**When the council starts.**\n\n- **High-risk trigger.** After the epic is classified high risk before round 1, an attended run\n  shows the decision card **before** round 1 starts. It explains the high-risk reason in plain\n  words from `risk_reasons`, for example \"two tickets both change the database layer\", without\n  changing any threshold or classification. The mandatory checks on the card are concurrent\n  writers, migration and rollback order, and rollout that runs ahead of the code, each with the\n  AI's current answer or stated uncertainty. On option 1, or option 3 with a focus, request the\n  council and start the round-1 reviewer run **in parallel**. Do not wait for a later round.\n  - **Decline.** On option 2, request no council. Record `council_id: null` and\n    `council_outcome: \"declined_by_operator\"`, omit `council_preapproval`, and continue the\n    reviewer run. The decline is final and is shown as `Council: skipped, your choice`.\n  - **Legacy input.** If the caller did supply `council_preapproval`, it still works and its\n    `value` and `source` are still recorded. `approved` starts the initial council alongside\n    round 1 after stating the cost, with no further ask. `declined` skips it and records the\n    same `declined_by_operator` outcome.\n  - If the technical request needs the `mode: general` retry, state the cost again, with the\n    disclosure and approval that retry already requires.\n- **Uncertain or disputed trigger.** Request the council after the round that raised the\n  finding. An attended run shows the same decision card with its own cost statement, a\n  recommendation, and questions about that finding, each with the AI's current answer. The task\n  text stays limited to the input document's artifacts and the relevant findings.\n  - **Decline.** On option 2, request no council and append no `councils` entry. The triggering\n    finding keeps its identity, severity, evidence, and blocking status. Keep the finding id in\n    the run state as declined, so no later round offers a council for the same finding again.\n    No new record field is added for this.\n  - A genuinely new qualifying finding may still get an offer, within the limit below.\n- **How many.** One council per drafting run for the initial high-risk trigger. A later\n  qualifying trigger (an uncertain or disputed blocking finding) may start **at most one more**\n  council, with its own cost statement and approval.\n\nCall `request_council` with:\n\n- `mode`: `technical`\n- `wait_for_result`: `false`\n- no `repo_name`\n- task text containing **only** the input document's artifacts and the contested findings.\n  The early high-risk council has no reviewer findings yet, so its task text holds **only** the\n  input document's artifacts. Never invent findings for it. Ask it to look for cross-child and\n  release-level risks, such as concurrent writers, migration and rollback order, and rollout\n  that runs ahead of the code.\n\nThen poll `get_council` for a bounded period. If technical mode cannot run because the\nrepository is not indexed, repeat the request with `mode: general`, and state the cost again\nbefore that request too.\n\n**The amendment freeze.** The round-1 amendment freezes at the moment the caller begins writing\nthe amended input document after collecting the round-1 findings. Poll `get_council` while the\nround-1 reviewer runs. Council conclusions received before the freeze join that **same**\namendment pass. Conclusions received after it join the next pass. A frozen round is never\nchanged after the fact.\n\nCouncil conclusions join the finding list as **separate** findings with `source: council`. The\noriginal reviewer finding is kept unchanged. It is never edited, downgraded, or removed because\na council failed, timed out, is still running, left the dispute unresolved, or concluded.\nRecord the `council_id` and the council outcome. Record still-running and failed outcomes as\nunresolved.\n\n**An unfinished required council.** A required council that is `still_running`, `failed`, or\n`timed_out` when the last round or confirmation pass ends is unresolved. The verdict is never\n`pass`. An **attended** operator, after being shown the council's id, cost, and elapsed time,\nmay accept it with a typed override of kind `accept` that names its `council_id`. An\n**unattended** run records `blocked` and halts before any ticket is created.\n\nA council outcome of `declined_by_operator` is resolved and needs no `accept` override, whether it was declined at the pre-round-1 ask or through legacy `council_preapproval: declined`. A legacy `accept` override targeting `council: \"declined_by_operator\"` remains valid but is ignored for clearance.\n\n**Declining an escalation council.** Declining a council offered for an uncertain or disputed\nfinding resolves the council decision only. The finding itself stays blocking until it is\namended or accepted by its own `finding_id`.\n\n## Drafting mode\n\nDrafting mode is for a drafting surface that can still change the manifest.\n\n- **Attended progress.** After every completed reviewer round, an attended run says one short\n  line with the number of gaps in how the work is split that still need a decision. Use the\n  real ordinary-round ceiling for this epic (the low-risk or the high-risk limit below), for\n  example: `Gap check, round 1 of up to 3: 2 gaps need a decision.` A confirmation pass is\n  named as a confirmation pass. It is never counted as an extra ordinary round. Unattended runs\n  print no such line.\n- **Amend and recheck.** The reviewer only describes amendments. The **caller** amends the\n  manifest (adds or rescopes children), re-freezes it, and writes a **new** input document. The\n  procedure then reruns the reviewer in a fresh context. Record each round with its own\n  `manifest_sha256`, `child_evidence_sha256`, and `non_child_owners_sha256`, blocking and\n  advisory counts, whether a council ran, and whether it was a confirmation pass.\n- **Foundation readiness and carry.** A round with zero foundation blockers is ready and exits the ordinary loop immediately. Carry unresolved ticket-local blockers without amending or rechecking merely because they remain. `pass` requires zero unresolved foundation blockers and may retain carried ticket-local findings; `accepted_with_gaps` is reserved for accepted remaining foundation blockers.\n- **Risk-scaled round limit.** The number of ordinary reviewer runs, `round_limit`, depends on\n  the risk tier from \"Escalation rule\":\n  - **Low risk** (the epic is not high risk and no blocking finding is `uncertain`):\n    `round_limit` is **2**. These are maximum ordinary rounds; exit earlier when a round has zero foundation blockers.\n    That is at most **2 reviewer runs**.\n  - **High risk**: `round_limit` is **3**. Allow at most **2 re-checks**, which is\n    **3 reviewer runs in total**, with the same zero-foundation early exit.\n  - **Promotion.** A low-risk epic whose round produces a blocking finding with\n    `confidence: uncertain` becomes high risk from that point. It gets the high-risk limit, and\n    trigger 1 fires. Promotion raises the ceiling to three total ordinary rounds, including rounds already completed.\n\n  If a round with foundation blockers has a foundation count greater than or equal to the preceding round's count, stop automatic looping with `non_convergence`; route attended findings to the create gate or halt unattended as `blocked`.\n\n  Record the final `risk_tier`, `risk_reasons`, and `round_limit`. A confirmation pass is not an\n  ordinary run and does not count toward `round_limit`.\n- **Confirmation pass.** Run a confirmation only after a caller amendment targeting foundation findings and when the ordinary-round rule calls for it. Derive `confirmation_passes_used` from `rounds[].confirmation`; the budget is two attended passes or one unattended pass, and refuse another at the budget.\n\n  When the caller changes the input after the last allowed ordinary\n  round, run **one confirmation pass**. It is a fresh-context reviewer run over the **whole**\n  amended manifest, never a subset. Its requested focus is narrower: the amended children, the\n  hand-offs they touch, and whether the findings the amendment targeted are closed. It must\n  still report **any** blocking finding it observes anywhere in the manifest; the narrower\n  focus never suppresses one. When it cannot establish where an amendment's impact ends, it\n  raises that as a blocking finding with `confidence: uncertain` instead of calling the\n  amendment confirmed. Record it in `rounds[]` with `\"confirmation\": true`.\n  - A confirmation pass **never** starts another automatic amendment loop. A new blocking\n    finding goes to attended fix-or-accept, or to the unattended halt.\n  - In an **attended** run, after the first confirmation pass, the operator may direct **at\n    most one** fix of a confirmation blocker. Then run **one** further whole-manifest\n    confirmation pass, so the last round bears the final digests. That is the whole budget\n    across re-runs in the same attended `define-tickets` run.\n  - Once that budget is spent, a remaining blocker is accepted with a non-empty reason or stays\n    `blocked`. Do not add an \"unconfirmed fixed\" state, and do not start another automatic\n    amendment loop. A typed acceptance stays available instead of the fix at any point.\n- **Final identity.** The top-level `manifest_sha256`, `child_evidence_sha256`, and\n  `non_child_owners_sha256` equal the digests of the **last** entry in `rounds[]`. A record\n  whose top-level digests no round saw does not clear. The sole exception is a confirmation\n  pass that cannot run: an **attended** operator may record `amended_after_final_round: true`\n  with an override of kind `bypass` carrying a typed reason. The verdict is then\n  `not_checked`, never `pass` or `accepted_with_gaps`, and the top-level digests still describe\n  the amended input. An **unattended** run halts instead.\n- **Attended resolution.** After the bound, each remaining **foundation** blocking finding must be\n  fixed within the same one-fix, one-further-confirmation-pass budget, or accepted with a non-empty reason.\n  Ticket-local blockers are carried to their child ticket; they do not require a foundation amendment\n  or acceptance to clear the epic record.\n  The reason may be typed by the operator or drafted by the agent and shown at the create gate\n  where that gate applies. An accepted finding is an override with `kind: accept`, plus\n  `finding_id`, `reason`, `accepted_by`, and `round`. Declining a foundation finding keeps the verdict `blocked`.\n  When **every** remaining foundation blocking finding is accepted, the verdict is `accepted_with_gaps`.\n- **Unattended halt.** If any foundation blocking finding remains after the bound, the verdict is\n  `blocked`. Return an explicit halt signal: **do not call `create_ticket`**. The caller must\n  stop.\n\n## When the review cannot run\n\nIf the reviewer cannot run (a tool error, a timeout, or a host that lacks the capability while\ninline execution also fails), or the material prevents a meaningful review, the verdict is\n`not_checked`. It is never `pass`.\n\n- **Attended:** tell the person \"Couldn't check\", then offer a retry, or a bypass with a typed\n  reason. A bypass is recorded as an override with `kind: bypass`. The verdict stays\n  `not_checked`.\n- **Unattended:** halt.\n\n## Report mode\n\nReport mode is diagnostic. It runs the reviewer **once**. There is no amendment loop and no halt\nsignal. Escalation still applies, with the cost stated and confirmation asked. It splits blocking counts and the verdict by scope: ticket-local blockers are labelled “would be carried into child N”, are not carried, and edit no ticket. The verdict is `pass`, `blocked`, or `not_checked` from foundation blockers only.\n\nA `blocked` or `not_checked` report is **diagnostic and not a clearance**.\n\nWhen showing a report-mode result to a person, use the words in \"What the user sees\". Describe\neach ticket-local finding as `a note that would be added to ticket N`, keep the result\ndiagnostic rather than clearing, and say plainly that the check changed no ticket.\n\n## The record: epic-coherence.json\n\nWrite `epic-coherence.json` into the output directory:\n\n```json\n{\n  \"schema_version\": 3,\n  \"checked_at\": \"2026-01-01T00:00:00Z\",\n  \"mode\": \"drafting\",\n  \"unattended\": false,\n  \"manifest_sha256\": \"<64 hex characters, or null>\",\n  \"child_evidence_sha256\": \"<64 hex characters, or null>\",\n  \"non_child_owners_sha256\": \"<64 hex characters, or null>\",\n  \"owns_verifications_source\": \"declared\",\n  \"verdict\": \"pass\",\n  \"independent\": true,\n  \"risk_tier\": \"low\",\n  \"risk_reasons\": [\"Three children; no child edits a high-risk path\"],\n  \"round_limit\": 2,\n  \"confirmation_passes_used\": 0,\n  \"confirmation_budget\": 2,\n  \"stop_reason\": \"ready\",\n  \"carried_ticket_local\": [],\n  \"amended_after_final_round\": false,\n  \"rounds\": [\n    {\n      \"manifest_sha256\": \"<64 hex characters>\",\n      \"child_evidence_sha256\": \"<64 hex characters>\",\n      \"non_child_owners_sha256\": \"<64 hex characters>\",\n      \"blocking_count\": 0,\n      \"foundation_blocking_count\": 0,\n      \"ticket_local_blocking_count\": 0,\n      \"findings_snapshot\": [],\n      \"advisory_count\": 0,\n      \"council_ran\": false,\n      \"confirmation\": false\n    }\n  ],\n  \"owner_run_acs\": [\"AC-2\"],\n  \"coverage_map\": [\n    {\n      \"epic_ac\": \"AC-1\",\n      \"judgment_basis\": \"verification\",\n      \"status\": \"covered\",\n      \"owners\": [\n        {\n          \"owner_kind\": \"child\",\n          \"child\": \"1\",\n          \"obligation\": \"Concrete obligation\",\n          \"child_ac\": \"The child AC id or a quoted child AC\",\n          \"source\": \"declared\"\n        }\n      ]\n    },\n    {\n      \"epic_ac\": \"AC-2\",\n      \"judgment_basis\": \"verification\",\n      \"status\": \"covered\",\n      \"owners\": [\n        {\n          \"owner_kind\": \"owner_run\",\n          \"child\": null,\n          \"owner\": \"OR-1\",\n          \"who\": \"Release owner\",\n          \"step_ref\": \"Release checklist step 6\",\n          \"records_result_in\": \"a comment on the epic\",\n          \"obligation\": \"Run the production smoke test and post its output on the epic\",\n          \"source\": \"declared\"\n        }\n      ]\n    }\n  ],\n  \"handoff_grid\": [\n    {\n      \"thing\": \"The stored field, endpoint, flag, event, job payload, or scope\",\n      \"consumer\": \"The consuming piece\",\n      \"write_path\": \"child id or null\",\n      \"read_path\": \"child id or null\",\n      \"caller\": \"child id or null\",\n      \"start\": \"child id or null\",\n      \"steady_state\": \"child id or null\",\n      \"wind_down\": \"child id or null\"\n    }\n  ],\n  \"findings\": [\n    {\n      \"id\": \"F-1\",\n      \"kind\": \"coverage\",\n      \"severity\": \"blocking\",\n      \"confidence\": \"certain\",\n      \"concerns\": \"AC-1\",\n      \"evidence\": \"What was observed, with file and line where code was read\",\n      \"smallest_amendment\": \"The smallest change that would close it\",\n      \"source\": \"reviewer\", \"scope\": \"foundation\"\n    }\n  ],\n  \"overrides\": [\n    { \"kind\": \"accept\", \"finding_id\": \"F-1\", \"reason\": \"Typed reason\", \"accepted_by\": \"Operator\", \"round\": 3 }\n  ],\n  \"council_preapproval\": { \"value\": \"approved\", \"source\": \"legacy caller input\" },\n  \"council_id\": null,\n  \"council_outcome\": \"not_run\",\n  \"councils\": []\n}\n```\n\nRules:\n\n- `schema_version` is `3`. Readers also accept versions `1` and `2`; interpret every legacy blocking finding as `foundation`.\n- In version 3, validate every blocking finding's closed `scope` and every `ticket_local` child against the final manifest before counting, clearing, or carrying. Invalid or orphaned ownership fails closed; reclassify an ambiguously owned former carry as foundation explicitly.\n- `blocking_count` is the sum of `foundation_blocking_count` and `ticket_local_blocking_count`; count every blocking finding regardless of confidence.\n- `pass` requires zero unresolved foundation blockers.\n- `carried_ticket_local` holds one unresolved entry per stable identity with its finding id, child id, evidence, and smallest amendment. Preserve the latest snapshot and close an identity only when a later review explicitly establishes correction or supersession.\n- `stop_reason` is one of `ready`, `round_limit`, `non_convergence`, or `confirmation_budget_spent`.\n- `verdict` is one of `pass`, `accepted_with_gaps`, `blocked`, `not_checked`.\n- A `pass` with `independent: false` is allowed but flagged prominently in both files.\n- An `accept` override accepts a known gap. A `bypass` override skips a review that could not\n  run. Keep the two distinct.\n- `kind` on a finding is one of `coverage`, `handoff`, `fit`, `e2e_proof`, `input`.\n  `severity` is `blocking` or `advisory`. `confidence` is `certain` or `uncertain`. `source`\n  is `reviewer` or `council`.\n- Digests may be `null` **only** when unreadable input makes computing them impossible. Then\n  add an explicit `input` finding and set the verdict to `not_checked`.\n- The top-level digests equal the last round's digests. The only record allowed to differ is\n  an attended one with `amended_after_final_round: true`, a `bypass` override with a typed\n  reason, and verdict `not_checked` (see \"Drafting mode\").\n- `rounds[].confirmation` is `true` only for a confirmation pass. `risk_tier` is `low` or\n  `high`, `risk_reasons` lists why, and `round_limit` is the ordinary-run limit that applied\n  (`2` or `3`; report mode runs once).\n- Each coverage owner carries `owner_kind`, which is `child` or `owner_run`. A child owner\n  carries `child`, `obligation`, `child_ac`, and `source`. An owner-run owner carries\n  `child: null`, `owner` (its `non_child_owners` id), `who`, `step_ref`, `records_result_in`,\n  `obligation`, and `source: declared`.\n- `owner_run_acs` lists the id of every epic AC with at least one owner-run owner. It is empty\n  when there are none. Owner-run coverage is always visible, never silently passed.\n- `council_id` is `null` when no council ran. `council_outcome` is one of `not_run`,\n  `concluded`, `failed`, `timed_out`, `still_running`, or `declined_by_operator`. These two fields describe the first\n  council. When a second council runs, `councils` lists **every** council in order, each with\n  `council_id`, `trigger` (`uncertain`, `disputed`, or `high_risk`), and `outcome`. An override\n  that accepts an unfinished council carries `council_id` in place of `finding_id`.\n  An initial council declined at the pre-round-1 ask, or through legacy `council_preapproval`,\n  is stored in `council_outcome` as `declined_by_operator` with `council_id: null`, and is\n  retained there when a later council also needs an entry in `councils`. It needs no override.\n  Older records may carry an override with `council: \"declined_by_operator\"` in place of\n  `finding_id` or `council_id`; it stays valid and is ignored for clearance.\n- `council_preapproval` is present only when a legacy caller supplied it. It persists its\n  `value` and `source`, and the record omits the field otherwise, including after an attended\n  decline at the pre-round-1 ask.\n- Unknown fields, such as a historical `council_note`, are outside this schema. Readers ignore\n  them. They never authorize clearance.\n- A `not_checked` record must **never** carry a coverage map that looks complete. Leave the map\n  empty, or mark every entry as not assessed.\n- Keep this schema in this file. Do not copy it into the ticket-authoring posture block.\n\n## The record: epic-coherence.md\n\nWrite `epic-coherence.md` into the same directory as a short human summary. Use **no tables**.\nIn this order:\n\n1. The **verdict**, as the very first line of the file (after the title heading). Nothing else comes\n   before it.\n2. **Independent: yes** or **Independent: no**, prominently, on the line directly after the\n   verdict, then the **next action**.\n3. The round count, the risk tier, and the round limit. Say which round, if any, was a\n   confirmation pass.\n4. Directly after the round count, one line: \"Owner-run coverage: N of M epic ACs depend on\n   steps a person runs outside the Epic Implementer.\"\n5. One **bullet per epic AC**: its id, the judgment basis (`verification` or `text only`), the\n   status, the owning child or the absence of one, the obligation, and the cited child AC\n   evidence. Mark derived ownership as derived. For an owner-run owner, say \"owner-run\" in\n   words, with the person or role, the step reference, and where the result is recorded, for\n   example: AC-4: covered, owner-run (Release owner, checklist step 5; result recorded in an\n   epic comment).\n6. **Blocking findings**, each labelled `blocking` with its `certain` or `uncertain` label.\n   Write each hand-off gap as a sentence naming the shared thing, the affected consumer, the\n   missing lifecycle end, and the smallest amendment.\n7. **Advisory and input findings.**\n8. **Council state.**\n9. **Overrides**, each with its typed reason.\n\nState every meaning in words, never by color alone.\n\nIn both files:\n\n- Label a report-mode `blocked` or `not_checked` result as **diagnostic and not a clearance**.\n- In report mode, state that the result gates no drafting surface: each drafting surface runs\n  its own drafting-mode check before creation.\n- Put `independent: false` at the top, directly after the verdict line, and offer an attended\n  fresh-context rerun.\n\n## Writing the records safely\n\n- Render both files to temporary files first. Replace the real files from the temporary files\n  where the host supports it. Both files must carry the same run identity (`checked_at` and\n  all three final digests), and both describe the same final round.\n- Report a write failure explicitly. A write failure is an **incomplete review**.\n- When a newer attempt fails or is incomplete, **invalidate or remove** any older successful\n  artifact in the output directory. Never leave an older `pass` beside a newer failed outcome.\n  An incomplete newer attempt must not leave an older clearing record in place.\n\n## Return\n\nReport to the caller:\n\n- the verdict and whether the run was independent;\n- the next action;\n- the paths of `epic-coherence.json` and `epic-coherence.md`;\n- for drafting mode, the halt signal (`do not call create_ticket`) when one applies, and the\n  amendments the caller must make before the next round.\n\nDo not describe a `blocked` or `not_checked` report-mode result as a clearance.\n",
     "screen-and-resolve.md": "Apply project standards and the minimum-evidence gate before drafting.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n- Research pack: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/research-pack.md` / `.json` (may be partial or absent).\n- Duplicate assessment: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/duplicate-assessment.json`.\n- Project standards: the response from the earlier `get_project_standards` step in the same pipeline run. Treat the standards as unavailable when that response was an error envelope, a 404, missing, or contains the onboarding placeholder sentence \"No project standards are configured yet for\" (a 200 response body that is telling the reader how to get standards, not standards content — it can appear alone or appended after a populated `## Project Context` section).\n\n## Instructions\n\n1. Produce three artifacts in the run directory:\n   - `{docs_dir}/idea-to-ticket/{slug}-{run_id}/standards-checklist.json`\n   - `{docs_dir}/idea-to-ticket/{slug}-{run_id}/open-questions.md`\n   - `{docs_dir}/idea-to-ticket/{slug}-{run_id}/resolved-uncertainties.md`\n\n2. Standards checklist:\n   - When `get_project_standards` returned a usable result — real standards content, not the onboarding placeholder — derive the checklist items from those standards. Each item is a `{requirement, satisfied, evidence}` triple where `evidence` either cites the research pack or notes \"deferred to draft\".\n   - When standards are unavailable (404, error envelope, missing, or the onboarding placeholder), generate a fallback baseline checklist covering at least: requirements clarity, acceptance criteria presence, testability, security/PII consideration, and rollback/observability when scope warrants it. Mark each as `satisfied: false` with `evidence: \"fallback baseline — no project standards available\"`.\n\n3. Open questions:\n   - List every unresolved unknown that blocks drafting. Pull from the research pack's `unresolved_unknowns` and from your own reading of `idea`.\n   - Each question gets its own bullet (no markdown tables, no `- [ ]` checkboxes — BAPI-320 hygiene).\n   - If the question has a defensible best-guess answer, write it in `resolved-uncertainties.md` instead, with explicit assumption language (\"Assuming X because Y...\").\n\n4. Resolved uncertainties:\n   - Mirror open questions that have defensible best-guess answers. Each entry must include `assumption`, `basis` (research-pack reference or codebase reference), and `confidence` (\"low\", \"medium\", \"high\").\n\n5. Minimum-evidence gate. Halt locally if ALL of the following are true:\n   - The research pack contains no codebase references for the idea.\n   - The standards checklist has zero items (even the fallback baseline is missing).\n   - `resolved-uncertainties.md` records no explicit assumptions.\n   When the gate fires, do not continue to drafting. Report the halt and direct the user to either run a smaller idea, run `--allow-duplicate` semantics for replays, or supply more context manually.\n\n## Return\n\nConfirm the three artifacts were written and whether the minimum-evidence gate fired.\n",
     "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\n## Return\n\nConfirm the rewritten ticket was saved to `{docs_dir}/tickets/{ticket_key}.md` and briefly note which clarifying-question answers were corrected against the codebase and which critique Requested Changes were addressed.\n",
-    "upload-and-track.md": "Step-10 umbrella upload instruction. Idempotently create the Jira ticket(s) for this run, attach the full draft(s), and call `track_ticket`.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n- Draft metadata: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/draft-metadata.json`.\n- For epic runs, this instruction is also responsible for producing or refreshing `{docs_dir}/idea-to-ticket/{slug}-{run_id}/decomposition-plan.json` before any Jira mutation, by following `decompose-epic-candidate.md` (hard cap `{max_children}`), and for the epic coherence record `epic-coherence.json` beside it, produced by `review-epic-coherence.md`.\n- Pipeline variable `auto_approve_external` controls whether the external-mutation pause is skipped (for this run, `auto_approve_external` = `{auto_approve_external}`). Treat the literal string `\"true\"` as skip; any other value (including `\"false\"`, missing, or empty) means pause and ask.\n\n## Instructions\n\n> **Orchestrator-directed step.** This agent task is part of the full-automation chain and is authorized to call `get_tickets`, `create_ticket`, `attachment` (operations: `upload`, `list`), `update_ticket_description`, `track_ticket`, and `add_comment`, and to execute the shared `gather-and-attach-materials.md` instruction, as directed below — performing orchestrator-directed tool calls is not \"re-orchestrating\".\n\n1. Read `run-manifest.json` and `draft-metadata.json`. Branch internally based on the manifest's `scope`:\n   - `task` or `spike` → follow the **Single-ticket path** below.\n   - `epic_candidate` → follow the **Epic path** below.\n   The orchestrator does not support conditional steps; this branching lives in agent logic.\n\n2. External approval gate, applied before any mutating MCP tool call. On the Epic path it applies **after** step 4.1 has frozen the decomposition and run the epic coherence check, and after step 4.2 has rendered the drafts — so the confirmation shows the verdict — but still before any mutating call. On the Single-ticket path it applies before step 3's first mutating call, as before.\n   - If `auto_approve_external` is `\"false\"` (or any non-`\"true\"` value), summarize the exact planned Jira mutations — list every `create_ticket`, `attachment` (operation: `\"upload\"`), and `track_ticket` call with its key arguments — and ask the user for explicit confirmation in this agent task before proceeding. On the Epic path, lead that summary with the coherence result from step 4.1: the exact verdict, `Independent: no` when the record says so, each remaining blocking finding or the reviewer failure, one compact coverage bullet per epic AC (AC id, owning child — or \"owner-run\" with the person or role and the step reference — and obligation), and every override with its reason.\n   - If `auto_approve_external` is `\"true\"`, proceed without the confirmation pause.\n\n3. **Single-ticket path** (`scope` is `task` or `spike`):\n\n   This path runs **no epic coherence check**: no reviewer call, no record, no render preflight, and no extra prompt. The residual risk — work that really needed a set-level check — is contained by the existing gates: the scope decided before this step and the writer-drafted body. An attended operator who sees that the work is really epic-shaped should stop at the step 2 confirmation and re-run it as an epic.\n\n   1. Idempotency lookup. Call `get_tickets` with its `labels` parameter set to both the per-run label `<idempotency_label>` and the stable `bapi-idea-hash-{idea_hash}` label from `draft-metadata.json` (comma-separated). If a match is found by either label, reuse that ticket key and skip `create_ticket`.\n   2. If no match was found, call `create_ticket` with `summary`, `slim_description` as the description, `issue_type`, and `labels` exactly as written in the metadata. Capture the returned `ticket_key`.\n\n      **Pass `slim_description` through unchanged.** On a `spike` ticket it carries the canonical `<!-- bridge:execution-class=investigation -->` marker line, and this call is the only path by which that marker reaches the persisted ticket record. Translating the metadata into the create call must not strip, reconstruct, re-render, normalize, duplicate, or relocate the marker, and must not move it into the attachment instead. Do not validate it either: this step is not a marker validator, and selection and stamping are the writer's and the drafting step's job. Copy the value; do not edit it. `create_ticket` takes no execution-class parameter and none is added — the marker travels in `description` and nowhere else.\n   3. Upload the full markdown draft via `attachment` (operation: `\"upload\"`) using `attachment_path`.\n   4. **Gather and attach referenced materials.** Execute the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the resolved ticket key, `draft_file_path` = `attachment_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value. It attaches phase-eligible local materials (Planning Assets, Downloadable Assets, and Planning & Downloadable Assets) and records external/auth-gated and binary/image materials per its own warn-not-halt rules. Any attach failure it reports is recorded (via `update_ticket_description`) as `partial_success` and never halts this step.\n   5. Call `track_ticket` with the resolved ticket key so Bridge API picks the new ticket up.\n   6. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/upload-state.json` describing the final state.\n\n4. **Epic path** (`scope` is `epic_candidate`):\n   1. If `decomposition-plan.json` does not yet exist for this run, follow `decompose-epic-candidate.md` first to produce it (hard cap `{max_children}`). If it **does** already exist, it is the approved manifest and this step performs **no fresh decomposition** — read it and use it as written. Decomposition happens once; re-deriving the split immediately before upload is how children end up overlapping or contradicting the parent they are about to be created under.\n\n      **Then run the epic coherence check, before rendering and before the step 2 approval gate.** Every Epic-path run does this; the Single-ticket path never does.\n      - **Normalize the input.** Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/epic-coherence-input.json` in the input document shape `review-epic-coherence.md` defines, built from the **complete, ordered** `children` array of `decomposition-plan.json` and nothing else. `epic` carries the `slug`, the parent summary, and the Epic parent draft's acceptance criteria, each with an `id`, its text, and its verification sentence. `design_text` is the parent draft's summary and requirements plus the System Goals from `goals-and-nfrs.md`. Each `manifest` entry maps one child: `id` is its 1-based index as a string, `title` is its `summary`, `scope` is its `rationale`, `size_band` is the band named in the rationale's size estimate, and `depends_on`, `recommended_after`, and `owns_verifications` are copied unchanged. Each `child_evidence` entry carries that child's planned `acceptance_criteria`, which include its `owns_verifications` obligations verbatim. When `decomposition-plan.json` has a plan-level `non_child_owners` array, copy it **unchanged** into the input's top-level `non_child_owners`; a child's `owns_verifications` keeps only that child's own obligations.\n      - **Run the shared procedure.** Follow `review-epic-coherence.md` in `drafting` mode, with that input path, the run directory as the output directory, and unattended exactly when `auto_approve_external` is the literal `\"true\"`. It computes `manifest_sha256`, `child_evidence_sha256`, and `non_child_owners_sha256` and writes `epic-coherence.json` and `epic-coherence.md` into the run directory. Read the procedure at `docs/install/review-epic-coherence-procedure.md` in this project, where the Bridge installer scaffolds it; if it is not there but `mcp_server/instructions/review-epic-coherence.md` exists in this checkout, read that instead. If neither exists, stop: the shared procedure is not installed, so re-run the Bridge installer or upgrade the Bridge package. Never improvise a substitute review.\n      - **Reuse or resume.** When `decomposition-plan.json` already existed, recompute **all three** digests from it and re-run the check when the record is absent, stale (any digest differs, or its top-level digests differ from its last round's), or not clearing. When tickets for this run already exist and a changed split or changed evidence would need reconciling against them, stop and ask the operator; never apply a changed split to tickets that already exist.\n      - **Amendments.** The reviewer only describes amendments. To make one, repeat `decompose-epic-candidate.md` with each remaining finding's `smallest_amendment` as extra input. That writes a **new** `decomposition-plan.json` with a new identity. Rewrite the input and let the procedure re-check. A record for the old manifest can never clear the new one. The bound is the procedure's risk-scaled round limit. An amendment made after the last allowed round goes through the procedure's one confirmation pass, or, attended only, its narrow `amended_after_final_round` bypass with verdict `not_checked`; it is never presented as covered by an older round.\n      - **Attended** (`auto_approve_external` is not the literal `\"true\"`): show the verdict, each remaining foundation blocking finding, carried ticket-local finding, or reviewer failure, the coverage bullets, and any overrides. Each remaining foundation blocking finding must be fixed (an amendment as above, re-frozen and re-checked) or accepted with a reason the operator types, recorded as an override of kind `accept`. Ticket-local blockers are carried to their child ticket and do not require an epic-level acceptance. When the reviewer is unavailable, the verdict is `not_checked`: offer a retry, or a bypass with an operator-typed reason recorded as an override of kind `bypass`. `not_checked` is never shown or treated as a pass. The step 2 confirmation shows the same result again.\n      - **Unattended** (`auto_approve_external` is the literal `\"true\"`, which covers `--auto` and `/idea-to-pr`): amend and re-check within the procedure's risk-scaled round limit. If any foundation blocking finding remains, halt with verdict `blocked`; carried ticket-local blockers continue into their child ticket. A foundation blocking finding from a confirmation pass, or a required council left unresolved, halts the same way. If the reviewer is unavailable, halt with verdict `not_checked`. If the record says `independent: false`, halt too — an inline check is not independent clearance. **Unattended runs have no bypass.** A halt happens before rendering and before any `create_ticket`; report it with the coherence halt payload in `## Return`.\n   2. Render bodies against the frozen manifest by following `render-ticket-manifest.md`: one `jira-ticket-writer` invocation per entry that lacks a draft on disk, each bound to its own entry's fixed boundary and size band, using the `draft_path` from the decomposition plan. A rendering invocation may not re-split, merge, reorder, renumber, or rescope. Its preflight is fail-closed — an unapproved manifest, a changed manifest identity, an XL epic child, a missing writer draft, or an epic coherence record that is missing, stale, or not clearing stops the flow **before** any Jira mutation. After drafting, extend `draft-metadata.json` so `children[]` mirrors the final list from the decomposition plan.\n\n      After clearance, bring the drafts in line with the reviewed manifest. Re-render the Epic parent draft through `jira-ticket-writer`, passing the record's coverage map (including its owner-run owners), exact verdict, and override reasons, so it carries a `## Epic coverage map` section; then refresh the parent's entry in `draft-metadata.json`. Delete any child draft whose manifest entry changed during an amendment, so it is rendered again against the reviewed manifest. Each child invocation receives that child's `owns_verifications` verbatim, and never an owner-run obligation.\n   3. Create only from writer-produced drafts. Every ticket body uploaded below came from `jira-ticket-writer`; nothing here composes a description inline.\n   4. Parent first. Look up the Epic parent by `bapi-idea-to-ticket-{run_id}-parent` via `get_tickets`. If found, reuse that key; otherwise call `create_ticket` with the parent's summary, slim description, issue type `Epic`, and parent labels. Attach the Epic draft via `attachment` (operation: `\"upload\"`) using `parent.attachment_path`. Then **gather and attach the Epic parent's referenced materials** by executing the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the Epic key, `draft_file_path` = `parent.attachment_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value. Then call `track_ticket` for the Epic key.\n   5. Children next. For each child in order:\n      - Look up by the child's `idempotency_label`. If found, reuse that key.\n      - Otherwise call `create_ticket(parent_key=<epic_key>)` with the child's `summary`, `slim_description`, `issue_type`, and `labels`. The `parent_key` is required so Jira's modern parent linkage is set.\n      - Upload the child draft via `attachment` (operation: `\"upload\"`) using `draft_path`.\n      - **Gather and attach this child's referenced materials** by executing the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the child key, `draft_file_path` = `draft_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value.\n      - Call `track_ticket` for the child key.\n   6. After every parent or child mutation, write partial progress to `{docs_dir}/idea-to-ticket/{slug}-{run_id}/upload-state.json` so a later resume can pick up exactly where the run stopped.\n   7. **Recommended implementation order comment.** Once the Epic parent and all surviving children exist (real keys known), post a single comment on the Epic via `add_comment` with `ticket_number` set to the Epic key. The comment carries (a) a short System Goals / Non-Functional Requirements summary from `goals-and-nfrs.md`, and (b) the **Recommended Implementation Order** — the children in order, each referenced by its real Jira key, derived from the `depends_on` / `recommended_after` / `order_rationale` fields in `decomposition-plan.json`. State that this is recommended sequencing only — do **not** create Jira dependency links and do **not** attach a separate markdown doc. Skip this only if the run reused a pre-existing comment for the same run (idempotency); do not post duplicate order comments on resume.\n\n5. Required child label set whenever any child is created: `ai-generated`, `idea-to-ticket`, `idea-to-ticket-child`, and `bapi-idea-to-ticket-{run_id}-child-<N>` (1-based index from the decomposition plan).\n\n6. Partial-failure recovery rules:\n   - If `create_ticket` succeeds but `attachment` (operation: `\"upload\"`) fails, record the outcome as `partial_success` in `upload-state.json` and continue with the next planned mutation; do not retry inside this step.\n   - If the Epic parent is created successfully but one or more children fail, preserve the parent key and any completed child keys in `upload-state.json` before raising the failure.\n   - On resume of any prior run, search by every relevant idempotency label first (`bapi-idea-to-ticket-{run_id}` for single tickets, `bapi-idea-to-ticket-{run_id}-parent`, and each `bapi-idea-to-ticket-{run_id}-child-<N>`) before considering any `create_ticket` call. Idempotency labels are how this pipeline avoids creating duplicate tickets across retries.\n   - That label-based idempotency is pre-existing and Jira-only; against the local ticket backend label lookups are unsupported. The epic coherence check does not depend on it and adds no label or label lookup: its state lives only in files in the run directory.\n\n## Return\n\nConfirm the run's final upload outcome: attachment results, `track_ticket` outcome, and any `partial_success` rows recorded in `upload-state.json`.\n\nThen, as the FINAL content of your reply, emit a fenced ```json block holding the authoritative payload for this run — and nothing else. The chain reads ONLY this final fenced JSON block to pick its review / start-tickets targets, so it must contain exactly the keys from `upload-state.json` and never any key you merely looked up during duplicate detection. Duplicate-detection / looked-up keys must not appear in this authoritative payload unless they are the final created/reused ticket for this run.\n\nThere are exactly three authoritative final payload shapes: two for a run that created or reused tickets, and one for an epic run that halted on the coherence check before creating anything.\n\n- **Single-ticket path** (`scope` is `task` or `spike`): emit strictly `created_ticket_keys` containing **exactly one** implementable ticket key. `created_ticket_keys` is only for the single-ticket `task`/`spike` path and must contain exactly one implementable ticket key:\n\n  ```json\n  {\"created_ticket_keys\": [\"BAPI-331\"]}\n  ```\n\n- **Epic path** (`scope` is `epic_candidate`): emit the Epic parent key separately as `epic_parent_key`, and the implementable children as `child_ticket_keys`:\n\n  ```json\n  {\"epic_parent_key\": \"BAPI-400\", \"child_ticket_keys\": [\"BAPI-401\", \"BAPI-402\"]}\n  ```\n\n  `child_ticket_keys` contains **only** implementable child Task/Spike ticket keys, listed in final decomposition order. `child_ticket_keys` must **never** include the Epic parent key.\n\n- **Epic coherence halt** (`scope` is `epic_candidate`, and the unattended check halted before any `create_ticket`): first, in prose, name the remaining foundation blocking findings or the reviewer failure, and tell the operator to rerun `/idea-to-ticket` without `--auto` to amend, retry, or explicitly accept the findings. Then emit exactly these four keys and no others:\n\n  ```json\n  {\"halted\": true, \"halt_reason\": \"epic_coherence\", \"coherence_verdict\": \"blocked\", \"coherence_record\": \"<path to epic-coherence.json>\"}\n  ```\n\n  `coherence_verdict` is `blocked`, or `not_checked` when the reviewer was unavailable or the check was not independent. The halt payload never carries `epic_parent_key`, `child_ticket_keys`, `created_ticket_keys`, or a findings array — nothing was created, so a halt can never look like a successful epic payload.\n",
+    "upload-and-track.md": "Step-10 umbrella upload instruction. Idempotently create the Jira ticket(s) for this run, attach the full draft(s), and call `track_ticket`.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`.\n- Draft metadata: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/draft-metadata.json`.\n- For epic runs, this instruction is also responsible for producing or refreshing `{docs_dir}/idea-to-ticket/{slug}-{run_id}/decomposition-plan.json` before any Jira mutation, by following `decompose-epic-candidate.md` (hard cap `{max_children}`), and for the epic coherence record `epic-coherence.json` beside it, produced by `review-epic-coherence.md`.\n- Pipeline variable `auto_approve_external` controls whether the external-mutation pause is skipped (for this run, `auto_approve_external` = `{auto_approve_external}`). Treat the literal string `\"true\"` as skip; any other value (including `\"false\"`, missing, or empty) means pause and ask.\n\n## Instructions\n\n> **Orchestrator-directed step.** This agent task is part of the full-automation chain and is authorized to call `get_tickets`, `create_ticket`, `attachment` (operations: `upload`, `list`), `update_ticket_description`, `track_ticket`, and `add_comment`, and to execute the shared `gather-and-attach-materials.md` instruction, as directed below — performing orchestrator-directed tool calls is not \"re-orchestrating\".\n\n1. Read `run-manifest.json` and `draft-metadata.json`. Branch internally based on the manifest's `scope`:\n   - `task` or `spike` → follow the **Single-ticket path** below.\n   - `epic_candidate` → follow the **Epic path** below.\n   The orchestrator does not support conditional steps; this branching lives in agent logic.\n\n2. External approval gate, applied before any mutating MCP tool call. On the Epic path it applies **after** step 4.1 has frozen the decomposition and run the epic coherence check, and after step 4.2 has rendered the drafts — so the confirmation shows the verdict — but still before any mutating call. On the Single-ticket path it applies before step 3's first mutating call, as before.\n   - If `auto_approve_external` is `\"false\"` (or any non-`\"true\"` value), summarize the exact planned Jira mutations — list every `create_ticket`, `attachment` (operation: `\"upload\"`), and `track_ticket` call with its key arguments — and ask the user for explicit confirmation in this agent task before proceeding. On the Epic path, lead that summary with the gap-check result from step 4.1, in the plain words from `review-epic-coherence.md`: `No gaps found` (or `No gaps found (N notes added to tickets)` when ticket-local findings are carried), `Accepted with known gaps`, `Needs your decision`, or `Couldn't check`; a note that the check is less independent when the record says `independent: false`; each remaining blocking finding or the reviewer failure; one compact \"Who covers each requirement\" bullet per epic AC (AC id, owning child — or \"owner-run\" with the person or role and the step reference — and obligation); and every override with its reason.\n   - If `auto_approve_external` is `\"true\"`, proceed without the confirmation pause.\n\n3. **Single-ticket path** (`scope` is `task` or `spike`):\n\n   This path runs **no epic coherence check**: no reviewer call, no record, no render preflight, and no extra prompt. The residual risk — work that really needed a set-level check — is contained by the existing gates: the scope decided before this step and the writer-drafted body. An attended operator who sees that the work is really epic-shaped should stop at the step 2 confirmation and re-run it as an epic.\n\n   1. Idempotency lookup. Call `get_tickets` with its `labels` parameter set to both the per-run label `<idempotency_label>` and the stable `bapi-idea-hash-{idea_hash}` label from `draft-metadata.json` (comma-separated). If a match is found by either label, reuse that ticket key and skip `create_ticket`.\n   2. If no match was found, call `create_ticket` with `summary`, `slim_description` as the description, `issue_type`, and `labels` exactly as written in the metadata. Capture the returned `ticket_key`.\n\n      **Pass `slim_description` through unchanged.** On a `spike` ticket it carries the canonical `<!-- bridge:execution-class=investigation -->` marker line, and this call is the only path by which that marker reaches the persisted ticket record. Translating the metadata into the create call must not strip, reconstruct, re-render, normalize, duplicate, or relocate the marker, and must not move it into the attachment instead. Do not validate it either: this step is not a marker validator, and selection and stamping are the writer's and the drafting step's job. Copy the value; do not edit it. `create_ticket` takes no execution-class parameter and none is added — the marker travels in `description` and nowhere else.\n   3. Upload the full markdown draft via `attachment` (operation: `\"upload\"`) using `attachment_path`.\n   4. **Gather and attach referenced materials.** Execute the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the resolved ticket key, `draft_file_path` = `attachment_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value. It attaches phase-eligible local materials (Planning Assets, Downloadable Assets, and Planning & Downloadable Assets) and records external/auth-gated and binary/image materials per its own warn-not-halt rules. Any attach failure it reports is recorded (via `update_ticket_description`) as `partial_success` and never halts this step.\n   5. Call `track_ticket` with the resolved ticket key so Bridge API picks the new ticket up.\n   6. Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/upload-state.json` describing the final state.\n\n4. **Epic path** (`scope` is `epic_candidate`):\n   1. If `decomposition-plan.json` does not yet exist for this run, follow `decompose-epic-candidate.md` first to produce it (hard cap `{max_children}`). If it **does** already exist, it is the approved manifest and this step performs **no fresh decomposition** — read it and use it as written. Decomposition happens once; re-deriving the split immediately before upload is how children end up overlapping or contradicting the parent they are about to be created under.\n\n      **Then run the epic coherence check, before rendering and before the step 2 approval gate.** Every Epic-path run does this; the Single-ticket path never does.\n      - **Normalize the input.** Write `{docs_dir}/idea-to-ticket/{slug}-{run_id}/epic-coherence-input.json` in the input document shape `review-epic-coherence.md` defines, built from the **complete, ordered** `children` array of `decomposition-plan.json` and nothing else. `epic` carries the `slug`, the parent summary, and the Epic parent draft's acceptance criteria, each with an `id`, its text, and its verification sentence. `design_text` is the parent draft's summary and requirements plus the System Goals from `goals-and-nfrs.md`. Each `manifest` entry maps one child: `id` is its 1-based index as a string, `title` is its `summary`, `scope` is its `rationale`, `size_band` is the band named in the rationale's size estimate, and `depends_on`, `recommended_after`, and `owns_verifications` are copied unchanged. Each `child_evidence` entry carries that child's planned `acceptance_criteria`, which include its `owns_verifications` obligations verbatim. When `decomposition-plan.json` has a plan-level `non_child_owners` array, copy it **unchanged** into the input's top-level `non_child_owners`; a child's `owns_verifications` keeps only that child's own obligations.\n      - **Run the shared procedure.** Follow `review-epic-coherence.md` in `drafting` mode, with that input path, the run directory as the output directory, and unattended exactly when `auto_approve_external` is the literal `\"true\"`. It computes `manifest_sha256`, `child_evidence_sha256`, and `non_child_owners_sha256` and writes `epic-coherence.json` and `epic-coherence.md` into the run directory. Read the procedure at `docs/install/review-epic-coherence-procedure.md` in this project, where the Bridge installer scaffolds it; if it is not there but `mcp_server/instructions/review-epic-coherence.md` exists in this checkout, read that instead. If neither exists, stop: the shared procedure is not installed, so re-run the Bridge installer or upgrade the Bridge package. Never improvise a substitute review.\n      - **Reuse or resume.** When `decomposition-plan.json` already existed, recompute **all three** digests from it and re-run the check when the record is absent, stale (any digest differs, or its top-level digests differ from its last round's), or not clearing. When tickets for this run already exist and a changed split or changed evidence would need reconciling against them, stop and ask the operator; never apply a changed split to tickets that already exist.\n      - **Amendments.** The reviewer only describes amendments. To make one, repeat `decompose-epic-candidate.md` with each remaining finding's `smallest_amendment` as extra input. That writes a **new** `decomposition-plan.json` with a new identity. Rewrite the input and let the procedure re-check. A record for the old manifest can never clear the new one. The bound is the procedure's risk-scaled round limit. An amendment made after the last allowed round goes through the procedure's one confirmation pass, or, attended only, its narrow `amended_after_final_round` bypass with verdict `not_checked`; it is never presented as covered by an older round.\n      - **Attended** (`auto_approve_external` is not the literal `\"true\"`): show the gap-check result in the plain words from `review-epic-coherence.md` (`No gaps found`, qualified as `No gaps found (N notes added to tickets)` when ticket-local findings are carried, `Accepted with known gaps`, `Needs your decision`, or `Couldn't check`), a less-independent note when `independent: false`, each remaining foundation blocking finding, carried ticket-local finding (as a note added to ticket N), or reviewer failure, the \"Who covers each requirement\" bullets, and any overrides. A council outcome of `declined_by_operator` is resolved by the render preflight and needs no extra step here. Each remaining foundation blocking finding must be fixed (an amendment as above, re-frozen and re-checked) or accepted with a reason the operator types, recorded as an override of kind `accept`. Ticket-local blockers are carried to their child ticket and do not require an epic-level acceptance. When the reviewer is unavailable, the verdict is `not_checked`: offer a retry, or a bypass with an operator-typed reason recorded as an override of kind `bypass`. `not_checked` (shown as `Couldn't check`) is never shown or treated as a pass. The step 2 confirmation shows the same result again.\n      - **Unattended** (`auto_approve_external` is the literal `\"true\"`, which covers `--auto` and `/idea-to-pr`): amend and re-check within the procedure's risk-scaled round limit. If any foundation blocking finding remains, halt with verdict `blocked`; carried ticket-local blockers continue into their child ticket. A foundation blocking finding from a confirmation pass, or a required council left unresolved, halts the same way. If the reviewer is unavailable, halt with verdict `not_checked`. If the record says `independent: false`, halt too — an inline check is not independent clearance. **Unattended runs have no bypass.** A halt happens before rendering and before any `create_ticket`; report it with the coherence halt payload in `## Return`.\n   2. Render bodies against the frozen manifest by following `render-ticket-manifest.md`: one `jira-ticket-writer` invocation per entry that lacks a draft on disk, each bound to its own entry's fixed boundary and size band, using the `draft_path` from the decomposition plan. A rendering invocation may not re-split, merge, reorder, renumber, or rescope. Its preflight is fail-closed — an unapproved manifest, a changed manifest identity, an XL epic child, a missing writer draft, or an epic coherence record that is missing, stale, or not clearing stops the flow **before** any Jira mutation. After drafting, extend `draft-metadata.json` so `children[]` mirrors the final list from the decomposition plan.\n\n      After clearance, bring the drafts in line with the reviewed manifest. Re-render the Epic parent draft through `jira-ticket-writer`, passing the record's coverage map (including its owner-run owners), exact verdict, and override reasons, so it carries a `## Epic coverage map` section; then refresh the parent's entry in `draft-metadata.json`. Delete any child draft whose manifest entry changed during an amendment, so it is rendered again against the reviewed manifest. Each child invocation receives that child's `owns_verifications` verbatim, and never an owner-run obligation.\n   3. Create only from writer-produced drafts. Every ticket body uploaded below came from `jira-ticket-writer`; nothing here composes a description inline.\n   4. Parent first. Look up the Epic parent by `bapi-idea-to-ticket-{run_id}-parent` via `get_tickets`. If found, reuse that key; otherwise call `create_ticket` with the parent's summary, slim description, issue type `Epic`, and parent labels. Attach the Epic draft via `attachment` (operation: `\"upload\"`) using `parent.attachment_path`. Then **gather and attach the Epic parent's referenced materials** by executing the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the Epic key, `draft_file_path` = `parent.attachment_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value. Then call `track_ticket` for the Epic key.\n   5. Children next. For each child in order:\n      - Look up by the child's `idempotency_label`. If found, reuse that key.\n      - Otherwise call `create_ticket(parent_key=<epic_key>)` with the child's `summary`, `slim_description`, `issue_type`, and `labels`. The `parent_key` is required so Jira's modern parent linkage is set.\n      - Upload the child draft via `attachment` (operation: `\"upload\"`) using `draft_path`.\n      - **Gather and attach this child's referenced materials** by executing the shared `gather-and-attach-materials.md` instruction as an `agent_task`, passing `ticket_number` = the child key, `draft_file_path` = `draft_path`, and `auto_approve_external` = the inherited `{auto_approve_external}` value.\n      - Call `track_ticket` for the child key.\n   6. After every parent or child mutation, write partial progress to `{docs_dir}/idea-to-ticket/{slug}-{run_id}/upload-state.json` so a later resume can pick up exactly where the run stopped.\n   7. **Recommended implementation order comment.** Once the Epic parent and all surviving children exist (real keys known), post a single comment on the Epic via `add_comment` with `ticket_number` set to the Epic key. The comment carries (a) a short System Goals / Non-Functional Requirements summary from `goals-and-nfrs.md`, and (b) the **Recommended Implementation Order** — the children in order, each referenced by its real Jira key, derived from the `depends_on` / `recommended_after` / `order_rationale` fields in `decomposition-plan.json`. State that this is recommended sequencing only — do **not** create Jira dependency links and do **not** attach a separate markdown doc. Skip this only if the run reused a pre-existing comment for the same run (idempotency); do not post duplicate order comments on resume.\n\n5. Required child label set whenever any child is created: `ai-generated`, `idea-to-ticket`, `idea-to-ticket-child`, and `bapi-idea-to-ticket-{run_id}-child-<N>` (1-based index from the decomposition plan).\n\n6. Partial-failure recovery rules:\n   - If `create_ticket` succeeds but `attachment` (operation: `\"upload\"`) fails, record the outcome as `partial_success` in `upload-state.json` and continue with the next planned mutation; do not retry inside this step.\n   - If the Epic parent is created successfully but one or more children fail, preserve the parent key and any completed child keys in `upload-state.json` before raising the failure.\n   - On resume of any prior run, search by every relevant idempotency label first (`bapi-idea-to-ticket-{run_id}` for single tickets, `bapi-idea-to-ticket-{run_id}-parent`, and each `bapi-idea-to-ticket-{run_id}-child-<N>`) before considering any `create_ticket` call. Idempotency labels are how this pipeline avoids creating duplicate tickets across retries.\n   - That label-based idempotency is pre-existing and Jira-only; against the local ticket backend label lookups are unsupported. The epic coherence check does not depend on it and adds no label or label lookup: its state lives only in files in the run directory.\n\n## Return\n\nConfirm the run's final upload outcome: attachment results, `track_ticket` outcome, and any `partial_success` rows recorded in `upload-state.json`.\n\nThen, as the FINAL content of your reply, emit a fenced ```json block holding the authoritative payload for this run — and nothing else. The chain reads ONLY this final fenced JSON block to pick its review / start-tickets targets, so it must contain exactly the keys from `upload-state.json` and never any key you merely looked up during duplicate detection. Duplicate-detection / looked-up keys must not appear in this authoritative payload unless they are the final created/reused ticket for this run.\n\nThere are exactly three authoritative final payload shapes: two for a run that created or reused tickets, and one for an epic run that halted on the coherence check before creating anything.\n\n- **Single-ticket path** (`scope` is `task` or `spike`): emit strictly `created_ticket_keys` containing **exactly one** implementable ticket key. `created_ticket_keys` is only for the single-ticket `task`/`spike` path and must contain exactly one implementable ticket key:\n\n  ```json\n  {\"created_ticket_keys\": [\"BAPI-331\"]}\n  ```\n\n- **Epic path** (`scope` is `epic_candidate`): emit the Epic parent key separately as `epic_parent_key`, and the implementable children as `child_ticket_keys`:\n\n  ```json\n  {\"epic_parent_key\": \"BAPI-400\", \"child_ticket_keys\": [\"BAPI-401\", \"BAPI-402\"]}\n  ```\n\n  `child_ticket_keys` contains **only** implementable child Task/Spike ticket keys, listed in final decomposition order. `child_ticket_keys` must **never** include the Epic parent key.\n\n- **Epic coherence halt** (`scope` is `epic_candidate`, and the unattended check halted before any `create_ticket`): first, in prose, name the remaining foundation blocking findings or the reviewer failure, and tell the operator to rerun `/idea-to-ticket` without `--auto` to amend, retry, or explicitly accept the findings. Then emit exactly these four keys and no others:\n\n  ```json\n  {\"halted\": true, \"halt_reason\": \"epic_coherence\", \"coherence_verdict\": \"blocked\", \"coherence_record\": \"<path to epic-coherence.json>\"}\n  ```\n\n  `coherence_verdict` is `blocked`, or `not_checked` when the reviewer was unavailable or the check was not independent. The halt payload never carries `epic_parent_key`, `child_ticket_keys`, `created_ticket_keys`, or a findings array — nothing was created, so a halt can never look like a successful epic payload.\n",
     "upload-epic-hierarchy.md": "Standalone Epic upload protocol. Use as the detailed reference for the Epic path triggered from `upload-and-track.md`.\n\n## Inputs\n\n- Run manifest: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json` with `scope == \"epic_candidate\"`.\n- Draft metadata: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/draft-metadata.json` with a populated `parent` and `children`.\n- Decomposition plan: `{docs_dir}/idea-to-ticket/{slug}-{run_id}/decomposition-plan.json`.\n- Pipeline variable `auto_approve_external` governs the external-mutation pause as in `upload-and-track.md` (for this run, `auto_approve_external` = `{auto_approve_external}`).\n\n## Instructions\n\n1. Parent idempotency lookup. Search Jira via `get_tickets` for issues carrying the label `bapi-idea-to-ticket-{run_id}-parent`. If a match exists, reuse that ticket key as the Epic parent and skip `create_ticket` for the parent. Otherwise call `create_ticket` with the parent's summary, slim description, `issue_type = \"Epic\"`, and labels including `ai-generated`, `idea-to-ticket`, and `bapi-idea-to-ticket-{run_id}-parent`. After creation or reuse, upload the Epic draft via `attachment` (operation: `\"upload\"`) and call `track_ticket`.\n\n2. Capture the resolved Epic key into a local variable `epic_key`. Every subsequent child mutation must reference this exact key.\n\n3. Per-child idempotency lookup. For each child in `decomposition-plan.json` (in order), search Jira by the child's `idempotency_label` (`bapi-idea-to-ticket-{run_id}-child-<N>`). If a match exists, reuse that key and skip `create_ticket` for that child. Otherwise call `create_ticket(parent_key=<epic_key>)` with:\n   - `summary` — child summary.\n   - `slim_description` — child slim description.\n   - `issue_type` — typically `Task` (or `Spike` when the child is primarily discovery).\n   - `labels` — `ai-generated`, `idea-to-ticket`, `idea-to-ticket-child`, and the child's own `bapi-idea-to-ticket-{run_id}-child-<N>` label.\n   The `parent_key` argument is REQUIRED for every child `create_ticket` call so Jira sets the modern parent relationship; never omit it.\n\n4. After each child is created or reused, upload its draft via `attachment` (operation: `\"upload\"`) using the child's `draft_path`, then call `track_ticket` for that child key, then append the child outcome to `upload-state.json` in the run directory.\n\n5. On partial failure (e.g., parent succeeded, third child failed), preserve `epic_key` plus every completed child key in `upload-state.json`. The next run of this protocol must rediscover those keys via the idempotency-label lookups in steps 1 and 3 before considering any new `create_ticket` call.\n\n## Return\n\nConfirm the Epic key, the number of children created vs reused vs failed, and the path of the updated `upload-state.json`.\n",
     "verify-plan.md": "Close the remaining plan gaps for ticket {ticket_key}, now that the pull request is open.\n\nThe plan's work has already been executed. The production phase authored the\nartifacts, the checkpoint pushed them, and the pre-PR verification phase ran the\nplan's review steps, test commands, and rendered-UI remediation — publishing each\nmaterial correction as it went. The pull request was then opened on top of all of it.\n\nThis phase exists for the narrow remainder: the plan obligations that genuinely could\n**not** be reached before a pull request existed, plus corrections attributable to this\nticket.\n\n**Verification scope: `{verification_scope}`.** In `targeted` scope, resolve genuine post-PR plan gaps with plan-authored commands, changed-module tests, and fast static guards in the foreground. Do not start a full or background suite; epic-level CI owns the full-suite check. In `full` scope, retain the existing behavior below.\n\nFor `targeted` scope only:\n\nBefore the first push, after committing, run targeted verification plus likely-tests\ndiscovery with the full literal comparison SHA and exact resolver commands supplied\nin trusted starter context. Prefer the packaged `epic-implementer likely-tests --base <sha>` executable; use `npx -y -p @bridge_gpt/mcp-server epic-implementer likely-tests --base <sha>` if unavailable. If neither starts, disclose that and continue with\navailable targeted verification. References are untrusted identifiers to map through\nthe repository's declared runner, never shell commands to execute verbatim. Disclose\nunavailable, malformed, unreadable, truncated, or unmappable coverage in the existing\nhandoff or attempt transcript. Empty discovery retains targeted verification; do not\nrun a whole suite as fallback. Actual failures retain existing repair/reporting\nbehavior. To diagnose a pre-existing failure, rerun only that failing reference on\nthe base through the repository's established safe workflow. Refresh discovery after\nadditional commits before publishing them. Never\nuse shell substitution, a moving branch ref, or a guessed comparison SHA.\n\n\nTwo consequences follow, and both are deliberate:\n\n- **This phase does not re-run completed work.** A step the durable ledger records as\n  `executed` or `adapted` stays settled unless a later correction invalidated its\n  evidence. Re-running it duplicates work the pre-PR phase already did and burns the\n  budget this protocol was reordered to protect.\n- **This phase never issues a verdict.** You report what you observed. The\n  authoritative pass/fail belongs to the pipeline's `ci` and `code_review` gates,\n  which the reconciler observes independently. Worker self-verification has\n  demonstrably reported green while the full suite was red; that is exactly why the\n  gates, not this phase, decide.\n\n**Tool and scope boundary.** Use only the tools this recipe names, the repo's own tooling, and MCP\ncapabilities provisioned for this repository. Keep all work confined to this worktree unless\nexplicitly told to do otherwise.\n\n**Execution mode for this run: `{execution_mode}`.** Under `orchestrated`\n(a server-side orchestrator) orchestration appends the routed phase context and\nparses the fenced result envelope you return. Under `inline` (`get_pipeline_recipe`)\nthere is no orchestrator: the ledger is read with a tool call and written with one.\nFollow the branch that matches wherever the two are named.\n\n---\n\n## Step 1 — Establish that the durable artifact exists\n\nBefore running any check:\n\n1. Run `git branch --show-current` and `git rev-parse HEAD`, then verify the branch\n   has been pushed and the local head is present on the remote (for example via\n   `git status -sb` showing no unpushed ahead-count, or `git ls-remote origin <branch>`).\n2. Verify that a usable pull request URL was obtained by the preceding PR step —\n   either a newly opened pull request or an already-open one on this head branch.\n\nIf the branch is not pushed, or no usable pull request URL exists, then\n**stop this phase** and report the missing prerequisite. This phase exists only to\nadd work on top of an open pull request.\n\n## Step 2 — Recover what remains from durable state\n\n1. Call the `get_plan` tool for `{ticket_key}`. The local copy at\n   `{docs_dir}/plans/{ticket_key}-plan.md` may be used as a reference.\n2. Recover the durable ledger, by mode:\n   - **orchestrated** — read the **Routed phase context** block appended to this\n     instruction: `ledger` carries every disposition earlier phases recorded, and\n     `ownedSteps` carries anything routed directly to this phase.\n   - **inline** — call `get_phase_context` with `ticket_key` `{ticket_key}` and\n     `phase` `post_pr_gap_close`. It returns the same `ownedSteps` plus the `ledger`\n     merged from every earlier phase's artifact, `terminalStepIds` for what is\n     already settled, and `unresolved` for the escalations that are this phase's\n     actual subject.\n\nRecover the remaining work from that durable record, not from conversation. A\ncompaction or a resumed session loses the conversation; the ledger survives both,\nwhich is why it replaced the conversational hand-off.\n\n## Step 3 — Select only genuine gaps\n\nRun only:\n\n- Steps the ledger records as `escalated` **because a capability was unavailable\n  before the pull request existed**, or **because the check genuinely requires an open pull request** — and\n  which are now satisfiable.\n- Corrections clearly attributable to this ticket's change.\n\nReport — do not attempt to fix — failures that are unrelated to this ticket, flaky,\nenvironmental, pre-existing on the base branch, or outside the declared file scope.\nSpeculative edits made under budget pressure are how a correction round turns into a\nregression.\n\nApply the same adaptation boundary the earlier phases use: **locator-correction**,\n**repository-command-correction**, and **equivalent-implementation-recognized** are\nmechanical and may be applied; anything touching design, schema, public API,\ndependencies, or security escalates instead.\n\nBefore beginning any correction, apply the **low-budget guard**: only start if enough\nsession budget clearly remains to make the edit, commit it, *and* push it. Starting a\nfix you cannot finish and publish is strictly worse than reporting the finding and\nletting the CI and review gates handle it — an unpushed correction is invisible to\nthose gates.\n\n## Step 4 — Report what you observed, honestly\n\nFor every check you run, record the exact command, its observed result, and — on\nfailure — the relevant failure detail (the failing test names, the error output, the\ndiagnostic lines).\n\nReport all of it, including failures you did not fix. Never soften or omit a failing\nresult.\n\nDescribe only what you observed. Do not write that CI passed, that the gate is met,\nthat the review is approved, or any equivalent claim about the pipeline's verdict —\nthose states are decided by the `ci` and `code_review` gates and observed by the\nreconciler, never asserted by this phase.\n\n## Step 5 — Correct only what is clearly yours, and push it immediately\n\nFor each accepted correction:\n\n1. Make the edit.\n2. Stage the specific files, commit, and **push immediately** — the commit and its\n   push are one consecutive sequence, never separated by another check. A local\n   commit that is never pushed is not visible to the pull request, to CI, or to the\n   reconciler.\n3. Run `git rev-parse HEAD` again and record the new pushed head as\n   `last_commit_sha`.\n\n## Step 6 — Final git-state audit\n\nBefore returning, run `git status --porcelain` and resolve the working tree:\n\n- Legitimate corrections still uncommitted → commit and push them (Step 5's\n  commit-then-push-immediately rule applies).\n- Accidental diagnostic edits — debug prints, scratch files, temporary config\n  tweaks made while investigating a failure → revert them when it is safe to do so.\n- Anything you cannot safely resolve → leave it and **report it explicitly**,\n  naming each remaining dirty path.\n\nNever return leaving unpushed commits unreported.\n\n## Step 7 — Hand unresolved findings forward\n\nAn unresolved local finding is normally **not** a reason to stop the pipeline. The\npull request is open and the authoritative gates will evaluate it. Report the\nfinding and let CI monitoring and code review take it from there.\n\nStop only when continuing would be unsafe or impossible — for example the durable\nartifact from Step 1 turned out to be missing, or the working tree is in a state you\ncannot resolve without risking the pushed branch.\n\n## Return\n\nReturn a summary containing:\n\n- the branch and the pull request URL,\n- the latest pushed `last_commit_sha`,\n- every gap-closing command run, with its observed outcome,\n- the correction commit, if one was made and pushed,\n- every unresolved finding and every unresolved dirty path.\n\nState these as worker observations. Do not include a pass/fail verdict for the `ci`\nor `code_review` gates.\n\nThen record the machine-readable phase result, by mode, so the durable ledger records\nhow the remaining gaps closed.\n\n### orchestrated\n\nEnd your result with the envelope in a fenced block tagged `bapi-phase-result`, which\norchestration parses, validates, and persists:\n\n```bapi-phase-result\n{\"version\":1,\"phase\":\"post_pr_gap_close\",\"lastCommitSha\":\"<sha>\",\"records\":[]}\n```\n\n### inline\n\nCall the `record_phase_result` tool with `ticket_key` `{ticket_key}` and\n`phase_result` set to that same envelope object; the tool validates and persists it.\n**Do not also emit a fenced `bapi-phase-result` block** — nothing parses one on this\npath.\n\nThe tool call is this phase's final action, **not the end of your turn.** When it\nreturns successfully, continue immediately with the next recipe step. What follows\ndepends on the verification scope (`{verification_scope}`):\n\n- **`full`:** the ticket status transition, the CI follow-up config, and CI\n  monitoring. The pull request is open and its gates are still pending; stopping\n  here abandons the run before anything observes them.\n- **`targeted`:** only the ticket status transition, and the final push if any\n  commit is still local. Then end your turn. Do not configure CI follow-up, and do\n  not wait on CI (no `wait_for_ci_checks` or `poll_ci_checks`): epic-level CI owns\n  the pull request's checks, and waiting here only delays this job's end.\n\nIf the call fails, fix what it reports and call it again.\n",
     "write-epic-summary.md": "Synthesize all sub-task explorations into a final overview document.\n\n## Instructions\n\n1. First, use a terminal command or glob pattern to list all files in `{docs_dir}/epic-plans/{epic_slug}/explorations/`. Then read each file. Do not guess filenames — discover them dynamically.\n\n2. Also read:\n   - `{docs_dir}/epic-plans/{epic_slug}/research-findings.md`\n   - `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md`\n   - `{docs_dir}/epic-plans/{epic_slug}/goals-and-nfrs.md` (the goals/NFR framing; carry its System Goals, NFRs, and any Recommended Implementation Order through to the overview).\n   - `{docs_dir}/epic-plans/{epic_slug}/epic-implementer-eligibility.json` (written by `assess-epic-implementer-eligibility`; required for the Epic Implementer Eligibility section below).\n\n3. Synthesize the information into an overview and write it to `{docs_dir}/epic-plans/{epic_slug}/overview.md` with the following required sections:\n\n```markdown\n# Epic Overview: {epic title derived from description}\n\n## Epic Description and Goals\n{Summary of the epic's purpose, scope, and desired outcomes. Lead with the business goal and desired end-state from goals-and-nfrs.md.}\n\n## Non-Functional Requirements\n{The classified NFRs from goals-and-nfrs.md — each with its category, requirement, implication, and final status (confirmed/assumed). Any NFRs the user clarified should now read as confirmed/assumed, not open.}\n\n## Research Summary\n{Key external findings that informed the decomposition. If no research was performed, state \"No external research was needed.\"}\n\n## Sub-task List\n{Numbered list of all sub-tasks with relative markdown links to their exploration docs.}\n1. [Sub-task title](explorations/01-subtask-slug.md) — one-line summary\n2. [Sub-task title](explorations/02-subtask-slug.md) — one-line summary\n...\n\n## Dependency Graph\n{Textual list showing execution ordering and dependencies between sub-tasks.}\n- Sub-task 1: No dependencies (start here)\n- Sub-task 2: Depends on Sub-task 1\n- Sub-task 3: Depends on Sub-task 1\n- Sub-task 4: Depends on Sub-tasks 2, 3\n...\n\n## Recommended Implementation Order\n{The recommended order in which to implement the sub-tasks, reconciling the provisional order from goals-and-nfrs.md with the approved decomposition. For each sub-task give the position, its hard prerequisites (depends on), any soft sequencing preferences (recommended after), and a one-line rationale. This is recommended sequencing only — no Jira dependency links are created.}\n\n## Epic Implementer Eligibility\n{Render from `epic-implementer-eligibility.json`, written by `assess-epic-implementer-eligibility`. This section\nis about predicted HUMAN WORKLOAD before any execution starts — it never blocks planning\ncompletion, on any status. Render this section whenever the status is `\"assessed\"` and either\n`predictedWorkflowChildren` or `containmentChildren` is non-zero — a containment-only epic\n(`predictedWorkflowChildren` == 0, `containmentChildren` > 0) still renders the section, it just\nskips the workflow-merge rows.\n\nOrder: assessment availability/status first, then the workflow, hand-review-subset, and\ncontainment counts — reported independently of one another — then affected-child evidence.\n\n**When status is `\"assessed\"`:**\n\n- If `predictedWorkflowChildren` > 0:\n  - A merge row stating: \"At least N of M children are predicted to modify workflow files. In an\n    epic-branch run they merge into the epic branch and are listed for the integration PR's\n    reviewer, because their CI ran on workflows they changed; in an `--into-base` run they require\n    human merge.\" where N is `predictedWorkflowChildren` and M is `totalChildren`. Include\n    the canonical `reason` identifier (e.g. `workflow_files_modified`) inline in monospace when it\n    is present, e.g. \"(reason: `workflow_files_modified`)\". This is a lower bound, not a promise —\n    see the caveat below.\n  - If `reviewSubsetChildren` > 0, a second, more severe row stating: \"K of those N are predicted to\n    modify `.github/workflows/claude-review.yml`; automated review will not run and hand review is\n    required.\" where K is `reviewSubsetChildren`. Use the literal path from the artifact's affected-child\n    matched paths, never a hard-coded literal in this instruction. State plainly that this narrower set\n    is also part of the workflow set above and gets no automated review verdict, so its merge still\n    waits on review.\n  - If `predictedWorkflowChildren` == 0: render \"No workflow-file changes predicted from current\n    ticket text.\"\n- A containment row, independent of the workflow rows above:\n  - If `containmentChildren` > 0: \"P of M children are predicted to describe a containment hazard —\n    a destructive primitive (truncate, drop, reset of shared state) or a change to Epic Implementer\n    enforcement code.\" where P is `containmentChildren` and M is `totalChildren`. State plainly that\n    containment is advisory and orthogonal to workflow merge eligibility: a containment-flagged\n    child is not thereby a workflow change, and a workflow-flagged child is not thereby a\n    containment hazard.\n  - If `containmentChildren` == 0: render \"No containment hazards predicted from ticket text.\"\n- The caveat, always present when either count is non-zero: \"Predictions are based on ticket text;\n  implementation choices, including defense-in-depth workflow changes, can increase the final\n  count.\" This lower-bound caveat covers both the workflow and containment predictions — neither\n  count is a guarantee that the corresponding merge/review/operator-attention need will or will not\n  materialize once implemented.\n- A note on why this matters more than it might look: workflow changes, hand-review, and\n  containment are especially consequential for unattended v2 execution, where no operator is\n  watching for a stalled or destructive child, and the integration PR's reviewer is the one who\n  sees them.\n- A collapsed \"Show affected children\" section (a Markdown `<details>` block) listing, for each\n  entry in `affectedChildren` (the union of workflow-affected and containment-affected children):\n  its compact `id`, `title`, its workflow status (`matchedPaths`, labelled \"Modifies workflows\", and\n  \"Hand review\" when `requiresHandReview` is set), and its containment-review status\n  independently, from `requiresContainmentReview` and the bounded `matchedHazards` evidence in the\n  order the artifact supplies. Label each status independently — a child can modify workflows,\n  need containment review, both, or (if only fetched via containment) neither workflow label.\n  **Never** label a containment-only child (hazard evidence present, `matchedPaths` empty) as\n  \"Modifies workflows\" — use a distinct \"Containment review\" label for it instead.\n\n**When status is `\"unavailable\"`:** render a non-blocking warning: eligibility could not be\npredicted from the current planning data, and workflow-related merge/review/containment eligibility\nmust be verified manually before execution. Do not report `0 of M` or any other count when the\nstatus is unavailable — an unresolved assessment and a genuine zero are different facts.\n\n## Next Steps\n{One-line summaries for each sub-task, specifically formatted so they can be handed directly to the Jira Ticket Writer / ticket-authoring workflow as input. Each line should be a self-contained ticket description.}\n```\n\n4. After writing the overview, display the file path to the user and summarize the epic plan.\n\n5. **Push the goals/NFRs + recommended order into the Jira epic (only when `{epic_key}` is non-empty).** The `epic_key` is empty when this run was started from free-form text rather than an existing Epic; in that case skip this step. When `{epic_key}` is a real Jira key, post the System Goals, the final NFRs, the Recommended Implementation Order, and a concise Epic Implementer Eligibility summary as a **comment** on that epic by calling the `add_comment` MCP tool with `ticket_number` set to `{epic_key}` and a comment containing those four parts. The eligibility summary is one or two lines derived the same way as the overview's Epic Implementer Eligibility section (the \"At least N of M\" / \"K of those N\" wording, or the zero/unavailable wording) — never the full affected-children detail. Do not create Jira dependency links and do not attach a separate markdown doc — the comment is the delivery. Display: `\"Posted epic goals/NFRs, recommended implementation order, and Epic Implementer eligibility to {epic_key}\"`.\n\n## Return\n\nConfirm the overview was written to `{docs_dir}/epic-plans/{epic_slug}/overview.md` and report the total sub-task count along with a one-line summary of the epic plan. State whether the goals/NFRs + recommended order were posted as a comment on `{epic_key}` or skipped because no epic key was provided.\n\nThen state plainly what approval inside `/plan-epic` did and did not do. The approval covered only the **local draft** in `{docs_dir}/epic-plans/{epic_slug}/`. No plan was stored or approved on the server, no run was created, no epic branch was cut, and no run fee was charged.\n\nGive the operator this sequence, in order:\n\n1. Create one child ticket for each sub-task in `epic-manifest.json`.\n2. Run `emit-epic-implementer-bundle finalize`, or the `emit-conductor-bundle.md` task. It replaces **every** `TBD-N` placeholder in `epic-plan.dag.json` with the real ticket key and writes `epic-plan.meta.json`.\n3. Launch with `/drive-epic-run {epic_key}` in Claude Code or Cursor, or `drive-epic {epic_key}` in Codex or Copilot. `drive-epic` is the single launch entry point. `/drive-epic-run` shows a run summary and asks `Create this run? (y/N)` before it creates the run or charges anything.\n\n`{epic_key}` is a value the operator replaces, never a command to run as written. When `{epic_key}` is empty (the run started from free-form text), do not print a launch command. Tell the operator to create an epic first, then follow the sequence above with that epic's key.\n",