semantic cleanup
This commit is contained in:
79
.opencode/skills/semantics-contracts/SKILL.md
Normal file
79
.opencode/skills/semantics-contracts/SKILL.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
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 `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 C5-ONLY.**
|
||||
Decision Memory tags belong exclusively to C5 contracts per Std:Semantics:Core complexity scale. C4 adds `@PRE`/`@POST`/`@SIDE_EFFECT` — not decision memory. Adding them below C5 violates INV_7 (verbosity/erosion). 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 `[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.]**
|
||||
Reference in New Issue
Block a user