# Spec: BrainDrive Memory Update Clean Slate Cleanup

## Overview

### What We're Building

This spec defines the cleanup needed to remove the current BrainDrive starter-pack memory update system from the product runtime, client surface, tests, prompts, instructions, and API contract so the team can rebuild memory update behavior from a clean slate later.

The current system is documented in `Memory-Starter-Pack-Update-Spec.md` in this same folder. That document describes the existing updater. This spec supersedes it only for the cleanup/removal effort.

### Why It Matters

The existing updater can automatically inspect and write owner memory on startup, optionally use an LLM to merge starter-pack changes, expose manual update endpoints, write update state/report/backup artifacts, run a Draft 3 transition, and display update notices in the web client. The team has decided not to keep iterating on that shape as the foundation for future memory update behavior.

The immediate need is to make the product honest and inert with respect to automatic memory updates: no startup memory reconciliation, no hidden updater prompt, no manual update endpoints that imply supported behavior, and no client notice for a subsystem being removed.

### Target Audience And Stakeholders

| Audience | Role / Need |
|---|---|
| BrainDrive owners | Existing owners must not have memory changed by removed or half-disabled update code. |
| Builder / implementation owner | Needs a clear removal contract that prevents accidental partial cleanup. |
| QA / harness audience | Needs proof that no runtime path still plans, applies, reports, or displays memory updates. |
| Operator / maintainer | Needs stale artifacts and future replacement work separated from the cleanup. |

### Success Definition

When this work is complete:

1. BrainDrive no longer runs starter-pack memory updates automatically during gateway startup.
2. BrainDrive no longer exposes the current `/updates/memory/*` planning/apply/report API surface.
3. The web client no longer requests memory update status or displays memory update report notices.
4. The current LLM memory update planning prompt and deterministic apply path are removed from runtime code.
5. Existing owner memory files and existing `system/updates/*` artifacts are left untouched by the cleanup.
6. Focused tests prove the old runtime, API, and client update paths are absent.

The work is not successful if:

1. Any gateway startup path can still write owner memory as a starter-pack update.
2. Any model call can still be made for memory update planning.
3. The client still calls memory update status/report endpoints.
4. Cleanup deletes, rewrites, or migrates existing owner memory artifacts without an explicit separate migration spec.
5. Broken imports, stale contract docs, or stale tests leave a plausible but non-working updater surface.

### Definition Of Done (V1)

V1 is done when the current memory update system is removed from active product behavior and all remaining references are either deleted or explicitly documented as historical/current-state reference material.

Explicitly not required for V1:

- Designing the replacement memory update architecture.
- Migrating existing `system/updates/*` artifacts.
- Rewriting starter-pack layout, page templates, or owner memory architecture.
- Adding an owner-facing manual update review UI.
- Building any new update, patch, migration, or release-note flow.

## Product Behavior

### User / System Experience

After cleanup, BrainDrive starts normally without checking the starter pack against owner memory and without attempting memory migrations. Existing owners do not see memory update notices in the shell. API clients no longer have a supported memory update API to call.

If stale `system/updates` files exist in an owner's memory from previous versions, BrainDrive leaves them in place and ignores them. They are historical artifacts, not active state.

### Primary Flows

1. **Gateway startup**
   - Trigger: BrainDrive gateway starts.
   - System behavior: loads runtime config, auth, memory, model, and prompt behavior without invoking the starter-pack memory updater or Draft 3 transition.
   - Outcome: no owner memory file is written by a memory update subsystem during startup.

2. **Web app load**
   - Trigger: authenticated owner opens the web client.
   - System behavior: AppShell renders without requesting memory update status or report content.
   - Outcome: no update notice appears and no dismissed-update localStorage key is read or written.

3. **Former memory update API request**
   - Trigger: a caller requests a removed `/updates/memory/*` path.
   - System behavior: the request is not served by memory update handlers.
   - Outcome: the API returns the normal missing-route behavior, unless the build plan chooses a temporary compatibility response.

4. **Existing update artifacts**
   - Trigger: owner memory contains `system/updates/memory-state.json`, migration logs, plans, reports, manifests, or backups from the removed updater.
   - System behavior: BrainDrive does not read them for startup update decisions and does not delete them.
   - Outcome: owner data remains stable and the old subsystem cannot resume from stale state.

### Secondary Flows

- If deployment configuration still sets `PAA_MEMORY_AUTO_UPDATE_ENABLED`, the variable has no active effect after cleanup and should be removed from documented configuration.
- If tests or code still import memory update functions, the build should fail until the stale dependency is removed.
- If a future replacement updater is introduced, it must be specified separately and must not reuse old state, endpoints, or prompts by accident.

### UX / Trust Bar

- Owners should experience silence rather than confusing "up to date" notices for removed functionality.
- Builders should see no active code path that can mutate owner memory under the old update model.
- Historical artifacts should not be treated as current product truth.

## User Stories

### US-1: Startup Does Not Mutate Owner Memory - Confirmed

As a BrainDrive owner, I want startup to avoid automatic starter-pack memory reconciliation so that existing memory is not changed by the removed updater.

Acceptance criteria:

```gherkin
Given an existing owner memory root contains files that differ from the starter pack
When the gateway starts
Then no starter-pack memory update plan is generated
And no starter-pack memory update apply path runs
And no owner memory file is created, merged, replaced, archived, or deleted by the old updater
```

### US-2: LLM Memory Update Planning Is Removed - Confirmed

As a maintainer, I want the current memory update planning prompt removed from runtime so that model behavior cannot silently decide memory edits under an obsolete design.

Acceptance criteria:

```gherkin
Given BrainDrive is running
When startup and normal authenticated API flows execute
Then no model call is made with trigger "memory_update_plan"
And no prompt instructs a model to merge starter-pack improvements into owner memory
```

### US-3: Manual Update API Surface Is Gone - Confirmed

As an API maintainer, I want the current `/updates/memory/*` routes removed so that clients cannot call stale plan/apply/report behavior.

Acceptance criteria:

```gherkin
Given an authenticated caller has administration and memory access
When the caller requests the old memory update status, plan, apply, or report endpoints
Then the gateway does not execute old memory update code
And the endpoints are absent from the supported API contract
```

### US-4: Client Notice Is Removed - Confirmed

As a BrainDrive owner, I do not want the web shell to display memory update completion notices for a removed subsystem.

Acceptance criteria:

```gherkin
Given the web client loads
When AppShell mounts
Then it does not call getMemoryUpdateStatus
And it does not call getMemoryUpdateReport
And it does not render a memory update notice
And it does not write braindrive.memoryUpdateReportSeen localStorage keys
```

### US-5: Existing Artifacts Are Preserved But Inactive - Confirmed

As a maintainer, I want stale updater artifacts preserved but ignored so cleanup does not become a risky owner-memory migration.

Acceptance criteria:

```gherkin
Given owner memory contains existing system/updates plans, reports, backups, manifests, or migration logs
When the cleanup version runs
Then those files remain unchanged
And BrainDrive does not use them to decide startup memory changes
```

### US-6: Replacement Design Starts Separately - Confirmed

As a builder, I want cleanup separated from replacement design so that the old implementation does not constrain the next architecture.

Acceptance criteria:

```gherkin
Given this cleanup is complete
When the team begins a new memory update design
Then the new work has its own spec, test plan, and build plan
And it does not depend on old updater state or routes unless explicitly approved
```

## Requirements

### Functional Requirements

- Remove gateway startup invocation of `runAutomaticMemoryUpdate`.
- Remove startup creation of a memory update model adapter.
- Remove the `PAA_MEMORY_AUTO_UPDATE_ENABLED` runtime behavior from active gateway startup logic.
- Remove gateway route handlers for:
  - `GET /updates/memory/status`
  - `POST /updates/memory/plan`
  - `POST /updates/memory/apply`
  - `GET /updates/memory/reports/:migrationId`
- Remove migration-gate exceptions that exist only to allow `/updates/memory` during migrations.
- Remove client API functions and types that only support memory update status/report calls.
- Remove AppShell state, effects, localStorage handling, copy, and tests for memory update report notices.
- Remove or rewrite integration tests that assert the old endpoints exist.
- Remove unit tests that assert old update planning/apply behavior.
- Update API contract documentation and changelog/release notes so the removed surface is not advertised.
- Leave existing owner memory files and existing updater artifacts untouched.

### AI / Model / Tool Behavior

- The current memory update LLM planning prompt must not exist in active runtime code.
- No model adapter should be constructed solely for memory update planning.
- No model metadata trigger such as `memory_update_plan` should be emitted.
- No deterministic fallback planner should remain as a callable runtime path for starter-pack memory updates.
- Future AI-assisted memory update behavior must be specified separately before implementation.

### Data, Memory, And Artifact Contracts

| Data / Artifact | Current Source | Cleanup Rule | Recommendation |
|---|---|---|---|
| `system/updates/memory-state.json` | Old updater | Do not read for startup update decisions; do not delete in V1. | Preserve as historical artifact. |
| `system/updates/memory-migrations.json` | Old updater | Do not append or modify. | Preserve as historical audit trail. |
| `system/updates/starter-pack-manifest.json` | Old updater | Do not regenerate. | Leave stale copy untouched. |
| `system/updates/plans/*.json` | Old updater | Do not read/apply/delete. | Preserve until separate artifact-retention decision. |
| `system/updates/reports/*.md` | Old updater | Do not serve through removed API. | Preserve as owner-readable historical reports. |
| `system/updates/backups/*.tar.gz` | Old updater | Do not delete. | Preserve because they may be recovery artifacts. |
| Starter-pack source files | App package | Do not use for automatic reconciliation in V1 cleanup. | Keep starter pack for new-memory initialization only. |

### Interface / UX Requirements

- Remove the memory update notice from `AppShell`.
- Remove user-facing copy that says memory instructions were updated by this subsystem.
- Do not replace the notice with a new update UI in V1.
- Do not introduce a warning banner unless a separate product decision requires owner-facing migration communication.

### Observability / Evidence Requirements

- Tests or code search evidence must show no active references to the old route handlers or client calls.
- Startup-focused test coverage must prove the old update function is not invoked.
- Gateway route tests must be updated to prove the old endpoints are absent or no longer part of the supported contract.
- Client tests must prove AppShell does not call memory update APIs.
- Build/typecheck must catch stale exported types or imports.

## Scope

### Work Type

- [x] Internal system/process
- [x] Documentation/specification
- [x] BrainDrive core/foundation
- [x] Interface / shell
- [ ] New owner-facing feature
- [ ] Replacement updater architecture

### Implementation Location / Ownership

| Area | Cleanup Surface |
|---|---|
| `builds/typescript/memory/update-prompting.ts` | Remove active updater implementation and prompt. |
| `builds/typescript/memory/alpha-draft3-transition.ts` | Remove from startup update flow; delete if no longer independently used. |
| `builds/typescript/memory/brain-drive-layout.ts` | Remove if only supporting updater/tests; retain only if separately adopted by lint or architecture checks. |
| `builds/typescript/gateway/server.ts` | Remove imports, startup call, route handlers, adapter helper, and update-specific migration gate exception. |
| `builds/typescript/client_web/src/api/*` | Remove update status/report API functions and types. |
| `builds/typescript/client_web/src/components/layout/AppShell.tsx` | Remove notice state/effect/rendering/dismissal behavior. |
| Tests | Remove or replace updater-specific unit/integration/client tests. |
| Docs/contracts | Remove advertised API/client contract for old memory updates. |

### Included

- Removal of automatic startup memory update execution.
- Removal of old LLM memory update prompt and planning path.
- Removal of deterministic starter-pack reconciliation path.
- Removal of old memory update API endpoints.
- Removal of web-client memory update notice behavior.
- Removal or rewrite of tests that assume the old system exists.
- Documentation cleanup for API contract and developer/runtime configuration.
- Verification that owner memory is not modified by cleanup behavior.

### Explicitly Excluded

- Designing or building the next memory update system.
- Migrating, deleting, compacting, or hiding existing `system/updates/*` owner artifacts.
- Changing starter-pack content for new users except where stale updater instructions must be removed.
- Changing memory backup/restore semantics.
- Changing provider/model settings.
- Changing owner profile, todo, project spec, plan, journal, source, report, or archive write-placement rules.
- Reintroducing Finance Budgetting transition logic under another automatic startup path.

### Future Versions / Deepenings

- A new memory update architecture with explicit owner control and a separate spec.
- A one-time artifact retention/migration policy for old `system/updates/*` files.
- A safer release-notes or starter-pack-diff experience that informs owners without writing memory automatically.
- A manual, owner-approved repair/migration tool for known legacy memory layouts.

## Invariants And Edge Cases

### Properties That Must Always Hold

- Cleanup must not modify owner memory content.
- Cleanup must not delete owner backups or historical update reports.
- No startup path may plan or apply starter-pack memory changes under the old subsystem.
- No removed endpoint may execute old update logic.
- No client surface may imply that memory updates were applied after the cleanup.
- New-user memory initialization must continue to work from the starter pack.
- Memory backup/export/import/history behavior outside the old updater must remain unchanged.

### Edge Cases To Test

- Existing owner memory differs from starter pack at `AGENT.md`.
- Existing owner memory contains old pending update state.
- Existing owner memory contains old reports and backups.
- `PAA_MEMORY_AUTO_UPDATE_ENABLED=true` is set in the environment.
- `PAA_MEMORY_AUTO_UPDATE_ENABLED=false` is set in the environment.
- Authenticated caller requests old update endpoints.
- AppShell loads with old `braindrive.memoryUpdateReportSeen.*` localStorage keys present.
- Full test build catches no stale imports from removed updater files.

### Failure Modes

| Scenario | Expected Behavior |
|---|---|
| Stale update state exists | Ignored by runtime; no writes occur. |
| Old endpoint is requested | Normal missing-route or explicitly chosen compatibility response; no update code executes. |
| Environment variable still configured | No memory update behavior occurs; docs should stop recommending the variable. |
| Stale client localStorage keys exist | Ignored; no notice renders. |
| New code accidentally imports removed updater | Typecheck/test failure before handoff. |

## Technical Context

### Current Implementation Surfaces To Remove Or Reconcile

The previous spec identified these active surfaces:

- `builds/typescript/memory/update-prompting.ts`
- `builds/typescript/memory/alpha-draft3-transition.ts`
- `builds/typescript/memory/brain-drive-layout.ts`
- `builds/typescript/gateway/server.ts`
- `builds/typescript/client_web/src/api/gateway-adapter.ts`
- `builds/typescript/client_web/src/api/types.ts`
- `builds/typescript/client_web/src/components/layout/AppShell.tsx`
- `builds/typescript/memory/update-prompting.test.ts`
- `builds/typescript/memory/alpha-draft3-transition.test.ts`
- `builds/typescript/memory/brain-drive-layout.test.ts`
- `builds/typescript/memory/starter-pack-draft3-layout.test.ts`
- `builds/typescript/gateway/auth-routes.integration.test.ts`
- `builds/typescript/client_web/src/components/layout/AppShell.test.tsx`
- `builds/typescript/client_web/src/api/CONTRACT.md`

The build plan must verify actual current imports before deletion. If any file has been repurposed outside memory updates, remove only the updater coupling and keep the independently useful code.

### Hard Constraints

- Do not put BrainDrive-owned provider keys in client config.
- Do not introduce a new model call path as part of cleanup.
- Do not change owner memory files as a cleanup side effect.
- Do not remove starter-pack files required for new-user initialization unless a separate starter-pack spec approves it.
- Do not silently preserve dead API documentation that tells clients to call removed endpoints.

## Test Strategy

### Focused Verification

Recommended focused commands after implementation:

```bash
cd builds/typescript
npm run test -- gateway/auth-routes.integration.test.ts
npm run web:test -- AppShell
npm run web:typecheck
```

Recommended code-search checks:

```bash
rg -n "runAutomaticMemoryUpdate|generateMemoryUpdatePlan|applyMemoryUpdatePlan|readMemoryUpdateReport|getMemoryUpdateStatus|memory_update_plan|/updates/memory|Memory instructions were updated|braindrive.memoryUpdateReportSeen" builds/typescript
```

Expected result: no active runtime/client references remain. Historical docs may remain only where clearly marked historical and outside active API/runtime instructions.

### Broader Verification

Before handoff:

```bash
cd builds/typescript
npm run test
npm run build
npm run web:typecheck
npm run web:test
```

### Acceptance Evidence

- Diff showing removed gateway startup update call and removed update routes.
- Diff showing removed AppShell update notice and removed client API calls/types.
- Diff showing deleted or rewritten updater tests.
- Passing focused and broad checks, or exact blocker if dependencies/tooling prevent them.
- Code-search output confirming no active old updater references.

## Security, Privacy, And Trust Considerations

Risk level: high, because this cleanup touches a subsystem that previously had permission to read and write owner memory.

Trust requirements:

- Cleanup must reduce write authority, not move it to a less visible path.
- Existing owner backups and reports must be preserved.
- Stale update state must not be used as an input to new behavior.
- Removed endpoints must not expose stale reports or migration metadata through a forgotten route.
- Prompt removal must be verified so no model can receive owner memory plus starter-pack target content under the old plan schema.

## Explicit Boundaries

### Do Not Modify Automatically

- `me/profile.md`
- `me/todo.md`
- Project `spec.md`
- Project `plan.md`
- Project journals
- Owner overlays such as `AGENT-user.md`
- Owner source files
- Generated reports
- Durable archives
- Preferences
- Provider secrets or credentials
- Existing `system/updates/*` artifacts

### Do Not Rebuild In This Cleanup

- Starter-pack manifest generation.
- LLM-assisted merge planning.
- Deterministic fallback update planning.
- Memory update report display.
- Manual plan/apply UI.
- Draft 3 or Finance Budgetting automatic transition.
- Three-way merge against previous starter-pack versions.

## Open Questions And Recommendations

| Open Item | Recommendation |
|---|---|
| Should old `/updates/memory/*` endpoints return 404 or a deliberate 410 response? | Prefer normal missing-route behavior for the cleanest removal unless external clients depend on a clearer 410. If 410 is chosen, implement a tiny compatibility handler that does not import or execute updater code and remove it in a later release. |
| Should `system/updates/*` artifacts be deleted from owner memory? | No for V1. Preserve them. Deletion or archival cleanup should be a separate owner-memory artifact-retention spec because backups and reports may be useful. |
| Should `alpha-draft3-transition.ts` remain as a standalone migration utility? | Remove it from startup. Keep it only if there is a separately documented manual/admin use. Otherwise delete it with its tests to avoid implying automatic legacy migration support. |
| Should `brain-drive-layout.ts` survive cleanup? | Delete it if it is only used by the updater and updater tests. Retain or move it only if starter-pack lint or future memory architecture tests explicitly depend on it outside the update system. |
| Should `PAA_MEMORY_AUTO_UPDATE_ENABLED` remain documented? | Remove it from active docs/config guidance. If compatibility code still parses it, document it as deprecated and inert for one release only. |
| Should the web client tell owners that memory auto-updates were removed? | Not in V1 unless there is evidence owners need that message. A silent removal is less confusing than a banner about internal cleanup. |
| Should the old current-state spec be edited? | No. Keep `Memory-Starter-Pack-Update-Spec.md` as historical/current-state reference. This new cleanup spec should be the build source for removal. |
| What should replace memory updates later? | Create a separate spec. Recommended direction: owner-approved, inspectable update proposals with no startup auto-apply, explicit artifact provenance, and no model-generated writes without review. |

## Changelog

| Date | Change | Reason | Source |
|---|---|---|---|
| 2026-07-01 | Initial clean-slate cleanup spec created. | Team decided to remove current memory update behavior before designing a replacement. | User request and current repo inspection. |

## Conversation References

| Date | Source | Topics Discussed |
|---|---|---|
| 2026-07-01 | User request in Codex | Create a new spec beside the prior BrainDrive Update spec for cleaning up memory update code, instructions, prompts, scope, goals, user stories, open items, and recommendations. |
| 2026-07-01 | Repo inspection | Current updater surfaces in memory, gateway, client API, AppShell, and tests. |
| 2026-06-29 | `Memory-Starter-Pack-Update-Spec.md` | Historical/current-state behavior of the existing starter-pack memory update system. |

## Approval

- [ ] Reviewed by: _______________
- [ ] Date: _______________
- [ ] Accepted as cleanup spec: [ ]