# BrainDrive Memory Architecture — Draft 2 Proposal

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

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

## Changes from Draft 1

Draft 2 carries forward Dave J's spine — five-stage workflow, five Execute primitives, profile rules, anti-patterns, the natural-language-first principle, and the layer model — all of which survived intact and are quoted from Draft 1 where unchanged. The substantive changes are:

1. **Apps are folders, not single files.** §11 in Draft 1 modeled apps as one file with `## Instructions` over `## Current Budget`. Empirical testing under Gemini 2.5 Flash (bug F-002, captured in `architecture-migration-testing-plan.md`) showed weak models conflate "edit the instructions section" with "rewrite the whole file" and overwrite owner content. The Finance migration in BrainDrive PR #127 splits state from methodology into a folder. Validated twice under Gemini 3.5 Flash: `budget.md` SHA-256 byte-identical before/after a saved-budget comparison.
2. **Orient files at every active scope are `AGENT.md`. Reference folders use `README.md`.** Active scopes that *do* things get the verb-shaped name (`AGENT.md`). Reference collections that *are* things — `statements/`, `reports/` — get the noun-shaped name (`README.md`). This retires `index.md` inside app folders. Standalone `index.md` files still have a role for navigation-only listings where there is no active scope to orient.
3. **Preservation Rule is a named, mandatory section** of every procedure file (new §9). It carries the byte-preservation guarantee for state artifacts and the "use today's date" guidance. Validated to hold under Gemini 3.5 Flash in the Run 2 test report.
4. **Common Procedure-File Shape and Common Artifact-File Shape** (new §13 and §14). Canonical structure for the two file types so weak models have a predictable form to follow.
5. **Reports Lifecycle** (new §21). `latest.md` is the working cache, overwritten every run; `monthly-YYYY-MM.md` is the durable archive, written only when the reporting period is complete. The "do not archive an open month" rule was added after Run 1 archived a mid-month report.
6. **Fractal OAPEP** is named in §1 as the operating principle: Orient → Align → Plan → Execute → Propagate recurs at every scope — BrainDrive, project, app, and procedure. Draft 1 hinted at this in §5 ("Orient can reappear locally"); Draft 2 makes it central.
7. **Two of Draft 1's "Still open" items are resolved** by the work behind Draft 2: the exact migration path is in PR #127, and the threshold for "when a one-file app becomes an app folder" is no longer a threshold — every app is a folder, uniformly.

Sections that did not change materially from Draft 1 are preserved verbatim and credited to Dave J. Section numbers are not stable across drafts because of the inserts; a cross-reference table is in §30.

---

## 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, 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`, 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`), a state artifact named for the folder (`budget/budget.md`), supporting rules artifacts, 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 set, or composition logic. Lives in procedure files or rules artifacts. |
| Procedure file | A file describing *how* a workflow runs (e.g., `create.md`, `compare.md`, `run-interview.md`). Carries a Preservation Rule. |
| Rules artifact | A file capturing owner-approved rules an app accumulates over time (e.g., `budget-rules.md`). |
| AGENT.md | Orient file for an active scope — a place that *does* things. Project, app. |
| 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`. |
| Reference folder | A collection that is consumed — sources, reports. Has a `README.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 |
| `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 `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) + state artifact + rules + procedures |
| Procedure file | Execute support | Narrow procedure for one workflow, with Preservation Rule |
| 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.
- Finance `AGENT.md` says Budget exists and routes to `budget/`.
- `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`.
- 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). 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` + state artifact + rules + procedures | `budget/`, `todo/` (future), `journal/` (future), `investments/` (future) |
| Instructions | AI-facing procedures and rules | Procedure files (verb-named) and rules artifacts (`*-rules.md`) | `create.md`, `compare.md`, `budget-rules.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.

## 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`.
- `spec.md`, `plan.md`.
- App `AGENT.md` and procedure files (`create.md`, `compare.md`, `run-interview.md`, `run-planning.md`).
- 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 artifacts (`budget-rules.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, 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.

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.

## 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         ← orient + Preservation Rule + procedure map
├── budget.md        ← state artifact (owner data; same name as folder)
├── budget-rules.md  ← rules artifact (owner-approved rules accumulate here)
├── create.md        ← procedure: create or revise the saved budget
└── compare.md       ← procedure: compare statements against the saved budget
```

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.

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`) and the procedures (`create.md`, `compare.md`) as separate files and modify either independently. The agent's instructions are in plain English, in a file 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 (§19) 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. 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 | `<topic>-rules.md` | `budget-rules.md`, `source-rules.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`.
- `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."

## 16. Folder Orient Files

Replaces Draft 1 §13 "Index Rules."

Folders fall into two roles:

| Role | Orient file | Examples |
|---|---|---|
| Active scope (does things) | `AGENT.md` | `documents/finance/`, `documents/finance/budget/` |
| Reference folder (is consumed) | `README.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).
- 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.
- 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` |
| Monthly comparison | Owner asks how they're doing vs. the saved budget | `compare.md` |
| 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.

## 17. 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).
- `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.

## 18. 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.

## 19. 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/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.

## 20. 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?

## 21. 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.

## 22. 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                ← project orient
├── spec.md                 ← Align stage (state artifact)
├── run-interview.md        ← procedure for filling spec.md
├── plan.md                 ← Plan stage (state artifact)
├── run-planning.md         ← procedure for filling plan.md
├── budget/                 ← Budget app folder
│   ├── AGENT.md            ← app orient + Preservation Rule
│   ├── budget.md           ← state artifact
│   ├── budget-rules.md     ← rules artifact
│   ├── create.md           ← workflow A
│   └── compare.md          ← 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.

## 23. 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`).

## 24. Owner Customization

*(Unchanged from Draft 1, with one clarification.)*

Owner-authored memory is owner data.

- Default templates define the supported path.
- Owners can edit natural-language app and instruction files.
- Do not silently overwrite owner-authored specs, plans, apps, instructions, or reports.
- Starter-pack updates must merge carefully, request approval, or defer.
- Heavy customization may move a file outside default guarantees, but owner changes should still be preserved unless the owner approves reset/merge.

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

## 25. 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.

## 26. 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, procedures, state artifacts, rules); reference files are consumed (sources, reports, READMEs).
3. **Classify the file.** Orient (AGENT.md / README.md), `spec.md`, `plan.md`, state artifact, procedure, rules, 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 + state artifact + procedures from day one.
5. **Place instructions at the lowest useful level.** Do not move narrow rules upward for convenience.
6. **If active and updateable, write a Preservation Rule.** Every procedure that touches a state artifact carries one.
7. **Check for bloat.** If a procedure file is becoming hard to understand, split into narrower procedure files.
8. **Check propagation impact.** Decide what should update after the work runs.

## 27. 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 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, no stale paths, no `memory_edit` leakage.

## 28. 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.** §21.
- **(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.

## 29. Current Decisions

Locked for Draft 2:

- 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.**

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.
- How starter-pack updates merge into owner-customized memory.
- 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?

## 30. 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), 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 Draft 1 sections

| Draft 1 § | Draft 2 § | 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 |
| 5. Orient | 5 | Updated routing example |
| 6. Align | 6 | + run-interview.md |
| 7. Plan | 7 | + run-planning.md |
| 8. Execute | 8 | App = folder; state vs methodology |
| 9. Active and Reference | 10 | Light touch |
| 10. Progressive Disclosure | 11 | Unchanged |
| 11. App File Shape | 12 (App Folder Shape) | Major rewrite |
| 12. Naming Rules | 15 | + AGENT.md/README.md |
| 13. Index Rules | 16 (Folder Orient Files) | Reframed |
| 14. Cross-Project Scope | 17 | Unchanged |
| 15. Profile Rules | 18 | Unchanged |
| 16. Composition | 19 | App-folder paths |
| 17. Propagate | 20 | + Run 2 observation |
| 18. Finance Direction | 22 | Updated to PR #127 shape |
| 19. Fitness And Health | 23 | Unchanged |
| 20. Owner Customization | 24 | Clarified linkage to §9 |
| 21. Harness Direction | 25 | Unchanged |
| 22. Placement Workflow | 26 | Updated for folders |
| 23. Review Tests | 27 | + lint check |
| 24. Anti-Patterns | 28 | + four new anti-patterns |
| 25. Current Decisions | 29 | Two items resolved |
| 26. One-Sentence Source Of Truth | 30 | Refined |
| — | 9 (Preservation Rule) | **NEW** |
| — | 13 (Common Procedure-File Shape) | **NEW** |
| — | 14 (Common Artifact-File Shape) | **NEW** |
| — | 21 (Reports Lifecycle) | **NEW** |

## Appendix B — Test evidence behind Draft 2 changes

| Draft 2 claim | Evidence |
|---|---|
| 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) |