V3 Updated V3 core documents. Added data folder backup/restore before/after running destructive tests.

2026-08-09 10:51:30 -05:00
parent b59d3da23e
commit e6549277c6
14 changed files with 417 additions and 271 deletions
@@ -142,3 +142,47 @@ Prompt files are stored in `prompts/` and loaded from `PROMPT_DIR` (default: `./

 The canonical MVP prompt is:
 - `prompts/transcribe_document.md`
+
+## Destructive test procedure (with data backup)
+
+Use the cross-platform Python wrapper below whenever a test run might alter local `./data`.
+
+1. Create backup of `./data`.
+2. Run your test command.
+3. On success, prompt whether to restore now.
+4. On failure, keep backup and current state for inspection.
+
+Preflight behavior:
+
+- Backup preflight is warning-only when `data/transcription.db` appears in use.
+- Restore preflight is blocking: the script prompts you to close conflicting applications, then type `retry` to re-check or `cancel` to skip restore.
+
+### Run with confirmation-gated restore (default)
+
+```bash
+uv run python tools/run_destructive_tests.py -- pytest tests/services/test_job_service.py tests/ui/test_jobs_page.py
+```
+
+After tests pass, the script asks whether to restore backup immediately.
+
+### Run with automatic restore (non-interactive)
+
+```bash
+uv run python tools/run_destructive_tests.py --auto-restore -- pytest
+```
+
+### Run without terminal prompt (decide restore later)
+
+```bash
+uv run python tools/run_destructive_tests.py --skip-restore-prompt -- pytest
+```
+
+This keeps both the current post-test state and the backup, so restore can be decided explicitly later.
+
+### Restore later from a saved backup
+
+```bash
+uv run python tools/run_destructive_tests.py --restore-from data-backup-YYYYMMDD-HHMMSS
+```
+
+Backups are stored in `.test-backups/` and ignored by git.