> ## Documentation Index
> Fetch the complete documentation index at: https://www.testmuai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Maintain a Kane CLI Test Suite

> Keep tests aligned with changing requirements: kane-cli maintain reconcile triages each changed source into an ADD/MODIFY/ARCHIVE plan you approve.

Products change, and tests should keep up. `kane-cli maintain` closes the [assurance loop](https://www.testmuai.com/docs/kane-cli-assurance) with two commands:

* `maintain reconcile`: when a requirement document changes, it turns that one changed source into an honest, row-by-row update plan for your suite.
* `maintain evolve`: re-designs a use-case whose design has gone stale.

Both work over the same `.context/` store. Maintain adds no new kinds of knowledge; it updates the ones you already have.

```bash theme={null}
kane-cli maintain reconcile --from <file> --source-id <id>          # the in-chat review (TTY default)
kane-cli maintain reconcile --from <file> --source-id <id> --plan   # preview: stage + store the plan
kane-cli maintain reconcile --apply [path]                          # continue a stored plan
kane-cli maintain reconcile --from <url>                              # a Jira, Confluence, Linear or web URL
kane-cli maintain reconcile --from <file> --source-id <id> --mode agent   # headless — see Automation
kane-cli maintain evolve <ref> [--because "<reason>"]               # re-design one stale use-case (interactive)
kane-cli maintain evolve --from-stale                               # …or every use-case with stale designs
kane-cli maintain evolve <ref> --mode agent                         # headless: the blast-radius question pauses the run
```

## `maintain reconcile`: one changed source, one triage

Use reconcile whenever a requirement document changes. It answers one question: what should the suite do about this change?

Reconcile re-ingests the source, re-extracts use-cases from the new version, and first shows you a changeset (what the change did to your knowledge). In a terminal, every proposed change (adds, updated versions, archives) then **waits behind a review card**, and nothing from the changeset is committed until you give a verdict. Only two things land without a card when the run finalizes: evidence attached to unchanged matches, and the extraction record itself.

Reconcile takes **two explicit inputs**, so it never has to guess which source a file belongs to:

* `--from <file|url>`: the **new** version of the document. This is a file path or a remote source URL; see [Remote sources](#remote-sources) below.
* `--source-id <id>`: the **existing** source that this file replaces. Reconcile moves that source's head (its current version) to the new file. Find ids with `kane-cli context list --type source`. Required with a file; optional with a URL, because a URL carries its own id.

With a file, both inputs are required on a fresh run. To continue a stored plan, `--apply <path>` alone is enough, because the plan remembers its source.

> [!TIP]
>
> Give reconcile the changed file directly. Don't run `context ingest` on the new version first: reconcile does the re-ingest itself, and [re-running the same command](#running-again) is always safe.

### Input checks

Before anything runs, reconcile checks its inputs in this order. These checks ask no questions, write nothing, and behave the same in every mode:

1. Both `--from` and `--source-id` are present.
2. The file exists and is a regular file.
3. It is a document type that can be ingested.
4. The source id names a known source.
5. That source isn't retired. Restore it first with [`kane-cli context revert`](https://www.testmuai.com/docs/kane-cli-assurance-context#housekeeping).
6. The file doesn't already back a **different** live source. This is the fork guard: it stops one document's history from silently splitting into another source's, and the error suggests the `--source-id` you probably meant.
7. No live session is holding review work pinned to this source. This is the held-source guard: if such a session exists, reconcile refuses to move the head and names the session to finish first (`kane-cli context extract --resume <sid>`), so the head never moves under evidence that is still being reviewed. If a session file can't be read, the check fails **closed** (it refuses rather than assumes) and points you to the [`context sessions`](https://www.testmuai.com/docs/kane-cli-assurance-context#sessions) list and clean commands, because an unreadable file can't prove there is no hold.

Any failure exits `2` with a message naming the next command to run. In `--mode agent`, these failures arrive on the NDJSON stream (`error` + `done`), never on stderr alone.

### The changeset: what the change did

The changeset is shown first, before any action. The line list below is what `--plan` and the headless modes print:

```
changeset: 3 item(s)
  [MODIFY] uc-manage-the-cart — updated: title, criteria
  [ADD] uc-save-cart-for-later
  [ARCHIVE] uc-legacy-flow — evidence decayed: no quote from the source relocates into the new text, no other live source, no fresh evidence this run
```

A terminal review opens with the same facts as a **decision briefing**: a headline and a boxed table with one row per upcoming card. Each row shows the card's kind, the item, why it's proposed, and its impact (`14 stale · 2 direct`, or `—` when nothing goes stale). The plan facts appear dimmed below the table.

* **MODIFY**: the re-extract matched an existing use-case whose content changed. Each MODIFY records *why*: either the source content changed, or the change caused a structural break.
* **ADD**: a use-case newly extracted from the changed source.
* **ARCHIVE**: the item's evidence has decayed on all three counts. Every quote fails to relocate into the new text, *and* no other live source supports the item, *and* this run attached no fresh evidence. If any one of the three is missing, the item isn't proposed for archiving.

### The in-chat review (the default in a terminal)

In a terminal, reconcile runs as an **in-chat review**:

1. The extraction runs over the change, and every proposed change is held.
2. The check-in offers `review N change(s) from <source>` as its first row. `later` stays available, every other row keeps working, and the offer comes back at each check-in until you take it.
3. Selecting it opens the decision briefing, then walks through the held changes **one card at a time, highest risk first**.

Each card shows what changed (a compact diff), why it matched, its evidence citation, and its real downstream cost (`impact: approving marks 14 item(s) stale`). A longer diff collapses to a summary plus a `view diff` row that commits nothing (esc returns to the card).

The verdicts:

* **approve** commits the change. An ADD creates the draft (and offers `design tests now`). A MODIFY creates the new version with a redirect from the old one (and offers `evolve the design now`). An ARCHIVE applies a non-destructive retire, which you can undo at any time with [`kane-cli context revert`](https://www.testmuai.com/docs/kane-cli-assurance-context#housekeeping). Offers are rows you choose; they never run on their own, and a child design run asks its questions in this same session.
* **reject** drops the staged proposal and leaves **nothing behind**. Because nothing is remembered, a later reconcile may propose the same change again. This is deliberate.
* **defer** parks the decision as **one durable gap**. It appears in [`cover gaps`](https://www.testmuai.com/docs/kane-cli-assurance-coverage) with the reconcile command as its remedy, and it clears when a later verdict lands on the same change.
* **✎ / typing is steering**: your words go to the agent, the remaining changes are finalized again, and revised cards are shown. Cards you already resolved never come back. ARCHIVE cards cannot be steered.

> [!NOTE]
>
> While a deferred change is on the record, Kane CLI releases older than 0.7.2 cannot pass the store's integrity checks or commit to it. If several machines share a store, upgrade them to Kane CLI 0.7.2 or later together.

Three properties worth knowing:

* **Every verdict is checked again at commit time.** If the target was retired during the review, the source's head moved again, or an archive target gained new live evidence, the card is shown again with the reason. An approved change never lands differently from what you saw.
* **There is no "approve all".** Row 1 carries the recommendation, so pressing Enter through the cards is the fast path, but every change gets its own decision. Esc on a card does nothing on purpose: verdicts are commits, so there is nothing to back out of.
* **Your decisions are never lost.** Verdicts are saved next to the proposal as you make them. Ctrl+C keeps every decision, and you resume the review with `--apply` (below) or by resuming the session. The last verdict releases the source for other work.

The review also shows pending items from earlier extract sessions: held items waiting for a verdict (including held updates to existing items) and possible duplicates join the same card review, so one pass covers everything waiting on you. A problem in those earlier items never blocks the reconcile changes themselves. Before a held item commits, its citations are checked against the source's current text. A citation that no longer holds is refused with a hint to re-stage it, instead of committing silently.

### `--plan`: a preview that doesn't touch the suite

`--plan` records the source change and **stages everything downstream**. The proposed rows are kept in a stored plan (`plan stored: <path>`, under `.context/reconcile/plans/`), and no tests or designs are touched.

Two things do land, and the output says so:

* The head move, because the fact that the source changed is true whatever you decide.
* Updates to a matched use-case whose source content moved, because they are part of the re-extract itself.

Every MODIFY and ARCHIVE row in the plan carries its impact line (`impact: approving marks N item(s) stale`), and a `skipped arms` line names every analysis that reconcile does not run.

To walk the plan later, run `--apply <path>`, or `--apply` on its own:

* If a live review is holding changes, bare `--apply` resumes it as cards first, **without the agent**: no model and no network are needed, because your stored verdicts are the saved state. (A headless run that meets a held review refuses instead of guessing verdicts.)
* With no held review, it picks the latest stored plan behind an approval prompt. Headless modes accept the prompt silently.
* `--apply --from <file> --source-id <id>` recomputes the plan live instead.

`--plan` and `--apply` together is a usage error (exit `2`). Running `--plan` again re-renders the stored plan. If the source hasn't changed, reconcile says so truthfully (`nothing to reconcile`).

### Remote sources: `--from <url>`

`--from` also accepts a remote source URL: a Jira issue or Confluence page, a public web page, or a Linear issue or document. These are the same URLs that [`context ingest`](https://www.testmuai.com/docs/kane-cli-assurance-sources) takes.

Remote sources follow the same flow as files. Reconcile fetches the latest content through the provider, and the head moves if anything you would cite has changed. Everything downstream (the cards, `--plan` and `--apply`) works the same way.

```bash theme={null}
kane-cli maintain reconcile --from https://<your-site>/browse/PROJ-123 --plan
kane-cli maintain reconcile --from https://<site>/wiki/spaces/<KEY>/pages/<id>/…
kane-cli maintain reconcile --from https://linear.app/<workspace>/issue/ENG-42
kane-cli maintain reconcile --from https://docs.example.com/guide
```

Three rules apply only to remote sources:

* **The id comes from the URL.** It is `proj-123` or `eng-42` for an issue, `page-<id>` for a Confluence page, `doc-<id>` for a Linear document, and a slug plus a short hash for a web page. That is why `--source-id` is optional. If you pass an id that contradicts the URL's own id, reconcile refuses, because it never adopts a URL under a different id. To maintain a source you ingested under a custom id with `context ingest --as`, re-run that ingest with the same `--as`.
* **The kind of source must match, both ways.** A URL cannot version a file-backed source that happens to share its id, and a file cannot version a remote source. Each case refuses and names the correct `--from`. The same check runs when a stored plan is replayed, so a stale plan can never overwrite a source that is now backed by something else.
* **Stored plans remember the URL** and recompute by fetching it again, the same way a file plan re-reads its file.

> [!NOTE]
>
> If a Jira issue was ingested with a Kane CLI release older than 0.7.2, its first reconcile after you upgrade may report a head move that is not a content edit. This is a one-time re-version of the source, not a change to review.

### Running again: reconcile converges

You can safely repeat the same command. It picks up from wherever things stand:

| State on a re-run | What happens |
| - | - |
| the file's bytes changed again | a fresh reconcile of the new change |
| unchanged, and the stored plan has pending rows | the plan is **resumed** in your chosen mode |
| unchanged, and the plan was fully applied | `already reconciled`, and a clean exit |
| unchanged, no stored plan | `nothing to reconcile` |
| the graph moved since the plan was stored | `graph moved since this plan — recomputing` (pending work is staged again, not billed again) |

A plan stored by an earlier kane-cli version is refused with a hint to recompute it, so plans never carry silently across format changes.

### Headless modes

`--mode agent|ci|override` uses the same ask-policy table as extract and design. See [Automation](https://www.testmuai.com/docs/kane-cli-assurance-automation) for the full contract and reconcile's NDJSON stream. Three things are specific to reconcile:

* **Headless runs don't stage.** The re-extract commits as it goes, and rows apply according to the mode. `override` and `ci` apply ADD and MODIFY rows automatically; `ci` stops when a run needs a person's judgement; `agent` streams typed events and pauses. The in-chat review is available only in a terminal.
* **Archiving is never automatic.** No headless mode archives anything; ARCHIVE decisions wait for an interactive session.
* **The `--mode agent` stream is pure NDJSON.** It opens with a minimal `run_start`, and nothing else prints on either output. The re-extract shares the same stream: its extract events appear between the `reconcile_*` events, each stamped `verb: "reconcile"`. See [Automation](https://www.testmuai.com/docs/kane-cli-assurance-automation) for the event list.

A bare run without a terminal (no TTY) refuses with exit `2` and asks for an explicit `--mode`, or for `--plan` to preview.

### The rows

| Kind | Fact behind it | Action on approve |
| - | - | - |
| `ADD` | a use-case newly extracted from the changed source, or an uncovered criterion of a touched use-case | a design run for that use-case (`kane-cli design tests --use-case <id>`) |
| `MODIFY` | content that matched but changed, or an entity whose pins (the source snapshots its evidence is tied to) this change broke | commit the update, or re-design with `kane-cli maintain evolve <id>` when the break is structural |
| `REMOVE` | a use-case that is now orphaned: no live source supports it | plan-only: listed in the plan, never executed |

## `maintain evolve`: re-design a stale use-case

```bash theme={null}
kane-cli maintain evolve <ref> [--because "<reason>"]   # any designed entity → its parent use-case
kane-cli maintain evolve --from-stale                   # every use-case with stale designed entities
```

Evolve re-designs the **parent use-case** of whatever you point it at: a test, a scenario, a criterion, or the use-case itself. Before anything runs, it states the blast radius (the scenario and test pairs the re-design would affect). Declining exits cleanly.

* **It only runs on stale designs.** A target that is still fresh refuses. `--because "<reason>"` is the supported override: your reason becomes the change context the re-design sees, and it is kept on the record.
* `--from-stale` collects every use-case with stale designed entities. In a terminal it confirms them one at a time; with `--mode agent` it asks one question per use-case and runs nothing until all are answered.
* In a terminal, evolve's output starts with an aligned diff report, marks its child design runs with progress-dot lines, and ends with the same session summary that every interactive session prints.
* After a clean run, evolve reports the diff between the two design generations: what was superseded, what was created, what was **kept** unchanged, and which criteria's verifying tests moved. A re-design doesn't break what it didn't change.
* Reconcile's MODIFY rows lead here automatically. Run evolve directly when a design went stale outside a reconcile (an older change, or a retired source). [`kane-cli cover gaps`](https://www.testmuai.com/docs/kane-cli-assurance-coverage) lists stale designed entities in its ranked worklist.

> [!NOTE]
>
> Evolve runs a design, so, like extract, design and reconcile, it calls the KaneAI service and consumes credits.

### Headless: `--mode agent`

Requires Kane CLI 0.8.21 or later.

`--mode agent` uses the same typed stream as `design tests` and `reconcile`: one JSON object per line on stdout, `verb: "evolve"`, nothing on stderr, and `done` last. Agent mode never answers for you. The blast-radius confirmation becomes a question, the run pauses with exit `3`, and the answer comes on the next call:

```bash theme={null}
kane-cli maintain evolve t-4 --mode agent
# evolve_target (the blast radius), evolve_paused (question id evolve:uc-3, options proceed / decline), done paused, exit 3
kane-cli maintain evolve t-4 --mode agent --answer evolve:uc-3=1     # 1 = proceed, 2 = decline
# evolve_target, child_start, the design run's own events (verb: design), child_end, evolve_diff, done complete, exit 0
```

* The resume command keeps `--because`.
* With `--from-stale` there is one question per use-case, and nothing runs until every one is answered. A partial set of answers pauses again on the rest and keeps the answers you gave. After a partial answer, the suggested commands include the answers already given, so declining the rest still re-designs the use-cases you answered proceed.
* A design session that pauses arrives as its own `session_paused`, and `done` carries its resume command. Resume it, then run evolve again to get the diff.
* `--mode` accepts `interactive` and `agent` only (anything else refuses with `MODE_USAGE`). An answer to a question the run does not ask refuses with `ANSWER_USAGE`.

The event table is in [Automation](https://www.testmuai.com/docs/kane-cli-assurance-automation#evolves-stream).

## Exit codes

| Code | Meaning |
| - | - |
| `0` | The session, plan, or resume completed, or there was nothing to do (an unchanged source). |
| `1` | The reconcile chain failed, or another live reconcile holds the lock. A lock left by a dead run clears itself; never delete it by hand. |
| `2` | Usage or validation failure. Nothing was changed. |
| `3` | Paused. Pending work is in the stored plan; the same command (or `--apply`) continues it. |

## Next steps

* [Requirement sources](https://www.testmuai.com/docs/kane-cli-assurance-sources): every file type and remote URL reconcile accepts.
* [Coverage](https://www.testmuai.com/docs/kane-cli-assurance-coverage): `cover gaps --stage design` is the standing worklist between reconciles.
* [Designing tests](https://www.testmuai.com/docs/kane-cli-assurance-design): what an approved ADD row actually runs.
* [Automation](https://www.testmuai.com/docs/kane-cli-assurance-automation): reconcile in CI, and its NDJSON stream.

## Terminal First Testing With Kane CLI

Natural language browser & mobile app tests right from terminal.

Book a Demo

![Kane CLI terminal](https://assets.testmu.ai/resources/images/Terminal-KaneCLI.png)

×

Schedule Your Personal Demo

<form>
  Select Product

  Schedule Demo
</form>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.