From 81e83a2ad984f164eacc5adf3897eabecca15f22 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Wed, 11 Mar 2026 20:09:39 -0500
Subject: [PATCH 01/22] feat: add score command

---
 .changeset/add-score-command.md               |   5 +
 docs/@v2/commands/index.md                    |   5 +-
 docs/@v2/commands/score.md                    | 152 ++++++++
 .../score/__tests__/example-coverage.test.ts  | 183 ++++++++++
 .../score/__tests__/schema-walker.test.ts     | 334 ++++++++++++++++++
 .../commands/score/__tests__/scoring.test.ts  | 284 +++++++++++++++
 .../score/collectors/document-metrics.ts      | 261 ++++++++++++++
 .../score/collectors/schema-walker.ts         | 165 +++++++++
 .../score/collectors/workflow-graph.ts        |  71 ++++
 packages/cli/src/commands/score/constants.ts  |  57 +++
 .../cli/src/commands/score/formatters/json.ts |  60 ++++
 .../src/commands/score/formatters/stylish.ts  | 149 ++++++++
 packages/cli/src/commands/score/hotspots.ts   | 115 ++++++
 packages/cli/src/commands/score/index.ts      | 145 ++++++++
 packages/cli/src/commands/score/scoring.ts    | 199 +++++++++++
 packages/cli/src/commands/score/types.ts      | 140 ++++++++
 packages/cli/src/index.ts                     |  25 ++
 17 files changed, 2348 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/add-score-command.md
 create mode 100644 docs/@v2/commands/score.md
 create mode 100644 packages/cli/src/commands/score/__tests__/example-coverage.test.ts
 create mode 100644 packages/cli/src/commands/score/__tests__/schema-walker.test.ts
 create mode 100644 packages/cli/src/commands/score/__tests__/scoring.test.ts
 create mode 100644 packages/cli/src/commands/score/collectors/document-metrics.ts
 create mode 100644 packages/cli/src/commands/score/collectors/schema-walker.ts
 create mode 100644 packages/cli/src/commands/score/collectors/workflow-graph.ts
 create mode 100644 packages/cli/src/commands/score/constants.ts
 create mode 100644 packages/cli/src/commands/score/formatters/json.ts
 create mode 100644 packages/cli/src/commands/score/formatters/stylish.ts
 create mode 100644 packages/cli/src/commands/score/hotspots.ts
 create mode 100644 packages/cli/src/commands/score/index.ts
 create mode 100644 packages/cli/src/commands/score/scoring.ts
 create mode 100644 packages/cli/src/commands/score/types.ts

diff --git a/.changeset/add-score-command.md b/.changeset/add-score-command.md
new file mode 100644
index 0000000000..e118660343
--- /dev/null
+++ b/.changeset/add-score-command.md
@@ -0,0 +1,5 @@
+---
+'@redocly/cli': minor
+---
+
+Added new `score` command that analyzes OpenAPI 3.x descriptions and produces integration simplicity and agent readiness scores (0-100). Reports normalized subscores, raw per-operation metrics, and top hotspot operations with human-readable explanations. Supports `--format=stylish` (default) and `--format=json` output.
diff --git a/docs/@v2/commands/index.md b/docs/@v2/commands/index.md
index 8dafe429df..aad01badaf 100644
--- a/docs/@v2/commands/index.md
+++ b/docs/@v2/commands/index.md
@@ -13,10 +13,11 @@ Documentation commands:
 
 API management commands:
 
-- [`stats`](stats.md) Gather statistics for a document.
 - [`bundle`](bundle.md) Bundle API description.
-- [`split`](split.md) Split API description into a multi-file structure.
 - [`join`](join.md) Join API descriptions [experimental feature].
+- [`score`](score.md) Score an API for integration simplicity and agent readiness.
+- [`split`](split.md) Split API description into a multi-file structure.
+- [`stats`](stats.md) Gather statistics for a document.
 
 Linting commands:
 
diff --git a/docs/@v2/commands/score.md b/docs/@v2/commands/score.md
new file mode 100644
index 0000000000..cdea1bcb9b
--- /dev/null
+++ b/docs/@v2/commands/score.md
@@ -0,0 +1,152 @@
+# `score`
+
+## Introduction
+
+The `score` command analyzes an OpenAPI description and produces two composite scores:
+
+- **Integration Simplicity** (0–100): How easy is this API to integrate? Higher is better.
+- **Agent Readiness** (0–100): How usable is this API by AI agents and LLM-based tooling? Higher is better.
+
+In addition to the top-level scores, the command reports normalized subscores, raw metrics for every operation, and a list of **hotspot operations** — the endpoints most likely to cause integration friction — along with human-readable explanations.
+
+{% admonition type="warning" name="OpenAPI 3.x only" %}
+The `score` command supports OpenAPI 3.0, 3.1, and 3.2 descriptions. OpenAPI 2.0 (Swagger) and AsyncAPI are not currently supported.
+{% /admonition %}
+
+### Metrics
+
+The following raw metrics are collected per operation and aggregated across the document:
+
+| Metric                             | Description                                                                                                                          |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Parameter count                    | Total parameters (path, query, header, cookie) per operation.                                                                        |
+| Required parameter count           | How many of those parameters are required.                                                                                           |
+| Request body presence              | Whether the operation defines a request body.                                                                                        |
+| Top-level writable field count     | Number of non-`readOnly` top-level properties in request schemas.                                                                    |
+| Max request/response schema depth  | Deepest nesting level in request and response schemas.                                                                               |
+| Polymorphism count                 | Number of `oneOf`, `anyOf`, and `allOf` usages. `anyOf` is penalized more heavily.                                                   |
+| Property count                     | Total schema properties across request and response.                                                                                 |
+| Description coverage               | Fraction of operations, parameters, and schema properties that have descriptions.                                                    |
+| Ambiguous identifier count         | Parameters with generic names (e.g. `id`, `name`, `type`) and no description.                                                        |
+| Constraint coverage                | Count of constraining keywords (`enum`, `format`, `pattern`, `minimum`, `maximum`, `minLength`, `maxLength`, `discriminator`, etc.). |
+| Request/response example coverage  | Whether request and response media types include `example` or `examples`.                                                            |
+| Structured error response coverage | How many 4xx/5xx responses include a content schema or meaningful description.                                                       |
+| Workflow dependency depth          | Inferred from shared `$ref` usage across operations; deeper shared-schema graphs indicate more tightly coupled workflows.            |
+
+### Subscores
+
+Subscores are normalized to 0–1 and grouped into two categories:
+
+**Integration Simplicity subscores:** `parameterSimplicity`, `schemaSimplicity`, `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `workflowClarity`.
+
+**Agent Readiness subscores:** `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `identifierClarity`, `workflowClarity`, `polymorphismClarity`.
+
+### Hotspots
+
+The command identifies the operations with the lowest scores and provides reasons such as:
+
+- "High parameter count (N)"
+- "Deep schema nesting (depth M)"
+- "Polymorphism (anyOf) without discriminator"
+- "Missing request and response examples"
+- "No structured error responses (4xx/5xx)"
+- "Missing operation description"
+
+## Usage
+
+```bash
+redocly score <api>
+redocly score <api> [--format=<option>] [--config=<path>]
+```
+
+## Options
+
+| Option        | Type    | Description                                                                                                                                    |
+| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| api           | string  | **REQUIRED.** Path to the API description filename or alias that you want to score. Refer to [the API section](#specify-api) for more details. |
+| --config      | string  | Specify path to the [configuration file](#use-alternative-configuration-file).                                                                 |
+| --format      | string  | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`.                                                |
+| --help        | boolean | Show help.                                                                                                                                     |
+| --lint-config | string  | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`.             |
+| --version     | boolean | Show version number.                                                                                                                           |
+
+## Examples
+
+### Specify API
+
+#### Pass an API directly
+
+```bash
+redocly score openapi/openapi.yaml
+```
+
+#### Pass an API alias
+
+Instead of a full path, you can use an API name from the `apis` section of your Redocly configuration file.
+
+```yaml
+apis:
+  core@v1:
+    root: ./openapi/api-description.json
+```
+
+```bash
+redocly score core@v1
+```
+
+### Use alternative configuration file
+
+By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory.
+Use the optional `--config` argument to provide an alternative path to a configuration file.
+
+```bash
+redocly score --config=./another/directory/config.yaml
+```
+
+### Specify output format
+
+#### Stylish output (default)
+
+The default output format shows a human-readable summary in your terminal:
+
+<pre>
+  Scores
+
+  Integration Simplicity:  72.5/100
+  Agent Readiness:         68.3/100
+
+  Integration Simplicity Subscores
+
+  Parameter Simplicity     [████████████████░░░░] 80%
+  Schema Simplicity        [██████████████░░░░░░] 70%
+  Documentation Quality    [████████████░░░░░░░░] 60%
+  Constraint Clarity       [██████████░░░░░░░░░░] 50%
+  Example Coverage         [████████████████████] 100%
+  Error Clarity            [████████████████░░░░] 80%
+  Workflow Clarity         [██████████████████░░] 90%
+
+  Top 3 Hotspot Operations
+
+  POST /orders (createOrder)
+    Integration Simplicity: 45.2  Agent Readiness: 38.7
+    - High parameter count (12)
+    - Deep schema nesting (depth 6)
+    - Missing request and response examples
+
+  PUT /orders/{id} (updateOrder)
+    Integration Simplicity: 52.1  Agent Readiness: 44.0
+    - Polymorphism (anyOf) without discriminator (3 anyOf)
+    - No structured error responses (4xx/5xx)
+</pre>
+
+#### JSON output
+
+Use `--format=json` for machine-readable output:
+
+```bash
+redocly score openapi.yaml --format=json
+```
+
+The JSON output includes the full data: top-level scores, subscores, per-operation raw metrics, per-operation scores, workflow depths, and hotspot details with reasoning.
+
+The JSON format is suitable for CI pipelines, quality gates, or feeding results into dashboards.
diff --git a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
new file mode 100644
index 0000000000..18c9b3a71b
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
@@ -0,0 +1,183 @@
+import { collectDocumentMetrics } from '../collectors/document-metrics.js';
+import {
+  computeOperationIntegrationSubscores,
+  computeOperationAgentSubscores,
+  computeIntegrationSimplicity,
+  computeAgentReadiness,
+} from '../scoring.js';
+
+describe('example coverage', () => {
+  function makeDocument(overrides: {
+    requestExample?: boolean;
+    responseExample?: boolean;
+    hasRequestBody?: boolean;
+  }) {
+    const requestBody =
+      overrides.hasRequestBody !== false
+        ? {
+            content: {
+              'application/json': {
+                schema: { type: 'object', properties: { name: { type: 'string' } } },
+                ...(overrides.requestExample ? { example: { name: 'test' } } : {}),
+              },
+            },
+          }
+        : undefined;
+
+    return {
+      openapi: '3.0.0',
+      info: { title: 'Test', version: '1.0.0' },
+      paths: {
+        '/items': {
+          post: {
+            operationId: 'createItem',
+            description: 'Create an item',
+            ...(requestBody ? { requestBody } : {}),
+            responses: {
+              '200': {
+                description: 'Success',
+                content: {
+                  'application/json': {
+                    schema: { type: 'object', properties: { id: { type: 'string' } } },
+                    ...(overrides.responseExample ? { example: { id: '123' } } : {}),
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+
+  it('should give perfect example coverage when both request and response examples present', () => {
+    const doc = makeDocument({ requestExample: true, responseExample: true, hasRequestBody: true });
+    const metrics = collectDocumentMetrics(doc);
+    const opMetrics = metrics.operations.get('createItem')!;
+
+    expect(opMetrics.requestExamplePresent).toBe(true);
+    expect(opMetrics.responseExamplePresent).toBe(true);
+
+    const subscores = computeOperationIntegrationSubscores(opMetrics, 0);
+    expect(subscores.exampleCoverage).toBe(1);
+  });
+
+  it('should give half example coverage when only response example present', () => {
+    const doc = makeDocument({
+      requestExample: false,
+      responseExample: true,
+      hasRequestBody: true,
+    });
+    const metrics = collectDocumentMetrics(doc);
+    const opMetrics = metrics.operations.get('createItem')!;
+
+    expect(opMetrics.requestExamplePresent).toBe(false);
+    expect(opMetrics.responseExamplePresent).toBe(true);
+
+    const subscores = computeOperationIntegrationSubscores(opMetrics, 0);
+    expect(subscores.exampleCoverage).toBe(0.5);
+  });
+
+  it('should give zero example coverage when no examples', () => {
+    const doc = makeDocument({
+      requestExample: false,
+      responseExample: false,
+      hasRequestBody: true,
+    });
+    const metrics = collectDocumentMetrics(doc);
+    const opMetrics = metrics.operations.get('createItem')!;
+
+    const subscores = computeOperationIntegrationSubscores(opMetrics, 0);
+    expect(subscores.exampleCoverage).toBe(0);
+  });
+
+  it('should affect integration simplicity score positively with examples', () => {
+    const docWith = makeDocument({
+      requestExample: true,
+      responseExample: true,
+      hasRequestBody: true,
+    });
+    const docWithout = makeDocument({
+      requestExample: false,
+      responseExample: false,
+      hasRequestBody: true,
+    });
+
+    const metricsWithExamples = collectDocumentMetrics(docWith).operations.get('createItem')!;
+    const metricsWithout = collectDocumentMetrics(docWithout).operations.get('createItem')!;
+
+    const subWith = computeOperationIntegrationSubscores(metricsWithExamples, 0);
+    const subWithout = computeOperationIntegrationSubscores(metricsWithout, 0);
+
+    const scoreWith = computeIntegrationSimplicity(subWith);
+    const scoreWithout = computeIntegrationSimplicity(subWithout);
+
+    expect(scoreWith).toBeGreaterThan(scoreWithout);
+  });
+
+  it('should affect agent readiness score positively with examples', () => {
+    const docWith = makeDocument({
+      requestExample: true,
+      responseExample: true,
+      hasRequestBody: true,
+    });
+    const docWithout = makeDocument({
+      requestExample: false,
+      responseExample: false,
+      hasRequestBody: true,
+    });
+
+    const metricsWithExamples = collectDocumentMetrics(docWith).operations.get('createItem')!;
+    const metricsWithout = collectDocumentMetrics(docWithout).operations.get('createItem')!;
+
+    const subWith = computeOperationAgentSubscores(metricsWithExamples, 0);
+    const subWithout = computeOperationAgentSubscores(metricsWithout, 0);
+
+    const scoreWith = computeAgentReadiness(subWith);
+    const scoreWithout = computeAgentReadiness(subWithout);
+
+    expect(scoreWith).toBeGreaterThan(scoreWithout);
+  });
+
+  it('should handle examples via examples map', () => {
+    const doc = {
+      openapi: '3.0.0',
+      info: { title: 'Test', version: '1.0.0' },
+      paths: {
+        '/items': {
+          post: {
+            operationId: 'createItem',
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { type: 'object' },
+                  examples: {
+                    sample: { value: { name: 'test' } },
+                  },
+                },
+              },
+            },
+            responses: {
+              '200': {
+                description: 'OK',
+                content: {
+                  'application/json': {
+                    schema: { type: 'object' },
+                    examples: {
+                      result: { value: { id: '1' } },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const metrics = collectDocumentMetrics(doc);
+    const opMetrics = metrics.operations.get('createItem')!;
+    expect(opMetrics.requestExamplePresent).toBe(true);
+    expect(opMetrics.responseExamplePresent).toBe(true);
+  });
+});
diff --git a/packages/cli/src/commands/score/__tests__/schema-walker.test.ts b/packages/cli/src/commands/score/__tests__/schema-walker.test.ts
new file mode 100644
index 0000000000..b1dd96af81
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/schema-walker.test.ts
@@ -0,0 +1,334 @@
+import { walkSchema } from '../collectors/schema-walker.js';
+
+describe('schema-walker', () => {
+  describe('depth', () => {
+    it('should return depth 0 for a flat schema with no properties', () => {
+      const schema = { type: 'string' };
+      expect(walkSchema(schema).depth).toBe(0);
+    });
+
+    it('should return depth 0 for null/undefined', () => {
+      expect(walkSchema(null).depth).toBe(0);
+      expect(walkSchema(undefined).depth).toBe(0);
+    });
+
+    it('should return depth 1 for a single level of properties', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          age: { type: 'integer' },
+        },
+      };
+      expect(walkSchema(schema).depth).toBe(1);
+    });
+
+    it('should return depth 2 for nested objects', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          address: {
+            type: 'object',
+            properties: {
+              city: { type: 'string' },
+            },
+          },
+        },
+      };
+      expect(walkSchema(schema).depth).toBe(2);
+    });
+
+    it('should return depth 3 for deeply nested schemas', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          level1: {
+            type: 'object',
+            properties: {
+              level2: {
+                type: 'object',
+                properties: {
+                  level3: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+      };
+      expect(walkSchema(schema).depth).toBe(3);
+    });
+
+    it('should count array items as depth', () => {
+      const schema = {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+          },
+        },
+      };
+      expect(walkSchema(schema).depth).toBe(2);
+    });
+
+    it('should handle circular references gracefully', () => {
+      const schema: Record<string, any> = {
+        type: 'object',
+        properties: {},
+      };
+      schema.properties.self = schema;
+      const result = walkSchema(schema);
+      expect(result.depth).toBe(1);
+    });
+
+    it('should count additionalProperties depth', () => {
+      const schema = {
+        type: 'object',
+        additionalProperties: {
+          type: 'object',
+          properties: {
+            value: { type: 'string' },
+          },
+        },
+      };
+      expect(walkSchema(schema).depth).toBe(2);
+    });
+  });
+
+  describe('polymorphism counts', () => {
+    it('should count oneOf schemas', () => {
+      const schema = {
+        oneOf: [{ type: 'string' }, { type: 'integer' }, { type: 'boolean' }],
+      };
+      const result = walkSchema(schema);
+      expect(result.oneOfCount).toBe(3);
+      expect(result.anyOfCount).toBe(0);
+      expect(result.allOfCount).toBe(0);
+    });
+
+    it('should count anyOf schemas', () => {
+      const schema = {
+        anyOf: [{ type: 'string' }, { type: 'integer' }],
+      };
+      const result = walkSchema(schema);
+      expect(result.anyOfCount).toBe(2);
+      expect(result.oneOfCount).toBe(0);
+    });
+
+    it('should count allOf schemas', () => {
+      const schema = {
+        allOf: [
+          { type: 'object', properties: { a: { type: 'string' } } },
+          { type: 'object', properties: { b: { type: 'integer' } } },
+        ],
+      };
+      const result = walkSchema(schema);
+      expect(result.allOfCount).toBe(2);
+    });
+
+    it('should count nested polymorphism', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          field: {
+            oneOf: [
+              { type: 'string' },
+              {
+                anyOf: [{ type: 'integer' }, { type: 'boolean' }],
+              },
+            ],
+          },
+        },
+      };
+      const result = walkSchema(schema);
+      expect(result.oneOfCount).toBe(2);
+      expect(result.anyOfCount).toBe(2);
+    });
+
+    it('should detect discriminator', () => {
+      const schema = {
+        oneOf: [
+          { type: 'object', properties: { kind: { type: 'string' } } },
+          { type: 'object', properties: { kind: { type: 'string' } } },
+        ],
+        discriminator: { propertyName: 'kind' },
+      };
+      const result = walkSchema(schema);
+      expect(result.hasDiscriminator).toBe(true);
+    });
+
+    it('should not report discriminator when missing', () => {
+      const schema = {
+        oneOf: [{ type: 'string' }, { type: 'integer' }],
+      };
+      expect(walkSchema(schema).hasDiscriminator).toBe(false);
+    });
+  });
+
+  describe('property counting and description coverage', () => {
+    it('should count properties', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          a: { type: 'string' },
+          b: { type: 'integer' },
+          c: { type: 'boolean' },
+        },
+      };
+      const result = walkSchema(schema);
+      expect(result.propertyCount).toBe(3);
+      expect(result.totalProperties).toBe(3);
+    });
+
+    it('should count properties with descriptions', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          a: { type: 'string', description: 'First field' },
+          b: { type: 'integer' },
+          c: { type: 'boolean', description: 'Third field' },
+        },
+      };
+      const result = walkSchema(schema);
+      expect(result.propertiesWithDescription).toBe(2);
+    });
+  });
+
+  describe('constraint counting', () => {
+    it('should count enum as a constraint', () => {
+      const schema = { type: 'string', enum: ['a', 'b', 'c'] };
+      expect(walkSchema(schema).constraintCount).toBe(1);
+    });
+
+    it('should count format as a constraint', () => {
+      const schema = { type: 'string', format: 'email' };
+      expect(walkSchema(schema).constraintCount).toBe(1);
+    });
+
+    it('should count multiple constraints', () => {
+      const schema = {
+        type: 'string',
+        minLength: 1,
+        maxLength: 255,
+        pattern: '^[a-z]+$',
+        format: 'email',
+      };
+      expect(walkSchema(schema).constraintCount).toBe(4);
+    });
+
+    it('should count numeric constraints', () => {
+      const schema = {
+        type: 'integer',
+        minimum: 0,
+        maximum: 100,
+        multipleOf: 5,
+      };
+      expect(walkSchema(schema).constraintCount).toBe(3);
+    });
+  });
+
+  describe('$ref resolution', () => {
+    it('should resolve $ref schemas via resolveRef', () => {
+      const components = {
+        Address: {
+          type: 'object',
+          properties: {
+            city: { type: 'string', description: 'City name' },
+            zip: { type: 'string', pattern: '^[0-9]{5}$' },
+          },
+        },
+      };
+      const resolveRef = (ref: string) => {
+        if (ref === '#/components/schemas/Address') return components.Address;
+        return undefined;
+      };
+
+      const schema = { $ref: '#/components/schemas/Address' };
+      const result = walkSchema(schema, resolveRef);
+      expect(result.depth).toBe(1);
+      expect(result.propertyCount).toBe(2);
+      expect(result.propertiesWithDescription).toBe(1);
+      expect(result.constraintCount).toBe(1);
+    });
+
+    it('should resolve nested $ref in properties', () => {
+      const components = {
+        Name: { type: 'string', minLength: 1 },
+      };
+      const resolveRef = (ref: string) => {
+        if (ref === '#/components/schemas/Name') return components.Name;
+        return undefined;
+      };
+
+      const schema = {
+        type: 'object',
+        properties: {
+          name: { $ref: '#/components/schemas/Name' },
+          age: { type: 'integer' },
+        },
+      };
+      const result = walkSchema(schema, resolveRef);
+      expect(result.propertyCount).toBe(2);
+      expect(result.constraintCount).toBe(1);
+    });
+  });
+
+  describe('const constraint', () => {
+    it('should count const as a constraint', () => {
+      const schema = { type: 'string', const: 'fixed' };
+      expect(walkSchema(schema).constraintCount).toBe(1);
+    });
+  });
+
+  describe('property-level examples', () => {
+    it('should count properties with example keyword', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string', example: 'abc123' },
+          name: { type: 'string' },
+        },
+      };
+      const result = walkSchema(schema);
+      expect(result.propertiesWithExamples).toBe(1);
+    });
+
+    it('should count properties with examples keyword', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          status: { type: 'string', examples: ['active', 'inactive'] },
+          name: { type: 'string' },
+        },
+      };
+      const result = walkSchema(schema);
+      expect(result.propertiesWithExamples).toBe(1);
+    });
+  });
+
+  describe('writable fields', () => {
+    it('should count writable top-level fields', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string', readOnly: true },
+          name: { type: 'string' },
+          email: { type: 'string' },
+        },
+      };
+      const result = walkSchema(schema);
+      expect(result.writableTopLevelFieldCount).toBe(2);
+    });
+
+    it('should count all fields as writable when none are readOnly', () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          a: { type: 'string' },
+          b: { type: 'string' },
+        },
+      };
+      expect(walkSchema(schema).writableTopLevelFieldCount).toBe(2);
+    });
+  });
+});
diff --git a/packages/cli/src/commands/score/__tests__/scoring.test.ts b/packages/cli/src/commands/score/__tests__/scoring.test.ts
new file mode 100644
index 0000000000..98df9be26e
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/scoring.test.ts
@@ -0,0 +1,284 @@
+import { collectDocumentMetrics } from '../collectors/document-metrics.js';
+import { DEFAULT_SCORING_CONSTANTS } from '../constants.js';
+import {
+  computeOperationIntegrationSubscores,
+  computeOperationAgentSubscores,
+  computeIntegrationSimplicity,
+  computeAgentReadiness,
+  computeAllOperationScores,
+  computeDocumentScores,
+} from '../scoring.js';
+import type { OperationMetrics, ScoringConstants } from '../types.js';
+
+function makeBaseMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetrics {
+  return {
+    path: '/test',
+    method: 'get',
+    operationId: 'testOp',
+    parameterCount: 0,
+    requiredParameterCount: 0,
+    paramsWithDescription: 0,
+    requestBodyPresent: false,
+    topLevelWritableFieldCount: 0,
+    maxRequestSchemaDepth: 0,
+    maxResponseSchemaDepth: 0,
+    polymorphismCount: 0,
+    anyOfCount: 0,
+    hasDiscriminator: false,
+    propertyCount: 0,
+    operationDescriptionPresent: true,
+    schemaPropertiesWithDescription: 0,
+    totalSchemaProperties: 0,
+    constraintCount: 0,
+    requestExamplePresent: false,
+    responseExamplePresent: true,
+    structuredErrorResponseCount: 0,
+    totalErrorResponses: 0,
+    ambiguousIdentifierCount: 0,
+    refsUsed: new Set(),
+    ...overrides,
+  };
+}
+
+describe('scoring', () => {
+  describe('depth normalization', () => {
+    it('should give high schema simplicity for shallow schemas', () => {
+      const metrics = makeBaseMetrics({ maxRequestSchemaDepth: 1, maxResponseSchemaDepth: 1 });
+      const subscores = computeOperationIntegrationSubscores(metrics, 0);
+      expect(subscores.schemaSimplicity).toBeGreaterThan(0.8);
+    });
+
+    it('should give lower schema simplicity for deep schemas', () => {
+      const metrics = makeBaseMetrics({ maxRequestSchemaDepth: 8, maxResponseSchemaDepth: 6 });
+      const subscores = computeOperationIntegrationSubscores(metrics, 0);
+      expect(subscores.schemaSimplicity).toBeLessThan(0.5);
+    });
+
+    it('should clamp schema simplicity at 0 for extremely deep schemas', () => {
+      const metrics = makeBaseMetrics({ maxRequestSchemaDepth: 20, maxResponseSchemaDepth: 20 });
+      const subscores = computeOperationIntegrationSubscores(metrics, 0);
+      expect(subscores.schemaSimplicity).toBe(0);
+    });
+  });
+
+  describe('polymorphism penalties', () => {
+    it('should penalize anyOf more than oneOf', () => {
+      const metricsAnyOf = makeBaseMetrics({
+        polymorphismCount: 3,
+        anyOfCount: 3,
+      });
+      const metricsOneOf = makeBaseMetrics({
+        polymorphismCount: 3,
+        anyOfCount: 0,
+      });
+
+      const subAnyOf = computeOperationIntegrationSubscores(metricsAnyOf, 0);
+      const subOneOf = computeOperationIntegrationSubscores(metricsOneOf, 0);
+
+      expect(subAnyOf.schemaSimplicity).toBeLessThan(subOneOf.schemaSimplicity);
+    });
+
+    it('should apply anyOfPenaltyMultiplier from constants', () => {
+      const metrics = makeBaseMetrics({ polymorphismCount: 2, anyOfCount: 2 });
+      const lowPenalty: ScoringConstants = {
+        ...DEFAULT_SCORING_CONSTANTS,
+        weights: {
+          ...DEFAULT_SCORING_CONSTANTS.weights,
+          anyOfPenaltyMultiplier: 1.0,
+        },
+      };
+      const highPenalty: ScoringConstants = {
+        ...DEFAULT_SCORING_CONSTANTS,
+        weights: {
+          ...DEFAULT_SCORING_CONSTANTS.weights,
+          anyOfPenaltyMultiplier: 5.0,
+        },
+      };
+
+      const subLow = computeOperationIntegrationSubscores(metrics, 0, lowPenalty);
+      const subHigh = computeOperationIntegrationSubscores(metrics, 0, highPenalty);
+
+      expect(subLow.schemaSimplicity).toBeGreaterThan(subHigh.schemaSimplicity);
+    });
+
+    it('should give higher agent polymorphism clarity when discriminator is present', () => {
+      const withDisc = makeBaseMetrics({
+        polymorphismCount: 4,
+        anyOfCount: 2,
+        hasDiscriminator: true,
+      });
+      const withoutDisc = makeBaseMetrics({
+        polymorphismCount: 4,
+        anyOfCount: 2,
+        hasDiscriminator: false,
+      });
+
+      const subWith = computeOperationAgentSubscores(withDisc, 0);
+      const subWithout = computeOperationAgentSubscores(withoutDisc, 0);
+
+      expect(subWith.polymorphismClarity).toBeGreaterThan(subWithout.polymorphismClarity);
+    });
+  });
+
+  describe('determinism', () => {
+    it('should produce identical scores for the same input', () => {
+      const doc = {
+        openapi: '3.0.0',
+        info: { title: 'Test', version: '1.0.0' },
+        paths: {
+          '/a': {
+            get: {
+              operationId: 'getA',
+              description: 'Get A',
+              parameters: [{ name: 'id', in: 'query', required: true, schema: { type: 'string' } }],
+              responses: {
+                '200': {
+                  description: 'OK',
+                  content: {
+                    'application/json': {
+                      schema: { type: 'object', properties: { name: { type: 'string' } } },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          '/b': {
+            post: {
+              operationId: 'createB',
+              description: 'Create B',
+              requestBody: {
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'object',
+                      properties: {
+                        value: { type: 'string', minLength: 1 },
+                      },
+                    },
+                    example: { value: 'test' },
+                  },
+                },
+              },
+              responses: {
+                '201': {
+                  description: 'Created',
+                  content: {
+                    'application/json': {
+                      schema: { type: 'object', properties: { id: { type: 'string' } } },
+                      example: { id: '1' },
+                    },
+                  },
+                },
+                '400': {
+                  description: 'Bad Request',
+                  content: {
+                    'application/json': {
+                      schema: {
+                        type: 'object',
+                        properties: { message: { type: 'string' } },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const metrics1 = collectDocumentMetrics(doc);
+      const metrics2 = collectDocumentMetrics(doc);
+
+      const depths1 = new Map(Array.from(metrics1.operations.keys()).map((k) => [k, 0]));
+      const depths2 = new Map(Array.from(metrics2.operations.keys()).map((k) => [k, 0]));
+
+      const scores1 = computeAllOperationScores(metrics1, depths1);
+      const scores2 = computeAllOperationScores(metrics2, depths2);
+
+      const doc1 = computeDocumentScores(scores1);
+      const doc2 = computeDocumentScores(scores2);
+
+      expect(doc1.integrationSimplicity).toBe(doc2.integrationSimplicity);
+      expect(doc1.agentReadiness).toBe(doc2.agentReadiness);
+
+      for (const [key, s1] of scores1) {
+        const s2 = scores2.get(key)!;
+        expect(s1.integrationSimplicity).toBe(s2.integrationSimplicity);
+        expect(s1.agentReadiness).toBe(s2.agentReadiness);
+      }
+    });
+  });
+
+  describe('composite scores', () => {
+    it('should produce scores in 0-100 range', () => {
+      const metrics = makeBaseMetrics({
+        parameterCount: 10,
+        maxRequestSchemaDepth: 5,
+        polymorphismCount: 3,
+        anyOfCount: 2,
+      });
+      const intSub = computeOperationIntegrationSubscores(metrics, 2);
+      const agentSub = computeOperationAgentSubscores(metrics, 2);
+      const intScore = computeIntegrationSimplicity(intSub);
+      const agentScore = computeAgentReadiness(agentSub);
+
+      expect(intScore).toBeGreaterThanOrEqual(0);
+      expect(intScore).toBeLessThanOrEqual(100);
+      expect(agentScore).toBeGreaterThanOrEqual(0);
+      expect(agentScore).toBeLessThanOrEqual(100);
+    });
+
+    it('should return 100/100 for an empty document', () => {
+      const opScores = new Map();
+      const { integrationSimplicity, agentReadiness } = computeDocumentScores(opScores);
+      expect(integrationSimplicity).toBe(100);
+      expect(agentReadiness).toBe(100);
+    });
+
+    it('should return higher scores for well-documented API', () => {
+      const good = makeBaseMetrics({
+        operationDescriptionPresent: true,
+        paramsWithDescription: 3,
+        parameterCount: 3,
+        schemaPropertiesWithDescription: 5,
+        totalSchemaProperties: 5,
+        constraintCount: 5,
+        requestExamplePresent: true,
+        responseExamplePresent: true,
+        requestBodyPresent: true,
+        structuredErrorResponseCount: 2,
+        totalErrorResponses: 2,
+      });
+      const bad = makeBaseMetrics({
+        operationDescriptionPresent: false,
+        paramsWithDescription: 0,
+        parameterCount: 8,
+        schemaPropertiesWithDescription: 0,
+        totalSchemaProperties: 10,
+        constraintCount: 0,
+        requestExamplePresent: false,
+        responseExamplePresent: false,
+        requestBodyPresent: true,
+        maxRequestSchemaDepth: 6,
+        polymorphismCount: 5,
+        anyOfCount: 3,
+        structuredErrorResponseCount: 0,
+        totalErrorResponses: 3,
+        ambiguousIdentifierCount: 4,
+      });
+
+      const goodIntSub = computeOperationIntegrationSubscores(good, 0);
+      const badIntSub = computeOperationIntegrationSubscores(bad, 3);
+      expect(computeIntegrationSimplicity(goodIntSub)).toBeGreaterThan(
+        computeIntegrationSimplicity(badIntSub)
+      );
+
+      const goodAgentSub = computeOperationAgentSubscores(good, 0);
+      const badAgentSub = computeOperationAgentSubscores(bad, 3);
+      expect(computeAgentReadiness(goodAgentSub)).toBeGreaterThan(
+        computeAgentReadiness(badAgentSub)
+      );
+    });
+  });
+});
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
new file mode 100644
index 0000000000..564cbe46e5
--- /dev/null
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -0,0 +1,261 @@
+import { AMBIGUOUS_PARAM_NAMES } from '../constants.js';
+import type { DocumentMetrics, OperationMetrics, RefResolver } from '../types.js';
+import { walkSchema } from './schema-walker.js';
+
+const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const;
+
+export function collectDocumentMetrics(document: Record<string, any>): DocumentMetrics {
+  const operations = new Map<string, OperationMetrics>();
+  const paths = document.paths;
+  const resolveRef = createRefResolver(document);
+
+  if (paths && typeof paths === 'object') {
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
+      if (!pathItem || typeof pathItem !== 'object') continue;
+      const pathObj = resolveIfRef(pathItem as Record<string, any>, resolveRef);
+      if (!pathObj) continue;
+
+      const pathLevelParams: any[] = Array.isArray(pathObj.parameters) ? pathObj.parameters : [];
+
+      for (const method of HTTP_METHODS) {
+        const operation = pathObj[method];
+        if (!operation || typeof operation !== 'object') continue;
+
+        const opKey = operation.operationId ?? `${method.toUpperCase()} ${pathStr}`;
+        const metrics = collectOperationMetrics(
+          pathStr,
+          method,
+          operation as Record<string, any>,
+          pathLevelParams,
+          resolveRef
+        );
+        operations.set(opKey, metrics);
+      }
+    }
+  }
+
+  return { operationCount: operations.size, operations };
+}
+
+function createRefResolver(document: Record<string, any>): RefResolver {
+  return (ref: string) => {
+    if (!ref.startsWith('#/')) return undefined;
+    const parts = ref.slice(2).split('/');
+    let current: any = document;
+    for (const part of parts) {
+      if (!current || typeof current !== 'object') return undefined;
+      current = current[decodeURIComponent(part.replace(/~1/g, '/').replace(/~0/g, '~'))];
+    }
+    return current && typeof current === 'object' ? current : undefined;
+  };
+}
+
+function resolveIfRef(
+  node: Record<string, any>,
+  resolveRef: RefResolver
+): Record<string, any> | undefined {
+  if (node.$ref && typeof node.$ref === 'string') {
+    return resolveRef(node.$ref);
+  }
+  return node;
+}
+
+function collectOperationMetrics(
+  path: string,
+  method: string,
+  operation: Record<string, any>,
+  pathLevelParams: any[],
+  resolveRef: RefResolver
+): OperationMetrics {
+  const allParams = mergeParameters(pathLevelParams, operation.parameters ?? [], resolveRef);
+
+  let parameterCount = 0;
+  let requiredParameterCount = 0;
+  let paramsWithDescription = 0;
+  let ambiguousIdentifierCount = 0;
+
+  for (const param of allParams) {
+    if (!param || typeof param !== 'object') continue;
+    parameterCount++;
+    if (param.required) requiredParameterCount++;
+    if (param.description) paramsWithDescription++;
+    if (isAmbiguousParam(param)) ambiguousIdentifierCount++;
+  }
+
+  const reqBody = operation.requestBody
+    ? resolveIfRef(operation.requestBody, resolveRef)
+    : undefined;
+  const requestBodyPresent = !!reqBody;
+  let maxRequestSchemaDepth = 0;
+  let topLevelWritableFieldCount = 0;
+  let requestExamplePresent = false;
+  let totalPolymorphism = 0;
+  let totalAnyOf = 0;
+  let hasDiscriminator = false;
+  let propertyCount = 0;
+  let schemaPropsWithDesc = 0;
+  let totalSchemaProps = 0;
+  let constraintCount = 0;
+  const refsUsed = new Set<string>();
+
+  if (reqBody) {
+    collectRefs(reqBody, refsUsed);
+
+    if (reqBody.content && typeof reqBody.content === 'object') {
+      for (const [, mediaType] of Object.entries(reqBody.content)) {
+        const mt = mediaType as Record<string, any>;
+        if (hasExample(mt)) {
+          requestExamplePresent = true;
+        }
+        if (mt.schema) {
+          const sm = walkSchema(mt.schema, resolveRef);
+          maxRequestSchemaDepth = Math.max(maxRequestSchemaDepth, sm.depth);
+          topLevelWritableFieldCount = Math.max(
+            topLevelWritableFieldCount,
+            sm.writableTopLevelFieldCount
+          );
+          totalPolymorphism += sm.oneOfCount + sm.anyOfCount + sm.allOfCount;
+          totalAnyOf += sm.anyOfCount;
+          if (sm.hasDiscriminator) hasDiscriminator = true;
+          propertyCount += sm.propertyCount;
+          schemaPropsWithDesc += sm.propertiesWithDescription;
+          totalSchemaProps += sm.totalProperties;
+          constraintCount += sm.constraintCount;
+          if (sm.propertiesWithExamples > 0) requestExamplePresent = true;
+          collectRefs(mt.schema, refsUsed);
+        }
+      }
+    }
+  }
+
+  let maxResponseSchemaDepth = 0;
+  let responseExamplePresent = false;
+  let structuredErrorResponseCount = 0;
+  let totalErrorResponses = 0;
+
+  if (operation.responses && typeof operation.responses === 'object') {
+    for (const [code, rawResponse] of Object.entries(operation.responses)) {
+      if (!rawResponse || typeof rawResponse !== 'object') continue;
+      const resp = resolveIfRef(rawResponse as Record<string, any>, resolveRef);
+      if (!resp) continue;
+      collectRefs(rawResponse as Record<string, any>, refsUsed);
+
+      const isError = isErrorCode(code);
+      if (isError) totalErrorResponses++;
+
+      const hasContent = resp.content && typeof resp.content === 'object';
+      if (hasContent) {
+        for (const [, mediaType] of Object.entries(resp.content)) {
+          const mt = mediaType as Record<string, any>;
+          if (hasExample(mt)) {
+            responseExamplePresent = true;
+          }
+          if (mt.schema) {
+            const sm = walkSchema(mt.schema, resolveRef);
+            maxResponseSchemaDepth = Math.max(maxResponseSchemaDepth, sm.depth);
+            totalPolymorphism += sm.oneOfCount + sm.anyOfCount + sm.allOfCount;
+            totalAnyOf += sm.anyOfCount;
+            if (sm.hasDiscriminator) hasDiscriminator = true;
+            propertyCount += sm.propertyCount;
+            schemaPropsWithDesc += sm.propertiesWithDescription;
+            totalSchemaProps += sm.totalProperties;
+            constraintCount += sm.constraintCount;
+            if (sm.propertiesWithExamples > 0) responseExamplePresent = true;
+            collectRefs(mt.schema, refsUsed);
+          }
+
+          if (isError) {
+            structuredErrorResponseCount++;
+          }
+        }
+      } else if (isError && resp.description) {
+        structuredErrorResponseCount++;
+      }
+    }
+  }
+
+  return {
+    path,
+    method,
+    operationId: operation.operationId,
+    parameterCount,
+    requiredParameterCount,
+    paramsWithDescription,
+    requestBodyPresent,
+    topLevelWritableFieldCount,
+    maxRequestSchemaDepth,
+    maxResponseSchemaDepth,
+    polymorphismCount: totalPolymorphism,
+    anyOfCount: totalAnyOf,
+    hasDiscriminator,
+    propertyCount,
+    operationDescriptionPresent: !!operation.description,
+    schemaPropertiesWithDescription: schemaPropsWithDesc,
+    totalSchemaProperties: totalSchemaProps,
+    constraintCount,
+    requestExamplePresent,
+    responseExamplePresent,
+    structuredErrorResponseCount,
+    totalErrorResponses,
+    ambiguousIdentifierCount,
+    refsUsed,
+  };
+}
+
+function mergeParameters(pathLevel: any[], opLevel: any[], resolveRef: RefResolver): any[] {
+  const merged = new Map<string, any>();
+  for (const raw of pathLevel) {
+    const p = raw && typeof raw === 'object' ? (resolveIfRef(raw, resolveRef) ?? raw) : raw;
+    if (p && typeof p === 'object' && p.name && p.in) {
+      merged.set(`${p.in}:${p.name}`, p);
+    }
+  }
+  for (const raw of opLevel) {
+    const p = raw && typeof raw === 'object' ? (resolveIfRef(raw, resolveRef) ?? raw) : raw;
+    if (p && typeof p === 'object' && p.name && p.in) {
+      merged.set(`${p.in}:${p.name}`, p);
+    }
+  }
+  return Array.from(merged.values());
+}
+
+function hasExample(mediaType: Record<string, any>): boolean {
+  if (mediaType.example !== undefined) return true;
+  if (mediaType.examples && typeof mediaType.examples === 'object') {
+    return Object.keys(mediaType.examples).length > 0;
+  }
+  return false;
+}
+
+function isAmbiguousParam(param: Record<string, any>): boolean {
+  if (param.description) return false;
+  const name = (param.name ?? '').toLowerCase();
+  return AMBIGUOUS_PARAM_NAMES.has(name);
+}
+
+function isErrorCode(code: string): boolean {
+  if (code === 'default') return true;
+  const num = parseInt(code, 10);
+  return num >= 400 && num < 600;
+}
+
+function collectRefs(node: any, refs: Set<string>, seen?: Set<any>): void {
+  if (!node || typeof node !== 'object') return;
+  seen = seen ?? new Set();
+  if (seen.has(node)) return;
+  seen.add(node);
+
+  if (typeof node.$ref === 'string') {
+    refs.add(node.$ref);
+  }
+
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectRefs(item, refs, seen);
+    }
+  } else {
+    for (const val of Object.values(node)) {
+      collectRefs(val, refs, seen);
+    }
+  }
+}
diff --git a/packages/cli/src/commands/score/collectors/schema-walker.ts b/packages/cli/src/commands/score/collectors/schema-walker.ts
new file mode 100644
index 0000000000..3425fb8a70
--- /dev/null
+++ b/packages/cli/src/commands/score/collectors/schema-walker.ts
@@ -0,0 +1,165 @@
+import type { RefResolver, SchemaMetrics } from '../types.js';
+
+const CONSTRAINT_KEYS = [
+  'enum',
+  'const',
+  'format',
+  'pattern',
+  'minimum',
+  'maximum',
+  'minLength',
+  'maxLength',
+  'minItems',
+  'maxItems',
+  'minProperties',
+  'maxProperties',
+  'multipleOf',
+  'exclusiveMinimum',
+  'exclusiveMaximum',
+  'uniqueItems',
+] as const;
+
+export function walkSchema(
+  schema: Record<string, any> | undefined | null,
+  resolveRef?: RefResolver,
+  seen?: Set<object>
+): SchemaMetrics {
+  const result: SchemaMetrics = {
+    depth: 0,
+    propertyCount: 0,
+    oneOfCount: 0,
+    anyOfCount: 0,
+    allOfCount: 0,
+    hasDiscriminator: false,
+    propertiesWithDescription: 0,
+    totalProperties: 0,
+    constraintCount: 0,
+    writableTopLevelFieldCount: 0,
+    propertiesWithExamples: 0,
+  };
+
+  if (!schema || typeof schema !== 'object') {
+    return result;
+  }
+
+  if (schema.$ref && typeof schema.$ref === 'string' && resolveRef) {
+    const resolved = resolveRef(schema.$ref);
+    if (resolved) {
+      return walkSchema(resolved, resolveRef, seen);
+    }
+    return result;
+  }
+
+  seen = seen ?? new Set();
+  if (seen.has(schema)) {
+    return result;
+  }
+  seen.add(schema);
+
+  if (schema.discriminator && schema.discriminator.propertyName) {
+    result.hasDiscriminator = true;
+  }
+
+  for (const key of CONSTRAINT_KEYS) {
+    if (schema[key] !== undefined) {
+      result.constraintCount++;
+    }
+  }
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    const props = Object.entries(schema.properties) as [string, Record<string, any>][];
+    result.totalProperties += props.length;
+    result.propertyCount += props.length;
+
+    for (const [, rawPropSchema] of props) {
+      const propSchema =
+        rawPropSchema?.$ref && resolveRef
+          ? (resolveRef(rawPropSchema.$ref) ?? rawPropSchema)
+          : rawPropSchema;
+      if (propSchema && typeof propSchema === 'object') {
+        if (propSchema.description) {
+          result.propertiesWithDescription++;
+        }
+        if (propSchema.example !== undefined || propSchema.examples) {
+          result.propertiesWithExamples++;
+        }
+        if (!propSchema.readOnly) {
+          result.writableTopLevelFieldCount++;
+        }
+      }
+    }
+
+    let maxChildDepth = 0;
+    for (const [, rawPropSchema] of props) {
+      const propSchema =
+        rawPropSchema?.$ref && resolveRef
+          ? (resolveRef(rawPropSchema.$ref) ?? rawPropSchema)
+          : rawPropSchema;
+      if (propSchema && typeof propSchema === 'object') {
+        const child = walkSchema(propSchema, resolveRef, seen);
+        maxChildDepth = Math.max(maxChildDepth, child.depth);
+        mergeChildMetrics(result, child);
+      }
+    }
+    result.depth = Math.max(result.depth, 1 + maxChildDepth);
+  }
+
+  if (schema.items && typeof schema.items === 'object' && schema.items !== true) {
+    const child = walkSchema(schema.items as Record<string, any>, resolveRef, seen);
+    result.depth = Math.max(result.depth, 1 + child.depth);
+    mergeChildMetrics(result, child);
+  }
+
+  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+    const child = walkSchema(schema.additionalProperties as Record<string, any>, resolveRef, seen);
+    result.depth = Math.max(result.depth, 1 + child.depth);
+    mergeChildMetrics(result, child);
+  }
+
+  walkComposition(schema, 'oneOf', result, resolveRef, seen);
+  walkComposition(schema, 'anyOf', result, resolveRef, seen);
+  walkComposition(schema, 'allOf', result, resolveRef, seen);
+
+  return result;
+}
+
+function walkComposition(
+  schema: Record<string, any>,
+  keyword: 'oneOf' | 'anyOf' | 'allOf',
+  result: SchemaMetrics,
+  resolveRef: RefResolver | undefined,
+  seen: Set<object>
+): void {
+  const arr = schema[keyword];
+  if (!Array.isArray(arr) || arr.length === 0) return;
+
+  const countKey = `${keyword}Count` as keyof Pick<
+    SchemaMetrics,
+    'oneOfCount' | 'anyOfCount' | 'allOfCount'
+  >;
+  result[countKey] += arr.length;
+
+  let maxChildDepth = 0;
+  for (const subSchema of arr) {
+    if (subSchema && typeof subSchema === 'object') {
+      const child = walkSchema(subSchema, resolveRef, seen);
+      maxChildDepth = Math.max(maxChildDepth, child.depth);
+      mergeChildMetrics(result, child);
+    }
+  }
+  result.depth = Math.max(result.depth, 1 + maxChildDepth);
+}
+
+function mergeChildMetrics(parent: SchemaMetrics, child: SchemaMetrics): void {
+  parent.oneOfCount += child.oneOfCount;
+  parent.anyOfCount += child.anyOfCount;
+  parent.allOfCount += child.allOfCount;
+  parent.propertyCount += child.propertyCount;
+  parent.propertiesWithDescription += child.propertiesWithDescription;
+  parent.totalProperties += child.totalProperties;
+  parent.constraintCount += child.constraintCount;
+  parent.propertiesWithExamples += child.propertiesWithExamples;
+  if (child.hasDiscriminator) {
+    parent.hasDiscriminator = true;
+  }
+}
diff --git a/packages/cli/src/commands/score/collectors/workflow-graph.ts b/packages/cli/src/commands/score/collectors/workflow-graph.ts
new file mode 100644
index 0000000000..5dc57c67f2
--- /dev/null
+++ b/packages/cli/src/commands/score/collectors/workflow-graph.ts
@@ -0,0 +1,71 @@
+import type { OperationMetrics } from '../types.js';
+
+/**
+ * Builds a workflow dependency graph from shared $ref usage across operations.
+ * An edge from A to B means both A and B reference the same schema $ref.
+ * The depth for each operation is the longest path from a root node (no incoming edges)
+ * in the undirected "shared ref" graph.
+ */
+export function computeWorkflowDepths(
+  operations: Map<string, OperationMetrics>
+): Map<string, number> {
+  const refToOps = new Map<string, Set<string>>();
+
+  for (const [opKey, metrics] of operations) {
+    for (const ref of metrics.refsUsed) {
+      let ops = refToOps.get(ref);
+      if (!ops) {
+        ops = new Set();
+        refToOps.set(ref, ops);
+      }
+      ops.add(opKey);
+    }
+  }
+
+  const adjacency = new Map<string, Set<string>>();
+  for (const opKey of operations.keys()) {
+    adjacency.set(opKey, new Set());
+  }
+
+  for (const ops of refToOps.values()) {
+    if (ops.size < 2) continue;
+    const opArray = Array.from(ops);
+    for (let i = 0; i < opArray.length; i++) {
+      for (let j = i + 1; j < opArray.length; j++) {
+        adjacency.get(opArray[i])!.add(opArray[j]);
+        adjacency.get(opArray[j])!.add(opArray[i]);
+      }
+    }
+  }
+
+  const depths = new Map<string, number>();
+
+  for (const opKey of operations.keys()) {
+    const depth = bfsMaxDepth(opKey, adjacency);
+    depths.set(opKey, depth);
+  }
+
+  return depths;
+}
+
+function bfsMaxDepth(start: string, adjacency: Map<string, Set<string>>): number {
+  const visited = new Set<string>([start]);
+  let queue = [start];
+  let depth = 0;
+
+  while (queue.length > 0) {
+    const next: string[] = [];
+    for (const node of queue) {
+      for (const neighbor of adjacency.get(node) ?? []) {
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          next.push(neighbor);
+        }
+      }
+    }
+    if (next.length > 0) depth++;
+    queue = next;
+  }
+
+  return depth;
+}
diff --git a/packages/cli/src/commands/score/constants.ts b/packages/cli/src/commands/score/constants.ts
new file mode 100644
index 0000000000..59994102e4
--- /dev/null
+++ b/packages/cli/src/commands/score/constants.ts
@@ -0,0 +1,57 @@
+import type { ScoringConstants } from './types.js';
+
+export const DEFAULT_SCORING_CONSTANTS: ScoringConstants = {
+  thresholds: {
+    maxParamsGood: 5,
+    maxDepthGood: 4,
+    maxPolymorphismGood: 2,
+    maxPropertiesGood: 20,
+    maxWorkflowDepthGood: 3,
+    maxAmbiguousGood: 0,
+  },
+  weights: {
+    integration: {
+      parameterSimplicity: 0.2,
+      schemaSimplicity: 0.2,
+      documentationQuality: 0.15,
+      constraintClarity: 0.1,
+      exampleCoverage: 0.15,
+      errorClarity: 0.1,
+      workflowClarity: 0.1,
+    },
+    agent: {
+      documentationQuality: 0.2,
+      constraintClarity: 0.15,
+      exampleCoverage: 0.2,
+      errorClarity: 0.15,
+      identifierClarity: 0.1,
+      workflowClarity: 0.1,
+      polymorphismClarity: 0.1,
+    },
+    anyOfPenaltyMultiplier: 2.0,
+  },
+  hotspotLimit: 10,
+};
+
+export const AMBIGUOUS_PARAM_NAMES = new Set([
+  'id',
+  'name',
+  'type',
+  'value',
+  'data',
+  'key',
+  'status',
+  'state',
+  'code',
+  'result',
+  'item',
+  'object',
+  'resource',
+  'entity',
+  'input',
+  'output',
+  'payload',
+  'body',
+  'content',
+  'info',
+]);
diff --git a/packages/cli/src/commands/score/formatters/json.ts b/packages/cli/src/commands/score/formatters/json.ts
new file mode 100644
index 0000000000..8e45cc6073
--- /dev/null
+++ b/packages/cli/src/commands/score/formatters/json.ts
@@ -0,0 +1,60 @@
+import { logger } from '@redocly/openapi-core';
+
+import type { ScoreResult } from '../types.js';
+
+export function printScoreJson(result: ScoreResult): void {
+  const output = {
+    integrationSimplicity: result.integrationSimplicity,
+    agentReadiness: result.agentReadiness,
+    integrationSubscores: result.integrationSubscores,
+    agentSubscores: result.agentSubscores,
+    rawMetrics: {
+      operationCount: result.rawMetrics.operationCount,
+      operations: Object.fromEntries(
+        Array.from(result.rawMetrics.operations.entries()).map(([key, m]) => [
+          key,
+          {
+            path: m.path,
+            method: m.method,
+            operationId: m.operationId,
+            parameterCount: m.parameterCount,
+            requiredParameterCount: m.requiredParameterCount,
+            paramsWithDescription: m.paramsWithDescription,
+            requestBodyPresent: m.requestBodyPresent,
+            topLevelWritableFieldCount: m.topLevelWritableFieldCount,
+            maxRequestSchemaDepth: m.maxRequestSchemaDepth,
+            maxResponseSchemaDepth: m.maxResponseSchemaDepth,
+            polymorphismCount: m.polymorphismCount,
+            anyOfCount: m.anyOfCount,
+            hasDiscriminator: m.hasDiscriminator,
+            propertyCount: m.propertyCount,
+            operationDescriptionPresent: m.operationDescriptionPresent,
+            schemaPropertiesWithDescription: m.schemaPropertiesWithDescription,
+            totalSchemaProperties: m.totalSchemaProperties,
+            constraintCount: m.constraintCount,
+            requestExamplePresent: m.requestExamplePresent,
+            responseExamplePresent: m.responseExamplePresent,
+            structuredErrorResponseCount: m.structuredErrorResponseCount,
+            totalErrorResponses: m.totalErrorResponses,
+            ambiguousIdentifierCount: m.ambiguousIdentifierCount,
+          },
+        ])
+      ),
+    },
+    operationScores: Object.fromEntries(
+      Array.from(result.operationScores.entries()).map(([key, s]) => [
+        key,
+        {
+          integrationSimplicity: s.integrationSimplicity,
+          agentReadiness: s.agentReadiness,
+          integrationSubscores: s.integrationSubscores,
+          agentSubscores: s.agentSubscores,
+        },
+      ])
+    ),
+    workflowDepths: Object.fromEntries(result.workflowDepths),
+    hotspots: result.hotspots,
+  };
+
+  logger.output(JSON.stringify(output, null, 2));
+}
diff --git a/packages/cli/src/commands/score/formatters/stylish.ts b/packages/cli/src/commands/score/formatters/stylish.ts
new file mode 100644
index 0000000000..7ad5a58d44
--- /dev/null
+++ b/packages/cli/src/commands/score/formatters/stylish.ts
@@ -0,0 +1,149 @@
+import { logger } from '@redocly/openapi-core';
+import { bold, cyan, green, red, white, yellow, gray } from 'colorette';
+
+import type { ScoreResult } from '../types.js';
+
+export function printScoreStylish(result: ScoreResult): void {
+  printScores(result);
+  printSubscores(result);
+  printRawMetricsSummary(result);
+  printHotspots(result);
+}
+
+function scoreColor(score: number): (text: string) => string {
+  if (score >= 80) return green;
+  if (score >= 50) return yellow;
+  return red;
+}
+
+function formatScore(score: number): string {
+  return scoreColor(score)(bold(score.toFixed(1)));
+}
+
+function out(str: string): void {
+  logger.output(str + '\n');
+}
+
+function printScores(result: ScoreResult): void {
+  out('');
+  out(bold(white('  Scores')));
+  out('');
+  out(`  Integration Simplicity:  ${formatScore(result.integrationSimplicity)}/100`);
+  out(`  Agent Readiness:         ${formatScore(result.agentReadiness)}/100`);
+  out('');
+}
+
+function printSubscores(result: ScoreResult): void {
+  out(bold(white('  Integration Simplicity Subscores')));
+  out('');
+  const is = result.integrationSubscores;
+  printSubscore('Parameter Simplicity', is.parameterSimplicity);
+  printSubscore('Schema Simplicity', is.schemaSimplicity);
+  printSubscore('Documentation Quality', is.documentationQuality);
+  printSubscore('Constraint Clarity', is.constraintClarity);
+  printSubscore('Example Coverage', is.exampleCoverage);
+  printSubscore('Error Clarity', is.errorClarity);
+  printSubscore('Workflow Clarity', is.workflowClarity);
+  out('');
+
+  out(bold(white('  Agent Readiness Subscores')));
+  out('');
+  const ar = result.agentSubscores;
+  printSubscore('Documentation Quality', ar.documentationQuality);
+  printSubscore('Constraint Clarity', ar.constraintClarity);
+  printSubscore('Example Coverage', ar.exampleCoverage);
+  printSubscore('Error Clarity', ar.errorClarity);
+  printSubscore('Identifier Clarity', ar.identifierClarity);
+  printSubscore('Workflow Clarity', ar.workflowClarity);
+  printSubscore('Polymorphism Clarity', ar.polymorphismClarity);
+  out('');
+}
+
+function printSubscore(label: string, value: number): void {
+  const pct = Math.round(value * 100);
+  const bar = buildBar(value);
+  out(`  ${label.padEnd(24)} ${bar} ${scoreColor(pct)(pct + '%')}`);
+}
+
+function buildBar(fraction: number): string {
+  const width = 20;
+  const filled = Math.round(fraction * width);
+  return cyan('[' + '\u2588'.repeat(filled) + '\u2591'.repeat(width - filled) + ']');
+}
+
+function printRawMetricsSummary(result: ScoreResult): void {
+  out(bold(white('  Raw Metrics Summary')));
+  out('');
+  out(`  Total operations: ${result.rawMetrics.operationCount}`);
+
+  if (result.rawMetrics.operationCount === 0) {
+    out('');
+    return;
+  }
+
+  let totalParams = 0;
+  let totalDepth = 0;
+  let totalPoly = 0;
+  let totalProps = 0;
+  let opsWithReqExample = 0;
+  let opsWithResExample = 0;
+  let opsWithDescription = 0;
+
+  for (const m of result.rawMetrics.operations.values()) {
+    totalParams += m.parameterCount;
+    totalDepth += Math.max(m.maxRequestSchemaDepth, m.maxResponseSchemaDepth);
+    totalPoly += m.polymorphismCount;
+    totalProps += m.propertyCount;
+    if (m.requestExamplePresent) opsWithReqExample++;
+    if (m.responseExamplePresent) opsWithResExample++;
+    if (m.operationDescriptionPresent) opsWithDescription++;
+  }
+
+  const n = result.rawMetrics.operationCount;
+  out(`  Avg parameters/operation: ${(totalParams / n).toFixed(1)}`);
+  out(`  Avg max schema depth: ${(totalDepth / n).toFixed(1)}`);
+  out(`  Avg polymorphism/operation: ${(totalPoly / n).toFixed(1)}`);
+  out(`  Avg properties/operation: ${(totalProps / n).toFixed(1)}`);
+  out(
+    `  Operations with request examples: ${opsWithReqExample}/${n} (${fmtPct(opsWithReqExample, n)})`
+  );
+  out(
+    `  Operations with response examples: ${opsWithResExample}/${n} (${fmtPct(opsWithResExample, n)})`
+  );
+  out(
+    `  Operations with description: ${opsWithDescription}/${n} (${fmtPct(opsWithDescription, n)})`
+  );
+  out('');
+}
+
+function fmtPct(num: number, denom: number): string {
+  return denom > 0 ? `${Math.round((num / denom) * 100)}%` : 'N/A';
+}
+
+function printHotspots(result: ScoreResult): void {
+  if (result.hotspots.length === 0) {
+    out(bold(white('  No hotspot operations found.')));
+    out('');
+    return;
+  }
+
+  out(bold(white(`  Top ${result.hotspots.length} Hotspot Operations`)));
+  out('');
+
+  for (const hotspot of result.hotspots) {
+    const label = hotspot.operationId
+      ? `${hotspot.method.toUpperCase()} ${hotspot.path} (${hotspot.operationId})`
+      : `${hotspot.method.toUpperCase()} ${hotspot.path}`;
+
+    out(bold(`  ${label}`));
+    out(
+      `    Integration Simplicity: ${formatScore(hotspot.integrationSimplicityScore)}  ` +
+        `Agent Readiness: ${formatScore(hotspot.agentReadinessScore)}`
+    );
+
+    for (const reason of hotspot.reasons) {
+      out(gray(`    - ${reason}`));
+    }
+    out('');
+  }
+}
diff --git a/packages/cli/src/commands/score/hotspots.ts b/packages/cli/src/commands/score/hotspots.ts
new file mode 100644
index 0000000000..ef21a5acad
--- /dev/null
+++ b/packages/cli/src/commands/score/hotspots.ts
@@ -0,0 +1,115 @@
+import { DEFAULT_SCORING_CONSTANTS } from './constants.js';
+import type {
+  DocumentMetrics,
+  HotspotOperation,
+  OperationScores,
+  ScoringConstants,
+} from './types.js';
+
+export function selectTopHotspots(
+  documentMetrics: DocumentMetrics,
+  operationScores: Map<string, OperationScores>,
+  workflowDepths: Map<string, number>,
+  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
+): HotspotOperation[] {
+  const entries: HotspotOperation[] = [];
+
+  for (const [key, scores] of operationScores) {
+    const metrics = documentMetrics.operations.get(key);
+    if (!metrics) continue;
+
+    const reasons = getHotspotReasons(metrics, scores, workflowDepths.get(key) ?? 0, constants);
+    if (reasons.length === 0) continue;
+
+    entries.push({
+      path: metrics.path,
+      method: metrics.method,
+      operationId: metrics.operationId,
+      integrationSimplicityScore: scores.integrationSimplicity,
+      agentReadinessScore: scores.agentReadiness,
+      reasons,
+    });
+  }
+
+  entries.sort((a, b) => {
+    if (a.reasons.length !== b.reasons.length) return b.reasons.length - a.reasons.length;
+    const aAvg = (a.integrationSimplicityScore + a.agentReadinessScore) / 2;
+    const bAvg = (b.integrationSimplicityScore + b.agentReadinessScore) / 2;
+    return aAvg - bAvg;
+  });
+
+  return entries.slice(0, constants.hotspotLimit);
+}
+
+function getHotspotReasons(
+  metrics: {
+    parameterCount: number;
+    maxRequestSchemaDepth: number;
+    maxResponseSchemaDepth: number;
+    polymorphismCount: number;
+    anyOfCount: number;
+    hasDiscriminator: boolean;
+    requestBodyPresent: boolean;
+    requestExamplePresent: boolean;
+    responseExamplePresent: boolean;
+    structuredErrorResponseCount: number;
+    totalErrorResponses: number;
+    operationDescriptionPresent: boolean;
+    paramsWithDescription: number;
+    ambiguousIdentifierCount: number;
+  },
+  scores: OperationScores,
+  workflowDepth: number,
+  constants: ScoringConstants
+): string[] {
+  const { thresholds } = constants;
+  const reasons: string[] = [];
+
+  if (metrics.parameterCount > thresholds.maxParamsGood) {
+    reasons.push(`High parameter count (${metrics.parameterCount})`);
+  }
+
+  const maxDepth = Math.max(metrics.maxRequestSchemaDepth, metrics.maxResponseSchemaDepth);
+  if (maxDepth > thresholds.maxDepthGood) {
+    reasons.push(`Deep schema nesting (depth ${maxDepth})`);
+  }
+
+  if (metrics.anyOfCount > 0 && !metrics.hasDiscriminator) {
+    reasons.push(`Polymorphism (anyOf) without discriminator (${metrics.anyOfCount} anyOf)`);
+  } else if (metrics.polymorphismCount > thresholds.maxPolymorphismGood) {
+    reasons.push(`High polymorphism count (${metrics.polymorphismCount})`);
+  }
+
+  const missingReqExample = metrics.requestBodyPresent && !metrics.requestExamplePresent;
+  const missingResExample = !metrics.responseExamplePresent;
+
+  if (missingReqExample && missingResExample) {
+    reasons.push('Missing request and response examples');
+  } else if (missingReqExample) {
+    reasons.push('Missing request body examples');
+  } else if (missingResExample) {
+    reasons.push('Missing response examples');
+  }
+
+  if (metrics.totalErrorResponses > 0 && metrics.structuredErrorResponseCount === 0) {
+    reasons.push('No structured error responses (4xx/5xx)');
+  }
+
+  if (!metrics.operationDescriptionPresent) {
+    reasons.push('Missing operation description');
+  }
+
+  if (metrics.parameterCount > 0 && metrics.paramsWithDescription === 0) {
+    reasons.push('No parameter descriptions');
+  }
+
+  if (workflowDepth > thresholds.maxWorkflowDepthGood) {
+    reasons.push(`High workflow dependency depth (${workflowDepth})`);
+  }
+
+  if (metrics.ambiguousIdentifierCount > thresholds.maxAmbiguousGood) {
+    reasons.push(`Ambiguous identifiers (${metrics.ambiguousIdentifierCount})`);
+  }
+
+  return reasons;
+}
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
new file mode 100644
index 0000000000..a9caa9969d
--- /dev/null
+++ b/packages/cli/src/commands/score/index.ts
@@ -0,0 +1,145 @@
+import { bundle, detectSpec, logger } from '@redocly/openapi-core';
+import type { OutputFormat } from '@redocly/openapi-core';
+import * as colors from 'colorette';
+import { performance } from 'perf_hooks';
+
+import type { VerifyConfigOptions } from '../../types.js';
+import { getFallbackApisOrExit, printExecutionTime } from '../../utils/miscellaneous.js';
+import type { CommandArgs } from '../../wrapper.js';
+import { collectDocumentMetrics } from './collectors/document-metrics.js';
+import { computeWorkflowDepths } from './collectors/workflow-graph.js';
+import { printScoreJson } from './formatters/json.js';
+import { printScoreStylish } from './formatters/stylish.js';
+import { selectTopHotspots } from './hotspots.js';
+import { computeAllOperationScores, computeDocumentScores } from './scoring.js';
+import type {
+  AgentReadinessSubscores,
+  IntegrationSimplicitySubscores,
+  ScoreResult,
+} from './types.js';
+
+export type ScoreArgv = {
+  api?: string;
+  format: OutputFormat;
+} & VerifyConfigOptions;
+
+export async function handleScore({ argv, config, collectSpecData }: CommandArgs<ScoreArgv>) {
+  const [{ path }] = await getFallbackApisOrExit(argv.api ? [argv.api] : [], config);
+  const { bundle: document } = await bundle({ config, ref: path });
+  collectSpecData?.(document.parsed);
+
+  const specVersion = detectSpec(document.parsed);
+  if (!specVersion.startsWith('oas3')) {
+    logger.error(
+      colors.red(`The score command currently supports only OpenAPI 3.x. Detected: ${specVersion}`)
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const startedAt = performance.now();
+
+  const rawMetrics = collectDocumentMetrics(document.parsed as Record<string, any>);
+  const workflowDepths = computeWorkflowDepths(rawMetrics.operations);
+  const operationScores = computeAllOperationScores(rawMetrics, workflowDepths);
+  const { integrationSimplicity, agentReadiness } = computeDocumentScores(operationScores);
+
+  const hotspots = selectTopHotspots(rawMetrics, operationScores, workflowDepths);
+
+  const avgIntSubscores = averageIntegrationSubscores(operationScores);
+  const avgAgentSubscores = averageAgentSubscores(operationScores);
+
+  const result: ScoreResult = {
+    integrationSimplicity,
+    agentReadiness,
+    integrationSubscores: avgIntSubscores,
+    agentSubscores: avgAgentSubscores,
+    rawMetrics,
+    hotspots,
+    operationScores,
+    workflowDepths,
+  };
+
+  logger.info(`Document: ${colors.magenta(path)} score:\n`);
+
+  switch (argv.format) {
+    case 'json':
+      printScoreJson(result);
+      break;
+    default:
+      printScoreStylish(result);
+      break;
+  }
+
+  printExecutionTime('score', startedAt, path);
+}
+
+function averageIntegrationSubscores(
+  operationScores: Map<string, { integrationSubscores: IntegrationSimplicitySubscores }>
+): IntegrationSimplicitySubscores {
+  const n = operationScores.size || 1;
+  const result: IntegrationSimplicitySubscores = {
+    parameterSimplicity: 0,
+    schemaSimplicity: 0,
+    documentationQuality: 0,
+    constraintClarity: 0,
+    exampleCoverage: 0,
+    errorClarity: 0,
+    workflowClarity: 0,
+  };
+
+  for (const scores of operationScores.values()) {
+    result.parameterSimplicity += scores.integrationSubscores.parameterSimplicity;
+    result.schemaSimplicity += scores.integrationSubscores.schemaSimplicity;
+    result.documentationQuality += scores.integrationSubscores.documentationQuality;
+    result.constraintClarity += scores.integrationSubscores.constraintClarity;
+    result.exampleCoverage += scores.integrationSubscores.exampleCoverage;
+    result.errorClarity += scores.integrationSubscores.errorClarity;
+    result.workflowClarity += scores.integrationSubscores.workflowClarity;
+  }
+
+  result.parameterSimplicity /= n;
+  result.schemaSimplicity /= n;
+  result.documentationQuality /= n;
+  result.constraintClarity /= n;
+  result.exampleCoverage /= n;
+  result.errorClarity /= n;
+  result.workflowClarity /= n;
+
+  return result;
+}
+
+function averageAgentSubscores(
+  operationScores: Map<string, { agentSubscores: AgentReadinessSubscores }>
+): AgentReadinessSubscores {
+  const n = operationScores.size || 1;
+  const result: AgentReadinessSubscores = {
+    documentationQuality: 0,
+    constraintClarity: 0,
+    exampleCoverage: 0,
+    errorClarity: 0,
+    identifierClarity: 0,
+    workflowClarity: 0,
+    polymorphismClarity: 0,
+  };
+
+  for (const scores of operationScores.values()) {
+    result.documentationQuality += scores.agentSubscores.documentationQuality;
+    result.constraintClarity += scores.agentSubscores.constraintClarity;
+    result.exampleCoverage += scores.agentSubscores.exampleCoverage;
+    result.errorClarity += scores.agentSubscores.errorClarity;
+    result.identifierClarity += scores.agentSubscores.identifierClarity;
+    result.workflowClarity += scores.agentSubscores.workflowClarity;
+    result.polymorphismClarity += scores.agentSubscores.polymorphismClarity;
+  }
+
+  result.documentationQuality /= n;
+  result.constraintClarity /= n;
+  result.exampleCoverage /= n;
+  result.errorClarity /= n;
+  result.identifierClarity /= n;
+  result.workflowClarity /= n;
+  result.polymorphismClarity /= n;
+
+  return result;
+}
diff --git a/packages/cli/src/commands/score/scoring.ts b/packages/cli/src/commands/score/scoring.ts
new file mode 100644
index 0000000000..6aeda0f388
--- /dev/null
+++ b/packages/cli/src/commands/score/scoring.ts
@@ -0,0 +1,199 @@
+import { DEFAULT_SCORING_CONSTANTS } from './constants.js';
+import type {
+  AgentReadinessSubscores,
+  DocumentMetrics,
+  IntegrationSimplicitySubscores,
+  OperationMetrics,
+  OperationScores,
+  ScoringConstants,
+} from './types.js';
+
+export function computeOperationIntegrationSubscores(
+  metrics: OperationMetrics,
+  workflowDepth: number,
+  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
+): IntegrationSimplicitySubscores {
+  const { thresholds, weights } = constants;
+
+  const parameterSimplicity = clamp01(1 - metrics.parameterCount / (thresholds.maxParamsGood * 2));
+
+  const maxDepth = Math.max(metrics.maxRequestSchemaDepth, metrics.maxResponseSchemaDepth);
+  const depthPenalty = maxDepth / (thresholds.maxDepthGood * 2);
+  const polyPenalty =
+    effectivePolymorphism(metrics, weights.anyOfPenaltyMultiplier) /
+    (thresholds.maxPolymorphismGood * 3);
+  const schemaSimplicity = clamp01(1 - depthPenalty - polyPenalty);
+
+  const descCount =
+    (metrics.operationDescriptionPresent ? 1 : 0) +
+    metrics.paramsWithDescription +
+    metrics.schemaPropertiesWithDescription;
+  const descTotal = 1 + metrics.parameterCount + metrics.totalSchemaProperties;
+  const documentationQuality = descTotal > 0 ? clamp01(descCount / descTotal) : 1;
+
+  const propCount = metrics.totalSchemaProperties || 1;
+  const constraintClarity = clamp01(metrics.constraintCount / propCount);
+
+  const examplePoints =
+    (metrics.requestExamplePresent ? 1 : 0) + (metrics.responseExamplePresent ? 1 : 0);
+  const exampleTotal = (metrics.requestBodyPresent ? 1 : 0) + 1;
+  const exampleCoverage = clamp01(examplePoints / exampleTotal);
+
+  const errorClarity =
+    metrics.totalErrorResponses > 0
+      ? clamp01(metrics.structuredErrorResponseCount / metrics.totalErrorResponses)
+      : 1;
+
+  const workflowClarity = clamp01(1 - workflowDepth / (thresholds.maxWorkflowDepthGood * 2));
+
+  return {
+    parameterSimplicity,
+    schemaSimplicity,
+    documentationQuality,
+    constraintClarity,
+    exampleCoverage,
+    errorClarity,
+    workflowClarity,
+  };
+}
+
+export function computeOperationAgentSubscores(
+  metrics: OperationMetrics,
+  workflowDepth: number,
+  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
+): AgentReadinessSubscores {
+  const { thresholds, weights } = constants;
+
+  const descCount =
+    (metrics.operationDescriptionPresent ? 1 : 0) +
+    metrics.paramsWithDescription +
+    metrics.schemaPropertiesWithDescription;
+  const descTotal = 1 + metrics.parameterCount + metrics.totalSchemaProperties;
+  const documentationQuality = descTotal > 0 ? clamp01(descCount / descTotal) : 1;
+
+  const propCount = metrics.totalSchemaProperties || 1;
+  const constraintClarity = clamp01(metrics.constraintCount / propCount);
+
+  const examplePoints =
+    (metrics.requestExamplePresent ? 1 : 0) + (metrics.responseExamplePresent ? 1 : 0);
+  const exampleTotal = (metrics.requestBodyPresent ? 1 : 0) + 1;
+  const exampleCoverage = clamp01(examplePoints / exampleTotal);
+
+  const errorClarity =
+    metrics.totalErrorResponses > 0
+      ? clamp01(metrics.structuredErrorResponseCount / metrics.totalErrorResponses)
+      : 1;
+
+  const identifierClarity = clamp01(
+    1 - metrics.ambiguousIdentifierCount / Math.max(thresholds.maxAmbiguousGood + 3, 1)
+  );
+
+  const workflowClarity = clamp01(1 - workflowDepth / (thresholds.maxWorkflowDepthGood * 2));
+
+  const polyScore = effectivePolymorphism(metrics, weights.anyOfPenaltyMultiplier);
+  const polyClarity =
+    polyScore === 0
+      ? 1
+      : metrics.hasDiscriminator
+        ? clamp01(1 - polyScore / (thresholds.maxPolymorphismGood * 4))
+        : clamp01(1 - polyScore / (thresholds.maxPolymorphismGood * 2));
+
+  return {
+    documentationQuality,
+    constraintClarity,
+    exampleCoverage,
+    errorClarity,
+    identifierClarity,
+    workflowClarity,
+    polymorphismClarity: polyClarity,
+  };
+}
+
+export function computeIntegrationSimplicity(
+  subscores: IntegrationSimplicitySubscores,
+  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
+): number {
+  const w = constants.weights.integration;
+  const raw =
+    subscores.parameterSimplicity * w.parameterSimplicity +
+    subscores.schemaSimplicity * w.schemaSimplicity +
+    subscores.documentationQuality * w.documentationQuality +
+    subscores.constraintClarity * w.constraintClarity +
+    subscores.exampleCoverage * w.exampleCoverage +
+    subscores.errorClarity * w.errorClarity +
+    subscores.workflowClarity * w.workflowClarity;
+  return round(clamp01(raw) * 100);
+}
+
+export function computeAgentReadiness(
+  subscores: AgentReadinessSubscores,
+  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
+): number {
+  const w = constants.weights.agent;
+  const raw =
+    subscores.documentationQuality * w.documentationQuality +
+    subscores.constraintClarity * w.constraintClarity +
+    subscores.exampleCoverage * w.exampleCoverage +
+    subscores.errorClarity * w.errorClarity +
+    subscores.identifierClarity * w.identifierClarity +
+    subscores.workflowClarity * w.workflowClarity +
+    subscores.polymorphismClarity * w.polymorphismClarity;
+  return round(clamp01(raw) * 100);
+}
+
+export function computeAllOperationScores(
+  documentMetrics: DocumentMetrics,
+  workflowDepths: Map<string, number>,
+  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
+): Map<string, OperationScores> {
+  const result = new Map<string, OperationScores>();
+
+  for (const [key, metrics] of documentMetrics.operations) {
+    const depth = workflowDepths.get(key) ?? 0;
+    const integrationSubscores = computeOperationIntegrationSubscores(metrics, depth, constants);
+    const agentSubscores = computeOperationAgentSubscores(metrics, depth, constants);
+
+    result.set(key, {
+      integrationSimplicity: computeIntegrationSimplicity(integrationSubscores, constants),
+      agentReadiness: computeAgentReadiness(agentSubscores, constants),
+      integrationSubscores,
+      agentSubscores,
+    });
+  }
+
+  return result;
+}
+
+export function computeDocumentScores(operationScores: Map<string, OperationScores>): {
+  integrationSimplicity: number;
+  agentReadiness: number;
+} {
+  if (operationScores.size === 0) {
+    return { integrationSimplicity: 100, agentReadiness: 100 };
+  }
+
+  let sumInt = 0;
+  let sumAgent = 0;
+  for (const scores of operationScores.values()) {
+    sumInt += scores.integrationSimplicity;
+    sumAgent += scores.agentReadiness;
+  }
+
+  return {
+    integrationSimplicity: round(sumInt / operationScores.size),
+    agentReadiness: round(sumAgent / operationScores.size),
+  };
+}
+
+function effectivePolymorphism(metrics: OperationMetrics, anyOfMultiplier: number): number {
+  const otherPoly = metrics.polymorphismCount - metrics.anyOfCount;
+  return otherPoly + metrics.anyOfCount * anyOfMultiplier;
+}
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function round(value: number): number {
+  return Math.round(value * 10) / 10;
+}
diff --git a/packages/cli/src/commands/score/types.ts b/packages/cli/src/commands/score/types.ts
new file mode 100644
index 0000000000..b05f7bbe75
--- /dev/null
+++ b/packages/cli/src/commands/score/types.ts
@@ -0,0 +1,140 @@
+export type RefResolver = (ref: string) => Record<string, any> | undefined;
+
+export interface SchemaMetrics {
+  depth: number;
+  propertyCount: number;
+  oneOfCount: number;
+  anyOfCount: number;
+  allOfCount: number;
+  hasDiscriminator: boolean;
+  propertiesWithDescription: number;
+  totalProperties: number;
+  constraintCount: number;
+  writableTopLevelFieldCount: number;
+  propertiesWithExamples: number;
+}
+
+export interface OperationMetrics {
+  path: string;
+  method: string;
+  operationId?: string;
+
+  parameterCount: number;
+  requiredParameterCount: number;
+  paramsWithDescription: number;
+  requestBodyPresent: boolean;
+
+  topLevelWritableFieldCount: number;
+  maxRequestSchemaDepth: number;
+  maxResponseSchemaDepth: number;
+
+  polymorphismCount: number;
+  anyOfCount: number;
+  hasDiscriminator: boolean;
+  propertyCount: number;
+
+  operationDescriptionPresent: boolean;
+  schemaPropertiesWithDescription: number;
+  totalSchemaProperties: number;
+
+  constraintCount: number;
+
+  requestExamplePresent: boolean;
+  responseExamplePresent: boolean;
+
+  structuredErrorResponseCount: number;
+  totalErrorResponses: number;
+
+  ambiguousIdentifierCount: number;
+
+  refsUsed: Set<string>;
+}
+
+export interface DocumentMetrics {
+  operationCount: number;
+  operations: Map<string, OperationMetrics>;
+}
+
+export interface IntegrationSimplicitySubscores {
+  parameterSimplicity: number;
+  schemaSimplicity: number;
+  documentationQuality: number;
+  constraintClarity: number;
+  exampleCoverage: number;
+  errorClarity: number;
+  workflowClarity: number;
+}
+
+export interface AgentReadinessSubscores {
+  documentationQuality: number;
+  constraintClarity: number;
+  exampleCoverage: number;
+  errorClarity: number;
+  identifierClarity: number;
+  workflowClarity: number;
+  polymorphismClarity: number;
+}
+
+export interface OperationScores {
+  integrationSimplicity: number;
+  agentReadiness: number;
+  integrationSubscores: IntegrationSimplicitySubscores;
+  agentSubscores: AgentReadinessSubscores;
+}
+
+export interface HotspotOperation {
+  path: string;
+  method: string;
+  operationId?: string;
+  integrationSimplicityScore: number;
+  agentReadinessScore: number;
+  reasons: string[];
+}
+
+export interface ScoreResult {
+  integrationSimplicity: number;
+  agentReadiness: number;
+  integrationSubscores: IntegrationSimplicitySubscores;
+  agentSubscores: AgentReadinessSubscores;
+  rawMetrics: DocumentMetrics;
+  hotspots: HotspotOperation[];
+  operationScores: Map<string, OperationScores>;
+  workflowDepths: Map<string, number>;
+}
+
+export interface ScoringThresholds {
+  maxParamsGood: number;
+  maxDepthGood: number;
+  maxPolymorphismGood: number;
+  maxPropertiesGood: number;
+  maxWorkflowDepthGood: number;
+  maxAmbiguousGood: number;
+}
+
+export interface ScoringWeights {
+  integration: {
+    parameterSimplicity: number;
+    schemaSimplicity: number;
+    documentationQuality: number;
+    constraintClarity: number;
+    exampleCoverage: number;
+    errorClarity: number;
+    workflowClarity: number;
+  };
+  agent: {
+    documentationQuality: number;
+    constraintClarity: number;
+    exampleCoverage: number;
+    errorClarity: number;
+    identifierClarity: number;
+    workflowClarity: number;
+    polymorphismClarity: number;
+  };
+  anyOfPenaltyMultiplier: number;
+}
+
+export interface ScoringConstants {
+  thresholds: ScoringThresholds;
+  weights: ScoringWeights;
+  hotspotLimit: number;
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index eed24c88c7..2f0ec4c011 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -22,6 +22,7 @@ import { PRODUCT_PLANS } from './commands/preview-project/constants.js';
 import { previewProject } from './commands/preview-project/index.js';
 import { handleRespect, type RespectArgv } from './commands/respect/index.js';
 import { validateMtlsCommandOption } from './commands/respect/mtls/validate-mtls-command-option.js';
+import { handleScore } from './commands/score/index.js';
 import { handleScorecardClassic } from './commands/scorecard-classic/index.js';
 import type {
   ScorecardClassicArgv,
@@ -73,6 +74,30 @@ yargs(hideBin(process.argv))
       commandWrapper(handleStats)(argv);
     }
   )
+  .command(
+    'score [api]',
+    'Score an API description for integration simplicity and agent readiness.',
+    (yargs) =>
+      yargs
+        .env('REDOCLY_CLI_SCORE')
+        .positional('api', { type: 'string' })
+        .option({
+          config: { description: 'Path to the config file.', type: 'string' },
+          'lint-config': {
+            description: 'Severity level for config file linting.',
+            choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+            default: 'warn' as RuleSeverity,
+          },
+          format: {
+            description: 'Use a specific output format.',
+            choices: ['stylish', 'json', 'markdown'] as ReadonlyArray<OutputFormat>,
+            default: 'stylish' as OutputFormat,
+          },
+        }),
+    (argv) => {
+      commandWrapper(handleScore)(argv);
+    }
+  )
   .command(
     'split [api]',
     'Split an API description into a multi-file structure.',

From 7c277f9e7e9a22e2de34156d3caff48cb34ea8ab Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Wed, 11 Mar 2026 20:39:36 -0500
Subject: [PATCH 02/22] chore: add more tests

---
 docs/@v2/v2.sidebars.yaml                     |   2 +
 .../score/__tests__/document-metrics.test.ts  | 413 ++++++++++++++++++
 .../score/__tests__/formatters.test.ts        | 221 ++++++++++
 .../commands/score/__tests__/hotspots.test.ts | 304 +++++++++++++
 .../commands/score/__tests__/index.test.ts    | 196 +++++++++
 .../commands/score/__tests__/scoring.test.ts  | 143 ++++++
 .../score/__tests__/workflow-graph.test.ts    |  89 ++++
 7 files changed, 1368 insertions(+)
 create mode 100644 packages/cli/src/commands/score/__tests__/document-metrics.test.ts
 create mode 100644 packages/cli/src/commands/score/__tests__/formatters.test.ts
 create mode 100644 packages/cli/src/commands/score/__tests__/hotspots.test.ts
 create mode 100644 packages/cli/src/commands/score/__tests__/index.test.ts
 create mode 100644 packages/cli/src/commands/score/__tests__/workflow-graph.test.ts

diff --git a/docs/@v2/v2.sidebars.yaml b/docs/@v2/v2.sidebars.yaml
index 80232d684b..2e11a05018 100644
--- a/docs/@v2/v2.sidebars.yaml
+++ b/docs/@v2/v2.sidebars.yaml
@@ -34,6 +34,8 @@
           page: commands/push-status.md
         - label: respect
           page: commands/respect.md
+        - label: score
+          page: commands/score.md
         - label: scorecard-classic
           page: commands/scorecard-classic.md
         - label: split
diff --git a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
new file mode 100644
index 0000000000..bcb28577e8
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
@@ -0,0 +1,413 @@
+import { collectDocumentMetrics } from '../collectors/document-metrics.js';
+
+function makeDoc(paths: Record<string, any>, components?: Record<string, any>) {
+  return {
+    openapi: '3.0.0',
+    info: { title: 'Test', version: '1.0.0' },
+    paths,
+    ...(components ? { components } : {}),
+  };
+}
+
+describe('collectDocumentMetrics', () => {
+  it('should return zero operations for empty paths', () => {
+    const result = collectDocumentMetrics(makeDoc({}));
+    expect(result.operationCount).toBe(0);
+    expect(result.operations.size).toBe(0);
+  });
+
+  it('should count operations across methods', () => {
+    const doc = makeDoc({
+      '/items': {
+        get: { operationId: 'listItems', responses: { '200': { description: 'OK' } } },
+        post: { operationId: 'createItem', responses: { '201': { description: 'Created' } } },
+      },
+      '/items/{id}': {
+        get: { operationId: 'getItem', responses: { '200': { description: 'OK' } } },
+        delete: { operationId: 'deleteItem', responses: { '204': { description: 'Deleted' } } },
+      },
+    });
+    const result = collectDocumentMetrics(doc);
+    expect(result.operationCount).toBe(4);
+  });
+
+  it('should use operationId as key when present', () => {
+    const doc = makeDoc({
+      '/items': {
+        get: { operationId: 'listItems', responses: { '200': { description: 'OK' } } },
+      },
+    });
+    const result = collectDocumentMetrics(doc);
+    expect(result.operations.has('listItems')).toBe(true);
+  });
+
+  it('should fall back to METHOD path as key when no operationId', () => {
+    const doc = makeDoc({
+      '/items': {
+        get: { responses: { '200': { description: 'OK' } } },
+      },
+    });
+    const result = collectDocumentMetrics(doc);
+    expect(result.operations.has('GET /items')).toBe(true);
+  });
+
+  describe('parameter counting', () => {
+    it('should count resolved parameters via $ref', () => {
+      const doc = makeDoc(
+        {
+          '/items': {
+            get: {
+              operationId: 'listItems',
+              parameters: [
+                { $ref: '#/components/parameters/Limit' },
+                { $ref: '#/components/parameters/Offset' },
+              ],
+              responses: { '200': { description: 'OK' } },
+            },
+          },
+        },
+        {
+          parameters: {
+            Limit: {
+              name: 'limit',
+              in: 'query',
+              required: false,
+              description: 'Max items',
+              schema: { type: 'integer' },
+            },
+            Offset: { name: 'offset', in: 'query', schema: { type: 'integer' } },
+          },
+        }
+      );
+      const result = collectDocumentMetrics(doc);
+      const op = result.operations.get('listItems')!;
+      expect(op.parameterCount).toBe(2);
+      expect(op.paramsWithDescription).toBe(1);
+    });
+
+    it('should merge path-level and operation-level parameters', () => {
+      const doc = makeDoc({
+        '/items/{id}': {
+          parameters: [{ name: 'id', in: 'path', required: true, description: 'Item ID' }],
+          get: {
+            operationId: 'getItem',
+            parameters: [{ name: 'fields', in: 'query' }],
+            responses: { '200': { description: 'OK' } },
+          },
+        },
+      });
+      const op = collectDocumentMetrics(doc).operations.get('getItem')!;
+      expect(op.parameterCount).toBe(2);
+      expect(op.requiredParameterCount).toBe(1);
+    });
+
+    it('should let operation params override path params with same name+in', () => {
+      const doc = makeDoc({
+        '/items/{id}': {
+          parameters: [{ name: 'id', in: 'path', required: true }],
+          get: {
+            operationId: 'getItem',
+            parameters: [{ name: 'id', in: 'path', required: true, description: 'Overridden' }],
+            responses: { '200': { description: 'OK' } },
+          },
+        },
+      });
+      const op = collectDocumentMetrics(doc).operations.get('getItem')!;
+      expect(op.parameterCount).toBe(1);
+      expect(op.paramsWithDescription).toBe(1);
+    });
+
+    it('should detect ambiguous params without description', () => {
+      const doc = makeDoc({
+        '/items': {
+          get: {
+            operationId: 'listItems',
+            parameters: [
+              { name: 'id', in: 'query' },
+              { name: 'type', in: 'query' },
+              { name: 'category', in: 'query', description: 'Filter category' },
+            ],
+            responses: { '200': { description: 'OK' } },
+          },
+        },
+      });
+      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      expect(op.ambiguousIdentifierCount).toBe(2);
+    });
+  });
+
+  describe('request body', () => {
+    it('should detect request body and resolve schema $ref', () => {
+      const doc = makeDoc(
+        {
+          '/items': {
+            post: {
+              operationId: 'createItem',
+              requestBody: {
+                content: {
+                  'application/json': {
+                    schema: { $ref: '#/components/schemas/Item' },
+                    example: { name: 'test' },
+                  },
+                },
+              },
+              responses: { '201': { description: 'Created' } },
+            },
+          },
+        },
+        {
+          schemas: {
+            Item: {
+              type: 'object',
+              properties: {
+                name: { type: 'string', description: 'Item name', minLength: 1 },
+                price: { type: 'integer', minimum: 0 },
+              },
+            },
+          },
+        }
+      );
+      const op = collectDocumentMetrics(doc).operations.get('createItem')!;
+      expect(op.requestBodyPresent).toBe(true);
+      expect(op.requestExamplePresent).toBe(true);
+      expect(op.propertyCount).toBe(2);
+      expect(op.constraintCount).toBe(2);
+      expect(op.totalSchemaProperties).toBe(2);
+      expect(op.schemaPropertiesWithDescription).toBe(1);
+    });
+
+    it('should resolve requestBody $ref', () => {
+      const doc = makeDoc(
+        {
+          '/items': {
+            post: {
+              operationId: 'createItem',
+              requestBody: { $ref: '#/components/requestBodies/ItemBody' },
+              responses: { '201': { description: 'Created' } },
+            },
+          },
+        },
+        {
+          requestBodies: {
+            ItemBody: {
+              content: {
+                'application/json': {
+                  schema: { type: 'object', properties: { name: { type: 'string' } } },
+                },
+              },
+            },
+          },
+        }
+      );
+      const op = collectDocumentMetrics(doc).operations.get('createItem')!;
+      expect(op.requestBodyPresent).toBe(true);
+      expect(op.propertyCount).toBe(1);
+    });
+  });
+
+  describe('responses', () => {
+    it('should resolve response $refs and count structured errors', () => {
+      const doc = makeDoc(
+        {
+          '/items': {
+            get: {
+              operationId: 'listItems',
+              responses: {
+                '200': { description: 'OK' },
+                '400': { $ref: '#/components/responses/BadRequest' },
+                '500': { $ref: '#/components/responses/ServerError' },
+              },
+            },
+          },
+        },
+        {
+          responses: {
+            BadRequest: {
+              description: 'Bad request',
+              content: { 'application/json': { schema: { type: 'object' } } },
+            },
+            ServerError: {
+              description: 'Server error',
+              content: { 'application/json': { schema: { type: 'object' } } },
+            },
+          },
+        }
+      );
+      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      expect(op.totalErrorResponses).toBe(2);
+      expect(op.structuredErrorResponseCount).toBe(2);
+    });
+
+    it('should count description-only error responses as structured', () => {
+      const doc = makeDoc({
+        '/items': {
+          get: {
+            operationId: 'listItems',
+            responses: {
+              '200': { description: 'OK' },
+              '404': { description: 'Not found' },
+            },
+          },
+        },
+      });
+      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      expect(op.totalErrorResponses).toBe(1);
+      expect(op.structuredErrorResponseCount).toBe(1);
+    });
+
+    it('should count default as error response', () => {
+      const doc = makeDoc({
+        '/items': {
+          get: {
+            operationId: 'listItems',
+            responses: {
+              '200': { description: 'OK' },
+              default: { description: 'Error' },
+            },
+          },
+        },
+      });
+      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      expect(op.totalErrorResponses).toBe(1);
+    });
+
+    it('should detect response examples and compute schema depth', () => {
+      const doc = makeDoc({
+        '/items': {
+          get: {
+            operationId: 'listItems',
+            responses: {
+              '200': {
+                description: 'OK',
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'object',
+                      properties: {
+                        items: {
+                          type: 'array',
+                          items: {
+                            type: 'object',
+                            properties: { name: { type: 'string' } },
+                          },
+                        },
+                      },
+                    },
+                    example: { items: [{ name: 'test' }] },
+                  },
+                },
+              },
+            },
+          },
+        },
+      });
+      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      expect(op.responseExamplePresent).toBe(true);
+      expect(op.maxResponseSchemaDepth).toBe(3);
+    });
+  });
+
+  describe('schema property examples as coverage', () => {
+    it('should count schema property examples towards response example coverage', () => {
+      const doc = makeDoc(
+        {
+          '/items': {
+            get: {
+              operationId: 'listItems',
+              responses: {
+                '200': {
+                  description: 'OK',
+                  content: {
+                    'application/json': {
+                      schema: { $ref: '#/components/schemas/Item' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+        {
+          schemas: {
+            Item: {
+              type: 'object',
+              properties: {
+                id: { type: 'string', example: 'abc123' },
+              },
+            },
+          },
+        }
+      );
+      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      expect(op.responseExamplePresent).toBe(true);
+    });
+  });
+
+  describe('description and misc', () => {
+    it('should detect operation description presence', () => {
+      const doc = makeDoc({
+        '/a': {
+          get: {
+            operationId: 'withDesc',
+            description: 'Has description',
+            responses: { '200': { description: 'OK' } },
+          },
+        },
+        '/b': {
+          get: {
+            operationId: 'noDesc',
+            responses: { '200': { description: 'OK' } },
+          },
+        },
+      });
+      const metrics = collectDocumentMetrics(doc);
+      expect(metrics.operations.get('withDesc')!.operationDescriptionPresent).toBe(true);
+      expect(metrics.operations.get('noDesc')!.operationDescriptionPresent).toBe(false);
+    });
+
+    it('should collect refs used across operations', () => {
+      const doc = makeDoc(
+        {
+          '/items': {
+            get: {
+              operationId: 'listItems',
+              responses: {
+                '200': {
+                  description: 'OK',
+                  content: {
+                    'application/json': { schema: { $ref: '#/components/schemas/Item' } },
+                  },
+                },
+              },
+            },
+            post: {
+              operationId: 'createItem',
+              requestBody: {
+                content: { 'application/json': { schema: { $ref: '#/components/schemas/Item' } } },
+              },
+              responses: { '201': { description: 'Created' } },
+            },
+          },
+        },
+        { schemas: { Item: { type: 'object' } } }
+      );
+      const metrics = collectDocumentMetrics(doc);
+      expect(metrics.operations.get('listItems')!.refsUsed.has('#/components/schemas/Item')).toBe(
+        true
+      );
+      expect(metrics.operations.get('createItem')!.refsUsed.has('#/components/schemas/Item')).toBe(
+        true
+      );
+    });
+
+    it('should handle missing/null paths gracefully', () => {
+      expect(collectDocumentMetrics({ openapi: '3.0.0' }).operationCount).toBe(0);
+      expect(collectDocumentMetrics({ openapi: '3.0.0', paths: null }).operationCount).toBe(0);
+    });
+
+    it('should skip non-object path items', () => {
+      const doc = makeDoc({ '/a': null, '/b': 'invalid' });
+      expect(collectDocumentMetrics(doc).operationCount).toBe(0);
+    });
+  });
+});
diff --git a/packages/cli/src/commands/score/__tests__/formatters.test.ts b/packages/cli/src/commands/score/__tests__/formatters.test.ts
new file mode 100644
index 0000000000..185ced54ef
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/formatters.test.ts
@@ -0,0 +1,221 @@
+import { printScoreJson } from '../formatters/json.js';
+import { printScoreStylish } from '../formatters/stylish.js';
+import type { ScoreResult } from '../types.js';
+
+vi.mock('@redocly/openapi-core', () => ({
+  logger: { output: vi.fn() },
+}));
+
+import { logger } from '@redocly/openapi-core';
+const mockOutput = vi.mocked(logger.output);
+
+function makeResult(overrides: Partial<ScoreResult> = {}): ScoreResult {
+  return {
+    integrationSimplicity: 75,
+    agentReadiness: 60,
+    integrationSubscores: {
+      parameterSimplicity: 0.8,
+      schemaSimplicity: 0.7,
+      documentationQuality: 0.9,
+      constraintClarity: 0.5,
+      exampleCoverage: 0.6,
+      errorClarity: 1.0,
+      workflowClarity: 0.8,
+    },
+    agentSubscores: {
+      documentationQuality: 0.9,
+      constraintClarity: 0.5,
+      exampleCoverage: 0.6,
+      errorClarity: 1.0,
+      identifierClarity: 0.8,
+      workflowClarity: 0.8,
+      polymorphismClarity: 1.0,
+    },
+    rawMetrics: {
+      operationCount: 2,
+      operations: new Map([
+        [
+          'getItems',
+          {
+            path: '/items',
+            method: 'get',
+            operationId: 'getItems',
+            parameterCount: 2,
+            requiredParameterCount: 0,
+            paramsWithDescription: 1,
+            requestBodyPresent: false,
+            topLevelWritableFieldCount: 0,
+            maxRequestSchemaDepth: 0,
+            maxResponseSchemaDepth: 2,
+            polymorphismCount: 0,
+            anyOfCount: 0,
+            hasDiscriminator: false,
+            propertyCount: 3,
+            operationDescriptionPresent: true,
+            schemaPropertiesWithDescription: 2,
+            totalSchemaProperties: 3,
+            constraintCount: 1,
+            requestExamplePresent: false,
+            responseExamplePresent: true,
+            structuredErrorResponseCount: 1,
+            totalErrorResponses: 1,
+            ambiguousIdentifierCount: 0,
+            refsUsed: new Set(),
+          },
+        ],
+        [
+          'createItem',
+          {
+            path: '/items',
+            method: 'post',
+            operationId: 'createItem',
+            parameterCount: 0,
+            requiredParameterCount: 0,
+            paramsWithDescription: 0,
+            requestBodyPresent: true,
+            topLevelWritableFieldCount: 3,
+            maxRequestSchemaDepth: 1,
+            maxResponseSchemaDepth: 1,
+            polymorphismCount: 0,
+            anyOfCount: 0,
+            hasDiscriminator: false,
+            propertyCount: 5,
+            operationDescriptionPresent: false,
+            schemaPropertiesWithDescription: 2,
+            totalSchemaProperties: 5,
+            constraintCount: 2,
+            requestExamplePresent: true,
+            responseExamplePresent: true,
+            structuredErrorResponseCount: 1,
+            totalErrorResponses: 1,
+            ambiguousIdentifierCount: 0,
+            refsUsed: new Set(),
+          },
+        ],
+      ]),
+    },
+    hotspots: [
+      {
+        path: '/items',
+        method: 'post',
+        operationId: 'createItem',
+        integrationSimplicityScore: 65,
+        agentReadinessScore: 55,
+        reasons: ['Missing operation description'],
+      },
+    ],
+    operationScores: new Map(),
+    workflowDepths: new Map(),
+    ...overrides,
+  };
+}
+
+describe('printScoreStylish', () => {
+  beforeEach(() => {
+    mockOutput.mockClear();
+  });
+
+  it('outputs main scores', () => {
+    printScoreStylish(makeResult());
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('Integration Simplicity');
+    expect(output).toContain('Agent Readiness');
+  });
+
+  it('outputs subscores', () => {
+    printScoreStylish(makeResult());
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('Parameter Simplicity');
+    expect(output).toContain('Schema Simplicity');
+    expect(output).toContain('Documentation Quality');
+    expect(output).toContain('Identifier Clarity');
+    expect(output).toContain('Polymorphism Clarity');
+  });
+
+  it('outputs raw metrics summary', () => {
+    printScoreStylish(makeResult());
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('Total operations: 2');
+    expect(output).toContain('Avg parameters/operation');
+  });
+
+  it('outputs hotspots', () => {
+    printScoreStylish(makeResult());
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('Hotspot Operations');
+    expect(output).toContain('POST /items');
+    expect(output).toContain('Missing operation description');
+  });
+
+  it('outputs no hotspot message when empty', () => {
+    printScoreStylish(makeResult({ hotspots: [] }));
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('No hotspot operations found');
+  });
+
+  it('handles zero operations in raw metrics', () => {
+    printScoreStylish(
+      makeResult({
+        rawMetrics: { operationCount: 0, operations: new Map() },
+        hotspots: [],
+      })
+    );
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('Total operations: 0');
+    expect(output).not.toContain('Avg parameters');
+  });
+
+  it('appends newline to every output call', () => {
+    printScoreStylish(makeResult());
+    for (const call of mockOutput.mock.calls) {
+      expect(call[0]).toMatch(/\n$/);
+    }
+  });
+});
+
+describe('printScoreJson', () => {
+  beforeEach(() => {
+    mockOutput.mockClear();
+  });
+
+  it('outputs valid JSON', () => {
+    printScoreJson(makeResult());
+    const output = mockOutput.mock.calls[0][0];
+    const parsed = JSON.parse(output);
+    expect(parsed.integrationSimplicity).toBe(75);
+    expect(parsed.agentReadiness).toBe(60);
+  });
+
+  it('includes operations as plain object', () => {
+    printScoreJson(makeResult());
+    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
+    expect(parsed.rawMetrics.operations.getItems).toBeDefined();
+    expect(parsed.rawMetrics.operations.getItems.path).toBe('/items');
+  });
+
+  it('includes hotspots', () => {
+    printScoreJson(makeResult());
+    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
+    expect(parsed.hotspots.length).toBe(1);
+    expect(parsed.hotspots[0].reasons).toContain('Missing operation description');
+  });
+
+  it('includes subscores', () => {
+    printScoreJson(makeResult());
+    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
+    expect(parsed.integrationSubscores.parameterSimplicity).toBe(0.8);
+    expect(parsed.agentSubscores.polymorphismClarity).toBe(1.0);
+  });
+
+  it('includes workflow depths as object', () => {
+    const result = makeResult();
+    result.workflowDepths = new Map([
+      ['opA', 2],
+      ['opB', 0],
+    ]);
+    printScoreJson(result);
+    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
+    expect(parsed.workflowDepths.opA).toBe(2);
+    expect(parsed.workflowDepths.opB).toBe(0);
+  });
+});
diff --git a/packages/cli/src/commands/score/__tests__/hotspots.test.ts b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
new file mode 100644
index 0000000000..a348f79294
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
@@ -0,0 +1,304 @@
+import { DEFAULT_SCORING_CONSTANTS } from '../constants.js';
+import { selectTopHotspots } from '../hotspots.js';
+import type { DocumentMetrics, OperationMetrics, OperationScores } from '../types.js';
+
+function makeMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetrics {
+  return {
+    path: '/test',
+    method: 'get',
+    parameterCount: 0,
+    requiredParameterCount: 0,
+    paramsWithDescription: 0,
+    requestBodyPresent: false,
+    topLevelWritableFieldCount: 0,
+    maxRequestSchemaDepth: 0,
+    maxResponseSchemaDepth: 0,
+    polymorphismCount: 0,
+    anyOfCount: 0,
+    hasDiscriminator: false,
+    propertyCount: 0,
+    operationDescriptionPresent: true,
+    schemaPropertiesWithDescription: 0,
+    totalSchemaProperties: 0,
+    constraintCount: 0,
+    requestExamplePresent: false,
+    responseExamplePresent: true,
+    structuredErrorResponseCount: 0,
+    totalErrorResponses: 0,
+    ambiguousIdentifierCount: 0,
+    refsUsed: new Set(),
+    ...overrides,
+  };
+}
+
+function makeScores(overrides: Partial<OperationScores> = {}): OperationScores {
+  return {
+    integrationSimplicity: 80,
+    agentReadiness: 80,
+    integrationSubscores: {
+      parameterSimplicity: 1,
+      schemaSimplicity: 1,
+      documentationQuality: 1,
+      constraintClarity: 1,
+      exampleCoverage: 1,
+      errorClarity: 1,
+      workflowClarity: 1,
+    },
+    agentSubscores: {
+      documentationQuality: 1,
+      constraintClarity: 1,
+      exampleCoverage: 1,
+      errorClarity: 1,
+      identifierClarity: 1,
+      workflowClarity: 1,
+      polymorphismClarity: 1,
+    },
+    ...overrides,
+  };
+}
+
+describe('selectTopHotspots', () => {
+  it('returns empty array when no operations have issues', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([['op1', makeMetrics()]]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const depths = new Map([['op1', 0]]);
+    const result = selectTopHotspots(docMetrics, opScores, depths);
+    expect(result).toEqual([]);
+  });
+
+  it('detects high parameter count', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([['op1', makeMetrics({ parameterCount: 10 })]]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result.length).toBe(1);
+    expect(result[0].reasons).toContain('High parameter count (10)');
+  });
+
+  it('detects deep schema nesting', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([['op1', makeMetrics({ maxResponseSchemaDepth: 10 })]]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result.length).toBe(1);
+    expect(result[0].reasons[0]).toMatch(/Deep schema nesting/);
+  });
+
+  it('detects anyOf without discriminator', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([
+        ['op1', makeMetrics({ anyOfCount: 2, polymorphismCount: 2, hasDiscriminator: false })],
+      ]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('Polymorphism (anyOf) without discriminator (2 anyOf)');
+  });
+
+  it('detects high polymorphism count with discriminator', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([
+        [
+          'op1',
+          makeMetrics({
+            anyOfCount: 0,
+            polymorphismCount: 5,
+            hasDiscriminator: true,
+          }),
+        ],
+      ]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('High polymorphism count (5)');
+  });
+
+  it('detects missing request and response examples for POST with body', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([
+        [
+          'op1',
+          makeMetrics({
+            method: 'post',
+            requestBodyPresent: true,
+            requestExamplePresent: false,
+            responseExamplePresent: false,
+          }),
+        ],
+      ]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('Missing request and response examples');
+  });
+
+  it('detects missing request body examples only', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([
+        [
+          'op1',
+          makeMetrics({
+            requestBodyPresent: true,
+            requestExamplePresent: false,
+            responseExamplePresent: true,
+          }),
+        ],
+      ]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('Missing request body examples');
+  });
+
+  it('does NOT flag missing request example for GET (no body)', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([
+        [
+          'op1',
+          makeMetrics({
+            method: 'get',
+            requestBodyPresent: false,
+            requestExamplePresent: false,
+            responseExamplePresent: true,
+          }),
+        ],
+      ]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result).toEqual([]);
+  });
+
+  it('detects missing response examples only', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([['op1', makeMetrics({ responseExamplePresent: false })]]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('Missing response examples');
+  });
+
+  it('detects no structured error responses', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([
+        ['op1', makeMetrics({ totalErrorResponses: 2, structuredErrorResponseCount: 0 })],
+      ]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('No structured error responses (4xx/5xx)');
+  });
+
+  it('detects missing operation description', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([['op1', makeMetrics({ operationDescriptionPresent: false })]]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('Missing operation description');
+  });
+
+  it('detects no parameter descriptions', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([['op1', makeMetrics({ parameterCount: 3, paramsWithDescription: 0 })]]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('No parameter descriptions');
+  });
+
+  it('detects high workflow dependency depth', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([['op1', makeMetrics()]]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 5]]));
+    expect(result[0].reasons).toContain('High workflow dependency depth (5)');
+  });
+
+  it('detects ambiguous identifiers', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 1,
+      operations: new Map([['op1', makeMetrics({ ambiguousIdentifierCount: 3 })]]),
+    };
+    const opScores = new Map([['op1', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 0]]));
+    expect(result[0].reasons).toContain('Ambiguous identifiers (3)');
+  });
+
+  it('sorts by reasons.length desc then by avg score asc', () => {
+    const manyReasons = makeMetrics({
+      parameterCount: 10,
+      operationDescriptionPresent: false,
+      responseExamplePresent: false,
+      path: '/many',
+    });
+    const fewerReasons = makeMetrics({
+      parameterCount: 10,
+      path: '/fewer',
+    });
+
+    const docMetrics: DocumentMetrics = {
+      operationCount: 2,
+      operations: new Map([
+        ['opFewer', fewerReasons],
+        ['opMany', manyReasons],
+      ]),
+    };
+    const opScores = new Map([
+      ['opFewer', makeScores({ integrationSimplicity: 90, agentReadiness: 90 })],
+      ['opMany', makeScores({ integrationSimplicity: 90, agentReadiness: 90 })],
+    ]);
+    const result = selectTopHotspots(
+      docMetrics,
+      opScores,
+      new Map([
+        ['opFewer', 0],
+        ['opMany', 0],
+      ])
+    );
+    expect(result[0].path).toBe('/many');
+  });
+
+  it('respects hotspotLimit', () => {
+    const ops = new Map<string, OperationMetrics>();
+    const scores = new Map<string, OperationScores>();
+    const depths = new Map<string, number>();
+    for (let i = 0; i < 20; i++) {
+      const key = `op${i}`;
+      ops.set(key, makeMetrics({ parameterCount: 10, path: `/path${i}` }));
+      scores.set(key, makeScores());
+      depths.set(key, 0);
+    }
+    const docMetrics: DocumentMetrics = { operationCount: 20, operations: ops };
+    const result = selectTopHotspots(docMetrics, scores, depths, DEFAULT_SCORING_CONSTANTS);
+    expect(result.length).toBe(10);
+  });
+
+  it('skips operations not found in documentMetrics', () => {
+    const docMetrics: DocumentMetrics = {
+      operationCount: 0,
+      operations: new Map(),
+    };
+    const opScores = new Map([['missing', makeScores()]]);
+    const result = selectTopHotspots(docMetrics, opScores, new Map());
+    expect(result).toEqual([]);
+  });
+});
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
new file mode 100644
index 0000000000..ef17cbc6e7
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -0,0 +1,196 @@
+vi.mock('@redocly/openapi-core', async (importOriginal) => {
+  const actual = (await importOriginal()) as any;
+  return {
+    ...actual,
+    bundle: vi.fn(),
+    detectSpec: vi.fn(),
+    logger: { output: vi.fn(), info: vi.fn(), error: vi.fn() },
+  };
+});
+
+vi.mock('../../../utils/miscellaneous.js', () => ({
+  getFallbackApisOrExit: vi.fn(),
+  printExecutionTime: vi.fn(),
+}));
+
+import { bundle, detectSpec, logger } from '@redocly/openapi-core';
+
+import { getFallbackApisOrExit } from '../../../utils/miscellaneous.js';
+import { handleScore, type ScoreArgv } from '../index.js';
+
+const mockedBundle = vi.mocked(bundle);
+const mockedDetectSpec = vi.mocked(detectSpec);
+const mockedGetFallback = vi.mocked(getFallbackApisOrExit);
+const mockOutput = vi.mocked(logger.output);
+const mockInfo = vi.mocked(logger.info);
+const mockError = vi.mocked(logger.error);
+
+function makeMinimalDoc(overrides: Record<string, any> = {}) {
+  return {
+    openapi: '3.0.0',
+    info: { title: 'Test', version: '1.0.0' },
+    paths: {
+      '/items': {
+        get: {
+          operationId: 'listItems',
+          description: 'List items',
+          responses: {
+            '200': {
+              description: 'OK',
+              content: {
+                'application/json': {
+                  schema: { type: 'object', properties: { id: { type: 'string' } } },
+                  example: { id: '1' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    ...overrides,
+  };
+}
+
+function createArgs(overrides: Partial<ScoreArgv> = {}) {
+  return {
+    argv: { format: 'stylish' as const, ...overrides } as ScoreArgv,
+    config: {} as any,
+    collectSpecData: vi.fn(),
+  };
+}
+
+describe('handleScore', () => {
+  beforeEach(() => {
+    mockOutput.mockClear();
+    mockInfo.mockClear();
+    mockError.mockClear();
+    mockedGetFallback.mockResolvedValue([{ path: 'test.yaml' }] as any);
+    process.exitCode = undefined;
+  });
+
+  it('should produce stylish output for a valid oas3 document', async () => {
+    const doc = makeMinimalDoc();
+    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
+    mockedDetectSpec.mockReturnValue('oas3_0');
+
+    await handleScore(createArgs());
+
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('Integration Simplicity');
+    expect(output).toContain('Agent Readiness');
+  });
+
+  it('should produce JSON output when format is json', async () => {
+    const doc = makeMinimalDoc();
+    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
+    mockedDetectSpec.mockReturnValue('oas3_0');
+
+    await handleScore(createArgs({ format: 'json' }));
+
+    const output = mockOutput.mock.calls[0][0];
+    const parsed = JSON.parse(output);
+    expect(parsed.integrationSimplicity).toBeDefined();
+    expect(parsed.agentReadiness).toBeDefined();
+    expect(parsed.rawMetrics.operationCount).toBe(1);
+  });
+
+  it('should reject non-oas3 documents', async () => {
+    mockedBundle.mockResolvedValue({ bundle: { parsed: { swagger: '2.0' } } } as any);
+    mockedDetectSpec.mockReturnValue('oas2');
+
+    await handleScore(createArgs());
+
+    expect(process.exitCode).toBe(1);
+    expect(mockError).toHaveBeenCalled();
+    const errorMsg = mockError.mock.calls[0][0];
+    expect(errorMsg).toContain('OpenAPI 3.x');
+  });
+
+  it('should call collectSpecData', async () => {
+    const doc = makeMinimalDoc();
+    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
+    mockedDetectSpec.mockReturnValue('oas3_1');
+
+    const args = createArgs();
+    await handleScore(args);
+
+    expect(args.collectSpecData).toHaveBeenCalledWith(doc);
+  });
+
+  it('should handle document with no operations', async () => {
+    const doc = makeMinimalDoc({ paths: {} });
+    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
+    mockedDetectSpec.mockReturnValue('oas3_0');
+
+    await handleScore(createArgs());
+
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('Total operations: 0');
+  });
+
+  it('should handle document with multiple operations', async () => {
+    const doc = makeMinimalDoc({
+      paths: {
+        '/items': {
+          get: {
+            operationId: 'listItems',
+            description: 'List items',
+            responses: { '200': { description: 'OK' } },
+          },
+          post: {
+            operationId: 'createItem',
+            description: 'Create item',
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { type: 'object', properties: { name: { type: 'string' } } },
+                },
+              },
+            },
+            responses: {
+              '201': { description: 'Created' },
+              '400': { description: 'Bad Request' },
+            },
+          },
+        },
+      },
+    });
+    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
+    mockedDetectSpec.mockReturnValue('oas3_0');
+
+    await handleScore(createArgs({ format: 'json' }));
+
+    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
+    expect(parsed.rawMetrics.operationCount).toBe(2);
+    expect(parsed.operationScores.listItems).toBeDefined();
+    expect(parsed.operationScores.createItem).toBeDefined();
+  });
+
+  it('should include hotspots in output', async () => {
+    const doc = makeMinimalDoc({
+      paths: {
+        '/complex': {
+          post: {
+            operationId: 'complexOp',
+            parameters: Array.from({ length: 10 }, (_, i) => ({
+              name: `param${i}`,
+              in: 'query',
+            })),
+            requestBody: {
+              content: { 'application/json': { schema: { type: 'object' } } },
+            },
+            responses: { '200': { description: 'OK' } },
+          },
+        },
+      },
+    });
+    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
+    mockedDetectSpec.mockReturnValue('oas3_0');
+
+    await handleScore(createArgs());
+
+    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+    expect(output).toContain('Hotspot');
+  });
+});
diff --git a/packages/cli/src/commands/score/__tests__/scoring.test.ts b/packages/cli/src/commands/score/__tests__/scoring.test.ts
index 98df9be26e..3aa9e6edd6 100644
--- a/packages/cli/src/commands/score/__tests__/scoring.test.ts
+++ b/packages/cli/src/commands/score/__tests__/scoring.test.ts
@@ -210,6 +210,149 @@ describe('scoring', () => {
     });
   });
 
+  describe('example coverage', () => {
+    it('should give full example coverage when both request and response examples present', () => {
+      const metrics = makeBaseMetrics({
+        requestBodyPresent: true,
+        requestExamplePresent: true,
+        responseExamplePresent: true,
+      });
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.exampleCoverage).toBe(1);
+    });
+
+    it('should give full example coverage when no body and response example present', () => {
+      const metrics = makeBaseMetrics({
+        requestBodyPresent: false,
+        requestExamplePresent: false,
+        responseExamplePresent: true,
+      });
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.exampleCoverage).toBe(1);
+    });
+
+    it('should give 50% when request body present but only response example', () => {
+      const metrics = makeBaseMetrics({
+        requestBodyPresent: true,
+        requestExamplePresent: false,
+        responseExamplePresent: true,
+      });
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.exampleCoverage).toBe(0.5);
+    });
+  });
+
+  describe('error clarity', () => {
+    it('should give full score when all errors are structured', () => {
+      const metrics = makeBaseMetrics({
+        structuredErrorResponseCount: 3,
+        totalErrorResponses: 3,
+      });
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.errorClarity).toBe(1);
+    });
+
+    it('should give full score when there are no error responses', () => {
+      const metrics = makeBaseMetrics({
+        structuredErrorResponseCount: 0,
+        totalErrorResponses: 0,
+      });
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.errorClarity).toBe(1);
+    });
+
+    it('should give 0 when no errors are structured', () => {
+      const metrics = makeBaseMetrics({
+        structuredErrorResponseCount: 0,
+        totalErrorResponses: 2,
+      });
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.errorClarity).toBe(0);
+    });
+  });
+
+  describe('documentation quality', () => {
+    it('should give full score when all items have descriptions', () => {
+      const metrics = makeBaseMetrics({
+        operationDescriptionPresent: true,
+        parameterCount: 2,
+        paramsWithDescription: 2,
+        totalSchemaProperties: 3,
+        schemaPropertiesWithDescription: 3,
+      });
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.documentationQuality).toBe(1);
+    });
+
+    it('should give full score when there are no params or properties', () => {
+      const metrics = makeBaseMetrics({
+        operationDescriptionPresent: true,
+        parameterCount: 0,
+        paramsWithDescription: 0,
+        totalSchemaProperties: 0,
+        schemaPropertiesWithDescription: 0,
+      });
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.documentationQuality).toBe(1);
+    });
+  });
+
+  describe('workflow clarity', () => {
+    it('should give full score with 0 workflow depth', () => {
+      const metrics = makeBaseMetrics();
+      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      expect(sub.workflowClarity).toBe(1);
+    });
+
+    it('should decrease with higher workflow depth', () => {
+      const metrics = makeBaseMetrics();
+      const sub0 = computeOperationIntegrationSubscores(metrics, 0);
+      const sub3 = computeOperationIntegrationSubscores(metrics, 3);
+      expect(sub0.workflowClarity).toBeGreaterThan(sub3.workflowClarity);
+    });
+  });
+
+  describe('agent-specific subscores', () => {
+    it('should give full identifier clarity with no ambiguous identifiers', () => {
+      const metrics = makeBaseMetrics({ ambiguousIdentifierCount: 0 });
+      const sub = computeOperationAgentSubscores(metrics, 0);
+      expect(sub.identifierClarity).toBe(1);
+    });
+
+    it('should decrease identifier clarity with ambiguous identifiers', () => {
+      const metrics = makeBaseMetrics({ ambiguousIdentifierCount: 3 });
+      const sub = computeOperationAgentSubscores(metrics, 0);
+      expect(sub.identifierClarity).toBe(0);
+    });
+
+    it('should give full polymorphism clarity with no polymorphism', () => {
+      const metrics = makeBaseMetrics({ polymorphismCount: 0, anyOfCount: 0 });
+      const sub = computeOperationAgentSubscores(metrics, 0);
+      expect(sub.polymorphismClarity).toBe(1);
+    });
+  });
+
+  describe('computeAllOperationScores', () => {
+    it('should compute scores for all operations', () => {
+      const doc = {
+        operationCount: 2,
+        operations: new Map([
+          ['op1', makeBaseMetrics()],
+          ['op2', makeBaseMetrics({ parameterCount: 10 })],
+        ]),
+      };
+      const depths = new Map([
+        ['op1', 0],
+        ['op2', 1],
+      ]);
+      const result = computeAllOperationScores(doc, depths);
+      expect(result.size).toBe(2);
+      expect(result.get('op1')!.integrationSimplicity).toBeGreaterThan(
+        result.get('op2')!.integrationSimplicity
+      );
+    });
+  });
+
   describe('composite scores', () => {
     it('should produce scores in 0-100 range', () => {
       const metrics = makeBaseMetrics({
diff --git a/packages/cli/src/commands/score/__tests__/workflow-graph.test.ts b/packages/cli/src/commands/score/__tests__/workflow-graph.test.ts
new file mode 100644
index 0000000000..f296353116
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/workflow-graph.test.ts
@@ -0,0 +1,89 @@
+import { computeWorkflowDepths } from '../collectors/workflow-graph.js';
+import type { OperationMetrics } from '../types.js';
+
+function makeOp(path: string, method: string, refs: string[]): OperationMetrics {
+  return {
+    path,
+    method,
+    parameterCount: 0,
+    requiredParameterCount: 0,
+    paramsWithDescription: 0,
+    requestBodyPresent: false,
+    topLevelWritableFieldCount: 0,
+    maxRequestSchemaDepth: 0,
+    maxResponseSchemaDepth: 0,
+    polymorphismCount: 0,
+    anyOfCount: 0,
+    hasDiscriminator: false,
+    propertyCount: 0,
+    operationDescriptionPresent: false,
+    schemaPropertiesWithDescription: 0,
+    totalSchemaProperties: 0,
+    constraintCount: 0,
+    requestExamplePresent: false,
+    responseExamplePresent: false,
+    structuredErrorResponseCount: 0,
+    totalErrorResponses: 0,
+    ambiguousIdentifierCount: 0,
+    refsUsed: new Set(refs),
+  };
+}
+
+describe('computeWorkflowDepths', () => {
+  it('returns depth 0 for isolated operations', () => {
+    const ops = new Map([
+      ['opA', makeOp('/a', 'get', ['#/components/schemas/A'])],
+      ['opB', makeOp('/b', 'get', ['#/components/schemas/B'])],
+    ]);
+    const depths = computeWorkflowDepths(ops);
+    expect(depths.get('opA')).toBe(0);
+    expect(depths.get('opB')).toBe(0);
+  });
+
+  it('returns depth 1 for two operations sharing a ref', () => {
+    const shared = '#/components/schemas/Shared';
+    const ops = new Map([
+      ['opA', makeOp('/a', 'get', [shared])],
+      ['opB', makeOp('/b', 'post', [shared])],
+    ]);
+    const depths = computeWorkflowDepths(ops);
+    expect(depths.get('opA')).toBe(1);
+    expect(depths.get('opB')).toBe(1);
+  });
+
+  it('returns depth 2 for a linear chain A-B-C', () => {
+    const ops = new Map([
+      ['opA', makeOp('/a', 'get', ['#/schemas/AB'])],
+      ['opB', makeOp('/b', 'post', ['#/schemas/AB', '#/schemas/BC'])],
+      ['opC', makeOp('/c', 'put', ['#/schemas/BC'])],
+    ]);
+    const depths = computeWorkflowDepths(ops);
+    expect(depths.get('opA')).toBe(2);
+    expect(depths.get('opC')).toBe(2);
+    expect(depths.get('opB')).toBeLessThanOrEqual(2);
+  });
+
+  it('handles empty operations map', () => {
+    const depths = computeWorkflowDepths(new Map());
+    expect(depths.size).toBe(0);
+  });
+
+  it('handles operations with no refs', () => {
+    const ops = new Map([['opA', makeOp('/a', 'get', [])]]);
+    const depths = computeWorkflowDepths(ops);
+    expect(depths.get('opA')).toBe(0);
+  });
+
+  it('groups all operations sharing the same ref', () => {
+    const shared = '#/components/schemas/Common';
+    const ops = new Map([
+      ['opA', makeOp('/a', 'get', [shared])],
+      ['opB', makeOp('/b', 'post', [shared])],
+      ['opC', makeOp('/c', 'put', [shared])],
+    ]);
+    const depths = computeWorkflowDepths(ops);
+    expect(depths.get('opA')).toBe(1);
+    expect(depths.get('opB')).toBe(1);
+    expect(depths.get('opC')).toBe(1);
+  });
+});

From f9bd3e75fcf662d50e19dfe55943b88e78066abe Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Wed, 11 Mar 2026 20:59:23 -0500
Subject: [PATCH 03/22] refactor: address PR review feedback for score command

- Add "AI" before "agent readiness" in changeset and docs for clarity
- Replace <pre> block with fenced code block in score.md
- Add security scheme coverage to metrics documentation
- Remove resolveIfRef helper, replace with resolveNode that falls back
  to the original node when resolution fails
- Refactor to use walkDocument visitor approach (matching stats command
  pattern) instead of manually iterating the document tree
- Use resolveDocument + normalizeVisitors + walkDocument from
  openapi-core for proper $ref resolution and spec-format extensibility
- Update index.test.ts to mock the new walk infrastructure

Made-with: Cursor
---
 .changeset/add-score-command.md               |   2 +-
 docs/@v2/commands/index.md                    |   2 +-
 docs/@v2/commands/score.md                    |   5 +-
 .../commands/score/__tests__/index.test.ts    | 200 ++++++++++--------
 .../score/collectors/document-metrics.ts      |  88 ++++++--
 packages/cli/src/commands/score/index.ts      |  53 ++++-
 6 files changed, 241 insertions(+), 109 deletions(-)

diff --git a/.changeset/add-score-command.md b/.changeset/add-score-command.md
index e118660343..5a8799de03 100644
--- a/.changeset/add-score-command.md
+++ b/.changeset/add-score-command.md
@@ -2,4 +2,4 @@
 '@redocly/cli': minor
 ---
 
-Added new `score` command that analyzes OpenAPI 3.x descriptions and produces integration simplicity and agent readiness scores (0-100). Reports normalized subscores, raw per-operation metrics, and top hotspot operations with human-readable explanations. Supports `--format=stylish` (default) and `--format=json` output.
+Added new `score` command that analyzes OpenAPI 3.x descriptions and produces integration simplicity and AI agent readiness scores (0-100). Reports normalized subscores, raw per-operation metrics, and top hotspot operations with human-readable explanations. Supports `--format=stylish` (default) and `--format=json` output.
diff --git a/docs/@v2/commands/index.md b/docs/@v2/commands/index.md
index aad01badaf..add90a21f3 100644
--- a/docs/@v2/commands/index.md
+++ b/docs/@v2/commands/index.md
@@ -15,7 +15,7 @@ API management commands:
 
 - [`bundle`](bundle.md) Bundle API description.
 - [`join`](join.md) Join API descriptions [experimental feature].
-- [`score`](score.md) Score an API for integration simplicity and agent readiness.
+- [`score`](score.md) Score an API for integration simplicity and AI agent readiness.
 - [`split`](split.md) Split API description into a multi-file structure.
 - [`stats`](stats.md) Gather statistics for a document.
 
diff --git a/docs/@v2/commands/score.md b/docs/@v2/commands/score.md
index cdea1bcb9b..596fa29914 100644
--- a/docs/@v2/commands/score.md
+++ b/docs/@v2/commands/score.md
@@ -31,6 +31,7 @@ The following raw metrics are collected per operation and aggregated across the
 | Constraint coverage                | Count of constraining keywords (`enum`, `format`, `pattern`, `minimum`, `maximum`, `minLength`, `maxLength`, `discriminator`, etc.). |
 | Request/response example coverage  | Whether request and response media types include `example` or `examples`.                                                            |
 | Structured error response coverage | How many 4xx/5xx responses include a content schema or meaningful description.                                                       |
+| Security scheme coverage           | Whether operations reference documented security schemes with descriptions.                                                          |
 | Workflow dependency depth          | Inferred from shared `$ref` usage across operations; deeper shared-schema graphs indicate more tightly coupled workflows.            |
 
 ### Subscores
@@ -109,7 +110,7 @@ redocly score --config=./another/directory/config.yaml
 
 The default output format shows a human-readable summary in your terminal:
 
-<pre>
+```sh
   Scores
 
   Integration Simplicity:  72.5/100
@@ -137,7 +138,7 @@ The default output format shows a human-readable summary in your terminal:
     Integration Simplicity: 52.1  Agent Readiness: 44.0
     - Polymorphism (anyOf) without discriminator (3 anyOf)
     - No structured error responses (4xx/5xx)
-</pre>
+```
 
 #### JSON output
 
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index ef17cbc6e7..fd15fbeff4 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -4,6 +4,12 @@ vi.mock('@redocly/openapi-core', async (importOriginal) => {
     ...actual,
     bundle: vi.fn(),
     detectSpec: vi.fn(),
+    BaseResolver: vi.fn(),
+    resolveDocument: vi.fn(),
+    normalizeTypes: vi.fn(),
+    getTypes: vi.fn(),
+    normalizeVisitors: vi.fn(),
+    walkDocument: vi.fn(),
     logger: { output: vi.fn(), info: vi.fn(), error: vi.fn() },
   };
 });
@@ -13,49 +19,84 @@ vi.mock('../../../utils/miscellaneous.js', () => ({
   printExecutionTime: vi.fn(),
 }));
 
-import { bundle, detectSpec, logger } from '@redocly/openapi-core';
+vi.mock('../collectors/document-metrics.js', async (importOriginal) => {
+  const actual = (await importOriginal()) as any;
+  return {
+    ...actual,
+    createScoreAccumulator: vi.fn(),
+    createScoreVisitor: vi.fn(),
+  };
+});
+
+import {
+  bundle,
+  detectSpec,
+  logger,
+  normalizeTypes,
+  resolveDocument,
+  normalizeVisitors,
+  walkDocument,
+} from '@redocly/openapi-core';
 
 import { getFallbackApisOrExit } from '../../../utils/miscellaneous.js';
+import {
+  createScoreAccumulator,
+  createScoreVisitor,
+  type ScoreAccumulator,
+} from '../collectors/document-metrics.js';
 import { handleScore, type ScoreArgv } from '../index.js';
+import type { OperationMetrics } from '../types.js';
 
 const mockedBundle = vi.mocked(bundle);
 const mockedDetectSpec = vi.mocked(detectSpec);
 const mockedGetFallback = vi.mocked(getFallbackApisOrExit);
 const mockOutput = vi.mocked(logger.output);
-const mockInfo = vi.mocked(logger.info);
 const mockError = vi.mocked(logger.error);
-
-function makeMinimalDoc(overrides: Record<string, any> = {}) {
+const mockedCreateAccumulator = vi.mocked(createScoreAccumulator);
+const mockedCreateVisitor = vi.mocked(createScoreVisitor);
+const mockedNormalizeTypes = vi.mocked(normalizeTypes);
+const mockedResolveDocument = vi.mocked(resolveDocument);
+const mockedNormalizeVisitors = vi.mocked(normalizeVisitors);
+const mockedWalkDocument = vi.mocked(walkDocument);
+
+function makeTestMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetrics {
   return {
-    openapi: '3.0.0',
-    info: { title: 'Test', version: '1.0.0' },
-    paths: {
-      '/items': {
-        get: {
-          operationId: 'listItems',
-          description: 'List items',
-          responses: {
-            '200': {
-              description: 'OK',
-              content: {
-                'application/json': {
-                  schema: { type: 'object', properties: { id: { type: 'string' } } },
-                  example: { id: '1' },
-                },
-              },
-            },
-          },
-        },
-      },
-    },
+    path: '/items',
+    method: 'get',
+    operationId: 'listItems',
+    parameterCount: 0,
+    requiredParameterCount: 0,
+    paramsWithDescription: 0,
+    requestBodyPresent: false,
+    topLevelWritableFieldCount: 0,
+    maxRequestSchemaDepth: 0,
+    maxResponseSchemaDepth: 1,
+    polymorphismCount: 0,
+    anyOfCount: 0,
+    hasDiscriminator: false,
+    propertyCount: 1,
+    operationDescriptionPresent: true,
+    schemaPropertiesWithDescription: 0,
+    totalSchemaProperties: 1,
+    constraintCount: 0,
+    requestExamplePresent: false,
+    responseExamplePresent: true,
+    structuredErrorResponseCount: 0,
+    totalErrorResponses: 0,
+    ambiguousIdentifierCount: 0,
+    refsUsed: new Set(),
     ...overrides,
   };
 }
 
+function makeAccumulator(ops: Map<string, OperationMetrics> = new Map()): ScoreAccumulator {
+  return { operations: ops, currentPath: '', pathLevelParams: [] };
+}
+
 function createArgs(overrides: Partial<ScoreArgv> = {}) {
   return {
     argv: { format: 'stylish' as const, ...overrides } as ScoreArgv,
-    config: {} as any,
+    config: { extendTypes: (types: any) => types, resolve: {} } as any,
     collectSpecData: vi.fn(),
   };
 }
@@ -63,17 +104,22 @@ function createArgs(overrides: Partial<ScoreArgv> = {}) {
 describe('handleScore', () => {
   beforeEach(() => {
     mockOutput.mockClear();
-    mockInfo.mockClear();
     mockError.mockClear();
     mockedGetFallback.mockResolvedValue([{ path: 'test.yaml' }] as any);
+    mockedBundle.mockResolvedValue({ bundle: { parsed: {} } } as any);
+    mockedDetectSpec.mockReturnValue('oas3_0');
+    mockedNormalizeTypes.mockReturnValue({ Root: {} } as any);
+    mockedResolveDocument.mockResolvedValue(new Map() as any);
+    mockedNormalizeVisitors.mockReturnValue([] as any);
+    mockedWalkDocument.mockImplementation(() => {});
+    mockedCreateVisitor.mockReturnValue({} as any);
+    mockedCreateAccumulator.mockReturnValue(
+      makeAccumulator(new Map([['listItems', makeTestMetrics()]]))
+    );
     process.exitCode = undefined;
   });
 
   it('should produce stylish output for a valid oas3 document', async () => {
-    const doc = makeMinimalDoc();
-    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
-    mockedDetectSpec.mockReturnValue('oas3_0');
-
     await handleScore(createArgs());
 
     const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
@@ -82,10 +128,6 @@ describe('handleScore', () => {
   });
 
   it('should produce JSON output when format is json', async () => {
-    const doc = makeMinimalDoc();
-    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
-    mockedDetectSpec.mockReturnValue('oas3_0');
-
     await handleScore(createArgs({ format: 'json' }));
 
     const output = mockOutput.mock.calls[0][0];
@@ -96,7 +138,6 @@ describe('handleScore', () => {
   });
 
   it('should reject non-oas3 documents', async () => {
-    mockedBundle.mockResolvedValue({ bundle: { parsed: { swagger: '2.0' } } } as any);
     mockedDetectSpec.mockReturnValue('oas2');
 
     await handleScore(createArgs());
@@ -108,7 +149,7 @@ describe('handleScore', () => {
   });
 
   it('should call collectSpecData', async () => {
-    const doc = makeMinimalDoc();
+    const doc = { openapi: '3.0.0' };
     mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
     mockedDetectSpec.mockReturnValue('oas3_1');
 
@@ -119,9 +160,7 @@ describe('handleScore', () => {
   });
 
   it('should handle document with no operations', async () => {
-    const doc = makeMinimalDoc({ paths: {} });
-    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
-    mockedDetectSpec.mockReturnValue('oas3_0');
+    mockedCreateAccumulator.mockReturnValue(makeAccumulator());
 
     await handleScore(createArgs());
 
@@ -130,34 +169,23 @@ describe('handleScore', () => {
   });
 
   it('should handle document with multiple operations', async () => {
-    const doc = makeMinimalDoc({
-      paths: {
-        '/items': {
-          get: {
-            operationId: 'listItems',
-            description: 'List items',
-            responses: { '200': { description: 'OK' } },
-          },
-          post: {
-            operationId: 'createItem',
-            description: 'Create item',
-            requestBody: {
-              content: {
-                'application/json': {
-                  schema: { type: 'object', properties: { name: { type: 'string' } } },
-                },
-              },
-            },
-            responses: {
-              '201': { description: 'Created' },
-              '400': { description: 'Bad Request' },
-            },
-          },
-        },
-      },
-    });
-    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
-    mockedDetectSpec.mockReturnValue('oas3_0');
+    mockedCreateAccumulator.mockReturnValue(
+      makeAccumulator(
+        new Map([
+          ['listItems', makeTestMetrics()],
+          [
+            'createItem',
+            makeTestMetrics({
+              path: '/items',
+              method: 'post',
+              operationId: 'createItem',
+              requestBodyPresent: true,
+              operationDescriptionPresent: true,
+            }),
+          ],
+        ])
+      )
+    );
 
     await handleScore(createArgs({ format: 'json' }));
 
@@ -168,25 +196,23 @@ describe('handleScore', () => {
   });
 
   it('should include hotspots in output', async () => {
-    const doc = makeMinimalDoc({
-      paths: {
-        '/complex': {
-          post: {
-            operationId: 'complexOp',
-            parameters: Array.from({ length: 10 }, (_, i) => ({
-              name: `param${i}`,
-              in: 'query',
-            })),
-            requestBody: {
-              content: { 'application/json': { schema: { type: 'object' } } },
-            },
-            responses: { '200': { description: 'OK' } },
-          },
-        },
-      },
-    });
-    mockedBundle.mockResolvedValue({ bundle: { parsed: doc } } as any);
-    mockedDetectSpec.mockReturnValue('oas3_0');
+    mockedCreateAccumulator.mockReturnValue(
+      makeAccumulator(
+        new Map([
+          [
+            'complexOp',
+            makeTestMetrics({
+              path: '/complex',
+              method: 'post',
+              operationId: 'complexOp',
+              parameterCount: 10,
+              requestBodyPresent: true,
+              operationDescriptionPresent: false,
+            }),
+          ],
+        ])
+      )
+    );
 
     await handleScore(createArgs());
 
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
index 564cbe46e5..fefe4b4d79 100644
--- a/packages/cli/src/commands/score/collectors/document-metrics.ts
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -4,16 +4,80 @@ import { walkSchema } from './schema-walker.js';
 
 const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const;
 
+export interface ScoreAccumulator {
+  operations: Map<string, OperationMetrics>;
+  currentPath: string;
+  pathLevelParams: any[];
+}
+
+export function createScoreAccumulator(): ScoreAccumulator {
+  return {
+    operations: new Map(),
+    currentPath: '',
+    pathLevelParams: [],
+  };
+}
+
+export function createScoreVisitor(accumulator: ScoreAccumulator) {
+  return {
+    Paths: {
+      PathItem: {
+        enter(pathItem: any, ctx: any) {
+          accumulator.currentPath = ctx.key as string;
+          accumulator.pathLevelParams = Array.isArray(pathItem.parameters)
+            ? pathItem.parameters
+            : [];
+        },
+        Operation: {
+          enter(operation: any, ctx: any) {
+            const path = accumulator.currentPath;
+            const method = ctx.key as string;
+            const resolveRef = wrapCtxResolve(ctx.resolve);
+
+            const opKey = operation.operationId ?? `${method.toUpperCase()} ${path}`;
+            const metrics = collectOperationMetrics(
+              path,
+              method,
+              operation,
+              accumulator.pathLevelParams,
+              resolveRef
+            );
+            accumulator.operations.set(opKey, metrics);
+          },
+        },
+      },
+    },
+  };
+}
+
+export function getDocumentMetrics(accumulator: ScoreAccumulator): DocumentMetrics {
+  return { operationCount: accumulator.operations.size, operations: accumulator.operations };
+}
+
+function wrapCtxResolve(
+  resolve: (ref: { $ref: string }) => { node?: any } | undefined
+): RefResolver {
+  return (ref: string) => {
+    try {
+      const result = resolve({ $ref: ref });
+      return result?.node && typeof result.node === 'object'
+        ? (result.node as Record<string, any>)
+        : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+}
+
 export function collectDocumentMetrics(document: Record<string, any>): DocumentMetrics {
   const operations = new Map<string, OperationMetrics>();
   const paths = document.paths;
-  const resolveRef = createRefResolver(document);
+  const resolveRef = createSimpleRefResolver(document);
 
   if (paths && typeof paths === 'object') {
     for (const [pathStr, pathItem] of Object.entries(paths)) {
       if (!pathItem || typeof pathItem !== 'object') continue;
-      const pathObj = resolveIfRef(pathItem as Record<string, any>, resolveRef);
-      if (!pathObj) continue;
+      const pathObj = resolveNode(pathItem as Record<string, any>, resolveRef);
 
       const pathLevelParams: any[] = Array.isArray(pathObj.parameters) ? pathObj.parameters : [];
 
@@ -37,7 +101,7 @@ export function collectDocumentMetrics(document: Record<string, any>): DocumentM
   return { operationCount: operations.size, operations };
 }
 
-function createRefResolver(document: Record<string, any>): RefResolver {
+function createSimpleRefResolver(document: Record<string, any>): RefResolver {
   return (ref: string) => {
     if (!ref.startsWith('#/')) return undefined;
     const parts = ref.slice(2).split('/');
@@ -50,12 +114,9 @@ function createRefResolver(document: Record<string, any>): RefResolver {
   };
 }
 
-function resolveIfRef(
-  node: Record<string, any>,
-  resolveRef: RefResolver
-): Record<string, any> | undefined {
+function resolveNode(node: Record<string, any>, resolveRef: RefResolver): Record<string, any> {
   if (node.$ref && typeof node.$ref === 'string') {
-    return resolveRef(node.$ref);
+    return resolveRef(node.$ref) ?? node;
   }
   return node;
 }
@@ -83,7 +144,7 @@ function collectOperationMetrics(
   }
 
   const reqBody = operation.requestBody
-    ? resolveIfRef(operation.requestBody, resolveRef)
+    ? resolveNode(operation.requestBody, resolveRef)
     : undefined;
   const requestBodyPresent = !!reqBody;
   let maxRequestSchemaDepth = 0;
@@ -136,8 +197,7 @@ function collectOperationMetrics(
   if (operation.responses && typeof operation.responses === 'object') {
     for (const [code, rawResponse] of Object.entries(operation.responses)) {
       if (!rawResponse || typeof rawResponse !== 'object') continue;
-      const resp = resolveIfRef(rawResponse as Record<string, any>, resolveRef);
-      if (!resp) continue;
+      const resp = resolveNode(rawResponse as Record<string, any>, resolveRef);
       collectRefs(rawResponse as Record<string, any>, refsUsed);
 
       const isError = isErrorCode(code);
@@ -205,13 +265,13 @@ function collectOperationMetrics(
 function mergeParameters(pathLevel: any[], opLevel: any[], resolveRef: RefResolver): any[] {
   const merged = new Map<string, any>();
   for (const raw of pathLevel) {
-    const p = raw && typeof raw === 'object' ? (resolveIfRef(raw, resolveRef) ?? raw) : raw;
+    const p = raw && typeof raw === 'object' ? resolveNode(raw, resolveRef) : raw;
     if (p && typeof p === 'object' && p.name && p.in) {
       merged.set(`${p.in}:${p.name}`, p);
     }
   }
   for (const raw of opLevel) {
-    const p = raw && typeof raw === 'object' ? (resolveIfRef(raw, resolveRef) ?? raw) : raw;
+    const p = raw && typeof raw === 'object' ? resolveNode(raw, resolveRef) : raw;
     if (p && typeof p === 'object' && p.name && p.in) {
       merged.set(`${p.in}:${p.name}`, p);
     }
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
index a9caa9969d..0cc0f2120a 100644
--- a/packages/cli/src/commands/score/index.ts
+++ b/packages/cli/src/commands/score/index.ts
@@ -1,12 +1,26 @@
-import { bundle, detectSpec, logger } from '@redocly/openapi-core';
-import type { OutputFormat } from '@redocly/openapi-core';
+import {
+  normalizeTypes,
+  BaseResolver,
+  resolveDocument,
+  detectSpec,
+  getTypes,
+  normalizeVisitors,
+  walkDocument,
+  bundle,
+  logger,
+} from '@redocly/openapi-core';
+import type { OutputFormat, WalkContext } from '@redocly/openapi-core';
 import * as colors from 'colorette';
 import { performance } from 'perf_hooks';
 
 import type { VerifyConfigOptions } from '../../types.js';
 import { getFallbackApisOrExit, printExecutionTime } from '../../utils/miscellaneous.js';
 import type { CommandArgs } from '../../wrapper.js';
-import { collectDocumentMetrics } from './collectors/document-metrics.js';
+import {
+  createScoreAccumulator,
+  createScoreVisitor,
+  getDocumentMetrics,
+} from './collectors/document-metrics.js';
 import { computeWorkflowDepths } from './collectors/workflow-graph.js';
 import { printScoreJson } from './formatters/json.js';
 import { printScoreStylish } from './formatters/stylish.js';
@@ -25,6 +39,7 @@ export type ScoreArgv = {
 
 export async function handleScore({ argv, config, collectSpecData }: CommandArgs<ScoreArgv>) {
   const [{ path }] = await getFallbackApisOrExit(argv.api ? [argv.api] : [], config);
+  const externalRefResolver = new BaseResolver(config.resolve);
   const { bundle: document } = await bundle({ config, ref: path });
   collectSpecData?.(document.parsed);
 
@@ -39,7 +54,37 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
 
   const startedAt = performance.now();
 
-  const rawMetrics = collectDocumentMetrics(document.parsed as Record<string, any>);
+  const types = normalizeTypes(config.extendTypes(getTypes(specVersion), specVersion), config);
+  const accumulator = createScoreAccumulator();
+  const scoreVisitor = createScoreVisitor(accumulator);
+
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+
+  const walkCtx: WalkContext = {
+    problems: [],
+    specVersion,
+    config,
+    visitorsData: {},
+  };
+
+  const normalizedVisitors = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
+    types
+  );
+
+  walkDocument({
+    document,
+    rootType: types.Root,
+    normalizedVisitors,
+    resolvedRefMap,
+    ctx: walkCtx,
+  });
+
+  const rawMetrics = getDocumentMetrics(accumulator);
   const workflowDepths = computeWorkflowDepths(rawMetrics.operations);
   const operationScores = computeAllOperationScores(rawMetrics, workflowDepths);
   const { integrationSimplicity, agentReadiness } = computeDocumentScores(operationScores);

From a98ad599072dd7a0c09bacf58dbd160bedadd7e5 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Wed, 11 Mar 2026 21:02:42 -0500
Subject: [PATCH 04/22] fix: add missing version property to test CommandArgs

Made-with: Cursor
---
 packages/cli/src/commands/score/__tests__/index.test.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index fd15fbeff4..84bde4006f 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -97,6 +97,7 @@ function createArgs(overrides: Partial<ScoreArgv> = {}) {
   return {
     argv: { format: 'stylish' as const, ...overrides } as ScoreArgv,
     config: { extendTypes: (types: any) => types, resolve: {} } as any,
+    version: '0.0.0-test',
     collectSpecData: vi.fn(),
   };
 }

From 95fe9f084c4a3eb7f7894cdf61ed8023ac67713e Mon Sep 17 00:00:00 2001
From: Roman Hotsiy <gotsijroman@gmail.com>
Date: Thu, 12 Mar 2026 12:51:23 +0800
Subject: [PATCH 05/22] chore: add e2e

---
 tests/e2e/score/score-json/museum.yaml     |   1 +
 tests/e2e/score/score-json/snapshot.txt    | 441 +++++++++++++++++++++
 tests/e2e/score/score-minimal/openapi.yaml |  46 +++
 tests/e2e/score/score-minimal/snapshot.txt |  56 +++
 tests/e2e/score/score-stylish/museum.yaml  |   1 +
 tests/e2e/score/score-stylish/snapshot.txt |  52 +++
 tests/e2e/score/score.test.ts              |  32 ++
 7 files changed, 629 insertions(+)
 create mode 120000 tests/e2e/score/score-json/museum.yaml
 create mode 100644 tests/e2e/score/score-json/snapshot.txt
 create mode 100644 tests/e2e/score/score-minimal/openapi.yaml
 create mode 100644 tests/e2e/score/score-minimal/snapshot.txt
 create mode 120000 tests/e2e/score/score-stylish/museum.yaml
 create mode 100644 tests/e2e/score/score-stylish/snapshot.txt
 create mode 100644 tests/e2e/score/score.test.ts

diff --git a/tests/e2e/score/score-json/museum.yaml b/tests/e2e/score/score-json/museum.yaml
new file mode 120000
index 0000000000..5a811493e9
--- /dev/null
+++ b/tests/e2e/score/score-json/museum.yaml
@@ -0,0 +1 @@
+../../../../resources/museum.yaml
\ No newline at end of file
diff --git a/tests/e2e/score/score-json/snapshot.txt b/tests/e2e/score/score-json/snapshot.txt
new file mode 100644
index 0000000000..7b720786a2
--- /dev/null
+++ b/tests/e2e/score/score-json/snapshot.txt
@@ -0,0 +1,441 @@
+{
+  "integrationSimplicity": 82.1,
+  "agentReadiness": 81.2,
+  "integrationSubscores": {
+    "parameterSimplicity": 0.8625,
+    "schemaSimplicity": 0.921875,
+    "documentationQuality": 0.9374999999999999,
+    "constraintClarity": 0.27575757575757576,
+    "exampleCoverage": 0.75,
+    "errorClarity": 1,
+    "workflowClarity": 0.8333333333333333
+  },
+  "agentSubscores": {
+    "documentationQuality": 0.9374999999999999,
+    "constraintClarity": 0.27575757575757576,
+    "exampleCoverage": 0.75,
+    "errorClarity": 1,
+    "identifierClarity": 1,
+    "workflowClarity": 0.8333333333333333,
+    "polymorphismClarity": 1
+  },
+  "rawMetrics": {
+    "operationCount": 8,
+    "operations": {
+      "getMuseumHours": {
+        "path": "/museum-hours",
+        "method": "get",
+        "operationId": "getMuseumHours",
+        "parameterCount": 3,
+        "requiredParameterCount": 0,
+        "paramsWithDescription": 3,
+        "requestBodyPresent": false,
+        "topLevelWritableFieldCount": 0,
+        "maxRequestSchemaDepth": 0,
+        "maxResponseSchemaDepth": 2,
+        "polymorphismCount": 0,
+        "anyOfCount": 0,
+        "hasDiscriminator": false,
+        "propertyCount": 5,
+        "operationDescriptionPresent": true,
+        "schemaPropertiesWithDescription": 2,
+        "totalSchemaProperties": 5,
+        "constraintCount": 3,
+        "requestExamplePresent": false,
+        "responseExamplePresent": true,
+        "structuredErrorResponseCount": 2,
+        "totalErrorResponses": 2,
+        "ambiguousIdentifierCount": 0
+      },
+      "listSpecialEvents": {
+        "path": "/special-events",
+        "method": "get",
+        "operationId": "listSpecialEvents",
+        "parameterCount": 4,
+        "requiredParameterCount": 0,
+        "paramsWithDescription": 4,
+        "requestBodyPresent": false,
+        "topLevelWritableFieldCount": 0,
+        "maxRequestSchemaDepth": 0,
+        "maxResponseSchemaDepth": 2,
+        "polymorphismCount": 0,
+        "anyOfCount": 0,
+        "hasDiscriminator": false,
+        "propertyCount": 6,
+        "operationDescriptionPresent": true,
+        "schemaPropertiesWithDescription": 6,
+        "totalSchemaProperties": 6,
+        "constraintCount": 2,
+        "requestExamplePresent": false,
+        "responseExamplePresent": true,
+        "structuredErrorResponseCount": 0,
+        "totalErrorResponses": 0,
+        "ambiguousIdentifierCount": 0
+      },
+      "createSpecialEvent": {
+        "path": "/special-events",
+        "method": "post",
+        "operationId": "createSpecialEvent",
+        "parameterCount": 0,
+        "requiredParameterCount": 0,
+        "paramsWithDescription": 0,
+        "requestBodyPresent": true,
+        "topLevelWritableFieldCount": 5,
+        "maxRequestSchemaDepth": 0,
+        "maxResponseSchemaDepth": 0,
+        "polymorphismCount": 0,
+        "anyOfCount": 0,
+        "hasDiscriminator": false,
+        "propertyCount": 5,
+        "operationDescriptionPresent": true,
+        "schemaPropertiesWithDescription": 5,
+        "totalSchemaProperties": 5,
+        "constraintCount": 0,
+        "requestExamplePresent": true,
+        "responseExamplePresent": true,
+        "structuredErrorResponseCount": 0,
+        "totalErrorResponses": 0,
+        "ambiguousIdentifierCount": 0
+      },
+      "getSpecialEvent": {
+        "path": "/special-events/{eventId}",
+        "method": "get",
+        "operationId": "getSpecialEvent",
+        "parameterCount": 1,
+        "requiredParameterCount": 1,
+        "paramsWithDescription": 1,
+        "requestBodyPresent": false,
+        "topLevelWritableFieldCount": 0,
+        "maxRequestSchemaDepth": 0,
+        "maxResponseSchemaDepth": 0,
+        "polymorphismCount": 0,
+        "anyOfCount": 0,
+        "hasDiscriminator": false,
+        "propertyCount": 0,
+        "operationDescriptionPresent": true,
+        "schemaPropertiesWithDescription": 0,
+        "totalSchemaProperties": 0,
+        "constraintCount": 0,
+        "requestExamplePresent": false,
+        "responseExamplePresent": true,
+        "structuredErrorResponseCount": 0,
+        "totalErrorResponses": 0,
+        "ambiguousIdentifierCount": 0
+      },
+      "deleteSpecialEvent": {
+        "path": "/special-events/{eventId}",
+        "method": "delete",
+        "operationId": "deleteSpecialEvent",
+        "parameterCount": 1,
+        "requiredParameterCount": 1,
+        "paramsWithDescription": 1,
+        "requestBodyPresent": false,
+        "topLevelWritableFieldCount": 0,
+        "maxRequestSchemaDepth": 0,
+        "maxResponseSchemaDepth": 0,
+        "polymorphismCount": 0,
+        "anyOfCount": 0,
+        "hasDiscriminator": false,
+        "propertyCount": 0,
+        "operationDescriptionPresent": true,
+        "schemaPropertiesWithDescription": 0,
+        "totalSchemaProperties": 0,
+        "constraintCount": 0,
+        "requestExamplePresent": false,
+        "responseExamplePresent": false,
+        "structuredErrorResponseCount": 1,
+        "totalErrorResponses": 1,
+        "ambiguousIdentifierCount": 0
+      },
+      "updateSpecialEvent": {
+        "path": "/special-events/{eventId}",
+        "method": "patch",
+        "operationId": "updateSpecialEvent",
+        "parameterCount": 1,
+        "requiredParameterCount": 1,
+        "paramsWithDescription": 1,
+        "requestBodyPresent": true,
+        "topLevelWritableFieldCount": 5,
+        "maxRequestSchemaDepth": 0,
+        "maxResponseSchemaDepth": 0,
+        "polymorphismCount": 0,
+        "anyOfCount": 0,
+        "hasDiscriminator": false,
+        "propertyCount": 5,
+        "operationDescriptionPresent": true,
+        "schemaPropertiesWithDescription": 5,
+        "totalSchemaProperties": 5,
+        "constraintCount": 0,
+        "requestExamplePresent": true,
+        "responseExamplePresent": true,
+        "structuredErrorResponseCount": 0,
+        "totalErrorResponses": 0,
+        "ambiguousIdentifierCount": 0
+      },
+      "buyMuseumTickets": {
+        "path": "/tickets",
+        "method": "post",
+        "operationId": "buyMuseumTickets",
+        "parameterCount": 0,
+        "requiredParameterCount": 0,
+        "paramsWithDescription": 0,
+        "requestBodyPresent": true,
+        "topLevelWritableFieldCount": 5,
+        "maxRequestSchemaDepth": 1,
+        "maxResponseSchemaDepth": 1,
+        "polymorphismCount": 0,
+        "anyOfCount": 0,
+        "hasDiscriminator": false,
+        "propertyCount": 11,
+        "operationDescriptionPresent": true,
+        "schemaPropertiesWithDescription": 9,
+        "totalSchemaProperties": 11,
+        "constraintCount": 3,
+        "requestExamplePresent": true,
+        "responseExamplePresent": true,
+        "structuredErrorResponseCount": 0,
+        "totalErrorResponses": 0,
+        "ambiguousIdentifierCount": 0
+      },
+      "getTicketCode": {
+        "path": "/tickets/{ticketId}/qr",
+        "method": "get",
+        "operationId": "getTicketCode",
+        "parameterCount": 1,
+        "requiredParameterCount": 1,
+        "paramsWithDescription": 1,
+        "requestBodyPresent": false,
+        "topLevelWritableFieldCount": 0,
+        "maxRequestSchemaDepth": 0,
+        "maxResponseSchemaDepth": 0,
+        "polymorphismCount": 0,
+        "anyOfCount": 0,
+        "hasDiscriminator": false,
+        "propertyCount": 0,
+        "operationDescriptionPresent": true,
+        "schemaPropertiesWithDescription": 0,
+        "totalSchemaProperties": 0,
+        "constraintCount": 1,
+        "requestExamplePresent": false,
+        "responseExamplePresent": false,
+        "structuredErrorResponseCount": 0,
+        "totalErrorResponses": 0,
+        "ambiguousIdentifierCount": 0
+      }
+    }
+  },
+  "operationScores": {
+    "getMuseumHours": {
+      "integrationSimplicity": 78.3,
+      "agentReadiness": 85.7,
+      "integrationSubscores": {
+        "parameterSimplicity": 0.7,
+        "schemaSimplicity": 0.75,
+        "documentationQuality": 0.6666666666666666,
+        "constraintClarity": 0.6,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "workflowClarity": 0.8333333333333334
+      },
+      "agentSubscores": {
+        "documentationQuality": 0.6666666666666666,
+        "constraintClarity": 0.6,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "identifierClarity": 1,
+        "workflowClarity": 0.8333333333333334,
+        "polymorphismClarity": 1
+      }
+    },
+    "listSpecialEvents": {
+      "integrationSimplicity": 78.7,
+      "agentReadiness": 88.3,
+      "integrationSubscores": {
+        "parameterSimplicity": 0.6,
+        "schemaSimplicity": 0.75,
+        "documentationQuality": 1,
+        "constraintClarity": 0.3333333333333333,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "workflowClarity": 0.8333333333333334
+      },
+      "agentSubscores": {
+        "documentationQuality": 1,
+        "constraintClarity": 0.3333333333333333,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "identifierClarity": 1,
+        "workflowClarity": 0.8333333333333334,
+        "polymorphismClarity": 1
+      }
+    },
+    "createSpecialEvent": {
+      "integrationSimplicity": 88.3,
+      "agentReadiness": 83.3,
+      "integrationSubscores": {
+        "parameterSimplicity": 1,
+        "schemaSimplicity": 1,
+        "documentationQuality": 1,
+        "constraintClarity": 0,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "workflowClarity": 0.8333333333333334
+      },
+      "agentSubscores": {
+        "documentationQuality": 1,
+        "constraintClarity": 0,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "identifierClarity": 1,
+        "workflowClarity": 0.8333333333333334,
+        "polymorphismClarity": 1
+      }
+    },
+    "getSpecialEvent": {
+      "integrationSimplicity": 86.3,
+      "agentReadiness": 83.3,
+      "integrationSubscores": {
+        "parameterSimplicity": 0.9,
+        "schemaSimplicity": 1,
+        "documentationQuality": 1,
+        "constraintClarity": 0,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "workflowClarity": 0.8333333333333334
+      },
+      "agentSubscores": {
+        "documentationQuality": 1,
+        "constraintClarity": 0,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "identifierClarity": 1,
+        "workflowClarity": 0.8333333333333334,
+        "polymorphismClarity": 1
+      }
+    },
+    "deleteSpecialEvent": {
+      "integrationSimplicity": 71.3,
+      "agentReadiness": 63.3,
+      "integrationSubscores": {
+        "parameterSimplicity": 0.9,
+        "schemaSimplicity": 1,
+        "documentationQuality": 1,
+        "constraintClarity": 0,
+        "exampleCoverage": 0,
+        "errorClarity": 1,
+        "workflowClarity": 0.8333333333333334
+      },
+      "agentSubscores": {
+        "documentationQuality": 1,
+        "constraintClarity": 0,
+        "exampleCoverage": 0,
+        "errorClarity": 1,
+        "identifierClarity": 1,
+        "workflowClarity": 0.8333333333333334,
+        "polymorphismClarity": 1
+      }
+    },
+    "updateSpecialEvent": {
+      "integrationSimplicity": 86.3,
+      "agentReadiness": 83.3,
+      "integrationSubscores": {
+        "parameterSimplicity": 0.9,
+        "schemaSimplicity": 1,
+        "documentationQuality": 1,
+        "constraintClarity": 0,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "workflowClarity": 0.8333333333333334
+      },
+      "agentSubscores": {
+        "documentationQuality": 1,
+        "constraintClarity": 0,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "identifierClarity": 1,
+        "workflowClarity": 0.8333333333333334,
+        "polymorphismClarity": 1
+      }
+    },
+    "buyMuseumTickets": {
+      "integrationSimplicity": 86.1,
+      "agentReadiness": 84.1,
+      "integrationSubscores": {
+        "parameterSimplicity": 1,
+        "schemaSimplicity": 0.875,
+        "documentationQuality": 0.8333333333333334,
+        "constraintClarity": 0.2727272727272727,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "workflowClarity": 0.8333333333333334
+      },
+      "agentSubscores": {
+        "documentationQuality": 0.8333333333333334,
+        "constraintClarity": 0.2727272727272727,
+        "exampleCoverage": 1,
+        "errorClarity": 1,
+        "identifierClarity": 1,
+        "workflowClarity": 0.8333333333333334,
+        "polymorphismClarity": 1
+      }
+    },
+    "getTicketCode": {
+      "integrationSimplicity": 81.3,
+      "agentReadiness": 78.3,
+      "integrationSubscores": {
+        "parameterSimplicity": 0.9,
+        "schemaSimplicity": 1,
+        "documentationQuality": 1,
+        "constraintClarity": 1,
+        "exampleCoverage": 0,
+        "errorClarity": 1,
+        "workflowClarity": 0.8333333333333334
+      },
+      "agentSubscores": {
+        "documentationQuality": 1,
+        "constraintClarity": 1,
+        "exampleCoverage": 0,
+        "errorClarity": 1,
+        "identifierClarity": 1,
+        "workflowClarity": 0.8333333333333334,
+        "polymorphismClarity": 1
+      }
+    }
+  },
+  "workflowDepths": {
+    "getMuseumHours": 1,
+    "listSpecialEvents": 1,
+    "createSpecialEvent": 1,
+    "getSpecialEvent": 1,
+    "deleteSpecialEvent": 1,
+    "updateSpecialEvent": 1,
+    "buyMuseumTickets": 1,
+    "getTicketCode": 1
+  },
+  "hotspots": [
+    {
+      "path": "/special-events/{eventId}",
+      "method": "delete",
+      "operationId": "deleteSpecialEvent",
+      "integrationSimplicityScore": 71.3,
+      "agentReadinessScore": 63.3,
+      "reasons": [
+        "Missing response examples"
+      ]
+    },
+    {
+      "path": "/tickets/{ticketId}/qr",
+      "method": "get",
+      "operationId": "getTicketCode",
+      "integrationSimplicityScore": 81.3,
+      "agentReadinessScore": 78.3,
+      "reasons": [
+        "Missing response examples"
+      ]
+    }
+  ]
+}
+Document: museum.yaml score:
+
+museum.yaml: score processed in <test>ms
+
diff --git a/tests/e2e/score/score-minimal/openapi.yaml b/tests/e2e/score/score-minimal/openapi.yaml
new file mode 100644
index 0000000000..e3db706ac3
--- /dev/null
+++ b/tests/e2e/score/score-minimal/openapi.yaml
@@ -0,0 +1,46 @@
+openapi: 3.0.3
+info:
+  title: Minimal API
+  version: 0.1.0
+paths:
+  /items:
+    get:
+      operationId: listItems
+      parameters:
+        - name: id
+          in: query
+          schema:
+            type: string
+        - name: type
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    name:
+                      type: string
+    post:
+      operationId: createItem
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                value:
+                  type: string
+      responses:
+        '201':
+          description: Created
diff --git a/tests/e2e/score/score-minimal/snapshot.txt b/tests/e2e/score/score-minimal/snapshot.txt
new file mode 100644
index 0000000000..09037529a4
--- /dev/null
+++ b/tests/e2e/score/score-minimal/snapshot.txt
@@ -0,0 +1,56 @@
+
+  Scores
+
+  Integration Simplicity:  54.3/100
+  Agent Readiness:         41.7/100
+
+  Integration Simplicity Subscores
+
+  Parameter Simplicity     [██████████████████░░] 90%
+  Schema Simplicity        [████████████████░░░░] 81%
+  Documentation Quality    [░░░░░░░░░░░░░░░░░░░░] 0%
+  Constraint Clarity       [░░░░░░░░░░░░░░░░░░░░] 0%
+  Example Coverage         [░░░░░░░░░░░░░░░░░░░░] 0%
+  Error Clarity            [████████████████████] 100%
+  Workflow Clarity         [████████████████████] 100%
+
+  Agent Readiness Subscores
+
+  Documentation Quality    [░░░░░░░░░░░░░░░░░░░░] 0%
+  Constraint Clarity       [░░░░░░░░░░░░░░░░░░░░] 0%
+  Example Coverage         [░░░░░░░░░░░░░░░░░░░░] 0%
+  Error Clarity            [████████████████████] 100%
+  Identifier Clarity       [█████████████░░░░░░░] 67%
+  Workflow Clarity         [████████████████████] 100%
+  Polymorphism Clarity     [████████████████████] 100%
+
+  Raw Metrics Summary
+
+  Total operations: 2
+  Avg parameters/operation: 1.0
+  Avg max schema depth: 1.5
+  Avg polymorphism/operation: 0.0
+  Avg properties/operation: 2.0
+  Operations with request examples: 0/2 (0%)
+  Operations with response examples: 0/2 (0%)
+  Operations with description: 0/2 (0%)
+
+  Top 2 Hotspot Operations
+
+  GET /items (listItems)
+    Integration Simplicity: 51.0  Agent Readiness: 38.3
+    - Missing response examples
+    - Missing operation description
+    - No parameter descriptions
+    - Ambiguous identifiers (2)
+
+  POST /items (createItem)
+    Integration Simplicity: 57.5  Agent Readiness: 45.0
+    - Missing request and response examples
+    - Missing operation description
+
+
+Document: openapi.yaml score:
+
+openapi.yaml: score processed in <test>ms
+
diff --git a/tests/e2e/score/score-stylish/museum.yaml b/tests/e2e/score/score-stylish/museum.yaml
new file mode 120000
index 0000000000..5a811493e9
--- /dev/null
+++ b/tests/e2e/score/score-stylish/museum.yaml
@@ -0,0 +1 @@
+../../../../resources/museum.yaml
\ No newline at end of file
diff --git a/tests/e2e/score/score-stylish/snapshot.txt b/tests/e2e/score/score-stylish/snapshot.txt
new file mode 100644
index 0000000000..f75c76ea20
--- /dev/null
+++ b/tests/e2e/score/score-stylish/snapshot.txt
@@ -0,0 +1,52 @@
+
+  Scores
+
+  Integration Simplicity:  82.1/100
+  Agent Readiness:         81.2/100
+
+  Integration Simplicity Subscores
+
+  Parameter Simplicity     [█████████████████░░░] 86%
+  Schema Simplicity        [██████████████████░░] 92%
+  Documentation Quality    [███████████████████░] 94%
+  Constraint Clarity       [██████░░░░░░░░░░░░░░] 28%
+  Example Coverage         [███████████████░░░░░] 75%
+  Error Clarity            [████████████████████] 100%
+  Workflow Clarity         [█████████████████░░░] 83%
+
+  Agent Readiness Subscores
+
+  Documentation Quality    [███████████████████░] 94%
+  Constraint Clarity       [██████░░░░░░░░░░░░░░] 28%
+  Example Coverage         [███████████████░░░░░] 75%
+  Error Clarity            [████████████████████] 100%
+  Identifier Clarity       [████████████████████] 100%
+  Workflow Clarity         [█████████████████░░░] 83%
+  Polymorphism Clarity     [████████████████████] 100%
+
+  Raw Metrics Summary
+
+  Total operations: 8
+  Avg parameters/operation: 1.4
+  Avg max schema depth: 0.6
+  Avg polymorphism/operation: 0.0
+  Avg properties/operation: 4.0
+  Operations with request examples: 3/8 (38%)
+  Operations with response examples: 6/8 (75%)
+  Operations with description: 8/8 (100%)
+
+  Top 2 Hotspot Operations
+
+  DELETE /special-events/{eventId} (deleteSpecialEvent)
+    Integration Simplicity: 71.3  Agent Readiness: 63.3
+    - Missing response examples
+
+  GET /tickets/{ticketId}/qr (getTicketCode)
+    Integration Simplicity: 81.3  Agent Readiness: 78.3
+    - Missing response examples
+
+
+Document: museum.yaml score:
+
+museum.yaml: score processed in <test>ms
+
diff --git a/tests/e2e/score/score.test.ts b/tests/e2e/score/score.test.ts
new file mode 100644
index 0000000000..48751ee860
--- /dev/null
+++ b/tests/e2e/score/score.test.ts
@@ -0,0 +1,32 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getCommandOutput, getParams, cleanupOutput } from '../helpers.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const indexEntryPoint = join(process.cwd(), 'packages/cli/lib/index.js');
+
+describe('score', () => {
+  const folderPath = __dirname;
+
+  test('score should produce correct stylish output', async () => {
+    const testPath = join(folderPath, 'score-stylish');
+    const args = getParams(indexEntryPoint, ['score', 'museum.yaml']);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+
+  test('score should produce correct JSON output', async () => {
+    const testPath = join(folderPath, 'score-json');
+    const args = getParams(indexEntryPoint, ['score', 'museum.yaml', '--format=json']);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+
+  test('score should produce correct output for minimal API', async () => {
+    const testPath = join(folderPath, 'score-minimal');
+    const args = getParams(indexEntryPoint, ['score', 'openapi.yaml']);
+    const result = getCommandOutput(args, { testPath });
+    await expect(cleanupOutput(result)).toMatchFileSnapshot(join(testPath, 'snapshot.txt'));
+  });
+});

From 1fc409c68eebe23f8cf35db38e7f1843f5c95f92 Mon Sep 17 00:00:00 2001
From: Roman Hotsiy <gotsijroman@gmail.com>
Date: Thu, 12 Mar 2026 12:20:27 +0800
Subject: [PATCH 06/22] chore: refactor the visitor to use native pattern

---
 .../score/__tests__/collect-metrics.ts        |  47 ++
 .../score/__tests__/document-metrics.test.ts  |  90 +--
 .../score/__tests__/example-coverage.test.ts  |  34 +-
 .../commands/score/__tests__/index.test.ts    |   2 +-
 .../score/__tests__/schema-walker.test.ts     | 334 ----------
 .../commands/score/__tests__/scoring.test.ts  |   8 +-
 .../score/collectors/document-metrics.ts      | 599 ++++++++++--------
 .../score/collectors/schema-walker.ts         | 165 -----
 packages/cli/src/commands/score/index.ts      |   2 +-
 packages/cli/src/commands/score/types.ts      |  16 -
 10 files changed, 456 insertions(+), 841 deletions(-)
 create mode 100644 packages/cli/src/commands/score/__tests__/collect-metrics.ts
 delete mode 100644 packages/cli/src/commands/score/__tests__/schema-walker.test.ts
 delete mode 100644 packages/cli/src/commands/score/collectors/schema-walker.ts

diff --git a/packages/cli/src/commands/score/__tests__/collect-metrics.ts b/packages/cli/src/commands/score/__tests__/collect-metrics.ts
new file mode 100644
index 0000000000..f766e9a77f
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/collect-metrics.ts
@@ -0,0 +1,47 @@
+import {
+  normalizeTypes,
+  getTypes,
+  normalizeVisitors,
+  walkDocument,
+  resolveDocument,
+  BaseResolver,
+  Source,
+} from '@redocly/openapi-core';
+import type { Document, WalkContext } from '@redocly/openapi-core';
+
+import {
+  createScoreAccumulator,
+  createScoreVisitor,
+  getDocumentMetrics,
+} from '../collectors/document-metrics.js';
+import type { DocumentMetrics } from '../types.js';
+
+export async function collectDocumentMetrics(
+  doc: Record<string, unknown>
+): Promise<DocumentMetrics> {
+  const types = normalizeTypes(getTypes('oas3_0'), {});
+  const accumulator = createScoreAccumulator();
+  const visitor = createScoreVisitor(accumulator);
+  const normalizedVis = normalizeVisitors([{ severity: 'warn', ruleId: 'test', visitor }], types);
+  const source = new Source('test.yaml', JSON.stringify(doc));
+  const document: Document = { source, parsed: doc };
+  const externalRefResolver = new BaseResolver();
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+  const ctx: WalkContext = {
+    problems: [],
+    specVersion: 'oas3_0',
+    visitorsData: {},
+  };
+  walkDocument({
+    document,
+    rootType: types.Root,
+    normalizedVisitors: normalizedVis,
+    resolvedRefMap,
+    ctx,
+  });
+  return getDocumentMetrics(accumulator);
+}
diff --git a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
index bcb28577e8..93586eeb33 100644
--- a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
+++ b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
@@ -1,6 +1,6 @@
-import { collectDocumentMetrics } from '../collectors/document-metrics.js';
+import { collectDocumentMetrics } from './collect-metrics.js';
 
-function makeDoc(paths: Record<string, any>, components?: Record<string, any>) {
+function makeDoc(paths: Record<string, unknown>, components?: Record<string, unknown>) {
   return {
     openapi: '3.0.0',
     info: { title: 'Test', version: '1.0.0' },
@@ -10,13 +10,13 @@ function makeDoc(paths: Record<string, any>, components?: Record<string, any>) {
 }
 
 describe('collectDocumentMetrics', () => {
-  it('should return zero operations for empty paths', () => {
-    const result = collectDocumentMetrics(makeDoc({}));
+  it('should return zero operations for empty paths', async () => {
+    const result = await collectDocumentMetrics(makeDoc({}));
     expect(result.operationCount).toBe(0);
     expect(result.operations.size).toBe(0);
   });
 
-  it('should count operations across methods', () => {
+  it('should count operations across methods', async () => {
     const doc = makeDoc({
       '/items': {
         get: { operationId: 'listItems', responses: { '200': { description: 'OK' } } },
@@ -27,32 +27,32 @@ describe('collectDocumentMetrics', () => {
         delete: { operationId: 'deleteItem', responses: { '204': { description: 'Deleted' } } },
       },
     });
-    const result = collectDocumentMetrics(doc);
+    const result = await collectDocumentMetrics(doc);
     expect(result.operationCount).toBe(4);
   });
 
-  it('should use operationId as key when present', () => {
+  it('should use operationId as key when present', async () => {
     const doc = makeDoc({
       '/items': {
         get: { operationId: 'listItems', responses: { '200': { description: 'OK' } } },
       },
     });
-    const result = collectDocumentMetrics(doc);
+    const result = await collectDocumentMetrics(doc);
     expect(result.operations.has('listItems')).toBe(true);
   });
 
-  it('should fall back to METHOD path as key when no operationId', () => {
+  it('should fall back to METHOD path as key when no operationId', async () => {
     const doc = makeDoc({
       '/items': {
         get: { responses: { '200': { description: 'OK' } } },
       },
     });
-    const result = collectDocumentMetrics(doc);
+    const result = await collectDocumentMetrics(doc);
     expect(result.operations.has('GET /items')).toBe(true);
   });
 
   describe('parameter counting', () => {
-    it('should count resolved parameters via $ref', () => {
+    it('should count resolved parameters via $ref', async () => {
       const doc = makeDoc(
         {
           '/items': {
@@ -79,13 +79,13 @@ describe('collectDocumentMetrics', () => {
           },
         }
       );
-      const result = collectDocumentMetrics(doc);
+      const result = await collectDocumentMetrics(doc);
       const op = result.operations.get('listItems')!;
       expect(op.parameterCount).toBe(2);
       expect(op.paramsWithDescription).toBe(1);
     });
 
-    it('should merge path-level and operation-level parameters', () => {
+    it('should merge path-level and operation-level parameters', async () => {
       const doc = makeDoc({
         '/items/{id}': {
           parameters: [{ name: 'id', in: 'path', required: true, description: 'Item ID' }],
@@ -96,12 +96,12 @@ describe('collectDocumentMetrics', () => {
           },
         },
       });
-      const op = collectDocumentMetrics(doc).operations.get('getItem')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('getItem')!;
       expect(op.parameterCount).toBe(2);
       expect(op.requiredParameterCount).toBe(1);
     });
 
-    it('should let operation params override path params with same name+in', () => {
+    it('should let operation params override path params with same name+in', async () => {
       const doc = makeDoc({
         '/items/{id}': {
           parameters: [{ name: 'id', in: 'path', required: true }],
@@ -112,12 +112,12 @@ describe('collectDocumentMetrics', () => {
           },
         },
       });
-      const op = collectDocumentMetrics(doc).operations.get('getItem')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('getItem')!;
       expect(op.parameterCount).toBe(1);
       expect(op.paramsWithDescription).toBe(1);
     });
 
-    it('should detect ambiguous params without description', () => {
+    it('should detect ambiguous params without description', async () => {
       const doc = makeDoc({
         '/items': {
           get: {
@@ -131,13 +131,13 @@ describe('collectDocumentMetrics', () => {
           },
         },
       });
-      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
       expect(op.ambiguousIdentifierCount).toBe(2);
     });
   });
 
   describe('request body', () => {
-    it('should detect request body and resolve schema $ref', () => {
+    it('should detect request body and resolve schema $ref', async () => {
       const doc = makeDoc(
         {
           '/items': {
@@ -167,7 +167,7 @@ describe('collectDocumentMetrics', () => {
           },
         }
       );
-      const op = collectDocumentMetrics(doc).operations.get('createItem')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('createItem')!;
       expect(op.requestBodyPresent).toBe(true);
       expect(op.requestExamplePresent).toBe(true);
       expect(op.propertyCount).toBe(2);
@@ -176,7 +176,7 @@ describe('collectDocumentMetrics', () => {
       expect(op.schemaPropertiesWithDescription).toBe(1);
     });
 
-    it('should resolve requestBody $ref', () => {
+    it('should resolve requestBody $ref', async () => {
       const doc = makeDoc(
         {
           '/items': {
@@ -199,14 +199,14 @@ describe('collectDocumentMetrics', () => {
           },
         }
       );
-      const op = collectDocumentMetrics(doc).operations.get('createItem')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('createItem')!;
       expect(op.requestBodyPresent).toBe(true);
       expect(op.propertyCount).toBe(1);
     });
   });
 
   describe('responses', () => {
-    it('should resolve response $refs and count structured errors', () => {
+    it('should resolve response $refs and count structured errors', async () => {
       const doc = makeDoc(
         {
           '/items': {
@@ -233,12 +233,12 @@ describe('collectDocumentMetrics', () => {
           },
         }
       );
-      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
       expect(op.totalErrorResponses).toBe(2);
       expect(op.structuredErrorResponseCount).toBe(2);
     });
 
-    it('should count description-only error responses as structured', () => {
+    it('should count description-only error responses as structured', async () => {
       const doc = makeDoc({
         '/items': {
           get: {
@@ -250,12 +250,12 @@ describe('collectDocumentMetrics', () => {
           },
         },
       });
-      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
       expect(op.totalErrorResponses).toBe(1);
       expect(op.structuredErrorResponseCount).toBe(1);
     });
 
-    it('should count default as error response', () => {
+    it('should count default as error response', async () => {
       const doc = makeDoc({
         '/items': {
           get: {
@@ -267,11 +267,11 @@ describe('collectDocumentMetrics', () => {
           },
         },
       });
-      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
       expect(op.totalErrorResponses).toBe(1);
     });
 
-    it('should detect response examples and compute schema depth', () => {
+    it('should detect response examples and compute schema depth', async () => {
       const doc = makeDoc({
         '/items': {
           get: {
@@ -301,14 +301,14 @@ describe('collectDocumentMetrics', () => {
           },
         },
       });
-      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
       expect(op.responseExamplePresent).toBe(true);
       expect(op.maxResponseSchemaDepth).toBe(3);
     });
   });
 
   describe('schema property examples as coverage', () => {
-    it('should count schema property examples towards response example coverage', () => {
+    it('should count schema property examples towards response example coverage', async () => {
       const doc = makeDoc(
         {
           '/items': {
@@ -338,13 +338,13 @@ describe('collectDocumentMetrics', () => {
           },
         }
       );
-      const op = collectDocumentMetrics(doc).operations.get('listItems')!;
+      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
       expect(op.responseExamplePresent).toBe(true);
     });
   });
 
   describe('description and misc', () => {
-    it('should detect operation description presence', () => {
+    it('should detect operation description presence', async () => {
       const doc = makeDoc({
         '/a': {
           get: {
@@ -360,12 +360,12 @@ describe('collectDocumentMetrics', () => {
           },
         },
       });
-      const metrics = collectDocumentMetrics(doc);
+      const metrics = await collectDocumentMetrics(doc);
       expect(metrics.operations.get('withDesc')!.operationDescriptionPresent).toBe(true);
       expect(metrics.operations.get('noDesc')!.operationDescriptionPresent).toBe(false);
     });
 
-    it('should collect refs used across operations', () => {
+    it('should collect refs used across operations', async () => {
       const doc = makeDoc(
         {
           '/items': {
@@ -391,7 +391,7 @@ describe('collectDocumentMetrics', () => {
         },
         { schemas: { Item: { type: 'object' } } }
       );
-      const metrics = collectDocumentMetrics(doc);
+      const metrics = await collectDocumentMetrics(doc);
       expect(metrics.operations.get('listItems')!.refsUsed.has('#/components/schemas/Item')).toBe(
         true
       );
@@ -400,14 +400,16 @@ describe('collectDocumentMetrics', () => {
       );
     });
 
-    it('should handle missing/null paths gracefully', () => {
-      expect(collectDocumentMetrics({ openapi: '3.0.0' }).operationCount).toBe(0);
-      expect(collectDocumentMetrics({ openapi: '3.0.0', paths: null }).operationCount).toBe(0);
-    });
-
-    it('should skip non-object path items', () => {
-      const doc = makeDoc({ '/a': null, '/b': 'invalid' });
-      expect(collectDocumentMetrics(doc).operationCount).toBe(0);
+    it('should handle empty paths gracefully', async () => {
+      expect(
+        (
+          await collectDocumentMetrics({
+            openapi: '3.0.0',
+            info: { title: 'T', version: '1' },
+            paths: {},
+          })
+        ).operationCount
+      ).toBe(0);
     });
   });
 });
diff --git a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
index 18c9b3a71b..71bdf1d22d 100644
--- a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
+++ b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
@@ -1,10 +1,10 @@
-import { collectDocumentMetrics } from '../collectors/document-metrics.js';
 import {
   computeOperationIntegrationSubscores,
   computeOperationAgentSubscores,
   computeIntegrationSimplicity,
   computeAgentReadiness,
 } from '../scoring.js';
+import { collectDocumentMetrics } from './collect-metrics.js';
 
 describe('example coverage', () => {
   function makeDocument(overrides: {
@@ -50,9 +50,9 @@ describe('example coverage', () => {
     };
   }
 
-  it('should give perfect example coverage when both request and response examples present', () => {
+  it('should give perfect example coverage when both request and response examples present', async () => {
     const doc = makeDocument({ requestExample: true, responseExample: true, hasRequestBody: true });
-    const metrics = collectDocumentMetrics(doc);
+    const metrics = await collectDocumentMetrics(doc);
     const opMetrics = metrics.operations.get('createItem')!;
 
     expect(opMetrics.requestExamplePresent).toBe(true);
@@ -62,13 +62,13 @@ describe('example coverage', () => {
     expect(subscores.exampleCoverage).toBe(1);
   });
 
-  it('should give half example coverage when only response example present', () => {
+  it('should give half example coverage when only response example present', async () => {
     const doc = makeDocument({
       requestExample: false,
       responseExample: true,
       hasRequestBody: true,
     });
-    const metrics = collectDocumentMetrics(doc);
+    const metrics = await collectDocumentMetrics(doc);
     const opMetrics = metrics.operations.get('createItem')!;
 
     expect(opMetrics.requestExamplePresent).toBe(false);
@@ -78,20 +78,20 @@ describe('example coverage', () => {
     expect(subscores.exampleCoverage).toBe(0.5);
   });
 
-  it('should give zero example coverage when no examples', () => {
+  it('should give zero example coverage when no examples', async () => {
     const doc = makeDocument({
       requestExample: false,
       responseExample: false,
       hasRequestBody: true,
     });
-    const metrics = collectDocumentMetrics(doc);
+    const metrics = await collectDocumentMetrics(doc);
     const opMetrics = metrics.operations.get('createItem')!;
 
     const subscores = computeOperationIntegrationSubscores(opMetrics, 0);
     expect(subscores.exampleCoverage).toBe(0);
   });
 
-  it('should affect integration simplicity score positively with examples', () => {
+  it('should affect integration simplicity score positively with examples', async () => {
     const docWith = makeDocument({
       requestExample: true,
       responseExample: true,
@@ -103,8 +103,10 @@ describe('example coverage', () => {
       hasRequestBody: true,
     });
 
-    const metricsWithExamples = collectDocumentMetrics(docWith).operations.get('createItem')!;
-    const metricsWithout = collectDocumentMetrics(docWithout).operations.get('createItem')!;
+    const metricsWithExamples = (await collectDocumentMetrics(docWith)).operations.get(
+      'createItem'
+    )!;
+    const metricsWithout = (await collectDocumentMetrics(docWithout)).operations.get('createItem')!;
 
     const subWith = computeOperationIntegrationSubscores(metricsWithExamples, 0);
     const subWithout = computeOperationIntegrationSubscores(metricsWithout, 0);
@@ -115,7 +117,7 @@ describe('example coverage', () => {
     expect(scoreWith).toBeGreaterThan(scoreWithout);
   });
 
-  it('should affect agent readiness score positively with examples', () => {
+  it('should affect agent readiness score positively with examples', async () => {
     const docWith = makeDocument({
       requestExample: true,
       responseExample: true,
@@ -127,8 +129,10 @@ describe('example coverage', () => {
       hasRequestBody: true,
     });
 
-    const metricsWithExamples = collectDocumentMetrics(docWith).operations.get('createItem')!;
-    const metricsWithout = collectDocumentMetrics(docWithout).operations.get('createItem')!;
+    const metricsWithExamples = (await collectDocumentMetrics(docWith)).operations.get(
+      'createItem'
+    )!;
+    const metricsWithout = (await collectDocumentMetrics(docWithout)).operations.get('createItem')!;
 
     const subWith = computeOperationAgentSubscores(metricsWithExamples, 0);
     const subWithout = computeOperationAgentSubscores(metricsWithout, 0);
@@ -139,7 +143,7 @@ describe('example coverage', () => {
     expect(scoreWith).toBeGreaterThan(scoreWithout);
   });
 
-  it('should handle examples via examples map', () => {
+  it('should handle examples via examples map', async () => {
     const doc = {
       openapi: '3.0.0',
       info: { title: 'Test', version: '1.0.0' },
@@ -175,7 +179,7 @@ describe('example coverage', () => {
       },
     };
 
-    const metrics = collectDocumentMetrics(doc);
+    const metrics = await collectDocumentMetrics(doc);
     const opMetrics = metrics.operations.get('createItem')!;
     expect(opMetrics.requestExamplePresent).toBe(true);
     expect(opMetrics.responseExamplePresent).toBe(true);
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index 84bde4006f..45071d5f9b 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -90,7 +90,7 @@ function makeTestMetrics(overrides: Partial<OperationMetrics> = {}): OperationMe
 }
 
 function makeAccumulator(ops: Map<string, OperationMetrics> = new Map()): ScoreAccumulator {
-  return { operations: ops, currentPath: '', pathLevelParams: [] };
+  return { operations: ops, currentPath: '', pathLevelParams: [], current: null };
 }
 
 function createArgs(overrides: Partial<ScoreArgv> = {}) {
diff --git a/packages/cli/src/commands/score/__tests__/schema-walker.test.ts b/packages/cli/src/commands/score/__tests__/schema-walker.test.ts
deleted file mode 100644
index b1dd96af81..0000000000
--- a/packages/cli/src/commands/score/__tests__/schema-walker.test.ts
+++ /dev/null
@@ -1,334 +0,0 @@
-import { walkSchema } from '../collectors/schema-walker.js';
-
-describe('schema-walker', () => {
-  describe('depth', () => {
-    it('should return depth 0 for a flat schema with no properties', () => {
-      const schema = { type: 'string' };
-      expect(walkSchema(schema).depth).toBe(0);
-    });
-
-    it('should return depth 0 for null/undefined', () => {
-      expect(walkSchema(null).depth).toBe(0);
-      expect(walkSchema(undefined).depth).toBe(0);
-    });
-
-    it('should return depth 1 for a single level of properties', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          name: { type: 'string' },
-          age: { type: 'integer' },
-        },
-      };
-      expect(walkSchema(schema).depth).toBe(1);
-    });
-
-    it('should return depth 2 for nested objects', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          address: {
-            type: 'object',
-            properties: {
-              city: { type: 'string' },
-            },
-          },
-        },
-      };
-      expect(walkSchema(schema).depth).toBe(2);
-    });
-
-    it('should return depth 3 for deeply nested schemas', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          level1: {
-            type: 'object',
-            properties: {
-              level2: {
-                type: 'object',
-                properties: {
-                  level3: { type: 'string' },
-                },
-              },
-            },
-          },
-        },
-      };
-      expect(walkSchema(schema).depth).toBe(3);
-    });
-
-    it('should count array items as depth', () => {
-      const schema = {
-        type: 'array',
-        items: {
-          type: 'object',
-          properties: {
-            name: { type: 'string' },
-          },
-        },
-      };
-      expect(walkSchema(schema).depth).toBe(2);
-    });
-
-    it('should handle circular references gracefully', () => {
-      const schema: Record<string, any> = {
-        type: 'object',
-        properties: {},
-      };
-      schema.properties.self = schema;
-      const result = walkSchema(schema);
-      expect(result.depth).toBe(1);
-    });
-
-    it('should count additionalProperties depth', () => {
-      const schema = {
-        type: 'object',
-        additionalProperties: {
-          type: 'object',
-          properties: {
-            value: { type: 'string' },
-          },
-        },
-      };
-      expect(walkSchema(schema).depth).toBe(2);
-    });
-  });
-
-  describe('polymorphism counts', () => {
-    it('should count oneOf schemas', () => {
-      const schema = {
-        oneOf: [{ type: 'string' }, { type: 'integer' }, { type: 'boolean' }],
-      };
-      const result = walkSchema(schema);
-      expect(result.oneOfCount).toBe(3);
-      expect(result.anyOfCount).toBe(0);
-      expect(result.allOfCount).toBe(0);
-    });
-
-    it('should count anyOf schemas', () => {
-      const schema = {
-        anyOf: [{ type: 'string' }, { type: 'integer' }],
-      };
-      const result = walkSchema(schema);
-      expect(result.anyOfCount).toBe(2);
-      expect(result.oneOfCount).toBe(0);
-    });
-
-    it('should count allOf schemas', () => {
-      const schema = {
-        allOf: [
-          { type: 'object', properties: { a: { type: 'string' } } },
-          { type: 'object', properties: { b: { type: 'integer' } } },
-        ],
-      };
-      const result = walkSchema(schema);
-      expect(result.allOfCount).toBe(2);
-    });
-
-    it('should count nested polymorphism', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          field: {
-            oneOf: [
-              { type: 'string' },
-              {
-                anyOf: [{ type: 'integer' }, { type: 'boolean' }],
-              },
-            ],
-          },
-        },
-      };
-      const result = walkSchema(schema);
-      expect(result.oneOfCount).toBe(2);
-      expect(result.anyOfCount).toBe(2);
-    });
-
-    it('should detect discriminator', () => {
-      const schema = {
-        oneOf: [
-          { type: 'object', properties: { kind: { type: 'string' } } },
-          { type: 'object', properties: { kind: { type: 'string' } } },
-        ],
-        discriminator: { propertyName: 'kind' },
-      };
-      const result = walkSchema(schema);
-      expect(result.hasDiscriminator).toBe(true);
-    });
-
-    it('should not report discriminator when missing', () => {
-      const schema = {
-        oneOf: [{ type: 'string' }, { type: 'integer' }],
-      };
-      expect(walkSchema(schema).hasDiscriminator).toBe(false);
-    });
-  });
-
-  describe('property counting and description coverage', () => {
-    it('should count properties', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          a: { type: 'string' },
-          b: { type: 'integer' },
-          c: { type: 'boolean' },
-        },
-      };
-      const result = walkSchema(schema);
-      expect(result.propertyCount).toBe(3);
-      expect(result.totalProperties).toBe(3);
-    });
-
-    it('should count properties with descriptions', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          a: { type: 'string', description: 'First field' },
-          b: { type: 'integer' },
-          c: { type: 'boolean', description: 'Third field' },
-        },
-      };
-      const result = walkSchema(schema);
-      expect(result.propertiesWithDescription).toBe(2);
-    });
-  });
-
-  describe('constraint counting', () => {
-    it('should count enum as a constraint', () => {
-      const schema = { type: 'string', enum: ['a', 'b', 'c'] };
-      expect(walkSchema(schema).constraintCount).toBe(1);
-    });
-
-    it('should count format as a constraint', () => {
-      const schema = { type: 'string', format: 'email' };
-      expect(walkSchema(schema).constraintCount).toBe(1);
-    });
-
-    it('should count multiple constraints', () => {
-      const schema = {
-        type: 'string',
-        minLength: 1,
-        maxLength: 255,
-        pattern: '^[a-z]+$',
-        format: 'email',
-      };
-      expect(walkSchema(schema).constraintCount).toBe(4);
-    });
-
-    it('should count numeric constraints', () => {
-      const schema = {
-        type: 'integer',
-        minimum: 0,
-        maximum: 100,
-        multipleOf: 5,
-      };
-      expect(walkSchema(schema).constraintCount).toBe(3);
-    });
-  });
-
-  describe('$ref resolution', () => {
-    it('should resolve $ref schemas via resolveRef', () => {
-      const components = {
-        Address: {
-          type: 'object',
-          properties: {
-            city: { type: 'string', description: 'City name' },
-            zip: { type: 'string', pattern: '^[0-9]{5}$' },
-          },
-        },
-      };
-      const resolveRef = (ref: string) => {
-        if (ref === '#/components/schemas/Address') return components.Address;
-        return undefined;
-      };
-
-      const schema = { $ref: '#/components/schemas/Address' };
-      const result = walkSchema(schema, resolveRef);
-      expect(result.depth).toBe(1);
-      expect(result.propertyCount).toBe(2);
-      expect(result.propertiesWithDescription).toBe(1);
-      expect(result.constraintCount).toBe(1);
-    });
-
-    it('should resolve nested $ref in properties', () => {
-      const components = {
-        Name: { type: 'string', minLength: 1 },
-      };
-      const resolveRef = (ref: string) => {
-        if (ref === '#/components/schemas/Name') return components.Name;
-        return undefined;
-      };
-
-      const schema = {
-        type: 'object',
-        properties: {
-          name: { $ref: '#/components/schemas/Name' },
-          age: { type: 'integer' },
-        },
-      };
-      const result = walkSchema(schema, resolveRef);
-      expect(result.propertyCount).toBe(2);
-      expect(result.constraintCount).toBe(1);
-    });
-  });
-
-  describe('const constraint', () => {
-    it('should count const as a constraint', () => {
-      const schema = { type: 'string', const: 'fixed' };
-      expect(walkSchema(schema).constraintCount).toBe(1);
-    });
-  });
-
-  describe('property-level examples', () => {
-    it('should count properties with example keyword', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          id: { type: 'string', example: 'abc123' },
-          name: { type: 'string' },
-        },
-      };
-      const result = walkSchema(schema);
-      expect(result.propertiesWithExamples).toBe(1);
-    });
-
-    it('should count properties with examples keyword', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          status: { type: 'string', examples: ['active', 'inactive'] },
-          name: { type: 'string' },
-        },
-      };
-      const result = walkSchema(schema);
-      expect(result.propertiesWithExamples).toBe(1);
-    });
-  });
-
-  describe('writable fields', () => {
-    it('should count writable top-level fields', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          id: { type: 'string', readOnly: true },
-          name: { type: 'string' },
-          email: { type: 'string' },
-        },
-      };
-      const result = walkSchema(schema);
-      expect(result.writableTopLevelFieldCount).toBe(2);
-    });
-
-    it('should count all fields as writable when none are readOnly', () => {
-      const schema = {
-        type: 'object',
-        properties: {
-          a: { type: 'string' },
-          b: { type: 'string' },
-        },
-      };
-      expect(walkSchema(schema).writableTopLevelFieldCount).toBe(2);
-    });
-  });
-});
diff --git a/packages/cli/src/commands/score/__tests__/scoring.test.ts b/packages/cli/src/commands/score/__tests__/scoring.test.ts
index 3aa9e6edd6..acbfb8583c 100644
--- a/packages/cli/src/commands/score/__tests__/scoring.test.ts
+++ b/packages/cli/src/commands/score/__tests__/scoring.test.ts
@@ -1,4 +1,3 @@
-import { collectDocumentMetrics } from '../collectors/document-metrics.js';
 import { DEFAULT_SCORING_CONSTANTS } from '../constants.js';
 import {
   computeOperationIntegrationSubscores,
@@ -9,6 +8,7 @@ import {
   computeDocumentScores,
 } from '../scoring.js';
 import type { OperationMetrics, ScoringConstants } from '../types.js';
+import { collectDocumentMetrics } from './collect-metrics.js';
 
 function makeBaseMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetrics {
   return {
@@ -121,7 +121,7 @@ describe('scoring', () => {
   });
 
   describe('determinism', () => {
-    it('should produce identical scores for the same input', () => {
+    it('should produce identical scores for the same input', async () => {
       const doc = {
         openapi: '3.0.0',
         info: { title: 'Test', version: '1.0.0' },
@@ -187,8 +187,8 @@ describe('scoring', () => {
         },
       };
 
-      const metrics1 = collectDocumentMetrics(doc);
-      const metrics2 = collectDocumentMetrics(doc);
+      const metrics1 = await collectDocumentMetrics(doc);
+      const metrics2 = await collectDocumentMetrics(doc);
 
       const depths1 = new Map(Array.from(metrics1.operations.keys()).map((k) => [k, 0]));
       const depths2 = new Map(Array.from(metrics2.operations.keys()).map((k) => [k, 0]));
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
index fefe4b4d79..f03512f110 100644
--- a/packages/cli/src/commands/score/collectors/document-metrics.ts
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -1,13 +1,84 @@
-import { AMBIGUOUS_PARAM_NAMES } from '../constants.js';
-import type { DocumentMetrics, OperationMetrics, RefResolver } from '../types.js';
-import { walkSchema } from './schema-walker.js';
+import type {
+  Oas3Visitor,
+  UserContext,
+  Oas3PathItem,
+  Oas3Operation,
+  Oas3Parameter,
+  Oas3Schema,
+  Oas3_1Schema,
+  Referenced,
+} from '@redocly/openapi-core';
 
-const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const;
+import { AMBIGUOUS_PARAM_NAMES } from '../constants.js';
+import type { DocumentMetrics, OperationMetrics } from '../types.js';
+
+type Schema = Oas3Schema | Oas3_1Schema;
+type Param = Oas3Parameter<Schema>;
+
+const CONSTRAINT_KEYS: readonly string[] = [
+  'enum',
+  'const',
+  'format',
+  'pattern',
+  'minimum',
+  'maximum',
+  'minLength',
+  'maxLength',
+  'minItems',
+  'maxItems',
+  'minProperties',
+  'maxProperties',
+  'multipleOf',
+  'exclusiveMinimum',
+  'exclusiveMaximum',
+  'uniqueItems',
+];
+
+interface CurrentOperationContext {
+  path: string;
+  method: string;
+  operationId?: string;
+  operationDescriptionPresent: boolean;
+
+  parameterCount: number;
+  requiredParameterCount: number;
+  paramsWithDescription: number;
+  ambiguousIdentifierCount: number;
+
+  schemaDepth: number;
+  maxRequestSchemaDepth: number;
+  maxResponseSchemaDepth: number;
+  propertyCount: number;
+  totalSchemaProperties: number;
+  schemaPropertiesWithDescription: number;
+  constraintCount: number;
+  propertiesWithExamples: number;
+  polymorphismCount: number;
+  anyOfCount: number;
+  hasDiscriminator: boolean;
+
+  currentMediaTypeWritableFields: number;
+  writableTopLevelFieldCount: number;
+
+  requestBodyPresent: boolean;
+  requestExamplePresent: boolean;
+  responseExamplePresent: boolean;
+  structuredErrorResponseCount: number;
+  totalErrorResponses: number;
+
+  inRequestBody: boolean;
+  inResponse: boolean;
+  inMediaType: boolean;
+  currentResponseCode: string;
+
+  refsUsed: Set<string>;
+}
 
 export interface ScoreAccumulator {
   operations: Map<string, OperationMetrics>;
   currentPath: string;
-  pathLevelParams: any[];
+  pathLevelParams: Array<Referenced<Param>>;
+  current: CurrentOperationContext | null;
 }
 
 export function createScoreAccumulator(): ScoreAccumulator {
@@ -15,271 +86,298 @@ export function createScoreAccumulator(): ScoreAccumulator {
     operations: new Map(),
     currentPath: '',
     pathLevelParams: [],
+    current: null,
   };
 }
 
-export function createScoreVisitor(accumulator: ScoreAccumulator) {
+function createOperationContext(
+  path: string,
+  method: string,
+  operation: Oas3Operation
+): CurrentOperationContext {
   return {
-    Paths: {
-      PathItem: {
-        enter(pathItem: any, ctx: any) {
-          accumulator.currentPath = ctx.key as string;
-          accumulator.pathLevelParams = Array.isArray(pathItem.parameters)
-            ? pathItem.parameters
-            : [];
-        },
-        Operation: {
-          enter(operation: any, ctx: any) {
-            const path = accumulator.currentPath;
-            const method = ctx.key as string;
-            const resolveRef = wrapCtxResolve(ctx.resolve);
-
-            const opKey = operation.operationId ?? `${method.toUpperCase()} ${path}`;
-            const metrics = collectOperationMetrics(
-              path,
-              method,
-              operation,
-              accumulator.pathLevelParams,
-              resolveRef
-            );
-            accumulator.operations.set(opKey, metrics);
-          },
-        },
-      },
-    },
-  };
-}
-
-export function getDocumentMetrics(accumulator: ScoreAccumulator): DocumentMetrics {
-  return { operationCount: accumulator.operations.size, operations: accumulator.operations };
-}
+    path,
+    method,
+    operationId: operation.operationId,
+    operationDescriptionPresent: !!operation.description,
 
-function wrapCtxResolve(
-  resolve: (ref: { $ref: string }) => { node?: any } | undefined
-): RefResolver {
-  return (ref: string) => {
-    try {
-      const result = resolve({ $ref: ref });
-      return result?.node && typeof result.node === 'object'
-        ? (result.node as Record<string, any>)
-        : undefined;
-    } catch {
-      return undefined;
-    }
+    parameterCount: 0,
+    requiredParameterCount: 0,
+    paramsWithDescription: 0,
+    ambiguousIdentifierCount: 0,
+
+    schemaDepth: 0,
+    maxRequestSchemaDepth: 0,
+    maxResponseSchemaDepth: 0,
+    propertyCount: 0,
+    totalSchemaProperties: 0,
+    schemaPropertiesWithDescription: 0,
+    constraintCount: 0,
+    propertiesWithExamples: 0,
+    polymorphismCount: 0,
+    anyOfCount: 0,
+    hasDiscriminator: false,
+
+    currentMediaTypeWritableFields: 0,
+    writableTopLevelFieldCount: 0,
+
+    requestBodyPresent: false,
+    requestExamplePresent: false,
+    responseExamplePresent: false,
+    structuredErrorResponseCount: 0,
+    totalErrorResponses: 0,
+
+    inRequestBody: false,
+    inResponse: false,
+    inMediaType: false,
+    currentResponseCode: '',
+
+    refsUsed: new Set(),
   };
 }
 
-export function collectDocumentMetrics(document: Record<string, any>): DocumentMetrics {
-  const operations = new Map<string, OperationMetrics>();
-  const paths = document.paths;
-  const resolveRef = createSimpleRefResolver(document);
-
-  if (paths && typeof paths === 'object') {
-    for (const [pathStr, pathItem] of Object.entries(paths)) {
-      if (!pathItem || typeof pathItem !== 'object') continue;
-      const pathObj = resolveNode(pathItem as Record<string, any>, resolveRef);
-
-      const pathLevelParams: any[] = Array.isArray(pathObj.parameters) ? pathObj.parameters : [];
-
-      for (const method of HTTP_METHODS) {
-        const operation = pathObj[method];
-        if (!operation || typeof operation !== 'object') continue;
-
-        const opKey = operation.operationId ?? `${method.toUpperCase()} ${pathStr}`;
-        const metrics = collectOperationMetrics(
-          pathStr,
-          method,
-          operation as Record<string, any>,
-          pathLevelParams,
-          resolveRef
-        );
-        operations.set(opKey, metrics);
-      }
-    }
-  }
-
-  return { operationCount: operations.size, operations };
-}
-
-function createSimpleRefResolver(document: Record<string, any>): RefResolver {
-  return (ref: string) => {
-    if (!ref.startsWith('#/')) return undefined;
-    const parts = ref.slice(2).split('/');
-    let current: any = document;
-    for (const part of parts) {
-      if (!current || typeof current !== 'object') return undefined;
-      current = current[decodeURIComponent(part.replace(/~1/g, '/').replace(/~0/g, '~'))];
-    }
-    return current && typeof current === 'object' ? current : undefined;
+function buildOperationMetrics(ctx: CurrentOperationContext): OperationMetrics {
+  return {
+    path: ctx.path,
+    method: ctx.method,
+    operationId: ctx.operationId,
+    parameterCount: ctx.parameterCount,
+    requiredParameterCount: ctx.requiredParameterCount,
+    paramsWithDescription: ctx.paramsWithDescription,
+    requestBodyPresent: ctx.requestBodyPresent,
+    topLevelWritableFieldCount: ctx.writableTopLevelFieldCount,
+    maxRequestSchemaDepth: ctx.maxRequestSchemaDepth,
+    maxResponseSchemaDepth: ctx.maxResponseSchemaDepth,
+    polymorphismCount: ctx.polymorphismCount,
+    anyOfCount: ctx.anyOfCount,
+    hasDiscriminator: ctx.hasDiscriminator,
+    propertyCount: ctx.propertyCount,
+    operationDescriptionPresent: ctx.operationDescriptionPresent,
+    schemaPropertiesWithDescription: ctx.schemaPropertiesWithDescription,
+    totalSchemaProperties: ctx.totalSchemaProperties,
+    constraintCount: ctx.constraintCount,
+    requestExamplePresent: ctx.requestExamplePresent,
+    responseExamplePresent: ctx.responseExamplePresent,
+    structuredErrorResponseCount: ctx.structuredErrorResponseCount,
+    totalErrorResponses: ctx.totalErrorResponses,
+    ambiguousIdentifierCount: ctx.ambiguousIdentifierCount,
+    refsUsed: ctx.refsUsed,
   };
 }
 
-function resolveNode(node: Record<string, any>, resolveRef: RefResolver): Record<string, any> {
-  if (node.$ref && typeof node.$ref === 'string') {
-    return resolveRef(node.$ref) ?? node;
-  }
-  return node;
-}
+export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
+  return {
+    ref: {
+      enter(ref) {
+        accumulator.current?.refsUsed.add(ref.$ref);
+      },
+    },
+    RequestBody: {
+      enter() {
+        if (!accumulator.current) return;
+        accumulator.current.requestBodyPresent = true;
+        accumulator.current.inRequestBody = true;
+      },
+      leave() {
+        if (accumulator.current) accumulator.current.inRequestBody = false;
+      },
+    },
+    Response: {
+      enter(
+        response: { description?: string; content?: Record<string, unknown> },
+        ctx: UserContext
+      ) {
+        const current = accumulator.current;
+        if (!current) return;
+        const code = String(ctx.key);
+        current.inResponse = true;
+        current.currentResponseCode = code;
+
+        if (isErrorCode(code)) {
+          current.totalErrorResponses++;
+          if (!response.content && response.description) {
+            current.structuredErrorResponseCount++;
+          }
+        }
+      },
+      leave() {
+        if (accumulator.current) accumulator.current.inResponse = false;
+      },
+    },
+    MediaType: {
+      enter(mediaType: { example?: unknown; examples?: Record<string, unknown> }) {
+        const current = accumulator.current;
+        if (!current) return;
+        current.inMediaType = true;
+        current.schemaDepth = 0;
+
+        if (current.inRequestBody) {
+          current.currentMediaTypeWritableFields = 0;
+        }
 
-function collectOperationMetrics(
-  path: string,
-  method: string,
-  operation: Record<string, any>,
-  pathLevelParams: any[],
-  resolveRef: RefResolver
-): OperationMetrics {
-  const allParams = mergeParameters(pathLevelParams, operation.parameters ?? [], resolveRef);
-
-  let parameterCount = 0;
-  let requiredParameterCount = 0;
-  let paramsWithDescription = 0;
-  let ambiguousIdentifierCount = 0;
-
-  for (const param of allParams) {
-    if (!param || typeof param !== 'object') continue;
-    parameterCount++;
-    if (param.required) requiredParameterCount++;
-    if (param.description) paramsWithDescription++;
-    if (isAmbiguousParam(param)) ambiguousIdentifierCount++;
-  }
+        if (hasExample(mediaType)) {
+          if (current.inRequestBody) current.requestExamplePresent = true;
+          if (current.inResponse) current.responseExamplePresent = true;
+        }
 
-  const reqBody = operation.requestBody
-    ? resolveNode(operation.requestBody, resolveRef)
-    : undefined;
-  const requestBodyPresent = !!reqBody;
-  let maxRequestSchemaDepth = 0;
-  let topLevelWritableFieldCount = 0;
-  let requestExamplePresent = false;
-  let totalPolymorphism = 0;
-  let totalAnyOf = 0;
-  let hasDiscriminator = false;
-  let propertyCount = 0;
-  let schemaPropsWithDesc = 0;
-  let totalSchemaProps = 0;
-  let constraintCount = 0;
-  const refsUsed = new Set<string>();
-
-  if (reqBody) {
-    collectRefs(reqBody, refsUsed);
-
-    if (reqBody.content && typeof reqBody.content === 'object') {
-      for (const [, mediaType] of Object.entries(reqBody.content)) {
-        const mt = mediaType as Record<string, any>;
-        if (hasExample(mt)) {
-          requestExamplePresent = true;
+        if (current.inResponse && isErrorCode(current.currentResponseCode)) {
+          current.structuredErrorResponseCount++;
         }
-        if (mt.schema) {
-          const sm = walkSchema(mt.schema, resolveRef);
-          maxRequestSchemaDepth = Math.max(maxRequestSchemaDepth, sm.depth);
-          topLevelWritableFieldCount = Math.max(
-            topLevelWritableFieldCount,
-            sm.writableTopLevelFieldCount
+      },
+      leave() {
+        const current = accumulator.current;
+        if (!current) return;
+        if (current.inRequestBody) {
+          current.writableTopLevelFieldCount = Math.max(
+            current.writableTopLevelFieldCount,
+            current.currentMediaTypeWritableFields
           );
-          totalPolymorphism += sm.oneOfCount + sm.anyOfCount + sm.allOfCount;
-          totalAnyOf += sm.anyOfCount;
-          if (sm.hasDiscriminator) hasDiscriminator = true;
-          propertyCount += sm.propertyCount;
-          schemaPropsWithDesc += sm.propertiesWithDescription;
-          totalSchemaProps += sm.totalProperties;
-          constraintCount += sm.constraintCount;
-          if (sm.propertiesWithExamples > 0) requestExamplePresent = true;
-          collectRefs(mt.schema, refsUsed);
         }
-      }
-    }
-  }
-
-  let maxResponseSchemaDepth = 0;
-  let responseExamplePresent = false;
-  let structuredErrorResponseCount = 0;
-  let totalErrorResponses = 0;
-
-  if (operation.responses && typeof operation.responses === 'object') {
-    for (const [code, rawResponse] of Object.entries(operation.responses)) {
-      if (!rawResponse || typeof rawResponse !== 'object') continue;
-      const resp = resolveNode(rawResponse as Record<string, any>, resolveRef);
-      collectRefs(rawResponse as Record<string, any>, refsUsed);
-
-      const isError = isErrorCode(code);
-      if (isError) totalErrorResponses++;
-
-      const hasContent = resp.content && typeof resp.content === 'object';
-      if (hasContent) {
-        for (const [, mediaType] of Object.entries(resp.content)) {
-          const mt = mediaType as Record<string, any>;
-          if (hasExample(mt)) {
-            responseExamplePresent = true;
+        current.inMediaType = false;
+      },
+    },
+    SchemaProperties: {
+      enter(properties: Record<string, Referenced<Schema>>, ctx: UserContext) {
+        const current = accumulator.current;
+        if (!current?.inMediaType) return;
+
+        const entries = Object.values(properties);
+        current.totalSchemaProperties += entries.length;
+        current.propertyCount += entries.length;
+
+        const isRootLevel = current.schemaDepth === 1;
+
+        for (const prop of entries) {
+          const resolved =
+            '$ref' in prop && prop.$ref
+              ? (ctx.resolve(prop).node ?? (prop as Schema))
+              : (prop as Schema);
+
+          if (resolved.description) current.schemaPropertiesWithDescription++;
+          if (resolved.example !== undefined || ('examples' in resolved && resolved.examples)) {
+            current.propertiesWithExamples++;
           }
-          if (mt.schema) {
-            const sm = walkSchema(mt.schema, resolveRef);
-            maxResponseSchemaDepth = Math.max(maxResponseSchemaDepth, sm.depth);
-            totalPolymorphism += sm.oneOfCount + sm.anyOfCount + sm.allOfCount;
-            totalAnyOf += sm.anyOfCount;
-            if (sm.hasDiscriminator) hasDiscriminator = true;
-            propertyCount += sm.propertyCount;
-            schemaPropsWithDesc += sm.propertiesWithDescription;
-            totalSchemaProps += sm.totalProperties;
-            constraintCount += sm.constraintCount;
-            if (sm.propertiesWithExamples > 0) responseExamplePresent = true;
-            collectRefs(mt.schema, refsUsed);
+          if (isRootLevel && current.inRequestBody && !resolved.readOnly) {
+            current.currentMediaTypeWritableFields++;
           }
+        }
 
-          if (isError) {
-            structuredErrorResponseCount++;
+        if (current.propertiesWithExamples > 0) {
+          if (current.inRequestBody) current.requestExamplePresent = true;
+          if (current.inResponse) current.responseExamplePresent = true;
+        }
+      },
+    },
+    Schema: {
+      enter(schema: Schema) {
+        const current = accumulator.current;
+        if (!current?.inMediaType) return;
+        current.schemaDepth++;
+
+        if (current.inRequestBody) {
+          current.maxRequestSchemaDepth = Math.max(
+            current.maxRequestSchemaDepth,
+            current.schemaDepth - 1
+          );
+        }
+        if (current.inResponse) {
+          current.maxResponseSchemaDepth = Math.max(
+            current.maxResponseSchemaDepth,
+            current.schemaDepth - 1
+          );
+        }
+
+        for (const key of CONSTRAINT_KEYS) {
+          if ((schema as Record<string, unknown>)[key] !== undefined) {
+            current.constraintCount++;
           }
         }
-      } else if (isError && resp.description) {
-        structuredErrorResponseCount++;
-      }
-    }
-  }
 
-  return {
-    path,
-    method,
-    operationId: operation.operationId,
-    parameterCount,
-    requiredParameterCount,
-    paramsWithDescription,
-    requestBodyPresent,
-    topLevelWritableFieldCount,
-    maxRequestSchemaDepth,
-    maxResponseSchemaDepth,
-    polymorphismCount: totalPolymorphism,
-    anyOfCount: totalAnyOf,
-    hasDiscriminator,
-    propertyCount,
-    operationDescriptionPresent: !!operation.description,
-    schemaPropertiesWithDescription: schemaPropsWithDesc,
-    totalSchemaProperties: totalSchemaProps,
-    constraintCount,
-    requestExamplePresent,
-    responseExamplePresent,
-    structuredErrorResponseCount,
-    totalErrorResponses,
-    ambiguousIdentifierCount,
-    refsUsed,
+        if (schema.discriminator?.propertyName) {
+          current.hasDiscriminator = true;
+        }
+
+        if (Array.isArray(schema.oneOf)) {
+          current.polymorphismCount += schema.oneOf.length;
+        }
+        if (Array.isArray(schema.anyOf)) {
+          current.polymorphismCount += schema.anyOf.length;
+          current.anyOfCount += schema.anyOf.length;
+        }
+        if (Array.isArray(schema.allOf)) {
+          current.polymorphismCount += schema.allOf.length;
+        }
+      },
+      leave() {
+        if (accumulator.current?.inMediaType) {
+          accumulator.current.schemaDepth--;
+        }
+      },
+    },
+    Paths: {
+      PathItem: {
+        enter(pathItem: Oas3PathItem, ctx: UserContext) {
+          accumulator.currentPath = String(ctx.key);
+          accumulator.pathLevelParams = pathItem.parameters ?? [];
+        },
+        Operation: {
+          enter(operation: Oas3Operation, ctx: UserContext) {
+            const method = String(ctx.key);
+            const current = createOperationContext(accumulator.currentPath, method, operation);
+            accumulator.current = current;
+
+            const merged = mergeParameters(
+              accumulator.pathLevelParams,
+              operation.parameters ?? [],
+              ctx.resolve
+            );
+            for (const param of merged.values()) {
+              current.parameterCount++;
+              if (param.required) current.requiredParameterCount++;
+              if (param.description) current.paramsWithDescription++;
+              if (isAmbiguousParam(param)) current.ambiguousIdentifierCount++;
+            }
+          },
+          leave(operation: Oas3Operation) {
+            const current = accumulator.current;
+            if (!current) return;
+            const opKey =
+              operation.operationId ?? `${current.method.toUpperCase()} ${current.path}`;
+            accumulator.operations.set(opKey, buildOperationMetrics(current));
+            accumulator.current = null;
+          },
+        },
+      },
+    },
   };
 }
 
-function mergeParameters(pathLevel: any[], opLevel: any[], resolveRef: RefResolver): any[] {
-  const merged = new Map<string, any>();
+export function getDocumentMetrics(accumulator: ScoreAccumulator): DocumentMetrics {
+  return { operationCount: accumulator.operations.size, operations: accumulator.operations };
+}
+
+function resolveParam(raw: Referenced<Param>, resolve: UserContext['resolve']): Param | undefined {
+  return resolve<Param>(raw).node;
+}
+
+function mergeParameters(
+  pathLevel: Array<Referenced<Param>>,
+  opLevel: Array<Referenced<Param>>,
+  resolve: UserContext['resolve']
+): Map<string, Param> {
+  const merged = new Map<string, Param>();
   for (const raw of pathLevel) {
-    const p = raw && typeof raw === 'object' ? resolveNode(raw, resolveRef) : raw;
-    if (p && typeof p === 'object' && p.name && p.in) {
-      merged.set(`${p.in}:${p.name}`, p);
-    }
+    const p = resolveParam(raw, resolve);
+    if (p?.name && p.in) merged.set(`${p.in}:${p.name}`, p);
   }
   for (const raw of opLevel) {
-    const p = raw && typeof raw === 'object' ? resolveNode(raw, resolveRef) : raw;
-    if (p && typeof p === 'object' && p.name && p.in) {
-      merged.set(`${p.in}:${p.name}`, p);
-    }
+    const p = resolveParam(raw, resolve);
+    if (p?.name && p.in) merged.set(`${p.in}:${p.name}`, p);
   }
-  return Array.from(merged.values());
+  return merged;
 }
 
-function hasExample(mediaType: Record<string, any>): boolean {
+function hasExample(mediaType: { example?: unknown; examples?: Record<string, unknown> }): boolean {
   if (mediaType.example !== undefined) return true;
   if (mediaType.examples && typeof mediaType.examples === 'object') {
     return Object.keys(mediaType.examples).length > 0;
@@ -287,7 +385,7 @@ function hasExample(mediaType: Record<string, any>): boolean {
   return false;
 }
 
-function isAmbiguousParam(param: Record<string, any>): boolean {
+function isAmbiguousParam(param: Param): boolean {
   if (param.description) return false;
   const name = (param.name ?? '').toLowerCase();
   return AMBIGUOUS_PARAM_NAMES.has(name);
@@ -298,24 +396,3 @@ function isErrorCode(code: string): boolean {
   const num = parseInt(code, 10);
   return num >= 400 && num < 600;
 }
-
-function collectRefs(node: any, refs: Set<string>, seen?: Set<any>): void {
-  if (!node || typeof node !== 'object') return;
-  seen = seen ?? new Set();
-  if (seen.has(node)) return;
-  seen.add(node);
-
-  if (typeof node.$ref === 'string') {
-    refs.add(node.$ref);
-  }
-
-  if (Array.isArray(node)) {
-    for (const item of node) {
-      collectRefs(item, refs, seen);
-    }
-  } else {
-    for (const val of Object.values(node)) {
-      collectRefs(val, refs, seen);
-    }
-  }
-}
diff --git a/packages/cli/src/commands/score/collectors/schema-walker.ts b/packages/cli/src/commands/score/collectors/schema-walker.ts
deleted file mode 100644
index 3425fb8a70..0000000000
--- a/packages/cli/src/commands/score/collectors/schema-walker.ts
+++ /dev/null
@@ -1,165 +0,0 @@
-import type { RefResolver, SchemaMetrics } from '../types.js';
-
-const CONSTRAINT_KEYS = [
-  'enum',
-  'const',
-  'format',
-  'pattern',
-  'minimum',
-  'maximum',
-  'minLength',
-  'maxLength',
-  'minItems',
-  'maxItems',
-  'minProperties',
-  'maxProperties',
-  'multipleOf',
-  'exclusiveMinimum',
-  'exclusiveMaximum',
-  'uniqueItems',
-] as const;
-
-export function walkSchema(
-  schema: Record<string, any> | undefined | null,
-  resolveRef?: RefResolver,
-  seen?: Set<object>
-): SchemaMetrics {
-  const result: SchemaMetrics = {
-    depth: 0,
-    propertyCount: 0,
-    oneOfCount: 0,
-    anyOfCount: 0,
-    allOfCount: 0,
-    hasDiscriminator: false,
-    propertiesWithDescription: 0,
-    totalProperties: 0,
-    constraintCount: 0,
-    writableTopLevelFieldCount: 0,
-    propertiesWithExamples: 0,
-  };
-
-  if (!schema || typeof schema !== 'object') {
-    return result;
-  }
-
-  if (schema.$ref && typeof schema.$ref === 'string' && resolveRef) {
-    const resolved = resolveRef(schema.$ref);
-    if (resolved) {
-      return walkSchema(resolved, resolveRef, seen);
-    }
-    return result;
-  }
-
-  seen = seen ?? new Set();
-  if (seen.has(schema)) {
-    return result;
-  }
-  seen.add(schema);
-
-  if (schema.discriminator && schema.discriminator.propertyName) {
-    result.hasDiscriminator = true;
-  }
-
-  for (const key of CONSTRAINT_KEYS) {
-    if (schema[key] !== undefined) {
-      result.constraintCount++;
-    }
-  }
-
-  if (schema.properties && typeof schema.properties === 'object') {
-    const props = Object.entries(schema.properties) as [string, Record<string, any>][];
-    result.totalProperties += props.length;
-    result.propertyCount += props.length;
-
-    for (const [, rawPropSchema] of props) {
-      const propSchema =
-        rawPropSchema?.$ref && resolveRef
-          ? (resolveRef(rawPropSchema.$ref) ?? rawPropSchema)
-          : rawPropSchema;
-      if (propSchema && typeof propSchema === 'object') {
-        if (propSchema.description) {
-          result.propertiesWithDescription++;
-        }
-        if (propSchema.example !== undefined || propSchema.examples) {
-          result.propertiesWithExamples++;
-        }
-        if (!propSchema.readOnly) {
-          result.writableTopLevelFieldCount++;
-        }
-      }
-    }
-
-    let maxChildDepth = 0;
-    for (const [, rawPropSchema] of props) {
-      const propSchema =
-        rawPropSchema?.$ref && resolveRef
-          ? (resolveRef(rawPropSchema.$ref) ?? rawPropSchema)
-          : rawPropSchema;
-      if (propSchema && typeof propSchema === 'object') {
-        const child = walkSchema(propSchema, resolveRef, seen);
-        maxChildDepth = Math.max(maxChildDepth, child.depth);
-        mergeChildMetrics(result, child);
-      }
-    }
-    result.depth = Math.max(result.depth, 1 + maxChildDepth);
-  }
-
-  if (schema.items && typeof schema.items === 'object' && schema.items !== true) {
-    const child = walkSchema(schema.items as Record<string, any>, resolveRef, seen);
-    result.depth = Math.max(result.depth, 1 + child.depth);
-    mergeChildMetrics(result, child);
-  }
-
-  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
-    const child = walkSchema(schema.additionalProperties as Record<string, any>, resolveRef, seen);
-    result.depth = Math.max(result.depth, 1 + child.depth);
-    mergeChildMetrics(result, child);
-  }
-
-  walkComposition(schema, 'oneOf', result, resolveRef, seen);
-  walkComposition(schema, 'anyOf', result, resolveRef, seen);
-  walkComposition(schema, 'allOf', result, resolveRef, seen);
-
-  return result;
-}
-
-function walkComposition(
-  schema: Record<string, any>,
-  keyword: 'oneOf' | 'anyOf' | 'allOf',
-  result: SchemaMetrics,
-  resolveRef: RefResolver | undefined,
-  seen: Set<object>
-): void {
-  const arr = schema[keyword];
-  if (!Array.isArray(arr) || arr.length === 0) return;
-
-  const countKey = `${keyword}Count` as keyof Pick<
-    SchemaMetrics,
-    'oneOfCount' | 'anyOfCount' | 'allOfCount'
-  >;
-  result[countKey] += arr.length;
-
-  let maxChildDepth = 0;
-  for (const subSchema of arr) {
-    if (subSchema && typeof subSchema === 'object') {
-      const child = walkSchema(subSchema, resolveRef, seen);
-      maxChildDepth = Math.max(maxChildDepth, child.depth);
-      mergeChildMetrics(result, child);
-    }
-  }
-  result.depth = Math.max(result.depth, 1 + maxChildDepth);
-}
-
-function mergeChildMetrics(parent: SchemaMetrics, child: SchemaMetrics): void {
-  parent.oneOfCount += child.oneOfCount;
-  parent.anyOfCount += child.anyOfCount;
-  parent.allOfCount += child.allOfCount;
-  parent.propertyCount += child.propertyCount;
-  parent.propertiesWithDescription += child.propertiesWithDescription;
-  parent.totalProperties += child.totalProperties;
-  parent.constraintCount += child.constraintCount;
-  parent.propertiesWithExamples += child.propertiesWithExamples;
-  if (child.hasDiscriminator) {
-    parent.hasDiscriminator = true;
-  }
-}
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
index 0cc0f2120a..9a8253d016 100644
--- a/packages/cli/src/commands/score/index.ts
+++ b/packages/cli/src/commands/score/index.ts
@@ -72,7 +72,7 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
   };
 
   const normalizedVisitors = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
+    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor }],
     types
   );
 
diff --git a/packages/cli/src/commands/score/types.ts b/packages/cli/src/commands/score/types.ts
index b05f7bbe75..5b346f6c25 100644
--- a/packages/cli/src/commands/score/types.ts
+++ b/packages/cli/src/commands/score/types.ts
@@ -1,19 +1,3 @@
-export type RefResolver = (ref: string) => Record<string, any> | undefined;
-
-export interface SchemaMetrics {
-  depth: number;
-  propertyCount: number;
-  oneOfCount: number;
-  anyOfCount: number;
-  allOfCount: number;
-  hasDiscriminator: boolean;
-  propertiesWithDescription: number;
-  totalProperties: number;
-  constraintCount: number;
-  writableTopLevelFieldCount: number;
-  propertiesWithExamples: number;
-}
-
 export interface OperationMetrics {
   path: string;
   method: string;

From f7d269910f0cb62a7db8a671c658b3efc0cce2e8 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Thu, 12 Mar 2026 07:29:38 -0500
Subject: [PATCH 07/22] chore: fix semantic line breaks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Jacek Łękawa <164185257+JLekawa@users.noreply.github.com>
---
 .changeset/add-score-command.md | 3 ++-
 docs/@v2/commands/score.md      | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.changeset/add-score-command.md b/.changeset/add-score-command.md
index 5a8799de03..5187db8b6d 100644
--- a/.changeset/add-score-command.md
+++ b/.changeset/add-score-command.md
@@ -2,4 +2,5 @@
 '@redocly/cli': minor
 ---
 
-Added new `score` command that analyzes OpenAPI 3.x descriptions and produces integration simplicity and AI agent readiness scores (0-100). Reports normalized subscores, raw per-operation metrics, and top hotspot operations with human-readable explanations. Supports `--format=stylish` (default) and `--format=json` output.
+Added new `score` command that analyzes OpenAPI 3.x descriptions and produces integration simplicity and AI agent readiness scores (0-100).
+Reports normalized subscores, raw per-operation metrics, and top hotspot operations with human-readable explanations. Supports `--format=stylish` (default) and `--format=json` output.
diff --git a/docs/@v2/commands/score.md b/docs/@v2/commands/score.md
index 596fa29914..6cb42b3169 100644
--- a/docs/@v2/commands/score.md
+++ b/docs/@v2/commands/score.md
@@ -10,7 +10,8 @@ The `score` command analyzes an OpenAPI description and produces two composite s
 In addition to the top-level scores, the command reports normalized subscores, raw metrics for every operation, and a list of **hotspot operations** — the endpoints most likely to cause integration friction — along with human-readable explanations.
 
 {% admonition type="warning" name="OpenAPI 3.x only" %}
-The `score` command supports OpenAPI 3.0, 3.1, and 3.2 descriptions. OpenAPI 2.0 (Swagger) and AsyncAPI are not currently supported.
+The `score` command supports OpenAPI 3.0, 3.1, and 3.2 descriptions.
+OpenAPI 2.0 (Swagger) and AsyncAPI are not currently supported.
 {% /admonition %}
 
 ### Metrics

From 54303d9a808b221ce7ccacffba8ac88bf50b1c19 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Fri, 13 Mar 2026 09:56:45 -0500
Subject: [PATCH 08/22] chore: refactor based on feedback

---
 docs/@v2/commands/score.md                    |  33 +-
 .../score/__tests__/document-metrics.test.ts  | 619 +++++++-----------
 .../score/__tests__/formatters.test.ts        | 307 ++++-----
 .../src/commands/score/formatters/stylish.ts  |   8 +-
 packages/cli/src/commands/score/index.ts      | 106 +--
 packages/cli/src/commands/score/scoring.ts    |  70 ++
 6 files changed, 447 insertions(+), 696 deletions(-)

diff --git a/docs/@v2/commands/score.md b/docs/@v2/commands/score.md
index 6cb42b3169..614dcf6818 100644
--- a/docs/@v2/commands/score.md
+++ b/docs/@v2/commands/score.md
@@ -33,15 +33,15 @@ The following raw metrics are collected per operation and aggregated across the
 | Request/response example coverage  | Whether request and response media types include `example` or `examples`.                                                            |
 | Structured error response coverage | How many 4xx/5xx responses include a content schema or meaningful description.                                                       |
 | Security scheme coverage           | Whether operations reference documented security schemes with descriptions.                                                          |
-| Workflow dependency depth          | Inferred from shared `$ref` usage across operations; deeper shared-schema graphs indicate more tightly coupled workflows.            |
+| Cross-operation dependency depth   | Inferred from shared `$ref` usage across operations; deeper shared-schema graphs indicate tightly coupled multi-step interactions.   |
 
 ### Subscores
 
 Subscores are normalized to 0–1 and grouped into two categories:
 
-**Integration Simplicity subscores:** `parameterSimplicity`, `schemaSimplicity`, `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `workflowClarity`.
+**Integration Simplicity subscores:** `parameterSimplicity`, `schemaSimplicity`, `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `dependencyClarity`.
 
-**Agent Readiness subscores:** `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `identifierClarity`, `workflowClarity`, `polymorphismClarity`.
+**Agent Readiness subscores:** `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `identifierClarity`, `dependencyClarity`, `polymorphismClarity`.
 
 ### Hotspots
 
@@ -66,7 +66,7 @@ redocly score <api> [--format=<option>] [--config=<path>]
 | Option        | Type    | Description                                                                                                                                    |
 | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | api           | string  | **REQUIRED.** Path to the API description filename or alias that you want to score. Refer to [the API section](#specify-api) for more details. |
-| --config      | string  | Specify path to the [configuration file](#use-alternative-configuration-file).                                                                 |
+| --config      | string  | Specify path to the [configuration file](../configuration/index.md).                                                                           |
 | --format      | string  | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`.                                                |
 | --help        | boolean | Show help.                                                                                                                                     |
 | --lint-config | string  | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`.             |
@@ -82,29 +82,6 @@ redocly score <api> [--format=<option>] [--config=<path>]
 redocly score openapi/openapi.yaml
 ```
 
-#### Pass an API alias
-
-Instead of a full path, you can use an API name from the `apis` section of your Redocly configuration file.
-
-```yaml
-apis:
-  core@v1:
-    root: ./openapi/api-description.json
-```
-
-```bash
-redocly score core@v1
-```
-
-### Use alternative configuration file
-
-By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory.
-Use the optional `--config` argument to provide an alternative path to a configuration file.
-
-```bash
-redocly score --config=./another/directory/config.yaml
-```
-
 ### Specify output format
 
 #### Stylish output (default)
@@ -125,7 +102,7 @@ The default output format shows a human-readable summary in your terminal:
   Constraint Clarity       [██████████░░░░░░░░░░] 50%
   Example Coverage         [████████████████████] 100%
   Error Clarity            [████████████████░░░░] 80%
-  Workflow Clarity         [██████████████████░░] 90%
+  Dependency Clarity       [██████████████████░░] 90%
 
   Top 3 Hotspot Operations
 
diff --git a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
index 93586eeb33..d971a5589f 100644
--- a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
+++ b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
@@ -1,415 +1,244 @@
+import { parseYaml } from '@redocly/openapi-core';
+import { outdent } from 'outdent';
+
 import { collectDocumentMetrics } from './collect-metrics.js';
 
-function makeDoc(paths: Record<string, unknown>, components?: Record<string, unknown>) {
-  return {
-    openapi: '3.0.0',
-    info: { title: 'Test', version: '1.0.0' },
-    paths,
-    ...(components ? { components } : {}),
-  };
+function yaml(source: string): Record<string, unknown> {
+  return parseYaml(source) as Record<string, unknown>;
 }
 
 describe('collectDocumentMetrics', () => {
-  it('should return zero operations for empty paths', async () => {
-    const result = await collectDocumentMetrics(makeDoc({}));
+  it('returns zero operations for empty paths', async () => {
+    const result = await collectDocumentMetrics(
+      yaml(outdent`
+        openapi: 3.0.0
+        info:
+          title: Test
+          version: '1.0'
+        paths: {}
+      `)
+    );
     expect(result.operationCount).toBe(0);
     expect(result.operations.size).toBe(0);
   });
 
-  it('should count operations across methods', async () => {
-    const doc = makeDoc({
-      '/items': {
-        get: { operationId: 'listItems', responses: { '200': { description: 'OK' } } },
-        post: { operationId: 'createItem', responses: { '201': { description: 'Created' } } },
-      },
-      '/items/{id}': {
-        get: { operationId: 'getItem', responses: { '200': { description: 'OK' } } },
-        delete: { operationId: 'deleteItem', responses: { '204': { description: 'Deleted' } } },
-      },
-    });
-    const result = await collectDocumentMetrics(doc);
-    expect(result.operationCount).toBe(4);
-  });
-
-  it('should use operationId as key when present', async () => {
-    const doc = makeDoc({
-      '/items': {
-        get: { operationId: 'listItems', responses: { '200': { description: 'OK' } } },
-      },
-    });
-    const result = await collectDocumentMetrics(doc);
+  it('counts operations, uses operationId as key or falls back to METHOD /path', async () => {
+    const result = await collectDocumentMetrics(
+      yaml(outdent`
+        openapi: 3.0.0
+        info:
+          title: Test
+          version: '1.0'
+        paths:
+          /items:
+            get:
+              operationId: listItems
+              responses:
+                '200':
+                  description: OK
+            post:
+              responses:
+                '201':
+                  description: Created
+          /items/{id}:
+            get:
+              operationId: getItem
+              responses:
+                '200':
+                  description: OK
+      `)
+    );
+    expect(result.operationCount).toBe(3);
     expect(result.operations.has('listItems')).toBe(true);
+    expect(result.operations.has('getItem')).toBe(true);
+    expect(result.operations.has('POST /items')).toBe(true);
   });
 
-  it('should fall back to METHOD path as key when no operationId', async () => {
-    const doc = makeDoc({
-      '/items': {
-        get: { responses: { '200': { description: 'OK' } } },
-      },
-    });
-    const result = await collectDocumentMetrics(doc);
-    expect(result.operations.has('GET /items')).toBe(true);
-  });
-
-  describe('parameter counting', () => {
-    it('should count resolved parameters via $ref', async () => {
-      const doc = makeDoc(
-        {
-          '/items': {
-            get: {
-              operationId: 'listItems',
-              parameters: [
-                { $ref: '#/components/parameters/Limit' },
-                { $ref: '#/components/parameters/Offset' },
-              ],
-              responses: { '200': { description: 'OK' } },
-            },
-          },
-        },
-        {
-          parameters: {
-            Limit: {
-              name: 'limit',
-              in: 'query',
-              required: false,
-              description: 'Max items',
-              schema: { type: 'integer' },
-            },
-            Offset: { name: 'offset', in: 'query', schema: { type: 'integer' } },
-          },
-        }
-      );
-      const result = await collectDocumentMetrics(doc);
-      const op = result.operations.get('listItems')!;
-      expect(op.parameterCount).toBe(2);
-      expect(op.paramsWithDescription).toBe(1);
-    });
-
-    it('should merge path-level and operation-level parameters', async () => {
-      const doc = makeDoc({
-        '/items/{id}': {
-          parameters: [{ name: 'id', in: 'path', required: true, description: 'Item ID' }],
-          get: {
-            operationId: 'getItem',
-            parameters: [{ name: 'fields', in: 'query' }],
-            responses: { '200': { description: 'OK' } },
-          },
-        },
-      });
-      const op = (await collectDocumentMetrics(doc)).operations.get('getItem')!;
-      expect(op.parameterCount).toBe(2);
-      expect(op.requiredParameterCount).toBe(1);
-    });
-
-    it('should let operation params override path params with same name+in', async () => {
-      const doc = makeDoc({
-        '/items/{id}': {
-          parameters: [{ name: 'id', in: 'path', required: true }],
-          get: {
-            operationId: 'getItem',
-            parameters: [{ name: 'id', in: 'path', required: true, description: 'Overridden' }],
-            responses: { '200': { description: 'OK' } },
-          },
-        },
-      });
-      const op = (await collectDocumentMetrics(doc)).operations.get('getItem')!;
-      expect(op.parameterCount).toBe(1);
-      expect(op.paramsWithDescription).toBe(1);
-    });
-
-    it('should detect ambiguous params without description', async () => {
-      const doc = makeDoc({
-        '/items': {
-          get: {
-            operationId: 'listItems',
-            parameters: [
-              { name: 'id', in: 'query' },
-              { name: 'type', in: 'query' },
-              { name: 'category', in: 'query', description: 'Filter category' },
-            ],
-            responses: { '200': { description: 'OK' } },
-          },
-        },
-      });
-      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
-      expect(op.ambiguousIdentifierCount).toBe(2);
-    });
-  });
-
-  describe('request body', () => {
-    it('should detect request body and resolve schema $ref', async () => {
-      const doc = makeDoc(
-        {
-          '/items': {
-            post: {
-              operationId: 'createItem',
-              requestBody: {
-                content: {
-                  'application/json': {
-                    schema: { $ref: '#/components/schemas/Item' },
-                    example: { name: 'test' },
-                  },
-                },
-              },
-              responses: { '201': { description: 'Created' } },
-            },
-          },
-        },
-        {
-          schemas: {
-            Item: {
-              type: 'object',
-              properties: {
-                name: { type: 'string', description: 'Item name', minLength: 1 },
-                price: { type: 'integer', minimum: 0 },
-              },
-            },
-          },
-        }
-      );
-      const op = (await collectDocumentMetrics(doc)).operations.get('createItem')!;
-      expect(op.requestBodyPresent).toBe(true);
-      expect(op.requestExamplePresent).toBe(true);
-      expect(op.propertyCount).toBe(2);
-      expect(op.constraintCount).toBe(2);
-      expect(op.totalSchemaProperties).toBe(2);
-      expect(op.schemaPropertiesWithDescription).toBe(1);
-    });
-
-    it('should resolve requestBody $ref', async () => {
-      const doc = makeDoc(
-        {
-          '/items': {
-            post: {
-              operationId: 'createItem',
-              requestBody: { $ref: '#/components/requestBodies/ItemBody' },
-              responses: { '201': { description: 'Created' } },
-            },
-          },
-        },
-        {
-          requestBodies: {
-            ItemBody: {
-              content: {
-                'application/json': {
-                  schema: { type: 'object', properties: { name: { type: 'string' } } },
-                },
-              },
-            },
-          },
-        }
-      );
-      const op = (await collectDocumentMetrics(doc)).operations.get('createItem')!;
-      expect(op.requestBodyPresent).toBe(true);
-      expect(op.propertyCount).toBe(1);
-    });
+  it('counts parameters, resolves $refs, merges path-level params, and detects ambiguous names', async () => {
+    const result = await collectDocumentMetrics(
+      yaml(outdent`
+        openapi: 3.0.0
+        info:
+          title: Test
+          version: '1.0'
+        paths:
+          /items/{id}:
+            parameters:
+              - name: id
+                in: path
+                required: true
+                description: Item ID
+            get:
+              operationId: getItem
+              parameters:
+                - $ref: '#/components/parameters/Fields'
+                - name: type
+                  in: query
+              responses:
+                '200':
+                  description: OK
+        components:
+          parameters:
+            Fields:
+              name: fields
+              in: query
+              description: Select fields
+      `)
+    );
+
+    const op = result.operations.get('getItem')!;
+    expect(op.parameterCount).toBe(3);
+    expect(op.requiredParameterCount).toBe(1);
+    expect(op.paramsWithDescription).toBe(2);
+    expect(op.ambiguousIdentifierCount).toBe(1);
   });
 
-  describe('responses', () => {
-    it('should resolve response $refs and count structured errors', async () => {
-      const doc = makeDoc(
-        {
-          '/items': {
-            get: {
-              operationId: 'listItems',
-              responses: {
-                '200': { description: 'OK' },
-                '400': { $ref: '#/components/responses/BadRequest' },
-                '500': { $ref: '#/components/responses/ServerError' },
-              },
-            },
-          },
-        },
-        {
-          responses: {
-            BadRequest: {
-              description: 'Bad request',
-              content: { 'application/json': { schema: { type: 'object' } } },
-            },
-            ServerError: {
-              description: 'Server error',
-              content: { 'application/json': { schema: { type: 'object' } } },
-            },
-          },
-        }
-      );
-      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
-      expect(op.totalErrorResponses).toBe(2);
-      expect(op.structuredErrorResponseCount).toBe(2);
-    });
-
-    it('should count description-only error responses as structured', async () => {
-      const doc = makeDoc({
-        '/items': {
-          get: {
-            operationId: 'listItems',
-            responses: {
-              '200': { description: 'OK' },
-              '404': { description: 'Not found' },
-            },
-          },
-        },
-      });
-      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
-      expect(op.totalErrorResponses).toBe(1);
-      expect(op.structuredErrorResponseCount).toBe(1);
-    });
-
-    it('should count default as error response', async () => {
-      const doc = makeDoc({
-        '/items': {
-          get: {
-            operationId: 'listItems',
-            responses: {
-              '200': { description: 'OK' },
-              default: { description: 'Error' },
-            },
-          },
-        },
-      });
-      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
-      expect(op.totalErrorResponses).toBe(1);
-    });
-
-    it('should detect response examples and compute schema depth', async () => {
-      const doc = makeDoc({
-        '/items': {
-          get: {
-            operationId: 'listItems',
-            responses: {
-              '200': {
-                description: 'OK',
-                content: {
-                  'application/json': {
-                    schema: {
-                      type: 'object',
-                      properties: {
-                        items: {
-                          type: 'array',
-                          items: {
-                            type: 'object',
-                            properties: { name: { type: 'string' } },
-                          },
-                        },
-                      },
-                    },
-                    example: { items: [{ name: 'test' }] },
-                  },
-                },
-              },
-            },
-          },
-        },
-      });
-      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
-      expect(op.responseExamplePresent).toBe(true);
-      expect(op.maxResponseSchemaDepth).toBe(3);
-    });
+  it('detects request body with $ref schema, examples, constraints, and property descriptions', async () => {
+    const result = await collectDocumentMetrics(
+      yaml(outdent`
+        openapi: 3.0.0
+        info:
+          title: Test
+          version: '1.0'
+        paths:
+          /items:
+            post:
+              operationId: createItem
+              requestBody:
+                content:
+                  application/json:
+                    schema:
+                      $ref: '#/components/schemas/Item'
+                    example:
+                      name: Widget
+                      price: 10
+              responses:
+                '201':
+                  description: Created
+        components:
+          schemas:
+            Item:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: Item name
+                  minLength: 1
+                price:
+                  type: integer
+                  minimum: 0
+      `)
+    );
+
+    const op = result.operations.get('createItem')!;
+    expect(op.requestBodyPresent).toBe(true);
+    expect(op.requestExamplePresent).toBe(true);
+    expect(op.propertyCount).toBe(2);
+    expect(op.constraintCount).toBe(2);
+    expect(op.schemaPropertiesWithDescription).toBe(1);
   });
 
-  describe('schema property examples as coverage', () => {
-    it('should count schema property examples towards response example coverage', async () => {
-      const doc = makeDoc(
-        {
-          '/items': {
-            get: {
-              operationId: 'listItems',
-              responses: {
-                '200': {
-                  description: 'OK',
-                  content: {
-                    'application/json': {
-                      schema: { $ref: '#/components/schemas/Item' },
-                    },
-                  },
-                },
-              },
-            },
-          },
-        },
-        {
-          schemas: {
-            Item: {
-              type: 'object',
-              properties: {
-                id: { type: 'string', example: 'abc123' },
-              },
-            },
-          },
-        }
-      );
-      const op = (await collectDocumentMetrics(doc)).operations.get('listItems')!;
-      expect(op.responseExamplePresent).toBe(true);
-    });
+  it('resolves response $refs, counts structured errors, and computes schema depth', async () => {
+    const result = await collectDocumentMetrics(
+      yaml(outdent`
+        openapi: 3.0.0
+        info:
+          title: Test
+          version: '1.0'
+        paths:
+          /items:
+            get:
+              operationId: listItems
+              responses:
+                '200':
+                  description: OK
+                  content:
+                    application/json:
+                      schema:
+                        type: object
+                        properties:
+                          items:
+                            type: array
+                            items:
+                              type: object
+                              properties:
+                                name:
+                                  type: string
+                      example:
+                        items:
+                          - name: test
+                '400':
+                  $ref: '#/components/responses/BadRequest'
+                '404':
+                  description: Not found
+                default:
+                  description: Unexpected error
+        components:
+          responses:
+            BadRequest:
+              description: Bad request
+              content:
+                application/json:
+                  schema:
+                    type: object
+      `)
+    );
+
+    const op = result.operations.get('listItems')!;
+    expect(op.responseExamplePresent).toBe(true);
+    expect(op.maxResponseSchemaDepth).toBe(3);
+    expect(op.totalErrorResponses).toBe(3);
+    expect(op.structuredErrorResponseCount).toBe(3);
   });
 
-  describe('description and misc', () => {
-    it('should detect operation description presence', async () => {
-      const doc = makeDoc({
-        '/a': {
-          get: {
-            operationId: 'withDesc',
-            description: 'Has description',
-            responses: { '200': { description: 'OK' } },
-          },
-        },
-        '/b': {
-          get: {
-            operationId: 'noDesc',
-            responses: { '200': { description: 'OK' } },
-          },
-        },
-      });
-      const metrics = await collectDocumentMetrics(doc);
-      expect(metrics.operations.get('withDesc')!.operationDescriptionPresent).toBe(true);
-      expect(metrics.operations.get('noDesc')!.operationDescriptionPresent).toBe(false);
-    });
-
-    it('should collect refs used across operations', async () => {
-      const doc = makeDoc(
-        {
-          '/items': {
-            get: {
-              operationId: 'listItems',
-              responses: {
-                '200': {
-                  description: 'OK',
-                  content: {
-                    'application/json': { schema: { $ref: '#/components/schemas/Item' } },
-                  },
-                },
-              },
-            },
-            post: {
-              operationId: 'createItem',
-              requestBody: {
-                content: { 'application/json': { schema: { $ref: '#/components/schemas/Item' } } },
-              },
-              responses: { '201': { description: 'Created' } },
-            },
-          },
-        },
-        { schemas: { Item: { type: 'object' } } }
-      );
-      const metrics = await collectDocumentMetrics(doc);
-      expect(metrics.operations.get('listItems')!.refsUsed.has('#/components/schemas/Item')).toBe(
-        true
-      );
-      expect(metrics.operations.get('createItem')!.refsUsed.has('#/components/schemas/Item')).toBe(
-        true
-      );
-    });
-
-    it('should handle empty paths gracefully', async () => {
-      expect(
-        (
-          await collectDocumentMetrics({
-            openapi: '3.0.0',
-            info: { title: 'T', version: '1' },
-            paths: {},
-          })
-        ).operationCount
-      ).toBe(0);
-    });
+  it('detects operation descriptions and tracks shared $ref usage across operations', async () => {
+    const result = await collectDocumentMetrics(
+      yaml(outdent`
+        openapi: 3.0.0
+        info:
+          title: Test
+          version: '1.0'
+        paths:
+          /items:
+            get:
+              operationId: listItems
+              description: List all items
+              responses:
+                '200':
+                  description: OK
+                  content:
+                    application/json:
+                      schema:
+                        $ref: '#/components/schemas/Item'
+            post:
+              operationId: createItem
+              requestBody:
+                content:
+                  application/json:
+                    schema:
+                      $ref: '#/components/schemas/Item'
+              responses:
+                '201':
+                  description: Created
+        components:
+          schemas:
+            Item:
+              type: object
+              properties:
+                id:
+                  type: string
+                  example: abc123
+      `)
+    );
+
+    expect(result.operations.get('listItems')!.operationDescriptionPresent).toBe(true);
+    expect(result.operations.get('createItem')!.operationDescriptionPresent).toBe(false);
+    expect(result.operations.get('listItems')!.refsUsed.has('#/components/schemas/Item')).toBe(
+      true
+    );
+    expect(result.operations.get('createItem')!.refsUsed.has('#/components/schemas/Item')).toBe(
+      true
+    );
+    expect(result.operations.get('listItems')!.responseExamplePresent).toBe(true);
   });
 });
diff --git a/packages/cli/src/commands/score/__tests__/formatters.test.ts b/packages/cli/src/commands/score/__tests__/formatters.test.ts
index 185ced54ef..c9b35da1f6 100644
--- a/packages/cli/src/commands/score/__tests__/formatters.test.ts
+++ b/packages/cli/src/commands/score/__tests__/formatters.test.ts
@@ -9,213 +9,156 @@ vi.mock('@redocly/openapi-core', () => ({
 import { logger } from '@redocly/openapi-core';
 const mockOutput = vi.mocked(logger.output);
 
-function makeResult(overrides: Partial<ScoreResult> = {}): ScoreResult {
-  return {
-    integrationSimplicity: 75,
-    agentReadiness: 60,
-    integrationSubscores: {
-      parameterSimplicity: 0.8,
-      schemaSimplicity: 0.7,
-      documentationQuality: 0.9,
-      constraintClarity: 0.5,
-      exampleCoverage: 0.6,
-      errorClarity: 1.0,
-      workflowClarity: 0.8,
+const RESULT: ScoreResult = {
+  integrationSimplicity: 75,
+  agentReadiness: 60,
+  integrationSubscores: {
+    parameterSimplicity: 0.8,
+    schemaSimplicity: 0.7,
+    documentationQuality: 0.9,
+    constraintClarity: 0.5,
+    exampleCoverage: 0.6,
+    errorClarity: 1.0,
+    workflowClarity: 0.8,
+  },
+  agentSubscores: {
+    documentationQuality: 0.9,
+    constraintClarity: 0.5,
+    exampleCoverage: 0.6,
+    errorClarity: 1.0,
+    identifierClarity: 0.8,
+    workflowClarity: 0.8,
+    polymorphismClarity: 1.0,
+  },
+  rawMetrics: {
+    operationCount: 2,
+    operations: new Map([
+      [
+        'getItems',
+        {
+          path: '/items',
+          method: 'get',
+          operationId: 'getItems',
+          parameterCount: 2,
+          requiredParameterCount: 0,
+          paramsWithDescription: 1,
+          requestBodyPresent: false,
+          topLevelWritableFieldCount: 0,
+          maxRequestSchemaDepth: 0,
+          maxResponseSchemaDepth: 2,
+          polymorphismCount: 0,
+          anyOfCount: 0,
+          hasDiscriminator: false,
+          propertyCount: 3,
+          operationDescriptionPresent: true,
+          schemaPropertiesWithDescription: 2,
+          totalSchemaProperties: 3,
+          constraintCount: 1,
+          requestExamplePresent: false,
+          responseExamplePresent: true,
+          structuredErrorResponseCount: 1,
+          totalErrorResponses: 1,
+          ambiguousIdentifierCount: 0,
+          refsUsed: new Set(),
+        },
+      ],
+      [
+        'createItem',
+        {
+          path: '/items',
+          method: 'post',
+          operationId: 'createItem',
+          parameterCount: 0,
+          requiredParameterCount: 0,
+          paramsWithDescription: 0,
+          requestBodyPresent: true,
+          topLevelWritableFieldCount: 3,
+          maxRequestSchemaDepth: 1,
+          maxResponseSchemaDepth: 1,
+          polymorphismCount: 0,
+          anyOfCount: 0,
+          hasDiscriminator: false,
+          propertyCount: 5,
+          operationDescriptionPresent: false,
+          schemaPropertiesWithDescription: 2,
+          totalSchemaProperties: 5,
+          constraintCount: 2,
+          requestExamplePresent: true,
+          responseExamplePresent: true,
+          structuredErrorResponseCount: 1,
+          totalErrorResponses: 1,
+          ambiguousIdentifierCount: 0,
+          refsUsed: new Set(),
+        },
+      ],
+    ]),
+  },
+  hotspots: [
+    {
+      path: '/items',
+      method: 'post',
+      operationId: 'createItem',
+      integrationSimplicityScore: 65,
+      agentReadinessScore: 55,
+      reasons: ['Missing operation description'],
     },
-    agentSubscores: {
-      documentationQuality: 0.9,
-      constraintClarity: 0.5,
-      exampleCoverage: 0.6,
-      errorClarity: 1.0,
-      identifierClarity: 0.8,
-      workflowClarity: 0.8,
-      polymorphismClarity: 1.0,
-    },
-    rawMetrics: {
-      operationCount: 2,
-      operations: new Map([
-        [
-          'getItems',
-          {
-            path: '/items',
-            method: 'get',
-            operationId: 'getItems',
-            parameterCount: 2,
-            requiredParameterCount: 0,
-            paramsWithDescription: 1,
-            requestBodyPresent: false,
-            topLevelWritableFieldCount: 0,
-            maxRequestSchemaDepth: 0,
-            maxResponseSchemaDepth: 2,
-            polymorphismCount: 0,
-            anyOfCount: 0,
-            hasDiscriminator: false,
-            propertyCount: 3,
-            operationDescriptionPresent: true,
-            schemaPropertiesWithDescription: 2,
-            totalSchemaProperties: 3,
-            constraintCount: 1,
-            requestExamplePresent: false,
-            responseExamplePresent: true,
-            structuredErrorResponseCount: 1,
-            totalErrorResponses: 1,
-            ambiguousIdentifierCount: 0,
-            refsUsed: new Set(),
-          },
-        ],
-        [
-          'createItem',
-          {
-            path: '/items',
-            method: 'post',
-            operationId: 'createItem',
-            parameterCount: 0,
-            requiredParameterCount: 0,
-            paramsWithDescription: 0,
-            requestBodyPresent: true,
-            topLevelWritableFieldCount: 3,
-            maxRequestSchemaDepth: 1,
-            maxResponseSchemaDepth: 1,
-            polymorphismCount: 0,
-            anyOfCount: 0,
-            hasDiscriminator: false,
-            propertyCount: 5,
-            operationDescriptionPresent: false,
-            schemaPropertiesWithDescription: 2,
-            totalSchemaProperties: 5,
-            constraintCount: 2,
-            requestExamplePresent: true,
-            responseExamplePresent: true,
-            structuredErrorResponseCount: 1,
-            totalErrorResponses: 1,
-            ambiguousIdentifierCount: 0,
-            refsUsed: new Set(),
-          },
-        ],
-      ]),
-    },
-    hotspots: [
-      {
-        path: '/items',
-        method: 'post',
-        operationId: 'createItem',
-        integrationSimplicityScore: 65,
-        agentReadinessScore: 55,
-        reasons: ['Missing operation description'],
-      },
-    ],
-    operationScores: new Map(),
-    workflowDepths: new Map(),
-    ...overrides,
-  };
+  ],
+  operationScores: new Map(),
+  workflowDepths: new Map(),
+};
+
+function getStylishOutput(result: ScoreResult = RESULT): string {
+  mockOutput.mockClear();
+  printScoreStylish(result);
+  return mockOutput.mock.calls.map(([s]: [string]) => s).join('');
 }
 
 describe('printScoreStylish', () => {
-  beforeEach(() => {
-    mockOutput.mockClear();
-  });
-
-  it('outputs main scores', () => {
-    printScoreStylish(makeResult());
-    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+  it('outputs scores, subscores, metrics, and hotspots', () => {
+    const output = getStylishOutput();
     expect(output).toContain('Integration Simplicity');
     expect(output).toContain('Agent Readiness');
-  });
-
-  it('outputs subscores', () => {
-    printScoreStylish(makeResult());
-    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
     expect(output).toContain('Parameter Simplicity');
-    expect(output).toContain('Schema Simplicity');
-    expect(output).toContain('Documentation Quality');
-    expect(output).toContain('Identifier Clarity');
-    expect(output).toContain('Polymorphism Clarity');
-  });
-
-  it('outputs raw metrics summary', () => {
-    printScoreStylish(makeResult());
-    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
     expect(output).toContain('Total operations: 2');
-    expect(output).toContain('Avg parameters/operation');
-  });
-
-  it('outputs hotspots', () => {
-    printScoreStylish(makeResult());
-    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
-    expect(output).toContain('Hotspot Operations');
     expect(output).toContain('POST /items');
     expect(output).toContain('Missing operation description');
   });
 
-  it('outputs no hotspot message when empty', () => {
-    printScoreStylish(makeResult({ hotspots: [] }));
-    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
-    expect(output).toContain('No hotspot operations found');
-  });
-
-  it('handles zero operations in raw metrics', () => {
-    printScoreStylish(
-      makeResult({
-        rawMetrics: { operationCount: 0, operations: new Map() },
-        hotspots: [],
-      })
-    );
-    const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
+  it('handles zero operations gracefully', () => {
+    const output = getStylishOutput({
+      ...RESULT,
+      rawMetrics: { operationCount: 0, operations: new Map() },
+      hotspots: [],
+    });
     expect(output).toContain('Total operations: 0');
-    expect(output).not.toContain('Avg parameters');
-  });
-
-  it('appends newline to every output call', () => {
-    printScoreStylish(makeResult());
-    for (const call of mockOutput.mock.calls) {
-      expect(call[0]).toMatch(/\n$/);
-    }
+    expect(output).toContain('No hotspot operations found');
   });
 });
 
 describe('printScoreJson', () => {
-  beforeEach(() => {
+  it('outputs valid JSON with all sections', () => {
     mockOutput.mockClear();
-  });
+    printScoreJson(RESULT);
+    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
 
-  it('outputs valid JSON', () => {
-    printScoreJson(makeResult());
-    const output = mockOutput.mock.calls[0][0];
-    const parsed = JSON.parse(output);
     expect(parsed.integrationSimplicity).toBe(75);
     expect(parsed.agentReadiness).toBe(60);
-  });
-
-  it('includes operations as plain object', () => {
-    printScoreJson(makeResult());
-    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
-    expect(parsed.rawMetrics.operations.getItems).toBeDefined();
-    expect(parsed.rawMetrics.operations.getItems.path).toBe('/items');
-  });
-
-  it('includes hotspots', () => {
-    printScoreJson(makeResult());
-    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
-    expect(parsed.hotspots.length).toBe(1);
-    expect(parsed.hotspots[0].reasons).toContain('Missing operation description');
-  });
-
-  it('includes subscores', () => {
-    printScoreJson(makeResult());
-    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
     expect(parsed.integrationSubscores.parameterSimplicity).toBe(0.8);
     expect(parsed.agentSubscores.polymorphismClarity).toBe(1.0);
+    expect(parsed.rawMetrics.operations.getItems.path).toBe('/items');
+    expect(parsed.hotspots[0].reasons).toContain('Missing operation description');
   });
 
-  it('includes workflow depths as object', () => {
-    const result = makeResult();
-    result.workflowDepths = new Map([
-      ['opA', 2],
-      ['opB', 0],
-    ]);
-    printScoreJson(result);
+  it('serializes Maps as plain objects', () => {
+    mockOutput.mockClear();
+    printScoreJson({
+      ...RESULT,
+      workflowDepths: new Map([
+        ['opA', 2],
+        ['opB', 0],
+      ]),
+    });
     const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
-    expect(parsed.workflowDepths.opA).toBe(2);
-    expect(parsed.workflowDepths.opB).toBe(0);
+    expect(parsed.workflowDepths).toEqual({ opA: 2, opB: 0 });
   });
 });
diff --git a/packages/cli/src/commands/score/formatters/stylish.ts b/packages/cli/src/commands/score/formatters/stylish.ts
index 7ad5a58d44..1673594404 100644
--- a/packages/cli/src/commands/score/formatters/stylish.ts
+++ b/packages/cli/src/commands/score/formatters/stylish.ts
@@ -1,5 +1,5 @@
 import { logger } from '@redocly/openapi-core';
-import { bold, cyan, green, red, white, yellow, gray } from 'colorette';
+import { bold, cyan, green, red, white, yellow } from 'colorette';
 
 import type { ScoreResult } from '../types.js';
 
@@ -43,7 +43,7 @@ function printSubscores(result: ScoreResult): void {
   printSubscore('Constraint Clarity', is.constraintClarity);
   printSubscore('Example Coverage', is.exampleCoverage);
   printSubscore('Error Clarity', is.errorClarity);
-  printSubscore('Workflow Clarity', is.workflowClarity);
+  printSubscore('Dependency Clarity', is.workflowClarity);
   out('');
 
   out(bold(white('  Agent Readiness Subscores')));
@@ -54,7 +54,7 @@ function printSubscores(result: ScoreResult): void {
   printSubscore('Example Coverage', ar.exampleCoverage);
   printSubscore('Error Clarity', ar.errorClarity);
   printSubscore('Identifier Clarity', ar.identifierClarity);
-  printSubscore('Workflow Clarity', ar.workflowClarity);
+  printSubscore('Dependency Clarity', ar.workflowClarity);
   printSubscore('Polymorphism Clarity', ar.polymorphismClarity);
   out('');
 }
@@ -142,7 +142,7 @@ function printHotspots(result: ScoreResult): void {
     );
 
     for (const reason of hotspot.reasons) {
-      out(gray(`    - ${reason}`));
+      out(yellow(`    - ${reason}`));
     }
     out('');
   }
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
index 9a8253d016..06a6fe6a17 100644
--- a/packages/cli/src/commands/score/index.ts
+++ b/packages/cli/src/commands/score/index.ts
@@ -25,12 +25,13 @@ import { computeWorkflowDepths } from './collectors/workflow-graph.js';
 import { printScoreJson } from './formatters/json.js';
 import { printScoreStylish } from './formatters/stylish.js';
 import { selectTopHotspots } from './hotspots.js';
-import { computeAllOperationScores, computeDocumentScores } from './scoring.js';
-import type {
-  AgentReadinessSubscores,
-  IntegrationSimplicitySubscores,
-  ScoreResult,
-} from './types.js';
+import {
+  averageAgentSubscores,
+  averageIntegrationSubscores,
+  computeAllOperationScores,
+  computeDocumentScores,
+} from './scoring.js';
+import type { ScoreResult } from './types.js';
 
 export type ScoreArgv = {
   api?: string;
@@ -64,7 +65,7 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
     externalRefResolver,
   });
 
-  const walkCtx: WalkContext = {
+  const ctx: WalkContext = {
     problems: [],
     specVersion,
     config,
@@ -72,7 +73,7 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
   };
 
   const normalizedVisitors = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor }],
+    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
     types
   );
 
@@ -81,7 +82,7 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
     rootType: types.Root,
     normalizedVisitors,
     resolvedRefMap,
-    ctx: walkCtx,
+    ctx,
   });
 
   const rawMetrics = getDocumentMetrics(accumulator);
@@ -91,23 +92,24 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
 
   const hotspots = selectTopHotspots(rawMetrics, operationScores, workflowDepths);
 
-  const avgIntSubscores = averageIntegrationSubscores(operationScores);
-  const avgAgentSubscores = averageAgentSubscores(operationScores);
-
   const result: ScoreResult = {
     integrationSimplicity,
     agentReadiness,
-    integrationSubscores: avgIntSubscores,
-    agentSubscores: avgAgentSubscores,
+    integrationSubscores: averageIntegrationSubscores(operationScores),
+    agentSubscores: averageAgentSubscores(operationScores),
     rawMetrics,
     hotspots,
     operationScores,
     workflowDepths,
   };
 
-  logger.info(`Document: ${colors.magenta(path)} score:\n`);
+  printScore(result, path, startedAt, argv.format);
+}
 
-  switch (argv.format) {
+function printScore(result: ScoreResult, api: string, startedAt: number, format: string): void {
+  logger.info(`Document: ${colors.magenta(api)} score:\n`);
+
+  switch (format) {
     case 'json':
       printScoreJson(result);
       break;
@@ -116,75 +118,5 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
       break;
   }
 
-  printExecutionTime('score', startedAt, path);
-}
-
-function averageIntegrationSubscores(
-  operationScores: Map<string, { integrationSubscores: IntegrationSimplicitySubscores }>
-): IntegrationSimplicitySubscores {
-  const n = operationScores.size || 1;
-  const result: IntegrationSimplicitySubscores = {
-    parameterSimplicity: 0,
-    schemaSimplicity: 0,
-    documentationQuality: 0,
-    constraintClarity: 0,
-    exampleCoverage: 0,
-    errorClarity: 0,
-    workflowClarity: 0,
-  };
-
-  for (const scores of operationScores.values()) {
-    result.parameterSimplicity += scores.integrationSubscores.parameterSimplicity;
-    result.schemaSimplicity += scores.integrationSubscores.schemaSimplicity;
-    result.documentationQuality += scores.integrationSubscores.documentationQuality;
-    result.constraintClarity += scores.integrationSubscores.constraintClarity;
-    result.exampleCoverage += scores.integrationSubscores.exampleCoverage;
-    result.errorClarity += scores.integrationSubscores.errorClarity;
-    result.workflowClarity += scores.integrationSubscores.workflowClarity;
-  }
-
-  result.parameterSimplicity /= n;
-  result.schemaSimplicity /= n;
-  result.documentationQuality /= n;
-  result.constraintClarity /= n;
-  result.exampleCoverage /= n;
-  result.errorClarity /= n;
-  result.workflowClarity /= n;
-
-  return result;
-}
-
-function averageAgentSubscores(
-  operationScores: Map<string, { agentSubscores: AgentReadinessSubscores }>
-): AgentReadinessSubscores {
-  const n = operationScores.size || 1;
-  const result: AgentReadinessSubscores = {
-    documentationQuality: 0,
-    constraintClarity: 0,
-    exampleCoverage: 0,
-    errorClarity: 0,
-    identifierClarity: 0,
-    workflowClarity: 0,
-    polymorphismClarity: 0,
-  };
-
-  for (const scores of operationScores.values()) {
-    result.documentationQuality += scores.agentSubscores.documentationQuality;
-    result.constraintClarity += scores.agentSubscores.constraintClarity;
-    result.exampleCoverage += scores.agentSubscores.exampleCoverage;
-    result.errorClarity += scores.agentSubscores.errorClarity;
-    result.identifierClarity += scores.agentSubscores.identifierClarity;
-    result.workflowClarity += scores.agentSubscores.workflowClarity;
-    result.polymorphismClarity += scores.agentSubscores.polymorphismClarity;
-  }
-
-  result.documentationQuality /= n;
-  result.constraintClarity /= n;
-  result.exampleCoverage /= n;
-  result.errorClarity /= n;
-  result.identifierClarity /= n;
-  result.workflowClarity /= n;
-  result.polymorphismClarity /= n;
-
-  return result;
+  printExecutionTime('score', startedAt, api);
 }
diff --git a/packages/cli/src/commands/score/scoring.ts b/packages/cli/src/commands/score/scoring.ts
index 6aeda0f388..0806e61b90 100644
--- a/packages/cli/src/commands/score/scoring.ts
+++ b/packages/cli/src/commands/score/scoring.ts
@@ -194,6 +194,76 @@ function clamp01(value: number): number {
   return Math.max(0, Math.min(1, value));
 }
 
+export function averageIntegrationSubscores(
+  operationScores: Map<string, { integrationSubscores: IntegrationSimplicitySubscores }>
+): IntegrationSimplicitySubscores {
+  const n = operationScores.size || 1;
+  const result: IntegrationSimplicitySubscores = {
+    parameterSimplicity: 0,
+    schemaSimplicity: 0,
+    documentationQuality: 0,
+    constraintClarity: 0,
+    exampleCoverage: 0,
+    errorClarity: 0,
+    workflowClarity: 0,
+  };
+
+  for (const scores of operationScores.values()) {
+    result.parameterSimplicity += scores.integrationSubscores.parameterSimplicity;
+    result.schemaSimplicity += scores.integrationSubscores.schemaSimplicity;
+    result.documentationQuality += scores.integrationSubscores.documentationQuality;
+    result.constraintClarity += scores.integrationSubscores.constraintClarity;
+    result.exampleCoverage += scores.integrationSubscores.exampleCoverage;
+    result.errorClarity += scores.integrationSubscores.errorClarity;
+    result.workflowClarity += scores.integrationSubscores.workflowClarity;
+  }
+
+  result.parameterSimplicity /= n;
+  result.schemaSimplicity /= n;
+  result.documentationQuality /= n;
+  result.constraintClarity /= n;
+  result.exampleCoverage /= n;
+  result.errorClarity /= n;
+  result.workflowClarity /= n;
+
+  return result;
+}
+
+export function averageAgentSubscores(
+  operationScores: Map<string, { agentSubscores: AgentReadinessSubscores }>
+): AgentReadinessSubscores {
+  const n = operationScores.size || 1;
+  const result: AgentReadinessSubscores = {
+    documentationQuality: 0,
+    constraintClarity: 0,
+    exampleCoverage: 0,
+    errorClarity: 0,
+    identifierClarity: 0,
+    workflowClarity: 0,
+    polymorphismClarity: 0,
+  };
+
+  for (const scores of operationScores.values()) {
+    result.documentationQuality += scores.agentSubscores.documentationQuality;
+    result.constraintClarity += scores.agentSubscores.constraintClarity;
+    result.exampleCoverage += scores.agentSubscores.exampleCoverage;
+    result.errorClarity += scores.agentSubscores.errorClarity;
+    result.identifierClarity += scores.agentSubscores.identifierClarity;
+    result.workflowClarity += scores.agentSubscores.workflowClarity;
+    result.polymorphismClarity += scores.agentSubscores.polymorphismClarity;
+  }
+
+  result.documentationQuality /= n;
+  result.constraintClarity /= n;
+  result.exampleCoverage /= n;
+  result.errorClarity /= n;
+  result.identifierClarity /= n;
+  result.workflowClarity /= n;
+  result.polymorphismClarity /= n;
+
+  return result;
+}
+
 function round(value: number): number {
   return Math.round(value * 10) / 10;
 }

From 3cb0f51a4bafe71d892122072d5e524d57495ed0 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Fri, 13 Mar 2026 12:52:45 -0500
Subject: [PATCH 09/22] fix: adjust walking method and add debugging arguments

---
 .../score/__tests__/collect-metrics.ts        |  41 ++-
 .../commands/score/__tests__/index.test.ts    |  20 +-
 .../score/collectors/document-metrics.ts      | 311 ++++++++++++------
 .../src/commands/score/formatters/stylish.ts  | 132 +++++++-
 packages/cli/src/commands/score/index.ts      | 148 ++++++++-
 packages/cli/src/commands/score/types.ts      |  17 +
 packages/cli/src/index.ts                     |   9 +
 tests/e2e/score/score-json/snapshot.txt       | 218 ++++++------
 tests/e2e/score/score-minimal/snapshot.txt    |   4 +-
 tests/e2e/score/score-stylish/snapshot.txt    |  36 +-
 10 files changed, 683 insertions(+), 253 deletions(-)

diff --git a/packages/cli/src/commands/score/__tests__/collect-metrics.ts b/packages/cli/src/commands/score/__tests__/collect-metrics.ts
index f766e9a77f..0248b001b9 100644
--- a/packages/cli/src/commands/score/__tests__/collect-metrics.ts
+++ b/packages/cli/src/commands/score/__tests__/collect-metrics.ts
@@ -12,6 +12,9 @@ import type { Document, WalkContext } from '@redocly/openapi-core';
 import {
   createScoreAccumulator,
   createScoreVisitor,
+  createSchemaWalkState,
+  resetSchemaWalkState,
+  createSchemaMetricVisitor,
   getDocumentMetrics,
 } from '../collectors/document-metrics.js';
 import type { DocumentMetrics } from '../types.js';
@@ -20,9 +23,6 @@ export async function collectDocumentMetrics(
   doc: Record<string, unknown>
 ): Promise<DocumentMetrics> {
   const types = normalizeTypes(getTypes('oas3_0'), {});
-  const accumulator = createScoreAccumulator();
-  const visitor = createScoreVisitor(accumulator);
-  const normalizedVis = normalizeVisitors([{ severity: 'warn', ruleId: 'test', visitor }], types);
   const source = new Source('test.yaml', JSON.stringify(doc));
   const document: Document = { source, parsed: doc };
   const externalRefResolver = new BaseResolver();
@@ -36,6 +36,41 @@ export async function collectDocumentMetrics(
     specVersion: 'oas3_0',
     visitorsData: {},
   };
+
+  const schemaWalkState = createSchemaWalkState();
+  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
+  const normalizedSchemaVis = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'test-schema', visitor: schemaVisitor }],
+    types
+  );
+
+  const walkSchema = (schemaNode: any) => {
+    resetSchemaWalkState(schemaWalkState);
+    walkDocument({
+      document: { ...document, parsed: schemaNode },
+      rootType: types.Schema,
+      normalizedVisitors: normalizedSchemaVis,
+      resolvedRefMap,
+      ctx,
+    });
+    return {
+      maxDepth: schemaWalkState.maxDepth,
+      polymorphismCount: schemaWalkState.polymorphismCount,
+      anyOfCount: schemaWalkState.anyOfCount,
+      hasDiscriminator: schemaWalkState.hasDiscriminator,
+      propertyCount: schemaWalkState.propertyCount,
+      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
+      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
+      constraintCount: schemaWalkState.constraintCount,
+      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
+      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
+      refsUsed: [...schemaWalkState.refsUsed],
+    };
+  };
+
+  const accumulator = createScoreAccumulator(walkSchema);
+  const visitor = createScoreVisitor(accumulator);
+  const normalizedVis = normalizeVisitors([{ severity: 'warn', ruleId: 'test', visitor }], types);
   walkDocument({
     document,
     rootType: types.Root,
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index 45071d5f9b..0186dd30bc 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -90,7 +90,25 @@ function makeTestMetrics(overrides: Partial<OperationMetrics> = {}): OperationMe
 }
 
 function makeAccumulator(ops: Map<string, OperationMetrics> = new Map()): ScoreAccumulator {
-  return { operations: ops, currentPath: '', pathLevelParams: [], current: null };
+  return {
+    operations: ops,
+    currentPath: '',
+    pathLevelParams: [],
+    current: null,
+    walkSchema: () => ({
+      maxDepth: 0,
+      polymorphismCount: 0,
+      anyOfCount: 0,
+      hasDiscriminator: false,
+      propertyCount: 0,
+      totalSchemaProperties: 0,
+      schemaPropertiesWithDescription: 0,
+      constraintCount: 0,
+      hasPropertyExamples: false,
+      writableTopLevelFields: 0,
+      refsUsed: [],
+    }),
+  };
 }
 
 function createArgs(overrides: Partial<ScoreArgv> = {}) {
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
index f03512f110..9a7719f63b 100644
--- a/packages/cli/src/commands/score/collectors/document-metrics.ts
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -10,10 +10,16 @@ import type {
 } from '@redocly/openapi-core';
 
 import { AMBIGUOUS_PARAM_NAMES } from '../constants.js';
-import type { DocumentMetrics, OperationMetrics } from '../types.js';
+import type {
+  DebugMediaTypeLog,
+  DebugSchemaEntry,
+  DocumentMetrics,
+  OperationMetrics,
+} from '../types.js';
 
 type Schema = Oas3Schema | Oas3_1Schema;
 type Param = Oas3Parameter<Schema>;
+type ResolveFn = UserContext['resolve'];
 
 const CONSTRAINT_KEYS: readonly string[] = [
   'enum',
@@ -34,6 +40,143 @@ const CONSTRAINT_KEYS: readonly string[] = [
   'uniqueItems',
 ];
 
+export interface SchemaWalkState {
+  depth: number;
+  maxDepth: number;
+  polymorphismCount: number;
+  anyOfCount: number;
+  hasDiscriminator: boolean;
+  propertyCount: number;
+  totalSchemaProperties: number;
+  schemaPropertiesWithDescription: number;
+  constraintCount: number;
+  hasPropertyExamples: boolean;
+  writableTopLevelFields: number;
+  refsUsed: string[];
+  debugEntries: DebugSchemaEntry[] | null;
+  pendingRef: string | null;
+}
+
+export function createSchemaWalkState(): SchemaWalkState {
+  return {
+    depth: -1,
+    maxDepth: 0,
+    polymorphismCount: 0,
+    anyOfCount: 0,
+    hasDiscriminator: false,
+    propertyCount: 0,
+    totalSchemaProperties: 0,
+    schemaPropertiesWithDescription: 0,
+    constraintCount: 0,
+    hasPropertyExamples: false,
+    writableTopLevelFields: 0,
+    refsUsed: [],
+    debugEntries: null,
+    pendingRef: null,
+  };
+}
+
+export function resetSchemaWalkState(s: SchemaWalkState): void {
+  s.depth = -1;
+  s.maxDepth = 0;
+  s.polymorphismCount = 0;
+  s.anyOfCount = 0;
+  s.hasDiscriminator = false;
+  s.propertyCount = 0;
+  s.totalSchemaProperties = 0;
+  s.schemaPropertiesWithDescription = 0;
+  s.constraintCount = 0;
+  s.hasPropertyExamples = false;
+  s.writableTopLevelFields = 0;
+  s.refsUsed = [];
+  s.debugEntries = null;
+  s.pendingRef = null;
+}
+
+export function createSchemaMetricVisitor(state: SchemaWalkState): Oas3Visitor {
+  return {
+    ref: {
+      enter(ref: { $ref: string }) {
+        if (typeof ref?.$ref === 'string') {
+          state.refsUsed.push(ref.$ref);
+          state.pendingRef = ref.$ref;
+        }
+      },
+    },
+    Schema: {
+      enter(schema: any, ctx: UserContext) {
+        state.depth++;
+        state.maxDepth = Math.max(state.maxDepth, state.depth);
+
+        let localConstraints = 0;
+        for (const key of CONSTRAINT_KEYS) {
+          if (schema[key] !== undefined) {
+            state.constraintCount++;
+            localConstraints++;
+          }
+        }
+
+        if (schema.discriminator?.propertyName) state.hasDiscriminator = true;
+
+        const localPoly: { oneOf?: number; anyOf?: number; allOf?: number } = {};
+        for (const keyword of ['oneOf', 'anyOf', 'allOf'] as const) {
+          const list = schema[keyword];
+          if (!Array.isArray(list)) continue;
+          state.polymorphismCount += list.length;
+          if (keyword === 'anyOf') state.anyOfCount += list.length;
+          localPoly[keyword] = list.length;
+        }
+
+        const localPropertyNames: string[] = [];
+        if (schema.properties && typeof schema.properties === 'object') {
+          const props = Object.entries(schema.properties) as [string, any][];
+          state.totalSchemaProperties += props.length;
+          state.propertyCount += props.length;
+
+          for (const [name, prop] of props) {
+            localPropertyNames.push(name);
+            const res =
+              prop && '$ref' in prop && prop.$ref ? (ctx.resolve(prop)?.node ?? prop) : prop;
+            if (res?.description) state.schemaPropertiesWithDescription++;
+            if (res?.example !== undefined || res?.examples) state.hasPropertyExamples = true;
+            if (!res?.readOnly) state.writableTopLevelFields++;
+          }
+        }
+
+        if (state.debugEntries !== null) {
+          state.debugEntries.push({
+            ref: state.pendingRef,
+            depth: state.depth,
+            propertyNames: localPropertyNames,
+            polymorphism: Object.keys(localPoly).length > 0 ? localPoly : {},
+            constraintCount: localConstraints,
+          });
+        }
+
+        state.pendingRef = null;
+      },
+      leave() {
+        state.depth--;
+      },
+    },
+  };
+}
+
+interface SchemaStats {
+  maxDepth: number;
+  polymorphismCount: number;
+  anyOfCount: number;
+  hasDiscriminator: boolean;
+  propertyCount: number;
+  totalSchemaProperties: number;
+  schemaPropertiesWithDescription: number;
+  constraintCount: number;
+  hasPropertyExamples: boolean;
+  writableTopLevelFields: number;
+  refsUsed: string[];
+  debugEntries?: DebugSchemaEntry[];
+}
+
 interface CurrentOperationContext {
   path: string;
   method: string;
@@ -45,19 +188,16 @@ interface CurrentOperationContext {
   paramsWithDescription: number;
   ambiguousIdentifierCount: number;
 
-  schemaDepth: number;
   maxRequestSchemaDepth: number;
   maxResponseSchemaDepth: number;
   propertyCount: number;
   totalSchemaProperties: number;
   schemaPropertiesWithDescription: number;
   constraintCount: number;
-  propertiesWithExamples: number;
   polymorphismCount: number;
   anyOfCount: number;
   hasDiscriminator: boolean;
 
-  currentMediaTypeWritableFields: number;
   writableTopLevelFieldCount: number;
 
   requestBodyPresent: boolean;
@@ -68,7 +208,6 @@ interface CurrentOperationContext {
 
   inRequestBody: boolean;
   inResponse: boolean;
-  inMediaType: boolean;
   currentResponseCode: string;
 
   refsUsed: Set<string>;
@@ -79,14 +218,23 @@ export interface ScoreAccumulator {
   currentPath: string;
   pathLevelParams: Array<Referenced<Param>>;
   current: CurrentOperationContext | null;
+  walkSchema: (schema: any, debug?: boolean) => SchemaStats;
+  debugOperationId?: string;
+  debugLogs: DebugMediaTypeLog[];
 }
 
-export function createScoreAccumulator(): ScoreAccumulator {
+export function createScoreAccumulator(
+  walkSchema: (schema: any, debug?: boolean) => SchemaStats,
+  debugOperationId?: string
+): ScoreAccumulator {
   return {
     operations: new Map(),
     currentPath: '',
     pathLevelParams: [],
     current: null,
+    walkSchema,
+    debugOperationId,
+    debugLogs: [],
   };
 }
 
@@ -106,19 +254,16 @@ function createOperationContext(
     paramsWithDescription: 0,
     ambiguousIdentifierCount: 0,
 
-    schemaDepth: 0,
     maxRequestSchemaDepth: 0,
     maxResponseSchemaDepth: 0,
     propertyCount: 0,
     totalSchemaProperties: 0,
     schemaPropertiesWithDescription: 0,
     constraintCount: 0,
-    propertiesWithExamples: 0,
     polymorphismCount: 0,
     anyOfCount: 0,
     hasDiscriminator: false,
 
-    currentMediaTypeWritableFields: 0,
     writableTopLevelFieldCount: 0,
 
     requestBodyPresent: false,
@@ -129,7 +274,6 @@ function createOperationContext(
 
     inRequestBody: false,
     inResponse: false,
-    inMediaType: false,
     currentResponseCode: '',
 
     refsUsed: new Set(),
@@ -167,11 +311,6 @@ function buildOperationMetrics(ctx: CurrentOperationContext): OperationMetrics {
 
 export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
   return {
-    ref: {
-      enter(ref) {
-        accumulator.current?.refsUsed.add(ref.$ref);
-      },
-    },
     RequestBody: {
       enter() {
         if (!accumulator.current) return;
@@ -205,15 +344,12 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
       },
     },
     MediaType: {
-      enter(mediaType: { example?: unknown; examples?: Record<string, unknown> }) {
+      enter(
+        mediaType: { schema?: any; example?: unknown; examples?: Record<string, unknown> },
+        _ctx: UserContext
+      ) {
         const current = accumulator.current;
         if (!current) return;
-        current.inMediaType = true;
-        current.schemaDepth = 0;
-
-        if (current.inRequestBody) {
-          current.currentMediaTypeWritableFields = 0;
-        }
 
         if (hasExample(mediaType)) {
           if (current.inRequestBody) current.requestExamplePresent = true;
@@ -223,94 +359,63 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
         if (current.inResponse && isErrorCode(current.currentResponseCode)) {
           current.structuredErrorResponseCount++;
         }
-      },
-      leave() {
-        const current = accumulator.current;
-        if (!current) return;
-        if (current.inRequestBody) {
-          current.writableTopLevelFieldCount = Math.max(
-            current.writableTopLevelFieldCount,
-            current.currentMediaTypeWritableFields
-          );
-        }
-        current.inMediaType = false;
-      },
-    },
-    SchemaProperties: {
-      enter(properties: Record<string, Referenced<Schema>>, ctx: UserContext) {
-        const current = accumulator.current;
-        if (!current?.inMediaType) return;
-
-        const entries = Object.values(properties);
-        current.totalSchemaProperties += entries.length;
-        current.propertyCount += entries.length;
 
-        const isRootLevel = current.schemaDepth === 1;
+        if (mediaType.schema) {
+          const isDebugTarget =
+            !!accumulator.debugOperationId &&
+            (current.operationId === accumulator.debugOperationId ||
+              `${current.method.toUpperCase()} ${current.path}` === accumulator.debugOperationId);
 
-        for (const prop of entries) {
-          const resolved =
-            '$ref' in prop && prop.$ref
-              ? (ctx.resolve(prop).node ?? (prop as Schema))
-              : (prop as Schema);
+          const stats = accumulator.walkSchema(mediaType.schema, isDebugTarget);
 
-          if (resolved.description) current.schemaPropertiesWithDescription++;
-          if (resolved.example !== undefined || ('examples' in resolved && resolved.examples)) {
-            current.propertiesWithExamples++;
-          }
-          if (isRootLevel && current.inRequestBody && !resolved.readOnly) {
-            current.currentMediaTypeWritableFields++;
-          }
-        }
-
-        if (current.propertiesWithExamples > 0) {
-          if (current.inRequestBody) current.requestExamplePresent = true;
-          if (current.inResponse) current.responseExamplePresent = true;
-        }
-      },
-    },
-    Schema: {
-      enter(schema: Schema) {
-        const current = accumulator.current;
-        if (!current?.inMediaType) return;
-        current.schemaDepth++;
-
-        if (current.inRequestBody) {
-          current.maxRequestSchemaDepth = Math.max(
-            current.maxRequestSchemaDepth,
-            current.schemaDepth - 1
+          current.propertyCount = Math.max(current.propertyCount, stats.propertyCount);
+          current.totalSchemaProperties = Math.max(
+            current.totalSchemaProperties,
+            stats.totalSchemaProperties
           );
-        }
-        if (current.inResponse) {
-          current.maxResponseSchemaDepth = Math.max(
-            current.maxResponseSchemaDepth,
-            current.schemaDepth - 1
+          current.schemaPropertiesWithDescription = Math.max(
+            current.schemaPropertiesWithDescription,
+            stats.schemaPropertiesWithDescription
           );
-        }
+          current.constraintCount = Math.max(current.constraintCount, stats.constraintCount);
+          current.polymorphismCount = Math.max(current.polymorphismCount, stats.polymorphismCount);
+          current.anyOfCount = Math.max(current.anyOfCount, stats.anyOfCount);
+          if (stats.hasDiscriminator) current.hasDiscriminator = true;
 
-        for (const key of CONSTRAINT_KEYS) {
-          if ((schema as Record<string, unknown>)[key] !== undefined) {
-            current.constraintCount++;
+          for (const ref of stats.refsUsed) current.refsUsed.add(ref);
+
+          if (stats.hasPropertyExamples) {
+            if (current.inRequestBody) current.requestExamplePresent = true;
+            if (current.inResponse) current.responseExamplePresent = true;
           }
-        }
 
-        if (schema.discriminator?.propertyName) {
-          current.hasDiscriminator = true;
-        }
+          if (current.inRequestBody) {
+            current.maxRequestSchemaDepth = Math.max(current.maxRequestSchemaDepth, stats.maxDepth);
+            current.writableTopLevelFieldCount = Math.max(
+              current.writableTopLevelFieldCount,
+              stats.writableTopLevelFields
+            );
+          }
+          if (current.inResponse) {
+            current.maxResponseSchemaDepth = Math.max(
+              current.maxResponseSchemaDepth,
+              stats.maxDepth
+            );
+          }
 
-        if (Array.isArray(schema.oneOf)) {
-          current.polymorphismCount += schema.oneOf.length;
-        }
-        if (Array.isArray(schema.anyOf)) {
-          current.polymorphismCount += schema.anyOf.length;
-          current.anyOfCount += schema.anyOf.length;
-        }
-        if (Array.isArray(schema.allOf)) {
-          current.polymorphismCount += schema.allOf.length;
-        }
-      },
-      leave() {
-        if (accumulator.current?.inMediaType) {
-          accumulator.current.schemaDepth--;
+          if (isDebugTarget && stats.debugEntries) {
+            const context = current.inRequestBody
+              ? 'REQUEST BODY'
+              : `RESPONSE ${current.currentResponseCode}`;
+            accumulator.debugLogs.push({
+              context,
+              entries: stats.debugEntries,
+              totalProperties: stats.propertyCount,
+              totalPolymorphism: stats.polymorphismCount,
+              totalConstraints: stats.constraintCount,
+              maxDepth: stats.maxDepth,
+            });
+          }
         }
       },
     },
@@ -356,14 +461,14 @@ export function getDocumentMetrics(accumulator: ScoreAccumulator): DocumentMetri
   return { operationCount: accumulator.operations.size, operations: accumulator.operations };
 }
 
-function resolveParam(raw: Referenced<Param>, resolve: UserContext['resolve']): Param | undefined {
+function resolveParam(raw: Referenced<Param>, resolve: ResolveFn): Param | undefined {
   return resolve<Param>(raw).node;
 }
 
 function mergeParameters(
   pathLevel: Array<Referenced<Param>>,
   opLevel: Array<Referenced<Param>>,
-  resolve: UserContext['resolve']
+  resolve: ResolveFn
 ): Map<string, Param> {
   const merged = new Map<string, Param>();
   for (const raw of pathLevel) {
diff --git a/packages/cli/src/commands/score/formatters/stylish.ts b/packages/cli/src/commands/score/formatters/stylish.ts
index 1673594404..ac85a5ee12 100644
--- a/packages/cli/src/commands/score/formatters/stylish.ts
+++ b/packages/cli/src/commands/score/formatters/stylish.ts
@@ -1,12 +1,13 @@
 import { logger } from '@redocly/openapi-core';
 import { bold, cyan, green, red, white, yellow } from 'colorette';
 
-import type { ScoreResult } from '../types.js';
+import type { DebugMediaTypeLog, ScoreResult } from '../types.js';
 
-export function printScoreStylish(result: ScoreResult): void {
+export function printScoreStylish(result: ScoreResult, operationDetails = false): void {
   printScores(result);
   printSubscores(result);
   printRawMetricsSummary(result);
+  if (operationDetails) printOperationDetails(result);
   printHotspots(result);
 }
 
@@ -120,6 +121,133 @@ function fmtPct(num: number, denom: number): string {
   return denom > 0 ? `${Math.round((num / denom) * 100)}%` : 'N/A';
 }
 
+function printOperationDetails(result: ScoreResult): void {
+  out(bold(white('  Per-Operation Metrics')));
+  out('');
+
+  const header =
+    '  ' +
+    'Operation'.padEnd(50) +
+    'Props'.padStart(7) +
+    'Poly'.padStart(7) +
+    'Depth'.padStart(7) +
+    'Params'.padStart(8) +
+    'Constr'.padStart(8);
+  out(cyan(header));
+  out(cyan('  ' + '─'.repeat(header.length - 2)));
+
+  const entries = [...result.rawMetrics.operations.entries()].sort(
+    ([, a], [, b]) => b.propertyCount - a.propertyCount
+  );
+
+  for (const [, m] of entries) {
+    const label = (m.operationId ?? `${m.method.toUpperCase()} ${m.path}`).slice(0, 48);
+    const depth = Math.max(m.maxRequestSchemaDepth, m.maxResponseSchemaDepth);
+    const line =
+      '  ' +
+      label.padEnd(50) +
+      String(m.propertyCount).padStart(7) +
+      String(m.polymorphismCount).padStart(7) +
+      String(depth).padStart(7) +
+      String(m.parameterCount).padStart(8) +
+      String(m.constraintCount).padStart(8);
+    out(line);
+  }
+  out('');
+}
+
+export function printDebugOperation(operationId: string, logs: DebugMediaTypeLog[]): void {
+  out('');
+  out(bold(white(`  Debug: ${operationId} schema breakdown`)));
+  out('');
+
+  if (logs.length === 0) {
+    out(yellow(`  No schemas found for operation "${operationId}".`));
+    out(yellow('  Make sure the value matches an operationId or "METHOD /path" exactly.'));
+    out('');
+    return;
+  }
+
+  for (const log of logs) {
+    out(bold(cyan(`  ${log.context}`)));
+    out(cyan('  ' + '─'.repeat(70)));
+
+    const refGroups = new Map<string, { count: number; totalProps: number; propNames: string[] }>();
+
+    for (const entry of log.entries) {
+      const key = entry.ref ?? `(inline depth ${entry.depth})`;
+      const group = refGroups.get(key);
+      if (group) {
+        group.count++;
+        group.totalProps += entry.propertyNames.length;
+        for (const n of entry.propertyNames) {
+          if (!group.propNames.includes(n)) group.propNames.push(n);
+        }
+      } else {
+        refGroups.set(key, {
+          count: 1,
+          totalProps: entry.propertyNames.length,
+          propNames: [...entry.propertyNames],
+        });
+      }
+    }
+
+    for (const entry of log.entries) {
+      const label = entry.ref ?? '(inline)';
+      const depthPad = '  '.repeat(Math.min(entry.depth, 6));
+      const propCount = entry.propertyNames.length;
+
+      let line = `  ${depthPad}${label}`;
+      if (propCount > 0) {
+        line += ` (${propCount} properties)`;
+      }
+
+      const polyParts: string[] = [];
+      if (entry.polymorphism.oneOf) polyParts.push(`oneOf:${entry.polymorphism.oneOf}`);
+      if (entry.polymorphism.anyOf) polyParts.push(`anyOf:${entry.polymorphism.anyOf}`);
+      if (entry.polymorphism.allOf) polyParts.push(`allOf:${entry.polymorphism.allOf}`);
+      if (polyParts.length > 0) {
+        line += ` [${polyParts.join(', ')}]`;
+      }
+      if (entry.constraintCount > 0) {
+        line += ` {${entry.constraintCount} constraints}`;
+      }
+
+      out(line);
+
+      if (propCount > 0 && propCount <= 20) {
+        out(`  ${depthPad}  properties: ${entry.propertyNames.join(', ')}`);
+      } else if (propCount > 20) {
+        const preview = entry.propertyNames.slice(0, 15).join(', ');
+        out(`  ${depthPad}  properties: ${preview}, ... +${propCount - 15} more`);
+      }
+    }
+
+    out('');
+    out(
+      `  Totals: ${log.totalProperties} properties, ` +
+        `${log.totalPolymorphism} polymorphism items, ` +
+        `${log.totalConstraints} constraints, ` +
+        `max depth ${log.maxDepth}`
+    );
+
+    const topRefs = [...refGroups.entries()]
+      .filter(([, v]) => v.totalProps > 0)
+      .sort(([, a], [, b]) => b.totalProps - a.totalProps)
+      .slice(0, 10);
+
+    if (topRefs.length > 0) {
+      out('');
+      out(bold('  Top schemas by property count:'));
+      for (const [ref, data] of topRefs) {
+        out(`    ${ref}: ${data.totalProps} properties`);
+      }
+    }
+
+    out('');
+  }
+}
+
 function printHotspots(result: ScoreResult): void {
   if (result.hotspots.length === 0) {
     out(bold(white('  No hotspot operations found.')));
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
index 06a6fe6a17..25d5458065 100644
--- a/packages/cli/src/commands/score/index.ts
+++ b/packages/cli/src/commands/score/index.ts
@@ -8,8 +8,9 @@ import {
   walkDocument,
   bundle,
   logger,
+  type OutputFormat,
+  type WalkContext,
 } from '@redocly/openapi-core';
-import type { OutputFormat, WalkContext } from '@redocly/openapi-core';
 import * as colors from 'colorette';
 import { performance } from 'perf_hooks';
 
@@ -19,11 +20,14 @@ import type { CommandArgs } from '../../wrapper.js';
 import {
   createScoreAccumulator,
   createScoreVisitor,
+  createSchemaWalkState,
+  resetSchemaWalkState,
+  createSchemaMetricVisitor,
   getDocumentMetrics,
 } from './collectors/document-metrics.js';
 import { computeWorkflowDepths } from './collectors/workflow-graph.js';
 import { printScoreJson } from './formatters/json.js';
-import { printScoreStylish } from './formatters/stylish.js';
+import { printDebugOperation, printScoreStylish } from './formatters/stylish.js';
 import { selectTopHotspots } from './hotspots.js';
 import {
   averageAgentSubscores,
@@ -31,11 +35,22 @@ import {
   computeAllOperationScores,
   computeDocumentScores,
 } from './scoring.js';
-import type { ScoreResult } from './types.js';
+import type { DebugMediaTypeLog, ScoreResult } from './types.js';
+
+function resolveJsonPointer(root: any, ref: string): any {
+  if (!ref.startsWith('#/')) return undefined;
+  let node = root;
+  for (const segment of ref.slice(2).split('/')) {
+    node = node?.[decodeURIComponent(segment)];
+  }
+  return node;
+}
 
 export type ScoreArgv = {
   api?: string;
   format: OutputFormat;
+  'operation-details'?: boolean;
+  'debug-operation-id'?: string;
 } & VerifyConfigOptions;
 
 export async function handleScore({ argv, config, collectSpecData }: CommandArgs<ScoreArgv>) {
@@ -56,8 +71,6 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
   const startedAt = performance.now();
 
   const types = normalizeTypes(config.extendTypes(getTypes(specVersion), specVersion), config);
-  const accumulator = createScoreAccumulator();
-  const scoreVisitor = createScoreVisitor(accumulator);
 
   const resolvedRefMap = await resolveDocument({
     rootDocument: document,
@@ -72,6 +85,107 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
     visitorsData: {},
   };
 
+  const schemaWalkState = createSchemaWalkState();
+  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
+  const normalizedSchemaVisitors = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor as any }],
+    types
+  );
+
+  type SchemaStats = ReturnType<typeof walkSchemaRaw>;
+
+  const walkSchemaRaw = (schemaNode: any, debug: boolean) => {
+    resetSchemaWalkState(schemaWalkState);
+    if (debug) schemaWalkState.debugEntries = [];
+    walkDocument({
+      document: { ...document, parsed: schemaNode },
+      rootType: types.Schema,
+      normalizedVisitors: normalizedSchemaVisitors,
+      resolvedRefMap,
+      ctx,
+    });
+    return {
+      maxDepth: schemaWalkState.maxDepth,
+      polymorphismCount: schemaWalkState.polymorphismCount,
+      anyOfCount: schemaWalkState.anyOfCount,
+      hasDiscriminator: schemaWalkState.hasDiscriminator,
+      propertyCount: schemaWalkState.propertyCount,
+      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
+      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
+      constraintCount: schemaWalkState.constraintCount,
+      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
+      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
+      refsUsed: [...schemaWalkState.refsUsed],
+      debugEntries: debug ? (schemaWalkState.debugEntries ?? undefined) : undefined,
+    };
+  };
+
+  const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
+    let resolved = schemaNode;
+    if (schemaNode?.$ref && typeof schemaNode.$ref === 'string') {
+      resolved = resolveJsonPointer(document.parsed, schemaNode.$ref) ?? schemaNode;
+    }
+
+    const polyKeyword: 'oneOf' | 'anyOf' | null =
+      Array.isArray(resolved?.oneOf) && resolved.oneOf.length > 1
+        ? 'oneOf'
+        : Array.isArray(resolved?.anyOf) && resolved.anyOf.length > 1
+          ? 'anyOf'
+          : null;
+
+    if (polyKeyword && !resolved.allOf) {
+      const branches = resolved[polyKeyword] as any[];
+
+      const parentOnly = { ...resolved };
+      delete parentOnly[polyKeyword];
+      delete parentOnly.discriminator;
+
+      let maxBranch = walkSchema(branches[0], debug);
+      for (let i = 1; i < branches.length; i++) {
+        const branchStats = walkSchema(branches[i], debug);
+        if (branchStats.propertyCount > maxBranch.propertyCount) {
+          maxBranch = branchStats;
+        }
+      }
+
+      const parentStats = walkSchemaRaw(parentOnly, debug);
+
+      return combineOneOfStats(parentStats, maxBranch, branches.length, polyKeyword);
+    }
+
+    return walkSchemaRaw(schemaNode, debug);
+  };
+
+  function combineOneOfStats(
+    parent: SchemaStats,
+    branch: SchemaStats,
+    branchCount: number,
+    keyword: 'oneOf' | 'anyOf'
+  ): SchemaStats {
+    return {
+      maxDepth: Math.max(parent.maxDepth, branch.maxDepth + 1),
+      polymorphismCount: parent.polymorphismCount + branch.polymorphismCount + branchCount,
+      anyOfCount: parent.anyOfCount + branch.anyOfCount + (keyword === 'anyOf' ? branchCount : 0),
+      hasDiscriminator: parent.hasDiscriminator || branch.hasDiscriminator,
+      propertyCount: parent.propertyCount + branch.propertyCount,
+      totalSchemaProperties: parent.totalSchemaProperties + branch.totalSchemaProperties,
+      schemaPropertiesWithDescription:
+        parent.schemaPropertiesWithDescription + branch.schemaPropertiesWithDescription,
+      constraintCount: parent.constraintCount + branch.constraintCount,
+      hasPropertyExamples: parent.hasPropertyExamples || branch.hasPropertyExamples,
+      writableTopLevelFields: parent.writableTopLevelFields + branch.writableTopLevelFields,
+      refsUsed: [...parent.refsUsed, ...branch.refsUsed],
+      debugEntries:
+        parent.debugEntries || branch.debugEntries
+          ? [...(parent.debugEntries ?? []), ...(branch.debugEntries ?? [])]
+          : undefined,
+    };
+  }
+
+  const debugOpId = argv['debug-operation-id'];
+  const accumulator = createScoreAccumulator(walkSchema, debugOpId);
+  const scoreVisitor = createScoreVisitor(accumulator);
+
   const normalizedVisitors = normalizeVisitors(
     [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
     types
@@ -103,10 +217,24 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
     workflowDepths,
   };
 
-  printScore(result, path, startedAt, argv.format);
+  printScore(
+    result,
+    path,
+    startedAt,
+    argv.format,
+    !!argv['operation-details'],
+    debugOpId ? { operationId: debugOpId, logs: accumulator.debugLogs } : undefined
+  );
 }
 
-function printScore(result: ScoreResult, api: string, startedAt: number, format: string): void {
+function printScore(
+  result: ScoreResult,
+  api: string,
+  startedAt: number,
+  format: string,
+  operationDetails: boolean,
+  debugData?: { operationId: string; logs: DebugMediaTypeLog[] }
+): void {
   logger.info(`Document: ${colors.magenta(api)} score:\n`);
 
   switch (format) {
@@ -114,9 +242,13 @@ function printScore(result: ScoreResult, api: string, startedAt: number, format:
       printScoreJson(result);
       break;
     default:
-      printScoreStylish(result);
+      printScoreStylish(result, operationDetails);
       break;
   }
 
+  if (debugData) {
+    printDebugOperation(debugData.operationId, debugData.logs);
+  }
+
   printExecutionTime('score', startedAt, api);
 }
diff --git a/packages/cli/src/commands/score/types.ts b/packages/cli/src/commands/score/types.ts
index 5b346f6c25..586d1a0608 100644
--- a/packages/cli/src/commands/score/types.ts
+++ b/packages/cli/src/commands/score/types.ts
@@ -122,3 +122,20 @@ export interface ScoringConstants {
   weights: ScoringWeights;
   hotspotLimit: number;
 }
+
+export interface DebugSchemaEntry {
+  ref: string | null;
+  depth: number;
+  propertyNames: string[];
+  polymorphism: { oneOf?: number; anyOf?: number; allOf?: number };
+  constraintCount: number;
+}
+
+export interface DebugMediaTypeLog {
+  context: string;
+  entries: DebugSchemaEntry[];
+  totalProperties: number;
+  totalPolymorphism: number;
+  totalConstraints: number;
+  maxDepth: number;
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 2f0ec4c011..2b86faaa01 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -93,6 +93,15 @@ yargs(hideBin(process.argv))
             choices: ['stylish', 'json', 'markdown'] as ReadonlyArray<OutputFormat>,
             default: 'stylish' as OutputFormat,
           },
+          'operation-details': {
+            description: 'Print per-operation metric details.',
+            type: 'boolean' as const,
+            default: false,
+          },
+          'debug-operation-id': {
+            description: 'Print detailed schema breakdown for a specific operation.',
+            type: 'string' as const,
+          },
         }),
     (argv) => {
       commandWrapper(handleScore)(argv);
diff --git a/tests/e2e/score/score-json/snapshot.txt b/tests/e2e/score/score-json/snapshot.txt
index 7b720786a2..b63a0a7a27 100644
--- a/tests/e2e/score/score-json/snapshot.txt
+++ b/tests/e2e/score/score-json/snapshot.txt
@@ -1,22 +1,22 @@
 {
-  "integrationSimplicity": 82.1,
-  "agentReadiness": 81.2,
+  "integrationSimplicity": 83,
+  "agentReadiness": 86.6,
   "integrationSubscores": {
     "parameterSimplicity": 0.8625,
-    "schemaSimplicity": 0.921875,
-    "documentationQuality": 0.9374999999999999,
-    "constraintClarity": 0.27575757575757576,
-    "exampleCoverage": 0.75,
+    "schemaSimplicity": 0.796875,
+    "documentationQuality": 0.9017857142857143,
+    "constraintClarity": 0.5833333333333333,
+    "exampleCoverage": 0.875,
     "errorClarity": 1,
-    "workflowClarity": 0.8333333333333333
+    "workflowClarity": 0.7291666666666669
   },
   "agentSubscores": {
-    "documentationQuality": 0.9374999999999999,
-    "constraintClarity": 0.27575757575757576,
-    "exampleCoverage": 0.75,
+    "documentationQuality": 0.9017857142857143,
+    "constraintClarity": 0.5833333333333333,
+    "exampleCoverage": 0.875,
     "errorClarity": 1,
     "identifierClarity": 1,
-    "workflowClarity": 0.8333333333333333,
+    "workflowClarity": 0.7291666666666669,
     "polymorphismClarity": 1
   },
   "rawMetrics": {
@@ -36,10 +36,10 @@
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 5,
+        "propertyCount": 3,
         "operationDescriptionPresent": true,
         "schemaPropertiesWithDescription": 2,
-        "totalSchemaProperties": 5,
+        "totalSchemaProperties": 3,
         "constraintCount": 3,
         "requestExamplePresent": false,
         "responseExamplePresent": true,
@@ -57,7 +57,7 @@
         "requestBodyPresent": false,
         "topLevelWritableFieldCount": 0,
         "maxRequestSchemaDepth": 0,
-        "maxResponseSchemaDepth": 2,
+        "maxResponseSchemaDepth": 3,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
@@ -65,7 +65,7 @@
         "operationDescriptionPresent": true,
         "schemaPropertiesWithDescription": 6,
         "totalSchemaProperties": 6,
-        "constraintCount": 2,
+        "constraintCount": 3,
         "requestExamplePresent": false,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
@@ -81,16 +81,16 @@
         "paramsWithDescription": 0,
         "requestBodyPresent": true,
         "topLevelWritableFieldCount": 5,
-        "maxRequestSchemaDepth": 0,
-        "maxResponseSchemaDepth": 0,
+        "maxRequestSchemaDepth": 2,
+        "maxResponseSchemaDepth": 2,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 5,
+        "propertyCount": 6,
         "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 5,
-        "totalSchemaProperties": 5,
-        "constraintCount": 0,
+        "schemaPropertiesWithDescription": 6,
+        "totalSchemaProperties": 6,
+        "constraintCount": 3,
         "requestExamplePresent": true,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
@@ -107,15 +107,15 @@
         "requestBodyPresent": false,
         "topLevelWritableFieldCount": 0,
         "maxRequestSchemaDepth": 0,
-        "maxResponseSchemaDepth": 0,
+        "maxResponseSchemaDepth": 2,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 0,
+        "propertyCount": 6,
         "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 0,
-        "totalSchemaProperties": 0,
-        "constraintCount": 0,
+        "schemaPropertiesWithDescription": 6,
+        "totalSchemaProperties": 6,
+        "constraintCount": 3,
         "requestExamplePresent": false,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
@@ -132,17 +132,17 @@
         "requestBodyPresent": false,
         "topLevelWritableFieldCount": 0,
         "maxRequestSchemaDepth": 0,
-        "maxResponseSchemaDepth": 0,
+        "maxResponseSchemaDepth": 1,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 0,
+        "propertyCount": 2,
         "operationDescriptionPresent": true,
         "schemaPropertiesWithDescription": 0,
-        "totalSchemaProperties": 0,
+        "totalSchemaProperties": 2,
         "constraintCount": 0,
         "requestExamplePresent": false,
-        "responseExamplePresent": false,
+        "responseExamplePresent": true,
         "structuredErrorResponseCount": 1,
         "totalErrorResponses": 1,
         "ambiguousIdentifierCount": 0
@@ -156,16 +156,16 @@
         "paramsWithDescription": 1,
         "requestBodyPresent": true,
         "topLevelWritableFieldCount": 5,
-        "maxRequestSchemaDepth": 0,
-        "maxResponseSchemaDepth": 0,
+        "maxRequestSchemaDepth": 2,
+        "maxResponseSchemaDepth": 2,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 5,
+        "propertyCount": 6,
         "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 5,
-        "totalSchemaProperties": 5,
-        "constraintCount": 0,
+        "schemaPropertiesWithDescription": 6,
+        "totalSchemaProperties": 6,
+        "constraintCount": 3,
         "requestExamplePresent": true,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
@@ -186,11 +186,11 @@
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 11,
+        "propertyCount": 6,
         "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 9,
-        "totalSchemaProperties": 11,
-        "constraintCount": 3,
+        "schemaPropertiesWithDescription": 5,
+        "totalSchemaProperties": 6,
+        "constraintCount": 4,
         "requestExamplePresent": true,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
@@ -226,20 +226,20 @@
   },
   "operationScores": {
     "getMuseumHours": {
-      "integrationSimplicity": 78.3,
-      "agentReadiness": 85.7,
+      "integrationSimplicity": 85.2,
+      "agentReadiness": 95.5,
       "integrationSubscores": {
         "parameterSimplicity": 0.7,
         "schemaSimplicity": 0.75,
-        "documentationQuality": 0.6666666666666666,
-        "constraintClarity": 0.6,
+        "documentationQuality": 0.8571428571428571,
+        "constraintClarity": 1,
         "exampleCoverage": 1,
         "errorClarity": 1,
         "workflowClarity": 0.8333333333333334
       },
       "agentSubscores": {
-        "documentationQuality": 0.6666666666666666,
-        "constraintClarity": 0.6,
+        "documentationQuality": 0.8571428571428571,
+        "constraintClarity": 1,
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
@@ -248,140 +248,140 @@
       }
     },
     "listSpecialEvents": {
-      "integrationSimplicity": 78.7,
-      "agentReadiness": 88.3,
+      "integrationSimplicity": 76.2,
+      "agentReadiness": 89.2,
       "integrationSubscores": {
         "parameterSimplicity": 0.6,
-        "schemaSimplicity": 0.75,
+        "schemaSimplicity": 0.625,
         "documentationQuality": 1,
-        "constraintClarity": 0.3333333333333333,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.8333333333333334
+        "workflowClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 1,
-        "constraintClarity": 0.3333333333333333,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.8333333333333334,
+        "workflowClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
     "createSpecialEvent": {
-      "integrationSimplicity": 88.3,
-      "agentReadiness": 83.3,
+      "integrationSimplicity": 86.7,
+      "agentReadiness": 89.2,
       "integrationSubscores": {
         "parameterSimplicity": 1,
-        "schemaSimplicity": 1,
+        "schemaSimplicity": 0.75,
         "documentationQuality": 1,
-        "constraintClarity": 0,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.8333333333333334
+        "workflowClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 1,
-        "constraintClarity": 0,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.8333333333333334,
+        "workflowClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
     "getSpecialEvent": {
-      "integrationSimplicity": 86.3,
-      "agentReadiness": 83.3,
+      "integrationSimplicity": 84.7,
+      "agentReadiness": 89.2,
       "integrationSubscores": {
         "parameterSimplicity": 0.9,
-        "schemaSimplicity": 1,
+        "schemaSimplicity": 0.75,
         "documentationQuality": 1,
-        "constraintClarity": 0,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.8333333333333334
+        "workflowClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 1,
-        "constraintClarity": 0,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.8333333333333334,
+        "workflowClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
     "deleteSpecialEvent": {
-      "integrationSimplicity": 71.3,
-      "agentReadiness": 63.3,
+      "integrationSimplicity": 74.7,
+      "agentReadiness": 71.7,
       "integrationSubscores": {
         "parameterSimplicity": 0.9,
-        "schemaSimplicity": 1,
-        "documentationQuality": 1,
+        "schemaSimplicity": 0.875,
+        "documentationQuality": 0.5,
         "constraintClarity": 0,
-        "exampleCoverage": 0,
+        "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.8333333333333334
+        "workflowClarity": 0.6666666666666667
       },
       "agentSubscores": {
-        "documentationQuality": 1,
+        "documentationQuality": 0.5,
         "constraintClarity": 0,
-        "exampleCoverage": 0,
+        "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.8333333333333334,
+        "workflowClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
     "updateSpecialEvent": {
-      "integrationSimplicity": 86.3,
-      "agentReadiness": 83.3,
+      "integrationSimplicity": 84.7,
+      "agentReadiness": 89.2,
       "integrationSubscores": {
         "parameterSimplicity": 0.9,
-        "schemaSimplicity": 1,
+        "schemaSimplicity": 0.75,
         "documentationQuality": 1,
-        "constraintClarity": 0,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.8333333333333334
+        "workflowClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 1,
-        "constraintClarity": 0,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.8333333333333334,
+        "workflowClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
     "buyMuseumTickets": {
-      "integrationSimplicity": 86.1,
-      "agentReadiness": 84.1,
+      "integrationSimplicity": 88.7,
+      "agentReadiness": 88.8,
       "integrationSubscores": {
         "parameterSimplicity": 1,
         "schemaSimplicity": 0.875,
-        "documentationQuality": 0.8333333333333334,
-        "constraintClarity": 0.2727272727272727,
+        "documentationQuality": 0.8571428571428571,
+        "constraintClarity": 0.6666666666666666,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.8333333333333334
+        "workflowClarity": 0.6666666666666667
       },
       "agentSubscores": {
-        "documentationQuality": 0.8333333333333334,
-        "constraintClarity": 0.2727272727272727,
+        "documentationQuality": 0.8571428571428571,
+        "constraintClarity": 0.6666666666666666,
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.8333333333333334,
+        "workflowClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
     "getTicketCode": {
-      "integrationSimplicity": 81.3,
-      "agentReadiness": 78.3,
+      "integrationSimplicity": 83,
+      "agentReadiness": 80,
       "integrationSubscores": {
         "parameterSimplicity": 0.9,
         "schemaSimplicity": 1,
@@ -389,7 +389,7 @@
         "constraintClarity": 1,
         "exampleCoverage": 0,
         "errorClarity": 1,
-        "workflowClarity": 0.8333333333333334
+        "workflowClarity": 1
       },
       "agentSubscores": {
         "documentationQuality": 1,
@@ -397,38 +397,28 @@
         "exampleCoverage": 0,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.8333333333333334,
+        "workflowClarity": 1,
         "polymorphismClarity": 1
       }
     }
   },
   "workflowDepths": {
     "getMuseumHours": 1,
-    "listSpecialEvents": 1,
-    "createSpecialEvent": 1,
-    "getSpecialEvent": 1,
-    "deleteSpecialEvent": 1,
-    "updateSpecialEvent": 1,
-    "buyMuseumTickets": 1,
-    "getTicketCode": 1
+    "listSpecialEvents": 2,
+    "createSpecialEvent": 2,
+    "getSpecialEvent": 2,
+    "deleteSpecialEvent": 2,
+    "updateSpecialEvent": 2,
+    "buyMuseumTickets": 2,
+    "getTicketCode": 0
   },
   "hotspots": [
-    {
-      "path": "/special-events/{eventId}",
-      "method": "delete",
-      "operationId": "deleteSpecialEvent",
-      "integrationSimplicityScore": 71.3,
-      "agentReadinessScore": 63.3,
-      "reasons": [
-        "Missing response examples"
-      ]
-    },
     {
       "path": "/tickets/{ticketId}/qr",
       "method": "get",
       "operationId": "getTicketCode",
-      "integrationSimplicityScore": 81.3,
-      "agentReadinessScore": 78.3,
+      "integrationSimplicityScore": 83,
+      "agentReadinessScore": 80,
       "reasons": [
         "Missing response examples"
       ]
diff --git a/tests/e2e/score/score-minimal/snapshot.txt b/tests/e2e/score/score-minimal/snapshot.txt
index 09037529a4..6695a9404f 100644
--- a/tests/e2e/score/score-minimal/snapshot.txt
+++ b/tests/e2e/score/score-minimal/snapshot.txt
@@ -12,7 +12,7 @@
   Constraint Clarity       [░░░░░░░░░░░░░░░░░░░░] 0%
   Example Coverage         [░░░░░░░░░░░░░░░░░░░░] 0%
   Error Clarity            [████████████████████] 100%
-  Workflow Clarity         [████████████████████] 100%
+  Dependency Clarity       [████████████████████] 100%
 
   Agent Readiness Subscores
 
@@ -21,7 +21,7 @@
   Example Coverage         [░░░░░░░░░░░░░░░░░░░░] 0%
   Error Clarity            [████████████████████] 100%
   Identifier Clarity       [█████████████░░░░░░░] 67%
-  Workflow Clarity         [████████████████████] 100%
+  Dependency Clarity       [████████████████████] 100%
   Polymorphism Clarity     [████████████████████] 100%
 
   Raw Metrics Summary
diff --git a/tests/e2e/score/score-stylish/snapshot.txt b/tests/e2e/score/score-stylish/snapshot.txt
index f75c76ea20..cc6ac4998f 100644
--- a/tests/e2e/score/score-stylish/snapshot.txt
+++ b/tests/e2e/score/score-stylish/snapshot.txt
@@ -1,48 +1,44 @@
 
   Scores
 
-  Integration Simplicity:  82.1/100
-  Agent Readiness:         81.2/100
+  Integration Simplicity:  83.0/100
+  Agent Readiness:         86.6/100
 
   Integration Simplicity Subscores
 
   Parameter Simplicity     [█████████████████░░░] 86%
-  Schema Simplicity        [██████████████████░░] 92%
-  Documentation Quality    [███████████████████░] 94%
-  Constraint Clarity       [██████░░░░░░░░░░░░░░] 28%
-  Example Coverage         [███████████████░░░░░] 75%
+  Schema Simplicity        [████████████████░░░░] 80%
+  Documentation Quality    [██████████████████░░] 90%
+  Constraint Clarity       [████████████░░░░░░░░] 58%
+  Example Coverage         [██████████████████░░] 88%
   Error Clarity            [████████████████████] 100%
-  Workflow Clarity         [█████████████████░░░] 83%
+  Dependency Clarity       [███████████████░░░░░] 73%
 
   Agent Readiness Subscores
 
-  Documentation Quality    [███████████████████░] 94%
-  Constraint Clarity       [██████░░░░░░░░░░░░░░] 28%
-  Example Coverage         [███████████████░░░░░] 75%
+  Documentation Quality    [██████████████████░░] 90%
+  Constraint Clarity       [████████████░░░░░░░░] 58%
+  Example Coverage         [██████████████████░░] 88%
   Error Clarity            [████████████████████] 100%
   Identifier Clarity       [████████████████████] 100%
-  Workflow Clarity         [█████████████████░░░] 83%
+  Dependency Clarity       [███████████████░░░░░] 73%
   Polymorphism Clarity     [████████████████████] 100%
 
   Raw Metrics Summary
 
   Total operations: 8
   Avg parameters/operation: 1.4
-  Avg max schema depth: 0.6
+  Avg max schema depth: 1.6
   Avg polymorphism/operation: 0.0
-  Avg properties/operation: 4.0
+  Avg properties/operation: 4.4
   Operations with request examples: 3/8 (38%)
-  Operations with response examples: 6/8 (75%)
+  Operations with response examples: 7/8 (88%)
   Operations with description: 8/8 (100%)
 
-  Top 2 Hotspot Operations
-
-  DELETE /special-events/{eventId} (deleteSpecialEvent)
-    Integration Simplicity: 71.3  Agent Readiness: 63.3
-    - Missing response examples
+  Top 1 Hotspot Operations
 
   GET /tickets/{ticketId}/qr (getTicketCode)
-    Integration Simplicity: 81.3  Agent Readiness: 78.3
+    Integration Simplicity: 83.0  Agent Readiness: 80.0
     - Missing response examples
 
 

From a150a077e53ddb8dd4683b7d2df9da9b57cce7dd Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Tue, 24 Mar 2026 06:58:13 -0500
Subject: [PATCH 10/22] chore: address PR review feedback from tatomyr

- Inline collect-metrics.ts test helper into document-metrics.test.ts
- Use parseYaml as yaml directly instead of wrapper function
- Remove default parameter from getStylishOutput in formatter tests
- Use getMajorSpecVersion + exitWithError for spec version check
- Add explicit case 'stylish' before default in format switch
- Remove unsupported 'markdown' from score command format choices
- Add comment explaining depth=-1 initialization
- Clarify anyOf penalty and dependency terminology in docs
- Update non-oas3 rejection test for exitWithError (throws)

Made-with: Cursor
---
 docs/@v2/commands/score.md                    | 34 ++++----
 .../score/__tests__/collect-metrics.ts        | 82 ------------------
 .../score/__tests__/document-metrics.test.ts  | 83 ++++++++++++++++++-
 .../score/__tests__/formatters.test.ts        |  4 +-
 .../commands/score/__tests__/index.test.ts    |  7 +-
 .../score/collectors/document-metrics.ts      |  6 +-
 packages/cli/src/commands/score/index.ts      | 11 +--
 packages/cli/src/index.ts                     |  2 +-
 8 files changed, 110 insertions(+), 119 deletions(-)
 delete mode 100644 packages/cli/src/commands/score/__tests__/collect-metrics.ts

diff --git a/docs/@v2/commands/score.md b/docs/@v2/commands/score.md
index 614dcf6818..40d0114642 100644
--- a/docs/@v2/commands/score.md
+++ b/docs/@v2/commands/score.md
@@ -18,22 +18,22 @@ OpenAPI 2.0 (Swagger) and AsyncAPI are not currently supported.
 
 The following raw metrics are collected per operation and aggregated across the document:
 
-| Metric                             | Description                                                                                                                          |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| Parameter count                    | Total parameters (path, query, header, cookie) per operation.                                                                        |
-| Required parameter count           | How many of those parameters are required.                                                                                           |
-| Request body presence              | Whether the operation defines a request body.                                                                                        |
-| Top-level writable field count     | Number of non-`readOnly` top-level properties in request schemas.                                                                    |
-| Max request/response schema depth  | Deepest nesting level in request and response schemas.                                                                               |
-| Polymorphism count                 | Number of `oneOf`, `anyOf`, and `allOf` usages. `anyOf` is penalized more heavily.                                                   |
-| Property count                     | Total schema properties across request and response.                                                                                 |
-| Description coverage               | Fraction of operations, parameters, and schema properties that have descriptions.                                                    |
-| Ambiguous identifier count         | Parameters with generic names (e.g. `id`, `name`, `type`) and no description.                                                        |
-| Constraint coverage                | Count of constraining keywords (`enum`, `format`, `pattern`, `minimum`, `maximum`, `minLength`, `maxLength`, `discriminator`, etc.). |
-| Request/response example coverage  | Whether request and response media types include `example` or `examples`.                                                            |
-| Structured error response coverage | How many 4xx/5xx responses include a content schema or meaningful description.                                                       |
-| Security scheme coverage           | Whether operations reference documented security schemes with descriptions.                                                          |
-| Cross-operation dependency depth   | Inferred from shared `$ref` usage across operations; deeper shared-schema graphs indicate tightly coupled multi-step interactions.   |
+| Metric                             | Description                                                                                                                                                                                                         |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Parameter count                    | Total parameters (path, query, header, cookie) per operation.                                                                                                                                                       |
+| Required parameter count           | How many of those parameters are required.                                                                                                                                                                          |
+| Request body presence              | Whether the operation defines a request body.                                                                                                                                                                       |
+| Top-level writable field count     | Number of non-`readOnly` top-level properties in request schemas.                                                                                                                                                   |
+| Max request/response schema depth  | Deepest nesting level in request and response schemas.                                                                                                                                                              |
+| Polymorphism count                 | Number of `oneOf`, `anyOf`, and `allOf` usages. `anyOf` is penalized more heavily because it allows ambiguous combinations of schemas, making it harder for consumers and AI agents to determine the correct shape. |
+| Property count                     | Total schema properties across request and response.                                                                                                                                                                |
+| Description coverage               | Fraction of operations, parameters, and schema properties that have descriptions.                                                                                                                                   |
+| Ambiguous identifier count         | Parameters with generic names (e.g. `id`, `name`, `type`) and no description.                                                                                                                                       |
+| Constraint coverage                | Count of constraining keywords (`enum`, `format`, `pattern`, `minimum`, `maximum`, `minLength`, `maxLength`, `discriminator`, etc.).                                                                                |
+| Request/response example coverage  | Whether request and response media types include `example` or `examples`.                                                                                                                                           |
+| Structured error response coverage | How many 4xx/5xx responses include a content schema or meaningful description.                                                                                                                                      |
+| Security scheme coverage           | Whether operations reference documented security schemes with descriptions.                                                                                                                                         |
+| Cross-operation dependency depth   | Inferred from shared `$ref` usage across operations. Operations that share many schemas form a dependency graph; deeper graphs indicate tightly coupled multi-step interactions.                                    |
 
 ### Subscores
 
@@ -126,6 +126,6 @@ Use `--format=json` for machine-readable output:
 redocly score openapi.yaml --format=json
 ```
 
-The JSON output includes the full data: top-level scores, subscores, per-operation raw metrics, per-operation scores, workflow depths, and hotspot details with reasoning.
+The JSON output includes the full data: top-level scores, subscores, per-operation raw metrics, per-operation scores, dependency depths, and hotspot details with reasoning.
 
 The JSON format is suitable for CI pipelines, quality gates, or feeding results into dashboards.
diff --git a/packages/cli/src/commands/score/__tests__/collect-metrics.ts b/packages/cli/src/commands/score/__tests__/collect-metrics.ts
deleted file mode 100644
index 0248b001b9..0000000000
--- a/packages/cli/src/commands/score/__tests__/collect-metrics.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-import {
-  normalizeTypes,
-  getTypes,
-  normalizeVisitors,
-  walkDocument,
-  resolveDocument,
-  BaseResolver,
-  Source,
-} from '@redocly/openapi-core';
-import type { Document, WalkContext } from '@redocly/openapi-core';
-
-import {
-  createScoreAccumulator,
-  createScoreVisitor,
-  createSchemaWalkState,
-  resetSchemaWalkState,
-  createSchemaMetricVisitor,
-  getDocumentMetrics,
-} from '../collectors/document-metrics.js';
-import type { DocumentMetrics } from '../types.js';
-
-export async function collectDocumentMetrics(
-  doc: Record<string, unknown>
-): Promise<DocumentMetrics> {
-  const types = normalizeTypes(getTypes('oas3_0'), {});
-  const source = new Source('test.yaml', JSON.stringify(doc));
-  const document: Document = { source, parsed: doc };
-  const externalRefResolver = new BaseResolver();
-  const resolvedRefMap = await resolveDocument({
-    rootDocument: document,
-    rootType: types.Root,
-    externalRefResolver,
-  });
-  const ctx: WalkContext = {
-    problems: [],
-    specVersion: 'oas3_0',
-    visitorsData: {},
-  };
-
-  const schemaWalkState = createSchemaWalkState();
-  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
-  const normalizedSchemaVis = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'test-schema', visitor: schemaVisitor }],
-    types
-  );
-
-  const walkSchema = (schemaNode: any) => {
-    resetSchemaWalkState(schemaWalkState);
-    walkDocument({
-      document: { ...document, parsed: schemaNode },
-      rootType: types.Schema,
-      normalizedVisitors: normalizedSchemaVis,
-      resolvedRefMap,
-      ctx,
-    });
-    return {
-      maxDepth: schemaWalkState.maxDepth,
-      polymorphismCount: schemaWalkState.polymorphismCount,
-      anyOfCount: schemaWalkState.anyOfCount,
-      hasDiscriminator: schemaWalkState.hasDiscriminator,
-      propertyCount: schemaWalkState.propertyCount,
-      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
-      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
-      constraintCount: schemaWalkState.constraintCount,
-      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
-      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
-      refsUsed: [...schemaWalkState.refsUsed],
-    };
-  };
-
-  const accumulator = createScoreAccumulator(walkSchema);
-  const visitor = createScoreVisitor(accumulator);
-  const normalizedVis = normalizeVisitors([{ severity: 'warn', ruleId: 'test', visitor }], types);
-  walkDocument({
-    document,
-    rootType: types.Root,
-    normalizedVisitors: normalizedVis,
-    resolvedRefMap,
-    ctx,
-  });
-  return getDocumentMetrics(accumulator);
-}
diff --git a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
index d971a5589f..2f8c00d552 100644
--- a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
+++ b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
@@ -1,10 +1,85 @@
-import { parseYaml } from '@redocly/openapi-core';
+import {
+  normalizeTypes,
+  getTypes,
+  normalizeVisitors,
+  walkDocument,
+  resolveDocument,
+  BaseResolver,
+  Source,
+  parseYaml as yaml,
+  type Document,
+  type WalkContext,
+} from '@redocly/openapi-core';
 import { outdent } from 'outdent';
 
-import { collectDocumentMetrics } from './collect-metrics.js';
+import {
+  createScoreAccumulator,
+  createScoreVisitor,
+  createSchemaWalkState,
+  resetSchemaWalkState,
+  createSchemaMetricVisitor,
+  getDocumentMetrics,
+} from '../collectors/document-metrics.js';
+import type { DocumentMetrics } from '../types.js';
 
-function yaml(source: string): Record<string, unknown> {
-  return parseYaml(source) as Record<string, unknown>;
+async function collectDocumentMetrics(doc: Record<string, unknown>): Promise<DocumentMetrics> {
+  const types = normalizeTypes(getTypes('oas3_0'), {});
+  const source = new Source('test.yaml', JSON.stringify(doc));
+  const document: Document = { source, parsed: doc };
+  const externalRefResolver = new BaseResolver();
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+  const ctx: WalkContext = {
+    problems: [],
+    specVersion: 'oas3_0',
+    visitorsData: {},
+  };
+
+  const schemaWalkState = createSchemaWalkState();
+  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
+  const normalizedSchemaVis = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'test-schema', visitor: schemaVisitor }],
+    types
+  );
+
+  const walkSchema = (schemaNode: any) => {
+    resetSchemaWalkState(schemaWalkState);
+    walkDocument({
+      document: { ...document, parsed: schemaNode },
+      rootType: types.Schema,
+      normalizedVisitors: normalizedSchemaVis,
+      resolvedRefMap,
+      ctx,
+    });
+    return {
+      maxDepth: schemaWalkState.maxDepth,
+      polymorphismCount: schemaWalkState.polymorphismCount,
+      anyOfCount: schemaWalkState.anyOfCount,
+      hasDiscriminator: schemaWalkState.hasDiscriminator,
+      propertyCount: schemaWalkState.propertyCount,
+      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
+      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
+      constraintCount: schemaWalkState.constraintCount,
+      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
+      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
+      refsUsed: [...schemaWalkState.refsUsed],
+    };
+  };
+
+  const accumulator = createScoreAccumulator(walkSchema);
+  const visitor = createScoreVisitor(accumulator);
+  const normalizedVis = normalizeVisitors([{ severity: 'warn', ruleId: 'test', visitor }], types);
+  walkDocument({
+    document,
+    rootType: types.Root,
+    normalizedVisitors: normalizedVis,
+    resolvedRefMap,
+    ctx,
+  });
+  return getDocumentMetrics(accumulator);
 }
 
 describe('collectDocumentMetrics', () => {
diff --git a/packages/cli/src/commands/score/__tests__/formatters.test.ts b/packages/cli/src/commands/score/__tests__/formatters.test.ts
index c9b35da1f6..5762eb1c40 100644
--- a/packages/cli/src/commands/score/__tests__/formatters.test.ts
+++ b/packages/cli/src/commands/score/__tests__/formatters.test.ts
@@ -107,7 +107,7 @@ const RESULT: ScoreResult = {
   workflowDepths: new Map(),
 };
 
-function getStylishOutput(result: ScoreResult = RESULT): string {
+function getStylishOutput(result: ScoreResult): string {
   mockOutput.mockClear();
   printScoreStylish(result);
   return mockOutput.mock.calls.map(([s]: [string]) => s).join('');
@@ -115,7 +115,7 @@ function getStylishOutput(result: ScoreResult = RESULT): string {
 
 describe('printScoreStylish', () => {
   it('outputs scores, subscores, metrics, and hotspots', () => {
-    const output = getStylishOutput();
+    const output = getStylishOutput(RESULT);
     expect(output).toContain('Integration Simplicity');
     expect(output).toContain('Agent Readiness');
     expect(output).toContain('Parameter Simplicity');
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index 0186dd30bc..ec55ae0b9e 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -159,12 +159,7 @@ describe('handleScore', () => {
   it('should reject non-oas3 documents', async () => {
     mockedDetectSpec.mockReturnValue('oas2');
 
-    await handleScore(createArgs());
-
-    expect(process.exitCode).toBe(1);
-    expect(mockError).toHaveBeenCalled();
-    const errorMsg = mockError.mock.calls[0][0];
-    expect(errorMsg).toContain('OpenAPI 3.x');
+    await expect(handleScore(createArgs())).rejects.toThrow('OpenAPI 3.x');
   });
 
   it('should call collectSpecData', async () => {
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
index 9a7719f63b..2b020086ed 100644
--- a/packages/cli/src/commands/score/collectors/document-metrics.ts
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -59,7 +59,8 @@ export interface SchemaWalkState {
 
 export function createSchemaWalkState(): SchemaWalkState {
   return {
-    depth: -1,
+    depth: -1, // starts at -1 because the root Schema.enter increments to 0
+
     maxDepth: 0,
     polymorphismCount: 0,
     anyOfCount: 0,
@@ -77,7 +78,8 @@ export function createSchemaWalkState(): SchemaWalkState {
 }
 
 export function resetSchemaWalkState(s: SchemaWalkState): void {
-  s.depth = -1;
+  s.depth = -1; // starts at -1 because the root Schema.enter increments to 0
+
   s.maxDepth = 0;
   s.polymorphismCount = 0;
   s.anyOfCount = 0;
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
index 25d5458065..1575570ce5 100644
--- a/packages/cli/src/commands/score/index.ts
+++ b/packages/cli/src/commands/score/index.ts
@@ -3,6 +3,7 @@ import {
   BaseResolver,
   resolveDocument,
   detectSpec,
+  getMajorSpecVersion,
   getTypes,
   normalizeVisitors,
   walkDocument,
@@ -15,6 +16,7 @@ import * as colors from 'colorette';
 import { performance } from 'perf_hooks';
 
 import type { VerifyConfigOptions } from '../../types.js';
+import { exitWithError } from '../../utils/error.js';
 import { getFallbackApisOrExit, printExecutionTime } from '../../utils/miscellaneous.js';
 import type { CommandArgs } from '../../wrapper.js';
 import {
@@ -60,12 +62,10 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
   collectSpecData?.(document.parsed);
 
   const specVersion = detectSpec(document.parsed);
-  if (!specVersion.startsWith('oas3')) {
-    logger.error(
-      colors.red(`The score command currently supports only OpenAPI 3.x. Detected: ${specVersion}`)
+  if (getMajorSpecVersion(specVersion) !== 'oas3') {
+    return exitWithError(
+      `The score command currently supports only OpenAPI 3.x. Detected: ${specVersion}`
     );
-    process.exitCode = 1;
-    return;
   }
 
   const startedAt = performance.now();
@@ -241,6 +241,7 @@ function printScore(
     case 'json':
       printScoreJson(result);
       break;
+    case 'stylish':
     default:
       printScoreStylish(result, operationDetails);
       break;
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 2b86faaa01..b7083155f0 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -90,7 +90,7 @@ yargs(hideBin(process.argv))
           },
           format: {
             description: 'Use a specific output format.',
-            choices: ['stylish', 'json', 'markdown'] as ReadonlyArray<OutputFormat>,
+            choices: ['stylish', 'json'] as ReadonlyArray<OutputFormat>,
             default: 'stylish' as OutputFormat,
           },
           'operation-details': {

From 126f5e018bc0a7056bd3c8301f0ef8bb628d14ac Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Tue, 24 Mar 2026 07:08:22 -0500
Subject: [PATCH 11/22] fix: resolve CI typecheck failures

- Add type cast for parseYaml (returns unknown) in document-metrics tests
- Inline collectDocumentMetrics helper into example-coverage tests
- Remove collect-metrics.js import from scoring tests, use direct metrics
- Add missing debugLogs property to accumulator mock in index tests

Made-with: Cursor
---
 .../score/__tests__/document-metrics.test.ts  |   4 +-
 .../score/__tests__/example-coverage.test.ts  |  75 +++++++++++-
 .../commands/score/__tests__/index.test.ts    |   1 +
 .../commands/score/__tests__/scoring.test.ts  | 110 +++++++-----------
 4 files changed, 118 insertions(+), 72 deletions(-)

diff --git a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
index 2f8c00d552..a5d53635af 100644
--- a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
+++ b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
@@ -6,12 +6,14 @@ import {
   resolveDocument,
   BaseResolver,
   Source,
-  parseYaml as yaml,
+  parseYaml,
   type Document,
   type WalkContext,
 } from '@redocly/openapi-core';
 import { outdent } from 'outdent';
 
+const yaml = (source: string) => parseYaml(source) as Record<string, unknown>;
+
 import {
   createScoreAccumulator,
   createScoreVisitor,
diff --git a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
index 71bdf1d22d..3e6150e3ef 100644
--- a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
+++ b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
@@ -1,10 +1,83 @@
+import {
+  normalizeTypes,
+  getTypes,
+  normalizeVisitors,
+  walkDocument,
+  resolveDocument,
+  BaseResolver,
+  Source,
+  type Document,
+  type WalkContext,
+} from '@redocly/openapi-core';
+
+import {
+  createScoreAccumulator,
+  createScoreVisitor,
+  createSchemaWalkState,
+  resetSchemaWalkState,
+  createSchemaMetricVisitor,
+  getDocumentMetrics,
+} from '../collectors/document-metrics.js';
 import {
   computeOperationIntegrationSubscores,
   computeOperationAgentSubscores,
   computeIntegrationSimplicity,
   computeAgentReadiness,
 } from '../scoring.js';
-import { collectDocumentMetrics } from './collect-metrics.js';
+import type { DocumentMetrics } from '../types.js';
+
+async function collectDocumentMetrics(doc: Record<string, unknown>): Promise<DocumentMetrics> {
+  const types = normalizeTypes(getTypes('oas3_0'), {});
+  const source = new Source('test.yaml', JSON.stringify(doc));
+  const document: Document = { source, parsed: doc };
+  const externalRefResolver = new BaseResolver();
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+  const ctx: WalkContext = { problems: [], specVersion: 'oas3_0', visitorsData: {} };
+  const schemaWalkState = createSchemaWalkState();
+  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
+  const normalizedSchemaVis = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'test-schema', visitor: schemaVisitor }],
+    types
+  );
+  const walkSchema = (schemaNode: any) => {
+    resetSchemaWalkState(schemaWalkState);
+    walkDocument({
+      document: { ...document, parsed: schemaNode },
+      rootType: types.Schema,
+      normalizedVisitors: normalizedSchemaVis,
+      resolvedRefMap,
+      ctx,
+    });
+    return {
+      maxDepth: schemaWalkState.maxDepth,
+      polymorphismCount: schemaWalkState.polymorphismCount,
+      anyOfCount: schemaWalkState.anyOfCount,
+      hasDiscriminator: schemaWalkState.hasDiscriminator,
+      propertyCount: schemaWalkState.propertyCount,
+      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
+      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
+      constraintCount: schemaWalkState.constraintCount,
+      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
+      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
+      refsUsed: [...schemaWalkState.refsUsed],
+    };
+  };
+  const accumulator = createScoreAccumulator(walkSchema);
+  const visitor = createScoreVisitor(accumulator);
+  const normalizedVis = normalizeVisitors([{ severity: 'warn', ruleId: 'test', visitor }], types);
+  walkDocument({
+    document,
+    rootType: types.Root,
+    normalizedVisitors: normalizedVis,
+    resolvedRefMap,
+    ctx,
+  });
+  return getDocumentMetrics(accumulator);
+}
 
 describe('example coverage', () => {
   function makeDocument(overrides: {
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index ec55ae0b9e..93fc0f32e5 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -108,6 +108,7 @@ function makeAccumulator(ops: Map<string, OperationMetrics> = new Map()): ScoreA
       writableTopLevelFields: 0,
       refsUsed: [],
     }),
+    debugLogs: [],
   };
 }
 
diff --git a/packages/cli/src/commands/score/__tests__/scoring.test.ts b/packages/cli/src/commands/score/__tests__/scoring.test.ts
index acbfb8583c..d86dde18be 100644
--- a/packages/cli/src/commands/score/__tests__/scoring.test.ts
+++ b/packages/cli/src/commands/score/__tests__/scoring.test.ts
@@ -8,7 +8,6 @@ import {
   computeDocumentScores,
 } from '../scoring.js';
 import type { OperationMetrics, ScoringConstants } from '../types.js';
-import { collectDocumentMetrics } from './collect-metrics.js';
 
 function makeBaseMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetrics {
   return {
@@ -121,80 +120,51 @@ describe('scoring', () => {
   });
 
   describe('determinism', () => {
-    it('should produce identical scores for the same input', async () => {
-      const doc = {
-        openapi: '3.0.0',
-        info: { title: 'Test', version: '1.0.0' },
-        paths: {
-          '/a': {
-            get: {
+    it('should produce identical scores for the same input', () => {
+      const metrics = {
+        operationCount: 2,
+        operations: new Map([
+          [
+            'getA',
+            makeBaseMetrics({
+              path: '/a',
+              method: 'get',
               operationId: 'getA',
-              description: 'Get A',
-              parameters: [{ name: 'id', in: 'query', required: true, schema: { type: 'string' } }],
-              responses: {
-                '200': {
-                  description: 'OK',
-                  content: {
-                    'application/json': {
-                      schema: { type: 'object', properties: { name: { type: 'string' } } },
-                    },
-                  },
-                },
-              },
-            },
-          },
-          '/b': {
-            post: {
+              parameterCount: 1,
+              requiredParameterCount: 1,
+              paramsWithDescription: 0,
+              propertyCount: 1,
+              totalSchemaProperties: 1,
+              maxResponseSchemaDepth: 1,
+            }),
+          ],
+          [
+            'createB',
+            makeBaseMetrics({
+              path: '/b',
+              method: 'post',
               operationId: 'createB',
-              description: 'Create B',
-              requestBody: {
-                content: {
-                  'application/json': {
-                    schema: {
-                      type: 'object',
-                      properties: {
-                        value: { type: 'string', minLength: 1 },
-                      },
-                    },
-                    example: { value: 'test' },
-                  },
-                },
-              },
-              responses: {
-                '201': {
-                  description: 'Created',
-                  content: {
-                    'application/json': {
-                      schema: { type: 'object', properties: { id: { type: 'string' } } },
-                      example: { id: '1' },
-                    },
-                  },
-                },
-                '400': {
-                  description: 'Bad Request',
-                  content: {
-                    'application/json': {
-                      schema: {
-                        type: 'object',
-                        properties: { message: { type: 'string' } },
-                      },
-                    },
-                  },
-                },
-              },
-            },
-          },
-        },
+              requestBodyPresent: true,
+              requestExamplePresent: true,
+              constraintCount: 1,
+              propertyCount: 2,
+              totalSchemaProperties: 2,
+              maxRequestSchemaDepth: 1,
+              maxResponseSchemaDepth: 1,
+              structuredErrorResponseCount: 1,
+              totalErrorResponses: 1,
+            }),
+          ],
+        ]),
       };
 
-      const metrics1 = await collectDocumentMetrics(doc);
-      const metrics2 = await collectDocumentMetrics(doc);
-
-      const depths1 = new Map(Array.from(metrics1.operations.keys()).map((k) => [k, 0]));
-      const depths2 = new Map(Array.from(metrics2.operations.keys()).map((k) => [k, 0]));
+      const depths = new Map<string, number>([
+        ['getA', 0],
+        ['createB', 0],
+      ]);
 
-      const scores1 = computeAllOperationScores(metrics1, depths1);
-      const scores2 = computeAllOperationScores(metrics2, depths2);
+      const scores1 = computeAllOperationScores(metrics, depths);
+      const scores2 = computeAllOperationScores(metrics, depths);
 
       const doc1 = computeDocumentScores(scores1);
       const doc2 = computeDocumentScores(scores2);

From 8439a762c4858088aad0883e62ad521260fd939c Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Tue, 24 Mar 2026 07:42:27 -0500
Subject: [PATCH 12/22] refactor: extract collectMetrics and add schema
 memoization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extract the metric-collection pipeline from handleScore into a
standalone collect-metrics.ts module with two exports:
- collectMetrics(): low-level function used by handleScore
- collectDocumentMetrics(): high-level convenience used by tests

This eliminates ~300 lines of duplicated walker setup across three
test files (document-metrics, example-coverage, index) and ensures
tests exercise the same code path as the production command.

Add $ref-keyed memoization to walkSchema so repeated references to
the same component schema return cached stats instead of re-walking.
Stripe API: 37.6s → 11.3s (3.3× faster).

Made-with: Cursor
---
 .../score/__tests__/document-metrics.test.ts  |  97 +-------
 .../score/__tests__/example-coverage.test.ts  |  95 +-------
 .../commands/score/__tests__/index.test.ts    |  94 +++----
 .../cli/src/commands/score/collect-metrics.ts | 229 ++++++++++++++++++
 packages/cli/src/commands/score/index.ts      | 144 +----------
 5 files changed, 284 insertions(+), 375 deletions(-)
 create mode 100644 packages/cli/src/commands/score/collect-metrics.ts

diff --git a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
index a5d53635af..c26d81a0e5 100644
--- a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
+++ b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
@@ -1,92 +1,17 @@
-import {
-  normalizeTypes,
-  getTypes,
-  normalizeVisitors,
-  walkDocument,
-  resolveDocument,
-  BaseResolver,
-  Source,
-  parseYaml,
-  type Document,
-  type WalkContext,
-} from '@redocly/openapi-core';
+import { parseYaml } from '@redocly/openapi-core';
 import { outdent } from 'outdent';
 
-const yaml = (source: string) => parseYaml(source) as Record<string, unknown>;
-
-import {
-  createScoreAccumulator,
-  createScoreVisitor,
-  createSchemaWalkState,
-  resetSchemaWalkState,
-  createSchemaMetricVisitor,
-  getDocumentMetrics,
-} from '../collectors/document-metrics.js';
-import type { DocumentMetrics } from '../types.js';
-
-async function collectDocumentMetrics(doc: Record<string, unknown>): Promise<DocumentMetrics> {
-  const types = normalizeTypes(getTypes('oas3_0'), {});
-  const source = new Source('test.yaml', JSON.stringify(doc));
-  const document: Document = { source, parsed: doc };
-  const externalRefResolver = new BaseResolver();
-  const resolvedRefMap = await resolveDocument({
-    rootDocument: document,
-    rootType: types.Root,
-    externalRefResolver,
-  });
-  const ctx: WalkContext = {
-    problems: [],
-    specVersion: 'oas3_0',
-    visitorsData: {},
-  };
+import { collectDocumentMetrics } from '../collect-metrics.js';
 
-  const schemaWalkState = createSchemaWalkState();
-  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
-  const normalizedSchemaVis = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'test-schema', visitor: schemaVisitor }],
-    types
-  );
-
-  const walkSchema = (schemaNode: any) => {
-    resetSchemaWalkState(schemaWalkState);
-    walkDocument({
-      document: { ...document, parsed: schemaNode },
-      rootType: types.Schema,
-      normalizedVisitors: normalizedSchemaVis,
-      resolvedRefMap,
-      ctx,
-    });
-    return {
-      maxDepth: schemaWalkState.maxDepth,
-      polymorphismCount: schemaWalkState.polymorphismCount,
-      anyOfCount: schemaWalkState.anyOfCount,
-      hasDiscriminator: schemaWalkState.hasDiscriminator,
-      propertyCount: schemaWalkState.propertyCount,
-      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
-      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
-      constraintCount: schemaWalkState.constraintCount,
-      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
-      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
-      refsUsed: [...schemaWalkState.refsUsed],
-    };
-  };
+const yaml = (source: string) => parseYaml(source) as Record<string, unknown>;
 
-  const accumulator = createScoreAccumulator(walkSchema);
-  const visitor = createScoreVisitor(accumulator);
-  const normalizedVis = normalizeVisitors([{ severity: 'warn', ruleId: 'test', visitor }], types);
-  walkDocument({
-    document,
-    rootType: types.Root,
-    normalizedVisitors: normalizedVis,
-    resolvedRefMap,
-    ctx,
-  });
-  return getDocumentMetrics(accumulator);
+async function collect(doc: Record<string, unknown>) {
+  return (await collectDocumentMetrics(doc)).metrics;
 }
 
 describe('collectDocumentMetrics', () => {
   it('returns zero operations for empty paths', async () => {
-    const result = await collectDocumentMetrics(
+    const result = await collect(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -100,7 +25,7 @@ describe('collectDocumentMetrics', () => {
   });
 
   it('counts operations, uses operationId as key or falls back to METHOD /path', async () => {
-    const result = await collectDocumentMetrics(
+    const result = await collect(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -132,7 +57,7 @@ describe('collectDocumentMetrics', () => {
   });
 
   it('counts parameters, resolves $refs, merges path-level params, and detects ambiguous names', async () => {
-    const result = await collectDocumentMetrics(
+    const result = await collect(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -171,7 +96,7 @@ describe('collectDocumentMetrics', () => {
   });
 
   it('detects request body with $ref schema, examples, constraints, and property descriptions', async () => {
-    const result = await collectDocumentMetrics(
+    const result = await collect(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -216,7 +141,7 @@ describe('collectDocumentMetrics', () => {
   });
 
   it('resolves response $refs, counts structured errors, and computes schema depth', async () => {
-    const result = await collectDocumentMetrics(
+    const result = await collect(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -269,7 +194,7 @@ describe('collectDocumentMetrics', () => {
   });
 
   it('detects operation descriptions and tracks shared $ref usage across operations', async () => {
-    const result = await collectDocumentMetrics(
+    const result = await collect(
       yaml(outdent`
         openapi: 3.0.0
         info:
diff --git a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
index 3e6150e3ef..9483041ae5 100644
--- a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
+++ b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
@@ -1,82 +1,13 @@
-import {
-  normalizeTypes,
-  getTypes,
-  normalizeVisitors,
-  walkDocument,
-  resolveDocument,
-  BaseResolver,
-  Source,
-  type Document,
-  type WalkContext,
-} from '@redocly/openapi-core';
-
-import {
-  createScoreAccumulator,
-  createScoreVisitor,
-  createSchemaWalkState,
-  resetSchemaWalkState,
-  createSchemaMetricVisitor,
-  getDocumentMetrics,
-} from '../collectors/document-metrics.js';
+import { collectDocumentMetrics } from '../collect-metrics.js';
 import {
   computeOperationIntegrationSubscores,
   computeOperationAgentSubscores,
   computeIntegrationSimplicity,
   computeAgentReadiness,
 } from '../scoring.js';
-import type { DocumentMetrics } from '../types.js';
 
-async function collectDocumentMetrics(doc: Record<string, unknown>): Promise<DocumentMetrics> {
-  const types = normalizeTypes(getTypes('oas3_0'), {});
-  const source = new Source('test.yaml', JSON.stringify(doc));
-  const document: Document = { source, parsed: doc };
-  const externalRefResolver = new BaseResolver();
-  const resolvedRefMap = await resolveDocument({
-    rootDocument: document,
-    rootType: types.Root,
-    externalRefResolver,
-  });
-  const ctx: WalkContext = { problems: [], specVersion: 'oas3_0', visitorsData: {} };
-  const schemaWalkState = createSchemaWalkState();
-  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
-  const normalizedSchemaVis = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'test-schema', visitor: schemaVisitor }],
-    types
-  );
-  const walkSchema = (schemaNode: any) => {
-    resetSchemaWalkState(schemaWalkState);
-    walkDocument({
-      document: { ...document, parsed: schemaNode },
-      rootType: types.Schema,
-      normalizedVisitors: normalizedSchemaVis,
-      resolvedRefMap,
-      ctx,
-    });
-    return {
-      maxDepth: schemaWalkState.maxDepth,
-      polymorphismCount: schemaWalkState.polymorphismCount,
-      anyOfCount: schemaWalkState.anyOfCount,
-      hasDiscriminator: schemaWalkState.hasDiscriminator,
-      propertyCount: schemaWalkState.propertyCount,
-      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
-      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
-      constraintCount: schemaWalkState.constraintCount,
-      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
-      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
-      refsUsed: [...schemaWalkState.refsUsed],
-    };
-  };
-  const accumulator = createScoreAccumulator(walkSchema);
-  const visitor = createScoreVisitor(accumulator);
-  const normalizedVis = normalizeVisitors([{ severity: 'warn', ruleId: 'test', visitor }], types);
-  walkDocument({
-    document,
-    rootType: types.Root,
-    normalizedVisitors: normalizedVis,
-    resolvedRefMap,
-    ctx,
-  });
-  return getDocumentMetrics(accumulator);
+async function collect(doc: Record<string, unknown>) {
+  return (await collectDocumentMetrics(doc)).metrics;
 }
 
 describe('example coverage', () => {
@@ -125,7 +56,7 @@ describe('example coverage', () => {
 
   it('should give perfect example coverage when both request and response examples present', async () => {
     const doc = makeDocument({ requestExample: true, responseExample: true, hasRequestBody: true });
-    const metrics = await collectDocumentMetrics(doc);
+    const metrics = await collect(doc);
     const opMetrics = metrics.operations.get('createItem')!;
 
     expect(opMetrics.requestExamplePresent).toBe(true);
@@ -141,7 +72,7 @@ describe('example coverage', () => {
       responseExample: true,
       hasRequestBody: true,
     });
-    const metrics = await collectDocumentMetrics(doc);
+    const metrics = await collect(doc);
     const opMetrics = metrics.operations.get('createItem')!;
 
     expect(opMetrics.requestExamplePresent).toBe(false);
@@ -157,7 +88,7 @@ describe('example coverage', () => {
       responseExample: false,
       hasRequestBody: true,
     });
-    const metrics = await collectDocumentMetrics(doc);
+    const metrics = await collect(doc);
     const opMetrics = metrics.operations.get('createItem')!;
 
     const subscores = computeOperationIntegrationSubscores(opMetrics, 0);
@@ -176,10 +107,8 @@ describe('example coverage', () => {
       hasRequestBody: true,
     });
 
-    const metricsWithExamples = (await collectDocumentMetrics(docWith)).operations.get(
-      'createItem'
-    )!;
-    const metricsWithout = (await collectDocumentMetrics(docWithout)).operations.get('createItem')!;
+    const metricsWithExamples = (await collect(docWith)).operations.get('createItem')!;
+    const metricsWithout = (await collect(docWithout)).operations.get('createItem')!;
 
     const subWith = computeOperationIntegrationSubscores(metricsWithExamples, 0);
     const subWithout = computeOperationIntegrationSubscores(metricsWithout, 0);
@@ -202,10 +131,8 @@ describe('example coverage', () => {
       hasRequestBody: true,
     });
 
-    const metricsWithExamples = (await collectDocumentMetrics(docWith)).operations.get(
-      'createItem'
-    )!;
-    const metricsWithout = (await collectDocumentMetrics(docWithout)).operations.get('createItem')!;
+    const metricsWithExamples = (await collect(docWith)).operations.get('createItem')!;
+    const metricsWithout = (await collect(docWithout)).operations.get('createItem')!;
 
     const subWith = computeOperationAgentSubscores(metricsWithExamples, 0);
     const subWithout = computeOperationAgentSubscores(metricsWithout, 0);
@@ -252,7 +179,7 @@ describe('example coverage', () => {
       },
     };
 
-    const metrics = await collectDocumentMetrics(doc);
+    const metrics = await collect(doc);
     const opMetrics = metrics.operations.get('createItem')!;
     expect(opMetrics.requestExamplePresent).toBe(true);
     expect(opMetrics.responseExamplePresent).toBe(true);
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index 93fc0f32e5..caedb344ad 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -8,8 +8,6 @@ vi.mock('@redocly/openapi-core', async (importOriginal) => {
     resolveDocument: vi.fn(),
     normalizeTypes: vi.fn(),
     getTypes: vi.fn(),
-    normalizeVisitors: vi.fn(),
-    walkDocument: vi.fn(),
     logger: { output: vi.fn(), info: vi.fn(), error: vi.fn() },
   };
 });
@@ -19,45 +17,24 @@ vi.mock('../../../utils/miscellaneous.js', () => ({
   printExecutionTime: vi.fn(),
 }));
 
-vi.mock('../collectors/document-metrics.js', async (importOriginal) => {
-  const actual = (await importOriginal()) as any;
-  return {
-    ...actual,
-    createScoreAccumulator: vi.fn(),
-    createScoreVisitor: vi.fn(),
-  };
-});
+vi.mock('../collect-metrics.js', () => ({
+  collectMetrics: vi.fn(),
+}));
 
-import {
-  bundle,
-  detectSpec,
-  logger,
-  normalizeTypes,
-  resolveDocument,
-  normalizeVisitors,
-  walkDocument,
-} from '@redocly/openapi-core';
+import { bundle, detectSpec, logger, normalizeTypes, resolveDocument } from '@redocly/openapi-core';
 
 import { getFallbackApisOrExit } from '../../../utils/miscellaneous.js';
-import {
-  createScoreAccumulator,
-  createScoreVisitor,
-  type ScoreAccumulator,
-} from '../collectors/document-metrics.js';
+import { collectMetrics } from '../collect-metrics.js';
 import { handleScore, type ScoreArgv } from '../index.js';
-import type { OperationMetrics } from '../types.js';
+import type { DocumentMetrics, OperationMetrics } from '../types.js';
 
 const mockedBundle = vi.mocked(bundle);
 const mockedDetectSpec = vi.mocked(detectSpec);
 const mockedGetFallback = vi.mocked(getFallbackApisOrExit);
 const mockOutput = vi.mocked(logger.output);
-const mockError = vi.mocked(logger.error);
-const mockedCreateAccumulator = vi.mocked(createScoreAccumulator);
-const mockedCreateVisitor = vi.mocked(createScoreVisitor);
+const mockedCollectMetrics = vi.mocked(collectMetrics);
 const mockedNormalizeTypes = vi.mocked(normalizeTypes);
 const mockedResolveDocument = vi.mocked(resolveDocument);
-const mockedNormalizeVisitors = vi.mocked(normalizeVisitors);
-const mockedWalkDocument = vi.mocked(walkDocument);
 
 function makeTestMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetrics {
   return {
@@ -89,27 +66,8 @@ function makeTestMetrics(overrides: Partial<OperationMetrics> = {}): OperationMe
   };
 }
 
-function makeAccumulator(ops: Map<string, OperationMetrics> = new Map()): ScoreAccumulator {
-  return {
-    operations: ops,
-    currentPath: '',
-    pathLevelParams: [],
-    current: null,
-    walkSchema: () => ({
-      maxDepth: 0,
-      polymorphismCount: 0,
-      anyOfCount: 0,
-      hasDiscriminator: false,
-      propertyCount: 0,
-      totalSchemaProperties: 0,
-      schemaPropertiesWithDescription: 0,
-      constraintCount: 0,
-      hasPropertyExamples: false,
-      writableTopLevelFields: 0,
-      refsUsed: [],
-    }),
-    debugLogs: [],
-  };
+function makeDocumentMetrics(ops: Map<string, OperationMetrics> = new Map()): DocumentMetrics {
+  return { operationCount: ops.size, operations: ops };
 }
 
 function createArgs(overrides: Partial<ScoreArgv> = {}) {
@@ -124,18 +82,15 @@ function createArgs(overrides: Partial<ScoreArgv> = {}) {
 describe('handleScore', () => {
   beforeEach(() => {
     mockOutput.mockClear();
-    mockError.mockClear();
     mockedGetFallback.mockResolvedValue([{ path: 'test.yaml' }] as any);
     mockedBundle.mockResolvedValue({ bundle: { parsed: {} } } as any);
     mockedDetectSpec.mockReturnValue('oas3_0');
     mockedNormalizeTypes.mockReturnValue({ Root: {} } as any);
     mockedResolveDocument.mockResolvedValue(new Map() as any);
-    mockedNormalizeVisitors.mockReturnValue([] as any);
-    mockedWalkDocument.mockImplementation(() => {});
-    mockedCreateVisitor.mockReturnValue({} as any);
-    mockedCreateAccumulator.mockReturnValue(
-      makeAccumulator(new Map([['listItems', makeTestMetrics()]]))
-    );
+    mockedCollectMetrics.mockReturnValue({
+      metrics: makeDocumentMetrics(new Map([['listItems', makeTestMetrics()]])),
+      debugLogs: [],
+    });
     process.exitCode = undefined;
   });
 
@@ -175,7 +130,10 @@ describe('handleScore', () => {
   });
 
   it('should handle document with no operations', async () => {
-    mockedCreateAccumulator.mockReturnValue(makeAccumulator());
+    mockedCollectMetrics.mockReturnValue({
+      metrics: makeDocumentMetrics(),
+      debugLogs: [],
+    });
 
     await handleScore(createArgs());
 
@@ -184,8 +142,8 @@ describe('handleScore', () => {
   });
 
   it('should handle document with multiple operations', async () => {
-    mockedCreateAccumulator.mockReturnValue(
-      makeAccumulator(
+    mockedCollectMetrics.mockReturnValue({
+      metrics: makeDocumentMetrics(
         new Map([
           ['listItems', makeTestMetrics()],
           [
@@ -199,8 +157,9 @@ describe('handleScore', () => {
             }),
           ],
         ])
-      )
-    );
+      ),
+      debugLogs: [],
+    });
 
     await handleScore(createArgs({ format: 'json' }));
 
@@ -211,8 +170,8 @@ describe('handleScore', () => {
   });
 
   it('should include hotspots in output', async () => {
-    mockedCreateAccumulator.mockReturnValue(
-      makeAccumulator(
+    mockedCollectMetrics.mockReturnValue({
+      metrics: makeDocumentMetrics(
         new Map([
           [
             'complexOp',
@@ -226,8 +185,9 @@ describe('handleScore', () => {
             }),
           ],
         ])
-      )
-    );
+      ),
+      debugLogs: [],
+    });
 
     await handleScore(createArgs());
 
diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
new file mode 100644
index 0000000000..0079bcde59
--- /dev/null
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -0,0 +1,229 @@
+import {
+  normalizeTypes,
+  getTypes,
+  normalizeVisitors,
+  walkDocument,
+  resolveDocument,
+  BaseResolver,
+  Source,
+  type Document,
+  type SpecVersion,
+  type WalkContext,
+} from '@redocly/openapi-core';
+
+import {
+  createScoreAccumulator,
+  createScoreVisitor,
+  createSchemaWalkState,
+  resetSchemaWalkState,
+  createSchemaMetricVisitor,
+  getDocumentMetrics,
+} from './collectors/document-metrics.js';
+import type { DebugMediaTypeLog, DocumentMetrics } from './types.js';
+
+function resolveJsonPointer(root: any, ref: string): any {
+  if (!ref.startsWith('#/')) return undefined;
+  let node = root;
+  for (const segment of ref.slice(2).split('/')) {
+    node = node?.[decodeURIComponent(segment)];
+  }
+  return node;
+}
+
+interface SchemaStats {
+  maxDepth: number;
+  polymorphismCount: number;
+  anyOfCount: number;
+  hasDiscriminator: boolean;
+  propertyCount: number;
+  totalSchemaProperties: number;
+  schemaPropertiesWithDescription: number;
+  constraintCount: number;
+  hasPropertyExamples: boolean;
+  writableTopLevelFields: number;
+  refsUsed: string[];
+  debugEntries?: import('./types.js').DebugSchemaEntry[];
+}
+
+function combineOneOfStats(
+  parent: SchemaStats,
+  branch: SchemaStats,
+  branchCount: number,
+  keyword: 'oneOf' | 'anyOf'
+): SchemaStats {
+  return {
+    maxDepth: Math.max(parent.maxDepth, branch.maxDepth + 1),
+    polymorphismCount: parent.polymorphismCount + branch.polymorphismCount + branchCount,
+    anyOfCount: parent.anyOfCount + branch.anyOfCount + (keyword === 'anyOf' ? branchCount : 0),
+    hasDiscriminator: parent.hasDiscriminator || branch.hasDiscriminator,
+    propertyCount: parent.propertyCount + branch.propertyCount,
+    totalSchemaProperties: parent.totalSchemaProperties + branch.totalSchemaProperties,
+    schemaPropertiesWithDescription:
+      parent.schemaPropertiesWithDescription + branch.schemaPropertiesWithDescription,
+    constraintCount: parent.constraintCount + branch.constraintCount,
+    hasPropertyExamples: parent.hasPropertyExamples || branch.hasPropertyExamples,
+    writableTopLevelFields: parent.writableTopLevelFields + branch.writableTopLevelFields,
+    refsUsed: [...parent.refsUsed, ...branch.refsUsed],
+    debugEntries:
+      parent.debugEntries || branch.debugEntries
+        ? [...(parent.debugEntries ?? []), ...(branch.debugEntries ?? [])]
+        : undefined,
+  };
+}
+
+export interface CollectMetricsOptions {
+  document: Document;
+  types: ReturnType<typeof normalizeTypes>;
+  resolvedRefMap: ReturnType<typeof resolveDocument> extends Promise<infer R> ? R : never;
+  ctx: WalkContext;
+  debugOperationId?: string;
+}
+
+export interface CollectMetricsResult {
+  metrics: DocumentMetrics;
+  debugLogs: DebugMediaTypeLog[];
+}
+
+export function collectMetrics({
+  document,
+  types,
+  resolvedRefMap,
+  ctx,
+  debugOperationId,
+}: CollectMetricsOptions): CollectMetricsResult {
+  const schemaWalkState = createSchemaWalkState();
+  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
+  const normalizedSchemaVisitors = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor as any }],
+    types
+  );
+
+  const walkSchemaRaw = (schemaNode: any, debug: boolean): SchemaStats => {
+    resetSchemaWalkState(schemaWalkState);
+    if (debug) schemaWalkState.debugEntries = [];
+    walkDocument({
+      document: { ...document, parsed: schemaNode },
+      rootType: types.Schema,
+      normalizedVisitors: normalizedSchemaVisitors,
+      resolvedRefMap,
+      ctx,
+    });
+    return {
+      maxDepth: schemaWalkState.maxDepth,
+      polymorphismCount: schemaWalkState.polymorphismCount,
+      anyOfCount: schemaWalkState.anyOfCount,
+      hasDiscriminator: schemaWalkState.hasDiscriminator,
+      propertyCount: schemaWalkState.propertyCount,
+      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
+      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
+      constraintCount: schemaWalkState.constraintCount,
+      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
+      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
+      refsUsed: [...schemaWalkState.refsUsed],
+      debugEntries: debug ? (schemaWalkState.debugEntries ?? undefined) : undefined,
+    };
+  };
+
+  const schemaCache = new Map<string, SchemaStats>();
+
+  const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
+    let resolved = schemaNode;
+    const ref: string | undefined =
+      schemaNode?.$ref && typeof schemaNode.$ref === 'string' ? schemaNode.$ref : undefined;
+
+    if (ref) {
+      if (!debug) {
+        const cached = schemaCache.get(ref);
+        if (cached) return cached;
+      }
+      resolved = resolveJsonPointer(document.parsed, ref) ?? schemaNode;
+    }
+
+    const polyKeyword: 'oneOf' | 'anyOf' | null =
+      Array.isArray(resolved?.oneOf) && resolved.oneOf.length > 1
+        ? 'oneOf'
+        : Array.isArray(resolved?.anyOf) && resolved.anyOf.length > 1
+          ? 'anyOf'
+          : null;
+
+    let result: SchemaStats;
+
+    if (polyKeyword && !resolved.allOf) {
+      const branches = resolved[polyKeyword] as any[];
+
+      const parentOnly = { ...resolved };
+      delete parentOnly[polyKeyword];
+      delete parentOnly.discriminator;
+
+      let maxBranch = walkSchema(branches[0], debug);
+      for (let i = 1; i < branches.length; i++) {
+        const branchStats = walkSchema(branches[i], debug);
+        if (branchStats.propertyCount > maxBranch.propertyCount) {
+          maxBranch = branchStats;
+        }
+      }
+
+      const parentStats = walkSchemaRaw(parentOnly, debug);
+
+      result = combineOneOfStats(parentStats, maxBranch, branches.length, polyKeyword);
+    } else {
+      result = walkSchemaRaw(schemaNode, debug);
+    }
+
+    if (ref && !debug) {
+      schemaCache.set(ref, result);
+    }
+
+    return result;
+  };
+
+  const accumulator = createScoreAccumulator(walkSchema, debugOperationId);
+  const scoreVisitor = createScoreVisitor(accumulator);
+
+  const normalizedVisitors = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
+    types
+  );
+
+  walkDocument({
+    document,
+    rootType: types.Root,
+    normalizedVisitors,
+    resolvedRefMap,
+    ctx,
+  });
+
+  return {
+    metrics: getDocumentMetrics(accumulator),
+    debugLogs: accumulator.debugLogs,
+  };
+}
+
+/**
+ * Convenience wrapper that resolves a parsed OpenAPI document and collects metrics.
+ * Useful in tests and standalone usage where you don't already have resolved types.
+ */
+export async function collectDocumentMetrics(
+  parsed: Record<string, unknown>,
+  options?: { specVersion?: SpecVersion; debugOperationId?: string }
+): Promise<CollectMetricsResult> {
+  const specVersion: SpecVersion = options?.specVersion ?? 'oas3_0';
+  const types = normalizeTypes(getTypes(specVersion), {});
+  const source = new Source('score.yaml', JSON.stringify(parsed));
+  const document: Document = { source, parsed };
+  const externalRefResolver = new BaseResolver();
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+  const ctx: WalkContext = { problems: [], specVersion, visitorsData: {} };
+
+  return collectMetrics({
+    document,
+    types,
+    resolvedRefMap,
+    ctx,
+    debugOperationId: options?.debugOperationId,
+  });
+}
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
index 1575570ce5..eba76d70c0 100644
--- a/packages/cli/src/commands/score/index.ts
+++ b/packages/cli/src/commands/score/index.ts
@@ -5,12 +5,9 @@ import {
   detectSpec,
   getMajorSpecVersion,
   getTypes,
-  normalizeVisitors,
-  walkDocument,
   bundle,
   logger,
   type OutputFormat,
-  type WalkContext,
 } from '@redocly/openapi-core';
 import * as colors from 'colorette';
 import { performance } from 'perf_hooks';
@@ -19,14 +16,7 @@ import type { VerifyConfigOptions } from '../../types.js';
 import { exitWithError } from '../../utils/error.js';
 import { getFallbackApisOrExit, printExecutionTime } from '../../utils/miscellaneous.js';
 import type { CommandArgs } from '../../wrapper.js';
-import {
-  createScoreAccumulator,
-  createScoreVisitor,
-  createSchemaWalkState,
-  resetSchemaWalkState,
-  createSchemaMetricVisitor,
-  getDocumentMetrics,
-} from './collectors/document-metrics.js';
+import { collectMetrics } from './collect-metrics.js';
 import { computeWorkflowDepths } from './collectors/workflow-graph.js';
 import { printScoreJson } from './formatters/json.js';
 import { printDebugOperation, printScoreStylish } from './formatters/stylish.js';
@@ -39,15 +29,6 @@ import {
 } from './scoring.js';
 import type { DebugMediaTypeLog, ScoreResult } from './types.js';
 
-function resolveJsonPointer(root: any, ref: string): any {
-  if (!ref.startsWith('#/')) return undefined;
-  let node = root;
-  for (const segment of ref.slice(2).split('/')) {
-    node = node?.[decodeURIComponent(segment)];
-  }
-  return node;
-}
-
 export type ScoreArgv = {
   api?: string;
   format: OutputFormat;
@@ -78,128 +59,15 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
     externalRefResolver,
   });
 
-  const ctx: WalkContext = {
-    problems: [],
-    specVersion,
-    config,
-    visitorsData: {},
-  };
-
-  const schemaWalkState = createSchemaWalkState();
-  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
-  const normalizedSchemaVisitors = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor as any }],
-    types
-  );
-
-  type SchemaStats = ReturnType<typeof walkSchemaRaw>;
-
-  const walkSchemaRaw = (schemaNode: any, debug: boolean) => {
-    resetSchemaWalkState(schemaWalkState);
-    if (debug) schemaWalkState.debugEntries = [];
-    walkDocument({
-      document: { ...document, parsed: schemaNode },
-      rootType: types.Schema,
-      normalizedVisitors: normalizedSchemaVisitors,
-      resolvedRefMap,
-      ctx,
-    });
-    return {
-      maxDepth: schemaWalkState.maxDepth,
-      polymorphismCount: schemaWalkState.polymorphismCount,
-      anyOfCount: schemaWalkState.anyOfCount,
-      hasDiscriminator: schemaWalkState.hasDiscriminator,
-      propertyCount: schemaWalkState.propertyCount,
-      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
-      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
-      constraintCount: schemaWalkState.constraintCount,
-      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
-      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
-      refsUsed: [...schemaWalkState.refsUsed],
-      debugEntries: debug ? (schemaWalkState.debugEntries ?? undefined) : undefined,
-    };
-  };
-
-  const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
-    let resolved = schemaNode;
-    if (schemaNode?.$ref && typeof schemaNode.$ref === 'string') {
-      resolved = resolveJsonPointer(document.parsed, schemaNode.$ref) ?? schemaNode;
-    }
-
-    const polyKeyword: 'oneOf' | 'anyOf' | null =
-      Array.isArray(resolved?.oneOf) && resolved.oneOf.length > 1
-        ? 'oneOf'
-        : Array.isArray(resolved?.anyOf) && resolved.anyOf.length > 1
-          ? 'anyOf'
-          : null;
-
-    if (polyKeyword && !resolved.allOf) {
-      const branches = resolved[polyKeyword] as any[];
-
-      const parentOnly = { ...resolved };
-      delete parentOnly[polyKeyword];
-      delete parentOnly.discriminator;
-
-      let maxBranch = walkSchema(branches[0], debug);
-      for (let i = 1; i < branches.length; i++) {
-        const branchStats = walkSchema(branches[i], debug);
-        if (branchStats.propertyCount > maxBranch.propertyCount) {
-          maxBranch = branchStats;
-        }
-      }
-
-      const parentStats = walkSchemaRaw(parentOnly, debug);
-
-      return combineOneOfStats(parentStats, maxBranch, branches.length, polyKeyword);
-    }
-
-    return walkSchemaRaw(schemaNode, debug);
-  };
-
-  function combineOneOfStats(
-    parent: SchemaStats,
-    branch: SchemaStats,
-    branchCount: number,
-    keyword: 'oneOf' | 'anyOf'
-  ): SchemaStats {
-    return {
-      maxDepth: Math.max(parent.maxDepth, branch.maxDepth + 1),
-      polymorphismCount: parent.polymorphismCount + branch.polymorphismCount + branchCount,
-      anyOfCount: parent.anyOfCount + branch.anyOfCount + (keyword === 'anyOf' ? branchCount : 0),
-      hasDiscriminator: parent.hasDiscriminator || branch.hasDiscriminator,
-      propertyCount: parent.propertyCount + branch.propertyCount,
-      totalSchemaProperties: parent.totalSchemaProperties + branch.totalSchemaProperties,
-      schemaPropertiesWithDescription:
-        parent.schemaPropertiesWithDescription + branch.schemaPropertiesWithDescription,
-      constraintCount: parent.constraintCount + branch.constraintCount,
-      hasPropertyExamples: parent.hasPropertyExamples || branch.hasPropertyExamples,
-      writableTopLevelFields: parent.writableTopLevelFields + branch.writableTopLevelFields,
-      refsUsed: [...parent.refsUsed, ...branch.refsUsed],
-      debugEntries:
-        parent.debugEntries || branch.debugEntries
-          ? [...(parent.debugEntries ?? []), ...(branch.debugEntries ?? [])]
-          : undefined,
-    };
-  }
-
   const debugOpId = argv['debug-operation-id'];
-  const accumulator = createScoreAccumulator(walkSchema, debugOpId);
-  const scoreVisitor = createScoreVisitor(accumulator);
-
-  const normalizedVisitors = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
-    types
-  );
-
-  walkDocument({
+  const { metrics: rawMetrics, debugLogs } = collectMetrics({
     document,
-    rootType: types.Root,
-    normalizedVisitors,
+    types,
     resolvedRefMap,
-    ctx,
+    ctx: { problems: [], specVersion, config, visitorsData: {} },
+    debugOperationId: debugOpId,
   });
 
-  const rawMetrics = getDocumentMetrics(accumulator);
   const workflowDepths = computeWorkflowDepths(rawMetrics.operations);
   const operationScores = computeAllOperationScores(rawMetrics, workflowDepths);
   const { integrationSimplicity, agentReadiness } = computeDocumentScores(operationScores);
@@ -223,7 +91,7 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
     startedAt,
     argv.format,
     !!argv['operation-details'],
-    debugOpId ? { operationId: debugOpId, logs: accumulator.debugLogs } : undefined
+    debugOpId ? { operationId: debugOpId, logs: debugLogs } : undefined
   );
 }
 

From 4376c0259eadc384d0923b1288bb2a075a615e27 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Tue, 24 Mar 2026 07:57:14 -0500
Subject: [PATCH 13/22] chore: add median to raw metrics summary and fix label

Add median alongside averages for parameters, schema depth,
polymorphism, and properties in the stylish output. Rename
the misleading "Avg max schema depth" to "Schema depth".

Made-with: Cursor
---
 .../src/commands/score/formatters/stylish.ts  | 34 ++++++++++++-------
 tests/e2e/score/score-minimal/snapshot.txt    |  8 ++---
 tests/e2e/score/score-stylish/snapshot.txt    |  8 ++---
 3 files changed, 30 insertions(+), 20 deletions(-)

diff --git a/packages/cli/src/commands/score/formatters/stylish.ts b/packages/cli/src/commands/score/formatters/stylish.ts
index ac85a5ee12..208446626e 100644
--- a/packages/cli/src/commands/score/formatters/stylish.ts
+++ b/packages/cli/src/commands/score/formatters/stylish.ts
@@ -72,6 +72,13 @@ function buildBar(fraction: number): string {
   return cyan('[' + '\u2588'.repeat(filled) + '\u2591'.repeat(width - filled) + ']');
 }
 
+function median(values: number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
 function printRawMetricsSummary(result: ScoreResult): void {
   out(bold(white('  Raw Metrics Summary')));
   out('');
@@ -82,29 +89,32 @@ function printRawMetricsSummary(result: ScoreResult): void {
     return;
   }
 
-  let totalParams = 0;
-  let totalDepth = 0;
-  let totalPoly = 0;
-  let totalProps = 0;
+  const params: number[] = [];
+  const depths: number[] = [];
+  const polys: number[] = [];
+  const props: number[] = [];
   let opsWithReqExample = 0;
   let opsWithResExample = 0;
   let opsWithDescription = 0;
 
   for (const m of result.rawMetrics.operations.values()) {
-    totalParams += m.parameterCount;
-    totalDepth += Math.max(m.maxRequestSchemaDepth, m.maxResponseSchemaDepth);
-    totalPoly += m.polymorphismCount;
-    totalProps += m.propertyCount;
+    params.push(m.parameterCount);
+    depths.push(Math.max(m.maxRequestSchemaDepth, m.maxResponseSchemaDepth));
+    polys.push(m.polymorphismCount);
+    props.push(m.propertyCount);
     if (m.requestExamplePresent) opsWithReqExample++;
     if (m.responseExamplePresent) opsWithResExample++;
     if (m.operationDescriptionPresent) opsWithDescription++;
   }
 
   const n = result.rawMetrics.operationCount;
-  out(`  Avg parameters/operation: ${(totalParams / n).toFixed(1)}`);
-  out(`  Avg max schema depth: ${(totalDepth / n).toFixed(1)}`);
-  out(`  Avg polymorphism/operation: ${(totalPoly / n).toFixed(1)}`);
-  out(`  Avg properties/operation: ${(totalProps / n).toFixed(1)}`);
+  const avg = (arr: number[]) => (arr.reduce((s, v) => s + v, 0) / n).toFixed(1);
+  const med = (arr: number[]) => median(arr).toFixed(1);
+
+  out(`  Parameters/operation:   avg ${avg(params)}  median ${med(params)}`);
+  out(`  Schema depth:           avg ${avg(depths)}  median ${med(depths)}`);
+  out(`  Polymorphism/operation: avg ${avg(polys)}  median ${med(polys)}`);
+  out(`  Properties/operation:   avg ${avg(props)}  median ${med(props)}`);
   out(
     `  Operations with request examples: ${opsWithReqExample}/${n} (${fmtPct(opsWithReqExample, n)})`
   );
diff --git a/tests/e2e/score/score-minimal/snapshot.txt b/tests/e2e/score/score-minimal/snapshot.txt
index 6695a9404f..089a686508 100644
--- a/tests/e2e/score/score-minimal/snapshot.txt
+++ b/tests/e2e/score/score-minimal/snapshot.txt
@@ -27,10 +27,10 @@
   Raw Metrics Summary
 
   Total operations: 2
-  Avg parameters/operation: 1.0
-  Avg max schema depth: 1.5
-  Avg polymorphism/operation: 0.0
-  Avg properties/operation: 2.0
+  Parameters/operation:   avg 1.0  median 1.0
+  Schema depth:           avg 1.5  median 1.5
+  Polymorphism/operation: avg 0.0  median 0.0
+  Properties/operation:   avg 2.0  median 2.0
   Operations with request examples: 0/2 (0%)
   Operations with response examples: 0/2 (0%)
   Operations with description: 0/2 (0%)
diff --git a/tests/e2e/score/score-stylish/snapshot.txt b/tests/e2e/score/score-stylish/snapshot.txt
index cc6ac4998f..899c1f360f 100644
--- a/tests/e2e/score/score-stylish/snapshot.txt
+++ b/tests/e2e/score/score-stylish/snapshot.txt
@@ -27,10 +27,10 @@
   Raw Metrics Summary
 
   Total operations: 8
-  Avg parameters/operation: 1.4
-  Avg max schema depth: 1.6
-  Avg polymorphism/operation: 0.0
-  Avg properties/operation: 4.4
+  Parameters/operation:   avg 1.4  median 1.0
+  Schema depth:           avg 1.6  median 2.0
+  Polymorphism/operation: avg 0.0  median 0.0
+  Properties/operation:   avg 4.4  median 6.0
   Operations with request examples: 3/8 (38%)
   Operations with response examples: 7/8 (88%)
   Operations with description: 8/8 (100%)

From 483a0aa4b60f6a844c90e7773741d5fd65656e3a Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Tue, 24 Mar 2026 09:34:18 -0500
Subject: [PATCH 14/22] refactor: rename workflow to dependency across score
 command

Rename workflowClarity to dependencyClarity, workflowDepths to
dependencyDepths, and workflow-graph to dependency-graph to align
code naming with the "Dependency Clarity" display label. Also adds
discoverability subscore, recursive composition keyword stripping
for accurate property counting, and updates e2e snapshots.

Made-with: Cursor
---
 docs/@v2/commands/score.md                    |  25 +-
 ...graph.test.ts => dependency-graph.test.ts} |  16 +-
 .../score/__tests__/formatters.test.ts        |  11 +-
 .../commands/score/__tests__/hotspots.test.ts |   8 +-
 .../commands/score/__tests__/scoring.test.ts  |  51 ++++-
 .../cli/src/commands/score/collect-metrics.ts | 213 ++++++++++++++----
 ...{workflow-graph.ts => dependency-graph.ts} |   4 +-
 packages/cli/src/commands/score/constants.ts  |   8 +-
 .../cli/src/commands/score/formatters/json.ts |   3 +-
 .../src/commands/score/formatters/stylish.ts  |  27 ++-
 packages/cli/src/commands/score/hotspots.ts   |  10 +-
 packages/cli/src/commands/score/index.ts      |  26 ++-
 packages/cli/src/commands/score/scoring.ts    |  71 ++++--
 packages/cli/src/commands/score/types.ts      |  15 +-
 tests/e2e/score/score-json/snapshot.txt       |  43 ++--
 tests/e2e/score/score-minimal/snapshot.txt    |  14 +-
 tests/e2e/score/score-stylish/snapshot.txt    |  14 +-
 17 files changed, 390 insertions(+), 169 deletions(-)
 rename packages/cli/src/commands/score/__tests__/{workflow-graph.test.ts => dependency-graph.test.ts} (85%)
 rename packages/cli/src/commands/score/collectors/{workflow-graph.ts => dependency-graph.ts} (93%)

diff --git a/docs/@v2/commands/score.md b/docs/@v2/commands/score.md
index 40d0114642..c4114daca6 100644
--- a/docs/@v2/commands/score.md
+++ b/docs/@v2/commands/score.md
@@ -39,9 +39,11 @@ The following raw metrics are collected per operation and aggregated across the
 
 Subscores are normalized to 0–1 and grouped into two categories:
 
-**Integration Simplicity subscores:** `parameterSimplicity`, `schemaSimplicity`, `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `dependencyClarity`.
+**Integration Simplicity subscores:** `parameterSimplicity`, `schemaSimplicity`, `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `dependencyClarity`, `discoverability`.
 
-**Agent Readiness subscores:** `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `identifierClarity`, `dependencyClarity`, `polymorphismClarity`.
+**Agent Readiness subscores:** `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `identifierClarity`, `dependencyClarity`, `polymorphismClarity`, `discoverability`.
+
+The `discoverability` subscore reflects the total number of operations in the API. Larger APIs (approaching 1,000+ operations) receive a lower discoverability score because finding the right endpoint becomes harder for both humans and AI agents. This subscore is blended into both composite scores.
 
 ### Hotspots
 
@@ -63,14 +65,16 @@ redocly score <api> [--format=<option>] [--config=<path>]
 
 ## Options
 
-| Option        | Type    | Description                                                                                                                                    |
-| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| api           | string  | **REQUIRED.** Path to the API description filename or alias that you want to score. Refer to [the API section](#specify-api) for more details. |
-| --config      | string  | Specify path to the [configuration file](../configuration/index.md).                                                                           |
-| --format      | string  | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`.                                                |
-| --help        | boolean | Show help.                                                                                                                                     |
-| --lint-config | string  | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`.             |
-| --version     | boolean | Show version number.                                                                                                                           |
+| Option               | Type    | Description                                                                                                                                    |
+| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| api                  | string  | **REQUIRED.** Path to the API description filename or alias that you want to score. Refer to [the API section](#specify-api) for more details. |
+| --config             | string  | Specify path to the [configuration file](../configuration/index.md).                                                                           |
+| --format             | string  | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`.                                                |
+| --operation-details  | boolean | Print a per-operation metrics table sorted by property count.                                                                                  |
+| --debug-operation-id | string  | Print a detailed schema breakdown for a specific operation (by `operationId` or `METHOD /path`).                                               |
+| --help               | boolean | Show help.                                                                                                                                     |
+| --lint-config        | string  | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`.             |
+| --version            | boolean | Show version number.                                                                                                                           |
 
 ## Examples
 
@@ -103,6 +107,7 @@ The default output format shows a human-readable summary in your terminal:
   Example Coverage         [████████████████████] 100%
   Error Clarity            [████████████████░░░░] 80%
   Dependency Clarity       [██████████████████░░] 90%
+  Discoverability          [████████████████████] 100%
 
   Top 3 Hotspot Operations
 
diff --git a/packages/cli/src/commands/score/__tests__/workflow-graph.test.ts b/packages/cli/src/commands/score/__tests__/dependency-graph.test.ts
similarity index 85%
rename from packages/cli/src/commands/score/__tests__/workflow-graph.test.ts
rename to packages/cli/src/commands/score/__tests__/dependency-graph.test.ts
index f296353116..ad3a6ce8f7 100644
--- a/packages/cli/src/commands/score/__tests__/workflow-graph.test.ts
+++ b/packages/cli/src/commands/score/__tests__/dependency-graph.test.ts
@@ -1,4 +1,4 @@
-import { computeWorkflowDepths } from '../collectors/workflow-graph.js';
+import { computeDependencyDepths } from '../collectors/dependency-graph.js';
 import type { OperationMetrics } from '../types.js';
 
 function makeOp(path: string, method: string, refs: string[]): OperationMetrics {
@@ -29,13 +29,13 @@ function makeOp(path: string, method: string, refs: string[]): OperationMetrics
   };
 }
 
-describe('computeWorkflowDepths', () => {
+describe('computeDependencyDepths', () => {
   it('returns depth 0 for isolated operations', () => {
     const ops = new Map([
       ['opA', makeOp('/a', 'get', ['#/components/schemas/A'])],
       ['opB', makeOp('/b', 'get', ['#/components/schemas/B'])],
     ]);
-    const depths = computeWorkflowDepths(ops);
+    const depths = computeDependencyDepths(ops);
     expect(depths.get('opA')).toBe(0);
     expect(depths.get('opB')).toBe(0);
   });
@@ -46,7 +46,7 @@ describe('computeWorkflowDepths', () => {
       ['opA', makeOp('/a', 'get', [shared])],
       ['opB', makeOp('/b', 'post', [shared])],
     ]);
-    const depths = computeWorkflowDepths(ops);
+    const depths = computeDependencyDepths(ops);
     expect(depths.get('opA')).toBe(1);
     expect(depths.get('opB')).toBe(1);
   });
@@ -57,20 +57,20 @@ describe('computeWorkflowDepths', () => {
       ['opB', makeOp('/b', 'post', ['#/schemas/AB', '#/schemas/BC'])],
       ['opC', makeOp('/c', 'put', ['#/schemas/BC'])],
     ]);
-    const depths = computeWorkflowDepths(ops);
+    const depths = computeDependencyDepths(ops);
     expect(depths.get('opA')).toBe(2);
     expect(depths.get('opC')).toBe(2);
     expect(depths.get('opB')).toBeLessThanOrEqual(2);
   });
 
   it('handles empty operations map', () => {
-    const depths = computeWorkflowDepths(new Map());
+    const depths = computeDependencyDepths(new Map());
     expect(depths.size).toBe(0);
   });
 
   it('handles operations with no refs', () => {
     const ops = new Map([['opA', makeOp('/a', 'get', [])]]);
-    const depths = computeWorkflowDepths(ops);
+    const depths = computeDependencyDepths(ops);
     expect(depths.get('opA')).toBe(0);
   });
 
@@ -81,7 +81,7 @@ describe('computeWorkflowDepths', () => {
       ['opB', makeOp('/b', 'post', [shared])],
       ['opC', makeOp('/c', 'put', [shared])],
     ]);
-    const depths = computeWorkflowDepths(ops);
+    const depths = computeDependencyDepths(ops);
     expect(depths.get('opA')).toBe(1);
     expect(depths.get('opB')).toBe(1);
     expect(depths.get('opC')).toBe(1);
diff --git a/packages/cli/src/commands/score/__tests__/formatters.test.ts b/packages/cli/src/commands/score/__tests__/formatters.test.ts
index 5762eb1c40..fc3611a491 100644
--- a/packages/cli/src/commands/score/__tests__/formatters.test.ts
+++ b/packages/cli/src/commands/score/__tests__/formatters.test.ts
@@ -12,6 +12,7 @@ const mockOutput = vi.mocked(logger.output);
 const RESULT: ScoreResult = {
   integrationSimplicity: 75,
   agentReadiness: 60,
+  discoverability: 0.95,
   integrationSubscores: {
     parameterSimplicity: 0.8,
     schemaSimplicity: 0.7,
@@ -19,7 +20,7 @@ const RESULT: ScoreResult = {
     constraintClarity: 0.5,
     exampleCoverage: 0.6,
     errorClarity: 1.0,
-    workflowClarity: 0.8,
+    dependencyClarity: 0.8,
   },
   agentSubscores: {
     documentationQuality: 0.9,
@@ -27,7 +28,7 @@ const RESULT: ScoreResult = {
     exampleCoverage: 0.6,
     errorClarity: 1.0,
     identifierClarity: 0.8,
-    workflowClarity: 0.8,
+    dependencyClarity: 0.8,
     polymorphismClarity: 1.0,
   },
   rawMetrics: {
@@ -104,7 +105,7 @@ const RESULT: ScoreResult = {
     },
   ],
   operationScores: new Map(),
-  workflowDepths: new Map(),
+  dependencyDepths: new Map(),
 };
 
 function getStylishOutput(result: ScoreResult): string {
@@ -153,12 +154,12 @@ describe('printScoreJson', () => {
     mockOutput.mockClear();
     printScoreJson({
       ...RESULT,
-      workflowDepths: new Map([
+      dependencyDepths: new Map([
         ['opA', 2],
         ['opB', 0],
       ]),
     });
     const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
-    expect(parsed.workflowDepths).toEqual({ opA: 2, opB: 0 });
+    expect(parsed.dependencyDepths).toEqual({ opA: 2, opB: 0 });
   });
 });
diff --git a/packages/cli/src/commands/score/__tests__/hotspots.test.ts b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
index a348f79294..e85c373b01 100644
--- a/packages/cli/src/commands/score/__tests__/hotspots.test.ts
+++ b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
@@ -42,7 +42,7 @@ function makeScores(overrides: Partial<OperationScores> = {}): OperationScores {
       constraintClarity: 1,
       exampleCoverage: 1,
       errorClarity: 1,
-      workflowClarity: 1,
+      dependencyClarity: 1,
     },
     agentSubscores: {
       documentationQuality: 1,
@@ -50,7 +50,7 @@ function makeScores(overrides: Partial<OperationScores> = {}): OperationScores {
       exampleCoverage: 1,
       errorClarity: 1,
       identifierClarity: 1,
-      workflowClarity: 1,
+      dependencyClarity: 1,
       polymorphismClarity: 1,
     },
     ...overrides,
@@ -223,14 +223,14 @@ describe('selectTopHotspots', () => {
     expect(result[0].reasons).toContain('No parameter descriptions');
   });
 
-  it('detects high workflow dependency depth', () => {
+  it('detects high dependency depth', () => {
     const docMetrics: DocumentMetrics = {
       operationCount: 1,
       operations: new Map([['op1', makeMetrics()]]),
     };
     const opScores = new Map([['op1', makeScores()]]);
     const result = selectTopHotspots(docMetrics, opScores, new Map([['op1', 5]]));
-    expect(result[0].reasons).toContain('High workflow dependency depth (5)');
+    expect(result[0].reasons).toContain('High dependency depth (5)');
   });
 
   it('detects ambiguous identifiers', () => {
diff --git a/packages/cli/src/commands/score/__tests__/scoring.test.ts b/packages/cli/src/commands/score/__tests__/scoring.test.ts
index d86dde18be..851345ddb9 100644
--- a/packages/cli/src/commands/score/__tests__/scoring.test.ts
+++ b/packages/cli/src/commands/score/__tests__/scoring.test.ts
@@ -5,6 +5,7 @@ import {
   computeIntegrationSimplicity,
   computeAgentReadiness,
   computeAllOperationScores,
+  computeDiscoverability,
   computeDocumentScores,
 } from '../scoring.js';
 import type { OperationMetrics, ScoringConstants } from '../types.js';
@@ -166,8 +167,8 @@ describe('scoring', () => {
       const scores1 = computeAllOperationScores(metrics, depths);
       const scores2 = computeAllOperationScores(metrics, depths);
 
-      const doc1 = computeDocumentScores(scores1);
-      const doc2 = computeDocumentScores(scores2);
+      const doc1 = computeDocumentScores(scores1, 1);
+      const doc2 = computeDocumentScores(scores2, 1);
 
       expect(doc1.integrationSimplicity).toBe(doc2.integrationSimplicity);
       expect(doc1.agentReadiness).toBe(doc2.agentReadiness);
@@ -267,18 +268,18 @@ describe('scoring', () => {
     });
   });
 
-  describe('workflow clarity', () => {
-    it('should give full score with 0 workflow depth', () => {
+  describe('dependency clarity', () => {
+    it('should give full score with 0 dependency depth', () => {
       const metrics = makeBaseMetrics();
       const sub = computeOperationIntegrationSubscores(metrics, 0);
-      expect(sub.workflowClarity).toBe(1);
+      expect(sub.dependencyClarity).toBe(1);
     });
 
-    it('should decrease with higher workflow depth', () => {
+    it('should decrease with higher dependency depth', () => {
       const metrics = makeBaseMetrics();
       const sub0 = computeOperationIntegrationSubscores(metrics, 0);
       const sub3 = computeOperationIntegrationSubscores(metrics, 3);
-      expect(sub0.workflowClarity).toBeGreaterThan(sub3.workflowClarity);
+      expect(sub0.dependencyClarity).toBeGreaterThan(sub3.dependencyClarity);
     });
   });
 
@@ -323,6 +324,40 @@ describe('scoring', () => {
     });
   });
 
+  describe('discoverability', () => {
+    it('should return 1 for small APIs', () => {
+      expect(computeDiscoverability(0)).toBe(1);
+      expect(computeDiscoverability(10)).toBeGreaterThan(0.9);
+    });
+
+    it('should decrease with more operations', () => {
+      expect(computeDiscoverability(50)).toBeGreaterThan(computeDiscoverability(200));
+    });
+
+    it('should clamp at 0 for very large APIs', () => {
+      expect(computeDiscoverability(1200)).toBe(0);
+    });
+
+    it('should factor into document scores', () => {
+      const op = makeBaseMetrics({
+        operationDescriptionPresent: true,
+        responseExamplePresent: true,
+      });
+      const doc = {
+        operationCount: 1,
+        operations: new Map([['op1', op]]),
+      };
+      const depths = new Map([['op1', 0]]);
+      const scores = computeAllOperationScores(doc, depths);
+
+      const highDisc = computeDocumentScores(scores, 1.0);
+      const lowDisc = computeDocumentScores(scores, 0.0);
+
+      expect(highDisc.integrationSimplicity).toBeGreaterThanOrEqual(lowDisc.integrationSimplicity);
+      expect(highDisc.agentReadiness).toBeGreaterThanOrEqual(lowDisc.agentReadiness);
+    });
+  });
+
   describe('composite scores', () => {
     it('should produce scores in 0-100 range', () => {
       const metrics = makeBaseMetrics({
@@ -344,7 +379,7 @@ describe('scoring', () => {
 
     it('should return 100/100 for an empty document', () => {
       const opScores = new Map();
-      const { integrationSimplicity, agentReadiness } = computeDocumentScores(opScores);
+      const { integrationSimplicity, agentReadiness } = computeDocumentScores(opScores, 1);
       expect(integrationSimplicity).toBe(100);
       expect(agentReadiness).toBe(100);
     });
diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index 0079bcde59..2ed6df95c0 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -45,32 +45,6 @@ interface SchemaStats {
   debugEntries?: import('./types.js').DebugSchemaEntry[];
 }
 
-function combineOneOfStats(
-  parent: SchemaStats,
-  branch: SchemaStats,
-  branchCount: number,
-  keyword: 'oneOf' | 'anyOf'
-): SchemaStats {
-  return {
-    maxDepth: Math.max(parent.maxDepth, branch.maxDepth + 1),
-    polymorphismCount: parent.polymorphismCount + branch.polymorphismCount + branchCount,
-    anyOfCount: parent.anyOfCount + branch.anyOfCount + (keyword === 'anyOf' ? branchCount : 0),
-    hasDiscriminator: parent.hasDiscriminator || branch.hasDiscriminator,
-    propertyCount: parent.propertyCount + branch.propertyCount,
-    totalSchemaProperties: parent.totalSchemaProperties + branch.totalSchemaProperties,
-    schemaPropertiesWithDescription:
-      parent.schemaPropertiesWithDescription + branch.schemaPropertiesWithDescription,
-    constraintCount: parent.constraintCount + branch.constraintCount,
-    hasPropertyExamples: parent.hasPropertyExamples || branch.hasPropertyExamples,
-    writableTopLevelFields: parent.writableTopLevelFields + branch.writableTopLevelFields,
-    refsUsed: [...parent.refsUsed, ...branch.refsUsed],
-    debugEntries:
-      parent.debugEntries || branch.debugEntries
-        ? [...(parent.debugEntries ?? []), ...(branch.debugEntries ?? [])]
-        : undefined,
-  };
-}
-
 export interface CollectMetricsOptions {
   document: Document;
   types: ReturnType<typeof normalizeTypes>;
@@ -84,6 +58,59 @@ export interface CollectMetricsResult {
   debugLogs: DebugMediaTypeLog[];
 }
 
+interface StrippedComposition {
+  discriminator?: any;
+  oneOf?: any[];
+  anyOf?: any[];
+}
+
+function stripCompositionKeywords(parsed: any): Map<object, StrippedComposition> {
+  const removed = new Map<object, StrippedComposition>();
+  const seen = new WeakSet<object>();
+
+  function walk(node: any): void {
+    if (!node || typeof node !== 'object' || seen.has(node)) return;
+    seen.add(node);
+
+    const stripped: StrippedComposition = {};
+    let hasStripped = false;
+
+    if (node.discriminator?.mapping) {
+      stripped.discriminator = node.discriminator;
+      delete node.discriminator;
+      hasStripped = true;
+    }
+    if (Array.isArray(node.oneOf) && node.oneOf.length > 1) {
+      stripped.oneOf = node.oneOf;
+      delete node.oneOf;
+      hasStripped = true;
+    }
+    if (Array.isArray(node.anyOf) && node.anyOf.length > 1) {
+      stripped.anyOf = node.anyOf;
+      delete node.anyOf;
+      hasStripped = true;
+    }
+
+    if (hasStripped) removed.set(node, stripped);
+
+    for (const val of Object.values(node)) {
+      walk(val);
+    }
+  }
+
+  walk(parsed);
+  return removed;
+}
+
+function restoreCompositionKeywords(removed: Map<object, StrippedComposition>): void {
+  for (const [schema, stripped] of removed) {
+    const s = schema as any;
+    if (stripped.discriminator) s.discriminator = stripped.discriminator;
+    if (stripped.oneOf) s.oneOf = stripped.oneOf;
+    if (stripped.anyOf) s.anyOf = stripped.anyOf;
+  }
+}
+
 export function collectMetrics({
   document,
   types,
@@ -91,6 +118,8 @@ export function collectMetrics({
   ctx,
   debugOperationId,
 }: CollectMetricsOptions): CollectMetricsResult {
+  const removedComposition = stripCompositionKeywords(document.parsed);
+
   const schemaWalkState = createSchemaWalkState();
   const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
   const normalizedSchemaVisitors = normalizeVisitors(
@@ -125,6 +154,42 @@ export function collectMetrics({
   };
 
   const schemaCache = new Map<string, SchemaStats>();
+  const computing = new WeakSet<object>();
+
+  const emptyStats: SchemaStats = {
+    maxDepth: 0,
+    polymorphismCount: 0,
+    anyOfCount: 0,
+    hasDiscriminator: false,
+    propertyCount: 0,
+    totalSchemaProperties: 0,
+    schemaPropertiesWithDescription: 0,
+    constraintCount: 0,
+    hasPropertyExamples: false,
+    writableTopLevelFields: 0,
+    refsUsed: [],
+  };
+
+  function addStats(a: SchemaStats, b: SchemaStats): SchemaStats {
+    return {
+      maxDepth: Math.max(a.maxDepth, b.maxDepth),
+      polymorphismCount: a.polymorphismCount + b.polymorphismCount,
+      anyOfCount: a.anyOfCount + b.anyOfCount,
+      hasDiscriminator: a.hasDiscriminator || b.hasDiscriminator,
+      propertyCount: a.propertyCount + b.propertyCount,
+      totalSchemaProperties: a.totalSchemaProperties + b.totalSchemaProperties,
+      schemaPropertiesWithDescription:
+        a.schemaPropertiesWithDescription + b.schemaPropertiesWithDescription,
+      constraintCount: a.constraintCount + b.constraintCount,
+      hasPropertyExamples: a.hasPropertyExamples || b.hasPropertyExamples,
+      writableTopLevelFields: a.writableTopLevelFields + b.writableTopLevelFields,
+      refsUsed: [...a.refsUsed, ...b.refsUsed],
+      debugEntries:
+        a.debugEntries || b.debugEntries
+          ? [...(a.debugEntries ?? []), ...(b.debugEntries ?? [])]
+          : undefined,
+    };
+  }
 
   const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
     let resolved = schemaNode;
@@ -139,37 +204,101 @@ export function collectMetrics({
       resolved = resolveJsonPointer(document.parsed, ref) ?? schemaNode;
     }
 
+    if (resolved && typeof resolved === 'object' && computing.has(resolved)) {
+      return { ...emptyStats };
+    }
+    if (resolved && typeof resolved === 'object') {
+      computing.add(resolved);
+    }
+
+    const stripped =
+      resolved && typeof resolved === 'object' ? removedComposition.get(resolved) : undefined;
+
+    const oneOfBranches = resolved?.oneOf ?? stripped?.oneOf;
+    const anyOfBranches = resolved?.anyOf ?? stripped?.anyOf;
     const polyKeyword: 'oneOf' | 'anyOf' | null =
-      Array.isArray(resolved?.oneOf) && resolved.oneOf.length > 1
+      Array.isArray(oneOfBranches) && oneOfBranches.length > 1
         ? 'oneOf'
-        : Array.isArray(resolved?.anyOf) && resolved.anyOf.length > 1
+        : Array.isArray(anyOfBranches) && anyOfBranches.length > 1
           ? 'anyOf'
           : null;
+    const polyBranches: any[] | null =
+      polyKeyword === 'oneOf' ? oneOfBranches : polyKeyword === 'anyOf' ? anyOfBranches : null;
 
-    let result: SchemaStats;
+    const hasAllOf = Array.isArray(resolved?.allOf) && resolved.allOf.length > 0;
+
+    const disc = resolved?.discriminator ?? stripped?.discriminator;
+    const discriminatorRefs =
+      !polyKeyword && disc?.mapping
+        ? (Object.values(disc.mapping) as string[])
+            .filter((v) => typeof v === 'string' && v.startsWith('#/'))
+            .map((v) => ({ $ref: v }))
+        : null;
+    const hasDiscriminatorBranches = discriminatorRefs != null && discriminatorRefs.length > 0;
 
-    if (polyKeyword && !resolved.allOf) {
-      const branches = resolved[polyKeyword] as any[];
+    let result: SchemaStats;
 
+    if (polyKeyword || hasAllOf || hasDiscriminatorBranches) {
       const parentOnly = { ...resolved };
-      delete parentOnly[polyKeyword];
-      delete parentOnly.discriminator;
-
-      let maxBranch = walkSchema(branches[0], debug);
-      for (let i = 1; i < branches.length; i++) {
-        const branchStats = walkSchema(branches[i], debug);
-        if (branchStats.propertyCount > maxBranch.propertyCount) {
-          maxBranch = branchStats;
+
+      let polyStats: SchemaStats | null = null;
+      if (polyKeyword && polyBranches) {
+        delete parentOnly[polyKeyword];
+        delete parentOnly.discriminator;
+
+        let maxBranch = walkSchema(polyBranches[0], debug);
+        for (let i = 1; i < polyBranches.length; i++) {
+          const branchStats = walkSchema(polyBranches[i], debug);
+          if (branchStats.propertyCount > maxBranch.propertyCount) {
+            maxBranch = branchStats;
+          }
         }
+        polyStats = {
+          ...maxBranch,
+          polymorphismCount: maxBranch.polymorphismCount + polyBranches.length,
+          anyOfCount: maxBranch.anyOfCount + (polyKeyword === 'anyOf' ? polyBranches.length : 0),
+        };
       }
 
-      const parentStats = walkSchemaRaw(parentOnly, debug);
+      let discStats: SchemaStats | null = null;
+      if (hasDiscriminatorBranches) {
+        delete parentOnly.discriminator;
+
+        let maxBranch = walkSchema(discriminatorRefs![0], debug);
+        for (let i = 1; i < discriminatorRefs!.length; i++) {
+          const branchStats = walkSchema(discriminatorRefs![i], debug);
+          if (branchStats.propertyCount > maxBranch.propertyCount) {
+            maxBranch = branchStats;
+          }
+        }
+        discStats = {
+          ...maxBranch,
+          polymorphismCount: maxBranch.polymorphismCount + discriminatorRefs!.length,
+          hasDiscriminator: true,
+        };
+      }
 
-      result = combineOneOfStats(parentStats, maxBranch, branches.length, polyKeyword);
+      let allOfStats: SchemaStats | null = null;
+      if (hasAllOf) {
+        delete parentOnly.allOf;
+        allOfStats = { ...emptyStats };
+        for (const member of resolved.allOf) {
+          allOfStats = addStats(allOfStats, walkSchema(member, debug));
+        }
+      }
+
+      const parentStats = walkSchemaRaw(parentOnly, debug);
+      result = parentStats;
+      if (allOfStats) result = addStats(result, allOfStats);
+      if (polyStats) result = addStats(result, polyStats);
+      if (discStats) result = addStats(result, discStats);
     } else {
       result = walkSchemaRaw(schemaNode, debug);
     }
 
+    if (resolved && typeof resolved === 'object') {
+      computing.delete(resolved);
+    }
     if (ref && !debug) {
       schemaCache.set(ref, result);
     }
@@ -193,6 +322,8 @@ export function collectMetrics({
     ctx,
   });
 
+  restoreCompositionKeywords(removedComposition);
+
   return {
     metrics: getDocumentMetrics(accumulator),
     debugLogs: accumulator.debugLogs,
diff --git a/packages/cli/src/commands/score/collectors/workflow-graph.ts b/packages/cli/src/commands/score/collectors/dependency-graph.ts
similarity index 93%
rename from packages/cli/src/commands/score/collectors/workflow-graph.ts
rename to packages/cli/src/commands/score/collectors/dependency-graph.ts
index 5dc57c67f2..1842616941 100644
--- a/packages/cli/src/commands/score/collectors/workflow-graph.ts
+++ b/packages/cli/src/commands/score/collectors/dependency-graph.ts
@@ -1,12 +1,12 @@
 import type { OperationMetrics } from '../types.js';
 
 /**
- * Builds a workflow dependency graph from shared $ref usage across operations.
+ * Builds a dependency graph from shared $ref usage across operations.
  * An edge from A to B means both A and B reference the same schema $ref.
  * The depth for each operation is the longest path from a root node (no incoming edges)
  * in the undirected "shared ref" graph.
  */
-export function computeWorkflowDepths(
+export function computeDependencyDepths(
   operations: Map<string, OperationMetrics>
 ): Map<string, number> {
   const refToOps = new Map<string, Set<string>>();
diff --git a/packages/cli/src/commands/score/constants.ts b/packages/cli/src/commands/score/constants.ts
index 59994102e4..e693ca9935 100644
--- a/packages/cli/src/commands/score/constants.ts
+++ b/packages/cli/src/commands/score/constants.ts
@@ -6,8 +6,9 @@ export const DEFAULT_SCORING_CONSTANTS: ScoringConstants = {
     maxDepthGood: 4,
     maxPolymorphismGood: 2,
     maxPropertiesGood: 20,
-    maxWorkflowDepthGood: 3,
+    maxDependencyDepthGood: 3,
     maxAmbiguousGood: 0,
+    maxOperationsForDiscoverability: 1000,
   },
   weights: {
     integration: {
@@ -17,7 +18,7 @@ export const DEFAULT_SCORING_CONSTANTS: ScoringConstants = {
       constraintClarity: 0.1,
       exampleCoverage: 0.15,
       errorClarity: 0.1,
-      workflowClarity: 0.1,
+      dependencyClarity: 0.1,
     },
     agent: {
       documentationQuality: 0.2,
@@ -25,10 +26,11 @@ export const DEFAULT_SCORING_CONSTANTS: ScoringConstants = {
       exampleCoverage: 0.2,
       errorClarity: 0.15,
       identifierClarity: 0.1,
-      workflowClarity: 0.1,
+      dependencyClarity: 0.1,
       polymorphismClarity: 0.1,
     },
     anyOfPenaltyMultiplier: 2.0,
+    discoverabilityWeight: 0.1,
   },
   hotspotLimit: 10,
 };
diff --git a/packages/cli/src/commands/score/formatters/json.ts b/packages/cli/src/commands/score/formatters/json.ts
index 8e45cc6073..57cda63c80 100644
--- a/packages/cli/src/commands/score/formatters/json.ts
+++ b/packages/cli/src/commands/score/formatters/json.ts
@@ -6,6 +6,7 @@ export function printScoreJson(result: ScoreResult): void {
   const output = {
     integrationSimplicity: result.integrationSimplicity,
     agentReadiness: result.agentReadiness,
+    discoverability: Math.round(result.discoverability * 100),
     integrationSubscores: result.integrationSubscores,
     agentSubscores: result.agentSubscores,
     rawMetrics: {
@@ -52,7 +53,7 @@ export function printScoreJson(result: ScoreResult): void {
         },
       ])
     ),
-    workflowDepths: Object.fromEntries(result.workflowDepths),
+    dependencyDepths: Object.fromEntries(result.dependencyDepths),
     hotspots: result.hotspots,
   };
 
diff --git a/packages/cli/src/commands/score/formatters/stylish.ts b/packages/cli/src/commands/score/formatters/stylish.ts
index 208446626e..0ae85a78bc 100644
--- a/packages/cli/src/commands/score/formatters/stylish.ts
+++ b/packages/cli/src/commands/score/formatters/stylish.ts
@@ -44,7 +44,8 @@ function printSubscores(result: ScoreResult): void {
   printSubscore('Constraint Clarity', is.constraintClarity);
   printSubscore('Example Coverage', is.exampleCoverage);
   printSubscore('Error Clarity', is.errorClarity);
-  printSubscore('Dependency Clarity', is.workflowClarity);
+  printSubscore('Dependency Clarity', is.dependencyClarity);
+  printSubscore('Discoverability', result.discoverability);
   out('');
 
   out(bold(white('  Agent Readiness Subscores')));
@@ -55,8 +56,9 @@ function printSubscores(result: ScoreResult): void {
   printSubscore('Example Coverage', ar.exampleCoverage);
   printSubscore('Error Clarity', ar.errorClarity);
   printSubscore('Identifier Clarity', ar.identifierClarity);
-  printSubscore('Dependency Clarity', ar.workflowClarity);
+  printSubscore('Dependency Clarity', ar.dependencyClarity);
   printSubscore('Polymorphism Clarity', ar.polymorphismClarity);
+  printSubscore('Discoverability', result.discoverability);
   out('');
 }
 
@@ -108,13 +110,22 @@ function printRawMetricsSummary(result: ScoreResult): void {
   }
 
   const n = result.rawMetrics.operationCount;
-  const avg = (arr: number[]) => (arr.reduce((s, v) => s + v, 0) / n).toFixed(1);
-  const med = (arr: number[]) => median(arr).toFixed(1);
 
-  out(`  Parameters/operation:   avg ${avg(params)}  median ${med(params)}`);
-  out(`  Schema depth:           avg ${avg(depths)}  median ${med(depths)}`);
-  out(`  Polymorphism/operation: avg ${avg(polys)}  median ${med(polys)}`);
-  out(`  Properties/operation:   avg ${avg(props)}  median ${med(props)}`);
+  function statLine(label: string, values: number[]): void {
+    const sum = values.reduce((s, v) => s + v, 0);
+    const avg = (sum / n).toFixed(1);
+    const med = median(values).toFixed(1);
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    out(
+      `  ${label.padEnd(26)} avg ${avg.padStart(6)}  median ${med.padStart(6)}  min ${String(min).padStart(5)}  max ${String(max).padStart(5)}`
+    );
+  }
+
+  statLine('Parameters/operation:', params);
+  statLine('Schema depth:', depths);
+  statLine('Polymorphism/operation:', polys);
+  statLine('Properties/operation:', props);
   out(
     `  Operations with request examples: ${opsWithReqExample}/${n} (${fmtPct(opsWithReqExample, n)})`
   );
diff --git a/packages/cli/src/commands/score/hotspots.ts b/packages/cli/src/commands/score/hotspots.ts
index ef21a5acad..6288ac3a27 100644
--- a/packages/cli/src/commands/score/hotspots.ts
+++ b/packages/cli/src/commands/score/hotspots.ts
@@ -9,7 +9,7 @@ import type {
 export function selectTopHotspots(
   documentMetrics: DocumentMetrics,
   operationScores: Map<string, OperationScores>,
-  workflowDepths: Map<string, number>,
+  dependencyDepths: Map<string, number>,
   constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
 ): HotspotOperation[] {
   const entries: HotspotOperation[] = [];
@@ -18,7 +18,7 @@ export function selectTopHotspots(
     const metrics = documentMetrics.operations.get(key);
     if (!metrics) continue;
 
-    const reasons = getHotspotReasons(metrics, scores, workflowDepths.get(key) ?? 0, constants);
+    const reasons = getHotspotReasons(metrics, scores, dependencyDepths.get(key) ?? 0, constants);
     if (reasons.length === 0) continue;
 
     entries.push({
@@ -59,7 +59,7 @@ function getHotspotReasons(
     ambiguousIdentifierCount: number;
   },
   scores: OperationScores,
-  workflowDepth: number,
+  dependencyDepth: number,
   constants: ScoringConstants
 ): string[] {
   const { thresholds } = constants;
@@ -103,8 +103,8 @@ function getHotspotReasons(
     reasons.push('No parameter descriptions');
   }
 
-  if (workflowDepth > thresholds.maxWorkflowDepthGood) {
-    reasons.push(`High workflow dependency depth (${workflowDepth})`);
+  if (dependencyDepth > thresholds.maxDependencyDepthGood) {
+    reasons.push(`High dependency depth (${dependencyDepth})`);
   }
 
   if (metrics.ambiguousIdentifierCount > thresholds.maxAmbiguousGood) {
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
index eba76d70c0..875df601d8 100644
--- a/packages/cli/src/commands/score/index.ts
+++ b/packages/cli/src/commands/score/index.ts
@@ -17,14 +17,15 @@ import { exitWithError } from '../../utils/error.js';
 import { getFallbackApisOrExit, printExecutionTime } from '../../utils/miscellaneous.js';
 import type { CommandArgs } from '../../wrapper.js';
 import { collectMetrics } from './collect-metrics.js';
-import { computeWorkflowDepths } from './collectors/workflow-graph.js';
+import { computeDependencyDepths } from './collectors/dependency-graph.js';
 import { printScoreJson } from './formatters/json.js';
 import { printDebugOperation, printScoreStylish } from './formatters/stylish.js';
 import { selectTopHotspots } from './hotspots.js';
 import {
-  averageAgentSubscores,
-  averageIntegrationSubscores,
+  aggregateAgentSubscores,
+  aggregateIntegrationSubscores,
   computeAllOperationScores,
+  computeDiscoverability,
   computeDocumentScores,
 } from './scoring.js';
 import type { DebugMediaTypeLog, ScoreResult } from './types.js';
@@ -68,21 +69,26 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
     debugOperationId: debugOpId,
   });
 
-  const workflowDepths = computeWorkflowDepths(rawMetrics.operations);
-  const operationScores = computeAllOperationScores(rawMetrics, workflowDepths);
-  const { integrationSimplicity, agentReadiness } = computeDocumentScores(operationScores);
+  const dependencyDepths = computeDependencyDepths(rawMetrics.operations);
+  const operationScores = computeAllOperationScores(rawMetrics, dependencyDepths);
+  const discoverability = computeDiscoverability(rawMetrics.operationCount);
+  const { integrationSimplicity, agentReadiness } = computeDocumentScores(
+    operationScores,
+    discoverability
+  );
 
-  const hotspots = selectTopHotspots(rawMetrics, operationScores, workflowDepths);
+  const hotspots = selectTopHotspots(rawMetrics, operationScores, dependencyDepths);
 
   const result: ScoreResult = {
     integrationSimplicity,
     agentReadiness,
-    integrationSubscores: averageIntegrationSubscores(operationScores),
-    agentSubscores: averageAgentSubscores(operationScores),
+    discoverability,
+    integrationSubscores: aggregateIntegrationSubscores(operationScores),
+    agentSubscores: aggregateAgentSubscores(operationScores),
     rawMetrics,
     hotspots,
     operationScores,
-    workflowDepths,
+    dependencyDepths,
   };
 
   printScore(
diff --git a/packages/cli/src/commands/score/scoring.ts b/packages/cli/src/commands/score/scoring.ts
index 0806e61b90..8af67fd808 100644
--- a/packages/cli/src/commands/score/scoring.ts
+++ b/packages/cli/src/commands/score/scoring.ts
@@ -10,7 +10,7 @@ import type {
 
 export function computeOperationIntegrationSubscores(
   metrics: OperationMetrics,
-  workflowDepth: number,
+  dependencyDepth: number,
   constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
 ): IntegrationSimplicitySubscores {
   const { thresholds, weights } = constants;
@@ -44,7 +44,7 @@ export function computeOperationIntegrationSubscores(
       ? clamp01(metrics.structuredErrorResponseCount / metrics.totalErrorResponses)
       : 1;
 
-  const workflowClarity = clamp01(1 - workflowDepth / (thresholds.maxWorkflowDepthGood * 2));
+  const dependencyClarity = clamp01(1 - dependencyDepth / (thresholds.maxDependencyDepthGood * 2));
 
   return {
     parameterSimplicity,
@@ -53,13 +53,13 @@ export function computeOperationIntegrationSubscores(
     constraintClarity,
     exampleCoverage,
     errorClarity,
-    workflowClarity,
+    dependencyClarity,
   };
 }
 
 export function computeOperationAgentSubscores(
   metrics: OperationMetrics,
-  workflowDepth: number,
+  dependencyDepth: number,
   constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
 ): AgentReadinessSubscores {
   const { thresholds, weights } = constants;
@@ -88,7 +88,7 @@ export function computeOperationAgentSubscores(
     1 - metrics.ambiguousIdentifierCount / Math.max(thresholds.maxAmbiguousGood + 3, 1)
   );
 
-  const workflowClarity = clamp01(1 - workflowDepth / (thresholds.maxWorkflowDepthGood * 2));
+  const dependencyClarity = clamp01(1 - dependencyDepth / (thresholds.maxDependencyDepthGood * 2));
 
   const polyScore = effectivePolymorphism(metrics, weights.anyOfPenaltyMultiplier);
   const polyClarity =
@@ -104,7 +104,7 @@ export function computeOperationAgentSubscores(
     exampleCoverage,
     errorClarity,
     identifierClarity,
-    workflowClarity,
+    dependencyClarity,
     polymorphismClarity: polyClarity,
   };
 }
@@ -121,7 +121,7 @@ export function computeIntegrationSimplicity(
     subscores.constraintClarity * w.constraintClarity +
     subscores.exampleCoverage * w.exampleCoverage +
     subscores.errorClarity * w.errorClarity +
-    subscores.workflowClarity * w.workflowClarity;
+    subscores.dependencyClarity * w.dependencyClarity;
   return round(clamp01(raw) * 100);
 }
 
@@ -136,20 +136,20 @@ export function computeAgentReadiness(
     subscores.exampleCoverage * w.exampleCoverage +
     subscores.errorClarity * w.errorClarity +
     subscores.identifierClarity * w.identifierClarity +
-    subscores.workflowClarity * w.workflowClarity +
+    subscores.dependencyClarity * w.dependencyClarity +
     subscores.polymorphismClarity * w.polymorphismClarity;
   return round(clamp01(raw) * 100);
 }
 
 export function computeAllOperationScores(
   documentMetrics: DocumentMetrics,
-  workflowDepths: Map<string, number>,
+  dependencyDepths: Map<string, number>,
   constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
 ): Map<string, OperationScores> {
   const result = new Map<string, OperationScores>();
 
   for (const [key, metrics] of documentMetrics.operations) {
-    const depth = workflowDepths.get(key) ?? 0;
+    const depth = dependencyDepths.get(key) ?? 0;
     const integrationSubscores = computeOperationIntegrationSubscores(metrics, depth, constants);
     const agentSubscores = computeOperationAgentSubscores(metrics, depth, constants);
 
@@ -164,7 +164,18 @@ export function computeAllOperationScores(
   return result;
 }
 
-export function computeDocumentScores(operationScores: Map<string, OperationScores>): {
+export function computeDiscoverability(
+  operationCount: number,
+  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
+): number {
+  return clamp01(1 - operationCount / constants.thresholds.maxOperationsForDiscoverability);
+}
+
+export function computeDocumentScores(
+  operationScores: Map<string, OperationScores>,
+  discoverability: number,
+  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
+): {
   integrationSimplicity: number;
   agentReadiness: number;
 } {
@@ -172,16 +183,19 @@ export function computeDocumentScores(operationScores: Map<string, OperationScor
     return { integrationSimplicity: 100, agentReadiness: 100 };
   }
 
-  let sumInt = 0;
-  let sumAgent = 0;
+  const intScores: number[] = [];
+  const agentScores: number[] = [];
   for (const scores of operationScores.values()) {
-    sumInt += scores.integrationSimplicity;
-    sumAgent += scores.agentReadiness;
+    intScores.push(scores.integrationSimplicity);
+    agentScores.push(scores.agentReadiness);
   }
 
+  const w = constants.weights.discoverabilityWeight;
+  const discPct = discoverability * 100;
+
   return {
-    integrationSimplicity: round(sumInt / operationScores.size),
-    agentReadiness: round(sumAgent / operationScores.size),
+    integrationSimplicity: round(median(intScores) * (1 - w) + discPct * w),
+    agentReadiness: round(median(agentScores) * (1 - w) + discPct * w),
   };
 }
 
@@ -194,7 +208,7 @@ function clamp01(value: number): number {
   return Math.max(0, Math.min(1, value));
 }
 
-export function averageIntegrationSubscores(
+export function aggregateIntegrationSubscores(
   operationScores: Map<string, { integrationSubscores: IntegrationSimplicitySubscores }>
 ): IntegrationSimplicitySubscores {
   const n = operationScores.size || 1;
@@ -205,7 +219,7 @@ export function averageIntegrationSubscores(
     constraintClarity: 0,
     exampleCoverage: 0,
     errorClarity: 0,
-    workflowClarity: 0,
+    dependencyClarity: 0,
   };
 
   for (const scores of operationScores.values()) {
@@ -215,7 +229,7 @@ export function averageIntegrationSubscores(
     result.constraintClarity += scores.integrationSubscores.constraintClarity;
     result.exampleCoverage += scores.integrationSubscores.exampleCoverage;
     result.errorClarity += scores.integrationSubscores.errorClarity;
-    result.workflowClarity += scores.integrationSubscores.workflowClarity;
+    result.dependencyClarity += scores.integrationSubscores.dependencyClarity;
   }
 
   result.parameterSimplicity /= n;
@@ -224,12 +238,12 @@ export function averageIntegrationSubscores(
   result.constraintClarity /= n;
   result.exampleCoverage /= n;
   result.errorClarity /= n;
-  result.workflowClarity /= n;
+  result.dependencyClarity /= n;
 
   return result;
 }
 
-export function averageAgentSubscores(
+export function aggregateAgentSubscores(
   operationScores: Map<string, { agentSubscores: AgentReadinessSubscores }>
 ): AgentReadinessSubscores {
   const n = operationScores.size || 1;
@@ -239,7 +253,7 @@ export function averageAgentSubscores(
     exampleCoverage: 0,
     errorClarity: 0,
     identifierClarity: 0,
-    workflowClarity: 0,
+    dependencyClarity: 0,
     polymorphismClarity: 0,
   };
 
@@ -249,7 +263,7 @@ export function averageAgentSubscores(
     result.exampleCoverage += scores.agentSubscores.exampleCoverage;
     result.errorClarity += scores.agentSubscores.errorClarity;
     result.identifierClarity += scores.agentSubscores.identifierClarity;
-    result.workflowClarity += scores.agentSubscores.workflowClarity;
+    result.dependencyClarity += scores.agentSubscores.dependencyClarity;
     result.polymorphismClarity += scores.agentSubscores.polymorphismClarity;
   }
 
@@ -258,12 +272,19 @@ export function averageAgentSubscores(
   result.exampleCoverage /= n;
   result.errorClarity /= n;
   result.identifierClarity /= n;
-  result.workflowClarity /= n;
+  result.dependencyClarity /= n;
   result.polymorphismClarity /= n;
 
   return result;
 }
 
+function median(values: number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
 function round(value: number): number {
   return Math.round(value * 10) / 10;
 }
diff --git a/packages/cli/src/commands/score/types.ts b/packages/cli/src/commands/score/types.ts
index 586d1a0608..ea05ad6cd0 100644
--- a/packages/cli/src/commands/score/types.ts
+++ b/packages/cli/src/commands/score/types.ts
@@ -46,7 +46,7 @@ export interface IntegrationSimplicitySubscores {
   constraintClarity: number;
   exampleCoverage: number;
   errorClarity: number;
-  workflowClarity: number;
+  dependencyClarity: number;
 }
 
 export interface AgentReadinessSubscores {
@@ -55,7 +55,7 @@ export interface AgentReadinessSubscores {
   exampleCoverage: number;
   errorClarity: number;
   identifierClarity: number;
-  workflowClarity: number;
+  dependencyClarity: number;
   polymorphismClarity: number;
 }
 
@@ -78,12 +78,13 @@ export interface HotspotOperation {
 export interface ScoreResult {
   integrationSimplicity: number;
   agentReadiness: number;
+  discoverability: number;
   integrationSubscores: IntegrationSimplicitySubscores;
   agentSubscores: AgentReadinessSubscores;
   rawMetrics: DocumentMetrics;
   hotspots: HotspotOperation[];
   operationScores: Map<string, OperationScores>;
-  workflowDepths: Map<string, number>;
+  dependencyDepths: Map<string, number>;
 }
 
 export interface ScoringThresholds {
@@ -91,8 +92,9 @@ export interface ScoringThresholds {
   maxDepthGood: number;
   maxPolymorphismGood: number;
   maxPropertiesGood: number;
-  maxWorkflowDepthGood: number;
+  maxDependencyDepthGood: number;
   maxAmbiguousGood: number;
+  maxOperationsForDiscoverability: number;
 }
 
 export interface ScoringWeights {
@@ -103,7 +105,7 @@ export interface ScoringWeights {
     constraintClarity: number;
     exampleCoverage: number;
     errorClarity: number;
-    workflowClarity: number;
+    dependencyClarity: number;
   };
   agent: {
     documentationQuality: number;
@@ -111,10 +113,11 @@ export interface ScoringWeights {
     exampleCoverage: number;
     errorClarity: number;
     identifierClarity: number;
-    workflowClarity: number;
+    dependencyClarity: number;
     polymorphismClarity: number;
   };
   anyOfPenaltyMultiplier: number;
+  discoverabilityWeight: number;
 }
 
 export interface ScoringConstants {
diff --git a/tests/e2e/score/score-json/snapshot.txt b/tests/e2e/score/score-json/snapshot.txt
index b63a0a7a27..0e133ed19c 100644
--- a/tests/e2e/score/score-json/snapshot.txt
+++ b/tests/e2e/score/score-json/snapshot.txt
@@ -1,6 +1,7 @@
 {
-  "integrationSimplicity": 83,
-  "agentReadiness": 86.6,
+  "integrationSimplicity": 86.2,
+  "agentReadiness": 90.2,
+  "discoverability": 99,
   "integrationSubscores": {
     "parameterSimplicity": 0.8625,
     "schemaSimplicity": 0.796875,
@@ -8,7 +9,7 @@
     "constraintClarity": 0.5833333333333333,
     "exampleCoverage": 0.875,
     "errorClarity": 1,
-    "workflowClarity": 0.7291666666666669
+    "dependencyClarity": 0.7291666666666669
   },
   "agentSubscores": {
     "documentationQuality": 0.9017857142857143,
@@ -16,7 +17,7 @@
     "exampleCoverage": 0.875,
     "errorClarity": 1,
     "identifierClarity": 1,
-    "workflowClarity": 0.7291666666666669,
+    "dependencyClarity": 0.7291666666666669,
     "polymorphismClarity": 1
   },
   "rawMetrics": {
@@ -235,7 +236,7 @@
         "constraintClarity": 1,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.8333333333333334
+        "dependencyClarity": 0.8333333333333334
       },
       "agentSubscores": {
         "documentationQuality": 0.8571428571428571,
@@ -243,7 +244,7 @@
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.8333333333333334,
+        "dependencyClarity": 0.8333333333333334,
         "polymorphismClarity": 1
       }
     },
@@ -257,7 +258,7 @@
         "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.6666666666666667
+        "dependencyClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 1,
@@ -265,7 +266,7 @@
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.6666666666666667,
+        "dependencyClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
@@ -279,7 +280,7 @@
         "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.6666666666666667
+        "dependencyClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 1,
@@ -287,7 +288,7 @@
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.6666666666666667,
+        "dependencyClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
@@ -301,7 +302,7 @@
         "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.6666666666666667
+        "dependencyClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 1,
@@ -309,7 +310,7 @@
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.6666666666666667,
+        "dependencyClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
@@ -323,7 +324,7 @@
         "constraintClarity": 0,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.6666666666666667
+        "dependencyClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 0.5,
@@ -331,7 +332,7 @@
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.6666666666666667,
+        "dependencyClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
@@ -345,7 +346,7 @@
         "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.6666666666666667
+        "dependencyClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 1,
@@ -353,7 +354,7 @@
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.6666666666666667,
+        "dependencyClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
@@ -367,7 +368,7 @@
         "constraintClarity": 0.6666666666666666,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "workflowClarity": 0.6666666666666667
+        "dependencyClarity": 0.6666666666666667
       },
       "agentSubscores": {
         "documentationQuality": 0.8571428571428571,
@@ -375,7 +376,7 @@
         "exampleCoverage": 1,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 0.6666666666666667,
+        "dependencyClarity": 0.6666666666666667,
         "polymorphismClarity": 1
       }
     },
@@ -389,7 +390,7 @@
         "constraintClarity": 1,
         "exampleCoverage": 0,
         "errorClarity": 1,
-        "workflowClarity": 1
+        "dependencyClarity": 1
       },
       "agentSubscores": {
         "documentationQuality": 1,
@@ -397,12 +398,12 @@
         "exampleCoverage": 0,
         "errorClarity": 1,
         "identifierClarity": 1,
-        "workflowClarity": 1,
+        "dependencyClarity": 1,
         "polymorphismClarity": 1
       }
     }
   },
-  "workflowDepths": {
+  "dependencyDepths": {
     "getMuseumHours": 1,
     "listSpecialEvents": 2,
     "createSpecialEvent": 2,
diff --git a/tests/e2e/score/score-minimal/snapshot.txt b/tests/e2e/score/score-minimal/snapshot.txt
index 089a686508..9ef0ebf8d3 100644
--- a/tests/e2e/score/score-minimal/snapshot.txt
+++ b/tests/e2e/score/score-minimal/snapshot.txt
@@ -1,8 +1,8 @@
 
   Scores
 
-  Integration Simplicity:  54.3/100
-  Agent Readiness:         41.7/100
+  Integration Simplicity:  58.8/100
+  Agent Readiness:         47.5/100
 
   Integration Simplicity Subscores
 
@@ -13,6 +13,7 @@
   Example Coverage         [░░░░░░░░░░░░░░░░░░░░] 0%
   Error Clarity            [████████████████████] 100%
   Dependency Clarity       [████████████████████] 100%
+  Discoverability          [████████████████████] 100%
 
   Agent Readiness Subscores
 
@@ -23,14 +24,15 @@
   Identifier Clarity       [█████████████░░░░░░░] 67%
   Dependency Clarity       [████████████████████] 100%
   Polymorphism Clarity     [████████████████████] 100%
+  Discoverability          [████████████████████] 100%
 
   Raw Metrics Summary
 
   Total operations: 2
-  Parameters/operation:   avg 1.0  median 1.0
-  Schema depth:           avg 1.5  median 1.5
-  Polymorphism/operation: avg 0.0  median 0.0
-  Properties/operation:   avg 2.0  median 2.0
+  Parameters/operation:      avg    1.0  median    1.0  min     0  max     2
+  Schema depth:              avg    1.5  median    1.5  min     1  max     2
+  Polymorphism/operation:    avg    0.0  median    0.0  min     0  max     0
+  Properties/operation:      avg    2.0  median    2.0  min     2  max     2
   Operations with request examples: 0/2 (0%)
   Operations with response examples: 0/2 (0%)
   Operations with description: 0/2 (0%)
diff --git a/tests/e2e/score/score-stylish/snapshot.txt b/tests/e2e/score/score-stylish/snapshot.txt
index 899c1f360f..b01965e05b 100644
--- a/tests/e2e/score/score-stylish/snapshot.txt
+++ b/tests/e2e/score/score-stylish/snapshot.txt
@@ -1,8 +1,8 @@
 
   Scores
 
-  Integration Simplicity:  83.0/100
-  Agent Readiness:         86.6/100
+  Integration Simplicity:  86.2/100
+  Agent Readiness:         90.2/100
 
   Integration Simplicity Subscores
 
@@ -13,6 +13,7 @@
   Example Coverage         [██████████████████░░] 88%
   Error Clarity            [████████████████████] 100%
   Dependency Clarity       [███████████████░░░░░] 73%
+  Discoverability          [████████████████████] 99%
 
   Agent Readiness Subscores
 
@@ -23,14 +24,15 @@
   Identifier Clarity       [████████████████████] 100%
   Dependency Clarity       [███████████████░░░░░] 73%
   Polymorphism Clarity     [████████████████████] 100%
+  Discoverability          [████████████████████] 99%
 
   Raw Metrics Summary
 
   Total operations: 8
-  Parameters/operation:   avg 1.4  median 1.0
-  Schema depth:           avg 1.6  median 2.0
-  Polymorphism/operation: avg 0.0  median 0.0
-  Properties/operation:   avg 4.4  median 6.0
+  Parameters/operation:      avg    1.4  median    1.0  min     0  max     4
+  Schema depth:              avg    1.6  median    2.0  min     0  max     3
+  Polymorphism/operation:    avg    0.0  median    0.0  min     0  max     0
+  Properties/operation:      avg    4.4  median    6.0  min     0  max     6
   Operations with request examples: 3/8 (38%)
   Operations with response examples: 7/8 (88%)
   Operations with description: 8/8 (100%)

From dbcdb86c4a1bb58dcb5af33a2b17ebe436346e71 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Fri, 27 Mar 2026 05:45:56 -0500
Subject: [PATCH 15/22] chore: address PR review feedback

- Use isPlainObject from openapi-core for schema cycle detection
  instead of raw typeof checks that match arrays
- Remove formatter unit tests in favor of e2e snapshot coverage
- Clarify makeScores() purpose in hotspot tests

Made-with: Cursor
---
 .../score/__tests__/formatters.test.ts        | 165 ------------------
 .../commands/score/__tests__/hotspots.test.ts |   1 +
 .../cli/src/commands/score/collect-metrics.ts |  10 +-
 3 files changed, 6 insertions(+), 170 deletions(-)
 delete mode 100644 packages/cli/src/commands/score/__tests__/formatters.test.ts

diff --git a/packages/cli/src/commands/score/__tests__/formatters.test.ts b/packages/cli/src/commands/score/__tests__/formatters.test.ts
deleted file mode 100644
index fc3611a491..0000000000
--- a/packages/cli/src/commands/score/__tests__/formatters.test.ts
+++ /dev/null
@@ -1,165 +0,0 @@
-import { printScoreJson } from '../formatters/json.js';
-import { printScoreStylish } from '../formatters/stylish.js';
-import type { ScoreResult } from '../types.js';
-
-vi.mock('@redocly/openapi-core', () => ({
-  logger: { output: vi.fn() },
-}));
-
-import { logger } from '@redocly/openapi-core';
-const mockOutput = vi.mocked(logger.output);
-
-const RESULT: ScoreResult = {
-  integrationSimplicity: 75,
-  agentReadiness: 60,
-  discoverability: 0.95,
-  integrationSubscores: {
-    parameterSimplicity: 0.8,
-    schemaSimplicity: 0.7,
-    documentationQuality: 0.9,
-    constraintClarity: 0.5,
-    exampleCoverage: 0.6,
-    errorClarity: 1.0,
-    dependencyClarity: 0.8,
-  },
-  agentSubscores: {
-    documentationQuality: 0.9,
-    constraintClarity: 0.5,
-    exampleCoverage: 0.6,
-    errorClarity: 1.0,
-    identifierClarity: 0.8,
-    dependencyClarity: 0.8,
-    polymorphismClarity: 1.0,
-  },
-  rawMetrics: {
-    operationCount: 2,
-    operations: new Map([
-      [
-        'getItems',
-        {
-          path: '/items',
-          method: 'get',
-          operationId: 'getItems',
-          parameterCount: 2,
-          requiredParameterCount: 0,
-          paramsWithDescription: 1,
-          requestBodyPresent: false,
-          topLevelWritableFieldCount: 0,
-          maxRequestSchemaDepth: 0,
-          maxResponseSchemaDepth: 2,
-          polymorphismCount: 0,
-          anyOfCount: 0,
-          hasDiscriminator: false,
-          propertyCount: 3,
-          operationDescriptionPresent: true,
-          schemaPropertiesWithDescription: 2,
-          totalSchemaProperties: 3,
-          constraintCount: 1,
-          requestExamplePresent: false,
-          responseExamplePresent: true,
-          structuredErrorResponseCount: 1,
-          totalErrorResponses: 1,
-          ambiguousIdentifierCount: 0,
-          refsUsed: new Set(),
-        },
-      ],
-      [
-        'createItem',
-        {
-          path: '/items',
-          method: 'post',
-          operationId: 'createItem',
-          parameterCount: 0,
-          requiredParameterCount: 0,
-          paramsWithDescription: 0,
-          requestBodyPresent: true,
-          topLevelWritableFieldCount: 3,
-          maxRequestSchemaDepth: 1,
-          maxResponseSchemaDepth: 1,
-          polymorphismCount: 0,
-          anyOfCount: 0,
-          hasDiscriminator: false,
-          propertyCount: 5,
-          operationDescriptionPresent: false,
-          schemaPropertiesWithDescription: 2,
-          totalSchemaProperties: 5,
-          constraintCount: 2,
-          requestExamplePresent: true,
-          responseExamplePresent: true,
-          structuredErrorResponseCount: 1,
-          totalErrorResponses: 1,
-          ambiguousIdentifierCount: 0,
-          refsUsed: new Set(),
-        },
-      ],
-    ]),
-  },
-  hotspots: [
-    {
-      path: '/items',
-      method: 'post',
-      operationId: 'createItem',
-      integrationSimplicityScore: 65,
-      agentReadinessScore: 55,
-      reasons: ['Missing operation description'],
-    },
-  ],
-  operationScores: new Map(),
-  dependencyDepths: new Map(),
-};
-
-function getStylishOutput(result: ScoreResult): string {
-  mockOutput.mockClear();
-  printScoreStylish(result);
-  return mockOutput.mock.calls.map(([s]: [string]) => s).join('');
-}
-
-describe('printScoreStylish', () => {
-  it('outputs scores, subscores, metrics, and hotspots', () => {
-    const output = getStylishOutput(RESULT);
-    expect(output).toContain('Integration Simplicity');
-    expect(output).toContain('Agent Readiness');
-    expect(output).toContain('Parameter Simplicity');
-    expect(output).toContain('Total operations: 2');
-    expect(output).toContain('POST /items');
-    expect(output).toContain('Missing operation description');
-  });
-
-  it('handles zero operations gracefully', () => {
-    const output = getStylishOutput({
-      ...RESULT,
-      rawMetrics: { operationCount: 0, operations: new Map() },
-      hotspots: [],
-    });
-    expect(output).toContain('Total operations: 0');
-    expect(output).toContain('No hotspot operations found');
-  });
-});
-
-describe('printScoreJson', () => {
-  it('outputs valid JSON with all sections', () => {
-    mockOutput.mockClear();
-    printScoreJson(RESULT);
-    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
-
-    expect(parsed.integrationSimplicity).toBe(75);
-    expect(parsed.agentReadiness).toBe(60);
-    expect(parsed.integrationSubscores.parameterSimplicity).toBe(0.8);
-    expect(parsed.agentSubscores.polymorphismClarity).toBe(1.0);
-    expect(parsed.rawMetrics.operations.getItems.path).toBe('/items');
-    expect(parsed.hotspots[0].reasons).toContain('Missing operation description');
-  });
-
-  it('serializes Maps as plain objects', () => {
-    mockOutput.mockClear();
-    printScoreJson({
-      ...RESULT,
-      dependencyDepths: new Map([
-        ['opA', 2],
-        ['opB', 0],
-      ]),
-    });
-    const parsed = JSON.parse(mockOutput.mock.calls[0][0]);
-    expect(parsed.dependencyDepths).toEqual({ opA: 2, opB: 0 });
-  });
-});
diff --git a/packages/cli/src/commands/score/__tests__/hotspots.test.ts b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
index e85c373b01..0f1f5556e4 100644
--- a/packages/cli/src/commands/score/__tests__/hotspots.test.ts
+++ b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
@@ -31,6 +31,7 @@ function makeMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetric
   };
 }
 
+/** Baseline "no issues" operation scores — all subscores at 100%. */
 function makeScores(overrides: Partial<OperationScores> = {}): OperationScores {
   return {
     integrationSimplicity: 80,
diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index 2ed6df95c0..f26a241ca4 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -6,6 +6,7 @@ import {
   resolveDocument,
   BaseResolver,
   Source,
+  isPlainObject,
   type Document,
   type SpecVersion,
   type WalkContext,
@@ -204,15 +205,14 @@ export function collectMetrics({
       resolved = resolveJsonPointer(document.parsed, ref) ?? schemaNode;
     }
 
-    if (resolved && typeof resolved === 'object' && computing.has(resolved)) {
+    if (isPlainObject(resolved) && computing.has(resolved)) {
       return { ...emptyStats };
     }
-    if (resolved && typeof resolved === 'object') {
+    if (isPlainObject(resolved)) {
       computing.add(resolved);
     }
 
-    const stripped =
-      resolved && typeof resolved === 'object' ? removedComposition.get(resolved) : undefined;
+    const stripped = isPlainObject(resolved) ? removedComposition.get(resolved) : undefined;
 
     const oneOfBranches = resolved?.oneOf ?? stripped?.oneOf;
     const anyOfBranches = resolved?.anyOf ?? stripped?.anyOf;
@@ -296,7 +296,7 @@ export function collectMetrics({
       result = walkSchemaRaw(schemaNode, debug);
     }
 
-    if (resolved && typeof resolved === 'object') {
+    if (isPlainObject(resolved)) {
       computing.delete(resolved);
     }
     if (ref && !debug) {

From 4e5301fb0847d9b95e86d76dd9782ad30918660e Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Wed, 1 Apr 2026 16:52:47 -0500
Subject: [PATCH 16/22] chore: address tatomyr review feedback (round 3)

- Add experimental admonition to score command docs
- Remove --config from usage examples
- Remove redundant mockClear and process.exitCode in tests
- Simplify JSON formatter by using spread instead of manual field mapping
- Use isRef from openapi-core for $ref detection in collect-metrics
- Use isPlainObject and isNotEmptyObject from openapi-core in document-metrics
- Replace != null with Array.isArray for discriminatorRefs check
- Remove unnecessary non-null assertions on discriminatorRefs
- Lower branch coverage threshold to 70% per reviewer guidance

Made-with: Cursor
---
 docs/@v2/commands/score.md                    |  9 ++--
 .../commands/score/__tests__/index.test.ts    |  2 -
 .../cli/src/commands/score/collect-metrics.ts | 21 ++++-----
 .../score/collectors/document-metrics.ts      |  7 +--
 .../cli/src/commands/score/formatters/json.ts | 44 +++----------------
 vitest.config.ts                              |  4 +-
 6 files changed, 27 insertions(+), 60 deletions(-)

diff --git a/docs/@v2/commands/score.md b/docs/@v2/commands/score.md
index c4114daca6..ca2a109c1a 100644
--- a/docs/@v2/commands/score.md
+++ b/docs/@v2/commands/score.md
@@ -9,9 +9,10 @@ The `score` command analyzes an OpenAPI description and produces two composite s
 
 In addition to the top-level scores, the command reports normalized subscores, raw metrics for every operation, and a list of **hotspot operations** — the endpoints most likely to cause integration friction — along with human-readable explanations.
 
-{% admonition type="warning" name="OpenAPI 3.x only" %}
-The `score` command supports OpenAPI 3.0, 3.1, and 3.2 descriptions.
-OpenAPI 2.0 (Swagger) and AsyncAPI are not currently supported.
+{% admonition type="warning" name="Important" %}
+The `score` command is considered an experimental feature. This means it's still a work in progress and may go through major changes.
+
+The `score` command supports OpenAPI 3.x descriptions only.
 {% /admonition %}
 
 ### Metrics
@@ -60,7 +61,7 @@ The command identifies the operations with the lowest scores and provides reason
 
 ```bash
 redocly score <api>
-redocly score <api> [--format=<option>] [--config=<path>]
+redocly score <api> [--format=<option>]
 ```
 
 ## Options
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index caedb344ad..0cc141dc13 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -81,7 +81,6 @@ function createArgs(overrides: Partial<ScoreArgv> = {}) {
 
 describe('handleScore', () => {
   beforeEach(() => {
-    mockOutput.mockClear();
     mockedGetFallback.mockResolvedValue([{ path: 'test.yaml' }] as any);
     mockedBundle.mockResolvedValue({ bundle: { parsed: {} } } as any);
     mockedDetectSpec.mockReturnValue('oas3_0');
@@ -91,7 +90,6 @@ describe('handleScore', () => {
       metrics: makeDocumentMetrics(new Map([['listItems', makeTestMetrics()]])),
       debugLogs: [],
     });
-    process.exitCode = undefined;
   });
 
   it('should produce stylish output for a valid oas3 document', async () => {
diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index f26a241ca4..ad94db9421 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -7,6 +7,7 @@ import {
   BaseResolver,
   Source,
   isPlainObject,
+  isRef,
   type Document,
   type SpecVersion,
   type WalkContext,
@@ -194,8 +195,7 @@ export function collectMetrics({
 
   const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
     let resolved = schemaNode;
-    const ref: string | undefined =
-      schemaNode?.$ref && typeof schemaNode.$ref === 'string' ? schemaNode.$ref : undefined;
+    const ref: string | undefined = isRef(schemaNode) ? schemaNode.$ref : undefined;
 
     if (ref) {
       if (!debug) {
@@ -229,12 +229,13 @@ export function collectMetrics({
 
     const disc = resolved?.discriminator ?? stripped?.discriminator;
     const discriminatorRefs =
-      !polyKeyword && disc?.mapping
-        ? (Object.values(disc.mapping) as string[])
-            .filter((v) => typeof v === 'string' && v.startsWith('#/'))
+      !polyKeyword && isPlainObject(disc?.mapping)
+        ? Object.values(disc.mapping)
+            .filter((v): v is string => typeof v === 'string' && v.startsWith('#/'))
             .map((v) => ({ $ref: v }))
         : null;
-    const hasDiscriminatorBranches = discriminatorRefs != null && discriminatorRefs.length > 0;
+    const hasDiscriminatorBranches =
+      Array.isArray(discriminatorRefs) && discriminatorRefs.length > 0;
 
     let result: SchemaStats;
 
@@ -264,16 +265,16 @@ export function collectMetrics({
       if (hasDiscriminatorBranches) {
         delete parentOnly.discriminator;
 
-        let maxBranch = walkSchema(discriminatorRefs![0], debug);
-        for (let i = 1; i < discriminatorRefs!.length; i++) {
-          const branchStats = walkSchema(discriminatorRefs![i], debug);
+        let maxBranch = walkSchema(discriminatorRefs[0], debug);
+        for (let i = 1; i < discriminatorRefs.length; i++) {
+          const branchStats = walkSchema(discriminatorRefs[i], debug);
           if (branchStats.propertyCount > maxBranch.propertyCount) {
             maxBranch = branchStats;
           }
         }
         discStats = {
           ...maxBranch,
-          polymorphismCount: maxBranch.polymorphismCount + discriminatorRefs!.length,
+          polymorphismCount: maxBranch.polymorphismCount + discriminatorRefs.length,
           hasDiscriminator: true,
         };
       }
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
index 2b020086ed..4a3d3611f3 100644
--- a/packages/cli/src/commands/score/collectors/document-metrics.ts
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -1,3 +1,4 @@
+import { isNotEmptyObject, isPlainObject } from '@redocly/openapi-core';
 import type {
   Oas3Visitor,
   UserContext,
@@ -130,7 +131,7 @@ export function createSchemaMetricVisitor(state: SchemaWalkState): Oas3Visitor {
         }
 
         const localPropertyNames: string[] = [];
-        if (schema.properties && typeof schema.properties === 'object') {
+        if (isPlainObject(schema.properties)) {
           const props = Object.entries(schema.properties) as [string, any][];
           state.totalSchemaProperties += props.length;
           state.propertyCount += props.length;
@@ -486,8 +487,8 @@ function mergeParameters(
 
 function hasExample(mediaType: { example?: unknown; examples?: Record<string, unknown> }): boolean {
   if (mediaType.example !== undefined) return true;
-  if (mediaType.examples && typeof mediaType.examples === 'object') {
-    return Object.keys(mediaType.examples).length > 0;
+  if (isNotEmptyObject(mediaType.examples)) {
+    return true;
   }
   return false;
 }
diff --git a/packages/cli/src/commands/score/formatters/json.ts b/packages/cli/src/commands/score/formatters/json.ts
index 57cda63c80..b827ae0648 100644
--- a/packages/cli/src/commands/score/formatters/json.ts
+++ b/packages/cli/src/commands/score/formatters/json.ts
@@ -12,47 +12,13 @@ export function printScoreJson(result: ScoreResult): void {
     rawMetrics: {
       operationCount: result.rawMetrics.operationCount,
       operations: Object.fromEntries(
-        Array.from(result.rawMetrics.operations.entries()).map(([key, m]) => [
-          key,
-          {
-            path: m.path,
-            method: m.method,
-            operationId: m.operationId,
-            parameterCount: m.parameterCount,
-            requiredParameterCount: m.requiredParameterCount,
-            paramsWithDescription: m.paramsWithDescription,
-            requestBodyPresent: m.requestBodyPresent,
-            topLevelWritableFieldCount: m.topLevelWritableFieldCount,
-            maxRequestSchemaDepth: m.maxRequestSchemaDepth,
-            maxResponseSchemaDepth: m.maxResponseSchemaDepth,
-            polymorphismCount: m.polymorphismCount,
-            anyOfCount: m.anyOfCount,
-            hasDiscriminator: m.hasDiscriminator,
-            propertyCount: m.propertyCount,
-            operationDescriptionPresent: m.operationDescriptionPresent,
-            schemaPropertiesWithDescription: m.schemaPropertiesWithDescription,
-            totalSchemaProperties: m.totalSchemaProperties,
-            constraintCount: m.constraintCount,
-            requestExamplePresent: m.requestExamplePresent,
-            responseExamplePresent: m.responseExamplePresent,
-            structuredErrorResponseCount: m.structuredErrorResponseCount,
-            totalErrorResponses: m.totalErrorResponses,
-            ambiguousIdentifierCount: m.ambiguousIdentifierCount,
-          },
-        ])
+        Array.from(result.rawMetrics.operations.entries()).map(([key, m]) => {
+          const { refsUsed: _, ...rest } = m;
+          return [key, rest];
+        })
       ),
     },
-    operationScores: Object.fromEntries(
-      Array.from(result.operationScores.entries()).map(([key, s]) => [
-        key,
-        {
-          integrationSimplicity: s.integrationSimplicity,
-          agentReadiness: s.agentReadiness,
-          integrationSubscores: s.integrationSubscores,
-          agentSubscores: s.agentSubscores,
-        },
-      ])
-    ),
+    operationScores: Object.fromEntries(result.operationScores),
     dependencyDepths: Object.fromEntries(result.dependencyDepths),
     hotspots: result.hotspots,
   };
diff --git a/vitest.config.ts b/vitest.config.ts
index b24d24a5b7..778958cbc2 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -22,8 +22,8 @@ const configExtension: { [key: string]: ViteUserConfig } = {
         thresholds: {
           lines: 79,
           functions: 82,
-          statements: 79,
-          branches: 71,
+          statements: 78,
+          branches: 70,
         },
       },
     },

From 916b03a6a3b0eb0b9eb3deeeda399a050252d8d1 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Thu, 2 Apr 2026 08:53:21 -0500
Subject: [PATCH 17/22] fix: address PR review feedback and bugbot findings

- Fix duplicate import from @redocly/openapi-core (CI lint error)
- Propagate hasDiscriminator flag for oneOf/anyOf + discriminator schemas
- Prevent structured error response double-counting per media type
- Keep totalSchemaProperties and schemaPropertiesWithDescription paired
  from the same schema to avoid misleading documentation quality ratios
- Wrap composition stripping in try/finally to guarantee restoration
- Export isMappingRef from openapi-core and use in collect-metrics
- Rename bfsMaxDepth to computeLongestBfsPath for clarity

Made-with: Cursor
---
 .../cli/src/commands/score/collect-metrics.ts | 372 +++++++++---------
 .../score/collectors/dependency-graph.ts      |   4 +-
 .../score/collectors/document-metrics.ts      |  44 ++-
 packages/core/src/index.ts                    |   1 +
 4 files changed, 216 insertions(+), 205 deletions(-)

diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index ad94db9421..1fafe60e2c 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -8,6 +8,7 @@ import {
   Source,
   isPlainObject,
   isRef,
+  isMappingRef,
   type Document,
   type SpecVersion,
   type WalkContext,
@@ -122,213 +123,216 @@ export function collectMetrics({
 }: CollectMetricsOptions): CollectMetricsResult {
   const removedComposition = stripCompositionKeywords(document.parsed);
 
-  const schemaWalkState = createSchemaWalkState();
-  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
-  const normalizedSchemaVisitors = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor as any }],
-    types
-  );
-
-  const walkSchemaRaw = (schemaNode: any, debug: boolean): SchemaStats => {
-    resetSchemaWalkState(schemaWalkState);
-    if (debug) schemaWalkState.debugEntries = [];
-    walkDocument({
-      document: { ...document, parsed: schemaNode },
-      rootType: types.Schema,
-      normalizedVisitors: normalizedSchemaVisitors,
-      resolvedRefMap,
-      ctx,
-    });
-    return {
-      maxDepth: schemaWalkState.maxDepth,
-      polymorphismCount: schemaWalkState.polymorphismCount,
-      anyOfCount: schemaWalkState.anyOfCount,
-      hasDiscriminator: schemaWalkState.hasDiscriminator,
-      propertyCount: schemaWalkState.propertyCount,
-      totalSchemaProperties: schemaWalkState.totalSchemaProperties,
-      schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
-      constraintCount: schemaWalkState.constraintCount,
-      hasPropertyExamples: schemaWalkState.hasPropertyExamples,
-      writableTopLevelFields: schemaWalkState.writableTopLevelFields,
-      refsUsed: [...schemaWalkState.refsUsed],
-      debugEntries: debug ? (schemaWalkState.debugEntries ?? undefined) : undefined,
+  try {
+    const schemaWalkState = createSchemaWalkState();
+    const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
+    const normalizedSchemaVisitors = normalizeVisitors(
+      [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor as any }],
+      types
+    );
+
+    const walkSchemaRaw = (schemaNode: any, debug: boolean): SchemaStats => {
+      resetSchemaWalkState(schemaWalkState);
+      if (debug) schemaWalkState.debugEntries = [];
+      walkDocument({
+        document: { ...document, parsed: schemaNode },
+        rootType: types.Schema,
+        normalizedVisitors: normalizedSchemaVisitors,
+        resolvedRefMap,
+        ctx,
+      });
+      return {
+        maxDepth: schemaWalkState.maxDepth,
+        polymorphismCount: schemaWalkState.polymorphismCount,
+        anyOfCount: schemaWalkState.anyOfCount,
+        hasDiscriminator: schemaWalkState.hasDiscriminator,
+        propertyCount: schemaWalkState.propertyCount,
+        totalSchemaProperties: schemaWalkState.totalSchemaProperties,
+        schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
+        constraintCount: schemaWalkState.constraintCount,
+        hasPropertyExamples: schemaWalkState.hasPropertyExamples,
+        writableTopLevelFields: schemaWalkState.writableTopLevelFields,
+        refsUsed: [...schemaWalkState.refsUsed],
+        debugEntries: debug ? (schemaWalkState.debugEntries ?? undefined) : undefined,
+      };
     };
-  };
-
-  const schemaCache = new Map<string, SchemaStats>();
-  const computing = new WeakSet<object>();
-
-  const emptyStats: SchemaStats = {
-    maxDepth: 0,
-    polymorphismCount: 0,
-    anyOfCount: 0,
-    hasDiscriminator: false,
-    propertyCount: 0,
-    totalSchemaProperties: 0,
-    schemaPropertiesWithDescription: 0,
-    constraintCount: 0,
-    hasPropertyExamples: false,
-    writableTopLevelFields: 0,
-    refsUsed: [],
-  };
-
-  function addStats(a: SchemaStats, b: SchemaStats): SchemaStats {
-    return {
-      maxDepth: Math.max(a.maxDepth, b.maxDepth),
-      polymorphismCount: a.polymorphismCount + b.polymorphismCount,
-      anyOfCount: a.anyOfCount + b.anyOfCount,
-      hasDiscriminator: a.hasDiscriminator || b.hasDiscriminator,
-      propertyCount: a.propertyCount + b.propertyCount,
-      totalSchemaProperties: a.totalSchemaProperties + b.totalSchemaProperties,
-      schemaPropertiesWithDescription:
-        a.schemaPropertiesWithDescription + b.schemaPropertiesWithDescription,
-      constraintCount: a.constraintCount + b.constraintCount,
-      hasPropertyExamples: a.hasPropertyExamples || b.hasPropertyExamples,
-      writableTopLevelFields: a.writableTopLevelFields + b.writableTopLevelFields,
-      refsUsed: [...a.refsUsed, ...b.refsUsed],
-      debugEntries:
-        a.debugEntries || b.debugEntries
-          ? [...(a.debugEntries ?? []), ...(b.debugEntries ?? [])]
-          : undefined,
-    };
-  }
 
-  const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
-    let resolved = schemaNode;
-    const ref: string | undefined = isRef(schemaNode) ? schemaNode.$ref : undefined;
+    const schemaCache = new Map<string, SchemaStats>();
+    const computing = new WeakSet<object>();
+
+    const emptyStats: SchemaStats = {
+      maxDepth: 0,
+      polymorphismCount: 0,
+      anyOfCount: 0,
+      hasDiscriminator: false,
+      propertyCount: 0,
+      totalSchemaProperties: 0,
+      schemaPropertiesWithDescription: 0,
+      constraintCount: 0,
+      hasPropertyExamples: false,
+      writableTopLevelFields: 0,
+      refsUsed: [],
+    };
 
-    if (ref) {
-      if (!debug) {
-        const cached = schemaCache.get(ref);
-        if (cached) return cached;
-      }
-      resolved = resolveJsonPointer(document.parsed, ref) ?? schemaNode;
+    function addStats(a: SchemaStats, b: SchemaStats): SchemaStats {
+      return {
+        maxDepth: Math.max(a.maxDepth, b.maxDepth),
+        polymorphismCount: a.polymorphismCount + b.polymorphismCount,
+        anyOfCount: a.anyOfCount + b.anyOfCount,
+        hasDiscriminator: a.hasDiscriminator || b.hasDiscriminator,
+        propertyCount: a.propertyCount + b.propertyCount,
+        totalSchemaProperties: a.totalSchemaProperties + b.totalSchemaProperties,
+        schemaPropertiesWithDescription:
+          a.schemaPropertiesWithDescription + b.schemaPropertiesWithDescription,
+        constraintCount: a.constraintCount + b.constraintCount,
+        hasPropertyExamples: a.hasPropertyExamples || b.hasPropertyExamples,
+        writableTopLevelFields: a.writableTopLevelFields + b.writableTopLevelFields,
+        refsUsed: [...a.refsUsed, ...b.refsUsed],
+        debugEntries:
+          a.debugEntries || b.debugEntries
+            ? [...(a.debugEntries ?? []), ...(b.debugEntries ?? [])]
+            : undefined,
+      };
     }
 
-    if (isPlainObject(resolved) && computing.has(resolved)) {
-      return { ...emptyStats };
-    }
-    if (isPlainObject(resolved)) {
-      computing.add(resolved);
-    }
+    const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
+      let resolved = schemaNode;
+      const ref: string | undefined = isRef(schemaNode) ? schemaNode.$ref : undefined;
+
+      if (ref) {
+        if (!debug) {
+          const cached = schemaCache.get(ref);
+          if (cached) return cached;
+        }
+        resolved = resolveJsonPointer(document.parsed, ref) ?? schemaNode;
+      }
 
-    const stripped = isPlainObject(resolved) ? removedComposition.get(resolved) : undefined;
+      if (isPlainObject(resolved) && computing.has(resolved)) {
+        return { ...emptyStats };
+      }
+      if (isPlainObject(resolved)) {
+        computing.add(resolved);
+      }
 
-    const oneOfBranches = resolved?.oneOf ?? stripped?.oneOf;
-    const anyOfBranches = resolved?.anyOf ?? stripped?.anyOf;
-    const polyKeyword: 'oneOf' | 'anyOf' | null =
-      Array.isArray(oneOfBranches) && oneOfBranches.length > 1
-        ? 'oneOf'
-        : Array.isArray(anyOfBranches) && anyOfBranches.length > 1
-          ? 'anyOf'
+      const stripped = isPlainObject(resolved) ? removedComposition.get(resolved) : undefined;
+
+      const oneOfBranches = resolved?.oneOf ?? stripped?.oneOf;
+      const anyOfBranches = resolved?.anyOf ?? stripped?.anyOf;
+      const polyKeyword: 'oneOf' | 'anyOf' | null =
+        Array.isArray(oneOfBranches) && oneOfBranches.length > 1
+          ? 'oneOf'
+          : Array.isArray(anyOfBranches) && anyOfBranches.length > 1
+            ? 'anyOf'
+            : null;
+      const polyBranches: any[] | null =
+        polyKeyword === 'oneOf' ? oneOfBranches : polyKeyword === 'anyOf' ? anyOfBranches : null;
+
+      const hasAllOf = Array.isArray(resolved?.allOf) && resolved.allOf.length > 0;
+
+      const disc = resolved?.discriminator ?? stripped?.discriminator;
+      const discriminatorRefs =
+        !polyKeyword && isPlainObject(disc?.mapping)
+          ? Object.values(disc.mapping)
+              .filter((v): v is string => typeof v === 'string' && isMappingRef(v))
+              .map((v) => ({ $ref: v }))
           : null;
-    const polyBranches: any[] | null =
-      polyKeyword === 'oneOf' ? oneOfBranches : polyKeyword === 'anyOf' ? anyOfBranches : null;
-
-    const hasAllOf = Array.isArray(resolved?.allOf) && resolved.allOf.length > 0;
-
-    const disc = resolved?.discriminator ?? stripped?.discriminator;
-    const discriminatorRefs =
-      !polyKeyword && isPlainObject(disc?.mapping)
-        ? Object.values(disc.mapping)
-            .filter((v): v is string => typeof v === 'string' && v.startsWith('#/'))
-            .map((v) => ({ $ref: v }))
-        : null;
-    const hasDiscriminatorBranches =
-      Array.isArray(discriminatorRefs) && discriminatorRefs.length > 0;
-
-    let result: SchemaStats;
-
-    if (polyKeyword || hasAllOf || hasDiscriminatorBranches) {
-      const parentOnly = { ...resolved };
-
-      let polyStats: SchemaStats | null = null;
-      if (polyKeyword && polyBranches) {
-        delete parentOnly[polyKeyword];
-        delete parentOnly.discriminator;
-
-        let maxBranch = walkSchema(polyBranches[0], debug);
-        for (let i = 1; i < polyBranches.length; i++) {
-          const branchStats = walkSchema(polyBranches[i], debug);
-          if (branchStats.propertyCount > maxBranch.propertyCount) {
-            maxBranch = branchStats;
+      const hasDiscriminatorBranches =
+        Array.isArray(discriminatorRefs) && discriminatorRefs.length > 0;
+
+      let result: SchemaStats;
+
+      if (polyKeyword || hasAllOf || hasDiscriminatorBranches) {
+        const parentOnly = { ...resolved };
+
+        let polyStats: SchemaStats | null = null;
+        if (polyKeyword && polyBranches) {
+          delete parentOnly[polyKeyword];
+          delete parentOnly.discriminator;
+
+          let maxBranch = walkSchema(polyBranches[0], debug);
+          for (let i = 1; i < polyBranches.length; i++) {
+            const branchStats = walkSchema(polyBranches[i], debug);
+            if (branchStats.propertyCount > maxBranch.propertyCount) {
+              maxBranch = branchStats;
+            }
           }
+          polyStats = {
+            ...maxBranch,
+            polymorphismCount: maxBranch.polymorphismCount + polyBranches.length,
+            anyOfCount: maxBranch.anyOfCount + (polyKeyword === 'anyOf' ? polyBranches.length : 0),
+            hasDiscriminator: maxBranch.hasDiscriminator || !!disc,
+          };
         }
-        polyStats = {
-          ...maxBranch,
-          polymorphismCount: maxBranch.polymorphismCount + polyBranches.length,
-          anyOfCount: maxBranch.anyOfCount + (polyKeyword === 'anyOf' ? polyBranches.length : 0),
-        };
-      }
 
-      let discStats: SchemaStats | null = null;
-      if (hasDiscriminatorBranches) {
-        delete parentOnly.discriminator;
+        let discStats: SchemaStats | null = null;
+        if (hasDiscriminatorBranches) {
+          delete parentOnly.discriminator;
 
-        let maxBranch = walkSchema(discriminatorRefs[0], debug);
-        for (let i = 1; i < discriminatorRefs.length; i++) {
-          const branchStats = walkSchema(discriminatorRefs[i], debug);
-          if (branchStats.propertyCount > maxBranch.propertyCount) {
-            maxBranch = branchStats;
+          let maxBranch = walkSchema(discriminatorRefs[0], debug);
+          for (let i = 1; i < discriminatorRefs.length; i++) {
+            const branchStats = walkSchema(discriminatorRefs[i], debug);
+            if (branchStats.propertyCount > maxBranch.propertyCount) {
+              maxBranch = branchStats;
+            }
           }
+          discStats = {
+            ...maxBranch,
+            polymorphismCount: maxBranch.polymorphismCount + discriminatorRefs.length,
+            hasDiscriminator: true,
+          };
         }
-        discStats = {
-          ...maxBranch,
-          polymorphismCount: maxBranch.polymorphismCount + discriminatorRefs.length,
-          hasDiscriminator: true,
-        };
-      }
 
-      let allOfStats: SchemaStats | null = null;
-      if (hasAllOf) {
-        delete parentOnly.allOf;
-        allOfStats = { ...emptyStats };
-        for (const member of resolved.allOf) {
-          allOfStats = addStats(allOfStats, walkSchema(member, debug));
+        let allOfStats: SchemaStats | null = null;
+        if (hasAllOf) {
+          delete parentOnly.allOf;
+          allOfStats = { ...emptyStats };
+          for (const member of resolved.allOf) {
+            allOfStats = addStats(allOfStats, walkSchema(member, debug));
+          }
         }
-      }
 
-      const parentStats = walkSchemaRaw(parentOnly, debug);
-      result = parentStats;
-      if (allOfStats) result = addStats(result, allOfStats);
-      if (polyStats) result = addStats(result, polyStats);
-      if (discStats) result = addStats(result, discStats);
-    } else {
-      result = walkSchemaRaw(schemaNode, debug);
-    }
+        const parentStats = walkSchemaRaw(parentOnly, debug);
+        result = parentStats;
+        if (allOfStats) result = addStats(result, allOfStats);
+        if (polyStats) result = addStats(result, polyStats);
+        if (discStats) result = addStats(result, discStats);
+      } else {
+        result = walkSchemaRaw(schemaNode, debug);
+      }
 
-    if (isPlainObject(resolved)) {
-      computing.delete(resolved);
-    }
-    if (ref && !debug) {
-      schemaCache.set(ref, result);
-    }
+      if (isPlainObject(resolved)) {
+        computing.delete(resolved);
+      }
+      if (ref && !debug) {
+        schemaCache.set(ref, result);
+      }
 
-    return result;
-  };
+      return result;
+    };
 
-  const accumulator = createScoreAccumulator(walkSchema, debugOperationId);
-  const scoreVisitor = createScoreVisitor(accumulator);
+    const accumulator = createScoreAccumulator(walkSchema, debugOperationId);
+    const scoreVisitor = createScoreVisitor(accumulator);
 
-  const normalizedVisitors = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
-    types
-  );
+    const normalizedVisitors = normalizeVisitors(
+      [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
+      types
+    );
 
-  walkDocument({
-    document,
-    rootType: types.Root,
-    normalizedVisitors,
-    resolvedRefMap,
-    ctx,
-  });
-
-  restoreCompositionKeywords(removedComposition);
+    walkDocument({
+      document,
+      rootType: types.Root,
+      normalizedVisitors,
+      resolvedRefMap,
+      ctx,
+    });
 
-  return {
-    metrics: getDocumentMetrics(accumulator),
-    debugLogs: accumulator.debugLogs,
-  };
+    return {
+      metrics: getDocumentMetrics(accumulator),
+      debugLogs: accumulator.debugLogs,
+    };
+  } finally {
+    restoreCompositionKeywords(removedComposition);
+  }
 }
 
 /**
diff --git a/packages/cli/src/commands/score/collectors/dependency-graph.ts b/packages/cli/src/commands/score/collectors/dependency-graph.ts
index 1842616941..a2fb84d5ed 100644
--- a/packages/cli/src/commands/score/collectors/dependency-graph.ts
+++ b/packages/cli/src/commands/score/collectors/dependency-graph.ts
@@ -41,14 +41,14 @@ export function computeDependencyDepths(
   const depths = new Map<string, number>();
 
   for (const opKey of operations.keys()) {
-    const depth = bfsMaxDepth(opKey, adjacency);
+    const depth = computeLongestBfsPath(opKey, adjacency);
     depths.set(opKey, depth);
   }
 
   return depths;
 }
 
-function bfsMaxDepth(start: string, adjacency: Map<string, Set<string>>): number {
+function computeLongestBfsPath(start: string, adjacency: Map<string, Set<string>>): number {
   const visited = new Set<string>([start]);
   let queue = [start];
   let depth = 0;
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
index 4a3d3611f3..eae13e4faa 100644
--- a/packages/cli/src/commands/score/collectors/document-metrics.ts
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -1,13 +1,14 @@
-import { isNotEmptyObject, isPlainObject } from '@redocly/openapi-core';
-import type {
-  Oas3Visitor,
-  UserContext,
-  Oas3PathItem,
-  Oas3Operation,
-  Oas3Parameter,
-  Oas3Schema,
-  Oas3_1Schema,
-  Referenced,
+import {
+  isNotEmptyObject,
+  isPlainObject,
+  type Oas3Visitor,
+  type UserContext,
+  type Oas3PathItem,
+  type Oas3Operation,
+  type Oas3Parameter,
+  type Oas3Schema,
+  type Oas3_1Schema,
+  type Referenced,
 } from '@redocly/openapi-core';
 
 import { AMBIGUOUS_PARAM_NAMES } from '../constants.js';
@@ -212,6 +213,7 @@ interface CurrentOperationContext {
   inRequestBody: boolean;
   inResponse: boolean;
   currentResponseCode: string;
+  errorStructuredCounted: boolean;
 
   refsUsed: Set<string>;
 }
@@ -278,6 +280,7 @@ function createOperationContext(
     inRequestBody: false,
     inResponse: false,
     currentResponseCode: '',
+    errorStructuredCounted: false,
 
     refsUsed: new Set(),
   };
@@ -334,11 +337,13 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
         const code = String(ctx.key);
         current.inResponse = true;
         current.currentResponseCode = code;
+        current.errorStructuredCounted = false;
 
         if (isErrorCode(code)) {
           current.totalErrorResponses++;
           if (!response.content && response.description) {
             current.structuredErrorResponseCount++;
+            current.errorStructuredCounted = true;
           }
         }
       },
@@ -359,8 +364,13 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
           if (current.inResponse) current.responseExamplePresent = true;
         }
 
-        if (current.inResponse && isErrorCode(current.currentResponseCode)) {
+        if (
+          current.inResponse &&
+          isErrorCode(current.currentResponseCode) &&
+          !current.errorStructuredCounted
+        ) {
           current.structuredErrorResponseCount++;
+          current.errorStructuredCounted = true;
         }
 
         if (mediaType.schema) {
@@ -372,14 +382,10 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
           const stats = accumulator.walkSchema(mediaType.schema, isDebugTarget);
 
           current.propertyCount = Math.max(current.propertyCount, stats.propertyCount);
-          current.totalSchemaProperties = Math.max(
-            current.totalSchemaProperties,
-            stats.totalSchemaProperties
-          );
-          current.schemaPropertiesWithDescription = Math.max(
-            current.schemaPropertiesWithDescription,
-            stats.schemaPropertiesWithDescription
-          );
+          if (stats.totalSchemaProperties > current.totalSchemaProperties) {
+            current.totalSchemaProperties = stats.totalSchemaProperties;
+            current.schemaPropertiesWithDescription = stats.schemaPropertiesWithDescription;
+          }
           current.constraintCount = Math.max(current.constraintCount, stats.constraintCount);
           current.polymorphismCount = Math.max(current.polymorphismCount, stats.polymorphismCount);
           current.anyOfCount = Math.max(current.anyOfCount, stats.anyOfCount);
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 6283dc1e48..15b4f7591f 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -57,6 +57,7 @@ export { parseYaml, stringifyYaml } from './js-yaml/index.js';
 export {
   unescapePointerFragment,
   isRef,
+  isMappingRef,
   isAbsoluteUrl,
   getDir,
   resolvePath,

From 6b9d0176a12aedf8671b5a03235984052e4eb492 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Thu, 2 Apr 2026 13:32:55 -0500
Subject: [PATCH 18/22] fix: address bugbot findings (round 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add allOf member count to polymorphismCount for parity with
  oneOf/anyOf branch counting
- Handle RFC 6901 JSON Pointer escaping (~0 → ~ and ~1 → /) in
  resolveJsonPointer
- Remove unused scores parameter from getHotspotReasons

Made-with: Cursor
---
 packages/cli/src/commands/score/collect-metrics.ts | 4 +++-
 packages/cli/src/commands/score/hotspots.ts        | 3 +--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index 1fafe60e2c..87b801ef33 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -28,7 +28,8 @@ function resolveJsonPointer(root: any, ref: string): any {
   if (!ref.startsWith('#/')) return undefined;
   let node = root;
   for (const segment of ref.slice(2).split('/')) {
-    node = node?.[decodeURIComponent(segment)];
+    const decoded = decodeURIComponent(segment).replace(/~1/g, '/').replace(/~0/g, '~');
+    node = node?.[decoded];
   }
   return node;
 }
@@ -289,6 +290,7 @@ export function collectMetrics({
           for (const member of resolved.allOf) {
             allOfStats = addStats(allOfStats, walkSchema(member, debug));
           }
+          allOfStats.polymorphismCount += resolved.allOf.length;
         }
 
         const parentStats = walkSchemaRaw(parentOnly, debug);
diff --git a/packages/cli/src/commands/score/hotspots.ts b/packages/cli/src/commands/score/hotspots.ts
index 6288ac3a27..9236d6d081 100644
--- a/packages/cli/src/commands/score/hotspots.ts
+++ b/packages/cli/src/commands/score/hotspots.ts
@@ -18,7 +18,7 @@ export function selectTopHotspots(
     const metrics = documentMetrics.operations.get(key);
     if (!metrics) continue;
 
-    const reasons = getHotspotReasons(metrics, scores, dependencyDepths.get(key) ?? 0, constants);
+    const reasons = getHotspotReasons(metrics, dependencyDepths.get(key) ?? 0, constants);
     if (reasons.length === 0) continue;
 
     entries.push({
@@ -58,7 +58,6 @@ function getHotspotReasons(
     paramsWithDescription: number;
     ambiguousIdentifierCount: number;
   },
-  scores: OperationScores,
   dependencyDepth: number,
   constants: ScoringConstants
 ): string[] {

From bd6d82af62945f7033fd900efb8edc3b3e7c7e2a Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Sat, 4 Apr 2026 07:55:38 -0500
Subject: [PATCH 19/22] refactor: consolidate Integration Simplicity and Agent
 Readiness into single score

Merge the two overlapping composite scores into a single "Agent Readiness"
score with all 9 subscores. This eliminates duplication in weights, scoring
functions, and output. Also addresses code review feedback: use
unescapePointerFragment, simplify resetSchemaWalkState via Object.assign,
consolidate SchemaStats into types.ts, remove collect() test wrapper, simplify
hasExample return, and use spread for walkSchemaRaw return.

Made-with: Cursor
---
 .changeset/add-score-command.md               |   2 +-
 docs/@v2/commands/score.md                    |  26 ++-
 .../score/__tests__/document-metrics.test.ts  |  44 +++--
 .../score/__tests__/example-coverage.test.ts  |  41 +----
 .../commands/score/__tests__/hotspots.test.ts |  17 +-
 .../commands/score/__tests__/index.test.ts    |   2 -
 .../commands/score/__tests__/scoring.test.ts  |  92 ++++------
 .../cli/src/commands/score/collect-metrics.ts |  33 +---
 .../score/collectors/document-metrics.ts      |  43 +----
 packages/cli/src/commands/score/constants.ts  |  27 +--
 .../cli/src/commands/score/formatters/json.ts |   4 +-
 .../src/commands/score/formatters/stylish.ts  |  41 ++---
 packages/cli/src/commands/score/hotspots.ts   |  23 +--
 packages/cli/src/commands/score/index.ts      |  12 +-
 packages/cli/src/commands/score/scoring.ts    | 163 ++++--------------
 packages/cli/src/commands/score/types.ts      |  61 +++----
 tests/e2e/score/score-json/snapshot.txt       | 127 +++-----------
 tests/e2e/score/score-minimal/snapshot.txt    |  18 +-
 tests/e2e/score/score-stylish/snapshot.txt    |  16 +-
 19 files changed, 213 insertions(+), 579 deletions(-)

diff --git a/.changeset/add-score-command.md b/.changeset/add-score-command.md
index 5187db8b6d..719b1cc008 100644
--- a/.changeset/add-score-command.md
+++ b/.changeset/add-score-command.md
@@ -2,5 +2,5 @@
 '@redocly/cli': minor
 ---
 
-Added new `score` command that analyzes OpenAPI 3.x descriptions and produces integration simplicity and AI agent readiness scores (0-100).
+Added new `score` command that analyzes OpenAPI 3.x descriptions and produces an AI Agent Readiness score (0-100).
 Reports normalized subscores, raw per-operation metrics, and top hotspot operations with human-readable explanations. Supports `--format=stylish` (default) and `--format=json` output.
diff --git a/docs/@v2/commands/score.md b/docs/@v2/commands/score.md
index ca2a109c1a..3de86cc191 100644
--- a/docs/@v2/commands/score.md
+++ b/docs/@v2/commands/score.md
@@ -2,12 +2,9 @@
 
 ## Introduction
 
-The `score` command analyzes an OpenAPI description and produces two composite scores:
+The `score` command analyzes an OpenAPI description and produces a composite **Agent Readiness** score (0–100) that measures how easy the API is to integrate and how usable it is by AI agents and LLM-based tooling. Higher is better.
 
-- **Integration Simplicity** (0–100): How easy is this API to integrate? Higher is better.
-- **Agent Readiness** (0–100): How usable is this API by AI agents and LLM-based tooling? Higher is better.
-
-In addition to the top-level scores, the command reports normalized subscores, raw metrics for every operation, and a list of **hotspot operations** — the endpoints most likely to cause integration friction — along with human-readable explanations.
+In addition to the top-level score, the command reports normalized subscores, raw metrics for every operation, and a list of **hotspot operations** — the endpoints most likely to cause integration friction — along with human-readable explanations.
 
 {% admonition type="warning" name="Important" %}
 The `score` command is considered an experimental feature. This means it's still a work in progress and may go through major changes.
@@ -38,13 +35,11 @@ The following raw metrics are collected per operation and aggregated across the
 
 ### Subscores
 
-Subscores are normalized to 0–1 and grouped into two categories:
-
-**Integration Simplicity subscores:** `parameterSimplicity`, `schemaSimplicity`, `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `dependencyClarity`, `discoverability`.
+The following subscores are normalized to 0–1 and combined into the composite Agent Readiness score:
 
-**Agent Readiness subscores:** `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `identifierClarity`, `dependencyClarity`, `polymorphismClarity`, `discoverability`.
+`parameterSimplicity`, `schemaSimplicity`, `documentationQuality`, `constraintClarity`, `exampleCoverage`, `errorClarity`, `dependencyClarity`, `identifierClarity`, `polymorphismClarity`, `discoverability`.
 
-The `discoverability` subscore reflects the total number of operations in the API. Larger APIs (approaching 1,000+ operations) receive a lower discoverability score because finding the right endpoint becomes harder for both humans and AI agents. This subscore is blended into both composite scores.
+The `discoverability` subscore reflects the total number of operations in the API. Larger APIs (approaching 1,000+ operations) receive a lower discoverability score because finding the right endpoint becomes harder for both humans and AI agents.
 
 ### Hotspots
 
@@ -96,10 +91,9 @@ The default output format shows a human-readable summary in your terminal:
 ```sh
   Scores
 
-  Integration Simplicity:  72.5/100
-  Agent Readiness:         68.3/100
+  Agent Readiness:  68.3/100
 
-  Integration Simplicity Subscores
+  Subscores
 
   Parameter Simplicity     [████████████████░░░░] 80%
   Schema Simplicity        [██████████████░░░░░░] 70%
@@ -108,18 +102,20 @@ The default output format shows a human-readable summary in your terminal:
   Example Coverage         [████████████████████] 100%
   Error Clarity            [████████████████░░░░] 80%
   Dependency Clarity       [██████████████████░░] 90%
+  Identifier Clarity       [████████████████████] 100%
+  Polymorphism Clarity     [████████████████████] 100%
   Discoverability          [████████████████████] 100%
 
   Top 3 Hotspot Operations
 
   POST /orders (createOrder)
-    Integration Simplicity: 45.2  Agent Readiness: 38.7
+    Agent Readiness: 38.7
     - High parameter count (12)
     - Deep schema nesting (depth 6)
     - Missing request and response examples
 
   PUT /orders/{id} (updateOrder)
-    Integration Simplicity: 52.1  Agent Readiness: 44.0
+    Agent Readiness: 44.0
     - Polymorphism (anyOf) without discriminator (3 anyOf)
     - No structured error responses (4xx/5xx)
 ```
diff --git a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
index c26d81a0e5..3e46515c4c 100644
--- a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
+++ b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
@@ -5,13 +5,9 @@ import { collectDocumentMetrics } from '../collect-metrics.js';
 
 const yaml = (source: string) => parseYaml(source) as Record<string, unknown>;
 
-async function collect(doc: Record<string, unknown>) {
-  return (await collectDocumentMetrics(doc)).metrics;
-}
-
 describe('collectDocumentMetrics', () => {
   it('returns zero operations for empty paths', async () => {
-    const result = await collect(
+    const { metrics } = await collectDocumentMetrics(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -20,12 +16,12 @@ describe('collectDocumentMetrics', () => {
         paths: {}
       `)
     );
-    expect(result.operationCount).toBe(0);
-    expect(result.operations.size).toBe(0);
+    expect(metrics.operationCount).toBe(0);
+    expect(metrics.operations.size).toBe(0);
   });
 
   it('counts operations, uses operationId as key or falls back to METHOD /path', async () => {
-    const result = await collect(
+    const { metrics } = await collectDocumentMetrics(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -50,14 +46,14 @@ describe('collectDocumentMetrics', () => {
                   description: OK
       `)
     );
-    expect(result.operationCount).toBe(3);
-    expect(result.operations.has('listItems')).toBe(true);
-    expect(result.operations.has('getItem')).toBe(true);
-    expect(result.operations.has('POST /items')).toBe(true);
+    expect(metrics.operationCount).toBe(3);
+    expect(metrics.operations.has('listItems')).toBe(true);
+    expect(metrics.operations.has('getItem')).toBe(true);
+    expect(metrics.operations.has('POST /items')).toBe(true);
   });
 
   it('counts parameters, resolves $refs, merges path-level params, and detects ambiguous names', async () => {
-    const result = await collect(
+    const { metrics } = await collectDocumentMetrics(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -88,7 +84,7 @@ describe('collectDocumentMetrics', () => {
       `)
     );
 
-    const op = result.operations.get('getItem')!;
+    const op = metrics.operations.get('getItem')!;
     expect(op.parameterCount).toBe(3);
     expect(op.requiredParameterCount).toBe(1);
     expect(op.paramsWithDescription).toBe(2);
@@ -96,7 +92,7 @@ describe('collectDocumentMetrics', () => {
   });
 
   it('detects request body with $ref schema, examples, constraints, and property descriptions', async () => {
-    const result = await collect(
+    const { metrics } = await collectDocumentMetrics(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -132,7 +128,7 @@ describe('collectDocumentMetrics', () => {
       `)
     );
 
-    const op = result.operations.get('createItem')!;
+    const op = metrics.operations.get('createItem')!;
     expect(op.requestBodyPresent).toBe(true);
     expect(op.requestExamplePresent).toBe(true);
     expect(op.propertyCount).toBe(2);
@@ -141,7 +137,7 @@ describe('collectDocumentMetrics', () => {
   });
 
   it('resolves response $refs, counts structured errors, and computes schema depth', async () => {
-    const result = await collect(
+    const { metrics } = await collectDocumentMetrics(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -186,7 +182,7 @@ describe('collectDocumentMetrics', () => {
       `)
     );
 
-    const op = result.operations.get('listItems')!;
+    const op = metrics.operations.get('listItems')!;
     expect(op.responseExamplePresent).toBe(true);
     expect(op.maxResponseSchemaDepth).toBe(3);
     expect(op.totalErrorResponses).toBe(3);
@@ -194,7 +190,7 @@ describe('collectDocumentMetrics', () => {
   });
 
   it('detects operation descriptions and tracks shared $ref usage across operations', async () => {
-    const result = await collect(
+    const { metrics } = await collectDocumentMetrics(
       yaml(outdent`
         openapi: 3.0.0
         info:
@@ -233,14 +229,14 @@ describe('collectDocumentMetrics', () => {
       `)
     );
 
-    expect(result.operations.get('listItems')!.operationDescriptionPresent).toBe(true);
-    expect(result.operations.get('createItem')!.operationDescriptionPresent).toBe(false);
-    expect(result.operations.get('listItems')!.refsUsed.has('#/components/schemas/Item')).toBe(
+    expect(metrics.operations.get('listItems')!.operationDescriptionPresent).toBe(true);
+    expect(metrics.operations.get('createItem')!.operationDescriptionPresent).toBe(false);
+    expect(metrics.operations.get('listItems')!.refsUsed.has('#/components/schemas/Item')).toBe(
       true
     );
-    expect(result.operations.get('createItem')!.refsUsed.has('#/components/schemas/Item')).toBe(
+    expect(metrics.operations.get('createItem')!.refsUsed.has('#/components/schemas/Item')).toBe(
       true
     );
-    expect(result.operations.get('listItems')!.responseExamplePresent).toBe(true);
+    expect(metrics.operations.get('listItems')!.responseExamplePresent).toBe(true);
   });
 });
diff --git a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
index 9483041ae5..9ead3002a9 100644
--- a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
+++ b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
@@ -1,10 +1,5 @@
 import { collectDocumentMetrics } from '../collect-metrics.js';
-import {
-  computeOperationIntegrationSubscores,
-  computeOperationAgentSubscores,
-  computeIntegrationSimplicity,
-  computeAgentReadiness,
-} from '../scoring.js';
+import { computeOperationSubscores, computeAgentReadiness } from '../scoring.js';
 
 async function collect(doc: Record<string, unknown>) {
   return (await collectDocumentMetrics(doc)).metrics;
@@ -62,7 +57,7 @@ describe('example coverage', () => {
     expect(opMetrics.requestExamplePresent).toBe(true);
     expect(opMetrics.responseExamplePresent).toBe(true);
 
-    const subscores = computeOperationIntegrationSubscores(opMetrics, 0);
+    const subscores = computeOperationSubscores(opMetrics, 0);
     expect(subscores.exampleCoverage).toBe(1);
   });
 
@@ -78,7 +73,7 @@ describe('example coverage', () => {
     expect(opMetrics.requestExamplePresent).toBe(false);
     expect(opMetrics.responseExamplePresent).toBe(true);
 
-    const subscores = computeOperationIntegrationSubscores(opMetrics, 0);
+    const subscores = computeOperationSubscores(opMetrics, 0);
     expect(subscores.exampleCoverage).toBe(0.5);
   });
 
@@ -91,34 +86,10 @@ describe('example coverage', () => {
     const metrics = await collect(doc);
     const opMetrics = metrics.operations.get('createItem')!;
 
-    const subscores = computeOperationIntegrationSubscores(opMetrics, 0);
+    const subscores = computeOperationSubscores(opMetrics, 0);
     expect(subscores.exampleCoverage).toBe(0);
   });
 
-  it('should affect integration simplicity score positively with examples', async () => {
-    const docWith = makeDocument({
-      requestExample: true,
-      responseExample: true,
-      hasRequestBody: true,
-    });
-    const docWithout = makeDocument({
-      requestExample: false,
-      responseExample: false,
-      hasRequestBody: true,
-    });
-
-    const metricsWithExamples = (await collect(docWith)).operations.get('createItem')!;
-    const metricsWithout = (await collect(docWithout)).operations.get('createItem')!;
-
-    const subWith = computeOperationIntegrationSubscores(metricsWithExamples, 0);
-    const subWithout = computeOperationIntegrationSubscores(metricsWithout, 0);
-
-    const scoreWith = computeIntegrationSimplicity(subWith);
-    const scoreWithout = computeIntegrationSimplicity(subWithout);
-
-    expect(scoreWith).toBeGreaterThan(scoreWithout);
-  });
-
   it('should affect agent readiness score positively with examples', async () => {
     const docWith = makeDocument({
       requestExample: true,
@@ -134,8 +105,8 @@ describe('example coverage', () => {
     const metricsWithExamples = (await collect(docWith)).operations.get('createItem')!;
     const metricsWithout = (await collect(docWithout)).operations.get('createItem')!;
 
-    const subWith = computeOperationAgentSubscores(metricsWithExamples, 0);
-    const subWithout = computeOperationAgentSubscores(metricsWithout, 0);
+    const subWith = computeOperationSubscores(metricsWithExamples, 0);
+    const subWithout = computeOperationSubscores(metricsWithout, 0);
 
     const scoreWith = computeAgentReadiness(subWith);
     const scoreWithout = computeAgentReadiness(subWithout);
diff --git a/packages/cli/src/commands/score/__tests__/hotspots.test.ts b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
index 0f1f5556e4..8a7d6efd33 100644
--- a/packages/cli/src/commands/score/__tests__/hotspots.test.ts
+++ b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
@@ -31,12 +31,10 @@ function makeMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetric
   };
 }
 
-/** Baseline "no issues" operation scores — all subscores at 100%. */
 function makeScores(overrides: Partial<OperationScores> = {}): OperationScores {
   return {
-    integrationSimplicity: 80,
     agentReadiness: 80,
-    integrationSubscores: {
+    subscores: {
       parameterSimplicity: 1,
       schemaSimplicity: 1,
       documentationQuality: 1,
@@ -44,14 +42,7 @@ function makeScores(overrides: Partial<OperationScores> = {}): OperationScores {
       exampleCoverage: 1,
       errorClarity: 1,
       dependencyClarity: 1,
-    },
-    agentSubscores: {
-      documentationQuality: 1,
-      constraintClarity: 1,
-      exampleCoverage: 1,
-      errorClarity: 1,
       identifierClarity: 1,
-      dependencyClarity: 1,
       polymorphismClarity: 1,
     },
     ...overrides,
@@ -244,7 +235,7 @@ describe('selectTopHotspots', () => {
     expect(result[0].reasons).toContain('Ambiguous identifiers (3)');
   });
 
-  it('sorts by reasons.length desc then by avg score asc', () => {
+  it('sorts by reasons.length desc then by agentReadinessScore asc', () => {
     const manyReasons = makeMetrics({
       parameterCount: 10,
       operationDescriptionPresent: false,
@@ -264,8 +255,8 @@ describe('selectTopHotspots', () => {
       ]),
     };
     const opScores = new Map([
-      ['opFewer', makeScores({ integrationSimplicity: 90, agentReadiness: 90 })],
-      ['opMany', makeScores({ integrationSimplicity: 90, agentReadiness: 90 })],
+      ['opFewer', makeScores({ agentReadiness: 90 })],
+      ['opMany', makeScores({ agentReadiness: 90 })],
     ]);
     const result = selectTopHotspots(
       docMetrics,
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index 0cc141dc13..a5a194f7c1 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -96,7 +96,6 @@ describe('handleScore', () => {
     await handleScore(createArgs());
 
     const output = mockOutput.mock.calls.map(([s]: [string]) => s).join('');
-    expect(output).toContain('Integration Simplicity');
     expect(output).toContain('Agent Readiness');
   });
 
@@ -105,7 +104,6 @@ describe('handleScore', () => {
 
     const output = mockOutput.mock.calls[0][0];
     const parsed = JSON.parse(output);
-    expect(parsed.integrationSimplicity).toBeDefined();
     expect(parsed.agentReadiness).toBeDefined();
     expect(parsed.rawMetrics.operationCount).toBe(1);
   });
diff --git a/packages/cli/src/commands/score/__tests__/scoring.test.ts b/packages/cli/src/commands/score/__tests__/scoring.test.ts
index 851345ddb9..658750d8c7 100644
--- a/packages/cli/src/commands/score/__tests__/scoring.test.ts
+++ b/packages/cli/src/commands/score/__tests__/scoring.test.ts
@@ -1,8 +1,6 @@
 import { DEFAULT_SCORING_CONSTANTS } from '../constants.js';
 import {
-  computeOperationIntegrationSubscores,
-  computeOperationAgentSubscores,
-  computeIntegrationSimplicity,
+  computeOperationSubscores,
   computeAgentReadiness,
   computeAllOperationScores,
   computeDiscoverability,
@@ -44,19 +42,19 @@ describe('scoring', () => {
   describe('depth normalization', () => {
     it('should give high schema simplicity for shallow schemas', () => {
       const metrics = makeBaseMetrics({ maxRequestSchemaDepth: 1, maxResponseSchemaDepth: 1 });
-      const subscores = computeOperationIntegrationSubscores(metrics, 0);
+      const subscores = computeOperationSubscores(metrics, 0);
       expect(subscores.schemaSimplicity).toBeGreaterThan(0.8);
     });
 
     it('should give lower schema simplicity for deep schemas', () => {
       const metrics = makeBaseMetrics({ maxRequestSchemaDepth: 8, maxResponseSchemaDepth: 6 });
-      const subscores = computeOperationIntegrationSubscores(metrics, 0);
+      const subscores = computeOperationSubscores(metrics, 0);
       expect(subscores.schemaSimplicity).toBeLessThan(0.5);
     });
 
     it('should clamp schema simplicity at 0 for extremely deep schemas', () => {
       const metrics = makeBaseMetrics({ maxRequestSchemaDepth: 20, maxResponseSchemaDepth: 20 });
-      const subscores = computeOperationIntegrationSubscores(metrics, 0);
+      const subscores = computeOperationSubscores(metrics, 0);
       expect(subscores.schemaSimplicity).toBe(0);
     });
   });
@@ -72,8 +70,8 @@ describe('scoring', () => {
         anyOfCount: 0,
       });
 
-      const subAnyOf = computeOperationIntegrationSubscores(metricsAnyOf, 0);
-      const subOneOf = computeOperationIntegrationSubscores(metricsOneOf, 0);
+      const subAnyOf = computeOperationSubscores(metricsAnyOf, 0);
+      const subOneOf = computeOperationSubscores(metricsOneOf, 0);
 
       expect(subAnyOf.schemaSimplicity).toBeLessThan(subOneOf.schemaSimplicity);
     });
@@ -95,13 +93,13 @@ describe('scoring', () => {
         },
       };
 
-      const subLow = computeOperationIntegrationSubscores(metrics, 0, lowPenalty);
-      const subHigh = computeOperationIntegrationSubscores(metrics, 0, highPenalty);
+      const subLow = computeOperationSubscores(metrics, 0, lowPenalty);
+      const subHigh = computeOperationSubscores(metrics, 0, highPenalty);
 
       expect(subLow.schemaSimplicity).toBeGreaterThan(subHigh.schemaSimplicity);
     });
 
-    it('should give higher agent polymorphism clarity when discriminator is present', () => {
+    it('should give higher polymorphism clarity when discriminator is present', () => {
       const withDisc = makeBaseMetrics({
         polymorphismCount: 4,
         anyOfCount: 2,
@@ -113,8 +111,8 @@ describe('scoring', () => {
         hasDiscriminator: false,
       });
 
-      const subWith = computeOperationAgentSubscores(withDisc, 0);
-      const subWithout = computeOperationAgentSubscores(withoutDisc, 0);
+      const subWith = computeOperationSubscores(withDisc, 0);
+      const subWithout = computeOperationSubscores(withoutDisc, 0);
 
       expect(subWith.polymorphismClarity).toBeGreaterThan(subWithout.polymorphismClarity);
     });
@@ -170,12 +168,10 @@ describe('scoring', () => {
       const doc1 = computeDocumentScores(scores1, 1);
       const doc2 = computeDocumentScores(scores2, 1);
 
-      expect(doc1.integrationSimplicity).toBe(doc2.integrationSimplicity);
       expect(doc1.agentReadiness).toBe(doc2.agentReadiness);
 
       for (const [key, s1] of scores1) {
         const s2 = scores2.get(key)!;
-        expect(s1.integrationSimplicity).toBe(s2.integrationSimplicity);
         expect(s1.agentReadiness).toBe(s2.agentReadiness);
       }
     });
@@ -188,7 +184,7 @@ describe('scoring', () => {
         requestExamplePresent: true,
         responseExamplePresent: true,
       });
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.exampleCoverage).toBe(1);
     });
 
@@ -198,7 +194,7 @@ describe('scoring', () => {
         requestExamplePresent: false,
         responseExamplePresent: true,
       });
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.exampleCoverage).toBe(1);
     });
 
@@ -208,7 +204,7 @@ describe('scoring', () => {
         requestExamplePresent: false,
         responseExamplePresent: true,
       });
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.exampleCoverage).toBe(0.5);
     });
   });
@@ -219,7 +215,7 @@ describe('scoring', () => {
         structuredErrorResponseCount: 3,
         totalErrorResponses: 3,
       });
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.errorClarity).toBe(1);
     });
 
@@ -228,7 +224,7 @@ describe('scoring', () => {
         structuredErrorResponseCount: 0,
         totalErrorResponses: 0,
       });
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.errorClarity).toBe(1);
     });
 
@@ -237,7 +233,7 @@ describe('scoring', () => {
         structuredErrorResponseCount: 0,
         totalErrorResponses: 2,
       });
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.errorClarity).toBe(0);
     });
   });
@@ -251,7 +247,7 @@ describe('scoring', () => {
         totalSchemaProperties: 3,
         schemaPropertiesWithDescription: 3,
       });
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.documentationQuality).toBe(1);
     });
 
@@ -263,7 +259,7 @@ describe('scoring', () => {
         totalSchemaProperties: 0,
         schemaPropertiesWithDescription: 0,
       });
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.documentationQuality).toBe(1);
     });
   });
@@ -271,14 +267,14 @@ describe('scoring', () => {
   describe('dependency clarity', () => {
     it('should give full score with 0 dependency depth', () => {
       const metrics = makeBaseMetrics();
-      const sub = computeOperationIntegrationSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.dependencyClarity).toBe(1);
     });
 
     it('should decrease with higher dependency depth', () => {
       const metrics = makeBaseMetrics();
-      const sub0 = computeOperationIntegrationSubscores(metrics, 0);
-      const sub3 = computeOperationIntegrationSubscores(metrics, 3);
+      const sub0 = computeOperationSubscores(metrics, 0);
+      const sub3 = computeOperationSubscores(metrics, 3);
       expect(sub0.dependencyClarity).toBeGreaterThan(sub3.dependencyClarity);
     });
   });
@@ -286,19 +282,19 @@ describe('scoring', () => {
   describe('agent-specific subscores', () => {
     it('should give full identifier clarity with no ambiguous identifiers', () => {
       const metrics = makeBaseMetrics({ ambiguousIdentifierCount: 0 });
-      const sub = computeOperationAgentSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.identifierClarity).toBe(1);
     });
 
     it('should decrease identifier clarity with ambiguous identifiers', () => {
       const metrics = makeBaseMetrics({ ambiguousIdentifierCount: 3 });
-      const sub = computeOperationAgentSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.identifierClarity).toBe(0);
     });
 
     it('should give full polymorphism clarity with no polymorphism', () => {
       const metrics = makeBaseMetrics({ polymorphismCount: 0, anyOfCount: 0 });
-      const sub = computeOperationAgentSubscores(metrics, 0);
+      const sub = computeOperationSubscores(metrics, 0);
       expect(sub.polymorphismClarity).toBe(1);
     });
   });
@@ -318,9 +314,7 @@ describe('scoring', () => {
       ]);
       const result = computeAllOperationScores(doc, depths);
       expect(result.size).toBe(2);
-      expect(result.get('op1')!.integrationSimplicity).toBeGreaterThan(
-        result.get('op2')!.integrationSimplicity
-      );
+      expect(result.get('op1')!.agentReadiness).toBeGreaterThan(result.get('op2')!.agentReadiness);
     });
   });
 
@@ -353,7 +347,6 @@ describe('scoring', () => {
       const highDisc = computeDocumentScores(scores, 1.0);
       const lowDisc = computeDocumentScores(scores, 0.0);
 
-      expect(highDisc.integrationSimplicity).toBeGreaterThanOrEqual(lowDisc.integrationSimplicity);
       expect(highDisc.agentReadiness).toBeGreaterThanOrEqual(lowDisc.agentReadiness);
     });
   });
@@ -366,21 +359,16 @@ describe('scoring', () => {
         polymorphismCount: 3,
         anyOfCount: 2,
       });
-      const intSub = computeOperationIntegrationSubscores(metrics, 2);
-      const agentSub = computeOperationAgentSubscores(metrics, 2);
-      const intScore = computeIntegrationSimplicity(intSub);
-      const agentScore = computeAgentReadiness(agentSub);
-
-      expect(intScore).toBeGreaterThanOrEqual(0);
-      expect(intScore).toBeLessThanOrEqual(100);
-      expect(agentScore).toBeGreaterThanOrEqual(0);
-      expect(agentScore).toBeLessThanOrEqual(100);
+      const sub = computeOperationSubscores(metrics, 2);
+      const score = computeAgentReadiness(sub);
+
+      expect(score).toBeGreaterThanOrEqual(0);
+      expect(score).toBeLessThanOrEqual(100);
     });
 
-    it('should return 100/100 for an empty document', () => {
+    it('should return 100 for an empty document', () => {
       const opScores = new Map();
-      const { integrationSimplicity, agentReadiness } = computeDocumentScores(opScores, 1);
-      expect(integrationSimplicity).toBe(100);
+      const { agentReadiness } = computeDocumentScores(opScores, 1);
       expect(agentReadiness).toBe(100);
     });
 
@@ -416,17 +404,9 @@ describe('scoring', () => {
         ambiguousIdentifierCount: 4,
       });
 
-      const goodIntSub = computeOperationIntegrationSubscores(good, 0);
-      const badIntSub = computeOperationIntegrationSubscores(bad, 3);
-      expect(computeIntegrationSimplicity(goodIntSub)).toBeGreaterThan(
-        computeIntegrationSimplicity(badIntSub)
-      );
-
-      const goodAgentSub = computeOperationAgentSubscores(good, 0);
-      const badAgentSub = computeOperationAgentSubscores(bad, 3);
-      expect(computeAgentReadiness(goodAgentSub)).toBeGreaterThan(
-        computeAgentReadiness(badAgentSub)
-      );
+      const goodSub = computeOperationSubscores(good, 0);
+      const badSub = computeOperationSubscores(bad, 3);
+      expect(computeAgentReadiness(goodSub)).toBeGreaterThan(computeAgentReadiness(badSub));
     });
   });
 });
diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index 87b801ef33..625a25330e 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -9,6 +9,7 @@ import {
   isPlainObject,
   isRef,
   isMappingRef,
+  unescapePointerFragment,
   type Document,
   type SpecVersion,
   type WalkContext,
@@ -22,33 +23,17 @@ import {
   createSchemaMetricVisitor,
   getDocumentMetrics,
 } from './collectors/document-metrics.js';
-import type { DebugMediaTypeLog, DocumentMetrics } from './types.js';
+import type { DebugMediaTypeLog, DocumentMetrics, SchemaStats } from './types.js';
 
 function resolveJsonPointer(root: any, ref: string): any {
   if (!ref.startsWith('#/')) return undefined;
   let node = root;
   for (const segment of ref.slice(2).split('/')) {
-    const decoded = decodeURIComponent(segment).replace(/~1/g, '/').replace(/~0/g, '~');
-    node = node?.[decoded];
+    node = node?.[unescapePointerFragment(segment)];
   }
   return node;
 }
 
-interface SchemaStats {
-  maxDepth: number;
-  polymorphismCount: number;
-  anyOfCount: number;
-  hasDiscriminator: boolean;
-  propertyCount: number;
-  totalSchemaProperties: number;
-  schemaPropertiesWithDescription: number;
-  constraintCount: number;
-  hasPropertyExamples: boolean;
-  writableTopLevelFields: number;
-  refsUsed: string[];
-  debugEntries?: import('./types.js').DebugSchemaEntry[];
-}
-
 export interface CollectMetricsOptions {
   document: Document;
   types: ReturnType<typeof normalizeTypes>;
@@ -142,17 +127,9 @@ export function collectMetrics({
         resolvedRefMap,
         ctx,
       });
+      const { depth: _, pendingRef: __, debugEntries: _debug, ...stats } = schemaWalkState;
       return {
-        maxDepth: schemaWalkState.maxDepth,
-        polymorphismCount: schemaWalkState.polymorphismCount,
-        anyOfCount: schemaWalkState.anyOfCount,
-        hasDiscriminator: schemaWalkState.hasDiscriminator,
-        propertyCount: schemaWalkState.propertyCount,
-        totalSchemaProperties: schemaWalkState.totalSchemaProperties,
-        schemaPropertiesWithDescription: schemaWalkState.schemaPropertiesWithDescription,
-        constraintCount: schemaWalkState.constraintCount,
-        hasPropertyExamples: schemaWalkState.hasPropertyExamples,
-        writableTopLevelFields: schemaWalkState.writableTopLevelFields,
+        ...stats,
         refsUsed: [...schemaWalkState.refsUsed],
         debugEntries: debug ? (schemaWalkState.debugEntries ?? undefined) : undefined,
       };
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
index eae13e4faa..8c70b80d7c 100644
--- a/packages/cli/src/commands/score/collectors/document-metrics.ts
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -17,6 +17,7 @@ import type {
   DebugSchemaEntry,
   DocumentMetrics,
   OperationMetrics,
+  SchemaStats,
 } from '../types.js';
 
 type Schema = Oas3Schema | Oas3_1Schema;
@@ -80,21 +81,7 @@ export function createSchemaWalkState(): SchemaWalkState {
 }
 
 export function resetSchemaWalkState(s: SchemaWalkState): void {
-  s.depth = -1; // starts at -1 because the root Schema.enter increments to 0
-
-  s.maxDepth = 0;
-  s.polymorphismCount = 0;
-  s.anyOfCount = 0;
-  s.hasDiscriminator = false;
-  s.propertyCount = 0;
-  s.totalSchemaProperties = 0;
-  s.schemaPropertiesWithDescription = 0;
-  s.constraintCount = 0;
-  s.hasPropertyExamples = false;
-  s.writableTopLevelFields = 0;
-  s.refsUsed = [];
-  s.debugEntries = null;
-  s.pendingRef = null;
+  Object.assign(s, createSchemaWalkState());
 }
 
 export function createSchemaMetricVisitor(state: SchemaWalkState): Oas3Visitor {
@@ -166,21 +153,6 @@ export function createSchemaMetricVisitor(state: SchemaWalkState): Oas3Visitor {
   };
 }
 
-interface SchemaStats {
-  maxDepth: number;
-  polymorphismCount: number;
-  anyOfCount: number;
-  hasDiscriminator: boolean;
-  propertyCount: number;
-  totalSchemaProperties: number;
-  schemaPropertiesWithDescription: number;
-  constraintCount: number;
-  hasPropertyExamples: boolean;
-  writableTopLevelFields: number;
-  refsUsed: string[];
-  debugEntries?: DebugSchemaEntry[];
-}
-
 interface CurrentOperationContext {
   path: string;
   method: string;
@@ -352,10 +324,7 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
       },
     },
     MediaType: {
-      enter(
-        mediaType: { schema?: any; example?: unknown; examples?: Record<string, unknown> },
-        _ctx: UserContext
-      ) {
+      enter(mediaType: any) {
         const current = accumulator.current;
         if (!current) return;
 
@@ -492,11 +461,7 @@ function mergeParameters(
 }
 
 function hasExample(mediaType: { example?: unknown; examples?: Record<string, unknown> }): boolean {
-  if (mediaType.example !== undefined) return true;
-  if (isNotEmptyObject(mediaType.examples)) {
-    return true;
-  }
-  return false;
+  return mediaType.example !== undefined || isNotEmptyObject(mediaType.examples);
 }
 
 function isAmbiguousParam(param: Param): boolean {
diff --git a/packages/cli/src/commands/score/constants.ts b/packages/cli/src/commands/score/constants.ts
index e693ca9935..e2d1dbfc36 100644
--- a/packages/cli/src/commands/score/constants.ts
+++ b/packages/cli/src/commands/score/constants.ts
@@ -11,24 +11,15 @@ export const DEFAULT_SCORING_CONSTANTS: ScoringConstants = {
     maxOperationsForDiscoverability: 1000,
   },
   weights: {
-    integration: {
-      parameterSimplicity: 0.2,
-      schemaSimplicity: 0.2,
-      documentationQuality: 0.15,
-      constraintClarity: 0.1,
-      exampleCoverage: 0.15,
-      errorClarity: 0.1,
-      dependencyClarity: 0.1,
-    },
-    agent: {
-      documentationQuality: 0.2,
-      constraintClarity: 0.15,
-      exampleCoverage: 0.2,
-      errorClarity: 0.15,
-      identifierClarity: 0.1,
-      dependencyClarity: 0.1,
-      polymorphismClarity: 0.1,
-    },
+    parameterSimplicity: 0.1,
+    schemaSimplicity: 0.1,
+    documentationQuality: 0.18,
+    constraintClarity: 0.12,
+    exampleCoverage: 0.18,
+    errorClarity: 0.12,
+    dependencyClarity: 0.1,
+    identifierClarity: 0.05,
+    polymorphismClarity: 0.05,
     anyOfPenaltyMultiplier: 2.0,
     discoverabilityWeight: 0.1,
   },
diff --git a/packages/cli/src/commands/score/formatters/json.ts b/packages/cli/src/commands/score/formatters/json.ts
index b827ae0648..dd09033677 100644
--- a/packages/cli/src/commands/score/formatters/json.ts
+++ b/packages/cli/src/commands/score/formatters/json.ts
@@ -4,11 +4,9 @@ import type { ScoreResult } from '../types.js';
 
 export function printScoreJson(result: ScoreResult): void {
   const output = {
-    integrationSimplicity: result.integrationSimplicity,
     agentReadiness: result.agentReadiness,
     discoverability: Math.round(result.discoverability * 100),
-    integrationSubscores: result.integrationSubscores,
-    agentSubscores: result.agentSubscores,
+    subscores: result.subscores,
     rawMetrics: {
       operationCount: result.rawMetrics.operationCount,
       operations: Object.fromEntries(
diff --git a/packages/cli/src/commands/score/formatters/stylish.ts b/packages/cli/src/commands/score/formatters/stylish.ts
index 0ae85a78bc..449a022def 100644
--- a/packages/cli/src/commands/score/formatters/stylish.ts
+++ b/packages/cli/src/commands/score/formatters/stylish.ts
@@ -29,35 +29,23 @@ function printScores(result: ScoreResult): void {
   out('');
   out(bold(white('  Scores')));
   out('');
-  out(`  Integration Simplicity:  ${formatScore(result.integrationSimplicity)}/100`);
-  out(`  Agent Readiness:         ${formatScore(result.agentReadiness)}/100`);
+  out(`  Agent Readiness:  ${formatScore(result.agentReadiness)}/100`);
   out('');
 }
 
 function printSubscores(result: ScoreResult): void {
-  out(bold(white('  Integration Simplicity Subscores')));
+  out(bold(white('  Subscores')));
   out('');
-  const is = result.integrationSubscores;
-  printSubscore('Parameter Simplicity', is.parameterSimplicity);
-  printSubscore('Schema Simplicity', is.schemaSimplicity);
-  printSubscore('Documentation Quality', is.documentationQuality);
-  printSubscore('Constraint Clarity', is.constraintClarity);
-  printSubscore('Example Coverage', is.exampleCoverage);
-  printSubscore('Error Clarity', is.errorClarity);
-  printSubscore('Dependency Clarity', is.dependencyClarity);
-  printSubscore('Discoverability', result.discoverability);
-  out('');
-
-  out(bold(white('  Agent Readiness Subscores')));
-  out('');
-  const ar = result.agentSubscores;
-  printSubscore('Documentation Quality', ar.documentationQuality);
-  printSubscore('Constraint Clarity', ar.constraintClarity);
-  printSubscore('Example Coverage', ar.exampleCoverage);
-  printSubscore('Error Clarity', ar.errorClarity);
-  printSubscore('Identifier Clarity', ar.identifierClarity);
-  printSubscore('Dependency Clarity', ar.dependencyClarity);
-  printSubscore('Polymorphism Clarity', ar.polymorphismClarity);
+  const s = result.subscores;
+  printSubscore('Parameter Simplicity', s.parameterSimplicity);
+  printSubscore('Schema Simplicity', s.schemaSimplicity);
+  printSubscore('Documentation Quality', s.documentationQuality);
+  printSubscore('Constraint Clarity', s.constraintClarity);
+  printSubscore('Example Coverage', s.exampleCoverage);
+  printSubscore('Error Clarity', s.errorClarity);
+  printSubscore('Dependency Clarity', s.dependencyClarity);
+  printSubscore('Identifier Clarity', s.identifierClarity);
+  printSubscore('Polymorphism Clarity', s.polymorphismClarity);
   printSubscore('Discoverability', result.discoverability);
   out('');
 }
@@ -285,10 +273,7 @@ function printHotspots(result: ScoreResult): void {
       : `${hotspot.method.toUpperCase()} ${hotspot.path}`;
 
     out(bold(`  ${label}`));
-    out(
-      `    Integration Simplicity: ${formatScore(hotspot.integrationSimplicityScore)}  ` +
-        `Agent Readiness: ${formatScore(hotspot.agentReadinessScore)}`
-    );
+    out(`    Agent Readiness: ${formatScore(hotspot.agentReadinessScore)}`);
 
     for (const reason of hotspot.reasons) {
       out(yellow(`    - ${reason}`));
diff --git a/packages/cli/src/commands/score/hotspots.ts b/packages/cli/src/commands/score/hotspots.ts
index 9236d6d081..cc510e942e 100644
--- a/packages/cli/src/commands/score/hotspots.ts
+++ b/packages/cli/src/commands/score/hotspots.ts
@@ -2,6 +2,7 @@ import { DEFAULT_SCORING_CONSTANTS } from './constants.js';
 import type {
   DocumentMetrics,
   HotspotOperation,
+  OperationMetrics,
   OperationScores,
   ScoringConstants,
 } from './types.js';
@@ -25,7 +26,6 @@ export function selectTopHotspots(
       path: metrics.path,
       method: metrics.method,
       operationId: metrics.operationId,
-      integrationSimplicityScore: scores.integrationSimplicity,
       agentReadinessScore: scores.agentReadiness,
       reasons,
     });
@@ -33,31 +33,14 @@ export function selectTopHotspots(
 
   entries.sort((a, b) => {
     if (a.reasons.length !== b.reasons.length) return b.reasons.length - a.reasons.length;
-    const aAvg = (a.integrationSimplicityScore + a.agentReadinessScore) / 2;
-    const bAvg = (b.integrationSimplicityScore + b.agentReadinessScore) / 2;
-    return aAvg - bAvg;
+    return a.agentReadinessScore - b.agentReadinessScore;
   });
 
   return entries.slice(0, constants.hotspotLimit);
 }
 
 function getHotspotReasons(
-  metrics: {
-    parameterCount: number;
-    maxRequestSchemaDepth: number;
-    maxResponseSchemaDepth: number;
-    polymorphismCount: number;
-    anyOfCount: number;
-    hasDiscriminator: boolean;
-    requestBodyPresent: boolean;
-    requestExamplePresent: boolean;
-    responseExamplePresent: boolean;
-    structuredErrorResponseCount: number;
-    totalErrorResponses: number;
-    operationDescriptionPresent: boolean;
-    paramsWithDescription: number;
-    ambiguousIdentifierCount: number;
-  },
+  metrics: OperationMetrics,
   dependencyDepth: number,
   constants: ScoringConstants
 ): string[] {
diff --git a/packages/cli/src/commands/score/index.ts b/packages/cli/src/commands/score/index.ts
index 875df601d8..0f297ac223 100644
--- a/packages/cli/src/commands/score/index.ts
+++ b/packages/cli/src/commands/score/index.ts
@@ -22,8 +22,7 @@ import { printScoreJson } from './formatters/json.js';
 import { printDebugOperation, printScoreStylish } from './formatters/stylish.js';
 import { selectTopHotspots } from './hotspots.js';
 import {
-  aggregateAgentSubscores,
-  aggregateIntegrationSubscores,
+  aggregateSubscores,
   computeAllOperationScores,
   computeDiscoverability,
   computeDocumentScores,
@@ -72,19 +71,14 @@ export async function handleScore({ argv, config, collectSpecData }: CommandArgs
   const dependencyDepths = computeDependencyDepths(rawMetrics.operations);
   const operationScores = computeAllOperationScores(rawMetrics, dependencyDepths);
   const discoverability = computeDiscoverability(rawMetrics.operationCount);
-  const { integrationSimplicity, agentReadiness } = computeDocumentScores(
-    operationScores,
-    discoverability
-  );
+  const { agentReadiness } = computeDocumentScores(operationScores, discoverability);
 
   const hotspots = selectTopHotspots(rawMetrics, operationScores, dependencyDepths);
 
   const result: ScoreResult = {
-    integrationSimplicity,
     agentReadiness,
     discoverability,
-    integrationSubscores: aggregateIntegrationSubscores(operationScores),
-    agentSubscores: aggregateAgentSubscores(operationScores),
+    subscores: aggregateSubscores(operationScores),
     rawMetrics,
     hotspots,
     operationScores,
diff --git a/packages/cli/src/commands/score/scoring.ts b/packages/cli/src/commands/score/scoring.ts
index 8af67fd808..8f6a946a76 100644
--- a/packages/cli/src/commands/score/scoring.ts
+++ b/packages/cli/src/commands/score/scoring.ts
@@ -1,18 +1,17 @@
 import { DEFAULT_SCORING_CONSTANTS } from './constants.js';
 import type {
-  AgentReadinessSubscores,
   DocumentMetrics,
-  IntegrationSimplicitySubscores,
   OperationMetrics,
   OperationScores,
   ScoringConstants,
+  Subscores,
 } from './types.js';
 
-export function computeOperationIntegrationSubscores(
+export function computeOperationSubscores(
   metrics: OperationMetrics,
   dependencyDepth: number,
   constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
-): IntegrationSimplicitySubscores {
+): Subscores {
   const { thresholds, weights } = constants;
 
   const parameterSimplicity = clamp01(1 - metrics.parameterCount / (thresholds.maxParamsGood * 2));
@@ -46,52 +45,12 @@ export function computeOperationIntegrationSubscores(
 
   const dependencyClarity = clamp01(1 - dependencyDepth / (thresholds.maxDependencyDepthGood * 2));
 
-  return {
-    parameterSimplicity,
-    schemaSimplicity,
-    documentationQuality,
-    constraintClarity,
-    exampleCoverage,
-    errorClarity,
-    dependencyClarity,
-  };
-}
-
-export function computeOperationAgentSubscores(
-  metrics: OperationMetrics,
-  dependencyDepth: number,
-  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
-): AgentReadinessSubscores {
-  const { thresholds, weights } = constants;
-
-  const descCount =
-    (metrics.operationDescriptionPresent ? 1 : 0) +
-    metrics.paramsWithDescription +
-    metrics.schemaPropertiesWithDescription;
-  const descTotal = 1 + metrics.parameterCount + metrics.totalSchemaProperties;
-  const documentationQuality = descTotal > 0 ? clamp01(descCount / descTotal) : 1;
-
-  const propCount = metrics.totalSchemaProperties || 1;
-  const constraintClarity = clamp01(metrics.constraintCount / propCount);
-
-  const examplePoints =
-    (metrics.requestExamplePresent ? 1 : 0) + (metrics.responseExamplePresent ? 1 : 0);
-  const exampleTotal = (metrics.requestBodyPresent ? 1 : 0) + 1;
-  const exampleCoverage = clamp01(examplePoints / exampleTotal);
-
-  const errorClarity =
-    metrics.totalErrorResponses > 0
-      ? clamp01(metrics.structuredErrorResponseCount / metrics.totalErrorResponses)
-      : 1;
-
   const identifierClarity = clamp01(
     1 - metrics.ambiguousIdentifierCount / Math.max(thresholds.maxAmbiguousGood + 3, 1)
   );
 
-  const dependencyClarity = clamp01(1 - dependencyDepth / (thresholds.maxDependencyDepthGood * 2));
-
   const polyScore = effectivePolymorphism(metrics, weights.anyOfPenaltyMultiplier);
-  const polyClarity =
+  const polymorphismClarity =
     polyScore === 0
       ? 1
       : metrics.hasDiscriminator
@@ -99,21 +58,23 @@ export function computeOperationAgentSubscores(
         : clamp01(1 - polyScore / (thresholds.maxPolymorphismGood * 2));
 
   return {
+    parameterSimplicity,
+    schemaSimplicity,
     documentationQuality,
     constraintClarity,
     exampleCoverage,
     errorClarity,
-    identifierClarity,
     dependencyClarity,
-    polymorphismClarity: polyClarity,
+    identifierClarity,
+    polymorphismClarity,
   };
 }
 
-export function computeIntegrationSimplicity(
-  subscores: IntegrationSimplicitySubscores,
+export function computeAgentReadiness(
+  subscores: Subscores,
   constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
 ): number {
-  const w = constants.weights.integration;
+  const w = constants.weights;
   const raw =
     subscores.parameterSimplicity * w.parameterSimplicity +
     subscores.schemaSimplicity * w.schemaSimplicity +
@@ -121,22 +82,8 @@ export function computeIntegrationSimplicity(
     subscores.constraintClarity * w.constraintClarity +
     subscores.exampleCoverage * w.exampleCoverage +
     subscores.errorClarity * w.errorClarity +
-    subscores.dependencyClarity * w.dependencyClarity;
-  return round(clamp01(raw) * 100);
-}
-
-export function computeAgentReadiness(
-  subscores: AgentReadinessSubscores,
-  constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
-): number {
-  const w = constants.weights.agent;
-  const raw =
-    subscores.documentationQuality * w.documentationQuality +
-    subscores.constraintClarity * w.constraintClarity +
-    subscores.exampleCoverage * w.exampleCoverage +
-    subscores.errorClarity * w.errorClarity +
-    subscores.identifierClarity * w.identifierClarity +
     subscores.dependencyClarity * w.dependencyClarity +
+    subscores.identifierClarity * w.identifierClarity +
     subscores.polymorphismClarity * w.polymorphismClarity;
   return round(clamp01(raw) * 100);
 }
@@ -150,14 +97,11 @@ export function computeAllOperationScores(
 
   for (const [key, metrics] of documentMetrics.operations) {
     const depth = dependencyDepths.get(key) ?? 0;
-    const integrationSubscores = computeOperationIntegrationSubscores(metrics, depth, constants);
-    const agentSubscores = computeOperationAgentSubscores(metrics, depth, constants);
+    const subscores = computeOperationSubscores(metrics, depth, constants);
 
     result.set(key, {
-      integrationSimplicity: computeIntegrationSimplicity(integrationSubscores, constants),
-      agentReadiness: computeAgentReadiness(agentSubscores, constants),
-      integrationSubscores,
-      agentSubscores,
+      agentReadiness: computeAgentReadiness(subscores, constants),
+      subscores,
     });
   }
 
@@ -175,27 +119,21 @@ export function computeDocumentScores(
   operationScores: Map<string, OperationScores>,
   discoverability: number,
   constants: ScoringConstants = DEFAULT_SCORING_CONSTANTS
-): {
-  integrationSimplicity: number;
-  agentReadiness: number;
-} {
+): { agentReadiness: number } {
   if (operationScores.size === 0) {
-    return { integrationSimplicity: 100, agentReadiness: 100 };
+    return { agentReadiness: 100 };
   }
 
-  const intScores: number[] = [];
-  const agentScores: number[] = [];
-  for (const scores of operationScores.values()) {
-    intScores.push(scores.integrationSimplicity);
-    agentScores.push(scores.agentReadiness);
+  const scores: number[] = [];
+  for (const s of operationScores.values()) {
+    scores.push(s.agentReadiness);
   }
 
   const w = constants.weights.discoverabilityWeight;
   const discPct = discoverability * 100;
 
   return {
-    integrationSimplicity: round(median(intScores) * (1 - w) + discPct * w),
-    agentReadiness: round(median(agentScores) * (1 - w) + discPct * w),
+    agentReadiness: round(median(scores) * (1 - w) + discPct * w),
   };
 }
 
@@ -208,11 +146,11 @@ function clamp01(value: number): number {
   return Math.max(0, Math.min(1, value));
 }
 
-export function aggregateIntegrationSubscores(
-  operationScores: Map<string, { integrationSubscores: IntegrationSimplicitySubscores }>
-): IntegrationSimplicitySubscores {
+export function aggregateSubscores(
+  operationScores: Map<string, { subscores: Subscores }>
+): Subscores {
   const n = operationScores.size || 1;
-  const result: IntegrationSimplicitySubscores = {
+  const result: Subscores = {
     parameterSimplicity: 0,
     schemaSimplicity: 0,
     documentationQuality: 0,
@@ -220,16 +158,20 @@ export function aggregateIntegrationSubscores(
     exampleCoverage: 0,
     errorClarity: 0,
     dependencyClarity: 0,
+    identifierClarity: 0,
+    polymorphismClarity: 0,
   };
 
   for (const scores of operationScores.values()) {
-    result.parameterSimplicity += scores.integrationSubscores.parameterSimplicity;
-    result.schemaSimplicity += scores.integrationSubscores.schemaSimplicity;
-    result.documentationQuality += scores.integrationSubscores.documentationQuality;
-    result.constraintClarity += scores.integrationSubscores.constraintClarity;
-    result.exampleCoverage += scores.integrationSubscores.exampleCoverage;
-    result.errorClarity += scores.integrationSubscores.errorClarity;
-    result.dependencyClarity += scores.integrationSubscores.dependencyClarity;
+    result.parameterSimplicity += scores.subscores.parameterSimplicity;
+    result.schemaSimplicity += scores.subscores.schemaSimplicity;
+    result.documentationQuality += scores.subscores.documentationQuality;
+    result.constraintClarity += scores.subscores.constraintClarity;
+    result.exampleCoverage += scores.subscores.exampleCoverage;
+    result.errorClarity += scores.subscores.errorClarity;
+    result.dependencyClarity += scores.subscores.dependencyClarity;
+    result.identifierClarity += scores.subscores.identifierClarity;
+    result.polymorphismClarity += scores.subscores.polymorphismClarity;
   }
 
   result.parameterSimplicity /= n;
@@ -239,40 +181,7 @@ export function aggregateIntegrationSubscores(
   result.exampleCoverage /= n;
   result.errorClarity /= n;
   result.dependencyClarity /= n;
-
-  return result;
-}
-
-export function aggregateAgentSubscores(
-  operationScores: Map<string, { agentSubscores: AgentReadinessSubscores }>
-): AgentReadinessSubscores {
-  const n = operationScores.size || 1;
-  const result: AgentReadinessSubscores = {
-    documentationQuality: 0,
-    constraintClarity: 0,
-    exampleCoverage: 0,
-    errorClarity: 0,
-    identifierClarity: 0,
-    dependencyClarity: 0,
-    polymorphismClarity: 0,
-  };
-
-  for (const scores of operationScores.values()) {
-    result.documentationQuality += scores.agentSubscores.documentationQuality;
-    result.constraintClarity += scores.agentSubscores.constraintClarity;
-    result.exampleCoverage += scores.agentSubscores.exampleCoverage;
-    result.errorClarity += scores.agentSubscores.errorClarity;
-    result.identifierClarity += scores.agentSubscores.identifierClarity;
-    result.dependencyClarity += scores.agentSubscores.dependencyClarity;
-    result.polymorphismClarity += scores.agentSubscores.polymorphismClarity;
-  }
-
-  result.documentationQuality /= n;
-  result.constraintClarity /= n;
-  result.exampleCoverage /= n;
-  result.errorClarity /= n;
   result.identifierClarity /= n;
-  result.dependencyClarity /= n;
   result.polymorphismClarity /= n;
 
   return result;
diff --git a/packages/cli/src/commands/score/types.ts b/packages/cli/src/commands/score/types.ts
index ea05ad6cd0..0d6380ed08 100644
--- a/packages/cli/src/commands/score/types.ts
+++ b/packages/cli/src/commands/score/types.ts
@@ -39,7 +39,7 @@ export interface DocumentMetrics {
   operations: Map<string, OperationMetrics>;
 }
 
-export interface IntegrationSimplicitySubscores {
+export interface Subscores {
   parameterSimplicity: number;
   schemaSimplicity: number;
   documentationQuality: number;
@@ -47,40 +47,27 @@ export interface IntegrationSimplicitySubscores {
   exampleCoverage: number;
   errorClarity: number;
   dependencyClarity: number;
-}
-
-export interface AgentReadinessSubscores {
-  documentationQuality: number;
-  constraintClarity: number;
-  exampleCoverage: number;
-  errorClarity: number;
   identifierClarity: number;
-  dependencyClarity: number;
   polymorphismClarity: number;
 }
 
 export interface OperationScores {
-  integrationSimplicity: number;
   agentReadiness: number;
-  integrationSubscores: IntegrationSimplicitySubscores;
-  agentSubscores: AgentReadinessSubscores;
+  subscores: Subscores;
 }
 
 export interface HotspotOperation {
   path: string;
   method: string;
   operationId?: string;
-  integrationSimplicityScore: number;
   agentReadinessScore: number;
   reasons: string[];
 }
 
 export interface ScoreResult {
-  integrationSimplicity: number;
   agentReadiness: number;
   discoverability: number;
-  integrationSubscores: IntegrationSimplicitySubscores;
-  agentSubscores: AgentReadinessSubscores;
+  subscores: Subscores;
   rawMetrics: DocumentMetrics;
   hotspots: HotspotOperation[];
   operationScores: Map<string, OperationScores>;
@@ -98,24 +85,15 @@ export interface ScoringThresholds {
 }
 
 export interface ScoringWeights {
-  integration: {
-    parameterSimplicity: number;
-    schemaSimplicity: number;
-    documentationQuality: number;
-    constraintClarity: number;
-    exampleCoverage: number;
-    errorClarity: number;
-    dependencyClarity: number;
-  };
-  agent: {
-    documentationQuality: number;
-    constraintClarity: number;
-    exampleCoverage: number;
-    errorClarity: number;
-    identifierClarity: number;
-    dependencyClarity: number;
-    polymorphismClarity: number;
-  };
+  parameterSimplicity: number;
+  schemaSimplicity: number;
+  documentationQuality: number;
+  constraintClarity: number;
+  exampleCoverage: number;
+  errorClarity: number;
+  dependencyClarity: number;
+  identifierClarity: number;
+  polymorphismClarity: number;
   anyOfPenaltyMultiplier: number;
   discoverabilityWeight: number;
 }
@@ -142,3 +120,18 @@ export interface DebugMediaTypeLog {
   totalConstraints: number;
   maxDepth: number;
 }
+
+export interface SchemaStats {
+  maxDepth: number;
+  polymorphismCount: number;
+  anyOfCount: number;
+  hasDiscriminator: boolean;
+  propertyCount: number;
+  totalSchemaProperties: number;
+  schemaPropertiesWithDescription: number;
+  constraintCount: number;
+  hasPropertyExamples: boolean;
+  writableTopLevelFields: number;
+  refsUsed: string[];
+  debugEntries?: DebugSchemaEntry[];
+}
diff --git a/tests/e2e/score/score-json/snapshot.txt b/tests/e2e/score/score-json/snapshot.txt
index 0e133ed19c..13a5f14862 100644
--- a/tests/e2e/score/score-json/snapshot.txt
+++ b/tests/e2e/score/score-json/snapshot.txt
@@ -1,23 +1,15 @@
 {
-  "integrationSimplicity": 86.2,
-  "agentReadiness": 90.2,
+  "agentReadiness": 88.4,
   "discoverability": 99,
-  "integrationSubscores": {
+  "subscores": {
     "parameterSimplicity": 0.8625,
     "schemaSimplicity": 0.796875,
     "documentationQuality": 0.9017857142857143,
     "constraintClarity": 0.5833333333333333,
     "exampleCoverage": 0.875,
     "errorClarity": 1,
-    "dependencyClarity": 0.7291666666666669
-  },
-  "agentSubscores": {
-    "documentationQuality": 0.9017857142857143,
-    "constraintClarity": 0.5833333333333333,
-    "exampleCoverage": 0.875,
-    "errorClarity": 1,
-    "identifierClarity": 1,
     "dependencyClarity": 0.7291666666666669,
+    "identifierClarity": 1,
     "polymorphismClarity": 1
   },
   "rawMetrics": {
@@ -227,178 +219,114 @@
   },
   "operationScores": {
     "getMuseumHours": {
-      "integrationSimplicity": 85.2,
-      "agentReadiness": 95.5,
-      "integrationSubscores": {
+      "agentReadiness": 90.3,
+      "subscores": {
         "parameterSimplicity": 0.7,
         "schemaSimplicity": 0.75,
         "documentationQuality": 0.8571428571428571,
         "constraintClarity": 1,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "dependencyClarity": 0.8333333333333334
-      },
-      "agentSubscores": {
-        "documentationQuality": 0.8571428571428571,
-        "constraintClarity": 1,
-        "exampleCoverage": 1,
-        "errorClarity": 1,
-        "identifierClarity": 1,
         "dependencyClarity": 0.8333333333333334,
+        "identifierClarity": 1,
         "polymorphismClarity": 1
       }
     },
     "listSpecialEvents": {
-      "integrationSimplicity": 76.2,
-      "agentReadiness": 89.2,
-      "integrationSubscores": {
+      "agentReadiness": 82.9,
+      "subscores": {
         "parameterSimplicity": 0.6,
         "schemaSimplicity": 0.625,
         "documentationQuality": 1,
         "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "dependencyClarity": 0.6666666666666667
-      },
-      "agentSubscores": {
-        "documentationQuality": 1,
-        "constraintClarity": 0.5,
-        "exampleCoverage": 1,
-        "errorClarity": 1,
-        "identifierClarity": 1,
         "dependencyClarity": 0.6666666666666667,
+        "identifierClarity": 1,
         "polymorphismClarity": 1
       }
     },
     "createSpecialEvent": {
-      "integrationSimplicity": 86.7,
-      "agentReadiness": 89.2,
-      "integrationSubscores": {
+      "agentReadiness": 88.2,
+      "subscores": {
         "parameterSimplicity": 1,
         "schemaSimplicity": 0.75,
         "documentationQuality": 1,
         "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "dependencyClarity": 0.6666666666666667
-      },
-      "agentSubscores": {
-        "documentationQuality": 1,
-        "constraintClarity": 0.5,
-        "exampleCoverage": 1,
-        "errorClarity": 1,
-        "identifierClarity": 1,
         "dependencyClarity": 0.6666666666666667,
+        "identifierClarity": 1,
         "polymorphismClarity": 1
       }
     },
     "getSpecialEvent": {
-      "integrationSimplicity": 84.7,
-      "agentReadiness": 89.2,
-      "integrationSubscores": {
+      "agentReadiness": 87.2,
+      "subscores": {
         "parameterSimplicity": 0.9,
         "schemaSimplicity": 0.75,
         "documentationQuality": 1,
         "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "dependencyClarity": 0.6666666666666667
-      },
-      "agentSubscores": {
-        "documentationQuality": 1,
-        "constraintClarity": 0.5,
-        "exampleCoverage": 1,
-        "errorClarity": 1,
-        "identifierClarity": 1,
         "dependencyClarity": 0.6666666666666667,
+        "identifierClarity": 1,
         "polymorphismClarity": 1
       }
     },
     "deleteSpecialEvent": {
-      "integrationSimplicity": 74.7,
-      "agentReadiness": 71.7,
-      "integrationSubscores": {
+      "agentReadiness": 73.4,
+      "subscores": {
         "parameterSimplicity": 0.9,
         "schemaSimplicity": 0.875,
         "documentationQuality": 0.5,
         "constraintClarity": 0,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "dependencyClarity": 0.6666666666666667
-      },
-      "agentSubscores": {
-        "documentationQuality": 0.5,
-        "constraintClarity": 0,
-        "exampleCoverage": 1,
-        "errorClarity": 1,
-        "identifierClarity": 1,
         "dependencyClarity": 0.6666666666666667,
+        "identifierClarity": 1,
         "polymorphismClarity": 1
       }
     },
     "updateSpecialEvent": {
-      "integrationSimplicity": 84.7,
-      "agentReadiness": 89.2,
-      "integrationSubscores": {
+      "agentReadiness": 87.2,
+      "subscores": {
         "parameterSimplicity": 0.9,
         "schemaSimplicity": 0.75,
         "documentationQuality": 1,
         "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "dependencyClarity": 0.6666666666666667
-      },
-      "agentSubscores": {
-        "documentationQuality": 1,
-        "constraintClarity": 0.5,
-        "exampleCoverage": 1,
-        "errorClarity": 1,
-        "identifierClarity": 1,
         "dependencyClarity": 0.6666666666666667,
+        "identifierClarity": 1,
         "polymorphismClarity": 1
       }
     },
     "buyMuseumTickets": {
-      "integrationSimplicity": 88.7,
       "agentReadiness": 88.8,
-      "integrationSubscores": {
+      "subscores": {
         "parameterSimplicity": 1,
         "schemaSimplicity": 0.875,
         "documentationQuality": 0.8571428571428571,
         "constraintClarity": 0.6666666666666666,
         "exampleCoverage": 1,
         "errorClarity": 1,
-        "dependencyClarity": 0.6666666666666667
-      },
-      "agentSubscores": {
-        "documentationQuality": 0.8571428571428571,
-        "constraintClarity": 0.6666666666666666,
-        "exampleCoverage": 1,
-        "errorClarity": 1,
-        "identifierClarity": 1,
         "dependencyClarity": 0.6666666666666667,
+        "identifierClarity": 1,
         "polymorphismClarity": 1
       }
     },
     "getTicketCode": {
-      "integrationSimplicity": 83,
-      "agentReadiness": 80,
-      "integrationSubscores": {
+      "agentReadiness": 81,
+      "subscores": {
         "parameterSimplicity": 0.9,
         "schemaSimplicity": 1,
         "documentationQuality": 1,
         "constraintClarity": 1,
         "exampleCoverage": 0,
         "errorClarity": 1,
-        "dependencyClarity": 1
-      },
-      "agentSubscores": {
-        "documentationQuality": 1,
-        "constraintClarity": 1,
-        "exampleCoverage": 0,
-        "errorClarity": 1,
-        "identifierClarity": 1,
         "dependencyClarity": 1,
+        "identifierClarity": 1,
         "polymorphismClarity": 1
       }
     }
@@ -418,8 +346,7 @@
       "path": "/tickets/{ticketId}/qr",
       "method": "get",
       "operationId": "getTicketCode",
-      "integrationSimplicityScore": 83,
-      "agentReadinessScore": 80,
+      "agentReadinessScore": 81,
       "reasons": [
         "Missing response examples"
       ]
diff --git a/tests/e2e/score/score-minimal/snapshot.txt b/tests/e2e/score/score-minimal/snapshot.txt
index 9ef0ebf8d3..63ea3d7936 100644
--- a/tests/e2e/score/score-minimal/snapshot.txt
+++ b/tests/e2e/score/score-minimal/snapshot.txt
@@ -1,10 +1,9 @@
 
   Scores
 
-  Integration Simplicity:  58.8/100
-  Agent Readiness:         47.5/100
+  Agent Readiness:  52.7/100
 
-  Integration Simplicity Subscores
+  Subscores
 
   Parameter Simplicity     [██████████████████░░] 90%
   Schema Simplicity        [████████████████░░░░] 81%
@@ -13,16 +12,7 @@
   Example Coverage         [░░░░░░░░░░░░░░░░░░░░] 0%
   Error Clarity            [████████████████████] 100%
   Dependency Clarity       [████████████████████] 100%
-  Discoverability          [████████████████████] 100%
-
-  Agent Readiness Subscores
-
-  Documentation Quality    [░░░░░░░░░░░░░░░░░░░░] 0%
-  Constraint Clarity       [░░░░░░░░░░░░░░░░░░░░] 0%
-  Example Coverage         [░░░░░░░░░░░░░░░░░░░░] 0%
-  Error Clarity            [████████████████████] 100%
   Identifier Clarity       [█████████████░░░░░░░] 67%
-  Dependency Clarity       [████████████████████] 100%
   Polymorphism Clarity     [████████████████████] 100%
   Discoverability          [████████████████████] 100%
 
@@ -40,14 +30,14 @@
   Top 2 Hotspot Operations
 
   GET /items (listItems)
-    Integration Simplicity: 51.0  Agent Readiness: 38.3
+    Agent Readiness: 44.2
     - Missing response examples
     - Missing operation description
     - No parameter descriptions
     - Ambiguous identifiers (2)
 
   POST /items (createItem)
-    Integration Simplicity: 57.5  Agent Readiness: 45.0
+    Agent Readiness: 50.7
     - Missing request and response examples
     - Missing operation description
 
diff --git a/tests/e2e/score/score-stylish/snapshot.txt b/tests/e2e/score/score-stylish/snapshot.txt
index b01965e05b..e1c6c3b044 100644
--- a/tests/e2e/score/score-stylish/snapshot.txt
+++ b/tests/e2e/score/score-stylish/snapshot.txt
@@ -1,10 +1,9 @@
 
   Scores
 
-  Integration Simplicity:  86.2/100
-  Agent Readiness:         90.2/100
+  Agent Readiness:  88.4/100
 
-  Integration Simplicity Subscores
+  Subscores
 
   Parameter Simplicity     [█████████████████░░░] 86%
   Schema Simplicity        [████████████████░░░░] 80%
@@ -13,16 +12,7 @@
   Example Coverage         [██████████████████░░] 88%
   Error Clarity            [████████████████████] 100%
   Dependency Clarity       [███████████████░░░░░] 73%
-  Discoverability          [████████████████████] 99%
-
-  Agent Readiness Subscores
-
-  Documentation Quality    [██████████████████░░] 90%
-  Constraint Clarity       [████████████░░░░░░░░] 58%
-  Example Coverage         [██████████████████░░] 88%
-  Error Clarity            [████████████████████] 100%
   Identifier Clarity       [████████████████████] 100%
-  Dependency Clarity       [███████████████░░░░░] 73%
   Polymorphism Clarity     [████████████████████] 100%
   Discoverability          [████████████████████] 99%
 
@@ -40,7 +30,7 @@
   Top 1 Hotspot Operations
 
   GET /tickets/{ticketId}/qr (getTicketCode)
-    Integration Simplicity: 83.0  Agent Readiness: 80.0
+    Agent Readiness: 81.0
     - Missing response examples
 
 

From 47a9667cdee54d78efc565dcc6b78cbf3388b204 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Tue, 7 Apr 2026 08:54:46 -0500
Subject: [PATCH 20/22] fix: address bugbot findings (round 3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove global stripCompositionKeywords that silently lost nested
  oneOf/anyOf within properties/items — the parentOnly shallow copy
  already prevents double-counting at the top level while preserving
  nested composition for walkSchemaRaw to count naturally
- Remove unused maxPropertiesGood threshold (dead code)
- Extract duplicate median function to shared utils.ts

Made-with: Cursor
---
 .../cli/src/commands/score/collect-metrics.ts | 409 ++++++++----------
 packages/cli/src/commands/score/constants.ts  |   1 -
 .../src/commands/score/formatters/stylish.ts  |   8 +-
 packages/cli/src/commands/score/scoring.ts    |   8 +-
 packages/cli/src/commands/score/types.ts      |   1 -
 packages/cli/src/commands/score/utils.ts      |   6 +
 6 files changed, 182 insertions(+), 251 deletions(-)
 create mode 100644 packages/cli/src/commands/score/utils.ts

diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index 625a25330e..60f003cf48 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -47,59 +47,6 @@ export interface CollectMetricsResult {
   debugLogs: DebugMediaTypeLog[];
 }
 
-interface StrippedComposition {
-  discriminator?: any;
-  oneOf?: any[];
-  anyOf?: any[];
-}
-
-function stripCompositionKeywords(parsed: any): Map<object, StrippedComposition> {
-  const removed = new Map<object, StrippedComposition>();
-  const seen = new WeakSet<object>();
-
-  function walk(node: any): void {
-    if (!node || typeof node !== 'object' || seen.has(node)) return;
-    seen.add(node);
-
-    const stripped: StrippedComposition = {};
-    let hasStripped = false;
-
-    if (node.discriminator?.mapping) {
-      stripped.discriminator = node.discriminator;
-      delete node.discriminator;
-      hasStripped = true;
-    }
-    if (Array.isArray(node.oneOf) && node.oneOf.length > 1) {
-      stripped.oneOf = node.oneOf;
-      delete node.oneOf;
-      hasStripped = true;
-    }
-    if (Array.isArray(node.anyOf) && node.anyOf.length > 1) {
-      stripped.anyOf = node.anyOf;
-      delete node.anyOf;
-      hasStripped = true;
-    }
-
-    if (hasStripped) removed.set(node, stripped);
-
-    for (const val of Object.values(node)) {
-      walk(val);
-    }
-  }
-
-  walk(parsed);
-  return removed;
-}
-
-function restoreCompositionKeywords(removed: Map<object, StrippedComposition>): void {
-  for (const [schema, stripped] of removed) {
-    const s = schema as any;
-    if (stripped.discriminator) s.discriminator = stripped.discriminator;
-    if (stripped.oneOf) s.oneOf = stripped.oneOf;
-    if (stripped.anyOf) s.anyOf = stripped.anyOf;
-  }
-}
-
 export function collectMetrics({
   document,
   types,
@@ -107,211 +54,203 @@ export function collectMetrics({
   ctx,
   debugOperationId,
 }: CollectMetricsOptions): CollectMetricsResult {
-  const removedComposition = stripCompositionKeywords(document.parsed);
-
-  try {
-    const schemaWalkState = createSchemaWalkState();
-    const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
-    const normalizedSchemaVisitors = normalizeVisitors(
-      [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor as any }],
-      types
-    );
-
-    const walkSchemaRaw = (schemaNode: any, debug: boolean): SchemaStats => {
-      resetSchemaWalkState(schemaWalkState);
-      if (debug) schemaWalkState.debugEntries = [];
-      walkDocument({
-        document: { ...document, parsed: schemaNode },
-        rootType: types.Schema,
-        normalizedVisitors: normalizedSchemaVisitors,
-        resolvedRefMap,
-        ctx,
-      });
-      const { depth: _, pendingRef: __, debugEntries: _debug, ...stats } = schemaWalkState;
-      return {
-        ...stats,
-        refsUsed: [...schemaWalkState.refsUsed],
-        debugEntries: debug ? (schemaWalkState.debugEntries ?? undefined) : undefined,
-      };
+  const schemaWalkState = createSchemaWalkState();
+  const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
+  const normalizedSchemaVisitors = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor as any }],
+    types
+  );
+
+  const walkSchemaRaw = (schemaNode: any, debug: boolean): SchemaStats => {
+    resetSchemaWalkState(schemaWalkState);
+    if (debug) schemaWalkState.debugEntries = [];
+    walkDocument({
+      document: { ...document, parsed: schemaNode },
+      rootType: types.Schema,
+      normalizedVisitors: normalizedSchemaVisitors,
+      resolvedRefMap,
+      ctx,
+    });
+    const { depth: _, pendingRef: __, debugEntries: _debug, ...stats } = schemaWalkState;
+    return {
+      ...stats,
+      refsUsed: [...schemaWalkState.refsUsed],
+      debugEntries: debug ? (schemaWalkState.debugEntries ?? undefined) : undefined,
     };
-
-    const schemaCache = new Map<string, SchemaStats>();
-    const computing = new WeakSet<object>();
-
-    const emptyStats: SchemaStats = {
-      maxDepth: 0,
-      polymorphismCount: 0,
-      anyOfCount: 0,
-      hasDiscriminator: false,
-      propertyCount: 0,
-      totalSchemaProperties: 0,
-      schemaPropertiesWithDescription: 0,
-      constraintCount: 0,
-      hasPropertyExamples: false,
-      writableTopLevelFields: 0,
-      refsUsed: [],
+  };
+
+  const schemaCache = new Map<string, SchemaStats>();
+  const computing = new WeakSet<object>();
+
+  const emptyStats: SchemaStats = {
+    maxDepth: 0,
+    polymorphismCount: 0,
+    anyOfCount: 0,
+    hasDiscriminator: false,
+    propertyCount: 0,
+    totalSchemaProperties: 0,
+    schemaPropertiesWithDescription: 0,
+    constraintCount: 0,
+    hasPropertyExamples: false,
+    writableTopLevelFields: 0,
+    refsUsed: [],
+  };
+
+  function addStats(a: SchemaStats, b: SchemaStats): SchemaStats {
+    return {
+      maxDepth: Math.max(a.maxDepth, b.maxDepth),
+      polymorphismCount: a.polymorphismCount + b.polymorphismCount,
+      anyOfCount: a.anyOfCount + b.anyOfCount,
+      hasDiscriminator: a.hasDiscriminator || b.hasDiscriminator,
+      propertyCount: a.propertyCount + b.propertyCount,
+      totalSchemaProperties: a.totalSchemaProperties + b.totalSchemaProperties,
+      schemaPropertiesWithDescription:
+        a.schemaPropertiesWithDescription + b.schemaPropertiesWithDescription,
+      constraintCount: a.constraintCount + b.constraintCount,
+      hasPropertyExamples: a.hasPropertyExamples || b.hasPropertyExamples,
+      writableTopLevelFields: a.writableTopLevelFields + b.writableTopLevelFields,
+      refsUsed: [...a.refsUsed, ...b.refsUsed],
+      debugEntries:
+        a.debugEntries || b.debugEntries
+          ? [...(a.debugEntries ?? []), ...(b.debugEntries ?? [])]
+          : undefined,
     };
+  }
 
-    function addStats(a: SchemaStats, b: SchemaStats): SchemaStats {
-      return {
-        maxDepth: Math.max(a.maxDepth, b.maxDepth),
-        polymorphismCount: a.polymorphismCount + b.polymorphismCount,
-        anyOfCount: a.anyOfCount + b.anyOfCount,
-        hasDiscriminator: a.hasDiscriminator || b.hasDiscriminator,
-        propertyCount: a.propertyCount + b.propertyCount,
-        totalSchemaProperties: a.totalSchemaProperties + b.totalSchemaProperties,
-        schemaPropertiesWithDescription:
-          a.schemaPropertiesWithDescription + b.schemaPropertiesWithDescription,
-        constraintCount: a.constraintCount + b.constraintCount,
-        hasPropertyExamples: a.hasPropertyExamples || b.hasPropertyExamples,
-        writableTopLevelFields: a.writableTopLevelFields + b.writableTopLevelFields,
-        refsUsed: [...a.refsUsed, ...b.refsUsed],
-        debugEntries:
-          a.debugEntries || b.debugEntries
-            ? [...(a.debugEntries ?? []), ...(b.debugEntries ?? [])]
-            : undefined,
-      };
-    }
-
-    const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
-      let resolved = schemaNode;
-      const ref: string | undefined = isRef(schemaNode) ? schemaNode.$ref : undefined;
-
-      if (ref) {
-        if (!debug) {
-          const cached = schemaCache.get(ref);
-          if (cached) return cached;
-        }
-        resolved = resolveJsonPointer(document.parsed, ref) ?? schemaNode;
-      }
+  const walkSchema = (schemaNode: any, debug = false): SchemaStats => {
+    let resolved = schemaNode;
+    const ref: string | undefined = isRef(schemaNode) ? schemaNode.$ref : undefined;
 
-      if (isPlainObject(resolved) && computing.has(resolved)) {
-        return { ...emptyStats };
+    if (ref) {
+      if (!debug) {
+        const cached = schemaCache.get(ref);
+        if (cached) return cached;
       }
-      if (isPlainObject(resolved)) {
-        computing.add(resolved);
-      }
-
-      const stripped = isPlainObject(resolved) ? removedComposition.get(resolved) : undefined;
-
-      const oneOfBranches = resolved?.oneOf ?? stripped?.oneOf;
-      const anyOfBranches = resolved?.anyOf ?? stripped?.anyOf;
-      const polyKeyword: 'oneOf' | 'anyOf' | null =
-        Array.isArray(oneOfBranches) && oneOfBranches.length > 1
-          ? 'oneOf'
-          : Array.isArray(anyOfBranches) && anyOfBranches.length > 1
-            ? 'anyOf'
-            : null;
-      const polyBranches: any[] | null =
-        polyKeyword === 'oneOf' ? oneOfBranches : polyKeyword === 'anyOf' ? anyOfBranches : null;
+      resolved = resolveJsonPointer(document.parsed, ref) ?? schemaNode;
+    }
 
-      const hasAllOf = Array.isArray(resolved?.allOf) && resolved.allOf.length > 0;
+    if (isPlainObject(resolved) && computing.has(resolved)) {
+      return { ...emptyStats };
+    }
+    if (isPlainObject(resolved)) {
+      computing.add(resolved);
+    }
 
-      const disc = resolved?.discriminator ?? stripped?.discriminator;
-      const discriminatorRefs =
-        !polyKeyword && isPlainObject(disc?.mapping)
-          ? Object.values(disc.mapping)
-              .filter((v): v is string => typeof v === 'string' && isMappingRef(v))
-              .map((v) => ({ $ref: v }))
+    const oneOfBranches = resolved?.oneOf;
+    const anyOfBranches = resolved?.anyOf;
+    const polyKeyword: 'oneOf' | 'anyOf' | null =
+      Array.isArray(oneOfBranches) && oneOfBranches.length > 1
+        ? 'oneOf'
+        : Array.isArray(anyOfBranches) && anyOfBranches.length > 1
+          ? 'anyOf'
           : null;
-      const hasDiscriminatorBranches =
-        Array.isArray(discriminatorRefs) && discriminatorRefs.length > 0;
-
-      let result: SchemaStats;
-
-      if (polyKeyword || hasAllOf || hasDiscriminatorBranches) {
-        const parentOnly = { ...resolved };
-
-        let polyStats: SchemaStats | null = null;
-        if (polyKeyword && polyBranches) {
-          delete parentOnly[polyKeyword];
-          delete parentOnly.discriminator;
-
-          let maxBranch = walkSchema(polyBranches[0], debug);
-          for (let i = 1; i < polyBranches.length; i++) {
-            const branchStats = walkSchema(polyBranches[i], debug);
-            if (branchStats.propertyCount > maxBranch.propertyCount) {
-              maxBranch = branchStats;
-            }
+    const polyBranches: any[] | null =
+      polyKeyword === 'oneOf' ? oneOfBranches : polyKeyword === 'anyOf' ? anyOfBranches : null;
+
+    const hasAllOf = Array.isArray(resolved?.allOf) && resolved.allOf.length > 0;
+
+    const disc = resolved?.discriminator;
+    const discriminatorRefs =
+      !polyKeyword && isPlainObject(disc?.mapping)
+        ? Object.values(disc.mapping)
+            .filter((v): v is string => typeof v === 'string' && isMappingRef(v))
+            .map((v) => ({ $ref: v }))
+        : null;
+    const hasDiscriminatorBranches =
+      Array.isArray(discriminatorRefs) && discriminatorRefs.length > 0;
+
+    let result: SchemaStats;
+
+    if (polyKeyword || hasAllOf || hasDiscriminatorBranches) {
+      const parentOnly = { ...resolved };
+
+      let polyStats: SchemaStats | null = null;
+      if (polyKeyword && polyBranches) {
+        delete parentOnly[polyKeyword];
+        delete parentOnly.discriminator;
+
+        let maxBranch = walkSchema(polyBranches[0], debug);
+        for (let i = 1; i < polyBranches.length; i++) {
+          const branchStats = walkSchema(polyBranches[i], debug);
+          if (branchStats.propertyCount > maxBranch.propertyCount) {
+            maxBranch = branchStats;
           }
-          polyStats = {
-            ...maxBranch,
-            polymorphismCount: maxBranch.polymorphismCount + polyBranches.length,
-            anyOfCount: maxBranch.anyOfCount + (polyKeyword === 'anyOf' ? polyBranches.length : 0),
-            hasDiscriminator: maxBranch.hasDiscriminator || !!disc,
-          };
         }
+        polyStats = {
+          ...maxBranch,
+          polymorphismCount: maxBranch.polymorphismCount + polyBranches.length,
+          anyOfCount: maxBranch.anyOfCount + (polyKeyword === 'anyOf' ? polyBranches.length : 0),
+          hasDiscriminator: maxBranch.hasDiscriminator || !!disc,
+        };
+      }
 
-        let discStats: SchemaStats | null = null;
-        if (hasDiscriminatorBranches) {
-          delete parentOnly.discriminator;
+      let discStats: SchemaStats | null = null;
+      if (hasDiscriminatorBranches) {
+        delete parentOnly.discriminator;
 
-          let maxBranch = walkSchema(discriminatorRefs[0], debug);
-          for (let i = 1; i < discriminatorRefs.length; i++) {
-            const branchStats = walkSchema(discriminatorRefs[i], debug);
-            if (branchStats.propertyCount > maxBranch.propertyCount) {
-              maxBranch = branchStats;
-            }
+        let maxBranch = walkSchema(discriminatorRefs[0], debug);
+        for (let i = 1; i < discriminatorRefs.length; i++) {
+          const branchStats = walkSchema(discriminatorRefs[i], debug);
+          if (branchStats.propertyCount > maxBranch.propertyCount) {
+            maxBranch = branchStats;
           }
-          discStats = {
-            ...maxBranch,
-            polymorphismCount: maxBranch.polymorphismCount + discriminatorRefs.length,
-            hasDiscriminator: true,
-          };
         }
+        discStats = {
+          ...maxBranch,
+          polymorphismCount: maxBranch.polymorphismCount + discriminatorRefs.length,
+          hasDiscriminator: true,
+        };
+      }
 
-        let allOfStats: SchemaStats | null = null;
-        if (hasAllOf) {
-          delete parentOnly.allOf;
-          allOfStats = { ...emptyStats };
-          for (const member of resolved.allOf) {
-            allOfStats = addStats(allOfStats, walkSchema(member, debug));
-          }
-          allOfStats.polymorphismCount += resolved.allOf.length;
+      let allOfStats: SchemaStats | null = null;
+      if (hasAllOf) {
+        delete parentOnly.allOf;
+        allOfStats = { ...emptyStats };
+        for (const member of resolved.allOf) {
+          allOfStats = addStats(allOfStats, walkSchema(member, debug));
         }
-
-        const parentStats = walkSchemaRaw(parentOnly, debug);
-        result = parentStats;
-        if (allOfStats) result = addStats(result, allOfStats);
-        if (polyStats) result = addStats(result, polyStats);
-        if (discStats) result = addStats(result, discStats);
-      } else {
-        result = walkSchemaRaw(schemaNode, debug);
+        allOfStats.polymorphismCount += resolved.allOf.length;
       }
 
-      if (isPlainObject(resolved)) {
-        computing.delete(resolved);
-      }
-      if (ref && !debug) {
-        schemaCache.set(ref, result);
-      }
+      const parentStats = walkSchemaRaw(parentOnly, debug);
+      result = parentStats;
+      if (allOfStats) result = addStats(result, allOfStats);
+      if (polyStats) result = addStats(result, polyStats);
+      if (discStats) result = addStats(result, discStats);
+    } else {
+      result = walkSchemaRaw(schemaNode, debug);
+    }
 
-      return result;
-    };
+    if (isPlainObject(resolved)) {
+      computing.delete(resolved);
+    }
+    if (ref && !debug) {
+      schemaCache.set(ref, result);
+    }
 
-    const accumulator = createScoreAccumulator(walkSchema, debugOperationId);
-    const scoreVisitor = createScoreVisitor(accumulator);
+    return result;
+  };
 
-    const normalizedVisitors = normalizeVisitors(
-      [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
-      types
-    );
+  const accumulator = createScoreAccumulator(walkSchema, debugOperationId);
+  const scoreVisitor = createScoreVisitor(accumulator);
 
-    walkDocument({
-      document,
-      rootType: types.Root,
-      normalizedVisitors,
-      resolvedRefMap,
-      ctx,
-    });
+  const normalizedVisitors = normalizeVisitors(
+    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
+    types
+  );
 
-    return {
-      metrics: getDocumentMetrics(accumulator),
-      debugLogs: accumulator.debugLogs,
-    };
-  } finally {
-    restoreCompositionKeywords(removedComposition);
-  }
+  walkDocument({
+    document,
+    rootType: types.Root,
+    normalizedVisitors,
+    resolvedRefMap,
+    ctx,
+  });
+
+  return {
+    metrics: getDocumentMetrics(accumulator),
+    debugLogs: accumulator.debugLogs,
+  };
 }
 
 /**
diff --git a/packages/cli/src/commands/score/constants.ts b/packages/cli/src/commands/score/constants.ts
index e2d1dbfc36..5b2e07ac9f 100644
--- a/packages/cli/src/commands/score/constants.ts
+++ b/packages/cli/src/commands/score/constants.ts
@@ -5,7 +5,6 @@ export const DEFAULT_SCORING_CONSTANTS: ScoringConstants = {
     maxParamsGood: 5,
     maxDepthGood: 4,
     maxPolymorphismGood: 2,
-    maxPropertiesGood: 20,
     maxDependencyDepthGood: 3,
     maxAmbiguousGood: 0,
     maxOperationsForDiscoverability: 1000,
diff --git a/packages/cli/src/commands/score/formatters/stylish.ts b/packages/cli/src/commands/score/formatters/stylish.ts
index 449a022def..0c3412805a 100644
--- a/packages/cli/src/commands/score/formatters/stylish.ts
+++ b/packages/cli/src/commands/score/formatters/stylish.ts
@@ -2,6 +2,7 @@ import { logger } from '@redocly/openapi-core';
 import { bold, cyan, green, red, white, yellow } from 'colorette';
 
 import type { DebugMediaTypeLog, ScoreResult } from '../types.js';
+import { median } from '../utils.js';
 
 export function printScoreStylish(result: ScoreResult, operationDetails = false): void {
   printScores(result);
@@ -62,13 +63,6 @@ function buildBar(fraction: number): string {
   return cyan('[' + '\u2588'.repeat(filled) + '\u2591'.repeat(width - filled) + ']');
 }
 
-function median(values: number[]): number {
-  if (values.length === 0) return 0;
-  const sorted = [...values].sort((a, b) => a - b);
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
-}
-
 function printRawMetricsSummary(result: ScoreResult): void {
   out(bold(white('  Raw Metrics Summary')));
   out('');
diff --git a/packages/cli/src/commands/score/scoring.ts b/packages/cli/src/commands/score/scoring.ts
index 8f6a946a76..ead123c4f2 100644
--- a/packages/cli/src/commands/score/scoring.ts
+++ b/packages/cli/src/commands/score/scoring.ts
@@ -6,6 +6,7 @@ import type {
   ScoringConstants,
   Subscores,
 } from './types.js';
+import { median } from './utils.js';
 
 export function computeOperationSubscores(
   metrics: OperationMetrics,
@@ -187,13 +188,6 @@ export function aggregateSubscores(
   return result;
 }
 
-function median(values: number[]): number {
-  if (values.length === 0) return 0;
-  const sorted = [...values].sort((a, b) => a - b);
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
-}
-
 function round(value: number): number {
   return Math.round(value * 10) / 10;
 }
diff --git a/packages/cli/src/commands/score/types.ts b/packages/cli/src/commands/score/types.ts
index 0d6380ed08..0bafddd89b 100644
--- a/packages/cli/src/commands/score/types.ts
+++ b/packages/cli/src/commands/score/types.ts
@@ -78,7 +78,6 @@ export interface ScoringThresholds {
   maxParamsGood: number;
   maxDepthGood: number;
   maxPolymorphismGood: number;
-  maxPropertiesGood: number;
   maxDependencyDepthGood: number;
   maxAmbiguousGood: number;
   maxOperationsForDiscoverability: number;
diff --git a/packages/cli/src/commands/score/utils.ts b/packages/cli/src/commands/score/utils.ts
new file mode 100644
index 0000000000..aa79564d5e
--- /dev/null
+++ b/packages/cli/src/commands/score/utils.ts
@@ -0,0 +1,6 @@
+export function median(values: number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}

From edcd5a7471f911ebc09e11956d95fe918fef16c4 Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Tue, 7 Apr 2026 21:49:35 -0500
Subject: [PATCH 21/22] refactor: address tatomyr review feedback (round 4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove as any casts from normalizeVisitors — types infer correctly
- Remove redundant propertyCount (always equals totalSchemaProperties)
- Fix constraintCount mixing across media types — keep all three
  correlated metrics from the same schema walk
- Consolidate CurrentOperationContext with OperationMetrics field names,
  simplify buildOperationMetrics to destructuring spread
- Export Oas3MediaType from openapi-core, use in hasExample signature
- Remove any type on MediaType.enter — visitor infers type by default
- Move collectDocumentMetrics to __tests__/collect-metrics-helper.ts
  since it is test-only code

Made-with: Cursor
---
 .../score/__tests__/collect-metrics-helper.ts |  41 +++++
 .../score/__tests__/dependency-graph.test.ts  |   1 -
 .../score/__tests__/document-metrics.test.ts  |   4 +-
 .../score/__tests__/example-coverage.test.ts  |   2 +-
 .../commands/score/__tests__/hotspots.test.ts |   1 -
 .../commands/score/__tests__/index.test.ts    |   1 -
 .../commands/score/__tests__/scoring.test.ts  |   3 -
 .../cli/src/commands/score/collect-metrics.ts |  47 +-----
 .../score/collectors/document-metrics.ts      |  57 ++-----
 .../src/commands/score/formatters/stylish.ts  |   6 +-
 packages/cli/src/commands/score/types.ts      |   2 -
 packages/core/src/index.ts                    |   1 +
 tests/e2e/score/score-json/snapshot.txt       | 150 +++++++++---------
 tests/e2e/score/score-stylish/snapshot.txt    |   6 +-
 14 files changed, 145 insertions(+), 177 deletions(-)
 create mode 100644 packages/cli/src/commands/score/__tests__/collect-metrics-helper.ts

diff --git a/packages/cli/src/commands/score/__tests__/collect-metrics-helper.ts b/packages/cli/src/commands/score/__tests__/collect-metrics-helper.ts
new file mode 100644
index 0000000000..c4ad392fa0
--- /dev/null
+++ b/packages/cli/src/commands/score/__tests__/collect-metrics-helper.ts
@@ -0,0 +1,41 @@
+import {
+  normalizeTypes,
+  getTypes,
+  resolveDocument,
+  BaseResolver,
+  Source,
+  type Document,
+  type SpecVersion,
+  type WalkContext,
+} from '@redocly/openapi-core';
+
+import { collectMetrics, type CollectMetricsResult } from '../collect-metrics.js';
+
+/**
+ * Convenience wrapper that resolves a parsed OpenAPI document and collects metrics.
+ * Useful in tests where you don't already have resolved types.
+ */
+export async function collectDocumentMetrics(
+  parsed: Record<string, unknown>,
+  options?: { specVersion?: SpecVersion; debugOperationId?: string }
+): Promise<CollectMetricsResult> {
+  const specVersion: SpecVersion = options?.specVersion ?? 'oas3_0';
+  const types = normalizeTypes(getTypes(specVersion), {});
+  const source = new Source('score.yaml', JSON.stringify(parsed));
+  const document: Document = { source, parsed };
+  const externalRefResolver = new BaseResolver();
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.Root,
+    externalRefResolver,
+  });
+  const ctx: WalkContext = { problems: [], specVersion, visitorsData: {} };
+
+  return collectMetrics({
+    document,
+    types,
+    resolvedRefMap,
+    ctx,
+    debugOperationId: options?.debugOperationId,
+  });
+}
diff --git a/packages/cli/src/commands/score/__tests__/dependency-graph.test.ts b/packages/cli/src/commands/score/__tests__/dependency-graph.test.ts
index ad3a6ce8f7..817a8e1087 100644
--- a/packages/cli/src/commands/score/__tests__/dependency-graph.test.ts
+++ b/packages/cli/src/commands/score/__tests__/dependency-graph.test.ts
@@ -15,7 +15,6 @@ function makeOp(path: string, method: string, refs: string[]): OperationMetrics
     polymorphismCount: 0,
     anyOfCount: 0,
     hasDiscriminator: false,
-    propertyCount: 0,
     operationDescriptionPresent: false,
     schemaPropertiesWithDescription: 0,
     totalSchemaProperties: 0,
diff --git a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
index 3e46515c4c..5c4460c59d 100644
--- a/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
+++ b/packages/cli/src/commands/score/__tests__/document-metrics.test.ts
@@ -1,7 +1,7 @@
 import { parseYaml } from '@redocly/openapi-core';
 import { outdent } from 'outdent';
 
-import { collectDocumentMetrics } from '../collect-metrics.js';
+import { collectDocumentMetrics } from './collect-metrics-helper.js';
 
 const yaml = (source: string) => parseYaml(source) as Record<string, unknown>;
 
@@ -131,7 +131,7 @@ describe('collectDocumentMetrics', () => {
     const op = metrics.operations.get('createItem')!;
     expect(op.requestBodyPresent).toBe(true);
     expect(op.requestExamplePresent).toBe(true);
-    expect(op.propertyCount).toBe(2);
+    expect(op.totalSchemaProperties).toBe(2);
     expect(op.constraintCount).toBe(2);
     expect(op.schemaPropertiesWithDescription).toBe(1);
   });
diff --git a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
index 9ead3002a9..11b3dae983 100644
--- a/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
+++ b/packages/cli/src/commands/score/__tests__/example-coverage.test.ts
@@ -1,5 +1,5 @@
-import { collectDocumentMetrics } from '../collect-metrics.js';
 import { computeOperationSubscores, computeAgentReadiness } from '../scoring.js';
+import { collectDocumentMetrics } from './collect-metrics-helper.js';
 
 async function collect(doc: Record<string, unknown>) {
   return (await collectDocumentMetrics(doc)).metrics;
diff --git a/packages/cli/src/commands/score/__tests__/hotspots.test.ts b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
index 8a7d6efd33..0cc6ee65c7 100644
--- a/packages/cli/src/commands/score/__tests__/hotspots.test.ts
+++ b/packages/cli/src/commands/score/__tests__/hotspots.test.ts
@@ -16,7 +16,6 @@ function makeMetrics(overrides: Partial<OperationMetrics> = {}): OperationMetric
     polymorphismCount: 0,
     anyOfCount: 0,
     hasDiscriminator: false,
-    propertyCount: 0,
     operationDescriptionPresent: true,
     schemaPropertiesWithDescription: 0,
     totalSchemaProperties: 0,
diff --git a/packages/cli/src/commands/score/__tests__/index.test.ts b/packages/cli/src/commands/score/__tests__/index.test.ts
index a5a194f7c1..c4db442052 100644
--- a/packages/cli/src/commands/score/__tests__/index.test.ts
+++ b/packages/cli/src/commands/score/__tests__/index.test.ts
@@ -51,7 +51,6 @@ function makeTestMetrics(overrides: Partial<OperationMetrics> = {}): OperationMe
     polymorphismCount: 0,
     anyOfCount: 0,
     hasDiscriminator: false,
-    propertyCount: 1,
     operationDescriptionPresent: true,
     schemaPropertiesWithDescription: 0,
     totalSchemaProperties: 1,
diff --git a/packages/cli/src/commands/score/__tests__/scoring.test.ts b/packages/cli/src/commands/score/__tests__/scoring.test.ts
index 658750d8c7..11b4f55551 100644
--- a/packages/cli/src/commands/score/__tests__/scoring.test.ts
+++ b/packages/cli/src/commands/score/__tests__/scoring.test.ts
@@ -23,7 +23,6 @@ function makeBaseMetrics(overrides: Partial<OperationMetrics> = {}): OperationMe
     polymorphismCount: 0,
     anyOfCount: 0,
     hasDiscriminator: false,
-    propertyCount: 0,
     operationDescriptionPresent: true,
     schemaPropertiesWithDescription: 0,
     totalSchemaProperties: 0,
@@ -132,7 +131,6 @@ describe('scoring', () => {
               parameterCount: 1,
               requiredParameterCount: 1,
               paramsWithDescription: 0,
-              propertyCount: 1,
               totalSchemaProperties: 1,
               maxResponseSchemaDepth: 1,
             }),
@@ -146,7 +144,6 @@ describe('scoring', () => {
               requestBodyPresent: true,
               requestExamplePresent: true,
               constraintCount: 1,
-              propertyCount: 2,
               totalSchemaProperties: 2,
               maxRequestSchemaDepth: 1,
               maxResponseSchemaDepth: 1,
diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index 60f003cf48..53b9e32a29 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -1,17 +1,13 @@
 import {
-  normalizeTypes,
-  getTypes,
+  type normalizeTypes,
   normalizeVisitors,
   walkDocument,
-  resolveDocument,
-  BaseResolver,
-  Source,
+  type resolveDocument,
   isPlainObject,
   isRef,
   isMappingRef,
   unescapePointerFragment,
   type Document,
-  type SpecVersion,
   type WalkContext,
 } from '@redocly/openapi-core';
 
@@ -57,7 +53,7 @@ export function collectMetrics({
   const schemaWalkState = createSchemaWalkState();
   const schemaVisitor = createSchemaMetricVisitor(schemaWalkState);
   const normalizedSchemaVisitors = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor as any }],
+    [{ severity: 'warn', ruleId: 'score-schema', visitor: schemaVisitor }],
     types
   );
 
@@ -87,7 +83,6 @@ export function collectMetrics({
     polymorphismCount: 0,
     anyOfCount: 0,
     hasDiscriminator: false,
-    propertyCount: 0,
     totalSchemaProperties: 0,
     schemaPropertiesWithDescription: 0,
     constraintCount: 0,
@@ -102,7 +97,6 @@ export function collectMetrics({
       polymorphismCount: a.polymorphismCount + b.polymorphismCount,
       anyOfCount: a.anyOfCount + b.anyOfCount,
       hasDiscriminator: a.hasDiscriminator || b.hasDiscriminator,
-      propertyCount: a.propertyCount + b.propertyCount,
       totalSchemaProperties: a.totalSchemaProperties + b.totalSchemaProperties,
       schemaPropertiesWithDescription:
         a.schemaPropertiesWithDescription + b.schemaPropertiesWithDescription,
@@ -172,7 +166,7 @@ export function collectMetrics({
         let maxBranch = walkSchema(polyBranches[0], debug);
         for (let i = 1; i < polyBranches.length; i++) {
           const branchStats = walkSchema(polyBranches[i], debug);
-          if (branchStats.propertyCount > maxBranch.propertyCount) {
+          if (branchStats.totalSchemaProperties > maxBranch.totalSchemaProperties) {
             maxBranch = branchStats;
           }
         }
@@ -191,7 +185,7 @@ export function collectMetrics({
         let maxBranch = walkSchema(discriminatorRefs[0], debug);
         for (let i = 1; i < discriminatorRefs.length; i++) {
           const branchStats = walkSchema(discriminatorRefs[i], debug);
-          if (branchStats.propertyCount > maxBranch.propertyCount) {
+          if (branchStats.totalSchemaProperties > maxBranch.totalSchemaProperties) {
             maxBranch = branchStats;
           }
         }
@@ -235,7 +229,7 @@ export function collectMetrics({
   const scoreVisitor = createScoreVisitor(accumulator);
 
   const normalizedVisitors = normalizeVisitors(
-    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor as any }],
+    [{ severity: 'warn', ruleId: 'score', visitor: scoreVisitor }],
     types
   );
 
@@ -252,32 +246,3 @@ export function collectMetrics({
     debugLogs: accumulator.debugLogs,
   };
 }
-
-/**
- * Convenience wrapper that resolves a parsed OpenAPI document and collects metrics.
- * Useful in tests and standalone usage where you don't already have resolved types.
- */
-export async function collectDocumentMetrics(
-  parsed: Record<string, unknown>,
-  options?: { specVersion?: SpecVersion; debugOperationId?: string }
-): Promise<CollectMetricsResult> {
-  const specVersion: SpecVersion = options?.specVersion ?? 'oas3_0';
-  const types = normalizeTypes(getTypes(specVersion), {});
-  const source = new Source('score.yaml', JSON.stringify(parsed));
-  const document: Document = { source, parsed };
-  const externalRefResolver = new BaseResolver();
-  const resolvedRefMap = await resolveDocument({
-    rootDocument: document,
-    rootType: types.Root,
-    externalRefResolver,
-  });
-  const ctx: WalkContext = { problems: [], specVersion, visitorsData: {} };
-
-  return collectMetrics({
-    document,
-    types,
-    resolvedRefMap,
-    ctx,
-    debugOperationId: options?.debugOperationId,
-  });
-}
diff --git a/packages/cli/src/commands/score/collectors/document-metrics.ts b/packages/cli/src/commands/score/collectors/document-metrics.ts
index 8c70b80d7c..ee93cf20d9 100644
--- a/packages/cli/src/commands/score/collectors/document-metrics.ts
+++ b/packages/cli/src/commands/score/collectors/document-metrics.ts
@@ -1,6 +1,7 @@
 import {
   isNotEmptyObject,
   isPlainObject,
+  type Oas3MediaType,
   type Oas3Visitor,
   type UserContext,
   type Oas3PathItem,
@@ -49,7 +50,6 @@ export interface SchemaWalkState {
   polymorphismCount: number;
   anyOfCount: number;
   hasDiscriminator: boolean;
-  propertyCount: number;
   totalSchemaProperties: number;
   schemaPropertiesWithDescription: number;
   constraintCount: number;
@@ -68,7 +68,6 @@ export function createSchemaWalkState(): SchemaWalkState {
     polymorphismCount: 0,
     anyOfCount: 0,
     hasDiscriminator: false,
-    propertyCount: 0,
     totalSchemaProperties: 0,
     schemaPropertiesWithDescription: 0,
     constraintCount: 0,
@@ -122,7 +121,6 @@ export function createSchemaMetricVisitor(state: SchemaWalkState): Oas3Visitor {
         if (isPlainObject(schema.properties)) {
           const props = Object.entries(schema.properties) as [string, any][];
           state.totalSchemaProperties += props.length;
-          state.propertyCount += props.length;
 
           for (const [name, prop] of props) {
             localPropertyNames.push(name);
@@ -166,7 +164,6 @@ interface CurrentOperationContext {
 
   maxRequestSchemaDepth: number;
   maxResponseSchemaDepth: number;
-  propertyCount: number;
   totalSchemaProperties: number;
   schemaPropertiesWithDescription: number;
   constraintCount: number;
@@ -174,7 +171,7 @@ interface CurrentOperationContext {
   anyOfCount: number;
   hasDiscriminator: boolean;
 
-  writableTopLevelFieldCount: number;
+  topLevelWritableFieldCount: number;
 
   requestBodyPresent: boolean;
   requestExamplePresent: boolean;
@@ -233,7 +230,6 @@ function createOperationContext(
 
     maxRequestSchemaDepth: 0,
     maxResponseSchemaDepth: 0,
-    propertyCount: 0,
     totalSchemaProperties: 0,
     schemaPropertiesWithDescription: 0,
     constraintCount: 0,
@@ -241,7 +237,7 @@ function createOperationContext(
     anyOfCount: 0,
     hasDiscriminator: false,
 
-    writableTopLevelFieldCount: 0,
+    topLevelWritableFieldCount: 0,
 
     requestBodyPresent: false,
     requestExamplePresent: false,
@@ -259,32 +255,14 @@ function createOperationContext(
 }
 
 function buildOperationMetrics(ctx: CurrentOperationContext): OperationMetrics {
-  return {
-    path: ctx.path,
-    method: ctx.method,
-    operationId: ctx.operationId,
-    parameterCount: ctx.parameterCount,
-    requiredParameterCount: ctx.requiredParameterCount,
-    paramsWithDescription: ctx.paramsWithDescription,
-    requestBodyPresent: ctx.requestBodyPresent,
-    topLevelWritableFieldCount: ctx.writableTopLevelFieldCount,
-    maxRequestSchemaDepth: ctx.maxRequestSchemaDepth,
-    maxResponseSchemaDepth: ctx.maxResponseSchemaDepth,
-    polymorphismCount: ctx.polymorphismCount,
-    anyOfCount: ctx.anyOfCount,
-    hasDiscriminator: ctx.hasDiscriminator,
-    propertyCount: ctx.propertyCount,
-    operationDescriptionPresent: ctx.operationDescriptionPresent,
-    schemaPropertiesWithDescription: ctx.schemaPropertiesWithDescription,
-    totalSchemaProperties: ctx.totalSchemaProperties,
-    constraintCount: ctx.constraintCount,
-    requestExamplePresent: ctx.requestExamplePresent,
-    responseExamplePresent: ctx.responseExamplePresent,
-    structuredErrorResponseCount: ctx.structuredErrorResponseCount,
-    totalErrorResponses: ctx.totalErrorResponses,
-    ambiguousIdentifierCount: ctx.ambiguousIdentifierCount,
-    refsUsed: ctx.refsUsed,
-  };
+  const {
+    inRequestBody: _1,
+    inResponse: _2,
+    currentResponseCode: _3,
+    errorStructuredCounted: _4,
+    ...metrics
+  } = ctx;
+  return metrics;
 }
 
 export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
@@ -324,7 +302,7 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
       },
     },
     MediaType: {
-      enter(mediaType: any) {
+      enter(mediaType) {
         const current = accumulator.current;
         if (!current) return;
 
@@ -350,12 +328,11 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
 
           const stats = accumulator.walkSchema(mediaType.schema, isDebugTarget);
 
-          current.propertyCount = Math.max(current.propertyCount, stats.propertyCount);
           if (stats.totalSchemaProperties > current.totalSchemaProperties) {
             current.totalSchemaProperties = stats.totalSchemaProperties;
             current.schemaPropertiesWithDescription = stats.schemaPropertiesWithDescription;
+            current.constraintCount = stats.constraintCount;
           }
-          current.constraintCount = Math.max(current.constraintCount, stats.constraintCount);
           current.polymorphismCount = Math.max(current.polymorphismCount, stats.polymorphismCount);
           current.anyOfCount = Math.max(current.anyOfCount, stats.anyOfCount);
           if (stats.hasDiscriminator) current.hasDiscriminator = true;
@@ -369,8 +346,8 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
 
           if (current.inRequestBody) {
             current.maxRequestSchemaDepth = Math.max(current.maxRequestSchemaDepth, stats.maxDepth);
-            current.writableTopLevelFieldCount = Math.max(
-              current.writableTopLevelFieldCount,
+            current.topLevelWritableFieldCount = Math.max(
+              current.topLevelWritableFieldCount,
               stats.writableTopLevelFields
             );
           }
@@ -388,7 +365,7 @@ export function createScoreVisitor(accumulator: ScoreAccumulator): Oas3Visitor {
             accumulator.debugLogs.push({
               context,
               entries: stats.debugEntries,
-              totalProperties: stats.propertyCount,
+              totalProperties: stats.totalSchemaProperties,
               totalPolymorphism: stats.polymorphismCount,
               totalConstraints: stats.constraintCount,
               maxDepth: stats.maxDepth,
@@ -460,7 +437,7 @@ function mergeParameters(
   return merged;
 }
 
-function hasExample(mediaType: { example?: unknown; examples?: Record<string, unknown> }): boolean {
+function hasExample(mediaType: Oas3MediaType): boolean {
   return mediaType.example !== undefined || isNotEmptyObject(mediaType.examples);
 }
 
diff --git a/packages/cli/src/commands/score/formatters/stylish.ts b/packages/cli/src/commands/score/formatters/stylish.ts
index 0c3412805a..088308104a 100644
--- a/packages/cli/src/commands/score/formatters/stylish.ts
+++ b/packages/cli/src/commands/score/formatters/stylish.ts
@@ -85,7 +85,7 @@ function printRawMetricsSummary(result: ScoreResult): void {
     params.push(m.parameterCount);
     depths.push(Math.max(m.maxRequestSchemaDepth, m.maxResponseSchemaDepth));
     polys.push(m.polymorphismCount);
-    props.push(m.propertyCount);
+    props.push(m.totalSchemaProperties);
     if (m.requestExamplePresent) opsWithReqExample++;
     if (m.responseExamplePresent) opsWithResExample++;
     if (m.operationDescriptionPresent) opsWithDescription++;
@@ -140,7 +140,7 @@ function printOperationDetails(result: ScoreResult): void {
   out(cyan('  ' + '─'.repeat(header.length - 2)));
 
   const entries = [...result.rawMetrics.operations.entries()].sort(
-    ([, a], [, b]) => b.propertyCount - a.propertyCount
+    ([, a], [, b]) => b.totalSchemaProperties - a.totalSchemaProperties
   );
 
   for (const [, m] of entries) {
@@ -149,7 +149,7 @@ function printOperationDetails(result: ScoreResult): void {
     const line =
       '  ' +
       label.padEnd(50) +
-      String(m.propertyCount).padStart(7) +
+      String(m.totalSchemaProperties).padStart(7) +
       String(m.polymorphismCount).padStart(7) +
       String(depth).padStart(7) +
       String(m.parameterCount).padStart(8) +
diff --git a/packages/cli/src/commands/score/types.ts b/packages/cli/src/commands/score/types.ts
index 0bafddd89b..dbc3b8a840 100644
--- a/packages/cli/src/commands/score/types.ts
+++ b/packages/cli/src/commands/score/types.ts
@@ -15,7 +15,6 @@ export interface OperationMetrics {
   polymorphismCount: number;
   anyOfCount: number;
   hasDiscriminator: boolean;
-  propertyCount: number;
 
   operationDescriptionPresent: boolean;
   schemaPropertiesWithDescription: number;
@@ -125,7 +124,6 @@ export interface SchemaStats {
   polymorphismCount: number;
   anyOfCount: number;
   hasDiscriminator: boolean;
-  propertyCount: number;
   totalSchemaProperties: number;
   schemaPropertiesWithDescription: number;
   constraintCount: number;
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 15b4f7591f..c0d8b45678 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -145,6 +145,7 @@ export type {
   Oas3Parameter,
   Oas3Server,
   Oas3Operation,
+  Oas3MediaType,
   Oas3Responses,
   ApiKeyAuth,
   HttpAuth,
diff --git a/tests/e2e/score/score-json/snapshot.txt b/tests/e2e/score/score-json/snapshot.txt
index 13a5f14862..748cc341e9 100644
--- a/tests/e2e/score/score-json/snapshot.txt
+++ b/tests/e2e/score/score-json/snapshot.txt
@@ -1,11 +1,11 @@
 {
-  "agentReadiness": 88.4,
+  "agentReadiness": 88.2,
   "discoverability": 99,
   "subscores": {
     "parameterSimplicity": 0.8625,
     "schemaSimplicity": 0.796875,
     "documentationQuality": 0.9017857142857143,
-    "constraintClarity": 0.5833333333333333,
+    "constraintClarity": 0.4375,
     "exampleCoverage": 0.875,
     "errorClarity": 1,
     "dependencyClarity": 0.7291666666666669,
@@ -19,201 +19,193 @@
         "path": "/museum-hours",
         "method": "get",
         "operationId": "getMuseumHours",
+        "operationDescriptionPresent": true,
         "parameterCount": 3,
         "requiredParameterCount": 0,
         "paramsWithDescription": 3,
-        "requestBodyPresent": false,
-        "topLevelWritableFieldCount": 0,
+        "ambiguousIdentifierCount": 0,
         "maxRequestSchemaDepth": 0,
         "maxResponseSchemaDepth": 2,
+        "totalSchemaProperties": 3,
+        "schemaPropertiesWithDescription": 2,
+        "constraintCount": 3,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 3,
-        "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 2,
-        "totalSchemaProperties": 3,
-        "constraintCount": 3,
+        "topLevelWritableFieldCount": 0,
+        "requestBodyPresent": false,
         "requestExamplePresent": false,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 2,
-        "totalErrorResponses": 2,
-        "ambiguousIdentifierCount": 0
+        "totalErrorResponses": 2
       },
       "listSpecialEvents": {
         "path": "/special-events",
         "method": "get",
         "operationId": "listSpecialEvents",
+        "operationDescriptionPresent": true,
         "parameterCount": 4,
         "requiredParameterCount": 0,
         "paramsWithDescription": 4,
-        "requestBodyPresent": false,
-        "topLevelWritableFieldCount": 0,
+        "ambiguousIdentifierCount": 0,
         "maxRequestSchemaDepth": 0,
         "maxResponseSchemaDepth": 3,
+        "totalSchemaProperties": 6,
+        "schemaPropertiesWithDescription": 6,
+        "constraintCount": 3,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 6,
-        "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 6,
-        "totalSchemaProperties": 6,
-        "constraintCount": 3,
+        "topLevelWritableFieldCount": 0,
+        "requestBodyPresent": false,
         "requestExamplePresent": false,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
-        "totalErrorResponses": 0,
-        "ambiguousIdentifierCount": 0
+        "totalErrorResponses": 0
       },
       "createSpecialEvent": {
         "path": "/special-events",
         "method": "post",
         "operationId": "createSpecialEvent",
+        "operationDescriptionPresent": true,
         "parameterCount": 0,
         "requiredParameterCount": 0,
         "paramsWithDescription": 0,
-        "requestBodyPresent": true,
-        "topLevelWritableFieldCount": 5,
+        "ambiguousIdentifierCount": 0,
         "maxRequestSchemaDepth": 2,
         "maxResponseSchemaDepth": 2,
+        "totalSchemaProperties": 6,
+        "schemaPropertiesWithDescription": 6,
+        "constraintCount": 3,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 6,
-        "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 6,
-        "totalSchemaProperties": 6,
-        "constraintCount": 3,
+        "topLevelWritableFieldCount": 5,
+        "requestBodyPresent": true,
         "requestExamplePresent": true,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
-        "totalErrorResponses": 0,
-        "ambiguousIdentifierCount": 0
+        "totalErrorResponses": 0
       },
       "getSpecialEvent": {
         "path": "/special-events/{eventId}",
         "method": "get",
         "operationId": "getSpecialEvent",
+        "operationDescriptionPresent": true,
         "parameterCount": 1,
         "requiredParameterCount": 1,
         "paramsWithDescription": 1,
-        "requestBodyPresent": false,
-        "topLevelWritableFieldCount": 0,
+        "ambiguousIdentifierCount": 0,
         "maxRequestSchemaDepth": 0,
         "maxResponseSchemaDepth": 2,
+        "totalSchemaProperties": 6,
+        "schemaPropertiesWithDescription": 6,
+        "constraintCount": 3,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 6,
-        "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 6,
-        "totalSchemaProperties": 6,
-        "constraintCount": 3,
+        "topLevelWritableFieldCount": 0,
+        "requestBodyPresent": false,
         "requestExamplePresent": false,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
-        "totalErrorResponses": 0,
-        "ambiguousIdentifierCount": 0
+        "totalErrorResponses": 0
       },
       "deleteSpecialEvent": {
         "path": "/special-events/{eventId}",
         "method": "delete",
         "operationId": "deleteSpecialEvent",
+        "operationDescriptionPresent": true,
         "parameterCount": 1,
         "requiredParameterCount": 1,
         "paramsWithDescription": 1,
-        "requestBodyPresent": false,
-        "topLevelWritableFieldCount": 0,
+        "ambiguousIdentifierCount": 0,
         "maxRequestSchemaDepth": 0,
         "maxResponseSchemaDepth": 1,
+        "totalSchemaProperties": 2,
+        "schemaPropertiesWithDescription": 0,
+        "constraintCount": 0,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 2,
-        "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 0,
-        "totalSchemaProperties": 2,
-        "constraintCount": 0,
+        "topLevelWritableFieldCount": 0,
+        "requestBodyPresent": false,
         "requestExamplePresent": false,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 1,
-        "totalErrorResponses": 1,
-        "ambiguousIdentifierCount": 0
+        "totalErrorResponses": 1
       },
       "updateSpecialEvent": {
         "path": "/special-events/{eventId}",
         "method": "patch",
         "operationId": "updateSpecialEvent",
+        "operationDescriptionPresent": true,
         "parameterCount": 1,
         "requiredParameterCount": 1,
         "paramsWithDescription": 1,
-        "requestBodyPresent": true,
-        "topLevelWritableFieldCount": 5,
+        "ambiguousIdentifierCount": 0,
         "maxRequestSchemaDepth": 2,
         "maxResponseSchemaDepth": 2,
+        "totalSchemaProperties": 6,
+        "schemaPropertiesWithDescription": 6,
+        "constraintCount": 3,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 6,
-        "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 6,
-        "totalSchemaProperties": 6,
-        "constraintCount": 3,
+        "topLevelWritableFieldCount": 5,
+        "requestBodyPresent": true,
         "requestExamplePresent": true,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
-        "totalErrorResponses": 0,
-        "ambiguousIdentifierCount": 0
+        "totalErrorResponses": 0
       },
       "buyMuseumTickets": {
         "path": "/tickets",
         "method": "post",
         "operationId": "buyMuseumTickets",
+        "operationDescriptionPresent": true,
         "parameterCount": 0,
         "requiredParameterCount": 0,
         "paramsWithDescription": 0,
-        "requestBodyPresent": true,
-        "topLevelWritableFieldCount": 5,
+        "ambiguousIdentifierCount": 0,
         "maxRequestSchemaDepth": 1,
         "maxResponseSchemaDepth": 1,
+        "totalSchemaProperties": 6,
+        "schemaPropertiesWithDescription": 5,
+        "constraintCount": 3,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 6,
-        "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 5,
-        "totalSchemaProperties": 6,
-        "constraintCount": 4,
+        "topLevelWritableFieldCount": 5,
+        "requestBodyPresent": true,
         "requestExamplePresent": true,
         "responseExamplePresent": true,
         "structuredErrorResponseCount": 0,
-        "totalErrorResponses": 0,
-        "ambiguousIdentifierCount": 0
+        "totalErrorResponses": 0
       },
       "getTicketCode": {
         "path": "/tickets/{ticketId}/qr",
         "method": "get",
         "operationId": "getTicketCode",
+        "operationDescriptionPresent": true,
         "parameterCount": 1,
         "requiredParameterCount": 1,
         "paramsWithDescription": 1,
-        "requestBodyPresent": false,
-        "topLevelWritableFieldCount": 0,
+        "ambiguousIdentifierCount": 0,
         "maxRequestSchemaDepth": 0,
         "maxResponseSchemaDepth": 0,
+        "totalSchemaProperties": 0,
+        "schemaPropertiesWithDescription": 0,
+        "constraintCount": 0,
         "polymorphismCount": 0,
         "anyOfCount": 0,
         "hasDiscriminator": false,
-        "propertyCount": 0,
-        "operationDescriptionPresent": true,
-        "schemaPropertiesWithDescription": 0,
-        "totalSchemaProperties": 0,
-        "constraintCount": 1,
+        "topLevelWritableFieldCount": 0,
+        "requestBodyPresent": false,
         "requestExamplePresent": false,
         "responseExamplePresent": false,
         "structuredErrorResponseCount": 0,
-        "totalErrorResponses": 0,
-        "ambiguousIdentifierCount": 0
+        "totalErrorResponses": 0
       }
     }
   },
@@ -303,12 +295,12 @@
       }
     },
     "buyMuseumTickets": {
-      "agentReadiness": 88.8,
+      "agentReadiness": 86.8,
       "subscores": {
         "parameterSimplicity": 1,
         "schemaSimplicity": 0.875,
         "documentationQuality": 0.8571428571428571,
-        "constraintClarity": 0.6666666666666666,
+        "constraintClarity": 0.5,
         "exampleCoverage": 1,
         "errorClarity": 1,
         "dependencyClarity": 0.6666666666666667,
@@ -317,12 +309,12 @@
       }
     },
     "getTicketCode": {
-      "agentReadiness": 81,
+      "agentReadiness": 69,
       "subscores": {
         "parameterSimplicity": 0.9,
         "schemaSimplicity": 1,
         "documentationQuality": 1,
-        "constraintClarity": 1,
+        "constraintClarity": 0,
         "exampleCoverage": 0,
         "errorClarity": 1,
         "dependencyClarity": 1,
@@ -346,7 +338,7 @@
       "path": "/tickets/{ticketId}/qr",
       "method": "get",
       "operationId": "getTicketCode",
-      "agentReadinessScore": 81,
+      "agentReadinessScore": 69,
       "reasons": [
         "Missing response examples"
       ]
diff --git a/tests/e2e/score/score-stylish/snapshot.txt b/tests/e2e/score/score-stylish/snapshot.txt
index e1c6c3b044..d948cb6646 100644
--- a/tests/e2e/score/score-stylish/snapshot.txt
+++ b/tests/e2e/score/score-stylish/snapshot.txt
@@ -1,14 +1,14 @@
 
   Scores
 
-  Agent Readiness:  88.4/100
+  Agent Readiness:  88.2/100
 
   Subscores
 
   Parameter Simplicity     [█████████████████░░░] 86%
   Schema Simplicity        [████████████████░░░░] 80%
   Documentation Quality    [██████████████████░░] 90%
-  Constraint Clarity       [████████████░░░░░░░░] 58%
+  Constraint Clarity       [█████████░░░░░░░░░░░] 44%
   Example Coverage         [██████████████████░░] 88%
   Error Clarity            [████████████████████] 100%
   Dependency Clarity       [███████████████░░░░░] 73%
@@ -30,7 +30,7 @@
   Top 1 Hotspot Operations
 
   GET /tickets/{ticketId}/qr (getTicketCode)
-    Agent Readiness: 81.0
+    Agent Readiness: 69.0
     - Missing response examples
 
 

From 64884e63fd1f2d87bf40d4ae292572149ff12bcb Mon Sep 17 00:00:00 2001
From: Adam Altman <adam@redocly.com>
Date: Wed, 8 Apr 2026 11:58:19 -0500
Subject: [PATCH 22/22] fix: address bugbot findings (round 4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Preserve top-level $ref in refsUsed when composition branch is taken,
  so computeDependencyDepths correctly tracks cross-operation schema
  sharing for oneOf/anyOf/allOf/discriminator schemas
- Return constraintClarity=1 when totalSchemaProperties is 0, matching
  errorClarity's "no data" pattern — avoids unfairly penalizing DELETE
  and binary-returning endpoints that have no schema properties

Made-with: Cursor and Adam
---
 packages/cli/src/commands/score/collect-metrics.ts | 4 ++++
 packages/cli/src/commands/score/scoring.ts         | 6 ++++--
 tests/e2e/score/score-json/snapshot.txt            | 8 ++++----
 tests/e2e/score/score-stylish/snapshot.txt         | 4 ++--
 4 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/packages/cli/src/commands/score/collect-metrics.ts b/packages/cli/src/commands/score/collect-metrics.ts
index 53b9e32a29..96e5099336 100644
--- a/packages/cli/src/commands/score/collect-metrics.ts
+++ b/packages/cli/src/commands/score/collect-metrics.ts
@@ -211,6 +211,10 @@ export function collectMetrics({
       if (allOfStats) result = addStats(result, allOfStats);
       if (polyStats) result = addStats(result, polyStats);
       if (discStats) result = addStats(result, discStats);
+
+      if (ref) {
+        result = { ...result, refsUsed: [ref, ...result.refsUsed] };
+      }
     } else {
       result = walkSchemaRaw(schemaNode, debug);
     }
diff --git a/packages/cli/src/commands/score/scoring.ts b/packages/cli/src/commands/score/scoring.ts
index ead123c4f2..97778e458f 100644
--- a/packages/cli/src/commands/score/scoring.ts
+++ b/packages/cli/src/commands/score/scoring.ts
@@ -31,8 +31,10 @@ export function computeOperationSubscores(
   const descTotal = 1 + metrics.parameterCount + metrics.totalSchemaProperties;
   const documentationQuality = descTotal > 0 ? clamp01(descCount / descTotal) : 1;
 
-  const propCount = metrics.totalSchemaProperties || 1;
-  const constraintClarity = clamp01(metrics.constraintCount / propCount);
+  const constraintClarity =
+    metrics.totalSchemaProperties > 0
+      ? clamp01(metrics.constraintCount / metrics.totalSchemaProperties)
+      : 1;
 
   const examplePoints =
     (metrics.requestExamplePresent ? 1 : 0) + (metrics.responseExamplePresent ? 1 : 0);
diff --git a/tests/e2e/score/score-json/snapshot.txt b/tests/e2e/score/score-json/snapshot.txt
index 748cc341e9..69a8bb3e1b 100644
--- a/tests/e2e/score/score-json/snapshot.txt
+++ b/tests/e2e/score/score-json/snapshot.txt
@@ -5,7 +5,7 @@
     "parameterSimplicity": 0.8625,
     "schemaSimplicity": 0.796875,
     "documentationQuality": 0.9017857142857143,
-    "constraintClarity": 0.4375,
+    "constraintClarity": 0.5625,
     "exampleCoverage": 0.875,
     "errorClarity": 1,
     "dependencyClarity": 0.7291666666666669,
@@ -309,12 +309,12 @@
       }
     },
     "getTicketCode": {
-      "agentReadiness": 69,
+      "agentReadiness": 81,
       "subscores": {
         "parameterSimplicity": 0.9,
         "schemaSimplicity": 1,
         "documentationQuality": 1,
-        "constraintClarity": 0,
+        "constraintClarity": 1,
         "exampleCoverage": 0,
         "errorClarity": 1,
         "dependencyClarity": 1,
@@ -338,7 +338,7 @@
       "path": "/tickets/{ticketId}/qr",
       "method": "get",
       "operationId": "getTicketCode",
-      "agentReadinessScore": 69,
+      "agentReadinessScore": 81,
       "reasons": [
         "Missing response examples"
       ]
diff --git a/tests/e2e/score/score-stylish/snapshot.txt b/tests/e2e/score/score-stylish/snapshot.txt
index d948cb6646..ad17c44775 100644
--- a/tests/e2e/score/score-stylish/snapshot.txt
+++ b/tests/e2e/score/score-stylish/snapshot.txt
@@ -8,7 +8,7 @@
   Parameter Simplicity     [█████████████████░░░] 86%
   Schema Simplicity        [████████████████░░░░] 80%
   Documentation Quality    [██████████████████░░] 90%
-  Constraint Clarity       [█████████░░░░░░░░░░░] 44%
+  Constraint Clarity       [███████████░░░░░░░░░] 56%
   Example Coverage         [██████████████████░░] 88%
   Error Clarity            [████████████████████] 100%
   Dependency Clarity       [███████████████░░░░░] 73%
@@ -30,7 +30,7 @@
   Top 1 Hotspot Operations
 
   GET /tickets/{ticketId}/qr (getTicketCode)
-    Agent Readiness: 69.0
+    Agent Readiness: 81.0
     - Missing response examples