kadence 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## [0.2.1] — 2026-09-08
+
+> Numbered 0.2.1 because 0.2.0 cannot be published under this name: a different
+> package called `kadence` used that version on 2026-02-05, before this one
+> claimed the name, and npm never allows a version number to be reused. Nothing
+> was released as 0.2.0 — this is the first release of the 0.2 line.
+
+The agent contract, made real. `schema: "kadence/v1"` used to be a version
+string that nothing checked; now the contract is published, the failures are
+machine-readable, and the responses can be narrowed to what an agent actually
+reads. Reasoning in [ADR-009](docs/decisions/009-the-agent-contract.md),
+measurements in [Probe C](docs/research/probe-c-agent-cost.md).
+
+### Added
+
+- `kadence schema --json` — the machine-readable contract behind
+  `schema: "kadence/v1"`: every command, the fields you can rely on, and every
+  error code. It works outside a repository, because an agent asks what the tool
+  does before it has a project to ask about.
+- Failed `--json` calls now carry `error.code` from a closed list, plus
+  `received`, `allowed` and `hint` where each is knowable. `allowed` matters
+  most for statuses: they are configured per project, so an agent cannot learn
+  the valid set from documentation. There is deliberately no `retryable` field —
+  with no network and no lock, the same input always fails the same way.
+- `--fields` on `board --json` and `task list --json`, so an agent can ask for
+  the columns it reads instead of every description. On a 200-task board that is
+  130,799 bytes down to 11,015. An unknown name fails with `unknown_field` and
+  the list of what exists.
+
+### Changed
+
+- **`init` now writes the kadence section into `CLAUDE.md` as well as
+  `AGENTS.md`.** Claude Code does not read `AGENTS.md`, so a repository carrying
+  only the latter was invisible to the largest agent audience — the README's
+  promise that "the AI agent finds it on its own" was not true for them. Text a
+  human wrote in either file is left untouched, and a repeat `init` does not
+  duplicate the section. If you do not want the file, delete it; nothing else
+  depends on it.
+
+### Fixed
+
+- **Any `--json` response larger than the pipe buffer was truncated
+  mid-string.** `process.exit()` does not wait for an asynchronous write to
+  drain, and writing to a pipe — how every agent reads us — is asynchronous,
+  while writing to a file is not. A 200-task board produced 131,072 bytes and a
+  parse error; the same command redirected to a file was valid. Output is now
+  written synchronously.
+
+### Note on the roadmap
+
+`kadence context <task>` will not be built. `task show --json` already returns
+the whole history of one piece of work in 948 bytes, and that number does not
+grow with the project — the only thing left to add was a format nobody has
+asked for.
+
+## [0.1.5] — 2026-09-03
+
+### Changed
+
+- README rewritten to lead with the number the product exists for — what a
+  story point actually costs — instead of a feature list. Claims now carry
+  their evidence inline: the merge thesis links to the 8,396-commit study and
+  to the integration test that proves it, and the performance table says these
+  are tests that fail the build.
+- Repository URLs follow the rename to `bogutskiandriy/kadence`.
+
 ## [0.1.4] — 2026-09-03
 
 ### Fixed

package/README.md

@@ -1,236 +1,262 @@
 # kadence
 
-**Your team plans sprints on gut feel. kadence counts what it actually delivers — from a journal that lives in your repository.**
-
-Tasks, sprints and velocity as plain files inside your git repo. No server, no
-account, no network. Works offline, and works for AI agents because the data is
-just files they can read.
+**Your team and your AI agents work from the same context — it lives in your repo and remembers what the code cannot.**
 
 ```bash
 npm install -g kadence
-
 kadence init
-kadence task add "Fix login" -d "Broken since 2.3" --type bug --estimate 3
-kadence ui        # interactive board, or `kadence board` for a plain list
 ```
 
-> **v0.1.0.** The architecture is measured and covered by 383 tests. The product
-> bet — that teams want sprint analytics in their repo — has not been validated
-> with users yet. See [Honest status](#honest-status).
+No server. No account. No network. Tasks, their whole history and the time they
+took are files next to your code, and they move with your branches.
 
-## Why another tracker
+---
 
-There are good file-based trackers already:
-[git-bug](https://github.com/git-bug/git-bug),
-[Backlog.md](https://github.com/MrLesk/Backlog.md),
-[git-issues](https://steviee.github.io/git-issues/). kadence differs in two ways.
+## The context your code cannot hold
 
-**1. It never conflicts on merge.** The others store a task as a *mutable* file,
-so two branches touching one task collide. kadence stores an append-only journal
-of events: one file per event, never rewritten.
+Your code says **what** exists. `git log` says **when** it changed. Neither says
+what was tried and abandoned, why a task is blocked, or what the team agreed on
+Tuesday.
 
-We measured this rather than assumed it. Across **8,396 merge commits from 130
-public repositories** using file-based trackers, conflicts in task files occur
-in 15% of repositories — and **89% of them are `CONFLICT (content)`**, exactly
-the type this design eliminates. Full data:
-[probe-a-results.md](docs/research/probe-a-results.md).
+That gap costs a human a few minutes. It costs an AI agent the entire session:
+every new one starts from scratch, re-reads the same files and asks the same
+questions you answered yesterday.
 
-**2. It computes velocity.** None of the three tracks sprints, velocity, or how
-estimates compare with reality. kadence derives all of it from the journal, so
-the numbers cannot be forgotten or faked — they are a product of the work.
+kadence keeps that missing layer as an append-only journal — one file per event,
+committed with the code:
 
+```bash
+$ kadence task show KAD-1 --json
 ```
-Sprint "Sprint 12" closed.
 
-  Velocity:  10 of 10 points
-  Actual:    16h — 1.6h per point
+```json
+{
+  "schema": "kadence/v1",
+  "label": "KAD-1",
+  "title": "Fix login",
+  "status": "in_review",
+  "loggedHours": 4.5,
+  "blockedBy": ["KAD-7"],
+  "comments": [
+    { "at": "2026-09-02T09:14:00Z", "by": "ana",
+      "text": "Session cookie is fine — the redirect drops it." }
+  ],
+  "history": [
+    { "at": "2026-09-01T10:02:00Z", "by": "ana",  "type": "task.created" },
+    { "at": "2026-09-01T14:40:00Z", "by": "ana",  "type": "task.moved", "to": "in_progress" },
+    { "at": "2026-09-02T09:20:00Z", "by": "agent","type": "task.blocked_by_added" }
+  ]
+}
 ```
 
-That last number is the point of the whole tool: what a story point actually
-costs your team.
+That is the whole state of a piece of work, in one call, with no server to ask
+and no context to rebuild. A human reads it in `kadence task show`. An AI agent
+reads the same thing as JSON.
 
-## Install
+**And it stays one call.** That answer is 948 bytes whether the project holds ten
+tasks or a thousand — while the journal behind it grows from 5 KB to 528 KB. The
+cost of asking does not grow with the history that makes the answer worth having.
+[Measured](docs/research/probe-c-agent-cost.md).
 
-Requires Node 20 or newer, and a git repository.
+## Why events and not files
 
-Install it once, so the command stays available:
+Every other tool that keeps work in a repository keeps **state**: a task file, a
+row in a database, the current spec. State has three failure modes, and all
+three are why kadence stores **events** instead.
 
-```bash
-npm install -g kadence
-kadence init
-```
+**It drifts.** A spec written on Monday and edited by an agent on Thursday no
+longer says what actually happened. An event cannot drift — it records that
+something occurred, not what is currently true.
 
-Or run it without installing — but note that `npx` fetches the package for that
-one command and leaves nothing behind, so every later call needs `npx` too:
+**It conflicts.** Two people editing one task on two branches is a merge
+conflict in every file-based tracker. Here it is not, by construction: the
+journal is append-only, one file per event.
 
-```bash
-npx kadence init
-npx kadence board
-```
+**It forgets.** Rewriting a task file destroys the previous version. The journal
+keeps every step, so «how did we get here» has an answer.
 
-`init` creates `.kadence/`, adds the derived cache to `.gitignore`, and writes a
-short guide for AI agents. It does **not** commit anything — that call is yours.
+State is still there when you want it — it is folded from the journal on read,
+which is why the board can never drift from reality.
 
-## Commands
+---
 
-```
-kadence init                          set up kadence in this repository
-kadence ui                            interactive kanban board
-
-kadence task add "<title>"            create a task
-    -d, --description <text>         full description
-    --type task|bug|story|epic       type; an epic is simply a parent task
-    --priority low|normal|high|urgent
-    -a, --assignee <who>             assignee
-    --label <name>                   label; repeat for several
-    --due <date>                     deadline, YYYY-MM-DD
-    --parent <task>                  make it a subtask
-    --template <name>                pre-fill from a saved template
-    --estimate <points>              estimate, always last
-kadence task list                     list tasks
-    --search <text>                  title, description and comments
-    --status|--type|--priority|--assignee|--label
-    --overdue  --due-before <date>
-    --sort created|priority|due|estimate
-    --tree                           show parent/child structure
-kadence task show KAD-1              full detail and history
-kadence task edit KAD-1              opens $EDITOR; or pass field flags
-kadence task move KAD-1 done         change state
-kadence task assign KAD-1 <who>      assign; "none" unassigns
-kadence task comment KAD-1 "text"    comment
-kadence task log KAD-1 2h            log time; 90m, -30m to correct
-kadence task parent KAD-2 KAD-1     nest under a parent
-kadence task block KAD-2 KAD-1      KAD-2 waits for KAD-1
-kadence task cancel KAD-1            keeps it in history
-kadence task delete KAD-1            drops it from the board
-
-kadence board                         plain board, one column per status
-    -a, --assignee me                only your tasks
-    --sprint                         only the active sprint
-kadence board config                  show or change the columns
-    --statuses "todo,doing,done"     your own workflow
-
-kadence sprint create "Sprint 1"      first starts now, later ones are planned
-kadence sprint add KAD-1 [--sprint "Sprint 2"]
-kadence sprint start ["Sprint 2"]     start the next planned sprint
-kadence sprint close                  close and report velocity
-kadence sprint status                 progress of the active sprint
-kadence sprint burndown               chart rebuilt from the journal
-kadence sprint list                   every sprint
-
-kadence template save bug --type bug --priority high
-kadence template list | delete <name>
-```
+## Why the merge claim holds
+
+We measured it before building on it.
+
+Across **8,396 merge commits in 130 public repositories** using file-based
+trackers, conflicts in task files hit **15% of repositories** — and **89% are
+`CONFLICT (content)`**, the exact type an append-only journal removes.
 
-Most commands accept several tasks at once — `kadence task move KAD-1,KAD-2 done`
-— and apply **all or nothing**: if one id does not exist, nothing changes.
+Then the other direction: three people editing one task on three branches,
+merged in every order. Zero conflicts, every author preserved, identical final
+state. That is an [integration test](test/integration/merge.test.ts), not a
+claim.
 
-Add `--json` to any command for a stable machine-readable shape.
+Full data: [probe-a-results.md](docs/research/probe-a-results.md).
 
-## The interactive board
+---
+
+## In practice
+
+```bash
+kadence init
+
+kadence sprint create "Sprint 14"
+kadence task add "Fix login" -d "Broken since 2.3" --type bug --priority high --estimate 3
+kadence task comment KAD-1 "Session cookie is fine — the redirect drops it."
+kadence task move KAD-1 done
+kadence sprint close
+```
+
+**The board, when you want to look at it:**
 
 ```
-kadence ui
+$ kadence ui
+
+ kadence   Sprint 14   9 tasks, 28 points
++- backlog (2) -------++- in_progress (1) --++- in_review (1) ----++- done (3) ---------+
+| ^# KAD-1 Auth epic  || . KAD-4 Tokens @dev||!! KAD-7 Crash   [] || v KAD-2 Export     |
+|  * KAD-3 Login form ||                    ||                    || v KAD-5 Docs       |
++---------------------++--------------------++--------------------++--------------------+
+ arrows move  enter details  m status  a assign  e edit  s sprint  / filter  q quit
 ```
 
-Columns side by side, mouse and keyboard:
+Keyboard, mouse, drag between columns, every field editable in place. It calls
+the same commands the CLI does, so the two can never disagree.
+
+**And because the journal has the timestamps, the cost comes out of it for free:**
 
 ```
-←→ column   ↑↓ task   enter details   [ ] shift a card
-m status    a assign  c comment       e edit in $EDITOR
-p priority  t log time                n new    d delete
-s sprint menu (status, burndown, start, close)   S add to sprint
-/ filter    ? help    q quit
+$ kadence sprint close
+
+Sprint "Sprint 14" closed.
+
+  Velocity:  23 of 28 points
+  Actual:    37h — 1.6h per point
+
+  Carried over (2):
+    · KAD-12  Auth refactor
 ```
 
-Enter opens a card where every field is editable in place. Dragging a card with
-the mouse moves it between columns. Each action runs the same command the CLI
-does, so the board can never disagree with the terminal.
+Nobody fills in a form. Nobody can forget to update it. The number is derived
+from state changes the team already made.
 
-The board loads its UI layer lazily — `kadence task add` never pays for it.
+---
 
-## For AI agents
+## For agents
 
-Tasks are files. An agent reads them directly, or through the CLI — no MCP
-server, no token, no network:
+Files first. Every command speaks `--json`, every response carries
+`schema: "kadence/v1"`, stdout is JSON and nothing else, warnings go to stderr.
 
 ```bash
 kadence board --json
-kadence task list --json --status in_progress --sort priority
-kadence task show KAD-1 --json
-kadence sprint status --json
+kadence task show KAD-1 --json          # full history and comments
 KADENCE_SOURCE=agent kadence task move KAD-1 in_progress
 ```
 
-Every `--json` response carries `schema: "kadence/v1"`. stdout holds JSON and
-nothing else; warnings go to stderr. Exit codes: `0` success, `1` runtime error,
-`2` bad arguments.
+`init` writes that guide into both `AGENTS.md` and `CLAUDE.md` — the first is the
+cross-tool convention, the second is what Claude Code actually reads. Whatever a
+human wrote in either is left alone. No MCP server to run, no token to issue, no
+network call to make.
 
-`init` writes `.kadence/README.md` and a section in `AGENTS.md` so your agent
-finds this on its own.
-
-## How it works
+The contract is not a promise you have to take on trust:
 
+```bash
+kadence schema --json      # every command, every field, every error code
 ```
-.kadence/
-├── state.json          derived cache — gitignored, safe to delete
-└── events/
-    ├── archive/        compacted history, one file per month
-    └── 2026-09/        recent events, one file each
+
+A failure carries `error.code` and, where the valid set is knowable, `allowed` —
+which matters most for statuses, because they are configured per project and no
+documentation can tell an agent what yours are.
+
+An MCP wrapper stays on the roadmap as an **optional package**: it costs about
+700 tokens a session over the CLI path — [we measured it](docs/research/probe-c-agent-cost.md),
+and it is not the saving the industry benchmarks suggest — but it would be a
+second way to say the same thing, and it would not work for agents that have no
+MCP client at all.
+
+Ask for only what you need — a board of a thousand tasks is 803 KB in full, and
+a tenth of that with the fields an agent actually reads:
+
+```bash
+kadence board --json --fields label,status,assignee
 ```
 
-Every command appends one event. State is folded from the journal on read, so
-the board can never drift from reality. Two branches writing at once produce two
-different files, and git merges them without a conflict by construction.
+Bulk works everywhere and is all or nothing: `kadence task move KAD-1,KAD-2 done`
+either moves both or changes nothing. A typo does not leave half a board.
+
+---
 
-Measured on 10,000 events:
+## What it costs you
 
 | | |
 |---|---|
-| Cold start with compacted archive | 28 ms |
-| Warm start (cache) | 7 ms |
-| Journal on disk | 1.9 MB (39 MB without compaction) |
-| Bundle | 30 KB, zero runtime deps in the fast path |
+| Install | 29 KB, one runtime dependency |
+| Startup | 80 ms |
+| 10,000 events | 28 ms cold, 7 ms warm |
+| Journal on disk | 1.9 MB |
+| One task, as an agent reads it | 948 bytes — the same at 10 tasks or 1,000 |
+
+These are tests. They fail the build on regression, which is why they are still
+true.
 
-These are enforced by tests that fail on regression.
+---
 
 ## Honest status
 
-What is verified:
+**Verified.** The merge thesis, on real git branches. Performance and size, by
+tests that fail if they regress. That the conflict problem exists in the wild —
+measured, not assumed. 428 tests, including an end-to-end run through the
+installed binary.
 
-- The merge thesis, on real git branches: three people editing one task produce
-  zero conflicts, and every intent is preserved with its author.
-- Performance and size guardrails, by tests that fail if they regress.
-- The conflict problem exists in the wild — measured, not assumed.
+**Not verified.** That teams and their AI agents actually lose enough context to want
+this. The bet rests on reasoning and on the industry naming the problem out
+loud — not on our own users. That research is
+[designed](docs/research/interview-script.md) and not yet run.
 
-What is not:
+**On the roadmap, not shipped.** `kadence decision` (record why, as its own event
+type) and the optional MCP package — the latter kept as a response to someone who
+cannot use the CLI, not as an inevitability.
 
-- **Whether teams want this.** The velocity bet rests on reasoning, not on user
-  interviews. That research is designed but not yet run
-  ([interview script](docs/research/interview-script.md)).
-- Conflicts are real but **rare** — roughly one merge in two hundred. That is
-  why the headline message is analytics, not conflict-freedom.
+`kadence context <task>` was dropped: we measured what `task show --json` already
+returns and it is the whole history of one piece of work, 948 bytes, constant.
+The only thing left to add was a different format, and nobody has asked for one.
 
-The full reasoning, including what would prove this product wrong, lives in
-[docs/](docs/README.md).
+**Known limits.** Conflicts are real but rare: roughly one merge in two hundred.
+Terminal interaction is covered by manual testing; only the key router is
+unit-tested.
 
-## Development
+---
+
+## How it works
+
+```
+.kadence/
+|- state.json          derived cache - gitignored, safe to delete
+`- events/
+   |- archive/         compacted history, one file per month
+   `- 2026-09/         recent events, one file each
+```
+
+Every command appends one event. State is folded from the journal on read, so
+the board cannot drift from reality. Two branches writing at once produce two
+different files, and git merges them without a conflict by construction.
+
+Design decisions, each recording what was measured and what would make us
+revisit it: [docs/decisions/](docs/decisions/).
+
+## Contributing
 
 ```bash
 npm install
-npm test          # 363 tests
-npm run build     # single 40 KB bundle
-npm run typecheck
+npm test          # 428 tests
+npm run build     # 29 KB bundle
 ```
 
-The core has **zero runtime dependencies** — ULID and validation are
-hand-rolled, because a general-purpose validator cost 15% of the startup budget
-for a seven-field object ([ADR-003](docs/decisions/003-zero-runtime-deps-in-core.md)).
-The CLI layer uses `cac` and nothing else.
-
-Architecture decisions are in [docs/decisions/](docs/decisions/); each one
-records what was measured and what would make us revisit it.
+`CLAUDE.md` documents the invariants, the boundaries, and the decisions that
+look arbitrary without their reasoning. Read it before changing the core.
 
-## License
+## Licence
 
 MIT