# Runtime / Starter-Pack Boundary Execution Plan

**Status:** In Progress  
**Created:** 2026-06-27  
**Updated:** 2026-06-27  
**Source brief:** `dave-j-runtime-pack-boundary-brief (2).md`  
**Target repo area:** `builds/typescript/gateway/server.ts` and focused gateway prompt/context tests

## Overview

This plan translates the runtime-pack-boundary brief into a scoped cleanup path.

The goal is to remove hidden runtime behavior instructions that compete with the starter pack, while preserving runtime context that the live app still needs: active project state, file lists, uploaded-file metadata, tool/capability context, and safety/scoping constraints.

The guiding rule is:

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

Dave W's starter-pack-only harness result increases confidence that behavior can live in the pack without runtime coaching. The implementation should still verify the live gateway-assembled prompt, because that is where the hidden behavior entered the product.

## Progress Update: 2026-06-27

Phase 1 has been implemented in the repo on branch `dev`.

Completed:

- Removed the `buildProjectChatContext` forced write-as-facts-arrive instruction.
- Removed the `buildProjectChatContext` instruction to write durable state before interview completion.
- Replaced those lines with neutral `spec.md` / `plan.md` state that defers timing/behavior to project markdown.
- Removed the `buildProjectConversationGuard` success-criterion branch that forced this-turn `spec.md` / `plan.md` writes.
- Removed the Finance-specific runtime deferral guard for large worksheets / statement gathering.
- Updated focused gateway tests in `builds/typescript/gateway/project-chat-context.test.ts`.

Verification:

- `cd builds/typescript && npm run test -- gateway/project-chat-context.test.ts` passed.
- `cd builds/typescript && npm run build` passed.
- `cd builds/typescript && npm run test` failed in unrelated starter-pack/memory layout tests:
  - `memory/init.test.ts` expected `# Owner Profile` but current starter profile begins with `# Your Profile`.
  - `memory/starter-pack-draft3-layout.test.ts` reported existing Draft 3 starter-pack lint failures.

Work log:

- See `dave-j-runtime-pack-boundary-work-log.md`.

Phase 2 audit has also been completed as a documentation step.

Audit output:

- See `dave-j-runtime-pack-boundary-runtime-audit.md`.

Audit result:

- `buildProjectChatContext` is mostly KEEP/CODIFY runtime state and scoping.
- `buildProjectConversationGuard` contains some MOVE/CODIFY repeated-question and one-question behavior.
- `buildProjectSpecificTurnGuard` is the main remaining MOVE/MOVE-CODIFY behavior block.
- `buildAppChatContextGuidance` has been reclassified as DELETE because Budget app and child-app support are retired.
- No additional code changes were made during the audit step itself. Follow-up implementation has since removed the Fitness-specific runtime guards and obsolete child-app/app-scope handling.

Product clarification after the audit:

- BrainDrive no longer has a Budget app or child apps.
- Runtime app-scope prompt injection was only for child apps and has no remaining product purpose.
- App-scope prompt assembly has been removed rather than preserved as generic runtime state.

Additional runtime behavior cleanup completed:

- Removed the two Fitness-specific runtime guards from `buildProjectSpecificTurnGuard`.
- Updated focused gateway tests so Fitness phrases no longer appear in runtime guard output.
- `cd builds/typescript && npm run test -- gateway/project-chat-context.test.ts` passed after the change.
- `cd builds/typescript && npm run build` passed after the change.

Child-app cleanup completed:

- Removed gateway app-scope prompt handling and `metadata.app` prompt-audit fields.
- Removed web-client active app path state, child-app sidebar models/navigation, app labels, and app empty-state copy.
- Nested files now remain visible as ordinary project files or advanced project files.
- `cd builds/typescript && npm run test -- gateway/project-chat-context.test.ts` passed.
- `cd builds/typescript && npm --prefix client_web run test -- src/components/layout/sidebar-categorize.test.ts src/components/layout/Sidebar.test.tsx` passed.
- `cd builds/typescript && npm run web:typecheck` passed.
- `cd builds/typescript && npm run web:test` passed.
- `cd builds/typescript && npm run web:build` passed.

## Source Inputs

- `dave-j-runtime-pack-boundary-brief (2).md`
- Dave W's message requesting cleanup of runtime instructions outside the starter pack
- Current gateway prompt assembly in `builds/typescript/gateway/server.ts`
- Starter-pack interview behavior, especially project `AGENT.md`, `run-interview.md`, `run-planning.md`, `spec.md`, and `plan.md`
- Existing gateway/runtime tests, if present

## Scope Guardrails

Do:

- Remove runtime instructions about when to interview, when to write, how to mirror, when to stop asking, and how to run page-specific interview flows.
- Remove the immediate forced-write triggers called out in the brief.
- Remove Finance runtime deferral behavior that tells the model to gather statements or rough estimates instead of following Finance pack behavior.
- Remove child-app runtime context, including Budget app / app-scope prompt injection.
- Keep runtime state/capability context needed by the live app.
- Add regression coverage against gateway-assembled context, not only starter-pack content.
- Keep the first code change small enough to review safely.

Do not:

- Mechanically delete every runtime line that uses imperative wording without classifying it first.
- Rewrite starter-pack behavior as part of the runtime cleanup unless a moved instruction is explicitly needed and approved.
- Remove active project/file-list/upload/tool context.
- Remove security-sensitive or path-scoping constraints unless they are replaced by stronger code enforcement.
- Reintroduce Budget app workflows, child-app workflows, BrainDrive-owned provider secrets, or hosted URLs as part of this work.

## Classification Rule

Every runtime prompt/context line touched by this work should be classified before changing it:

| Classification | Meaning | Action |
|---|---|---|
| KEEP | Runtime state, capability, active selection, file list, or upload metadata | Leave in runtime |
| DELETE | Obsolete, contradictory, duplicated, or harmful behavior | Remove |
| MOVE | Owner-visible behavior that belongs in starter-pack markdown | Move only if the destination pack file is in scope and approved |
| CODIFY | Hard safety guarantee currently expressed as prose | Enforce in code or leave as temporary runtime guard with a follow-up issue |

## Key Decisions

1. The first implementation pass should target the brief's immediate fixes and regression coverage.
2. The larger audit of all runtime behavioral guidance should be a second pass unless the first pass reveals an obvious low-risk deletion.
3. Runtime can still say what is true about the current session, such as active project, visible files, and available project state files. It should not inject child-app scope because child apps are retired.
4. Runtime should not instruct the model to bypass starter-pack gates, including the playback-and-confirm gate before `spec.md` / `plan.md` writes.
5. Finance interview behavior should come from `documents/finance/run-interview.md` and related pack files, not gateway prose.
6. `buildAppChatContextGuidance` is obsolete because it only served child-app prompt context.

## Current State & Remediation

Known runtime issues from the brief and spot-check:

- `buildProjectChatContext` tells the model to update `spec.md` / `plan.md` once usable facts appear.
- `buildProjectChatContext` tells the model not to wait for a perfect interview before writing durable state.
- `buildProjectConversationGuard` tells the model to update `spec.md` / `plan.md` when a success criterion appears, then answer with a no-question summary.
- `buildProjectSpecificTurnGuard` contains page-specific behavioral guidance, including Finance guidance.
- `buildAppChatContextGuidance` contains obsolete child-app scope guidance now that Budget app and child apps are retired.
- Finance runtime guidance can defer owner-facing artifacts by telling the model to gather statements or rough estimates.
- Pack-only harness results can pass while live gateway behavior fails, because the harness does not include runtime prompt assembly.

## Implementation Roadmap

### Phase 1: Immediate Runtime Cleanup

Status: Complete as of 2026-06-27.

Goal: remove the known runtime instructions that directly override starter-pack write timing and Finance behavior.

Tasks:

1. [x] Write or update focused tests that assemble project context and conversation guard output.
2. [x] Assert that project context no longer contains:
   - `Once the owner provides usable facts`
   - `Do not wait for a perfect interview`
   - any equivalent forced-write-as-facts-arrive instruction
3. [x] Assert that success-criterion guard output no longer forces `spec.md` / `plan.md` writes this turn.
4. [x] Assert that Finance runtime guard output no longer contains the gather-statements / small-first-step deferral behavior.
5. [x] Replace the forced-write project context lines with neutral state/capability wording, for example:
   - `The project has spec.md and plan.md files. Follow the project's AGENT.md and run-interview.md for when and how to update them.`
6. [x] Remove or neutralize the success-criterion forced-write behavior in `buildProjectConversationGuard`.
7. [x] Remove the Finance-specific deferral line from `buildProjectSpecificTurnGuard`.
8. [x] Run focused tests.

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Forced write timing removed | Focused gateway/context test | Test fails before change and passes after change | Test output |
| Finance runtime deferral removed | Focused Finance guard test | Runtime guard does not tell model to gather statements or rough estimates as the next step | Test output |
| Type/build health preserved | Relevant repo command, likely `npm run test` or focused Vitest command from `builds/typescript` | Focused gateway test and TypeScript build exit code 0; full suite currently has unrelated starter-pack/memory failures | Command output |

### Phase 2: Runtime Prompt Boundary Audit

Status: Complete as a documentation artifact as of 2026-06-27. Selected recommendations have been implemented: the Fitness-specific runtime guards were removed, and obsolete child-app/app-scope handling was removed. Remaining page-specific runtime behavior still needs review before move/delete decisions.

Goal: classify remaining gateway prompt/context lines and produce a safe migration list.

Tasks:

1. [x] Review these functions line by line:
   - `buildProjectChatContext`
   - `buildProjectConversationGuard`
   - `buildProjectSpecificTurnGuard`
   - `buildAppChatContextGuidance`
2. [x] Classify each behavioral-looking line as KEEP / DELETE / MOVE / CODIFY.
3. [x] Identify any instructions that should move into starter-pack markdown.
4. [x] Identify any safety/scoping constraints that should become code checks instead of prose.
5. [x] Create a concise audit note or checklist before making broad deletions.

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Remaining runtime instructions classified | Audit checklist | Every reviewed line has a disposition | `dave-j-runtime-pack-boundary-runtime-audit.md` |
| No unreviewed broad deletion | Code review | Diff maps back to classification | PR/review notes |

### Phase 3: Behavioral Migration / Deletion

Goal: remove or move remaining runtime behavior without weakening required product behavior.

Tasks:

1. Delete obsolete or contradictory runtime behavior.
2. Move approved owner-visible behavior into the appropriate starter-pack files.
3. Preserve user-customized owner files and avoid overwrites.
4. Add or update tests for moved behavior only where the live runtime previously depended on it.
5. For CODIFY items, either implement code enforcement or create a tracked follow-up if implementation is larger than this cleanup.
6. [x] Remove child-app runtime context:
   - stop calling `buildAppChatContextGuidance`
   - remove `buildAppChatContextGuidance`
   - remove child-app metadata handling tied to prompt context
   - preserve active project/file-list/upload context

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Behavior lives in pack | Search gateway prompt assembly | No page interview strategy remains in runtime unless classified KEEP/CODIFY | Search output |
| Child-app runtime context removed | Search gateway prompt assembly | No `### Active App Scope`, `focused on the app folder`, child app state-file, statements, or reports guidance remains | Search/test output |
| Pack still drives interview | Starter-pack harness plus live runtime-sim check | Both pass the playback/write-gate scenario | Harness output |
| Existing users protected | Review starter-pack/migration changes | No customized owner files overwritten | Code review |

### Phase 4: Live Prompt Regression

Goal: prove the live app does not reintroduce hidden behavior that starter-pack-only tests cannot see.

Tasks:

1. Add a runtime-sim test that assembles the live gateway project context.
2. Fail the test on prohibited runtime behavior phrases or regexes.
3. Include Finance-specific prohibited phrases:
   - `documents/finance/budget`
   - `Draft 3 app folders`
   - Budget workflow language, unless explicitly behind a legacy flag
   - gather-statements deferral behavior
4. Include child-app prohibited phrases:
   - `### Active App Scope`
   - `focused on the app folder`
   - `this app's owner state file`
   - `app source evidence`
   - `app-generated reports`
5. Include write-timing prohibited phrases:
   - write as soon as facts appear
   - do not wait for interview completion before writing
   - update `spec.md` / `plan.md` outside starter-pack gates

Success criteria:

| Criterion | Verification | Expected Result | Evidence |
|---|---|---|---|
| Live prompt boundary covered | Runtime-sim test | Gateway-assembled prompt contains starter-pack behavior plus runtime state/capability only | Test output |
| Pack-only blind spot closed | Regression test review | Test exercises runtime assembly, not only pack files | Test source |

## Technical Details

Likely code areas:

- `builds/typescript/gateway/server.ts`
- Existing gateway tests near `builds/typescript/gateway/` or repo-local Vitest suites
- Starter-pack files only if Phase 3 explicitly moves approved behavior
- Child-app runtime code paths tied only to app prompt context, if unused elsewhere

Likely commands:

```bash
cd builds/typescript
npm run test
npm run build
```

Use focused test commands during iteration if the repo already has a narrower Vitest target for gateway/server tests.

## Security Considerations

- Do not remove runtime constraints that prevent unsafe path behavior, cross-project access, credential exposure, or unauthorized writes unless replacing them with code enforcement.
- Treat provider configuration, owner keys, and gateway URLs as security-sensitive.
- Do not add BrainDrive-owned provider keys to client config.
- Keep runtime state/capability separate from behavior, but do not weaken safety boundaries for the sake of prompt cleanliness.

## Risks & Mitigations

| Risk | Mitigation |
|---|---|
| Removing behavior regresses interview quality | Use Dave W's starter-pack harness plus live runtime-sim regression before broad deletion |
| Runtime state is accidentally removed as "instructions" | Apply KEEP / DELETE / MOVE / CODIFY classification before editing |
| Safety prose is removed without replacement | Classify as CODIFY and enforce in code or track as follow-up |
| Finance cleanup reintroduces Budget app or child-app assumptions | Add prohibited-phrase regression for Finance and app-scope runtime context |
| Broad prompt changes become hard to review | Land immediate forced-write/Finance cleanup first, then audit/migrate remaining behavior |

## Human Checkpoints

1. After Phase 1: confirm the immediate cleanup matches Dave W's requested boundary and does not over-delete runtime context.
2. After Phase 2: review the classification list before moving or deleting larger per-domain guidance.
3. Before Phase 3 starter-pack changes: confirm which moved behaviors, if any, should become owner-visible starter-pack instructions.
4. Before final merge: review regression output from both pack-only harness and live runtime-sim tests.

## Open Items

- Confirm whether `runtime-pack-boundary.md` exists elsewhere and should be used as the Phase 2 audit baseline.
- Confirm where live runtime-sim regression should live if there is already a preferred gateway prompt test harness.
- Decide whether any project-specific guards in `buildProjectSpecificTurnGuard` are still wanted in starter-pack markdown or should simply be deleted.

## Completion Checklist

- [x] Immediate forced-write runtime lines removed or neutralized.
- [x] Finance runtime deferral line removed.
- [x] Focused tests cover removed write-timing and Finance behavior.
- [x] Runtime prompt audit completed for the four named functions.
- [ ] Approved behavior moved to starter-pack markdown or deleted.
- [x] Obsolete child-app runtime context removed.
- [ ] Safety requirements identified and codified or tracked.
- [ ] Live gateway-assembled prompt regression added.
- [x] Relevant focused TypeScript tests/build checks pass.
- [ ] Final handoff reports changed files, checks run, results, and remaining risks.