contract-driven-delivery 1.0.0 → 1.6.0

package/assets/agents/visual-reviewer.md

@@ -1,7 +1,8 @@
 ---
 name: visual-reviewer
-description: Review visual output, layout, responsive behavior, screenshot diffs, CSS contract compliance, and component state coverage.
+description: Review pixel-level visual output, layout, responsive viewport behavior, screenshot diffs, CSS contract compliance, and component visual state coverage. Does not cover interaction or copy -- those go to ui-ux-reviewer.
 tools: Read, Grep, Glob, Bash
+model: claude-haiku-4-5-20251001
 ---
 
 You are the visual reviewer.
@@ -17,6 +18,13 @@ Frontend visual changes require evidence. Use screenshots, videos, or a clear ma
 - shared component contract compliance
 - visual regression diff acceptance
 
+## Tooling and matrix
+
+- Snapshot tools — Percy, Chromatic, Playwright `toHaveScreenshot()`; pick one per repo.
+- Diff threshold — start strict (~0.1%) and relax only with documented reason; "approved with diff" must list the changed pixels.
+- Variant matrix — themes (light, dark), languages (LTR, RTL), density (default, compact), reduced motion, high contrast — at least theme + RTL on top of viewport matrix.
+- Asset review — icons, fonts, images must come from the design system or have a documented exception.
+
 ## Output
 
 ```md
@@ -42,3 +50,35 @@ Frontend visual changes require evidence. Use screenshots, videos, or a clear ma
 ## Decision
 approved / changes-required
 ```
+
+## 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):
+
+```
+# Visual Reviewer Log
+- change-id: <id>
+- timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
+- status: complete | needs-review | blocked
+- artifacts:
+  - <evidence-type>: <concrete pointer>
+  - <evidence-type>: <concrete pointer>
+- next-action: <one line, or "none">
+```
+
+### Required artifacts for this agent
+- `screenshots-compared`: list of `<screen>: baseline → current`
+- `diff-percentage`: per-screen
+- `state-coverage`: matrix
+- `tokens-violated`: list of CSS contract violations or "none"
+
+### Rules
+- NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log
+  is missing the `status:` line or has an invalid status.
+- If you cannot complete the task, set `status: blocked` and write a
+  concrete `next-action` (NOT "investigate further" — write the actual
+  next step a human can act on).
+- Evidence must be concrete: file:line, command name + last-10-line stdout,
+  contract path + section, test name, etc. NEVER write "verified" or "OK"
+  without a pointer.

package/assets/ci/github-actions/contract-driven-gates.yml

@@ -1,3 +1,7 @@
+# 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.
+
 name: contract-driven-gates
 
 on:
@@ -11,28 +15,69 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        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: Validate spec traceability
+        run: python .claude/skills/contract-driven-delivery/scripts/validate_spec_traceability.py
+
+      - name: Validate contract versions
+        run: python .claude/skills/contract-driven-delivery/scripts/validate_contract_versions.py .
+
       - name: Repository-specific fast gate
         run: |
-          echo "Replace with repo commands: lint, typecheck, build, unit, contract tests"
+          # TODO: add your stack-specific commands here.
+          # This step is intentionally left as a placeholder — cdd-kit does not assume your stack.
+          # Examples of what belongs here:
+          #   lint:       npx eslint src/ / ruff check . / golangci-lint run
+          #   typecheck:  npx tsc --noEmit / mypy src/
+          #   build:      npm run build / go build ./...
+          #   unit tests: your test runner command (jest, vitest, pytest, go test, etc.)
+          echo "No stack-specific fast gate configured — add lint/typecheck/build/unit-test commands above."
 
   e2e-critical:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Critical E2E placeholder
-        run: echo "Replace with Playwright/Cypress critical journey command"
+
+      - name: Critical E2E
+        run: |
+          # TODO: add your critical E2E command here (Tier 1 — blocks merge).
+          # This step is intentionally left as a placeholder — cdd-kit does not assume your stack.
+          # Examples:
+          #   Playwright:  npx playwright test --project=critical
+          #   Cypress:     npx cypress run --spec "cypress/e2e/critical/**"
+          #   pytest:      python -m pytest tests/e2e/critical/ -x
+          echo "No critical E2E command configured — add your runner command above."
 
   scheduled-stress-soak:
     if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Stress/soak placeholder
-        run: echo "Replace with production-like stress/soak workflow"
+
+      - name: Stress and soak tests
+        run: |
+          # TODO: add your stress/soak workflow here (Tier 4 — weekly long-run gate).
+          # This step is intentionally left as a placeholder — cdd-kit does not assume your stack.
+          # Examples:
+          #   pytest soak:  python -m pytest tests/stress/ --soak-hours=4
+          #   k6 load:      k6 run --vus=50 --duration=4h tests/load/scenario.js
+          #   locust:       locust -f tests/stress/locustfile.py --headless -u 100 -r 10 --run-time 4h
+          echo "No stress/soak command configured — add your runner command above."

package/assets/ci-templates/bun.yml

@@ -0,0 +1,5 @@
+- uses: oven-sh/setup-bun@v1
+  with:
+    bun-version: latest
+- run: bun install --frozen-lockfile
+- run: bun run lint && bun run typecheck && bun test

package/assets/ci-templates/conda.yml

@@ -0,0 +1,11 @@
+- uses: conda-incubator/setup-miniconda@v3
+  with:
+    environment-file: environment.yml
+    activate-environment: ""  # 空字串讓 conda 從 environment.yml 讀 name
+    auto-activate-base: false
+- name: Lint + Type + Test
+  shell: bash -el {0}
+  run: |
+    ruff check . || true
+    mypy src/ || true
+    pytest

package/assets/ci-templates/go.yml

@@ -0,0 +1,12 @@
+- uses: actions/setup-go@v5
+  with:
+    go-version: '1.22'
+    cache: true
+- name: Lint
+  run: |
+    go vet ./... || true
+    which golangci-lint && golangci-lint run || true
+- name: Build + Test
+  run: |
+    go build ./...
+    go test ./...

package/assets/ci-templates/npm.yml

@@ -0,0 +1,6 @@
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    cache: 'npm'
+- run: npm ci
+- run: npm run lint && npm run typecheck && npm test

package/assets/ci-templates/pip.yml

@@ -0,0 +1,10 @@
+- uses: actions/setup-python@v5
+  with:
+    python-version: '3.11'
+- name: Install dependencies
+  run: pip install -r requirements.txt
+- name: Lint + Type + Test
+  run: |
+    ruff check . || true
+    mypy src/ || true
+    pytest

package/assets/ci-templates/pnpm.yml

@@ -0,0 +1,9 @@
+- uses: pnpm/action-setup@v3
+  with:
+    version: 9
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    cache: 'pnpm'
+- run: pnpm install --frozen-lockfile
+- run: pnpm run lint && pnpm run typecheck && pnpm test

package/assets/ci-templates/poetry.yml

@@ -0,0 +1,12 @@
+- uses: actions/setup-python@v5
+  with:
+    python-version: '3.11'
+- name: Install Poetry
+  run: pip install poetry
+- name: Install dependencies
+  run: poetry install --no-interaction
+- name: Lint + Type + Test
+  run: |
+    poetry run ruff check . || true
+    poetry run mypy src/ || true
+    poetry run pytest

package/assets/ci-templates/rust.yml

@@ -0,0 +1,12 @@
+- uses: dtolnay/rust-toolchain@stable
+  with:
+    components: clippy, rustfmt
+- uses: Swatinem/rust-cache@v2
+- name: Lint
+  run: |
+    cargo fmt --check || true
+    cargo clippy -- -D warnings || true
+- name: Build + Test
+  run: |
+    cargo build
+    cargo test

package/assets/ci-templates/unknown.yml

@@ -0,0 +1,4 @@
+- name: Repository-specific fast gate (unconfigured)
+  run: |
+    # TODO: cdd-kit could not detect a stack. Add lint/typecheck/test here.
+    echo "No stack detected — fill this step in manually."

package/assets/ci-templates/uv.yml

@@ -0,0 +1,12 @@
+- uses: actions/setup-python@v5
+  with:
+    python-version: '3.11'
+- name: Install uv
+  run: pip install uv
+- name: Install dependencies
+  run: uv sync
+- name: Lint + Type + Test
+  run: |
+    uv run ruff check . || true
+    uv run mypy src/ || true
+    uv run pytest

package/assets/ci-templates/yarn.yml

@@ -0,0 +1,6 @@
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    cache: 'yarn'
+- run: yarn install --frozen-lockfile
+- run: yarn lint && yarn typecheck && yarn test

package/assets/contracts/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Contracts Changelog
+
+All notable contract surface changes belong here.
+Format: Keep-a-Changelog (https://keepachangelog.com/).
+Versions are semantic per contract type.
+
+While a contract is at 0.x (draft), entries here are optional.
+Once a contract reaches 1.0.0, every schema-version bump must have
+a corresponding entry below.
+
+## [api 0.1.0] — 2026-04-27
+Initial draft.
+
+## [css 0.1.0] — 2026-04-27
+Initial draft.
+
+## [env 0.1.0] — 2026-04-27
+Initial draft.
+
+## [data 0.1.0] — 2026-04-27
+Initial draft.
+
+## [business 0.1.0] — 2026-04-27
+Initial draft.
+
+## [ci 0.1.0] — 2026-04-27
+Initial draft.

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

@@ -1,3 +1,10 @@
+---
+contract: api
+schema-version: 0.1.0
+last-changed: 2026-04-27
+breaking-change-policy: deprecate-2-minors
+---
+
 # API Contract
 
 ## API Style

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

@@ -1,3 +1,10 @@
+---
+contract: business
+schema-version: 0.1.0
+last-changed: 2026-04-27
+breaking-change-policy: deprecate-2-minors
+---
+
 # Business Rules
 
 ## Rule Inventory

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

@@ -1,3 +1,10 @@
+---
+contract: ci
+schema-version: 0.1.0
+last-changed: 2026-04-27
+breaking-change-policy: deprecate-2-minors
+---
+
 # CI/CD Gate Contract
 
 ## Gate Inventory

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

@@ -1,3 +1,10 @@
+---
+contract: css
+schema-version: 0.1.0
+last-changed: 2026-04-27
+breaking-change-policy: deprecate-2-minors
+---
+
 # CSS / UI Contract
 
 ## Token Source of Truth

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

@@ -1,3 +1,10 @@
+---
+contract: data
+schema-version: 0.1.0
+last-changed: 2026-04-27
+breaking-change-policy: deprecate-2-minors
+---
+
 # Data Shape Contract
 
 ## Required Columns

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

@@ -1,3 +1,10 @@
+---
+contract: env
+schema-version: 0.1.0
+last-changed: 2026-04-27
+breaking-change-policy: deprecate-2-minors
+---
+
 # Env Contract
 
 | name | scope | environments | required | secret | default | example | owner | validation | restart required | failure behavior |

package/assets/hooks/pre-commit

@@ -0,0 +1,23 @@
+#!/bin/sh
+# cdd-kit-managed-block-start
+# Auto-runs cdd-kit gate for any change folder touched in this commit.
+# Generated by: cdd-kit install-hooks (re-run to update).
+# Bypass with --no-verify (NOT recommended; defeats AI process enforcement).
+
+set -e
+
+staged=$(git diff --cached --name-only --diff-filter=ACM)
+[ -z "$staged" ] && exit 0
+
+change_ids=$(echo "$staged" | grep -oE '^specs/changes/[^/]+' | sort -u | sed 's|specs/changes/||')
+[ -z "$change_ids" ] && exit 0
+
+for id in $change_ids; do
+  echo "[cdd-kit] running gate for change: $id"
+  if ! cdd-kit gate "$id"; 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
+  fi
+done
+# cdd-kit-managed-block-end

package/assets/skill/SKILL.md

@@ -13,32 +13,47 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
 
 1. Classify the request.
    - Use `references/workflow-router.md`.
-   - Create or update `classification.md`.
+   - Create or update `change-classification.md`.
+   - Invoke change-classifier to perform classification.
 2. Scan project context.
    - Use `scripts/detect_project_profile.py` when useful.
    - Capture stack, commands, contracts, tests, and CI/CD.
+   - Invoke repo-context-scanner to capture project profile and standardization gaps.
 3. Select required artifacts.
    - Use templates in `templates/`.
-   - Do not force every artifact for tiny changes, but do require `classification.md`, `test-plan.md`, and `ci-gates.md` for implementation changes.
-4. Update contracts before or alongside implementation.
+   - Do not force every artifact for tiny changes, but do require `change-classification.md`, `test-plan.md`, and `ci-gates.md` for implementation changes.
+4. Update contracts before or alongside implementation. Invoke contract-reviewer to validate API/CSS/env/data/business/CI-CD contracts before or alongside implementation.
    - API: `references/api-contract-standard.md`
    - CSS/UI: `references/css-contract-standard.md`
    - Env: `references/env-contract-standard.md`
    - Data/report shape: `references/data-contract-standard.md`
    - Business logic: `references/business-logic-standard.md`
    - CI/CD: `references/ci-cd-policy.md`
-5. Apply SDD + TDD discipline.
+   - Deps/migrations: invoke `dependency-security-reviewer` whenever the change touches lockfiles, dependency manifests, or database migrations.
+5. Apply SDD + TDD discipline and commission test engineers.
    - Use `references/sdd-tdd-policy.md`.
    - Tests should be planned before implementation and should fail first when feasible.
+   - `test-strategist` authors the test plan (write target: specs/changes/<id>/test-plan.md only).
+   - `e2e-resilience-engineer` implements E2E, failure-injection, and data-boundary tests.
+   - `monkey-test-engineer` implements adversarial-input, fuzz, and rapid-UI-action tests.
+   - `stress-soak-engineer` implements load, soak, and long-running stability tests.
+   - Invoke the relevant test engineer(s) before or alongside implementation based on the risk tier.
+   - Each engineer must read the matching standard before authoring tests: e2e-resilience-engineer → references/e2e-standard.md, monkey-test-engineer → references/monkey-operation-standard.md, stress-soak-engineer → references/stress-soak-standard.md.
 6. Implement through the right role.
    - Backend/frontend work must follow contracts and tests.
    - UI changes require UI/UX and visual review.
+   - Invoke ui-ux-reviewer for interaction, copy, accessibility, and information hierarchy review whenever UI changes.
+   - Invoke visual-reviewer for layout, responsive, CSS contract, and screenshot diff review whenever UI changes.
+   - If implementation reveals an unexpected boundary or architectural constraint, halt and re-invoke `spec-architect` before continuing.
 7. Run quality gates.
    - Use `references/qa-gates.md`.
    - CI/CD gate plan is mandatory.
+   - `qa-reviewer` decides release readiness; Tier 1 gates must be green; Tier 3+ gates must be green or explicitly deferred with a recorded promotion policy.
+   - Invoke ci-cd-gatekeeper to design and enforce the gate plan.
 8. Archive and audit drift.
    - Use `references/spec-drift-policy.md`.
    - Durable learnings must be promoted back to contracts or CLAUDE.md.
+   - `spec-drift-auditor` must run before every release to main and weekly during active multi-iteration development.
 
 ## Required gates by risk
 
@@ -66,6 +81,7 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
 - visual review evidence
 - E2E or component interaction coverage
 - accessibility check
+- See references/visual-review-standard.md for the required state matrix.
 
 ### API/backend/data/report change
 

package/assets/skill/scripts/detect_project_profile.py

@@ -8,12 +8,54 @@ BACKEND_MARKERS = ['pyproject.toml', 'requirements.txt', 'app.py', 'main.py', 'm
 CI_MARKERS = ['.github/workflows', '.gitlab-ci.yml', 'bitbucket-pipelines.yml', '.circleci']
 CONTRACT_DIRS = ['contracts', 'contract']
 
+# The cdd-kit skill directory name — used to detect whether cdd-kit is installed.
+CDD_KIT_SKILL = 'contract-driven-delivery'
+
 def exists(root: Path, rel: str) -> bool:
     return (root / rel).exists()
 
 def list_existing(root: Path, rels):
     return [r for r in rels if exists(root, r)]
 
+def cdd_kit_installed(root: Path) -> bool:
+    """Return True if cdd-kit's skill is present in this repo's .claude directory."""
+    return (root / '.claude' / 'skills' / CDD_KIT_SKILL).exists()
+
+def classify_agents(root: Path, kit_installed: bool):
+    """
+    Return (kit_agents, user_agents) lists of agent .md basenames.
+
+    When cdd-kit is installed, ALL agents found under .claude/agents/ are
+    assumed to originate from the kit installation (the kit ships its own
+    agent suite and deploys it there). Users who add their own agents
+    alongside the kit should note this in their AGENTS.md.
+    If cdd-kit is NOT installed, all agents are treated as user-authored.
+    """
+    agents_dir = root / '.claude' / 'agents'
+    if not agents_dir.is_dir():
+        return [], []
+    all_agents = sorted(p.name for p in agents_dir.glob('*.md'))
+    if not all_agents:
+        return [], []
+    if kit_installed:
+        return all_agents, []
+    return [], all_agents
+
+def classify_skills(root: Path, kit_installed: bool):
+    """
+    Return (kit_skills, user_skills) lists of skill directory names.
+
+    contract-driven-delivery is always flagged as a cdd-kit skill when present.
+    Other skills are user-authored.
+    """
+    skills_dir = root / '.claude' / 'skills'
+    if not skills_dir.is_dir():
+        return [], []
+    all_skills = sorted(p.name for p in skills_dir.iterdir() if p.is_dir())
+    kit_skills = [s for s in all_skills if s == CDD_KIT_SKILL]
+    user_skills = [s for s in all_skills if s != CDD_KIT_SKILL]
+    return kit_skills, user_skills
+
 def detect_commands(root: Path):
     commands = {}
     pkg = root / 'package.json'
@@ -32,18 +74,42 @@ def main():
     ap.add_argument('--write', help='optional output markdown path')
     args = ap.parse_args()
     root = Path(args.root).resolve()
+
     frontend = list_existing(root, FRONTEND_MARKERS)
     backend = list_existing(root, BACKEND_MARKERS)
     ci = list_existing(root, CI_MARKERS)
     contracts = [d for d in CONTRACT_DIRS if (root/d).exists()]
     tests = [p for p in ['tests','frontend/tests','e2e','playwright.config.ts','playwright.config.js'] if (root/p).exists()]
     commands = detect_commands(root)
-    lines = ['# Project Profile', '', f'## Root', str(root), '', '## Detected Markers']
+
+    kit_installed = cdd_kit_installed(root)
+    kit_agents, user_agents = classify_agents(root, kit_installed)
+    kit_skills, user_skills = classify_skills(root, kit_installed)
+
+    lines = ['# Project Profile', '', '## Root', str(root), '', '## Detected Markers']
     lines += ['- frontend: ' + (', '.join(frontend) if frontend else 'none detected')]
     lines += ['- backend: ' + (', '.join(backend) if backend else 'none detected')]
     lines += ['- contracts: ' + (', '.join(contracts) if contracts else 'none detected')]
     lines += ['- tests: ' + (', '.join(tests) if tests else 'none detected')]
     lines += ['- ci/cd: ' + (', '.join(ci) if ci else 'none detected')]
+
+    lines += ['', '## Claude Assets (.claude/)']
+    if kit_installed:
+        lines += [f'- cdd-kit detected (skill: {CDD_KIT_SKILL})']
+    if kit_agents:
+        lines += [f'- agents installed by cdd-kit ({len(kit_agents)}): ' + ', '.join(kit_agents)]
+        lines += ['  (these are bundled by cdd-kit; not user-authored)']
+    if user_agents:
+        lines += [f'- user-authored agents ({len(user_agents)}): ' + ', '.join(user_agents)]
+    if not kit_agents and not user_agents:
+        lines += ['- agents: none detected']
+    if kit_skills:
+        lines += [f'- skills installed by cdd-kit ({len(kit_skills)}): ' + ', '.join(kit_skills)]
+    if user_skills:
+        lines += [f'- user-authored skills ({len(user_skills)}): ' + ', '.join(user_skills)]
+    if not kit_skills and not user_skills:
+        lines += ['- skills: none detected']
+
     lines += ['', '## Suggested Commands']
     if commands:
         lines += [f'- {k}: `{v}`' for k,v in sorted(commands.items())]
@@ -57,5 +123,6 @@ def main():
     if args.write:
         Path(args.write).write_text(out, encoding='utf-8')
     print(out)
+
 if __name__ == '__main__':
     main()

package/assets/skill/scripts/generate_change_scaffold.py

@@ -15,8 +15,8 @@ def main():
     dest=root/'specs'/'changes'/args.change_id
     dest.mkdir(parents=True, exist_ok=False)
     mapping={
-        'change-request.md':'request.md',
-        'change-classification.md':'classification.md',
+        'change-request.md':'change-request.md',
+        'change-classification.md':'change-classification.md',
         'current-behavior.md':'current-behavior.md',
         'proposal.md':'proposal.md',
         'spec.md':'spec.md',