The Kane CLI Assurance Lifecycle

kane-cli began as a way to author and replay browser tests. The assurance commands take on the step before and after: describe what your product must do, and kane-cli designs the tests that prove it — each one permanently linked to the requirement it verifies. Run them, and coverage stops being a guess: every run reports exactly what it proved and what it still owes. And as your product changes, the suite is reconciled instead of quietly rotting.

Requires kane-cli 0.6.1 or later (kane-cli --version). On 0.6.0 these commands fail after a fresh install — upgrade.

The loop

  requirement docs                          product changes
        │                                          │
        ▼                                          ▼
  context ingest ──► context extract ──► context review ──► design tests
  (snapshot the      (agent proposes       (promote to       (ACs, scenarios,
   sources)           use-cases, cites      trusted)          one test per
                      every claim)                            scenario — written
                                                              as *_test.md files)
                                                                     │
                                                                     ▼
  maintain ◄── cover ◄── evidence pack ◄── testrun run ◄── testmd run ◄── context review
  (reconcile   (proven     (sealed proof)   (batch replay)   (author each    (approve the
   a changed    vs owed)                                      test once)      design output)
   source)

Every stage is a separate command, so you can stop, review, and resume at any point — nothing downstream happens without the upstream commit.

Stage	Command	What it does
Capture	`kane-cli context ingest`	Snapshot requirement documents into a local, content-addressed store (`.context/`)
Extract	`kane-cli context extract`	An agent reads the sources and proposes use-cases, citing the exact lines it read
Review	`kane-cli context review`	You promote proposals to trusted, edit them, or reject them
Design	`kane-cli design tests`	Turn one use-case into acceptance criteria, scenarios, and runnable tests — each test tagged with the criteria it verifies
Review the design	`kane-cli context review`	Design output is `derived` too — approve, edit, or reject the generated ACs, scenarios, and tests
Execute	`kane-cli testmd run`, `kane-cli testrun run`	Author and replay the designed tests; every run seals an evidence pack
Measure	`kane-cli cover`	Two axes: what a pack proved vs what the design still owes
Maintain	`kane-cli maintain`	Reconcile the suite when a source document changes
Share	`kane-cli context sync`	Share the store with your team through a location, a GitHub repository, an S3-compatible bucket, or a folder, with `kane-cli context push`, `kane-cli context pull` and `kane-cli context clone`

The vocabulary

Term	Meaning
Source	A requirement document you ingested — a PRD, a spec, a policy page. Content-addressed: editing the file and re-ingesting creates a new version.
Use-case	One thing a user needs to accomplish, extracted from sources with cited evidence.
Acceptance criterion (AC)	A single verifiable promise (“the cart holds at most 10 items”), with a machine-checkable oracle.
Scenario	One path through a use-case — happy, negative, boundary, edge.
Test	Exactly one runnable test per scenario (strict 1:1), written as a normal `*_test.md` file.
derived / trusted / archived	Trust states. Everything an agent proposes starts `derived` (unreviewed); your review promotes it to `trusted` or rejects it to `archived`. Nothing is silently trusted.
fresh / stale / orphaned	Freshness. When a source document changes, everything extracted from the old snapshot reads `stale` until re-verified; a node whose sources are all retired reads `orphaned`.
Gap	A recorded, ranked piece of missing coverage — a criterion no test verifies, a question nobody answered, a scenario cut by budget. Gaps are first-class output, not silence.
Evidence pack	The sealed `.evidence` file every run produces — the proof coverage is measured from.

Assurance vs `generate`

kane-cli has two ways to author tests, for two different jobs:

kane-cli generate — quick test cases from a plain-language description. One prompt in, scenarios and cases out. Great for exploring coverage of a feature you can describe in a sentence.
The assurance lifecycle — tests derived from your actual requirement documents, with every claim cited, every proposal reviewed, and a permanent, auditable link from each test back to the criteria it verifies. Use it when you need to answer “what exactly is covered, and how do we know?”

If you have a PRD and care about coverage accounting, start with assurance. If you want ten good test ideas in a minute, start with generate.

The store: `.context/`

The assurance commands work over a local store in your project directory, created on first ingest:

It is append-only in everyday use: no command that writes to it deletes or rewrites a record. Edits create new versions, and mistakes are reverted with compensation records. kane-cli context explain can replay the full history of any node. The one exception is a sync rebase, which replaces your records after the last shared one with the location’s and reapplies your own on top, and every replaced record is kept in a backup.
It is yours and local: sources, use-cases, designs, and review verdicts live in your project. The extract and design agents run against the KaneAI service using your login and send it what they need to read, but the store they commit to is on your disk, and the store itself goes elsewhere only when you publish it to a location your team shares.
Never merge .context/ with git. The store is single-writer, and two branches appending records will corrupt it on the next read. Kane CLI adds .context/ to your .gitignore when it creates the store inside a git repository, and KANE_CONTEXT_GITIGNORE=0 keeps it out.
Share it through a location: bind the store to a GitHub repository, an S3-compatible bucket, or a folder on a shared drive, then kane-cli context push publishes your records, kane-cli context pull takes your teammates’, and kane-cli context clone gives a new teammate a store of their own. Nothing on a location is ever overwritten or deleted, and when two people change the same thing the disagreement is a decision you answer, never a silent overwrite. See Sharing the context graph with your team.
kane-cli context fsck verifies the whole store; kane-cli context rebuild regenerates the read caches from the verified records.

What costs credits

context extract, design tests, and maintain reconcile (which embeds them) call the KaneAI agent and consume credits (kane-cli balance to check; each agent turn’s cost is reported as it happens). Everything else — list, view, review, explain, cover, fsck — is local and free.

Next steps

Building the context graph — ingest, extract, review.
Designing tests — from a use-case to runnable *_test.md files.
Coverage — proven vs owed, and how designed tests join execution.
Maintaining the suite — reconcile a changed source.
Automation — running all of this headless in CI or from an agent.

​The loop

​The vocabulary

​Assurance vs generate

​The store: .context/

​What costs credits

​Next steps

The loop

The vocabulary

Assurance vs `generate`

The store: `.context/`

What costs credits

Next steps