contract-driven-delivery 2.0.12 → 2.0.14

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [2.0.14] - 2026-05-06
+
+Operational hardening for real multi-agent CDD runs.
+
+### Added
+
+- **Context read preflight**: `cdd-kit context check <change-id> --path ...`
+  validates expected agent reads against `Allowed Paths`, approved expansions,
+  repo-relative path rules, and the forbidden-path baseline before agent work.
+- **Pre-existing failure tracking**: QA templates and reviewer prompts now
+  require baseline evidence, scope rationale, owner, and follow-up when an
+  existing failing test is excluded from the current gate.
+
+### Changed
+
+- **Agent-log YAML is more resilient**: gate keeps YAML timestamps as strings
+  and accepts `done` / `approved` as completion aliases while still documenting
+  `complete` as canonical.
+- **Model policy is provider-neutral**: role bindings now use model classes
+  (`opus`, `sonnet`, `haiku`) instead of provider release IDs.
+- **Agent orchestration guidance is stricter**: `/cdd-new` now requires
+  closeout after each agent, including agent-log verification and immediate
+  `tasks.yml` updates before the next agent is invoked.
+- **Migration review guidance is sharper**: MySQL ENUM contraction and
+  `ALGORITHM=COPY` DDL are explicitly treated as high risk on large tables.
+
+## [2.0.13] - 2026-05-05
+
+Documentation and release-prep patch focused on keeping CDD low-friction.
+
+### Changed
+
+- **Clarified workflow lanes**: README now distinguishes full tracked CDD
+  changes from maintenance / micro-change work, so typo fixes, formatting,
+  lint-only changes, and tiny local repairs do not imply proposal-level
+  ceremony.
+- **Documented future machine-readable metadata direction**:
+  `docs/machine-readable-change-design.md` defines `change.yml` and
+  `trace.yml` as generated metadata for reducing markdown parsing and token
+  use, not as new manually-authored forms.
+- **Synced skill/protocol docs with implementation**: `/cdd-new` now reflects
+  that `context-manifest.md` is required and that `cdd-kit new` auto-runs
+  `context-scan` when indexes are missing or stale; the agent-log protocol now
+  reflects that gate enforces per-agent artifact types when prompt files are
+  installed.
+
 ## [2.0.12] - 2026-05-04
 
 Tiny patch — closes the last line-ending hole.

package/README.md

@@ -99,6 +99,21 @@ or
 8. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
 9. Claude reports a summary and the suggested git commit
 
+### Workflow Lanes: Avoiding Ceremony for Small Fixes
+
+CDD is a governance workflow, not a rule that every edit must become a full proposal. Use the tracked `/cdd-new` flow when a change can affect product behavior, contracts, data shape, API behavior, env/deploy rules, CI/CD, security, permissions, cross-module architecture, or release risk.
+
+Use a lightweight maintenance lane for small corrections where the intent is already obvious:
+
+| Lane | Examples | Required record |
+|---|---|---|
+| maintenance / micro-change | typo fixes, comment updates, README cleanup, formatting, lint-only fixes, tiny local test repair | normal commit message and test output if applicable |
+| tracked CDD change | behavior changes, contract updates, API/data/env/security/CI changes, cross-module refactors, high-risk bug fixes | `specs/changes/<id>/`, `tasks.yml`, `context-manifest.md`, agent logs, and `cdd-kit gate` |
+
+Do not add hard pre-commit rules that block every `src/`, `tests/`, or `contracts/` edit unless your team explicitly wants that policy. The default kit favors low-friction traceability: make risky changes reviewable, but let obvious maintenance edits stay small.
+
+Machine-readable metadata such as future `change.yml` / `trace.yml` should follow the same rule: generated from existing artifacts to reduce token use and markdown parsing, not introduced as extra forms. See `docs/machine-readable-change-design.md` for the proposed shape.
+
 ### Agent Ownership Model
 
 CDD uses two agent classes on purpose:
@@ -237,6 +252,8 @@ cdd-kit init --force          # overwrite existing project files
 
 Creates: `contracts/`, `specs/templates/`, provider guidance files (`CLAUDE.md`, `AGENTS.md`, and/or `CODEX.md`), `hooks/`
 
+`.cdd/model-policy.json` stores role-to-model **classes** (`opus`, `sonnet`, `haiku`) instead of provider release IDs such as `claude-opus-4-7`. This keeps the policy stable across Claude and Codex adapters; provider-specific tooling can map the class to the concrete model available in that environment.
+
 ---
 
 ### `cdd-kit update`
@@ -301,7 +318,7 @@ Checks:
 - All required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`; new context-governed changes also require `context-manifest.md`)
 - Each artifact has sufficient content (not a stub): change-classification ≥ 200 chars, test-plan ≥ 200, ci-gates ≥ 150, others ≥ 100
 - `change-classification.md` contains a tier or risk marker
-- `agent-log/*.yml` files all have `status: complete` (not blocked)
+- `agent-log/*.yml` files all have a completed status (`complete`, with `done` and `approved` accepted as compatibility aliases) and are not blocked
 - For context-governed changes, `agent-log/*.yml` files include a structured `files-read:` list and those repo-relative paths are audited against `context-manifest.md` and `.cdd/context-policy.json`
 - Atomic `depends-on` upstream changes are completed or archived before dependent work gates
 - Tier 0–1 changes have `e2e-resilience-engineer`, `monkey-test-engineer`, and `stress-soak-engineer` logs
@@ -396,6 +413,9 @@ files-read:
 ```
 
 Paths must be repo-relative. Absolute paths and `..` parent traversal are rejected.
+If a logged read is legitimate but gate says it is unauthorized, add that path
+to `context-manifest.md` `## Allowed Paths` or approve a Context Expansion
+Request. Do not remove it from `files-read`; that list is the audit trail.
 
 Run this after upgrading from v1.10 or earlier if you have mid-flight changes.
 
@@ -419,6 +439,24 @@ Use this when an agent needs more context than its current work packet allows.
 
 ---
 
+### `cdd-kit context check <change-id>`
+
+Preflight-checks repo-relative read paths against `context-manifest.md` before
+you invoke an agent.
+
+```bash
+cdd-kit context check add-todos-ui --path src/components/Sidebar.vue src/stores/todos.js src/views/DashboardView.vue
+cdd-kit context check add-ci-gate --path contracts/ci/ci-gate-contract.md .github/workflows/contract-driven-gates.yml
+```
+
+The check uses the same authorization model as `cdd-kit gate`: `## Allowed
+Paths`, `## Approved Expansions`, repo-relative path rules, and the forbidden
+baseline in `.cdd/context-policy.json`. If the command fails and the read is
+legitimate, update the manifest or record/approve a Context Expansion Request
+before the agent reads the file.
+
+---
+
 ### `cdd-kit context approve <change-id> <request-id>`
 
 Approves a pending Context Expansion Request in `context-manifest.md` and adds its `requested_paths` to `## Approved Expansions`.

package/assets/CLAUDE.template.md

@@ -33,6 +33,7 @@ This repository follows the Contract-Driven Delivery workflow.
 | `cdd-kit list` | show all active changes and their status |
 | `cdd-kit gate <id>` | verify a change is gate-ready (run before PR) |
 | `cdd-kit gate <id> --strict` | full gate with pending-task enforcement (pre-commit default) |
+| `cdd-kit context check <id> --path <paths...>` | preflight expected agent reads against `context-manifest.md` before invoking the agent |
 | `cdd-kit archive <id>` | physically move a completed change to `specs/archive/<year>/` |
 | `cdd-kit abandon <id> --reason <text>` | mark a change as abandoned; preserves directory for git history |
 | `cdd-kit migrate <id> \| --all` | upgrade pre-v1.11 change directories to new format (frontmatter + tier format) |
@@ -46,7 +47,22 @@ Run `cdd-kit detect-stack` to verify the detected tech stack.
 For context-governed changes, read `specs/changes/<change-id>/context-manifest.md` before using file-reading or broad search tools.
 
 - Read only paths allowed by the manifest or approved expansions.
+- Before invoking an agent with known concrete reads, run
+  `cdd-kit context check <change-id> --path <paths...>`. If it fails and the
+  reads are legitimate, expand `Allowed Paths` or approve a Context Expansion
+  Request before the agent reads the files.
 - If more context is needed, stop and write a Context Expansion Request in the manifest (`cdd-kit context request`).
 - The full agent-log format (including `files-read:` schema) is defined in
   `~/.claude/skills/contract-driven-delivery/references/agent-log-protocol.md`.
   Read that once; do not paraphrase it elsewhere.
+
+## CDD Operational Notes
+
+- After each agent returns, verify its agent-log exists, tick the related
+  `tasks.yml` items immediately, and only then move to the next agent.
+- Pre-existing test failures may be excluded from the current gate only when
+  `qa-report.md` records the failing test, baseline evidence, why it is outside
+  scope, owner, and follow-up.
+- For MySQL migrations, treat ENUM contraction and any DDL requiring
+  `ALGORITHM=COPY` as high risk on large tables; require row-count/runtime
+  estimate, online migration or maintenance window, and rollback plan.

package/assets/CODEX.template.md

@@ -16,6 +16,10 @@ This project uses Contract-Driven Delivery (CDD).
 Read `specs/changes/<change-id>/context-manifest.md` before using file-reading or search tools.
 
 - Read only paths allowed by the manifest or approved expansions.
+- Before invoking an agent with known concrete reads, run
+  `cdd-kit context check <change-id> --path <paths...>`. If it fails and the
+  reads are legitimate, expand `Allowed Paths` or approve a Context Expansion
+  Request before the agent reads the files.
 - Do not use broad repository search unless the manifest authorizes it.
 - If more context is needed, stop and write a Context Expansion Request in the manifest.
 - Record every file read through tools in the relevant `agent-log/*.yml` under `files-read:`.
@@ -37,3 +41,14 @@ Every entry must be a repo-relative path. Do not omit files, use absolute paths,
 - Cold: `specs/archive/`.
 
 Cold historical data is evidence, not current requirements.
+
+## Operational Notes
+
+- After each agent returns, verify its agent-log exists, tick the related
+  `tasks.yml` items immediately, and only then move to the next agent.
+- Pre-existing test failures may be excluded from the current gate only when
+  `qa-report.md` records the failing test, baseline evidence, why it is outside
+  scope, owner, and follow-up.
+- For MySQL migrations, treat ENUM contraction and any DDL requiring
+  `ALGORITHM=COPY` as high risk on large tables; require row-count/runtime
+  estimate, online migration or maintenance window, and rollback plan.

package/assets/agents/backend-engineer.md

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the backend engineer.

package/assets/agents/change-classifier.md

@@ -2,7 +2,7 @@
 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
-model: claude-opus-4-7
+model: opus
 ---
 
 You are the change classifier for Contract-Driven Delivery.

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

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the CI/CD gatekeeper.
@@ -61,6 +61,14 @@ mergeable / blocked / informational-risk
 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 commonly needs CI contracts and workflow definitions, for example
+`contracts/ci/ci-gate-contract.md`, `ci/`, `ci-templates/`,
+`github-workflows/`, or project `.github/workflows/`. Those paths must appear
+in the manifest before you read them; if they are legitimate scope, expand the
+manifest rather than omitting them from `files-read`.
+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/`.

package/assets/agents/contract-reviewer.md

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the contract reviewer.

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

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the dependency and migration safety reviewer.
@@ -25,6 +25,10 @@ For any change that adds, removes, or upgrades a package:
 For any change that adds or modifies a database migration:
 
 - Verify the migration can run without a full-table exclusive lock on large tables (prefer `ADD COLUMN ... DEFAULT NULL`, online DDL, or batched backfills).
+- For MySQL, treat ENUM contraction, column type changes, and any DDL requiring
+  `ALGORITHM=COPY` as high risk because it rewrites the table. For tables above
+  500k rows, block unless there is an explicit online migration, maintenance
+  window, rollback path, and row-count/runtime estimate.
 - Verify a rollback path exists: either a `down` migration or an explicit documented rollback procedure.
 - Verify backfill operations are safe under concurrent writes (idempotent, does not corrupt existing rows).
 - Flag irreversible operations (column drops, type coercions, constraint additions on large tables) as high-risk.

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

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the E2E and resilience engineer.

package/assets/agents/frontend-engineer.md

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the frontend engineer.
@@ -51,6 +51,13 @@ See `references/code-map-protocol.md` for the full protocol.
 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 commonly needs exact component, store, route, and view files (for
+example `src/components/...`, `src/stores/...`, `src/views/...`). Those paths
+must appear in the manifest before you read them; if they are legitimate scope,
+expand the manifest rather than omitting them from `files-read`.
+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/`.

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

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the monkey operation engineer.
@@ -29,6 +29,12 @@ Before implementation, ensure the spec says what should happen for:
 
 Use fuzz payloads, Playwright action sequences, property-based tests, and targeted randomization where useful. Every monkey test must assert a safe outcome, not merely that the app does not crash.
 
+If an existing monkey/fuzz test already fails before your change, do not hide
+or rewrite that failure to make the current gate look green. Record the test
+id, seed/input, baseline commit or prior evidence, and whether this change
+touched the failing surface. Mark it as a follow-up when it is outside this
+change's scope; keep new or regressed failures blocking.
+
 ## Tools
 
 - Property-based — fast-check (JS/TS), hypothesis (Python), proptest (Rust) for state machine invariants.

package/assets/agents/qa-reviewer.md

@@ -2,7 +2,7 @@
 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
-model: claude-opus-4-7
+model: opus
 ---
 
 You are the QA reviewer.
@@ -46,6 +46,10 @@ Invoke `spec-drift-auditor` at the following points (do not wait for issues to s
 - `approved-with-risk` — only when (a) the residual risk is documented in qa-report.md, (b) an owner is assigned, (c) a follow-up issue exists with a date.
 - `blocked` — any required gate failing, any contract claim unverified, any UI change without visual evidence.
 - Sign-off — single reviewer for low/medium risk; two reviewers (qa-reviewer + spec-architect) for high/critical.
+- Pre-existing failures may be excluded from this change's gate only when the
+  report includes the failing test id, baseline commit or prior evidence,
+  reason it is outside the current scope, owner, and follow-up date. Without
+  that record, treat the failure as blocking.
 
 ## Output
 
@@ -61,6 +65,10 @@ Invoke `spec-drift-auditor` at the following points (do not wait for issues to s
 ## Failures
 ...
 
+## Pre-existing Failures Excluded From This Gate
+| failure/test | baseline evidence | why outside scope | owner/follow-up |
+|---|---|---|---|
+
 ## Fixback Routing
 ...
 

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

@@ -2,7 +2,7 @@
 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
-model: claude-haiku-4-5-20251001
+model: haiku
 ---
 
 You are the repository context scanner.

package/assets/agents/spec-architect.md

@@ -2,7 +2,7 @@
 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
-model: claude-opus-4-7
+model: opus
 ---
 
 You are the architecture reviewer.

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

@@ -2,7 +2,7 @@
 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
-model: claude-opus-4-7
+model: opus
 ---
 
 You are the spec drift auditor.

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

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the stress and soak engineer.

package/assets/agents/test-strategist.md

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the test strategist.

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

@@ -2,7 +2,7 @@
 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
-model: claude-sonnet-4-6
+model: sonnet
 ---
 
 You are the UI/UX reviewer.

package/assets/agents/visual-reviewer.md

@@ -2,7 +2,7 @@
 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
-model: claude-haiku-4-5-20251001
+model: haiku
 ---
 
 You are the visual reviewer.

package/assets/cdd/model-policy.json

@@ -3,22 +3,22 @@
   "generated_at": null,
   "schema-version": "0.2.0",
   "roles": {
-    "change-classifier": "claude-opus-4-7",
-    "spec-architect": "claude-opus-4-7",
-    "qa-reviewer": "claude-opus-4-7",
-    "contract-reviewer": "claude-sonnet-4-6",
-    "test-strategist": "claude-sonnet-4-6",
-    "backend-engineer": "claude-sonnet-4-6",
-    "frontend-engineer": "claude-sonnet-4-6",
-    "ci-cd-gatekeeper": "claude-sonnet-4-6",
-    "e2e-resilience-engineer": "claude-sonnet-4-6",
-    "monkey-test-engineer": "claude-sonnet-4-6",
-    "stress-soak-engineer": "claude-sonnet-4-6",
-    "ui-ux-reviewer": "claude-sonnet-4-6",
-    "visual-reviewer": "claude-haiku-4-5-20251001",
-    "dependency-security-reviewer": "claude-sonnet-4-6",
-    "spec-drift-auditor": "claude-opus-4-7",
-    "repo-context-scanner": "claude-haiku-4-5-20251001"
+    "change-classifier": "opus",
+    "spec-architect": "opus",
+    "qa-reviewer": "opus",
+    "contract-reviewer": "sonnet",
+    "test-strategist": "sonnet",
+    "backend-engineer": "sonnet",
+    "frontend-engineer": "sonnet",
+    "ci-cd-gatekeeper": "sonnet",
+    "e2e-resilience-engineer": "sonnet",
+    "monkey-test-engineer": "sonnet",
+    "stress-soak-engineer": "sonnet",
+    "ui-ux-reviewer": "sonnet",
+    "visual-reviewer": "haiku",
+    "dependency-security-reviewer": "sonnet",
+    "spec-drift-auditor": "opus",
+    "repo-context-scanner": "haiku"
   },
-  "_notes": "Roles map agent name -> model ID. Override per-project as needed. cdd-kit doctor warns when an installed agent's frontmatter `model:` does not match this policy."
+  "_notes": "Roles map agent name -> model class (opus, sonnet, haiku), not provider release IDs. Provider adapters may map these classes to concrete Claude or Codex model names. Override per-project as needed. cdd-kit doctor warns when an installed agent's frontmatter `model:` does not match this policy."
 }

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

@@ -106,7 +106,7 @@ Note: `archive.md` is created during `/cdd-close`, not during `/cdd-new` — it
 
 If the classifier marks an artifact as `no` or leaves it blank, **do not create the file** — even if a review agent could contribute to it.
 
-The 5 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`.
+The 6 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`, and `context-manifest.md`.
 
 ## Step 1: Generate change-id, scaffold, and scan context
 
@@ -122,17 +122,19 @@ Create the scaffold with the CLI so every provider gets the same templates:
 cdd-kit new <change-id>
 ```
 
-Then build deterministic context indexes before invoking any classifier:
-
-```bash
-cdd-kit context-scan
-```
+`cdd-kit new` auto-runs `cdd-kit context-scan` when `specs/context/` indexes are missing or stale. Do not run a second scan unless the command warned that context-scan failed, or you intentionally used `--skip-scan`.
 
 Verify these files exist:
 - `specs/changes/<change-id>/context-manifest.md`
 - `specs/context/project-map.md`
 - `specs/context/contracts-index.md`
 
+If either context index is still missing, run:
+
+```bash
+cdd-kit context-scan
+```
+
 Do not use broad search or ad hoc reads to classify the change before `context-scan` has completed.
 
 The generated scaffold contains the artifacts listed in the table below. **All
@@ -166,7 +168,9 @@ Do not authorize the classifier to read `contracts/`, `src/`, `tests/`, or broad
 
 The classifier must include a `## Context Manifest Draft` section with:
 - affected surfaces
-- allowed paths for each required agent work packet
+- allowed paths for each required agent work packet; this must be the union of
+  every file/directory agents are expected to read, including component/store/view
+  files for frontend work and CI contracts/workflows for CI work
 - required contracts
 - required tests
 - any context expansion requests that must be approved before implementation
@@ -235,6 +239,27 @@ Change directory: specs/changes/<change-id>/
 ```
 This ensures the agent's Read scope restriction points to the correct directory.
 
+Before invoking an agent, preflight any concrete paths you already expect that
+agent to read:
+
+```bash
+cdd-kit context check <change-id> --path <repo-relative path> [more paths...]
+```
+
+If the check fails and the paths are legitimate work scope, update
+`context-manifest.md` `## Allowed Paths` or approve a Context Expansion Request
+before the agent reads them. This catches common late gate failures such as UI
+components/stores/views or CI workflow files missing from the manifest.
+
+After every agent returns, complete the closeout before starting the next
+agent:
+- confirm its `agent-log/<agent>.yml` exists or write it for read-only agents
+- confirm the log has a completed status (`complete`, `done`, or `approved`) or
+  halt on `blocked`
+- tick the owned `tasks.yml` items immediately
+- record incidental/pre-existing findings in the appropriate report instead of
+  silently fixing unrelated scope
+
 ### Agent stage badges (UI v1)
 
 When you announce that you are about to invoke an agent, prefix the
@@ -263,9 +288,9 @@ the user; do not put them inside the prompt sent to the agent.
 | Audit | `repo-context-scanner` | ⚫ `[repo-scan]` |
 
 Color semantics:
-- 🟣 purple: deciding what we will do (heavy model, opus-class)
-- 🔵 blue: writing code (sonnet-class implementation)
-- 🟡 yellow: planning tests (sonnet-class)
+- 🟣 purple: deciding what we will do (heavy model, `opus`)
+- 🔵 blue: writing code (`sonnet` implementation)
+- 🟡 yellow: planning tests (`sonnet`)
 - 🟠 orange: heavy testing — only appears for Tier 0–1, signals high-risk scope
 - 🟢 green: reviewing what was done (no code writes; just verdicts)
 - ⚫ neutral: audits and scans (read-only background work)
@@ -364,6 +389,13 @@ All agents from Tier 2–3, plus insert these after `frontend-engineer` / `backe
 - Skip an agent only if the classifier explicitly marks its surface as "not affected"
 - If backend-only with no UI: skip `frontend-engineer`, `ui-ux-reviewer`, `visual-reviewer`
 - If UI-only with no backend: skip `backend-engineer`
+- If a required or informational test has pre-existing failures unrelated to
+  this change, do not count them as this change's pass/fail result. Record the
+  failing test id, baseline commit or prior evidence, owner, and follow-up in
+  `qa-report.md`; QA may only approve this as `approved-with-risk`.
+- If implementation uncovers unrelated old bugs, fix only those needed to meet
+  this change's acceptance criteria or to avoid a new safety/security risk.
+  Otherwise record them as follow-up with evidence and owner.
 
 **Resuming from blocked**: After the user resolves the blocking issue, re-invoke the blocked agent (do not restart from Step 1). Continue with the remaining agents in their original order.
 

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

@@ -98,7 +98,7 @@ Read only paths allowed by the context manifest and approved expansions.
 If more context is needed, stop and output a Context Expansion Request instead of reading outside the manifest.
 ```
 
-Do NOT re-run agents that already have a `status: complete` agent-log.
+Do NOT re-run agents that already have a completed agent-log (`status: complete`, `done`, or `approved`).
 
 Continue until all required agents are done, then run `cdd-kit gate <change-id>`.
 
@@ -106,7 +106,7 @@ Continue until all required agents are done, then run `cdd-kit gate <change-id>`
 
 ## Rules
 
-- Never re-run an agent that already has `status: complete` in its agent-log
+- Never re-run an agent that already has `status: complete`, `done`, or `approved` in its agent-log
 - Never start from Step 1 of `/cdd-new` — only resume from the next pending agent
 - Never use broad search to reconstruct state; resume from `tasks.yml`, `context-manifest.md`, and `agent-log/`
 - Never continue past pending Context Expansion Requests

package/assets/skills/contract-driven-delivery/SKILL.md

@@ -41,6 +41,11 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
    - Each engineer must read the matching standard before authoring tests: e2e-resilience-engineer → references/e2e-standard.md, monkey-test-engineer → references/monkey-operation-standard.md, stress-soak-engineer → references/stress-soak-standard.md.
 6. Implement through the right role.
    - Backend/frontend work must follow contracts and tests.
+   - Before invoking an agent with known concrete read paths, run
+     `cdd-kit context check <change-id> --path <paths...>` and expand the
+     manifest before the agent reads legitimate missing paths.
+   - After each agent finishes, verify its agent-log exists and tick the
+     related `tasks.yml` items before starting the next agent.
    - UI changes require UI/UX and visual review.
    - Invoke ui-ux-reviewer for interaction, copy, accessibility, and information hierarchy review whenever UI changes.
    - Invoke visual-reviewer for layout, responsive, CSS contract, and screenshot diff review whenever UI changes.

package/assets/skills/contract-driven-delivery/references/agent-log-protocol.md

@@ -24,7 +24,7 @@ The file is pure YAML (no markdown wrapping, no checklist).
 ```yaml
 change-id: <id>
 agent: <agent-name>
-timestamp: <ISO 8601 UTC, e.g. 2026-04-27T14:30:00Z>
+timestamp: "<ISO 8601 date-time, e.g. 2026-04-27T14:30:00Z>"
 status: complete            # complete | needs-review | blocked
 files-read:
   - <repo-relative path>
@@ -42,8 +42,8 @@ notes: <optional free-form>
 |---|---|---|
 | `change-id` | yes | must equal the parent change directory name |
 | `agent` | yes | canonical agent name (matches the agent's filename) |
-| `timestamp` | yes | ISO 8601 UTC; used by spec-drift-auditor for ordering |
-| `status` | yes | exactly one of `complete` \| `needs-review` \| `blocked` |
+| `timestamp` | yes | ISO 8601 date-time string; quote it to avoid YAML timestamp coercion in non-cdd tools. UTC `Z` is preferred; numeric offsets such as `+08:00` are accepted. |
+| `status` | yes | canonical values are `complete` \| `needs-review` \| `blocked`; `done` and `approved` are accepted by gate as compatibility aliases for `complete` |
 | `files-read` | conditional | required for context-governed changes (see below) |
 | `artifacts` | yes | array of `{type, pointer}` objects, ≥ 1 item |
 | `next-action` | yes | when `status: blocked`, ≥ 10 chars and not `none` |
@@ -60,6 +60,12 @@ files-read:
   - specs/changes/<change-id>/
 ```
 
+If `cdd-kit gate` reports `read unauthorized path`, do not delete that
+`files-read` entry to silence the gate. If the read was legitimate work scope,
+add the repo-relative path to `context-manifest.md` under `## Allowed Paths` or
+approve a Context Expansion Request. `files-read` is the audit trail; the
+manifest is the authorization boundary.
+
 #### `artifacts`
 
 Concrete pointers only. Allowed forms:
@@ -77,12 +83,27 @@ When `status: blocked`, this must be ≥ 10 chars, must not be `none`, `tbd`,
 `investigate further`, or `n/a`, and must name the actual next step a human
 can act on. When `status: complete`, `none` is acceptable.
 
+#### `status`
+
+Use `status: complete` for a finished agent-log. `tasks.yml` task entries use
+`status: done`, and review language may say "approved", but agent-log
+completion is canonically `complete`. `cdd-kit gate` accepts `done` and
+`approved` as compatibility aliases so these common mix-ups do not block
+delivery.
+
 ## Per-agent additional artifact requirements
 
 Each agent prompt lists its own `### Required artifacts for this agent`. The
-gate does not enforce those today; they are a discipline contract enforced by
-`qa-reviewer` and `contract-reviewer`. If you add a required artifact in an
-agent prompt, also update the qa-reviewer checklist.
+gate enforces the declared artifact `type` values when the corresponding agent
+prompt file is installed in `.claude/agents/` or `~/.claude/agents/`. This keeps
+agent prompts, evidence logs, and gate behavior aligned without duplicating the
+full protocol in every prompt.
+
+If you add a required artifact type in an agent prompt, also update tests that
+exercise `cdd-kit gate` for that agent. Agents may emit
+`pointer: "n/a (<reason>)"` when a declared type is genuinely inapplicable; the
+type must still be present so reviewers can tell that the omission was
+intentional.
 
 ## Self-validation before submitting your response
 
@@ -97,8 +118,13 @@ verify each item:
 - [ ] **All required keys exist**: `change-id`, `agent`, `timestamp`,
       `status`, `artifacts`, `next-action` (plus `files-read` for
       context-governed changes).
-- [ ] **`status` is one of**: `complete`, `needs-review`, `blocked` — not
-      `done`, `OK`, `pending`, `wip`, or anything else.
+- [ ] **`timestamp` is quoted** and uses ISO 8601 date-time form. Prefer
+      UTC `Z`, e.g. `timestamp: "2026-04-27T14:30:00Z"`. Numeric offsets
+      such as `timestamp: "2026-05-05T00:00:00+08:00"` are valid.
+- [ ] **`status` is one of**: `complete`, `needs-review`, `blocked`.
+      Prefer `complete` for finished logs; `done` and `approved` are accepted
+      only as compatibility aliases. Do not use `OK`, `pending`, `wip`, or
+      anything else.
 - [ ] **Every `artifacts` item is a `{type, pointer}` mapping** with a
       concrete pointer:
       - GOOD: `{ type: tests-added, pointer: "tests/foo.test.ts::should reject empty body" }`
@@ -130,9 +156,11 @@ ship a known-bad log and rely on the gate to catch it.
 3. `status` is missing or has an unknown value.
 4. `status: blocked` without a concrete `next-action`.
 5. `files-read` is missing for a context-governed change, or contains an
-   absolute path / `..` segment / forbidden path.
+   absolute path / `..` segment / forbidden path / path outside manifest
+   `Allowed Paths` and `Approved Expansions`.
 6. Any `artifacts` item is missing `type` or `pointer`, or the array is empty.
-7. With `--strict`: any `artifacts` pointer that looks like a path but does
+7. A required per-agent artifact `type` declared in the agent prompt is missing.
+8. With `--strict`: any `artifacts` pointer that looks like a path but does
    not exist on disk; or any runtime-logged read not declared in `files-read`.
 
 ## Why this lives in references/

package/assets/skills/contract-driven-delivery/templates/agent-log.example.yml

@@ -1,6 +1,6 @@
 change-id: feat-001
 agent: backend-engineer
-timestamp: 2026-04-27T14:30:00Z
+timestamp: "2026-04-27T14:30:00Z"
 status: complete
 files-read:
   - contracts/api/api-contract.md

package/assets/skills/contract-driven-delivery/templates/change-classification.md

@@ -75,7 +75,9 @@ Always required: change-request.md, change-classification.md, test-plan.md, ci-g
 -
 
 ### Allowed Paths
-<!-- Union of ALL paths any agent will read. Add change-specific paths below the defaults. -->
+<!-- Union of ALL paths any agent will read. Add change-specific paths below the defaults.
+     Include component/store/view files for frontend work and CI contracts/workflows for CI work
+     when those files are legitimate work scope. Gate compares agent-log files-read against this list. -->
 - specs/changes/<change-id>/
 - specs/context/project-map.md
 - specs/context/contracts-index.md

package/assets/skills/contract-driven-delivery/templates/qa-report.md

@@ -18,6 +18,10 @@
 
 ## Known Risks
 
+## Pre-existing Failures Excluded From This Gate
+| failure/test | baseline evidence | why outside scope | owner/follow-up |
+|---|---|---|---|
+
 ## Failures and Fixback Routing
 | failure | evidence | owner | required fix |
 |---|---|---|---|

package/assets/specs-templates/context-manifest.md

@@ -10,6 +10,8 @@ and is automatically applied by `cdd-kit gate` — do not duplicate it here.
 ## Allowed Paths
 <!-- UNION of all repo-relative paths (or globs) any agent may read for this change.
      cdd-kit gate validates every agent's files-read log against this list.
+     If an agent legitimately read a path, add that path here; do not remove it
+     from files-read just to pass gate.
      Be specific — wide globs (e.g. src/) defeat read-scope governance.
      Always include the three defaults below; add change-specific paths beneath them. -->
 - specs/changes/<change-id>/

package/assets/specs-templates/qa-report.md

@@ -18,6 +18,10 @@
 
 ## Known Risks
 
+## Pre-existing Failures Excluded From This Gate
+| failure/test | baseline evidence | why outside scope | owner/follow-up |
+|---|---|---|---|
+
 ## Failures and Fixback Routing
 | failure | evidence | owner | required fix |
 |---|---|---|---|

package/dist/cli/index.js

@@ -9881,22 +9881,22 @@ async function attemptAutoFixes(cwd, report) {
         const merged = {
           ...existing,
           roles: {
-            "change-classifier": "claude-opus-4-7",
-            "spec-architect": "claude-opus-4-7",
-            "qa-reviewer": "claude-opus-4-7",
-            "contract-reviewer": "claude-sonnet-4-6",
-            "test-strategist": "claude-sonnet-4-6",
-            "backend-engineer": "claude-sonnet-4-6",
-            "frontend-engineer": "claude-sonnet-4-6",
-            "ci-cd-gatekeeper": "claude-sonnet-4-6",
-            "e2e-resilience-engineer": "claude-sonnet-4-6",
-            "monkey-test-engineer": "claude-sonnet-4-6",
-            "stress-soak-engineer": "claude-sonnet-4-6",
-            "ui-ux-reviewer": "claude-sonnet-4-6",
-            "visual-reviewer": "claude-haiku-4-5-20251001",
-            "dependency-security-reviewer": "claude-sonnet-4-6",
-            "spec-drift-auditor": "claude-opus-4-7",
-            "repo-context-scanner": "claude-haiku-4-5-20251001"
+            "change-classifier": "opus",
+            "spec-architect": "opus",
+            "qa-reviewer": "opus",
+            "contract-reviewer": "sonnet",
+            "test-strategist": "sonnet",
+            "backend-engineer": "sonnet",
+            "frontend-engineer": "sonnet",
+            "ci-cd-gatekeeper": "sonnet",
+            "e2e-resilience-engineer": "sonnet",
+            "monkey-test-engineer": "sonnet",
+            "stress-soak-engineer": "sonnet",
+            "ui-ux-reviewer": "sonnet",
+            "visual-reviewer": "haiku",
+            "dependency-security-reviewer": "sonnet",
+            "spec-drift-auditor": "opus",
+            "repo-context-scanner": "haiku"
           }
         };
         const { writeFileSync: writeFileSync14 } = await import("fs");
@@ -10321,6 +10321,7 @@ var context_exports = {};
 __export(context_exports, {
   approveAllPending: () => approveAllPending,
   approveContextExpansion: () => approveContextExpansion,
+  checkContextPaths: () => checkContextPaths,
   listContextExpansions: () => listContextExpansions,
   rejectAllPending: () => rejectAllPending,
   rejectContextExpansion: () => rejectContextExpansion,
@@ -10328,6 +10329,7 @@ __export(context_exports, {
 });
 import { existsSync as existsSync22, readFileSync as readFileSync26, writeFileSync as writeFileSync13 } from "fs";
 import { join as join26 } from "path";
+import picomatch3 from "picomatch";
 function normalizePath(path) {
   return path.replace(/\\/g, "/").replace(/^\.\//, "").trim();
 }
@@ -10356,9 +10358,57 @@ function writeManifest(changeId, content) {
 `, "utf8");
 }
 function sectionBody(content, heading) {
-  const match = content.match(new RegExp(`## ${heading}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`));
+  const match = stripHtmlComments2(content).match(new RegExp(`## ${heading}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`));
   return match?.[1] ?? "";
 }
+function stripHtmlComments2(text) {
+  return text.replace(/<!--[\s\S]*?-->/g, "");
+}
+function parseListSection2(content, heading) {
+  return sectionBody(content, heading).split(/\r?\n/).map((line) => line.replace(/^\s*-\s*/, "").trim()).filter((item) => item && item !== "-" && item.toLowerCase() !== "none").map(normalizePath);
+}
+function pathMatches2(relPath, patterns, currentChangeId) {
+  const normalized = normalizePath(relPath);
+  return patterns.some((rawPattern) => {
+    const pattern = normalizePath(rawPattern).replace(/\/+$/, "");
+    if (!pattern)
+      return false;
+    if (pattern === "specs/changes/*" && currentChangeId) {
+      const current = `specs/changes/${currentChangeId}`;
+      if (normalized === current || normalized.startsWith(`${current}/`))
+        return false;
+      return normalized.startsWith("specs/changes/");
+    }
+    if (/[*?[{]/.test(pattern)) {
+      if (picomatch3.isMatch(normalized, pattern, { dot: true, nocase: false }))
+        return true;
+      if (pattern.endsWith("/**")) {
+        const base = pattern.slice(0, -3);
+        if (normalized === base)
+          return true;
+      }
+      return false;
+    }
+    return normalized === pattern || normalized.startsWith(`${pattern}/`);
+  });
+}
+function loadContextPolicy2() {
+  const policyPath = join26(process.cwd(), ".cdd", "context-policy.json");
+  if (!existsSync22(policyPath))
+    return { forbiddenPaths: DEFAULT_FORBIDDEN_PATHS };
+  try {
+    const custom = JSON.parse(readFileSync26(policyPath, "utf8"));
+    return {
+      forbiddenPaths: Array.from(/* @__PURE__ */ new Set([
+        ...DEFAULT_FORBIDDEN_PATHS,
+        ...custom.forbiddenPaths ?? []
+      ]))
+    };
+  } catch {
+    log.warn("could not parse .cdd/context-policy.json; using default context policy");
+    return { forbiddenPaths: DEFAULT_FORBIDDEN_PATHS };
+  }
+}
 function parseRequests(content) {
   const body = sectionBody(content, "Context Expansion Requests");
   if (!body.trim())
@@ -10496,6 +10546,47 @@ async function listContextExpansions(changeId, json = false) {
       log.dim(`    ${path}`);
   }
 }
+async function checkContextPaths(changeId, paths, json = false) {
+  if (paths.length === 0) {
+    log.error("at least one --path value is required");
+    process.exit(1);
+  }
+  const content = readManifest(changeId);
+  const allowedPaths = parseListSection2(content, "Allowed Paths");
+  const approvedExpansions = parseListSection2(content, "Approved Expansions");
+  const policy = loadContextPolicy2();
+  const normalizedPaths = [...new Set(paths.map(normalizePath).filter(Boolean))];
+  const results = normalizedPaths.map((path) => {
+    const validationError = validateRepoRelativePath(path);
+    const forbidden = !validationError && pathMatches2(path, policy.forbiddenPaths, changeId);
+    const authorized = !validationError && !forbidden && (pathMatches2(path, allowedPaths) || pathMatches2(path, approvedExpansions));
+    let reason = "authorized";
+    if (validationError)
+      reason = validationError;
+    else if (forbidden)
+      reason = "forbidden by .cdd/context-policy.json baseline";
+    else if (!authorized)
+      reason = "not in context-manifest Allowed Paths or Approved Expansions";
+    return { path, authorized, reason };
+  });
+  if (json) {
+    console.log(JSON.stringify({ changeId, results }, null, 2));
+  } else {
+    for (const result of results) {
+      if (result.authorized)
+        log.ok(`authorized: ${result.path}`);
+      else
+        log.error(`unauthorized: ${result.path} (${result.reason})`);
+    }
+    const unauthorized = results.filter((r) => !r.authorized).map((r) => r.path);
+    if (unauthorized.length > 0) {
+      log.info(`If these reads are legitimate, add them to specs/changes/${changeId}/context-manifest.md Allowed Paths or request expansion:`);
+      log.info(`  cdd-kit context request ${changeId} CER-<id> --path ${unauthorized.join(" ")} --reason "<why needed>"`);
+    }
+  }
+  if (results.some((result) => !result.authorized))
+    process.exit(1);
+}
 function applyApproval(content, request) {
   for (const path of request.paths) {
     const validationError = validateRepoRelativePath(path);
@@ -10569,10 +10660,21 @@ async function rejectAllPending(changeId) {
   writeManifest(changeId, content);
   log.ok(`rejected ${pending.length} pending context expansion request(s) for ${changeId}`);
 }
+var DEFAULT_FORBIDDEN_PATHS;
 var init_context = __esm({
   "src/commands/context.ts"() {
     "use strict";
     init_logger();
+    DEFAULT_FORBIDDEN_PATHS = [
+      ".claude/worktrees/**",
+      ".git/**",
+      "node_modules/**",
+      "dist/**",
+      "build/**",
+      "assets/**",
+      "specs/archive/**",
+      "specs/changes/*"
+    ];
   }
 });
 
@@ -11243,7 +11345,7 @@ var agentLogSchema = {
     "change-id": { type: "string", pattern: "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$" },
     timestamp: { type: "string", format: "date-time" },
     agent: { type: "string", minLength: 1 },
-    status: { type: "string", enum: ["complete", "needs-review", "blocked"] },
+    status: { type: "string", enum: ["complete", "done", "approved", "needs-review", "blocked"] },
     "files-read": { type: "array", items: { type: "string", minLength: 1 } },
     artifacts: {
       type: "array",
@@ -11469,7 +11571,7 @@ function loadContextPolicy(cwd) {
 function loadYamlFile(path) {
   try {
     const raw = readFileSync16(path, "utf8");
-    return { data: yaml2.load(raw), parseError: null };
+    return { data: yaml2.load(raw, { schema: yaml2.JSON_SCHEMA }), parseError: null };
   } catch (err) {
     return { data: null, parseError: err.message };
   }
@@ -11786,9 +11888,18 @@ async function gate(changeId, opts = {}) {
       let statusReported = false;
       if (!ok) {
         for (const e of validateAgentLog.errors ?? []) {
-          if (e.keyword === "required" && e.params.missingProperty === "status" || e.instancePath === "/status" && e.keyword === "enum") {
+          if (e.keyword === "required" && e.params.missingProperty === "status") {
             if (!statusReported) {
-              errors.push(`agent-log/${f}: missing or invalid "status:" line (must be complete | needs-review | blocked)`);
+              errors.push(`agent-log/${f}: missing required "status:" line (expected complete | needs-review | blocked; aliases accepted: done, approved)`);
+              statusReported = true;
+            }
+            continue;
+          }
+          if (e.instancePath === "/status" && e.keyword === "enum") {
+            if (!statusReported) {
+              const rawStatus = data.status;
+              const shownStatus = typeof rawStatus === "string" ? rawStatus : JSON.stringify(rawStatus);
+              errors.push(`agent-log/${f}: invalid "status:" value ${shownStatus ?? "<missing>"} (expected complete | needs-review | blocked; aliases accepted: done, approved)`);
               statusReported = true;
             }
             continue;
@@ -11837,7 +11948,7 @@ async function gate(changeId, opts = {}) {
             errors.push(`agent-log/${f}: read forbidden path -> ${p}`);
           }
           if (hasManifest && allowedPaths.length > 0 && !pathMatches(p, allowedPaths) && !pathMatches(p, approvedExpansions)) {
-            errors.push(`agent-log/${f}: read unauthorized path -> ${p} (not in allowed paths or approved expansions)`);
+            errors.push(`agent-log/${f}: read unauthorized path -> ${p} (not in context-manifest Allowed Paths or Approved Expansions; if legitimate, add it to the manifest instead of deleting it from files-read)`);
           }
         }
         const runtimeLog = join16(cwd, ".cdd", "runtime", `${changeId}-files-read.jsonl`);
@@ -12140,4 +12251,8 @@ context.command("list <change-id>").description("List Context Expansion Requests
   const { listContextExpansions: listContextExpansions2 } = await Promise.resolve().then(() => (init_context(), context_exports));
   await listContextExpansions2(changeId, opts.json);
 });
+context.command("check <change-id>").description("Preflight-check repo-relative read paths against context-manifest Allowed Paths").requiredOption("--path <paths...>", "Repo-relative path(s) an agent is expected to read").option("--json", "Print machine-readable JSON", false).action(async (changeId, opts) => {
+  const { checkContextPaths: checkContextPaths2 } = await Promise.resolve().then(() => (init_context(), context_exports));
+  await checkContextPaths2(changeId, opts.path, opts.json);
+});
 program.parse();

package/docs/machine-readable-change-design.md

@@ -0,0 +1,137 @@
+# Machine-Readable Change Metadata Design
+
+## Goal
+
+`change.yml` and `trace.yml` should reduce markdown parsing and repeated agent
+reads. They must not become new forms humans must fill out before making small
+fixes.
+
+The design principle is:
+
+- Humans write normal change artifacts only when a tracked CDD change is useful.
+- Tools derive machine-readable state from existing artifacts whenever possible.
+- Missing machine-readable files should be fixable by regeneration, not by
+  forcing a user through extra ceremony.
+
+## Workflow Lanes
+
+| lane | when to use | metadata expectation |
+|---|---|---|
+| maintenance / micro-change | typo fixes, docs cleanup, formatting, lint-only fixes, tiny local test repair | no `specs/changes/<id>/` required |
+| tracked CDD change | behavior, contract, API, data, env, security, CI/CD, cross-module, or release-risk work | `change.yml` and `trace.yml` generated under `specs/changes/<id>/` |
+
+The kit should not enforce "every hot file edit needs a change id" by default.
+Teams that want that policy can add a repo-local hook or CI wrapper, but it
+should not be the baseline behavior.
+
+## `change.yml`
+
+Purpose: a compact state index for one tracked change.
+
+Source of truth:
+
+- `tasks.yml` for status, tier, dependencies, and task state.
+- `change-classification.md` for change type, agents, and acceptance criteria.
+- `context-manifest.md` for read scope.
+- `agent-log/*.yml` for evidence and agent completion.
+
+Generated shape:
+
+```yaml
+change-id: add-jwt-auth
+status: in-progress
+tier: 2
+lane: tracked
+types:
+  primary: feature-enhancement
+  secondary: [api-only-change]
+required-agents:
+  - change-classifier
+  - test-strategist
+  - backend-engineer
+  - contract-reviewer
+  - qa-reviewer
+artifacts:
+  required:
+    - change-request.md
+    - change-classification.md
+    - test-plan.md
+    - ci-gates.md
+    - tasks.yml
+    - context-manifest.md
+  optional: []
+context:
+  manifest: specs/changes/add-jwt-auth/context-manifest.md
+  allowed-paths-count: 8
+dependencies: []
+generated-from:
+  tasks.yml: sha256:<digest>
+  change-classification.md: sha256:<digest>
+  context-manifest.md: sha256:<digest>
+```
+
+Rules:
+
+- `change.yml` is generated by the CLI, not hand-authored.
+- If it is absent, agents may fall back to existing markdown/YAML artifacts.
+- `cdd-kit doctor --fix` is the right place to regenerate stale metadata.
+- `cdd-kit gate` may warn on stale metadata, but should not fail only because
+  `change.yml` is missing unless a repo opts into strict metadata mode.
+
+## `trace.yml`
+
+Purpose: a compact traceability graph from acceptance criteria to evidence.
+
+Source of truth:
+
+- Acceptance criteria from `change-classification.md`.
+- Test mapping from `test-plan.md`.
+- CI gates from `ci-gates.md`.
+- Evidence pointers from `agent-log/*.yml`.
+
+Generated shape:
+
+```yaml
+change-id: add-jwt-auth
+criteria:
+  - id: AC-1
+    text: Users can log in with a valid JWT.
+    tests:
+      - family: integration
+        path: tests/auth/login.test.ts
+        name: accepts valid token
+    gates:
+      - unit
+      - contract
+    evidence:
+      - agent: backend-engineer
+        type: tests-added
+        pointer: tests/auth/login.test.ts::accepts valid token
+      - agent: qa-reviewer
+        type: qa-verdict
+        pointer: specs/changes/add-jwt-auth/agent-log/qa-reviewer.yml
+```
+
+Rules:
+
+- `trace.yml` is generated from existing evidence.
+- It should help reviewers and agents avoid rereading long markdown files.
+- Missing evidence should point back to the existing artifact that needs work;
+  it should not introduce a new place to manually duplicate the same content.
+
+## CLI Direction
+
+Useful future commands:
+
+```bash
+cdd-kit metadata <change-id>        # regenerate change.yml and trace.yml
+cdd-kit metadata <change-id> --check
+cdd-kit doctor --fix                # regenerate stale metadata for active changes
+```
+
+Default gate behavior should stay low-friction:
+
+- Warn when generated metadata is stale or absent.
+- Fail only when source artifacts themselves are invalid.
+- Add a repo opt-in for strict metadata enforcement later if teams ask for it.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "description": "Contract-driven delivery kit for AI coding agents with deterministic context indexes, manifest-backed read-scope governance, and orchestrated contracts-first delivery.",
   "keywords": [
     "contract-driven",