# Journal Runtime Implementation Plan **Status:** Draft implementation plan for Dave J / runtime PR **Created:** 2026-07-03 **Source handoff:** [`dj-handoff.md`](dj-handoff.md) **Target repo:** `/home/hex/Project/BrainDrive-Test-01` **Target branch:** `dev` unless maintainers direct otherwise ## Goal Wire the V.1 Page Journal pattern into the BrainDrive runtime and sidebar so Fitness and Relationships expose the same owner-facing triad: ```text Your Goals Your Plan Your Journal ``` `journal.md` must be a flat page artifact next to `spec.md` and `plan.md`. `run-journal.md` must be a managed procedure next to `run-interview.md` and `run-planning.md`. The retired nested layout must not be seeded: ```text documents//journal/AGENT.md documents//journal/journal.md ``` The implementation should make fresh provisions seed the correct flat journal files, make the sidebar show `Your Journal`, classify `run-journal.md` with the other run procedures, and prevent stale nested journal templates from producing duplicate or misleading sidebar entries. ## Current Context The handoff and posts establish these decisions: - Journaling is a core BrainDrive fixture, not a child app and not a custom UI. - The first proof pages are Fitness and Relationships. - Finance, Career, New Project, and Your Agent general routing are not part of this runtime pass unless template contract tooling requires placeholder coverage. - Starter-pack prompt/content work is owned separately; this PR owns runtime/interface plumbing and any runtime bugs uncovered by that plumbing. - The live bug from fresh provision is caused by mixed layouts: `JOURNAL_PROJECT_TEMPLATE_FILES` still references stale nested journal files, while the new starter pack uses flat `journal.md`. - The double-Journal sidebar symptom is likely caused by stale nested journal files plus missing sidebar label/grouping support for the flat file. Current repo reconnaissance on `dev` found mixed state: - `builds/typescript/memory/init.ts` has `PROJECT_TEMPLATE_FILES` without journal files and `JOURNAL_PROJECT_TEMPLATE_FILES` still referencing stale nested files. - `builds/typescript/memory/starter-pack/projects/templates/fitness/journal.md` and `relationships/journal.md` exist. - Stale nested files still exist under `builds/typescript/memory/starter-pack/projects/templates/fitness/journal/` and `relationships/journal/`. - `builds/typescript/memory/starter-pack/layout.contract.json` still enumerates only the five pre-journal project template files. - `builds/typescript/client_web/src/components/layout/sidebar-labels.ts` labels `spec.md` and `plan.md`, but not `journal.md`. - `builds/typescript/client_web/src/components/layout/sidebar-categorize.ts` treats `run-interview.md` and `run-planning.md` as managed instruction files, but not `run-journal.md`. - The handoff references `memory/brain-drive-layout.ts` and `memory/update-prompting.ts`; those paths were not present in this checkout. Find the active equivalents before editing. - Date injection exists in `readBootstrapPrompt()`, but the gateway currently builds `systemPrompt` once at server startup and reuses it for `/message`. It reloads on `/agent` overlay save, not on every request. A long-running dev/container instance can therefore send a stale "Today's date is ..." line after midnight, which is a journaling blocker. ## In Scope - Update project template enumeration so fresh provisions seed flat `run-journal.md` and `journal.md`. - Delete stale nested journal starter-pack templates for Fitness and Relationships in the same commit as the seeding fix. - Update starter-pack layout contract and related tests to include journal files where appropriate. - Update runtime fallback/default template generation so any fabricated journal files use the flat layout. - Update sidebar labels so `journal.md` displays as `Your Journal`. - Update sidebar grouping so `journal.md` appears with `Your Goals` and `Your Plan`, not under a generic `YOUR FILES` section. - Update managed-procedure classification so `run-journal.md` is treated like `run-interview.md` and `run-planning.md`. - If managed run documents are displayed in an advanced/procedure section, label the procedure as `Run Journal`; do not display it as an owner-state journal item. - Add or update focused tests for seeding, contract, sidebar labeling/grouping, and stale nested file removal. - Verify date injection is still active in the running bootstrap prompt path and document the result. - Fix date freshness so every assistant model request receives the actual current date for that request, not the server-start date. - Confirm whether one approved turn can write both a parent `spec.md`/`plan.md` update and a matching `journal.md` entry. - Confirm live memory edit behavior for ambiguous replacement targets and either fix it or open a blocking follow-up if it can corrupt owner data. ## Out Of Scope - Building a custom journal UI, dashboard, tracker, database schema, or journal API. - Adding general Your Agent journal routing. - Adding non-proof page journal prompt content beyond placeholders required by existing contract tooling. - Removing or changing Ollama, BYOK OpenRouter, or BrainDrive Models provider choices. - Making BrainDrive Models credits required for Ollama or BYOK OpenRouter. - Adding BrainDrive-owned provider keys to client config. - Reworking the full starter-pack interview/planning prompt content. - Building a full `memory_append` primitive unless the team explicitly promotes it into this PR. - Full runtime retry/provider-blacklist architecture for truncated model responses unless the existing code has a small, localized retry hook. ## User Stories ### DJ-1: Fresh Provision Seeds The Flat Journal Files As a new Fitness or Relationships owner, I want the correct journal files to exist after provision so the page is ready for follow-up sessions. Acceptance: - `documents/fitness/run-journal.md` and `documents/fitness/journal.md` exist. - `documents/relationships/run-journal.md` and `documents/relationships/journal.md` exist. - No `documents//journal/AGENT.md` or `documents//journal/journal.md` is created from starter-pack templates or fallback seeding. ### DJ-2: Sidebar Shows The Owner Artifact Triad As an owner, I want the page sidebar to show `Your Goals`, `Your Plan`, and `Your Journal` together. Acceptance: - `journal.md` is labeled `Your Journal`. - `journal.md` is grouped with `spec.md` and `plan.md`. - A stale `YOUR FILES` section is not created solely for `journal.md`. - Nested stale journal files do not produce duplicate `Journal` entries. ### DJ-3: Run Journal Is A Managed Procedure As a power user or maintainer, I want `run-journal.md` handled like the other run procedures. Acceptance: - `run-journal.md` is hidden or grouped with managed/advanced instructions according to existing sidebar behavior. - If visible, it is labeled as `Run Journal`, not confused with `Your Journal`. - Overlay handling is consistent with other procedures if `run-journal-user.md` is supported. ### DJ-4: Starter-Pack Contract Matches Runtime Seeding As a maintainer, I want the layout contract, seeder, fallback generation, architecture lint, and tests to agree on the same journal file layout. Acceptance: - Contract enumerations and runtime enumerations both reference flat `run-journal.md` and `journal.md`. - Static lint checks no longer require nested journal templates. - Tests fail if the stale nested layout comes back. ### DJ-5: Runtime Does Not Corrupt Journal History As an owner, I want journal writes and corrections to preserve my prior entries. Acceptance: - Ambiguous edit targets are rejected or require disambiguation rather than silently editing the first match. - A correction to a repeated line such as `- Status: captured` cannot splice new content into an old entry. - If this cannot be fixed in this PR, it is documented as a blocking owner-data-safety follow-up before release. ### DJ-6: Runtime Uses The Real Current Date As an owner, I want journal entries to use today's actual date rather than extrapolating from old entries. Acceptance: - The active bootstrap prompt path includes today's date. - A local/dev container check verifies date injection in the deployed runtime path, not only in unit tests. - If date injection is present but the model ignores it, record that as a prompt/adherence issue for the journal harness. ## Implementation Steps ### 1. Preflight 1. Read repo instructions and confirm branch/status: - `git status --short --branch` 2. Inspect current journal state: - `rg -n "JOURNAL_PROJECT_TEMPLATE_FILES|journal/journal|journal/AGENT|run-journal|journal.md" builds/typescript -S` 3. Confirm whether PR #181 or #210 is the current starter-pack PR. The posts mention #181; the handoff says PR #210. Use the actual merged/open PR state as source of truth before resolving conflicts. ### 2. Fix Runtime Seeding Primary target: - `builds/typescript/memory/init.ts` Expected edits: - Change the journal project template list from stale nested files to: ```ts const JOURNAL_PROJECT_TEMPLATE_FILES = ["run-journal.md", "journal.md"] as const; ``` - Update fallback template generation for: - `run-journal.md` - `journal.md` - Remove or rewrite fallback branches for: - `journal/AGENT.md` - `journal/journal.md` - Update any bootstrap instructions that still tell the model to create only five project files, if that prompt is still used for project folder creation. Required paired deletion: - Delete `builds/typescript/memory/starter-pack/projects/templates/fitness/journal/AGENT.md` - Delete `builds/typescript/memory/starter-pack/projects/templates/fitness/journal/journal.md` - Delete `builds/typescript/memory/starter-pack/projects/templates/relationships/journal/AGENT.md` - Delete `builds/typescript/memory/starter-pack/projects/templates/relationships/journal/journal.md` Do not delete flat `fitness/journal.md`, `fitness/run-journal.md`, `relationships/journal.md`, or `relationships/run-journal.md`. ### 3. Update Contract And Architecture Lint Primary targets found in this checkout: - `builds/typescript/memory/starter-pack/layout.contract.json` - `builds/typescript/tools/architecture-lint/draft3-memory-lint.ts` Expected edits: - Add `run-journal.md` and `journal.md` to the project template file lists that are meant to describe pages with journal support. - For V.1, prefer including them for the default/life-area page template lists only if every listed page has valid source content or fallback generation. If not, scope the contract checks to Fitness and Relationships until other page content lands. - Add `run-journal-user.md` to optional overlays only if the runtime already supports owner overlays for managed procedure files or the implementation adds support consistently. - Update lint to validate the flat layout: - `run-journal.md` exists for proof pages. - `journal.md` exists for proof pages. - `run-journal.md` includes the expected `## Preservation Rule` heading. - `journal.md` includes `# Your Journal` and the append marker/default header expected by the pack. - Remove lint expectations for nested `journal/AGENT.md` and `journal/journal.md`. Recommendation: - Keep lint focused on file placement and preservation invariants. Do not validate full journal entry scaffolds. The minimum valid entry is a dated heading plus entry text. ### 4. Update Sidebar Labeling And Grouping Primary targets: - `builds/typescript/client_web/src/components/layout/sidebar-labels.ts` - `builds/typescript/client_web/src/components/layout/sidebar-categorize.ts` - Related sidebar tests in `builds/typescript/client_web/src/components/layout/` Expected edits: - In `sidebarFileLabel`, add: - `relativePath === "journal.md" -> "Your Journal"` - If procedure files are visible, label `run-journal.md` as `Run Journal` consistently with run docs. - In `buildProjectSidebarModel`, add a `journal` slot or otherwise group `journal.md` with goals and plan. - Ensure `run-journal.md` is treated as managed/advanced instruction. - Ensure owner overlays for `run-journal-user.md`, if supported, are treated like other run overlays. Recommendation: - Model shape should explicitly include `journal` if the UI already has explicit `goals` and `plan` slots. That makes the triad testable and avoids accidental sorting under generic files. ### 5. Locate And Update Managed-Procedure Classification The handoff names `memory/brain-drive-layout.ts`, but that file was not present in this checkout. Search for the active classification source instead: ```bash rg -n "PROCEDURE_NAMES|isManagedInstructionFile|run-interview|run-planning|generate-report|owner state|managed procedure" builds/typescript -S ``` Update every active procedure classifier so `run-journal.md` is treated the same as `run-interview.md` and `run-planning.md`. ### 6. Fix Per-Request Date Injection Inspect the active bootstrap prompt path around `readBootstrapPrompt` and runtime initialization. Primary targets found in this checkout: - `builds/typescript/config.ts` - `builds/typescript/gateway/server.ts` - Gateway/config tests that can observe final prompt assembly or model-request messages. Checks: - Unit-level: existing tests for today's date injection still pass. - Runtime-level: start the local/dev server or Docker dev instance and inspect/log the prompt context enough to verify it includes `Today's date is YYYY-MM-DD` for the request date. - Staleness check: simulate or test a server that starts on one date and receives a `/message` request on a later date. The model request must contain the later date. Required fix: - Do not cache the final date-bearing `systemPrompt` across requests. - In the `/message` handler, call `readBootstrapPrompt(runtimeConfig.memory_root)` immediately before `skills.composePromptWithSkills(...)`. - Remove the stale startup cache path for the date-bearing prompt. A cached helper for date-free managed base content is acceptable only if the final `Today's date is ...` line is added per request. - Remove `/agent` overlay-save prompt refresh if the final prompt is rebuilt per request; keep overlay save behavior itself unchanged. - Add a focused gateway or prompt-assembly test that would have failed with the old startup-cached `systemPrompt`. Recommended test shape: - Arrange a startup/bootstrap read that would produce `Today's date is 2026-06-30.`. - Arrange the `/message` request-time bootstrap read to produce `Today's date is 2026-07-03.`. - Assert the final system prompt or provider/model request contains `2026-07-03` and does not use the stale startup date. Recommendation: - If injection exists in code but not the deployed container, treat it as deployment/image freshness, bootstrap path mismatch, or a stale cached startup prompt. - If injection exists and the model still writes the wrong date, do not solve that in seeding/sidebar code. Hand it to the prompt/harness lane as a P-8 adherence issue. ### 7. Confirm Two-Write Approval Behavior Test or inspect whether one approved owner turn can produce: - One parent update to `spec.md` or `plan.md` - One matching entry or change in `journal.md` Recommendation: - If live runtime approvals are per assistant turn and can execute multiple file writes, document the proof. - If approvals are per tool call and require two separate approvals, flag this back to Dave/DW because the journal instructions assume one approval covers both writes. ### 8. Confirm Ambiguous Edit Rejection Inspect the file-edit memory tool behavior for find/replace targets that match more than once. Expected owner-data-safety behavior: - If a find string appears N times, the edit must fail with an error naming the count and asking for more context. Recommendation: - If the tool silently edits the first match, fix it if localized. - If the fix touches shared memory-tool semantics broadly, open a blocking follow-up issue and avoid claiming journal release readiness. ### 9. Optional Runtime Resilience Item The handoff reports GLM providers can return 200 responses with empty or truncated content mid-tool-loop. Recommendation: - Look for an existing retry hook for empty/no-tool-call completions. - If a small localized retry can be added safely, implement it with tests. - If it requires provider-routing architecture, document a follow-up. Do not bury this inside sidebar/seeding changes. ## Open Questions And Recommendations ### Q1. Should contract lists include non-proof pages now? Recommendation: include journal files only where the repo has valid source content or fallback generation. For this first runtime PR, Fitness and Relationships are the proof pages. If existing contract tooling requires life-area-wide files, use generic substituted copies only with DW/Dave approval. ### Q2. Which PR number is the starter-pack source of truth? Recommendation: verify before implementation. User post says PR #181; handoff says PR #210. Do not base runtime edits on a stale PR number. ### Q3. Should `journal.md` be seeded at initial provision or at first plan write? Recommendation: seed at initial page setup for default pages. If page folders are only materialized at first interview completion, seed at that first durable materialization point. Do not wait until the first journal entry. ### Q4. Should `run-journal-user.md` ship now? Recommendation: add overlay support only if it follows the existing run overlay pattern with minimal changes. Otherwise leave it out of the first PR and document it as follow-up symmetry work. ### Q5. Should a real append primitive be added now? Recommendation: not in this runtime/sidebar PR unless already mostly implemented. Keep the append-marker workaround from the pack and open a separate memory-tool enhancement for `memory_append`. ### Q6. Is truncated/empty model retry blocking? Recommendation: owner-data fabrication risk is real, but the implementation size is unknown. Do reconnaissance in this PR. Implement only if localized; otherwise file a high-priority follow-up and call it out in release risk. ## Verification Plan Run focused checks first, then broader checks before handoff. Focused checks: ```bash cd builds/typescript npm run test -- memory/init.test.ts npm run web:test -- sidebar ``` If exact test filters differ in this repo, use the nearest Vitest file filters and report the actual commands. Broader checks: ```bash cd builds/typescript npm run test npm run web:typecheck npm run web:test ``` If starter-pack lint has a separate script, run it too. If no script exists, run the direct architecture-lint command used by the repo's package scripts or document that none was found. Manual/file-tree checks: - Fresh seeded memory contains flat `documents/fitness/journal.md`. - Fresh seeded memory contains flat `documents/fitness/run-journal.md`. - Fresh seeded memory contains flat `documents/relationships/journal.md`. - Fresh seeded memory contains flat `documents/relationships/run-journal.md`. - No nested `documents/fitness/journal/` or `documents/relationships/journal/` folder is created by default seeding. - Sidebar model test shows `Your Goals`, `Your Plan`, `Your Journal`. - Managed procedure classification hides or groups `run-journal.md` with the other run docs. ## Handoff Requirements The final PR summary should report: - Files changed. - Tests run and exact results. - Whether stale nested templates were removed. - Whether fresh provision creates flat journal files. - Whether sidebar shows `Your Journal`. - Whether `run-journal.md` is managed/advanced, hidden, or shown as `Run Journal`. - Date injection verification result. - Two-write approval verification result. - Ambiguous edit behavior result. - Any deferred follow-up issues with release risk.