contract-driven-delivery 2.0.16 → 2.0.17

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

@@ -1,4 +1,4 @@
----
+---
 name: ui-ux-reviewer
 description: Review interaction design, information hierarchy, copy, accessibility, empty/error/loading state semantics, and user journey quality. Does not cover pixel-level visuals or CSS -- those go to visual-reviewer.
 tools: Read, Grep, Glob
@@ -24,9 +24,9 @@ Review the intended interaction, not just whether code compiles.
 ## Heuristics
 
 - Use Nielsen's 10 usability heuristics as default frame: visibility of system status, match between system and real world, user control and freedom, consistency, error prevention, recognition over recall, flexibility/efficiency, aesthetic and minimalist design, help users recognize/recover from errors, help and documentation.
-- Match the design system in use (Material 3, HIG, Fluent, custom tokens) — do not invent affordances that contradict the system.
-- Copy — clear > clever; verbs in CTAs; error messages must say what to do, not just what failed.
-- Information hierarchy — one primary action per screen; group related controls; align labels with content language.
+- Match the design system in use (Material 3, HIG, Fluent, custom tokens) ??do not invent affordances that contradict the system.
+- Copy ??clear > clever; verbs in CTAs; error messages must say what to do, not just what failed.
+- Information hierarchy ??one primary action per screen; group related controls; align labels with content language.
 
 ## Output
 
@@ -51,8 +51,8 @@ approved / changes-required
 
 ## Read scope
 
-Source of truth: `specs/changes/<change-id>/context-manifest.md` → `## Allowed Paths`.
-Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. `cdd-kit gate` validates `files-read:` against this list and rejects unauthorized paths.
+Source of truth: `specs/changes/<change-id>/context-manifest.md` ??`## Allowed Paths`.
+Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. Use this boundary as pre-read discipline, not as post-run paperwork.
 
 This agent's natural reads include UI source under `src/` (components, pages, layouts), `contracts/ui/` for design tokens, and screenshot/video paths under `specs/changes/<change-id>/`. Make sure the manifest's Allowed Paths includes them, or file a `## Context Expansion Requests` entry.
 
@@ -60,30 +60,27 @@ Need a path not listed? File a `## Context Expansion Requests` entry (see `specs
 
 Forbidden by default (enforced by `.cdd/context-policy.json`): `specs/archive/`, sibling `specs/changes/*`, `assets/`, `node_modules/`, `dist/`, `build/`, `.git/`, `.claude/worktrees/`.
 
-## Machine-Verifiable Evidence
+## Optional Handoff Evidence
 
-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.
+If a short handoff note is useful, end your response with an optional `Agent Log` YAML block`nfor main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Optional fields
+and field rules are defined once in
+`references/agent-log-protocol.md` ??do not duplicate them in this prompt.
 
-### Required artifacts for this agent
+### Suggested artifacts for this agent
 
 `artifacts` is a YAML array of `{type, pointer}` items in your agent log
 (see `references/agent-log-protocol.md` for the full schema and self-validation
-checklist). Do NOT write top-level `files-changed:` / `tests-added:` keys —
-those are `type` values, not log keys.
+checklist). Do NOT write top-level `files-changed:` / `tests-added:` keys ??those are `type` values, not log keys.
 
-Minimum required `type` values for this agent (each must appear at least once
-in your `artifacts:` array; add more items per type as needed):
+Recommended `type` values for this agent when you emit an optional agent log:
 
 - `journeys-reviewed`: user journeys covered
 - `state-coverage`: per-journey state coverage
 - `copy-issues`: copy/wording findings count
 - `accessibility-findings`: a11y findings by severity
 
-Copy this exact shape into your agent log; replace each `<pointer>` with a
+If you emit a log, copy this shape and replace each `<pointer>` with a
 concrete pointer (path:line-range, test-id, URL, or pass/fail string):
 
 ```yaml
@@ -94,6 +91,4 @@ artifacts:
   - { type: accessibility-findings, pointer: "0 high, 2 low" }
 ```
 
-If a required `type` does not apply to your run, emit one item with
-`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
-counts presence, qa-reviewer audits the reason.
+If a recommended `type` does not apply to your run, either omit it or use `pointer: "n/a (<one-line reason>)"` so reviewers can tell the omission was intentional.

package/assets/agents/visual-reviewer.md

@@ -1,4 +1,4 @@
----
+---
 name: visual-reviewer
 description: Review pixel-level visual output, layout, responsive viewport behavior, screenshot diffs, CSS contract compliance, and component visual state coverage. Does not cover interaction or copy -- those go to ui-ux-reviewer.
 tools: Read, Grep, Glob, Bash
@@ -20,10 +20,10 @@ Frontend visual changes require evidence. Use screenshots, videos, or a clear ma
 
 ## Tooling and matrix
 
-- Snapshot tools — Percy, Chromatic, Playwright `toHaveScreenshot()`; pick one per repo.
-- Diff threshold — start strict (~0.1%) and relax only with documented reason; "approved with diff" must list the changed pixels.
-- Variant matrix — themes (light, dark), languages (LTR, RTL), density (default, compact), reduced motion, high contrast — at least theme + RTL on top of viewport matrix.
-- Asset review — icons, fonts, images must come from the design system or have a documented exception.
+- Snapshot tools ??Percy, Chromatic, Playwright `toHaveScreenshot()`; pick one per repo.
+- Diff threshold ??start strict (~0.1%) and relax only with documented reason; "approved with diff" must list the changed pixels.
+- Variant matrix ??themes (light, dark), languages (LTR, RTL), density (default, compact), reduced motion, high contrast ??at least theme + RTL on top of viewport matrix.
+- Asset review ??icons, fonts, images must come from the design system or have a documented exception.
 
 ## Output
 
@@ -53,8 +53,8 @@ approved / changes-required
 
 ## Read scope
 
-Source of truth: `specs/changes/<change-id>/context-manifest.md` → `## Allowed Paths`.
-Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. `cdd-kit gate` validates `files-read:` against this list and rejects unauthorized paths.
+Source of truth: `specs/changes/<change-id>/context-manifest.md` ??`## Allowed Paths`.
+Read it first (your prompt header has `CURRENT_CHANGE_ID`). Read only paths it lists or paths under `## Approved Expansions`. Use this boundary as pre-read discipline, not as post-run paperwork.
 
 This agent's natural reads include screenshots under `specs/changes/<change-id>/`, `contracts/css/`, and component source under `src/`. Make sure the manifest's Allowed Paths includes them, or file a `## Context Expansion Requests` entry.
 
@@ -62,40 +62,35 @@ Need a path not listed? File a `## Context Expansion Requests` entry (see `specs
 
 Forbidden by default (enforced by `.cdd/context-policy.json`): `specs/archive/`, sibling `specs/changes/*`, `assets/`, `node_modules/`, `dist/`, `build/`, `.git/`, `.claude/worktrees/`.
 
-## Machine-Verifiable Evidence
+## Optional Handoff Evidence
 
-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.
+If a short handoff note is useful, end your response with an optional `Agent Log` YAML block`nfor main Claude to write to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`. Optional fields
+and field rules are defined once in
+`references/agent-log-protocol.md` ??do not duplicate them in this prompt.
 
-### Required artifacts for this agent
+### Suggested artifacts for this agent
 
 `artifacts` is a YAML array of `{type, pointer}` items in your agent log
 (see `references/agent-log-protocol.md` for the full schema and self-validation
-checklist). Do NOT write top-level `files-changed:` / `tests-added:` keys —
-those are `type` values, not log keys.
+checklist). Do NOT write top-level `files-changed:` / `tests-added:` keys ??those are `type` values, not log keys.
 
-Minimum required `type` values for this agent (each must appear at least once
-in your `artifacts:` array; add more items per type as needed):
+Recommended `type` values for this agent when you emit an optional agent log:
 
-- `screenshots-compared`: baseline → current screenshot pairs
+- `screenshots-compared`: baseline ??current screenshot pairs
 - `diff-percentage`: pixel diff per surface
 - `state-coverage`: visual states verified (default, loading, error, empty)
 - `tokens-violated`: design-token violations or "none"
 
-Copy this exact shape into your agent log; replace each `<pointer>` with a
+If you emit a log, copy this shape and replace each `<pointer>` with a
 concrete pointer (path:line-range, test-id, URL, or pass/fail string):
 
 ```yaml
 artifacts:
-  - { type: screenshots-compared, pointer: "dashboard: baseline.png → current.png" }
+  - { type: screenshots-compared, pointer: "dashboard: baseline.png ??current.png" }
   - { type: diff-percentage, pointer: "dashboard: 0.04%" }
   - { type: state-coverage, pointer: "default, loading, error, empty" }
   - { type: tokens-violated, pointer: "none" }
 ```
 
-If a required `type` does not apply to your run, emit one item with
-`pointer: "n/a (<one-line reason>)"` rather than omitting the type — the gate
-counts presence, qa-reviewer audits the reason.
+If a recommended `type` does not apply to your run, either omit it or use `pointer: "n/a (<one-line reason>)"` so reviewers can tell the omission was intentional.