# Journaling — Implementation Handoff for Dave J (review draft)

**From:** Dave W · **Date:** 2026-06-30 · **Status:** for your review before Phase 1
**Full plan:** [`build-plan.md`](build-plan.md) · **Specs:** [shared](spec.md) + [Fitness](../../fitness/fitness-journal/spec.md) + [Relationship](../../relationships/relationship-journal/spec.md) · **Test plans:** [shared](test-plan.md) + 2 deltas

---

## What this is

Journaling — the "Repeat" half of every page (interview → spec → plan → **journal**). It's V.1 item #4 and now the **sole built-in companion feature in V.1** (the to-do list moved to V.1.1, [[braindrive-repo]] D272). This first build proves the shared pattern on **Fitness** and **Relationships**.

It's spec'd, test-planned, and build-planned. I want your review on whether the **implementation approach matches the actual runtime** before we start, plus the two runtime recommendations below to confirm or correct.

## The core call: text-first, no code

The journal is **a Markdown file the existing file-ops memory tools manage, driven by authored starter-pack instructions** — **no new product runtime code, UI, or schema** for journaling itself (aside from however the journal folder gets created — your call, [[T-732]]). The offline test-harness work ([[T-731]]) is ours. Each page template gains:

```
projects/templates/<page>/
  run-journal.md      (NEW — the follow-up session instructions)
  run-planning.md     (+ the plan→journal handoff appended at the end)
  AGENT.md            (+ journal wiring; reconcile the existing "don't require daily journaling" line)

runtime owner instance:
  documents/<page>/journal/
    AGENT.md          (NEW — journal instructions + the no-overwrite preservation rule)
    journal.md        (NEW — append-only entries; seeded empty at page setup)
```

The append-only / targeted-edit / recovery behavior is **instruction-enforced and gate-verified**, using the file-ops tools (read/write/edit/delete/list/search) you already have. **No new product runtime code, no UI, no schema** for journaling itself (the offline harness work is ours; the journal-folder creation is your T-732 call). If that's wrong — if any of this genuinely needs runtime/code support — that's the most important thing to flag.

## Phases (full detail in the build plan)

| Phase | What | Verifies |
|---|---|---|
| **0a** | Offline harness journal mode — **[[T-731]]** (ours) | makes the rest testable |
| **0b** | Runtime enablement — **[[T-732]]** (you) | makes the rest buildable |
| **1** | Shared pattern, proven on Fitness | G-1…G-6 + Fitness gates |
| **2** | Relationship instantiation + deltas | + Relationship gates (privacy, professional-care, no CRM) |
| **3** | Lock the shared source + full regression + ship to live pack | baseline + all release gates |

## The hard part: don't regress the interview

The real difficulty isn't building journaling as Markdown — it's editing the *same* starter-pack files that already produce a good interview → spec → plan, without degrading them. Good news: the risk collapses to **one file per page — the page `AGENT.md`** (the only journal edit loaded *during* the first conversation; `run-journal.md` is follow-up-only, and the PJ-1 handoff fires *after* the plan exists). So the approach:

- Keep `AGENT.md` journal wording to **one line** — "a journal exists after the plan, owner-driven, not mandatory" — and put the actual procedure in `run-journal.md`.
- **Lock a pre-journal interview baseline** (Katie A/B/C) before any pack edit.
- Re-run the alignment smoke after **every** `AGENT.md` change, not just at the end.
- **G-7 blocks release** if interview quality, spec/plan convergence, or the no-forced-tracker behavior regresses.

## What I need from you (Phase 0b — [[T-732]])

**1. Journal folder materialization — recommend: seed at page setup.** Seed an empty `journal.md` (and its folder) when the page is set up, so "Your Journal" appears next to "Your Goals" and "Your Plan" from the start — that sidebar triad is what tells the owner the page is for *goals → plan → journaling*. The PJ-1 handoff stays the active "now go journal" prompt, and the recovery rule is the backstop. **Need from you:** confirm the runtime can seed it at setup — or, if a page folder doesn't materialize until the interview writes spec/plan, the earliest sensible seed point.

**2. Shared-instruction reuse — recommend: copy-per-page for V.1.** The pack has no include/partial mechanism today, and inline instructions keep each page plain-English and owner-editable (and match how `run-interview.md` / `run-planning.md` already work). The canonical journal source lives in the spec so the copies don't drift. **Need from you:** confirm copy-per-page — or flag if you'd rather build a shared include now (worth revisiting when journaling hits all six pages).

**Heads up — the test-harness side is on us, not you.** Teaching the harness to run + score a journaling follow-up session, and to catch any interview → spec → plan regression, is our offline-lane work ([[T-731]]) — you don't need to build journal scenarios. It overlaps your [[T-603]] (existing-owner state) and [[T-602]] (spec-anchored scoring), so we'll fold where they meet. If you want journaling also validated on your canonical/live harness as a final gate, say so and we'll coordinate.

## Two things I already worked through (so you don't have to re-litigate)

- **"Don't require daily journaling" stays.** The live pack tells the model not to force journaling/logging — that's *correct* and stays. The journal is owner-driven follow-up, available but never mandatory. The build reconciles the wording, doesn't contradict it.
- **Your Agent routing is deferred.** Journaling from the Your-Agent front door (spec Success #9) waits for the general-journal router build — out of scope here. In-scope journaling is direct, on the Fitness/Relationship pages.

---

*Confirm or adjust 1–2 (and any "the runtime doesn't work that way" corrections) and I'll fold them into the build plan before Phase 1.*