kadence 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,520 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.5.0] — 2026-09-16
+
+**The second author.** kadence was built for a team, and until now its first
+run spoke to one person with a sprint. This release is the path the second
+person walks: their agent learns to write the why, a machine without kadence
+gets an install hint instead of an error, and the first screens talk about the
+work and its decisions rather than points. Reports are still here; they are
+just no longer the first thing anyone meets.
+
+### Added — the teammate path
+
+- **The section `init` writes into `AGENTS.md` and `CLAUDE.md` teaches writes,
+  not only reads.** `task claim`, `note "…" --task`, and `decision add "…" --why`
+  sit beside the read commands, plus one line for an agent on a machine where
+  `kadence` is not on PATH: ask the human to install it; `npx` needs the network
+  and that is their call. Still 23 lines and 1.2 KB, under a test of 25 lines and
+  2 KB; an older section is replaced in place by its version marker.
+- **The `SessionStart` hook survives a machine without kadence.** It runs
+  `kadence prime` when the binary is there and otherwise prints one line asking
+  the human to install it, exiting 0 (DEC-12: no `npx`, because a hook written by
+  `init` must not download code on a teammate's machine). `init --hooks` upgrades
+  the old `kadence prime` hook in place instead of adding a second.
+- **`.kadence/README.md` leads to decisions and teammates.** `decision list` and
+  `decision add` replace `sprint status` among the top commands, and a new
+  "Adding a teammate" section covers install, one `user.email` per person and
+  `KADENCE_SOURCE=agent`. Existing READMEs are still never overwritten.
+- **README: the first ten minutes, "Adding a teammate" and "Removing kadence"** —
+  the last one lists everything `init` touches, so leaving is a table, not a
+  guess. Sprints, reports and exports moved to `docs/reports.md`.
+
+### Changed — the first run speaks about the work
+
+- **`init`** suggests a first task *and* a first decision, names what to commit
+  so a teammate's agent finds it, and mentions `--hooks` when `.claude/` exists.
+- **`prime`** no longer opens with "No active sprint." when there is none; with
+  no decision in force it shows one line on how to record one. `--json` unchanged.
+- **`task add` without `--estimate`** says nothing outside a sprint; inside one it
+  names the sprint instead of velocity. `sprint add` says the same.
+- **`kadence --help`** lists commands in the order a session meets them: `init,
+  prime, ready, task, decision, note, board, ui, schema`, then planning, reports
+  and maintenance.
+- **The TUI header** without a sprint reads `N open · M ready · K decisions in
+  force`; points appear only when something is estimated.
+- **`report --list`** puts `attention` first and groups burndown, velocity and
+  workload under "Sprint and team".
+
+### Fixed — the contract
+
+- **`schema --json` lists every shipped command.** 21 entries were missing,
+  among them `sprint add/edit/start/list/burndown`, `task parent/unblock/cancel/delete`,
+  `template`, `completion` and `ui` — additive within `kadence/v1`. A test now
+  compares the binary's own commands and actions against the contract and fails
+  on any gap. Unknown `decision` actions now return `allowed`, and `task` lists
+  `doc` in it.
+
+### Tooling
+
+- **`scripts/north-star.mjs`** counts repositories with two authors fourteen days
+  after their first event — `--local` for a checkout, `--search` through `gh` for
+  public ones — and appends a weekly row to `docs/research/north-star-log.md`.
+  A maintainer script: the product itself still opens no socket. First row: 0,
+  with the reason GitHub code search has not indexed even this repository.
+
+---
+
+The command reference stops being prose. And the first two bugs found by using
+the product on itself.
+
+### Added
+
+- **`kadence report` is the whole catalogue.** `report burndown`, `report
+  velocity` and `report workload` join `flow`, `cfd` and `attention`, and
+  `report --list` names all six with what each one answers.
+
+  The folds were already here — the burndown under `sprint`, the workload
+  inside `stats` — so an agent reading `schema --json` could not find them and
+  `kadence report` was not the catalogue it looked like. `report burndown`
+  calls the same function `sprint burndown` does, resolved in one place, so the
+  two cannot drift. `report velocity` is new arithmetic over `sprintReport`,
+  and it answers with a range rather than an average (DEC-9): the spread
+  between sprints is the forecast, and a series shorter than four sprints says
+  so. `report workload` counts open tasks, points, work in progress and blocked
+  work per owner, with a row for unassigned work — no hours, no capacity, since
+  the journal has neither.
+
+  `--since` on a report that has no window, or `--sprint` on anything but the
+  burndown, is now an error rather than a silently ignored flag (DEC-10).
+
+- **`kadence report <name> --html`** — a report as one self-contained page, with
+  charts. `flow` gets a percentile dot plot, a created-vs-finished column chart
+  and an aging-work chart with the p85 cycle time drawn as a reference line;
+  `cfd` gets a stacked area chart with the bands named where they are wide
+  enough; `attention` gets the idle days against the threshold. `--file` puts it
+  where you want it, and with `--json` the response is the path, not the report.
+
+  The charts are hand-written inline SVG. Every chart library is a script tag,
+  and the page's one promise is the one the board export already makes: it opens
+  from disk and asks the network for nothing — asserted structurally, down to
+  `url(` in the stylesheet and the `xmlns` an inline `<svg>` does not need.
+  Measured at 0.1 ms and 14 KB for the flow page, 1.7 ms and 301 KB for a
+  two-year cumulative flow diagram. Every chart is followed by the rows it was
+  drawn from: three of the eight categorical colours sit below 3:1 against
+  white, and the rule that buys them is that colour is never the only channel.
+
+  Reasoning in DEC-7 (a page per report rather than a Reports section inside the
+  board export — a report is a question with a window, and the board export has
+  none) and DEC-8 (the charts).
+
+- **`kadence schema --json` and every `--help` now have a machine-readable
+  sibling.** `npm run reference` writes `dist/reference.json`: every command,
+  its usage line, its flags with their descriptions, its examples, and the
+  whole agent contract, read out of the binary rather than written about it.
+  The release workflow attaches it to the GitHub release of each tag.
+
+  This exists because the hand-typed CLI page on the site described 0.3 for the
+  whole of 0.4 — nine commands and two dozen flags shipped without it noticing,
+  and the agents page named ten of the fifteen error codes. A paragraph has no
+  test. A test now reads `src/cli/commands/` and fails when a command file has
+  no help behind it, which is the only way that gap stays closed.
+
+  The generator ships in the package rather than its output: measured at 1.9 KB
+  packed against 6.2 KB, and 4.9 KB unpacked against 39.7 KB, for the same
+  result. Nothing in the data is unavailable from the CLI itself.
+
+- **`scripts/kadence.mjs`** — runs the build in this working tree, rebuilding
+  when `src/` is newer. For working on kadence with kadence, which is now how
+  this repository is run; `CLAUDE.md` says what that means in practice.
+
+### Fixed
+
+- **`burndown.finalRemaining` was always `null`.** Both branches of
+  `sprint.status === 'closed' ? null : null` read the same, so the one number
+  the field exists for — what a closed sprint did not finish — was never in the
+  response, including in `sprint burndown --json`. It now carries the points
+  left on the sprint's last day.
+
+- **A repeated flag crashed `decision add`.** `--rejected A --rejected B` threw
+  `o.rejected.trim is not a function`: cac hands a single flag back as a string
+  and a repeat as an array, and only `--doc` was normalised for it. The four
+  single-value flags went into `.trim()` as arrays.
+
+  Repeats now mean what each flag means. A second `--why`, `--task` or
+  `--supersedes` is a correction, so the last wins; a second `--rejected` is a
+  second alternative that was turned down — which is what a decision record is
+  for — so both are kept, joined rather than stored as an array because
+  `rejected` is a string in `kadence/v1` and the contract only ever gains
+  fields.
+
+  Found by recording a real decision about this repository with two rejected
+  options, with 898 tests green. The tests for it go through the built binary,
+  because calling the command directly is exactly the path that could not see
+  it.
+
+### Notes
+
+Deleting several tasks by `KAD-N` in one loop removes the wrong ones. Labels
+are derived while folding (I7), so removing `KAD-1` renumbers everything after
+it and the next label in the list now belongs to a different task. Working as
+designed, and a sharp edge: delete by ULID, or one at a time. Recorded as a
+note in this repository's own journal rather than fixed, because the fix is not
+obvious — warning on a bulk delete of labels would fire on the common case too.
+
+A board-wide Definition of Done is engineering-shaped. `board config --dod`
+copies its criteria into every new task, so "typecheck clean" landed on the
+Probe B interview tasks, where it means nothing, and there is no `task ac
+remove` to take it off. Noted, not yet answered.
+
+## [0.4.1] — 2026-09-13
+
+`0.4.0` was tagged and never published: these three were found by using it
+before it reached anyone, so `0.4.1` is the first published 0.4. Nothing below
+changes the shape of an event or renames a field in `kadence/v1`.
+
+### Fixed
+
+- **The fold dropped who wrote a comment or a history line.** Every event
+  carries `source` — `"human"` or `"agent"`, from `KADENCE_SOURCE` — and it is
+  validated on read, but the projection kept it only on decisions and notes. So
+  `task show` printed an agent's comment exactly like a person's, and
+  `task show --json` gave an agent no way to tell them apart: `actor` is the git
+  identity, which a person and their agent share. The one surface the product's
+  headline is about could not show the thing it claims. Comments and history
+  entries now carry `source`, `task show` marks an agent's line `[agent]` the
+  way `decision list` already did, and a note shows the mark it always knew.
+  The snapshot shape test now records nested records too — it is what should
+  have failed when `source` reached the event and not the comment. Cache version
+  bumped to `kadence-snapshot/11`.
+- **`kadence ready` offered work that had already started.** The filter knew
+  about finished, blocked-by and claimed-by-others, and nothing about the board:
+  a task sitting in `in_review`, or parked in the `blocked` column, was listed
+  first with `kadence task claim KAD-1` printed under it. An agent following
+  `prime → ready → claim` took work somebody was reviewing. Ready now means
+  ready to *start* — anything in the started column or past it is left out,
+  using the board's own boundary, so a team that renames its columns keeps a
+  `ready` that means what its board means. When that is why the list is empty,
+  the message says so: `Nothing ready (2 already started)`.
+- **The performance fixture moved all 500 tasks into `in_progress`**, so the
+  `ready` guardrail was timing a filter over an empty answer and asserting only
+  that it was fast. Every third move parks a task back in `todo` now; the
+  guardrail times a real result.
+
+## [0.4.0] — 2026-09-13
+
+Planned as slices 0.4.0 through 0.4.4 and published as one minor release.
+
+The agent loop: four commands that answer "what next" without folding the whole
+board by hand. Everything here is additive within `kadence/v1` — no field or
+command was renamed, and `--json` responses gain keys rather than losing them.
+
+### Added
+
+- **`kadence ready`** — open tasks with no live blockers, not claimed by anyone
+  else, priority first and age second. `--json` returns five fields per task
+  rather than the whole record, because this goes into an agent's context on
+  every session. An empty result names the reason: how many are blocked, how
+  many belong to someone else. Measured at 9 ms over 10,000 events.
+- **`kadence prime`** — the session preamble: active sprint and days left, your
+  claimed and in-progress work, how many tasks are ready, decisions in force by
+  title, the last five notes, and four commands to go deeper. Held to 40 lines
+  and 3 KB by a test; 16 lines and 493 bytes on this repository. It carries the
+  part that changes and points at the part that does not, because the static
+  half already lives in `AGENTS.md`.
+- **`kadence init --hooks`** — adds a `SessionStart` hook running `kadence prime`
+  to `.claude/settings.json`. Only with the flag: that file belongs to the user
+  and is committed to their repository. The write is an upsert — hooks of other
+  events, other matchers and other commands survive, running it twice leaves one
+  hook, and a file that does not parse is reported rather than replaced.
+- **`kadence task claim` / `task release`** — take a task, or give it back.
+  `claim` with no argument takes the top of `ready`, which is one step instead
+  of two. There is **no lock**, and the message says so: two machines can each
+  claim before either pushes. See [ADR-011](docs/decisions/011-claims-as-events.md).
+- **`kadence note "text" [--task KAD-1]`** and `note list` — something learned
+  that was never a choice. Deliberately not a decision: no `--why`, no
+  `supersedes`, no number. The help says when to reach for `decision add`
+  instead. Notes show up in `task show` and in `prime`.
+- **`claimedBy` and `contestedBy`** on the task record in `--json`, and a
+  `Claimed:` line in `task show`.
+- **TUI**: `R` shows only what can be started now, `C` claims the selected task
+  or releases it if it is yours, and a card carries a claim mark — a separate
+  colour when the claim is contested. Both actions call the same functions the
+  CLI does.
+
+### Changed
+
+- **A contested claim is reported, not rejected.** When two people claim one
+  task, the earliest by ULID holds and the later one is kept, with the task
+  reading `contested` under both names. Rejecting the second would make the
+  owner depend on which branch merged first — the same invariant that keeps
+  dependency cycles and orphaned status columns alive rather than dropped. It is
+  the first conflict in kadence that names people rather than values.
+- **The state cache version moved from 2 to 4.** The projected shape changed
+  twice: three claim fields on a task, then notes on the project state. Missing
+  exactly this bump is what shipped as a bug in 0.3.1, so it is now pinned to
+  the field lists by a test.
+- The agent section written into `AGENTS.md` and `CLAUDE.md` grew by one line —
+  `kadence prime` first — and by no more than that.
+
+### Added — the branch, the human, and the evidence behind done (0.4.1)
+
+- **`kadence task list --branch`** — the work this branch introduced, measured
+  against `--base` (`main`, or `init.defaultBranch`). Membership is derived from
+  git at read time and never stored: writing a branch name into an event would
+  go stale the moment the branch is renamed or merged, and would make the same
+  events fold differently depending on where they were written. A detached HEAD
+  and an unknown base both fail by name rather than reporting no work.
+  The measurement that justified the flag, including what would make it wrong,
+  is in [branch-context-2026-09.md](docs/research/branch-context-2026-09.md).
+- **Acceptance criteria** — `task ac add|check|uncheck|list`. The number is a
+  position in the folded list, assigned like `KAD-N` and never stored, so two
+  branches can each add a criterion and merge without renumbering. Moving a task
+  to `done` with unchecked criteria **warns and proceeds**: the checklist is
+  evidence, not a gate, and refusing would make the board lie about where the
+  work is.
+- **Definition of done** — `board config --dod "tests green,docs updated"`. The
+  criteria are **copied** into each new task, never referenced, so raising the
+  standard cannot reach back and change what finished work had promised.
+  `task add --no-dod` skips them.
+- **Milestones** — `milestone create|add|list|close`. Grouping by outcome, where
+  an epic groups by structure and a sprint by time. Not a third hierarchy: a
+  task carries at most one, as a field beside `sprint`. `MS-N` is derived from
+  ULID order like every other label, and progress is counted in points, the same
+  unit as velocity and burndown.
+- **`kadence stats`** — counts by status and assignee, open blockers, contested
+  claims, and the velocity of the last three closed sprints.
+- **`kadence completion install`** — zsh, bash and fish, generated from one list
+  rather than three hand-written scripts. Without a terminal it prints the
+  script instead of writing, because that is how people pipe it into a file.
+  For zsh it writes the file and prints the `fpath` line rather than editing a
+  shell rc, which is the user's file.
+- **`board --json --summary`** — the column state without `history` and
+  `comments`. Those are the two fields that grow with how long a task has been
+  worked on rather than with how many tasks there are.
+- **TUI**: `b` shows only what the branch introduced, `M` filters to one
+  milestone, and the card dialog carries the acceptance-criteria checklist with
+  space to toggle. Every toggle calls the same command the CLI does.
+
+### Changed
+
+- `task list --json` and `board --json` gain a `milestone` field on each task,
+  carrying the `MS-N` label. The response without `--summary` is otherwise
+  unchanged; the contract only ever gains.
+- The state cache version moved again with the projected shape.
+
+### Added — reports, and the two things they needed first (0.4.3)
+
+What the neighbours call reports is, here, a fold over timestamps the journal
+already carries. The reasoning, the sources and the verdict per report are in
+[reports-discovery-2026-09.md](docs/research/reports-discovery-2026-09.md).
+Velocity and cycle time stay out of the headline; they are a consequence, served
+to the person who asks.
+
+- **`kadence report flow`** — the four flow metrics the Kanban Guide mandates,
+  and what sits around them: work in progress, throughput per ISO week, cycle /
+  lead / response time as **p50 / p85 / p95 in calendar days**, aging work
+  against the p85, created versus resolved, and days spent blocked. There is no
+  mean anywhere, on purpose. Every response names the window and the column
+  work counts as started from, so a number is never quoted without its terms.
+  Empty sections say why they are empty.
+- **`kadence report cfd`** — tasks per column at the end of every day of the
+  window. A move backwards subtracts. The first version re-walked each task's
+  history per day and cost 150 ms on 10,000 events; it is a single pass now, at
+  4 ms.
+- **`kadence board config --started <status>`** — the column cycle time and a
+  sprint's actual hours are measured from. It was the literal `in_progress` in
+  three places while columns were configurable, so a board named
+  `todo,doing,review,done` closed every sprint with `actualHours: null` and
+  never said why. It is a folded setting now, validated against the live
+  columns, and a column change that strands it warns instead of going quiet.
+- **`kadence compact`** — folds months older than `--keep-months` into one
+  archive file each. The primitive existed since 0.1 and was reachable only from
+  tests. `--dry-run` says what would move and writes nothing. It touches no git
+  state, and it says the one thing worth knowing: an archived month is a single
+  file, so compact on one branch and merge before compacting on another.
+
+### Added — three experiments (0.4.2)
+
+Each of these was a standing "no". Each is now tried in the shape that survives
+the three constraints, and each has a kill condition written before the code, in
+[feature-adoption-2026-09.md](docs/product/feature-adoption-2026-09.md).
+
+- **`kadence board export --html`** — the board, the sprint, the burndown,
+  milestones and decisions in force, as **one self-contained file**. No script
+  tag, no stylesheet link, no font, no image: the page asks the network for
+  nothing and opens from disk. That is what makes it an experiment in place of a
+  web UI rather than a web UI with extra steps. A test asserts the absence, not
+  the appearance. Acceptance criteria are printed in full rather than counted,
+  because a file attached to a pull request is evidence and "2/3" is not.
+- **`kadence board export --md`**, and `--readme` to update the section between
+  markers in an existing README. It will not create one — that would be a
+  different command and a bigger promise.
+- **`@kadence/github`** — a separate package that publishes tasks to GitHub
+  Issues **in one direction**, by shelling out to `gh`. The core is unchanged
+  and still opens no socket; the credential stays with a tool the user already
+  trusts. A marker in the issue body makes a second publish an edit rather than
+  a duplicate, and the issue itself says that edits made there are overwritten.
+  Nothing is ever read back. See
+  [ADR-012](docs/decisions/012-network-only-in-packages.md), written before the
+  code. Every test runs against a recorded `gh`, never the real one.
+- **`kadence task doc add KAD-1 docs/design.md`** — creates the file from a
+  four-line template and records the link in one call. It never overwrites: a
+  file that is already there is the document, and replacing it with a template
+  would destroy the thing being linked.
+
+### Added — attention signals, and labels that survive a merge (0.4.4)
+
+- **`kadence report attention`** — work the board presents as active while
+  nobody is moving it. Four signals, one definition: `stalled` (no event for N
+  days), `unowned` (in flight for N days with no assignee and no claim),
+  `stale_claim` (a claim older than N days with no move since), and
+  `dead_blocker` (`blockedBy` pointing at a finished task — the one signal that
+  waits for no threshold). `--since` is the days of silence, default 7. No new
+  event type, no new field: the report is a fold over what the journal already
+  holds, and it costs 0.5 ms over 10,000 events on top of the fold.
+
+  Two candidates were left out on purpose and the module says why. "Open task
+  with no owner" is the definition of a backlog. "Criteria added and never
+  checked" would fire on every task in any repository that configured a
+  Definition of Done, because `task add` copies it in unchecked — loudest in
+  the repositories that took our advice.
+- **`prime` carries an attention line** — up to three tasks, and only when
+  there is something to say.
+- **`task.label_added` / `task.label_removed`** — labels move as deltas. This
+  was the one field where "every intent is preserved" was untrue: `task.updated`
+  carried the whole array and the fold replaced the whole array, so two branches
+  adding different labels merged without a conflict and one label vanished with
+  no warning. Not a merge failure — a fold storing *state* in an event, the
+  exact mistake the product exists to avoid. Reasoning in
+  [ADR-013](docs/decisions/013-labels-as-deltas.md).
+- **`labels` in `ready --json`**, the seventh field, and in the guaranteed set.
+
+Source for this slice: a tech lead's feedback of 2026-09-10 — drift comes not
+from where state lives but from work that stops being watched. Append-only
+removes the drift between board and journal; it promises nothing about the
+drift between journal and reality. The README now says so.
+
+### Fixed before release
+
+- **`compact` could destroy an archive it had already written.** A branch that
+  compacts a month, merges, and then delivers one more event for that month
+  gets a fresh month directory beside the archive — `append` files an event by
+  its own timestamp. The second compaction replaced the archive with the
+  directory's contents alone. Reproduced: three events became one, silently, in
+  a journal whose one promise is that nothing is lost. Archives are merged by
+  id now, and the dry run counts only what is not archived yet. The primitive
+  had been this way since 0.1; this release is what made it reachable.
+- **A reopened task stayed `done` on the cumulative flow chart** and was not
+  counted as work in progress, because `task.reopened` moves a task without a
+  `task.moved`. Both now follow it.
+- **A finished task went on accruing blocked days.** Work that is over is not
+  blocked, whatever its blocker is doing.
+- **A started boundary that is not one of the columns inflated work in progress**
+  instead of emptying the report — the default state of every board that renames
+  `in_progress`, and the opposite of what `board config` warns.
+- **`--started` was dropped when given with `--statuses` or `--dod`**, which is
+  the natural first command on a custom board. It travels in the same event now,
+  validated against the list being set.
+- **The sprint report and `report flow` disagreed about what counts as started.**
+  A task that skipped the started column had a cycle time in one and no actual
+  hours in the other. One definition serves both.
+- **A deferred `task.reopened` read the boundary as of the end of the fold**
+  rather than as of its own position in ULID order. Resolved the way claims and
+  criteria already are.
+- `--started done` was accepted, `--since 007` became 7 before the parser saw
+  it, `--keep-months abc` reported "NaN", and nothing said the dates are UTC.
+- **The "cold start" performance figure was a warm one.** The perf test removed
+  the state cache once, then took the best of three runs — the first run built
+  the cache and the next two read it, so "11 ms cold" was a 12 ms warm read.
+  Measured with the cache removed before every run: **199 ms cold when every
+  event is a separate file, 21 ms cold with a compacted archive.** The first of
+  those is the budget itself, with no room. The test now removes the cache per
+  iteration, the README carries the honest numbers, and the finding feeds the
+  reports work: compaction exists in the core but is not yet a command anyone
+  can run.
+- **Two commands could write outside the repository.** `task doc add` and
+  `board export --file` both described containment in a comment and did not
+  enforce it: `../pwned.md` created a file in the parent directory, and the doc
+  link went into the append-only journal as a path meaningless on any other
+  machine. Both now resolve and verify before anything is written.
+- **A task title containing the board end marker corrupted README.md**, and the
+  corruption grew by one copy on every export. The marker is now neutralised
+  where text enters, and the end marker is searched for after the begin marker
+  rather than from the top of the file.
+- **A failed `gh issue list` read as "no issue exists"**, so a rate limit
+  created a duplicate and reported success. The lookup is now a value rather
+  than an absence, and runs once for the batch instead of once per task.
+- **A batch that failed halfway said nothing about what was already
+  published**, and the JSON path discarded the partial record entirely. Both now
+  name it.
+- **`@kadence/github` was never typechecked or built in CI** — nothing imports
+  its entry point, so the root config never saw it. That is why two of the bugs
+  above survived to review. CI now gates the package, and greps the core bundle
+  for network imports.
+- Decisions and milestones vanished from an export of a board with no tasks yet.
+- A `|` in a configured status broke the Markdown table.
+- **Three event types were dropped instead of held pending.**
+  `milestone.task_added`, `milestone.closed` and `task.criterion_checked` were
+  handled as they arrived, so an event carrying a lower ULID than the entity it
+  names vanished — no `pending`, no `rejected`, no trace. Reachable for the same
+  reason claims are: clocks disagree between machines, so an assignment written
+  on a lagging clock sorts before the `task.created` it refers to. Milestone
+  events now go through the same defer path every task event uses, and criterion
+  checked-state is folded from the task's history, where the order is ULID order.
+- **`completion install` could overwrite a file it did not write.** Every
+  generated script now carries a marker; a file without it is left alone and the
+  command says what is there, with `--force` for the deliberate case. Both target
+  directories are shared — a distribution package writes into the bash one.
+- **The `milestone` field could carry a raw ULID** when the milestone was created
+  on a branch that has not merged. The contract promises `MS-N`; it is now `MS-N`
+  or `null`.
+- `--branch` on a detached HEAD returned `invalid_argument` and exit 2. The flag
+  was understood; the repository state is what refuses, so it is
+  `conflicting_state` and exit 1.
+- `--summary` omitted `contestedBy`, so a contested task read as a cleanly owned
+  one in the response large boards are steered towards.
+- Acceptance criteria were reachable only through `task show`, which made
+  "which tasks have unchecked criteria" cost one call per task. `criteria` and
+  `openCriteria` are now on every task record.
+
+### Notes
+
+The plan set a target of 80 KB for `--summary` on a 1000-task board, taken from
+Probe C. **That target was wrong, and the measurement says so:** a full board of
+1000 tasks is 855 KB, `--summary` is 275 KB, and even the narrowest useful set
+of three fields is 104 KB. Task titles are irreducible — 1000 of them do not fit
+in 80 KB. The property the flag actually exists for is a different one and it
+holds: a summary record costs the same whether the task carries one event or
+five hundred, while the full record grows past fifty times the size. That is
+what the test pins.
+
+### Notes
+
+The bundle grew from 35 KB to 71 KB across 0.4. The export templates sit in the
+fast path rather than behind a dynamic import, and that was measured rather than
+assumed: reading the whole bundle costs under a millisecond, and every
+non-interactive command still runs in about 100 ms against a 200 ms budget. The
+lazy-import rule exists for `blessed`, a heavy third-party dependency that reads
+terminfo at runtime — not for 16 KB of our own strings. `blessed` is still absent
+from `dist/cli.js`.
+
+At release the build prints an 82 KB bundle, `npm pack` a 76 KB tarball with
+233 KB unpacked, and `--version` returns in 60–70 ms on this machine; `blessed`
+is still absent from `dist/cli.js`.
+
+Claim state is folded from each task's own history rather than as events
+arrive. It has to be: an event about a task whose `task.created` has not merged
+is replayed after the main loop, so a claim carrying a lower ULID could be
+applied last and hand the task to the wrong person. Reachable rather than
+theoretical, because clocks disagree between machines.
+
+The TUI additions were exercised by hand by the owner on 2026-09-13 before the
+tag, as CLAUDE.md requires: four TUI bugs have shipped past a green suite in
+this project, so a green suite alone is not evidence there.
+
 ## [0.3.2] — 2026-09-09
 
 Nothing in the package changed. `src/`, `scripts/`, `package.json` and the