# CaskMCP Scopes

Scopes are the reviewable capability boundary between inferred API behavior and approved runtime authority.

## Ownership model

- `scopes.suggested.yaml` is generated by capture/compile/verify workflows.
- `scopes.yaml` is user-owned and authoritative.
- `caskmcp scopes merge` proposes diffs and never silently overwrites authoritative scope definitions.
- `scopes merge` accepts both canonical `scopes:` maps and compile-emitted draft lists (`drafts:`), normalizing drafts into reviewable scope entries.
- Draft `endpoint_id` values are **published action signatures** (the `signature_id` values in `tools.json`), so scope drafts can be joined to the runtime tool surface even when compilation performs transforms (for example GraphQL operation splitting).

Toolset derivation and lockfile bindings are computed from `scopes.yaml` only.

## Scope contract

Each scope should encode:

1. Intent/effect class (`read`, `search`, `write`, `admin`, etc.).
2. Surface constraints (host/method/path templates and optional param/body constraints).
3. Risk and sensitivity (`low|medium|high|critical`, plus PII/financial/auth markers).
4. Execution constraints (rate/budget/confirmation rules).
5. Confidence and review state (`confidence`, `review_required`, evidence signals).

## Draft-first inference pipeline

1. Structural normalization (method/host/path templates).
2. Deterministic rule matching (path/body/query/auth signals).
3. Capability labeling and risk scoring.
4. Conservative fallback for low-confidence findings.

Generated drafts are advisory and require human review before promotion.

## High-risk gate rule

If confidence is low and risk is `high` or `critical`:

- mark `review_required: true`
- block auto-publish
- fail CI by default on broadening changes

## Scope binding invariants

- Toolsets derive from authoritative scopes only.
- Lockfile records bind `scope_id` and `scope_digest`.
- Scope broadening requires explicit approval.

## Example scope draft

```yaml
version: 1
scopes:
  search_readonly:
    intent: search
    surface:
      hosts: [api.example.com]
      methods: [GET]
      paths: [/search, /products]
    risk_tier: low
    constraints:
      confirmation: none
    confidence: 0.91
    review_required: false
```
