contract-driven-delivery 2.1.2 → 2.2.0

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

package/assets/skills/contract-driven-delivery/scripts/validate_api_conformance.py

@@ -0,0 +1,543 @@
+#!/usr/bin/env python3
+"""Code-vs-contract API conformance check.
+
+The other API validator (validate_api_semantic.py) only checks that the
+contract *document* is internally well formed. It never looks at code, so
+frontend and backend can both drift away from the contract without anything
+failing. In a workflow where no human reviews the contract by hand, that
+markdown is only worth what a machine can enforce against real code.
+
+This validator closes that gap. It:
+  1. reads the authoritative endpoint table from contracts/api/api-contract.md
+  2. scans backend source for route declarations (Express/Koa/Fastify/NestJS,
+     Flask/FastAPI/Django, Spring, Go net/http & chi/gin, Laravel, Rails-ish)
+  3. scans frontend source for HTTP call sites (fetch/axios/ky/$http/api.*)
+  4. diffs both against the contract and reports drift
+
+It is intentionally heuristic and stack-agnostic (regex, no per-framework
+parser). To avoid false positives on the many repos that ship this kit, it is
+OFF unless `.cdd/conformance.json` exists with `"enabled": true`. When the
+config is absent it prints a one-line skip notice and exits 0.
+
+Exit codes:
+  0  conformance OK, or skipped (no/disabled config)
+  1  drift found (or, in strict mode, warnings escalated to errors)
+
+Config (.cdd/conformance.json), all keys optional:
+{
+  "enabled": true,
+  "apiPrefixes": ["/api"],          // only FE calls under these prefixes are checked
+  "sourceRoots": ["src", "app"],    // dirs to scan; default: common roots that exist
+  "backendGlobsExt": [".py", ".js", ".ts", ".go", ".java", ".php"],
+  "frontendGlobsExt": [".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte"],
+  "excludeDirs": ["node_modules", "dist", "build", ".git", "tests", "__tests__"],
+  "ignorePaths": ["/health", "/metrics"],  // contract+code paths to ignore (supports trailing *)
+  "checks": {
+    "backendRouteNotInContract": "error",
+    "contractEndpointNotImplemented": "warning",
+    "frontendCallNotInContract": "error"
+  },
+  "strict": false                   // escalate all warnings to errors
+}
+"""
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+CONTRACT_PATH = Path('contracts/api/api-contract.md')
+CONFIG_PATH = Path('.cdd/conformance.json')
+
+VALID_METHODS = {'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'}
+
+DEFAULT_CONFIG = {
+    'enabled': False,
+    'apiPrefixes': ['/api'],
+    'sourceRoots': [],  # auto-detected when empty
+    # No '.rb' by default: Rails routing is a stateful DSL (routes.rb draw block)
+    # that a regex heuristic cannot parse honestly, so it is not claimed here.
+    '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': [],
+    'checks': {
+        'backendRouteNotInContract': 'error',
+        'contractEndpointNotImplemented': 'warning',
+        'frontendCallNotInContract': 'error',
+    },
+    'strict': False,
+}
+
+AUTO_ROOTS = ['src', 'app', 'lib', 'server', 'backend', 'frontend', 'web', 'api', 'pages', 'packages']
+
+
+# ── contract parsing (mirrors validate_api_semantic.py table logic) ───────────
+
+def strip_frontmatter(text: str) -> str:
+    if text.startswith('---'):
+        end = text.find('\n---', 3)
+        if end != -1:
+            return text[end + 4:].lstrip('\n')
+    return text
+
+
+def parse_table_row(line: str) -> list:
+    return [cell.strip() for cell in line.strip().strip('|').split('|')]
+
+
+def is_separator_row(cells: list) -> bool:
+    return all(re.match(r'^:?-+:?$', c) for c in cells if c)
+
+
+def find_contract_endpoints(lines: list) -> set:
+    """Return a set of (METHOD, normalized_path) from all '| method |' tables."""
+    in_table = False
+    sep_seen = False
+    endpoints = set()
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or not stripped.startswith('|'):
+            continue
+        cells = parse_table_row(stripped)
+        if not cells:
+            continue
+        if cells[0].lower() == 'method':
+            in_table = True
+            sep_seen = False
+            continue
+        if not in_table:
+            continue
+        if not sep_seen and is_separator_row(cells):
+            sep_seen = True
+            continue
+        if len(cells) < 2 or not any(cells):
+            continue
+        method = cells[0].upper()
+        path = cells[1]
+        if method not in VALID_METHODS or not path.startswith('/'):
+            continue
+        endpoints.add((method, normalize_path(path)))
+    return endpoints
+
+
+# ── path normalization ────────────────────────────────────────────────────────
+
+PARAM_PATTERNS = [
+    re.compile(r'\$\{[^}/]*\}'),             # ${id}          (js template literal) — before {id}
+    re.compile(r':[A-Za-z_][\w]*'),          # :id            (express/rails)
+    re.compile(r'\{[^}/]*\}'),               # {id}           (flask/fastapi/spring)
+    re.compile(r'<[^>/]*>'),                 # <int:id>       (django/flask)
+    re.compile(r'\*\*?'),                    # wildcard segments
+]
+
+
+def normalize_path(path: str) -> str:
+    """Collapse route params and template interpolations to a single token so
+    `/users/:id`, `/users/{id}`, and `/users/${x}` all compare equal."""
+    # strip query string / hash
+    path = path.split('?', 1)[0].split('#', 1)[0]
+    for pat in PARAM_PATTERNS:
+        path = pat.sub('{}', path)
+    # template literal leftovers like /users/`+id+`  -> treat remainder as param
+    path = re.sub(r'`.*$', '{}', path)
+    if not path.startswith('/'):
+        path = '/' + path
+    if len(path) > 1:
+        path = path.rstrip('/')
+    # collapse duplicate slashes
+    path = re.sub(r'/{2,}', '/', path)
+    return path
+
+
+def matches_ignore(path: str, ignore_list: list) -> bool:
+    for ig in ignore_list:
+        ig_norm = normalize_path(ig.rstrip('*'))
+        if ig.endswith('*'):
+            if path == ig_norm or path.startswith(ig_norm.rstrip('/') + '/') or path.startswith(ig_norm):
+                return True
+        elif path == normalize_path(ig):
+            return True
+    return False
+
+
+def under_api_prefix(path: str, prefixes: list) -> bool:
+    if not prefixes:
+        return True
+    for p in prefixes:
+        pn = normalize_path(p)
+        if path == pn or path.startswith(pn.rstrip('/') + '/'):
+            return True
+    return False
+
+
+# ── source scanning ────────────────────────────────────────────────────────────
+
+# Backend route patterns grouped by language. Only the patterns for a file's
+# extension are applied to it, so a Python Flask/Django pattern can never match a
+# PHP or JS file (cross-language false matches were polluting results, e.g. the
+# Flask route regex firing on a Laravel `Route::match` line).
+_JS_BACKEND = [
+    # Express / Koa / Fastify: app.get('/x'), router.post("/x").
+    # Client idioms (api/http/client/request/...) are intentionally excluded —
+    # those are frontend calls, not server routes; counting them as backend
+    # would silently satisfy `contractEndpointNotImplemented`.
+    (re.compile(r'\b(?:app|router|server|fastify|route|routes)\.(get|post|put|delete|patch|options|head|all)\s*\(\s*[\'"`]([^\'"`]+)[\'"`]', re.I), 'verb_first'),
+]
+
+# NestJS: @Controller('users') class prefix + @Get(':id') method decorators.
+# Handled by a dedicated two-pass scanner (scan_nestjs) since the route path is
+# the join of the controller prefix and the per-method decorator argument.
+NEST_CONTROLLER_RE = re.compile(r'@Controller\s*\(\s*[\'"`]?([^\'"`)]*)[\'"`]?\s*\)', re.I)
+NEST_METHOD_RE = re.compile(r'@(Get|Post|Put|Delete|Patch|Options|Head|All)\s*\(\s*[\'"`]?([^\'"`)]*)[\'"`]?\s*\)', re.I)
+_PY_BACKEND = [
+    # FastAPI / APIRouter decorators: @app.get("/x"), @router.post('/x')
+    (re.compile(r'@(?:app|router|\w+)\.(get|post|put|delete|patch|options|head)\s*\(\s*[\'"]([^\'"]+)[\'"]', re.I), 'verb_first'),
+    # Flask: @app.route("/x", methods=["POST"])  (methods captured separately below)
+    (re.compile(r'@(?:app|bp|blueprint|\w+)\.route\s*\(\s*[\'"]([^\'"]+)[\'"]([^)]*)', re.I), 'flask_route'),
+    # Django urls: path("x/", ...)  re_path(r"^x/$", ...)
+    (re.compile(r'\b(?:path|re_path|url)\s*\(\s*r?[\'"]([^\'"]+)[\'"]', re.I), 'path_only'),
+]
+_JAVA_BACKEND = [
+    # Spring: @GetMapping("/x")
+    (re.compile(r'@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?[\'"]([^\'"]+)[\'"]', re.I), 'verb_first'),
+    # Spring: @RequestMapping(value="/x", method=RequestMethod.POST) — method (if
+    # present) is parsed from the call tail so method drift is not wildcarded.
+    (re.compile(r'@RequestMapping\s*\(\s*(?:value\s*=\s*)?[\'"]([^\'"]+)[\'"]([^)]*)', re.I), 'spring_request_mapping'),
+]
+_GO_BACKEND = [
+    # chi/gin/echo/mux: r.Get("/x", ...) router.POST("/x", ...) mux.HandleFunc("/x", ...)
+    (re.compile(r'\b\w+\.(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s*\(\s*"([^"]+)"', re.I), 'verb_first'),
+    (re.compile(r'\b\w+\.HandleFunc\s*\(\s*"([^"]+)"', re.I), 'path_only'),
+]
+_PHP_BACKEND = [
+    # Laravel verb form: Route::get('/x', ...)
+    (re.compile(r'\bRoute::(get|post|put|delete|patch|options|any)\s*\(\s*[\'"]([^\'"]+)[\'"]', re.I), 'verb_first'),
+    # Laravel array form: Route::match(['get','post'], '/x', ...)
+    (re.compile(r'\bRoute::match\s*\(\s*\[([^\]]*)\]\s*,\s*[\'"]([^\'"]+)[\'"]', re.I), 'laravel_match'),
+]
+
+BACKEND_PATTERNS_BY_EXT = {
+    '.js': _JS_BACKEND, '.jsx': _JS_BACKEND, '.mjs': _JS_BACKEND, '.cjs': _JS_BACKEND,
+    '.ts': _JS_BACKEND, '.tsx': _JS_BACKEND,
+    '.py': _PY_BACKEND,
+    '.java': _JAVA_BACKEND,
+    '.go': _GO_BACKEND,
+    '.php': _PHP_BACKEND,
+}
+
+FLASK_METHODS_RE = re.compile(r'methods\s*=\s*\[([^\]]*)\]', re.I)
+SPRING_METHOD_RE = re.compile(r'method\s*=\s*\{?([^)}]*)', re.I)
+
+# Frontend HTTP calls -> list of (method_or_None, raw_path). Only scanned in
+# files with a frontend extension. The path capture allows ${...} template
+# params (normalize_path collapses them) but stops at the closing quote/backtick,
+# a paren, or whitespace.
+_FE_PATH = r"([^`'\")\s]+)"
+_FE_EXTS = {'.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.vue', '.svelte'}
+FRONTEND_PATTERNS = [
+    # axios.get('/x'), ky.post(`/x`), http.put("/x"), $http.delete('/x'), client.patch('/x')
+    (re.compile(r'\b(?:axios|ky|http|\$http|api|client|request|httpClient|fetcher)\.(get|post|put|delete|patch|head|options)\s*\(\s*[`\'"]' + _FE_PATH, re.I), 'verb_first'),
+    # fetch('/x', { method: 'POST' })  — method parsed from the options object below
+    (re.compile(r'\bfetch\s*\(\s*[`\'"]' + _FE_PATH, re.I), 'fetch'),
+    # axios({ url: '/x', method: 'post' }) — method parsed from a nearby window so
+    # config-object method drift is caught instead of wildcarded.
+    (re.compile(r'\burl\s*:\s*[`\'"]' + _FE_PATH, re.I), 'config_object'),
+    # useFetch('/x') / useSWR('/x') — no method on the call site; method-agnostic.
+    (re.compile(r'\b(?:useFetch|useSWR|useQuery)\s*\(\s*[`\'"]' + _FE_PATH, re.I), 'path_only'),
+]
+
+# Look a short window on EITHER side of a config-object `url:` for `method:`
+# (the key order in axios({ method, url }) is not fixed).
+OBJECT_METHOD_RE = re.compile(r'method\s*:\s*[`\'"](\w+)[`\'"]', re.I)
+OBJECT_METHOD_WINDOW = 200
+
+
+def iter_source_files(roots, exts, exclude_dirs):
+    seen = set()
+    excl = set(exclude_dirs)
+    for root in roots:
+        if not os.path.isdir(root):
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in excl and not d.startswith('.')]
+            for fn in filenames:
+                ext = os.path.splitext(fn)[1]
+                if ext not in exts:
+                    continue
+                full = os.path.join(dirpath, fn)
+                if full in seen:
+                    continue
+                seen.add(full)
+                yield full
+
+
+def looks_like_test(path: str) -> bool:
+    base = os.path.basename(path).lower()
+    return ('.test.' in base or '.spec.' in base or base.startswith('test_')
+            or '/tests/' in path.replace('\\', '/') or '/__tests__/' in path.replace('\\', '/'))
+
+
+def _join_route(prefix: str, suffix: str) -> str:
+    parts = [p.strip('/') for p in (prefix, suffix) if p and p.strip('/')]
+    return normalize_path('/' + '/'.join(parts)) if parts else normalize_path('/')
+
+
+def scan_nestjs(text: str):
+    """Yield (METHOD, normalized_path) for NestJS controllers in one file.
+
+    Each method decorator's path is joined with the nearest preceding
+    @Controller(prefix). This is the documented NestJS shape; it deliberately
+    does not try to resolve dynamic prefixes or RouterModule registrations."""
+    controllers = [(m.start(), m.group(1) or '') for m in NEST_CONTROLLER_RE.finditer(text)]
+    if not controllers:
+        return
+    for mm in NEST_METHOD_RE.finditer(text):
+        prefix = ''
+        for pos, pfx in controllers:
+            if pos < mm.start():
+                prefix = pfx
+            else:
+                break
+        method = mm.group(1).upper()
+        method = 'ANY' if method == 'ALL' else method
+        yield (method, _join_route(prefix, mm.group(2) or ''))
+
+
+def scan_backend(roots, exts, exclude_dirs):
+    """Return set of (METHOD, normalized_path). METHOD may be 'ANY'."""
+    routes = set()
+    for path in iter_source_files(roots, exts, exclude_dirs):
+        if looks_like_test(path):
+            continue
+        ext = os.path.splitext(path)[1].lower()
+        patterns = BACKEND_PATTERNS_BY_EXT.get(ext)
+        if not patterns:
+            continue
+        try:
+            text = Path(path).read_text(encoding='utf-8', errors='ignore')
+        except OSError:
+            continue
+        if ext in ('.ts', '.tsx', '.js', '.mjs', '.cjs'):
+            routes.update(scan_nestjs(text))
+        for pat, kind in patterns:
+            for m in pat.finditer(text):
+                if kind == 'verb_first':
+                    method = m.group(1).upper()
+                    raw = m.group(2)
+                    method = 'ANY' if method == 'ALL' else method
+                    routes.add((method, normalize_path(raw)))
+                elif kind == 'flask_route':
+                    raw = m.group(1)
+                    tail = m.group(2) or ''
+                    mm = FLASK_METHODS_RE.search(tail)
+                    if mm:
+                        for meth in re.findall(r'[A-Za-z]+', mm.group(1)):
+                            if meth.upper() in VALID_METHODS:
+                                routes.add((meth.upper(), normalize_path(raw)))
+                    else:
+                        routes.add(('GET', normalize_path(raw)))
+                elif kind == 'path_only':
+                    routes.add(('ANY', normalize_path(m.group(1))))
+                elif kind == 'laravel_match':
+                    methods_raw = m.group(1)
+                    raw = m.group(2)
+                    found = [meth.upper() for meth in re.findall(r'[A-Za-z]+', methods_raw)
+                             if meth.upper() in VALID_METHODS]
+                    for meth in (found or ['ANY']):
+                        routes.add((meth, normalize_path(raw)))
+                elif kind == 'spring_request_mapping':
+                    raw = m.group(1)
+                    tail = m.group(2) or ''
+                    mm = SPRING_METHOD_RE.search(tail)
+                    methods = []
+                    if mm:
+                        # method=RequestMethod.POST  or  method={RequestMethod.GET, RequestMethod.POST}
+                        methods = [tok.upper() for tok in re.findall(r'[A-Za-z]+', mm.group(1))
+                                   if tok.upper() in VALID_METHODS]
+                    for meth in (methods or ['ANY']):
+                        routes.add((meth, normalize_path(raw)))
+    return routes
+
+
+def scan_frontend(roots, exts, exclude_dirs):
+    calls = set()
+    for path in iter_source_files(roots, exts, exclude_dirs):
+        if looks_like_test(path):
+            continue
+        if os.path.splitext(path)[1].lower() not in _FE_EXTS:
+            continue
+        try:
+            text = Path(path).read_text(encoding='utf-8', errors='ignore')
+        except OSError:
+            continue
+        for pat, kind in FRONTEND_PATTERNS:
+            for m in pat.finditer(text):
+                if kind == 'verb_first':
+                    method = m.group(1).upper()
+                    raw = m.group(2)
+                elif kind == 'fetch':
+                    raw = m.group(1)
+                    # Per the fetch spec the default method is GET; look a short
+                    # window past the URL for an explicit `method:` so method
+                    # drift (e.g. DELETE on a GET-only endpoint) is caught.
+                    window = text[m.end():m.end() + OBJECT_METHOD_WINDOW]
+                    mm = OBJECT_METHOD_RE.search(window)
+                    method = mm.group(1).upper() if mm else 'GET'
+                elif kind == 'config_object':
+                    raw = m.group(1)
+                    # axios({ url, method }) — key order is not fixed, so scan a
+                    # window on both sides of the url: token for method:.
+                    lo = max(0, m.start() - OBJECT_METHOD_WINDOW)
+                    window = text[lo:m.end() + OBJECT_METHOD_WINDOW]
+                    mm = OBJECT_METHOD_RE.search(window)
+                    method = mm.group(1).upper() if mm else 'ANY'
+                else:  # path_only
+                    method = 'ANY'
+                    raw = m.group(1)
+                if not raw.startswith('/'):
+                    continue  # skip absolute URLs / relative non-rooted strings
+                calls.add((method, normalize_path(raw)))
+    return calls
+
+
+# ── contract matching ──────────────────────────────────────────────────────────
+
+def contract_has(method: str, path: str, contract: set) -> bool:
+    """A code endpoint conforms if some entry matches the path and the method
+    matches OR *either* side is method-agnostic ('ANY'). Path-only declarations
+    (Go HandleFunc, Django path(), Spring @RequestMapping) register as 'ANY' and
+    must therefore satisfy a concrete contract method, and vice versa."""
+    for c_method, c_path in contract:
+        if c_path != path:
+            continue
+        if method == 'ANY' or c_method == 'ANY' or c_method == method:
+            return True
+    return False
+
+
+def load_config():
+    cfg = dict(DEFAULT_CONFIG)
+    if not CONFIG_PATH.exists():
+        return cfg, False
+    try:
+        user = json.loads(CONFIG_PATH.read_text(encoding='utf-8'))
+    except (OSError, ValueError) as e:
+        print(f'API conformance: .cdd/conformance.json is not valid JSON: {e}')
+        sys.exit(1)
+    cfg.update({k: v for k, v in user.items() if k != 'checks'})
+    if isinstance(user.get('checks'), dict):
+        merged = dict(DEFAULT_CONFIG['checks'])
+        merged.update(user['checks'])
+        cfg['checks'] = merged
+    return cfg, True
+
+
+def resolve_roots(cfg):
+    roots = cfg.get('sourceRoots') or []
+    if roots:
+        return [r for r in roots if os.path.isdir(r)]
+    return [r for r in AUTO_ROOTS if os.path.isdir(r)]
+
+
+def severity(check_name, cfg):
+    sev = cfg['checks'].get(check_name, 'error')
+    if cfg.get('strict') and sev == 'warning':
+        return 'error'
+    return sev
+
+
+def main() -> None:
+    cfg, present = load_config()
+
+    if not present:
+        print('API conformance: skipped (no .cdd/conformance.json; '
+              'add one with "enabled": true to enforce code-vs-contract checks).')
+        sys.exit(0)
+    if not cfg.get('enabled'):
+        print('API conformance: skipped (.cdd/conformance.json has "enabled": false).')
+        sys.exit(0)
+
+    if not CONTRACT_PATH.exists():
+        print(f'API conformance: contract not found: {CONTRACT_PATH}')
+        sys.exit(1)
+
+    body = strip_frontmatter(CONTRACT_PATH.read_text(encoding='utf-8', errors='ignore'))
+    contract = find_contract_endpoints(body.splitlines())
+    if not contract:
+        print('API conformance: no endpoint table found in contract; nothing to check.')
+        sys.exit(0)
+
+    roots = resolve_roots(cfg)
+    if not roots:
+        # Enabled but nothing to scan almost always means a mistyped/missing
+        # sourceRoots. Failing (not exit 0) prevents a config mistake from
+        # silently disabling the drift net while the gate stays green.
+        print('API conformance validation failed:')
+        print('  conformance is enabled but no source roots were found to scan; '
+              'set "sourceRoots" in .cdd/conformance.json to existing directories.')
+        sys.exit(1)
+
+    exclude = cfg['excludeDirs']
+    ignore = cfg['ignorePaths']
+    prefixes = cfg['apiPrefixes']
+
+    backend = scan_backend(roots, set(cfg['backendGlobsExt']), exclude)
+    frontend = scan_frontend(roots, set(cfg['frontendGlobsExt']), exclude)
+
+    errors = []
+    warnings = []
+
+    def emit(check_name, message):
+        (errors if severity(check_name, cfg) == 'error' else warnings).append(message)
+
+    # 1. Backend routes that are not documented in the contract.
+    for method, path in sorted(backend):
+        if matches_ignore(path, ignore):
+            continue
+        if not under_api_prefix(path, prefixes):
+            continue
+        if not contract_has(method, path, contract):
+            emit('backendRouteNotInContract',
+                 f'backend route {method} {path} is not in the API contract')
+
+    # 2. Contract endpoints with no backend implementation found.
+    for method, path in sorted(contract):
+        if matches_ignore(path, ignore):
+            continue
+        if not contract_has(method, path, backend):
+            emit('contractEndpointNotImplemented',
+                 f'contract endpoint {method} {path} has no backend route in scanned source')
+
+    # 3. Frontend calls to paths not in the contract (the FE/BE drift case).
+    for method, path in sorted(frontend):
+        if matches_ignore(path, ignore):
+            continue
+        if not under_api_prefix(path, prefixes):
+            continue
+        if not contract_has(method, path, contract):
+            label = path if method == 'ANY' else f'{method} {path}'
+            emit('frontendCallNotInContract',
+                 f'frontend calls {label} which is not in the API contract')
+
+    print(f'API conformance: contract={len(contract)} endpoint(s), '
+          f'backend={len(backend)} route(s), frontend={len(frontend)} call(s) '
+          f'across roots: {", ".join(roots)}')
+
+    if warnings:
+        print('API conformance warnings:')
+        for w in warnings:
+            print(f'  {w}')
+
+    if errors:
+        print('API conformance validation failed:')
+        for e in errors:
+            print(f'  {e}')
+        sys.exit(1)
+
+    print('API conformance validation passed.')
+
+
+if __name__ == '__main__':
+    main()