# Build Plan: Your Agent Identity Cleanup Completion

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

---

## Overview

This build plan completes the remaining root-assistant identity cleanup from **BrainDrive+1** / `braindrive-plus-one` to **Your Agent** / `your-agent`.

The work is not a broad rename. The active product contract is: `your-agent` is canonical, **Your Agent** is the only normal owner-facing and model-fed name, and `braindrive-plus-one` remains only as a legacy compatibility alias, migration artifact, historical reference, or test fixture.

The main implementation risk is owner-memory data loss. Every cleanup step that removes a legacy active folder must archive or report the legacy content first.

---

## Goal

Complete the remaining identity transition so that:

1. Fresh installs seed only `your-agent` / **Your Agent**.
2. Existing installs with legacy root-agent memory self-heal without data loss.
3. `project_list` does not expose `braindrive-plus-one` as a normal project when `projects.json` is canonical.
4. Stale ignored desktop-runtime output cannot silently package old **BrainDrive+1** starter content.
5. Remaining legacy references are documented and allowlisted.

---

## Source Inputs

| Input | Location | Status | Notes |
|---|---|---|---|
| Completion spec | `/home/hex/Reference/Designs/BrainDrive-MVP/BrainDrive - Your Agent/your-agent-identity-cleanup-completion-spec.md` | Draft/accepted for planning by user request | Source of scope, findings, actions, user stories, and recommendations. |
| Original identity cleanup spec | `/home/hex/Reference/Designs/BrainDrive-MVP/BrainDrive - Your Agent/dave-j-your-agent-identity-cleanup-spec.md` | Reviewed previously | Defines broader Your Agent identity contract. |
| Original identity cleanup plan | `/home/hex/Reference/Designs/BrainDrive-MVP/BrainDrive - Your Agent/dave-j-your-agent-identity-cleanup-implementation-plan.md` | Reviewed previously | Prior plan that PR #207 partially implemented. |
| Work log | `/home/hex/Reference/Designs/BrainDrive-MVP/BrainDrive - Your Agent/dave-j-your-agent-identity-cleanup-work-log.md` | Reviewed previously | Historical execution notes. |
| Current repo | `/home/hex/Project/BrainDrive-Test-01` | Audited on `dev` | Current branch was clean and aligned with `origin/dev` at audit time. |
| Formal test plan | Not present | Missing by design | Inline gates below should be promoted to a separate test plan before release if needed. |

---

## Scope Guardrails

### In Scope

- Align `builds/mcp_release` `project_list` with manifest-based project discovery.
- Keep `projects.json` as the source of truth for active projects when present and parseable.
- Add tests proving leftover `documents/braindrive-plus-one` folders do not appear as active projects when the manifest is canonical.
- Improve duplicate root-agent folder handling in memory init:
  - legacy-only folder
  - canonical-only folder
  - both folders identical
  - both folders divergent
- Archive or quarantine legacy duplicate folders outside active `documents/` before removing them from active discovery.
- Write migration reports for any archive/quarantine action.
- Add a legacy identity search gate with an explicit allowlist.
- Add or document desktop-runtime staging/preflight cleanup so stale ignored output cannot ship old **BrainDrive+1** content.
- Keep compatibility alias support for old `braindrive-plus-one` inputs.

### Out Of Scope

- Removing `braindrive-plus-one` compatibility alias support entirely.
- Rewriting historical changelog entries.
- Editing old conversation logs, backups, exports, or ignored owner-memory snapshots unless doing local manual cleanup after archive verification.
- Refactoring unrelated memory architecture.
- Changing provider/model configuration, auth, billing, credits, installer, Docker, or deployment behavior.
- Redesigning the Your Agent page or broader starter-pack prompts.

### Change Control

If implementation reveals a new product requirement, release gate, or data-loss risk not covered here, stop and update `your-agent-identity-cleanup-completion-spec.md` before expanding scope.

Do not silently choose between conflicting conversation ids or overwrite canonical owner-authored files. Preserve and report conflicts.

---

## User Stories

### US-1: Owner Sees One Root Assistant - Confirmed

As a BrainDrive owner, I want the root assistant to appear only as **Your Agent** so that the product feels consistent and does not expose old internal naming.

**Implementation acceptance:**

```gherkin
Given a clean install
When memory initializes and project context is loaded
Then the root assistant is named "Your Agent"
And active starter-pack source contains no BrainDrive+1 root assistant seed
```

### US-2: Existing Legacy Memory Self-Heals - Confirmed

As an existing owner, I want old root-agent memory to carry forward safely so that upgrading does not lose files, conversation state, or customizations.

**Implementation acceptance:**

```gherkin
Given memory with only documents/braindrive-plus-one
When memory initialization runs
Then documents/your-agent exists with preserved content
And projects.json contains the canonical your-agent entry
And legacy content is archived or preserved according to policy
```

### US-3: Duplicate Folders Do Not Leak Into Project Discovery - Confirmed

As a BrainDrive owner or assistant, I want project discovery to list canonical projects so that preserved compatibility folders do not appear as extra projects.

**Implementation acceptance:**

```gherkin
Given projects.json contains only your-agent
And documents/braindrive-plus-one exists
When project_list runs
Then project_list returns Your Agent only
And project_list does not return braindrive-plus-one
```

### US-4: Divergent Legacy Data Is Preserved For Review - Confirmed

As a maintainer, I want divergent root-agent folders archived with a report so cleanup can remove stale active folders without destroying owner-authored data.

**Implementation acceptance:**

```gherkin
Given documents/your-agent and documents/braindrive-plus-one both exist
And their file contents differ
When memory initialization runs
Then legacy content is archived under system/migrations/your-agent-identity-cleanup
And a report explains the archive action
And active project discovery does not list braindrive-plus-one
```

### US-5: Desktop Runtime Cannot Package Stale Identity - Confirmed

As a desktop release builder, I want staged runtime output to be regenerated and checked so stale ignored files cannot ship old **BrainDrive+1** content.

**Implementation acceptance:**

```gherkin
Given desktop runtime is staged
When preflight/search checks run
Then staged starter-pack files do not contain BrainDrive+1, BD+1, or templates/braindrive-plus-one
```

---

## Key Decisions

| Decision | Choice | Rationale |
|---|---|---|
| Canonical active id | `your-agent` | Already implemented by PR #207 and matches product naming. |
| Owner-facing name | `Your Agent` | Accepted product language. |
| Legacy id | Keep `braindrive-plus-one` as alias only | Required for existing memory, URLs, tests, and older references. |
| Project source of truth | `documents/projects.json` when present and parseable | Prevents stale folders from appearing as active projects. |
| Duplicate folder cleanup | Archive/quarantine before removing legacy active folder | Prevents owner data loss while cleaning active namespace. |
| Divergent conflict policy | Preserve and report, do not silently merge | Avoids overwriting owner-authored files and conversation state. |
| Desktop runtime handling | Regenerate or remove ignored output; commit source/preflight only | `src-tauri/desktop-runtime/` is generated and ignored. |
| Formal test plan | Optional follow-up for release | User asked for implementation plan now; inline gates cover execution. |

---

## Current State And Remediation

| Current Behavior / Gap | Required Target | Source | Build Task |
|---|---|---|---|
| Main runtime has `your-agent` constants and legacy alias | Preserve constants and alias contract | Spec findings 1-2 | Phase 1 audit and allowlist |
| Duplicate manifest entries with conflicting conversation ids are preserved | Preserve safely, report conflict clearly | Spec finding 3 | Phase 2 tests/reporting |
| Duplicate folders only warn when divergent | Archive/quarantine legacy duplicate folder outside active `documents/` | Spec finding 4 | Phase 2 |
| Main starter pack is canonical | Keep canonical and add search guard | Spec finding 5 | Phase 1/4 |
| Ignored local `your-memory` can contain both folders | Do not treat as source; optionally clean after archive verification | Spec finding 6 | Phase 5 manual/local |
| `builds/mcp_release` scans directories for projects | Read `projects.json` first and canonicalize root-agent ids | Spec finding 7 | Phase 3 |
| Ignored desktop runtime can contain stale old seed/template | Regenerate/remove and add preflight/search guard | Spec finding 8 | Phase 4 |
| Tracked legacy refs remain for compatibility/tests/history | Add allowlist and fail on unapproved refs | Spec finding 9 | Phase 4 |

---

## Architecture

### Component Map

```text
Memory init
  builds/typescript/memory/init.ts
  - canonicalizes manifest entries
  - migrates/copies/archives duplicate root-agent folders
  - writes migration reports

Root-agent identity helpers
  builds/typescript/memory/root-agent.ts
  builds/typescript/client_web/src/lib/rootAgent.ts
  - canonical id, display name, legacy aliases

Project discovery
  builds/typescript/tools/project-tools.ts
  builds/mcp_release/src/memory-core.ts
  - read active projects from projects.json
  - canonicalize legacy root-agent ids
  - avoid directory-only stale project leaks

Desktop runtime staging
  builds/typescript/scripts/desktop-stage-runtime.mjs
  builds/typescript/scripts/desktop-stage-runtime.ps1
  - copies current tracked starter-pack into generated runtime
  - preflight/search gate rejects stale identity strings

Verification gates
  focused unit/integration tests
  search/lint allowlist
  optional local memory cleanup checklist
```

### Data Flow

1. BrainDrive starts and initializes memory.
2. Memory init reads `documents/projects.json`.
3. Root-agent manifest entries are canonicalized to `your-agent` unless there is a true conflict requiring review.
4. Root-agent folder compatibility checks active folders.
5. Legacy duplicate folders are archived/quarantined outside active `documents/` after preserving data.
6. `project_list` reads manifest projects and reports active projects only.
7. UI/model/tool context receives **Your Agent** and `your-agent`, not old identity text.

### Migration Artifact Contract

Recommended archive root:

```text
system/migrations/your-agent-identity-cleanup/<timestamp-or-run-id>/
```

Recommended files:

```text
system/migrations/your-agent-identity-cleanup/<run-id>/report.md
system/migrations/your-agent-identity-cleanup/<run-id>/report.json
system/migrations/your-agent-identity-cleanup/<run-id>/braindrive-plus-one/
```

Minimum report fields:

- migration id / timestamp
- dry-run status
- memory root
- canonical folder path
- legacy folder path
- action taken
- files archived
- files identical
- files divergent
- warnings
- manual review instructions

### Observability And Evidence Hooks

| Evidence Need | Implementation Hook |
|---|---|
| Duplicate-folder cleanup proof | Migration report fixture assertions |
| No project leak | `project_list` test output |
| No stale owner-facing identity | Search gate output |
| Desktop runtime clean | Desktop staging/search output |
| No data loss | Tests assert archived legacy content remains readable |

---

## Implementation Instructions For Coding Agents

1. Start in `/home/hex/Project/BrainDrive-Test-01`.
2. Confirm branch and worktree before editing:

```bash
git status --short --branch
```

3. Read files before touching them:
   - `builds/typescript/memory/init.ts`
   - `builds/typescript/memory/init.test.ts`
   - `builds/typescript/memory/root-agent.ts`
   - `builds/typescript/tools/project-tools.ts`
   - `builds/mcp_release/src/memory-core.ts`
   - relevant `builds/mcp_release` tests
   - desktop staging scripts if implementing Phase 4
4. Write tests first in each phase.
5. Do not delete user data. Archive first, assert archive contents in tests, then remove the active legacy folder only after preservation is proven.
6. Do not edit ignored `builds/typescript/your-memory/` as part of source implementation unless explicitly doing the optional local cleanup phase.
7. Do not commit or edit `builds/typescript/src-tauri/desktop-runtime/`; it is ignored generated output. Commit source/preflight changes only.
8. Do not remove `braindrive-plus-one` alias support in V1.
9. Keep changes scoped to Your Agent identity cleanup.

### Implementation Prompt For Phase 1

Use this prompt when assigning Phase 1 to an implementation agent:

```text
You are implementing Phase 1 of the Your Agent identity cleanup completion plan in /home/hex/Project/BrainDrive-Test-01 on dev.

Goal: establish the verification baseline and allowlist for legacy identity references without changing behavior yet.

Read:
- your-agent-identity-cleanup-completion-spec.md
- builds/typescript/memory/root-agent.ts
- builds/typescript/memory/init.ts
- builds/typescript/tools/project-tools.ts
- builds/mcp_release/src/memory-core.ts

Tasks:
1. Add or update a focused legacy identity search/check script or test.
2. Allowlist compatibility constants, migration code, focused tests, and historical changelog lines.
3. Fail on unapproved owner-facing BrainDrive+1, BD+1, or braindrive-plus-one references.
4. Run focused tests/searches and report exact output.

Do not modify memory migration behavior in this phase.
```

### Implementation Prompt For Phase 2

```text
You are implementing Phase 2 of the Your Agent identity cleanup completion plan.

Goal: replace warning-only duplicate folder handling with safe archive/quarantine behavior.

Rules:
- Tests first.
- Do not delete divergent owner data.
- Archive duplicate legacy folders outside active documents before removing them from active discovery.
- Write migration reports under system/migrations/your-agent-identity-cleanup/.

Required scenarios:
1. legacy-only folder
2. canonical-only folder
3. both folders identical
4. both folders divergent
5. dry-run mode

Run focused memory init tests before handoff.
```

### Implementation Prompt For Phase 3

```text
You are implementing Phase 3 of the Your Agent identity cleanup completion plan.

Goal: align builds/mcp_release project_list with the manifest-based project discovery used by the main TypeScript tool path.

Rules:
- Read documents/projects.json when present and parseable.
- Canonicalize braindrive-plus-one to your-agent.
- Do not include folder-only legacy projects when manifest is canonical.
- Keep fallback directory scanning only for missing/unparseable manifest if needed for backward compatibility.

Add tests showing that a leftover documents/braindrive-plus-one folder does not appear in project_list when projects.json contains your-agent only.
```

### Implementation Prompt For Phase 4

```text
You are implementing Phase 4 of the Your Agent identity cleanup completion plan.

Goal: prevent stale BrainDrive+1 identity strings from entering generated desktop runtime or tracked starter-pack source.

Rules:
- Do not commit src-tauri/desktop-runtime; it is ignored generated output.
- Add source/preflight checks where appropriate.
- Verify the tracked main starter pack remains canonical.
- If desktop runtime is staged locally, search it and fail/report stale BrainDrive+1 or templates/braindrive-plus-one.
```

### Implementation Prompt For Phase 5

```text
You are implementing Phase 5 final verification and optional local cleanup.

Goal: prove the cleanup is complete and, if requested, clean this local dev memory safely.

Rules:
- Do not edit ignored your-memory unless explicitly authorized for local cleanup.
- If cleaning local memory, compare/archive before removing documents/braindrive-plus-one.
- Run focused tests, MCP release tests, source search gate, and git diff checks.
- Report changed files, commands run, results, and remaining risks.
```

---

## Implementation Roadmap

### Schedule Overview

| Phase | Goal | Spec Refs | Owner | Status |
|---|---|---|---|---|
| 1 | Baseline, allowlist, and search gate | Findings 1, 5, 9; US-1 | Implementation agent | Not Started |
| 2 | Safe memory duplicate-folder archive/quarantine | Findings 3, 4, 6; US-2, US-4 | Implementation agent | Not Started |
| 3 | Manifest-based MCP release project discovery | Finding 7; US-3 | Implementation agent | Not Started |
| 4 | Desktop runtime and starter-pack stale identity guard | Finding 8; US-5 | Implementation agent | Not Started |
| 5 | Final verification and optional local cleanup | All | Implementation agent + Dave W checkpoint | Not Started |

### Phase 1: Baseline And Legacy Identity Gate

**Goal:** Establish the allowed/forbidden legacy reference boundary before behavior changes.

**Tasks:**

| # | Task | Spec Ref | Owner | Status |
|---|---|---|---|---|
| 1.1 | Write or update a focused test/script that scans tracked source for `BrainDrive+1`, `BD+1`, `braindrive-plus-one`, and `templates/braindrive-plus-one` | Findings 5, 9 | Implementation agent | Not Started |
| 1.2 | Define allowlist entries for compatibility constants, migration code, focused tests, and historical changelog lines | Finding 9 | Implementation agent | Not Started |
| 1.3 | Ensure the check fails on owner-facing UI, active starter-pack source, model prompts, and unapproved project discovery surfaces | US-1 | Implementation agent | Not Started |
| 1.4 | Run baseline search and focused existing tests before behavior changes | All | Implementation agent | Not Started |

**Success Criteria:**

| Criterion | Spec Ref | Verification | Expected Result | Evidence |
|---|---|---|---|---|
| Legacy search gate exists | Finding 9 | Run added script/test | Fails on unapproved legacy refs, passes allowlisted refs | Command output |
| Main starter pack clean | Finding 5 | `rg -n "BrainDrive\\+1|BD\\+1|templates/braindrive-plus-one" builds/typescript/memory/starter-pack` | No unapproved matches | Search output |
| Baseline tests pass | All | Focused test commands | Exit code 0 | Test output |

**Exit Criteria:** Search allowlist is documented and passing before migration behavior changes.

### Phase 2: Memory Init Archive And Quarantine

**Goal:** Remove legacy duplicate folders from the active `documents/` namespace without losing data.

**Tasks:**

| # | Task | Spec Ref | Owner | Status |
|---|---|---|---|---|
| 2.1 | Write tests for identical duplicate folders | Finding 4; US-4 | Implementation agent | Not Started |
| 2.2 | Write tests for divergent duplicate folders with unique legacy content | Finding 4; US-4 | Implementation agent | Not Started |
| 2.3 | Write tests for dry-run behavior and migration report output | Finding 4 | Implementation agent | Not Started |
| 2.4 | Implement archive/quarantine helper in `memory/init.ts` or a local helper module | Finding 4 | Implementation agent | Not Started |
| 2.5 | Preserve legacy-only migration behavior while ensuring canonical folder is created | US-2 | Implementation agent | Not Started |
| 2.6 | Write `report.md` and/or `report.json` under `system/migrations/your-agent-identity-cleanup/` | US-4 | Implementation agent | Not Started |
| 2.7 | Run focused memory init tests | US-2, US-4 | Implementation agent | Not Started |

**Success Criteria:**

| Criterion | Spec Ref | Verification | Expected Result | Evidence |
|---|---|---|---|---|
| Identical duplicates cleaned safely | US-4 | `npm run test -- memory/init.test.ts` | Legacy active folder archived/removed; content preserved or proven identical | Test output |
| Divergent duplicates archived | US-4 | `npm run test -- memory/init.test.ts` | Archive contains legacy files and report exists | Test output + fixture assertions |
| Dry-run safe | Finding 4 | Focused dry-run test | Reports planned actions; no files moved | Test output |
| Legacy-only still migrates | US-2 | Existing/focused migration test | Canonical folder created and content preserved | Test output |

**Exit Criteria:** Memory init no longer leaves duplicate legacy folders active without archive/report handling.

### Phase 3: MCP Release Project Discovery Alignment

**Goal:** Prevent `builds/mcp_release` `project_list` from exposing folder-only legacy projects.

**Tasks:**

| # | Task | Spec Ref | Owner | Status |
|---|---|---|---|---|
| 3.1 | Read existing `builds/mcp_release` test patterns for memory-core/project tools | Finding 7 | Implementation agent | Not Started |
| 3.2 | Write tests for manifest-based project listing with leftover `documents/braindrive-plus-one` folder | US-3 | Implementation agent | Not Started |
| 3.3 | Write tests for missing/malformed manifest fallback behavior if fallback is retained | Open Q4 | Implementation agent | Not Started |
| 3.4 | Implement manifest parsing and root-agent canonicalization in `builds/mcp_release/src/memory-core.ts` | US-3 | Implementation agent | Not Started |
| 3.5 | Ensure returned shape stays compatible with MCP consumers | US-3 | Implementation agent | Not Started |
| 3.6 | Run `builds/mcp_release` tests | US-3 | Implementation agent | Not Started |

**Success Criteria:**

| Criterion | Spec Ref | Verification | Expected Result | Evidence |
|---|---|---|---|---|
| MCP project_list uses manifest | US-3 | `cd builds/mcp_release && npm run test` | Canonical manifest controls output | Test output |
| Folder-only legacy project excluded | US-3 | Focused MCP test | No `braindrive-plus-one` project returned | Test output |
| Fallback behavior defined | Open Q4 | Missing/malformed manifest test | Intentional fallback or intentional empty result | Test output |

**Exit Criteria:** Main TypeScript and MCP release project discovery agree on active project list behavior.

### Phase 4: Desktop Runtime And Starter-Pack Guard

**Goal:** Ensure stale generated runtime output cannot package old **BrainDrive+1** starter content.

**Tasks:**

| # | Task | Spec Ref | Owner | Status |
|---|---|---|---|---|
| 4.1 | Write or extend a search/preflight check for active starter-pack and staged desktop runtime identity strings | Finding 8; US-5 | Implementation agent | Not Started |
| 4.2 | Ensure check ignores absent `src-tauri/desktop-runtime/` but validates it when present | US-5 | Implementation agent | Not Started |
| 4.3 | Add documentation or script output instructing builders to regenerate/remove ignored runtime before desktop build | Finding 8 | Implementation agent | Not Started |
| 4.4 | Run desktop-related search checks; run desktop preflight only if dependencies/build artifacts are available | US-5 | Implementation agent | Not Started |

**Success Criteria:**

| Criterion | Spec Ref | Verification | Expected Result | Evidence |
|---|---|---|---|---|
| Tracked starter-pack clean | Finding 5 | Source search gate | No unapproved stale identity strings | Search output |
| Staged runtime checked when present | US-5 | Runtime search/preflight | Fails on stale `BrainDrive+1`; passes canonical runtime | Command output |
| No generated output committed | Finding 8 | `git status --short` | No tracked generated desktop runtime changes | Git status |

**Exit Criteria:** Desktop build path has a clear guard against stale ignored runtime identity content.

### Phase 5: Final Verification And Optional Local Dev Memory Cleanup

**Goal:** Prove all cleanup work is complete, then optionally clean local ignored memory after archive verification.

**Tasks:**

| # | Task | Spec Ref | Owner | Status |
|---|---|---|---|---|
| 5.1 | Run all focused TypeScript tests touched by memory/project cleanup | All | Implementation agent | Not Started |
| 5.2 | Run all `builds/mcp_release` tests | US-3 | Implementation agent | Not Started |
| 5.3 | Run source search gate and `git diff --check` | Findings 5, 9 | Implementation agent | Not Started |
| 5.4 | Run broader repo checks if time and dependencies allow | All | Implementation agent | Not Started |
| 5.5 | Optional: archive/remove local ignored `builds/typescript/your-memory/documents/braindrive-plus-one` after confirming no unique data is lost | Finding 6 | Dave W approval + implementation agent | Not Started |
| 5.6 | Update work log or implementation plan with completed commands and results | All | Implementation agent | Not Started |

**Success Criteria:**

| Criterion | Spec Ref | Verification | Expected Result | Evidence |
|---|---|---|---|---|
| Focused TS tests pass | All | `cd builds/typescript && npm run test -- memory/init.test.ts gateway/projects.test.ts` plus any new tests | Exit code 0 | Test output |
| MCP release tests pass | US-3 | `cd builds/mcp_release && npm run test` | Exit code 0 | Test output |
| Search gate clean | Findings 5, 9 | Added script/test or `rg` command | Only allowlisted refs remain | Search output |
| Diff clean | All | `git diff --check` | Exit code 0 | Command output |
| Optional local cleanup safe | Finding 6 | Manual diff/archive report | Legacy local folder removed from active docs only after archive/review | Report/log |

**Exit Criteria:** Implementation satisfies spec success definition and remaining risk is documented.

---

## Technical Details

### Likely Files To Touch

| Area | Files |
|---|---|
| Memory init/migration | `builds/typescript/memory/init.ts`, `builds/typescript/memory/init.test.ts` |
| Root-agent constants | `builds/typescript/memory/root-agent.ts`, maybe tests only |
| Main project tools | `builds/typescript/tools/project-tools.ts`, add test if missing |
| MCP release project listing | `builds/mcp_release/src/memory-core.ts`, relevant MCP tests |
| Verification/search gate | `builds/typescript/package.json`, scripts or tests; exact location to follow repo patterns |
| Desktop staging guard | `builds/typescript/scripts/desktop-stage-runtime.mjs`, `builds/typescript/scripts/desktop-stage-runtime.ps1`, or preflight script if one exists |
| Docs/work log | This plan and/or a new work log if requested during implementation |

### Tech Stack

| Layer | Technology | Notes |
|---|---|---|
| Core runtime | TypeScript / Node | Main memory init and project tools. |
| Tests | Vitest | Existing TypeScript test runner. |
| MCP release | TypeScript / Node | Separate package under `builds/mcp_release`. |
| Desktop shell | Tauri | Only staging/preflight guard is in scope; no desktop UI changes expected. |

### Verification Commands

Focused commands:

```bash
cd /home/hex/Project/BrainDrive-Test-01/builds/typescript
npm run test -- memory/init.test.ts gateway/projects.test.ts
```

```bash
cd /home/hex/Project/BrainDrive-Test-01/builds/mcp_release
npm run test
```

```bash
cd /home/hex/Project/BrainDrive-Test-01
rg -n "BrainDrive\\+1|BD\\+1|braindrive-plus-one|templates/braindrive-plus-one" builds/typescript builds/mcp_release CHANGELOG.md
```

```bash
cd /home/hex/Project/BrainDrive-Test-01
git diff --check
```

Broader checks if scope justifies and dependencies are available:

```bash
cd /home/hex/Project/BrainDrive-Test-01/builds/typescript
npm run test
npm run web:typecheck
```

```bash
cd /home/hex/Project/BrainDrive-Test-01/builds/mcp_release
npm run build
npm run test
```

### Migration Report Example

Suggested `report.md` shape:

```markdown
# Your Agent Identity Cleanup Migration

**Run:** 2026-07-02T00-00-00Z
**Dry run:** false
**Action:** archived divergent legacy root-agent folder

## Paths

- Canonical: documents/your-agent
- Legacy: documents/braindrive-plus-one
- Archive: system/migrations/your-agent-identity-cleanup/2026-07-02T00-00-00Z/braindrive-plus-one

## Summary

- Files archived: 5
- Identical files: 1
- Divergent files: 4
- Files unique to legacy: 0

## Manual Review

Review the archive before deleting it from memory exports. Active project discovery now uses documents/projects.json and does not list braindrive-plus-one.
```

### Search Allowlist Guidance

Allow:

- `ROOT_AGENT_LEGACY_IDS = ["braindrive-plus-one"]`
- tests named around legacy compatibility
- migration/archive code
- user-facing reports that explicitly say "legacy"
- historical changelog entries

Fail:

- active starter-pack templates
- UI labels and empty states
- model/system prompts
- tool output that lists active projects
- desktop staged starter-pack output
- new docs that refer to **BrainDrive+1** as current product identity

---

## Security, Privacy, And Trust Considerations

| Risk | Mitigation |
|---|---|
| Owner data loss during folder cleanup | Archive before active removal; assert archive contents in tests. |
| Silent overwrite of canonical files | Never overwrite canonical divergent files without report/manual review. |
| Legacy identity leakage into model context | Search gate plus project_list manifest behavior. |
| Generated desktop runtime stale state | Regenerate/remove ignored output and add preflight/search. |
| Overbroad cleanup | Keep alias support and historical records; do not global-replace blindly. |

---

## Risks And Mitigations

| Risk | Likelihood | Mitigation |
|---|---:|---|
| Duplicate folders contain meaningful divergent owner data | Medium | Archive full legacy folder and write report before active cleanup. |
| MCP release consumers rely on directory-scan shape | Medium | Preserve response shape while changing project source to manifest; add fallback only for missing/malformed manifest. |
| Search gate becomes noisy because compatibility refs are legitimate | Medium | Maintain a narrow allowlist with file/path reasons. |
| Desktop runtime checks fail on local stale ignored output | High locally | Document regeneration/removal path; do not commit generated runtime. |
| Full repo tests are slow or flaky | Medium | Run focused tests first, then broader checks where available; report exact blockers. |

---

## Open Items And Recommendations

| # | Open Item | Recommendation | Blocks |
|---:|---|---|---|
| 1 | Should duplicate legacy folders be deleted or archived? | Archive in V1. Delete only after at least one release window or explicit manual approval. | Phase 2 implementation details. |
| 2 | Where should archived folders live? | `system/migrations/your-agent-identity-cleanup/<run-id>/` inside memory root, outside active `documents/`. | Phase 2 path contract. |
| 3 | Should migration write markdown, JSON, or both? | Write JSON for tests/tooling and markdown for human review. | Phase 2 report format. |
| 4 | Should conflicting manifest conversation ids preserve both active manifest entries? | Preserve conflict information, but prefer one canonical active entry if a report/archive can hold the conflict safely. If schema cannot represent manual-review state, preserve existing behavior until a schema decision is made. | Manifest conflict implementation. |
| 5 | Should MCP release fall back to directory scanning? | Yes only when `projects.json` is missing or unreadable. Manifest must be authoritative when valid. | Phase 3 behavior. |
| 6 | Should ignored local `your-memory` be cleaned during implementation? | Not as source work. Do it only as optional local hygiene after Phase 2 behavior is implemented or after manual archive verification. | Phase 5 optional cleanup. |
| 7 | Should ignored desktop runtime be deleted now? | Safe to remove/regenerate locally, but do not commit it. Commit only source/preflight changes. | Phase 4 local hygiene. |
| 8 | Should formal `/test-plan` be created? | Recommended before release, but not blocking this implementation plan because inline gates are explicit. | Release process quality, not Phase 1 start. |

---

## Human Checkpoints

### Before Phase 2 Merge

- Confirm archive/quarantine behavior is acceptable.
- Review migration report shape.
- Confirm no owner data is deleted from active memory without archive.

### Before Phase 3 Merge

- Confirm MCP release `project_list` fallback behavior when `projects.json` is missing or malformed.

### Before Phase 5 Optional Local Cleanup

- Dave W approves cleaning ignored local `builds/typescript/your-memory/documents/braindrive-plus-one`.
- Archive/diff evidence is reviewed.

### Final Review

- Review remaining legacy references and allowlist.
- Confirm all unapproved **BrainDrive+1** references are gone.
- Confirm final commands and results are logged.

---

## Completion Checklist

### Code

- [ ] Phase 1 search/allowlist gate complete.
- [ ] Phase 2 memory archive/quarantine behavior complete.
- [ ] Phase 3 MCP release project discovery aligned.
- [ ] Phase 4 desktop runtime/source stale identity guard complete.
- [ ] No generated or ignored runtime output committed.
- [ ] No unrelated refactors included.

### Tests

- [ ] Memory init duplicate-folder tests pass.
- [ ] Project discovery tests pass.
- [ ] MCP release tests pass.
- [ ] Search gate passes with only allowlisted legacy references.
- [ ] `git diff --check` passes.
- [ ] Broader TypeScript/MCP builds run or blockers documented.

### Documentation

- [ ] Migration report format documented in tests or code comments where useful.
- [ ] This plan updated if implementation changes scope or decisions.
- [ ] Optional work log updated if one is created for implementation.

### Data Safety

- [ ] Owner-authored divergent legacy content is archived before active cleanup.
- [ ] Canonical `documents/your-agent` content is not overwritten silently.
- [ ] Legacy alias support remains.
- [ ] Historical records are preserved.

---

## Work Log

### 2026-07-02 - Plan Created

- What was attempted: Created implementation plan from `your-agent-identity-cleanup-completion-spec.md`.
- What worked: Converted current-state findings into five testable phases with explicit instructions, prompts, and verification gates.
- What did not work: Formal test plan is still absent; inline gates are included as a pragmatic substitute.
- Decisions made: Recommend archive/quarantine over deletion for V1; recommend manifest-based MCP release project discovery.
- Lessons learned: Remaining cleanup is mostly namespace hygiene and project discovery correctness, not product copy rename work.

---

## Conversation References

| Date | Source | Topic | Location |
|---|---|---|---|
| 2026-07-02 | Dave W / Codex chat | Audit of PR #207/#208, remaining Your Agent cleanup issues, completion spec creation, implementation plan request | Current session |

---

## Notes

The highest-priority implementation item is Phase 3 if the immediate symptom is the assistant seeing `braindrive-plus-one` in project discovery. The highest data-safety item is Phase 2 because it defines how active duplicate folders leave `documents/` without data loss.

Recommended execution order remains Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5 because the search/allowlist and migration policy reduce risk before changing discovery behavior broadly.