improved tools for ai

docs/ai-policy.md

@@ -0,0 +1,73 @@
+# 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.