agenda — session handoff (2026-08-14)

# agenda — session handoff

Date: 2026-08-14 · Repo: /Users/yachintyadav/Workspace/agenda · Branch: design (10 commits ahead of main, nothing pushed) · Working tree: clean

0. Read this first

Three files govern how you work here, and they outrank anything in this handoff:

1. AGENTS.md — the pillar rule (§2), the 27 hard invariants (§3), conventions (§6), and how decisions get recorded (§7).
2. CLAUDE.md — Claude-specific notes. Most relevant: use plan mode for anything that touches a pillar, and the document wins until amended.
3. MEMORY.md — the dated decision journal, D1–D59, with a Direction section at the bottom that states the current phase and the immediate order of work. Start there.

The project's own handoff mechanism is MEMORY.md's Direction section. It is current as of this commit. This document is a narrative layer over it, not a replacement.

1. What agenda is

A personal, single-user, self-hosted daily-practice tracker (PWA on a VPS behind Traefik). It exists because Habitica destroys task history when you miss a day — it is built on jeopardy (loss must be real) while being asked to serve as a record (nothing may ever be lost). Those purposes are incompatible.

agenda resolves that by separating two layers:

• The ledger — append-only, immutable, enforced by database triggers. Facts about what happened.
• The scoring layer — pure functions computed at read time. Opinionated, swappable, retroactively recomputable.

The product never scolds, never congratulates for streaks, and never implies a missed day is a character flaw. That is not decoration; it is enforced by invariants (I11 no streak summaries, I12 no punishment/HP/badges, I27 no hue may mean good or bad) and it is the thing to protect in every design decision.

2. Current phase

Phase 0 — pillars ratified and amended, no application code yet.

The repository contains no packages/, apps/, or schema.sql. What exists is four pillar documents, three agent files, and one very large reference prototype.

The four pillars (source of truth, ahead of code)

The amendment protocol is mandatory. If a change contradicts a pillar: stop, say so, and propose an amendment. An amendment = edit the pillar body so it reads as current truth + add a row to that document's Amendment Log + add a dated entry to MEMORY.md. All three, in the same commit.

The prototype

docs/ui/capture-prototype.html — a single file, ~3,100 lines, HTML+CSS+JS, no build step. It is the reference of record for the visual system and carries three surfaces:

1. Capture screen (default) — today's rows; the primary job is logging a session in one tap
2. Commitment index — &v=index
3. Detail page — &c=<slug>: present reading, three-month calendar with a real role="grid" contract, day inspector, analysis zone under a window control, retirement

Serve it:

cd docs/ui && python3 -m http.server 8142
# http://127.0.0.1:8142/capture-prototype.html

A server was already running on 8142 (PID 3611) at handoff time; it may not survive. Do not commit anything into docs/ui/ as a temp file.

URL parameters: ?w=390 simulated width (container queries at 353/620/900) · &n=8 commitment count · &c=<slug> detail page · &v=index · ?day=YYYY-MM-DD overrides today. A floating Prototype controls panel carries dev overrides (coverage, warm-up, sync state).

3. What this session did

Ten commits on design. Grouped by theme:

The review surface (built and specified)

Index, detail page, calendar, day inspector, and retirement were shaped, ratified, and built into the prototype. One terminal state (retired) with a required note. Pillar amendments across DESIGN.md (A12–A17), Architecture.md (A5), and Metrics.md (A4).

Settlement correctness

Three defects found and fixed, verified over roughly 2.7M week-evaluations:

• Slot assignment in date order violated I22 — upgrading skipped→partial dropped momentum. Fixed with surplus ranking (§5.4).
• Momentum seeded at first observation — 39,916 property violations. Fixed to s₀ = 1.0.
• I20 violated in open weeks — logging a partial Monday cost more than logging nothing. Fixed by counted-side certainty (Metrics A5).

Coverage (last thing before the critique)

The prototype was computing coverage as day-based (inScopeDays − blocked) ÷ inScopeDays. Replaced with §7.1's obligation terms, which never reuse targetScaled (I24). Recorded as Metrics A6 with a new §7.1.1.

The amendment exists because implementing the formula forced a placement question the pillars disagreed about: §6.8 makes coverage a mandatory companion to momentum, §3.1 makes momentum window-independent and coverage window-governed. Resolved as one formula, two named spans — a fixed 28-day confidence statement beside momentum, and a windowed analysis reading.

Accessibility and focus

Escape focus restore on all five sheets; the roving tab stop now follows focus out of a dialog. Both of the last two defects here were found by the user pressing a key, not by any harness.

4. Where to resume — in this order

The user chose this order explicitly at the end of the session. Full detail in MEMORY.md D59 and the critique snapshot at .impeccable/critique/2026-08-14T09-45-26Z__docs-ui-capture-prototype-html.md.

(a) Three focus/motion defects — /impeccable harden

Causes are already located in source; these are not investigations.

(b) Two pillar questions — /impeccable shape, in plan mode

Both are contract changes, so CLAUDE.md requires plan mode and approval before code.

1 — Coverage cannot soften a bad fortnight. Coverage guards against a thin record, not a bad stretch. After fourteen missed days, missed is covered (§7.1, correctly — not doing it is a real observation), so coverage stays 95–100% and the Confidence Rule cannot fire. Momentum reads 0.24 at full chroma and full authority: yes, trust this, and it is 0.24. The worst-feeling screen in the product is the one with nothing qualifying it — on the exact scenario agenda exists to survive.

Either that is right and the interface needs another way to say it, or coverage is not the only confidence term. This is upstream of the deferred absence-screen fix — settling the principle decides what that screen should say, which is why it comes first.

2 — The calendar's empty cell means four things. Before start, during a pause, after retirement, and not yet. The Key teaches exactly one meaning and DESIGN.md says it "means nothing else". Every future day currently announces "no obligation" on an active commitment. Either future earns a mark of its own the way missed did, or the stated single meaning is wrong.

Sequencing note given to the user: take the pillar questions before the type pass, because the calendar question may add a mark to the cell, which changes what the numerals sit beside.

(c) The 8px type step — /impeccable typeset

Raise .cn (calendar date numerals) and .cw (weekday initials) from 8px to the 11.5px step — three declarations, 65 visible instances, cells are 49×44 with room. .dlab (field axis labels) is the same declaration family; decide it in the same pass.

Deferred by the user's scope choice (recorded, not lost)

• [P1] The absence screen offers 20 obligations and no exit after 14 days away — blocked on pillar question 1
• [P2] The index is a right-aligned column of eight bare decimals, with no trace and no day composition
• Minor: run rendered but absent from the Key · aria-expanded="false" while the overflow menu is open · .mini border at 2.992:1 in paper · six CSS.escape calls inside quoted attribute selectors · the HSL hue ramp clusters five commitments in a 40° green band at n=20 (OKLCH would recover it)

After the prototype: phase 1–2

pnpm workspace scaffold, schema.sql with the immutability triggers, migrations, and packages/core with reducers and metrics — built from docs/Metrics.md against the §17 fixture table, not from the prototype.

The retire_needs_note CHECK must land in schema.sql at creation — I19 makes it unaddable afterwards, because the twelve-step rebuild SQLite needs to add a CHECK destroys the immutability triggers.

5. Method notes that will save you time

What works

• Extract functions from the artifact; never retype them. The fixture harness pulls periodsIn and coverageOver out of the HTML by brace-matching and stubs only leaf dependencies. Testing a re-implementation is how the momentum seeding defect survived.
• Property sweeps over exhaustive week shapes caught all three settlement defects. Single fixtures caught none of them.
• node --check on each extracted <script> block after every edit. This file has twice acquired ${/* … */""} template comments written into plain JS, and once a literal NUL byte.
• The design detector: node ~/.claude/skills/impeccable/scripts/detect.mjs docs/ui/capture-prototype.html (currently 0 anti-patterns, 1 advisory false positive).

Harness limits — real, and they produced contradictory readings

• CDP cannot deliver Escape to a modal <dialog>. Tab and arrows work; Escape produces zero keydown events in the page.
• .focus() does not fire focus events when the document lacks OS focus. So a focusin-based fix is unobservable and so is the bug it fixes. Any focus invariant must be maintained synchronously, never dependent on an event arriving.
• :focus does not match under some CDP conditions.
• When the instrument cannot reach the case, the case is not verified — it is someone's five seconds. Two defects this session were found by the user pressing a key after four automated attempts had contradicted each other.

Two recurring failure patterns worth internalising

1. Fixtures that cannot fail. Three separate defects survived a passing test because the test could not vary: the momentum seed (D47), settled-period-only momentum (D50), and the entire coverage fixture set (D58 — five fixtures all satisfied by the very formula §7.2 rejects, because targetRaw cancels when periods share an in-scope length). Run every §17 row against a deliberately wrong implementation before trusting it.
2. The Preserved Focus Rule has failed six distinct ways in this one file. The fifth and sixth were found after the rule was written down. Documenting a behaviour reliably produces the feeling of having handled it.

6. Commit log for this session

efef346  docs: record the fourth UX critique and the work it ordered (D59)
414813e  fix(ui): coverage computed from obligations, not days
768fa7d  docs: coverage gets its span named (Metrics A6)
f9a8523  fix(ui): the roving tab stop follows focus out of a dialog
a5fdbab  docs: confirm the Escape focus path end to end (D57)
e240bb4  chore(impeccable): design sidecar and critique snapshots
f353800  docs: pillar amendments for the review surface and settlement
8090141  feat(ui): the review surface — index, detail page, calendar, day inspector, retirement
a31290d  docs: add DESIGN.md as the fourth pillar, and PRODUCT.md
4d2a544  chore: ignore machine-local agent hooks and Impeccable caches

Branch design. Nothing has been pushed — AGENTS.md §8 says do not commit or push unless asked, and only committing was asked for.

7. Design health at handoff

Fourth UX critique (dual-agent, isolated): 32/40 — Good. Trend 23 → 29 → 27 → 32.

Measured clean: 0 text-contrast failures across 220+183 elements × both renditions · field bars and calendar marks floor at 4.82:1 (ink) / 3.99:1 (paper) across all 20 channel hues · 0 horizontal overflow in 24/24 width×surface combinations · 0 unnamed interactive nodes · 0 heading skips · 0 console errors · 0 layout-triggering transitions · roving-tabindex grid contract verified [1,1,1].

Strongest thing in the product, and the thing to protect: the Confidence Rule renders as written. At cov 35% the row's --c moves hsl(H 72% 68%) → hsl(H 42% 65%) and the momentum numeral drains from a hard boundary. Colour is removed to signal doubt, never added to signal fault. It is the rare case of an ethical claim surviving contact with CSS.