ss-tools/.kilo/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 logger.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 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 logger.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.

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 logger.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.

[/DEF:Std:Semantics:Contracts]

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