openapi-agent-ready 0.3.0__tar.gz → 0.4.1__tar.gz

{openapi_agent_ready-0.3.0 → openapi_agent_ready-0.4.1}/CHANGELOG.md

@@ -5,6 +5,31 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-24
+
+### Fixed
+- **Swagger 2.0 specs are now rejected (exit 2)** instead of being audited.
+  They have `paths`, so they were scored, but auth lives in
+  `securityDefinitions`, so a spec with scoped OAuth2 was reported as having no
+  security schemes at all.
+- **Progress bar counts operations, not paths.** A spec with 100 paths × 3
+  methods (300 operations) previously never showed progress.
+
+## [0.4.0] - 2026-08-08
+
+### Added
+- **Baseline mode** (`--write-baseline`, `--baseline`, `--max-new`). A mature
+  API audited for the first time produces hundreds of findings, so a score gate
+  is unusable on day one and gets switched off. Recording the current state lets
+  CI block only regressions while the backlog stays visible.
+
+  Findings are matched on category, endpoint, and severity rather than message
+  text — messages embed counts and parameter names ("3/3 parameters have no
+  description (a, b, c)") that shift when unrelated things change, which would
+  report unfixed problems as new. Severity is part of the identity so a warning
+  escalating to a fail is caught; message is excluded so rewording a finding in
+  a future release doesn't invalidate stored baselines.
+
 ## [0.3.0] - 2026-07-31
 
 ### Added

{openapi_agent_ready-0.3.0 → openapi_agent_ready-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openapi-agent-ready
-Version: 0.3.0
+Version: 0.4.1
 Summary: Audit any OpenAPI spec for AI-agent and MCP readiness, and generate an MCP server scaffold.
 Project-URL: Homepage, https://github.com/sfaisal/agent-ready
 Project-URL: Issues, https://github.com/sfaisal/agent-ready/issues
@@ -64,7 +64,7 @@ Description-Content-Type: text/markdown
 **Audit any OpenAPI spec for AI-agent readiness — then generate an MCP server scaffold for the endpoints that pass.**
 
 Your API works fine for human developers. That doesn't mean an AI agent can use
-it reliably. `agent-ready` scores a spec against seven categories of
+it reliably. `agent-ready` scores a spec against eight categories of
 agent-specific failure, tells you exactly which endpoints will cause trouble and
 why, and can gate a CI pipeline so specs don't regress.
 
@@ -75,17 +75,18 @@ agent-ready https://example.com/openapi.yaml
 
 ```
 Generic Booking Platform API (v1.0)
-AI-readiness score: 54.4/100
-Endpoints: 4  Fails: 6  Warnings: 12
+AI-readiness score: 58.4/100
+Endpoints: 4  Fails: 7  Warnings: 14
 
 Category scores:
-  Description Clarity            37.5/100
-  Side Effects                   70.0/100
-  Error Responses                62.5/100
-  Auth Clarity                   50.0/100
-  Ambiguity                     100.0/100
-  Parameter Explanation          16.7/100
-  Usage Guidelines               50.0/100
+  Description Clarity           37.5/100
+  Side Effects                  70.0/100
+  Error Responses               62.5/100
+  Auth Clarity                  50.0/100
+  Ambiguity                    100.0/100
+  Parameter Explanation         10.0/100
+  Usage Guidelines              50.0/100
+  Tool Surface                 100.0/100
 ```
 
 ## Why this exists
@@ -111,11 +112,8 @@ directly onto the rubric:
 | **Frictionless authentication** | 4 (auth/scope clarity) |
 | **Structured error handling** | 3 (actionable errors) |
 
-Categories 2 (side effects) and 5 (ambiguity) have no counterpart in the
-article — they were added during implementation, once it became clear that
-unsignalled write operations and confusable endpoint descriptions cause agent
-failures as often as the original three. Category 8 came later still, from
-OpenAI's function-calling guidance.
+Categories 2 (side effects) and 5 (ambiguity) weren't in the article. They came
+up once I started building, and they matter as much as the original three.
 
 The gap is measurable, and enormous. A 2026 study of 856 tools across 103 MCP
 servers found that **97.1% of tool descriptions contained at least one quality
@@ -185,9 +183,55 @@ Exit codes:
 | Code | Meaning |
 |---|---|
 | `0` | All configured gates passed |
-| `1` | A gate failed (`--min-score` / `--max-fails`) |
+| `1` | A gate failed (`--min-score` / `--max-fails` / `--max-new`) |
 | `2` | The spec could not be loaded or parsed |
 
+### Adopting on an existing API
+
+A mature API audited for the first time will produce hundreds of findings. No
+team can fix all of them before merging anything, so a score gate is unusable
+on day one and gets switched off within a week.
+
+Record the current state instead, and block only what gets worse:
+
+```bash
+# once, when you adopt the tool — commit this file
+agent-ready openapi.yaml --write-baseline .agent-ready-baseline.json
+
+# in CI, from then on
+agent-ready openapi.yaml --baseline .agent-ready-baseline.json --max-new 0
+```
+
+Existing findings stay visible in the report but don't fail the build. A pull
+request that introduces a new one does, and the output names exactly which
+findings it added:
+
+```
+Compared against .agent-ready-baseline.json: 5 new, 0 fixed, 11 unchanged
+  NEW FAIL  GET /invoices — Description is a bare label (12 chars) ...
+  NEW FAIL  GET /invoices — No error responses documented ...
+```
+
+Findings are matched on category, endpoint, and severity — not on message text,
+which contains counts and parameter names that shift when unrelated things
+change. A warning escalating to a fail counts as new; rewording a finding in a
+future release does not invalidate your baseline.
+
+As the team fixes the backlog, regenerate the baseline to lock in the progress.
+
+### Python API
+
+```python
+from agent_ready import load_spec, run_audit
+
+spec = load_spec("openapi.yaml")
+result = run_audit(spec)
+
+print(result["overall_score"])
+for finding in result["gaps"]:
+    print(finding.severity, finding.endpoint, finding.message)
+```
+
 ## Real-world results
 
 Running it against Stripe's production spec (587 endpoints), as of v0.1.0.
@@ -213,8 +257,8 @@ Two things worth drawing out.
 in this tool, not in Stripe.** Stripe documents errors via OpenAPI's `default`
 response rather than enumerating explicit 4xx/5xx codes. Perfectly valid, and
 arguably cleaner. The check only looked for `4`/`5` prefixes, so it failed all
-587 endpoints. Fixed, regression-tested, and the reason the README says to run
-this against a real spec before trusting it.
+587 endpoints. Fixed and regression-tested — and a good reason to run this
+against your own real spec before trusting the score.
 
 **Stripe is widely and correctly regarded as agent-ready, yet its raw OpenAPI
 spec scores 62.9.** That isn't a contradiction — it's the whole point. Stripe's
@@ -229,19 +273,6 @@ Genuine findings that survived scrutiny: `GET /v1/account` and
 uses bearer/basic API keys rather than scoped OAuth2, so there's no way to
 express "this agent may only read."
 
-### Python API
-
-```python
-from agent_ready import load_spec, run_audit
-
-spec = load_spec("openapi.yaml")
-result = run_audit(spec)
-
-print(result["overall_score"])
-for finding in result["gaps"]:
-    print(finding.severity, finding.endpoint, finding.message)
-```
-
 ## The eight categories
 
 | # | Category | What it catches | Published anchor |
@@ -305,7 +336,7 @@ doesn't:
 
 - **The ambiguity check uses string similarity**, so it misses endpoints that
   are semantically similar but differently worded. Embedding-based similarity
-  would be stronger. ([#1](https://github.com/sfaisal/agent-ready/issues))
+  would be stronger. ([#1](https://github.com/sfaisal/agent-ready/issues/1))
 - **Category weights are judgement calls, not measured effect sizes.**
   Description clarity is weighted highest on the prior that wrong tool selection
   is the costliest failure — that prior is untested here.
@@ -328,7 +359,7 @@ doesn't:
 - [ ] LLM-assisted rewriting of flagged descriptions (`--fix`)
 - [ ] Live tool-selection testing against a generated MCP server
 - [ ] GitHub Action wrapper
-- [ ] Baseline mode (`--baseline`) so CI only fails on *new* regressions
+- [x] Baseline mode (`--baseline`) so CI only fails on *new* regressions
 
 ## Contributing
 

{openapi_agent_ready-0.3.0 → openapi_agent_ready-0.4.1}/README.md

@@ -9,7 +9,7 @@
 **Audit any OpenAPI spec for AI-agent readiness — then generate an MCP server scaffold for the endpoints that pass.**
 
 Your API works fine for human developers. That doesn't mean an AI agent can use
-it reliably. `agent-ready` scores a spec against seven categories of
+it reliably. `agent-ready` scores a spec against eight categories of
 agent-specific failure, tells you exactly which endpoints will cause trouble and
 why, and can gate a CI pipeline so specs don't regress.
 
@@ -20,17 +20,18 @@ agent-ready https://example.com/openapi.yaml
 
 ```
 Generic Booking Platform API (v1.0)
-AI-readiness score: 54.4/100
-Endpoints: 4  Fails: 6  Warnings: 12
+AI-readiness score: 58.4/100
+Endpoints: 4  Fails: 7  Warnings: 14
 
 Category scores:
-  Description Clarity            37.5/100
-  Side Effects                   70.0/100
-  Error Responses                62.5/100
-  Auth Clarity                   50.0/100
-  Ambiguity                     100.0/100
-  Parameter Explanation          16.7/100
-  Usage Guidelines               50.0/100
+  Description Clarity           37.5/100
+  Side Effects                  70.0/100
+  Error Responses               62.5/100
+  Auth Clarity                  50.0/100
+  Ambiguity                    100.0/100
+  Parameter Explanation         10.0/100
+  Usage Guidelines              50.0/100
+  Tool Surface                 100.0/100
 ```
 
 ## Why this exists
@@ -56,11 +57,8 @@ directly onto the rubric:
 | **Frictionless authentication** | 4 (auth/scope clarity) |
 | **Structured error handling** | 3 (actionable errors) |
 
-Categories 2 (side effects) and 5 (ambiguity) have no counterpart in the
-article — they were added during implementation, once it became clear that
-unsignalled write operations and confusable endpoint descriptions cause agent
-failures as often as the original three. Category 8 came later still, from
-OpenAI's function-calling guidance.
+Categories 2 (side effects) and 5 (ambiguity) weren't in the article. They came
+up once I started building, and they matter as much as the original three.
 
 The gap is measurable, and enormous. A 2026 study of 856 tools across 103 MCP
 servers found that **97.1% of tool descriptions contained at least one quality
@@ -130,9 +128,55 @@ Exit codes:
 | Code | Meaning |
 |---|---|
 | `0` | All configured gates passed |
-| `1` | A gate failed (`--min-score` / `--max-fails`) |
+| `1` | A gate failed (`--min-score` / `--max-fails` / `--max-new`) |
 | `2` | The spec could not be loaded or parsed |
 
+### Adopting on an existing API
+
+A mature API audited for the first time will produce hundreds of findings. No
+team can fix all of them before merging anything, so a score gate is unusable
+on day one and gets switched off within a week.
+
+Record the current state instead, and block only what gets worse:
+
+```bash
+# once, when you adopt the tool — commit this file
+agent-ready openapi.yaml --write-baseline .agent-ready-baseline.json
+
+# in CI, from then on
+agent-ready openapi.yaml --baseline .agent-ready-baseline.json --max-new 0
+```
+
+Existing findings stay visible in the report but don't fail the build. A pull
+request that introduces a new one does, and the output names exactly which
+findings it added:
+
+```
+Compared against .agent-ready-baseline.json: 5 new, 0 fixed, 11 unchanged
+  NEW FAIL  GET /invoices — Description is a bare label (12 chars) ...
+  NEW FAIL  GET /invoices — No error responses documented ...
+```
+
+Findings are matched on category, endpoint, and severity — not on message text,
+which contains counts and parameter names that shift when unrelated things
+change. A warning escalating to a fail counts as new; rewording a finding in a
+future release does not invalidate your baseline.
+
+As the team fixes the backlog, regenerate the baseline to lock in the progress.
+
+### Python API
+
+```python
+from agent_ready import load_spec, run_audit
+
+spec = load_spec("openapi.yaml")
+result = run_audit(spec)
+
+print(result["overall_score"])
+for finding in result["gaps"]:
+    print(finding.severity, finding.endpoint, finding.message)
+```
+
 ## Real-world results
 
 Running it against Stripe's production spec (587 endpoints), as of v0.1.0.
@@ -158,8 +202,8 @@ Two things worth drawing out.
 in this tool, not in Stripe.** Stripe documents errors via OpenAPI's `default`
 response rather than enumerating explicit 4xx/5xx codes. Perfectly valid, and
 arguably cleaner. The check only looked for `4`/`5` prefixes, so it failed all
-587 endpoints. Fixed, regression-tested, and the reason the README says to run
-this against a real spec before trusting it.
+587 endpoints. Fixed and regression-tested — and a good reason to run this
+against your own real spec before trusting the score.
 
 **Stripe is widely and correctly regarded as agent-ready, yet its raw OpenAPI
 spec scores 62.9.** That isn't a contradiction — it's the whole point. Stripe's
@@ -174,19 +218,6 @@ Genuine findings that survived scrutiny: `GET /v1/account` and
 uses bearer/basic API keys rather than scoped OAuth2, so there's no way to
 express "this agent may only read."
 
-### Python API
-
-```python
-from agent_ready import load_spec, run_audit
-
-spec = load_spec("openapi.yaml")
-result = run_audit(spec)
-
-print(result["overall_score"])
-for finding in result["gaps"]:
-    print(finding.severity, finding.endpoint, finding.message)
-```
-
 ## The eight categories
 
 | # | Category | What it catches | Published anchor |
@@ -250,7 +281,7 @@ doesn't:
 
 - **The ambiguity check uses string similarity**, so it misses endpoints that
   are semantically similar but differently worded. Embedding-based similarity
-  would be stronger. ([#1](https://github.com/sfaisal/agent-ready/issues))
+  would be stronger. ([#1](https://github.com/sfaisal/agent-ready/issues/1))
 - **Category weights are judgement calls, not measured effect sizes.**
   Description clarity is weighted highest on the prior that wrong tool selection
   is the costliest failure — that prior is untested here.
@@ -273,7 +304,7 @@ doesn't:
 - [ ] LLM-assisted rewriting of flagged descriptions (`--fix`)
 - [ ] Live tool-selection testing against a generated MCP server
 - [ ] GitHub Action wrapper
-- [ ] Baseline mode (`--baseline`) so CI only fails on *new* regressions
+- [x] Baseline mode (`--baseline`) so CI only fails on *new* regressions
 
 ## Contributing
 

{openapi_agent_ready-0.3.0 → openapi_agent_ready-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openapi-agent-ready"
-version = "0.3.0"
+version = "0.4.1"
 description = "Audit any OpenAPI spec for AI-agent and MCP readiness, and generate an MCP server scaffold."
 readme = "README.md"
 requires-python = ">=3.10"

openapi_agent_ready-0.4.1/src/agent_ready/baseline.py

@@ -0,0 +1,137 @@
+"""
+Baseline support: fail CI only on *new* findings.
+
+The problem this solves: a mature API audited for the first time produces
+hundreds of findings. A team cannot fix them all before merging anything, so
+`--min-score` and `--max-fails` are unusable as gates and get switched off
+within a week. A baseline records the current state and lets the gate fail only
+when something gets worse.
+
+The whole design rests on one question: what makes a finding "the same finding"
+across two runs? Message text is the obvious answer and the wrong one — it
+embeds counts and parameter names ("3/3 parameters have no description
+(date_from, date_to, location)") that change when an unrelated parameter is
+added, which would report a fixed finding as new.
+
+So findings are fingerprinted on (category, endpoint, severity) instead:
+
+- **category** — which rule fired.
+- **endpoint** — where. Stable across edits to the endpoint's content.
+- **severity** — a warning becoming a fail is a regression worth catching, so
+  it belongs in the identity rather than being treated as the same finding.
+
+Message is deliberately excluded. Rewording a finding's text in a future
+release must not invalidate every stored baseline.
+"""
+
+import json
+from collections import Counter
+from dataclasses import asdict
+from pathlib import Path
+
+BASELINE_VERSION = 1
+
+
+class BaselineError(Exception):
+    """Raised when a baseline file can't be read or is malformed."""
+
+
+def fingerprint(finding) -> str:
+    """A stable identity for a finding across runs. See module docstring."""
+    return f"{finding.category}|{finding.endpoint}|{finding.severity}"
+
+
+def _counted(findings) -> Counter:
+    """
+    Fingerprints with multiplicity.
+
+    A single endpoint can legitimately produce two findings in one category —
+    for example a parameter-explanation fail for undocumented parameters plus a
+    warning for a missing date format. Counting rather than set-membership means
+    going from one such finding to two is correctly reported as new.
+    """
+    return Counter(fingerprint(f) for f in findings)
+
+
+def write_baseline(path: str, spec: dict, result: dict) -> dict:
+    """Record the current findings so future runs can compare against them."""
+    info = spec.get("info") or {}
+    payload = {
+        "baseline_version": BASELINE_VERSION,
+        "api": {
+            "title": info.get("title", "Untitled API"),
+            "version": str(info.get("version", "unknown")),
+        },
+        "overall_score": result["overall_score"],
+        "endpoint_count": result["endpoint_count"],
+        "fingerprints": sorted(_counted(result["gaps"]).elements()),
+        # Stored for human readability when reviewing a baseline diff; never
+        # read back during comparison.
+        "findings": [asdict(f) for f in result["gaps"]],
+    }
+    Path(path).write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return payload
+
+
+def load_baseline(path: str) -> dict:
+    p = Path(path)
+    if not p.exists():
+        raise BaselineError(
+            f"Baseline file not found: {path}\n"
+            f"Create one from the current state with: --write-baseline {path}"
+        )
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise BaselineError(f"Baseline file is not valid JSON: {exc}") from exc
+
+    if not isinstance(data, dict) or "fingerprints" not in data:
+        raise BaselineError(
+            f"{path} does not look like an agent-ready baseline "
+            "(no 'fingerprints' key)."
+        )
+
+    version = data.get("baseline_version", 0)
+    if version > BASELINE_VERSION:
+        raise BaselineError(
+            f"Baseline was written by a newer version of agent-ready "
+            f"(format v{version}, this build understands v{BASELINE_VERSION}). "
+            "Upgrade agent-ready or regenerate the baseline."
+        )
+    return data
+
+
+def compare_to_baseline(result: dict, baseline: dict) -> dict:
+    """
+    Classify current findings against a baseline.
+
+    Returns counts plus the actual new findings, so the CLI can show a team
+    exactly what their change introduced rather than the whole backlog.
+    """
+    baseline_counts = Counter(baseline.get("fingerprints", []))
+    current_counts = _counted(result["gaps"])
+
+    # A fingerprint appearing more often than the baseline recorded is new,
+    # by the excess amount.
+    new_counts = current_counts - baseline_counts
+    fixed_counts = baseline_counts - current_counts
+
+    # Map fingerprints back to findings so the report can name them. Consume
+    # the allowance so duplicates beyond it are still reported.
+    remaining = Counter(new_counts)
+    new_findings = []
+    for f in result["gaps"]:
+        fp = fingerprint(f)
+        if remaining.get(fp, 0) > 0:
+            new_findings.append(f)
+            remaining[fp] -= 1
+
+    return {
+        "new_findings": new_findings,
+        "new_count": sum(new_counts.values()),
+        "fixed_count": sum(fixed_counts.values()),
+        "unchanged_count": sum((current_counts & baseline_counts).values()),
+        "new_fails": sum(1 for f in new_findings if f.severity == "fail"),
+        "baseline_score": baseline.get("overall_score"),
+        "current_score": result["overall_score"],
+    }

{openapi_agent_ready-0.3.0 → openapi_agent_ready-0.4.1}/src/agent_ready/cli.py

@@ -3,8 +3,8 @@ Command-line interface for agent-ready.
 
 Exit codes (designed for CI use):
     0  audit passed all configured gates
-    1  audit ran, but a gate failed (score below --min-score, or
-       --max-fails exceeded)
+    1  audit ran, but a gate failed (score below --min-score,
+       --max-fails exceeded, or --max-new exceeded against --baseline)
     2  the spec could not be loaded or parsed
 """
 
@@ -17,10 +17,17 @@ from . import __version__
 from .auditor import (
     SpecLoadError,
     endpoints_ready_for_mcp,
+    extract_endpoints,
     load_spec,
     result_to_dict,
     run_audit,
 )
+from .baseline import (
+    BaselineError,
+    compare_to_baseline,
+    load_baseline,
+    write_baseline,
+)
 from .mcp_generator import generate_mcp_scaffold
 from .report_generator import generate_report
 
@@ -38,7 +45,12 @@ def build_parser() -> argparse.ArgumentParser:
         ),
         epilog=(
             "CI example:\n"
-            "  agent-ready openapi.yaml --min-score 70 --max-fails 0 --quiet\n"
+            "  agent-ready openapi.yaml --min-score 60 --max-fails 0 --quiet\n"
+            "\n"
+            "Adopting on an existing API, where fixing everything first is not\n"
+            "realistic — record today's findings, then block only regressions:\n"
+            "  agent-ready openapi.yaml --write-baseline .agent-ready-baseline.json\n"
+            "  agent-ready openapi.yaml --baseline .agent-ready-baseline.json --max-new 0\n"
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
@@ -60,6 +72,31 @@ def build_parser() -> argparse.ArgumentParser:
         type=int,
         help="Exit 1 if the number of FAIL findings exceeds this value (CI gate)",
     )
+    parser.add_argument(
+        "--write-baseline",
+        metavar="PATH",
+        help=(
+            "Record current findings to PATH as an accepted baseline. Run this "
+            "once when adopting the tool on an existing API."
+        ),
+    )
+    parser.add_argument(
+        "--baseline",
+        metavar="PATH",
+        help=(
+            "Compare against a baseline file and report what changed. Combine "
+            "with --max-new to fail only on regressions."
+        ),
+    )
+    parser.add_argument(
+        "--max-new",
+        type=int,
+        metavar="N",
+        help=(
+            "Exit 1 if more than N findings are new since --baseline. "
+            "Use --max-new 0 to block any regression."
+        ),
+    )
     parser.add_argument(
         "--generate-mcp",
         metavar="PATH",
@@ -147,6 +184,16 @@ def _run(argv=None) -> int:
         print(f"error: {exc}", file=sys.stderr)
         return EXIT_SPEC_ERROR
 
+    # Swagger 2.0 has `paths` too, but keeps auth in `securityDefinitions` and
+    # bodies in `in: body` params, so auditing it yields confidently wrong scores.
+    if isinstance(spec, dict) and "swagger" in spec:
+        print(
+            f"error: Swagger {spec['swagger']} is not supported — only OpenAPI 3.x. "
+            "Convert it first (e.g. with swagger2openapi).",
+            file=sys.stderr,
+        )
+        return EXIT_SPEC_ERROR
+
     if not isinstance(spec, dict) or not spec.get("paths"):
         print(
             "error: no 'paths' found — this does not look like an OpenAPI spec.",
@@ -154,7 +201,8 @@ def _run(argv=None) -> int:
         )
         return EXIT_SPEC_ERROR
 
-    endpoint_count = len(spec.get("paths") or {})
+    # Operations, not paths — the audit (and the ambiguity check) is per operation.
+    endpoint_count = len(extract_endpoints(spec))
     result = run_audit(spec, progress=_make_progress(endpoint_count, args.quiet))
 
     if result["endpoint_count"] == 0:
@@ -185,6 +233,37 @@ def _run(argv=None) -> int:
                 f"({len(ready)}/{result['endpoint_count']} endpoints included)"
             )
 
+    # Baseline: write, or compare and gate on regressions only.
+    if args.write_baseline:
+        write_baseline(args.write_baseline, spec, result)
+        if not args.quiet:
+            print(
+                f"Baseline written to {args.write_baseline} "
+                f"({len(result['gaps'])} finding(s) recorded as accepted)"
+            )
+
+    comparison = None
+    if args.baseline:
+        try:
+            comparison = compare_to_baseline(result, load_baseline(args.baseline))
+        except BaselineError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return EXIT_SPEC_ERROR
+
+        if not args.quiet:
+            print()
+            print(
+                f"Compared against {args.baseline}: "
+                f"{comparison['new_count']} new, "
+                f"{comparison['fixed_count']} fixed, "
+                f"{comparison['unchanged_count']} unchanged"
+            )
+            for f in comparison["new_findings"][:20]:
+                marker = "FAIL" if f.severity == "fail" else "WARN"
+                print(f"  NEW {marker}  {f.endpoint} — {f.message}")
+            if len(comparison["new_findings"]) > 20:
+                print(f"  ... and {len(comparison['new_findings']) - 20} more")
+
     # CI gates
     gate_failed = False
     if args.min_score is not None and result["overall_score"] < args.min_score:
@@ -202,6 +281,18 @@ def _run(argv=None) -> int:
         )
         gate_failed = True
 
+    if (
+        comparison is not None
+        and args.max_new is not None
+        and comparison["new_count"] > args.max_new
+    ):
+        print(
+            f"GATE FAILED: {comparison['new_count']} new finding(s) since "
+            f"baseline exceeds maximum {args.max_new}",
+            file=sys.stderr,
+        )
+        gate_failed = True
+
     return EXIT_GATE_FAILED if gate_failed else EXIT_OK