@bridge_gpt/mcp-server 0.1.12 → 0.1.13

package/build/commands.generated.js

@@ -15,7 +15,7 @@ export const COMMANDS = {
     "plan-ticket.md": "Generate an implementation plan for a Jira ticket, wait for the result, and save it locally.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nExecute all steps in this command as a simple linear sequence of MCP tool calls.\n\n## Step 1 — Parse Arguments\n\n1. **Parse `$ARGUMENTS`**: Extract a required `ticket_key`, an optional `--second-opinion` flag, and an optional `--provider` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--second-opinion` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `second_opinion_value`.\n   - If `--second-opinion` appears without a provider name following it (or is the last token), set `second_opinion_value = \"auto\"`.\n   - If `--second-opinion` is absent, set `second_opinion_value = null`.\n   - If `--provider` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `provider_value`.\n   - If `--provider` appears without a valid provider name following it (or is the last token), stop immediately and report: \"Usage error: --provider requires a provider name (openai, anthropic, or gemini).\"\n   - If `--provider` is absent, set `provider_value = null`.\n   - If both `--second-opinion` and `--provider` are present, `--second-opinion` takes precedence (set `provider_value = null`).\n   - The remaining token (after removing flags and their arguments) is the `ticket_key`.\n   - If `ticket_key` is empty or missing, stop immediately and display:\n\n   ```\n   Usage: /plan-ticket <ticket_key> [--second-opinion [provider]] [--provider <name>] (e.g., /plan-ticket BAPI-150)\n   ```\n\n## Step 2 — Resolve Docs Directory\n\nCall the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n## Step 3 — Generate Plan\n\nCall the `request_plan_generation` MCP tool with:\n- `ticket_number`: the parsed `ticket_key`\n- `wait_for_result`: `true`\n- `save_locally`: `true`\n- `second_opinion`: set to `second_opinion_value` if non-null; omit entirely if null\n- `provider`: set to `provider_value` if non-null; omit entirely if null\n\nThis step may take 1-5 minutes while the backend processes the plan.\n\nIf the tool returns an error, stop immediately and display:\n\n```\nPlan generation failed: <error message from the tool>\n```\n\n## Step 4 — Confirm Success\n\nDisplay a confirmation message:\n\n```\nPlan generated successfully for <ticket_key>\nSaved to: {docs_dir}/plans/<ticket_key>-plan.md\n```\n\n## Final Summary\n\nDisplay a summary block:\n\n```\n## Plan Generation Report\n\n- **Ticket**: <ticket_key>\n- **Plan Status**: Generated successfully\n- **Local File**: {docs_dir}/plans/<ticket_key>-plan.md\n```\n\nOn failure at any step, stop immediately, display which step failed and the error details, and do not proceed.\n",
     "reimplement-ticket.md": "# Reimplement Ticket: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command retrieves the reimplement context for a previously-implemented Jira ticket via MCP, then implements follow-up changes inline. Use this for small follow-up requests on tickets that have already been through the plan+implement cycle.\n\nIf any critical stage fails (Stage 0 or Stage 1), stop immediately and report which stage failed and why.\n\n---\n\n# Instructions\n\nYou are executing a 4-stage pipeline to implement follow-up changes on a Jira ticket using assembled reimplement context. Execute all stages in sequence.\n\n## Stage 0 — Setup and Argument Parsing\n\n1. **Parse `$ARGUMENTS`**: Extract a required `ticket_key`, an optional `--second-opinion` flag, and an optional `--provider` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--second-opinion` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `second_opinion_value`.\n   - If `--second-opinion` appears without a provider name following it (or is the last token), set `second_opinion_value = \"auto\"`.\n   - If `--second-opinion` is absent, set `second_opinion_value = null`.\n   - If `--provider` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `provider_value`.\n   - If `--provider` appears without a valid provider name following it (or is the last token), stop immediately and report: \"Usage error: --provider requires a provider name (openai, anthropic, or gemini).\"\n   - If `--provider` is absent, set `provider_value = null`.\n   - If both `--second-opinion` and `--provider` are present, `--second-opinion` takes precedence (set `provider_value = null`).\n   - The remaining token (after removing flags and their arguments) is the `ticket_key`.\n   - If `ticket_key` is empty or does not match the expected format (one or more uppercase letters, a hyphen, and one or more digits), stop immediately and display:\n\n   ```\n   Invalid ticket key format: '<value>'. Expected format: PROJ-123 (uppercase letters, hyphen, digits).\n   Usage: /reimplement-ticket <ticket_key> [--second-opinion [provider]] [--provider <name>] (e.g., /reimplement-ticket BAPI-150)\n   ```\n\nThis stage is **critical** — stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 — Request and Retrieve Reimplement Context\n\nCall the `request_reimplement_context` MCP tool with:\n- `ticket_number`: the parsed `ticket_key` from Stage 0\n- `wait_for_result`: `true`\n- `save_locally`: `true`\n- `second_opinion`: set to `second_opinion_value` if it is non-null; omit the parameter entirely if `second_opinion_value` is null\n- `provider`: set to `provider_value` if it is non-null; omit the parameter entirely if `provider_value` is null\n\nIf the tool returns an error or 404 persists after polling, stop immediately and display:\n\n```\nFailed to retrieve reimplement context for <ticket_key>.\nThis may mean:\n- The ticket has not been previously processed by Bridge API\n- Background processing failed — check server logs\n- The ticket does not exist in Jira\n\nTry running /plan-ticket <ticket_key> first if this is a new ticket.\n```\n\nOn success, read and internalize the returned context markdown. This document contains:\n- A summary of changes (if applicable)\n- New/changed information since last processing (comments, description changes, attachments)\n- The original ticket description\n- The existing implementation plan (at the bottom, for reference only)\n\nThis stage is **critical** — stop immediately on failure. Do not proceed to Stage 2.\n\n## Stage 2 — Implement Follow-Up Changes\n\nExecute changes inline in this conversation. Work directly so the user can see all progress and approve tool calls.\n\nFollow these rules:\n\n1. **Focus on the new information.** The context document identifies what has changed since the last implementation. Focus your changes on addressing the new/changed requirements.\n2. **Reference the existing plan as supplementary guidance only.** The plan at the bottom of the context describes the original implementation, not the follow-up. Use it to understand the existing code structure, not as a step-by-step guide.\n3. **Make code changes** as directed by the new information.\n4. **Run tests and checks** to verify your changes don't break existing functionality.\n5. **Do NOT run `git commit` or `git push`.** Leave all changes uncommitted for developer review.\n6. **Scope guard**: If the follow-up changes are too large in scope (e.g., fundamentally restructuring the original implementation, touching more than 5-6 files, or requiring new infrastructure), stop and ask the user for guidance rather than attempting everything. Follow-up reimplementations should be small and targeted.\n7. **If a change is ambiguous or blocked**, note the issue clearly and continue with the next change rather than halting entirely.\n\nThis stage is **critical** — if a blocking error prevents further progress, stop and report the failure.\n\n## Stage 3 — Final Summary Report\n\nDisplay a structured report after all stages complete:\n\n```\n## Reimplement Complete\n\n**Ticket**: <ticket_key>\n\n**Changes Made**:\n- <brief summary of each change>\n\n**Developer Action Items**:\n- All changes are uncommitted. Review the changes with `git diff` before committing.\n- Run the project's test suite to verify nothing is broken before committing.\n\n**Warnings**:\n<If any issues arose during implementation (scope concerns, ambiguous requirements,\nfiles that couldn't be modified), list them here. If no warnings, omit this section.>\n```\n\n## Final Report\n\nOn success, display the structured report from Stage 3 confirming that the follow-up changes are complete.\n\nOn failure at any critical stage (Stage 0 or Stage 1), display which stage failed and the error details.\n",
     "review-ticket.md": "# Review Ticket\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command is recipe-driven. Do not call MCP tools directly -- the recipe determines which tools to call and with what parameters.\n\n1. Parse `$ARGUMENTS` to extract a single required `ticket_key` (e.g., `BAPI-123`). If `$ARGUMENTS` is empty or does not match the Jira key pattern (`[A-Z][A-Z0-9]+-\\d+`), stop immediately and display:\n   ```\n   Invalid ticket key format. Expected: PROJ-123\n   Usage: /review-ticket <ticket_key>\n   ```\n\n2. Call the `get_pipeline_recipe` MCP tool with:\n   - `pipeline`: `\"review-ticket\"`\n   - `variables`: `{ \"ticket_key\": \"<ticket_key>\" }`\n\n   If the tool returns an error, stop and report the failure.\n\n3. Read and strictly obey the `agent_instructions` field in the response. Execute each step in order, announcing each as **Step N of M: <description>**.\n\n4. After all steps complete, display a summary:\n   ```\n   ## Pipeline Complete\n\n   **Ticket**: <ticket_key>\n   **Steps executed**: N of M\n   **Status**: Success / Failed at step N\n   ```\n",
-    "run-tests.md": "Run the project's full test suite (unit, integration, and Playwright E2E), triage failures, fix test-code issues, and produce a structured health-check report in docs/tmp/testing/.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\n## Stage 0 — Argument Parsing and Setup\n\n1. **Parse `$ARGUMENTS`** for optional flags. Supported flags:\n   - `--skip-integration` — skip integration tests (they make real LLM calls)\n   - `--skip-playwright` — skip Playwright E2E tests (they require a running server)\n   - `--unit-only` — shorthand that implies both `--skip-integration` and `--skip-playwright`\n\n   Resolve flags to boolean variables:\n   - Start with: `run_integration = true`, `run_playwright = true`\n   - If `--unit-only` is present: set both to `false`\n   - If `--skip-integration` is present: set `run_integration = false`\n   - If `--skip-playwright` is present: set `run_playwright = false`\n   - Unknown flags: note them in the final report as \"Unrecognized flag ignored\" but do not fail\n\n2. **Generate a run timestamp** using the current date and time in `YYYY-MM-DD-HH-MM` format (e.g., `2026-03-10-14-35`). Store this as `run_timestamp`. Both output documents will use this value.\n\nThis stage has no failure conditions — proceed to Stage 1.\n\n## Stage 1 — Environment Setup\n\nRun the following command in the terminal:\n```\nmkdir -p docs/tmp/testing/\n```\nIf this fails, stop immediately and report: \"Cannot create output directory docs/tmp/testing/ — check permissions.\"\n\nVerify the Python venv is available:\n```\nsource .venv/bin/activate && python --version\n```\nIf the venv is not available, note \"venv not available\" in the report and skip unit and integration tests. Continue to Playwright stage if applicable.\n\n## Stage 2 — Unit Tests\n\nRun in the terminal:\n```\nsource .venv/bin/activate && pytest tests/pytest/ -v --tb=short\n```\n\nCapture the full output. Extract the pytest summary line (e.g., `47 passed, 3 failed in 12.4s`). For each failing test, apply the triage logic below, then record the result.\n\n## Stage 3 — Integration Tests\n\nIf `run_integration` is `false`, skip this stage and record: `Integration tests: SKIPPED (--skip-integration or --unit-only flag was set)`\n\nIf `run_integration` is `true`, run each subdirectory as a separate batch. **Continue to the next batch even if the current one has failures.**\n\nRun the following batches in order in the terminal:\n```\nsource .venv/bin/activate && pytest tests/integration/code_writer/ --run-integration -v -s\nsource .venv/bin/activate && pytest tests/integration/estimator/ --run-integration -v -s\nsource .venv/bin/activate && pytest tests/integration/ticket_updater/ --run-integration -v -s\nsource .venv/bin/activate && pytest tests/integration/routes/ --run-integration -v -s\nsource .venv/bin/activate && pytest tests/integration/db/ --run-integration -v -s\n```\n\nApply triage logic to any failures. Note: integration test failures involve real LLM behavior and are more likely to be implementation issues than test-code issues — apply extra caution before fixing.\n\n## Stage 4 — Playwright E2E Tests\n\nIf `run_playwright` is `false`, skip this stage and record: `Playwright tests: SKIPPED (--skip-playwright or --unit-only flag was set)`\n\nIf `run_playwright` is `true`, first check whether the server is running:\n```\ncurl -s -o /dev/null -w \"%{http_code}\" http://localhost:8000/ping\n```\n\nIf the status code is NOT `200`, skip Playwright and record:\n```\nPlaywright tests: SKIPPED — server not running.\nStart the server with: uvicorn main:app --reload\nThen re-run this command without --skip-playwright.\n```\n\nIf the server IS running, run each spec directory as a separate batch. **Continue to the next batch even if the current one has failures.**\n\n```\nnpx playwright test tests/playwright/setup/ --config=tests/playwright/playwright.config.js --reporter=list\nnpx playwright test tests/playwright/projects/ --config=tests/playwright/playwright.config.js --reporter=list\nnpx playwright test tests/playwright/optimize/ --config=tests/playwright/playwright.config.js --reporter=list\n```\n\nApply triage logic to any failures.\n\n## Triage Logic\n\nFor every failing test, examine the test file and the code it tests. Classify as ONE of the following:\n\n### TEST-CODE ISSUE — fix it directly\n\nClassify as a test-code issue if ANY of the following applies:\n- The test asserts against a hardcoded value that no longer matches current behavior (outdated mock data)\n- The test imports or calls a function that was renamed, moved, or removed\n- The test asserts on a response field that was restructured\n- The test expects a specific error message string that has since changed\n- A fixture or conftest references a removed table column or model field\n\n**Action**: Apply a minimal, targeted fix to the test file only. Then re-run just that failing test to confirm:\n```\nsource .venv/bin/activate && pytest path/to/test_file.py::test_function_name -v --tb=short\n```\nIf the re-run **still fails** after your fix, do not make further edits — escalate to implementation-code issue instead and revert your change.\n\n### IMPLEMENTATION-CODE ISSUE (or UNCERTAIN) — document it, do not fix\n\nClassify as an implementation issue if ANY of the following applies:\n- The production function raises an unexpected exception\n- A route handler returns the wrong status code for a documented behavior\n- Business logic produces incorrect output that the test correctly asserts against\n- You are not confident the test is wrong\n\n**Action**: Do NOT touch any files in `api/`, `src/`, `main.py`, or `db/`. Record this issue in the implementation-issues document.\n\n## Stage 5 — Write Output Documents\n\n### Document 1: Test Run Report (always write this)\n\nWrite to: `docs/tmp/testing/test-run-{run_timestamp}.md`\n\n```markdown\n# Test Run: {run_timestamp}\n\n## Configuration\n- Unit tests: RUN\n- Integration tests: RUN / SKIPPED — (reason)\n- Playwright tests: RUN / SKIPPED — (reason)\n\n## Unit Tests\n**Result**: X passed, Y failed\n**Duration**: ~Ns\n**Fixes applied**:\n- `path/to/test_file.py`: brief description of what was fixed\n- (or \"none\" if no fixes were needed)\n\n**Failures escalated as implementation issues**: N\n\n## Integration Tests\n\n### tests/integration/code_writer/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/integration/estimator/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/integration/ticket_updater/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/integration/routes/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/integration/db/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n## Playwright Tests\n\n### tests/playwright/setup/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/playwright/projects/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/playwright/optimize/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n## Overall Summary\n- Total test fixes applied: N\n- Suspected implementation issues found: N\n- Implementation issues document: docs/tmp/testing/implementation-issues-{run_timestamp}.md\n  (or \"not created — no issues found\")\n```\n\n### Document 2: Implementation Issues (only write if issues were found)\n\nIf at least one failure was escalated as an implementation-code issue, write to:\n`docs/tmp/testing/implementation-issues-{run_timestamp}.md`\n\n```markdown\n# Suspected Implementation Issues: {run_timestamp}\n\nThese test failures were NOT fixed. They may indicate bugs in production code.\nA developer should investigate each item before merging.\n\n## Issue 1\n- **Test**: `path/to/test_file.py::test_function_name`\n- **Tier**: unit / integration / playwright\n- **Failure message**: (paste the key assertion or exception line)\n- **Why not fixed**: (brief reasoning, e.g., \"production function raises KeyError on valid input\")\n\n## Issue 2\n...\n```\n\nIf no implementation issues were found, do NOT create this file.\n\n## Final Output\n\nAfter writing all documents, print this summary:\n\n```\nTest run complete: {run_timestamp}\nReport saved to: docs/tmp/testing/test-run-{run_timestamp}.md\nImplementation issues: docs/tmp/testing/implementation-issues-{run_timestamp}.md (if applicable)\nNo suspected implementation issues found. (if none)\n```\n",
+    "run-tests.md": "Run the project's full test suite (unit, integration, and Playwright E2E), triage failures, fix test-code issues, and produce a structured health-check report in docs/tmp/testing/.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\n## Stage 0 — Argument Parsing and Setup\n\n1. **Parse `$ARGUMENTS`** for optional flags. Supported flags:\n   - `--skip-integration` — skip integration tests (they make real LLM calls)\n   - `--skip-playwright` — skip Playwright E2E tests (they require a running server)\n   - `--unit-only` — shorthand that implies both `--skip-integration` and `--skip-playwright`\n\n   Resolve flags to boolean variables:\n   - Start with: `run_integration = true`, `run_playwright = true`\n   - If `--unit-only` is present: set both to `false`\n   - If `--skip-integration` is present: set `run_integration = false`\n   - If `--skip-playwright` is present: set `run_playwright = false`\n   - Unknown flags: note them in the final report as \"Unrecognized flag ignored\" but do not fail\n\n2. **Generate a run timestamp** using the current date and time in `YYYY-MM-DD-HH-MM` format (e.g., `2026-03-10-14-35`). Store this as `run_timestamp`. Both output documents will use this value.\n\nThis stage has no failure conditions — proceed to Stage 1.\n\n## Stage 1 — Environment Setup\n\nRun the following command in the terminal:\n```\nmkdir -p docs/tmp/testing/\n```\nIf this fails, stop immediately and report: \"Cannot create output directory docs/tmp/testing/ — check permissions.\"\n\nVerify the Python venv is available:\n```\nsource .venv/bin/activate && python --version\n```\nIf the venv is not available, note \"venv not available\" in the report and skip unit and integration tests. Continue to Playwright stage if applicable.\n\n## Stage 2 — Unit Tests\n\nRun in the terminal:\n```\nsource .venv/bin/activate && pytest tests/pytest/ -v --tb=short\n```\n\nCapture the full output. Extract the pytest summary line (e.g., `47 passed, 3 failed in 12.4s`). For each failing test, apply the triage logic below, then record the result.\n\n## Stage 3 — Integration Tests\n\nIf `run_integration` is `false`, skip this stage and record: `Integration tests: SKIPPED (--skip-integration or --unit-only flag was set)`\n\nIf `run_integration` is `true`, run each subdirectory as a separate batch. **Continue to the next batch even if the current one has failures.**\n\nRun the following batches in order in the terminal:\n```\nsource .venv/bin/activate && pytest tests/integration/code_writer/ --run-integration -v -s\nsource .venv/bin/activate && pytest tests/integration/estimator/ --run-integration -v -s\nsource .venv/bin/activate && pytest tests/integration/ticket_updater/ --run-integration -v -s\nsource .venv/bin/activate && pytest tests/integration/routes/ --run-integration -v -s\nsource .venv/bin/activate && pytest tests/integration/db/ --run-integration -v -s\n```\n\nApply triage logic to any failures. Note: integration test failures involve real LLM behavior and are more likely to be implementation issues than test-code issues — apply extra caution before fixing.\n\n## Stage 4 — Playwright E2E Tests\n\nIf `run_playwright` is `false`, skip this stage and record: `Playwright tests: SKIPPED (--skip-playwright or --unit-only flag was set)`\n\nIf `run_playwright` is `true`, first check whether the server is running:\n```\ncurl -s -o /dev/null -w \"%{http_code}\" http://localhost:8000/\n```\n\nIf the status code is NOT `200`, skip Playwright and record:\n```\nPlaywright tests: SKIPPED — server not running.\nStart the server with: uvicorn main:app --reload\nThen re-run this command without --skip-playwright.\n```\n\nIf the server IS running, run each spec directory as a separate batch. **Continue to the next batch even if the current one has failures.**\n\n```\nnpx playwright test tests/playwright/setup/ --config=tests/playwright/playwright.config.js --reporter=list\nnpx playwright test tests/playwright/projects/ --config=tests/playwright/playwright.config.js --reporter=list\nnpx playwright test tests/playwright/optimize/ --config=tests/playwright/playwright.config.js --reporter=list\n```\n\nApply triage logic to any failures.\n\n## Triage Logic\n\nFor every failing test, examine the test file and the code it tests. Classify as ONE of the following:\n\n### TEST-CODE ISSUE — fix it directly\n\nClassify as a test-code issue if ANY of the following applies:\n- The test asserts against a hardcoded value that no longer matches current behavior (outdated mock data)\n- The test imports or calls a function that was renamed, moved, or removed\n- The test asserts on a response field that was restructured\n- The test expects a specific error message string that has since changed\n- A fixture or conftest references a removed table column or model field\n\n**Action**: Apply a minimal, targeted fix to the test file only. Then re-run just that failing test to confirm:\n```\nsource .venv/bin/activate && pytest path/to/test_file.py::test_function_name -v --tb=short\n```\nIf the re-run **still fails** after your fix, do not make further edits — escalate to implementation-code issue instead and revert your change.\n\n### IMPLEMENTATION-CODE ISSUE (or UNCERTAIN) — document it, do not fix\n\nClassify as an implementation issue if ANY of the following applies:\n- The production function raises an unexpected exception\n- A route handler returns the wrong status code for a documented behavior\n- Business logic produces incorrect output that the test correctly asserts against\n- You are not confident the test is wrong\n\n**Action**: Do NOT touch any files in `api/`, `src/`, `main.py`, or `db/`. Record this issue in the implementation-issues document.\n\n## Stage 5 — Write Output Documents\n\n### Document 1: Test Run Report (always write this)\n\nWrite to: `docs/tmp/testing/test-run-{run_timestamp}.md`\n\n```markdown\n# Test Run: {run_timestamp}\n\n## Configuration\n- Unit tests: RUN\n- Integration tests: RUN / SKIPPED — (reason)\n- Playwright tests: RUN / SKIPPED — (reason)\n\n## Unit Tests\n**Result**: X passed, Y failed\n**Duration**: ~Ns\n**Fixes applied**:\n- `path/to/test_file.py`: brief description of what was fixed\n- (or \"none\" if no fixes were needed)\n\n**Failures escalated as implementation issues**: N\n\n## Integration Tests\n\n### tests/integration/code_writer/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/integration/estimator/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/integration/ticket_updater/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/integration/routes/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/integration/db/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n## Playwright Tests\n\n### tests/playwright/setup/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/playwright/projects/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n### tests/playwright/optimize/\n**Result**: X passed, Y failed\n**Fixes applied**: ...\n\n## Overall Summary\n- Total test fixes applied: N\n- Suspected implementation issues found: N\n- Implementation issues document: docs/tmp/testing/implementation-issues-{run_timestamp}.md\n  (or \"not created — no issues found\")\n```\n\n### Document 2: Implementation Issues (only write if issues were found)\n\nIf at least one failure was escalated as an implementation-code issue, write to:\n`docs/tmp/testing/implementation-issues-{run_timestamp}.md`\n\n```markdown\n# Suspected Implementation Issues: {run_timestamp}\n\nThese test failures were NOT fixed. They may indicate bugs in production code.\nA developer should investigate each item before merging.\n\n## Issue 1\n- **Test**: `path/to/test_file.py::test_function_name`\n- **Tier**: unit / integration / playwright\n- **Failure message**: (paste the key assertion or exception line)\n- **Why not fixed**: (brief reasoning, e.g., \"production function raises KeyError on valid input\")\n\n## Issue 2\n...\n```\n\nIf no implementation issues were found, do NOT create this file.\n\n## Final Output\n\nAfter writing all documents, print this summary:\n\n```\nTest run complete: {run_timestamp}\nReport saved to: docs/tmp/testing/test-run-{run_timestamp}.md\nImplementation issues: docs/tmp/testing/implementation-issues-{run_timestamp}.md (if applicable)\nNo suspected implementation issues found. (if none)\n```\n",
     "scan-tickets.md": "$ARGUMENTS\n\n---\n\n# Instructions\n\nSynchronize recently-updated Jira tickets with the local `tickets` database table and backfill missing workflow state timestamps. Perform all work directly in the main thread.\n\n## Stage 0 — Parse Arguments and Calculate Date\n\n1. Read the value of `$ARGUMENTS`. If it is empty, whitespace-only, or not a valid integer, default `months_back` to `3`. If it contains multiple tokens, extract only the first token and attempt to parse it as an integer. If parsing fails, default to `3`.\n\n2. Calculate `updated_since` by subtracting `months_back` months from today's date. Format the result as `YYYY-MM-DD`. Example: if today is 2026-03-07 and `months_back` is 3, then `updated_since` is 2025-12-07.\n\n3. Display the parsed values: \"Scanning tickets updated since {updated_since} (months_back = {months_back})\"\n\n4. Initialize the following tracking variables:\n   - `tickets_scanned` = 0 (total tickets fetched from Jira)\n   - `newly_tracked` = 0 (tickets inserted into database for the first time)\n   - `state_updated_list` = [] (list of objects with ticket key and fields updated)\n   - `warnings` = [] (list of warning strings for any per-ticket failures)\n\n## Stage 1 — Fetch All Tickets from Jira\n\n1. Initialize an empty list `all_tickets` and set `offset` to `0`.\n\n2. Enter a pagination loop:\n   - Call the `get_tickets` MCP tool with: `updated_since` set to the calculated date, `limit` set to `100`, and `offset` set to the current offset value.\n   - Parse the JSON response. The response contains a `tickets` array of ticket objects. Each ticket object has a `ticket_number` field (the Jira key, e.g., `BAPI-42`), along with `summary`, `status`, `issue_type`, `assignee`, and `updated_at`.\n   - Append all tickets from the response's `tickets` array to `all_tickets`.\n   - If the number of tickets returned in this page equals `100`, increment `offset` by `100` and repeat the loop.\n   - If fewer than `100` tickets are returned, exit the loop.\n\n3. Set `tickets_scanned` to the length of `all_tickets`.\n\n4. Display: \"Fetched {tickets_scanned} tickets from Jira. Processing...\"\n\n5. If the `get_tickets` call fails at any point during pagination, **stop** and report the error. Do not proceed to Stage 2.\n\n## Stage 2 — Track Each Ticket\n\n1. Iterate over each ticket in `all_tickets`. For each ticket:\n   - Call the `track_ticket` MCP tool with `ticket_number` set to the ticket's `ticket_number` field. If the ticket object includes a `summary` field, pass it as the `description` parameter.\n   - Inspect the response message. If the response indicates the ticket was newly created/inserted (look for words like \"created\" or \"inserted\" in the message, as opposed to \"already exists\" or \"updated\"), increment `newly_tracked` by 1.\n   - If the `track_ticket` call fails for this ticket, add a warning to the `warnings` list (e.g., \"Warning: Failed to track ticket {ticket_number}: {error}\") and **continue** to the next ticket. Do not abort the scan.\n\n2. Display a brief progress indicator every 25 tickets, e.g., \"Tracked {N} of {tickets_scanned} tickets...\"\n\n## Stage 3 — Detect and Backfill Workflow State\n\nDisplay: \"Checking workflow state for {tickets_scanned} tickets...\"\n\nIterate over each ticket in `all_tickets`. For each ticket (referenced by its `ticket_number` field), perform the following sub-steps. Wrap the entire per-ticket block in error handling: if the `get_ticket_state` call or the subsequent `update_ticket_state` call fails for a ticket, add a warning to `warnings` and continue to the next ticket.\n\n**Sub-step 4a — Retrieve current state**: Call the `get_ticket_state` MCP tool with `ticket_number` set to the ticket's key. The response contains:\n\n- Five timestamp fields (each is a timestamp string or null): `clarify_called`, `clarify_answered`, `critique_called`, `critique_answered`, `plan_generated`\n- Three boolean artifact flags: `has_clarifying_questions`, `has_critique`, `has_plan`\n\nIf the call returns a 404 or any error, add a warning to `warnings` and continue to the next ticket.\n\n**Sub-step 4b — Build fields_to_update list**: Initialize an empty `fields_to_update` list, then apply the following rules:\n\n- If `has_clarifying_questions` is `true` AND `clarify_called` is null -> add `\"clarify_called\"` to `fields_to_update`\n- If `has_clarifying_questions` is `true` AND `clarify_answered` is null -> add `\"clarify_answered\"` to `fields_to_update`\n- If `has_critique` is `true` AND `critique_called` is null -> add `\"critique_called\"` to `fields_to_update`\n- If `has_critique` is `true` AND `critique_answered` is null -> add `\"critique_answered\"` to `fields_to_update`\n- If `has_plan` is `true` AND `plan_generated` is null -> add `\"plan_generated\"` to `fields_to_update`\n\n**Sub-step 4c — Call update_ticket_state if needed**: If `fields_to_update` is non-empty, call the `update_ticket_state` MCP tool with `ticket_number` set to the ticket's key and `fields` set to the `fields_to_update` array. If this succeeds, add an entry to `state_updated_list` recording the ticket key and the list of fields that were set. If `update_ticket_state` fails, add a warning to `warnings` and continue.\n\nDisplay a progress indicator every 25 tickets that includes the current ticket key, e.g., \"Checked state for {TICKET-KEY} ({N} of {tickets_scanned} tickets)\"\n\n## Stage 4 — Report Summary\n\n1. Calculate `state_updated_count` as the length of `state_updated_list`.\n\n2. Display the summary:\n\n   ```\n   **Scan complete**\n\n   * Tickets scanned: {tickets_scanned}\n   * Newly tracked: {newly_tracked}\n   * State updated: {state_updated_count}\n   ```\n\n3. If `state_updated_list` is non-empty, display a section titled \"Updated tickets:\" with one bullet per ticket showing the ticket key and the comma-separated list of fields that were set. Example:\n\n   ```\n   Updated tickets:\n   * BAPI-101: clarify_called, clarify_answered\n   * BAPI-105: critique_called, critique_answered, plan_generated\n   ```\n\n4. If the `warnings` list is non-empty, display a section titled \"Warnings:\" listing each warning string as a bullet. Example:\n\n   ```\n   Warnings:\n   * Warning: Failed to track ticket BAPI-99: Connection timeout\n   * Warning: State query failed for BAPI-112: SQL error\n   ```\n\n5. If there are no warnings, do not display the \"Warnings:\" section.\n",
     "teach-bridge.md": "Update a Bridge API configuration field via a natural-language teaching.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command takes a natural-language teaching (e.g., \"use data-testid selectors in Playwright tests\") and updates the appropriate Bridge API configuration field. The teaching is auto-classified to the correct field, merged with existing content as actionable AI instructions, and uploaded after user confirmation.\n\n`$ARGUMENTS` is required — it is the teaching text. If `$ARGUMENTS` is empty, show:\n\n```\nUsage: /teach-bridge <teaching>\n\nExamples:\n  /teach-bridge use data-testid selectors in Playwright tests\n  /teach-bridge always validate input DTOs with Pydantic before passing to service layer\n  /teach-bridge prefer composition over inheritance for service classes\n```\n\nIf any stage fails, stop immediately and report which stage failed and why.\n\n## Stage 0 — Preflight\n\n1. **Validate arguments**: If `$ARGUMENTS` is empty or contains only whitespace, display the usage instructions above and stop.\n\n2. **Admin check**: Call the `get_my_role` MCP tool (no parameters). Inspect the response:\n   - If `role` is `\"admin\"` OR `source` is `\"legacy\"`: proceed normally.\n   - Otherwise: stop immediately and display:\n     ```\n     Admin access required. Your API key has role \"<role>\" (source: <source>).\n     Only admin keys and legacy shared keys can update configuration fields.\n     Contact your project administrator to request admin access.\n     ```\n\nIf this stage fails, stop immediately and report the error. Do not proceed to Stage 1.\n\n## Stage 1 — Classify\n\n1. **List available fields**: Call the `list_config_fields` MCP tool (no parameters). This returns all available configuration field names with descriptions.\n\n2. **Evaluate the teaching**: Compare the user's teaching (`$ARGUMENTS`) against each field's description to determine which field it applies to.\n\n3. **Handle classification outcomes**:\n   - **Clear single match**: If one field is clearly the best target, proceed to Stage 2 with that field.\n   - **Multiple plausible matches**: If 2-3 fields are equally plausible, present them to the user with their descriptions and ask which one to update. Wait for user input before proceeding.\n   - **No confident match**: If you cannot confidently map the teaching to any field, ask the user to elaborate or specify which field they intend. Wait for user input before proceeding.\n\n## Stage 2 — Merge\n\n1. **Read current value**: Call the `get_config_field` MCP tool with `field_name` set to the selected field from Stage 1. Capture the current value, description, and examples from the response.\n\n2. **Draft the update**:\n   - **If the field is currently null or empty**: Compose initial content from the teaching. Rephrase the user's input as imperative, agent-facing instructions (e.g., convert \"I want you to use data-testid\" to \"Always use `data-testid` attributes for Playwright element locators\"). Do not use the user's exact conversational text.\n   - **If the field has existing content**: Merge the teaching into the existing value at the most appropriate location. Rephrase as imperative, agent-facing instructions. Preserve the existing structure and formatting.\n\n3. **Handle contradictions**: If the teaching contradicts existing instructions in the field, present both the existing instruction and the new teaching side-by-side and ask the user which should take precedence. Wait for user input before proceeding.\n\n## Stage 3 — Confirm and Upload\n\n1. **Show the proposed update**: Display to the user:\n   - **Field**: The name of the field being updated\n   - **Change summary**: A brief description of what was added or changed\n   - **Full proposed value**: The complete new value for the field (not just the diff)\n\n2. **Wait for confirmation**: Ask the user to confirm, request edits, or abort.\n\n3. **On confirmation**: Call the `update_config_field` MCP tool with:\n   - `field_name`: the selected field name\n   - `value`: the full merged value (pass inline, do not use `file_path`)\n\n   Display a success message confirming the update.\n\n4. **On rejection**: Ask the user what they'd like to change. If they provide edits, revise the proposed value and show it again. If they abort, stop without making any changes.\n"
 };

package/build/decision-page-schema.js

@@ -0,0 +1,101 @@
+/**
+ * Decision Page schema
+ *
+ * Zod schema for the `generate_decision_page` MCP tool's actionable-item contract.
+ * Extracted into its own module so unit tests can validate the schema without
+ * importing the full MCP server (which has startup side effects).
+ *
+ * Keep this in sync with the inputSchema registered for `generate_decision_page`
+ * in src/index.ts. The handler in index.ts continues to enforce duplicate-id,
+ * recommendation_index bounds, and reserved "None of these" rules at runtime.
+ */
+import { z } from "zod";
+export const ActionableItemSchema = z
+    .object({
+    id: z
+        .string()
+        .min(1)
+        .regex(/^[A-Za-z0-9_-]+$/, "id must contain only letters, digits, hyphens, or underscores"),
+    question: z.string().min(1),
+    original_question: z
+        .string()
+        .min(1)
+        .describe("The clarifying question or critique point as originally raised; soft cap ~30 words."),
+    why_it_matters: z
+        .string()
+        .min(1)
+        .describe("Concrete one-sentence impact of this decision; soft cap ~40 words."),
+    recommendation_explanation: z
+        .string()
+        .min(1)
+        .describe("Why the recommended branch is the best choice; soft cap ~60 words."),
+    codebase_evidence: z
+        .string()
+        .min(1)
+        .describe("Combined Assessment paragraph and Codebase Evidence bullet list. Rendered as escaped plain text inside a closed-by-default <details> block."),
+    source: z
+        .string()
+        .min(1)
+        .describe("Source reference from the combined review-and-resolution doc, e.g. 'Clarifying Q3 (prior round, weak concurrence)'"),
+    recommendation_index: z
+        .number()
+        .int()
+        .min(0)
+        .describe("0-based index of the recommended option in the options array"),
+    options: z
+        .array(z.string().min(1))
+        .min(2)
+        .max(4)
+        .describe("Option labels from the decision tree branches. Values are auto-generated. Must have 2–4 entries."),
+    option_consequences: z
+        .array(z.string().min(1))
+        .min(2)
+        .max(4)
+        .describe("Behavioral consequence per branch, parallel to options. Must have 2–4 entries; length must equal options.length."),
+})
+    .superRefine((item, ctx) => {
+    if (item.option_consequences.length !== item.options.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["option_consequences"],
+            message: `option_consequences length (${item.option_consequences.length}) must match options length (${item.options.length}).`,
+        });
+    }
+    if (item.recommendation_index >= item.options.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["recommendation_index"],
+            message: `recommendation_index (${item.recommendation_index}) is out of bounds (${item.options.length} options).`,
+        });
+    }
+});
+// Raw input shape for the `generate_decision_page` tool registration.
+// MCP's registerTool expects a shape object (which the SDK wraps in z.object),
+// not a pre-built z.object. Exporting the shape lets index.ts and the schema
+// share a single source of truth for the input contract.
+export const DecisionPageInputShape = {
+    ticket_key: z.string().describe("Jira ticket key, e.g. BAPI-123"),
+    actionable_items: z
+        .array(ActionableItemSchema)
+        .optional()
+        .default([])
+        .describe("Actionable review decisions sourced from the combined review-and-resolution document. 'None of these' is auto-appended by the renderer and must not appear in options."),
+    clear_improvements: z
+        .array(z.object({
+        id: z
+            .string()
+            .min(1)
+            .describe("Stable identifier for the improvement. Stored for the rewrite/capture step but intentionally not rendered to the user."),
+        title: z.string().min(1),
+        action: z.string().min(1),
+        confidence: z.string().min(1),
+        source: z
+            .string()
+            .min(1)
+            .describe("Source reference from the evaluation. Stored for the rewrite/capture step but intentionally not rendered to the user — the confirmed-improvements list shows title/confidence/action only."),
+    }))
+        .optional()
+        .default([])
+        .describe("Confirmed improvements displayed as informational list, not submitted."),
+};
+export const DecisionPageInputSchema = z.object(DecisionPageInputShape);

package/build/decision-page-schema.test.js

@@ -0,0 +1,248 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ActionableItemSchema } from "./decision-page-schema.js";
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+function validItemRaw() {
+    return {
+        id: "E-1",
+        question: "E-1: Timeout behavior needs a decision",
+        original_question: "Should the ticket specify timeout behavior for slow upstream calls?",
+        why_it_matters: "Timeout behavior affects retry paths and determines whether users see stale, failed, or delayed responses.",
+        options: ["Keep existing", "Add configurable", "Defer"],
+        option_consequences: [
+            "No new implementation work, but slow calls keep current failure behavior.",
+            "Implementers add configuration and tests for timeout-specific behavior.",
+            "The ticket remains smaller, but timeout ambiguity persists for a later change.",
+        ],
+        recommendation_explanation: "Configurable timeout best matches code paths that already branch on external service latency.",
+        codebase_evidence: "Assessment: ...\n\nCodebase Evidence:\n- src/api/timeouts.ts:42 — current latency-branching helper",
+        source: "Clarifying Q1 (prior round, weak concurrence)",
+        recommendation_index: 1,
+    };
+}
+// ---------------------------------------------------------------------------
+// Schema validation — happy path
+// ---------------------------------------------------------------------------
+describe("ActionableItemSchema — happy path", () => {
+    it("accepts a valid actionable item using the new contract", () => {
+        const result = ActionableItemSchema.safeParse(validItemRaw());
+        assert.equal(result.success, true);
+    });
+    it("does not require a context field", () => {
+        const item = validItemRaw();
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, true);
+        if (result.success) {
+            assert.equal(result.data.context, undefined);
+        }
+    });
+    it("accepts the minimum branch count (2 options, 2 consequences)", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B"],
+            option_consequences: ["Consequence A.", "Consequence B."],
+            recommendation_index: 0,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, true);
+    });
+    it("accepts the maximum branch count (4 options, 4 consequences)", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B", "C", "D"],
+            option_consequences: ["A.", "B.", "C.", "D."],
+            recommendation_index: 0,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, true);
+    });
+});
+// ---------------------------------------------------------------------------
+// Schema validation — required fields
+// ---------------------------------------------------------------------------
+describe("ActionableItemSchema — required clarity fields", () => {
+    for (const fieldName of [
+        "original_question",
+        "why_it_matters",
+        "recommendation_explanation",
+        "codebase_evidence",
+    ]) {
+        it(`rejects payloads missing ${fieldName}`, () => {
+            const item = { ...validItemRaw() };
+            delete item[fieldName];
+            const result = ActionableItemSchema.safeParse(item);
+            assert.equal(result.success, false);
+            if (!result.success) {
+                const paths = result.error.issues.map((issue) => issue.path.join("."));
+                assert.ok(paths.includes(fieldName), `expected issue at path ${fieldName}, got ${paths.join(", ")}`);
+            }
+        });
+    }
+    it("rejects payloads missing option_consequences", () => {
+        const item = { ...validItemRaw() };
+        delete item.option_consequences;
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+        if (!result.success) {
+            const paths = result.error.issues.map((issue) => issue.path.join("."));
+            assert.ok(paths.includes("option_consequences"));
+        }
+    });
+    it("rejects payloads that still use a legacy context field instead of the new clarity fields", () => {
+        const item = { ...validItemRaw(), context: "legacy context blob" };
+        delete item.original_question;
+        delete item.why_it_matters;
+        delete item.recommendation_explanation;
+        delete item.codebase_evidence;
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+        if (!result.success) {
+            const paths = result.error.issues.map((issue) => issue.path.join("."));
+            assert.ok(paths.includes("original_question"));
+            assert.ok(paths.includes("why_it_matters"));
+            assert.ok(paths.includes("recommendation_explanation"));
+            assert.ok(paths.includes("codebase_evidence"));
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// Schema validation — branch count boundaries
+// ---------------------------------------------------------------------------
+describe("ActionableItemSchema — 2–4 branch boundary", () => {
+    it("rejects options with only one branch", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["Only one"],
+            option_consequences: ["Only one."],
+            recommendation_index: 0,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+    });
+    it("rejects options with five branches", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B", "C", "D", "E"],
+            option_consequences: ["A.", "B.", "C.", "D.", "E."],
+            recommendation_index: 0,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+    });
+    it("rejects option_consequences with only one entry", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B"],
+            option_consequences: ["Only one."],
+            recommendation_index: 0,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+    });
+    it("rejects option_consequences with five entries", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B"],
+            option_consequences: ["A.", "B.", "C.", "D.", "E."],
+            recommendation_index: 0,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+    });
+});
+// ---------------------------------------------------------------------------
+// Schema validation — option/consequence parity
+// ---------------------------------------------------------------------------
+describe("ActionableItemSchema — option/consequence parity", () => {
+    it("rejects mismatched lengths and attaches the issue to option_consequences", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B", "C"],
+            option_consequences: ["A.", "B."],
+            recommendation_index: 0,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+        if (!result.success) {
+            const matchingIssue = result.error.issues.find((issue) => issue.path.join(".") === "option_consequences" && /must match options length/.test(issue.message));
+            assert.ok(matchingIssue, `expected an option_consequences issue with the parity message; got: ${JSON.stringify(result.error.issues)}`);
+        }
+    });
+    it("rejects mismatched lengths in the other direction", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B"],
+            option_consequences: ["A.", "B.", "C."],
+            recommendation_index: 0,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+    });
+});
+// ---------------------------------------------------------------------------
+// Schema validation — recommendation_index upper bound
+// ---------------------------------------------------------------------------
+describe("ActionableItemSchema — recommendation_index upper bound", () => {
+    it("rejects recommendation_index >= options.length and attaches the issue to recommendation_index", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B", "C"],
+            option_consequences: ["A.", "B.", "C."],
+            recommendation_index: 99,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+        if (!result.success) {
+            const matchingIssue = result.error.issues.find((issue) => issue.path.join(".") === "recommendation_index" && /out of bounds/.test(issue.message));
+            assert.ok(matchingIssue, `expected a recommendation_index issue with the out-of-bounds message; got: ${JSON.stringify(result.error.issues)}`);
+        }
+    });
+    it("rejects recommendation_index equal to options.length (off-by-one)", () => {
+        const item = {
+            ...validItemRaw(),
+            options: ["A", "B"],
+            option_consequences: ["A.", "B."],
+            recommendation_index: 2,
+        };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+    });
+});
+// ---------------------------------------------------------------------------
+// id format — must produce a valid HTML id so getElementById can find the
+// per-item textarea/radio. Whitespace and dots silently break that lookup
+// (and would skip the "no comment selected" validation), so the schema
+// rejects anything outside [A-Za-z0-9_-].
+// ---------------------------------------------------------------------------
+describe("ActionableItemSchema — id format", () => {
+    it("rejects an id containing whitespace", () => {
+        const item = { ...validItemRaw(), id: "E 1" };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+        if (!result.success) {
+            assert.ok(result.error.issues.some((issue) => issue.path[0] === "id"));
+        }
+    });
+    it("rejects an id containing only whitespace", () => {
+        const item = { ...validItemRaw(), id: "   " };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+    });
+    it("rejects an id containing a dot", () => {
+        const item = { ...validItemRaw(), id: "E.1" };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, false);
+    });
+    it("accepts an id with hyphens (matches the instruction's generator format)", () => {
+        const item = { ...validItemRaw(), id: "E-1" };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, true);
+    });
+    it("accepts an id with underscores", () => {
+        const item = { ...validItemRaw(), id: "decision_1" };
+        const result = ActionableItemSchema.safeParse(item);
+        assert.equal(result.success, true);
+    });
+});