@bridge_gpt/mcp-server 0.1.16 → 0.2.0

package/pipelines/full-automation.json

@@ -0,0 +1,49 @@
+{
+  "name": "full-automation",
+  "description": "Drive an idea end-to-end: create ticket(s) (idea-to-ticket), review each ticket (review-ticket fan-out), then hand off to the /start-tickets CLI seam to spawn worktrees.",
+  "variables": [
+    "idea",
+    "auto_approve",
+    "scheduled_at",
+    "max_children",
+    "allow_duplicate",
+    "agent"
+  ],
+  "stages": [
+    {
+      "pipeline_name": "idea-to-ticket",
+      "description": "Convert the idea into one or more Jira tickets.",
+      "variables": {
+        "idea": "{idea}",
+        "max_children": "{max_children}",
+        "allow_duplicate": "{allow_duplicate}",
+        "auto_approve_external": "{auto_approve}"
+      },
+      "outputs": {
+        "child_ticket_keys": "child_ticket_keys",
+        "epic_parent_key": "epic_parent_key",
+        "created_ticket_keys": "created_ticket_keys"
+      }
+    },
+    {
+      "pipeline_name": "review-ticket",
+      "description": "Review each created ticket (one child pipeline run per ticket).",
+      "fan_out_input": "child_ticket_keys",
+      "fan_out_variable": "ticket_key",
+      "variables": {
+        "ticket_key": "{ticket_key}"
+      },
+      "outputs": {
+        "reviewed_ticket_keys": "reviewed_ticket_keys"
+      }
+    },
+    {
+      "pipeline_name": "start-tickets",
+      "description": "Hand off the reviewed tickets to the /start-tickets CLI seam (agent-task; not a server pipeline).",
+      "fan_out_input": "reviewed_ticket_keys",
+      "outputs": {
+        "started_ticket_keys": "started_ticket_keys"
+      }
+    }
+  ]
+}

package/pipelines/idea-to-ticket.json

@@ -0,0 +1,71 @@
+{
+  "name": "Idea to Ticket",
+  "description": "Convert a short human idea into either a single Jira Task/Spike or a Jira Epic plus decomposed child tickets.",
+  "variables": [
+    "idea",
+    "idea_hash",
+    "slug",
+    "run_id",
+    "docs_dir",
+    "allow_duplicate",
+    "auto_approve_external",
+    "max_children"
+  ],
+  "steps": [
+    {
+      "type": "mcp_call",
+      "tool": "ping",
+      "params": {},
+      "description": "Verify Bridge API connectivity"
+    },
+    {
+      "type": "mcp_call",
+      "tool": "get_docs_dir",
+      "params": {},
+      "description": "Resolve the docs directory for run artifacts"
+    },
+    {
+      "type": "mcp_call",
+      "tool": "get_project_standards",
+      "params": {},
+      "description": "Fetch project standards for screening (optional)",
+      "on_error": "warn_and_continue"
+    },
+    {
+      "type": "agent_task",
+      "instruction_file": "preflight-and-readiness.md",
+      "description": "Initialize run directory, classify readiness and scope"
+    },
+    {
+      "type": "agent_task",
+      "instruction_file": "research-decision.md",
+      "description": "Decide which research tools to run for this idea"
+    },
+    {
+      "type": "agent_task",
+      "instruction_file": "execute-research.md",
+      "description": "Execute the planned research and produce the research pack",
+      "on_error": "warn_and_continue"
+    },
+    {
+      "type": "agent_task",
+      "instruction_file": "duplicate-and-context-scan.md",
+      "description": "Scan Jira for duplicate/related tickets"
+    },
+    {
+      "type": "agent_task",
+      "instruction_file": "screen-and-resolve.md",
+      "description": "Build standards checklist and resolve open questions"
+    },
+    {
+      "type": "agent_task",
+      "instruction_file": "draft-and-critique.md",
+      "description": "Draft the ticket(s) and run a hygiene/critique pass"
+    },
+    {
+      "type": "agent_task",
+      "instruction_file": "upload-and-track.md",
+      "description": "Upload to Jira and track the new ticket(s) idempotently"
+    }
+  ]
+}

package/pipelines/implement-ticket.json

@@ -22,7 +22,7 @@
     },
     {
       "type": "agent_task",
-      "instruction_file": "execute-plan.md",
+      "instruction_file": "execute-plan-sectioned.md",
       "description": "Execute the implementation plan"
     },
     {
@@ -58,5 +58,31 @@
       "instruction_file": "monitor-ci-checks.md",
       "description": "Monitor CI checks and report results"
     }
-  ]
+  ],
+  "tiered_executor_policy": {
+    "supported_hosts": ["claude_code"],
+    "sequential_only": true,
+    "tier_model_mapping": {
+      "cheap": "haiku",
+      "basic": "sonnet",
+      "premium": "opus"
+    },
+    "final_review_policy": {
+      "default": "premium_whole_diff_when_below_coordinator_tier_touched_code",
+      "skip_when": "entire_run_inline_default_at_coordinator_tier"
+    },
+    "escalation_policy": {
+      "max_section_escalations": 1,
+      "allowed_hops": {
+        "cheap": "basic",
+        "basic": "premium"
+      },
+      "final_review_fix_reverify_passes": 1
+    },
+    "budget_policy": {
+      "cache_hit_rate_source": "measurement_spike_go_marker",
+      "default_cache_hit_rate": 0.0,
+      "abort_mode": "inline_default"
+    }
+  }
 }

package/smoke-test/SMOKE-TEST.md

@@ -0,0 +1,511 @@
+# Bridge API MCP Cross-Platform Smoke-Test Runbook
+
+This runbook is executed **by an AI agent running inside a host** (Claude Code,
+Cursor, OpenAI Codex, Windsurf, or VS Code/Copilot). The agent calls real Bridge
+API MCP tools through the host's own MCP client and records a PASS/FAIL verdict
+for each one in a markdown report. The point is to prove that the MCP server
+actually works end-to-end *inside this specific host*, not just that the server
+process started.
+
+## Sequestered, not part of the tool surface
+
+- This runbook **adds no MCP tool.** It is documentation the host agent reads and
+  follows; it never registers a `registerTool(...)` call.
+- The server's **registered MCP tool set remains unchanged** at its existing
+  count. Running the smoke test does not add, remove, or rename any tool.
+- The companion `/smoke-test-mcp` command is **opt-in**: it is not scaffolded by
+  the default `--init` flow and must be copied in manually (see
+  `smoke-test-mcp.md`).
+
+## Why protocol-level success is not enough
+
+**Protocol-level MCP success is insufficient** to judge a tool as passing. The
+server's `handleResponse()` helper (`mcp_server/src/index.ts`) does **not throw**
+on HTTP errors — it **returns HTTP errors as JSON text content**:
+
+```json
+{ "error": "NOT_FOUND", "status": 404, "message": "..." }
+```
+
+So an MCP call can "succeed" at the protocol level (the host returns content with
+no transport error) while the content itself describes a failure. **Agents must
+inspect the returned content** rather than treating invocation success as `PASS`.
+
+### Content-based grading
+
+For every tool result:
+
+1. Read the returned text content.
+2. **Parse the JSON text when possible.** If it parses, inspect fields such as
+   `error`, `status`, `message`, and any known success fields for that tool
+   (e.g. `status: "decision_page_generated"`, a `file_path`, a `task_id`).
+3. If the content is plain text (e.g. `get_docs_dir` returns a bare path), check
+   for expected success markers or saved-file path evidence.
+4. Only then assign a verdict from the vocabulary below.
+
+---
+
+## Phase 0 — Prerequisites
+
+Before running anything, confirm:
+
+- The host has the `bridge-api` MCP server configured and connected (the tools
+  are visible to the agent).
+- You can call `ping` and get a non-error result (this is the first metadata
+  check in Phase 2).
+- You have permission to write files under the host's project (the report and
+  the local-write canary file are written locally).
+
+### Environment variables
+
+The server reads these environment variables:
+
+| Variable | Meaning |
+|---|---|
+| `BAPI_BASE_URL` | Bridge API base URL |
+| `BAPI_REPO_NAME` | Jira project/repository identifier |
+| `BAPI_API_KEY` | API key used for all calls |
+| `BAPI_PROJECT_ROOT` | Absolute path to the project root |
+| `BAPI_DOCS_DIR` | Local docs directory (default `docs/tmp`) for file output |
+
+Project-root resolution detail: in the server, `PROJECT_ROOT` **falls back to
+`process.cwd()`** when `BAPI_PROJECT_ROOT` is unset, and `BAPI_DOCS_DIR` is then
+resolved relative to that root. **Codex-like hosts may need `BAPI_PROJECT_ROOT`
+set manually**, because the working directory the host launches the server from
+is not guaranteed to be the project root.
+
+---
+
+## Phase 1 — Input Collection (collect inputs before starting)
+
+Ask the user for the following before making any tool calls:
+
+1. **Required:** a **read-only Jira ticket key** that the configured
+   `BAPI_API_KEY` can read (used for the Tier 1 read-only checks). It only needs
+   to be readable — comments, attachments, tracked state, and generated
+   artifacts are all optional.
+2. **Optional:** a **config field name** (for `get_config_field`).
+3. **Optional:** a **pipeline name** (for `get_pipeline_recipe`).
+4. **Optional:** an **attachment identifier or filename** (for
+   `download_attachment` / `list_attachments`).
+5. **Optional:** any **artifact or task IDs** (e.g. a `task_id`, `brainstorm_id`,
+   or commit ref) for retriever and CI tools.
+6. **Required decision:** explicit **Tier 3 consent** (Tier 3 spends tokens and
+   is skipped without it).
+
+### Optional input omission rule
+
+If the user does not supply an optional input, **omit that parameter from the MCP
+call entirely.** Do **not** send it as `null`, an empty string `""`, or a
+placeholder value. Tools whose only input is missing are graded
+`SKIP_USER_INPUT`, not `FAIL`.
+
+### Report redaction rule
+
+Never write **`BAPI_API_KEY`**, **authorization headers**, **raw stack traces**,
+or **raw protocol noise** into the report. Base URL and repo name may be
+recorded; secrets must be redacted. (Repeated in the report template below.)
+
+---
+
+## Phase 2 — Metadata Discovery
+
+Run these first; their output populates the report's metadata header and anchors
+all local writes:
+
+1. `ping` — connectivity + API key validity.
+2. `get_my_role` — the role of the configured key.
+3. **`get_docs_dir` — call this as one of the first calls.** Store the **exact
+   returned docs path** verbatim. This path is the **root for every local write**
+   in this run (the report and the local-write canary file). Do not recompute it
+   from environment variables.
+
+### Path discipline
+
+- Every local write **must be anchored to the exact docs directory returned by
+  `get_docs_dir`.**
+- Before recording any local write as evidence, **verify the path is absolute and
+  resides under the returned docs directory** (a strict prefix containment
+  check). A path outside that directory is a `FAIL` for that step.
+- The report file path is:
+
+  ```
+  <docs_dir>/smoke-test/REPORT-<host>-<timestamp>.md
+  ```
+
+  - `<host>` sanitization: replace every character outside `[A-Za-z0-9._-]` with
+    `-`, collapse repeated separators, and trim leading/trailing separators.
+  - `<timestamp>` is a filesystem-safe **UTC** timestamp such as
+    `YYYYMMDDTHHMMSSZ` (e.g. `20260525T174500Z`).
+
+---
+
+## Verdict Vocabulary
+
+### Per-tool verdicts
+
+| Verdict | Meaning |
+|---|---|
+| `PASS` | Content confirms success. |
+| `PASS_EXPECTED_404` | Artifact retriever returned a clean 404 indicating the artifact is simply absent. |
+| `FAIL` | Content describes an error, or required content is missing. |
+| `SKIP_USER_INPUT` | A required input for this tool was not supplied. |
+| `SKIP_NOT_APPROVED` | Tier 3 (or another gated tool) was not consented to. |
+| `SKIP_NOT_APPLICABLE` | Tool is disabled/not applicable in this environment. |
+| `WARN` | Non-blocking anomaly, including host serialization quirks. |
+
+### Overall verdicts
+
+`PASS`, `PASS_WITH_WARNINGS`, `FAIL`, `INCOMPLETE`.
+
+### Grading rules
+
+- Parsed content containing an **`error` key** is a **`FAIL`**, *unless* it is an
+  explicitly expected clean-empty condition (an empty artifact retriever).
+- Parsed **`status >= 400`** is a **`FAIL`**, *except* a clean expected **404**
+  for an artifact retriever or optional-empty retriever, which is
+  `PASS_EXPECTED_404`.
+- **`401` and `403` are always `FAIL`.**
+- **`5xx` is always `FAIL`**, *except* `poll_ci_checks` returning a
+  `TOOL_DISABLED` / `503` self-disable response, which is `SKIP_NOT_APPLICABLE`.
+- **Expected-empty artifact retrievers** that return a clean 404 (no artifact
+  yet) are **`PASS_EXPECTED_404`**.
+- **Artifact retrievers that return valid non-empty content** are **`PASS`**
+  (not `PASS_EXPECTED_404`).
+- **Host/tool invocation errors**, **schema validation failures outside the
+  documented host-risk probes**, **empty responses where non-empty content is
+  required**, and **failure-prefixed text** such as `Failed to request ...` are
+  all **`FAIL`**.
+- A **host boolean-serialization rejection during the dedicated boolean probe**
+  (Phase 7) is a **`WARN`** for host behavior — **not** an MCP server `FAIL`.
+
+---
+
+## Phase 3 — Default Pass
+
+The default pass is the release-blocking fast path. It runs all Tier 0 tools by
+default plus the read-only ticket checks when a readable ticket was supplied.
+
+### All Tier 0 tools run by default
+
+`ping`, `get_my_role`, `get_docs_dir`, `get_project_standards`,
+`list_config_fields`, `list_pipelines`, `get_parse_status`,
+`list_pipeline_runs`.
+
+(The "fast-pass" list is the minimum release-blocking subset; the tier
+definition is "always run", so do not exclude the other Tier 0 tools.)
+
+### Default read-only ticket checks (when a readable ticket is supplied)
+
+Run `get_ticket`, `get_comments`, and `get_plan` against the user-supplied
+ticket.
+
+- **`get_comments` is preferred**; **`list_attachments` is the fallback** if
+  comments are unavailable for the selected ticket.
+- **`get_plan` must be called with a real boolean `save_locally: false`** (a true
+  JSON boolean, not the string `"false"`).
+- Grade `get_plan` as **`PASS`** if it returns valid plan content, or
+  **`PASS_EXPECTED_404`** if it returns a clean missing-plan 404.
+
+### Default overall verdict
+
+The default run can be overall **`PASS`** when **all required default calls are
+`PASS` or `PASS_EXPECTED_404`** and the optional tools are skipped for lack of
+input or consent. Add `PASS_WITH_WARNINGS` if any `WARN` was recorded. Reserve
+`INCOMPLETE` for missing required metadata, interrupted execution, or a
+default-set tool that did not run.
+
+---
+
+## Phase 4 — Optional Tier 1
+
+Tier 1 tools are read-only but require an input. Run each only when the user
+supplied the relevant input; otherwise record `SKIP_USER_INPUT`.
+
+- `get_tickets` — a query/filter (a default project query is acceptable).
+- `get_ticket_state`, `get_jira_transitions`, `resolve_target_status` — the
+  ticket key.
+- `get_config_field` — the optional config field name.
+- `get_pipeline_recipe` — the optional pipeline name.
+- `list_attachments` / `download_attachment` — the optional attachment input.
+- The artifact retrievers `get_architecture`, `get_clarifying_questions`,
+  `get_ticket_critique`, `get_reimplement_context`, `get_deep_research`,
+  `get_brainstorm` — grade a clean empty result as `PASS_EXPECTED_404` and valid
+  content as `PASS`.
+- `poll_ci_checks` — see the matrix note; `SKIP_NOT_APPLICABLE` when CI is not
+  configured.
+
+---
+
+## Phase 5 — Tier 2 Canary (`generate_decision_page`)
+
+Tier 2 is the **local-only file-write canary** and **always runs**. It forces a
+real HTML file write instead of the no-decision fast path (which writes nothing).
+
+Call `generate_decision_page` with this **verbatim** payload. It is a fixed,
+local-only fixture: the handler validates `ticket_key` against
+`^[A-Za-z][A-Za-z0-9_-]*$` (which `BAPI-SMOKE` satisfies) and writes
+`<docs_dir>/review/<ticket_key>-decisions.html` **without ever calling Jira**, so
+the literal `BAPI-SMOKE` key is safe and deterministic across all hosts. Do not
+substitute the user's ticket key.
+
+```json
+{
+  "ticket_key": "BAPI-SMOKE",
+  "actionable_items": [
+    {
+      "id": "E-1",
+      "question": "Should the smoke-test canary write a real decision-page HTML file?",
+      "original_question": "Does generate_decision_page write a local file when given one actionable item?",
+      "why_it_matters": "Proves the MCP server's local file-write path works end to end inside this host.",
+      "recommendation_explanation": "Writing a real file is the only way to verify the disk-write canary instead of taking the no-op no-decisions fast path.",
+      "codebase_evidence": "generate_decision_page writes <docs_dir>/review/<ticket_key>-decisions.html when actionable_items is non-empty (mcp_server/src/index.ts generate_decision_page handler).",
+      "source": "BAPI-314 smoke-test runbook — Tier 2 canary",
+      "recommendation_index": 0,
+      "options": ["Write the decision page file", "Skip the file write"],
+      "option_consequences": [
+        "A real HTML file is created under the docs directory — the desired canary signal.",
+        "No file is written and the canary cannot prove local writes — undesired."
+      ]
+    }
+  ],
+  "clear_improvements": [
+    {
+      "id": "CI-1",
+      "title": "Anchor all local writes under get_docs_dir",
+      "action": "Resolve the report path and the canary file path from the exact get_docs_dir result.",
+      "confidence": "high",
+      "source": "BAPI-314 smoke-test runbook — path discipline"
+    }
+  ]
+}
+```
+
+### Tier 2 grading
+
+- **`PASS`**: the response JSON contains `status: "decision_page_generated"`
+  **and** an **absolute** `file_path` that resides **under the exact
+  `get_docs_dir` result**. Verify containment by checking that `file_path`
+  begins with the stored docs directory prefix.
+- **`FAIL`**: the response is `no_decisions_needed`, **or** `file_path` is absent,
+  **or** the path is **not absolute**, **or** the path is **outside the returned
+  docs directory**.
+
+---
+
+## Phase 6 — Optional Tier 3
+
+**Tier 3 is skipped by default and requires explicit user consent**, because it
+**may spend tokens** and can take **up to roughly 15 minutes**. Without consent,
+record each Tier 3 tool as `SKIP_NOT_APPROVED`.
+
+Ask for one explicit Tier 3 consent decision; if granted, the user may pick which
+flows to run. Use **bounded polling with increasing intervals and a maximum wait
+of about 15 minutes** for any async flow.
+
+### Synchronous Tier 3 tool
+
+- **`second_opinion` is synchronous and token-costing.** It blocks and returns
+  its result directly — it is **not** an async request/get flow. Do not try to
+  capture an ID for it.
+
+### Async request/get Tier 3 tools
+
+| Submit tool | Returns | Retrieve with |
+|---|---|---|
+| `request_deep_research` | a **`task_id`** | `get_deep_research` |
+| `request_brainstorm` | a **`brainstorm_id`** | `get_brainstorm` |
+| `request_plan_generation` | (ticket-key based) | `get_plan` |
+| `request_architecture` | (ticket-key based) | `get_architecture` |
+| `request_clarifying_questions` | (ticket-key based) | `get_clarifying_questions` |
+| `request_ticket_critique` | (ticket-key based) | `get_ticket_critique` |
+| `request_reimplement_context` | (ticket-key based) | `get_reimplement_context` |
+
+- **`request_ticket_review`** is the combined submit side for review. There is
+  **no dedicated `get_*` review-retrieval tool** for it. Retrieve its results
+  with **`get_clarifying_questions`** and **`get_ticket_critique`**, or pass
+  `wait_for_result: true` **only if explicitly approved**.
+
+---
+
+## Phase 7 — Host Probes (host-specific probes)
+
+Record evidence for the cross-platform risks that differ between Claude Code,
+Cursor, Codex, Windsurf, and VS Code/Copilot.
+
+### Boolean serialization probe
+
+Target an artifact retriever with a **real `save_locally` boolean** — preferably
+**`get_plan` with `save_locally: false`** when a plan artifact exists.
+
+- `get_plan`'s `save_locally` is a strict `z.boolean().optional()`; the schema
+  performs **no string coercion**. If the **host serializes `false` as the string
+  `"false"`** and Zod rejects it with a 400, record **`WARN`** for the host's
+  serialization behavior — this is the cross-platform quirk the probe exists to
+  surface, **not** an MCP server `FAIL`.
+- If **no artifact exists** and the probe returns a clean 404, record
+  **`SKIP_NOT_APPLICABLE`**.
+- If content exists and a **file is saved despite `save_locally: false`**, record
+  **`WARN`**.
+
+### Optional-parameter omission probe
+
+Record whether the agent **avoided sending `null`, empty strings, or
+placeholders** for `.optional()` schema fields throughout the run.
+
+### Codex project-root probe
+
+Record whether **`BAPI_PROJECT_ROOT` is set** and whether **`get_docs_dir`
+resolves to the expected project-root-relative docs directory**.
+
+### Windows separator probe
+
+Record the **returned path formats** (separator style) and **still perform the
+containment checks** against the exact docs directory regardless of separator
+differences.
+
+### Tier 3 async round-trip probe
+
+Only with explicit consent, run one `request_*` → `get_*` round trip end-to-end
+(bounded polling) to prove the async pattern works in this host.
+
+---
+
+## Phase 8 — Report Writing
+
+Write the report to `<docs_dir>/smoke-test/REPORT-<host>-<timestamp>.md` using the
+template below. Create the `<docs_dir>/smoke-test/` directory if needed. Use the
+host's normal file-write capability (no new MCP tool is involved).
+
+### Report template
+
+```markdown
+# MCP Smoke-Test Report
+
+## Metadata
+- Host name / version: <host and version>
+- OS: <operating system>
+- MCP package version: <version if known>
+- Base URL: <BAPI_BASE_URL>
+- Repo name: <BAPI_REPO_NAME>
+- Project root: <BAPI_PROJECT_ROOT or resolved root>
+- Docs dir: <exact get_docs_dir result>
+- Role: <get_my_role result>
+- Test ticket: <user-supplied ticket key>
+- Tier 3 consent: <yes/no>
+
+## Summary counts
+- PASS: <n>
+- PASS_EXPECTED_404: <n>
+- FAIL: <n>
+- SKIP_USER_INPUT: <n>
+- SKIP_NOT_APPROVED: <n>
+- SKIP_NOT_APPLICABLE: <n>
+- WARN: <n>
+
+## Overall verdict
+<PASS | PASS_WITH_WARNINGS | FAIL | INCOMPLETE>
+
+## Per-tool results
+| Tier | Tool | Inputs | Expected result | Actual summary | Verdict | Evidence | File paths | Duration | Notes |
+|---|---|---|---|---|---|---|---|---|---|
+| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
+
+## Host-specific probes
+- Boolean serialization probe: <result>
+- Optional-parameter omission probe: <result>
+- Codex project-root probe: <result>
+- Windows separator probe: <result>
+- Tier 3 async round-trip probe: <result or skipped>
+
+## Path evidence
+- get_docs_dir: <exact path>
+- Tier 2 HTML file path: <absolute path under docs dir>
+- Report file path: <absolute path under docs dir>
+
+## Cleanup
+v1 default execution creates **no Jira/server-side cleanup requirement**. The
+Tier 2 generated HTML decision page is **retained as evidence** that local writes
+work. (This section is reserved for future Tier 4 runs.)
+
+## Redaction note
+This report excludes **secrets, authorization headers, API keys, stack traces,
+and raw protocol noise.** Sensitive values are redacted.
+```
+
+---
+
+## Phase 9 — Cleanup
+
+- v1 default execution requires **no Jira/server-side cleanup**.
+- The Tier 2 `generate_decision_page` HTML file is **kept** as evidence; do not
+  delete it unless the user asks.
+- This section is reserved for future Tier 4 (mutating) runs, which are out of
+  scope for v1.
+
+---
+
+## Full 55-Tool Smoke Tier Matrix
+
+Every registered MCP tool appears **exactly once** below with its smoke tier.
+Tier 4 (mutating/hazardous) tools are **deferred in v1**.
+
+Coverage reconciliation: **8 + 18 + 1 + 10 + 18 = 55**.
+
+| Tier | Tool | Default action / expected-empty / special handling |
+|---|---|---|
+| Tier 0 | `ping` | Zero-input read; always run. |
+| Tier 0 | `get_my_role` | Zero-input read; always run. |
+| Tier 0 | `get_docs_dir` | Zero-input read; always run; call first to anchor writes. |
+| Tier 0 | `get_project_standards` | Zero-input read; always run. |
+| Tier 0 | `list_config_fields` | Zero-input read; always run. |
+| Tier 0 | `list_pipelines` | Zero-input read; always run. |
+| Tier 0 | `get_parse_status` | Zero-input read; always run. |
+| Tier 0 | `list_pipeline_runs` | Zero-input read; always run. |
+| Tier 1 | `get_tickets` | Read-only; needs a query/filter. |
+| Tier 1 | `get_ticket` | Read-only; needs ticket key (default-pass tool). |
+| Tier 1 | `get_comments` | Read-only; needs ticket key (preferred default-pass tool). |
+| Tier 1 | `get_plan` | Artifact retriever; `PASS` with content, `PASS_EXPECTED_404` when cleanly empty; boolean probe target. |
+| Tier 1 | `get_architecture` | Artifact retriever; `PASS_EXPECTED_404` when cleanly empty. |
+| Tier 1 | `get_clarifying_questions` | Artifact retriever; `PASS_EXPECTED_404` when cleanly empty. |
+| Tier 1 | `get_ticket_critique` | Artifact retriever; `PASS_EXPECTED_404` when cleanly empty. |
+| Tier 1 | `get_reimplement_context` | Artifact retriever; `PASS_EXPECTED_404` when cleanly empty. |
+| Tier 1 | `get_deep_research` | Artifact retriever; `PASS_EXPECTED_404` when cleanly empty. |
+| Tier 1 | `get_brainstorm` | Artifact retriever; `PASS_EXPECTED_404` when cleanly empty. |
+| Tier 1 | `get_ticket_state` | Read-only; needs ticket key. |
+| Tier 1 | `get_jira_transitions` | Read-only; needs ticket key. |
+| Tier 1 | `resolve_target_status` | Read-only; needs ticket key. |
+| Tier 1 | `get_config_field` | Read-only; needs a config field name. |
+| Tier 1 | `list_attachments` | Read-only; needs ticket key; comments-fallback tool. |
+| Tier 1 | `download_attachment` | Tier 1 network read; secondary **path-canary** — saves locally only when an attachment input is supplied; omit `file_path` or keep any override under `get_docs_dir`. |
+| Tier 1 | `poll_ci_checks` | `SKIP_NOT_APPLICABLE` when disabled with `TOOL_DISABLED`/503, or when `resolve_ci_checks` has not populated CI configuration. |
+| Tier 1 | `get_pipeline_recipe` | Read-only; needs a pipeline name. |
+| Tier 2 | `generate_decision_page` | Local-only file-write canary; always run with the verbatim payload above. |
+| Tier 3 | `second_opinion` | Synchronous, token-costing; opt-in. |
+| Tier 3 | `generate_image` | Synchronous, token/credit-costing; spends provider credits; opt-in. |
+| Tier 3 | `request_plan_generation` | Async (ticket-key based); retrieve with `get_plan`; opt-in. |
+| Tier 3 | `request_architecture` | Async (ticket-key based); retrieve with `get_architecture`; opt-in. |
+| Tier 3 | `request_clarifying_questions` | Async (ticket-key based); retrieve with `get_clarifying_questions`; opt-in. |
+| Tier 3 | `request_ticket_critique` | Async (ticket-key based); retrieve with `get_ticket_critique`; opt-in. |
+| Tier 3 | `request_ticket_review` | Async submit; retrieve with `get_clarifying_questions` + `get_ticket_critique`; opt-in. |
+| Tier 3 | `request_reimplement_context` | Async (ticket-key based); retrieve with `get_reimplement_context`; opt-in. |
+| Tier 3 | `request_deep_research` | Async; returns `task_id`; retrieve with `get_deep_research`; opt-in. |
+| Tier 3 | `request_brainstorm` | Async; returns `brainstorm_id`; retrieve with `get_brainstorm`; opt-in. |
+| Tier 4 | `create_ticket` | Mutating; deferred in v1. |
+| Tier 4 | `add_comment` | Mutating; deferred in v1. |
+| Tier 4 | `update_ticket_description` | Mutating; deferred in v1. |
+| Tier 4 | `upload_attachment` | Mutating; deferred in v1. |
+| Tier 4 | `track_ticket` | Mutating; deferred in v1. |
+| Tier 4 | `update_ticket_state` | Mutating; deferred in v1. |
+| Tier 4 | `update_jira_status` | Mutating; deferred in v1. |
+| Tier 4 | `update_config_field` | Mutating; deferred in v1. |
+| Tier 4 | `create_pull_request` | Mutating; deferred in v1. |
+| Tier 4 | `resolve_ci_checks` | Cache-mutating/orchestration; deferred in v1. |
+| Tier 4 | `run_pipeline` | Orchestration (can dispatch mutating tools); deferred in v1. |
+| Tier 4 | `resume_pipeline` | Orchestration; deferred in v1. |
+| Tier 4 | `delete_pipeline_run` | Mutating (deletes run state); deferred in v1. |
+| Tier 4 | `parse_repository` | Hazardous (Pinecone index); deferred in v1. |
+| Tier 4 | `regenerate_directory_map` | Hazardous; deferred in v1. |
+| Tier 4 | `run_full_automation` | Orchestration (dispatches mutating child pipelines / spawns worktrees); deferred in v1. |
+| Tier 4 | `resume_full_automation` | Orchestration; deferred in v1. |
+| Tier 4 | `record_tiered_section_metric` | Writes server-side telemetry state (tiered_section_metrics row); deferred in v1. |