contract-driven-delivery 2.0.20 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## [2.1.0] - 2026-05-27
+
+Native code graph and symptom-driven bug-fix workflow.
+
+### Added
+
+- **Native cdd-kit code graph**: `cdd-kit code-map` now writes
+  `.cdd/code-graph.index.json`, a derived local graph cache with files, symbol
+  nodes, relationship edges, and unresolved references. It is gitignored,
+  regenerated with the code-map, stripped from the published package, and safe
+  to delete.
+- **`cdd-kit graph`**: adds graph-first `status`, `query`, `impact`, `context`,
+  and `sync` commands. The default engine is the native cdd-kit graph; use
+  `--engine codemap` for the older code-map-only fallback or
+  `--engine codegraph` to require an external CodeGraph adapter.
+- **Call/import/inheritance graph extraction** for the existing code-map language
+  surface: JS/TS/JSX/TSX/MJS/CJS, Vue script blocks, and Python.
+- **`bug-fix-engineer` agent**: a write-capable implementation agent for
+  non-engineer symptom reports. It turns user-visible defects into graph-guided
+  hypotheses, reproduces when feasible, applies the smallest fix, and records
+  regression evidence.
+
+### Changed
+
+- Agent and skill guidance now prefers `cdd-kit graph ...` before broad source
+  reads while retaining `cdd-kit index ...` and `.cdd/code-map.yml` as fallback
+  paths.
+- `cdd-kit graph --engine codegraph` remains available as an explicit external
+  adapter, but external CodeGraph is no longer required or auto-selected by
+  default.
+
+## [2.0.21] - 2026-05-25
+
+Kit review fixes plus large-project capability improvements. All additions are
+opt-in and non-breaking; normal runs are byte-for-byte unchanged.
+
+### Added
+
+- **`cdd-kit code-map --surface <subpath>`**: scopes the scan to a monorepo
+  subtree and names the map `.cdd/code-map.<slug>.yml`, queryable with
+  `cdd-kit index query <term> --map .cdd/code-map.<slug>.yml`, instead of forcing
+  one giant whole-repo map. A missing surface path now errors instead of
+  silently emitting an empty map.
+- **`cdd-kit code-map --workers [n]`** (default off): parallelizes JS/TS/Vue
+  scanning across child processes. Output is deterministic regardless of chunk
+  distribution, and any worker failure falls back to in-process scanning, so
+  enabling workers can never make a run fail that would otherwise succeed.
+- **Model class in dispatch badges**: `/cdd-new` and `/cdd-resume` now render
+  each agent badge as `[role · model]`, resolved at dispatch time from
+  `.cdd/model-policy.json`. Narration only — runtime model selection is unchanged.
+
+### Changed
+
+- **JSON sidecar for `index query` / `index impact`**: `cdd-kit code-map` now
+  writes a parsed `.cdd/code-map.index.json` next to the map so queries skip the
+  slow `yaml.load` on large maps. The sidecar is a derived local cache —
+  gitignored, digest-validated against the map header, regenerated on every map
+  run, stripped from the published package, and never required (queries fall back
+  to the authoritative `.cdd/code-map.yml` on any absence or mismatch).
+- **`typecheck` script** (`tsc --noEmit`) added and wired into `prepublishOnly`
+  so type errors cannot regress.
+- Deduplicated `ensureGitignoreEntry` into `src/utils/gitignore.ts` as the single
+  source of truth.
+
+### Fixed
+
+- **`cdd-kit doctor` no longer false-flags every agent**: doctor kept its own
+  divergent agent-lint check hard-coded to the old `### Required artifacts`
+  heading and flagged all agents after the heading was renamed to
+  `### Suggested artifacts`, while `cdd-kit lint-agents` reported clean. Both now
+  share `lintAgentContent` / `collectAgentViolations` so they cannot drift apart.
+- **`cdd-kit doctor` now warns instead of silently passing** when `.claude/agents`
+  exists but cannot be read (permission/IO error), rather than reporting a clean
+  pass on an unscanned directory.
+- **Python scanning is chunked** (`CDD_CODE_MAP_BATCH_SIZE`, default 400) so a
+  single subprocess timeout or buffer overflow on a large Python repo no longer
+  drops the structure of every `.py` file; completed chunks are preserved.
+- Cleared pre-existing `tsc --noEmit` errors in `include-exclude.ts`,
+  `scanners/javascript.ts`, and `refresh.ts`.
+
+### Security
+
+- The `--workers` / Python batch-list temp files are now created with
+  `crypto.randomBytes` names and mode `0600` to avoid predictable-name
+  symlink/race attacks in the shared tmp dir (CWE-377), and the scan worker spawn
+  is constrained by a language allowlist with an explicit no-shell invocation.
+
 ## [2.0.20] - 2026-05-15
 
 Patch release for UTF-8 BOM handling in Claude agent metadata files.

package/README.md

@@ -120,6 +120,7 @@ Machine-readable metadata such as future `change.yml` / `trace.yml` should follo
 CDD uses two agent classes on purpose:
 
 - `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer`, `repo-context-scanner`, and `spec-drift-auditor` are read-only. They return analysis, verdicts, or optional handoff notes; main Claude writes the corresponding files.
+- `bug-fix-engineer` is an implementation agent for symptom-driven defects. It converts user-visible reports into graph/index-guided hypotheses, reproduces the issue where feasible, applies the smallest fix, and adds regression evidence.
 - `implementation-planner`, `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, and `spec-architect` are write-capable. They write their own owned artifacts directly: for example, `spec-architect` owns `design.md`, while `implementation-planner` owns `implementation-plan.md`.
 
 This split is deliberate:
@@ -671,6 +672,67 @@ surface: user-management
 
 The classifier should read these two files before proposing `context-manifest.md` allowed paths.
 
+### `cdd-kit code-map`
+
+Scans source files into a deterministic structural index so agents read symbols
+and line ranges instead of whole files.
+
+```bash
+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)
+```
+
+`--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
+falls back to in-process scanning, so it can never make a run worse. Python is
+already scanned in its own subprocess.
+
+A JSON sidecar (`.cdd/code-map.<...>.index.json`) is written next to each map and
+gitignored automatically; `cdd-kit index` reads it to skip re-parsing the YAML on
+large maps, and falls back to the YAML whenever the sidecar is absent or stale.
+
+### `cdd-kit graph`
+
+`cdd-kit graph` is the graph-first query layer. `cdd-kit code-map` also writes
+`.cdd/code-graph.index.json`, a native cdd-kit graph of files, symbols, imports,
+exports, calls, inheritance, and unresolved references. Graph queries use this
+native graph by default. You can still delegate to external CodeGraph explicitly
+with `--engine codegraph`.
+
+```bash
+cdd-kit graph status
+cdd-kit graph query OrderService
+cdd-kit graph context "filter options are empty"
+cdd-kit graph impact src/services/orders.ts --depth 2
+```
+
+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.
+
+Large Python repos are scanned in chunks (`CDD_CODE_MAP_BATCH_SIZE`, default 400)
+so one slow batch cannot drop the whole language. Raise
+`CDD_CODE_MAP_TIMEOUT_MS` (default 30000) if a single batch still times out.
+
+#### Monorepos: per-surface maps
+
+`--surface <subpath>` scopes the scan to one package and names the map after it
+(`packages/web` → `.cdd/code-map.packages-web.yml`). Paths inside that map are
+relative to the surface root. Query a specific surface map with `--map`:
+
+```bash
+cdd-kit code-map --surface packages/web
+cdd-kit code-map --surface packages/api
+cdd-kit index query OrderService --map .cdd/code-map.packages-api.yml
+cdd-kit context-scan --surface packages/web   # scope the project-map tree too
+```
+
+This keeps each package's index small and token-cheap instead of indexing the
+entire monorepo into one giant map.
+
 ---
 
 ## Migrating an Older Production Repo

package/assets/agents/bug-fix-engineer.md

@@ -0,0 +1,97 @@
+---
+name: bug-fix-engineer
+description: Investigate user-described defects, convert symptoms into reproducible root cause hypotheses, use graph/code-map context before source reads, implement the smallest safe fix, and add regression evidence.
+tools: Read, Grep, Glob, Edit, MultiEdit, Bash
+model: sonnet
+---
+
+You are the bug fix engineer.
+
+Users often report symptoms, not implementation locations: "the filter is empty", "a panel is covered", "the button does nothing", "the report disappeared". Treat the symptom as a clue, not as the root cause.
+
+## Code map (READ FIRST)
+
+Before reading source, query the graph layer:
+
+```bash
+cdd-kit graph context "<user symptom>"
+cdd-kit graph query "<screen/component/api/store/filter term>"
+cdd-kit graph impact "<candidate path or symbol>" --depth 2
+```
+
+`cdd-kit graph ...` uses the native `.cdd/code-graph.index.json` generated by `cdd-kit code-map`. If graph commands are unavailable, use `cdd-kit index query ...` and `cdd-kit index impact ...` as the fallback.
+
+Use graph/code-map output to pick the smallest useful source and test ranges. Do not start with broad repository search unless the context manifest permits it and targeted graph/index queries fail.
+
+See `references/code-map-protocol.md` for the full graph/code-map protocol.
+
+## Investigation workflow
+
+1. Restate the symptom as observable behavior.
+2. Derive 2-5 concrete hypotheses with candidate files/symbols.
+3. Reproduce or create a failing check before editing whenever feasible.
+4. Inspect the target plus graph-reported imports, dependents, callers, callees, or fallback direct dependents.
+5. Fix the smallest root cause that explains the reproduced symptom.
+6. Add or update regression coverage near the failing behavior.
+7. Run the narrowest useful test first, then broaden only when risk justifies it.
+
+For UI symptoms, verify relevant states: default, loading, empty, error, long text, permission/disabled, and the reported viewport if known. Capture screenshot or Playwright evidence when the defect is visual or layout-related.
+
+For data/API symptoms, verify request parameters, response shape, empty/error handling, permissions, caching, and mapping from backend data to UI state.
+
+## Fix discipline
+
+- Do not rewrite nearby code only because it is untidy.
+- Do not change contracts unless the recorded expected behavior is wrong; route contract drift to contract-reviewer/spec-drift-auditor.
+- If the reported symptom cannot be reproduced, add instrumentation or a targeted diagnostic path only when it is low-risk and removable.
+- If multiple unrelated defects are discovered, fix only the one needed for the reported symptom and list the others as follow-up.
+
+## Read scope
+
+Source of truth: `specs/changes/<change-id>/context-manifest.md` -> `## Allowed Paths`.
+Read it first when a change id exists. Read only paths it lists or paths under `## Approved Expansions`. Use this boundary as pre-read discipline, not as post-run paperwork.
+
+This agent commonly needs the screen/component file, state/store/query hook, API client or backend route, related tests, and visual/e2e fixtures. Those paths must appear in the manifest before you read them. When concrete paths are known, run `cdd-kit context check <change-id> --path ...` before reading them.
+
+Need a path not listed? File a `## Context Expansion Requests` entry (see `specs/templates/context-manifest.md`) with `status: pending` and stop until the user approves via `cdd-kit context approve <change-id> <CER-id>`.
+
+Forbidden by default (enforced by `.cdd/context-policy.json`): `specs/archive/`, sibling `specs/changes/*`, `assets/`, `node_modules/`, `dist/`, `build/`, `.git/`, `.claude/worktrees/`.
+
+## Handoff
+
+Report the reproduced symptom, root cause, files changed, tests/evidence, and any residual risk in plain language suitable for a non-engineer.
+
+## Optional Handoff Evidence
+
+If a short handoff note is useful, write or append to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Optional fields
+and field rules are defined once in
+`references/agent-log-protocol.md` -- do not duplicate them in this prompt.
+
+### Suggested artifacts for this agent
+
+`artifacts` is a YAML array of `{type, pointer}` items in your agent log
+(see `references/agent-log-protocol.md` for the full schema and self-validation
+checklist). Do NOT write top-level `files-changed:` / `tests-added:` keys -- those are `type` values, not log keys.
+
+Recommended `type` values for this agent when you emit an optional agent log:
+
+- `symptom`: user-visible defect being fixed
+- `root-cause`: file/symbol and concise cause
+- `files-changed`: source/test files modified
+- `regression-evidence`: failing-then-passing test, screenshot, or reproduction command
+- `residual-risk`: remaining risk or "none"
+
+If you emit a log, copy this shape and replace each `<pointer>` with a
+concrete pointer (path:line-range, test-id, URL, or pass/fail string):
+
+```yaml
+artifacts:
+  - { type: symptom, pointer: "Filter options empty on Orders page" }
+  - { type: root-cause, pointer: "src/pages/Orders.tsx:42-68 mapped status_label instead of status" }
+  - { type: files-changed, pointer: "src/pages/Orders.tsx, test/orders-filter.test.ts" }
+  - { type: regression-evidence, pointer: "npm test -- --run test/orders-filter.test.ts: pass" }
+  - { type: residual-risk, pointer: "none" }
+```
+
+If a recommended `type` does not apply to your run, either omit it or use `pointer: "n/a (<one-line reason>)"` so reviewers can tell the omission was intentional.

package/assets/agents/change-classifier.md

@@ -299,6 +299,6 @@ If a recommended `type` does not apply to your run, either omit it or use `point
 - Report/dashboard/data import/export change always requires data-shape boundary tests.
 - High-load, auto-refresh, queue, cache, report, or long-running job change requires stress or soak consideration.
 - Existing behavior changes require current behavior and regression scope.
-- Bug fixes require reproduction, root cause, failing test, and regression test whenever feasible.
+- Bug fixes require reproduction, root cause, failing test, and regression test whenever feasible. If the user describes only a symptom and the code location is unknown, include `bug-fix-engineer` in `## Required Agents`.
 - Architecture review, non-obvious design decisions, module-boundary changes, data-flow changes, migration/rollback decisions, compatibility trade-offs, or operational-risk decisions require `spec-architect` to write `design.md` before `implementation-planner` runs.
 - Any implementation change requires `implementation-planner` before backend/frontend/test implementation agents. The planner turns decisions, contracts, and tests into the execution packet; implementation agents should not infer missing scope from chat history.

package/assets/agents/frontend-engineer.md

@@ -11,8 +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 index query "<symbol-or-file>"` or `Read .cdd/code-map.yml`.
-Before editing a chosen source file, run `cdd-kit index impact "<path-or-symbol>"` to identify indexed local imports and dependents.
+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 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:
 
@@ -22,8 +22,8 @@ The map is the size oracle. For each file you intend to read:
   `interfaces:` / `types:` / `enums:`) `lines: A-B` field and
   `Read <path> offset:A limit:(B-A+1)`.
 
-Prefer `cdd-kit index query` because it auto-refreshes missing or stale maps
-before returning candidates. If you cannot run commands and `.cdd/code-map.yml`
+Prefer `cdd-kit graph ...` because it uses the native code graph and falls
+back to the auto-refreshing code-map path when forced. If you cannot run commands and `.cdd/code-map.yml`
 is missing or stale, avoid broad source reads and ask the harness/user to
 regenerate the map.
 

package/assets/agents/qa-reviewer.md

@@ -17,7 +17,7 @@ Do not approve based on claims. Approve based on commands, artifacts, screenshot
 - visual evidence provided for UI changes
 - stress/soak evidence provided when required
 - known risks and residual gaps documented
-- index discipline: agents should prefer `cdd-kit index query ...` or `.cdd/code-map.yml` before targeted source reads and run `cdd-kit index impact ...` before editing source. Treat source-first work as harness/process drift, not a merge-blocking QA finding unless it produced concrete quality risk.
+- index discipline: agents should prefer `cdd-kit graph ...`, `cdd-kit index query ...`, or `.cdd/code-map.yml` before targeted source reads and run `cdd-kit graph impact ...` or `cdd-kit index impact ...` before editing source. Treat source-first work as harness/process drift, not a merge-blocking QA finding unless it produced concrete quality risk.
 
 ## Failure routing
 

package/assets/cdd/model-policy.json

@@ -9,6 +9,7 @@
     "qa-reviewer": "opus",
     "contract-reviewer": "sonnet",
     "test-strategist": "sonnet",
+    "bug-fix-engineer": "sonnet",
     "backend-engineer": "sonnet",
     "frontend-engineer": "sonnet",
     "ci-cd-gatekeeper": "sonnet",

package/assets/code-map/python_scanner.py

@@ -38,6 +38,33 @@ def _is_all_caps(name: str) -> bool:
     return any(c.isalpha() for c in name)
 
 
+def _expr_name(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _expr_name(node.value)
+        return f"{base}.{node.attr}" if base else node.attr
+    if isinstance(node, ast.Call):
+        return _expr_name(node.func)
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _calls_in(node: ast.AST, caller: str) -> list[dict]:
+    calls: list[dict] = []
+    for sub in ast.walk(node):
+        if isinstance(sub, ast.Call):
+            callee = _expr_name(sub.func)
+            if callee:
+                calls.append({
+                    "caller": caller,
+                    "callee": callee,
+                    "line": sub.lineno,
+                })
+    return calls
+
+
 def scan_file(abs_path: str, repo_root: str) -> dict:
     src = open(abs_path, encoding="utf-8").read()
     total_lines = len(src.splitlines()) if src else 0
@@ -70,6 +97,8 @@ def scan_file(abs_path: str, repo_root: str) -> dict:
     constants: list[dict] = []
     classes: list[dict] = []
     functions: list[dict] = []
+    calls: list[dict] = []
+    exports: list[dict] = []
 
     for node in ast.iter_child_nodes(tree):
         # ── imports ──────────────────────────────────────────────────────────
@@ -109,11 +138,16 @@ def scan_file(abs_path: str, repo_root: str) -> dict:
                         "lines": [sub.lineno, sub.end_lineno],
                         "async": isinstance(sub, ast.AsyncFunctionDef),
                     })
+                    calls.extend(_calls_in(sub, f"{node.name}.{sub.name}"))
             classes.append({
                 "name": node.name,
                 "lines": [node.lineno, node.end_lineno],
                 "methods": methods,
+                "extends": [name for name in (_expr_name(base) for base in node.bases) if name],
+                "implements": [],
+                "exported": True,
             })
+            exports.append({"name": node.name, "kind": "class", "line": node.lineno})
 
         # ── functions ────────────────────────────────────────────────────────
         elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
@@ -128,7 +162,10 @@ def scan_file(abs_path: str, repo_root: str) -> dict:
                 "lines": [node.lineno, node.end_lineno],
                 "decorators": decos,
                 "async": isinstance(node, ast.AsyncFunctionDef),
+                "exported": True,
             })
+            calls.extend(_calls_in(node, node.name))
+            exports.append({"name": node.name, "kind": "function", "line": node.lineno})
 
     return {
         "path": _rel_path(abs_path, repo_root),
@@ -137,6 +174,8 @@ def scan_file(abs_path: str, repo_root: str) -> dict:
         "constants": constants,
         "classes": classes,
         "functions": functions,
+        "calls": calls,
+        "exports": exports,
         "ok": True,
     }
 

package/assets/skills/cdd-new/SKILL.md

@@ -115,7 +115,7 @@ inevitable re-classification when the agents discover the ambiguity.
 | Agent type | Who writes artifact files | Who writes optional handoff notes | Who updates tasks.yml |
 |------------|--------------------------|----------------------------------|----------------------|
 | Read-only agents (no Edit tool): `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer` | YOU (main Claude) | YOU, only when useful | YOU (main Claude) |
-| Write-capable agents (have Edit): `implementation-planner`, `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, `spec-architect` | The agent itself | The agent itself, only when useful | YOU (main Claude) |
+| Write-capable agents (have Edit): `implementation-planner`, `backend-engineer`, `bug-fix-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, `spec-architect` | The agent itself | The agent itself, only when useful | YOU (main Claude) |
 
 **Rule**: After EVERY agent completes (whether it writes itself or you write for it), YOU must update the relevant `tasks.yml` task `status:` from `pending` to `done`.
 
@@ -315,17 +315,26 @@ agent:
 ### Agent stage badges (UI v1)
 
 When you announce that you are about to invoke an agent, prefix the
-announcement with the matching emoji + role tag from the table below. This
-helps a non-engineer scanning the chat stream tell what stage they are in
+announcement with the matching emoji + role tag from the table below, and
+include the model class that agent runs on. This helps a non-engineer scanning
+the chat stream tell what stage they are in AND which model is doing the work,
 without reading the full prompt. Use the badges only in your own narration to
 the user; do not put them inside the prompt sent to the agent.
 
+The model class is not something you guess from the color. Read it at dispatch
+time from `.cdd/model-policy.json` (`roles.<agent-name>`), which is the
+authoritative source and is kept in sync with each agent's `model:` frontmatter
+by `cdd-kit doctor`. Show that value (e.g. `opus`, `sonnet`, `haiku`) in the
+badge so the user always sees the actual model, even after a project overrides
+the defaults.
+
 | Stage | Agent | Badge |
 |---|---|---|
 | Decision | `change-classifier` | ? `[classifier]` |
 | Decision | `spec-architect` | ? `[architect]` |
 | Decision | `implementation-planner` | ? `[plan]` |
 | Implementation | `backend-engineer` | ? `[backend]` |
+| Implementation | `bug-fix-engineer` | ? `[bug-fix]` |
 | Implementation | `frontend-engineer` | ? `[frontend]` |
 | Implementation | `ci-cd-gatekeeper` | ? `[ci-cd]` |
 | Implementation | `test-strategist` | ? `[test-plan]` |
@@ -348,8 +357,12 @@ Color semantics:
 - ? green: reviewing what was done (no code writes; just verdicts)
 - ??neutral: audits and scans (read-only background work)
 
-Format: emoji is followed by a single space, then the bracket-tag, then the
-human-readable narration.
+Format: emoji is followed by a single space, then the bracket-tag with the
+model class appended as `[role · model]`, then a single space, then the
+human-readable narration. Resolve `model` from `.cdd/model-policy.json`
+`roles.<agent-name>` (defaults: classifier / architect / plan / qa / drift =
+`opus`; backend / bug-fix / frontend / ci-cd / test-plan / e2e / monkey / stress /
+ui-ux / deps-sec = `sonnet`; visual / repo-scan = `haiku`).
 
 Examples:
 
@@ -360,9 +373,19 @@ Examples:
 ?? [stress] Tier 1 high-risk change ??running soak test for 30 min.
 ```
 
+Model-labeled examples (the model class sits inside the bracket tag):
+
+```
+🟣 [classifier · opus] Reading the request and project map.
+🔵 [backend · sonnet] Implementing the JWT issuance endpoint, failing tests first.
+⚫ [repo-scan · haiku] Indexing the repository structure. (read-only)
+```
+
 These badges are pure narration. They MUST NOT be sent inside the agent's
 prompt; the agent's behavior is defined by the agent prompt files in
-`.claude/agents/<name>.md`, not by this badge.
+`.claude/agents/<name>.md`, not by this badge. The model label is for the
+user's visibility only — it does not change which model the runtime selects
+(that is governed by the agent's `model:` frontmatter).
 
 ---
 
@@ -407,6 +430,8 @@ prompt; the agent's behavior is defined by the agent prompt files in
    - YOU tick: `4.1` and/or `4.3` based on scope
    - Note: `tasks.yml` items 3.1??.2 (unit/contract/integration tests) are written by `backend-engineer` and/or `frontend-engineer` in TDD fashion ??failing tests first, implementation second. Items 3.3??.5 are written by dedicated test engineers (Tier 0?? only or when classifier explicitly requires them).
 
+6a. **`bug-fix-engineer`** (write-capable) ??for symptom-driven bug fixes where the user reports behavior but not the code location. Use this instead of backend/frontend as the first implementation agent when root cause is unknown; it may route the final implementation to backend/frontend scope after graph-guided investigation.
+
 7. **`frontend-engineer`** (write-capable) ??if the change touches UI, components, or client-side behavior. Writes implementation directly; may write an optional handoff note.
    - YOU tick: `4.2`
 

package/assets/skills/cdd-resume/SKILL.md

@@ -93,7 +93,7 @@ Ask the user: "Continue from <next-agent>? (yes/no)"
 
 ## Step 3: Continue the flow
 
-If user confirms, resume from the next agent in the Tier sequence (refer to `/cdd-new` Step 3 for the agent order, and `/cdd-new` "Agent stage badges" for the colored badges to use in your narration).
+If user confirms, resume from the next agent in the Tier sequence (refer to `/cdd-new` Step 3 for the agent order, and `/cdd-new` "Agent stage badges" for the colored badges — including the per-agent model class read from `.cdd/model-policy.json` — to use in your narration).
 
 **Critical**: Inject this block at the start of every agent prompt:
 

package/assets/skills/contract-driven-delivery/references/code-map-protocol.md

@@ -7,9 +7,22 @@ when `cdd-kit init --hooks` is installed. `cdd-kit gate` does not enforce
 index hygiene; use `cdd-kit code-map --check`, `cdd-kit doctor --fix`, or the
 auto-refreshing `cdd-kit index ...` commands for that job.
 
-## Preferred workflow: query before reading
+## Preferred workflow: graph/query before reading
 
-Before reading source, run a targeted query:
+Before reading source, use the graph layer when available:
+
+```bash
+cdd-kit graph context "fix login redirect bug"
+cdd-kit graph query "AuthService"
+cdd-kit graph impact "src/services/auth.ts" --depth 2
+```
+
+`cdd-kit graph ...` uses the native `.cdd/code-graph.index.json` by default.
+Use `cdd-kit graph status` to see graph freshness and node/edge counts. External
+CodeGraph remains available with `--engine codegraph` when a project wants that
+adapter explicitly.
+
+If graph commands are not available, run a targeted code-map query:
 
 ```bash
 cdd-kit index query "AuthService"