contract-driven-delivery 1.12.0 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # Changelog
 
+## [1.16.0] - 2026-04-30
+
+### Visual narration: per-agent stage badges
+
+- `/cdd-new` skill now instructs main Claude to prefix every agent
+  invocation announcement with a colored emoji badge tagging the role and
+  stage. Non-engineer users can scan the chat stream and see "we're at
+  review now, not implementation" without reading prompts.
+- Six color buckets:
+  - 🟣 decision (classifier, architect — opus-class)
+  - 🔵 implementation (backend, frontend, ci-cd, sonnet-class)
+  - 🟡 test planning (test-strategist)
+  - 🟠 heavy testing (e2e, monkey, stress — Tier 0–1 only; orange = scope warning)
+  - 🟢 review (read-only verdicts)
+  - ⚫ audits & scans (background, read-only)
+- `/cdd-resume` references the same badge table so resumed flows look
+  consistent.
+
+### Notes
+
+This is the only PR in the v1.13 follow-up series that changes the visible
+chat narration. Prompt-only; no code or test changes.
+
+## [1.15.0] - 2026-04-30
+
+### Workflow safety net (defaults that protect non-engineers)
+
+- `cdd-kit new` auto-runs `context-scan` when `specs/context/*.md` indexes are
+  missing or stale (B5 hash-based check). Avoids classifier wasting a round
+  on outdated paths. New `--skip-scan` for advanced users.
+- `cdd-kit gate` now lints `tasks.md` frontmatter:
+  - Requires `change-id` and `status`.
+  - Validates `status` against known set (`in-progress`, `completed`,
+    `gate-blocked`, `abandoned`, `needs-review`, `complete`, `done`).
+  - Warns on unknown keys with did-you-mean suggestions (e.g. `Tier:` →
+    `did you mean tier?`). Catches the typo class that previously caused
+    silent enforcement skips.
+- `cdd-kit gate` now detects `depends-on` cycles via DFS and reports the
+  full cycle path (e.g. `feat-a → feat-b → feat-c → feat-a`).
+- `cdd-kit doctor --fix`: auto-resolves the safe subset of warnings
+  - regenerates stale or missing `specs/context/*.md` indexes
+  - populates empty `model-policy.json` roles with defaults
+  - leaves invasive fixes (`.cdd/*` missing → suggests `cdd-kit upgrade`)
+    for the user to confirm
+- `cdd-kit gate`: artifact-pointer existence check now runs **by default**
+  (previously `--strict`-only). Use `--lax` to skip for legacy repos with
+  unfixed agent logs.
+
+### Tests
+
+- 11 new tests across `gate.test.ts` (frontmatter lint, DAG cycle, default
+  pointer check), `new.test.ts` (auto-scan), `doctor.test.ts` (--fix).
+- Updated `gate.test.ts` test 13b — its premise inverted by PR-3 #6.
+- Updated `writeValidChangeArtifacts` helper to include required frontmatter.
+
+## [1.14.0] - 2026-04-30
+
+### Agent efficiency for non-engineer users
+
+- `/cdd-new` Step 0: request-quality pre-lint. Refuses to run when the user's
+  request is missing affected-surface, desired-behavior, or success-criterion.
+  Avoids one full classifier round-trip on ambiguous requests.
+- `change-classifier`: atomic-split detection. Mega-requests crossing 2+
+  change-types or 3+ surfaces now return an `## Atomic Split Proposal` table
+  with suggested `cdd-kit new --depends-on` commands instead of a single
+  Tier 0/1 monolith. Estimated 40-60% token saving on multi-feature requests.
+- `references/agent-log-protocol.md`: every agent must self-validate its log
+  block before sending its response. Prevents the round-trip where gate
+  catches a malformed log and forces a full agent re-run.
+- `/cdd-new` Step 4 fix-back: structured error-to-agent routing table. Each
+  gate error class now has a defined re-invocation owner and a templated
+  prompt prefix that includes the verbatim gate error. No more "blind retry".
+
+### Notes
+
+This release is prompt-only (no code changes in `src/`). Improvements are
+qualitative for the AI agent flow, not exposed as new CLI flags.
+
+## [1.13.0] - 2026-04-29
+
+### Token-budget reductions
+- Shared `references/agent-log-protocol.md` — extracted the duplicated agent-log
+  format block out of all 16 agent prompts. Total agent-prompt size dropped
+  from 1675 → 1344 lines (≈20% smaller). One source of truth, no drift.
+- `/cdd-new` skill no longer inlines the 5 change-template bodies; `cdd-kit
+  new` writes them from disk. Skill went from 483 → ~340 lines (≈30%).
+- Tier 5 fast-path for docs/prompts/config-only changes — classifier now
+  short-circuits the full agent flow when no source/tests/contracts are
+  touched; bounds doc-only token cost to 2 read-only reviews.
+- `context-manifest.md` template no longer duplicates the forbidden-paths list
+  that `.cdd/context-policy.json` already carries.
+- `cdd-kit context-scan` now caps per-directory entries to 50 and supports
+  `--surface <path>` to scope the project map to a sub-tree.
+
+### Stability hardening
+- Tier source moved to `tasks.md` frontmatter `tier: <0-5>`. The legacy
+  `## Tier\n- N` and `**Tier:** Tier N` formats remain as fallback-only;
+  bold-only legacy format produces a migration warning instead of silently
+  skipping tier-specific agent enforcement.
+- Section-7 archive exemption is no longer hard-coded `7\.[12]`; reads from
+  `tasks.md` frontmatter `archive-tasks: ["7.1", "7.2"]` (default preserved).
+- `cdd-kit migrate` is now atomic: per-session backup at
+  `.cdd/migrate-backup/<timestamp>/`, two-phase tmp-write + rename, restore
+  hint on failure. New `--no-backup` opt-out.
+- `cdd-kit migrate` now backfills `tier:` and `archive-tasks:` into legacy
+  `tasks.md` frontmatter automatically.
+- `cdd-kit doctor` freshness check is now content-hash based, not mtime.
+  `git clone` no longer triggers spurious staleness warnings.
+- `cdd-kit context approve|reject --all-pending` resolves every pending
+  Context Expansion Request in one command.
+- `cdd-kit gate` now reconciles agent self-reported `files-read:` against the
+  runtime hook log at `.cdd/runtime/<change-id>-files-read.jsonl`. Undeclared
+  reads warn (or fail under `--strict`).
+- `hooks/post-tool-use-files-read.sh` — Claude Code PostToolUse hook scaffold
+  that records actual Read/Grep/Glob targets for the gate to verify.
+- `cdd-kit gate` now invokes `validate` in-process instead of via
+  `spawnSync(process.execPath, [process.argv[1], ...])`. No more `argv[1]`
+  indirection or extra Node startup.
+- `.cdd/model-policy.json` ships with real role-to-model defaults (no longer
+  empty `{}`). `cdd-kit doctor` warns when an installed agent's `model:`
+  frontmatter drifts from policy. `init`/`upgrade` preserve any custom
+  `roles` overrides instead of clobbering them.
+
+### Skill updates
+- `/cdd-new` now lints classifier output before writing files (`## Tier`,
+  `## Required Agents`, `## Inferred Acceptance Criteria` must be filled).
+- `/cdd-new` writes the classifier's tier into `tasks.md` frontmatter as the
+  authoritative source.
+
+### Tests
+- 19 new tests covering B1–B7 + A5 + B3. 39 gate tests, 15 migrate tests, 9
+  context tests, 7 doctor tests all pass.
+
 ## [1.12.0] - 2026-04-29
 
 ### Added

package/README.md

@@ -1,8 +1,8 @@
 # Contract-Driven Delivery Kit
 
-**cdd-kit** is a contract-driven delivery kit for AI coding agents. It started with Claude Code skills and now keeps the core workflow provider-neutral: contracts-first, test-first, spec-first. Every change goes through classification, contract review, TDD, implementation, and gate verification.
+**cdd-kit** is a contract-driven delivery kit for AI coding agents. It started with Claude Code skills and now keeps the core workflow provider-neutral: contracts-first, test-first, spec-first. Every change goes through classification, contract review, TDD, implementation, and gate verification, with deterministic context indexes and manifest-backed read-scope auditing to keep long agent runs reviewable.
 
-Designed for solo developers and small teams building brownfield production systems (dashboards, APIs, workflow tools, data apps) who want AI to do all the implementation while they stay in the spec-author and reviewer seat.
+Designed for solo developers and small teams building brownfield production systems (dashboards, APIs, workflow tools, data apps), especially when non-engineers or product owners want AI to do the implementation while they stay in the spec-author and reviewer seat.
 
 **Context Governance v1** adds a manifest-driven audit layer for AI agents. New changes include `context-manifest.md`, `agent-log` entries are expected to report `files-read`, and `cdd-kit gate` audits those reads against allowed and forbidden paths. This is governance and review support, not a sandbox.
 
@@ -90,11 +90,14 @@ or
 
 **What happens:**
 1. Claude generates a `change-id` (e.g. `add-jwt-auth`) and scaffolds `specs/changes/add-jwt-auth/`
-2. The `change-classifier` agent (Opus) reads the request, classifies risk and tier, decides which agents are needed
-3. Agents run in order: contracts → test plan → spec/architecture review (if needed) → backend engineer → frontend engineer → CI/CD gates → QA
-4. Each agent produces machine-verifiable evidence (agent-log files)
-5. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
-6. Claude reports a summary and the suggested git commit
+2. If the request is ambiguous, Claude asks back for affected surface, desired behavior, and success criterion before spending a classifier round-trip
+3. The `change-classifier` agent (Opus) reads the request, classifies risk and tier, decides which agents are needed
+4. If the request is too broad, the classifier can return an atomic split proposal instead of forcing one Tier 0/1 monolith
+5. For Tier 0-1 work, Claude's narration uses stage badges so users can tell whether the flow is deciding, implementing, testing, or reviewing
+6. Agents run in order: contracts → test plan → spec/architecture review (if needed) → backend engineer → frontend engineer → CI/CD gates → QA
+7. Each agent produces machine-verifiable evidence (agent-log files)
+8. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
+9. Claude reports a summary and the suggested git commit
 
 **You stay in control by:**
 - Reviewing the `change-classification.md` before implementation starts
@@ -240,16 +243,17 @@ Codex currently has no global assets to update, so Codex-only projects report th
 
 ### `cdd-kit doctor`
 
-Inspects repo-level cdd-kit health without writing files.
+Inspects repo-level cdd-kit health. Default mode is read-only; `--fix` applies only the safe auto-remediations.
 
 ```bash
 cdd-kit doctor
 cdd-kit doctor --strict
+cdd-kit doctor --fix
 cdd-kit doctor --json
 cdd-kit doctor --provider codex
 ```
 
-Checks for missing `.cdd/` policy files, provider guidance (`CLAUDE.md`, `AGENTS.md`, `CODEX.md`), context indexes, stale `specs/context/*` outputs, and contract summary metadata gaps. `--strict` treats warnings as errors. `--json` emits a machine-readable report for CI or wrapper scripts.
+Checks for missing `.cdd/` policy files, provider guidance (`CLAUDE.md`, `AGENTS.md`, `CODEX.md`), context indexes, stale `specs/context/*` outputs, and contract summary metadata gaps. `--strict` treats warnings as errors. `--json` emits a machine-readable report for CI or wrapper scripts. `--fix` currently auto-runs `context-scan` for stale or missing indexes and backfills empty `.cdd/model-policy.json` role bindings, but deliberately does not run invasive repo upgrades for you.
 
 ---
 
@@ -277,6 +281,7 @@ The single quality gate for a change. Blocks merge if anything is missing or inc
 ```bash
 cdd-kit gate add-jwt-auth
 cdd-kit gate add-jwt-auth --strict
+cdd-kit gate add-jwt-auth --lax
 ```
 
 Checks:
@@ -292,9 +297,11 @@ Checks:
 
 `--strict` additionally:
 - Treats any pending `[ ]` tasks (except section 7 archive items) as errors
-- Validates that every file path listed in `agent-log` artifact pointers actually exists on disk
+- Treats runtime-vs-declared `files-read` drift as errors
 - Treats legacy changes missing `context-manifest.md` or `files-read` audit data as errors
 
+Default mode also validates that artifact file pointers listed in `agent-log` evidence exist on disk. Use `--lax` only when cleaning up legacy repos with stale historical logs.
+
 Pre-commit hook uses `--strict` by default (installed via `cdd-kit install-hooks`).
 
 ```
@@ -405,6 +412,7 @@ Approves a pending Context Expansion Request in `context-manifest.md` and adds i
 
 ```bash
 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.
@@ -417,6 +425,7 @@ Rejects a pending Context Expansion Request and records `status: rejected` in th
 
 ```bash
 cdd-kit context reject add-jwt-auth CER-001
+cdd-kit context reject add-jwt-auth --all-pending   # bulk reject every pending request
 ```
 
 ---
@@ -456,8 +465,11 @@ cdd-kit new add-user-auth
 cdd-kit new add-user-auth --all     # include optional templates too
 cdd-kit new add-user-auth --force   # overwrite existing directory
 cdd-kit new add-user-api --depends-on add-user-db
+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.
 
 ---
@@ -506,6 +518,7 @@ Builds deterministic, low-token context indexes for classifiers and orchestrator
 
 ```bash
 cdd-kit context-scan
+cdd-kit context-scan --surface src/server   # scope project-map to a sub-tree (large monorepos)
 ```
 
 Outputs:

package/assets/CLAUDE.template.md

@@ -46,15 +46,7 @@ Run `cdd-kit detect-stack` to verify the detected tech stack.
 For context-governed changes, read `specs/changes/<change-id>/context-manifest.md` before using file-reading or broad search tools.
 
 - Read only paths allowed by the manifest or approved expansions.
-- 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:`.
-
-Required `agent-log/*.md` format:
-
-```md
-- files-read:
-  - contracts/api/api-contract.md
-  - src/server/routes/users.ts
-```
-
-Every entry must be a repo-relative path. Do not omit files, use absolute paths, or use `..`.
+- If more context is needed, stop and write a Context Expansion Request in the manifest (`cdd-kit context request`).
+- The full agent-log format (including `files-read:` schema) is defined in
+  `~/.claude/skills/contract-driven-delivery/references/agent-log-protocol.md`.
+  Read that once; do not paraphrase it elsewhere.

package/assets/agents/backend-engineer.md

@@ -47,21 +47,10 @@ 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`
-with this exact structure (lines starting with `- ` are required):
-
-```
-# Backend Engineer Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- files-read:
-  - <repo-relative path read through tools>
-- 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
 - `files-changed`: list of `path/to/file.ts:line-range`
@@ -69,16 +58,6 @@ with this exact structure (lines starting with `- ` are required):
 - `test-output`: last 10 lines of `npm test` or equivalent stdout
 - `contracts-touched`: list of contract file paths 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.
-
 ## Read scope
 
 - Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`

package/assets/agents/change-classifier.md

@@ -32,6 +32,87 @@ Use `project-map.md` to identify candidate source/test paths and `contracts-inde
 
 When in doubt, classify upward.
 
+### Atomic-split detection (BEFORE producing classification)
+
+Non-engineer users often hand in mega-requests like "redesign the dashboard
+and add JWT auth and migrate sessions". Running these as a single Tier 0/1
+change burns 10+ agents in series, couples unrelated rollback risk, and
+leaves no good fix-back path when one piece blocks.
+
+Before producing a single classification, check these triggers:
+
+- **Cross-feature**: 2+ unrelated change-types ("primary" categories) in one
+  request (e.g. `feature-add` + `migration` + `ui-redesign`).
+- **Cross-surface**: 3+ distinct surfaces touched (auth + UI + DB + email +
+  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`.
+
+If **any one trigger fires**, output `## Atomic Split Proposal` INSTEAD of the
+normal classification, in this exact shape:
+
+```md
+## Atomic Split Proposal
+
+This request spans <N> independent risk surfaces. Running it as one change
+would require <N> agents in series and couple unrelated rollback risk.
+
+Recommended atomic split (each is a separate `cdd-kit new`):
+
+| change-id | scope | tier | depends-on |
+|---|---|---|---|
+| <kebab-id-1> | <one-line scope> | <0-5> | (none) |
+| <kebab-id-2> | <one-line scope> | <0-5> | <kebab-id-1> |
+| <kebab-id-3> | <one-line scope> | <0-5> | <kebab-id-1> |
+
+Suggested commands (run in order):
+
+\`\`\`bash
+cdd-kit new <kebab-id-1>
+cdd-kit new <kebab-id-2> --depends-on <kebab-id-1>
+cdd-kit new <kebab-id-3> --depends-on <kebab-id-1>
+\`\`\`
+
+Estimated token savings vs single Tier 0/1 monolith: ~40-60% (parallel
+review-agent overlap removed, smaller per-change context).
+
+If you want to proceed as a single monolithic change anyway, reply with
+`force-monolithic` and I will produce the normal Tier <X> classification
+instead.
+```
+
+When emitting an Atomic Split Proposal, **also include the standard
+`## Agent Log` block** at the end so `cdd-kit gate` can record this run, but
+mark `status: needs-review` and include `next-action: wait-for-user-approval`.
+Do NOT produce other artifacts (no test-plan, no manifest draft) until the
+user picks a path.
+
+If no trigger fires, skip this section entirely and produce the normal
+classification.
+
+### Tier 5 fast-path (token budget protection)
+
+If, after reading the change-request and project-map, ALL of the following are
+true, output Tier 5 and skip the heavy artifact list:
+
+- Only `*.md`, `*.txt`, `prompts/*`, `AGENTS.md`, `CLAUDE.md`, `CODEX.md`,
+  `README*` are touched (no source, no tests, no contracts).
+- No env var, secret, or runtime configuration change.
+- No public API behavior change.
+
+Tier 5 fast-path output minima:
+- `## Tier` → `- 5`
+- `## Required Agents` → `contract-reviewer` (read-only confirmation that no
+  contracts are touched) and `qa-reviewer` (release readiness, ~1 paragraph).
+- `## Optional Artifacts` → all `no`.
+- `## Required Tests` → all blank.
+
+This exists because previously every doc-only change paid 8–12 agent
+invocations of token cost. The fast-path bounds it to 2 read-only reviews. If
+unsure whether the fast-path applies, classify Tier 4 instead and proceed
+through the normal flow.
+
 ## Output
 
 Use this structure:
@@ -144,21 +225,10 @@ Note: `archive.md` is created during change close-out, not at classification tim
 
 ## 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/change-classifier.md`.
-
-```
-## Agent Log
-# Change Classifier Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- files-read:
-  - <repo-relative path read through tools>
-- 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
 - `tier`: Tier 0-5
@@ -167,16 +237,6 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - `required-reviewers`: list of agent names
 - `context-manifest-draft`: allowed paths and agent work packets based only on `project-map.md` and `contracts-index.md`
 
-### 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.
-
 ## Mixed and edge cases
 
 - A single request can be both `ui-only-change` and `api-only-change` — list both as primary; require both UI/UX-visual review AND contract tests.

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

@@ -64,21 +64,10 @@ 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`
-with this exact structure (lines starting with `- ` are required):
-
-```
-# CI/CD Gatekeeper Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- files-read:
-  - <repo-relative path read through tools>
-- 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
 - `tiers-modified`: list of tier numbers
@@ -86,16 +75,6 @@ with this exact structure (lines starting with `- ` are required):
 - `workflow-files-changed`: list of paths
 - `required-status-checks`: list of check names
 
-### 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/contract-reviewer.md

@@ -63,21 +63,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/contract-reviewer.md`.
-
-```
-## Agent Log
-# Contract Reviewer Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- files-read:
-  - <repo-relative path read through tools>
-- 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
 - `contracts-reviewed`: list of contract file paths
@@ -85,16 +74,6 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - `breaking-changes`: list or "none"
 - `consumers-impacted`: list 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.
-
 ## Read scope
 
 - Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`

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

@@ -64,21 +64,10 @@ approved / changes-required / blocked
 
 ## 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/dependency-security-reviewer.md`.
-
-```
-## Agent Log
-# Dependency Security Reviewer Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- files-read:
-  - <repo-relative path read through tools>
-- 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
 - `packages-reviewed`: list of `<name>@<version>`
@@ -86,12 +75,3 @@ After completing your task, include an **## Agent Log** section at the end of yo
 - `license-issues`: list or "none"
 - `lockfile-changes`: list of files
 
-### 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/e2e-resilience-engineer.md

@@ -41,21 +41,10 @@ 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`
-with this exact structure (lines starting with `- ` are required):
-
-```
-# E2E Resilience Engineer Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- files-read:
-  - <repo-relative path read through tools>
-- 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-files`: list of paths under `tests/e2e/` or `tests/resilience/`
@@ -63,16 +52,6 @@ with this exact structure (lines starting with `- ` are required):
 - `mutation-checks`: list or "none"
 - `trace-artifacts`: paths 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.
-
 ## Read scope
 
 - Allowed: `contracts/`, `tests/`, `src/`, `specs/changes/<current-change-id>/`

package/assets/agents/frontend-engineer.md

@@ -45,21 +45,10 @@ 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`
-with this exact structure (lines starting with `- ` are required):
-
-```
-# Frontend Engineer Log
-- change-id: <id>
-- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
-- status: complete | needs-review | blocked
-- files-read:
-  - <repo-relative path read through tools>
-- 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
 - `files-changed`: list of `path/to/file.tsx:line-range`
@@ -67,16 +56,6 @@ with this exact structure (lines starting with `- ` are required):
 - `screenshot-paths`: list of paths under `specs/changes/<id>/screenshots/`
 - `accessibility-audit`: tool name + score or "skipped: reason"
 
-### 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>/`