contract-driven-delivery 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,193 @@
 # Changelog
 
+## [Unreleased]
+
+_No unreleased changes yet._
+
+## [2.2.0] - 2026-06-02
+
+Make enforcement live by default, add a mechanical risk-tier safety net under the
+AI classifier, and give code indexing an opt-in background mode — the three gaps
+that matter most for a fully automated, no-human-reviewer workflow.
+
+### Added
+
+- **Arm enforcement chokepoints by default in `cdd-kit init`.** A fresh `init`
+  now wires the graph-first PreToolUse hook (Claude provider, advisory) and the
+  pre-commit gate hook, instead of shipping them dormant. In an automated
+  workflow with no human reviewer, dormant enforcement means the contracts and
+  docs only *look* like they prevent drift. Best-effort: a missing `.git` or
+  unusual `settings.json` downgrades to a warning, never a failed init. Opt out
+  with `cdd-kit init --no-arm`. `installHooks`/`installAgentHooks` gained a
+  `fromInit` mode so arming is non-fatal.
+- **Mechanical risk-tier floor (`src/utils/tier-floor.ts`).** A deterministic
+  backstop under the (AI) classifier: `cdd-kit gate` scans `change-request.md`
+  for sensitive surfaces (auth, payments, migrations, concurrency, secrets, …)
+  and **fails** when the declared tier is weaker than the matched floor, so a
+  single mis-classification can no longer silently drop the required agents and
+  tests. Bypass per-change with `tier-floor-override: "<reason>"` in `tasks.yml`
+  frontmatter (downgrades to an audit warning). Policy lives in
+  `.cdd/tier-policy.json` (scaffolded, fully editable, `enabled:false` to
+  disable); built-in defaults apply when the file is absent so existing repos are
+  protected without a re-init.
+- **`cdd-kit classify-check [change-id] | --text "<intent>"`** — advisory probe
+  that prints the mechanical tier floor *before* classification, so the
+  classifier can be steered up front rather than only caught by the gate.
+  Supports `--json`.
+- **`cdd-kit code-map --watch`** — opt-in background auto-indexing. A debounced
+  (default 500 ms, `--debounce`) recursive watcher keeps the map fresh during
+  long-lived co-editing sessions, with a freshness-polling fallback where
+  recursive `fs.watch` is unavailable. Trigger-based indexing stays the default
+  for ephemeral CI/agent runs.
+- **ADR 0003** (`docs/adr/0003-code-intelligence-indexing-strategy.md`):
+  evaluates LSP (Serena) vs tree-sitter incremental (CocoIndex) vs the kit's
+  native AST scanners, and the trigger-vs-background refresh question. Decision:
+  keep native AST (LSP does not translate to headless agents), keep trigger-based
+  as default, add the opt-in `--watch` above, and sequence per-file incremental
+  rebuild as the next step.
+
+### Added (mechanical chokepoints — prior unreleased work)
+
+- **API conformance validator** (`validate_api_conformance.py`): parses real
+  backend route declarations and frontend HTTP call sites and diffs them against
+  `contracts/api/api-contract.md`. Catches frontend/backend API drift that the
+  markdown-only validators never could. Chained into `cdd-kit validate
+  --contracts`, so `cdd-kit gate` blocks on drift. Off until enabled in
+  `.cdd/conformance.json` (`"enabled": true`); a disabled config is scaffolded by
+  `cdd-kit init`. See `docs/api-conformance.md`.
+- **`--with-source` / `withSource`** on `cdd-kit index query`, `cdd-kit graph
+  query`, and the `cdd_index_query` / `cdd_graph_query` MCP tools: returns the
+  matched symbol's code inline so the query replaces a follow-up `Read` instead
+  of preceding it. `--source-budget` caps total lines and flags truncated ranges.
+- **`hooks/pre-tool-use-graph-first.sh`** (opt-in PreToolUse hook): steers agents
+  to `cdd-kit index query --with-source` before reading source files. Advisory by
+  default; `CDD_GRAPH_FIRST_STRICT=1` hard-blocks source reads when a code-map
+  exists.
+- `cdd-kit doctor` reports whether API conformance is enabled, disabled, or
+  unconfigured (informational; never fails `--strict`).
+- `cdd-kit doctor` reports whether the **cdd-kit MCP server is registered** with
+  Claude Code (runs `claude mcp list`). If it is not registered, agents never see
+  the graph/index tools and silently fall back to `Read`, so doctor surfaces the
+  `claude mcp add --scope user cdd-kit -- cdd-kit mcp` command to fix it.
+  Informational only (never fails `--strict`), best-effort with a 3s timeout
+  (never blocks on a slow/missing `claude` CLI), skipped for non-Claude and
+  non-cdd-kit projects. `CDD_CLAUDE_BIN` overrides the CLI path. Closes the gap
+  left by `--with-source`: the incentive to use the kit tools only helps if the
+  agent can see them.
+- **`cdd-kit install-agent-hooks --graph-first advisory|strict`**: installs the
+  graph-first `PreToolUse` hook into `.claude/settings.json` (project-scoped) and
+  copies the script to `.claude/hooks/`, so steering agents to
+  `cdd-kit index query --with-source` before `Read` becomes an installed harness
+  chokepoint instead of manual settings wiring. Advisory by default; `strict`
+  writes `CDD_GRAPH_FIRST_STRICT=1`. Idempotent and preserves unrelated settings.
+- **`cdd-kit openapi export`**: projects `contracts/api/api-contract.md` into a
+  minimal OpenAPI 3.1 skeleton (`--yaml`, `--out`) for tooling such as
+  `openapi-typescript`. One-way projection — the markdown contract stays the
+  source of truth. Derives paths/params/auth/status codes; marks free-form
+  request/response bodies as `x-cdd-unresolved` rather than fabricating schemas.
+  Per-stack client generation is intentionally left to the consumer repo; see
+  `docs/adr/0001-contract-to-openapi-export.md` and `docs/openapi-export.md`.
+- **`cdd-kit openapi export --check`**: the OpenAPI sync gate. Instead of
+  writing, it verifies the committed artifact at `--out` still equals what the
+  contract produces and exits non-zero on drift — so CI fails when the contract
+  changes but the export was not regenerated. This is the kit-owned half of the
+  preventive chain (the consumer's typed-client codegen runs from an artifact
+  that can never be silently stale).
+- **`cdd-kit init` now wires the consumer codegen seam**: when a `package.json`
+  is present it adds editable `contract:client` and `contract:client:check` npm
+  scripts (the latter is the `openapi export --check` gate), turning the
+  consumer half of the OpenAPI seam from a doc into a chokepoint. Additive,
+  idempotent, never clobbers existing scripts; `openapi-typescript` is an
+  editable default, not a hard dependency.
+- **`cdd-kit doctor` chokepoint dashboard**: reports each enforcement chokepoint
+  (graph-first hook, pre-commit gate, OpenAPI sync gate) as `live` or `dormant`
+  with the one command to arm it. The kit's mechanisms are opt-in and dormant
+  until armed, so a repo could carry all the machinery yet enforce none of it —
+  this makes that observable. Advisory only (never fails `--strict`).
+
+### Changed
+
+- `backend-engineer` and `frontend-engineer` prompts now prefer
+  `--with-source` queries and warn that endpoint changes/calls require a contract
+  update when conformance is enabled.
+
+### Fixed
+
+- **graph-first hook now installs in the shape Claude Code executes.**
+  `install-agent-hooks` wrote the command directly on the `PreToolUse` matcher
+  group; Claude Code requires it nested under an inner `hooks: [{ type:
+  "command", … }]` array, so the chokepoint was silently dormant even though
+  install/init reported it armed. Re-running upgrades a legacy entry in place and
+  preserves unrelated handlers that share the matcher group.
+- **tier floor scans the right path scope.** `cdd-kit gate` now scans the
+  **staged** change (rename-aware, both sides) instead of the whole worktree, so
+  an unrelated unstaged `auth/` edit can no longer trip the floor and reject a
+  low-risk commit; when a single commit stages more than one change directory the
+  path signal is dropped (source paths can't be attributed to one change) and
+  only the request text sets the floor. `cdd-kit classify-check` keeps
+  whole-worktree scope (its in-progress change is not yet committed).
+- **tier-floor pattern accuracy.** Critical-surface patterns now match plural
+  directories (`payments/`, `migrations/`); the `token` pattern is qualified to
+  security contexts (`access`/`api`/`auth`/`session`/`bearer`/`refresh`/`csrf`/
+  `id`/`reset`) so frontend "design tokens" / `theme/tokens.ts` no longer trip
+  the secrets floor. The gate / `classify-check` `matched:` line now reports the
+  actual matched text (e.g. `session token`) instead of the raw regex pattern.
+- **`cdd-kit doctor` detects a gate armed under a custom `core.hooksPath`** (or a
+  worktree/submodule), resolving the hooks dir via git instead of probing only
+  `.git/hooks/pre-commit` — no more reporting a live gate as dormant.
+- **`cdd-kit code-map --watch` skips churn under ignored trees** (`node_modules`,
+  `dist`, `.git`, `.next`, coverage) before rebuilding, and adds an `error`
+  listener so fs-watch runtime errors (ENOSPC, permissions) degrade to polling
+  instead of crashing the watch. Edits to `.cdd/code-map-config.yml` still
+  trigger a rebuild even though it lives under the ignored `.cdd/` tree.
+- **`cdd-kit gate` no longer passes changes whose artifacts are still unfilled
+  scaffolds.** The stub check counted "meaningful chars", but a template's own
+  instructional prose (900+ chars) cleared the threshold while every field was
+  still an `<id>` / `<date>` / `<change-id>` placeholder — so a change could pass
+  `--strict` with raw templates and zero real content. Gate now fails and names
+  the remaining placeholder tokens per artifact. The check is a closed allowlist
+  (`<id>` / `<date>` / `<change-id>`) anchored to the colon-led, line-final value
+  position the templates use (`change-id: <id>`, `# …: <change-id>`), so inline
+  XML/markup examples (`<id>123</id>`) and hyphenated custom elements
+  (`<my-element>`) are not false-flagged — and a file may carry both a real
+  placeholder and an XML example without the placeholder slipping through.
+  `context-manifest.md` is exempt (its `<...>` sub-sections are documented as
+  illustrative; it is enforced via Allowed Paths, not template fill-ins).
+- **`cdd-kit validate` / `gate` no longer crash with `UnicodeDecodeError` on
+  non-UTF-8 Windows locales (e.g. cp950/zh-TW).** `validate_contract_versions.py`
+  read `git show` output and the validators wrote stdout using the locale codec,
+  spamming tracebacks and mojibaking em-dashes in contracts. The Python
+  validators are now spawned with `PYTHONUTF8=1` / `PYTHONIOENCODING=utf-8`, and
+  the git subprocesses decode as UTF-8 explicitly.
+- **`cdd-kit openapi export` fails fast on a mis-tagged schema fence** instead of
+  silently dropping it: a `### Name` section under `## Schemas` that uses ` ```json `
+  (or any non-`json-schema` fence) now errors with the fix — including when a field
+  table is also present (the stray fence was previously ignored). A prose-only
+  section with no fence stays a valid Tier C contract and is left unresolved.
+- **`cdd-kit openapi export --out <absolute-path>`** no longer ENOENTs on an
+  absolute path (it was concatenated onto cwd, e.g. `D:\repo\C:\Users\…`); paths
+  are resolved with `path.resolve`.
+
+### Added
+
+- **`cdd-kit openapi export` typed schemas (ADR 0002)**: `## Schemas` sections
+  compile field tables (Tier A) and `json-schema` fenced blocks (Tier B) into
+  `components.schemas` with `$ref` resolution; the contract stub documents both
+  tiers.
+
+## [2.1.3] - 2026-05-29
+
+Correct Claude Code MCP registration guidance.
+
+### Changed
+
+- Install and upgrade guidance now recommends
+  `claude mcp add --scope user cdd-kit -- cdd-kit mcp`, which writes the server
+  to `~/.claude.json`.
+- Documentation now warns that adding `mcpServers` to
+  `~/.claude/settings.json` alone is not sufficient for Claude Code CLI MCP
+  discovery.
+
 ## [2.1.2] - 2026-05-29
 
 Recommended MCP setup during install and upgrade.

package/README.md

@@ -269,17 +269,34 @@ 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
+cdd-kit init --no-arm         # scaffold without arming enforcement chokepoints
 ```
 
+By default `init` **arms** the enforcement chokepoints so a fresh repo enforces
+the workflow instead of carrying it dormant: the graph-first PreToolUse hook
+(Claude provider, advisory) and the pre-commit gate hook are wired in place. This
+matters most in a fully automated, no-human-reviewer workflow — dormant
+enforcement means the contracts only *look* like they prevent drift. Arming is
+best-effort (a missing `.git` becomes a warning, never a failed init); pass
+`--no-arm` to skip it, and `cdd-kit doctor` reports the live/dormant status of
+each chokepoint.
+
 Creates: `contracts/`, `specs/templates/`, provider guidance files (`CLAUDE.md`, `AGENTS.md`, and/or `CODEX.md`), `hooks/`
 
 `.cdd/model-policy.json` stores role-to-model **classes** (`opus`, `sonnet`, `haiku`) instead of provider release IDs such as `claude-opus-4-7`. This keeps the policy stable across Claude and Codex adapters; provider-specific tooling can map the class to the concrete model available in that environment.
 
-Recommended: configure MCP-capable AI agents with `command: "cdd-kit"` and
-`args: ["mcp"]` after init. This exposes graph/code-map tools directly to the
-agent (`cdd_graph_context`, `cdd_graph_query`, `cdd_graph_impact`,
-`cdd_index_query`, `cdd_index_impact`) so project exploration does not depend on
-the agent remembering shell commands.
+Recommended: register the cdd-kit MCP server with Claude Code after init:
+
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+claude mcp list
+```
+
+This writes the server to `~/.claude.json` and exposes graph/code-map tools
+directly to the agent (`cdd_graph_context`, `cdd_graph_query`,
+`cdd_graph_impact`, `cdd_index_query`, `cdd_index_impact`). Do not rely on
+manually adding `mcpServers` to `~/.claude/settings.json`; that file is a Claude
+Code UI settings format and is not the MCP registry read by the CLI.
 
 ---
 
@@ -313,9 +330,10 @@ cdd-kit migrate --all    # add new per-change scaffolds such as implementation-p
 cdd-kit doctor --strict
 ```
 
-After syncing, configure MCP-capable agents with `command: "cdd-kit"` and
-`args: ["mcp"]`. This is the recommended way for agents to use the regenerated
-code graph and code-map; shell commands remain the fallback.
+After syncing, register MCP-capable agents with
+`claude mcp add --scope user cdd-kit -- cdd-kit mcp`. This is the recommended
+way for agents to use the regenerated code graph and code-map; shell commands
+remain the fallback.
 
 What gets updated:
 
@@ -333,6 +351,29 @@ place. Then run `cdd-kit migrate --all` so existing active change directories
 receive `implementation-plan.md`; fill required `design.md` with
 `spec-architect` before resuming the planner or implementation agents.
 
+#### Upgrading to 2.2.0
+
+2.2.0 **arms enforcement chokepoints by default on a fresh `cdd-kit init`**, adds
+the mechanical **tier floor**, `cdd-kit classify-check`, and `cdd-kit code-map
+--watch`. A repo first set up with an older version keeps its chokepoints
+*dormant* after a plain `npm`/`refresh` update — `cdd-kit doctor` will show them
+as such. To bring an existing repo up to the 2.2.0 enforcement posture:
+
+```bash
+npm install -g contract-driven-delivery   # get 2.2.0
+cdd-kit refresh --yes                      # sync agents/skills/templates/hooks/code-map
+cdd-kit install-hooks                      # arm the pre-commit gate
+cdd-kit install-agent-hooks --graph-first advisory   # arm the graph-first hook (or: strict)
+cdd-kit doctor                             # confirm both chokepoints report "live"
+```
+
+The tier floor needs **no policy file** — built-in defaults apply when
+`.cdd/tier-policy.json` is absent, so existing repos are protected without a
+re-init. To customize or disable it, scaffold the policy with `cdd-kit upgrade
+--yes` (writes an editable `.cdd/tier-policy.json`) and set rules or
+`"enabled": false`. Bypass a single change with `tier-floor-override:
+"<reason>"` in its `tasks.yml` frontmatter (recorded as an audit warning).
+
 If you do not want template overwrites, run the narrower path:
 
 ```bash
@@ -358,6 +399,10 @@ cdd-kit doctor --provider codex
 
 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. `--fix` currently auto-runs `context-scan` for stale or missing indexes and backfills empty `.cdd/model-policy.json` role bindings, but deliberately does not run invasive repo upgrades for you.
 
+For Claude projects, `doctor` also reports whether the **cdd-kit MCP server is registered** with Claude Code (it runs `claude mcp list`). If it is not registered, agents never see the graph/index tools and silently fall back to `Read`, so doctor surfaces the exact `claude mcp add --scope user cdd-kit -- cdd-kit mcp` command to fix it. This check is **informational only** — it never fails `--strict`, never blocks on a slow or missing `claude` CLI (3s timeout, best-effort), and is skipped for non-Claude projects. Point `CDD_CLAUDE_BIN` at an alternate Claude CLI if needed.
+
+`doctor` finally prints a **chokepoint dashboard**: for each enforcement mechanism — the graph-first hook, the pre-commit gate, and the OpenAPI sync gate — it reports `live` (armed) or `dormant`, with the one command to arm it. The kit's mechanisms are opt-in and dormant until installed, so a repo can carry all the machinery yet enforce none of it; this makes that state observable. Like the MCP and conformance lines, it is **advisory only** and never fails `--strict`.
+
 ---
 
 ### `cdd-kit upgrade`
@@ -399,10 +444,17 @@ cdd-kit refresh --yes --no-templates
 5. Resyncs `.cdd/model-policy.json` roles from installed agent frontmatter.
 6. Regenerates `.cdd/code-map.yml`.
 
-After `refresh --yes`, configure MCP-capable agents to run `cdd-kit mcp`.
+After `refresh --yes`, register the MCP server:
+
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+```
+
 The MCP tools are the recommended graph/code-map exploration interface for AI
-agents; `cdd-kit graph ...` and `cdd-kit index ...` remain the fallback when MCP
-is not available.
+agents. Claude Code CLI stores user-scope MCP servers in `~/.claude.json`; a
+manual `mcpServers` entry in `~/.claude/settings.json` is not sufficient.
+`cdd-kit graph ...` and `cdd-kit index ...` remain the fallback when MCP is not
+available.
 
 Run `cdd-kit migrate --all` separately when you need existing
 `specs/changes/*` directories to gain new required artifacts.
@@ -422,6 +474,7 @@ Checks:
 - All required artifacts exist (`change-request.md`, `change-classification.md`, `implementation-plan.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`; new context-governed changes also require `context-manifest.md`)
 - Each artifact has sufficient content and is not a stub.
 - `change-classification.md` contains a tier or risk marker.
+- **Mechanical risk-tier floor.** `change-request.md` is scanned for sensitive surfaces (auth, payments, migrations, concurrency, secrets, …) — and the change's git paths are scanned against the critical (tier-0) rules only, so a generic request whose work lives under `auth/` or `payments/` is still caught. The gate scans the **staged** change (so an unrelated unstaged edit can't trip it; rename-aware on both sides; the path signal is dropped when a commit stages multiple change dirs), while `classify-check` scans the whole worktree. The gate fails when the declared tier is weaker than the matched floor — the deterministic safety net under the AI classifier. Bypass one change with `tier-floor-override: "<reason>"` in `tasks.yml` frontmatter (becomes an audit warning); tune or disable in `.cdd/tier-policy.json`.
 - Atomic `depends-on` upstream changes are completed or archived before dependent work gates.
 - All contract validators pass.
 
@@ -441,6 +494,25 @@ Pre-commit hook uses `--strict` by default (installed via `cdd-kit install-hooks
 
 ---
 
+### `cdd-kit classify-check`
+
+Advisory probe that prints the **mechanical risk-tier floor** for a change
+*before* classification, so the classifier can be steered up front instead of
+only being caught later by `cdd-kit gate`. The blocking enforcement lives in the
+gate; this command never fails (exit 0).
+
+```bash
+cdd-kit classify-check add-jwt-auth                 # scan the change's change-request.md
+cdd-kit classify-check --text "add stripe checkout" # scan inline intent
+cdd-kit classify-check add-jwt-auth --json          # machine-readable
+```
+
+It reads the same ground-truth source the gate enforces against
+(`change-request.md`), reports the strictest matched tier and the matched
+patterns, and points at `.cdd/tier-policy.json` for tuning.
+
+---
+
 ### `cdd-kit list`
 
 Lists all active changes in `specs/changes/` with status and pending task count.
@@ -592,13 +664,38 @@ Runs contract validation scripts.
 
 ```bash
 cdd-kit validate                # all validators
-cdd-kit validate --contracts    # API, CSS, data-shape (+ semantic checks)
+cdd-kit validate --contracts    # API, CSS, data-shape (+ semantic + conformance 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
 ```
 
+`--contracts` includes **API conformance**: a code-vs-contract check that parses
+real backend routes and frontend call sites and fails on drift from
+`contracts/api/api-contract.md` (e.g. the frontend calling an endpoint the
+contract never declares). It is off until you enable it in `.cdd/conformance.json`
+(`"enabled": true`); `cdd-kit init` scaffolds a disabled config. See
+[docs/api-conformance.md](docs/api-conformance.md). This is the mechanical net
+for frontend/backend API drift in a workflow where no human reviews the contract
+by hand.
+
+---
+
+### `cdd-kit openapi export`
+
+Projects `contracts/api/api-contract.md` into a minimal **OpenAPI 3.1** skeleton for tooling (e.g. feeding `openapi-typescript` to generate a typed frontend client). The markdown contract stays the source of truth; the OpenAPI document is a one-way, regenerable projection.
+
+```bash
+cdd-kit openapi export                          # JSON to stdout
+cdd-kit openapi export --yaml --out openapi.yaml # YAML to a file
+cdd-kit openapi export --check --out openapi.json # sync gate: fail on drift
+```
+
+It derives paths (normalizing `:id`/`{id}`), path parameters, auth → bearer security, and success/error status codes. Free-form request/response schemas in the contract are marked `x-cdd-unresolved` rather than fabricated. Generating an actual client is left to your stack's generator in your own CI — this is the **preventive** complement to the **detective** conformance check above. See [docs/openapi-export.md](docs/openapi-export.md) and [docs/adr/0001-contract-to-openapi-export.md](docs/adr/0001-contract-to-openapi-export.md).
+
+`--check` is the **sync gate**: it does not write, it verifies the committed artifact at `--out` still matches the contract and exits non-zero on drift, so CI fails when a contract edit forgets to regenerate the export (and the typed client downstream). To wire the consumer half, `cdd-kit init` scaffolds editable `contract:client` and `contract:client:check` npm scripts when a `package.json` is present — the generic contract→OpenAPI step is the kit's, the stack-specific codegen stays an editable script in your repo.
+
 ---
 
 ### `cdd-kit new <name>`
@@ -636,6 +733,22 @@ Idempotent. Preserves existing hook content. Bypass with `--no-verify` is possib
 
 ---
 
+### `cdd-kit install-agent-hooks`
+
+Installs Claude Code **agent hooks** into the project's `.claude/settings.json`. Currently installs the graph-first `PreToolUse` hook, which steers agents to `cdd-kit index query --with-source` before reading source files — turning the hook from a documented file you wire by hand into an enforced harness chokepoint.
+
+```bash
+cdd-kit install-agent-hooks                      # advisory (default)
+cdd-kit install-agent-hooks --graph-first strict # hard-block source Reads when a code-map exists
+```
+
+- **advisory** (default): reminds the agent to use the graph/index query first; does not block the `Read`.
+- **strict**: writes `CDD_GRAPH_FIRST_STRICT=1` into the hook command so the hook blocks source-file `Read` when `.cdd/code-map.yml` exists.
+
+Writes the hook script to `.claude/hooks/pre-tool-use-graph-first.sh` and a `PreToolUse` entry to `.claude/settings.json` (project-scoped, so it travels with the repo). Idempotent: re-running replaces the cdd-kit entry and switches mode cleanly, preserving every other setting and hook.
+
+---
+
 ### `cdd-kit detect-stack`
 
 Detects the project tech stack from lockfiles and config files.
@@ -697,8 +810,21 @@ cdd-kit code-map                          # whole repo -> .cdd/code-map.yml
 cdd-kit code-map --check                  # exit 1 if regenerating would change the map
 cdd-kit code-map --surface packages/web   # monorepo: scope + auto-name the map
 cdd-kit code-map --workers                # parallelize JS/TS/Vue scanning (default off)
+cdd-kit code-map --watch                  # background: keep the map fresh as files change
+cdd-kit code-map --watch --debounce 800   # coalesce change bursts within 800ms
 ```
 
+Indexing is **trigger-based by default** — the map regenerates when a command
+needs it (gate, `index query --refresh`, `doctor --fix`, the pre-commit code-map
+hook). That is the right default for ephemeral CI containers and one-shot agent
+runs. `--watch` is the opt-in **background** mode for long-lived co-editing
+sessions: a debounced recursive watcher keeps the map fresh so queries stay cheap
+and current, with a freshness-polling fallback where recursive `fs.watch` is
+unavailable. See
+[docs/adr/0003-code-intelligence-indexing-strategy.md](docs/adr/0003-code-intelligence-indexing-strategy.md)
+for why the kit keeps native AST scanners instead of an LSP daemon, and the
+incremental-rebuild roadmap.
+
 `--workers [n]` (default off; `n` defaults to CPU count − 1, capped at 16)
 parallelizes the synchronous JS/TS/Vue parsing across child processes for large
 repos. Output is byte-identical to a single-process run, and any worker failure
@@ -720,10 +846,22 @@ with `--engine codegraph`.
 ```bash
 cdd-kit graph status
 cdd-kit graph query OrderService
+cdd-kit graph query OrderService --with-source   # include code inline; no follow-up Read needed
 cdd-kit graph context "filter options are empty"
 cdd-kit graph impact src/services/orders.ts --depth 2
 ```
 
+`--with-source` (also on `cdd-kit index query`, and `withSource: true` via MCP)
+returns the matched symbol's code inline so the query *replaces* a `Read` rather
+than preceding it — making the kit tool strictly cheaper than the built-in
+`Read`. `--source-budget <n>` caps total lines returned; truncated ranges are
+flagged so you can `Read` only those.
+
+To make graph-first exploration a real chokepoint instead of a prompt
+preference, wire the shipped `hooks/pre-tool-use-graph-first.sh` as a
+`PreToolUse` hook on `Read` (advisory by default; `CDD_GRAPH_FIRST_STRICT=1`
+hard-blocks source `Read`s when a code-map exists).
+
 Use `--engine native` for the built-in graph, `--engine codemap` for the older
 code-map-only fallback, `--engine codegraph` to require external CodeGraph, or
 `CDD_CODEGRAPH_BIN=/path/to/codegraph` to point at a custom binary.
@@ -731,19 +869,17 @@ code-map-only fallback, `--engine codegraph` to require external CodeGraph, or
 ### `cdd-kit mcp`
 
 `cdd-kit mcp` runs a stdio MCP server so agents can call the graph/index layer
-as tools instead of shelling out manually.
+as tools instead of shelling out manually. Register it with Claude Code:
 
-```json
-{
-  "mcpServers": {
-    "cdd-kit": {
-      "command": "cdd-kit",
-      "args": ["mcp"]
-    }
-  }
-}
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+claude mcp list
 ```
 
+Use the CLI command above so Claude Code writes the server to `~/.claude.json`.
+Do not rely on manually editing `~/.claude/settings.json`; that file is not the
+MCP registry read by the CLI.
+
 Exposed tools:
 
 - `cdd_graph_status`
@@ -819,7 +955,7 @@ Then choose one path per active change:
 ### Recommended rollout for production repos already burned by token overuse
 
 1. Run `cdd-kit refresh --yes` once per repo after updating the npm package.
-2. Configure MCP-capable agents with `command: "cdd-kit"` and `args: ["mcp"]`.
+2. Register MCP-capable agents with `claude mcp add --scope user cdd-kit -- cdd-kit mcp`.
 3. Run `cdd-kit migrate --all` so existing active changes receive the current required artifact set.
 4. Review and fill `implementation-plan.md` before resuming implementation agents on active changes.
 5. Run `cdd-kit doctor --strict` in CI.

package/assets/CLAUDE.template.md

@@ -46,17 +46,16 @@ Run `cdd-kit detect-stack` to verify the detected tech stack.
 
 Configure MCP-capable agents to use the cdd-kit server:
 
-```json
-{
-  "mcpServers": {
-    "cdd-kit": {
-      "command": "cdd-kit",
-      "args": ["mcp"]
-    }
-  }
-}
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+claude mcp list
 ```
 
+For Claude Code, use `claude mcp add` so the server is written to
+`~/.claude.json`. Do not rely on manually adding `mcpServers` to
+`~/.claude/settings.json`; that is a Claude Code UI settings format and is not
+the MCP registry read by the CLI.
+
 Prefer these MCP tools before reading source files: `cdd_graph_context`,
 `cdd_graph_query`, `cdd_graph_impact`, `cdd_index_query`, and
 `cdd_index_impact`. They use `.cdd/code-map.yml` and
@@ -64,6 +63,19 @@ Prefer these MCP tools before reading source files: `cdd_graph_context`,
 available, use the equivalent CLI commands: `cdd-kit graph ...` and
 `cdd-kit index ...`.
 
+Pass `withSource: true` (MCP) or `--with-source` (CLI) on `query` to get the
+matched symbol's code inline. The query then replaces a follow-up `Read` instead
+of preceding it — use a plain `Read` only for ranges the query did not return
+(e.g. a range flagged as source-budget truncated).
+
+## API Conformance
+
+If `.cdd/conformance.json` has `"enabled": true`, `cdd-kit validate --contracts`
+(and `cdd-kit gate`) mechanically check real backend routes and frontend call
+sites against `contracts/api/api-contract.md`. Do not add, rename, or call an
+endpoint without updating the contract in the same change, or the gate will fail
+on the drift. See `docs/api-conformance.md`.
+
 ## Context Governance
 
 For context-governed changes, read `specs/changes/<change-id>/context-manifest.md` before using file-reading or broad search tools.

package/assets/CODEX.template.md

@@ -15,17 +15,16 @@ This project uses Contract-Driven Delivery (CDD).
 
 Configure MCP-capable agents to use the cdd-kit server:
 
-```json
-{
-  "mcpServers": {
-    "cdd-kit": {
-      "command": "cdd-kit",
-      "args": ["mcp"]
-    }
-  }
-}
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+claude mcp list
 ```
 
+For Claude Code, use `claude mcp add` so the server is written to
+`~/.claude.json`. Do not rely on manually adding `mcpServers` to
+`~/.claude/settings.json`; that is a Claude Code UI settings format and is not
+the MCP registry read by the CLI.
+
 Prefer these MCP tools before reading source files: `cdd_graph_context`,
 `cdd_graph_query`, `cdd_graph_impact`, `cdd_index_query`, and
 `cdd_index_impact`. They use `.cdd/code-map.yml` and

package/assets/agents/backend-engineer.md

@@ -11,7 +11,8 @@ Before editing production code, read `specs/changes/<change-id>/implementation-p
 
 ## Code map (READ FIRST)
 
-Before reading ANY source file (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.vue`), FIRST run `cdd-kit index query "<symbol-or-file>"` or `Read .cdd/code-map.yml`.
+Before reading ANY source file (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.vue`), FIRST run `cdd-kit index query "<symbol-or-file>" --with-source` or `Read .cdd/code-map.yml`.
+Prefer `--with-source`: it returns the matched symbol's code inline, so you do NOT need a separate `Read` for that range. Use a plain `Read` only when you need lines the query did not return (e.g. a range flagged as source-budget truncated).
 Before editing a chosen source file, run `cdd-kit index impact "<path-or-symbol>"` to identify indexed local imports and dependents.
 
 The map is the size oracle. For each file you intend to read:
@@ -31,6 +32,7 @@ See `references/code-map-protocol.md` for the full protocol.
 
 ## Rules
 
+- Do not change API response shape or add/rename/remove endpoints without updating `contracts/api/api-contract.md` in the same change. If `.cdd/conformance.json` is enabled, `cdd-kit validate --contracts` (and the gate) will fail when a backend route is missing from the contract.
 - Do not change API response shape without contract updates.
 - Keep route/controller code thin.
 - Put business logic in service/domain layers.

package/assets/agents/frontend-engineer.md

@@ -11,7 +11,8 @@ Before editing, read `specs/changes/<change-id>/implementation-plan.md`, API con
 
 ## Code map (READ FIRST)
 
-Before reading ANY source file (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.vue`), FIRST run `cdd-kit graph query "<symbol-or-file>"`, `cdd-kit graph context "<task>"`, `cdd-kit index query "<symbol-or-file>"`, or `Read .cdd/code-map.yml`.
+Before reading ANY source file (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.vue`), FIRST run `cdd-kit graph query "<symbol-or-file>" --with-source`, `cdd-kit graph context "<task>"`, `cdd-kit index query "<symbol-or-file>" --with-source`, or `Read .cdd/code-map.yml`.
+Prefer `--with-source`: it returns the matched symbol's code inline, so you do NOT need a separate `Read` for that range. Use a plain `Read` only for lines the query did not return (e.g. a range flagged as source-budget truncated).
 Before editing a chosen source file, run `cdd-kit graph impact "<path-or-symbol>" --depth 2` or `cdd-kit index impact "<path-or-symbol>"` to identify imports, dependents, callers/callees when available, and likely affected scope.
 
 The map is the size oracle. For each file you intend to read:
@@ -31,7 +32,7 @@ See `references/code-map-protocol.md` for the full protocol.
 
 ## Rules
 
-- Do not assume backend response shape; use the API contract.
+- Do not assume backend response shape; use the API contract. Do not call an endpoint (path + method) that is not in `contracts/api/api-contract.md`. If `.cdd/conformance.json` is enabled, `cdd-kit validate --contracts` (and the gate) will fail on frontend calls that drift from the contract.
 - Follow `implementation-plan.md` for scope, non-goals, required changes, and file-level plan.
 - Do not expand scope beyond the implementation plan unless a Context Expansion Request is approved and the plan is updated.
 - Do not hard-code visual tokens when token system exists.

package/assets/cdd/conformance.json

@@ -0,0 +1,16 @@
+{
+  "_README": "Code-vs-contract API conformance. Run via `cdd-kit validate --contracts` (and `cdd-kit gate`). Set enabled:true to mechanically catch frontend/backend drift against contracts/api/api-contract.md. See docs/api-conformance.md.",
+  "enabled": false,
+  "apiPrefixes": ["/api"],
+  "sourceRoots": [],
+  "backendGlobsExt": [".py", ".js", ".ts", ".mjs", ".cjs", ".go", ".java", ".php"],
+  "frontendGlobsExt": [".js", ".jsx", ".ts", ".tsx", ".mjs", ".vue", ".svelte"],
+  "excludeDirs": ["node_modules", "dist", "build", ".git", ".cdd", "coverage", "vendor", "__pycache__", ".next", ".nuxt"],
+  "ignorePaths": ["/health", "/metrics"],
+  "checks": {
+    "backendRouteNotInContract": "error",
+    "contractEndpointNotImplemented": "warning",
+    "frontendCallNotInContract": "error"
+  },
+  "strict": false
+}