Merge branch 'main' into cw/continuous-code-quality-conflict-1772832123778

# Conflicts:
#	apps/server/drizzle/meta/0037_snapshot.json
#	apps/server/drizzle/meta/_journal.json

docs/database-migrations.md

@@ -55,3 +55,27 @@ Migrations 0000–0007 were generated by `drizzle-kit generate`. Migrations 0008
 - **Migration files are immutable.** Once committed, never edit them. Make a new migration instead.
 - **Keep schema.ts in sync.** The schema file is the source of truth for TypeScript types; migrations are the source of truth for database DDL. Both must reflect the same structure.
 - **Test with `npm test`** after generating migrations to verify they work with in-memory databases.
+
+## Post-migration backfill scripts
+
+Some schema additions require a one-time data backfill because SQLite migrations cannot execute Node.js logic (e.g., JSON parsing). In these cases, the migration creates the table structure, and a separate Node.js script populates it from existing data.
+
+### agent_metrics backfill
+
+**When to run:** After deploying the migration that creates the `agent_metrics` table (introduced in the Radar Screen Performance initiative). Run this once per production database after upgrading.
+
+**Command:**
+```sh
+cw backfill-metrics
+# Or with a custom DB path:
+cw backfill-metrics --db /path/to/codewalkers.db
+```
+
+**What it does:**
+- Reads all existing `agent_log_chunks` rows in batches of 500 (ordered by `createdAt ASC`)
+- Parses each chunk's `content` JSON to count `AskUserQuestion` tool calls, `Agent` spawns, and compaction events
+- Upserts the accumulated counts into `agent_metrics` using additive conflict resolution
+
+**Idempotency:** The script uses `ON CONFLICT DO UPDATE` with additive increments, matching the ongoing write-path behavior. Running it against an empty `agent_metrics` table is fully safe. Running it a second time will double-count — only run it once per database, immediately after applying the migration.
+
+**Batch size:** 500 rows per query, to avoid loading the full `agent_log_chunks` table into memory. Progress is logged every 1,000 chunks.

docs/dispatch-events.md

@@ -93,6 +93,18 @@ InitiativeChangesRequestedEvent { initiativeId, phaseId, taskId }
 4. **Auto-queue tasks** — When phase starts (branches confirmed), pending execution tasks are queued (planning-category tasks excluded)
 5. **Events** — `phase:queued`, `phase:started`, `phase:completed`, `phase:blocked`
 
+### Auto-Integration Phase
+
+When `queueAllPhases` is called (i.e. the user clicks "Execute"), it auto-creates an **Integration** phase if the initiative has multiple end phases (leaf nodes with no dependents). This catches cross-phase incompatibilities before the initiative reaches review.
+
+- **Trigger**: `queueAllPhases` in `apps/server/trpc/routers/phase-dispatch.ts`
+- **Guard**: Only created when `endPhaseIds.length > 1` and no existing "Integration" phase
+- **Status**: Created as `approved` (same pattern as Finalization in orchestrator.ts)
+- **Dependencies**: Integration depends on all end phases — dispatched last
+- **Task**: A single `verify` category task instructs the agent to build, run tests, check types, and review cross-phase imports
+- **Idempotency**: Name-based check prevents duplicates on re-execution
+- **Coexistence**: Independent of the Finalization phase (different purpose, different trigger)
+
 ### PhaseDispatchManager Methods
 
 | Method | Purpose |
@@ -137,8 +149,11 @@ When an agent crashes (`agent:crashed` event), the orchestrator automatically re
 On server restart, `recoverDispatchQueues()` also recovers:
 - Stuck `in_progress` tasks whose agents are dead (status is not `running` or `waiting_for_input`) — reset to `pending` and re-queued
 - Erroneously `blocked` tasks whose agents completed successfully (status is `idle` or `stopped`) — marked `completed` so the phase can progress. This handles the legacy case where conflict resolution incorrectly blocked already-completed tasks.
+- Stale duplicate planning tasks — if a phase has both a completed and a pending task of the same planning category (e.g. two `detail` tasks from a crash-and-retry), the pending one is marked `completed` with summary "Superseded by retry"
 - Fully-completed `in_progress` phases — after task recovery, if all tasks in an `in_progress` phase are completed, triggers `handlePhaseAllTasksDone` to complete/review the phase
 
+The `detailPhase` mutation in `architect.ts` also cleans up orphaned pending/in_progress detail tasks before creating new ones, preventing duplicates at the source.
+
 Manual retry via `retryBlockedTask()` resets `retryCount` to 0, giving the task a fresh set of automatic retries.
 
 ### Coalesced Scheduling