---
kind: decision
status: accepted
confidence: medium
---

# ADR — brain-state must preserve custom content

## Context

`tools/brain-state.mjs` regenerates `wiki/<scope>/state.md`, `roadmap.md`, and `options.md` from a generic template plus dynamic page lists. In a user session, running `brain_sync` after backfilling the upstream runner overwrote project-specific narrative in those pages. The user had to restore the custom content manually and resorted to `brain_validate + brain_views` to avoid the clobber.

These pages are `kind: state`, `roadmap`, and `options` with `status: living`. They are intended to be living documents that humans edit, not disposable generated views like `wiki/index.md`.

## Decision

`tools/brain-state.mjs` must preserve existing custom content in `state.md`, `roadmap.md`, and `options.md`. It will do this by using marker comments to delimit generated sections.

Generated sections will be wrapped like this:

```markdown
## What is stable

<!-- brain-state: stable -->
- `Some page` at `path/to/some-page.md`
<!-- /brain-state -->

Custom narrative added by the user survives regeneration.
```

### Behavior

1. If a target file does not exist, generate it from the template with markers.
2. If a target file exists and contains `<!-- brain-state: <section> -->` markers, replace only the content between matching markers.
3. If a target file exists but contains no markers, skip overwriting it and log a warning. The user can either add markers manually or delete the file to regenerate from scratch.

## Alternatives considered

1. **Keep current behavior.** Always overwrite.
   - *Rejected:* destroys user content, violates the living-document contract.

2. **Only generate if missing.** Never update existing state/roadmap/options pages.
   - *Rejected:* dynamic page lists would go stale; users would have to maintain them by hand.

3. **Diff/merge approach.** Three-way merge of generated and existing content.
   - *Rejected:* too complex and error-prone for this tool; marker boundaries are simpler and predictable.

4. **Marker-aware regeneration.** (Chosen.) Update only generated sections, preserve user narrative.
   - *Pros:* keeps dynamic lists fresh, protects custom content, easy to reason about.
   - *Cons:* requires users to understand the marker convention if they want predictable regeneration.

## Consequences

- Existing custom state/roadmap/options pages are safe from accidental overwrite.
- New pages generated by `brain-state` include markers so future regenerations work correctly.
- `brain_sync` becomes safe to run without fear of clobbering project narrative.
- Users who want a full reset can delete the file and re-run `brain_state`.

## Related

- `tools/brain-state.mjs`
- [wiki/brain/bets/brain-state-preserves-custom-content.md](../bets/brain-state-preserves-custom-content.md)