kadence 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,106 @@
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-09-25
+
+**One question over everything written down — and three fixes that had to come
+first.** `kadence search` answers "what do we know about X" across tasks,
+decisions, notes and documents at once. Getting there meant admitting that the
+commands an agent already calls were returning answers it could not use: one
+that could be forged by a note, one that read the whole journal twice on every
+call, and one that returned four thousand tasks into a window that truncates at
+twenty-five thousand tokens.
+
+### ⚠️ Upgrading — three defaults changed
+
+Nothing was renamed or removed from `kadence schema --json`, so `kadence/v1`
+stands. What a caller gets **by default** changed in three places, and a script
+that assumed otherwise needs one flag:
+
+| Was | Is | To get the old answer |
+|---|---|---|
+| `task list --json` carried `history` | it does not | `--fields id,label,history` |
+| list commands returned everything | one page of 100 | `--limit 0` |
+| `prime --json` carried full note text | capped at 2000 characters | `kadence note list --json` |
+
+`history` was never promised there — the schema has always placed it in
+`task show` — but it was emitted, and Hyrum's Law says somebody depended on it.
+It is 61% of that response at 4000 tasks, which put the command past the point
+where an agent's tool output is silently cut in half.
+
+### Added — `kadence search`
+
+- **One query, every kind of record.** Tasks with their descriptions,
+  acceptance criteria and comments; decisions with their reason and the
+  alternative they rejected; notes; documents cut at their headings. Most of
+  that was unreachable by any command before this: `task list --search` covered
+  24% of the journal's prose and only tasks.
+- **Lexical, not semantic, and measured rather than assumed.** BM25,
+  hand-rolled, no dependency, over the folded projection — so labels exist
+  (I7), a superseded decision does not answer as though it were current, and
+  search cannot disagree with `task show`. An embedding model is 200 MB and
+  seconds of cold start against a 200 ms budget and a promise to work offline;
+  on a vocabulary of `ULID`, `KAD-N` and `FlowEvent` it is also the weaker
+  method. 26 ms a query over 829 units; 158 ms end to end (DEC-26).
+- **A hit is something you can cite.** The ULID, never the derived label; the
+  lines a document section came from; and a quoted span whose offsets land on
+  the quoted text, so an agent quotes the journal instead of paraphrasing it.
+- **`coverage` — how much of the question a record actually holds**, 0 to 1,
+  weighted by how rare each word is. Where the first hit is right this is 1.00
+  at the median; where it is wrong, 0.62. Below 0.7 the human output says the
+  passage answers part of the question. The obvious signal — the gap to the
+  second hit — was measured and does not work: 0.10 against 0.08 (DEC-30).
+- **An empty answer, said plainly.** Below the coverage floor the result is
+  nothing, and the message says the journal has no answer. A model handed
+  passages that merely look relevant fabricates more than one handed none, so
+  this is a feature and not a cop-out. Nine of ten questions about things this
+  journal has never discussed get silence.
+- **Quality is held by a test, not by hope.** `test/search-relevance.test.ts`
+  runs 25 real questions against the repository's own journal and fails below
+  recall@3 of 0.64. Three ranking ideas were measured this release and two were
+  removed for making it worse (DEC-27, DEC-28).
+
+### Fixed — `prime` could be forged, and repainted your terminal
+
+- **A note carrying newlines rendered as sections of its own**, and the
+  cheapest section to forge is the `Go deeper:` block `prime` ends with. The
+  length was capped; the shape was not. An escape sequence went further and
+  cleared the screen — `prime` runs from the `SessionStart` hook without being
+  asked.
+- **`prime --json` was unbounded.** One 200 KB note made the session preamble
+  200,728 bytes. Free text is now capped at 2000 characters with `bytes`
+  alongside, the signal `documentation` already gave (DEC-21).
+
+### Fixed — a warm command read the whole journal anyway
+
+- **`loadState` called `readAll` on every command**, purely to count corrupted
+  and unknown events for a warning, after the snapshot had already answered.
+  A warm call read all 10,103 files; a cold one read every event twice.
+  345 ms to 201 ms end to end at 10k events; 204 ms to 5 ms in process.
+- **The fingerprint counts bytes as well as names**, so a file rewritten in
+  place invalidates the cache. That also means `git checkout .kadence/` — the
+  remedy the corruption warning itself recommends — finally invalidates the
+  cache it needed to, which it never did (DEC-22).
+- Every performance guardrail measured `loadOrBuild`; the CLI calls
+  `loadState`. The bug lived in the gap between them. Both are measured now.
+
+### Fixed — list commands returned the whole board
+
+- **One page of 100, with the real total and the offset beside it.**
+  `task list --json` was 1.3M tokens at 4000 tasks against the 25k at which an
+  agent's tool output is cut — silently, so the agent answers on a fraction
+  while believing it saw everything. Now 50 KB. `--limit 0` returns everything;
+  `--offset` walks (DEC-24).
+- 100 rather than 200 because this repository's own tasks run 1100 bytes each,
+  where the ceiling is 93.
+
+### Changed
+
+- Documentation moved into the journal: 65 documents, `DOC-2` through `DOC-66`,
+  as `doc.written` events. `docs/` stays on disk as the working draft and links
+  are rewritten to `DOC-N` on publication (DEC-25). The npm package is
+  unaffected — `.kadence/` is not in `files`.
+
 ## [0.6.0] — 2026-09-23
 
 **Documentation in the journal, and an honest answer when something goes
@@ -318,7 +418,7 @@ command was renamed, and `--json` responses gain keys rather than losing them.
 - **`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).
+  claim before either pushes. See ADR-011.
 - **`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`
@@ -354,7 +454,7 @@ command was renamed, and `--json` responses gain keys rather than losing them.
   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).
+  is in 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
@@ -395,7 +495,7 @@ command was renamed, and `--json` responses gain keys rather than losing them.
 
 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).
+reports-discovery-2026-09.md.
 Velocity and cycle time stay out of the headline; they are a consequence, served
 to the person who asks.
 
@@ -426,7 +526,7 @@ to the person who asks.
 
 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).
+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
@@ -444,7 +544,7 @@ the three constraints, and each has a kill condition written before the code, in
   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
+  ADR-012, 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
@@ -475,7 +575,7 @@ the three constraints, and each has a kill condition written before the code, in
   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).
+  ADR-013.
 - **`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
@@ -662,7 +762,7 @@ is additive within `kadence/v1`, which the contract permits at any version.
 The journal held what happened. It now holds **why** — and the reasoning cannot
 quietly go stale, because superseding a decision is one event rather than two
 edits somebody has to remember to make. Reasoning in
-[ADR-010](docs/decisions/010-decisions-as-events.md).
+ADR-010.
 
 ### Added
 
@@ -687,7 +787,7 @@ edits somebody has to remember to make. Reasoning in
   explains this task, and that is the only thing recorded. A missing file is a
   warning, not a refusal — it may arrive in a later commit.
 
-  Measured before building ([Probe D](docs/research/probe-d-docs-linkage.md)):
+  Measured before building (Probe D):
   across five real questions, grep finds the answering document every time and
   buries it among 10–35 candidates. The link saves the sifting, not the search.
 
@@ -758,8 +858,8 @@ published package rather than the source.
 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).
+reads. Reasoning in ADR-009,
+measurements in Probe C.
 
 ### Added
 
@@ -830,7 +930,7 @@ asked for.
 - Developer tooling (`.claude/`, `.serena/`) is no longer committed: 381 files
   and 3.8 MB of it, against 94 files of actual product. What belongs in git and
   what does not is written down in
-  [ADR-007](docs/decisions/007-what-goes-into-git.md), and `.gitignore` now
+  ADR-007, and `.gitignore` now
   also covers `.env`, coverage output and editor leftovers.
 
 ## [0.1.3] — 2026-09-03

package/README.md

@@ -56,7 +56,7 @@ reads the same thing as JSON.
 **And it stays one call.** That answer stays under a kilobyte 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) at 948 bytes in
+worth having. Measured at 948 bytes in
 0.2; 982 bytes at 0.4, after claims and acceptance criteria joined every record.
 
 ## Why events and not files
@@ -102,7 +102,9 @@ 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.
 
-Full data: [probe-a-results.md](docs/research/probe-a-results.md).
+The measurement itself is a working paper and is not published (see
+`.gitignore`); the mechanism it measures is proved here by
+`test/integration/merge.test.ts`.
 
 ---
 
@@ -187,7 +189,7 @@ kadence task list --branch
 
 Nothing is stored for that: which tasks belong to a branch lives in git's
 history and is read when you ask. It narrows the answer between three and
-twenty times, [measured](docs/research/branch-context-2026-09.md) on real board
+twenty times, measured on real board
 sizes.
 
 ### Also in the box
@@ -198,8 +200,8 @@ columns, reports folded from the same journal (`report flow`, `cfd`,
 `attention`; burndown, velocity and workload are in the repository and not yet
 on npm), a self-contained HTML or Markdown export, `compact` for long journals,
 and shell completion. None of it is required, and none of it is the point —
-it is what the journal happens to know. Commands and caveats:
-[docs/reports.md](docs/reports.md), and `--help` on each command.
+it is what the journal happens to know. `--help` on each command is the
+reference, and `kadence doc list` is what the journal knows about itself.
 
 ### Removing kadence
 
@@ -257,7 +259,7 @@ documentation can tell an agent what yours are.
 
 There is no MCP wrapper, and one gets built only as an **optional package**, when
 someone who cannot run a CLI asks for it: it costs about 700 tokens a session
-over the CLI path — [we measured it](docs/research/probe-c-agent-cost.md), and it
+over the CLI path — we measured it, and it
 is not the saving the industry benchmarks suggest — 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.
@@ -340,10 +342,10 @@ end-to-end run through the installed binary.
 **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, Probe B, is
-[designed](docs/research/interview-script.md) and not yet run: as of
-2026-09-16, [zero conversations](docs/research/probe-b-results.md) and no
-external users. [The strategy](docs/product/strategy.md) says what happens next
-and on which dates.
+designed and not yet run: as of
+2026-09-16, zero conversations and no external users. What happens next, and
+on which dates, is recorded in this repository's own journal — `kadence
+decision list` and `kadence note list`.
 
 **Not built, on purpose.** An MCP package — only if someone who cannot run a CLI
 asks for it, not as an inevitability.
@@ -382,7 +384,10 @@ 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/).
+revisit it, are in the journal that ships with this repository — `kadence
+decision list`, or `kadence decision show DEC-3` for one in full. The longer
+write-ups behind them are working papers and are kept out of git on purpose;
+the decision, its reason and the alternatives that lost are in the events.
 
 ## Contributing