contract-driven-delivery 2.0.19 → 2.0.21

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## [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.
+
+### Fixed
+
+- Removed UTF-8 BOM bytes from packaged Claude agent and skill sources so YAML
+  frontmatter starts at `---` and Claude Code can mount subagents reliably.
+- `cdd-kit lint-agents` now rejects agent files that start with `U+FEFF`, since
+  frontmatter parsers may otherwise treat the first key as invalid.
+- Added package-source and generated-assets regression coverage to prevent BOM
+  bytes from being shipped again.
+
 ## [2.0.19] - 2026-05-15
 
 Design ownership patch for the implementation-planning flow.

package/README.md

@@ -1,4 +1,4 @@
-# Contract-Driven Delivery Kit
+# Contract-Driven Delivery Kit
 
 **cdd-kit** is a contract-driven delivery kit for AI coding agents. It started with Claude Code skills and now keeps the core workflow provider-neutral: contracts-first, test-first, spec-first. Every change goes through classification, contract review, TDD, implementation, and gate verification, with deterministic context indexes to keep agent work targeted.
 
@@ -671,6 +671,48 @@ 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.
+
+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/backend-engineer.md

@@ -1,4 +1,4 @@
----
+---
 name: backend-engineer
 description: Implement backend changes only after specs, contracts, tests, and CI gates are defined; maintain thin controllers, service boundaries, validation, and error handling.
 tools: Read, Grep, Glob, Edit, MultiEdit, Bash

package/assets/agents/change-classifier.md

@@ -1,4 +1,4 @@
----
+---
 name: change-classifier
 description: Classify incoming requests into change types and decide required artifacts, contracts, tests, and review gates before implementation.
 tools: Read, Grep, Glob

package/assets/agents/ci-cd-gatekeeper.md

@@ -1,4 +1,4 @@
----
+---
 name: ci-cd-gatekeeper
 description: Enforce CI/CD as a required delivery artifact; design and implement required, informational, nightly, weekly, and manual gates with promotion policy.
 tools: Read, Grep, Glob, Edit, MultiEdit, Bash

package/assets/agents/contract-reviewer.md

@@ -1,4 +1,4 @@
----
+---
 name: contract-reviewer
 description: Review and maintain API, CSS/UI, env, data-shape, business-rule, and CI/CD contracts for every change. Dependency and migration contracts are recorded here at contract level only; the active audit lives in dependency-security-reviewer.
 tools: Read, Grep, Glob

package/assets/agents/dependency-security-reviewer.md

@@ -1,4 +1,4 @@
----
+---
 name: dependency-security-reviewer
 description: Reviews dependency CVE risk, license compliance (GPL/AGPL copyleft vs proprietary), lockfile changes, and database migrations whenever lockfiles, dependency manifests, or database migrations are touched.
 tools: Read, Grep, Glob, Bash

package/assets/agents/e2e-resilience-engineer.md

@@ -1,4 +1,4 @@
----
+---
 name: e2e-resilience-engineer
 description: Design and implement E2E, browser-behavior, failure-injection, data-boundary, and resilience tests for production-like user journeys.
 tools: Read, Grep, Glob, Edit, MultiEdit, Bash

package/assets/agents/frontend-engineer.md

@@ -1,4 +1,4 @@
----
+---
 name: frontend-engineer
 description: Implement frontend changes under API, CSS, UI/UX, accessibility, E2E, and visual review contracts.
 tools: Read, Grep, Glob, Edit, MultiEdit, Bash

package/assets/agents/monkey-test-engineer.md

@@ -1,4 +1,4 @@
----
+---
 name: monkey-test-engineer
 description: Design preventive specs and structured exploratory tests for invalid user operations, adversarial inputs, malformed data, rapid UI actions, and production misuse. Not random fuzzing -- every monkey scenario is mapped to a known failure mode or hardening goal.
 tools: Read, Grep, Glob, Edit, MultiEdit, Bash

package/assets/agents/qa-reviewer.md

@@ -1,4 +1,4 @@
----
+---
 name: qa-reviewer
 description: Execute quality gates, verify evidence, route failures back to the correct agent, and decide release readiness.
 tools: Read, Grep, Glob, Bash

package/assets/agents/repo-context-scanner.md

@@ -1,4 +1,4 @@
----
+---
 name: repo-context-scanner
 description: Scan a repository and summarize its project profile, commands, contracts, tests, CI/CD, and missing standardization surfaces.
 tools: Read, Grep, Glob, Bash

package/assets/agents/spec-architect.md

@@ -1,4 +1,4 @@
----
+---
 name: spec-architect
 description: Evaluate architectural impact, compatibility, data flow, module boundaries, and whether a change requires ADR-like design decisions. Author ADRs when required.
 tools: Read, Grep, Glob, Edit, MultiEdit

package/assets/agents/spec-drift-auditor.md

@@ -1,4 +1,4 @@
----
+---
 name: spec-drift-auditor
 description: Audit drift between live contracts, implementation code, tests, and CI gates. Does NOT read historical specs/changes ??contracts/ is the single source of truth.
 tools: Read, Grep, Glob, Bash

package/assets/agents/stress-soak-engineer.md

@@ -1,4 +1,4 @@
----
+---
 name: stress-soak-engineer
 description: Design stress, load, soak, and long-running stability tests for reporting systems, queues, caches, auto-refresh, and data-heavy features.
 tools: Read, Grep, Glob, Edit, MultiEdit, Bash

package/assets/agents/test-strategist.md

@@ -1,4 +1,4 @@
----
+---
 name: test-strategist
 description: Convert specs and acceptance criteria into TDD-oriented test plans covering unit, contract, integration, E2E, resilience, monkey, stress, and soak tests.
 tools: Read, Grep, Glob, Edit, Write

package/assets/agents/ui-ux-reviewer.md

@@ -1,4 +1,4 @@
----
+---
 name: ui-ux-reviewer
 description: Review interaction design, information hierarchy, copy, accessibility, empty/error/loading state semantics, and user journey quality. Does not cover pixel-level visuals or CSS -- those go to visual-reviewer.
 tools: Read, Grep, Glob

package/assets/agents/visual-reviewer.md

@@ -1,4 +1,4 @@
----
+---
 name: visual-reviewer
 description: Review pixel-level visual output, layout, responsive viewport behavior, screenshot diffs, CSS contract compliance, and component visual state coverage. Does not cover interaction or copy -- those go to ui-ux-reviewer.
 tools: Read, Grep, Glob, Bash

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

@@ -1,4 +1,4 @@
----
+---
 name: cdd-new
 description: Start a new tracked change. Scaffolds all required artifacts, classifies the change by risk tier, commissions the right agents in order, and runs cdd-kit gate. Args: <change description in natural language>
 ---
@@ -315,11 +315,19 @@ 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]` |
@@ -348,8 +356,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 / frontend / ci-cd / test-plan / e2e / monkey / stress /
+ui-ux / deps-sec = `sonnet`; visual / repo-scan = `haiku`).
 
 Examples:
 
@@ -360,9 +372,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).
 
 ---
 

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: