TalkEdit/docs/ai-policy.md

AI Execution Policy

Purpose: define what autonomous AI can do in this repository without explicit human approval.

Default Mode

• AI may implement and debug within approved scope.
• AI must run validation commands after code changes.
• AI must stop and escalate when blocked by policy or ambiguity.

Allowed Autonomous Actions

1. Edit frontend, backend, shared schema, docs, and scripts.
2. Add/modify tests related to the task.
3. Run non-destructive validation commands.
4. Update project docs and Copilot instructions when behavior changes.

Restricted Actions (Require Approval)

1. Security/privacy-sensitive logic changes.
2. Data migrations or destructive file operations.
3. Credential handling changes or secrets management changes.
4. Breaking API/schema changes.
5. Build/release signing, packaging, and deployment automation changes.

Prohibited Actions

1. Destructive git commands (git reset --hard, force pushing protected branches).
2. Deleting user project/media data.
3. Bypassing required checks in CI.

Required Validation Workflow

For each autonomous task:

1. Implement smallest safe change set.
2. Run lint/type/test/build checks for impacted scope.
3. Inspect errors and fix with bounded retries.
4. Re-run checks until green or escalated.
5. Produce concise summary with risks and assumptions.

Escalation Triggers

AI must ask a human when:

1. Requirements are ambiguous and affect user-visible behavior.
2. Multiple product choices are plausible with no clear preference.
3. Potential legal, security, or compliance impact exists.
4. CI remains failing after 3 repair attempts in the same area.
5. A requested operation conflicts with this policy.

Required Artifacts In AI PR/Change Summary

1. What changed.
2. Why it changed.
3. Validation commands and outcome.
4. Residual risks.
5. Follow-up tasks.

Risk Levels

• Low: docs, styling, isolated refactors, non-critical bugfixes.
• Medium: feature additions with contract-stable behavior.
• High: API/schema/security/export pipeline/transcription pipeline changes.

High-risk changes require explicit human review before merge.

TalkEdit-Specific Rules

1. Preserve compatibility for desktop bridge contracts unless explicitly approved.
2. Keep routers thin and business logic in backend services.
3. Export/transcription pipeline changes must include regression tests.
4. Linux WebKit startup behavior and media URL consistency are mandatory regression targets.