# Document Branching

Document branching prevents unproven lessons from becoming mainline project
truth too early.

## Core Principle

```text
Mainline docs contain promoted truth.
Document branches contain proposed, experimental, or regressed truth.
```

## When To Create A Document Branch

Create a document branch for:

- critical path work
- emergent lessons
- proposed PRD changes
- proposed architecture changes
- implementation plan changes outside the active MVP scope
- fixes that appear to work but need proof
- regressions in previously promoted lessons
- disputed or reversible decisions

## Folder Shape

```text
docs/doc-branches/
  DBR-001-topic/
    BRANCH.md
    BRANCH.json
    PRD-DELTA.md
    ARCH-DELTA.md
    PLAN-DELTA.md
    EVIDENCE.md
    MERGE-CHECKLIST.md
```

## Branch States

| State | Meaning |
| --- | --- |
| `observed` | A problem, opportunity, or lesson has been noticed. |
| `hypothesis` | A proposed answer exists but is not proven. |
| `experimenting` | Work is underway to test the branch. |
| `proven` | Evidence supports promotion. |
| `promoted` | Mainline docs were updated from this branch. |
| `rejected` | Evidence did not support the branch. |
| `regressed` | A promoted branch no longer matches reality. |
| `retired` | The branch is obsolete or superseded. |

## Promotion Rule

Do not promote a branch into mainline docs unless it has:

- evidence ID
- code anchor, if applicable
- test anchor, if applicable
- telemetry query, if applicable
- last verified commit
- regression condition
- merge decision

If promotion also changes durable agent memory or tracking state, update the
relevant committed `.prd_plugin/state/*.json` file and include the originating
`AGENT-*`, `SES-*`, source references, and evidence link.

## Parallel Tracking Profile

Parallel-agent tracking uses a compact JSON profile of document branching:

1. Before fan-out, the lead calls `prd_open_tracking_branch` once per worker and
   commits the separate `.prd_plugin/state/tracking-branches/DBR-*.json` seeds.
   It launches each worker with `PRD_WORKER_SESSION=1`,
   `PRD_TRACKING_BRANCH_ID=<DBR-*>`, and `PRD_TRACKING_BRANCH_OWNER=<owner>`.
2. Each worker calls `prd_update_tracking_branch` only for its assigned branch.
   Worker updates allocate no IDs and do not touch canonical tracking or the
   registry, so separate worktrees can merge distinct files cleanly.
   The runtime rejects canonical state/registry tools and any DBR assignment or
   owner mismatch while `tracking.branching.require_for_parallel_agents` is true.
3. After worker code and tracking files merge, the lead calls
   `prd_promote_tracking_branch` serially. Promotion owns canonical `TRK-*` and
   `DBR-MERGE-*` allocation, merges additive notes/links, rejects overlapping
   field changes, records provenance, and is idempotent on retry.

The lead pre-allocates branches because isolated worktrees do not share the same
filesystem lock or live registry. Direct goal/create/update tools remain valid
for the lead and ordinary single-writer work.

Workers put requested non-TRK state changes in branch notes. The lead records
those `REQ-*`, `EV-*`, `DEC-*`, `CHG-*`, `HLT-*`, `MEM-*`, and session updates
serially after merge. `prd_status`, `prd_find(kind: DBR)`, and `prd_get(DBR-*)`
provide discovery without manually scanning the branch directory.

If promotion creates or resolves health findings, update
`.prd_plugin/state/health.json` with the relevant `HLT-*` records.

## Regression Rule

If telemetry, tests, or code inspection show a promoted branch no longer matches
the codebase, create a regression branch and mark the old branch as regressed or
superseded.