---
name: semantics-contracts
description: Methodology reference: Design by Contract enforcement, Fractal Decision Memory (ADR), Zero-Erosion rules, Verifiable Edit Loop, and Search Discipline. Load when implementing C4+ contracts or when your agent prompt says "READ → REASON → ACT → REFLECT → UPDATE" and you need the detailed version.
---

#region Std.Semantics.Contracts [C:5] [TYPE Skill] [SEMANTICS methodology,contracts,adr,decision-memory,anti-erosion]
@BRIEF HOW to enforce PRE/POST, write ADRs, prevent structural erosion, execute verifiable edit loops, and maintain anchor safety (anti-corruption) across Python + Svelte.
@RELATION DEPENDS_ON -> [Std.Semantics.Core]
@RELATION DISPATCHES -> [Std.Semantics.Python]
@RELATION DISPATCHES -> [Std.Semantics.Svelte]
@RATIONALE Design by Contract is the ONLY mechanism that prevents Transformer agents from silently corrupting code over long horizons. Without @PRE/@POST enforcement, agents optimize for token-likelihood rather than correctness — adding null checks where @PRE already guarantees non-null, re-implementing @REJECTED paths because KV-cache evicted the rejection, and growing functions past the CC=10 threshold because no structural limit is visible in the attention window. The anti-corruption protocol (§VIII) exists because a single broken #region/#endregion pair cascades silently through the entire semantic graph — rendering all downstream contracts invisible to every agent.
@REJECTED Trusting agents to self-police code quality without contracts was rejected — they optimize for immediate token likelihood, not long-term invariants. Linter-only enforcement was rejected — linters cannot see cross-file dependency graphs or detect rejected-path regression. Implicit contracts (naming conventions alone) were rejected — without explicit @PRE/@POST in the attention-dense header region, agents default to their pre-trained behavior of adding defensive checks everywhere.

**Protocol Reference:** Tier definitions, tag catalog, and anchor syntax are defined in `semantics-core`. This skill assumes you have loaded it. All rules below reference `semantics-core` §III for tier semantics — tiers are descriptive, not tag-gating.

## I. DECISION MEMORY (ADR PROTOCOL)

Decision memory prevents architectural drift. It records the *Decision Space* — why we chose a path, and what we abandoned.

- **`@RATIONALE`** — The reasoning behind the chosen implementation.
- **`@REJECTED`** — The alternative path that was considered but FORBIDDEN, and the exact risk/disqualification.

**Three layers of decision memory:**
1. **Global ADR** — Standalone nodes defining repo-shaping decisions (e.g., "Use lingua, not fasttext"). Cannot be overridden locally.
2. **Task Guardrails** — Preventive `@REJECTED` tags injected by the Orchestrator to keep agents away from known LLM pitfalls.
3. **Reactive Micro-ADR** — If you encounter a runtime failure and invent a valid workaround, document it via `@RATIONALE` + `@REJECTED` BEFORE closing the task. This prevents regression loops.

**Resurrection Ban:** Silently reintroducing a pattern or library marked as `@REJECTED` is a fatal regression. If the rejected path must be revived, emit `<ESCALATION>`.

**`@RATIONALE`/`@REJECTED` are universally allowed at ALL tiers (C1-C5).** They prevent regression loops only when they record a real decision. Absence is valid. Synthetic decision memory (interchangeable "chosen because simpler", copy-paste across siblings, generic "rejected alternative approach") is a defect — delete it. If you cannot name the rejected path, the incident, or the ADR, **do not write the tags**.

**Synthetic-ban (all `@`-tags, not only decision memory):** no local fact → no tag. Do not invent `@PRE`/`@BRIEF`/`@RELATION`/`@UX_*`/`@TEST_*` from the typical-tier matrix. Empty is better than garbage. See `semantics-core` INV_9.

## II. CORE CONTRACT ENFORCEMENT (C4-C5)

- **`@PRE`** — Execution prerequisites. Enforce via explicit `if/raise` guards. NEVER use `assert`.
- **`@POST`** — Strict output guarantees. **Cascading Protection:** You CANNOT alter a `@POST` without verifying upstream `@RELATION CALLS` consumers won't break.
- **`@SIDE_EFFECT`** — Explicit declaration of state mutations, I/O, DB writes, network calls.
- **`@DATA_CONTRACT`** — DTO mappings (e.g., `Input: UserCreateDTO → Output: UserResponseDTO`).

## III. ZERO-EROSION & ANTI-VERBOSITY

Long-horizon AI coding accumulates "slop":
1. **Structural Erosion:** If modifications push a contract's CC above 10, decompose into smaller helpers linked via `@RELATION CALLS`.
2. **Verbosity:** Don't write identity-wrappers, useless intermediate variables, or defensive checks for impossible states if `@PRE` already guarantees validity. Trust the contract.

## IV. VERIFIABLE EDIT LOOP

1. **Define verifier first.** What pytest or browser check proves the `@POST`?
2. **Build bounded working packet** from semantic context, impact analysis, and related tests.
3. **Outline-first mutation.** `read_outline` (Axiom) or grep the `#region` tree, then `edit` one file. Axiom has no `simulate` / `guarded_preview` / `apply` / `destructive_intent`.
4. **Run the smallest falsifiable verifier** against the intended `@POST` (pytest, vitest, or a browser path). If there is no `@POST`, verify the behavior you actually changed.
5. **Re-read the outline** and confirm `#region`/`#endregion` pairs still match.
6. **Re-run the verifier after the edit.** Record the result. Rebuild the Axiom index only when Axiom is connected.

**Shortcut Ban:** A patch that "looks right" without an executable verifier is incomplete.

## V. SEARCH DISCIPLINE

- Default to ONE primary hypothesis + explicit verification.
- Use multiple branches only for ambiguous high-impact changes where the verifier can't discriminate.
- Don't spend additional search budget on low-impact edits once the verifier passes.
- Overthinking is also a bug: avoid Best-of-N patch churn when one verified path suffices.

## VI. RUBRIC REFINEMENT

- Convert repeated failures into explicit rule updates: which invariant was missed, which verifier was weak.
- Treat failed previews, blocked mutations, and failing test outputs as early experience.
- If the same failure repeats, improve the rubric or verifier BEFORE editing again.
- When unblock requires a higher-level change, escalate with the refined rubric.

## VII. LANGUAGE-SPECIFIC VERIFICATION

```bash
# Python
cd backend && source .venv/bin/activate && python -m pytest -v

# Svelte
cd frontend && npm run test

# Linting
python -m ruff check .   # Python
npm run lint              # Frontend
```

## VIII. ANTI-CORRUPTION PROTOCOL (Anchor Safety)

This is the **canonical** anti-corruption protocol. Agent prompts reference this section — they do NOT duplicate these rules.

The `#region`/`#endregion` markers are AST boundaries. If you break a pair, the semantic index breaks and ALL downstream agents hallucinate.

### Before editing any file with anchors
1. **Read the file's region outline:** Axiom `search operation="read_outline"` when available; otherwise grep `#region`/`#endregion` in that file.
2. **Identify nested contracts** — a child `#region` inside a parent `#region` is the fractal tree. Nesting is required, not a violation.
3. **Never:**
   - Insert code between `#region` and the first metadata tag line (breaks INV_4)
   - Remove, move, or duplicate ANY `#endregion` line
   - Add `@COMPLEXITY N` — complexity goes in the anchor: `[C:N]`
   - Add `@C N` — this is a non-standard legacy artifact, never create it
   - Put code outside all regions — every line must be inside a `#region`/`#endregion` pair
   - Leave a **sibling** `#region` unclosed and start another sibling (nesting children is allowed; overlapping siblings are not)
   - Invent `@`-tags to satisfy an audit (INV_9)

### After every edit
4. **Verify:** run `read_outline` on the file — confirm all `#region`/`#endregion` pairs match
5. **If a `#endregion` is missing** → the file is corrupted, roll back immediately via `git checkout` / `git restore`
6. **If you changed anchors and Axiom is connected** → `search operation="rebuild" rebuild_mode="full"`. If Axiom is down, skip rebuild; pair-count via grep is the verifier.

### When adding new contracts
7. Always add BOTH `#region Id [C:N] [TYPE Type]` and its matching `# #endregion Id`
8. Complexity `[C:N]` goes in the ANCHOR line, never as a separate `@` tag
9. If the new contract is nested inside another → DO NOT close the parent until after your child's `#endregion`

### Language-specific anchor formats
- **Python:** `# #region ContractId [C:N] [TYPE TypeName] [SEMANTICS tags]` / `# #endregion ContractId`
- **Svelte HTML:** `<!-- #region ContractId [C:N] [TYPE Component] [SEMANTICS tags] -->` / `<!-- #endregion ContractId -->`
- **Svelte JS/TS (script block):** `// #region ContractId [C:N] ...` / `// #endregion ContractId`
- **Markdown/ADR:** `## @{ ContractId [C:N] [TYPE TypeName]` / `## @} ContractId`

Doxygen HTML in this repo is a module→function navigation graph for agents (`semantics-core` §IX). After changing module-level `@defgroup`/`@ingroup` or contract IDs, regenerate with `make docs-nav`. Do not invent extra groups to make the tree look full (INV_9).

### Batch semantic work
- **ONE file at a time.** Verify each file before moving to the next.
- Never dispatch multiple agents to edit the same file simultaneously.
- For >3 files: process sequentially, with `read_outline` verification between each.
- **Forbidden operations** (immediate `<ESCALATION>`):
  - Duplicating ANY `#region` or `#endregion` line
  - Editing a parent contract's body while ignoring nested children (read the full subtree first; there is no `destructive_intent` flag)
  - Batch-editing multiple files without per-file verification
  - Filling missing tags with boilerplate to close an audit list

### Verification loop (every file, every edit)
```
read_outline(file) → identify boundaries → apply ONE patch → read_outline(file) → rebuild index
```
If ANY step fails — stop and fix before next file. Never chain patches without verification.

#endregion Std.Semantics.Contracts