contract-driven-delivery 1.0.1 → 1.6.0

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")