53 lines
4.8 KiB
Markdown
53 lines
4.8 KiB
Markdown
---
|
|
name: semantics-contracts
|
|
description: 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.]**
|