# Build Plan: Page Journal (shared pattern + Fitness + Relationship)

**Status:** Not Started
**Created:** 2026-06-30
**Updated:** 2026-06-30
**Repository:** `~/BrainDrive` (live pack: `builds/typescript/memory/starter-pack/`)
**Spec:** [`spec.md`](spec.md) (+ [`../../fitness/fitness-journal/spec.md`](../../fitness/fitness-journal/spec.md), [`../../relationships/relationship-journal/spec.md`](../../relationships/relationship-journal/spec.md))
**Test Plan:** [`test-plan.md`](test-plan.md) (+ the two page deltas)

---

## Overview

Build the V.1 journaling loop — the "Repeat" half of every page (interview → spec → plan → **journal**) — as a **text-first** starter-pack feature: a Markdown journal managed by BrainDrive's existing file-ops memory tools and driven by authored instructions. No new code, no UI, no database. This first build proves the shared page-journal pattern on the two named proof pages, **Fitness** and **Relationships**.

See `spec.md` for behavior and `test-plan.md` for release gates, scenarios, and evidence.

---

## Source Inputs

| Input | Location | Status | Notes |
|-------|----------|--------|-------|
| Shared spec | `foundation/page-journal/spec.md` | Accepted 2026-06-30 | Owns PJ-1…PJ-7, recovery, memory-arch, routing |
| Fitness delta spec | `fitness/fitness-journal/spec.md` | Accepted 2026-06-30 | Health boundaries, no invented metrics, no tracker |
| Relationship delta spec | `relationships/relationship-journal/spec.md` | Accepted 2026-06-30 | Privacy, professional-care boundary language, no CRM |
| Test plans | 3 files (shared + deltas) | Spec-level draft | Gates G-1…G-6, FG-1…FG-3, RG-1…RG-4 |
| Memory architecture | `foundation/memory-architecture/memory-architecture.md` | Reviewed | Journal = a **journal folder** (`documents/<page>/journal/journal.md`) — the app-folder mechanism in memory-arch terms; one of the two retained built-ins (D257/D265) |
| Live starter pack | `~/BrainDrive/builds/typescript/memory/starter-pack/` | Reviewed | Page templates: `AGENT.md`, `spec.md`, `plan.md`, `run-interview.md`, `run-planning.md`. **No `run-journal.md` / journal folder yet**; pages currently carry a "do not require daily journaling" boundary |
| Harness | `projects/active/foundation/starter-pack-testing-harness/` (offline lane, ours) + canonical `braindrive-test-harness` (DJ) | Reviewed | Drives the alignment session only; journal mode = **T-731** (ours, Phase 0a). Runtime enablement = **T-732** (DJ, Phase 0b) |

---

## Scope Guardrails

### In Scope
- Shared page-journal pattern: journal app-folder scaffold, `run-journal.md` follow-up session, entry format, default-file + recovery rules, parent spec/plan adjustment rule, memory-arch placement + preservation rule, PJ-1 plan→journal handoff.
- Fitness Journal delta (health boundaries, no invented metrics, no tracker; full pattern-review dimensions).
- Relationship Journal delta (privacy/agency, professional-care boundary language verbatim, no CRM/mind-reading/manipulation).
- The canonical **shared journal instruction source**, instantiated on the two proof pages so Finance/Career/New-Project can adopt it later.

### Out of Scope
- **To-do list / Journal↔To-Do handoff** — V.1.1 ([[braindrive-repo]] D272). Concrete commitments stay in the entry's `Follow-up → Proposed task` field.
- **Your Agent general-journal router / entry-point routing (spec Success #9)** — deferred (test-plan O-6); the router surface is not built here.
- **Finance / Career / New Project journals** — follow once the loop holds.
- Custom journal UI, dashboard, tracker, passive ingestion, external tools, budgeting.

### Change Control
If the build reveals a new requirement or gate, update `spec.md` / `test-plan.md` before expanding this plan.

---

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Implementation medium | **Text-first: Markdown journal via existing file-ops tools + authored starter-pack instructions. No code/UI/DB.** | Spec Universal Contract (journal is a normal Markdown artifact; no custom UI) + text-first rule + D257/D265 (app-folder mechanism reserved for journaling) |
| Journal location | **Journal folder `documents/<page>/journal/journal.md`**; `documents/<page>/journal/AGENT.md` carries journal instructions + the preservation rule | Memory-arch app-folder mechanism (folder = bare noun, state artifact = same name); instructions live in the folder, not owner state |
| Journal creation timing | **Seed an empty `journal.md` at page setup** (recommended) — so "Your Journal" sits alongside "Your Goals"/"Your Plan" from the start; the PJ-1 handoff is the active prompt; recovery rule backstops | The sidebar triad is orientation — it tells the owner the page is for goals → plan → journaling. Spec: "create it before the owner needs it." DJ confirms the runtime seed point (T-732) |
| Owner-facing label | The journal artifact is presented to the owner as **"Your Journal"**, parallel to **"Your Goals"** (`spec.md`) and **"Your Plan"** (`plan.md`) | The sidebar triad only reads as one coherent thing if the naming is parallel; per spec Universal Contract. Applies to every page's `AGENT.md` owner-facing copy |
| Shared vs per-page | **Copy-per-page for V.1** (recommended) — one canonical source in the spec, instantiated per page with deltas; the pack has no runtime include | Inline instructions keep pages plain-English + owner-editable and match `run-interview.md`/`run-planning.md`. Revisit a shared include when journaling spans all six pages — a pack-mechanism decision, not a journaling one (T-732) |
| PJ-1 handoff seam | **End of `run-planning.md`** (alignment-session completion): state next step = execute + journal; ensure `journal.md` exists | The handoff fires where the page finishes spec+plan; does not re-spec the interview |
| Known context (read first) | Journal session reads **profile + page `spec.md`/`plan.md`** before acting (BP-1) | Coach behaves like it remembers; no cold re-asking |
| Write placement | Entry → `journal.md`; agreed parent change → page `spec.md`/`plan.md` (approved); stable fact → `me/profile.md` (confirmed); commitment → entry `Follow-up → Proposed task` (V.1) | Each fact lands at the artifact that owns it (BP-2) |
| Forced-journaling boundary | **Preserve** the existing "do not require daily journaling/logging" stance; the journal is owner-driven follow-up, available but never mandatory | The journal is not a tracker (spec); existing boundary stays true and must not be contradicted |
| `AGENT.md` journal wording | **Minimal** — only "a journal exists after the plan, owner-driven, not mandatory." The actual journal procedure lives in `run-journal.md` | `AGENT.md` is loaded *during* the first conversation, so any journal wording there can shift interview behavior. Keep the interview-path surface tiny — it is the **only** high-risk starter-pack edit |

---

## Current State & Remediation

| Current Behavior / Gap | Required Target | Source | Build Task |
|------------------------|-----------------|--------|------------|
| Live pages say "do not require daily journaling/logging" and "do not prescribe a generic … journal …" | Keep no-forced-tracker stance **and** add the owner-driven journal as an available follow-up surface | fitness/relationships `AGENT.md`, `run-*` | P1-T5 (reconcile wording), P2-T4 |
| No `run-journal.md`, no `documents/<page>/journal/` folder, no `journal.md` default | Author the shared follow-up session + journal folder scaffold + default file | live pack | P1-T2/T3 |
| Harness drives the alignment session only | Journal follow-up mode + post-plan state + journal gates | test-plan O-1 / T-731 | **Phase 0** |
| memory-arch examples/lint still illustrate via Budget | Journal app-folder is the canonical built-in; example/lint migration is a coordinated DJ task | memory-arch §0/§20 | Open Item (not gating this build) |

---

## Architecture

**No service/DB/UI components.** The feature is instruction + file artifacts inside the starter pack, executed by the runtime's existing file-ops memory tools (read/write/edit/delete/list/search).

```
starter-pack/projects/templates/<page>/
  AGENT.md            (+ journal wiring: when/how to use the journal; reconcile no-forced-tracker)
  run-interview.md
  run-planning.md     (+ PJ-1 handoff appended at plan completion)
  run-journal.md      (NEW — shared follow-up session, instantiated per page with deltas)
  spec.md / plan.md   (unchanged page artifacts; journal adjusts them only on approval)

runtime owner instance:
  documents/<page>/journal/
    AGENT.md          (NEW — journal instructions + preservation rule)
    journal.md        (NEW — append-only owner entries; default-created)
```

**Data flow (a journal session):** owner speaks → runtime loads page `AGENT.md` + `run-journal.md` → reads profile + page `spec.md`/`plan.md` (known context) → identifies journal-worthy content → appends an entry to `journal.md` via file-ops (preservation rule enforced) → optionally proposes an owner-approved `spec.md`/`plan.md` adjustment or confirmed profile write → confirms what/where.

---

## Implementation Roadmap

> Tests-first within every phase: extend/author harness scenarios **before** authoring the instructions, then run gates.

### Phase 0: Prerequisites (gated)

Two prerequisites gate the build, owned separately:

**0a — Offline test-harness journaling mode ([[T-731]], DW + Claude).** Our offline `starter-pack-testing-harness` lane learns to drive + score a journaling follow-up session: post-plan owner state, journal driver, journal-file invariant + recovery gates, journal judge rubric, Fitness/Relationship journal personas, plus the locked interview baseline (B-0) + regression gate (G-7). **Exit:** `test-plan.md` Open Item O-1 runs so G-1…G-6 / FG-* / RG-* can be scored. (Overlaps T-603/T-602 — fold where they meet. Optional final validation on DJ's canonical `braindrive-test-harness`.)

**0b — Runtime enablement ([[T-732]], Dave J).** The runtime/product piece the instruction authoring sits on, two confirms (recommendations in the DJ handoff): **journal-folder materialization** (recommended: **seed `journal.md` at page setup** so Your Journal is visible alongside Your Goals/Your Plan) + the **pack instruction-reuse mechanism** (recommended: **copy-per-page for V.1**). Gates Phase 1's PJ-1 handoff. See [`dj-handoff.md`](dj-handoff.md).

### Phase 1: Shared pattern, proven on Fitness

| # | Task |
|---|---|
| P1-T0 | **Lock the pre-journal alignment baseline** for Fitness (Katie A/B/C interview→spec→plan on the *current* pack; freeze scores, B-0) **before touching any pack file** — this is the regression reference for G-7 |
| P1-T1 | **Tests first:** with T-731, author harness scenarios H-1…H-7 + recovery E-1…E-7 + properties P-1…P-7 against a Fitness post-plan fixture; add Fitness FH-1…FH-5 + FH-2b |
| P1-T2 | Author the canonical shared `run-journal.md`: check-in → progress review → blocker handling → adjustment-when-agreed → next step; entry format; create/view/correct/pattern-reflection flows |
| P1-T3 | Author the journal folder scaffold: `documents/fitness/journal/AGENT.md` (journal instructions + **preservation rule on every write/correct/recovery instruction**, P-7) + `journal.md` default template; encode recovery rules (missing/empty/malformed/corrupt) |
| P1-T4 | Wire the **PJ-1 handoff** into Fitness `run-planning.md` (point the owner to the already-seeded **Your Journal**; state next step = execute + journal; recovery rule ensures `journal.md` exists as a fallback) |
| P1-T5 | Apply Fitness delta + **reconcile** the "do not require daily journaling" boundary (no-forced-tracker stance kept; owner-driven journal added); encode no-invented-metrics + health boundary; **present the journal to the owner as "Your Journal"** (parallel to Your Goals/Your Plan) |
| P1-T6 | Run gates; capture evidence |

**Success criteria**

| Criterion | Spec Ref | Test-Plan Ref | Verification | Expected | Evidence |
|---|---|---|---|---|---|
| Plan→journal handoff fires; `journal.md` exists | PJ-1 | G-3 / H-1 | harness Fitness post-plan run | Next-step stated; file present | transcript + file check |
| Create/view/correct work | PJ-2/3/4, FJ-1/2 | G-4 / H-2,3,4 | harness + file diff | Entry appended; only target edited | `journal.md` diffs |
| No data loss / recovery correct | PJ-7, Recovery | G-1 / E-1…E-7 | recovery fixtures | Each case per rule; corrupt→recovery file | per-case file state |
| No silent parent change | PJ-6 | G-2 / H-6 | file diff gated on approval | Approved + concise; no raw dump | parent diffs |
| Placement + preservation static gate | Mem-Arch | G-5 / P-7 | instruction-set review | Instructions in app folder; preservation rule on every write | review checklist |
| Reflection is hypothesis-framed | PJ-4, FJ-3/4 | G-6 / H-5, FH-2/2b | judge | Hypotheses, no shame/overclaim, asks before edit | scorecard |
| Fitness domain gates | FJ-1…FJ-5 | FG-1/2/3 | harness FH-1…FH-5 | No invented metrics; health boundary; not a tracker | transcripts + scorecard |
| **Alignment not regressed** | — | **G-7** / R-1 / B-0 | re-run interview→spec→plan after **each** `AGENT.md` edit | No drop vs B-0 baseline (interview quality, spec/plan convergence, no-forced-tracker) | before/after scores |

**Human checkpoint:** UX review — does the loop feel like a coach who remembers? + approve owner-facing **PJ-1 handoff copy**.

### Phase 2: Relationship instantiation + deltas

| # | Task |
|---|---|
| P2-T0 | **Lock the pre-journal alignment baseline** for Relationships (B-0) before touching its pack files — G-7 regression reference |
| P2-T1 | **Tests first:** Relationship post-plan fixtures (incl. sensitive third-party + crisis seeds); author RH-1…RH-6 |
| P2-T2 | Instantiate the shared `run-journal.md` + journal folder on Relationships |
| P2-T3 | Add relationship deltas: privacy/agency, **professional-care boundary language verbatim**, no CRM/mind-reading/manipulation/passive-ingestion |
| P2-T4 | Reconcile Relationship `AGENT.md` journal wording; re-run shared gates G-1…G-6 on Relationships (proves the pattern generalizes to a higher-sensitivity page) |
| P2-T5 | Run relationship gates; capture evidence |

**Success criteria**

| Criterion | Spec Ref | Test-Plan Ref | Verification | Expected | Evidence |
|---|---|---|---|---|---|
| Shared gates hold on a 2nd page | PJ-1…PJ-7 | G-1…G-6 | harness Relationship runs | All shared gates pass | transcripts + diffs |
| No mind-reading / third-party dignity | RJ-1/2/4 | RG-1 / RH-1,2 | judge | Owner-context only; uncertainty labeled | scorecard |
| Professional-care boundary | RJ-5 | RG-2 / RH-3 | exact-string + judge | Approved wording verbatim; routes safety | transcript |
| No CRM / passive ingestion | RJ-4 scope | RG-3 / RH-4 | harness | Refused; owner-entered only | transcript |
| No manipulation / surveillance | RJ-4 | RG-4 / RH-5 | judge | Agency + dignity preserved | scorecard |
| **Alignment not regressed** | — | **G-7** / R-1 / B-0 | re-run Relationship interview→spec→plan after each `AGENT.md` edit | No drop vs B-0 baseline | before/after scores |

**Human checkpoint:** **DW review** of relationship boundary behavior (sensitive) — professional-care language + privacy/dignity.

### Phase 3: Lock the shared source + ship

| # | Task |
|---|---|
| P3-T1 | **Tests first:** full cross-page regression set (R-1…R-3 alignment/profile/placement) + baseline B-1…B-3 |
| P3-T2 | Lock the **canonical shared journal source** (the reusable instruction block) so Finance/Career/New-Project can instantiate later without re-deriving |
| P3-T3 | Final reconciliation sweep of journal wording across both pages; confirm no-forced-tracker stance intact |
| P3-T4 | Full regression + release-gate run; bundle evidence; merge to live pack |

**Success criteria**

| Criterion | Spec Ref | Test-Plan Ref | Verification | Expected | Evidence |
|---|---|---|---|---|---|
| Alignment session not regressed | — | R-1 | harness alignment runs | Interview→spec→plan unchanged | transcripts |
| Profile reuse/placement intact | — | R-2 / BP-1,2 | harness profile scenarios | No re-ask; correct placement | traces |
| Smoke + sweep green | — | B-1…B-3 | `./smoke.sh`; `openrouter-eval.py --sweep`; `judge.py` | Gates pass | reports |
| All release gates pass | all | G/FG/RG | full run | No blocker fails | scorecard bundle |

**Human checkpoint:** final review before merge to the live starter pack.

---

## Technical Details

- **Tools used:** existing file-ops memory tools only (read/write/edit/delete/list/search) — verified in `memory_tools.py` port. The append-only + targeted-edit + recovery behavior is **instruction-enforced** and **gate-verified**, not new code.
- **Preservation rule:** every instruction in `run-journal.md` / journal `AGENT.md` that writes, corrects, or recovers `journal.md` must carry the documented no-overwrite preservation rule (P-7).
- **Entry format:** the shared append-only Markdown block from spec §Shared V.1 Entry Format (date, source, page, context, entry, signals, follow-up, status).

## Security Considerations

Risk level **medium** (owner-private content; no external network/credentials in V.1). Hard gates: no data loss (G-1), no silent parent change (G-2), confirmed profile writes, no hidden catch-all. Relationship adds third-party privacy, crisis routing, and anti-manipulation gates (RG-1…RG-4).

## Risks & Mitigations

| Risk | Mitigation |
|---|---|
| Phase 0a (T-731, ours) slips → nothing verifiable | Sequence T-731 first; fold into T-603/T-602 to cut cost; until then only a hand-seeded smoke is possible |
| Phase 0b (T-732, DJ) slips → can't author the handoff | DJ confirms journal-folder materialization + reuse mechanism before Phase 1 (the two open items / DJ handoff) |
| Instruction-enforced no-overwrite is probabilistic across models | Deterministic file-diff gates (G-1) + adherence check across candidate default models; preservation rule explicit in every touch instruction |
| "Available but not mandatory" journal drifts into a nagging tracker | Reconcile boundary wording (P1-T5/P3-T3); no-forced-tracker is a kept boundary, judge-checked |
| **Editing the live pack regresses the interview→spec→plan loop** — the real hard part | `AGENT.md` is the only journal edit loaded during the interview; keep its journal wording minimal (3-line), procedure in `run-journal.md`; **lock a pre-journal baseline (B-0) before any pack edit**; re-run the alignment smoke after **every** `AGENT.md` edit; **G-7 blocks release** on any regression in interview quality, spec/plan convergence, or no-forced-tracker behavior |
| Shared-vs-duplicated drift across page templates | Single canonical source (P3-T2); deltas only |
| Template→runtime journal folder materialization unclear | Open Item — confirm with DJ before P1-T4 (handoff "ensure journal.md exists") |

## Human Checkpoints

1. **After Phase 1** — UX review of the loop + PJ-1 handoff copy approval.
2. **After Phase 2** — DW review of relationship boundary behavior (sensitive).
3. **After Phase 3** — final review before merge to the live pack.

## Open Items

- [ ] **Template→runtime materialization (T-732):** recommended = **seed an empty `journal.md` at page setup** (orientation — Your Journal visible alongside Your Goals/Your Plan). Confirm the runtime can seed at setup, or the earliest seed point if a page folder doesn't materialize until the interview writes spec/plan. (DJ)
- [ ] **Shared-source reuse mechanism (T-732):** recommended = **copy-per-page for V.1** (no include mechanism exists; keeps pages owner-editable). Confirm, or flag if a shared include is wanted now. (DJ)
- [ ] **Harness authority (O-5):** offline `starter-pack-testing-harness` lane vs canonical `braindrive-test-harness` vs both.
- [ ] **Judge calibration (O-4 / RO-2):** reflection-quality and crisis-routing known-good/known-bad examples before G-6 / RG-2 are hard gates.
- [ ] **memory-arch example/lint migration** off the Budget illustration to the journal built-in — coordinate with DJ (not gating this build).

## Completion Checklist

- [ ] Phase 0a (T-731, ours) + Phase 0b (T-732, DJ) exit criteria met
- [ ] Phase 1 gates pass on Fitness (G-1…G-6, FG-1…FG-3) + UX checkpoint
- [ ] Phase 2 gates pass on Relationships (G-1…G-6, RG-1…RG-4) + DW checkpoint
- [ ] Phase 3 regression + baseline + all release gates green + final checkpoint
- [ ] Merged to live starter pack; evidence bundle archived

---

*Next: resolve the Phase-0/T-731 dependency and the template→runtime open item, then begin Phase 1 (tests first). Run `/milestone-check` after each phase.*