@sponsio/sdk 0.1.0 → 0.2.0-alpha.8

package/prompts/scan.md

@@ -105,11 +105,9 @@ to enforce and they wedge the agent.  For each tool in
   here — take them seriously.  A policy doc saying "no destructive
   Railway calls without confirmation" should produce a concrete
   arg_blacklist + irreversible_once pair.
-- **`trace_summary.total_events`** > 0: ordering / sequence rules are
-  more reliable now (you can run `sponsio refresh --emit-traces` to
-  mine them properly).  Without traces, prefer single-event patterns
-  (`arg_blacklist`, `rate_limit`, `irreversible_once`) over
-  trace-aware ones.
+- Prefer single-event patterns (`arg_blacklist`, `rate_limit`,
+  `irreversible_once`) unless the code clearly establishes a required
+  ordering; only then reach for sequence-shaped rules.
 - **`existing_yaml`**: don't duplicate rules already there.  Read its
   contracts, only emit gaps.
 

package/skills/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: sponsio
-description: Install, observe, tune, enforce, and periodically refresh Sponsio — a runtime contract layer for LLM agents that blocks unsafe tool calls and scores output quality against declared rules. Use when the user wants to set up / add / install Sponsio, add guardrails or runtime safety to an LLM agent, generate or refine a sponsio.yaml, audit tool configurations for risks (data leaks, unguarded writes, missing confirmations), explain or review existing contracts, check what Sponsio would have blocked (`sponsio report`), refresh the contract library from recent traces (`sponsio refresh`), move from observe to enforce mode, or debug why a contract is (or isn't) firing. Triggers on phrases like "set up sponsio", "add sponsio", "install sponsio", "add guardrails", "monitor my agent", "harden my agent", "audit my agent", "generate contracts", "explain my sponsio.yaml", "sponsio report", "refresh contracts", "update my sponsio.yaml from traces", "flip to enforce", "false positive", "why is this rule firing".
+description: Install, observe, tune, and enforce Sponsio: a runtime contract layer for LLM agents that blocks unsafe tool calls and scores output quality against declared rules. Use when the user wants to set up / add / install Sponsio, add guardrails or runtime safety to an LLM agent, generate or refine a sponsio.yaml, audit tool configurations for risks (data leaks, unguarded writes, missing confirmations), explain or review existing contracts, check what Sponsio would have blocked (`sponsio report`), move from observe to enforce mode, or debug why a contract is (or isn't) firing. Triggers on phrases like "set up sponsio", "add sponsio", "install sponsio", "add guardrails", "monitor my agent", "harden my agent", "audit my agent", "generate contracts", "explain my sponsio.yaml", "sponsio report", "flip to enforce", "false positive", "why is this rule firing".
 ---
 
 # Sponsio — Agent Safety Lifecycle Companion
 
-Sponsio is a Python/TypeScript runtime safety layer for LLM agents: it evaluates deterministic contracts against each tool call and can block (enforce) or just log (observe) violations. (LLM-judged stochastic contracts — tone, prompt-injection, semantic PII, scope respect — are a Sponsio Cloud feature available via `pip install sponsio[cloud]`; the OSS engine is det-only.) This skill covers the full lifecycle — first-time setup, contract authoring/review, observe-mode tuning, and flipping to enforce — by orchestrating Sponsio's CLI and explaining its output in plain language.
+Sponsio is a Python/TypeScript runtime safety layer for LLM agents: it evaluates deterministic contracts against each tool call and can block (enforce) or just log (observe) violations. The engine is deterministic-only. This skill covers the full lifecycle — first-time setup, contract authoring/review, observe-mode tuning, and flipping to enforce — by orchestrating Sponsio's CLI and explaining its output in plain language.
 
 This skill does NOT reimplement Sponsio's logic; it calls the CLI and interprets results.
 
@@ -18,7 +18,6 @@ Dispatch by what the user is trying to do. Pick ONE workflow and follow it; do n
 | Setting up Sponsio for the first time in a project ("add sponsio", "install sponsio", "add guardrails") | **W1 — Initial setup** |
 | Handing you a codebase and asking "what could go wrong?" / wants a fresh contract file from scratch / has a policy doc to encode | **W2 — Audit & refine** |
 | Has Sponsio running in observe mode and wants to review violations, tune thresholds, silence false positives | **W3 — Tune in observe** |
-| Wants to re-mine contracts from accumulated production traces / periodically maintain the library | **W3b — Refresh from traces** |
 | Ready to ship — wants to move from observe to enforce, needs regression confidence | **W4 — Flip to enforce** |
 | Sponsio errored, a rule isn't firing when it should, a rule is firing when it shouldn't | **W5 — Troubleshoot** |
 
@@ -64,7 +63,7 @@ Goal: from "project has no Sponsio" to "agent runs under observe mode with a san
 
 | Pack | Auto-included when… | Notes |
 |---|---|---|
-| `sponsio:core/universal` | Always | Empty stub on OSS — kept so existing `include:` lines don't error. The output-quality contracts (injection / jailbreak / toxic / PII / harm) live in `sponsio:core/llm_safety` and require Sponsio Cloud (`pip install sponsio[cloud]`) |
+| `sponsio:core/universal` | Always | Empty stub, kept so existing `include:` lines don't error. |
 | `sponsio:core/runaway` | Framework runs a multi-step loop (langgraph/crewai/…) | token budget, delegation depth, loop detection; no LLM calls |
 | `sponsio:capability/shell` | A tool name matches `{bash, shell, exec, execute, execute_command, run_command, run_shell, run_bash, terminal, subprocess}` | Auto-fills `tool_rename:` if the user's tool name isn't the canonical `exec` |
 | `sponsio:capability/filesystem` | A tool name matches `{read, read_file, open_file, write, write_file, edit, edit_file, apply_patch, patch_file, ...}` | Auto-fills `tool_rename:` and `workspace:` |
@@ -92,17 +91,16 @@ Sponsio contracts come from four sources, mixable in one yaml:
 | 1 | **Shipped packs** | Pre-built, parameterized rule sets (`sponsio:core/universal`, `sponsio:capability/shell`, …) | Hand-add `include: [sponsio:<spec>]` — or W1's `onboard` does it automatically |
 | 2 | **Extraction** | AST + optional LLM inference from your code / policy docs / execution traces | `sponsio scan <paths> [--llm] [--policy <doc>] [-t <trace-glob>]` |
 | 3 | **User input** | An NL sentence or a structured dict the user writes | Hand-edit `sponsio.yaml`; validate a single NL string with `sponsio validate "<NL>"` |
-| 4 | **Pattern library** | Deterministic parameterized templates (`rate_limit`, `must_precede`, `arg_blacklist`, …) — full list via `sponsio patterns`. Stochastic templates (`injection_free`, `tone`, `llm_judge`, …) live in Sponsio Cloud | `sponsio patterns` to browse; hand-write the YAML entry |
+| 4 | **Pattern library** | Deterministic parameterized templates (`rate_limit`, `must_precede`, `arg_blacklist`, …) — full list via `sponsio patterns` | `sponsio patterns` to browse; hand-write the YAML entry |
 
 Match the user's input to the source(s):
 
 - "Explain / review my `sponsio.yaml`" → source 1 and/or others already applied; jump to "Explain contracts" below.
 - "Scan my agent code" → source 2, code-only.
 - "We have a security policy document" → source 2, add `--policy <doc> --llm`.
-- "We already have session logs / OTLP traces" → source 2, add `-t '<glob>'` (trace mining; no LLM needed).
 - "I know the pattern I want but not the syntax" → source 4, then show them the yaml entry.
 
-If ambiguous: ask ONE question — "(a) scan your code, (b) extract from a policy document, or (c) mine from traces?"
+If ambiguous: ask ONE question — "(a) scan your code, or (b) extract from a policy document?"
 
 ### Run scan (when extraction is needed)
 
@@ -115,12 +113,9 @@ sponsio scan <PATHS> --agent <AGENT> --llm -o ./sponsio.yaml
 
 # + policy doc:
 sponsio scan <PATHS> --policy <POLICY.md> --llm -o ./sponsio.yaml
-
-# + trace mining (works on OTLP/JSON, OTLP JSONL, native, Sponsio session logs):
-sponsio scan <PATHS> -t '~/.sponsio/sessions/<agent>/*.jsonl' -o ./sponsio.yaml
 ```
 
-Scan auto-validates before writing; only contracts that parse cleanly are saved. Source-tagged with `source: scan` / `source: policy` / `source: trace`. The `source: trace` subset is the one `sponsio refresh` maintains over time (W3b).
+Scan auto-validates before writing; only contracts that parse cleanly are saved. Source-tagged with `source: scan` / `source: policy`.
 
 ### Validate existing yaml (explain-only path)
 
@@ -128,7 +123,7 @@ Scan auto-validates before writing; only contracts that parse cleanly are saved.
 sponsio validate --config ./sponsio.yaml --json
 ```
 
-JSON shape per entry: `{nl, ok, type: "det"|"sto"|"unknown", pattern, formula, agent, section}`. `ok: false` means the NL didn't match any pattern — surface those as "ambiguous — needs refinement".
+JSON shape per entry: `{nl, ok, type: "det"|"unknown", pattern, formula, agent, section}`. `ok: false` means the NL didn't match any pattern — surface those as "ambiguous — needs refinement".
 
 ### Explain contracts (use this as the report template)
 
@@ -138,7 +133,7 @@ JSON shape per entry: `{nl, ok, type: "det"|"sto"|"unknown", pattern, formula, a
 **Setup**: <N> contracts total, <sources breakdown>. Mode: <observe|enforce>.
 
 ### Active packs
-- `sponsio:core/universal` (empty stub on OSS — judge-based output safety lives in `sponsio:core/llm_safety` and requires Sponsio Cloud)
+- `sponsio:core/universal` (empty stub, kept so existing `include:` lines don't error)
 - `sponsio:capability/shell` (11 det) — guards on <tool name after rename>
 <...>
 
@@ -211,66 +206,6 @@ With the assumption, the rule stays silent until the integration actually emits
 
 ---
 
-## W3b — Refresh from traces
-
-Goal: treat `sponsio.yaml` as a **living library**, not a one-shot output. As real session logs accumulate, re-mine them to discover new patterns and retire stale ones, without clobbering anything the user wrote or tuned.
-
-### When to run
-
-- Weekly / sprint boundary — recommended cadence for an agent seeing live traffic.
-- After a material behavior change (new tools, new workflow, new integration).
-- Before flipping to enforce (W4) — catches late-arriving trace-sourced rules that weren't present in the original scan.
-
-### Steps
-
-1. Dry-run first. Always.
-
-   ```bash
-   sponsio refresh --since 7d
-   ```
-
-   Prints a structured diff per agent:
-
-   ```
-   Agent: support_bot
-     + new      must_precede(validate_payment, charge_card)
-     ~ drifted  rate_limit(send_email, 5) → args [send_email, 12]
-     - stale    idempotent(list_users)  (not re-observed)
-     = 8 unchanged (source: trace, re-observed)
-     = 12 preserved (user / scan / policy / overrides — not touched)
-   ```
-
-2. Review with the user. For each bucket:
-   - `+ new` — "the agent started doing X that your current yaml doesn't cover." User usually wants this.
-   - `~ drifted` — threshold moved. If new value is bigger, the rule was too tight; if smaller, production tightened up. User decides.
-   - `- stale` — rule hasn't fired in this window. **Not necessarily dead** — could just be rare. Conservative default is `--mode add-only` (never remove), which we recommend for the first few refreshes until the user trusts the window size.
-   - `= preserved` — these include every user rule, `source: scan`, `source: policy`, and anything under `overrides:`. The count being non-zero is the load-bearing invariant: refresh **only** ever changes `source: trace` entries.
-
-3. Apply.
-
-   ```bash
-   sponsio refresh --since 7d --apply                 # default mode: replace-trace
-   sponsio refresh --since 7d --apply --mode add-only # conservative: never remove
-   ```
-
-   Writes `sponsio.yaml` and backs the old file up to `sponsio.yaml.sponsio.bak`. **Comments in the YAML are not preserved** — the backup is how users recover any prose annotations they'd inlined. Warn them of this before running.
-
-### Mode selection
-
-| Situation | Mode |
-|---|---|
-| First time running refresh, or small trace window | `add-only` (never removes) |
-| Healthy trace volume, stable agent behavior | `replace-trace` (default — recent traces are authoritative) |
-| Window just covers a launch / migration / incident (abnormal traffic) | Skip — artifact traces mislead the miner |
-
-### Do NOT
-
-- Do NOT run refresh on traces from an agent still in early iteration. Wait until the workflow is stable; otherwise every sprint invalidates the library.
-- Do NOT use `--apply` without first showing the dry-run diff.
-- Do NOT remove `source: scan` / `source: policy` entries in the yaml by hand just because refresh doesn't touch them — they represent knowledge refresh can't reconstruct (code AST, policy docs). If you think one is wrong, edit `overrides:`, don't delete.
-
----
-
 ## W4 — Flip to enforce
 
 Goal: move from observe to enforce with regression confidence — no more logging, actual blocking. **This is a production change**; don't skip the checks.
@@ -332,7 +267,6 @@ Check in this order:
 1. `sponsio validate --config sponsio.yaml --json` — does the contract parse? `ok: false` means it was silently dropped.
 2. The tool name in the contract matches the actual tool name the agent calls (LangGraph `node_id` vs the `@tool` Python name is a common trap; see `tool_rename:`).
 3. The rule has an `A:` (assumption) that isn't holding. Look at the trace — is the precondition ever true?
-4. The rule is a `sto` pattern (`injection_free`, `tone_*`, `semantic_pii_free`, …). The OSS engine ships no evaluator for those — `pip install sponsio[cloud]` to activate the judge pipeline. Without Cloud, OSS rejects the contract loudly at config load.
 
 ### "A rule is firing that shouldn't."
 
@@ -393,10 +327,6 @@ agents:
 runtime:
   mode: observe                      # "observe" | "enforce"
   dashboard: http://localhost:8000   # URL | true | false | null
-
-judge:                               # Sponsio Cloud only — required when any include uses sto patterns
-  provider: openai                   # openai | anthropic | gemini
-  model: gpt-4o-mini
 ```
 
 Both `A` and `G` accept: scalar NL string, list (AND), or structured dict `{pattern, args, source?}`.
@@ -407,7 +337,7 @@ Placeholders rewritten at include-time: `<workspace>/` (from agent's `workspace:
 
 ## Pattern reference
 
-Full list: `sponsio patterns` (deterministic templates only). LLM-judged stochastic templates are a Sponsio Cloud feature.
+Full list: `sponsio patterns` (deterministic templates only).
 
 ### Core Temporal (14 det)
 | Pattern | Meaning |
@@ -436,8 +366,8 @@ Full list: `sponsio patterns` (deterministic templates only). LLM-judged stochas
 ### Resource & Delegation (3 det)
 `token_budget(max_tokens)` · `arg_value_range(tool, field, min, max)` · `delegation_depth_limit(max_depth)`
 
-### Soft Evaluators
-LLM-judged stochastic atoms (`tone_*`, `relevance`, `llm_judge`, `injection_free`, `semantic_pii_free`, `scope_respect`, …) ship in Sponsio Cloud (`pip install sponsio[cloud]`). The OSS engine refuses to load them at config time with a clear pointer. Det response-quality patterns (`no_pii` regex, `max_length`, `no_keywords`) remain available in OSS.
+### Response-quality patterns (3 det)
+Deterministic response-quality patterns (`no_pii` regex, `max_length`, `no_keywords`) check `llm_said` and need no judge.
 
 ---
 
@@ -492,8 +422,8 @@ If asked for something out of scope (e.g., "also check my DB schema"), say so an
 
 This skill only uses these. Internal refactors are safe as long as these stay stable.
 
-1. **CLI**: `sponsio onboard [--apply]`, `sponsio scan PATHS [--agent N] [--llm] [--policy P] [-t GLOB] [-o FILE] [--append]`, `sponsio refresh [-c FILE] [-a AGENT] [-t GLOB] [--since DUR] [--mode add-only|replace-trace] [--apply]`, `sponsio validate [--config FILE | "NL string"] [--json]`, `sponsio check --trace FILE --config FILE --agent ID`, `sponsio report --agent ID --since DUR`, `sponsio doctor`, `sponsio patterns`, `sponsio packs`, `sponsio skill install [--tool cursor|claude|codex|both|auto]`. Exit 0 on success.
-2. **YAML**: top-level `agents:` as dict; each agent has optional `include:` / `tool_rename:` / `overrides:` / `workspace:` and required `contracts:`; top-level `runtime:` and `judge:`.
+1. **CLI**: `sponsio onboard [--apply]`, `sponsio scan PATHS [--agent N] [--llm] [--policy P] [-o FILE] [--append]`, `sponsio validate [--config FILE | "NL string"] [--json]`, `sponsio check --trace FILE --config FILE --agent ID`, `sponsio report --agent ID --since DUR`, `sponsio doctor`, `sponsio patterns`, `sponsio packs`, `sponsio skill install [--tool cursor|claude|codex|both|auto]`. Exit 0 on success.
+2. **YAML**: top-level `agents:` as dict; each agent has optional `include:` / `tool_rename:` / `overrides:` / `workspace:` and required `contracts:`; top-level `runtime:`.
 3. **Patterns**: names in the table above keep their semantics. Renaming is a breaking change for this skill.
 4. **`validate --json` shape**: per-contract `ok` / `type` / `pattern` / `formula` / `agent`.
 5. **`onboard` JSON report shape**: `out_path` / `tools_count` / `contracts_count` / `mode` / `framework` / `provider` / `doctor_results` / `apply_result.diff`.

package/contracts/core/llm_safety.yaml

@@ -1,140 +0,0 @@
-# =============================================================================
-# sponsio/contracts/core/llm_safety.yaml
-#
-# !! Sponsio Cloud only !! — this pack is composed entirely of LLM-judged
-# stochastic atoms (`injection_free`, `jailbreak_free`, `harmful`,
-# `toxic_free`, `semantic_pii_free`). The OSS engine ships no evaluator
-# for them and will refuse to load this pack with a clear pointer to
-# `pip install sponsio[cloud]`.
-#
-# It still ships in the OSS package so Cloud installs see the same on-disk
-# layout — Cloud's StoEvaluator (auto-discovered via the
-# `sponsio.evaluators` entry-point group) is what actually evaluates
-# these contracts.
-#
-# Once Cloud is installed, opt in from your config:
-#
-#     include:
-#       - sponsio:core/llm_safety
-#
-# Why opt-in even on Cloud: every contract here triggers a judge LLM call
-# on each evaluation. That's the right default for response-quality work
-# but the wrong default for tool-call-only agents (no LLM responses to
-# score → judge calls add latency without value). Splitting out of
-# `core/universal` was the user-driven fix for "why is the SRE tool-call
-# demo running prompt-injection scoring".
-#
-# Source tag convention for this file:
-#   library:tier0.<category>  where category ∈
-#     adversarial | harm | privacy | scope
-# =============================================================================
-
-version: "1"
-
-# NOTE: no `tools:` section here because these contracts are response-scoped.
-# They evaluate against llm_response events, not tool calls.  Agents that
-# include this file will add their own `tools:` inventory separately.
-
-agents:
-  # Template agent id — replaced at include time by the including config.
-  # The include mechanism substitutes this section under the real agent id.
-  "*":
-    contracts:
-
-      # -- Adversarial resistance ----------------------------------------
-      #
-      # `beta` weights the cost of a *missed* violation in the contract
-      # score.  Higher beta = a missed violation hurts the score more,
-      # so the judge has to be near-certain the response is *clean*
-      # before allowing it.  We ship the values below as defaults
-      # calibrated for the threat profile (slip-through cost) of each
-      # category.  Override per-agent in your config if your workload
-      # has different stakes.
-
-      # 0.95 — prompt-injection slip-throughs cause downstream tool
-      # misuse with full agent privileges.  High slip-through cost.
-      - desc: "Every LLM response must be free of prompt-injection compliance"
-        G:
-          pattern: injection_free
-          context_scope: full_trace
-          source: "library:tier0.adversarial"
-        beta: 0.95
-
-      # 0.90 — jailbreak compliance is bad but mostly self-contained
-      # (response-level harm, not tool-level harm).
-      - desc: "LLM must not comply with jailbreak attempts (DAN, roleplay, hypothetical bypass)"
-        G:
-          pattern: jailbreak_free
-          source: "library:tier0.adversarial"
-        beta: 0.9
-
-      # -- Harm avoidance -----------------------------------------------
-
-      # 0.95 — real-world-harm enablement (CSAM, weapons, self-harm
-      # methods) carries the same high slip-through cost as injection.
-      - desc: "Response must not encourage or enable real-world harm"
-        G:
-          pattern: harmful
-          source: "library:tier0.harm"
-        beta: 0.95
-
-      # 0.90 — toxic language is corrosive but not safety-critical;
-      # match the jailbreak weight rather than the harm weight.
-      - desc: "Response free of toxic / harassing language"
-        G:
-          pattern: toxic_free
-          source: "library:tier0.harm"
-        beta: 0.9
-
-      # -- Privacy ------------------------------------------------------
-
-      # 0.95 — PII slip-throughs are regulatory issues (GDPR / CCPA)
-      # not just trust issues.  High slip-through cost.
-      - desc: "Response free of contextual PII (names tied to conditions, inferable identity)"
-        G:
-          pattern: semantic_pii_free
-          source: "library:tier0.privacy"
-        beta: 0.95
-
-      # -- Scope --------------------------------------------------------
-      #
-      # `scope_respect` is deliberately NOT shipped on by default.  It
-      # needs a concrete, agent-specific scope string to be useful —
-      # something like "respond only to loan-origination questions for
-      # the approved product catalogue".  A generic default like "do
-      # not act beyond the task" is irredeemably abstract: the judge
-      # has nothing to anchor on and will either flag everything or
-      # pass everything, depending on model temperament.  Shipping
-      # such a rule as default-on produces noise, not signal.
-      #
-      # Add it to your own agent config once you have a concrete scope
-      # statement, e.g.::
-      #
-      #     agents:
-      #       support_bot:
-      #         contracts:
-      #           - desc: "Stays within customer-support remit"
-      #             E:
-      #               pattern: scope_respect
-      #               args: ["answer questions about order status,
-      #                       refunds, and shipping — no legal advice,
-      #                       no medical advice, no code execution"]
-      #             beta: 0.85
-      #
-      # The β=0.85 default acknowledges that "out of scope" is fuzzier
-      # than "contains PII"; a higher beta flags too aggressively on
-      # responses that drift only slightly.
-
-# -----------------------------------------------------------------------------
-# What this file deliberately does NOT include
-# -----------------------------------------------------------------------------
-#
-# - Token / loop budgets — those live in core/budget.yaml and core/runaway.yaml
-#   respectively, so an agent with a custom budget can include only that.
-#
-# - Tool-specific protections — any constraint that mentions a specific tool
-#   name (exec, web_fetch, ...) belongs in capability/*.yaml.
-#
-# - Hallucination / faithfulness atoms — those require a retrieval source
-#   argument and are not universally applicable.  See docs/sto-atoms.md §1
-#   for when to add them per-agent.

package/prompts/refresh.md

@@ -1,118 +0,0 @@
-# Contract refresh prompt — sponsio refresh from traces
-
-You are tuning an existing `sponsio.yaml` against accumulated
-session traces.  The library already exists; you're proposing
-deltas — added contracts, retired stale ones, tightened thresholds
-— based on what the agent actually did.
-
-This is the **self-evolve loop**: each refresh round looks at recent
-near-misses (would-have-blocked in observe mode) and confirmed
-patterns (rules that fire frequently and correctly), and proposes
-targeted edits.
-
-## Input
-
-A JSON object from `sponsio refresh --emit-traces`:
-
-```json
-{
-  "agent": "...",
-  "since": "7d",
-  "existing_contracts": [
-    {"desc": "...", "pattern": "...", "args": [...], "source": "..."}
-  ],
-  "trace_summary": {
-    "total_events": 1247,
-    "would_have_blocked": [
-      {
-        "tool": "send_email",
-        "rule_desc": "rate_limit 5",
-        "fire_count": 12,
-        "sample_calls": [
-          {"args": {...}, "ts": "...", "agent_outcome": "succeeded"}
-        ]
-      }
-    ],
-    "blocked_actual": [...],
-    "uncovered_patterns": [
-      {
-        "tool": "transfer_funds",
-        "call_count": 3,
-        "sample_args": [{...}],
-        "note": "tool was called 3x; no contract covers it"
-      }
-    ]
-  }
-}
-```
-
-## What you produce
-
-A YAML diff with three sections:
-
-```yaml
-proposed_changes:
-  add:
-    - desc: "..."
-      G: {pattern: ..., args: [...]}
-      source: agent-extracted-from-traces
-  retire:
-    - match: { desc: "<exact desc of existing contract>" }
-      reason: "fired 0 times in 7d window"
-  tighten:
-    - match: { desc: "<exact desc>" }
-      from: {pattern: rate_limit, args: [send_email, 5]}
-      to:   {pattern: rate_limit, args: [send_email, 10]}
-      reason: "false-positive rate 12/30 over last 7d"
-```
-
-## Rules of thumb
-
-### Adding contracts
-
-* `uncovered_patterns` with `call_count` ≥ 3 and clear semantics →
-  add a contract.
-* Don't add for tools that fired 1–2x — too sparse.
-* Match the source-tag convention: new agent-derived contracts get
-  `source: agent-extracted-from-traces`.
-
-### Retiring (only `source: trace` or `source: agent-extracted-*`)
-
-* Existing contract that fired 0 times in the window → candidate for
-  retirement, but ONLY if it's `source: trace` or
-  `source: agent-extracted-*`.
-* **Never propose retiring** `source: scan`, `source: policy`, or
-  user-written (no source / `source: user`) contracts.
-* If retiring, include a one-line `reason`.
-
-### Tightening / loosening
-
-* High false-positive rate (`would_have_blocked` clusters with
-  `agent_outcome: succeeded` — the call was actually fine) →
-  loosen the cap or add `arg_blacklist` carve-outs.
-* High true-positive rate (would-have-blocked + agent_outcome
-  shows the agent was caught doing something problematic) →
-  tighten.
-* Always cite the trace counts in `reason` so the user can verify.
-
-## Pattern vocabulary
-
-Same as plugin scan / onboard — `arg_blacklist`, `rate_limit`,
-`loop_detection`, `irreversible_once`, `must_precede`,
-`arg_value_range`, `arg_length_limit`.
-
-## What you must not do
-
-* **Don't** retire user-written or pack-derived contracts.
-* **Don't** propose changes without trace evidence — every proposal
-  needs a count + window in `reason`.
-* **Don't** merge proposals into the YAML directly — output the
-  diff for the user to review and apply.  Apply via
-  `sponsio refresh --apply` (which respects the same source-tag
-  protections automatically) or by hand-editing for ad-hoc changes.
-
-## Output format
-
-ONLY the `proposed_changes:` YAML block above.  No prose, no
-markdown wrapping.  The host driver will show it to the user
-verbatim.