## 2026-08-25 — checkpoint hook floods the diary with virtualenv internals

What happened: `checkpoint.sh` appended every changed file under `.venv-dev/`
(thousands of site-packages paths) to `.logs/diary.md` after a venv rebuild.
Cost: a few minutes of cleanup, and a diary entry that buried the real changes.
Candidate fix: the hook's changed-file detection should exclude `.venv*/`,
`node_modules/`, `data/`, and `__pycache__/` — the same set every tool ignores.

## 2026-08-25 — no named home for "what's open on this project, at a glance"

**What happened:** while cutting internal issues out of the client review page,
rian asked for our running internal issues/ideas record. v8 deliberately
decomposes the memory-bank "living activeContext" into handoff.md (append-only
stream) + .memory/ (curated facts, updated/removed) + one server-level
ideas.md ("no parallel trackers") — but names no per-project open/watched/
parked register, so neither rian nor the session could point at one. We
created `.logs/issues.md` as a declared override (noted in agents.md), which
works but sits in tension with the twice-stated "never add a parallel store".

**What it cost:** a re-derivation session and real uncertainty about whether
the architecture covered the need — the decomposition is sound but not
self-evident at the moment of need; also two days of sessions closed without
/checkpoint, so diary.md lags handoff.md (the manual half of the loop needs
either habit or a stronger hook).

**Candidate fix (standards decision):** either (a) add a `.logs/issues.md`
role to the scaffolded shape (empty-file-skip header: "topical register —
open/watched/parked, updated in place; handoff stays the story"), or (b)
document the native decomposition prominently (an issue = a .memory/ file
with a status line; the at-a-glance view = the memory index) and forbid the
register. Either is fine; the failure mode is only the UNNAMED middle where
each project reinvents it.

**Addendum (rian, same night) — the gap is bigger than a missing filename.**
His articulation, kept verbatim in spirit: working with agents is "10 really
smart engineers reporting back at superhuman speed" — a firehose where the
human keeps up with a fraction; items get ignored, backgrounded, or attended;
over time some resolve, some go irrelevant, some turn critical, some are blue-
sky. What's missing is a **living list that is constantly REWRITTEN, not
appended** — plus a **garbage collector** that prunes what no longer matters.
Honest constraint: he will never sit and read the file; it exists so the
build can "come back to something" later (e.g. the revenue-model discussion).
Implication worth carrying into the v8 revisit: the register's real READER is
the agent, retrieval is conversational ("what did we decide about X?"), so
the design target is agent-retrievable + curated, not human-browsable — and
the garbage-collection pass is a natural /checkpoint (or heartbeat) duty, not
a human habit. Status: parked here for the next v8 evolution session; interim
mechanism is this project's .logs/issues.md updated-in-place.

## 2026-09-11 — Stream E: no substrate path to a live host

- **What happened:** the gateway and the standards library cover dev on this server only.
  Standing up the live host meant hand-rolling everything the substrate does here: a droplet
  bootstrap, a Caddy bundle, a deploy script (dump, rsync over Tailscale, build, health), backup
  crons at both ends, and a host firewall rule for the sidecar. About a day, most of it generic.
- **What it cost:** one preflight bug shipped in the hand-rolled deploy script (`grep -c` exits 1
  on a zero count) and two fixes in the fence script on first install; none would exist with a
  shared template.
- **Candidate fix:** a standards-library `deploy/` template (bootstrap, Caddy with Cloudflare,
  production.sh, backup crons, fence) that a project copies, or `srv-gw deploy --target live`
  once the live box has a gateway. Also: the server `/checkpoint` hook keys on `$PWD`, and a
  long session's cwd drifts (`cd main && ...` persists); the project command says "run from the
  workspace root" but nothing enforces it.

## 2026-09-11 — a git worktree session: the dev loop assumes the workspace root

- **What happened:** the desktop app opened this session in a git worktree under
  `.claude/worktrees/`. `main/check.sh` calls `../.venv-dev` and the SPA build needs
  `main/web/node_modules`; neither is tracked, so both had to be symlinked from the main
  checkout (and excluded in `.git/info/exclude`, since a `dir/` ignore pattern does not match a
  symlink). `scripts/docmap.py --write` then baked the worktree's path into RUNBOOK's generated
  CLI reference (the `audit --out` default is an absolute path), dirtying a doc the change never
  touched. Separately, the main checkout's `node_modules` lacks `node-releases/data/processed/`,
  so `vite` dev mode fails on every file; `vite build` still works.
- **What it cost:** about twenty minutes of setup and one near-miss commit of a machine path.
- **Candidate fix:** check.sh resolves the venv from the git common dir when `../.venv-dev` is
  absent; docmap renders path defaults relative to the workspace; `npm ci` in the main checkout.