contract-driven-delivery 1.16.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [2.0.1] - 2026-04-30
+
+### Fixed
+
+- Clarified the agent ownership model in the public docs so read-only reviewers
+  and write-capable implementation agents have explicit, non-conflicting file
+  ownership rules.
+- Aligned bundled prompts so read-only agents emit an `Agent Log` YAML block
+  for main Claude to persist, while write-capable agents continue writing their
+  own artifacts and `agent-log/*.yml` files.
+- Synchronized package version metadata for the post-`2.0.0` publish path.
+
+## [2.0.0] - 2026-04-30
+
+### BREAKING: structured YAML for tasks and agent-log
+
+- `tasks.md` is replaced by `tasks.yml`. The previous markdown-frontmatter +
+  checklist hybrid is gone. The new file is a single YAML document validated
+  by `src/schemas/tasks.schema.ts` (JSON Schema, draft-07). Task items use
+  `status: pending | done | skipped` instead of `[ ] / [x] / [-]` checkboxes.
+- `agent-log/<agent>.md` is replaced by `agent-log/<agent>.yml`, validated by
+  `src/schemas/agent-log.schema.ts`. The "field: value" prose convention is
+  gone; agents now emit a structured YAML record with `change-id`, `agent`,
+  `timestamp` (ISO 8601), `status`, `files-read`, `artifacts`, and
+  `next-action`.
+- `cdd-kit gate` parses both files with `js-yaml` and validates them with
+  `ajv`. Errors and warnings now reference YAML paths rather than markdown
+  line patterns.
+- All bundled templates, skill prompts, agent prompts, and Python helper
+  scripts have been updated to point at the new file names.
+
+### Upgrading
+
+Run `cdd-kit migrate <change-id>` (or `cdd-kit migrate --all`) to convert
+existing changes:
+
+- `tasks.md` is parsed (frontmatter + markdown checklist) and rewritten as
+  `tasks.yml`. The legacy `tasks.md` is deleted.
+- Every `agent-log/*.md` is parsed and rewritten as `agent-log/*.yml`. The
+  legacy markdown logs are deleted.
+- A backup of the change directory is written to
+  `.cdd/migrate-backup/<stamp>/<change-id>/` before any rewrite.
+
+### Notes
+
+This is a breaking release; pin to `^1.16.0` if you still depend on the old
+markdown formats.
+
 ## [1.16.0] - 2026-04-30
 
 ### Visual narration: per-agent stage badges

package/README.md

@@ -99,10 +99,23 @@ or
 8. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
 9. Claude reports a summary and the suggested git commit
 
+### Agent Ownership Model
+
+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`.
+
+This split is deliberate:
+
+- Review and audit agents stay read-only so they do not silently change the thing they are supposed to assess.
+- Implementation and planning agents write directly so large artifacts and code edits do not have to be relayed back through the main orchestrator, which reduces token waste and preserves clearer ownership.
+- `tasks.yml` remains owned by main Claude so task state changes stay centralized even when multiple agents contribute files.
+
 **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.md` for the release-readiness verdict
+- Reading the final `agent-log/qa-reviewer.yml` for the release-readiness verdict
 
 ---
 
@@ -142,12 +155,12 @@ What changes are currently in progress? (cdd-kit list)
 ```
 
 **What happens:**
-1. Claude reads `tasks.md` and `agent-log/` to determine what was completed
+1. Claude reads `tasks.yml` and `agent-log/` 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
 
-> If you're upgrading from an older version and your change was created before v1.11.0, Claude will automatically run `cdd-kit migrate <change-id>` to upgrade the format before resuming.
+> If you're upgrading from an older version and your change was created before v2.0.0, Claude will automatically run `cdd-kit migrate <change-id>` to upgrade the format before resuming.
 
 ---
 
@@ -285,18 +298,18 @@ 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.md`; new context-governed changes also require `context-manifest.md`)
+- 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/*.md` files all have `status: complete` (not blocked)
-- For context-governed changes, `agent-log/*.md` files include a structured `- files-read:` list and those repo-relative paths are audited against `context-manifest.md` and `.cdd/context-policy.json`
+- `agent-log/*.yml` files all have `status: complete` (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
 
 `--strict` additionally:
-- Treats any pending `[ ]` tasks (except section 7 archive items) as errors
+- 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
 
@@ -309,8 +322,8 @@ Pre-commit hook uses `--strict` by default (installed via `cdd-kit install-hooks
 
 ✗  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.md
-✗    1 task(s) still pending (use [-] for N/A items, [x] for done)
+✗    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)
 ```
 
 ---
@@ -342,13 +355,13 @@ cdd-kit archive add-jwt-auth
 # ✓  Index updated: specs/archive/INDEX.md
 ```
 
-Warns (but does not block) if `tasks.md` 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.
 
 ---
 
 ### `cdd-kit abandon <change-id>`
 
-Marks a change as abandoned. Updates `tasks.md` status to `abandoned`, records the reason in `specs/archive/INDEX.md`. The directory stays on disk for git history.
+Marks a change as abandoned. Updates `tasks.yml` status to `abandoned`, records the reason in `specs/archive/INDEX.md`. The directory stays on disk for git history.
 
 ```bash
 cdd-kit abandon add-jwt-auth --reason "using Auth0 instead"
@@ -359,7 +372,7 @@ cdd-kit abandon add-jwt-auth --reason "using Auth0 instead"
 
 ### `cdd-kit migrate <change-id> | --all`
 
-Upgrades pre-v1.11.0 change directories to the current format.
+Upgrades pre-v2.0.0 change directories to the current format.
 
 ```bash
 cdd-kit migrate add-jwt-auth        # migrate one change
@@ -369,15 +382,15 @@ cdd-kit migrate --all --enable-context-governance
 ```
 
 What it upgrades:
-- `tasks.md`: adds YAML frontmatter (`change-id`, `status: in-progress`) and `[x]/[-]/[ ]` legend if missing
+- `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
 
-`agent-log/*.md` must use this `files-read` format for context-governed changes:
+`agent-log/*.yml` must use this `files-read` format for context-governed changes:
 
-```md
-- files-read:
+```yaml
+files-read:
   - contracts/api/api-contract.md
   - src/server/routes/users.ts
 ```
@@ -415,7 +428,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/*.md`; `cdd-kit gate` audits those paths against the manifest.
+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.
 
 ---
 
@@ -470,7 +483,7 @@ cdd-kit new add-user-auth --skip-scan
 
 By default, `cdd-kit new` auto-runs `cdd-kit context-scan` when `specs/context/` indexes are missing or stale. Use `--skip-scan` only if you intentionally want a bare scaffold without refreshing classifier indexes first.
 
-For larger requests, split the work into atomic changes on the same feature branch and use `--depends-on` to record upstream order. `cdd-kit gate` blocks a dependent change until each upstream change is either archived or has `status: completed` in its `tasks.md` frontmatter.
+For larger requests, split the work into atomic changes on the same feature branch and use `--depends-on` to record upstream order. `cdd-kit gate` blocks a dependent change until each upstream change is either archived or has `status: completed` in its `tasks.yml`.
 
 ---
 
@@ -559,7 +572,7 @@ git add specs/changes/
 git commit -m "chore: migrate changes to current cdd-kit format"
 ```
 
-This gives those legacy specs the new `tasks.md` frontmatter, 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, and a warning-mode `context-manifest.md` without forcing strict context governance on closed work.
 
 ### Old in-progress specs
 
@@ -606,7 +619,7 @@ your-repo/
 │   │       ├── change-classification.md (required)
 │   │       ├── test-plan.md         (required)
 │   │       ├── ci-gates.md          (required)
-│   │       ├── tasks.md             (required)
+│   │       ├── tasks.yml            (required)
 │   │       └── agent-log/           ← machine-verifiable evidence per agent
 │   ├── archive/                     ← completed and abandoned changes
 │   │   ├── INDEX.md
@@ -630,15 +643,22 @@ your-repo/
 
 ---
 
-## Task notation in `tasks.md`
-
-```markdown
-- [x] 1.1 Confirm classification       ← done
-- [-] 2.2 CSS/UI contract              ← N/A (not applicable to this change)
-- [ ] 4.1 Backend implementation       ← pending
-```
+## Task notation in `tasks.yml`
 
-`cdd-kit gate --strict` treats any `[ ]` (except section 7 archive tasks) as an error. Use `[-]` for items that are genuinely not applicable to a given change.
+```yaml
+tasks:
+  - id: "1.1"
+    title: Confirm classification
+    status: done
+  - id: "2.2"
+    title: CSS/UI contract
+    status: skipped
+  - id: "4.1"
+    title: Backend implementation
+    status: pending
+```
+
+`cdd-kit gate --strict` treats any task with `status: pending` (except IDs listed in `archive-tasks`, which default to `7.1` and `7.2`) as an error. Use `status: skipped` for tasks that are genuinely not applicable to a given change.
 
 ---
 

package/assets/CODEX.template.md

@@ -18,12 +18,12 @@ Read `specs/changes/<change-id>/context-manifest.md` before using file-reading o
 - Read only paths allowed by the manifest or approved expansions.
 - 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/*.md` under `- files-read:`.
+- Record every file read through tools in the relevant `agent-log/*.yml` under `files-read:`.
 
-Required `agent-log/*.md` format:
+Required `agent-log/*.yml` format:
 
-```md
-- files-read:
+```yaml
+files-read:
   - contracts/api/api-contract.md
   - src/server/routes/users.ts
 ```

package/assets/agents/backend-engineer.md

@@ -17,7 +17,7 @@ Before editing production code, read the change artifacts, API/env/data/business
 - Validate input at the boundary.
 - Return standardized errors, not raw exceptions.
 - Preserve backward compatibility unless the spec explicitly marks a breaking change.
-- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit, contract, and integration tests BEFORE writing feature code. Tests in `tasks.md` items 3.1–3.2 are your responsibility.
+- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit, contract, and integration tests BEFORE writing feature code. Tests in `tasks.yml` items 3.1–3.2 are your responsibility.
 - Update CI/CD workflows when required by `ci-gates.md`.
 
 ## Common pitfalls
@@ -48,7 +48,7 @@ In your agent log, reference file paths and function names — do not paste code
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

package/assets/agents/change-classifier.md

@@ -47,7 +47,7 @@ Before producing a single classification, check these triggers:
   export).
 - **Contract-heavy**: ≥ 5 of the 6 contracts (api / css / env / data /
   business / ci) need changes.
-- **Task-heavy**: estimated > 10 task-IDs across sections 3-4 of `tasks.md`.
+- **Task-heavy**: estimated > 10 task-IDs across sections 3-4 of `tasks.yml`.
 
 If **any one trigger fires**, output `## Atomic Split Proposal` INSTEAD of the
 normal classification, in this exact shape:
@@ -140,7 +140,7 @@ Use this structure:
 ## Required Artifacts
 
 The following 5 artifacts are always required for implementation changes:
-`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`
+`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`
 
 ## Optional Artifacts (default: no — set yes only with explicit reason)
 
@@ -216,7 +216,7 @@ Note: `archive.md` is created during change close-out, not at classification tim
 - AC-3:
 
 ## Tasks Not Applicable
-(List task IDs from tasks.md that are NOT applicable to this change, using the format `2.2, 2.3, 4.2`. Main Claude will mark these as [-] in tasks.md.)
+(List task IDs from tasks.yml that are NOT applicable to this change, using the format `2.2, 2.3, 4.2`. Main Claude will mark these as `status: skipped` in tasks.yml.)
 - not-applicable:
 
 ## Clarifications or Assumptions
@@ -225,8 +225,9 @@ Note: `archive.md` is created during change close-out, not at classification tim
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

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

@@ -65,7 +65,7 @@ mergeable / blocked / informational-risk
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

package/assets/agents/contract-reviewer.md

@@ -63,8 +63,9 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

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

@@ -64,8 +64,9 @@ approved / changes-required / blocked
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
@@ -74,4 +75,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `cve-findings`: count + severity buckets
 - `license-issues`: list or "none"
 - `lockfile-changes`: list of files
-

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

@@ -42,7 +42,7 @@ Record test files, scenarios, fixtures/mocks, commands, screenshots/videos, and
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

package/assets/agents/frontend-engineer.md

@@ -46,7 +46,7 @@ In your agent log, reference file paths and function names — do not paste code
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

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

@@ -45,7 +45,7 @@ Use fuzz payloads, Playwright action sequences, property-based tests, and target
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

package/assets/agents/qa-reviewer.md

@@ -75,8 +75,9 @@ approved / blocked / approved-with-risk
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

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

@@ -84,8 +84,9 @@ frontend / backend / fullstack / monorepo / library / tool
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
@@ -93,4 +94,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `profile-path`: `project-profile.generated.md`
 - `stack-detected`: from cdd-kit detect-stack
 - `surfaces-flagged`: list of missing standardization surfaces
-

package/assets/agents/spec-architect.md

@@ -94,7 +94,7 @@ Target: `design.md` ≤ 150 lines.
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

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

@@ -52,8 +52,9 @@ By default, do NOT read `specs/changes/` history. Only read historical change re
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
@@ -62,4 +63,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `drift-items`: count + severity
 - `drift-summary-path`: `specs/audits/<YYYY-MM-DD>-drift-audit.md`
 - `next-audit-due`: ISO date
-

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

@@ -69,7 +69,7 @@ Use realistic load profiles rather than arbitrary request loops.
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

package/assets/agents/test-strategist.md

@@ -73,7 +73,7 @@ Target: `test-plan.md` ≤ 100 lines.
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 

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

@@ -51,8 +51,9 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
@@ -61,4 +62,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `state-coverage`: list of `<screen>: empty/loading/error/success` matrix
 - `copy-issues`: count + severity
 - `accessibility-findings`: count + severity
-

package/assets/agents/visual-reviewer.md

@@ -53,8 +53,9 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to
-`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+After completing your task, end your response with an `Agent Log` YAML block
+for main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Required fields,
 field rules, and gate-enforcement behavior are defined once in
 `references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
@@ -63,4 +64,3 @@ field rules, and gate-enforcement behavior are defined once in
 - `diff-percentage`: per-screen
 - `state-coverage`: matrix
 - `tokens-violated`: list of CSS contract violations or "none"
-

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

@@ -38,7 +38,7 @@ If the user wants to **abandon** this change (not close as complete):
 cdd-kit abandon <change-id> --reason "<reason>"
 ```
 
-This marks `tasks.md` as `status: abandoned` and records it in `specs/archive/INDEX.md`. The directory is preserved for git history. Do NOT run the rest of this skill after abandoning.
+This marks `tasks.yml` as `status: abandoned` and records it in `specs/archive/INDEX.md`. The directory is preserved for git history. Do NOT run the rest of this skill after abandoning.
 
 ---
 
@@ -48,13 +48,13 @@ Run: `cdd-kit gate <change-id>`
 
 If gate fails: stop and report failures. Do NOT archive a change that hasn't passed gate.
 
-Exception: if `tasks.md` contains `status: gate-blocked`, ask the user: "This change was gate-blocked. Abandon it? (yes/no)". If yes, run `cdd-kit abandon <change-id> --reason "gate-blocked after 3 attempts"` and stop.
+Exception: if `tasks.yml` contains `status: gate-blocked`, ask the user: "This change was gate-blocked. Abandon it? (yes/no)". If yes, run `cdd-kit abandon <change-id> --reason "gate-blocked after 3 attempts"` and stop.
 
 ---
 
-## Step 2: Review tasks.md section 7
+## Step 2: Review tasks.yml section 7
 
-Read `specs/changes/<change-id>/tasks.md`.
+Read `specs/changes/<change-id>/tasks.yml`.
 
 Check section 7:
 - `7.1 Archive change` — will be ticked after Step 4
@@ -71,7 +71,7 @@ Read only active evidence for this change:
 - `specs/changes/<change-id>/qa-report.md` (if exists)
 - `specs/changes/<change-id>/ci-gates.md`
 - `specs/changes/<change-id>/context-manifest.md`
-- `specs/changes/<change-id>/tasks.md`
+- `specs/changes/<change-id>/tasks.yml`
 
 Do not read `specs/archive/` while closing a change. Historical archives are cold data and must not be used as current requirements.
 
@@ -110,9 +110,9 @@ After contract-reviewer responds:
 3. Run `cdd-kit validate --contracts` to confirm contract format is preserved
 4. Run `cdd-kit context-scan` so future classifiers see updated hot context indexes
 5. Fill in `## Lessons Promoted to Standards` in archive.md with what was promoted, where, and evidence path
-6. Tick `7.2` in tasks.md
+6. Set task `7.2` to `status: done` in tasks.yml
 
-If there are no lessons to promote, mark `[-]` for 7.2 with rationale.
+If there are no lessons to promote, mark `7.2` as `status: skipped` with rationale.
 
 ---
 
@@ -120,8 +120,8 @@ If there are no lessons to promote, mark `[-]` for 7.2 with rationale.
 
 Run: `cdd-kit archive <change-id>`
 
-If successful, tick `7.1` in tasks.md (the file is now in specs/archive/, update it there):
-`specs/archive/<year>/<change-id>/tasks.md` — change `7.1` from `[ ]` to `[x]`.
+If successful, set task `7.1` to `status: done` in tasks.yml (the file is now in specs/archive/, update it there):
+`specs/archive/<year>/<change-id>/tasks.yml` — change `7.1` from `status: pending` to `status: done`.
 
 ---