# AI Triage v1 Implementation Plan

**Goal:** Deliver a safe, locally tested GHA controller for scheduled workflow execution and AI-assisted failure triage.

**Architecture:** A Python 3.11 standard-library CLI is launched by a gated GHA workflow. Dependency-injected adapters keep GitHub, ACP, and Feishu side effects outside deterministic config, parsing, classification, and report logic.

**Tech stack:** Python 3.11, `tomllib`, `urllib`, `subprocess`, `unittest`, GitHub Actions, ACP v1 JSON-RPC, Feishu custom-bot webhook.

## Global constraints

- Do not modify or stop EC2.
- Do not add third-party runtime dependencies.
- Do not store or print secrets.
- Write tests before production behavior and observe the intended failure.
- Keep the example task disabled and scheduled execution gated by `AI_TRIAGE_ENABLED`.

### Task 1: Configuration and core models

**Files:** `pyproject.toml`, `src/ai_triage/models.py`, `src/ai_triage/config.py`, `tests/test_config.py`

- [x] Define category, task, run, evidence, triage, and report data structures.
- [x] Test strict TOML loading, environment references, task selection, and invalid config.
- [x] Implement only the configuration behavior required by those tests.

### Task 2: GitHub Actions client

**Files:** `src/ai_triage/github.py`, `tests/test_github.py`

- [x] Test v2026 dispatch response, legacy 204 discovery, ambiguous discovery, polling, attempts, jobs, logs, and transient read retries.
- [x] Implement an injectable HTTP transport and clock/sleep functions.
- [x] Confirm dispatch is never blindly retried.

### Task 3: Redaction and failure evidence

**Files:** `src/ai_triage/redaction.py`, `src/ai_triage/evidence.py`, `tests/fixtures/*.log`, `tests/test_redaction.py`, `tests/test_evidence.py`

- [x] Test credential, URL-query, DSN, email, header, body, and placeholder redaction.
- [x] Test scenario markers, HTTP fields, retry selection, expect extraction, trace IDs, missing evidence, and infrastructure step gating.
- [x] Implement bounded normalization and parsing without retaining raw logs.

### Task 4: ACP and triage policy

**Files:** `src/ai_triage/acp.py`, `src/ai_triage/triage.py`, `prompts/triage_knowledge.md`, `tests/fake_acp_agent.py`, `tests/test_acp.py`, `tests/test_triage.py`

- [x] Test ACP initialize/new-session/prompt, assistant chunks, permission rejection, malformed messages, process exit, and timeout.
- [x] Test strict AI JSON validation, Markdown-fence handling, gate enforcement, fallback, and three-way owner routing.
- [x] Implement ACP v1 JSON-RPC over newline-delimited stdio and the triage policy.

### Task 5: Feishu and reports

**Files:** `src/ai_triage/feishu.py`, `src/ai_triage/report.py`, `tests/test_feishu.py`, `tests/test_report.py`

- [x] Test lifecycle/final payloads, truncation, escaping, unassigned owners, JSON/Markdown output, and notification error recording.
- [x] Implement the webhook provider and redacted report serializers.

### Task 6: Orchestration and CLI

**Files:** `src/ai_triage/orchestrator.py`, `src/ai_triage/cli.py`, `src/ai_triage/__main__.py`, `tests/test_orchestrator.py`, `tests/test_cli.py`

- [x] Test success, scenario failure, infrastructure failure, agent fallback, notification failure, dry-run, and schedule selection end to end with fakes.
- [x] Implement the state machine and CLI exit-code contract.

### Task 7: Operator documentation

**Files:** `config.example.toml`, `README.md`, `docs/knowledge/gha-triage-evidence.md`, `docs/specs/ai-triage/impl_details/task_progress.md`

- [x] Document host-managed operation without a repository GitHub Actions runner.
- [x] Document configuration, required secrets/variables, local use, ACP setup, report fields, owner setup, cutover steps, limitations, and downstream credential exposure risk.
- [x] Run the complete test suite, compile check, packaging check, and secret scan.

### Task 8: Final review improvements

- [x] Compare implementation against every requirement and close gaps.
- [x] Perform dedicated architecture, security, and test reviews.
- [x] Record deferred improvements and explicit decisions required from the operator.

## Deferred improvements after v1

- Bound GitHub rate-limit retry sleep against the exact remaining poll deadline.
- Add a static contract check against downstream workflow input names and step names.
- Add persistent dispatch state and cross-run deduplication before supporting controller restart.
- Add a Feishu application-bot adapter for topic replies and stable owner mentions.
- Add a Pi JSONL RPC adapter if Pi becomes a required agent backend.