micro-contracts 0.14.4 → 0.15.1

package/cli-contract.yaml

@@ -1,9 +1,9 @@
 # yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json
-cliContracts: 0.1.0
+cli_contracts: 0.1.0
 
 info:
   title: micro-contracts CLI
-  version: 0.14.2
+  version: 0.15.0
   description: >-
     Contract-first OpenAPI toolchain for TypeScript Web/API systems.
     Generates contract packages, server routes, and frontend clients
@@ -14,12 +14,29 @@ info:
     name: foo-ogawa
     url: https://github.com/foo-ogawa/micro-contracts
 
-commandSets:
+artifact_slots:
+  openapi-specs:
+    direction: read
+    description: OpenAPI specification files
+  config:
+    direction: read
+    description: micro-contracts.config.yaml configuration
+  generated-packages:
+    direction: write
+    description: Generated contract packages, server routes, and frontend clients
+  guardrails-config:
+    direction: read
+    description: guardrails.yaml configuration
+  manifest:
+    direction: write
+    description: Generated manifest (.generated-manifest.json)
+
+command_sets:
   micro-contracts:
     summary: Contract-first OpenAPI toolchain for TypeScript.
     executable: micro-contracts
 
-    globalOptions:
+    global_options:
       - name: version
         aliases: [V]
         description: Print version and exit.
@@ -52,19 +69,19 @@ commandSets:
           - name: config
             aliases: [c]
             description: Path to config file (micro-contracts.config.yaml).
-            valueName: path
+            value_name: path
             schema:
               type: string
             file:
               mode: read
               exists: false
-              mediaType: application/yaml
+              media_type: application/yaml
               encoding: utf-8
 
           - name: module
             aliases: [m]
             description: Module names, comma-separated. Generates all modules if omitted.
-            valueName: names
+            value_name: names
             schema:
               type: string
 
@@ -108,7 +125,7 @@ commandSets:
 
           - name: manifest-dir
             description: Directory for manifest output.
-            valueName: path
+            value_name: path
             schema:
               type: string
               default: packages/
@@ -135,12 +152,12 @@ commandSets:
             files:
               - path: packages/contract/{module}/**/*.ts
                 required: true
-                mediaType: text/x-typescript
+                media_type: text/x-typescript
                 encoding: utf-8
                 description: Generated contract packages.
               - path: packages/contract-published/{module}/**/*.ts
                 required: false
-                mediaType: text/x-typescript
+                media_type: text/x-typescript
                 encoding: utf-8
                 description: Generated public contract packages.
 
@@ -150,12 +167,12 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: medium
-          requiresConfirmation: false
+          risk_level: medium
+          requires_confirmation: false
           idempotent: true
-          sideEffects:
+          side_effects:
             - file_write
-          recommendedBeforeUse:
+          recommended_before_use:
             - Ensure micro-contracts.config.yaml exists.
             - Verify OpenAPI specs are valid.
 
@@ -179,7 +196,7 @@ commandSets:
             file:
               mode: read
               exists: true
-              mediaType: application/yaml
+              media_type: application/yaml
               encoding: utf-8
 
         options:
@@ -201,10 +218,10 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: low
-          requiresConfirmation: false
+          risk_level: low
+          requires_confirmation: false
           idempotent: true
-          sideEffects: []
+          side_effects: []
 
       # ── init ─────────────────────────────────────────
       init:
@@ -232,7 +249,7 @@ commandSets:
           - name: dir
             aliases: [d]
             description: Base directory for server/frontend files.
-            valueName: path
+            value_name: path
             schema:
               type: string
               default: src
@@ -240,19 +257,19 @@ commandSets:
           - name: openapi
             aliases: [i]
             description: OpenAPI spec to process (auto-adds x-micro-contracts-service/method extensions).
-            valueName: path
+            value_name: path
             schema:
               type: string
             file:
               mode: read
               exists: true
-              mediaType: application/yaml
+              media_type: application/yaml
               encoding: utf-8
 
           - name: output
             aliases: [o]
             description: Output path for processed OpenAPI. Defaults to spec/{name}/openapi/{name}.yaml.
-            valueName: path
+            value_name: path
             schema:
               type: string
 
@@ -276,17 +293,17 @@ commandSets:
             files:
               - path: spec/{name}/openapi/{name}.yaml
                 required: false
-                mediaType: application/yaml
+                media_type: application/yaml
                 encoding: utf-8
                 description: OpenAPI spec (created when --openapi provided or --screens used).
               - path: spec/default/templates/*.hbs
                 required: false
-                mediaType: text/x-handlebars-template
+                media_type: text/x-handlebars-template
                 encoding: utf-8
                 description: Starter Handlebars templates.
               - path: micro-contracts.config.yaml
                 required: false
-                mediaType: application/yaml
+                media_type: application/yaml
                 encoding: utf-8
                 description: Config file (created if not already present).
 
@@ -296,10 +313,10 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: medium
-          requiresConfirmation: false
+          risk_level: medium
+          requires_confirmation: false
           idempotent: true
-          sideEffects:
+          side_effects:
             - file_write
             - directory_create
 
@@ -321,19 +338,19 @@ commandSets:
         options:
           - name: only
             description: Run only specific checks (comma-separated check names).
-            valueName: checks
+            value_name: checks
             schema:
               type: string
 
           - name: skip
             description: Skip specific checks (comma-separated check names).
-            valueName: checks
+            value_name: checks
             schema:
               type: string
 
           - name: gate
             description: Run checks for specific gates only (comma-separated, 1-5).
-            valueName: gates
+            value_name: gates
             schema:
               type: string
 
@@ -353,32 +370,32 @@ commandSets:
           - name: guardrails
             aliases: [g]
             description: Path to guardrails.yaml.
-            valueName: path
+            value_name: path
             schema:
               type: string
             file:
               mode: read
               exists: false
-              mediaType: application/yaml
+              media_type: application/yaml
               encoding: utf-8
 
           - name: generated-dir
             aliases: [d]
             description: Path to generated files directory.
-            valueName: path
+            value_name: path
             schema:
               type: string
               default: packages/
 
           - name: changed-files
             description: Path to file containing list of changed files (for CI).
-            valueName: path
+            value_name: path
             schema:
               type: string
             file:
               mode: read
               exists: true
-              mediaType: text/plain
+              media_type: text/plain
               encoding: utf-8
 
           - name: list
@@ -408,11 +425,11 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: low
-          requiresConfirmation: false
+          risk_level: low
+          requires_confirmation: false
           idempotent: true
-          sideEffects: []
-          recommendedBeforeUse:
+          side_effects: []
+          recommended_before_use:
             - Run generate first so generated files exist.
 
       # ── pipeline ─────────────────────────────────────
@@ -433,13 +450,13 @@ commandSets:
           - name: config
             aliases: [c]
             description: Path to config file (micro-contracts.config.yaml).
-            valueName: path
+            value_name: path
             schema:
               type: string
             file:
               mode: read
               exists: false
-              mediaType: application/yaml
+              media_type: application/yaml
               encoding: utf-8
 
           - name: verbose
@@ -451,7 +468,7 @@ commandSets:
 
           - name: skip
             description: Skip specific checks (comma-separated).
-            valueName: checks
+            value_name: checks
             schema:
               type: string
 
@@ -464,19 +481,19 @@ commandSets:
           - name: guardrails
             aliases: [g]
             description: Path to guardrails.yaml.
-            valueName: path
+            value_name: path
             schema:
               type: string
             file:
               mode: read
               exists: false
-              mediaType: application/yaml
+              media_type: application/yaml
               encoding: utf-8
 
           - name: generated-dir
             aliases: [d]
             description: Path to generated files directory.
-            valueName: path
+            value_name: path
             schema:
               type: string
               default: packages/
@@ -548,12 +565,12 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: medium
-          requiresConfirmation: false
+          risk_level: medium
+          requires_confirmation: false
           idempotent: true
-          sideEffects:
+          side_effects:
             - file_write
-          recommendedBeforeUse:
+          recommended_before_use:
             - Ensure micro-contracts.config.yaml and guardrails.yaml exist.
             - Verify OpenAPI specs are valid.
 
@@ -576,19 +593,19 @@ commandSets:
           - name: config
             aliases: [c]
             description: Path to config file.
-            valueName: path
+            value_name: path
             schema:
               type: string
             file:
               mode: read
               exists: false
-              mediaType: application/yaml
+              media_type: application/yaml
               encoding: utf-8
 
           - name: module
             aliases: [m]
             description: Module to analyze.
-            valueName: name
+            value_name: name
             schema:
               type: string
 
@@ -600,13 +617,13 @@ commandSets:
 
           - name: impact
             description: Analyze impact of changing a specific API (e.g., core.User.getUsers).
-            valueName: ref
+            value_name: ref
             schema:
               type: string
 
           - name: who-depends-on
             description: Find modules that depend on a specific API.
-            valueName: ref
+            value_name: ref
             schema:
               type: string
 
@@ -628,10 +645,10 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: low
-          requiresConfirmation: false
+          risk_level: low
+          requires_confirmation: false
           idempotent: true
-          sideEffects: []
+          side_effects: []
 
       # ── guardrails-init ──────────────────────────────
       guardrails-init:
@@ -648,7 +665,7 @@ commandSets:
           - name: output
             aliases: [o]
             description: Output path for guardrails.yaml.
-            valueName: path
+            value_name: path
             schema:
               type: string
               default: guardrails.yaml
@@ -661,7 +678,7 @@ commandSets:
             files:
               - path: '{options.output}'
                 required: true
-                mediaType: application/yaml
+                media_type: application/yaml
                 encoding: utf-8
 
           '1':
@@ -670,10 +687,10 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: low
-          requiresConfirmation: false
+          risk_level: low
+          requires_confirmation: false
           idempotent: false
-          sideEffects:
+          side_effects:
             - file_write
 
       # ── manifest ─────────────────────────────────────
@@ -693,7 +710,7 @@ commandSets:
           - name: dir
             aliases: [d]
             description: Directory to scan.
-            valueName: path
+            value_name: path
             schema:
               type: string
               default: packages/
@@ -707,7 +724,7 @@ commandSets:
           - name: output
             aliases: [o]
             description: Output manifest path. Defaults to {dir}/.generated-manifest.json.
-            valueName: path
+            value_name: path
             schema:
               type: string
 
@@ -719,7 +736,7 @@ commandSets:
             files:
               - path: '{options.dir}/.generated-manifest.json'
                 required: false
-                mediaType: application/json
+                media_type: application/json
                 encoding: utf-8
                 description: Generated manifest (not created in verify mode).
 
@@ -729,8 +746,628 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: low
-          requiresConfirmation: false
+          risk_level: low
+          requires_confirmation: false
           idempotent: true
-          sideEffects:
+          side_effects:
             - file_write
+
+      # ── audit-openapi ──────────────────────────────
+      audit-openapi:
+        path: [audit-openapi]
+        summary: Run LLM-based OpenAPI design quality audit.
+        description: >-
+          Performs a semantic review of OpenAPI specification design quality
+          using an LLM agent. Evaluates path design, module boundary alignment,
+          schema bloat, CRUD vs use-case orientation, and cross-cutting
+          concern coverage. Requires agent-contracts-runtime.
+        usage:
+          - micro-contracts audit-openapi
+          - micro-contracts audit-openapi -m core
+          - micro-contracts audit-openapi --adapter cursor --report-format text
+          - micro-contracts audit-openapi --show-prompt
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to config file (micro-contracts.config.yaml).
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              media_type: application/yaml
+              encoding: utf-8
+
+          - name: module
+            aliases: [m]
+            description: Module name to audit (default is all modules).
+            value_name: name
+            schema:
+              type: string
+
+          - name: adapter
+            aliases: [a]
+            description: SDK adapter to use for LLM execution.
+            value_name: name
+            schema:
+              type: string
+              enum: [cursor, claude, openai, gemini, mock]
+
+          - name: model
+            description: LLM model override.
+            value_name: name
+            schema:
+              type: string
+
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            value_name: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            value_name: file
+            schema:
+              type: string
+            file:
+              mode: write
+              media_type: application/json
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the audit report.
+            value_name: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: text
+
+        exits:
+          '0':
+            description: Audit completed, no blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/OpenApiAuditResult'
+
+          '1':
+            description: Unexpected error.
+            stderr:
+              format: text
+
+          '3':
+            description: Input validation failed (config not found, spec invalid).
+            stderr:
+              format: text
+
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/OpenApiAuditResult'
+
+          '11':
+            description: Runtime dependency missing (agent-contracts-runtime).
+            stderr:
+              format: text
+
+          '12':
+            description: LLM provider or adapter error.
+            stderr:
+              format: text
+
+        effects:
+          reads: [openapi-specs, config]
+          writes: []
+          network:
+            description: LLM API calls when adapter is not mock
+            requires_secrets: []
+            idempotent: true
+
+        x-agent:
+          risk_level: low
+          requires_confirmation: false
+          idempotent: true
+          side_effects: [network]
+          sideEffectNote: >-
+            Network calls to LLM provider when adapter is not mock.
+            Filesystem write only when --output is specified.
+          safe_dry_run_option: show-prompt
+          expectedDurationMs: 120000
+          retryableExitCodes: [12]
+
+      # ── review-published ───────────────────────────
+      review-published:
+        path: [review-published]
+        summary: Review published API surface for internal leakage.
+        description: >-
+          Analyzes the published (public-facing) API specification for
+          internal type leakage, backward compatibility risks, and
+          x-micro-contracts-non-exportable violations.
+          Requires agent-contracts-runtime.
+        usage:
+          - micro-contracts review-published
+          - micro-contracts review-published -m billing
+          - micro-contracts review-published --adapter claude --report-format json
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to config file (micro-contracts.config.yaml).
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              media_type: application/yaml
+              encoding: utf-8
+
+          - name: module
+            aliases: [m]
+            description: Module name to review (default is all modules).
+            value_name: name
+            schema:
+              type: string
+
+          - name: adapter
+            aliases: [a]
+            description: SDK adapter to use for LLM execution.
+            value_name: name
+            schema:
+              type: string
+              enum: [cursor, claude, openai, gemini, mock]
+
+          - name: model
+            description: LLM model override.
+            value_name: name
+            schema:
+              type: string
+
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            value_name: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            value_name: file
+            schema:
+              type: string
+            file:
+              mode: write
+              media_type: application/json
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the review report.
+            value_name: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: text
+
+        exits:
+          '0':
+            description: Review completed, no blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/PublishedReviewResult'
+
+          '1':
+            description: Unexpected error.
+            stderr:
+              format: text
+
+          '3':
+            description: Input validation failed.
+            stderr:
+              format: text
+
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/PublishedReviewResult'
+
+          '11':
+            description: Runtime dependency missing (agent-contracts-runtime).
+            stderr:
+              format: text
+
+          '12':
+            description: LLM provider or adapter error.
+            stderr:
+              format: text
+
+        effects:
+          reads: [openapi-specs, config, generated-packages]
+          writes: []
+          network:
+            description: LLM API calls when adapter is not mock
+            requires_secrets: []
+            idempotent: true
+
+        x-agent:
+          risk_level: low
+          requires_confirmation: false
+          idempotent: true
+          side_effects: [network]
+          sideEffectNote: >-
+            Network calls to LLM provider when adapter is not mock.
+            Filesystem write only when --output is specified.
+          safe_dry_run_option: show-prompt
+          expectedDurationMs: 120000
+          retryableExitCodes: [12]
+
+      # ── propose-overlays ───────────────────────────
+      propose-overlays:
+        path: [propose-overlays]
+        summary: Propose cross-cutting overlay candidates.
+        description: >-
+          Analyzes the OpenAPI specification and proposes cross-cutting
+          overlay candidates for authentication, tenancy, rate limiting,
+          audit logging, and other patterns. Verifies proposals do not
+          conflict with existing overlay definitions.
+          Requires agent-contracts-runtime.
+        usage:
+          - micro-contracts propose-overlays
+          - micro-contracts propose-overlays -m core
+          - micro-contracts propose-overlays --adapter openai --report-format json
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to config file (micro-contracts.config.yaml).
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              media_type: application/yaml
+              encoding: utf-8
+
+          - name: module
+            aliases: [m]
+            description: Module name to analyze (default is all modules).
+            value_name: name
+            schema:
+              type: string
+
+          - name: adapter
+            aliases: [a]
+            description: SDK adapter to use for LLM execution.
+            value_name: name
+            schema:
+              type: string
+              enum: [cursor, claude, openai, gemini, mock]
+
+          - name: model
+            description: LLM model override.
+            value_name: name
+            schema:
+              type: string
+
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            value_name: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            value_name: file
+            schema:
+              type: string
+            file:
+              mode: write
+              media_type: application/json
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the proposal report.
+            value_name: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: json
+
+        exits:
+          '0':
+            description: Proposal generated successfully.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/OverlayProposalResult'
+
+          '1':
+            description: Unexpected error.
+            stderr:
+              format: text
+
+          '3':
+            description: Input validation failed.
+            stderr:
+              format: text
+
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/OverlayProposalResult'
+
+          '11':
+            description: Runtime dependency missing (agent-contracts-runtime).
+            stderr:
+              format: text
+
+          '12':
+            description: LLM provider or adapter error.
+            stderr:
+              format: text
+
+        effects:
+          reads: [openapi-specs, config]
+          writes: []
+          network:
+            description: LLM API calls when adapter is not mock
+            requires_secrets: []
+            idempotent: true
+
+        x-agent:
+          risk_level: low
+          requires_confirmation: false
+          idempotent: true
+          side_effects: [network]
+          sideEffectNote: >-
+            Network calls to LLM provider when adapter is not mock.
+            Filesystem write only when --output is specified.
+          safe_dry_run_option: show-prompt
+          expectedDurationMs: 120000
+          retryableExitCodes: [12]
+
+      # ── audit-guardrails ───────────────────────────
+      audit-guardrails:
+        path: [audit-guardrails]
+        summary: Audit guardrails configuration for drift and lint coverage.
+        description: >-
+          Checks that guardrails.yaml configuration covers all generated
+          output directories for drift detection and that OpenAPI lint
+          rules are properly configured. Note: file permission and
+          editing checks have been moved to artifact-contracts.
+          Requires agent-contracts-runtime.
+        usage:
+          - micro-contracts audit-guardrails
+          - micro-contracts audit-guardrails --adapter mock --report-format json
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to config file (micro-contracts.config.yaml).
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              media_type: application/yaml
+              encoding: utf-8
+
+          - name: guardrails
+            aliases: [g]
+            description: Path to guardrails.yaml.
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              media_type: application/yaml
+              encoding: utf-8
+
+          - name: adapter
+            aliases: [a]
+            description: SDK adapter to use for LLM execution.
+            value_name: name
+            schema:
+              type: string
+              enum: [cursor, claude, openai, gemini, mock]
+
+          - name: model
+            description: LLM model override.
+            value_name: name
+            schema:
+              type: string
+
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            value_name: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            value_name: file
+            schema:
+              type: string
+            file:
+              mode: write
+              media_type: application/json
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the audit report.
+            value_name: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: text
+
+        exits:
+          '0':
+            description: Audit completed, no blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/GuardrailsAuditResult'
+
+          '1':
+            description: Unexpected error.
+            stderr:
+              format: text
+
+          '3':
+            description: Input validation failed (guardrails.yaml not found).
+            stderr:
+              format: text
+
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/GuardrailsAuditResult'
+
+          '11':
+            description: Runtime dependency missing (agent-contracts-runtime).
+            stderr:
+              format: text
+
+          '12':
+            description: LLM provider or adapter error.
+            stderr:
+              format: text
+
+        effects:
+          reads: [guardrails-config, config]
+          writes: []
+          network:
+            description: LLM API calls when adapter is not mock
+            requires_secrets: []
+            idempotent: true
+
+        x-agent:
+          risk_level: low
+          requires_confirmation: false
+          idempotent: true
+          side_effects: [network]
+          sideEffectNote: >-
+            Network calls to LLM provider when adapter is not mock.
+            Filesystem write only when --output is specified.
+          safe_dry_run_option: show-prompt
+          expectedDurationMs: 120000
+          retryableExitCodes: [12]
+
+components:
+  schemas:
+    # ── AI Agent Interoperability Schemas ──────────────────
+    AgentEvidence:
+      $ref: 'components.yaml#/schemas/agent-evidence'
+    AgentFinding:
+      $ref: 'components.yaml#/schemas/agent-finding'
+    AgentRecommendedAction:
+      $ref: 'components.yaml#/schemas/agent-recommended-action'
+    OpenApiAuditResult:
+      $ref: 'components.yaml#/schemas/agent-audit-result'
+
+    PublishedReviewResult:
+      type: object
+      description: >-
+        Result from review-published command. Contains published endpoint
+        enumeration and internal type leakage analysis.
+      allOf:
+        - $ref: 'components.yaml#/schemas/agent-audit-result'
+        - type: object
+          required: [publishedEndpoints, leakedInternalTypes]
+          properties:
+            publishedEndpoints:
+              type: array
+              items:
+                type: object
+                required: [operationId, path, method]
+                properties:
+                  operationId:
+                    type: string
+                  path:
+                    type: string
+                  method:
+                    type: string
+            leakedInternalTypes:
+              type: array
+              items:
+                type: object
+                required: [schemaName, referencedBy, reason]
+                properties:
+                  schemaName:
+                    type: string
+                  referencedBy:
+                    type: string
+                  reason:
+                    type: string
+
+    OverlayProposalResult:
+      type: object
+      description: >-
+        Result from propose-overlays command. Contains overlay candidate
+        proposals with endpoint, type, rationale, and suggested config.
+      allOf:
+        - $ref: 'components.yaml#/schemas/agent-audit-result'
+        - type: object
+          required: [overlayCandidates]
+          properties:
+            overlayCandidates:
+              type: array
+              items:
+                type: object
+                required: [endpoint, overlayType, rationale]
+                properties:
+                  endpoint:
+                    type: string
+                  overlayType:
+                    type: string
+                    enum: [auth, tenancy, rateLimit, auditLog, custom]
+                  rationale:
+                    type: string
+                  suggestedConfig:
+                    type: object
+                    additionalProperties: true
+
+    GuardrailsAuditResult:
+      type: object
+      description: >-
+        Result from audit-guardrails command. Contains drift detection
+        and lint rule coverage analysis.
+      allOf:
+        - $ref: 'components.yaml#/schemas/agent-audit-result'
+        - type: object
+          required: [coveredPaths, uncoveredPaths]
+          properties:
+            coveredPaths:
+              type: array
+              items:
+                type: string
+            uncoveredPaths:
+              type: array
+              items:
+                type: string