contract-driven-delivery 2.0.3 → 2.0.8

package/CHANGELOG.md

@@ -1,5 +1,289 @@
 # Changelog
 
+## [2.0.8] - 2026-05-04
+
+Adds `cdd-kit refresh` — a one-shot complete upgrade command. The previous
+upgrade flow (`update --yes` + `upgrade --yes`) only touched `~/.claude/`
+and added missing project files; kit-shipped templates that the user already
+had on disk were never refreshed, leaving them stale across releases.
+
+### Added
+
+- **`cdd-kit refresh [--yes]`**: composes `update` + `upgrade` and adds
+  force-refresh for kit-owned templates with automatic timestamped backup.
+  Six steps, each independently skippable:
+  1. `~/.claude/agents` and `~/.claude/skills/contract-driven-delivery`
+     (delegates to `cdd-kit update`)
+  2. Add missing project files (delegates to `cdd-kit upgrade`)
+  3. **Force-refresh kit templates** with backup to
+     `.cdd/.refresh-backup/<timestamp>/`. Targets:
+     `specs/templates/`, `tests/templates/`, `ci-templates/`,
+     `.github/workflows/contract-driven-gates.yml`.
+  4. Re-install pre-commit hook if `.cdd/.hooks-installed` marker exists.
+  5. Resync `.cdd/model-policy.json` roles map from
+     `~/.claude/agents/<name>.md` `model:` frontmatter (drift detector).
+  6. Regenerate `.cdd/code-map.yml`.
+
+  Flags to skip individual steps: `--no-templates`, `--no-hooks`,
+  `--no-code-map`, `--no-update`, `--no-upgrade`. Default is dry-run; pass
+  `--yes` to apply.
+
+- **`.cdd/.hooks-installed` marker**: written by `cdd-kit init --hooks`.
+  Travels in the repo. Lets `cdd-kit refresh` know whether to re-install
+  the pre-commit hook on every refresh — so the hook stays in sync with
+  the latest kit version automatically.
+
+### Fixed
+
+- **Pre-commit hook extension list**: `installCodeMapHook` now triggers
+  on `.py / .js / .jsx / .mjs / .cjs / .ts / .tsx / .vue` (was: `.py / .js / .vue`).
+  Mirrors `BUILTIN_INCLUDE` and the 2.0.7 qa-reviewer fix.
+
+### Boundaries (locked)
+
+`cdd-kit refresh` will **never** touch:
+- `contracts/`, `specs/changes/`, `specs/archive/`
+- `src/`, `tests/*` (except `tests/templates/`)
+- `.cdd/code-map-config.yml`, `.cdd/context-policy.json`
+- `CLAUDE.md`, `AGENTS.md`, `CODEX.md`
+- `package.json`, `.git/` (except `.git/hooks/pre-commit` when marker exists),
+  `node_modules/`, `dist/`, `build/`
+
+### Migration
+
+Existing 2.0.x projects: `npm install -g contract-driven-delivery@latest`
+then `cdd-kit refresh --yes`. The first refresh will surface any drift
+that accumulated across 2.0.3 → 2.0.7 — backups land in
+`.cdd/.refresh-backup/<timestamp>/` so rolling back any specific change
+is a single `cp` away.
+
+To use the auto-refreshing pre-commit hook on every push:
+1. `cdd-kit init --hooks` (writes the marker)
+2. From now on, `cdd-kit refresh --yes` will re-install the hook every time.
+
+## [2.0.7] - 2026-05-04
+
+Comprehensive cross-consistency audit fixes. Targets the #1 root cause of
+agent ↔ gate friction: prompts that teach a format the gate cannot recognize.
+All 12 drifts surfaced by an opus-model audit are addressed; new gate
+enforcement is added where prompts described policy that was previously
+documented-only.
+
+### Fixed (BLOCKING)
+
+- **CER pending detection**: gate now correctly recognises Context Expansion
+  Requests written by `cdd-kit context request`. Previously the regex
+  required `-` immediately before `status:`, but the canonical writer puts
+  `status:` on its own indented line — every real-world pending CER was
+  silently bypassed. Replaced with a per-block parser mirroring
+  `src/commands/context.ts`.
+- **`pointer: "n/a (...)"` false rejection**: gate skips path-existence checks
+  for pointers starting with `n/a` (case-insensitive). Previously, a natural
+  reason text like `"n/a (no contracts/ files touched)"` was treated as a
+  path because of the `/` and produced a spurious "artifact pointer not
+  found" error.
+- **Per-agent `model:` policy drift**: synced `.cdd/model-policy.json` with
+  the actual `model:` frontmatter on three agent prompts (spec-drift-auditor,
+  visual-reviewer, repo-context-scanner). `cdd-kit doctor` no longer emits
+  drift warnings for these three. Same fix applied to the doctor `--fix`
+  defaults so newly-initialized projects start in sync.
+- **4 review agents had no `## Read scope`**: dependency-security-reviewer,
+  spec-drift-auditor, ui-ux-reviewer, visual-reviewer now point at
+  `context-manifest.md → ## Allowed Paths`, matching the 10 already-scoped
+  agents. Each prompt also lists the agent's typical extra reads (lockfiles,
+  screenshots, contracts) so users know what to add to the manifest up
+  front.
+- **qa-reviewer code-map discipline check**: now lists the full extension set
+  `(.py, .js, .jsx, .mjs, .cjs, .ts, .tsx, .vue)` instead of the 2.0.5
+  three-extension subset that effectively disabled the check on TS-heavy
+  repos.
+
+### Fixed (RISK)
+
+- **`.cdd/code-map-config.yml` errors surface in gate / doctor**: a malformed
+  config no longer silently degrades to "greenfield". `freshness.ts` returns
+  a `config-error` status and gate emits a hard error; doctor reports it as
+  a warning.
+- **`next-action` validation tightened**: gate now rejects placeholder values
+  the agent-log-protocol already disallowed (`tbd`, `n/a`, `investigate`,
+  `unknown`, `todo`) — previously only `none` was rejected.
+- **Allowed-Paths glob grammar upgraded to picomatch**: patterns like
+  `src/**/*.ts`, `lib/{a,b}/**`, `?(...)` now match correctly. The previous
+  hand-rolled matcher only supported trailing `/**` and `/*`. Special
+  `specs/changes/*` exception preserved.
+- **Engineer agent prompts (`backend-engineer`, `frontend-engineer`) now
+  list `.mjs` and `.cjs`** in the code-map "READ FIRST" extension list,
+  matching `BUILTIN_INCLUDE` and `references/code-map-protocol.md`.
+- **`change-classification.md` template aligned with classifier output**:
+  added the `## Inferred Acceptance Criteria` and `## Tasks Not Applicable`
+  sections; renamed `## Required Test Families` → `## Required Tests` and
+  `## Assumptions / Clarifications` → `## Clarifications or Assumptions`
+  to match what `change-classifier` actually produces.
+- **`.claude/worktrees/` added to all agent forbidden lists** to match
+  `.cdd/context-policy.json` defaults (documentation drift only — runtime
+  behaviour was already correct).
+
+### Added
+
+- **Per-agent required-artifact-types enforcement**: gate now reads each
+  agent's prompt file (resolution: `<cwd>/.claude/agents/<name>.md` →
+  `~/.claude/agents/<name>.md`) and extracts the "Minimum required `type`
+  values" bullet list. Every listed type must appear at least once in the
+  agent log's `artifacts:` array (a `pointer: "n/a (<reason>)"` item still
+  counts as present — only type membership is checked). Missing types
+  produce an actionable error naming the agent and the missing types. When
+  no prompt file is found, the check is skipped (back-compat).
+
+### Migration
+
+- Existing 2.0.6 projects: `cdd-kit update --yes` to refresh the agent
+  prompts and `references/code-map-protocol.md`. Then re-run `cdd-kit code-map`.
+- Manifests using literal paths continue to work unchanged. Manifests using
+  the new picomatch grammar (`src/**/*.ts`) start working correctly.
+- The new per-agent required-types check may surface previously-silent
+  gaps. Each error message is actionable and tells you which type to add.
+
+## [2.0.6] - 2026-05-04
+
+### Added
+
+- TypeScript scanner for `cdd-kit code-map`: `.ts` and `.tsx` files are
+  now indexed alongside `.py` / `.js` / `.vue`. `.jsx` / `.mjs` / `.cjs`
+  also routed through the JS scanner. Real-world scan of a React 19 +
+  TS 5.9 frontend (137 files / 20,119 src lines) compresses to 1,675
+  map lines (12.0x) in ~140 ms.
+- New code-map schema fields for TS files: `interfaces:`, `types:`,
+  `enums:` — each entry carries `name`, `lines`, and an `# local`
+  annotation when the symbol is not exported. Enum entries also list
+  their members.
+- User-overridable `.cdd/code-map-config.yml`: optional file with
+  `include:` / `exclude:` glob lists. When set, each list REPLACES the
+  matching built-in default (replacement semantics keep the mental
+  model simple — copy the built-in list and edit it for partial
+  overrides). CLI `--include` / `--exclude` flags continue to stack on
+  top of whichever lists won. Schema errors produce a clear message
+  and a non-zero exit.
+- `lint-agents` Rule A is now stricter: parses the YAML inside each
+  agent prompt's `artifacts:` fence and rejects stray top-level keys
+  (e.g. a stray `pointer:` or `type:` sibling alongside `artifacts:`).
+  This catches the residual format drift that the runtime gate
+  already rejects but that previously slipped through prompt review.
+
+### Changed
+
+- `backend-engineer` and `frontend-engineer` agent prompts: the
+  `## Code map (READ FIRST)` section now lists `.ts` / `.tsx` /
+  `.jsx` as covered extensions and points agents at the new
+  `interfaces:` / `types:` / `enums:` sections for TS files.
+- `references/code-map-protocol.md` documents the TS schema additions
+  and the `.cdd/code-map-config.yml` override format.
+- Variable-declaration heuristic in the JS/TS scanner now treats an
+  uppercase const initialised by a `CallExpression` (e.g.
+  `const Button = forwardRef(...)`, `const X = memo(...)`) as a
+  function entry, so React HOC-wrapped components show up in the map.
+  Single-letter uppercase identifiers (`X`, `T`, `Y`) are no longer
+  classified as ALL_CAPS constants — they fall through to the
+  function-heuristic branch.
+
+### Fixed
+
+- `build.js` no longer ships `.cdd/code-map.yml` inside `assets/cdd/`.
+  The map is a per-repo runtime artifact; shipping a pre-built copy
+  caused fresh `cdd-kit init` repos to inherit a stale snapshot that
+  fooled freshness checks.
+
+### Migration
+
+- Existing 2.0.5 projects: nothing to do. The TS scanner activates
+  automatically on the next `cdd-kit code-map` run if `.ts` / `.tsx`
+  files are present. Re-run `cdd-kit code-map` to pick them up.
+- To customise scan scope: create `.cdd/code-map-config.yml`. Without
+  it, all built-in defaults apply.
+- `cdd-kit update --yes` to refresh agent prompts in `~/.claude/`.
+
+## [2.0.5] - 2026-05-04
+
+### Added
+
+- `cdd-kit code-map` subcommand: scans `.py`, `.js`, `.vue` source files
+  via per-language AST parsers and emits a deterministic structural index
+  at `.cdd/code-map.yml`. The map is committed to git and refreshed on
+  demand.
+- `cdd-kit init --hooks` (opt-in): installs a pre-commit hook that
+  regenerates `.cdd/code-map.yml` whenever staged changes touch source
+  files, then re-stages the map. Coexists with `cdd-kit install-hooks`.
+- `cdd-kit gate <change-id>` now hard-fails when any source file is
+  newer than `.cdd/code-map.yml`, naming up to 5 stale files. Emits a
+  warning (not error) when the map is missing but source files exist.
+- `cdd-kit doctor` reports code-map status (missing / stale / compression
+  ratio) and `doctor --fix` regenerates a stale map.
+- New skill reference doc:
+  `.claude/skills/contract-driven-delivery/references/code-map-protocol.md`
+  documenting the map format and the read-first protocol.
+
+### Changed
+
+- `backend-engineer` and `frontend-engineer` agent prompts now require
+  `Read .cdd/code-map.yml` BEFORE reading any source file. The 300-line
+  rule directs agents to use `Read offset:N limit:M` for files larger
+  than 300 lines, eliminating whole-file Reads of large modules.
+- `qa-reviewer` now flags any agent log whose `files-read` lists a
+  source file without listing `.cdd/code-map.yml` first.
+
+### Migration
+
+After upgrading existing projects:
+
+1. Run `cdd-kit code-map` once to create `.cdd/code-map.yml`. Commit it.
+2. (Optional but recommended) Run `cdd-kit init --hooks` to install the
+   auto-regenerate pre-commit hook.
+3. Run `cdd-kit update --yes` to refresh agent prompts in `~/.claude/`.
+
+Greenfield projects with no `.py`/`.js`/`.vue` files yet are unaffected.
+
+### Dependencies
+
+Added: `@babel/parser ^7.25.0`, `@vue/compiler-sfc ^3.4.0`,
+`picomatch ^4.0.2`. Python scanning shells out to the system `python3`
+or `python` interpreter (Python 3.9+); if neither is on PATH, `.py`
+files are skipped with a warning.
+
+## [2.0.4] - 2026-05-04
+
+### Fixed
+
+- All 16 agent prompts now describe the `Required artifacts` block as a
+  `{type, pointer}` YAML array (matching `src/schemas/agent-log.schema.ts`)
+  instead of a flat key list. Previously agents copied the prompt verbatim
+  and emitted top-level `files-changed:` / `tests-added:` keys, which
+  `cdd-kit gate` correctly rejected as `missing required artifacts`.
+- Removed duplicate `## Read scope` sections from 10 agents
+  (backend-engineer, frontend-engineer, qa-reviewer, contract-reviewer,
+  ci-cd-gatekeeper, spec-architect, test-strategist, e2e-resilience-engineer,
+  monkey-test-engineer, stress-soak-engineer).
+- Read scope in those 10 agents now points to
+  `specs/changes/<change-id>/context-manifest.md → ## Allowed Paths` as the
+  single source of truth (matching what `cdd-kit gate` already enforces),
+  and instructs agents to file a Context Expansion Request rather than
+  reading outside the manifest. Eliminates the most common
+  `read unauthorized path` gate failure.
+
+### Added
+
+- `cdd-kit lint-agents` subcommand: validates every `.claude/agents/*.md`
+  has the new artifacts shape, at most one `## Read scope`, a
+  `context-manifest.md` reference where applicable, and a pointer to
+  `references/agent-log-protocol.md`. Wired into `cdd-kit doctor`.
+- Optional `note:` field on tasks in `tasks.yml` (schema and template) for
+  recording per-task context without breaking the existing `pending |
+  done | skipped` status enum.
+
+### Migration
+
+No project-side migration required — the fix is to the bundled agent
+prompts. After upgrading run `cdd-kit update --yes` to refresh the agents
+in `~/.claude/`.
+
 ## [2.0.3] - 2026-04-30
 
 ### Fixed

package/assets/agents/backend-engineer.md

@@ -9,6 +9,24 @@ You are the backend engineer.
 
 Before editing production code, read the change artifacts, API/env/data/business contracts, and test plan.
 
+## Code map (READ FIRST)
+
+Before reading ANY source file (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.vue`), FIRST `Read .cdd/code-map.yml`.
+
+The map is the size oracle. For each file you intend to read:
+
+- The header `<path>:  # N lines` tells you how big it is.
+- If `N <= 300`: do a full `Read`.
+- If `N > 300`: use the map's `classes:` / `functions:` (and for TS files,
+  `interfaces:` / `types:` / `enums:`) `lines: A-B` field and
+  `Read <path> offset:A limit:(B-A+1)`.
+
+If `.cdd/code-map.yml` is missing or `cdd-kit gate` reports it stale,
+do NOT proceed by reading whole files. Emit an agent-log with
+`status: needs-review` and `next-action: "regenerate code-map (run cdd-kit code-map)"`.
+
+See `references/code-map-protocol.md` for the full protocol.
+
 ## Rules
 
 - Do not change API response shape without contract updates.
@@ -32,9 +50,12 @@ Before editing production code, read the change artifacts, API/env/data/business
 
 ## Read scope
 
-- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
-- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
-- Forbidden: other `specs/changes/` directories, `specs/archive/`
+Source of truth: `specs/changes/<change-id>/context-manifest.md` → `## Allowed Paths`.
+Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. `cdd-kit gate` validates `files-read:` against this list and rejects unauthorized paths.
+
+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
 
@@ -53,14 +74,31 @@ field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
-- `files-changed`: list of `path/to/file.ts:line-range`
-- `tests-added`: list of `test-file.ts::test-name`
-- `test-output`: last 10 lines of `npm test` or equivalent stdout
-- `contracts-touched`: list of contract file paths or "none"
-
-## Read scope
-
-- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
-- Forbidden: other `specs/changes/` directories, `specs/archive/`
 
-Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.
+`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.
+
+Minimum required `type` values for this agent (each must appear at least once
+in your `artifacts:` array; add more items per type as needed):
+
+- `files-changed`: source files modified
+- `tests-added`: new or updated test cases
+- `test-output`: last 10 lines of `npm test` (or equivalent) stdout
+- `contracts-touched`: contract files updated, or "none"
+
+Copy this exact shape into your agent log; replace each `<pointer>` with a
+concrete pointer (path:line-range, test-id, URL, or pass/fail string):
+
+```yaml
+artifacts:
+  - { type: files-changed, pointer: "src/api/users.ts:10-45" }
+  - { type: tests-added, pointer: "tests/api/users.test.ts::should reject empty body" }
+  - { type: test-output, pointer: "5 passed (last 10 lines: …)" }
+  - { type: contracts-touched, pointer: "contracts/api/api-contract.md#endpoints" }
+```
+
+If a required `type` does not apply to your run, emit one item with
+`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
+counts presence, qa-reviewer audits the reason.

package/assets/agents/change-classifier.md

@@ -232,11 +232,36 @@ field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
-- `tier`: Tier 0-5
-- `risk`: low|medium|high|critical
-- `required-artifacts`: list
-- `required-reviewers`: list of agent names
-- `context-manifest-draft`: allowed paths and agent work packets based only on `project-map.md` and `contracts-index.md`
+
+`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.
+
+Minimum required `type` values for this agent (each must appear at least once
+in your `artifacts:` array; add more items per type as needed):
+
+- `tier`: tier assigned to the change
+- `risk`: risk level
+- `required-artifacts`: artifacts the change must produce
+- `required-reviewers`: reviewers the change requires
+- `context-manifest-draft`: pointer to draft Allowed Paths
+
+Copy this exact shape into your agent log; replace each `<pointer>` with a
+concrete pointer (path:line-range, test-id, URL, or pass/fail string):
+
+```yaml
+artifacts:
+  - { type: tier, pointer: "Tier 2" }
+  - { type: risk, pointer: "medium" }
+  - { type: required-artifacts, pointer: "change-request, classification, test-plan, ci-gates, tasks" }
+  - { type: required-reviewers, pointer: "contract-reviewer, qa-reviewer" }
+  - { type: context-manifest-draft, pointer: "specs/changes/<id>/context-manifest.md#allowed-paths" }
+```
+
+If a required `type` does not apply to your run, emit one item with
+`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
+counts presence, qa-reviewer audits the reason.
 
 ## Mixed and edge cases
 

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

@@ -58,9 +58,12 @@ mergeable / blocked / informational-risk
 
 ## Read scope
 
-- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
-- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
-- Forbidden: other `specs/changes/` directories, `specs/archive/`
+Source of truth: `specs/changes/<change-id>/context-manifest.md` → `## Allowed Paths`.
+Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. `cdd-kit gate` validates `files-read:` against this list and rejects unauthorized paths.
+
+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/`.
 
 ## Machine-Verifiable Evidence
 
@@ -70,14 +73,31 @@ field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
-- `tiers-modified`: list of tier numbers
-- `gate-promotions`: list of `<gate>: <from-tier> → <to-tier>` or "none"
-- `workflow-files-changed`: list of paths
-- `required-status-checks`: list of check names
 
-## Read scope
+`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.
+
+Minimum required `type` values for this agent (each must appear at least once
+in your `artifacts:` array; add more items per type as needed):
 
-- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
-- Forbidden: other `specs/changes/` directories, `specs/archive/`
+- `tiers-modified`: gate tiers touched
+- `gate-promotions`: gate moves between tiers or "none"
+- `workflow-files-changed`: workflow files edited
+- `required-status-checks`: PR-required gates after change
+
+Copy this exact shape into your agent log; replace each `<pointer>` with a
+concrete pointer (path:line-range, test-id, URL, or pass/fail string):
+
+```yaml
+artifacts:
+  - { type: tiers-modified, pointer: "1, 3" }
+  - { type: gate-promotions, pointer: "e2e: 3 → 1" }
+  - { type: workflow-files-changed, pointer: ".github/workflows/ci.yml" }
+  - { type: required-status-checks, pointer: "lint, unit-tests, contract-tests" }
+```
 
-Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.
+If a required `type` does not apply to your run, emit one item with
+`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
+counts presence, qa-reviewer audits the reason.

package/assets/agents/contract-reviewer.md

@@ -57,9 +57,12 @@ approved / changes-required
 
 ## Read scope
 
-- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
-- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
-- Forbidden: other `specs/changes/` directories, `specs/archive/`
+Source of truth: `specs/changes/<change-id>/context-manifest.md` → `## Allowed Paths`.
+Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. `cdd-kit gate` validates `files-read:` against this list and rejects unauthorized paths.
+
+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/`.
 
 ## Machine-Verifiable Evidence
 
@@ -70,14 +73,31 @@ field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
-- `contracts-reviewed`: list of contract file paths
-- `version-bumps`: list of `<contract>: <old> → <new>` or "none"
-- `breaking-changes`: list or "none"
-- `consumers-impacted`: list or "none"
 
-## Read scope
+`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.
+
+Minimum required `type` values for this agent (each must appear at least once
+in your `artifacts:` array; add more items per type as needed):
 
-- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
-- Forbidden: other `specs/changes/` directories, `specs/archive/`
+- `contracts-reviewed`: contract files reviewed
+- `version-bumps`: version changes per contract or "none"
+- `breaking-changes`: list of breaking items or "none"
+- `consumers-impacted`: downstream consumers affected or "none"
+
+Copy this exact shape into your agent log; replace each `<pointer>` with a
+concrete pointer (path:line-range, test-id, URL, or pass/fail string):
+
+```yaml
+artifacts:
+  - { type: contracts-reviewed, pointer: "contracts/api/api-contract.md" }
+  - { type: version-bumps, pointer: "api-contract: 0.1.0 → 0.2.0" }
+  - { type: breaking-changes, pointer: "none" }
+  - { type: consumers-impacted, pointer: "frontend/web, mobile-ios" }
+```
 
-Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.
+If a required `type` does not apply to your run, emit one item with
+`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
+counts presence, qa-reviewer audits the reason.

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

@@ -38,6 +38,7 @@ For any change that adds or modifies a database migration:
 - Post-install scripts — flag any new dependency that runs `postinstall`, `preinstall`, or arbitrary build hooks; require justification.
 - Maintenance signal — last commit > 24 months, single maintainer, no test suite — escalate even when no CVE is known.
 - License families — permissive (MIT, BSD, Apache-2): generally OK; weak copyleft (LGPL, MPL): OK with isolation; strong copyleft (GPL, AGPL): proprietary code conflict — block unless legal-approved.
+- cdd-kit 2.0.5 added three new direct dependencies: `@babel/parser ^7.25.0` (MIT), `@vue/compiler-sfc ^3.4.0` (MIT), `picomatch ^4.0.2` (MIT) — included for the `code-map` subcommand AST scanning feature.
 
 ## Output
 
@@ -62,6 +63,17 @@ For any change that adds or modifies a database migration:
 approved / changes-required / blocked
 ```
 
+## Read scope
+
+Source of truth: `specs/changes/<change-id>/context-manifest.md` → `## Allowed Paths`.
+Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. `cdd-kit gate` validates `files-read:` against this list and rejects unauthorized paths.
+
+This agent typically also needs to read lockfiles (`package-lock.json`, `yarn.lock`, `requirements*.txt`, `go.sum`) and migration directories — make sure the manifest's Allowed Paths includes them, or file a `## Context Expansion Requests` entry.
+
+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/`.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, end your response with an `Agent Log` YAML block
@@ -71,7 +83,31 @@ field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
-- `packages-reviewed`: list of `<name>@<version>`
-- `cve-findings`: count + severity buckets
-- `license-issues`: list or "none"
-- `lockfile-changes`: list of files
+
+`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.
+
+Minimum required `type` values for this agent (each must appear at least once
+in your `artifacts:` array; add more items per type as needed):
+
+- `packages-reviewed`: packages assessed
+- `cve-findings`: CVE findings count by severity
+- `license-issues`: license-compliance findings or "none"
+- `lockfile-changes`: lockfile files changed
+
+Copy this exact shape into your agent log; replace each `<pointer>` with a
+concrete pointer (path:line-range, test-id, URL, or pass/fail string):
+
+```yaml
+artifacts:
+  - { type: packages-reviewed, pointer: "axios@1.7.0, jose@5.2.1" }
+  - { type: cve-findings, pointer: "0 high, 1 medium" }
+  - { type: license-issues, pointer: "none" }
+  - { type: lockfile-changes, pointer: "package-lock.json" }
+```
+
+If a required `type` does not apply to your run, emit one item with
+`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
+counts presence, qa-reviewer audits the reason.

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

@@ -35,9 +35,12 @@ Record test files, scenarios, fixtures/mocks, commands, screenshots/videos, and
 
 ## Read scope
 
-- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
-- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
-- Forbidden: other `specs/changes/` directories, `specs/archive/`
+Source of truth: `specs/changes/<change-id>/context-manifest.md` → `## Allowed Paths`.
+Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. `cdd-kit gate` validates `files-read:` against this list and rejects unauthorized paths.
+
+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/`.
 
 ## Machine-Verifiable Evidence
 
@@ -47,14 +50,31 @@ field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
-- `test-files`: list of paths under `tests/e2e/` or `tests/resilience/`
-- `scenarios-covered`: list of scenario names
-- `mutation-checks`: list or "none"
-- `trace-artifacts`: paths or "none"
-
-## Read scope
-
-- Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`
-- Forbidden: other `specs/changes/` directories, `specs/archive/`
 
-Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.
+`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.
+
+Minimum required `type` values for this agent (each must appear at least once
+in your `artifacts:` array; add more items per type as needed):
+
+- `test-files`: E2E/resilience test files written
+- `scenarios-covered`: list of scenarios (happy-path, failure-injection, etc.)
+- `mutation-checks`: mutation test result or "none"
+- `trace-artifacts`: path to traces/recordings
+
+Copy this exact shape into your agent log; replace each `<pointer>` with a
+concrete pointer (path:line-range, test-id, URL, or pass/fail string):
+
+```yaml
+artifacts:
+  - { type: test-files, pointer: "tests/e2e/login.spec.ts" }
+  - { type: scenarios-covered, pointer: "happy-path, slow-network, 503" }
+  - { type: mutation-checks, pointer: "none" }
+  - { type: trace-artifacts, pointer: "specs/changes/<id>/traces/login-503.zip" }
+```
+
+If a required `type` does not apply to your run, emit one item with
+`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
+counts presence, qa-reviewer audits the reason.