@bridge_gpt/mcp-server 0.2.25 → 0.2.27

package/smoke-test/SMOKE-TEST.md

@@ -1,560 +0,0 @@
-# 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 `config_field` with operation `"get"`).
-3. **Optional:** a **pipeline name** (for `get_pipeline_recipe`) — either a
-   no-variable pipeline name (e.g. `learn-repository`) or, for a
-   variable-declaring pipeline, the variable values it needs (e.g. a
-   `ticket_key`).
-4. **Optional:** an **attachment identifier or filename** (for `attachment` with operation `"download"` or `"list"`).
-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`.
-
-### Heavy-read truncation grading
-
-There are **five heavy-read tools** whose successful oversized output is saved to
-disk before a truncated inline preview is returned: `get_project_standards`,
-`get_tickets`, `get_ticket`, `get_comments`, and `attachment` (operation: `"list"`).
-
-- When a heavy-read response begins with `[Response truncated. Full response
-  saved locally.]` and carries a `Saved to <path>` note, grade it **`PASS`** as
-  long as the saved `<path>` is contained under the `get_docs_dir` result. The
-  truncation banner is the **expected** large-payload behavior, never a `FAIL`.
-- `get_project_standards` is a zero-input read that may exceed the inline
-  threshold; when it does, the full payload is saved under a `project-standards/`
-  subdirectory of the docs directory and only a truncated preview is returned
-  inline.
-- To exercise the truncation banner live, point the run at a known-large fixture
-  — a busy ticket with long comments, a broad `get_tickets` query, or a repo with
-  large project standards.
-
----
-
-## 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_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**; **`attachment` (operation: `"list"`) 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.
-- `config_field` (operation: `"get"`) — the optional config field name.
-- `get_pipeline_recipe` — a pipeline name. When no variables are supplied, use a
-  no-variable pipeline such as `learn-repository` as the smoke target. A
-  variable-declaring pipeline (e.g. a ticket-based pipeline) requires a
-  `variables` map such as `{ "ticket_key": "<user ticket>" }`. A `400
-  BAD_REQUEST` with `Missing required variable(s)` is **working as designed**, not
-  a server fault — rerun with the required variables or pick a no-variable
-  pipeline.
-- `attachment` (operation: `"list"` or `"download"`) — the optional attachment input.
-- The clean-empty artifact retrievers `get_architecture`,
-  `get_clarifying_questions`, `get_ticket_critique` — grade a clean empty result
-  as `PASS_EXPECTED_404` and valid content as `PASS`.
-- `get_reimplement_context` — can return **live-assembled, non-empty content**
-  even for an untracked or previously unprocessed ticket. Grade valid returned
-  content as `PASS`; a clean 404 is `PASS_EXPECTED_404`. It is **not** a
-  clean-empty-only retriever.
-- `get_ticket_state` — in a v1 read-only run this can only confirm the clean
-  "not tracked" 404 path unless a prior state-populating submit has occurred.
-  Full lifecycle-state coverage requires `track_ticket`, which remains a deferred
-  Tier 4 mutating tool.
-- `get_deep_research` — requires a `task_id` produced by `request_deep_research`.
-  When Tier 3 is skipped and no ID exists, record `SKIP_USER_INPUT`.
-- `get_brainstorm` — requires a `brainstorm_id` produced by `request_brainstorm`.
-  When Tier 3 is skipped and no ID exists, record `SKIP_USER_INPUT`.
-- `poll_ci_checks` — an `available:true` envelope with `checks:[]`,
-  `all_complete:true`, and `all_passed:true` is a `PASS`. The `TOOL_DISABLED` /
-  `503` self-disable branch is `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.
-
-### Single-call Tier 3 tool
-
-- **`second_opinion` returns its result in one call and is token-costing.** The
-  backend is now async (submit → poll → result, so a slow opinion no longer trips
-  the 30s Heroku request timeout / H12), but the tool **absorbs that polling
-  internally** — it still returns the reply directly. It is **not** an async
-  request/get flow: do not try to capture an ID for it. If an opinion is still
-  processing after ~5 minutes, the tool returns a **recoverable-result message**
-  (with the `request_id` and a `GET /llm/second-opinion/{id}/result` URL) rather
-  than failing — treat that as `PASS`, not an error.
-
-### 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 62-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: **7 + 19 + 1 + 13 + 22 = 62** (BAPI-443 Phase 3a: `list_config_fields` merged into `config_field`; `get_config_field`/`list_attachments`/`download_attachment` merged into `config_field`/`attachment`; BAPI-474 added `materialize_fresh_base` + `cleanup_fresh_base` to Tier 4; BAPI-563 added `visual_diff` to Tier 4; BAPI-523 added `estimate_epic` to Tier 3).
-
-| 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 heavy read; always run; may save/truncate oversized output under `project-standards/`. |
-| 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_ticket_model_tier` | Read-only; needs ticket key; returns a coarse model tier (`cheap`/`basic`/`premium`) for start-tickets routing — `source:"fallback"` with a null tier is a clean `PASS`. |
-| 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_doc` | Artifact retriever (tdd/fsd/prd via `doc_type`); `PASS_EXPECTED_404` when cleanly empty. |
-| Tier 1 | `get_prd` | Artifact retriever (Product Requirements Document); `PASS_EXPECTED_404` when cleanly empty. |
-| Tier 1 | `get_install_manifest` | Read-only; returns the easy-install bootstrap manifest + signed snapshot token; a clean 404 (no config row) is `PASS_EXPECTED_404`. |
-| 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; valid live-assembled content is `PASS`; a clean 404 is `PASS_EXPECTED_404` — the clean 404 is not the only expected outcome. |
-| Tier 1 | `get_deep_research` | Artifact retriever; requires a Tier 3-produced `task_id`; `PASS_EXPECTED_404` when cleanly empty. |
-| Tier 1 | `get_brainstorm` | Artifact retriever; requires a Tier 3-produced `brainstorm_id`; `PASS_EXPECTED_404` when cleanly empty. |
-| Tier 1 | `get_ticket_state` | Read-only; needs ticket key; v1 read-only reaches the clean "not tracked" 404; full state requires deferred Tier 4 `track_ticket`. |
-| Tier 1 | `get_jira_transitions` | Read-only; needs ticket key. |
-| Tier 1 | `resolve_target_status` | Read-only; needs ticket key. |
-| Tier 1 | `poll_ci_checks` | `available:true` with empty or populated checks is `PASS`; `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 plus required variables for variable-declaring pipelines; use `learn-repository` as the no-variable smoke target. |
-| Tier 2 | `generate_decision_page` | Local-only file-write canary; always run with the verbatim payload above. |
-| Tier 3 | `second_opinion` | Single-call (absorbs async polling under the hood — H12-safe); token-costing; opt-in. A ~5-min recoverable-result message is `PASS`, not a failure. |
-| 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 | `create_doc` | Async (ticket-key based; `doc_type` tdd/fsd/prd); retrieve with `get_doc`; opt-in. |
-| Tier 3 | `request_prd` | Async (ticket-key based; Product Requirements Document); retrieve with `get_prd`; 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 3 | `estimate_epic` | Synchronous, token-costing epic estimation orchestrator (`epic_key` or explicit `ticket_keys`); returns the estimate in one call; 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 | `attachment` | Discriminated-union: `upload`/`download`/`list`; classified Tier 4 (upload is 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 | `config_field` | Discriminated-union: `get`/`update`/`list`; classified Tier 4 (update is 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 | `apply_install_manifest` | Mutating (atomically writes easy-install config across the four config tables); deferred in v1. |
-| Tier 4 | `persist_routing_credential` | Mutating (writes the routing credential to the user-scoped store `~/.config/bridge/credentials.json`); deferred in v1. |
-| Tier 4 | `materialize_fresh_base` | Network + filesystem side effects (`git fetch` + `git archive` into a temp dir); deferred in v1. |
-| Tier 4 | `cleanup_fresh_base` | Mutating (deletes a review workspace temp directory); deferred in v1. |
-| Tier 4 | `visual_diff` | Launches a headless browser, opens `target_url`, and writes a local heatmap artifact (network + browser + filesystem side effects); deferred in v1. |

package/smoke-test/smoke-test-mcp.md

@@ -1,23 +0,0 @@
-# Smoke Test MCP
-
-Run the Bridge API MCP cross-platform smoke test inside this host. This command
-is a **thin pointer** — it does not contain the test logic itself.
-
-## What to do
-
-1. Locate and read the canonical runbook **`SMOKE-TEST.md`** from the same
-   `smoke-test/` directory these assets ship in, then execute it step by step.
-   - **Local repo development:** `mcp_server/smoke-test/SMOKE-TEST.md`
-   - **Package consumers:** `node_modules/@bridge_gpt/mcp-server/smoke-test/SMOKE-TEST.md`
-2. Follow `SMOKE-TEST.md` exactly: it is **authoritative**. Collect inputs, run
-   the tiered tool checks, grade each result by inspecting response content, and
-   write the report.
-3. Write the report **under the docs directory returned by `get_docs_dir`** — at
-   `<docs_dir>/smoke-test/REPORT-<host>-<timestamp>.md`, as the runbook specifies.
-
-## Do not duplicate the runbook
-
-This command must **not** restate or re-derive the runbook's logic. `SMOKE-TEST.md`
-owns the tier model, the verdict rules, the Tier 2 canary payload, the host
-probes, the full tool matrix, and the report template. If `SMOKE-TEST.md` and
-this file ever disagree, **`SMOKE-TEST.md` wins.**