From e5b83839ad1afe53111b3dd29758e64cf3774694 Mon Sep 17 00:00:00 2001
From: Bill <bill@bballou.com>
Date: Fri, 7 Nov 2025 13:28:26 -0500
Subject: [PATCH] docs: document duplicate prevention and cross-job continuity

Added documentation for:
- Duplicate simulation prevention in JobManager.create_job()
- Cross-job portfolio continuity in position tracking
- Updated CLAUDE.md with Duplicate Simulation Prevention section
- Updated docs/developer/architecture.md with Position Tracking Across Jobs section
---
 CLAUDE.md                      | 28 ++++++++++++++++++++++++++++
 docs/developer/architecture.md | 25 +++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 419870c..53ac528 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -202,6 +202,34 @@ bash main.sh
 - Search results: News filtered by publication date
 - All tools enforce temporal boundaries via `TODAY_DATE` from `runtime_env.json`
 
+### Duplicate Simulation Prevention
+
+**Automatic Skip Logic:**
+- `JobManager.create_job()` checks database for already-completed model-day pairs
+- Skips completed simulations automatically
+- Returns warnings list with skipped pairs
+- Raises `ValueError` if all requested simulations are already completed
+
+**Example:**
+```python
+result = job_manager.create_job(
+    config_path="config.json",
+    date_range=["2025-10-15", "2025-10-16"],
+    models=["model-a"],
+    model_day_filter=[("model-a", "2025-10-15")]  # Already completed
+)
+
+# result = {
+#     "job_id": "new-job-uuid",
+#     "warnings": ["Skipped model-a/2025-10-15 - already completed"]
+# }
+```
+
+**Cross-Job Portfolio Continuity:**
+- `get_current_position_from_db()` queries across ALL jobs for a given model
+- Enables portfolio continuity even when new jobs are created with overlapping dates
+- Starting position = most recent trading_day.ending_cash + holdings where date < current_date
+
 ## Configuration File Format
 
 ```json
diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md
index 7940e87..f01e3f2 100644
--- a/docs/developer/architecture.md
+++ b/docs/developer/architecture.md
@@ -66,3 +66,28 @@ See README.md for architecture diagram.
 - Search results filtered by publication date
 
 See [CLAUDE.md](../../CLAUDE.md) for implementation details.
+
+---
+
+## Position Tracking Across Jobs
+
+**Design:** Portfolio state is tracked per-model across all jobs, not per-job.
+
+**Query Logic:**
+```python
+# Get starting position for current trading day
+SELECT id, ending_cash FROM trading_days
+WHERE model = ? AND date < ?  # No job_id filter
+ORDER BY date DESC
+LIMIT 1
+```
+
+**Benefits:**
+- Portfolio continuity when creating new jobs with overlapping dates
+- Prevents accidental portfolio resets
+- Enables flexible job scheduling (resume, rerun, backfill)
+
+**Example:**
+- Job 1: Runs 2025-10-13 to 2025-10-15 for model-a
+- Job 2: Runs 2025-10-16 to 2025-10-20 for model-a
+- Job 2 starts with Job 1's ending position from 2025-10-15