DEC-0031 — The read-only /board as "The Ledger of Work"

Reversibility: two-way door — the entire surface is a derived, read-only view over the git board (board.astro + board.css can be rewritten or deleted without touching the OKF system of record, the runtime worker, or any sovereign behavior); the one less-trivial-to-undo change is the new --ds-duration-pulse motion token in @dossier/design, but it is additive and generator-sourced. The durable commitment is only the POV — this surface exists to make loop health legible (read-only-as-serenity), not to manage tasks, and its motion only ever animates real committed git state, never a fabricated live-agent signal.

Context

Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first shipped the read-only, KB-agnostic /board surface (KB-agnostic @dossier/site (renders any tenant's OKF KB) + runtime-driven site rendering + the Node-26 Windows build fix) as a functional rendering of the git-resident OKF task board — 8 task atoms across lifecycle columns, never writing the board (Adopt OKF as Dossier's canonical knowledge format). It was correct but generic: a per-status count chip row over a heavy priority/sort toolbar slab and conventional kanban cards. The founder flagged the UX as "horrible" and asked for a creative, unique rethink. A Product Owner (framing) + Principal UX Engineer (build, owner) pass this session (2026-06-16) converged on one direction, which the Principal Forward Deployed Engineer then implemented and verified offline.

This sits downstream of Recalibrate the Dossier brand identity — demote color, promote type + restraint + craft — then build the showcase landing ("warmth from type + restraint, not tint") and reuses the motion discipline established for the public landing in A motion language for the public landing — make the compounding learning-loop story kinetic while holding the brand bar (and a documented exception for the section-4 loop diagram) (tokens-only, reduced-motion-safe, animate-only-what's-true). It honors the Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first non-negotiables — read-only/sovereign, no-fabricated-status, KB-agnostic — as the redesign's load-bearing guarantees, not as afterthoughts.

Options considered

A — Polish the existing kanban (better chips, lighter toolbar, nicer cards). Rejected. It answers a question the board does not need to answer well. A generic kanban is built to answer "what tasks exist and who's doing them?" — task management. But this board has no mutation affordances by design (it is read-only over the git board), so the task-management framing fights the surface's actual nature and leaves its real differentiation invisible.

B — Reframe around loop-health legibility, ship "The Ledger of Work" (chosen). Ask the only question this surface alone can answer: "is the autonomous loop healthy, and what needs a human right now?" Promote the agentic substrate (Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first's lease/claim/review-gate/git-source) from incidental card metadata to the hero of the page; treat read-only not as a limitation but as serenity (a record, not a workspace); lean on editorial serif + restraint (Recalibrate the Dossier brand identity — demote color, promote type + restraint + craft — then build the showcase landing) over dashboard chrome.

C — A dense "mission-control" telemetry dashboard. Rejected as off-brand (chrome-heavy, anxious) and as over-claiming: the autonomous worker is RESERVED (Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first), so a live-telemetry framing would imply a running process that does not exist — exactly the fabricated-status trap. The "ledger / record" framing is honest about what the data is: committed git frontmatter.

Motion scope. Following A motion language for the public landing — make the compounding learning-loop story kinetic while holding the brand bar (and a documented exception for the section-4 loop diagram)'s discipline, the board gets one continuous motion (the lease heartbeat) bound to a real, build-computed state — never an ambient "something is happening" animation. A live lease breathes, an expiring one quickens, a stale one flatlines. The alternative (a generic always-animating pulse to suggest activity) was rejected as a fabricated live-agent signal.

Decision

Redesign the read-only /board as "The Ledger of Work" — a record, not a workspace, whose job is to make autonomous-loop health legible and surface what needs a human now — built tokens-only over @dossier/design, with the one continuous motion (the lease heartbeat) animating only real committed git state. Concretely, the v1 moves over packages/site/src/pages/board.astro + packages/site/src/styles/board.css:

1. Pulse strip replaces the per-status count chips: an editorial vital-signs sentence surfacing the autonomous-workforce facts — N atoms · in-hand · awaiting-review · expiring/stale leases · blocked · git file count — all derived at build from the rendered set (no second source of truth).
2. Lifecycle rail fuses the status summary and the status filter into one connected left→right pipeline (a hairline spine, status-hued nodes); priority + sort are demoted into a collapsed "Refine" disclosure. The old heavy toolbar slab is gone.
3. Card redesign: editorial serif title (primary); the redundant in-card status pill removed (the column + left rail already carry status) and the always-task type badge removed; a signature foot showing the review handoff ("→ awaiting your merge") on review cards, the claim/lease (with the heartbeat) otherwise, or "unclaimed · open to any agent"; provenance (source path + timestamp + confidence) demoted to a quiet foot but present on every card.
4. Lease heartbeat — the board's one continuous motion: a live lease breathes (a slow pulse ring on the claim avatar), an expiring one quickens, a stale one flatlines to a static danger ring. It animates a REAL, build-computed lease state — never a fabricated "agent running now" signal.
5. The review column reads as a literal human gate: a "⊢ human gate · awaiting merge" sub-label + a dashed threshold rule.
6. A persistent read-only chip in the topbar (sovereignty declared in the chrome); empty states reframed from absence to readiness ("ready to be claimed and drained by an agent"); a restrained reveal-once entrance.
7. The board recomposed as a "stacked ledger of shelves" (a second pass, same session, on the founder's "the columns still look bad" note): the side-by-side gray kanban boxes are gone; the stages stack top-to-bottom in lifecycle order, each one a single horizontal shelf read most-urgent-first (left) with priority descending rightward, scrolling horizontally on overflow so the next-up task always leads. Frameless, divided by hairlines, each shelf headed in its stage hue with a status-hued marker — and it holds on mobile (the lead card leads, the next peeks). Page-level art-direction over the design system's default boxed kanban primitive; the primitive is unchanged.
8. A quick-look details modal (founder request): clicking a card opens a read-only <dialog> panel — status, full (unclamped) description, a facts grid (for / priority / claim+lease / confidence), dependencies, acceptance criteria, and the sovereign source path — whose only outbound action is "Open the atom ↗" in a new tab. Progressive enhancement: with JS off a card is a plain link to its atom, and cmd/ctrl/middle-click still opens the atom natively; the panel reads from one build-time JSON payload (no second source) and never mutates.

The @dossier/design primitives evolved through the generator (packages/design/src/css.ts + packages/design/src/tokens/motion.ts — one new motion token --ds-duration-pulse), and the drift-tested packages/design/styles/dossier.css was regenerated, not hand-edited.

Rationale

• The board's differentiated value is loop-health legibility, not task management. A generic kanban answers a question this read-only surface neither can nor should answer; "is the loop healthy, what needs a human?" is the only question it alone can answer, so the design is organized entirely around it.
• Read-only is reframed as a feature, not a constraint. "A record, not a workspace" turns the absence of mutation affordances into serenity and makes the read-only chip a sovereignty statement (Adopt OKF as Dossier's canonical knowledge format) rather than a missing-feature apology.
• Honesty is structural, not promised. Every number in the pulse strip is derived at build from the same rendered set the cards come from (no second source); the heartbeat animates a real build-computed lease state read from committed git frontmatter — never a surface-invented "agent typing now" animation. The dogfood board deliberately exercises both lease states from real committed data: the original claimed seed task keeps its genuinely-past lease and renders as a STALE exemplar (flatlined ring, struck-through "claim reclaimable"), while a second seed task (task-design-task-concept-type, in_progress) was given a real future-dated lease_expires at the founder's request so the board demonstrates a healthy, breathing live claim beside it. The honesty contract is unbroken because the heartbeat reflects a real committed lease, not a fabricated process; the live lease is honest seed/demo data that will itself age to stale if not refreshed (self-correcting). This is the Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first "no fabricated status" rule made visible: the UI animates committed git state, whatever that state happens to be.
• It conforms to the existing bars instead of inventing new ones. Tokens-only / on-system: every value is a --ds-* token and the one new token came through the generator with the drift test regenerated, not hand-patched — the same SSOT-for-design discipline as Establish the design system and the UX-engineering function. Type + restraint over chrome is Recalibrate the Dossier brand identity — demote color, promote type + restraint + craft — then build the showcase landing; the single-real-motion, reduced-motion-safe, progressive-enhancement stance is A motion language for the public landing — make the compounding learning-loop story kinetic while holding the brand bar (and a documented exception for the section-4 loop diagram).
• KB-agnostic survives the redesign. Columns / rail / pulse all derive from the distinct statuses present in the rendered set; the human-gate treatment is page-applied to review only (opt-in), never baked into the board's survival; unknown statuses still degrade to neutral (KB-agnostic @dossier/site (renders any tenant's OKF KB) + runtime-driven site rendering + the Node-26 Windows build fix).
• verified, scoped to the surface. The redesign renders, builds green, and is Playwright-checked — but the confidence is on the front-end UI, not on the autonomous worker, which remains RESERVED (Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first). This decision makes no claim about live autonomy.

Consequences

• The redesign changes are confined to two derived files (packages/site/src/pages/board.astro, packages/site/src/styles/board.css) plus the additive generator evolution (packages/design/src/css.ts, packages/design/src/tokens/motion.ts, regenerated packages/design/styles/dossier.css). The only non-surface edit is one seed-data line — a future-dated claimed_by/lease_expires on knowledge/tasks/task-design-task-concept-type.md to demonstrate a live claim — which is ordinary OKF board content, not a code or protocol change. No change to the OKF system of record's shape, the runtime board worker, the claim/lease protocol, or any sovereign behavior — the surface stays read-only/zero-copy.
• Accessibility held: status / priority / lease / blocked / gate are never color-only (label + dot + countdown string + glyph+text); reduced-motion no-ops the heartbeat and the entrance (state still reads from text); the progressive-enhancement filter JS is intact (the rail filter works with JS off).
• A Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first routed follow-up is addressed on both branches: DEC-0030's Review asked to either roll the demo claimed task's historical lease_expires to a live-looking value or annotate it as an intentional stale-lease exemplar. The board now does both, from real committed data — the original past-lease claim stands as a first-class STALE exemplar (flatlined ring), and a second seed task carries a real future-dated lease so a healthy breathing claim renders beside it; together they exercise the full lease state machine on the dogfood board. The other DEC-0030 board routed items (shared LEASE_STALE_GRACE_MS, hook-doc precision, dangling owner/assignee role edges) are unrelated to this surface pass; the lease-grace drift was confirmed already consistent this session (LEASE_STALE_GRACE_MS = 5*60_000 across site lib / runtime / hook — not re-touched).
• The one less-trivial-to-undo artifact is the new --ds-duration-pulse motion token in @dossier/design (additive, generator-sourced); everything else is freely rewritable derived view code. Two-way door.
• Build-side only. Nothing is added to the client-facing plugin subset; no sovereign behavior changes.

Verification (this session, offline)

• @dossier/design drift test green (9/9) after the primitive evolutions + regeneration — dossier.css is a true generated cache of the token tree, not hand-edited.
• pnpm -F @dossier/site build (via the out-dir workaround for the known Windows dist editor-watcher lock — an environment lock, not a code defect) — complete, zero errors; the whole docs surface + /board built.
• Live render verified with Playwright at 1440px (light + dark) and 390px: the pulse strip, lifecycle rail, human gate, stacked-shelf board (stages top-to-bottom, each a horizontal shelf, most-urgent-left), stale-claim treatment, and redesigned cards all render correctly; only console error is an unrelated Vite dev-toolbar 504, none from the board. The lifecycle-rail filter verified functionally (toggling a status hides the others).
• The live breathing claim verified end-to-end: the seeded future-dated lease renders on task-design-task-concept-type as ds-task-claim--live, lease text "5h 55m left", with the avatar ::after actively running ds-lease-pulse at the --ds-duration-pulse 2.4s cadence; the pulse strip correctly gains a "◐ 1 in hand" segment. The original past-lease claim still renders STALE (struck-through "claim reclaimable", no animation) — both states visible at once.
• The quick-look modal verified: clicking a card opens the read-only <dialog> with the correct title, full description, facts grid (incl. the live "claimed by … · 5h 55m left"), acceptance criteria, source path, and the "Open the atom ↗" new-tab action; backdrop/✕/Escape close it; with JS off the card remains a plain link to its atom.
• NOT claimed: nothing here verifies the autonomous worker (still RESERVED, Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first); the verified confidence is for the front-end surface only.

Review

The surface redesign is verified as built and needs no promotion. Revisit the design POV ("The Ledger of Work" / loop-health-over-task-management) when the board is first pointed at a real client KB via DOSSIER_KB (KB-agnostic @dossier/site (renders any tenant's OKF KB) + runtime-driven site rendering + the Node-26 Windows build fix) and at higher task volume — confirm the pulse-strip vital-signs sentence and the lifecycle rail still read well across many statuses and a board with multiple live/expiring/stale leases at once (the dogfood board exercises only one claim). The heartbeat's honesty contract — animate only real committed lease state, never a manufactured live-agent signal — is the load-bearing invariant to preserve through any future iteration, including when the reserved AgentSdkBoardWorker is eventually activated (Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first).