contract-driven-delivery 2.0.13 → 2.0.15

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [2.0.15] - 2026-05-06
+
+Prompt guidance patch for agent-log evidence and closeout learning ownership.
+
+### Changed
+
+- **Agent-log pointer guidance matches gate behavior**: `/cdd-new` and
+  `agent-log-protocol.md` now spell out that a pointer whose text before the
+  first `:` contains `/` is validated as a single repo-relative file path, so
+  agents avoid parenthetical path notes and slash-containing labels such as
+  `I/O:` or `WARNING/OVERDUE:`.
+- **Durable learning ownership is explicit**: prompts now consistently say
+  general agents record evidence and findings only, while durable learning
+  promotion happens during `/cdd-close` Step 3 and targets `contracts/` or
+  project guidance (`CLAUDE.md`/`CODEX.md`).
+
+## [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.

package/README.md

@@ -190,7 +190,7 @@ After the PR is merged:
 **What happens:**
 1. Runs `cdd-kit gate` to confirm the change still passes
 2. Synthesizes `archive.md` — a permanent record of what changed, what tests were added, and what lessons were found
-3. Invokes `contract-reviewer` to propose any durable learnings back into `contracts/`
+3. Promotes only evidence-backed durable learnings to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`). General agents record evidence and findings only; durable learning promotion happens during `/cdd-close` Step 3.
 4. Runs `cdd-kit archive add-jwt-auth` — moves the change from `specs/changes/` to `specs/archive/2026/`
 5. Reduces the active context that future Claude sessions need to load
 
@@ -252,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`
@@ -316,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
@@ -411,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.
 
@@ -434,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-close/SKILL.md

@@ -10,7 +10,7 @@ description: Close and archive a completed change. Confirms all tasks are done,
 A change is "done" when:
 1. Gate has passed (`cdd-kit gate <change-id>` exits 0)
 2. PR is merged (or change is abandoned)
-3. Durable learnings have been promoted to hot sources: `contracts/`, `CLAUDE.md`, or `CODEX.md`
+3. Durable learnings have been promoted to hot sources: `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`)
 
 This skill drives steps 2–3 and physically moves the change to `specs/archive/`.
 
@@ -58,7 +58,7 @@ Read `specs/changes/<change-id>/tasks.yml`.
 
 Check section 7:
 - `7.1 Archive change` — will be ticked after Step 4
-- `7.2 Promote durable learnings to contracts or CLAUDE.md` — must be done NOW
+- `7.2 Promote durable learnings to contracts or project guidance` — must be done NOW
 
 If `7.2` is `[ ]`, proceed to Step 2.5. If already `[x]` or `[-]`, skip Steps 2.5 and 3.
 
@@ -92,6 +92,11 @@ This file records the close-out evidence, but Step 3 promotion must still be evi
 
 ## Step 3: Promote learnings (task 7.2)
 
+General agents do not perform durable learning promotion during `/cdd-new`; they
+only record evidence and findings in artifacts and `agent-log/*.yml`. Durable
+learning promotion happens here, during `/cdd-close` Step 3, and main Claude
+owns the final writes.
+
 Read `specs/changes/<change-id>/archive.md` section `## Lessons Promoted to Standards` and cross-check every proposed lesson against agent-log, QA report, contract/test changes, or gate evidence from this change.
 
 Classify each candidate:
@@ -132,7 +137,7 @@ If successful, set task `7.1` to `status: done` in tasks.yml (the file is now in
 
 Change ID: <change-id>
 Archived to: specs/archive/<year>/<change-id>/
-Learnings promoted: <list what was added to contracts/CLAUDE.md/CODEX.md, or "none">
+Learnings promoted: <list what was added to contracts/ or project guidance (CLAUDE.md/CODEX.md), or "none">
 
 specs/changes/<change-id>/ has been removed from the active surface.
 Token cost of future sessions reduced by ~<N> files.

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

@@ -96,6 +96,21 @@ inevitable re-classification when the agents discover the ambiguity.
 
 **Rule**: After EVERY agent completes (whether it writes itself or you write for it), YOU must update the relevant `tasks.yml` task `status:` from `pending` to `done`.
 
+**Agent-log pointer rule**: When you or an agent writes `artifacts[].pointer`,
+follow `references/agent-log-protocol.md` exactly. If the text before the first
+`:` contains `/`, `cdd-kit gate` treats that text as a repo-relative file path
+and verifies that the file exists. Therefore each pointer may name only one
+file, file pointers must not include parenthetical notes on the path, and
+slash-containing labels such as `I/O:` or `WARNING/OVERDUE:` must not be used as
+pointer prefixes. Put extra explanation in `notes` or a separate non-path
+artifact pointer instead.
+
+**Durable learning rule**: During `/cdd-new`, agents record evidence and
+findings in artifacts and `agent-log/*.yml` only. Do not promote durable lessons
+while the change is still active. Durable learning promotion happens only during
+`/cdd-close` Step 3, where main Claude cross-checks evidence and writes approved
+rules to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`).
+
 ---
 
 ## Artifact opt-in policy
@@ -168,7 +183,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
@@ -237,6 +254,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
@@ -265,9 +303,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)
@@ -366,6 +404,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.
 
@@ -485,4 +530,4 @@ Please review the above items and re-run: cdd-kit gate <change-id>
 
 The `/cdd-new` workflow is now complete. **Return to normal assistant mode immediately.** Answer any question the user asks — including questions unrelated to this change, new feature discussions, debugging help, or general conversation — without requiring them to use a specific command. The git commit shown in the report is a suggestion, not a required next step; do not wait for it before resuming normal behavior.
 
-When the change is merged and ready to close, run `/cdd-close <change-id>` to promote learnings and archive the change directory.
+When the change is merged and ready to close, run `/cdd-close <change-id>` to promote durable learnings to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`) and archive the change directory.

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.
@@ -52,7 +57,10 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
    - Invoke ci-cd-gatekeeper to design and enforce the gate plan.
 8. Archive and audit drift.
    - Use `references/spec-drift-policy.md`.
-   - Durable learnings must be promoted back to contracts or CLAUDE.md.
+   - General agents record evidence and findings only; durable learning
+     promotion happens only during `/cdd-close` Step 3.
+   - Durable learnings must be promoted back to `contracts/` or project
+     guidance (`CLAUDE.md`/`CODEX.md`).
    - `spec-drift-auditor` must run before every release to main and weekly during active multi-iteration development.
 
 ## Required gates by risk

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:
@@ -69,6 +75,22 @@ Concrete pointers only. Allowed forms:
 - `cdd-kit gate <id>: 0 errors`
 - `contracts/api/api-contract.md#endpoints`
 
+Gate path-existence rule: unless gate is run with `--lax`, any pointer whose
+text before the first `:` contains `/` is treated as a repo-relative file path
+and that file must exist. This makes path-like pointers useful, but it also
+means:
+
+- One pointer names one file only. Use separate `artifacts` items for multiple
+  files.
+- Do not attach parenthetical notes to a file path, e.g. use
+  `src/api/users.ts:45-67`, not `src/api/users.ts (updated):45-67`.
+- Do not start a pointer with slash-containing prose labels such as `I/O:` or
+  `WARNING/OVERDUE:`; gate will try to validate `I/O` or `WARNING/OVERDUE` as a
+  path. Write those labels in `notes` or after a non-path command/result
+  pointer.
+- `n/a (<reason>)` is exempt from path validation and is allowed for genuinely
+  inapplicable required artifact types.
+
 Never `verified`, `OK`, `done`, or unscoped prose.
 
 #### `next-action`
@@ -77,6 +99,14 @@ 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
@@ -104,8 +134,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" }`
@@ -114,7 +149,12 @@ verify each item:
       - BAD: `{ type: tests-added, pointer: verified }`
       - BAD: `{ type: files-changed, pointer: yes }`
       - BAD: `{ type: contract, pointer: OK }`
+      - BAD: `{ type: files-changed, pointer: "src/api/users.ts (updated):45-67" }`
+      - BAD: `{ type: test-output, pointer: "I/O: warning reproduced" }`
+      - BAD: `{ type: test-output, pointer: "WARNING/OVERDUE: manual follow-up" }`
       Reject any line whose pointer would not let a reviewer click through.
+      If the text before the first `:` contains `/`, confirm it is exactly one
+      existing repo-relative file path with no parenthetical note.
 - [ ] **If `status: blocked`**, `next-action` is ≥ 10 chars, is NOT `none`,
       `investigate further`, `tbd`, or `n/a`, and names the actual next step
       a human can act on.
@@ -137,11 +177,13 @@ 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. 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`.
+8. Unless gate is run with `--lax`: any `artifacts` pointer whose text before
+   the first `:` contains `/` 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/skills/contract-driven-delivery/templates/tasks.yml

@@ -36,4 +36,4 @@ tasks:
   - { id: "6.3", section: Verification, title: "Informational gates", status: pending }
   - { id: "6.4", section: Verification, title: "Nightly/weekly/manual gates if required", status: pending }
   - { id: "7.1", section: Archive, title: "Archive change", status: pending }
-  - { id: "7.2", section: Archive, title: "Promote durable learnings to contracts or CLAUDE.md", status: pending }
+  - { id: "7.2", section: Archive, title: "Promote durable learnings to contracts or project guidance", status: pending }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.0.13",
+  "version": "2.0.15",
   "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",