TalkEdit/AI_dev_plan.md

# AI Dev Plan (Must-Haves Only)

## Purpose

This is the minimum implementation needed for AI to reliably build, test, and debug TalkEdit with high confidence.

Target: reliable 80-90% autonomous implementation/debugging on scoped tasks.

## Must-Have Pillars

## 1. Single Validation Command

Required:

1. One command that runs lint, build, backend tests, and smoke checks.
2. Works locally and in CI.

Current status:

1. Implemented via scripts/validate-all.sh.
2. Enforced in CI via .github/workflows/validate-all.yml.

## 2. CI Quality Gate

Required:

1. Pull requests fail if validation fails.
2. Failures produce diagnostics artifacts.

Current status:

1. Implemented in .github/workflows/validate-all.yml.
2. Diagnostics collected by scripts/collect-diagnostics.sh on failure.

## 3. Spec Requirement for Feature Changes

Required:

1. Feature code changes must include a spec file update.
2. Spec format must be standardized.

Current status:

1. Implemented via scripts/check-feature-spec.sh.
2. Spec template exists at docs/spec-template.md.
3. Specs folder guidance exists at docs/specs/README.md.

## 4. Backend Contract Test Coverage

Required:

1. Router-level contract tests for success and error paths.
2. Tests are deterministic and mock heavy services.

Current status:

1. Implemented in backend/tests/test_router_contracts.py.
2. Cache utility baseline tests implemented in backend/tests/test_cache_utils.py.

## 5. Error-Tolerant Router Contracts

Required:

1. Expected client errors must remain 4xx.
2. Server failures must return 5xx with useful detail.

Current status:

1. Implemented for captions/export HTTPException passthrough.
2. Covered by contract tests.

## 6. Basic Autonomy Policy

Required:

1. Clear autonomous scope and escalation rules.
2. Clear restrictions for high-risk changes.

Current status:

1. Implemented in docs/ai-policy.md.

## Must-Have Remaining Work

No remaining must-have items.

Completed in this pass:

1. Added lightweight frontend tests and integrated them into scripts/validate-all.sh.
2. Added pull request template with required spec link and acceptance criteria checklist.
3. Added endpoint-level contract assertions for /file range requests and /audio/waveform cache-hit/cache-miss behavior.
4. Confirmed scripts/validate-all.sh passes end-to-end with frontend tests + expanded backend contracts.

## Out of Scope for Must-Have Baseline

Useful later, but not required for strong day-to-day autonomous implementation:

1. Full quality dashboards.
2. Advanced autonomy telemetry.
3. Complete long-term governance expansion.
4. High-autonomy optimization beyond 90% reliability target.

## Definition of Done (Must-Have Plan)

Must-have plan is complete when all are true:

1. scripts/validate-all.sh passes locally and in CI.
2. Feature PRs without spec updates are blocked.
3. Backend router contracts cover core success and error paths.
4. Frontend has at least one stable test command integrated into validation.
5. AI policy + diagnostics workflow are active.

## Current State Summary

Completed:

1. Validation and CI enforcement.
2. Diagnostics capture.
3. Spec policy and templates.
4. Backend contract test foundation (including AI endpoints).
5. Core router error-path correctness.
6. Autonomy policy baseline.
7. Frontend test command integrated into validation.
8. PR template requirement added.
9. /file and /audio/waveform contract assertions implemented.

Remaining:

1. No must-have items remaining.