contract-driven-delivery 2.0.16 → 2.0.18

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## [2.0.18] - 2026-05-15
+
+Implementation planning handoff release. This adds a senior planning step so
+implementation agents receive a concise execution packet instead of inferring
+scope from chat history.
+
+### Added
+
+- **`implementation-planner` agent**: writes
+  `specs/changes/<change-id>/implementation-plan.md` after classification,
+  contracts, test plan, design, and CI gate plan are known.
+- **Required `implementation-plan.md` template**: new changes scaffold it by
+  default, `cdd-kit gate` validates it, and `cdd-kit migrate` adds a scaffold
+  for existing active changes.
+- **Upgrade documentation**: README now explains how to sync npm package
+  updates into global agents/skills, repo templates, `.cdd/model-policy.json`,
+  hooks, code-map, and existing change directories.
+
+### Changed
+
+- **Implementation agents now consume the plan**: backend, frontend, E2E,
+  monkey, and stress/soak agents must read `implementation-plan.md` and report
+  `blocked` instead of inferring missing scope.
+- **`/cdd-new` ordering now plans before implementation**: contracts, test
+  plan, design if needed, and CI gate plan come before `implementation-planner`;
+  backend/frontend/test implementation agents start only after task `1.4`
+  confirms the implementation plan.
+- **Traceability helpers include implementation plan**:
+  `generate_change_scaffold.py` copies the new template and
+  `validate_spec_traceability.py` treats it as required.
+
+## [2.0.17] - 2026-05-07
+
+Focused index-assisted development release. Agents now get a smaller, more
+precise pre-read path through the code-map, while `cdd-kit gate` returns to
+delivery-quality validation instead of post-run harness paperwork.
+
+### Added
+
+- **`cdd-kit index query <term>`**: searches `.cdd/code-map.yml` for matching
+  files, imports, symbols, and line ranges, auto-refreshing a missing or stale
+  map before returning candidates.
+- **`cdd-kit index impact <path-or-symbol>`**: reports indexed local imports and
+  dependent files so agents can inspect the smallest useful modification scope
+  before editing.
+
+### Changed
+
+- **Gate is now delivery-quality only**: `cdd-kit gate` validates required
+  artifacts, tasks, tier consistency, dependencies, and contract validators,
+  without requiring agent logs, files-read lists, or code-map freshness as
+  merge blockers.
+- **Agent prompts prefer index-first targeting**: implementation agents are
+  instructed to use `index query` before broad source reads and `index impact`
+  before editing chosen source files.
+- **Agent logs are optional handoff notes**: prompt templates and protocols no
+  longer require agents to create logs or reconstruct every file they read just
+  to satisfy a gate.
+
 ## [2.0.16] - 2026-05-06
 
 New-change scaffold hardening so freshly opened proposals use the installed

package/README.md

@@ -1,10 +1,10 @@
-# Contract-Driven Delivery Kit
+# Contract-Driven Delivery Kit
 
-**cdd-kit** is a contract-driven delivery kit for AI coding agents. It started with Claude Code skills and now keeps the core workflow provider-neutral: contracts-first, test-first, spec-first. Every change goes through classification, contract review, TDD, implementation, and gate verification, with deterministic context indexes and manifest-backed read-scope auditing to keep long agent runs reviewable.
+**cdd-kit** is a contract-driven delivery kit for AI coding agents. It started with Claude Code skills and now keeps the core workflow provider-neutral: contracts-first, test-first, spec-first. Every change goes through classification, contract review, TDD, implementation, and gate verification, with deterministic context indexes to keep agent work targeted.
 
 Designed for solo developers and small teams building brownfield production systems (dashboards, APIs, workflow tools, data apps), especially when non-engineers or product owners want AI to do the implementation while they stay in the spec-author and reviewer seat.
 
-**Context Governance v1** adds a manifest-driven audit layer for AI agents. New changes include `context-manifest.md`, `agent-log` entries are expected to report `files-read`, and `cdd-kit gate` audits those reads against allowed and forbidden paths. This is governance and review support, not a sandbox.
+**Context Governance v1** adds a manifest-driven planning layer for AI agents. New changes include `context-manifest.md`; agents should use `cdd-kit index query` and `cdd-kit index impact` before broad source reads. `cdd-kit gate` focuses on delivery quality, not post-run read paperwork.
 
 ---
 
@@ -38,7 +38,7 @@ cdd-kit init
 
 ## How to Direct Claude Code
 
-> All workflows are started by typing a **natural language instruction** to Claude Code in your IDE or terminal. The `/cdd-*` prefixed commands are Claude Code skills — not shell commands.
+> All workflows are started by typing a **natural language instruction** to Claude Code in your IDE or terminal. The `/cdd-*` prefixed commands are Claude Code skills ??not shell commands.
 
 ### Starting a new project (first time)
 
@@ -94,10 +94,11 @@ or
 3. The `change-classifier` agent (Opus) reads the request, classifies risk and tier, decides which agents are needed
 4. If the request is too broad, the classifier can return an atomic split proposal instead of forcing one Tier 0/1 monolith
 5. For Tier 0-1 work, Claude's narration uses stage badges so users can tell whether the flow is deciding, implementing, testing, or reviewing
-6. Agents run in order: contracts → test plan → spec/architecture review (if needed) → backend engineer → frontend engineer → CI/CD gates → QA
-7. Each agent produces machine-verifiable evidence (agent-log files)
-8. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
-9. Claude reports a summary and the suggested git commit
+6. Agents run in order: contracts ??test plan ??spec/architecture review (if needed) ??CI/CD gates ??implementation plan ??backend engineer ??frontend engineer ??QA
+7. `implementation-planner` writes `implementation-plan.md`, the concise execution packet implementation agents follow
+8. Implementation agents write code/tests from that plan and optional concise handoff notes
+9. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
+10. Claude reports a summary and the suggested git commit
 
 ### Workflow Lanes: Avoiding Ceremony for Small Fixes
 
@@ -108,7 +109,7 @@ Use a lightweight maintenance lane for small corrections where the intent is alr
 | 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` |
+| tracked CDD change | behavior changes, contract updates, API/data/env/security/CI changes, cross-module refactors, high-risk bug fixes | `specs/changes/<id>/`, `implementation-plan.md`, `tasks.yml`, `context-manifest.md`, 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.
 
@@ -118,8 +119,8 @@ Machine-readable metadata such as future `change.yml` / `trace.yml` should follo
 
 CDD uses two agent classes on purpose:
 
-- `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer`, `repo-context-scanner`, and `spec-drift-auditor` are read-only. They return analysis, verdicts, or an `Agent Log` YAML block; main Claude writes the corresponding files.
-- `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, and `spec-architect` are write-capable. They write their own implementation artifacts and their own `agent-log/*.yml`.
+- `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer`, `repo-context-scanner`, and `spec-drift-auditor` are read-only. They return analysis, verdicts, or optional handoff notes; main Claude writes the corresponding files.
+- `implementation-planner`, `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, and `spec-architect` are write-capable. They write their own implementation artifacts directly.
 
 This split is deliberate:
 
@@ -130,7 +131,8 @@ This split is deliberate:
 **You stay in control by:**
 - Reviewing the `change-classification.md` before implementation starts
 - Checking the `test-plan.md` to confirm the right test families are planned
-- Reading the final `agent-log/qa-reviewer.yml` for the release-readiness verdict
+- Checking `implementation-plan.md` when you want to review the exact execution packet before code changes
+- Reading the final QA summary for the release-readiness verdict
 
 ---
 
@@ -148,7 +150,7 @@ This split is deliberate:
 /cdd-new add Redis caching layer to the reporting queries
 ```
 
-The change-classifier will detect that these are architectural or contract-level changes, assign a higher risk tier (0–2), and automatically require:
+The change-classifier will detect that these are architectural or contract-level changes, assign a higher risk tier (0??), and automatically require:
 - Architecture review (`spec-architect` agent)
 - E2E, resilience, stress, and monkey tests
 - Updated contracts before any implementation begins
@@ -170,7 +172,7 @@ What changes are currently in progress? (cdd-kit list)
 ```
 
 **What happens:**
-1. Claude reads `tasks.yml` and `agent-log/` to determine what was completed
+1. Claude reads `tasks.yml` and existing change artifacts to determine what was completed
 2. Reports the current state (which agents ran, which tasks are pending)
 3. Asks if you want to continue from the next pending agent
 4. Resumes the full agent flow from where it stopped, with no duplication
@@ -189,9 +191,9 @@ 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
+2. Synthesizes `archive.md` ??a permanent record of what changed, what tests were added, and what lessons were found
 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/`
+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
 
 ---
@@ -235,7 +237,7 @@ Active changes:
 
 ## CLI Reference
 
-These are shell commands — not Claude Code skills. Run them directly in the terminal, or Claude Code will run them on your behalf.
+These are shell commands ??not Claude Code skills. Run them directly in the terminal, or Claude Code will run them on your behalf.
 
 ### `cdd-kit init`
 
@@ -271,6 +273,48 @@ Codex currently has no global assets to update, so Codex-only projects report th
 
 ---
 
+### After Updating the npm Package
+
+Updating npm only replaces the `cdd-kit` CLI package. Existing repos and
+global Claude Code assets keep their previously copied agents, skills,
+templates, hooks, and `.cdd/model-policy.json` until you sync them.
+
+Recommended one-command sync after `npm update -g contract-driven-delivery`:
+
+```bash
+cdd-kit refresh          # dry-run preview
+cdd-kit refresh --yes    # apply agents, skills, templates, model policy, hook, code-map
+cdd-kit migrate --all    # add new per-change scaffolds such as implementation-plan.md
+cdd-kit doctor --strict
+```
+
+What gets updated:
+
+| command | updates | preserves |
+|---|---|---|
+| `cdd-kit update --yes` | `~/.claude/agents/` and `~/.claude/skills/` for Claude provider projects | project files |
+| `cdd-kit upgrade --yes` | missing repo files only: contracts, templates, `.cdd/`, guidance, workflows | existing files and project guidance |
+| `cdd-kit refresh --yes` | global agents/skills, missing project files, kit-shipped templates with backup, model policy roles, hooks, `.cdd/code-map.yml` | user source, contracts content, active change content |
+| `cdd-kit migrate --all` | existing `specs/changes/*` metadata and new required scaffolds | implementation code and completed archive history |
+
+For this release, run `cdd-kit refresh --yes` so the new
+`implementation-planner` agent, updated `/cdd-new` and `/cdd-resume` skills,
+fresh `specs/templates/`, and `.cdd/model-policy.json` role binding are all in
+place. Then run `cdd-kit migrate --all` so existing active change directories
+receive `implementation-plan.md`; fill that plan before resuming implementation
+agents.
+
+If you do not want template overwrites, run the narrower path:
+
+```bash
+cdd-kit update --yes
+cdd-kit upgrade --yes
+cdd-kit migrate --all
+cdd-kit doctor --strict
+```
+
+---
+
 ### `cdd-kit doctor`
 
 Inspects repo-level cdd-kit health. Default mode is read-only; `--fix` applies only the safe auto-remediations.
@@ -304,6 +348,33 @@ Use this for old repos that already have `contracts/` or `specs/` but are missin
 
 ---
 
+### `cdd-kit refresh`
+
+Complete sync after upgrading the npm package. Default mode is a dry run.
+
+```bash
+cdd-kit refresh
+cdd-kit refresh --yes
+cdd-kit refresh --yes --provider both
+cdd-kit refresh --yes --no-templates
+```
+
+`refresh --yes` runs the practical upgrade sequence:
+
+1. `cdd-kit update --yes` for global Claude agents and skills.
+2. `cdd-kit upgrade --yes` for missing project files.
+3. Force-refreshes kit-shipped `specs/templates/`, `tests/templates/`,
+   `ci-templates/`, and `.github/workflows/` with backup under
+   `.cdd/.refresh-backup/`.
+4. Re-installs the code-map hook if the project marker exists.
+5. Resyncs `.cdd/model-policy.json` roles from installed agent frontmatter.
+6. Regenerates `.cdd/code-map.yml`.
+
+Run `cdd-kit migrate --all` separately when you need existing
+`specs/changes/*` directories to gain new required artifacts.
+
+---
+
 ### `cdd-kit gate <change-id>`
 
 The single quality gate for a change. Blocks merge if anything is missing or incomplete.
@@ -311,36 +382,27 @@ The single quality gate for a change. Blocks merge if anything is missing or inc
 ```bash
 cdd-kit gate add-jwt-auth
 cdd-kit gate add-jwt-auth --strict
-cdd-kit gate add-jwt-auth --lax
 ```
 
 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 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
-- Tier 0–3 changes have `contract-reviewer` and `qa-reviewer` logs
-- All contract validators pass
+- All required artifacts exist (`change-request.md`, `change-classification.md`, `implementation-plan.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`; new context-governed changes also require `context-manifest.md`)
+- Each artifact has sufficient content and is not a stub.
+- `change-classification.md` contains a tier or risk marker.
+- Atomic `depends-on` upstream changes are completed or archived before dependent work gates.
+- All contract validators pass.
 
 `--strict` additionally:
 - Treats any task with `status: pending` (except IDs listed in `archive-tasks`) as an error
-- Treats runtime-vs-declared `files-read` drift as errors
-- Treats legacy changes missing `context-manifest.md` or `files-read` audit data as errors
-
-Default mode also validates that artifact file pointers listed in `agent-log` evidence exist on disk. Use `--lax` only when cleaning up legacy repos with stale historical logs.
+- Treats legacy changes missing `context-manifest.md` as errors
 
 Pre-commit hook uses `--strict` by default (installed via `cdd-kit install-hooks`).
 
 ```
-✓  gate passed for change: add-jwt-auth
+?? gate passed for change: add-jwt-auth
 
-✗  gate failed for change: feat-001
-✗    change-classification.md: appears to be a stub (< 200 meaningful chars)
-✗    Tier 1 change requires agent-log/e2e-resilience-engineer.yml
-✗    1 task(s) still pending (mark archive items in archive-tasks frontmatter; mark N/A items as status: skipped)
+?? gate failed for change: feat-001
+??   change-classification.md: appears to be a stub (< 200 meaningful chars)
+??   1 task(s) still pending (mark archive items in archive-tasks frontmatter; mark N/A items as status: skipped)
 ```
 
 ---
@@ -368,11 +430,11 @@ Physically moves a completed change from `specs/changes/` to `specs/archive/<yea
 
 ```bash
 cdd-kit archive add-jwt-auth
-# ✓  Archived: specs/changes/add-jwt-auth → specs/archive/2026/add-jwt-auth
-# ✓  Index updated: specs/archive/INDEX.md
+# ?? Archived: specs/changes/add-jwt-auth ??specs/archive/2026/add-jwt-auth
+# ?? Index updated: specs/archive/INDEX.md
 ```
 
-Warns (but does not block) if `tasks.yml` has pending items or `status: gate-blocked`. Use after `/cdd-close` — the skill runs this automatically at the end.
+Warns (but does not block) if `tasks.yml` has pending items or `status: gate-blocked`. Use after `/cdd-close` ??the skill runs this automatically at the end.
 
 ---
 
@@ -382,7 +444,7 @@ Marks a change as abandoned. Updates `tasks.yml` status to `abandoned`, records
 
 ```bash
 cdd-kit abandon add-jwt-auth --reason "using Auth0 instead"
-# ✓  Change add-jwt-auth marked as abandoned.
+# ?? Change add-jwt-auth marked as abandoned.
 ```
 
 ---
@@ -401,10 +463,11 @@ cdd-kit migrate --all --enable-context-governance
 What it upgrades:
 - `tasks.yml`: converts legacy `tasks.md` checklist/frontmatter into structured YAML task records
 - `change-classification.md`: detects old `**Tier:** Tier N` format and appends the new `## Tier\n- N` section so tier-based gate checks activate
-- `context-manifest.md`: adds a legacy manifest scaffold by default so old changes can continue with warning-only context audit behavior
-- `--enable-context-governance`: explicitly adds `context-governance: v1` and a context-governed manifest scaffold, making missing manifest or malformed `files-read` data hard gate failures
+- `implementation-plan.md`: adds the execution-plan scaffold required before backend/frontend/test implementation agents continue
+- `context-manifest.md`: adds a legacy manifest scaffold by default so old changes can use the same pre-read planning layer
+- `--enable-context-governance`: explicitly adds `context-governance: v1` and a context-governed manifest scaffold for pre-read planning
 
-`agent-log/*.yml` must use this `files-read` format for context-governed changes:
+If you choose to emit `agent-log/*.yml`, keep `files-read` optional and concise:
 
 ```yaml
 files-read:
@@ -412,10 +475,8 @@ files-read:
   - src/server/routes/users.ts
 ```
 
-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.
+Paths should be repo-relative. Do not reconstruct this list after the fact;
+use `cdd-kit context check` before invoking agents when read scope matters.
 
 Run this after upgrading from v1.10 or earlier if you have mid-flight changes.
 
@@ -449,11 +510,10 @@ cdd-kit context check add-todos-ui --path src/components/Sidebar.vue src/stores/
 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.
+The check uses `## 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.
 
 ---
 
@@ -466,7 +526,7 @@ cdd-kit context approve add-jwt-auth CER-001
 cdd-kit context approve add-jwt-auth --all-pending   # bulk approve every pending request
 ```
 
-This keeps expansion history explicit while avoiding manual manifest editing. Agents still have to report `files-read` in `agent-log/*.yml`; `cdd-kit gate` audits those paths against the manifest.
+This keeps expansion history explicit while avoiding manual manifest editing.
 
 ---
 
@@ -531,7 +591,7 @@ Installs a pre-commit Git hook that auto-runs `cdd-kit gate --strict` on any sta
 
 ```bash
 cdd-kit install-hooks
-# ✓  pre-commit hook installed at .git/hooks/pre-commit
+# ?? pre-commit hook installed at .git/hooks/pre-commit
 ```
 
 Idempotent. Preserves existing hook content. Bypass with `--no-verify` is possible but defeats enforcement.
@@ -595,8 +655,8 @@ The classifier should read these two files before proposing `context-manifest.md
 
 ```bash
 npm update -g contract-driven-delivery
-cdd-kit upgrade --yes
-cdd-kit context-scan
+cdd-kit refresh --yes
+cdd-kit migrate --all
 cdd-kit doctor --strict
 ```
 
@@ -610,7 +670,9 @@ git add specs/changes/
 git commit -m "chore: migrate changes to current cdd-kit format"
 ```
 
-This gives those legacy specs a new `tasks.yml`, tier markers, and a warning-mode `context-manifest.md` without forcing strict context governance on closed work.
+This gives those legacy specs a new `tasks.yml`, tier markers,
+`implementation-plan.md`, and a warning-mode `context-manifest.md` without
+forcing strict context governance on closed work.
 
 ### Old in-progress specs
 
@@ -624,15 +686,15 @@ cdd-kit doctor --strict
 
 Then choose one path per active change:
 
-- Conservative path: keep the migrated legacy manifest, resume work, and let `gate` warn on missing `files-read` data while the team transitions.
-- Strict path: run `cdd-kit migrate <change-id> --enable-context-governance`, review `context-manifest.md`, narrow `Allowed Paths`, and require agents to report `- files-read:` before continuing implementation.
+- Conservative path: keep the migrated legacy manifest and resume work; use `context check` before invoking agents.
+- Tight context path: run `cdd-kit migrate <change-id> --enable-context-governance`, review `context-manifest.md`, narrow `Allowed Paths`, fill `implementation-plan.md`, and use `cdd-kit context check` before invoking agents.
 
 ### Recommended rollout for production repos already burned by token overuse
 
-1. Run `cdd-kit upgrade --yes` once per repo after updating the npm package.
-2. Run `cdd-kit context-scan` so classifiers can read `specs/context/project-map.md` and `specs/context/contracts-index.md` instead of broad repo searches.
-3. Run `cdd-kit doctor --strict` in CI.
-4. Migrate old completed specs with plain `cdd-kit migrate`.
+1. Run `cdd-kit refresh --yes` once per repo after updating the npm package.
+2. Run `cdd-kit migrate --all` so existing active changes receive the current required artifact set.
+3. Review and fill `implementation-plan.md` before resuming implementation agents on active changes.
+4. Run `cdd-kit doctor --strict` in CI.
 5. Migrate active specs with `cdd-kit migrate --enable-context-governance` only after reviewing the generated manifest.
 6. Teach agents to use `cdd-kit context request/approve/reject/list` instead of silently widening context.
 
@@ -642,31 +704,31 @@ Then choose one path per active change:
 
 ```
 your-repo/
-├── contracts/
-│   ├── api/api-contract.md          ← what endpoints exist and how they behave
-│   ├── css/css-contract.md          ← design tokens, component states
-│   ├── data/data-shape-contract.md  ← schemas, types, nullability
-│   ├── env/env-contract.md          ← every env var, secret flags, defaults
-│   ├── business/business-rules.md   ← rules, edge cases, decision tables
-│   └── ci/ci-gate-contract.md       ← gate tiers, promotion, rollback
-├── specs/
-│   ├── project-profile.md           ← overall system description
-│   ├── changes/                     ← active in-progress changes
-│   │   └── <change-id>/
-│   │       ├── change-request.md    (required)
-│   │       ├── change-classification.md (required)
-│   │       ├── test-plan.md         (required)
-│   │       ├── ci-gates.md          (required)
-│   │       ├── tasks.yml            (required)
-│   │       └── agent-log/           ← machine-verifiable evidence per agent
-│   ├── archive/                     ← completed and abandoned changes
-│   │   ├── INDEX.md
-│   │   └── 2026/<change-id>/
-│   └── templates/
-├── tests/
-├── CLAUDE.md                        ← Claude's project guide (edit this)
-├── AGENTS.md                        ← agent roster (auto-managed)
-└── CODEX.md                         ← Codex project guide when initialized for Codex
+???€ contracts/
+??  ???€ api/api-contract.md          ??what endpoints exist and how they behave
+??  ???€ css/css-contract.md          ??design tokens, component states
+??  ???€ data/data-shape-contract.md  ??schemas, types, nullability
+??  ???€ env/env-contract.md          ??every env var, secret flags, defaults
+??  ???€ business/business-rules.md   ??rules, edge cases, decision tables
+??  ???€ ci/ci-gate-contract.md       ??gate tiers, promotion, rollback
+???€ specs/
+??  ???€ project-profile.md           ??overall system description
+??  ???€ changes/                     ??active in-progress changes
+??  ??  ???€ <change-id>/
+??  ??      ???€ change-request.md    (required)
+??  ??      ???€ change-classification.md (required)
+??  ??      ???€ test-plan.md         (required)
+??  ??      ???€ ci-gates.md          (required)
+??  ??      ???€ tasks.yml            (required)
+??  ??      ???€ agent-log/           optional handoff notes
+??  ???€ archive/                     ??completed and abandoned changes
+??  ??  ???€ INDEX.md
+??  ??  ???€ 2026/<change-id>/
+??  ???€ templates/
+???€ tests/
+???€ CLAUDE.md                        ??Claude's project guide (edit this)
+???€ AGENTS.md                        ??agent roster (auto-managed)
+???€ CODEX.md                         ??Codex project guide when initialized for Codex
 ```
 
 ---
@@ -675,9 +737,9 @@ your-repo/
 
 | Tier | Risk level | Example changes | Extra agents |
 |---|---|---|---|
-| 0–1 | High / critical | Auth, payments, migrations, concurrency | E2E + monkey + stress/soak |
-| 2–3 | Medium | Feature with API change, bug fix with behavior change | Contract review + QA |
-| 4–5 | Low | Docs, prompts, config only, no behavior change | Contract review + QA |
+| 0?? | High / critical | Auth, payments, migrations, concurrency | E2E + monkey + stress/soak |
+| 2?? | Medium | Feature with API change, bug fix with behavior change | Contract review + QA |
+| 4?? | Low | Docs, prompts, config only, no behavior change | Contract review + QA |
 
 ---
 

package/assets/AGENTS.template.md

@@ -6,6 +6,7 @@ Use these agents as reusable Claude Code subagents. Project-level agents may be
 
 - `change-classifier`: routes requests into change types and required artifacts.
 - `repo-context-scanner`: detects tech stack, commands, contracts, tests, and CI/CD.
+- `implementation-planner`: writes the execution plan that implementation agents follow.
 - `spec-architect`: evaluates architectural impact and produces design constraints.
 - `contract-reviewer`: owns API, CSS, env, data, business, and CI contract consistency.
 - `test-strategist`: maps acceptance criteria to test families.

package/assets/CLAUDE.template.md

@@ -52,14 +52,18 @@ For context-governed changes, read `specs/changes/<change-id>/context-manifest.m
   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
+- Optional agent-log notes are 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.
+- After each agent returns, tick the related `tasks.yml` items immediately,
+  and only then move to the next agent.
+- Do not start backend/frontend/test implementation agents until
+  `implementation-plan.md` is ready; implementation agents should follow that
+  plan and report `blocked` instead of inferring missing scope from chat
+  history.
 - 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.

package/assets/CODEX.template.md

@@ -22,9 +22,9 @@ Read `specs/changes/<change-id>/context-manifest.md` before using file-reading o
   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:`.
+- Optional `agent-log/*.yml` notes may include `files-read:` when that list is cheap and accurate.
 
-Required `agent-log/*.yml` format:
+Optional `agent-log/*.yml` read note:
 
 ```yaml
 files-read:
@@ -32,7 +32,7 @@ files-read:
   - src/server/routes/users.ts
 ```
 
-Every entry must be a repo-relative path. Do not omit files, use absolute paths, or use `..`.
+Every entry should be a repo-relative path. Do not reconstruct this list after the fact.
 
 ## Hot And Cold Data
 
@@ -44,8 +44,12 @@ 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.
+- After each agent returns, tick the related `tasks.yml` items immediately,
+  then move to the next agent.
+- Do not start backend/frontend/test implementation agents until
+  `implementation-plan.md` is ready; implementation agents should follow that
+  plan and report `blocked` instead of inferring missing scope from chat
+  history.
 - 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.