# Build Plan: Your Agent Identity Cleanup

**Status:** Not Started  
**Created:** 2026-07-01  
**Updated:** 2026-07-01  
**Repository:** `/home/hex/Project/BrainDrive-Test-01`  
**Branch target:** `dev`  
**Spec:** `dave-j-your-agent-identity-cleanup-spec.md`  
**Test Plan:** Not created as a separate artifact. This plan includes inline release gates and verification scenarios.

---

## Overview

This build plan implements the Your Agent identity cleanup described in the spec. The plan makes `your-agent` the canonical persisted root-agent id and folder for new installs and active memory, while preserving `braindrive-plus-one` as a legacy compatibility alias for existing memory, historical links, and migration tests.

The work is data-sensitive because `braindrive-plus-one` is currently used as a project id, folder path, selection target, protected-project id, template alias, and test fixture. Implementation must proceed as a staged migration with tests first, not as a global string replacement.

---

## Source Inputs

| Input | Location | Status | Notes |
|---|---|---|---|
| Spec | `/home/hex/Reference/Designs/BrainDrive-MVP/BrainDrive - Your Agent/dave-j-your-agent-identity-cleanup-spec.md` | Draft but accepted for planning by user request | Defines scope, user stories, invariants, and recommendations. |
| Prior rename brief | `/home/hex/Reference/Designs/BrainDrive-MVP/BrainDrive - Your Agent/dave-j-your-agent-rename-brief.md` | Reviewed | Explains original display-name bug and why `braindrive-plus-one` was preserved in the prior scope. |
| Prior implementation plan | `/home/hex/Reference/Designs/BrainDrive-MVP/BrainDrive - Your Agent/dave-j-your-agent-rename-implementation-plan.md` | Reviewed | PR #203 renamed display/model-facing text to Your Agent and left internal id cleanup open. |
| Prior work log | `/home/hex/Reference/Designs/BrainDrive-MVP/BrainDrive - Your Agent/dave-j-your-agent-rename-work-log.md` | Reviewed | Documents completed display rename, verification, and known full-test blocker. |
| Current repo scan | `/home/hex/Project/BrainDrive-Test-01` on `dev` | Reviewed | Tracked `braindrive-plus-one` references are concentrated in gateway, memory, client project selection, starter seeds, lint, and tests. |
| Formal test plan | Not present | Missing by design for this request | Inline gates below should be promoted to a separate test plan later if this becomes release-critical. |

---

## Scope Guardrails

### In Scope

- Make `your-agent` the canonical root-agent project id and canonical active memory folder.
- Keep display name as `Your Agent` everywhere owner-facing or model-fed.
- Centralize root-agent identity constants and helper functions.
- Migrate or repair memory layouts containing:
  - only `braindrive-plus-one`
  - only `your-agent`
  - both ids/folders
  - missing folder or missing manifest entries
- Preserve conversation ids, default skill ids, owner-authored files, and project protection.
- Update gateway, memory init, starter seeds, update prompting, client selection, sidebar, collapsed sidebar, empty state, and focused tests.
- Add retired-name and legacy-literal verification with an allowlist.
- Keep historical `CHANGELOG.md` and `your-memory.*` backups untouched.

### Out Of Scope

- Provider/model configuration cleanup.
- Auth, billing, deployment, installer, Docker, or Tauri packaging changes unless a touched test reveals a direct identity regression.
- Broad UI redesign.
- Editing historical changelog entries.
- Rewriting ignored backup/snapshot directories.
- Removing legacy alias support in this same V1 cleanup.
- Deleting owner-authored duplicate root-agent files without archive or manual-review behavior.

### Change Control

If implementation reveals that `your-agent` cannot safely become canonical without broader routing, memory-tool, or conversation-history changes, stop and update the spec before continuing. The fallback is to centralize `braindrive-plus-one` as a compatibility id while leaving the persisted id unchanged.

---

## Key Decisions

| Decision | Choice | Rationale |
|---|---|---|
| Canonical display name | `Your Agent` | Already accepted and implemented by prior rename work. |
| Canonical persisted id for new installs | `your-agent` | Aligns internal id with product name and reduces long-term confusion. |
| Legacy id | `braindrive-plus-one` remains supported as a compatibility alias | Existing owner memory, tests, conversations, and paths may reference it. |
| Migration behavior | Safe repair during memory initialization / project manifest repair | Existing app already has memory init/repair patterns; identity cleanup belongs there rather than in client-only code. |
| Root assistant as page/template | Keep it special and protected, not a normal page template | Starter `your-agent/AGENT.md` says Your Agent does not maintain its own spec/plan/interview/planning procedure. |
| Duplicate folders | Preserve both unless an automated merge is provably safe | Prevents loss of owner-authored memory. |
| Historical records | Do not rewrite | Changelogs, old backups, and conversation snapshots are historical evidence. |
| Test strategy | Tests first in each phase | Migration mistakes can silently lose owner data or break startup. |
| Formal test plan | Not blocking for this requested plan | Inline gates are included. A separate test plan can be created before implementation if desired. |

---

## Current State & Remediation

| Current Behavior / Gap | Required Target | Source | Build Task |
|---|---|---|---|
| `builds/typescript/gateway/projects.ts` uses `ROOT_AGENT_PROJECT_ID = "braindrive-plus-one"` | Gateway root project uses canonical `your-agent`, with legacy repair/alias support | Spec US-3, US-4 | Phase 2 |
| `builds/typescript/memory/init.ts` protects and seeds `braindrive-plus-one` | Memory init seeds `your-agent` and migrates legacy layouts safely | Spec US-2, US-3 | Phase 2 |
| `PROJECT_TEMPLATE_ALIASES` maps `braindrive-plus-one` to `your-agent` | Alias support remains but moves behind central identity helper | Spec US-4 | Phase 1, Phase 2 |
| `builds/typescript/memory/starter-pack/projects/projects.seed.json` seeds `braindrive-plus-one` | Starter seed uses `your-agent` | Spec US-3 | Phase 2 |
| Client layout/hooks hard-code `braindrive-plus-one` | Client uses identity helper/constants and selects canonical id | Spec US-1, US-4 | Phase 3 |
| `EmptyState.tsx` uses `braindrive-plus-one` as root intro key | Empty state uses canonical id or root identity predicate | Spec US-1 | Phase 3 |
| `update-prompting.ts` excludes `braindrive-plus-one` template folder | Exclusion is expressed as legacy/canonical root-agent template policy | Spec US-4, US-5 | Phase 2 |
| Live memory has manifest id `braindrive-plus-one` and both root-agent folders | Live dev memory should migrate safely, preserving divergent content | Spec US-2 | Phase 2, Phase 5 |
| Tests assert legacy id for normal behavior | Normal-flow tests assert `your-agent`; legacy fixtures only test migration | Spec US-5 | All phases |
| No guard against new scattered literals | Add retired-name/legacy-literal scan with allowlist | Spec US-5 | Phase 4 |

---

## Architecture

### Component Diagram

```text
Root Agent Identity Helper
  |
  +-- memory/init.ts
  |     - seeds canonical root project
  |     - repairs legacy/duplicate manifests
  |     - scaffolds canonical root-agent folder
  |
  +-- gateway/projects.ts
  |     - exposes canonical root project
  |     - protects canonical and legacy ids during migration
  |
  +-- client_web project selection
  |     - selects canonical id
  |     - recognizes legacy id only in compatibility inputs
  |
  +-- update-prompting / architecture lint
  |     - treats root assistant as special built-in surface
  |
  +-- tests and retired-name scan
        - proves normal behavior uses your-agent
        - proves legacy data migrates safely
```

### Components

#### 1. Root Agent Identity Helper

- **Purpose:** Single source of truth for root-agent display name, canonical id, legacy ids, template id, folder path, and predicates.
- **Candidate location:** `builds/typescript/memory/root-agent.ts` or `builds/typescript/root-agent.ts`.
- **Exports:**
  - `ROOT_AGENT_CANONICAL_ID = "your-agent"`
  - `ROOT_AGENT_LEGACY_IDS = ["braindrive-plus-one"]`
  - `ROOT_AGENT_DISPLAY_NAME = "Your Agent"`
  - `ROOT_AGENT_ICON = "sparkles"`
  - `ROOT_AGENT_TEMPLATE_ID = "your-agent"`
  - `isRootAgentProjectId(id: string): boolean`
  - `isLegacyRootAgentProjectId(id: string): boolean`
  - `canonicalizeRootAgentProjectId(id: string): string`
  - `rootAgentProjectSeed()`
- **Spec refs:** US-1, US-4, US-5.
- **Inline gates:** G1, G4.

#### 2. Memory Migration / Repair

- **Purpose:** Convert existing memory manifests/folders to canonical root-agent identity without data loss.
- **Primary files:**
  - `builds/typescript/memory/init.ts`
  - `builds/typescript/memory/init.test.ts`
  - `builds/typescript/memory/starter-pack/projects/projects.seed.json`
- **Responsibilities:**
  - Seed new installs with `your-agent`.
  - Detect legacy manifest id `braindrive-plus-one`.
  - Preserve conversation id and default skill ids.
  - Move or merge folder content only when safe.
  - Retain legacy path compatibility where needed.
  - Emit warnings when manual review is required.
- **Spec refs:** US-2, US-3, invariants.
- **Inline gates:** G2, G5.

#### 3. Gateway Project Service

- **Purpose:** Expose and protect the root assistant through canonical identity while repairing legacy manifests.
- **Primary files:**
  - `builds/typescript/gateway/projects.ts`
  - `builds/typescript/gateway/projects.test.ts`
- **Responsibilities:**
  - Root project default id becomes `your-agent`.
  - Rename/delete protection covers canonical id and legacy id during compatibility.
  - List/repair behavior avoids duplicate visible root projects.
  - Project files resolve canonical root-agent folder after migration.
- **Spec refs:** US-1, US-2, US-3.
- **Inline gates:** G2, G3.

#### 4. Client Project Selection And Labels

- **Purpose:** Remove scattered legacy selection literals from UI and ensure root assistant selection uses canonical identity.
- **Primary files:**
  - `builds/typescript/client_web/src/hooks/useProjects.ts`
  - `builds/typescript/client_web/src/hooks/useProjects.test.ts`
  - `builds/typescript/client_web/src/components/layout/AppShell.tsx`
  - `builds/typescript/client_web/src/components/layout/AppShell.test.tsx`
  - `builds/typescript/client_web/src/components/layout/Sidebar.tsx`
  - `builds/typescript/client_web/src/components/layout/SidebarCollapsed.tsx`
  - `builds/typescript/client_web/src/components/layout/sidebar-labels.ts`
  - `builds/typescript/client_web/src/components/chat/EmptyState.tsx`
- **Responsibilities:**
  - Select `your-agent` by default.
  - Treat legacy project ids returned from old memory as root-agent inputs only until migration normalizes them.
  - Keep visible text as `Your Agent`.
- **Spec refs:** US-1, US-4.
- **Inline gates:** G3, G4.

#### 5. Retired-Name Guard

- **Purpose:** Ensure remaining legacy references are intentional.
- **Candidate locations:**
  - Existing architecture lint in `builds/typescript/tools/architecture-lint/draft3-memory-lint.ts`.
  - A small script under `builds/typescript/tools/architecture-lint/`.
  - Or a documented `rg` verification command if no script is added in V1.
- **Responsibilities:**
  - Block `BrainDrive+1` and `BD+1` in active product surfaces.
  - Block raw `braindrive-plus-one` outside identity helper, migration code, historical docs, and compatibility tests.
  - Produce a readable allowlist.
- **Spec refs:** US-5.
- **Inline gates:** G4.

### Data Flow

1. App starts and memory initialization runs.
2. Memory init reads `documents/projects.json`.
3. Root identity repair canonicalizes root-agent manifest entries to `your-agent`.
4. Folder repair ensures canonical `documents/your-agent/` exists and preserves legacy content.
5. Gateway project service lists projects and protects root-agent ids.
6. Client hooks select canonical `your-agent`.
7. Sidebar, empty state, and model context display `Your Agent`.
8. Legacy `braindrive-plus-one` references are accepted only through alias/migration paths.

### Migration Rules

Use these rules unless implementation discovers a data-loss risk requiring spec update:

1. **Empty memory:** seed `your-agent` with display name `Your Agent`.
2. **Only canonical manifest entry exists:** leave it; ensure display name/icon are correct.
3. **Only legacy manifest entry exists:** rewrite id to `your-agent`, preserve name/icon/conversation/default skills, and migrate folder according to folder rules.
4. **Both manifest entries exist, neither has conversation/default skills:** keep one canonical `your-agent` entry and drop legacy manifest entry after folder handling.
5. **Both manifest entries exist, one has conversation/default skills:** preserve that state on the canonical entry.
6. **Both manifest entries have different conversation ids or default skills:** fail safe by keeping canonical visible entry, preserving legacy data, and emitting a warning/manual-review item. Do not silently choose one.
7. **Only legacy folder exists:** move to or copy into `documents/your-agent/` if canonical folder is absent.
8. **Both folders exist and files are byte-identical or canonical folder is generated/default only:** keep canonical folder and archive/remove duplicate according to existing repo cleanup conventions.
9. **Both folders exist and files differ:** preserve both. Do not delete. Emit warning/manual-review item.
10. **Legacy path reads after migration:** either resolve to canonical path or return a clear compatibility diagnostic. Prefer alias/redirect for one compatibility window if memory tools support it cleanly.

### Observability And Evidence Hooks

| Evidence Need | Implementation Hook | Gate |
|---|---|---|
| New-install manifest uses canonical id | Memory init test fixture and output assertion | G2 |
| Legacy manifest migrates without data loss | Memory init integration tests with before/after manifests | G2 |
| Duplicate folders are preserved on conflict | Temp memory fixture with divergent files and warning assertion | G2 |
| Client selects canonical root | Hook/component tests | G3 |
| Remaining legacy references are intentional | Retired-name scan or lint guard output | G4 |
| Live dev memory result | Manual/local file inspection after running migration | G5 |
| Runtime owner-facing behavior | Optional app run and model/chat verification | G5 |

---

## Inline Verification Gates

Because no standalone `test-plan.md` exists yet, use these gates as the test-plan substitute.

| Gate | Name | Purpose | Required Evidence |
|---|---|---|---|
| G1 | Identity Contract Gate | Root-agent constants/helper behaves correctly | Unit tests and call-site import review |
| G2 | Memory Migration Gate | New, legacy, duplicate, and conflict memory layouts are handled safely | `memory/init.test.ts` focused run and before/after manifest assertions |
| G3 | Gateway/Client Behavior Gate | Gateway and web select/show canonical Your Agent | Gateway and web focused tests |
| G4 | Retired Reference Gate | Remaining legacy references are approved only | Scan/lint output with allowlist |
| G5 | Baseline And Live-Memory Gate | Build/test baseline passes and live dev memory is sane | Build/typecheck/test output plus live file inspection |

---

## Implementation Roadmap

### Schedule Overview

| Phase | Goal | Spec Refs | Gates | Owner | Status |
|---|---|---|---|---|---|
| 0 | Preflight and current-state snapshot | All guardrails | G4 | Dave J / coding agent | Not Started |
| 1 | Centralize root-agent identity | US-4, US-5 | G1 | Dave J / coding agent | Not Started |
| 2 | Implement memory migration and gateway repair | US-2, US-3 | G2, G3 | Dave J / coding agent | Not Started |
| 3 | Update client selection and UI references | US-1, US-4 | G3 | Dave J / coding agent | Not Started |
| 4 | Add retired-reference guard and cleanup tests/docs | US-5 | G4 | Dave J / coding agent | Not Started |
| 5 | Full verification and live-memory review | All | G5 | Dave J / coding agent + human checkpoint | Not Started |

### Phase 0: Preflight And Current-State Snapshot

**Goal:** Capture the exact starting point before touching migration-sensitive files.

**Spec/Test Trace:**

| Spec Ref | Gate | Evidence Required |
|---|---|---|
| Scope guardrails, invariants | G4 | Branch/status output, tracked-reference scan, live-memory folder comparison |

**Tasks:**

| # | Task | Spec Ref | Gate | Owner | Estimate | Status |
|---|---|---|---|---|---|---|
| 0.1 | Confirm branch is `dev` and working tree is clean or identify unrelated changes | Guardrails | G5 | Coding agent | 5 min | Not Started |
| 0.2 | Run tracked-file scan for `BrainDrive+1`, `BD+1`, and `braindrive-plus-one` | US-5 | G4 | Coding agent | 10 min | Not Started |
| 0.3 | Run live-memory scan under `builds/typescript/your-memory/documents` | US-2 | G2 | Coding agent | 10 min | Not Started |
| 0.4 | Compare `documents/braindrive-plus-one/` and `documents/your-agent/` in live memory | US-2 | G2 | Coding agent | 10 min | Not Started |
| 0.5 | Record any unrelated worktree changes and do not touch them | Guardrails | G5 | Coding agent | 5 min | Not Started |

**Commands:**

```bash
git status --short --branch
git ls-files | rg -v '(^|/)node_modules/|(^|/)dist/|(^|/)coverage/|^builds/typescript/src-tauri/target/' | xargs rg -n -S 'BrainDrive\+1|BD\+1|braindrive-plus-one'
rg -n --hidden --no-ignore -S 'BrainDrive\+1|BD\+1|braindrive-plus-one|your-agent' builds/typescript/your-memory/documents
diff -qr builds/typescript/your-memory/documents/braindrive-plus-one builds/typescript/your-memory/documents/your-agent
```

**Success Criteria:**

| Criterion | Spec Ref | Gate | Verification | Expected Result | Evidence |
|---|---|---|---|---|---|
| Starting state is known | Guardrails | G5 | `git status --short --branch` | Branch and unrelated changes recorded | Command output |
| Legacy references are inventoried | US-5 | G4 | tracked-file `rg` scan | Known reference list captured | Scan output |
| Live-memory duplicate state is known | US-2 | G2 | live-memory scan and diff | Duplicate/conflict state documented | Scan/diff output |

**Exit Criteria:** Builder knows the exact starting reference set and live-memory duplicate state before editing.

### Phase 1: Centralize Root-Agent Identity

**Goal:** Introduce a single identity contract that later phases can use instead of scattered string literals.

**Spec/Test Trace:**

| Spec Ref | Gate | Evidence Required |
|---|---|---|
| US-4, US-5 | G1 | Identity helper tests and import review |

**Tasks:**

| # | Task | Spec Ref | Gate | Owner | Estimate | Status |
|---|---|---|---|---|---|---|
| 1.1 | Write unit tests for identity constants and predicates | US-4 | G1 | Coding agent | 20 min | Not Started |
| 1.2 | Write tests for canonicalizing `braindrive-plus-one` to `your-agent` | US-2, US-4 | G1 | Coding agent | 20 min | Not Started |
| 1.3 | Add root-agent identity helper/module | US-4 | G1 | Coding agent | 30 min | Not Started |
| 1.4 | Export root-agent seed/object helper to avoid repeated object literals | US-3, US-4 | G1 | Coding agent | 20 min | Not Started |
| 1.5 | Replace low-risk imports in memory/gateway tests where behavior should not change yet | US-4 | G1 | Coding agent | 30 min | Not Started |
| 1.6 | Run Phase 1 focused tests | US-4 | G1 | Coding agent | 10 min | Not Started |

**Candidate files:**

- Add one of:
  - `builds/typescript/memory/root-agent.ts`
  - `builds/typescript/root-agent.ts`
- Add test:
  - `builds/typescript/memory/root-agent.test.ts`

**Implementation notes:**

- Prefer a location importable by both gateway and memory without circular dependencies.
- If client needs the same constants, do not import server-side Node modules into Vite client code. Either duplicate minimal client-safe constants under `client_web/src` with tests, or create a package-safe shared module only if the repo already supports that pattern.
- Keep ASCII names in code comments and docs.

**Success Criteria:**

| Criterion | Spec Ref | Gate | Verification | Expected Result | Evidence |
|---|---|---|---|---|---|
| Identity helper exists | US-4 | G1 | Unit test run | Constants and predicates pass | Test output |
| Legacy canonicalization works | US-2 | G1 | Unit test run | `braindrive-plus-one` canonicalizes to `your-agent` | Test output |
| No behavior-changing migration yet | Guardrails | G1 | Focused test run | Existing relevant tests still pass or only expected pending tests fail | Test output |

**Likely command:**

```bash
cd builds/typescript && npm run test -- --run memory/root-agent.test.ts
```

**Exit Criteria:** All later code can depend on a documented identity helper instead of hard-coded root-agent strings.

### Phase 2: Memory Migration And Gateway Repair

**Goal:** Make `your-agent` the canonical active persisted id/folder while preserving existing legacy data.

**Spec/Test Trace:**

| Spec Ref | Gate | Evidence Required |
|---|---|---|
| US-2, US-3, invariants | G2, G3 | Memory/gateway tests with before/after manifests and warnings |

**Tasks:**

| # | Task | Spec Ref | Gate | Owner | Estimate | Status |
|---|---|---|---|---|---|---|
| 2.1 | Write memory init tests for empty memory seeding `your-agent` | US-3 | G2 | Coding agent | 30 min | Not Started |
| 2.2 | Write memory init tests for legacy-only manifest migration | US-2 | G2 | Coding agent | 45 min | Not Started |
| 2.3 | Write memory init tests for canonical-only manifest preservation | US-3 | G2 | Coding agent | 20 min | Not Started |
| 2.4 | Write memory init tests for duplicate manifest entries with no state | US-2 | G2 | Coding agent | 30 min | Not Started |
| 2.5 | Write memory init tests for duplicate manifest entries where one has conversation state | US-2 | G2 | Coding agent | 45 min | Not Started |
| 2.6 | Write memory init tests for duplicate manifest entries where both have conflicting state | US-2 | G2 | Coding agent | 45 min | Not Started |
| 2.7 | Write folder migration tests: legacy only, canonical only, identical folders, divergent folders | US-2 | G2 | Coding agent | 1 hr | Not Started |
| 2.8 | Write gateway tests for root project default id and protection | US-1, US-3 | G3 | Coding agent | 30 min | Not Started |
| 2.9 | Update `FALLBACK_PROJECT_SEEDS`, protected ids, template aliases, and repair logic in `memory/init.ts` | US-2, US-3 | G2 | Coding agent | 1-2 hr | Not Started |
| 2.10 | Update `projects.seed.json` to seed `your-agent` | US-3 | G2 | Coding agent | 10 min | Not Started |
| 2.11 | Update `gateway/projects.ts` root id/default object and protection behavior | US-1, US-3 | G3 | Coding agent | 45 min | Not Started |
| 2.12 | Update `update-prompting.ts` root-template exclusion through identity helper or documented constants | US-4 | G4 | Coding agent | 30 min | Not Started |
| 2.13 | Run Phase 2 focused backend tests | US-2, US-3 | G2, G3 | Coding agent | 20 min | Not Started |

**Candidate files:**

- `builds/typescript/memory/init.ts`
- `builds/typescript/memory/init.test.ts`
- `builds/typescript/gateway/projects.ts`
- `builds/typescript/gateway/projects.test.ts`
- `builds/typescript/memory/starter-pack/projects/projects.seed.json`
- `builds/typescript/memory/update-prompting.ts`

**Implementation details:**

- The manifest should end with one visible active root-agent entry using:
  - `id: "your-agent"`
  - `name: "Your Agent"`
  - `icon: "sparkles"`
  - preserved `conversation_id`
  - preserved `default_skill_ids`
- `isProtectedProjectId` should protect canonical and legacy ids during compatibility.
- `scaffoldProjectFiles` should use the `your-agent` template for the canonical id.
- If `PROJECT_TEMPLATE_FILES` still creates fallback `spec.md` and `plan.md` for Your Agent, decide whether to special-case root-agent scaffolding so it only creates `AGENT.md`, or preserve current behavior temporarily and document why. Recommendation: special-case root-agent scaffolding to align with starter `AGENT.md`, but preserve existing owner files during migration.
- If a folder merge is unsafe, add a warning to the init summary. Do not throw unless startup would expose inconsistent data or corrupt memory.

**Success Criteria:**

| Criterion | Spec Ref | Gate | Verification | Expected Result | Evidence |
|---|---|---|---|---|---|
| Empty memory seeds canonical root | US-3 | G2 | `memory/init.test.ts` | Manifest id is `your-agent`; name is `Your Agent` | Test output |
| Legacy manifest migrates safely | US-2 | G2 | `memory/init.test.ts` | State preserved on canonical entry | Test output |
| Duplicate no-state manifests collapse safely | US-2 | G2 | `memory/init.test.ts` | One canonical entry remains | Test output |
| Duplicate one-state manifests preserve state | US-2 | G2 | `memory/init.test.ts` | Canonical entry keeps state | Test output |
| Duplicate conflicting manifests fail safe | US-2 | G2 | `memory/init.test.ts` | No silent data loss; warning/manual-review item exists | Test output |
| Gateway root default is canonical | US-3 | G3 | `gateway/projects.test.ts` | Root project id is `your-agent` | Test output |
| Legacy root id remains protected | US-2 | G3 | `gateway/projects.test.ts` | Rename/delete rejects legacy id during compatibility | Test output |

**Likely command:**

```bash
cd builds/typescript && npm run test -- --run memory/root-agent.test.ts memory/init.test.ts gateway/projects.test.ts
```

**Exit Criteria:** Backend initialization and gateway behavior use canonical identity and preserve legacy data under test.

### Phase 3: Client Selection And UI Cleanup

**Goal:** Move web client root-agent behavior to canonical `your-agent`, while still recognizing legacy project data returned before migration.

**Spec/Test Trace:**

| Spec Ref | Gate | Evidence Required |
|---|---|---|
| US-1, US-4 | G3 | Web hook/component tests and visible-label assertions |

**Tasks:**

| # | Task | Spec Ref | Gate | Owner | Estimate | Status |
|---|---|---|---|---|---|---|
| 3.1 | Write/update `useProjects` tests for canonical default selection | US-1, US-3 | G3 | Coding agent | 30 min | Not Started |
| 3.2 | Write/update `useProjects` tests for legacy response normalization | US-2 | G3 | Coding agent | 30 min | Not Started |
| 3.3 | Write/update AppShell/Sidebar tests for selecting `your-agent` | US-1 | G3 | Coding agent | 30 min | Not Started |
| 3.4 | Write/update empty-state tests if current coverage does not assert root intro behavior | US-1 | G3 | Coding agent | 20 min | Not Started |
| 3.5 | Add client-safe root-agent constants/helper if needed | US-4 | G3 | Coding agent | 30 min | Not Started |
| 3.6 | Replace `braindrive-plus-one` hard-coded selection/filter literals in web code | US-1, US-4 | G3 | Coding agent | 1 hr | Not Started |
| 3.7 | Keep labels as `Your Agent` and short label as `Agent` | US-1 | G3 | Coding agent | 15 min | Not Started |
| 3.8 | Run Phase 3 focused web tests | US-1, US-4 | G3 | Coding agent | 20 min | Not Started |

**Candidate files:**

- `builds/typescript/client_web/src/hooks/useProjects.ts`
- `builds/typescript/client_web/src/hooks/useProjects.test.ts`
- `builds/typescript/client_web/src/components/layout/AppShell.tsx`
- `builds/typescript/client_web/src/components/layout/AppShell.test.tsx`
- `builds/typescript/client_web/src/components/layout/Sidebar.tsx`
- `builds/typescript/client_web/src/components/layout/Sidebar.test.tsx`
- `builds/typescript/client_web/src/components/layout/SidebarCollapsed.tsx`
- `builds/typescript/client_web/src/components/layout/sidebar-labels.ts`
- `builds/typescript/client_web/src/components/chat/EmptyState.tsx`
- Optional new file: `builds/typescript/client_web/src/lib/rootAgent.ts` or similar existing utility location.

**Implementation details:**

- Default selection should prefer canonical `your-agent`.
- If API returns only legacy `braindrive-plus-one`, the client may treat it as root-agent for the current session but should avoid persisting legacy selection if the backend migration has normalized it.
- UI copy must not display `braindrive-plus-one`.
- Keep `Your Agent` in settings tabs and customization surfaces.

**Success Criteria:**

| Criterion | Spec Ref | Gate | Verification | Expected Result | Evidence |
|---|---|---|---|---|---|
| Client defaults to canonical root | US-1, US-3 | G3 | `useProjects.test.ts` | `selectedProjectId` is `your-agent` | Test output |
| Legacy API payload still works | US-2 | G3 | `useProjects.test.ts` | Legacy id is recognized as root without visible legacy text | Test output |
| Sidebar selects root assistant | US-1 | G3 | AppShell/Sidebar tests | Click/select uses canonical id | Test output |
| UI displays Your Agent | US-1 | G3 | Web tests | Label is `Your Agent` | Test output |

**Likely command:**

```bash
cd builds/typescript && npm run web:test -- --run src/hooks/useProjects.test.ts src/components/layout/AppShell.test.tsx src/components/layout/Sidebar.test.tsx
```

**Exit Criteria:** Web client root-agent behavior is canonical and owner-facing UI remains clean.

### Phase 4: Retired-Reference Guard And Intentional Legacy Allowlist

**Goal:** Make remaining legacy references auditable and prevent accidental reintroduction.

**Spec/Test Trace:**

| Spec Ref | Gate | Evidence Required |
|---|---|---|
| US-5 | G4 | Lint/scan output and allowlist |

**Tasks:**

| # | Task | Spec Ref | Gate | Owner | Estimate | Status |
|---|---|---|---|---|---|---|
| 4.1 | Define allowlist categories: identity helper, migration code, compatibility tests, historical docs, backup snapshots | US-5 | G4 | Coding agent | 20 min | Not Started |
| 4.2 | Write a script or architecture-lint test for retired display names and raw legacy slug locations | US-5 | G4 | Coding agent | 1 hr | Not Started |
| 4.3 | Update `draft3-memory-lint.ts` guard if root-agent template policy changes | US-5 | G4 | Coding agent | 30 min | Not Started |
| 4.4 | Rename test descriptions that use legacy language but are not compatibility tests | US-5 | G4 | Coding agent | 20 min | Not Started |
| 4.5 | Run retired-reference scan and document remaining allowed matches | US-5 | G4 | Coding agent | 20 min | Not Started |

**Candidate files:**

- `builds/typescript/tools/architecture-lint/draft3-memory-lint.ts`
- Optional new script/test under `builds/typescript/tools/architecture-lint/`
- Focused tests changed in Phases 1-3.

**Recommended allowlist:**

- Root identity helper constants for legacy ids.
- Migration/repair tests with fixtures named as legacy data.
- Migration/repair implementation where legacy ids are explicitly handled.
- Historical docs: `CHANGELOG.md`.
- Ignored backups/snapshots: `builds/typescript/your-memory.*`.
- Prior design docs under `/home/hex/Reference/...` are planning history, not repo product code.

**Success Criteria:**

| Criterion | Spec Ref | Gate | Verification | Expected Result | Evidence |
|---|---|---|---|---|---|
| Retired display names blocked | US-5 | G4 | lint/script or `rg` scan | No active owner-facing `BrainDrive+1` or `BD+1` | Scan/lint output |
| Legacy slug use is intentional | US-5 | G4 | allowlist scan | Matches only in allowed categories | Scan/lint output |
| Architecture lint still passes or known blocker is documented | US-5 | G4 | relevant test command | Pass or documented pre-existing failure | Test output |

**Suggested scan command if no script is added:**

```bash
git ls-files | rg -v '(^|/)node_modules/|(^|/)dist/|(^|/)coverage/|^CHANGELOG.md$|^builds/typescript/src-tauri/target/' | xargs rg -n -S 'BrainDrive\+1|BD\+1|braindrive-plus-one'
```

**Exit Criteria:** A future builder can tell why every remaining legacy reference exists.

### Phase 5: Baseline Verification, Live-Memory Review, And Handoff

**Goal:** Prove the cleanup works across focused checks, broader builds/tests, and the local live-memory state.

**Spec/Test Trace:**

| Spec Ref | Gate | Evidence Required |
|---|---|---|
| All success criteria and invariants | G5 | Test/build output, scan output, live-memory inspection |

**Tasks:**

| # | Task | Spec Ref | Gate | Owner | Estimate | Status |
|---|---|---|---|---|---|---|
| 5.1 | Run focused backend tests | US-2, US-3, US-4 | G2, G3 | Coding agent | 20 min | Not Started |
| 5.2 | Run focused web tests | US-1, US-4 | G3 | Coding agent | 20 min | Not Started |
| 5.3 | Run build and typecheck | All | G5 | Coding agent | 30 min | Not Started |
| 5.4 | Run full web test suite | US-1 | G5 | Coding agent | 30 min | Not Started |
| 5.5 | Run full backend test suite and document any pre-existing Draft 3 lint failure | All | G5 | Coding agent | 45 min | Not Started |
| 5.6 | Run retired-reference guard/scan | US-5 | G4 | Coding agent | 15 min | Not Started |
| 5.7 | Inspect live `builds/typescript/your-memory/documents/projects.json` and root-agent folders after migration | US-2 | G2, G5 | Coding agent | 20 min | Not Started |
| 5.8 | If practical, start dev app and verify owner-facing message says Your Agent | US-1 | G5 | Human/coding agent | TBD | Not Started |
| 5.9 | Update this plan/work log with completed evidence and any unresolved risk | All | G5 | Coding agent | 20 min | Not Started |

**Verification commands:**

```bash
cd builds/typescript && npm run test -- --run memory/root-agent.test.ts memory/init.test.ts gateway/projects.test.ts
cd builds/typescript && npm run web:test -- --run src/hooks/useProjects.test.ts src/components/layout/AppShell.test.tsx src/components/layout/Sidebar.test.tsx
cd builds/typescript && npm run build
cd builds/typescript && npm run web:typecheck
cd builds/typescript && npm run web:test
cd builds/typescript && npm run test
git diff --check
```

**Live-memory inspection commands:**

```bash
sed -n '1,140p' builds/typescript/your-memory/documents/projects.json
find builds/typescript/your-memory/documents -maxdepth 2 -type f | sort
rg -n --hidden --no-ignore -S 'BrainDrive\+1|BD\+1|braindrive-plus-one|your-agent' builds/typescript/your-memory/documents
```

**Success Criteria:**

| Criterion | Spec Ref | Gate | Verification | Expected Result | Evidence |
|---|---|---|---|---|---|
| Focused backend tests pass | US-2, US-3 | G2, G3 | focused `npm run test` | Exit code 0 | Test output |
| Focused web tests pass | US-1, US-4 | G3 | focused `npm run web:test` | Exit code 0 | Test output |
| Build passes | All | G5 | `npm run build` | Exit code 0 | Build output |
| Web typecheck passes | All | G5 | `npm run web:typecheck` | Exit code 0 | Typecheck output |
| Full web suite passes | US-1 | G5 | `npm run web:test` | Exit code 0 | Test output |
| Full backend suite status is known | All | G5 | `npm run test` | Passes or pre-existing blocker documented exactly | Test output |
| Retired references are approved | US-5 | G4 | scan/lint | Only allowlisted matches remain | Scan output |
| Live memory is sane | US-2 | G5 | file inspection | One active canonical root-agent manifest entry or documented manual-review item | File output |

**Exit Criteria:** The implementation is ready for PR or handoff with exact checks, outputs, remaining risks, and any manual-review items documented.

---

## Technical Details

### Tech Stack

| Layer | Technology | Notes |
|---|---|---|
| Main runtime | TypeScript / Node | Work is under `builds/typescript`. |
| Web client | React + TypeScript + Vite | Keep client constants browser-safe. |
| Tests | Vitest | Focused backend and web tests already exist. |
| Memory | File-backed JSON/Markdown | Migration must preserve owner-authored files. |
| Gateway | Fastify/TypeScript project service | Existing project service handles listing/create/rename/delete/files. |

### Environment And Version Constraints

Use the repo's existing Node/npm setup. Do not add dependencies unless unavoidable; this cleanup should be implemented with existing TypeScript and Node standard-library APIs.

### Data Structures

#### Root Agent Identity

Expected conceptual contract:

```ts
export const ROOT_AGENT_CANONICAL_ID = "your-agent";
export const ROOT_AGENT_LEGACY_IDS = ["braindrive-plus-one"] as const;
export const ROOT_AGENT_DISPLAY_NAME = "Your Agent";
export const ROOT_AGENT_ICON = "sparkles";
export const ROOT_AGENT_TEMPLATE_ID = "your-agent";
```

Expected helper behavior:

```ts
isRootAgentProjectId("your-agent") === true
isRootAgentProjectId("braindrive-plus-one") === true
isLegacyRootAgentProjectId("braindrive-plus-one") === true
canonicalizeRootAgentProjectId("braindrive-plus-one") === "your-agent"
canonicalizeRootAgentProjectId("finance") === "finance"
```

#### Migration Warning

If the existing `MemoryInitSummary.warnings` is sufficient, use it. Avoid adding a new persistence format unless required.

Suggested warning shape in text:

```text
Root agent identity migration preserved divergent legacy folder documents/braindrive-plus-one for manual review.
```

### API Endpoints

No new endpoints are planned. Existing gateway project APIs should return canonical root-agent identity after migration/repair.

### Dependencies

No new package dependencies are expected.

### Platform / Environment Notes

| Environment | Implementation Impact |
|---|---|
| Local dev memory | Must be migrated carefully; `builds/typescript/your-memory/` may be ignored by Git. |
| Existing owner memory | Must preserve data and conversation state. |
| New installs | Must seed canonical `your-agent`. |
| Managed mode | No provider/auth changes; verify root project behavior still works if mode-specific tests exist. |

### Model / Provider / Tool-Calling Notes

- No model provider configuration should change.
- Model-visible project context must use display name `Your Agent`.
- Memory tools may need path alias support if they can receive historical `documents/braindrive-plus-one/...` paths.
- Do not claim live model verification unless a running app and usable provider configuration are actually tested.

---

## Security Considerations

| Threat | Mitigation |
|---|---|
| Owner memory loss during folder migration | Tests for duplicate/conflicting folders; preserve divergent folders; fail safe with warning. |
| Conversation continuity loss | Preserve `conversation_id` on canonical manifest entry; test one-state and conflict cases. |
| Owner sees legacy branding again | Retired-name scan and owner-facing UI tests. |
| Model receives raw legacy id as display context | Gateway/memory tests plus runtime verification when possible. |
| Broad accidental refactor | Scope to identity, memory repair, gateway, client selection, and tests only. |
| Secrets/provider config touched accidentally | Do not edit provider credentials, config secrets, auth, or installer assets. |

---

## Risks And Mitigations

| Risk | Likelihood | Mitigation |
|---|---|---|
| Migration conflicts when both root-agent folders contain different owner-authored content | Medium | Preserve both and emit manual-review warning; do not delete. |
| Existing tests assume fallback `spec.md`/`plan.md` for root agent | High | Decide in Phase 2 whether to special-case root-agent scaffolding; update tests to reflect accepted behavior. |
| Full `npm run test` still fails on Draft 3 starter-pack lint issues | Medium | Document exact output; if this cleanup intentionally resolves the Your Agent artifact issue, update lint/tests accordingly. |
| Client imports server-only helper and breaks Vite build | Medium | Keep client-safe helper separate unless shared module is known browser-safe. |
| Legacy paths in old conversations are not resolved | Medium | Add path alias behavior or document compatibility diagnostic; test memory tool behavior if touched. |
| Global string replacement breaks compatibility fixtures | Medium | Avoid global replacement; use phased tests and allowlist. |
| Live `your-memory` changes are ignored by Git and missed in handoff | High | Inspect live files directly and report them explicitly. |

---

## Human Checkpoints

| Checkpoint | When | Human Decision / Review Needed |
|---|---|---|
| Canonical id confirmation | Before implementation starts | Confirm `your-agent` should become canonical persisted id. This plan assumes yes. |
| Duplicate live-memory folder review | After Phase 2 tests and before editing live memory | Decide whether divergent live `braindrive-plus-one` / `your-agent` files are archived, kept, or manually merged. |
| Root-agent artifact decision | During Phase 2 if tests expose `spec.md`/`plan.md` behavior | Confirm whether root agent should only scaffold `AGENT.md` for new installs. Recommendation: yes. |
| Live app verification | After Phase 5 automated checks | Human may need to run provider-backed chat and confirm assistant says Your Agent. |
| PR/handoff review | End of Phase 5 | Review remaining legacy allowlist and any documented blockers. |

---

## Open Items

1. **Formal test plan missing.**  
   Recommendation: proceed with inline gates for implementation, or create `dave-j-your-agent-identity-cleanup-test-plan.md` before coding if this needs release-process rigor.

2. **Canonical id decision is assumed, not separately approved in the spec file.**  
   This plan assumes the recommendation is accepted: canonical id becomes `your-agent`; `braindrive-plus-one` remains a legacy alias.

3. **Root-agent scaffold artifact policy needs final confirmation.**  
   Recommendation: for new canonical Your Agent scaffolds, only create `AGENT.md` unless existing code requires placeholder `spec.md`/`plan.md`. Preserve existing owner files.

4. **Legacy path alias behavior for memory tools may need deeper inspection.**  
   If memory tools resolve raw paths without project id canonicalization, add a focused compatibility layer or explicitly document the compatibility limit.

5. **Live app model verification depends on runnable dev instance and model/provider config.**  
   Do not claim this verification unless actually performed.

---

## Completion Checklist

### Phase 0

- [ ] Branch/worktree status captured.
- [ ] Tracked legacy-reference scan captured.
- [ ] Live-memory duplicate folder state captured.

### Phase 1

- [ ] Root-agent identity helper added.
- [ ] Identity helper tests pass.
- [ ] Constants cover canonical id, legacy ids, display name, icon, and template id.

### Phase 2

- [ ] Memory init tests cover empty, legacy-only, canonical-only, duplicate no-state, duplicate one-state, duplicate conflicting-state, legacy-folder-only, identical folders, and divergent folders.
- [ ] Memory init seeds `your-agent`.
- [ ] Legacy manifest/folder migration preserves data.
- [ ] Gateway root project default uses `your-agent`.
- [ ] Canonical and legacy root ids are protected during compatibility.
- [ ] Starter seed uses `your-agent`.

### Phase 3

- [ ] Web project selection defaults to `your-agent`.
- [ ] Legacy project payloads remain compatible.
- [ ] Sidebar/collapsed sidebar/AppShell use canonical root id.
- [ ] Owner-facing labels remain `Your Agent`.
- [ ] Focused web tests pass.

### Phase 4

- [ ] Retired-name/legacy-literal allowlist is defined.
- [ ] Guard script/lint or documented scan exists.
- [ ] Remaining `braindrive-plus-one` references are migration/compatibility/historical only.
- [ ] No active owner-facing `BrainDrive+1` or `BD+1` references remain.

### Phase 5

- [ ] Focused backend tests pass.
- [ ] Focused web tests pass.
- [ ] `npm run build` passes.
- [ ] `npm run web:typecheck` passes.
- [ ] `npm run web:test` passes.
- [ ] `npm run test` passes or exact pre-existing blocker is documented.
- [ ] `git diff --check` passes.
- [ ] Live `your-memory` manifest/folders are inspected and reported.
- [ ] Optional live owner-facing model check is completed or explicitly not run with reason.

---

## Recommended Next Step

Before coding, confirm the two practical decisions:

1. `your-agent` becomes the canonical persisted id now.
2. New root-agent scaffolds should only create `AGENT.md`, while existing `spec.md`, `plan.md`, `run-interview.md`, and `run-planning.md` files are preserved or archived through migration rather than deleted silently.

If both are accepted, begin Phase 0 and proceed tests-first through Phase 1.