contract-driven-delivery 1.16.0 → 2.0.1

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

@@ -89,12 +89,12 @@ inevitable re-classification when the agents discover the ambiguity.
 
 **This distinction is critical — follow it for every step:**
 
-| Agent type | Who writes artifact files | Who writes agent-log | Who ticks tasks.md |
-|------------|--------------------------|----------------------|--------------------|
+| Agent type | Who writes artifact files | Who writes agent-log | Who updates tasks.yml |
+|------------|--------------------------|----------------------|----------------------|
 | Read-only agents (no Edit tool): `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer` | YOU (main Claude) | YOU (main Claude) | YOU (main Claude) |
 | Write-capable agents (have Edit): `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, `spec-architect` | The agent itself | The agent itself | YOU (main Claude) |
 
-**Rule**: After EVERY agent completes (whether it writes itself or you write for it), YOU must update the relevant `tasks.md` checkbox(es) from `[ ]` to `[x]`.
+**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`.
 
 ---
 
@@ -106,7 +106,7 @@ Note: `archive.md` is created during `/cdd-close`, not during `/cdd-new` — it
 
 If the classifier marks an artifact as `no` or leaves it blank, **do not create the file** — even if a review agent could contribute to it.
 
-The 5 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`.
+The 5 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`.
 
 ## Step 1: Generate change-id, scaffold, and scan context
 
@@ -146,7 +146,7 @@ the kit and is bundled into every install.
 | `change-classification.md` | `specs/templates/change-classification.md` | Replace blank template with classifier output (Step 2) |
 | `test-plan.md` | `specs/templates/test-plan.md` | `test-strategist` writes this directly |
 | `ci-gates.md` | `specs/templates/ci-gates.md` | `ci-cd-gatekeeper` writes this directly |
-| `tasks.md` | `specs/templates/tasks.md` | Tick checkboxes as agents complete; backfill `tier:` frontmatter from classifier (Step 2.4) |
+| `tasks.yml` | `specs/templates/tasks.yml` | Tick checkboxes as agents complete; backfill `tier:` frontmatter from classifier (Step 2.4) |
 | `context-manifest.md` | `specs/templates/context-manifest.md` | Replace from classifier `## Context Manifest Draft` (Step 2) |
 
 If `cdd-kit new` reports a missing template, run `cdd-kit upgrade --yes`.
@@ -207,14 +207,14 @@ If any of these are missing or still hold the literal placeholder text, STOP. Re
 ### When the classifier output passes lint
 
 1. **YOU write** `specs/changes/<change-id>/change-classification.md` — replace the blank template with the classifier's classification output.
-2. **YOU write** `specs/changes/<change-id>/agent-log/change-classifier.md` — copy the Agent Log block from the classifier's response.
+2. **YOU write** `specs/changes/<change-id>/agent-log/change-classifier.yml` — copy the Agent Log block from the classifier's response.
 3. **YOU update** `specs/changes/<change-id>/context-manifest.md` from the classifier's `## Context Manifest Draft`.
-4. **YOU update** `tasks.md` frontmatter: set `tier: <N>` to the classifier's tier digit. This is now the authoritative source for `cdd-kit gate` tier-based agent enforcement (the classification.md `## Tier` section is fallback only).
-5. **YOU tick** `tasks.md` item `1.1`.
+4. **YOU update** `tasks.yml` frontmatter: set `tier: <N>` to the classifier's tier digit. This is now the authoritative source for `cdd-kit gate` tier-based agent enforcement (the classification.md `## Tier` section is fallback only).
+5. **YOU tick** `tasks.yml` item `1.1`.
 
 Wait until these five writes are done before continuing.
 
-**After writing change-classification.md**: read the classifier's `## Tasks Not Applicable` list. For each listed task ID (e.g., `2.2`, `4.2`), update `tasks.md` to change that item from `[ ]` to `[-]`. Do this before invoking any other agent.
+**After writing change-classification.md**: read the classifier's `## Tasks Not Applicable` list. For each listed task ID (e.g., `2.2`, `4.2`), update `tasks.yml` to change that item's `status:` from `pending` to `skipped`. Do this before invoking any other agent.
 
 ---
 
@@ -222,9 +222,9 @@ Wait until these five writes are done before continuing.
 
 Read `change-classification.md` to determine the tier. Then invoke agents **in the exact order below**.
 
-**For each read-only agent**: wait for its text response → YOU write its artifact file(s) → YOU write its agent-log → YOU tick relevant tasks.md item(s).
+**For each read-only agent**: wait for its text response → YOU write its artifact file(s) → YOU write its agent-log → YOU tick relevant tasks.yml item(s).
 
-**For each write-capable agent**: wait for it to confirm completion → YOU tick relevant tasks.md item(s).
+**For each write-capable agent**: wait for it to confirm completion → YOU tick relevant tasks.yml item(s).
 
 If any agent sets `status: blocked` in its log, halt immediately and report the agent's `next-action` to the user — do not proceed to subsequent agents.
 
@@ -292,11 +292,11 @@ prompt; the agent's behavior is defined by the agent prompt files in
 ### Tier 4–5 (low risk: docs, prompts, config-only, no behavior change)
 
 1. **`contract-reviewer`** (read-only) — confirm no contracts are touched or all touched ones are already updated.
-   - YOU write: `agent-log/contract-reviewer.md`
+   - YOU write: `agent-log/contract-reviewer.yml`
    - YOU tick: `1.2`, applicable items in section 2
 
 2. **`qa-reviewer`** (read-only) — confirm release readiness.
-   - YOU write: `agent-log/qa-reviewer.md`
+   - YOU write: `agent-log/qa-reviewer.yml`
    - YOU tick: `5.4`
 
 ---
@@ -304,7 +304,7 @@ prompt; the agent's behavior is defined by the agent prompt files in
 ### Tier 2–3 (normal: feature, enhancement, bug fix with behavior change)
 
 1. **`contract-reviewer`** (read-only) — update or create contracts in `contracts/` before any implementation starts.
-   - YOU write: `agent-log/contract-reviewer.md`
+   - YOU write: `agent-log/contract-reviewer.yml`
    - YOU tick: `1.2`, applicable items in section 2
 
 2. **`test-strategist`** (write-capable) — writes `specs/changes/<change-id>/test-plan.md` directly.
@@ -316,31 +316,31 @@ prompt; the agent's behavior is defined by the agent prompt files in
 
 4. **`backend-engineer`** (write-capable) — if the change touches server, API, data, or business logic. Writes implementation and its own agent-log.
    - YOU tick: `4.1` and/or `4.3` based on scope
-   - Note: `tasks.md` items 3.1–3.2 (unit/contract/integration tests) are written by `backend-engineer` and/or `frontend-engineer` in TDD fashion — failing tests first, implementation second. Items 3.3–3.5 are written by dedicated test engineers (Tier 0–1 only or when classifier explicitly requires them).
+   - Note: `tasks.yml` items 3.1–3.2 (unit/contract/integration tests) are written by `backend-engineer` and/or `frontend-engineer` in TDD fashion — failing tests first, implementation second. Items 3.3–3.5 are written by dedicated test engineers (Tier 0–1 only or when classifier explicitly requires them).
 
 5. **`frontend-engineer`** (write-capable) — if the change touches UI, components, or client-side behavior. Writes implementation and its own agent-log.
    - YOU tick: `4.2`
 
 6. **`dependency-security-reviewer`** (read-only) — if the change touches lockfiles, package manifests, or DB migrations.
    - **Only invoke if** `change-classification.md` lists lockfiles, package manifests, or DB migrations as affected.
-   - YOU write: `agent-log/dependency-security-reviewer.md`
+   - YOU write: `agent-log/dependency-security-reviewer.yml`
    - YOU tick: applicable security-related items
 
 7. **`ui-ux-reviewer`** (read-only) — if any UI change (run alongside or after frontend-engineer).
    - **Only invoke if** classifier marks UI/CSS as affected.
-   - YOU write: `agent-log/ui-ux-reviewer.md`
+   - YOU write: `agent-log/ui-ux-reviewer.yml`
    - YOU tick: `5.1`
 
 8. **`visual-reviewer`** (read-only) — if any UI change (run after ui-ux-reviewer).
    - **Only invoke if** classifier marks UI/CSS as affected.
-   - YOU write: `agent-log/visual-reviewer.md`
+   - YOU write: `agent-log/visual-reviewer.yml`
    - YOU tick: `5.2`
 
 9. **`ci-cd-gatekeeper`** (write-capable) — writes `specs/changes/<change-id>/ci-gates.md` directly.
    - YOU tick: `1.3`, `4.4`, applicable items in section 6
 
 10. **`qa-reviewer`** (read-only) — release readiness decision (always last).
-    - YOU write: `agent-log/qa-reviewer.md`
+    - YOU write: `agent-log/qa-reviewer.yml`
     - YOU tick: `5.4`
 
 ---
@@ -371,14 +371,14 @@ All agents from Tier 2–3, plus insert these after `frontend-engineer` / `backe
 
 ## Step 4: Run the gate
 
-After all required agents have completed and all tasks.md items for their sections are ticked:
+After all required agents have completed and all tasks.yml items for their sections are ticked:
 
 ```
 cdd-kit gate <change-id>
 ```
 
 **If gate passes**:
-- YOU tick: `tasks.md` item `6.1`
+- YOU tick: `tasks.yml` item `6.1`
 - Proceed to Step 5.
 
 **If gate fails — structured fix-back routing**:
@@ -389,11 +389,11 @@ matches one of them.
 
 | Error pattern | Route to | Re-invocation prompt seed |
 |---|---|---|
-| `agent-log/<name>.md: …` | the named agent | "PREVIOUS GATE FAILURE FOR THIS AGENT: <full error line>. Fix only your `agent-log/<name>.md`. Re-output your Agent Log block." |
+| `agent-log/<name>.yml: …` | the named agent | "PREVIOUS GATE FAILURE FOR THIS AGENT: <full error line>. Fix only your `agent-log/<name>.yml`. Re-output your Agent Log block." |
 | `change-classification.md: …` | `change-classifier` | "PREVIOUS CLASSIFICATION FAILED GATE: <error>. Re-emit only the failing section." |
 | `context-manifest.md: …` | `change-classifier` | "PREVIOUS MANIFEST FAILED GATE: <error>. Re-emit `## Context Manifest Draft`." |
-| `tasks.md: …` (frontmatter / pending) | YOU (main Claude) — direct edit | n/a — fix `tasks.md` yourself. Don't re-invoke an agent for a file you own. |
-| `Tier <N> change requires agent-log/<X>.md` | invoke the missing agent `<X>` | "TIER <N> REQUIRES THIS LOG. Run your full work, not just the log." |
+| `tasks.yml: …` (frontmatter / pending) | YOU (main Claude) — direct edit | n/a — fix `tasks.yml` yourself. Don't re-invoke an agent for a file you own. |
+| `Tier <N> change requires agent-log/<X>.yml` | invoke the missing agent `<X>` | "TIER <N> REQUIRES THIS LOG. Run your full work, not just the log." |
 | `dependency <id>: upstream change is not completed` | n/a — STOP | Tell user: "Upstream change `<id>` must complete before this change can gate. Run `/cdd-new <id>` first or run `cdd-kit archive <id>` if it's already done." |
 | `validators returned non-zero` | `contract-reviewer` | "PREVIOUS CONTRACT VALIDATION FAILED: <last 10 lines of validator stderr>. Reconcile contracts." |
 
@@ -422,7 +422,7 @@ iteration must be on a strictly smaller error set — if the same error returns
 twice, halt and surface to user (an agent stuck in a loop is more expensive
 than a human read).
 
-**Terminal state after 3 failures**: Update `tasks.md` frontmatter with
+**Terminal state after 3 failures**: Update `tasks.yml` frontmatter with
 `status: gate-blocked` and report all remaining errors to the user, grouped
 by responsible agent, so they know who to manually direct next.
 
@@ -441,7 +441,7 @@ Agents invoked: <list in order>
 Gate: PASSED
 
 Tasks completed:
-- [x] all applicable items checked in specs/changes/<change-id>/tasks.md
+- [x] all applicable items have status: done in specs/changes/<change-id>/tasks.yml
 
 All artifacts written to: specs/changes/<change-id>/
 
@@ -473,8 +473,8 @@ Please review the above items and re-run: cdd-kit gate <change-id>
 - Never start implementation (backend/frontend-engineer) before `contract-reviewer` has completed for Tier 0–3 changes
 - Never skip `test-plan.md` for Tier 0–3 changes
 - Never skip `ci-gates.md` for any implementation change
-- Every agent must have its `agent-log/<name>.md` written — YOU write it for read-only agents after receiving their response; write-capable agents write their own
-- Tick the relevant `tasks.md` checkbox immediately after each agent completes — do not batch
+- Every agent must have its `agent-log/<name>.yml` written — YOU write it for read-only agents after receiving their response; write-capable agents write their own
+- Tick the relevant `tasks.yml` checkbox immediately after each agent completes — do not batch
 - `qa-reviewer` always runs last and makes the release-readiness decision
 
 ---

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>
 
@@ -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

@@ -1,16 +1,17 @@
-# Agent Log Protocol
+# 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` parses these files; drift here equals silent gate
-skips, so do not re-document this in agent prompts.
+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>.md
+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),
@@ -18,42 +19,63 @@ overwrite the file — only the latest run is gate-relevant.
 
 ## Required structure
 
-```
-# <Agent Display Name> Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- files-read:
+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:
-  - <evidence-type>: <concrete pointer>
-  - <evidence-type>: <concrete pointer>
-- next-action: <one line, or "none">
+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
 
-- `change-id` — must match the directory name. Mismatch is a contract violation.
-- `timestamp` — ISO 8601 UTC. Used by spec-drift-auditor for ordering.
-- `status` — exactly one of `complete | needs-review | blocked`. Anything
-  else (e.g. `done`, `OK`, `pending`) fails gate.
-- `files-read` — required for context-governed changes (`tasks.md` frontmatter
-  has `context-governance: v1`). Each entry must be a repo-relative path.
-  Absolute paths and `..` traversal are rejected. If you legitimately read
-  nothing beyond your own change directory, write:
-  ```
-  - 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` (command + outcome)
-  - `contracts/api/api-contract.md#endpoints` (file + anchor)
-  - **Never** `verified`, `OK`, `done`, or unscoped prose.
-- `next-action` — when `status: blocked`, this must be ≥ 10 chars and
-  not `none`. When `status: complete`, `none` is acceptable.
+| 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
 
@@ -64,34 +86,39 @@ agent prompt, also update the qa-reviewer checklist.
 
 ## Self-validation before submitting your response
 
-**Every agent MUST self-validate its draft Agent Log block before finishing.**
-A malformed log block 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
+**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 your `## Agent Log` block and
+Before sending your final response, re-read the YAML you intend to write and
 verify each item:
 
-- [ ] **All four required keys exist**: `status`, `files-read`, `artifacts`,
-      `next-action`. (Plus `change-id`, `timestamp` at the top.)
+- [ ] **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:` line has a concrete pointer**:
-      - GOOD: `tests-added: tests/foo.test.ts::should reject empty body`
-      - GOOD: `files-changed: src/api/users.ts:45-67`
-      - GOOD: `test-output: 5 passed (last 10 lines: …)`
-      - BAD: `tests-added: verified`
-      - BAD: `files-changed: yes`
-      - BAD: `contract: OK`
-      Reject any line whose value would not let a reviewer click through.
-- [ ] **If `status: blocked`, `next-action`** is ≥ 10 chars, is NOT `none`,
+- [ ] **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
+- [ ] **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 block before sending your response**. Do not
+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
@@ -99,12 +126,14 @@ ship a known-bad log and rely on the gate to catch it.
 `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. `status:` line is missing or has an unknown value.
-3. `status: blocked` without a concrete `next-action`.
-4. `files-read` is missing for a context-governed change, or contains an
+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.
-5. With `--strict`: any `- artifacts:` entry whose value looks like a path but
-   does not exist on disk.
+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/
 
@@ -114,4 +143,5 @@ 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, tests, and prompts stay in sync via this single doc.
+- 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/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 }