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.

[DEF:Std:Semantics:Contracts]

@COMPLEXITY 5

@PURPOSE Core extension protocol for Design by Contract, Fractal Decision Memory (ADR), and Long-Horizon Agentic Engineering.

@RELATION DEPENDS_ON -> [Std:Semantics:Core]

@INVARIANT A contract's @POST guarantees cannot be weakened without verifying upstream @RELATION dependencies.

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 (via <thinking> or reason()) MUST precede any AST mutation.
3. Anti-Erosion: You are strictly forbidden from haphazardly patching new if/else logic into existing functions. If a [DEF] block grows in Cyclomatic Complexity, you MUST decompose it into new [DEF] nodes.

I. CORE SEMANTIC CONTRACTS (C4-C5 REQUIREMENTS)

Before implementing or modifying any logic inside a [DEF] 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 ValueError(...) 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 [DEF] (which has a @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 ([DEF:id:ADR]): Standalone nodes defining repo-shaping decisions (e.g., [DEF:AuthPattern:ADR]). You cannot override these locally.
2. Task Guardrails: Preventative @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, use explore(), and invent a valid workaround, you MUST ascend to the [DEF] header and document it via @RATIONALE [Why] and @REJECTED [The failing path] BEFORE closing the task.

@RATIONALE / @REJECTED are ORTHOGONAL tags. Per axiom_config.yaml, these are protected: true and orthogonal: true — they may appear at ANY complexity level (C1-C5) when a node records a deliberate architectural choice. They are REQUIRED for ADR type contracts. Removal of an existing @RATIONALE/@REJECTED requires <ESCALATION> to the Architect.

If a C1-C4 contract records a workaround after a runtime failure, add @RATIONALE/@REJECTED at that node's header BEFORE closing the task. This is a Reactive Micro-ADR — it does NOT require bumping the complexity to 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 [DEF] node's Cyclomatic Complexity (CC) above 10, or its length beyond 150 lines, you MUST decompose the logic into smaller [DEF] 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 [DEF] 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 [DEF]...[/DEF] AST boundaries.
4. REFLECT: Emit reflect() (or equivalent <reflection>) verifying 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.

[/DEF:Std:Semantics:Contracts]

[SYSTEM: END OF CONTRACTS DIRECTIVE. ENFORCE STRICT AST COMPLIANCE.]