@rasensio/aidlc 1.27.1 → 1.28.0

package/README.md

@@ -1,25 +1,55 @@
-# @rasensio/aidlc
+<!-- Generated from the repo-root README.md by packages/cli/scripts/sync-readme.mjs.
+     Edit that file, not this one. npm renders this copy; GitHub renders the root. -->
 
-Structured lifecycle guidance for AI coding agents across platforms. One set of skills, every major AI coding tool.
+<div align="center">
 
+# `$ aidlc_`
+
+## AI codes fast. AIDLC makes it ship right.
+
+A real software lifecycle for AI coding agents: **phases, gates, state, and traceability** — from idea to maintenance, on any agent platform.
+
+[![npm](https://img.shields.io/npm/v/%40rasensio%2Faidlc?logo=npm&color=cb3837)](https://www.npmjs.com/package/@rasensio/aidlc)
+[![downloads](https://img.shields.io/npm/dm/%40rasensio%2Faidlc?color=1f9d55)](https://www.npmjs.com/package/@rasensio/aidlc)
+[![node](https://img.shields.io/node/v/%40rasensio%2Faidlc?logo=node.js&logoColor=white)](https://nodejs.org)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/rasensio/aidlc/blob/main/LICENSE)
+[![website](https://img.shields.io/badge/docs-aidlc.rodrigoasensio.com-6d28d9)](https://aidlc.rodrigoasensio.com)
+
+**[🌐 Homepage](https://aidlc.rodrigoasensio.com)** · [📚 Docs](https://aidlc.rodrigoasensio.com/docs/) · [🎓 Tutorials](https://aidlc.rodrigoasensio.com/tutorials/) · [📝 Blog](https://aidlc.rodrigoasensio.com/blog/) · [📦 npm](https://www.npmjs.com/package/@rasensio/aidlc)
+
+```bash
+npx @rasensio/aidlc init
+```
+
+**One command. Any agent.**
 
-## What is AIDLC?
+</div>
 
-AIDLC brings phase-driven workflows, review gates, and quality checkpoints to AI-assisted software development. Instead of letting your AI assistant jump straight into code, AIDLC guides it through structured phases — ideation, requirements, design, implementation, testing, deployment, and maintenance.
+---
 
-Works with **Claude Code**, **Cursor**, **Windsurf**, **Kiro**, and **Codex**.
+## The problem isn't speed
 
-## Requirements
+Agents outpace the capacity to review what they produce. What's missing isn't throughput — it's the lifecycle around it:
 
-**Node.js >= 22.13.** The knowledge graph uses the built-in `node:sqlite` module — zero native dependencies, but it needs a modern runtime.
+- requirements anyone actually agreed to
+- designs anyone actually challenged
+- tests mapped to the criteria they're supposed to prove
+- a record of why decisions were made
 
-> **Upgrading from an earlier version?** The CLI previously supported Node >= 18. Upgrade your Node runtime (e.g. `nvm install 22`); no other migration steps are required — existing `.aidlc/` state and skills work unchanged.
+AIDLC adds that missing lifecycle **without slowing the agent down**. It works with **Claude Code**, **Kiro**, **Cursor**, **Windsurf**, **Codex**, **GitHub Copilot** — and any platform that reads skills. State lives as plain YAML in your repo: no server, no lock-in.
+
+## The loop
+
+An idea arrives mid-task, gets captured in five seconds, and comes back out the far end with a number attached to it.
+
+> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#the-loop)** — npm does not render Mermaid.
+
+Nothing in that picture lives in a database. Every box is a file in your repository, readable by the next agent, the next session, and you.
 
 ## Quick Start
 
 ```bash
-# Set up AIDLC once — interactive wizard, or pass --platform to skip prompts
+# 1 — Set up once (interactive wizard, or pass --platform to skip prompts)
 npx @rasensio/aidlc init --platform claude-code
 ```
 
@@ -31,71 +61,168 @@ Then work from your AI coding tool. In Claude Code, invoke the entry point:
 
 It reads your lifecycle state and offers the next actions — continue an in-progress instance, start something new, check status, or review an artifact. You can also just describe what you want ("help me fix a bug") and the matching skill activates on its own.
 
-## CLI Commands
+Prefer the terminal? The same state protocol is addressable directly:
+
+```bash
+aidlc start full-feature --name dark-mode
+aidlc status
+```
 
-The CLI has two core jobs: **bootstrap** (installing and refreshing skills) and **CI enforcement** (`aidlc gate`). Lifecycle work happens inside your AI tool via skills; the runtime commands below remain available as terminal shortcuts for the same state protocol.
+```text
+Name                Template      Phase           Completion  Owner       Stalled  Cost   Coverage  Tasks
+------------------  ------------  --------------  ----------  ----------  -------  -----  --------  -------
+20260821-dark-mode  full-feature  implementation  57%         session-a1  no       $4.18  12/14     9/12 ▸1
+20260824-login-500  bugfix        testing         80%         -           no       $0.92  3/3       4/4
+```
 
-| Command | Purpose |
-|---------|---------|
-| `aidlc` (no arguments) | Interactive menu of common commands; each entry shows the command it runs |
-| `aidlc menu` | The same menu, addressable by name |
-| `aidlc init [--platform <id>]` | Set up AIDLC: interactive wizard, or non-interactive with `--platform` |
-| `aidlc update` | Update CLI and refresh project skills |
-| `aidlc gate <phase>` | CI gate check (exit 0 = pass, 1 = fail) |
-| `aidlc start [template]` | Begin a new lifecycle instance |
-| `aidlc continue [instance]` | Resume the active instance |
-| `aidlc status [--json]` | Show progress across active instances |
-| `aidlc transition <instance>` | Evaluate gates and advance phase |
-| `aidlc review <artifact>` | Adversarial review of an artifact |
-| `aidlc discover [--no-knowledge]` | Scan codebase, generate context docs, seed the knowledge graph |
-| `aidlc docs` | Generate onboarding documentation |
-| `aidlc knowledge <subcommand>` | Query and update the local knowledge graph (see below) |
-| `aidlc add action <description>` | Create lifecycle automation from a natural language description |
-| `aidlc compliance <subcommand>` | Install compliance packs and report evidence per control (`list`, `add`, `remove`, `check`, `report`) |
+Or run `aidlc` with no arguments for an interactive menu of the common commands.
 
-## Knowledge Graph
+## The gate is the whole idea
 
-AIDLC keeps a persistent, git-versioned memory of your codebase in `.aidlc/knowledge/` — human-readable YAML as the source of truth, backed by a SQLite FTS5 index for fast queries. Agents consult it before re-exploring code and record what they learn after changing it.
+A phase doesn't end because an agent says it did. It ends when the gate lets it.
 
-```bash
-aidlc discover                                  # seed from static analysis (modules, deps, endpoints, conventions)
-aidlc knowledge query "payment"                 # full-text search
-aidlc knowledge get payment-service             # one entity + its relationships
-aidlc knowledge graph payment-service --depth 2 # subgraph traversal
-aidlc knowledge context --max-tokens 2000       # markdown summary for agent prompts
-aidlc knowledge add --id my-decision --type decision --name "Use X" --description "…"
-aidlc knowledge sync                            # after git pull: rebuild index, flag suspicious merges
-```
+> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#the-gate-is-the-whole-idea)** — npm does not render Mermaid.
+
+The same binary runs in CI. `aidlc gate <instance> <phase>` exits 0 when the phase is complete and 1 when it isn't, so a pull request can be blocked by the identical check the agent just faced — see [`ci/aidlc-gate.yml`](https://github.com/rasensio/aidlc/blob/main/ci/aidlc-gate.yml).
+
+| | |
+|---|---|
+| **🚦 Phases with gates** | Each phase exits through a gate that requires artifacts, adversarial review, and a test per criterion. Agents cannot skip ahead. |
+| **💾 State on disk** | Lifecycle state is YAML under `.aidlc/` — readable across agents, sessions, and git worktrees. Claims stop concurrent sessions from colliding. |
+| **🔗 Traceability built in** | Every acceptance criterion gets an ID. Tasks reference criteria; tests reference both. The gate fails on any criterion without a test. |
 
-Multi-user teams can install a git merge driver that auto-resolves concurrent edits to knowledge files (`aidlc knowledge install-merge-driver` — asks for confirmation before touching git config). The SQLite index (`index.db`) is a disposable cache and stays out of git; only the YAML is versioned.
+## How much process? Pick a template
+
+Ceremony that fits a new subsystem will make people route around a typo fix. So the amount of lifecycle is a choice you make per piece of work, and it is the choice worth getting right.
+
+> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#how-much-process-pick-a-template)** — npm does not render Mermaid.
+
+| Template | Scope | Description |
+|----------|-------|-------------|
+| `full-feature` | full | Full lifecycle from ideation through maintenance with adversarial review gates |
+| `quick-feature` | standard | Standard feature workflow from requirements through deployment |
+| `bugfix` | standard | Bug fix workflow with reproduction steps, no design phase |
+| `spike` | standard | Spike or research workflow for exploration and findings documentation |
+| `micro-task` | micro | Minimal workflow for small tasks requiring only implementation and testing |
+
+**Scope** is the second dial, and the one people get wrong: it is not how big or ambitious the work is, it is which phases run. **Full** (all phases), **Standard** (Requirements → Deployment), **Micro** (Implementation + Testing only). A large change with a settled design is standard; a small change nobody has thought about is full.
+
+## Lifecycle Phases
+
+| Phase | Purpose |
+|-------|---------|
+| Ideation | Explore and validate ideas, identify alternatives |
+| Requirements | Define acceptance criteria, scope, and constraints |
+| Design | Produce architecture and technical design documents |
+| Implementation | Write code following established conventions |
+| Testing | Validate correctness and coverage |
+| Deployment | Release to target environment |
+| Maintenance | Monitor, patch, and evolve |
+
+When requirements move after their phase closed, `aidlc amend <instance>` retires the old criterion, issues a replacement, and reopens exactly the phases that assumption invalidated — so drift shows up in history instead of hiding behind gates that all still pass.
+
+## Two people, one repo
+
+Claims are a lease on an instance, not a lock on the filesystem. They are what keeps two sessions from silently overwriting each other's phase.
+
+> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#two-people-one-repo)** — npm does not render Mermaid.
+
+For genuinely concurrent work, use a worktree: `aidlc start --worktree` puts the second instance in its own checkout, because two sessions in one checkout collide on git long before they collide on state.
 
 ## Supported Platforms
 
+One canonical skill body is written once and packaged into whatever each tool reads natively.
+
+> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#supported-platforms)** — npm does not render Mermaid.
+
 | Platform | Config Location | Strategy |
 |----------|----------------|----------|
 | Claude Code | `.claude/skills/aidlc-*/SKILL.md` | Thin activation shims |
 | Kiro | `.kiro/skills/aidlc-*/SKILL.md` + steering | Shims + steering file |
 | Cursor | `.cursor/rules/aidlc-*.mdc` | Description-based rules |
 | Windsurf | `.windsurf/rules/aidlc-*.md` | Size-constrained pointer shims |
-| Codex | `.agents/skills/aidlc-*/SKILL.md` + `AGENTS.md` | Full skill bodies + managed block |
-| GitHub Copilot | `.github/skills/aidlc-*/SKILL.md` + `.github/copilot-instructions.md` | Full skill bodies + managed block |
+| Codex | `AGENTS.md` | Managed delimiter block |
+| GitHub Copilot | `.github/skills/aidlc-*/SKILL.md` + `.github/copilot-instructions.md` | Full bodies + instructions block |
+
+Switching assistants, or having two people on different ones, doesn't fork your process: the rules are in your repository, the packaging is per-tool.
+
+## It Closes the Loop
+
+Most tooling stops at "the feature shipped." AIDLC keeps measuring after that, from state you already have:
+
+```bash
+aidlc metrics
+```
+
+```text
+Feedback-loop metrics (attribution: full-count-per-cause)
+Coverage: 14 instances, 5 with defect linkage, 12 with cost data
+
+By template:
+  full-feature: 6 completed, change failure rate 33%, avg lead time 2.4d
+    phases: ideation 3.1h, requirements 5.8h, design 7.2h, implementation 1.4d
+  bugfix: 5 completed, change failure rate 0%, avg lead time 4.6h
+
+By instance:
+  20260821-dark-mode (full-feature): complete, lead 2.1d, cost $4.18, caused 1 bugfix(es), true cost $5.10
+```
+
+- **`aidlc metrics`** — DORA-style roll-ups: change failure rate per template, lead time per phase, and true feature cost including the bugfixes it caused
+- **`aidlc cost`** — per-instance cost tracking with metered capture across every session that touched the instance
+- **`caused_by`** — links a bugfix back to the feature that produced it, so quality leaks become measurable instead of anecdotal
+
+## Learn it
+
+The tutorials are on the website, where the terminal transcripts are interactive.
+
+**[🎓 Getting Started](https://aidlc.rodrigoasensio.com/tutorials/getting-started/)** — five steps: install, pick a template, run one instance end to end, enforce the gate in CI.
+
+**[📖 The deep dive](https://aidlc.rodrigoasensio.com/tutorials/deep-dive/)** — eight short chapters covering everything past that first session:
+
+1. [Why the work lives in files](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-why-files/)
+2. [How much process is enough](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-how-much-process/)
+3. [The check that says no](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-gates-that-say-no/)
+4. [Notes about your code, kept once](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-memory/)
+5. [What it cost, and what it really cost](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-what-it-cost/)
+6. [Ideas that don't evaporate](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-ideas-you-keep/)
+7. [Two people, one checkout](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-two-people/)
+8. [Making it yours](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-making-it-yours/)
 
-GitHub Copilot gets full skill bodies rather than pointer shims, so every phase skill
-activates on its own description and `/aidlc` works as a slash command. The instruction
-block goes in `.github/copilot-instructions.md` because that is the one customization file
-every Copilot surface reads — editor chat, the cloud agent, code review and the CLI. It
-writes nothing under `.claude/`, `.agents/` or any other vendor's directory.
+Reference material is generated from the shipped packages, so it cannot drift from what you install: **[CLI reference](https://aidlc.rodrigoasensio.com/docs/cli/)** · **[phases](https://aidlc.rodrigoasensio.com/docs/phases/ideation/)** · **[skills](https://aidlc.rodrigoasensio.com/docs/skills/overview/)** · **[templates](https://aidlc.rodrigoasensio.com/docs/templates/bugfix/)** · **[guidance layers](https://aidlc.rodrigoasensio.com/docs/guidance/secure-defaults/)** · **[glossary](https://aidlc.rodrigoasensio.com/docs/glossary/)**.
 
-## How It Works
+And [📝 the blog](https://aidlc.rodrigoasensio.com/blog/) has a post per release, written the moment the work landed — including the ones where it went wrong.
 
-1. **Install** — `aidlc init` creates a `.aidlc/` directory with skills and configuration, compiled for your platform
-2. **Pick a template** — full features, quick tasks, bug fixes, or spikes
-3. **Your AI follows the lifecycle** — skills activate in each phase, and the agent manages state directly in `.aidlc/state/` (plain YAML)
-4. **Gates enforce quality** — phase transitions require artifacts to be complete; `aidlc gate` gives CI the same check
+## CLI Commands
 
-## Non-Interactive Setup
+The CLI has two core jobs: **bootstrap** (installing and refreshing skills — the step that can't be a skill) and **CI enforcement** (`aidlc gate`, which runs where no agent does). Lifecycle work itself happens inside your AI tool via skills; the runtime commands below remain available as terminal shortcuts for the same state protocol.
 
-For CI or AI-agent-driven setup:
+| Command | Purpose |
+|---------|---------|
+| `aidlc` (no arguments) | Interactive menu of common commands; each entry shows the command it runs |
+| `aidlc menu` | The same menu, addressable by name |
+| `aidlc init [--platform <id>]` | Set up AIDLC: interactive wizard, or non-interactive with `--platform` |
+| `aidlc update` | Update CLI and refresh project skills |
+| `aidlc gate <instance> [phase]` | CI gate check (exit 0 = pass, 1 = fail) |
+| `aidlc start [template]` | Begin a new lifecycle instance (`--name`, `--scope`, `--worktree`) |
+| `aidlc continue [instance]` | Resume the active instance |
+| `aidlc status [--json]` | Show progress across active instances (`--all`, `--prune`) |
+| `aidlc transition <instance>` | Evaluate gates and advance phase |
+| `aidlc amend <instance>` | Record a requirements amendment and reopen the phases it invalidated (`--impact` is read-only) |
+| `aidlc review <instance> <artifact>` | Adversarial review of a lifecycle artifact |
+| `aidlc metrics [--json]` | DORA-style metrics: change failure rate, lead times, true cost |
+| `aidlc cost` | Per-instance cost tracking: reports, capture, rates, hooks |
+| `aidlc claim` / `release` | Claim or release an instance for this session |
+| `aidlc knowledge` | Local knowledge graph — persistent codebase memory for agents |
+| `aidlc discover` | Scan codebase, generate context docs |
+| `aidlc docs` | Generate onboarding documentation |
+| `aidlc doctor` | Check and repair repo hygiene |
+| `aidlc constitution` | Import a product vision document and track the repo scope derived from it |
+| `aidlc compliance` | Install compliance packs and report evidence per control (`list`, `add`, `remove`, `check`, `report`) |
+| `aidlc roadmap` | Project the roadmap onto GitHub Issues (`sync`), or seed an item from one (`import`) |
+| `aidlc add` | Add framework components: an `action` on a lifecycle event, or an app-owned `skill` |
+
+<details>
+<summary><b>Non-interactive setup (CI or agent-driven)</b></summary>
 
 ```bash
 # Apply defaults (or keep the existing config) without prompts
@@ -105,6 +232,8 @@ npx @rasensio/aidlc init --non-interactive
 npx @rasensio/aidlc init --platform claude-code
 ```
 
+</details>
+
 ## Configuration
 
 Project configuration lives in `.aidlc/config.yaml`:
@@ -118,6 +247,157 @@ claim_timeout_minutes: 60
 
 Without this file, AIDLC defaults to Micro scope (Implementation + Testing only).
 
+## Compliance packs
+
+A compliance pack applies a regime's controls while code is written and reports the
+evidence the lifecycle already produces. Packs are opt-in: with none installed,
+nothing changes. Install one with `aidlc compliance add <pack>`, and it applies from
+the next phase — advisory by default, so findings are recorded and reported without
+blocking. Set `compliance.enforce: true` in `.aidlc/config.yaml` to make a critical
+control finding block a phase transition.
+
+Packs describe themselves as guidance toward a regime. Nothing a pack emits states or
+implies that a project is compliant, certified, or audit-ready.
+
+`aidlc compliance check` assesses a change against the installed controls, for use in
+continuous integration. Its exit codes:
+
+| Exit | Meaning |
+|------|---------|
+| 0 | No failing control, or failures present in advisory mode |
+| 1 | A failing critical control, with `--enforce` |
+| 2 | Usage or pack-load error, or a control left unassessed with `--enforce` |
+
+`--enforce` raises the exit code for that one invocation and reads no config, so a
+failing pull-request check does not require blocking every local phase transition. An
+unassessed control exits non-zero under `--enforce` rather than passing silently: a
+control nothing looked at is never a pass.
+
+## Architecture
+
+Three packages, one direction of dependency.
+
+> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#architecture)** — npm does not render Mermaid.
+
+- **`@rasensio/aidlc-content`** — Knowledge layer. Skills, templates, guidance documents, capability maps, and phase definitions. The single source of truth for what AIDLC knows about lifecycle phases.
+- **`@rasensio/aidlc`** (CLI) — Engine. Orchestrates lifecycle state, compiles skills into platform-native formats, evaluates transition gates, and manages instance sessions.
+- **`@rasensio/aidlc-website`** — Documentation and marketing site at [aidlc.rodrigoasensio.com](https://aidlc.rodrigoasensio.com).
+
+Content is the shared dependency. The CLI reads it at compile time to produce installable artifacts. The website reads it at build time to generate documentation pages — which is why the reference docs cannot describe a command the binary doesn't have.
+
+<details>
+<summary><b>Monorepo structure</b></summary>
+
+This repository is a pnpm workspace:
+
+```
+aidlc/
+├── docs/                 # How AIDLC works — nine prose pages on why each subsystem exists
+├── packages/
+│   ├── content/          # @rasensio/aidlc-content — skills, templates, guidance, capabilities
+│   ├── cli/              # @rasensio/aidlc — CLI tool (npm package)
+│   └── website/          # @rasensio/aidlc-website — documentation website (Next.js)
+├── ci/                   # CI pipeline configuration
+├── pnpm-workspace.yaml
+├── tsconfig.json         # Shared compiler options + project references
+└── package.json          # Workspace-level scripts
+```
+
+| Package | Description | Published |
+|---------|-------------|-----------|
+| `@rasensio/aidlc-content` | Shared content (skills, templates, guidance layers, capability maps) | npm |
+| `@rasensio/aidlc` | CLI tool — lifecycle engine, platform adapters, state management | npm |
+| `@rasensio/aidlc-website` | Marketing site + documentation (Next.js, Tailwind, static export) | AWS Amplify — [aidlc.rodrigoasensio.com](https://aidlc.rodrigoasensio.com) |
+
+</details>
+
+## How this repo works
+
+Reference docs tell you *what* a command does. [**`docs/`**](https://github.com/rasensio/aidlc/blob/main/docs/README.md) tells you *why the subsystem exists and what breaks without it* — nine pages, written for a person trying to understand the system and for an agent about to change it. Read the relevant page before modifying a subsystem: several of these designs look arbitrary until you know which bug bought them.
+
+| Page | What it covers |
+|---|---|
+| [lifecycle.md](https://github.com/rasensio/aidlc/blob/main/docs/lifecycle.md) | Instances, templates, scope, phases, gates, amendments |
+| [state-and-concurrency.md](https://github.com/rasensio/aidlc/blob/main/docs/state-and-concurrency.md) | State files, claims, the registry, worktrees |
+| [roadmap.md](https://github.com/rasensio/aidlc/blob/main/docs/roadmap.md) | Capture, triage, promote, and the GitHub Issues projection |
+| [reviews-and-guidance.md](https://github.com/rasensio/aidlc/blob/main/docs/reviews-and-guidance.md) | Adversarial review, guidance layers, context docs, the constitution |
+| [cost-tracking.md](https://github.com/rasensio/aidlc/blob/main/docs/cost-tracking.md) | What a feature cost, and how the number is attributed |
+| [metrics.md](https://github.com/rasensio/aidlc/blob/main/docs/metrics.md) | Change failure rate, lead times, true cost |
+| [knowledge-graph.md](https://github.com/rasensio/aidlc/blob/main/docs/knowledge-graph.md) | Persistent codebase memory for agents |
+| [skills-and-platforms.md](https://github.com/rasensio/aidlc/blob/main/docs/skills-and-platforms.md) | One canonical skill body, six platform packagings |
+| [hygiene-and-compliance.md](https://github.com/rasensio/aidlc/blob/main/docs/hygiene-and-compliance.md) | `aidlc doctor`, compliance packs |
+
+## Development
+
+**Prerequisites:** Node.js >= 22.13 (the CLI's knowledge graph uses the built-in `node:sqlite` module, unflagged since 22.13) and pnpm >= 9.
+
+```bash
+pnpm install
+pnpm build        # content first, then CLI + website in parallel
+pnpm test         # all tests, one package at a time (see note below)
+pnpm lint         # type-check all packages
+
+pnpm --filter @rasensio/aidlc-website dev    # work on the site locally
+```
+
+Tests use **vitest** (unit + integration) and **fast-check** (property-based testing):
+
+```bash
+pnpm --filter @rasensio/aidlc test
+pnpm --filter @rasensio/aidlc-content test
+pnpm --filter @rasensio/aidlc-website test
+```
+
+`pnpm test` is `pnpm -r --workspace-concurrency=1 test` — the packages run one at a
+time, deliberately. vitest already parallelises test files across workers, so a
+second axis of parallelism oversubscribes the CPU and pushes subprocess-spawning
+tests past their timeout. Measured on an idle machine: 263s for `packages/cli` with
+two 30-second timeouts when the packages run concurrently, against 71s and 75s for
+the whole workspace when they do not. Serialising is both faster and greener —
+please don't change it back.
+
+Every push to `main` and every pull request runs the same gate as a release —
+`pnpm build`, `pnpm lint`, `pnpm test` — via [`.github/workflows/ci.yml`](https://github.com/rasensio/aidlc/blob/main/.github/workflows/ci.yml).
+
+**One caution, learned the hard way:** during development invoke the workspace build,
+`node packages/cli/dist/cli.js`, never `npx aidlc`. `npx` prefers a globally installed
+binary, and it once reported "0 files updated, 35 unchanged" while the edited files sat
+changed on disk.
+
+<details>
+<summary><b>Project conventions & migration notes</b></summary>
+
+- TypeScript, ES modules, Node >= 22.13
+- Pure-function core (no I/O) with I/O pushed to edges
+- Pinned dependencies
+- Property-based tests for core logic
+- Content package uses `import.meta.url` for path resolution
+
+> **Migration note (v1.0):** the CLI previously ran on Node >= 18. The local
+> knowledge graph feature raised the floor to Node 22.13+ to use `node:sqlite`
+> with zero native dependencies. Users on Node 18/20 must upgrade their Node
+> runtime (e.g. `nvm install 22`); no other migration steps are required.
+
+</details>
+
+## Contributing
+
+Contributions welcome. Please open an issue first for significant changes.
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
 ## License
 
 [MIT](https://github.com/rasensio/aidlc/blob/main/LICENSE)
+
+---
+
+<div align="center">
+
+**[aidlc.rodrigoasensio.com](https://aidlc.rodrigoasensio.com)** — docs, tutorials, and the build log
+
+</div>

package/dist/commands/cost.d.ts

@@ -8,6 +8,7 @@
  * Design: design.md §1 (command surface)
  */
 import { Command } from 'commander';
+import type { CostDrivers, UnattributedSummary } from '../cost/report.js';
 /**
  * Token counts at the magnitude they actually occur: `245k`, `1.2M`.
  *
@@ -17,5 +18,8 @@ import { Command } from 'commander';
 export declare function fmtTokens(tokens: number): string;
 /** Human age of an ISO timestamp, for the capture-error note (AC-11). */
 export declare function fmtAge(timestamp: string, now?: Date): string;
+export declare function fmtDriverLine(d: CostDrivers): string | null;
+/** One whole-project line pricing the pool no instance owns (AC-8). */
+export declare function fmtUnattributedLine(u: UnattributedSummary): string;
 export declare function registerCost(program: Command): void;
 //# sourceMappingURL=cost.d.ts.map

package/dist/commands/cost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/commands/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0FpC;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CASxE;AAikBD,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiGnD"}
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/commands/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAgF1E;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CASxE;AA4LD,wBAAgB,aAAa,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAwB3D;AAgBD,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAMlE;AAoaD,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiGnD"}

package/dist/commands/cost.js

@@ -17,7 +17,7 @@ import { registerBuiltinProviders } from '../cost/providers/index.js';
 import { recordUsage, lastCaptureError, logCapture, captureLiveness } from '../cost/recorder.js';
 import { stashSession, unstashSession } from '../cost/sessions.js';
 import { appendEntry, ledgerPath } from '../cost/ledger.js';
-import { instanceCost, listInstances, byTemplate, unattributedEntries } from '../cost/report.js';
+import { instanceCost, listInstances, byTemplate, unattributedEntries, unattributedSummary } from '../cost/report.js';
 import { effectiveRates, updateRates, microToUsd, NORMALIZATION_RULES } from '../cost/rates.js';
 import { loadCostConfig, loadClaimTimeoutMinutes } from '../cost/config.js';
 import { resolvePin, skipReason, pinLabel } from '../cost/pin.js';
@@ -270,17 +270,98 @@ async function runSessionStart(opts) {
         logCapture(root, 'session-start', 'stash-failed');
     }
 }
+/*
+ * Where the money went, not just how much. `$578.45` alone gives a reader
+ * nothing to act on: on this project's ledger 59.6% of dollars is cache read —
+ * re-reading the conversation prefix, not producing anything — so the lever is
+ * context size, and that is invisible from a total.
+ *
+ * Every figure is a word or a number, never a colour or a bare symbol, so the
+ * line reads the same piped, in a monochrome terminal, and to a screen reader.
+ * `unmeasured` is printed rather than omitted: a missing figure and a zero one
+ * mean different things, which is the rule the rest of this report already
+ * follows.
+ */
+export function fmtDriverLine(d) {
+    if (d.responses === null && d.cacheReadShare === null)
+        return null;
+    const parts = [];
+    if (d.cacheReadShare !== null) {
+        parts.push(`context re-read: ${(d.cacheReadShare * 100).toFixed(1)}% of spend`);
+    }
+    // The same `~` the response count carries: the averages are derived from the
+    // counted subset, so when the count is a floor they are estimates over part of
+    // the ledger, not measurements of all of it (cost-driver-integrity/AC-2).
+    const approx = d.responsesPartial ? '~' : '';
+    if (d.avgContextTokens !== null) {
+        parts.push(`avg context: ${approx}${fmtTokens(d.avgContextTokens)}`);
+    }
+    if (d.microUsdPerResponse !== null) {
+        parts.push(`per response: ${approx}${microToUsd(d.microUsdPerResponse)}`);
+    }
+    if (d.responses !== null) {
+        // `~` marks a floor, matching how activePartial is already marked: some
+        // entries predate response counting, so the total understates the truth.
+        parts.push(`responses: ${d.responsesPartial ? '~' : ''}${d.responses}`);
+    }
+    else {
+        parts.push('responses: unmeasured');
+    }
+    return parts.join('  ');
+}
+/*
+ * The pool's headline figure, in the most honest unit available.
+ *
+ * Dollars when anything priced; otherwise tokens, or credits for a kiro-only
+ * pool; and `unmeasured` when there is no quantity of any kind — never the bare
+ * `0` that `fmtTokens(0)` would produce for entries that carry real usage.
+ */
+function fmtUnattributedTotal(u) {
+    if (u.microUsd !== null)
+        return microToUsd(u.microUsd);
+    if (u.tokens > 0)
+        return `${fmtTokens(u.tokens)} tok`;
+    if (u.credits > 0)
+        return `${u.credits} credits`;
+    return 'unmeasured';
+}
+/** One whole-project line pricing the pool no instance owns (AC-8). */
+export function fmtUnattributedLine(u) {
+    return (`unattributed: ${fmtUnattributedTotal(u)} across ${u.entries} entries` +
+        (u.unpricedModels.length > 0 ? ` (unpriced: ${u.unpricedModels.join(', ')})` : '') +
+        ' — `aidlc cost sync` attributes what claim windows cover');
+}
 function runReport(instance, opts) {
     const root = projectRoot();
     const config = loadCostConfig(root);
     if (opts.unattributed) {
-        const entries = unattributedEntries(root);
         if (opts.json) {
-            process.stdout.write(JSON.stringify(entries, null, 2) + '\n');
+            process.stdout.write(JSON.stringify(unattributedEntries(root), null, 2) + '\n');
+            return;
         }
-        else {
-            process.stdout.write(`${entries.length} unattributed entries\n`);
+        const u = unattributedSummary(root, config);
+        if (u === null) {
+            process.stdout.write('0 unattributed entries\n');
+            return;
+        }
+        // Dollars first: a count alone let ~44% of this repo's spend hide here
+        // (cost-driver-integrity/AC-9).
+        process.stdout.write(`${u.entries} unattributed entries  total: ${fmtUnattributedTotal(u)}` +
+            (u.unpricedModels.length > 0 ? `  (unpriced: ${u.unpricedModels.join(', ')})` : '') +
+            '\n');
+        const fid = Object.entries(u.fidelity)
+            .filter(([, n]) => n > 0)
+            .map(([k, n]) => `${k} ${n}`)
+            .join(', ');
+        process.stdout.write(`  fidelity: ${fid}\n`);
+        for (const [model, tokens] of Object.entries(u.modelTokens).sort((a, b) => b[1] - a[1])) {
+            process.stdout.write(`  ${model.padEnd(24)} ${fmtTokens(tokens)} tok (raw)\n`);
+        }
+        // Credits are a separate unit and are never printed as tokens.
+        for (const [model, credits] of Object.entries(u.modelCredits).sort((a, b) => b[1] - a[1])) {
+            process.stdout.write(`  ${model.padEnd(24)} ${credits} credits (raw)\n`);
         }
+        process.stdout.write('  `aidlc cost sync` attributes what claim windows cover\n');
         return;
     }
     if (opts.byTemplate) {
@@ -355,30 +436,22 @@ function runReport(instance, opts) {
          * mean different things, which is the rule the rest of this report already
          * follows.
          */
-        const d = c.drivers;
-        if (d.responses !== null || d.cacheReadShare !== null) {
-            const parts = [];
-            if (d.cacheReadShare !== null) {
-                parts.push(`context re-read: ${(d.cacheReadShare * 100).toFixed(1)}% of spend`);
-            }
-            if (d.avgContextTokens !== null) {
-                parts.push(`avg context: ${fmtTokens(d.avgContextTokens)}`);
-            }
-            if (d.microUsdPerResponse !== null) {
-                parts.push(`per response: ${microToUsd(d.microUsdPerResponse)}`);
-            }
-            if (d.responses !== null) {
-                // `~` marks a floor, matching how activePartial is already marked: some
-                // entries predate response counting, so the total understates the truth.
-                parts.push(`responses: ${d.responsesPartial ? '~' : ''}${d.responses}`);
-            }
-            else {
-                parts.push('responses: unmeasured');
-            }
-            process.stdout.write(`  ${parts.join('  ')}\n`);
+        const driverLine = fmtDriverLine(c.drivers);
+        if (driverLine !== null) {
+            process.stdout.write(`  ${driverLine}\n`);
         }
         process.stdout.write(`  rates: ${c.snapshot}\n`);
     }
+    // The pool of spend no instance owns, priced — on this repo it was ~44% of the
+    // total while the report said nothing. Whole-project view only: beside a single
+    // instance it would read as that instance's number (AC-8). Empty pool prints
+    // nothing — silence, never `$0.00` (AC-10).
+    if (instance === undefined) {
+        const u = unattributedSummary(root, config);
+        if (u !== null) {
+            process.stdout.write(`${fmtUnattributedLine(u)}\n`);
+        }
+    }
     const err = lastCaptureError(root);
     if (err) {
         process.stderr.write(`note: last capture error ${err.error_code} at ${err.stage} (${fmtAge(err.timestamp)}) — see .aidlc/cost/capture.log\n`);