From dd20248176086e0e918e8d982a1e38599ed45a87 Mon Sep 17 00:00:00 2001
From: Ben Sima <ben@bsima.me>
Date: Sun, 9 Nov 2025 08:20:52 -0500
Subject: Document TASK_TEST_MODE for safe testing in AGENTS.md

Add critical documentation about using test database to protect
production task data during development and testing.

Key points: - Set TASK_TEST_MODE=1 to use .tasks/tasks-test.jsonl -
Test suite automatically uses test mode - Never run destructive tests
on production database

This prevents accidental data loss like we experienced earlier when
test runs overwrote the production tasks.jsonl file.
---
 AGENTS.md | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

(limited to 'AGENTS.md')

diff --git a/AGENTS.md b/AGENTS.md
index 653e8f3..3cd9aa7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -255,11 +255,32 @@ States:
 
 ```
 .tasks/
-├── tasks.jsonl    # Git-tracked, source of truth
+├── tasks.jsonl       # Git-tracked, production database
+├── tasks-test.jsonl  # Test database (not tracked, auto-created)
 ```
 
 Each line in `tasks.jsonl` is a JSON object representing a task.
 
+## Testing and Development
+
+**IMPORTANT**: When writing or testing code that modifies tasks, use the test database:
+
+```bash
+# Set test mode to protect production database
+export TASK_TEST_MODE=1
+
+# Now all task operations use .tasks/tasks-test.jsonl
+task create "Test task" --type=task
+task list
+
+# Unset when done
+unset TASK_TEST_MODE
+```
+
+**The test suite automatically uses test mode** - you don't need to set it manually when running `task test` or `bild --test Omni/Task.hs`.
+
+**Never run destructive tests against the production database** (`.tasks/tasks.jsonl`) as this will delete real task data.
+
 ## Example Session
 
 ```bash
-- 
cgit v1.2.3