# Kanban boards with rigor mode, time tracking & congruency ## Context listam today is a P2P grocery/list app: every item is a flat `{id, text, isDone, timeOfCompletion, updatedAt, listId, listType}` record replicated over Autobase. We mocked (in this session) a full kanban experience — a project/ticket board, two ticket-detail views, and a Properties/States/Automations/Rules config — and now want to implement it. The new product rules: 1. **Rigor mode** — a board-level mode, **on by default**, that the board owner can disable. While on, creating a ticket requires at minimum: a short description, a task checklist (≥1), estimated hours (>0), and estimated complexity (1–100%). 2. **Time tracking** — accumulate the time a ticket spends in the *In Progress* state. 3. **On-time flagging** — on reaching *Done*, freeze a verdict from `delta = (actualInProgressHours − estimatedHours) / estimatedHours`: `delta > +10%` → **overtime** (not in time); `delta < −10%` → **undertime** (overestimated); otherwise **on time**. 4. **Congruency score** (per user) — calibration accuracy: a user is more congruent the closer their average estimated complexity is to the share of their tickets that missed the estimate (ran overtime **or** undertime). **Authority model (user decision):** the **signature of the board creator** is the authority. Rigor mode and all board configuration are stored as an **owner-signed record** verified against the creator's authority key — no client (desktop, mobile, headless, leaf) can change them without that signature. This reuses the proven `membership.mjs` owner-signed-record pattern. **Outcome:** a kanban board where tickets are first-class items, estimation discipline is enforceable and creator-controlled, delivery accuracy is measured objectively, and every peer agrees on the numbers. --- ## Load-bearing architecture (verified against source) - **Tickets are list items.** `normalizeListItem` (`listam-packages/packages/domain/list-reducer.mjs:17`) spreads `...item` before stamping the three required fields (`text`, `isDone`, `timeOfCompletion`), so **arbitrary extra fields survive the reduction untouched**. A ticket is a list item with `listType:'kanban'` + extra optional fields. No new op types, and **no `LIST_OPERATION_VERSION` bump** (stays `1`; ops with `version>1` are dropped — keep it 1 for forward-compat with old peers). - **`RPC_UPDATE` already passes extra fields through** (`item.mjs:156` spreads `...item`), but **`addItem(text, listId, listType)` discards everything but `text`** (`item.mjs:98`). → `addItem` and the `RPC_ADD` handler must be extended to carry ticket fields. This is the one unavoidable backend change for ticket creation. - **LWW on `updatedAt`.** `isStaleUpdate` (`identity.mjs`) drops any update with a lower `updatedAt`. **Every** ticket mutation (drag, block edit, checklist toggle, property edit) MUST set `updatedAt: Date.now()`. Forgetting this is the #1 silent-no-op bug. - **Owner-signed shared state precedent:** `membership.mjs` — `ownerAuthorityKeyPair`, owner check `canCreateMembershipInvite(state, ownerAuthorityKeyPair)`, records persisted to the view as `{op:'membership', record}`, rebuilt via `reduceMembershipLog` + `view-checkpoint.mjs` (returns `{items, membershipRecords}`), and `normalizeViewEntry` ignores `op:'membership'` (`list-reducer.mjs:158`) so control records never pollute the item reduction. Board config will mirror this exactly. - **New `RPC_MESSAGE` types need no client change** — the client adapter forwards unknown `{type}` payloads as a generic event. - **Writes are serialized** through `enqueueWrite` and gated by `waitForFlushableWriter` (`item.mjs:72,31`) — reuse, don't bypass. --- ## Data model — ticket fields (all optional; absence = legacy/non-rigor) Added to `NormalizedListItem` typing in `listam-packages/packages/domain/list-reducer.d.ts` (declared as an exported `KanbanFields`; carried via the existing catch-all at runtime): | Field | Type | Notes | |---|---|---| | `status` | `'todo'\|'in_progress'\|'blocked'\|'review'\|'done'` | board column. Keep `isDone = (status==='done')` so legacy UIs still read done-ness. | | `description` | `string` | rigor-required (short description). | | `checklist` | `{id,text,done}[]` | rigor-required (≥1). | | `estimatedHours` | `number` | rigor-required (>0). | | `estimatedComplexity` | `number` (1–100) | rigor-required. | | `priority` | `'low'\|'medium'\|'high'\|'urgent'` | optional. | | `assignee` | `string` (writer-key hex) | optional. | | `createdBy` / `completedBy` | `string` (writer-key hex) | attribution, stamped write-side. | | `inProgressMs` | `number` | cumulative accumulator. | | `inProgressSince` | `number\|null` | wall-clock ms of current in-progress entry. | | `actualInProgressHours` | `number` | frozen at Done. | | `timeliness` | `'on_time'\|'overtime'\|'undertime'` | frozen at Done. | | `blocks` | `Block[]` | block-based body (see below). | | `kanbanVersion` | `number` (=1) | field-level marker, independent of op version. | `Block = {id, type, ...payload}`, `type ∈ {markdown, image, table, links, checklist, numberedList, callout, code}`. --- ## Board configuration — one owner-signed record (creator authority) New module **`listam-packages/packages/backend/lib/board-config.mjs`** (models `membership.mjs`). A single owner-signed record holds the whole board config (this is also what the Properties/States/Automations/Rules mock edits): ``` { type:'board-config', version:1, sequence, ownerAuthorityKey, createdAt, rigorOn: true, // default ON states: [{id,name,color,wipLimit,isDone}], // board columns properties: [{key,label,kind,options}], // ticket fields/property rail rules: [{id,kind,params,enforce:'block'|'warn'}], // WIP, required-owner, done-gate, blocked-reason, rigor-required automations:[{id,trigger,actions,enabled}], // on-done→freeze timeliness/archive, urgent→notify, etc. signature } ``` - `createBoardConfigState()` → defaults (`rigorOn:true`, the 4 default states, built-in rules/automations). Absence of any record = defaults (rigor ON). - `createBoardConfigRecord({ownerAuthorityKeyPair, baseKey, config, sequence, createdAt})` — signs the canonical body with the creator's authority secret (same canonicalization as `membershipSigningPayload`). - `reduceBoardConfigOperation(record, state, {baseKey, ownerAuthorityKey})` — `verify` against `body.ownerAuthorityKey`; accept only if it equals the membership's `ownerAuthorityKey` (the **board creator**); reject wrong-base / replay (`sequence ≤ highest`) / bad-signature. **This is how non-creators are prevented — purely cryptographic, no client trust.** - `reduceBoardConfigLog(records, opts)` — rebuild after restart. - `isBoardConfigRecord(value)`. **Wiring:** - `apply()` (`backend.mjs`): after the membership branch, handle `isBoardConfigRecord(value)` → reduce, `setBoardConfigState`, persist `{op:'board-config', record}`, broadcast. - `view-checkpoint.mjs`: collect `entry.op === 'board-config'` into a `boardConfigRecords[]` (alongside `membershipRecords`), keep it out of the item reduction (add the guard in `normalizeViewEntry` like `op:'membership'`). - `state.mjs`: add `boardConfigState` + setter (default config), rebuilt on restart via a new `readPersistedBoardConfigRecords()` in `item.mjs` (mirrors `readPersistedMembershipRecords`). - Owner-only mutation RPC (below); non-owner attempts → `notifyFrontend({type:'config-denied',reason:'not-owner'})`. --- ## Shared domain logic — `listam-packages/packages/domain/kanban.mjs` (NEW, pure) Single source of truth, callable by backend AND any frontend, fully unit-testable: - `DEFAULT_BOARD_CONFIG`. - `validateTicketDraft(item, config)` → `{ok, missing[]}`. When `config.rigorOn`, requires description, checklist≥1, estimatedHours>0, estimatedComplexity∈[1,100]. Enforced on **add** only (never on update, so status changes of legacy/grandfathered tickets are never rejected). - `applyStatusTransition(existing, incoming, now)` → mutated fields. On entering `in_progress`: set `inProgressSince=now`. On leaving: `inProgressMs += max(0, now − inProgressSince)` (clamp negative skew; cap a single slice to bound garbage), clear `inProgressSince`. On entering `done`: flush the open slice, set `actualInProgressHours = inProgressMs/3.6e6`, compute `delta`, freeze `timeliness`, set `isDone:true`, `timeOfCompletion:now`, `completedBy`. Reopen (`done→in_progress`) re-arms; re-completion recomputes. - `computeCongruency(tickets)` → per-user stats grouped by `completedBy ?? createdBy`: - `N` = completed count; `avgComplexityPct` = mean(`estimatedComplexity`); `offEstimateRatePct` = 100·(#overtime + #undertime)/N — the share that missed the estimate in **either** direction (i.e. `100 − onTimeRate`). - `gap = |avgComplexityPct − offEstimateRatePct|`; `raw = 100 − gap`. - **Volume shrinkage** toward neutral 50: `score = round(50 + (raw − 50)·N/(N+5))`. - Also emit `onTime/over/under` counts and an optional `tendency` (`underestimates|overestimates|calibrated`, from #overtime vs #undertime) for display. - `evaluateRules(config, nextItem, prevItem)` → `{blocked[], warnings[]}` (WIP limit, required-owner-in-active, done-gate "no open checklist items", blocked-needs-reason). **Timeliness/time are frozen at the source writer** (in `applyStatusTransition`, called by `updateItem`) — only the writer that owns the wall clock computes its own elapsed slice; every peer then receives the frozen verdict verbatim and agrees. Cross-writer clock skew is clamped; concurrent in-progress exits can lose one increment under LWW (documented limitation, acceptable — no counter-CRDT). --- ## Backend changes (summary) `listam-packages/packages/`: - **`protocol/index.mjs` (+`.d.ts`)** — add `RPC_SET_BOARD_CONFIG = 22`, `RPC_GET_BOARD_CONFIG = 23`. (Ticket CRUD reuses `RPC_ADD/UPDATE/DELETE`.) Bump package version. - **`backend/lib/item.mjs`**: - Extend `addItem` to accept optional ticket fields (merge onto the constructed item; stamp `createdBy = autobase.local.key.toString('hex')`, `status` default `todo`). - In `updateItem`, diff incoming vs `currentList` status and run `applyStatusTransition` (time accumulation + timeliness freeze + `completedBy`). - `readPersistedBoardConfigRecords()`. - **`backend/lib/board-config.mjs`** (NEW) — owner-signed config (above). - **`backend/backend.mjs`** — `apply()` board-config branch + rigor add-gate (read reduced `boardConfigState.rigorOn`; **fail OPEN** when indeterminate so a write is never permanently dropped); `RPC_SET_BOARD_CONFIG` handler guarded by `canCreateMembershipInvite(membershipState, ownerAuthorityKeyPair)`; `RPC_GET_BOARD_CONFIG`. - **`backend/lib/view-checkpoint.mjs`** — collect `op:'board-config'` records. - **`domain/kanban.mjs`** (NEW), **`domain/list-reducer.d.ts`** (types), **`domain/identity`** (no change). - **Attribution caveat:** `createdBy/completedBy/assignee` are self-asserted (honest-client). The rigor *rule* is signature-enforced; per-ticket attribution is not. Upgrade path if non-repudiation is later needed: derive from `node.from` in `apply()` (currently discarded). --- ## Desktop UI changes — `listam-desktop/src/` New pure module **`src/ticket.mjs`** (selectors/helpers; keeps `ui.mjs` presentational and re-exports the shared `@listam/domain/kanban` math): `isTicket`, `isKanbanList`, `groupByStatus(items, states)`, `ticketBadges(item, now)`, `selectBoardConfig(state)`, `selectWriterStats(items)` (delegates to `computeCongruency`), `validateRigorDraft`. **`src/ui.mjs`:** - `ui` object: add `view` values `'board'|'congruency'`, plus `selectedTicketId`, `ticketDocId`, `boardDrag`, `blockEditingId` (UI-local, **not** store state — keeps drag off the re-render path). - `RAIL_DEFS`: add `{key:'board', icon:'layout-columns', …}`; badge = in-progress count. `SYSTEM_DEFS`: add `{key:'congruency', icon:'gauge', …}`. - `renderMain` dispatch: `if (ui.ticketDocId) renderTicketFull`; `if view==='board' renderBoardPane`; `if view==='congruency' renderCongruencyPane`. - `renderBoardPane` → columns from `groupByStatus`; `renderBoardColumn`; `renderTicketCard` (priority pill, assignee avatar, due, checklist count, **in-progress timer**, **on-time/ overtime/undertime badge** when done). Reuse `rowAnimationClass` but **suppress while `ui.boardDrag` is set**. - Detail: three shared pure builders used by BOTH presentations (no duplication): `renderTicketSummary`, `renderTicketBody` (block renderer), `renderPropertyRail` (Shared-with pinned top, then properties). `renderTicketSplitPanel` (right aside, board shrinks to `1fr 420px`) and `renderTicketFull` (full-canvas `.ticket-doc` grid) compose them. - **Block editor** (`renderTicketBody`): `BLOCK_RENDERERS` dispatch for the 8 types; hover `.block-gutter` with `+`/drag handle; `/` opens `.block-slash-menu`; all edits persist via one `commitBlocks(item, next)` → `RPC_UPDATE` with `updatedAt`. Live markdown = minimal subset (bold/italic/`code`/links) rendered from a `