ss-tools/.opencode/skills/semantics-contracts/SKILL.md

name, description

name	description
semantics-contracts	Core extension protocol for Design by Contract, Fractal Decision Memory (ADR), and Long-Horizon Agentic Engineering across Python and Svelte codebases.

#region Std.Semantics.Contracts [C:5] [TYPE Skill] [SEMANTICS contracts,adr,methodology,anti-erosion] @BRIEF HOW to enforce Design by Contract, Fractal Decision Memory (ADR), and Long-Horizon Agentic Engineering — the methodology for writing correct, traceable, anti-erosion code. @RELATION DEPENDS_ON -> [Std.Semantics.Core] @INVARIANT A contract's @POST guarantees cannot be weakened without verifying upstream @RELATION dependencies. @RATIONALE This skill defines the contract lifecycle methodology: PRE/POST enforcement, RAII guards, ADR propagation, and anti-loop protocols. It answers HOW to write code that doesn't erode over long agentic sessions. @REJECTED Implicit contract enforcement (linters, macros) was rejected because explicit annotations are the only auditable form of machine-readable intent across agent boundaries.

0. AGENTIC ENGINEERING & PRESERVED THINKING (GLM-5 PARADIGM)

You are operating in an "Agentic Engineering" paradigm, far beyond single-turn "vibe coding". In long-horizon tasks (over 50+ commits), LLMs naturally degrade, producing "Slop" (high verbosity, structural erosion) due to Amnesia of Rationale and Context Blindness.

To survive this:

1. Preserved Thinking: We store the architectural thoughts of past agents directly in the AST via @RATIONALE and @REJECTED tags. You MUST read and respect them to avoid cyclic regressions.
2. Interleaved Thinking: You MUST reason before you act. Deductive logic MUST precede any AST mutation.
3. Anti-Erosion: You are strictly forbidden from haphazardly patching new if/else logic into existing functions. If a contract block grows in Cyclomatic Complexity, you MUST decompose it into new contract nodes.

I. CORE SEMANTIC CONTRACTS (C4-C5 REQUIREMENTS)

Before implementing or modifying any logic inside a contract anchor, you MUST define or respect its contract metadata:

• @PURPOSE — One-line essence of the node.
• @PRE — Execution prerequisites. MUST be enforced in code via explicit if/raise early returns or guards. NEVER use assert for business logic.
• @POST — Strict output guarantees. Cascading Failure Protection: You CANNOT alter a @POST guarantee without explicitly verifying that no upstream contract (which has @RELATION CALLS to your node) will break.
• @SIDE_EFFECT — Explicit declaration of state mutations, I/O, DB writes, or network calls.
• @DATA_CONTRACT — DTO mappings (e.g., Input -> UserCreateDTO, Output -> UserResponseDTO).

II. FRACTAL DECISION MEMORY & ADRs (ADMentor PROTOCOL)

Decision memory prevents architectural drift. It records the Decision Space (Why we do it, and What we abandoned).

• @RATIONALE — The strict reasoning behind the chosen implementation path.
• @REJECTED — The alternative path that was considered but FORBIDDEN, and the exact risk, bug, or technical debt that disqualified it.

The 3 Layers of Decision Memory:

1. Global ADR — Standalone nodes defining repo-shaping decisions. You cannot override these locally.
2. Task Guardrails — Preventive @REJECTED tags injected by the Orchestrator to keep you away from known LLM pitfalls.
3. Reactive Micro-ADR (Your Responsibility) — If you encounter a runtime failure and invent a valid workaround, you MUST ascend to the contract header and document it via @RATIONALE [Why] and @REJECTED [The failing path] BEFORE closing the task.

⚠️ @RATIONALE/@REJECTED ARE C5-ONLY. Decision Memory tags belong exclusively to C5 contracts per core complexity scale. C4 adds @PRE/@POST/@SIDE_EFFECT — not decision memory. If a C1-C4 contract genuinely needs decision memory, it should be C5.

Resurrection Ban: Silently reintroducing a coding pattern, library, or logic flow previously marked as @REJECTED is classified as a fatal regression. If the rejected path is now required, emit <ESCALATION> to the Architect.

III. ZERO-EROSION & ANTI-VERBOSITY RULES (SlopCodeBench PROTOCOL)

Long-horizon AI coding naturally accumulates "slop". You are audited against two strict metrics:

1. Structural Erosion: Do not concentrate decision-point mass into monolithic functions. If your modifications push a contract node's Cyclomatic Complexity (CC) above 10, or its length beyond 150 lines, you MUST decompose the logic into smaller helpers and link them via @RELATION CALLS.
2. Verbosity: Do not write identity-wrappers, useless intermediate variables, or defensive checks for impossible states if the @PRE contract already guarantees data validity. Trust the contract.

IV. EXECUTION LOOP (INTERLEAVED PROTOCOL)

When assigned a Worker Packet for a specific contract node, execute strictly in this order:

1. READ (Preserved Thinking): Analyze the injected @RATIONALE, @REJECTED, and @PRE/@POST tags.
2. REASON (Interleaved Thinking): Emit your deductive logic. How will you satisfy the @POST without violating @REJECTED?
3. ACT (AST Mutation): Write the code strictly within the contract's AST boundaries.
4. REFLECT: Verify that the resulting code physically guarantees the @POST condition.
5. UPDATE MEMORY: If you discovered a new dead-end during implementation, inject a Reactive Micro-ADR into the header.

V. VERIFIABLE EDIT LOOP (EXECUTABLE ENVIRONMENT PROTOCOL)

Every non-trivial contract change MUST be framed as a verifiable edit loop:

1. Define the target behavior and the concrete verifier before mutating.
2. Build a bounded working packet from semantic context, impact analysis, and related tests.
3. Prefer preview-first mutation.
4. Run the smallest executable verifier that can falsify the intended @POST guarantee.
5. Apply only after the preview and verifier agree.
6. Re-run focused verification after apply and record the result in the evidence packet.

Shortcut Ban: A patch that "looks right" but is not tied to an executable verifier is incomplete.

VI. SEARCH DISCIPLINE (DELIBERATE BUT BOUNDED)

• Default to one primary implementation hypothesis plus explicit verification.
• Use multiple branches only for ambiguous high-impact changes where the verifier cannot discriminate the first path.
• Do not spend additional search budget on low-impact edits once the verifier already passes and semantic invariants hold.
• Overthinking is also a bug: avoid Best-of-N style patch churn when one verified path is already sufficient.

VII. RUBRIC REFINEMENT AND EARLY EXPERIENCE

Long-horizon agents improve by learning from their own failed attempts.

• Convert repeated failures into explicit rubric updates: which invariant was missed, which verifier was weak, which rejected path was accidentally revisited.
• Treat failed previews, blocked mutations, and failing test outputs as early experience for the next bounded attempt.
• If the same failure repeats, improve the rubric or the verifier before editing again.
• When the unblock requires a higher-level change, escalate with the refined rubric instead of continuing local patch churn.

VIII. LANGUAGE-SPECIFIC VERIFICATION

• Python: cd backend && source .venv/bin/activate && python -m pytest -v
• Svelte/Frontend: cd frontend && npm run test
• Full-stack: Run both sequentially; backend tests first, then frontend.
• Linting: python -m ruff check (Python), npm run lint (Frontend, if configured).

#endregion Std.Semantics.Contracts