contract-driven-delivery 1.9.0 → 1.11.0

package/assets/agents/spec-drift-auditor.md

@@ -1,6 +1,6 @@
 ---
 name: spec-drift-auditor
-description: Audit drift across specs, contracts, implementation, tests, CI/CD gates, tasks, and archived learnings over multiple iterations.
+description: Audit drift between live contracts, implementation code, tests, and CI gates. Does NOT read historical specs/changes — contracts/ is the single source of truth.
 tools: Read, Grep, Glob, Bash
 model: claude-opus-4-7
 ---
@@ -9,22 +9,27 @@ You are the spec drift auditor.
 
 Multi-iteration development creates drift. Find it before it becomes production debt.
 
-## Audit questions
+## Audit axes
 
-- Does every implemented behavior trace to a spec or approved bug fix?
-- Does every spec acceptance criterion have test evidence?
-- Did API/CSS/env/data/business/CI contracts change with the code?
-- Are tasks marked complete actually implemented?
-- Are CI gates running the tests they claim to run?
-- Did completed changes archive durable rules back into contracts?
-- Are old archived specs contradicting current contracts?
+**1. contracts/ vs code**
+- Does every contract entry (API endpoint, business rule, env var, CSS token) have evidence in source code?
+- Does any code behaviour exceed or contradict what contracts declare?
+
+**2. contracts/ vs tests**
+- Does every contract entry have at least one corresponding test?
+- Are tests asserting the correct contract schema (not internal implementation details)?
+
+**3. CI workflows vs ci-gates declarations**
+- Does every gate declared in contracts/ci/ci-gate-contract.md exist in .github/workflows/?
+- Are required gates non-skippable?
+
+By default, do NOT read `specs/changes/` history. Only read historical change records when the user explicitly asks for cross-iteration traceability or historical investigation ("why was X decided?"). Contracts are the authority.
 
 ## Cadence and automation
 
 - Cadence — before every release to main; weekly during active multi-iteration work; ad-hoc when QA finds unexplained behavior.
 - Automatable — file existence, traceability term presence, contract column completeness, CI step presence (already covered by `validate_*.py` scripts).
-- Manual-only — semantic correctness ("does the spec actually describe what shipped?"), archive currency ("does this archive still reflect today's standard?"), cross-iteration redundancy.
-- Sunset policy — archived specs older than 12 months that conflict with current contracts must be either updated, marked superseded, or moved to `specs/archive/_deprecated/`.
+- Manual-only — semantic correctness ("does the spec actually describe what shipped?"), cross-iteration redundancy.
 
 ## Output
 
@@ -43,19 +48,17 @@ Multi-iteration development creates drift. Find it before it becomes production
 
 ## CI/Test Drift
 ...
-
-## Archive Actions Needed
-...
 ```
 
 ## 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/spec-drift-auditor.md`.
+Write this block to `specs/audits/<YYYY-MM-DD>-drift-audit.md` (create the file yourself).
+Use this exact structure (lines starting with `- ` are required):
 
 ```
 ## Agent Log
 # Spec Drift Auditor Log
-- change-id: <id>
+- audit-id: <YYYY-MM-DD>-drift
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
 - artifacts:
@@ -67,12 +70,11 @@ After completing your task, include an **## Agent Log** section at the end of yo
 ### Required artifacts for this agent
 - `surfaces-audited`: list (specs/contracts/code/tests/CI/tasks/archive)
 - `drift-items`: count + severity
-- `drift-summary-path`: path
+- `drift-summary-path`: `specs/audits/<YYYY-MM-DD>-drift-audit.md`
 - `next-audit-due`: ISO date
 
 ### Rules
-- NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log
-  is missing the `status:` line or has an invalid status.
+- NEVER omit this audit summary file. The drift-audit cadence (release / weekly / ad-hoc) requires this file as its persistence record; missing `status:` voids the audit.
 - 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).

package/assets/agents/stress-soak-engineer.md

@@ -60,6 +60,12 @@ Use realistic load profiles rather than arbitrary request loops.
 ...
 ```
 
+## Read scope
+
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
@@ -91,3 +97,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/agents/test-strategist.md

@@ -29,43 +29,46 @@ Design tests before implementation. Prefer concrete test cases, inputs, expected
 
 ## Output
 
-```md
-# Test Plan
+Write to `specs/changes/<change-id>/test-plan.md` using this structure:
 
-## Acceptance Criteria Mapping
-| requirement | test family | test file/spec | expected evidence |
-|---|---|---|---|
+```markdown
+# Test Plan: <change-id>
 
-## Unit Tests
-...
+## Acceptance Criteria → Test Mapping
+| criterion id | test family | test file path | tier |
+|---|---|---|---|
 
-## Contract Tests
-...
+## Test Families Required
+| family | tier | notes |
+|---|---|---|
+| (unit / contract / integration / e2e / data-boundary / resilience / monkey / stress / soak) | | |
 
-## Integration Tests
-...
+## Out of Scope
 
-## E2E Tests
-...
+## Notes
+(Keep under 10 lines. Implementation detail belongs in the test files themselves.)
+```
 
-## Data Boundary Tests
-...
+## Output discipline
 
-## Resilience Tests
-...
+Your output goes into `specs/changes/<id>/test-plan.md`. It must answer WHAT to test and WHY — not HOW to implement the tests.
 
-## Monkey Operation Tests
-...
+- **DO** write: acceptance criteria → test family mapping (table)
+- **DO** write: test file paths and test function names (one line each, no body)
+- **DO** write: tier assignment per test family
+- **DO NOT** write: full test function bodies
+- **DO NOT** write: mock setup details, fixture data, or expected JSON payloads
+- **DO NOT** write: per-test input/output tables with more than 15 rows
+- **DO NOT** write: example assertions or test helper code
 
-## Stress / Soak Tests
-...
+Implementation detail belongs in the test files, not in test-plan.md.
+Target: `test-plan.md` ≤ 100 lines.
 
-## Mutation Checks
-...
+## Read scope
 
-## Commands
-...
-```
+- Allowed: `contracts/`, `tests/`, `src/`, and the change directory provided in `CURRENT_CHANGE_ID` at the top of your prompt
+- **Before reading any file**: confirm the CURRENT_CHANGE_ID from your prompt header. If not provided, ask the caller: "What is the current change-id?" before proceeding.
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
 
 ## Machine-Verifiable Evidence
 
@@ -98,3 +101,10 @@ with this exact structure (lines starting with `- ` are required):
 - 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>/`
+- Forbidden: other `specs/changes/` directories, `specs/archive/`
+
+Read only the current change's directory. Do NOT glob `specs/changes/**` — it pulls historical data into context and wastes tokens.

package/assets/ci-templates/conda.yml

@@ -1,7 +1,7 @@
 - uses: conda-incubator/setup-miniconda@v3
   with:
     environment-file: environment.yml
-    activate-environment: ""  # 空字串讓 conda 從 environment.yml 讀 name
+    activate-environment: "{{conda-env-name}}"
     auto-activate-base: false
 - name: Lint + Type + Test
   shell: bash -el {0}

package/assets/{ci/github-actions → github-workflows}/contract-driven-gates.yml

@@ -1,10 +1,12 @@
 # Contract-driven gates baseline (provided by cdd-kit).
-# Contract validation steps run as-is; application/test commands MUST be customized for your stack.
-# See README.md and ci/gate-policy.md for tier semantics and promotion policy.
+# Application/test commands MUST be customized for your stack.
+# See ci/gate-policy.md for tier semantics and promotion policy.
 
 name: contract-driven-gates
 
 on:
+  push:
+    branches: [main, master]
   pull_request:
   workflow_dispatch:
   schedule:
@@ -21,23 +23,16 @@ jobs:
         with:
           python-version: '3.10'
 
-      - name: Detect project profile
-        run: python .claude/skills/contract-driven-delivery/scripts/detect_project_profile.py . --write project-profile.generated.md || true
-
-      - name: Validate contracts
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_contracts.py .
-
-      - name: Validate env contract
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_env_contract.py contracts/env/env-contract.md
-
-      - name: Validate ci gates
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_ci_gates.py
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
 
-      - name: Validate spec traceability
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_spec_traceability.py
+      - name: Install cdd-kit
+        run: npm install -g contract-driven-delivery
 
-      - name: Validate contract versions
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_contract_versions.py .
+      - name: Validate contracts and gates
+        run: cdd-kit validate
 
       - name: Repository-specific fast gate
         run: |

package/assets/hooks/pre-commit

@@ -14,7 +14,7 @@ change_ids=$(echo "$staged" | grep -oE '^specs/changes/[^/]+' | sort -u | sed 's
 
 for id in $change_ids; do
   echo "[cdd-kit] running gate for change: $id"
-  if ! cdd-kit gate "$id"; then
+  if ! cdd-kit gate "$id" --strict; then
     echo "[cdd-kit] gate failed for $id — commit rejected."
     echo "[cdd-kit] fix issues above; --no-verify bypasses but defeats the kit."
     exit 1

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

@@ -0,0 +1,123 @@
+---
+name: cdd-close
+description: Close and archive a completed change. Confirms all tasks are done, promotes durable learnings, then runs cdd-kit archive. Args: <change-id>
+---
+
+# cdd-close — Close and Archive a Change
+
+## Purpose
+
+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`
+
+This skill drives steps 2–3 and physically moves the change to `specs/archive/`.
+
+## Input
+
+The skill argument is the change-id (e.g., `add-jwt-auth`).
+
+If not provided, ask: "Which change-id do you want to close?"
+
+---
+
+## Abandon path
+
+If the user wants to **abandon** this change (not close as complete):
+
+```
+cdd-kit abandon <change-id> --reason "<reason>"
+```
+
+This marks `tasks.md` as `status: abandoned` and records it in `specs/archive/INDEX.md`. The directory is preserved for git history. Do NOT run the rest of this skill after abandoning.
+
+---
+
+## Step 1: Confirm gate status
+
+Run: `cdd-kit gate <change-id>`
+
+If gate fails: stop and report failures. Do NOT archive a change that hasn't passed gate.
+
+Exception: if `tasks.md` contains `status: gate-blocked`, ask the user: "This change was gate-blocked. Abandon it? (yes/no)". If yes, run `cdd-kit abandon <change-id> --reason "gate-blocked after 3 attempts"` and stop.
+
+---
+
+## Step 2: Review tasks.md section 7
+
+Read `specs/changes/<change-id>/tasks.md`.
+
+Check section 7:
+- `7.1 Archive change` — will be ticked after Step 4
+- `7.2 Promote durable learnings to contracts or CLAUDE.md` — must be done NOW
+
+If `7.2` is `[ ]`, proceed to Step 2.5. If already `[x]` or `[-]`, skip Steps 2.5 and 3.
+
+---
+
+## 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).
+
+Synthesize a `specs/changes/<change-id>/archive.md` file with:
+- **Change Summary**: 1 paragraph what was changed and why
+- **Final Behavior**: what the system now does differently
+- **Final Contracts Updated**: list from agent-log evidence
+- **Final Tests Added / Updated**: list from agent-log evidence
+- **Final CI/CD Gates**: list from ci-gates.md
+- **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
+
+This file is the source for Step 3's learning promotion.
+
+---
+
+## Step 3: Promote learnings (task 7.2)
+
+Read `specs/changes/<change-id>/archive.md` section `## Lessons Promoted to Standards`.
+
+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)."
+
+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
+
+If there are no lessons to promote, mark `[-]` for 7.2 with rationale.
+
+---
+
+## Step 4: Archive
+
+Run: `cdd-kit archive <change-id>`
+
+If successful, tick `7.1` in tasks.md (the file is now in specs/archive/, update it there):
+`specs/archive/<year>/<change-id>/tasks.md` — change `7.1` from `[ ]` to `[x]`.
+
+---
+
+## Step 5: Report
+
+```
+## /cdd-close complete
+
+Change ID: <change-id>
+Archived to: specs/archive/<year>/<change-id>/
+Learnings promoted: <list what was added to contracts/CLAUDE.md, or "none">
+
+specs/changes/<change-id>/ has been removed from the active surface.
+Token cost of future sessions reduced by ~<N> files.
+```
+
+---
+
+## Rules
+
+- NEVER archive before gate passes (unless user explicitly confirms abandoned)
+- NEVER skip Step 3 — lessons rot if not promoted
+- The archive command is irreversible without git — remind user to commit after archiving

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

@@ -186,3 +186,9 @@ Next step: /cdd-new <describe the gap or feature to address first>
 - Gate enforcement starts only after contracts reach 1.0.0
 - Scanning agents only report — YOU (main Claude) write all files
 - If `cdd-kit init` fails: `npm install -g contract-driven-delivery@latest`
+
+---
+
+## After Completion
+
+The `/cdd-init` workflow is now complete. **Return to normal assistant mode immediately.** Answer any question the user asks — including questions unrelated to this project, new feature discussions, or general conversation — without requiring them to use a specific command. Do not wait for a commit or any other action before resuming normal behavior.

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

@@ -5,6 +5,42 @@ description: Start a new tracked change. Scaffolds all required artifacts, class
 
 # cdd-new — New Change Request
 
+## Mental model
+
+- `contracts/` = the single source of truth (live — always reflects current system behaviour)
+- `tests/` = proof the contracts hold (live)
+- `specs/changes/<id>/` = why we decided this back then (passive archive — read only when investigating history, never as input to planning)
+- `CLAUDE.md` = what this project is and how to start work
+
+## Spec depth rules
+
+Every artifact under `specs/changes/<id>/` answers **WHAT** and **WHY**, not HOW.
+
+Soft caps (guidance, not gate-enforced):
+- `spec.md` ≤ 200 lines
+- `design.md` ≤ 150 lines
+- `test-plan.md` ≤ 100 lines
+- `ci-gates.md` ≤ 80 lines
+
+**Forbidden in spec artifacts** (these belong in code/tests, not specs):
+- SQL DDL or migration code → put in migrations/, reference the path
+- ORM model code (SQLAlchemy, Prisma, etc.) → put in source, reference the module
+- Full test function bodies, mock setup, fixture data, expected JSON payloads → put in tests/
+- Runnable code blocks > 10 lines belong in source files, not specs. Pseudocode and mapping tables are fine at any length.
+- Per-test input/output tables with more than 15 rows (data-boundary tests with up to 15 boundary cases are acceptable)
+
+**test-plan.md should contain:**
+- Acceptance criteria → test family mapping (table)
+- Test file paths and test names (one line per test, no implementation detail)
+- Tier assignment per family
+- Out-of-scope list
+
+**design.md should contain:**
+- Architecture summary (1 paragraph)
+- Affected components (table: component | file path | nature of change)
+- Key decisions and rejected alternatives (prose)
+- Migration/rollback strategy (prose, not SQL)
+
 ## Input
 
 The skill argument is the user's change description in natural language (e.g., "add JWT authentication to the API" or "redesign the dashboard homepage").
@@ -26,6 +62,16 @@ If no description is provided, ask the user: "Please describe the change you wan
 
 ---
 
+## Artifact opt-in policy
+
+Only create optional artifacts (`current-behavior.md`, `proposal.md`, `spec.md`, `design.md`, `qa-report.md`, `regression-report.md`) when the classifier's `change-classification.md` explicitly marks them as `yes`.
+
+Note: `archive.md` is created during `/cdd-close`, not during `/cdd-new` — it is not part of the classifier's opt-in surface.
+
+If the classifier marks an artifact as `no` or leaves it blank, **do not create the file** — even if a review agent could contribute to it.
+
+The 5 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`.
+
 ## Step 1: Generate change-id and scaffold
 
 Derive a `change-id` from the description:
@@ -72,18 +118,25 @@ Create `specs/changes/<change-id>/change-classification.md` with blank template:
 ## 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
-| artifact | required | reason |
-|---|---:|---|
-| current-behavior.md | | |
-| proposal.md | | |
-| spec.md | | |
-| design.md | | |
-| contracts.md | | |
-| test-plan.md | yes | every implementation change requires test planning |
-| ci-gates.md | yes | every implementation change requires CI/CD gate planning |
-| qa-report.md | | |
-| regression-report.md | | |
+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 |
+|---|---|---|
+| current-behavior.md | no | |
+| proposal.md | no | |
+| spec.md | no | |
+| design.md | no | |
+| qa-report.md | no | |
+| regression-report.md | no | |
 
 ## Required Contracts
 - API:
@@ -114,21 +167,19 @@ Create `specs/changes/<change-id>/test-plan.md` with blank template:
 ```
 # Test Plan: <change-id>
 
-## Scope
+## Acceptance Criteria → Test Mapping
+| criterion id | test family | test file path | tier |
+|---|---|---|---|
 
-## Unit Tests
-
-## Contract Tests
-
-## Integration Tests
-
-## E2E Tests
-
-## Resilience / Data-Boundary Tests
-
-## Stress / Soak Tests
+## Test Families Required
+| family | tier | notes |
+|---|---|---|
+| (unit / contract / integration / e2e / data-boundary / resilience / monkey / stress / soak) | | |
 
 ## Out of Scope
+
+## Notes
+(Keep under 10 lines. Implementation detail belongs in the test files themselves.)
 ```
 
 Create `specs/changes/<change-id>/ci-gates.md` with blank template:
@@ -146,6 +197,13 @@ Create `specs/changes/<change-id>/ci-gates.md` with blank template:
 
 Create `specs/changes/<change-id>/tasks.md` with ALL checkboxes unchecked:
 ```
+---
+change-id: <change-id>
+status: in-progress
+---
+
+<!-- [x]=done [-]=N/A [ ]=pending -->
+
 # Tasks: <change-id>
 
 ## 1. Preparation
@@ -208,6 +266,8 @@ Invoke `change-classifier` agent with:
 
 Wait until these three 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.
+
 ---
 
 ## Step 3: Read the tier and commission agents
@@ -220,6 +280,13 @@ Read `change-classification.md` to determine the tier. Then invoke agents **in t
 
 If any agent sets `status: blocked` in its log, halt immediately and report the agent's `next-action` to the user — do not proceed to subsequent agents.
 
+**When invoking any agent, always begin the prompt with:**
+```
+CURRENT_CHANGE_ID: <change-id>
+Change directory: specs/changes/<change-id>/
+```
+This ensures the agent's Read scope restriction points to the correct directory.
+
 ---
 
 ### Tier 4–5 (low risk: docs, prompts, config-only, no behavior change)
@@ -242,25 +309,30 @@ If any agent sets `status: blocked` in its log, halt immediately and report the
 
 2. **`test-strategist`** (write-capable) — writes `specs/changes/<change-id>/test-plan.md` directly.
    - YOU tick: applicable items in section 3 based on what test families were planned
+   - Provide the classifier's `## Inferred Acceptance Criteria` list to test-strategist. These become the `criterion id` column in the Acceptance Criteria → Test Mapping table.
 
-3. **`spec-architect`** (write-capable) — only if the classifier flagged an architectural boundary or cross-module impact.
+3. **`spec-architect`** (write-capable) — only if `change-classification.md` contains `Architecture Review Required: yes`.
    - YOU tick: `1.3` (if it produced a gate plan)
 
 4. **`backend-engineer`** (write-capable) — if the change touches server, API, data, or business logic. Writes implementation and its own agent-log.
    - YOU tick: `4.1` and/or `4.3` based on scope
+   - Note: `tasks.md` items 3.1–3.2 (unit/contract/integration tests) are written by `backend-engineer` and/or `frontend-engineer` in TDD fashion — failing tests first, implementation second. Items 3.3–3.5 are written by dedicated test engineers (Tier 0–1 only or when classifier explicitly requires them).
 
 5. **`frontend-engineer`** (write-capable) — if the change touches UI, components, or client-side behavior. Writes implementation and its own agent-log.
    - YOU tick: `4.2`
 
 6. **`dependency-security-reviewer`** (read-only) — if the change touches lockfiles, package manifests, or DB migrations.
+   - **Only invoke if** `change-classification.md` lists lockfiles, package manifests, or DB migrations as affected.
    - YOU write: `agent-log/dependency-security-reviewer.md`
    - YOU tick: applicable security-related items
 
 7. **`ui-ux-reviewer`** (read-only) — if any UI change (run alongside or after frontend-engineer).
+   - **Only invoke if** classifier marks UI/CSS as affected.
    - YOU write: `agent-log/ui-ux-reviewer.md`
    - YOU tick: `5.1`
 
 8. **`visual-reviewer`** (read-only) — if any UI change (run after ui-ux-reviewer).
+   - **Only invoke if** classifier marks UI/CSS as affected.
    - YOU write: `agent-log/visual-reviewer.md`
    - YOU tick: `5.2`
 
@@ -293,6 +365,8 @@ All agents from Tier 2–3, plus insert these after `frontend-engineer` / `backe
 - If backend-only with no UI: skip `frontend-engineer`, `ui-ux-reviewer`, `visual-reviewer`
 - If UI-only with no backend: skip `backend-engineer`
 
+**Resuming from blocked**: After the user resolves the blocking issue, re-invoke the blocked agent (do not restart from Step 1). Continue with the remaining agents in their original order.
+
 ---
 
 ## Step 4: Run the gate
@@ -314,6 +388,8 @@ cdd-kit gate <change-id>
 4. Re-run `cdd-kit gate <change-id>`
 5. Repeat until gate passes (max 3 iterations; if still failing after 3, report to user)
 
+**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.
+
 ---
 
 ## Step 5: Report to user
@@ -364,3 +440,11 @@ Please review the above items and re-run: cdd-kit gate <change-id>
 - Every agent must have its `agent-log/<name>.md` written — YOU write it for read-only agents after receiving their response; write-capable agents write their own
 - Tick the relevant `tasks.md` checkbox immediately after each agent completes — do not batch
 - `qa-reviewer` always runs last and makes the release-readiness decision
+
+---
+
+## After Completion
+
+The `/cdd-new` workflow is now complete. **Return to normal assistant mode immediately.** Answer any question the user asks — including questions unrelated to this change, new feature discussions, debugging help, or general conversation — without requiring them to use a specific command. The git commit shown in the report is a suggestion, not a required next step; do not wait for it before resuming normal behavior.
+
+When the change is merged and ready to close, run `/cdd-close <change-id>` to promote learnings and archive the change directory.