# Spec: Journal Go-Live Activation For Finance, Career, And New Project > **Purpose:** Builder-facing BrainDrive product/engineering spec for turning on page journaling for Finance, Career, and New Project after the remaining-page starter-pack templates land. > **Generated from:** PR #217 description, PR #215 sequencing note, local repo reconnaissance on `dev`, and the 2026-07-05 Codex session. > **Target repo:** `/home/hex/Project/BrainDrive-Test-01` > **Target branch:** `dev` ## Overview ### What We're Building Activate the already-authored page journal templates for the three remaining page domains: - Finance - Career - New Project The starter-pack template PR adds `run-journal.md`, `journal.md`, `AGENT.md` journal routing, and `run-planning.md` handoff text for those pages. That PR is intentionally inert until runtime and contract journal id lists include the three page ids. This spec covers the deliberate go-live switch and the cleanup needed so fallback-generated journals match the D288 newest-first format. ### Why It Matters Journaling is the repeat loop after a page's first interview, goals, and plan. Fitness and Relationships already have the journal pattern. The remaining owner-facing pages need the same post-plan follow-up behavior before the journaling release is considered complete. The risk is not the template merge itself. PR #217 says merging changes nothing live. The risk begins when the page ids are added to runtime and contract enumerations: fresh provisions will start seeding journal files for Finance, Career, and New Project, so the seeding, contract, fallback content, sidebar, and verification evidence must agree. ### Target Audience And Stakeholders | Audience | Role / Need | |---|---| | BrainDrive owners using Finance, Career, or New Project | Get `Your Journal` as an owner-editable follow-up history after `Your Goals` and `Your Plan` exist. | | Builder / implementation owner | Make the narrow go-live activation changes without changing unrelated journaling behavior. | | QA / harness audience | Verify fresh provisions seed the expected files and that the page journal contract is consistent. | | Operator / maintainer | Know whether journaling is live for all page domains and what evidence supports the release. | ### Success Definition When this work is complete: 1. Freshly provisioned BrainDrive instances seed `journal.md` and `run-journal.md` for Finance, Career, and New Project. 2. The starter-pack layout contract and architecture lint agree that those three pages are page-journal projects. 3. The fallback-generated `journal.md` and `run-journal.md` content uses the D288 newest-first anchor-line format and no longer seeds bare "No entries yet" journal content. 4. Existing Fitness and Relationships journaling behavior remains intact. 5. The release owner has fresh-provision evidence showing at least one of the three newly activated pages has `journal.md`, `run-journal.md`, and sidebar access to `Your Journal`. The work is not successful if: 1. A fresh provision still omits journal files for Finance, Career, or New Project. 2. Any page gets a malformed journal fallback with no insertion anchor line. 3. Activation overwrites or mutates customized existing owner files without explicit approval. 4. The repo contract and runtime seeding enumerate different page-journal projects. 5. The sidebar exposes duplicate or misleading journal items after activation. ### Definition Of Done Go-live is done when: 1. PR #215 and PR #217 are merged to `dev` with normal merge commits, not squash merges. 2. `finance`, `career`, and `new-project` are added everywhere page-journal project ids are enumerated. 3. Focused tests are updated and passing. 4. A fresh dev provision proves the new pages seed `journal.md` and `run-journal.md`. 5. A manual sidebar check confirms `journal.md` appears as `Your Journal` and `run-journal.md` is not confused with owner state. Explicitly not required for this go-live: - General Your Agent journal routing. - A custom journal UI, dashboard, tracker, database schema, or journal API. - A new append-only memory primitive. - Full model retry/provider blacklisting for empty or truncated completions. - New offline journal harness scenarios for these pages, beyond the author's already reported verification and release-owner review needs. ## Product Behavior ### User / System Experience After activation, Finance, Career, and New Project behave like Fitness and Relationships: - The first page conversation still creates `Your Goals` (`spec.md`) and `Your Plan` (`plan.md`). - After the plan exists, owner follow-up updates, blockers, progress notes, and next-step help route through `run-journal.md`. - `journal.md` is the owner-facing `Your Journal` artifact, flat beside `spec.md` and `plan.md`. - The journal is available but never mandatory. The system must not prescribe daily logging or require the owner to journal during the first interview. ### Primary Flows 1. Fresh provisioning: - Runtime seeds page files for Finance, Career, Fitness, Relationships, and New Project. - For all page-journal projects, runtime also seeds `run-journal.md` and `journal.md`. - The new pages have the authored PR #217 templates, not fallback stubs. 2. Page sidebar: - Owner opens Finance, Career, or New Project after files are seeded. - Sidebar shows `Your Goals`, `Your Plan`, and `Your Journal` as the owner-facing triad. - `run-journal.md` remains managed procedure content, not an owner-state file. 3. Fallback generation: - If starter-pack template content is missing and runtime creates fallback journal files, the fallback journal includes the proper heading and anchor-line insertion comment. - Fallback `run-journal.md` describes newest-first insertion, not generic append-at-bottom behavior. 4. Existing user preservation: - Existing owners with seeded project files are not silently overwritten. - Dogfood or release-test instances that need the new files are fresh-provisioned or deliberately patched by an operator. ### UX / Trust Bar - The owner sees the journal as their editable history, not as a hidden log or required tracker. - The model must not claim it wrote to the journal unless file writes actually happened and were verified in the active flow. - Recovery and correction rules must preserve existing owner content. - The sidebar must not show two generic "Journal" entries for the same page. ## User Stories ### US-1: Activate Remaining Page Journal Seeding - **Confirmed** As a new BrainDrive owner, I want Finance, Career, and New Project to include journaling files after provisioning so that follow-up sessions work on every owner-facing page. **Source:** PR #217 go-live checklist. **Acceptance Criteria:** ```gherkin Given a fresh provision after the go-live activation When the runtime seeds default page projects Then documents/finance/run-journal.md exists And documents/finance/journal.md exists And documents/career/run-journal.md exists And documents/career/journal.md exists And documents/new-project/run-journal.md exists And documents/new-project/journal.md exists ``` ```gherkin Given the starter-pack templates from PR #217 are available When Finance, Career, or New Project is seeded Then the seeded journal files come from the page-specific template files And they are not generic fallback stubs unless the template source is unavailable ``` ### US-2: Keep Runtime And Contract In Sync - **Confirmed** As a maintainer, I want the runtime seeder, layout contract, lint, and tests to agree on page-journal project ids so that future changes cannot silently split behavior. **Source:** PR #217 go-live checklist and current repo state. **Acceptance Criteria:** ```gherkin Given page journaling is live for Finance, Career, Fitness, Relationships, and New Project When layout contract and architecture lint run Then each active page-journal id is present in the contract And each active page-journal id is present in runtime seeding And each active page-journal id is present in architecture lint checks ``` ### US-3: Repair Fallback Journal Defaults - **Confirmed** As an owner, I want fallback-created journals to use the same safe newest-first format as authored templates so that owner history is not malformed if a fallback path fires. **Source:** PR #217 cleanup item. **Acceptance Criteria:** ```gherkin Given runtime must create a fallback journal.md When the fallback content is generated Then the file contains a "# Your [Page] Journal" style owner-facing heading And it contains the exact insertion anchor line used by authored templates And it does not contain the old bare "No entries yet." body ``` ```gherkin Given runtime must create a fallback run-journal.md When the fallback content is generated Then the preservation rule describes inserting new entries directly below the anchor line, newest first And it does not instruct the model to append entries at the bottom ``` ### US-4: Verify The Go-Live Surface - **Confirmed** As the release owner, I want fresh-provision evidence before release so that the go-live switch is proven in the real runtime path, not only in static files. **Source:** PR #217 go-live checklist. **Acceptance Criteria:** ```gherkin Given a fresh dev instance after activation When at least one of Finance, Career, or New Project is inspected Then journal.md and run-journal.md are present And journal.md appears as Your Journal in the sidebar And no duplicate generic Journal item appears for the same page ``` ## Requirements ### Functional Requirements - [ ] Add `"finance"`, `"career"`, and `"new-project"` to `PAGE_JOURNAL_PROJECT_IDS` in `builds/typescript/memory/init.ts`. - [ ] Add the same three ids to `page_journal_project_ids` in `builds/typescript/memory/starter-pack/layout.contract.json`. - [ ] Add the same three ids to `PAGE_JOURNAL_PROJECT_IDS` in `builds/typescript/tools/architecture-lint/draft3-memory-lint.ts`. - [ ] Update focused tests that currently assert Finance, Career, and New Project do not seed `run-journal.md`. - [ ] Verify `JOURNAL_PROJECT_TEMPLATE_FILES` remains `["run-journal.md", "journal.md"]`. - [ ] Confirm `JOURNAL_PROJECT_TEMPLATE_FILES` and sidebar handling are generic and do not need per-page special cases. - [ ] Fix fallback `journal.md` content in `builds/typescript/memory/init.ts` so it uses the D288 anchor-line header. - [ ] Fix fallback `run-journal.md` content in `builds/typescript/memory/init.ts` so it says newest-first insertion, not generic append. - [ ] Fresh-provision a dev instance and inspect seeded files for at least one newly activated page. ### AI / Model / Tool Behavior - [ ] The page `AGENT.md` files from PR #217 route follow-up sessions to `run-journal.md` only after `spec.md` and `plan.md` exist. - [ ] The journal remains owner-driven follow-up, not mandatory daily logging. - [ ] Journal writes must preserve owner history, use newest-first insertion, and avoid whole-file rewrites. - [ ] Parent `spec.md` or `plan.md` changes remain owner-approved and paired with a journal record when applicable. ### Data, Memory, And Artifact Contracts | Data / Artifact | Source | Owner | Read/Write Rules | Retention / Migration | |---|---|---|---|---| | `documents//journal.md` | Starter-pack template or fallback | Owner state | Insert-only newest-first journal entries; targeted corrections only | Preserve existing owner edits; do not overwrite customized files | | `documents//run-journal.md` | Starter-pack template or fallback | Managed procedure | Read by model for follow-up behavior; owner overlay optional only if supported | Seed on fresh provision for page-journal projects | | `PAGE_JOURNAL_PROJECT_IDS` in `memory/init.ts` | Runtime config | Runtime seeder | Controls which project templates include journal files | Must match contract/lint/test expectations | | `page_journal_project_ids` in `layout.contract.json` | Starter-pack contract | Maintainers | Declares page-journal pages | Must match runtime/lint/test expectations | | `PAGE_JOURNAL_PROJECT_IDS` in architecture lint | Static lint | Maintainers | Enforces journal template presence and stale nested layout absence | Must match runtime/contract expectations | ### BrainDrive Page Context And Write Placement | Information | Primary Home | |---|---| | Stable cross-project owner facts, values, preferences, life context | `me/profile.md` | | Page goals, current state, constraints, assumptions, success criteria | Page `spec.md` | | Ordered next steps, owner decisions, timing, status | Page `plan.md` | | Follow-up entries, observations, progress, blockers, reflections | Page `journal.md` | | How to run follow-up journal sessions | Page `run-journal.md` | Journaling is a built-in page fixture. It is not an in-product app, hidden tracker, dashboard, passive ingestion system, or external tool. ### Interface / UX Requirements - [ ] `journal.md` displays as `Your Journal`. - [ ] `journal.md` is grouped with `Your Goals` and `Your Plan`. - [ ] `run-journal.md` does not display as owner journal state. - [ ] If `run-journal.md` is visible in advanced files, its label must not create duplicate owner-facing "Journal" confusion. - [ ] If #213 sidebar handling is already generic, no sidebar code change is required. Verification still must prove the behavior for one newly activated page. ### Observability / Evidence Requirements - [ ] Test output from focused memory seeding and sidebar tests. - [ ] Architecture lint output or equivalent command output proving the starter-pack contract is consistent. - [ ] Fresh-provision evidence listing the seeded files for at least one of Finance, Career, or New Project. - [ ] Manual or screenshot evidence showing `Your Journal` in sidebar for one newly activated page, if practical. ## Scope ### Work Type - [x] **V1** - First complete release activation for all page-journal domains. - [x] **Built-in feature** - Journaling. - [x] **BrainDrive core/foundation** - Memory seeding and starter-pack contract. - [x] **Interface / shell** - Sidebar verification, code only if generic handling is missing. - [x] **Testing / harness / factory** - Focused unit/integration verification and fresh-provision check. ### Included - Runtime page-journal id activation for Finance, Career, and New Project. - Starter-pack contract id activation for Finance, Career, and New Project. - Architecture lint id activation for Finance, Career, and New Project. - Test expectation updates for newly seeded journal files. - Fallback journal content cleanup. - Fresh-provision verification. ### Explicitly Excluded - Merging PR #217 itself, except as a precondition for this go-live. - Re-authoring the PR #217 template text. - Your Agent journal routing. - New journal UI or custom journal editor. - New model retry/provider exclusion behavior for empty/truncated completions. - Broad provider, auth, installer, or deployment changes. - Existing-owner automatic migration that overwrites customized files. ### Future Versions / Deepenings - General Your Agent routing into page journals. - Optional `run-journal-user.md` overlay support if product decides managed journal procedures need owner overlays. - A dedicated append operation if memory tool risk justifies it. - Broader runtime retry handling for empty or truncated model completions. ## Invariants And Edge Cases ### Properties That Must Always Hold - [ ] Runtime seeding, contract, lint, and tests enumerate the same page-journal project ids. - [ ] `journal.md` is flat under `documents//`, not nested under `documents//journal/`. - [ ] `run-journal.md` is a managed procedure, not owner state. - [ ] `journal.md` is owner state and must preserve owner edits. - [ ] New journal entries are newest-first below the anchor comment. - [ ] Existing Fitness and Relationships journal behavior does not regress. - [ ] Existing owners are not silently overwritten by activation. ### Edge Cases To Test - Fresh provision after PR #217 is merged and ids are activated. - Starter-pack template missing for a page, forcing fallback generation. - Existing owner memory already has customized `journal.md`. - Sidebar receives both flat journal files and stale nested journal files. - Contract includes a page id whose template files are missing. - Tests run before PR #217 is merged, making activation fail because templates are absent. ### Failure Modes | Scenario | Expected Behavior | |---|---| | PR #217 is not merged before activation | Stop. Do not activate ids until page-specific template files exist. | | PR #215 is not merged before journaling release | Stop or explicitly accept release risk. PR #217 says both should land before the journaling release. | | Fallback journal generation fires | Create a D288-compatible `journal.md` with the anchor line; do not seed "No entries yet." | | Runtime and contract ids differ | Tests or lint fail; fix before release. | | Sidebar shows duplicate journal items | Treat as release blocker for go-live surface verification. | | Existing owner has customized journal files | Preserve files; use fresh provision or explicit manual patch for dogfood activation. | ## Technical Context ### Existing System Context Current local `dev` state before PR #217 merge: - `builds/typescript/memory/init.ts` - `JOURNAL_PROJECT_TEMPLATE_FILES` is already flat: `["run-journal.md", "journal.md"]`. - `PAGE_JOURNAL_PROJECT_IDS` currently includes only `fitness` and `relationships`. - Fallback `run-journal.md` still uses generic "Append new entries" wording. - Fallback `journal.md` still seeds a bare `# Your Journal` plus `No entries yet.` - `builds/typescript/memory/starter-pack/layout.contract.json` - `page_journal_project_ids` currently includes only `fitness` and `relationships`. - `page_journal_project_template_files` already lists `run-journal.md` and `journal.md`. - `builds/typescript/tools/architecture-lint/draft3-memory-lint.ts` - `PAGE_JOURNAL_PROJECT_IDS` currently includes only `fitness` and `relationships`. - Journal lint checks are already oriented to flat `run-journal.md` and `journal.md`. - `builds/typescript/memory/init.test.ts` - Currently asserts Finance, Career, and New Project reject reads for `run-journal.md`. - These expectations must flip after activation. - Sidebar tests already include generic journal behavior for Finance in local `dev`, but fresh-provision sidebar behavior still needs verification after ids are activated. ### Related PRs - PR #215: `Starter pack: journal calibration tunes (person-first tell, coach closes, check-in phrasing)` - Should land before journaling release. - Mergeable at time of triage. - PR #217: `Starter pack: journaling for Finance, Career, and New Project pages (T-749)` - Adds the remaining page template files. - Merge itself is inert. - Go-live begins only when ids are activated. ### Integration Points - Memory seeding: `builds/typescript/memory/init.ts` - Starter-pack contract: `builds/typescript/memory/starter-pack/layout.contract.json` - Starter-pack templates: `builds/typescript/memory/starter-pack/projects/templates/{finance,career,new-project}/` - Architecture lint: `builds/typescript/tools/architecture-lint/draft3-memory-lint.ts` - Memory seeding tests: `builds/typescript/memory/init.test.ts` - Sidebar behavior and tests: - `builds/typescript/client_web/src/components/layout/sidebar-labels.ts` - `builds/typescript/client_web/src/components/layout/sidebar-categorize.ts` - `builds/typescript/client_web/src/components/layout/sidebar-categorize.test.ts` - `builds/typescript/client_web/src/components/layout/Sidebar.test.tsx` ### Hard Constraints - Do not overwrite existing owner memory without explicit approval. - Do not introduce a nested `journal/` layout. - Do not convert journaling into an app, tracker, dashboard, or database feature. - Do not put BrainDrive-owned provider keys or secrets anywhere in client config. - Do not remove Ollama or BYOK OpenRouter provider choices. - Activation should be a small, reviewable diff. ### Build Workflow Inputs Candidate focused commands: ```bash cd builds/typescript npm run test -- memory/init.test.ts npm run web:test -- src/components/layout/sidebar-categorize.test.ts src/components/layout/Sidebar.test.tsx ``` If the repo test runner does not support direct file arguments through those npm scripts, use the existing package scripts or Vitest invocation pattern already used in the repo. Candidate broader checks before handoff: ```bash cd builds/typescript npm run test npm run web:test npm run web:typecheck ``` Fresh-provision evidence should use the repo's current dev provisioning path. If Docker is used: ```bash ./scripts/start.sh dev ``` Then inspect the seeded memory files in the dev instance and sidebar for one newly activated page. ## Test Strategy ### Test Levels Required - [x] **Unit / integration** - Memory seeding and fallback content tests. - [x] **Static contract / lint** - Starter-pack contract and architecture lint. - [x] **Frontend unit** - Sidebar label/grouping tests if behavior changes or needs regression protection. - [x] **E2E / workflow** - Fresh-provision dev instance verification. - [x] **Human review** - Confirm release owner accepts the go-live evidence. ### Verification Approach - **Agent self-verification:** Read changed files and confirm ids match across runtime, contract, lint, and tests. - **Automated verification:** Run focused tests for memory seeding and sidebar. Run broader `npm run test`, `npm run web:test`, and `npm run web:typecheck` if practical. - **Harness verification:** Rely on PR #217 author's reported offline journal board verification for prompt behavior unless release owner asks for additional harness runs. - **Human verification:** Fresh-provision a dev instance and inspect one of Finance, Career, or New Project for file seeding and sidebar placement. ### Acceptance Evidence - [ ] Test output showing `init.test.ts` passes with Finance, Career, and New Project journal seeding expectations. - [ ] Test or lint output showing the layout contract accepts the expanded `page_journal_project_ids`. - [ ] Sidebar test output or manual screenshot showing `Your Journal` for one newly activated page. - [ ] File listing from fresh provision showing `journal.md` and `run-journal.md` for at least one newly activated page. ### Baseline / Regression Impact - Fitness and Relationships remain page-journal projects. - Finance, Career, and New Project become page-journal projects. - Your Agent remains excluded from page-journal activation. - Existing interview and planning behavior must remain unchanged before `spec.md` and `plan.md` exist. ## Security, Privacy, And Trust Considerations ### Risk Level - [x] **Medium** - Touches owner memory files and model/tool instructions, but does not add new network surfaces, secrets, auth, or external APIs. ### Threat / Trust Assessment - **User input:** Journal entries come from owner conversation and must be owner-editable. - **Code execution:** No new code execution capability. - **Data sensitivity:** Journal files may contain sensitive owner progress, blockers, finances, career details, or project context. - **Network surface:** No new network surface. - **Model/tool behavior:** Model must preserve owner history, use targeted edits, and avoid fabricated write success. - **Blast radius:** Bad seeding or fallback content can create malformed journal history for new owners. - **Owner trust:** Owner must retain control over journal content and never be forced into mandatory logging. ### Required Mitigations - [ ] Preserve existing owner files. - [ ] Keep all journal files owner-inspectable markdown. - [ ] Verify fallback content includes the safe insertion anchor. - [ ] Keep activation scoped to page ids and fallback cleanup. ## Explicit Boundaries ### Do Not Modify Unless Needed For This Spec - [ ] Provider configuration and secrets. - [ ] Auth, signup, billing, gateway security, or hosted deployment config. - [ ] Installer/release packaging. - [ ] Unrelated starter-pack prompt content. - [ ] Existing owner memory outside deliberate fresh-provision or operator-approved patching. ### Do Not Introduce - [ ] A custom journal database or schema. - [ ] A journal app folder. - [ ] A hidden passive ingestion feed. - [ ] A required daily logging workflow. - [ ] A broad refactor of memory seeding or sidebar architecture. ### Out Of Scope Even If Related - [ ] Full empty/truncated model completion retry behavior. - [ ] Ambiguous memory edit rejection, unless release owner promotes it into this go-live gate. - [ ] External tool calling. - [ ] To-do list integration. - [ ] General Your Agent routing. ## Open Questions - [ ] Has PR #215 landed on `dev` before the journaling release? - [ ] Has PR #217 landed on `dev` before activating the ids? - [ ] Should fallback cleanup be in the same activation PR, as PR #217 recommends, or can it be a preceding prerequisite PR? - [ ] What exact fresh-provision environment should be used for release evidence: local dev, Docker dev, or another dogfood instance? - [ ] Does the release owner require additional offline harness runs after activation, or is PR #217's reported board verification sufficient? - [ ] Should existing dogfood instances be wiped/re-provisioned or manually patched to receive the new page journal files? ## Changelog | Date | Change | Reason | Source | Decision | |---|---|---|---|---| | 2026-07-05 | Initial go-live activation spec created | Convert PR #217 go-live checklist into builder-facing spec | Codex session + PR #217 description | Pending review | ## Conversation References | Date | Source | Topics Discussed | Link | |---|---|---|---| | 2026-07-05 | Codex session in `/home/hex/Project/BrainDrive-Test-01` | PR #217 merge readiness, inert merge vs go-live switch, activation checklist | Local chat | | 2026-07-05 | GitHub PR #217 | Remaining page journal templates and go-live checklist | https://github.com/BrainDriveAI/BrainDrive/pull/217 | | 2026-07-05 | GitHub PR #215 | Journal calibration tunes that should land before journaling release | https://github.com/BrainDriveAI/BrainDrive/pull/215 | ## Approval - [ ] Reviewed by: _______________ - [ ] Date: _______________ - [ ] Ready for test plan / build plan: [ ]