spck-conformance 0.1.0__py3-none-any.whl

spck_conformance/__init__.py

@@ -0,0 +1,2 @@
+"""spck-conformance — unofficial capability-adaptive UCP conformance runner."""
+__version__ = "0.1.0"

spck_conformance/_bundle/conformance/checks/engine.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+engine.py — Phase 1 register-driven conformance check engine.
+
+A check cites the register requirement(s) it verifies, evaluates a real server
+response, and declares the mutations that MUST break it. Before any check counts
+toward a verdict, the engine self-validates it: the check must pass on the clean
+response AND fail on every declared mutant (kill-rate). A check that isn't
+mutation-safe is reported kill_safe=False, which the verdict gate downgrades to
+inconclusive (so it can never produce a green). Results feed verdict_gate for an
+honest, coverage-gated report.
+
+Mutations here operate on the CAPTURED response (deterministic golden+mutation),
+which works for stateful checks too — we mutate the final response under test.
+The live mutation_proxy remains for integration/timing/replay cases.
+"""
+import json, sys, ssl, urllib.request, urllib.error, pathlib, glob
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "selfcheck"))
+from verdict_gate import CheckResult, aggregate, CLEAN, DEVIATION, INCONCLUSIVE  # noqa: E402
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+REQ_DIR = ROOT / "conformance" / "requirements"
+
+# ---- TLS: use certifi's CA bundle if available (many Pythons ship no bundle, so a
+# plain urlopen against https fails with CERTIFICATE_VERIFY_FAILED). --insecure skips
+# verification entirely (testing only). -------------------------------------------
+def _make_ssl_context(insecure=False):
+    if insecure:
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        return ctx
+    try:
+        import certifi
+        return ssl.create_default_context(cafile=certifi.where())
+    except Exception:
+        return ssl.create_default_context()
+
+INSECURE = False
+_SSL_CTX = _make_ssl_context()
+
+def set_insecure(v):
+    """Toggle TLS verification (used by the --insecure CLI flag)."""
+    global INSECURE, _SSL_CTX
+    INSECURE = bool(v)
+    _SSL_CTX = _make_ssl_context(INSECURE)
+
+class TLSError(Exception):
+    """Raised on a TLS certificate verification failure, with a friendly hint."""
+
+# ---- response capture -------------------------------------------------------
+class Resp:
+    def __init__(self, status, headers, body):
+        self.status, self.headers, self.body = status, dict(headers), body
+        try: self.json = json.loads(body)
+        except Exception: self.json = None
+    def clone(self):
+        return Resp(self.status, dict(self.headers), self.body)
+
+def fetch(base, path, method="GET", body=None, headers=None):
+    data = json.dumps(body).encode() if body is not None else None
+    h = {"Content-Type": "application/json", **(headers or {})}
+    req = urllib.request.Request(base.rstrip("/") + path, data=data, method=method, headers=h)
+    try:
+        with urllib.request.urlopen(req, context=_SSL_CTX) as r:
+            return Resp(r.status, r.getheaders(), r.read())
+    except urllib.error.HTTPError as e:
+        return Resp(e.code, e.headers.items(), e.read())
+    except Exception as e:
+        return Resp(0, {}, str(e).encode())
+
+# ---- mutations on a captured response (defect injection) --------------------
+def _reparse(r):
+    r.body = json.dumps(r.json).encode() if r.json is not None else r.body
+    return r
+def mutate(resp, mut):
+    r = resp.clone()
+    name, _, arg = mut.partition(":")
+    if name == "status":         r.status = int(arg); return r
+    if name == "empty":          r.body = b""; r.json = None; return r
+    if name == "corrupt-json":   r.body = (r.body or b"{}")[:-1]; r.json = None; return r
+    if name == "drop" and r.json is not None:
+        cur = r.json; parts = arg.split(".")
+        for p in parts[:-1]:
+            if isinstance(cur, list) and p.isdigit() and int(p) < len(cur): cur = cur[int(p)]
+            elif isinstance(cur, dict): cur = cur.get(p)
+            else: cur = None
+            if cur is None: break
+        last = parts[-1]
+        if isinstance(cur, dict): cur.pop(last, None)
+        elif isinstance(cur, list) and last.isdigit() and int(last) < len(cur): cur.pop(int(last))
+        return _reparse(r)
+    if name == "set" and r.json is not None:
+        path, _, v = arg.partition("="); val = json.loads(v)
+        cur = r.json; parts = path.split(".")
+        for p in parts[:-1]:
+            if isinstance(cur, list) and p.isdigit() and int(p) < len(cur): cur = cur[int(p)]
+            elif isinstance(cur, dict): cur = cur.get(p)
+            else: cur = None
+            if cur is None: break
+        last = parts[-1]
+        if isinstance(cur, dict): cur[last] = val
+        elif isinstance(cur, list) and last.isdigit() and int(last) < len(cur): cur[int(last)] = val
+        return _reparse(r)
+    if name == "hset":       # set/replace a response header (case-insensitive): hset:Content-Type=text/plain
+        k, _, v = arg.partition("=")
+        for hk in [h for h in r.headers if h.lower() == k.lower()]: r.headers.pop(hk)
+        r.headers[k] = v; return r
+    if name == "hdrop":      # remove a response header (case-insensitive)
+        for hk in [h for h in r.headers if h.lower() == arg.lower()]: r.headers.pop(hk)
+        return r
+    return r  # no-op (mutation not applicable)
+
+# ---- check spec -------------------------------------------------------------
+class Check:
+    def __init__(self, cid, req_ids, keyword, fetch_fn, predicate, mutations):
+        self.id, self.req_ids, self.keyword = cid, req_ids, keyword
+        self.fetch_fn, self.predicate, self.mutations = fetch_fn, predicate, mutations
+
+def run_check(chk, base):
+    """Returns (results: list[CheckResult], detail: dict). kill_safe is computed by
+    mutation: clean must pass, every declared mutant must deviate."""
+    try:
+        golden = chk.fetch_fn(base)
+    except Exception as e:
+        kill_safe = False
+        res = [CheckResult(rid, chk.keyword, INCONCLUSIVE, kill_safe) for rid in chk.req_ids]
+        return res, {"clean": "error:" + str(e), "kills": "", "kill_safe": kill_safe}
+    clean = chk.predicate(golden)
+    kills, survivors = 0, []
+    for m in chk.mutations:
+        if chk.predicate(mutate(golden, m)) == DEVIATION: kills += 1
+        else: survivors.append(m)
+    kill_safe = (clean == CLEAN and not survivors)
+    status = clean if kill_safe else (clean if clean == DEVIATION else INCONCLUSIVE)
+    res = [CheckResult(rid, chk.keyword, status, kill_safe) for rid in chk.req_ids]
+    return res, {"clean": clean, "kills": f"{kills}/{len(chk.mutations)}",
+                 "kill_safe": kill_safe, "survivors": survivors}
+
+# ---- inscope MUSTs from the register (coverage denominator) -----------------
+def inscope_musts(version, transports=("rest", "any")):
+    ids = set()
+    for f in glob.glob(str(REQ_DIR / version / "*.json")):
+        for r in json.load(open(f)).get("rows", []):
+            if r["keyword"] in ("MUST", "MUST NOT") and r["testability"] == "testable" \
+               and any(t in transports for t in r.get("transport", [])):
+                ids.add(r["id"])
+    return ids
+
+def run_report(checks, base, version, scope_stamp, disclaimer, transports=("rest", "any")):
+    all_results, details = [], []
+    for chk in checks:
+        res, det = run_check(chk, base)
+        all_results += res
+        details.append((chk, det))
+    rep = aggregate(all_results, inscope_musts(version, transports), scope_stamp, disclaimer)
+    return rep, details

spck_conformance/_bundle/conformance/checks/merchant.py

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""
+merchant.py — Phase A: the MERCHANT-AGNOSTIC conformance runner.
+
+Point it at ANY UCP server. It discovers the server's spec version + declared
+capabilities from /.well-known/ucp, then runs only the checks that apply:
+  * discovery/structural checks run on every server (no seeded data);
+  * extension checks (fulfillment, discount, catalog, cart) run ONLY if the server
+    declares that capability — otherwise `not-applicable` (never a deviation);
+  * data-dependent lifecycle checks run against an auto-discovered product (catalog
+    search) or a product id from an optional merchant config; otherwise `not-tested`.
+
+The verdict denominator is the set of APPLICABLE testable MUSTs (extensions a server
+doesn't implement are excluded), so a lean-but-correct merchant scores honestly.
+
+  merchant.py --server https://api.example.com [--config merchant.json] [--json]
+"""
+import sys, json, argparse, pathlib, urllib.request, urllib.error, glob
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+from engine import fetch, Resp                    # noqa: E402
+sys.path.insert(0, str(HERE.parents[0] / "selfcheck"))
+from verdict_gate import aggregate                # noqa: E402
+import merchant_checks                            # noqa: E402
+REQ_DIR = HERE.parents[0] / "requirements"
+
+# register area -> the capability a server must declare for that area to be in-scope
+AREA_CAPABILITY = {
+    "fulfillment": "dev.ucp.shopping.fulfillment",
+    "discount-consent-identity": "dev.ucp.shopping.discount",
+    "discounts-consent": "dev.ucp.shopping.discount",
+    "catalog": "dev.ucp.shopping.catalog.search",
+    "cart": "dev.ucp.shopping.cart",
+    "signals-attribution-eligibility": None,   # informational; treat as core
+    "order": "dev.ucp.shopping.order",
+}
+CORE_CAP = "dev.ucp.shopping.checkout"
+
+class MerchantCtx:
+    def __init__(self, base, profile, config):
+        self.base = base.rstrip("/")
+        self.profile = profile
+        self.config = config or {}
+        ucp = profile.get("ucp", profile)          # profile may or may not nest under "ucp"
+        self.version = ucp.get("version")
+        caps = ucp.get("capabilities")
+        # Spec requires capabilities to be a keyed object of reverse-domain names.
+        # Never crash on a non-conformant shape (a real sample ships a list): treat it
+        # as no declared capabilities (extension checks -> not-applicable) and flag it,
+        # so the profile-structure check can report the deviation instead of exploding.
+        if isinstance(caps, dict):
+            self.capabilities = set(caps.keys())
+            self.caps_malformed = False
+        else:
+            self.capabilities = set()
+            self.caps_malformed = caps is not None
+        svc = (ucp.get("services") or {}).get("dev.ucp.shopping") or []
+        rest = next((s for s in svc if isinstance(s, dict) and s.get("transport") == "rest"), None)
+        # A server MAY offer only MCP/embedded transports and still be fully conformant.
+        # This runner is REST-scoped, so absence of a REST transport makes the REST
+        # lifecycle out-of-scope (not-applicable), never a deviation.
+        self.has_rest = rest is not None
+        self.transports = [s.get("transport") for s in svc if isinstance(s, dict)]
+        self.shopping_endpoint = (rest or {}).get("endpoint", self.base)
+        self.product_id = self.config.get("product_id")
+
+def discover(base):
+    import engine
+    try:
+        with urllib.request.urlopen(base.rstrip("/") + "/.well-known/ucp", timeout=10,
+                                    context=engine._SSL_CTX) as r:
+            return json.loads(r.read()), r.headers.get("Content-Type", "")
+    except Exception as e:
+        if "CERTIFICATE_VERIFY_FAILED" in str(e):
+            raise SystemExit(
+                f"discovery failed for {base}: TLS certificate verification failed.\n"
+                f"  Your Python has no CA bundle. Fix with one of:\n"
+                f"    • pip install certifi         (spck-conformance uses it automatically)\n"
+                f"    • macOS python.org build: run 'Install Certificates.command'\n"
+                f"    • re-run with --insecure       (skips TLS verification; testing only)")
+        raise SystemExit(f"discovery failed for {base}: {e}")
+
+def auto_discover_product(ctx):
+    """If the server supports catalog.search, find a real product id to drive lifecycle."""
+    if ctx.product_id:
+        return ctx.product_id
+    if not ctx.has_rest:                     # REST catalog search only; never probe a non-REST store
+        return None
+    if "dev.ucp.shopping.catalog.search" not in ctx.capabilities:
+        return None
+    try:
+        r = fetch(ctx.shopping_endpoint, "/catalog/search", "POST", {"query": "*"},
+                  {"UCP-Agent": 'profile="https://spck.dev/agent"'})
+        prods = (r.json or {}).get("products") or []
+        if prods:
+            v = (prods[0].get("variants") or [{}])[0]
+            return v.get("id") or prods[0].get("id")
+    except Exception:
+        pass
+    return None
+
+def applicable_areas(ctx):
+    """Which register areas are in scope for THIS server, given its declared capabilities."""
+    out = {}
+    for area, cap in AREA_CAPABILITY.items():
+        out[area] = (cap is None) or (cap in ctx.capabilities) or (cap == CORE_CAP)
+    return out
+
+def report(base, config=None):
+    profile, ctype = discover(base)
+    ctx = MerchantCtx(base, profile, config)
+    ctx.product_id = auto_discover_product(ctx)
+    areas = applicable_areas(ctx)
+    return ctx, ctype, areas
+
+def applicable_musts(ctx, areas):
+    """Testable MUSTs from the merchant's spec-version register, restricted to areas
+    the server implements (unsupported extensions are excluded from the denominator)."""
+    ids = set()
+    vdir = REQ_DIR / (ctx.version or "")
+    if not vdir.is_dir():
+        return ids
+    for f in glob.glob(str(vdir / "*.json")):
+        area = json.load(open(f)).get("_area", "?")
+        if areas.get(area, True) is False:
+            continue
+        for r in json.load(open(f)).get("rows", []):
+            if r["keyword"] in ("MUST", "MUST NOT") and r["testability"] == "testable" \
+               and any(t in ("rest", "any") for t in r.get("transport", [])):
+                ids.add(r["id"])
+    return ids
+
+SCOPE = {"tool": "spck.dev merchant conformance (dev)",
+         "methodology": "discovery-driven, capability-adaptive, kill-rate-gated"}
+DISCLAIMER = ("Unofficial. Not affiliated with or endorsed by the UCP project. A pass "
+             "reflects only the checks run against this server; not certified compliance.")
+
+def run_conformance(ctx, areas):
+    results, detail = merchant_checks.run_merchant_checks(ctx)
+    stamp = {**SCOPE, "spec_version": ctx.version, "server": ctx.base}
+    rep = aggregate(results, applicable_musts(ctx, areas), stamp, DISCLAIMER)
+    return rep, detail
+
+# Synthetic (non-register) check ids get a plain-language description so their reports
+# are still actionable (e.g. the holistic profile-schema validation).
+SYNTHETIC_REQS = {
+    "DISC-000": {"keyword": "MUST", "source": "ucp:source/schemas/ucp.json",
+                 "requirement": "The /.well-known/ucp profile document MUST validate against "
+                                "the official ucp.json profile schema (structure of version, "
+                                "services array, and reverse-domain-keyed capabilities object)."},
+}
+
+def scaffold_config(ctx):
+    """Build a starter --config for THIS server: detected product + FILL_ME placeholders
+    for the data-dependent inputs each declared capability needs. Friendly onboarding."""
+    caps = ctx.capabilities
+    def pay(desc):
+        return {"payment": {"instruments": [{"id": "instr_1", "handler_id": "FILL_ME: handler id",
+            "type": "card", "display": {"brand": "Visa", "last_digits": "1234"},
+            "credential": {"type": "token", "token": desc},
+            "billing_address": {"street_address": "1 Main St", "address_locality": "Town",
+                "address_region": "CA", "address_country": "US", "postal_code": "12345"}}]},
+            "risk_signals": {}}
+    cfg = {"product_id": ctx.product_id or "FILL_ME: an in-stock product id",
+           "currency": "USD"}
+    if "dev.ucp.shopping.checkout" in caps:
+        cfg["out_of_stock_id"] = "FILL_ME: a product id known to be out of stock"
+    if "dev.ucp.shopping.order" in caps:
+        cfg["fulfillment_option_id"] = "FILL_ME: a valid fulfillment option id"
+        cfg["complete_payment"] = pay("FILL_ME: a payment token that SUCCEEDS")
+        cfg["fail_payment"] = pay("FILL_ME: a payment token that FAILS (expect 402)")
+    if "dev.ucp.shopping.discount" in caps:
+        cfg["discount"] = {"valid_code": "FILL_ME: a real discount code",
+                           "second_valid_code": "FILL_ME: another real code",
+                           "invalid_code": "NOT_A_REAL_CODE"}
+    if "dev.ucp.shopping.catalog.lookup" in caps:
+        cfg["catalog"] = {"variant_id": ctx.product_id or "FILL_ME: a variant id"}
+    return cfg
+
+def req_meta(version):
+    """req_id -> {requirement, source} from the register, so every result cites its
+    normative clause (the trust story: each check traces to a verbatim spec quote)."""
+    meta = dict(SYNTHETIC_REQS)
+    vdir = REQ_DIR / (version or "")
+    if vdir.is_dir():
+        for f in glob.glob(str(vdir / "*.json")):
+            for r in json.load(open(f)).get("rows", []):
+                meta[r["id"]] = {"requirement": r.get("requirement", ""),
+                                 "source": r.get("source", ""), "keyword": r.get("keyword", "")}
+    return meta
+
+def _citations(req_ids, meta):
+    return [{"id": rid, **meta.get(rid, {"requirement": "", "source": ""})} for rid in req_ids]
+
+def _xml_escape(s):
+    return (str(s).replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+            .replace('"', "&quot;"))
+
+def junit_xml(ctx, detail, meta):
+    """Render results as JUnit XML so any CI can consume the report as a test run.
+    deviation -> <failure>; not-applicable/not-tested -> <skipped>; clean -> pass."""
+    cases, n_fail, n_skip = [], 0, 0
+    for c, d in detail:
+        st = str(d["status"])
+        cites = "; ".join(f"{x['id']}: {x['requirement']} [{x['source']}]"
+                          for x in _citations(c.req_ids, meta))
+        name = f"{c.id} ({', '.join(c.req_ids)})"
+        body = ""
+        if st == "deviation":
+            n_fail += 1
+            obs = d.get("observed") or {}
+            evidence = (f"expected: {cites}\nobserved: HTTP {obs.get('status')} "
+                        f"body: {obs.get('body')}")
+            body = (f'\n      <failure message="MUST violated: {_xml_escape(c.req_ids)}">'
+                    f'{_xml_escape(evidence)}</failure>\n    ')
+        elif st.startswith(("not-applicable", "not-tested")):
+            n_skip += 1
+            body = f'\n      <skipped message="{_xml_escape(st)}"/>\n    '
+        cases.append(f'    <testcase classname="ucp.{_xml_escape(ctx.version)}" '
+                     f'name="{_xml_escape(name)}">{body}</testcase>')
+    suite = (f'  <testsuite name="ucp-merchant-conformance" tests="{len(detail)}" '
+             f'failures="{n_fail}" skipped="{n_skip}" '
+             f'hostname="{_xml_escape(ctx.base)}">\n' + "\n".join(cases) + "\n  </testsuite>")
+    return '<?xml version="1.0" encoding="UTF-8"?>\n<testsuites>\n' + suite + "\n</testsuites>\n"
+
+def main():
+    ap = argparse.ArgumentParser(description="Merchant-agnostic UCP conformance (unofficial).")
+    ap.add_argument("--server", required=True)
+    ap.add_argument("--config", help="optional merchant config JSON (product_id, out_of_stock_id, fail_token, discount_codes, ...)")
+    ap.add_argument("--json", action="store_true", help="emit the report as JSON")
+    ap.add_argument("--junit", metavar="FILE", help="write a JUnit XML report to FILE (for CI)")
+    ap.add_argument("--init", nargs="?", const="merchant.json", metavar="FILE",
+                    help="probe the server and scaffold a starter --config to FILE, then exit")
+    ap.add_argument("--insecure", action="store_true",
+                    help="skip TLS certificate verification (testing only)")
+    args = ap.parse_args()
+    if args.insecure:
+        import engine; engine.set_insecure(True)
+    config = json.loads(pathlib.Path(args.config).read_text()) if args.config else {}
+    ctx, ctype, areas = report(args.server, config)
+    if args.init:
+        cfg = scaffold_config(ctx)
+        pathlib.Path(args.init).write_text(json.dumps(cfg, indent=2) + "\n")
+        fills = sum(1 for v in json.dumps(cfg).split('"') if v.startswith("FILL_ME"))
+        print(f"Wrote {args.init} for {ctx.base} (spec {ctx.version}).")
+        print(f"  detected capabilities: {', '.join(sorted(ctx.capabilities)) or '(none)'}")
+        print(f"  product for lifecycle: {ctx.product_id or '(none auto-discovered)'}")
+        print(f"\nNext: replace the {fills} FILL_ME placeholder(s) with real values, then run:")
+        print(f"  spck-conformance --server {ctx.base} --config {args.init}")
+        return 0
+    meta = req_meta(ctx.version)
+    supported = sorted(c for c in ctx.capabilities)
+    out = {
+        "server": ctx.base, "spec_version": ctx.version,
+        "content_type_json": "application/json" in ctype.lower(),
+        "capabilities": supported,
+        "shopping_endpoint": ctx.shopping_endpoint,
+        "product_for_lifecycle": ctx.product_id,
+        "applicable_areas": {a: v for a, v in areas.items()},
+    }
+    rep, detail = run_conformance(ctx, areas)
+    cc = rep.counts
+    out["verdict"] = {"aggregate": rep.aggregate, "coverage": rep.coverage,
+                      "applicable_musts": cc["inscope_musts"], "musts_passed": cc["musts_clean_pass"],
+                      "deviations": cc["deviations"]}
+    out["checks"] = [{"id": c.id, "req_ids": c.req_ids, "capability": c.capability,
+                      "status": d["status"], "kill_safe": d["kill_safe"],
+                      "requirements": _citations(c.req_ids, meta),
+                      # actionable evidence: what the server actually returned
+                      "observed": d.get("observed")} for c, d in detail]
+    out["disclaimer"] = DISCLAIMER
+    # exit code for CI: 2 if any MUST deviation, else 0 (partial coverage is not a failure)
+    rc = 2 if cc["deviations"] else 0
+    if args.junit:
+        pathlib.Path(args.junit).write_text(junit_xml(ctx, detail, meta))
+    if args.json:
+        print(json.dumps(out, indent=2)); return rc
+    # ---- grouped, scannable report ------------------------------------------
+    passed  = [(c, d) for c, d in detail if d["status"] == "clean-pass"]
+    devs    = [(c, d) for c, d in detail if d["status"] == "deviation"]
+    nottest = [(c, d) for c, d in detail if str(d["status"]).startswith("not-tested")]
+    napp    = [(c, d) for c, d in detail if str(d["status"]).startswith("not-applicable")]
+    other   = [(c, d) for c, d in detail if (c, d) not in passed + devs + nottest + napp]
+
+    print(f"═══ UCP conformance report (unofficial) — {ctx.base} ═══")
+    print(f"  spec {ctx.version} · endpoint {ctx.shopping_endpoint}")
+    print(f"  capabilities: {', '.join(supported) or '(none declared)'}")
+    print(f"  product for lifecycle: {ctx.product_id or '(none)'}\n")
+    print(f"  VERDICT: {rep.aggregate.upper()} — "
+          f"{cc['musts_clean_pass']}/{cc['inscope_musts']} applicable MUSTs "
+          f"({round(100*rep.coverage)}%), {cc['deviations']} deviation(s)")
+    print(f"  [{len(passed)} passed · {len(devs)} deviations · {len(nottest)} not-tested "
+          f"· {len(napp)} not-applicable]")
+
+    if devs:
+        print(f"\n  ✗ DEVIATIONS ({len(devs)}) — a MUST was violated:")
+        for c, d in devs:
+            print(f"    {c.id}")
+            for x in _citations(c.req_ids, meta):
+                print(f"        expected  {x['id']}: {x['requirement']}")
+                print(f"        spec      {x['source']}")
+            obs = d.get("observed") or {}
+            print(f"        observed  HTTP {obs.get('status')}  body: {obs.get('body')}")
+    if passed:
+        print(f"\n  ✓ PASSED ({len(passed)}) — satisfied & kill-safe:")
+        for c, _ in passed:
+            print(f"        {c.id}")
+    if nottest:
+        print(f"\n  ⊘ NOT TESTED ({len(nottest)}) — need config/data (not a failure):")
+        for c, d in nottest:
+            reason = str(d["status"]).replace("not-tested", "").strip("() ")
+            print(f"        {c.id:30} {reason or 'needs data'}")
+    if napp:
+        print(f"\n  — NOT APPLICABLE ({len(napp)}) — capability/transport not declared:")
+        print(f"        {', '.join(c.id for c, _ in napp)}")
+    if other:
+        print(f"\n  ? INCONCLUSIVE ({len(other)}):")
+        for c, d in other:
+            print(f"        {c.id:30} {d['status']}")
+    if args.junit:
+        print(f"\n  JUnit report written to {args.junit}")
+
+    # ---- friendly next steps -------------------------------------------------
+    n_pass = sum(1 for _, d in detail if d["status"] == "clean-pass")
+    n_dev = cc["deviations"]
+    needed = set()
+    for c, d in detail:
+        st = str(d["status"])
+        if st.startswith("not-tested (needs config"):
+            needed.update(st.split("needs config:")[1].rstrip(")").strip().split(","))
+    print("\n  Next steps:")
+    if n_dev:
+        print(f"    • Fix {n_dev} MUST deviation(s) above — each shows expected vs the observed response.")
+    if needed:
+        keys = ", ".join(sorted(k.strip() for k in needed if k.strip()))
+        hint = "--init to scaffold one" if not args.config else f"add: {keys}"
+        print(f"    • Unlock more checks by supplying config ({hint}).")
+    if ctx.product_id is None and "dev.ucp.shopping.checkout" in ctx.capabilities:
+        print(f"    • Set config.product_id to a real in-stock product to run the lifecycle checks.")
+    if not n_dev and not needed:
+        print(f"    • Looking good — {n_pass} checks clean-pass, 0 deviations for the checks run.")
+    if not args.config:
+        print(f"    • Tip: `spck-conformance --server {ctx.base} --init` scaffolds a config for this server.")
+    print(f"\n  {DISCLAIMER}")
+    return rc
+
+if __name__ == "__main__":
+    sys.exit(main())