V4.10

.github/instructions/documentation-sync.instructions.md

@@ -0,0 +1,35 @@
+---
+description: Require documentation updates whenever code changes alter contracts, behavior, or scope.
+applyTo: 'src/transcription/**/*.py'
+---
+
+# Documentation Sync Requirements
+
+Keep docs in sync in the same change whenever implementation alters a documented contract, behavior, or roadmap decision.
+
+## Update documentation when any of these change
+
+1. **Schema/Data contract**
+   - Models, fields, enums, constraints, indexes, relationships, loading semantics.
+   - **Required doc update:** `docs/schema.md`.
+
+2. **Configuration contract**
+   - `Settings` keys, defaults, required/optional environment values.
+   - **Required doc update:** `.env.example` and any directly related setup docs.
+
+3. **User-visible UI behavior**
+   - Page flow, routes, button/action behavior, labels, status wording, empty/error states.
+   - **Required doc update:** relevant `docs/ui/pages/*.md` docs and feature docs when applicable.
+
+4. **Error handling semantics**
+   - Error categories, retry behavior, envelope structure, translation boundaries.
+   - **Required doc update:** `docs/error_handling.md` and `docs/invariant/error_handling.md`.
+
+5. **Roadmap/scope decisions**
+   - Version targets, sequencing, deferrals, and accepted alternatives.
+   - **Required doc update:** `docs/roadmap_plan.md` and related backlog docs (for example `docs/ver4.8/feature_backlog_v4_8.md`).
+
+## Working rule
+
+If none of the categories above changed, documentation edits are optional.
+If any category changed, update docs in the same PR/change set rather than deferring.

.github/instructions/services.instructions.md

@@ -134,6 +134,13 @@ Atomicity rules:
 - If model fields, enums, constraints, indexes, or relationship-loading semantics change, update `docs/schema.md` in the same change.
 - If `Settings` fields or defaults change in `src/transcription/config.py`, update `.env.example` in the same change so keys/defaults remain synchronized and no stale settings remain documented.
 
+## Schema Drift and Legacy Compatibility Policy
+
+- Prefer schema migration or startup reconciliation over runtime compatibility paths in service writes.
+- Do not add legacy read/write compatibility code in service workflows by default.
+- If drift is discovered and a migration decision is ambiguous (for example, one-way destructive DDL, uncertain data retention impact, or unknown deployment sequence), pause and ask the user to choose migration vs compatibility before coding.
+- If a temporary compatibility path is explicitly approved, document an expiration/removal plan in the same change.
+
 # Service Composition
 
 A service method may read across models it does not own, using eager loads from its own