kivax 2.1.0__tar.gz

kivax-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Fernández Fernández
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kivax-2.1.0/PKG-INFO

@@ -0,0 +1,611 @@
+Metadata-Version: 2.4
+Name: kivax
+Version: 2.1.0
+Summary: A runtime for spec-anchored Spec-Driven Development
+Author: null-result
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/null-result/kivax
+Project-URL: Repository, https://github.com/null-result/kivax
+Project-URL: Issues, https://github.com/null-result/kivax/issues
+Project-URL: Changelog, https://github.com/null-result/kivax/releases
+Keywords: spec-driven-development,sdd,ai-agents,claude-code,traceability
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# Kivax
+
+<p align="center">
+  <img src="assets/logo.png" alt="Kivax logo" width="200">
+</p>
+
+<p align="center">
+  <a href="https://github.com/null-result/kivax/actions/workflows/ci.yml"><img src="https://github.com/null-result/kivax/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+Kivax is a runtime for spec-anchored Spec-Driven Development: the narrative spec compiles into a canonical yml, from which the plan, tests, and code are derived, with hash-verifiable traceability between them at every step.
+
+Works with **Claude Code**, **opencode**, **Cursor**, **GitHub Copilot** (in VS Code and via Copilot CLI), and **OpenAI Codex CLI** — one project can use several at once.
+
+**Contents** — [Quick start](#quick-start) · [Prerequisites](#prerequisites) · [Install](#install-once-per-machine) · [Set up a project](#set-up-a-project) · [Using it day to day](#using-it-day-to-day) · [Project files](#project-files-and-the-global-store) · [Keeping in sync](#keeping-in-sync) · [CLI](#cli-reference) · [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick start
+
+```bash
+pipx install kivax
+```
+
+Then, at the root of the project you want to work on:
+
+```bash
+kivax init
+```
+
+Answer the wizard, then open your AI assistant in that project and ask it to **set the project up** (writes `PRINCIPLES.md` and `ARCHITECTURE.md` with you, once) and then to **start a new feature**. That's it — the rest of this document explains each step in detail.
+
+---
+
+## Prerequisites
+
+- **Python 3.10 or later.** Kivax is a pip package; its one dependency (PyYAML) is installed with it.
+- **git** — Kivax's traceability model diffs your branch against a base branch, so run `kivax init` inside a git repository, at its root.
+- **A forge CLI: [`gh`](https://cli.github.com) or [`glab`](https://gitlab.com/gitlab-org/cli)**, authenticated (`gh auth login`). The flow ends by opening a pull request, and a pull request is a forge concept, not a git one — no git command creates one. `kivax doctor` checks for it.
+- **At least one supported assistant**: [Claude Code](https://claude.com/product/claude-code), [opencode](https://opencode.ai), [Cursor](https://cursor.com), [GitHub Copilot](https://github.com/features/copilot) in VS Code, [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli), or [OpenAI Codex CLI](https://developers.openai.com/codex). You can mix several in the same project.
+- Linux, macOS, and Windows are all supported and all covered by CI.
+
+---
+
+## Install (once per machine)
+
+```bash
+pipx install kivax
+```
+
+Same command on Linux, macOS, and Windows.
+
+[pipx](https://pipx.pypa.io) is the recommendation rather than plain `pip` because Kivax is an *application*, not a library you import: pipx puts it in its own virtualenv and links just the `kivax` command onto your PATH, so it can't collide with your projects' dependencies. It also sidesteps the "externally-managed-environment" error that `pip install` hits on Debian, Ubuntu, and Homebrew Python.
+
+Plain pip works too, if you'd rather:
+
+```bash
+pip install --user kivax
+```
+
+**Upgrade** — one command, and it's the whole story. The agents, skills, and templates Kivax installs into projects ship *inside* the package, so the CLI and the material it copies can never be out of step:
+
+```bash
+pipx upgrade kivax
+```
+
+That updates Kivax itself. It deliberately doesn't touch any project — run `kivax upgrade` inside each repository you want to bring current, and review the diff.
+
+**Uninstall** — `pipx uninstall kivax`.
+
+### Verify
+
+```bash
+kivax version
+```
+
+Should print the store path and the version. If you get `command not found`, see [Troubleshooting](#troubleshooting).
+
+> **Upgrading from 2.0 or earlier?** Kivax used to be installed by cloning this repository and running `install.py`, which left a store in `~/.kivax` and a `kivax` symlink in `~/.local/bin`. Neither is used any more. Delete both — if that old symlink sits earlier on your PATH it will keep shadowing the version you just installed. `kivax version` warns you when it spots the leftovers.
+>
+> ```bash
+> rm -rf ~/.kivax ~/.local/bin/kivax
+> ```
+>
+> Projects need no migration: everything `kivax init` wrote is committed in the repository already.
+
+---
+
+## Set up a project
+
+Run this at the **root of your repository**, once per project:
+
+```bash
+kivax init
+```
+
+It's an interactive wizard that:
+
+1. **Asks which assistant(s) you use** — Claude Code, opencode, Cursor, GitHub Copilot in VS Code, GitHub Copilot CLI, OpenAI Codex CLI. Any combination (Claude Code defaults to yes, the rest to no).
+2. **Detects greenfield vs. existing code** (counts source files) and asks you to confirm — it never decides on its own. Stored as `greenfield` in the config, because project setup needs it later.
+3. **Chooses the features root.** Kivax keeps one directory per feature under it (`specs/01-booking/`, `specs/02-cancel/`). If the project isn't greenfield it looks for `specs/`, `spec/`, `docs/specs/`… and offers what it finds — but if that folder already holds loose markdown, it says so and suggests a separate folder instead: Kivax never reads, moves, or migrates a pre-existing corpus of specs.
+4. **Asks what language the spec *content* should be written in** (`spec_language`) — see [Language](#language).
+5. **Detects your stack** by looking for `pom.xml`, `package.json`, `pyproject.toml`, `go.mod`… at the root and in first-level subdirectories (monorepo support), and presents it for confirmation.
+6. **Detects git's base branch** for PRs and diffs — `develop` when the repo has one (gitflow's integration branch), otherwise whatever `origin/HEAD` points at.
+7. **Proposes `legacy_globs`** if the project isn't greenfield — pre-existing files exempt from requiring a spec, for your confirmation. If it found a folder of spec documents you already had, that goes in too: those are documents, not untraced code, so editing one later isn't reported as a violation.
+8. **Writes `.kivax/config.yml`**, creates the (empty) features root, and **copies** the agents, skills, and orchestrator instructions into the project as ordinary files. No spec is written yet: the first one arrives with your first feature.
+
+### Commit what it creates
+
+Everything `kivax init` writes is a normal file meant to live in git:
+
+```bash
+git add .kivax/ CLAUDE.md AGENTS.md .claude/ specs/   # plus .cursor/, .github/, .codex/, .opencode/ if you use them
+git commit -m "chore: install kivax"
+```
+
+Teammates then need nothing but `git clone` — the agents, skills, and config are already in the repo. Running `kivax init` again on an already-installed project does nothing (no wizard, no re-copy); it tells you to use `kivax upgrade` instead.
+
+### Check the setup
+
+```bash
+kivax doctor
+```
+
+Diagnoses the project's installation: a missing `paths.features`, config keys left over from an older Kivax (it names each one and what replaced it), an `agents:` entry naming an agent that doesn't exist, a phase whose `kivax-<phase>` skill is missing, duplicate feature numbers or ids, a mistyped feature directory, tag regexes that predate the per-feature id form, and empty agent/skill directories. It stays quiet about documentation folders you deliberately keep alongside your features — it only flags a directory that was clearly *meant* to be a feature.
+
+---
+
+## Using it day to day
+
+Once installed, you drive Kivax by **talking to your assistant**, not by typing CLI commands. Each phase of the flow is a *skill* the assistant reads (`kivax-spec`, `kivax-plan`, …); you either name the skill or just describe what you want and let it trigger.
+
+### The pipeline
+
+The sequence, fixed and the same in every Kivax project:
+
+```
+spec → compile → plan → tdd → it → audit → retro → done
+```
+
+| Phase | Skill | What happens | Gate |
+|---|---|---|---|
+| `spec` | `kivax-spec` | Drafts/refines the narrative `spec.md` by interviewing you. | human |
+| `compile` | `kivax-compile` | Compiles `spec.md` → canonical `spec.yml`; validates and hashes it. | human |
+| `plan` | `kivax-plan` | Writes `plan.md` (contracts, REQ→module→test mapping), cuts `feature/NN-slug`, pushes, opens a draft PR. | human |
+| `tdd` | `kivax-tdd` | Per REQ: red unit tests, then minimum code until green. | auto |
+| `it` | `kivax-it` | Integration tests from the spec's `integration_scenarios`. | auto |
+| `audit` | `kivax-audit` | Traceability gate (`kivax trace`) + clean-context PR review, then marks the PR ready. | human |
+| `retro` | `kivax-retro` | Records what the cycle *cost* as lessons the next one has to answer for. | human |
+
+Every phase runs, for every feature. The sequence is not configurable, and neither are the gates — they're the workflow Kivax exists to impose, not settings.
+
+Writing `PRINCIPLES.md` and `ARCHITECTURE.md` is **not** part of this sequence: those describe the project, so they happen once, before your first feature — see [Project setup](#project-setup-principles-and-architecture).
+
+A **gate** is what happens at the end of a phase: `human` means the assistant stops and waits for your explicit approval; `auto` means it chains straight into the next phase. The phases where a mistake is expensive and hard to walk back — a wrong spec, a wrong plan, a passed audit — are the ones a person has to see.
+
+**Exceptions are not gates and are not configurable.** An `AMBIGUITY`, `DISPUTE`, `GAP`, `CONFLICT`, `PRINCIPLES-VIOLATION`, a `NOT PASSING` audit verdict, or a failed validation **always** stops the flow and comes to you, even when the gate is `auto`. `auto` delegates approval, never quality control.
+
+### A first feature, end to end
+
+```
+You:  Start a new feature: users can cancel a booking up to 24h before check-in.
+```
+
+The assistant runs `kivax-new`, which calls `kivax feature new cancel-booking`: that allocates the next feature number, creates `specs/01-cancel-booking/` with its own `spec.md`, and makes it the active feature. Then `kivax-spec`: it asks you clarifying questions, writes the spec, and stops at the `spec` human gate with its open questions and assumptions.
+
+```
+You:  Approved.
+```
+
+It compiles to `spec.yml` (`kivax-compile`), shows you the assigned REQ-IDs and the hash diff, and stops again. Approve, and `kivax-plan` explores your codebase, writes `plan.md` with concrete contracts, creates the branch, opens a draft PR, and stops.
+
+```
+You:  Looks good — run through to the audit.
+```
+
+That's `kivax-run`: it chains `tdd` (red tests → green code, one REQ at a time, one commit per REQ) and `it`, both `auto`, and stops at the `audit` human gate with the traceability verdict and the reviewer's findings. Approve, and `kivax-retro` writes down what the cycle cost — the bug that took three attempts, the assumption that was wrong twice — as lessons the *next* feature is forced to answer for. You merge; Kivax never does.
+
+### Everyday commands (things you say)
+
+| You want to… | Ask for | Notes |
+|---|---|---|
+| Start a feature | `kivax-new <description>` | Creates `specs/NN-slug/` with its own spec. One active feature per branch. |
+| Write/refine the spec | `kivax-spec <request>` | The only phase that interviews you at length. |
+| Run several phases at once | `kivax-run` | Stops at the first human gate or exception, and tells you which. |
+| Know where things stand | `kivax-status` | Current phase, REQs by status, coverage, stale hashes. |
+| Change a requirement after the fact | `kivax-evolve <change>` | Selectively invalidates only the affected REQs — never everything. Works on any feature, including ones that shipped long ago. |
+| Build/query the knowledge wiki | `kivax-wiki ingest \| query <question> \| lint` | Derived from the specs; the spec always wins. |
+| Record what an iteration taught | `kivax-retro` | Runs after the audit. Writes the lessons store; later phases must answer for it. |
+| Document legacy code before touching it | `kivax-spec` ("document the current behavior of X") | Retroactive spec mode — describes what the code *does*, not what it should do. |
+
+Six more skills are reference material the specialists read rather than phases you invoke: `kivax-spec-writing`, `kivax-yml-spec`, `kivax-tdd-loop`, `kivax-wiki-schema`, `kivax-lessons-schema`, `kivax-tasks`.
+
+**Vague ideas get researched first.** If you arrive with a problem that has no shape yet — or one whose answer depends on options nobody on the team has checked — the `spec` phase can bring in the **researcher** before the interview starts. It's the one agent that reaches the internet: it reads your principles, architecture, and code first so it only proposes things this project can actually do, then comes back with `specs/NN-slug/research.md` — two or more real options with their costs, concrete prior art, and every claim carrying a dated source URL. It writes no requirements; the spec-analyst uses the brief as the starting point of its interview, and you approve what makes it into the spec. It's optional and skipped by default when you already know what you want — the assistant asks rather than assuming.
+
+> `kivax init` (terminal, project setup) is a different thing from `kivax-new` (chat, start a feature). The first is infrastructure and you run it yourself; the second is workflow.
+
+### Artifacts you'll see
+
+| File | Owner | Lifecycle |
+|---|---|---|
+| `specs/NN-slug/research.md` | researcher | Optional. Options, prior art, and cited sources behind a vague idea — input to the spec, never a requirement. |
+| `specs/NN-slug/spec.md` | spec-analyst | That feature's narrative spec — the human-readable source. |
+| `specs/NN-slug/spec.yml` | spec-compiler | That feature's canonical anchor. IDs are immutable; hashes drive invalidation. |
+| `specs/NN-slug/plan.md` | tech-planner | Contracts, REQ→module→test mapping, implementation order for that feature. |
+| `specs/wiki/` | wiki-curator | Optional compiled knowledge, one page per domain concept. |
+| `specs/lessons/LSN-*.md` | knowledge-curator | What past iterations cost. Written by `retro`, enforced at the audit gate. |
+| `.kivax/state.yml` | the CLI | Current phase and per-REQ status. The single source of truth across sessions. |
+| `.kivax/traceability.lock.json` | trace-auditor | Hashes and REQ→tests from the last PASSING cycle. |
+| `PRINCIPLES.md` / `ARCHITECTURE.md` | spec-analyst / tech-planner | Project-wide, opt-in. |
+
+State lives in the repo, not in the assistant's context — you can close the session, come back tomorrow, and it picks up from `.kivax/state.yml`.
+
+### Interrupted mid-agent
+
+Knowing the phase isn't always enough. If the session dies while the tech-planner is halfway through exploring your modules, "phase: plan" tells the next session to start the plan — not to finish the one already half-written on disk. Re-running from scratch is worse than it sounds: an agent given the same prompt twice can produce a *different* plan, and you end up reconciling two.
+
+So the long-running specialists — researcher, spec-analyst, tech-planner, test-writer, implementer, wiki-curator, knowledge-curator — write down their steps before working and mark them off as they go, via `kivax task`. The list lives in `.kivax/state.yml` beside the phase and the per-REQ status, and is archived and restored with its feature.
+
+```bash
+kivax task list
+```
+
+```
+Phase 'spec' (01-cancel-booking):
+  [x] 1. Read PRINCIPLES.md and ARCHITECTURE.md  <researcher>
+  [~] 2. Search primary sources for option A  <researcher>  (3 of 6 sources checked)
+  [ ] 3. Write research.md  <researcher>
+
+1/3 closed.
+Resume at: 2. Search primary sources for option A  <researcher>
+```
+
+You don't run this yourself in normal use: `kivax state show` ends with the same resume point, and the orchestrator reads it at the start of every session — it will tell you what was in flight and offer to continue rather than restart. The single-pass agents (spec-compiler, trace-auditor, reviewer) keep no list, because re-running them from scratch is already the right recovery.
+
+These tasks are **not** requirements. A task is one agent's disposable working step; a REQ is the flow's contract, tracked separately and read by traceability. Nothing in the audit ever looks at a task.
+
+### One spec per feature
+
+Each feature gets its own directory, and it stays in the repo after the feature ships:
+
+```
+specs/
+  01-booking/        spec.md  spec.yml  plan.md
+  02-cancel-booking/ spec.md  spec.yml  plan.md
+  wiki/              (project-wide, spans features)
+```
+
+The directory number prefixes every id in that spec — `REQ-01-001`, `IT-02-003` — so ids are unique project-wide and a test tag resolves to exactly one requirement. Numbering restarts per feature: feature 02 has its own `REQ-02-001`.
+
+**Old specs keep being enforced.** `kivax validate`, `kivax hash`, and `kivax trace` all operate on the union of every feature's spec. Edit the spec of something that merged three months ago and its hashes change, its tests are flagged as potentially stale, and the audit blocks until that change goes through `kivax-evolve` — a spec change always has to produce a code change. Only the phase workflow is scoped to one feature: the *active* one, one per git branch.
+
+You rarely touch this yourself; `kivax-new` and `kivax-evolve` drive it. The commands behind them are `kivax feature new <slug>`, `kivax feature list`, `kivax feature show --json`, and `kivax feature switch <NN>` (to resume a feature that already shipped).
+
+---
+
+## Language
+
+Two deliberately independent things:
+
+- **The CLI (`kivax` and the `lib/` modules behind it) is always in English.** Not configurable — it's infrastructure, not content, which keeps it maintainable and easy to get help with.
+- **The specs' content follows `spec_language`**, a free-form value you set during `kivax init` (or edit later in `.kivax/config.yml`). The spec-analyst writes titles, descriptions, and acceptance criteria in that language regardless of what language you speak to it in — so you can converse in whatever you like and still guarantee specs land in, say, Spanish, if that's your team's documentation language.
+
+The agents and skills (the instructions the assistant reads) are written in English and don't change with `spec_language`. That doesn't affect what language the assistant replies to you in, which always follows the conversation.
+
+One technical constraint that never changes: the **keys** in `spec.yml` (`given`, `when`, `then`, `requirements`, `priority`…) are fixed. They're the format the scripts read literally; translating them would break validation and traceability. Only the prose gets translated.
+
+---
+
+## Git: the flow is a gitflow feature branch
+
+Every feature runs on its own branch and **ends as a pull request marked ready for review**. That pull request is the deliverable — Kivax never merges it.
+
+```
+develop ──┬─────────────────────────────────────────────► (you merge)
+          └── feature/01-booking ──[spec+plan]──[REQ commits]──[IT]──[lessons]──► PR ready
+```
+
+| Phase | What it does to git |
+|---|---|
+| `plan` | `git checkout -b feature/NN-slug origin/<base>`, commits spec+plan, **pushes**, opens the PR as a **draft** |
+| `tdd` | one commit per green REQ (`feat(REQ-01-002): …`), pushes before the phase ends |
+| `it` | commits the integration tests, pushes |
+| `retro` | commits the lessons store, pushes |
+| `audit` | checks the tree is clean and everything is pushed, then marks the PR **ready** and writes the reviewer's summary into its description |
+
+**The base branch is gitflow's integration branch.** `kivax init` picks `develop` when the repo has one, and stores it as `git.base_branch`. It deliberately doesn't trust `origin/HEAD`: that points at the *published* branch, which on a gitflow repo is `main` — a feature PR against it would be targeting production. The branch name (`feature/`) is fixed, like the pipeline.
+
+**Every phase pushes.** A commit that isn't pushed isn't in the pull request, and the pull request is the only thing a reviewer actually reads.
+
+### Merges, releases, and hotfixes
+
+These are **not** part of the flow. They live in the `kivax-git` skill, which runs **only when you ask for it by name** and confirms every irreversible step with you first:
+
+| Ask for | What it does |
+|---|---|
+| merge | Checks the PR isn't draft, its checks are green, and it has an approving review — then merges on your confirmation |
+| release | Opens a `develop → main` PR, and after it lands, tags and opens the back-merge |
+| hotfix | Branches from `main`, and reminds you the fix still needs a spec, then opens PRs into **both** `main` and `develop` |
+
+The assistant will never merge, tag, or deploy on its own initiative — not even when the audit passes. A passing audit is what makes a PR *reviewable*; it isn't a review.
+
+---
+
+## Project setup (principles and architecture)
+
+After `kivax init`, one thing is left before your first feature. Open your assistant and ask it to set the project up — the **`kivax-setup`** skill. It writes two project-wide documents, once:
+
+- **`PRINCIPLES.md`** — the project's non-negotiable engineering principles, ratified by interviewing you (the spec-analyst). It is **not** a living document: once ratified it changes only on an explicit request to amend it, never as a side effect of a feature.
+- **`ARCHITECTURE.md`** — the system's actual technical shape (the tech-planner drafts it from the intended stack for a greenfield project, or reverse-engineers it from the existing codebase — decided by the `greenfield` flag), then kept current **incrementally**: every `kivax-plan` updates only the sections the feature actually affects.
+
+These are **not phases**. They describe the project, not the thing you're building this week, so putting them at the head of every feature's pipeline would have meant answering a question about the repository in the wrong place — two steps in every feature's history that did nothing. They happen once, they're tracked by the files existing on disk, and `kivax state` never sees them.
+
+`kivax feature new` refuses while either document is missing:
+
+```
+ERROR: this project hasn't been set up yet — PRINCIPLES.md, ARCHITECTURE.md are missing.
+```
+
+That's the whole enforcement: mandatory, but paid for once. `kivax doctor` reports it as a next step on a fresh project, and as a real problem if features already exist without them.
+
+Every `kivax-plan` and `kivax-audit` also cross-checks the feature against `PRINCIPLES.md` when it exists. A conflict is a `PRINCIPLES-VIOLATION:` — always escalated to you, never auto-resolved, regardless of the gate.
+
+---
+
+## The lessons store (the `retro` phase)
+
+`spec.yml` records what was built. The wiki records what it means. Neither records what it **cost** — which bug was rediscovered, which assumption was wrong twice, which fix had to be redone — and that's the knowledge a team actually loses between iterations. The `retro` phase runs last, after the audit passes, and writes it down.
+
+The knowledge-curator doesn't reconstruct the cycle from memory. It reads the evidence the repo already holds: `.kivax/state.yml`'s history (a REQ that cycled `red → green → red`, one marked `invalidated`), the branch's fix-on-fix commits, the audit violations, the reviewer's repeated BLOCKING findings. One lesson per file:
+
+```markdown
+---
+id: LSN-0007                      # allocated by `kivax lessons new`, never by hand
+title: Flyway migrations must run before the Spring test context boots
+phases: [plan, tdd, it]           # which phases get shown this lesson
+paths: ["src/main/resources/db/**"]   # empty = project-wide
+origin: {feature: 03-cancel-booking, phase: it, evidence: ["commit 8f2a1c3"]}
+seen_in: [03-cancel-booking, 05-refunds]
+---
+## Rule
+Run migrations in the shared fixture's `@BeforeAll`, never per-test.
+```
+
+**This is not documentation — it binds.** `kivax-plan`, `kivax-tdd`, and `kivax-it` each run `kivax lessons relevant --phase <p>` *before* producing anything, and the plan has to answer for every applicable lesson under `## Lessons applied`:
+
+```markdown
+## Lessons applied
+- LSN-0007 — migrations moved into the shared test fixture's @BeforeAll.
+- LSN-0002 — not applicable: this feature adds no scheduled job.
+```
+
+`kivax lessons check` computes which lessons apply (the project-wide ones, plus the path-scoped ones whose globs match the branch diff or a path named in `plan.md`) and **fails when one isn't answered for**. The trace-auditor runs it as part of the audit gate. A lesson can be dismissed; it cannot be dismissed silently.
+
+Three rules keep the store from rotting into noise:
+
+- **Reinforce, don't duplicate.** The same problem hitting a second feature appends to `seen_in` and sharpens the rule — it never becomes a second lesson.
+- **Retire, don't delete.** A lesson that stopped being true gets `status: retired` with a `superseded_by` or a `retired_reason`. Deleting the file loses the record that it was ever true.
+- **Zero lessons is a valid cycle.** Every applicable lesson is read by every future planner, so each worthless entry buys inattention to the good ones. Padding the store is the one way to destroy it.
+
+A lesson is **never** a substitute for a requirement. If what the retro found is unspecified *behavior*, it's a `GAP:` and it goes through `kivax-evolve` into the spec — the lessons store is not a back door around spec-first.
+
+---
+
+
+## Project files and the global store
+
+`kivax init` copies agents, skills, and the orchestrator instructions into your project as real, ordinary, git-committed files. **Nothing in a project points back at the global store** — every file is yours to open and edit, including changing an agent's `model:` line. This also means Kivax updates never change a project's behavior on their own: pulling in changes is always an explicit step (`kivax upgrade`), reviewable with `git diff` before you commit.
+
+The global store is the "upstream" those copies come from, and it ships inside the installed package — that's why `pipx upgrade kivax` updates the CLI and the store as a single artifact, with no way for the two to disagree about which version they are. `kivax version` prints where it landed.
+
+```
+<the installed package>/kivax/data/    (the global store — read-only, part of the install)
+  agents/<name>.md                     (canonical: description + tools + body — one file per
+                                         specialist, PLUS orchestrator.md, shared by every runtime)
+  runtime/skills/                      (shared by all 6 runtimes — 6 reference skills +
+                                         14 phase-driver skills, e.g. kivax-spec/, kivax-plan/)
+  templates/                           (spec, plan, research, lesson… seeds)
+  agent_runtimes.yml                   (per-runtime agent frontmatter recipe)
+  stack_profiles.yml                   (the stack catalog the init wizard offers)
+  templates/                           (spec, plan, research, principles, architecture, state, PR…)
+  ci/                                  (sample CI gate workflow)
+
+your-project/                          (all committed to git, no exceptions)
+  .claude/agents/*.md        # generated — commit them, but change them upstream, not here
+  .claude/skills/*/SKILL.md
+  .opencode/agent/*.md       # if you use opencode
+  .opencode/skills/*/SKILL.md
+  .cursor/agents/*.md        # if you use Cursor
+  .cursor/skills/*/SKILL.md
+  .github/agents/*.agent.md  # if you use GitHub Copilot CLI
+  .github/skills/*/SKILL.md  # if you use GitHub Copilot (VS Code and/or CLI)
+  .github/copilot-instructions.md   # if you use GitHub Copilot in VS Code
+  .codex/skills/*/SKILL.md   # if you use OpenAI Codex CLI
+  CLAUDE.md / AGENTS.md      # same content, two filenames — Claude Code needs the former
+  PRINCIPLES.md              # ratified once, rarely touched again
+  ARCHITECTURE.md            # kept current via kivax-plan
+  .kivax/
+    config.yml               # project config, yours, editable
+    state.yml                # flow state (phase, REQs)
+    traceability.lock.json   # traceability lock
+    templates/               # copy of the global templates
+  specs/                     # your specs folder (or wherever you placed it)
+    01-booking/              # one directory per feature, each with its own spec
+      spec.md / spec.yml / plan.md
+    02-cancel-booking/
+      spec.md / spec.yml / plan.md
+    wiki/                    # project-wide, spans features
+    lessons/                 # LSN-NNNN-*.md — what past iterations cost
+```
+
+SKILL.md content is identical across every runtime — only the destination directory changes.
+
+**Agent files are the one thing not copied verbatim.** Each specialist — and the orchestrator itself — has a single canonical source (the store's `agents/<name>.md`: description, tools, body, no runtime-specific frontmatter), and `kivax init`/`kivax upgrade` render it into every active runtime's own agent-file shape on the fly, per the recipe in the store's `agent_runtimes.yml`. Fixing an instruction once fixes it everywhere instead of needing the same edit repeated per tool.
+
+The orchestrator's rendering is special in one way: besides landing as an ordinary agent file (`.claude/agents/orchestrator.md`, invokable explicitly on tools that support picking an agent), its frontmatter-stripped body is **also** what becomes `AGENTS.md` / `CLAUDE.md` / `.github/copilot-instructions.md` — the ambient context every runtime's default conversation reads. That's how the orchestrator is "the agent the human talks to" on tools without an agent picker.
+
+### Choosing a model per agent
+
+The agent files are generated, so you don't edit them to change a model — you say it once in `.kivax/config.yml` and Kivax bakes it into every runtime's file on the next `kivax init`/`kivax upgrade`:
+
+```yaml
+agents:
+  default:      {model: sonnet}   # applies to every agent below
+  orchestrator: {model: opus}     # ...except the ones you name
+  tech-planner: {model: opus}
+  implementer:  {model: sonnet}
+```
+
+The keys are agent names (`kivax doctor` rejects a typo). `default` is optional; omit the whole block and every agent inherits whatever model the assistant is already running. Values are passed through untouched — they're your assistant's vocabulary, not Kivax's, so use whatever spelling it expects (`opus`, `claude-opus-4-8`, `anthropic/claude-sonnet-4-5`…).
+
+This lands where the runtime can actually read it: Claude Code and Cursor take a `model:` in the agent frontmatter, opencode takes one when set, and GitHub Copilot CLI has no such field — there, the CLI picks the model and the setting has no effect.
+
+---
+
+## Keeping in sync
+
+### Pulling updates in: `kivax upgrade`
+
+Run it inside a project. It re-materializes every file Kivax manages: agents and skills are rewritten from the global store, anything Kivax used to ship and no longer does is deleted, and files it doesn't manage are never touched.
+
+There's no merge and no conflict, because there's nothing to reconcile — the agent and skill files are *generated* from the store plus your `config.yml`, so those two together are the whole truth about what they should contain. **A hand-edit to one of them will be overwritten.** Everything a project legitimately varies lives in `config.yml`, which `kivax upgrade` never rewrites.
+
+`kivax upgrade --dry-run` prints exactly what it would add, update, and remove, without writing anything. This is the only thing that ever pulls from the global store into a project, and only when you run it.
+
+## CLI reference
+
+You'll rarely type these — the assistant runs most of them for you. The ones you own are `init`, `upgrade`, `doctor`, and `version`.
+
+| Command | What it does |
+|---|---|
+| `kivax init [--force]` | Install/configure the current project (wizard), or report if already installed |
+| `kivax upgrade [--dry-run]` | Re-copy agents, skills, and templates from the global store, pruning what it no longer ships |
+| `kivax doctor` | Diagnose the current project's installation |
+| `kivax version` | Version and location of the global store |
+| `kivax feature <new\|list\|show\|switch>` | Feature lifecycle: create one, list them, resolve its paths (`show --json`), or make an existing one active |
+| `kivax validate` | Validate every feature's `spec.yml`. Exit 1 if invalid |
+| `kivax hash [--diff] [--json] [--feature NN]` | Current hashes across all features, or the diff against the lock. **Exit 2 = there is pending work, not an error** |
+| `kivax trace [--report-only\|--update-lock\|--json]` | Traceability audit across every feature: coverage, freshness, orphans. Exit 1 if NOT PASSING |
+| `kivax state <show\|set-phase\|set-req\|sync-reqs\|gate\|next>` | Phase and per-requirement status of the active feature |
+| `kivax task <add\|list\|set\|next\|clear>` | Per-agent checklists for the active feature. `list` shows where to resume after an interruption |
+| `kivax wiki <lint\|stale> [--strict] [--json]` | Wiki provenance checks |
+| `kivax lessons <list\|show\|new\|relevant\|check\|lint>` | The lessons store. `relevant --phase <p>` is what a phase reads; `check` is what the audit enforces (exit 1 = an applicable lesson isn't answered for in `plan.md`) |
+| `kivax specfirst [--json] [--base <branch>]` | Classify the branch diff into tests / kivax / legacy / production |
+
+`--runtime` accepts `claude`, `opencode`, `cursor`, `vscode-copilot`, `copilot-cli`, or `codex`.
+
+---
+
+## CI
+
+The store's `ci/github-actions-kivax.yml` (in this repo: [src/kivax/data/ci/](src/kivax/data/ci/)) is a sample CI gate: it validates the spec and runs `kivax trace`. Installing Kivax on the runner is one line — `pip install kivax` — and the sample is copy-pasteable as-is. Pin the version (`kivax==2.1.0`) if you'd rather a release never changes what your gate accepts without you choosing it.
+
+---
+
+## Troubleshooting
+
+**`kivax: command not found` after installing.**
+The installer only links into a directory *already on your PATH*. Add the store's bin directory to your shell rc and open a new terminal:
+
+```bash
+export PATH="$HOME/.kivax/bin:$PATH"
+```
+
+**`ERROR: can't find the Kivax global store at ...`**
+The store ships with the package, so this almost always means `KIVAX_HOME` is set (it overrides the packaged store) and points somewhere that isn't one. Unset it. If it isn't set, the install is damaged — `pipx install --force kivax`.
+
+**`ERROR: PyYAML is missing`**
+Shouldn't happen: pip installs it as a dependency. It means the environment was modified after install — `pipx install --force kivax` rebuilds it.
+
+**`ERROR: .kivax/config.yml does not exist. Run 'kivax init' first.`**
+You're not at the project root, or the project was never initialized. The scripts walk up parent directories looking for `.kivax/config.yml`, so this means it isn't anywhere above you.
+
+**`kivax doctor` says my config's `version` is wrong and lists keys to delete.**
+The project was installed by an older Kivax, when the pipeline, the gates, and most paths were configurable. They aren't any more — Kivax owns the flow. Nothing is broken: those keys are simply ignored. Delete the ones doctor names, set `version: 3`, and the message goes away.
+
+**An edit I made to an agent or a skill file disappeared.**
+`kivax upgrade` rewrites those files from the global store — they're generated, not yours to edit.
+
+- **To change which model an agent runs on**, use the `agents:` block in `.kivax/config.yml`. That's the supported knob, and upgrade never touches it.
+- **To change what an agent *does***, open an issue or a PR. The store lives inside the installed package and is replaced wholesale on every upgrade, so a local edit to it wouldn't survive either — behavior belongs upstream, where everyone gets the fix.
+- **If you genuinely need a divergent store** (a fork, an internal variant), point `KIVAX_HOME` at your own copy of `src/kivax/data`. Kivax will read that instead of the packaged one. You then own keeping it current — which is exactly the maintenance burden the packaged store exists to avoid, so weigh it before choosing this.
+
+**`ERROR running git diff against 'main'` from `kivax specfirst` or the audit.**
+The configured base branch doesn't exist locally. Fix `git.base_branch` in `.kivax/config.yml`, or fetch the branch.
+
+**Every new requirement shows as uncovered even though the tests exist.**
+The project's `id_tag_regexes` in `.kivax/config.yml` predate the per-feature id form, so tags like `REQ-02-001` don't match. `kivax doctor` detects exactly this and prints the replacement pattern; `kivax upgrade` warns about it too. Kivax never rewrites `config.yml` for you.
+
+**`kivax trace` is NOT PASSING because of a feature I'm not even working on.**
+That's the anchor doing its job: someone edited that feature's spec, so its hashes no longer match the lock and its tests may be stale. `kivax feature switch <NN>`, then run the `kivax-evolve` skill for it.
+
+**`ERROR: refusing to write the lock`.**
+`kivax trace --update-lock` rewrites the lock for every feature at once and refused because the rebuild didn't account for ids the lock already held — either a feature lost its `spec.yml` (recompile it) or a requirement was deleted outright instead of being marked `status: deprecated`.
+
+**The audit says a file is a spec-first violation but it's pre-existing code.**
+Add it to `legacy_globs` in `.kivax/config.yml` — and remove it again once you migrate that zone with a retroactive spec and tests.
+
+**Windows: `kivax` isn't recognized.**
+The installer prints the folder to add to your PATH. From PowerShell, add `%USERPROFILE%\.kivax\bin`, then open a new terminal.
+
+---
+
+## Updating or uninstalling
+
+**Update Kivax:** `pipx upgrade kivax`. This does **not** touch any project by itself — run `kivax upgrade` inside each project you want to bring current.
+
+**Uninstall from a project:** delete `.claude/`, `.opencode/`, `.cursor/`, `.codex/`, `CLAUDE.md`, `AGENTS.md`, and `.kivax/`. For `.github/`, don't delete the whole directory — it commonly holds unrelated CI workflows and issue templates — remove only Kivax's own paths: `.github/agents/`, `.github/skills/`, and `.github/copilot-instructions.md`. You lose the state and the lock if you hadn't committed them; since everything here is a normal file, `git log` has your history regardless.
+
+**Uninstall from the system:** `pipx uninstall kivax`. If you ever installed a pre-2.1 version from a clone, also `rm -rf ~/.kivax ~/.local/bin/kivax`.
+
+---
+
+## Scope and limitations
+
+Kivax's traceability model — spec hash ↔ tests ↔ code, verified against one git diff — **assumes a single git repository per installation**. It works well for a single repo and for monorepos (multiple stacks in one repo, via `stack.profiles[*].root`), but it does not span multiple independent repositories: a feature touching a separate frontend and backend repo needs a spec (and a `kivax init`) in each, with no built-in way to link their REQs together.
+
+The flow drives **one active feature at a time per working tree** — `.kivax/state.yml` names a single active feature. That isn't a limit on how many features a project has (they accumulate, each with its own spec), but on how many you advance simultaneously in one checkout: git branches supply the isolation, one active feature per branch. Two branches cut from the same commit can both allocate the same feature number; `kivax validate` and `kivax doctor` treat a duplicated number as a hard error, and the fix is to renumber the branch that hasn't merged yet — its tests aren't on the base branch, so rewriting its ids and tags is still local and safe.
+
+## Repository layout (this repo)
+
+```
+pyproject.toml        Packaging: console script, dependencies, package data
+assets/               Logo and other repo media
+src/kivax/
+  cli.py              The CLI — every 'kivax <cmd>' entry point
+  lib/                kivax_*.py modules the CLI dispatches to (python -m kivax.lib.X),
+                       plus kivax_agents.py, the agent renderer
+  data/               THE GLOBAL STORE — shipped inside the wheel, copied into projects
+    agents/           One canonical file per specialist (description + tools + body, no
+                       runtime-specific frontmatter), PLUS orchestrator.md — the primary
+                       coordinator, rendered like every other agent and additionally
+                       stripped of frontmatter to produce AGENTS.md / CLAUDE.md /
+                       copilot-instructions.md. Nothing here is copied verbatim.
+    runtime/skills/   6 reference skills + 14 phase-driver skills, shared by all 6
+                       runtimes (just placed in each one's own skills directory)
+    templates/        Starting scaffolds (spec, plan, research, principles, architecture,
+                       lesson, state, PR)
+    ci/               Sample CI gate workflow
+    stack_profiles.yml  The stack catalog the init wizard offers
+    agent_runtimes.yml  Per-runtime agent frontmatter recipe
+    VERSION           Single source of truth: the distribution version and what
+                       'kivax version' reports
+```
+
+## Contributing
+
+Issues and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers running the test suite, how the repository is laid out, and the conventions that aren't obvious from the code — chiefly that agents and skills are documentation the assistant *executes*, so they change alongside the CLI.
+
+```bash
+pytest tests                                                          # unit + integration + e2e
+pytest tests --cov --cov-config=.coveragerc --cov-report=term-missing # coverage gate (>= 90%)
+ruff check .                                                          # lint
+```
+
+## License
+
+[MIT](LICENSE).