contract-driven-delivery 1.12.0 → 2.0.0

package/assets/hooks/post-tool-use-files-read.sh

@@ -0,0 +1,55 @@
+#!/bin/sh
+# cdd-kit PostToolUse hook (B3): append actual Read/Grep/Glob targets to a
+# runtime audit log so `cdd-kit gate` can reconcile them against the agent-log
+# self-report. This turns Context Governance from a trust contract into a
+# verified contract.
+#
+# Wire into Claude Code (~/.claude/settings.json):
+#
+#   {
+#     "hooks": {
+#       "PostToolUse": [
+#         { "matcher": "Read|Grep|Glob", "command": "/path/to/hooks/post-tool-use-files-read.sh" }
+#       ]
+#     }
+#   }
+#
+# The hook receives the tool-call payload as JSON on stdin. We extract the
+# best-effort path candidate and append `<change-id>\t<path>` to a JSONL audit
+# file. CURRENT_CHANGE_ID is read from environment (cdd-new sets it on every
+# agent invocation as of v1.10.0+).
+
+set -eu
+
+CDD_RUNTIME_DIR="${CDD_RUNTIME_DIR:-./.cdd/runtime}"
+CHANGE_ID="${CURRENT_CHANGE_ID:-unknown}"
+
+mkdir -p "$CDD_RUNTIME_DIR"
+LOG_FILE="$CDD_RUNTIME_DIR/${CHANGE_ID}-files-read.jsonl"
+
+# Read JSON payload from stdin without choking if jq is missing.
+payload="$(cat || true)"
+[ -z "$payload" ] && exit 0
+
+# Try to extract the path field. Common Claude Code tool inputs:
+#   Read    → tool_input.file_path
+#   Grep    → tool_input.path / glob / pattern
+#   Glob    → tool_input.path / pattern
+# We grep first then fall back to jq when available.
+path_value=""
+if command -v jq >/dev/null 2>&1; then
+  path_value="$(printf '%s' "$payload" | jq -r '
+    .tool_input.file_path
+    // .tool_input.path
+    // .tool_input.pattern
+    // empty
+  ' 2>/dev/null || true)"
+fi
+if [ -z "$path_value" ]; then
+  path_value="$(printf '%s' "$payload" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]+"' | head -n1 | sed -E 's/.*"file_path"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')"
+fi
+
+[ -z "$path_value" ] && exit 0
+
+timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+printf '{"ts":"%s","change":"%s","path":"%s"}\n' "$timestamp" "$CHANGE_ID" "$path_value" >> "$LOG_FILE"

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`.
 
 ---
 

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

@@ -49,16 +49,52 @@ If no description is provided, ask the user: "Please describe the change you wan
 
 ---
 
+## Step 0: Request quality check (BEFORE classifier)
+
+Non-engineers often submit ambiguous requests like "fix the slow report" or
+"make it nicer". These cost a full classifier round-trip when the right move is
+to ask back. Before scaffolding anything, verify the request contains all
+three elements below. Rephrase the request internally in this shape:
+
+| Element | Example | Required? |
+|---|---|---|
+| 1. Affected surface | "the order export page", "the JWT login flow" | always |
+| 2. Desired behavior change | "complete in <10s", "support 2FA via TOTP" | always |
+| 3. Observable success criterion | "1000-row export finishes without timeout", "user with 2FA can log in end-to-end" | always |
+
+If any element is missing or ambiguous, **STOP. Do NOT call `cdd-kit new` or
+the classifier.** Ask the user back in this exact shape:
+
+```
+Before I start a tracked change, I need to lock down three things:
+
+  Affected surface:       <best guess from request, or empty>
+  Desired behavior:       <best guess, or empty>
+  Success criterion:      <empty — please fill>
+
+Could you confirm or fill in the missing pieces?
+```
+
+Only proceed to Step 1 once all three are answered or the user explicitly says
+"proceed without success criterion". Record the user's clarifications verbatim
+in `change-request.md` § Original Request.
+
+The cost of this step: 1 short message round-trip. The cost of skipping it:
+one full classifier+contract-reviewer cycle, often 5-10× more tokens, plus an
+inevitable re-classification when the agents discover the ambiguity.
+
+---
+
 ## Write Responsibilities
 
 **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`.
 
 ---
 
@@ -70,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
 
@@ -99,176 +135,21 @@ Verify these files exist:
 
 Do not use broad search or ad hoc reads to classify the change before `context-scan` has completed.
 
-The generated scaffold contains the artifacts below. Fill `change-request.md` with the user's request before invoking the classifier.
-
-Update `specs/changes/<change-id>/change-request.md` with the user's description filled in:
-```
-# Change Request: <change-id>
-
-## Original Request
-<user's exact description, verbatim>
-
-## Business / User Goal
-<infer from the description>
-
-## Non-goals
-
-## Constraints
-
-## Known Context
+The generated scaffold contains the artifacts listed in the table below. **All
+templates are written from disk by `cdd-kit new` — do not paste template bodies
+into this prompt.** The on-disk source of truth lives in `specs/templates/` of
+the kit and is bundled into every install.
 
-## Open Questions
-
-## Requested Delivery Date / Priority
-as soon as possible
-```
-
-`specs/changes/<change-id>/change-classification.md` starts from this blank template:
-```
-# Change Classification
-
-## Change Types
-- primary:
-- secondary:
-
-## Risk Level
-- low / medium / high / critical
-
-## Impact Radius
-- isolated / module-level / cross-module / system-wide
-
-## Tier
-- 0 / 1 / 2 / 3 / 4 / 5
-
-## Architecture Review Required
-- yes / no
-- reason: (fill only if yes)
-
-## Required Artifacts
-Always required: change-request.md, change-classification.md, test-plan.md, ci-gates.md, tasks.md
-
-## Optional Artifacts (default: no — set yes only with explicit reason)
-| artifact | create? | reason |
+| File | Source | Your job |
 |---|---|---|
-| current-behavior.md | no | |
-| proposal.md | no | |
-| spec.md | no | |
-| design.md | no | |
-| qa-report.md | no | |
-| regression-report.md | no | |
-
-## Required Contracts
-- API:
-- CSS/UI:
-- Env:
-- Data shape:
-- Business logic:
-- CI/CD:
-
-## Required Test Families
-- unit:
-- contract:
-- integration:
-- E2E:
-- visual:
-- data-boundary:
-- resilience:
-- fuzz/monkey:
-- stress:
-- soak:
-
-## Required Agents
-
-## Assumptions / Clarifications
-```
-
-`specs/changes/<change-id>/test-plan.md` starts from this blank template:
-```
-# Test Plan: <change-id>
-
-## Acceptance Criteria → Test Mapping
-| criterion id | test family | test file path | tier |
-|---|---|---|---|
-
-## Test Families Required
-| family | tier | notes |
-|---|---|---|
-| (unit / contract / integration / e2e / data-boundary / resilience / monkey / stress / soak) | | |
-
-## Out of Scope
+| `change-request.md` | `specs/templates/change-request.md` | Fill the `## Original Request` section with the user's exact description before invoking the classifier; leave the rest blank |
+| `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.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) |
 
-## Notes
-(Keep under 10 lines. Implementation detail belongs in the test files themselves.)
-```
-
-`specs/changes/<change-id>/ci-gates.md` starts from this blank template:
-```
-# CI Gates: <change-id>
-
-## Required Gates (block merge if failing)
-
-## Informational Gates (report only)
-
-## Nightly / Weekly / Manual Gates
-
-## Promotion Policy
-```
-
-`specs/changes/<change-id>/tasks.md` starts with ALL checkboxes unchecked:
-```
----
-change-id: <change-id>
-status: in-progress
-context-governance: v1
-depends-on: []
----
-
-<!-- [x]=done [-]=N/A [ ]=pending -->
-
-# Tasks: <change-id>
-
-## 1. Preparation
-- [ ] 1.1 Confirm classification and required artifacts
-- [ ] 1.2 Confirm contracts to update
-- [ ] 1.3 Confirm CI/CD gate plan
-
-## 2. Contract Updates
-- [ ] 2.1 API contract
-- [ ] 2.2 CSS/UI contract
-- [ ] 2.3 Env contract
-- [ ] 2.4 Data shape contract
-- [ ] 2.5 Business logic contract
-- [ ] 2.6 CI/CD contract
-
-## 3. Tests First
-- [ ] 3.1 Unit/contract tests
-- [ ] 3.2 Integration tests
-- [ ] 3.3 E2E/resilience tests
-- [ ] 3.4 Data-boundary/monkey tests
-- [ ] 3.5 Stress/soak tests if required
-
-## 4. Implementation
-- [ ] 4.1 Backend
-- [ ] 4.2 Frontend
-- [ ] 4.3 Env/deploy
-- [ ] 4.4 CI/CD workflows
-
-## 5. Review
-- [ ] 5.1 UI/UX review
-- [ ] 5.2 Visual review
-- [ ] 5.3 Contract review
-- [ ] 5.4 QA review
-
-## 6. Verification
-- [ ] 6.1 Local gates
-- [ ] 6.2 PR required gates
-- [ ] 6.3 Informational gates
-- [ ] 6.4 Nightly/weekly/manual gates if required
-
-## 7. Archive
-- [ ] 7.1 Archive change
-- [ ] 7.2 Promote durable learnings to contracts or CLAUDE.md
-```
+If `cdd-kit new` reports a missing template, run `cdd-kit upgrade --yes`.
 
 ---
 
@@ -290,16 +171,50 @@ The classifier must include a `## Context Manifest Draft` section with:
 - required tests
 - any context expansion requests that must be approved before implementation
 
-**change-classifier is read-only** — it will return its output as text. After it responds:
+**change-classifier is read-only** — it will return its output as text.
+
+### If the classifier returns `## Atomic Split Proposal`
+
+The classifier has decided this request is too big for a single change. Do
+NOT proceed with the rest of `/cdd-new`. Instead:
+
+1. Show the user the full `## Atomic Split Proposal` table verbatim.
+2. Ask: "Run these as separate changes (recommended), or force a single
+   monolithic change?"
+3. If user picks "separate":
+   - For each row in the proposal table, run `cdd-kit new <change-id>` with
+     the listed `--depends-on`.
+   - Then say: "I created N change directories. Want me to run `/cdd-new`
+     against the first one now?" — wait for confirmation; do not auto-loop.
+4. If user picks "force monolithic":
+   - Re-invoke change-classifier with `force-monolithic` appended to the
+     change-request and proceed with whatever Tier the classifier returns.
+5. Delete the partially-scaffolded change directory you created in Step 1
+   if the user picked "separate" and the originally-derived change-id is
+   not in the proposal — it would otherwise sit empty and confuse `cdd-kit
+   list`.
+
+### Classifier output lint (B8): refuse stub responses
+
+Before writing any files, verify the classifier response contains:
+
+- `## Tier` followed by `- N` where N is a single digit 0-5 (NOT `0 / 1 / 2 / 3 / 4 / 5` — that is the unfilled placeholder).
+- `## Required Agents` with at least one agent name.
+- `## Inferred Acceptance Criteria` with at least one filled `AC-1: …` line.
+
+If any of these are missing or still hold the literal placeholder text, STOP. Re-prompt the classifier with the missing pieces named explicitly. Do NOT write classification.md — gate will reject it as a stub anyway and you will have wasted the round-trip.
+
+### 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 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 four writes are done before continuing.
+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.
 
 ---
 
@@ -307,9 +222,9 @@ Wait until these four 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.
 
@@ -320,16 +235,68 @@ Change directory: specs/changes/<change-id>/
 ```
 This ensures the agent's Read scope restriction points to the correct directory.
 
+### Agent stage badges (UI v1)
+
+When you announce that you are about to invoke an agent, prefix the
+announcement with the matching emoji + role tag from the table below. This
+helps a non-engineer scanning the chat stream tell what stage they are in
+without reading the full prompt. Use the badges only in your own narration to
+the user; do not put them inside the prompt sent to the agent.
+
+| Stage | Agent | Badge |
+|---|---|---|
+| Decision | `change-classifier` | 🟣 `[classifier]` |
+| Decision | `spec-architect` | 🟣 `[architect]` |
+| Implementation | `backend-engineer` | 🔵 `[backend]` |
+| Implementation | `frontend-engineer` | 🔵 `[frontend]` |
+| Implementation | `ci-cd-gatekeeper` | 🔵 `[ci-cd]` |
+| Implementation | `test-strategist` | 🟡 `[test-plan]` |
+| Heavy testing (Tier 0–1 only) | `e2e-resilience-engineer` | 🟠 `[e2e]` |
+| Heavy testing (Tier 0–1 only) | `monkey-test-engineer` | 🟠 `[monkey]` |
+| Heavy testing (Tier 0–1 only) | `stress-soak-engineer` | 🟠 `[stress]` |
+| Review | `contract-reviewer` | 🟢 `[contracts]` |
+| Review | `qa-reviewer` | 🟢 `[qa]` |
+| Review | `ui-ux-reviewer` | 🟢 `[ui-ux]` |
+| Review | `visual-reviewer` | 🟢 `[visual]` |
+| Review | `dependency-security-reviewer` | 🟢 `[deps-sec]` |
+| Audit | `spec-drift-auditor` | ⚫ `[drift]` |
+| Audit | `repo-context-scanner` | ⚫ `[repo-scan]` |
+
+Color semantics:
+- 🟣 purple: deciding what we will do (heavy model, opus-class)
+- 🔵 blue: writing code (sonnet-class implementation)
+- 🟡 yellow: planning tests (sonnet-class)
+- 🟠 orange: heavy testing — only appears for Tier 0–1, signals high-risk scope
+- 🟢 green: reviewing what was done (no code writes; just verdicts)
+- ⚫ neutral: audits and scans (read-only background work)
+
+Format: emoji is followed by a single space, then the bracket-tag, then the
+human-readable narration.
+
+Examples:
+
+```
+🟣 [classifier] Reading the request and project map…
+🟢 [contracts] Confirming the API contract is unchanged. (read-only)
+🔵 [backend] Implementing the JWT issuance endpoint and writing failing
+            tests first per TDD policy.
+🟠 [stress] Tier 1 high-risk change — running soak test for 30 min.
+```
+
+These badges are pure narration. They MUST NOT be sent inside the agent's
+prompt; the agent's behavior is defined by the agent prompt files in
+`.claude/agents/<name>.md`, not by this badge.
+
 ---
 
 ### 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`
 
 ---
@@ -337,7 +304,7 @@ This ensures the agent's Read scope restriction points to the correct directory.
 ### 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.
@@ -349,31 +316,31 @@ This ensures the agent's Read scope restriction points to the correct directory.
 
 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`
 
 ---
@@ -404,24 +371,60 @@ 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**:
-1. Read the gate error output carefully
-2. Identify which artifact is missing, stub, or invalid
-3. Re-invoke the specific agent responsible for that artifact with the exact fix required
-4. Re-run `cdd-kit gate <change-id>`
-5. Repeat until gate passes (max 3 iterations; if still failing after 3, report to user)
+**If gate fails — structured fix-back routing**:
+
+Capture gate's full stderr verbatim. Parse error lines and route each to the
+right owner. The patterns below are exhaustive — every gate error message
+matches one of them.
+
+| Error pattern | Route to | Re-invocation prompt seed |
+|---|---|---|
+| `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.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." |
+
+**Re-invocation prompt template** (always use this exact prefix when re-invoking an agent for fix-back):
+
+```
+CURRENT_CHANGE_ID: <change-id>
+Change directory: specs/changes/<change-id>/
+
+PREVIOUS GATE FAILURE FOR THIS AGENT (re-invocation):
+<the exact gate error line(s) tied to this agent>
+
+FIX TARGET:
+<the specific file or section that needs to change>
+
+REFERENCES:
+- references/agent-log-protocol.md (log format)
+- references/<agent-specific-standard>.md (if applicable)
+
+Fix this exact issue without re-doing your prior work. Re-output only the
+section that changed plus your updated Agent Log block.
+```
+
+After re-invoking, re-run `cdd-kit gate <change-id>`. Repeat up to **3 times**. Each
+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**: Add a line at the top of `tasks.md` reading `status: gate-blocked` and report all blocking items to the user. The change is paused — do not proceed to Step 5.
+**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.
 
 ---
 
@@ -438,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>/
 
@@ -470,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
 
 ---