# Document Branch: Agent-scoped tracking branches

ID: `DBR-001`

## State

promoted

## Trigger

The repository has a document-branching method but no document-branch instances,
while parallel-agent guidance still requires one writer for all canonical state.
The MCP lock serializes processes only when they share one checkout; separate Git
worktrees have separate `.prd_plugin/local/` locks and registry snapshots.

## Hypothesis

Pre-allocate one lightweight `DBR-*` tracking branch per agent before fan-out.
Each worker updates only its assigned branch file. After worker branches are
merged, the lead promotes each tracking branch under the canonical state lock,
where `TRK-*` allocation, conflict checks, validation, and branch provenance are
applied atomically. This removes concurrent canonical-state writes without a
database, remote lock service, or distributed ID allocator.

## Scope

- Add MCP tools to open, update, and promote tracking branches.
- Store one machine-readable file per branch under
  `.prd_plugin/state/tracking-branches/`.
- Reuse `DBR-*`, `DBR-DELTA-*`, and `DBR-MERGE-*` IDs; allocate them only in the
  lead/canonical checkout before fan-out or during serialized promotion.
- Make promotion idempotent and reject unsafe concurrent changes to the same
  canonical tracking fields.
- Teach agent-team workflows that workers write assigned branches, never shared
  canonical state or the ID registry.

## Non-Goals

- No database, daemon, network coordinator, or remote lock.
- No automatic Git worktree creation or merging.
- No replacement of guarded evidence, decision, health, request, or changelog
  workflows.
- No numeric ID allocation by workers in isolated worktrees.

## Proposed Deltas

| ID | Target | Summary |
| --- | --- | --- |
| `DBR-DELTA-001` | `PRD-002` / `ARCH-002` / MCP state tools | Add agent-scoped tracking branches with serialized canonical promotion. |

## Evidence Requirements

- Two isolated roots based on the same registry can update different pre-created
  branch files without touching canonical tracking or registry state.
- After those files are combined, serialized promotion creates or updates
  canonical tracking records with unique IDs and no lost links or notes.
- Repeating promotion is idempotent.
- Conflicting non-additive updates are rejected with an actionable error.
- Existing single-writer tracking tools remain compatible.
- State, graph, release, drift, and CHML audits finish clean.

## Merge Criteria

All evidence requirements pass; the architecture and method docs describe the
lead/worker boundary; downstream templates and installed MCP payload are in
parity; `HLT-008` is resolved; and `REQ-087`/`TRK-079` link to fresh evidence.

## Regression Conditions

- A worker can allocate or mutate canonical `TRK-*` state from its isolated
  worktree instead of its assigned branch.
- Two branch promotions create the same canonical ID, lose an update, or silently
  overwrite a conflicting field.
- Promotion is not idempotent after a partial or repeated call.
- Downstream agent instructions still prescribe parallel canonical-state writes.

## Links

- `REQ-087`
- `TRK-079`
- `HLT-008`
- `PRD-002`
- `ARCH-002`
- `ARCH-RISK-004`