# BrainDrive Memory Architecture — Draft 3 Proposal

Date: 2026-05-26
Status: Proposal — pending Dave J review of Draft 3 evolution
Builds on: Draft 2 (2026-05-24)

*Forum-language framing: this is a proposed evolution of Draft 2, not a declared source of truth. Once reviewed and accepted, the "Changes from Draft 2" section moves to Appendix A and the doc opens with Position.*

## Changes from Draft 2

Draft 3 carries forward Draft 2's spine — app folders, AGENT/README orient split, Preservation Rule, common file shapes, reports lifecycle, fractal OAPEP, and the Finance proof. The substantive change is an explicit owner-customization overlay model:

1. **Managed base files get paired user overlays.** `AGENT.md` remains the BrainDrive-managed active-scope orient file; `AGENT-user.md` is the owner-managed overlay read immediately after it and given precedence where it conflicts. The same pattern applies to managed instruction and rule-framework files where owner customization is expected: `<name>.md` + `<name>-user.md`, or `<topic>-rules.md` + `<topic>-rules-user.md`.
2. **Starter-pack updates become deterministic where possible.** BrainDrive can update managed base files from the starter pack while preserving overlay files byte-for-byte. LLM merge becomes the exception for legacy customized files or ambiguous migrations, not the default path for ordinary owner customization.
3. **Owner customization is a first-class file primitive, not accidental drift.** Heavy edits no longer need to live inside starter-pack-owned files. Owners get a known place to add personal guidance, and the update system gets a known place it must not overwrite.
4. **Precedence is explicit.** Higher-level safety rules still apply, but within ordinary memory instructions the load order is base first, user overlay second. The overlay can narrow, personalize, or add owner-specific behavior; it cannot authorize destructive writes, secret storage, or violations of Preservation Rules.
5. **Draft 2's validated architecture remains intact.** Apps are still folders, state and methodology remain separated, Preservation Rule remains mandatory, reports still follow the cache/archive lifecycle, and OAPEP remains the operating model.

Sections that did not change materially from Draft 2 are preserved. Section numbers are not stable across drafts because of the inserts; a cross-reference table is in Appendix A.

---

## Position

BrainDrive memory architecture exists to keep owner memory understandable, editable, and scalable as BrainDrive moves from orientation and planning into doing useful work.

The core position:

> BrainDrive should keep high-level orientation short, place rules at the lowest useful level, use owner-facing **app folders** for work, separate **state from methodology** so weak models can't accidentally overwrite owner content, provide explicit **user overlay files** for owner customization, and rely on progressive disclosure so both the AI and the owner can understand the memory system without loading every instruction at once.

## 1. Core Architecture

BrainDrive memory follows a five-stage workflow:

1. Orient.
2. Align.
3. Plan.
4. Execute.
5. Propagate.

These are process stages, not all file types.

**The five stages are fractal.** The same OAPEP cycle recurs at every active scope:

```
BrainDrive scope (BD+1)  →  O A P E P
  Project scope          →   O A P E P
    App scope            →    O A P E P
      Procedure scope    →     O A P E P
```

Learning OAPEP once lets the agent navigate every scope. This is the *single* operating model — everything else is an implementation detail of how OAPEP gets carried out at a given scope.

The architecture has a stable set of primitives:

| Stage | Primitives |
|---|---|
| Orient | System prompt, `base/AGENT.md`, project `AGENT.md`, app `AGENT.md`, optional `AGENT-user.md` overlays, folder `README.md`, `me/profile.md` |
| Align | `spec.md` (+ `run-interview.md` procedure) |
| Plan | `plan.md` (+ `run-planning.md` procedure) |
| Execute | Apps (folders), Instructions, Sources, Reports |
| Propagate | No file primitive; behavior only |

Domain complexity scales by adding app folders, instruction depth, source collections, reports, and (where genuinely navigational) indexes. It does not scale by inventing new primitive types for every feature.

## 2. Natural-Language-First Principle

*(Unchanged from Draft 1.)*

BrainDrive's differentiator is that much of its behavior can live in owner-readable memory.

Default rule:

> If a behavior can be clearly expressed as natural-language instructions, templates, indexes, or documents, start there before adding code.

Code is still correct for: file I/O, upload plumbing, runtime validation, authentication and authorization, versioning and migration mechanics, deterministic safety checks, audit logs, model/tool routing, and anything natural language cannot reliably enforce.

Prompts, app instructions, project workflows, and owner-customizable behavior should start as documents.

## 3. Canonical Vocabulary

| Term | Meaning |
|---|---|
| App | Owner-facing work artifact. **An app is a folder** containing an orient file (`AGENT.md`), optional user overlays, a state artifact named for the folder (`budget/budget.md`), supporting rule-framework files and owner-rule overlays, and procedure files. |
| State artifact | Owner-readable file capturing the current state of an app (e.g., `budget.md` inside `budget/`). The owner's data lives here. Procedures must not overwrite it whole-file. |
| Instructions | AI-facing procedure, rule framework, owner-rule overlay, or composition logic. Lives in procedure files or rules files. |
| Procedure file | A file describing *how* a workflow runs (e.g., `create.md`, `compare.md`, `run-interview.md`). Carries a Preservation Rule. |
| Rules framework | BrainDrive-managed default rule framework for an app or topic (e.g., `budget-rules.md`). It defines how to interpret rules, default transaction types, safety notes, and starter examples. |
| Rules overlay | Owner-managed accumulated rules for an app or topic (e.g., `budget-rules-user.md`). It captures owner-approved merchant mappings, category preferences, transfer handling, and recurring exceptions. |
| AGENT.md | Orient file for an active scope — a place that *does* things. Project, app. |
| User overlay | Optional owner-managed instruction file read after its managed base file and given precedence where it conflicts (e.g., `AGENT-user.md`, `compare-user.md`, `budget-rules-user.md`). |
| README.md | Orient file for a reference folder — a collection that *is* something. Sources, reports. |
| Index | Folder map and optional routing — used where there is a navigable collection with no active scope (rare; most folders are either active or reference). |
| Sources | Uploaded or imported data consumed by apps or instructions (e.g., `statements/`). |
| Reports | Regenerated synthesis outputs the owner reads (e.g., `reports/`). |
| Active scope | A scope that does something — project, app. Has an `AGENT.md` and may have an `AGENT-user.md`. |
| Reference folder | A collection that is consumed — sources, reports. Has a `README.md` and rarely a `README-user.md`. |
| Propagate | Post-execution behavior that syncs affected memory and returns up the scope chain. |

Retired vocabulary:

- "Executable" as a canonical noun (carried forward from Draft 1).
- `index.md` inside app folders (replaced by `AGENT.md`). Standalone `index.md` may still be used at project scope when a flat file listing is the right tool; default is AGENT.md.

## 4. Layer Model

| Layer | Purpose | What Belongs Here |
|---|---|---|
| System prompt | Universal BrainDrive behavior | Rules that apply everywhere; current date (see §9) |
| `base/AGENT.md` | Cross-project orientation and routing | Project list, global routing signals, active cross-project state |
| `base/AGENT-user.md` | Owner overlay for cross-project behavior | Owner-authored global custom instructions; read after `base/AGENT.md` |
| `me/profile.md` | Cross-project owner context | Stable owner facts, values, preferences, life context |
| Project `AGENT.md` | Domain orientation | What this domain is, boundaries, available apps/files |
| Project `AGENT-user.md` | Owner overlay for a domain | Project-specific owner instructions that override or narrow the project orient |
| Project `spec.md` | Align | Goals, current state, success criteria, constraints |
| Project `plan.md` | Plan | Milestones, sequence, next steps, dependencies |
| App folder | Execute | Owner-facing work; folder contains AGENT.md (orient) + optional overlays + state artifact + rules + procedures |
| App `AGENT-user.md` | Owner overlay for an app | App-specific owner customizations read after app `AGENT.md` |
| Procedure file | Execute support | Narrow procedure for one workflow, with Preservation Rule |
| Procedure overlay | Execute support | Optional owner customization for a managed procedure (e.g., `compare-user.md`) |
| Folder `README.md` | Reference contract | What's in this folder, how files are named, how to read them |
| Source | Evidence/data | Uploaded or imported documents/data |
| Report | Output | Regenerated synthesis for the owner |

Higher-level rules apply to everything below them. The higher a rule is placed, the more universal it must be.

## 5. Orient

*(Unchanged from Draft 1, with the routing example updated to the app-folder shape.)*

Orient answers: Where am I? Who am I helping? What project or domain is active? What files and apps exist here? Where should I route this request?

Orient files should be short. They should not carry detailed app workflows.

Correct pattern:

- `base/AGENT.md` says Finance exists and routes finance work there.
- `base/AGENT-user.md`, if present, adds owner-specific global guidance after the base orient.
- Finance `AGENT.md` says Budget exists and routes to `budget/`.
- Finance `AGENT-user.md`, if present, adds or narrows Finance-specific guidance after Finance `AGENT.md`.
- `budget/AGENT.md` says what the Budget app is, names its state artifact (`budget.md`) and procedures (`create.md`, `compare.md`), and carries the Preservation Rule for `budget.md`.
- `budget/AGENT-user.md`, if present, adds owner-specific Budget guidance without modifying the managed app orient.
- A procedure file says how *one* workflow runs; nothing more.

Incorrect pattern:

- `base/AGENT.md` explains the whole budget workflow.
- Finance `AGENT.md` contains every bank statement rule.
- `budget/AGENT.md` becomes an 80-line procedure dump.

Orient reappears at every active scope: BrainDrive (base/AGENT.md), project (project AGENT.md), app (app AGENT.md). If a matching `AGENT-user.md` exists, it is read immediately after the base orient for that scope. The same five-stage cycle runs inside each one. See §1.

## 6. Align

In BrainDrive, Align is project `spec.md`. *(Unchanged from Draft 1.)*

The spec is not a rigid universal form. Each domain may need different questions and different success criteria. Finance, Fitness, Career, and Relationships can each have different spec shapes, but they all serve the same purpose: alignment.

When alignment behavior changes, update the relevant `spec.md` template — and, if the procedure for filling it changes, update the project's `run-interview.md`.

## 7. Plan

In BrainDrive, Plan is project `plan.md`. *(Unchanged from Draft 1.)*

The plan depends on orientation and alignment, but planning instructions live in `run-planning.md` (the procedure file), not in high-level orientation.

## 8. Execute

Execute is where BrainDrive does work for the owner.

Execute answers: What useful work can BrainDrive now perform? What owner-facing artifact or workflow supports progress? What source files, instructions, and reports are needed?

Execute-stage files fit five types:

| Type | Meaning | Shape | Examples |
|---|---|---|---|
| Apps | Owner-facing work folders | Folder with `AGENT.md` + optional `AGENT-user.md` + state artifact + rules + procedures | `budget/`, `todo/` (future), `journal/` (future), `investments/` (future) |
| Instructions | AI-facing procedures, rule frameworks, and owner-rule overlays | Procedure files (verb-named), optional procedure overlays, managed rule frameworks (`*-rules.md`), and owner-rule overlays (`*-rules-user.md`) | `create.md`, `compare.md`, `compare-user.md`, `budget-rules.md`, `budget-rules-user.md`, `net-worth.md` |
| Sources | Uploaded/imported evidence | Reference folder with `README.md` | `statements/`, `health-docs/` |
| Reports | Regenerated owner-readable outputs | Reference folder with `README.md`; `latest.md` cache + dated archives | `reports/latest.md`, `reports/monthly-2026-05.md` |
| Indexes | (Optional) flat folder listings | `index.md` when there is no active scope to orient — rare | Used sparingly; default is `AGENT.md` or `README.md` |

The boundary between Apps and Instructions matters: **state lives in apps, methodology lives in instructions**. Procedures may read app state and write to it according to the Preservation Rule, but they never replace the state artifact whole-file. Owner customizations to managed methodology belong in `*-user.md` overlays when possible, not as edits inside starter-pack-owned base files.

## 9. Preservation Rule

*New in Draft 2. Bedrock fix for the F-002 class of bugs.*

Every procedure file that touches a state artifact carries a Preservation Rule at the top.

The Preservation Rule says:

- **Update sections in place — never replace the whole file.**
- **Always keep:** every section header, every italic section description, every `*Last updated: …*` line, the `**Status:**` line, the `## Changelog`. If a section has no owner content yet, leave its placeholder text in place.
- **You may remove:** generic example blockquotes once a section has real owner content (unless the examples are still useful for orientation).
- **Use today's date** from your current system context for "Last updated" lines and changelog entries. Do not invent a date.

Procedures that build new files (e.g., a new monthly report) do not need a Preservation Rule for their *output*, but they do need one for any state artifact they read.

This rule is the bedrock. Without it, weak models conflate "edit a section" with "rewrite the file" and the owner's data is gone. With it (and the app-folder separation of state from methodology), state artifacts survive byte-for-byte across procedure runs. See `test-run-2026-05-24-run2-claude.md` for the empirical validation under Gemini 3.5 Flash.

The Preservation Rule depends on the current date being available. **The bootstrap prompt should inject `Today's date is YYYY-MM-DD.`** at the top, so the rule has something real to refer to. This is an app-side change in `readBootstrapPrompt` (currently outstanding — see PR #127 open items).

## 10. Active And Reference Files

Use the Onion Test:

> Does this file do something, or is it consumed by something that does?

If it does something, it is **active** — and it carries instructions, almost always including a Preservation Rule.

Active files:

- Project `AGENT.md`.
- Project `AGENT-user.md` when present.
- `spec.md`, `plan.md`.
- App `AGENT.md` and procedure files (`create.md`, `compare.md`, `run-interview.md`, `run-planning.md`).
- App and procedure overlays (`AGENT-user.md`, `compare-user.md`) when present.
- State artifacts (`budget.md`) — active in the sense that they hold owner state and are read by procedures; they are owner-facing and rarely carry procedural instructions themselves.
- Rules frameworks and rules overlays (`budget-rules.md`, `budget-rules-user.md`).

Reference material:

- Sources (with `README.md` describing the folder contract).
- Reports (with `README.md` describing the output contract and lifecycle).

Reports may contain light notes about how to read the report, but detailed workflow belongs in procedure files. Sources should be labeled and organized, not instruction-bearing.

## 11. Progressive Disclosure

*(Unchanged from Draft 1.)*

Progressive disclosure is the central scaling rule.

The agent should see: a short orientation, a pointer to the relevant next file, any matching user overlay for that file, and only the detailed instructions needed for the current task.

The agent should not load every possible instruction just in case.

Canonical rule:

> Instructions live in the active file that owns the current scope. If that scope becomes too complex, the active file points to child instruction files that own narrower scopes.

Overlay rule:

> When a managed file has a matching `*-user.md` overlay, read the managed file first and the user overlay second. The overlay may add, narrow, or personalize behavior. It does not replace higher-level safety, Preservation Rules, or runtime validation.

Do not split prematurely. If an app only needs one or two local instructions, keep them in the app's `AGENT.md`. If the instruction section becomes hard for a human to understand comfortably, create narrower procedure files. If the owner wants personal behavior that should survive starter-pack updates, place it in the matching `*-user.md` overlay instead of editing the managed file.

## 12. App Folder Shape

*Major revision of Draft 1 §11 "App File Shape." Apps are folders in Draft 2; this section defines the folder's contents.*

An app is a folder named for the capability it provides. Inside the folder:

```
budget/
├── AGENT.md              ← managed orient + Preservation Rule + procedure map
├── AGENT-user.md         ← optional owner overlay for this app
├── budget.md             ← state artifact (owner data; same name as folder)
├── budget-rules.md       ← managed default rule framework
├── budget-rules-user.md  ← owner-approved accumulated rules
├── create.md             ← managed procedure: create or revise the saved budget
├── create-user.md        ← optional owner overlay for create.md
├── compare.md            ← managed procedure: compare statements against the saved budget
└── compare-user.md       ← optional owner overlay for compare.md
```

The state artifact has the same name as the folder. This is the rule that lets the owner and the agent both find it without ambiguity: an app at `documents/finance/budget/` always has its state at `documents/finance/budget/budget.md`.

The app's `AGENT.md` is short. It orients (what this app does, two-jobs framing), names the Preservation Rule for the state artifact, lists the procedures with one-line summaries, and stops. It does not duplicate the procedures themselves. If `AGENT-user.md` exists, the agent reads it after `AGENT.md` and treats it as the owner-managed overlay for this app.

The app's rule files have split ownership:

- `budget-rules.md` is the BrainDrive-managed default rule framework. It explains how to apply rules, names allowed transaction types, carries starter defaults, and may be updated by starter-pack updates.
- `budget-rules-user.md` is the owner-managed accumulated rules file. It captures owner-approved merchant/category mappings, transfer handling, recurring exceptions, and personal category preferences. Starter-pack updates must never overwrite it.

The state artifact follows the **Common Artifact-File Shape** (§14). Procedures follow the **Common Procedure-File Shape** (§13).

Owner customization works the same way the Draft 1 "view mode / edit mode" pattern wanted to enable — except now the owner can open the state artifact (`budget.md`), the managed procedures (`create.md`, `compare.md`), or the user overlays (`create-user.md`, `compare-user.md`) as separate files. Default customization should use overlays because they survive starter-pack updates without an LLM merge. The agent's instructions are in plain English, in files the owner can read and edit. No code, no schema. This is the natural-language-first principle (§2) at the app level.

Rationale for the folder shape (not in Draft 1):

- **F-002 evidence.** When state and instructions live in the same file, weak models overwrite the file when they think they're editing the instructions. The Finance migration test against the old single-file shape produced this bug under Gemini 2.5 Flash. The folder shape with separated state passed the same test class under Gemini 3.5 Flash with byte-preservation guaranteed.
- **Uniformity.** Every app is a folder, with no threshold. Draft 1 §25 had "exact threshold for when a one-file app becomes an app folder" as an open question. Draft 2's answer: there is no threshold. Always a folder. Simpler for the architecture and the agent to reason about.
- **Composition.** Multi-app compositions (§20) read state artifacts from sibling folders cleanly — `net-worth.md` reads `budget/budget.md` and `investments/investments.md`.

## 13. Common Procedure-File Shape

*New in Draft 2.*

Every procedure file follows the same shape so weak models have a predictable form:

```markdown
# <Workflow Name>

*One-line italic descriptor — what this workflow does and who runs it.*

## Preservation Rule

(see §9)

## What This Procedure Accomplishes

The two jobs this procedure delivers on. Brief.

## When to Run

Bullet list of triggers.

## Method

How the agent runs the workflow. Behavioral defaults, applied conversationally — not a checklist.

## Done Criteria

What "good enough to stop" looks like.

## After Running

What to update once the workflow completes (state artifact, changelog, propagation).

## What This Procedure Is Not

Anti-patterns specific to this workflow.
```

A procedure file with all seven sections in this order is well-formed. Procedures may add a "Reference" section at the bottom (e.g., pointing to example shapes) but they should not invent new top-level sections without a reason.

## 14. Common Artifact-File Shape

*New in Draft 2.*

Every owner-facing state artifact follows the same shape:

```markdown
# <Artifact Title>

*One-line italic descriptor — what this artifact is and how it's used.*

**Status:** <one line>

**Last updated:** <today's date or em-dash>

## <Section 1>

*Italic section description — what content goes here.*

<Section content; placeholders for sections without owner content yet.>

## <Section 2>

…

## Changelog

Material changes only.

*Example entries left for reference until real entries replace them.*
```

The mandatory header fields are Status, Last updated, and the existence of a `## Changelog` section. Sections inside the artifact are domain-specific (Finance's `spec.md` differs from Fitness's), but the wrapper is uniform.

## 15. Managed Base And User Overlays

*New in Draft 3. Owner customization path for starter-pack-managed instruction files.*

BrainDrive distinguishes **managed base files** from **owner-managed overlay files**.

Managed base files are shipped by BrainDrive and may be updated by starter-pack updates:

- `AGENT.md`
- procedure files such as `create.md`, `compare.md`, `run-interview.md`
- rule-framework files such as `budget-rules.md`
- reference contracts such as `README.md` when the folder contract is part of the starter pack

User overlay files are created or edited by the owner and are never overwritten by starter-pack updates:

- `AGENT-user.md`
- `<procedure>-user.md` (e.g., `compare-user.md`)
- `<topic>-rules-user.md` (e.g., `budget-rules-user.md`)
- `README-user.md` only when a reference folder genuinely needs owner-specific reading or naming guidance

Read order:

1. Read the managed base file.
2. If the matching user overlay exists, read it next.
3. Apply the overlay where it adds, narrows, or personalizes behavior.
4. If base and overlay conflict, the overlay wins unless it conflicts with a higher-level safety rule, a Preservation Rule, code-enforced invariant, or explicit owner data in a state artifact.

Write ownership:

- Starter-pack updates may create or replace managed base files.
- Starter-pack updates must not overwrite `*-user.md` overlay files.
- The agent may create an overlay when the owner asks for persistent customization.
- The agent may edit an overlay when the owner asks to change their custom instruction.
- The agent should avoid editing managed base files for owner preference changes unless the owner is intentionally authoring a new reusable default.

This turns owner customization from accidental starter-pack drift into a supported extension point. It also reduces reliance on LLM merges: the normal update path is "update base, preserve overlay," while legacy customized base files still require merge, approval, or defer.

Overlay files are not state artifacts. They carry instructions, preferences, and owner-approved rules; they do not replace `spec.md`, `plan.md`, `budget.md`, `me/profile.md`, or other owner-state files.

For rules, the split is explicit:

```text
budget-rules.md        BrainDrive-managed default rule framework
budget-rules-user.md   owner-approved accumulated rules
```

The agent reads `budget-rules.md` first, then `budget-rules-user.md` if present. Default rule semantics come from the managed framework; owner-specific learned rules live in the user overlay.

## 16. Naming Rules

| Function | Pattern | Examples |
|---|---|---|
| App folder | Bare noun | `budget/`, `journal/`, `workout-log/` |
| State artifact | Same name as folder | `budget/budget.md`, `journal/journal.md` |
| Procedure | Verb-first | `compare.md`, `create.md`, `generate-report.md`, `run-interview.md`, `run-planning.md` |
| Rules framework | `<topic>-rules.md` | `budget-rules.md`, `source-rules.md` |
| Owner rules overlay | `<topic>-rules-user.md` | `budget-rules-user.md`, `source-rules-user.md` |
| User overlay | Add `-user` before `.md` | `AGENT-user.md`, `compare-user.md`, `budget-rules-user.md`, `README-user.md` |
| Composition | Clear noun or verb phrase | `net-worth.md`, `compute-net-worth.md` |
| Active-scope orient | `AGENT.md` | At project, app levels |
| Reference-folder orient | `README.md` | `statements/README.md`, `reports/README.md` |
| Index (rare) | `index.md` | Only where a navigable listing exists with no active scope |

Rules:

- Apps do not need `-app`.
- Procedures do not need `-procedure`.
- User overlays always use `-user`, not `custom`, `local`, `mine`, or owner initials.
- `AGENT-user.md` pairs with `AGENT.md`; do not name it `user-AGENT.md`.
- `spec.md` is reserved for project-level Align. Do not put `spec.md` inside app folders.
- Active scopes get `AGENT.md`. Reference folders get `README.md`. The verb/noun distinction signals "does things" vs "is consumed."

## 17. Folder Orient Files

Replaces Draft 1 §13 "Index Rules."

Folders fall into two roles:

| Role | Orient file | Examples |
|---|---|---|
| Active scope (does things) | `AGENT.md`, optional `AGENT-user.md` | `documents/finance/`, `documents/finance/budget/` |
| Reference folder (is consumed) | `README.md`, rarely `README-user.md` | `documents/finance/statements/`, `documents/finance/reports/` |

Rules:

- An active scope's `AGENT.md` orients the agent and points to the procedures it contains. It is short (one screen).
- If an active scope has `AGENT-user.md`, read it immediately after `AGENT.md` and apply it as the owner overlay for that scope.
- A reference folder's `README.md` describes the folder's contract — what files belong here, naming conventions, lifecycle rules. It is read by procedures before they touch the folder.
- If a reference folder has `README-user.md`, read it immediately after `README.md` and use it for owner-specific naming or reading preferences.
- A simple project with one app may still benefit from listing the app in the project `AGENT.md`.
- A flat `index.md` is used only when there is genuinely no active behavior to orient — i.e., navigation-only listings. Inside app folders, prefer `AGENT.md`.

Pattern for an app `AGENT.md`:

```markdown
# Budget — Agent Context

*App folder for managing the owner's saved monthly spending plan.*

## What This App Does

[Two-jobs framing: maintain saved budget + compare actuals against it.]

## App-Level Flow

[Brief OAPEP-style: orient (this file), align (with project spec), plan
(scope of this run), execute (run a procedure), propagate (back up).]

## Preservation Rule

[Quote the rule for budget.md. Procedures must update sections in place,
never replace whole-file.]

## Procedures

| Workflow | Use when | Read |
|---|---|---|
| Create or revise saved budget | Owner wants to define or change limits | `create.md`, then `create-user.md` if present |
| Monthly comparison | Owner asks how they're doing vs. the saved budget | `compare.md`, then `compare-user.md` if present |
| Source upload routing | Owner uploads statements | `../statements/README.md` |
```

The file listing is the floor. Common-request hints are an optimization where the routing isn't obvious.

## 18. Cross-Project Scope

BD+1 is a cross-project scope, not a normal domain project.

It contains:

- `base/AGENT.md` (the BD+1 orient file).
- `base/AGENT-user.md` (optional owner overlay for global custom instructions).
- `me/profile.md`.
- `me/todo.md`.

There is no BD+1 `spec.md` or `plan.md` for now. Reasoning carries forward from Draft 1.

Revisit if Whyfinder or another life-level artifact needs a cross-project Align/Plan layer.

## 19. Profile Rules

*(Unchanged from Draft 1.)*

`me/profile.md` is the highest-trust owner memory file because it affects every project.

Boundary rule:

> Relevant in multiple projects → profile. Relevant in one project → that project's `spec.md`.

Examples:

| Fact | Placement |
|---|---|
| Owner age | `me/profile.md` |
| Communication preference | `me/profile.md` |
| Self-employed | `me/profile.md` |
| Wants to retire at 55 | Finance `spec.md` |
| Carries credit card debt | Finance `spec.md` |
| Does StrongLifts 3x/week | Fitness `spec.md` |

Write rule:

- Stated cross-project facts can be added.
- Inferred facts require confirmation.
- Do not silently turn a project-specific fact into a profile fact.
- No profile tiering for now.

## 20. Composition

When apps combine, composition is an Instruction file. It is not a new primitive. *(Carried from Draft 1, with app-folder paths.)*

Example: `documents/finance/net-worth.md`

- Reads `budget/budget.md`.
- Reads `investments/investments.md` (future app).
- Defines how to compose them.
- Produces `reports/net-worth-latest.md`.

Compositions reach apps via the app's `AGENT.md` (the orient), not directly to the state artifact. The composition's procedure reads `budget/AGENT.md` first so it sees the Preservation Rule, then reads `budget/AGENT-user.md` if present, then reads `budget/budget.md`.

Composition can live at project scope (`documents/finance/net-worth.md`) or cross-project scope (e.g., a `life-dashboard.md` reading from multiple projects) depending on what it combines.

Lower-level apps should not need to know every higher-level composition that might use them.

## 21. Propagate

*Carries Draft 1's spirit; refined by Run 2 observation.*

Propagate is behavior, not a file primitive.

Minimum responsibilities:

1. Report what happened.
2. Sync affected memory.
3. Return up the scope chain.
4. Decide what the owner should see or do next.

After execution, BrainDrive may need to update:

- App state (when the workflow's job is to change it).
- Reports (always, as the output of a comparison or synthesis).
- Indexes or source manifests.
- Project `spec.md` if goals/current state changed materially.
- Project `plan.md` if milestones or next steps changed.
- `me/profile.md` only for confirmed cross-project facts.
- `me/todo.md` for new active tasks.
- Audit logs where needed.

**Propagation rule (from Run 2):** summarize material changes, don't copy. When a comparison surfaces an insight, the agent updates `spec.md`'s "Where You Are" or `plan.md`'s phase status with a brief summary — it does not paste the full report content into the spec. Reports are the synthesis; specs and plans hold the orientation.

The agent must not get stuck deep inside a narrow execution task. After completing a subtask, it should return upward and ask: What changed? Which parent artifacts need updating? Which reports are stale? Which next actions should be created? What should the owner see now?

## 22. Reports Lifecycle

*New in Draft 2. Bug class caught and fixed in Run 1 → Run 2.*

The `reports/` folder distinguishes two file types:

- **`latest.md`** — working cache of the most recent comparison. **Overwritten on every run.** Use this for continuity across sessions and quick re-reference. Not the canonical history.
- **`<period>-<id>.md`** (e.g., `monthly-2026-05.md`) — durable archive. **Written only when the period is complete** (today's date is strictly after the last day of the period being reported). Preserved as stable history once written.

Default behavior: write `latest.md` only. Archives are the exception.

**Anti-pattern (caught in Run 1):** writing the dated archive for an open month. If today is 2026-05-24 and the report covers May 2026, the month is still open — write `latest.md` only. Mid-month archives create snapshots that the next run will overwrite, defeating the "durable" guarantee.

Other apps may add their own report types (`net-worth-latest.md`, `quarterly-2026-Q1.md`). The same lifecycle rule applies: working cache by default; dated archive only when the period is closed.

## 23. Finance Direction

Finance/Budgeting is the first proof of the Execute architecture. **Migrated and tested in PR #127.**

Implemented shape (from PR #127):

```text
documents/finance/
├── AGENT.md                ← managed project orient
├── AGENT-user.md           ← optional owner overlay for Finance
├── spec.md                 ← Align stage (state artifact)
├── run-interview.md        ← procedure for filling spec.md
├── run-interview-user.md   ← optional owner overlay for interview behavior
├── plan.md                 ← Plan stage (state artifact)
├── run-planning.md         ← procedure for filling plan.md
├── run-planning-user.md    ← optional owner overlay for planning behavior
├── budget/                 ← Budget app folder
│   ├── AGENT.md            ← managed app orient + Preservation Rule
│   ├── AGENT-user.md       ← optional owner overlay for Budget
│   ├── budget.md           ← state artifact
│   ├── budget-rules.md     ← managed default rule framework
│   ├── budget-rules-user.md ← owner-approved accumulated rules
│   ├── create.md           ← workflow A
│   ├── create-user.md      ← optional owner overlay for workflow A
│   ├── compare.md          ← workflow B
│   └── compare-user.md     ← optional owner overlay for workflow B
├── statements/
│   └── README.md           ← sources folder contract
└── reports/
    └── README.md           ← reports folder contract + lifecycle rules
```

Test evidence: `test-run-2026-05-24-claude.md` (Run 1) and `test-run-2026-05-24-run2-claude.md` (Run 2). Both used Gemini 3.5 Flash via OpenRouter against a fresh-provisioned Docker dev stack. The Run 2 report under natural interview pacing is the strongest empirical validation.

Do not put full budget execution behavior in Finance `AGENT.md`. It points to the Budget app; the app's `AGENT.md` points to its procedures. Put owner-specific Finance or Budget preferences in the matching `AGENT-user.md`, procedure overlay, or rules overlay. For budget rules specifically, keep reusable default semantics in `budget-rules.md` and learned owner-approved rules in `budget-rules-user.md`.

## 24. Fitness And Health Direction

*(Unchanged from Draft 1.)*

Health records are currently Fitness context, not a standalone Health product.

- Health records support Fitness alignment and planning.
- Uploaded health documents are Sources under the Fitness scope.
- Fitness `spec.md` captures relevant health constraints and context.
- Fitness `plan.md` uses that context for safe, realistic planning.
- BrainDrive should not become symptom triage, diagnosis, or disease-management software through this path.

Fitness/Health is the second proof that the document-processing substrate generalizes beyond Finance. When migrated, it adopts the same app-folder shape (e.g., `documents/fitness/workout-log/AGENT.md`, `workout-log/workout-log.md`).

## 25. Owner Customization

*Updated in Draft 3 to make customization a supported overlay path.*

Owner-authored memory is owner data.

- Default templates define the supported path.
- Owners can edit natural-language app and instruction files, but persistent custom behavior should default to `*-user.md` overlays.
- Managed base files carry BrainDrive defaults. Overlay files carry owner-specific customizations.
- Managed rule-framework files carry reusable BrainDrive defaults. Rules overlays carry owner-approved accumulated rules.
- Read managed base first, then read the matching overlay if present.
- Overlay guidance takes precedence over the managed base unless it conflicts with safety, Preservation Rules, runtime validation, or explicit owner state.
- Do not silently overwrite owner-authored specs, plans, apps, instructions, or reports.
- Starter-pack updates may update managed base files; they must preserve overlay files.
- Legacy customization inside managed base files must still merge carefully, request approval, or defer.
- Heavy customization inside overlays stays inside default guarantees because the overlay is the supported extension point.

The Preservation Rule (§9) is the per-turn equivalent of this rule: even within a procedure run, the agent does not overwrite owner content.

## 26. Harness Direction

*(Unchanged from Draft 1.)*

Harness work supports real product proof. It should not become the main objective.

Two harness purposes remain distinct:

- Full application harness: UI, upload flow, front-end behavior.
- Starter-pack/persona harness: lower-cost prompt and memory testing.

Finance and Fitness/Health validation are the priority.

## 27. Placement Workflow

*Updated from Draft 1 §22 to reflect the folder-shape changes.*

When adding or reviewing a file, follow this workflow:

1. **Identify scope.** Cross-project, project, app, procedure, source collection, or report.
2. **Identify whether the file is active or reference.** Active files do something (AGENT.md, overlays, procedures, state artifacts, rule frameworks, owner-rule overlays); reference files are consumed (sources, reports, READMEs).
3. **Classify the file.** Orient (AGENT.md / README.md), user overlay, `spec.md`, `plan.md`, state artifact, procedure, rule framework, owner-rule overlay, source, or report.
4. **If it's a new app, it's a folder.** Don't create a flat `<app>.md`. Folder with AGENT.md + optional AGENT-user.md + state artifact + procedures from day one.
5. **Place instructions at the lowest useful level.** Do not move narrow rules upward for convenience.
6. **Decide ownership.** BrainDrive defaults go in managed base files; owner-specific custom behavior goes in `*-user.md` overlays.
7. **If active and updateable, write a Preservation Rule.** Every procedure that touches a state artifact carries one.
8. **Check for bloat.** If a procedure file is becoming hard to understand, split into narrower procedure files.
9. **Check propagation impact.** Decide what should update after the work runs.

## 28. Review Tests

Before accepting a memory architecture change, ask:

- Does every new file fit an existing primitive?
- Is the file at the right scope?
- If the new file is an app, is it a folder with `AGENT.md` + state artifact + procedures?
- If it is owner customization for a managed instruction file, is it in the matching `*-user.md` overlay?
- If it is an owner-approved accumulated rule, is it in `<topic>-rules-user.md` rather than the managed `<topic>-rules.md` framework?
- Is the base/overlay read order clear?
- If active, does it self-describe in its header? Status, Last updated, Changelog for artifacts; Preservation Rule for procedures.
- If reference, is it free of detailed workflow instructions?
- Does it duplicate instructions from another file?
- Does it push narrow rules too high?
- Does it rely on prompt text for runtime invariants that code should enforce?
- Does the active-scope `AGENT.md` route common requests without hiding the full file listing?
- Does Propagate know what may need to change afterward?
- (New) Will the static-pack lint (`tools/architecture-lint/`) pass? Folder has AGENT.md, artifact has metadata, overlay names are canonical, no stale paths, no `memory_edit` leakage.

## 29. Anti-Patterns

Avoid (Draft 1's list, extended):

- Giant system prompts.
- Giant `base/AGENT.md`.
- Giant project `AGENT.md`.
- Hiding full app workflows in project orientation.
- Moving a giant procedure from `AGENT.md` into an app header and calling it fixed.
- Loading every instruction file just in case.
- Turning Sources into procedure files.
- Turning Reports into procedure files.
- Creating a new primitive before proving the current primitives cannot express the use case.
- Overbuilding Propagate before Budget and Fitness/Health prove Execute.
- **(New) State and methodology in the same file.** F-002 class — weak models overwrite owner content when "editing" the instructions section. Apps are folders.
- **(New) Writing the dated archive for an open period.** §22.
- **(New) Inventing a date.** §9 — use today's date from the system prompt, ask the owner if unavailable, never make one up.
- **(New) `index.md` inside an app folder.** Use `AGENT.md` for active scopes.
- **(New) Editing managed base files for personal preference drift.** Put owner customization in `*-user.md` overlays so starter-pack updates remain clean.
- **(New) Writing owner-learned rules into managed rule frameworks.** Put owner-approved accumulated rules in `<topic>-rules-user.md`, not `<topic>-rules.md`.
- **(New) Treating overlays as safety overrides.** User overlays can personalize behavior; they cannot cancel Preservation Rules, authorization checks, or runtime invariants.

## 30. Current Decisions

Locked for Draft 3:

- Five-stage workflow: Orient, Align, Plan, Execute, Propagate (and OAPEP is fractal).
- Canonical Execute vocabulary: Apps, Instructions, Sources, Reports, with Indexes used sparingly.
- "Executable" retired as a canonical noun.
- Propagate is behavior, not a primitive.
- BD+1 is cross-project scope, not a standard project.
- No BD+1 `spec.md` or `plan.md` for now.
- Profile is highest-trust cross-project memory.
- Finance/Budgeting is first Execute proof. **Migrated and tested in PR #127.**
- Fitness/Health documents are Fitness context for MVP.
- **(New) Apps are folders, uniformly.** No threshold.
- **(New) Active scopes use `AGENT.md`. Reference folders use `README.md`.** `index.md` retired inside app folders.
- **(New) Preservation Rule is mandatory on every procedure file that touches a state artifact.**
- **(New) Reports archive only on closed periods.**
- **(New in Draft 3) Managed base files may have matching `*-user.md` overlays.** Base is updateable by starter-pack updates; overlay is owner-owned and takes precedence during reads.
- **(New in Draft 3) Rules split by ownership.** `<topic>-rules.md` is the BrainDrive-managed default rule framework; `<topic>-rules-user.md` is the owner-approved accumulated rules file.
- **(New in Draft 3) Starter-pack updates preserve overlays byte-for-byte.** LLM merge is for legacy customized base files and ambiguous migrations, not the normal customization path.

Resolved from Draft 1's "Still open":

- ~~Exact migration path from current repo layout to this model~~ → done for Finance in PR #127.
- ~~Exact threshold for when a one-file app becomes an app folder~~ → no threshold; always a folder.

Still open:

- Minimum Propagate protocol after the next app example is stable.
- How to audit whether the agent followed progressive disclosure.
- Exact migration path for legacy users who already customized managed base files before overlays existed.
- Date-injection mechanism — the architecture says "use today's date"; this requires `readBootstrapPrompt` to prepend it (~2-line app change, flagged in PR #127).
- Owner-facing sidebar UX (carryover from F-UI1) — should the project sidebar hide agent-instruction files behind an Advanced toggle?
- Owner-facing edit UX for overlays — should the default "customize" action open/create `*-user.md` instead of the managed base file?

## 31. One-Sentence Source Of Truth

BrainDrive scales by keeping high-level orientation short (AGENT.md), separating state from methodology so weak models can't overwrite owner content (apps are folders), preserving owner customization in `*-user.md` overlays, placing rules at the lowest useful level (Preservation Rule per procedure), and letting the same OAPEP cycle run fractally at every scope — from BrainDrive down to a single procedure.

---

## Appendix A — Cross-reference to earlier sections

| Earlier § | Draft 3 § | Note |
|---|---|---|
| Position | Position | Refined |
| 1. Core Architecture | 1. Core Architecture | + fractal OAPEP |
| 2. Natural-Language-First | 2 | Unchanged |
| 3. Vocabulary | 3 | App = folder; AGENT.md/README.md added |
| 4. Layer Model | 4 | App row = folder; overlay rows added |
| 5. Orient | 5 | Updated routing example; overlay read order added |
| 6. Align | 6 | + run-interview.md |
| 7. Plan | 7 | + run-planning.md |
| 8. Execute | 8 | App = folder; state vs methodology; overlays as customization path |
| 9. Active and Reference | 10 | Light touch |
| 10. Progressive Disclosure | 11 | Overlay rule added |
| 11. App File Shape | 12 (App Folder Shape) | Major rewrite; overlay files added |
| — | 15 (Managed Base And User Overlays) | **NEW in Draft 3** |
| 12. Naming Rules | 16 | + AGENT.md/README.md and `-user` overlays |
| 13. Index Rules | 17 (Folder Orient Files) | Reframed; overlay read order added |
| 14. Cross-Project Scope | 18 | + `base/AGENT-user.md` |
| 15. Profile Rules | 19 | Unchanged |
| 16. Composition | 20 | App-folder paths; app overlay read added |
| 17. Propagate | 21 | + Run 2 observation |
| 18. Finance Direction | 23 | Updated to PR #127 shape; overlay examples added |
| 19. Fitness And Health | 24 | Unchanged |
| 20. Owner Customization | 25 | Reworked around `*-user.md` overlays |
| 21. Harness Direction | 26 | Unchanged |
| 22. Placement Workflow | 27 | Updated for folders and ownership |
| 23. Review Tests | 28 | + lint and overlay checks |
| 24. Anti-Patterns | 29 | + overlay anti-patterns |
| 25. Current Decisions | 30 | Two Draft 1 items resolved; Draft 3 overlay decisions added |
| 26. One-Sentence Source Of Truth | 31 | Refined |
| — | 9 (Preservation Rule) | **NEW** |
| — | 13 (Common Procedure-File Shape) | **NEW** |
| — | 14 (Common Artifact-File Shape) | **NEW** |
| — | 22 (Reports Lifecycle) | **NEW** |

## Appendix B — Evidence And Rationale

| Claim | Evidence / rationale |
|---|---|
| Apps as folders survive byte-preservation under weak models | `test-run-2026-05-24-run2-claude.md` — Run 2, Gemini 3.5 Flash, `budget.md` SHA-256 byte-identical before/after comparison |
| Single-file apps fail under weak models (F-002) | `architecture-migration-testing-plan.md` background; pre-migration failure under Gemini 2.5 Flash |
| Preservation Rule wording matters | Run 1 with loose wording → sections deleted; Run 2 with structured wording → all sections preserved |
| Archive timing rule prevents mid-month archives | Run 1 wrote `monthly-2026-05.md` mid-month (bug F-S8a); Run 2 with explicit anti-pattern callout did not |
| Orient-first holds with AGENT.md at app level | Run 2 tool trace shows `budget/AGENT.md` read before any write to `budget/budget.md` |
| Natural pacing produces healthier behavior | Run 2 (10 turns, agent asked owner before writing budget) vs. Run 1 (1 turn, agent steamrolled) |
| User overlays simplify starter-pack updates | Design rationale from the current update system: managed base files can be updated deterministically while `*-user.md` overlays are preserved, reducing reliance on LLM merge for ordinary customization |