contract-driven-delivery 1.10.0 → 1.12.0

package/README.md

@@ -1,96 +1,479 @@
 # Contract-Driven Delivery Kit
 
-A reusable Claude Code development kit for brownfield full-stack systems that need specification-driven development, test-driven development, strict contracts, CI/CD gates, visual review, E2E, resilience, fuzz/monkey, stress, and soak testing.
+**cdd-kit** is a contract-driven delivery kit for AI coding agents. It started with Claude Code skills and now keeps the core workflow provider-neutral: contracts-first, test-first, spec-first. Every change goes through classification, contract review, TDD, implementation, and gate verification.
 
-This kit is designed for internal production systems such as dashboards, reporting systems, workflow tools, and data-heavy web apps. It is repo-informed but repo-agnostic: install it once, deploy it into any repository, and apply the same delivery discipline without repeating instructions every time.
+Designed for solo developers and small teams building brownfield production systems (dashboards, APIs, workflow tools, data apps) who want AI to do all the implementation while they stay in the spec-author and reviewer seat.
 
-## Install via npm
+**Context Governance v1** adds a manifest-driven audit layer for AI agents. New changes include `context-manifest.md`, `agent-log` entries are expected to report `files-read`, and `cdd-kit gate` audits those reads against allowed and forbidden paths. This is governance and review support, not a sandbox.
+
+---
+
+## Install
 
 ```bash
 npm install -g contract-driven-delivery
 ```
 
-Requires Node.js 18+ and Python 3.8+.
+Requires **Node.js 18+** and **Python 3.8+** (for contract validators).
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install globally
+npm install -g contract-driven-delivery
+
+# 2. Go to your repo
+cd your-repo
+
+# 3. Deploy the kit
+cdd-kit init
+
+# 4. Open Claude Code in your repo and tell Claude:
+# "Use /cdd-new to set up the project. My system is a <brief description>."
+```
+
+---
+
+## How to Direct Claude Code
+
+> All workflows are started by typing a **natural language instruction** to Claude Code in your IDE or terminal. The `/cdd-*` prefixed commands are Claude Code skills — not shell commands.
+
+### Starting a new project (first time)
+
+After `cdd-kit init`, open Claude Code and say:
+
+```
+Scan this repo and create a project profile. Tell me what contracts are
+missing and what the minimum setup should be before we start any feature work.
+```
+
+Claude will:
+1. Run `cdd-kit detect-stack` to detect the tech stack
+2. Read your existing code structure
+3. Create `specs/project-profile.md`
+4. Identify gaps in `contracts/` and recommend filling order
+
+Then fill your contracts in this order (Claude can help draft them):
+
+| Contract | File | What it captures |
+|---|---|---|
+| Env | `contracts/env/env-contract.md` | Every env var, secret flag, default, validation |
+| API | `contracts/api/api-contract.md` | Every endpoint: method, path, auth, schemas, errors |
+| Data | `contracts/data/data-shape-contract.md` | Schemas, types, nullability, bad-data behavior |
+| CSS/UI | `contracts/css/css-contract.md` | Design tokens, component states, forbidden raw values |
+| Business | `contracts/business/business-rules.md` | Rules, edge cases, decision tables |
+| CI/CD | `contracts/ci/ci-gate-contract.md` | Gate tiers, promotion policy, rollback policy |
+
+---
+
+### Starting a new task / feature / bug fix
+
+Type this in Claude Code:
+
+```
+/cdd-new add JWT authentication to the API
+```
+
+or
+
+```
+/cdd-new redesign the user dashboard to show real-time metrics
+```
+
+or
+
+```
+/cdd-new fix the order export timeout when result set exceeds 10 000 rows
+```
+
+**What happens:**
+1. Claude generates a `change-id` (e.g. `add-jwt-auth`) and scaffolds `specs/changes/add-jwt-auth/`
+2. The `change-classifier` agent (Opus) reads the request, classifies risk and tier, decides which agents are needed
+3. Agents run in order: contracts → test plan → spec/architecture review (if needed) → backend engineer → frontend engineer → CI/CD gates → QA
+4. Each agent produces machine-verifiable evidence (agent-log files)
+5. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
+6. Claude reports a summary and the suggested git commit
+
+**You stay in control by:**
+- Reviewing the `change-classification.md` before implementation starts
+- Checking the `test-plan.md` to confirm the right test families are planned
+- Reading the final `agent-log/qa-reviewer.md` for the release-readiness verdict
+
+---
+
+### Updating architecture or contracts
+
+```
+/cdd-new update the API contract to add pagination to all list endpoints
+```
+
+```
+/cdd-new migrate the database from MySQL to PostgreSQL
+```
+
+```
+/cdd-new add Redis caching layer to the reporting queries
+```
+
+The change-classifier will detect that these are architectural or contract-level changes, assign a higher risk tier (0–2), and automatically require:
+- Architecture review (`spec-architect` agent)
+- E2E, resilience, stress, and monkey tests
+- Updated contracts before any implementation begins
+
+---
+
+### Resuming an interrupted task
+
+If a session was cut off or you need to return to an in-progress change:
+
+```
+/cdd-resume add-jwt-auth
+```
+
+or, if you're unsure of the change-id:
+
+```
+What changes are currently in progress? (cdd-kit list)
+```
+
+**What happens:**
+1. Claude reads `tasks.md` and `agent-log/` to determine what was completed
+2. Reports the current state (which agents ran, which tasks are pending)
+3. Asks if you want to continue from the next pending agent
+4. Resumes the full agent flow from where it stopped, with no duplication
+
+> If you're upgrading from an older version and your change was created before v1.11.0, Claude will automatically run `cdd-kit migrate <change-id>` to upgrade the format before resuming.
+
+---
+
+### Closing a completed change
+
+After the PR is merged:
+
+```
+/cdd-close add-jwt-auth
+```
+
+**What happens:**
+1. Runs `cdd-kit gate` to confirm the change still passes
+2. Synthesizes `archive.md` — a permanent record of what changed, what tests were added, and what lessons were found
+3. Invokes `contract-reviewer` to propose any durable learnings back into `contracts/`
+4. Runs `cdd-kit archive add-jwt-auth` — moves the change from `specs/changes/` to `specs/archive/2026/`
+5. Reduces the active context that future Claude sessions need to load
+
+---
+
+### Abandoning a change
+
+If you decide not to proceed with a change:
+
+```
+/cdd-close add-jwt-auth
+```
+
+Then when Claude asks for confirmation, say "abandon it." Claude will run:
+
+```bash
+cdd-kit abandon add-jwt-auth --reason "decided to use a third-party auth service instead"
+```
+
+The directory stays on disk for git history, but `cdd-kit list` will show it as `abandoned`.
+
+---
+
+### Checking the status of all active changes
+
+Type to Claude:
+
+```
+What changes are currently in progress?
+```
+
+Claude will run `cdd-kit list`, which shows:
+
+```
+Active changes:
+  add-jwt-auth       [in-progress]  (3 pending)
+  fix-export-timeout [gate-blocked]
+  redesign-dashboard [in-progress]  (12 pending)
+```
+
+---
+
+## CLI Reference
 
-## CLI Usage
+These are shell commands — not Claude Code skills. Run them directly in the terminal, or Claude Code will run them on your behalf.
 
 ### `cdd-kit init`
 
-Installs Claude Code agents and the `contract-driven-delivery` skill into `~/.claude`, and scaffolds project files (`contracts/`, `specs/templates/`, `tests/templates/`, `ci/`, `CLAUDE.md`, `AGENTS.md`) into the current repository.
+Installs agents and skill into `~/.claude` and scaffolds project files.
 
 ```bash
-cdd-kit init                  # global + local (recommended for first-time setup)
-cdd-kit init --global-only    # only install agents/skill into ~/.claude
-cdd-kit init --local-only     # only scaffold project files in current repo
-cdd-kit init --force          # overwrite existing project files (CLAUDE.md is never overwritten)
+cdd-kit init                  # global + local (recommended)
+cdd-kit init --global-only    # only install into ~/.claude
+cdd-kit init --local-only     # only scaffold project files
+cdd-kit init --provider codex # scaffold Codex-oriented project guidance
+cdd-kit init --provider both  # scaffold Claude Code + Codex guidance
+cdd-kit init --force          # overwrite existing project files
 ```
 
+Creates: `contracts/`, `specs/templates/`, provider guidance files (`CLAUDE.md`, `AGENTS.md`, and/or `CODEX.md`), `hooks/`
+
+---
+
 ### `cdd-kit update`
 
-Updates the agents and skill in `~/.claude` to the latest installed version. Does not touch project-level files like `contracts/` or `CLAUDE.md`.
+Updates provider assets to the latest installed version. By default, `update` reads `.cdd/model-policy.json` and updates only the matching provider adapter. It does not overwrite project guidance files such as `CLAUDE.md`, `AGENTS.md`, or `CODEX.md`.
 
 ```bash
 cdd-kit update
+cdd-kit update --yes          # apply without confirmation
+cdd-kit update --provider codex
+cdd-kit update --provider both
 ```
 
-### `cdd-kit new <name>`
+Codex currently has no global assets to update, so Codex-only projects report that they are already up to date. Run `cdd-kit init --local-only --provider codex` if a project is missing `CODEX.md`.
 
-Creates a new change scaffold under `specs/changes/<name>/` with the required template files.
+---
+
+### `cdd-kit doctor`
+
+Inspects repo-level cdd-kit health without writing files.
 
 ```bash
-cdd-kit new add-user-auth             # required templates only
-cdd-kit new add-user-auth --all       # include all optional templates
-cdd-kit new add-user-auth --force     # re-scaffold even if directory already exists
+cdd-kit doctor
+cdd-kit doctor --strict
+cdd-kit doctor --json
+cdd-kit doctor --provider codex
 ```
 
-Required templates: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`
+Checks for missing `.cdd/` policy files, provider guidance (`CLAUDE.md`, `AGENTS.md`, `CODEX.md`), context indexes, stale `specs/context/*` outputs, and contract summary metadata gaps. `--strict` treats warnings as errors. `--json` emits a machine-readable report for CI or wrapper scripts.
 
-Optional templates (with `--all`): `current-behavior.md`, `proposal.md`, `spec.md`, `design.md`, `contracts.md`, `qa-report.md`, `regression-report.md`, `archive.md`
+---
 
-### `cdd-kit validate`
+### `cdd-kit upgrade`
 
-Runs contract validation scripts against the current repository.
+Adds missing repo-level cdd-kit files after upgrading the npm package. It preserves existing contracts and guidance files; default mode is a dry run.
 
 ```bash
-cdd-kit validate                # run all validators
-cdd-kit validate --contracts    # validate API/data/CSS contracts + semantic validators
-cdd-kit validate --env          # validate env contract
-cdd-kit validate --ci           # validate CI gate policy
-cdd-kit validate --spec         # validate spec traceability
+cdd-kit upgrade
+cdd-kit upgrade --yes
+cdd-kit upgrade --yes --migrate-changes
+cdd-kit upgrade --yes --migrate-changes --enable-context-governance
+cdd-kit upgrade --provider codex --yes
+cdd-kit upgrade --provider both --yes
 ```
 
-`--contracts` also chains two semantic validators:
-- **API semantic**: checks endpoint table for valid HTTP methods, paths starting with `/`, and valid auth values.
-- **Env semantic**: checks variable table for secrets with default values (forbidden), and warns on required non-secret vars with no default.
+Use this for old repos that already have `contracts/` or `specs/` but are missing new assets such as `.cdd/context-policy.json`, `.cdd/model-policy.json`, `CODEX.md`, or newer templates. Add `--migrate-changes` if you also want to upgrade existing `specs/changes/<change-id>/` directories in the same run.
+
+---
 
 ### `cdd-kit gate <change-id>`
 
-Validates that a change has completed the full orchestration workflow before it can be committed or shipped. Checks: directory exists, all 5 required artifacts are present, each has > 100 meaningful characters (not a stub), `change-classification.md` contains a tier or risk marker, and all contract validators pass.
+The single quality gate for a change. Blocks merge if anything is missing or incomplete.
 
 ```bash
-cdd-kit gate add-user-auth
-# ✓  gate passed for change: add-user-auth
+cdd-kit gate add-jwt-auth
+cdd-kit gate add-jwt-auth --strict
 ```
 
-Failure examples:
+Checks:
+- All required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`; new context-governed changes also require `context-manifest.md`)
+- Each artifact has sufficient content (not a stub): change-classification ≥ 200 chars, test-plan ≥ 200, ci-gates ≥ 150, others ≥ 100
+- `change-classification.md` contains a tier or risk marker
+- `agent-log/*.md` files all have `status: complete` (not blocked)
+- For context-governed changes, `agent-log/*.md` files include a structured `- files-read:` list and those repo-relative paths are audited against `context-manifest.md` and `.cdd/context-policy.json`
+- Atomic `depends-on` upstream changes are completed or archived before dependent work gates
+- Tier 0–1 changes have `e2e-resilience-engineer`, `monkey-test-engineer`, and `stress-soak-engineer` logs
+- Tier 0–3 changes have `contract-reviewer` and `qa-reviewer` logs
+- All contract validators pass
+
+`--strict` additionally:
+- Treats any pending `[ ]` tasks (except section 7 archive items) as errors
+- Validates that every file path listed in `agent-log` artifact pointers actually exists on disk
+- Treats legacy changes missing `context-manifest.md` or `files-read` audit data as errors
+
+Pre-commit hook uses `--strict` by default (installed via `cdd-kit install-hooks`).
+
 ```
+✓  gate passed for change: add-jwt-auth
+
 ✗  gate failed for change: feat-001
-✗    missing required artifact: tasks.md
-✗    change-classification.md: missing tier/risk marker (Tier 0-5 or low/medium/high/critical)
+✗    change-classification.md: appears to be a stub (< 200 meaningful chars)
+✗    Tier 1 change requires agent-log/e2e-resilience-engineer.md
+✗    1 task(s) still pending (use [-] for N/A items, [x] for done)
+```
+
+---
+
+### `cdd-kit list`
+
+Lists all active changes in `specs/changes/` with status and pending task count.
+
+```bash
+cdd-kit list
+```
+
+```
+Active changes:
+  add-jwt-auth       [in-progress]  (3 pending)
+  fix-export-timeout [gate-blocked]
+  old-experiment     [abandoned]
+```
+
+---
+
+### `cdd-kit archive <change-id>`
+
+Physically moves a completed change from `specs/changes/` to `specs/archive/<year>/`.
+
+```bash
+cdd-kit archive add-jwt-auth
+# ✓  Archived: specs/changes/add-jwt-auth → specs/archive/2026/add-jwt-auth
+# ✓  Index updated: specs/archive/INDEX.md
+```
+
+Warns (but does not block) if `tasks.md` has pending items or `status: gate-blocked`. Use after `/cdd-close` — the skill runs this automatically at the end.
+
+---
+
+### `cdd-kit abandon <change-id>`
+
+Marks a change as abandoned. Updates `tasks.md` status to `abandoned`, records the reason in `specs/archive/INDEX.md`. The directory stays on disk for git history.
+
+```bash
+cdd-kit abandon add-jwt-auth --reason "using Auth0 instead"
+# ✓  Change add-jwt-auth marked as abandoned.
+```
+
+---
+
+### `cdd-kit migrate <change-id> | --all`
+
+Upgrades pre-v1.11.0 change directories to the current format.
+
+```bash
+cdd-kit migrate add-jwt-auth        # migrate one change
+cdd-kit migrate --all               # migrate all changes in specs/changes/
+cdd-kit migrate --all --dry-run     # preview without writing
+cdd-kit migrate --all --enable-context-governance
+```
+
+What it upgrades:
+- `tasks.md`: adds YAML frontmatter (`change-id`, `status: in-progress`) and `[x]/[-]/[ ]` legend if missing
+- `change-classification.md`: detects old `**Tier:** Tier N` format and appends the new `## Tier\n- N` section so tier-based gate checks activate
+- `context-manifest.md`: adds a legacy manifest scaffold by default so old changes can continue with warning-only context audit behavior
+- `--enable-context-governance`: explicitly adds `context-governance: v1` and a context-governed manifest scaffold, making missing manifest or malformed `files-read` data hard gate failures
+
+`agent-log/*.md` must use this `files-read` format for context-governed changes:
+
+```md
+- files-read:
+  - contracts/api/api-contract.md
+  - src/server/routes/users.ts
+```
+
+Paths must be repo-relative. Absolute paths and `..` parent traversal are rejected.
+
+Run this after upgrading from v1.10 or earlier if you have mid-flight changes.
+
+```bash
+cdd-kit migrate --all
+git add specs/changes/
+git commit -m "chore: migrate changes to current cdd-kit format"
+```
+
+---
+
+### `cdd-kit context request <change-id> <request-id>`
+
+Records a pending Context Expansion Request in `context-manifest.md`.
+
+```bash
+cdd-kit context request add-jwt-auth CER-001 --path src/server/users.ts tests/users.test.ts --reason "paired implementation and regression coverage"
+```
+
+Use this when an agent needs more context than its current work packet allows.
+
+---
+
+### `cdd-kit context approve <change-id> <request-id>`
+
+Approves a pending Context Expansion Request in `context-manifest.md` and adds its `requested_paths` to `## Approved Expansions`.
+
+```bash
+cdd-kit context approve add-jwt-auth CER-001
 ```
 
+This keeps expansion history explicit while avoiding manual manifest editing. Agents still have to report `files-read` in `agent-log/*.md`; `cdd-kit gate` audits those paths against the manifest.
+
+---
+
+### `cdd-kit context reject <change-id> <request-id>`
+
+Rejects a pending Context Expansion Request and records `status: rejected` in the manifest.
+
+```bash
+cdd-kit context reject add-jwt-auth CER-001
+```
+
+---
+
+### `cdd-kit context list <change-id>`
+
+Lists all Context Expansion Requests for a change.
+
+```bash
+cdd-kit context list add-jwt-auth
+cdd-kit context list add-jwt-auth --json
+```
+
+---
+
+### `cdd-kit validate`
+
+Runs contract validation scripts.
+
+```bash
+cdd-kit validate                # all validators
+cdd-kit validate --contracts    # API, CSS, data-shape (+ semantic checks)
+cdd-kit validate --env          # env contract
+cdd-kit validate --ci           # CI gate policy
+cdd-kit validate --spec         # spec traceability
+cdd-kit validate --versions     # contract frontmatter schema versions
+```
+
+---
+
+### `cdd-kit new <name>`
+
+Scaffolds an empty change directory. Normally you use `/cdd-new` (the Claude Code skill) instead, which runs this and then orchestrates all agents. Use `cdd-kit new` only if you want an empty scaffold without agent orchestration.
+
+```bash
+cdd-kit new add-user-auth
+cdd-kit new add-user-auth --all     # include optional templates too
+cdd-kit new add-user-auth --force   # overwrite existing directory
+cdd-kit new add-user-api --depends-on add-user-db
+```
+
+For larger requests, split the work into atomic changes on the same feature branch and use `--depends-on` to record upstream order. `cdd-kit gate` blocks a dependent change until each upstream change is either archived or has `status: completed` in its `tasks.md` frontmatter.
+
+---
+
 ### `cdd-kit install-hooks`
 
-Installs a pre-commit Git hook that automatically runs `cdd-kit gate` for any change folder touched in the staged commit. Prevents skipping the orchestration workflow.
+Installs a pre-commit Git hook that auto-runs `cdd-kit gate --strict` on any staged change directory.
 
 ```bash
 cdd-kit install-hooks
 # ✓  pre-commit hook installed at .git/hooks/pre-commit
 ```
 
-- Idempotent: re-running updates the cdd-kit block in place without duplicating it.
-- Preserves existing hook content: if a pre-commit hook already exists, the cdd-kit block is prepended after the shebang line.
-- Bypass with `--no-verify` (not recommended; defeats AI process enforcement).
+Idempotent. Preserves existing hook content. Bypass with `--no-verify` is possible but defeats enforcement.
+
+---
 
 ### `cdd-kit detect-stack`
 
@@ -99,139 +482,153 @@ Detects the project tech stack from lockfiles and config files.
 ```bash
 cdd-kit detect-stack
 # Detected stack: conda
-# Candidates (in order): conda, pnpm
 # Polyglot: yes (config will be generated for conda)
 ```
 
-## Supported stacks (stack detection)
+| Language | Tool | Detection signal |
+|---|---|---|
+| Python | conda | `environment.yml`, `conda-lock.yml` |
+| Python | poetry | `pyproject.toml` with `[tool.poetry]` |
+| Python | uv | `pyproject.toml` (no poetry section) |
+| Python | pip | `requirements.txt` |
+| JS/TS | pnpm | `pnpm-lock.yaml` |
+| JS/TS | bun | `bun.lockb` |
+| JS/TS | yarn | `yarn.lock` |
+| JS/TS | npm | `package.json` (fallback) |
+| Go | go | `go.mod` |
+| Rust | rust | `Cargo.toml` |
 
-| Language   | Tool    | Detection signal                             |
-|------------|---------|----------------------------------------------|
-| Python     | conda   | `environment.yml`, `conda-lock.yml`, `meta.yaml` |
-| Python     | poetry  | `pyproject.toml` with `[tool.poetry]`        |
-| Python     | uv      | `pyproject.toml` (no poetry section)         |
-| Python     | pip     | `requirements.txt`                           |
-| JavaScript | pnpm    | `package.json` + `pnpm-lock.yaml`            |
-| JavaScript | bun     | `package.json` + `bun.lockb`                 |
-| JavaScript | yarn    | `package.json` + `yarn.lock`                 |
-| JavaScript | npm     | `package.json` (no lockfile match)           |
-| Go         | go      | `go.mod`                                     |
-| Rust       | rust    | `Cargo.toml`                                 |
+---
 
-When multiple language families are detected (polyglot project), `cdd-kit init` generates CI config for the first detected stack and prints a warning.
+### `cdd-kit context-scan`
 
-## First-time setup in a repository
+Builds deterministic, low-token context indexes for classifiers and orchestrators.
 
 ```bash
-# 1. Install the CLI globally
-npm install -g contract-driven-delivery
+cdd-kit context-scan
+```
 
-# 2. Navigate to your repository
-cd your-repo
+Outputs:
+- `specs/context/project-map.md`: ASCII directory tree with schema metadata, visible file/dir counts, and excluded paths from `.cdd/context-policy.json`
+- `specs/context/contracts-index.md`: contract inventory table plus deterministic details from YAML frontmatter or `<!-- cdd: ... -->` metadata
 
-# 3. Deploy the kit
-cdd-kit init
+Recommended contract metadata:
 
-# 4. Open Claude Code and run the workflow
-# Ask Claude Code: "Use the contract-driven-delivery workflow.
-# Scan this repo, create a project profile, identify missing contracts,
-# and recommend the minimum standardization changes before feature work."
+```yaml
+---
+contract: api
+summary: User API endpoint rules and compatibility policy.
+owner: backend-team
+surface: user-management
+---
 ```
 
-## What to expect after `cdd-kit init`
+The classifier should read these two files before proposing `context-manifest.md` allowed paths.
+
+---
 
-The first `cdd-kit validate` after `init` is expected to print contract placeholder warnings — six contract files are scaffolded but empty. Validation still exits 0; warnings are advisory.
+## Migrating an Older Production Repo
 
-```text
-Warning: contracts present but appear empty: contracts/api/api-contract.md, ...
-Fill them in before relying on the gate.
+```bash
+npm update -g contract-driven-delivery
+cdd-kit upgrade --yes
+cdd-kit context-scan
+cdd-kit doctor --strict
 ```
 
-To turn warnings off, fill each contract with real content (typical user-filled contracts run 500+ characters of meaningful text, well above the placeholder threshold). Recommended filling order:
+### Old completed specs
+
+If a change is already finished, merged, or only kept for audit/history:
 
-1. `contracts/env/env-contract.md` — list every env var your app reads, with `secret`, `default`, `validation` columns.
-2. `contracts/api/api-contract.md` — inventory every endpoint with method, path, request/response shape, and error format.
-3. `contracts/data/data-shape-contract.md` — required columns, types, nullability, and malformed-data behavior for each data surface.
-4. `contracts/css/css-contract.md` — design tokens, component states, and forbidden raw values.
-5. `contracts/business/business-rules.md` — current rules, decision tables, edge cases.
-6. `contracts/ci/ci-gate-contract.md` — gate tiers, promotion policy, rollback policy.
+```bash
+cdd-kit migrate --all
+git add specs/changes/
+git commit -m "chore: migrate changes to current cdd-kit format"
+```
 
-`cdd-kit validate --contracts` re-runs only the contract check; use it incrementally as you fill each file.
+This gives those legacy specs the new `tasks.md` frontmatter, tier markers, and a warning-mode `context-manifest.md` without forcing strict context governance on closed work.
 
-## What this kit standardizes
+### Old in-progress specs
 
-- Change classification before implementation
-- SDD artifacts for every meaningful change
-- TDD and test-first handoff rules
-- API, CSS/UI, environment, data-shape, business-rule, and CI/CD contracts
-- Required CI/CD gate planning for every change
-- E2E, resilience, data-boundary, monkey-operation, stress, and soak testing
-- Visual and UI/UX review for frontend changes
-- Spec drift audits across multiple iterations
-- Archiving completed changes back into durable standards
+If a change is still being actively developed:
 
-## Core workflow
+```bash
+cdd-kit upgrade --yes --migrate-changes
+cdd-kit context-scan
+cdd-kit doctor --strict
+```
 
-1. Classify the change.
-2. Scan the repository context.
-3. Decide the required artifact path.
-4. Write or update specs, contracts, tests, and CI gate plan before implementation.
-5. Implement through the right engineer agents.
-6. Run local and CI gates.
-7. Run visual, E2E, resilience, stress, soak, or monkey testing as required.
-8. Archive stable learnings back into contracts and standards.
+Then choose one path per active change:
 
-## Change folder structure
+- Conservative path: keep the migrated legacy manifest, resume work, and let `gate` warn on missing `files-read` data while the team transitions.
+- Strict path: run `cdd-kit migrate <change-id> --enable-context-governance`, review `context-manifest.md`, narrow `Allowed Paths`, and require agents to report `- files-read:` before continuing implementation.
 
-```text
-specs/changes/<change-id>/
-├── change-request.md        (required)
-├── change-classification.md (required)
-├── test-plan.md             (required)
-├── ci-gates.md              (required)
-├── tasks.md                 (required)
-├── current-behavior.md
-├── proposal.md
-├── spec.md
-├── design.md
-├── contracts.md
-├── qa-report.md
-├── regression-report.md
-└── archive.md
-```
+### Recommended rollout for production repos already burned by token overuse
 
-## Definition of done
+1. Run `cdd-kit upgrade --yes` once per repo after updating the npm package.
+2. Run `cdd-kit context-scan` so classifiers can read `specs/context/project-map.md` and `specs/context/contracts-index.md` instead of broad repo searches.
+3. Run `cdd-kit doctor --strict` in CI.
+4. Migrate old completed specs with plain `cdd-kit migrate`.
+5. Migrate active specs with `cdd-kit migrate --enable-context-governance` only after reviewing the generated manifest.
+6. Teach agents to use `cdd-kit context request/approve/reject/list` instead of silently widening context.
 
-A change is not done until:
+---
 
-- Required specs and contracts are updated.
-- Required tests exist and are mapped to acceptance criteria.
-- Required CI/CD gates are present and green or explicitly marked as informational with promotion policy.
-- UI changes have visual evidence.
-- Data/reporting changes have data-boundary and bad-shape coverage.
-- High-load or long-running features have stress or soak evidence.
-- The archive captures what should become durable project knowledge.
+## Directory structure after `cdd-kit init`
 
-## Stress / Soak runner support
+```
+your-repo/
+├── contracts/
+│   ├── api/api-contract.md          ← what endpoints exist and how they behave
+│   ├── css/css-contract.md          ← design tokens, component states
+│   ├── data/data-shape-contract.md  ← schemas, types, nullability
+│   ├── env/env-contract.md          ← every env var, secret flags, defaults
+│   ├── business/business-rules.md   ← rules, edge cases, decision tables
+│   └── ci/ci-gate-contract.md       ← gate tiers, promotion, rollback
+├── specs/
+│   ├── project-profile.md           ← overall system description
+│   ├── changes/                     ← active in-progress changes
+│   │   └── <change-id>/
+│   │       ├── change-request.md    (required)
+│   │       ├── change-classification.md (required)
+│   │       ├── test-plan.md         (required)
+│   │       ├── ci-gates.md          (required)
+│   │       ├── tasks.md             (required)
+│   │       └── agent-log/           ← machine-verifiable evidence per agent
+│   ├── archive/                     ← completed and abandoned changes
+│   │   ├── INDEX.md
+│   │   └── 2026/<change-id>/
+│   └── templates/
+├── tests/
+├── CLAUDE.md                        ← Claude's project guide (edit this)
+├── AGENTS.md                        ← agent roster (auto-managed)
+└── CODEX.md                         ← Codex project guide when initialized for Codex
+```
 
-cdd-kit ships starter configs for three load runners. Pick one
-when filling out `tests/<change-id>/stress-test-plan.md`:
+---
 
-| runner | best for | example |
-|--------|----------|---------|
-| k6 | JS-friendly, scriptable scenarios, native thresholds | tests/templates/stress/k6-example.js |
-| locust | Python teams, complex stateful scenarios | tests/templates/stress/locust-example.py |
-| artillery | declarative YAML, quick http flows | tests/templates/stress/artillery-example.yml |
+## Risk tiers and what each triggers
 
-Soak templates live under `tests/templates/soak/`.
+| Tier | Risk level | Example changes | Extra agents |
+|---|---|---|---|
+| 0–1 | High / critical | Auth, payments, migrations, concurrency | E2E + monkey + stress/soak |
+| 2–3 | Medium | Feature with API change, bug fix with behavior change | Contract review + QA |
+| 4–5 | Low | Docs, prompts, config only, no behavior change | Contract review + QA |
 
-## Updating the kit
+---
 
-```bash
-npm update -g contract-driven-delivery
-cdd-kit update
+## Task notation in `tasks.md`
+
+```markdown
+- [x] 1.1 Confirm classification       ← done
+- [-] 2.2 CSS/UI contract              ← N/A (not applicable to this change)
+- [ ] 4.1 Backend implementation       ← pending
 ```
 
+`cdd-kit gate --strict` treats any `[ ]` (except section 7 archive tasks) as an error. Use `[-]` for items that are genuinely not applicable to a given change.
+
+---
+
 ## License
 
 MIT