agents
This commit is contained in:
@@ -1,58 +1,67 @@
|
||||
---
|
||||
name: semantics-contracts
|
||||
description: Core extension protocol for Design by Contract, Fractal Decision Memory (ADR), and Long-Horizon Agentic Engineering.
|
||||
description: Core extension protocol for Design by Contract, Fractal Decision Memory (ADR), and Long-Horizon Agentic Engineering across Python and Svelte codebases.
|
||||
---
|
||||
# [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.
|
||||
|
||||
#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 (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.
|
||||
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 `[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`).
|
||||
|
||||
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.
|
||||
|
||||
- `@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.
|
||||
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 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.
|
||||
**⚠️ `@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 `[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`.
|
||||
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 `[DEF]` node, execute strictly in this order:
|
||||
|
||||
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 `[DEF]...[/DEF]` AST boundaries.
|
||||
4. **REFLECT:** Emit `reflect()` (or equivalent `<reflection>`) verifying that the resulting code physically guarantees the `@POST` condition.
|
||||
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.
|
||||
@@ -64,17 +73,25 @@ Every non-trivial contract change MUST be framed as a verifiable edit loop:
|
||||
**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.]**
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user