# Clarity Contract

### Two models agreed. Their example still assumed a fact.

Astra and Fable co-wrote a style guide. When asked to challenge it, Fable caught an unsupported assumption in their own “better” error message: a **25 MB upload limit that had never been established**.

So we turned the guide into a contract you can inspect, reuse and try to break.

**[Live playground](https://astra-fable-style-guide-meliwat.muhammedeliwat.chatgpt.site) · [Copy the agent guide](STYLE_GUIDE.md) · [Exact experiment](research/study.json) · [MIT license](LICENSE)**

![Agreement is not evidence: an agent style contract with real disagreements and six paired tests](docs/social-card.png)

## Save this part

```text
Truth and consequences > access > useful next step > brevity.

Never invent a cause, capability, action, deadline or promise
just to make the answer sound more helpful.

Unknown cause? Preserve the uncertainty.
Irreversible action? Name the scope and consequence.
Task complete? Stop. Don't invent a next step.
```

Copy [STYLE_GUIDE.md](STYLE_GUIDE.md) into your agent's project instructions, or use the structured [contract](research/contract.json). This is a prompt and decision aid, not an enforcement mechanism.

## The difference in one example

**Known facts:** upload failed; cause unknown; file remains selected; retry is supported.

| Unsupported specificity | Grounded response |
| --- | --- |
| “Your file exceeds 25 MB. Compress it and retry.” | “Upload failed. The cause is unknown. Your file is still selected. Retry upload.” |

The first response sounds useful. It makes up the diagnosis. The second gives the supported next step.

## What you get

- **Seven conditional rules** with explicit conflict priorities and review requirements.
- **An interactive resolver:** choose task, evidence and consequence; get the applicable contract.
- **Six paired Fable outputs**, with exact prompts and visible failures.
- **An adversarial review transcript:** what Fable challenged, what Astra rejected, what both accepted.
- **Browser WebMCP and HTTP MCP tools** sharing the same rule engine.
- **Zero runtime dependencies.** No API key needed to run the recorded demo.

## What the experiment actually found

One fresh Fable CLI session per condition, six tasks batched in fixed order. The guided condition received contract **2.0**. The current revision is **2.1**; it has **not** been retested in this comparison.

| Case | Observation |
| --- | --- |
| Unknown upload failure | Guided output removed an unsupported Cancel action. |
| Unconfirmed launch | Both still added unsupported future workflow details. |
| Irreversible deletion | Both named scope and consequence; no clear advantage. |
| Offline save | Outputs were identical. |
| Compact form | Both included labels, linked errors and focus styling; runtime accessibility untested. |
| Successful export | Both stopped after confirming completion. |

**This is an exploratory comparison, not a benchmark victory.** One sample per condition, six authored tasks, unblinded Astra review, no independent human evaluation or significance claim. The baseline was already good in several cases. Agreement is not evidence of better performance.

Read the [full study](research/study.json), [tested contract](research/contract-tested.json), and [review transcript](research/provenance.json). Model output identity reported by the CLI: `claude-fable-5-1`. Astra is the authoring/reviewing agent, not a separately benchmarked condition.

## Run locally

Requires Node.js 22 or newer. No install step or API credentials.

```bash
git clone https://github.com/Meliwat/clarity-contract.git
cd clarity-contract
npm start
```

Open **http://localhost:4173**.

```bash
npm test        # build + 20 context combinations, document routes and MCP checks
npm run build   # create the self-contained Worker bundle
```

`PORT=8080 npm start` changes the local port. The local server binds to loopback.

## Use through MCP

Public Streamable HTTP endpoint:

```text
https://astra-fable-style-guide-meliwat.muhammedeliwat.chatgpt.site/api/mcp
```

Use a client that supports Streamable HTTP, with that URL and no API key. The implemented protocol version is `2025-03-26`. The server is stateless and read-only; it returns JSON responses and does not offer an SSE stream or automatic OAuth/plugin provisioning.

| Tool | Inputs | Result |
| --- | --- | --- |
| `get_style_guide` | `{}` | Current contract and limits |
| `resolve_style_contract` | `task`, `evidence`, `consequence` | Applicable rules and reasons |
| `inspect_style_case` | `id` | Recorded prompt, outputs and finding |

Example (not a model call):

```bash
curl -sS https://astra-fable-style-guide-meliwat.muhammedeliwat.chatgpt.site/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resolve_style_contract","arguments":{"task":"confirmation","evidence":"known","consequence":"irreversible"}}}'
```

Tasks: `error`, `confirmation`, `status`, `success`, `interface`. Evidence: `known`, `unknown`. Consequence: `reversible`, `irreversible`. This models a deliberately small set of contexts, not every writing situation.

In browsers supporting `document.modelContext`, the same three **WebMCP** tools are registered. Browser resolver and case-selection calls update the visible page; HTTP calls only return data. Unsupported browsers still have a normal working interface.

## Reproduce or extend the experiment

The exact baseline and guided prompts are in `research/study.json` under `prompts`. Use fresh model sessions and preserve model identity, settings, exact outputs and failed cases. The recorded run used the installed Fable CLI with default settings, no temperature control, and its existing system context. It is not a controlled cross-model study.

The repository serves recorded outputs. It does not call a model or collect your inputs. To propose a new case, see [CONTRIBUTING.md](CONTRIBUTING.md).

**The best contribution: an example where following the contract still produces a bad answer.**

## Structure

```text
STYLE_GUIDE.md          Copyable agent instructions
research/contract.json Current contract (2.1)
research/study.json    Prompts, exact outputs, analysis, limitations
research/provenance.json  Visible review and agreement transcript
src/engine.js         Shared deterministic resolver
src/client.js         Browser controls and WebMCP
src/worker.js         HTTP routes and MCP
scripts/              Build, local server and checks
```

`npm run build` generates `dist/server/index.js`, a self-contained Worker with a Fetch handler. It can be deployed to a compatible runtime. A Sites manifest is optional for local builds and is deliberately excluded from this public repository. The live demo is hosted with Sites; no hosting credentials are included.

## License and attribution

MIT © 2026 Meliwat. Created with Astra and Fable in response to Tibo's suggestion to have them agree on a style guide and host it with WebMCP. No affiliation or endorsement is implied. Model-authored text and human-facing analysis are disclosed in the study.