contract-driven-delivery 1.12.0 → 1.16.0

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

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

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

@@ -86,7 +86,7 @@ Ask the user: "Continue from <next-agent>? (yes/no)"
 
 ## Step 3: Continue the flow
 
-If user confirms, resume from the next agent in the Tier sequence (refer to `/cdd-new` Step 3 for the agent order). 
+If user confirms, resume from the next agent in the Tier sequence (refer to `/cdd-new` Step 3 for the agent order, and `/cdd-new` "Agent stage badges" for the colored badges to use in your narration).
 
 **Critical**: Inject this block at the start of every agent prompt:
 

package/assets/skills/contract-driven-delivery/references/agent-log-protocol.md

@@ -0,0 +1,117 @@
+# Agent Log Protocol
+
+All cdd-kit agents share the same machine-verifiable agent-log format. This file
+is the single source of truth — agent prompts reference it instead of inlining
+the format. `cdd-kit gate` parses these files; drift here equals silent gate
+skips, so do not re-document this in agent prompts.
+
+## Output target
+
+Each agent writes (or has main Claude write) one file per run:
+
+```
+specs/changes/<change-id>/agent-log/<agent-name>.md
+```
+
+If the same agent runs more than once for a change (e.g., after fix-back),
+overwrite the file — only the latest run is gate-relevant.
+
+## Required structure
+
+```
+# <Agent Display Name> Log
+- change-id: <id>
+- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
+- status: complete | needs-review | blocked
+- files-read:
+  - <repo-relative path>
+  - <repo-relative path>
+- artifacts:
+  - <evidence-type>: <concrete pointer>
+  - <evidence-type>: <concrete pointer>
+- next-action: <one line, or "none">
+```
+
+### Field rules
+
+- `change-id` — must match the directory name. Mismatch is a contract violation.
+- `timestamp` — ISO 8601 UTC. Used by spec-drift-auditor for ordering.
+- `status` — exactly one of `complete | needs-review | blocked`. Anything
+  else (e.g. `done`, `OK`, `pending`) fails gate.
+- `files-read` — required for context-governed changes (`tasks.md` frontmatter
+  has `context-governance: v1`). Each entry must be a repo-relative path.
+  Absolute paths and `..` traversal are rejected. If you legitimately read
+  nothing beyond your own change directory, write:
+  ```
+  - files-read:
+    - specs/changes/<change-id>/
+  ```
+- `artifacts` — concrete pointers only. Allowed forms:
+  - `path/to/file.ts:10-45`
+  - `tests/foo.test.ts::should reject empty body`
+  - `cdd-kit gate <id>: 0 errors` (command + outcome)
+  - `contracts/api/api-contract.md#endpoints` (file + anchor)
+  - **Never** `verified`, `OK`, `done`, or unscoped prose.
+- `next-action` — when `status: blocked`, this must be ≥ 10 chars and
+  not `none`. When `status: complete`, `none` is acceptable.
+
+## Per-agent additional artifact requirements
+
+Each agent prompt lists its own `### Required artifacts for this agent`. The
+gate does not enforce those today; they are a discipline contract enforced by
+`qa-reviewer` and `contract-reviewer`. If you add a required artifact in an
+agent prompt, also update the qa-reviewer checklist.
+
+## Self-validation before submitting your response
+
+**Every agent MUST self-validate its draft Agent Log block before finishing.**
+A malformed log block forces `cdd-kit gate` to fail, which forces the skill
+to re-invoke you, which costs the user another full agent round. Self-lint is
+~5 seconds; a re-run is minutes and dollars.
+
+Before sending your final response, re-read your `## Agent Log` block and
+verify each item:
+
+- [ ] **All four required keys exist**: `status`, `files-read`, `artifacts`,
+      `next-action`. (Plus `change-id`, `timestamp` at the top.)
+- [ ] **`status` is one of**: `complete`, `needs-review`, `blocked` — not
+      `done`, `OK`, `pending`, `wip`, or anything else.
+- [ ] **Every `artifacts:` line has a concrete pointer**:
+      - GOOD: `tests-added: tests/foo.test.ts::should reject empty body`
+      - GOOD: `files-changed: src/api/users.ts:45-67`
+      - GOOD: `test-output: 5 passed (last 10 lines: …)`
+      - BAD: `tests-added: verified`
+      - BAD: `files-changed: yes`
+      - BAD: `contract: OK`
+      Reject any line whose value would not let a reviewer click through.
+- [ ] **If `status: blocked`, `next-action`** is ≥ 10 chars, is NOT `none`,
+      `investigate further`, `tbd`, or `n/a`, and names the actual next step
+      a human can act on.
+- [ ] **Every `files-read:` entry**: repo-relative path, no leading `/`,
+      no `..`, no `~`. If you read your own change directory only, write
+      `- specs/changes/<change-id>/`.
+
+If any check fails, **fix the block before sending your response**. Do not
+ship a known-bad log and rely on the gate to catch it.
+
+## Gate enforcement summary
+
+`cdd-kit gate` rejects an agent log when any of these are true:
+
+1. The file is missing for a tier-required agent (see CONTRACTS for tier matrix).
+2. `status:` line is missing or has an unknown value.
+3. `status: blocked` without a concrete `next-action`.
+4. `files-read` is missing for a context-governed change, or contains an
+   absolute path / `..` segment / forbidden path.
+5. With `--strict`: any `- artifacts:` entry whose value looks like a path but
+   does not exist on disk.
+
+## Why this lives in references/
+
+The historical mistake was duplicating the protocol inside every agent prompt.
+Sixteen agents × ~30 lines = ~480 lines of identical text loaded on every
+spawn. Moving it here:
+
+- Cuts per-agent prompt size by 25–35%.
+- Makes drift between agents impossible (one file to change).
+- Lets gate.ts behavior, tests, and prompts stay in sync via this single doc.

package/assets/specs-templates/context-manifest.md

@@ -1,22 +1,16 @@
 # Context Manifest
 
-This manifest defines the approved context boundaries for agents working on this change.
+This manifest defines the approved context boundaries for agents working on
+this change. The forbidden-paths baseline lives in `.cdd/context-policy.json`
+and is automatically applied by `cdd-kit gate` — do not duplicate it here.
 
 ## Affected Surfaces
 -
 
 ## Allowed Paths
 - specs/changes/<change-id>/
-
-## Forbidden Paths
-- .claude/worktrees/**
-- .git/**
-- node_modules/**
-- dist/**
-- build/**
-- assets/**
-- specs/archive/**
-- specs/changes/* except specs/changes/<change-id>/
+- specs/context/project-map.md
+- specs/context/contracts-index.md
 
 ## Required Contracts
 -
@@ -35,8 +29,8 @@ This manifest defines the approved context boundaries for agents working on this
 ## Context Expansion Requests
 
 <!--
-Agents must request context expansion instead of reading outside their work packet.
-Use this format only for real requests:
+Agents must request context expansion instead of reading outside their work
+packet. Format example for real requests:
 
 - request-id: CER-001
   requested_paths:
@@ -44,6 +38,7 @@ Use this format only for real requests:
   reason: why this file is required
   status: pending
 -->
+-
 
 ## Approved Expansions
 -

package/assets/specs-templates/tasks.md

@@ -1,7 +1,9 @@
 ---
 change-id: <change-id>
 status: in-progress
+tier:
 context-governance: v1
+archive-tasks: ["7.1", "7.2"]
 depends-on: []
 ---