contract-driven-delivery 1.12.0 → 2.0.0

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

@@ -1,6 +1,6 @@
 ---
 name: cdd-resume
-description: Resume an in-progress change across sessions. Reads tasks.md and agent-log/ to determine where to continue. Args: <change-id>
+description: Resume an in-progress change across sessions. Reads tasks.yml and agent-log/ to determine where to continue. Args: <change-id>
 ---
 
 # cdd-resume — Resume a Change
@@ -17,9 +17,9 @@ Provide the `change-id`. If unsure, run `cdd-kit list` to see active changes.
 
 ## Step 0: Detect format version
 
-Before reading state, check if `specs/changes/<change-id>/tasks.md` starts with `---` (YAML frontmatter).
+Before reading state, check if `specs/changes/<change-id>/tasks.yml` exists.
 
-If it does NOT start with `---`, this change was created with a pre-v1.11 version of cdd-kit. Run:
+If only `specs/changes/<change-id>/tasks.md` exists (no `tasks.yml`), this change was created with a pre-v2.0 version of cdd-kit. Run:
 
 ```
 cdd-kit migrate <change-id>
@@ -27,8 +27,8 @@ cdd-kit migrate <change-id>
 
 Then commit the migration:
 ```
-git add specs/changes/<change-id>/tasks.md specs/changes/<change-id>/change-classification.md
-git commit -m "chore: migrate <change-id> to v1.11 format"
+git add specs/changes/<change-id>/tasks.yml specs/changes/<change-id>/agent-log
+git commit -m "chore: migrate <change-id> to v2.0 YAML format"
 ```
 
 If there are many mid-flight changes, suggest `cdd-kit migrate --all` instead.
@@ -38,17 +38,17 @@ If there are many mid-flight changes, suggest `cdd-kit migrate --all` instead.
 ## Step 1: Read current state
 
 Read only these state files first:
-- `specs/changes/<change-id>/tasks.md`
+- `specs/changes/<change-id>/tasks.yml`
 - `specs/changes/<change-id>/context-manifest.md` if present
-- `specs/changes/<change-id>/agent-log/*.md`
+- `specs/changes/<change-id>/agent-log/*.yml`
 - `specs/changes/<change-id>/change-classification.md`
 
 Do not run broad repository search during resume. Do not read `src/`, `tests/`, or `contracts/` unless the current `context-manifest.md` authorizes that path or an approved expansion lists it.
 
-From `tasks.md`:
-- Identify all `[x]` (done) items
-- Identify all `[-]` (N/A) items  
-- Identify all `[ ]` (pending) items
+From `tasks.yml`:
+- Identify all `status: done` items
+- Identify all `status: skipped` (N/A) items
+- Identify all `status: pending` items
 
 Read `specs/changes/<change-id>/agent-log/` to list which agents have already run.
 
@@ -73,7 +73,7 @@ Tier: <tier>
 Status: <in-progress | gate-blocked>
 
 Completed agents: <list from agent-log/>
-Pending tasks: <list of [ ] items>
+Pending tasks: <list of status: pending items>
 Pending context expansions: <none | list request ids and paths>
 Allowed context: <short summary from context-manifest.md>
 
@@ -86,7 +86,7 @@ Ask the user: "Continue from <next-agent>? (yes/no)"
 
 ## Step 3: Continue the flow
 
-If user confirms, resume from the next agent in the Tier sequence (refer to `/cdd-new` Step 3 for the agent order). 
+If user confirms, resume from the next agent in the Tier sequence (refer to `/cdd-new` Step 3 for the agent order, and `/cdd-new` "Agent stage badges" for the colored badges to use in your narration).
 
 **Critical**: Inject this block at the start of every agent prompt:
 
@@ -108,7 +108,7 @@ Continue until all required agents are done, then run `cdd-kit gate <change-id>`
 
 - Never re-run an agent that already has `status: complete` 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.md`, `context-manifest.md`, and `agent-log/`
+- Never use broad search to reconstruct state; resume from `tasks.yml`, `context-manifest.md`, and `agent-log/`
 - Never continue past pending Context Expansion Requests
-- If tasks.md has `status: abandoned`, report to user and stop
-- If tasks.md has `status: gate-blocked`, go directly to gate retry (max 3)
+- If tasks.yml has `status: abandoned`, report to user and stop
+- If tasks.yml has `status: gate-blocked`, go directly to gate retry (max 3)

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

@@ -116,3 +116,9 @@ When using this skill, produce concrete artifact content instead of vague recomm
 - `scripts/validate_spec_traceability.py`: check coarse traceability between spec, tasks, tests, and CI gates.
 
 Run scripts with Python 3 from the repository root.
+
+## Output discipline (file formats)
+
+- `tasks.yml`: structured YAML, validated by `src/schemas/tasks.schema.ts`.
+- `agent-log/<agent>.yml`: structured YAML per `references/agent-log-protocol.md`.
+- All other change artifacts remain markdown prose.

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

@@ -0,0 +1,147 @@
+# Agent Log Protocol (YAML)
+
+All cdd-kit agents share the same machine-verifiable agent-log format. This
+file is the single source of truth — agent prompts reference it instead of
+inlining the format. `cdd-kit gate` validates these files against
+`src/schemas/agent-log.schema.ts` (JSON Schema, draft-07). Drift here equals
+silent gate skips, so do not re-document this in agent prompts.
+
+## Output target
+
+Each agent writes (or has main Claude write) one file per run:
+
+```
+specs/changes/<change-id>/agent-log/<agent-name>.yml
+```
+
+If the same agent runs more than once for a change (e.g., after fix-back),
+overwrite the file — only the latest run is gate-relevant.
+
+## Required structure
+
+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>
+status: complete            # complete | needs-review | blocked
+files-read:
+  - <repo-relative path>
+  - <repo-relative path>
+artifacts:
+  - { type: <evidence-type>, pointer: <concrete pointer> }
+  - { type: <evidence-type>, pointer: <concrete pointer> }
+next-action: <one line, or "none">
+notes: <optional free-form>
+```
+
+### Field rules
+
+| field | required | rule |
+|---|---|---|
+| `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` |
+| `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` |
+| `notes` | no | optional |
+
+#### `files-read`
+
+Required when `tasks.yml` has `context-governance: v1`. Each entry is a
+repo-relative path. Absolute paths and `..` traversal are rejected. If you
+legitimately read nothing beyond your own change directory, write:
+
+```yaml
+files-read:
+  - specs/changes/<change-id>/
+```
+
+#### `artifacts`
+
+Concrete pointers only. Allowed forms:
+
+- `path/to/file.ts:10-45`
+- `tests/foo.test.ts::should reject empty body`
+- `cdd-kit gate <id>: 0 errors`
+- `contracts/api/api-contract.md#endpoints`
+
+Never `verified`, `OK`, `done`, or unscoped prose.
+
+#### `next-action`
+
+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.
+
+## 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.
+
+## Self-validation before submitting your response
+
+**Every agent MUST self-validate its draft agent-log YAML before finishing.**
+A malformed log forces `cdd-kit gate` to fail, which forces the skill to
+re-invoke you, which costs the user another full agent round. Self-lint is
+~5 seconds; a re-run is minutes and dollars.
+
+Before sending your final response, re-read the YAML you intend to write and
+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.
+- [ ] **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" }`
+      - GOOD: `{ type: files-changed, pointer: "src/api/users.ts:45-67" }`
+      - GOOD: `{ type: test-output, pointer: "5 passed (last 10 lines: …)" }`
+      - BAD: `{ type: tests-added, pointer: verified }`
+      - BAD: `{ type: files-changed, pointer: yes }`
+      - BAD: `{ type: contract, pointer: OK }`
+      Reject any line whose pointer would not let a reviewer click through.
+- [ ] **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.
+- [ ] **Every `files-read` entry**: repo-relative path, no leading `/`, no
+      `..`, no `~`. If you read your own change directory only, write
+      `- specs/changes/<change-id>/`.
+- [ ] **YAML is parseable**: indentation is consistent (2 spaces), strings
+      with special characters (`:`, `#`, leading numbers like `001`) are
+      quoted.
+
+If any check fails, **fix the YAML before sending your response**. Do not
+ship a known-bad log and rely on the gate to catch it.
+
+## Gate enforcement summary
+
+`cdd-kit gate` rejects an agent log when any of these are true:
+
+1. The file is missing for a tier-required agent (see CONTRACTS for tier matrix).
+2. YAML fails to parse, or top-level is not a mapping.
+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.
+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
+   not exist on disk; or any runtime-logged read not declared in `files-read`.
+
+## Why this lives in references/
+
+The historical mistake was duplicating the protocol inside every agent prompt.
+Sixteen agents × ~30 lines = ~480 lines of identical text loaded on every
+spawn. Moving it here:
+
+- Cuts per-agent prompt size by 25–35%.
+- Makes drift between agents impossible (one file to change).
+- Lets gate.ts behavior, schemas, tests, and prompts stay in sync via this
+  single doc.

package/assets/skills/contract-driven-delivery/scripts/generate_change_scaffold.py

@@ -24,7 +24,7 @@ def main():
         'contracts.md':'contracts.md',
         'test-plan.md':'test-plan.md',
         'ci-gates.md':'ci-gates.md',
-        'tasks.md':'tasks.md',
+        'tasks.yml':'tasks.yml',
         'qa-report.md':'qa-report.md',
         'regression-report.md':'regression-report.md',
         'archive.md':'archive.md',

package/assets/skills/contract-driven-delivery/scripts/validate_spec_traceability.py

@@ -2,7 +2,7 @@
 """Coarse traceability check for a change folder."""
 from pathlib import Path
 import argparse, sys
-REQUIRED=['change-classification.md','test-plan.md','ci-gates.md','tasks.md']
+REQUIRED=['change-classification.md','test-plan.md','ci-gates.md','tasks.yml']
 def check_change_dir(d):
     """Check one change directory. Returns list of error strings (empty = pass)."""
     errors=[]

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

@@ -0,0 +1,14 @@
+change-id: feat-001
+agent: backend-engineer
+timestamp: 2026-04-27T14:30:00Z
+status: complete
+files-read:
+  - contracts/api/api-contract.md
+  - src/api/users.ts
+  - specs/changes/feat-001/test-plan.md
+artifacts:
+  - { type: files-changed,     pointer: "src/api/users.ts:45-67" }
+  - { type: tests-added,       pointer: "tests/api/users.test.ts::should reject empty body" }
+  - { type: contracts-touched, pointer: "contracts/api/api-contract.md#endpoints" }
+  - { type: test-output,       pointer: "5 passed (vitest run --filter users)" }
+next-action: none

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

@@ -18,7 +18,7 @@
 - reason: (fill only if yes)
 
 ## Required Artifacts
-Always required: change-request.md, change-classification.md, test-plan.md, ci-gates.md, tasks.md
+Always required: change-request.md, change-classification.md, test-plan.md, ci-gates.md, tasks.yml
 
 ## Optional Artifacts (default: no — set yes only with explicit reason)
 | artifact | create? | reason |

package/assets/skills/contract-driven-delivery/templates/tasks.yml

@@ -0,0 +1,39 @@
+change-id: <change-id>
+status: in-progress
+tier: null
+context-governance: v1
+archive-tasks:
+  - "7.1"
+  - "7.2"
+depends-on: []
+
+tasks:
+  # status: pending | done | skipped
+  - { id: "1.1", section: Preparation, title: "Confirm classification and required artifacts", status: pending }
+  - { id: "1.2", section: Preparation, title: "Confirm contracts to update", status: pending }
+  - { id: "1.3", section: Preparation, title: "Confirm CI/CD gate plan", status: pending }
+  - { id: "2.1", section: "Contract Updates", title: "API contract", status: pending }
+  - { id: "2.2", section: "Contract Updates", title: "CSS/UI contract", status: pending }
+  - { id: "2.3", section: "Contract Updates", title: "Env contract", status: pending }
+  - { id: "2.4", section: "Contract Updates", title: "Data shape contract", status: pending }
+  - { id: "2.5", section: "Contract Updates", title: "Business logic contract", status: pending }
+  - { id: "2.6", section: "Contract Updates", title: "CI/CD contract", status: pending }
+  - { id: "3.1", section: "Tests First", title: "Unit/contract tests", status: pending }
+  - { id: "3.2", section: "Tests First", title: "Integration tests", status: pending }
+  - { id: "3.3", section: "Tests First", title: "E2E/resilience tests", status: pending }
+  - { id: "3.4", section: "Tests First", title: "Data-boundary/monkey tests", status: pending }
+  - { id: "3.5", section: "Tests First", title: "Stress/soak tests if required", status: pending }
+  - { id: "4.1", section: Implementation, title: "Backend", status: pending }
+  - { id: "4.2", section: Implementation, title: "Frontend", status: pending }
+  - { id: "4.3", section: Implementation, title: "Env/deploy", status: pending }
+  - { id: "4.4", section: Implementation, title: "CI/CD workflows", status: pending }
+  - { id: "5.1", section: Review, title: "UI/UX review", status: pending }
+  - { id: "5.2", section: Review, title: "Visual review", status: pending }
+  - { id: "5.3", section: Review, title: "Contract review", status: pending }
+  - { id: "5.4", section: Review, title: "QA review", status: pending }
+  - { id: "6.1", section: Verification, title: "Local gates", status: pending }
+  - { id: "6.2", section: Verification, title: "PR required gates", status: pending }
+  - { 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 }

package/assets/specs-templates/change-classification.md

@@ -18,7 +18,7 @@
 - reason: (fill only if yes)
 
 ## Required Artifacts
-Always required: change-request.md, change-classification.md, test-plan.md, ci-gates.md, tasks.md
+Always required: change-request.md, change-classification.md, test-plan.md, ci-gates.md, tasks.yml
 
 ## Optional Artifacts (default: no — set yes only with explicit reason)
 | artifact | create? | reason |

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

@@ -1,22 +1,16 @@
 # Context Manifest
 
-This manifest defines the approved context boundaries for agents working on this change.
+This manifest defines the approved context boundaries for agents working on
+this change. The forbidden-paths baseline lives in `.cdd/context-policy.json`
+and is automatically applied by `cdd-kit gate` — do not duplicate it here.
 
 ## Affected Surfaces
 -
 
 ## Allowed Paths
 - specs/changes/<change-id>/
-
-## Forbidden Paths
-- .claude/worktrees/**
-- .git/**
-- node_modules/**
-- dist/**
-- build/**
-- assets/**
-- specs/archive/**
-- specs/changes/* except specs/changes/<change-id>/
+- specs/context/project-map.md
+- specs/context/contracts-index.md
 
 ## Required Contracts
 -
@@ -35,8 +29,8 @@ This manifest defines the approved context boundaries for agents working on this
 ## Context Expansion Requests
 
 <!--
-Agents must request context expansion instead of reading outside their work packet.
-Use this format only for real requests:
+Agents must request context expansion instead of reading outside their work
+packet. Format example for real requests:
 
 - request-id: CER-001
   requested_paths:
@@ -44,6 +38,7 @@ Use this format only for real requests:
   reason: why this file is required
   status: pending
 -->
+-
 
 ## Approved Expansions
 -

package/assets/specs-templates/tasks.yml

@@ -0,0 +1,39 @@
+change-id: <change-id>
+status: in-progress
+tier: null
+context-governance: v1
+archive-tasks:
+  - "7.1"
+  - "7.2"
+depends-on: []
+
+tasks:
+  # status: pending | done | skipped
+  - { id: "1.1", section: Preparation, title: "Confirm classification and required artifacts", status: pending }
+  - { id: "1.2", section: Preparation, title: "Confirm contracts to update", status: pending }
+  - { id: "1.3", section: Preparation, title: "Confirm CI/CD gate plan", status: pending }
+  - { id: "2.1", section: "Contract Updates", title: "API contract", status: pending }
+  - { id: "2.2", section: "Contract Updates", title: "CSS/UI contract", status: pending }
+  - { id: "2.3", section: "Contract Updates", title: "Env contract", status: pending }
+  - { id: "2.4", section: "Contract Updates", title: "Data shape contract", status: pending }
+  - { id: "2.5", section: "Contract Updates", title: "Business logic contract", status: pending }
+  - { id: "2.6", section: "Contract Updates", title: "CI/CD contract", status: pending }
+  - { id: "3.1", section: "Tests First", title: "Unit/contract tests", status: pending }
+  - { id: "3.2", section: "Tests First", title: "Integration tests", status: pending }
+  - { id: "3.3", section: "Tests First", title: "E2E/resilience tests", status: pending }
+  - { id: "3.4", section: "Tests First", title: "Data-boundary/monkey tests", status: pending }
+  - { id: "3.5", section: "Tests First", title: "Stress/soak tests if required", status: pending }
+  - { id: "4.1", section: Implementation, title: "Backend", status: pending }
+  - { id: "4.2", section: Implementation, title: "Frontend", status: pending }
+  - { id: "4.3", section: Implementation, title: "Env/deploy", status: pending }
+  - { id: "4.4", section: Implementation, title: "CI/CD workflows", status: pending }
+  - { id: "5.1", section: Review, title: "UI/UX review", status: pending }
+  - { id: "5.2", section: Review, title: "Visual review", status: pending }
+  - { id: "5.3", section: Review, title: "Contract review", status: pending }
+  - { id: "5.4", section: Review, title: "QA review", status: pending }
+  - { id: "6.1", section: Verification, title: "Local gates", status: pending }
+  - { id: "6.2", section: Verification, title: "PR required gates", status: pending }
+  - { 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 }