contract-driven-delivery 2.1.3 → 2.2.1

package/CHANGELOG.md

@@ -1,5 +1,224 @@
 # Changelog
 
+## [Unreleased]
+
+_No unreleased changes yet._
+
+## [2.2.1] - 2026-06-03
+
+Fix a class of false positives in the 2.2.0 API conformance validator that broke
+CI on correct contracts (issue #15), and stop a heuristic blind spot from being
+fatal by default.
+
+### Fixed
+
+- **Resolve Flask Blueprint `url_prefix` / FastAPI APIRouter `prefix` across
+  files (`validate_api_conformance.py`).** A route declared as
+  `@admin_bp.route("/api/logs")` on a `Blueprint(..., url_prefix="/admin")` (or a
+  `register_blueprint(bp, url_prefix=...)` in another file) was recorded as
+  `/api/logs`, so every prefixed route was flagged `backendRouteNotInContract`
+  while the matching contract endpoint was flagged
+  `contractEndpointNotImplemented` — two false errors per route against a contract
+  that was actually correct. The validator now resolves constructor prefixes per
+  file and registration prefixes across files (registration winning) and folds
+  them into the route path. Constructor scoping is **per file**, so a bare
+  `router` name reused across modules cannot collide; registration prefixes are
+  matched across files with each framework's semantics — Flask
+  `register_blueprint(url_prefix=...)` **overrides** the Blueprint's own prefix
+  while FastAPI `include_router(prefix=...)` is **additive** with the
+  `APIRouter(prefix=...)` (served as `<include>/<router>/<route>`). A name
+  registered under conflicting prefixes across files is detected and dropped (the
+  per-file constructor prefix decides) rather than guessed. The constructor regex
+  tolerates a nested-paren kwarg (`APIRouter(dependencies=[Depends(x)],
+  prefix=...)`), a module-qualified call (`flask.Blueprint(...)`,
+  `fastapi.APIRouter(...)`), and a type-annotated assignment (`router: APIRouter =
+  APIRouter(...)`); Flask 2.0 `@bp.get(...)` shorthand is covered too. An explicit
+  empty registration prefix (`register_blueprint(bp, url_prefix="")`, a deliberate
+  root mount) is preserved and overrides the constructor prefix rather than being
+  discarded as falsy. (Issue #15; hardened over three rounds of Codex/Sourcery PR
+  review.)
+
+### Changed
+
+- **`backendRouteNotInContract` now defaults to `warning`, not `error`.** Regex
+  scanning cannot resolve every cross-file route prefix (aliased routers, the
+  Express `app.use` mount form, module-qualified `include_router(pkg.router, …)`),
+  so a scanner blind spot must not break CI on a contract that is correct. Raise it to
+  `error` (or set `"strict": true`) to enforce once a project's routing shape is
+  known to resolve cleanly. Updated in `DEFAULT_CONFIG`, the scaffolded
+  `.cdd/conformance.json`, and `docs/api-conformance.md`.
+
+## [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.

package/README.md

@@ -269,8 +269,18 @@ 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.
@@ -341,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
@@ -366,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`
@@ -437,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.
 
@@ -456,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.
@@ -607,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>`
@@ -651,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.
@@ -712,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
@@ -735,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.

package/assets/CLAUDE.template.md

@@ -63,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/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": "warning",
+    "contractEndpointNotImplemented": "warning",
+    "frontendCallNotInContract": "error"
+  },
+  "strict": false
+}

package/assets/cdd/tier-policy.json

@@ -0,0 +1,35 @@
+{
+  "_README": "Mechanical risk-tier floor. A classifier (or any agent) proposes a tier in change-classification.md / tasks.yml; this policy is the safety net that prevents a high-risk surface from being silently under-classified. `cdd-kit gate` and `cdd-kit classify-check` scan change-request.md against ALL rules, and the change's git paths against the critical (maxTier 0) rules only (file paths are noisier than prose) — gate scans the STAGED change (what is about to be committed), classify-check scans the whole worktree (the in-progress change is not yet committed) — then require the declared tier to be at least as strict as the matched floor. Lower tier number = stricter. Set enabled:false to disable, or record `tier-floor-override: \"<reason>\"` in a change's tasks.yml frontmatter to bypass for one change with an audit trail.",
+  "enabled": true,
+  "schema-version": "0.1.0",
+  "rules": [
+    {
+      "maxTier": 0,
+      "label": "critical surface (auth / payments / data migration / concurrency / secrets)",
+      "patterns": [
+        "auth", "authn", "authz",
+        "authentication", "authorization", "authenticate", "authorize",
+        "authenticated", "authorized",
+        "login", "logout", "sign-?in", "sign-?up",
+        "passwords?", "passwd", "credentials?", "secrets?", "api[- ]?keys?",
+        "(access|api|auth|session|bearer|refresh|csrf|id|reset)[- ]?tokens?",
+        "jwt", "oauth", "oidc", "saml", "sessions?", "cookies?",
+        "payments?", "billing", "invoices?", "charges?", "refunds?", "checkout", "stripe", "paypal",
+        "migrations?", "migrate", "alter table", "drop table", "drop column", "schema change",
+        "concurrency", "race condition", "mutex", "deadlock", "transaction isolation",
+        "encrypt", "decrypt", "crypto", "hashing", "rbac", "permissions?", "access control",
+        "privileges?", "pii", "gdpr", "hipaa", "rate limit", "csrf", "xss", "sql injection"
+      ]
+    },
+    {
+      "maxTier": 2,
+      "label": "behavioral surface (api / data shape / queue / cache / external integration)",
+      "patterns": [
+        "endpoint", "route", "api contract", "request schema", "response schema",
+        "pagination", "queue", "worker", "cron", "scheduler", "webhook",
+        "cache", "redis", "database", "query", "index", "external service",
+        "third[- ]?party", "integration", "data shape", "nullable", "breaking change"
+      ]
+    }
+  ]
+}

package/assets/contracts/api/api-contract.md

@@ -21,6 +21,32 @@ breaking-change-policy: deprecate-2-minors
 | method | path | auth | request schema | response schema | errors | tests |
 |---|---|---|---|---|---|---|
 
+## Schemas
+
+<!--
+Optional. Add named schemas here when request/response bodies should become
+machine-typed in `cdd-kit openapi export`. Reference a schema by name in the
+endpoint table's "request schema" / "response schema" cell (use `Name[]` for an
+array). A schema is defined ONE of two ways — never both:
+
+Tier A — a field table (preferred; readable, diffable):
+
+### ExampleRequest
+| field | type | required | format | notes |
+|---|---|---|---|---|
+| email | string | yes | email | login identity |
+| status | enum(active, disabled) | no | | lifecycle state |
+| owner | ExampleUser | no | | reference another schema by name |
+
+Tier B — a raw JSON Schema, for shapes Tier A can't express (oneOf, etc.).
+The fence MUST be tagged `json-schema` (NOT `json`) or export fails fast:
+
+### ExampleEvent
+```json-schema
+{ "type": "object", "oneOf": [ { "required": ["createdAt"] }, { "required": ["deletedAt"] } ] }
+```
+-->
+
 ## Error Format
 
 ## Compatibility Policy

package/assets/hooks/pre-tool-use-graph-first.sh

@@ -0,0 +1,65 @@
+#!/bin/sh
+# cdd-kit PreToolUse hook (opt-in): steer agents to graph-first exploration.
+#
+# Prose in agent prompts ("run cdd-kit index query before reading") is a soft
+# preference that loses to the model's built-in habit of reaching for Read.
+# This hook turns that preference into an actual chokepoint: when an agent is
+# about to Read a *source* file and a code-map exists, it reminds the agent to
+# use `cdd-kit index query "<symbol>" --with-source` (which returns the code
+# inline, so the Read is usually unnecessary).
+#
+# Default mode is ADVISORY: it prints guidance to stderr and allows the Read.
+# Set CDD_GRAPH_FIRST_STRICT=1 to BLOCK the Read instead (exit 2), forcing the
+# graph-first path. Contract/spec/markdown/Read of .cdd/code-map.yml itself are
+# always allowed.
+#
+# Wire into Claude Code (~/.claude/settings.json):
+#
+#   {
+#     "hooks": {
+#       "PreToolUse": [
+#         { "matcher": "Read", "command": "/path/to/hooks/pre-tool-use-graph-first.sh" }
+#       ]
+#     }
+#   }
+#
+# The hook receives the tool-call payload as JSON on stdin.
+
+set -eu
+
+# No code-map → nothing to steer toward; allow.
+[ -f ".cdd/code-map.yml" ] || exit 0
+
+payload="$(cat || true)"
+[ -z "$payload" ] && exit 0
+
+# Extract the Read target path.
+path_value=""
+if command -v jq >/dev/null 2>&1; then
+  path_value="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+fi
+if [ -z "$path_value" ]; then
+  path_value="$(printf '%s' "$payload" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]+"' | head -n1 | sed -E 's/.*"file_path"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')"
+fi
+[ -z "$path_value" ] && exit 0
+
+# Only steer for source files; never interfere with docs/specs/contracts/config.
+case "$path_value" in
+  *.py|*.js|*.jsx|*.mjs|*.cjs|*.ts|*.tsx|*.vue|*.svelte|*.go|*.java|*.rb|*.php) : ;;
+  *) exit 0 ;;
+esac
+# Allow reading the map itself.
+case "$path_value" in
+  *.cdd/code-map.yml) exit 0 ;;
+esac
+
+msg="cdd-kit: prefer \`cdd-kit index query \"<symbol-or-file>\" --with-source\` (or \`cdd-kit graph query ... --with-source\`) before Read — it returns the code inline and keeps token use low. Read directly only for ranges the query did not return."
+
+if [ "${CDD_GRAPH_FIRST_STRICT:-0}" = "1" ]; then
+  # Block and feed the reason back to the model.
+  printf '%s\n' "$msg Set CDD_GRAPH_FIRST_STRICT=0 to make this advisory only." 1>&2
+  exit 2
+fi
+
+printf '%s\n' "$msg" 1>&2
+exit 0