contract-driven-delivery 1.12.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,174 @@
 # Changelog
 
+## [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
+
+- `/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,16 +90,19 @@ 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
 - 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
 
 ---
 
@@ -139,12 +142,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.
 
 ---
 
@@ -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,24 +281,27 @@ 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:
-- 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
-- Validates that every file path listed in `agent-log` artifact pointers actually exists on disk
+- 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
 
+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`).
 
 ```
@@ -302,8 +309,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)
 ```
 
 ---
@@ -335,13 +342,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"
@@ -352,7 +359,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
@@ -362,15 +369,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
 ```
@@ -405,9 +412,10 @@ 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.
+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.
 
 ---
 
@@ -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,9 +465,12 @@ 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
 ```
 
-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.
+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.yml`.
 
 ---
 
@@ -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:
@@ -546,7 +559,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
 
@@ -593,7 +606,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
@@ -617,15 +630,22 @@ your-repo/
 
 ---
 
-## Task notation in `tasks.md`
+## Task notation in `tasks.yml`
 
-```markdown
-- [x] 1.1 Confirm classification       ← done
-- [-] 2.2 CSS/UI contract              ← N/A (not applicable to this change)
-- [ ] 4.1 Backend implementation       ← pending
-```
-
-`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/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

@@ -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
@@ -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>.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.
 
 ### 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.yml`.
+
+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:
@@ -59,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)
 
@@ -135,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
@@ -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>.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.
 
 ### 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.