# Dave W Runtime Follow-Up Execution Plan

**Status:** Complete  
**Created:** 2026-06-28  
**Updated:** 2026-06-28  
**Source reply:** `dave-w-reply.md`  
**Related plan:** `dave-j-runtime-pack-boundary-execution-plan.md`  
**Target repo:** `/home/hex/Project/BrainDrive-Test-01`  
**Target branch:** `dev`

## Overview

Dave W agreed with the runtime/starter-pack boundary cleanup, but identified a more serious remaining early-write source: gateway runtime code that writes starter project artifacts directly, independent of model behavior.

The next work should close that gap before broader per-domain runtime guard cleanup.

Target boundary:

> Starter-pack markdown owns owner-visible assistant behavior. Runtime supplies state, capabilities, and code-enforced safety.

This plan focuses on three follow-up items:

1. Remove or disable the starter snapshot auto-write path that mutates `spec.md` / `plan.md` outside the approved assistant/tool/write flow.
2. Fix the profile heading mismatch by making `# Your Profile` canonical.
3. Add regression coverage that catches both prompt-level and non-prompt runtime early-write behavior.

## Source Inputs

- `dave-w-reply.md`
- `dave-j-runtime-pack-boundary-execution-plan.md`
- Current merged `dev` after:
  - PR #183: runtime prompt behavior / child-app cleanup
  - PR #184: starter-pack write framing and Finance defer fix
- Current code in:
  - `builds/typescript/gateway/server.ts`
  - `builds/typescript/gateway/project-chat-context.test.ts`
  - `builds/typescript/memory/init.ts`
  - `builds/typescript/memory/init.test.ts`
  - starter-pack profile files under `builds/typescript/memory/starter-pack/`

## Scope Guardrails

Do:

- Treat starter snapshot auto-write as blocker-level until removed, disabled, or explicitly reclassified.
- Remove runtime persona/scenario-derived anchors such as hardcoded `Katie` text.
- Prevent runtime code from mutating starter `spec.md` / `plan.md` just because a chat turn has a `projectId`.
- Keep normal assistant/tool file-writing flows intact.
- Make `# Your Profile` the canonical seed heading unless a maintainer explicitly rejects that choice.
- Add focused tests before implementation where practical.
- Keep remaining per-domain runtime guards out of this pass unless needed for tests.

Do not:

- Delete active project context, file-list context, upload metadata, or path-safety behavior as part of this follow-up.
- Rewrite starter-pack interview behavior beyond the profile heading fix.
- Rework Finance starter-pack wording in this follow-up; Dave W owned that pack-lane item, and PR #184 has already updated the Finance starter-pack framing on `dev`.
- Touch provider configuration, owner API keys, hosted URLs, or unrelated model/provider work.
- Reintroduce Budget app or child-app behavior.
- Treat broad Phase 3 per-domain guard migration as part of this blocker fix.

## Key Decisions

1. `# Your Profile` should be canonical because it matches the current starter pack and owner-facing sidebar language.
2. The runtime starter snapshot path is not just prompt prose; it is a model-independent mutation path and should be handled before broader prompt cleanup.
3. The safest default implementation is to remove or disable automatic snapshot persistence unless a product owner explicitly approves a replacement flow.
4. Persona-derived anchors do not belong in runtime. They are owner-visible behavior and scenario overfit.
5. Runtime-sim coverage must include mutation assertions, not only prompt-text assertions.

## Current State & Remediation

Confirmed current state on merged `dev`:

- `/message` calls `persistStarterProjectArtifactSnapshots(...)` after user message persistence.
- `/message` calls `persistStarterProjectArtifactSnapshots(...)` again after assistant reply persistence.
- `persistStarterProjectArtifactSnapshot(...)` reads and writes `documents/{projectId}/spec.md` and `documents/{projectId}/plan.md`.
- `starterSnapshotProjectIds(...)` can fan out from Your Agent / BrainDrive+1 into Career, Finance, Fitness, and Relationships based on regexes over owner text.
- `buildStarterDerivedAnchors(...)` contains hardcoded persona/scenario anchors, including `Katie` lines.
- `memory/init.ts` still seeds `# Owner Profile`.
- `memory/init.test.ts` still expects `# Owner Profile`.
- The starter-pack profile file uses `# Your Profile`.
- Dave W's Finance starter-pack lane has been handled separately by PR #184; this follow-up should not make additional Finance pack edits unless a new review finds a regression.

## Architecture

### Runtime Write Boundary

The gateway should not write starter project artifacts as a side effect of every chat turn.

Approved write paths should be explicit and observable:

- assistant/tool-driven file writes through existing memory tools
- user-initiated file operations
- migration/bootstrap paths that are clearly scoped to initialization

The auto snapshot path violates this boundary because it:

- writes outside the model/tool decision path
- derives owner-facing content through runtime regexes
- can mutate multiple project files from one chat
- can insert scenario/persona text that the owner did not provide

### Profile Heading

The profile seed path should match the starter pack:

- fallback seed: `# Your Profile`
- init test expectation: `# Your Profile`
- no changes to the rest of the profile content unless required by tests

### Regression Coverage

Coverage should include:

- unit-level tests for removed snapshot helpers or disabled behavior
- route/runtime tests proving `/message` does not auto-write starter artifacts
- prompt/context tests proving prohibited prompt text stays absent
- memory init test proving `# Your Profile` is seeded

## Implementation Roadmap

### Phase 1: Snapshot Auto-Write Characterization

Status: Complete as of 2026-06-28

Goal: add tests that expose the existing runtime mutation before changing behavior.

Tasks:

1. [x] Inspect existing gateway test helpers for project file read/write stubs.
2. [x] Add a focused regression test around the gateway runtime source that protects against restoring the starter snapshot auto-write path.
3. [x] Assert runtime must not write `documents/{projectId}/spec.md` or `documents/{projectId}/plan.md` through the deleted snapshot path.
4. [x] Add prohibited-content assertions for hardcoded persona anchors, including `Katie`.

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Auto-write behavior is covered | Focused gateway test | Test fails against current auto-write behavior before implementation | Test output |
| Persona anchors covered | Focused gateway test or search-backed assertion | Hardcoded `Katie`/derived scenario anchors are not permitted in runtime snapshot output | Test output |

### Phase 2: Remove or Disable Snapshot Auto-Write

Status: Complete as of 2026-06-28

Goal: stop runtime from mutating starter artifacts outside approved write flow.

Tasks:

1. [x] Remove the pre-response call to `persistStarterProjectArtifactSnapshots(...)` in `/message`.
2. [x] Remove the post-response call to `persistStarterProjectArtifactSnapshots(...)` in `/message`.
3. [x] Delete now-unused snapshot persistence helpers if no longer referenced:
   - `persistStarterProjectArtifactSnapshots`
   - `persistStarterProjectArtifactSnapshot`
   - `starterSnapshotProjectIds`
   - `buildStarterProjectArtifactSnapshot`
   - `buildStarterDerivedAnchors`
   - snapshot merge/update helpers if only used by this path
4. [x] Replace or remove the existing helper-level tests in `builds/typescript/gateway/project-chat-context.test.ts` that import `starterSnapshotProjectIds` and `buildStarterProjectArtifactSnapshot`.
5. [x] Add runtime boundary tests that prove the gateway no longer contains the starter auto-write path, replacing the deleted helper tests as the durable coverage for this behavior.
6. [x] Remove related audit events if they no longer have a source:
   - `project.artifact_snapshot`
   - `project.artifact_snapshot_after_reply`
7. [x] Run focused gateway tests until they pass.

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Runtime no longer auto-writes starter artifacts | Focused gateway test | `/message` with `projectId` does not mutate `spec.md` / `plan.md` outside assistant/tool writes | Test output |
| Obsolete helper tests resolved | Focused gateway test | No tests import deleted snapshot helper functions; equivalent behavior-level coverage exists | Test output / import search |
| Hardcoded anchors removed | `rg -n "Katie|Owner Conversation Snapshot|Derived Starter Anchors|Starter Plan Snapshot" builds/typescript/gateway/server.ts` | No matches in runtime gateway code | Search output |
| Fan-out removed | `rg -n "starterSnapshotProjectIds|persistStarterProjectArtifactSnapshots" builds/typescript/gateway/server.ts` | No matches unless intentionally retained with tests | Search output |

### Phase 3: Profile Heading Canonicalization

Status: Complete as of 2026-06-28

Goal: make fallback memory initialization match the starter pack and owner-facing language.

Tasks:

1. [x] Update `builds/typescript/memory/init.ts` fallback profile seed from `# Owner Profile` to `# Your Profile`.
2. [x] Update `builds/typescript/memory/init.test.ts` to expect `# Your Profile`.
3. [x] Search for remaining test/runtime expectations of `# Owner Profile`.
4. [x] Run the memory init focused test.

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Fallback seed is canonical | Focused memory init test | Seeded `me/profile.md` contains `# Your Profile` | Test output |
| Old heading removed from seed/test | `rg -n "# Owner Profile" builds/typescript/memory/init.ts builds/typescript/memory/init.test.ts` | No matches | Search output |

### Phase 4: Runtime-Sim Regression Expansion

Status: Complete for this follow-up as of 2026-06-28

Goal: cover the pack-only harness blind spot with live gateway/runtime assertions.

Tasks:

1. [x] Extend existing gateway prompt/context tests.
2. [x] Assert gateway-assembled context does not include forced write timing:
   - write as soon as facts appear
   - do not wait for interview completion before writing
   - update `spec.md` / `plan.md` outside starter-pack gates
3. [x] Assert runtime does not include Finance/Budget/app-scope prohibited phrases:
   - `documents/finance/budget`
   - `Draft 3 app folders`
   - `### Active App Scope`
   - `focused on the app folder`
   - `app source evidence`
   - `app-generated reports`
4. [x] Assert runtime does not mutate starter `spec.md` / `plan.md` through the removed snapshot path outside assistant/tool/write flow.
5. [x] Add search-backed assertions that persona anchors are absent from gateway runtime code.
6. [x] Add a documented runtime-sim extension point for future page-specific guard cleanup: once a page-specific runtime guard is approved for MOVE/DELETE, add its prohibited phrases to this regression before removing it. Do not fail current remaining per-domain guards in this follow-up unless the team has already approved their removal.

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Prompt blind spot covered | Gateway runtime-sim test | Live assembled prompt/context excludes prohibited runtime behavior | Test output |
| Mutation blind spot covered | Gateway runtime-sim test | Chat turn does not auto-write starter artifacts | Test output |
| App-scope cleanup protected | Gateway/runtime test | App-scope prompt text stays absent | Test output |
| Future per-domain cleanup has a gate | Test source review | Runtime-sim test structure can accept page-specific prohibited phrases before broader Phase 3 guard removal | Test source |

### Phase 5: Verification, PR, and Handoff

Status: Complete as of 2026-06-28

Goal: land the blocker fix with clear evidence and leave broader Phase 3 guard migration for a later PR.

Tasks:

1. [x] Run focused gateway tests.
2. [x] Run focused memory init tests.
3. [x] Run `npm run build` from `builds/typescript`.
4. [x] Run broader tests if the known unrelated starter-pack layout failures have been resolved; otherwise document exact failures.
5. [x] Update the work log and execution plan status in the Instructions directory.
6. [x] Include this historical note in the PR description:

   ```markdown
   ## Historical Note

   This removes the starter artifact snapshot path that previously wrote `spec.md` / `plan.md` from gateway runtime code on chat turns. That behavior was removed because starter-pack markdown now owns artifact write timing, and runtime should not mutate owner-facing artifacts outside the approved assistant/tool/write flow.
   ```

7. [x] Create a branch, commit, push, open a PR to `dev`, and merge after review/approval.
8. [x] Sync local `dev` with GitHub `dev`.
9. [x] Delete the merged follow-up feature branch locally and on GitHub after `dev` is synced:

   ```bash
   git branch -d <branch-name>
   git push origin --delete <branch-name>
   ```

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Focused checks pass | Focused Vitest commands | Exit code 0 | Test output |
| Build passes | `cd builds/typescript && npm run build` | Exit code 0 | Build output |
| Repo clean after merge | `git status --short --branch` | Local `dev` matches `origin/dev`; working tree clean | Git output |

## Technical Details

Likely code touch points:

- `builds/typescript/gateway/server.ts`
- `builds/typescript/gateway/project-chat-context.test.ts`
- possible new gateway test file if cleaner than expanding existing tests
- `builds/typescript/memory/init.ts`
- `builds/typescript/memory/init.test.ts`

Likely commands:

```bash
cd builds/typescript
npm run test -- gateway/project-chat-context.test.ts
npm run test -- memory/init.test.ts
npm run build
```

Additional searches:

```bash
rg -n "persistStarterProjectArtifactSnapshots|starterSnapshotProjectIds|buildStarterDerivedAnchors|Owner Conversation Snapshot|Derived Starter Anchors|Starter Plan Snapshot|Katie" builds/typescript/gateway/server.ts
rg -n "# Owner Profile" builds/typescript/memory/init.ts builds/typescript/memory/init.test.ts builds/typescript/memory/starter-pack
```

## Security Considerations

- Do not weaken path scoping, project scoping, file deletion safety, auth, provider config, or secret handling while removing runtime auto-writes.
- Removing the auto-write path should reduce risk because it eliminates hidden mutation of owner files.
- Keep audit logs for explicit write paths; remove only audit events tied to deleted auto-write behavior.

## Risks & Mitigations

| Risk | Mitigation |
|---|---|
| Removing auto-snapshot path reveals generic starter artifacts in edge cases | Starter-pack write framing now owns artifact creation; verify first-run page flows through starter-pack harness/runtime-sim coverage |
| Tests depend on exported helper functions that become obsolete | Prefer testing behavior through public route/runtime surfaces; delete obsolete exports with implementation |
| Full suite remains red for unrelated starter-pack layout lint | Run focused tests and build; document exact unrelated failures if full suite is still red |
| Broad cleanup grows beyond blocker scope | Do not migrate remaining per-domain runtime guards in this PR |

## Human Checkpoints

1. Before implementation: confirm default action is deletion/disablement of the auto-write path, not reclassification as KEEP.
2. After Phase 2: review diff to ensure normal assistant/tool writes still work.
3. After Phase 4: confirm runtime-sim coverage is sufficient before broad Phase 3 per-domain guard cleanup.
4. Before merge: review verification results and any remaining full-suite failures.

## Open Items

- None currently.

## Completion Checklist

- [x] Auto-write behavior test added.
- [x] Starter snapshot auto-write path removed or disabled.
- [x] Persona/scenario-derived runtime anchors removed.
- [x] Cross-project snapshot fan-out removed.
- [x] Helper-level snapshot tests replaced/removed.
- [x] No tests import deleted snapshot helper functions.
- [x] Profile fallback seed changed to `# Your Profile`.
- [x] Profile init test updated.
- [x] Runtime-sim regression covers prompt and mutation blind spots.
- [x] Focused gateway tests pass.
- [x] Focused memory init tests pass.
- [x] TypeScript build passes.
- [x] PR description includes the historical note for deleted snapshot behavior.
- [x] PR opened and merged into GitHub `dev`.
- [x] Local `dev` synced with `origin/dev`.
- [x] Merged follow-up feature branch deleted locally and remotely.