# Token-efficient prompt contracts

`simplicio-prompt` teaches the LLM to use the deterministic contracts
defined in
[`wesleysimplicio/simplicio-runtime#70`](https://github.com/wesleysimplicio/simplicio-runtime/issues/70).
The principle generalizes the mechanical-edit contract (#69) beyond
file editing: when the runtime can hand the model a compact, typed
artifact, the model uses it instead of pasting or producing large
unstructured text.

This repo references the canonical schemas; it does **not** fork them.

## Contracts in play

| Contract | Purpose |
|---|---|
| `simplicio.artifact-response/v1` | Generic typed envelope for an artifact-only reply. Body is a `Plan` / `EditPlan` / `TestPlan` / `ReviewDecision` / `FailureAnalysis` / `RetryRequest`. |
| `simplicio.log-summary/v1` | Request or emit a compact log summary instead of streaming full logs. |
| `simplicio.diff-review/v1` | Review a change using diff + structured evidence, not by re-reading whole files. |
| `simplicio.postconditions/v1` | Express success criteria as machine-checkable assertions (regex matches, tests pass, hashes change). |
| `simplicio.retry/v1` | Structured retry request when a deterministic tool fails — what failed, what to try next, what context to add. |
| `simplicio.model-routing/v1` | Route repetitive low-risk work to cheap/local roles when policy allows; reserve paid remote capacity for steps that need it. |

## What the model emits

When the runtime requests an artifact response, the body is exactly
**one** of the typed artifacts below. The whole reply is strict JSON
— no prose, no markdown fences, no preamble.

### Plan

```json
{
  "schema": "simplicio.artifact-response/v1",
  "artifact": "Plan",
  "steps": [
    { "id": 1, "title": "Pull context for router.ts", "contract": "context_request" },
    { "id": 2, "title": "Patch GET handler", "contract": "simplicio.mechanical-edit/v1" },
    { "id": 3, "title": "Run targeted tests", "contract": "validation" }
  ],
  "postconditions": [
    { "kind": "regex", "file": "src/router.ts", "pattern": "req\\.method === \"HEAD\"" }
  ]
}
```

### EditPlan

A wrapper around `simplicio.mechanical-edit/v1` when the artifact
envelope is requested:

```json
{
  "schema": "simplicio.artifact-response/v1",
  "artifact": "EditPlan",
  "plan": { "schema": "simplicio.mechanical-edit/v1", "...": "..." }
}
```

### TestPlan

```json
{
  "schema": "simplicio.artifact-response/v1",
  "artifact": "TestPlan",
  "tests": [
    {
      "command": "npm run test -- router.spec.ts",
      "expects_passing": ["handles HEAD", "leaves POST untouched"],
      "max_seconds": 30
    }
  ]
}
```

### ReviewDecision

```json
{
  "schema": "simplicio.artifact-response/v1",
  "artifact": "ReviewDecision",
  "accepted": true,
  "matched_intent": true,
  "evidence": {
    "diff_hash": "sha256:...",
    "postconditions_passed": ["regex:HEAD-handling"]
  }
}
```

### FailureAnalysis

```json
{
  "schema": "simplicio.artifact-response/v1",
  "artifact": "FailureAnalysis",
  "failed_step": 2,
  "root_cause": "anchor missing in executor snapshot",
  "next_action_contract": "simplicio.retry/v1"
}
```

### RetryRequest

```json
{
  "schema": "simplicio.artifact-response/v1",
  "artifact": "RetryRequest",
  "retry_of_step": 2,
  "context_pack_requested": {
    "file": "src/router.ts",
    "around_pattern": "method === \"GET\"",
    "lines_before": 8,
    "lines_after": 16
  },
  "expected_resolution": "regexReplace on the broader window"
}
```

## Operational rules

- **Compact context first.** Request a context pack (selected files,
  ranges, anchors, hashes) instead of asking for the whole repository
  or whole files. If the pack is insufficient, request a wider pack
  via the appropriate contract; do not paraphrase.
- **Compact logs.** When evaluating a failed deterministic step, ask
  for or emit `simplicio.log-summary/v1`. Never paste a multi-MB log
  into the conversation.
- **Diff-first review.** Before signing off, look at the diff and the
  executor's structured evidence (hashes, test results, postcondition
  checks). A final "success" is allowed only when the evidence says
  the deterministic step passed, **or** the result carries an explicit
  `policy_waiver` field.
- **Structured retry, not apology.** When a tool returns a failure,
  reply with `simplicio.retry/v1`. Never produce a narrative apology
  or a full rewritten file.
- **Routing.** If the runtime supplies a `simplicio.model-routing/v1`
  hint that the current step is low-risk repetitive work and a local
  model role is available, take it. Reserve remote/paid roles for
  planning, reviewing, or steps that explicitly opt in.

## Precedence rules

Token-efficient contracts compose with the mechanical-edit contract
and respect every higher-precedence rule already documented in the
prompt:

1. `[CLI-6LAYER]` / `[GOAL]` / `[TARGET]` / `[CONTRACT]` / `[OUTPUT]`
   from `simplicio-cli` win on output shape when set.
2. `simplicio.mechanical-edit/v1` wins for edit tasks below that.
3. The token-efficient contracts above govern everything else the
   runtime requests.

## Safety rule

Do not normalize token waste as convenience. If a deterministic
contract exists, use it before asking the LLM to read or produce
large unstructured text. The point of the local-LLM, many-agent
runtime is to spend tokens on inference that matters, not on
reformatting prose.

## Tests

`tests/test_token_efficient_prompts.py` pins the structural
guarantees: both prompts reference all six schemas by name, link the
runtime issue, list the typed artifacts, enumerate the operational
rules, and forbid narrative apology / full-file rewrite / token-waste
normalization.
