# Architecture Delta

Branch: `DBR-001`
Delta: `DBR-DELTA-001`

## Target Architecture

`PRD-002` and `ARCH-002`: the validated MCP state server, state store, registry
allocator, and parallel-agent write boundary.

## Proposed Component Or Decision Changes

1. Add a tracking-branch store at
   `.prd_plugin/state/tracking-branches/DBR-###.json`. Each file has one assigned
   writer and contains its base snapshot, proposed tracking fields, additive
   notes/links, provenance, and promotion state.
2. Add `prd_open_tracking_branch`, `prd_update_tracking_branch`, and
   `prd_promote_tracking_branch`.
3. Opening allocates `DBR-*` and `DBR-DELTA-*` while the lead owns the canonical
   registry. Workers update an already-assigned branch and allocate no IDs.
4. Promotion holds the existing canonical state lock, allocates a `TRK-*` only
   when creating new tracking, detects overlapping updates against the captured
   base snapshot, writes canonical state, allocates `DBR-MERGE-*`, and marks the
   branch promoted.
5. Promotion is idempotent: a promoted branch returns its existing canonical
   result and never allocates again.
6. Existing direct tracking tools remain for the lead/single-writer path.
   Parallel workers must use their assigned tracking branches.

## Rationale

The coordination problem is Git-level, not process-level. A filesystem lock
inside one checkout cannot coordinate separate worktrees. Unique pre-created
branch files let Git merge independent worker tracking cleanly, while the
existing lock and allocator remain the only authority for canonical state.

## Evidence Required

Focused tests must simulate independent worktree copies, branch-file merging,
serialized promotion, repeated promotion, and conflicting updates. Full gates
must prove the new branch files participate in consistency and traceability
validation.