contract-driven-delivery 1.0.0 → 1.6.0

package/assets/skill/scripts/validate_env_semantic.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Semantic validation of the env contract variable table.
+
+Reads contracts/env/env-contract.md (relative to cwd), skips YAML frontmatter,
+finds the variable table (first markdown table whose header starts with '| name |'),
+and validates each data row for:
+  - secret=true AND non-empty default → fail (secrets must not have defaults)
+  - required=true AND secret=false AND empty default → warn only (valid scenario)
+
+Column order expected:
+  name | scope | environments | required | secret | default | example | owner |
+  validation | restart required | failure behavior
+"""
+import sys
+import re
+from pathlib import Path
+
+CONTRACT_PATH = Path('contracts/env/env-contract.md')
+
+# Column indices (0-based)
+COL_NAME     = 0
+COL_REQUIRED = 3
+COL_SECRET   = 4
+COL_DEFAULT  = 5
+
+
+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."""
+    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 is_truthy(val: str) -> bool:
+    """Return True if the value represents a truthy boolean in the table."""
+    return val.lower() in {'true', 'yes', '1'}
+
+
+def is_empty_default(val: str) -> bool:
+    """Return True if the default column represents an absent/empty value."""
+    return val in {'', '-', 'n/a', 'none', '—'}
+
+
+def find_variable_table(lines: list[str]) -> list[tuple[int, str]]:
+    """
+    Find all rows belonging to any table with a '| name |' header in the document.
+    This is robust to blank lines within the table and to the table header appearing
+    multiple times (e.g., when content is appended to a file that already has a header).
+    Returns list of (line_number, raw_line) for all data rows across all matching tables.
+    """
+    # Collect all (line_index, line) pairs that start with '|'
+    # Track which lines are headers, separators, or data rows.
+    in_name_table = False
+    sep_seen = False
+    data_rows: list[tuple[int, str]] = []
+
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+
+        # Blank lines inside a table: keep scanning (don't break out of table mode)
+        if not stripped:
+            continue
+
+        if not stripped.startswith('|'):
+            # Non-pipe line: if we were collecting data, pause (but don't stop searching)
+            # A new section heading might precede another occurrence of the table header.
+            # We keep `in_name_table` True so we capture data rows even after headings.
+            continue
+
+        cells = parse_table_row(stripped)
+        if not cells:
+            continue
+
+        # A header row for a '| name |' table
+        if cells[0].lower() == 'name':
+            in_name_table = True
+            sep_seen = False
+            continue  # skip header row itself
+
+        if not in_name_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))
+
+    return data_rows
+
+
+def main() -> None:
+    cwd = Path('.')
+    contract = cwd / CONTRACT_PATH
+
+    if not contract.exists():
+        print(f'Env 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('Env contract: file is empty.')
+        sys.exit(1)
+
+    body = strip_frontmatter(raw)
+    lines = body.splitlines()
+
+    data_rows = find_variable_table(lines)
+
+    if not data_rows:
+        print('Env contract: no variable table found')
+        sys.exit(1)
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    for lineno, raw_line in data_rows:
+        cells = parse_table_row(raw_line)
+
+        # Skip entirely empty rows
+        if not any(cells):
+            continue
+
+        # Need at least name, required (col 3), secret (col 4), default (col 5)
+        if len(cells) <= COL_DEFAULT:
+            # Not enough columns to validate — skip silently
+            continue
+
+        name      = cells[COL_NAME]
+        required  = is_truthy(cells[COL_REQUIRED])
+        secret    = is_truthy(cells[COL_SECRET])
+        default_  = cells[COL_DEFAULT]
+
+        # Rule: secret=true AND non-empty default → fail
+        if secret and not is_empty_default(default_):
+            errors.append(
+                f'Line {lineno}: variable "{name}" is secret=true but has '
+                f'a non-empty default value "{default_}" '
+                f'(secrets must not have defaults in the contract)'
+            )
+
+        # Rule: required=true AND secret=false AND empty default → warn only
+        if required and not secret and is_empty_default(default_):
+            warnings.append(
+                f'Line {lineno}: variable "{name}" is required=true, '
+                f'secret=false, and has no default — ensure it is always set.'
+            )
+
+    for w in warnings:
+        print(f'Warning: {w}')
+
+    if errors:
+        print('Env semantic validation failed:')
+        for err in errors:
+            print(f'  {err}')
+        sys.exit(1)
+
+    print(f'Env semantic validation passed ({len(data_rows)} variable(s) checked).')
+
+
+if __name__ == '__main__':
+    main()

package/assets/skill/scripts/validate_spec_traceability.py

@@ -2,17 +2,43 @@
 """Coarse traceability check for a change folder."""
 from pathlib import Path
 import argparse, sys
-REQUIRED=['classification.md','test-plan.md','ci-gates.md','tasks.md']
-def main():
-    ap=argparse.ArgumentParser(); ap.add_argument('change_dir')
-    args=ap.parse_args(); d=Path(args.change_dir)
-    if not d.exists(): print(f'{d} not found'); sys.exit(1)
+REQUIRED=['change-classification.md','test-plan.md','ci-gates.md','tasks.md']
+def check_change_dir(d):
+    """Check one change directory. Returns list of error strings (empty = pass)."""
+    errors=[]
     missing=[f for f in REQUIRED if not (d/f).exists()]
-    if missing: print('Missing required change artifacts: '+', '.join(missing)); sys.exit(1)
+    if missing:
+        errors.append(f'{d.name}: missing required artifacts: '+', '.join(missing))
+        return errors
     text='\n'.join((d/f).read_text(encoding='utf-8', errors='ignore') for f in REQUIRED)
     warnings=[]
     for term in ['contract','test','ci','gate']:
         if term not in text.lower(): warnings.append(term)
-    if warnings: print('Warning: weak traceability terms: '+', '.join(warnings))
-    print('Change traceability basic validation passed.')
+    if warnings: print(f'Warning: {d.name}: weak traceability terms: '+', '.join(warnings))
+    print(f'Change traceability basic validation passed: {d.name}')
+    return errors
+def main():
+    ap=argparse.ArgumentParser(); ap.add_argument('change_dir', nargs='?', default=None)
+    args=ap.parse_args()
+    if args.change_dir is not None:
+        d=Path(args.change_dir)
+        if not d.exists(): print(f'{d} not found'); sys.exit(1)
+        errors=check_change_dir(d)
+        if errors: [print(e) for e in errors]; sys.exit(1)
+        sys.exit(0)
+    # No argument: scan specs/changes/*/
+    changes_root=Path('specs/changes')
+    if not changes_root.exists() or not any(True for _ in changes_root.iterdir() if changes_root.exists()):
+        print('Warning: specs/changes/ not found or empty -- skipping spec traceability validation.')
+        sys.exit(0)
+    subdirs=[p for p in changes_root.iterdir() if p.is_dir()]
+    if not subdirs:
+        print('Warning: specs/changes/ is empty -- skipping spec traceability validation.')
+        sys.exit(0)
+    all_errors=[]
+    for d in sorted(subdirs):
+        all_errors.extend(check_change_dir(d))
+    if all_errors:
+        [print(e) for e in all_errors]; sys.exit(1)
+    sys.exit(0)
 if __name__=='__main__': main()

package/assets/tests-templates/soak/k6-example.js

@@ -0,0 +1,19 @@
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  vus: 5,                  // low constant load
+  duration: '4h',          // long-running
+  thresholds: {
+    http_req_duration: ['p(95)<800'],  // looser threshold for soak
+    http_req_failed:   ['rate<0.005'],  // tighter error rate over long run
+  },
+};
+
+const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000';
+
+export default function () {
+  const res = http.get(`${BASE_URL}/api/health`);
+  check(res, { 'status is 200': (r) => r.status === 200 });
+  sleep(2);  // slower cadence; we are looking for leaks, not throughput
+}

package/assets/tests-templates/soak/locust-example.py

@@ -0,0 +1,21 @@
+"""Locust example: soak profile (long-running, low load).
+
+Run:  locust -f tests/templates/soak/locust-example.py \
+        --headless -u 5 -r 1 --run-time 4h \
+        --host http://localhost:3000
+
+Soak focuses on stability over time, not peak throughput.
+Watch for: memory growth, connection exhaustion, queue backlog,
+latency drift, error rate creep.
+"""
+from locust import HttpUser, task, between
+
+
+class SoakUser(HttpUser):
+    wait_time = between(2.0, 5.0)
+
+    @task
+    def health_check(self):
+        with self.client.get("/api/health", catch_response=True) as r:
+            if r.status_code != 200:
+                r.failure(f"unexpected status {r.status_code}")

package/assets/tests-templates/soak/soak-profile.md

@@ -13,3 +13,19 @@
 ## Failure Thresholds
 
 ## Artifact Retention
+
+## Runner Config (REQUIRED — fill before running)
+
+- runner: k6 | locust | artillery
+- config file: tests/soak/<scenario>.<ext>
+- target environment:
+- constant load (VUs or arrival rate):
+- duration: <!-- soak runs are typically 2h–24h+ -->
+- pass criteria (must include leak/drift signals):
+  - memory growth: <!-- e.g., RSS < 1.2× baseline after 4h -->
+  - latency drift: <!-- e.g., p95 within ±10% of hour-1 baseline -->
+  - error rate: <!-- e.g., < 0.5% sustained -->
+- artifacts:
+
+### Reference templates
+See `tests/templates/soak/k6-example.js` or `locust-example.py`.

package/assets/tests-templates/stress/artillery-example.yml

@@ -0,0 +1,27 @@
+# Run:  npx artillery run tests/templates/stress/artillery-example.yml
+config:
+  target: "http://localhost:3000"
+  phases:
+    - duration: 30
+      arrivalRate: 5
+      name: warm-up
+    - duration: 120
+      arrivalRate: 20
+      name: sustain
+    - duration: 30
+      arrivalRate: 5
+      name: cool-down
+  ensure:
+    p95: 500       # 95% under 500ms
+    maxErrorRate: 1  # < 1% errors
+
+scenarios:
+  - name: health-then-list
+    flow:
+      - get:
+          url: "/api/health"
+          expect:
+            - statusCode: 200
+      - think: 1
+      - get:
+          url: "/api/items"

package/assets/tests-templates/stress/k6-example.js

@@ -0,0 +1,22 @@
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '30s', target: 20 },   // ramp up to 20 VUs
+    { duration: '2m',  target: 20 },   // hold 20 VUs
+    { duration: '30s', target: 0 },    // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500'],  // 95% of requests under 500ms
+    http_req_failed:   ['rate<0.01'],   // <1% errors
+  },
+};
+
+const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000';
+
+export default function () {
+  const res = http.get(`${BASE_URL}/api/health`);
+  check(res, { 'status is 200': (r) => r.status === 200 });
+  sleep(1);
+}

package/assets/tests-templates/stress/load-profile.md

@@ -13,3 +13,17 @@
 ## Metrics
 
 ## Thresholds
+
+## Runner Config (REQUIRED — fill before running)
+
+- runner: k6 | locust | artillery   <!-- pick one -->
+- config file: tests/stress/<scenario>.<ext>   <!-- e.g., tests/stress/checkout-load.js -->
+- target environment: <!-- staging | preprod | local -->
+- VUs / arrival rate: <!-- e.g., 50 VUs, or 20 req/s -->
+- duration: <!-- e.g., 3m -->
+- pass criteria: <!-- must reference an SLO, e.g., p95 < 500ms, error rate < 1% -->
+- artifacts: <!-- where stdout/HTML report is stored, e.g., ci/artifacts/stress/<run-id>/ -->
+
+### Reference templates
+See `tests/templates/stress/k6-example.js`, `locust-example.py`, or
+`artillery-example.yml` for runner-specific starting points.

package/assets/tests-templates/stress/locust-example.py

@@ -0,0 +1,21 @@
+"""Locust example: stress profile.
+
+Run:  locust -f tests/templates/stress/locust-example.py \
+        --headless -u 50 -r 5 --run-time 3m \
+        --host http://localhost:3000
+"""
+from locust import HttpUser, task, between
+
+
+class StressUser(HttpUser):
+    wait_time = between(0.5, 2.0)
+
+    @task(3)
+    def health_check(self):
+        with self.client.get("/api/health", catch_response=True) as r:
+            if r.status_code != 200:
+                r.failure(f"unexpected status {r.status_code}")
+
+    @task(1)
+    def list_items(self):
+        self.client.get("/api/items")