contract-driven-delivery 1.0.1 → 1.6.0

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',

package/assets/skill/scripts/validate_api_semantic.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Semantic validation of the API contract endpoint table.
+
+Reads contracts/api/api-contract.md (relative to cwd), skips YAML frontmatter,
+finds the endpoint table (first markdown table whose header starts with '| method |'),
+and validates each data row for:
+  - method ∈ VALID_METHODS
+  - path starts with '/'
+  - auth ∈ VALID_AUTH
+  - at least 5 columns present
+"""
+import sys
+import re
+from pathlib import Path
+
+VALID_METHODS = {'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'}
+VALID_AUTH = {'required', 'optional', 'admin', 'none', 'public'}
+
+CONTRACT_PATH = Path('contracts/api/api-contract.md')
+
+
+def strip_frontmatter(text: str) -> str:
+    """Remove YAML frontmatter delimited by --- ... ---."""
+    if text.startswith('---'):
+        end = text.find('\n---', 3)
+        if end != -1:
+            return text[end + 4:].lstrip('\n')
+    return text
+
+
+def parse_table_row(line: str) -> list[str]:
+    """Split a markdown table row into stripped cell values."""
+    # Remove leading/trailing pipes and whitespace, then split on '|'
+    row = line.strip().strip('|')
+    return [cell.strip() for cell in row.split('|')]
+
+
+def is_separator_row(cells: list[str]) -> bool:
+    """Return True if this is a markdown table separator (---|---|...)."""
+    return all(re.match(r'^:?-+:?$', c) for c in cells if c)
+
+
+def find_endpoint_table(lines: list[str]) -> list[tuple[int, str]]:
+    """
+    Find all data rows across ALL '| method |' tables in the document.
+    Blank lines and prose between rows do not end collection, making this
+    robust to files where content is appended after the original table block.
+    """
+    in_table = False
+    sep_seen = False
+    data_rows: list[tuple[int, str]] = []
+
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+
+        if not stripped:
+            continue  # blank lines never end table mode
+
+        if not stripped.startswith('|'):
+            # Non-pipe line: keep searching (don't break)
+            # A new `## heading` may precede a duplicate table header
+            continue
+
+        cells = parse_table_row(stripped)
+        if not cells:
+            continue
+
+        # A header row for an endpoint table
+        if cells[0].lower() == 'method':
+            in_table = True
+            sep_seen = False
+            continue  # skip header row
+
+        if not in_table:
+            continue
+
+        # Separator row
+        if not sep_seen and is_separator_row(cells):
+            sep_seen = True
+            continue
+
+        # Data row
+        data_rows.append((i + 1, line))  # 1-based line numbers
+
+    return data_rows
+
+
+def main() -> None:
+    cwd = Path('.')
+    contract = cwd / CONTRACT_PATH
+
+    if not contract.exists():
+        print(f'API contract not found: {CONTRACT_PATH}')
+        sys.exit(1)
+
+    try:
+        raw = contract.read_text(encoding='utf-8', errors='ignore')
+    except OSError as e:
+        print(f'Cannot read {CONTRACT_PATH}: {e}')
+        sys.exit(1)
+
+    if not raw.strip():
+        print('API contract: file is empty.')
+        sys.exit(1)
+
+    body = strip_frontmatter(raw)
+    lines = body.splitlines()
+
+    data_rows = find_endpoint_table(lines)
+
+    if not data_rows:
+        print('API contract: no endpoint table found')
+        sys.exit(1)
+
+    errors: list[str] = []
+
+    for lineno, raw_line in data_rows:
+        cells = parse_table_row(raw_line)
+
+        # Skip entirely empty rows (blank table filler lines)
+        if not any(cells):
+            continue
+
+        # Must have at least 5 columns: method, path, auth, request, response
+        if len(cells) < 5:
+            errors.append(
+                f'Line {lineno}: row has only {len(cells)} column(s), need at least 5: {raw_line.strip()}'
+            )
+            continue
+
+        method = cells[0].upper()
+        path   = cells[1]
+        auth   = cells[2].lower()
+
+        if method not in VALID_METHODS:
+            errors.append(
+                f'Line {lineno}: invalid method "{cells[0]}" '
+                f'(valid: {", ".join(sorted(VALID_METHODS))})'
+            )
+
+        if not path.startswith('/'):
+            errors.append(
+                f'Line {lineno}: path "{path}" does not start with "/"'
+            )
+
+        if auth not in VALID_AUTH:
+            errors.append(
+                f'Line {lineno}: invalid auth "{cells[2]}" '
+                f'(valid: {", ".join(sorted(VALID_AUTH))})'
+            )
+
+    if errors:
+        print('API semantic validation failed:')
+        for err in errors:
+            print(f'  {err}')
+        sys.exit(1)
+
+    print(f'API semantic validation passed ({len(data_rows)} endpoint(s) checked).')
+
+
+if __name__ == '__main__':
+    main()