# AI Triage v1 Requirements

## Goal

Build a locally testable AI triage controller that replaces the scheduling responsibilities of the existing EC2 service with GitHub Actions, waits for dispatched GitHub Actions runs, classifies failures, and notifies a configured Feishu group. This version must not modify or stop EC2.

## Functional requirements

1. Run as a one-shot Python 3.11+ CLI from GitHub Actions or a developer machine.
2. Load task definitions from TOML. Configuration may contain environment-variable references but must not contain secret values.
3. Select enabled tasks by the current GitHub `schedule` expression or a manually supplied schedule key.
4. Dispatch a configured workflow, obtain or discover its run ID, and poll until `status == completed` or a configured deadline expires.
5. Handle all GitHub terminal conclusions, including `success`, `failure`, `cancelled`, `timed_out`, `action_required`, `stale`, `skipped`, and `neutral`.
6. Enumerate failed matrix jobs and failed steps. A downstream `test-summary` failure after a primary scenario failure must not create a duplicate incident.
7. Enforce this invariant before AI analysis:
   - Only a failure in an allowed scenario execution step, initially the exact step `Run scenario cases`, may be classified as a product or case error.
   - Every other failed step is an infrastructure error.
8. For scenario failures, extract and report the scenario YAML, case ID, operation, order, request URL and method, request body, expected result, actual status and response body, trace ID, relevant error, and evidence gaps.
9. Invoke a local agent through ACP. OpenCode (`opencode acp`) is the supported v1 agent. The base prompt is a configurable Markdown file.
10. Accept only strict, validated AI JSON. AI output cannot override the infrastructure gate. Invalid, timed-out, or unavailable AI execution must produce a safe low-confidence fallback result and must not block notification.
11. Route product errors to a component owner, case errors to a case owner, and infrastructure errors to an infrastructure owner. All owner values are initially allowed to be empty and must render as unassigned.
12. Notify configured lifecycle states and final triage through a Feishu custom-bot webhook. Webhook mode sends group messages; reliable replies inside one topic thread are explicitly outside v1.
13. Persist a redacted JSON report and Markdown summary as local files suitable for GitHub Actions artifact upload.
14. Provide a dry-run mode that performs selection and validation without dispatching, invoking an agent, or notifying Feishu.

## Security requirements

- Redact secrets before excerpts are retained, passed to ACP, written to reports, or sent to Feishu.
- Redaction must cover authorization headers, cookies, API keys, tokens, passwords, DSNs, SAS signatures, credential-like JSON fields, email addresses, and secret URL query parameters.
- Limit downloaded/log-derived evidence and agent output sizes.
- ACP must advertise no filesystem capabilities, reject tool permission requests, use an isolated temporary working directory, and terminate on timeout.
- Never print resolved secret configuration values.
- Do not copy the hard-coded webhook or Azure SAS values found in the existing downstream workflow.

## Reliability requirements

- Use GitHub REST API version `2026-03-10` by default. Its dispatch response includes the run ID and URLs.
- Support the legacy `204 No Content` response by taking a pre-dispatch run snapshot and discovering a new workflow-dispatch run created after dispatch. Treat ambiguous candidates as an error.
- Retry read-only GitHub calls for rate limiting and transient 5xx failures; never blindly repeat a dispatch.
- Poll the exact run ID and the current run attempt. Fetch per-job logs to keep evidence bounded.
- Notification failure must be represented in the report but must not erase triage results.

## Out of scope for v1

- Any EC2 change, migration, shutdown, or production cutover.
- A database, web server, inbound webhook service, UI, or monitoring dashboard.
- Automatic mutation of the triage knowledge Markdown.
- Pi presented as ACP. A Pi RPC adapter may be added later.
- Feishu application-bot topic replies and stable `@owner` mentions.
- Cross-run deduplication and restart persistence.
- Modifying downstream workflows to add a correlation input.

## Acceptance criteria

- All code runs with Python 3.11 standard library only.
- Unit tests cover configuration, GitHub dispatch/polling, log parsing, redaction, ACP protocol behavior, classification gates, owner routing, Feishu payloads, reports, and end-to-end orchestration with fakes.
- The repository provides an example TOML, a safe gated GitHub Actions scheduler, a triage knowledge prompt, and English setup/usage documentation.
- Local lint/static checks and the complete unit test suite pass without live GitHub, Feishu, ACP, or EC2 access.