Add scan.py to offload triage Jira scan from MCP to REST API (#79)

## Summary

- Adds `triage/scripts/scan.py` that replaces the AI-driven `/scan`
phase with a deterministic Python script calling the Jira REST API
directly, eliminating ~50-100K tokens of mechanical MCP pagination per
run
- Key-based cursor pagination (Jira Cloud ignores `startAt`),
ADF-to-text extraction, issue normalization, retry with backoff on
429/5xx, dual auth (Basic for API tokens, Bearer for PATs)
- 102 unit + integration tests with fixture data, structured in layers
(pure functions, pagination with fake search callable, integration with
mocked HTTP)
- Updates `scan.md` skill file, `guidelines.md` tool table, `README.md`
prerequisites, and `SKILL.md` version (0.1.0 → 0.2.0)

**Merge-order note:** PR #78 also bumps triage to 0.2.0 and makes
identical CI changes (`test.yaml`, `lint.yaml`). Whichever merges second
should rebase and bump to 0.3.0 — each PR introduces its own MINOR
change and needs a distinct version.

## Test plan

- [x] 102 unit + integration tests pass (`python3 -m pytest
triage/scripts/test_scan.py -v`)
- [x] Live-tested against Jira Cloud (`redhat.atlassian.net`, project
EDM) — 154 unresolved bugs paginated correctly, fields normalized, ADF
descriptions extracted as readable text
- [x] Markdown lint passes on all changed files
- [x] Structure validation passes (`pre-review-checks.py triage`)
- [x] Existing `_shared/scripts` tests still pass
- [x] Code reviewed (2 iterations — 2 critical issues fixed:
guidelines.md tool table contradiction, script path convention)

Assisted-by: Claude Opus 4.6 (1M) <noreply@anthropic.com>

Author: adalton

triage/README.md

@@ -17,8 +17,12 @@ graph TD
 
 ## Prerequisites
 
-- **Jira MCP server** — the `user-mcp-jira` MCP server must be configured and authenticated
 - **Jira access** — the authenticated user must have read access to the target project
+- **Jira MCP server** — the `user-mcp-jira` MCP server must be configured and authenticated (used by `/start` and `/assess`)
+- **Environment variables for `/scan` (and `/run`, which includes scan)** — the scan phase calls the Jira REST API directly via `scripts/scan.py` instead of MCP:
+  - `JIRA_URL` — Jira instance base URL (e.g., `https://redhat.atlassian.net`)
+  - `JIRA_TOKEN` — API token or Personal Access Token
+  - `JIRA_EMAIL` — (optional) account email; set this when using an API token (Basic auth); omit for PATs (Bearer auth)
 
 ## Phases
 

triage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: triage
-version: 0.4.0
+version: 0.5.0
 description: >-
   Bulk-triage unresolved Jira bugs with AI-driven recommendations and an
   interactive HTML report. Scan also loads recently resolved bugs for regression

triage/guidelines.md

@@ -34,15 +34,15 @@ artifacts and published output from this workflow.
 - **No Jira writes** — this workflow must not create, update, close, or comment on any Jira issue
 - **No fabricated data** — if a field is missing from the Jira response, report it as missing; never invent values
 - **No skipping issues** — every unresolved bug in the scan results must appear in the analysis and report
-- **Read-only MCP tools only** — each phase declares its allowed tools; never call a tool outside that list. No phase may use write-oriented Jira tools (`jira_create_issue`, `jira_update_issue`, `jira_delete_issue`, `jira_transition_issue`, `jira_add_comment`, `jira_add_worklog`, `jira_create_issue_link`, etc.)
+- **Read-only Jira access only** — each phase declares its allowed tools; never call a tool outside that list. The read-only restriction covers both Jira MCP tools and the approved `scripts/scan.py` REST client, which issues only `GET /rest/api/3/search/jql`. No phase may use write-oriented Jira tools (`jira_create_issue`, `jira_update_issue`, `jira_delete_issue`, `jira_transition_issue`, `jira_add_comment`, `jira_add_worklog`, `jira_create_issue_link`, etc.)
 
 ## Allowed Tools Per Phase
 
 | Phase   | Jira MCP tools (read-only)         | Local tools                    |
 |---------|-------------------------------------|--------------------------------|
 | Run     | Per phase below                     | Per phase below                |
 | Start   | `jira_search`                       | `mkdir` (create artifact dir)  |
-| Scan    | `jira_search`                       | Write `issues.json` and `resolved.json` |
+| Scan    | none (script calls REST API directly) | Run `scripts/scan.py`; read stdout/stderr |
 | Analyze | none                                | Read `issues.json`, read `resolved.json` (if present), write `analyzed.json` |
 | Report  | none                                | Read `analyzed.json`, read/update `issues.json` (renderer reads `jiraBaseUrl` from it); run `render_report.py`; write `ai-synthesis.json`, `report.html` |
 | Assess (`/assess`) | `jira_search`              | Optionally read `issues.json`; no required artifact writes |