@rasensio/aidlc 1.27.0 → 1.27.2

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/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/commands/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8DpC;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqDvD"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/commands/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4EpC;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8EvD"}

package/dist/commands/discover.js

@@ -19,13 +19,14 @@ import { Command } from 'commander';
 import { scanCodebase, writeContextDocs } from '../discover/scanner.js';
 import { seedFromScan } from '../knowledge/seed.js';
 import { openKnowledge } from '../knowledge/engine.js';
+import { defaultPrompter } from '../core/prompt.js';
 // ---------------------------------------------------------------------------
 // Summary renderer
 // ---------------------------------------------------------------------------
 /**
  * Format a human-readable summary from the scan result.
  */
-function formatSummary(result, docPaths, preserved = []) {
+function formatSummary(result, docPaths, preserved = [], declined = []) {
     const lines = [];
     // Languages
     if (result.languages.length > 0) {
@@ -64,6 +65,12 @@ function formatSummary(result, docPaths, preserved = []) {
         // the same from the outside.
         lines.push(`Kept hand-written: ${preserved.join(', ')} (use --force to regenerate)`);
     }
+    if (declined.length > 0) {
+        // `--force` was asked for and refused. Saying so is the point: a silent
+        // preserve here would read as the flag having worked.
+        lines.push(`Refused to overwrite: ${declined.join(', ')} — --force was declined, ` +
+            'so these hand-written docs were left as they are');
+    }
     return lines.join('\n') + '\n';
 }
 // ---------------------------------------------------------------------------
@@ -79,7 +86,7 @@ export function registerDiscover(program) {
         .option('--json', 'Output full scan result as JSON')
         .option('--no-knowledge', 'Skip seeding the knowledge graph')
         .option('--force', 'Overwrite hand-edited context docs as well as generated ones')
-        .action((opts) => {
+        .action(async (opts) => {
         // `process.cwd()` deliberately, NOT resolveProjectRoot() — a documented
         // exemption (cwd-project-root/AC-16), asserted by
         // test/project-root-call-sites.test.ts.
@@ -92,8 +99,23 @@ export function registerDiscover(program) {
         // Run the scanner
         const result = scanCodebase(cwd);
         // Write Context_Docs
-        const { written: docPaths, preserved } = writeContextDocs(cwd, result, {
+        const { written: docPaths, preserved, declined } = await writeContextDocs(cwd, result, {
             force: opts.force === true,
+            // Only reached when --force would destroy a hand-owned doc. `defaultPrompter`
+            // is the single clack seam; its `no-tty` miss and an explicit cancel both
+            // mean no, matching doctor/runner.ts. That gives AC-13's non-interactive
+            // refusal without a separate TTY check here.
+            confirmOverwrite: async (paths) => {
+                process.stdout.write(`--force would overwrite ${paths.length} hand-written context doc(s):\n`);
+                for (const p of paths)
+                    process.stdout.write(`  ${p}\n`);
+                process.stdout.write('Their text exists nowhere but git history — regenerating cannot produce it again.\n');
+                const answer = await defaultPrompter.confirm({
+                    message: 'Overwrite them with generated content?',
+                    initialValue: false,
+                });
+                return answer.ok && answer.value;
+            },
         });
         // Seed the knowledge graph (KG Req 8.1)
         let knowledgeSummary = '';
@@ -119,9 +141,15 @@ export function registerDiscover(program) {
             process.stdout.write(JSON.stringify(result, null, 2) + '\n');
         }
         else {
-            const summary = formatSummary(result, docPaths, preserved);
+            const summary = formatSummary(result, docPaths, preserved, declined);
             process.stdout.write(summary + knowledgeSummary);
         }
+        // A declined --force is a request that did not happen. Exiting non-zero is
+        // what makes a scripted `aidlc discover --force` fail loudly instead of
+        // reporting success over docs it never touched (AC-13).
+        if (declined.length > 0) {
+            process.exitCode = 1;
+        }
     });
 }
 //# sourceMappingURL=discover.js.map

package/dist/commands/discover.js.map

@@ -1 +1 @@
-{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/commands/discover.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/commands/discover.ts"],"names":[],"mappings":"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"}

package/dist/commands/doctor.js

@@ -91,7 +91,11 @@ function report(result, dryRun) {
         process.stdout.write('Doctor: everything healthy — nothing to do.\n');
     }
     else if (dryRun) {
-        process.stdout.write('No changes were made (--dry-run).\n');
+        // Scoped to doctor by name. `aidlc update` runs this pass and then prints its
+        // own end-of-run line, so the unqualified sentence appeared twice in one
+        // invocation and read as a bug rather than as two true statements about two
+        // scopes (update-overwrites-authored-context/AC-6).
+        process.stdout.write('Doctor: no changes were made (--dry-run).\n');
     }
 }
 function printCommands(o) {

package/dist/commands/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}