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.

## 7. AI Tools Validation Strategy

Required:

1. **Per-edit validation**: After each code change (file edit, replacement, or creation), validate immediately with appropriate tools.
2. **Tool selection by change type**:
   - Frontend changes: ESLint (`npm run -s lint`), then TypeScript build (`npm run build`)
   - Backend changes: Syntax check via Python import, then run relevant test suite
   - Type/interface changes: Full type check via build or `tsc -b`
3. **Failure handling**: If validation fails, fix immediately before proceeding to next edit.
4. **Documentation updates**: When changing architecture, always update [.github/copilot-instructions.md](.github/copilot-instructions.md) as part of the same PR.
5. **Large multi-edit operations**: Use `multi_replace_string_in_file` to batch independent edits and reduce tool call overhead.
6. **Error collection**: Use `get_errors` tool to identify issues across multiple files in one call post-change.

Current implementation:

1. Electron removal completed with post-edit lint and build validation at each phase.
2. Zone editor feature implemented with immediate lint/build validation after component creation and UI integration.
3. Validation tools: `npm run -s lint`, `npm run build`, `get_errors`, `run_in_terminal` for test scripts.

Best practices established:

- Always run lint before build to catch TypeScript errors early
- Run full build after component changes to verify tree-shaking and bundling
- Use `get_errors` for multi-file error detection rather than sequential file reads
- Batch unrelated edits with `multi_replace_string_in_file` for efficiency
- Cache key decisions in session memory to avoid repeated exploration
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.