docs: add a contributor-facing capability glossary (#48)

* docs: add a contributor-facing capability glossary

Observe, Tool Enforcement and Full Compute Enforcement are defined in the
integration overview's "Integration labels" section, but an adapter PR had no
single page to link to, and the reasoning a reviewer applies was spread across
the overview and CONTRIBUTING.

Add docs/reference/capability-glossary.md restating the three definitions
verbatim in substance, plus the boundaries that decide between them:

- a prompt instruction, skill, or advisory middleware is not enforced
  interception;
- transporting a protocol directive is not implementing it -- protocol v1
  defines seven, the reference v0.2 runtime emits allow and deny;
- Enforce Mode requires block_actions=True, and UniversalRuntime rejects an
  observe-only adapter configured as enforced.

Uses the two current examples the codebase already documents: Codex as Tool
Enforcement (not Full Compute Enforcement, because specialized and hosted tool
paths can fall outside local hook coverage) and Claude Code as Observe. The
Claude Code entry notes that engine-declared outcome evidence is a statement
about evidence quality, not capability, since that is the likeliest way to
misread the label.

Closes with a four-step "choosing a label" checklist that resolves ties
downward: under-claiming is conservative, over-claiming invites a user to rely
on a control that fails open.

No capability claim is broadened; every statement traces to overview.md or
CONTRIBUTING.md. Linked from docs/index.md, the integration overview and the
adapter section of CONTRIBUTING.md.

Closes #37

* docs: link the capability glossary from the docs index, overview and CONTRIBUTING

The glossary is only useful if an adapter PR can find it. Link it from the
three places a contributor actually looks:

- docs/index.md, under Reference;
- the "Integration labels" section of the integration overview, next to the
  normative definitions it restates;
- the adapter section of CONTRIBUTING.md, after the Full Compute Enforcement
  bar.

Refs #37

Author: dchaudhari7177

CONTRIBUTING.md

@@ -62,6 +62,8 @@ An adapter must:
 
 An adapter must not advertise Full Compute Enforcement unless the underlying engine exposes official controls for the relevant model turns, tool calls, retry loops, and stopping behavior.
 
+The [capability glossary](docs/reference/capability-glossary.md) defines Observe, Tool Enforcement, and Full Compute Enforcement, and gives the questions a reviewer uses to pick between them.
+
 ## Estimator contributions
 
 An estimator must expose a stable name, semantic version, configuration hash, training-data fingerprint when applicable, and provenance. It must report uncertainty or explicitly state that uncertainty is unavailable. Claims of causal marginal value require an identification strategy, not only historical correlation.

docs/index.md

@@ -30,6 +30,7 @@ MARGINAL documentation is organized by user intent instead of keeping every guid
 ## Reference
 
 - [API reference](reference/api.md)
+- [Capability glossary](reference/capability-glossary.md)
 
 ## Operations
 

docs/integrations/overview.md

@@ -68,6 +68,9 @@ Documentation must distinguish:
 
 A prompt instruction, skill, or advisory middleware is not equivalent to enforced interception.
 
+See the [capability glossary](../reference/capability-glossary.md) for the contributor-facing
+version of these definitions, including how to choose a label for a new adapter.
+
 ## Current status
 
 The v0.3 candidate implements and validates the native Codex plugin against Codex CLI 0.147.0.

docs/reference/capability-glossary.md

@@ -0,0 +1,99 @@
+# Capability glossary
+
+MARGINAL labels every integration with exactly one capability level. The label
+is a claim about what the integration can *do*, not about how much evidence it
+collects, and it is the first thing a reviewer checks on an adapter pull
+request.
+
+The normative definitions live in the
+[integration overview](../integrations/overview.md#integration-labels). This
+page restates them for contributors and adds the reasoning a reviewer applies,
+so an adapter PR can link to one place.
+
+## The three levels
+
+### Observe
+
+Telemetry and non-blocking recommendations.
+
+An Observe integration records normalized evidence and may surface advice, but
+it declares no control capability and never blocks or alters an action. If the
+integration were removed, the engine would behave identically.
+
+### Tool Enforcement
+
+Supported tool actions can be blocked or changed.
+
+The integration intercepts tool calls through an official engine control point
+and a deny or modify directive actually takes effect. The qualifier
+**supported** carries weight: a level is Tool Enforcement, not Full Compute
+Enforcement, when some tool paths fall outside that coverage.
+
+### Full Compute Enforcement
+
+Model turns, tools, retries, and stop behavior are controllable and measured.
+
+This is the whole compute loop, not just the tool surface.
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md#adapter-contributions) states the bar
+directly: an adapter must not advertise Full Compute Enforcement unless the
+underlying engine exposes official controls for the relevant model turns, tool
+calls, retry loops, and stopping behavior.
+
+## What is not enforcement
+
+A prompt instruction, skill, or advisory middleware **is not** equivalent to
+enforced interception.
+
+Asking a model not to do something is not the same as being able to stop it.
+Only an official engine control point that MARGINAL can refuse through counts
+toward an enforcement label. Text that the model is free to ignore does not,
+however reliably it happens to be obeyed in practice.
+
+Two related boundaries a reviewer will also check:
+
+- **Transporting a directive is not implementing it.** Protocol v1 defines
+  allow, deny, modify, defer, reuse, stop, and force-verify, but the reference
+  v0.2 runtime emits only allow and deny. An adapter may carry the broader
+  contract; documentation must not imply the rest are generated automatically
+  until a policy implements them.
+- **Enforce Mode requires `block_actions=True`.** `UniversalRuntime` rejects an
+  observe-only adapter configured as enforced, so the label and the
+  configuration cannot silently disagree.
+
+## Current MARGINAL examples
+
+### Codex — Tool Enforcement
+
+The native Codex plugin is validated against Codex CLI 0.147.0 and provides
+lifecycle correlation, an authenticated local service, Shadow Mode, and Earned
+Enforcement receipts.
+
+It is labeled Tool Enforcement rather than Full Compute Enforcement because
+specialized and hosted tool paths can fall outside local hook coverage. The
+gap is in coverage, not in the mechanism — which is exactly the distinction the
+two labels exist to record. See [Codex plugin](../integrations/codex.md).
+
+### Claude Code — Observe
+
+The Claude Code plugin records normalized evidence and repeated-work
+recommendations in a local Decision Ledger, declares no control capability, and
+never blocks a tool call.
+
+Its outcome evidence is engine-declared, because Claude Code reports success
+and failure as separate hook events. Note that this is a statement about
+evidence quality, not capability: richer evidence does not move an integration
+up a level. See [Claude Code plugin](../integrations/claude-code.md).
+
+## Choosing a label
+
+1. Can the integration refuse or alter an action through an official engine
+   control point, such that the engine honors it? If no, the label is
+   **Observe**.
+2. Does that control cover every tool path, or only the supported ones? Partial
+   coverage is **Tool Enforcement**.
+3. Does it additionally control model turns, retries, and stopping, with those
+   measured? Only then is it **Full Compute Enforcement**.
+
+When a step is uncertain, claim the lower label. An integration that
+under-claims is merely conservative; one that over-claims invites a user to
+rely on a control that will fail open.