contract-driven-delivery 1.11.0 → 1.16.0

package/assets/agents/test-strategist.md

@@ -72,19 +72,10 @@ 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`
-with this exact structure (lines starting with `- ` are required):
-
-```
-# Test Strategist Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- artifacts:
-  - <evidence-type>: <concrete pointer>
-  - <evidence-type>: <concrete pointer>
-- next-action: <one line, or "none">
-```
+After completing your task, write or append to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+field rules, and gate-enforcement behavior are defined once in
+`references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
 - `test-plan-path`: `specs/changes/<id>/test-plan.md`
@@ -92,16 +83,6 @@ with this exact structure (lines starting with `- ` are required):
 - `coverage-tiers`: list of tiers covered (unit/contract/integration/E2E/resilience/monkey/stress/soak)
 - `mapping-completeness`: percentage or "all requirements covered"
 
-### Rules
-- NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log
-  is missing the `status:` line or has an invalid status.
-- If you cannot complete the task, set `status: blocked` and write a
-  concrete `next-action` (NOT "investigate further" — write the actual
-  next step a human can act on).
-- Evidence must be concrete: file:line, command name + last-10-line stdout,
-  contract path + section, test name, etc. NEVER write "verified" or "OK"
-  without a pointer.
-
 ## Read scope
 
 - Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`

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

@@ -51,19 +51,10 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/ui-ux-reviewer.md`.
-
-```
-## Agent Log
-# UI/UX Reviewer Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- artifacts:
-  - <evidence-type>: <concrete pointer>
-  - <evidence-type>: <concrete pointer>
-- next-action: <one line, or "none">
-```
+After completing your task, write or append to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+field rules, and gate-enforcement behavior are defined once in
+`references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
 - `journeys-reviewed`: list of journey names
@@ -71,12 +62,3 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - `copy-issues`: count + severity
 - `accessibility-findings`: count + severity
 
-### Rules
-- NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log
-  is missing the `status:` line or has an invalid status.
-- If you cannot complete the task, set `status: blocked` and write a
-  concrete `next-action` (NOT "investigate further" — write the actual
-  next step a human can act on).
-- Evidence must be concrete: file:line, command name + last-10-line stdout,
-  contract path + section, test name, etc. NEVER write "verified" or "OK"
-  without a pointer.

package/assets/agents/visual-reviewer.md

@@ -53,19 +53,10 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/visual-reviewer.md`.
-
-```
-## Agent Log
-# Visual Reviewer Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- artifacts:
-  - <evidence-type>: <concrete pointer>
-  - <evidence-type>: <concrete pointer>
-- next-action: <one line, or "none">
-```
+After completing your task, write or append to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.md`. Required fields,
+field rules, and gate-enforcement behavior are defined once in
+`references/agent-log-protocol.md` — do not duplicate them in this prompt.
 
 ### Required artifacts for this agent
 - `screenshots-compared`: list of `<screen>: baseline → current`
@@ -73,12 +64,3 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - `state-coverage`: matrix
 - `tokens-violated`: list of CSS contract violations or "none"
 
-### Rules
-- NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log
-  is missing the `status:` line or has an invalid status.
-- If you cannot complete the task, set `status: blocked` and write a
-  concrete `next-action` (NOT "investigate further" — write the actual
-  next step a human can act on).
-- Evidence must be concrete: file:line, command name + last-10-line stdout,
-  contract path + section, test name, etc. NEVER write "verified" or "OK"
-  without a pointer.

package/assets/cdd/context-policy.json

@@ -0,0 +1,25 @@
+{
+  "forbiddenPaths": [
+    ".claude/worktrees/**",
+    ".git/**",
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    "assets/**",
+    "specs/archive/**",
+    "specs/changes/*"
+  ],
+  "contextExpansion": {
+    "mode": "auto-safe",
+    "autoApprovePatterns": [
+      "src/**",
+      "tests/**",
+      "contracts/**",
+      "specs/changes/<current-change-id>/**"
+    ]
+  },
+  "audit": {
+    "requireFilesRead": true,
+    "unknownFilesRead": "warn-for-legacy-fail-for-new"
+  }
+}

package/assets/cdd/model-policy.json

@@ -0,0 +1,24 @@
+{
+  "provider": "claude",
+  "generated_at": null,
+  "schema-version": "0.2.0",
+  "roles": {
+    "change-classifier": "claude-opus-4-7",
+    "spec-architect": "claude-opus-4-7",
+    "qa-reviewer": "claude-opus-4-7",
+    "contract-reviewer": "claude-sonnet-4-6",
+    "test-strategist": "claude-sonnet-4-6",
+    "backend-engineer": "claude-sonnet-4-6",
+    "frontend-engineer": "claude-sonnet-4-6",
+    "ci-cd-gatekeeper": "claude-sonnet-4-6",
+    "e2e-resilience-engineer": "claude-sonnet-4-6",
+    "monkey-test-engineer": "claude-sonnet-4-6",
+    "stress-soak-engineer": "claude-sonnet-4-6",
+    "ui-ux-reviewer": "claude-sonnet-4-6",
+    "visual-reviewer": "claude-sonnet-4-6",
+    "dependency-security-reviewer": "claude-sonnet-4-6",
+    "spec-drift-auditor": "claude-sonnet-4-6",
+    "repo-context-scanner": "claude-haiku-4-5"
+  },
+  "_notes": "Roles map agent name -> model ID. Override per-project as needed. cdd-kit doctor warns when an installed agent's frontmatter `model:` does not match this policy."
+}

package/assets/contracts/api/api-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: api
+summary: API behavior, compatibility rules, and endpoint contract requirements.
+owner: application-team
+surface: api
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/api/api-inventory.md

@@ -1,3 +1,10 @@
+---
+contract: api-inventory
+summary: Endpoint inventory categories and ownership map for non-standard API surfaces.
+owner: application-team
+surface: api
+---
+
 # API Inventory
 
 | method | path | category | owner | contract test | notes |

package/assets/contracts/api/error-format.md

@@ -1,3 +1,10 @@
+---
+contract: api-error-format
+summary: Standard error payload shape, safety rules, and reusable error code table.
+owner: application-team
+surface: api
+---
+
 # API Error Format
 
 ## Standard Error Shape

package/assets/contracts/business/business-rules.md

@@ -1,5 +1,8 @@
 ---
 contract: business
+summary: Business decision tables, rule inventory, and change policy for behavior updates.
+owner: application-team
+surface: domain-behavior
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/ci/ci-gate-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: ci
+summary: CI gate inventory, artifact retention, and rollback requirements.
+owner: platform-team
+surface: delivery-pipeline
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/css/css-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: css
+summary: UI token policy, component styling rules, and visual review constraints.
+owner: application-team
+surface: ui
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/css/design-tokens.md

@@ -1,3 +1,10 @@
+---
+contract: design-tokens
+summary: Canonical design token inventory for colors, spacing, typography, and layering.
+owner: design-system
+surface: ui
+---
+
 # Design Tokens
 
 ## Colors

package/assets/contracts/data/data-shape-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: data
+summary: Data schema, invalid-data handling, and row-level compatibility rules.
+owner: application-team
+surface: data
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

package/assets/contracts/env/env-contract.md

@@ -1,5 +1,8 @@
 ---
 contract: env
+summary: Environment variable inventory, secret handling, and deployment sync policy.
+owner: platform-team
+surface: runtime-config
 schema-version: 0.1.0
 last-changed: 2026-04-27
 breaking-change-policy: deprecate-2-minors

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

@@ -10,10 +10,18 @@ description: Close and archive a completed change. Confirms all tasks are done,
 A change is "done" when:
 1. Gate has passed (`cdd-kit gate <change-id>` exits 0)
 2. PR is merged (or change is abandoned)
-3. Durable learnings have been promoted to `contracts/` or `CLAUDE.md`
+3. Durable learnings have been promoted to hot sources: `contracts/`, `CLAUDE.md`, or `CODEX.md`
 
 This skill drives steps 2–3 and physically moves the change to `specs/archive/`.
 
+## Hot / Warm / Cold Data Rules
+
+- Hot data: `contracts/`, source files, tests, CI config, `CLAUDE.md`, `CODEX.md`.
+- Warm data: the active `specs/changes/<change-id>/` directory while the change is open.
+- Cold data: `specs/archive/` after close.
+
+Cold data is historical evidence, not current requirements. Do not promote claims from old specs or archive prose unless they are backed by agent-log evidence, QA evidence, changed contracts, changed tests, or passing gates from this change.
+
 ## Input
 
 The skill argument is the change-id (e.g., `add-jwt-auth`).
@@ -58,7 +66,14 @@ If `7.2` is `[ ]`, proceed to Step 2.5. If already `[x]` or `[-]`, skip Steps 2.
 
 ## Step 2.5: Create archive.md
 
-Read `specs/changes/<change-id>/agent-log/` (all log files) and `specs/changes/<change-id>/qa-report.md` (if exists).
+Read only active evidence for this change:
+- `specs/changes/<change-id>/agent-log/` (all log files)
+- `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`
+
+Do not read `specs/archive/` while closing a change. Historical archives are cold data and must not be used as current requirements.
 
 Synthesize a `specs/changes/<change-id>/archive.md` file with:
 - **Change Summary**: 1 paragraph what was changed and why
@@ -69,24 +84,33 @@ Synthesize a `specs/changes/<change-id>/archive.md` file with:
 - **Production Reality Findings**: any surprises or deviations from the plan (from qa-reviewer agent-log)
 - **Lessons Promoted to Standards**: (leave blank — to be filled in Step 3)
 - **Follow-up Work**: any known issues deferred
+- **Cold Data Warning**: "This archive is historical evidence. Current requirements live in contracts/ and active project guidance."
 
-This file is the source for Step 3's learning promotion.
+This file records the close-out evidence, but Step 3 promotion must still be evidence-gated. Archive prose alone is not enough to change hot data.
 
 ---
 
 ## Step 3: Promote learnings (task 7.2)
 
-Read `specs/changes/<change-id>/archive.md` section `## Lessons Promoted to Standards`.
+Read `specs/changes/<change-id>/archive.md` section `## Lessons Promoted to Standards` and cross-check every proposed lesson against agent-log, QA report, contract/test changes, or gate evidence from this change.
+
+Classify each candidate:
+- **promote-to-contract**: stable product/system behavior, API/data/env/business/CI rule, compatibility rule, or testable invariant.
+- **promote-to-guidance**: durable workflow guidance for future agents, provider-specific operating instructions, or project-specific agent constraints. Target `CLAUDE.md` and/or `CODEX.md`.
+- **do-not-promote**: one-off implementation detail, abandoned approach, temporary workaround, historical rationale, or anything contradicted by current contracts.
 
 If there are lessons to promote, invoke `contract-reviewer` with:
 - The archive.md lessons section
-- Instruction: "Review these lessons and propose specific additions to the relevant contract files. For each lesson, output: target file, target section, proposed text (≤ 5 lines), schema-version bump required (yes/no)."
+- Supporting evidence from agent-log / QA / changed contracts / changed tests
+- Instruction: "Review these lessons and propose specific additions only for evidence-backed durable rules. For each lesson, output: classification, target file, target section, proposed text (≤ 5 lines), evidence path, schema-version bump required (yes/no). Reject any cold-data-only or one-off lesson."
 
 After contract-reviewer responds:
-1. Apply each proposed addition to the contract file (YOU write)
-2. Run `cdd-kit validate --contracts` to confirm format is preserved
-3. Fill in `## Lessons Promoted to Standards` in archive.md with what was promoted
-4. Tick `7.2` in tasks.md
+1. Apply each approved contract addition to the contract file (YOU write)
+2. Apply each approved guidance addition to `CLAUDE.md` and/or `CODEX.md` only if it is provider/project guidance, not product behavior
+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
 
 If there are no lessons to promote, mark `[-]` for 7.2 with rationale.
 
@@ -108,7 +132,7 @@ If successful, tick `7.1` in tasks.md (the file is now in specs/archive/, update
 
 Change ID: <change-id>
 Archived to: specs/archive/<year>/<change-id>/
-Learnings promoted: <list what was added to contracts/CLAUDE.md, or "none">
+Learnings promoted: <list what was added to contracts/CLAUDE.md/CODEX.md, or "none">
 
 specs/changes/<change-id>/ has been removed from the active surface.
 Token cost of future sessions reduced by ~<N> files.
@@ -120,4 +144,7 @@ Token cost of future sessions reduced by ~<N> files.
 
 - NEVER archive before gate passes (unless user explicitly confirms abandoned)
 - NEVER skip Step 3 — lessons rot if not promoted
+- NEVER treat `specs/archive/` as hot requirements
+- NEVER promote a lesson without an evidence path from this change
+- Product behavior belongs in `contracts/`; agent workflow guidance belongs in `CLAUDE.md` and/or `CODEX.md`
 - The archive command is irreversible without git — remind user to commit after archiving