openapi.yaml

openapi: 3.1.0
info:
  title: Scrutineer Skill API
  version: 0.4.0
  description: |
    A narrow HTTP surface that claude-code skills use while they run. The
    goal is enough to let a skill orchestrate other skills and read prior
    scan outputs without pushing that logic into scrutineer's Go code.

    Every scrutineer skill scan is issued a bearer token that is staged into
    the workspace context.json. Skills authenticate with that token. A token
    is only valid while its originating scan is running, and only grants
    access to the repository the scan was issued against.

    The `/v1/*` paths are an unauthenticated, localhost-only export surface
    intended for external scripts (jq, cron, CI dumps). They emit JSONL and
    rely on the same host-header check as the browser UI; see threatmodel.md.

servers:
  - url: http://127.0.0.1:8080/api
    description: Local scrutineer server

security:
  - bearerAuth: []

paths:
  /openapi.yaml:
    get:
      summary: Fetch this OpenAPI document
      description: |
        Returns the embedded copy of `openapi.yaml`, so a skill or an external
        tool can read the API surface from a running server without a checkout.

        Two ways in. From localhost it is unauthenticated, because a caller
        discovering the API has no running scan to take a bearer token from;
        the host check is the boundary, as on the browser UI. A skill inside
        the runner container cannot pass that check -- it reaches the server
        through the egress proxy on the host endpoint `api_base` advertises,
        which forwards the original `Host` -- so it authenticates with the
        per-scan bearer token it already holds for the rest of this API.
        See threatmodel.md.
      operationId: getOpenAPISpec
      security:
        - {}
        - bearerAuth: []
      responses:
        "200":
          description: The OpenAPI document
          content:
            application/yaml:
              schema:
                type: string
        "401":
          description: |
            Request came from a non-local host without a bearer token
            belonging to a currently running scan
  /claim-check:
    servers:
      - url: http://127.0.0.1:8080
        description: Local scrutineer server root
    post:
      summary: Check whether this instance already holds a federated finding claim
      description: |
        Accepts a salted finding hash from a federation peer and returns whether
        this instance already has a claimable matching finding. The request does
        not reveal the finding; a match discloses only the configured operator
        contact. Disabled instances, non-POST requests, and instances without a
        federation salt answer 404 so federation support is not fingerprintable.
      operationId: claimCheck
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [hash]
              properties:
                hash:
                  type: string
                  pattern: '^[0-9a-f]{64}$'
      responses:
        '200':
          description: Claim-check result
          content:
            application/json:
              schema:
                type: object
                required: [match]
                properties:
                  match: { type: boolean }
                  contact:
                    type: string
                    description: Present only when match is true and federation contact is configured.
        '400':
          description: Invalid JSON body or hash value
        '404':
          description: Claim check disabled or unsupported method
        '500':
          description: Failed to load local findings

  /repositories/{id}:
    get:
      summary: Fetch a repository summary
      operationId: getRepository
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Repository' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      summary: Update skill-writable repository fields
      description: |
        Allows the authenticated scan to write repository fields that are
        produced by skills rather than owned by metadata refreshes. Currently
        only `fork` is accepted.
      operationId: patchRepository
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [fork]
              properties:
                fork:
                  type: string
                  description: Owner/name of the staging fork prepared for patch work.
      responses:
        '204':
          description: Repository updated
        '400':
          description: Body is not valid JSON
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422':
          description: No writable fields were supplied
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '500':
          description: Database update failed
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /repositories/{id}/scans:
    get:
      summary: List scans for a repository
      operationId: listRepositoryScans
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
        - name: status
          in: query
          schema:
            type: string
            enum: [queued, running, paused, done, failed, skipped, cancelled]
        - name: skill
          in: query
          schema: { type: string }
          description: Filter by skill name (matches Scan.skill_name).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Scan' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/maintainers:
    get:
      summary: List maintainers linked to this repository
      operationId: listRepositoryMaintainers
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Maintainer' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/packages:
    get:
      summary: List published packages produced by this repository
      operationId: listRepositoryPackages
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Package' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/alternatives:
    get:
      summary: List operator-curated package migration alternatives
      operationId: listRepositoryAlternatives
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/PackageAlternative' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/advisories:
    get:
      summary: List published advisories affecting this repository's packages
      operationId: listRepositoryAdvisories
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Advisory' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/dependents:
    get:
      summary: List downstream dependents of this repository's packages
      operationId: listRepositoryDependents
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
        - $ref: '#/components/parameters/RepositoryReadLimit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Dependent' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/ecosystems/{source}/raw:
    get:
      summary: Verbatim cached ecosyste.ms payload for one source
      description: >
        Returns the raw upstream payload pre-fetched and cached server-side.
        A 404 signals nothing is cached, in which case the caller falls
        back to a direct WebFetch. When the operator sets
        ecosystems_enrichment false, no source is ever cached, so every
        request answers 404 and the fallback is the only path.
      operationId: getRepositoryEcosystemsRaw
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
        - name: source
          in: path
          required: true
          schema:
            type: string
            enum: [repo, packages, advisories, commits, issues, dependents]
      responses:
        '200':
          description: Cached payload, returned verbatim
          content:
            application/json: {}
        '400':
          description: Unknown source
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /repositories/{id}/expected:
    get:
      summary: List expected findings for benchmark comparison
      operationId: listRepositoryExpectedFindings
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/ExpectedFinding' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /repositories/{id}/dependencies:
    get:
      summary: List dependencies declared by this repository's manifests
      operationId: listRepositoryDependencies
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
        - $ref: '#/components/parameters/RepositoryReadLimit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Dependency' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/findings:
    get:
      summary: List findings across every scan on this repository
      operationId: listRepositoryFindings
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
        - name: severity
          in: query
          schema: { type: string, enum: [Critical, High, Medium, Low] }
        - name: status
          in: query
          schema:
            type: string
            enum: [new, enriched, triaged, ready, reported, acknowledged, fixed, published, rejected, duplicate]
        - name: skill
          in: query
          description: Only return findings produced by scans of this skill (e.g. `semgrep`, `security-deep-dive`).
          schema: { type: string }
        - name: scan_group
          in: query
          description: Only return findings from scans in this parallel batch, so an in-flight audit skill reads only its siblings' findings.
          schema: { type: string }
        - name: sub_path
          in: query
          description: Only return findings for this monorepo sub-package (e.g. `activesupport`), so a repository can be exported or bundled one sub-package at a time.
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/FindingSummary' }
        '403': { $ref: '#/components/responses/Forbidden' }
    post:
      summary: Stream one finding into the concurrent-finding log
      description: >
        Records a single finding emitted mid-scan so sibling scans in the same
        `scan_group` can read it before this scan completes. The body is one
        finding in the same shape it has in the skill's `report.json`; the
        scan's identity (scan id, repository, commit, sub-path) is stamped from
        the bearer token, never trusted from the body. The finding still
        belongs in the final `report.json`, which reconciles against the
        streamed row by fingerprint rather than duplicating it.
      operationId: streamRepositoryFinding
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FindingInput' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FindingSummary' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/dependency-findings:
    get:
      summary: List findings on libraries this repository depends on
      description: >
        Joins this repository's Dependency rows against every Package row
        scrutineer knows about and returns the live findings on the matched
        library repositories. git-pkgs ecosystem names (gem, golang,
        composer) are normalised to packages.ecosyste.ms names (rubygems,
        go, packagist) before matching. Findings already marked fixed,
        rejected or duplicate are excluded. Consumed by the reachability
        skill.
      operationId: listRepositoryDependencyFindings
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
        - name: severity
          in: query
          schema: { type: string, enum: [Critical, High, Medium, Low] }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/DependencyFinding' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /repositories/{id}/skills/{name}/run:
    post:
      summary: Enqueue a skill scan against this repository
      operationId: runSkill
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
        - name: name
          in: path
          required: true
          schema: { type: string }
          description: Skill name (matches the SKILL.md `name` field).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                model:
                  type: string
                  description: Override model; defaults to the system default.
                ref:
                  type: string
                  description: Git ref to checkout; empty means the repository's default branch.
                sub_path:
                  type: string
                  description: |
                    Scope this run to a monorepo sub-package (a relative sub-folder, e.g. `activesupport`).
                    The `triage` skill forwards it to every pipeline child so the whole scan set stays
                    scoped to the same sub-package. Empty means the whole repository. A `..` segment is rejected.
                profile:
                  type: string
                  description: |
                    Runner profile name (e.g. `php`). Empty auto-detects from the clone via `brief`;
                    `default` forces the default runner image. Unknown names return 400, as do
                    overrides that conflict with the skill's `requires_profile` constraint.
                rescan_mode:
                  type: string
                  enum: [full, diff]
                  description: |
                    `diff` asks Scrutineer to compare the current commit against a compatible baseline
                    scan and stage `diff.patch` plus `changed_files.json` for diff-aware skills. The
                    worker falls back to a full scan when no usable baseline exists or the diff exceeds
                    safety limits.
                baseline_scan_id:
                  type: integer
                  format: int64
                  description: |
                    Optional baseline scan to use for `rescan_mode: diff`; omitted lets Scrutineer
                    choose the latest compatible completed scan.
      responses:
        '201':
          description: Scan enqueued
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Scan' }
        '400':
          description: Bad request (unknown profile, profile mismatch with the skill's `requires_profile`, invalid ref, or invalid `rescan_mode`)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: Skill or repository not found
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '409':
          description: 'The repository maintainer opted out of federated scanning, so no scan may be enqueued for it.'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /findings/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer, format: int64 }
    get:
      summary: Fetch one finding with its six-step prose
      operationId: getFinding
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FindingDetail' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      summary: Update mutable fields on a finding
      operationId: patchFinding
      description: |
        The authenticated scan must be finding-scoped to this finding ID.
        Each field value is written through the history-tracked path.
        Finding-scoped skills write with source=model_suggested; browser
        form edits use separate routes and write with source=analyst.
        Unknown field names are rejected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [fields]
              properties:
                by:
                  type: string
                  description: Optional author string for the history row.
                fields:
                  type: object
                  additionalProperties: { type: string }
                  description: |
                    Map of field name to new value. Allowed fields:
                    title, severity, status, cwe, location, affected, reachability, quality_tier,
                    cve_id, ghsa_id, cvss_vector, cvss_v4_vector, fix_version, fix_commit,
                    resolution, disclosure_draft, disclosure_title, suggested_recipients, assignee,
                    suggested_fix, suggested_fix_commit, breaking_change, breaking_change_rationale,
                    exploited_in_wild, exploited_in_wild_evidence, mitigation, mitigation_semgrep,
                    release_tag, release_url, last_revalidate_verdict.
      responses:
        '204': { description: Updated }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /findings/{id}/bundle.tar.gz:
    get:
      summary: Disclosure bundle for one finding
      operationId: getFindingBundle
      description: |
        A gzipped tar containing every per-finding export scrutineer
        produces (OSV, CSAF, markdown report, patch.diff when one is on
        file) plus a manifest.json header naming the finding and the
        archive contents. The per-file bytes are identical to what the
        matching /findings/{id}/{file} endpoint serves directly; the
        bundle is a composition, not a new format. Shape mirrors the
        OSS-SIRT intake brief: one summary line, aliases for
        cross-system identifiers, contents map.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: tar.gz archive.
          content:
            application/gzip:
              schema: { type: string, format: binary }
        '404': { description: Finding not found }
        '410': { description: Finding is a duplicate; bundle unavailable }
        '500': { description: Underlying export failed }

  /findings/{id}/notes:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer, format: int64 }
    get:
      summary: List notes on a finding
      operationId: listFindingNotes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/FindingNote' }
    post:
      summary: Append a note to a finding
      operationId: addFindingNote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body: { type: string }
                by:   { type: string }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FindingNote' }

  /findings/{id}/reviews:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer, format: int64 }
    get:
      summary: List structured human verdicts on a finding
      operationId: listFindingReviews
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/FindingReview' }
  /v1/audit/queue:
    get:
      summary: Sample of recently auto-bucketed findings without a recorded review
      description: |
        Returns findings the automation has bucketed as not worth pursuing
        (low-severity, rejected, or marked by revalidate as false positive,
        already fixed, or uncertain) and that do not yet have a
        FindingReview row. Spot-check the queue to keep automated triage
        calibrated.

        Instance-wide and unauthenticated; relies on the host-only
        boundary like the other `/v1/*` exports. Not reachable with a
        per-scan bearer token.
      operationId: getAuditQueue
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 50, maximum: 500 }
        - name: since
          in: query
          description: RFC3339 timestamp; excludes findings older than this.
          schema: { type: string, format: date-time }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Finding' }

  /v1/audit/metrics:
    get:
      summary: Aggregate audit metrics
      description: |
        Total reviews, those comparable to an automation outcome,
        agreements between human verdict and automation, and the
        agreement rate (0..1). The audit page renders the same numbers.

        Instance-wide and unauthenticated; relies on the host-only
        boundary like the other `/v1/*` exports.
      operationId: getAuditMetrics
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  TotalReviews: { type: integer }
                  WithAutomatedOutcome: { type: integer }
                  Agreements: { type: integer }
                  AgreementRate: { type: number, format: float }
                  ByVerdict:
                    type: object
                    additionalProperties: { type: integer }

  /findings/{id}/communications:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer, format: int64 }
    get:
      summary: List logged communications for a finding
      operationId: listFindingCommunications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/FindingCommunication' }
    post:
      summary: Log a communication (sent or received) about a finding
      operationId: addFindingCommunication
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FindingCommunication' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FindingCommunication' }

  /findings/{id}/references:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer, format: int64 }
    get:
      summary: List references attached to a finding
      operationId: listFindingReferences
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/FindingReference' }
    post:
      summary: Attach an external reference to a finding
      operationId: addFindingReference
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FindingReference' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FindingReference' }

  /findings/{id}/labels:
    put:
      summary: Replace the set of labels on a finding
      operationId: setFindingLabels
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [labels]
              properties:
                labels:
                  type: array
                  items: { type: string }
                  description: |
                    Label names, replacing the finding's current set. Missing
                    labels are created on demand. Blank and whitespace-only
                    names are trimmed and ignored, so a request whose names are
                    all blank clears every label just as `[]` does. The field
                    itself is required: omitting it or sending null is rejected
                    rather than treated as a clear-all.
      responses:
        '204': { description: Updated }
        '400':
          description: Body is not valid JSON, or has no labels array
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /findings/{id}/history:
    get:
      summary: List the history rows recorded for a finding
      operationId: listFindingHistory
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/FindingHistory' }

  /findings/{id}/skills/{name}/run:
    post:
      summary: Enqueue a finding-scoped skill (verify, revalidate, patch, reattack, disclose)
      operationId: runFindingSkill
      description: |
        The authenticated scan's repository must own the finding. The scan
        that gets enqueued has FindingID set so its skill body can read
        `scrutineer.finding_id` from context.json and act on one finding
        specifically.
        A `reattack` enqueue ignores a caller-supplied ref and pins the scan to
        the newest immutable gated patch attempt and its base commit. It returns
        412 when the finding has no gated patch.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, format: int64 }
          description: Finding id.
        - name: name
          in: path
          required: true
          schema: { type: string }
          description: Skill name.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                model: { type: string }
      responses:
        '201':
          description: Scan enqueued
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Scan' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: Finding or skill not found
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '409':
          description: 'The repository maintainer opted out of federated scanning, so no scan may be enqueued for it, or a federation peer already holds this finding and an outreach skill was asked to report it.'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '412':
          description: A re-attack was requested but the finding has no reproducible gated patch attempt.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /scans/{id}:
    get:
      summary: Fetch a scan with its report (if complete)
      operationId: getScan
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ScanDetail' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /scans/{id}/validate-report:
    post:
      summary: Validate a candidate report.json against the skill's schema
      description: >
        Lets a running skill check its report against its skill's schema using
        scrutineer's own validator, instead of installing a JSON Schema library
        inside the runner container. The request body is the candidate report
        JSON; a 200 response carries {"valid": true} when it conforms, or
        {"valid": false, "errors": "..."} listing the failures. A skill with no
        schema returns {"valid": true, "note": "skill has no schema"}. The token
        may only validate the scan it was issued for. Body is capped at 1 MB.
      operationId: validateReport
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Validation result (valid true or false; never a schema error)
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid: { type: boolean }
                  errors: { type: string }
                  note: { type: string }
                required: [valid]
        '400':
          description: Scan has no associated skill
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413':
          description: Report body exceeds the 1 MB limit
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /skills:
    get:
      summary: List installed skills
      operationId: listSkills
      parameters:
        - name: active
          in: query
          schema: { type: boolean }
          description: >
            Filter by active state. An empty value applies no filter; a value
            that is not a boolean returns 400.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/SkillSummary' }
        '400': { $ref: '#/components/responses/BadRequest' }

  /cnas:
    get:
      summary: List CVE Numbering Authorities
      description: >
        Cached copy of the cve.org partner list. Global, not repo-scoped.
        Use q to substring-match across short_name, organization, and scope.
      operationId: listCNAs
      parameters:
        - name: q
          in: query
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    short_name:   { type: string }
                    cna_id:       { type: string }
                    organization: { type: string }
                    scope:        { type: string }
                    email:        { type: string }
                    contact_url:  { type: string }
                    policy_url:   { type: string }
                    advisory_url: { type: string }
                    root:         { type: string }
                    types:        { type: string }

  /v1/repositories:
    get:
      summary: Export repositories as JSONL
      description: |
        Returns one JSON object per line (`application/x-ndjson`) for the
        Repositories tab data set. Each line includes selected scalar
        repository columns, the latest scan summary, and the same curated
        findings count shown in the UI. Large metadata and ecosystems cache
        blobs are intentionally omitted to keep the payload suitable for
        automation. No bearer token; localhost-only.
      operationId: exportRepositories
      security: []
      parameters:
        - name: format
          in: query
          schema: { type: string, enum: [jsonl] }
      responses:
        '200':
          description: JSONL stream of RepositoryExport objects, one per line.
          content:
            application/x-ndjson:
              schema: { $ref: '#/components/schemas/RepositoryExport' }
        '400':
          description: Unsupported format query value, or `encrypt`/`scope`/`include` requested (only valid on per-repository bundle exports).
        '403':
          description: Host header is not localhost

  /v1/repositories/{id}:
    delete:
      summary: Delete a repository and its linked data
      description: |
        Host-only operator endpoint for local automation. Removes the
        repository, its scans, findings, repository-scoped rows, chat
        conversations, and cached clone/workspace artifacts using the same
        cleanup path as the browser delete action. Not reachable with a
        per-scan bearer token.
      operationId: deleteRepository
      security: []
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
      responses:
        '204': { description: Repository deleted }
        '400': { description: Invalid repository id }
        '403': { description: Host header is not localhost }
        '404': { description: Repository not found }
        '409': { description: Repository has queued, running, or paused scans }
        '500': { description: Delete failed }

  /v1/repositories/{id}/findings:
    get:
      summary: Export findings for a repository (JSONL, or a shareable bundle)
      description: |
        With `format=jsonl` (the default) returns one JSON object per line
        (`application/x-ndjson`), each a `FindingExport` carrying the full set
        of `db.Finding` columns. With `format=bundle` returns a single
        self-contained JSON document (the minimal ingest shape) that
        round-trips through `/v1/import`. The default bundle is share-safe: it
        carries finding substance (the six-step audit narrative, reachability,
        sinks, VID, provenance) but not the analyst's private workspace or the
        recipient's triage — status, assignee, resolution, notes, and
        communications stay out.

        Adding `include=all` (bundle only) promotes the bundle to an archival
        superset for round-tripping a repo's findings back into your own
        instance: on top of the default it carries the enrichment and disclosure
        work product (snippet, affected, fix_version, CVE/GHSA id, CVSS vectors,
        mitigation, breaking-change verdict, dup-check, disclosure draft,
        exploited-in-wild, upstream fix commit) and the notes, communications,
        and references child records. Instance-local lifecycle (status,
        resolution, assignee), the change history, release-watch, and labels are
        never carried. It is opt-in because notes/communications are internal and
        snippet embeds verbatim source, which a cross-party share must not leak.

        Adding `encrypt=1` (bundle only) wraps the bundle in armored age,
        encrypted to every configured recipient. Adding `scope=findings` (bundle
        only) curates the bundle to the Findings bucket (deep-dive and vuln-scan
        audits plus operator imports), dropping per-repo scanner noise. No bearer
        token; localhost-only.
      operationId: exportRepositoryFindings
      security: []
      parameters:
        - $ref: '#/components/parameters/RepositoryID'
        - name: format
          in: query
          description: |
            `jsonl` (default) streams NDJSON; `bundle` returns one JSON sharing
            document. Other values get a 400.
          schema: { type: string, enum: [jsonl, bundle] }
        - name: encrypt
          in: query
          description: |
            Any non-empty value wraps a `format=bundle` export in armored age,
            encrypted to the configured recipients. Requires `format=bundle`
            and at least one configured recipient, else 400.
          schema: { type: string }
        - name: scope
          in: query
          description: |
            `findings` curates a `format=bundle` export to the Findings bucket
            (deep-dive and vuln-scan audits plus operator imports), excluding
            per-repo scanner noise. Requires `format=bundle`; any other value,
            or use on the cross-repo `/v1/findings` and `/v1/scans` endpoints,
            gets a 400. Omitted: the bundle carries every finding.
          schema: { type: string, enum: [findings] }
        - name: include
          in: query
          description: |
            `all` promotes a `format=bundle` export to the archival superset —
            the operator's enrichment and disclosure work product plus the
            notes/communications/references child records — for lossless
            round-trip into your own instance. The default bundle omits them so a
            cross-party share stays lean and leaks no internal workspace.
            Requires `format=bundle`; any other value, or use on the cross-repo
            `/v1/findings` and `/v1/scans` endpoints, gets a 400.
          schema: { type: string, enum: [all] }
        - name: severity
          in: query
          schema: { type: string, enum: [Critical, High, Medium, Low] }
        - name: status
          in: query
          schema:
            type: string
            enum: [new, enriched, triaged, ready, reported, acknowledged, fixed, published, rejected, duplicate]
      responses:
        '200':
          description: |
            JSONL stream (`format=jsonl`), a JSON sharing bundle
            (`format=bundle`), or armored age ciphertext
            (`format=bundle&encrypt=1`).
          content:
            application/x-ndjson:
              schema: { $ref: '#/components/schemas/FindingExport' }
            application/json:
              schema: { $ref: '#/components/schemas/ImportMinimal' }
            text/plain:
              schema:
                type: string
                description: Armored age ciphertext, starting `-----BEGIN AGE ENCRYPTED FILE-----`.
        '400':
          description: Unsupported `format`, `encrypt`/`scope`/`include` without `format=bundle`, an unknown `scope`/`include` value, or encryption requested with no recipients configured.
        '403':
          description: Host header is not localhost
        '404':
          description: Repository not found

  /v1/findings:
    get:
      summary: Export findings across all repositories as JSONL
      description: |
        Returns one JSON object per line (`application/x-ndjson`). No bearer
        token; localhost-only. Each line is a `FindingExport` carrying the
        full set of `db.Finding` columns.
      operationId: exportFindings
      security: []
      parameters:
        - name: format
          in: query
          schema: { type: string, enum: [jsonl] }
        - name: severity
          in: query
          schema: { type: string, enum: [Critical, High, Medium, Low] }
        - name: status
          in: query
          schema:
            type: string
            enum: [new, enriched, triaged, ready, reported, acknowledged, fixed, published, rejected, duplicate]
      responses:
        '200':
          description: JSONL stream of FindingExport objects, one per line.
          content:
            application/x-ndjson:
              schema: { $ref: '#/components/schemas/FindingExport' }
        '400':
          description: Unsupported format query value, or `encrypt`/`scope`/`include` requested (only valid on per-repository bundle exports).
        '403':
          description: Host header is not localhost

  /v1/findings/{id}:
    delete:
      summary: Delete one finding and its linked data
      description: |
        Host-only operator endpoint for local automation. Removes the finding,
        labels join rows, notes, communications, references, history, reviews,
        exposure rows, and finding-scoped chat conversations. Scans that
        pointed at the finding are preserved with `finding_id` cleared. Not
        reachable with a per-scan bearer token.
      operationId: deleteFinding
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '204': { description: Finding deleted }
        '400': { description: Invalid finding id }
        '403': { description: Host header is not localhost }
        '404': { description: Finding not found }
        '409': { description: Finding has queued, running, or paused scans }
        '500': { description: Delete failed }

  /v1/scans:
    get:
      summary: Export scans across all repositories as JSONL
      description: |
        Returns one JSON object per line (`application/x-ndjson`). No bearer
        token; localhost-only. Each line is a `ScanExport` carrying the full
        set of `db.Scan` columns minus `api_token` (the per-scan bearer must
        not leak through an unauthenticated channel).
      operationId: exportScans
      security: []
      parameters:
        - name: format
          in: query
          schema: { type: string, enum: [jsonl] }
        - name: status
          in: query
          schema: { type: string, enum: [queued, running, paused, done, failed, skipped, cancelled] }
        - name: skill
          in: query
          schema: { type: string }
      responses:
        '200':
          description: JSONL stream of ScanExport objects, one per line.
          content:
            application/x-ndjson:
              schema: { $ref: '#/components/schemas/ScanExport' }
        '400':
          description: Unsupported format query value, or `encrypt`/`scope`/`include` requested (only valid on per-repository bundle exports).
        '403':
          description: Host header is not localhost

  /v1/import:
    post:
      summary: Import externally-produced findings
      description: |
        Ingests a SARIF 2.1.0 document, a minimal JSON report, a findings
        CSV export, or a findings markdown export and creates Finding rows
        under a synthetic `Kind: import` scan. The format is sniffed from
        the body. The repository is taken from the body's own provenance
        (SARIF `versionControlProvenance`, the minimal-JSON `repository`
        field, the CSV `Repository` column, the markdown location link);
        when absent the caller must pass `?repo=`. Re-importing the same
        report dedupes by fingerprint and bumps `seen_count` rather than
        inserting duplicates. The scanner exports (SARIF, CSV, markdown)
        are raw rule output and are bounded on the way in: at most 5
        findings per rule and 50 per result are imported, in input order,
        with the drop counts reported in the response. Curated input
        imports whole.
        A body matching no supported format is
        routed to the `ingest` skill instead when `?repo=` is supplied:
        the raw payload is staged into the skill workspace and a scan is
        queued, returning 202 with the scan id. Age-encrypted bodies (armored
        or binary) are transparently decrypted first when an identity file or
        plugin is configured (`-identity-file` or `-identity-plugin`); plaintext
        bodies pass through untouched.
        No bearer token; localhost-only. See docs/import.md for the per-format
        field mapping.
      operationId: importFindings
      security: []
      parameters:
        - name: repo
          in: query
          description: Repository URL to attribute findings to. Overrides any provenance in the body.
          schema: { type: string, format: uri }
        - name: revalidate
          in: query
          description: |
            Whether each newly-imported finding is enqueued for the
            `revalidate` pre-sort (which chains into `verify` on a confirmed
            High/Critical). Defaults to true. Pass `false` to import
            already-audited findings — e.g. a trusted sharing bundle — without
            priming the funnel. A value that is neither true/false nor 1/0 is a
            400.
          schema: { type: boolean, default: true }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ImportMinimal'
                - description: SARIF 2.1.0 document (see sarif-2.1.0 schema).
                  type: object
          text/csv:
            schema:
              type: string
              description: Header row must contain Severity, Repository, Name, Description.
          text/markdown:
            schema:
              type: string
              description: One H1 per finding with H2 sections and a `**Key:** value` metadata block.
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: |
                An age-encrypted bundle (armored or binary). Decrypted in place
                when an identity is configured, then ingested as the minimal
                JSON shape above.
      responses:
        '201':
          description: Findings created and/or re-observed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ImportResponse' }
        '202':
          description: Unrecognised format routed to the ingest skill; a scan is queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  format: { type: string, enum: [unrecognised] }
                  repository_id: { type: integer }
                  repository: { type: string }
                  scan_id: { type: integer }
                  skill: { type: string, enum: [ingest] }
                  status: { type: string, enum: [queued] }
        '400':
          description: Body unreadable or empty, or `revalidate` is not a boolean
        '403':
          description: Host header is not localhost
        '413':
          description: Body exceeds 16 MiB
        '422':
          description: Unrecognised format without `?repo=` (or with the ingest skill unavailable), recognised format that fails to parse, repository unknown, or an age-encrypted body received with no identity configured

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  parameters:
    RepositoryID:
      name: id
      in: path
      required: true
      schema: { type: integer, format: int64 }
    RepositoryReadLimit:
      name: limit
      in: query
      description: Maximum number of rows to return; defaults to 200 and is capped at 1000.
      schema: { type: integer, minimum: 0, maximum: 1000, default: 200 }

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Forbidden:
      description: Token does not grant access to this resource
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    BadRequest:
      description: Malformed query or request body, or a missing required field
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error: { type: string }

    Repository:
      type: object
      required: [id, url, name]
      properties:
        id:             { type: integer, format: int64 }
        url:            { type: string, format: uri }
        name:           { type: string }
        full_name:      { type: string }
        default_branch: { type: string }
        html_url:       { type: string }
        stars:          { type: integer }
        forks:          { type: integer }
        archived:       { type: boolean }
        languages:      { type: string, description: Comma-joined language names. }
        license:        { type: string }
        fork:           { type: string, description: 'owner/name of the staging fork in fork_org, when one exists.' }
        posture:        { type: string, enum: [ready, partial, unprepared], description: 'Disclosure-readiness tier from the posture skill. Empty when posture has not run.' }
        posture_summary: { type: string }
        health:            { type: string, enum: [active, stale, abandoned, zombie], description: 'Evidence-based maintenance classification. Empty when evidence is incomplete.' }

    RepositoryExport:
      description: |
        Compact repository row used by the unauthenticated JSONL export. This
        intentionally omits large metadata and ecosystems cache blobs.
      type: object
      required: [id, url, name, findings_count, last_scan]
      properties:
        id:             { type: integer, format: int64 }
        url:            { type: string, format: uri }
        name:           { type: string }
        full_name:      { type: string }
        owner:          { type: string }
        languages:      { type: string, description: Comma-joined language names. }
        stars:          { type: integer }
        findings_count: { type: integer, description: Curated open findings count matching the Repositories tab. }
        created_at:     { type: string, format: date-time }
        updated_at:     { type: string, format: date-time }
        last_scan:
          nullable: true
          type: object
          properties:
            id:          { type: integer, format: int64 }
            kind:        { type: string }
            status:      { type: string, enum: [queued, running, paused, done, failed, skipped, cancelled] }
            skill_name:  { type: string }
            commit:      { type: string }
            created_at:  { type: string, format: date-time, nullable: true }
            finished_at: { type: string, format: date-time, nullable: true }

    ExpectedFinding:
      type: object
      required: [id, repository_id, file, cwe]
      properties:
        id:            { type: integer, format: int64 }
        repository_id: { type: integer, format: int64 }
        file:          { type: string, description: Path relative to the repository root, without line number. }
        cwe:           { type: string, description: CWE identifier, e.g. CWE-79. }
        cve:           { type: string }
        note:          { type: string }

    Scan:
      type: object
      required: [id, kind, status, repository_id]
      properties:
        id:            { type: integer, format: int64 }
        repository_id: { type: integer, format: int64 }
        kind:          { type: string }
        status:        { type: string, enum: [queued, running, paused, done, failed, skipped, cancelled] }
        model:         { type: string }
        commit:        { type: string }
        ref:           { type: string, description: Branch, tag, or commit requested for this scan. Omitted for the repository default branch. }
        sub_path:      { type: string, description: Monorepo sub-folder this scan was scoped to. Omitted for a repository-root scan. }
        rescan_mode:
          type: string
          enum: [full, diff]
          description: Requested or resolved scan mode.
        diff_base_scan_id:
          type: integer
          format: int64
          nullable: true
          description: Baseline scan used for a diff rescan.
        diff_base_commit:
          type: string
          description: Baseline commit used to generate the staged diff.
        diff_threat_model_scan_id:
          type: integer
          format: int64
          nullable: true
          description: Prior threat-model scan staged as `old_threat_model.json`, when available.
        diff_stats:
          type: string
          description: JSON metadata for staged diff inputs, including changed files and size limits.
        remediation_attempt_id:
          type: integer
          format: int64
          nullable: true
          description: Immutable gated patch attempt pinned to a re-attack scan at enqueue time.
        coverage:
          type: string
          description: JSON coverage metadata, including diff fallback reasons and threat-model update decisions.
        skill_name:           { type: string }
        skill_version:        { type: integer, description: Snapshot of the Skill row version at enqueue time. }
        skill_schema_version: { type: integer, description: Snapshot of metadata.scrutineer.version at enqueue time. }
        started_at:    { type: string, format: date-time, nullable: true }
        finished_at:   { type: string, format: date-time, nullable: true }
        max_turns_hit: { type: boolean, description: True when the scan completed with partial output after hitting the Claude max-turns cap; retry resumes the saved session when available. }
        refusal_audit_warning: { type: boolean, description: True when a security-deep-dive refusal audit reports declined or skipped analysis. }
        error:         { type: string }

    ScanDetail:
      allOf:
        - $ref: '#/components/schemas/Scan'
        - type: object
          properties:
            report: { type: string, description: Raw output report (may be JSON text). }
            refusal_audit: { type: string, description: Structured post-report security-deep-dive refusal audit. }
            log:    { type: string }

    Maintainer:
      type: object
      required: [id, login]
      properties:
        id:     { type: integer, format: int64 }
        login:  { type: string }
        name:   { type: string }
        email:  { type: string }
        status: { type: string, enum: [active, inactive, unknown] }
        notes:  { type: string }

    Package:
      type: object
      required: [id, name, ecosystem]
      properties:
        id:                 { type: integer, format: int64 }
        name:               { type: string }
        ecosystem:          { type: string }
        purl:               { type: string }
        latest_version:     { type: string }
        downloads:          { type: integer, format: int64 }
        dependent_packages: { type: integer }
        dependent_repos:    { type: integer }
        registry_url:       { type: string }
        latest_release_at:  { type: string, format: date-time, nullable: true }
        risk_flags:         { type: array, items: { type: string, enum: [single_maintainer, no_security_policy, native_extension, stale_release, maintainer_domain_expired] }, description: "Supply-chain hygiene warnings from the packages skill. The evidence for each stays in the scan report." }
        sub_path:           { type: string, description: "Monorepo sub-package this package is attributed to (its subproject path). Omitted for a repo-level package." }

    Advisory:
      type: object
      required: [id]
      properties:
        id:             { type: integer, format: int64 }
        uuid:           { type: string }
        url:            { type: string }
        title:          { type: string }
        severity:       { type: string }
        cvss_score:     { type: number }
        classification: { type: string }
        packages:       { type: string, description: Comma-joined affected package names. }
        published_at:   { type: string, format: date-time, nullable: true }
        withdrawn_at:   { type: string, format: date-time, nullable: true }

    Dependent:
      type: object
      required: [id, name, ecosystem]
      properties:
        id:              { type: integer, format: int64 }
        name:            { type: string }
        ecosystem:       { type: string }
        purl:            { type: string }
        repository_url:  { type: string }
        downloads:       { type: integer, format: int64 }
        dependent_repos: { type: integer }
        registry_url:    { type: string }
        latest_version:  { type: string }

    PackageAlternative:
      type: object
      required: [id, repository_id, purl, kind]
      properties:
        id:            { type: integer, format: int64 }
        repository_id: { type: integer, format: int64 }
        purl:          { type: string }
        kind:          { type: string, enum: [fork, successor, equivalent] }
        note:          { type: string }

    Dependency:
      type: object
      required: [id, name, ecosystem]
      properties:
        id:              { type: integer, format: int64 }
        name:            { type: string }
        ecosystem:       { type: string }
        purl:            { type: string }
        requirement:     { type: string }
        requirement_unresolved: { type: boolean }
        requirement_resolution: { type: string }
        dependency_type: { type: string, description: 'Normalised phase: runtime, dev, test, build, or an unrecognised source value.' }
        manifest_path:   { type: string }
        manifest_kind:   { type: string }

    DependencyFinding:
      type: object
      required: [package, ecosystem, finding_id, library_repository_id, severity]
      properties:
        package:               { type: string }
        ecosystem:             { type: string }
        requirement:           { type: string }
        manifest_path:         { type: string }
        dependency_type:       { type: string, description: 'Normalised phase: runtime, dev, test, build, or an unrecognised source value.' }
        finding_id:            { type: integer, format: int64 }
        library_repository_id: { type: integer, format: int64 }
        library_repository_url: { type: string, format: uri }
        title:                 { type: string }
        severity:              { type: string, enum: [Critical, High, Medium, Low] }
        cwe:                   { type: string }
        location:              { type: string, description: file:line inside the library }
        sinks:                 { type: string }
        status:                { type: string }
        trace:                 { type: string }
        boundary:              { type: string }

    FindingInput:
      type: object
      description: >
        One finding as it appears in a skill's report.json, streamed into the
        concurrent-finding log. Only title, severity and location are required;
        the other report.json finding fields (cwe, sinks, dup_check, trace, …)
        are accepted and stored. Scan-owned identity fields are ignored.
      required: [title, severity, location]
      additionalProperties: true
      properties:
        title:    { type: string }
        severity: { type: string, enum: [Critical, High, Medium, Low] }
        location: { type: string }
        cwe:      { type: string }
        sinks:    { type: array, items: { type: string } }
        dup_check: { type: string, description: "One sentence: which siblings under this scan_group you compared against and why this one is distinct." }

    FindingSummary:
      type: object
      required: [id, scan_id, repository_id, severity, location]
      properties:
        id:            { type: integer, format: int64 }
        scan_id:       { type: integer, format: int64 }
        repository_id: { type: integer, format: int64 }
        finding_id:    { type: string, description: Short id within the scan report (F1, F2, ...). }
        sinks:         { type: string, description: Comma-joined sink ids. }
        title:         { type: string }
        severity:      { type: string, enum: [Critical, High, Medium, Low] }
        severity_caps: { type: array, items: { type: string }, description: "Deterministic reasons that currently cap severity, derived from the latest reconciled verification controls and typed attacker prerequisites." }
        severity_calibration_incomplete: { type: boolean, description: "True when an unknown severity, unknown or unattempted prerequisite, unavailable control resolution, or unresolved control assessment prevented complete calibration; unknown inputs never lower severity." }
        status:        { type: string }
        cwe:           { type: string }
        location:      { type: string }
        vid:           { type: string, description: "Code identifier (VID-...) hashed from the sink code at the scanned commit; correlates findings across tools. Empty when not computed." }
        affected:      { type: string }
        reachability:  { type: string, enum: [reachable, harness_only, unclear] }
        quality_tier:  { type: string, enum: [high, low] }
        cve_id:        { type: string }
        ghsa_id:       { type: string, description: "GitHub Security Advisory id (GHSA-xxxx-xxxx-xxxx), set once the advisory is published." }
        cvss_vector:    { type: string, description: "CVSS v3.x base vector (3.0 or 3.1)." }
        cvss_score:     { type: number, description: "Base score derived from cvss_vector." }
        cvss_v4_vector: { type: string, description: "CVSS v4.0 base vector. Independent of cvss_vector; both may be populated." }
        cvss_v4_score:  { type: number, description: "Base score derived from cvss_v4_vector." }
        fix_version:   { type: string }
        fix_commit:    { type: string }
        resolution:    { type: string, enum: [fix, migrate, workaround, adopt, wontfix, ""] }
        assignee:      { type: string }
        exploited_in_wild: { type: string, enum: [yes, no, ""], description: "Analyst's call on whether this finding is being exploited in the wild. Empty means unknown. Automation never sets this." }
        exploited_in_wild_evidence: { type: string }
        mitigation:    { type: string, description: "Markdown body of operational mitigation guidance from the mitigate skill: workarounds, detection, optionally a semgrep rule (see mitigation_semgrep)." }
        mitigation_semgrep: { type: string, description: "Optional YAML semgrep rule from the mitigate skill. Empty when no rule was warranted." }
        dup_check:     { type: string, description: "Audit agent's one-sentence rationale for why this finding is distinct from the siblings already filed under the same scan_group. Empty for findings from skills that do not emit it." }
        novelty:       { type: string, enum: [unfixed, fixed, unclear, not_checked, ""], description: "Latest upstream novelty state. A touched file remains unclear until revalidate classifies the staged history." }
        production_viability: { type: string, enum: [VIABLE, NON_VIABLE, SAMPLE_OR_TEST, CONDITIONAL_VIABLE, ""], description: "Latest critic assessment of whether the finding can affect a real release build. Empty before assessment." }
        novelty_checked_commit: { type: string, description: "Repository HEAD compared with the finding's scanned commit for novelty." }
        novelty_checked_at: { type: string, format: date-time, nullable: true }

    FindingDetail:
      allOf:
        - $ref: '#/components/schemas/FindingSummary'
        - type: object
          description: Adds the six-step narrative and the disclosure draft/routing fields.
          properties:
            trace:            { type: string }
            boundary:         { type: string }
            validation:       { type: string }
            prior_art:        { type: string }
            reach:            { type: string }
            rating:           { type: string }
            disclosure_draft: { type: string }
            disclosure_title: { type: string, description: "The disclose skill's drafted GHSA summary; may differ from the finding's own title." }
            suggested_recipients: { type: string, description: "File-level owners for the finding's location, from CODEOWNERS or recent non-bot committers." }
            sub_path:         { type: string, description: "Monorepo sub-folder the producing scan was scoped to. The finding's location is relative to it; empty means the repo root." }
            verification:
              allOf:
                - $ref: '#/components/schemas/FindingVerification'
              nullable: true
            attack_path:
              allOf:
                - $ref: '#/components/schemas/FindingAttackPath'
              nullable: true
            remediation:
              allOf:
                - $ref: '#/components/schemas/RemediationAttempt'
              nullable: true

    FindingVerification:
      type: object
      required: [id, scan_id, status, report, created_at]
      properties:
        id:         { type: integer, format: int64 }
        scan_id:    { type: integer, format: int64 }
        status:     { type: string, enum: [confirmed, fixed, inconclusive, deferred, not_attempted] }
        score:      { type: number, format: double, minimum: 0, maximum: 1, nullable: true, description: "Fraction of the five fixed verification criteria that passed. Null for legacy reports and reports that remain internally inconsistent after repair." }
        report:     { $ref: '#/components/schemas/VerificationReport' }
        created_at: { type: string, format: date-time }

    FindingAttackPath:
      type: object
      required: [id, scan_id, production_viability, report, created_at]
      properties:
        id:                   { type: integer, format: int64 }
        scan_id:              { type: integer, format: int64 }
        production_viability: { type: string, enum: [VIABLE, NON_VIABLE, SAMPLE_OR_TEST, CONDITIONAL_VIABLE] }
        report:               { $ref: '#/components/schemas/AttackPathReport' }
        created_at:           { type: string, format: date-time }

    AttackPathReport:
      type: object
      required: [production_viability, source_state, reason, counterevidence, attacker_position, preconditions, impact, likelihood, applied_adjustments, facts_that_would_change_the_result]
      additionalProperties: false
      properties:
        production_viability: { type: string, enum: [VIABLE, NON_VIABLE, SAMPLE_OR_TEST, CONDITIONAL_VIABLE] }
        source_state: { type: string, enum: [PRESENT, MOVED, MISSING, UNKNOWN] }
        reason: { type: string }
        counterevidence: { type: array, items: { type: string } }
        attacker_position: { type: string }
        preconditions: { type: array, items: { type: string } }
        impact: { type: string }
        likelihood: { type: string, enum: [likely, plausible, unlikely, unknown] }
        applied_adjustments:
          type: array
          maxItems: 0
          description: "Reserved for severity-cap calibration; critic emits an empty array."
          items:
            type: object
            required: [kind, reason, severity_before, severity_after]
            additionalProperties: false
            properties:
              kind: { type: string }
              reason: { type: string }
              severity_before: { type: string, enum: [Critical, High, Medium, Low] }
              severity_after: { type: string, enum: [Critical, High, Medium, Low] }
        facts_that_would_change_the_result: { type: array, items: { type: string } }

    RemediationAttempt:
      type: object
      required: [id, attempt, patch_scan_id, base_commit, status, created_at]
      properties:
        id:            { type: integer, format: int64 }
        attempt:       { type: integer, minimum: 1 }
        patch_scan_id: { type: integer, format: int64 }
        base_commit:   { type: string }
        status:        { type: string, enum: [verification_incomplete, bypassed_patch, verified_secure] }
        created_at:    { type: string, format: date-time }
        validation:
          allOf:
            - $ref: '#/components/schemas/RemediationValidation'
          nullable: true

    RemediationValidation:
      type: object
      required: [scan_id, outcome, valid_variants, benign_control_passed, bypass_input, created_at]
      properties:
        scan_id:               { type: integer, format: int64 }
        outcome:               { type: string, enum: [failed_to_bypass, bypassed_patch, inconclusive] }
        valid_variants:        { type: integer, minimum: 0 }
        benign_control_passed: { type: boolean }
        bypass_input:          { type: string }
        created_at:            { type: string, format: date-time }

    VerificationReport:
      type: object
      description: "Immutable verify output containing an evidenced attack tree, typed attacker prerequisites, three attempt records, five scored criteria, and a non-scored host-validated control-bypass gate. Historical reports may omit attack_tree, severity_prerequisites, or criteria.control_bypass. See skills/verify/schema.json for the current output contract."
      required: [status]
      additionalProperties: true
      properties:
        status: { type: string, enum: [confirmed, fixed, inconclusive, deferred, not_attempted] }
        attack_tree:
          type: object
          description: "Claim-specific attack path with a rooted parent-linked node set, per-node evidence, an overall reachable/blocked/unproven/not_attempted verdict, and concrete blockers."
          additionalProperties: true
          properties:
            goal: { type: string }
            root_id: { type: string }
            verdict: { type: string, enum: [reachable, blocked, unproven, not_attempted] }
            nodes:
              type: array
              items: { type: object, additionalProperties: true }
            blockers:
              type: array
              items: { type: string }
        severity_prerequisites:
          type: object
          description: "Evidence-backed inputs for deterministic severity caps. Required by the current verify contract; optional here only for historical stored reports. Unknown inputs mark calibration incomplete and never lower severity."
          required: [attacker_position, user_interaction, outcome_determinism, impact, existing_capability]
          additionalProperties: false
          properties:
            attacker_position:
              type: object
              required: [value, evidence]
              properties:
                value: { type: string, enum: [remote_unauthenticated, remote_authenticated, internal_authenticated, local, host_shell, long_term_physical, unknown, not_attempted] }
                evidence: { type: string }
            user_interaction:
              type: object
              required: [value, evidence]
              properties:
                value: { type: string, enum: [none, required, unknown, not_attempted] }
                evidence: { type: string }
            outcome_determinism:
              type: object
              required: [value, evidence]
              properties:
                value: { type: string, enum: [deterministic, probabilistic_llm, unknown, not_attempted] }
                evidence: { type: string }
            impact:
              type: object
              required: [value, evidence]
              properties:
                value: { type: string, enum: [code_execution_or_equivalent, privilege_escalation, sensitive_data_access, availability, other, unknown, not_attempted] }
                evidence: { type: string }
            existing_capability:
              type: object
              required: [value, evidence]
              properties:
                value: { type: string, enum: [none, less_than_outcome, support_channel_equivalent, equivalent_or_greater, unknown, not_attempted] }
                evidence: { type: string }
        attempts:
          type: array
          minItems: 3
          maxItems: 3
          items: { type: object, additionalProperties: true }
        criteria:
          type: object
          additionalProperties: true
          properties:
            control_bypass:
              type: object
              required: [matched_controls, assessments]
              properties:
                matched_controls:
                  type: array
                  uniqueItems: true
                  items: { type: string }
                unavailable_reason:
                  type: string
                  description: "Exact host-staged reason control resolution failed; omitted when resolution succeeded or no controls exist."
                assessments:
                  type: array
                  items:
                    type: object
                    required: [control_id, disposition, evidence]
                    properties:
                      control_id: { type: string }
                      disposition: { type: string, enum: [bypassed, held, not_applicable, unresolved, not_attempted] }
                      evidence: { type: string }

    FindingExport:
      description: |
        Full db.Finding row used by the unauthenticated JSONL export. Adds
        the dedup, denormalised, and timestamp columns that the bearer-only
        FindingDetail leaves out.
      allOf:
        - $ref: '#/components/schemas/FindingDetail'
        - type: object
          properties:
            commit:            { type: string }
            fingerprint:       { type: string }
            last_seen_scan_id: { type: integer, format: int64 }
            last_seen_commit:  { type: string }
            seen_count:        { type: integer }
            created_at:        { type: string, format: date-time }
            updated_at:        { type: string, format: date-time }

    ImportMinimal:
      description: |
        Minimal hand-written ingest shape for findings from a pentest writeup or
        a tool with no SARIF emitter. It is also the shape scrutineer's own
        `format=bundle` export emits and `/v1/import` round-trips: the seven base
        fields, the extended fields every bundle carries, and the archival fields
        an `include=all` bundle adds. Everything past the base seven is optional;
        a hand-written report or a bundle produced before a field existed simply
        omits it.
      type: object
      required: [findings]
      properties:
        repository: { type: string, format: uri }
        commit:     { type: string }
        tool:       { type: string, description: "Producer name; defaults to 'manual'." }
        findings:
          type: array
          items:
            type: object
            properties:
              title:       { type: string }
              description: { type: string }
              severity:    { type: string, enum: [critical, high, medium, low] }
              confidence:  { type: string, enum: [high, medium, low] }
              cwe:         { type: string }
              location:    { type: string, description: "path[:line[:col]]" }
              patch:       { type: string, description: "unified diff" }
              # Extended fields every scrutineer bundle carries (six-step audit
              # prose, provenance, correlation).
              commit:       { type: string, description: "Per-finding revision; falls back to the top-level commit." }
              sub_path:     { type: string }
              locations:    { type: string, description: "Newline-joined file:line hit set." }
              sinks:        { type: string, description: "Comma-joined sink ids." }
              vid:          { type: string }
              reachability: { type: string, enum: [reachable, harness_only, unclear] }
              quality_tier: { type: string, enum: [high, low] }
              boundary:     { type: string }
              validation:   { type: string }
              prior_art:    { type: string }
              reach:        { type: string }
              rating:       { type: string }
              fix_commit:   { type: string, description: "Base revision the patch applies to." }
              # Archival fields, emitted only with include=all: the operator's
              # enrichment, disclosure work product, and child records.
              snippet:                    { type: string }
              affected:                   { type: string, description: "Vulnerable version range." }
              fix_version:                { type: string }
              cve_id:                     { type: string }
              ghsa_id:                    { type: string }
              cvss_vector:                { type: string, description: "v3.x base vector; score recomputed on import." }
              cvss_v4_vector:             { type: string, description: "v4.0 base vector; score recomputed on import." }
              mitigation:                 { type: string }
              mitigation_semgrep:         { type: string }
              breaking_change:            { type: string, enum: [breaking, non_breaking, unknown] }
              breaking_change_rationale:  { type: string }
              dup_check:                  { type: string }
              disclosure_draft:           { type: string }
              disclosure_title:           { type: string, description: "The disclose skill's drafted GHSA summary; may differ from the finding's own title." }
              suggested_recipients:       { type: string, description: "File-level owners for the finding's location, from CODEOWNERS or recent non-bot committers." }
              exploited_in_wild:          { type: string, enum: [yes, no] }
              exploited_in_wild_evidence: { type: string }
              upstream_fix_commit:        { type: string, description: "Real upstream fix commit (distinct from fix_commit)." }
              notes:
                type: array
                items:
                  type: object
                  properties:
                    body:       { type: string }
                    by:         { type: string }
                    created_at: { type: string, format: date-time }
              communications:
                type: array
                items:
                  type: object
                  properties:
                    channel:      { type: string, enum: [email, ghsa, issue, pr, direct, registry] }
                    direction:    { type: string, enum: [outbound, inbound] }
                    actor:        { type: string }
                    body:         { type: string }
                    offered_help: { type: string, enum: [pr, funding, adoption, none] }
                    at:           { type: string, format: date-time }
                    created_at:   { type: string, format: date-time }
              references:
                type: array
                items:
                  type: object
                  properties:
                    url:        { type: string, format: uri }
                    tags:       { type: string, description: "Comma-joined: issue, pr, cve, ghsa, patch, advisory, discussion, article." }
                    summary:    { type: string }
                    created_at: { type: string, format: date-time }

    ImportResponse:
      type: object
      properties:
        format: { type: string, enum: [sarif, minimal, csv, markdown] }
        results:
          type: array
          items:
            type: object
            properties:
              repository_id: { type: integer, format: int64 }
              repository:    { type: string, format: uri }
              scan_id:       { type: integer, format: int64 }
              tool:          { type: string }
              created:       { type: integer }
              observed:      { type: integer }
              received:
                type: integer
                description: Findings the parser produced for this result, before the scanner caps.
              accepted:
                type: integer
                description: |
                  Findings that survived the scanner caps and were imported.
                  Equal to `received` for the curated formats. A scanner
                  export (SARIF, CSV, markdown) is capped at 5 findings per
                  rule and 50 per result.
              dropped_per_rule:
                type: integer
                description: Findings rejected by the per-rule cap.
              dropped_total_cap:
                type: integer
                description: |
                  Findings rejected by the per-result cap. A finding both caps
                  would reject counts against `dropped_per_rule` only, so the
                  two drop counts sum to `received` minus `accepted`.
              finding_ids:
                type: array
                items: { type: integer, format: int64 }

    ScanExport:
      description: |
        Full db.Scan row used by the unauthenticated JSONL export, minus
        api_token.
      allOf:
        - $ref: '#/components/schemas/ScanDetail'
        - type: object
          properties:
            skill_id:           { type: integer, format: int64, nullable: true }
            finding_id:         { type: integer, format: int64, nullable: true }
            sub_path:           { type: string }
            cost_usd:           { type: number }
            turns:              { type: integer }
            input_tokens:       { type: integer }
            output_tokens:      { type: integer }
            cache_read_tokens:  { type: integer }
            cache_write_tokens: { type: integer }
            prompt:             { type: string }
            findings_count:     { type: integer }
            created_at:         { type: string, format: date-time }
            updated_at:         { type: string, format: date-time }

    FindingNote:
      type: object
      required: [id, finding_id, body]
      properties:
        id:         { type: integer, format: int64 }
        finding_id: { type: integer, format: int64 }
        body:       { type: string }
        by:         { type: string }
        created_at: { type: string, format: date-time }

    FindingReview:
      type: object
      required: [id, finding_id, verdict]
      properties:
        id:                { type: integer, format: int64 }
        finding_id:        { type: integer, format: int64 }
        verdict:           { type: string, enum: [true_positive, false_positive, already_fixed, uncertain] }
        reason:            { type: string }
        automated_outcome: { type: string, description: Automation verdict snapshotted at review time, empty when no revalidate run had spoken. }
        reviewer:          { type: string }
        created_at:        { type: string, format: date-time }

    FindingCommunication:
      type: object
      required: [channel, direction, actor]
      properties:
        id:           { type: integer, format: int64 }
        finding_id:   { type: integer, format: int64 }
        channel:      { type: string, enum: [email, ghsa, issue, pr, direct, registry] }
        direction:    { type: string, enum: [outbound, inbound] }
        actor:        { type: string }
        body:         { type: string }
        offered_help: { type: string, enum: [pr, funding, adoption, "none", ""] }
        at:           { type: string, format: date-time }
        created_at:   { type: string, format: date-time }

    FindingReference:
      type: object
      required: [url]
      properties:
        id:         { type: integer, format: int64 }
        finding_id: { type: integer, format: int64 }
        url:        { type: string, format: uri }
        tags:       { type: string, description: Comma-joined tags (issue, pr, cve, ghsa, patch, advisory, discussion, article). }
        summary:    { type: string }
        created_at: { type: string, format: date-time }

    FindingHistory:
      type: object
      required: [id, finding_id, field, new_value, source]
      properties:
        id:         { type: integer, format: int64 }
        finding_id: { type: integer, format: int64 }
        field:      { type: string }
        old_value:  { type: string }
        new_value:  { type: string }
        source:     { type: string, enum: [tool, model_suggested, analyst] }
        by:         { type: string }
        created_at: { type: string, format: date-time }

    SkillSummary:
      type: object
      required: [id, name, description]
      properties:
        id:          { type: integer, format: int64 }
        name:        { type: string }
        description: { type: string }
        output_kind: { type: string }
        output_file: { type: string }
        version:     { type: integer }
        active:      { type: boolean }